Understand-Anything 中文实践指南：将代码库转化为可探索的知识图谱

Understand-Anything 是一个多智能体（multi-agent）代码分析插件：它把任意代码库解析为包含文件、函数、类与依赖关系的知识图谱，并提供可平移、可缩放、可搜索的交互式仪表盘，帮助你从全局视角理解系统结构，而不是"盲读代码"。本文基于仓库的简体中文文档 READMEs/README.zh-CN.md 展开，覆盖安装、/understand 全流程、多平台适配、团队共享与底层 Tree-sitter + LLM 混合分析原理。读完后，你可以独立完成：安装插件并生成图谱、用 --language zh 产出中文内容、配置增量更新与 post-commit 钩子、将图谱提交给团队、以及不依赖 LLM 地离线查看仪表盘。

核心功能一览

项目定位一句话概括：把任意代码库、知识库或文档转化为可探索、可搜索、可对话的交互式知识图谱，支持 Claude Code、Codex、Cursor、Copilot、Gemini CLI 等多平台。具体能力包括：

能力	说明
探索代码结构图	每个文件、函数、类都是可点击、可搜索、可探索的节点；选择任意节点即可查看摘要、依赖关系和引导式学习路径
理解业务逻辑	领域视图以水平图展示领域、流程和步骤，看代码如何映射到真实业务流程
分析知识库	/understand-knowledge 指向一个 Karpathy 模式的 LLM Wiki，获得带社区聚类的力导向知识图谱；确定性解析器从 index.md 提取 wikilinks 和分类，LLM 代理再发现隐式关系、提取实体与论断
引导式学习	自动生成架构学习路径，按依赖顺序学习
语义搜索	模糊搜索 + 语义搜索，例如"哪些部分处理身份验证？"
变更影响分析	提交前查看更改会影响系统的哪些部分，理解连锁反应
用户角色自适应 UI	按用户类型（初级开发 / 项目经理 / 高级用户）调整详细程度
层级可视化	按架构层级自动分组——API、服务、数据、UI、系统工具——并附颜色编码图例
语言概念	12 种编程模式（泛型、闭包、装饰器等）在上下文中逐一解释

对应的仪表盘技术栈可在 understand-anything-plugin/packages/dashboard/package.json 中确认：React 19 + TypeScript、React Flow（@xyflow/react）、Zustand、TailwindCSS v4，布局引擎包含 dagre、ELK（elkjs）、d3-force，并引入 graphology-communities-louvain 实现社区聚类。

快速开始（以 Claude Code 为例）

1. 安装插件

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

使用本地模型？ 出于隐私或企业需求，可以将平台指向本地模型提供方（例如 Ollama）——按对应平台的集成指南更改模型提供方即可。

2. 分析你的代码库

/understand

多智能体架构会扫描项目、提取函数 / 类 / 依赖、构建知识图谱并保存至 .ua/knowledge-graph.json。已经有 .understand-anything/ 目录的项目会继续使用该目录——存在时它仍是数据目录，因此无需迁移（这一规则在 CLAUDE.md 的 Conventions 一节也有同样表述）。

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

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

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

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

--language 参数会影响三处内容：知识图谱中的节点摘要和描述、Dashboard UI 的标签 / 按钮 / 提示、导览路线的解释说明。

技能定义 understand-anything-plugin/skills/understand/SKILL.md 对 --language 给出了更完整的说明：它接受 ISO 639-1 代码（zh、ja、ko、en、es、fr、de 等）或友好名称（chinese、japanese 等），并支持 zh-TW、zh-HK、pt-BR 等地区变体；解析后的语言偏好会写入 $UA_DIR/config.json，保证后续增量更新时语言一致。此外，若未显式指定 --language，首次运行会检测会话的主导语言——若为英文则静默使用 en，若非英文则一次性向你确认后再写入配置。

3. 打开数据看板

/understand-dashboard

打开交互式网页数据看板：代码库以图表形式呈现，按架构层级颜色编码，支持搜索和点击。选择任意节点即可查看其代码、关系以及简明解释。根据 SKILL.md 的流程，/understand 在最终图谱通过校验后会自动触发 /understand-dashboard，无需手动执行第 3 步。

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 钩子，每次提交自动增量更新
/understand --auto-update

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

/understand 命令的完整参数集（来自 SKILL.md 的 Options 一节）：

参数	作用
--full	强制全量重建，忽略已有图谱
--auto-update	开启提交时自动更新（向 $UA_DIR/config.json 写入 autoUpdate: true）
--no-auto-update	关闭自动更新（写入 autoUpdate: false）
--review	运行完整的 LLM graph-reviewer，替代内联确定性校验
--language <lang>	指定所有文本内容的生成语言，默认 en
--exclude <patterns>	逗号分隔的 glob 排除模式（支持 gitignore 语法与 ! 否定），优先级最高；新增排除模式需配合 --full 生效
目录路径	分析指定目录（如 ../other-project）而非当前目录

/understand 的七阶段流水线（源码视角）

README 只说"扫描 → 提取 → 构建图谱"，而 SKILL.md 定义了完整的七阶段流程，每个阶段都有明确的中间产物与决策逻辑，这也是理解"增量更新为什么便宜"的关键：

1. Phase 0（Pre-flight）：解析目标目录、检测 git worktree 并自动重定向到主仓库（避免 Claude Code 的临时 worktree 销毁数据目录）、确保插件已构建（pnpm --filter @understand-anything/core build）、解析数据目录 $UA_DIR（.understand-anything/ 存在则优先，否则用 .ua/）、读取 meta.json 中的 gitCommitHash 决定走全量还是增量路径；
2. Phase 0.5：生成 / 确认 .understandignore 排除规则；
3. Phase 1（SCAN）：派发 project-scanner 子代理，输出 scan-result.json——文件清单（含行数与 fileCategory 分类：code、config、docs、infra、data、script、markup）、语言与框架检测、以及预先解析好的项目内 importMap；超过 100 个文件时会提示改用子目录参数缩小范围；
4. Phase 1.5（BATCH）：运行 compute-batches.mjs 将文件划分为语义批次，并附跨批次邻居符号表，提升跨批次边的置信度；
5. Phase 2（ANALYZE）：每批派发一个 file-analyzer 子代理，最多 5 个并发，产出 batch-<i>.json；随后 merge-batch-graphs.py 一次性合并、归一化节点 ID、去重、丢弃悬空边，并运行 tested_by 链接器规范化测试覆盖边；
6. Phase 3–5：assemble-reviewer 复审组装图 → architecture-analyzer 识别架构层（输出 layers.json）→ tour-builder 生成引导式学习路径（输出 tour.json），两者都经过确定性归一化（解包 envelope、重命名遗留字段、补前缀、丢弃悬空引用）；
7. Phase 6–7（REVIEW + SAVE）：默认走内联确定性校验脚本（校验必填字段、悬空边、节点重复、孤立节点并输出统计），仅在 --review 时才派发 LLM graph-reviewer；通过后将图谱写入 $UA_DIR/knowledge-graph.json，并在写 meta.json 之前先生成结构指纹基线——这是自动增量更新的比较基础，缺了它每次提交都会被误判为需要全量更新。

增量更新路径（Phase 2 的 Incremental update path）用 git diff <lastCommitHash>..HEAD --name-only 得到变更文件列表，只对变更文件重算批次，再从旧图中删除对应节点与边后与新批次合并。scan-result.json 会被刻意保留到 Phase 7 清理之后，因为后续增量运行可以跳过 Phase 1 SCAN，显著省掉重复扫描的开销。

图谱的数据模型也在 SKILL.md 的 Reference 一节有完整定义：13 种节点类型（file、function、class、module、concept、config、document、service、table、endpoint、pipeline、schema、resource，各有 type:<path> 形式的 ID 约定）和 26 种边类型（按 Structural / Behavioral / Data flow / Dependencies / Semantic / Infrastructure / Schema-Data 七个类别组织），并规定了边权重约定（如 contains = 1.0、calls = 0.8、tested_by = 0.5）。图谱输出格式遵循 docs/benchmarks/large-repo-report-1.0.0.schema.json 所示的 1.0.0 版本契约，包含 version、project（名称、语言、框架、描述、分析时间、gitCommitHash）、nodes、edges、layers、tour。

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

README 对分工的表述是：把确定性的事情交给静态分析，把需要语义理解的事情交给 LLM。

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

正因为这个分工，图谱在结构层面是可复现的（同样的代码总是产生同样的边），同时在语义层面又能捕捉意图——一个文件是"为了什么"存在，而不仅仅是它 import 了什么。

从源码结构看，这一分工落在 packages/core 的插件体系上：understand-anything-plugin/packages/core/src/plugins/tree-sitter-plugin.ts 基于 web-tree-sitter（WASM） 而非原生绑定（CLAUDE.md 的 Gotchas 一节说明原因是原生绑定在 darwin/arm64 + Node 24 上失败）。languages/configs/index.ts 注册了约 45 种语言的配置（每种配置定义扩展名、概念词表、文件模式与入口点识别规则），plugins/extractors/ 提供 12 种语言的专用结构提取器（C++、C#、Dart、Go、Java、Kotlin、PHP、Python、Ruby、Rust、Scala、Swift、TypeScript），plugins/parsers/ 则解析 Dockerfile、env、GraphQL、JSON、Makefile、Markdown、Protobuf、Shell、SQL、Terraform、TOML、YAML 等非代码文件——这正是"节点类型不只是 file/function/class，还有 config、service、pipeline、table、endpoint"的原因。

多智能体架构

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

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

这些 agent 定义位于 understand-anything-plugin/agents/ 目录（project-scanner.md、file-analyzer.md、graph-reviewer.md、tour-builder.md、domain-analyzer.md、article-analyzer.md 等）。文件分析器并行运行，支持增量更新——仅重新分析自上次运行以来发生更改的文件。

多平台支持

Understand-Anything 可在多个 AI 编码平台上运行，各平台的安装方式不同。

Claude Code（原生）

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

一行命令安装（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 源码可以看到其内部的平台表：每个平台条目是 id|skills目标目录|链接风格 三元组（如 codex|$HOME/.agents/skills|per-skill、cline|$HOME/.cline/skills|folder），支持 --update（git pull --ff-only 更新现有 checkout）与 --uninstall <platform>，并允许用环境变量 UA_REPO_URL / UA_DIR 覆盖克隆地址与目标目录。

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

• 支持的 <platform> 取值：gemini、codex、opencode、pi、openclaw、antigravity、vibe、vscode、hermes、cline、kimi、nanobot、kiro
• 后续更新：./install.sh --update
• 卸载：./install.sh --uninstall <platform>

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 后两者均可使用。

多平台兼容总表

平台	状态	安装方式
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
Nanobot	✅ 支持	install.sh nanobot
Kiro CLI / IDE	✅ 支持	install.sh kiro

与团队共享知识图谱

图谱就是一份 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 调用，也不会有任何数据离开你的机器。

understand-anything-plugin/packages/viewer/README.md 补充了 viewer 的实现细节：它支持 --port <n>（默认 5173，端口占用时自动递增）和 --no-open 选项，服务绑定在 127.0.0.1 并受一次性访问令牌保护；tarball 由 pack:release 脚本构建，内嵌编译后的 dashboard dist/，是一个零依赖的自包含包。

如果你是从克隆的仓库工作：先执行 pnpm install && pnpm --filter @understand-anything/core build，再运行 GRAPH_DIR=/path/to/analyzed/project pnpm dev:dashboard，即可通过 Vite 开发服务器实现同样的效果。

环境要求与本地开发

• 运行 viewer：Node.js >= 18（见 understand-anything-plugin/packages/viewer/package.json 的 engines 字段）；
• 开发插件本体：Node.js >= 22、pnpm >= 10（由根 package.json 的 packageManager 字段固定为 pnpm 10.6.2）；
• 仓库是 pnpm workspaces monorepo：understand-anything-plugin/packages/core 是共享分析引擎（类型、持久化、tree-sitter、搜索、schema、tour、插件注册），packages/dashboard 是 React 仪表盘，skills/ 与 agents/ 是技能与代理定义（见 CLAUDE.md 的 Architecture 一节）。

常用命令（与 READMEs/README.zh-CN.md 贡献一节一致）：

pnpm install
pnpm --filter @understand-anything/core build   # 构建 core 包
pnpm --filter @understand-anything/core test    # 运行 core 测试
pnpm test                                       # 运行全部测试（skill 测试位于仓库根 tests/skill/）
pnpm dev:dashboard                              # 启动仪表盘开发服务器

贡献流程：Fork 项目 → 新建分支（git checkout -b feature/my-feature）→ 运行测试（pnpm --filter @understand-anything/core test）→ 提交更改并创建 PR；重大变更请先提交 issue 讨论。

小结

Understand-Anything 的设计可以归纳为三条主线：结构上可复现（Tree-sitter 静态解析 + 结构指纹，同样的代码永远产生同样的边，增量更新只重算变更文件）、语义上靠 LLM（多智能体分工产出摘要、架构层、引导路径、领域映射与图谱校验）、产物上纯 JSON（.ua/knowledge-graph.json 可提交、可共享、可用零依赖 viewer 离线查看）。对刚接手一个大型代码库的开发者，最短路径是：安装插件 → /understand --language zh → /understand-dashboard 浏览结构图与领域视图 → 用 /understand-chat 提问、/understand-diff 评估改动影响，并配合 /understand --auto-update 让图谱随提交自动保持最新。