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

一、项目概述

Understand Anything 是一个 Claude Code 插件，它能将任意代码库、知识库或文档转化为可交互的知识图谱——你可以在上面探索、搜索、提问。当你加入一个新团队，面对 20 万行代码无从下手时，它能帮你从"盲目读代码"切换到"看清全局"。

核心解决的问题是：如何快速理解一个陌生的大型代码库？ 传统的做法是逐文件阅读、画架构图、写文档，而 Understand Anything 通过多 Agent 流水线自动完成这一过程，并生成一个可视化的交互式仪表板。

核心特性包括：

结构图谱探索：将代码库中每个文件、函数、类都作为可点击的节点，支持缩放、搜索和浏览
业务逻辑视图：Domain 视图将代码映射到真实业务流程——领域、流程和步骤以水平图谱展示
知识库分析：支持 Karpathy 模式的 LLM Wiki，提取实体、声明和隐含关系
引导式导览：自动生成按依赖关系排序的架构导览
模糊与语义搜索：支持按名称或按语义搜索，如"哪些部分处理认证？"
Diff 影响分析：提交前查看代码变更的系统级影响
增量更新：默认只重新分析变更过的文件

二、技术原理

架构设计：Tree-sitter + LLM 混合方案

Understand Anything 的核心设计理念是让静态分析和 LLM 各司其职：

Tree-sitter（确定性层）：将源码解析为具体语法树（CST），提取结构化事实——导入导出、函数/类定义、调用点、继承关系。扫描阶段预解析为 importMap，传递给文件分析器避免重复推导。相同输入 → 相同输出，保证可复现性。同时支持基于指纹的变更检测，驱动增量更新。
LLM（语义层）：读取解析后的结构及原始源码，产出解析器无法生成的内容——自然语言摘要、标签、架构层分配、业务域映射、导览和语言概念标注。

这种分层设计保证了图谱的结构边具有确定性（相同代码总是产生相同的边），同时语义边能捕捉意图（一个文件"是做什么的"，而非仅仅是"导入了什么"）。

多 Agent 流水线

/understand 命令编排了 5 个专业化 Agent，/understand-domain 额外增加第 6 个：

Agent	职责
`project-scanner`	发现文件，检测语言和框架
`file-analyzer`	提取函数、类、导入；生成图谱节点和边
`architecture-analyzer`	识别架构分层
`tour-builder`	生成引导式学习导览
`graph-reviewer`	验证图谱完整性和引用完整性
`domain-analyzer`	提取业务领域、流程和步骤

文件分析器并行执行（最多 5 并发，每批 20-30 个文件），并支持增量更新。

技术栈

从 package.json 和配置文件可以看出项目的技术选型：

运行时：Node.js + TypeScript（ESM 模块系统，ES2022 目标）
包管理：pnpm 10.6（monorepo 架构）
代码解析：Tree-sitter（支持 C、C#、C++、Go、Java、JavaScript、PHP、Python、Ruby、Rust、TypeScript 共 11 种语言）
构建工具：esbuild
测试：Vitest
代码规范：ESLint 9 + typescript-eslint

{
  "pnpm": {
    "onlyBuiltDependencies": [
      "tree-sitter-c", "tree-sitter-c-sharp", "tree-sitter-cpp",
      "tree-sitter-go", "tree-sitter-java", "tree-sitter-javascript",
      "tree-sitter-php", "tree-sitter-python", "tree-sitter-ruby",
      "tree-sitter-rust", "tree-sitter-typescript"
    ]
  }
}

数据流

扫描阶段：project-scanner 发现文件并检测语言框架
分析阶段：file-analyzer 并行提取结构，Tree-sitter 解析 + LLM 语义分析
架构阶段：architecture-analyzer 识别 API/Service/Data/UI/Utility 等分层
验证阶段：graph-reviewer 检查引用完整性
输出阶段：生成 knowledge-graph.json，Dashboard 可视化

三、安装与快速开始

环境要求

Claude Code、Cursor、VS Code + Copilot、Codex、Gemini CLI 等 AI 编程工具之一
Node.js 运行时（插件本身依赖）

安装步骤

Claude Code 原生安装：

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

一键安装（支持 Codex / OpenCode / OpenClaw / Gemini CLI / VS Code Copilot 等多平台）：

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

# 指定平台跳过交互提示
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 并为所选平台创建符号链接。

最简运行

# 分析代码库
/understand

# 中文内容生成
/understand --language zh

# 打开交互式仪表板
/understand-dashboard

四、使用方法与实战

基础用法

# 向代码库提问
/understand-chat 支付流程是如何工作的？

# 分析当前变更的影响
/understand-diff

# 深入分析特定文件
/understand-explain src/auth/login.ts

# 生成新成员入门指南
/understand-onboard

进阶用法

# 提取业务领域知识
/understand-domain

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

# 增量更新（默认行为，仅分析变更文件）
/understand

# 自动更新：每次提交后通过 post-commit hook 增量更新图谱
/understand --auto-update

# 限定子目录范围（适合大型 monorepo）
/understand src/frontend

团队协作：共享图谱

图谱本质是 JSON 文件，提交一次，团队成员即可跳过分析流水线。适合用于：

新人 onboarding
PR Review
文档即代码

# 提交这些
.understand-anything/knowledge-graph.json
.understand-anything/

# 忽略这些（本地临时文件）
.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/

五、常见问题与解决方案

Q: 分析大型代码库时耗时过长？

启用增量更新模式（默认行为）。只分析变更文件，大幅减少重复分析开销。也可以用子目录限定范围：

/understand src/core  # 只分析核心模块

Q: 图谱太大，Git 仓库膨胀？

使用 Git LFS 管理图谱 JSON 文件。10MB 以上的图谱建议走 LFS。

Q: 支持 Windows 吗？

支持。PowerShell 一键安装器可用，Tree-sitter 在 Windows 上正常工作。

Q: 不使用 Claude Code 可以用吗？

可以。支持 Cursor、VS Code + Copilot、Codex、Gemini CLI、OpenCode、OpenClaw、Vibe CLI、Cline、KIMI CLI 等多平台。

Q: 分析结果可以离线查看吗？

可以。仪表板是静态 Web 应用，/understand-dashboard 启动后可在浏览器中离线浏览已生成的图谱。

Q: 如何更新到最新版？

./install.sh --update

卸载：

./install.sh --uninstall <platform>

六、总结

Understand Anything 解决了一个真实痛点：面对陌生的大型代码库，从"逐文件盲读"到"全局可视化理解"的跨越。其 Tree-sitter + LLM 的混合架构保证了结构分析的可复现性和语义理解的深度，多 Agent 流水线的并行化设计使分析效率可控，而增量更新和团队共享机制则让图谱能持续演进。

对于频繁切换项目的开发者、需要快速上手新代码库的团队成员、或者单纯想更好理解自己项目架构的人来说，这是一个值得尝试的工具。项目采用 MIT 许可证，可直接在 GitHub 上使用。

一、项目概述#

二、技术原理#

架构设计：Tree-sitter + LLM 混合方案#

多 Agent 流水线#

技术栈#

数据流#

三、安装与快速开始#

环境要求#

安装步骤#

最简运行#

四、使用方法与实战#

基础用法#

进阶用法#

团队协作：共享图谱#

五、常见问题与解决方案#

Q: 分析大型代码库时耗时过长？#

Q: 图谱太大，Git 仓库膨胀？#

Q: 支持 Windows 吗？#

Q: 不使用 Claude Code 可以用吗？#

Q: 分析结果可以离线查看吗？#

Q: 如何更新到最新版？#

六、总结#