OpenClaw 文档技能中的 synthesis-agent：长上下文合成子代理如何将多 Agent 审查结果合并为一份可执行的文档行动清单

OpenClaw 仓库内置了一个名为 technical-documentation 的 Agent 技能，它用四个职责不同的子代理（inventory、governance、docs-framework、synthesis）分工完成全仓库技术文档的盘点、审查与修复。本文以 synthesis-agent.md 为核心，完整拆解这个"合成"环节：它如何作为长上下文终点站，把上游三个子代理的离散输出归一化为一份去重、分级的行动清单，并逐项解析其模型选型（opus）、工具白名单（仅 Read）与回合预算（maxTurns: 12）背后的设计意图。

synthesis-agent 在技能编排中的位置

SKILL.md 定义了这套技能的整体工作流：任务先被分类为 build 或 review（再区分 brownfield/evergreen 上下文），随后进行文档面盘点、多语言范围检测、规则读取，最后产出交付物。其中第 10 步明确写道：

When available, use sub-agents for bounded parallel discovery/review work, then merge outputs into one coherent final deliverable.

也就是说，"合并"不是可选项而是工作流的收尾动作。SKILL.md 的 Sub-agent orchestration guidance 小节给出了四个子代理的完整编排表（agents/ 目录下的四个文件一一对应）：

子代理	定义文件	模型档位	可用工具	maxTurns	职责
inventory-agent	inventory-agent.md	fast / Claude haiku	Read、Glob、Grep、LS	6	文件与配置发现、覆盖度地图、缺失路径检测
governance-agent	governance-agent.md	thinking / Claude sonnet	Read、Glob、Grep	10	AGENTS/CONTRIBUTING/别名优先级、冲突与策略漂移
docs-framework-agent	docs-framework-agent.md	thinking / Claude sonnet	Read、Glob、Grep	10	框架配置、路径映射与发布路由一致性
synthesis-agent	synthesis-agent.md	long / Claude opus	Read	12	合并上游输出为一份分优先级、去重的修复计划

从源码结构看，前三个代理各自输出"局部结论"，synthesis-agent 是流水线中唯一以"合并"为目标的节点：SKILL.md 对它的一句话定位是 "merge sub-agent outputs into one prioritized fix plan and unified precedence model"。principles.md 的 Execution policy 部分也再次约束了这一原则："Keep one merged outcome: sub-agent outputs must be normalized into a single consistent recommendation/fix set."——任何子代理方案最终都必须收敛为唯一的一套建议，这正是 synthesis-agent 存在的理由。

Frontmatter 配置逐项解析

synthesis-agent.md 的 YAML frontmatter 只有 8 行，但每个字段都对应一个明确的工程决策：

---
name: synthesis-agent
description: Long-context synthesis agent that merges sub-agent outputs into one prioritized and deduplicated documentation action plan.
model: opus
tools:
  - Read
permissionMode: default
maxTurns: 12
---

• name: synthesis-agent：与 SKILL.md 中 "synthesis-agent -> agents/synthesis-agent.md" 的映射一致，技能通过该名称定位到本文件。
• description：一句话同时声明了三个关键属性——"Long-context"（长上下文）、"merges sub-agent outputs"（合并上游输出）、"prioritized and deduplicated documentation action plan"（输出是分优先级且去重的文档行动计划）。这段描述既是给编排方看的选型依据，也隐含了输出契约。
• model: opus：对照 SKILL.md 的档位标注 long / Claude opus，可见这里选的是四代理中最强的长上下文模型。可以推断其原因是：合并任务需要在上下文里同时容纳 inventory 的覆盖度地图、governance 的冲突清单和 docs-framework 的路径错配报告，输入体量远超单个上游代理；而 haiku/sonnet 档位的代理只需在各自边界内做发现与比对。
• tools: [Read]：只开放 Read，与其余三个代理形成鲜明对比——inventory 需要 Glob/Grep/LS 做全盘扫描，governance 与 docs-framework 需要 Glob/Grep 做交叉核对，而 synthesis 阶段不再做任何新发现，它的职责只是读取并消化上游已经产出（或以文件形式落盘）的结论。只读工具白名单从机制上保证了合成阶段不会引入"边合并边重查"造成的结论漂移。
• permissionMode: default：与上游代理保持一致的默认权限模式，不额外放宽。
• maxTurns: 12：四个代理中回合预算最高（6 / 10 / 10 / 12）。这与任务形态吻合：它不做探索，但要依次完成"排序 → 归一化 → 去重 → 压缩"四道加工，留出的回合数用于对输入做充分的多轮通读与交叉比对，而不是文件遍历。

另外，openai.yaml 中技能级的 policy.allow_implicit_invocation: true 表明该技能允许隐式触发；一旦触发且任务被判定为仓库级、多框架或高冲突场景，SKILL.md 要求"默认启用子代理"，synthesis-agent 随之成为收尾节点。

核心任务：四条合成职责的展开

文档正文对 synthesis-agent 的定位与任务定义非常精炼（全文见 synthesis-agent.md，正文仅 20 行）：

You are the synthesis sub-agent for technical documentation.

Goal: merge sub-agent outputs into one coherent, non-duplicated action plan

四条 Tasks 分别解决多代理并行审查中必然出现的四类问题：

1. 阻塞项优先（prioritize blockers first, then non-blocking improvements）

这是输出结构的硬约束：先列必须修复的阻塞项，再列改进项。它直接对接技能审查侧的输出规范——review.md 第 12 节 Output format 要求最终交付物按三段式组织：

1. Blocking issues（文件 + 所需修复）
2. Non-blocking improvements
3. Validation notes（done vs pending）

synthesis-agent 的 "blockers first" 任务就是把上游各自为政的发现重排进这个骨架，保证执行方拿到的是可排期的清单而非按发现顺序罗列的噪声。

2. 归一化为统一优先级模型（normalize to one precedence model）

这是四条任务中最具架构性的一条。上游代理的输出天然使用不同的"优先级语言"：

• governance-agent.md 的 Return 是 precedence model / conflict list with severity / recommended low-risk remediations——它产出的是策略层级（AGENTS 与别名的规范源判定、冲突严重级）；
• inventory-agent.md 的 Return 是 coverage map / missing-broken path list / unresolved blockers——它产出的是事实清单（缺失文件、坏引用、硬失败）；
• docs-framework-agent.md 的 Return 是 config files reviewed / path assumptions / mismatches（missing file、stale route、wrong base path 三类错配）。

"normalize to one precedence model for governance decisions" 意味着 synthesis-agent 要把这三套口径压平成单一排序：例如 inventory 报告的一条坏链接与 governance 报告的一处 AGENTS 冲突，谁先修、谁阻塞谁，必须落入同一把标尺。这把标尺的底层依据在 principles.md 的 Practical merge policy 中已经给出——读者任务成功 > 结构清晰度 > 长期可维护性 > Agent 优化，且 "Add agent optimization only if it does not reduce human clarity"。合成阶段做的正是把各代理发现按这条合并策略重新定级。

3. 去重与矛盾消解（remove duplicated recommendations and contradictory fixes）

并行代理从不同视角扫同一仓库，重复是必然的：inventory 报"README 缺失"，docs-framework 也可能因 config -> file exists 校验失败报同一文件；governance 与 docs-framework 还可能对"哪个文件是规范源"给出矛盾结论。synthesis-agent 的 description 中 "non-duplicated" 与任务列表中的 "remove duplicated recommendations and contradictory fixes" 互相呼应，说明去重（同一问题多来源）和矛盾消解（不同代理结论相反）是两类独立工作：前者合并证据来源，后者必须裁决并保留唯一结论。

4. 保持输出简洁且可执行（keep final output concise and execution-ready）

"execution-ready" 指输出可直接被下游（人或主 Agent）逐条执行，而非需要二次解读的分析报告。结合 review.md 对阻塞项的要求（file + required fix，即必须落到具体文件与修复动作），synthesis-agent 的产物粒度是"文件 → 修复动作"级别。同时 build.md 第 1 节要求合并结果为 "one canonical decision set"，即合成产物同时服务于 build 与 review 两类任务，是整条流水线唯一的决策出口。

输入契约：synthesis-agent 实际"合并"什么

从三个上游代理的 Return 定义可以精确拼出合成阶段的输入契约：

输入来源	具体内容	合成时的处理方式
inventory-agent	覆盖度地图、缺失/坏路径列表、未解决阻塞项	作为"事实底座"，坏路径类发现通常直接进入 Blocking 区
governance-agent	优先级模型、带严重级的冲突清单、低风险修复建议	其优先级模型是归一化的主要骨架来源
docs-framework-agent	已审查配置清单、路径假设、missing file / stale route / wrong base path 错配	路径错配与 inventory 的坏路径做交叉去重
技能自身的执行模式	single-agent 或 sub-agent-assisted（SKILL.md Inputs 小节）	单代理模式下该步骤退化为主 Agent 自合并，子代理模式下的合成输入即上表

值得注意的是，synthesis-agent 的 tools 只有 Read，说明从设计上看，上游输出要么以消息形式注入其上下文，要么以文件形式落盘后由它读取——两条路径都不需要它自己发起搜索。这与 review.md 第 2 节的描述一致："use sub-agents for bounded parallel discovery ..., then merge to one final issue set"：发现（discovery）与合并（merge）是严格分层的两个阶段。

输出契约：三件交付物

synthesis-agent.md 的 Return 部分定义了合成阶段的完整交付物：

• prioritized fix plan（分优先级的修复计划）：按 "blockers first, then non-blocking improvements" 排序的统一行动清单，每条可追溯到具体文件；
• validation summary (done vs pending)（验证摘要）：与 review.md 第 12 节第 3 项 "Validation notes (done vs pending)" 逐字对应——已验证完成的检查项与尚待完成的检查项分开陈述；
• explicit remaining gaps/blockers（显式的剩余缺口与阻塞项）：要求把无法在合成阶段裁决或修复的问题明确列出，而不是静默丢弃。

这三件交付物正好也是 SKILL.md 工作流第 15 步（"Return deliverables plus validation notes, parity status, and remaining gaps"）对整个技能最终输出的要求。换句话说，synthesis-agent 不是流水线末端的一个"格式化器"，它产出的就是技能对外的最终契约：交付物 + 验证状态 + 剩余缺口。

与仓库治理规则的一致性约束

合成阶段的裁决并非无据可依。当待合并的发现涉及 AGENTS/CONTRIBUTING/别名体系时，principles.md 指明以 agent-and-contributing.md 为详细规则源，其中给出了可直接作为归一化标尺的硬规则：

1. AGENTS.md 存在时即为规范源（canonical），否则取最近的别名文件；
2. 兼容面（AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/）必须显式映射回规范策略，"Keep policy DRY: store one shared policy core and expose it via aliases/symlinks instead of duplicating rule text"；
3. 行为边界统一使用 Always / Ask first / Never 三级表述。

这意味着 synthesis-agent 在消解 governance-agent 与 docs-framework-agent 的矛盾结论时，有一条确定的裁决顺序：优先服从"单一策略核心 + 别名兼容"的 DRY 原则，而不是在两份冲突建议间折中。同样，openclaw.md 作为 OpenClaw 专属叠加层，要求文档工作遵循页面类型（Overview/Quickstart/Topic/Guide/Reference 等）、docs/docs.json 导航约束与保留性审查（keep/drop/move/destination 矩阵）——当合成输入包含 OpenClaw 文档面发现时，这些规则构成排序与归类的附加约束。

小结：一个"长上下文终点站"的设计范式

把 synthesis-agent.md 放回 technical-documentation 技能 的完整编排中，可以看到一套清晰的子代理分工范式：

• 发现层用便宜、快速的模型（haiku/sonnet）+ 搜索工具（Glob/Grep/LS）做有界并行扫描；
• 合成层用最强长上下文模型（opus）+ 只读工具，放弃发现能力，换取对全量上游输入的完整通读与交叉裁决能力；
• 回合预算随职责复杂度递增（6 → 10 → 12），合成阶段最高，因为它的产出质量决定整条流水线的交付标准；
• 输出契约（分优先级计划 + done/pending 验证摘要 + 显式剩余缺口）与技能顶层 SKILL.md 及 review.md 的输出格式严格对齐，保证子代理产物无需二次加工即可作为最终交付物。

对于在多 Agent 系统里设计"结果合并"环节的读者，这个 28 行的代理文件提供了一个可直接参照的模板：合并者应当工具最小化（只读）、上下文最大化（长上下文模型）、任务显式化（排序/归一化/去重/压缩四步各自成条）、输出契约与上游技能的最终交付标准逐字对齐。