开源本地化代码审查CLI工具：AST感知+本地LLM深度分析

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

“open-code-review”这个名字乍一听像某个 GitHub 上刚起步的玩具项目，但如果你最近在团队里被 PR 堆得喘不过气、被“请检查一下这段逻辑”这种模糊反馈折磨过，或者自己写完代码总不敢点 Merge，那它背后代表的不是又一个概念玩具，而是一套可嵌入日常开发流、不依赖私有 API、不上传源码到第三方、且能用本地大模型完成深度语义分析的代码审查闭环。我从去年开始在三个不同规模的团队里试过七种类似工具——从 GitHub Copilot 的 inline suggestion 到 CodeWhisperer 的 IDE 插件，再到 Dify + 自建 LLM 的 Web 端 review bot，最后回到命令行。结果发现：真正能每天稳定跑在 CI 流程里、能和git diff无缝衔接、能在开发者本地环境一键触发、且审查结论经得起 senior engineer 当面质疑的，只有极少数几个设计扎实的 CLI 工具，“open-code-review”正是其中最接近“开箱即用工业级标准”的那个。

它不是另一个 LLM 包装壳。核心差异在于：它把code review 拆解为三个不可跳过的阶段——diff 解析层（非简单 patch 提取，而是 AST-aware 的变更定位）、上下文构建层（自动识别函数签名、调用链、测试覆盖率缺口、历史 commit 关联）、以及 LLM 推理层（非 raw prompt 注入，而是带 role-based system message + structured output schema 的 constrained decoding）。这意味着它不会告诉你“这段代码可能有 bug”，而是输出：“【高危】validateEmail()在第 42 行移除了对空字符串的校验，该函数被UserRegistrationService.register()调用（见 commit abc123），且对应单元测试testValidatesEmptyEmail()已被删除（覆盖率下降 3.2%）”。这种颗粒度，是靠硬编码规则+LLM 协同实现的，不是单靠模型瞎猜。

适合谁？不是给 LLM 爱好者练手的玩具。它是给那些已经用 Git 做版本管理、用 GitHub/GitLab 托管代码、但苦于 code review 效率低下的中小型技术团队准备的——尤其适合没有专职 QA、没有专职 SRE、但又必须保障交付质量的创业公司或业务中台团队。你不需要懂 transformer 架构，但需要知道git diff --cached是什么；你不需要会微调 Qwen2-7B，但得会配~/.config/open-code-review/config.yaml。它不承诺替代人类 review，但它能把 review 中重复性最高、最耗时的 60% 工作（比如“这个变量命名是否符合规范”、“这个 if 分支有没有漏掉 else”、“这个 HTTP 错误码返回是否覆盖了所有异常路径”）提前拦截，让工程师把精力聚焦在真正的架构决策和边界 case 上。

2. 核心设计思路与方案选型逻辑

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

很多人第一反应是：“CLI？现在都 2024 年了，谁还用命令行做 code review？”——这恰恰是 open-code-review 最清醒的设计起点。我们团队曾用 Web 版 review bot 试运行三个月，结果发现三个致命问题：第一，review 结果延迟严重，平均要等 92 秒（含模型推理+网络传输+前端渲染），而开发者在git commit后等待超过 15 秒就会切走干别的；第二，上下文丢失严重，Web 端只能看到当前 diff，看不到整个文件的 import 链、看不到 test 文件里对应的 mock 数据、看不到 git blame 显示的上次修改人；第三，权限模型混乱，为了获取完整代码上下文，不得不给 bot 配置 repo 的 full access token，一旦 token 泄露，等于交出整个代码库。

CLI 方案直接绕过所有这些问题。它运行在开发者本机，天然拥有全部文件读写权限，git diff --cached输出的 patch 可以立刻喂给本地解析器；它能实时读取.git/config、package.json、pyproject.toml，自动识别项目语言栈和 lint 规则；它甚至能调用pytest --cov-report=term-missing获取当前变更的测试覆盖缺口。更重要的是，所有敏感信息——API key、token、未提交的代码、内部业务逻辑——全程不出本机内存。我们做过实测：用strace -e trace=connect,sendto,recvfrom监控进程，确认 open-code-review 在默认配置下零外网连接（除非你主动启用远程模型 endpoint）。这才是“open”二字的真正含义：开放源码、开放设计、开放审计，而非开放你的代码。

2.2 为什么选择本地 LLM 而非调用 OpenAI/Claude API？

热搜词里反复出现 “llm 密钥泄露”“prompt injection”“agent 和 llm 区别”，说明大家已经意识到云端模型的风险。open-code-review 默认使用Ollama + CodeLlama-7b-Instruct 或 Qwen2.5-Coder-7B，原因很实在：

• 速度可控：在 M2 Ultra Mac 上，CodeLlama-7b 处理 200 行 diff 的平均响应时间是 3.8 秒（batch_size=1, temperature=0.3）；换成 API 调用，光 DNS 解析+TLS 握手+排队等待就可能突破 5 秒，更别说网络抖动。
• 输出确定性：本地模型关闭 top_p、固定 seed，同一段 diff 连续 10 次 review 结果完全一致；而云端 API 即使固定 temperature，也会因服务端负载动态调整采样策略，导致 review 结论漂移——这对 CI 流程是灾难性的。
• 成本真实：按我们团队日均 120 次 review 计算，用 GPT-4-turbo API 月成本约 $1800；用本地 7B 模型，电费+折旧成本不到 $12/月。
• 合规兜底：金融客户明确要求“代码不得离开内网”，本地 LLM 是唯一满足项。我们甚至把模型权重放在 NAS 上，通过OLLAMA_HOST=192.168.1.100:11434指向内网 Ollama 服务，既共享资源又隔离风险。

当然，它也支持远程模型（如--model https://your-llm-gateway/v1/chat/completions），但必须显式声明，且默认禁用。这是设计哲学：安全不是可选项，而是默认态。

2.3 为什么强调 “AST-aware diff 解析”，而不是简单用正则匹配？

这是 open-code-review 和其他“LLM + git diff”工具的本质分水岭。普通工具拿到git diff输出，直接当纯文本塞给 LLM，结果就是模型看到一堆+if (user != null && user.getEmail() != null)和-if (user != null)，却不知道user.getEmail()调用了哪个类的哪个方法、这个user对象是从哪里 new 出来的、getEmail()是否可能抛出 NPE。open-code-review 内置了轻量级 AST 解析器（基于 tree-sitter），对主流语言做三件事：

1. 变更定位：把 diff 行号映射到 AST 节点 ID，精准定位“被修改的表达式”“被删除的分支”“新增的参数”；
2. 上下文提取：自动向上追溯到父函数、父类、import 语句；向下展开到被调用的方法签名、类型定义；
3. 语义标注：标记出user.getEmail()是 method call，user是 local variable，getEmail()返回String，从而让 LLM 的 prompt 里能写：“注意：此变更影响UserService.validateEmail(String)方法的空值校验路径，该方法被AuthController.login()调用”。

我们对比过：对同一段 Java diff，纯文本输入的 LLM 给出 4 条建议，其中 2 条错误（把Optional.ofNullable()误判为冗余）；AST-aware 输入给出 6 条建议，全部准确，且第 5 条指出：“Optional.ofNullable(user).map(User::getEmail).orElse("")替代原user != null ? user.getEmail() : ""可提升可读性，但需同步更新User.getEmail()的 Javadoc，注明其可能返回 null”。

2.4 为什么内置 Git 集成，而非做成独立工具？

因为真正的 code review 发生在 Git 的四个关键节点：pre-commit（提交前）、pre-push（推送前）、CI job（合并前）、post-merge（合并后复盘）。open-code-review 不是让你手动敲open-code-review --file src/main/java/UserService.java，而是让你在.husky/pre-commit里加一行：

npx open-code-review --stage --severity high --exit-code 1

它会自动：

• 执行git diff --cached --name-only获取暂存区文件列表；
• 对每个文件执行git show HEAD:src/main/java/UserService.java获取 base 版本；
• 对比当前暂存区内容，生成 AST-aware diff；
• 调用 LLM 分析，只报告 severity=high 的问题（如空指针、SQL 注入、硬编码密钥）；
• 若发现问题，exit 1阻止 commit，并输出带行号的 Markdown 报告。

这种深度集成，让 review 成为开发者的肌肉记忆，而不是额外负担。我们上线后，团队git commit失败率从 12% 降到 3%，但 PR 中被人工发现的高危 bug 数量下降了 67%——说明问题真正在提交前就被拦住了。

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

3.1 安装与基础配置：避开新手最常见的三个坑

安装本身很简单：npm install -g open-code-review或pip install open-code-review。但真正决定成败的是接下来的三步配置，90% 的用户卡在这儿：

第一坑：模型加载失败，报错Ollama connection refused
这不是 open-code-review 的 bug，而是 Ollama 服务没起来。正确流程是：

1. 先下载 Ollama 客户端（官网 ollama.com/download）；
2. 启动服务：ollama serve（后台运行）；
3. 拉取模型：ollama pull codellama:7b-instruct；
4. 验证：ollama list应显示codellama 7b-instruct latest ...。

提示：Mac 用户常忽略第 2 步，以为ollama run就够了；Linux 用户常因 SELinux 阻止ollama serve，需执行sudo setsebool -P container_manage_cgroup on。

第二坑：AST 解析器报错language not supported
open-code-review 支持 Java/Python/TypeScript/Go/Rust，但每种语言需要对应 tree-sitter parser。安装命令是：

# Python open-code-review install-parser python # TypeScript open-code-review install-parser typescript # Java（需先装 JDK） open-code-review install-parser java

注意：install-parser不是 npm install，而是下载二进制 parser 到~/.cache/open-code-review/parsers/。如果网络慢，可手动下载 release 包（GitHub 上搜 tree-sitter-java），解压后放到对应目录。

第三坑：Git 集成后pre-commit无限循环
这是因为 open-code-review 的 report 生成会触发 git add，进而再次触发 pre-commit。解决方案是在.husky/pre-commit脚本开头加守卫：

#!/usr/bin/env sh # 如果是 open-code-review 自动生成的 report，跳过 if [ "$GIT_COMMIT" = "" ] && [ -n "$(git status --porcelain | grep 'report.md')" ]; then exit 0 fi npx open-code-review --stage --severity high --exit-code 1

3.2 配置文件详解：.open-code-review.yaml的 7 个关键字段

默认配置文件位于~/.config/open-code-review/config.yaml，但强烈建议项目根目录放一份.open-code-review.yaml（会被优先读取）。以下是必须理解的 7 个字段：

特别注意rules字段：它不是开关，而是规则优先级队列。顺序决定 LLM 的 prompt 权重——排在前面的规则，LLM 会分配更多 token 去分析。比如把"sql-injection"放第一位，模型会更仔细检查字符串拼接。

3.3 自定义规则：如何编写一条真正有效的检查规则

open-code-review 的规则不是正则表达式，而是YAML 定义的语义模式 + LLM 指令。以“禁止硬编码数据库密码”为例，.rules/db-password.yaml内容如下：

name: "hardcoded-db-password" description: "Detect hardcoded database passwords in config files or connection strings" severity: "critical" languages: ["python", "java", "typescript"] patterns: - type: "ast" language: "python" query: '(assignment_statement left: (identifier) @key right: (string) @value) where (eq? @key "DB_PASSWORD")' # tree-sitter query：匹配形如 DB_PASSWORD = "xxx" 的赋值 - type: "text" regex: 'password\s*[:=]\s*[\'"]([^\'"]+)[\'"]' # 备用文本匹配，当 AST 解析失败时触发 llm_prompt: | 你是一名资深后端安全工程师。请严格检查以下代码片段： {{code_snippet}} 重点关注：1. 是否存在明文数据库密码；2. 密码是否来自环境变量或密钥管理服务；3. 如果是测试代码，请确认是否在 .env.test 中定义。 输出格式必须为 JSON： {"issue": true/false, "line": 12, "message": "硬编码密码 'abc123' 存在，应改用 os.getenv('DB_PASSWORD')", "suggestion": "替换为 os.getenv('DB_PASSWORD', 'default')"}

关键点解析：

• patterns定义静态检测入口，AST 模式精准，文本模式兜底；
• llm_prompt是真正的智能层，它告诉模型“你是谁”“看什么”“怎么判断”“怎么输出”；
• {{code_snippet}}是模板变量，会被实际代码片段替换；
• 强制 JSON 输出，便于后续解析和 CI 集成。

我们团队写了 12 条自定义规则，包括“Spring Boot Actuator 端点未鉴权”“React useEffect 依赖数组遗漏”“Go defer 语句中 panic 未处理”，全部经过 200+ 次真实 diff 验证，误报率 < 2%。

3.4 Git 集成实战：从 pre-commit 到 CI 的四层防护

open-code-review 的价值不在单次运行，而在嵌入整个研发流水线。我们实践出四层防护：

第一层：pre-commit（开发者本地）
作用：拦截明显低级错误。配置.husky/pre-commit：

#!/usr/bin/env sh set -e echo "🔍 Running open-code-review on staged files..." npx open-code-review --stage --severity high --exit-code 1 --format markdown > /tmp/ocr-report.md 2>&1 || { echo "❌ Code review failed. See report:" cat /tmp/ocr-report.md exit 1 }

效果：提交前 3 秒内给出报告，90% 的NullPointerException、ArrayIndexOutOfBoundsException在这里被消灭。

第二层：pre-push（推送前强化）
作用：检查跨文件影响。配置.husky/pre-push：

# 获取本次推送的所有 commit commits=$(git rev-list --reverse ${PREV_COMMIT}..${CUR_COMMIT}) for commit in $commits; do # 对每个 commit 的 diff 做 review git show --no-patch --format="%H %s" $commit | \ xargs -I {} sh -c 'git show {} --name-only | xargs open-code-review --files --severity medium' done

效果：发现“修改了 DAO 层，但没更新 Service 层调用”的耦合问题。

第三层：CI job（合并前最终防线）
作用：全量扫描，生成 SARIF 报告。GitHub Actions 示例：

- name: Run open-code-review run: | open-code-review --diff-base origin/main --format sarif > ocr-report.sarif # 上传到 GitHub Code Scanning gh codeql github upload-sarif --sarif=ocr-report.sarif --category="open-code-review"

效果：PR 页面自动显示 security alert，点击直达问题行。

第四层：post-merge（知识沉淀）
作用：把 review 结论转为文档。我们用脚本监听 merge 事件：

# 每次 merge 后，提取 review 中的 "suggestion" 字段，生成 CONVENTIONS.md open-code-review --diff-base HEAD~1 --json-output | \ jq -r '.issues[] | select(.suggestion != null) | "\(.file):\(.line) \(.suggestion)"' >> CONVENTIONS.md

效果：团队新成员入职，直接看CONVENTIONS.md就知道“我们怎么处理日期格式”“API 错误码怎么定义”。

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

4.1 一次完整的 review 流程拆解：从 git diff 到 Markdown 报告

以一个真实的 Java Spring Boot 变更为例，演示 open-code-review 如何工作：

Step 1：获取 AST-aware diff
开发者执行git add src/main/java/com/example/UserService.java，然后git diff --cached输出：

diff --git a/src/main/java/com/example/UserService.java b/src/main/java/com/example/UserService.java index abc123..def456 100644 --- a/src/main/java/com/example/UserService.java +++ b/src/main/java/com/example/UserService.java @@ -38,7 +38,7 @@ public class UserService { public User updateUser(Long id, UserUpdateRequest request) { User user = userRepository.findById(id).orElseThrow(); user.setName(request.getName()); - user.setEmail(request.getEmail()); + user.setEmail(request.getEmail().toLowerCase()); return userRepository.save(user); }

open-code-review 不直接处理这段文本，而是：

1. 用 tree-sitter-java 解析src/main/java/com/example/UserService.java的 AST；
2. 定位到updateUser方法体内的user.setEmail(...)节点；
3. 对比 base 版本和 current 版本的 AST，发现变更点是request.getEmail()被包裹了.toLowerCase()；
4. 向上追溯：request是UserUpdateRequest类型，UserUpdateRequest.getEmail()返回String；
5. 向下展开：user.setEmail()是User类的方法，签名void setEmail(String email)。

Step 2：构建 LLM 上下文
生成 prompt 时，注入以下结构化信息：

[CONTEXT] - 文件路径: src/main/java/com/example/UserService.java - 方法名: updateUser - 变更类型: method call argument transformation - 原表达式: request.getEmail() - 新表达式: request.getEmail().toLowerCase() - request 类型: UserUpdateRequest (fields: name:String, email:String) - user 类型: User (methods: setName, setEmail, etc.) - 项目框架: Spring Boot 3.2, Hibernate 6.3 - 已知约束: email 字段在数据库为 VARCHAR(255), 有唯一索引

Step 3：LLM 推理与结构化输出
模型收到 prompt 后，按预设 schema 输出 JSON：

{ "issue": true, "file": "src/main/java/com/example/UserService.java", "line": 41, "severity": "medium", "category": "data-consistency", "message": "email 转小写可能破坏唯一性约束。若数据库已存 'John@EXAMPLE.COM'，新请求 'john@example.com' 会因 toLowerCase() 变为相同值，导致唯一索引冲突。", "suggestion": "1. 在数据库层面使用 COLLATE utf8mb4_0900_as_cs 实现大小写敏感比较；2. 或在 service 层添加校验：if (userRepository.existsByEmailIgnoreCase(request.getEmail())) throw new EmailExistsException();", "references": ["https://dev.mysql.com/doc/refman/8.0/en/charset-binary-collations.html", "https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#jpa.query-methods.query-creation"] }

Step 4：生成可读报告
将 JSON 转为 Markdown：

### 🚨 Medium Severity Issue **File**: `src/main/java/com/example/UserService.java` **Line**: 41 **Category**: Data Consistency **Message**: email 转小写可能破坏唯一性约束。若数据库已存 'John@EXAMPLE.COM'，新请求 'john@example.com' 会因 toLowerCase() 变为相同值，导致唯一索引冲突。 **Suggestion**: 1. 在数据库层面使用 `COLLATE utf8mb4_0900_as_cs` 实现大小写敏感比较； 2. 或在 service 层添加校验：`if (userRepository.existsByEmailIgnoreCase(request.getEmail())) throw new EmailExistsException();` **References**: [MySQL Collation Docs](https://dev.mysql.com/doc/refman/8.0/en/charset-binary-collations.html), [Spring Data JPA Query Methods](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#jpa.query-methods.query-creation)

整个过程平均耗时 4.2 秒（M2 Max），比人工 review 一行代码快 10 倍，且结论可审计、可复现。

4.2 模型微调实战：用 LoRA 优化 CodeLlama 在特定领域表现

虽然 open-code-review 默认用通用 CodeLlama，但当我们接入金融风控系统时，发现模型对“反洗钱规则引擎”“实时授信评分”等术语理解偏差大。于是我们做了轻量微调：

数据准备：收集 327 个真实 code review 会话（含原始 diff + senior engineer 的人工 review comment），清洗后转为 Alpaca 格式：

{ "instruction": "Review this Java diff for AML compliance issues", "input": "diff --git a/risk-engine/src/main/java/com/bank/rule/RuleEngine.java b/risk-engine/src/main/java/com/bank/rule/RuleEngine.java\n@@ -120,3 +120,3 @@ public class RuleEngine {\n- if (transaction.getAmount() > 5000) {\n+ if (transaction.getAmount() > 5000 && transaction.getCountry().equals(\"CN\")) {", "output": "【高危】AML 规则阈值未区分国家。中国境内交易 5000 元触发，但跨境交易未设限，违反 FATF Recommendation 16。建议：增加 countryCode 参数，调用 central-bank-api 获取实时阈值。" }

微调命令：

# 使用 Unsloth（比 HuggingFace Trainer 快 2x） unsloth train \ --model_name_or_path codellama/CodeLlama-7b-Instruct \ --dataset ./aml-review-data.json \ --lora_r 64 \ --lora_alpha 128 \ --lora_dropout 0.1 \ --max_seq_length 2048 \ --output_dir ./lora-aml-7b

集成到 open-code-review：

ollama create aml-codellama -f Modelfile # Modelfile 内容： FROM codellama:7b-instruct ADAPTER ./lora-aml-7b/adapter_model.bin PARAMETER num_ctx 2048

然后配置model: aml-codellama。实测后，AML 相关 issue 识别准确率从 68% 提升到 92%，false positive 从 15% 降到 3%。

4.3 CI/CD 深度集成：与 GitHub Actions 和 GitLab CI 的无缝对接

open-code-review 的 CI 集成不是简单跑个命令，而是要融入现有 pipeline。以下是两个生产环境验证过的方案：

GitHub Actions 方案（推荐）：

name: Code Review on: pull_request: types: [opened, synchronize, reopened] branches: [main, develop] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # 必须，否则无法获取 base commit - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install open-code-review run: npm install -g open-code-review - name: Run open-code-review id: ocr run: | # 生成 SARIF 报告 open-code-review \ --diff-base ${{ github.event.pull_request.base.sha }} \ --format sarif \ --severity high \ --output ocr-report.sarif # 上传到 Code Scanning gh auth login --with-token <<< "${{ secrets.GITHUB_TOKEN }}" gh codeql github upload-sarif \ --sarif=ocr-report.sarif \ --category="open-code-review" \ --repo="${{ github.repository }}" \ --ref="${{ github.head_ref }}" env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Post PR Comment (if issues found) if: always() && steps.ocr.outcome == 'failure' uses: actions/github-script@v6 with: script: | const data = require('./ocr-report.sarif'); const issues = data.runs[0].results.filter(r => r.level === 'error'); if (issues.length > 0) { github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: `🔍 open-code-review found ${issues.length} high-severity issues:\n\n${issues.map(i => `- ${i.message}`).join('\n')}` }); }

GitLab CI 方案：

code-review: image: node:20-alpine before_script: - apk add --no-cache git - npm install -g open-code-review script: - open-code-review --diff-base $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME --format json > ocr-report.json - | if [ $(jq '.issues | length' ocr-report.json) -gt 0 ]; then echo "❌ Found $(jq '.issues | length' ocr-report.json) issues" jq -r '.issues[] | "• \(.file):\(.line) \(.message)"' ocr-report.json exit 1 else echo "✅ No issues found" fi allow_failure: false rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"

关键技巧：

• GitHub 必须fetch-depth: 0，否则--diff-base找不到 base commit；
• GitLab 用$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME而非$CI_COMMIT_REF_NAME，因为后者是 target branch；
• 所有 CI 环境必须预装 tree-sitter parser，可在before_script加open-code-review install-parser java。

4.4 性能调优：让 7B 模型在 4GB RAM 设备上稳定运行

很多团队想在 CI runner（如 AWS EC2 t3.micro，1vCPU/1GB RAM）上跑 open-code-review，但默认 Ollama 会 OOM。我们的调优方案：

内存控制：

# 启动 Ollama 时限制内存 OLLAMA_NUM_GPU=0 OLLAMA_MAX_LOADED_MODELS=1 OLLAMA_NO_CUDA=1 \ ollama serve --host 0.0.0.0:11434 --log-level error

• OLLAMA_NUM_GPU=0：强制 CPU 模式，避免 GPU 内存碎片；
• OLLAMA_MAX_LOADED_MODELS=1：同一时间只加载一个模型，防止多模型竞争；
• --log-level error：关闭 debug 日志，减少 I/O 开销。

模型量化：

# 下载 GGUF 量化版（Q4_K_M） curl -L https://huggingface.co/TheBloke/CodeLlama-7B-Instruct-GGUF/resolve/main/codellama-7b-instruct.Q4_K_M.gguf \ -o ~/.ollama/models/manifests/registry.ollama.ai/library/codellama/blobs/sha256-xxx

Q4_K_M 比 FP16 版本小 58%，推理速度提升 2.3 倍，内存占用从 5.2GB 降到 2.1GB。

批处理优化：
open-code-review 默认逐文件 review，但 CI 场景可批量：

# 一次性 review 所有变更文件，共享模型上下文 git diff --name-only origin/main | xargs open-code-review --files --batch

实测 12 个文件的 review 时间从 48 秒（串行）降到 19 秒（批处理），因为模型 warmup 只需一次。

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

5.1 典型问题速查表

5.2 我踩过的三个深坑及独家修复技巧

坑一：LLM 在长函数中漏检空指针
现象：一段 200 行的 Java 方法，LLM 只报告了 3 个 issue，但人工发现还有 2 处obj.toString()可能 NPE。
排查：用--debug看 LLM 输入，发现 prompt 被截断到 1024 token，obj的定义被砍掉了。
修复技巧：open-code-review 支持--context-lines 50参数，强制包含更多上下文行；更优解是启用--ast-context，它会自动提取obj的声明位置（哪怕在 50 行外），并注入到 prompt。我们团队在 config.yaml 里全局设ast_context: true。

坑二：TypeScript interface 变更未触发 review
现象：修改User.ts的interface User { name: string; }为interface User { name: string; email?: string; }，但 open-code-review 没报告任何问题。
原因：AST 解析器默认只关注function/class，忽略interface变更。
修复技巧：在.open-code-review.yaml的rules里加一条：

- name: "interface-change"