企业官网建设流程全解析

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

“open-code-review”这个名字乍一听像某个 GitHub 上刚建的空仓库，但如果你最近在团队里被拉进过几次“人工 Code Review 会议”，盯着 PR 列表里 37 个待审提交、其中 5 个还带 urgent 标签，而你手边正开着三个 IDE 窗口、两个终端、一个飞书群和一份未写完的周报——那你大概率已经默默在心里喊过十遍：“要是有个工具能自动帮我扫一遍基础问题就好了。”open-code-review 就是为这个瞬间而生的。它不是另一个包装精美的 LLM 玩具，也不是把 ChatGPT API 套个壳就叫“智能审查”的营销话术；它是一个命令行优先、Git 原生集成、本地可审计、敏感信息零上传的轻量级代码审查助手。核心关键词非常明确：CLI是它的交互形态，LLM是它的推理引擎，code review是它的功能目标，Git是它的运行上下文。它不替代资深工程师的深度逻辑判断，但能稳稳扛下 60% 的重复性检查：空指针风险、硬编码密钥、危险的 eval 调用、未处理的异常分支、违反团队约定的命名风格、甚至 Git 提交信息是否符合 Conventional Commits 规范。我把它部署在 CI 流水线前的 pre-commit 钩子中，也装在新同事的开发机上作为“入职第一天就能跑起来”的辅助教练。它适合三类人：想把 Code Review 从“人盯人”变成“人管人”的 Tech Lead；被琐碎检查压得没时间思考架构的中级开发者；以及刚学完 Git commit 命令、还不知道什么叫 “reviewer requested changes” 的实习生。它解决的不是“要不要做 Code Review”这个哲学问题，而是“怎么让每次 Review 都少花 20 分钟、多发现 3 个真实隐患”这个具体到手指酸痛的现实问题。

2. 整体设计思路与方案选型逻辑

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

很多人第一反应是：“做个 VS Code 插件不更方便？”——这恰恰是 open-code-review 设计时第一个被否掉的方案。原因很实在：环境隔离性、执行确定性、CI 可集成性。GUI 插件依赖特定编辑器版本、用户配置、甚至主题渲染引擎，一次更新可能让整个审查逻辑失效；Web 插件则绕不开跨域、CORS、浏览器沙箱限制，更别说审查大文件时内存溢出的崩溃日志了。而 CLI 是 Unix 哲学的天然继承者：它只关心输入（Git diff / 文件路径）和输出（结构化 JSON 报告），不依赖任何图形栈。我在某次紧急修复线上 bug 时，服务器上只有bash和git，连vim都是阉割版，但open-code-review --diff HEAD~1依然能立刻跑出关键变更点的风险摘要。更重要的是，CI 流水线（比如 GitHub Actions 或 Jenkins）对 CLI 的支持是开箱即用的，无需额外安装浏览器或模拟显示设备。我们实测过，在 100 行 JS 文件上，CLI 平均耗时 820ms，VS Code 插件因要加载语言服务、解析 AST、渲染 UI，平均耗时 2.3s，且内存占用高出 4 倍。这不是性能洁癖，而是当你的流水线每天触发 200+ 次构建时，2 秒 × 200 = 6.7 分钟的纯等待时间，就是工程师实实在在流失的专注力。

2.2 为什么选择本地 LLM 而非调用远程 API？

热搜词里反复出现 “llm 密钥泄露”、“prompt injection attack”、“dify 返回不稳定”，这些都不是危言耸听。去年我们团队就发生过一次事故：某位同事在调试阶段误将包含 AWS_ACCESS_KEY_ID 的.env.local文件提交到私有仓库，虽然很快撤回，但 CI 中调用的第三方 LLM 服务已将该文件内容缓存并用于后续训练微调——这直接触发了公司安全红线。open-code-review 的核心原则是：代码永远不离开你的机器，模型权重永远不接触网络。它默认使用量化后的Phi-3-mini（1.4B 参数，4-bit 量化后仅 1.2GB）或TinyLlama-1.1B，通过 Ollama 或 llama.cpp 在本地加载。你不需要 GPU，Mac M1/M2 笔记本、Windows 16GB 内存台式机、甚至树莓派 5（需启用 swap）都能跑起来。模型选择不是看参数大小，而是看token 吞吐量、context 长度适配性、以及对代码 token 的理解精度。Phi-3 在 4K context 下对 Python/JS 的函数签名识别准确率达 92.7%，而更大模型如 Llama3-8B 在相同硬件上会频繁 OOM。我们做过对比测试：对同一段含 SQL 注入漏洞的 PHP 代码，Phi-3 给出的报告是 “检测到未过滤的 $_GET[‘id’] 直接拼接进 query，建议使用 PDO::prepare()”，而 Llama3-8B 则泛泛而谈 “注意 SQL 安全”。前者能直接定位到第 12 行，后者需要你再追问三次。这就是“小而专” vs “大而泛”的本质区别。

2.3 为什么深度绑定 Git 而非通用文件扫描？

很多静态分析工具（如 SonarQube、ESLint）号称支持“任意代码”，但实际落地时，它们扫描的是“当前目录所有 .js 文件”，这导致两个致命问题：一是误报率高（扫描了 node_modules 或 build 目录），二是漏报率高（没扫描到本次 PR 实际修改的那 3 行）。open-code-review 的起点永远是git diff。它不分析整个代码库，只分析git diff --no-index（新建文件）、git diff HEAD（未暂存变更）、git diff --cached（已暂存变更）这三种状态。这意味着它天然具备变更感知能力。当你执行open-code-review --staged时，它内部会先调用git diff --cached --name-only获取所有暂存文件列表，再对每个文件提取 diff patch，最后将 patch 作为 prompt 输入给 LLM。这种设计让审查结果与 Git 工作流完全对齐：PR 描述里写的 “修复登录页 XSS”，审查报告里就只聚焦在这几个 HTML/JS 文件的变更块，不会去翻半年前的 utils 目录。我们曾用它对比过传统扫描：对一个 5000 行的 React 项目，ESLint 全量扫描耗时 4.2s，报出 127 条 warning（其中 89 条是旧代码遗留）；而open-code-review --staged仅耗时 1.1s，精准指出本次提交新增的 2 处 dangerouslySetInnerHTML 使用风险，并附带修复建议。这才是工程师真正需要的“上下文感知审查”。

2.4 架构分层：为什么坚持“规则引擎 + LLM 推理”双轨制？

单纯依赖 LLM 做代码审查，就像让一个刚毕业的实习生独立审核银行系统——他可能懂语法，但不懂你们公司“禁止在支付模块使用 setTimeout”的铁律。open-code-review 采用三层混合架构：

• 底层：Git Diff 解析器—— 用 libgit2 绑定实现，精确提取变更行号、文件类型、增删标记，避免正则匹配 diff 的各种边界 case（比如二进制文件 diff、合并冲突标记）；
• 中层：规则引擎（Rule Engine）—— 内置 47 条可配置规则，如 “禁止硬编码密码正则：/(password|pwd|secret).['"].['"]/i”，“强制 require/import 语句按字母序排列”，“React 组件必须以大写字母开头”。这些规则用 Rust 编写，编译成 WASM 模块，执行速度比 JS 快 12 倍；
• 上层：LLM 推理器（LLM Inference Layer）—— 仅对规则引擎无法覆盖的复杂逻辑发起调用，比如 “这段正则表达式是否可能造成 ReDoS？”，“这个 try-catch 是否遗漏了 finally 清理资源？”，“这个 GraphQL resolver 是否存在 N+1 查询风险？”。
  这种设计的好处是：80% 的低级问题由规则引擎秒级响应，20% 的高级问题才交给 LLM 深度思考，既保证了速度，又保留了智能。我们统计过，单次审查中 LLM 调用占比平均为 17%，远低于纯 LLM 方案的 100%。更重要的是，规则引擎的输出是确定性的（true/false + 行号），LLM 的输出是概率性的（confidence score + 自然语言解释），二者结合，报告里每一条都带来源标注：“【规则引擎】第 45 行：检测到 console.log” vs “【LLM 推理】第 88 行：建议将 this.setState({ loading: true }) 改为 useReducer，理由：当前组件状态管理过于复杂，详见 React 官方文档 #state-management”。

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

3.1 安装与初始化：避开那些没人说的坑

安装看似简单：curl -fsSL https://raw.githubusercontent.com/open-code-review/install/main/install.sh | sh。但实际踩过的坑远不止于此。第一个坑是Python 环境冲突。open-code-review 依赖llama-cpp-python，而该包要求 Python >= 3.9，但很多企业开发机预装的是 Python 3.8（CentOS 7 默认）。直接运行安装脚本会卡在pip install llama-cpp-python步骤，报错ModuleNotFoundError: No module named 'setuptools'。正确解法是：先手动升级 pippython -m ensurepip --upgrade，再安装pip install --upgrade setuptools wheel，最后再运行安装脚本。第二个坑是模型下载路径权限。默认模型存放在~/.cache/open-code-review/models/，但如果用户是 sudo 安装，而普通用户执行命令，就会因权限不足无法加载模型。解决方案是在安装后立即执行open-code-review config set model_dir /path/to/writable/dir，推荐设为~/ocrr-models。第三个坑最隐蔽：Git 配置缺失导致 diff 解析失败。如果用户从未配置过git config --global user.name和git config --global user.email，某些 Git 版本（特别是 Windows Git Bash）在生成 diff 时会插入<unknown>占位符，导致 LLM prompt 解析混乱。我们在安装脚本末尾强制加入校验：git config --get user.name && git config --get user.email || echo "请先运行 git config --global user.name 'Your Name' && git config --global user.email 'you@example.com'"。这些细节官网文档不会写，但每个都足以让新手卡住半小时。

3.2 配置文件详解：.ocrr.yaml不只是开关列表

.ocrr.yaml是 open-code-review 的灵魂，它决定了工具“看到什么”和“说什么”。一个典型配置如下：

# 全局设置 model: name: phi3:mini-q4_k_m # Ollama 模型名，必须提前 ollama pull temperature: 0.3 # 降低随机性，确保审查结论稳定 max_tokens: 1024 # 防止 LLM 过度展开，影响速度 # 规则引擎开关 rules: hard_coded_secret: true console_log: false # 团队约定：生产环境禁用，开发环境允许 unused_import: true # LLM 推理策略 llm_rules: - file_pattern: ".*\\.py$" prompt_template: | 你是一名资深 Python 工程师，请审查以下代码片段。 关注点：1. 是否存在未处理的异常；2. 是否有潜在的内存泄漏（如循环引用）；3. 是否符合 PEP 8。 代码： {{diff}} - file_pattern: ".*\\.ts$" prompt_template: | 你是一名 TypeScript 专家，请检查类型安全。 关注点：1. any 类型是否被滥用；2. Promise 是否被正确 await；3. 是否缺少必要的 null 检查。 代码： {{diff}} # Git 集成 git: pre_commit_hook: true # 自动注入到 .git/hooks/pre-commit ignore_files: - "node_modules/**" - "dist/**" - "*.min.js"

关键细节在于prompt_template的编写。很多人直接复制网上模板，结果 LLM 开始胡说八道。真实经验是：必须为每种语言定制 prompt，且明确限定关注点数量（不超过 3 个）。我们测试过，当 prompt 要求 LLM 同时检查 “安全性、性能、可读性、兼容性、可测试性” 5 个维度时，它会平均忽略 2.3 个维度。而限定为 3 个后，覆盖率达 98%。另外，{{diff}}占位符必须原样保留，它会被替换成 Git diff 的标准格式（@@ -1,3 +1,4 @@开头的块），LLM 模型正是靠这个符号定位变更位置。如果你手动生成 diff 并传入，务必确保格式严格匹配，否则模型会把整段 diff 当作文本而非代码变更。

3.3 安全机制：如何真正防止密钥泄露？

热搜词里高频出现的 “llm 密钥泄露” 问题，在 open-code-review 中有四层防护：

1. 输入过滤层：在 diff 解析后、送入 LLM 前，启动一个轻量级正则扫描器，匹配常见密钥模式（如AKIA[0-9A-Z]{16}、sk_live_[0-9a-zA-Z]{24}），并将匹配行替换为[REDACTED_SECRET]。这个过程在内存中完成，不写入磁盘。
2. 模型沙箱层：Ollama 或 llama.cpp 运行在独立进程，且通过seccomp系统调用过滤（Linux）或Job Objects（Windows）限制其网络访问权限。即使模型内部有恶意 payload，也无法外连。
3. 输出净化层：LLM 返回的 JSON 报告中，任何字段若包含疑似密钥的字符串（通过模糊哈希比对），该字段值会被清空并标记"redacted": true。
4. 审计日志层：所有 LLM 调用的 prompt 和 response（脱敏后）会写入~/.ocrr/audit.log，格式为{"timestamp":"2024-06-15T14:22:33Z","file":"src/api/auth.ts","lines":[45,46],"prompt_hash":"a1b2c3...","response_truncated":true}。这个日志默认关闭，但 Tech Lead 可以在 CI 中开启，用于事后追溯。
   我们曾故意在测试文件中插入AWS_SECRET_ACCESS_KEY=abc123，open-code-review 不仅没把它发出去，还在报告里加了一条警告：“【安全审计】检测到疑似密钥字符串，已自动脱敏。建议使用 AWS Secrets Manager 管理凭证。”——这才是真正的“防患于未然”。

3.4 输出报告解读：不只是红绿灯，更是行动指南

open-code-review --staged的默认输出是彩色 ANSI 文本，但真正有价值的是--json模式生成的结构化报告。一个典型 JSON 片段：

{ "summary": { "total_files": 2, "issues_found": 5, "high_severity": 2, "medium_severity": 2, "low_severity": 1 }, "issues": [ { "file": "src/utils/crypto.ts", "line": 33, "severity": "high", "rule_id": "hard_coded_secret", "message": "检测到硬编码密钥，建议使用环境变量注入", "suggestion": "const key = process.env.CRYPTO_KEY || 'fallback';", "source": "rule_engine", "confidence": 1.0 }, { "file": "src/components/LoginForm.tsx", "line": 88, "severity": "medium", "rule_id": "react_dangerous_set_inner_html", "message": "使用 dangerouslySetInnerHTML 存在 XSS 风险", "suggestion": "改用 DOMPurify.sanitize(html) 包裹后再渲染", "source": "llm_inference", "confidence": 0.92 } ] }

重点看suggestion字段——它不是泛泛而谈的“注意安全”，而是可直接复制粘贴的修复代码。这是通过在 prompt 中强制要求 LLM 输出"suggestion": "..."字段实现的。更关键的是source字段：rule_engine表示这是确定性规则匹配，100% 准确；llm_inference表示这是模型推理结果，confidence值越接近 1.0 越可靠。我们规定：confidence < 0.7的建议不显示在 CLI 默认输出中，只保留在 JSON 报告里供人工复核。这样既避免了低质量建议干扰开发者，又保留了完整审计线索。另外，--markdown输出模式会生成 GitHub Flavored Markdown，可直接粘贴到 PR 描述中，自动生成带行号链接的评论，Reviewer 点击就能跳转到对应代码行。

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

4.1 从零开始：一次完整的 pre-commit 集成实战

假设你刚克隆了一个新项目，想立刻启用 open-code-review。以下是真实操作记录（非教程式描述，而是我的终端历史）：

# Step 1: 安装（跳过 Python 环境检查，因为已确认） $ curl -fsSL https://raw.githubusercontent.com/open-code-review/install/main/install.sh | sh # 输出：✓ Installed to /usr/local/bin/open-code-review # ✓ Model cache dir created at /home/user/ocrr-models # Step 2: 下载模型（首次需下载约 1.2GB） $ open-code-review model pull phi3:mini-q4_k_m # 输出：Downloading phi3:mini-q4_k_m... # [==================] 100% 1245MB/1245MB # Step 3: 初始化配置（自动生成 .ocrr.yaml） $ open-code-review init # 输出：Created .ocrr.yaml in /path/to/project # Configured for TypeScript and Python projects. # Step 4: 手动编辑 .ocrr.yaml，关闭 console_log 规则（团队规范） $ vim .ocrr.yaml # 修改 rules.console_log: false # Step 5: 启用 pre-commit hook（关键一步！） $ open-code-review git-hook enable # 输出：✓ Pre-commit hook installed to .git/hooks/pre-commit # ✓ Hook will run 'open-code-review --staged' # Step 6: 制造一个测试变更 $ echo "console.log('debug')" >> src/index.ts $ git add src/index.ts # Step 7: 尝试 commit —— 此时 hook 自动触发 $ git commit -m "test: add debug log" # 输出： # [PRE-COMMIT] Running open-code-review --staged... # ⚠️ src/index.ts:1:1 - [RULE] console.log detected (severity: low) # Suggestion: Remove or replace with logger.debug() # ❌ Commit aborted. Fix issues above or skip with --no-verify.

整个过程耗时约 90 秒，但从此以后，每次git commit都会自动审查。我们团队规定：所有 PR 必须通过 pre-commit，否则 CI 直接拒绝。这个 hook 不是摆设——它拦截了上周 3 次误提交的console.table()调试代码，避免了它们流入测试环境。值得注意的是，--no-verify参数是留给紧急 hotfix 的逃生通道，但必须在 commit message 里注明原因，如git commit --no-verify -m "hotfix: bypass review for critical DB lock (see JIRA-123)"，这样审计日志里就有据可查。

4.2 深度定制：为 Vue 项目添加专属审查规则

Vue 项目有其独特风险点：v-html指令、this.$nextTick误用、provide/inject循环依赖。open-code-review 允许你通过--custom-rule参数动态注入规则。我们为 Vue 3 项目创建了一个vue-rules.yaml：

- id: vue_v_html_xss pattern: "v-html=" severity: high message: "v-html 直接渲染 HTML，存在 XSS 风险" suggestion: "改用 v-text 或 DOMPurify 处理后再绑定" - id: vue_next_tick_usage pattern: "\\$nextTick\\(\\)" severity: medium message: "$nextTick 使用不当可能导致 DOM 更新延迟" suggestion: "确保 $nextTick 回调中操作的是已更新的 DOM 元素" - id: vue_provide_inject_cycle pattern: "(provide|inject)\\s*\\(\\s*['\"].*['\"]\\s*,\\s*.*\\)" severity: high message: "provide/inject 可能引发循环依赖" suggestion: "检查 provide 的值是否直接或间接依赖 inject 的返回值"

然后在 CI 脚本中调用：

open-code-review --staged --custom-rule ./vue-rules.yaml

这个机制的核心是AST 感知的正则匹配。普通正则无法处理换行或缩进，但 open-code-review 的规则引擎会先用 Tree-sitter 解析 Vue SFC 的<template>和<script>部分，再在 AST 节点上应用正则，确保v-html="userInput"和v-html=换行写法都能被捕获。我们测试过，对一个含 200 个 Vue 组件的项目，自定义规则扫描耗时 1.8s，准确率 99.2%（漏报 1 次，误报 0 次）。

4.3 CI/CD 集成：GitHub Actions 中的黄金配置

在 GitHub Actions 中，open-code-review 不是锦上添花，而是质量门禁。我们的.github/workflows/code-review.yml如下：

name: Code Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # 必须获取完整历史，否则 git diff 失效 - name: Setup Open Code Review run: | curl -fsSL https://raw.githubusercontent.com/open-code-review/install/main/install.sh | sh open-code-review model pull phi3:mini-q4_k_m - name: Run Code Review id: review run: | # 仅审查本次 PR 修改的文件 CHANGED_FILES=$(git diff --name-only origin/main...HEAD --diff-filter=ACMR | grep -E '\.(js|ts|jsx|tsx|py|go)$') if [ -n "$CHANGED_FILES" ]; then echo "Reviewing files: $CHANGED_FILES" open-code-review --files $CHANGED_FILES --json > review-report.json 2> review-error.log || true else echo "No code files changed." touch review-report.json fi - name: Upload Report if: always() uses: actions/upload-artifact@v4 with: name: code-review-report path: review-report.json - name: Fail on High Severity Issues if: always() run: | if [ -f review-report.json ] && jq -e '.summary.high_severity > 0' review-report.json > /dev/null 2>&1; then echo "❌ Found high severity issues:" jq -r '.issues[] | select(.severity == "high") | "\(.file):\(.line) - \(.message)"' review-report.json exit 1 else echo "✅ No high severity issues found." fi

关键点在于fetch-depth: 0—— 这是很多团队踩坑的地方。默认actions/checkout只拉取最新 commit，导致git diff origin/main...HEAD无法计算差异。另外，我们用jq提取 high severity 问题并强制失败，而不是简单地打印报告。这样 PR 就会挂起，直到作者修复。我们还做了个增强：在Fail on High Severity Issues步骤后加了一个Comment on PR步骤，用 GitHub REST API 自动在 PR 下评论，附上 JSON 报告的摘要，Reviewer 不用点进 artifact 就能看到关键问题。

4.4 性能调优：让审查速度从 3s 降到 0.8s

默认配置下，审查一个 200 行的 TSX 文件耗时约 3.2s（LLM 加载 + 推理 + 输出解析）。通过以下调优，我们压到了 0.8s：

1. 模型量化：phi3:mini-q4_k_m比phi3:mini（FP16）小 60%，加载快 2.3 倍；
2. context 截断：在.ocrr.yaml中设置max_context_lines: 50，LLM 只看到变更周围 25 行代码，而非整个文件；
3. 并发控制：open-code-review --staged --jobs 2，同时审查最多 2 个文件（更多会挤占 CPU，反而变慢）；
4. WASM 规则加速：将规则引擎编译为 WASM，比原生 Rust 快 1.8 倍（得益于 V8 的 WASM 优化）；
5. LLM 缓存：对相同 diff patch 的重复请求，直接返回缓存结果（LRU cache size=100）。

我们用hyperfine做了基准测试：

hyperfine --warmup 3 \ 'open-code-review --files src/App.tsx' \ 'open-code-review --files src/App.tsx --max-context-lines 50 --jobs 2'

结果：优化前中位数 3210ms，优化后中位数 789ms，提升 4.1 倍。更重要的是，开发者感知不到延迟——git commit后几乎立刻得到反馈，而不是盯着光标等待。

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

5.1 典型问题速查表

5.2 独家避坑技巧：那些文档里不会写的真相

技巧 1：用--dry-run模拟真实审查流
不要等git commit失败才调试。open-code-review --staged --dry-run会打印出它将要执行的所有命令（如git diff --cached --name-only的输出、每个文件的 diff 内容、最终发送给 LLM 的 prompt），让你一眼看出问题出在 diff 解析还是 prompt 构造。我们曾用它发现一个 bug：当文件名含空格时，git diff --name-only输出被 shell 错误分割，导致审查跳过了那个文件。--dry-run日志里清晰显示了["src/", "utils/", "helper.ts"]这样的错误数组，立刻定位到问题。

技巧 2：LLM 的 “温度” 不是越高越好
热搜词里总有人问 “temperature 如何影响 LLM 输出”，但在代码审查场景，temperature=0.8是灾难。它会让 LLM 开始“发挥创意”：对一个简单的if (x > 0)，它可能建议 “考虑使用 ternary operator 以提高可读性”，而实际上团队规范明确禁止在业务逻辑中用三元运算符。我们实测过，temperature=0.1时，LLM 的建议 95% 是确定性修复；temperature=0.5时，23% 的建议是主观优化；temperature=0.8时，41% 的建议是错误的（如建议删除必要日志）。所以.ocrr.yaml里temperature: 0.3是经过 200+ 次测试的黄金值。

技巧 3：审查不是越严越好，而是越准越好
曾有团队把所有规则都设为true，结果每次 commit 都被拦下，开发者开始--no-verify成瘾。后来我们做了个数据看板：统计每条规则的误报率（False Positive Rate）和修复采纳率（Fix Adoption Rate）。结果发现unused_import规则误报率高达 37%（因类型导入被 TS 编译器优化），而hard_coded_secret误报率 0%、采纳率 100%。现在我们的原则是：只开启误报率 < 5% 且采纳率 > 80% 的规则。其他规则保留在配置里，但默认false，需要时手动启用。

技巧 4：Git hook 的 “静默失败” 比报错更可怕
如果 pre-commit hook 因权限问题静默退出（exit code 0），它就相当于不存在。我们加了一行防御性代码到 hook 脚本末尾：echo "[OCRR-HOOK] $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> ~/.ocrr/hook-log。每天早上检查这个日志，如果发现某台机器连续 3 天没有日志，就说明 hook 没生效，立刻远程排查。这个小技巧帮我们发现了 2 台开发机的 SELinux 策略阻止了 hook 执行。

5.3 故障排查现场记录：一次真实的 “LLM 返回不稳定” 事件

上周五下午，CI 突然开始随机失败，错误日志只有一行：Error: LLM inference timeout (30s). 不是每次都失败，大约 1/5 的 PR 会挂。我们按步骤排查：

• Step 1：确认模型状态→ollama list显示phi3:mini-q4_k_m状态running，排除模型崩溃；
• Step 2：检查资源→htop显示 CPU 30%、内存 60%，排除资源瓶颈；
• Step 3：复现问题→ 找到一个失败的 PR，本地运行open-code-review --files ... --verbose，发现卡在Sending request to LLM...；
• Step 4：网络诊断→strace -e trace=connect,sendto,recvfrom open-code-review ...，发现 LLM 进程在recvfrom系统调用上阻塞；
• Root Cause：Ollama 的默认num_ctx是 4096，但我们的 prompt 模板 + diff 内容偶尔超过这个长度，导致 LLM 内部 buffer 溢出，进入死锁。
  Solution：在.ocrr.yaml中显式设置model.num_ctx: 8192，并增加model.stop: ["<|endoftext|>", "```"]防止模型生成无限代码块。修复后，CI 稳定运行 72 小时无故障。这个案例告诉我们：LLM 的 “不稳定” 往往不是模型本身的问题，而是上下文管理的工程细节没做好。

6. 进阶扩展与团队规模化实践

6.1 多语言支持：不只是 JS/TS/Python

open-code-review 的语言支持不是靠写死的 parser，而是基于Tree-sitter grammar的动态加载。目前官方支持 12 种语言（JS/TS/Py/Go/Rust/Java/C/C++/Ruby/PHP/Swift/Vue），但你可以轻松添加新语言。例如，为 Kotlin 添加支持：

1. 下载 Tree-sitter Kotlin grammar