企业官网建设流程全解析

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

“open-code-review”这个名字乍一听像某个 GitHub 上刚起步的玩具项目，但如果你最近在团队里被 PR 堆得喘不过气、被“已阅”式评论反复折磨、或者发现 junior 同学提交的代码里藏着三个未处理的null异常和一个硬编码的 API 密钥——那你大概率已经站在了这个工具的真实需求入口。它不是另一个“用 LLM 自动生成 review comment”的演示 Demo，而是一个以 Git 为输入源、以 CLI 为唯一交互界面、以安全可控为设计底线的代码审查工作流中枢。核心关键词 open-code-review、CLI、LLM、code review、Git 全部不是装饰词：open 指的是整个审查逻辑可配置、规则可审计、模型调用链路透明；code-review 是它的唯一使命，不搞文档生成、不写测试用例、不补 README；CLI 意味着它必须能在 CI 流水线里静默运行，也能在开发者终端里一键触发；LLM 不是噱头，而是作为深度语义理解引擎嵌入在规则判断之后，而非替代人工决策；Git 则是它唯一的上下文来源——从git diff的原始输出开始，到git log --oneline -n 5的提交脉络，再到.gitignore定义的边界，全部是它认知世界的全部素材。

我去年在带一个跨时区的 12 人前端团队时，每天平均要处理 37 个 PR，其中 62% 的问题其实属于“模式化缺陷”：比如 React 组件中重复创建函数导致不必要的重渲染、TypeScript 类型断言滥用、Axios 请求缺少错误兜底、甚至.env文件误提交。这些问题靠人工肉眼扫描效率极低，靠 ESLint 等静态检查又覆盖不到语义层。我们试过把 diff 内容喂给通用 LLM API，结果要么超时、要么返回格式混乱、要么把密钥当普通字符串直接回显在 review comment 里——这直接触发了公司安全红线。后来我们砍掉所有花哨功能，只保留“读 diff → 提取变更块 → 匹配规则 → 触发 LLM 深度分析 → 生成结构化建议”这一条主干路径，用纯 Bash + Python 脚本搭出最小可行版本，上线三个月后，PR 平均审核时长下降 41%，高危问题漏检率从 18% 降到 2.3%。这个过程让我彻底明白：“open-code-review”的价值不在“用了多大的模型”，而在“如何让 LLM 在 Git 的约束框架里老老实实干活”。

它适合三类人：第一类是 DevOps 或工程效能工程师，需要把它集成进 Jenkins/GitLab CI，在pre-merge阶段自动拦截明显问题；第二类是技术负责人或资深开发，想在本地git pull后快速扫一遍上游变更，提前预判兼容风险；第三类是开源项目维护者，面对海量外部 PR，需要一套可复现、可解释、不依赖特定云服务的审查辅助工具。它不承诺取代 Code Reviewer，但能把你从“找 for 循环里有没有 i++ 写成 i--”这种体力劳动里解放出来，把精力聚焦在“这个状态管理方案是否符合长期演进路线”这类真正需要经验判断的问题上。

2. 整体架构设计与核心思路拆解

2.1 为什么必须是 CLI 优先？而不是 Web UI 或 VS Code 插件？

很多人第一反应是：“既然用 LLM，那做个漂亮的 Web 界面，拖拽上传 diff 文件，点几下就出报告，多直观？”——这恰恰是 open-code-review 明确拒绝的方向。原因非常实际：代码审查的上下文永远绑定在 Git 工作区里，脱离这个环境的分析就是空中楼阁。举个真实例子：一个 PR 修改了src/utils/date.ts，新增了一个formatDuration(ms: number)函数。如果只给 LLM 看这个函数的 diff 片段，它可能夸你命名清晰、类型完整；但如果你把git log --oneline -n 3 src/utils/date.ts的历史拉出来，会发现这个文件过去两年只改过一次，且那次修改是为了修复时区计算 bug，而新函数里恰好复用了那个有 bug 的基础算法。这个关键信息，任何脱离 Git 历史的独立分析都无法获取。

CLI 的强制性带来了三个不可替代的优势：
第一，上下文保真。open-code-review启动时默认读取当前目录的.git，自动识别分支、提交哈希、远程 URL，甚至能解析.git/config里的core.autocrlf设置来预处理 diff 中的换行符差异。这些细节决定了 LLM 输入文本的准确性——比如 Windows 换行符\r\n在某些模型 tokenizer 里会被切分成两个 token，导致语义错乱。
第二，流水线友好。CI 环境里没有浏览器、没有 GUI、甚至没有$DISPLAY环境变量。一个curl就能下载安装的二进制 CLI，配合--no-interactive参数静默运行，输出 JSON 格式报告，后续管道直接接jq或python -m json.tool做聚合分析。我们线上 CI 用的就是这条链路：git diff origin/main...HEAD | open-code-review --ruleset=security --output-format=json | jq '.issues[] | select(.severity=="critical")'。
第三，安全边界清晰。Web UI 必然涉及前端 JS 加载、API 密钥管理、用户 session 控制；VS Code 插件则要申请workspace权限，可能读取整个项目文件。而 CLI 的权限模型极其简单：它只对当前git rev-parse --show-toplevel返回的路径有读取权，所有 LLM 请求都通过本地进程间通信（IPC）或明确指定的--llm-endpoint http://localhost:8000/v1/chat/completions发起，密钥绝不硬编码、不存配置文件、不进 Git 历史——这点后面会详细展开。

2.2 LLM 在这里扮演什么角色？不是“AI 审查员”，而是“规则增强器”

网络热词里频繁出现的 “LLM”、“agent”、“embedding” 容易让人误解：open-code-review 是不是要把整个 Code Review 流程交给大模型？答案是否定的。它的核心分层是：Git 层 → 规则层 → LLM 层 → 输出层，而 LLM 只在第二层规则触发后的“深度研判”环节介入。

具体来说：

• Git 层负责提供原始事实：哪些文件被修改（git diff --name-only）、每处修改的精确位置（git diff -U0的 hunk header）、变更前后的代码片段（git show HEAD~1:src/file.ts）、甚至关联的 commit message（git log -1 --pretty=%B）。
• 规则层是纯逻辑判断：用正则匹配硬编码密钥（/\b[A-Z]{2,}[0-9]{3,}\b/）、检测敏感文件提交（.env$|.pem$|.key$）、识别危险 API 调用（eval\(|setTimeout\([^)]*function\(）、验证 TypeScript 类型守卫（if (typeof x === 'string') { x.toUpperCase() }）。这部分完全离线、零延迟、100% 可控。
• LLM 层只在规则层标记出“疑似问题”后才启动：比如规则层发现fetch('/api/user', { method: 'POST', body: JSON.stringify(data) })，它不会直接报错，而是把这段代码、前后 5 行上下文、以及package.json里axios的版本号一起打包，问 LLM：“这个 fetch 调用是否缺少错误处理？请用 JSON 输出 {"has_error_handling": true/false, "suggestion": "..."}”。
• 输出层把规则层的确定性结论（如 “.env file detected in commit”）和 LLM 层的概率性建议（如{"has_error_handling": false, "suggestion": "Add try/catch or .catch() handler"}）合并，按 severity 分级输出。

这种设计直接规避了热词里反复出现的痛点：“使用 LLM 时如何防止密钥等鉴权信息泄露”。因为 LLM 永远看不到完整的.env文件——规则层一旦检测到.env被提交，立刻终止流程，直接报 critical 错误，根本不会把文件内容传给 LLM。同理，对于git diff输出中的密钥片段，我们在送入 LLM 前会做确定性脱敏：匹配AKIA[0-9A-Z]{16}这类 AWS Access Key 模式，替换成<REDACTED_AWS_KEY>，再把脱敏后的文本交给模型。这不是“信任模型不泄露”，而是“根本不给模型接触原始敏感数据的机会”。

2.3 为什么强调 “open”？不是开源许可证那么简单

“open-code-review” 的 open，首要含义是open to inspection（开放审查）。这意味着：

• 所有规则定义都放在rules/目录下的 YAML 文件里，比如security.yaml里写着：

- id: "hardcoded-api-key" description: "Detect hardcoded API keys in source code" pattern: "\\b(?i)(api[_-]?key|secret[_-]?key|token)\\s*[:=]\\s*[\"']([A-Za-z0-9+/]{32,})[\"']" severity: "critical" llm_enhancement: true

任何人 clone 仓库后，cat rules/security.yaml就能看清每条规则的触发条件、严重等级、是否启用 LLM 深度分析。

• 所有 LLM 请求的 payload 和 response 都可通过--debug-log参数记录到本地文件，格式为标准 JSON Lines：

{"timestamp":"2024-06-15T10:23:45Z","request":{"model":"deepseek-coder-33b","messages":[{"role":"user","content":"Analyze this fetch call..."}]},"response":{"choices":[{"message":{"content":"{\"has_error_handling\":false,...}"}]},"usage":{"prompt_tokens":128,"completion_tokens":42}}}

这让你能回溯每一次 LLM 调用，验证它是否真的按预期工作，而不是黑箱输出。

• 模型 endpoint 完全由用户指定：支持 OpenAI 兼容 API（如 Ollama、vLLM、Fireworks）、本地 GGUF 模型（通过 llama.cpp）、甚至自建的 FastChat 服务。没有 vendor lock-in，没有隐藏的 SaaS 调用。

这种 open，本质上是对“AI 辅助开发”工具的信任重建。当你的团队在代码里发现一个 LLM 建议的 bug 修复方案反而引入了竞态条件时，你能立刻打开rules/performance.yaml，找到对应规则，修改 prompt template，重新测试——而不是联系客服、等 patch、祈祷下次别出错。

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

3.1 Git 上下文提取：不只是git diff，而是构建代码快照

open-code-review 的第一步不是调 LLM，而是用 Git 构建一个精确的“变更快照”。很多同类工具只执行git diff，这会导致严重的信息丢失。比如：

• 如果一个 PR 删除了src/legacy/api.ts，git diff默认不显示被删文件的内容，但审查时你可能需要确认这个删除是否移除了关键的错误处理逻辑；
• 如果一个文件被重命名（git mv utils/date.js utils/time.js），git diff可能只显示新文件的添加，而忽略旧文件的删除，导致无法追溯逻辑迁移是否完整；
• 如果一个 commit 修改了package.json的dependencies，git diff只显示 JSON 行变化，但你需要知道这个变更是否引入了已知漏洞的库版本。

因此，open-code-review 的 Git 提取模块包含四个子步骤：

Step 1：确定变更范围
执行git diff --name-status origin/main...HEAD获取所有变更文件的状态（A/M/D/R/C/U），并过滤出非二进制、非忽略文件（尊重.gitignore）。对重命名文件（R100），额外执行git show HEAD~1:old/path > /tmp/old_content保存旧内容快照。

Step 2：提取精确 diff 块
不用git diff -U3（默认上下文 3 行），而是用git diff -U0获取无上下文的最小 diff，再用 Python 的difflib.SequenceMatcher自动扩展上下文至 5 行——但仅扩展到函数边界内。例如：

@@ -120,7 +120,7 @@ export function formatDate(date: Date) { - return date.toLocaleString(); + return date.toLocaleString('en-US');

会自动捕获export function formatDate(date: Date) {到下一个}之间的完整函数体，确保 LLM 理解修改发生在哪个作用域。

Step 3：关联元数据

• 从git log -1 --pretty=%B HEAD提取 commit message，用于判断意图（如 message 含 “fix security” 则提升 security 规则权重）；
• 用git ls-files --stage | grep '\.ts$'获取当前所有 TypeScript 文件列表，用于验证新增文件是否符合项目约定（如是否在src/下）；
• 解析git config --get remote.origin.url，若为git@gitlab.com:org/repo.git，则启用 GitLab 特定的 MR link 生成逻辑。

Step 4：构建安全沙箱
所有提取的代码片段、文件路径、commit hash 都经过严格校验：

• 路径必须以git rev-parse --show-toplevel返回的绝对路径为根，禁止../跳转；
• 文件内容读取前检查os.stat().st_size < 10MB，防止单个巨型文件阻塞流程；
• 对package.json等配置文件，只解析dependencies、devDependencies字段，忽略scripts等无关内容。

提示：实测发现，跳过 Step 1 的“变更范围确定”，直接对整个 repo 执行git diff，在大型 monorepo（如含 500+ package）中平均增加 3.2 秒延迟，且 78% 的 diff 内容与本次 PR 无关，徒增 LLM token 开销。务必让 Git 告诉你“到底改了什么”，而不是你自己猜。

3.2 规则引擎设计：YAML 驱动 + 正则 + AST 辅助

规则层是 open-code-review 的骨架，它必须足够灵活以覆盖不同语言，又足够轻量以保证毫秒级响应。我们采用三层混合策略：

第一层：纯正则匹配（占规则 65%）
适用于模式固定、无需语义理解的场景：

• 密钥检测：/\b(AKIA|A3T|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}\b/（AWS Access Key）；
• 敏感文件：/\.(env|pem|key|jks|keystore)$/i；
• 危险函数：/(eval|setTimeout|setInterval|Function|document\.write)\(/。
  正则优势在于速度（C 语言级），但弱点是易误报。因此我们加入“上下文白名单”：比如eval在测试文件（/test\/.*\.ts$/）中出现不报警，setTimeout在node_modules/下不触发。

第二层：AST 解析（占规则 25%）
针对 JavaScript/TypeScript，用@babel/parser构建 AST，精准定位：

• CallExpression中callee.name === 'fetch'且arguments.length >= 2但无.catch()链；
• VariableDeclarator中id.name为password且init.type === 'StringLiteral'；
• ImportDeclaration中source.value包含crypto-js但未使用AES.decrypt。
  AST 解析比正则慢 10-20 倍，所以只在正则命中后触发，且缓存 AST 结果供后续规则复用。

第三层：LLM 增强（占规则 10%，但覆盖 80% 的高价值场景）
仅用于正则和 AST 无法判定的模糊地带：

• “这个 React useEffect 依赖数组是否完整？”——需理解组件 state 和 props 的数据流；
• “这个 SQL 查询是否可能被注入？”——需结合参数绑定方式和 query string 拼接逻辑；
• “这个 error handling 是否覆盖所有分支？”——需追踪 try/catch 嵌套和 promise 链。
  每个 LLM 增强规则在 YAML 中定义prompt_template：

- id: "incomplete-useeffect-deps" prompt_template: | You are a senior React developer reviewing code changes. Given the following useEffect hook: {{hunk}} And the component's state declarations: {{state_declarations}} Does the dependency array [{{deps}}] include all variables that change during render? Answer strictly in JSON: {"complete": true/false, "missing": ["var1", "var2"]}

注意：LLM prompt 必须包含明确的角色设定（“You are a senior React developer”）、输入限定（“Answer strictly in JSON”）、且所有变量（{{hunk}}）都来自 Git 提取的确定性数据，绝不用 LLM 自己去“猜测”上下文。这是防止幻觉的关键。

3.3 LLM 集成安全实践：密钥隔离、输入脱敏、输出校验

网络热词里高频出现的 “llm 密钥泄露”、“prompt injection” 不是理论风险，而是真实踩过的坑。open-code-review 的 LLM 集成模块有三道硬防线：

防线一：密钥绝不落地

• 支持三种密钥管理方式：
  1. 环境变量：OPEN_CODE_REVIEW_API_KEY=sk-xxx，CLI 启动时读取，内存中使用，进程退出即销毁；
  2. 外部凭证服务：--llm-cred-source vault://my-vault-path，调用 HashiCorp Vault API 动态获取，响应有效期 5 分钟；
  3. 本地加密文件：--llm-cred-file ~/.config/open-code-review/creds.enc，用age工具加密，私钥存于 YubiKey。
• 绝对禁止：在 YAML 规则文件、CLI 命令历史、debug log 中记录明文密钥。所有日志中的密钥字段自动替换为sk-***abc。

防线二：输入强制脱敏
在 LLM 请求前，对所有文本执行确定性清洗：

• 正则替换密钥模式：re.sub(r'\b[A-Z]{2,}[0-9]{3,}\b', '<REDACTED_KEY>', text)；
• 替换邮箱：re.sub(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', '<REDACTED_EMAIL>', text)；
• 截断长文本：单次请求 token 限制 2048，超长代码块按函数边界截断，末尾加// ... truncated标记。
  关键原则：脱敏规则本身是公开的（在src/llm/sanitizer.py），任何人都可审计其有效性。

防线三：输出结构化校验
LLM 返回的 JSON 必须通过严格 schema 验证：

schema = { "type": "object", "properties": { "complete": {"type": "boolean"}, "missing": {"type": "array", "items": {"type": "string"}} }, "required": ["complete", "missing"] }

若验证失败（如返回"complete": "yes"字符串而非布尔值），则标记该规则为llm_failed，降级为人工 review，并记录错误详情。我们曾遇到某模型在 temperature=0.8 时返回"missing": "none"，触发校验失败，这直接暴露了模型输出不稳定的问题，促使我们后续强制设置temperature=0.1并添加重试机制。

实操心得：不要相信 LLM 的“自然语言回答”。我们早期用{"result": "Yes, deps are complete"}这种自由格式，结果 CI 流水线因 JSON 解析失败而中断。改成强制 schema 后，稳定性从 92% 提升到 99.8%。记住：LLM 是工具，不是同事，它需要被明确告知“你要交什么作业”。

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

4.1 从零安装与基础配置

open-code-review 的安装设计为“开箱即用，但可深度定制”。支持三种安装方式，按推荐顺序排列：

方式一：一键脚本安装（推荐新手）

# 下载并执行安装脚本（验证 SHA256 后自动安装） curl -sL https://github.com/open-code-review/cli/releases/download/v0.8.3/install.sh | bash # 脚本会： # 1. 检测系统（Linux/macOS/Windows WSL） # 2. 下载对应平台的二进制（arm64/x86_64） # 3. 校验签名（GPG key ID: 0xA1B2C3D4E5F67890） # 4. 安装到 /usr/local/bin/open-code-review # 5. 创建 ~/.config/open-code-review/config.yaml 示例

安装后，首次运行open-code-review --help会提示配置 LLM endpoint：

# 使用本地 Ollama 模型（需先 `ollama pull deepseek-coder:33b`） open-code-review config set llm.endpoint http://localhost:11434/v1/chat/completions open-code-review config set llm.model deepseek-coder:33b # 使用 OpenAI 兼容服务（如 Fireworks） open-code-review config set llm.endpoint https://api.fireworks.ai/inference/v1/chat/completions open-code-review config set llm.api_key sk-xxx # 仅内存存储

方式二：Docker 容器化（推荐 CI 环境）

# Dockerfile FROM python:3.11-slim RUN pip install open-code-review==0.8.3 COPY ./rules /app/rules WORKDIR /app CMD ["open-code-review", "--rules-dir", "/app/rules", "--output-format", "json"]

构建并运行：

docker build -t ocr-ci . docker run -v $(pwd):/workspace -w /workspace ocr-ci \ --git-root . --diff-stdin --ruleset security

方式三：源码编译（推荐深度定制者）

git clone https://github.com/open-code-review/cli.git cd cli make setup # 安装 Poetry, 依赖, pre-commit hooks make build # 编译二进制 sudo make install # 安装到 /usr/local/bin

源码结构清晰：

• src/git/：Git 上下文提取核心逻辑；
• src/rules/：YAML 规则加载与匹配引擎；
• src/llm/：请求构造、脱敏、校验、重试；
• src/output/：JSON/Markdown/Checkstyle 多格式输出。

注意：Windows 用户请务必使用 Git Bash 或 WSL2。原生 cmd.exe 对git diff的换行符处理不一致，会导致规则匹配失效。我们测试过 12 种 Windows 终端，只有 Git Bash 和 Windows Terminal + WSL2 组合能 100% 复现 Linux 行为。

4.2 本地 PR 审查实战：以一个真实 React PR 为例

假设你正在 review 一个 PR，修改了src/components/UserProfile.tsx，新增用户头像上传功能。让我们走一遍完整流程：

Step 1：进入 PR 分支，生成 diff

git checkout pr/avatar-upload git diff origin/main...HEAD > /tmp/pr.diff

Step 2：运行 open-code-review，聚焦 security 规则集

open-code-review \ --diff-file /tmp/pr.diff \ --ruleset security \ --llm-enhance \ --output-format markdown

Step 3：查看结构化输出
CLI 输出如下（精简版）：

## 🔍 open-code-review Report (v0.8.3) ### 📁 Changed Files - `src/components/UserProfile.tsx` (modified) ### ⚠️ Issues Found #### 1. Hardcoded API Key (critical) - **File**: `src/components/UserProfile.tsx` - **Line**: 42 - **Code**: `const UPLOAD_URL = "https://api.example.com/upload?token=abc123def456";` - **Rule**: `hardcoded-api-key` - **Action**: **BLOCK MERGE** - Remove hardcoded token. #### 2. Incomplete useEffect Dependencies (high) - **File**: `src/components/UserProfile.tsx` - **Line**: 88 - **Code**: ```tsx useEffect(() => { if (user) fetchAvatar(user.id); }, [user]); // ❌ missing `fetchAvatar` in deps

• Rule:incomplete-useeffect-deps
• LLM Analysis:{"complete": false, "missing": ["fetchAvatar"]}
• Suggestion: AddfetchAvatarto dependency array, or wrap in useCallback.

3. Missing Error Handling in Fetch (medium)

• File:src/components/UserProfile.tsx
• Line: 105
• Code:await fetch(UPLOAD_URL, { method: 'POST', body });
• Rule:fetch-without-error-handling
• LLM Analysis:{"has_error_handling": false, "suggestion": "Wrap in try/catch or add .catch()"}

✅ No issues found in other files

**Step 4：深度解读 LLM 建议的可靠性** 点击 `--debug-log` 生成的日志，找到对应请求： ```json { "request": { "messages": [ {"role": "system", "content": "You are a senior React developer..."}, {"role": "user", "content": "Given the following useEffect hook:\nuseEffect(() => {\n if (user) fetchAvatar(user.id);\n}, [user]);\nAnd the component's state declarations:\nconst [user, setUser] = useState<User | null>(null);\nconst fetchAvatar = useCallback((id) => {...}, []);\nDoes the dependency array [user] include all variables that change during render?"} ] }, "response": { "choices": [{"message": {"content": "{\"complete\": false, \"missing\": [\"fetchAvatar\"]}"}}], "usage": {"prompt_tokens": 156, "completion_tokens": 22} } }

看到fetchAvatar被声明为useCallback，且 deps 为空数组，说明它确实不会随 render 变化——但useEffect依赖它，就必须将其列入 deps，否则闭包会捕获旧的fetchAvatar。LLM 的判断完全正确。这证明了 LLM 增强的价值：正则无法理解useCallback的语义，AST 解析能识别函数声明但无法判断依赖关系，只有 LLM 能综合上下文给出准确结论。

4.3 CI 流水线集成：GitLab CI 示例

将 open-code-review 嵌入 CI 是发挥其最大价值的场景。以下是一个生产级 GitLab CI 配置：

# .gitlab-ci.yml stages: - review code-review: stage: review image: python:3.11-slim before_script: - pip install open-code-review==0.8.3 - git config --global user.email "ci@example.com" - git config --global user.name "CI Bot" script: # 1. 安装 LLM endpoint（Ollama） - curl -fsSL https://ollama.com/install.sh | sh - ollama pull deepseek-coder:33b # 2. 运行审查 - | open-code-review \ --git-root "$CI_PROJECT_DIR" \ --diff-stdin \ --ruleset security,performance \ --llm-enhance \ --output-format checkstyle \ --output-file /tmp/ocr-report.xml \ < <(git diff origin/main...HEAD) # 3. 解析报告，失败时上传 artifact - | if [ -s /tmp/ocr-report.xml ]; then echo "Found issues, uploading report..." artifacts: paths: [/tmp/ocr-report.xml] exit 1 else echo "No issues found." fi allow_failure: false only: - merge_requests

关键设计点：

• allow_failure: false：确保有 critical/high 问题时 pipeline 直接失败，阻止 merge；
• only: merge_requests：只在 MR 创建/更新时触发，避免污染其他 pipeline；
• artifacts上传：失败时把 Checkstyle XML 报告上传，GitLab 会自动解析并在 MR 页面高亮显示问题行；
• Ollama 本地部署：避免调用外部 API，保障审查速度（平均 8.3 秒/PR）和隐私。

实操心得：CI 中不要用--output-format markdown，因为 GitLab 无法渲染 Markdown artifact。坚持用checkstyle或json，它们是工业级工具的标准格式。我们曾因输出 markdown 导致 MR 页面显示乱码，花了 2 小时排查才意识到是格式问题。

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

5.1 LLM 请求失败：Connection refused / timeout

这是最常遇到的问题，根源往往不在模型本身，而在网络或配置。排查按此顺序进行：

检查 1：Endpoint 是否可达

# 测试基础连通性 curl -I http://localhost:11434/health # 应返回 HTTP/1.1 200 OK # 测试 API 兼容性 curl http://localhost:11434/v1/models # 应返回 JSON 包含 "models": [{"name":"deepseek-coder:33b", ...}]

检查 2：CLI 配置是否正确

open-code-review config get llm.endpoint # 确认输出是 http://localhost:11434/v1/chat/completions，不是 http://localhost:11434/ open-code-review config get llm.model # 确认模型名与 `ollama list` 输出一致

检查 3：Ollama 是否在运行且模型已加载

# 查看 Ollama 日志 journalctl -u ollama -n 50 --no-pager # 寻找 "serving request" 或 "error loading model" # 手动加载模型（有时自动加载失败） ollama run deepseek-coder:33b # 在交互式 shell 中输入 "hi"，看是否响应

检查 4：资源是否充足
Ollama 默认使用 CPU，33B 模型需至少 16GB RAM。监控命令：

# 实时查看内存占用 watch -n 1 'free -h | grep Mem' # 查看 Ollama 进程 ps aux | grep ollama | grep -v grep # 若 RES 列 > 12G，说明内存吃紧

解决方案：

• 降低模型尺寸（ollama pull deepseek-coder:1.3b）；
• 增加 swap：sudo fallocate -l 8G /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile；
• 改用 GPU：OLLAMA_NUM_GPU=1 ollama run deepseek-coder:33b（需 NVIDIA 驱动）。

独家技巧：在 CI 中，我们用timeout 30s ollama run deepseek-coder:33b --verbose启动模型，30 秒内未响应则自动 fallback 到 smaller 模型。这避免了 pipeline 因模型加载慢而卡死。

5.2 规则误报：为什么我的合法代码被标为 “hardcoded-api-key”？

正则匹配的误报是规则引擎的固有挑战。典型场景：

场景 1：测试数据中的假密钥

// src/__tests__/api.test.ts test("should handle invalid token", () => { const fakeToken = "AKIAEXAMPLEKEY123456"; expect(validateToken(fakeToken)).toBe(false); });

解决：在rules/security.yaml中添加白名单：

- id: "hardcoded-api-key" # ... 其他字段 exclude_paths: [".*__tests__/.*\\.ts$", ".*test/.*\\.js$"]

场景 2：Base64 编码的密钥片段

const encoded = "QWtpYUJhbmsxMjM0NTY3ODk="; // "AKIABank123456789" 的 base64

解决：增强正则，添加 base64 检测：

pattern: "\\b(?i)(api[_-]?key|secret[_-]?key|token)\\s*[:=]\\s*[\"']([A-Za-z0-9+/]{32,})[\"']|([A-Za-z0-9+/]{32,}={0,2})"

**场景 3：动态生成的密钥（如