近年来，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 历史索引。
两个流派各有所长，但面对以下问题时还是难以很好工作：
这些问题的共性是：它们需要确定性的结构关系、跨域的实体关联、以及时间维度的变更历史。
笔者在可观测领域工作十多年，回顾可观测的发展，尤其是随着云原生、AI 原生系统复杂度不断上升，可观测面对的早已不只是“看一条日志、盯一张监控图”，而是要把应用、服务、容器、数据库、告警、变更、事件这些分散对象放回同一个上下文里，回答“谁和谁有关”“影响是如何传播的”“问题从什么时间点开始发生”。也正因为如此，阿里云可观测逐步从日志、指标、链路等零散数据的采集和展示，演进到面向对象、关系和时序的统一建模；UModel 正是在这样的实践背景下沉淀出来的。
站在这个视角再看代码理解，两者的发展轨迹就非常相似：从看日志到统一建模，可观测经历了从零散数据到 UModel 知识图谱的进化。而代码理解，即使最先进的 CodeIndex 方案，也还停留在帮 Agent 找到相关代码片段的阶段：找到了片段，但不理解结构。
在展开技术方案之前，有必要先厘清当前代码理解的完整图谱。五种范式，代表了从无状态搜索到有状态推理的演进变化。
▍范式一：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 系统：可以查询任意两点之间的路径，可以叠加实时交通数据，可以标注每条路的通行历史，可以随着地形变化持续更新，支持任意维度的空间分析。
关键差异不是更好的搜索，而是三个维度的系统性结合：
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：
同一套范式，不同的确定性
在之前的文章《如何用 UModel 构建一个会成长的个人 Wiki》中，我们探讨了一个核心问题：如果我们真的要做一个可长期维护、可持续演进、对 Agent 友好的知识系统，底层应该长什么样？
那篇文章的结论是：真正让知识系统长期成立的，不只是 Agent，也不是 Markdown，而是一个足够清晰的建模层。UModel 提供了这个建模层：用 Set 表达对象，用 Link 表达关系，用 Field 约束语义。
个人 Wiki 的流程是：原始资料 → LLM 抽取实体和关系 → 对齐与规范化 → UModel 结构层 → Wiki 页面。整个抽取过程完全依赖 LLM，因此每条关系天然带有不确定性：张城和元乙是不是同一个人？这篇文章和那个项目有没有关系？都需要 LLM 来判断，需要对齐层来修正。
代码领域有一个根本不同：代码的结构关系是确定性的。
import pkg/a2a 就是导入了 pkg/a2a，func (s *Server) HandleRequest() 就是 Server 类型的方法：这些不需要 LLM 推断，AST 解析即可确定，置信度 = 1.0。
这意味着代码 Wiki 可以在个人 Wiki 的范式之上，引入一个模型层的确定性保证：
个人 Wiki： 原始资料 → [LLM 抽取] → 对齐 → UModel → Wiki 页面 ↑ 全程依赖 LLM，置信度 0.4-0.9代码 Wiki： 代码仓库 → [AST 确定性提取] + [LLM 语义增强] → UModel → CLI 查询 ↑ 结构关系确定（1.0） ↑ 摘要/归属补充（0.6-0.9）
这一层确定性对 Agent 的推理至关重要：当 Agent 做 RCA 时，它需要信任调用链上的每一跳。如果某条 calls 关系是 LLM 猜的，整个推理链就不可靠。而 AST 提取的关系是确定性事实，Agent 可以无条件信任。
同时，代码 Wiki 保留了个人 Wiki 的 LLM 增强能力：模块摘要、文档-代码关联、组件归属这些语义层信息仍由 LLM 生成，标注为 INFERRED，Agent 可以选择性采信。
UModel 在可观测领域的核心设计是用 Set 和 Link 组成的图来描述 IT 世界：EntitySet 描述实体现态，LogSet 描述时序事件，MetricSet 描述度量指标，Link 将它们连接成网络。
当我们把同样的建模方法论应用到代码领域，获得的不只是一张结构图。
5 种 EntitySet 描述代码的现态，通过 repo_id 复合主键支持多仓库共存：
repo_id 参与主键计算（Entity ID = md5(repo_id:pk_value)），使得不同仓库的同名模块不会冲突，同一个图谱可以同时容纳多个项目。
6 种 EntitySetLink 描述结构关系：contains、imports、calls、extends、describes、belongs_to。每条关系标注 __confidence__ 和 __extraction_method__（EXTRACTED / INFERRED / AMBIGUOUS）。
这是 Code-WIKI 和所有纯图谱工具的关键分水岭。
在可观测领域，我们不只看 Pod 当前的状态（Entity），还要看它的日志和指标趋势。代码也一样：只看结构不看历史，等于只看了一帧截图。
代码领域的 Log 远不止 Git Commit：
Log 的价值在于和 Entity 的关联查询：
这个模块最近一周被谁修改过？ → commit_log WHERE module_path = X AND time > now()-7d。
上次部署之后有没有新增 incident？ → deploy_log JOIN incident_log ON time_window。
引入这个依赖之后，构建时间变长了吗？ → build_log GROUP BY week，交叉 commit_log 的依赖变更时间。
每条 LogSet 通过 DataLink 关联到对应的 EntitySet，Agent 可以从 Entity 跳转到 Log，或从 Log 回溯到 Entity。
代码从来不是独立存在的。它服务于需求，通过 CICD 到达生产，在运行时产生可观测数据，出了问题又回到代码来定位。当前的工具链中，每个环节都是一座孤岛：需求在 Jira 里，代码在 Git 里，构建在 Jenkins 里，运行在 K8s 里，告警在监控系统里。
当生产告警响起时，从告警追溯到代码变更，中间要跳转多少个系统、人工关联多少条信息？
UModel 的价值在于：所有这些实体可以活在同一个图里。
DETECT：增量变更检测
每个文件计算 SHA256 内容指纹，和上次构建的缓存比对。对于 vibeops-agents（~2375 个 Go 文件），增量构建通常只需处理几十个变更文件，耗时从全量的数分钟降到秒级。
EXTRACT：AST + LLM 双轨
AST 轨道（tree-sitter）：基于 PEG 的增量解析器，支持 40+ 语言，通过 tags.scm 规则跨语言一致地提取定义、引用、结构关系、导入关系、调用关系、继承关系。所有提取结果置信度 = 1.0。
值得注意的是，Cursor 等 CodeIndex 方案也使用 tree-sitter：但它们用 tree-sitter 做语义切片（把代码切成适合 embedding 的块），我们用 tree-sitter 做结构提取（提取定义、引用、调用、继承等确定性关系）。同一个解析器，服务于完全不同的目标：前者产出向量，后者产出图谱。
LLM 轨道：模块摘要（Agent 上下文注入片段，不是人读的文档）、文档-代码关联、组件归属。每条标注 __extraction_method__: INFERRED + 置信度。Agent 可按场景选择信任阈值：RCA 高置信度优先，探索场景可放宽。
RESOLVE：跨文件符号解析
单文件 AST 无法解决跨文件引用。RESOLVE 处理：
Go import github.com/org/repo/pkg/a2a → module_path pkg/a2a。
方法 receiver type (s *Server) → 归属 code.type pkg/server.Server。
调用 s.HandleRequest() → pkg/server.Server.HandleRequest。
接口实现 type Adapter struct implements Handler → extends 关系。
确定性解析，不依赖 LLM。
BUILD：图谱组装 + 架构发现
架构发现不是简单的社区检测：Louvain/Leiden 发现的是聚类，不是架构。完整流程：
Step 1: 图构建 module 为节点，imports + calls + extends 为有向边 边权重：calls > imports > extendsStep 2: 层次分析 计算依赖方向性：A→B 且 B↛A → A 在 B 上层 识别入度 = 0 的顶层入口和出度 = 0 的底层基础设施Step 3: 社区发现 Leiden 算法在有向图上发现功能簇 resolution 参数控制粒度（~150 模块 → ~15 组件）Step 4: 标注与命名 基于依赖方向标注层次：API/Gateway、Service/Business、Infrastructure/Utility LLM 命名和描述，与项目文档交叉验证
输出是有层次、有方向、有命名的架构视图。Agent 可以据此判断这个调用是否跨越了架构层次。
SYNC：同步到 UModel
Entity 写入: starops umodel post-logs → __entity logstoreTopo 写入: starops umodel post-logs → __topo logstoreSchema 同步: starops umodel sync（注册 EntitySet/Link 定义）
UModel 后端基于 SLS 存储引擎，继承了高吞吐写入、秒级查询、graph-match 图遍历、SQL 聚合、全文检索等能力。
SERVE：查询的工程细节
实践中摸索出的关键模式：
两步查询：graph-match 返回 entity_id，不含业务字段。所有图遍历查询先走拓扑获取 id 集合，再批量拉取业务字段：
Step 1: .topo | graph-match (n1:code@code.module {__entity_id__: '<id>'}) -[e]->(n2) project n1, e, n2Step 2: .entity with(domain='code', name='code.module', ids=['id1','id2',...])
聚合走 SLS 直查：热点分析等统计查询直接 SQL 查 __topo logstore：
SELECT __dest_entity_id__, count(1) as import_countFROM log WHERE __relation_type__ = 'imports'GROUP BY __dest_entity_id__ORDER BY import_count DESC LIMIT 20
在当前多仓库规模（~11000 实体、~19000 条边，含 vibeops-agents 和 starops-cli 两个项目）下，单次查询端到端延迟百毫秒。
Agent 的推理是渐进式的：先搜索，看到结果再决定下一步。CLI 的 search → context → impact 天然匹配这个模式，且支持批量执行和管道组合。
code-wiki query <子命令> ├── search <keyword> ├── context <name> ├── impact <path> ├── callers / callees ├── deps / rdeps code-wiki check <子命令> ├── arch └── hotspots code-wiki ingest code-wiki status
子命令按 Agent 意图组织。Agent 不需要知道底层是 graph-match 还是 SLS SQL：看影响范围就用 impact。
默认 --format brief 输出为 Agent 的 token 预算优化：
$ code-wiki query context pkg/a2aModule: pkg/a2a LOC: 1,247 | Language: Go | Component: a2a-protocol Summary: A2A protocol implementation for agent-to-agent communicationTypes (17): TaskStore(struct), A2AServer(struct), AgentCard(struct), ...Functions (52): HandleA2ARequest[entry], StartA2AServer[entry], ...Reverse dependencies (9): pkg/api/handler, pkg/server, cmd/vibeops-agents, ...Component crossings: → api, → scheduler
一个 query context 的输出 < 500 tokens。需要完整数据时用 --format json。
配合 CLI 的 Agent Skill 按场景组织，Agent 不需要学习 SPL 语法：
code-wiki query search <关键词> code-wiki query context <module> code-wiki query callers <function> code-wiki query impact <module> code-wiki query deps / rdeps code-wiki check arch code-wiki check hotspots
粤ICP备14082021号
免费POC，
零成本试错
