SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场make-diagram

make-diagram

设计与创作

查看项目

更新于 10-20 02:50

技能介绍

make-diagram 是一个以 skill（SKILL.md）形式分发的图表生成工具，帮助 AI 根据用户需求产出架构图、流程图、时序图或状态图，输出为一个精良的离线 HTML 页面，并附带可播放的“故事”（分章节的节拍动画）。

用途

核心思路是只写一份 JSON 文件 diagram.json：包含标题、类型、节点与边（或参与者与消息），通常还包含一到两个故事——由命名章节组成的节拍序列，每个节拍是沿一条边的一次跳转，带标题与说明。脚本负责用 ELK 布局、检查几何，并构建单个离线 HTML 页面，页面带有故事播放器、Explore 面板和全屏功能。使用者不需要写坐标、CSS、SVG 或 HTML。

图表类型与节点种类

  • architecture（架构图）：service（默认）、client、user、database、storage、queue、cache、function、gateway、external、other。可选 groups，最多嵌套 3 层，边可以终止于一个分组。
  • flow（流程图）：step（默认）、start、end、decision、io、subprocess、wait。默认方向向下。
  • state（状态图）：state（默认）、start、end、choice。允许状态到自身的转移。
  • sequence（时序图）：participants 种类为 service（默认）、actor、database、queue、external；messages 种类为 sync（默认）、async、reply、self（from = to）。

每个节点或参与者可以携带 emoji（恰好一个表情，绘制在图标位置，裸形状不支持）和 detail（最多 400 字符纯文本，读者点击节点时在 Explore 面板显示）。每种种类有各自的颜色族，用于给卡片和出边着色；tone（neutral、accent、good、warn、bad）只覆盖边框和图标颜色。图标可通过图标检索脚本获得引用（如 lucide:database 或 brand:postgresql），不确定时可省略，多数种类有默认图标。

书写规则

标签用名词（如“Orders DB”），边和消息标签用动词（如“writes order”）。标签不超过 48 字符，注释不超过 60（单行），边标签不超过 40，标题不超过 120，副标题不超过 160。id 为小写字母、数字、-、_，以字母开头。最多 12 个节点阅读效果最佳，更大的系统建议拆成多张图（硬上限：60 节点、120 边、12 参与者、60 消息）。direction（right 或 down）适用于图形类图表，不适用于序列图。

边样式与故事

边样式有 solid（默认，图例键“call”）、dashed（图例键“secondary”，用于回复、“否”分支或次要路径）、async（图例键“event”）；both: true 在两端画箭头。序列图消息会显示“call”“event”“reply”或“self”。

stories 最多 8 个章节（id、title、beats），章节标题不超过 40 字符，总共 60 个节拍，作为一条时间线播放。每个节拍有标题（不超过 48 字符）和可选说明（不超过 160 字符，镜头停留时读者听到的一句话），并且恰好指定一个目标：

  • from 与 to：两个节点之间的那一条边（架构图中分组也算，序列图中参与者也算）。逆着箭头方向命名两端会反向播放该跳转，可用于回复。
  • edge：边 id（没有 id 的边为 edge-<index>），或序列图中的消息 id。
  • focus：镜头对准并高亮节点、分组或参与者 id，没有移动圆点，用于开场或收尾镜头。

建议为主路径写一个故事（3 到 8 个节拍），为每条支路（重试、失败、事件）各写一个。节拍标题用简短的现在时句子，说明补充标题未包含的那个事实。只有当没有可叙述内容时才省略 stories，此时构建会按布局层生成节拍（序列图按消息）。autoplay 为 true 时页面打开即开始播放（在减少动态效果设置下忽略）。steps 是旧的漫游形式，新图不要使用。

序列图还支持 frames（loop、alt、opt、par）覆盖一段连续的消息 id，可嵌套；notes 在消息之后把一段短文字放在参与者上方。

工作流程

所有命令在项目文件夹（diagram.json 所在处）运行，使用脚本的完整路径。步骤包括：

  1. 运行 doctor 脚本做环境检查（需要 Node；针对 check 时需 Playwright 与浏览器）。若报告缺失项，告知用户每一项、为何需要、大小与命令，以及输出中的 notes 和 info 条目，征得同意后用 --fix 安装；对拒绝、跳过、安装在别处或失败的项目，给出用户自行运行的准确命令。
  2. 选择类型并编写 diagram.json，可参考示例文件与 schema。
  3. 运行 validate 脚本校验，按输出逐行修复直到显示 valid（退出码 0 正常，1 规格错误，2 用法错误）。
  4. 设置 generatedBy 为所运行的模型、effort 级别（若知道）和宿主（如 Claude Code、Codex、Copilot CLI、Gemini CLI），不知道的字段留空；构建脚本的 --model、--effort、--agent 可覆盖。运行 build 脚本打印 HTML 路径，默认输出到 ~/.agent/diagrams/（或 PA_OUTPUT_DIR 环境变量指定的文件夹），--out 可改路径，--theme（dusk、press、poster、paper、blueprint、ink、editorial）覆盖主题，默认 blueprint。
  5. 运行 check 脚本在桌面和手机宽度下打开页面，检查溢出、控制台错误或节点压在图例浮层下；需要 Playwright 与浏览器，缺失时干净跳过（退出码 0）。

最后报告 HTML 路径、一句话说明图表内容，以及操作提示：Play story（或 P）打开第 1 拍，Space 播放，E 探索，F 全屏。修改需求（如重命名、增加节拍）时只改 diagram.json 中相应字段，再校验并构建。

限制与安全

若无法运行 shell 命令，则写 diagram.json 并把第 3、4、5 步的准确命令交给用户（附真实 skill 目录路径）。页面中标签、说明和 id 均被转义，不会被当作标记读取；规格不接受 URL、CSS、SVG 或 HTML。页面不发起网络请求，其 CSP 阻止外联。标签和说明中不要放机密信息。