Understand Anything：把代码库变成 AI 可查询的知识图谱

一、学习目标

读完本文，你应该能够：

1. 解释 Understand Anything 的核心功能：说清楚它如何把代码库变成可查询的知识图谱，以及它解决什么问题（AI 编程工具在项目整体结构上的"失明"）。
2. 描述 Understand Anything 的工作流程：从 Phase 0 到 Phase 7 的完整流程，包括项目扫描、语义切批、文件分析、图谱合并、架构识别、tour 生成等步骤。
3. 理解 Tree-sitter 与 LLM 的分工：知道哪些工作由确定性分析完成（结构抽取），哪些工作交给 LLM（语义摘要），以及这种分层的好处。
4. 使用 Understand Anything 加速新人 onboarding：能为实际项目生成知识图谱，用 Dashboard 和 tour 快速建立系统全貌。
5. 判断 Understand Anything 是否适合你的团队：能根据项目规模、协作模式、安全策略做出选型决策。

二、目录

• 定位
• 项目现状
• 系统地图
• 它和"把仓库塞给 LLM"的区别
• knowledge-graph.json 里有什么
• 一次真实任务如何流过系统
• Dashboard 提供的视角
• 快速上手
• 多平台支持的实现方式
• Tree-sitter 与 LLM 的分工
• 图谱即文档
• v2.7.3 的关键变化
• 与同类工具的差异
• 适用边界
• 采用建议
• 自测题
• 练习
• 进阶路径
• 资料口径说明
• 最后

定位

Understand Anything 把读代码拆成两段：结构抽取回答"代码里有什么、谁依赖谁"，LLM 摘要回答"这些模块承担什么职责、应该按什么顺序读"。它更适用的是这几类场景——新人 onboarding、PR review、20 万行级别重构前的影响面判断。传统代码搜索和"把整个仓库塞进上下文"在这几类场景里都不太够用，前者只能给字符串匹配，后者会撞上上下文窗口和失焦。

真正值得展开看的是 .understand-anything/knowledge-graph.json。把它当 Dashboard 容易看偏：Dashboard 只是入口之一，聊天、diff 影响分析、onboarding 导览都消费这份 JSON，图谱本身可以提交、复用、增量更新，是长期维护的工程资产，不是某次扫描的临时副产物。

下面聊三件事：它和 Sourcegraph、Cursor/Copilot、依赖分析工具的边界，多 Agent 流水线为什么同时用 Tree-sitter 和 LLM，哪些团队该把 .understand-anything/ 提交到仓库、哪些场景反而不必。

项目现状

旧资料里引用的 Lum1104/Understand-Anything 和 16K-55K 不等的 Stars 数据都已经过期。README 仍注明项目最初由 Lum1104 创建，但当前仓库主体是 Egonex-AI/Understand-Anything，安装命令、仓库链接、活跃度判断都按这个仓库来。

系统地图

架构可以分成四层：扫描层、语义分析层、图谱装配层和使用层。

阶段的边界按"能不能确定性完成"划：扫描、语言识别、import 解析、结构抽取这些能由脚本和 Tree-sitter 完成的工作，留在确定性管线里；文件摘要、标签、业务语义、tour 解释这类需要上下文判断的工作，才交给 LLM。结构骨架和语义注释因此分开存储，前者能复现，后者负责解释。

它和"把仓库塞给 LLM"的区别

很多代码理解工具走的是"把仓库喂给模型，让模型总结"的路线。Understand Anything 在 /understand 里把这条管线拆得更细：

1. Phase 0 处理项目根目录、worktree redirect、语言偏好、.understandignore、已有 graph 和增量策略。
2. Phase 1 用 project-scanner 生成文件清单、语言、框架、行数、文件类别和 import map。
3. Phase 1.5 用 compute-batches.mjs 做语义切批，避免一个 Agent 处理过大的上下文。
4. Phase 2 让多个 file-analyzer 并行处理批次，默认最多 5 个并发。
5. Phase 3 到 Phase 6 依次合并图、识别层级、生成 tour、执行图谱校验。
6. Phase 7 写出最终 .understand-anything/knowledge-graph.json 和元数据，并清理中间目录。

file-analyzer 不是直接读源码自由发挥。它会先运行 bundled extract-structure.mjs，用 Tree-sitter 和专用 parser 提取函数、类、导入、导出、call graph 以及部分非代码结构。LLM 拿到这些结构化结果后，再补摘要、标签、复杂度和语义边。

这种分层之下，LLM 还是会总结错，但它的失败模式变了：结构事实先由静态分析给出，LLM 错的多是措辞和归类，不再凭空猜依赖关系。

knowledge-graph.json 里有什么

.understand-anything/knowledge-graph.json 的字段可以分成五块：

这份 JSON 不止记录 import 边。传统依赖分析一般只回答"谁 import 了谁"，Understand Anything 还会把配置、CI、文档、基础设施、schema 这类非代码文件纳入图谱。在真实项目里，很多"为什么这样设计"的答案藏在 README、Dockerfile、GitHub Actions、OpenAPI schema 或迁移脚本里。

2.7.x 之后还补强了 tested_by 边。合并脚本会把测试覆盖关系规范化，尽量从 LLM 批次输出和路径约定中恢复"生产代码 -> 测试文件"的关联，并给被测试的生产节点打上 tested 标签。这个细节对 PR review 很有价值：能看到改动影响了哪些模块，也能看到附近有没有测试保护。

一次真实任务如何流过系统

新加入团队时，常见的起点是搞清"支付流程从 API 到数据库经过哪些模块"。传统做法是先在 IDE 里搜 payment，再从 controller、service、model、job 一路跳。用 Understand Anything 时，路径更接近这样：

1. 先在项目里运行 /understand --language zh，生成中文摘要和中文 Dashboard UI。
2. 打开 /understand-dashboard，在结构图里搜索 payment 或"支付"。
3. 如果你更关心业务语义，切到 domain view，看它是否把系统拆成 domain、flow、step。
4. 用 /understand-chat 支付流程从入口到落库经过哪些模块？ 让它基于图谱回答，而不是让模型临时扫仓库。
5. 准备改代码前运行 /understand-diff，让它把当前 git diff 映射到 graph node 和一跳影响面。

先拿到系统地图，再进入源码细节。对 20 万行级别的项目，这一步比直接看代码更省时间——新人最缺的不是某个函数的解释，而是哪些文件是入口、哪些模块是核心、哪些边界不能随便碰。

Dashboard 提供的视角

Dashboard 目前基于 React 19、Vite、@xyflow/react、Dagre、ELK、D3 Force、Graphology、Zustand 和 Tailwind CSS v4。它给同一份图谱提供多种阅读方式。

搜索、导览、解释、diff、业务视图都消费同一份 graph 数据。这是它和一次性"代码转图"工具的差别：后者通常只交一张静态截图，前者把图谱当成长期工件的入口。

快速上手

Claude Code 原生插件安装：

/plugin marketplace add Egonex-AI/Understand-Anything
/plugin install understand-anything

分析当前项目：

/understand

生成中文节点摘要、Dashboard UI 和 guided tour：

/understand --language zh

打开 Dashboard：

/understand-dashboard

继续探索代码库：

# 询问项目结构或业务流程
/understand-chat How does the payment flow work?

# 分析当前修改影响面
/understand-diff

# 深入解释某个文件或函数
/understand-explain src/auth/login.ts

# 给新人生成 onboarding 指南
/understand-onboard

# 提取业务 domain / flow / step
/understand-domain

# 分析 Karpathy-pattern LLM wiki
/understand-knowledge ~/path/to/wiki

Codex、OpenCode、Gemini CLI 等平台可以用统一安装脚本：

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

# 或直接指定平台，例如 Codex
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s codex

Windows 使用 PowerShell：

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

Copilot CLI 的安装命令是：

copilot plugin install Egonex-AI/Understand-Anything:understand-anything-plugin

多平台支持的实现方式

多平台支持并不意味着每个平台各写一套分析引擎。核心逻辑集中在 understand-anything-plugin/：

understand-anything-plugin/
├── agents/             # project-scanner、file-analyzer、architecture-analyzer 等 Agent 定义
├── hooks/              # auto-update post-commit hook
├── packages/
│   ├── core/           # 共享分析核心、schema、search、tree-sitter、tour 等
│   └── dashboard/      # React/Vite Dashboard
├── skills/             # /understand、/understand-dashboard、/understand-chat 等命令
└── src/                # chat、diff、explain、onboard 等能力实现

不同平台主要解决"命令如何被宿主识别、插件目录如何被发现、符号链接如何建立"这些事。统一 install.sh / install.ps1 之后，这部分成本下降不少。v2.7.3 的 release note 里也明确提到：旧的分平台安装器不再是主路径，统一安装脚本会根据目标 CLI 建立对应 symlink 和配置。

团队里有人用 Claude Code，有人用 Codex，有人用 Cursor 或 Copilot，理论上仍然可以共用同一份 .understand-anything/knowledge-graph.json。

Tree-sitter 与 LLM 的分工

“混合分析"可以粗略拆成两条线。

第一条线是确定性分析：

• scan-project.mjs 负责枚举文件、识别语言、分类文件、估算复杂度。
• extract-import-map.mjs 负责解析项目内 import 关系。
• extract-structure.mjs 用 Tree-sitter 和专用 parser 抽取函数、类、导入、导出、配置、schema、CI step 等结构。
• merge-batch-graphs.py 负责合并、去重、规范 ID、清理 dangling edge，并补充 tested_by 关系。

第二条线是 LLM 语义分析：

• file-analyzer 给文件、函数、类写摘要、标签和复杂度判断。
• architecture-analyzer 把文件和边映射到架构层。
• tour-builder 生成按依赖顺序的学习路径。
• article-analyzer / domain-analyzer 处理知识库和业务域图谱。
• graph-reviewer 在 --review 模式下执行更完整的 LLM 质量检查；默认路径还有内联确定性校验。

完全靠 LLM 读源码的 AI 编码工具会撞上两类问题：上下文不够时漏关系，上下文太大时摘要变泛。Understand Anything 把 LLM 放在"解释结构"这一格，不让它当唯一 parser。

图谱即文档

README 建议把 .understand-anything/knowledge-graph.json 提交到 git。推荐提交 .understand-anything/ 里的核心工件，排除这些本地中间产物：

.understand-anything/intermediate/
.understand-anything/diff-overlay.json

收益：

• 新人 clone 仓库后可以直接打开 Dashboard，不必先跑一遍完整分析。
• PR review 可以围绕同一份图谱讨论影响面。
• 文档不再是独立 Markdown，而是和代码 commit 绑定的结构化索引。
• --auto-update 可以挂 post-commit hook，让 graph 跟随提交更新。

代价：大型仓库的 graph 可能超过 10 MB，README 建议用 Git LFS 管理。图谱会包含项目结构、文件摘要、业务语义和部分关系。如果仓库包含敏感业务逻辑或内部系统名称，不要把 graph 当成无害产物随便公开。

v2.7.3 的关键变化

GitHub 上最新 release 是 v2.7.3，围绕"可复用图谱"补了这些细节：

本地化和增量是这版最值得关注的两个变化。前者影响国内团队是否愿意把它用在 onboarding 上，后者决定图谱能不能从一次性演示变成长期维护的工程资产。

与同类工具的差异

Understand Anything 不能取代所有文档。机器自动生成"项目地形图”，团队再补"关键设计决策、历史原因、风险约束"——前者随代码自动更新，后者必须有人判断。

适用边界

建议优先尝试的场景：

• 新人加入中大型代码库，需要快速建立系统全貌。
• 多团队共用一个 monorepo，跨域理解成本很高。
• 代码审查前需要知道一个 diff 影响哪些模块。
• 架构文档长期滞后，团队想要一份跟 commit 绑定的结构化索引。
• PM、架构师或技术负责人需要看业务流程，而不是逐文件读源码。
• 个人或团队维护 Karpathy 风格 LLM Wiki，想把文档变成可导航图谱。

建议先不投入的场景：

• 小项目，文件少、依赖浅，直接读源码更快。
• 主要问题是运行时行为、性能瓶颈或线上状态，静态图谱无法代替 tracing、profiling 和日志。
• 团队无法接受生成物进入仓库，也没有明确的 graph 刷新责任。
• 代码和文档里有大量敏感信息，却没有清晰的脱敏和访问控制。
• 指望它替你做架构决策。它能整理结构，但哪些边界该保留还是要人来判断。

采用建议

在团队里试用时，建议先选一个子集，不要一上来全仓库铺开。具体路径可以分六步：

1. 选一个 5 万到 20 万行之间、文档不太完整但边界还算清晰的项目。
2. 先运行 /understand --language zh，只让少数维护者看 Dashboard 和 tour。
3. 用 /understand-chat 问 5 个真实 onboarding 问题，比如"请求从入口到数据库经过哪些层"“哪个模块处理鉴权"“某个 job 依赖哪些 service”。
4. 用一次真实 PR 跑 /understand-diff，看它给出的影响面是否符合维护者直觉。
5. 如果结果有用，再决定是否把 .understand-anything/knowledge-graph.json 提交到仓库，并约定刷新频率。
6. 对大图启用 Git LFS，对敏感项目先限制 graph 的可见范围。

评估标准不在 demo 好不好看，而在几项实际效果：它能不能缩短新人第一次定位系统边界的时间，能不能在 review 前暴露影响面，能不能让 AI 编码助手在项目级问题上少一点盲猜。

自测题

读完本文后，请自测以下问题：

1. Understand Anything 的核心功能是什么？它解决什么问题？

   点击查看参考答案

   • 核心功能：把代码库变成一份可查询的知识图谱（.understand-anything/knowledge-graph.json）
   • 解决的问题：AI 编程工具写局部代码越来越顺手，但一碰到项目整体结构就容易"失明”
   • 应用场景：新人 onboarding、PR review 影响面分析、架构理解与解释

2. Understand Anything 的工作流程是什么？

   点击查看参考答案

   • Phase 0：处理项目根目录、worktree redirect、语言偏好、.understandignore、已有 graph 和增量策略
   • Phase 1-6：分析代码结构、提取符号、建立依赖关系、生成图谱
   • Phase 7：写出最终 .understand-anything/knowledge-graph.json 和元数据，并清理中间目录

3. 如何用 Understand Anything 加速新人 onboarding？

   点击查看参考答案

   • 运行 /understand --language zh 生成知识图谱
   • 让新人看 Dashboard 和 tour（项目结构导览）
   • 用 /understand-chat 问 5 个真实 onboarding 问题（例如：“请求从入口到数据库经过哪些层？““哪个模块处理鉴权？““某个 job 依赖哪些 service？"）
   • 用 /understand-diff 看 PR 的影响面

4. Understand Anything 的局限性和边界是什么？

   点击查看参考答案

   • 静态图谱：无法代替运行时 tracing、profiling 和日志
   • 生成物维护：团队需要接受生成物进入仓库，并明确 graph 刷新责任
   • 敏感信息：代码和文档里有大量敏感信息，需要清晰的脱敏和访问控制
   • 架构决策：图谱能整理结构，但哪些边界该保留还是要人来判断

5. 如何在团队里试用 Understand Anything？

   点击查看参考答案

   • 先选一个子集（5 万到 20 万行之间、文档不太完整但边界还算清晰的项目）
   • 先运行 /understand --language zh，只让少数维护者看 Dashboard 和 tour
   • 用 /understand-chat 问 5 个真实 onboarding 问题
   • 用一次真实 PR 跑 /understand-diff，看它给出的影响面是否符合维护者直觉
   • 如果结果有用，再决定是否把 .understand-anything/knowledge-graph.json 提交到仓库

练习

练习 1：为你的项目生成知识图谱

目标：从零开始安装 Understand Anything，并为你的一个实际项目生成知识图谱。

步骤：

1. 安装 Understand Anything：根据官方 README 的安装方式（统一 install.sh / install.ps1）
2. 进入你的一个实际项目目录（5 万到 20 万行之间，代码结构相对清晰）
3. 运行 /understand --language zh 生成知识图谱
4. 检查生成的 .understand-anything/knowledge-graph.json 是否准确反映了项目结构
5. 用 /understand-chat 问几个关于项目结构的问题，验证图谱的准确性

验证：生成的图谱能准确回答项目结构问题吗？和你自己理解的项目结构一致吗？

练习 2：用 Understand Anything 做 PR review

目标：实践用知识图谱分析 PR 的影响面。

步骤：

1. 找一个你团队的真实 PR（或模拟一个）
2. 运行 /understand-diff 分析这个 PR 的影响面
3. 检查它给出的影响面是否符合你的直觉（哪些模块会受影响？哪些依赖需要更新？）
4. 对比传统的 PR review（只看 diff 和描述），评估知识图谱是否提供了额外价值

验证：/understand-diff 给出的影响面分析准确吗？能帮你发现传统 review 容易遗漏的问题吗？

练习 3：评估 Understand Anything 是否适合你的团队

目标：系统评估你团队的项目规模和协作模式，判断是否需要引入知识图谱工具。

步骤：

1. 明确你团队的项目规模（代码行数、模块数量、依赖复杂度）
2. 评估当前 onboarding 成本（新人需要多少天才能独立做 PR？）
3. 评估当前 PR review 质量（是否能发现跨模块影响？是否经常漏掉依赖更新？）
4. 试用 Understand Anything 一个月，收集团队成员的反馈
5. 基于反馈决定是否在团队内推广

验证：引入知识图谱工具后，团队的 onboarding 成本和 review 质量有显著提升吗？

进阶路径

如果你想更深入地使用或扩展 Understand Anything，可以按这个顺序：

1. 深入理解源码：克隆 Understand Anything 仓库，理解它是如何分析代码结构、提取符号、建立依赖关系的
2. 定制化图谱生成：根据你的项目需求修改配置（例如：指定重点分析的模块、排除生成的代码、调整图谱粒度）
3. 结合 CI/CD 做自动化：在 CI 中自动生成和更新知识图谱，让每次 PR 都能看到影响面分析
4. 扩展到多项目场景：如果你有多个相关项目，研究如何让它们的知识图谱互相引用（例如：微服务架构下的跨服务依赖分析）
5. 贡献代码或文档：给 Understand Anything 提交 PR，修复 Bug、添加功能、改进文档
6. 探索更丰富的可视化：研究如何把知识图谱做成可交互的 HTML 页面（就像 thariq 的 html-effectiveness 项目一样）
7. 写一篇实践文章：把你团队的使用经验和教训写成文章，分享给社区

资料口径说明

为保障文章的判断和可操作性，在此说明本文章的资料来源和边界：

1. 信息来源与时效性：本文基于 Understand Anything 的官方仓库和文档。该项目仍在早期阶段，部分细节（命令行参数、配置选项、图谱格式）可能在你读到时已经更新。
2. 功能验证：文中提到的功能（Phase 0-7 的工作流程、Dashboard、tour、/understand-chat、/understand-diff）已在官方文档中描述，但我未逐一实测。实际使用时请参考最新官方文档。
3. 性能与准确性：知识图谱的准确性和生成速度取决于项目规模、代码复杂度、LLM 能力等因素。文中提到的"5 万到 20 万行"是推荐的项目规模，但你的实际体验可能不同。
4. 敏感信息处理：文中提到"代码和文档里有大量敏感信息，却没有清晰的脱敏和访问控制”，这是使用知识图谱工具时必须考虑的问题。实际部署时需要配置访问控制、脱敏规则、审计日志。
5. 采用建议的适用性：文中提到的"六步采用路径"是基于通用场景的建议。你的团队规模、项目类型、协作模式、安全策略可能影响最佳采用路径，需要酌情调整。
6. 更新记录：本文撰写于 2026-06-30，基于 Understand Anything 的当时版本。如果该项目在之后有重大版本更新，本文可能需要补充。

最后

AI 编程工具写局部代码越来越顺手，但一碰到项目整体结构就容易失明。Understand Anything 做的事很具体：把代码库变成一份可查询的图谱。剩下的——聊天、diff 分析、onboarding 导览——都在同一份图谱上展开。

不能说有了图谱就万事大吉。架构判断还是要人做，图谱也可能跟不上代码变化。但新人不用再靠问人和 grep 拼凑系统全貌，PR review 能看到改动的影响面，团队可以把项目知识从口头经验搬进一个跟代码一起维护的文件。对大型代码库来说，这就够了。