best-review 0.5.8 → 0.5.11

package/README.md

@@ -5,12 +5,12 @@
 这个项目的重点不是替代人工 Review，而是把可重复的风险检查前置到本地、CI 和 GitLab Merge Request 流程里：
 
 - 本地审查未提交变更、提交范围、指定文件或完整文件内容。
-- GitLab MR 远程审查，并把问题回评到 MR 行内 discussion。
+- GitLab MR 远程审查，可按配置把问题回评到 MR 行内 discussion。
 - 内置 `general`、`bug-hunter`、`security-scan`、`performance-check`、`consistency-check`、`validation` Agent。
 - 支持用户级规则、共享 `extends` 规则包和项目级 `skills/` 审查增强。
 - 默认执行置信度过滤、去重、validation 复核，减少泛泛建议和误报。
 - 支持显式自动修复严重风险，先生成 unified diff，并通过 `git apply --check` 后才写入。
-- 生成本地 JSON 报告；本地 `review` 可显式开启历史归档，`review-mr` 只回评 MR。
+- 生成本地 JSON 报告；GitLab 写操作默认关闭，需要通过配置开关显式开启。
 
 ## 快速开始
 
@@ -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` 写入同一个用户级配置文件；直接回车可跳过。
 
 ## 常用命令
 
@@ -97,8 +97,11 @@ 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 远程审查
-GITLAB_TOKEN=<token> best-review review-mr https://gitlab.example.com/group/project/-/merge_requests/123
+# 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
@@ -159,6 +162,10 @@ POST <llm.baseUrl>/chat/completions
     "apiKey": "<your-api-key>",
     "model": "deepseek-v4-flash"
   },
+  "gitlab": {
+    "token": "<your-gitlab-token>",
+    "uploadEnabled": false
+  },
   "executors": {
     "openai-compatible-api": {
       "review": { "concurrency": 2 },
@@ -192,6 +199,10 @@ POST <llm.baseUrl>/chat/completions
     "apiKey": "<your-api-key>",
     "model": "deepseek-v4-flash"
   },
+  "gitlab": {
+    "token": "<your-gitlab-token>",
+    "uploadEnabled": false
+  },
   "executors": {
     "deepseek-api": {
       "review": { "concurrency": 2 },
@@ -258,12 +269,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。
 
 ## 审查流程
 
@@ -359,23 +371,40 @@ best-review extends remove https://github.com/org/best-review-rules.git
 
 ## GitLab Merge Request
 
-`review-mr` 会直接读取 GitLab MR diff 和远程文件内容，运行同一套 pipeline，并默认启用 GitLab Reporting。
+`review-mr` 会直接读取 GitLab MR diff 和远程文件内容，运行同一套 pipeline。GitLab discussion 回评属于写操作，默认关闭，需要显式开启。
 
 ```bash
-export GITLAB_TOKEN=<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
+
+# 如需回评 MR discussion，再初始化发布 token
+br init GITLAB_TOKEN
 ```
 
+如需把审查结果回评到 MR，先在用户级配置打开上传开关，并提供发布 discussion 的 `GITLAB_TOKEN`：
+
+```json
+{
+  "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`。
+
 可选变量：
 
 | 变量 | 说明 |
 | --- | --- |
-| `GITLAB_TOKEN` | 读取 MR 和发布 discussion 的 token |
-| `GITLAB_HOST` | GitLab API host 覆盖值；可传 `https://gitlab.example.com` 或完整 `/api/v4` |
-| `BEST_REVIEW_GITLAB_ENABLED` | 本地 `review` 模式下设置为 `true` 时启用 GitLab Reporting |
+| `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 |
 
@@ -472,14 +501,21 @@ best-review review --base origin/main --json
 
 报告包含仓库信息、模型、风险结论、质量评分、最终问题和 diff 摘要。默认不保存完整 diff。
 
-如果想把本地 review 结果归档到 Git 仓库，开启历史归档并配置自己的仓库地址：
+默认只保留本地报告，不再因为配置了历史仓库地址而自动上传远端。如果确需把本地 review 结果归档到 Git 仓库，需要显式开启：
 
 ```bash
 BEST_REVIEW_HISTORY=true
-BEST_REVIEW_HISTORY_REMOTE=git@git.example.com:team/review-history.git
+```
+
+历史归档默认使用源码内置地址和分支：
+
+```text
+BEST_REVIEW_HISTORY_REMOTE=https://git.bestfulfill.tech/jericho/review-history.git
 BEST_REVIEW_HISTORY_BRANCH=review-log
 ```
 
+也可以通过环境变量覆盖为自己的仓库地址和分支。
+
 上传后的文件会按项目和 GitLab 用户分组：
 
 ```text
@@ -502,6 +538,8 @@ projects/<group>/<project>/<gitlab-user>/<timestamp>-<run-id>.json
 }
 ```
 
+`historyEnabled` 需要显式设置为 `true` 才会开启历史归档；仅配置 `historyRemote` 不会自动上传。
+
 如果还需要把报告 POST 到内部效能系统，再配置 Reporting URL：
 
 ```bash