上周 GitHub 上冒出一个叫 Understand-Anything 的项目，一天涨了近两万星。它声称能把任何代码变成「交互式知识图谱」，还能用自然语言问它问题。作为一个被老项目代码折磨过的后端，我立刻点进去看了。

今天这篇文章就聊聊这个东西到底怎么用、比现有方案好在哪、以及我踩到的坑。保证你看完能判断：自己的项目需要用，还是只是图个新鲜。

这工具解决什么问题

你可能也有过这种经历：接到一个维护任务，代码仓库扔你脸上，文档要么没有要么过时。你打开 IDE，从入口文件开始，一路点着引用跳转，两个小时后还在同一个函数里打转。

传统工具能帮上忙吗？

• IDE 的“查找引用”只能给你一个扁平的列表。
• 文档生成器（如 Docusaurus）需要你手动写注释。
• 代码搜索（如 Sourcegraph）能搜到文本，但看不全调用链。

Understand-Anything 的做法是：先用静态分析抽取出代码里的函数、类、模块和它们之间的调用/继承/引用关系，然后把这些关系渲染成一个可拖拽、可缩放的知识图谱。更关键的是，它嵌入了 LLM，让你可以用自然语言提问，比如“这个模块的入口函数在哪里？”、“哪些地方用到了这个 API？”——它会在图上高亮并给出解释。

核心功能与演示

我找了一个实际项目来跑（一个我自己的小 Node.js 微服务，大概 30 个文件）。步骤如下：

1. 安装 CLI：npm install -g @lum1104/understand-anything（需要 Node 18+）
2. 在项目根目录执行：understand-anything ./
3. 等待几秒钟，CLI 会分析代码并生成一个 JSON 数据文件，然后自动在本地启动一个 Web 服务，打开浏览器就看到图了。

（终端里执行命令的输出截图）

下图是我项目的部分模块图（右键在新标签打开看大图）：

（浏览器里展开几个模块的截图，显示节点和连线）

可以看到每个文件是一个节点，箭头表示引用或调用关系。双击节点可以展开内部函数，左侧搜索栏可以输入函数名高亮定位。最上面的文本输入框就是“问问题”的地方。

我测试了三个问题：

• “What is the main entry point?” → 自动把 index.ts 高亮，并显示 app.listen(3000) 的代码片段。
• “Which modules depend on config?” → 图中高亮所有引用 config.ts 的节点，并按依赖数量排序。
• “Show me all async functions” → 图过滤出所有带 async 的函数节点，并标记调用链。

说实话，前两个问题很准，第三个偶尔漏掉一些不带 async 关键字的 Promise 函数。但总体来说，对一个 30 文件的项目，效果已经超过我手动读代码了。

和同类方案的区别

我拿它和两个常用工具做了对比：

1. Sourcegraph（v5.3）

• 优势：搜索速度快，支持精确匹配和正则，适合大型仓库。
• 劣势：只能看到“哪些文件包含了这个函数”，看不出调用上下文，更不提供可视化图。
• Understand-Anything 胜在：图本身就是关系网，一眼看出谁依赖谁。

2. CodeGraph（npm上另一个包 code-graph，star 500+）

• 它也生成依赖图，但只输出静态图片（SVG 或 PNG），没有交互，不能搜索或提问。
• Understand-Anything 多了交互、搜索和 LLM 问答，但代价是要启动一个 Web 服务，占用更多内存。

3. IDE 插件（如 VS Code 的 Dependency Graph）

• 嵌入 IDE 方便，但图往往只针对单个文件或单层调用。
• Understand-Anything 是全局的，而且可以脱离 IDE 使用（比如在 CI 中生成报告）。

我的观点：如果你只是需要快速找代码位置，Sourcegraph 足够；如果你要给团队做架构讲解，Understand-Anything 的交互图更直观；如果你要一次性生成静态文档，CodeGraph 就够了，不用多一个后台进程。

局限与注意事项

大型项目性能堪忧

我试着把它跑在一个有 2000+ 文件的 Java 微服务项目上（提前告诉我它支持 TypeScript/JavaScript，对 Java 还只是实验性）。CLI 跑了 3 分钟后还没出结果，直接 OOM 了。GitHub 上的 issue 里也有人说超过 500 文件建议分批处理。所以如果你要分析企业级代码库，目前可能撑不住。

LLM 的幻觉问题

当问复杂逻辑问题时，比如“这段话句为什么会慢？”它回答了一大堆，但全是泛泛而谈（缓存、索引、异步）。其实我的代码里有一处死循环，它完全没识别出来。LLM 部分更像是锦上添花，不是可靠的分析工具。

语言支持有限

官方明确支持 TypeScript/JavaScript。Python、Java、Go 还在实验阶段。README 里说“能用，但图不完整”。我简单试了 Go 项目，函数节点识别了，但接口实现关系没画出来。

图形交互易用性一般

图节点多了以后非常乱，手动布局了好一会儿才看得清。虽然有“自动布局”按钮，但效果还是不如 Gephi 这类专业可视化工具。

快速上手步骤（3 分钟）

如果你决定在自己的小项目（<50 文件）上试试，按这个来：

# 1. 确保 Node >=18
node -v

# 2. 全局安装
npm install -g @lum1104/understand-anything

# 3. 进入项目目录
cd your-project

# 4. 分析（默认递归所有文件）
understand-anything .

# 5. 等待 CLI 输出 “Graph server running at http://localhost:3001”，打开浏览器
# 6. 在搜索框里输入函数名，或点击节点查看代码
# 7. 想提问就直接在底部输入框打字

如果你只想生成 JSON 数据，不加 Web 服务：

understand-anything . --format json > graph.json

然后可以用其他工具加载这个 JSON 做进一步处理。

我的最终评价

Understand-Anything 是一个很好的「入门代码理解」工具，尤其适合用来快速认识陌生的中小型项目。它的交互图和 LLM 问答比单纯的文件搜索直观得多。但别指望它能代替你读代码，特别不要在大型项目或生产环境里依赖它做 bug 分析。

作为开源项目，它还很年轻，性能、语言支持和稳定性都有提升空间。如果你手上正好有个 100 文件以内的 TypeScript 项目需要快速理解，花 5 分钟跑一次是值得的。如果你的项目是上千文件的 Java 恐龙，还是老老实实先用 Sourcegraph，等它迭代几版再试。

(一个表格，比较 Understand-Anything, Sourcegraph, CodeGraph, IDE插件的特性)