Understand-Anything 使用指南：把代码库与知识库变成可探索图谱

普通代码图谱只给你文件、函数和边。问题在于：你看到一团节点后，仍然不知道从哪里开始。

Understand-Anything 想固化的是：

• 结构：文件、函数、类、模块、文档、API、pipeline
• 关系：imports、contains、calls、depends_on、documents、related
• 意义：节点摘要、复杂度、标签、架构层
• 学习路径：guided tour / onboarding
• 业务视角：domain / flow / step
• 变更影响：diff impact

一句话：它把「AI 对复杂系统的理解」固化成 .understand-anything/knowledge-graph.json，成为可复用的 知识库工件，而不是每次从零让模型重读仓库。

Claude Code 原生

1
/plugin marketplace add Lum1104/Understand-Anything
2
/plugin install understand-anything

项目目录里：

1
/understand
2
/understand-dashboard

多平台安装脚本

macOS / Linux：

1
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash

直接指定平台：

1
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s codex
2
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s pi
3
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s vscode

官方支持 Claude Code、Cursor、VS Code + Copilot、Codex、OpenCode、Gemini CLI、Pi Agent 等。本地建议 Node.js ≥ 22、pnpm ≥ 10。这些入口本质上是挂在 agent harness 上的 agent skills，不是独立桌面应用。

1
cd /path/to/project

然后：

1
/understand

产物通常在：

1
.understand-anything/knowledge-graph.json
2
.understand-anything/meta.json
3
.understand-anything/config.json

过程大致是：扫描文件 → 检测语言框架 → tree-sitter 抽结构 → agent 分析语义 → 生成节点边与架构层 → guided tour → 校验完整性。

常用参数：

| 命令 | 作用 | | --- | --- | | /understand --full | 强制全量重建 | | /understand --language zh | 中文摘要与 dashboard 文案 | | /understand src/frontend | 只分析子目录，适合 monorepo | | /understand --auto-update | 提交后增量更新 | | /understand --review | 更完整的 LLM graph reviewer |

1
/understand-dashboard

本地会起 Vite server。URL 必须带 ?token=，否则接口会要求 Access Token。

先看 layers，不要先被节点数量吓住。推荐顺序：

1. 项目名 / 语言 / 框架
2. layer 列表
3. 每层关键节点
4. Learn / Guided Tour
5. 搜索你关心的概念
6. 再点具体文件或函数

节点常见字段：id、type、name、filePath、summary、tags、complexity。边常见类型：imports、contains、calls、depends_on、documents、related、categorized_under。

这套读图方式，本质上是把 可视分析 用到代码与知识结构上：overview first，再 zoom / filter，再 details-on-demand。

| 技能 | 用途 | | --- | --- | | /understand-chat | 基于 graph 问业务流程、认证模块、数据流 | | /understand-explain | 结合全局关系解释某个文件/函数 | | /understand-diff | 改动 blast radius、affected layers、risk | | /understand-onboard | 生成新人入门文档 | | /understand-domain | 抽出 domain / flow / step 业务图 | | /understand-knowledge | 分析 Karpathy-pattern wiki / 论文知识库 |

适合问：登录流程在哪、哪些文件是新手必读、哪些节点复杂度最高。不适合问：图谱没覆盖的最新未分析改动、纯运行时性能、外部服务黑箱细节。

知识库需要 Karpathy-pattern wiki：

1
wiki-root/
2
  index.md
3
  log.md
4
  AGENTS.md 或 CLAUDE.md
5
  raw/
6
    source.md
7
  Concept A.md
8
  Concept B.md

要求：

• 必须有 index.md
• 多个 .md 文件
• 用 [[wikilink]] 连接
• index.md 的二级标题会变成 category / layer

不要把整篇论文塞进一个长 note。拆成概念节点后，图谱才清楚：Architecture、Attention、Representation、Evidence 分层。

建议提交：

1
.understand-anything/knowledge-graph.json
2
.understand-anything/meta.json
3
.understand-anything/config.json

不要提交 intermediate 与 diff-overlay。图谱超过 10MB 时用 git-lfs。

常见坑：

1. 没 graph：先 /understand 或 /understand-knowledge
2. dashboard 无数据：URL 丢了 token
3. invalid graph：目录指错或 JSON 不完整
4. unresolved wikilink 太多：文件名、H1、index 链接不一致
5. 大项目慢：分析子目录 + .understandignore 排除 node_modules/、dist/ 等

代码库

1
/understand --language zh
2
/understand-dashboard
3
/understand-onboard
4
/understand-chat 这个项目最核心的模块是什么？
5
/understand-diff

论文

1. 在笔记库把论文拆成概念 note
2. 写 index.md 分组
3. [[wikilink]] 连接
4. /understand-knowledge /path/to/wiki
5. dashboard 对照补缺失概念
6. 把 learning path 写回笔记库

PR review

1
/understand
2
# 改代码
3
/understand-diff
4
/understand-chat 这次改动可能影响哪些模块？

Understand-Anything 最强的不是「画图」，而是把代码库、知识库、论文材料转成 AI 可查询、可解释、可复用的知识图谱。它适合挂在 coding agent 工作流里：先固化结构理解，再聊天、解释、做 diff，而不是每次把整个仓库重新塞进上下文。

• 官网与 Demo：https://understand-anything.com/
• GitHub：https://github.com/Lum1104/Understand-Anything
• 同系列：用它理解 Transformer 架构的最佳实践