@wx-sab/ai-review

AI 驱动的代码审查工具，支持多种 AI Agent 和 API，适用于任何编程语言的项目。

特性

• 多适配器支持 — 自动检测可用的 AI 后端，优先使用能力最强的
  • Agent 模式（Claude Code）：自主读文件、调用 Skill、自动修复代码
  • API 模式（Anthropic / OpenAI / 自定义端点）：直接调用 API 审查
• Skill 集成 — 自动发现并调用已安装的 code review skill（如 code-review-expert），保留 skill 原生的输出风格和分级体系
• 交互式自然语言修复 — 审查发现问题时，直接用中文/英文描述你想怎么处理，agent 会执行
• 语言无关 — 基于 git diff，适用于 JS/TS/Java/Python/Go 等任何语言
• Hook 集成 — 支持 Git pre-commit hook 或 Claude Code PreToolUse hook（二选一）
• 自动继承 .gitignore — 无需重复配置忽略规则
• 中文输出 — 默认中文显示审查结果

快速开始

# 安装依赖并构建
npm install && npm run build

# 全局安装（可选）
npm link

使用方法

基础审查

# 审查 staged 的改动
npx @wx-sab/ai-review review

# 指定 adapter
npx @wx-sab/ai-review review --adapter claude-code

# 只审查不阻止提交
npx @wx-sab/ai-review review --fail-on never

自动修复

# 开启 fix 模式（需要 agent adapter）
npx @wx-sab/ai-review review --fix

# 修复所有问题
npx @wx-sab/ai-review review --fix --fix-all

# 修复指定级别
npx @wx-sab/ai-review review --fix --fix-severity error

# 修复指定问题
npx @wx-sab/ai-review review --fix --fix-issues E1,E2

交互式修复

审查发现问题后，自动进入交互模式（仅 agent 模式）：

Found 3 issue(s):
[E1] [P0] auth.ts:42 - SQL注入漏洞
[W1] [P2] utils.ts:15 - 未定义变量

Interactive mode — 输入自然语言指令，agent 会执行。输入 'exit' 退出

npx @wx-sab/ai-review ❯ 修复SQL注入问题
npx @wx-sab/ai-review ❯ 删除这个文件
npx @wx-sab/ai-review ❯ 把所有P0的问题都修掉
npx @wx-sab/ai-review ❯ skip
npx @wx-sab/ai-review ❯ exit

跳过审查

紧急情况下可以跳过审查直接提交（慎用）：

# 交互模式：直接输入 skip
npx @wx-sab/ai-review ❯ skip

# Hook 模式：临时跳过审查
AI_REVIEW_SKIP=1 git commit

# 或者降低阻止级别
npx @wx-sab/ai-review review --fail-on never

Hook 集成

# 安装 Git pre-commit hook（二选一）
npx @wx-sab/ai-review hook install

# 安装 Claude Code agent hook（二选一，两者互斥）
npx @wx-sab/ai-review hook install --agent claude-code

# 卸载
npx @wx-sab/ai-review hook uninstall            # 卸载 git hook
npx @wx-sab/ai-review hook uninstall --all      # 卸载所有 hook

两种 hook 互斥，安装一种会自动卸载另一种，避免重复触发和嵌套调用。

安装后每次 git commit 自动运行审查，发现严重问题会阻止提交。

配置文件

# 生成配置文件
npx @wx-sab/ai-review init

适配器详解

适配器总览

| 适配器 | 检测方式 | 修复能力 | 说明 | |--------|---------|---------|------| | claude-code | claude CLI | 支持 | 完整 agent 能力，可调用 skill | | codex | codex CLI | 支持 | OpenAI Codex agent，可调用 skill | | api-claude | ANTHROPIC_API_KEY | 不支持 | Anthropic API 直调 | | api-openai | OPENAI_API_KEY | 不支持 | OpenAI API 直调 | | api-custom | AI_REVIEW_BASE_URL 或 AI_REVIEW_API_KEY | 不支持 | 任意 OpenAI 兼容端点 | | hiagent | 需显式配置 | 不支持 | 内部 HiAgent 工作流，无需自带 API Key |

自动检测优先级：claude-code → codex → api-claude → api-openai → api-custom（hiagent 不参与自动检测，需显式指定）

Agent 模式 vs API 模式

| | Claude Code | Codex | API 模式 | |---|---|---|---| | 文件访问 | 自主读取文件、运行命令 | 自主读取文件、运行命令 | 无，只能看传入的 diff | | 上下文 | 能看全局代码结构 | 能看全局代码结构 | 局限在 diff 片段 | | 修复能力 | 直接修改文件并 git add | 直接修改文件并 git add | 不支持 | | Skill 调用 | 自动发现并使用已安装的 skill | 自动发现并使用已安装的 skill | 不支持 | | 交互式 | 自然语言对话修复 | 自然语言对话修复 | 仅报告后退出 |

Claude Code Agent（推荐）

前提条件：已安装 Claude Code CLI

# 无需额外配置，自动检测 claude CLI
npx @wx-sab/ai-review review

# 或显式指定
npx @wx-sab/ai-review review --adapter claude-code

配置文件方式：

{
  "adapter": "claude-code",
  "skills": ["code-review-expert"],
  "customPrompt": "重点关注安全问题"
}

支持的能力：

• 自动发现并调用已安装的 code review skill
• 保留 skill 的原生输出风格和分级体系（如 P0-P3）
• 交互式修复：审查后直接用自然语言描述修复意图
• 自主读取文件、执行命令、修改代码并 re-stage

OpenAI Codex Agent（codex）

前提条件：已安装 OpenAI Codex CLI

# 无需额外配置，自动检测 codex CLI
npx @wx-sab/ai-review review

# 或显式指定
npx @wx-sab/ai-review review --adapter codex

配置文件方式：

{
  "adapter": "codex",
  "skills": ["code-review-expert"],
  "customPrompt": "重点关注安全问题"
}

支持的能力：

• 自动发现并调用已安装的 code review skill
• 保留 skill 的原生输出风格和分级体系（如 P0-P3）
• 交互式修复：审查后直接用自然语言描述修复意图
• 自主读取文件、执行命令、修改代码并 re-stage
• 支持 review() 和 fix() 两种模式

严重级别映射：agent 返回的原生级别自动映射为标准级别

| Agent 原生级别 | 映射结果 | |---|---| | P0, P1, critical, high, blocker, major, error | error | | P2, medium, minor, warning | warning | | P3, low, trivial, info | info |

Codex adapter 使用 --sandbox workspace-write 权限运行，允许读写工作区文件。

Anthropic API（api-claude）

方式一：环境变量（推荐）

export ANTHROPIC_API_KEY="sk-ant-xxxxx"
npx @wx-sab/ai-review review

方式二：配置文件

{
  "adapter": "api-claude",
  "api": {
    "provider": "claude",
    "apiKey": "sk-ant-xxxxx"
  }
}

自定义模型和端点：

{
  "adapter": "api-claude",
  "api": {
    "provider": "claude",
    "apiKey": "sk-ant-xxxxx",
    "model": "claude-opus-4-7",
    "baseUrl": "https://your-proxy.example.com"
  }
}

| 配置项 | 默认值 | 说明 | |--------|-------|------| | apiKey | — | 也可通过 ANTHROPIC_API_KEY 环境变量设置 | | model | claude-sonnet-4-6 | 任意 Anthropic 模型 | | baseUrl | https://api.anthropic.com | 自定义代理地址 |

API 调用路径为 {baseUrl}/v1/messages（Anthropic Messages API 格式）。

优先级：环境变量 > 配置文件中的 apiKey > 默认值

OpenAI API（api-openai）

方式一：环境变量（推荐）

export OPENAI_API_KEY="sk-xxxxx"
npx @wx-sab/ai-review review --adapter api-openai

方式二：配置文件

{
  "adapter": "api-openai",
  "api": {
    "provider": "openai",
    "apiKey": "sk-xxxxx"
  }
}

自定义模型和端点：

{
  "adapter": "api-openai",
  "api": {
    "provider": "openai",
    "apiKey": "sk-xxxxx",
    "model": "gpt-4o-mini",
    "baseUrl": "https://your-proxy.example.com"
  }
}

| 配置项 | 默认值 | 说明 | |--------|-------|------| | apiKey | — | 也可通过 OPENAI_API_KEY 环境变量设置 | | model | gpt-4o | 任意 OpenAI 模型 | | baseUrl | https://api.openai.com | 自定义代理地址 |

自定义端点（api-custom）

适用于任何 OpenAI 兼容的 API 端点，例如：

• 本地模型：Ollama、LM Studio、LocalAI
• 国内代理：各种 OpenAI 兼容的转发服务
• 其他平台：Azure OpenAI、Groq、DeepSeek、通义千问等

方式一：环境变量

# 设置端点地址（必须）
export AI_REVIEW_BASE_URL="http://localhost:11434"

# 设置 API Key（部分端点不需要可省略）
export AI_REVIEW_API_KEY="your-key"

npx @wx-sab/ai-review review --adapter api-custom

方式二：配置文件

{
  "adapter": "api-custom",
  "api": {
    "provider": "custom",
    "baseUrl": "http://localhost:11434",
    "apiKey": "your-key",
    "model": "qwen2.5-coder:7b"
  }
}

常见端点配置示例

Ollama（本地模型，免费）：

{
  "adapter": "api-custom",
  "api": {
    "provider": "custom",
    "baseUrl": "http://localhost:11434",
    "model": "qwen2.5-coder:7b"
  }
}

Ollama 默认不需要 API Key。确保已启动 Ollama 并拉取了模型：

ollama pull qwen2.5-coder:7b
ollama serve

DeepSeek：

{
  "adapter": "api-custom",
  "api": {
    "provider": "custom",
    "baseUrl": "https://api.deepseek.com",
    "apiKey": "sk-xxxxx",
    "model": "deepseek-chat"
  }
}

通义千问（Qwen）：

{
  "adapter": "api-custom",
  "api": {
    "provider": "custom",
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode",
    "apiKey": "sk-xxxxx",
    "model": "qwen-plus"
  }
}

Groq（高速推理）：

{
  "adapter": "api-custom",
  "api": {
    "provider": "custom",
    "baseUrl": "https://api.groq.com/openai",
    "apiKey": "gsk_xxxxx",
    "model": "llama-3.3-70b-versatile"
  }
}

OpenAI 兼容代理：

{
  "adapter": "api-custom",
  "api": {
    "provider": "custom",
    "baseUrl": "https://your-proxy.example.com",
    "apiKey": "your-key",
    "model": "gpt-4o"
  }
}

| 配置项 | 默认值 | 说明 | |--------|-------|------| | baseUrl | http://localhost:11434 | OpenAI 兼容 API 地址，实际调用 {baseUrl}/v1/chat/completions | | apiKey | — | 也可通过 AI_REVIEW_API_KEY 环境变量设置，部分端点可省略 | | model | default | 建议始终显式指定，使用端点支持的模型名称 |

HiAgent 工作流（hiagent）

适用于公司内部部署的 HiAgent 平台，调用工作流接口进行审查，用户无需自带 API Key。

配置文件（必须显式指定 adapter）：

{
  "adapter": "hiagent",
  "api": {
    "baseUrl": "https://hiagent.internal.example.com",
    "apiKey": "<从 HiAgent 智能体预览页获取>",
    "userId": "your-unique-id"
  }
}

| 配置项 | 必填 | 说明 | |--------|------|------| | api.baseUrl | 是 | HiAgent 实例地址（不含 /api/proxy/... 路径） | | api.apiKey | 是 | 从 HiAgent 智能体预览页右侧 API 调用信息获取 | | api.userId | 是 | 当前用户唯一 ID，1-20 字符 |

HiAgent 适配器不参与自动检测，必须通过 adapter: "hiagent" 显式启用。

配置文件参考

配置文件位置

工具按以下顺序查找配置文件，使用第一个找到的：

1. .ai-reviewrc.json
2. .ai-reviewrc
3. ai-review.config.json
4. package.json 中的 "ai-review" 字段

完整配置示例

{
  "mode": "review",
  "adapter": "auto",
  "failOn": "error",
  "skills": ["code-review-expert"],
  "ignore": ["generated/**", "*.auto.ts"],
  "customPrompt": "./review-rules.md",
  "api": {
    "provider": "claude",
    "apiKey": "sk-ant-xxxxx",
    "model": "claude-sonnet-4-6",
    "baseUrl": "https://api.anthropic.com"
  }
}

配置项说明

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | mode | "review" | "review-and-fix" | "review" | 审查模式，review-and-fix 允许修复 | | adapter | "auto" | 适配器名称 | "auto" | 指定适配器，auto 自动检测 | | failOn | "error" | "warning" | "info" | "never" | "error" | 阻止提交的严重级别 | | skills | string[] | — | Agent 使用的 skill 列表 | | ignore | string[] | lock 文件 + node_modules | 忽略的文件 glob 模式（自动合并 .gitignore） | | customPrompt | string | — | 自定义审查规则，可以是字符串内容或文件路径（./rules.md） | | api.provider | "claude" | "openai" | "custom" | — | API 提供商 | | api.apiKey | string | — | API Key（推荐用环境变量） | | api.model | string | 各适配器默认值 | 模型名称 | | api.baseUrl | string | 各适配器默认值 | API 端点地址 | | api.userId | string | — | 用户唯一 ID（hiagent 适配器必填） |

自定义审查规则

customPrompt 支持两种方式：

直接写规则：

{
  "customPrompt": "重点关注：SQL注入、XSS、认证逻辑、敏感信息泄露"
}

引用规则文件：

{
  "customPrompt": "./review-rules.md"
}

review-rules.md 内容示例：

# 审查规则

## 必须检查
- SQL 拼接和注入风险
- 未经验证的用户输入
- 敏感信息硬编码（密码、密钥、token）

## 项目约定
- 所有 API 必须有错误处理
- 禁止使用 any 类型
- 组件必须包含 PropTypes 或 TypeScript 接口

配置优先级

CLI 参数 > .ai-reviewrc.json > package.json#ai-review > 默认值

.gitignore 中的模式会自动合并到 ignore 配置中，无需重复配置。

CLI 参数

npx @wx-sab/ai-review review [options]

  --fix                      开启修复模式
  --adapter <name>           指定适配器
  --fail-on <level>          阻止提交的严重级别 (error|warning|info|never)
  --fix-all                  修复所有问题
  --fix-issues <ids>         修复指定问题 (如 E1,E2)
  --fix-severity <levels>    修复指定级别 (如 error,warning)
  --skills <names>           指定 agent 使用的 skill
  --ignore <patterns>        忽略的文件模式
  --custom-prompt <path>     自定义审查规则文件
  --verbose                  调试模式，显示完整 prompt 和原始响应

环境变量

| 变量 | 说明 | |------|------| | ANTHROPIC_API_KEY | Anthropic API Key（api-claude 适配器） | | OPENAI_API_KEY | OpenAI API Key（api-openai 适配器） | | AI_REVIEW_BASE_URL | 自定义 API 端点地址（api-custom 适配器） | | AI_REVIEW_API_KEY | 自定义 API Key（api-custom 适配器） | | AI_REVIEW_NON_INTERACTIVE | 设为 1 强制非交互模式（isTTY 为 false 时自动生效） | | AI_REVIEW_RUNNING | 防重入标记，防止嵌套调用 | | AI_REVIEW_SKIP | 设为 1 跳过审查，允许直接提交（hook 模式下紧急使用） |

Hook 机制

Git Hook

npx @wx-sab/ai-review hook install

写入 .git/hooks/pre-commit，每次 git commit 前自动审查。

• 目标仓库可以是 Java、Python、Go 或其他任意语言项目
• 执行顺序：项目本地 ./node_modules/.bin/wx-ai-review → PATH 中的 wx-ai-review → npx --yes @wx-sab/ai-review
• 阻止级别由 .ai-reviewrc.json 中的 failOn 控制（默认 error）
• 配置读取、Git diff、AI 调用、结果解析或自动修复失败时会阻止 commit/push；可通过 AI_REVIEW_SKIP=1 显式绕过
• adapter: "auto" 未检测到任何可用 adapter 时跳过 review 并提示，不阻止 commit/push

.git/hooks/ 不被 git 跟踪，仅影响安装者的本地环境。

Agent Hook

npx @wx-sab/ai-review hook install --agent claude-code

写入 .claude/settings.json 的 PreToolUse hook，仅在 Claude Code 执行 git commit / git push 前自动审查。

• 与 Git Hook 互斥，安装一种会自动卸载另一种
• 如果 .claude/ 未被 .gitignore 排除，则会被 git 跟踪，团队成员 clone 后自动生效
• 同样按项目本地命令、全局命令、npx 的顺序启动 review
• git push 会先通过隔离的 --dry-run 捕获实际 remote/refspec 和完整 SHA 范围，不会在 review 阶段真正推送
• 普通 git commit -m ... 审查当前 staged diff；commit -a、pathspec commit 或 compound shell 命令因无法在 PreToolUse 阶段保证精确 diff，会按技术失败阻止
• findings 或技术失败都会转换为 Claude Code PreToolUse 的阻断退出码 2

如何选择

| 场景 | 推荐 | |------|------| | 个人项目 / 团队不统一使用 Claude Code | Git Hook | | 团队都用 Claude Code | Agent Hook | | Java / Python / Go 等非 Node 项目 | 可用；执行机器需安装 Node.js，并可使用全局命令或 npx |

开发

npm install
npm run build       # 构建
npm run dev         # 监听模式
npm run typecheck   # 类型检查

License

MIT