代码审查 —— 多维度审计方法论

通过五个维度系统化地审计代码库发布版本，并采用并行子代理（subagent）委托机制实现深度验证。

灵感来源：现代代码审查分类学研究（Bavota & Russo 2015，《Four Eyes Are Better Than Two》）、reviewdog 的工具无关封装模式（tool-agnostic harness pattern）、Danger 的预审门控（pre-review gate）理念，以及社区在 AI 生成代码质量缺陷方面的实践经验。

核心原则

1. 以真实代码为依据，而非发布说明。 每一项发现都必须通过拉取实际源文件进行验证。唯一可接受的证据形式是 file:line 引用。唯一可接受的结论标签为：Confirmed / Mitigated / False Alarm。

2. 每个 Critical 级别问题均需“四眼验证”。 任何被归类为 Critical 严重级别的发现，必须由第二位独立子代理复核确认后，方可进入最终报告。该原则源自 Bavota & Russo（2015）提出的“Four Eyes”理念：多位评审者独立审视同一问题，相比单人评审可多发现 60% 以上的实际缺陷。详见 four-eyes.md。

3. 简洁性是一等公民维度。 AI 生成的代码常出现“过度设计”现象——仅需两个方法变更的问题，却产出数百行代码。始终追问：“该方案的复杂度是否与问题本身的复杂度相匹配？” 此维度灵感来自 Hacker News 与 Reddit 社区关于《2025 AI 代码质量现状》的讨论。

工作流程

阶段 0：预审门控（主会话中执行，耗时 <2 分钟）

在启动完整审计前，先运行以下快速检查。该设计受 Danger “自动化预审”理念启发。

1. PR/差异补丁大小检查：若变更超过 400 行，标记为高风险，并建议拆分
2. 缺失构件检查：是否存在 CHANGELOG 条目？API 变更是否更新了 README？Schema 变更是否附带迁移指南？
3. 文件级风险信号：是否存在已提交的 .env 文件、凭据或大型二进制文件？
4. 测试覆盖检查：本次变更是否包含或更新了测试？若差异超过 100 行但无任何测试变更，则标记为风险项。

输出：门控报告（pass/warn/fail） + 推荐的审计深度。

阶段 1：表层扫描（主会话中执行）

按顺序阅读以下材料——足以理解整体架构并识别潜在问题候选：

1. 发布说明 / CHANGELOG —— 作者声明的变更内容
2. README —— 项目目标、架构图、磁盘目录结构
3. ARCHITECTURE.md 或等效文档 —— 模块划分、API 合约
4. 目录树（通过 GitHub tree view 获取）—— 文件列表用于映射模块边界
5. 关键源文件 —— 入口点、核心状态机、关键路径（阅读约 3–8 个文件）

输出：一份含 10–20 个候选问题的清单，按维度分类：

• 安全性（SSRF、注入、认证、路径遍历、凭据泄露）
• 并发性与状态机（竞态条件、锁缺失、TOCTOU、状态污染）
• 用户体验与实现逻辑（功能语义、错误提示、恢复路径、访问控制）
• 测试质量（Mock 保真度、集成缺口、签名不匹配、覆盖率盲区）
• 简洁性与过度工程（复杂度与问题不匹配、不必要的抽象、AI-bloat 模式）

阶段 2：深度审计（通过子代理执行）

对每个非平凡维度，启动一个隔离的子代理。每个子代理须：

1. 通过 web_fetch 拉取所有相关源文件 —— 绝不依赖文档推断
2. 基于实际代码逐条验证每个问题 —— 必须引用具体行号
3. 构建漏洞利用场景（安全性）或 竞态时间线（并发性）
4. 返回结构化发现结果，包含：结论 / 严重级别 / 源码证据 / 风险描述 / 修复建议

详见 subagent-templates.md 中的精确提示模板。
详见 audit-dimensions.md 中各维度专属的问题探针（question probes）。

模型使用指引：所有子代理应使用相同模型，以确保判断一致性。对于复杂审计任务，优先选用高推理能力模型。

阶段 3：四眼交叉验证（仅限 Critical 级别问题）

对子代理判定为 Critical 的每一项发现：

1. 启动一位 第二位独立子代理（聚焦不同维度），使用完全相同的原始问题提示
2. 若双方均确认 → Confirmed。该问题将进入最终报告，并附带 👁️ Four-Eyes Verified 标识。
3. 若双方结论不一致 → 在报告中标记为 “Disputed”，并同时引述双方结论。
4. 若第二位子代理判定为 Mitigated/False Alarm，而第一位判定为 Critical → 以第二位结论为准。但需将双方结论均保留在附录中。

阶段 4：综合汇总（主会话中执行）

待全部子代理报告返回后：

1. 合并发现结果 —— 跨维度去重，重新校准严重级别
2. 构建摘要表格 —— 列出全部问题，含结论 + 严重级别 + 所属维度 + 根本原因
3. 构建优先级矩阵 —— 从 P0（立即中断一切）至 P5（锦上添花），标注预估工作量与影响范围（blast radius）
4. 撰写执行摘要 —— 整体质量评估 + 前三项关键行动项
5. 添加简洁性评分（Simplicity Score） —— 主观打分（1–5 分），评估代码库复杂度是否与其问题域匹配。5 分 = 优雅简洁；1 分 = 严重过度工程。

详见 output-format.md 中的表格与 emoji 使用规范。
详见 severity-rubric.md 中的严重级别分类规则。

关键启发式规则

安全扫描启发式规则

• 每个 URL 请求路径均须检查 SSRF 风险：追踪用户输入 → URL 解析 → DNS 解析 → HTTP 请求 → 重定向处理 → 响应读取全过程。任一环节跳过 IP 校验即标记为风险。
• 每个子进程调用均须检查注入风险：是否启用 shell=True？是否将用户可控字符串拼接到命令中？文件路径是否经过净化？
• 每个外部 API 调用均须检查凭据泄露风险：令牌/密钥是否被记录？错误消息是否包含请求体？

并发性扫描启发式规则

• 针对每个 .json / .jsonl 写入操作：检查是否采用 tmp-rename 原子模式或 flock。未使用二者之一的直接覆写即为缺陷。
• 针对每个 load → modify → save 模式：检查整个块是否受锁保护。若 load 发生在锁外，则构成 TOCTOU 缺陷。
• 针对每个状态机状态迁移：检查两个并发事件是否可能同时观测到相同的“之前”状态并各自推进。若是，则存在状态污染风险。
• 针对每个仅追加日志（append-only log）：验证 flock(LOCK_EX) 是否覆盖完整追加操作。

UX/逻辑扫描启发式规则

• 针对每个特性开关/模式（feature flag/mode）：追踪所有分支路径。“mode=review-only” 是否真正阻止了非 review 类操作？切勿轻信命名，务必验证代码逻辑。
• 针对每个错误消息：以终端用户视角通读。是否既说明了问题所在，又提供了明确修复指引？若仅显示 “X failed”，则标记为风险。
• 针对每个多步工作流：是否存在撤销/回退/重访路径？若无，则标记为风险。
• 针对每个访问控制检查：关注“未检查项”。群组聊天是否强制要求 @-mention？是否存在速率限制？

测试质量启发式规则

• 签名错配的 Mock：若测试通过 monkeypatch 替换 call_llm，且 fake 实现接收 **kw 并读取 kw.get("old_param")，则无法捕获生产代码中参数名改为 new_param 的变更。此类情形需标记。
• CI 中缺失集成测试：若 CI 仅运行带 Mock 的单元测试，且无端到端冒烟测试（end-to-end smoke test），则标记为风险。

简洁性与过度工程启发式规则（新增 — v1.1.0）

• AI-bloat 检测：本次变更是否为本应仅用 1–2 个方法即可解决的问题，引入了新服务类、后台工作者或框架依赖？（灵感源自 HN 社区“批量处理 = 2 个方法，而非 200 行代码”的典型案例。）
• 缺乏合理性的抽象：代码是否在直接调用已足够的情况下，引入了接口、工厂或依赖注入？对每一层抽象，均需追问：“此抽象当下解决了哪个具体问题？”
• 死代码或“过度预留”：是否存在未被任何现有功能使用的代码路径、配置选项或扩展点？
• 配置泛滥：本次变更是否新增了配置键、环境变量或 CLI 标志？每个新增项是否均有真实用例支撑？
• 复制粘贴检测：是否存在可提取为公共逻辑的 >10 行重复块？需双向标记：缺失 DRY（重复未抽取） AND 强制 DRY（两处副本演化路径不同却强行共用）。

反模式（应避免）

• ❌ 仅依据发布说明提交问题（必须始终对照源码验证）
• ❌ 盲信 docstring 描述而不核查实现逻辑
• ❌ 使用 “I think” / “probably” / “seems like” 等模糊表述 —— 每一项发现要么是 Confirmed，否则就不算发现
• ❌ 将严重级别留为 “TBD” —— 必须立即依据 severity-rubric.md 进行分类
• ❌ 在正文叙述中提及问题，却未将其录入结构化输出表格
• ❌ 未经四眼交叉验证，即采信单个子代理的 Critical 判定

工具链兼容性

本能力旨在 协同 现有代码审查工具工作，而非替代它们。推荐技术栈如下：

预审门控（阶段 0）承接 reviewdog/SonarQube 可覆盖的部分，避免将子代理资源浪费于风格类问题。子代理专注处理静态分析 无法识别 的深层问题。