企业官网建设流程全解析

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

open-code-review 这个名字乍看像某个具体软件，但实际它代表的是一类正在快速演进的工程实践——用开源技术栈、命令行界面（CLI）和大语言模型（LLM）能力，构建一套不依赖商业 SaaS 平台、不上传源码至第三方服务器、完全可控的自动化代码审查体系。我从 2022 年底开始在团队内部推动这件事，最初只是想解决一个很现实的问题：PR（Pull Request）评审经常卡在“没人看”“看了也只扫两眼”“意见太笼统没实操价值”上。后来发现，真正卡点不在人，而在流程本身——GitHub/GitLab 的 Web UI 审查界面，本质上是个信息孤岛：它把代码、上下文、历史变更、风格规范、安全规则全割裂开，评审者得在多个标签页间反复切换，手动查 commit diff、翻文档、比对 CI 日志，效率极低。而 open-code-review 的核心价值，恰恰是把这套分散动作，压缩进一次git review --auto命令里，让 LLM 在本地或私有环境中，基于真实 Git 上下文做结构化分析。

它不是替代人工评审，而是把人从“找问题”的体力劳动中解放出来，专注在“判问题”和“定方案”上。比如，当 LLM 检出一段 SQL 查询缺少参数绑定，它不会只说“存在 SQL 注入风险”，而是直接定位到user_id = request.args.get('id')这一行，指出“此处未使用 SQLAlchemy 的bindparam或text()参数化机制”，并附上修改后的三行示例代码。这种颗粒度，是传统静态扫描工具（如 SonarQube）做不到的，也是闭源 AI 编程助手（如 GitHub Copilot 的 PR Review 功能）不愿/不能提供的——因为后者必须把你的代码发到云端，而 open-code-review 的整个 pipeline，从 Git 提交解析、AST 抽取、上下文拼接，到 LLM 推理、结果格式化，全部跑在你自己的机器或内网服务器上。关键词里的 “CLI” 不是噱头，它是信任边界的物理锚点：只要你不执行curl | bash，不配置公网 API Key，整个流程就始终处于你的控制域内。这也是为什么 “使用 LLM 时如何防止密钥等鉴权信息泄露” 会成为热搜词——大家已经意识到，模型能力再强，一旦输入数据失控，就是灾难。open-code-review 的设计哲学，就是把“数据不出域”作为第一性原则，而不是事后打补丁。

适合谁来参考？如果你是中小型技术团队的 Tech Lead，正被 PR 积压困扰；如果你是开源项目维护者，想给贡献者提供即时、一致的反馈；如果你是安全合规要求严格的金融/政企开发者，连 CI 流水线都必须跑在离线环境；甚至如果你只是个喜欢折腾的个人开发者，想搞清楚“LLM 到底怎么读懂我的代码”——这个项目都值得你花 45 分钟搭起来跑一遍。它不追求“一键全自动”，而是提供一套可拆解、可替换、可审计的模块化链条：Git 是源头活水，CLI 是调度中枢，LLM 是分析引擎，而所有中间产物（diff patch、AST JSON、prompt template）都是明文可读的。没有黑盒，没有魔法，只有清晰的输入输出契约。接下来我会带你一层层剥开这个链条，告诉你每个环节为什么这么选、怎么调、踩过哪些坑。

2. 整体架构设计与核心思路拆解：为什么必须是 CLI + Git + 本地 LLM 的三角闭环

open-code-review 的架构看起来简单，但背后每一步选择都经过大量试错。我最初也走过弯路：试过用 Webhook 接 GitHub API 拉取 PR 数据，再转发给远程 LLM API；也试过用 VS Code 插件在编辑器里实时分析。结果发现两个致命问题：一是网络延迟让反馈周期拉长到 10 秒以上，失去“即时性”这个核心体验；二是任何涉及外部服务的环节，都会引入不可控变量——API 限流、模型返回格式漂移、Token 超时、甚至服务商突然调整计费策略。最终确定的三角闭环（CLI + Git + 本地 LLM），本质是用确定性对抗不确定性。

2.1 Git 作为唯一可信数据源：为什么不用 GitHub API？

Git 仓库本地存储的不仅是代码，更是完整的变更历史、分支拓扑、提交元数据（author、date、commit message）、以及精确到行的 diff 信息。这些数据天然具备三个优势：原子性（一次git diff输出就是本次变更的完整快照）、一致性（不受 API 版本迭代影响）、零延迟（毫秒级响应）。相比之下，GitHub API 返回的files字段是经过服务端处理的简化版，丢失了空行、缩进细节、甚至部分二进制文件的 diff 信息；更关键的是，它无法获取git blame的逐行作者信息，而这恰恰是判断“这段可疑代码是谁加的、什么时候加的、当时有没有相关 issue” 的关键上下文。

我做过对比测试：对同一个 PR，用gh api repos/{owner}/{repo}/pulls/{pr}/files获取文件列表，再逐个请求contents，平均耗时 3.2 秒；而git diff --name-only HEAD~1...HEAD只需 0.012 秒。更重要的是，API 方式无法获取git log -p -n 5 --grep="fix sql"这类语义化搜索结果，而本地 Git 命令可以瞬间完成。所以 open-code-review 的第一步永远是git fetch origin main && git diff --unified=3 origin/main...HEAD，它生成的 Unified Diff 格式，是后续所有分析的基石。这个 diff 不仅包含增删行，还包含函数签名、文件路径、hunk 头（@@ -123,5 +128,7 @@），这些信息让 LLM 能准确定位上下文范围，避免“张冠李戴”。

2.2 CLI 作为调度中枢：为什么拒绝 GUI 和 Web 界面？

GUI 和 Web 界面在用户体验上确实友好，但它们引入了额外的抽象层和状态管理复杂度。一个按钮点击背后，可能是 React 组件状态更新、WebSocket 消息推送、前端缓存刷新、跨域请求配置……任何一个环节出问题，用户看到的就是“加载中”转圈。而 CLI 的哲学是“所见即所得”：你输入什么命令，就得到什么输出，没有隐藏状态，没有异步回调陷阱。更重要的是，CLI 天然适配 CI/CD 流水线——你可以把它嵌入pre-commit hook，也可以放在 Jenkins 的Execute shell步骤里，甚至集成到 GitOps 工具链中。我们团队就把它配置在git commit后自动触发：git config --global core.hooksPath .githooks，然后在.githooks/pre-commit里写open-code-review --stage --fix，这样每次提交前，它会自动检查 staged 文件，对能自动修复的问题（如 PEP8 格式错误、TODO 注释）直接git add，不能修的则打印警告。这种侵入式集成，GUI 根本做不到。

另一个常被忽视的优势是调试便利性。当分析结果出错时，GUI 用户只能看到“分析失败”，而 CLI 用户可以直接加-v参数看到完整日志：open-code-review --diff-file pr.diff --model llama3:8b --verbose，你会看到它如何解析 diff、如何构造 prompt、LLM 返回的原始 JSON、以及最终渲染的 Markdown。这种透明度，是构建可信系统的前提。

2.3 本地 LLM 作为分析引擎：为什么坚持 offline inference？

热搜词里反复出现的 “llm 代理地址”、“llm 框架”、“dify 的 sql 查询内容太多导致 llm 返回不稳定”，都指向一个事实：调用远程 LLM API 就像租用别人的厨房——你不知道灶具温度是否稳定，油盐酱醋是不是过期，厨师今天心情好不好。而本地运行 LLM（如 Ollama 的llama3:8b、LM Studio 的Phi-3-mini），意味着你完全掌控推理环境。我们实测过：在 32GB 内存的 M2 Mac 上，llama3:8b处理 500 行 diff 的平均响应时间是 4.7 秒，标准差仅 0.3 秒；而同等条件下调用某公有云 LLM API，P95 延迟高达 12.8 秒，且偶尔返回{"error": "rate limit exceeded"}。稳定性差异直接决定了它能否融入开发工作流。

更重要的是数据安全。热搜词 “使用 LLM 时如何防止密钥等鉴权信息泄露” 直击痛点。我们曾用git grep -n "API_KEY\|SECRET" -- '*.py'扫描过内部仓库，发现 17 处硬编码密钥。如果把这些文件丢给远程 LLM，等于主动泄露敏感信息。而本地 LLM 的 prompt 构造逻辑里，有一条铁律：所有输入文本必须经过严格清洗。我们的sanitize_diff()函数会扫描每一行，匹配正则r'(?:password|secret|key|token|credential).*[:=]\s*[\'"]([^\'"]+)[\'"]'，并将匹配到的值替换为[REDACTED]。这个过程在本地内存中完成，数据 never leaves your machine。你可能会问：“本地跑 LLM 不是需要很强的 GPU 吗？” 其实不然。像Phi-3-mini（3.8B 参数）在 CPU 上就能跑出可用效果，llama3:8b在 Apple Silicon 上已足够流畅。我们甚至用llama3:1b在树莓派 5 上跑过基础语法检查——它不追求“完美回答”，而是提供“可验证的线索”，这恰恰符合代码审查的本质：不是替你写代码，而是帮你更快找到问题。

3. 核心细节解析与实操要点：从 diff 解析到 prompt 工程的全链路拆解

open-code-review 的威力，不在于它用了多大的模型，而在于它如何把 Git 的原始数据，转化为 LLM 能理解的结构化上下文。这个转化过程，就是它的核心技术壁垒。下面我带你走一遍从git diff输出到最终审查报告的完整链条，每个环节都附上真实代码片段和避坑心得。

3.1 Diff 解析与上下文提取：不只是“增删行”，而是构建代码宇宙

一个典型的git diff输出如下：

diff --git a/src/utils/db.py b/src/utils/db.py index abc123..def456 100644 --- a/src/utils/db.py +++ b/src/utils/db.py @@ -120,5 +120,7 @@ def get_user_by_id(user_id): cursor.execute("SELECT * FROM users WHERE id = " + str(user_id)) return cursor.fetchone() +def get_user_by_email(email): + cursor.execute("SELECT * FROM users WHERE email = '" + email + "'") + return cursor.fetchone()

单纯把这段文本喂给 LLM，效果很差——模型不知道a/src/utils/db.py是旧文件还是新文件，不清楚+120,7中的120是原文件行号还是新文件行号，更无法关联到get_user_by_id函数的实现逻辑。所以我们设计了一个DiffParser类，它做三件事：

1. 文件级元数据提取：解析diff --git a/... b/...行，获取变更文件路径、模式（new file/modified/deleted）；
2. hunk 级上下文重建：对每个@@ -L,N +L,N @@区块，提取其前后各 3 行“锚点代码”（anchor lines）。例如上面的@@ -120,5 +120,7 @@，我们会从src/utils/db.py中读取第 117-122 行（旧文件）和第 117-124 行（新文件），构建成一个带行号的上下文块；
3. AST 辅助增强：对 Python/JS 等语言，用ast.parse()或esprima解析变更区域附近的 AST 节点，提取函数名、参数列表、调用关系。比如cursor.execute(...)这行，AST 能告诉我们它属于get_user_by_email函数，且email参数来自函数入参，而非request对象。

提示：不要试图用正则匹配所有语言的 AST！我们只对主流语言（Python、JavaScript、TypeScript、Go）做了 AST 支持，其他语言退化为纯文本上下文。实测下来，Python 的ast模块最稳定，JS 的acorn解析速度最快，Go 的go/parser需要先go list -f '{{.Dir}}' ./...获取模块路径才能正确解析 imports。

这个过程产出的不是字符串，而是一个结构化对象：

{ "file_path": "src/utils/db.py", "change_type": "modified", "hunks": [ { "old_start": 120, "old_lines": 5, "new_start": 120, "new_lines": 7, "anchor_before": ["def get_user_by_id(user_id):", " cursor.execute(\"SELECT * FROM users WHERE id = \" + str(user_id))"], "anchor_after": [" return cursor.fetchone()"], "added_lines": ["def get_user_by_email(email):", " cursor.execute(\"SELECT * FROM users WHERE email = '\" + email + \"'\")", " return cursor.fetchone()"], "ast_context": {"function_name": "get_user_by_email", "params": ["email"], "calls": ["cursor.execute"]} } ] }

这个对象才是 LLM 的理想输入。它把零散的 diff 行，组织成有层次、有关联、有语义的“代码宇宙”。

3.2 Prompt 工程：如何让 LLM 理解“代码审查”这个任务

很多团队失败的原因，是把 LLM 当成万能黑盒，随便扔个Please review this code就完事。结果模型要么泛泛而谈“代码可读性有待提高”，要么过度发挥，把print("hello")说成“存在潜在的安全风险”。真正的 prompt 工程，是给模型一套明确的“游戏规则”。

我们的核心 prompt 模板分四部分：

# ROLE 你是一名资深后端工程师，专注于 Python Web 开发和数据库安全。你的任务是进行代码审查，只关注本次变更（diff）引入的问题，不评论未改动的代码。 # CONTEXT 以下是从 Git 仓库提取的变更上下文： [插入上一步生成的结构化对象 JSON] # RULES - 必须按 severity 分级：CRITICAL（阻断上线，如 SQL 注入、XSS）、HIGH（严重缺陷，如空指针、资源泄漏）、MEDIUM（建议优化，如重复代码、魔法数字）、LOW（风格问题，如 PEP8） - 每个问题必须包含：1) 精确行号（格式：`src/utils/db.py:122`）；2) 问题描述（不超过 20 字）；3) 风险解释（1-2 句）；4) 修复建议（带代码示例） - 禁止猜测未出现在 diff 中的信息（如“这个函数可能被其他模块调用”） - 如果无问题，返回 JSON: {"review_result": "clean", "issues": []} # OUTPUT_FORMAT 严格按以下 JSON Schema 输出，不加任何额外文本： { "review_result": "clean" | "issues_found", "issues": [ { "file": "string", "line": "number", "severity": "CRITICAL" | "HIGH" | "MEDIUM" | "LOW", "summary": "string", "explanation": "string", "suggestion": "string", "code_example": "string" } ] }

这个 prompt 的设计逻辑很明确：用结构约束代替自由发挥。ROLE定义专业背景，避免模型胡乱跨界；CONTEXT提供精准输入，杜绝幻觉；RULES是硬性契约，特别是“禁止猜测未出现在 diff 中的信息”这一条，砍掉了 70% 的无效输出；OUTPUT_FORMAT强制 JSON，方便后续程序解析。我们测试过不同模型对同一 prompt 的响应一致性：llama3:8b的 JSON 格式合规率是 98.2%，Phi-3-mini是 94.7%，而某公有云 API 在高负载时会返回{"error": "invalid json"}。

注意：不要迷信“越长越好”的 prompt。我们曾把 prompt 扩充到 2000 字，加入各种示例和边界说明，结果模型反而更倾向于复述示例，忽略真实 diff。现在的版本是经过 37 次 A/B 测试迭代出来的最优长度——它足够约束行为，又留出模型发挥空间。

3.3 结果渲染与交互：CLI 如何把 JSON 变成开发者友好的反馈

LLM 返回的 JSON 只是中间产物，最终呈现给开发者的是终端里的彩色文字。这里的关键是“信息密度”和“操作引导”的平衡。一个糟糕的设计是把所有 JSON 原样print(json.dumps(result, indent=2))，那用户得自己滚动查找。我们的ReviewRenderer类做了三件事：

1. 分级折叠显示：CRITICAL 和 HIGH 问题默认展开，MEDIUM 和 LOW 问题默认折叠，用▶符号标记可展开项；
2. 一键跳转支持：每行问题末尾添加#L122锚点，VS Code 用户点击即可跳转到对应行；终端里用open-code-review --jump src/utils/db.py:122可直接打开编辑器；
3. 批量操作指令：在报告底部生成git checkout -- src/utils/db.py（撤销修改）、git add src/utils/db.py（暂存修复）等快捷命令，用户复制粘贴即可执行。

渲染效果示例：

🔍 代码审查报告 (2 issues found) ─────────────────────────────────────────────────── ❌ CRITICAL: SQL 注入风险 src/utils/db.py:122 cursor.execute("SELECT * FROM users WHERE email = '" + email + "'") → 风险：字符串拼接直接将用户输入注入 SQL，可被构造恶意 payload → 建议：使用参数化查询 → 示例：cursor.execute("SELECT * FROM users WHERE email = ?", (email,)) ⚠️ HIGH: 函数缺少类型注解 src/utils/db.py:121 def get_user_by_email(email): → 风险：降低 IDE 自动补全准确率，增加后期维护成本 → 建议：为参数和返回值添加类型提示 → 示例：def get_user_by_email(email: str) -> Optional[dict]: ─────────────────────────────────────────────────── 💡 下一步操作： • 修复后运行：git add src/utils/db.py && git commit -m "fix: prevent SQL injection in get_user_by_email" • 查看全部问题：open-code-review --show-all • 跳转到问题行：open-code-review --jump src/utils/db.py:122

这个设计让反馈不再是“阅读题”，而是“操作指南”。数据显示，采用此渲染方式后，开发者对 HIGH 及以上问题的修复率从 43% 提升到 89%。

4. 实操过程与核心环节实现：手把手搭建你的第一个 open-code-review 环境

现在，让我们把前面讲的所有理论，变成你电脑上可运行的命令。整个过程分为四个阶段：环境准备、模型部署、工具安装、工作流配置。全程无需 root 权限，Windows/macOS/Linux 通用。我以 macOS 为例，但会标注其他系统的差异点。

4.1 环境准备：最小化依赖，拒绝臃肿

我们刻意避开 Docker、Kubernetes 这类重依赖，因为目标是让每个开发者都能在 5 分钟内跑起来。基础环境只需三样：

1. Git 2.30+：确保支持git diff --no-index等新特性。macOS 用户用brew install git；Windows 用户下载官方 installer（https://git-scm.com/download/win），安装时勾选 “Add Git to PATH”；Linux 用户sudo apt install git-core（Ubuntu/Debian）或sudo yum install git（CentOS/RHEL）。
2. Python 3.9+：用于运行 CLI 工具。推荐用pyenv管理多版本，避免污染系统 Python。安装命令：

   # macOS/Linux curl https://pyenv.run | bash # 按提示将 pyenv 添加到 ~/.zshrc echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc echo 'eval "$(pyenv init -)"' >> ~/.zshrc source ~/.zshrc pyenv install 3.11.8 pyenv global 3.11.8

3. Ollama（本地 LLM 运行时）：这是最关键的组件。它像一个轻量级的 LLM 应用商店，一键下载、运行、管理模型。官网下载地址 https://ollama.com/download，安装后终端输入ollama list应返回空列表，表示安装成功。

实操心得：不要用 conda 或 system Python 安装 ollama CLI！它会与 conda 的环境隔离冲突。Ollama 的二进制文件默认放在/usr/local/bin/ollama，确保它在$PATH中。如果ollama run llama3:8b报错command not found，请运行export PATH="/usr/local/bin:$PATH"并写入 shell 配置文件。

4.2 模型部署：选对模型，比调参更重要

Ollama 支持上百个模型，但并非所有都适合代码审查。我们实测过 12 个主流模型，结论很明确：小而精的代码专用模型，远胜于大而全的通用模型。以下是我们的推荐清单（按优先级排序）：

注意：deepseek是模型系列名，不是某个具体模型。热搜词里 “比如常说的 deepseek 是属于哪个”，答案是：DeepSeek 是一家公司，他们开源了DeepSeek-Coder系列（6.7B/1.3B 参数），专为代码任务优化，和 Llama、Phi 属于同等级别的开源模型，不是“LLM 框架”或 “Agent”。它和llm的关系，就像React和JavaScript的关系——前者是后者的一个具体实现。

部署命令很简单：

# 下载 codellama:7b（约 4.2GB，首次下载需耐心等待） ollama pull codellama:7b # 验证是否可用（会启动一个交互式会话） ollama run codellama:7b >>> Hello world Hello! How can I help you today? # 输入 Ctrl+D 退出

4.3 工具安装：用 pip 安装，而非 clone repo

open-code-review 的 CLI 工具名为oclr（open code review 的缩写），发布在 PyPI 上。安装命令：

pip install oclr # 验证安装 oclr --version # 输出：oclr 0.8.3

它依赖的核心包只有 5 个：gitpython（操作 Git）、requests（可选，用于未来扩展）、rich（美化终端输出）、pydantic（校验 JSON Schema）、ollama（调用本地模型）。没有 TensorFlow、PyTorch 这类重型依赖，安装耗时通常 <10 秒。

4.4 工作流配置：从单次运行到自动化集成

4.4.1 基础用法：一次审查，立竿见影

进入你的 Git 仓库，执行：

# 审查当前分支相对于 main 的所有变更 oclr --base-branch main # 审查指定文件（适合快速验证） oclr --file src/utils/db.py # 审查上次提交的变更 oclr --commit HEAD~1

4.4.2 进阶配置：定制你的审查规则

创建配置文件~/.oclr/config.yaml：

model: name: "codellama:7b" # 默认使用的模型 timeout: 30 # LLM 推理超时（秒） rules: - severity: CRITICAL pattern: "cursor\.execute\(.*\+.*\+.*\)" message: "SQL 注入风险：检测到字符串拼接 SQL" - severity: HIGH pattern: "print\(" message: "调试残留：检测到 print 语句" output: format: "markdown" # 支持 markdown / json / plain color: true # 是否启用彩色输出

这个配置文件让oclr具备了规则引擎能力。pattern是正则表达式，会在 diff 解析后预扫描，命中即直接标记，不经过 LLM——这比让 LLM 去识别print()快 100 倍。

4.4.3 自动化集成：嵌入开发习惯

这才是 open-code-review 的灵魂所在。我们把它深度集成到日常开发流中：

1. Pre-commit Hook：在项目根目录创建.pre-commit-config.yaml：

   repos: - repo: local hooks: - id: open-code-review name: Run open code review entry: oclr --staged --fix language: system types: [python, javascript] pass_filenames: false

   然后pip install pre-commit && pre-commit install。每次git commit前，它会自动审查暂存区文件，并尝试自动修复 PEP8、多余空格等问题。

2. CI/CD 集成：在.github/workflows/code-review.yml中：

   name: Code Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Ollama run: | curl -fsSL https://ollama.com/install.sh | sh ollama pull codellama:7b - name: Run open-code-review run: oclr --pr-number ${{ github.event.number }} --output json > review-report.json - name: Upload report uses: actions/upload-artifact@v3 with: name: review-report path: review-report.json

这套组合拳下来，代码审查就不再是“某个周五下午的仪式”，而是融入每一次敲击键盘的呼吸节奏里。

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

即使是最成熟的工具，也会在真实世界中遇到千奇百怪的问题。下面是我和团队在过去 18 个月里，踩过的坑、记录的日志、总结的速查表。它们不是“可能遇到”，而是“一定会遇到”。

5.1 模型响应异常：JSON 格式错误与截断问题

现象：oclr命令卡住几秒后报错JSONDecodeError: Expecting value: line 1 column 1 (char 0)，或返回的 JSON 缺少issues字段。

根本原因：LLM 在生成长文本时，可能因 token 限制被强制截断，导致 JSON 不完整；或模型在压力下输出非 JSON 文本（如Sure! Here's the review...）。

解决方案：

• 强制 JSON 模式：Ollama 从 v0.1.40 开始支持--format json参数。修改oclr的调用逻辑：

  # 替换原来的 ollama.run() 调用 import subprocess result = subprocess.run( ["ollama", "run", "--format", "json", "codellama:7b"], input=prompt.encode(), capture_output=True, timeout=30 )

• JSON 校验重试：在解析前，用正则r'\{.*\}'提取第一个{...}块，再json.loads()。如果失败，最多重试 2 次，每次增加temperature=0.3参数（降低随机性）。

5.2 Git 上下文丢失：为什么 LLM 总说“找不到函数定义”

现象：审查utils/db.py时，LLM 报告get_user_by_email函数缺少 docstring，但该函数在 diff 中是新增的，模型却认为它“已存在”。

根本原因：DiffParser在提取 anchor lines 时，错误地从HEAD（最新提交）读取了文件，而应该从HEAD~1（变更前）读取旧版本。对于新增文件，HEAD~1中该文件不存在，导致 anchor lines 为空。

解决方案：

• 智能 fallback：当git show HEAD~1:src/utils/db.py失败时，改用git ls-tree -r HEAD~1 | grep "src/utils/db.py"检查文件是否存在。若不存在，则 anchor lines 设为空数组，prompt 中明确告知模型“此为新增文件，无历史上下文”。
• 行号映射修正：新增文件的+120,7中，120是新文件行号，但 LLM 可能误以为是旧文件行号。我们在 prompt 中强制声明：“所有行号均指新文件（b/...）中的绝对行号”。

5.3 中文注释解析失败：LLM 说“看不懂这个函数名”

现象：代码中有def 获取用户信息(用户ID: int) -> dict:，LLM 返回{"review_result": "clean"}，完全忽略这个函数。

根本原因：codellama:7b训练数据中中文占比不足 5%，对中文标识符理解力弱；而llama3:8b虽支持中文，但默认 tokenizer 对中文字符切分不准。

解决方案：

• 双模型路由：在oclr中增加语言检测。用langdetect库分析 diff 中非 ASCII 字符比例，>30% 则自动切换到llama3:8b模型；
• 注释翻译前置：对中文 docstring 和注释，用googletrans库（离线版）临时翻译成英文，送入 LLM 分析，结果再反向翻译回中文。实测翻译耗时 <200ms，准确率 92%。

5.4 性能瓶颈：为什么审查一个 PR 要 2 分钟

现象：一个包含 15 个文件、2000 行变更的 PR，oclr运行时间超过 120 秒。

根本原因：默认是串行处理每个 hunk，而codellama:7b单次推理平均 6 秒，15 个文件 × 平均 3 个 hunk = 45 次调用，总耗时必然长。

解决方案：

• hunk 级并发：用concurrent.futures.ThreadPoolExecutor并行处理 hunk，线程数设为min(8, os.cpu_count())。注意 Ollama 本身是单进程，所以并发数不宜超过 4，否则模型加载竞争导致更慢；
• 结果缓存：对相同 diff hash（sha256(diff_content)）的结果，缓存到~/.oclr/cache/，有效期 24 小时。PR 重新推送时，diff hash 不变，直接返回缓存结果。

5.5 安全红线：如何确保密钥真的没泄露

现象：oclr报告一切正常，但审计发现某次 PR 中硬编码了 AWS 密钥。

根本原因：sanitize_diff()函数的正则r'(?:password|secret|key|token).*[:=]\s*[\'"]([^\'"]+)[\'"]'无法匹配os.environ.get("AWS_SECRET_ACCESS_KEY")这种间接引用。

终极防护方案：

• 三层过滤：
  1. 静态扫描：用git secrets（AWS 开源工具）预扫描所有提交，拦截含密钥的 commit；
  2. 动态脱敏：oclr的sanitize_diff()升级为 AST 驱动——对 Python，用ast.walk()找到所有Call(func=Attribute(attr='get'))节点，检查args[0].value是否为敏感 key 字符串；
  3. 沙箱执行：对疑似高危代码（如subprocess.run(...)），在隔离的 Docker 容器中执行