Understand Anything 配套工作流

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end --> Understand Anything 和 Tesserae 是互补项目。

• Understand Anything 擅长生成代码库知识图谱和交互式仪表板。
• Tesserae 专注于长期存在的智能体记忆：文档、markdown/wiki 编译、静态发布、会话历史以及面向智能体的导出。

Tesserae 不应内置或吸收 Understand Anything。应将其视为一个独立的配套工具，用来生成有用的图谱产物。

为什么两者都用？

Understand Anything 可以写入：

.understand-anything/knowledge-graph.json

该图谱捕获文件、函数、类、模块、概念、依赖、层和导览等代码结构。

随后 Tesserae 可以将该产物与项目记忆的其余部分一起保存：

• 源文档和 markdown 页面；
• 仓库文件；
• 研究笔记；
• 本地 Claude Code / Codex 会话历史；
• 生成的静态 wiki 页面；
• 2D / 3D 图谱网站视图；
• llms.txt、llms-full.txt、search-index.json、graph.json 以及每页对应的智能体 sibling。

当前低摩擦工作流

推荐路径是设置向导：

tesserae project setup

在配套工具步骤中选择 Understand Anything。Tesserae 会在请求时安装/更新配套 skills，并把受管理的刷新命令写入 .tesserae/config.json。之后调用 tesserae project compile 时，如果 UA 图谱缺失或过期，就会自动运行该包装命令。

对于非交互式自动化，请使用：

tesserae project setup \
  --yes \
  --with-understand-anything \
  --install-understand-anything \
  --understand-anything-platform codex
tesserae project compile

存储的命令由 Tesserae 管理，不需要用户自行构造：

tesserae project refresh-understand-anything --platform codex

编译期间，Tesserae 会：

1. 检查 .understand-anything/knowledge-graph.json 是否存在，并在元数据可用时确认它与当前 git 提交匹配；
2. 仅当图谱缺失/过期或强制刷新时，运行已配置的智能体平台（codex、opencode 或 claude）；
3. 验证图谱已经写入；
4. 生成 .tesserae/external/understand-anything.md；
5. 继续正常的记忆编译。

你可以在编译前强制运行所有已配置的外部刷新命令：

tesserae project compile --refresh-external-tools

也需要 Cognee？在同一 setup 命令中添加运行时记忆标志：

tesserae project setup \
  --yes \
  --with-understand-anything \
  --install-understand-anything \
  --understand-anything-platform codex \
  --run-cognee \
  --install-cognee

手动等效流程

推荐使用受管理的设置路径。如果你有意在 Tesserae 之外使用 UA，请先在你的智能体环境中运行 Understand Anything：

/understand

然后运行 tesserae project setup --with-understand-anything，让 Tesserae 记录 markdown 投影源。直接的 JSON 文件会保留为原始配套产物，而不是手动输入的源路径。

tesserae project setup --with-understand-anything
tesserae project compile
tesserae project build-site

如果你还想要本地智能体会话记忆：

tesserae project sessions discover --import
tesserae project build-site

原生图同步

Tesserae 仍然保留便于阅读的 markdown projection，同时当配置的工具使用 sync_mode: native_graph 时，会在 compile 期间原生导入 UA 图。

原生适配器读取 .understand-anything/knowledge-graph.json，把 UA 节点/边映射到 Tesserae 的受控 ontology，并写入同步 manifest：

.tesserae/external/understand-anything-sync.json

当前映射：

Concept synchronization 会做 canonicalization，而不是盲目创建重复节点。如果 UA 输出 Mermaid Rendering，而 Tesserae 已有 Mermaid rendering，compile 会保留一个 concept node，并在 metadata.external_refs 下添加 UA provenance。

Tesserae 仍然是 memory compiler；UA 仍然是独立的 companion graph generator。

协作原则

不要把 Tesserae 描述为 Understand Anything 的替代品。

更好的表述：

• Understand Anything 帮助开发者当下理解代码库。
• Tesserae 帮助智能体长期记忆、搜索、引用、更新并发布项目知识。