nexus/wiki/concepts/Workflow-Tree-Spec.md

title, type, tags, last_updated

title	type	tags	last_updated
Workflow Tree Spec	concept	workflow specification documentation quality-assurance	2026-04-25

Definition

工作流树规范格式——为每个工作流生成的结构化规范文档，工程师可直接依据实现，QA 可直接导出测试用例，运维可理解系统行为，产品负责人可验证需求是否满足。

Required Sections（必须章节）

1. Overview：2-3 句话描述工作流目标、触发者和产出
2. Actors：参与此工作流的所有角色（人/系统/Agent）
3. Prerequisites：工作流启动前必须满足的条件
4. Trigger：触发来源（用户操作/API调用/定时任务/事件）
5. Workflow Tree：每步的 Actor/Action/Timeout/Input/Output on SUCCESS/Output on FAILURE + Observable States
6. ABORT_CLEANUP：失败清理流程（含触发条件、清理动作顺序、客户视图、运维视图）
7. State Transitions：状态机转换图
8. Handoff Contracts：每个系统边界的交接合同
9. Cleanup Inventory：工作流创建的所有资源及其销毁方法
10. Reality Checker Findings：规范与代码对照验证结果
11. Test Cases：每个分支对应一个测试用例
12. Assumptions：所有未经代码验证的假设
13. Open Questions：待确认事项

Branch Coverage（分支覆盖要求）

每个工作流规范必须覆盖 7 类分支：

1. 快乐路径（所有步骤成功，所有输入有效）
2. 输入验证失败（具体错误信息 + 客户看到什么）
3. 超时失败（每个步骤的超时值 + 超时后行为）
4. 瞬态失败（网络抖动/限流，可重试并退避）
5. 永久失败（无效输入/配额超限，立即失败并清理）
6. 部分失败（步骤7/12失败，已创建资源必须销毁）
7. 并发冲突（同一资源同时被创建/修改）

Status Lifecycle

Draft → Review → Approved
           ↑
    Reality Checker 验证（必须，不可跳过）

Source

• specialized-workflow-architect（Workflow Architect Agent）