# Deep Review

> 审查拉取请求或用户明确指定的代码差异；显式调用 /deep-review 或工作流要求本地正式评审时使用。

- Skill: `ben2pc/deep-review` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add ben2pc/deep-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ben2pc/deep-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ben2pc (https://skillmd.com/u/ben2pc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ben2pc/deep-review

---


# Deep Review

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

资料研究、规则冲突审计和技能适配不因出现“审查”一词而触发本技能。明确代码差异但没有拉取请求时，以用户指定的基准和目标版本收集等价材料，跳过拉取请求状态与身份检查。

先判断触发来源。用户明确只要求修改待评审状态时不自动启动审查；请求“跑到待评审”则按当前工作流完成适用的首次评审并交接，不自动循环修复。用户明确要求运行本地深度审查时直接执行。其他待评审请求：没有为当前拉取请求配置并实际运行的持续集成评审时，第一次本地深度审查直接执行；已有持续集成评审时，先询问用户是否还需要本地深度审查；是否存在有效的持续集成评审无法判断时也询问用户。

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

旧报告须识别其基准、头提交与覆盖的路径和维度；它只能证明对应版本的审查结果。当前版本按变化及其影响判断哪些证据仍有效、哪些维度需要补审，不把旧报告当作本版完成，也不机械重跑全部维度。补审仍遵守上述授权边界。

## Prerequisites

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

## 1. 收集审查数据包

运行 `gh pr view --json number,title,body,baseRefName,headRefName,baseRefOid,headRefOid` 与 `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 仓库回退当前目录，但只有用户明确确认这些文件可信时才执行；否则列为审查缺口。

### frontmatter 字段

项目审查者必须有合法 YAML frontmatter。主代理只解析元数据。

**必填：**

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

**可选：**

- `effort`：仅在需要覆盖默认推理投入时设置，取值须受当前运行时支持，不写死模型名。

任一必填字段缺失或非法（包括 `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

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

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

### Reviewer Output Contract

把以下输出契约原文放进每个审查数据包。它是所有内置、补充型和独立项目审查者共同遵守的外层格式；审查者文件只补充本维度在各单元格中必须说明的证据，不得改列、改章节名或退回自由列表。除模板中的章节外不要添加自由摘要、前言或结语。

阻断问题、非阻断问题和需要验证是每个审查者的固定核心章节，没有条目时也保留章节并写 `无。`。编号在单个数据包内按章节从 1 开始；主代理综合时会重新合并、排序和编号。来源使用第 3 节定义的标签；同一来源的条目相邻，多来源发现保留全部来源。置信度只允许写 `高`、`中` 或 `低`，表示审查者对证据链的判断，不代替主代理的修复建议。

架构观察仅由 `architecture` 审查数据包及其吸收的项目补充审查者输出；其他维度发现结构性根因时，仍按该维度的阻断、非阻断或需要验证报告。审查缺口仅在审查者因权威来源、权限、工具或证据不可用而无法完成本维度时输出；调度失败由主代理在综合阶段补充。任意审查者都可以输出有证据的亮点，但每个数据包至多一条。可选章节没有内容时直接省略。

```markdown
## Reviewer Result: <数据包来源>

### 阻断问题

| 编号 | 来源 | 位置 | 问题与影响 | 置信度 |
|---|---|---|---|---|
| 阻断1 | <来源> | `<file:line>` | <问题、触发条件与影响> | <高、中、低之一> |

### 非阻断问题

| 编号 | 来源 | 位置 | 问题与影响 | 置信度 |
|---|---|---|---|---|
| 非阻断1 | <来源> | `<file:line>` | <问题与具体维护成本> | <高、中、低之一> |

### 需要验证

| 编号 | 来源 | 位置或证据 | 缺失证据与风险 | 验证方式 |
|---|---|---|---|---|
| 验证1 | <来源> | <file:line 或证据源> | <缺少的证据及其影响> | <如何确认> |

### 架构观察

| 编号 | 来源 | 位置或证据 | 观察与长期成本 | 后续建议 |
|---|---|---|---|---|
| 架构1 | <architecture 来源> | <file:line 或证据源> | <不阻塞当前合并的架构观察> | <后续如何处理> |

### 审查缺口

| 编号 | 来源 | 缺口 | 影响 | 补齐方式 |
|---|---|---|---|---|
| 缺口1 | <来源> | <本维度无法完成的原因> | <对结论的影响> | <如何补齐> |

### 亮点

| 编号 | 来源 | 位置或证据 | 亮点 |
|---|---|---|---|
| 亮点1 | <来源> | <file:line 或证据源> | <有证据的亮点> |
```

## 6. 综合

主代理逐条复核审查者证据，按同一根因合并重复发现，同时保留所有来源。不要仅因置信度低就把条目移动到架构维度；证据不足但风险具体时进入“需要验证”，证据足够时按实际影响分类。

阻断与非阻断条目不展示审查者置信度。主代理必须结合权威需求、差异证据、当前拉取请求范围和修复成本，给出自己的处理建议与判断理由：

- `修`：建议在当前拉取请求合并前处理，并说明为什么收益与风险值得现在修改；
- `不修`：建议当前拉取请求不处理，并说明为什么不构成缺陷、超出范围或收益不足；
- 阻断问题只能建议 `修`。主代理若判断 `不修`，该条不得继续保留为阻断，必须根据证据重新分类为非阻断或需要验证。

主代理丢弃子审查者局部编号，在每个分类内按当前影响排序，保留全部来源，再连续编号。使用下方主报告格式，记录目标提交与实际覆盖范围；所有分类章节保留，空章节写 `无。`。

总判断按以下优先级生成：存在阻断问题时写“阻塞”；没有阻断但存在审查缺口时写“评审不完整”；没有前两者但存在需要验证项时写“需要验证”；其余写“可合并”，并在存在非阻断问题时注明数量。结论只表示审查判断，不执行修复或替用户批准合并。

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

```markdown
## Deep Review: PR #<n> — <title>
**结论**：<阻塞 | 评审不完整 | 需要验证 | 可合并> — <一句话理由>
**目标版本**：<基准提交与头提交>  |  **覆盖范围**：<本轮路径和维度；沿用证据注明对应版本>
**信号**：<标签>  |  **已完成审查者**：<列表>

### 阻断问题

| 编号 | 来源 | 位置 | 问题与影响 | 主代理建议与判断理由 |
|---|---|---|---|---|
| 阻断1 | <来源> | `<file:line>` | <问题与影响> | **修**：<判断理由> |

### 非阻断问题

| 编号 | 来源 | 位置 | 问题与影响 | 主代理建议与判断理由 |
|---|---|---|---|---|
| 非阻断1 | <来源> | `<file:line>` | <问题与影响> | **修**或**不修**：<判断理由> |

### 需要验证

| 编号 | 来源 | 位置或证据 | 缺失证据与风险 | 验证方式 |
|---|---|---|---|---|
| 验证1 | <来源> | <file:line 或证据源> | <缺少的证据及其影响> | <如何确认> |

### 架构观察

| 编号 | 来源 | 位置或证据 | 观察与长期成本 | 后续建议 |
|---|---|---|---|---|
| 架构1 | <来源> | <file:line 或证据源> | <不阻塞当前合并的观察> | <后续如何处理> |

### 审查缺口

| 编号 | 来源 | 缺口 | 影响 | 补齐方式 |
|---|---|---|---|---|
| 缺口1 | <来源或失败维度> | <缺失的权威来源或不可用证据> | <对审查结论的影响> | <如何补齐> |

### 亮点

| 编号 | 来源 | 位置或证据 | 亮点 |
|---|---|---|---|
| 亮点1 | <来源> | <file:line 或证据源> | <有证据的亮点，至多两条> |
```

## 7. 交回用户决定

单轮正式审查到报告为止。独立审查交回用户决定后续；已授权收敛目标的协调者消费报告，按原授权继续修复、验证和再次审查。新增产品或架构决定、对外沟通和跟踪事项仍须相应授权；修复后的定向验证本身不构成再次完整审查授权。

## Anti-patterns

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