best-review 0.5.5 → 0.5.7

package/README.md

@@ -7,10 +7,10 @@
 - 本地审查未提交变更、提交范围、指定文件或完整文件内容。
 - GitLab MR 远程审查，并把问题回评到 MR 行内 discussion。
 - 内置 `general`、`bug-hunter`、`security-scan`、`performance-check`、`consistency-check`、`validation` Agent。
-- 支持项目规则、全局规则、共享 `extends` 规则包和项目级 `skills/` 审查增强。
+- 支持用户级规则、共享 `extends` 规则包和项目级 `skills/` 审查增强。
 - 默认执行置信度过滤、去重、validation 复核，减少泛泛建议和误报。
 - 支持显式自动修复严重风险，先生成 unified diff，并通过 `git apply --check` 后才写入。
-- 生成本地 JSON 报告，可选上报到内部效能统计系统。
+- 生成本地 JSON 报告；本地 `review` 可显式开启历史归档，`review-mr` 只回评 MR。
 
 ## 快速开始
 
@@ -90,7 +90,7 @@ 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
+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
@@ -207,7 +207,6 @@ POST <llm.baseUrl>/chat/completions
     "domain-review": { "enabled": true }
   },
   "reporting": {
-    "localDir": ".best-review/reports",
     "enabled": false,
     "includeDiffs": false,
     "failOnError": false
@@ -309,7 +308,6 @@ flowchart LR
 自定义规则可以放在：
 
 ```text
-.best-review/rules/*.md
 ~/.best-review/rules/*.md
 ```
 
@@ -332,14 +330,13 @@ agent: security-scan
 自定义 Agent 可以放在：
 
 ```text
-.best-review/agents/*.md
 ~/.best-review/agents/*.md
 ```
 
 规则和 Agent 加载优先级：
 
 ```text
-defaults < extends < user < project
+defaults < extends < user
 ```
 
 共享规则包：
@@ -389,7 +386,7 @@ 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
+best-review review --fix-critical --fix-max-issues 3 --fix-patch-file ~/.best-review/fix.patch
 ```
 
 安全约束：
@@ -463,22 +460,42 @@ best-review review --base origin/main --json
 每次 review 都会尽量生成本地报告，默认目录：
 
 ```text
-.best-review/reports/
+~/.best-review/reports/
 ```
 
 报告包含仓库信息、base/head、模型、Agent 结果、阶段结果、风险结论、质量评分、issue audit trail、最终问题和 diff 摘要。默认不保存完整 diff。
 
+本地 `best-review review` 默认只保存本地报告。显式设置 `BEST_REVIEW_HISTORY=true` 或 `reporting.historyEnabled: true` 后，会把报告上传到你配置的审查历史仓库，默认分支为 `review-log`。远端地址必须显式设置，避免把报告误传到不属于你的仓库：
+
+```text
+BEST_REVIEW_HISTORY_REMOTE=git@git.example.com:team/review-history.git
+```
+
+历史记录按项目和 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-mr` 的结果不会上传到审查历史仓库，也不会因为该历史上传逻辑删除本地报告；MR 模式仍通过 GitLab Reporting 把问题回评到 MR。
+
 配置上报：
 
 ```json
 {
   "reporting": {
-    "localDir": ".best-review/reports",
     "enabled": true,
     "url": "https://efficiency.example.com/api/ai-review/usages",
     "token": "replace-with-token",
     "includeDiffs": false,
-    "failOnError": false
+    "failOnError": false,
+    "historyEnabled": false,
+    "historyRemote": "git@git.example.com:team/review-history.git",
+    "historyBranch": "review-log"
   }
 }
 ```
@@ -486,13 +503,38 @@ best-review review --base origin/main --json
 环境变量覆盖：
 
 ```bash
-BEST_REVIEW_REPORT_DIR=.best-review/reports
+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`。
 
 ## 审查质量评测
@@ -556,8 +598,8 @@ BEST_REVIEW_DISABLE_SMART_ROUTING=true best-review review
 默认缓存目录：
 
 ```text
-.best-review/cache/review
-.best-review/cache/validation
+~/.best-review/cache/review
+~/.best-review/cache/validation
 ```
 
 缓存 key 包含模型、base URL、temperature、prompt、规则和 diff 输入。相同输入会复用成功结果，并在终端/JSON 中统计缓存命中和节省 token。