best-review 0.5.4

package/README.md

@@ -0,0 +1,611 @@
+# 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 报告，可选上报到内部效能统计系统。
+
+## 快速开始
+
+### 运行要求
+
+- Node.js 18+
+- npm
+- Git 仓库
+- 可用模型服务：
+  - DeepSeek API
+  - OpenAI Chat Completions 兼容 API
+
+### 安装和初始化
+
+```bash
+npm install -g best-review
+
+best-review init
+best-review review
+```
+
+`best-review review` 默认审查未提交变更；如果工作区没有变更，会回退审查最近一次提交。
+
+如果使用 OpenAI 兼容服务：
+
+```bash
+best-review init --provider openai
+best-review review
+```
+
+`best-review init` 会以选项式流程写入用户级 `~/.best-review/config.json`。`.best-review.json` 已弃用，CLI 不再生成或默认读取它。
+
+## 常用命令
+
+```bash
+# 审查未提交变更；工作区干净时审查最近一次提交
+best-review review
+
+# 审查 HEAD 相对 main 的变更
+best-review review --base main
+
+# 审查指定分支相对默认分支的变更；"." 表示当前分支
+best-review review --branch .
+best-review review --branch feature/login --base main
+
+# 只审查指定文件的 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 远程审查
+GITLAB_TOKEN=<token> best-review review-mr https://gitlab.example.com/group/project/-/merge_requests/123
+
+# 查看内置资产和执行器
+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`。模型优先级为：
+
+```text
+CLI --model > workflow run model > executors.<executor>.<stage>.model > llm.model > MODEL 环境变量 > 平台默认模型
+```
+
+审查和验证都会请求：
+
+```text
+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` 会写入模型服务配置和基础执行器配置：
+
+```json
+{
+  "executor": "deepseek-api",
+  "llm": {
+    "platform": "deepseek",
+    "baseUrl": "https://api.deepseek.com",
+    "apiKey": "<your-api-key>",
+    "model": "deepseek-v4-flash"
+  },
+  "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 }
+    }
+  }
+}
+```
+
+配置优先级：
+
+```text
+默认值 < ~/.best-review/config.json < CLI 参数
+```
+
+可配置项包括：
+
+```json
+{
+  "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"
+  },
+  "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": {
+    "localDir": ".best-review/reports",
+    "enabled": false,
+    "includeDiffs": false,
+    "failOnError": false
+  },
+  "qualityScore": {
+    "base": 100,
+    "min": 0,
+    "weights": {
+      "critical": 40,
+      "high": 15,
+      "medium": 6,
+      "low": 2
+    }
+  }
+}
+```
+
+可选：让 validation 使用更强模型时，只在配置里添加阶段级 `model`：
+
+```json
+{
+  "executors": {
+    "deepseek-api": {
+      "review": { "model": "<cheap-review-model>", "concurrency": 2 },
+      "validation": { "model": "<strong-validation-model>", "timeout": 1800 }
+    }
+  }
+}
+```
+
+`workflows` 只允许配置模型，不允许在 workflow 条目里配置 executor：
+
+```json
+{
+  "workflows": {
+    "review": [{ "model": "gpt-4o-mini" }, { "model": "deepseek-v4-flash" }],
+    "validation": [{ "model": "gpt-4o-mini" }]
+  }
+}
+```
+
+相关命令：
+
+```bash
+best-review config
+best-review init
+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。
+
+## 审查流程
+
+默认 pipeline 顺序：
+
+```mermaid
+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 会补充变更文件全文和一层相对依赖上下文，避免模型只看 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++ 以及常见配置文件。
+
+自定义规则可以放在：
+
+```text
+.best-review/rules/*.md
+~/.best-review/rules/*.md
+```
+
+规则示例：
+
+```markdown
+---
+name: input-validation
+description: 所有用户输入必须使用 schema 校验
+version: 1
+patterns:
+  - "src/**/*.ts"
+agent: security-scan
+---
+
+发现新增入口参数、请求体、环境变量读取时，检查是否有集中 schema 校验。
+只报告有实际风险的缺失校验，不报告已经被上游可靠校验的代码。
+```
+
+自定义 Agent 可以放在：
+
+```text
+.best-review/agents/*.md
+~/.best-review/agents/*.md
+```
+
+规则和 Agent 加载优先级：
+
+```text
+defaults < extends < user < project
+```
+
+共享规则包：
+
+```bash
+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 Reporting。
+
+```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
+```
+
+可选变量：
+
+| 变量 | 说明 |
+| --- | --- |
+| `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` 模式下用于定位项目 |
+| `GITLAB_MR_IID` / `CI_MERGE_REQUEST_IID` | 非 `review-mr` 模式下用于定位 MR |
+
+GitLab Reporting 会优先发布行内 discussion；无法映射到 diff position 的问题会汇总到 summary discussion。`review-mr` 模式下会清理旧的 best-review comment marker，避免重复刷屏。
+
+## 自动修复
+
+自动修复默认关闭，必须显式开启：
+
+```bash
+# 只修复 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` 只生成并校验补丁，不写入源码。
+
+可调变量：
+
+```bash
+BEST_REVIEW_FIX_MAX_ISSUES=5
+BEST_REVIEW_FIX_MAX_FILE_CHARS=60000
+```
+
+## 输出、质量评分和 CI
+
+终端输出会包含：
+
+- pipeline 是否成功。
+- Agent 成功/失败数量。
+- 模型调用次数、缓存命中次数、token 用量和缓存节省估算。
+- 风险结论。
+- 原始问题数、置信度过滤后、validation 后、最终计分问题数。
+- 质量评分。
+- 按文件分组的问题详情。
+
+风险枚举：
+
+| 内部 severity | 终端标签 |
+| --- | --- |
+| `critical` | 严重风险 |
+| `high` | 高风险 |
+| `medium` | 中风险 |
+| `low` | 低风险 |
+
+示例风险结论：
+
+```text
+风险结论：严重 1，高 2，中 0，低 3；整体风险：严重
+```
+
+JSON 输出包含：
+
+- `stats`
+- `riskSummary`
+- `qualityScore`
+- `reviewSummary`
+- `rawIssues`
+- `finalIssues`
+- `issues`
+- `files`
+- `autofix`
+- `usage`
+
+CI 建议：
+
+```bash
+best-review review --base origin/main --json
+```
+
+当 pipeline 失败或最终存在 `critical` 问题时，CLI 会返回非 0 exit code。`high`、`medium`、`low` 默认不阻断，可由 CI 根据 JSON 自定义策略。
+
+## Reporting
+
+每次 review 都会尽量生成本地报告，默认目录：
+
+```text
+.best-review/reports/
+```
+
+报告包含仓库信息、base/head、模型、Agent 结果、阶段结果、风险结论、质量评分、issue audit trail、最终问题和 diff 摘要。默认不保存完整 diff。
+
+配置上报：
+
+```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
+  }
+}
+```
+
+环境变量覆盖：
+
+```bash
+BEST_REVIEW_REPORT_DIR=.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
+```
+
+上报失败默认不阻断 review；如果 CI 要求上报失败即失败，设置 `failOnError: true` 或 `BEST_REVIEW_REPORT_FAIL_ON_ERROR=true`。
+
+## 审查质量评测
+
+`best-review eval` 会实时调用当前模型跑 golden fixtures，流程包含 review、confidence filter、deduplication 和 validation，用于评估 prompt、规则或模型变更是否造成质量回归。
+
+```bash
+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`。
+
+## 性能和成本控制
+
+```bash
+# 关闭缓存
+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
+```
+
+默认缓存目录：
+
+```text
+.best-review/cache/review
+.best-review/cache/validation
+```
+
+缓存 key 包含模型、base URL、temperature、prompt、规则和 diff 输入。相同输入会复用成功结果，并在终端/JSON 中统计缓存命中和节省 token。
+
+## 开发
+
+```bash
+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 评测 |
+
+更多设计说明：
+
+- [架构说明](docs/ARCHITECTURE.md)
+- [执行流程图](docs/EXECUTION_FLOW.md)
+- [AI 代码评审工具建设方案](docs/AI_REVIEW_TOOL_README.md)
+
+## License
+
+MIT