背景
Cloud Native
近年来,AI Agent(Cursor、Copilot、Claude Code、Codex 等)已经深度参与软件开发。从代码补全到跨文件重构,从 Bug 定位到架构设计,Agent 能力越来越强。从 Prompt Engineering 到 Context Engineering 到 Harness Engineering,驾驭 AI 的方式也在不断进化,Agent 的能力边界也在不断扩展。
然而,当我们把一个真实的企业级项目交给 Agent 时,一个被忽视的问题开始浮现:Agent 真的理解你的项目吗?
当前 Agent 理解代码的方式正在分化成两个明确的流派:
- 无索引流派:Claude Code 信奉 Unix 哲学,完全不做预索引:用 grep、rg、glob 实时搜索文件系统。Anthropic 内部测试发现 agentic search 性能全面超越 RAG,by a lot。简洁、实时、无隐私问题,但每次会话从零开始,且对大仓库代价高昂。
- CodeIndex 流派:Cursor、Windsurf、Copilot 走向量索引路线:用 tree-sitter 做语义切片,生成 embedding 存入向量数据库(如 Turbopuffer),再用 Merkle tree 做增量同步。Qodo 和 Augment Code 更进一步,在向量索引之上叠加了代码依赖图和 commit 历史索引。
两个流派各有所长,但面对以下问题时还是难以很好工作:
- 我要改 pkg/a2a 的 Adapter 接口,影响范围是什么?
- 向量相似度搜不到依赖链,grep 逐文件搜效率低且不完整
- 生产上 vibeops-xxx SLO 破线了,有大量的 pending request,什么原因,是代码变更吗?
- 代码索引只覆盖代码域,运维域的数据不在图里
- 项目里有没有跨越架构边界的异常依赖?
- 没有架构层级建模,跨越边界无从定义
这些问题的共性是:它们需要确定性的结构关系、跨域的实体关联、以及时间维度的变更历史。
笔者在可观测领域工作十多年,回顾可观测的发展,尤其是随着云原生、AI 原生系统复杂度不断上升,可观测面对的早已不只是“看一条日志、盯一张监控图”,而是要把应用、服务、容器、数据库、告警、变更、事件这些分散对象放回同一个上下文里,回答“谁和谁有关”“影响是如何传播的”“问题从什么时间点开始发生”。也正因为如此,阿里云可观测逐步从日志、指标、链路等零散数据的采集和展示,演进到面向对象、关系和时序的统一建模;UModel 正是在这样的实践背景下沉淀出来的。 站在这个视角再看代码理解,两者的发展轨迹就非常相似:从看日志到统一建模,可观测经历了从零散数据到 UModel 知识图谱的进化。而代码理解,即使最先进的 CodeIndex 方案,也还停留在帮 Agent 找到相关代码片段的阶段:找到了片段,但不理解结构。
代码理解的五种范式
Cloud Native
在展开技术方案之前,有必要先厘清当前代码理解的完整图谱。五种范式,代表了从无状态搜索到有状态推理的演进变化。
▍范式一:Agentic Search(Claude Code 流派)
Claude Code 是当前最极致的无索引路线。Anthropic 创始工程师 Boris Cherny 公开分享过这个决策的来龙去脉:Claude Code 早期版本用过 RAG + 本地向量库,但内部测试发现 agentic search 全面胜出:by a lot, and this was surprising。
它的工作方式纯粹到优美:
Agent 收到问题 → Glob: 按文件名模式匹配(近零 token 成本) → Grep (ripgrep): 按内容正则搜索(低 token 成本) → Read: 读取完整文件(高 token 成本) → 判断 → 下一轮搜索或给出答案
工具按 token 成本分层,Agent 自主决定搜索策略,像一个经验丰富的开发者在终端里 rg + cat 排查问题。这种 Unix 哲学的方法有几个真实的优势:
- 零预处理:不需要索引构建时间,打开项目即可工作。
- 永远新鲜:没有索引过期问题,每次搜索都是实时文件系统状态。
- 隐私友好:代码不离开本地,不生成 embedding,不上传到任何服务器。
- 简单可靠:依赖链极短:Agent + 文件系统 + ripgrep,没有向量数据库可以挂掉。
但这种方法的天花板同样明确:
- 无结构感知:rg HandleRequest 能找到所有出现位置,但分不清哪些是定义、哪些是调用、哪些是注释。Agent 要靠自己阅读代码来判断。
- 每次从零开始:上一个会话分析过的依赖关系,下一个会话全部作废。没有持久化的知识积累。
- 规模受限:200 个文件的 TypeScript 项目没问题;5 万个文件的企业级单仓,agentic search 可能需要 30+ 轮工具调用和几万 token 才能拼凑出全局依赖图。实际上根本不可能拼出完整的全局图:只能拼出与当前任务相关的局部视图。
- 无法做全局分析:无法回答列出所有跨架构层级的调用,因为架构层级本身就没有被建模。
▍范式二:CodeIndex / 向量索引(Cursor、Windsurf、Copilot 流派)
这是当前 AI IDE 的主流技术路线。以 Cursor 为例,其技术架构已有大量公开分析:
代码仓库 → tree-sitter 解析为 AST → 按语义单元切片(函数、类、逻辑块) → 生成向量 embedding → 存入 Turbopuffer 向量数据库 → Merkle Tree 跟踪变更,增量同步
Cursor 在工程上做到了几个精巧的优化:每 10 分钟用 Merkle Tree 根哈希比对检测变更,只重新嵌入变化的文件;团队成员间 92% 的代码库相似度可以复用索引,将新成员的首次索引从数分钟降到秒级;通过 .cursorignore 控制索引范围。
Windsurf(Codeium)用类似的 RAG 架构:768 维向量嵌入 + 自研 M-Query 检索:但额外叠加了 Cascade 上下文引擎,跟踪编辑历史、终端命令、导航模式等会话状态。GitHub Copilot 在 2025 年 3 月将语义搜索索引做到了秒级完成。
CodeIndex 的真正价值是语义搜索:Agent 不用知道精确的函数名,用自然语言描述意图就能找到相关代码。这是 grep 做不到的。
但 CodeIndex 有一个根本性的局限:向量相似度是文本层面的近似匹配,不是结构层面的关系推理。
- import pkg/a2a 在代码里是一条确定性的依赖关系,但在向量空间里只是一个文本片段的相似度信号。
- 找到所有直接或间接依赖 pkg/a2a 的模块需要图遍历,不是向量检索。
- 这个接口变更的影响沿调用链传播了几跳需要确定性的 calls 关系,不是语义相似度。
- Augment Code 的评测显示,Cursor 在 50+ 文件的跨文件重构中会出现不一致:前 30 个文件改对了,后 20 个因为上下文窗口溢出而产生错误。
CodeIndex 本质上是更聪明的搜索引擎:帮 Agent 找到正确的代码片段塞入上下文,但不替 Agent 做结构化推理。
▍范式三:Code Graph + RAG 混合(Qodo、Augment Code 流派)
Qodo 和 Augment Code 代表了 CodeIndex 的下一个演化方向:在向量索引之上叠加代码结构图。
Qodo 的技术栈显得尤其认真:
- 自研 Qodo-Embed-1 代码嵌入模型(1.5B 参数在 CoIR 基准上超越 7B 竞品),通过合成数据训练来捕获语法、变量依赖、控制流、API 用法等代码特有语义。
- 客户端构建代码图:函数、类、模块及其调用图、继承关系、跨语言链接。
- 服务端维护向量数据库 + 设计文档 + 架构图 + PR/commit 历史。
- AST 感知的切片策略:递归切分 AST 节点,回填 import 语句和类定义等关键上下文。
Augment Code 的 Context Engine 走得更远:
- 跨仓库的语义索引,理解服务间如何连接和依赖。
- 索引范围超出代码:commit 历史(为什么改)、codebase patterns、外部文档、ticket、甚至tribal knowledge。
- 2025 年发布 Context Lineage,索引 commit 历史和 diff 摘要,让 Agent 理解架构决策的演变。
- 通过 MCP 协议开放给任何兼容的 Agent,基准测试显示 30-80% 的质量提升。
这一流派的关键进步是:代码不只是文本,还是一个有结构的图。Augment 尤其体现了理解需要上下文,上下文需要历史的洞察。
但即使是最先进的 Code Graph + RAG 混合方案,仍有几个系统性的边界:
- 图的范围限于代码域:知道 A 调用 B,但不知道 B 对应的服务在生产环境出过什么告警。代码图和运维图是割裂的。
- 图的查询能力有限:服务于 RAG 检索的图,通常支持邻居查找和短路径查询,但不支持任意深度的图遍历、模式匹配、聚合分析。
- IDE 局部,非团队全局:索引绑定在开发者的 IDE 实例上。一个人分析过的结构洞察,另一个人无法直接复用。
- 缺乏标准化的时序维度:Augment 的 Context Lineage 开始做 commit 历史,但构建日志、部署日志、测试日志、事件日志:这些完整的时间记忆还不在图中。
▍范式四:CodeWiki / LLM 文档(DeepWiki 流派)
DeepWiki(GitHub 15.7k star,Cognition AI / Devin 背后的团队出品)代表了另一种路线:代码仓库 → LLM → 精美 Wiki 文档。只需把 URL 中的 github.com 替换为 deepwiki.com,就能看到自动生成的架构图、模块文档、函数注解。
对人类开发者快速了解陌生项目,这是极好的体验。DeepWiki 还支持通过 .devin/wiki.json 配置文件控制生成范围,通过 MCP Server 提供 ask_question、read_wiki_structure、read_wiki_contents 等工具接口。
但文档本质上是为人类阅读而优化的线性叙事:
- 难验证:LLM 生成的描述可能含有幻觉,而在代码理解中,一条错误的A 调用 B比没有信息更危险。
- 难遍历:文档无法回答列出所有调用 X 的函数这类图遍历查询。
- 难推理:不支持多跳分析:改了 A,沿 calls 关系走 3 跳,影响到哪些入口点。
- 难维护:改一行代码就要全量重生成。虽然 DeepWiki 支持 badge 触发自动刷新,但每次都是全量 LLM 调用,成本和延迟都不低。
- 不可编程:MCP 接口本质上是问文档一个问题,不是在图上执行一次查询。
CodeWiki 和 CodeIndex 的关系,类似于数据库领域里物化视图和查询引擎的关系:文档是预计算好的视图,回答预设问题很快,但无法回答视图之外的临时查询。
▍范式五:代码知识图谱(我们的选择)
五种范式可以按一条轴线排列:从“无状态搜索”到“有状态推理”。
如果说 Agentic Search 是每次现场勘察,CodeIndex 是带着高清地图勘察,Code Graph+RAG 是地图上标注了公路和铁路,CodeWiki 是请人写了一本地方志:那我们要建的是一个活的 GIS 系统:可以查询任意两点之间的路径,可以叠加实时交通数据,可以标注每条路的通行历史,可以随着地形变化持续更新,支持任意维度的空间分析。
关键差异不是更好的搜索,而是三个维度的系统性结合:
-
确定性 vs 概率性:CodeIndex 给你的是最可能相关的代码片段(向量相似度),Code Graph 给你的是 AST 解析出的结构关系(但查询能力受限于 RAG 框架),我们给你的是 AST 确定性提取 + SPL/graph-match 任意查询:置信度 1.0 的关系 + 图灵完备的查询语言。
-
代码域 vs 跨域:从 Agentic Search 到 Code Graph+RAG,所有方案都止步于代码域。这个模块调用了哪些函数:可以回答。这个模块对应的生产服务上周出过几次告警:无法回答。UModel 的 EntitySetLink 可以将 code.module 连接到 ops.service、event.alert、req.issue,Agent 沿着链路推理不需要跳出图谱。
-
快照 vs 时间线:CodeIndex 是当前代码的快照索引。Code Graph 开始加入 commit 历史。我们提供完整的时间维度:commit_log、build_log、deploy_log、test_log、incident_log,每种 LogSet 通过 DataLink 关联到 EntitySet。Agent 不只知道现在的结构是什么,还知道它是怎么演变到这里的和它在生产上表现如何。
从个人 Wiki 到代码 Wiki:
同一套范式,不同的确定性
Cloud Native
在之前的文章《如何用 UModel 构建一个会成长的个人 Wiki》中,我们探讨了一个核心问题:如果我们真的要做一个可长期维护、可持续演进、对 Agent 友好的知识系统,底层应该长什么样?
那篇文章的结论是:真正让知识系统长期成立的,不只是 Agent,也不是 Markdown,而是一个足够清晰的建模层。UModel 提供了这个建模层:用 Set 表达对象,用 Link 表达关系,用 Field 约束语义。
个人 Wiki 的流程是:原始资料 → LLM 抽取实体和关系 → 对齐与规范化 → UModel 结构层 → Wiki 页面。整个抽取过程完全依赖 LLM,因此每条关系天然带有不确定性:张城和元乙是不是同一个人?这篇文章和那个项目有没有关系?都需要 LLM 来判断,需要对齐层来修正…