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

从脚本到工程

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

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

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

四层架构

Policy Layer policy.md 执行原则，全局约束→ 谁能做什么，高风险操作的授权规则Workflow Layer workflow.mdPhase / 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: accumulatecontext_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_onlycontext_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: explicitcontext_inputs:- source: phases.phase1fields: [bug_info.summary, bug_info.stack_trace, bug_info.jira_key]- source: phases.phase2fields: [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_Btype: interrupttrigger_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_manualtimeout: 24htimeout_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: 3feedback_mode: include_prev_errorphase_4_fix:retry_strategy: parallel# 修法不唯一，并发选优parallel_candidates: 3selection_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 并行候选是方向性决策：根因分析用串行（学习有效），代码修复用并行（解空间多样）——搞反了效率和质量都会变差

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

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