deep-review

深度审查

查找可执行的缺陷和改进建议，并完整记录所选代码块和项目规则。脚本负责发现、分区、制品组装和验证；模型负责提供适用性判断和基于证据的审查。保持源代码只读；将审查制品写入 <out>（默认为 .deep-review/<target>/）。根据此文件解析 <skill-dir>，并从被审查的仓库根目录运行捆绑命令。

契约

• PR 的文件总数或行数不设上限。每个所选代码块恰有一个缺陷责任方和一个润色责任方。两者默认采用较大的批次，每个任务 200 个文件 / 15,000 行变更，可通过 --max-cohort-files、--max-cohort-lines、--max-polish-files 和 --max-polish-lines 调整。超大文件会被切片，但不会丢失代码块。可选的 --max-context-lines N 准备预算会将通读整份文件的开销计入，同时保留所选内容。
• 每个缺陷都必须有因果证据；每条建议都必须有观察到的前提、具体改进和范围明确的修复。已调查但不予采纳的内容须保留在抑制记录中。不设配额；建议永远不会阻止 SHIP。
• 每条已应用规则都必须来自实际读取的内容，并记录原文、来源、适用范围和明确评估。根目录和嵌套指令须保留其适用范围和优先级。元数据是分类队列，而不是加载所有技能的指令。
• 相关检查器必须先运行，或复用针对相同冻结输入的证据。记录不可用的检查环节；抑制重叠的发现。切勿为了填补检查环节而安装工具。
• 工作区、规则证据和任务契约均已固定。仅复用契约未变的有效输出。覆盖缺失、证据过时和结果格式错误都会阻止完成。
• 仅在使用 --publish 或获得明确的会话授权时发布。产品修复不属于此技能的范围。

1. 准备

python3 <skill-dir>/scripts/prepare_review.py --out <out> \
  [--pr N | --base REF | --staged | --worktree] [--files p1,p2] \
  [--spec PATH] [--full] [--max-cohort-files N] [--max-cohort-lines N] \
  [--max-polish-files N] [--max-polish-lines N]

该辅助工具会创建清单、knowledge.md 和 decisions.template.json。检查清单摘要，确认 base/head 和文件选择正确，尤其是在变基之后。若选择结果为空，则以“无可审查内容”结束。对于 PR，使用清单中的诊断信息获取缺失的 head/base/历史记录，然后重试。

阅读 knowledge.md，而不是原始注册表。利用其中的元数据对路由规则分类；阅读适用的指令和所选技能章节。使用 cp <out>/decisions.template.json <out>/decisions.json 复制模板，然后仅编辑语义决策，同时保留指纹。使用简洁的来源 ID 或分组排除项；提供实际原因、精确的规则片段、变更意图和检查器证据。请阅读 context-pack.md — 决策文件，了解此输入契约，包括规则检查环节与视角的绑定。

python3 <skill-dir>/scripts/prepare_review.py --out <out> --decisions <out>/decisions.json

退出码 2 表示仍有待处理的决策：已应用技能的父项会在下一次编译时显示其引用路径。刷新的 decisions.template.json 已保留先前的决策和附加字段；将其复制覆盖 decisions.json，并编辑待处理条目。根据引用的路由条件进行评估。排除父项即可同时处理其依赖引用；若某条引用被仍适用的父项共用，则该引用仍待处理。缺少必需引用会阻止准备完成。

决策全部完成后，会编译生成 rules.json、context-pack.md、面向软件包的 plan.json、各任务契约和 jobs.json。不要编写准备脚本、手动枚举分区，也不要在分派任务前撰写操作指南。仅在存在真实语义边界时调整生成的分组。默认不执行批次扫描；只有存在具体的跨批次假设时，才使用 orchestration.md — 批次扫描。--spec 会自动添加一致性检查批次。

2. 审查

默认使用原生 Agent，最多并发 6 个。工作 Agent 只能收到渲染后的提示词：“阅读 <prompt> 并完成分配的审查；使用该提示词中的本地命令提交草稿。”在支持的情况下，不继承对话上下文（fork_turns=none）。工作 Agent 不会加载此技能、全局 jobs/manifest 文件或编排器引用。其任务约定包含所需上下文、规则、hunk ID、证据语法和输出格式。

工作 Agent 使用提供的草稿模板填写明确的评估，然后运行：

python3 <skill-dir>/scripts/run_jobs.py --out <out> --job <label> --submit

此操作仅验证该任务，并将 ID 展开为规范输出。缺失或无效字段会生成完整的本地诊断；请修复现有草稿。不要一概使用 clear/compliant，不要让工作 Agent 执行全局验证，也不要仅为重建 JSON 而重新调查。

只有编排器会在一批任务完成后运行全局门禁，或在恢复中断的轮次时运行：

python3 <skill-dir>/scripts/run_jobs.py --out <out> --validate-only

仅分派状态为待处理/无效的行，并使用其 prompt 字段：无效行已指向有针对性的修复提示词。重复使用有效输出。若反复失败却没有进展，应检查实际诊断，而不是循环发送相同的审查请求。如需执行 Workflow，请阅读 orchestration.md — Engines；如需使用非原生 --subagent，请阅读 subagent-runtimes.md。外部调用会消耗 compozy exec 额度；请保留用户选择的模型/effort。

3. 报告

全局验证以 0 退出后：

python3 <skill-dir>/scripts/merge_findings.py --out <out>
python3 <skill-dir>/scripts/render_review.py --out <out> [--rework "<structural rationale>"]
python3 <skill-dir>/scripts/render_html.py --out <out>

渲染器会在生成报告时，根据计划、意图和审查者摘要构建演练文档。它会根据缺陷判定 SHIP / FIX_BEFORE_SHIP / REWORK，保留建议/抑制项并写入状态。只有渲染成功后才陈述结论；包括数量、所有 Critical/Major 缺陷、覆盖范围和 review.html 路径。若有 ReportFindings 可用，请先列缺陷，再列建议。只有在更改呈现方式或解决报告诊断时，才阅读 output-contracts.md。

范围、配置与恢复

--base、--staged、--worktree、--files、--pr、--full 保留清单构建器的范围语义。工作树审查包含未提交/未跟踪文件，并始终执行完整审查。常规轮次会根据先前状态增量处理；--full 则请求完整轮次。--spec 接受文件/目录，也可以在决策中指定其他规范工件。

批次限制接受任意正整数，且绝不会截断 PR。准备阶段会在 prepare-request.json 中保留所选限制，以供决策阶段、恢复和刷新使用；再次传入某项限制，只会覆盖该设置。直接运行 build_jobs.py 会继承计划限制，并接受相同的四个批次标志。

仓库中的 .deep-review.yaml 键 path_filters、path_instructions、request_changes_workflow 会分别回退到 .coderabbit.yaml（reviews.*）。内置的生成文件/供应商文件/锁文件/快照排除规则仍然有效。路径说明的评审优先级最高，其次依次为最深层的适用项目说明、根目录说明、路由技能和经验。

不带 --refresh 重新运行准备步骤，可恢复固定输入。范围/来源发生变化时，需要使用 --refresh 并提供新的适用性证据；绝不要手动为旧快照背书。提供方阻断时，Runner 会以退出码 2 退出并生成 run-blocker.json；条件允许时，使用相同命令恢复。Runner/全局冻结以退出码 3 退出，表示输入已过时。无效输入以退出码 1 退出，需要修复工件，绝不能绕过覆盖检查。prepare-status.json、各作业状态和外部尝试日志会显示耗时，无需额外调用模型。

使用 --publish 时，请阅读 publish-github.md，并在本地渲染后执行其中的 GitHub 操作方案。当用户反驳某项发现时，请阅读 state-and-learnings.md 了解修正工作流。只有在证据/严重性判断不明确时才阅读 taxonomy.md；常规审查提示词已包含所需的语法。