review

代码审查

审查当前分支上的代码变更：先阅读检查点转录，了解每项变更背后的意图，再审查实际差异并查找问题。这样可以进行结合意图的审查，发现开发者期望与代码实际行为之间的不一致。

响应格式

本次技能调用的首次响应必须以如下行开头：

Entire Review:

然后空一行，再开始正文。

• 此标题仅用于本次调用的首次响应。同一次调用中的后续轮次不要再次打印。
• 错误或提前退出时（例如“不是 git 仓库”“分支与基线之间没有提交”），不要包含此标题。

规则

1. 这是一次只读审计。审查期间不要修改任何文件。
2. 列出问题之前，始终先显示范围横幅，让用户了解审查范围。
3. 如果无法获取检查点上下文，仍需仅根据差异和提交消息进行审查。明确说明本次审查缺少意图上下文。
4. 按文件对问题分组。每个文件内按严重程度排序（严重 > 高 > 中 > 低）。
5. 每个问题都必须附带具体建议或解释，不能只指出问题。
6. 列出问题后，询问用户是否需要修复计划。不要自动修复。
7. 除非用户明确要求，否则不要审查生成文件、锁文件或二进制文件。

流程

1. 验证环境

运行 entire version，检查 CLI 是否可用。如果未安装，请说明本次审查将在缺少检查点意图上下文的降级模式下进行。

2. 检测基准引用

查找要与之比较的主线分支。按以下顺序尝试这些引用，并使用第一个存在的引用：

git rev-parse --verify origin/HEAD 2>/dev/null
git rev-parse --verify origin/main 2>/dev/null
git rev-parse --verify origin/master 2>/dev/null
git rev-parse --verify main 2>/dev/null
git rev-parse --verify master 2>/dev/null

如果都不存在，请告知用户未找到基准引用，并请用户指定一个。

3. 计算范围

git rev-list --count <base>..HEAD
git diff --stat <base>..HEAD

记录变更的提交数和文件数，作为范围横幅。

4. 收集检查点意图（降级模式下跳过）

git log --format='%H%x00%s%x00%b' <base>..HEAD

从提交正文中提取 Entire-Checkpoint: 尾部字段的值，并对检查点 ID 去重。

对每个唯一的检查点 ID（最多 20 个）：

entire checkpoint explain --checkpoint <checkpoint-id> --json --no-pager

解析 JSON，提取会话元数据。对于检查点中的每个非审查会话，优先使用摘要（意图 + 结果）。如果没有摘要，则退而使用最新的用户提示。将每个检查点的详情截断至 320 个字符。

如果某个检查点的 --json 失败，则退而使用纯文本输出：

entire checkpoint explain --checkpoint <checkpoint-id> --no-pager

审查流程中不要使用 --full，因为它会生成较长的叙述性文本，不利于 Agent 批量解析。如果该方式也失败，则跳过该检查点，并注明其不可用。

此外，读取当前正在进行的会话（如果有），以获取未提交工作的上下文：

entire session current --json

如果返回有效的 JSON，则提取 last_prompt 和 files_touched；它们代表尚未记录在任何检查点中的未提交变更意图。

构建意图映射：对于差异中的每个文件（已提交和未提交），收集所有涉及该文件的检查点及活动会话中的相关意图上下文。

5. 阅读差异

git diff <base>..HEAD

也要包含未提交的变更：

git diff HEAD

对于大型差异（总计超过 5000 行），重点审查最关键的文件：

• 变更最多的文件
• 检查点意图中提及的文件
• 源文件优先于生成文件和配置文件

必要时阅读单个文件的差异，而不是一次性加载整个差异。

6. 执行审查

阅读审查规则：

references/review-rules.md

对于差异中的每个文件，审查时考虑：

结合检查点上下文：

• 实现是否符合所述意图？
• 是否遵守了对话记录中的约束？
• Agent 是否遗漏了讨论过的边界情况？
• 是否遗留了调试产物或 TODO？

始终检查（无论是否有上下文）：

• 逻辑错误、差一错误、空值安全
• 安全问题（注入、绕过身份验证、数据泄露）
• 性能问题（N+1 查询、不必要的内存分配）
• 错误处理缺失
• API 契约违规
• 无用代码或不可达分支

7. 输出审查结果

使用与 entire review --fix 解析器匹配的严重性前缀来呈现审查结果：

Entire Review:

Reviewing <branch> vs <base>: N commits, M files changed
[Intent context: available from K checkpoints | unavailable — reviewing diff only]

## path/to/file.ts

Critical: <issue description>
  Intent: <what the checkpoint said this should do, if available>
  Actual: <what the code actually does>
  Fix: <concrete suggestion>

High: <issue description>
  Intent: <what the checkpoint said this should do, if available>
  Actual: <what the code actually does>
  Fix: <concrete suggestion>

Medium: <improvement opportunity>
  Issue: <what is wrong>
  Fix: <concrete suggestion>

## path/to/other-file.ts

Low: <observation that is not a bug but worth noting>

---

Found N issues (X critical, Y high, Z medium, W low).
Would you like me to create a fix plan for the critical and high issues?

如果某项审查结果没有检查点上下文，请省略 Intent: 行，改用 Issue: / Fix:。

8. 提供后续选项

呈现审查结果后，等待用户回复：

• 如果用户同意制定修复计划，列出解决每项严重/高优先级问题的具体步骤。
• 如果用户要求直接修复，则切换到实现模式并处理这些问题。
• 如果用户拒绝，则审查完成。

降级模式（没有 Entire CLI 或没有检查点）

检查点上下文不可用时：

1. 完全跳过第 4 步
2. 在范围说明中写明：“意图上下文不可用 — 仅审查差异”
3. 从审查结果中省略 Intent: 行
4. 仍执行第 6 步中的完整代码审查
5. 最后注明：“本次审查未使用 Entire 检查点上下文。启用检查点后，审查还会验证实现是否符合 开发者最初的意图。”

失败情况

• 基础版本与 HEAD 之间没有提交：告知用户该分支相对于基础版本没有变更。不要输出审查结果。
• 无法检测基础引用：请用户指定基础分支或提交。
• 差异过大（超过 100 个文件）：询问用户是要审查所有文件，还是聚焦于部分文件。建议仅审查源文件或具有检查点上下文的文件。
• entire checkpoint explain 失败：注明具体检查点不可用，并在没有该上下文的情况下继续审查其余文件。