Agent Skills › OpenAEV-Platform/openaev › review-chaining-engine

review-chaining-engine

GitHub

指导审查或修改 OpenAEV Chaining Engine,涵盖步骤生命周期、条件评估、队列处理、状态管理及超时逻辑。适用于涉及链式引擎代码的 PR 审查、新功能添加及故障排查。

.claude/skills/review-chaining-engine/SKILL.md OpenAEV-Platform/openaev

触发场景

审查涉及 /chaining/ 路径的代码 PR 实现新的 ActionStep 或 ConditionType 调试步骤执行流或队列处理问题

安装

npx skills add OpenAEV-Platform/openaev --skill review-chaining-engine -g -y
更多选项

非标准路径

npx skills add https://github.com/OpenAEV-Platform/openaev/tree/main/.claude/skills/review-chaining-engine -g -y

不安装直接使用

npx skills use OpenAEV-Platform/openaev@review-chaining-engine

指定 Agent (Claude Code)

npx skills add OpenAEV-Platform/openaev --skill review-chaining-engine -a claude-code -g -y

安装 repo 全部 skill

npx skills add OpenAEV-Platform/openaev --all -g -y

预览 repo 内 skill

npx skills add OpenAEV-Platform/openaev --list

SKILL.md

Frontmatter
{
    "name": "review-chaining-engine",
    "description": "Reviews or modifies the OpenAEV Chaining Engine: step lifecycle, condition evaluation, queue processing, WorkflowState, timeout handling, scope resolution and the inject lifecycle AOP bridge. Use when touching **\/chaining\/**, QueueChainingJob or WorkflowTimeoutJob."
}

Skill: Review Chaining Engine

Purpose

This skill guides Copilot when reviewing or modifying the Chaining Engine of OpenAEV. It covers the full feature: step lifecycle, condition evaluation, queue processing, state management, timeout handling, scope resolution, and the AOP bridge to inject lifecycle.


When to use this skill

  • Reviewing a PR that touches chaining code (API, service, model, scheduler)
  • Adding a new Step action type (implementing ActionStep)
  • Adding a new Condition type (extending ConditionType enum)
  • Modifying the Global/Local State synchronization logic
  • Adding or modifying queue processing (ready queue, update queue, delay queue)
  • Modifying timeout or scope logic
  • Adding new endpoints that need @WorkflowUpdateEvent annotation
  • Debugging step execution flow or queue processing

Review Checklist

1. Step Lifecycle Integrity

  • Status transitions follow: TEMPLATE → READY → RUN → END
  • TEMPLATE steps are never executed directly — always cloned to READY
  • Before execution, workflowService.isWorkflowEnded() is checked
  • Active steps are identified by StepStatus.READY or StepStatus.RUN

2. Workflow Lifecycle

  • Workflow status transitions: TEMPLATE → RUN → END/STOP
  • Timeout handling doesn't leave orphaned READY/RUN steps
  • Duplication correctly copies templates and conditions

3. Queue & Scheduling

  • All queue publishing goes through QueueChainingService
  • No direct RabbitMQ calls from services
  • Time delays use StepDelayQueueService, never Thread.sleep()
  • Quartz jobs handle concurrent execution correctly (@DisallowConcurrentExecution)

4. State Management

  • Global state updated via WorkflowStateService.syncState() BEFORE propagation
  • Local state propagation uses propagateToLocalStates()
  • State is written and read only through WorkflowStateStore (append-only deltas, views restricted to the keys actually read — never a full-state load or rewrite)
  • Execution hashes are committed with commitHashes() and a READY step is created only for the hashes it returned (anti-replay, ADR-011)

5. Conditions

  • Conditions evaluated BEFORE step execution
  • Tree structure maintained: root (AND/OR) + leaf conditions
  • DEPEND_ON conditions use ConditionFactory.dependOn()
  • MAPPER conditions properly resolve from LOCAL or GLOBAL pool
  • Conditions linked to steps via ConditionStep entity

6. External Update Bridge (AOP)

  • Methods that mutate inject status are annotated with @WorkflowUpdateEvent
  • SpEL expressions correctly extract inject/expectation IDs
  • Exactly one of injectId, injectIds, or expectationIds is specified per annotation

7. Scope

  • Allowlist rules are applied first, then denylist exclusions
  • Both individual assets and asset groups are handled
  • IP address matching uses IpAddressUtils

8. API Layer

  • All endpoints have @AccessControl with correct Action and ResourceType
  • DTOs are returned (never entities)
  • Static mapper methods used (not MapStruct annotation processing)
  • @Transactional(rollbackFor = Exception.class) on write operations
  • Proper HTTP status codes (201 for creation, 204 for deletion)

9. Error Handling

  • ChainingException used for chaining-specific errors
  • No swallowed exceptions in queue consumers (at minimum logged)

Step-by-step: Add a new Step action type

  1. Create the class — implement ActionStep interface in io.openaev.api.chaining.
  2. Implement all methods — create(), ready(), run(), update(), end().
  3. Register in factory — add to StepService.factoryAction() switch/map.
  4. Add enum value — extend StepActionClass with the new action class name.
  5. Add tests — unit test each lifecycle method; integration test the full flow.

Step-by-step: Add a new Condition type

  1. Add enum value — extend ConditionType with the new type.
  2. Update evaluation — add logic in ConditionUtils for the new type.
  3. Update factory (if special) — add a factory method in ConditionFactory.
  4. Update mapper — extend ConditionMapper if the new type has special serialization.
  5. Write tests — test condition evaluation in isolation and in a workflow context.

Step-by-step: Add a new API endpoint

  1. Add the method in the relevant *Api.java file.
  2. Add @AccessControl with appropriate Action and ResourceType.
  3. Add @Transactional(rollbackFor = Exception.class) for writes.
  4. Create input/output DTOs in io.openaev.api.chaining.dto.
  5. Add static mapper methods (not MapStruct annotations).
  6. Implement service logic in io.openaev.service.chaining.
  7. Write integration test following existing patterns (StepApiTest, ConditionApiTest, WorkflowApiTest).

Key Invariants (Never Break)

  • ✅ Endpoint access is enforced via @AccessControl (including EE validation where required)
  • ✅ Conditions evaluated before step execution
  • ✅ Global state updated before local state propagation
  • ✅ Step status follows TEMPLATE → READY → RUN → END
  • ✅ Workflow ended check before any step execution
  • ✅ Queue interactions go only through QueueChainingService
  • ✅ Time delays use StepDelayQueueService
  • ✅ Static mapper methods for entity ↔ DTO conversions
  • ✅ @WorkflowUpdateEvent on inject-mutating methods
  • ✅ Timeout force-completes all active steps and clears delay queue

Test Fixtures & Composers

Class Purpose
WorkflowFixture Creates test workflow entities
WorkflowComposer Builds complex workflow test scenarios
ConditionComposer Builds condition trees for tests
StepComposer Builds Step tests

Key Test Classes

Test Scope
ChainingIntegrationTest End-to-end chaining flow
StepServiceTest / StepServiceIntegrationTest Step lifecycle
StepServiceScenarioIntegrationTest Scenario-based chaining
ConditionServiceTest Condition CRUD and evaluation
WorkflowServiceTest Workflow CRUD and configuration
WorkflowStateServiceTest State sync and propagation
StepEventServiceTest Queue event handling
QueueChainingServiceTest Queue management
ScopeServiceTest Scope resolution
WorkflowEndServiceTest / WorkflowTimeoutIntegrationTest Timeout handling
StepDelayQueueServiceTest / StepDelayQueueIntegrationTest Delay queue
StepApiTest / ConditionApiTest / WorkflowApiTest API layer

Useful Links

版本历史

  • 3.261016.0 当前 2026-10-19 22:29

同 Skill 集合

.claude/skills/add-contract-output-type/SKILL.md
.claude/skills/add-migration/SKILL.md
.claude/skills/add-test/SKILL.md
.claude/skills/create-feature-module/SKILL.md
.claude/skills/reduce-tx-baseline/SKILL.md
.claude/skills/review-code/SKILL.md
.claude/skills/review-docs/SKILL.md
.claude/skills/review-frontend/SKILL.md
.claude/skills/review-migration/SKILL.md
.claude/skills/review-multi-tenancy/SKILL.md
.claude/skills/review-performance/SKILL.md
.claude/skills/review-security/SKILL.md
.github/skills/add-contract-output-type/SKILL.md
.github/skills/add-migration/SKILL.md
.github/skills/add-test/SKILL.md
.github/skills/create-feature-module/SKILL.md
.github/skills/reduce-tx-baseline/SKILL.md
.github/skills/review-code/SKILL.md
.github/skills/review-docs/SKILL.md
.github/skills/review-frontend/SKILL.md
.github/skills/review-migration/SKILL.md
.github/skills/review-multi-tenancy/SKILL.md
.github/skills/review-performance/SKILL.md
.github/skills/review-security/SKILL.md
.claude/skills/activate-tenant-table/SKILL.md
.github/skills/activate-tenant-table/SKILL.md

元信息

文件数
0
版本
3.261016.0
Hash
60d4f345
收录时间
2026-10-19 22:29

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-21 16:18
浙ICP备14020137号-1