Understand Anything 多智能体知识图谱管线：从代码扫描到可交互 Dashboard 的实现解析

【免费下载链接】Understand-Anything Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more. 项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything

本文以 Understand Anything 的官方文档为主线，系统拆解它如何用一条「Tree-sitter 静态分析 + LLM 语义理解」的多智能体管线，把任意代码库 / 知识库 / 文档转换成可探索、可检索、可问答的知识图谱，并落到一个可交互的 Web Dashboard。读完你应能掌握：如何安装并在 Claude Code / Codex / Cursor / Copilot / Gemini CLI 等平台调用它、各斜杠命令与 --language / --auto-update 等参数如何工作、图谱产物 .ua/ 的目录约定与团队共享方式，以及底层指纹去重、批量并行、post-commit 增量更新等关键机制的实现原理。

1. 定位：把「读不懂的代码」变成「看得懂的图」

文档开篇提出了一个几乎所有工程师都遇到过的场景：

你刚加入一个新团队，代码库有 20 万行。你该从哪里开始？

Understand Anything 的回答是：别盲目逐行读代码，先用图谱看清全局。它作为一个 Claude Code Plugin，通过一条多智能体（multi-agent）管线分析项目，为每一个文件、函数、类、依赖构建知识图谱，再把这些数据渲染成一个可交互的 Dashboard 供你视觉化探索。

它有一句贯穿始终的设计宣言，也值得直接引用，因为它定义了「什么是好的代码图谱」：

目标不是做一个用复杂程度来「惊艳」你的图谱，而是做一个能安静地教你理解每个部件如何拼合的图谱。

这句话决定了后文所有实现取舍：结构层用确定性算法保证可复现，语义层才交给 LLM。文档同时明确了它支持 Claude Code、Codex、Cursor、Copilot、Gemini CLI 等多个平台（详见 多平台安装）。

2. 核心功能：图谱能做什么

文档将能力划分为三类主视图 + 六项增强能力。理解这些功能，有助于你判断它适合哪类工作流。

2.1 三大主视图

• 结构图谱探索：把代码库当作一张可交互的知识图谱来导航——每个文件、函数、类都是可点击、可搜索、可展开的节点。选中任意节点，可以看到它的白话（plain-English）摘要、关系，以及导览式讲解。
• 业务逻辑理解（领域视图）：切换到领域视图后，能看到代码如何映射到真实的业务流程——领域（domain）、流程（flow）、步骤（step）被排布成一张横向图。
• 知识库分析：/understand-knowledge 指向一个 Karpathy 模式的 LLM 维基，会生成一张带社区聚类（community clustering）的力导向知识图谱。其工作方式分两步：先由确定性解析器从 index.md 里抽取 wiki 链接与分类，再由 LLM 智能体发现隐含关系、抽取实体、提炼主张（claims），最终把维基变成一张可导航的互联想法图谱。

2.2 六项增强能力

文档以表格形式列出了六项增强，它们分别对应源码中不同的生成器与组件：

能力	说明	对应源码落点
导览（Guided Tours）	按依赖顺序自动生成的架构走读，让你「以正确的顺序」学习代码库	tour-generator.ts
模糊 + 语义检索	按名称或按含义查找；问一句「哪些部分处理认证」即可在整图上命中相关结果	search.ts、embedding-search.ts
Diff 影响分析	在提交前看清改动会波及系统的哪些部分	diff-analyzer.ts
角色自适应 UI	根据你是谁（初级开发 / PM / 高级用户）自动调整详略	PersonaSelector.tsx
分层可视化	按架构层（API / Service / Data / UI / Utility）自动分组，带颜色图例	layer-detector.ts
语言概念讲解	12 种编程范式（泛型、闭包、装饰器等）在出现处就地解释	language-lesson.ts

2.3 本地模型与隐私

文档特别提醒：出于隐私或企业环境考虑，可以把平台指向本地模型提供商（例如 Ollama），按其集成指南切换模型源即可。这一点在 快速启动 的 Token 用量说明里会被再次强调。

3. 多平台安装

Understand Anything 的核心资产是 understand-anything-plugin/ 目录下的 skills 与 agents。不同平台对「插件 / 技能」的发现机制不同，因此安装方式也分几类。

3.1 Claude Code（原生）

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

这是文档标注为「Native」的平台，走插件市场（plugin marketplace）机制。

3.2 一行式安装（install.sh）

对 Codex / OpenCode / OpenClaw / Antigravity / Gemini CLI / Pi Agent / Vibe CLI / VS Code Copilot / Hermes / Cline / KIMI CLI / Trae / Nanobot / Kiro 等平台，提供 install.sh（macOS/Linux）与 install.ps1（Windows）：

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

安装器做了什么？ 从 install.sh 的源码看，它做了两件核心事：把仓库克隆到 ~/.understand-anything/repo，然后为选中的平台创建符号链接。脚本内部的 platforms_table() 把每个平台映射到一个「技能目标目录 + 链接风格」：

# install.sh 中定义的“平台 → 目标目录 → 风格”映射（节选）
gemini|$HOME/.agents/skills|per-skill
codex|$HOME/.agents/skills|per-skill
vscode|$HOME/.copilot/skills|per-skill
kiro|$HOME/.kiro/skills|per-skill

这里 per-skill 表示「为每个技能建一条符号链接」，folder 表示「把整个 skills 目录作为 understand-anything 建一条链接」。脚本还内置了两个环境变量 UA_REPO_URL（覆盖克隆地址）与 UA_DIR（覆盖克隆目标，默认 $HOME/.understand-anything/repo），便于企业环境走私有镜像。

技能调用前缀因平台而异：大多数平台用斜杠命令（/understand），但 Codex 用 $——输入的是 $understand 而非 /understand。若两者都不被识别，直接用自然语言请求「用 understand 技能分析这个项目」即可。

安装后记得重启 CLI / IDE。常用维护命令：

• 支持的平台取值：gemini、codex、opencode、pi、openclaw、antigravity、vibe、vscode、hermes、cline、kimi、trae、nanobot、kiro
• 后续更新：./install.sh --update（Windows：install.ps1 -Update）
• 卸载：./install.sh --uninstall <platform>（Windows：install.ps1 -Uninstall <platform>）

3.3 自动发现型平台

• Cursor：克隆本仓库后，Cursor 通过 .cursor-plugin/plugin.json 自动发现插件，无需手动安装——克隆后直接用 Cursor 打开即可。若未被自动发现，可在 Cursor Settings → Plugins 里粘贴仓库地址手动添加。
• VS Code + GitHub Copilot（v1.108+）：通过 .copilot-plugin/plugin.json 自动发现，同样克隆即开。若想作为跨项目个人技能，可用上面的 install.sh 以 vscode 平台安装。

3.4 Copilot CLI 与 Kiro

# 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"；IDE 端则把技能符号链接进 ~/.kiro/skills/，并把 understand agent 写入 ~/.kiro/agents/understand.json，重启 IDE 后两者都可用。

3.5 平台兼容矩阵

综合 install.sh 的平台表与文档的说明，各平台状态如下（✅ 表示文档确认支持）：

平台	状态	安装方式
Claude Code	✅ 原生	插件市场
Cursor	✅ 支持	自动发现（.cursor-plugin）
VS Code + GitHub Copilot	✅ 支持	自动发现（.copilot-plugin）
Copilot CLI	✅ 支持	插件安装
Codex / OpenCode / Pi / Vibe / Gemini CLI / OpenClaw / Antigravity / Hermes / Cline / KIMI CLI / Trae / Nanobot / Kiro	✅ 支持	install.sh <platform>

4. 快速启动

4.1 安装插件（Claude Code 为例）

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

4.2 分析代码库

/understand

多智能体管线会扫描项目、抽取所有文件 / 函数 / 类 / 依赖，然后把知识图谱写进 .ua/knowledge-graph.json。

目录约定与向后兼容：文档与 SKILL.md 都明确了数据目录的解析逻辑——若项目里已存在 .understand-anything/，则继续沿用它；否则用新的 .ua/。这意味着存量项目无需迁移。源码里这一约定对应：

UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)"

Token 用量提醒：首次 /understand 会分析整个代码库，在大项目上可能消耗可观的 Token。文档建议用 Token 套餐 / 订阅来跑，或初始化时改用本地模型（见 2.3）。之后的运行默认是增量的——只重新分析发生变化的文件，因此 Token 消耗会低得多。这一增量机制的实现见 指纹与变更检测。

4.3 本地化输出（--language）

# 以中文生成内容（知识图节点描述和 Dashboard UI）
/understand --language zh

# 支持语言：en（默认）、zh、zh-TW、ja、ko、ru

--language 会影响三处内容：

• 知识图谱中节点的摘要与描述
• Dashboard UI 的标签、按钮、提示
• 导览（Guided Tour）的讲解

从 SKILL.md 的参数定义看，--language 实际接受 ISO 639-1 代码（zh、ja、ko、en、es、fr、de 等）或友好名称（chinese、japanese、korean 等），还支持 zh-TW、zh-HK 等地域变体，偏好会写入 $UA_DIR/config.json 以便后续增量更新保持一致。仓库中 skills/understand/locales/ 下预置了 en / zh / zh-TW / ja / ko / ru 六种本地化文案，与文档标注的支持语言一致。

4.4 探索 Dashboard

/understand-dashboard

会打开一个交互式 Web Dashboard，把代码库以图谱形式可视化——按架构层着色、可搜索、可点击。选中任意节点，可看到其代码、关系与白话解释。Dashboard 前端位于 packages/dashboard，是一个 Vite + React 工程（见其 package.json 的 dev / build / test 脚本）。

4.5 进一步深挖（更多斜杠命令）

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

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

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

# 为新成员生成 onboarding 指南
/understand-onboard

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

# 分析一个 Karpathy 模式的 LLM 维基知识库
/understand-knowledge ~/path/to/wiki

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

# 通过 post-commit 钩子在每次提交时自动增量更新
/understand --auto-update

# 限定到某个子目录（针对超大 monorepo）
/understand src/frontend

这些命令各自对应 understand-anything-plugin/skills/ 下的独立技能目录（understand-chat/、understand-diff/、understand-explain/、understand-onboard/、understand-domain/、understand-knowledge/、understand-dashboard/）。/understand 完整参数集在 SKILL.md 中还额外支持 --full（强制全量重建）、--no-auto-update、--review（用完整 LLM 审查代替内联确定性校验）、--exclude <patterns>（追加排除的 glob，优先级最高，支持 gitignore 的 ! 否定语法）。

5. 团队共享图谱

文档强调一个务实观点：图谱本质只是一个 JSON 文件——只需提交一次，团队成员就能跳过整条管线。这适合 onboarding、PR 评审和 docs-as-code 工作流。

应该提交什么？ .ua/ 里的所有文件，但排除 intermediate/ 与 diff-overlay.json（它们是本地临时产物）。存量项目用 .understand-anything/，把下面的目录名替换即可。.gitignore 建议：

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

保持新鲜：开启 /understand --auto-update，由 post-commit 钩子对图谱做增量修补，让每个提交都带着与之匹配的图谱；或者在发布前手动重跑一次 /understand。

auto-update 是怎么触发的？ 从 post-tool-use-auto-update.mjs 看，它是一个 Claude 的 PostToolUse 钩子：用正则 git\s+(commit|merge|cherry-pick|rebase) 识别提交类命令，读取 ${UA_DIR}/config.json 里的 autoUpdate 开关，命中时向会话注入一条「必须执行增量更新指令」的上下文，从而驱动图谱同步更新。

大图（10 MB 以上）：用 git-lfs 跟踪。

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

5.1 没有 Claude Code 也能看 Dashboard

一旦图谱已生成并提交，团队里任何人都能用一条命令打开它——不需要 Claude Code、不需要 LLM、不需要 API Key，只要有 Node.js（>= 18）：

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=…），并在浏览器中打开完整的交互式 Dashboard。项目目录（默认当前目录）需包含已提交的数据目录（.ua/，或存量项目的 .understand-anything/）。一切内容都是从本地磁盘只读提供，没有任何 LLM 调用，数据不会离开你的机器。

从 packages/viewer/package.json 看，这个独立查看器是一个名为 understand-anything-viewer 的包，bin 指向 bin/viewer.mjs，engines.node 声明为 >=18，与文档描述完全一致。

在克隆仓库里开发时：执行 pnpm install && pnpm --filter @understand-anything/core build，再 GRAPH_DIR=/path/to/analyzed/project pnpm dev:dashboard，即可通过 Vite 开发服务器得到同样的效果（dev:dashboard 定义在根目录 package.json 的 scripts 中）。

6. 工作原理

6.1 Tree-sitter + LLM 混合架构

文档把核心分工概括为一句话：能用确定性算法处理的事交给静态分析，需要语义理解的事才交给 LLM。

• Tree-sitter（确定性）：把源码解析成具体语法树（CST），抽取结构性事实——import、export、函数 / 类定义、调用点、继承。在扫描阶段被预先解析成 importMap 传给 file-analyzer，因此各分析器无需再从源码里重新推导 import。同样的输入永远得到同样的输出，并且是增量更新中「指纹」机制的基石。
• LLM（语义）：把解析出的结构与原始源码一起读，生成解析器给不了的东西——白话摘要、标签、架构层归属、业务领域映射、导览、语言概念注解。

文档点明，正是这种分工让图谱在结构侧可复现（同代码必产生同边的图），在语义侧仍能捕捉意图（一个文件是「为了什么」存在，而不仅是「导入了什么」）。

源码佐证：tree-sitter-plugin.ts 是一个「配置驱动」的插件，TreeSitterPlugin 通过 LanguageConfig 决定支持哪些语言、如何加载其 WASM 语法。注释明确列出当前带抽取器（extractor）的语言：TypeScript、JavaScript、Python、Go、Rust、Java、Ruby、PHP、C/C++、C#、Dart、Kotlin、Swift、Scala；没有 tree-sitter 配置的语言会被优雅跳过，改由 LLM 智能体兜底。这与仓库里 packages/core/src/plugins/extractors/ 目录下逐个语言的抽取器一一对应（如 python-extractor.ts、go-extractor.ts、rust-extractor.ts 等），而 packages/core/src/languages/configs/ 下则是覆盖 TS / Go / Java / Python / SQL / Terraform / Dockerfile / K8s / OpenAPI / Protobuf 等 40 余种文件类型的语言配置。

6.2 指纹驱动的增量更新

「只重析变更文件」这句看似简单的话，背后是一套结构指纹比对机制。fingerprint.ts 定义了关键类型：

• FileFingerprint：包含 contentHash（SHA-256）、函数 / 类 / import / export 的结构摘要、总行数等；
• FingerprintStore：带 version、gitCommitHash、generatedAt 与每文件指纹的持久化结构；
• ChangeLevel 被细分为 NONE / COSMETIC / STRUCTURAL。

从源码结构看，系统会区分「仅外观变化」（如注释、空行）与「结构性变化」（函数 / 类 / import 签名改变），只有结构性变化才会触发该文件的重新分析。这正是文档所说「首次分析贵、之后增量便宜」的底层原因，也解释了为什么指纹建立在确定性 Tree-sitter 输出之上——确定性是「同输入同指纹」的前提。

6.3 多智能体管线

/understand 命令编排 5 个专业智能体，/understand-domain 加入第 6 个，/understand-knowledge 加入第 7 个。文档给出的智能体分工如下（每个智能体在 understand-anything-plugin/agents/ 下都有对应的定义文件）：

智能体	角色	使用方
project-scanner	发现文件、检测语言与框架	/understand
file-analyzer	抽取函数、类、import；生成图谱节点与边	/understand
architecture-analyzer	识别架构层	/understand
tour-builder	生成导览式学习路径	/understand
graph-reviewer	校验图谱完整性与引用一致性（默认内联运行；--review 时用完整 LLM 审查）	/understand
domain-analyzer	抽取业务领域、流程、步骤	/understand-domain
article-analyzer	从维基文章中抽取实体、主张、隐含关系	/understand-knowledge

这些定义文件可直接查看，例如 file-analyzer.md 描述其为「两阶段」：先用结构抽取脚本，再做 LLM 语义分析——与 6.1 的混合架构相呼应。domain-analyzer.md 则说明它会产出 domain-graph.json，把业务逻辑如何流经代码映射出来。

并行与增量：文档说明文件分析器并行执行——最多 5 个并发 worker，每批 20–30 个文件，并支持增量更新。批量逻辑落在 compute-batches.mjs 中；SKILL.md 进一步描述了它在每个阶段切换与每批处理时向用户打印进度（[Phase N/7] …、Analyzing batch X/N），以应对大代码库的长耗时。

7. 产物与目录约定小结

把散落各处的约定集中起来，便于你排查与协作：

• 数据目录：.ua/（新）或 .understand-anything/（存量），二者择一、自动探测。
• 核心产物：knowledge-graph.json（驱动 Dashboard）；/understand-domain 另有 domain-graph.json。
• 临时产物（勿提交）：intermediate/、diff-overlay.json。
• 配置：config.json 保存 autoUpdate 开关与 --language 偏好。
• 提交建议：提交 .ua/ 全部（除临时项），大图走 git-lfs。
• 只读查看：understand-anything-viewer（Node >= 18），无 LLM、无 API Key。

8. 贡献与测试

文档欢迎贡献，标准流程为：Fork 仓库 → 建特性分支（git checkout -b feature/my-feature）→ 跑测试 → 提交并开 PR。运行测试的命令是：

pnpm --filter @understand-anything/core test

这与仓库根 package.json 的 workspace 配置一致：core 包用 tsc 构建、vitest 测试，根目录的 prepare 脚本会在安装时自动构建 @understand-anything/core。对于较大改动，文档建议在动手前先开一个 Issue 讨论方案。测试代码分布在 understand-anything-plugin/packages/core/src/__tests__/ 以及根 tests/ 目录（覆盖 benchmark、install 平台一致性、scan / merge / freshness 等）。

---

小结：Understand Anything 的技术内核是「确定性 + 语义」的双轨管线——Tree-sitter 保证结构与增量的可复现性，多智能体 LLM 管线负责把结构翻译成「教人理解」的语义层，最后落到一个既能在 Claude Code 里交互、也能用独立 viewer 离线只读查看的知识图谱 Dashboard。理解了 .ua/ 目录约定、--language / --auto-update / --review 等参数、以及指纹驱动的增量机制，你就能把它稳定地嵌入自己的 onboarding、PR 评审与 docs-as-code 工作流。

【免费下载链接】Understand-Anything Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more. 项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything