企业官网建设流程全解析

1. 项目概述：这不是一个“工具”，而是一套可落地的代码审查工作流重构方案

“open-code-review”这个名字乍看像某个开源项目仓库名，但结合当前搜索热词里高频出现的CLI、LLM、git、code review四个关键词，再叠加“codex cli”“zcode cli”“trae cli”“vs code gemini cli companion”等具体工具名反复交叉出现，我立刻意识到——这根本不是在问某个现成软件怎么用，而是在描述一个正在快速成型的新型开发范式：把大语言模型（LLM）深度嵌入到 Git 工作流中，以命令行（CLI）为统一入口，实现自动化、上下文感知、可审计、可复现的代码审查闭环。我从去年底开始在三个不同规模的团队里落地这套方案，从最初用 shell 脚本硬调curl发请求，到现在稳定运行在 CI/CD 流水线里每天自动扫描 200+ PR，核心就围绕这四个字展开：open、code、review。这里的 “open” 不是指开源协议，而是指开放接口、开放上下文、开放决策过程——所有 LLM 的输入 prompt、原始 diff、生成的 review comment、甚至 token 消耗和响应延迟，全部结构化输出、可追溯、可重放。它解决的不是“能不能让 AI 看代码”这个伪命题，而是“如何让 AI 的审查意见真正被工程师信任、被流程接纳、被质量体系验证”。适合两类人重点参考：一是正在搭建内部 DevOps 平台的 SRE 或平台工程师，你需要的是可集成、可管控、可审计的模块；二是日常要写大量 CR（Code Review）的资深开发，你缺的不是更多功能按钮，而是能帮你聚焦关键风险、自动补全检查项、把重复劳动压缩掉 70% 的“审查搭档”。它不替代人，但会彻底改变你打开 GitHub/GitLab 页面后第一眼要看什么、第二步要做什么。

2. 整体设计思路：为什么必须绕开 IDE 插件和 Web UI，死磕 CLI？

2.1 核心矛盾：LLM 审查的“可信度鸿沟”与工程流程的“确定性刚需”

我见过太多团队踩坑：花两周接入某款 VS Code 插件，AI 能高亮出潜在空指针，但当它建议“此处应加 try-catch”时，工程师第一反应是“它知道我们服务的熔断超时是 800ms 吗？知道这个方法被下游三个核心链路强依赖吗？”——LLM 的泛化能力越强，其在具体工程语境下的可信度反而越低。这不是模型问题，是信息断层问题。IDE 插件看到的只是当前文件片段，Web UI 界面里展示的 review comment 是孤立的文本气泡，它们天然缺失三个关键上下文：1）本次提交完整的 git diff（含删减行）；2）关联的 Jira Issue 或 PR 描述里的业务目标；3）该代码路径在历史 commit 中的变更密度与缺陷率。而 CLI 方案从设计第一天起，就把这三者作为 mandatory input。比如我们定义的最小执行单元不是open-code-review --file UserService.java，而是open-code-review --pr-url https://gitlab.example.com/proj/backend/-/merge_requests/12345。命令执行时，CLI 会自动拉取：① MR 的完整 diff（通过 GitLab API）；② MR 描述中的Resolves #BUG-789字样，并查询 Jira 获取该 issue 的优先级、影响范围标签、关联的测试用例 ID；③ 查询数据库，拿到UserService.java这个文件过去 90 天内被修改过 17 次，其中 5 次关联线上告警。这些数据不是装饰，而是 LLM prompt 的前置条件。当模型输出“建议增加参数校验”时，背后已注入了“该方法近半年引发 3 次 5xx 错误，且本次修改涉及新增对外 HTTP 调用”的事实锚点。这种设计让 AI 的建议从“可能有用”变成“有依据可查”。

2.2 架构选型：为什么拒绝封装成黑盒服务，坚持“CLI + 配置即代码”？

市面上已有不少商业 code review SaaS，它们把 LLM 封装成 API，你传 diff 过去，它吐 JSON 回来。但我们团队在试用三个月后全部弃用，核心原因就一条：无法调试、无法定制、无法归因。当 AI 给出一条错误建议（比如把一段性能优化的位运算误判为“可读性差需重构”），你既看不到它收到的完整 prompt，也改不了 temperature 参数，更没法回放当时的历史上下文。而 CLI 方案的核心哲学是：“所有决策过程必须暴露在终端里，像git log一样可追溯。” 我们用 Python 实现主 CLI（非 Node.js，因需深度集成 Pydantic 做 schema validation），但关键不在语言，而在分层设计：

• Layer 1：Context Collector—— 纯 Bash/Shell 脚本，只做一件事：根据输入（PR URL / branch name / commit hash）精准抓取 diff、issue metadata、code history metrics。它不碰 LLM，只输出一个标准化 JSON 文件，字段如diff_hunk_count,jira_priority,file_churn_rate_90d。这个层的好处是：运维同学可以独立更新数据源（比如把 Jira 换成 Azure DevOps），不影响上层。
• Layer 2：Prompt Orchestrator—— Python 模块，负责把 Layer 1 的 JSON 和预设的 prompt template（存放在./prompts/目录下）组装成最终请求体。这里支持 Jinja2 模板语法，例如{% if jira_priority == 'Critical' %}请优先检查线程安全问题{% endif %}。所有 prompt 版本都 git track，每次 review 自动生成prompt_version: v2.3.1字段。
• Layer 3：LLM Adapter—— 抽象出统一接口，当前支持 OpenAI、Claude、本地 Ollama 模型。关键设计是：Adapter 不直接返回 text，而是返回带元数据的ReviewResult对象，包含suggestion_type（bug_risk/perf_issue/style_violation）、confidence_score（0.1~0.9）、affected_lines（精确到行号数组）。这样后续过滤、分级、入库才有依据。
• Layer 4：Output Renderer—— 最终把ReviewResult渲染成三种格式：① 终端彩色 ANSI 输出（供开发者本地运行时快速扫读）；② GitHub-flavored Markdown（自动生成 PR comment）；③ 结构化 JSONL（供 ELK 日志系统消费，做长期质量趋势分析）。

这个架构让每个环节都可替换、可测试、可监控。上周我们把 Claude 切换到本地 Qwen2-7B，只需改一行配置llm_provider: ollama，连 prompt template 都不用动。这才是真正的 open。

2.3 为什么 Git 是不可替代的基石？不是“用 Git”，而是“活在 Git 里”

所有热词里，“git”出现频次远超“LLM”，这不是偶然。Git 不是运输工具，它是状态源头、权限边界、审计凭证。我们曾尝试过两种替代路径，全部失败：

• Path A：监听 IDE 编辑事件—— 用 VS Code Extension 监听onDidChangeTextDocument，实时分析当前编辑内容。问题在于：它看到的是“未提交的草稿”，而真实 review 必须基于“已确认的变更意图”。工程师在写代码时临时注释掉一段逻辑，IDE 插件会误报“存在 dead code”，但这段代码可能只是调试残留，根本不会进 PR。Git commit 才是意图的正式表达。
• Path B：对接 CI/CD webhook—— 在 Jenkins pipeline 里调用 LLM API。表面看很自动化，但致命缺陷是：CI 环境缺乏开发者的本地上下文。比如某次 PR 修改了数据库 schema，CI 里跑的是 clean Docker image，它不知道开发者本地.env里设置了DB_DEBUG_MODE=true，而这个 flag 会导致 ORM 生成完全不同的 SQL。结果 LLM 基于 CI 环境分析出的“无风险”，在开发者本地却引发事务死锁。

而 CLI 方案强制要求：open-code-review命令必须在 Git worktree 内执行，且默认只分析git diff --staged（暂存区）。这意味着：① 它看到的代码状态，和你git commit时的状态 100% 一致；② 它能读取.gitattributes判断二进制文件是否跳过；③ 它能通过git config --get user.name自动填充 reviewer identity。我们甚至把 review 结果存为 Git note（git notes add -m "LLM-review: v2.3.1"），这样git log --notes就能看到每次 commit 的 AI 审查记录，和人工 review 并列显示。Git 不是管道，它是整个流程的时空坐标系。

3. 核心细节解析：从零构建一个可生产的 CLI 审查器

3.1 Context Collector 层：如何用 20 行 Bash 抓取有业务意义的上下文？

很多人以为 LLM 审查的关键在模型，其实 70% 的效果差异来自 Context Collector。我们不用任何 SDK，纯 Bash + curl + jq 实现，确保能在最小化 Alpine 容器里运行。核心脚本collect_context.sh关键逻辑如下：

#!/bin/bash # 输入：PR URL，如 https://gitlab.example.com/proj/backend/-/merge_requests/12345 PR_URL=$1 PROJECT_ID=$(echo $PR_URL | sed -E 's|https://[^/]+/([^/]+)/([^/]+)/.*|\1/\2|') MR_IID=$(echo $PR_URL | grep -oE '/merge_requests/[0-9]+' | sed 's|/merge_requests/||') # Step 1: 获取 MR 基础信息（title, description, source_branch） MR_INFO=$(curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \ "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/merge_requests/$MR_IID") MR_TITLE=$(echo $MR_INFO | jq -r '.title') MR_DESC=$(echo $MR_INFO | jq -r '.description') # Step 2: 提取 Jira Issue ID（正则匹配 Resolves #XXX 或 Fixes PROJ-123） ISSUE_ID=$(echo "$MR_DESC" | grep -oE 'Resolves #[A-Za-z0-9]+|Fixes [A-Z]+-[0-9]+' | head -1 | sed 's/Resolves #//; s/Fixes //') # Step 3: 查询 Jira 获取优先级（这里用简化版，实际对接 Jira REST API） if [ -n "$ISSUE_ID" ]; then JIRA_RESP=$(curl -s -u "$JIRA_USER:$JIRA_TOKEN" \ "https://jira.example.com/rest/api/3/issue/$ISSUE_ID?fields=priority,issuetype") JIRA_PRIORITY=$(echo $JIRA_RESP | jq -r '.fields.priority.name // "Medium"') JIRA_TYPE=$(echo $JIRA_RESP | jq -r '.fields.issuetype.name // "Task"') else JIRA_PRIORITY="Medium" JIRA_TYPE="Task" fi # Step 4: 计算文件变更热度（过去 90 天该文件被修改次数） FILE_PATHS=$(echo $MR_INFO | jq -r '.changes[].old_path, .changes[].new_path' | sort -u) CHURN_DATA="{\"file_churn\":{}}" for FILE in $FILE_PATHS; do if [ -n "$FILE" ]; then # 使用 git log 统计，注意：必须在 repo root 下执行 COUNT=$(git log --since="90 days ago" --oneline -- "$FILE" | wc -l) CHURN_DATA=$(echo $CHURN_DATA | jq --arg file "$FILE" --argjson count "$COUNT" \ '.file_churn[$file] = $count') fi done # 最终输出标准化 JSON jq -n --arg title "$MR_TITLE" \ --arg desc "$MR_DESC" \ --arg priority "$JIRA_PRIORITY" \ --arg type "$JIRA_TYPE" \ --argjson churn "$CHURN_DATA" \ '{mr_title: $title, mr_description: $desc, jira_priority: $priority, jira_type: $type, churn_metrics: $churn}'

提示：这个脚本的关键价值不在技术多炫酷，而在于把模糊的业务规则固化为可执行逻辑。比如jira_priority字段，我们约定：只有Critical和High优先级的 issue 触发的 PR，才要求 LLM 重点检查并发安全；churn_metrics不是简单统计次数，而是后续 prompt 里会用if $churn_metrics.UserService.java > 5 then ...做条件分支。所有这些规则，都在 Bash 层完成，LLM 只负责基于明确指令推理。

3.2 Prompt Orchestrator：为什么用 Jinja2 模板，而不是拼接字符串？

早期我们用 Python f-string 拼 prompt，很快陷入泥潭：一个if-else分支要加新条件，就得改代码、发版本、重启服务。后来换成 Jinja2，体验天壤之别。prompts/review_v2.3.jinja2示例：

你是一名资深 Java 后端工程师，正在审查一个 {{ jira_type }} 类型的代码变更。 本次变更关联 Jira 问题 {{ jira_priority }} 优先级，标题为：{{ mr_title }} 【变更摘要】 {% for file in diff_files %} - {{ file.path }} ({{ file.additions }} 新增, {{ file.deletions }} 删除) {% endfor %} 【历史背景】 {% for file, churn in churn_metrics.file_churn.items() %} - {{ file }} 过去 90 天被修改 {{ churn }} 次，属于高变更频率文件。 {% endfor %} 【具体要求】 1. 仅针对 diff 中标记为 '+' 的新增代码行进行审查； 2. 若发现潜在 bug（如 NPE、SQL 注入、资源泄漏），必须指出具体行号并给出修复建议； 3. 若涉及数据库操作，检查是否使用了连接池且设置了合理超时； 4. 若 jira_priority 为 "Critical"，额外检查：线程安全、分布式锁粒度、幂等性实现。 【输出格式】 严格按以下 JSON Schema 输出，不要任何额外文字： { "suggestions": [ { "file": "string", "line_number": "integer", "suggestion_type": "enum: bug_risk | perf_issue | style_violation", "description": "string", "confidence_score": "number between 0.1 and 0.9" } ] }

注意：模板里所有变量都来自 Context Collector 的 JSON 输出，没有魔法值。jinja2的--undefined参数确保变量缺失时直接报错，而不是静默忽略。我们用pytest写了 12 个单元测试，覆盖jira_priority=Low时是否跳过并发检查、churn_metrics为空时是否不渲染历史背景等边界 case。模板即契约，这是保证 LLM 输出稳定性的第一道防线。

3.3 LLM Adapter：如何让不同模型输出统一结构，且不牺牲专业性？

最大的陷阱是：直接把 diff 丢给 LLM，让它自由发挥。我们实测过，OpenAI 的 response 里suggestion_type字段可能是"bug"、"potential_bug"、"critical_issue"，Claude 则爱用"high_risk"。统一 schema 的关键不是靠正则清洗，而是用 System Prompt 强约束输出结构。Adapter 的核心逻辑：

class LLMAdapter: def __init__(self, provider: str): self.provider = provider self.system_prompt = """ 你是一个严格的 JSON 输出引擎。你的唯一任务是：根据用户提供的代码 diff 和审查要求， 生成符合指定 JSON Schema 的响应。绝不添加任何解释性文字、Markdown 格式或额外字段。 如果无法确定建议类型，请使用 "unknown"。 """ def call(self, prompt: str) -> ReviewResult: if self.provider == "openai": response = openai.ChatCompletion.create( model="gpt-4-turbo", messages=[ {"role": "system", "content": self.system_prompt}, {"role": "user", "content": prompt} ], response_format={"type": "json_object"} # 关键！强制 JSON mode ) elif self.provider == "claude": response = anthropic.Anthropic().messages.create( model="claude-3-haiku-20240307", system=self.system_prompt, messages=[{"role": "user", "content": prompt}], response_format={"type": "json_object"} ) # 解析 response.content，用 Pydantic 模型校验 try: result = ReviewResult.model_validate_json(response.content) except ValidationError as e: # 记录原始 response.content 到日志，用于 debug logger.error(f"LLM output invalid: {response.content}, error: {e}") raise RuntimeError("LLM output schema violation") return result

实操心得：response_format={"type": "json_object"}是 OpenAI/Claude 的隐藏王牌，它比任何 post-process 正则都可靠。我们曾用 GPT-3.5 测试，开启此参数后 JSON 合法率从 62% 提升到 99.8%。但要注意：Claude 的response_format参数在 2024 年 4 月才正式支持，旧版需用{"type": "text"}+ 严格 prompt 约束。另外，Pydantic 的model_validate_json()会自动做类型转换（如把"123"转成int），避免前端解析失败。

3.4 Output Renderer：终端里的一行 colorized 输出，背后是 3 层渲染逻辑

开发者最常运行的是open-code-review --pr-url ... --output terminal，看似简单，实则最难。我们拒绝用rich库做花哨渲染，坚持用 ANSI escape codes，因为：

• 兼容所有 CI 环境（Jenkins agent、GitLab Runner 的 minimal image）
• 避免引入第三方依赖导致pip install失败
• 更容易做自动化测试（echo -e "\033[31mERROR\033[0m"可直接断言）

Renderer 的三层逻辑：

1. Level 1：Severity-based coloring
   bug_risk→ 红色（\033[31m），perf_issue→ 黄色（\033[33m），style_violation→ 蓝色（\033[34m）
2. Level 2：Context-aware truncation
   终端宽度 < 120 字符时，自动截断description字段，末尾加...，但保留file:line信息（这是定位关键）
3. Level 3：Interactive hint
   如果检测到当前在 Git Bash 或 Windows Terminal，且suggestion_type == "bug_risk"，末尾追加→ Run 'git show :<file> | head -n <line>' to view context

最终效果：

[BUG_RISK] UserService.java:47 → Null pointer risk on user.getProfile().getAvatar() Confidence: 0.87 | Fix: Add null check before accessing getAvatar() → Run 'git show :UserService.java | head -n 47' to view context

注意：git show :<file>是 Git 的 index 检出语法，它显示的是暂存区版本，而非工作区当前内容，确保看到的代码和 LLM 分析的完全一致。这个细节让开发者第一次点击就能精准定位，而不是抱怨“AI 说的行号不对”。

4. 实操全流程：从安装到生产部署的 7 个关键步骤

4.1 步骤 1：环境准备——为什么推荐 Ubuntu 22.04 LTS 而非最新版？

我们明确要求所有团队使用 Ubuntu 22.04 LTS（内核 5.15），理由非常实际：

• Python 版本锁定：Ubuntu 22.04 默认python3.10，而pydantic>=2.0要求 Python >=3.8，llama-cpp-python在 3.12 上编译失败率高达 40%。用 LTS 版本省去所有 Python 版本管理的麻烦。
• Git 版本兼容性：git diff --no-index在 Git 2.34+ 才支持--ignore-space-change的精确控制，而 Ubuntu 22.04 的 apt 仓库提供 Git 2.37，完美匹配。
• 容器镜像基础：Docker Hub 的python:3.10-slim镜像基于 Debian 11，但我们的 CI runner 是 Ubuntu，混合使用导致libc版本冲突。统一 OS 栈，故障率下降 65%。

安装命令极简：

# 更新系统 sudo apt update && sudo apt upgrade -y # 安装核心依赖 sudo apt install -y git python3-pip python3-venv curl jq # 验证 git --version # 必须 >= 2.34 python3 --version # 必须 == 3.10.*

提示：跳过sudo apt install python3-dev！这是最大坑。llama-cpp-python编译需要libssl-dev，但python3-dev会安装全套 CPython 头文件，导致pip install时内存溢出（尤其在 2GB RAM 的 CI agent 上）。正确做法是sudo apt install libssl-dev build-essential。

4.2 步骤 2：CLI 安装——为什么用pipx而非pip install --user？

pipx是 Python CLI 工具的事实标准，它解决两个致命问题：

• 隔离性：每个 CLI 工具在独立 virtualenv 中运行，open-code-review依赖anthropic==0.30.0，而你本地项目用anthropic==0.25.0，互不干扰。
• PATH 管理：pipx install open-code-review后，open-code-review命令自动加入$PATH，无需手动export PATH。

安装流程：

# 1. 安装 pipx（Ubuntu 22.04 需先装 ensurepip） sudo apt install -y python3-venv python3-pip python3 -m pip install --upgrade pip python3 -m pip install pipx python3 -m pipx ensurepath # 2. 安装 CLI（注意：我们发布在私有 PyPI，非 PyPI.org） pipx install --index-url https://pypi.internal.example.com/simple/ open-code-review # 3. 验证 open-code-review --version # 输出 v2.3.1 open-code-review --help

实操心得：pipx install会自动创建~/.local/bin并加入 PATH，但某些 shell（如 zsh）需要重启终端或执行source ~/.zshrc。我们写了个post-install.sh脚本，自动检测 shell 类型并 reload config，避免新手卡在这一步。

4.3 步骤 3：配置初始化——config.yaml里 5 个必填字段的深层含义

运行open-code-review init会生成~/.open-code-review/config.yaml，其中 5 个字段绝不能留空：

gitlab: base_url: "https://gitlab.example.com" # 必须带协议和端口（如 https://gitlab:8443） private_token: "glpat-xxxxxxxxxxxxxx" # GitLab Personal Access Token，需 api scope jira: base_url: "https://jira.example.com" username: "svc-open-code-review@company.com" api_token: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" llm: provider: "openai" # 可选 openai/claud/ollama api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" model: "gpt-4-turbo" review: max_suggestions: 10 # 单次 review 最多返回几条建议，防 LLM 过度发挥

关键细节：

• private_token必须是Personal Access Token，不是 Project Access Token。因为 Context Collector 需要跨项目查询 MR，Project Token 权限不足。
• jira.username必须是service account，不能用个人邮箱。我们创建了svc-open-code-review用户，只赋予Browse Projects和View Issues权限，最小化权限原则。
• llm.api_key的存储：config.yaml文件权限必须设为600（chmod 600 ~/.open-code-review/config.yaml），否则open-code-review启动时会报错退出，这是安全强制措施。

4.4 步骤 4：本地首次运行——如何用--dry-run捕获 90% 的配置错误？

永远不要直接跑open-code-review --pr-url ...。先用--dry-run：

open-code-review --pr-url https://gitlab.example.com/proj/backend/-/merge_requests/12345 --dry-run

--dry-run模式下，CLI 只执行到 Context Collector 和 Prompt Orchestrator，输出最终组装的 prompt JSON，但不调用 LLM。你会看到类似：

{ "prompt": "你是一名资深 Java 后端工程师...（完整 prompt）", "context": { "mr_title": "Refactor user profile loading", "jira_priority": "High", "churn_metrics": {"UserService.java": 17} } }

检查点：

• ✅context.jira_priority是否正确解析（若为null，说明 Jira URL 配错或 token 无效）
• ✅churn_metrics是否有数据（若为空，检查git命令是否在 repo root 执行）
• ✅prompt字段长度是否 < 128000 字符（GPT-4 Turbo 上限，超限会触发 fallback 逻辑）

注意：--dry-run输出的 prompt 是真实发送给 LLM 的内容，可直接复制到 ChatGPT 网页版测试，验证 prompt 逻辑是否符合预期。这是调试 prompt 的黄金方法。

4.5 步骤 5：CI/CD 集成——为什么必须用git clone --depth=1？

在 GitLab CI 的.gitlab-ci.yml中，常见错误是：

# ❌ 错误：完整 clone，耗时 3 分钟，且可能因 submodule 失败 - git clone https://gitlab.example.com/proj/backend.git # ✅ 正确：浅克隆 + 检出 MR 源分支 - git clone --depth=1 --branch $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME \ https://gitlab.example.com/proj/backend.git . - cd backend - open-code-review --pr-url $CI_MERGE_REQUEST_PROJECT_URL/-/merge_requests/$CI_MERGE_REQUEST_IID

--depth=1减少 80% clone 时间，但关键在--branch参数：它确保工作目录状态和 MR 的源分支完全一致。我们曾遇到一个诡异 bug——CI 里git diff抓到的文件和开发者本地不一致，根源是 CI 默认 checkout 的是refs/pull/12345/head，而open-code-review的 Context Collector 用git diff比较的是origin/main...HEAD，导致 diff 范围错乱。用--branch显式指定，一劳永逸。

4.6 步骤 6：GitHub 集成——如何让 LLM review 自动作为 PR comment？

GitLab 原生支持 CI job 输出artifacts:reports:codequality，但 GitHub 需要自己造轮子。我们在 CLI 里内置了--output github-comment模式：

# 在 GitHub Actions 的 workflow.yml 中 - name: Run Open Code Review run: | open-code-review \ --pr-url ${{ github.event.pull_request.html_url }} \ --output github-comment \ --github-token ${{ secrets.GITHUB_TOKEN }}

CLI 内部逻辑：

• 解析html_url得到 owner/repo/PR number
• 调用 GitHub REST API/repos/{owner}/{repo}/issues/{issue_number}/commentsPOST
• 渲染 Markdown 时，对suggestion_type == "bug_risk"的条目，自动添加:rotating_light:emoji 和**CRITICAL**标签，提升视觉权重

实操心得：GitHub 的 comment rate limit 是 60/minute，我们做了指数退避重试（1s, 2s, 4s），并在config.yaml里加了github: {max_retries: 3}配置项。同时，CLI 会检查 PR 是否已有相同内容的 comment（用body的 hash 去重），避免重复刷屏。

4.7 步骤 7：生产监控——如何用open-code-review stats看懂质量趋势？

CLI 自带stats子命令，每天定时执行：

# 收集过去 24 小时所有 review 数据 open-code-review stats --since 24h --format json > /var/log/ocr/daily.json # 输出关键指标 open-code-review stats --since 7d --summary # 输出：Total reviews: 142 | Avg suggestions per PR: 3.2 | Bug risk rate: 18.3% | Avg latency: 4.2s

stats命令的底层是读取~/.open-code-review/logs/下的 JSONL 日志（每行一个 review event），关键字段：

• llm_latency_ms: LLM API 响应时间，用于识别模型退化
• suggestion_count: 总建议数，结合git diff --stat的行数，计算“每千行代码建议密度”
• confidence_score_avg: 所有建议的平均置信度，低于 0.65 时触发告警（说明 prompt 或模型需优化）

我们把stats --format prometheus输出喂给 Prometheus，设置告警规则：rate(open_code_review_suggestions_total{type="bug_risk"}[1h]) > 5，即每小时发现高危问题超过 5 个，说明近期代码质量在下滑。

5. 常见问题与排查技巧实录：那些文档里不会写的血泪教训

5.1 问题 1：unable to locate the codex cli binary—— 这根本不是路径问题，而是权限问题

所有搜索热词里，unable to locate the codex cli binary高频出现，但 95% 的 case 和 PATH 无关。真实原因是：CLI 安装后，其依赖的llama-cpp-python在首次 import 时会动态编译 native extension，需要 write 权限到~/.cache/llama-cpp/目录。如果用户用sudo pipx install，那么 cache 目录属主是 root，普通用户运行时就会 Permission Denied。

排查命令：

# 查看实际报错（不是表面提示） open-code-review --debug --pr-url ... 2>&1 | grep -A5 "ImportError" # 输出：ImportError: cannot write to /root/.cache/llama-cpp/...

解决方案：

# 1. 删除错误的 cache sudo rm -rf /root/.cache/llama-cpp/ # 2. 用普通用户重新安装（关键！） pipx uninstall open-code-review pipx install open-code-review # 3. 验证 cache 目录属主 ls -ld ~/.cache/llama-cpp/ # 必须是当前用户

注意：--debug参数会输出完整 traceback，这是定位此类问题的唯一途径。我们把--debug加入所有 CI job 的默认参数，确保日志可追溯。

5.2 问题 2：LLM 返回 JSON 格式错误，但response_format={"type":"json_object"}已开启

这是 Claude 用户的专属痛点。Claude 的response_format参数在 2024 年 4 月前是 beta 功能，需显式启用。解决方案分两步：

• Step 1：升级 Anthropic SDK

  pipx upgrade anthropic # 确保 anthropic>=0.30.0

• Step 2：在 config.yaml 中显式声明

  llm: provider: "claude" api_key: "..." model: "claude-3-haiku-20240307" # 新增字段，告诉 SDK 启用 JSON mode json_mode: true

CLI 内部会检测json_mode: true，然后在调用anthropic.messages.create()时传入response_format={"type": "json_object"}。如果 SDK 版本过低，会静默忽略该参数，导致返回 plain text。

5.3 问题 3：git -c diff.mnemonicprefix=false -c core.quotepath=false --no-optional-locks这串命令是干什么的？

这是 Git 的高级配置，open-code-review在 Context Collector 里默认启用，目的是消除 Git 输出的非确定性：

• diff.mnemonicprefix=false：禁用a/b/前缀（如diff --git a/src/UserService.java b/src/UserService.java），让 diff 更简洁，LLM 解析更稳定。
• `core.quotep