公众号名称：AI 方寸山

作者名称：九皋山人

发布时间：2026-05-28 08:19

说实话，第一次看到 Understand-Anything 这个项目，我就被名字误导，认为噱头太大，就没关注。直到最近看到它的热度，才重新拆解跑了下。

名字还是大了，应该改名成 Understand-Anything-Code 最贴切，它主要是让Agent能更好更省钱的理解代码仓。如果你对代码库尤其是大型项目有工作或学习的需求，可以一切使用和学习下。

先看技术。schema 当总线、tree-sitter 抽 AST、Louvain 社区检测做 batching，挺好的路线。

再看工程经验。翻到 merge-batch-graphs.py，开头 30 多条 alias 规则：func: → function:，low/medium/high → simple/moderate/complex，tested_by 方向反了自动翻转。每一条都是 LLM 吐错吐出来的伤疤。

我看这些 alias 的时候反应过来，自己写 skill 用的 sanitize 规则跟它一个逻辑。只不过它踩了 100 个坑，我只踩了十几个。这东西真正值钱的，是工程纪律。技术招式可以一夜复制，工程纪律要踩 100 个坑才有。

这个项目叫 Lum1104/Understand-Anything。开仓 4 个月，35k star、2.8k fork。下面分三步说清楚：它是怎么运作的、独特在哪、能拿走什么。

/understand 的架构和流程

Understand-Anything 是一个 Claude Code Plugin，也支持 Cursor、Codex、Gemini CLI 等 15 个平台。核心功能一句话：把代码库扫成 JSON 知识图谱，落到 .understand-anything/knowledge-graph.json，可以 commit 进仓库共享。

它要解决的场景每个程序员都经历过。新人入职，20 万行代码摆面前，目录树滚不到底，不知道从哪读。改了一个函数想评估波及面，全靠 reviewer 脑补。给 AI agent 喂代码时没有结构化的项目地图，每次从零解释一遍。

这些问题指向同一个答案：项目缺一份结构化的、能自动更新的、团队共享的知识地图。下面这张是 Understand-Anything 的整仓架构，6 层 41 个模块：

这张图最值得注意的不是模块多，是模块之间怎么连的。没有一个中央编排器。所有命令通过共享的 schema 文件互通，用户敲命令，命令派 agent 干活，agent 把结果写进那份 JSON，下一个命令读同一份文件继续干活，谁也不需要知道谁。

一条 /understand 命令跑下去，六个步骤顺次展开。

第一步，钩子拉起来。 hooks.json 注册了两个 hook：SessionStart 检查 commit hash 判断是否需要更新，PostToolUse 监听 git 操作自动触发增量。框架层就做这两件事，其余全靠用户主动敲命令。

第二步，结构抽取，机器干机器的活。 scan-project.mjs 枚举文件树，extract-import-map.mjs 用 tree-sitter 解析 import 依赖。代码骨架是事实，不该让概率模型猜。这一步不调用 LLM。

第三步，按亲疏关系分片。 compute-batches.mjs 跑 Louvain 社区检测算法，把互相依赖多的文件分到同一批，减少 agent 之间的信息孤岛。一个 100+ 文件的项目通常切成 10-20 个 batch，每批 20-30 个文件。

第四步，agent 并发分析。 9 个专职 agent 各管一段：project-scanner 发现文件和语言，file-analyzer 抽函数和类，architecture-analyzer 识别架构分层，tour-builder 编排阅读顺序，graph-reviewer 兜底校验完整性。每个 agent 只写自己的 prompt，互不知道对方存在。

这一步有一条硬约束写在 CLAUDE.md 里：「Agents write intermediate results to disk, not returned to context.」每个 agent 跑完把 JSON 写到 .understand-anything/intermediate/，主流程只读一行 stderr 摘要就走，原始数据从不进对话历史。一个 100+ 文件的项目并发跑 10-20 个 batch，每个 batch 产生几十个节点和几十条边，如果全部塞回主流程 context，越后面的 batch 看到的对话历史越长，LLM 有效注意越稀薄。

第五步，合并消歧。 merge-batch-graphs.py 合并所有 batch。这是整个流水线最脏的环节。30 多条 alias 规则在这里干活：func: 统一成 function:，low/medium/high 统一成 simple/moderate/complex，方向反的边自动翻转，多套一层 envelope 的 unwrap 掉。每一条规则都是 LLM 吐错吐出来的，没人会主动设计这种东西。

第六步，落盘成图。 21 种节点类型、35 种边类型，全部按 types.ts 定义的 schema 写入 knowledge-graph.json。这份文件是唯一真相源。后续 /understand-dashboard、/understand-chat、/understand-diff、/understand-onboard 全都读它，不重新分析。

六步走完，一份能 commit 进仓库的知识图就生成了。下次有人 clone 下来跑 /understand-dashboard，浏览器里直接看。

招式都不新，护城河在另一层

架构挺漂亮。但拆开看，单个招式没几个新的。

schema 当总线，10 年前 docs-as-code 就在用。写文件不写 API，IDE 项目索引的老路。多 agent 并发，AutoGPT 时代就遍地跑了。tree-sitter 解析，上世纪 90 年代的产物。Louvain 社区检测，30 年前的图算法。指纹增量更新，编译工具几十年的传统。

仓库里一份外部深度拆解给了一句判断，我读到的时候心里咯噔一下：

最难复刻点不是 schema 本身，是 schema 后面踩出来的修复层——merge-batch-graphs.py 里 30+ 条 alias 规则、func: → function: 归一、tested_by 方向校验、unwrap envelope、layer 引用补全，全是经验工程。

我把仓库又翻了一遍，这次专看修 bug 的 commit。越看越确定：踩过的坑才是这个项目的护城河。下面四条最说明问题。

sub-agent 写磁盘，把 context 留给决策

前面提过 CLAUDE.md 那条硬约束。往深想一步：写文件不只是省 token 预算，是保住 LLM 的有效注意。

每个 batch 产生几十个节点和几十条边。如果 agent 把结果塞回 context，后面每个 agent 看到的对话历史都在膨胀。越靠后的分析质量越差，因为有效信息被前面 batch 的噪音稀释了。写磁盘等于每次对话都从干净状态开始，agent 只看到上一步的摘要结论，不背上全部中间产物。

我自己写并发 sub-agent 的 skill 踩过一模一样的坑。跑到第 5 个 batch 触发 context 警告，后来全改成写文件。

30+ 条 alias，是 LLM 的边界

merge-batch-graphs.py 里的 alias 表，每一条对应一次「这个模型为什么又吐错了」的吐血时刻。

复杂度写 simple/moderate/complex 还是 low/medium/high？节点前缀用 func: 还是 function:？prompt 里写三遍「请使用 function: 前缀」，模型还是随机给你 func:。边的方向有没有反？返回有没有多套一层 envelope？这些问题 prompt 管不住，只能靠后处理硬补。

我自己维护的 translator skill 也写了 12 条 sanitize 规则，规模是这工具的三分之一。这种东西复制不来。新人 fork 完仓库按 schema 写一个 clone 容易，把「这个模型在什么输入下会吐什么样的脏数据」的知识迁移过来才是难的。脏数据样本本身就是资产。

issue 编号是最好的文档

翻这个项目的 SKILL.md，有些地方读起来像过度防御。但每条「过度」背后都跟着一个用户报的 bug。

issue #152 记录了一条坑：fingerprint.json 必须先于 meta.json 写盘成功。顺序反过来，下次增量更新会把所有文件当成结构变化，触发全量重跑。原本一块钱的更新变成五十块。SKILL.md 第 740 行专门用一段警告记着这条约束。

issue #133 是 worktree 重定向。Claude Code 的 worktree 是临时目录，session 结束就没了。作者在 Phase 0 补了 20 行 shell 检测 worktree，自动把输出重定向到主仓库根。

issue #167 是 model: inherit。opencode 平台不认识这个值，当成字面 model id 报错。所以仓库里 9 个 agent 文件全都不写 model 字段。

三条加起来才几十行代码，每一行都是用户报 bug 换的。

指纹：代码的增量更新

build-fingerprints.mjs 用 tree-sitter 抽出每个文件的函数/类/导出签名作为指纹。下次 commit 后只比对指纹，结构真变了的才送 LLM 重新分析。改注释、重排 import、跑 prettier 这种零结构变化的操作，增量阶段零 token 消耗，只 bump meta.json 里的 commit hash。

这是把「代码理解」做成经济可持续的关键。一个团队每天 50 个 commit，没有指纹增量，光是 auto-update 每天就烧几百块。

我维护的 wechat-stats skill 也加过类似的时间过滤，只重抓最近 7 天数据，成本砍掉九成多。

思考

拆完这个仓库之后我回头看自己写的 skill，会顺着三层问自己：

架构上：skill 之间用什么互通？API、共享内存、还是文件？文件最慢但最稳，能 commit 进 git、能跨宿主、能脱离生成它的 agent 独立存在。

编排上：系统里有没有一个不可替换的中央调度器？有的话，去掉它还能跑吗？跑不了说明耦合太深，早晚卡住扩展。

工程上：LLM 输出准备了几道兜底？一道没有，skill 大概只跑过 hello world。加一道能撑过第一个真实用户。三道以上才敢甩给同事用三个月。

这几件事没有标准答案。但一个都答不上来的话，那大概率做的是个能跑的 demo，不是个能用三个月的工具。

技术招式可以一夜复制。工程纪律要踩 100 个坑才有。

Agent 到现在没有炫技，只有朴实无华的工程经验，CC 泄露的源码说明了这一点，众多的垂直领域的 Agent 也说明了这一点。

创新可不从来都这样？在旧的土地上新出新的路。

#Agent #AI #大模型 #智能体 #代码 #Understand-Anything

---

Original 九皋山人 AI 方寸山

---

内容效果不满意？点此反馈