先画地图再读代码：Understand-Anything 在 NEHermes 里的安装与实测

loveyihui

先画地图再读代码：Understand-Anything 在 NEHermes 里的安装与实测

接手陌生项目最难的不是读代码，是不知道从哪开始读。Understand-Anything（下称 UA）用 Tree-sitter 抽结构、用 LLM 写摘要，把一个项目变成 knowledge-graph.json，再用一个可缩放、可搜索的仪表盘展示：每个文件、类、函数是节点，点开是中文摘要和依赖关系。

它的目标不是“图有多炫”，是“这张图能教你东西”。

一、安装（macOS，本文实测）

前提：Node ≥ 22 与 pnpm。NEHermes 自带 Node 26，pnpm 用 corepack 开：

1. corepack enable pnpm

复制代码

能连 github.com 时，官方一行安装：

1. curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s hermes

复制代码

它把仓库克隆到 ~/.understand-anything/repo，并在 ~/.hermes/skills/understand-anything 建一条软链——9 个技能随即被 Hermes 读到。

若像本文实测环境一样 git clone 连不上 github.com（等 75 秒超时），改用 codeload 的 tar 包 + 两条软链，效果完全一样：

1. curl -sSL https://codeload.github.com/Egonex-AI/Understand-Anything/tar.gz/refs/heads/main -o /tmp/ua.tgz
   
2. mkdir -p ~/.understand-anything && tar xzf /tmp/ua.tgz -C ~/.understand-anything
   
3. mv ~/.understand-anything/Understand-Anything-main ~/.understand-anything/repo
   
4. ln -sfn ~/.understand-anything/repo/understand-anything-plugin/skills ~/.hermes/skills/understand-anything
   
5. ln -sfn ~/.understand-anything/repo/understand-anything-plugin ~/.understand-anything-plugin

复制代码

首次分析会自动构建 core 包（pnpm install && pnpm --filter @understand-anything/core build），也可以先手动跑一遍。装完在会话里问一句“列一下 understand 相关的技能”，能列出 9 个就说明通了。

二、在 NEHermes 里怎么用

Hermes 不解析 /understand 这类斜杠命令，但技能就是一份 SKILL.md，说人话即可触发：

• 直接下指令：“用 understand 技能分析 ~/work/myproj，输出中文”
• 让它先读技能：“读 understand 技能，按它的流程分析 ua-demo”
• 只要仪表盘：“按 understand-dashboard 技能把图谱开起来”
  

技能内部的多代ne理流水线（扫描 → 逐文件分析 → 架构分层 → 导览 → 校验）在 Hermes 上由 delegate_task 分派；--language zh 照常生效，摘要、层名、导览全是中文。

技能	用途
understand	全量/增量分析，产出图谱
understand-dashboard	启动仪表盘
understand-chat	用图谱回答“支付流程怎么走”
understand-diff	看本次改动的影响面
understand-explain	单文件/单函数深挖
understand-onboard	给新人生成上手路线

另有 understand-domain（业务域）、understand-knowledge（LLM wiki）、understand-figma（设计稿）。

也可以完全绕过技能手动起仪表盘（图谱已生成时）：

1. cd ~/.understand-anything-plugin/packages/dashboard
   
2. GRAPH_DIR=/path/to/project npx vite --host 127.0.0.1

复制代码

终端会打印 🔑 Dashboard URL: http://127.0.0.1:5199/?token=... ，把整条 URL 贴进 NEHermes 的预览窗（或浏览器）即可。

三、实测：12 个文件的小服务

样本 ua-demo：HTTP 接入层 → 服务层 → 仓储层 → 领域模型，11 个 Python 文件共 337 行 + README。

指标	结果
阶段	7/7 全部跑通
节点	31（文件 11 / 类 11 / 函数 8 / 文档 1）
边	65（contains 19、exports 19、imports 12、calls 12、depends_on 2、documents 1）
分层	6 层：接入/服务/仓储/领域/工具/文档，12 个文件级节点全部归属
导览	8 步，按依赖顺序从 README 讲到 user_service.py
校验	0 issue，4 条 warning（全指向空 __init__.py 的孤立节点）
耗时	端到端约 25 分钟，3 个 file-analyzer 子代ne理并行占了大部分
产物	.ua/knowledge-graph.json，37.9 KB

导览不是目录复读，而是带因果的讲法。第 3 步原文：

HTTP 请求适配与路由分发：承接上一步的装配结果，make_handler 负责把 http.server 的原始请求读成 JSON body 与 query 参数，再交给 Router.resolve 按 (method, path) 落到具体 handler…

仪表盘直接开在 NEHermes 右侧预览窗，不用切 App：



点任一图层即下钻，看到该层的文件级节点和跨层连线（悬停出现 Focus / Open code / Start Tour）：



点文件节点，右侧给出中文摘要、TAGS 与连接关系——价值在这里，不在炫技：



四、五个坑

• github.com 的 git clone 常超时。raw.githubusercontent.com 和 codeload.github.com 通常能通，用上面的 tar 包路线，或给 UA_REPO_URL 套镜像。
• 斜杠命令不存在。技能正文写的是 Claude Code 的 Task/Agent 工具，Hermes 里对应 delegate_task；不会因此失效。
• token 与文件数成正比。大仓库先 --exclude "tests/*,docs/*" 或直接喂子目录；超过 100 个文件技能会先提醒你。
• 仪表盘 URL 必须带 ?token=，剪掉就是 Access Token Required；重启服务 token 会变。
• 空文件也会成节点。零行的 __init__.py 保留文件节点、没有边，校验报 orphan 属正常。
  

五、小结

UA 干的是“读之前先画地图”：一次分析换一份可点、可搜、可问的结构，之后增量更新只重算改动文件。装一次 3 分钟，跑通一个小项目 25 分钟——比盲读几百上千行便宜得多。