Understand Anything 实战：把任意代码库变成可探索、可检索的知识图谱

Understand Anything 是一个面向 AI 编码代理（Claude Code、Codex、Cursor、Copilot、Gemini CLI 等）的开源插件，它通过"Tree-sitter 静态分析 + LLM 语义理解"的多智能体流水线，把代码库中每个文件、函数、类与依赖关系构建成知识图谱，并生成可交互的可视化 Dashboard。读完本文，你将掌握它的完整安装方式（覆盖 15+ 平台）、全部分析命令与参数、团队协作下的图谱共享方案，以及从扫描到保存的 7 阶段流水线与增量更新机制的源码级原理。

一、它解决什么问题，以及产品形态

README 开宗明义地描述了这个项目的动机场景：你刚加入一个新团队，代码库有 20 万行代码，从哪里看起？（见 README.md）。Understand Anything 的定位是"教你理解代码的图谱，而不是炫技的图谱"——它不展示代码有多复杂，而是安静地告诉你每一部分如何拼接在一起。

从仓库结构看，产品由三部分组成：

• 插件本体 understand-anything-plugin/：包含 9 个技能（skills/）、10 个代理定义（agents/）、自动更新钩子（hooks/）以及 pnpm workspace 子包；
• 核心分析库 @understand-anything/core（understand-anything-plugin/packages/core/）：提供 Tree-sitter 解析插件、图 Schema、指纹变更检测、嵌入检索等确定性能力；
• 可视化前端：Dashboard 应用（packages/dashboard/）与一个独立查看器（packages/viewer/，包名 understand-anything-viewer，见 viewer/README.md），后者可以脱离任何 LLM 环境直接打开已生成的图谱。

核心功能一览

功能	说明
结构图谱（Structural Graph）	每个文件、函数、类都是可点击、可搜索的节点；选中节点可见白话摘要、关系与引导式导览
业务域视图（Domain View）	切换域视图后，代码映射为真实业务流程——领域、流程、步骤以水平图谱呈现
知识库分析（/understand-knowledge）	指向 Karpathy 模式的 LLM wiki，先由确定性解析器从 index.md 提取 wikilinks 与分类，再由 LLM 代理发现隐含关系、抽取实体与论断，生成带社区聚类的力导向知识图谱
引导式导览（Guided Tours）	按依赖顺序自动生成的架构走查路径
模糊 + 语义搜索	按名称或按含义搜索，例如"哪些部分处理鉴权？"
Diff 影响分析	提交前查看变更会波及系统的哪些部分
分层可视化	自动按架构层（API / Service / Data / UI / Utility）分组，配彩色图例
语言概念讲解	在出现位置上下文解释 12 种编程模式（泛型、闭包、装饰器等）
人格自适应 UI	Dashboard 根据你是初级开发、PM 还是资深用户调整信息详略

---

二、快速开始：四步跑通完整流程

1. 安装插件（Claude Code 原生方式）

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

使用本地模型？ 出于隐私或企业环境考虑，可把平台指向本地模型提供方（如 Ollama），按对应集成指南切换模型提供方即可。

2. 分析代码库

/understand

该命令触发一条多智能体流水线：扫描项目、抽取每个文件/函数/类/依赖，最终把知识图谱保存到 .ua/knowledge-graph.json。注意数据目录的兼容规则：如果项目里已存在旧版 .understand-anything/ 目录，则继续沿用该目录，无需任何迁移。

Token 用量提示：首次 /understand 会全量分析整个代码库，大型项目会消耗可观的 token，建议在订阅/token 计划下运行，或使用本地模型做首次初始化。之后的运行默认是增量的——只重新分析变更文件，token 消耗大幅下降。

3. 打开 Dashboard

/understand-dashboard

一个交互式 Web Dashboard 会打开：代码库以图谱形式呈现，按架构层着色，可搜索、可点击。选中任意节点可看到其代码、关系和一段白话解释。

4. 日常使用的全套命令

# 询问关于代码库的任何问题
/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 hook 在每次提交后自动更新
/understand --auto-update

# 限定子目录分析（适合超大 monorepo）
/understand src/frontend

--language：本地化输出

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

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

README 说明 --language 参数影响三处：知识图中节点的摘要与描述、Dashboard 的 UI 标签/按钮/提示、引导导览的讲解文案。

从技能实现看，语言逻辑远比"选一个语言"精细（见 skills/understand/SKILL.md 第 3.6 节）：

• 首次运行且未传 --language 时，流水线会检测你对话使用的语言；若不是英语，会先请求确认（或输入其他语言覆盖）再生成；英语对话则静默跳过；
• 解析结果（含 en）持久化到 .ua/config.json 的 outputLanguage 字段，之后每次运行复用，不会重复询问；
• --language 接受 ISO 639-1 代码（zh、ja、ko、es、fr 等）或友好名称（chinese、japanese 等），并支持 zh-TW、zh-HK 等区域变体；
• 流水线内部会注入一条"语言指令模板"（Language directive），要求所有文本内容（summaries、descriptions、tags、titles、languageNotes、languageLesson）用目标语言以母语级自然表达生成，且没有标准译法的技术术语保留英文（如 "middleware"、"hook"、"barrel"）。

---

三、多平台安装

Understand Anything 支持多种 AI 编码平台，README 给出的平台兼容性如下（当前插件版本为 2.9.4，见 .claude-plugin/plugin.json）：

平台	状态	安装方式
Claude Code	原生	插件市场
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
Trae	支持	install.sh trae
Nanobot	支持	install.sh nanobot
Kiro CLI / IDE	支持	install.sh kiro

一行式安装（install.sh / install.ps1）

仓库根目录提供 install.sh（macOS / Linux）与 install.ps1（Windows PowerShell），README 给出了 curl 管道安装的一条命令形式；直接运行脚本同样可行：

# 交互式选择平台，或显式指定：
./install.sh codex

阅读 install.sh 源码可以确认安装器的具体行为：

• 仓库被克隆/更新到 ~/.understand-anything/repo（可用环境变量 UA_DIR 覆盖目标、UA_REPO_URL 覆盖克隆地址），已是 git 仓库时执行 git pull --ff-only；
• 按"平台表"（脚本内 platforms_table）为每个平台建立符号链接，风格分两种：per-skill（逐个技能软链到目标 skills 目录，如 ~/.agents/skills）与 folder（整个 skills/ 目录以 understand-anything 为名软链，如 ~/.openclaw/skills）；
• 额外创建通用插件根链接 ~/.understand-anything-plugin → 仓库内 understand-anything-plugin，供技能运行时解析插件根目录；
• Kiro 平台会额外把 10 个代理定义动态拼装成 ~/.kiro/agents/understand.json；
• 维护命令：./install.sh --update（拉取最新，技能经软链自动生效）、./install.sh --uninstall <platform>（Windows 对应 install.ps1 -Update / -Uninstall）。

平台表与 README 的取值列表由测试 tests/install/platform-table-consistency.test.mjs 保持一致性约束。

技能调用前缀差异：多数平台用斜杠命令（/understand），但 Codex 用 $ —— 输入 $understand 而不是 /understand。若你的平台两个前缀都不识别，用自然语言表达即可："Use the understand skill to analyze this project."

Cursor / VS Code：自动发现

• Cursor 在克隆本仓库时通过 .cursor-plugin/plugin.json 自动发现插件，无需手动安装；自动发现失败时，可打开 Cursor Settings → Plugins 手动添加仓库；
• VS Code + GitHub Copilot（v1.108+）通过 .copilot-plugin/plugin.json 自动发现；两个 plugin.json 均把 skills 与 agents 字段指向 understand-anything-plugin/ 下对应目录；
• 想让技能在所有项目中可用（个人级技能），用 install.sh vscode 安装即可。

Copilot CLI 与 Kiro

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

Kiro 通过 ./install.sh kiro 安装后：

• Kiro CLI：kiro-cli chat --agent understand "Analyze this project"；
• Kiro IDE：技能被软链进 ~/.kiro/skills/，understand 代理写入 ~/.kiro/agents/understand.json，重启 IDE 后两者均可用。

---

四、与团队共享图谱：提交 JSON 即完成交接

图谱本质就是一份 JSON——提交一次，队友就可以跳过整条分析流水线。这对新人 onboarding、PR 评审和 docs-as-code 场景非常合适。

提交什么

提交 .ua/ 目录中的所有内容，除本地临时产物 intermediate/ 与 diff-overlay.json 之外：

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

旧项目若仍使用 .understand-anything/ 目录，则替换为旧目录名。

保持图谱新鲜

启用 /understand --auto-update：它会把 autoUpdate: true 写入 $UA_DIR/config.json。该开关背后的机制可以在源码中完整看到（hooks/hooks.json）：

• SessionStart 钩子（第 14–24 行）：每次会话启动时，若 config.json 里 autoUpdate 为 true，且 meta.json 记录的 gitCommitHash 与当前 HEAD 不一致，就向代理注入一条强制指令，要求其读取 auto-update-prompt.md 并执行图谱更新——无需用户确认；
• PostToolUse 钩子（匹配 Bash 工具）：执行 post-tool-use-auto-update.mjs，在提交后自动增量修补图谱，配套测试见 tests/hooks/post-tool-use-auto-update.test.mjs。

超大图谱（10 MB+）用 git-lfs

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

无 Claude Code、无 LLM 地查看 Dashboard

图谱生成并提交后，任何团队成员只需一条 npx 命令即可打开完整交互式 Dashboard（完整命令见 README"Share the Graph with Your Team"小节）——不需要 Claude Code、不需要 LLM、不需要 API key，仅要求 Node.js ≥ 18。终端会打印一个带 token 的 URL（形如 http://127.0.0.1:5173/?token=…）并在浏览器中打开；项目目录（默认当前目录）中必须存在提交的数据目录（.ua/ 或旧版 .understand-anything/）。所有内容只读地服务自本地磁盘——没有 LLM 调用，数据不出机器。

如果你直接基于克隆开发，也可以走 Vite 开发服务器：pnpm install && pnpm --filter @understand-anything/core build，然后 GRAPH_DIR=/path/to/analyzed/project pnpm dev:dashboard，效果等价。

---

五、底层原理：Tree-sitter + LLM 混合分析

README 的 "Under the Hood" 一节解释了图谱为什么"结构上可复现、语义上有理解"。核心是职责分工：

• Tree-sitter（确定性侧）：把源码解析为具体语法树，抽取结构化事实——imports、exports、函数/类定义、调用点、继承关系。这些在扫描阶段被预解析成 importMap 并直接传给文件分析器，避免各分析器重复从源码推导 import。相同输入 → 相同输出，每次运行都成立。它同时支撑基于指纹的变更检测，实现增量更新。对应实现见 tree-sitter-plugin.ts 与 scan-project.mjs、extract-import-map.mjs。
• LLM（语义侧）：把解析出的结构连同原始源码一起阅读，产出解析器做不到的东西——白话摘要、标签、架构层归属、业务域映射、引导导览、语言概念讲解。

这个切分使得图谱在结构边（imports/calls 等）上可复现——同一段代码永远得到同样的边——同时仍能捕获"意图"（一个文件是为了什么，而不只是它 import 了什么）。

多智能体流水线

/understand 编排 5 个专职代理，/understand-domain 增加第 6 个，/understand-knowledge 增加第 7 个：

代理	职责	服务于
project-scanner	发现文件，检测语言与框架	/understand
file-analyzer	抽取函数、类、import；产出图的节点与边	/understand
architecture-analyzer	识别架构层	/understand
tour-builder	生成引导式学习导览	/understand
graph-reviewer	校验图的完整性与引用一致性；默认走内联确定性校验，--review 触发完整 LLM 审查	/understand
domain-analyzer	抽取业务域、流程与步骤	/understand-domain
article-analyzer	从 wiki 文章中抽取实体、论断与隐含关系	/understand-knowledge

文件分析器并行运行，最多 5 个并发工作进程，每批 20–30 个文件。所有代理定义位于 understand-anything-plugin/agents/（目录下另有 design-analyzer 与 knowledge-graph-guide 两个代理定义，从目录结构看分别服务于 Figma 分析与知识图谱引导场景）。

七阶段流水线（来自 SKILL.md 的完整实现）

skills/understand/SKILL.md 把 /understand 展开为 7 个阶段，这也是理解增量机制的关键：

1. Phase 0 预检：解析参数（--full / --auto-update / --no-auto-update / --review / --language / --exclude / 目录路径）；检测 git worktree 并把输出重定向回主仓库根（防止临时 worktree 销毁数据目录）；解析插件根并确保 @understand-anything/core 已构建（要求 Node.js ≥ 22 与 pnpm ≥ 10）；解析数据目录 $UA_DIR（.ua/，存在旧目录则沿用）；根据现有图谱与提交哈希决定"全量 / 增量 / 审查-only / 已是最新"。
2. Phase 0.5 忽略配置：首次运行时调用 generate-ignore.mjs 生成 .understandignore 起点文件（读取 .gitignore、去重内置默认项、按语言分组给出测试文件排除建议），等待用户确认后继续。
3. Phase 1 扫描：派发 project-scanner，产出 scan-result.json——项目名/描述、语言、框架、带 fileCategory（code / config / docs / infra / data / script / markup）的文件清单、复杂度估计，以及预解析的 importMap（非代码文件为空数组）。超过 100 个文件时会提示用户考虑用子目录限定范围。
4. Phase 1.5 分批：compute-batches.mjs 把文件组织成语义批次并写入 batches.json；每个批次携带 batchImportData（本批 import 数据）与 neighborMap（跨批邻居及其导出符号，用于提升跨批边置信度）。
5. Phase 2 分析：按批次派发 file-analyzer（最多 5 并发），输出 batch-<i>.json（大输出可拆分 batch-<i>-part-<k>.json）；随后 merge-batch-graphs.py 一次性完成：合并节点/边、规范化节点 ID 与复杂度值、按 (source, target, type) 去重、丢弃悬空边，并运行 tested_by 链接器把测试覆盖边统一为"生产节点 → 测试节点"方向。
6. Phase 3–5 组装审查 / 架构 / 导览：assemble-reviewer 复核合并产物；architecture-analyzer 结合语言上下文（languages/*.md）、框架附录（frameworks/*.md）与区域指南（locales/*.md）产出 layers.json，主会话再做五步归一化（解包信封、字段改名、合成缺失 ID、路径转前缀 ID、丢弃悬空引用）；tour-builder 产出 tour.json 并同样归一化。
7. Phase 6 校验：默认执行内联确定性校验脚本（检查节点必填字段、ID 唯一性、边两端存在、每层/每步引用有效、文件节点必须归属某层等）；--review 则派发 LLM graph-reviewer 做完整审查，并与 Phase 1 的扫描清单交叉核对"每个文件是否都有对应节点"。
8. Phase 7 保存：写 knowledge-graph.json → 生成结构指纹基线（必须成功才允许写 meta.json，否则自动更新会误判所有文件为 STRUCTURAL 而每次提交都触发全量重建）→ 写 meta.json（含 lastAnalyzedAt、gitCommitHash、version、analyzedFiles）→ 把中间产物移入 .trash-* 延迟清理（保留 scan-result.json 供下次增量运行直接跳过扫描）。

增量更新的指纹机制

README 宣称"后续运行默认增量，只重分析变更文件"。其底层实现在 packages/core/src/fingerprint.ts：

• FileFingerprint 记录每个文件的 SHA-256 内容哈希、函数签名（名称/参数/返回类型/行数）、类签名（方法/属性）、import 与 export 列表；
• 变更被分为三级：NONE / COSMETIC（仅外观，如注释与空白）/ STRUCTURAL（结构变化）。只有 COSMETIC 与 STRUCTURAL 之外的语义判断决定是否需要 LLM 重分析——指纹只捕获"影响知识图谱的元素（函数/类/import/export 签名），不捕获实现细节"，因此纯实现改动不会触发昂贵的重新分析。

知识图谱 Schema

SKILL.md 参考节（SKILL.md 第 819 行起）定义了完整的数据模型：13 种节点类型与 26 种边类型。

节点类型（节选，ID 约定）：file（file:<相对路径>）、function（function:<路径>:<名>）、class（class:<路径>:<名>）、module、concept、config、document、service（Dockerfile/K8s）、table（数据库表/迁移）、endpoint（API 路由）、pipeline（CI/CD）、schema（GraphQL/Protobuf/Prisma）、resource（Terraform/CloudFormation）。

边类型按 8 类组织：

类别	类型
结构	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；其余默认 0.5。Schema 的权威定义与校验位于 packages/core/src/schema.ts。

---

六、开发、测试与贡献

仓库是 pnpm workspace（pnpm-workspace.yaml），核心贡献流程（见 README.md 与 CONTRIBUTING.md）：

# 运行核心测试
pnpm --filter @understand-anything/core test

测试覆盖了本文提到的关键机制，可作为阅读源码的入口：

• tests/install/platform-table-consistency.test.mjs：校验 install.sh 平台表与文档一致性；
• tests/hooks/post-tool-use-auto-update.test.mjs：post-commit 自动更新钩子；
• tests/skill/understand/test_scan_project.test.mjs 及同目录 fixtures/scan-result-*.json：扫描阶段对多 cliques、大社区、非代码文件等场景的行为；
• understand-anything-plugin/packages/core/src/__tests__/ 下的 fingerprint.test.ts、schema.test.ts、staleness.test.ts 等：指纹、Schema 与新鲜度逻辑。

---

七、小结

Understand Anything 的设计取舍可以概括为三点：

1. 确定性优先：结构事实（import、调用、继承）全部由 Tree-sitter 保证可复现，LLM 只负责"意图"，这让图谱可以作为团队资产被提交与共享；
2. 增量原生：指纹三级分类（NONE/COSMETIC/STRUCTURAL）+ git 提交哈希 + 自动更新钩子，让图谱能随代码库持续保鲜而不持续烧 token；
3. 平台无关分发：同一套 skills/ + agents/ 通过符号链接适配 15+ 平台，插件清单（.claude-plugin/、.cursor-plugin/、.copilot-plugin/）则让支持原生发现的平台零配置可用。

如果你正在接手一个陌生的大型代码库，最短路径就是：安装插件 → /understand → /understand-dashboard，然后用 /understand-chat 和 /understand-diff 把它变成日常工具。