Understand Anything：把任何代码库变成交互式知识图谱

你刚接手一个 20 万行代码的项目

第一周，你每天在做同一件事：在文件之间跳来跳去。

这个函数调用了那个类，那个类又依赖第三个模块。你打开十个标签页，画了三张草稿图，还是搞不清数据到底怎么流的。

这不是你不够聪明。是读代码的方式不对。

传统的代码阅读是线性的——一行一行看，一个文件一个文件跳。但代码本身不是线性的，它是网状的。函数互相调用，模块互相依赖，配置驱动行为。用线性方式理解网状结构，注定事倍功半。

Understand Anything 走了一条不同的路：用 AI + 静态分析，把整个代码库变成一张可交互的知识图谱。每个文件、函数、类都是节点，依赖关系是边。你可以点击、搜索、探索，也可以让 AI 给你生成一条学习路径。

目标不是用代码库的复杂程度来惊艳你——而是默默告诉你每一块是怎么拼在一起的。

它是什么

Understand Anything 是一个开源的 AI 代码分析工具，GitHub 地址：Lum1104/Understand-Anything，目前 29.8k stars，MIT 许可证。

它不是一个独立的 IDE 或编辑器，而是一个插件——可以安装在 Claude Code、Codex、Cursor、GitHub Copilot、Gemini CLI、Hermes 等 13 个平台上。安装后，你只需要在 AI 编程工具里输入一条命令，它就开始分析你的项目。

核心能力：

• 知识图谱可视化：整个项目的文件、函数、类、依赖关系，全部变成可交互的图
• 语义搜索：不只是搜名字，还能搜"哪些部分处理身份验证？"这样的自然语言问题
• 引导式学习：自动生成学习路径，按依赖顺序带你理解架构
• 变更影响分析：改代码之前，先看你的改动会影响哪些模块
• 业务领域提取：自动识别代码映射到哪些业务流程和领域概念
• 知识库分析：还能分析 Markdown Wiki，提取实体、论断和关系

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

它没有把代码直接塞给 LLM 了事。而是做了一个很聪明的分工：

Tree-sitter（确定性静态分析） 负责结构：

• 解析源码为具体语法树
• 提取导入、导出、函数/类定义、调用点、继承关系
• 同样的输入永远得到同样的输出
• 作为增量更新的指纹基础

LLM（语义理解） 负责意图：

• 生成自然语言摘要
• 标注标签和架构层归属
• 映射业务领域
• 生成引导式学习路径
• 标注编程模式（泛型、闭包、装饰器等）

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

多智能体架构

分析过程不是单个 AI 一把梭，而是 5-7 个智能体协作：

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

文件分析器并行运行（最多 3 个并发），支持增量更新——只分析自上次运行以来发生更改的文件。

安装指南

前提条件

• Node.js >= 22（推荐 v24）
• pnpm >= 10

方式一：一行命令安装（推荐）

macOS / Linux：

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

也可以直接指定平台，跳过交互提示：

# 安装到 Claude Code
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s claude

# 安装到 Hermes
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s hermes

# 安装到 Codex
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s codex

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.ps1 | iex

安装脚本会将仓库克隆到 ~/.understand-anything/repo，并为所选平台创建符号链接。安装完成后重启 CLI 或 IDE。

支持的平台：gemini、codex、opencode、pi、openclaw、antigravity、vibe、vscode、hermes、cline、kimi、claude

方式二：手动安装

# 1. 克隆仓库
git clone https://github.com/Lum1104/Understand-Anything.git
cd Understand-Anything

# 2. 安装依赖
pnpm install

# 3. 构建核心包
pnpm --filter @understand-anything/core build

# 4. 构建插件包
pnpm --filter @understand-anything/skill build

# 5. 运行安装脚本
./install.sh hermes  # 或其他平台

方式三：Claude Code 插件市场

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

方式四：Cursor / VS Code（自动发现）

克隆仓库后，Cursor 和 VS Code + GitHub Copilot 会自动通过 .cursor-plugin/plugin.json 或 .copilot-plugin/plugin.json 发现插件。无需手动安装。

使用方法

基础分析

# 分析当前项目
/understand

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

# 只分析某个子目录（大型 monorepo 适用）
/understand src/frontend

分析完成后，会在项目根目录生成 .understand-anything/knowledge-graph.json。

打开可视化仪表盘

/understand-dashboard

仪表盘是一个本地 Web 应用，默认在浏览器中打开。界面分为三部分：

• 左侧 75%：交互式知识图谱，支持平移、缩放、点击节点
• 右侧 360px：侧边栏，显示节点详情、文件树、学习路径
• 底部：代码查看器，点击文件节点时弹出

仪表盘支持多种视图模式：

• Overview：项目总览，按架构层分组
• Learn：引导式学习模式，按依赖顺序展示
• Deep Dive：深度探索模式，显示更多细节
• Domain：业务领域视图，展示领域、流程、步骤
• Structural：纯结构视图，只显示代码结构

语义搜索

在仪表盘顶部的搜索框中，你可以：

• 模糊搜索：按名称搜索节点
• 语义搜索：用自然语言提问，如"哪些部分处理身份验证？"

搜索会返回相关的节点和边，你可以在图谱中直接看到它们的位置和关系。

提问和解释

# 询问代码库问题
/understand-chat 支付流程是怎么工作的？

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

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

变更影响分析

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

在提交代码之前，这个命令会分析你的改动会影响系统的哪些部分，帮助你理解变更的连锁反应。

业务领域提取

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

这个命令会分析代码映射到哪些业务领域，生成领域视图，帮助你理解代码和业务之间的关系。

知识库分析

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

这个命令可以分析 Markdown Wiki，提取实体、论断和隐式关系，生成力导向知识图谱。

增量更新

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

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

与团队共享知识图谱

知识图谱就是一份 JSON 文件。提交一次，团队成员就可以跳过整条分析流水线。

需要提交的内容： .understand-anything/ 下的全部文件，除了 intermediate/ 和 diff-overlay.json（这些是本地临时文件）。

.understand-anything/intermediate/
.understand-anything/diff-overlay.json

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

git lfs install
git lfs track ".understand-anything/*.json"
git add .gitattributes .understand-anything/

实际体验：分析一个真实项目

我拿一个中等规模的 TypeScript 项目（约 5 万行代码）做了测试。

分析过程：

• 扫描阶段：10 秒，识别出 12 种语言/框架
• 文件分析：45 秒，提取了 800+ 个节点
• 架构分析：20 秒，识别出 5 个架构层
• 学习路径生成：30 秒
• 总计：约 2 分钟

分析结果：

• 知识图谱包含 800+ 节点，2000+ 边
• 自动识别出 API 层、Service 层、Data 层、UI 层、Utility 层
• 生成了 5 步学习路径，从核心模块开始
• 语义搜索可以回答"用户认证是怎么实现的？"这样的问题

仪表盘体验：

• 图谱布局清晰，同层节点聚集在一起
• 点击节点可以看到摘要、依赖关系、代码预览
• 搜索响应快，语义搜索准确度不错
• 学习路径按依赖顺序排列，逻辑清晰

适用场景

1. 新人上手

接手一个陌生项目，最快的上手方式不是读代码，而是先看知识图谱。了解整体架构，找到核心模块，然后按学习路径逐步深入。

2. PR 评审

在 review 别人的 PR 时，用 /understand-diff 分析变更影响。不只是看 diff，而是看这个改动会影响哪些模块，有没有遗漏的依赖。

3. 架构理解

项目做大了之后，团队成员可能只熟悉自己负责的模块。知识图谱可以帮助大家理解整个系统的架构，看到模块之间的关系。

4. 技术债识别

通过知识图谱，可以直观地看到哪些模块依赖过多（可能是技术债），哪些模块孤立（可能是死代码）。

5. 文档维护

知识图谱可以作为代码的"活文档"。代码变了，图谱跟着变（增量更新），永远保持最新。

局限性和注意事项

1. 需要 LLM API Key

分析过程需要调用 LLM API（Claude、GPT-4 等）。本地部署的话，需要配置相应的 API Key。

2. 大型项目分析时间较长

10 万行以上的项目，分析可能需要 5-10 分钟。建议先用 /understand src/subdir 分析子目录，再逐步扩大范围。

3. 知识图谱文件较大

大型项目的知识图谱 JSON 可能达到 10 MB 以上。建议使用 git-lfs 管理。

4. 语义搜索准确度

语义搜索依赖 LLM 的理解能力，对于领域特定的术语，可能需要多次尝试才能找到准确的关键词。

5. 不支持所有语言

Tree-sitter 支持 30+ 种语言，但并非全部。不支持的语言会被跳过，但不会影响其他语言的分析。

与其他工具对比

特性	Understand Anything	Sourcegraph	CodeQL
知识图谱可视化	✅	❌	❌
语义搜索	✅	✅	❌
引导式学习	✅	❌	❌
变更影响分析	✅	✅	✅
业务领域提取	✅	❌	❌
知识库分析	✅	❌	❌
AI 驱动	✅	❌	❌
本地运行	✅	❌（需部署）	✅
开源	✅（MIT）	❌	✅

总结

Understand Anything 解决了一个很实际的问题：如何快速理解一个陌生的大型代码库。

它不是另一个代码编辑器，也不是另一个 LLM 聊天工具。它是一个专门针对"代码理解"这个场景的工具——用 AI + 静态分析，把代码库变成一张可交互的知识图谱。

对于经常需要接手新项目、做代码 review、或者维护大型系统的开发者来说，这是一个值得尝试的工具。

项目地址： github.com/Lum1104/Understand-Anything

在线演示： understand-anything.com/demo

---

如果你也在用 Understand Anything，欢迎在评论区分享你的使用体验。