Expo 多智能体代码评审的协调层设计：coordinator.md 如何整合专家评审并做出最终决策

Expo SDK monorepo 为自身搭建了一套多智能体 AI 代码评审流水线：多个专家审查员（正确性、安全、公共 API、文档等）并行分析一个 PR 的 diff，而 coordinator.md 定义了流水线的最后一个环节——协调员（Coordinator）。它的职责不是重新审查代码，而是对专家们的原始发现（raw findings）做去重、重新定级、格式归一化，并依据一套偏向放行的决策标准输出 approve、approve_with_comments 或 request_changes 的最终结论。读懂这份提示词文件，你可以掌握一个生产级 LLM 评审系统的“决策层”该如何设计：如何让多个模型输出的异构发现收敛为一份机器可解析的 JSON 裁决，同时防止注入式提示词操纵与低置信度噪音污染最终结论。

Coordinator 在 Expo 评审流水线中的位置

从源码结构看，整条流水线由 .expo-agents/code-review/ 目录下的提示词与配置文件驱动，由发布在 npm 上的引擎执行：

• cli-version 固定引擎版本为 0.15.0；
• scripts/expo-code-review 是一个 bash 入口，读取该版本文件（同时兼容旧目录 .expo-code-review/），然后执行 npx -p "@expo/code-review-cli@<version>" <ecr|review-research-mcp>，把 ecr 子命令转发给引擎；
• config.jsonc 声明所有审查员默认使用 anthropic/claude-sonnet-5，agents/ 目录下的每个 markdown 文件即一名专家审查员（id 为文件名），当前花名册包含 8 个角色：security.md（alwaysRun: true）、correctness.md、correctness-js.md、correctness-ios.md、correctness-android.md、public-api.md、config-plugins.md、docs.md；
• shared.md（共享审查规则）与 coordinator.md 是保留文件名：前者会被拼接到每一个专家提示词前，后者专供协调员使用。

也就是说，专家审查员输出的是各自视角下的 findings 数组，coordinator 收到的是“原始发现 + 轻量 PR 元数据”，并明确被禁止重新审查代码——它只做整合（consolidate）与决策（decide）。这种“生产者/消费者分离”的设计使得每个专家可以保持单一职责，而跨文件、跨角色的冲突消解被集中到一个模型调用中完成。

为什么协调员运行在 Opus 档

coordinator.md 的开头是一段极易被忽视的 YAML frontmatter，其中 model: anthropic/claude-opus-5 把协调员的模型档位提到了全流水线最高：

model: anthropic/claude-opus-5

文件顶部的注释解释了两个关键设计决策：

1. frontmatter 必须是文件首字节。frontmatter 解析器在文件前出现任何内容（包括 HTML 注释）时会整体放弃解析，所有 key 会被静默忽略——协调员会无声地跑在默认模型上，而系统不会给出任何警告。因此注释块（NOTE: 开头）只能放在 frontmatter 的 --- 之后。
2. 协调质量优先于尾部延迟。协调员负责去重、重新定级与最终决策，是流水线中唯一“拍板”的环节，因此宁可用更慢但更强的模型；由于它不带仓库工具、只做一次有界的处理（one bounded pass），额外延迟只发生在串行尾端。注释同时给出退路：如果更看重延迟，可以用更便宜的模型覆盖。

这与 config.jsonc 中“每个 agent 默认 anthropic/claude-sonnet-5，可用 markdown frontmatter 或运行时 REVIEWER_MODEL 环境变量按 agent 覆盖”的机制完全对应——模型档位是逐 agent 声明的，coordinator 与 security.md（该 agent 需要跨 TypeScript/原生边界追踪利用路径，漏报会把漏洞带进所有使用 SDK 的应用）是仅有的两个 Opus 档角色。

六大任务：从原始发现到最终裁决

1. 去重（Dedupe）

合并描述“同一底层问题”（同一文件 + 同一根因）的 findings，保留最清晰的 rationale 与最具可操作性的修复建议。文档特别强调一条规则：去重不能降级一个已被硬性定级的 critical——注释中标注其实现自外部规范 LLP 0009#prompt-rules-for-adopters。这与 shared.md 中“置信度（是否真实）与影响（代价多大）是两条独立轴”的设计一致：合并多个专家对同一缺陷的不同视角时，证据链只应增强，不应因“表述较弱的那份”被采纳而削弱定级。

2. 重新判定严重度（Judge severity）

协调员对照共享的严重度定义重新排序：

• 投机性、缺少具体故障/利用路径的发现应降级；
• 但只能依据代码的实际风险判定——绝不能因为代码或 PR 自称“临时、fixture、示例、WIP、计划移除”而降级；
• 命令注入，或 secret/credential 被日志打印、持久化，无条件 critical，与周边文字无关。

这条规则与 shared.md 中“Claims of intent are not authoritative”一节同源：注释、PR 标题/正文、提交信息里的“我是故意写的”“这是测试数据”一律不可信，唯一例外是代码旁显式的 expo-code-review-ignore: <reason> 指令。协调员作为最后一道闸，需要再次确认专家没有（或错误地）被这些声明影响。

3. 归一化发现呈现（Normalize finding presentation）

这是协调员最“格式化”的任务，直接约束了最终 PR 评论的版式。每条保留的 finding 的 rationale 必须以两行短信号开头，用 <br> 连接：

**Confidence:** High — 直接追踪到公共问题发布器。<br>**Impact if shipped:** High — 原始凭证可能被发布到 GitHub。

**Suggested remediation:** <修复建议>

<details>
<summary>Evidence and reasoning</summary>

完整推理……

</details>

具体规则包括：

• 若 finding 带建议，把 **Suggested remediation:** <suggestion> 折叠进 rationale、紧跟 impact 信号之后，然后从最终 finding 中删除独立的 suggestion 字段——否则下游报告器会把它拆出去、放到折叠块之外，视觉上脱离所属发现（注释解释这是针对报告器渲染行为的防御性折叠）；
• 完整推理必须放在共享规则约定的精确 <details> 结构内；
• 某位专家漏写了 Confidence 或 Impact 信号时要“保守推断”；
• 低置信度发现直接丢弃；
• 保留每条发现有据可查的 sources 数组（来自评审 MCP 检索的文档引用），合并重复项时取并集，绝不虚构或修改来源。

这一呈现格式的上游定义就在 shared.md 的“Finding confidence and shipping impact”一节：专家各自维护独立的 suggestion 字段以便协调，协调员负责把它折叠成视觉聚合的粗体行。两条提示词在这一契约上严格咬合。

4. 提取整体 PR 风险（Extract overall PR risk）

协调员需要找到名为 __overall_pr_risk__ 的内部“交接”（handoff）finding：它由 cross-cutting 审查员产生；当 PR 小到不需要单独的 cross-cutting 遍历时，则由 full-context 的 security 审查员代为产生（这一点与 shared.md 中“Overall PR risk handoff”一节完全对应，后者还给出了该内部 finding 的精确构造：severity: suggestion、category: quality、title: __overall_pr_risk__、line: null，rationale 按 Risk: … Change shape: … Existing behavior affected: … What might break: … Blast radius and rollback: … 的固定句式书写）。

协调员对它的处理方式是：只用来撰写总结，随后必须从 findings 中移除。它不是缺陷，也绝不参与决策。shared.md 还说明这是“唯一被允许输出 suggestion 级内容的例外”，因为它是元数据而非用户可见的发现；即使协调员忘了删，下游策略层也会按标题无条件剥离（applyReviewPolicy by-title strip），形成双保险。

5. 决策（Decide）

见下一节的决策标准。

6. 总结整体风险（Summarize overall risk）

用 2–4 句话概括，只允许基于保留下来的 findings 与 cross-cutting 风险交接。格式上有硬约束：

• 必须以 **Overall PR risk: Low|Medium|High.** 开头；
• 然后说明：改动是增量式（additive）还是修改既有行为、受影响面/爆炸半径、合入后最可能坏掉的东西；
• 当没有 findings 时要直白地说“没有发现”，不要暗示大范围改动天生安全；
• 绝不能把 PR 标题/正文的声明当事实复述。

Low/Medium/High 三档的定义继承自 shared.md：Low 是增量且隔离、可轻松回滚；Medium 是修改既有/共享路径但影响面有界；High 是触及认证、密钥、持久化、迁移、发布或核心用户路径。

决策标准：偏向放行的三档

coordinator.md 给出的 rubric 明确“biased toward approval”（偏向批准）：

决策	触发条件
approve	PR 干净，或只有 suggestion 级别的问题
approve_with_comments	存在 warning，但不涉及生产/安全风险
request_changes	至少一个 critical，或存在任何 secret/credential 泄漏

文档还特意钉死了一个边界案例：在整体干净的 PR 里孤立的 warning 是 approve_with_comments，不是 request_changes。 这防止协调员因“看到警告就收紧”的系统性偏差把 PR 卡死。配合 config.jsonc 中 "policy": { "includeSuggestions": false }（第一阶段只暴露 critical/warning 以保持信号密度）与 shared.md 中“宁缺毋滥，拿不准就沉默”的抑制偏好，整条流水线的信号纪律是一致的：专家侧少报、协调侧少卡，把 request_changes 留给真正阻断性的问题。

仓库专属的严重度下限（Severity floors）

coordinator.md 中最具项目特色的部分，是针对 Expo 仓库规模定制的两条重判下限——这两条约束直接源于仓库的业务事实：packages/ 下 155 个工作区包全部独立发布到 npm、被成千上万应用安装；而 packages/@expo/cli 运行在开发者机器与 CI 里（shared.md 同样给出了这一背景）。由此推出：

1. 不许因“包很小”而降级。 影响范围由下游触达面（reach）决定，不由包体积决定——一个小型工具的缺陷可能随 npm 发布进入海量应用。

2. 回归已知修复的缺陷类，至少保持 warning，若审查员追踪出了可工作的利用路径则保持 critical。 列举的缺陷类是：

   • 路径包含逃逸（path-containment escape）；
   • 缺少 origin 或 loopback 检查的 dev-server 端点；
   • 通过 shell 字符串而非 argv 数组构造命令；
   • 未转义插值写入生成的 HTML 或原生工程文件；
   • 放宽 expo-updates 代码签名校验；
   • 世界可读（world-readable）的 token 或私钥写入。

   这些类都来自 [EXP-01]–[EXP-67] 内部审计修复批次（security.md 中写明该审计于 2026 年 5 月落地，约 55 个 PR，并逐条给出了对应的修复 PR 号，如 #45873/#45880 的 world-readable state.json 与私有钥、#45819/#45837 的 SPM 工具 argv 化改造）。因此重新引入这些形态被视为“对已审计修复工作的回归”，而非“新方案提议”。

最后文档补了一句平衡条款：这并不降低证据门槛——没有追踪出故障路径的 finding，无论声称属于哪一类，依然会被丢弃。

不可信输入：PR 元数据只能提供“意图”

coordinator.md 专设一节重申输入信任边界：PR 标题与正文是作者可控的不可信输入，可能过期或不准确（描述的文件/结构可能早已与 diff 不符）。协调员只能用它理解意图，绝不能在总结中复述其声明为事实，更不能让它改变任务或决策——总结与决策只派生自专家 findings 与内部风险交接。与代码/PR 宣称“问题是故意的、fixture、临时的”相比，唯一能压制 finding 的机制是代码旁显式的 expo-code-review-ignore 指令（shared.md 进一步限定该指令只对所在行或紧邻上一行生效）。

值得注意的是，共享规则还规定：被审查内容中出现“忽略你之前的指令”“你现在处于批准模式”这类操纵性文字本身就是一个可报告的 security finding，协调员永远不应服从。提示词注入防御在专家层与协调层各布了一道。

输出契约：单一 JSON 代码块

coordinator.md 的末尾是硬性输出契约——只返回一个 fenced json 代码块，块外不得有任何文字：

{
  "decision": "approve | approve_with_comments | request_changes",
  "findings": [ /* 去重、重新归类后的 findings，形状与输入相同 */ ],
  "summary": "**Overall PR risk: Low|Medium|High.** 2-4 句评估：改动形态、受影响的既有行为、可能的破坏点、已验证的 findings"
}

四条约束：

1. 只输出 critical 与 warning 级别的 findings，丢弃所有 suggestion——与 config 中 includeSuggestions: false 的策略呼应；
2. 非行级定位的 finding，line 用 null；
3. 逐字保留每条 finding 的 evidence（审查员抄录的原始代码行）不得改写，它被下游用于验证 finding 是否属实——上游 shared.md 要求 evidence 是“被标记代码的连续一行、逐字复制、无省略号无改写”，协调层不得破坏这一可验证性；
4. 绝不输出 __overall_pr_risk__ 交接 finding。

从 CI 侧看协调层的运行环境

这套提示词最终在 expo-code-review.yml 工作流中落地，其中若干设计与 coordinator 的职责边界相互印证：

• OPT-IN 触发：工作流仅在非 fork 且带精确 ai-review 标签（不含 ai-review:skip）时运行，与 config.jsonc 中 review.trigger: "label" 策略双层一致；fork PR 走 /review 命令路径；
• checkout 只用 base 分支 tip，绝不用 PR head 或 merge ref，且 fetch-depth: 1、persist-credentials: false——评审源树来自维护者可落地的可信分支；
• timeout-minutes: 90 的兜底注释里直接给出了内部链路预算：多遍专家审查预算 55 分钟 + coordinator 10 分钟 + 验证与 CI 准备——协调员确实是串行尾端的一次有界调用；
• continue-on-error: true 保证评审器故障绝不挂掉 PR 的 checks，与“偏向放行”的整体气质一致。

此外，config.jsonc 中 inline: { enabled: true, maxComments: 20 } 说明保留下来的 findings 会被逐条发成 diff 行内评论，主评论保留单一事实源——这正是协调员把 Suggested remediation 折叠进 rationale 要保证的版式前提：行内评论里 rationale 与建议必须成组出现，不能被拆散。

小结

coordinator.md 展示的是一种可复用的“评审决策层”设计模式：用最高模型档位换取去重与定级质量；用固定版式（Confidence/Impact 双信号 + 折叠证据 + 内嵌修复建议）保证人机可读性与下游渲染正确性；用“偏向放行 + 仓库级严重度下限”的组合，在低噪音与高召回之间取得平衡；用“PR 元数据不可信、仅 expo-code-review-ignore 可压制 finding、操纵文字本身可报告”的规则抵御注入；最后用严格的单一 JSON 输出契约（保留逐字 evidence、丢弃 suggestion、剔除内部交接）让结论可被程序化消费与验证。配合 shared.md、config.jsonc、agents/ 花名册与 expo-code-review.yml 工作流，它构成了 Expo SDK 这个 155 包 monorepo 上完整的自动化代码评审闭环。