接手一个陌生项目,20万行代码摆在眼前,从哪看起?

大多数人的做法是翻 README、找入口文件、grep 关键函数名,一个个跳转。运气好半天摸清脉络,运气差一周还在迷路。

Understand-Anything 换了个思路:用多 Agent 流水线扫描整个代码库,提取文件、函数、类、依赖关系,生成一张交互式知识图谱。你可以在浏览器里拖拽、搜索、点击任意节点查看说明。截至今天,GitHub Trending 日榜第一,单日 4600+ star,总星数 36000+。

这篇文章记录我的安装和实测过程,包括踩到的坑。

它干了什么

一句话:把代码变成可视化的知识网络。

具体来说,它做了两件事:

静态分析(Tree-sitter)-- 解析源码的语法树,提取 import、export、函数定义、类继承、调用关系。同样的代码跑多少次,结果一样。

语义分析(LLM)-- 读解析后的结构加上源码原文,生成自然语言描述:这个文件是干什么的、属于哪个架构层、业务域是什么。

分析完之后,结果存成 JSON 文件,放在项目根目录的 .understand-anything/ 下。

支持哪些平台

这不是 Claude Code 专属工具。它支持 15 个平台:

Claude Code(原生插件市场)、Cursor(自动发现)、VS Code + GitHub Copilot、Copilot CLI、Codex、OpenCode、OpenClaw、Gemini CLI、Trae、Cline、Hermes、KIMI CLI、Pi Agent、Vibe CLI、Antigravity。

基本上你在用的 AI 编程工具,它都能接。

安装过程

我用 Claude Code 测试。两条命令:

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

用其他平台的话,走安装脚本:

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

# 指定平台,比如 Codex
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s codex

安装脚本会把仓库克隆到 ~/.understand-anything/repo,然后创建对应平台的符号链接。装完重启 CLI 或 IDE。

如果你用 Cursor,更简单--克隆这个仓库,打开项目,Cursor 会通过 .cursor-plugin/plugin.json 自动发现插件,不用手动安装。

实际使用

安装好之后,进入你想分析的项目目录,跑一条命令:

/understand

等它跑完。多 Agent 流水线会依次扫描项目文件,时间取决于项目大小。一个中等规模的项目(几千个文件)大概需要几分钟。

分析结果存在 .understand-anything/knowledge-graph.json 里。然后打开 Dashboard:

/understand-dashboard

浏览器会弹出一个交互页面。每个文件、函数、类都是图上的一个节点,颜色按架构层分--API 层、Service 层、Data 层、UI 层、工具类,一目了然。

点击任意节点,右侧面板展示:源码位置、自然语言描述、上下游依赖关系。

几个实用命令

除了基础的图谱生成,还有几个值得记住的命令:

# 问问题,比如"支付流程怎么走的"
/understand-chat How does the payment flow work?

# 分析当前改动的影响范围
/understand-diff

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

# 生成新人入职指南
/understand-onboard

# 提取业务域知识(域、流程、步骤)
/understand-domain

# 只分析某个子目录(大型 monorepo 用)
/understand src/frontend

/understand-diff 比较实用。改了几个文件之后,跑一下就能看到哪些模块会受影响。比 git diff 看到的信息多得多--它追踪的是函数调用链,不只是文件变更。

中文支持

加 --language zh 参数,生成的节点描述和 Dashboard UI 都是中文:

/understand --language zh

支持的语言:en(默认)、zh、zh-TW、ja、ko、ru。

增量更新

第一次跑完整分析之后,后续再跑 /understand 默认走增量模式,只重新分析改过的文件。它用 fingerprint 做变更检测,没改的文件直接跳过。

想让它每次 commit 自动更新:

/understand --auto-update

这会注册一个 post-commit hook,每次提交后自动增量更新知识图谱。

团队协作

知识图谱本质上就是 JSON 文件,可以提交到 Git 仓库。新同事 clone 项目后直接打开 Dashboard 看,不用重跑分析流水线。

提交时注意排除两个文件:

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

这两个是本地临时文件。

如果图谱文件超过 10MB(大型项目很常见),建议用 git-lfs:

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

踩坑记录

说几个我遇到的问题:

1. 大项目首次分析慢

几万个文件的项目首次分析需要不少时间,因为每个文件都要过 LLM。不过只有第一次慢,后面增量更新很快。可以先用 /understand src/核心目录 缩小范围试试水。

2. 需要 API 额度

语义分析部分需要调 LLM,走的是你当前 AI 编程工具的 API。Claude Code 用户注意 token 消耗,大项目一次分析可能吃掉不少额度。

3. .gitignore 没覆盖的垃圾文件

如果项目里有大量生成文件(编译产物、node_modules 之类),建议先确认 .gitignore 配置正确。Understand-Anything 会参考 .gitignore 跳过这些文件,但如果你的 .gitignore 不全,分析结果会混入噪音。

跟 CodeSee、Sourcegraph 比呢

市面上做代码可视化的不少。Understand-Anything 的区别在于每个节点都带自然语言解释——不只是画个依赖图给你看，而是告诉你“这个文件是干什么的、它为什么依赖那边那个模块”。加上 /understand-chat 可以直接问问题，用起来更像有个熟悉项目的同事在旁边讲解。

它是开源的，GitHub 上能拿到全部代码，不绑定某个平台。

值不值得用

如果你经常需要接手别人的项目,或者团队有新人入职,Understand-Anything 省的时间是实打实的。花几分钟跑一次分析,换来的是可以反复查看的交互式文档,比翻代码效率高。

自己的项目用处没那么大，毕竟自己写的代码不需要画图才能看懂。但半年没碰的项目重新捡起来，跑一下 /understand 确实能省不少翻代码的时间。

GitHub 地址:https://github.com/Lum1104/Understand-Anything

star 还在涨,感兴趣的可以试试。