上周我接手一个同事留下的 React 项目，代码量不大，但文件间依赖关系错综复杂，每个组件 props 传递路径全靠脑补。我花了一整天画 UML 图，结果第二天需求变更，图又废了。

如果你也经历过这种痛苦，今天这个开源项目也许会改变你的工作方式。

code knowledge graph interactive visualization

项目叫 Understand-Anything，是个 TypeScript 写的 CLI 工具，能把任何代码文件夹变成交互式知识图谱，并且支持自然语言搜索和提问。GitHub 上今天新增了 20972 个 star，增长曲线几乎垂直。

它解决了什么问题？

理解别人的代码永远是开发者的日常噩梦。传统做法要么靠文档（往往过时），要么靠人肉脑内构建依赖图。更有效的方式是直接看代码结构，但 IDE 的类图/调用关系虽然能生成，很难回答“这个模块到底做什么”这样的语义问题。

Understand-Anything 结合了 LLM 和代码解析，把代码库中的实体（函数、类、模块、文件）以及它们之间的关系（调用、继承、导入）提取出来，组织成图结构。然后你可以在网页上交互探索，甚至直接问“用户登录逻辑在哪”这样的问题。

interactive knowledge graph exploration

核心功能和亮点

根据 README，它支持的主流 AI 工具包括：Claude Code、Codex、Cursor、Copilot、Gemini CLI 等。本质上是把代码分析结果以图数据格式输出，然后结合 LLM 的问答能力实现智能搜索。

我试了一下，实际操作很简洁：

bash
1 
npx understand-anything ./my-project --output ./graph.html

运行后会生成一个 HTML 文件，浏览器打开就能看到可拖拽、缩放、点击展开的节点图。每个节点代表一个文件或函数，边代表依赖或调用关系。点击节点会展示代码片段，双击节点可以展开更多细节。

更让我惊喜的是它的搜索栏：支持自然语言查询。例如输入“哪个函数处理用户输入”，它会基于图谱的语义和 LLM 推理返回相关节点路径。这种方式比纯文本搜索更精准，因为它利用了图结构中的上下文关系。

官方例子中展示了分析一个 Express 应用的效果：中间件函数、路由、模型之间的关系一目了然，甚至能问“这个 POST 路由调用了哪些模型方法”，图谱会高亮路径。

代码示例：实际跑一个 TodoMVC 项目

我拿了一个标准的 React TodoMVC 来测试。项目结构如下：

text
1 2 3 4 5 6 7 8 
├── src
│   ├── App.jsx
│   ├── components
│   │   ├── TodoList.jsx
│   │   ├── TodoItem.jsx
│   │   └── AddTodo.jsx
│   └── utils
│       └── todoStorage.js

执行命令：

bash
1 
npx understand-anything@latest ./todomvc -o todomvc-graph.html

（注意：首次运行会提示安装依赖，大约 2-3 分钟。之后会调用 LLM API，需配置 OPENAI_API_KEY 环境变量或使用支持的其他模型。我在 .env 里设置了 ANTHROPIC_API_KEY 用 Claude。）

生成后的图谱中，App.jsx 作为根节点连接到三个组件，todoStorage.js 被所有组件引用。我可以点击 TodoList.jsx 看到其代码摘要，并询问“哪些组件直接修改了本地存储”，图谱会高亮 TodoItem.jsx 和 AddTodo.jsx。

这个能力在大型项目中更有价值，但小项目也能验证原理。

和同类项目的区别

市面上已有一些代码可视化工具，比如 CodeSee、Sourcegraph、以及传统的 UML 生成器。我来对比几个关键点：

特性 Understand-Anything CodeSee Sourcegraph
视图类型 交互式知识图谱 代码地图（侧重文件依赖） 代码搜索 + 引用图
自然语言查询 ✅ 强（结合 LLM） ❌ 仅搜索文件名 ✅ 代码搜索（但无图）
实时更新 需重新运行 CLI 支持仓库监听 自动索引（云端）
成本 依赖 LLM API 调用 免费版有限 免费 / 付费
适用规模 中小型项目（< 10万行） 中大型 超大型

CodeSee 的依赖图更多是文件级的，而 Understand-Anything 可以到函数/类级别（取决于 LLM 的解析能力）。Sourcegraph 强在搜索，但没有图形化的知识图谱关系可用。

另一个我常用的替代方案是 dependency-cruiser，它能生成静态的 SVG，但不可交互，更别提提问了。

我个人看法：Understand-Anything 的最大价值在于“可探索”和“可提问”，而不是“展示”。静态图看两眼就烦了，但交互式图谱允许你点进点出、切换视角，配合自然语言搜索，确实能让新成员更快定位代码逻辑。

局限性和适用边界

说几个你需要注意的地方：

  1. 依赖 LLM API：运行时会调用 LLM 做实体识别和关系抽取。这意味着每次生成图都有成本（按 token 计费）。如果是大型项目，可能消耗几十万 token，费用不低。免费方案可以用本地模型（例如 Ollama 加载 CodeLlama），但速度慢且准确率可能下降。

  2. **准确性不是 100%**：LLM 从代码中提取的语义关系有时会出错，例如把两个同名函数搞混，或误解继承关系。虽然可以通过多次抽取校验，但会增加延迟。

  3. 大型项目性能瓶颈：我试了一个 5 万行的 monorepo，生成图时内存占用飙到 2GB 以上，浏览器端渲染几千个节点和边也会卡顿。官方虽然支持分页或折叠，但实际体验仍待优化。

  4. 不是实时监控工具：它适合一次性理解代码库，或者做代码审查时用。如果你们日增代码很快，每次都要重新运行 CLI 才能更新图谱，不如直接依赖 IDE 插件。

  5. 特定语言支持深度不均衡：TypeScript/JavaScript 支持最好（因为是用 TS 写的），Python 其次，其他语言（Java、Go、Rust）可能缺乏精确的 AST 解析，更多依赖 LLM 猜测。

适用建议：在以下场景使用效果最好：

  • 新员工入职时快速了解一个中等规模项目（< 5 万行）
  • 设计评审时生成模块关系图
  • 跨团队代码交接的场景
  • 小型开源库的贡献者指南

不适用场景：

  • 超大型微服务项目（节点太多，交互反而低效）
  • 需要实时反映代码变更的持续集成流程
  • 对准确性要求极其严格的领域（如安全审计）

快速上手步骤

三分钟跑起来：

bash
1 2 3 4 5 6 7 8 9 10 11 12 13 14 
# 1. 安装（全局 or npx）
# 推荐使用 npx 临时运行，避免污染
npx understand-anything --help

# 2. 配置 API Key（以 Claude 为例）
export ANTHROPIC_API_KEY=your_key
# 或 OpenAI:
export OPENAI_API_KEY=your_key

# 3. 分析项目
npx understand-anything ./my-project -o output.html

# 4. 打开生成的 HTML 文件
open output.html

第一次运行会下载 LLM 依赖，可能稍慢。之后如果项目没变，可以复用缓存：运行 --cache 参数。

我的最终评价

Understand-Anything 让我看到了“代码理解”这个古老问题的新解法：与其让开发者靠自己脑补，不如让 AI 辅助构建语义图。它的交互体验和自然语言提问是亮点，但成本和准确性是需要权衡的代价。

如果你经常需要向别人解释代码架构，或者你正加入一个新项目感到迷茫，花 10 分钟跑一次这个工具，大概率比你自己翻一天代码收益更大。

仓库地址：https://github.com/Lum1104/Understand-Anything