AIReview

本地 push 前 AI 代码门禁 CLI，基于 Cursor SDK 审查 git diff，输出结构化报告；可选部署 Webhook 服务接入阿里云 Codeup MR 审查。

git diff → Cursor 审查 → docs/{分支名}/审查发现.md + 审查发现.json → 门禁通过/拦截

环境要求

• Node.js 22+
• pnpm
• 已安装并登录 Cursor（本地 CLI 审查依赖 Cursor SDK）
• 项目变更已 commit 到当前分支（审查的是分支相对基准的 diff）

快速开始（CLI）

1. 安装依赖

pnpm install

2. 配置本地环境变量

复制 .env.example 为 .env，至少填写 CLI 所需项：

CURSOR_API_KEY=          # cursor.com/dashboard/integrations 获取
CURSOR_MODEL=auto        # 可选，默认 auto

.env 含密钥，勿提交到仓库。

3. 运行审查

pnpm ai:review --deep

• 退出码 0：门禁通过，可以 push
• 退出码 1：门禁未通过，或审查/解析失败

CLI 用法

命令总览

| 命令 | 说明 | |------|------| | pnpm ai:review --deep | 运行 AI 审查（必填 --deep） | | pnpm ai:review annotate list | 列出所有问题及编号 | | pnpm ai:review annotate --index N --as <状态> | 命令行标注（可选） | | pnpm ai:review --help | 审查帮助 | | pnpm ai:review annotate --help | 标注帮助 |

审查参数

| 参数 | 默认值 | 说明 | |------|--------|------| | --deep | — | 必填。调用 Cursor 引擎审查 | | --fail-on <级别> | high | 门禁拦截级别，见下文 | | --base <分支> | master | diff 对比基准分支 | | --path <路径> | 全仓库 | 仅审查指定路径下的变更 | | --name <名称> | 当前分支名 | 覆盖 docs/ 下的报告文件夹名 | | --doc | 关闭 | 额外生成 背景和影响.md（适合 MR 定稿归档） | | --force | 关闭 | 全量重审（重调 Cursor）；保留 md/json 中的人工标注 | | --recheck | — | 与默认行为相同；已有报告且 commit 变化时自动增量复检 | | -h / --help | — | 显示帮助 |

常用示例

# 标准 push 前审查
pnpm ai:review --deep

# 对比 main 分支
pnpm ai:review --deep --base main

# 只审查 src/api 目录
pnpm ai:review --deep --path src/api

# 全量重审（忽略缓存与旧报告）
pnpm ai:review --deep --force

# 审查 + 生成变更说明文档
pnpm ai:review --deep --doc

# 更严格的门禁（公共 medium 也拦截）
pnpm ai:review --deep --fail-on medium

运行中交互

• 审查过程支持流式输出（TTY 下可见进度）
• 按 Ctrl+C 可中断 Cursor 审查

审查报告

报告固定写入：

docs/{分支名}/
├── 审查发现.md      # 人类可读报告
├── 审查发现.json    # 结构化缓存（门禁与增量复检的数据源）
└── 背景和影响.md    # 仅 --doc 时生成

同分支多次审查会覆盖更新同一目录（不再按 commit 分子目录）。

报告结构说明

审查发现.md 大致分为：

1. 公共与系统影响 — 门禁判定的主要依据
2. 仍待处理 — 公共/系统 — 可阻断 push 的风险
3. 仍待处理 — 局部功能 — 全面列出，默认不阻断 push
4. 已标注 — 人工确认可忽略的项，不参与门禁
5. 已修复 — 增量复检时相对上次已消失的问题

门禁规则

审查策略为两条线并行：

| 类型 | scope | 行为 | |------|-------|------| | 公共/系统 | shared | 重点关注，高严重度可阻断 push | | 局部功能 | local | 全面排查，列出问题但默认不单独阻断 |

--fail-on 拦截级别

| 值 | 行为 | |----|------| | high（默认） | systemImpact.overallRisk=high，或 shared + high finding → 拦截 | | medium | 上述 + overallRisk=medium 或 shared medium → 拦截 | | any | 任意公共影响或任意 finding → 拦截 | | none | 永不拦截（仅生成报告） |

local 级问题无论 severity 多高，在默认 fail-on=high 下不单独阻断 push。

缓存与增量复检

| 场景 | 行为 | |------|------| | 同 commit 再次运行 | 跳过 Cursor 调用，直接使用已有报告（会先同步 md 标注） | | 新 commit + 已有报告 | 自动增量复检：核对旧问题 + 扫描新 diff | | --force | 全量重审（重调 Cursor）；保留人工标注，不需重新标注 |

增量复检时会：

• 保留人工标注（同文件同行或相同问题描述）
• 将已修复项写入「已修复」节
• 已标注项不会再次参与门禁

人工标注（推荐：在 Markdown 里写）

推荐直接在 审查发现.md 里标注，比命令行更方便。保存后，下次运行 pnpm ai:review --deep 会自动从 md 同步到 json。

写法

在对应问题下方加一行（与「建议」同级缩进）：

- `src/foo.ts:42` `[局部]` — **某问题描述**
  - 建议: 改成 xxx
  - @wontfix 设计如此，不需要改

支持的关键词

| 关键词 | 含义 | 别名 | |--------|------|------| | @wontfix | 不需要修改 | @nofix、@skip | | @fp | 误报 | @false_positive | | @deferred | 延后处理 | @later | | @accepted | 已知风险可接受 | @accept | | @open | 恢复为待处理 | — |

也支持中文标签：@不需要修改、@误报、@延后处理、@已知风险可接受。

标注示例

  - @fp 测试数据，不是真漏洞
  - @wontfix 与上游约定保持一致
  - @accepted 已知性能问题，下版本优化
  - @deferred 等需求确认后再改
  - @open

同步成功后，条目会移到「已标注」分区；终端会提示：已从 审查发现.md 同步 N 条标注。

标注注意事项

• @ 行必须写在对应问题块下面，系统按 `文件:行号` 匹配
• 仅改 md 里普通文字备注不会生效，必须用 @关键词 格式
• 审查发现.json 是机器数据源；md 标注会自动写回 json
• 已标注项不参与门禁，增量复检时也不会重复拦截

命令行标注（可选）

不习惯改 md 时，可用 annotate 子命令，效果与 md 标注相同。

# 列出编号
pnpm ai:review annotate list

# 按编号标注
pnpm ai:review annotate --index 2 --as wontfix --reason "设计如此"

# 按文件定位
pnpm ai:review annotate --file src/a.ts --line 10 --as false_positive

# 恢复为待处理
pnpm ai:review annotate --index 1 --as open

--as 可选值

| 值 | 含义 | |----|------| | wontfix | 不需要修改 | | false_positive | 误报 | | deferred | 延后处理 | | accepted | 已知风险可接受 | | open | 恢复为待处理 |

使用注意事项

1. 先 commit 再审查 — 审查的是当前分支相对 --base 的已提交 diff，未 commit 的工作区变更不在范围内。
2. --deep 必填 — 不带 --deep 只会打印帮助，不会执行审查。
3. 基准分支要存在 — 默认对比 master，仓库若无该分支请用 --base 指定（如 main）。
4. 同提交不重复调模型 — 同一 commit 重复运行会直接读缓存；改完 md 标注后重新运行即可同步，无需 --force。
5. 需要彻底重审时再用 --force — 会重新调用 Cursor；你在 md/json 里的 @标注 会自动保留，不必重标。
6. 局部问题不挡 push（默认） — 默认 fail-on=high 只拦公共高风险；若希望更严，用 --fail-on medium 或 any。
7. 标注请用 @关键词 — 在 md 里写普通备注不会被识别；annotate 命令与 md 标注二选一即可。
8. .env 不要提交 — 尤其 CURSOR_API_KEY。
9. 解析失败视为未通过 — 模型未按 JSON 格式返回时，门禁不通过，可查看报告内「原始输出」或 --force 重试。

环境变量参考

本地 CLI

| 变量 | 必填 | 说明 | |------|------|------| | CURSOR_API_KEY | 是 | Cursor API Key | | CURSOR_MODEL | 否 | 模型 ID，默认 auto | | CURSOR_RIPGREP_PATH | 否 | 自定义 ripgrep 路径 |

Webhook 服务（可选）

部署 pnpm dev / pnpm start 接入 Codeup MR 时需额外配置：

| 变量 | 说明 | |------|------| | PORT | 服务端口，默认 3000 | | CODEUP_ACCESS_TOKEN | 云效个人访问令牌 | | CODEUP_ORGANIZATION_ID | 云效组织 ID | | DEEPSEEK_API_KEY | DeepSeek API Key | | WEBHOOK_SECRET | Webhook 签名校验（预留） |

完整项见 .env.example。

Webhook 服务（可选）

除本地 CLI 外，项目也支持 Codeup MR Webhook 自动审查：

Codeup MR → Webhook → 获取 Diff → 多 Reviewer 编排 → 回写 MR 评论

pnpm dev                    # 开发模式
pnpm build && pnpm start    # 生产模式

• 健康检查：GET /health
• Webhook：POST /webhook/codeup
• 收到 MR 事件后异步审查，立即返回 202

开发脚本

pnpm ai:review --deep   # 本地 AI 审查
pnpm dev                # Webhook 服务开发模式
pnpm build              # 编译
pnpm start              # 运行编译产物
pnpm typecheck          # 类型检查
pnpm lint               # ESLint
pnpm format             # Prettier 格式化

License

MIT