best-review 0.5.7 → 0.5.9

package/README.md

@@ -10,7 +10,7 @@
 - 支持用户级规则、共享 `extends` 规则包和项目级 `skills/` 审查增强。
 - 默认执行置信度过滤、去重、validation 复核，减少泛泛建议和误报。
 - 支持显式自动修复严重风险，先生成 unified diff，并通过 `git apply --check` 后才写入。
-- 生成本地 JSON 报告；本地 `review` 可显式开启历史归档，`review-mr` 只回评 MR。
+- 生成本地 JSON 报告；本地 `review` 配置历史仓库后会自动归档，`review-mr` 只回评 MR。
 
 ## 快速开始
 
@@ -41,7 +41,7 @@ best-review init --provider openai
 best-review review
 ```
 
-`best-review init` 会以选项式流程写入用户级 `~/.best-review/config.json`。`.best-review.json` 已弃用，CLI 不再生成或默认读取它。
+`best-review init` 会以选项式流程写入用户级 `~/.best-review/config.json`，并提示是否把 `GITLAB_TOKEN` 写入同一个用户级配置文件；直接回车可跳过。
 
 ## 常用命令
 
@@ -56,6 +56,11 @@ 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
@@ -93,7 +98,8 @@ 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 远程审查
-GITLAB_TOKEN=<token> best-review review-mr https://gitlab.example.com/group/project/-/merge_requests/123
+br init GITLAB_TOKEN
+best-review review-mr https://gitlab.example.com/group/project/-/merge_requests/123
 
 # 查看内置资产和执行器
 best-review agents
@@ -154,6 +160,9 @@ POST <llm.baseUrl>/chat/completions
     "apiKey": "<your-api-key>",
     "model": "deepseek-v4-flash"
   },
+  "gitlab": {
+    "token": "<your-gitlab-token>"
+  },
   "executors": {
     "openai-compatible-api": {
       "review": { "concurrency": 2 },
@@ -187,6 +196,9 @@ POST <llm.baseUrl>/chat/completions
     "apiKey": "<your-api-key>",
     "model": "deepseek-v4-flash"
   },
+  "gitlab": {
+    "token": "<your-gitlab-token>"
+  },
   "executors": {
     "deepseek-api": {
       "review": { "concurrency": 2 },
@@ -253,12 +265,13 @@ POST <llm.baseUrl>/chat/completions
 ```bash
 best-review config
 best-review init
+br init GITLAB_TOKEN
 best-review config show
 best-review config edit
 best-review doctor
 ```
 
-`best-review init` 用来初始化或更新 `~/.best-review/config.json`；`best-review config` 会用当前用户级配置做一次简化诊断；`best-review doctor` 输出同一套诊断结果，适合在本地或 CI 中确认当前机器是否可以直接执行 review。
+`best-review init` 用来初始化或更新 `~/.best-review/config.json`；`br init GITLAB_TOKEN` 只配置用户级 `gitlab.token`，不会要求重新填写模型服务。`best-review config` 会用当前用户级配置做一次简化诊断；`best-review doctor` 输出同一套诊断结果，适合在本地或 CI 中确认当前机器是否可以直接执行 review。
 
 ## 审查流程
 
@@ -282,6 +295,8 @@ flowchart LR
 关键行为：
 
 - `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 合并成一次快速审查。
@@ -355,18 +370,23 @@ best-review extends remove https://github.com/org/best-review-rules.git
 `review-mr` 会直接读取 GitLab MR diff 和远程文件内容，运行同一套 pipeline，并默认启用 GitLab Reporting。
 
 ```bash
-export GITLAB_TOKEN=<token>
+br init GITLAB_TOKEN
 
 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
 ```
 
+如果运行 `review-mr` 时当前环境和用户级配置都没有 `GITLAB_TOKEN`，CLI 会在交互式终端中提示填写并写入 `~/.best-review/config.json`；直接回车会取消本次 MR 审查。CI 中仍可通过 `export GITLAB_TOKEN=<token>` 或平台变量注入。
+
+`review-mr` 启动前会先校验内置 GitLab 配置是否存在：`BEST_REVIEW_HISTORY_REMOTE`、`BEST_REVIEW_HISTORY_BRANCH`、`GITLAB_HOST`、`BEST_REVIEW_HISTORY_USER_TOKEN`。其中 `BEST_REVIEW_HISTORY_USER_TOKEN` 只用于读取 MR 和解析 GitLab 用户；`GITLAB_TOKEN` 只用于向 MR 发布 discussion。
+
 可选变量：
 
 | 变量 | 说明 |
 | --- | --- |
-| `GITLAB_TOKEN` | 读取 MR 和发布 discussion 的 token |
+| `BEST_REVIEW_HISTORY_USER_TOKEN` | 读取 MR 和解析 GitLab 用户的内置 token |
+| `GITLAB_TOKEN` | 发布 MR discussion 的 token，需要用户自行配置 |
 | `GITLAB_HOST` | GitLab API host 覆盖值；可传 `https://gitlab.example.com` 或完整 `/api/v4` |
 | `BEST_REVIEW_GITLAB_ENABLED` | 本地 `review` 模式下设置为 `true` 时启用 GitLab Reporting |
 | `GITLAB_PROJECT_ID` / `CI_PROJECT_ID` | 非 `review-mr` 模式下用于定位项目 |
@@ -457,85 +477,58 @@ best-review review --base origin/main --json
 
 ## Reporting
 
-每次 review 都会尽量生成本地报告，默认目录：
+每次 `best-review review` 都会保存一份本地 JSON 报告，默认目录：
 
 ```text
 ~/.best-review/reports/
 ```
 
-报告包含仓库信息、base/head、模型、Agent 结果、阶段结果、风险结论、质量评分、issue audit trail、最终问题和 diff 摘要。默认不保存完整 diff。
+报告包含仓库信息、模型、风险结论、质量评分、最终问题和 diff 摘要。默认不保存完整 diff。
 
-本地 `best-review review` 默认只保存本地报告。显式设置 `BEST_REVIEW_HISTORY=true` 或 `reporting.historyEnabled: true` 后，会把报告上传到你配置的审查历史仓库，默认分支为 `review-log`。远端地址必须显式设置，避免把报告误传到不属于你的仓库：
+如果想把本地 review 结果归档到 Git 仓库，配置自己的仓库地址即可启用历史归档：
 
-```text
+```bash
 BEST_REVIEW_HISTORY_REMOTE=git@git.example.com:team/review-history.git
+BEST_REVIEW_HISTORY_BRANCH=review-log
 ```
 
-历史记录按项目和 GitLab 用户分组，路径形如：
+如需临时关闭历史归档，可以设置：
+
+```bash
+BEST_REVIEW_HISTORY=false
+```
+
+上传后的文件会按项目和 GitLab 用户分组：
 
 ```text
 projects/<group>/<project>/<gitlab-user>/<timestamp>-<run-id>.json
 ```
 
-项目优先从 `GITLAB_PROJECT_PATH` / `CI_PROJECT_PATH` 读取，其次解析当前仓库 `origin` remote，最后退回仓库目录名。GitLab 用户优先读取 `BEST_REVIEW_GITLAB_USER` / `GITLAB_USER_LOGIN` / `GITLAB_USER_NAME` / `GITLAB_USER_EMAIL`；如果设置了 `GITLAB_TOKEN`，只会在同时存在显式 `GITLAB_HOST`、`CI_SERVER_URL` 或 `CI_SERVER_HOST` 时调用 GitLab `/api/v4/user` 获取当前用户，避免把 token 发给从仓库 remote 推导出的主机。历史仓库使用 HTTPS 远端时，也只会在远端 host 与显式 GitLab host 一致时，临时把 `GITLAB_TOKEN` 提供给 Git clone/push。
-
-历史归档显式开启且上传成功后，本地 JSON 会被删除，避免长期占用用户电脑空间。如果历史上传失败，或主 Reporting 上报失败，本地 JSON 会保留，方便排查或手动处理。
+历史归档只上传 `best-review review` 的本地结果；`best-review review-mr` 不会上传到历史仓库。
 
-`best-review review-mr` 的结果不会上传到审查历史仓库，也不会因为该历史上传逻辑删除本地报告；MR 模式仍通过 GitLab Reporting 把问题回评到 MR。
+上传成功后，本地 JSON 会被删除，避免长期占用磁盘；上传失败时会保留本地文件，方便排查。
 
-配置上报：
+也可以通过用户级 `~/.best-review/config.json` 配置：
 
 ```json
 {
   "reporting": {
-    "enabled": true,
-    "url": "https://efficiency.example.com/api/ai-review/usages",
-    "token": "replace-with-token",
-    "includeDiffs": false,
-    "failOnError": false,
-    "historyEnabled": false,
     "historyRemote": "git@git.example.com:team/review-history.git",
     "historyBranch": "review-log"
   }
 }
 ```
 
-环境变量覆盖：
+`historyEnabled` 仍可显式设置为 `true`；配置了 `historyRemote` 时不再需要额外开启。
+
+如果还需要把报告 POST 到内部效能系统，再配置 Reporting URL：
 
 ```bash
-BEST_REVIEW_REPORT_DIR=$HOME/.best-review/reports
 BEST_REVIEW_REPORT_URL=https://efficiency.example.com/api/ai-review/usages
 BEST_REVIEW_REPORT_TOKEN=replace-with-token
-BEST_REVIEW_REPORT_INCLUDE_DIFFS=false
-BEST_REVIEW_REPORT_FAIL_ON_ERROR=false
-```
-
-审查历史仓库相关环境变量：
-
-```bash
-# 显式开启本地 review 历史归档；默认关闭
-BEST_REVIEW_HISTORY=true
-
-# 如需覆盖配置并关闭历史归档
-BEST_REVIEW_HISTORY=false
-
-# 审查历史仓库地址，启用历史归档时必须显式设置
-BEST_REVIEW_HISTORY_REMOTE=git@git.example.com:team/review-history.git
-
-# 审查历史分支；默认 review-log
-BEST_REVIEW_HISTORY_BRANCH=review-log
-
-# 覆盖临时 clone 目录；默认在 ~/.best-review/tmp 下创建并自动清理
-BEST_REVIEW_HISTORY_TMP_DIR=$HOME/.best-review/tmp
-
-# 显式指定归档使用的 GitLab 用户名
-BEST_REVIEW_GITLAB_USER=alice
-
-# HTTPS 远端认证可使用 GITLAB_TOKEN；如需覆盖 Git 用户名可单独设置
-BEST_REVIEW_HISTORY_GIT_USERNAME=alice
 ```
 
-上报失败默认不阻断 review；如果 CI 要求上报失败即失败，设置 `failOnError: true` 或 `BEST_REVIEW_REPORT_FAIL_ON_ERROR=true`。
+默认上报失败不会阻断 review。CI 里想让上报失败直接失败，可以设置 `BEST_REVIEW_REPORT_FAIL_ON_ERROR=true`。
 
 ## 审查质量评测