Understand Anything 繁体中文实战指南：多平台安装、/understand 全链路分析与可共享知识图谱

Understand Anything 是一个将任意代码库、知识库或文档转化为「可探索、可搜索、可对话」的交互式知识图谱的开源项目，通过 Claude Code 插件 + 多智能体（multi-agent）流水线分析你的项目，输出包含文件、函数、类与依赖关系的图谱，并配套一个可交互的可视化仪表盘。读完本篇指南，你将掌握：如何在 Claude Code、Codex、Cursor、Copilot、Gemini CLI 等 16 个平台上完成安装、如何用 /understand 完成从扫描到图谱保存的完整分析流程、如何通过 --language zh-TW 等参数控制输出语言，以及如何把生成的知识图谱提交给团队共享并在无 Claude Code 环境下用一条命令打开仪表盘。

一、定位与设计目标：从「盲读代码」到全局理解

当你刚加入一个新团队，面对 20 万行代码，从哪里开始？这是 README 开篇给出的核心场景。Understand Anything 是一个 Claude Code Plugin，它做的事情可以概括为三步：

1. 用多智能体流水线分析你的项目；
2. 构建涵盖每个文件、函数、类与依赖关系的知识图谱；
3. 提供交互式仪表盘，让你以可视化方式探索整个系统。

其设计目标在项目文档中被明确表述为：

目标不是用代码库的复杂程度惊艳你 —— 而是默默告诉你每一块是怎么拼在一起的。（"Graphs that teach > graphs that impress."）

从仓库结构看（见 CLAUDE.md），该项目是一个 pnpm workspaces monorepo，核心代码全部位于 understand-anything-plugin/ 目录下：

• packages/core — 共享分析引擎（类型、持久化、tree-sitter、搜索、schema、tour、插件）；
• packages/dashboard — React + TypeScript 网页仪表盘（React Flow、Zustand、TailwindCSS）；
• skills/ — 技能定义（/understand、/understand-dashboard 等）；
• agents/ — 智能体定义（project-scanner、file-analyzer、architecture-analyzer、tour-builder、graph-reviewer 等）。

运行前提：Node.js >= 22（开发环境为 v24）、pnpm >= 10（通过根 package.json 的 packageManager 字段锁定）。

二、核心功能：知识图谱能做什么

探索代码结构图

将代码库以交互式知识图谱呈现 —— 每个文件、函数和类都是可点击、可搜索、可探索的节点。选中任意节点即可查看浅显易懂的摘要、依赖关系和引导式学习路径。

理解业务逻辑

切换到领域视图（domain view），查看代码如何对应到真实的业务流程 —— 以水平图的形式展示领域（domain）、流程（flow）和步骤（step）。

分析知识库

将 /understand-knowledge 指向一个 Karpathy 模式的 LLM Wiki 知识库，即可获得带社区聚类的力导向知识图谱。其工作原理是：确定性解析器先从 index.md 中提取 wikilinks 和分类，然后 LLM 代理发现隐式关系、提取实体并挖掘论断（claims）—— 将 wiki 转化为可导航的互联思想图谱。

其余六项功能在 README 中以两列三行表格给出，完整继承如下：

功能	说明
🧭 引导式学习（Guided Tours）	自动产生架构学习路径，按依赖顺序学习，在正确的顺序里学代码库
🔍 语义搜索	支持模糊搜索 + 语义搜索，例如搜索「哪些部分处理身份验证？」即可在整个图中获取相关结果
📊 变更影响分析（Diff Impact）	提交变更前，查看变更会影响系统的哪些部分，了解变更对整个代码库的连锁反应
🎭 用户角色自适应 UI	根据用户类型（初级开发 / 项目经理 / 高级用户）调整其详细程度
🏗️ 层级可视化	按架构层级自动分组 —— API、服务、数据、UI、系统工具 —— 并附有颜色编码图例
📚 语言概念	12 种编程模式（泛型、闭包、装饰器等）将在上下文中逐一解释

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

第 1 步：安装插件（Claude Code 原生方式）

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

使用本地模型？ 基于隐私或企业需求，可以将平台指向本地模型提供方（例如 Ollama），依照其整合指南变更模型提供方即可。

第 2 步：分析你的代码库

/understand

多智能体架构会：扫描项目、提取函数 / 类 / 依赖关系、构建知识图谱并保存至 .ua/knowledge-graph.json。

数据目录兼容规则： 已经有 .understand-anything/ 目录的旧项目会继续使用该目录 —— 只要它存在，它仍是数据目录（读写都走它），无需任何迁移；新项目则统一使用 .ua/。这一规则在 CLAUDE.md 与技能脚本中一致实现。

关于 Token 消耗的提醒： 首次执行 /understand 会分析整个代码库，在大型项目上可能消耗大量 token。建议在有 token 方案 / 订阅的情况下执行，或在初始化时使用本地模型（见上文）。后续执行默认为增量式 —— 只重新分析变更过的文件 —— 因此消耗的 token 大幅减少。

在地化输出： 使用 --language 参数产生中文内容：

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

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

--language 参数会影响三个层面：

• 知识图谱中的节点摘要和描述；
• Dashboard UI 的标签、按钮和提示；
• 引导路线（tour）的解释说明。

结合技能定义（见 understand-anything-plugin/skills/understand/SKILL.md），该参数的实际能力比 README 列出的更多：它接受 ISO 639-1 代码（zh、ja、ko、en、es、fr、de 等）或友好名称（chinese、japanese、korean 等），并保留地区变体（zh-TW、zh-HK、pt-BR 等）。解析后的语言偏好会写入 .ua/config.json 的 outputLanguage 字段，后续增量更新自动复用，保证多轮运行语言一致。

第 3 步：打开数据看板

/understand-dashboard

打开交互式网页数据看板，你的代码库将以图表形式呈现 —— 按架构层级进行颜色编码，支持搜索和点击。选中任意节点即可查看其代码、关系以及简明易懂的解释。

第 4 步：深度使用

以下是 README 给出的完整斜杠命令集合，覆盖日常使用场景：

# 询问任意代码库的问题
/understand-chat 付款流程是怎麼運作的？

# 分析目前修改的影响
/understand-diff

# 深入理解某个文件
/understand-explain src/auth/login.ts

# 为新团队成员产生指南
/understand-onboard

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

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

# 直接重跑即可 —— 默认增量更新，只分析变更的文件
/understand

# 安装 post-commit 挂钩，每次提交自动增量更新
/understand --auto-update

# 大型 monorepo？把分析范围限定到某个子目录
/understand src/frontend

除 README 列出的用法外，/understand 技能本身还支持一组在 SKILL.md 中定义的高级选项，值得了解：

选项	作用
--full	强制全量重建，忽略现有图谱
--auto-update / --no-auto-update	写 autoUpdate: true/false 到 .ua/config.json，开关提交时自动更新
--review	运行完整的 LLM graph-reviewer 校验（替代内联确定性校验）
--language <lang>	指定输出语言（详见上文）
--exclude <patterns>	逗号分隔的 glob 排除模式，支持 gitignore 语法与 ! 否定，优先级高于内置默认与 .understandignore；新增排除模式需 --full 才生效
<目录路径>	分析指定目录而非当前工作目录（monorepo 子项目场景）

四、多平台安装：一份技能，16 个平台

Understand-Anything 可在多个 AI 编码平台上运行。除 Claude Code 原生插件外，官方提供了 install.sh（macOS / Linux）与 install.ps1（Windows）两条安装脚本，通过「克隆仓库 + 建立符号链接」的方式把技能接入各平台。

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

关于技能调用方式： 不同平台的调用前缀不同。大多数平台使用斜杠指令（/understand），但 Codex 使用 $ —— 请输入 $understand，而不是 /understand。如果两种前缀都无法识别，直接用自然语言请求即可：「使用 understand 技能分析这个项目」。

脚本参数一览（来自 install.sh 源码头部注释与 usage() 函数）：

install.sh [<platform>]            为 <platform> 安装（省略则交互提示）
install.sh --update                拉取最新变更（技能经符号链接自动更新）
install.sh --uninstall <platform>  移除 <platform> 的链接
install.sh --help                  查看帮助

环境变量：
  UA_REPO_URL  覆盖克隆 URL（默认为官方仓库）
  UA_DIR       覆盖克隆目标（默认：$HOME/.understand-anything/repo）

从源码看安装机制的细节（install.sh 第 25–46 行的平台表）：脚本内置一张 平台ID|技能目标目录|链接风格 三列表格，其中：

• per-skill 风格：为每个技能（understand、understand-chat、understand-diff 等）单独建立一条符号链接；
• folder 风格：把整个 skills/ 目录以 understand-anything 名义链接一个入口。

平台与目标目录对应关系如下（引自 platforms_table()）：

平台 ID	技能目标目录	风格
gemini / codex / opencode / pi	~/.agents/skills	per-skill
vibe	~/.vibe/skills	per-skill
vscode	~/.copilot/skills	per-skill
nanobot	~/.nanobot/workspace/skills	per-skill
kiro	~/.kiro/skills	per-skill
openclaw	~/.openclaw/skills	folder
antigravity	~/.gemini/antigravity/skills	folder
hermes	~/.hermes/skills	folder
cline	~/.cline/skills	folder
kimi	~/.kimi/skills	folder

除 README 列出的 13 个平台取值外，当前脚本的平台表还包含 trae（~/.trae/skills），从源码结构看是后续新增的支持平台。此外，安装时还会把 ~/.understand-anything-plugin 指向仓库内 understand-anything-plugin/ 目录（通用插件根符号链接）；针对 Kiro，脚本会额外生成 ~/.kiro/agents/understand.json，其 resources 列表从 agents/ 目录下的 agent 定义文件动态构建（LC_ALL=C sort 保证确定性顺序，不依赖 jq）。

各平台安装方式汇总

多平台兼容性完整继承自原文档：

平台	状态	安装方式
Claude Code	✅ 原生	插件市集（/plugin marketplace add）
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

Cursor：复制此仓库后，Cursor 会自动通过 .cursor-plugin/plugin.json 发现插件。无需手动安装 —— 只需克隆并在 Cursor 中打开即可。若自动发现未生效，可手动安装：打开 Cursor Settings → Plugins，在搜索框中粘贴仓库地址并新增。

VS Code + GitHub Copilot：安装 GitHub Copilot 扩展（v1.108+）后，VS Code 会透过 .copilot-plugin/plugin.json 自动发现插件，克隆后直接在 VS Code 中打开即可，无需手动安装。若需要在所有项目中使用（个人技能），运行 install.sh 并选择 vscode 平台即可。

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 "分析这个项目"
• Kiro IDE：技能会以符号链接方式建立到 ~/.kiro/skills/，并将 understand agent 写入 ~/.kiro/agents/understand.json，重启 IDE 后两者皆可使用。

五、技术原理：Tree-sitter + LLM 混合分析

确定性与语义的分工

把确定性的事情交给静态分析，把需要语义理解的事情交给 LLM：

• Tree-sitter（确定性） —— 将源码解析为具体语法树，提取结构性事实：import、export、函数 / 类定义、调用点、继承关系。在 scan 阶段预解析为 importMap 并传给 file-analyzer，避免它再从源码推导一次 import。相同输入永远得到相同输出，并作为增量更新的手指指纹（fingerprint）基础。
• LLM（语义） —— 读取解析后的结构以及源码，产生解析器做不到的事：plain-English 摘要、标签、架构层归属、业务领域映射、导览路径、语言概念标注。

正是这个分工让图谱在结构层面具备可重现性（同样的代码总是产生同样的边），同时在语义层面也能捕捉意图（一个文件是「为了什么」而存在，不只是它 import 了什么）。

补充实现细节：core 包使用的是 web-tree-sitter（WASM 版）而非原生 tree-sitter 绑定 —— 原因是原生绑定在 darwin/arm64 + Node 24 上会失败（见 CLAUDE.md Gotchas 一节）；解析器与提取器按语言/框架注册，对应源码位于 understand-anything-plugin/packages/core/src/languages/ 与 understand-anything-plugin/packages/core/src/plugins/extractors/。

多智能体流水线

/understand 指令调度 5 个 agent，/understand-domain 额外增加第 6 个：

Agent	职责	定义文件
project-scanner	扫描项目文件，侦测语言和框架	agents/project-scanner.md
file-analyzer	提取代码结构（函数、类和导入），产生图节点和边	agents/file-analyzer.md
architecture-analyzer	识别架构层	agents/architecture-analyzer.md
tour-builder	产生引导式学习路径	agents/tour-builder.md
graph-reviewer	验证图的完整性和引用完整性	agents/graph-reviewer.md
domain-analyzer	提取业务领域、流程和处理步骤（由 /understand-domain 使用）	agents/domain-analyzer.md
article-analyzer	从 wiki 文章中提取实体、论断和隐式关系（由 /understand-knowledge 使用）	agents/article-analyzer.md

除 README 列出的 7 个 agent 外，从 SKILL.md 的流水线定义看，Phase 3 还会调度 assemble-reviewer（agents/assemble-reviewer.md）审查合并后的组装图。文件分析器并行执行（当前 SKILL.md 中为最多 5 个并发 subagent），支持增量更新 —— 仅重新分析自上次运行以来发生变更的文件。

七阶段流水线细节

结合 SKILL.md 的完整定义，一次 /understand 运行的内部流程如下：

阶段	名称	关键动作
Phase 0	Pre-flight	解析项目根目录（含 git worktree 重定向）、解析数据目录 $UA_DIR（.ua/ 或旧版 .understand-anything/）、读取 meta.json 决定全量 / 增量 / 仅审查
Phase 0.5	Ignore 配置	不存在时生成 .understandignore 起始文件（读取 .gitignore 去重并给出测试文件建议），等待用户确认
Phase 1	SCAN	调度 project-scanner 产出 intermediate/scan-result.json：文件清单、语言/框架、importMap；超过 100 文件时提示用户可改用子目录限定范围
Phase 1.5	BATCH	运行 compute-batches.mjs 计算语义批次，产出 batches.json
Phase 2	ANALYZE	按批次并行调度 file-analyzer，逐批写出 batch-<i>.json；随后运行 merge-batch-graphs.py 合并、规范化节点 ID 与复杂度值、去重、丢弃悬空边
Phase 3	ASSEMBLE REVIEW	调度 assemble-reviewer 审查组装图
Phase 4	ARCHITECTURE	调度 architecture-analyzer，注入语言上下文（languages/<id>.md）与框架附录（frameworks/<id>.md），产出 layers.json
Phase 5	TOUR	调度 tour-builder，产出 tour.json（含 order/title/description/nodeIds 四必填字段）
Phase 6	REVIEW	组装完整 KnowledgeGraph JSON；默认走内联确定性校验脚本，--review 则走 LLM graph-reviewer
Phase 7	SAVE	写入 knowledge-graph.json；先生成结构指纹基线（build-fingerprints.mjs）再写 meta.json（顺序颠倒会导致每次提交都被误判为全量更新）；清理中间文件（保留 scan-result.json 供增量运行复用）

增量更新机制：增量路径通过 git diff <lastCommitHash>..HEAD --name-only 得到变更文件列表，仅对这些文件重建批次；随后从旧图中删除变更文件对应的节点与关联边，把修剪后的旧节点作为 batch-existing.json 与新批次一起交给同一个合并脚本。架构层分析在增量更新时始终基于全量合并节点集重跑，以维持层级命名一致。

六、与团队共享知识图谱

图谱就是一份 JSON 文件 —— 提交一次，团队成员就可以跳过整条流水线。适合新人上手、PR 审查和 docs-as-code 工作流程。

需要提交的内容： .ua/ 底下的全部文件，除了 intermediate/ 与 diff-overlay.json（这些是本机暂存文件）。（旧项目使用 .understand-anything/ —— 如果存在的是该目录，请将下方的目录名称替换为它。）

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

保持最新： 启用 /understand --auto-update —— 一个 post-commit 挂钩会增量更新图谱，让每次提交都有对应的图谱版本。也可以在发布前手动重跑 /understand。

大型图谱（10 MB 以上）： 使用 git-lfs 追踪。

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

无需 Claude Code 也能检视仪表盘

图谱产生并提交后，团队中的任何人只需一条命令即可打开它 —— 无需 Claude Code，无需 LLM，无需 API 金钥，只需要 Node.js（>= 18）：

npx https://github.com/Egonex-AI/Understand-Anything/releases/latest/download/understand-anything-viewer.tgz /path/to/analyzed/project

终端会印出一个带令牌的 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 开发服务器达到同样的效果。

七、知识图谱 Schema 速览：13 种节点、26 种边

图谱的最终产物是一份结构化 JSON。根据 SKILL.md 末尾的 Schema 参考，节点 ID 均带类型前缀，便于精确引用：

节点类型（13 种）：

类型	说明	ID 约定
file	源代码文件	file:<relative-path>
function	函数或方法	function:<relative-path>:<name>
class	类、接口或类型	class:<relative-path>:<name>
module	逻辑模块或包	module:<name>
concept	抽象概念或模式	concept:<name>
config	配置文件（YAML、JSON、TOML、env）	config:<relative-path>
document	文档文件（Markdown、RST、TXT）	document:<relative-path>
service	可部署服务定义（Dockerfile、K8s）	service:<relative-path>
table	数据库表或迁移	table:<relative-path>:<table-name>
endpoint	API 端点或路由定义	endpoint:<relative-path>:<endpoint-name>
pipeline	CI/CD 流水线配置	pipeline:<relative-path>
schema	Schema 定义（GraphQL、Protobuf、Prisma）	schema:<relative-path>
resource	基础设施资源（Terraform、CloudFormation）	resource:<relative-path>

边类型（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；inherits/implements 为 0.9；calls/exports/defines_schema 为 0.8；imports/deploys/migrates 为 0.7；depends_on/configures/triggers 为 0.6；tested_by/documents/provisions/serves/routes 为 0.5；其余默认 0.5。

八、小结

Understand Anything 的核心价值在于：用 Tree-sitter 保证结构可重现、用 LLM 补足语义理解，通过七阶段多智能体流水线把「20 万行代码从哪看起」这一难题转化为一张可点击、可搜索、可对话的知识图谱。从使用侧看，安装只需一次（Claude Code 插件市集或 install.sh <platform> 一行命令即可覆盖 16 个平台）；从协作侧看，.ua/ 目录提交后即成为团队的「文档即代码」资产，配合 --auto-update 与 git-lfs 可长期保鲜；即便没有 Claude Code 环境，npx 一条命令也能只读地打开完整仪表盘。想继续深入，建议按顺序阅读 README.md 的多语言版本、understand-anything-plugin/skills/understand/SKILL.md 的完整流水线定义，以及 tests/ 目录下的技能与仪表盘测试用例。