code-review

代码审查

目标

基于证据，找出变更代码中的高影响缺陷。优先关注正确性、安全性、数据完整性、Shell/配置安全性和回归问题，而非风格方面的小问题。

参数

• 路径、模式、提交/范围或范围描述：用于范围解析步骤 2。
• --fix：先在内部整理问题，按严重性顺序应用建议的修复，然后生成一份最终报告，并按验证部分进行验证。不要单独输出修复前的报告。
• --with-profile <name>：按名称或文件名强制启用可选领域配置（例如 --with-profile shell）。可重复使用。
• --skip-profile <name>：按名称或文件名跳过可选领域配置（例如 --skip-profile naming）。可重复使用。如果 --with-profile 和 --skip-profile 指定了同一配置，则以跳过为准。
• 默认：报告问题，并等待确认后再编辑。

范围解析

解析一次范围，然后在本次运行的其余阶段将其视为固定范围。

1. 验证仓库上下文：执行 git rev-parse --git-dir。如果失败，则停止并告知用户从 Git 仓库中运行。
2. 如果请求指定了目标——文件路径/模式、提交/范围、自然语言描述的子集（例如“解析器变更”），或每行包含一个仓库相对路径的 resolved-scope 围栏代码块——则范围仅限这些目标。继续之前，将自然语言描述的子集映射为具体路径。
3. 否则，范围仅限本会话中修改过的文件：即本会话早些时候创建或编辑的文件。不要包含其他未提交的变更。
4. 如果没有本会话中修改过的文件，或当前上下文中看不到先前的对话历史，则回退到所有未提交文件，并各运行一次以下命令：
   • 已跟踪文件：git diff --name-only --diff-filter=ACMR
   • 未跟踪文件：git ls-files --others --exclude-standard
   • 合并两个列表并去重。
5. 除非明确要求，否则不要手动审查生成文件、供应代码、大批量文件和低信号文件：锁文件、压缩包、构建产物、生成产物、供应代码和大型数据快照。如果这些文件与正确性相关，则输出可选的、带 excluded-scope 标签的围栏代码块，每行一个仓库相对路径或 glob，并通过验证或不变量检查覆盖它们。
6. 如果解析出的范围不包含任何文件，则报告此情况并停止。
7. 使用带 resolved-scope 标签的围栏代码块列出范围，每行一个仓库相对路径。该代码块具有权威性：之后不要重新运行范围命令，也不要重新审视排除项。

工作流

1）解析范围

• 应用范围解析部分，然后阅读差异及必要的上下文。
• 将任何 excluded-scope 代码块视为不在手动审查范围内，但纳入验证计划。

2）执行检查

• 根据变更行为和涉及的风险领域对文件分类。
• 应用核心检查，以及配置分派规则中匹配的配置；遵循 --with-profile 和 --skip-profile。
• 对于生成文件、供应代码、大批量文件或低信号文件，应审查生成它们或约束它们的生成器、架构、契约或不变量，而不是逐行或逐个手动审查。

3）整理问题

• 为问题提供位置、影响、证据、置信度和具体修复方案。
• 根据严重性模型分配严重性。

4）修复或等待

• 默认：报告问题，并等待确认后再编辑。
• 使用 --fix 时：按严重性顺序（CRITICAL -> HIGH -> MEDIUM -> LOW）应用所有建议的修复，然后按验证部分进行验证。首次面向用户的问题报告即为修复后的最终报告。

5）报告

按下方的报告部分生成报告。

Review Lens

将用户的请求视为评判差异的边界。

• 揭示隐藏假设：如果行为意图不明确，或不同解读会导致不同修复方案，请停止处理，或将该假设记录为剩余风险，而不是自行猜测。
• 优先采用站得住脚的最小修复。如果单次使用的抽象、推测性的可配置性、额外功能和大范围重写会增加风险或审查负担，请予以标记。
• 对无关改动保持警惕：相邻重构、仅格式调整、删除预先存在的死代码或风格转换，都需要与请求有直接关联。
• 验证目标契合度：改动的行为应有具体的成功标准和范围明确的检查。实际可行时，应通过复现测试验证缺陷；验证逻辑改动应覆盖无效输入；重构应进行改动前后的安全检查。

Core Review Checks

每次运行都要应用。

• CORE-001 行为回归（HIGH）：改动分支／状态转换改变了外部行为。
• CORE-002 错误路径安全性（HIGH）：故障可能级联、导致崩溃或返回不安全的默认值。
• CORE-003 边界处理（HIGH）：未处理 null／空值／溢出／边界输入。
• CORE-004 资源卫生（MEDIUM）：计时器／监听器／句柄／连接泄漏。
• CORE-005 复杂度热点（MEDIUM）：改动引入了可避免的耦合或隐藏副作用。
• CORE-006 测试缺口（MEDIUM）：改动的行为没有针对性测试覆盖。
• CORE-007 范围过宽的改动（MEDIUM）：改动的代码行与用户请求或经验证由该改动引起的清理工作没有直接关联。
• CORE-008 推测性复杂度（MEDIUM）：新增抽象、可配置性、灵活性或对不可能情况的处理，在没有已证实需求的情况下增加了代码。
• CORE-009 成功标准不明确（MEDIUM）：实现缺少针对其声称要改变的行为的明确验证目标。

Profile Dispatch

按风险触发并全面选择配置文件。阅读所有能实质提升所涉及风险面的缺陷发现能力、且未跳过的配置文件；不能仅依据文件扩展名作判断，因为核心检查已覆盖改动。每个选定的配置文件都完整阅读一次；每个配置文件都能在一次读取中读完，因此不要分页阅读，也不要重复读取。

先遵循 --skip-profile 排除项，再添加 --with-profile 指定的配置文件。除非跳过，否则必须包含 references/profiles/naming.md。

• references/profiles/security.md：身份验证、外部输入、密钥、加密、公共网络接口、不安全解析。
• references/profiles/configuration.md：环境变量／配置、超时、重试、连接池、限制、资源调优、发布控制。
• references/profiles/go.md：Go 服务、命令行工具、并发、上下文传递、错误处理、模块或测试。
• references/profiles/typescript-react.md：TypeScript／JavaScript／React／Node 行为改动，涉及类型、渲染、运行时、包或异步语义。
• references/profiles/python.md：Python 服务、脚本、异步工作负载、打包、数据处理或大量 I/O 的改动。
• references/profiles/shell.md：Shell 脚本、CI 命令块、部署脚本、安装命令或命令引用。
• references/profiles/data-formats.md：CSV／JSON／YAML／二进制数据的导入、导出或解析，架构、生成数据、迁移或测试固件更新。
• references/profiles/naming.md：名称／意图清晰度。除非跳过，否则每次审查都要运行。

生成文件和批量文件

• 除非用户明确要求检查，否则手动审查时排除生成文件、供应商文件、大批量文件和信号较弱的文件。
• 优先审查创建或约束这些文件的源：生成器代码、架构、迁移、模板、锁文件更新意图、固定数据契约，或序列化／反序列化路径。
• 使用不变量检查验证受影响的输出，例如重新生成差异、架构验证、解析器往返、行数、校验和、针对性固定数据测试，或包管理器锁文件检查。
• 如果排除的文件会影响审查结论的可信度，请在“范围”或“验证”中说明。

严重性模型

• CRITICAL：可被利用的安全漏洞、数据丢失路径，或关键路径上的服务中断风险。
• HIGH：可能破坏核心行为的逻辑缺陷或性能故障。
• MEDIUM：可能在近期导致缺陷的可维护性／可靠性问题。
• LOW：局部的清晰度、风格或文档改进。

证据规则

• 将每项发现关联到真实且已核实位置的具体代码证据；绝不捏造文件路径或行号。
• 展示会触发故障的输入或状态，以及导致故障的修改行或缺失防护。
• 简洁说明影响范围和故障模式。
• 合并重复发现。
• 优先采用针对性修复，而非大范围重写。
• 对于范围或简洁性方面的问题，引用修改行，并说明它为何无法满足所请求的行为。
• 将无关的死代码作为剩余风险提及；除非用户要求清理，否则不要建议删除。
• 纯风格问题维持为 LOW，除非它们会带来运行风险。

验证

运行能验证已修改行为的最小范围检查：

• 对已修改文件运行格式化工具／静态检查工具
• 对已修改模块运行针对性测试
• 相关时运行类型检查
• 对任何相关的 excluded-scope 输出运行不变量检查

只有在风险需要时才运行更广泛的检查，尤其是在修复涉及共享契约时。列出每项跳过的检查及原因。

报告

按以下顺序使用这些章节标题。省略不适用的章节，不要编号，也不要留下空缺或占位内容。

范围

审查的文件，以及任何 excluded-scope 条目和对其采用的验证策略。

发现

按严重性排序：CRITICAL -> HIGH -> MEDIUM -> LOW。每项发现：

• [SEVERITY] 标题 — path/to/file.ext:line
• 影响：对用户／系统的具体影响。
• 证据：准确的代码行为或差异证据。
• 修复：最小可行的补救措施。
• 可信度：high | medium | low。

建议的修复

仅在未使用 --fix 时提供。

已应用的修复

仅在使用 --fix 时提供。列出每项变更及其文件引用。

验证

运行的命令及结果，包括跳过的检查。

剩余风险

每项风险占一行：假设 <假设>；如果不成立，<可能出问题之处>；通过 <命令或检查> 确认。 使用通俗语言，展开或解释领域术语。直接提出需要用户决定的问题。没有风险时写 None.。

停止条件

遇到以下情况时，停止并寻求指导：

• 修复需要重新设计 API／契约。
• 行为意图过于模糊，无法判断严重性。
• 存在多种合理解释，且会导致实质上不同的发现或修复。
• 必需的验证工具不可用，且风险较高。