Code Review

代码审核流程 (Code Review)

对指定代码目录进行系统性的全量代码审核，按模块分批审查代码质量，发现逻辑错误和性能问题，生成带作者追溯的完整报告。

配置文件

审核启动时，首先读取项目根目录下 AiDoc/CodeReview/config.json 配置文件。

config.json 结构

{
  "target": {
    "directories": ["审核的目标目录列表"],
    "file_extensions": [".cs", ".java"],
    "exclude_directories": ["排除的目录列表"],
    "exclude_file_patterns": ["*.meta", "*.Designer.cs"]
  },
  "git": {
    "since": "起始日期，如 2026-01-17",
    "branch": "指定分支，空字符串表示当前分支"
  },
  "review": {
    "max_files_per_module": 30,
    "parallel_agents": 18,
    "focus": {
      "logic_errors": ["关注的逻辑错误类型列表"],
      "performance_issues": ["关注的性能问题类型列表"]
    }
  },
  "output": {
    "language": "zh-CN",
    "generate_summary": true,
    "generate_full_report": true,
    "blame_authors": true,
    "author_alias": { "别名": "统一名" }
  }
}

配置加载逻辑

1. 检查 AiDoc/CodeReview/config.json 是否存在
2. 如果存在：读取并解析配置，从中获取��标目录、文件后缀、排除项、时间范围等参数
3. 如果不存在：询问用户以下信息，然后按用户回答执行：
   • 审核的目标目录
   • 目标文件后缀（默认 .cs）
   • 需要排除的目录
   • git 起始日期（默认最近2个月）

输出目录

每次审核的结果存放在 AiDoc/CodeReview/ 下以执行时间命名的子目录中：

AiDoc/CodeReview/
├── config.json
├── 2026-03-19_143000/          # 本次审核结果
│   ├── SUMMARY.md
│   ├── FULL_REPORT.md
│   ├── review_模块名.md ...
│   └── module_commits.md
├── 2026-04-15_100000/          # 下次审核结果
│   └── ...

目录命名格式：YYYYMMDDHHmm@开始日期@结束日期，例如 202601261245@20260125@20260126。检查时间使用审核开始时的本地时间，开始日期和结束日期使用审核范围对应的日期。

在阶段1开始时，立即创建本次输出目录，后续所有产物写入该目录。

适用场景

• 定期（如每月/每季度）对项目运行时代码进行质量审查
• 新版本发布前的代码健康度检查
• 对特定目录/模块的深度审查

流程概览

整个审核分为 5 个阶段：

阶段0: 加载配置 → 阶段1: 确定审核范围 → 阶段2: 模块划分与提交分析 → 阶段3: 逐模块代码审查 → 阶段4: 汇总报告 → 阶段5: 作者追溯

阶段0: 加载配置

目标：读取配置文件，确定审核参数。

操作：

1. 读取 AiDoc/CodeReview/config.json
2. 如果文件不存在，询问用户审核参数（目标目录、文件后缀、排除目录、时间范围）
3. 从配置中提取：
   • TARGET_DIRS：目标目录列表
   • FILE_EXTS：目标文件后缀列表
   • EXCLUDE_DIRS：排除目录列表
   • EXCLUDE_PATTERNS：排除文件模式列表
   • SINCE_DATE：git log 起始日期
   • MAX_FILES_PER_MODULE：单模块最大文件数
   • PARALLEL_AGENTS：并行 agent 数量
   • AUTHOR_ALIAS：作者名映射表
4. 创建本次输出目录：AiDoc/CodeReview/YYYYMMDDHHmm@开始日期@结束日期/

输出：审核参数 + 输出目录路径

阶段1: 确定审核范围

目标：基于配置参数，确定实际要审核的文件列表。

操作：

1. 对 TARGET_DIRS 中的每个目录，使用 git log --since=SINCE_DATE --name-only 获取变更文件
2. 按 FILE_EXTS 过滤文件后缀
3. 按 EXCLUDE_DIRS 和 EXCLUDE_PATTERNS 排除不需要的文件
4. 去重并统计总文件数、总提交数

输出：变更文件列表（写入临时文件供后续阶段使用）

阶段2: 模块划分与提交分析

目标：将大量代码文件按业务模块分组，确定审核优先级。

操作：

1. 按目录结构和业务逻辑将文件分组为模块，分组原则：

   • 同一业务功能目录下的文件归为一个模块
   • 提交数少的小模块可以合并
   • 单个模块的文件数不宜超过 MAX_FILES_PER_MODULE，超过的拆分为 Part1/Part2

2. 统计每个模块的提交数、变更文件数

3. 将模块划分结果写入 {输出目录}/module_commits.md

输出：模块划分文档

踩坑提醒

• git log 在大仓库上可能很慢，加 -- 限定路径范围
• 文件可能被重命名或删除，注意用 --follow 或 --diff-filter
• 中文提交信息在某些终端可能乱码，确保 UTF-8 编码

阶段3: 逐模块多subagent代码审查

目标：对每个模块的变更文件进行深度代码审查，发现逻辑错误和性能问题。

操作：

0. 强制要求：阶段3必须启动 subagent 执行，不允许主会话直接完成模块审查。
1. 按模块逐个审查，每个模块启动一到多个subagent生成一个独立的审查报告（如 {输出目录}/review_GameBattle.md）
2. 对每个模块：
   • 读取该模块所有变更文件的完整代码
   • 按配置中 review.focus 定义的问题类型重点关注

逻辑错误类（高优先级）：

• 数组/字典越界访问
• 除零风险
• 类型转换异常
• 事件监听注册/注销不匹配导致泄漏
• 循环中修改集合
• 条件判断逻辑错误（运算符优先级、短路求值）
• 多线程/重入安全问题
• 资源未释放（Timer、异步操作、对象/句柄）

性能问题类（中优先级）：

• 热路径上的 LINQ/ToList() 产生 GC 分配
• 每帧重复创建临时对象
• 字典双重查找（先 ContainsKey 再索引）
• 字符串拼接在循环/高频调用中
• 不必要的反射调用
• O(n²) 或更高复杂度的嵌套循环

3. 每个问题的记录格式：

### 问题N
- 文件：完整文件路径
- 行号：具体行号或行号范围
- 问题代码：（贴出关键代码片段）
- 问题类型：逻辑错误 / 性能问题
- 描述：问题的具体说明和修复建议

4. 如果模块文件太多（超过 MAX_FILES_PER_MODULE），拆分为多个 Part 分批审查
5. 必须使用 并行 subagent 同时审查不同模块
6. 若 subagent 不可用或执行失败，阶段3必须立即中止并报告阻塞原因，禁止降级为主会话直审

输出：每个模块一个 review_模块名.md 文件，存放在输出目录下

踩坑提醒

• 单次读取的文件不要太多，容易超出上下文窗口。建议每次读取 5-10 个文件
• 对于超大文件（>1000行），可以分段读取，重点看变更相关的部分
• 脚本生成代码、跨语言桥接代码或自动生成代码有特殊模式，需要特别注意
• 审查时注意区分"确定的 bug"和"代码风格问题"，只报告前者

阶段4: 汇总报告

目标：将所有模块的审查结果合并为一份完整报告，并生成总结。

操作：

1. 生成汇总摘要（{输出目录}/SUMMARY.md），包含：

   • 审核概览（模块数、问题总数、分类统计）
   • 按严重程度分组的问题列表
   • 共性问题模式总结
   • 修复优先级建议

2. 生成完整报告（{输出目录}/FULL_REPORT.md），包含：

   • 汇总摘要部分
   • 所有模块的详细问题列表

输出：SUMMARY.md + FULL_REPORT.md

踩坑提醒

• FULL_REPORT 可能非常长（7000+ 行），注意文件写入时分块处理
• 合并时注意各模块报告的格式可能不完全一致，解析需要兼容多种格式

阶段5: 作者追溯与按人拆分

目标：为每个问题找到对应的代码作者，生成按作者拆分的独立文件，方便直接分发给各开发者修复。

操作：

运行 skill 自带的 blame_split.py 脚本，一次性完成 blame + 标注 + 拆分 + 校验：

python .agents/skills/code-review/blame_split.py \
  --root . \
  --report {输出目录}/FULL_REPORT.md \
  --config AiDoc/CodeReview/config.json

脚本自动完成以下工作：

1. 解析问题：从 FULL_REPORT.md 提取所有 ### 问题N 块，兼容多种字段格式（- 文件：、**文件**：、文件路径： 等）
2. 构建文件索引：通过 git ls-files 建立完整路径索引 + 后缀索引 + basename 索引，支持5级路径匹配策略：
   • 精确匹配 → 大小写不敏感匹配 → 磁盘存在性检查 → 常见前缀补全 → 后缀/basename 兜底
3. 逐问题 blame：
   • 从行号字段提取起始行（支持范围格式 78-84、中文前缀 约170）
   • git blame -L N,N --line-porcelain 精确定位作者
   • 失败时 fallback 到 git log -1 --format=%an
   • 每次 blame 设置 10 秒 timeout 防止卡死
4. 作者归一化：使用 config.json 中的 output.author_alias 映射表合并同名作者
5. 更新报告：
   • 在 FULL_REPORT.md 每个问题标题后追加 【作者: xxx】
   • 在 FULL_REPORT.md 和 SUMMARY.md 末尾追加作者统计表
6. 按作者拆分：
   • 每位作者生成独立的 bugs_<author>.md，包含该作者的所有问题
   • 无法归属的问题写入 bugs_未归属.md，附带失败原因
   • 生成 INDEX.md 索引文件
   • 生成 VERIFY.md 一致性校验（条目数量 + 内容哈希，确保拆分过程不丢不改）

输出：

• 更新后的 FULL_REPORT.md（含作者标注 + 统计表）
• 更新后的 SUMMARY.md（含作者统计表）
• by_author/ 目录（按作者拆分的独立文件 + 索引 + 校验）

最终产物清单

AiDoc/CodeReview/
├── config.json                         # 审核配置
└── YYYYMMDDHHmm@开始日期@结束日期/      # 本次审核结果目录
    ├── module_commits.md               # 模块划分与提交记录
    ├── review_*.md                     # 各模块审查报告
    ├── SUMMARY.md                      # 汇总摘要（含作者统计）
    ├── FULL_REPORT.md                  # 完整报告（含作者标注 + 统计表）
    └── by_author/                      # 按作者拆分
        ├── INDEX.md                    # 作者文档索引
        ├── VERIFY.md                   # 一致性校验结果
        ├── bugs_<author>.md            # 每位作者的问题清单
        └── bugs_未归属.md              # 无法追溯作者的问题

执行建议

1. 并行审查（强制）：模块之间互相独立，必须用多个 subagent 并行审查不同模块 spawn a subagent per module
2. 增量审核：下次审核时修改 config.json 中的 git.since 日期即可只审查新增变更
3. 历史对比：不同时间的审核结果在各自的时间目录下，方便对比代码质量趋势
4. 作者追溯优先脚本化：阶段5 优先运行 blame_split.py，不要用自然语言逐条 blame，除非是极少量问题的临时分析
5. 时间预估：
   • 阶段0-2：10-15 分钟
   • 阶段3：取决于模块数量，20+ 模块约需 2-3 小时
   • 阶段4：10-15 分钟
   • 阶段5：15-30 分钟（主要是 git blame 耗时）