best-review 0.5.7 → 0.5.8

package/README.md

@@ -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
@@ -282,6 +287,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 合并成一次快速审查。
@@ -457,85 +464,52 @@ 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=true
 BEST_REVIEW_HISTORY_REMOTE=git@git.example.com:team/review-history.git
+BEST_REVIEW_HISTORY_BRANCH=review-log
 ```
 
-历史记录按项目和 GitLab 用户分组，路径形如：
+上传后的文件会按项目和 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。
+历史归档只上传 `best-review review` 的本地结果；`best-review review-mr` 不会上传到历史仓库。
 
-历史归档显式开启且上传成功后，本地 JSON 会被删除，避免长期占用用户电脑空间。如果历史上传失败，或主 Reporting 上报失败，本地 JSON 会保留，方便排查或手动处理。
+上传成功后，本地 JSON 会被删除，避免长期占用磁盘；上传失败时会保留本地文件，方便排查。
 
-`best-review review-mr` 的结果不会上传到审查历史仓库，也不会因为该历史上传逻辑删除本地报告；MR 模式仍通过 GitLab Reporting 把问题回评到 MR。
-
-配置上报：
+也可以通过用户级 `~/.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,
+    "historyEnabled": true,
     "historyRemote": "git@git.example.com:team/review-history.git",
     "historyBranch": "review-log"
   }
 }
 ```
 
-环境变量覆盖：
+如果还需要把报告 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`。
 
 ## 审查质量评测