AI 代码知识图谱 教程（三）| Understand-Anything（给人看）

AI 代码知识图谱 教程（三）| Understand-Anything（给人看）

• 一、新人看代码的困境
• [二、给人看的图 ≠ 给 AI 查的图](#二、给人看的图 ≠ 给 AI 查的图)
• [三、Understand-Anything 是什么](#三、Understand-Anything 是什么)
• • 核心亮点
  • [和 Graphify 的关系](#和 Graphify 的关系)
• [四、Understand-Anything 实战教学](#四、Understand-Anything 实战教学)
• • [4.1 前提条件](#4.1 前提条件)
  • [4.2 安装](#4.2 安装)
  • [4.3 初始配置](#4.3 初始配置)
  • [4.4 建图](#4.4 建图)
  • [4.5 命令速查](#4.5 命令速查)
  • [4.6 卸载](#4.6 卸载)
  • [4.7 常见问题](#4.7 常见问题)
• 五、入职引导三步法
• • 第一步：看社区全景
  • 第二步：深入核心模块
  • 第三步：对照架构文档验证
• 六、避坑清单
• 七、能和其他工具搭配吗？
• • 推荐新人的完整配置
• 八、总结

本文是「AI 图谱系列」专栏三。如果你是团队负责人或新人，需要"一眼看懂项目架构"，这篇文章是写给你的。

---

一、新人看代码的困境

• 打开代码库，几百个文件，不知道先看哪个
• 架构文档是有的，但和代码对不上------文档说模块 A 依赖模块 B，代码里其实是 C
• 问了同事一星期，还是搞不清楚"我一个请求进来，到底走了哪些组件"

Codegraph 和 Graphify 是给 AI 用的，新人需要的是给人看的。

---

二、给人看的图 ≠ 给 AI 查的图

	Codegraph	Graphify	Understand-Anything
为谁设计	AI Agent	AI Agent	人
输出格式	MCP 工具返回 JSON	HTML + JSON + Markdown	交互式 Dashboard
交互方式	通过 AI 查	通过 AI 查 + 浏览器看图	拖拽探索、点击展开
视角切换	❌	❌	✅ 初级/架构师两种视角
中文支持	❌	❌	✅ --language zh 生成中文节点

Understand-Anything 是专门给人看的地图。Codegraph 和 Graphify 是给 AI 的导航仪。三者定位不冲突。

---

三、Understand-Anything 是什么

多 Agent 协同分析代码库后，生成一个交互式 React Flow Dashboard。你可以拖拽节点、点击展开子图，按角色切换视角。

核心亮点

• 交互式可视化：拖拽、缩放、点击展开，不像静态 HTML 那样只能看
• 按角色切换：初级工程师视角（看模块关系） / 架构师视角（看设计意图和依赖方向）
• 中文节点描述 ：/understand --language zh 生成中文，对国内团队友好
• 引导式导览：不会几百个节点一下子砸脸上，按社区逐步展开

和 Graphify 的关系

Understand-Anything → 给人看：新人打开 Dashboard，拖拽探索项目结构
Graphify            → 给 AI 查：AI 通过 MCP 查图谱，回答问题

两者是互补关系，不冲突。 理想配置：新人入职时两个都装------自己看图，AI 帮查。

---

四、Understand-Anything 实战教学

4.1 前提条件

项目	要求
Claude Code	已安装并登录
API Key	至少一个大模型 API Key（推荐 Claude 3.5 Sonnet）

所有代码分析和图谱构建均在本地完成，代码不会上传至任何服务器。

4.2 安装

Understand-Anything 有两种使用方式，选一种即可。

方式一：Claude Code 插件（推荐，官方主推）

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

安装完成后仓库克隆到 ~/.understand-anything/repo。装完需重启 Claude Code。 安装后使用 /understand、/understand-dashboard 等斜杠命令。

方式二：一键安装脚本（支持多平台）

# 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

支持的平台参数：Claude Code、Codex、Cursor、OpenCode、Gemini CLI、VS Code、Pi Agent 等 12+ 个。

4.3 初始配置

首次运行时自动引导配置 API Key 和模型选择。支持 Claude、GPT-4o、DeepSeek 等。

4.4 建图

在 Claude Code 对话框或终端中使用：

/understand                    # 完整构建当前项目图谱
/understand src/frontend       # 只分析指定子目录
/understand --language zh      # 生成中文节点描述（国内团队推荐）
/understand --auto-update      # 同时注册 post-commit hook，每次提交自动增量更新

构建耗时参考：

项目规模	构建时间
< 1 万行	30 秒 ~ 2 分钟
1 ~ 10 万行	2 ~ 10 分钟
10 ~ 100 万行	10 ~ 60 分钟
> 100 万行	1 ~ 3 小时

产物存储在 .understand-anything/knowledge-graph.json。

4.5 命令速查

图谱与探索：

命令	用途
/understand	构建/更新知识图谱（后续自动走增量模式）
/understand --auto-update	注册 post-commit hook，每次提交自动更新
/understand-dashboard	打开浏览器交互式图谱页面
/understand-chat How does the payment flow work?	基于图谱进行自然语言问答

学习与入职：

命令	用途
/understand-onboard	生成新人入职指南
/understand-explain src/auth/login.ts	深入解释某个文件/函数
/understand-domain	提取业务域知识（域、流程、步骤）

变更分析：

命令	用途
/understand-diff	分析当前改动的影响范围（追踪函数调用链）

4.6 卸载

# 移除 Claude Code 插件
/plugin uninstall understand-anything

# 删除项目图谱数据
# Windows：Remove-Item -Recurse -Force .understand-anything\
# Mac/Linux：rm -rf .understand-anything/

4.7 常见问题

问题	解法
图谱构建失败	检查 API Key 配置是否正确；确保网络可访问 LLM 服务
Dashboard 无法访问	/understand-dashboard 会输出本地地址，浏览器打开即可
AI 回答不准确	运行 /understand 更新图谱；切换更强模型（推荐 Claude 3.5 Sonnet）
Dashboard 卡顿	2700+ 节点后 Dagre 布局可能阻塞，分模块建图或关闭全量渲染

---

五、入职引导三步法

第一步：看社区全景

打开 Dashboard，先看全局。图会按"社区"分组（社区 = 功能相近的一组类/模块），每块有自己的颜色。

比如一个博客项目，你会看到：
├──🔵 认证社区（SecurityConfig、LoginController、SessionService）
├──🟢 文章社区（ArticleController、ArticleService、ArticleMapper）
├──🟡 评论社区（CommentController、CommentService、SensitiveWordFilter）
├──🟣 站点管理社区（SiteConfig、FriendLink、SocialLink）
└──🔴 基础设施社区（RedisConfig、FlywayMigration、GlobalExceptionHandler）

先不点进去，先看有哪些社区、它们大概做什么。

第二步：深入核心模块

选你最相关的社区（比如你要改认证，就看蓝色社区），点进去，看内部连接：

SecurityConfig
    ├──→ SessionService（创建、验证、销毁 Session）
    ├──→ RedisConfig（Session 存 Redis）
    ├──→ CsrfFilter（CSRF Double Submit Cookie）
    └──→ LoginRateLimiter（登录限流）

看一个模块和哪些东西有连线，连线越多越核心。

第三步：对照架构文档验证

打开项目的架构文档（Graphify 的 GRAPH_REPORT.md 里有关联），对照你刚在 Dashboard 上看到的，验证理解：

"文档说认证模块依赖 Redis 做 Session 持久化 → 图上也看到了 SecurityConfig → RedisConfig → ✅ 对上了"

"文档说模块间单向依赖 → 图上有一条反向的线 → ⚠️ 可能是新加的，确认一下"

---

六、避坑清单

坑	后果	解法
Dashboard 节点太多卡顿	2700+ 节点后 Dagre 布局阻塞主线程	分模块建图，或关闭全量渲染
当 AI 查询工具用	它不是为省 token 设计的	AI 查询用 Codegraph 或 Graphify
和 Graphify 比较谁更好	两者定位不同没法比	一个给人看，一个给 AI 查，互补

---

七、能和其他工具搭配吗？

组合	给谁用	效果
Understand-Anything 单独	新人自己看	快速了解项目结构
+ Graphify	新人 + AI	自己看图 + AI 帮查深入问题
+ Codegraph	AI 日常导航	新人看图，AI 用 Codegraph 回答具体调用链

推荐新人的完整配置

新人入职第一天：
  1. 打开 Understand-Anything Dashboard → 看社区全景（30 分钟）
  2. 深入自己负责的模块 → 看内部连线（1 小时）
  3. 对照架构文档验证理解（1 小时）
  
  之后日常：
  → AI 用 Codegraph 回答"谁调了谁"（新人不用自己 grep）
  → AI 用 Graphify 回答"为什么这么设计"（新人直接看到决策依据）

---

八、总结

你的情况	选什么
新人入职引导、团队 onboarding	Understand-Anything
纯代码项目，日常开发导航	看 专栏一：纯代码篇
有架构文档，需要理解 WHY	看 专栏二：文档篇

一句话：Understand-Anything 是给新人画的地图，Codegraph 是给 AI 的导航仪，Graphify 是给 AI 的说明书。一个团队三种工具各司其职，不冲突。