架构图别再手画：archify 技能让 agent 出图前先过 9 项校验

写 README 或者交接文档的时候，你总得在文字之外再给一张结构图。手画一张不算难，难的是它从画完那一刻就开始过期：重构了两个模块、加了一条消息队列，图还停留在上个月的样子，下一次有人照着它理解系统，就被带偏了。

archify 是 Hermes 的可选技能里专门解决这类问题的一个：你用一段结构化的 JSON（或者直接把草稿 Mermaid 丢进去），它产出一张自包含、可交互的 HTML 图，而且在交给你之前会跑一遍校验。

它到底做什么

简单说，archify 把“图”当成一种有 schema 的产物，而不是一张画：

  • 支持五种图类型：architecture（架构）、workflow（流程）、sequence（时序）、dataflow（数据流）、lifecycle（状态机）；
  • 输出是自包含的 HTML：深色/浅色主题、平移缩放、搜索、关系追踪，可选的运动轨迹效果，导出 PNG / JPEG / WebP / SVG / WebM；
  • 输入可以是大白话的需求描述，也可以是你从别处复制来的 Mermaid（支持 flowchart、sequenceDiagram、stateDiagram）；
  • 当图必须反映真实代码时，它还能去读仓库里的证据（代码结构、调用关系），而不是凭你的描述硬编。

关键差别在最后一步：每个候选产物都要过一遍 9 项 validate / deliver 校验，并给出回执。也就是说，“图对不对”这个问题有一个可检查的答案，而不是靠肉眼看。

安装

hermes skills install official/creative/archify

这是一个官方可选技能（optional skill），不在默认安装里，显式装才有。它归属于 optional-skills/creative/archify，作者是 tt-a1i，MIT 许可，版本 2.17.0。

有一处设计值得知道：Hermes 端更像一个上游维护的目录条目。技能目录本身在 tt-a1i/archify 上游维护（Node CLI、schema、渲染器、示例、参考文档都在那边），安装时会从那个仓库实时拉取当前代码树，并且和其它 hub 安装一样经过隔离与扫描。好处很直接：内置副本不会过期。

前置条件只有一条：Node.js 18+ 在 PATH 上。安装过程会从 GitHub 拉大约 200 个文件（约 8 MB，主要是上游的测试和示例），拉取被固定到一个 tree SHA 上。装完可以用这行确认：

node bin/archify.mjs doctor

技能包内部不需要跑 npm install。

五种图，同一套用法

对使用者来说，流程是一样的：描述你要什么 → 拿到 HTML 图 + 校验回执。

实际使用时几个判断可以省时间：

  • 想表达“系统由哪些部分组成、它们怎么连”→ architecture；
  • 想表达“一次请求按什么顺序经过哪些步骤”→ workflow 或 sequence（前者偏流程分支，后者偏参与者之间的往返）；
  • 想表达“数据从哪来、经过哪些处理、落到哪”→ dataflow；
  • 想表达“这个对象有哪些状态、什么事件触发迁移”→ lifecycle。

如果手上已经有 Mermaid（很多人的会议记录和 issue 里就有），直接粘进去让它转成可交互版本，比重新描述一遍省事得多。

和内置画图技能的分工

Hermes 自带一个 architecture-diagram 技能，零依赖，是 archify 的兜底选项（两者同源，都出自 Cocoon AI 那条线）。

选择标准很简单：

  • 只要一张图、不想装 Node、不需要交互和导出 → 用内置的；
  • 想要校验回执、需要 Mermaid 转换、需要时序/状态机这类更专门的图型、或者需要导出成 PNG/SVG/WebM 等多种格式 → 用 archify。

两个使用注意

  1. 更新检查只打印提示。上游的“更新感知”步骤会跑 scripts/check-update.mjs，它读取 GitHub 上的发布清单，只打印一行通知，不下载也不安装任何东西。如果你的环境不希望有对外请求，这一步可以跳过。
  2. 它读取代码是有前提的。让 archify 去仓库里找证据时，它读的是你当前工作目录里的内容——所以在仓库根目录调用它，比在一个空的临时目录里调用要靠谱得多。

小结

archify 的价值点不在于“agent 会画图”（这早就不稀奇了），而在于它把图当成有 schema、有校验、有回执的产物：五种图型对应五种明确的表达意图，输入可以是结构化 JSON 或现成 Mermaid，输出是可交互 HTML 加多种导出格式，而上游维护的目录结构保证你拿到的不是一份过期的内置副本。

如果你在挑可选技能，新增的可选技能那篇给了更全的视角；可视化相关还可以看把办公室画成 3D 的那篇和桌面技能中心；技能安装、信任与目录管理的完整命令在 hermes skills 参考。