Agent Skills
› OpenAEV-Platform/openaev
› review-chaining-engine
review-chaining-engine
GitHub指导审查或修改 OpenAEV Chaining Engine,涵盖步骤生命周期、条件评估、队列处理、状态管理及超时逻辑。适用于涉及链式引擎代码的 PR 审查、新功能添加及故障排查。
触发场景
审查涉及 /chaining/ 路径的代码 PR
实现新的 ActionStep 或 ConditionType
调试步骤执行流或队列处理问题
安装
npx skills add OpenAEV-Platform/openaev --skill review-chaining-engine -g -y
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
ConditionTypeenum) - 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
@WorkflowUpdateEventannotation - 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.READYorStepStatus.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, neverThread.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_ONconditions useConditionFactory.dependOn() -
MAPPERconditions properly resolve from LOCAL or GLOBAL pool - Conditions linked to steps via
ConditionStepentity
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, orexpectationIdsis 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
@AccessControlwith correctActionandResourceType - 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
-
ChainingExceptionused for chaining-specific errors - No swallowed exceptions in queue consumers (at minimum logged)
Step-by-step: Add a new Step action type
- Create the class — implement
ActionStepinterface inio.openaev.api.chaining. - Implement all methods —
create(),ready(),run(),update(),end(). - Register in factory — add to
StepService.factoryAction()switch/map. - Add enum value — extend
StepActionClasswith the new action class name. - Add tests — unit test each lifecycle method; integration test the full flow.
Step-by-step: Add a new Condition type
- Add enum value — extend
ConditionTypewith the new type. - Update evaluation — add logic in
ConditionUtilsfor the new type. - Update factory (if special) — add a factory method in
ConditionFactory. - Update mapper — extend
ConditionMapperif the new type has special serialization. - Write tests — test condition evaluation in isolation and in a workflow context.
Step-by-step: Add a new API endpoint
- Add the method in the relevant
*Api.javafile. - Add
@AccessControlwith appropriateActionandResourceType. - Add
@Transactional(rollbackFor = Exception.class)for writes. - Create input/output DTOs in
io.openaev.api.chaining.dto. - Add static mapper methods (not MapStruct annotations).
- Implement service logic in
io.openaev.service.chaining. - 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
- ✅
@WorkflowUpdateEventon 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
- Chaining PRs
- Instructions: chaining-engine.instructions.md
版本历史
- 3.261016.0 当前 2026-10-19 22:29


