ce-code-review

代码审查 (Code Review)

利用动态挑选的审查者角色（Persona）对代码变更进行审查。通过分发职责边界明确的专家子 Agent（返回结构化 JSON），将最终的发现结果合并、去重并汇集成一份统一的审查报告。

环境初始化 (Setup)

在本次调用的开头、分发任何子 Agent 之前执行一次，并遵循其打印的指令 —— 除非这些指令与当前 Skill 本身关于“向用户提问”的规则相冲突（无论该规则仅适用于非交互模式还是全局适用；在此类冲突下以当前 Skill 的规则优先，不进行阻塞式提问）。在同一次调用中切勿重复运行；后续调用当前或其他 Skill 时会自行运行其各自的初始化。若当前未安装 Node 运行时，Skill 将按常规流程继续执行。

SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
NODE="$(for c in node nodejs; do command -v "$c" >/dev/null 2>&1 && "$c" -e '' >/dev/null 2>&1 && { echo "$c"; break; }; done)";
if [ -n "$NODE" ]; then
"$NODE" "$SKILL_DIR/scripts/context.mjs" || echo "context script failed; continue with the skill's normal behavior";
else
echo "no Node runtime; continue with the skill's normal behavior";
fi

使用场景 (When to Use)

• 提交 PR 之前
• 在迭代开发过程中完成某个子任务之后
• 需要对任意代码变更获取反馈时
• 可独立调用
• 可在更大规模的工作流中运行；当调用方需要 JSON 格式而非 Markdown 表格时，使用 mode:agent

产物根目录 (Artifact Root)

本 Skill 会自动读取 <root>/plans/ 下的 Plan 计划，扫描 <root>/solutions/ 下的经验积累（Learnings），并将解析后的根目录路径传递给 review-scope.py（以 --docs-root 形式）及其角色子 Agent。在首次拼接任何 <root>/ 路径或设置 --docs-root "<root>" 参数前，请先解析出 <root>（参考下方规则块），并在后续出现该占位符的所有地方进行替换。

<!-- ce-docs-root:start -->
在拼接任何产物路径之前，请先解析 CE 产物根目录 <root>。

• 读取 <repo-root>/.compound-engineering/config.local.yaml 中的 docs_root，若为空则继续读取 config.yaml；以首个非空值为准（其中 <repo-root> 通过 git rev-parse --show-toplevel 获取）。若均未配置，则 <root> 默认为 docs（与此前行为完全一致）。
• 校验 配置值：必须为相对于仓库根目录的相对路径，且经软链接解析后的真实路径须保持在仓库内部，既不能直接是仓库根目录，也不能在 .git/ 目录之下。校验失败时停止运行并抛出指出 docs_root 及非法值的错误 —— 绝不静默降级回退到 docs。
• 使用 <root> 作为唯一的产物存储位置：若目录不存在则创建；以 <root>/<subdir> 形式拼接本 Skill 专用子目录的各路径；严禁再重复读取 docs。
  <!-- ce-docs-root:end -->

执行主干流程 (Execution spine)

按顺序遵循以下边界步骤；参考文档仅提供细节支持，绝不得改变此顺序：

1. 解析审查 Diff 与意图：确定待审查的代码变更集及相关意图。
2. 加载角色目录并遴选名单：读取 references/persona-catalog.md，随后根据风险驱动策略挑选审查者名单（Roster）并探测适用的规范路径。在未加载该目录前，切勿挑选或分发任何角色。
3. 跨模型对抗节点（Adversarial Check）：若审查本地工作树时挑选了对抗性审查角色（Adversarial），必须在分发任何本地角色之前启动并持久化受许可的跨模型任务。调用本 Skill 即视为已授权使用其配置/白名单内的 Peer 路由（在向用户说明必要的接收方及代码出境提示之后）；不得二次要求用户确认，也不得仅因用户未单独重复授权而跳过该步骤。但是，若用户显式明确禁止外部审查，则该禁止指令优先。成功启动的 Peer 将替代本地对抗角色；只有在作用域、白名单、可用性、身份验证或启动遭遇实际失败时，才保留本地回退逻辑。
4. 并发分发本地审查者：在进行任何本地分发前，读取 references/dispatch-reviewers.md；若未加载则立即停止并先加载它。随后，按照宿主环境的活跃 Agent 上限，将实例化后的本地审查者名单作为前台并发批次分发 —— 在支持同消息并发调用的 Harness 中，通过单条消息派生多个关闭后台执行的审查者，并在汇总合成前收集所有审查者的返回（在类 Claude Harness 上进行单次阻塞等待；在异步 spawn_agent Harness 上进行多次非轮询式的收集等待）；若宿主不支持并发则降级为串行分发。严禁将本地审查剥离为轮询式的后台任务；跨模型 Peer 是唯一允许后台运行的任务，且须与本批次重叠并行。严禁使用 Shell 空指令（no-op）或唤醒轮询。
5. 汇总报告与校验：待所有审查者返回就绪后，读取 references/finish-review.md；若未加载则立即停止并先加载它。将 Peer 的结果合并进来，执行文档记载的 Finding 处理机制，运行参考文档指定的每一个校验器，最后才返回最终报告。切勿直接从审查者的原始产物中合成报告。必须完整填写 Actionable Findings（可操作问题）、Coverage（覆盖范围）及 Verdict（最终结论）等必填字段。当运行了 Peer 时，Coverage 必须记录其路由以及产物中字面量键值对字段：model_requested、model_actual、effort_requested、effort_actual、receipt_supported 和 independence_verified；绝不可将其简化为模型家族代号或模糊的“高推理能力”声明。在多 Agent 路径中，仅输出本 Skill 的报告，切勿同时调用 Harness 原生的 Findings/Reporting 工具。原生 Review 工具仅适用于显式的快速审查快捷路径（Quick Review Short-Circuit）。无参数的基础调用及 mode:agent 审查绝不应用修复；只有显式指定 apply:local 才能进入 Stage 5c 修复应用阶段。

阶段参考文档中附带的 Helper 契约为权威标准。请直接运行文档中说明的命令；除非文档命令确实因兼容性问题执行失败，否则不要私自查看 Helper 源码、正则匹配模型映射、干跑（dry-run）适配器或探查 --help 参数。

任务进度可视化 (Task Visibility)

对于多 Agent 路径，一旦解析出审查范围，在平台支持任务追踪（Task-tracking）功能时，应当展示一段基于执行主干流程导出的用户视角简要进度视图。进度应当追踪审查的阶段成果，而非展示具体的角色个体、初始化细节或工具调用过程；仅在条件触发闸门开启时才添加条件性任务，并在发生实质阶段变更时更新视图。若平台不支持任务追踪能力，直接以常规进度展示并输出最终报告即可，无需在对话框中人工伪造任务清单。

参数解析 (Argument Parsing)

解析调用时传入的参数以提取可选 Token。在将剩余文本解析为 PR 编号、GitHub URL 或分支名称前，先剥离所有已识别的 Token。

Token	示例	作用
mode:agent	mode:agent	仅输出报告：返回 JSON 格式而非 Markdown 表格，并跳过 Stage 5c 本地应用阶段（由调用方自行应用）。不影响审查者挑选、合并逻辑或作用域规则（详见输出格式）
mode:headless	mode:headless	mode:agent 的已废弃别名
mode:report-only	mode:report-only	已废弃 —— 直接忽略。原无产物模式；目前默认行为即为无需 Checkout 的纯审查模式
apply:local	apply:local	显式授权 Stage 5c 将校验通过的 Finding 修复应用到本地检出的代码树中。此参数代表授权而非输出模式；基础审查默认仍为仅输出报告。
base:<sha-or-ref>	base:abc1234 或 base:origin/main	指定当前检出分支的 Diff 基线（显式传参；跳过自动基线检测）
plan:<path>	plan:<root>/plans/2026-03-25-001-feat-foo-plan.md	用于需求校验的 Plan 计划文件路径（显式传参）。支持 Markdown 及 HTML 统一计划。
depth:full	depth:full	强制全量审查者名单 —— 跳过 Stage 3c 的小 Diff 简化路径，无论 Diff 大小如何均运行所有常驻角色。当用户明确要求深度/全面审查时使用（此为 Stage 3c 无法从 Diff 中自动推导出的唯一升级信号）。不改变条件挑选、合并或作用域。
depth:auto	depth:auto	默认 —— 通过 Stage 3c 自动匹配合适规模（对于简单、低风险、纯代码的 Diff 使用精简名单；其余情况使用全量名单）。
grouping:auto	grouping:auto	默认 —— 当 Finding 跨越不同关注点时，自动构建主题分类组（Stage 5 步骤 9b）
grouping:off	grouping:off	关闭分类组：不输出 Triage Groups 章节，JSON 中 triage_groups 为空
grouping:always	grouping:always	始终构建分类组，即使是小规模审查也不例外

分组仅影响呈现形式，而非运行模式。 grouping: 标记仅改变 Finding 在分类排查时的组织方式 —— 绝不影响审查者挑选、合并逻辑、作用域规则或 Stage 5c 的应用决策。

模式别名： mode:headless 会规范化为 mode:agent。同时传入 mode:agent 与 mode:headless 不属于参数冲突。

冲突参数： 当出现以下情况时，应停止运行且不分发审查者：

• 同时出现多个互斥的作用域选择器（例如同时传入 base: 和 PR 编号/分支目标 —— 因为 base: 意味“基于该基线审查当前检出的代码”）
• 除 mode:agent/mode:headless 这一别名对以外，同时出现多个不同的 mode: 标记
• apply:local 与 mode:agent 同时出现 —— 流水线交接时必须为纯报告模式
• 同时出现多个不同的 grouping: 标记（例如 grouping:off 和 grouping:always）

已废弃的 mode:autofix 不视为冲突 —— 直接忽略该 Token 并按正常流程继续运行（详见下文）。

遇到冲突时输出一行失败原因。在 mode:agent 模式下，返回 JSON：{"status":"failed","reason":"..."}。

运行原则 (Operating principles)

默认模式与 mode:agent 使用相同的审查流水线：

• 默认仅输出报告；绝不自动 Push。 基础调用 ce-code-review 仅生成 Finding，不会将修改应用到代码中。向本地写入修改需要显式传入 apply:local 或在调用 Prompt 中明确要求“应用/修复本次审查的 Finding”。mode:agent 绝不会修改代码树，即便它嵌套在后续会应用修改的工作流内部也是如此。在任何模式下均不得执行 git push、创建 PR 或提交 Issue/Ticket。
• 无需阻塞式交互。 严禁使用 AskUserQuestion、request_user_input、ask_user 或其他阻塞式提问工具。请从显式 Token、Git 状态、PR 元数据及上下文对话中推导出意图、Plan 和作用域。若存在不确定性，在 Coverage 或 Verdict 最终结论中予以注明即可 —— 切勿暂停中断来询问用户。
• 仅进行显式修改。 切勿擅自运行 gh pr checkout、git checkout、git switch 或类似的分支切换命令。传入 PR 编号、URL 或分支名称仅代表选择审查作用域，绝不代表获得了修改当前工作树的分支权限。若要审查 Feature 分支上的本地未提交工作，请自行切到该分支（或保持在该分支上）并传入 base: 或不传目标。
• 合理的默认行为。 对于 Untracked 未跟踪文件：仅审查已跟踪的变更，并在 Coverage 中列出排除的路径。对于 Plan 计划文件：若显式传入 plan: 则直接使用；否则从 PR Body 或分支关键字中保守推导。对于仅来自测试/可维护性层面的弱建议类 P2/P3 问题：根据 Stage 5 规则降级为 testing_gaps / residual_risks。
• 聚焦输出结果，掩盖内部机械细节。 展示给用户的文本应当紧扣审查本身：审查的对象（PR/分支）、包含的覆盖范围及各个条件视角的一句话原因、独立的跨模型审查及具体运行的模型、以及最终发现的 Finding。切勿在面向用户的文本中暴露本 Skill 的内部细节 —— 例如模型层级分配、作用域模式的原始代号（local-aligned/pr-remote）、将 Diff 暂存到磁盘、加载 Persona 角色文件、并行分发的账目记录、以及自身初始化的逐步叙述。使用用户能识别的术语（PR 编号、审查者的关注点、Peer 模型），而非内部管道实现。本原则决定了应当展示与隐去哪些内容，而非限制具体措辞 —— 请用自然的语气表达。

输出格式 (Output format)

调用方式	交付物
默认（Default）	仅输出报告的 Markdown（竖线分隔的 Finding 表格）+ 可操作问题摘要（Actionable Findings）
显式本地应用（Explicit local apply）	相同的 Markdown 报告 + 校验通过的本地修复 + 已应用修改章节（Applied 章节）
mode:agent	单个 JSON 对象（完整结构化数据）

<!-- truncated for translation batch; full body continues in source -->