code-review

代码审查

使命

针对所请求的范围，尽可能深入地开展审查。问题发现和覆盖范围证据是主要输出；赞许、风格偏好和宽泛的重构建议则是次要内容。

协调 Agent 负责范围、最终判断、去重、严重性评定和已保存的报告。子 Agent 只提供有限范围的分析；未经独立综合，不得将其结论直接复制到报告中。

必需资源

• 委派审查工作前，先阅读 references/subagent-orchestration.md。
• 根据 references/report-template.md 编写报告。
• 使用 python3 scripts/validate_review_report.py <report-path> 验证 generation 0。验证 generation 1 时，还需传入 --parent-report <generation-0-report> --parent-resolution <resolution-report> 参数。

硬性要求

• 开始实质性审查前，协调者必须根据基线、变更文件清单、差异规模和已知约束评估范围和风险。
• 只有在拆分工作不确定，或独立风险分析能显著改进计划时，才委派此项评估。根据覆盖收益和上下文共享成本选择专家；仅仅因为有工具可用，并不足以成为委派理由。
• 如果环境没有子 Agent 原语，记录 Subagent unavailable，并由协调者执行相同的评估流程。不得声称运行过实际上并未运行的子 Agent。
• 所有审查子 Agent 均须保持只读。不得编辑文件、暂存、提交、推送、重置、切换、变基或更改 Git 状态。
• 审查阶段须保持只读。如果用户也要求修复，先完成并冻结报告，再在现有实施授权范围内继续，无需另行请求。仅请求审查时，以报告作为最终交付。
• 所有报告都必须纳入审查链。冻结的初始范围使用 generation 0；只有在 receiving-code-review resolution 之后，才可对实施差异及受影响的执行链使用 generation 1。
• generation 1 为终止状态：编写报告后，将剩余问题交还用户或产品负责人，不得自动调用 receiving-code-review。之后的任何工作都需要用户明确请求，并开启新的 generation 0 审查链。
• 没有权威的预期行为依据时，不得将有争议的产品选择归类为 Blocker、Major 或 Minor。若产品意图尚未确认，应使用 Question。

范围与身份

1. 确定所请求的范围：工作树、暂存差异、提交范围、分支差异、拉取请求、文件集或粘贴的代码。
2. 未明确指定范围时，选择合理的最小范围。存在暂存变更时，优先审查暂存变更；否则将工作树与 HEAD 比较。
3. 精确记录基线和目标。有可用的提交 SHA 时，使用提交 SHA。
4. 创建审查链 ID，并记录 generation、触发原因、父级 resolution ID/路径和范围模式。审查前，generation 1 必须读取完整的父级 resolution。
5. 在可行时，根据基线、目标、变更路径和规范化差异哈希计算范围指纹。若无法计算，应说明原因。
6. 判断意图前，阅读需求、问题文本、PR 描述、设计说明、迁移内容、相关契约，以及已确定的父级 resolution 决策。
7. 冻结 generation 0 的范围。对于 generation 1，审查实施差异，以及其可能影响的调用方、被调用方、契约和执行链；不得重新展开完整的原始发现范围。
8. 不得悄然扩大范围。将无关上下文标记为辅助证据或后续事项，而不是当前审查链中的问题。

编排

1. 由协调者或有充分理由的只读评估者评估范围身份、差异清单、变更统计、涉及的子系统、已知需求和环境限制。
2. 记录结构化决策：Single reviewer 或 Parallel specialists，并说明理由、风险维度、拟定分工、重叠计划和验证需求。未使用评估子代理时，使用 Coordinator assessment - <reason>；协调者也可以担任单一审查者。
3. 除非有具体的新证据使决策失效，否则遵循该决策。记录任何偏离及其理由。
4. 并行审查时，分配范围明确且互不相同的职责。常见角度包括：
   • 正确性、状态、数据流和 API 契约
   • 安全、隐私、身份验证、权限和信任边界
   • 测试、回归、错误路径、并发和可靠性
   • 迁移、持久化、兼容性、集成、性能和运维
   • 框架或领域特定语义
5. 要求每位专家返回候选发现、覆盖范围、已排除的候选项、不确定性和证据指针。
6. 对每项可能纳入最终报告的候选发现，重新阅读相关代码和证据。明确解决冲突，并且只由协调者分配最终的 F#、T# 和 A# ID。

深度审查约定

当风险可能扩散时，审查范围应超出变更行。追踪到足以评估以下内容的程度：

• 调用方、被调用方、共享工具、适配器和其他入口
• 输入验证、授权、信任边界、机密信息、隐私和不安全的外部影响
• 状态转换、持久化、迁移、序列化、兼容性、回滚和数据丢失
• 重试、幂等性、顺序、缓存、并发、竞态、超时、部分故障和清理
• 公共 API、CLI、UI、生成输出、配置、依赖项和部署契约
• 正向、负向、边界、回归、集成和迁移测试覆盖
• 当运行时行为会实质影响判断信心时，通过有针对性且无破坏性的命令进行验证
• 需求和有意的行为变更，避免将预期变更误报为缺陷

接受一项发现前，先确立预期行为的依据：

1. 优先采用当前用户或产品负责人的明确决策和验收标准。
2. 其次采用公共契约、已批准的设计或迁移决策，以及安全、隐私、合规或数据完整性不变量。
3. 将测试、当前代码和历史记录视为行为证据，而非其本身具有产品决策权威。
4. 如果分歧涉及产品选择，且没有权威依据，则提出会影响审批的 Question，并附上解决标准，而不是报告为缺陷。
5. 在 generation 1 中，继承父级决议中的 Intentional、Disproved、Stale 和 Duplicate 决策。只有在相关代码、约束契约或实质性证据发生变化时，才重新审查相同的语义问题。记录 kind:<code|contract|evidence>; ref:<concrete source>; change:<concrete delta>；占位符引用或 None、unknown 等变更描述及模板文本，均不足以授权重新审查。

只有在能增强证据时，才使用搜索、历史记录、blame、运行时检查或有针对性的测试。lint、类型检查或无关测试通过，只能作为工程规范方面的证据，不能证明行为安全。

只有在每个已变更的审查相关区域或影响未知的区域都得到说明、重要候选项均已裁定且剩余盲点已明确时，才停止。

完整性约定

• 列出在审查范围内合理可发现的每一项独立问题，而不只是最高风险问题。
• 维护一份带有稳定 A# 区域 ID 的 Review Coverage Ledger。将每个有变更且与审查相关或影响未知的区域映射为：
  • Finding F#
  • Reviewed - no issue found
  • Not review-relevant
  • Not covered
• 为每个独立测试缺口分配稳定的 T# ID 和严重性。
• 为每个 F# 和 T# 分配规范语义问题键。发现项使用 behavior; entry=<semantic entry>; contract=<stable expectation>; effect=<terminal failure>，独立测试缺口使用 test-gap; entry=<semantic entry>; contract=<stable expectation>; gap=<missing coverage>。排除行号、报告本地 ID、生成过程和当前实现符号。将其指纹计算为 ifp-sha256:<sha256 of the exact UTF-8 issue key>，以便在不同生成版本中识别相同主张。
• 在 Subagent Candidate Adjudication 或证据附录中记录有意义的驳回或合并候选项。
• 如果上下文、凭据、运行环境、差异大小或其他限制导致无法完整覆盖，则将报告标记为 Incomplete，并指出确切的未覆盖范围。
• 绝不要将部分审查说成完整审查。

发现项与证据

按不同的故障模式、受影响约定、安全边界、数据风险或审批决策分别计为一项发现。合并同一缺陷的重复表现；对影响有实质差异的情况分别列项。

优先关注：

• 崩溃、结果错误、数据陈旧或丢失、可用性故障，以及边缘情况失效
• 用户可见、API、CLI、持久化、身份验证、权限、重试、顺序、缓存和集成方面的回归
• 注入、不安全反序列化、身份验证绕过、机密泄露、SSRF、XSS、CSRF、访问权限过宽，以及不安全的文件系统或依赖项使用
• 对高风险变更行为缺少测试，尤其是修复、权限、迁移、并发和故障相关行为
• 仅在可造成具体审查风险时关注可维护性

对于每项已接受的发现：

• 将主张与位置、行为路径、输出、缺失测试或覆盖缺口关联起来
• 区分已验证事实和推断
• 说明假设，并在证据不充分时降低置信度
• 在 Look here first 中恰好包含一或两个主要代码链接
• 记录提出该问题的审查者，以及协调者如何验证该问题
• 记录结构化的预期行为依据、规范问题键和已验证的语义问题指纹

不要臆造缺陷。即使结果干净，也必须提供完整的覆盖台账、最严重的盲点和验证记录。

严重性与建议

按报告模板中的定义使用 Blocker、Major、Minor 和 Question。

按以下顺序将未解决的发现项和独立测试缺口映射到建议：

1. 存在任何 Blocker -> Block。
2. 否则，存在任何 Major -> Changes requested。
3. 否则，存在任何可能影响审批的 Question -> Discuss。
4. 否则，存在任何与审查相关或影响未知的 Not covered 区域 -> Discuss。
5. 否则，存在任何 Minor -> Pass with caveat。
6. 否则 -> Pass。

对于未经证实的疑似阻断问题，应降低其严重性，而不是保留含糊其辞的 Blocker。不要将不会影响审批的好奇问题标记为 Question。

持久化与交接

• 始终使用规范的 code-review 报告契约，编写一份全新的 Markdown 报告。
• 生成唯一的报告 ID 和文件名。遵循现有的仓库报告约定；否则使用 tmp/reviews/YYYY-MM-DD-code-review-report-<random-id>.md。
• 切勿覆盖现有报告。
• 持久化范围标识、范围指纹、编排决策、专家分配、候选项裁定、发现、测试缺口、覆盖情况、证据和 Receiving Handoff 部分。
• 持久化审查链标识、代次、触发条件、父级审查及其解决情况、语义问题键和指纹、预期行为依据，以及继承结案项的核对结果。
• 将已完成的审查报告视为固定输入产物。在接收或实施期间不得重写；后续处置和代码更改应记录在单独的 receiving-code-review 解决报告中，并通过报告 ID 与原报告关联。
• 第 0 代报告可以已准备好进入 receiving-code-review，但 Automatic receiving permitted 为 No：就绪状态描述的是产物，而非用户授权。只有在报告已就绪且用户已授权继续时才使用 Yes；仅审查请求使用 No。第 1 代报告必须使用终止性交接，不得自动接收。
• 将每项非 Question 发现和独立测试缺口分别且仅分配一次至可执行或延期交接 ID。将每个 Question 和 Not covered 区域列入对应的开放 ID 字段。
• 运行验证器，并在声称报告已完成前修复所有错误。

工作流

1. 确定审查链标识、代次、触发条件、范围、基线、目标和最小差异清单。
2. 在协调者中评估编排，或在理由充分时委派评估。
3. 记录并执行单审查者或专家计划。
4. 构建语义差异清单和 A# 覆盖区域。
5. 追踪变更涉及的控制、数据、安全、持久化、集成和测试路径。
6. 在能显著提高可信度时执行针对性验证。
7. 收集候选发现和专家覆盖结果。
8. 根据每项候选内容的预期行为依据和继承结案项，独立验证、去重、质疑并分类。
9. 分配最终的 F#、T# 和 A# ID，以及语义问题指纹。
10. 根据未解决事项和覆盖情况得出建议。
11. 根据模板编写规范报告。
12. 运行 scripts/validate_review_report.py 并修正所有失败项。
13. 返回简短摘要，包含报告路径、建议、完成状态、严重性计数、编排模式和主要风险。

最终自检

• 报告记录了实际评估模式及其理由：协调者、委派评估者或不可用时的备用方案。
• 编排决策基于范围和风险，而非任意指定的 Agent 数量。
• 每项专家候选内容均已通过证据验证、驳回、合并或保留。
• 每个发生变更且与审查相关或影响未知的区域都有一个 A# 行。
• 每个 F# 和 T# 都有权威的预期行为依据，或明确标记为 Question，且各自具有唯一的语义问题指纹。
• 代次与交接方式一致：第 0 代可以允许接收；第 1 代为终止状态，并关联其父级解决报告。
• 每项索引发现都有一张对应卡片，且每个 Finding F# 区域均引用真实发现。
• 每个 Not covered 行都有理由和明确的后续步骤。
• 建议映射完全准确。
• 报告验证器通过。
• Git 状态未改变。