Understand-Anything：把代码库变成可交互知识图谱的多代理流水线与多平台安装实战

本篇以 Understand-Anything 项目的完整产品文档为主线，系统讲解它的核心工作流：通过 /understand 命令驱动一个"Tree-sitter 静态分析 + LLM 语义理解"的混合流水线，将项目中的每个文件、函数、类与依赖抽取为知识图谱（输出到 .ua/knowledge-graph.json），再用 /understand-dashboard 打开可搜索、可点击、按架构层着色的交互式 Web 面板。读完本文，你将掌握从各平台（Claude Code、Codex、Cursor、VS Code Copilot、Gemini CLI 等）安装插件、执行全量/增量分析、配置多语言输出、与团队共享已提交图谱的全部操作，并能看懂其多代理流水线与指纹化增量更新的底层实现。

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

项目的切入点是一个典型场景：你刚加入一个新团队，代码库有 20 万行，从哪里开始读？ Understand-Anything 是一个 Claude Code 插件（同时支持 Codex、Cursor、Copilot、Gemini CLI 等多个平台），它用一个多代理（multi-agent）流水线分析你的项目，为每个文件、函数、类、依赖构建知识图谱，然后提供一个交互面板让你可视化地探索它。项目的设计哲学在 README 中被明确表述为："目标不是做一个用你的代码有多复杂来震撼你的图——而是一个安静地教你理解每一部分如何拼合在一起的图"（原文口号：Graphs that teach > graphs that impress）。

从源码结构看，这一哲学落到了具体的技术分工上：

• **Tree-sitter（确定性一侧）**负责解析代码为具体语法树，抽取结构性事实：imports、exports、函数/类定义、调用点、继承关系。这些结果在扫描阶段被预解析为 importMap，直接传给文件分析器，避免它们从源码重新推导依赖。同样的输入永远产生同样的输出，这也是增量更新中指纹（fingerprint）变更检测的基础。
• **LLM（语义一侧）**读取解析后的结构并结合原始源码，产出解析器无法给出的内容：自然语言摘要、标签、架构层归属、业务领域映射、导览路径（guided tours）、语言概念讲解。

这个"确定性结构 + 语义意图"的分工，是图谱在结构上可复现（同样的代码永远生成同样的边）、在语义上捕捉意图（一个文件是用来做什么的，而不只是它 import 了什么）的根本原因。仓库中 understand-anything-plugin/packages/core/src/plugins/ 下按语言拆分的 tree-sitter 提取器（如 typescript-extractor.ts、python-extractor.ts、go-extractor.ts 等）就是"确定性一侧"的具体实现，packages/core/src/fingerprint.ts 与 staleness.ts 则支撑增量更新与图谱新鲜度判断。

2. 快速上手：安装、分析、探索三步走

2.1 安装插件（Claude Code 原生路径）

在 Claude Code 中直接执行：

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

使用本地模型？ 出于隐私或企业合规考虑，可以把你的平台指向本地模型服务（如 Ollama），按平台的集成指南更换模型提供商即可。Understand-Anything 本身不绑定特定模型，它通过你所在平台的模型执行 LLM 阶段。

2.2 分析你的代码库

/understand

该命令驱动多代理流水线：扫描项目 → 逐文件抽取函数、类、依赖 → 构建知识图谱，最终保存到 .ua/knowledge-graph.json。已有 .understand-anything/ 目录的旧项目会继续使用该目录——它存在时就是数据目录，无需任何迁移（这一兼容逻辑在 understand-anything-plugin/skills/understand/SKILL.md 的 Phase 0 中有明确规则：UA_DIR 优先取 .understand-anything，否则取 .ua）。

Token 消耗提示： 首次 /understand 会分析整个代码库，在大项目上可能消耗大量 token。建议在 token 套餐/订阅下执行，或使用本地模型完成首次初始化。之后的每次运行默认是增量的——只重新分析被修改的文件——因此消耗少得多。

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

# 生成内容（图谱节点描述与 Dashboard UI）的目标语言
/understand --language en

# 支持的语言: en (默认), zh, zh-TW, ja, ko, ru

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

• 知识图谱中节点的摘要与描述；
• Dashboard 界面的标签、按钮与 tooltip；
• 导览（tours）的讲解文案。

结合 SKILL.md 中的完整参数说明，还可以看到该参数的实现细节：它接受 ISO 639-1 代码（zh、ja、ko、en、es、fr、de 等）或友好名称（chinese、japanese 等），支持 zh-TW、pt-BR 等地域变体；解析结果会持久化到 $UA_DIR/config.json 的 outputLanguage 字段，保证后续增量更新的输出语言一致。在项目内首次运行且未传 --language 时，/understand 会自动检测你正在使用的会话语言：若检测出的语言不是英语，会在生成前请求确认（或输入其他语言覆盖）；英语会话不受影响。

2.3 打开交互面板

/understand-dashboard

会打开一个交互式 Web 面板：你的代码库被可视化为一张图，按架构层着色，可搜索、可点击。选中任意节点即可查看它的代码、关联关系以及自然语言解释。面板的源码位于 understand-anything-plugin/packages/dashboard/src，其中 GraphView.tsx、DomainGraphView.tsx、SearchBar.tsx、LayerLegend.tsx、PersonaSelector.tsx 等组件分别对应下文的功能列表。

2.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

这些命令一一对应仓库中的 skill 定义目录：understand-chat、understand-diff、understand-explain、understand-onboard、understand-domain、understand-knowledge、understand-dashboard。

其中 /understand-knowledge 值得一提：把它指向一个 Karpathy 模式的 LLM wiki，会先由确定性解析器从 index.md 抽取 wikilinks 与分类，再由 LLM 代理发现隐含关系、抽取实体、提炼论点（claims），最终得到一个带社区聚类的力导向知识图谱——把你的 wiki 变成一张可导航的"概念互联图"。

/understand 的其余参数（源自 SKILL.md 的 argument-hint 与 Options 一节）包括：

• --full：强制全量重建，忽略已有图谱；
• --auto-update / --no-auto-update：写入 $UA_DIR/config.json 的 autoUpdate 开关；
• --review：用完整的 LLM graph-reviewer 替代默认的内联确定性校验；
• --exclude <patterns>：逗号分隔的 glob 排除模式（支持 gitignore 语法与 ! 取反），优先级高于内置默认与 .understandignore 规则，新排除模式需配合 --full 才生效；
• 一个目录路径：分析该目录而非当前工作目录（worktree 场景下会自动重定向到主仓库根，可用 UNDERSTAND_NO_WORKTREE_REDIRECT=1 关闭）。

3. 功能全景：一个面板，六种视角

README 将功能组织为"探索结构图 + 理解业务逻辑 + 分析知识库"三条主线，外加六项面板能力。这里完整保留其功能矩阵：

功能	说明
结构图探索	每个文件、函数、类都是可点击、可搜索的节点；选中节点可见自然语言摘要、关系与导览路径
业务逻辑理解	切换到领域视图，代码被映射为真实的业务流程：领域（domains）、流程（flows）、步骤（steps）以横向图呈现
知识库分析	/understand-knowledge 将 Karpathy 模式 LLM wiki 转为带社区聚类的力导向图谱
导览路径（Guided Tours）	自动生成的架构走查，按依赖关系排序——按"正确的顺序"学习代码库
模糊与语义搜索	按名称或按含义查找；搜索"哪些部分处理认证？"即可在整张图上获得相关结果
改动影响分析（Diff Impact）	在提交前看到你的改动波及系统哪些部分，理解级联效应
按角色自适应界面	面板根据你是谁（初级开发 / PM / 高级用户）调整细节层级
分层可视化	按架构层自动分组——API、Service、Data、UI、Utility——并附颜色图例
语言概念讲解	12 种编程模式（泛型、闭包、装饰器等）在出现处就地讲解

这些能力与源码模块能对应上：understand-anything-plugin/packages/core/src/analyzer/tour-generator.ts 与 layer-detector.ts 对应导览与分层；embedding-search.ts、search.ts 对应语义/模糊搜索；change-classifier.ts 对应改动影响分析；dashboard 端的 PersonaSelector.tsx、LearnPanel.tsx、KnowledgeGraphView.tsx、DomainGraphView.tsx 则分别支撑角色自适应、语言概念、知识库视图与领域视图。

4. 多平台安装：一行命令打通 15+ 个 AI 编码平台

4.1 一行安装（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。

阅读 install.sh 源码可以确认这一过程的完整机制：

• 平台表（platforms_table）内置了各平台的 skills 目标目录与链接风格：如 gemini|~/.agents/skills|per-skill、codex|~/.agents/skills|per-skill、opencode|~/.agents/skills|per-skill、openclaw|~/.openclaw/skills|folder、vscode|~/.copilot/skills|per-skill、kiro|~/.kiro/skills|per-skill 等 14 个条目。per-skill 风格为每个 skill 单独建一个符号链接，folder 风格则把整个 skills/ 目录链为 understand-anything。
• --update 对 ~/.understand-anything/repo 执行 git pull --ff-only；--uninstall <platform> 精确移除该平台的链接（并处理 checkout 已丢失时的陈旧链接清理）。
• 环境变量可覆盖：UA_REPO_URL 修改克隆地址（适合私有镜像），UA_DIR 修改克隆目的地（默认 $HOME/.understand-anything/repo）。
• Kiro 特殊处理：安装 kiro 时，安装器还会动态扫描 agents/*.md 生成 ~/.kiro/agents/understand.json 代理配置，使 CLI 与 IDE 两种用法都可用。

skill 调用前缀说明： 各平台前缀不同。多数平台用斜杠命令（/understand），但 Codex 用 $——应输入 $understand 而不是 /understand。若两种前缀在你的平台上都不被识别，可以直接用自然语言请求："Use the understand skill to analyze this project."

常用维护命令：

./install.sh --update                # 更新到最新
./install.sh --uninstall <platform>  # 卸载指定平台

4.2 Cursor

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

4.3 VS Code + GitHub Copilot

VS Code（配合 GitHub Copilot v1.108+）在克隆本仓库时通过 .copilot-plugin/plugin.json 自动发现插件，无需手动安装。若需要"个人 skills"（跨所有项目可用），用上面的 install.sh 传 vscode 平台执行即可。

4.4 Copilot CLI

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

4.5 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 后两者都可用（与 install.sh 中 kiro 分支的行为一致）。

4.6 平台兼容矩阵

平台	状态	安装方式
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

5. 多代理流水线：图谱到底是怎么被造出来的

README 的"Under the Hood"一节给出代理分工表。/understand 编排 5 个专职代理，/understand-domain 加第 6 个，/understand-knowledge 加第 7 个：

代理	职责	使用方
project-scanner	发现文件，检测语言与框架	/understand
file-analyzer	抽取函数、类、导入；产出图谱节点与边	/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/（project-scanner.md、file-analyzer.md、architecture-analyzer.md、tour-builder.md、graph-reviewer.md、domain-analyzer.md、article-analyzer.md）。而 SKILL.md 则把整个 /understand 拆解为 7 个阶段，README 的每个论断都能在源码流程中得到印证：

1. Phase 0（预检）：解析目标目录、检测 git worktree 并重定向到主仓库根、确保插件已构建（首次需 pnpm --filter @understand-anything/core build）、解析数据目录 $UA_DIR、获取 commit hash、生成/确认 .understandignore，并根据"是否有 --full / 已有图谱 / commit 是否变化"决定全量、增量还是仅审查；
2. Phase 1（SCAN）：派发 project-scanner 子代理，产出 scan-result.json——文件清单（含 fileCategory：code/config/docs/infra/data/script/markup）、语言框架、复杂度估计，以及预解析的 importMap；
3. Phase 1.5（BATCH）：运行 compute-batches.mjs 计算语义批次（batches.json），把相关文件聚到一批并附带跨批邻居符号表（neighborMap），为跨批边提供置信度；
4. Phase 2（ANALYZE）：按批派发 file-analyzer（最多 5 并发），每批直接注入预解析的 import 数据；全部完成后运行 merge-batch-graphs.py 合并、规范化节点 ID、去重、剔除悬空边，并执行 tested_by 两遍链接（生产节点 → 测试节点）；
5. Phase 3（ASSEMBLE REVIEW）：assemble-reviewer 对组装后的图做完整性审查，报告并入警告列表；
6. Phase 4（ARCHITECTURE）与 Phase 5（TOUR）：architecture-analyzer 结合目录树与语言/框架上下文文件（languages/*.md、frameworks/*.md、locales/*.md）产出 layers.json；tour-builder 从项目入口点出发生成按依赖排序的 tour.json。两者的输出都会经过严格的归一化（剥信封、改写字段、补 ID、去悬空引用）；
7. Phase 6（REVIEW）与 Phase 7（SAVE）：默认用一段内联确定性校验脚本检查必需字段、重复节点、悬空边、文件节点必须全部入层、tour 引用有效性；--review 则派发 LLM graph-reviewer 做完整审查。保存时先写 knowledge-graph.json，再生成结构指纹基线（build-fingerprints.mjs，必须成功才写 meta.json——否则后续自动更新会把每个文件都误判为结构级变更），最后清理中间产物（把临时目录移入 .trash-* 而非直接删除，7 天后回收）。

知识图谱的 Schema 也在 SKILL.md 中有完整定义：13 种节点类型（file、function、class、module、concept、config、document、service、table、endpoint、pipeline、schema、resource，各有 前缀:路径[:名称] 的 ID 约定）与 26 种边类型（结构、行为、数据流、依赖、语义、基础设施、Schema/数据七大类），以及按边类型定义的权重约定（如 contains 为 1.0、calls 为 0.8、imports 为 0.7、默认 0.5）。

自动增量更新的机制：--auto-update 会写入 config.json 的 autoUpdate: true。插件的 hook 配置（understand-anything-plugin/hooks/hooks.json）在 SessionStart 时比对 meta.json 中的 gitCommitHash 与当前 HEAD，若不一致则提示代理读取 auto-update-prompt.md 并执行增量更新；PostToolUse（Bash）hook 还会调用 post-tool-use-auto-update.mjs 在提交后触发更新。相关测试见 tests/hooks/post-tool-use-auto-update.test.mjs 与 understand-anything-plugin/src/tests/worktree-redirect.test.mjs。

6. 与团队共享图谱：一次提交，全员受益

图谱本质上只是 JSON——提交一次，队友就跳过整个流水线。适合 onboarding、PR 评审与 docs-as-code 流程。

提交什么： .ua/ 下的一切，除了 intermediate/ 与 diff-overlay.json（这两个是本地临时文件）。旧项目若使用 .understand-anything/，把下面的目录名替换即可：

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

保持新鲜： 启用 /understand --auto-update——post-commit hook 会增量修补图谱，让每个 commit 都带着与之匹配的图谱；或者在每次 release 前手动重跑 /understand。

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

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

6.1 不装 Claude Code 也能看面板：独立 viewer

图谱生成并提交后，团队任何一人都能用一条命令打开面板——不需要 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=…）并在浏览器中打开完整的交互面板。项目目录（默认为当前目录）必须包含已提交的数据目录（.ua/，或旧的 .understand-anything/）。所有内容只读地从本地磁盘服务：没有 LLM 调用，没有任何数据离开你的机器。

从源码看，这个能力来自独立包 understand-anything-plugin/packages/viewer/package.json：包名 understand-anything-viewer，描述即 "Standalone read-only viewer … no Claude Code or LLM required"，engines.node 声明 >=18，与 README 的前置条件一致。

从克隆的仓库开发？ 先 pnpm install && pnpm --filter @understand-anything/core build，然后：

GRAPH_DIR=/path/to/analyzed/project pnpm dev:dashboard

即通过 Vite 开发服务器（package.json 根脚本 dev:dashboard 指向 dashboard 包的 dev）获得同样的只读浏览体验，适合需要调试面板本身的场景。

7. 运行环境与贡献指南

• 运行环境：Claude Code 插件路径首次运行会自建 @understand-anything/core（需 Node.js ≥ 22 与 pnpm，缺失时 SKILL.md 会明确提示）；独立 viewer 仅要求 Node.js ≥ 18；多平台安装路径通过符号链接分发 skills，本身不需要 Node 环境。
• 本地模型：隐私/企业场景下可把平台指向本地模型服务（如 Ollama）完成初始化，后续增量运行成本更低。
• 贡献流程（来自 README）：
  1. Fork 仓库；
  2. 创建功能分支（git checkout -b feature/my-feature）；
  3. 运行测试（pnpm --filter @understand-anything/core test——根 package.json 中 test 脚本为 vitest run，覆盖 tests/ 与 packages/core/src/__tests__/ 下的用例，如 parsers.test.ts、fingerprint.test.ts、tests/skill/ 中的批次计算与合并测试）；
  4. 提交改动并发起 PR；重大变更建议先开 issue 讨论方案。
• 许可：MIT License。

8. 小结

Understand-Anything 的价值链可以浓缩为一句话：确定性静态分析（Tree-sitter）提供可复现的结构骨架，LLM 提供不可解析的语义意图，两者经 7 阶段多代理流水线合成为一份 JSON 知识图谱，再由分层着色、语义搜索、导览、diff 影响面与领域视图五种视角呈现。安装上，它以 Claude Code 插件为原生形态，用一份 install.sh/install.ps1 覆盖其余十余个平台；分发上，"图谱即 JSON + 独立只读 viewer"的组合让它天然适配团队 onboarding 与 docs-as-code 工作流。对于接手大型陌生代码库的场景，它的定位非常明确：不再盲读代码，而是先看见全局，再深入局部。