Harness 与 Agent 工程 · AI研发与测试工程 · 2026-04-23

从可观测到可理解:用 UModel 构建 Agent 原生的代码知识图谱

探索AI Agent如何真正理解企业级项目代码,UModel知识图谱带来革命性突破。

核心内容:

  1. 当前AI Agent理解代码的两大流派对比与局限性分析
  2. 企业级项目面临的代码理解核心挑战与需求
  3. UModel知识图谱如何借鉴可观测领域经验实现代码理解跃迁

背景

Cloud Native

近年来,AI Agent(Cursor、Copilot、Claude Code、Codex 等)已经深度参与软件开发。从代码补全到跨文件重构,从 Bug 定位到架构设计,Agent 能力越来越强。从 Prompt Engineering 到 Context Engineering 到 Harness Engineering,驾驭 AI 的方式也在不断进化,Agent 的能力边界也在不断扩展。

然而,当我们把一个真实的企业级项目交给 Agent 时,一个被忽视的问题开始浮现:Agent 真的理解你的项目吗?

当前 Agent 理解代码的方式正在分化成两个明确的流派:

两个流派各有所长,但面对以下问题时还是难以很好工作:

这些问题的共性是:它们需要确定性的结构关系、跨域的实体关联、以及时间维度的变更历史。

笔者在可观测领域工作十多年,回顾可观测的发展,尤其是随着云原生、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 哲学的方法有几个真实的优势:

但这种方法的天花板同样明确:

▍范式二: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 有一个根本性的局限:向量相似度是文本层面的近似匹配,不是结构层面的关系推理。

CodeIndex 本质上是更聪明的搜索引擎:帮 Agent 找到正确的代码片段塞入上下文,但不替 Agent 做结构化推理。

▍范式三:Code Graph + RAG 混合(Qodo、Augment Code 流派)

Qodo 和 Augment Code 代表了 CodeIndex 的下一个演化方向:在向量索引之上叠加代码结构图。

Qodo 的技术栈显得尤其认真:

Augment Code 的 Context Engine 走得更远:

这一流派的关键进步是:代码不只是文本,还是一个有结构的图。Augment 尤其体现了理解需要上下文,上下文需要历史的洞察。

但即使是最先进的 Code Graph + RAG 混合方案,仍有几个系统性的边界:

▍范式四: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 等工具接口。

但文档本质上是为人类阅读而优化的线性叙事:

CodeWiki 和 CodeIndex 的关系,类似于数据库领域里物化视图和查询引擎的关系:文档是预计算好的视图,回答预设问题很快,但无法回答视图之外的临时查询。

▍范式五:代码知识图谱(我们的选择)

五种范式可以按一条轴线排列:从“无状态搜索”到“有状态推理”。

如果说 Agentic Search 是每次现场勘察,CodeIndex 是带着高清地图勘察,Code Graph+RAG 是地图上标注了公路和铁路,CodeWiki 是请人写了一本地方志:那我们要建的是一个活的 GIS 系统:可以查询任意两点之间的路径,可以叠加实时交通数据,可以标注每条路的通行历史,可以随着地形变化持续更新,支持任意维度的空间分析。

关键差异不是更好的搜索,而是三个维度的系统性结合:

  1. 确定性 vs 概率性:CodeIndex 给你的是最可能相关的代码片段(向量相似度),Code Graph 给你的是 AST 解析出的结构关系(但查询能力受限于 RAG 框架),我们给你的是 AST 确定性提取 + SPL/graph-match 任意查询:置信度 1.0 的关系 + 图灵完备的查询语言。

  2. 代码域 vs 跨域:从 Agentic Search 到 Code Graph+RAG,所有方案都止步于代码域。这个模块调用了哪些函数:可以回答。这个模块对应的生产服务上周出过几次告警:无法回答。UModel 的 EntitySetLink 可以将 code.module 连接到 ops.service、event.alert、req.issue,Agent 沿着链路推理不需要跳出图谱。

  3. 快照 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 来判断,需要对齐层来修正…

— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/knowledgegraph/2026042347823.html