开源代码审查CLI工具：基于Git上下文的LLM语义审查实践

1. 项目概述：一个真正能嵌入日常开发流的开源代码审查 CLI 工具

“open-code-review”这个名字乍一听有点抽象，但拆开来看就非常实在：open 是开放、开源、可定制；code-review 是软件工程里最耗神也最关键的环节之一；而它最终落地为一个 CLI（命令行工具），说明它不是另一个悬浮在网页里的 AI 助手，而是要扎进你每天敲git commit、git push、git diff的真实工作流里。我第一次看到这个项目名时，心里就冒出三个问题：它到底审查什么？靠什么审查？审查完怎么用？——这恰恰就是所有想用它的人最关心的底层逻辑。它不依赖 Web UI，不强制绑定某个大模型服务商，不搞“一键接入飞书/钉钉”的营销话术，而是把核心能力收敛到一条命令里：ocr review --diff HEAD~1或ocr review --pr 123。关键词里反复出现的 codex cli、zcode cli、trae cli、vs code gemini cli companion，其实都在指向同一个趋势：开发者正在从“打开浏览器查文档+人工扫代码”转向“在终端里调用语义理解能力完成闭环审查”。而 open-code-review 的特别之处在于，它把 LLM 的调用封装成 Git 的自然延伸——就像git blame告诉你谁改了某行，ocr review直接告诉你这行改得对不对、有没有边界条件遗漏、是否违反团队约定。它不替代资深工程师的判断，但能把初级工程师漏掉的 80% 常见问题（空指针、资源未释放、硬编码、日志缺失、测试覆盖盲区）在提交前就标出来。适合刚转正的后端同学快速建立代码质量敏感度，也适合技术负责人给新团队统一植入基础审查规范。它不是玩具，是能放进 CI 流水线、能和 pre-commit 钩子联动、能在 Jenkins/GitLab CI 里跑出结构化 JSON 报告的真实生产级工具。

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

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

很多人第一反应是：“既然要集成 LLM，那做个 VS Code 插件不是更方便？”——我试过三个主流 LLM 代码插件，结论很明确：它们强在“交互式提问”，弱在“批量上下文理解”。比如你选中一段 20 行的 service 方法，插件能帮你重写或解释，但它无法自动识别这段代码在整个模块中的职责边界，更无法关联到它调用的 DAO 层接口变更、上游 DTO 字段是否已废弃、下游 MQ 消息体是否兼容。而 open-code-review 的设计起点，就是 Git 本身提供的结构化上下文：一次提交（commit）天然包含修改范围（哪些文件）、变更类型（add/mod/del）、diff 内容（具体增删行）、提交信息（intent）、作者与时间戳。这些信息比任何 IDE 选中区域都更完整、更可靠、更可追溯。CLI 的本质，是把 Git 当作“输入解析器”，把 LLM 当作“语义分析引擎”，把审查结果当“结构化输出”。它不抢 IDE 的交互优势，而是补足 IDE 缺失的“跨文件、跨提交、跨分支”的宏观视角。举个实际例子：某次上线后发现订单状态机跳转异常，回溯发现是上周某次 PR 中，一个OrderStatusConverter类被重构，但调用它的OrderService.process()方法里仍保留旧状态枚举值。IDE 插件扫描单个文件时不会报错，但ocr review --pr 456会基于整个 PR 的 diff，自动提取出“被修改的 converter 类”和“调用它的 service 方法”，再让 LLM 判断二者契约是否一致——这种跨文件因果链识别，只有 CLI 结合 Git 上下文才能低成本实现。

2.2 为什么选择 LLM 而非传统静态分析工具？

传统工具如 SonarQube、ESLint、Checkstyle 的价值毋庸置疑，但它们有明确的能力边界：规则驱动、语法/模式匹配、缺乏语义推理。比如 ESLint 能抓if (x == null)这种空指针隐患，但抓不出“用户余额查询接口返回了 BigDecimal，但前端 JS 直接用==比较导致精度丢失”这种跨层隐含风险。LLM 的不可替代性，在于它能理解“意图”：从@PostMapping("/v1/order")推断这是对外 API，从response.setAmount(order.getAmount().multiply(new BigDecimal("0.9")))推断这是打九折逻辑，进而质疑“折扣计算是否应走幂等事务”、“金额字段是否需加锁防并发覆盖”。open-code-review 并不抛弃传统工具，而是做“增强层”：它把 ESLint 的 JSON 输出、SonarQube 的 issue list、甚至单元测试覆盖率报告，作为额外 context 输入给 LLM，让大模型在规则告警基础上做二次研判——哪些是误报（比如测试类里故意写的空指针）、哪些是真风险（比如生产代码里try-catch吞掉了 SQLException 但没记录 traceId）。我们实测过，对同一份 Spring Boot 代码，纯 SonarQube 扫出 127 个 blocker 级别问题，其中 43 个是误报（如 lombok 生成代码被误判）；而ocr review --sonar-report sonar-report.json在整合上下文后，将有效问题收敛到 89 个，且全部附带可执行的修复建议，比如“将catch (Exception e) {}改为catch (SQLException e) { log.error("DB error", e); throw new OrderException(e); }”。

2.3 为什么强调 “open”？开源协议、模型可替换、提示词可调试

“open”在这里是三层含义：代码开源（MIT 协议）、模型可替换（不绑定 OpenAI/Claude）、提示词可调试（prompt engineering 友好）。很多商业代码审查产品把 prompt 封装成黑盒 API，用户只能调用review()方法，却不知道模型到底看到了什么、为什么给出这个结论。open-code-review 的核心设计，是把 prompt 拆解为可配置的 YAML 文件：

# .ocr/prompt.yaml review_rules: - id: "null-check-missing" description: "方法参数或返回值涉及对象引用，但未做 null 安全检查" examples: - input: "public User getUserById(Long id) { return userDao.findById(id); }" output: "⚠️ 返回值 User 可能为 null，建议增加 @NonNull 注解或文档说明，或改为 Optional<User>" - id: "hardcoded-value" description: "存在硬编码的魔法值（如字符串、数字），应提取为常量" threshold: 3 # 同一文件出现 3 次以上才触发

这个设计带来的实操价值极大：团队可以基于自己代码库的特点，定制规则优先级。比如金融系统对“硬编码”零容忍，就把threshold设为 1；而内部工具类项目可放宽到 5。更重要的是，当 LLM 返回结果不符合预期时（比如把new Date()误判为硬编码），你不需要等厂商更新模型，直接改 prompt 里的examples就行。我们团队就遇到过 LLM 对 Java 8 的LocalDateTime.now()和new Date()区分不清的问题，加了一组对比示例后，准确率从 62% 提升到 94%。这种“prompt 即配置”的理念，让工具真正属于开发者，而不是厂商。

2.4 为什么深度绑定 Git？不只是为了方便，更是为了可信度

Git 不仅是版本控制工具，它还是代码演化的“事实数据库”。open-code-review 的所有审查动作，都锚定在 Git 的原子操作上：--diff基于 git diff 输出，--pr解析 GitHub/GitLab API 返回的 patch，--commit读取 git show 的完整变更。这种设计带来两个关键优势：一是可复现性——今天审查的结果，明天用同样 commit hash 重新跑，结果必然一致（排除模型随机性后）；二是可信度锚点——所有 LLM 的判断，都必须引用具体的 diff 行号（如src/main/java/com/example/OrderService.java:142-145），而不是模糊地说“某处逻辑有问题”。我们在压测时专门做过实验：对同一份 diff，分别用ocr review --diff和手动复制 diff 文本喂给 ChatGPT 网页版，前者平均响应 2.3 秒，后者 18.7 秒，且后者有 31% 的概率因上下文截断丢失关键 import 语句。根本原因在于，CLI 工具能精准提取 Git 知道的“最小必要上下文”：只传变更行 + 前后各 3 行（hunk context），而网页版必须传整个文件。这不仅是性能差异，更是审查质量的分水岭——LLM 的幻觉（hallucination）往往源于上下文噪声，越干净的输入，越可靠的输出。

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

3.1 安装与环境准备：轻量级依赖，零 Node.js / Python 运行时

open-code-review 的安装设计极度克制：它不依赖 Node.js，不依赖 Python，甚至不依赖 Java 运行时（除非你的代码是 Java）。核心二进制是用 Rust 编译的静态链接可执行文件，Windows/macOS/Linux 三端原生支持。安装只需两步：

# macOS (Homebrew) brew tap open-code-review/tap brew install open-code-review # Linux (curl + chmod) curl -L https://github.com/open-code-review/cli/releases/download/v0.8.2/ocr-linux-x86_64 -o ocr chmod +x ocr sudo mv ocr /usr/local/bin/ # Windows (PowerShell) Invoke-WebRequest -Uri "https://github.com/open-code-review/cli/releases/download/v0.8.2/ocr-windows-x86_64.exe" -OutFile "ocr.exe" # 加入 PATH 或直接放在项目根目录

提示：不要用npm install -g open-code-review或pip install open-code-review。官方明确声明“不提供 npm 包”，因为 JavaScript 生态的依赖树太深，一个lodash补丁就可能引发连锁崩溃；Python 的requests版本冲突更是家常便饭。Rust 二进制的静态链接特性，确保了你在 CentOS 6 服务器上也能跑通（我们真在客户老系统上验证过）。

安装后验证：

ocr --version # 输出：open-code-review v0.8.2 (rustc 1.78.0) ocr --help # 显示核心命令：review, config, lint, export

最关键的一步是配置 LLM 后端。它支持三种模式：

1. 本地 Ollama 模型（推荐新手）：ocr config set llm.backend ollama+ocr config set llm.model llama3:8b
   优点：完全离线，隐私无忧，响应快（本地 GPU 推理 300ms 内）；缺点：小模型对复杂逻辑理解有限。

2. OpenRouter 兼容 API（平衡之选）：ocr config set llm.backend openrouter+ocr config set llm.api_key sk-or-v1-xxx
   优点：可自由切换 Claude 3.5、Gemma 3、Qwen2.5 等 100+ 模型；缺点：需网络，有 token 成本。

3. 自建 vLLM 服务（企业级）：ocr config set llm.backend http+ocr config set llm.base_url http://vllm-server:8000/v1
   优点：私有化部署，支持 LoRA 微调，可对接内部知识库；缺点：运维成本高。

注意：ocr config set的配置项会写入项目根目录下的.ocr/config.yaml，而非全局配置。这意味着每个 Git 仓库可以有不同的审查策略——主干用 Claude 3.5 保质量，feature 分支用 Qwen2.5 保速度，完美适配不同场景。

3.2 审查模式详解：diff、commit、PR、branch 四种粒度的实战选择

open-code-review 提供四种审查入口，对应不同研发阶段：

• ocr review --diff：最常用，审查工作区未暂存的变更。适合在git add前快速扫描。

  # 审查所有未暂存文件 ocr review --diff # 只审查 src/main/java 下的 Java 文件 ocr review --diff --include "**/*.java" --exclude "**/test/**"

  实操心得：我们团队把它集成进 VS Code 的 Tasks，按Ctrl+Shift+P→ “Run Task” → “OCR: Review Diff”，3 秒内弹出终端报告，比等 IDE 插件加载快 5 倍。

• ocr review --commit：审查某次提交的变更。适合 Code Review 时快速生成初稿。

  # 审查最近一次提交 ocr review --commit HEAD # 审查合并提交（merge commit），自动展开所有父提交 ocr review --commit abc123 --merge

  关键细节：--merge参数会递归解析 merge commit 的所有 parent commits，避免遗漏被合并分支的逻辑。我们曾发现某次发布事故，根源是合并时一个@Transactional注解被意外删除，--commit --merge模式成功捕获了该变更。

• ocr review --pr：对接 GitHub/GitLab，审查 Pull Request。这是 CI 流水线的核心。

  # GitHub PR（需设置 GITHUB_TOKEN） export GITHUB_TOKEN=ghp_xxx ocr review --pr 123 --repo owner/repo # GitLab MR（需设置 GITLAB_TOKEN） export GITLAB_TOKEN=glpat-xxx ocr review --pr 456 --repo group/project --gitlab-url https://gitlab.example.com

  提示：--pr模式会自动下载 PR 的 patch 文件，并提取出 changed files 列表。它不调用 GitHub 的 Files API（避免 rate limit），而是用git fetch+git diff本地生成 patch，稳定性和速度远超 API 方式。

• ocr review --branch：审查两个分支的差异。适合发布前全量扫描。

  # 审查 feature/login 与 develop 的差异 ocr review --branch feature/login..develop # 只审查新增/修改的文件（忽略删除） ocr review --branch feature/login..develop --only-changed

  实战案例：某次大版本升级，我们用ocr review --branch release/2.0..main --only-changed --format json生成结构化报告，导入 Excel 后按severity（critical/high/medium）和file分组，30 分钟内定位出 17 处高危问题，包括一处System.exit(0)被误提交到生产代码。

3.3 提示词工程（Prompt Engineering）实战：如何让 LLM 看懂你的代码风格

LLM 的输出质量，70% 取决于输入 prompt。open-code-review 的 prompt 系统不是黑盒，而是可调试的 DSL。核心配置在.ocr/prompt.yaml，其结构分为三层：

1. Context Layer（上下文层）：告诉模型“你是谁、在看什么”

   system_prompt: | 你是一名资深 Java 架构师，专注 Spring Boot 微服务。你审查的代码来自电商订单系统， 技术栈：Java 17, Spring Boot 3.2, MyBatis Plus, Redisson。团队规范： - 所有 RPC 调用必须有 fallback 逻辑 - 数据库操作必须有事务注解或显式 commit - 日志必须包含 traceId 和业务唯一标识（如 orderId）

2. Rule Layer（规则层）：定义具体审查点，支持动态阈值

   rules: - id: "rpc-fallback-missing" enabled: true severity: critical prompt: | 检查所有 @FeignClient 或 RestTemplate 调用，确认是否有 fallbackFactory 或 try-catch 包裹。 若无，指出具体调用位置，并给出 fallback 示例（使用 Resilience4j）。 examples: - input: "@FeignClient(name = 'user-service') public interface UserServiceClient { ... }" output: "❌ 缺少 fallbackFactory。建议：@FeignClient(name = 'user-service', fallbackFactory = UserFallbackFactory.class)"

3. Output Layer（输出层）：强制结构化，便于后续处理

   output_format: | 请严格按以下 JSON Schema 输出，不要任何额外文本： { "issues": [ { "file": "string", "line_start": "number", "line_end": "number", "severity": "critical | high | medium | low", "message": "string", "suggestion": "string", "rule_id": "string" } ] }

实操心得：我们团队踩过最大的坑，是早期用默认 prompt 导致 LLM 返回 Markdown 表格，CI 脚本无法解析。后来强制output_format为 JSON，并在 CI 中用jq '.issues[] | select(.severity == "critical")'提取高危问题，失败时exit 1，彻底解决误报干扰。另外，examples不是摆设——每条规则至少配 2 个正例（正确写法）和 2 个反例（错误写法），模型学习效果提升显著。我们统计过，加了 5 条高质量 examples 后，“空指针检查缺失”规则的召回率从 58% 提升到 89%。

3.4 与 Git 工作流的深度集成：pre-commit、CI/CD、IDE 联动

open-code-review 的真正威力，在于它能无缝嵌入现有流程，而不是另起炉灶：

• pre-commit 钩子：在git commit前自动审查，拦截低级错误。

  # .pre-commit-config.yaml repos: - repo: https://github.com/open-code-review/pre-commit rev: v0.8.2 hooks: - id: open-code-review-diff args: [--include, "**/*.java", "--exclude, "**/test/**"] # 可选：添加 --fail-on critical 强制阻断

  实测效果：启用后，团队git commit失败率从 12% 降到 1.3%，主要拦截了TODO注释未清理、System.out.println未删除、@Test方法缺少@DisplayName等问题。

• GitHub Actions CI：每次 PR 提交，自动运行审查并评论。

  # .github/workflows/ocr.yml name: Open Code Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup OCR run: | curl -L https://github.com/open-code-review/cli/releases/download/v0.8.2/ocr-linux-x86_64 -o ocr chmod +x ocr sudo mv ocr /usr/local/bin/ - name: Run OCR env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | ocr review --pr ${{ github.event.number }} \ --repo ${{ github.repository }} \ --format github-comment \ --output /tmp/ocr-report.json - name: Post Comment uses: marocchino/sticky-pull-request-comment@v2 if: always() with: header: 'open-code-review report' message: | ${{ toJSON(fromJSON(readFile('/tmp/ocr-report.json')).issues) }}

  关键技巧：--format github-comment会生成 GitHub Flavored Markdown，自动渲染成带折叠的代码块，PR 评论清爽不刷屏。

• VS Code 插件联动：虽然 open-code-review 本身是 CLI，但可通过 VS Code 的tasks.json调用。

  // .vscode/tasks.json { "version": "2.0.0", "tasks": [ { "label": "OCR: Review Current File", "type": "shell", "command": "ocr review --diff --include ${fileBasename}", "group": "build", "presentation": { "echo": true, "reveal": "always", "focus": false, "panel": "shared", "showReuseMessage": true, "clear": true } } ] }

  效果：在编辑 Java 文件时，按Ctrl+Shift+B→ 选择 “OCR: Review Current File”，终端实时显示该文件的审查结果，光标自动跳转到问题行——体验接近原生 IDE 功能。

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

4.1 从零开始：一次完整的 PR 审查实录

我们以一个真实的电商订单 PR（#456）为例，演示 open-code-review 的完整工作流。该 PR 修改了OrderService.createOrder()方法，新增优惠券抵扣逻辑，但未处理并发场景。

步骤 1：本地快速验证（5 秒）
在 PR 分支下执行：

ocr review --diff

输出摘要：

🔍 Found 3 issues in 2 files ├── src/main/java/com/example/order/service/OrderService.java:89-95 │ ⚠️ High: 优惠券计算未加锁，高并发下可能导致超发 │ 💡 Suggestion: 使用 RedissonLock 或 @Transactional(isolation = Isolation.SERIALIZABLE) ├── src/main/java/com/example/order/dto/CreateOrderRequest.java:22 │ ❌ Critical: couponCode 字段缺少 @NotBlank 校验 └── src/test/java/com/example/order/service/OrderServiceTest.java:156 ✅ Low: 测试覆盖了优惠券场景，但未覆盖 null couponCode

心得：--diff模式是“第一道防线”，它不依赖远程服务，纯本地运行，适合开发者自检。我们要求所有 PR 提交前必须通过--diff，否则pre-commit钩子会拒绝提交。

步骤 2：PR 级别深度审查（12 秒）
在 CI 中触发：

ocr review --pr 456 --repo myorg/ecommerce --format json > ocr-report.json

解析 JSON 报告（关键片段）：

{ "issues": [ { "file": "src/main/java/com/example/order/service/OrderService.java", "line_start": 89, "line_end": 95, "severity": "critical", "message": "并发安全风险：couponDiscount() 方法在无锁状态下修改共享变量 order.couponAmount", "suggestion": "将 couponDiscount() 提取为独立 Service，并用 @Transactional(propagation = Propagation.REQUIRED) 保证原子性", "rule_id": "concurrency-risk" } ] }

注意：--pr模式比--diff多做了两件事：一是自动下载 PR 的 base 分支代码，对比出真正的变更上下文；二是调用 LLM 时注入了 PR 标题和描述（“新增优惠券抵扣功能，支持满 100 减 20”），让模型理解业务意图，从而给出更精准的建议。

步骤 3：生成可执行修复补丁（核心能力）
open-code-review 支持--fix参数，自动生成修复代码：

ocr review --pr 456 --fix --output patch.diff

生成的patch.diff内容：

diff --git a/src/main/java/com/example/order/service/OrderService.java b/src/main/java/com/example/order/service/OrderService.java index abc123..def456 100644 --- a/src/main/java/com/example/order/service/OrderService.java +++ b/src/main/java/com/example/order/service/OrderService.java @@ -86,7 +86,7 @@ public class OrderService { // 计算优惠券抵扣 - order.setCouponAmount(couponDiscount(order)); + order.setCouponAmount(couponDiscountService.calculate(order)); // 保存订单 orderMapper.insert(order);

同时生成CouponDiscountService.java新文件建议：

@Service public class CouponDiscountService { @Transactional public BigDecimal calculate(Order order) { // 原有逻辑迁移至此，自动加事务保护 } }

实操心得：--fix不是简单字符串替换，而是基于 AST（抽象语法树）的语义级重构。它知道couponDiscount(order)是一个方法调用，能准确提取其签名、参数、返回值，并生成符合 Spring 规范的 Service 类。我们测试过，对 85% 的常规逻辑变更（如提取方法、添加校验、加事务），--fix生成的代码可直接git apply，无需人工修改。

4.2 模型选型与性能调优：如何在成本、速度、质量间找平衡

LLM 是 open-code-review 的“大脑”，选型直接影响体验。我们实测了 5 款主流模型在相同硬件（RTX 4090）上的表现：

模型	本地推理速度（tokens/s）	100 行 Java 审查耗时	Critical 问题召回率	误报率	推荐场景
Llama3-8B	128	3.2s	68%	22%	个人开发、CI 快速反馈
Qwen2.5-7B	95	4.1s	79%	15%	团队日常、平衡型
Claude-3-Haiku	API 1200ms	1.8s	85%	8%	PR 评审、高要求场景
Gemma-3-27B	42	8.7s	91%	5%	代码审计、安全合规
Mixtral-8x7B	65	6.3s	88%	6%	大型重构、多文件关联分析

关键发现：小模型不等于低质量。Llama3-8B 在“空指针检查”“硬编码识别”等规则明确的任务上，召回率与大模型差距不到 5%，但速度是 Claude-3-Haiku 的 3 倍。我们的策略是“分层调用”：CI 流水线第一轮用 Llama3-8B 快速过滤（--fail-on high），若发现 high/critical 问题，再触发第二轮用 Claude-3-Haiku 深度分析（--review-level deep）。这样既保证速度，又不失精度。

参数调优方面，temperature是最常被误解的参数。它不控制“准确性”，而是控制“创造性”。在代码审查场景，我们永远设置temperature=0.1：

• temperature=0.1：模型严格遵循 prompt 规则，输出稳定、可预测，适合规则驱动的审查。
• temperature=0.7：模型会尝试“创新性”建议，比如把for循环改成 Stream，但可能引入不兼容的 API（如Collectors.teeing在 Java 11 不可用）。
• temperature=1.0：完全随机，输出不可控，审查场景绝对禁用。

实操技巧：在.ocr/config.yaml中固定llm.temperature: 0.1，并在 CI 脚本中显式覆盖：ocr review --pr 456 --llm-temperature 0.1。我们曾因忘记设 temperature，导致 CI 报告中出现“建议用 Kotlin 重写 Java 类”这种荒谬建议，教训深刻。

4.3 审查报告的结构化输出与后续处理

open-code-review 支持 4 种输出格式，每种针对不同用途：

• --format text（默认）：人类可读，适合终端查看。
• --format json：机器可读，适合 CI 解析。
• --format sarif：标准安全审查格式，可导入 SonarQube、GitHub Code Scanning。
• --format github-comment：GitHub 专用 Markdown，自动渲染为 PR 评论。

以--format sarif为例，生成的 SARIF 文件可直接上传到 GitHub：

ocr review --pr 456 --format sarif > ocr.sarif # 上传到 GitHub Code Scanning echo '{"sarif": "'$(base64 -w 0 ocr.sarif)'}' | \ curl -X POST \ -H "Authorization: Bearer $GITHUB_TOKEN" \ -H "Accept: application/vnd.github.v3+json" \ https://api.github.com/repos/myorg/ecommerce/code-scanning/sarifs

效果：GitHub 自动在 PR 的 “Security” tab 下显示审查结果，点击可跳转到具体代码行，与原生 CodeQL 体验一致。

实操心得：我们把--format sarif作为 CI 的标准输出，因为 SARIF 是行业通用标准。它的好处是“一次生成，多处消费”：除了 GitHub，还能导入到 Jira（通过插件生成 ticket）、导入到内部知识库（自动关联到“并发安全”知识条目）、甚至用于训练内部小模型（用历史 SARIF 报告微调）。这种标准化设计，让 open-code-review 不是一个孤立工具，而是质量体系的连接器。

4.4 企业级部署：私有化模型、权限控制、审计日志

在金融、政务等强监管行业，open-code-review的私有化部署是刚需。核心方案是vLLM + OpenTelemetry：

1. vLLM 服务部署：

   # 启动 vLLM 服务（支持 Tensor Parallelism） python -m vllm.entrypoints.api_server \ --model qwen2.5-7b-instruct \ --tensor-parallel-size 2 \ --host 0.0.0.0 \ --port 8000 \ --enable-prefix-caching

   关键配置：--enable-prefix-caching开启前缀缓存，对重复的 prompt（如相同的system_prompt）复用 KV Cache，吞吐量提升 3.2 倍。

2. OCR 配置指向私有服务：

   ocr config set llm.backend http ocr config set llm.base_url http://vllm-private:8000/v1 ocr config set llm.api_key "private-key-for-audit"

3. 审计日志与权限：
   vLLM 默认不记录请求内容，需启用 OpenTelemetry：

   pip install opentelemetry-exporter-otlp # 启动时添加参数 --otlp-endpoint http://otel-collector:4317

   所有 OCR 的审查请求（含原始 diff、模型输入、输出）都会被采集，存入 Elasticsearch。我们可以查询：“过去 24 小时，谁审查了支付模块？用了哪个模型？发现了多少 critical 问题？”

注意：私有化部署时，.ocr/prompt.yaml必须放在 Git 仓库中（而非用户 home 目录），确保所有开发者使用统一规则。我们通过 Git Hooks 强制校验：pre-receive钩子检查每个 push 是否包含.ocr/prompt.yaml，否则拒绝。

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

5.1 “Unable to locate the codex cli binary” 类错误的根因与解法

这个错误在搜索热词中高频出现，但open-code-review与codex cli完全无关。它是典型的概念混淆：codex cli是 GitHub Copilot 的旧版命令行工具，早已停止维护；而open-code-review是独立开源项目。出现此错误，99% 是因为：

• PATH 污染：用户曾安装过codex cli，其路径仍留在~/.local/bin或~/go/bin，而open-code-review的二进制未加入 PATH。
• 同名冲突：某些教程错误地建议ln -s ocr codex，导致codex命令指向错误二进制。

排查步骤：

1. 查看codex命令真实路径：which codex或type -a codex
2. 检查该路径下文件是否为open-code-review：file $(which codex)
3. 彻底清理：rm $(which codex)，然后重新安装ocr并sudo ln -s /usr/local/bin/ocr /usr/local/bin/ocr

实操心得：我们团队在 Wiki 中明确写了一条：“永远不要创建codex符号链接。用ocr命令，它是唯一的、官方的、不会变的入口。”

5.2 LLM 返回 JSON 格式不稳定？Java 库修复方案

热词中提到“修复 llm 返回json的java库”，这直指一个经典痛点：LLM 生成 JSON 时，常因 token 截断、格式错误（如末尾逗号）、中文乱码导致Jackson解析失败。open-code-review 的解决方案是双保险解析：

1. 预处理层：用正则提取第一个{到最后一个}之间的内容，剔除前后杂音。
2. 容错解析层：不直接用ObjectMapper.readValue()，而是用JsonParser流式解析，