Workflow设计范式：四层架构、三种Context传递与确认门

从脚本到工程：工作流设计的演进

一个工作流在初期往往只是一个单文件：用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

总结：核心设计要点

1. 四层架构的价值在于隔离：Policy层改动不影响路由，templates/改动可以独立测试，这是可维护性的基础。
2. Context传递最安全的默认选择是explicit：显式声明每个字段，比accumulate省token，比last_only灵活，出问题时也更容易定位。
3. 串行重试 vs 并行候选是方向性决策：根因分析用串行（学习有效），代码修复用并行（解空间多样）——搞反了效率和质量都会变差。