Understand Anything：从多平台安装到 Tree-sitter + LLM 混合架构的代码知识图谱实践指南

本文基于 Understand Anything 项目的俄语版官方 README 整理并深入仓库源码验证，完整覆盖功能全貌、快速开始、多平台安装、团队图谱共享等核心内容，并结合 核心技能定义、指纹模块 等实现细节，帮助你在 Claude Code、Codex、Cursor、Copilot、Gemini CLI 等平台上把任意代码库变成可探索、可搜索、可提问的交互式知识图谱。

Understand Anything 的定位可以用一句话概括：“目标是做一个能讲清代码如何拼合在一起的图谱，而不是一个用复杂度来炫耀的图谱。” 它通过多智能体流水线分析项目中的所有文件、函数、类与依赖，构建知识图谱，并提供可视化面板进行探索——无论是刚接手 20 万行代码新仓库的新成员，还是需要做 PR 影响面评估的资深工程师，都可以用它替代“盲读代码”。

核心功能一览

项目提供的能力可以分为“看结构”“懂业务”“查知识”三条主线，再加上一组辅助能力：

• 探索结构图谱：每个文件、函数、类都是可点击、可搜索的节点；选中任意节点可以看到通俗描述、关联关系和分步讲解。
• 理解业务逻辑：切换到领域视图，代码会被映射为真实的业务流程——领域（domain）、流程（flow）、步骤（step），以横向图谱形式呈现。
• 分析知识库：用 /understand-knowledge 指向一个 LLM 风格的 wiki（类似 Karpathy 提倡的 Markdown 知识库），即可得到带社区聚类的力导向知识图谱。确定性解析器从 index.md 提取 wikilinks 与分类，LLM 智能体负责发现隐含关联、抽取实体与论断——把 wiki 变成可导航的关联思想网络。

其余六项辅助能力如下（继承自原文档功能矩阵）：

能力	说明
分步导览（Tour）	自动生成按依赖关系排序的架构导览，以正确顺序学习代码库
模糊与语义搜索	按名称或按语义查找，例如“哪些部分负责认证？”，在整个图谱中获得相关结果
变更影响分析	在提交前查看改动波及系统的哪些部分，理解跨代码库的级联效应
角色自适应 UI	面板根据用户角色（初级开发者、PM 或高级用户）调整细节层级
分层可视化	按架构层自动分组——API、Service、Data、UI、Utility——并配彩色图例
语言概念讲解	12 种编程模式（泛型、闭包、装饰器等）在其出现的位置被就地讲解

面板本身是一个独立的 Vite + React 应用，源码位于 dashboard 包，其中 locales 目录 提供了中文、繁体中文、日文、俄文、韩文、英文等界面语言，角色选择器 与 分层图例 分别对应上面表格中的“角色自适应”和“分层可视化”能力。

快速开始

第一步：安装插件（Claude Code）

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

使用本地模型？ 面向私有化或企业场景，可以把平台的模型提供方切换到本地推理服务（例如 Ollama），按其官方集成指南更换模型提供方即可，其余流程不变。

第二步：分析代码库

/understand

多智能体流水线会扫描项目、抽取每个文件/函数/类与依赖关系，然后构建知识图谱并保存到 .ua/knowledge-graph.json。已经在用旧目录 .understand-anything/ 的项目会继续使用该目录——只要它存在就是数据目录，无需任何迁移。这一点在 SKILL.md 的数据目录解析逻辑 中有明确实现：优先检测 .understand-anything 是否存在，存在则沿用，否则使用新的 .ua。

注意 Token 消耗：首次运行 /understand 会分析整个代码库，在大项目上可能消耗大量 Token。建议在按量/包月 Token 计划下运行，或使用本地模型完成初始化。之后的运行默认是增量的——只重新分析发生变化的文件——因此开销小得多。增量的底层机制见后文增量更新与自动保鲜一节。

本地化输出：使用 --language 指定生成内容的语言：

# 生成俄语内容（知识图谱节点描述与面板 UI）
/understand --language ru

# 原文档列出的支持语言：en（默认）、zh、zh-TW、ja、ko、ru

--language 参数会影响三处内容：

• 知识图谱中的节点摘要与描述
• 面板 UI 的标签、按钮与提示文字
• 分步导览中的讲解文本

从 SKILL.md 的语言配置段 可以看到更完整的实现行为：参数接受 ISO 639-1 代码（zh、ja、ko、en、es、fr、de 等）或友好名称（chinese、japanese 等），支持 zh-TW、zh-HK 等区域变体；未显式指定时，已保存的偏好（config.json 中的 outputLanguage 字段）优先，否则首次运行会探测对话语言并请求确认一次，之后持久化到配置中，不再重复询问。

此外，源码中还支持原文档未提及的 --exclude <patterns> 参数（gitignore 语法、支持 ! 取反，优先级高于内置规则与 .understandignore，新增模式需配合 --full 重新扫描）以及 --full（强制全量重建）、--review（走完整 LLM 审阅）等选项，详见 SKILL.md 选项说明。

第三步：打开面板

/understand-dashboard

打开交互式 Web 面板，将代码库渲染为按架构层着色的图谱，支持搜索与可点击节点。选中任意节点即可查看其代码、关联关系和通俗描述。

第四步：持续学习

原文档给出的完整命令集如下，覆盖了日常使用的主要场景：

# 对代码库提问
/understand-chat How does the payment flow work?

# 分析当前改动的影响
/understand-diff

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

# 为团队成员生成入职指南
/understand-onboard

# 抽取业务知识（领域、流程、步骤）
/understand-domain

# 分析 Karpathy 风格的 LLM wiki
/understand-knowledge ~/path/to/wiki

# 随时重跑——默认增量（仅重新分析变更文件）
/understand

# 安装 post-commit 钩子，自动做增量更新
/understand --auto-update

# 超大 monorepo？用子目录限定分析范围
/understand src/frontend

多平台安装

Understand Anything 支持多个 AI 开发平台，以下按平台逐一说明（继承原文档全部内容）。

Claude Code（原生支持）

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

一行命令安装

适用于 Codex / OpenCode / OpenClaw / Antigravity / Gemini CLI / Pi Agent / Vibe CLI / VS Code Copilot / Hermes / Cline / KIMI CLI / Nanobot / Kiro。

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash
# 或直接传平台参数，跳过交互式选择：
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

安装器会把仓库克隆到 ~/.understand-anything/repo，然后为所选平台创建必要的符号链接；安装完成后重启 CLI/IDE。

如何调用 skill：调用前缀因平台而异。多数平台使用斜杠命令（/understand），但 Codex 使用 $——输入 $understand 而不是 /understand。如果两种前缀都不被识别，直接用自然语言说：“使用 understand skill 分析这个项目”。

• 支持的平台值 <platform>：gemini、codex、opencode、pi、openclaw、antigravity、vibe、vscode、hermes、cline、kimi、nanobot、kiro
• 更新：./install.sh --update
• 卸载：./install.sh --uninstall <platform>

从 install.sh 的平台表源码 可以看到，每个平台映射到一个目标技能目录和两种链接风格之一：per-skill（每个 skill 一个符号链接，如 ~/.agents/skills/understand、~/.copilot/skills/understand）或 folder（整个 skills/ 目录以 understand-anything 名义链接，如 ~/.kiro/skills/）。从源码结构看，该平台表实际还包含 trae 平台（对应 ~/.trae/skills），比文档列出的清单更宽。

Cursor

Cursor 在克隆本仓库后通过 .cursor-plugin/plugin.json 自动发现插件，无需手动安装——克隆并用 Cursor 打开即可。

如果自动发现未生效，可手动安装：打开 Cursor Settings → Plugins，在搜索框粘贴仓库地址并添加。

VS Code + GitHub Copilot

VS Code 搭配 GitHub Copilot（v1.108+）同样通过 .copilot-plugin/plugin.json 自动发现，克隆后用 VS Code 打开即可。若想让 skills 成为个人级（所有项目可用），运行上文 install.sh vscode。

Copilot CLI

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

Kiro CLI / IDE

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

安装完成后：

• Kiro CLI：kiro-cli chat --agent understand "Analyze this project"
• Kiro IDE：skills 被符号链接到 ~/.kiro/skills/，同时智能体 understand 写入 ~/.kiro/agents/understand.json，重启 IDE 后两者均可用。

个人级 skills 可通过 install.sh kiro 获得。

平台兼容性总表

平台	状态	安装方式
Claude Code	原生	插件 Marketplace
Cursor	支持	自动发现
VS Code + GitHub Copilot	支持	自动发现
Copilot CLI	支持	插件安装
Codex	支持	install.sh codex
OpenCode	支持	install.sh opencode
OpenClaw	支持	install.sh openclaw
Antigravity	支持	install.sh antigravity
Gemini CLI	支持	install.sh gemini
Pi Agent	支持	install.sh pi
Vibe CLI	支持	install.sh vibe
Hermes	支持	install.sh hermes
Cline	支持	install.sh cline
KIMI CLI	支持	install.sh kimi
Nanobot	支持	install.sh nanobot
Kiro CLI / IDE	支持	install.sh kiro

与团队共享图谱

图谱本质是一个 JSON 文件。固定（commit）一次之后，其他成员就可以跳过整个分析流水线。这对入职引导、PR 评审和 docs-as-code 流程都非常有用。原文档以 GoogleCloudPlatform/microservices-demo 的 fork 作为示例——一个 Go / Java / Python / Node 多语言、且已固定图谱的项目。

应提交什么：.ua/ 目录的全部内容，但排除 intermediate/ 和 diff-overlay.json（它们是本地临时文件）。使用旧目录的项目把 .ua/ 替换为 .understand-anything/：

.ua/intermediate/
.ua/diff-overlay.json

保持图谱新鲜：开启 /understand --auto-update，post-commit 钩子会增量更新图谱，使每个提交都伴随对应的图谱版本；或者在每次发版前手动运行 /understand。

大图谱（10 MB+）：建议用 git-lfs 存储：

git lfs install
git lfs track ".ua/*.json"
git add .gitattributes .ua/

没有 Claude Code 也能看面板

只要图谱已生成并提交，任何团队成员都可以用一条命令打开它——不需要 Claude Code、不需要 LLM、不需要 API Key，只需要 Node.js（>= 18，与 viewer 包的 engines 声明 一致）：

npx https://github.com/Egonex-AI/Understand-Anything/releases/latest/download/understand-anything-viewer.tgz /path/to/analyzed/project

终端会打印一个带 Token 的 URL（形如 http://127.0.0.1:5173/?token=…），随后完整交互式面板在浏览器中打开。项目目录（默认当前目录）需要包含已提交的数据目录（.ua/ 或旧版 .understand-anything/）。所有数据只读地从本地磁盘读取——没有 LLM 调用，没有任何数据离开你的机器。viewer 包 的定位也正是如此：“独立的只读查看器，无需 Claude Code 或 LLM”。

如果你就在本仓库的克隆里工作，也可以用开发模式跑同一套面板：

pnpm install
pnpm --filter @understand-anything/core build
GRAPH_DIR=/path/to/analyzed/project pnpm dev:dashboard

后者通过 Vite 开发服务器提供相同的功能。

内部机制：Tree-sitter + LLM 混合分析

原文档把内部设计概括为一句话：确定性工作交给静态分析，语义理解交给 LLM。

• Tree-sitter（确定性侧）：把源码解析为具体的语法树，抽取结构性事实——imports、exports、函数/类定义、调用点、继承关系。在扫描阶段预先解析为 importMap 并传给 file-analyzer，避免各批次重复从源码推断 import。同样输入永远得到同样输出；这套确定性也是增量更新所用指纹的基础。
• LLM（语义侧）：读取解析好的结构连同源码，生成解析器做不到的东西：面向人的摘要、标签、架构层职责、业务领域映射、引导式导览、语言概念注解。

正是这种分工让图谱结构上可复现（同一代码永远得到相同边），同时语义上抓住意图（文件是为什么存在，而不仅仅是它导入了什么）。

从源码看，确定性一侧由 TreeSitterPlugin 实现：它是一个配置驱动的插件，按 languages 配置目录 加载 WASM 语法，为已注册抽取器的语言（TypeScript、JavaScript、Python、Go、Rust、Java、Ruby、PHP、C/C++、C#、Dart、Kotlin、Swift、Scala）提供深度结构分析（函数、类、import、export、调用图）；没有对应 tree-sitter 配置的语言会优雅降级，交给 LLM 智能体分析。项目内部还内置了专门处理非代码文件的解析器（Dockerfile、env、GraphQL、JSON、Makefile、Markdown、Protobuf、Shell、SQL、Terraform、TOML、YAML），见 parsers 目录。

多智能体流水线

/understand 命令编排一组专职智能体，/understand-domain 再增加领域分析者。原文档给出的智能体职责表如下：

智能体	职责
project-scanner	文件发现、语言与框架识别
file-analyzer	抽取函数、类、imports；生成图谱节点与边
architecture-analyzer	识别架构层
tour-builder	生成分步学习导览
graph-reviewer	校验图谱完整性与引用一致性（默认走 inline 校验；--review 时启用完整 LLM 审阅）
domain-analyzer	抽取业务领域、流程与步骤（/understand-domain 使用）
article-analyzer	从 wiki 文章抽取实体、论断与隐含关联（/understand-knowledge 使用）

文件分析器并行工作（最多 5 个并发、每批 20–30 个文件）。各智能体的定义文件位于 agents 目录，例如 file-analyzer 定义 明确要求“两阶段分析”：先执行捆绑的结构抽取脚本 extract-structure.mjs（tree-sitter 处理代码文件、专用解析器处理非代码文件），再由 LLM 在确定性结果之上做摘要、标签、复杂度评级与语义边生成——这正是“混合架构”在智能体层面的落地。

从 SKILL.md 的完整阶段定义 看，实际执行被组织为 7 个主阶段（Phase 0–7）：

阶段	名称	关键行为
Phase 0	Pre-flight	解析目标目录、处理 git worktree 重定向、构建插件、解析数据目录，并按决策表选择全量/增量/仅审阅路径
Phase 0.5	Ignore 配置	生成/检查 .understandignore 排除规则文件，等待用户确认
Phase 1	SCAN	project-scanner 发现全部文件（含配置、文档、基础设施），输出语言、框架、importMap 与每文件的 fileCategory
Phase 1.5	BATCH	compute-batches.mjs 计算“语义批次”，使同批文件在语义上内聚，并附带跨批邻居符号表（neighborMap）
Phase 2	ANALYZE	最多 5 个 file-analyzer 子智能体并行分析各批次，随后 merge-batch-graphs.py 归一化节点 ID、去重、剔除悬空边、规范化 tested_by 测试覆盖边
Phase 3	ASSEMBLE REVIEW	assemble-reviewer 复核组装后的图谱
Phase 4	ARCHITECTURE	architecture-analyzer 识别架构层；语言上下文与框架附录从 languages 和 frameworks 目录按检测结果注入
Phase 5	TOUR	tour-builder 生成导览步骤，从检测到的项目入口点开始
Phase 6	REVIEW	默认内联确定性校验（节点/边/层/导览引用完整性）；--review 时派发 graph-reviewer 全量 LLM 审阅
Phase 7	SAVE	写入 knowledge-graph.json、生成指纹基线、写 meta.json、清理中间产物（保留 scan-result.json 以加速后续增量）

决策表明确了“全量 vs 增量”的判定：--full 强制全量；无既有图谱则全量；已有图谱且 commit 未变则提示用户选择重建/审阅/跳过；已有图谱且有文件变更则走增量路径（通过 git diff <lastCommitHash>..HEAD --name-only 获取变更文件清单）。

增量更新与自动保鲜

“后续运行默认只分析变更文件”不是口号，而是有明确实现的机制。从 fingerprint.ts 看，每个文件的指纹由 SHA-256 内容哈希加结构指纹组成——函数签名（名称、参数、返回类型、导出状态、行数）、类结构（方法、属性）、imports 与 exports；变更被分级为 NONE / COSMETIC（纯外观改动）/ STRUCTURAL（结构变化），只有结构性变化才会触发对应节点重新分析。

自动更新则由 hooks 配置 驱动：SessionStart 钩子在会话启动时比对 meta.json 中记录的 commit 与当前 HEAD，不一致时提示智能体读取自动更新指令并执行增量更新；PostToolUse 钩子（匹配 Bash 工具调用）负责 commit 后的增量刷新。/understand --auto-update 只是把 {"autoUpdate": true} 写入 .ua/config.json 来开启这套机制。

知识图谱的数据格式

图谱最终是一个 JSON（knowledge-graph.json），其模式在 SKILL.md 的参考节 中有完整定义，理解它对定制面板或二次开发很有帮助。

节点类型（13 种），各自有固定的 ID 约定：

类型	含义	ID 约定
file	源代码文件	file:<相对路径>
function	函数或方法	function:<相对路径>:<名称>
class	类、接口或类型	class:<相对路径>:<名称>
module	逻辑模块或包	module:<名称>
concept	抽象概念或模式	concept:<名称>
config	配置文件（YAML/JSON/TOML/env）	config:<相对路径>
document	文档文件（Markdown/RST/TXT）	document:<相对路径>
service	可部署服务定义（Dockerfile、K8s）	service:<相对路径>
table	数据表或迁移	table:<相对路径>:<表名>
endpoint	API 端点或路由	endpoint:<相对路径>:<端点名>
pipeline	CI/CD 流水线配置	pipeline:<相对路径>
schema	Schema 定义（GraphQL/Protobuf/Prisma）	schema:<相对路径>
resource	基础设施资源（Terraform 等）	resource:<相对路径>

边类型（26 种） 按语义分七大类：结构类（imports、exports、contains、inherits、implements）、行为类（calls、subscribes、publishes、middleware）、数据流类（reads_from、writes_to、transforms、validates）、依赖类（depends_on、tested_by、configures）、语义类（related、similar_to）、基础设施类（deploys、serves、provisions、triggers）、Schema/数据类（migrates、documents、routes、defines_schema）。

边权重约定（面板中可用作视觉强度）：contains 1.0；inherits/implements 0.9；calls/exports/defines_schema 0.8；imports/deploys/migrates 0.7；depends_on/configures/triggers 0.6；tested_by/documents/provisions/serves/routes 0.5；其余默认 0.5。

顶层结构还包含 project（名称、语言、框架、描述、分析时间戳、commit 哈希）、layers（架构层，每个节点必须且只能归属一个层）与 tour（导览步骤，含 order、title、description、nodeIds，可选 languageLesson 字段）。

参与贡献与项目信息

项目的贡献流程（继承原文档）：

1. Fork 仓库
2. 创建特性分支（git checkout -b feature/my-feature）
3. 运行测试（pnpm --filter @understand-anything/core test）
4. 提交变更并发起 Pull Request

大型改动请先开 issue 讨论方案。项目采用 MIT 许可证，由 Egonex 开源，最初由 Lum1104 创建；社区生态还包括官方站点上的可交互 Demo（浏览器内可直接缩放、搜索、导航的面板）。仓库内另有 benchmark 文档与样例、设计规格与实施计划 以及 homepage 站点源码，可供希望深入定制面板或分析流水线的读者继续研读。

核心参考路径：俄语版 README（本文依据） · 英文 README · /understand 技能定义 · install.sh · 指纹与增量机制 · hooks 配置 · viewer 包