Lum1104/Understand-Anything · v2.7.5 · TypeScript · MIT

Understand-Anything · 给人看的认知地图

把任意代码库变成可交互、可搜索、可问答的知识图谱。多 agent 流水线 + 业务域叠加 + React Flow 可视化 Dashboard。

23.1k
Stars (+2,299/周)
41+
语言
21×35
节点×边类型
5+
平台
UA

Understand-Anything

Lum1104/Understand-Anything · v2.7.5 · MIT
23,146
Stars (+2,299/周)
41+
语言
21×35
节点×边类型
5+
平台

一句话定位：“你刚加入新团队，代码库 20 万行，从哪看起？” Understand-Anything 用一条多 agent 流水线分析整个项目，建起一张涵盖每个文件、函数、类、依赖的知识图谱，再用一个可交互 Dashboard 让你像逛地图一样探索它。如果说 CodeGraph 是给机器读的，那 Understand-Anything 是给人看的——当然 agent 也能用。

“目标不是一张让你惊叹‘我的代码库好复杂’的图，而是一张悄悄教会你‘每块拼图如何拼在一起’的图。” —— 项目设计文档

Monorepo 三件套

与 CodeGraph 的单包不同，Understand-Anything 是 pnpm monorepo，职责切得很干净：

  • packages/core —— 分析引擎：图构建、语言/框架识别、持久化、搜索、校验。
  • packages/dashboard —— React + React Flow 的交互式可视化，Zustand 管状态，Tailwind v4 + ELK 布局。
  • understand-anything-plugin/src + agents/*.md —— 插件命令与多 agent 编排（markdown 定义）。

核心哲学：确定性结构 × LLM 语义

这是它与“纯静态分析”最根本的分野。Understand-Anything 在每一个环节都把两件事分开：

  • tree-sitter（确定性）负责签名级事实：函数/类/import/export、调用图、用于变更检测的指纹。同样输入永远同样输出，可进 git。
  • LLM（语义）负责意图：每个节点的大白话摘要、标签、复杂度、架构分层归属、业务域映射、导览设计、语言概念讲解。
packages/core/src/schema.ts — 21 节点 / 35 边，含别名归一
// 节点跨越「代码 / 非代码 / 业务域 / 知识」四大类
// code:     file function class module concept
// infra:    config document service table endpoint pipeline schema
// domain:   domain flow step          ← 业务域叠加层
// knowledge: article entity topic claim source

function autoFixGraph(graph): KnowledgeGraph {
  // LLM 爱造同义词：func→function、extends→inherits …
  // 确定性重映射 76 个节点别名 + 38 个边别名，
  // 既给 LLM 自由，又不破坏 schema。
}

多 Agent 流水线：七个专家的接力→ 深度页

这是 Understand-Anything 最具特色的设计。它不是一个大 prompt，而是把分析拆成七个职责单一的 agent（agents/*.md，带 YAML frontmatter），串行 + 并行协作：

🔍
project-scanner

确定性脚本枚举文件、识别语言、过滤 .understandignore；LLM 读 manifest 提取项目名/框架。

📄
file-analyzer ×N（并行 5）

每批 20–30 文件，tree-sitter 抽结构 + LLM 产出摘要/标签/语义边；输出过大时自动切片。

🏗️
architecture-analyzer

计算目录分组与 import 邻接，LLM 归纳 3–10 个逻辑分层，每个文件归属唯一一层。

🧭
tour-builder

算 fan-in/fan-out 排名与依赖链，LLM 设计 5–15 步“按正确顺序学代码”的导览。

✅
graph-reviewer

纯确定性校验：schema、引用完整性、分层覆盖、唯一性，问题分为已修正/已丢弃/致命。

🏢
domain-analyzer

可选：从代码中抽取业务域 / 流程 / 步骤，产出 domain-graph.json。

语义批处理：用社区发现切批次→ 深度页

朴素的“每 20 个文件一批”会把逻辑耦合的模块拆散，丢失跨批的语义边。Understand-Anything 在 2026-05 的设计里引入了一个聪明做法（compute-batches.mjs）：对 import 图跑 Louvain 社区发现，把语义耦合的文件聚成一批（5–35 个/批），超大社区再用边介数启发式拆分；同时为每个文件构造 neighborMap（跨批邻居导出的符号），让 file-analyzer 能自信地下跨批边的判断。这同时解决了另一个现实问题——在输出受限的后端（如 Bedrock Opus 4096–8192 token）上，agent 会自检输出大小并切成 batch-i-part-k.json。

指纹 + 陈旧检测 = 增量分析

fingerprint.ts 为每个文件算出结构指纹（内容 hash + 函数/类/import 签名）。变更被分成三级：NONE（hash 相同，跳过）/ COSMETIC（内容变但签名没变，只更新语义）/ STRUCTURAL（签名变，全量重分析）。配合 git diff 找出改动文件，只重分析它们，再 merge 回旧图——200 文件的库改了 3 个文件，秒级更新而非分钟级。

搜索走 fuse.js 做关键词模糊匹配（name/tags/summary 加权），同时有一个 SemanticSearchEngine 对预计算 embedding 做余弦相似度检索，Dashboard 里可在 fuzzy / semantic 间切换。一个值得称道的隐私细节：写盘前 sanitiseFilePaths 会把所有绝对路径转成项目相对路径，绝不把 /Users/alice/company/... 泄漏进可提交的 JSON。

可视化 Dashboard

前端用 React Flow 渲染图、Zustand 管 150+ 字段的状态、ELK（Eclipse Layout Kernel）做层次布局、Louvain 做视觉聚类、Prism 高亮源码。三种视图（structural / domain / knowledge）可切换；还有角色自适应 UI——根据你是“非技术 / 初级 / 资深”动态调整细节密度，以及暗金奢华主题（#0a0a0a + 金色 #d4a574 + DM Serif Display）与 6 国语言本地化。

业务域叠加层是它区别于一切纯静态工具的杀手锏：在结构图之上，它能再抽出“订单管理 → 创建订单 → 校验输入”这样的领域 / 流程 / 步骤三级业务层级，每个领域节点都能按 ID 下钻到真正实现它的函数和文件——把代码和业务逻辑第一次连了起来。

源码结构速览

understand-anything-plugin/ ├── packages/core/src/ │ ├── schema.ts # 21 节点/35 边 + 别名归一 │ ├── analyzer/ # graph-builder · llm-analyzer · layer-detector │ ├── fingerprint.ts # 结构指纹 → 增量分析 │ ├── search.ts · embedding-search.ts │ ├── languages/ # 41 语言 configs + 11 框架 │ └── plugins/extractors/ # 12 个 tree-sitter 抽取器 ├── packages/dashboard/src/ # React Flow + ELK + Louvain ├── agents/ # 7+ 个多 agent 编排 (.md) └── src/ # /understand /understand-chat /understand-diff …

对 coding agent 生态的意义

Understand-Anything 把“知识图谱”从 agent 的内部检索结构，变成了团队可共享、可提交、可视化的认知资产——图就是一份 JSON，commit 一次，队友跳过整条流水线直接用，等于“图即文档 (graph-as-docs)”。它还示范了一种正在成为主流的范式：用确定性工具打地基、用 LLM agent 做语义编排。而业务域层的引入，更预示着下一步——agent 不只理解代码怎么写，还要理解它为什么存在。