企业官网建设流程全解析

1. “open-code-review”不是个工具名，而是一类新型代码评审范式的代号

你点开 GitHub Trending，或者刷到某篇技术推文里提到“我们上线了 open-code-review 流程”，第一反应可能是——这又是个新开源的 CLI 工具？是不是要 pip install open-code-review？是不是像 pre-commit 那样配个 .pre-commit-config.yaml 就能跑起来？

不是。

我去年在三个不同规模的团队里推动过类似实践，从 8 人初创公司到 200+ 人的中台研发组，最后都放弃了“找一个叫 open-code-review 的工具来装”的思路。因为根本不存在这样一个统一命名、开箱即用的标准化产品。“open-code-review”这个词，本质上是社区对一类以开放性、可编程性、上下文感知为内核的代码评审新范式的集体指称——它不绑定某个品牌，不依赖某家大模型 API，也不强制要求你用特定 CLI。它描述的是：当代码变更（git diff）不再只是被人工 eyeball，而是被结构化地喂给可配置的智能体（Agent），由这些 Agent 在预设规则下完成语义理解、风险识别、风格校验、文档补全甚至跨 PR 关联分析，并将结果以人类可读、可追溯、可审计的方式沉淀进评审流中，整个过程对团队可见、可干预、可迭代。

这个定义里藏着四个关键词，也是你判断一个方案是否真属“open-code-review”范畴的核心标尺：

• Open：不是黑盒 SaaS 评审插件（比如点一下就弹出 AI 建议但看不到提示词、不暴露模型调用链、无法替换底层模型）。它必须允许你查看、修改、版本化评审逻辑本身——无论是 YAML 规则集、Python Hook 脚本，还是 LLM Agent 的 system prompt 模板。

• Code：评审对象必须锚定在真实、原子的代码变更上，而非笼统的“PR 描述”或“commit message”。它要能解析 git diff 的 hunk 级别上下文，识别出if (x == null)这种空指针隐患，也能定位// TODO: refactor this这种技术债标记，并关联到具体行号和文件路径。

• Review：不是单向生成建议，而是构建双向反馈闭环。它要支持人工 override（比如驳回某条 AI 提示）、支持评论线程嵌套（AI 建议 → 开发者回复 → AI 追问）、支持状态标记（“已确认”“需验证”“已忽略”），最终输出物必须能无缝嵌入 GitHub/GitLab 的原生评论区，而非另起一个悬浮窗。

• -（短横线）：这个符号常被忽略，但它恰恰是分水岭。它代表“解耦”与“组合”。真正的 open-code-review 架构里，diff 解析器、上下文提取器、LLM 调度器、规则引擎、输出渲染器，都是可插拔组件。你可以用 ripgrep 提取敏感词，用 tree-sitter 解析 AST，用 Ollama 本地跑 Qwen，用自研规则引擎做合规检查——只要它们通过标准输入（stdin）接收 diff 文本，通过标准输出（stdout）返回 JSON 格式建议，就能组装成你的 open-code-review 流水线。

所以，当你看到“open-code-review”这个词，别急着搜 npm 或 brew。先问自己三个问题：

1. 我想让机器看懂的，是“这段代码改了什么”，还是“这个人写了什么”？
2. 我希望评审逻辑是藏在云服务后台的魔法，还是躺在我仓库根目录下的.review-rules.yaml里？
3. 当某条 AI 建议出错时，我是只能点“忽略”，还是能打开prompt_templates/security-audit.jinja文件，把“请检查 SQL 注入风险”改成“请检查 MyBatis#{}与${}的混用风险”？

这三个问题的答案，决定了你是在用工具，还是在构建自己的评审操作系统。而后者，才是 open-code-review 的真正起点。

2. 为什么现有 CLI 工具（codex cli / zcode cli / claude cli）无法直接支撑 open-code-review？

市面上突然冒出一堆带 “cli” 后缀的工具名：codex cli、zcode cli、claude code cli、trae cli……它们名字响亮，安装命令也简洁（npm install -g codex-cli），文档首页就写着“一键接入 AI 代码评审”。但我在实际落地中发现，90% 的团队在试用三天后就停用了——不是因为效果差，而是因为它们和 open-code-review 的核心诉求存在结构性错位。这种错位，体现在四个不可绕过的硬伤上。

2.1 硬伤一：CLI 是入口，却不是管道——它不接受标准输入，只认文件路径

所有真正能融入工程流水线的 CLI 工具，必须遵循 Unix 哲学：接受 stdin 输入，输出 stdout 结果，错误走 stderr。这样你才能写git diff HEAD~1 | codex-cli review，或者在 pre-commit hook 里写cat $1 | zcode-cli scan。

但现实是，绝大多数所谓“code review CLI”根本不吃管道流。以 codex cli 为例，它的典型用法是：

codex-cli review --pr-url https://github.com/org/repo/pull/123

或者：

codex-cli review --files src/main/java/com/example/Service.java test/

这意味着什么？意味着它必须自己去 Git 服务器拉取完整 PR 数据，自己解析 diff，自己拼接上下文。它完全脱离了你本地已有的 git diff 流程。当你想在 CI 中做增量扫描（只扫本次 commit 修改的文件），它做不到；当你想在 pre-commit 阶段拦截高危修改（比如新增了System.exit(0)），它更做不到——因为 pre-commit hook 里根本没有--pr-url这种东西。

提示：真正的 open-code-review CLI 必须支持cat diff.patch | your-cli --format=diff。如果你看到的 CLI 文档里连--stdin参数都没有，直接划走。这不是功能缺失，而是设计哲学的背离。

2.2 硬伤二：模型绑定死，无法切换——deepseek、qwen、本地 ollama 全部被拒之门外

热词里反复出现“deepseek 是 agent 还是 LLM？”“codex cli 支持 claude 吗？”。这个问题本身就暴露了误区：open-code-review 不需要你选“哪个模型更好”，而是要你选“哪个模型更适合我的场景”。

• 安全合规强的团队，需要模型能理解《金融行业代码安全规范》，这时候闭源模型（如 Claude）可能因知识盲区漏报；
• 基础设施弱的团队，需要离线运行，这时候必须用 7B 量级的 Qwen2.5-Coder 在 24G 显存上跑；
• 做嵌入式开发的团队，需要模型熟悉 Keil C 语法和寄存器映射，通用大模型根本没见过__attribute__((section(".isr_vector")))这种写法。

但 codex cli 的架构是：CLI → 固定 API Endpoint（如https://api.codex.dev/v1/review）→ 固定模型（如 gpt-4-turbo）。你无法把它的请求转发到你自建的 vLLM 服务，也无法在 prompt 里注入你私有的 C 语言安全规则库。它的--model参数只支持gpt-4,claude-3-haiku这几个字符串，背后没有模型路由层，没有 adapter 抽象，没有 embedding cache 控制。

我试过用 mitmproxy 拦截 codex cli 的请求，想把它重定向到本地 Ollama，结果发现它用的是 WebSocket 长连接 + 二进制协议，连 request body 都是加密的。这不是技术难度问题，而是商业模型决定的：它要确保你永远离不开它的云服务。

2.3 硬伤三：规则黑盒化——你无法定义“什么是高危修改”，只能接受它的判断

open-code-review 的灵魂，在于“评审标准可编程”。比如，你团队约定：

• 所有日志打印必须包含 traceId；
• 新增的@Scheduled方法必须有熔断注解；
• Thread.sleep()调用必须附带 Javadoc 说明超时依据。

这些规则，应该用 YAML 写成：

# .review-rules.yaml rules: - id: "log-missing-traceid" description: "日志语句未携带 traceId 上下文" pattern: 'logger\.(info|warn|error)\([^)]*[^traceId][^)]*\)' severity: "critical" fix: "在日志参数中添加 MDC.get('traceId')" - id: "scheduled-no-circuit-breaker" description: "定时任务方法未配置熔断保护" pattern: '@Scheduled.*\n\s*public void [^(]+' severity: "high" context: "java-annotation"

但 codex cli 没有--rules参数，zcode cli 的规则配置藏在 Web 控制台里，trae cli 的规则引擎是付费模块。它们的“智能”来自云端训练好的分类器，而不是你本地可调试的规则集。当你发现它把Thread.sleep(1000)判为低危，而你认为这是分布式锁超时风险时，你只能提工单，等他们下一个季度更新模型——而不是打开编辑器，加一行正则。

2.4 硬伤四：输出不可审计——JSON 结构不标准，无法被下游系统消费

一个 open-code-review 输出，必须能被其他系统消费：CI 系统要根据 severity 字段决定是否阻断构建；代码质量平台要聚合critical数量生成周报；IDE 插件要解析file/line/suggestion渲染内联提示。

这就要求输出是稳定、标准的 JSON Schema。比如：

{ "review_id": "rev_abc123", "timestamp": "2024-06-15T10:22:33Z", "findings": [ { "rule_id": "log-missing-traceid", "file": "src/main/java/com/example/OrderService.java", "line": 47, "column": 12, "message": "日志语句未携带 traceId 上下文", "severity": "critical", "suggestion": "logger.info(\"order created, traceId={}\", MDC.get('traceId'));" } ] }

但 claude code cli 的输出是 Markdown 格式文本，codex cli 的输出是带 HTML 标签的富文本，zcode cli 的输出是自定义二进制协议。我写了个 Python 脚本试图解析它们的 stdout，结果发现：

• codex cli 的 JSON 里line字段有时是数字，有时是字符串"47"；
• trae cli 的severity字段值是"HIGH"、"medium"、"Critical"混用；
• claude cli 的输出里甚至包含 emoji（⚠️），导致 JSON 解析直接失败。

注意：任何不提供--output-format=json且不承诺字段稳定性（如 line 总是 int）的 CLI，都不具备工程集成价值。它或许能当玩具，但绝不能进你的 CI 流水线。

这四点硬伤，不是 bug，而是设计选择。它们服务于一个目标：让你留在他们的生态里。而 open-code-review 的目标，恰恰相反——让你彻底掌控评审的每一个环节。所以，别再浪费时间配置这些 CLI 的 token 和 webhook，转头去构建真正属于你的评审管道。

3. 从零搭建 open-code-review 管道：一个可落地的最小可行架构

既然现成的 CLI 工具走不通，那 open-code-review 到底怎么搭？别被“LLM Agent”“embedding”这些词吓住。我给你拆解一个已在生产环境跑了一年的最小可行架构（MVP），它只有 3 个核心组件，全部开源、可本地运行、总代码量不到 500 行，却能覆盖 80% 的日常评审需求。

这个架构不追求“全自动”，而是聚焦“可解释、可干预、可审计”——所有决策都有迹可循，所有建议都可被人工覆盖，所有输出都符合标准 JSON Schema。

3.1 组件一：diff 解析器 —— 用 ripgrep + jq 构建轻量级上下文提取器

评审的起点，永远是 git diff。但 raw diff 太“薄”，缺乏语义。我们需要从中提取：

• 修改了哪些文件？
• 每个文件里，修改发生在哪个函数/类/方法内？
• 新增/删除的代码行，其前后 3 行上下文是什么？

很多人第一反应是写 Python 脚本解析 diff。但更简单、更可靠、更 Unix 的方式是：用 ripgrep 提取 AST 级别上下文，用 jq 做结构化转换。

第一步：安装 ripgrep（rg）和 jq

# macOS brew install ripgrep jq # Ubuntu sudo apt install ripgrep jq

第二步：创建extract-context.sh，它接收 git diff 输出，返回结构化 JSON：

#!/bin/bash # extract-context.sh # Usage: git diff HEAD~1 | ./extract-context.sh # 1. 提取所有修改的 .java 文件路径 FILES=$(rg -o 'diff --git a/(.*) b/\1' | cut -d' ' -f4 | sort -u) # 2. 对每个文件，用 rg 提取修改行附近的函数名（基于 Java 语法） for FILE in $FILES; do if [[ -f "$FILE" ]]; then # 获取所有被修改的行号（+ 开头的行） LINES=$(git diff HEAD~1 -- "$FILE" | grep '^+' | grep -v '^\+\+\+' | awk '{print NR}' | head -n 20) for LINE in $LINES; do # 用 rg 向上搜索最近的 public/private/protected 修饰符，定位函数 FUNC=$(rg -U -A 5 -B 5 "^(public|private|protected).*void|String|List|Map" "$FILE" 2>/dev/null | rg -B 10 "^\s*$LINE:" | head -n 1 | sed 's/^[[:space:]]*//') if [[ -n "$FUNC" ]]; then echo "{\"file\":\"$FILE\",\"line\":$LINE,\"function\":\"$FUNC\"}" fi done fi done | jq -s '.'

这个脚本干了什么？它不解析 AST，而是用文本模式匹配逼近语义。实测下来，对 Java/Go/Python 的函数定位准确率超 92%。关键在于：它输出是标准 JSON，字段固定（file/line/function），下游可直接消费。

实操心得：别追求 100% 准确。在 open-code-review 里，“快速给出 90% 可用的上下文”远比“等待 10 秒得到 100% 准确的 AST”有价值。工程师看建议时，第一眼关注的是“改了哪个文件、哪一行”，函数名只是辅助定位。这个脚本 0.3 秒就跑完，而用 tree-sitter 解析整个文件要 2 秒。

3.2 组件二：评审引擎 —— 用 Ollama + 自定义 Prompt 实现规则驱动的 LLM 调用

有了上下文，下一步是“让模型看懂并判断”。这里不用 fancy 的 Agent 框架，就用最朴素的 curl + Ollama。

前提：你已安装 Ollama，并拉取了适合代码的模型（推荐qwen2.5-coder:7b，它在代码理解任务上超越多数 13B 模型，且 7B 量级可在 24G 显存笔记本上流畅运行）：

ollama pull qwen2.5-coder:7b

核心是review-prompt.jinja模板（Jinja2 格式，便于变量注入）：

你是一名资深 Java 安全工程师，正在执行代码评审。请严格按以下规则分析： 1. 只针对用户提供的 diff 片段，不假设其他代码； 2. 每条发现必须包含：file（文件路径）、line（行号）、message（问题描述）、severity（critical/high/medium/low）、suggestion（修复建议）； 3. 问题类型仅限：空指针风险、SQL 注入、硬编码密钥、日志敏感信息、并发安全、资源泄漏； 4. 如果无问题，返回空数组 []。 待评审 diff： {{ diff }} 上下文（当前修改所在函数）： {{ function_context }}

然后是run-review.sh脚本，它把 diff 和上下文喂给 Ollama：

#!/bin/bash # run-review.sh # Usage: ./run-review.sh <diff.json> DIFF_JSON=$1 CONTEXT=$(jq -r '.[0].function' "$DIFF_JSON") # 取第一个修改的函数上下文 DIFF_TEXT=$(git diff HEAD~1 | grep -E '^\+|^-') # 构造 prompt PROMPT=$(cat review-prompt.jinja | envsubst "DIFF_TEXT=$DIFF_TEXT FUNCTION_CONTEXT=$CONTEXT") # 调用 Ollama，强制输出 JSON curl -s http://localhost:11434/api/chat \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2.5-coder:7b", "messages": [{"role": "user", "content": "'"$PROMPT"'"}], "stream": false, "options": {"temperature": 0.1} }' | jq -r '.message.content' | jq -s '.'

这个脚本的关键设计：

• 温度（temperature）设为 0.1：极大降低幻觉，确保输出格式稳定；
• 用envsubst注入变量：避免 shell 字符串拼接导致的引号逃逸问题；
• jq -s '.'强制输出为数组：无论模型返回单条还是多条，都归一为 JSON Array。

实测中，qwen2.5-coder 对if (user != null && user.getName() != null)这种嵌套空指针判断准确率 98%，且能精准定位到user.getName()这一行，而非整个 if 语句块。

3.3 组件三：输出适配器 —— 用 Python 脚本清洗并标准化 JSON 结构

Ollama 返回的是自然语言，不是 JSON。我们需要一个“翻译器”，把模型说的“第 47 行有空指针风险”转成标准 JSON：

# normalize-output.py import sys import json import re def parse_llm_output(text): """将 LLM 的自然语言输出解析为标准 JSON""" findings = [] # 匹配模式：file: xxx.java, line: 47, issue: 空指针风险, suggestion: ... pattern = r'file:\s*(\S+),\s*line:\s*(\d+),\s*issue:\s*(.+?),\s*suggestion:\s*(.+?)(?=\nfile:|\Z)' matches = re.findall(pattern, text, re.DOTALL) for match in matches: file, line, issue, suggestion = match # 映射 severity severity = "medium" if "空指针" in issue or "SQL 注入" in issue or "硬编码密钥" in issue: severity = "critical" elif "日志" in issue or "并发" in issue: severity = "high" findings.append({ "file": file.strip(), "line": int(line.strip()), "message": issue.strip(), "severity": severity, "suggestion": suggestion.strip() }) return findings if __name__ == "__main__": input_text = sys.stdin.read() findings = parse_llm_output(input_text) print(json.dumps({"review_id": "local_" + str(hash(input_text))[:8], "timestamp": "2024-06-15T10:22:33Z", "findings": findings}, indent=2))

这个脚本的价值在于：它把不可控的 LLM 输出，变成了可控的结构化数据。你随时可以调整正则表达式，适配不同模型的输出风格（比如 Claude 喜欢用 Markdown 表格，你就加一个表格解析分支）。

3.4 串联三组件：一条命令完成端到端评审

现在，把三个组件串起来：

# 完整评审命令 git diff HEAD~1 | ./extract-context.sh | ./run-review.sh | python normalize-output.py

输出示例：

{ "review_id": "local_abc123", "timestamp": "2024-06-15T10:22:33Z", "findings": [ { "file": "src/main/java/com/example/OrderService.java", "line": 47, "message": "空指针风险：user.getName() 调用前未校验 user 是否为 null", "severity": "critical", "suggestion": "在调用 getName() 前添加 if (user != null) 判断" } ] }

这个输出，可直接：

• 被 CI 脚本读取，jq '.findings[] | select(.severity == "critical")'判断是否阻断构建；
• 被 VS Code 插件解析，在编辑器里高亮显示；
• 被飞书机器人消费，自动发到团队群：“检测到 critical 问题，详见 PR #123”。

关键经验：不要一开始就追求“完美 Agent”。先让git diff | ... | ... | ...这条管道跑通，哪怕第一版只识别空指针。跑通后，你再逐个升级组件：把 ripgrep 换成 tree-sitter，把 qwen 换成 deepseek-coder，把正则解析换成 LLM 的 JSON mode。每一步都可验证、可回滚。这才是工程化的 open-code-review。

4. 规则即代码：如何用 YAML 定义你的团队专属评审标准

open-code-review 的终极形态，不是“用 AI 替代人”，而是“把人的经验，变成可执行、可传播、可演进的代码”。这背后的核心载体，就是规则文件（Rule as Code）。它不是配置项，而是你团队技术共识的活文档。

我见过太多团队把评审规则写在 Confluence 里，标题是《Java 安全编码规范 V3.2》，内容是 50 页 PDF。结果呢？新人入职没人看，老员工凭记忆，PR 评审时各执一词。而规则即代码，意味着：

• 规则写在.review-rules.yaml里，和代码一起提交、一起 Review、一起发布；
• 每条规则有唯一 ID、有明确触发条件（pattern）、有 severity 等级、有自动修复建议（fix）；
• 规则可被 CLI 加载，也可被 IDE 插件实时校验，还可被测试框架验证（“这条规则是否真的能捕获测试用例中的漏洞？”）。

下面，我以一个真实场景为例，展示如何从模糊的“团队约定”，落地为可执行的 YAML 规则。

4.1 场景还原：我们团队的“日志必须带 traceId”约定

背景：我们做微服务，所有请求通过网关注入 traceId 到 MDC。但新人常忘记在日志里打印，导致问题排查困难。之前靠 Code Review 人工提醒，漏检率高。

旧做法：在 Confluence 写：“日志语句必须包含 MDC.get('traceId')”。
问题：太抽象。logger.info("order created")算不算违规？logger.info("order created, traceId={}", MDC.get('traceId'))算不算合规？没定义。

新做法：写成 YAML 规则：

# .review-rules.yaml version: "1.0" rules: - id: "log-missing-traceid" name: "日志语句未携带 traceId" description: "所有 logger.info/warn/error 调用必须在参数中包含 MDC.get('traceId')" severity: "critical" languages: ["java"] pattern: | (?i)logger\.(info|warn|error)\([^)]*[^traceId][^)]*\) # 正则详解： # (?i) 忽略大小写 # logger\.(info|warn|error) 匹配 logger.info 等 # \([^)]* 匹配左括号后任意非右括号字符 # [^traceId] 确保此处不出现 'traceId' 字符串（注意：这是简化版，实际用更精确的 negative lookahead） # [^)]*\) 匹配剩余参数直到右括号 fix: | 在日志参数中添加 MDC.get('traceId')，例如： logger.info("order created, traceId={}", MDC.get('traceId')); examples: - bad: "logger.info(\"order created\");" - good: "logger.info(\"order created, traceId={}\", MDC.get('traceId'));"

这个规则的关键设计点：

• pattern是可测试的：你可以在 regex101.com 上粘贴正则，用测试用例验证。logger.info("order created")应该匹配，logger.info("order created, traceId={}", MDC.get('traceId'))不应匹配。
• fix是可复制的：不是“请添加 traceId”，而是给出完整、可粘贴的代码片段。
• examples是可教育的：新人看一眼就知道什么算错、什么算对。

4.2 如何让规则生效？—— 用 ripgrep 直接执行规则扫描

有了规则文件，怎么让它动起来？不需要新工具，就用你 already have 的 ripgrep。

创建run-rules.sh：

#!/bin/bash # run-rules.sh # Usage: ./run-rules.sh RULES_FILE=".review-rules.yaml" # 用 yq 解析 YAML，提取所有 pattern PATTERNS=$(yq e '.rules[] | select(.languages[] == "java") | .pattern' "$RULES_FILE" | sed 's/^"//' | sed 's/"$//') # 对每个 pattern，用 rg 扫描所有 java 文件 while IFS= read -r PATTERN; do if [[ -n "$PATTERN" ]]; then # rg -l 列出匹配文件，-n 显示行号，-o 显示匹配内容 rg -l -n -o "$PATTERN" --glob "*.java" 2>/dev/null | while IFS=: read -r FILE LINE CONTENT; do # 从 rules.yaml 中查出对应 rule 的 id 和 description RULE_ID=$(yq e ".rules[] | select(.pattern | test(\"$PATTERN\")) | .id" "$RULES_FILE") DESCRIPTION=$(yq e ".rules[] | select(.pattern | test(\"$PATTERN\")) | .description" "$RULES_FILE") echo "{\"file\":\"$FILE\",\"line\":$LINE,\"rule_id\":\"$RULE_ID\",\"message\":\"$DESCRIPTION\",\"severity\":\"critical\"}" done fi done <<< "$PATTERNS" | jq -s '.'

这个脚本做了什么？它把 YAML 规则，编译成了 ripgrep 命令。yq是 YAML 专用的 jq，rg是文本搜索的王者。两者结合，实现了“规则即代码”的最简实现：规则写在 YAML 里，执行靠 shell，结果是标准 JSON。

运行它：

./run-rules.sh

输出：

[ { "file": "src/main/java/com/example/OrderService.java", "line": 47, "rule_id": "log-missing-traceid", "message": "所有 logger.info/warn/error 调用必须在参数中包含 MDC.get('traceId')", "severity": "critical" } ]

4.3 进阶：规则组合与优先级——当多条规则同时命中同一行

现实场景更复杂。比如，同一行logger.info("password=" + pwd);可能同时触发：

• log-missing-traceid（没打 traceId）
• log-sensitive-data（日志打印密码）
• string-concat-password（字符串拼接敏感字段）

这时，你需要规则优先级。YAML 里加priority字段：

rules: - id: "log-sensitive-data" priority: 10 # 最高优先级，先执行 ... - id: "log-missing-traceid" priority: 5 # 次之 ... - id: "string-concat-password" priority: 1 # 最低

run-rules.sh改成按 priority 排序执行，确保高危规则先被发现。你甚至可以加stop_on_first_match: true，让一条 critical 规则命中后，不再检查其他规则——这符合“安全评审宁可误报，不可漏报”的原则。

实操心得：规则即代码的最大价值，不是自动化，而是可审计性。当某次 PR 被阻断，你打开 CI 日志，能看到清晰的链条：git diff → extract-context → run-rules → finding: log-sensitive-data。你能立刻定位是规则写错了，还是代码真有问题。而闭源 CLI 的日志只有一行API call failed，你永远不知道是网络问题、token 过期，还是模型把pwd误判为普通变量。

5. 落地避坑指南：那些只有踩过才知道的 open-code-review 真实陷阱

我帮 7 个团队落地 open-code-review，平均每个团队踩过 3 个以上重大坑。有些坑看起来很小，比如“模型输出偶尔多一个空格”，但放到 CI 里就是构建失败；有些坑很隐蔽，比如“本地测试 OK，CI 里报错”，查了两天才发现是时区问题。我把这些血泪教训，浓缩成 5 条必须写进你团队 Wiki 的避坑守则。

5.1 陷阱一：LLM 的“自信幻觉”——它总爱编造不存在的行号和文件名

这是最危险的坑。LLM 在不确定时，不会说“我不知道”，而是会自信地编一个看似合理的答案。比如，你给它一段 diff：

+ public void processOrder(Order order) { + // TODO: add validation + save(order); + }

它可能回复：

{ "file": "src/main/java/com/example/OrderService.java", "line": 47, "message": "TODO 注释未被处理", "severity": "medium" }

但实际processOrder方法在OrderController.java里，行号是 123，不是 47。如果下游系统直接用这个line去高亮，就会误导开发者。

破解方案：永远用 diff 的原始行号，而不是 LLM 的“推测”行号。
在run-review.sh里，不要让 LLM 输出line，而是让它输出hunk_id（diff 的块编号），然后用git apply --recount或patchutils工具，把 hunk_id 映射回真实行号。或者更简单：在传给 LLM 的 prompt 里，强制要求它“只使用 diff 中明确写出的行号，禁止推测”。并在normalize-output.py里加校验：

# 如果 LLM 输出的 line 不在 diff 的实际行号范围内，直接丢弃 actual_lines = get_actual_lines_from_diff(diff_text) # 你自己实现的函数 if finding["line"] not in actual_lines: continue # 跳过这条伪造的发现

经验：第一次上线时，我让实习生手动抽查了 100 条 LLM 输出，发现 12% 的line字段是错的。加了这行校验后，误报率归零。

5.2 陷阱二：上下文丢失——LLM 只看到 diff，看不到 import 和 class signature

LLM 看 diff，就像医生只看化验单，不看病历。它不知道User类是否实现了Serializable，不知道save(order)方法是否有事务注解，不知道Order对象的getId()是Long还是String。

这导致大量误报。比如，if (order.getId() != null)被判为空指针风险，但其实getId()是long基本类型，不可能为 null。

破解方案：在 prompt 里，强制注入关键上下文。
用 ripgrep 提取import语句和类声明：

# 在 extract-context.sh 里追加 IMPORTS=$(rg "^import " "$FILE" | head -n 10) CLASS_DECL=$(rg "^public class |^public interface " "$FILE" | head -n 1) echo "{\"file\":\"$FILE\",\"line\":$LINE,\"imports\":\"$IMPORTS\",\"class_decl\":\"$CLASS_DECL\"}"

然后在review-prompt.jinja里加上：

当前文件导入了以下包： {{ imports }} 当前类声明为： {{ class_decl }} 请结合以上信息判断。

实测效果：空指针误报率从 35% 降到 7%。

5.3 陷阱三：CI 环境差异——本地跑得飞快，CI 里 timeout

本地用 Ollama，GPU 直连，响应 200ms。CI 用 CPU 运行 llama.cpp，响应 15 秒。而 GitHub Actions 默认 timeout 是 60 秒，一旦超时，整个构建失败。

破解方案：双模运行 + fallback 机制。
在run-review.sh里加检测：

if command -v ollama &> /dev/null; then # 本地：用 ollama curl http://localhost:114