coderev-cli 1.0.15 → 1.0.17

package/README.md

@@ -1,6 +1,6 @@
 # coderev-cli
 
-> 多智能体 AI 代码审查工具 — Security / Bug / Quality 三个 Agent 并行审查，带置信度评分。
+> 多智能体 AI 代码审查工具 — Security / Bug / Quality 三个 Agent 并行审查，带置信度评分和自动修复。
 
 [![npm version](https://img.shields.io/npm/v/coderev-cli)](https://www.npmjs.com/package/coderev-cli)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/jishuanjimingtian)](https://github.com/sponsors/jishuanjimingtian)
@@ -13,221 +13,444 @@
 
 ---
 
+## 目录
+
+- [项目介绍](#项目介绍)
+- [安装](#安装)
+- [快速上手](#快速上手)
+- [命令详解](#命令详解)
+  - [coderev review（核心审查）](#coderev-review核心审查)
+  - [coderev fix（自动修复）](#coderev-fix自动修复)
+  - [coderev hook（Git Hooks）](#coderev-hookgit-hooks)
+  - [coderev stats（统计看板）](#coderev-stats统计看板)
+  - [coderev cache（缓存管理）](#coderev-cache缓存管理)
+  - [coderev config（配置管理）](#coderev-config配置管理)
+  - [coderev init（初始化）](#coderev-init初始化)
+- [配置详解](#配置详解)
+- [平台集成](#平台集成)
+- [CI/CD 集成](#cicd-集成)
+- [FAQ / 常见问题](#faq--常见问题)
+
+---
+
+## 项目介绍
+
+**coderev 是什么？**
+
+coderev（Code Review 缩写）是一个**多智能体 AI 代码审查 CLI 工具**。你扔给它一段代码 diff，它会并行启动 3 个 AI Agent，从**安全、缺陷、质量**三个维度审查，然后汇总成结构化的审查报告。
+
+**为什么要用 coderev？**
+
+| 场景 | 不用 coderev | 用 coderev |
+|------|-------------|-----------|
+| 每次提交前 | 凭肉眼检查或忘了检查 | 自动跑三个维度审查 |
+| 审查同事的 PR | 逐行看，容易漏 | AI 先扫一遍，你只看高置信度 issue |
+| 安全审计 | 依赖经验，覆盖不全 | OWASP 级别检查 |
+| 项目代码质量把控 | 看个人标准和心情 | 统一的规则引擎 + 置信度评分 |
+
+**适用人群**
+- 独立开发者 — 提交前自动把关，减少 Bug
+- 团队/开源维护者 — PR 接入 AI 初审，提高审查效率
+- CI/CD 流水线 — 集成到 CI，自动拦截高风险代码
+
+---
+
 ## 安装
 
+### 全局安装（推荐）
+
 ```bash
 npm install -g coderev-cli
 ```
 
-> **Node.js 版本要求：>= 18**
+> **要求 Node.js >= 18**，可使用 `node -v` 检查版本。
+
+### 验证安装
+
+```bash
+coderev --help
+```
+
+看到命令列表则安装成功。
+
+### 更新
 
 ```bash
-# 验证版本
-node -v
+npm update -g coderev-cli
 ```
 
 ---
 
 ## 快速上手
 
+### 第 1 步：初始化
+
+在项目目录中执行，生成默认配置：
+
 ```bash
-# 1. 初始化项目配置
 coderev init
+```
 
-# 2. 设置 API Key（支持 DeepSeek / OpenAI）
-# Linux / macOS:
-export DEEPSEEK_API_KEY="***"
-# Windows PowerShell:
-$env:DEEPSEEK_API_KEY="***"
+会在当前目录创建 `.coderevrc.json` 配置文件。
 
-# 3. 审查暂存区变更
-coderev review
+### 第 2 步：设置 API Key
 
-# 4. 或传入 git diff
-git diff main | coderev review
+coderev 需要调用 AI API 来审查代码。支持 OpenAI 和 DeepSeek。
 
-# 5. 或审查 PR
-coderev review --pr owner/repo#42
+```bash
+# Windows PowerShell
+$env:DEEPSEEK_API_KEY="sk-your-key-here"
+
+# Linux / macOS
+export DEEPSEEK_API_KEY="sk-your-key-here"
 ```
 
----
+也可以写入配置文件（见下方「配置详解」）。
 
-## 架构
+### 第 3 步：运行审查
 
+#### 审查暂存区变更（最常用的方式）
+
+```bash
+git add .
+coderev review
 ```
-   你的代码 (git diff)
-          │
-   ┌──────┼──────┐
-   ▼      ▼      ▼
-┌──────┐┌──────┐┌──────┐
-│  🔒  ││  🐛  ││  📐  │
-│ 安全  ││ 缺陷  ││ 质量  │
-│ 审计  ││ 检测  ││ 检查  │
-└──┬───┘└──┬───┘└──┬───┘
-   │       │       │
-   └───────┼───────┘
-           ▼
-    ┌──────────┐
-    │ 合并 &    │
-    │ 置信度评分 │
-    │ (0-100)   │
-    └────┬─────┘
-         ▼
-  结构化审查报告
+
+#### 审查当前分支的未提交变更
+
+```bash
+coderev review --diff
 ```
 
-| Agent | 专注领域 |
-|-------|---------|
-| 🔒 安全审计 | SQL注入、XSS、SSRF、硬编码密钥、认证缺陷 |
-| 🐛 缺陷检测 | 空指针、竞态条件、异步问题、逻辑错误 |
-| 📐 质量检查 | 代码复杂度、DRY、命名规范、异常处理 |
+#### 审查某个 commit
 
-每个 issue 附带**置信度评分 (0-100)**，低于阈值（默认 60）自动过滤。多 Agent 发现的重复问题自动合并去重。
+```bash
+coderev review --commit HEAD~1
+```
 
----
+#### 审查 PR
+
+```bash
+coderev review --pr 42
+```
 
-## CLI 命令参考
+### 第 4 步：查看报告
 
-### review
+审查结果会直接输出在终端。如果开启 HTML 模式，可以生成可视化报告：
 
 ```bash
-coderev review                           # 多 Agent 并行审查（默认）
-coderev review --min-confidence 80       # 提高阈值，减少误报
-coderev review --single                  # 单 Agent 模式（v0.2 兼容，更省）
-coderev review --audit                   # 安全审计模式（OWASP 级）
-coderev review --no-cache                # 跳过缓存
-coderev review --format json             # JSON 输出
-coderev review --format html             # HTML 报告输出
-coderev review --incremental             # 只审查 diff 新增/变更行
-coderev review --interactive             # 交互式逐条修复问题
-coderev review --ci                      # CI 模式（发现问题则 exit code 1）
+coderev review --output html > report.html
+# 浏览器打开 report.html
 ```
 
-### interactive 交互式修复
+---
 
-`--interactive` 模式让你逐一审查每个 issue，选择修复（AI 生成补丁）或跳过：
+## 命令详解
+
+### coderev review（核心审查）
+
+**作用**：审查代码差异并输出审查报告。这是 coderev 最核心的命令。
+
+**使用方式**：
 
 ```bash
+coderev review [选项]
+```
+
+**默认可选参数**：
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `--diff` | 审查当前分支未提交的变更（与最近 commit 对比） | `coderev review --diff` |
+| `--commit <ref>` | 审查指定 commit | `coderev review --commit abc123` |
+| `--staged` | 审查暂存区（默认行为） | `coderev review` |
+| `--single` | 单 Agent 模式（只用 1 个 Agent，省 token，v0.2 兼容） | `coderev review --single` |
+| `--min-confidence <0-100>` | 置信度阈值，低于此值的结果不显示（默认 60） | `coderev review --min-confidence 80` |
+| `--no-cache` | 跳过缓存，强制重新审查 | `coderev review --no-cache` |
+| `--format <format>` | 输出格式：`terminal`（终端） / `json` / `html` / `markdown` | `coderev review --format json` |
+| `--output <type>` | 输出方式：`terminal`（终端）/ `json` / `html` / `markdown` | `coderev review --output html` |
+| `--audit` | 安全审计模式，重点关注安全问题 | `coderev review --audit` |
+| `--incremental` | 增量模式，只审查 diff 中新增和变更的行（忽略删除的行） | `coderev review --incremental` |
+| `--interactive` | 交互式模式，逐条审查 issue 并选择是否修复 | `coderev review --interactive` |
+| `--ci` | CI 模式，发现问题时以非零退出码终止 | `coderev review --ci` |
+| `--pr <value>` | 审查 Pull Request，格式 `owner/repo#number` 或仅 `number`（自动检测仓库） | `coderev review --pr jishuanjimingtian/coderev#42` |
+| `--post` | 审查 PR 后自动回贴评论（需配合 `--pr`） | `coderev review --pr 42 --post` |
+| `--inline` | 审查 PR 后以行内方式回贴评论（需配合 `--pr`） | `coderev review --pr 42 --inline` |
+
+**使用示例**：
+
+```bash
+# 最简用法：审查暂存区
+coderev review
+
+# 审查某个 PR 并回贴评论
+coderev review --pr jishuanjimingtian/coderev#42 --post
+
+# 终端输出 + 高置信度要求（减少误报）
+coderev review --min-confidence 80
+
+# CI 中使用，发现问题就报错
+coderev review --ci --min-confidence 70
+
+# 生成 HTML 报告
+coderev review --format html > review-report.html
+
+# 交互式审查并修复
+coderev review --interactive
+
+# 只审查新增的代码（增量模式）
+coderev review --incremental
+
+# 通过管道传入 diff（支持任意 diff 输入）
+git diff main | coderev review
+```
+
+#### --interactive 交互式修复详解
+
+**作用**：逐条展示每个审查发现的问题，让你决定是否用 AI 生成补丁自动修复。
+
+**工作流程**：
+
+```
 coderev review --interactive
-# 输出示例:
-# Issue #1 of 3
-# ● [high] [error] SQL injection risk in query construction
-# File: src/db.js:42
-# Suggestion: Use parameterized queries
-# [a]pply fix / [s]kip / [q]uit > a
 ```
 
-### CI 模式
+终端会依次展示每个 issue：
 
-`--ci` 模式用于 CI/CD 管道，发现问题时以非零退出码终止：
+```
+Issue #1 of 3
+● [high] [error] SQL injection risk in query construction
+  File: src/db.js:42
+  Suggestion: Use parameterized queries
+  
+  [a]pply fix / [s]kip / [q]uit > a
+```
+
+**交互选项**：
+
+| 按键 | 作用 |
+|------|------|
+| `a` | Apply fix — AI 生成补丁并应用到文件 |
+| `s` | Skip — 跳过当前 issue |
+| `q` | Quit — 退出交互模式 |
+
+#### --ci CI 模式详解
+
+**作用**：专为 CI/CD 管道设计。如果代码中发现任何 issue（且置信度高于阈值），coderev 以非零退出码退出，中断管道执行。
 
 ```bash
-coderev review --ci --min-confidence 70
-coderev review --ci --output json       # 结合 JSON 输出用于上游处理
+# 常规使用
+coderev review --ci
+
+# 配合高阈值，只拦截确定严重的问题
+coderev review --ci --min-confidence 80
+
+# 结合 JSON 输出，供上游 CI 脚本处理
+coderev review --ci --format json
 ```
 
-### HTML 报告
+**在 CI 配置中的用法**（例如 GitHub Actions）：
+
+```yaml
+- name: coderev check
+  run: |
+    git fetch origin main
+    git diff origin/main...HEAD | coderev review --ci
+```
+
+#### --incremental 增量审查详解
+
+**作用**：默认情况下，coderev 会审查整个 diff 的上下文。增量模式下，**只关注新增和修改的行**，忽略被删除的旧代码。适用于：
 
-生成漂亮的可视化 HTML 报告：
+- 大型代码库重构，不想看大段删除
+- 只想关注"引入的新代码"是否有问题
+- PR 审查时快速聚焦变更内容
+
+```bash
+coderev review --incremental
+```
+
+#### HTML 报告
+
+**作用**：生成可视化的 HTML 审查报告，支持深色/浅色模式自动适配，方便分享或归档。
 
 ```bash
 coderev review --output html > report.html
-# 支持深色/浅色模式自动适配
 ```
 
-### 增量审查
+---
+
+### coderev fix（自动修复）
 
-只关注 diff 中新增和修改的行，忽略移除的上下文：
+**作用**：根据审查结果生成补丁文件，或直接应用到代码中。
 
 ```bash
-coderev review --incremental
+coderev fix --file <diff文件>
 ```
 
-### fix
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `--file <path>` | **必填**，指定包含 diff 的文件路径 | `coderev fix --file changes.diff` |
+| `--apply` | 生成补丁后**直接应用到文件** | `coderev fix --file changes.diff --apply` |
+
+**使用示例**：
 
 ```bash
-coderev fix --file changes.diff          # 自动修复建议
-coderev fix --file changes.diff --apply  # 生成并应用补丁
+# 先生成 diff
+git diff > changes.diff
+
+# 审查并生成修复建议（不自动应用）
+coderev fix --file changes.diff
+
+# 审查并直接应用补丁
+coderev fix --file changes.diff --apply
 ```
 
-### PR 审查
+---
+
+### coderev hook（Git Hooks）
+
+**作用**：安装 Git hooks，让你在 git 操作时自动触发代码审查。支持 pre-commit（提交前）和 pre-push（推送前）。
 
 ```bash
-coderev review --pr owner/repo#42              # 审查外部 PR
-coderev review --pr 42                          # 自动检测当前仓库
-coderev review --pr owner/repo#42 --post        # 审查 + 贴评论
-coderev review --pr owner/repo#42 --inline      # 行内评论
-coderev review --pr owner/repo#42 --format json
+coderev hook install [hook类型] [选项]
 ```
 
-### Git Hooks
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `install` | 安装 hook | `coderev hook install` |
+| `install pre-commit` | 安装 pre-commit hook（提交前审查） | `coderev hook install pre-commit` |
+| `install pre-push` | 安装 pre-push hook（推送前审查） | `coderev hook install pre-push` |
+| `--min-score <number>` | 设置最低置信度阈值 | `coderev hook install pre-commit --min-score 70` |
+| `remove` | 移除已安装的 hook | `coderev hook remove` |
+
+**使用示例**：
 
 ```bash
-coderev hook install                         # 安装 pre-commit
+# 安装默认 hook（pre-commit）
+coderev hook install
+
+# 安装 pre-commit，设置置信度 70
 coderev hook install pre-commit --min-score 70
+
+# 安装 pre-push
 coderev hook install pre-push
+
+# 移除所有 hook
+coderev hook remove
 ```
 
-### 其他
+**安装后效果**：
+- `git commit` 时 → 自动审查暂存区代码，发现问题会阻止提交
+- `git push` 时 → 自动审查将要推送的变更
+
+---
+
+### coderev stats（统计看板）
+
+**作用**：查看代码审查的历史统计，包括审查次数、发现的 issue 数量、类型分布等。
 
 ```bash
-coderev stats                                # 统计看板
-coderev stats week                           # 本周统计
-coderev cache status                         # 缓存状态
-coderev cache clear                          # 清空缓存
-coderev config show                          # 查看配置
+coderev stats [周期]
 ```
 
----
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| （无参数） | 查看总体统计数据 | `coderev stats` |
+| `week` | 本周统计 | `coderev stats week` |
+| `month` | 本月统计 | `coderev stats month` |
 
-## 配置管理
+**输出示例**（实际内容取决于缓存数据）：
 
-coderev 支持三种配置方式（优先级从高到低），建议用配置文件，一劳永逸。
+```
+📊 coderev 统计
+═══════════════════
+总审查次数: 47
+总发现 issue: 156
+  安全: 23 (14.7%)
+  缺陷: 67 (42.9%)
+  质量: 66 (42.3%)
+═══════════════════
+```
+
+---
 
-### 方式一：全局配置文件
+### coderev cache（缓存管理）
 
-在项目根目录创建 `.coderevrc.json`，coderev 会自动从当前目录向父目录逐级查找。也支持 `.coderevrc` 或 `coderev.config.json` 作为文件名。
+**作用**：管理审查结果缓存，避免重复审查相同的代码。
 
 ```bash
-# 一键生成默认配置
-coderev init
+coderev cache <子命令>
 ```
 
-### 方式二：环境变量
+| 子命令 | 说明 | 示例 |
+|--------|------|------|
+| `status` | 查看缓存状态（缓存条目数、过期时间） | `coderev cache status` |
+| `clear` | 清空所有缓存 | `coderev cache clear` |
 
-适用于临时测试或 CI 环境：
-```bash
-# Linux / macOS
-export DEEPSEEK_API_KEY="sk-xxx"
-export OPENAI_API_KEY="sk-xxx"
+**缓存机制**：
+- 基于代码 diff 的 SHA256 哈希值
+- 缓存有效期 24 小时
+- 同段代码反复审查时直接返回缓存结果，节省 API 调用
 
-# Windows PowerShell
-$env:DEEPSEEK_API_KEY="sk-xxx"
+---
+
+### coderev config（配置管理）
+
+**作用**：查看或管理当前配置。
+
+```bash
+coderev config <子命令>
 ```
 
-默认读取 `OPENAI_API_KEY`，如需改用 `DEEPSEEK_API_KEY`，在配置文件中设置：
-```json
-{
-  "ai": {
-    "apiKeyEnv": "DEEPSEEK_API_KEY"
-  }
-}
+| 子命令 | 说明 | 示例 |
+|--------|------|------|
+| `show` | 显示当前生效的完整配置 | `coderev config show` |
+
+---
+
+### coderev init（初始化）
+
+**作用**：在当前项目目录生成 `.coderevrc.json` 配置文件。
+
+```bash
+coderev init
 ```
 
-### 方式三：配置文件内直接写 Key
+生成的文件内容：
 
 ```json
 {
   "ai": {
-    "apiKey": "sk-xxx"
+    "provider": "deepseek",
+    "temperature": 0.3,
+    "maxTokens": 4096
+  },
+  "rules": {
+    "maxLineLength": 100,
+    "predefined": ["security", "performance", "style"]
   }
 }
 ```
-> ⚠️ 注意：不要在公开仓库中提交含 Key 的配置文件，建议配合 `.gitignore` 或使用环境变量。
+
+如果项目已有配置文件，执行 `coderev init` 会提示是否覆盖。
 
 ---
 
-### 完整配置项说明
+## 配置详解
+
+### 配置加载顺序
+
+coderev 按以下优先级加载配置（高的优先）：
+
+1. **CLI 参数**（命令行传入）
+2. **配置文件**（`.coderevrc.json` / `.coderevrc` / `coderev.config.json`）
+3. **环境变量**（环境变量中设置的 API Key）
+4. **默认值**
+
+配置文件会自动从**当前目录向父目录逐级查找**，找到第一个便停止。
+
+### 完整配置项参考
 
 ```json
 {
@@ -244,14 +467,7 @@ $env:DEEPSEEK_API_KEY="sk-xxx"
     "maxLineLength": 100,
     "predefined": ["security", "performance", "style"],
     "autoLanguage": true,
-    "custom": [
-      {
-        "name": "no-console-log",
-        "severity": "warning",
-        "message": "避免在生产代码中使用 console.log",
-        "filePattern": "src/**/*.js"
-      }
-    ]
+    "custom": []
   },
   "output": {
     "format": "terminal",
@@ -260,53 +476,90 @@ $env:DEEPSEEK_API_KEY="sk-xxx"
 }
 ```
 
+#### ai（AI 配置）
+
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `ai.provider` | string | `"openai"` | AI 提供商，支持 `"openai"` / `"deepseek"` |
-| `ai.model` | string | 取决于 provider | 模型名称（openai 默认 `gpt-4o`，deepseek 默认 `deepseek-chat`）|
-| `ai.temperature` | number | `0.3` | 生成温度，越低越确定（0-1） |
-| `ai.maxTokens` | number | `4096` | 每次请求最大 token 数 |
-| `ai.apiKey` | string | `""` | 直接在配置文件中写入 API Key |
-| `ai.apiKeyEnv` | string | `"OPENAI_API_KEY"` | 从环境变量读取 Key 的变量名 |
-| `ai.baseURL` | string | `""` | 自定义 API 地址（兼容 OpenAI 协议的任意服务） |
-| `rules.maxLineLength` | number | `100` | 最大行长度检查 |
-| `rules.predefined` | string[] | `["security","performance","style"]` | 启用的预定义规则集 |
-| `rules.autoLanguage` | boolean | `true` | 是否自动检测 diff 语言并追加专项规则 |
-| `rules.custom` | object[] | `[]` | 自定义规则数组 |
-| `output.format` | string | `"terminal"` | 输出格式：`"terminal"` / `"markdown"` / `"json"` |
-| `output.includeScore` | boolean | `true` | 是否显示评分 |
-
-### 支持的 Provider
+| `provider` | string | `"openai"` | AI 提供商，支持 `"openai"` / `"deepseek"` |
+| `model` | string | 取决于 provider | 模型名称 |
+| `temperature` | number | `0.3` | 生成温度（0-1），越低越确定越保守 |
+| `maxTokens` | number | `4096` | 每次请求最大输出 token 数 |
+| `apiKey` | string | `""` | 直接在配置文件中写入 API Key |
+| `apiKeyEnv` | string | `"OPENAI_API_KEY"` | 读取环境变量中的 API Key |
+| `baseURL` | string | `""` | 自定义 API 地址，兼容 OpenAI 协议的任何服务 |
+
+**支持的 Provider 默认值**：
 
 | provider | 默认模型 | 默认 API 地址 |
 |----------|---------|--------------|
 | `openai` | `gpt-4o` | `https://api.openai.com` |
 | `deepseek` | `deepseek-chat` | `https://api.deepseek.com` |
 
-通过 `ai.baseURL` 可对接任何兼容 OpenAI 协议的 API 服务（如 Azure OpenAI、本地 LLM 等）。
+**对接任意兼容 OpenAI API 的服务**（如 Azure OpenAI、本地 LLM）：
 
----
+```json
+{
+  "ai": {
+    "provider": "openai",
+    "baseURL": "https://your-custom-endpoint.com/v1",
+    "apiKey": "sk-your-key"
+  }
+}
+```
 
-### 预定义规则集
+#### rules（规则引擎配置）
 
-`rules.predefined` 数组中可以启用以下规则集：
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `maxLineLength` | number | `100` | 最大行长度检查，超过会警告 |
+| `predefined` | string[] | `["security","performance","style"]` | 启用的预定义规则集 |
+| `autoLanguage` | boolean | `true` | 是否自动检测 diff 语言并追加专项规则 |
+| `custom` | object[] | `[]` | 自定义规则数组 |
 
-| 名称 | 说明 |
-|------|------|
-| `security` | 安全检查：注入、XSS、认证缺陷、密钥泄露 |
-| `performance` | 性能检查：不必要的循环、内存泄漏、N+1 查询 |
-| `style` | 代码风格：空格、import、未使用变量 |
-| `typescript` | TypeScript 最佳实践（strict 模式、泛型、类型断言） |
-| `react` | React 最佳实践（hooks 规则、key props、组件命名） |
-| `node` | Node.js 最佳实践（错误处理、async 模式、文件安全） |
-| `naming` | 命名规范（camelCase、PascalCase、常量大写） |
-| `testing` | 测试质量（断言覆盖、边界情况、测试隔离） |
+**预定义规则集一览**：
 
----
+通过配置 `rules.predefined` 数组，可以自由组合启用以下规则集：
 
-### 自定义规则
+| 名称 | 检查重点 |
+|------|---------|
+| `security` | SQL/NoSQL 注入、XSS、SSRF、CSRF、硬编码密钥、认证缺陷、授权缺失 |
+| `performance` | 不必要的循环、大对象未释放、N+1 查询、内存泄漏、冗余计算 |
+| `style` | 空格/缩进不统一、未使用的 import/变量、分号规范、命名约定 |
+| `typescript` | 非严格模式、滥用 any、泛型使用不当、类型断言滥用、枚举误用 |
+| `react` | hooks 规则违反、缺少 key props、函数组件命名、副作用清理 |
+| `node` | 未捕获异常、异步回调链、文件 I/O 未关闭、路径遍历 |
+| `naming` | 驼峰 vs 帕斯卡命名规范、常量大写、函数命名动词化 |
+| `testing` | 断言覆盖不足、边界条件缺失、测试间耦合、输出不明确 |
+
+**启用示例**：
+
+```json
+{
+  "rules": {
+    "predefined": ["security", "typescript", "react", "naming", "testing"]
+  }
+}
+```
+
+#### rules.autoLanguage 自动语言检测
+
+coderev 会自动检查 diff 中文件的扩展名，追加对应的语言专项规则：
+
+| 语言 | 扩展名 | 检查重点 |
+|------|--------|---------|
+| JavaScript | `.js`, `.jsx`, `.mjs` | async/await 链、== vs ===、内存泄漏、循环依赖 |
+| TypeScript | `.ts`, `.tsx` | strict 模式、禁止 any、泛型约束、类型断言 |
+| Python | `.py` | PEP 8 规范、异常类型指定、mutable 默认参数、async 用法 |
+| Rust | `.rs` | unsafe 块审计、unwrap/expect 滥用、ownership 问题 |
+| Go | `.go` | error 忽略、goroutine 泄漏、context 传播、data race |
+| Java | `.java` | null 处理、checked exception、== vs .equals()、线程安全 |
+| SQL | `.sql` | 注入防护、N+1 查询、索引缺失、大 IN-clause |
 
-在 `rules.custom` 中定义专属规则：
+可通过 `rules.autoLanguage: false` 关闭此功能。
+
+#### rules.custom 自定义规则
+
+**作用**：针对团队或项目的特定规范，编写专属审查规则。
 
 ```json
 {
@@ -322,41 +575,38 @@ $env:DEEPSEEK_API_KEY="sk-xxx"
         "severity": "error",
         "message": "React 组件必须包裹 ErrorBoundary",
         "filePattern": "src/components/**/*.jsx"
+      },
+      {
+        "name": "single-quote-string",
+        "severity": "warning",
+        "message": "请使用单引号",
+        "filePattern": "src/**/*.ts"
       }
     ]
   }
 }
 ```
 
-| 字段 | 说明 |
-|------|------|
-| `name` | 规则名称 |
-| `severity` | 严重级别：`"error"` / `"warning"` / `"info"` |
-| `message` | 审查时的提示文字 |
-| `filePattern` | 可选，限定生效的文件 glob 模式 |
-| `enabled` | 可选，设为 `false` 可临时禁用 |
-
----
-
-### 语言专项规则
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `name` | ✅ | string | 规则名称 |
+| `severity` | ✅ | string | `"error"` / `"warning"` / `"info"` |
+| `message` | ✅ | string | 审查时显示的提示文字 |
+| `filePattern` | ❌ | string | 可选，限定生效的文件 glob 模式，如 `src/**/*.ts` |
+| `enabled` | ❌ | boolean | 可选，设为 `false` 可临时禁用此规则 |
 
-coderev 自动从 diff 文件扩展名检测语言，追加专项检查（可通过 `rules.autoLanguage: false` 关闭）：
+#### output（输出配置）
 
-| 语言 | 检查重点 |
-|------|---------|
-| JavaScript | async/await 链、== vs ===、内存泄漏、import 循环依赖 |
-| TypeScript | strict 模式、避免 any、泛型、类型断言 |
-| Python | PEP 8、except 类型、mutable 默认参数、async 用法 |
-| Rust | unsafe 审计、unwrap/expect、生命周期、ownership |
-| Go | error handling、goroutine 安全、context 传播、data race |
-| Java | null 处理、checked exception、== vs .equals()、线程安全 |
-| SQL | 注入防护、N+1 查询、索引缺失、大 IN-clause |
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `format` | string | `"terminal"` | 输出格式：`"terminal"` / `"json"` / `"html"` / `"markdown"` |
+| `includeScore` | boolean | `true` | 是否显示置信度评分 |
 
----
+### .coderevignore 忽略文件
 
-### .coderevignore：忽略文件
+**作用**：指定 coderev 审查时跳过哪些文件或目录。
 
-不想被审查的文件，在 `.coderevignore` 中列出（glob 模式）：
+在项目根目录创建 `.coderevignore` 文件，语法同 `.gitignore`（glob 模式）：
 
 ```
 # coderev ignore list
@@ -369,11 +619,11 @@ dist/
 build/
 ```
 
----
+### .coderevhint 项目上下文
 
-### .coderevhint：项目上下文
+**作用**：给 AI 审查引擎提供项目背景，让它更准确理解你的代码。
 
-给 AI 审查提供项目背景，让它更懂你的代码：
+在项目根目录创建 `.coderevhint` 文件：
 
 ```
 # 项目概况
@@ -386,56 +636,129 @@ build/
 - Avoid: any 类型、使用 any 断言
 ```
 
-兼容 `CLAUDE.md` 格式，两者可共存。
+也兼容 `CLAUDE.md` 格式，两者可共存。
 
----
+### API Key 配置方式对比
 
-## 支持的 Git 平台
+| 方式 | 安全性 | 适用场景 | 配置方法 |
+|------|--------|---------|---------|
+| 环境变量 | ✅ 最安全（不落盘） | 本地开发、CI 环境 | `$env:OPENAI_API_KEY="..."` |
+| 配置文件直接写 | ⚠️ 注意.gitignore | 本地个人使用 | `"apiKey": "..."` |
+| 配置文件引用 env | ✅ 安全 + 方便 | 推荐方式 | `"apiKeyEnv": "DEEPSEEK_API_KEY"` |
 
-| 平台 | PR 审查 | 评论回贴 |
-|------|---------|---------|
-| GitHub | ✅ | ✅ 行内 / 摘要 |
-| GitLab | ✅ | ✅ |
-| Gitee  | ✅ | ✅ |
-| Bitbucket | ✅ | ✅ |
+> **推荐做法**：环境变量 + `apiKeyEnv`。既不在代码中暴露 key，又无需每次都手动设置。
 
 ---
 
-## 缓存
+## 平台集成
+
+### 支持的 Git 平台
+
+coderev 支持四大平台，均支持 PR 审查和评论回贴：
+
+| 平台 | PR 审查 | 摘要评论 | 行内评论 | 自动检测 |
+|------|:-------:|:--------:|:--------:|:--------:|
+| GitHub | ✅ | ✅ | ✅ | ✅ |
+| GitLab | ✅ | ✅ | ✅ | ✅ |
+| Gitee | ✅ | ✅ | ❌ | ❌ 需完整格式 |
+| Bitbucket | ✅ | ✅ | ❌ | ❌ 需完整格式 |
+
+**使用方式**：
+
+```bash
+# GitHub — 自动检测当前仓库
+coderev review --pr 42
+
+# 指定仓库（其他平台或跨平台）
+coderev review --pr owner/repo#42
 
-- SHA256 摘要哈希
-- 24 小时 TTL
-- `coderev cache status` / `coderev cache clear`
+# 审查 + 回贴评论
+coderev review --pr 42 --post
+
+# 审查 + 行内评论（仅 GitHub/GitLab）
+coderev review --pr 42 --inline
+```
 
 ---
 
-## CI / GitHub Actions
+## CI/CD 集成
+
+### GitHub Actions
 
-内置工作流文件 `.github/workflows/coderev-review.yml`，PR 自动审查。
+项目初始化时自动生成 `.github/workflows/coderev-review.yml`，在 PR 创建或更新时自动触发代码审查。
+
+**工作流说明**：
+- 触发条件：PR 打开、同步、重新打开
+- 执行内容：对比 PR 的 diff → coderev 审查 → 结果回贴到 PR 评论
+- 效果：每个 PR 自动获得一份 AI 审查报告
+
+### 自定义 CI 集成
+
+在任意 CI 管道中：
+
+```bash
+# 对比当前分支与 main
+git fetch origin main
+git diff origin/main...HEAD | coderev review --ci --min-confidence 70
+```
+
+如果代码存在高置信度问题，管道会以非零退出码中断，阻止合并。
 
 ---
 
-## 项目结构
-
-```
-coderev/
-├── src/
-│   ├── cli.js          # CLI 入口
-│   ├── reviewer.js     # 多 Agent 审查核心
-│   ├── config.js       # 配置加载
-│   ├── github.js       # GitHub API
-│   ├── gitlab.js       # GitLab API
-│   ├── gitee.js        # Gitee API
-│   ├── bitbucket.js    # Bitbucket API
-│   ├── cache.js        # 缓存系统
-│   ├── rules.js        # 规则引擎
-│   ├── stats.js        # 统计看板
-│   └── coderev.test.js # 20 个单元测试
-├── .github/workflows/
-├── .coderevrc.json
-├── .coderevignore
-└── .coderevhint
+## 架构
+
 ```
+   你的代码 (git diff / PR)
+          │
+   ┌──────┼──────┐
+   ▼      ▼      ▼
+┌──────┐┌──────┐┌──────┐
+│  🔒  ││  🐛  ││  📐  │
+│ 安全  ││ 缺陷  ││ 质量  │
+│ 审计  ││ 检测  ││ 检查  │
+└──┬───┘└──┬───┘└──┬───┘
+   │       │       │
+   └───────┼───────┘
+           ▼
+    ┌──────────┐
+    │ 合并 &    │
+    │ 置信度评分 │
+    │ (0-100)   │
+    └────┬─────┘
+         ▼
+  结构化审查报告
+```
+
+| Agent | 专注领域 |
+|-------|---------|
+| 🔒 安全审计 | SQL注入、XSS、SSRF、硬编码密钥、认证缺陷 |
+| 🐛 缺陷检测 | 空指针、竞态条件、异步问题、逻辑错误 |
+| 📐 质量检查 | 代码复杂度、DRY、命名规范、异常处理 |
+
+每个 issue 附带**置信度评分 (0-100)**，低于阈值（默认 60）自动过滤。多 Agent 发现的重复问题自动合并去重。
+
+---
+
+## FAQ / 常见问题
+
+### Q：为什么审查结果为空？
+A：可能是代码本身没有问题，也可能是置信度低于阈值。可以尝试 `coderev review --min-confidence 0` 查看所有结果。
+
+### Q：怎么换 API Key？
+A：重新设置环境变量即可，或在 `.coderevrc.json` 中修改 `ai.apiKey` / `ai.apiKeyEnv`。
+
+### Q：不想用 DeepSeek，想用其他 AI？
+A：改成 `provider: "openai"`，再设置 `apiKeyEnv: "OPENAI_API_KEY"`。如果用的是兼容 OpenAI 协议的自定义 API，设置 `baseURL` 即可。
+
+### Q：coderev 会泄漏我的代码吗？
+A：代码通过你的 API Key 发送到 AI 服务商。coderev 本身不会存储或转发你的代码。本地缓存仅存储在你自己机器上。
+
+### Q：缓存能关掉吗？
+A：可以，审查时加 `--no-cache` 参数即可跳过缓存。
+
+### Q：怎么给 coderev 加自己的规则？
+A：在 `.coderevrc.json` 的 `rules.custom` 数组中添加。详见上方「自定义规则」章节。
 
 ---