20 万行代码不知道从哪读起，这个插件把代码库变成可搜索的知识图谱

你刚加入一个新团队，接手一个 20 万行的代码库。README 写得像给机器看的，目录结构嵌了六层，你最想知道的不是这个项目用了什么框架，而是「登录流程到底经过哪几个文件」「改这个函数会影响谁」。

Understand Anything 解决的就是这个问题。它是个 Claude Code 插件，跑一条 /understand 命令，用多 Agent 管线扫你的整个项目，把每个文件、函数、类、依赖关系都拆出来，最后生成一个交互式知识图谱，可以在浏览器里点开、搜索、追问。

78410 Star，MIT 协议，TypeScript 写的，2026 年 3 月由 Lum1104 创建，Egonex 团队接手维护。它的口号我挺喜欢，不是「让你的代码库看起来多酷炫」，而是「让你安静地搞懂每个零件怎么咬合」。

但说真的，这个项目最值得拆的不是它做了什么，而是它怎么处理「用 LLM 理解大代码库」这件事里最难的那个矛盾，token 成本。

把确定性的事还给确定性

很多「用 AI 理解代码」的项目，做法是把整个代码库丢给 LLM，让它生成结构。问题很明显，一是贵，二是不稳定，同样的代码跑两遍可能得到不同的边。

Understand Anything 的核心设计是一个混合管线，Tree-sitter 做确定性的活，LLM 做语义的活，各干各的擅长的。

我读了它的源码，这个分工不是嘴上说说。understand-anything-plugin/skills/understand/ 目录下有两个关键脚本。scan-project.mjs 的注释写得很直白，它取代了过去「LLM 写的散文扫描器」，那个老方案会(a) 每次运行生成一个临时 Node 脚本，(b) 走文件树，(c) 用 LLM 上下文里的查找表分类每个文件。注释里有一句话点破了本质，「一个纯粹的规则查找过程，却按 LLM 的价格在计费」。

这就是它省钱的第一刀。

Tree-sitter 负责解析源码生成具体语法树，提取那些确定的事实，import、export、函数定义、类定义、调用点、继承关系。这些在扫描阶段预解析成一个 importMap，传给后面的 file-analyzer，这样 LLM 就不用再从源码里重新推导 import 关系了。同样的输入永远得到同样的输出，每跑一次都一样。

LLM 干的是 Tree-sitter 干不了的活，读解析出来的结构加原始源码，生成那些「这个文件是干嘛的」「这属于哪一层架构」「这段业务流程叫什么」这种需要理解力才能产出的东西。

这个分工有个直接好处，结构层面可复现，语义层面有意图。图谱的边是确定性的，节点的描述是有意义的。

七阶段管线

/understand 跑起来不是一键出图，它有一条七阶段的流水线。我逐个读了 SKILL.md 的源码，理出来是这样的。

Phase 0 是预检，判断跑全量还是增量。这里有个很细的设计，worktree 重定向。如果你在 git worktree 里跑（Claude Code 的 worktree 是临时的），它会检测到并把输出重定向到主仓库根目录，因为 worktree 会话结束就被销毁，图谱也会跟着丢。这个逻辑直接对应 issue #133，是踩过坑之后补的。

Phase 0.5 是忽略配置，生成 .understandignore 文件，基于你的 .gitignore 去重后给出排除建议，还会等用户确认才往下走。

Phase 1 是扫描，dispatch 一个 project-scanner 子 Agent，发现所有文件、检测语言和框架。超过 100 个文件会提醒你考虑用子目录限定范围。

Phase 1.5 是分批，跑 compute-batches.mjs 脚本，把文件按语义聚类成批次。这一步是后来加的成本优化，早期的版本按文件数硬切，现在是语义分批，相关文件放一批，减少跨批次重复理解上下文。

Phase 2 是分析，迭代 batches.json 里的每个批次，给每个批次 dispatch 一个 file-analyzer 子 Agent，最多 5 个并发，每批 20 到 30 个文件。这里产出 GraphNode 和 GraphEdge 对象，是图谱的节点和边。extract-structure.mjs 负责确定性的结构提取，用 Tree-sitter 插件替代早期「LLM 生成的临时正则脚本」。

Phase 3 到 Phase 5 是架构分析、构建导览、图谱校验。architecture-analyzer 识别 API、Service、Data、UI、Utility 这些架构层，tour-builder 按依赖顺序生成学习路线，graph-reviewer 验证图谱完整性和引用一致性（默认内联跑，加 --review 走完整 LLM 审查）。

Phase 6 是组装出最终的 knowledge-graph.json，存在 .ua/ 目录下。

整条管线的核心分流可以在这张图里看清楚，左边暖色的 Tree-sitter 层负责确定性的结构提取不花 token，右边蓝色的 LLM 层负责语义判断要花钱，两条线最终汇聚到底部的 knowledge-graph.json。

这套管线下次跑的时候默认是增量的，只重新分析变更过的文件。这是它控制成本的第二刀。

token 消耗神器，和它的自救

聊到这必须直面这个项目最大的争议，成本。

issue #472 标题就四个字加一句话，「我愿称之为 token 消耗神器，一个全新的项目初始化，token 消耗到千万级了」。issue #76 的作者语气客气得多，但问的是同一个事，首跑很慢，token 消耗很高。

这不是用户在黑它，官方 README 自己也承认了。原话是「initial /understand analyzes your whole codebase and can consume a significant number of tokens on large projects」，建议你在有订阅套餐的方案上跑，或者用本地模型初始化。

我算过这个账。5 个 Agent 并发，每批 20 到 30 个文件，一个中等规模的 monorepo 轻松几百个文件，分十几批，每批都要读源码、读 importMap、读项目上下文、生成结构化节点描述。首跑把整个代码库过一遍 LLM，token 消耗冲到千万级，这个数字我没有理由怀疑。

社区的应对方案在 issue #176。有人提了个 --hybrid flag，把最贵的 file-analyzer 阶段路由到本地 Gemma 模型（通过 Ollama），架构推理阶段还是留在 Claude 上。这个路由设计很聪明，把成本最高、但语义判断要求相对低的「逐文件提取」丢给本地模型，把需要全局推理的「架构层归属、业务域映射」留给强模型。issue 里给的数字是中大型仓库能降本约 4 到 5 倍。

坦白讲，一个项目能长到 78000 多 Star，同时首跑能把人 token 烧到千万级，这两件事同时成立，说明它解决的问题足够痛，痛到用户愿意接受这个成本。scan-project.mjs 和 extract-structure.mjs 把规则查找从 LLM 计费里挪出来，compute-batches 做语义分批，默认增量更新只跑变更文件，这些都是在往一个方向使劲，把贵的留下，把不需要 LLM 的坚决挪走。

一个值得警惕的安全插曲

issue 区有个值得单独拎出来讲的发现，issue #432 标题是「Security, PR #206 injects an obfuscated executable payload into homepage/astro.config.mjs (do not merge)」。有人在一个 PR 里往首页配置文件注入了混淆过的可执行 payload。

这个 issue 已经关了，对应的还有 issue #458 在做供应链加固，加混淆扫描器和公告策略，以及 issue #279 在做审计覆盖层的 5 个加固修复和指纹校验二进制。

你想想看，一个会 clone 到你本地、会被多个 AI 平台 symlink 到 Skills 目录、会跑 Node 脚本读你整个代码库的插件，供应链安全是实实在在的风险。Egonex 的处理方式是加审计、加指纹校验、在 SECURITY.md 里写明流程。这个插曲本身不构成弃用理由，但它提醒一件事，这类深度集成的 AI 工具，安装前最好看一眼它跑什么、读什么、往哪发。

不止看代码结构

除了结构图，它还有几个能力值得提。

/understand-domain 切换到业务域视图，把代码映射到真实的业务流程，按域、流程、步骤展开成横向图谱。这个对产品经理和新人特别有用，他们不想知道 auth/login.ts 里调了什么函数，他们想知道「用户登录」这个业务动作经过哪几步。

/understand-diff 做变更影响分析，commit 之前看你的改动会波及系统哪些部分。/understand-chat 可以对着图谱问任何问题，因为图谱是结构化的 JSON，chat 能把相关节点的上下文精准喂给 LLM，比裸问 Claude Code 效果好不少。/understand-explain 深挖单个文件或函数，/understand-onboard 生成新人 onboarding 指南。

还有个很实用的设计，图谱就是 JSON，commit 一次，团队成员直接用，不用再跑一遍管线。甚至不需要 Claude Code，只要 Node.js 18 加以上，一条 npx 命令就能在浏览器里打开交互式 dashboard，全程只读本地文件，不调 LLM，数据不出机器。

什么场景该用，什么场景别碰

回到选型这件事。

Understand Anything 适合的场景很明确，你接手了一个中等规模以上的陌生代码库，需要快速建立全局认知，你的团队有 token 预算或本地模型能力，你愿意为一次性的理解成本付费换来后续每次 chat 和 explain 都更精准。

别碰的场景也明确，代码库很小（几十个文件你自己读得完），没有 token 预算又不想折腾本地模型，或者你对供应链安全零容忍不愿意装第三方深度集成插件。

这个项目真正的方法论价值，不是那个交互式图谱，而是它对「LLM 该做什么、不该做什么」的清醒切分。Tree-sitter 吃下确定性的结构事实，LLM 只补语义判断，importMap 预解析避免重复推导，语义分批减少跨批次损耗，增量更新只动变更文件，hybrid 模式把贵且语义要求低的活丢给本地模型。

这五刀砍的是同一个东西，LLM 的无效 token 消耗。任何一个想用 LLM 做大规模代码分析的人，都该把这个切分逻辑记下来。它叫什么不重要，你叫它「确定性优先」也好，「贵活贱活分流」也罢，核心就一句话，别让 LLM 干它能干但不该干的事。