AI Codeview 安装与使用教程

本地优先的 AI 代码审查工具。审查 Git diff / 暂存区 / 指定路径，调用 DeepSeek 生成中文报告，适合提交前质量检查。

官方站点：AI Codeview

---

1. 环境要求

项	要求
Node.js	≥ 20（推荐 20 LTS 或以上）
Git	已安装并加入 PATH
仓库	必须在 Git 仓库目录内执行
API	DeepSeek API Key

---

2. 安装

全局安装（推荐）

npm install -g ai-codeview

安装后可用命令：acv（等同于 ai-codeview）。

验证：

acv --version
acv doctor

本仓库已有配置

仓库根目录存在 .ai-codeview.json 时，会自动读取。主要字段：

• provider：deepseek
• model：如 deepseek-v4-pro / deepseek-v4-flash
• apiKeyEnv：默认读取环境变量 DEEPSEEK_API_KEY
• failOn：达到该严重级别时审查失败（如 high）
• reportLanguage：zh-CN / en-US
• ignore：忽略文件模式

初始化配置（可选）：

acv init

打印最终生效配置：

acv config

---

3. 配置 API Key（必做）

acv 不会 自动读取项目 .env，只读系统/终端环境变量。

配置里 apiKeyEnv 为 DEEPSEEK_API_KEY 时，需设置：

Git Bash（当前窗口临时）

export DEEPSEEK_API_KEY=sk-你的密钥

Windows PowerShell（用户级，永久）

[System.Environment]::SetEnvironmentVariable('DEEPSEEK_API_KEY', 'sk-你的密钥', 'User')

然后关闭并重新打开终端。

验证

# Git Bash
echo ${DEEPSEEK_API_KEY}

acv doctor

DeepSeek API Key 一项应为 ✓。

密钥在 DeepSeek 开放平台 创建。不要把 Key 提交进 Git。

---

4. 常用命令

4.1 环境诊断

acv doctor

检查 Node、Git、配置、API Key、remote 等。

4.2 审查变更

命令	含义
acv review	审查工作区相对 HEAD 的 diff（含未暂存删除/修改）
acv review --staged	只审查暂存区（推荐提交前使用）
acv review --changed	审查 staged + unstaged
acv review --path src	审查指定路径（可多次 --path）
acv review --base main	相对某分支的变更

输出控制：

acv review --staged --format markdown
acv review --staged --format json
acv review --staged --summary
acv review --staged --output review-report.md

4.3 提交并推送前审查

git add .
acv push --dry-run    # 只审查 + 生成提交信息，不 commit/push
acv push              # 审查通过后提交并推送
acv push --no-push    # 只 commit，不 push

典型流程：

git add src/index.ts
acv push --dry-run
acv push

---

5. 推荐工作流（本仓库）

cd ai-review-initiative

# 1. 确认环境
acv doctor

# 2. 只暂存要提交的代码（避免误暂存删除文件、二进制）
git add index.js package.json .ai-codeview.json

# 3. 审查暂存区
acv review --staged

# 4. 按报告修改后，再 add，再 review
# 5. 确认无误再 commit / 或使用 acv push

---

6. 注意事项

1. 必须在 Git 仓库根目录或仓库内执行，且目录是 Git 仓库。
2. 必须先设置 DEEPSEEK_API_KEY，否则到「准备审查分块」会失败。
3. 密钥安全 ：不要把 Key 写进 .ai-codeview.json 或提交到远程；.env 请加入 .gitignore。
4. 默认会扫描敏感信息 （security.allowSecrets: false），diff 里像真密钥的内容会直接中止。
5. 大 diff 会自动分块 ；可用 ignore 排除 lock 文件、构建产物、node_modules。
6. 路径越界防护 ：默认拒绝审查工作目录外的路径（如系统 .ssh、用户主目录秘密文件）。
7. Windows / Git Bash：若用 Volta 管理 Node，注意中文路径下个别工具可能异常；本项目目录尽量用英文路径操作 CLI。
8. 审查的是 diff 内容：没改动 / 没暂存时会提示没有可审查的 diff。

---

7. 常见错误与处理

7.1 DeepSeek API Key: 未设置 DEEPSEEK_API_KEY

现象： acv doctor 该项为 ✗，或 review 提示缺少 Key。

处理：

export DEEPSEEK_API_KEY=sk-你的密钥
acv doctor

或设置 Windows 用户环境变量后重开终端。

注意：项目根目录 .env 不会被自动加载。

---

7.2 工具运行时发生未知错误

现象： 走到「过滤无需审查的文件...」后报未知错误。

常见原因（已踩坑）：

变更中含有删除文件 时，工具把路径解析成 /dev/null，过滤阶段崩溃。

处理（任选）：

# 方案 A：只审暂存区，且暂存区不要包含删除项
git restore --staged -- path/to/deleted-file
git add 仅要审查的代码文件
acv review --staged

# 方案 B：按路径审查（避开完整 diff）
acv review --path index.js

# 方案 C：不要直接用裸命令扫描含大量删除的工作区
# 慎用：acv review

建议： 提交前优先使用 acv review --staged ，并且暂存区尽量只有「新增/修改」的代码文件；二进制、临时文件、误删文件先 restore --staged。

---

7.3 没有发现可审查的 diff

原因： 工作区/暂存区没有变更，或 --staged 时暂存区为空。

处理：

git status
git add <files>
acv review --staged

---

7.4 检测到疑似密钥，审查被中止

原因： diff 中命中 PAT、AWS Key、JWT 等模式。

处理：

1. 从变更中移除密钥，改用环境变量。
2. 若是假阳性且确认安全，短期可（谨慎）：

acv review --staged --allow-secrets

或配置 "security": { "allowSecrets": true }（不推荐长期开启）。

---

7.5 不能同时使用互斥参数

例如：

• --path 不能与 --staged / --base 同时用
• --changed 不能与 --staged / --base / --path 同时用

按提示去掉冲突参数即可。

---

7.6 Git / Node 相关

提示	处理
无法执行 Git 命令	安装 Git 并加入 PATH
Node 版本过低	升级到 Node ≥ 20
当前目录不是 Git 仓库	cd 到仓库后再执行

---

7.7 审查失败退出码（质量门禁）

配置 failOn: "high" 时，若报告含 high/critical 级别问题，进程会以非 0 退出，便于 CI / 钩子拦截提交。

处理：按报告修复后重新 git add 再 acv review --staged。

---

8. 配置文件示例

{
  "provider": "deepseek",
  "model": "deepseek-v4-pro",
  "baseUrl": "https://api.deepseek.com",
  "apiKeyEnv": "DEEPSEEK_API_KEY",
  "reportLanguage": "zh-CN",
  "failOn": "high",
  "confidenceFloor": "medium",
  "security": {
    "allowSecrets": false
  },
  "ignore": [
    "pnpm-lock.yaml",
    "package-lock.json",
    "dist/**",
    "build/**",
    "*.min.js",
    "node_modules/**",
    ".git/**",
    "*.xlsx"
  ],
  "output": {
    "format": "markdown",
    "file": null
  }
}

可按需要把 *.xlsx、*.pyc、临时文件等加入 ignore，减少噪声与二进制干扰。

---

9. 命令速查

npm install -g ai-codeview

export DEEPSEEK_API_KEY=sk-xxx
acv doctor
acv init
acv config

acv review --staged
acv review --path src
acv review --changed
acv review --staged --format markdown --output report.md

acv push --dry-run
acv push

---

10. 参考链接

• 官网与指南：https://ai-codeview.vercel.app/
• DeepSeek API：https://platform.deepseek.com/