接手一个 20 万行的项目，你打开 IDE，光标在文件树第一行闪了两下，然后你把窗口关了。人的工作记忆一次大概握住四样东西，一个中等规模的代码库却躺着几千个函数、上万条 import 语句。Understand Anything 想补的就是这一下：让 AI 把整个项目摊成一张带标签的图谱，你从图上往下走，而不是顺着 import 往上猜。
它 3 月建仓，9 月长到 8.2 万 star、6900 多个 fork，MIT 协议，主语言 TypeScript。最初由 Lum1104 创建，现在归在 Egonex-AI 组织下。官网口号上下两行，上面是 Understand Anything. Understand Anyone.，下面小一号：AI should help people, not replace them.
一、三条命令，跑完多一个文件
它是 Claude Code 的原生插件：
/plugin marketplace add Egonex-AI/Understand-Anything /plugin install understand-anything /understand
跑完，项目根目录里多出一个 .ua/knowledge-graph.json。
就这一个文件。
节点、边、导览路线、架构分层、业务域映射都在里面。本地生成，本地看。
第一次跑中间有四处会停下来找你。
.understandignore 得先过。 首跑会生成一份排除规则，来源是三层叠加：项目里的 .gitignore、内置默认值、按语言分组的测试文件建议。生成完它不往下走，要求你过一眼、把想排除的模式取消注释，等你确认。这一步省下的都是真金白银，后面烧多少 token 由它决定。
文件数过 100 会拦一下。 扫描完超了这个门槛，它提示你改用子目录参数缩范围，让你自己决定要不要顶着跑。
排除统计。 扫描阶段报一句 Excluded N files via .understandignore，拿这个数核自己的规则写对没有。
进度看得见。 阶段按 [Phase N/7] 打日志，批处理报 Analyzing batch X/N，大项目上能看出它卡在哪。
跑完之后，图谱校验通过它才自动拉起 Dashboard。校验没过只报"已保存但有警告"，面板不开。
二、参数速查，.ua/ 里有什么
/understand 的参数比 README 展示的多：
| 参数 | 作用 |
|---|---|
<目录路径> | 分析指定目录而不是当前工作目录，相对路径按 cwd 解析 |
--full | 强制全量重建，忽略已有图谱 |
--auto-update | 打开自动更新，往 .ua/config.json 写 autoUpdate: true |
--no-auto-update | 关掉自动更新 |
--review | 跑完整的 LLM 图谱复核，替换默认的 inline 确定性校验 |
--language <lang> | 指定产出语言，接受 ISO 639-1 代码或语言名 |
--exclude <patterns> | 逗号分隔的 glob，支持 gitignore 语法（含 ! 取反），优先级高于 .understandignore |
--language 支持 en / zh / zh-TW / ja / ko / ru，影响节点摘要、Dashboard 的按钮与提示文案、导览解释。首次在非英文会话里跑，它会问你要不要中文，选完存进 .ua/config.json，之后一直复用。
跑完 .ua/ 长这样：
| 文件 | 是什么 | 提交吗 |
|---|---|---|
knowledge-graph.json | 主产物，图谱本体 | 提交 |
meta.json | lastAnalyzedAt / gitCommitHash / version / analyzedFiles | 提交 |
config.json | 语言偏好、autoUpdate 开关 | 提交 |
.understandignore | 排除规则 | 提交 |
intermediate/scan-result.json | 扫描阶段的确定性文件清单 | 提交 |
intermediate/ 其余 | 各阶段中间产物 | 不提交 |
.trash-<时间戳>/ | 清理暂存，7 天后延迟清 | 不提交 |
scan-result.json 单独说一句：清理中间产物时它是唯一被留下的。仓库注释给了原因：增量跑如果没有这个文件，Phase 1 必须重新派发扫描，每次增量白烧约 157k tokens、约 158 秒。这条注释比很多项目的 README 都实在。
三、它认得你的技术栈吗
我判断一个分析工具能不能用，先看这道筛子。翻了仓库里的规则库：
语言 24 种，规则文件从 cpp、csharp 排到 terraform、protobuf、graphql，中间有 Go、PHP、Python、Rust、Kotlin、Swift、SQL、Dockerfile、YAML、CSS、Markdown。
框架 10 种：gin、nextjs、vue、react、django、express、fastapi、flask、rails、spring。识别出框架后，扫描器拿到的上下文不一样，分层判断跟着变。
节点 13 类，这一项比前两项重要：
config 配置文件（YAML / JSON / TOML / env）
document 文档（Markdown / RST / TXT）
service 可部署服务定义（Dockerfile / K8s）
table 数据库表或 migration
endpoint API 端点或路由定义
pipeline CI/CD 流水线配置
schema Schema 定义（GraphQL / Protobuf / Prisma）
resource 基础设施资源（Terraform / CloudFormation）
加上 file / function / class / module / concept 五个代码节点。Dockerfile、K8s 清单、Terraform、SQL migration、API 路由表、CI 配置，跟源码进同一张图。节点 ID 有固定格式，比如 function:<相对路径>:<函数名>、table:<相对路径>:<表名>，可以拿这些 ID 在脚本里精确定位。
边 26 类，七组：结构（imports / inherits / implements）、行为（calls / subscribes / publishes / middleware）、数据流（reads_from / writes_to / transforms / validates）、依赖（depends_on / tested_by / configures）、语义（related / similar_to）、基础设施（deploys / serves / provisions / triggers）、Schema（migrates / documents / routes / defines_schema）。边带权重，contains 是 1.0，calls / exports 是 0.8。
数据流和基础设施那两组是我最想要的。能回答"改了这个表影响谁""这个镜像被哪几个服务部署"的图，跟一张只有 import 关系的图，使用场景不重叠。
四、确定的事交给解析器，意思交给模型
README 里两句话带过的设计，是这项目最该抄的一处。
Tree-sitter 管确定性那半边。 源码解析成语法树，抽 import、export、函数与类的定义、调用点、继承关系。同样的输入，每次跑出同样的边。它顺带干了件工程化的事：import 关系在扫描阶段预解析成 importMap 传给文件分析器，避免每个分析器自己再从源码推一遍。这一下省两笔，token 和一致性。
LLM 管语义那半边。 拿解析结果加原始源码，产出解析器给不出的东西：一句人话的摘要、标签、架构分层归属、业务域映射、导览路线、语言特性提示。
这个分工解释了一件事：图在结构侧可复现，语义侧能抓意图。很多同类工具一上来就把整个仓库丢给模型，得到一张每次都长得不一样的图，好看，改不动，也 review 不了 diff。
作者在首页丢了个反问，200,000 行代码，你从哪儿开始。后面跟着全文最清醒的一句：图谱的价值不在于让你惊叹这个代码库有多复杂，在于安静地教会你每一块怎么拼上去。
五、主流水线跑 6 个 agent
README 的功能表列了 5 个给 /understand，1 个给 /understand-domain，1 个给 /understand-knowledge，加起来 7 个。我把主 skill 定义里的 agent 名过了一遍，主流水线实际派发 6 个，README 漏了一个：
| Agent | 职责 | 归属 |
|---|---|---|
project-scanner | 发现文件、识别语言与框架 | /understand |
file-analyzer | 抽函数/类/import，产出节点与边 | /understand |
assemble-reviewer | 复核批次合并结果，捞回丢失的节点与边，补跨批次缺口 | /understand |
architecture-analyzer | 识别架构分层（API / Service / Data / UI / Utility） | /understand |
tour-builder | 生成按依赖排序的导览路线 | /understand |
graph-reviewer | 校验图谱完整性与引用完整性 | /understand |
domain-analyzer | 抽业务域、流程、步骤 | /understand-domain |
article-analyzer | 从 wiki 文章里抽实体、主张、隐性关系 | /understand-knowledge |
漏掉的那个 assemble-reviewer 干的是脏活：脚本把各批次子图合并完之后，语义问题抓不出来，节点被覆盖、跨批次的边断掉，全靠它回来捡。文件分析器并行跑，最多 5 个 worker、每批 20 到 30 个文件。
仓库里 agent 定义文件一共 10 个，除了上面 8 个还有 design-analyzer（给 Figma 用）和 knowledge-graph-guide。
还有个取舍：graph-reviewer 默认只做 inline 校验，要完整的 LLM 复核得显式加 --review。默认省下的那部分 token 是给大仓库留的活路。
六、图谱就是 JSON
产物是 JSON 文件，就该跟着代码走。把 .ua/ 提交进仓库，队友 clone 下来跳过整条多 agent 流水线，不用再烧一遍 token。官方只建议忽略两样本地杂物：
.ua/intermediate/
.ua/diff-overlay.json
图谱超过 10 MB 上 git-lfs。
自动更新的机制，README 写错了。 README 说 /understand --auto-update 通过 post-commit 钩子更新。翻 hooks/hooks.json，没有 post-commit，挂的是另外两个：
SessionStart：每次开会话比对meta.json里的gitCommitHash和当前git rev-parse HEAD。不一致判定图谱过期，往会话注入一条指令，让 agent 读hooks/auto-update-prompt.md并执行更新，明确写了不让它问你确认。PostToolUse（匹配 Bash）：每次跑完 Bash 命令触发一次增量更新判定。
--auto-update 这个参数不装钩子，只往 .ua/config.json 写 autoUpdate: true。钩子是插件自带的，参数是开关。
成本分级也写得很细：只删文件的提交、只改被忽略文件的提交、只改生成产物的提交、纯格式化的提交，一个 LLM agent 都不派；局部结构变更只对真正发生结构变化的文件派 file-analyzer；架构和导览这两个贵 agent 只在计划明确要求时才跑。
另一层是看图那一步彻底剥掉了模型。图谱生成并提交之后，任何人一条命令打开完整 Dashboard，不需要 Claude Code，不需要 LLM，不需要 API key，只要 Node.js ≥ 18：
npx https://github.com/Egonex-AI/Understand-Anything/releases/latest/download/understand-anything-viewer.tgz /path/to/project
终端打印一个带 token 的本地地址，浏览器打开就是完整面板，能平移、缩放、搜索。数据只读本地磁盘，不出机器。老员工在 CI 里更新图谱，新同事第一天 clone 仓库跑一条 npx，拿到一张标好分层和导览路线的图，整个链路没有一次模型调用。
七、平台矩阵，和一个容易踩的坑
支持列表拉到 17 个：Claude Code（原生插件）、Cursor、VS Code + Copilot、Copilot CLI、Codex、OpenCode、OpenClaw、Antigravity、Gemini CLI、Pi Agent、Vibe CLI、Hermes、Cline、KIMI CLI、Trae、Nanobot、Kiro。
非 Claude Code 的平台走一行安装脚本，脚本把仓库 clone 到 ~/.understand-anything/repo，再给目标平台建软链：
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash # 跳过交互直接指定平台 curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s codex
装完记得重启 CLI 或 IDE。更新和卸载：
./install.sh --update ./install.sh --uninstall codex
Windows 走 PowerShell：iwr -useb .../install.ps1 | iex，更新卸载用 -Update / -Uninstall <platform>。
坑在调用前缀。多数平台吃 /understand，Codex 吃的是 $understand，敲斜杠没反应别以为装坏了。两边都不认的平台，直接说人话：Use the understand skill to analyze this project.
八、代价得说清楚
README 里有一段自曝，比一堆宣传语有用：首次 /understand 会分析整个代码库，在大项目上吃掉相当可观的 token。作者建议走订阅额度，或者把模型指到本地 Ollama。后续再跑默认增量，只重分析改动过的文件。
另外三笔账：
- 图谱体积。10 MB 以上建议 git-lfs，否则仓库会肿。
- 新鲜度。图谱和代码是两份东西，忘了更新它就开始撒谎，而一张过期的架构图比没有架构图危险。
--auto-update是这套玩法能长期成立的前提，记住它只是写了个开关，干活的是插件自带的两个钩子。 - 仓库规模。巨型 monorepo 用
/understand src/frontend圈范围，全量扫不划算。
小项目别用。几千行的库，人脑扛得住，一张图不如你直接翻两个文件。
九、保留意见
我对这类工具的怀疑从来不在技术，在习惯。图谱第一次生成时所有人都会去看，一周之后没人点开，.ua/ 里的 JSON 慢慢变成仓库里一坨没人敢删的遗产。
能不能落地取决于两件事：有没有人在 CI 或钩子里保证它每次是新的，有没有人真养成改之前先看一眼影响面的动作。技术上它把门槛降到一个参数，剩下的在团队自己手里。
做 AI 编码助手相关的工程，可以把它的三个决策抽出来看：确定性解析与语义理解的边界怎么划，最贵的中间产物怎么变成可提交的文件，怎么让看图这一步彻底不依赖模型。这三条换任何技术栈都成立。
十、照着敲一遍
# 0. 装（Claude Code） /plugin marketplace add Egonex-AI/Understand-Anything /plugin install understand-anything # 1. 第一次建图，中文产出；中途会让你确认 .understandignore，认真过一遍 /understand --language zh --auto-update # 2. 打开面板，按架构分层扫一遍 /understand-dashboard # 3. 生成导览，跟着走一遍 /understand-onboard # 4. 用提问补导览没覆盖的部分 /understand-chat 认证是怎么串起来的？ # 5. 深挖某个具体文件 /understand-explain src/auth/login.ts # 6. 抽业务域，看代码到业务流程的映射 /understand-domain # 7. 等你开始改代码，再看影响面 /understand-diff
日志太乱想重建一次干净的加 --full；范围太大用 /understand src/frontend 圈；排除规则除了 .understandignore 还能临时用 --exclude "tests/*,docs/*" 压过去。
跑完第一次，去做那件真正重要的事：把 .ua/ 提交进仓库。
装完先跑 /understand，再开面板。别搜。先把分层图例点开，看哪种颜色最厚，那一层就是你接下来一个月的麻烦。