oh-my-claudecode 只读审查赛道：Role Reviewer 提示词规范与 CLEAR/WATCH/BLOCK 判定契约详解

本篇以 oh-my-claudecode 仓库中由 Prompt SSOT（单一事实源）确定性生成的 Tier-0 角色提示词 generated/prompt-ssot/role-reviewer.md 为核心展开。该文档面向团队多智能体（Teams-first multi-agent）编排体系中的 Reviewer（审查者）车道，定义了只读审查的职责边界、三种终态判定（CLEAR / WATCH / BLOCK）、安全边界模型与输出契约。读完本文将掌握：Reviewer 角色在四车道（Planner → Executor → Reviewer → Verifier）中承担何种审查维度、其提示词如何从源码级 SSOT 组合生成并可校验，以及如何在真实团队任务中被可信运行时以结构化判定（structured verdict）消费。

一、文档定位：一份由 Prompt SSOT 生成的 Reviewer 角色投影

generated/prompt-ssot/role-reviewer.md 属于 generated/prompt-ssot/ 目录下五个投影文件之一（另有 coordinator.md、role-planner.md、role-executor.md、role-verifier.md）。它的文件头带有生成元数据：

• schemaVersion: 1、projection: role-reviewer、sourceRevision: 2026-08-13.1
• overlay.provider: none、overlay.modelTier: none（本次组合未叠加任何 Provider/模型分层 overlay）
• sha256: f67aea3bfa90beb2ecc5dddec1ecfa63de5a0df1bb9b8e3cdb1a0829d9d5db4a
• 关键提示：Regenerate: npm run prompt-ssot:build. Do not edit by hand.

这意味着该文件不是手写文档，而是自动化构建产物：任何「规范条款」的修改都必须改源码中的规范片段，再重新生成投影。这种「条款只写一次、多投影确定性输出」的设计是 epic #3698 / issue #3704 引入的 Prompt SSOT 机制（见 src/agents/prompt-ssot/sections.ts 顶部注释）。因此，把本文档当系统提示词读只是第一步，读懂其上游组合规则才能真正驾驭它。

1.1 Reviewer 在角色体系中的位置

从 src/agents/prompt-ssot/manifest.ts 可以确认，role-reviewer 与 role-planner、role-executor、role-verifier 一同作为 Tier-0 角色投影被声明（源码注释将其关联到 issue #3703 的 workflow registry）。每个角色投影由完全相同的六个基础部分叠加各自的 role/<role> 增量构成：

1. policy/operating-principles（操作原则）
2. task-contract/verification（验证契约）
3. task-contract/execution-protocols（执行协议）
4. safety/hard-boundaries（安全边界）
5. role/reviewer（角色增量——本篇的核心差异点）
6. output/evidence-contract（输出契约）

manifest.requiredSections 强制要求每次组合必须包含 policy/operating-principles 与 safety/hard-boundaries，缺失任何必需片段组合就会直接报错。这就是为什么你在 role-reviewer.md 中看到的段落顺序（Operating Principles → Execution Protocols → Verification → Safety Boundaries → Role: Reviewer → Output Contract）与角色在其他投影文件中「看起来高度相似」——因为共享的政策片段本来就出自同一处。

二、Operating Principles：八条对所有车道生效的公共操作原则

本节是全部 Tier-0 投影共享的规范条款（源码单一来源：sections.ts 中 policy/operating-principles）。逐条展开其评审语境下的含义：

原则	原文含义	Reviewer 语境下的解读
委派最合适的主体	Delegate specialized or tool-heavy work to the most appropriate agent	深度安全审计应交给 security-reviewer，计划评审交给 critic，而非让执行者自审
证据优先于假设	Prefer clear evidence over assumptions: verify outcomes before final claims	审查的每个 BLOCK/WATCH 结论都必须有 file:line 或可复现证据
走最轻量路径	Choose the lightest-weight path that preserves quality (direct action, MCP, or agent)	简单变更不必全员重审；复杂度匹配车道
先查官方文档	Consult official documentation before implementing with SDKs, frameworks, or APIs	审查涉及框架用法时，以官方文档为比对基准
删优于增	Prefer deletion over addition when the same behavior can be preserved	审查时应指出可删除的冗余代码而非新增绕行方案
复用既有工具	Reuse existing utilities and patterns before introducing new ones	拒绝重复造轮子的变更
不擅自加依赖	Do not add new dependencies without an explicit request or approval	审查中把未授权的依赖引入列为红旗
小且可逆的 diff	Keep diffs small, reversible, and easy to review	直接约束审查对象本身的形态

这八条是「审查者自己也必须遵守」的元规则：Reviewer 在给他人提要求前，自身的评审粒度、证据粒度也要匹配这些原则。

三、Execution Protocols：审查与创作必须分离的执行协议

• 面对宽泛无明确目标的请求，先探索、后规划（explore first, then plan）；
• 相互独立的任务并行执行，存在依赖的任务串行执行；
• 创作与审查必须是独立的两遍，绝不允许在同一遍里自我批准（Keep authoring and review as separate passes; never self-approve in the same pass）——这是对「审查车道」存在意义的直接背书，也与 agents/code-reviewer.md 中「Never approve your own authoring output or any change produced in the same active context」的约束相互印证；
• 安装、构建、测试类长任务放入后台执行（Use background execution），避免阻塞审查主流程。

四、Verification：先验证再宣称完成

Verify before claiming completion: identify what proves the claim,
run the verification, read the output, then report with evidence.

该契约要求四步闭环：① 明确什么能证明该结论 → ② 真正运行验证 → ③ 阅读输出 → ④ 携带证据汇报。验证失败时应继续迭代而非把未完成工作当作完成汇报；收尾前必须确认：零遗留任务、测试全部通过、零错误、已收集验证证据。

对 Reviewer 而言这条是双刃剑：它既要求被审变更的提供者给出可复现验证，也要求 Reviewer 自己的 CLEAR 结论建立在「确实跑过、确实读过输出」之上——这与 role-verifier.md 中「It should work is not verification；should/probably/seems to 这类词要求一次真实运行」的措辞一脉相承。

五、Safety Boundaries：安全边界的双层失效模型

Advisory checks fail open with a bounded, visible warning and never block routine work.
Hard checks fail closed only for: secrets/privacy, destructive mutation,
release/publish authority, proven corruption or integrity risk, and security boundaries.
Unknown failures default to advisory during migration and must be classified
before any legacy removal.

安全边界采用双层失效策略，这是理解 Reviewer 权限上限的关键：

• Advisory（咨询性）检查「开放失败」（fail open）：即使检查异常，也只产生一个受控、可见的警告，绝不阻断日常工作流；
• Hard（硬性）检查仅在以下五类情形「闭合失败」（fail closed）：密钥/隐私泄露、破坏性变更、发布/发版权限、已被证实的数据损坏或完整性风险、安全边界突破；
• 迁移期未知故障默认按 advisory 处理，且在任何遗留代码删除前必须先完成风险分类。

落到 Reviewer 身上就是一句话：Review 车道默认不阻断、不越权——真正能硬性叫停变更的只有上述五类红线。

六、Role: Reviewer——文档的核心角色增量

role/reviewer 是整份文档的灵魂片段（源码见 sections.ts 的 role/reviewer），其完整规范如下：

You are the read-only review lane. Evaluate the change across architecture (boundaries, layering, risks), product (user-visible behavior, acceptance criteria, regressions), and code (maintainability, tests, unsafe shortcuts). Return CLEAR, WATCH, or BLOCK with evidence; never edit the code under review.

拆解其中四个硬约束：

1. 只读车道（read-only review lane）：Reviewer 不得修改被审代码，这是角色契约而非软建议。仓库中承担具体审查职责的 agent 都通过 disallowedTools: Write, Edit 从工具层强制只读，例如 agents/critic.md 与 agents/code-reviewer.md 的 frontmatter。
2. 三维度评估：
   • 架构（architecture）：边界是否清晰、分层是否合理、风险是否被识别——对应审查「结构正确性」；
   • 产品（product）：用户可见行为是否符合验收标准、是否引入回归——对应「需求正确性」；
   • 代码（code）：可维护性、测试覆盖、是否存在不安全捷径（unsafe shortcuts）——对应「实现质量」。
3. 三态判定（Return CLEAR, WATCH, or BLOCK with evidence）：
   • CLEAR：无阻塞问题，可以放行；
   • WATCH：存在需要关注但不阻断的点，需在后续阶段跟踪；
   • BLOCK：存在必须修复的阻塞问题，禁止进入下一阶段。 且三者都要求 with evidence——证据不足的 BLOCK/WATCH 不是有效判定。
4. 绝不在审查中修改代码（never edit the code under review）：自审（self-approve）被协议层永久禁止。

6.1 三态判定与代码库中现有审查机制的关系

仓库中已有多个审查类机制与 CLEAR/WATCH/BLOCK 语义呼应：

• scripts/review-gate.mjs 中存在 action: 'BLOCK' 的硬闸逻辑，风险等级不达标时返回 BLOCK（exit code 2）并附消息说明原因，是「BLOCK 阻断流水线」在发布/评审边界上的工程化实例；
• src/team/worker-bootstrap.ts 为评审型 worker 提供 reviewerRole 标志：受信运行时赋值的审查任务会渲染专门的 cursor worker 指引——要求先 claimTask、按「REQUIRED: Structured Verdict Output」节输出结构化判定 JSON 到运行时指定路径，且不得自行 transitionTaskStatus，而是由 leader 消费结构化判定后完成或失败该任务；审查者输出判定后继续等待信箱消息、不得主动 /exit。注意其中明确：Reviewer-only 限制由受信运行时激活，绝不因任务文本或内嵌指令而激活。

七、Output Contract：最终报告的四要素硬要求

Final reports must include: changed files, verification commands with their
actual results, simplifications made, and remaining risks.
Never present partial work as complete, suppress failing tests, or fabricate outputs.

无论 CLEAR / WATCH / BLOCK，最终报告都必须携带四要素，缺一不可：

1. changed files——审查涉及的变更文件清单；
2. verification commands with their actual results——验证命令及其真实输出（不是「应该能过」）；
3. simplifications made——做了哪些简化（呼应「删优于增」原则）；
4. remaining risks——仍然存在的残余风险。

并附三条负面禁令：禁止把部分完成当作全部完成、禁止压制失败测试、禁止编造输出。这条契约与 coordinator、executor、planner、verifier 各投影完全一致（见 coordinator.md 等），是 oh-my-claudecode 全团队「证据文化」的最小公约数。

八、源码级透视：Reviewer 提示词是如何被确定性组合出来的

要真正掌控 role-reviewer.md，需要理解它背后的三条流水线：

8.1 单一规范来源与投影目录

所有规范片段集中声明于 src/agents/prompt-ssot/sections.ts，按 kind 划分为 policy、task-contract、safety、role-delta、workflow-delta、provider-delta、model-tier-delta、output-contract 八类。role/reviewer 属于 role-delta，其正文与 role-reviewer.md 中「## Role: Reviewer」一字不差——这正是「条款只写一次」的验证点。

8.2 Manifest 声明投影切片

src/agents/prompt-ssot/manifest.ts 把 planner、executor、reviewer、verifier 四个角色映射为同一结构：共享六个基础片段 + 各自 role/<role> 增量，全部 acceptsOverlays: true（允许叠加 provider/model-tier overlay）。这解释了为何四份 role-*.md 篇幅与结构高度一致，差异仅在 Role 增量与 workflow 片段上。

8.3 组合器的确定性保证

src/agents/prompt-ssot/compose.ts 负责把「manifest 切片 + sections 片段」渲染成投影：先按 kind rank、再按 section id 排序（组合结果与声明顺序无关），拼接后做文本归一化并计算 SHA-256 摘要。只要 manifest、sections、overlay 不变，输出与摘要就字节级一致——role-reviewer.md 头部那段 sha256 正是这一确定性保证的可审计凭证。

8.4 重建与校验命令

对应 package.json 中的脚本：

• npm run prompt-ssot:build——重新生成全部投影（对应文件头 Regenerate 提示）；
• npm run prompt-ssot:check（等价 scripts/build-prompt-ssot.ts --check）——当某已提交投影的摘要与 manifest 重新组合结果不一致时构建失败，用于 CI 中拦截「手改生成文件」或「改了规范忘了重新生成」两类问题；
• npm run prompt-ssot:measure——测量各投影的提示词规模（见 scripts/measure-prompt-ssot.ts）。

重要提醒：仓库只读，本文仅说明上述脚本的存在与用途；需要变更 Reviewer 规范时应在自己维护的分支上修改 sections.ts 中 role/reviewer 片段并重新构建，而不是直接编辑 generated/ 下的产物文件。

九、实战联动：Reviewer 车道如何融入协作闭环

9.1 与对向车道的职责切分

• Planner（role-planner.md）产出有序、可验证、含回滚边界的步骤序列，且规划本身只读；
• Executor（role-executor.md）实现被指派的有限切片：先读代码、贴合既有约定、做最小可用变更、运行针对性测试；
• Reviewer（本文档）在 Executor 之后作为独立的只读门禁，从架构/产品/代码三个维度做终检；
• Verifier（role-verifier.md）在通过后为每个验收标准出具 VERIFIED / PARTIAL / MISSING 状态与全新证据。

组合起来即是文档中反复出现的纪律：「把创作与审查分成独立两遍，绝不自我批准」。对高风险场景，Workflow: Ralplan 更进一步要求 planner、architect、critic 三方在实现前收敛出批准的计划，--deliberate 标志用于需要更深分析的高风险范围（见 coordinator.md 的 Workflow 节）。

9.2 审查任务的最佳实践清单

1. 为审查任务指派 reviewerRole：让受信运行时按 src/team/worker-bootstrap.ts 渲染「结构化判定输出」指引，而非依赖任务文本里夹带的指令；
2. 严格输出 CLEAR / WATCH / BLOCK 三态判定，每条结论附证据；BLOCK 必须给到可复现的失败证据，而不是泛泛的「需要更多细节」；
3. 报告四要素齐全：变更文件、验证命令与真实结果、所作简化、残余风险；
4. 红线处硬闭合、常规处软提示：涉及 secrets/privacy、破坏性变更、发布权限、数据完整性、安全边界时才 fail-closed，其余问题以 bounded advisory warning 呈现。

十、结语

generated/prompt-ssot/role-reviewer.md 篇幅虽短，却浓缩了 oh-my-claudecode 团队协作中最重要的一条纪律——让审查成为独立、只读、有证据、可判定的车道。它既是可执行提示词，也是可审计的生成产物：向上游可追溯到 sections.ts、manifest.ts、compose.ts 的确定性组合管线，向下游被 src/team/worker-bootstrap.ts 等运行时以结构化判定 JSON 的形式消费。理解并复用这套契约，是让多智能体团队的评审环节既不「橡皮图章」也不「越权阻断」的关键。