acr - AI Code Review

AI 驱动的代码审查与提交工具。通过 AI 自动生成规范的 commit message，同时对代码变更进行审查，发现潜在问题。

特性

• 智能提交 — AI 自动生成 Conventional Commits 格式的 commit message
• 代码审查 — AI 分析代码变更，标注问题（严重/警告/建议）和亮点
• 交互式操作 — 审查完成后通过方向键选择提交、推送或取消
• 流式输出 — 实时显示 AI 审查过程
• 上下文感知 — 自动读取相关源文件，提供更准确的审查
• CodeGraph 集成 — 检测到项目存在 CodeGraph 索引时，自动获取跨文件调用关系，做超出本次 diff 的全面审查
• 多语言输出 — 支持中文、英文、日文等多种输出语言
• 灵活配置 — 支持交互式设置、配置文件、环境变量三种方式
• Git Hook — 可选的自动化审查，commit 时自动触发

安装

npm install -g @spahce/acr

要求 Node.js >= 18。

快速开始

# 1. 暂存你的代码变更
git add .

# 2. 运行 acr
acr

首次运行会提示输入 AI 服务配置（API 地址、密钥、模型），配置会保存到 ~/.acr/config.json。

之后 acr 会自动完成以下流程：

1. 分析暂存的代码变更
2. AI 生成 commit message 和代码审查
3. 展示结果，等待你选择操作（提交并推送 / 仅提交 / 取消）

配置

交互式配置（推荐）

# 首次运行时自动触发，或手动运行：
acr config

按提示输入 API 地址、密钥和模型名称，配置保存到 ~/.acr/config.json。

配置文件

直接编辑 ~/.acr/config.json：

{
  "baseUrl": "https://api.anthropic.com",
  "authToken": "sk-ant-...",
  "model": "claude-sonnet-4-20250514"
}

环境变量

export ANTHROPIC_BASE_URL=https://api.anthropic.com
export ANTHROPIC_AUTH_TOKEN=sk-ant-...
export ANTHROPIC_MODEL=claude-sonnet-4-20250514    # 可选，有默认值

优先级： 环境变量 > 配置文件 > 交互式设置。

使用方式

默认模式：提交 + 审查

# 暂存变更后直接运行
acr

AI 会在一次调用中同时生成 commit message 和代码审查。审查结果展示后，通过方向键选择：

• 提交并推送 — 执行 git commit + git push（有远程仓库时显示）
• 仅提交 — 只执行 git commit
• 取消 — 放弃操作

审查模式：仅查看审查结果

# 审查已暂存的变更
acr --staged

# 审查指定的 commit
acr --commit abc1234

# 审查两个引用之间的差异
acr --diff main...HEAD

# 限定审查特定文件
acr --staged --file src/index.ts

# 使用英文输出
acr --staged --lang en

CLI 参考

acr [选项] [命令]

选项：
  --staged              仅审查已暂存的变更（不提交）
  --commit <sha>        审查指定的 commit
  --diff <range>        审查两个引用之间的差异（如 main...HEAD）
  --file <path...>      限定审查指定文件
  --context <n>         diff 上下文行数（默认: 3）
  --lang <language>     输出语言（默认: zh）
  --no-stream           禁用流式输出
  -V, --version         显示版本号
  -h, --help            显示帮助信息

命令：
  config                配置 AI 服务参数
  weekly                基于本周提交的代码生成周工作评估
  hook install          安装 git hook（支持 --global --force）
  hook uninstall        卸载 git hook（支持 --global）

周工作评估

acr weekly

基于本周（周一至周日）通过 acr 提交的记录，拉取每次提交的真实代码 diff，由 AI 进行综合评估。

与仅总结 commit message 不同，acr weekly 会读取每条提交的代码变更内容，据此输出：

• 本周完成工作 — 基于实际代码变更，按模块/功能分组列出本周真正完成的工作，反映代码层面的具体改动。
• 本周工作总结 — 对本周工作做综合评估：主要方向、代码质量、技术亮点、潜在问题或风险、后续建议。

acr weekly --lang en     # 使用英文输出
acr weekly --brief       # 精简模式
acr weekly --fast        # 使用快速模型
acr weekly --no-stream   # 禁用流式输出

说明：

• 提交记录来源于 ~/.acr/history.json，仅记录通过 acr 完成的提交。
• 单条提交 diff 上限约 6KB，本周 diff 总量上限约 80KB，超出部分截断。
• 拉取 diff 失败的提交（如初始提交无父节点）保留 commit message 与文件列表参与评估。

Git Hook

安装 hook 后，每次 git commit 时自动执行代码审查：

# 在当前仓库安装
acr hook install

# 全局安装（对所有仓库生效）
acr hook install --global

# 卸载
acr hook uninstall
acr hook uninstall --global

审查输出格式

审查结果包含三个部分：

• 概要 — 变更内容的简要总结
• 问题 — 发现的问题，按严重程度标注：
  • 🔴 严重 — Bug、安全漏洞、数据丢失风险
  • 🟡 警告 — 潜在问题、性能隐患、不良实践
  • 🔵 建议 — 改进建议、风格优化
• 亮点 — 代码中做得好的地方：
  • 🟢 优秀

CodeGraph 集成

默认情况下，acr 只基于本次 diff 和变更文件的源码进行审查。当项目存在 CodeGraph 索引时，acr 会自动利用它进行更全面的跨文件审查。

工作方式

• 运行审查时，acr 会检测当前 git 仓库根目录是否存在 .codegraph/ 索引（仅在仓库根目录检查，不会向上递归到无关目录）。
• 若存在索引且系统已安装 codegraph 命令，acr 会针对本次变更的文件调用 codegraph explore，获取：
  • 相关符号的完整源码
  • 它们之间的调用路径（包括动态分派，grep 无法追踪的部分）
  • 依赖这些符号的调用方与影响范围
• 这些跨文件上下文会一并交给 AI，用于评估变更是否破坏调用方、是否违反既有契约、是否影响其他模块的行为——审查范围因此超出本次 diff 涉及的文件。

启用方式

在项目根目录建立索引即可，acr 会在后续审查中自动启用：

codegraph init

无需额外配置。未安装 codegraph 或无索引时，acr 会静默回退到常规审查流程，不会产生额外输出或报错。

说明

• 跨文件上下文有大小上限（约 120KB）与超时保护（45s），不会因索引过大拖慢审查。
• 变更文件较多时，最多取 25 个文件参与 codegraph explore 查询。
• CodeGraph 索引的建立与维护由用户决定，acr 仅在索引已存在时读取使用。

许可证

MIT