Open Code Review：CLI+LLM Agent+Git Diff 的现代代码评审范式

1. 什么是 open-code-review：一个被严重误解的开源协作新范式

“open-code-review”这个词最近在开发者社区里频繁刷屏，但很多人一搜，发现既没有官方文档，也没有成熟项目仓库，更没有统一的安装命令——它不像git或docker那样是个具体工具，而是一套正在快速成型的协作理念+技术栈组合+CLI工作流。我从去年底开始系统性地在三个中型团队（20–40人规模）落地这套模式，不是用某个“开箱即用”的SaaS平台，而是用开源组件自己搭了一套轻量级流水线。它核心解决的，不是“代码要不要审”，而是“谁来审、怎么审、审完怎么闭环”这三个长期被流程掩盖的真实痛点。

你可能已经用过 GitHub PR Review、GitLab MR Comment，甚至接入过 SonarQube 或 CodeClimate 的静态扫描。但这些工具的问题在于：它们把 code review 当成一个“收尾动作”，一个需要人点开 diff、逐行打勾、写几句“LGTM”的仪式性环节。而 open-code-review 的本质，是把 code review前移、拆解、自动化、可追溯、可参与——它不替代人工判断，而是让人工判断发生在更合适的时间、由更合适的人、基于更充分的信息做出。比如，当一个 junior 开发者提交了涉及支付回调逻辑的修改，系统不会等 senior 花 20 分钟手动 review，而是自动触发 LLM Agent 基于团队内部《支付安全规范 v3.2》做合规初筛，同时把 diff 中与“幂等校验”相关的 3 行代码高亮推送给负责该模块的两位同事，并附上历史类似 PR 的修复记录链接。这才是 open 的真意：开放的是上下文、开放的是决策依据、开放的是参与入口，而不是开放源码本身。

关键词 “open-code-review” 在搜索中常和 “LLM Agent”、“CLI”、“git diffs” 绑定出现，这绝非偶然。它背后是一条清晰的技术演进路径：从纯人工 → 工具辅助（IDE 插件/CI 检查）→ 模型增强（LLM 理解语义）→ Agent 协同（多角色自动分发+反馈聚合）。而 CLI 是这条路径的“控制中枢”——所有操作都始于一条命令，比如ocr review --pr=123 --focus=security，它背后串联的是 git diff 解析、embedding 向量检索、LLM prompt 编排、飞书消息推送、Jira issue 关联等一整套动作。这不是炫技，而是把原本散落在 5 个不同界面里的操作，压缩进一次终端输入。我见过太多团队，reviewer 要切到 GitHub 看 diff，再切到 Confluence 查规范，再切到 Slack 问同事，最后回到 PR 写评论——这个过程平均耗时 11 分钟。而用 open-code-review CLI，同样任务压缩到 92 秒，且所有中间产物（检索到的规范条款、调用的 LLM 提示模板、生成的建议草稿）全部可审计、可复现。

它适合三类人：第一类是技术负责人，想降低关键模块的漏审率，又不想靠增加 review 人力；第二类是资深工程师，厌倦了重复回答“这个参数为什么不能设为 null”，希望把经验沉淀为可复用的检查规则；第三类是刚转正的 junior，需要明确知道“我的这段代码，到底哪里不符合团队标准”。它不承诺“零 bug”，但能确保每次提交都经过至少三层过滤：语法层（pre-commit hook）、语义层（LLM Agent 基于知识库推理）、领域层（指定 reviewer 的人工确认）。这三层不是线性串行，而是并行触发、异步反馈、结果聚合——这才是现代工程团队真正需要的 review 节奏。

2. 核心设计思路：为什么必须是 CLI + LLM Agent + Git Diff 的三角组合

2.1 CLI 不是“复古”，而是确定性与可编排性的唯一出口

很多人看到 “CLI” 第一反应是“过时”，觉得 GUI 或 Web UI 才是未来。但在我落地的 7 个项目中，所有失败案例都有一个共性：试图用浏览器插件或独立桌面应用作为入口。问题出在哪儿？不是功能弱，而是状态不可控、行为不可复现、集成不可扩展。举个真实例子：某团队用 Chrome 插件做 PR 自动摘要，结果发现同一个 PR，不同 reviewer 点击插件按钮后生成的摘要完全不同——因为插件依赖当前页面 DOM 结构，而 GitHub 页面会动态加载、懒渲染，导致 LLM 输入的 HTML 片段每次都不一样。更麻烦的是，当需要把 review 结果同步到 Jira 时，插件没有标准 API，只能靠模拟点击，一升级 GitHub 前端就全崩。

CLI 则完全不同。ocr review --pr=123这条命令，无论你在 macOS、Linux 还是 WSL 下执行，只要环境变量和配置文件一致，输出就是完全确定的。它天然支持管道（pipe）、重定向（>）、脚本化（bash for 循环批量处理）、CI 集成（直接写进.gitlab-ci.yml）。更重要的是，CLI 是唯一能无缝衔接 git diff 的载体。Git diff 本身是纯文本、结构化、增量式的——它告诉你“哪几行变了”，而不是“整个文件长什么样”。LLM 处理大文件效率低、成本高，但处理 20 行 diff 片段却极快。CLI 可以精准提取 diff、过滤掉无关变更（如格式调整、日志语句）、按函数/模块切片，再把每一片喂给 LLM Agent。这种“精准投喂”带来的效果提升，远超模型参数量的增加。我实测过：对同一段支付逻辑修改，用完整文件喂给 7B 模型，准确率 68%；用 git diff 提取的 12 行核心变更喂给同模型，准确率跃升至 91%。这不是玄学，是信息密度的胜利。

2.2 LLM Agent 不是“ChatGPT 替代品”，而是领域知识的调度器

网络热词里总在争论 “Agent 和 LLM 有什么区别”、“DeepSeek 属于哪个”。这里必须划清界限：LLM（大语言模型）是能力基座，比如 Qwen2-7B、DeepSeek-Coder-33B，它擅长理解通用语言、生成文本；而 Agent 是工作流引擎，它决定“什么时候调用哪个 LLM、用什么提示词、输入什么上下文、如何处理输出”。举个例子：当ocr review命令检测到 diff 中包含crypto/aes包调用，Agent 就会自动切换到预设的“加密安全检查”工作流——它会从向量数据库中检索团队《密码学使用规范》，把规范条款和当前 diff 片段一起组装成 prompt，再调用专门微调过的 security-llm（而非通用 chat 模型），最后把输出中的“风险等级：高”、“依据条款：3.2.1”、“修复建议：改用 AES-GCM 模式”结构化提取出来。整个过程，用户只看到一条命令和一份带链接的报告。

为什么不能只用一个通用 LLM？因为通用模型缺乏领域纵深。它知道“AES 应该用 GCM 模式”，但不知道你们团队规定“所有对外接口的 AES 加密必须配合 HMAC-SHA256 双校验”，更不知道去年 Q3 因为没加 HMAC 导致的线上事故编号是 SEC-2023-087。这些信息，必须通过 Agent 的知识检索（RAG）、规则引擎（if-else workflow）、工具调用（curl 调 Jira API）来补全。DeepSeek-Coder 是优秀的基座模型，但它不是 Agent；Codex CLI 是早期探索，但它把 LLM 当成黑盒聊天机器人用，没构建 Agent 层。真正的 open-code-review，核心价值不在模型本身，而在 Agent 如何把模型、知识、工具、人，编织成一张响应式网络。

2.3 Git Diff 是唯一可信的“变更事实源”，其他都是衍生品

所有 code review 工具都声称“基于代码”，但多数实际基于“文件快照”或“PR 页面渲染”。这带来两个致命缺陷：一是无法感知意图，比如user.Name = "default"和user.Name = config.DefaultName()在文件快照里都是赋值，但后者可能引入 NPE 风险；二是丢失上下文，比如一个修复 bug 的 commit，其 diff 可能只显示一行if (x > 0) {...}，但原始 issue 描述里明确写了“x 可能为 null”。open-code-review 的设计哲学是：git diff 是唯一不可篡改的变更记录，一切分析必须从此出发。我们用git show --unified=0 <commit>获取最小化 diff（只显示变化行，无上下文行），再用自定义 parser 提取变更类型（新增函数？修改条件分支？删除异常捕获？），最后结合 git blame 获取该行代码的 last author 和 last commit message——这三者组合，构成了比任何 IDE 插件都更可靠的“变更画像”。

这个设计直接解决了最头疼的“误报”问题。传统静态扫描工具看到log.info("user: " + user)就报“字符串拼接”，但 open-code-review Agent 会先查 git blame：如果这行代码三年没变，而本次 diff 只是修改了 user 对象的某个字段，那风险等级立刻降为低；反之，如果这行是本次新增，且 commit message 写着“修复登录态泄露”，那就会触发高危规则。这种基于变更源头的动态评估，让 review 准确率提升 40%，而噪音减少 75%。它不追求“100% 覆盖”，而是追求“100% 精准”。你不需要审查每一行，只需要确保每一次有意义的变更都被恰当审视。

3. 实操细节：从零搭建一个可用的 open-code-review 环境

3.1 环境准备与核心组件选型逻辑

搭建 open-code-review 不是装一个包就完事，它是一个“乐高式”组合。我推荐从最小可行集（MVP）开始：CLI 框架 + Git Diff 解析器 + LLM 推理服务 + 向量知识库。这四块缺一不可，但选型必须遵循“可替换、可降级、可监控”原则。下面是我的实测推荐清单，附带选型理由：

提示：不要一开始就追求“最强模型”。Qwen2-7B 在代码理解任务上，综合得分已超过 Llama3-8B，且显存占用低 35%。我们用它微调了 200 条团队历史 review 记录（格式：[diff snippet] -> [review comment]），仅需 1 小时 GPU 时间，准确率就从 72% 提升到 89%。这比换 33B 模型更划算。

安装步骤（以 macOS/Linux 为例，Windows 用户请用 WSL）：

# 1. 创建独立虚拟环境（强烈建议，避免包冲突） python3 -m venv ~/venv-ocr source ~/venv-ocr/bin/activate # 2. 安装核心依赖（注意：llama.cpp 需要先编译） pip install click chromadb numpy pydantic # 3. 下载并编译 llama.cpp（官方 repo，非第三方包） git clone https://github.com/ggerganov/llama.cpp cd llama.cpp && make clean && make -j$(nproc) && cd .. # 4. 下载量化模型（Q4_K_M 量化，平衡速度与精度） mkdir -p ~/.ocr/models wget https://huggingface.co/Qwen/Qwen2-7B-Instruct-GGUF/resolve/main/qwen2-7b-instruct-q4_k_m.gguf \ -O ~/.ocr/models/qwen2-7b-instruct-q4_k_m.gguf # 5. 初始化 CLI 命令（创建主入口） echo '#!/usr/bin/env python3 import click @click.group() def ocr(): """Open Code Review CLI""" @ocr.command() @click.option("--pr", "-p", type=int, help="PR number") def review(pr): click.echo(f"Reviewing PR #{pr}...") if __name__ == "__main__": ocr()' > ~/venv-ocr/bin/ocr chmod +x ~/venv-ocr/bin/ocr

此时运行ocr --help应显示基础命令。这 5 步耗时约 8 分钟，但构建了完全可控的底层骨架。所有后续功能，都基于这个 CLI 扩展，而非替换它。

3.2 Git Diff 解析器的核心实现与意图识别

Diff 解析器是 open-code-review 的“眼睛”，它决定 LLM 看到什么。通用 diff 工具（如git diff --unified=0）输出的是类似这样的文本：

diff --git a/src/payment/service.go b/src/payment/service.go index abc123..def456 100644 --- a/src/payment/service.go +++ b/src/payment/service.go @@ -45,3 +45,4 @@ func ProcessPayment(req PaymentRequest) error { - if req.Amount <= 0 { + if req.Amount <= 0 || req.Currency == "" { return errors.New("invalid amount or currency") }

但这对 LLM 来说信息过载。我们的diff-parser会把它提炼成结构化 JSON：

{ "file": "src/payment/service.go", "function": "ProcessPayment", "change_type": "modify_condition", "old_condition": "req.Amount <= 0", "new_condition": "req.Amount <= 0 || req.Currency == \"\"", "added_terms": ["req.Currency == \"\""], "git_blame": { "author": "zhangsan@company.com", "commit_hash": "a1b2c3d", "commit_message": "fix: add currency validation for payment" } }

这个转换的关键，在于识别变更的编程语义，而非字符串差异。我们用 ANTLR4 为 Go 语言编写了轻量级 parser（仅解析 if/for/func 定义），它能准确捕获||是新增的逻辑运算符，req.Currency == ""是新增的原子表达式。有了这个，LLM Agent 就能精准提问：“根据团队《支付规范》第 4.1 条‘所有支付请求必须校验货币代码’，本次新增的req.Currency == ""是否符合要求？请给出依据和风险等级。”

注意：不要试图用正则匹配所有语言。我们只支持团队主力语言（Go/Java/Python），每种语言的 parser 不超过 300 行。强行支持 10 种语言，只会让解析器变成不可维护的怪物。聚焦，比全面更重要。

3.3 LLM Agent 工作流编排与提示工程实战

Agent 的核心是 workflow 文件，我们用 YAML 定义（~/.ocr/workflows/security.yaml）：

name: "payment-security-check" trigger: - file_pattern: ".*payment.*" - change_type: "modify_condition" steps: - name: "retrieve-spec" action: "chroma_query" params: collection: "payment-specs" query: "currency validation requirement" top_k: 3 - name: "generate-prompt" action: "template_render" params: template: | 你是一名资深支付安全专家。请严格依据以下规范条款评审代码变更： {% for spec in specs %}{{ spec.content }}{% endfor %} 本次变更： 文件：{{ diff.file }} 函数：{{ diff.function }} 原条件：{{ diff.old_condition }} 新条件：{{ diff.new_condition }} 新增项：{{ diff.added_terms | join(', ') }} 请按以下格式输出： RISK_LEVEL: [HIGH/MEDIUM/LOW] REASON: [不超过 50 字] REFERENCE: [规范条款编号，如 PAY-4.1] SUGGESTION: [具体修复建议] - name: "call-llm" action: "llama_cpp_inference" params: model_path: "~/.ocr/models/qwen2-7b-instruct-q4_k_m.gguf" temperature: 0.1 max_tokens: 256 - name: "parse-output" action: "regex_extract" params: pattern: "RISK_LEVEL: ([A-Z]+)\nREASON: (.+)\nREFERENCE: ([^\n]+)\nSUGGESTION: (.+)"

这个 workflow 的威力在于可测试、可调试、可版本化。你可以用ocr debug --workflow=security --diff-file=test.diff命令，传入一个测试 diff 文件，实时查看每一步的输入输出。当 LLM 输出格式错乱时（常见！），regex_extract步骤会失败，Agent 自动 fallback 到人工 review 模式，并记录错误日志——这比让整个流程静默失败强百倍。

实操心得：提示词（prompt）不是写一次就完事。我们建立了prompt-benchmark机制：每月用 50 条历史 high-risk diff 测试新 prompt，计算RISK_LEVEL准确率和REFERENCE引用正确率。发现一个关键技巧：在 prompt 末尾加上Output ONLY in the specified format. No extra text, no explanations.，能将格式错误率从 23% 降到 4%。LLM 不是人，它需要明确的边界约束。

3.4 向量知识库构建与团队规范注入

知识库不是把 Confluence 文档 PDF 丢进去就行。我们采用“规范条款原子化”策略：每一条可执行的规范，单独存为一条向量记录。例如《支付安全规范》第 4.1 条：

【PAY-4.1】所有对外支付接口的请求体，必须包含 currency 字段，且值不能为空字符串。 验证方式：检查 request struct 的 Currency 字段是否为非空 string 类型。 违规示例：type PaymentReq struct { Amount int } // 缺失 Currency

这条被存为一条记录，embedding 向量由all-MiniLM-L6-v2模型生成。当 Agent 查询时，返回的不只是文本，还有score: 0.92的相关度——这让我们能设置阈值（如score > 0.85才采纳），避免低相关度的噪声干扰。

构建脚本ingest-specs.py只有 80 行，核心逻辑：

import chromadb from sentence_transformers import SentenceTransformer client = chromadb.PersistentClient(path="~/.ocr/chroma") collection = client.get_or_create_collection("payment-specs") model = SentenceTransformer('all-MiniLM-L6-v2') # 从 Markdown 文件解析条款（用正则提取 【CODE】开头的段落） with open("payment-spec.md") as f: specs = re.findall(r'【([A-Z\-0-9]+)】(.*?)(?=【|$)', f.read(), re.DOTALL) for code, content in specs: embedding = model.encode(content.strip()).tolist() collection.add( ids=[code], embeddings=[embedding], documents=[content.strip()], metadatas=[{"section": code}] )

实操心得：知识库更新必须和代码发布同步。我们在 CI 流水线中加入ocr ingest-specs步骤，当specs/目录下的 Markdown 文件有变更时，自动触发知识库更新。这样，新规范上线 5 分钟内，所有 review 就能生效。别让知识库成为“历史文档库”。

4. 完整实操流程：一次真实的 open-code-review 从触发到闭环

4.1 触发：从 Git Commit 到 CLI 命令的全链路

整个流程始于一次普通的git push。但我们的 pre-push hook 做了两件事：

1. 自动检测本次提交是否关联 Jira issue（通过 commit message 中的PROJ-123格式）
2. 如果关联，且 issue type 为Bug或Security，则静默执行ocr review --commit=$GIT_COMMIT --auto

这个 hook 的代码（.git/hooks/pre-push）：

#!/bin/bash # 获取最后一次 commit 的 message MSG=$(git log -1 --pretty=%B HEAD) ISSUE=$(echo "$MSG" | grep -oE '[A-Z]{2,}-[0-9]+' | head -1) if [[ -n "$ISSUE" ]]; then # 检查 issue 类型（调用 Jira API） TYPE=$(curl -s -u "$JIRA_USER:$JIRA_TOKEN" \ "https://jira.example.com/rest/api/3/issue/$ISSUE" | \ jq -r '.fields.issuetype.name') if [[ "$TYPE" == "Bug" || "$TYPE" == "Security" ]]; then # 后台触发 review，不阻塞 push nohup ~/.ocr/bin/ocr review --commit=$GIT_COMMIT --auto > /dev/null 2>&1 & fi fi

这个设计解决了“review 总是滞后”的顽疾。传统流程是：push → 创建 PR → 等 reviewer 有空 → 2 小时后才开始 review。而 open-code-review 在代码离开开发者机器的瞬间，就已经启动分析。即使 reviewer 暂时离线，LLM Agent 的初筛报告、知识库检索结果、风险等级判定，都已经生成并存入本地缓存。当 reviewer 打开终端输入ocr status --pr=123，看到的不是“等待中”，而是“LLM 初筛完成（HIGH），安全规范 PAY-4.1 已匹配，建议立即介入”。

4.2 分析：LLM Agent 如何协同工作并生成可操作报告

以 PR #123 为例，ocr review --pr=123的执行过程如下：

Step 1: Diff 提取与切片
CLI 调用git diff origin/main...HEAD --unified=0，得到原始 diff。diff-parser将其切分为 3 个逻辑单元：

• Unit A:src/payment/service.go中ProcessPayment函数的条件修改（新增 currency 校验）
• Unit B:src/payment/model.go中PaymentRequeststruct 新增Currency string字段
• Unit C:test/payment_test.go中新增 2 个 currency 相关测试用例

Step 2: 并行工作流触发
Agent 根据每个单元的file_pattern和change_type，并行触发 3 个 workflow：

• Unit A →security.yaml（支付安全检查）
• Unit B →api-design.yaml（API 设计规范检查）
• Unit C →test-coverage.yaml（测试覆盖检查）

Step 3: 结果聚合与优先级排序
3 个 workflow 同时返回结构化结果：

// security.yaml result { "risk_level": "HIGH", "reason": "新增 currency 校验未覆盖空格场景", "reference": "PAY-4.1", "suggestion": "改为 strings.TrimSpace(req.Currency) != \"\"" } // api-design.yaml result { "risk_level": "MEDIUM", "reason": "Currency 字段未标注 json tag", "reference": "API-2.3", "suggestion": "添加 `json:\"currency\"` tag" } // test-coverage.yaml result { "risk_level": "LOW", "reason": "新增测试覆盖了 currency 为空场景，但未覆盖 currency 为全空格场景", "reference": "TEST-1.5", "suggestion": "增加 test case: Currency: \" \"" }

Agent 将这三条结果按risk_level排序（HIGH > MEDIUM > LOW），并合并为一份报告：

🔍 OPEN-CODE-REVIEW REPORT FOR PR #123 ==================================== [HIGH] Payment Security Issue (PAY-4.1) - File: src/payment/service.go - Change: Added `req.Currency == ""` to condition - Problem: Does not handle whitespace-only currency (e.g., " ") - Fix: Use `strings.TrimSpace(req.Currency) != ""` - Reference: https://confluence.company.com/pay-spec#PAY-4.1 [MEDIUM] API Design Issue (API-2.3) - File: src/payment/model.go - Change: Added Currency field to PaymentRequest - Problem: Missing JSON tag for serialization - Fix: Add `json:"currency"` to the field - Reference: https://confluence.company.com/api-spec#API-2.3 [LOW] Test Coverage Gap (TEST-1.5) - File: test/payment_test.go - Change: Added 2 new test cases - Problem: Missing test for whitespace-only currency - Fix: Add test with Currency = " " - Reference: https://confluence.company.com/test-spec#TEST-1.5

Step 4: 人机协同介入
这份报告不是终点，而是协作起点。CLI 提供ocr approve --pr=123 --comment="Addressed HIGH and MEDIUM items"命令，它会：

• 自动在 GitHub PR 的对应行添加 comment（引用 PAY-4.1 条款）
• 更新 Jira issue 的 status 为In Review
• 发送飞书消息给 PR author：“你的 PR #123 已通过 LLM 初筛，HIGH/MEDIUM 项已标注，请确认修复后 @reviewer”

整个过程，从命令输入到报告生成，平均耗时 4.2 秒（M2 Max 机器）。而人工 review 同样的内容，平均耗时 18 分钟。

4.3 闭环：如何让 review 结果真正驱动开发行为

最危险的 review，是“评完了，但没人改”。open-code-review 的闭环设计，核心是把 review 结果变成不可绕过的开发门禁。我们在 CI 中加入了ocr gate步骤：

# .gitlab-ci.yml review-gate: stage: validate script: - ocr gate --pr=$CI_MERGE_REQUEST_IID allow_failure: false rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"

ocr gate命令做了三件事：

1. 检查 PR 中所有 HIGH 风险项是否已被标记为resolved（通过 GitHub API 查询 comment 中是否有✅ RESOLVED）
2. 检查 MEDIUM 项是否已有acknowledgedcomment（开发者回复“收到，下个迭代优化”也算通过）
3. 检查 LOW 项是否被waived（技术负责人用ocr waive --pr=123 --rule=TEST-1.5 --reason="low impact"显式豁免）

只有三项全部满足，CI 才通过。否则，Pipeline 直接失败，并在失败日志中清晰列出：

❌ GATE FAILED: PR #123 - [HIGH] PAY-4.1: 'req.Currency == ""' not fixed. See comment #45. - [MEDIUM] API-2.3: JSON tag missing. No acknowledgement found.

这个设计彻底改变了团队行为。以前，HIGH 风险项可能被忽略，因为“反正只是建议”。现在，它和go build失败一样，是硬性阻断。我们统计了实施 3 个月后的数据：HIGH 风险项的 100% 修复率，MEDIUM 项的 92% 主动响应率，LOW 项的 78% 自动豁免率（由 AI 根据历史豁免记录学习判断）。review 不再是“可选项”，而是开发流程中和git commit一样自然的动作。

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

5.1 LLM 输出不稳定？试试这 3 个硬核技巧

LLM 在 code review 场景下最常见的问题是“幻觉”（hallucination）——编造不存在的规范条款，或给出错误的修复建议。这不是模型问题，而是提示工程和后处理问题。我踩过的坑和解决方案：

问题 1：LLM 自由发挥，输出格式混乱
现象：ocr review命令有时返回正常 JSON，有时返回大段解释文字，导致regex_extract步骤失败。
根源：温度（temperature）参数过高，或 prompt 末尾缺少强约束。
解决：

• 将temperature从默认 0.8 降至 0.1（在 workflow YAML 中显式设置）
• 在 prompt 末尾添加三重强调：Output ONLY in the exact format below. NO EXPLANATIONS. NO EXTRA TEXT. NO MARKDOWN.
• 增加post-process步骤：用jsonschema验证输出，失败则重试（最多 2 次），仍失败则 fallback 到人工 review 模式

问题 2：知识库检索召回率低
现象：明明规范文档里有 PAY-4.1 条款，但chroma_query返回空结果或低分结果。
根源：embedding 模型对技术术语不敏感，或查询语句太泛。
解决：

• 不用自然语言查询，改用结构化关键词：ocr在调用chroma_query前，会先用正则从 diff 中提取技术实体（如req.Currency,strings.TrimSpace），再用这些实体构造查询"currency validation" AND "strings.TrimSpace"
• 对规范条款做双 embedding：一条用all-MiniLM-L6-v2（语义），一条用BM25（关键词），然后加权融合结果
• 设置k=5但只取score > 0.75的结果，宁缺毋滥

问题 3：Agent 工作流卡死在某一步
现象：ocr review命令长时间无响应，ps aux | grep llama显示进程在运行但无输出。
根源：LLM 推理时遇到超长上下文或特殊字符，导致 tokenization 错误。
解决：

• 在llama_cpp_inference步骤前，加入context-truncator：自动截断 prompt，保留最后 2000 tokens，优先保留规范条款和 diff 片段，舍弃通用说明
• 对 diff 片段做安全清洗：移除可能触发 tokenizer bug 的 Unicode 字符（如零宽空格、组合字符），用unicodedata.normalize('NFKD', text)预处理
• 设置timeout=30s，超时则终止并记录错误日志，避免阻塞整个 CLI

5.2 CLI 命令不生效？检查这 5 个隐藏陷阱

CLI 是 open-code-review 的心脏，但也是最容易出问题的环节。以下是我在 12 个团队部署中，遇到频率最高的 5 个“看似简单、实则致命”的问题：

陷阱 1：PATH 环境变量未更新
现象：ocr --help报错command not found，但~/venv-ocr/bin/ocr --help正常。
原因：~/venv-ocr/bin/ocr脚本创建后，shell 的 PATH 没有包含该路径。
解决：在~/.zshrc或~/.bash_profile中添加export PATH="$HOME/venv-ocr/bin:$PATH"，然后source ~/.zshrc。别忘了重启终端或新开 tab。

陷阱 2：Git diff 解析器权限不足
现象：ocr review --pr=123报错Permission denied: /tmp/ocr-diff-xxx。
原因：diff-parser默认在/tmp创建临时文件，但某些企业 Mac 禁用了/tmp写入。
解决：在~/.ocr/config.yaml中指定temp_dir: "$HOME/.ocr/tmp"，并在 CLI 启动时读取该配置。

陷阱 3：LLM 模型路径错误
现象：ocr review报错llama.cpp: cannot load model from /path/to/model.gguf。
原因：wget下载时网络中断，文件不完整；或路径中包含空格/中文，llama.cpp无法解析