企业官网建设流程全解析

1. 项目概述：这不是一个“工具”，而是一套可落地的代码审查新范式

open-code-review 这个名字乍看像某个开源项目仓库名，但结合当前技术热词——CLI、LLM、git、codex cli、trae cli、dify、embedding、prompt injection——它实际指向一个正在快速成型的工程实践：用本地可控的命令行接口（CLI），调用轻量级或可私有部署的大语言模型（LLM），在 Git 提交前/后自动完成结构化代码审查，并将结果直接嵌入开发工作流。它不是替代人工 Code Review 的“黑盒AI助手”，而是把 LLM 变成你终端里一个可配置、可审计、可调试的“审查协作者”。我从去年开始在三个不同规模的团队中推动这类实践，从最初用 shell 脚本硬拼 curl 调 API，到如今稳定运行在 CI/CD 流水线中的定制 CLI 工具链，核心目标始终没变：让代码审查的“发现-定位-解释-建议”四个环节全部可追溯、可复现、可版本化。它解决的不是“要不要审代码”的问题，而是“为什么这次 PR 没被拦住 bug”、“为什么上次建议被忽略”、“为什么同一个问题在不同人提交时反馈不一致”这些真实痛点。适合两类人：一是每天要处理 10+ PR 的 Tech Lead，需要快速抓出高风险变更；二是刚转岗的 junior 开发者，需要在 commit 前就获得符合团队规范的即时反馈，而不是等 Code Review 会议时被当众指出低级错误。它不依赖 SaaS 平台、不上传源码、不绑定特定模型，所有逻辑跑在你自己的机器或内网服务器上——这才是真正意义上的 open code review。

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

2.1 为什么必须是 CLI 而不是 Web UI 或 IDE 插件？

很多人第一反应是：“既然要用 LLM 审代码，那做个 VS Code 插件不更方便？” 我试过，也带团队踩过坑。Web UI 的本质是把审查过程变成“请求-响应”式交互，用户点一下“Review This PR”，后台拉取 diff、喂给模型、等返回、渲染结果。问题在于：它切断了 Git 工作流的原子性。当你在 PR 页面点击审查按钮时，代码可能已经合并；当你看到结果想改代码，又得切回编辑器；更麻烦的是，UI 层无法天然继承 Git 的上下文——比如当前分支的 base 分支是谁、commit message 是否符合 Conventional Commits 规范、本次修改是否涉及已标记为 deprecated 的 API。而 CLI 天然就是 Git 的延伸。git commit -m "fix: handle null pointer in user service"执行后，hook 自动触发open-code-review --diff HEAD~1..HEAD --context=service，它能精确拿到这次提交的完整变更范围、关联的 issue 编号（如果 commit message 里写了#ISSUE-123）、甚至读取.gitattributes判断哪些文件该跳过审查（比如生成的 protobuf 文件）。我们团队实测数据：同样一次 50 行的 JS 修改，CLI 方式从触发到输出结构化 JSON 报告平均耗时 2.3 秒；Web UI 因网络延迟+页面渲染+状态同步，平均 8.7 秒，且失败重试成本高。更重要的是，CLI 输出可直接被其他工具消费——Jenkins 流水线用jq '.severity == "critical"' report.json判断是否阻断构建；SonarQube 插件读取report.json中的line_number字段做精准标记；甚至用cat report.json | grep -E '"severity":"high"' | wc -l就能统计本次 PR 的高危问题数。这种“管道化”能力，是任何图形界面都无法替代的底层优势。

2.2 为什么选择本地/私有 LLM 而非直接调 ChatGPT API？

热搜词里反复出现unable to locate the codex cli binary、dify的sql查询内容太多导致llm返回不稳定、llm代理地址，恰恰暴露了公有云 LLM 接入的三大硬伤：网络抖动、上下文截断、响应不可控。去年我们有个支付模块的 PR，diff 内容约 1200 行，调用某公有 API 时，模型返回的 JSON 格式在第 892 行突然中断，导致后续解析失败，CI 直接挂起。排查发现是服务端做了 1024 token 的硬截断，而我们的 prompt 模板本身占了 320 token，留给代码分析的只剩不到 700 token——根本不够解析一个完整的 Spring Boot Controller 类。更致命的是prompt injection attack风险：当 diff 中包含类似// TODO: fix this later @model:ignore的注释时，公有模型可能误判为指令，跳过关键逻辑审查。我们最终采用Ollama + CodeLlama-7b-Instruct的组合，部署在团队内网一台 32GB 内存的服务器上。选择理由很实在：CodeLlama 是专为代码训练的开源模型，对 Java/Python/Go 的语法理解远超通用模型；7b 参数量能在单卡 A10 上跑满 16 个并发请求；Ollama 提供标准化的/api/chat接口，和 OpenAI 兼容，现有 CLI 工具几乎不用改代码就能切换。最关键的是，我们给模型加了两层防护：第一层是预处理器，扫描 diff 内容，自动剥离所有以@开头的注释（如@SuppressWarnings、@Deprecated），避免 prompt 注入；第二层是后处理器，用正则强制校验返回 JSON 的}是否闭合，不闭合则触发重试并降级到规则引擎（比如直接匹配if (x == null)后无else的模式）。这套组合拳让审查稳定性从 73% 提升到 99.2%，且完全规避了数据外泄风险——所有代码片段只在内存中存在，生命周期不超过 30 秒。

2.3 Git 集成不是“锦上添花”，而是整个系统的基石

open-code-review 的名字里带 “git” 不是巧合。它的核心价值不在“用了 LLM”，而在“无缝嵌入 Git 生命周期”。我们设计了三级 Git 集成点：
第一级：pre-commit hook——在git commit执行前拦截，审查本次暂存区（staging）的代码。这是最轻量的防线，适合检查格式、空指针、硬编码密钥等基础问题。我们用 Python 写了个pre-commit.py，通过git diff --cached --name-only获取待提交文件列表，再用git show :<file>读取暂存区内容，喂给 LLM。关键技巧：对大文件（>500 行）自动跳过，改用grep -n "password\|secret" <file>做快速扫描，避免阻塞开发者。
第二级：post-merge hook——在git pull后触发，审查刚合并进本地分支的代码。这解决了“别人提交的代码我来不及看”的问题。我们把它和 IDE 的文件监听结合：IntelliJ 的FileWatcher检测到.git/FETCH_HEAD更新，就自动执行open-code-review --since=FETCH_HEAD --until=HEAD。
第三级：CI/CD 集成——在 Jenkins/GitLab CI 的test阶段前插入open-code-review --pr-id=$CI_MERGE_REQUEST_IID。这里我们做了个重要妥协：不审查整个 PR 的 diff，而是只审查本次构建实际编译/测试的模块。比如一个 PR 修改了 3 个微服务，但本次流水线只跑 user-service 的单元测试，那 CLI 就只提取 user-service 目录下的变更文件。这把审查耗时从平均 47 秒压到 8.2 秒，且问题定位精度更高——报告里每条建议都标注了“影响本次构建的 test case：UserLoginTest.testNullEmail()”。没有 Git 的深度集成，open-code-review 就只是个玩具；有了 Git，它才成为开发流程里真正咬得住的齿轮。

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

3.1 CLI 工具链的最小可行架构

一个真正可用的 open-code-review CLI，绝不是简单封装一个curl命令。我们最终采用的架构是三层设计：
Shell 层（入口）：open-code-review命令本身是个 Bash 脚本，只做三件事：参数解析（getopts）、环境校验（检查OLLAMA_HOST是否设置）、分发任务（根据子命令调用对应 Python 模块）。好处是启动极快（<10ms），且能利用 Shell 的管道能力，比如git diff HEAD~1 | open-code-review --stdin。
Python 层（核心逻辑）：用 Click 框架实现，包含review、config、template三个子命令。review命令是主干，负责：① 从 Git 获取 diff（调用git diff-tree -U0 --no-commit-id --root $commit_hash获取原始 diff）；② 应用预处理规则（过滤二进制文件、按语言拆分 chunk、注入团队规范文档片段）；③ 构造 prompt（不是简单拼字符串，而是用 Jinja2 模板，支持条件渲染）；④ 调用 LLM API；⑤ 后处理 JSON（校验 schema、补充 Git 元信息如commit_hash、author_email）。
Template 层（策略中心）：所有审查逻辑藏在templates/目录下。每个语言一个文件夹（java/,python/），里面是prompt.j2和schema.json。prompt.j2示例：

你是一名资深 {{ language }} 架构师，正在审查以下代码变更。请严格按以下规则输出 JSON： - 只分析 diff 中 marked as '+' 的新增行 - 忽略所有测试文件（路径含 'test' 或 'spec'） - 对每个问题，给出 severity（critical/high/medium/low）、file_path、line_number、description、suggestion - critical 问题必须满足：可能导致 NPE、SQL 注入、权限绕过 - 不要解释原理，只输出 JSON，不要额外文字 代码变更： {{ diff_content }} 团队规范摘要： - 禁止使用 System.out.println，必须用 SLF4J logger - 所有 REST 接口必须有 @Valid 注解 - 数据库密码必须从 Environment 读取，禁止硬编码

schema.json则定义了期望的 JSON 结构，用于jsonschema.validate()校验。这种设计让非程序员也能参与规则制定——产品经理只需改schema.json就能要求新增“business_logic_consistency”字段；安全工程师更新prompt.j2就能加入新的 OWASP Top 10 检查项。我们上线三个月，模板迭代了 17 版，但 CLI 主程序一行没动。

3.2 LLM Prompt 设计的“反直觉”技巧

网上教程总说“写好 prompt 就成功了一半”，但实际操作中，90% 的失败源于对 LLM 的“拟人化幻想”。我们总结出三条反常识但极其有效的 prompt 设计原则：
第一，“指令前置”比“示例后置”更可靠。很多教程教你在 prompt 末尾放几个 JSON 示例，指望模型模仿。但我们发现，当 diff 很长时，模型容易“遗忘”示例格式，尤其在 OOM 时会随机截断。解决方案：把 JSON Schema 直接写在 prompt 开头，并用粗体强调。例如：

你必须输出严格符合以下 JSON Schema 的对象，字段名、类型、必填项都不能错：
{ "issues": [ { "severity": "string", "file_path": "string", "line_number": "integer", "description": "string", "suggestion": "string" } ] }
如果无法判断，severity 设为 "low"，suggestion 设为空字符串。绝不输出任何 JSON 以外的文字。
这样模型的“注意力锚点”始终在结构上，而非内容上。实测 JSON 格式合规率从 61% 提升到 98%。
第二，用“否定式约束”代替“肯定式要求”。不要写“请检查空指针”，而写“如果代码中出现obj.method()且 obj 来源未做 null check，则视为 critical 问题”。LLM 对否定条件的识别更稳定。我们专门建了个negative_rules.md文档，收录了 37 条经过验证的否定式规则，比如：“不检查response.status == 200就直接response.json()”、“在 for 循环内 new 对象但未复用”、“catch Exception 但未 log”。
第三，给模型“思考留白”。在 prompt 末尾加一句：请先逐行分析 diff，再汇总问题，最后按 schema 输出 JSON。这看似多余，但实测能减少 22% 的漏报——模型真的会按这个步骤执行，而不是直接跳到输出。我们甚至对比过：加这句后，对if (user != null && user.getName().length() > 0)这种嵌套调用的 NPE 检测率，从 43% 提升到 79%。

3.3 Git Diff 解析的隐藏陷阱与绕过方案

git diff看似简单，但它是 open-code-review 最容易翻车的环节。我们踩过的坑足够写本书：
坑一：二进制文件的“假 diff”。git diff对图片、PDF、jar 包也会输出类似Binary files a/lib.jar and b/lib.jar differ的行。如果 CLI 不过滤，这些行会被当成代码喂给 LLM，导致模型困惑甚至崩溃。解决方案：在获取 diff 后，先用file -i <file>检查 MIME 类型，对application/octet-stream、image/*等类型直接跳过。我们还加了个“安全开关”：当 diff 中Binary files出现超过 3 次，自动终止审查并报错Too many binary files, aborting。
坑二：rename 的“幽灵行”。当文件被重命名（git mv old.java new.java），git diff会显示similarity index 100%，但不会输出具体行。LLM 拿不到代码，自然无法审查。我们的对策是：检测到 rename 时，用git show $commit_hash:old.java和git show $commit_hash:new.java分别提取旧版和新版内容，计算 diff 后再送审。虽然多一次 git 操作，但保证了逻辑完整性。
坑三：UTF-8 BOM 的“隐形杀手”。Windows 下某些编辑器保存的文件带 BOM（Byte Order Mark），git diff输出的+行开头会是public class ...。LLM 无法识别这种乱码，直接返回空结果。我们在预处理阶段加了 BOM 清洗：diff_content = diff_content.replace('\ufeff', '')。这个 3 字符的替换，解决了 15% 的“无响应”问题。
坑四：超长行的“截断灾难”。Java 的String sql = "SELECT * FROM users WHERE id = ? AND status = ?";这种长 SQL 行，在git diff -U0中会被截成多行，破坏语义。我们的方案是：对每行 diff，用正则^\+(.*)$提取新增内容，再用textwrap.fill(line, width=120, break_long_words=False)强制换行，确保 SQL 片段不被撕裂。这些细节，文档里不会写，但没它们，工具就只是个摆设。

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

4.1 从零搭建可运行的 open-code-review 环境（以 Ubuntu 22.04 为例）

第一步：安装基础依赖

# 安装 Git（确保 2.30+，因需 --no-optional-locks 支持） sudo apt update && sudo apt install -y git curl wget python3-pip python3-venv # 安装 Ollama（官方一键脚本） curl -fsSL https://ollama.com/install.sh | sh # 启动 Ollama 并拉取模型 systemctl start ollama ollama pull codellama:7b-instruct

第二步：创建 CLI 工具目录结构

mkdir -p ~/open-code-review/{bin,templates/java,templates/python,config} cd ~/open-code-review # 创建主 CLI 脚本 cat > bin/open-code-review << 'EOF' #!/bin/bash # open-code-review v1.0 set -e # 参数解析 while getopts "hvc:d:s:" opt; do case $opt in h) echo "Usage: open-code-review [OPTIONS]"; exit 0 ;; v) echo "open-code-review 1.0"; exit 0 ;; c) CONFIG_FILE="$OPTARG" ;; d) DIFF_FILE="$OPTARG" ;; s) SINCE_COMMIT="$OPTARG" ;; esac done # 环境校验 if [ -z "$OLLAMA_HOST" ]; then export OLLAMA_HOST="http://localhost:11434" fi # 分发任务 case "${1:-}" in review) python3 -m open_code_review.cli review "$@" ;; config) python3 -m open_code_review.cli config "$@" ;; *) echo "Unknown command: $1"; exit 1 ;; esac EOF chmod +x bin/open-code-review echo 'export PATH="$HOME/open-code-review/bin:$PATH"' >> ~/.bashrc source ~/.bashrc

第三步：初始化 Python 包（关键！用pyproject.toml管理依赖）

cd ~/open-code-review python3 -m venv venv source venv/bin/activate pip install click requests jinja2 jsonschema pydantic # 创建包结构 mkdir -p open_code_review/{cli,core,templates} touch open_code_review/__init__.py touch open_code_review/cli/__init__.py

第四步：实现核心审查逻辑（open_code_review/cli/review.py）

import click import json import requests from pathlib import Path from jinja2 import Environment, FileSystemLoader from jsonschema import validate, ValidationError from open_code_review.core.diff_parser import parse_git_diff from open_code_review.core.llm_client import call_ollama @click.command() @click.option('--diff', '-d', type=click.Path(exists=True), help='Path to diff file') @click.option('--since', '-s', help='Git commit hash to compare from') @click.option('--to', '-t', default='HEAD', help='Git commit hash to compare to') def review(diff, since, to): """Run code review on git diff""" # 1. 获取 diff 内容 if diff: with open(diff, 'r') as f: diff_content = f.read() else: if since: cmd = f"git diff {since} {to} --no-optional-locks" else: cmd = "git diff --cached --no-optional-locks" import subprocess result = subprocess.run(cmd, shell=True, capture_output=True, text=True) diff_content = result.stdout # 2. 解析 diff，提取有效代码变更 files_to_review = parse_git_diff(diff_content) # 3. 为每个文件生成 prompt 并调用 LLM all_issues = [] for file_info in files_to_review: # 加载对应语言的 prompt 模板 env = Environment(loader=FileSystemLoader('templates')) template = env.get_template(f"{file_info['lang']}/prompt.j2") # 渲染 prompt prompt = template.render( diff_content=file_info['diff'], language=file_info['lang'], team_rules=load_team_rules() ) # 调用 LLM try: response = call_ollama(prompt) issues = json.loads(response) # 注入 Git 元信息 for issue in issues.get('issues', []): issue['git_commit'] = to issue['git_author'] = get_git_author(to) all_issues.extend(issues.get('issues', [])) except (json.JSONDecodeError, ValidationError) as e: click.echo(f"LLM response invalid for {file_info['path']}: {e}") continue # 4. 输出结构化报告 report = {"issues": all_issues, "summary": {"total": len(all_issues)}} click.echo(json.dumps(report, indent=2)) def load_team_rules(): # 从 config/team_rules.json 加载 rules_path = Path("config/team_rules.json") return json.loads(rules_path.read_text()) if rules_path.exists() else {} def get_git_author(commit_hash): # 调用 git 命令获取作者邮箱 import subprocess result = subprocess.run( f"git log -n1 --pretty=format:'%ae' {commit_hash}", shell=True, capture_output=True, text=True ) return result.stdout.strip() if __name__ == '__main__': review()

第五步：配置团队规范（config/team_rules.json）

{ "java": { "forbidden_patterns": [ {"regex": "System\\.out\\.println\\(", "severity": "high", "message": "Use SLF4J logger instead"}, {"regex": "new String\\(.*getBytes\\(\\)\\)", "severity": "critical", "message": "Potential encoding vulnerability"} ], "required_annotations": ["@Valid", "@Transactional"] }, "python": { "forbidden_patterns": [ {"regex": "print\\(", "severity": "medium", "message": "Use logging instead"}, {"regex": "os\\.system\\(", "severity": "critical", "message": "Command injection risk"} ] } }

第六步：编写 Java 模板（templates/java/prompt.j2）

你是一名资深 Java 架构师，正在审查以下代码变更。请严格按以下规则输出 JSON： - 只分析 diff 中 marked as '+' 的新增行 - 忽略所有测试文件（路径含 'test' 或 'spec'） - 对每个问题，给出 severity（critical/high/medium/low）、file_path、line_number、description、suggestion - critical 问题必须满足：可能导致 NPE、SQL 注入、权限绕过 - 不要解释原理，只输出 JSON，不要额外文字 代码变更： {{ diff_content }} 团队规范摘要： {% for rule in team_rules.java.forbidden_patterns %} - 禁止 {{ rule.message }}（匹配 {{ rule.regex }}） {% endfor %} {% for ann in team_rules.java.required_annotations %} - 必须有 {{ ann }} 注解 {% endfor %}

第七步：运行首次审查

# 创建测试文件 echo "public class Test { public static void main(String[] args) { System.out.println(\"hello\"); } }" > Test.java git add Test.java git commit -m "test: add hello world" # 执行审查 open-code-review review

预期输出是一个包含issues数组的 JSON，其中至少有一条关于System.out.println的 high 级别问题。整个过程无需联网（除了首次拉取模型），所有代码都在本地处理，响应时间在 3 秒内。这就是 open-code-review 的最小闭环。

4.2 关键参数调优与性能实测数据

open-code-review 的效果高度依赖几个关键参数，它们不是随便设的，而是基于大量实测得出的平衡点：
temperature = 0.1：这是最反直觉的设置。网上都说 temperature 要调高让模型“更有创意”，但代码审查恰恰需要确定性。我们对比过 0.1/0.3/0.5/0.7 四个值：temperature=0.1 时，对同一段if (x == null)的 NPE 检测一致性达 99.8%；0.7 时只有 62%，因为模型有时会“发挥”说“此处 null check 不必要”。0.1 让模型像一台精密仪器，而不是一个爱聊天的朋友。
max_tokens = 2048：CodeLlama-7b 的上下文窗口是 4096，但留一半给 prompt，剩下 2048 给输出。我们发现，当输出 JSON 超过 1800 tokens 时，Ollama 会静默截断，导致 JSON 不完整。所以强制限制 max_tokens=2048，并在后处理器里加校验：if response.count('{') != response.count('}'):则重试。
chunk_size = 300 行：LLM 处理长代码时，准确率随长度指数下降。我们把 diff 按文件拆分后，再按函数粒度切 chunk。算法很简单：扫描public、def、func等关键字，每遇到一个就切一刀，但确保每 chunk 不超过 300 行。实测表明，300 行是准确率拐点——超过后，对try-catch-finally嵌套逻辑的识别率从 89% 降到 63%。
retry_times = 3：网络抖动或模型 OOM 是常态。我们的重试策略是：第一次失败后，降级到temperature=0.05；第二次失败，改用规则引擎（正则匹配）；第三次失败，直接报错。这个策略让整体成功率从 82% 提升到 99.4%。
性能实测表（基于 16GB RAM / i7-11800H / RTX 3060）：

注意：所有耗时都包含 Git 调用、diff 解析、prompt 构造、LLM 调用、JSON 校验全流程。这个数据证明，它不是概念玩具，而是能扛住生产环境压力的工具。

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

5.1 “Unable to locate the codex cli binary” 类错误的根因与解法

这个错误在热搜里高频出现，但它根本不是 open-code-review 的问题，而是用户混淆了工具链层级。codex cli是 GitHub Copilot 的官方 CLI，而 open-code-review 是完全独立的实现。当用户看到unable to locate the codex cli binary，90% 的情况是：
场景一：PATH 配置错误。用户把open-code-review脚本放在~/bin/，但没执行export PATH="$HOME/bin:$PATH"，或者写错了路径（比如~/open-code-review/bin写成~/open-code-review/）。排查命令：which open-code-review，如果返回空，说明 PATH 没生效。解法：echo 'export PATH="$HOME/open-code-review/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc。
场景二：权限不足。脚本没有执行权限。ls -l ~/open-code-review/bin/open-code-review如果显示-rw-r--r--，说明缺少x位。解法：chmod +x ~/open-code-review/bin/open-code-review。
场景三：Python 环境隔离失败。用户在全局 Python 环境里 pip install 了依赖，但 CLI 脚本里python3 -m open_code_review.cli却找不到模块。这是因为python3指向系统 Python，而pip install可能装到了用户 site-packages。解法：统一用虚拟环境，source ~/open-code-review/venv/bin/activate后再运行。
场景四：Ollama 服务未启动。curl http://localhost:11434/api/tags返回Connection refused。解法：systemctl status ollama查看状态，sudo systemctl start ollama启动。

提示：永远先运行open-code-review --version（如果实现了）或which open-code-review，再查curl -v http://localhost:11434/api/tags，最后看python3 -c "import requests; print(requests.get('http://localhost:11434/api/tags').json())"。按这个顺序排查，95% 的“binary not found”问题都能秒解。

5.2 LLM 返回 JSON 不稳定？先检查这三处

Dify 用户抱怨sql查询内容太多导致llm返回不稳定，这其实是通用问题。我们总结出三个必查点：
第一，prompt 中的 JSON Schema 是否严格？很多人写"issues": []，但没定义数组元素结构。正确写法：

{ "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "severity": {"type": "string", "enum": ["critical","high","medium","low"]}, "file_path": {"type": "string"}, "line_number": {"type": "integer"}, "description": {"type": "string"}, "suggestion": {"type": "string"} }, "required": ["severity","file_path","line_number","description","suggestion"] } } } }

少一个required，模型就可能漏字段。
第二，diff 内容是否包含控制字符？git diff输出的^M（Windows 换行符）、\0（空字符）会让 JSON 解析器崩溃。我们在parse_git_diff函数里加了清洗：diff_clean = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f]', '', diff_raw)。
第三，LLM 的 stop sequence 是否设置？Ollama 默认 stop sequence 是["\n", "```"]，但模型有时会输出...suggestion": "use Optional"...}后多一个换行，导致 JSON 多一行空白。解法：在call_ollama函数里显式传参{"stop": ["\n", "```", "}"]}，强制在}后停止。

注意：不要迷信“模型越强越好”。我们测试过 CodeLlama-13b 和 7b，13b 在长文本上确实更好，但 7b 的响应速度是 13b 的 2.3 倍，且对小 diff 的准确率反而高 1.2%——因为参数少，过拟合风险低。选型要算 ROI，不是堆参数。

5.3 Git 集成失效的典型场景与修复指南

git -c diff.mnemonicprefix=false -c core.quotepath=false --no-optional-locks这串命令频繁出现在热搜里，说明很多人卡在 Git 配置上。我们整理了四大失效场景：
场景一：pre-commit hook 不触发。原因：.git/hooks/pre-commit是 shell 脚本，但用户写了 Python 脚本却没加#!/usr/bin/env python3头，或没给执行权限。解法：chmod +x .git/hooks/pre-commit，并在第一行写#!/usr/bin/env python3。
场景二：--no-optional-locks被忽略。这是 Git 2.30+ 的特性，老版本不支持。git --version查版本，低于 2.30 的必须升级。Ubuntu 20.04 默认 Git 2.25，需手动编译或加 PPA。
场景三：diff 获取为空。常见于git commit -a后立即运行 CLI，此时暂存区为空。解法：CLI 内部加检测git diff --cached --quiet，如果返回 1（无差异），则自动 fallback 到git diff HEAD。
场景四：中文路径乱码。git diff在 UTF-8 环境下对中文路径输出"\344\270\215\345\220\215"这种 octal 编码。解法：在 diff 解析前加diff_utf8 = diff_bytes.decode('utf-8', errors='ignore')。

实操心得：永远用git config --global core.quotepath false关闭路径转义，用git config --global core.autocrlf input统一换行符。这两条配置能解决 70% 的 Git 集成问题。

5.4 安全边界与权限控制的硬性要求

claude code cli 如何给完全访问权限这类搜索暴露了一个危险倾向：把 CLI 当成万能钥匙。open-code-review 必须遵守三条铁律：
第一，绝不读取未跟踪文件。CLI 只处理git diff输出的内容，对git status --ignored显示的文件、.env、target/目录下的文件一律无视。我们在parse_git_diff里加了白名单：只处理git ls-files返回的文件。
第二，LLM 沙箱化。Ollama 运行在专用用户ollama下，sudo -u ollama ollama serve，且ollama用户对代码仓库目录只有读权限，无写权限。
第三，API 密钥零存储。如果未来要接入私有 LLM API，密钥必须从环境变量读取（`os.getenv('LLM_API_KEY')