best-review

v0.5.13

Published

a day ago

AI-powered code review CLI for git changes

0High
0Medium
0Low

jerichoding

code-review ai cli git diff llm openai-compatible deepseek pull-request

best-review

best-review 是一个本地多 Agent 代码审查 CLI。它读取 Git diff，匹配规则，调度多个审查 Agent，直接调用 OpenAI Chat Completions 兼容模型服务或 DeepSeek API，最后输出风险结论、质量评分、CI 门禁结果和可落盘/上报的审查报告。

这个项目的重点不是替代人工 Review，而是把可重复的风险检查前置到本地、CI 和 GitLab Merge Request 流程里：

本地审查未提交变更、提交范围、指定文件或完整文件内容。
GitLab MR 远程审查，可按配置把问题回评到 MR 行内 discussion。
内置 general、bug-hunter、security-scan、performance-check、consistency-check、validation Agent。
支持用户级规则、共享 extends 规则包和项目级 skills/ 审查增强。
默认执行置信度过滤、去重、validation 复核，减少泛泛建议和误报。
支持显式自动修复严重风险，先生成 unified diff，并通过 git apply --check 后才写入。
生成本地 JSON 报告；GitLab 写操作默认关闭，需要通过配置开关显式开启。

快速开始

运行要求

Node.js 18+
npm
Git 仓库
可用模型服务：
- DeepSeek API
- OpenAI Chat Completions 兼容 API

安装和初始化

npm install -g best-review

best-review init
best-review review

best-review review 默认审查未提交变更；如果工作区没有变更，会回退审查最近一次提交。

如果使用 OpenAI 兼容服务：

best-review init --provider openai
best-review review

best-review init 会以选项式流程写入用户级 ~/.best-review/config.json，并提示是否把 GITLAB_TOKEN 写入同一个用户级配置文件；直接回车可跳过。

常用命令

# 审查未提交变更；工作区干净时审查最近一次提交
best-review review

# 审查 HEAD 相对 main 的变更
best-review review --base main

# 审查指定分支相对默认分支的变更；"." 表示当前分支
best-review review --branch .
best-review review --branch feature/login --base main

# 审查单个 commit 或连续多个 commit
best-review review --commit HEAD
best-review review --commit abc1234
best-review review --commit-range HEAD~3..HEAD

# 只审查指定文件的 Git 变更
best-review review --files src/auth.ts
best-review review --files src/auth.ts,src/user.ts --base main

# 审查完整文件内容，不依赖 Git diff
best-review review --files src/auth.ts --full

# 临时忽略目录或文件
best-review review --ignore dist,coverage/**,fixtures/**

# 控制 Agent、规则、严重级别和置信度
best-review review --agent security-scan
best-review review --exclude-agent performance-check
best-review review --rule code-security,config-security
best-review review --severity critical,high
best-review review --confidence 80

# 覆盖执行器或模型
best-review review --executor deepseek-api --model deepseek-v4-flash
best-review review --executor openai-compatible-api --model gpt-4o-mini

# 输出 JSON，适合 CI
best-review review --base main --json

# 检查当前配置是否可以直接 review
best-review config
best-review doctor

# 展示每个 pipeline 阶段耗时
best-review review --log-steps

# 显式自动修复严重风险
best-review review --fix-critical
best-review review --fix-severity critical,high --fix-dry-run
best-review review --fix-critical --fix-max-issues 3 --fix-patch-file ~/.best-review/fix.patch

# GitLab MR 远程审查（默认只读）
best-review review-mr https://gitlab.example.com/group/project/-/merge_requests/123

# 如需回评 MR discussion，先配置发布 token 并打开 gitlab.uploadEnabled
br init GITLAB_TOKEN

# 查看内置资产和执行器
best-review agents
best-review rules
best-review executors

# 运行 golden fixture 质量评测
best-review eval
best-review eval evals/golden --min-recall 0.9 --min-precision 0.75 --max-duplicate-rate 0.25

package.json 同时暴露 br 别名；本地已 link 后可用 br review。

模型服务

内置执行器只有两个：

| executor | 用途 | | --- | --- | | deepseek-api | DeepSeek Chat Completions API，默认执行器 | | openai-compatible-api | OpenAI Chat Completions 兼容服务 |

运行时模型配置统一来自用户级 ~/.best-review/config.json 的 llm 字段；.env / 环境变量仅作为旧配置兼容回退：

| 字段 | 说明 | | --- | --- | | llm.platform | deepseek 或 openai；未设置时默认 deepseek | | llm.baseUrl | 模型服务 base URL；未设置时使用平台默认值 | | llm.apiKey | 模型服务密钥，必填 | | llm.model | 模型名称；DeepSeek 默认 deepseek-v4-flash，OpenAI 默认 gpt-4o-mini |

默认情况下，review 和 validation 使用同一个 llm.model。如果希望 validation 单独使用更强模型，需要在用户级配置里显式配置阶段级 model。模型优先级为：

CLI --model > workflow run model > executors.<executor>.<stage>.model > llm.model > MODEL 环境变量 > 平台默认模型

审查和验证都会请求：

POST <llm.baseUrl>/chat/completions

执行器期望模型按 prompt 输出可解析的 <json>...</json> 结果。best-review review 和 best-review review-mr 会在真正审查前先检查执行器、API Key、模型配置，并发起一次轻量 Chat Completions 联通校验；失败会直接退出并给出修复建议。

旧配置中的 opencode-cli 会在加载时归一化为当前默认模型 API 执行器。新配置和命令行参数应使用 deepseek-api 或 openai-compatible-api。

配置

配置文件位于用户根目录下的 ~/.best-review/config.json。best-review init 会写入模型服务配置和基础执行器配置：

{
  "executor": "deepseek-api",
  "llm": {
    "platform": "deepseek",
    "baseUrl": "https://api.deepseek.com",
    "apiKey": "<your-api-key>",
    "model": "deepseek-v4-flash"
  },
  "gitlab": {
    "token": "<your-gitlab-token>",
    "uploadEnabled": false
  },
  "executors": {
    "openai-compatible-api": {
      "review": { "concurrency": 2 },
      "validation": { "timeout": 1800, "batchSize": 10, "concurrency": 1 }
    },
    "deepseek-api": {
      "review": { "concurrency": 2 },
      "validation": { "timeout": 1800, "batchSize": 10, "concurrency": 1 }
    }
  }
}

配置优先级：

默认值 < ~/.best-review/config.json < CLI 参数

可配置项包括：

{
  "extends": ["https://github.com/org/best-review-rules.git#v1.0.0"],
  "excludePatterns": ["dist/**", "coverage/**", "docs/**", "*.md"],
  "concurrency": 2,
  "executor": "deepseek-api",
  "llm": {
    "platform": "deepseek",
    "baseUrl": "https://api.deepseek.com",
    "apiKey": "<your-api-key>",
    "model": "deepseek-v4-flash"
  },
  "gitlab": {
    "token": "<your-gitlab-token>",
    "uploadEnabled": true
  },
  "executors": {
    "deepseek-api": {
      "review": { "concurrency": 2 },
      "validation": {
        "timeout": 1800,
        "batchSize": 10,
        "concurrency": 1
      }
    }
  },
  "agents": {
    "security-scan": { "enabled": true, "timeout": 1800 }
  },
  "rules": {
    "code-security": { "enabled": true, "agent": "security-scan" }
  },
  "skills": {
    "domain-review": { "enabled": true }
  },
  "reporting": {
    "enabled": false,
    "includeDiffs": false,
    "failOnError": false
  },
  "qualityScore": {
    "base": 100,
    "min": 0,
    "weights": {
      "critical": 40,
      "high": 15,
      "medium": 6,
      "low": 2
    }
  }
}

可选：让 validation 使用更强模型时，只在配置里添加阶段级 model：

{
  "executors": {
    "deepseek-api": {
      "review": { "model": "<cheap-review-model>", "concurrency": 2 },
      "validation": { "model": "<strong-validation-model>", "timeout": 1800 }
    }
  }
}

workflows 只允许配置模型，不允许在 workflow 条目里配置 executor：

{
  "workflows": {
    "review": [{ "model": "gpt-4o-mini" }, { "model": "deepseek-v4-flash" }],
    "validation": [{ "model": "gpt-4o-mini" }]
  }
}

审查流程

默认 pipeline 顺序：

flowchart LR
    A["Git diff / MR diff"] --> B["load-rules"]
    B --> C["match-rules"]
    C --> D["review"]
    D --> E["aggregate-results"]
    E --> F["confidence-filter"]
    F --> G["deduplication"]
    G --> H["validation"]
    H --> I["gitlab-mr-issue-filter"]
    I --> J["autofix"]
    J --> K["reporting"]
    K --> L["gitlab-reporting"]

关键行为：

filterReviewableDiffs() 默认跳过二进制、生成物、文档和命中排除规则的文件。
本地 review 支持未提交变更、--base/--head、--branch、--commit、--commit-range、--files 和 --full；互斥或不完整的参数组合会在进入 pipeline 前直接拒绝。
--commit <ref> 等价于比较 <ref>^ 和 <ref>；--commit-range <oldest>..<newest> 会包含两端 commit，要求 <oldest> 是 <newest> 的祖先。
本地 review 会补充变更文件全文和一层相对依赖上下文，避免模型只看 diff。
diff 输入默认压缩，只保留 hunk 行号、变更行和少量上下文。
默认是多 Agent 独立审查；设置 BEST_REVIEW_MULTI_AGENT=false 可把多个专业 Agent 合并成一次快速审查。
confidence-filter 默认按最小置信度 70 过滤低质量问题，可用 --confidence 调整。
validation Agent 会复核候选问题并过滤误报；--skip-validation 会跳过该阶段。
自动修复必须显式开启，并且不能和 --skip-validation 同时使用。
reporting 会尽量执行，把当前上下文保存为本地 JSON 报告。

Agent、规则和 Skill

内置 Agent：

| Agent | 关注点 | | --- | --- | | general | 通用质量、可读性、职责边界和可维护性 | | bug-hunter | 逻辑错误、边界条件、异常路径和运行时风险 | | security-scan | 认证授权、敏感信息、注入、越权和真实攻击路径 | | performance-check | 复杂度、重复调用、资源使用和真实规模下的性能退化 | | consistency-check | 命名、返回形态、接口约定和架构模式一致性 | | validation | 复核其他 Agent 的发现，过滤误报 |

默认规则在 src/defaults/rules/，可审查 TypeScript、JavaScript、Python、Go、Rust、Java、Ruby、PHP、Kotlin、Shell、C/C++ 以及常见配置文件。

自定义规则可以放在：

~/.best-review/rules/*.md

规则示例：

---
name: input-validation
description: 所有用户输入必须使用 schema 校验
version: 1
patterns:
  - "src/**/*.ts"
agent: security-scan
---

发现新增入口参数、请求体、环境变量读取时，检查是否有集中 schema 校验。
只报告有实际风险的缺失校验，不报告已经被上游可靠校验的代码。

自定义 Agent 可以放在：

~/.best-review/agents/*.md

规则和 Agent 加载优先级：

defaults < extends < user

共享规则包：

best-review extends install https://github.com/org/best-review-rules.git
best-review extends install --force
best-review extends list
best-review extends remove https://github.com/org/best-review-rules.git

项目级 Skill 放在 skills/<skill-name>/SKILL.md，可选附带 references/*.md 和 agents/agent.yaml。启用后会被注入 review prompt，适合放业务域约束、框架约定或团队审查标准。

GitLab Merge Request

review-mr 会直接读取 GitLab MR diff 和远程文件内容，运行同一套 pipeline。GitLab discussion 回评属于写操作，默认关闭，需要显式开启。

best-review review-mr https://gitlab.example.com/group/project/-/merge_requests/123
best-review review-mr <mr-url> --agent security-scan --log-steps
best-review review-mr <mr-url> --executor deepseek-api --model deepseek-v4-flash

# 如需回评 MR discussion，再初始化发布 token
br init GITLAB_TOKEN

如需把审查结果回评到 MR，先在用户级配置打开上传开关，并提供发布 discussion 的 GITLAB_TOKEN：

{
  "gitlab": {
    "uploadEnabled": true,
    "token": "<your-gitlab-token>"
  }
}

也可以在 CI 中临时设置 BEST_REVIEW_GITLAB_ENABLED=true。只有上传开关开启时，review-mr 才会要求 GITLAB_TOKEN；否则它只读取 MR 并输出本地结果。

review-mr 会使用内置的 BEST_REVIEW_HISTORY_USER_TOKEN 读取 MR。BEST_REVIEW_HISTORY_REMOTE、BEST_REVIEW_HISTORY_BRANCH、GITLAB_HOST 已内置默认值，无需再写入项目 .env。

可选变量：

| 变量 | 说明 | | --- | --- | | BEST_REVIEW_HISTORY_USER_TOKEN | 已内置的 review 记录 token；如需临时替换，可通过环境变量覆盖 | | GITLAB_TOKEN | 发布 MR discussion 的 token；仅在上传开关开启时需要 | | GITLAB_HOST | GitLab API host 覆盖值；默认 https://git.bestfulfill.tech，可传完整 /api/v4 | | BEST_REVIEW_GITLAB_ENABLED | GitLab discussion 上传开关；设置为 true/false 可覆盖 gitlab.uploadEnabled | | GITLAB_PROJECT_ID / CI_PROJECT_ID | 非 review-mr 模式下用于定位项目 | | GITLAB_MR_IID / CI_MERGE_REQUEST_IID | 非 review-mr 模式下用于定位 MR |

GitLab Reporting 会优先发布行内 discussion；无法映射到 diff position 的问题会汇总到 summary discussion。review-mr 模式下会清理旧的 best-review comment marker，避免重复刷屏。

自动修复

自动修复默认关闭，必须显式开启：

# 只修复 critical
best-review review --fix-critical

# 修复 critical/high，但只校验补丁，不写入文件
best-review review --fix-severity critical,high --fix-dry-run

# 限制修复数量，并保存补丁
best-review review --fix-critical --fix-max-issues 3 --fix-patch-file ~/.best-review/fix.patch

安全约束：

只在 validation 之后运行。
拒绝 --skip-validation。
只读取目标问题涉及的文件。
只接受 unified diff。
拒绝二进制、新增、删除、重命名、复制文件变更。
补丁只能修改目标问题涉及文件。
先执行 git apply --check，通过后才写入文件。
--fix-dry-run 只生成并校验补丁，不写入源码。

可调变量：

BEST_REVIEW_FIX_MAX_ISSUES=5
BEST_REVIEW_FIX_MAX_FILE_CHARS=60000

输出、质量评分和 CI

终端输出会包含：

pipeline 是否成功。
Agent 成功/失败数量。
模型调用次数、缓存命中次数、token 用量和缓存节省估算。
风险结论。
原始问题数、置信度过滤后、validation 后、最终计分问题数。
质量评分。
按文件分组的问题详情。

风险枚举：

| 内部 severity | 终端标签 | | --- | --- | | critical | 严重风险 | | high | 高风险 | | medium | 中风险 | | low | 低风险 |

示例风险结论：

风险结论：严重 1，高 2，中 0，低 3；整体风险：严重

JSON 输出包含：

stats
riskSummary
qualityScore
reviewSummary
rawIssues
finalIssues
issues
files
autofix
usage

CI 建议：

best-review review --base origin/main --json

当 pipeline 失败或最终存在 critical 问题时，CLI 会返回非 0 exit code。high、medium、low 默认不阻断，可由 CI 根据 JSON 自定义策略。

Reporting

每次 best-review review 都会保存一份本地 JSON 报告，默认目录：

~/.best-review/reports/

报告包含仓库信息、模型、风险结论、质量评分、最终问题和 diff 摘要。默认不保存完整 diff。

默认只保留本地报告，不再因为配置了历史仓库地址而自动上传远端。如果确需把本地 review 结果归档到 Git 仓库，需要显式开启：

BEST_REVIEW_HISTORY=true

历史归档默认使用源码内置地址和分支：

BEST_REVIEW_HISTORY_REMOTE=https://git.bestfulfill.tech/jericho/review-history.git
BEST_REVIEW_HISTORY_BRANCH=review-log

也可以通过环境变量覆盖为自己的仓库地址和分支。

上传后的文件会按项目和 GitLab 用户分组：

projects/<group>/<project>/<gitlab-user>/<timestamp>-<run-id>.json

历史归档只上传 best-review review 的本地结果；best-review review-mr 不会上传到历史仓库。

上传成功后，本地 JSON 会被删除，避免长期占用磁盘；上传失败时会保留本地文件，方便排查。

也可以通过用户级 ~/.best-review/config.json 配置：

{
  "reporting": {
    "historyEnabled": true,
    "historyRemote": "[email protected]:team/review-history.git",
    "historyBranch": "review-log"
  }
}

historyEnabled 需要显式设置为 true 才会开启历史归档；仅配置 historyRemote 不会自动上传。

如果还需要把报告 POST 到内部效能系统，再配置 Reporting URL：

BEST_REVIEW_REPORT_URL=https://efficiency.example.com/api/ai-review/usages
BEST_REVIEW_REPORT_TOKEN=replace-with-token

默认上报失败不会阻断 review。CI 里想让上报失败直接失败，可以设置 BEST_REVIEW_REPORT_FAIL_ON_ERROR=true。

审查质量评测

best-review eval 会实时调用当前模型跑 golden fixtures，流程包含 review、confidence filter、deduplication 和 validation，用于评估 prompt、规则或模型变更是否造成质量回归。

best-review eval
best-review eval evals/golden --json
best-review eval --model gpt-4o-mini --min-recall 0.9 --min-precision 0.75 --max-duplicate-rate 0.25
best-review eval --use-cache

fixture 支持：

diffs：输入 Git diff。
supplementalContextFiles：可选补充上下文。
expectedIssues：最终应该保留的问题。
expectedFilteredIssues：如果模型产出，应该被过滤的问题。
thresholds：单 fixture 门禁。

主要指标：

precision、recall、f1
falsePositives、falseNegatives
severityMismatches
rawDuplicateRate
validationRetentionRate
reviewCoverageRate
expectedFilteredObserved、expectedFilteredLeaked

默认 eval 禁用 review/validation 缓存；调试成本时可用 --use-cache。

性能和成本控制

# 关闭缓存
BEST_REVIEW_CACHE=false best-review review

# 兼容旧变量：关闭缓存
BEST_REVIEW_DISABLE_CACHE=true best-review review

# 调整 batch token 和文件数量
BEST_REVIEW_BATCH_TOKENS=36000 best-review review
BEST_REVIEW_MAX_FILES_PER_BATCH=20 best-review review

# 使用完整 diff，不做压缩
BEST_REVIEW_FULL_DIFF=true best-review review

# 调整 diff 压缩上下文和单文件输入上限
BEST_REVIEW_DIFF_CONTEXT_LINES=2 best-review review
BEST_REVIEW_MAX_DIFF_CHARS_PER_FILE=30000 best-review review

# 合并多个专业 Agent 为一次快速审查
BEST_REVIEW_MULTI_AGENT=false best-review review

# 关闭智能规则路由
BEST_REVIEW_DISABLE_SMART_ROUTING=true best-review review

默认缓存目录：

~/.best-review/cache/review
~/.best-review/cache/validation

缓存 key 包含模型、base URL、temperature、prompt、规则和 diff 输入。相同输入会复用成功结果，并在终端/JSON 中统计缓存命中和节省 token。

开发

npm install

# 直接运行 TypeScript CLI
npm run dev -- review --base main

# 类型检查、测试、构建
npm run ts-check
npm test
npm run build

# lint 和格式化
npm run lint
npm run format:check

# 本地 link 后用全局命令调试
npm run link:local
best-review review --base main

常用源码入口：

| 路径 | 作用 | | --- | --- | | src/cli/ | CLI 命令、参数校验、review/review-mr runner | | src/config/ | 默认配置、用户级配置、旧配置归一化 | | src/providers/ | 模型运行时配置解析 | | src/executors/ | OpenAI-compatible 和 DeepSeek API 执行器 | | src/stages/ | pipeline 各阶段 | | src/review/ | issue 解析、格式化、缓存、评分、用量统计 | | src/git/ | 本地 diff、文件过滤、补充上下文 | | src/gitlab/ | GitLab MR 数据读取 | | src/defaults/agents/ | 内置 Agent prompt | | src/defaults/rules/ | 内置规则 | | src/eval/ | golden fixture 评测 |

更多设计说明：

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

best-review

快速开始

运行要求

安装和初始化

常用命令

模型服务

配置

审查流程

Agent、规则和 Skill

GitLab Merge Request

自动修复

输出、质量评分和 CI

Reporting

审查质量评测

性能和成本控制

开发

License