Understand Anything 实战指南：多平台安装、知识图谱生成流水线与团队共享

本文为 Understand Anything（一个以 Claude Code 插件形式发布、支持 Codex / Cursor / Copilot / Gemini CLI 等多平台的多智能体代码分析工具）的完整技术导读。基于仓库内的日文版 README（READMEs/README.ja-JP.md）展开，并结合 install.sh、skills/understand/SKILL.md 等源码逐层补充实现细节。读完本文，你将掌握：如何在各 AI 编码平台安装插件、如何用 /understand 命令族生成并维护知识图谱、如何向团队共享图谱、以及底层 “Tree-sitter 静态解析 + LLM 语义分析” 混合流水线的真实工作方式。

一、项目定位：把代码库变成可探索的知识图谱

Understand Anything 的出发点是一个很具体的场景：刚加入新团队，面对一个 20 万行的代码库，从哪开始？ 它的回答是：用多智能体流水线分析整个项目，把每个文件、函数、类、依赖关系构建成一张知识图谱，再通过交互式仪表盘可视化探索——项目自己的表述是“停止盲目读代码，开始看到全局”（Graphs that teach > graphs that impress，图要教会你，而不是炫耀你的代码有多复杂）。

从仓库结构看，它本质是一个 Claude Code Plugin（仓库根目录存在 .claude-plugin/、.cursor-plugin/、.copilot-plugin/ 三个插件清单目录），核心产物是一个 JSON 文件 .ua/knowledge-graph.json，由 packages/dashboard 下的 Vite + React 仪表盘消费。

它对外宣称的能力在 READMEs/README.ja-JP.md 中完整列出：

• 结构图探索：整个代码库作为交互式知识图谱呈现，每个文件、函数、类都是可点击、可搜索的节点；选中节点可看到通俗摘要、依赖关系和引导式学习路径（Guided Tour）。
• 业务逻辑理解：切换到 Domain 视图后，代码如何映射到真实业务流程（领域、流程、步骤）以横向图布局一目了然。
• 知识库分析：把 /understand-knowledge 指向 Karpathy 模式的 LLM Wiki，生成带社区聚类的力导向知识图谱——确定性解析器先从 index.md 抽取 wikilink 和分类，再由 LLM 代理发现隐含关系、抽取实体、浮出关键主张。
• 引导式学习路径：按依赖顺序自动生成的架构讲解，保证“以正确顺序学代码”。
• 模糊 + 语义检索：按名称或语义搜索，例如问“哪部分处理认证？”即可跨图检索。
• 差分影响分析：提交前预判改动波及系统哪些部分。
• Persona 自适应 UI：仪表盘根据用户身份（初级开发者 / PM / 高级用户）调整细节密度。
• 分层可视化：按 API、Service、Data、UI、Utility 等架构层自动分组，带颜色图例。
• 语言概念讲解：泛型、闭包、装饰器等 12 类编程模式在出现处结合上下文解释。

二、快速上手：四步跑通

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

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

使用本地模型：出于隐私或企业用途，可以把平台指向 Ollama 等本地模型服务商，按对应平台的集成指南更换模型提供方即可。

2. 分析代码库：/understand

/understand

多智能体流水线会扫描项目、抽取全部文件 / 函数 / 类 / 依赖，生成知识图谱并保存到 .ua/knowledge-graph.json。这里有一个重要的数据目录兼容规则（在 SKILL.md 的 Phase 0 中有源码级确认）：如果项目里已经存在旧版 .understand-anything/ 目录，它会继续作为数据目录使用，无需任何迁移；否则使用新的 .ua/ 目录。

Token 用量提示：首次 /understand 分析整个代码库，大项目会消耗相当可观的 token。文档建议在 token 套餐 / 订阅下运行，或初始化阶段使用本地模型；后续运行默认增量——只重新分析变更文件，消耗大幅降低。

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

# 用日语生成内容（知识图谱节点描述和 Dashboard UI）
/understand --language ja

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

语言行为在 SKILL.md 的 Phase 0 第 3.6 步有完整定义：--language 接受 ISO 639-1 代码（zh、ja、ko、en、es…）或友好名称（chinese、japanese…），也支持 zh-TW 这类区域变体；项目首次运行且未传 --language 时，流水线会检测对话语言，非英语时先询问确认（或输入其他语言代码覆盖），英语对话不受影响；确认结果持久化到 .ua/config.json 的 outputLanguage 字段，后续运行直接复用、不再询问。该参数影响三处内容：知识图谱节点的摘要与描述、仪表盘 UI 的标签 / 按钮 / 工具提示、引导式学习路径的讲解文本。

/understand 的完整参数表（源自 SKILL.md frontmatter 与 Options 章节，比 README 更详尽）：

参数	作用
[path]	分析指定目录（相对路径按当前工作目录解析），默认当前目录
--full	忽略已有图谱，强制全量重建
--auto-update	开启提交时自动更新图谱（向 $UA_DIR/config.json 写 autoUpdate: true）
--no-auto-update	关闭自动更新（写 autoUpdate: false）
--review	运行完整 LLM graph-reviewer 校验，而非默认的内置确定性校验
--language <lang>	指定全部文本内容的生成语言，偏好写入 config.json
--exclude <patterns>	逗号分隔的 gitignore 风格排除模式（支持 ! 否定），优先级高于内置默认和 .understandignore；新增排除需要 --full 才生效

3. 打开仪表盘探索

/understand-dashboard

交互式 Web 仪表盘会以图的形式呈现代码库——按架构层着色、可搜索、可点击；选中任意节点可以看到代码、关联关系和通俗解释。

4. 继续深入：/understand 命令族

# 就代码库问任何问题
/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

这些命令在插件中以独立 Skill 组织，每个目录对应一个技能：understand-chat、understand-diff、understand-explain、understand-onboard、understand-domain、understand-knowledge、understand-dashboard。

三、多平台安装

Understand-Anything 支持多 AI 编码平台，安装路径分四类。

3.1 Claude Code（原生）

即上文两步 /plugin 命令，通过插件市场安装。

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

适用于 Codex、OpenCode、OpenClaw、Antigravity、Gemini CLI、Pi Agent、Vibe CLI、VS Code Copilot、Hermes、Cline、KIMI CLI、Trae、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

安装器行为可以从 install.sh 源码精确验证：

• 把仓库克隆到 ~/.understand-anything/repo（install.sh 中 REPO_DIR 定义），并建立通用插件根软链 ~/.understand-anything-plugin（install.sh）；
• 支持的平台及其链接方式在 platforms_table() 中一张表维护（install.sh）：gemini / codex / opencode / pi 链到 ~/.agents/skills（per-skill 模式，每个技能一个软链）；openclaw、antigravity、hermes、cline、kimi 采用 folder 模式（整个 skills 目录链为 understand-anything）；vscode 对应 ~/.copilot/skills；kiro 对应 ~/.kiro/skills；
• 对 Kiro 平台会额外生成 ~/.kiro/agents/understand.json 代理配置，其中的 resources 列表由 agents/ 目录下的 .md 文件动态枚举生成，保证代理定义增删时不漂移（install.sh）；
• 可通过环境变量覆盖行为：UA_REPO_URL 改克隆地址（便于私有镜像）、UA_DIR 改克隆落点；
• 后续维护：更新用 ./install.sh --update（内部执行 git pull --ff-only），卸载用 ./install.sh --uninstall <platform>；卸载会保留 ~/.understand-anything/repo 本体（其他平台可能还在用），只移除对应平台的软链。

技能调用前缀差异：多数平台用斜杠命令（/understand），但 Codex 用 $——应输入 $understand 而非 /understand（安装器在 codex 安装结束后也会打印这条提示）。若平台两种前缀都不识别，可以直接用自然语言：“用 understand 技能分析这个项目”。

3.3 Cursor 与 VS Code + GitHub Copilot：自动发现

• Cursor：克隆本仓库后用 Cursor 打开，插件经 .cursor-plugin/plugin.json 自动发现，无需手动安装。若自动发现失效，打开 Cursor Settings → Plugins，在搜索框粘贴仓库地址手动添加。
• VS Code + GitHub Copilot（Copilot 扩展 v1.108+）：同样克隆后打开即经 .copilot-plugin/plugin.json 自动发现；想要“全项目可用的个人技能”时，用上面 install.sh 的 vscode 平台安装。

3.4 Copilot CLI 与 Kiro

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

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 代理写入 ~/.kiro/agents/understand.json，重启 IDE 后两者均可用。

3.5 平台兼容性一览

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

四、向团队共享图谱，以及无 LLM 查看

4.1 提交图谱，队友免跑流水线

图谱就是一个 JSON 文件——提交一次，队友就不用再跑一遍流水线，非常适合 onboarding、PR review 和 docs-as-code 工作流。README 给出的参考案例是 GoogleCloudPlatform/microservices-demo（含已提交图谱的 Go / Java / Python / Node 参考项目）。

提交什么：.ua/ 内所有文件，除了 intermediate/ 和 diff-overlay.json（它们是本地临时产物）。旧项目把目录名替换为 .understand-anything/ 即可：

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

4.2 不需要 Claude Code 也能看仪表盘

图谱生成并提交后，任何团队成员一条命令即可打开——不需要 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 调用，数据不出机器。

从仓库克隆直接开发也可以达到同样效果：

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

经由 Vite 开发服务器启动（dev:dashboard 脚本定义在根 package.json 的 scripts 中）。

五、内部机制：Tree-sitter + LLM 混合分工

日文 README 的“内部机制”一节说明了核心设计哲学：能确定性做的交给静态分析，需要语义理解的交给 LLM。

• Tree-sitter（确定性侧）：把源码解析成具象语法树，抽取结构性事实——import、export、函数 / 类定义、调用点、继承关系。扫描阶段会把它们预解析为 importMap 传给文件分析器，避免 LLM 再次从源码推导 import。同一输入永远产生同一输出，这也是增量更新做指纹变更检测的基础。
• LLM（语义侧）：读取解析后的结构和原始源码，产出解析器给不了的东西——通俗摘要、标签、架构层归属、业务领域映射、引导式学习路径、语言概念注解。

这个分工带来一个可验证的工程性质：结构侧可复现（相同代码永远得到相同的边），同时语义侧捕捉意图（一个文件“为什么存在”，而不只是“它 import 了什么”）。

仓库源码印证了这条分工线。skills/understand/scan-project.mjs 的头部注释（scan-project.mjs）明确写道：该脚本负责确定性的文件枚举（优先 git ls-files）、.understandignore 与 --exclude 过滤、逐文件语言检测、分类和行数统计、复杂度估计，并把确定性排序 + 内容摘要（SHA-256）作为变更检测基础——注释里还特别点出，这替代了早期“让 LLM 现场写一个 Node 脚本走文件树做规则查表”的做法，因为那纯属按 LLM 费率计费却只做查表的浪费。LLM 仍保留的部分（读 README 与清单、综合项目名 / 描述 / 框架叙述）则留在 project-scanner 代理里。语言检测表与 core 包的语言配置对齐：languages/configs/ 目录为每种语言（TypeScript、Python、Go、Rust、Terraform、Dockerfile、YAML 等）维护独立配置。

六、多 Agent 流水线详解

/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

这 7 个代理的提示词定义都在 agents/ 目录中，例如 project-scanner.md、file-analyzer.md、tour-builder.md、graph-reviewer.md。

并行度与增量：文件分析器并行执行，上限 5 个并发、每批 20～30 个文件；流水线支持增量更新，只重分析上次运行以来变更的文件。

SKILL.md 把整条流水线细化为 7 个阶段（外加预检阶段 0 / 0.5），值得逐段了解：

1. Phase 0（预检）：确定全量还是增量。除了解析目录参数外，还包含两个工程细节——git worktree 重定向（worktree 里的数据目录会随会话销毁，故检测到 worktree 时把输出重定向到主仓库根，可用 UNDERSTAND_NO_WORKTREE_REDIRECT=1 关闭），以及首次构建 core 包（pnpm --filter @understand-anything/core build，需要 Node.js ≥ 22、pnpm ≥ 10）。判定逻辑：无已有图谱或带 --full 走全量；已有图谱且 commit 哈希未变则询问用户是否重建 / 审查 / 跳过；已有图谱且有变更文件则走增量（git diff <lastCommitHash>..HEAD --name-only 取变更列表）。
2. Phase 0.5（忽略配置）：确保 .understandignore 存在——首次运行会用 generate-ignore.mjs 基于 .gitignore 和项目结构生成建议排除项，等用户确认后才继续。
3. Phase 1（SCAN）：派发 project-scanner，输出 scan-result.json（文件清单 + 行数 + fileCategory 分类 + importMap）。文件超过 100 个时会提示用户考虑用子目录参数缩小范围。
4. Phase 1.5（BATCH）：运行 compute-batches.mjs 计算语义批次，产出 batches.json；增量模式下用 --changed-files 只生成含变更文件的批次，但 neighborMap 仍引用未变更文件以保住跨批次边。
5. Phase 2（ANALYZE）：按批次派发 file-analyzer（最多 5 并发），随后运行 merge-batch-graphs.py 一次完成节点 / 边合并、ID 归一化、复杂度值归一化、(source, target, type) 去重、悬挂边丢弃，以及两遍 tested_by 边规范化（保证所有覆盖边方向为 production → test）。增量路径会先把旧图中受影响节点的边删干净，再与新鲜批次一起合并。
6. Phase 3～5（ASSEMBLE REVIEW / ARCHITECTURE / TOUR）：装配审查、架构层识别（layer-detector 与 LLM 协作）、学习路径生成。后两者的产物都经过确定性归一化（解包 envelope、重命名旧字段、补 ID、丢弃悬挂引用）。
7. Phase 6（REVIEW）：默认走内联确定性校验脚本（检查节点必填字段、边引用完整性、层归属唯一性、孤儿节点告警等）；带 --review 时派发完整 LLM graph-reviewer，并把扫描清单与图谱互相对账——每个扫描到的文件都应有对应节点。
8. Phase 7（SAVE）：写入 knowledge-graph.json，先生成结构指纹基线再写 meta.json（顺序不能反，否则每次 commit 都会被误判为需要全量重建——见 SKILL.md 中 issue #152 的注释），最后清理中间产物（保留 scan-result.json 供后续增量跳过 Phase 1）。

图谱的 Schema 契约同样在 SKILL.md 中完整定义：13 种节点类型（file、function、class、module、concept、config、document、service、table、endpoint、pipeline、schema、resource，各有 file:/config: 等 ID 前缀约定）和 26 种边类型（结构性 imports/contains/inherits…、行为性 calls/middleware…、数据流 reads_from/transforms…、基础设施 deploys/triggers 等），并按边类型给出权重约定（contains 1.0，inherits/implements 0.9，calls 0.8，直至默认 0.5）。

测试佐证：这条流水线的确定性部分有独立测试覆盖，如 test_scan_project.test.mjs、test_compute_batches.test.mjs、test_merge_batch_graphs.py（含 夹具数据）、图谱新鲜度检查 test_skill_graph_freshness.test.mjs。

七、参与贡献

贡献流程在 CONTRIBUTING.md 中有详细说明，README 给出的最短路径是：

1. Fork 仓库；
2. 创建特性分支（git checkout -b feature/my-feature）；
3. 运行测试（pnpm --filter @understand-anything/core test，core 包的 vitest 配置见 vitest.config.ts）；
4. 提交变更并发起 PR。较大的改动建议先开 issue 讨论方案。

---

小结：Understand Anything 的价值链条清晰——/understand 用 Tree-sitter + LLM 混合流水线和 7 个专职代理生成结构可复现、语义有深度的 knowledge-graph.json；/understand-dashboard、/understand-chat、/understand-diff 等命令围绕这张图谱提供探索与问答；install.sh 的软链机制 + 平台自动发现让它能铺开到 17 个 AI 编码平台；而“提交图谱 + npx viewer”的组合则让图谱成为团队资产——不跑流水线、不碰 LLM 也能看。