第13章：Understand-Anything —— 代码知识图谱

Skills 拆能力。Spec 写合约。Ralph Loop 循环到对。gstack 角色覆盖。Goal Workflow 串流水线。autoresearch 全自动闭环。官方插件注入领域知识。每一章都在回答同一件事：让 AI 写出更好的代码。

本章不教 AI 写代码——教 AI 读懂已有的代码。

Understand-Anything 是目前「代码理解」方向上最成熟的开源项目：48.4K Stars，15 个 AI Agent 平台支持，最新版本 v2.7.3。作者 Yuxiang Lin。装上之后，Agent 不再靠 grep 和逐文件阅读理解代码库——先查知识图谱。

13.1 问题：AI 不理解你的代码

AI 写代码很快。读代码是另一回事。

当你对 Claude Code 说「在这个功能里加上暗黑模式」，Agent 需要自己找出哪些文件跟主题相关、哪些组件需要适配、CSS 变量在哪里定义、有没有已有的主题切换逻辑。它用 grep 搜关键词，用 Read 逐文件阅读——每次一个文件，每次消耗上下文窗口。五万行的代码库，靠 grep + Read 理解全貌，几十轮对话。每轮烧 token，每轮都可能漏掉关键依赖。

Agent 不记昨天读过什么。你昨天问了「这个项目的认证逻辑在哪里」，今天再问，它从头搜。Understand-Anything 提前做了这件事。Agent 再来问，直接查知识图谱。

13.2 核心概念：代码 → 知识图谱

把代码库变成知识图谱。每个文件、每个函数、每个类是一个节点。import 关系、调用关系、继承关系是边。节点上挂 LLM 生成的摘要和标签，边上标依赖方向。

这张图有了之后：

• 快速定位。 搜索语义，不是搜索关键词。「认证逻辑在哪里？」——知识图谱返回 src/auth/ 模块及它依赖的 src/middleware/session.ts。
• 影响分析。 改了 UserModel，知识图谱展示哪些文件 import 了它、哪些函数调用了它的方法。
• 新人上手。 新成员 Clone 仓库后跑一次 /understand，再用 /understand-onboard 产出按依赖顺序的阅读指南——先看 domain 层，再看 service 层，最后看 API 层。

13.3 Tree-sitter + LLM：确定性骨架，语义血肉

Understand-Anything 的架构做了明确分工。

Tree-sitter 负责结构解析。把源代码解析成语法树，提取确定性事实：哪些文件 export 了哪些符号、import 来自哪个模块、函数调用了哪些函数、类继承自哪个类。同一份代码，Tree-sitter 每次输出完全相同——零随机性，零幻觉。这些结构事实在扫描阶段预解析成 importMap，文件分析 Agent 直接从 importMap 读取，不重新推导。Tree-sitter 还驱动增量更新——文件内容变了，fingerprint 定位变更范围。

LLM 负责语义判断。读入 Tree-sitter 产出的结构和原始源码，产出解析器做不到的事：每个节点的人类可读摘要、语义标签、架构层分类、业务域映射、引导式学习路径。Tree-sitter 确定「这文件导出了什么」，LLM 判断「这个文件是做什么的、属于哪一层、和哪些业务流程相关」。

分开的好处：结构解析不消耗 token、不膨胀、不摇摆。语义理解只在需要判断「含义」的地方才调 LLM。两侧产出可独立验证——结构结果和 import 语句逐条对账，语义结果人工抽查。

13.4 安装与配置

13.4.1 平台支持

Understand-Anything 支持 15 个 AI Agent 平台。核心引擎是同一套 TypeScript 代码，不同平台只是斜杠命令注册方式不同。

13.4.2 Claude Code 安装（推荐）

最简路径——Claude Code 内置 Plugin Marketplace：

/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything

第一条命令添加插件市场源，第二条安装插件。安装后 /understand 等命令全局可用。

13.4.3 一行命令安装（其他平台）

macOS/Linux：

curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash

指定平台：

curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s codex

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.ps1 | iex

安装脚本做的事：Clone 仓库到 ~/.understand-anything/repo，创建平台特定的符号链接，注册斜杠命令。重启 AI Agent 后生效。

13.4.4 更新与卸载

./install.sh --update          # 更新到最新版本
./install.sh --uninstall codex  # 卸载指定平台

13.5 五到七个专门的 Agent 流水线

运行 /understand，背后是五个专门 Agent 按序执行。

五个是基础流水线。/understand-domain 追加第六个 Agent——domain-analyzer，从代码中提取业务域、流程、步骤。/understand-knowledge 追加第七个 Agent——article-analyzer，处理 Karpathy-pattern LLM Wiki 文章，提取实体、声明和隐含关系。

文件分析 Agent 并发运行——最多 5 个并行，每批 20-30 个文件。LLM 调用的延迟被并行掩盖，大项目的分析时间主要由最长的那批文件决定，而不是文件总数。

增量更新模式（--auto-update 或 commit hook）：只重新分析变更的文件。Tree-sitter 的 fingerprint 检测哪些文件变了，只跑这几个文件的 file-analyzer，其他节点和边不动。小型 commit 的图更新秒级完成。

13.6 知识图谱的七种用途

13.6.1 交互式浏览：/understand-dashboard

产出的知识图谱可以导入交互式 Web Dashboard。每个节点可点击——点击文件节点，展示 LLM 摘要、导出的符号、依赖来源和去向。点击类节点，展示方法列表和继承链。节点按架构层颜色编码——API 层蓝色，Service 层绿色，Data 层橙色，UI 层紫色，Utility 层灰色。Dashboard 支持角色自适应 UI——初级开发者、PM、高级用户看到不同粒度的信息。

13.6.2 语义搜索：/understand-chat

搜索语义，不是关键词。「哪些模块处理用户认证？」——知识图谱中匹配到 src/auth/login.ts（摘要：「处理邮箱+密码登录」）、src/middleware/session.ts（摘要：「会话管理和 token 验证」）、src/models/User.ts（摘要：「用户数据模型和密码哈希」）。Agent 不仅告诉你在哪里，还能解释它们之间的协作关系。

13.6.3 影响分析：/understand-diff

改代码前先跑。告诉你在当前 diff 中，你改了哪些文件、每个被改文件影响了哪些下游依赖、哪些影响是「可能破坏」的、哪些是「需要测试」的。这是「在你把改动推出去之前，先让 AI 告诉你这一改会引发什么连锁反应」。

13.6.4 新人引导：/understand-onboard

自动生成项目上手文档——按依赖顺序，而不是文件名字母顺序。最底层的模块先讲，依赖它们的模块后讲。路径上附 LLM 摘要——「这个文件提供日期格式化、字符串转义和 UUID 生成，被项目中 17 个其他文件调用」。

13.6.5 业务域提取：/understand-domain

切换到业务视图。代码层的知识图谱展示技术结构——文件、函数、类。/understand-domain 提取业务结构——域、流程、步骤。一个电商项目，技术结构是 src/orders/ 目录下的文件。业务结构是「下单流程：购物车验证 → 地址校验 → 库存锁定 → 支付 → 订单确认」。

13.6.6 知识库分析：/understand-knowledge

Understand-Anything 处理的不仅是代码。它对 Karpathy-pattern LLM Wiki 有专门支持——纯 Markdown 文件 + index.md wikilinks 组织的个人知识库。/understand-knowledge 读取 Wiki 目录，确定性解析器提取 wikilinks 和分类，LLM 发现隐含关系、提取实体，生成力导向图。

13.6.7 深度解释：/understand-explain

对单个文件或函数做深度分析。「这个函数是做什么的，为什么这样设计，有什么性能考虑，有哪些调用方？」——不是给你代码注释的翻译，是给你这段代码存在的原因。

13.7 知识图谱的共享与版本控制

知识图谱产出 JSON 文件——.understand-anything/knowledge-graph.json。因为是 JSON，可以 Git。commit 一次，团队其他人 Clone 后直接拿到图，不需要重跑分析流水线。

.gitignore 按以下规则配置：

.understand-anything/intermediate/    ← 中间文件，不提交
.understand-anything/diff-overlay.json ← 本地临时文件，不提交

.understand-anything/ 下其余文件全部提交。大型项目（图文件 10MB+）用 Git LFS 管理：

git lfs install
git lfs track ".understand-anything/*.json"
git add .gitattributes .understand-anything/

commit 图的成本是一份 JSON 文件。收益是整个团队省掉重复的分析时间。

13.8 实战：用 Understand-Anything 理解 goscapy

goscapy 是一个纯 Go 网络协议库，12 个子包，200+ 个 .go 源文件。核心包包括 layers（以太网/IP/TCP/UDP/ARP/ICMP/IPv6/ICMPv6/NDP 等协议层实现）、packet（数据包序列化/反序列化核心接口）、pcap（抓包）、sendrecv（收发）、sniff（嗅探）、route（路由表）、reassembly（TCP 流重组）、arping（ARP 发现）、fields（协议字段注册表）、goscapy（高层快捷 API）。examples/ 下有 20 个示例程序，覆盖从以太网帧构造到 TCP SYN 扫描的完整场景。

这种规模的 Go 项目，新人想理解架构，通常要从 go doc 开始，然后逐包读 types.go 找接口定义，再追踪 layers/ 里的具体实现。一个下午至少耗掉。

用 Understand-Anything，几分钟。

第一步：Claude Code 中安装并运行。

/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything
/understand --language zh

Agent 做的事：

1. Tree-sitter 扫描 pkg/ 下所有 .go 文件，30 多个文件分析 Agent 并发提取每个包导出的函数、类型、接口；
2. architecture-analyzer 识别出 goscapy 的层次结构：
   1. packet/ 是核心接口层（Layer、Packet、SerializeBuffer），
   2. layers/ 是协议实现层（依赖 packet/ 的接口），
   3. pcap/、sendrecv/、sniff/ 是 I/O 层（依赖 layers/ 和 packet/），
   4. goscapy/ 是门面层（聚合所有下层能力）。

分析了将近一小时，分析完成，自动打开网页：

总之，眼花缭乱，需要你花点时间熟悉它的界面，以及你能不能从中获取帮助。

第二步：查构建器链。

/understand-chat goscapy 中一个 TCP SYN 包是怎么构建的？

Agent 查知识图谱，返回链路：goscapy.NewPacket() → packet.NewPacketInfo() 创建空数据包 → layers.EthernetType.Build() 加 Ethernet 头 → layers.IPv4Type.Build() 加 IP 头 → layers.TCPType.Build() 加 TCP 头（SYN flag）→ packet.Serialize() 序列化为字节流。每个 Build() 调用在知识图谱中用边标注，Agent 知道接口定义在 packet/layer.go:15 的 LayerBuilder 接口，TCP 实现在 layers/tcp.go:200 的 Build() 方法。

不靠 grep 搜 Build（200 个文件里至少有 40 个匹配）。不靠逐文件跟踪调用链。知识图谱一条边一条边走过。

第三步：影响分析。

/understand-diff

你改动了 packet/layer.go 的 Layer 接口定义（加了新方法）。知识图谱标记影响面：layers/ 下所有协议层都实现了这个接口——ethernet.go、ipv4.go、tcp.go、udp.go、arp.go、icmp.go、ipv6.go、icmpv6.go、ndp.go、vlan.go、gre.go，加上 pcap/、sendrecv/ 中引用 Layer 类型的函数。12 个文件受影响，需要逐文件补新方法实现。

第四步：新人上手。

/understand-onboard

产出一份按依赖顺序的阅读路径：第一步读 packet/layer.go（核心接口：Layer、Packet、LayerBuilder）→ 第二步读 packet/serialize.go（序列化原理）→ 第三步读 layers/ethernet.go（最简单的协议层实现）→ 第四步读 layers/ipv4.go（理解 options 和 fragmentation 处理）→ 第五步读 layers/tcp.go（理解 flag、checksum、状态机）→ 最后读 goscapy/goscapy.go（高层 API 封装）。每一个节点上都标注了关键的类型定义和核心方法，附 LLM 生成的中文摘要。

四个步骤，从安装到影响分析到新人阅读路径，200 个文件的 Go 项目全貌几分钟就通了。直接对 Claude Code 说「帮我理解这个项目」，Agent 靠 grep 猜结构。有知识图谱作骨架，是两套完全不同的东西。

13.9 支持的语言与本地化

Tree-sitter 覆盖了主流编程语言——TypeScript、JavaScript、Python、Go、Rust、Java、C、C++、Ruby、PHP、Swift、Kotlin。语言检测自动完成，不需要配置。

/understand --language zh 将输出切换为中文——节点摘要、Dashboard UI 标签、引导式学习路径。支持 en（默认）、zh、zh-TW、ja、ko、ru。

对中文开发者团队来说，中文知识图谱不仅降低阅读门槛，也让非技术角色（PM、设计师、运营）能读懂代码库的结构。

13.10 适用边界

最适合：五人以上的团队项目（知识图谱 commit 后新人上手速度翻倍）、长期维护的代码库（架构演进时可追踪模块间依赖变化）、跨语言项目（Tree-sitter 多语言解析让跨语言依赖关系可追溯）、频繁改动的核心模块（每次 commit 后增量更新，保持知识图谱最新）。

不适合：个人小项目（< 20 个文件，手动翻比生成知识图谱快）、单文件脚本、极度频繁变更的早期原型（代码结构一天三变，图的维护成本高于收益）。

13.11 与前后章节的关系

与第 2 章 Skills：Understand-Anything 本身是 Skill 包——通过 Plugin Marketplace 或 install.sh 安装、注册为 / 命令、Markdown + TypeScript 混合实现。这是 Pocock 的「一个 Markdown 文件定义一种行为」哲学在代码理解领域的体现。

与第 12 章官方插件：和 code-review、feature-dev 同类——都是通过 /plugin 或 /plugin marketplace 安装的插件。Understand-Anything 填补了官方插件未覆盖的缺口：代码理解。

与第 3 章 SDD：写增量规格需要知道哪些模块会被影响、哪些行为必须保持。知识图谱能显式回答这两个问题——让规格更有依据。

与第 5 章 gstack、第 7 章 autoresearch：多 Agent 流水线的架构共享同样的思路——不同 Agent 负责不同维度。Understand-Anything 的 Agent 是功能化分工——project-scanner 扫描、file-analyzer 提取、architecture-analyzer 分层。

与第 8 章 Goal Workflow：/to-issues 和 /review-it 能从知识图谱中获取代码结构信息，减少 grep + Read 的轮次。Understand-Anything 可以是 Goal Workflow 流水线的一层基础设施。

13.12 本章小结

Understand-Anything 是全书唯一聚焦「代码理解」而非「代码生成」的一章。AI 写好代码的前提是理解代码——而理解正是多数 AI 编码工具最薄弱的环节。grep + Read 能走通，但 token 成本高、遗漏概率大、缺乏记忆。

Understand-Anything 用 Tree-sitter + LLM 混合架构回答了这个问题——确定性的事归 Tree-sitter（imports、exports、调用链、继承），语义的事归 LLM（摘要、标签、架构分层、学习路径）。一次分析产出的 JSON 知识图谱可以 commit 到 Git，全团队共享。Dashboard 给人看，Chat 给 Agent 查，Diff 在改动前预警影响面。

在 goscapy 这个 200 文件 Go 项目上的实战说明了这个方案的可行性——几分钟内从安装到新人上手路径，覆盖了「这个项目怎么组织」「一个包怎么构建」「改了接口会影响多少文件」三个最常见的代码理解问题。

下一章讲 UML 在 AI 时代的新用途——当 AI 能生成 UML，当 UML 能反过来教我们理解 AI 生成的代码。