diagrams

用途

Diagrams 用于从结构化 JSON 生成可视化图表，输出 SVG（可选 PNG）。适用于用户要求绘制流程图、用户流程图、架构图或系统图等场景。

主要能力

将 ELK JSON 描述渲染为 SVG，批量模式可输出到 svg/ 子目录。
批量加 PNG 仅限 macOS，使用 sips 转换。
节点支持 id、宽高、labels（供 ELK 布局计算）、label（SVG 显示文本，支持 emoji）、color（调色板键）、subtitle、fontSize、children（嵌套节点，使其成为容器）、containerColor。
边支持 id、sources、targets、labels（含 text、width、height）、edgeColor（十六进制，默认 #64748B）、dashed、strokeWidth（默认 1.5）。
内置 8 种语义颜色：action（蓝，系统动作）、external（青，外部服务）、decision（粉，决策点）、user（橙，用户动作）、success（绿，正向结果）、negative（红，负向结果）、neutral（灰，中性/信息）、data（琥珀，数据/产物）。每个 SVG 底部自动渲染图例，可在根图设置 "legend": false 隐藏。
布局选项：elk.direction（DOWN 默认、RIGHT、LEFT、UP）、elk.algorithm（layered 默认、force、stress）、elk.spacing.nodeNode、elk.layered.spacing.nodeNodeBetweenLayers、elk.padding。

使用方式

在目标目录安装 elkjs（若尚未安装）：

cd <project>/docs/diagrams && npm init -y && npm install elkjs
# Set "type": "module" in package.json

编写描述图表的 ELK JSON 文件。
渲染：

# Single file
node <skill-dir>/scripts/render-elk.mjs diagram.json output.svg

批量：文件夹中所有 .json 文件 → svg/ 子目录：

node /scripts/render-elk.mjs --dir

批量 + PNG（仅 macOS，使用 sips）：

node /scripts/render-elk.mjs --dir  --png

嵌入 markdown：

![Diagram Title](diagrams/svg/my-diagram.svg)

ELK JSON Schema

{
  "id": "root",
  "title": "Diagram Title (rendered as heading)",
  "layoutOptions": {
    "elk.algorithm": "layered",
    "elk.direction": "DOWN",
    "elk.spacing.nodeNode": "30",
    "elk.layered.spacing.nodeNodeBetweenLayers": "40",
    "elk.padding": "[top=40,left=20,bottom=20,right=20]"
  },
  "children": [
    {
      "id": "node1",
      "width": 220,
      "height": 45,
      "labels": [{"text": "Node label for ELK layout"}],
      "label": "📦 Display label (rendered in SVG)",
      "color": "core",
      "subtitle": "Optional second line"
    }
  ],
  "edges": [
    {
      "id": "e1",
      "sources": ["node1"],
      "targets": ["node2"],
      "labels": [{"text": "Yes", "width": 25, "height": 14}],
      "edgeColor": "#10B981",
      "dashed": true
    }
  ]
}

设计建议

尺寸：大多数节点宽 200-280px；单行标签高 45px，两行标签高 55px。
决策节点：使用 decision（粉色）表示是/否分支。
边标签：保持简短（Yes/No/Error），设置 width/height 以正确定位。
容器：为节点添加 children 数组，使用 containerColor: "step" 表示浅蓝色分组。
手动与自动路径：对替代/可选路径使用 dashed: true。
标题：在根图设置 title，可在图表上方渲染标题。
标签中的 emoji：支持并鼓励用于视觉扫描。

限制与注意事项

容器布局：ELK 的 layered 算法在 RIGHT 方向嵌套容器时可能产生重叠布局。容器建议使用 DOWN，或若需水平则展平为非容器布局。
labels 与 label：labels（数组）供 ELK 计算布局间距，label（字符串）渲染到 SVG。应始终同时设置，labels[0].text 应接近显示标签长度以正确计算尺寸。
package.json 必须设置 "type": "module" 才能使用 ESM 导入。
elkjs 必须安装在运行脚本的本地目录，不是全局安装。
批量 PNG 仅限 macOS。

技能介绍

用途

主要能力

使用方式

ELK JSON Schema

设计建议

限制与注意事项