1. 这不是又一个“AI代码审查”玩具：open-code-review 的真实定位与设计哲学
open-code-review 这个名字乍看平平无奇，甚至有点“开源即正义”的朴素感——但如果你把它和 codex cli、zcode cli、trae cli 这些近期高频出现的热词放在一起看，就会发现它根本不是在重复造轮子。我去年深度参与过三个不同团队的 LLM 辅助开发工具链落地项目，从内部 PoC 到生产环境灰度上线，踩过的坑足够写一本《LLM 工具落地避坑手册》。而 open-code-review 是我见过的第一个把“安全边界”刻进基因里的 CLI 代码审查工具。它不追求“一键生成 PR 描述”，也不鼓吹“自动修复所有 bug”，它的核心目标非常具体：在开发者本地 Git 工作流中，嵌入一道可审计、可追溯、零密钥泄露风险的 LLM 审查环节。
关键词里没有填任何内容，但热搜词已经暴露了全部意图：open-code-review、CLI、LLM、code review、Git —— 这五个词连起来，就是它的完整技术坐标系。它不是 Web UI 工具，不依赖后端服务，不托管模型权重，不接入企业知识库；它就是一个二进制可执行文件，运行在你本地终端里，只读取你git diff输出的变更片段，调用你本地配置的 LLM 接口（OpenAI、DeepSeek、Qwen、Ollama 等均可），然后把审查结果以结构化 JSON 或 Markdown 格式输出到标准输出或文件。整个过程不上传任何代码到第三方服务器，不缓存历史 prompt，不记录用户行为日志。这听起来很“笨”，但恰恰是它能在金融、政企、芯片设计等强合规场景被真正接纳的根本原因。
我试过把 open-code-review 集成进 CI 流水线，在某家银行核心交易系统升级项目中跑了一整季度。它没发现过一次“高危漏洞”，但它成功拦截了 17 次因开发人员疏忽导致的敏感信息硬编码（比如把测试环境数据库密码写进了 config.js），也标记出 43 处违反内部《Java 安全编码规范 V3.2》的异常模式（如new Random().nextInt()在加密上下文中使用）。这些都不是传统 SAST 工具能覆盖的语义层问题，也不是 LLM 大模型泛泛而谈的“建议”，而是基于你本地配置的 prompt 模板 + 规则引擎 + 模型推理三者协同的结果。它不替代人工 Review，而是把 Reviewer 从“找错”解放出来，专注在“判责”和“决策”上。
提示：open-code-review 不是“让 AI 替你审代码”，而是“让你用 AI 更精准地定义什么是值得审的代码”。它的价值不在模型多大，而在你能否把业务规则、安全红线、架构约束，翻译成机器可执行的 prompt 指令集。
2. 为什么必须是 CLI？为什么必须绕开 Git Hook 自动触发？
很多人第一反应是：“既然要集成 Git，为什么不直接写 pre-commit hook？”——这是我去年在三个团队都听到过的问题。答案很现实：Git Hook 是最不可靠的自动化入口。不是技术不行，而是人不行。我见过太多次：开发同学为了跳过 pre-commit 的耗时检查，直接git commit --no-verify；或者因为 hook 脚本里 Python 版本不匹配，干脆删掉.git/hooks/pre-commit；更有甚者，把 hook 脚本里的 API Key 硬编码进去，结果一提交就泄露。open-code-review 坚决不碰 Git Hook，它的设计理念是“最小侵入、最大可控”。
它只做一件事：提供一个命令行接口，让你在你认为合适的时间、以你认为合适的方式，主动触发审查。比如：
# 审查当前分支相对于 main 的所有变更 open-code-review --base main --target HEAD # 只审查某个特定 commit 的变更（比 diff 更精确） open-code-review --commit abc1234 # 审查暂存区（staged）的代码，模拟即将提交的内容 open-code-review --staged # 审查指定文件路径下的变更，适合大型 PR 中聚焦关键模块 open-code-review --path src/services/payment/ --path tests/integration/这种显式调用方式，带来了三个关键优势：
第一，可审计性。每一次审查都有明确的命令行参数快照，可以完整记录在 CI 日志或本地 shell history 中。你清楚知道这次审查是基于哪个 base 分支、哪些文件、用了什么模型配置。而 Git Hook 是静默执行的，出了问题连日志都难追溯。
第二，环境隔离性。open-code-review 默认不读取全局环境变量（如OPENAI_API_KEY），而是要求你通过--api-key-file ~/.secrets/openai.key显式指定密钥文件路径。这个文件权限被强制设为600（仅属主可读写），且工具启动时会校验其权限是否合规，不合规则拒绝运行。这是对“使用 LLM 时如何防止密钥等鉴权信息泄露”这一热搜问题的硬性回应——它不依赖开发者自觉，而是用文件系统权限机制兜底。
第三，组合灵活性。你可以把它无缝嵌入任何已有流程：
- 在 VS Code 终端里手动运行，配合
Ctrl+Shift+P→ “Run Task” 快捷触发； - 在 GitHub Actions 中作为独立 step 加入，用
run: open-code-review --staged； - 在 Jenkins Pipeline 中用
sh 'open-code-review --commit ${env.GIT_COMMIT}'； - 甚至写成 alias：
alias ocr='open-code-review --staged --model qwen2.5:14b --format json'。
我实测下来，一个 200 行的 React 组件变更，用 Ollama 本地运行 Qwen2.5:14b 模型，平均耗时 8.3 秒；用 OpenAI gpt-4o-mini，平均耗时 2.1 秒。这个延迟完全在开发者可接受范围内，远低于等待 CI 构建完成的 5~15 分钟。关键是，它不打断你的思维流——你写完代码，敲下ocr，喝口咖啡，回来就能看到结构化报告，而不是被弹窗或通知打断。
2.1 CLI 设计背后的“信任链断裂”预判
open-code-review 的 CLI 架构，本质上是对当前 LLM 工具生态中普遍存在的“信任链断裂”问题的一次系统性防御。什么叫信任链断裂？举个典型例子：某款热门 VS Code 插件，号称“智能代码审查”，它会在你编辑时实时分析 AST 并调用云端 LLM。但它的插件 manifest.json 里声明了"permissions": ["*://*.example-llm-api.com/*"]，而实际请求却发往https://malicious-proxy.net/v1/chat/completions——这就是典型的中间人劫持。用户以为自己在用官方 API，实际流量已被重定向。
open-code-review 用 CLI 形式规避了这个问题：
- 它不注入任何前端脚本，不监听编辑器事件，不申请浏览器权限；
- 所有网络请求由本地进程发起，可通过
strace -e trace=connect,sendto,recvfrom ./open-code-review ...完全监控； - 支持
--proxy http://localhost:8080参数，方便你用 mitmproxy 抓包验证； - 内置证书固定（Certificate Pinning）机制，对已知主流 LLM 服务商域名（openai.com、deepseek.com、qwenlm.ai）进行 TLS 证书指纹校验，若证书不匹配则报错退出，而非静默降级。
这不是过度设计。我在某次红蓝对抗演练中，就用自签名证书伪造了api.deepseek.com域名，成功诱骗了两款主流 IDE 插件向假 API 端点发送了包含源码的请求。而 open-code-review 在连接阶段就因证书指纹不匹配而终止，日志里清晰写着：FATAL: TLS certificate pinning failed for api.deepseek.com (expected: sha256/abc123..., got: sha256/def456...)。这种级别的防护，只有 CLI 工具能做到。
2.2 为什么 Git 是唯一可信的输入源？diff 的三种解析策略
open-code-review 不接受--file path/to/code.js这样的参数，也不支持拖拽文件。它只认 Git。这不是偷懒，而是基于一个深刻认知：Git 是现代软件开发中唯一被广泛接受、版本可控、语义明确的代码状态权威来源。一个文件的“当前内容”可能被编辑器缓存污染，但git show HEAD:src/utils/date.js返回的永远是该 commit 下的确切字节流。
它内部对 Git diff 的解析采用三级策略：
语法级 diff（默认）：调用
git diff --no-color --unified=0 <base> <target>，提取+行（新增）和-行（删除），但保留上下文行（@@ -10,5 +15,8 @@中的行号信息）。这是最轻量、最通用的方式，适用于所有语言。open-code-review 会将每个 hunk（差异块）单独封装为一个审查单元，避免跨函数的语义割裂。AST 级 diff（需额外安装 parser）：当检测到项目根目录存在
tree-sitter-cli且已安装对应语言 grammar（如tree-sitter-javascript），它会启用 AST 模式。此时不是按行比较，而是构建两版 AST，计算节点增删改。例如，一个if语句被改为switch，传统 diff 会显示整段重写，而 AST diff 能精准识别为“ControlFlowStatement replaced with SwitchStatement”。这对识别重构类变更至关重要。语义级 diff（实验性）：结合
git blame和git log --oneline，为每个变更行标注最近一次修改该行的 commit hash 和作者。这使得审查结果能附带溯源信息：“第 42 行的空指针检查被移除，上次修改者 @zhangsan（commit a1b2c3d），原始提交信息：‘优化性能，移除冗余校验’”。这在责任界定和回滚决策时极具价值。
我曾用这三种模式对比审查同一个 PR：语法级 diff 报告了 7 处潜在 NPE；AST 级 diff 发现了 1 处被隐藏的逻辑反转（!=改为==但未改条件分支）；语义级 diff 则指出其中 3 处变更来自同一开发者上周的“性能优化”提交，建议合并审查。这说明，diff 解析策略的选择，直接决定了审查的深度和精度。
3. LLM 不是黑箱：open-code-review 如何驯服大模型的不确定性
热搜词里反复出现“llm 返回 json 不稳定”、“dify 的 sql 查询内容太多导致 llm 返回不稳定”，这直指当前 LLM 应用的最大痛点：输出格式不可控、语义漂移、幻觉率高。open-code-review 没有试图“训练一个更稳定的模型”，而是用工程化手段，在模型之上构建一层“确定性外壳”。
它的核心机制叫Prompt-Template + Schema-Guard + Retry-Backoff三重护栏：
Prompt-Template：不是简单拼接字符串，而是采用 Jinja2 模板引擎，支持条件渲染、循环、过滤器。例如，针对 Java 项目，模板会自动注入
@SuppressWarnings("all")注解的常见误用场景；针对 Go 项目，则预置defer语句遗漏检查规则。模板本身是纯文本，可版本控制、可审计、可 A/B 测试。Schema-Guard：所有 LLM 输出必须符合预定义的 JSON Schema。open-code-review 内置了一个轻量级 JSON Schema 验证器（基于
jsonschema库的精简版），在模型返回后立即校验。如果模型返回了{"issues": [{"severity": "high", "message": "xxx"}]}，但 schema 要求severity必须是["critical", "high", "medium", "low"]枚举值，校验失败则触发重试。更重要的是，它支持Schema-Directed Prompting：在 prompt 末尾明确写出"Output MUST be valid JSON matching this schema: {\"type\":\"object\",\"properties\":{\"issues\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"severity\":{\"enum\":[\"critical\",\"high\",\"medium\",\"low\"]},\"line\":{\"type\":\"integer\"},\"message\":{\"type\":\"string\"}}}}}}"。实测表明，这种“显式约束”比单纯靠 temperature 调节，降低格式错误率 63%。Retry-Backoff：不是简单重试三次。它采用指数退避 + 模型降级策略：第一次失败，用原模型重试（temperature=0.3）；第二次失败，切换到更小的模型（如 gpt-4o-mini 替代 gpt-4o）；第三次失败，启用本地 fallback 模型（Ollama 的 phi3:3.8b），并降低审查粒度（只检查安全类 issue，跳过风格类 issue）。整个过程对用户透明，日志里只记录
INFO: Retry #2 with model gpt-4o-mini (reduced context)。
注意：open-code-review 严格区分“模型能力”和“审查能力”。它不假设某个模型“更强”，而是根据任务类型动态选模。例如，SQL 注入检测用
sqlcoder-7b，JSON Schema 生成用gpt-4o-mini，而中文注释质量评估用qwen2.5:14b。这种细粒度调度，是它能在不同项目中保持高准确率的关键。
3.1 温度（temperature）在审查场景中的真实作用机制
热搜词里有“temperature 是如何在 LLM 的输出中发挥作用的，原理是怎样的”，这问题问到了点子上。在 open-code-review 中，temperature 不是用来“激发创意”的，而是用来控制审查结论的保守程度。
temperature=0.0：模型输出完全 deterministic，只选择概率最高的 token。这适合安全类审查（如硬编码密钥、SQL 注入），要求 100% 确定才报告，宁可漏报，不可误报。实测中，temperature=0.0下，对password = "123456"这种明文密码的检出率是 99.2%，但对password = env.PASSWORD这种间接引用的检出率是 0%（因为模型无法 100% 确定 env.PASSWORD 是否敏感）。temperature=0.5：引入适度随机性，允许模型在多个高概率选项中采样。这适合代码风格、可维护性类审查（如函数过长、圈复杂度高）。它能平衡“过于严苛”和“过于宽松”，比如对一个 80 行的函数，temp=0.0可能沉默，temp=0.5会给出“建议拆分为两个函数”的温和提示。temperature=0.8+：几乎不用。open-code-review 认为，在代码审查这种高确定性需求场景，高温度只会增加幻觉风险。它甚至在 CLI 参数中禁用了--temperature > 0.7的设置，尝试设置会报错ERROR: temperature must be <= 0.7 for code review tasks。
我做过一组对照实验：用同一段含 SQL 拼接的 PHP 代码，分别用temp=0.0,0.3,0.5,0.7运行 100 次。结果：
temp=0.0: 98 次报告“高危：SQL 注入风险”，2 次超时（因模型过于谨慎，反复重试）；temp=0.3: 100 次均报告，且附加了 3 种不同的修复建议；temp=0.5: 95 次报告，5 次误报（将合法的 ORM 查询误判为拼接）；temp=0.7: 82 次报告，18 次幻觉（编造不存在的漏洞，如“第 15 行缺少 try-catch”）。
结论很清晰：在审查场景，temperature 是精度与召回率的调节旋钮，而非创造力开关。open-code-review 的默认值0.3，是经过 27 个真实项目数据集验证后的帕累托最优解。
3.2 Agent、LLM、AI 模型的本质区别：为什么 open-code-review 拒绝“Agent”包装
热搜词里混杂着 “agent 和 llm 和 ai模型 有什么区别”、“比如常说的 deepseek 是属于哪个”，这反映出当前概念的严重混乱。open-code-review 的文档里有一句硬核定义：“我们不构建 Agent，我们只调用 LLM。Agent 是一个分布式系统概念，LLM 是一个统计模型，AI Model 是一个广义术语。混淆它们，是所有失败集成的起点。”
LLM（Large Language Model）：指具体的、可加载的神经网络权重文件，如
deepseek-coder-33b-instruct.Q4_K_M.gguf。它是一个数学函数f(prompt) -> text，输入是字符串，输出是字符串。open-code-review 就是这个函数的调用者。AI Model：更宽泛，包括 LLM、CV 模型、语音模型等。DeepSeek 是一家公司，它发布的 DeepSeek-Coder 是一个 LLM，而 DeepSeek-VL 是一个多模态 AI Model。
Agent：指一个具备“感知-规划-行动”闭环的软件系统。它需要状态管理（memory）、工具调用（tool use）、任务分解（task decomposition）。一个真正的 Agent 审查工具，应该能自动搜索相关文档、调用静态分析器、修改代码、提交 PR——这超出了 open-code-review 的设计边界。
open-code-review 拒绝“Agent”包装，是因为它深知：在代码审查这个垂直领域，增加 Agent 层只会引入新的故障点，而不会提升核心价值。Agent 的 memory 可能泄露上下文，tool use 可能调用错误的 API，task decomposition 可能误解开发者意图。它选择做最简单的事：把 prompt 工程做到极致，把模型调用做到最稳，把输出解析做到最准。这就像一把瑞士军刀，功能不多，但每一项都经得起高强度使用。
4. 实战部署：从零开始搭建一个可审计、可复现的审查流水线
现在，让我们把理论落地。以下是我在一个中型 SaaS 项目（Node.js + TypeScript + PostgreSQL）中，用 open-code-review 搭建的完整审查流水线。所有步骤均可复制，所有配置均有出处。
4.1 环境准备：最小化依赖与安全加固
第一步，下载二进制。不要用npm install或pip install，那会引入不可控的依赖树。直接从官方 GitHub Releases 下载：
# Linux x64 curl -L https://github.com/open-code-review/cli/releases/download/v0.8.2/open-code-review-linux-amd64 -o /usr/local/bin/open-code-review chmod +x /usr/local/bin/open-code-review # 验证完整性（官方提供 SHA256SUMS） curl -L https://github.com/open-code-review/cli/releases/download/v0.8.2/SHA256SUMS -o /tmp/sha256sums sha256sum -c /tmp/sha256sums 2>/dev/null | grep "open-code-review-linux-amd64: OK"第二步，创建密钥管理目录：
mkdir -p ~/.secrets/ocr chmod 700 ~/.secrets/ocr # 创建 OpenAI 密钥文件（权限自动设为 600） echo "sk-..." > ~/.secrets/ocr/openai.key chmod 600 ~/.secrets/ocr/openai.key # 创建本地 Ollama 模型别名（避免硬编码模型名） echo "qwen2.5:14b" > ~/.secrets/ocr/default-model第三步，初始化项目配置。在项目根目录创建.ocr.yaml：
# .ocr.yaml version: "1.0" # 审查范围：只关注 src/ 和 tests/ 目录 include_paths: - "src/**/*" - "tests/**/*" exclude_paths: - "**/node_modules/**" - "**/dist/**" - "**/*.test.ts" # 模型配置：优先用本地 Ollama，失败则降级到 OpenAI models: - name: "ollama-qwen" provider: "ollama" endpoint: "http://localhost:11434" model: "qwen2.5:14b" timeout: 30 - name: "openai-gpt4o" provider: "openai" endpoint: "https://api.openai.com/v1" model: "gpt-4o-mini" api_key_file: "~/.secrets/ocr/openai.key" timeout: 15 # 审查规则：基于 OWASP Top 10 和内部规范 rules: - id: "SEC-001" name: "Hardcoded Secret" severity: "critical" description: "Detect hardcoded credentials, API keys, passwords" prompt_template: | You are a security auditor. Analyze the following code diff. Identify any hardcoded secrets (passwords, API keys, tokens, private keys). Output ONLY valid JSON matching this schema: {"issues": [{"line": integer, "message": string, "severity": "critical"}]} Do NOT output anything else. - id: "STYLE-002" name: "Function Length" severity: "medium" description: "Functions longer than 50 lines should be refactored" prompt_template: | You are a senior developer reviewing code quality. Check if any function in the diff exceeds 50 lines of logic. Output ONLY valid JSON matching this schema: {"issues": [{"line": integer, "message": string, "severity": "medium"}]} Do NOT output anything else.这个配置文件是审查策略的核心，它被纳入 Git 版本控制，每次变更都有完整审计日志。
4.2 本地开发工作流：VS Code 集成与快捷键绑定
在 VS Code 中，我们不装任何插件，只用内置的 Tasks 功能：
- 创建
.vscode/tasks.json：
{ "version": "2.0.0", "tasks": [ { "label": "OCR: Staged Changes", "type": "shell", "command": "open-code-review --staged --config .ocr.yaml --format markdown", "group": "build", "presentation": { "echo": true, "reveal": "always", "focus": false, "panel": "shared", "showReuseMessage": true, "clear": true } }, { "label": "OCR: Current Branch vs Main", "type": "shell", "command": "open-code-review --base main --target HEAD --config .ocr.yaml --format json", "group": "build", "presentation": { "echo": true, "reveal": "silent", "focus": false, "panel": "shared", "showReuseMessage": true, "clear": true } } ] }- 绑定快捷键（
keybindings.json）：
[ { "key": "ctrl+alt+r", "command": "workbench.action.terminal.runActiveFile", "args": { "text": "open-code-review --staged --config .ocr.yaml --format markdown" } } ]现在，你只需按Ctrl+Alt+R，终端就会自动运行审查，并以 Markdown 格式输出带颜色的报告。关键在于，这个命令是完全可复现的：它依赖的.ocr.yaml、~/.secrets/ocr/目录、甚至open-code-review二进制的 SHA256 哈希，都可以被完整记录和验证。
4.3 CI/CD 集成：GitHub Actions 中的零信任审查
在.github/workflows/ocr-review.yml中：
name: Open Code Review on: pull_request: branches: [main, develop] types: [opened, synchronize, reopened] jobs: ocr: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # 必须获取完整历史，用于 git blame - name: Install open-code-review run: | curl -L https://github.com/open-code-review/cli/releases/download/v0.8.2/open-code-review-linux-amd64 -o ocr chmod +x ocr sudo mv ocr /usr/local/bin/ - name: Setup Secrets (Secure) run: | mkdir -p ~/.secrets/ocr echo "${{ secrets.OPENAI_API_KEY }}" > ~/.secrets/ocr/openai.key chmod 600 ~/.secrets/ocr/openai.key - name: Run OCR Review id: ocr run: | # 仅审查本次 PR 引入的变更 open-code-review \ --base ${{ github.event.pull_request.base.sha }} \ --target ${{ github.event.pull_request.head.sha }} \ --config .ocr.yaml \ --format json \ --output /tmp/ocr-report.json 2>&1 || true - name: Upload Report if: always() uses: actions/upload-artifact@v4 with: name: ocr-report path: /tmp/ocr-report.json - name: Post Comment (if issues found) if: steps.ocr.outputs.exit-code != '0' uses: actions/github-script@v7 with: script: | const data = require('/tmp/ocr-report.json'); const issues = data.issues.filter(i => i.severity === 'critical' || i.severity === 'high'); if (issues.length > 0) { const comment = `## 🔍 Open Code Review Alert\nFound ${issues.length} high/critical issues:\n\n${issues.map(i => `- \`${i.message}\` (line ${i.line})`).join('\n')}`; github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: comment }); }这个 workflow 的关键设计点：
fetch-depth: 0：确保git blame能正常工作；secrets.OPENAI_API_KEY通过 Actions Secrets 注入，绝不硬编码；|| true允许审查失败（如模型超时）不中断流水线，但后续步骤仍会处理；- 最终评论只在发现 critical/high 问题时才触发，避免噪音。
我实测过，一个 500 行的 PR，这个 workflow 平均耗时 42 秒，其中模型推理占 35 秒，其余为 Git 操作和 JSON 解析。它已成为我们团队 PR 的强制准入门槛——没有 OCR 报告，PR 无法合并。
5. 踩坑实录：那些让 open-code-review 在生产环境“失灵”的真实场景
再好的工具，也会在真实世界中撞墙。以下是我在三个不同客户现场遇到的、最具代表性的五个“失灵”场景，以及我们是如何修复的。这些不是理论推测，而是血泪教训。
5.1 场景一：Git 子模块（submodule）变更被完全忽略
现象：一个大型 C++ 项目，核心算法库放在 Git submodule 中。开发者更新了 submodule 的 commit，但 open-code-review 的--staged模式完全没有报告任何变更。
根因分析：open-code-review 默认只扫描工作区（working directory）的文件变更，而git diff --staged对 submodule 的变更，只显示Subproject commit abc123...这一行，不展开其内部 diff。这是 Git 的设计，不是工具缺陷。
解决方案：在.ocr.yaml中添加submodules: true配置，并在 CLI 中启用--recursive参数：
# .ocr.yaml submodules: enabled: true depth: 2 # 递归深度open-code-review --staged --recursive --config .ocr.yaml启用后，工具会自动执行git submodule foreach --recursive 'git diff --unified=0 HEAD@{1} HEAD'，并将子模块内的 diff 合并到主审查流中。注意：这会显著增加耗时，因此默认关闭，需显式启用。
5.2 场景二：LLM 返回了完美的 JSON，但字段值是空字符串
现象：审查报告里issues数组存在，但每个message字段都是空字符串""，导致无法判断问题。
根因分析：这是典型的 prompt 工程失败。我们的 prompt 模板里写了"Output ONLY valid JSON..."，但没约束message字段的最小长度。模型在不确定时，倾向于输出空字符串而非冒险编造。
解决方案：在 JSON Schema 中添加minLength: 10约束，并在 prompt 中强化指令：
rules: - id: "SEC-001" prompt_template: | You are a security auditor. Analyze the following code diff. Identify any hardcoded secrets... For EACH issue, provide a SPECIFIC, ACTIONABLE message (at least 10 characters, no placeholders like 'xxx'). Output ONLY valid JSON matching this schema: {"issues": [{"line": integer, "message": {"type": "string", "minLength": 10}, "severity": "critical"}]}实测后，空字符串率从 12% 降至 0.3%。
5.3 场景三：Windows 环境下路径分隔符导致文件匹配失败
现象：在 Windows 开发者机器上，--path src\utils\date.js参数无法匹配到文件，报错No files matched pattern 'src\utils\date.js'。
根因分析：open-code-review 内部使用 glob 库解析路径，而 Windows 的\在某些 shell 中会被转义。这不是 bug，而是跨平台路径处理的经典陷阱。
解决方案：工具层面统一转换路径分隔符。我们在 v0.8.1 版本中加入了自动规范化：
# 以下三种写法在 Windows 上效果完全相同 open-code-review --path "src\utils\date.js" open-code-review --path "src/utils/date.js" open-code-review --path "src\\utils\\date.js"原理是：CLI 启动时，对所有--path参数调用filepath.ToSlash()（Go 标准库），将\统一转为/，再进行 glob 匹配。这消除了 90% 的 Windows 用户首次使用障碍。
5.4 场景四：CI 环境中 Ollama 服务未启动，降级失败
现象：GitHub Actions 中，我们配置了 Ollama 作为首选模型，但 workflow 因Connection refused失败，且未按预期降级到 OpenAI。
根因分析：降级逻辑依赖于connection refused错误码，但 CI 环境中 Ollama 未安装，错误是exec: "ollama": executable file not found in $PATH，不属于网络错误，因此未触发降级。
解决方案：在 v0.8.2 中，我们重构了模型健康检查机制。现在，每个模型配置项都支持health_check_command：
models: - name: "ollama-qwen" provider: "ollama" endpoint: "http://localhost:11434" model: "qwen2.5:14b" health_check_command: "ollama list | grep qwen2.5:14b" # 如果 health_check_command 退出码非 0，则跳过此模型这样，CI 环境中 Ollama 未安装时，健康检查失败，自动跳过，直接使用下一个模型。
5.5 场景五：审查报告体积过大，导致 GitHub 评论被截断
现象：一个大型 PR 产生了 200+ 条审查意见，GitHub API 限制评论长度为 65536 字符，导致报告被截断，关键问题丢失。
根因分析：这是平台限制，不是工具问题。但我们不能让用户手动分页。
解决方案：open-code-review 内置了--max-comments和--comment-format参数：
open-code-review \ --staged \ --max-comments 50 \ --comment-format github-pr \ --output /tmp/ocr-report.md它会自动将报告按 severity 分组，每组最多 50 条，生成多个 Markdown 文件（ocr-report-01.md,ocr-report-02.md...），并在 CI 中循环调用gh pr comment命令。这样，即使 500 条问题，也能完整呈现。
6. 进阶技巧：如何用 open-code-review 构建自己的“审查知识库”
open-code-review 的终极价值，不在于它能发现多少问题，而在于它能把分散的、经验性的、口头传递的“审查智慧”，固化为可执行、可传播、可迭代的数字资产。这就是它的“审查知识库”能力。
6.1 从个人经验到团队规范：prompt 模板的版本化管理
我们团队最初只有一份.ocr.yaml，所有规则混在一起。随着项目增多，问题来了：支付模块的审查规则，不该套用在 UI 组件上；Go 项目的内存泄漏检查，对 TypeScript 无效。于是我们建立了三层模板体系：
基础层（global）：位于
$HOME/.ocr/templates/，存放所有项目通用的规则，如SEC-001 Hardcoded Secret、STYLE-001 Function Length。语言层（language）：位于项目根目录
templates/，按语言组织，如templates/typescript/下有
