开源CLI代码审查工具：Git驱动的本地LLM代码评审实现-育师

1. 项目概述：一个真正能落地的开源代码审查 CLI 工具

“open-code-review”这个名字乍看平平无奇，但拆开来看——open不是指“开源”，而是指“开放上下文”；code-review也不是简单地跑个 linter 或拼凑几行 commit message，而是让大语言模型（LLM）在真实 Git 工作流中，以开发者视角完成一次有依据、可追溯、带上下文感知的代码审查。我从去年开始在团队内部打磨这个工具，不是为了造轮子，而是因为市面上所有“LLM + Code Review”的方案，要么卡在 prompt 工程里反复调参，要么把 diff 当全文喂给模型，导致 review 结果空泛、漏报严重、甚至把 config.yaml 里的 API key 当漏洞标出来。我们最终落地的版本，核心就三件事：精准提取变更上下文、隔离敏感信息、绑定 Git 生命周期。它不依赖任何云服务，不上传代码到第三方，所有推理都在本地或私有模型 endpoint 完成；它不替代人工 review，而是把工程师从“找哪改了、为什么这么改、有没有副作用”这些重复劳动里解放出来，把注意力聚焦在“这个设计是否合理”“边界条件是否覆盖”这类高价值判断上。适合两类人：一是中小型技术团队想快速建立轻量级自动化 code review 能力，又不愿把代码交给 SaaS 平台；二是个人开发者想在提交前做一次“AI 同伴复盘”，尤其适合写脚本、维护 legacy 项目、或者接手别人代码时快速建立认知地图。它不是 magic wand，但确实是目前我见过最贴近真实开发节奏的 CLI code review 实现。

2. 整体设计思路与架构选型逻辑

2.1 为什么必须是 CLI 而非 Web 或 IDE 插件？

很多人第一反应是：“做个 VS Code 插件多方便？”——这恰恰是我们放弃的第一条路。原因很实际：IDE 插件生命周期不可控、环境依赖复杂、权限模型模糊。比如你用 JetBrains 系列，插件要适配 IntelliJ、PyCharm、WebStorm 多个平台；VS Code 插件则面临 Node.js 版本、WebView 沙箱、扩展主机进程崩溃等一堆 runtime 问题。更关键的是，真正的 code review 发生在 Git commit 前后，而不是编辑器打开文件时。我们观察了团队 37 次典型 review 场景，发现 82% 的有效反馈都来自“这次改了什么 + 为什么这么改 + 关联影响范围”这三个维度，而这三个维度的信息，只有 Git 的 staging area、commit message、branch history 和 diff 本身才完整携带。IDE 插件能看到当前文件，但看不到 staging 中其他文件的改动，也读不到 commit -m 里的设计意图，更无法关联 PR description 或 issue link。CLI 则天然站在 Git 流程的咽喉位置：git add后可触发 pre-commit hook，git commit时可拦截并注入 review 结果，git push前可生成标准化 review report。它不侵入编辑体验，只在关键决策点提供上下文增强。我们实测过，在git commit -m "fix: handle null pointer in user service"这一刻，CLI 能自动拉取该 commit 影响的函数签名、调用链上游/下游、最近三次对该函数的修改记录，并把这些结构化数据喂给 LLM——这种能力，IDE 插件根本做不到。

2.2 为什么选择“Git 驱动”而非“文件驱动”？

市面上很多 LLM code review 工具要求你指定一个文件路径或目录，然后扫描全部内容。这在 demo 里很炫酷，但在真实项目里就是灾难。试想：你改了user_service.go里一行逻辑，工具却把整个pkg/user/目录（含 12 个文件、3400 行代码）塞给模型——不仅 token 暴涨、响应变慢，更致命的是模型会丢失“这次改动的意图权重”。LLM 不是搜索引擎，它对输入文本的开头和结尾更敏感，中间大段无关代码会稀释核心变更的信号。我们的解法是：一切以 Git diff 为源头，反向推导最小必要上下文。具体流程是：

解析git diff --cached输出，提取所有被修改的文件及行号范围；
对每个变更块，用 AST（抽象语法树）解析器定位到精确的函数、方法、类定义；
向上追溯调用链（最多 2 层），向下抓取被该函数直接调用的依赖函数（仅限同一 package）；
提取这些函数的 signature（签名）、docstring、最近一次 commit message（用于理解修改动机）；
把这些结构化片段，按“变更块 → 所属函数 → 上游调用 → 下游依赖”的层级组织成 prompt context。
这套逻辑让平均输入 token 从 8000+ 降到 1200 以内，review 准确率提升 3.2 倍（基于我们内部标注的 156 个真实 bug 样本集）。更重要的是，它让 LLM 的输出天然具备“可验证性”——每一条建议都能回溯到具体的 diff 行、函数名、commit hash，而不是泛泛而谈“建议优化性能”。

2.3 为什么坚持“本地优先 + 模型可插拔”？

热词里反复出现 “llm 密钥泄露”“prompt injection”“agent 和 llm 区别”，这说明大家已经意识到：把 LLM 当黑盒 API 调用，风险远大于收益。我们拒绝内置任何厂商 SDK（比如不硬编码 OpenAI 或 Anthropic 的 client），而是定义了一套极简的ModelProvider接口：

# 任何符合此协议的 endpoint 都能接入 curl -X POST http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-coder-33b-instruct", "messages": [{"role":"user","content":"<context>...</context>"}], "temperature": 0.3, "max_tokens": 1024 }'

这意味着你可以：

用 Ollama 本地跑deepseek-coder，完全离线；
用 vLLM 部署Qwen2.5-Coder，吞吐翻 4 倍；
甚至对接公司内网的私有 Llama 3 微调模型，只要它支持 OpenAI 兼容 API。
安全方面，我们做了三重隔离：

环境变量过滤：启动时自动扫描.env、~/.gitconfig、$HOME/.zshrc等文件，移除所有含API_KEY、SECRET、TOKEN字样的行（正则(?i)(api|secret|token|key).*=）；
diff 内容清洗：对 Git diff 输出做两遍处理——第一遍删掉所有匹配https?://[^\s]+的 URL（防止泄露内部服务地址），第二遍用规则引擎识别并掩码常见密钥格式（如sk-.*[a-zA-Z0-9]{32}、AKIA[0-9A-Z]{16}）；
context 注入沙箱：所有传给 LLM 的上下文，都经过context-sandbox模块处理，强制将路径/home/alice/project/替换为<PROJECT_ROOT>，将用户名alice替换为<USER>，彻底切断模型对真实环境的感知。
这套设计让我们在金融客户现场部署时，通过了他们严苛的渗透测试——他们专门构造了含 AWS key 的 commit，结果 review report 里只看到<REDACTED_AWS_ACCESS_KEY>，且模型未产生任何越权推理。

3. 核心细节解析与实操要点

3.1 Git 集成机制：如何让 review 成为 commit 的自然环节？

“open-code-review” 不是独立运行的命令，而是深度嵌入 Git 生命周期的守门员。它的核心不是ocr review这样的手动命令，而是git commit的智能增强。实现方式分三层：

第一层：pre-commit hook 自动触发
我们在.git/hooks/pre-commit里写入：

#!/bin/bash # 检查是否安装了 open-code-review if ! command -v ocr &> /dev/null; then echo "⚠️ open-code-review 未安装，跳过自动 review" exit 0 fi # 获取本次 commit 的 staged 文件列表 STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(go|py|js|ts|java|cpp)$') if [ -z "$STAGED_FILES" ]; then exit 0 fi # 执行 review，超时 90 秒，失败则阻断 commit if ! timeout 90s ocr review --staged --format=github; then echo "❌ open-code-review 检测到高风险问题，commit 已中止" echo "💡 运行 'ocr review --staged --verbose' 查看详细报告" exit 1 fi

这里的关键细节：

文件类型白名单：只对主流语言源码生效，避免扫描.md、.json等非代码文件；
timeout 严格控制：90 秒是经过压测的平衡点——本地 Ollama 模型平均响应 12 秒，vLLM 集群平均 3.2 秒，留出足够 buffer 防止卡住开发流；
exit code 语义明确：非零退出即中断 commit，这是 Git hook 的标准契约，无需额外解释。

第二层：commit message 意图解析
我们发现，73% 的有效 review 建议都依赖对git commit -m内容的理解。比如feat: add rate limit to auth endpoint和chore: update deps，模型需要完全不同的审查重点。为此，我们训练了一个轻量级 intent classifier（仅 1.2MB），用 commit message 做 zero-shot 分类：

Intent Type	审查重点	示例 prompt 片段
`feat`	新功能完整性、接口兼容性、文档同步	“用户新增了 rate limiting 功能，请检查是否覆盖了所有 auth endpoint 的入口，是否提供了配置开关，是否更新了 README.md 中的 usage 示例”
`fix`	根本原因分析、回归测试覆盖、边界条件	“修复了空指针异常，请确认是否在所有可能为 null 的路径上都加了 guard clause，是否添加了对应的单元测试用例”
`refactor`	重构安全性、行为一致性、性能影响	“重构了 user service 的缓存逻辑，请验证新旧实现返回结果是否一致，内存占用是否增加超过 15%”
这个 classifier 不依赖外部 API，纯本地运行，准确率 91.4%（测试集 2000 条 commit message）。它让 review 不再是通用模板，而是针对每次提交意图的定制化诊断。

第三层：review report 格式化与可操作性
输出不是一长段文字，而是结构化 Markdown，直接兼容 GitHub/GitLab 的 comment 渲染：

### 🔍 open-code-review 检测报告（commit: a1b2c3d） - **高风险** `user_service.go:45` > 检测到潜在竞态条件：`sync.Mutex` 在 `UpdateUser` 方法中未覆盖所有写操作路径。建议将 `userCache.Set()` 移至 `mu.Lock()` 保护范围内。 📌 关联 commit: `e7f8g9h`（上次修改此函数） 📌 AST 节点：`func (s *UserService) UpdateUser(...)` - **中风险** `auth/middleware.go:128` > 日志级别过高：`log.Fatal()` 在中间件中会导致服务崩溃。建议改为 `log.Error()` 并返回 HTTP 500。 📌 调用链：`AuthMiddleware → validateToken → log.Fatal`

每条建议都带可点击的文件行号链接（VS Code 用户点击直接跳转）、关联历史 commit（方便追溯设计演进）、AST 节点标识（避免因代码格式化导致行号漂移）。这种设计让开发者一眼就能定位、验证、修复，而不是在一堆文字里找线索。

3.2 上下文提取引擎：AST 解析与调用链追踪的实战技巧

“精准提取上下文”听起来很学术，但落地时全是坑。我们最初用go list -f '{{.Deps}}'获取依赖，结果发现它返回的是 import path，不是实际调用关系——import "net/http"不代表代码里真调用了http.ServeHTTP()。后来转向 AST 解析，但 Go 的go/ast包对跨 package 调用链支持有限。最终方案是：语言特化 + 缓存加速。

Go 语言实现：

用golang.org/x/tools/go/loader加载整个 module，获取所有 package 的 AST；
遍历*ast.CallExpr节点，提取Fun字段（调用目标）；
对SelectorExpr（如db.QueryRow），解析X.Obj获取 receiver 类型，再查其 method set；
对Ident（如fmt.Println），直接匹配builtin或std包函数；
关键技巧：我们不实时解析，而是构建callgraph.dbSQLite 数据库，存入(caller_func, callee_func, file, line)四元组。首次运行ocr init时全量扫描，后续只增量更新——这让git commit触发的 review 响应时间从 8.2s 降到 1.4s。

Python 语言实现：

放弃ast模块（太底层），改用pyan3（Python AST Navigator）生成 call graph；
但pyan3依赖graphviz，CI 环境常缺失。于是我们用astroid库做轻量解析：

from astroid import MANAGER module = MANAGER.ast_from_module_name("user_service") for func in module.get_children(): if isinstance(func, astroid.FunctionDef): # 提取 func.body 中的所有 Call 节点 for call in func.nodes_of_class(astroid.Call): if hasattr(call.func, 'name'): print(f"{func.name} calls {call.func.name}")

避坑经验：Python 的动态特性（getattr,eval,importlib）会让静态分析漏报。我们的对策是：当检测到getattr(obj, method_name)时，不尝试解析method_name，而是标记为DYNAMIC_CALL，并在 review report 里提示“此处存在动态调用，建议人工验证”。宁可保守，也不误报。

通用原则：

最大深度限制为 2：A → B → C可以，A → B → C → D截断。实测发现，超过 2 层的调用链，对本次变更的影响概率低于 3.7%，但 token 开销翻倍；
跨语言调用不追踪：Go 调 Python（cgo）、JS 调 WASM 等场景，直接忽略。我们专注“同语言、同 repo”的上下文，这是 95% 的真实需求；
缓存键设计：cache_key = sha256(f"{git_head_commit}_{language}_{file_path}")，确保不同分支、不同 commit 的上下文绝对隔离，避免污染。

3.3 敏感信息防护：不只是正则替换，而是数据流级治理

热词里高频出现 “llm 密钥泄露”，这不是危言耸听。我们做过实验：把含 AWS key 的 diff 喂给gpt-3.5-turbo，模型在 response 里没直接泄露 key，但生成了“建议将密钥存储在环境变量中”的代码示例——而这个示例里，os.Getenv("AWS_SECRET_ACCESS_KEY")的变量名，恰恰暴露了密钥类型和用途。所以，防护必须贯穿数据流全程。

第一道防线：diff 输入清洗
我们不用简单的sed 's/.*API_KEY.*//g'，而是构建SecretDetector模块：

规则引擎：预置 47 种密钥模式（AWS、GCP、Azure、GitHub Token、Slack Bot Token 等），每种模式带置信度阈值；
上下文感知：只在config/,deploy/,.env,secrets.yaml等高风险路径的文件中启用严格模式；
掩码策略：对匹配项，用<REDACTED_{TYPE}_{HASH}>替换，如AKIAIOSFODNN7EXAMPLE→<REDACTED_AWS_ACCESS_KEY_8a3f2>。hash 用前 4 字符，既保证唯一性，又不泄露原始长度。

第二道防线：context 注入沙箱
这是最容易被忽视的环节。很多工具把清洗后的 diff 直接拼进 prompt，但 LLM 仍可能从代码结构推断出敏感信息。例如：

// 清洗后仍存在的风险 func NewClient() *Client { return &Client{ baseURL: "https://internal-api.company.com", // 即使删了 token，域名仍暴露内网架构 apiKey: "<REDACTED_AWS_ACCESS_KEY_8a3f2>", // 掩码后，模型仍知这是 AWS key } }

我们的解法是：在 AST 解析阶段，对所有字符串字面量做语义分类：

URL类型：https://...→ 替换为<INTERNAL_API_ENDPOINT>；
Path类型：/etc/secrets/db.key→ 替换为<CONFIG_FILE_PATH>；
EnvVar类型：os.Getenv("DB_PASSWORD")→ 替换为<ENV_VAR_DB_PASSWORD>；
HardcodedKey类型：已由 SecretDetector 处理。
这样，传给 LLM 的 context 是：

func NewClient() *Client { return &Client{ baseURL: "<INTERNAL_API_ENDPOINT>", apiKey: "<REDACTED_AWS_ACCESS_KEY_8a3f2>", } }

模型看到的不再是真实业务信息，而是抽象的占位符，从根本上杜绝信息泄露。

第三道防线：output 后处理
LLM 的 response 可能包含“请检查config.yaml中的aws_secret_key字段”这样的建议——这本身就在泄露信息。我们用OutputSanitizer对 response 做二次扫描：

识别所有<REDACTED_.*>占位符，还原其原始含义（如<REDACTED_AWS_ACCESS_KEY_8a3f2>→AWS secret key）；
将这些含义映射到通用术语（AWS secret key→authentication credential）；
在最终 report 中，用通用术语替代，如“请检查配置文件中的认证凭据是否安全存储”。
这套三级防护，让我们在 OWASP ZAP 扫描中，0 次触发敏感信息泄露告警。

4. 实操过程与核心环节实现

4.1 从零安装到首次 review：手把手实战指南

假设你用的是 macOS 或 Linux（Windows 用户请先装 WSL2），以下是完整流程，每一步都附带原理说明和避坑提示。

步骤 1：安装 Git 与基础依赖

# 确保 Git 2.30+（需支持 --no-optional-locks 等新 flag） git --version # 若 < 2.30，升级：brew install git（macOS）或 apt install git（Ubuntu） # 安装 Go 1.21+（用于编译 ocr CLI） go version # 若未安装，官网下载或 brew install go # 安装 Python 3.9+（用于 Python 项目上下文解析） python3 --version # 若未安装，pyenv install 3.11.7 && pyenv global 3.11.7

提示：不要跳过版本检查！open-code-review依赖 Git 的--no-optional-locks参数避免并发冲突，依赖 Go 的embed特性打包前端资源，低版本会编译失败。

步骤 2：安装 open-code-review CLI

# 方式一：二进制下载（推荐，免编译） curl -L https://github.com/your-org/open-code-review/releases/download/v0.8.3/ocr-darwin-arm64 -o /usr/local/bin/ocr chmod +x /usr/local/bin/ocr # 方式二：源码编译（适合想 hack 的人） git clone https://github.com/your-org/open-code-review.git cd open-code-review make build # 会自动下载依赖、编译、生成 ./bin/ocr sudo cp ./bin/ocr /usr/local/bin/

注意：二进制包已签名，下载后建议校验 SHA256：shasum -a 256 ocr-darwin-arm64对比 release 页面公布的 checksum。这是防供应链攻击的基本操作。

步骤 3：初始化项目配置

# 进入你的 Git 项目根目录 cd ~/my-project # 初始化 ocr 配置（会创建 .ocr.yaml） ocr init # 编辑 .ocr.yaml，关键配置项： cat .ocr.yaml

# .ocr.yaml 示例 model: provider: "ollama" # 可选：ollama, vllm, openai, anthropic endpoint: "http://localhost:11434" # ollama 默认端口 model_name: "deepseek-coder:33b" # 必须是已 pull 的模型名 git: ignore_patterns: # 忽略不审查的文件 - "**/test/**" - "**/*.md" - "migrations/**" review: severity_threshold: "medium" # high/medium/low，低于此级别的不阻断 commit max_context_lines: 200 # 单个函数上下文最大行数，防 token 溢出

实操心得：model_name必须和ollama list输出的名称完全一致（包括 tag）。我们曾遇到用户填deepseek-coder:latest，但 ollama 实际 pull 的是deepseek-coder:33b，导致 404 错误。建议运行ollama list确认后再填。

步骤 4：首次运行 review

# 修改一个文件，比如修复一个 bug echo "fmt.Println(\"hello world\")" >> main.go git add main.go # 手动触发 review（调试用） ocr review --staged --verbose # 输出示例： # [INFO] Detected 1 staged file: main.go # [INFO] Extracting context for main.go:45-45... # [INFO] Querying model deepseek-coder:33b... # [RESULT] ✅ No issues found. Ready to commit.

关键观察：--verbose会显示上下文提取详情，这是 debug 的黄金开关。如果卡住，先看这一步是否成功——若失败，90% 是模型 endpoint 未启动或网络不通。

步骤 5：启用 pre-commit hook（生产就绪）

# 自动生成 hook（覆盖原有 pre-commit） ocr setup-hook # 验证 hook 是否生效 ls -l .git/hooks/pre-commit # 应显示可执行权限

现在，每次git commit都会自动触发 review。如果检测到 high 风险问题，commit 会被中止，并打印清晰的修复指引。

4.2 模型接入实战：Ollama、vLLM、OpenAI 三种方案详解

“open-code-review” 的核心价值在于模型可插拔。以下是三种主流方案的实操对比，包含参数调优和效果验证。

方案一：Ollama 本地运行（适合个人/小团队）

# 1. 安装 Ollama # macOS: brew install ollama # Ubuntu: curl -fsSL https://ollama.com/install.sh | sh # 2. 拉取推荐模型（DeepSeek-Coder 33B 是目前开源最强） ollama pull deepseek-coder:33b # 3. 启动 Ollama（默认监听 localhost:11434） ollama serve & # 4. 配置 .ocr.yaml model: provider: "ollama" endpoint: "http://localhost:11434" model_name: "deepseek-coder:33b" temperature: 0.2 # 低温度，保证 review 建议稳定 max_tokens: 1024

实测数据：M2 Max Mac 上，deepseek-coder:33b平均响应 14.2s，CPU 占用 82%，内存峰值 12GB。建议关闭其他 heavy app。效果：对 Go/Python 代码，high 风险 bug 检出率 89.3%（对比人工 review 黄金标准）。

方案二：vLLM 高性能集群（适合中大型团队）

# 1. 部署 vLLM（需 GPU） pip install vllm python -m vllm.entrypoints.api_server \ --host 0.0.0.0 \ --port 8000 \ --model Qwen2.5-Coder-32B-Instruct \ --tensor-parallel-size 2 \ --gpu-memory-utilization 0.9 # 2. 配置 .ocr.yaml model: provider: "vllm" endpoint: "http://vllm-server:8000/v1" model_name: "Qwen2.5-Coder-32B-Instruct" temperature: 0.15 max_tokens: 2048

关键配置：--tensor-parallel-size必须匹配 GPU 数量；--gpu-memory-utilization 0.9防止 OOM。实测：A100 x2 集群，QPS 达 12.7，平均延迟 2.8s，支持 50+ 并发 review 请求。成本：比同等性能的 OpenAI API 便宜 63%。

方案三：OpenAI API（适合快速验证）

# 1. 获取 API Key（从 platform.openai.com） # 2. 配置 .ocr.yaml（注意：务必设低 temperature！） model: provider: "openai" endpoint: "https://api.openai.com/v1" model_name: "gpt-4o" api_key: "sk-..." # ⚠️ 强烈建议用环境变量：OCR_OPENAI_API_KEY temperature: 0.1 max_tokens: 1536

安全警告：永远不要把 API key 写在 .ocr.yaml 里！正确做法：

export OCR_OPENAI_API_KEY="sk-..." ocr review --staged

效果对比：gpt-4o在代码理解上略胜一筹，但temperature 0.1下，相同 diff 的两次 review 结果一致性仅 76%（vs DeepSeek 的 94%）。这意味着它更适合 exploratory review，而非 blocking commit。

4.3 定制化 review 规则：用 YAML 定义你的团队规范

默认 review 基于通用编程最佳实践，但每个团队都有独特规范。open-code-review支持用.ocr-rules.yaml定义自定义规则，这是它区别于其他工具的核心能力。

示例：禁止在 Go 代码中使用log.Fatal

# .ocr-rules.yaml rules: - id: "GO_LOG_FATAL_FORBIDDEN" name: "禁止使用 log.Fatal" language: "go" pattern: | # AST 模式匹配：查找所有 log.Fatal 调用 call_expr: func: "log\.Fatal" severity: "high" message: "log.Fatal 会导致进程退出，违反微服务优雅降级原则。请改用 log.Error + return error。" fix_suggestion: | # 自动修复建议（可选） replace: from: "log.Fatal(" to: "log.Error(" - id: "PYTHON_NO_PRINT_IN_PROD" name: "生产环境禁用 print" language: "python" pattern: | # 正则模式匹配：查找顶层 print 语句 regex: "^\s*print\(" severity: "medium" message: "print 语句会污染 stdout，影响日志采集。请改用 logging.getLogger(__name__).info()"

实操要点：

pattern支持 AST 和 regex 两种模式，AST 更精准，regex 更灵活；
fix_suggestion是可选的，但一旦定义，ocr fix命令就能自动应用；
规则文件支持include，可拆分成security.yaml、performance.yaml、style.yaml多个文件，便于团队协作维护。

如何启用规则？

# 在 .ocr.yaml 中引用 review: rules_file: ".ocr-rules.yaml"

经验分享：我们团队第一条自定义规则就是禁止log.Fatal。上线后，生产环境因日志导致的进程崩溃事故下降了 100%——因为所有log.Fatal都在 commit 阶段被拦截，开发者被迫思考错误处理路径。这就是工具驱动文化变革的力量。

5. 常见问题与排查技巧实录

5.1 模型响应超时或返回空：5 个必查点

这是新手最常遇到的问题，90% 可通过以下 checklist 解决：

检查点	操作命令	预期结果	常见原因
1. 模型 endpoint 是否存活？	`curl -v http://localhost:11434/health`	返回`{"status":"ok"}`	Ollama 未启动；vLLM server 进程崩溃；防火墙拦截端口
2. 模型是否已加载？	`curl http://localhost:11434/api/tags`	JSON 列表中包含`"name":"deepseek-coder:33b"`	模型未 pull；模型名拼写错误（如`deepseek-coder:33b`vs`deepseek-coder:33b-instruct`）
3. API key 是否正确？	`export OCR_DEBUG=1; ocr review --staged`	日志中显示`Request URL: https://api.openai.com/v1/chat/completions`	OpenAI key 过期；Anthropic key 权限不足（需`messages`权限）
4. Git staging 是否为空？	`git diff --cached --quiet	echo "有变更"`
5. 上下文提取是否失败？	`ocr context --file main.go --line 45`	输出结构化 JSON context	文件路径错误；Go module 未初始化（`go mod init`未运行）；Python virtualenv 未激活

独家技巧：启用OCR_DEBUG=1环境变量，所有内部调用（HTTP request/response、AST 解析日志、token 计数）都会打印。这是定位问题的终极开关，比任何文档都管用。

5.2 review 结果不准：为什么 LLM 总是“看不懂”我的代码？

这不是模型问题，而是上下文供给问题。我们统计了 217 次 inaccurate review 报告，根源分布如下：

根本原因	占比	解决方案
AST 解析失败	42%	检查 Go module 是否`go mod tidy`；Python 项目是否`pip install -e .`安装了依赖（否则 astroid 找不到 import）
调用链截断过早	28%	在`.ocr.yaml`中调高`review.max_call_depth: 3`（但需同步调低`max_context_lines`防 token 溢出）
commit message 意图识别错误	18%	手动指定 intent：`git commit -m "feat: add rate limit" --no-edit`，或用`ocr review --intent=feat`覆盖自动识别
模型能力不足	12%	换更强模型（如`Qwen2.5-Coder-32B`vs`deepseek-coder:6.7b`），或调整`temperature: 0.05`降低随机性

实战案例：某次 review 总是漏报数据库事务问题。debug 发现，AST 解析器把tx.Commit()识别为普通函数调用，而非事务结束信号。解决方案：在.ocr-rules.yaml中添加一条规则，强制将tx.Commit()和tx.Rollback()视为事务边界节点，参与上下文提取。这证明：规则引擎 + AST 解析，才是应对复杂代码逻辑的正解，不是靠换更大模型。