1. 项目概述：这不是又一个代码审查工具，而是一次对“人如何协作理解代码”的重新定义
“open-code-review”这个名字乍看平平无奇，甚至有点拗口——它不像“SonarQube”那样自带权威感，也不像“CodeClimate”那样直指质量指标。但正是这个看似朴素的命名，藏着一个非常务实的出发点：把代码审查（code review）这件事，从“流程环节”拉回到“开放协作行为”本身。它不绑定特定平台（比如只支持 GitHub），不强制要求你用某个云服务，更不预设“审查必须由 senior engineer 发起”。它要解决的核心问题，是开发者在真实工作流中反复遭遇的“卡点”：当你刚 checkout 一个陌生分支，面对 37 个文件、214 行 Git diffs，第一眼该看什么？当你想快速确认某段重构是否破坏了边界契约，是翻文档、查测试、还是硬着头皮读完所有调用链？当你作为新人被分配到一个十年老项目，如何在不打扰任何人的情况下，建立对模块职责的初步认知？这些不是技术难题，而是信息过载下的认知负荷问题。open-code-review 的设计哲学很清晰：不替代人的判断，而是成为你大脑的临时缓存和索引器。它把 LLM Agent 的能力，精准锚定在 Git diffs 这个最细粒度、最实时、最无歧义的代码变更信号上；它用 CLI 工具的形式，确保你能把它像git status一样自然地嵌入日常命令流；它强调“open”，既指开源可审计，也指开放接入——你可以用它对接本地 Llama 3-70B，也可以连上企业内网部署的 Qwen2.5-72B，甚至未来还能插拔式接入自定义的 embedding 模型或 RAG 检索器。它适合三类人：一是每天要扫几十个 PR 的 Tech Lead，需要快速抓住风险点而非逐行校验；二是刚接手遗留系统的工程师，需要一份“代码考古指南”；三是正在构建内部 DevOps 平台的 SRE 团队，需要一个可编程、可审计、不黑盒的审查增强模块。它不承诺“自动修复 bug”，但能让你在 8 秒内获得一份比资深同事口头解释更结构化的变更摘要。
2. 核心设计思路拆解：为什么是 Git diffs + CLI + Agent，而不是 Web UI 或 IDE 插件？
2.1 为什么死磕 Git diffs，而不是直接分析整个代码库？
这是 open-code-review 最关键的设计取舍。很多同类工具会尝试“理解整个项目”，结果要么陷入无限加载，要么给出泛泛而谈的结论（比如“这个模块耦合度高”）。而 open-code-review 只吃 Git diffs，原因有三：第一，diffs 是事实性输入。它不依赖你有没有写好文档、测试覆盖率是否达标、或者 CI 是否通过。一行+ if (user.id === null) {就是客观存在的变更，LLM 对它的解读不会因为项目 README 写得差而失真。第二，diffs 天然具备上下文边界。一个git diff HEAD~1命令输出的，就是本次提交引入的所有变化，范围明确、无歧义。这避免了 LLM 在分析“整个 UserService”时，因信息过载而混淆核心逻辑与日志埋点代码。第三，diffs 是最小可执行单元。你可以对单个 commit 做审查，也可以对整个 PR 的合并 diff 做审查，甚至可以对本地未提交的git diff做审查——这种灵活性让工具能无缝嵌入从编码、本地测试到 CI 的全链路。我实测过一个场景：一个同事提交了一个修复空指针的 PR，改动涉及 5 个文件。用传统方式，我得手动打开每个文件，定位到新增的 null-check 逻辑，再逆向追踪调用链验证是否覆盖所有路径。而用 open-code-review，我只需运行ocr review --commit abc123，它立刻返回：“检测到 3 处新增 null-check（UserService.java L45, OrderService.java L112, PaymentGateway.java L89），其中 PaymentGateway.java 的检查位于异步回调中，建议补充超时兜底逻辑”。这个结论不是凭空而来，它基于 diff 中+ if (payment == null)这行代码，结合对PaymentGateway类历史调用模式的 embedding 检索（后文详述），得出的强相关推断。如果工具去分析整个PaymentGateway.java文件，它可能会被里面 200 行的重试机制代码干扰，反而忽略这个关键的 null-check 新增点。
2.2 为什么坚持 CLI 形态，而不是做漂亮的 Web 界面？
这个问题我被问过至少 17 次。答案很实在：CLI 是开发者工作流的“零摩擦入口”。Web UI 意味着你需要打开浏览器、登录、等待页面加载、再找到对应的 PR 链接——这个过程平均耗时 23 秒（我用秒表测过团队数据）。而 CLI 命令ocr review -p 123，从敲下回车键到看到结果，平均响应时间是 6.2 秒（含 LLM 推理）。更重要的是，CLI 天然支持管道（pipe）和脚本化。你可以轻松写出这样的自动化脚本：
# 在 CI 流程中，对每个 PR 自动触发审查，并将高危项写入 Jira git fetch origin pull/$PR_NUMBER/head:pr-$PR_NUMBER git checkout pr-$PR_NUMBER ocr review --format json | jq '.high_risk_issues[]' | while read issue; do jira create --summary "PR $PR_NUMBER: $issue" --project DEVOPS done这个脚本在我们团队的 Jenkins Pipeline 中稳定运行了 4 个月，拦截了 11 个潜在的生产环境 NPE（空指针异常）。如果是个 Web UI，你根本没法把它塞进 CI 流水线里。还有个隐形优势：CLI 强制你明确输入意图。Web UI 上，用户可能点开一堆默认选项，最后得到一份不知所云的报告。而 CLI 的参数设计（如--context-lines 5控制 diff 上下文行数、--model local:qwen2.5-72b指定模型）迫使你在使用前思考：“我这次审查的重点是什么？需要多深的上下文？信任哪个模型？” 这种“主动选择”本身，就是高质量审查的开始。当然，CLI 不代表反 UI。open-code-review 的架构是分层的：底层 core 是纯 CLI，上层可以自由构建 VS Code 插件、JetBrains 插件，甚至 Slack Bot。但核心能力必须首先在 CLI 上跑通、跑稳、跑快——这是我对所有工程工具的底线。
2.3 LLM Agent 在这里扮演什么角色？它和普通 LLM 调用有何本质区别？
这是最容易被误解的一点。“Agent”这个词现在被用得太滥，很多人以为加个agent.run()就是 Agent 了。在 open-code-review 里，Agent 的核心价值在于状态感知与任务编排，而不是单纯“调用大模型”。一个典型的审查流程，绝不是“把 diff 丢给 LLM，让它自由发挥”。它包含明确的、可拆解的子任务：
- 变更归类：识别这是功能新增、Bug 修复、还是重构？依据是 commit message 模式 + diff 语义特征。
- 风险扫描：针对不同类别，启动不同检查器。例如，对“Bug 修复”，重点扫描 null-check、边界条件、异常处理；对“数据库迁移”，检查 SQL 语法、事务隔离级别、索引影响。
- 上下文检索：当发现
UserService.updateProfile()被修改，自动从本地代码库 embedding 向量库中，检索过去 6 个月内所有对该方法的调用、测试、以及相关文档片段。 - 交叉验证：把 LLM 对 diff 的解读，与静态分析工具（如 Semgrep 规则）的结果做比对。如果两者都标记某行有 SQL 注入风险，置信度就拉满；如果只有 LLM 标记，就降级为“待人工确认”。
- 报告生成：不是简单拼接结论，而是按“严重性-模块-文件”三维排序，并为每个高危项生成可操作的建议（如“建议在 L78 添加 try-catch 包裹数据库查询”）。
这个流程里，LLM 是每个子任务的“执行引擎”，但 Agent 是那个指挥官。它决定什么时候该查 embedding，什么时候该调用规则引擎，什么时候该合并多个来源的证据。我做过对比实验：用纯 prompt 工程让 LLM 直接分析 diff，准确率是 68%；而用 Agent 编排，把 embedding 检索结果作为 system prompt 的一部分喂给 LLM，准确率提升到 89%。提升的 21%，不是来自更大的模型，而是来自更严谨的任务分解和证据融合。这才是 Agent 的真实价值——它让 LLM 从“自由诗人”，变成了“严谨工程师”。
3. 核心细节解析与实操要点：从安装到产出一份可信报告的完整链路
3.1 安装与初始化：为什么推荐从源码构建，而不是 pip install？
open-code-review 的官方 PyPI 包（pip install open-code-review）只包含最精简的 CLI 核心和默认配置。它假设你愿意接受社区维护的模型权重、embedding 模型、以及预设的审查规则集。但在真实企业环境中，这往往不现实。你可能需要：
- 使用公司内网可访问的私有 LLM API（如部署在 Kubernetes 上的 vLLM 服务）；
- 用自己微调过的 CodeLlama 模型，专门针对内部 DSL（领域特定语言）做了优化；
- embedding 模型必须兼容现有向量数据库（如 Milvus 或 Weaviate）的 schema。
因此，我强烈建议从源码构建：
git clone https://github.com/open-code-review/open-code-review.git cd open-code-review # 创建虚拟环境，避免污染全局 Python python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows pip install -e ".[dev]" # -e 表示可编辑安装，[dev] 安装开发依赖这个过程的关键在于pip install -e。它让你的本地修改（比如改config.yaml里的模型地址）能立即生效，无需反复pip uninstall/install。更重要的是，它暴露了所有可配置项。安装后，你会在项目根目录看到config.yaml，这是整个工具的“中枢神经”。它的结构不是随意设计的，每一层都有明确职责：
# config.yaml 核心结构解析 llm: provider: "vllm" # 支持 vllm, ollama, openai, local_hf endpoint: "http://localhost:8000/v1" # vLLM 服务地址 model_name: "Qwen2.5-72B-Instruct" # 必须与 vLLM 加载的模型名一致 temperature: 0.1 # 低温度保证审查结论稳定，不胡说 embedding: model_name: "text-embedding-3-small" # 这里填你实际部署的 embedding 模型名 vector_db: "milvus" # 支持 milvus, weaviate, chroma collection_name: "codebase_v2" # 向量库中的集合名，需提前创建 review_rules: - name: "null_safety" enabled: true severity: "high" description: "Detects potential null pointer dereference risks" - name: "sql_injection" enabled: true severity: "critical"提示：
config.yaml中的llm.temperature: 0.1是我踩过坑后加的硬性规定。早期测试时，我把温度设为 0.7，LLM 在分析一个支付回调函数时，竟“脑补”出一段不存在的 Redis 缓存穿透逻辑，并给出了完全错误的修复建议。把温度压到 0.1 后，结论变得极其保守和确定，宁可漏报，绝不误报——这对代码审查工具而言，是生死线。
3.2 构建代码库 embedding 向量库：不是“一键生成”，而是“分层索引”
很多人以为ocr init就能搞定一切。实际上，“init”只是第一步，真正的难点在于如何让 embedding 真正理解你的代码语义。open-code-review 默认使用text-embedding-3-small，但它对 Java 的泛型语法、Python 的装饰器、Go 的 interface 实现，理解力有限。我的经验是：必须做两层 embedding。
第一层：文件级粗粒度索引
# 扫描整个代码库，为每个 .java/.py/.go 文件生成一个 embedding 向量 ocr embed --scope file --language java --path ./src/main/java这个命令会遍历所有 Java 文件，提取类名、方法签名、注释关键词，生成一个 512 维向量存入 Milvus。它的作用是快速定位“哪个文件最可能和当前 diff 相关”。比如，你修改了OrderService.java，Agent 就会优先检索OrderService.java的向量，以及与其向量距离最近的 3 个文件（通常是OrderRepository.java,OrderDTO.java,OrderController.java）。
第二层：方法级细粒度索引
# 针对高频变更的核心类，单独做方法级 embedding ocr embed --scope method --class UserService --path ./src/main/java/com/example/user这个命令会把UserService类里的每个 public 方法（如createUser(),updateProfile()）单独切片，提取其 Javadoc、参数类型、返回值、以及调用的其他方法，生成更精细的向量。当 diff 中出现userService.updateProfile(...)时，Agent 就能精准召回updateProfile()方法的历史调用模式、测试覆盖率、以及过去 3 个月的变更记录。
注意：方法级 embedding 的代价很高。一个 2000 行的
UserService.java，可能有 47 个 public 方法，生成 47 个向量。我建议只对core、domain、infrastructure这些包下的关键类启用。在我们团队，这个策略把向量库大小从 12GB 降到 1.8GB，而召回准确率反而提升了 15%，因为噪声少了。
3.3 执行一次审查：ocr review命令背后的 7 个隐式步骤
当你敲下ocr review --commit abc123 --context-lines 3，表面上只是一条命令，背后却发生了严谨的 7 步流水线：
- Diff 解析：调用
git show abc123，提取出完整的 patch。--context-lines 3参数确保每块 diff 都带上 3 行原始代码上下文，这对 LLM 理解变量作用域至关重要。 - 变更指纹生成：对每个 diff 块，计算一个 SHA256 指纹。这个指纹用于后续去重——如果同一个 diff 块在多个 commit 中重复出现，只审查一次。
- 变更归类：用轻量级分类器（基于 commit message 的正则 + diff 关键词统计）判断本次变更属于
feature、bugfix、refactor、docs中的哪一类。这一步耗时 < 100ms，但决定了后续启动哪些审查规则。 - 上下文检索：根据归类结果，发起向量检索。如果是
bugfix，就检索UserService.java的updateProfile()方法向量；如果是refactor，就检索整个UserService.java文件向量 + 其所有调用者向量。 - 多源证据融合：把检索到的向量相似度分数、静态分析工具（Semgrep）的匹配结果、以及 LLM 对 diff 的初步解读，全部打包成一个 structured prompt，喂给 LLM。
- LLM 推理：LLM 不是自由发挥，而是严格遵循预设的 JSON Schema 输出：
{ "summary": "一句话概括变更意图", "risk_assessment": [ { "file": "UserService.java", "line": 45, "type": "null_safety", "severity": "high", "explanation": "新增的 null-check 位于异步回调中，缺乏超时处理", "suggestion": "在 L45 处添加 try-catch，并设置 5s 超时" } ] } - 报告渲染：把 JSON 结构化输出，转换成终端友好的 ANSI 颜色格式。高危项用红色加粗，中危用黄色，低危用绿色。同时生成
report.json和report.md两个文件，方便集成到 CI 或人工复核。
这个流程里，第 4 步（上下文检索）和第 5 步（多源证据融合）是 open-code-review 的护城河。它让 LLM 的结论不再是“我觉得”，而是“我看到过去 3 个类似变更都导致了超时故障，且静态分析也标记了此处缺少 timeout”。
4. 实操过程与核心环节实现：从零搭建一个可落地的企业级审查工作流
4.1 场景实战：为一个微服务团队定制审查规则
我们团队负责一个订单微服务，技术栈是 Spring Boot + PostgreSQL。上线半年来，最常发生的线上事故是“数据库连接池耗尽”。根因分析显示，83% 的案例源于开发者在新增接口时，忘了在@Transactional方法里加timeout属性，导致慢 SQL 占满连接池。这是一个典型的、可被规则捕获的问题。open-code-review 的review_rules机制，让我们能精准打击这类问题。
首先，编写一条自定义规则transaction_timeout.yaml：
name: "transaction_timeout" enabled: true severity: "critical" description: "Detects @Transactional methods without timeout attribute" language: "java" pattern: | @Transactional( propagation = Propagation.REQUIRED, rollbackFor = Exception.class ) public .*? .*?\(.*?\) \{ # 注意：这个 pattern 不是正则，而是 Tree-sitter 查询语法，能精准匹配 AST 节点 # 它确保只匹配那些显式写了 propagation 和 rollbackFor，但漏掉 timeout 的情况 check: | # 这是一个 Python 函数，接收 diff AST 节点，返回 True/False def check(node): # 检查节点是否为 MethodDeclaration if not node.type == 'method_declaration': return False # 检查是否有 @Transactional 注解 annotations = node.children_by_field_name('annotation') for ann in annotations: if ann.text.decode().startswith('@Transactional'): # 解析注解参数 args = parse_annotation_args(ann) # 如果有 propagation 和 rollbackFor，但没有 timeout，则触发 if 'propagation' in args and 'rollbackFor' in args and 'timeout' not in args: return True return False suggestion: | 在 @Transactional 注解中添加 timeout = 5，例如： @Transactional( propagation = Propagation.REQUIRED, rollbackFor = Exception.class, timeout = 5 )把这个文件放到./rules/目录下，然后在config.yaml中引用：
review_rules: - path: "./rules/transaction_timeout.yaml"实操心得：规则编写不是一蹴而就的。我第一次写的 pattern 是正则
@Transactional\(.*?\)，结果误报率高达 40%——它匹配了所有@Transactional，包括那些已经加了timeout的。后来改用 Tree-sitter AST 查询，才把准确率提到 99.2%。Tree-sitter 的优势在于，它不看你代码长什么样，而看代码“是什么”。一个@Transactional(timeout=5)和一个@Transactional(rollbackFor=Exception.class)，在 AST 层面是完全不同的节点结构，可以精确区分。
4.2 CI 集成：如何让审查成为 PR 的“守门员”
在 GitHub Actions 中，我们配置了一个code-review.yml工作流：
name: Open Code Review on: pull_request: types: [opened, synchronize, reopened] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # 必须获取完整 git history - name: Setup Python uses: actions/setup-python@v5 with: python-version: '3.11' - name: Install open-code-review run: | git clone https://github.com/open-code-review/open-code-review.git cd open-code-review python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" - name: Run Open Code Review id: ocr run: | # 设置 config.yaml 指向我们的私有 vLLM 服务 echo "llm: provider: vllm endpoint: http://vllm-service:8000/v1 model_name: Qwen2.5-72B-Instruct temperature: 0.1 embedding: model_name: text-embedding-3-small vector_db: milvus collection_name: order_service_v1" > config.yaml # 执行审查，输出为 JSON ocr review --pr ${{ github.event.number }} --format json > report.json 2>&1 || true - name: Parse Report & Fail on Critical run: | # 解析 report.json，检查是否有 critical 级别问题 if jq -e '.risk_assessment[] | select(.severity == "critical")' report.json > /dev/null; then echo "❌ CRITICAL ISSUE DETECTED! Please address before merging." exit 1 else echo "✅ No critical issues found." fi这个工作流的关键点在于|| true。它确保即使ocr review命令因网络或模型超时失败，CI 也不会直接中断，而是继续执行下一步解析。这样，审查是“尽力而为”，但不阻断主流程。而真正的守门员是最后一步的jq解析——它只检查critical级别问题。我们刻意把high级别（如“建议加日志”）设为警告，不阻断合并，把critical（如“检测到未加 timeout 的 @Transactional”）设为必须修复。这种分级策略，让团队既能享受 AI 审查的红利，又不被噪音淹没。
4.3 本地开发提效：ocr watch命令如何改变你的编码习惯
ocr watch是我最常使用的命令，它让代码审查从“事后检查”变成“实时反馈”。启动方式很简单：
# 监听当前目录下所有 .java 文件的变更 ocr watch --language java --interval 2--interval 2表示每 2 秒扫描一次文件系统。一旦检测到文件保存，它会自动计算本次保存与上次保存之间的 diff，然后执行一次轻量级审查。这个审查不走 full pipeline，而是只启用null_safety和transaction_timeout这两条最紧急的规则。
效果非常直观：当我写完一个新接口，在OrderService.java里敲下@Transactional，还没来得及加timeout，终端就弹出：
[WATCH] Detected change in OrderService.java ⚠️ HIGH RISK: @Transactional method 'createOrder' lacks timeout attribute 💡 Suggestion: Add 'timeout = 5' to the annotation这种即时反馈，把“修复成本”从“PR 被拒后返工 20 分钟”，降到了“敲完注解后 2 秒内补上 timeout，耗时 3 秒”。我统计过，团队成员使用ocr watch后，@Transactional缺少 timeout 的错误率从 12.7% 降到了 0.3%。这不是靠培训，而是靠把最佳实践“焊”进了开发者的肌肉记忆里。
5. 常见问题与排查技巧实录：那些文档里不会写的“血泪教训”
5.1 问题速查表：从症状到根因的快速定位
| 症状 | 可能根因 | 排查命令 | 解决方案 |
|---|---|---|---|
ocr review报错Connection refused | vLLM 服务未启动，或config.yaml中 endpoint 地址错误 | curl -v http://localhost:8000/v1/models | 检查 vLLM 日志，确认服务监听地址与 config.yaml 一致 |
审查报告中大量UNKNOWN风险项 | embedding 向量库未初始化，或collection_name配置错误 | ocr embed --list-collections | 运行ocr embed --init初始化向量库，确认 collection 名称匹配 |
LLM 返回结果全是英文，即使config.yaml设了language: zh | 模型本身不支持中文指令微调，或 prompt 模板未正确注入语言指令 | ocr review --debug --commit abc123查看完整 prompt | 修改prompts/review.jinja2模板，在 system prompt 中硬编码请用中文回答 |
ocr watchCPU 占用率飙升到 90% | --interval设置过小（如 0.5 秒），或监控目录过大（如包含node_modules） | top -p $(pgrep -f "ocr watch") | 将--interval调至 3 秒，用--exclude "**/node_modules/**"排除无关目录 |
5.2 “模型幻觉”专项治理：3 个硬核技巧
LLM 在代码审查中最让人头疼的，不是它答错了，而是它“自信地答错了”。open-code-review 提供了三层防御：
第一层：Prompt 工程硬约束在prompts/review.jinja2中，system prompt 的最后一句必须是：
你只能基于提供的 Git diff 内容和检索到的上下文进行推理。禁止编造任何代码、方法名、类名、或业务逻辑。如果信息不足，请明确回答“无法确定”，而不是猜测。这个句子不是摆设。我测试过，去掉它，LLM 在分析一个空 diff 时，会“发明”出一个根本不存在的CacheManager.refresh()方法并给出调用建议；加上它，它只会说“无法确定”。
第二层：输出 Schema 强校验所有 LLM 的输出，都必须符合预定义的 JSON Schema。open-code-review 在调用 LLM 后，会用jsonschema.validate()进行校验。如果 LLM 返回了{"summary": "...", "risk_assessment": [{"file": "xxx", "line": "abc"}]}（注意"line": "abc"是字符串），校验就会失败，整个审查流程终止，并打印错误日志。这强迫 LLM 必须输出数字类型的line字段，杜绝了类型混淆。
第三层：静态分析交叉验证对于transaction_timeout这类规则，我们同时部署了 Semgrep 规则：
rules: - id: java-transactional-no-timeout patterns: - pattern: "@Transactional($CONFIG)" - pattern-not: "@Transactional($CONFIG, timeout = ...)" message: "@Transactional missing timeout" languages: [java] severity: ERRORocr review会并行运行 Semgrep 和 LLM。只有当两者都标记同一行时，才在报告中显示为CRITICAL；如果只有 Semgrep 标记，显示为HIGH；如果只有 LLM 标记，直接过滤掉。这个“双保险”机制，把误报率从 18% 降到了 0.7%。
5.3 性能瓶颈突破：当审查一个 5000 行的巨型 diff 时
遇到一个包含 5000 行变更的 PR（常见于重构或框架升级），ocr review默认会卡住。这不是 bug，而是设计使然——它在保护你。5000 行 diff 意味着 LLM 要处理一个超长上下文，推理时间可能超过 5 分钟，且准确率急剧下降。我们的应对策略是“分而治之”：
- 自动分块：
ocr review --chunk-size 500会把 5000 行 diff 拆成 10 个 500 行的块，分别审查，最后聚合结果。 - 智能聚焦：
ocr review --focus critical会跳过所有test/、docs/目录的变更，只审查src/main/java/下的代码。 - 缓存加速：
ocr review --cache-dir ~/.ocr/cache会把每个 diff 块的审查结果（包括 embedding 检索 ID 和 LLM 输出）存入本地 SQLite 数据库。下次遇到相同 diff，直接返回缓存结果，耗时从 42 秒降到 0.8 秒。
我实测过一个 4821 行的 Spring Boot 升级 PR。用默认参数，耗时 6 分 38 秒，内存峰值 12GB；用--chunk-size 500 --focus critical --cache-dir ~/.ocr/cache，耗时 1 分 12 秒，内存峰值 3.2GB，且报告质量无损。这个优化不是靠升级硬件，而是靠对工作流的深刻理解——开发者不需要一次性理解 4821 行，只需要知道“哪 3 个文件的变更最危险”。
6. 关键概念辨析：open code review、Agent LLM、embedding，它们到底在解决什么问题？
6.1 “open code review” 不是名词，而是一个动词短语
很多人把open-code-review当成一个工具名，就像git或docker。但它的本质，是一个倡导开放协作的审查范式。open有三层含义：
- 开源（Open Source）：代码完全公开，你可以审计每一个 prompt、每一条规则、每一个 embedding 向量的生成逻辑。没有黑盒 API，没有隐藏收费项。
- 开放（Open Access）：它不锁定你到某个云厂商。你可以用 HuggingFace 上免费的
all-MiniLM-L6-v2，也可以用企业采购的Cohere Embed，只要符合接口规范，就能插拔替换。 - 开放（Open Process）：审查报告不是一份“判决书”，而是一份“讨论提纲”。它鼓励你在报告末尾的
SUGGESTION区域，直接回复@team-lead提出质疑，或者@backend-dev请求补充上下文。工具本身不取代对话，而是让对话更高效。
这和传统 SaaS 审查工具形成鲜明对比。后者追求“一键生成完美报告”，结果往往是“报告很美，没人看”。而 open-code-review 追求“生成一份值得讨论的报告”，目标是让团队在 15 分钟内，就一个高危变更达成共识。
6.2 Agent LLM vs. 普通 LLM：从“问答机器”到“工作流协作者”
“Agent LLM” 这个词最近很火，但很多人没意识到，它和普通 LLM 的分水岭，不在模型大小，而在是否具备状态管理能力。一个普通 LLM 调用，是无状态的：你给它一个 prompt，它给你一个 response，仅此而已。而 open-code-review 的 Agent，拥有一个清晰的状态机：
- State 1: Input State——
git diff的文本内容、commit hash、当前分支名。 - State 2: Context State—— 从向量库检索到的 5 个最相关文件、3 个历史调用片段、2 条 Semgrep 规则匹配。
- State 3: Task State—— 当前正在执行
null_safety_check子任务，已执行 2/3 步骤。 - State 4: Output State—— 已生成
summary字段，正在生成risk_assessment数组。
这个状态机让 Agent 能做普通 LLM 做不到的事：比如，当它在risk_assessment中发现一个file: "DatabaseConfig.java"的高危项，它可以立刻触发一个新的子任务database_config_review，专门去检索DatabaseConfig.java的连接池配置历史。这种“基于中间结果动态规划下一步”的能力，才是 Agent 的灵魂。它让 LLM 从“被动应答者”，变成了“主动协作者”。
6.3 embedding 的本质：不是“向量化”，而是“关系建模”
最后说说embedding。很多人以为，把代码喂给 embedding 模型，得到一个向量，就完事了。这是巨大的误解。embedding 的真正价值，在于建模代码元素之间的隐含关系。一个UserService.java的向量，其意义不在于它自己的数值，而在于它和UserRepository.java向量的余弦相似度是 0.87，和OrderService.java的相似度是 0.32。这个 0.87，就是“UserService 重度依赖 UserRepository”的数学表达。
open-code-review 的 embedding 策略，正是围绕这个“关系”展开的：
- 文件级 embedding：建模“模块间依赖关系”。高相似度意味着强耦合，审查时要重点关注接口契约。
- 方法级 embedding：建模“调用链路关系”。高相似度意味着这些方法经常被一起调用，构成一个业务逻辑单元。
- 测试文件 embedding：建模“测试覆盖关系”。一个
UserServiceTest.java向量，如果和UserService.java的相似度高达 0.95，说明这个测试覆盖了核心路径；如果只有 0.4，就提示“这个变更可能缺乏有效测试”。
所以，当你在config.yaml中配置embedding.model_name: "text-embedding-3-small"，你买的不是
