deep-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. 综合

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

## 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 的项目审查者属于哪个宿主。
• 被吸收扩展命中、宿主未命中时直接跳过整个维度。
• 把低置信度问题塞进架构观察，隐藏其真实维度。
• 审查过程中顺手改代码、评论拉取请求或创建问题。