soloshine-ai-code-review 0.1.0__tar.gz

soloshine_ai_code_review-0.1.0/PKG-INFO

@@ -0,0 +1,758 @@
+Metadata-Version: 2.4
+Name: soloshine-ai-code-review
+Version: 0.1.0
+Summary: AI-powered code review tool with pre-commit hooks, custom LLM support, and context-aware analysis
+Author: SoloShine
+License: MIT
+Project-URL: Homepage, https://github.com/SoloShine/ai-code-review
+Project-URL: Documentation, https://soloshine.github.io/ai-code-review/
+Project-URL: Repository, https://github.com/SoloShine/ai-code-review
+Project-URL: Issues, https://github.com/SoloShine/ai-code-review/issues
+Keywords: code-review,ai,llm,pre-commit,git-hooks,ollama,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+
+# AI Code Review 使用手册
+
+> 版本 0.1.0 · AI 驱动的代码审查工具，支持 Git Hook 集成、自定义规则、LLM 审查、通知中心
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [配置](#配置)
+- [命令参考](#命令参考)
+- [规则系统](#规则系统)
+- [通知中心](#通知中心)
+- [抑制系统](#抑制系统)
+- [项目结构](#项目结构)
+- [注意事项](#注意事项)
+
+---
+
+## 概述
+
+AI Code Review 是一个本地运行的代码审查工具，通过接入 LLM（大语言模型）对代码变更进行智能审查。核心能力：
+
+| 能力 | 说明 |
+|------|------|
+| **Pre-commit 拦截** | 提交前快速筛查，发现严重问题直接阻止提交 |
+| **Post-commit 深度审查** | 提交后异步执行完整审查，生成详细报告 |
+| **自定义规则** | YAML 格式规则文件，按文件类型自动匹配 |
+| **记忆系统** | 跨次审查跟踪重复问题，计算风险分数 |
+| **通知中心** | 终端 Inbox + HTML 仪表盘 + 系统弹窗三通道提醒 |
+| **抑制管理** | 对已知且暂不处理的问题标记抑制，停止弹窗干扰 |
+
+支持的 LLM 后端：
+
+- **Ollama** — 本地部署，无需 API Key
+- **OpenAI Compatible** — 任何兼容 OpenAI 接口的服务（智谱 GLM、DeepSeek、通义千问等）
+
+---
+
+## 安装
+
+### 环境要求
+
+- Python >= 3.10
+- Git
+- LLM 后端（Ollama 或 OpenAI 兼容 API）
+
+### 安装步骤
+
+```bash
+# 克隆项目
+git clone <repo-url> ai-code-review
+cd ai-code-review
+
+# 安装（开发模式，方便后续更新）
+pip install -e .
+
+# 验证安装
+ai-review --help
+```
+
+### 依赖说明
+
+核心依赖（自动安装）：
+
+| 包 | 用途 |
+|----|------|
+| `typer` | CLI 框架 |
+| `httpx` | LLM API 调用 |
+| `pyyaml` | 配置和规则文件解析 |
+| `rich` | 终端美化输出 |
+
+---
+
+## 快速开始
+
+### 1. 在项目中初始化
+
+```bash
+cd your-project
+ai-review init
+```
+
+该命令会：
+- 创建 `.ai-review.yaml` 配置文件
+- 创建 `.ai-review/` 目录结构（含 `rules/` 子目录）
+- 安装 Git pre-commit 和 post-commit 钩子
+
+### 2. 配置 LLM 后端
+
+编辑 `.ai-review.yaml`，选择后端：
+
+**使用智谱 GLM（推荐国内用户）：**
+
+```yaml
+mode: "balanced"
+llm:
+  backend: "openai_compatible"
+  openai_compatible:
+    base_url: "https://open.bigmodel.cn/api/coding/paas/v4"
+    api_key_env: "ZHIPU_API_KEY"
+    model: "glm-5-turbo"
+    timeout: 60
+```
+
+然后设置环境变量：
+
+```bash
+# Linux/macOS
+export ZHIPU_API_KEY="your-api-key"
+
+# Windows PowerShell
+[Environment]::SetEnvironmentVariable("ZHIPU_API_KEY", "your-api-key", "User")
+```
+
+**使用 Ollama（本地部署）：**
+
+```bash
+# 先启动 Ollama 服务
+ollama serve
+ollama pull qwen2.5-coder:7b
+```
+
+```yaml
+mode: "balanced"
+llm:
+  backend: "ollama"
+  ollama:
+    base_url: "http://localhost:11434"
+    model: "qwen2.5-coder:7b"
+    timeout: 60
+```
+
+### 3. 添加审查规则
+
+在 `.ai-review/rules/` 下创建 YAML 规则文件，例如 `frontend-rules.yaml`：
+
+```yaml
+name: "Frontend Code Rules"
+description: "Vue/TypeScript frontend review rules"
+rules:
+  - id: "no-console-log"
+    title: "禁止提交 console.log 调试语句"
+    severity: "warning"
+    enabled: true
+    applies_to:
+      extensions: [".ts", ".js", ".vue"]
+    description: "console.log 调试语句不应提交到代码库，应使用项目中的 logger 工具替代。"
+
+  - id: "no-any-type"
+    title: "禁止使用 any 类型"
+    severity: "warning"
+    enabled: true
+    applies_to:
+      extensions: [".ts", ".tsx"]
+    description: "TypeScript 中使用 any 会导致类型检查失效，应使用具体类型或泛型替代。"
+```
+
+### 4. 提交代码触发审查
+
+```bash
+# 正常提交代码
+git add .
+git commit -m "feat: add user component"
+
+# pre-commit hook 会自动运行快速筛查
+# 如果发现 ERROR 级别问题，提交会被阻止
+# 如果通过，post-commit hook 会异步执行完整审查
+```
+
+### 5. 查看审查结果
+
+```bash
+# 查看未读报告
+ai-review inbox
+
+# 查看某份报告详情
+ai-review inbox show <report-id>
+
+# 打开 HTML 仪表盘
+ai-review inbox dashboard
+```
+
+---
+
+## 配置
+
+配置文件为项目根目录的 `.ai-review.yaml`。
+
+### 完整配置项
+
+```yaml
+# ==================== 基础设置 ====================
+
+# 运行模式: "balanced"（平衡，推荐） | "strict"（严格）
+mode: "balanced"
+
+# ==================== LLM 后端 ====================
+
+llm:
+  # 选择后端: "ollama" | "openai_compatible"
+  backend: "openai_compatible"
+
+  # Ollama 后端配置
+  ollama:
+    base_url: "http://localhost:11434"
+    model: "qwen2.5-coder:7b"
+    timeout: 60
+
+  # OpenAI 兼容后端配置
+  openai_compatible:
+    base_url: "https://open.bigmodel.cn/api/coding/paas/v4"
+    api_key_env: "ZHIPU_API_KEY"     # API Key 环境变量名
+    model: "glm-5-turbo"
+    timeout: 60
+
+# ==================== Git Hook ====================
+
+hooks:
+  pre_commit:
+    timeout: 30                       # 快速筛查超时（秒）
+    block_on: ["CRITICAL", "ERROR"]   # 遇到这些级别的问题阻止提交
+    rules_filter:
+      severities: ["error"]           # pre-commit 只检查 error 级别规则
+    bypass_env_vars: []               # 设置这些环境变量可跳过审查
+
+  post_commit:
+    enabled: true                     # 启用 post-commit 异步审查
+
+# ==================== 记忆系统 ====================
+
+memory:
+  enabled: true                       # 启用记忆系统
+  risk_threshold: 5                   # 风险分数阈值（0-10）
+  # reminder: 提醒策略（内部使用）
+
+# ==================== 仪表盘 ====================
+
+dashboard:
+  auto_open: true                     # 异步审查完成后自动打开浏览器
+
+# ==================== 排除规则 ====================
+
+exclude:
+  - "*.lock"
+  - "*.min.js"
+  - "*.min.css"
+  - "*.png"
+  - "*.jpg"
+  - "package-lock.json"
+  - "node_modules/"
+  - "dist/"
+  - "__pycache__/"
+```
+
+### 模式说明
+
+| 模式 | Pre-commit | Post-commit | Memory | 说明 |
+|------|-----------|-------------|--------|------|
+| **balanced** | 仅筛查 ERROR/CRITICAL，30s 超时 | 启用 | 启用 | 推荐日常使用 |
+| **strict** | 筛查所有级别（含 WARNING），60s 超时 | 禁用 | 禁用 | 严格模式，适合关键分支 |
+
+---
+
+## 命令参考
+
+### `ai-review init`
+
+初始化项目，创建配置文件和安装 Git 钩子。
+
+```bash
+ai-review init [--mode balanced] [--backend ollama] [--model qwen2.5-coder:7b]
+```
+
+### `ai-review check`
+
+执行代码审查，支持三种模式。
+
+**Pre-commit 模式**（由 Git Hook 自动调用）：
+
+```bash
+ai-review check --pre-commit [--no-block]
+```
+
+**异步 Post-commit 模式**（由 Git Hook 自动调用）：
+
+```bash
+ai-review check --async --commit <sha> [--open-dashboard]
+```
+
+**手动审查模式**：
+
+```bash
+# 审查当前暂存区
+ai-review check
+
+# 审查指定文件
+ai-review check --path src/app.py
+
+# 与分支对比审查
+ai-review check --base main
+
+# 详细输出
+ai-review check --verbose
+
+# 调试模式（显示 prompt 和 LLM 原始响应）
+ai-review check --debug --verbose
+```
+
+**选项说明：**
+
+| 选项 | 说明 |
+|------|------|
+| `--pre-commit` | 以 pre-commit hook 模式运行（快速筛查） |
+| `--async` | 异步 post-commit 审查模式 |
+| `--commit <sha>` | 指定审查的 commit（异步模式必需） |
+| `--base <branch>` | 与指定分支对比审查 |
+| `--path <file>` | 审查指定文件 |
+| `--no-block` | 仅报告，不阻止提交 |
+| `--verbose`, `-v` | 显示详细输出 |
+| `--debug` | 显示调试信息（prompt、LLM 原始响应） |
+| `--open-dashboard` | 审查完成后打开 HTML 仪表盘 |
+
+### `ai-review inbox`
+
+管理审查报告通知中心。
+
+```bash
+# 列出所有报告（默认命令）
+ai-review inbox
+ai-review inbox --unread              # 仅显示未读
+ai-review inbox --status WARNING      # 按状态筛选
+ai-review inbox --limit 10            # 限制数量
+ai-review inbox --all                 # 包含已归档
+
+# 查看报告详情（自动标记已读）
+ai-review inbox show <report-id>
+ai-review inbox show <report-id> --md # 在浏览器中打开 Markdown 报告
+
+# 标记已读/未读
+ai-review inbox read <report-id>
+ai-review inbox unread <report-id>
+ai-review inbox mark-all-read
+
+# 生成并打开 HTML 仪表盘
+ai-review inbox dashboard
+```
+
+### `ai-review suppress`
+
+管理规则抑制（对特定文件跳过特定规则的弹窗通知）。
+
+```bash
+# 查看已抑制的规则
+ai-review suppress --list
+
+# 抑制某个文件的特定规则
+ai-review suppress src/utils/helper.ts no-console-log --reason "调试阶段暂保留"
+
+# 抑制某个文件的所有规则
+ai-review suppress src/legacy/old.ts --all --reason "遗留代码，暂不处理"
+
+# 取消抑制
+ai-review suppress src/utils/helper.ts no-console-log --cancel
+ai-review suppress src/legacy/old.ts --all --cancel
+```
+
+> **注意**：抑制不会阻止审查本身，报告仍会包含这些问题，只是不再弹窗通知。
+
+### `ai-review status`
+
+查看高风险文件和待处理警告。
+
+```bash
+ai-review status
+```
+
+### `ai-review config-show`
+
+显示当前生效的完整配置。
+
+```bash
+ai-review config-show
+```
+
+---
+
+## 规则系统
+
+### 规则文件格式
+
+在 `.ai-review/rules/` 目录下创建 YAML 文件，支持多个规则文件：
+
+```yaml
+name: "规则集名称"
+description: "规则集描述"
+rules:
+  - id: "rule-id"                   # 唯一标识符
+    title: "规则标题"                # 简短描述
+    severity: "error"                # 级别: error | warning | info
+    enabled: true                    # 是否启用
+    applies_to:
+      extensions: [".py", ".js"]     # 适用的文件扩展名
+    description: "详细描述规则内容，LLM 会参考此描述进行审查。"
+
+  # 更多规则...
+```
+
+### 规则字段说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `id` | 是 | 规则唯一标识，用于抑制管理和报告引用 |
+| `title` | 是 | 规则简短标题 |
+| `severity` | 是 | `error`（阻止提交）/ `warning`（仅警告）/ `info`（提示） |
+| `enabled` | 否 | 默认 `true`，设为 `false` 禁用 |
+| `applies_to.extensions` | 否 | 适用的文件扩展名列表 |
+| `applies_to.paths` | 否 | 适用的文件路径 glob 模式 |
+| `description` | 是 | 规则详细描述，LLM 参考此内容审查 |
+
+### Severity 与 Pre-commit 行为
+
+| Severity | Pre-commit 行为 | Post-commit 行为 |
+|----------|----------------|-----------------|
+| `error` | 匹配到即阻止提交 | 报告为 ERROR 级别 |
+| `warning` | 不阻止提交 | 报告为 WARNING 级别 |
+| `info` | 不参与筛查 | 报告为 INFO 级别 |
+
+> 默认配置下，`pre_commit.rules_filter.severities` 为 `["error"]`，即只有 `severity: "error"` 的规则参与 pre-commit 筛查。如果需要更严格的筛查，可改为 `["error", "warning"]`。
+
+### 规则示例
+
+**前端 TypeScript/Vue 规则：**
+
+```yaml
+name: "Vue Frontend Rules"
+rules:
+  - id: "no-settimeout"
+    title: "禁止使用 setTimeout"
+    severity: "error"
+    applies_to:
+      extensions: [".ts", ".js", ".vue"]
+    description: "禁止使用 setTimeout 处理时序性问题，应使用 Promise/nextTick 等可靠机制。"
+
+  - id: "promise-catch"
+    title: "Promise 必须处理错误"
+    severity: "error"
+    applies_to:
+      extensions: [".ts", ".js", ".vue"]
+    description: "所有 Promise 链必须包含 .catch() 或使用 try/catch 包裹 async/await。"
+
+  - id: "no-console-log"
+    title: "禁止提交 console.log"
+    severity: "warning"
+    applies_to:
+      extensions: [".ts", ".js", ".vue"]
+    description: "console.log 调试语句不应提交到代码库，应使用项目中的 logger 工具替代。"
+
+  - id: "no-any-type"
+    title: "禁止使用 any 类型"
+    severity: "warning"
+    applies_to:
+      extensions: [".ts", ".tsx"]
+    description: "TypeScript 中使用 any 会导致类型检查失效，应使用具体类型或泛型替代。"
+```
+
+**后端 Python 规则：**
+
+```yaml
+name: "Python Backend Rules"
+rules:
+  - id: "no-eval"
+    title: "禁止使用 eval"
+    severity: "error"
+    applies_to:
+      extensions: [".py"]
+    description: "禁止使用 eval，存在严重的代码注入安全风险。"
+
+  - id: "sql-injection"
+    title: "防止 SQL 注入"
+    severity: "error"
+    applies_to:
+      extensions: [".py"]
+    description: "禁止拼接 SQL 语句，必须使用参数化查询。"
+
+  - id: "no-hardcoded-secrets"
+    title: "禁止硬编码密钥"
+    severity: "error"
+    applies_to:
+      extensions: [".py"]
+    description: "禁止在代码中硬编码 API Key、密码等敏感信息，应使用环境变量。"
+```
+
+---
+
+## 通知中心
+
+通知中心提供三种互补的报告查看方式：
+
+### 1. 系统弹窗（即时提醒）
+
+每次审查完成后自动弹出 Windows/macOS/Linux 系统通知。适合快速获知审查结果。
+
+- Windows：优先使用 BurntToast，回退到 BalloonTip
+- 弹窗内容包含 issue 摘要
+- 受抑制规则控制，被抑制的 issue 不触发弹窗
+
+### 2. 终端 Inbox（日常浏览）
+
+```bash
+ai-review inbox                    # 列出报告
+ai-review inbox --unread           # 仅看未读
+ai-review inbox show <report-id>   # 查看详情（自动标记已读）
+ai-review inbox mark-all-read      # 全部标记已读
+```
+
+在终端直接浏览、搜索、阅读报告。适合开发者日常工作流。
+
+### 3. HTML 仪表盘（全景视图）
+
+```bash
+ai-review inbox dashboard          # 生成并打开仪表盘
+```
+
+自动生成 `.ai-review/reports/index.html`，在浏览器中打开。功能：
+
+- 所有报告按时间倒序排列，状态分色标记
+- 点击展开查看每个 issue 的详情和代码建议（diff 风格）
+- 顶部搜索栏实时过滤
+- 未读标记（蓝点）
+- 深色主题，适配开发者审美
+
+> 异步审查完成后，如果 `dashboard.auto_open` 为 `true`（默认），会自动在浏览器中打开仪表盘。
+
+---
+
+## 抑制系统
+
+对于已知但暂不打算处理的问题，可以抑制其弹窗通知。
+
+### 工作机制
+
+抑制**不会**影响审查本身：
+- 审查照常运行
+- 报告照常生成（包含被抑制的问题）
+- **仅跳过弹窗通知**
+
+### 使用方法
+
+```bash
+# 抑制某个文件的某条规则
+ai-review suppress src/legacy/old.ts no-eval --reason "遗留代码，计划 Q3 重构"
+
+# 抑制某个文件的所有规则
+ai-review suppress src/legacy/old.ts --all --reason "遗留模块，不做审查"
+
+# 查看已抑制项
+ai-review suppress --list
+
+# 取消抑制
+ai-review suppress src/legacy/old.ts no-eval --cancel
+```
+
+### 匹配规则
+
+抑制匹配支持三级策略，解决 LLM 输出格式与规则 ID 不一致的问题：
+
+1. **精确匹配** — 规则 ID 完全一致（忽略大小写和下划线/连字符差异）
+2. **子串匹配** — 抑制的 ID 包含在 LLM 输出的 rule_id 中
+3. **关键词匹配** — 从抑制 ID 中提取关键词（如 `no-console-log` → `console`, `log`），全部出现在 issue 消息中则匹配
+
+---
+
+## 项目结构
+
+```
+your-project/
+├── .ai-review.yaml            # 项目配置文件
+└── .ai-review/
+    ├── memory.json             # 记忆数据（风险分数、抑制记录、inbox 状态）
+    ├── rules/                  # 自定义审查规则
+    │   ├── frontend.yaml
+    │   ├── backend.yaml
+    │   └── css-rules.yaml
+    └── reports/                # 审查报告（自动生成）
+        ├── index.html          # HTML 仪表盘
+        ├── review_<tag>_<ts>.json
+        └── review_<tag>_<ts>.md
+```
+
+### 源码结构
+
+```
+src/ai_review/
+├── cli.py                     # 主 CLI 入口（check/init/suppress/status）
+├── cli_inbox.py               # Inbox 子命令（inbox list/show/read/dashboard）
+├── config.py                  # 配置系统（分层合并、模式默认值）
+├── dashboard.py               # HTML 仪表盘生成器
+├── inbox.py                   # Inbox 管理器（报告注册、已读状态）
+├── memory/
+│   └── store.py               # 记忆系统（风险分数、抑制、衰减）
+├── llm/
+│   ├── base.py                # LLM 提供者抽象接口
+│   ├── ollama.py              # Ollama 本地后端
+│   └── openai.py              # OpenAI 兼容后端
+├── prompt/
+│   └── builder.py             # Prompt 构建（fast/full 两种模式）
+├── reviewer/
+│   ├── screener.py            # Pre-commit 快速筛查器
+│   └── parser.py              # LLM 输出解析（JSON 优先 + 文本回退）
+├── rules/
+│   ├── loader.py              # 规则加载和文件匹配
+│   └── formatter.py           # 规则格式化（prompt/JSON/HTML）
+├── hooks/
+│   └── installer.py           # Git Hook 安装/卸载
+└── output/
+    ├── notify.py              # 系统通知（跨平台，三级回退）
+    └── terminal.py            # Rich 终端格式化输出
+```
+
+---
+
+## 注意事项
+
+### 环境变量
+
+| 变量 | 用途 | 示例 |
+|------|------|------|
+| `ZHIPU_API_KEY` | 智谱 API Key | `export ZHIPU_API_KEY="xxx"` |
+| `OPENAI_API_KEY` | OpenAI API Key | 默认变量名，可通过 `api_key_env` 自定义 |
+| `AI_REVIEW_MODE` | 覆盖运行模式 | `export AI_REVIEW_MODE="strict"` |
+
+> Windows 用户设置环境变量后需**重启终端**才能生效，或使用：
+> ```powershell
+> [Environment]::SetEnvironmentVariable("ZHIPU_API_KEY", "your-key", "User")
+> ```
+
+### 编码问题
+
+工具内部已处理 Windows GBK 编码问题（emoji 输出、子进程中文），无需额外配置。
+
+### 性能
+
+| 场景 | 典型耗时 | 说明 |
+|------|---------|------|
+| Pre-commit 筛查 | 5-15 秒 | 仅发送 diff + error 级别规则，prompt 较短 |
+| Post-commit 全量审查 | 10-30 秒 | 包含所有规则，返回详细报告和代码建议 |
+| 手动审查 | 10-30 秒 | 同全量审查 |
+
+> Pre-commit 超时默认 30 秒，超时自动放行（不阻止提交）。可在配置中调整 `hooks.pre_commit.timeout`。
+
+### LLM 故障处理
+
+- Pre-commit：LLM 不可用时**自动放行**，不阻止提交
+- Post-commit：LLM 不可用时**静默跳过**，不影响工作流
+- 解析失败：LLM 返回无法解析的内容时**自动放行**
+
+### 报告管理
+
+- 报告存储在 `.ai-review/reports/` 下，每份报告包含 `.json`（机器可读）和 `.md`（人类可读）
+- 建议将 `.ai-review/reports/` 加入 `.gitignore`，报告为本地开发辅助数据
+- HTML 仪表盘每次审查后自动重新生成，始终反映最新状态
+
+### 记忆系统衰减
+
+- 警告记录 30 天后自动衰减清理
+- 风险分数基于警告出现频率计算（0-10 分）
+- 提醒策略随重复次数递减：完整 → 简短 → 最小 → 静默
+
+### Windows 通知
+
+系统弹窗依赖 Windows 通知服务：
+
+- 推荐安装 BurntToast PowerShell 模块获得最佳体验：`Install-Module -Name BurntToast -Force -Scope CurrentUser`
+- 如通知被系统设置屏蔽，工具会自动回退到终端输出
+- 通知中心（inbox + dashboard）不依赖系统通知服务，始终可用
+
+### 与 CI/CD 的关系
+
+本工具定位为**本地开发辅助**，在开发者提交代码时提供即时反馈，不替代 CI/CD 中的代码审查流程。建议将 `.ai-review/` 目录加入 `.gitignore`：
+
+```gitignore
+# AI Code Review 本地数据
+.ai-review/memory.json
+.ai-review/reports/
+```
+
+### 常见问题
+
+**Q: 提交时没有触发审查？**
+
+检查 Git Hook 是否安装：
+
+```bash
+ls .git/hooks/pre-commit
+ls .git/hooks/post-commit
+```
+
+如果不存在，运行 `ai-review init` 重新安装。
+
+**Q: 审查超时了？**
+
+Pre-commit 默认超时 30 秒。如果 LLM 响应较慢，可在 `.ai-review.yaml` 中增加超时：
+
+```yaml
+hooks:
+  pre_commit:
+    timeout: 60
+```
+
+**Q: 如何临时跳过审查？**
+
+方法一：设置环境变量（如果配置了 `bypass_env_vars`）
+方法二：使用 `--no-verify` 跳过 Git Hook（`git commit --no-verify`）
+
+> 不推荐长期使用 `--no-verify`，应通过抑制系统处理已知问题。
+
+**Q: 报告中 rule_id 是中文，抑制不生效？**
+
+抑制系统支持模糊匹配，会从英文规则 ID 中提取关键词与 issue 消息内容匹配。如果仍不生效，检查 `ai-review suppress --list` 中存储的文件路径是否与报告中的路径一致。
+
+**Q: 支持 GitLab / Bitbucket 吗？**
+
+工具通过 Git 命令获取 diff 信息，与代码托管平台无关，任何 Git 仓库均可使用。