Workflow 系列（02）：设计范式——四层架构、三种 Context 传递模式与确认门设计

从脚本到工程

一个工作流的早期形态往往是单一文件：一个 Markdown 描述全部逻辑，所有配置硬编码其中。这在小规模时能用，随着工作流增长会出现三个问题：

修改执行参数（如超时时长）需要找到并修改多处
不同子 Agent 的 task prompt 散落在工作流定义里，难以独立测试
安全策略和业务逻辑混在一起，合规审查困难

四层架构解决这三个问题。

四层架构

markdown 复制代码

Policy Layer     policy.md         执行原则，全局约束
                                    → 谁能做什么，高风险操作的授权规则

Workflow Layer   workflow.md        Phase / Step 结构，路由逻辑
                                    → 工作流的骨架，不包含具体任务内容

TaskSpec Layer   templates/         子 Agent 的 task prompt 模板
                                    → 每个子任务的详细指令和输出契约

Tool/Skill Layer skills/            原子能力
                                    → 可跨工作流复用的 Skill 定义

每层只改自己的事，不跨层。

markdown 复制代码

# ✅ 正确：修改分析的超时时间 → 改 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 需要对整个工作流的多个阶段结论做汇总或报告。

yaml 复制代码

# 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 的任务只依赖直接前驱的结果，历史信息对它无用。

yaml 复制代码

# 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 的全部输出。

yaml 复制代码

# 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。

三种模式的选择规则

arduino 复制代码

子 Agent 需要汇总多个 Phase 的结论   → accumulate
子 Agent 只依赖直接前驱               → last_only
子 Agent 需要来自多处的特定字段       → explicit（推荐默认）

explicit 是最安全的默认选择：即使不确定子 Agent 需要什么，从声明具体字段开始，比传入过多信息更容易排查问题。

确认门设计

确认门（Human Checkpoint）是工作流中让人类介入的节点。设计不完整的确认门是常见的生产故障来源。

三种门类型

复制代码

interrupt（阻塞型）
  工作流完全暂停，等待人工响应后才继续
  适合：高风险操作（合并代码、生产部署）

notification（通知型）
  工作流继续执行，同时通知人工
  适合：低风险操作，人工只需知晓，不需要确认

approval（审批型）
  异步等待审批，在指定时间窗口内响应
  适合：正式审批流程，有 SLA 要求

5 个必填字段

yaml 复制代码

# 完整的确认门定义
- 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 是最常见的设计缺漏，可选值：

c 复制代码

pause    → 超时后暂停工作流，等待人工续接（最常用）
continue → 超时后按默认选项继续（适合低风险的通知型门）
abort    → 超时后中止整个工作流（适合有严格时间窗口的操作）

没有 timeout_action，一个长时间无人响应的确认门会让工作流永远悬着，没有告警，没有记录，没有恢复路径。

确认门的信息设计

确认门的 message 是给人看的，直接影响确认速度。设计原则：

markdown 复制代码

✅ 好的确认门消息：
  "测试通过率：67%（8/12 通过）
   失败的测试：test_null_input, test_overflow
   当前修复方案：修改了 parseInput() 的边界检查
   建议选择：重新分析，因为失败模式与预期根因不符"

❌ 差的确认门消息：
  "修复失败，请选择操作"

好的消息让确认人在 30 秒内做出决策，差的消息迫使他们去查日志。

串行重试 vs 并行候选

工作流遇到失败时，有两种应对策略，选错会显著降低效率或质量。

串行重试

scss 复制代码

第 1 次执行 → 失败
           ↓ (携带失败原因和 feedback)
第 2 次执行 → 失败
           ↓ (携带失败原因和 feedback)
第 3 次执行 → 通过

适合： 错误原因明确，后一次能从前一次学习，执行角度有差异空间。

arduino 复制代码

示例：根因分析（Phase 3）
  第 1 次：从代码层面分析
  第 2 次：feedback "代码分析置信度低，尝试从日志异常模式分析"
  第 3 次：feedback "改从时序角度分析调用链"

每次重试都在前一次的失败基础上换角度，学习是有效的。

并行候选

css 复制代码

         → 候选 A → 测试 → 通过   ← 选这个
分析结果 → 候选 B → 测试 → 失败
         → 候选 C → 测试 → 失败

适合： 解空间多样，难以预判哪种方案可行，多个方案并发探索后选优。

css 复制代码

示例：代码修复（Phase 4）
  候选 A：修改边界检查逻辑
  候选 B：修改调用方的参数校验
  候选 C：修改 parseInput() 的默认值处理

三种修法都有可能正确，无法预判，并发跑后选通过测试且覆盖率最高的。

选择原则

复制代码

后一次可以从前一次失败中学习  → 串行重试
多种方案同等可能             → 并行候选
时间紧张，不能等串行          → 并行候选
需要比较多个方案质量           → 并行候选（即使串行也能收敛）

在工作流定义里明确标注策略，方便调试：

yaml 复制代码

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 并行候选是方向性决策：根因分析用串行（学习有效），代码修复用并行（解空间多样）------搞反了效率和质量都会变差

欢迎访问 PrimeSkills ------ 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。

更多实用知识和有趣产品，欢迎访问我的个人主页