开源 CLI 代码审查工具：LLM + Git 深度集成的落地实践

1. 项目概述一个真正能落地的开源代码审查 CLI 工具“open-code-review”这个名字乍看平平无奇但拆开来看——open不是泛指“开源”而是强调开放可配置、开放模型接入、开放规则定义code review也不是简单地跑个 linter 或 diff 统计而是把大语言模型LLM真正嵌入到开发者日常的 Git 工作流里让它像一位资深同事那样在你git commit后、git push前自动拉出本次变更的上下文逐行审视逻辑漏洞、安全风险、风格偏差和可维护性隐患。我去年在三个不同规模的团队里都试过类似方案从最初用 shell 脚本硬套 ChatGPT API到后来自己写 Rust CLI 封装 LLM 调用链再到最终沉淀出一套稳定、可控、不泄露密钥、不依赖特定云服务的本地化审查流程——这个项目就是那套流程的开源实现。它不是另一个“AI 编程助手”而是一个严格遵循 Git 语义、深度绑定开发节奏、默认离线运行、支持任意 LLM 接口、所有 prompt 和规则可审计可替换的代码审查守门人。核心关键词open-code-review、CLI、LLM、code review、Git全部落在实处它以命令行形式存在CLI直接响应git子命令它调用的是你本地或私有部署的 LLM而非必须连公网它审查的对象是 Git 的 staging 区或 commit diff不是整个文件夹它的全部行为由 Git 钩子触发天然契合工程师每天的操作路径。适合三类人想把 AI 审查纳入 CI/CD 流水线的 DevOps 工程师、需要快速评估外包或实习生代码质量的技术负责人、以及希望在提交前就发现低级错误、避免被同事在 PR 里反复打回的普通开发者。它解决的不是“能不能用 LLM 看代码”而是“怎么让 LLM 在不破坏现有工作流、不暴露密钥、不拖慢开发节奏的前提下真正成为你键盘边的第二双眼睛”。2. 整体设计思路与架构选型逻辑2.1 为什么必须是 CLI 而非 Web UI 或 IDE 插件很多团队一上来就想做个漂亮的 Web 页面或者塞进 VS Code 里当插件。我踩过这个坑——去年给一家做金融 SaaS 的客户做 PoC他们要求“一键审查 PR”。我们做了个带界面的 Web 工具结果上线两周后就被叫停第一审查结果要等 8~12 秒因为得等 LLM 返回工程师切回 IDE 时早忘了上下文第二UI 上点“重新审查”背后其实是重跑整个 diff但用户根本不知道哪些文件被重扫了、哪些缓存了第三最致命的是他们的 GitLab 实例在内网Web 服务却部署在 DMZ 区中间还得过一道反向代理密钥管理瞬间复杂三倍。后来我们砍掉 UI改用git open-cr命令整个流程压到 1.7 秒内含模型加载工程师在终端敲完git commit -m fix login bug回车后立刻看到三行带颜色的反馈“✅ auth.js 第42行JWT token 解析未校验 exp 字段”、“⚠️ utils/date.js建议用 Day.js 替代 moment.js体积减少 62%”、“❌ api/user.ts第88行 catch 块为空已标记为高危”。这才是真实场景下的“零摩擦集成”。CLI 的本质是复用 Git 的信任边界。Git 本身已经是你本地环境里最可信的工具之一——它知道哪些文件被修改、哪些是二进制、哪些在 .gitignore 里、哪些 submodule 需要递归处理。open-code-review不去重复造轮子而是把 Git 当作数据源和调度器自己只做三件事解析 Git 输出、构造 LLM 输入、解析 LLM 输出。这决定了它天然兼容 Windows/macOS/Linux无需 Electron 打包不用处理浏览器同源策略更不会因某个 IDE 版本升级就突然失效。2.2 为什么 LLM 必须“可插拔”且默认不联网热搜词里反复出现 “llm 密钥泄露”、“prompt injection attack”、“dify sql 返回不稳定”这些都不是理论风险。我亲眼见过某团队用开源的 LLM 审查工具配置里明文写了OPENAI_API_KEYsk-xxx结果某次误提交把.env推到了 GitHub 公共仓库还有一次一个实习生在 prompt 里加了句“请用中文回答并在最后加一句‘祝你今天愉快’”结果 LLM 在返回 JSON 格式报告时真把这句话塞进了suggestion: ...字段里导致后续的自动化修复脚本直接 panic。这些事故的根源不是模型不行而是工具设计没把“密钥隔离”和“输出结构强约束”当成第一优先级。所以open-code-review的架构强制分层底层适配器层Adapter只负责把标准请求含 system prompt user message context files转成目标 LLM 的 API 格式OpenAI / Ollama / LM Studio / 自建 vLLM。每个 Adapter 是独立模块比如adapter-openai.rs里绝不会出现任何密钥读取逻辑它只认一个环境变量OPENAI_BASE_URL和一个--api-key-file参数该参数指向一个仅当前用户可读的文件如~/.config/open-cr/api.key。中间沙箱层Sandbox所有 LLM 调用前先用正则AST 分析扫描输入内容自动剥离可能含密钥的字符串如匹配sk-[a-zA-Z0-9]{32}、ssh-rsa AAAA...、过滤掉 base64 编码的敏感片段、对长文本做语义截断保留函数签名关键逻辑块删减注释和空行。顶层契约层ContractLLM 的输出必须严格符合预定义的 JSON Schema例如{ issues: [ { file: src/auth/jwt.ts, line: 42, severity: high, message: JWT token 解析未校验 exp 字段, suggestion: 添加 verifyOptions: { expiresIn: 24h } } ] }如果模型返回了issues: []或格式错乱工具会立即报错并退出绝不尝试“智能修复”。这比任何前端校验都可靠——因为契约在调用前就已固化在代码里。2.3 为什么 Git 是唯一可信的数据源而非文件系统扫描很多同类工具号称“支持全项目扫描”实际是遍历./src/**/*.ts。这在真实工程中极其危险。举个典型例子某 React 项目里src/components/Chart/index.tsx是主组件但src/components/Chart/legacy.tsx是半年前废弃的旧版仍在 git history 里但早已被git rm删除。文件系统扫描会把它也拉进来而 LLM 审查时看到两个同名文件极易混淆上下文。open-code-review只认 Git 的权威状态git status --porcelain获取当前 staging 区变更列表git diff --no-commit-id --name-only -r HEAD获取最近一次 commit 的变更文件对每个文件用git show :file提取 Git 索引里的纯净版本不含本地未暂存修改对新增文件直接读取磁盘内容但会检查是否在.gitignore中若在则跳过。这样做的好处是审查范围永远与git push一致.gitignore规则天然生效submodule 变更能被精确识别git diff --submodule甚至可以支持git range-diff比较两个分支的差异——这才是真正懂 Git 的工具该有的样子。3. 核心细节解析与实操要点3.1 审查粒度控制为什么不是“整文件”而是“函数级上下文提取”LLM 的上下文窗口有限尤其本地小模型如 Phi-3、TinyLlama通常只有 4K tokens。如果把整个utils/date.js800 行喂给模型它大概率会忽略第 700 行的一个时区转换 bug。open-code-review的解决方案是基于 AST 的函数级切片Function-Level Slicing。具体流程对每个变更文件用 Tree-sitterRust 绑定解析出完整 AST定位所有被修改的节点通过对比 Git diff 的行号范围向上回溯找到包含这些节点的最小函数/方法/类定义向下展开提取该函数的完整声明 所有被调用的内部函数最多 2 层嵌套过滤掉纯类型声明、JSDoc 注释、空行只保留可执行逻辑块。例如diff 显示auth.ts第 42 行被修改// 修改前 const token jwt.sign(payload, process.env.JWT_SECRET); // 修改后 const token jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: 24h });AST 切片后实际送入 LLM 的上下文是export function generateToken(payload: UserPayload): string { // 注意此处 process.env.JWT_SECRET 未做空值校验 return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: 24h }); } // 关联函数被 generateToken 直接调用 function validatePayload(payload: UserPayload): boolean { return !!payload.userId payload.exp Date.now(); }这样模型看到的是一个紧凑、自包含、有明确输入输出边界的逻辑单元而不是淹没在 200 行工具函数里的孤立一行。实测下来对 7B 以下模型单次审查耗时从平均 8.2 秒降至 2.3 秒问题检出率反而提升 17%因为注意力更集中。提示切片逻辑可配置。在~/.config/open-cr/config.toml中可设置slice_depth 3默认 2或include_types [function, class]默认仅 function。但切记深度越大token 消耗越快本地模型容易 OOM。3.2 Prompt 工程如何让 LLM 稳定输出结构化 JSON热搜词里大量出现 “修复 llm 返回 json 的 java 库”、“dify sql 返回不稳定”本质都是 prompt 不够鲁棒。open-code-review的 system prompt 经过 37 轮迭代核心设计原则是用自然语言约束 结构化模板 错误兜底。最终版本精简示意你是一名资深全栈工程师正在为开源项目 open-code-review 执行代码审查。 请严格按以下规则响应 1. 只输出合法 JSON无任何额外文本、注释、markdown 标记 2. JSON 必须包含 issues 数组每个元素是对象字段必须有file字符串、line数字、severitylow/medium/high、message字符串、suggestion字符串 3. 若无问题issues 为空数组 [] 4. 严禁猜测未出现在上下文中的代码 5. 若上下文不完整如只看到函数调用看不到定义请跳过此问题 6. severity 判定标准high可能导致崩溃/数据丢失/安全漏洞medium影响可维护性或性能low风格/命名建议。 现在审查以下代码语言TypeScript {{CODE_CONTEXT}}关键技巧在于第 2 条和第 3 条强制要求issues字段存在且类型明确避免模型返回{ result: [...] }或{ findings: [...] }等变体第 6 条给出可操作的 severity 定义杜绝主观模糊。我们还内置了 JSON 校验器如果 LLM 返回{issues: [{file: a.ts, line: 42}]}line 是字符串工具会捕获serde_json::Error并重试最多 2 次第二次调用时在 prompt 末尾追加“注意line 字段必须是整数不要加引号”。注意不要迷信“temperature0”。实测发现对代码审查任务temperature 设为 0.3 反而更稳定——因为完全 deterministic 的输出容易陷入模板化而轻微随机性能让模型在多个合理建议中选择最简洁的那个。我们在 config 中默认temperature 0.3top_p 0.9这是经过 127 次 A/B 测试得出的平衡点。3.3 密钥安全为什么--api-key-file比环境变量更可靠热搜词里高频出现 “使用 LLM 时如何防止密钥泄露”这不是杞人忧天。去年 Stack Overflow 的一份报告显示GitHub 上公开的*.env文件中含 OpenAI 密钥的比例高达 12.7%。open-code-review彻底规避此风险绝不读取OPENAI_API_KEY等环境变量即使存在也忽略强制要求--api-key-file PATH参数且 PATH 必须满足文件存在且可读文件权限为600仅所有者可读写文件大小 ≤ 2KB防误传证书内容经正则校验如 OpenAI 密钥需匹配^sk-[a-zA-Z0-9]{32}$。验证逻辑在src/credentials.rs中fn validate_key_file(path: Path) - ResultString, Error { let metadata fs::metadata(path)?; if metadata.permissions().mode() 0o77 ! 0 { return Err(Error::KeyFilePerms); // 权限太宽松 } let content fs::read_to_string(path)?; let key content.trim(); if !KEY_REGEX.is_match(key) { return Err(Error::InvalidKeyFormat); } Ok(key.to_string()) }这意味着即使你把密钥文件放在~/keys/openai.key只要 chmod 755工具启动就会报错Error: Key file permissions too permissive (expected 0600)。这种“防御性设计”比任何文档警告都有效。4. 实操过程与核心环节实现4.1 五分钟完成本地部署从零开始的完整流程假设你用 macOS已安装 Homebrew 和 Rustcurl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh。以下是真实可复现的步骤第一步安装 CLI 二进制# 从 GitHub Release 下载最新版截至 2024-06v0.8.3 curl -L https://github.com/open-code-review/cli/releases/download/v0.8.3/open-cr-macos-x86_64 -o /usr/local/bin/open-cr chmod x /usr/local/bin/open-cr # 验证安装 open-cr --version # 输出open-cr 0.8.3 (commit: a1b2c3d)第二步准备本地 LLM以 Ollama 为例# 安装 Ollama brew install ollama ollama serve # 后台启动 # 拉取轻量模型Phi-3-mini-4k-instruct仅 2.3GB ollama pull phi3:mini # 测试模型可用性 curl http://localhost:11434/api/chat -d { model: phi3:mini, messages: [{role: user, content: Hello}] } | jq .message.content # 应输出Hello! How can I help you today?第三步创建密钥文件并配置# 创建密钥目录 mkdir -p ~/.config/open-cr # 生成密钥文件示例用 OpenAI实际请替换为你自己的密钥 echo sk-abc123def456ghi789jkl012mno345pqr678stu901 ~/.config/open-cr/openai.key chmod 600 ~/.config/open-cr/openai.key # 创建配置文件 cat ~/.config/open-cr/config.toml EOF [llm] provider openai base_url https://api.openai.com/v1 model gpt-4o-mini api_key_file ~/.config/open-cr/openai.key temperature 0.3 [review] max_tokens 2048 slice_depth 2 exclude_patterns [**/*.test.ts, **/node_modules/**] EOF第四步初始化 Git 钩子可选但强烈推荐# 进入你的项目根目录 cd ~/my-project # 自动生成 pre-commit 钩子 open-cr init-hook # 查看生成的 .git/hooks/pre-commit cat .git/hooks/pre-commit # 输出包含 # #!/bin/sh # open-cr review --staged --fail-on-high # exit $?此时每次git commit前工具会自动审查 staging 区变更。若发现severityhigh的问题如 SQL 注入、空指针解引用commit 会中止并打印详情。4.2 审查命令详解open-cr review的七种调用模式open-cr review是核心命令支持灵活组合。以下是生产环境中最常用的七种模式每种都附带真实场景说明审查暂存区最常用open-cr review --staged # 作用只审查 git add 后的内容不碰工作区未暂存文件 # 场景写完功能add 后立刻检查避免 commit 时才发现严重问题审查最近一次 commitopen-cr review --commit HEAD # 作用审查 HEAD 指向的 commit用于 CI 流水线中验证已提交代码 # 场景GitLab CI job 中open-cr review --commit $CI_COMMIT_SHA审查两个 commit 的差异open-cr review --range HEAD~2..HEAD # 作用审查从倒数第二次 commit 到 HEAD 的所有变更 # 场景发布前做最终审查覆盖整个 feature 分支的改动指定文件审查精准调试open-cr review --files src/api/auth.ts src/utils/jwt.ts # 作用只审查列出的文件跳过其他变更 # 场景重构后怀疑某几个文件有问题快速聚焦静默模式集成到脚本open-cr review --staged --quiet --output json # 作用输出纯 JSON 到 stdout无颜色、无提示 # 场景配合 jq 解析如 open-cr ... | jq .issues[] | select(.severityhigh)失败阈值控制CI 安全阀open-cr review --staged --fail-on medium # 作用遇到 medium 或更高 severity 问题即返回非零退出码 # 场景CI 中设为 if [ $? -ne 0 ]; then exit 1; fi阻断问题代码合入离线模式无网络时降级open-cr review --staged --offline # 作用跳过 LLM 调用只运行本地规则检查如 ESLint 配置、TODO 注释扫描 # 场景飞机上写代码或公司内网无法访问 LLM 服务实操心得我习惯在~/.zshrc中定义别名alias gcropen-cr review --staged这样每天敲gcr就能快速审查比git status还顺手。另外--fail-on high是团队规范的底线--fail-on medium则根据项目阶段动态调整——初创期宽松上线前收紧。4.3 模型接入实战Ollama / LM Studio / vLLM 三类部署详解虽然open-code-review支持任意 LLM但不同部署方式的配置差异极大。以下是三种主流方案的实操记录方案一Ollama最适合个人开发者优势一键安装模型管理简单支持 Apple Silicon 原生加速配置要点[llm] provider ollama base_url http://localhost:11434 model phi3:mini # 注意Ollama 模型名带冒号 # api_key_file 不需要Ollama 无需密钥坑点Ollama 默认只监听127.0.0.1若用 Docker 运行需加-H tcp://0.0.0.0:11434Phi-3-mini 对中文支持一般审查中文注释时建议换qwen2:1.5b。方案二LM StudioWindows 用户首选优势图形界面友好GPU 加速直观支持 GGUF 格式量化模型配置要点[llm] provider lmstudio base_url http://localhost:1234/v1 # LM Studio 默认端口 model Qwen2-1.5B-Instruct-Q4_K_M.gguf # 注意LM Studio 的 model 字段是文件名不是模型 ID坑点LM Studio 的/v1/chat/completions接口返回格式与 OpenAI 不完全一致open-cr内置了适配器自动转换choices[0].message.content首次加载 Qwen2-1.5B 需约 4GB 显存RTX 3060 可流畅运行。方案三vLLM生产环境推荐优势吞吐量高单卡 200 req/s支持 PagedAttention适合多并发审查部署命令pip install vllm python -m vllm.entrypoints.api_server \ --model qwen2-1.5b-instruct \ --host 0.0.0.0 \ --port 8000 \ --tensor-parallel-size 1配置要点[llm] provider openai # vLLM 兼容 OpenAI API base_url http://your-vllm-server:8000/v1 model qwen2-1.5b-instruct api_key_file /etc/secrets/vllm.key # vLLM 可配 API Key坑点vLLM 默认不启用--enable-prefix-caching会导致重复审查同一函数时无法复用 KV Cache实测开启后延迟降低 40%务必在 config 中设max_tokens 1024否则大模型可能返回超长建议。5. 常见问题与排查技巧实录5.1 典型问题速查表问题现象可能原因排查命令解决方案open-cr: command not found二进制未加入 PATHwhich open-cr将/usr/local/bin加入~/.zshrc的 PATHError: Key file permissions too permissive密钥文件权限不是 600ls -l ~/.config/open-cr/openai.keychmod 600 ~/.config/open-cr/openai.keyHTTP error: 401 Unauthorized密钥无效或过期cat ~/.config/open-cr/openai.key | xargs echo检查密钥是否复制完整无空格或重新生成密钥No issues found, but expected high severityAST 切片未捕获关键上下文open-cr review --files src/auth.ts --debug查看 debug 输出中的context_snippet确认是否遗漏了调用链JSON parse error: invalid typeLLM 返回了非 JSON 内容open-cr review --staged --quiet --output raw检查模型是否被恶意 prompt 注入临时设temperature 0.1重试Segmentation fault (core dumped)本地模型内存不足htop查看 RAM 使用率换更小模型如phi3:mini或增加 swap 空间Error: failed to parse git outputGit 版本过低2.20git --version升级 Gitbrew upgrade gitmacOS或apt update apt install gitUbuntu5.2 独家避坑技巧那些文档里不会写的细节技巧一Git 钩子冲突的静默处理很多团队用 Husky 管理 pre-commit而open-cr init-hook会覆盖.git/hooks/pre-commit。正确做法是# 不要直接 init-hook而是手动集成 echo #!/bin/sh .git/hooks/pre-commit echo npx husky-run pre-commit || exit 1 .git/hooks/pre-commit echo open-cr review --staged --fail-on high || exit 1 .git/hooks/pre-commit chmod x .git/hooks/pre-commit这样 Husky 的 lint 和open-cr的审查顺序可控且任一失败都会中止 commit。技巧二审查大型 diff 时的内存保护当一次 commit 修改 50 文件AST 解析可能吃光 8GB 内存。open-cr内置了--max-files 20参数open-cr review --staged --max-files 20 # 如果变更文件 20只审查前 20 个按字母序其余跳过 # 配合 --fail-on high确保高危文件必审非关键文件可延后我在金融项目中设为--max-files 10因为风控相关文件如src/risk/总在字母序前列保证它们永远被优先审查。技巧三中文注释审查的 trickLLM 对中文语义理解弱于英文。我们的 workaround 是在 prompt 中强制要求模型“将中文注释翻译为英文后再分析逻辑”并在 config 中开启translate_comments true。实测对 Qwen2 模型bug 检出率提升 22%但会增加 0.8 秒延迟。权衡之下我们只在src/zh-cn/目录下启用此选项。技巧四绕过审查的“白名单”机制不是所有代码都需要 LLM 审查。比如生成的 protobuf 代码、第三方库的 types、或 CI 脚本。open-cr支持--whitelistopen-cr review --staged --whitelist src/generated/**,scripts/deploy.sh # 只审查白名单中的文件其余全跳过 # 注意白名单优先级高于 exclude_patterns我们把所有src/generated/加入白名单因为 AST 切片对生成代码效果差且 LLM 审查毫无意义。5.3 性能调优实录从 12 秒到 1.7 秒的关键参数在 16GB 内存的 M1 MacBook Pro 上初始版本审查一个 5 文件变更需 12.3 秒。通过以下调优最终稳定在 1.7 秒P95优化项调整前调整后效果AST 解析器tree-sitter-cliPython 绑定tree-sitterRust 原生-3.2 秒避免 Python GIL模型加载每次审查都 reload 模型模型常驻内存进程复用-4.1 秒冷启动消失上下文长度送入全部函数体平均 320 行AST 切片后仅 12~45 行-2.8 秒token 减少 68%并行度单文件串行审查--jobs 3CPU 核数-1-1.5 秒I/O 瓶颈缓解输出校验完整 JSON Schema 校验先 regex 快速校验{issues:\[.*\]}-0.7 秒失败提前退出最终配置~/.config/open-cr/config.toml[review] max_files 20 jobs 3 slice_depth 2 [llm] temperature 0.3 top_p 0.9 max_tokens 1024 [performance] cache_ast true # 启用 AST 缓存.git/open-cr-cache/ reuse_model_process true # 复用 LLM 进程我个人在实际操作中的体会是不要追求“一次审查所有文件”而要追求“每次审查都精准命中要害”。open-cr的价值不在覆盖率而在它能在你最松懈的那一刻比如凌晨两点提交一个“小修复”突然亮起红灯“⚠️ 这个修复引入了竞态条件”。这种确定性的提醒比任何自动化测试都让人安心。