外观
第 36 章 Research Brief：Harness Design Patterns
要解决的工程问题
当团队把每一类 Agent 任务都塞进同一个“多 Agent”框架时，任务拥有者、状态边界、停止条件和副作用责任会变得不可见；反过来，所有任务都用固定串行步骤，又会把真正需要分派、并行或异步响应的工作强行压平。本章研究如何把控制流选择写成可审查的模式卡（Pattern Card）：读者可以说明为什么选择一种结构、它需要哪些输入与证据、何时应升级，以及它不保证什么。
读者问题与范围
| 读者问题 | 本章研究的回答 | 本章不回答 |
|---|---|---|
| 什么情况下应保留简单循环？ | 当一个任务的下一步主要由当前观察决定、只有一个结果所有者且不需要预定义子任务图时，可先使用受控单循环，并明确观察、预算和停止条件。 | 单循环天然安全、成本最低，或足以处理所有长任务。 |
| 什么时候把计划与执行分开？ | 当子任务和验收门可以预先写清时，可用计划—执行模式把计划工件、执行状态和重新规划门分开。 | 计划一经生成就必然正确，或执行者可以跳过验证。 |
| 为什么需要监督者或流水线？ | 当需要一个结果所有者协调有边界的专长输出时，使用监督者—工作者；当步骤顺序稳定且每段可以设置门时，使用流水线。 | 工作者数量越多越好，或监督者能够替代领域审批。 |
| 事件驱动结构解决什么？ | 当任务由外部状态变化触发且消费者可独立处理时，显式记录事件契约、去重、交付语义、失败所有者与恢复策略。 | “事件”一词本身保证可靠投递、顺序、幂等或安全。 |
| 如何避免模式堆叠？ | 每个模式卡都声明触发条件、控制权、状态边界、证据、停止/升级和副作用责任；缺一项时先补契约，不增加新角色。 | 一张决策树可以替代性能测试、风险评估或人工授权。 |
研究范围与非范围
研究范围： 控制流模式的选择条件、输入输出边界、单一结果所有者、状态与证据、组合限制、反模式和演进触发器。拟讨论的五张模式卡为受控单循环（Controlled Single Loop）、计划—执行（Plan–Execute）、监督者—工作者（Supervisor–Worker）、流水线（Pipeline）和事件驱动（Event-Driven）。这些名称是本书用于比较 Harness 控制流的工程模型；它们不构成产品 API、行业标准或运行时实现。
研究非范围： 不实现 Agent、队列、事件总线、调度器、外部工具、并发执行、工作流引擎或真实文件修复；不比较模型能力、吞吐、延迟、价格或基准；不承诺任何模式的可靠投递、恰好一次、自动恢复、权限或安全性质；不把 CloudEvents、AWS Step Functions、Node.js 或 OpenAI Agents SDK 的具体行为改写成跨产品规则。
已核验的一手资料
| 本地键 | 来源明确表达的内容 | 允许用途 | 不可外推 |
|---|---|---|---|
| CH36-REF-01 → REF-029 | Anthropic 将预定义代码路径编排的系统称为 workflow，将模型动态决定过程与工具使用的系统称为 agent；文章分别说明串联、路由、并行、编排者—工作者与评估—优化等常见结构，并建议仅在能证明改善结果时增加复杂度。 | 用作“固定控制流与模型主导控制流不同”“模式应从简单结构开始”的受限工程背景。 | 不是通用分类标准、性能结论、默认架构、生产安全保证或本书模式卡定义。 |
| CH36-REF-02 → REF-030 | OpenAI Agents SDK 的 Python 文档区分由 LLM 决策与由代码编排；在该 SDK 语境中说明 manager 调用 specialist、handoff、串联、评估循环和独立任务并行。 | 用作监督者—工作者、路由和代码控制流的产品特定例子。 | 不证明其他 SDK 有同一接口、handoff 安全、并行无共享状态冲突，或任一结构已经在本书运行。 |
| CH36-REF-03 → REF-031 | AWS Step Functions 文档将该产品的 workflow 描述为由事件驱动步骤构成的状态机，并列出 Choice、Wait、Map、Parallel 等流控制状态以及执行、输入输出和错误处理概念。 | 用作“显式状态、分支和并行都需由具体运行时定义”的产品例子。 | 不把 ASL 字段、redrive、数据格式、执行语义或恢复能力推广为通用 Harness 契约。 |
| CH36-REF-04 → REF-114 | CloudEvents 规范把 event 定义为表达一次发生及其上下文的数据记录，区分 producer、consumer 与 intermediary，并规定事件描述的可互操作格式。 | 用作事件契约至少要区分发生事实、上下文、生产者和消费者的规范背景。 | 不证明投递保证、顺序、去重、授权、重试、事件总线可用性或本书事件驱动模式的实现。 |
| CH36-REF-05 → REF-115 | Node.js EventEmitter 文档说明其命名事件与监听器模型；该实现会按注册顺序同步调用监听器。 | 用作“事件运行时语义必须具体核验”的反例背景。 | 不把 Node.js 监听器顺序或同步行为外推给消息队列、浏览器、云事件或任何其他事件系统。 |
来源观点、本书工程模型与教学案例的边界
来源明确表达的事实
- Anthropic 的文章在其工程建议语境中区分预定义 workflow 与模型动态控制的 agent，并列举多种组合结构；它明确提醒复杂度、成本和延迟存在取舍。
- OpenAI Agents SDK 文档只说明该 Python SDK 中 manager、handoff、代码编排和并行示例的接口与适用语境。
- AWS Step Functions 和 Node.js 文档只说明各自产品或运行时的状态/事件语义；CloudEvents 规范只说明事件数据描述与互操作格式。
本书工程扩展
本书把模式卡定义为一个可审查选择单元，最少包含以下字段。字段不是上述任何来源的 schema，也不会自动创建实现：
| 字段 | 本书中的作用 | 需要回答的问题 |
|---|---|---|
| Trigger | 说明何种输入、状态或事件可以启动模式。 | 谁能触发，触发前是否要验证？ |
| Control owner | 指定谁决定下一步和谁拥有最终结果。 | 模型、代码、监督者或人类分别能改变什么？ |
| Work contract | 描述每个步骤/工作者接收什么、返回什么、不能做什么。 | 输出是否可合并，副作用由谁批准？ |
| State and evidence | 指定何处记录状态、观察和验收证据。 | 中断后如何知道下一步，而不把自然语言摘要当作事实？ |
| Stop and escalation | 说明预算耗尽、证据矛盾或高风险动作时如何停止。 | 哪些条件只能升级给人类？ |
| Evolution trigger | 记录从简单模式升级的可观察理由。 | 什么证据表明现有结构已不足，而不是“看起来更专业”？ |
本书还提出一个选择顺序：先问任务的下一步是否可由稳定规则决定；再问子任务是否可预先枚举、相互独立，还是需要动态分派；最后才问是否有外部事件、跨执行状态或副作用使额外的运行时契约必要。这个顺序是教学上的风险控制，不是来源宣称的唯一决策算法。
教学案例与未执行边界
后续正文可使用一个虚构的“文件修复请求”作为比较输入：任务先读只读诊断，再决定是否形成计划并分派受限分析工作；任何写入候选都停在人工审批前。它不代表真实仓库、Bug、Agent、队列、事件、并行工作者、Git 操作、浏览器、CI、账户、网络或外部系统已经创建、调用或验证。
拟定模式卡与选择约束
| 本书模式卡 | 适用的最小条件 | 不应使用的信号 | 必须显式拥有的边界 |
|---|---|---|---|
| 受控单循环 | 一名结果所有者可根据观察决定下一步；任务规模与尝试预算可见。 | 需要稳定拆分、多个独立结果或异步外部触发却没有状态契约。 | 观察输入、工具/权限边界、预算、停止与证据。 |
| 计划—执行 | 子任务、依赖和验收门可在执行前形成可审查计划。 | 环境会快速改变，计划不能解释下一步，或计划被当作执行许可。 | 计划版本、执行状态、重新规划门、验收与审批。 |
| 监督者—工作者 | 有一个结果所有者，且工作者专长、输入输出和合并规则可界定。 | 多个工作者都能写同一外部状态，或没有人负责冲突、失败和最终结论。 | 委派契约、结果归属、合并、冲突处理与升级。 |
| 流水线 | 阶段顺序稳定，前一阶段产物可被下一阶段校验和消费。 | 步骤依赖高度动态，或某阶段失败后只能重新猜测全部历史。 | 阶段输入输出、质量门、失败分支、回退和状态记录。 |
| 事件驱动 | 触发来自可定义的发生事实，消费者可在明确交付/恢复语义下独立处理。 | 仅为了“异步”而引入事件，或无法定义去重、顺序、失败所有者和可观测性。 | 事件契约、路由、交付语义、去重、死信/升级与审计。 |
需要在后续阶段再次核验的事实
TODO(verify)：在 Chapter Outline、First Draft、Technical Review 与 Fact Check 当日重新读取 CH36-REF-01 至 CH36-REF-05；动态 SDK、云产品、Node.js 版本和 CloudEvents 草案不得仅凭本次访问记录进入正文。TODO(verify)：若正文保留 OpenAI Agents SDK 的 manager、specialist 或 handoff 术语，逐句限定为该 Python SDK 页面所述接口，并确认 URL 与文档版本仍可访问。TODO(verify)：若正文使用 AWS Step Functions 的 Choice、Map、Parallel、redrive 或 JSON 细节，逐项重新读取对应官方产品页；不要把字段名或产品保证混入模式卡。TODO(verify)：若正文讨论事件格式，确认 CloudEvents 正式稳定版本、协议绑定和所需属性；当前读取的规范页面标示为1.0.3-wip，不能写成固定版本承诺。TODO(verify)：任何“更快”“更可靠”“成本更低”“并行安全”或“可恢复”主张都需要任务级测量或实际运行证据；本研究没有该类证据。
计划图示、示例与验证
计划图示
后续可新增 diagrams/mermaid/chapter-36-control-flow-pattern-selection.mmd，以同一任务输入分别连接到五张模式卡，并在每张卡外侧标出控制权、状态/证据、停止/升级和副作用责任。图只解释本书选择模型；不描绘真实队列、事件总线、Agent、云服务或并发运行。
计划示例
后续可新增纯内存示例计划 36-harness-design-patterns.example-plan.md，并在 Example Implementation 阶段实现一个接收注入式模式提案的函数，例如 assessHarnessPatternSelection。它只检查模式卡字段是否齐全、控制权是否冲突、是否缺少停止或副作用边界，并返回教学状态；不启动工作者、不调用模型、不并行、不发送事件、不读写文件、不访问网络，也不证明任何真实架构可运行。
计划验证
- Research 阶段仅对本 Research Brief 与 references 文件运行 Markdown lint；未运行模式选择器、Agent、队列、事件、工作流或外部系统。
- Example Implementation 阶段先用一个缺失模块的测试记录红灯，再新增纯内存模块与行为测试；通过只能证明注入对象的分类契约。
- Diagram Review 阶段才导出并目检 Mermaid 图；图示完成也不代表控制流、并行、事件或恢复已执行。
- Fact Check 阶段重新定位所有动态资料，逐项复核允许用途与外推禁区。
风险、反模式与演进触发器
| 风险或反模式 | 可观察表现 | 本书建议的检测与收敛方向 |
|---|---|---|
| 为每个任务预设多 Agent | 工作者角色重叠，最终结论无人拥有，失败被转述而非处理。 | 先证明单循环或流水线不能满足明确的任务约束，再新增一个有输入输出和停止条件的角色。 |
| 计划被当成执行许可 | 计划包含写入或发布动作，却没有当前观察、授权或验收门。 | 分离计划、批准和执行状态；任何外部副作用回到权限与审批边界。 |
| 事件掩盖责任 | 事件产生后没有消费者所有者、去重策略、失败记录或升级路径。 | 先写事件契约和失败责任；无法定义时保留同步边界或停止。 |
| 把并行当作免费加速 | 共享状态冲突、预算不可见、聚合器把不一致输出压成单一结论。 | 只并行真正独立的输入；定义结果合并、冲突处理和成本/时间预算。 |
| 模式组合没有退出条件 | 新增路由、监督和评估循环后，无法说明何时结束或谁批准下一步。 | 每添加一层都补 Stop and escalation；若不能补齐，回退到更简单的可观测模式。 |
对后续阶段的交接
- Chapter Outline： 按“选择问题 → 五张 Pattern Card → 组合/反模式 → 虚构文件修复对比 → 纯内存准入器 → 图示断点 → 练习”的顺序展开；每节标明来源事实、本书模型与未执行边界。
- First Draft： 用原创的文件修复场景比较受控单循环与计划—执行，避免把厂商示例、术语或模式图改写为普适定理。
- Technical Review / Fact Check： 将 CH36-REF-01 至 CH36-REF-05 的逐句用途与动态来源复核拆开；确认“并行”“handoff”“事件”“状态机”“恢复”等词都带有具体主体与范围。
- Example / Diagram Review： 示例只能检查注入的模式提案；图只能表达选择关系和责任边界，二者均不得声称真实系统已调度、投递或恢复。
Research Brief 完成检查
- [x] 已说明读者问题、研究范围与明确非范围。
- [x] 已将来源明确表达的事实、本书工程扩展与虚构案例分开。
- [x] 每项来源均记录可支持陈述与不可外推范围。
- [x] 已为模式卡、图示、纯内存示例和后续 Fact Check 留出可验收入口。
- [x] 未实现或运行 Agent、工作流、队列、事件、并发、工具、外部系统或真实文件修复。