Code Review

---
name: code-review
description: 对指定代码目录进行全量代码审核，按模块并行subagent方式分批审查，生成问题报告并追溯问题作者。适用于通用代码工程的定期代码质量审查。
license: MIT
metadata:
  author: internal
  version: "2.0"
  language: zh-CN
---

# 代码审核流程 (Code Review)

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

---

## 配置文件

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

### config.json 结构

```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. 每个问题的记录格式：

```markdown
### 问题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 + 标注 + 拆分 + 校验：

```bash
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 耗时）