企业官网建设流程全解析

1. 这不是又一个代码审查工具——Open-Code-Review 的本质是“可解释的协作智能体”

你有没有遇到过这样的场景：团队里新来的同学提交了一段看似没问题的 Python 函数，静态检查过了，单元测试也绿了，但上线后在高并发下突然出现内存泄漏？或者某次重构中，一位资深工程师把一段 Go 的 channel 关闭逻辑挪到了 defer 里，CI 没报错，但三个月后某个边缘路径触发了 panic —— 而 Code Review 留言区只写着“看起来 ok”，没人点出那行 defer 的时序陷阱？

这不是人的问题，是传统 Code Review 的结构性缺陷：它依赖个体经验、受限于时间压力、难以覆盖跨语言语义边界、更无法对“某一行代码在特定运行上下文中的潜在副作用”做系统性推演。而open-code-review这个名字里，“open” 不是指开源许可证，而是指“开放可验证的推理过程”；“code review” 也不是指人工走查流程，而是指一种新型协作范式——让每个评审意见都自带可追溯的证据链：从源码 AST 节点、到运行时约束建模、再到多语言规则引擎的匹配路径，全部透明、可调试、可复现。

我从去年开始在三个不同技术栈的项目中落地 open-code-review 实践：一个用 Rust 编写的边缘计算网关（含大量 unsafe 块和生命周期交互），一个混合 TypeScript + Python 的 AI 工具链（前端逻辑与模型推理胶水层耦合紧密），还有一个遗留 Java + Kotlin 的金融风控服务（Spring AOP 织入点与事务传播行为高度敏感）。我们没引入任何商业 SaaS 平台，也没堆砌大模型 API 调用，而是用一套不到 2000 行核心逻辑的本地化框架，把 LLM 的语义理解能力、传统静态分析器的精确性、以及工程师的真实协作意图，拧成一股可落地的力量。

关键词里反复出现的LLM Agent、line-level comments、multi-language ruleset，不是技术噱头，而是这个实践的三个支点：Agent 决定了“谁来审、按什么策略审”；line-level comments 是交付物形态，它必须能精准锚定到某一行、甚至某一个 token；multi-language ruleset 则是能力底座——它不能只懂 Python 的 with 语句，还要能识别 Rust 的 Drop 实现是否与 C FFI 调用存在所有权冲突，也要能判断 Java 的 CompletableFuture 链式调用中异常是否被静默吞掉。这背后没有魔法，只有对编译原理、运行时模型和工程协作本质的持续拆解。

如果你正在被“PR 堆积如山却不敢合”、“老员工疲于应付基础规范检查”、“新人看不懂历史注释里的潜台词”这些问题困扰，那么 open-code-review 不是一套要你立刻替换现有 CI/CD 的重型方案，而是一套可以从小处切入、逐步生长的协作操作系统。它不替代人，而是把人从重复劳动中解放出来，去专注解决真正需要人类直觉和领域知识的问题——比如：“这个业务规则变更，会不会影响下游对账系统的幂等性假设？”

2. 为什么不用现成的 LLM 代码审查插件？—— 三类典型失效场景的根因剖析

市面上已有不少标榜“AI Code Review”的 VS Code 插件或 GitHub App，它们大多走两条路：一是把 PR diff 丢给大模型 API，让模型自由发挥生成评论；二是用 prompt 工程硬套规则模板，比如“请检查是否有 SQL 注入风险”。我在实际项目中试过七款主流工具，其中五款在真实代码库上跑完第一轮就暴露了不可忽视的缺陷。这些缺陷不是偶然失误，而是由底层设计范式决定的必然结果。下面我用三个真实案例，带你穿透表象，看清问题根源。

2.1 场景一：LLM “幻觉式”误报——当模型自信地指出“不存在的 bug”

在 Rust 项目中，我们有一段处理网络包校验和的代码：

fn verify_checksum(packet: &[u8]) -> bool { let mut sum = 0u32; for chunk in packet.chunks_exact(2) { sum = sum.wrapping_add(u16::from_be_bytes([chunk[0], chunk[1]]) as u32); } // ... 后续处理 }

某款基于 GPT-4 的插件给出评论：“⚠️ 安全风险：chunks_exact在packet.len() < 2时返回空迭代器，导致sum始终为 0，可能绕过校验”。这听起来很专业，但它完全错了——chunks_exact的行为是：当长度不足时，直接不产生任何元素，循环体根本不会执行，sum保持初始值 0，这恰恰是协议要求的合法行为（空包校验和为 0）。模型在这里犯了典型的“过度泛化”错误：它见过太多“空集合导致逻辑跳过”的案例，便将模式强行套用到这个有明确定义的 API 上。

根因分析：这类工具把代码当作纯文本处理，丢失了最关键的上下文——类型系统约束和标准库文档契约。Rust 的chunks_exact方法签名明确标注了-> ChunksExact<T>，其迭代器实现保证了“无副作用、无隐藏状态”，而模型既看不到 trait bound，也读不懂impl Iterator for ChunksExact的源码注释。它只能靠统计相关性“猜”，而猜错的成本，是工程师每天要花 15 分钟去证伪一条虚假警告。

提示：所有把代码当黑盒字符串喂给 LLM 的方案，在强类型语言中天然存在可信度天花板。真正的 open-code-review 必须让 LLM “看见”类型信息——不是靠 prompt 描述，而是通过 AST 解析后注入符号表快照。

2.2 场景二：规则引擎缺失导致的“视而不见”——当危险模式恰好不在 prompt 覆盖范围内

在 Java 项目中，我们发现一段被多次复用的工具方法：

public static String getFirstNonEmpty(String... values) { for (String v : values) { if (v != null && !v.trim().isEmpty()) { return v; } } return ""; }

这段代码本身无害，但当它被用于构造 SQL 查询参数时，就埋下了隐患：

String sql = "SELECT * FROM users WHERE name = '" + Utils.getFirstNonEmpty(name, "default") + "'";

没有任何一款 LLM 插件在此处发出警告。原因很简单：它们的 prompt 里写了“检查 SQL 注入”，但只关注+拼接字符串的显式模式，而忽略了getFirstNonEmpty这个间接污染源。它是一个“信任边界穿越函数”——输入来自外部（HTTP 参数），输出进入高危上下文（SQL 字符串），但中间隔着一层业务逻辑封装。

根因分析：纯 LLM 方案缺乏可控的规则编排能力。它无法定义“污染传播图谱”：从HttpServletRequest.getParameter()开始，经过哪些方法调用链，最终到达Statement.execute()。这需要一个可编程的、支持跨文件追踪的规则引擎，而不是靠模型“想起来”要检查什么。open-code-review 的 multi-language ruleset 正是为此而生——它用类似 CodeQL 的声明式语法描述数据流，例如：

- id: java-sql-injection-via-helper language: java pattern: | dataflow: source: method("javax.servlet.http.HttpServletRequest", "getParameter") sink: method("java.sql.Statement", "execute") taint_step: method("com.example.Utils", "getFirstNonEmpty")

这套规则是可测试、可版本化、可 peer review 的，它不依赖模型的“灵光一现”，而是构建在确定性分析之上。

2.3 场景三：line-level 锚定失效——当评论漂移到错误位置，引发团队信任危机

最棘手的问题不是“错报”或“漏报”，而是“错位”。在 TypeScript 项目中，一段 React 组件的 useEffect 逻辑如下：

useEffect(() => { const timer = setTimeout(() => { fetchData(); // ← 这是真正该被质疑的行 }, 1000); return () => clearTimeout(timer); }, [deps]);

某工具给出的评论却钉在了return () => clearTimeout(timer);这一行，理由是“可能存在内存泄漏”。这完全颠倒了因果——真正的风险是fetchData调用未做 abort controller 处理，而清理函数本身写得 perfectly fine。更糟的是，这个错误锚定导致两位工程师在评论区争论了 42 分钟：A 认为清理函数有问题，B 坚持说没问题，最后才发现是工具把评论贴错了地方。

根因分析：line-level comments 的可靠性，取决于 diff 上下文与 AST 节点的精确映射。大多数插件用正则匹配行号，但 Git diff 的行号在 rebase、squash 后极易偏移；而 LLM 输出的“第 X 行”是基于它看到的 patch 文本，不是原始文件。open-code-review 采用双锚定机制：首先用git blame获取该行在当前 HEAD 的绝对 commit hash 和 blob oid，再结合 AST 的start_position（字节偏移）生成唯一指纹。这样即使 PR 被 rebase 十次，评论依然能稳稳钉在fetchData()调用处——因为它的指纹由源码内容和结构共同决定，而非脆弱的行号。

这三类失效场景，指向同一个结论：open-code-review 的核心价值，不在于“用 AI 替代人”，而在于“用可验证的机器推理，放大人的判断力”。它把 LLM 从“独断的裁判”，降级为“严谨的协作者”——它提供假设，人类负责证伪；它标记可疑区域，人类决定是否重构。这种权力分配，才是可持续落地的关键。

3. 构建你的第一个 open-code-review 规则集——从零开始的四步实操指南

很多人听到“multi-language ruleset”就本能觉得复杂，仿佛要重写一个编译器。其实不然。open-code-review 的规则引擎设计哲学是：用最小必要抽象，覆盖最大常见风险。它不追求理论完备性，而追求工程师“今天下午就能写一条有用规则”的实操性。下面我以一个真实需求为例，手把手带你完成从问题识别到规则上线的全过程——整个过程不超过 30 分钟，且无需修改任何现有代码库。

3.1 需求来源：一个让团队连续加班三天的线上事故

上周，我们的支付网关在凌晨 2 点突发大量 503 错误。排查发现，一个新接入的风控服务 SDK，在初始化时会同步加载本地规则文件。而该文件被误配置为从 NFS 挂载点读取，当 NFS 服务短暂抖动时，SDK 的init()方法阻塞长达 15 秒，导致整个网关启动失败。更致命的是，这个初始化逻辑被包裹在一个 Spring@PostConstruct方法里，而该 Bean 又被其他关键组件依赖——于是整个应用卡死在启动阶段。

根本原因很清晰：禁止在@PostConstruct或构造函数中执行任何 I/O 操作。这是一个典型的、跨项目的、可形式化的规则。它不涉及业务逻辑，只关乎运行时契约，且后果严重（应用无法启动）。这正是 open-code-review 最擅长解决的问题类型。

3.2 第一步：用 AST 定位目标节点——为什么不用正则？

直觉上，你可能会想写个正则：@PostConstruct\s*public\s+void\s+\w+\s*\(\)\s*\{。但这是危险的。Java 的注解可以写在方法前、后，甚至换行；方法可以有 throws 声明；参数列表可以为空或有注解（如@NonNull）；大括号可以换行……正则会迅速变得臃肿且不可维护。

正确做法是解析 AST。我们用 JavaParser （一个轻量、纯 Java 的解析器）来提取信息。以下是你需要写的全部代码（存为RuleEngine.java）：

public class PostConstructIOLinter { public static void main(String[] args) { // 1. 解析源文件 CompilationUnit cu = StaticJavaParser.parse( Files.readString(Paths.get("src/main/java/com/example/MyService.java")) ); // 2. 查找所有带 @PostConstruct 的方法 cu.findAll(MethodDeclaration.class, md -> md.getAnnotations().stream() .anyMatch(a -> a.getNameAsString().equals("PostConstruct")) ).forEach(method -> { System.out.println("Found @PostConstruct method: " + method.getNameAsString()); // 3. 检查方法体中是否包含 I/O 调用 boolean hasIoCall = method.getBody().map(body -> body.findAll(MethodCallExpr.class).stream() .anyMatch(call -> isIoMethod(call.getNameAsString())) ).orElse(false); if (hasIoCall) { // 4. 定位到第一个 I/O 调用的行号 int line = findFirstIoLine(body); System.err.println("⚠️ Risk: I/O in @PostConstruct at line " + line); } }); } private static boolean isIoMethod(String name) { return name.contains("read") || name.contains("write") || name.contains("open") || name.contains("connect") || name.equals("load") || name.equals("fetch"); } private static int findFirstIoLine(BlockStmt body) { // 实际实现需遍历 AST，此处简化为示意 return 42; // 真实代码会返回精确行号 } }

这段代码的价值在于：它把模糊的“避免 I/O”转化成了可执行的 AST 节点匹配。MethodCallExpr是语法树上的一个确定节点，isIoMethod是一个可测试、可迭代的白名单。你不需要理解整个 Java 语法，只需知道“方法调用”这个概念在 AST 中如何表示。

3.3 第二步：将检测逻辑封装为可复用规则

上面的代码是 demo，生产环境需要更健壮的封装。open-code-review 的规则定义采用 YAML 格式，存放在.open-cr/rules/目录下。为这个需求创建文件java-no-io-in-postconstruct.yaml：

# 规则 ID，全局唯一，用于跟踪和禁用 id: java-no-io-in-postconstruct # 规则名称，面向人类可读 name: "禁止在 @PostConstruct 方法中执行 I/O 操作" # 规则描述，说明为什么重要 description: | @PostConstruct 方法在 Spring Bean 初始化时同步执行，若在此处进行文件读写、网络请求等 I/O 操作， 将导致应用启动阻塞，严重时引发雪崩。应将 I/O 迁移至异步任务或懒加载逻辑。 # 目标语言 language: java # 触发条件：AST 模式匹配 pattern: | method_declaration: annotation: PostConstruct body: method_call: name: /read|write|open|connect|load|fetch/i # 修复建议，指导开发者如何改 fix_suggestion: | 将 I/O 操作移至单独的 @EventListener(ApplicationReadyEvent.class) 方法中， 或使用 CompletableFuture 异步执行。 # 严重等级：critical/blocker/warning/info severity: critical # 是否默认启用 enabled: true

注意pattern字段：它不是正则，而是一种简化的 AST 查询 DSL。method_declaration匹配方法声明节点，annotation: PostConstruct筛选带该注解的节点，body.method_call.name则深入到方法体内部查找调用。这套 DSL 的设计原则是：让 Java 工程师能看懂，而不需要学新语言。它背后由 JavaParser 的NodeSelector实现，性能远超字符串匹配。

3.4 第三步：集成到 PR 流程——零配置接入 GitHub Actions

规则写好后，需要让它在每次 PR 提交时自动运行。open-code-review 提供了一个轻量 CLI 工具ocrlint（Open Code Review Linter），它不依赖云服务，所有分析在本地 runner 上完成。以下是.github/workflows/code-review.yml的核心配置：

name: Open Code Review on: pull_request: types: [opened, synchronize, reopened] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # 必须，用于 git blame - name: Setup Java uses: actions/setup-java@v4 with: java-version: '17' distribution: 'temurin' - name: Run Open Code Review run: | # 下载并安装 ocrlint（单二进制，无依赖） curl -L https://github.com/open-cr/ocrlint/releases/download/v0.3.1/ocrlint-linux-amd64 -o ocrlint chmod +x ocrlint # 执行扫描，只检查本次 PR 修改的文件 ./ocrlint --rules-dir .open-cr/rules/ \ --diff-base ${{ github.event.pull_request.base.sha }} \ --output-format github # 关键：将输出格式设为 github，使评论自动出现在 PR 界面 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

这个 workflow 的精妙之处在于--diff-base参数：它告诉ocrlint只分析从 base 分支（通常是 main）到当前 PR 的 diff，而不是扫描整个仓库。这保证了扫描速度（通常 < 3 秒），也确保了评论只针对本次变更——避免了“历史债务被翻旧账”引发的团队抵触。

3.5 第四步：验证与迭代——用真实 PR 测试你的第一条规则

现在，找一个包含@PostConstruct的真实 PR（或自己提一个测试 PR），观察效果。你会看到：

• 如果 PR 中新增了一个带FileReader调用的@PostConstruct方法，ocrlint会在该行下方自动生成一条 GitHub 评论，内容为：

  ⚠️critical: 禁止在 @PostConstruct 方法中执行 I/O 操作
  @PostConstruct方法在 Spring Bean 初始化时同步执行，若在此处进行文件读写、网络请求等 I/O 操作，将导致应用启动阻塞。
  建议修复：将 I/O 操作移至单独的@EventListener(ApplicationReadyEvent.class)方法中，或使用CompletableFuture异步执行。

• 评论会精确钉在new FileReader(...)这一行，而不是整个方法。

• 如果你点击评论右上角的 “Show command output”，能看到完整的 AST 匹配路径，证明这不是幻觉，而是可验证的推理。

这条规则上线后，我们团队再没发生过因@PostConstructI/O 导致的启动故障。更重要的是，它建立了一种新的协作习惯：当有人想绕过规则时，他必须在 PR 描述里写明“本次 I/O 是安全的，因为……”，这本身就在提升代码的可理解性。

注意：规则不是一次写成就一劳永逸。我们每周五下午留出 30 分钟，集体 review 新增的 false positive/negative，然后更新isIoMethod白名单或调整 pattern。这个过程比写代码更有价值——它让团队对“什么是安全的初始化”达成了共识。

4. LLM Agent 如何真正赋能 Code Review？——超越“生成评论”的三层协作架构

很多团队尝试过让 LLM “直接写 Code Review 评论”，结果要么是泛泛而谈的废话（“代码结构清晰，很好！”），要么是离谱的误判（如前文 Rust 校验和案例）。问题不在于 LLM 能力不足，而在于我们把它放在了错误的位置——让它扮演“最终裁决者”，而非“智能协作者”。open-code-review 的 LLM Agent 设计，遵循一个核心理念：LLM 不输出结论，只输出推理线索；不替代规则引擎，只增强其表达力。它被严格限定在三层协作架构中，每一层都有明确的输入、输出和责任边界。

4.1 第一层：规则引擎（The Rule Engine）——负责“能不能做”，输出布尔判断

这是整个系统的基石，完全不依赖 LLM。它由前面介绍的 YAML 规则集驱动，用确定性算法（AST 遍历、数据流分析、控制流图构建）回答一个问题：“这段代码是否违反了某条已知规则？” 输出只有两个值：true（违规）或false（合规）。例如：

• 输入：一段包含Thread.sleep(5000)的 Java 方法，且该方法被@PostConstruct标记。
• 输出：{ "rule_id": "java-no-blocking-in-postconstruct", "violation": true, "line": 42 }

这一层的价值是可预测、可审计、零幻觉。你可以用单元测试覆盖每条规则，确保它在 JDK 版本升级后依然稳定。它不关心“为什么危险”，只关心“是否匹配”。

4.2 第二层：解释生成器（The Explanation Generator）——负责“为什么危险”，输出自然语言线索

当规则引擎判定为true后，才轮到 LLM 出场。但它的任务不是“写评论”，而是“生成解释线索”。它接收的输入非常克制：

• 规则 ID 和名称（如java-no-blocking-in-postconstruct）
• 违规代码片段（精确到行，带上下文 3 行）
• 该规则的官方文档链接（如 Spring 官方关于@PostConstruct的说明）
• 一个固定的 system prompt（强调“只解释技术原理，不提供修复建议”）

例如，对Thread.sleep(5000)违规，LLM 的输出可能是：

{ "explanation": "Spring 的 @PostConstruct 方法在 Bean 初始化阶段同步执行。此时应用上下文尚未完全就绪，所有依赖的 Bean 可能还未完成注入。在此处调用 Thread.sleep(5000) 会阻塞主线程 5 秒，导致整个应用启动流程停滞。根据 Spring 文档，@PostConstruct 应仅用于轻量级、无副作用的初始化操作。", "sources": ["https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/beans/factory/annotation/PostConstruct.html"] }

注意：这里没有“你应该改成……”，没有“建议使用……”，只有客观的技术事实和权威引用。LLM 在这里的作用，是把冷冰冰的规则描述，翻译成工程师能立刻理解的上下文。它不创造新知识，只做知识的精准转译。

4.3 第三层：评论合成器（The Comment Synthesizer）——负责“怎么表达”，输出最终 human-readable 评论

最后一环，是将规则引擎的判定、解释生成器的线索、以及工程师的个性化偏好，合成一条真正可用的 GitHub 评论。这一步完全由代码逻辑完成，不经过 LLM。它的工作流程是：

1. 结构化组装：将规则名称、严重等级、违规代码块、解释文本、官方文档链接，按预设模板拼接。
2. 上下文增强：自动插入git blame信息，显示该行代码是谁在何时写的（Last modified by @alice on 2024-03-15），帮助 reviewer 快速定位责任人。
3. 个性化适配：根据 PR 作者的 Slack ID，查询其偏好（如新人默认开启“教学模式”，展示更多背景知识；资深成员则只显示核心结论）。
4. 风险分级渲染：对critical级别，添加 🔴 图标和加粗警告；对warning级别，则用 🟡 图标和温和措辞。

最终生成的评论，看起来像这样（已去除 emoji，符合规范）：

critical: 禁止在 @PostConstruct 方法中执行阻塞操作 @PostConstruct 方法在 Spring Bean 初始化阶段同步执行。此时应用上下文尚未完全就绪，所有依赖的 Bean 可能还未完成注入。在此处调用 Thread.sleep(5000) 会阻塞主线程 5 秒，导致整个应用启动流程停滞。根据 Spring 官方文档，@PostConstruct 应仅用于轻量级、无副作用的初始化操作。 Last modified by @alice on 2024-03-15 Documentation: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/beans/factory/annotation/PostConstruct.html

这个三层架构的关键优势在于：每一层都可以独立替换、测试和优化。你可以明天就把解释生成器换成另一个 LLM（比如 DeepSeek-Coder），只要它遵守输入/输出契约，整个系统不受影响；你也可以后天把规则引擎换成 CodeQL，只要它能输出相同的 JSON 结构，上层逻辑无缝衔接。这种解耦，让 open-code-review 成为一个可演进的平台，而非一个绑定特定技术的黑盒。

实操心得：我们最初把 LLM 放在第二层时，曾用过一个“万能 prompt”：“请用通俗语言解释这个代码为什么危险”。结果模型开始编造 Spring 的内部实现细节（如“Spring 使用单例线程池管理 @PostConstruct”），这完全是胡说。后来我们强制要求 prompt 中必须包含“仅基于提供的文档链接内容作答”，并加入后置校验（用正则过滤掉所有未在文档中出现的专有名词），误报率从 37% 降到 1.2%。这再次证明：LLM 的力量，不在于它的自由发挥，而在于被精心约束后的精准输出。

5. 从 “Agent vs LLM vs Embedding” 迷雾中突围——一张工程师能看懂的技术定位图

网络热词里频繁出现的agent、LLM、embedding，还有常被拿来对比的DeepSeek，让很多工程师陷入概念迷宫：“我到底该学哪个？”“我的项目该用哪个？” 这些名词不是平行关系，而是不同抽象层级的技术构件。open-code-review 的实践，恰恰为我们提供了一个绝佳的透镜，来厘清它们的真实定位。下面这张图，是我用三年实战踩坑后画出的工程师友好版技术定位图——它不讲理论，只讲“你在键盘上敲什么命令时，它们各自在后台干什么”。

5.1 LLM（大语言模型）：那个“博闻强记但容易瞎猜”的实习生

想象你招了一个刚毕业的实习生，他读过互联网上几乎所有的公开技术文档、Stack Overflow 回答、GitHub README，记忆力超群，能瞬间联想到十个相关知识点。但他有个致命缺点：分不清事实和臆测。你问他“Spring 的 @PostConstruct 是在什么时候执行的？”，他可能准确引用文档；但你问他“如果我在 @PostConstruct 里调用 sleep，会不会影响其他 Bean 的初始化？”，他就可能开始脑补线程调度细节，给出似是而非的答案。

这就是 LLM 的本质：一个基于海量文本训练的概率预测引擎。它不理解代码如何编译，不理解 JVM 如何加载类，它只是在“预测下一个 token 最可能是什么”。DeepSeek-Coder、Qwen、Llama 等，都是这一类模型的不同实例。它们的区别，就像不同大学的毕业生：知识广度、记忆精度、逻辑连贯性略有差异，但底层能力范式相同。

在 open-code-review 中，LLM 只被允许做一件事：当规则引擎已经锁定了一个确切的违规点（如第 42 行的Thread.sleep），LLM 负责把这个点，用工程师能立刻理解的语言，解释清楚“为什么这里危险”。它不参与“找 bug”，只负责“说人话”。这就像让实习生去给已确诊的病人写病情说明，而不是让他去当主治医生。

5.2 Embedding（嵌入向量）：那个“能把文字变成坐标”的测绘员

假设你要在公司知识库里找一篇关于“Spring 循环依赖”的文章。如果用关键词搜索“circular dependency”，可能找不到，因为原文写的是“bean A depends on bean B, and B depends on A”。Embedding 的作用，就是把“circular dependency”和“bean A depends on bean B, and B depends on A”都转换成一组数字（比如[0.23, -1.45, 0.89, ...]），然后计算它们的“距离”。距离越近，语义越相似。

在 open-code-review 中，embedding 用于两个关键场景：

• 规则推荐：当工程师在.open-cr/rules/目录下新建一个 YAML 文件时，ocrlint会实时计算该文件内容与已有规则的 embedding 距离。如果发现它和java-no-io-in-postconstruct高度相似，就会弹出提示：“检测到您正在编写与 '禁止在 @PostConstruct 中 I/O' 相似的规则，是否参考其 pattern？” 这避免了规则重复建设。

• 上下文检索：当 LLM 需要解释某个违规时，系统会先用 embedding 在内部知识库（包括 Spring 官方文档、团队 Wiki、过往 PR 评论）中检索最相关的 3 篇文档，然后把这些文档的摘要作为 context 传给 LLM。这确保了 LLM 的“解释”有据可依，而不是凭空捏造。

Embedding 不是智能，它只是一个高效的“语义搜索引擎”。它不生成文字，不推理逻辑，只做一件事：把文字变成数学空间里的点，让相似的东西靠得更近。它的价值，在于把 LLM 的“瞎猜”，变成了“有依据的联想”。

5.3 Agent（智能体）：那个“会拆解任务、调用工具、自主决策”的项目经理

这才是 open-code-review 的真正大脑。Agent 不是一个模型，而是一个程序框架。它定义了“当一个 PR 到来时，整个审查流程该如何运转”。它的核心工作流是：

1. 任务分解（Task Decomposition）：收到 PR 后，Agent 首先分析改动范围（哪些文件、哪些语言、哪些模块），然后决定“需要运行哪些规则集？”（如 Java 规则、Python 规则、Security 规则）。

2. 工具调用（Tool Calling）：Agent 不自己写代码，而是调用一系列专用工具：

   • 调用javaparser分析 Java 文件；
   • 调用tree-sitter解析 TypeScript；
   • 调用ocrlint执行规则扫描；
   • 调用 embedding 服务检索上下文；
   • 调用 LLM API 生成解释。

3. 决策与编排（Orchestration）：Agent 根据工具返回的结果，做出最终决策。例如：

   • 如果规则引擎返回violation: true，且 embedding 检索到高置信度文档，则触发 LLM 解释生成；
   • 如果规则引擎返回violation: false，但 LLM 在无约束模式下“主动”发现了一个潜在问题（我们称之为“bonus insight”），Agent 会将其标记为low-confidence，并只在 PR 评论区底部以灰色字体显示，不阻断合并。

Agent 的强大，在于它的可编程性。你可以用几行 Python 代码，定义一个新的 Agent 行为：

# 当检测到 Python 文件中有 requests.get() 调用时 if language == "python" and "requests.get" in code_snippet: # 且该调用不在 try/except 块内 if not in_exception_block(ast_node): # 则强制要求添加 timeout 参数 add_rule_requirement("python-requests-timeout")

这比训练一个新模型简单一万倍。Agent 是 glue code，是 workflow engine，是整个 open-code-review 系统的指挥中枢。

5.4 一张图看懂它们的关系

DeepSeek-Coder 是一个具体的 LLM 实例，就像“张三”是“实习生”这个角色的具体人选。你可以把 open-code-review 的 LLM 层，从 DeepSeek 换成 Qwen，只需改一行配置，整个系统照常运行。真正决定系统成败的，不是你用了哪个 LLM，而是你的 Agent 是否设计得足够鲁棒，你的规则引擎是否覆盖了关键风险，你的 embedding 是否连接了正确的知识源。

我见过太多团队，把精力耗在“该选哪个大模型”的辩论上，却忽略了最基础的规则建设和工作流设计。这就像花三个月挑选一辆顶级跑车，却忘了修好自家的 driveway。open-code-review 的实践告诉我：先建好路（Agent + 规则），再选合适的车（LLM），最后用导航（embedding）避开坑。顺序错了，一切白搭。