Understand Anything 实战指南：用多智能体管线构建代码库交互式知识图谱，并跨平台落地

本文以 Understand Anything 的官方土耳其语 README（READMEs/README.tr-TR.md）及其对应的英文主文档（README.md）为主体，完整梳理该工具的核心功能、/understand 全链路命令参数、多平台安装方式和团队协作流程；并结合仓库内的 SKILL.md、install.sh 与 viewer 包 等源码，补全文档未展开的管线阶段、数据目录约定与图谱 Schema。读完本文，你可以把任意代码库转成可搜索、可提问、可 diff 影响分析的知识图谱，并让团队在无需 LLM 的环境下查看同一份图谱。

1. 项目定位：从"盲读代码"到"看懂全貌"

Understand Anything 是一个 Claude Code Plugin（同时适配 Codex、Cursor、Copilot、Gemini CLI 等平台），它用多智能体管线分析你的项目，为每个文件、函数、类和依赖构建知识图谱，并提供一个交互式仪表板来可视化地探索它们。官方用一句话点出了它的目标：

目标不是做一个"炫耀你的代码库有多复杂"的图谱，而是做一个"默默教会你每一块如何拼在一起"的图谱。

典型场景是：刚加入新团队，面对 20 万行代码不知道从哪读起——图谱 + 引导式 Tour 就是为这个场景设计的。土耳其语 README（READMEs/README.tr-TR.md）与英文主文档（README.md）内容一一对应，本篇以二者为准。

2. 核心功能集

README 将功能分为三个主视图 + 六个增强能力：

2.1 探索结构图谱（Structural Graph）

把代码库当作交互式知识图谱浏览——每个文件、函数、类都是一个可点击、可搜索的节点。选中任意节点可以看到：白话摘要（plain-English summary）、依赖关系、引导式 Tour 步骤。

2.2 理解业务逻辑（Domain View）

切换到领域视图后，代码与真实业务流程一一对应：领域（domains）、流程（flows）、步骤（steps）以横向图谱呈现。该视图由 /understand-domain 命令驱动，背后是 domain-analyzer 智能体。

2.3 分析知识库（Knowledge Base）

把 /understand-knowledge 指向一个 Karpathy 模式的 LLM Wiki，即可得到一个带社区聚类的力导向知识图谱。其工作方式分两步：确定性解析器先从 index.md 中提取 wikilink 和分类，再由 LLM 智能体发现隐含关系、抽取实体、浮出论断（claims），把 Wiki 变成可导航的相互关联的想法图谱。

2.4 六项增强能力

能力	说明
引导式 Tour	按依赖顺序自动生成的架构走读，教你"以正确的顺序学代码库"
模糊与语义搜索	按名字或按含义查找，例如搜索"哪些部分负责鉴权"，在整个图谱上得到相关结果
Diff 影响分析	提交前看清你的改动影响系统哪些部分，理解跨代码库的涟漪效应
角色自适应 UI	仪表板根据你是谁（初级开发、产品经理、高级用户）调整细节层级
分层可视化	按架构层自动分组——API、Service、Data、UI、Utility——并附颜色图例
语言概念讲解	12 种编程模式（泛型、闭包、装饰器等）在出现处附带上下文解释

3. 快速开始：四步上手

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

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

使用本地模型？ 出于隐私或企业部署考虑，可以把平台的模型提供方指向 Ollama 等本地模型服务（按各平台的集成文档切换模型提供方）。

3.2 第二步：分析代码库

/understand

多智能体管线会扫描项目、抽取每个文件/函数/类/依赖，然后生成知识图谱并保存到 .ua/knowledge-graph.json。

数据目录的兼容约定（源码级证据）：SKILL.md 明确写道，所有产物写入 $UA_DIR，其解析逻辑是：

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

即：如果项目里已存在旧的 .understand-anything/ 目录就继续沿用它，否则使用新的 .ua/。已迁移过的项目无需做任何数据搬迁。

Token 用量注意：首次 /understand 会分析整个代码库，在大型项目上会消耗可观的 token。官方建议在 token 套餐/订阅下运行初始化，或改用本地模型；后续运行默认是增量的——只重新分析发生变化的文件，token 消耗大幅下降。增量的判断依据见 SKILL.md 的决策表：通过 git diff <lastCommitHash>..HEAD --name-only 得到变更文件清单，若清单为空则直接报告"图谱已是最新"并停止。

本地化输出：用 --language 指定生成内容（节点描述与仪表板 UI）的语言：

# 在你偏好的语言中生成内容（节点描述与 dashboard UI）
/understand --language en

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

--language 参数影响三处：知识图谱中的节点摘要与描述、仪表板 UI 的标签/按钮/工具提示、引导式 Tour 的说明文字。从源码看，解析到的语言会写入 .ua/config.json 并在之后的每次增量运行中复用（SKILL.md 的 Phase 0 语言配置逻辑）；首跑未传 --language 时会探测你的会话语言，非英语会请求一次确认。

3.3 /understand 的完整参数清单

土耳其语 README 只展示了部分用法，而 SKILL.md 的 argument-hint 给出了完整签名：[path] [--full|--auto-update|--no-auto-update|--review|--language <lang>|--exclude <patterns>]。各参数含义：

参数	作用
--full	强制全量重建，忽略已有图谱
--auto-update	启用提交时自动更新图谱（向 config.json 写入 autoUpdate: true）
--no-auto-update	关闭自动更新
--review	运行完整的 LLM graph-reviewer，而非默认的确定性内联校验
--language <lang>	指定文本内容语言，接受 ISO 639-1 代码或友好名称，支持 zh-TW 等地域变体
--exclude <patterns>	逗号分隔的 glob 排除模式，优先级高于内置默认与 .understandignore 规则，支持 ! 取反
<dir>	分析指定目录而非当前目录（例如 /understand src/frontend）

一个实操细节：--exclude 新增的模式需要 --full 重新扫描才能生效（SKILL.md 有明确注释）。

3.4 第三步：打开仪表板

/understand-dashboard

会打开一个交互式 Web 仪表板：代码库被渲染成图谱，按架构层着色、可搜索、可点击。选中任意节点可看到其源码、关系图和白话解释。

3.5 第四步：持续学习

# 对代码库问任何问题
/understand-chat 支付流程是怎么工作的？

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

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

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

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

# 分析 Karpathy 模式 LLM Wiki 知识库
/understand-knowledge ~/path/to/wiki

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

# 每次提交自动增量更新（post-commit 钩子）
/understand --auto-update

# 超大 monorepo 中把分析范围限定到子目录
/understand src/frontend

每个命令对应 understand-anything-plugin/skills/ 下的一个独立 skill 目录（understand、understand-chat、understand-dashboard、understand-diff、understand-domain、understand-explain、understand-knowledge、understand-onboard），每个目录内的 SKILL.md 定义了该命令的完整行为规范。

4. 多平台安装

Understand Anything 支持多个 AI 编码平台，安装方式分四类。

4.1 Claude Code（原生）

即 3.1 节的插件市场两条命令。

4.2 一行式安装脚本（14 个平台）

覆盖 Codex / OpenCode / OpenClaw / Antigravity / Gemini CLI / Pi Agent / Vibe CLI / VS Code Copilot / Hermes / Cline / KIMI CLI / Trae / Nanobot / Kiro：

macOS / Linux： 下载仓库提供的 install.sh 执行，或用 bash -s <platform> 直接指定平台跳过交互式选择；Windows (PowerShell) 对应执行 install.ps1。

脚本行为（以 install.sh 源码为准）：

• 把仓库克隆到 ~/.understand-anything/repo（可用环境变量 UA_DIR 覆盖克隆目标、UA_REPO_URL 覆盖克隆地址）；
• 按下表为所选平台创建符号链接，安装后重启 CLI/IDE：

平台 ID	链接目标	链接风格
gemini / codex / opencode / pi / vibe / vscode / trae / nanobot / kiro	各平台 skills 目录（如 ~/.agents/skills、~/.copilot/skills）	per-skill（每个 skill 一条链接）
openclaw / antigravity / hermes / cline / kimi	对应 skills 目录	folder（整个 skills 目录一条链接，名为 understand-anything）

技能调用前缀注意：大多数平台用斜杠命令（/understand），但 Codex 用 $ 前缀——应输入 $understand 而非 /understand。如果两个前缀都不被识别，直接用自然语言表达："用 understand 技能分析这个项目"。

维护操作：./install.sh --update 更新；./install.sh --uninstall <platform> 卸载某平台的链接。

4.3 Cursor

克隆本仓库后，Cursor 会通过 .cursor-plugin/plugin.json 自动发现插件，无需手动安装。若自动发现失效，可打开 Cursor Settings → Plugins，在搜索框粘贴仓库地址手动添加。

4.4 VS Code + GitHub Copilot

安装了 GitHub Copilot 扩展（v1.108+）的 VS Code 会通过 .copilot-plugin/plugin.json 自动发现插件——克隆并用 VS Code 打开即可。想让技能在所有项目可用（个人技能），可运行 4.2 节的 install.sh 并选择 vscode 平台。

4.5 Copilot CLI

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

4.6 Kiro CLI / IDE

用 4.2 节的 install.sh 指定 kiro 平台。安装后：Kiro CLI 可执行 kiro-cli chat --agent understand "分析这个项目"；Kiro IDE 中技能以符号链接放入 ~/.kiro/skills/，understand 智能体写入 ~/.kiro/agents/understand.json，重启 IDE 后两者均可用。

4.7 平台兼容性一览

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

5. 把图谱与团队共享

图谱本质只是一份 JSON——commit 一次，队友就无需再跑管线。适合新人 onboarding、PR 评审和 docs-as-code 工作流。

提交什么：.ua/ 里的所有文件，除了 intermediate/ 和 diff-overlay.json（它们是本地临时文件；旧项目若用 .understand-anything/ 则替换该目录名）。在 .gitignore 中写：

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

保持新鲜：启用 /understand --auto-update——一个 post-commit 钩子会增量修补图谱，使每个 commit 都伴随匹配的图谱；或者在发版前手动重跑 /understand。

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

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

无 Claude Code 查看仪表板

图谱生成并 commit 之后，团队任何人都能用一条命令打开它——不需要 Claude Code、不需要 LLM、不需要 API 密钥，只需要 Node.js (>= 18)：用 npx 运行发布包附带的 understand-anything-viewer tarball，参数为被分析项目的路径。终端会打印一个带一次性 token 的 URL（形如 http://127.0.0.1:5173/?token=…）并在浏览器中打开完整交互仪表板。

该 viewer 是一个独立只读包（understand-anything-plugin/packages/viewer/package.json，engines 要求 Node >= 18），行为细节见 viewer README：

• 项目目录（默认当前目录）必须包含已提交的数据目录（.ua/ 或旧的 .understand-anything/）及其中的 knowledge-graph.json；
• 支持 --port <n>（默认 5173，端口被占用时自动递增）与 --no-open；
• 一切内容从本地磁盘只读提供，绑定 127.0.0.1 并由一次性访问 token 保护——不做任何 LLM 调用，数据不离开你的机器。

从源码仓库开发则走 Vite 开发服务器：pnpm install && pnpm --filter @understand-anything/core build，然后 GRAPH_DIR=/path/to/analyzed/project pnpm dev:dashboard。

6. 底层原理：Tree-sitter + LLM 混合架构

README 用"各做各最擅长的事"概括了分工：

• Tree-sitter（确定性）：把源码解析成具体语法树，抽取结构事实——import、export、函数/类定义、调用点、继承。扫描阶段预解析成 importMap 传给 file-analyzer，使其不必再从源码重新推导 import。相同输入永远得到相同输出，并且是指纹式变更检测（增量更新）的基础。
• LLM（语义）：把解析出的结构与原始源码并排阅读，产出解析器给不了的东西：白话摘要、标签、架构层归属、业务领域映射、引导式 Tour、语言概念注释。

这一分工保证了图谱在结构侧可复现（同样的代码永远产生同样的边），在语义侧仍能捕获意图（一个文件不只是"import 了什么"，而是"为了什么而存在"）。仓库内的支撑证据：extract-import-map.mjs 负责生成 import 映射，compute-batches.mjs 在分批阶段用 tree-sitter 并发抽取每个文件的导出符号以构建跨批次的 neighborMap（若 tree-sitter 初始化失败会降级为文件级边并输出可见告警）。

7. 多智能体管线：7 个阶段与 7 个智能体

/understand 编排 5 个专业智能体，/understand-domain 加入第 6 个，/understand-knowledge 加入第 7 个：

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

各智能体的提示词定义位于 understand-anything-plugin/agents/ 目录（如 project-scanner.md、file-analyzer.md）。

土耳其语 README 写的是"文件分析器并行运行（最多 3 个并发）"，而英文主文档与 SKILL.md 当前版本写的是 最多 5 个并发、每批 20–30 个文件——以仓库当前源码（5 并发）为准，可判断并发上限在迭代中上调过。

7.1 七个阶段的实际流转

SKILL.md 是管线的权威执行规范，实际分为 7 个阶段（每个阶段开始都会打印 [Phase N/7] … 进度行）：

1. Phase 0 — 预检：解析目标目录、检测 git worktree（worktree 中会重定向输出到主仓库根，避免数据目录随临时 worktree 丢失）、解析 $UA_DIR、决定全量/增量、写入 --auto-update 与 --language 配置、检查待合并的子域图谱。
2. Phase 0.5 — 忽略配置：首次运行生成 .ua/.understandignore 起始文件（由 core 包的 generateStarterIgnoreFile 读取 .gitignore、去重并给出按语言分组的测试文件排除建议），等待用户确认。
3. Phase 1 — SCAN：调度 project-scanner，输出 scan-result.json（文件清单、语言、框架、每文件的 importMap）。超过 100 个文件时会提示改用子目录限定范围。
4. Phase 1.5 — BATCH：运行 compute-batches.mjs 计算语义批次（batches.json），含跨批次的 neighborMap。
5. Phase 2 — ANALYZE：按批次并发调度 file-analyzer，各自写入 batch-<i>.json；随后 merge-batch-graphs.py 一次遍历完成合并——归一化节点 ID 前缀、复杂度取值（low→simple 等）、去重、丢弃悬空边，并运行两遍 tested_by 链接器把测试覆盖边规范为 production → test 方向。
6. Phase 3 — ASSEMBLE REVIEW：assemble-reviewer 对照合并脚本报告与 import map 复核组装图。
7. Phase 4/5 — ARCHITECTURE / TOUR：architecture-analyzer 产出 layers.json（每个层必须含 id、name、description、nodeIds），tour-builder 产出 Tour 步骤（必须含 order、title、description、nodeIds）。增量更新时架构分析会在全量合并节点集上重跑，并注入上一次的层定义以保持命名一致。
8. Phase 6 — REVIEW：默认走内联确定性校验脚本（校验节点必填字段、边引用、层/Tour 引用、孤儿节点并输出统计）；--review 则调度完整 LLM graph-reviewer 做交叉验证（扫描清单中的每个文件都应有对应节点）。
9. Phase 7 — SAVE：写入 $UA_DIR/knowledge-graph.json，生成结构指纹基线（build-fingerprints.mjs，此步必须先于 meta.json 成功——否则自动更新会把每个文件都判为结构变更并每次 commit 触发全量重建），再写 meta.json，最后清理临时文件但保留 scan-result.json 以便后续增量运行跳过 Phase 1。

7.2 图谱 Schema：13 种节点、26 种边

SKILL.md 末尾给出了完整 Schema 参考。节点 13 类，覆盖代码与非代码资产：

类型	说明	ID 约定
file	源代码文件	file:<相对路径>
function	函数或方法	function:<相对路径>:<名>
class	类、接口或类型	class:<相对路径>:<名>
module / concept	逻辑模块 / 抽象概念	module:<名> / 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、CloudFormation）	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，imports 为 0.7，默认 0.5）。

8. 测试与贡献

贡献流程（见 READMEs/README.tr-TR.md 与 CONTRIBUTING.md）：fork 仓库 → 创建特性分支 → 运行测试 → 提交并开 PR；重大改动建议先开 issue 讨论方案。核心包的测试命令：

pnpm --filter @understand-anything/core test

仓库测试分布在多层：core 包的单元与集成测试（understand-anything-plugin/packages/core/src/tests/，涵盖 schema、staleness、ignore-filter、fingerprint 等）、skill 脚本测试（tests/skill/，如 test_compute_batches.test.mjs 验证分批逻辑、test_merge_batch_graphs.py 验证图谱合并），以及仪表板前端测试（understand-anything-plugin/packages/dashboard/src/tests/）。大型变更还可参考 docs/benchmarks/large-monorepo.md 中的大仓库基准报告。

9. 小结

Understand Anything 的设计可以浓缩为三句话：确定性解析负责可复现的结构事实，LLM 负责不可解析的语义意图，多智能体管线负责把两者组装成一份可 commit、可增量、可只读查看的团队资产。配合 13 种节点与 26 种边的图谱 Schema、.ua/ 数据目录约定和 14 个平台的安装矩阵，它把"读懂一个陌生代码库"从人力密集工作变成了一个可重复执行的工程流程。