requesting-code-review git:20260929.4be24eeA

Immutable. This exact content never changes and is served at /api/v1/blob/690d908d3d910145.

---
name: requesting-code-review
description: 用户要求审查当前代码差异或 PR 时使用，默认只读；处理已收到的评审意见用 receiving-code-review。
compatibility: 本地差异审查需要 git。读取 GitHub PR 或发布评审需要可用的 GitHub 连接器或已认证的 gh CLI。
---

# 系统性代码审查

## 边界

- 审查当前本地差异或指定 GitHub PR，默认只分析和报告。
- `receiving-code-review` 处理别人已经给出的意见。
- 审查阶段不修改文件、不提交、不推送；用户已明确授权后续工作时，审查完成后继续对应步骤。
- 发布远端评审仍须用户明确要求；同一范围内已有授权时不重复请求。
- 不要求特定客户端插件。GitHub 连接器可用时优先使用，否则回退 `gh`；两者都不可用时仍可审查本地差异，远端操作明确报告未执行。

## 1. 固定审查快照

先确认仓库、工作区和审查范围：

```bash
git rev-parse --git-dir
git status --short
git branch --show-current
git log --oneline -10
```

PR 模式通过当前可用的 GitHub 能力读取编号、基准分支和来源分支、状态、更新时间、完整差异和检查。本地模式读取 `git diff HEAD` 或明确的 `<base>...HEAD`。记录实际范围，不基于旧差异或截断差异块下结论。

完整差异、逐文件覆盖、可信上下文、行号定位和反证规则遵循 [评审证据协议](references/evidence-protocol.md)。标准或深入审查先执行 [范围与完整性预判](references/review-preflight.md)。

## 1.1 场景契约与验收范围

如果变更目录或目标项目已有 `test-scenarios.md`，在深入审查前读取它，把它当作本次行为范围和验收标准的输入，而不是把测试数量当作覆盖证明。

检查：

- 每个受影响的行为是否能映射到场景 ID；
- `covered` 场景是否有真实测试命令、日志、运行结果或其他证据；
- `skipped` 场景是否说明原因、影响和后续动作；
- P0/P1、错误路径、兼容性、权限和人工 E2E 场景是否被遗漏；
- 实现、测试和场景契约之间是否出现互相矛盾的预期。

没有场景契约时，不要为了补文档而擅自创建文件。对于非平凡或行为变化的差异，在摘要中记录 `scenario contract: none`，将其作为覆盖与验收缺口，而不是自动判定为代码缺陷。

审查仍然是只读流程；场景状态和证据的补充由实现者或用户授权的后续步骤完成。

## 2. 确定深度与专项

- 快速：100 行以内且 1-5 个文件
- 标准：100-500 行，或 6-10 个文件
- 深入：500 行以上、10 个以上文件，或涉及认证、支付、数据写入等高风险路径

只根据本轮变更加载专项：

- 通用正确性、边界、错误处理、测试与复杂度：[代码质量](references/code-quality.md)
- 所有审查都做轻量复杂度检查；标准、深入审查或用户明确关注简化时，读取 [简化审查](references/simplification-review.md)
- 明确热点、I/O/网络放大、锁或分配风险：[性能](references/performance.md)
- 信任边界、鉴权、输入或密钥风险：[安全](references/security.md)
- 行为、API、配置或示例变化：[文档](references/documentation.md)
- `.go` / `go.mod`：[Go](references/go-specialist.md)
- `.java`：[Java](references/java.md)
- `.py`：[Python](references/python.md)
- CI、YAML/JSON 配置或依赖清单：[CI 与配置](references/ci-config.md)

TS/JS 变更执行轻量语言检查，不因仓库存在某语言就加载无关清单。

## 3. 架构分路

用户明确要求架构评审，或差异改变模块分层、公共接口、适配器或中间件、状态或任务生命周期、存储、跨服务调用、权限、错误体系、并发与资源管理时，加载 [架构审查](references/architecture.md)。

架构结论必须基于当前差异和必要相邻实现。区分必须修复与可选优化，不把理想化分层、个人偏好或未触及历史问题包装成缺陷。

## 3.1 简化审查

每次审查都检查当前差异是否增加了可以删除的概念、分支、状态、层级或依赖。标准、深入审查或用户明确要求评估复杂度时，按 [简化审查](references/simplification-review.md) 完成专项检查。

简化建议必须落到当前代码：指出复杂度来源，给出适配现有类型和调用方式的替代实现，并说明如何验证错误语义、调用顺序、副作用和兼容性不变。只能描述“可以更优雅”或无法通过当前接口实现的方案，不作为 finding 输出。

## 4. 证据过滤与汇总

对每个候选 finding：

1. 读取定义、调用方、配置和测试等必要上下文；差异块不足时查真实代码。
2. 找能推翻关键事实的反证，有直接反证就删除。
3. 确认问题由当前变更引入或暴露，并定位到当前快照最小连续范围。
4. 内部评估置信度：`80+` 才作为问题；`50-79` 放入待确认；低于 50 不输出。
5. 按文件和根因去重，再按 P0/P1/P2 排序。

若要指出回归由哪个提交或 PR 引入，先用 `git log -S/-G`、`git blame` 和关联记录定位候选，再核对该提交的父提交与实际差异是否改变了相关行为。浅克隆、历史裁剪或缺少父提交导致无法核实时，写明“来源未确认”，不要仅凭 blame、提交标题或时间归因；区分代码作者、PR 作者与合并者。

简化候选还需通过可用性检查：替代方案能在当前依赖、类型和接口下实现；示例覆盖关键分支与错误路径；验证命令能够证明行为保持不变。缺少其中任何一项时，先补充上下文或把它降为待确认问题。

对影响范围较大的变更，找出“该变更安全所依赖的一个关键事实”，并尽量用真实代码、最小脚本或针对性测试证明它。只能从源码推理或无法运行验证时，明确标为待确认，不把未证明的安全假设写成结论。

判断兼容性时，以 PR 目标分支在本次变更前已有的行为、数据和调用方为基线。若接口、配置或功能由本 PR 首次引入，同一 PR 内对它的调整不算破坏性变更，也不要求兼容 PR 的中间版本；按最终快照检查正确性、用法和文档。若调整同时影响基线已有的行为、数据或调用方，仍按实际回归评估。

对可能改变开发者或既有功能使用方式的差异，额外检查环境变量和 secret 读取、端口与网络、必需脚本、构建入口、feature gate 和内部权限条件。研究尚未完成时保留未确认项，不用条件猜测替代对后端、调用方或 PR 讨论的核实。

测试相关差异额外检查：

- 关键主流程、失败路径、边界输入、兼容性、权限和并发/异步状态是否有与风险匹配的验证；
- 新增或修复的 bug 是否有可复现的回归场景，而不是只增加无关覆盖率；
- 测试是否依赖执行顺序、共享状态、未提交事务、固定资源名或外部环境；
- 删除、收缩或改写测试时，原有关键约束是否仍被保留；
- 单元测试使用 mock/fake 时，集成/E2E 是否仍覆盖真实协议、数据和最终状态；
- 测试通过、编译通过或中间资源状态是否被错误地报告成完整运行面验证。

严重度：

- P0：确定的正确性、安全或严重并发缺陷
- P1：健壮性、关键测试缺口或明确性能退化
- P2：有实际维护成本的设计、文档或规范问题

不为凑数量报告问题。默认检查是否存在可删除的抽象、依赖和配置层，但安全校验、错误处理、数据保护、可访问性和用户明确需求不算无效复杂度。

## 5. 发布评审

只有用户明确要求把结果发布到 GitHub 时：

1. 完成所有适用检查和去重后再发布，避免中途制造多次通知。
2. 使用当前可用的连接器；不支持写入时回退 `gh api`。
3. 只发布一次不阻塞合并的 `COMMENT`，不擅自使用 `REQUEST_CHANGES`。
4. 发布后读回评审，验证目标 PR、正文和事件类型。
5. 没有远端写能力时输出完整评审正文和人工执行说明，不声称已经发布。

## 输出

```text
## 问题
[P0/P1/P2] <标题> - <文件:行> [置信度: 90]
证据: <触发条件、当前代码和影响>
建议: <最小可执行修复>

## 待确认问题
- <缺少的关键证据>

## 可行的简化（存在时才输出）
[P2/建议] <标题> - <文件:行>
复杂度来源: <多余概念、分支、状态、层级或依赖>
替代实现: <适配当前代码的代码片段或具体步骤>
行为证明: <保持的语义与验证方法>

## 摘要
- diff 快照：<range>
- 文件覆盖：<已审查 / 上下文 / 跳过 / 失败>
- 范围与需求：<结论>
- 场景契约：<path / none>; 覆盖：<结论>
- 可拆分性与文档债务：<结论>
- 架构专项：<未执行或基于证据的结论>
- 发布：<未请求 / connector / gh / 未执行>
```

没有高置信问题时明确写“未发现明确问题”，并说明验证和上下文边界。

## 统一约束

- 验收标准：遵循 `../_shared/common-acceptance.md`
- 场景契约只作为审查输入；没有用户授权，不在审查流程中创建或修改它。