---
name: deep-review
description: "当用户要求审查拉取请求、执行 /deep-review、将拉取请求标记为待审（Ready for Review），或请求正式 / 全面代码审查时触发。"
---

# Deep Review

多维度拉取请求审查调度器。主代理负责收集原始材料、按风险路由和综合结果；每个审查维度在彼此隔离的全新上下文中独立判断。

先判断触发来源。用户明确要求运行本地深度审查时直接执行。若只是将拉取请求标记为 Ready：没有为当前拉取请求配置并实际运行的持续集成评审时，第一次本地深度审查直接执行；已有持续集成评审时，先询问用户是否还需要本地深度审查；是否存在有效的持续集成评审无法判断时也询问用户。

确定需要本地审查后，再检查当前任务、拉取请求正文或讨论、已归档记录中是否已有可识别的正式审查记录。已有记录时，用户明确要求再次审查则直接执行，代理主动建议重跑则先询问用户。记录彼此冲突或无法判断时询问用户。不要因为修复了上一轮发现就自动开始下一轮深度审查。

## Prerequisites

- 已确定目标拉取请求和基准分支，`gh auth status` 正常。
- 正式审查面向 Ready 拉取请求；Draft 只做用户明确要求的早期反馈。
- 找到本轮权威需求来源；缺失时仍可审查其他维度，但必须把需求符合性标记为不完整。

## 1. 收集审查数据包

运行 `gh pr view --json number,title,body,baseRefName,headRefName` 与 `gh pr diff`，并读取：

- 当前对话里用户对本任务的原始要求和最新明确决定；
- 与本分支相关的 `docs/specs/`、`docs/long-running-specs/`、`docs/worklog/`、任务或问题；
- 仓库指令以及本次涉及的 `docs/rules/`；
- 原始差异与必要的未改动上下文。

提交信息、拉取请求里的实现理由和实现代理的自主决定可以帮助定位，但不是需求权威来源，不能覆盖用户或已确认契约。

## 2. 按事实与风险表面分类

标签可以多选，不使用统一的“平凡 / 非平凡”二分替代判断：

| 标签 | 命中条件 |
|---|---|
| `executable-behavior` | 生产代码、运行时配置、schema、数据转换、命令或其他会改变执行结果的差异 |
| `tests` | 新增或修改测试、测试工具、夹具或测试规则 |
| `maintained-code` | 需要长期维护且存在实质逻辑、结构或接口变化的代码；机械生成物和纯格式不算 |
| `security-sensitive` | 信任边界、身份与权限、秘密、外部输入、文件或网络、支付、隐私数据、代理工具执行能力 |
| `ui` | Web、移动端、桌面端、终端交互或命令行用户体验 |
| `performance-sensitive` | 热路径、大数据量、高频或并发路径、资源预算、第三方或模型调用成本 |
| `architecture` | 模块或组件边界、依赖方向、公共接口、领域职责、持久化模型或迁移方式发生实质变化 |
| `agent-extension` | 技能、插件清单、市场清单、代理、钩子、模型上下文协议配置、`AGENTS.md` 或 `CLAUDE.md` |

一行修复仍可能命中正确性、测试或安全；新增普通文件本身不等于架构变化；纯文档也可能改变权威契约并触发需求与文档审查。

## 3. 发现并校验审查者

内置审查者位于 `references/reviewers/`。主代理只读取每个文件的 YAML frontmatter 做编排，把文件**绝对路径**交给审查代理，由审查代理自读正文。若执行环境无法解析仓库绝对路径，才内联该文件正文。

项目审查者位于 `docs/rules/review/*.md`。用 `git rev-parse --show-toplevel` 定位仓库根，同时从受影响路径向上查找更近的 `docs/rules/review/`；两层都读取，冲突时子包级优先。正式拉取请求审查只执行**基准分支的可信版本**。头分支新增或修改的项目审查者仍作为差异交给 `skill-plugin-quality` 审查，但本轮不执行，合并后才影响后续审查。非 git 仓库回退当前目录，但只有用户明确确认这些文件可信时才执行；否则列为审查缺口。

项目审查者必须有合法 YAML frontmatter。主代理只解析元数据，并校验全部必填字段：

- `name`：kebab-case，且与文件名一致；
- `best_for` 与 `value`：非空字符串；
- `extends: <内置审查者名>`：作为宿主维度的项目专属补充；或 `extends: standalone`：作为内置维度没有覆盖的独立维度；
- `trigger`：`always` 或当前路由表支持的一个 `tag:<标签>`；
- `reasoning`：`flagship` 或 `workhorse`；
- `tools`：只包含 `Read`、`Grep`、`Glob`、`Bash`，且至少包含 `Read`。

任一必填字段缺失或非法（包括 `extends` 指向不存在的宿主），都不做正文语义猜测，也不回退读取旧 `## Metadata`；将该文件列入“审查缺口”。与内置审查者重名时仍必须显式声明宿主或 `standalone`。

被吸收的项目审查者与宿主组成一个数据包。**宿主默认条件或任一项目扩展的 `trigger` 命中时，都运行宿主**，避免项目规则因宿主默认条件未命中而静默失效。每个数据包显式携带来源标签：仅来自宿主时写 `(宿主名)`；项目补充产生的发现写 `(宿主名 / 项目审查者名)`；独立审查者写 `(项目审查者名, standalone)`。补充型审查者继承宿主的输出契约，不自行改变字段。

使用 `reviewer-creator` 创建或修正项目审查者。

## 4. 路由

| 审查者 | 触发条件 |
|---|---|
| `spec-conformance` | 始终执行 |
| `docs-sync` | 始终执行 |
| `correctness` | `executable-behavior` |
| `test-quality` | `executable-behavior` 或 `tests` |
| `code-quality` | `maintained-code` |
| `security` | `security-sensitive` |
| `ux` | `ui` |
| `performance` | `performance-sensitive` |
| `architecture` | `architecture` |
| `skill-plugin-quality` | `agent-extension` |

`correctness` 同时覆盖正常、边界和失败路径，不再单独分派鲁棒性审查者。项目独立审查者按自己的合法 `trigger` 路由。

## 5. 独立执行

每个维度必须在**全新、干净的上下文**中运行：

- 不继承实现会话、当前对话历史或先前审查会话；
- 不使用 `resume` / `continue`，也不复制父上下文；
- 只接收目标元数据、原始差异、权威需求、适用项目规则、审查者文件路径和下面的统一约束；
- 默认使用平台内置的干净上下文 Agent；
- 只有用户明确要求使用独立进程的非交互式 Agent 调用时，才允许改用外部 Agent；跨模型覆盖、缺少细粒度权限控制或其他平台能力差异都不能自行触发外部调用；
- `reasoning: flagship` 用当前平台最强推理档，`workhorse` 用下一档；尊重审查者显式 `effort`，没有时不额外写死投入档位。

frontmatter 的 `tools` 是审查者申请的最大权限，不是提示词建议。实际权限取“审查者 `tools`、主编排只读策略、运行时可执行限制”的交集。

内置 Agent 继承主编排的只读策略，并通过平台原生隔离与权限边界运行；宿主提供任务级只读模式时必须启用。宿主支持逐 Agent 的允许列表、禁止列表或只读沙箱时，应当用这些机制进一步收紧权限；缺少逐 Agent 的细粒度工具允许列表，不能切换到外部 Agent，也不能停止内置评审。下面的 Reviewer Must-Not Preamble 仍作为审查任务契约。

只有用户明确要求的外部调用才需要额外验证进程级只读边界。外部进程若无法强制只读或阻止外部写入，不启动该外部调用并记录审查缺口，不能用自然语言承诺冒充权限边界。

不可信头分支或来源无法判断时按不可信处理：可以读取差异、源码和持续集成证据，但不执行该头分支的测试、构建脚本、安装脚本或二进制。需要运行证据时优先引用现有持续集成结果；没有可信证据则列入“需要验证”。只有仓库策略或用户明确确认头分支可信，并且执行环境移除秘密、限制外部写入后，才允许 `Bash` 运行无外部副作用的验证。

并行执行彼此独立的只读审查。只有超时、限流或代理启动失败等**明确的瞬时失败**，才用新的干净上下文重试一次。无效元数据、权限不足、路径不存在等永久错误直接记录为审查缺口；多个维度出现同一共享故障时停止继续重试。不能宣称未完成的维度已经通过。

### Reviewer Must-Not Preamble

把以下约束原文放在每个审查数据包开头：

- 不按严重度或置信度预过滤；报告范围内所有发现，由综合阶段排序。
- 不修改代码、创建问题、提交评论、批准设计或执行其他外部写入。
- 可以给出具体修复方向和验证方式，但不要编写补丁或自主展开完整替代设计。
- 必须重新检查本次差异，即使相同行以前通过过审查。
- 只对本维度有证据的问题下结论；缺少运行、视觉、负载或权威来源时明确写为需要验证。

## 6. 综合

按同一根因合并重复发现，同时保留所有来源。不要仅因置信度低就把条目移动到架构维度；它仍属于原审查维度，只是进入“需要验证”。

```markdown
## Deep Review: PR #<n> — <title>
**Signals**: <标签>  |  **Reviewers**: <已完成列表>

### Blocking issues
- [ ] <file:line> — <问题与影响> — [severity: blocking] — [confidence: high|medium|low] (<来源>)

### Non-blocking suggestions
- [ ] <file:line> — <问题与影响> — [severity: non-blocking] — [confidence: high|medium|low] (<来源>)

### Needs validation
- [ ] <file:line或证据源> — <缺少什么证据、如何确认> (<来源>)

### Architectural observations
- <不阻塞当前合并、但值得进入架构设计或长期治理的观察>

### Review gaps
- <失败的维度、缺失的权威来源或不可用证据；没有则写 None>

### Strengths
- <至多两条有证据的亮点>
```

Blocking 包括会造成错误行为、安全问题、契约或测试破坏、未满足权威要求、实质性未授权范围扩张，以及对仍有效设计的高风险偏离。Non-blocking 是有具体维护成本但不阻止合并的问题。Needs validation 只用于已有权威来源或具体风险、但缺少运行、视觉或负载证据的情况；缺少权威需求来源、维度无法执行或证据源不可用属于 Review gaps。同一缺口不要同时放进两节。

## 7. 交回用户决定

正式审查到报告为止。是否修复、如何分组、是否创建跟踪事项、是否重新设计和何时再次深度审查，均由用户决定。修复后的定向验证不等于自动触发第二次完整审查。

## Anti-patterns

- 复用实现上下文或上一轮审查会话，削弱独立判断。
- 主代理读取全部审查者正文再转发，浪费主上下文。
- 因差异很小就跳过正确性或测试审查，或因新增文件就触发架构审查。
- 让实现者理由覆盖用户原始要求，或在缺少需求来源时输出“符合规格”。
- 猜测无合法 frontmatter 的项目审查者属于哪个宿主。
- 被吸收扩展命中、宿主未命中时直接跳过整个维度。
- 把低置信度问题塞进架构观察，隐藏其真实维度。
- 审查过程中顺手改代码、评论拉取请求或创建问题。