从脚本到工程：工作流设计的演进
一个工作流在初期往往只是一个单文件：用Markdown把全部逻辑描述清楚，所有配置直接硬编码。在小规模场景下这种方式足够应对，但随着工作流规模增长，三个问题会逐渐暴露：
- 想改个执行参数（比如超时时长），必须找到并修改多处
- 不同子Agent的任务提示词散落在工作流定义里，无法独立测试
- 安全策略和业务逻辑混在一起，合规审查时令人头疼
如何解决？采用四层架构。
四层架构：分离关注点
Policy Layer policy.md 执行原则，全局约束 → 谁能做什么，高风险操作的授权规则
Workflow Layer workflow.md Phase / Step 结构，路由逻辑 → 工作流的骨架，不包含具体任务内容
TaskSpec Layer templates/ 子 Agent 的 task prompt 模板 → 每个子任务的详细指令和输出契约
Tool/Skill Layer skills/ 原子能力 → 可跨工作流复用的 Skill 定义
每一层各司其职，不越界干涉。
# ✅ 正确：修改分析的超时时间 → 改 workflow.md 的配置
phase_3_analyze:
timeout: 30m ← 在 Workflow Layer 修改
# ✅ 正确：修改分析的输出格式 → 改 templates/analyze.md
## Output Contract
{"confidence": float, "root_cause": str, ...} ← 在 TaskSpec Layer 修改
# ❌ 错误：在 task prompt 里写权限规则（权限属于 Policy Layer）
# ❌ 错误：在 workflow.md 里写具体的分析步骤（步骤属于 TaskSpec Layer）
工作流修改的安全性完全依赖分层设计——修改 templates/ 只影响对应子Agent的输出，调整 policy.md 不会意外破坏路由逻辑。
Context 传递模式：精准控制信息流
子Agent需要知道哪些信息，是工作流设计中最容易出错的地方。
最常见的错误，就是把主Agent的全部历史一股脑传给每个子Agent。结果导致Context爆炸：子Agent处理变慢，输出质量下降，Token成本翻倍。
必须根据子Agent的实际需求来选择传递模式，共有三种：
accumulate（汇总传递）
定义：传递工作流到目前为止的所有相关输出。
适用场景：子Agent需要对整个工作流的多个阶段结论进行汇总或生成报告。
# Phase 7：写结案通知，需要整个工作流的结论
phase_7_notify:
context_mode: accumulate
context_inputs:
- phases.phase3.root_cause_summary
- phases.phase4.fix_summary
- phases.phase5.commit_result
- phases.phase6.review_status
Phase 7的子Agent需要根因、修复摘要、提交结果和Review状态，缺一个都无法写出完整的通知。
last_only（仅上一步）
定义：只传递上一个Phase/Step的输出。
适用场景：子Agent的任务只依赖直接前驱的结果，历史信息对它毫无用处。
# Phase 2：解压日志文件，只需要 Phase 1 获取的附件路径
phase_2_extract_logs:
context_mode: last_only
context_inputs:
- phases.phase1.attachment_path # 只需要这一个字段
解压日志不需要知道Jira工单的全部信息，只需要文件存放位置。把Phase 1的所有输出都传进来纯粹是浪费，last_only模式强制只取所需。
explicit（显式声明）
定义：明确列出子Agent需要的每一个字段，来源可以跨多个Phase。
适用场景：子Agent需要来自多个历史Phase的特定字段，但不需要任何Phase的全部输出。
# Phase 3：根因分析，需要 bug_info（Phase 1）+ log_dir（Phase 2）
phase_3_analyze:
context_mode: explicit
context_inputs:
- source: phases.phase1
fields: [bug_info.summary, bug_info.stack_trace, bug_info.jira_key]
- source: phases.phase2
fields: [log_dir, extracted_files]
Phase 3需要bug描述（来自Phase 1）和日志目录（来自Phase 2），但不需要Phase 1的附件路径，也不需要Phase 2的解压日志。explicit模式精确控制哪些字段流入子Agent。
三种模式的选择规则
子 Agent 需要汇总多个 Phase 的结论 → accumulate
子 Agent 只依赖直接前驱 → last_only
子 Agent 需要来自多处的特定字段 → explicit（推荐默认）
explicit是最安全的默认选择——即使不确定子Agent需要什么，从声明具体字段开始，也比传入过多信息更容易排查问题。
确认门设计：让人类有效介入
确认门（Human Checkpoint）是工作流中让人类介入的节点。设计不完整的确认门，是生产故障的常见来源。
三种门类型
interrupt（阻塞型）工作流完全暂停，等待人工响应后才继续
适合：高风险操作（合并代码、生产部署）
notification（通知型）工作流继续执行，同时通知人工
适合：低风险操作，人工只需知晓，不需要确认
approval（审批型）异步等待审批，在指定时间窗口内响应
适合：正式审批流程，有 SLA 要求
5 个必填字段
# 完整的确认门定义
- gate_id: gate_B
type: interrupt
trigger_condition: "fix_result.all_passed == false after 3 retries"
message: |
修复尝试 3 次均未通过测试。
根因：{{ phases.phase3.root_cause_summary }}
最近一次错误：{{ phases.phase4.last_error }}
请选择后续操作：
options:
- label: 人工介入修复
value: manual_fix
- label: 重新分析根因
value: re_analyze
- label: 标记为不可自动修复
value: mark_manual
timeout: 24h
timeout_action: pause # ← 最容易漏掉的字段
timeout_action是最常见的设计缺漏，可选值：
pause → 超时后暂停工作流，等待人工续接（最常用）
continue → 超时后按默认选项继续（适合低风险的通知型门）
abort → 超时后中止整个工作流（适合有严格时间窗口的操作）
没有timeout_action，一个长时间无人响应的确认门会让工作流永远悬着——没有告警，没有记录，没有恢复路径。
确认门的信息设计
确认门的message是给人看的，直接影响确认速度。设计原则：
✅ 好的确认门消息：
"测试通过率：67%（8/12 通过）
失败的测试：test_null_input, test_overflow
当前修复方案：修改了 parseInput() 的边界检查
建议选择：重新分析，因为失败模式与预期根因不符"
❌ 差的确认门消息：
"修复失败，请选择操作"
好的消息让确认人在30秒内做出决策，差的消息迫使他们去查日志。
串行重试 vs 并行候选：失败应对策略
工作流遇到失败时，有两种应对策略。选错，会显著降低效率或质量。
串行重试
第 1 次执行 → 失败
↓ (携带失败原因和 feedback)
第 2 次执行 → 失败
↓ (携带失败原因和 feedback)
第 3 次执行 → 通过
适合场景：错误原因明确，后一次能从前一次学习，执行角度有差异空间。
示例：根因分析（Phase 3）
第 1 次：从代码层面分析
第 2 次：feedback "代码分析置信度低，尝试从日志异常模式分析"
第 3 次：feedback "改从时序角度分析调用链"
每次重试都在前一次失败基础上换角度，学习是有效的。
并行候选
→ 候选 A → 测试 → 通过 ← 选这个
分析结果 → 候选 B → 测试 → 失败
→ 候选 C → 测试 → 失败
适合场景：解空间多样，难以预判哪种方案可行，多个方案并发探索后选优。
示例：代码修复（Phase 4）
候选 A：修改边界检查逻辑
候选 B：修改调用方的参数校验
候选 C：修改 parseInput() 的默认值处理
三种修法都有可能正确，无法预判，并发跑后选通过测试且覆盖率最高的。
选择原则
后一次可以从前一次失败中学习 → 串行重试
多种方案同等可能 → 并行候选
时间紧张，不能等串行 → 并行候选
需要比较多个方案质量 → 并行候选（即使串行也能收敛）
在工作流定义里明确标注策略，方便调试：
phase_3_analyze:
retry_strategy: serial # 换角度分析，每次从失败中学
max_retries: 3
feedback_mode: include_prev_error
phase_4_fix:
retry_strategy: parallel # 修法不唯一，并发选优
parallel_candidates: 3
selection_criteria: passed_tests AND max_coverage
设计 Checklist：确保可维护性
四层分离
- Policy（权限/安全）和 Workflow（路由/结构）在不同文件
- 子 Agent 的 task prompt 在独立的 templates/ 文件里
- config.yaml 集中管理超时、重试次数等可变参数
Context 传递
- 每个子 Agent 调用都声明了 context_mode
- 使用 explicit 时列出了具体字段，没有传整个 Phase 的输出
- 没有把主 Agent 的全部历史传给每个子 Agent
确认门
- 每个门都有 timeout 和 timeout_action
- message 包含足够信息让确认人 30 秒内决策
- options 的 value 是确定性枚举，不是自由文本
重试策略
- 每个有重试逻辑的节点都标注了 serial 或 parallel
- 串行重试有 feedback_mode（要把失败原因传回去）
- 并行候选有明确的 selection_criteria
总结：核心设计要点
- 四层架构的价值在于隔离：Policy层改动不影响路由，templates/改动可以独立测试，这是可维护性的基础。
- Context传递最安全的默认选择是explicit：显式声明每个字段，比accumulate省token，比last_only灵活，出问题时也更容易定位。
- 串行重试 vs 并行候选是方向性决策：根因分析用串行（学习有效），代码修复用并行（解空间多样）——搞反了效率和质量都会变差。
