dynamic-archify

Dynami-carchify Skill

创建专业技术图表，并将其制作为独立的 HTML 文件，其中包含内联 SVG、主题切换开关和内置的图像/SVG 导出菜单。

每张图表都带有深色/浅色主题切换开关（设置会保存在 localStorage 中，并遵循 prefers-color-scheme）、导出菜单（将 PNG 复制到剪贴板；以最高 4× 分辨率原生栅格化并下载 PNG/JPEG/WebP；下载会遵循嵌入宿主 prefers-color-scheme 的双主题 SVG——非常适合 GitHub README），以及CSS 变量颜色系统，确保两种主题保持一致。

设置（仅渲染器模式需一次性设置）

四种类型化渲染器使用 ajv 根据架构验证 JSON。在此 Skill 文件夹中：

npm install

即使没有安装，渲染器仍会运行——它们会打印警告并跳过架构验证，但会保留自身的布局检查。生成的 HTML 不依赖任何项；只有渲染器有依赖。

如果你完全无法访问 shell（例如，此 Skill 是作为项目知识添加的），则每次请求都改用架构模式：按照下方的设计系统，将 SVG 手动放入 assets/template.html，并在交付前运行自查清单。

选择图表类型

类型	用途	方法
architecture	系统组件、云资源、服务、安全边界、基础设施	renderers/architecture/render-architecture.mjs + JSON（或在无法运行渲染器时手动放置 SVG）
workflow	技术流程、审批关卡、工具调用、运行手册、CI/CD、事件响应	renderers/workflow/render-workflow.mjs + JSON
sequence	API 调用链、请求生命周期、缓存回退、异步跟踪、返回路径	renderers/sequence/render-sequence.mjs + JSON
dataflow	数据管道、ETL/ELT、PII 隔离、数据沿袭、数据仓库同步、使用方	renderers/dataflow/render-dataflow.mjs + JSON
lifecycle	状态机、状态转换、等待状态、重试、终止状态	renderers/lifecycle/render-lifecycle.mjs + JSON

触发短语：“架构/系统/云图” → architecture（除非明确以流程为主）。“工作流/流/流程/运行手册/审批/CI-CD/事件” → workflow。“序列/交互/调用链/谁调用谁” → sequence。“数据流/管道/ETL/沿袭/PII/治理” → dataflow。“状态/状态值/生命周期/状态机/重试/终止” → lifecycle。

将 Mermaid 作为输入方言

当用户粘贴 Mermaid 代码时，不要尝试机械地渲染或解析它——应根据其结构，从头布局，并选择匹配的 archify 模式：

Mermaid	Archify 模式	映射
flowchart / graph	workflow（如果是组件图，则用 architecture）	subgraph → 泳道或区域边界；节点形状 {}（菱形）→ 决策/安全节点；--> 标签 → 边标签（少用）；classDef/style → 最接近的语义类型
sequenceDiagram	sequence	participant → 参与者（根据名称选择语义 type）；->> → 消息，-->> → return 变体；Note → 消息 note；rect 块 → 分段
stateDiagram	lifecycle	状态 → 状态（根据名称选择 start/active/waiting/success/failure）；[*] 开始/结束 → start 类型/terminal 泳道；转换标签 → 类似事件的标签

舍弃 Mermaid 样式；只保留拓扑结构和含义。分组方式、泳道顺序以及需要强调的内容由你决定——这份判断正是成果的价值所在。

渲染器模式（工作流 / 序列 / 数据流 / 生命周期）

四种模式都遵循相同的循环：

1. 先阅读：架构（schemas/<type>.schema.json）和完整的示例（examples/*.{workflow,sequence,dataflow,lifecycle}.json）——照着其中的模式编写，不要猜测字段格式。
2. 编写 <name>.<type>.json。
3. 渲染：node renderers/<type>/render-<type>.mjs <input>.json <output>.html（路径相对于此技能文件夹）。
4. 如果失败，错误信息会指出 JSON 路径或修复方法（阈值、有效范围、要更改的参数）。修正 JSON 并重新运行；切勿编辑渲染器。

架构违规会以非零状态码退出，并显示带路径前缀的消息，例如 /nodes/3 (id/label: "router") must NOT have additional properties。渲染器还会针对布局问题快速失败：节点/状态重叠（包括跨泳道）、标签与节点或其他标签重叠、标签宽于其节点、列/行超出范围、边过短，以及图例位于 viewBox 外。CJK 文本会自动按双倍宽度测量。

工作流

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Release Workflow", "subtitle": "PR to production", "output": "release.html" },
  "lanes": [ { "id": "dev", "label": "Developer" }, { "id": "ci", "label": "CI" } ],
  "nodes": [
    { "id": "pr", "lane": "dev", "col": 0, "type": "frontend", "label": "Open PR", "sublabel": "feature branch" },
    { "id": "build", "lane": "ci", "col": 1, "type": "backend", "label": "Build", "sublabel": "lint + test", "tag": "blocking" }
  ],
  "edges": [
    { "from": "pr", "to": "build", "label": "webhook", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop" }
  ],
  "cards": []
}

布局限制：6 列（col 0–5），x 坐标固定为 [88, 220, 300, 430, 500, 625]——第 1↔2 列和第 3↔4 列仅相距 70–80px，因此同一泳道中这些相邻列的默认宽度（92px）节点会重叠；请跳过一列或缩小 width。泳道内容宽度为 640px。省略 meta.viewBox——渲染器会根据泳道数量自动调整高度。边的路由方式：straight、drop（在泳道之间弯折；bias 取值 0–1，用于选择弯折位置）、outside-right、return-left、bottom-channel、up-channel，或显式指定 via 点。相邻步骤之间的边不要加标签；标签仅用于跨泳道转换、审批、异步写入和返回。

序列

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "Cache Miss Request", "subtitle": "auth and cache fallback", "output": "cache-miss.html" },
  "participants": [
    { "id": "web", "type": "frontend", "label": "Web App", "sublabel": "React UI" },
    { "id": "api", "type": "backend", "label": "API", "sublabel": "handler" }
  ],
  "segments": [ { "from": 160, "to": 320, "label": "01 / AUTH" } ],
  "messages": [
    { "from": "web", "to": "api", "y": 200, "label": "GET /data", "variant": "emphasis" },
    { "from": "api", "to": "web", "y": 290, "label": "200 JSON", "variant": "return" }
  ],
  "activations": [ { "participant": "api", "from": 190, "to": 300, "type": "backend" } ],
  "cards": []
}

布局限制：参与者位于 x = 62 + index×108，因此宽 920 的 viewBox 最多容纳 8 个参与者。消息的 y 必须在 [160, viewBox_height − 83] 范围内；共享水平空间的消息之间需要至少 28px 的垂直间距；箭头的水平跨度至少为 60px。segments[].from/to 和 activations[].from/to 是 y 像素坐标，不是参与者 ID。更高的 meta.viewBox（默认值为 [920, 760]）可以提供更多时间线空间。标签应简短，例如："GET /path"、"verify JWT"、"cache miss"、"200 JSON"。

数据流

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "Product Analytics", "subtitle": "events to consumers", "output": "analytics.html" },
  "stages": [ { "label": "Sources" }, { "label": "Ingest" }, { "label": "Store" } ],
  "nodes": [
    { "id": "web", "type": "frontend", "label": "Web App", "stage": 0, "row": 0, "sublabel": "clickstream" },
    { "id": "kafka", "type": "messagebus", "label": "Kafka", "stage": 1, "row": 0, "tag": "accepted events" }
  ],
  "flows": [
    { "from": "web", "to": "kafka", "label": "events", "classification": "PII touch", "variant": "emphasis" }
  ],
  "cards": []
}

布局限制：2–5 个阶段，x = 100 + stage×215；5 行（row 0–4），y 坐标为 [128, 242, 356, 470, 584]；默认节点尺寸为 112×58。默认 viewBox 为 [940, 720]。必须填写流程标签，并使用类似资产名称的短语（"clickstream"、"identity map"、"feature vectors"）；在 classification 中标注敏感性（"PII touch"、"approved only"、"non-PII"）。变体：emphasis = 主路径，security = PII/策略/同意，dashed = 异步/批处理。

生命周期

{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Agent Run Lifecycle", "subtitle": "states and terminal outcomes", "output": "agent-run.html" },
  "lanes": [
    { "id": "main", "label": "Lifecycle phases" },
    { "id": "waiting", "label": "Interruptions" },
    { "id": "terminal", "label": "Terminal exits" }
  ],
  "states": [
    { "id": "queued", "type": "start", "label": "Queued", "lane": "main", "col": 0, "step": "01" },
    { "id": "running", "type": "active", "label": "Executing", "lane": "main", "col": 2, "step": "02" },
    { "id": "approval", "type": "waiting", "label": "Needs Approval", "lane": "waiting", "col": 0 },
    { "id": "done", "type": "success", "label": "Completed", "lane": "terminal", "col": 2 }
  ],
  "transitions": [
    { "from": "queued", "to": "running", "variant": "emphasis" },
    { "from": "running", "to": "approval", "label": "needs approval", "variant": "security", "fromSide": "bottom", "toSide": "right" },
    { "from": "running", "to": "done", "label": "success", "variant": "emphasis", "fromSide": "bottom", "toSide": "top" }
  ],
  "cards": []
}

布局限制——泳道 ID 具有语义且保留使用：必须包含 main，它映射到顶部阶段带（第 0–4 列）；terminal 映射到底部结果带（第 0–2 列）；所有其他泳道 ID 共用唯一的中间事件带（第 0–2 列）——请使用不同的 col 或 yOffset 分隔同一带中的状态。带标题根据你的泳道标签渲染。默认 viewBox 为 [980, 660]。转换标签应简短且体现事件（"retry"、"timeout"、"cancel"）；优先使用状态 tag、step 编号和摘要卡片，而不是在箭头上堆砌标签。请将终止状态放入 terminal 泳道，以明确标示流程结束。

各模式深入指南

每个渲染器都有一份 README，介绍其完整的设计语言（路由预设、语义类型、叙事指南）：renderers/workflow/README.md、renderers/sequence/README.md、renderers/dataflow/README.md、renderers/lifecycle/README.md。在某次会话中首次绘制某种模式的图表之前，请先阅读对应的 README。

架构模式

架构模式与其他模式一样，采用先读取 schema、再渲染的循环——优先使用这种方式。无法运行渲染器时，再使用手动放置的 SVG。

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Sample Web App", "subtitle": "3-tier SaaS on AWS", "output": "web-app.html" },
  "components": [
    { "id": "users", "type": "external", "label": "Users", "sublabel": "Browser", "pos": [40, 300] },
    { "id": "api", "type": "backend", "label": "API Server", "sublabel": "FastAPI :8000", "pos": [460, 300] },
    { "id": "db", "type": "database", "label": "PostgreSQL", "sublabel": ":5432", "pos": [680, 300] }
  ],
  "boundaries": [
    { "kind": "region", "label": "AWS us-west-2", "wraps": ["api", "db"] }
  ],
  "connections": [
    { "from": "users", "to": "api", "label": "HTTPS", "variant": "emphasis" },
    { "from": "api", "to": "db", "label": "SQL" }
  ],
  "cards": []
}

渲染：node renderers/architecture/render-architecture.mjs <input>.json <output>.html。

渲染器会自动完成过去需要手动调整的机械性工作，因此你只需选择坐标和含义：

• 自由坐标 — pos: [x, y] 是组件的左上角；size: [w, h] 默认为 [120, 60]。与类型化模式不同，这里没有泳道／阶段网格——非对称布局由你决定。meta.viewBox 可选（会自动适配组件和图例行）。
• 通过 wraps 定义边界 — 列出 region（琥珀色虚线）或 security-group（玫瑰色虚线）所包围的组件 ID；渲染器会自动计算边框，并正确留出 30／50 像素的内边距。再也不用手动计算边界！
• 连接的路由方式与边类似（variant、fromSide／toSide、route: straight|orthogonal-h|orthogonal-v|auto、via、labelDx/labelDy/labelAt）。对于带标签的垂直连接，使用 labelDy 将标签移入间隙（验证器会提示标签是否落在框上）。
• 渲染器会自动生成双矩形 c-mask 图案，先绘制箭头再绘制框（z 轴顺序），根据所用组件类型生成图例，并且会在组件重叠、组件／边界超出画布、wraps／连接 ID 未知、标签与组件碰撞以及坐标非有限时立即报错——可靠性与其他四种模式一致。

手动放置回退方案（无法使用渲染器时）

当 Node／ajv 无法运行时，复制 assets/template.html 并手动放置 SVG。参考模板中的示例图和 examples/web-app.html，了解坐标惯例；遵循下方的设计系统，并在交付前执行自检清单。

首要规则：使用 CSS 类，而非内联颜色

主题切换通过更改 CSS 自定义属性实现。硬编码的 fill="rgba(...)" 或 stroke="#22d3ee" 在主题切换时不会更新。务必使用类系统：

<rect x="X" y="Y" width="W" height="H" rx="6" class="c-mask"/>
<rect x="X" y="Y" width="W" height="H" rx="6" class="c-backend" stroke-width="1.5"/>
<text x="CX" y="CY" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">API Server</text>
<text x="CX" y="CY+16" class="t-muted" font-size="9" text-anchor="middle">FastAPI :8000</text>

设计系统

组件填充色使用 c-frontend（客户端／UI）、c-backend（服务／API）、c-database（存储／缓存）、c-cloud（托管基础设施）、c-security（身份验证／密钥）、c-messagebus（Kafka／队列）、c-external（第三方）；文字强调色使用 t-<same>，另有中性色 t-primary／t-muted／t-dim。箭头使用 a-default、a-emphasis（关键路径）、a-security（虚线）、a-dashed（异步）——始终设置 stroke-width，并将 marker-end="url(#arrowhead[-variant])" 与对应的类配对。边界：c-security-group（玫瑰色虚线）、c-region（琥珀色虚线）、c-lane（泳道）。

字体从 SVG 根元素继承 JetBrains Mono。字号：组件名称 11–12px，副标签 9px，注释 8px，极小标签 7px。

硬性布局规则

• 始终使用双矩形图案：先放置不透明的 c-mask 矩形，再在上方放置样式为 c-<type> 的矩形——否则半透明填充会让箭头透出来。
• 箭头绘制在组件之前，即在文档顺序中位于组件之前（SVG 按顺序绘制；箭头必须位于框的后面）。
• 垂直堆叠：组件之间至少间隔 40px；内联连接器（消息总线，高 20px）应放在间隙内，不得与框重叠。
• 边界内边距：边界 y = 内部元素 y − 30；边界 height = 内部元素 height + 50；标签基线位于边界顶部下方 18px。
• 图例位置：放在所有边界框之外，且位于最低边界框下方至少 20px；必要时扩大 viewBox。

自检清单（交付前执行）

1. 在 SVG 内运行 grep -E 'fill="(#|rgb)|stroke="(#|rgb)' out.html，除模板自身的 defs 外，不应有任何输出（首要规则）。
2. 每个 c-<type> 矩形前都紧邻一个几何尺寸完全相同的 c-mask 矩形。
3. 文档顺序中，所有 <line>／<path> 箭头都必须位于所有组件矩形之前。

导出选项

Archify 支持多种静态和动画图表导出格式：

静态导出

• PNG — 高分辨率光栅图像（源分辨率的 4 倍）
• JPEG — 带背景的压缩光栅图像
• WebP — 支持透明度的现代压缩格式
• SVG — 支持自动主题的矢量格式
• Copy to Clipboard — 快速复制 PNG 以便粘贴

动画导出（适用于包含流动动画的图表）

• GIF — 捕捉流动动画的动态 GIF

  • 使用 gif.js 库在客户端进行编码
  • 导出前会显示用户可配置的设置对话框：
    • 分辨率：1x / 2x（默认）/ 3x / 4x
    • 帧率：10 / 15 / 20（默认）/ 24 / 30 / 60 fps
    • 时长：2 / 3（默认）/ 5 / 8 秒
  • 显示实时帧数预览（例如“60 帧 · 20 fps · 3s”）
  • 文件大小：通常为 1-10 MB，具体取决于设置和复杂度

• WebM — 高质量视频格式

  • 使用 MediaRecorder API 原生录制视频
  • 与 GIF 使用相同的用户可配置设置对话框
  • 画质优于 GIF，文件更小
  • 支持 Chrome、Firefox、Edge

导出提示

获得最佳 GIF 画质：

1. 使用深色主题（动画对比度更高）
2. 控制图表尺寸（图表越大，GIF 文件越大）
3. 等待“GIF exported successfully!”提示消息

WebM 视频：

1. 在 Chrome 和 Firefox 中效果最佳
2. Safari 对 MediaRecorder 的支持有限
3. 使用 VLC 或浏览器播放 WebM 文件

优化文件大小：

• GIF：常见图表为 1-5 MB
• WebM：相同内容为 0.5-2 MB
• 分享时：建议使用 WebM（画质与文件大小的比例更好）

流动动画效果

现在，所有图表的连接路径都包含自动流动动画效果。此功能已内置于渲染器和模板中，无需额外配置。

动画行为

CSS 动画（stroke-dasharray 流动）：

• a-emphasis：快速流动（周期为 0.8s），带脉冲效果和 3px 光晕
• a-default：中速流动（周期为 1.2s），带 2px 光晕
• a-dashed：平稳流动（周期为 1s）
• a-security：平稳流动（周期为 1s）

SVG 动画（移动圆点）：

• 每条连接路径都有一个沿路径流动的动画圆点
• 圆点属性因变体而异：
  • emphasis：半径 3px，不透明度较高（0.9），持续时间为 2-3.5s
  • default：半径 2.5px，不透明度中等（0.8），持续时间为 2.5-3.7s
  • dashed：半径 2px，不透明度较低（0.7），持续时间为 2.2-3.4s
  • security：半径 2px，不透明度较低（0.7），持续时间为 2.5-3.5s

流动方向规则

关键限制：流动动画必须从源端（无箭头）流向目标端（有箭头）。

渲染器会自动处理：

• 所有路径都使用 marker-end 设置箭头
• 动画方向沿路径从起点指向终点
• 圆点从没有箭头的组件流向有箭头的组件

视觉效果

1. 描边虚线动画：营造虚线沿路径流动的效果
2. 移动圆点：动画圆点沿路径轨迹移动
3. 光晕效果：强调路径使用增强型 drop-shadow 滤镜
4. 脉冲效果：强调路径具有轻微的不透明度脉冲

自定义

流动效果会根据连接/边/流/转换的 variant 属性自动应用：

{
  "from": "source",
  "to": "target",
  "variant": "emphasis",  // Fast flow with glow
  "label": "data flow"
}

可用变体：

• emphasis — 主要数据流，动画最快，光晕最强
• default — 标准连接，中速动画
• dashed — 异步/批处理操作，平稳流动
• security — 安全/策略路径，平稳流动

技术实现

流动效果分为两层实现：

1. CSS 层（assets/template.html）：

   • @keyframes flowDash — 为流动虚线设置 stroke-dashoffset 动画
   • @keyframes flowPulse — 为强调脉冲设置透明度动画
   • 通过 .a-emphasis、.a-default、.a-dashed、.a-security 类应用

2. SVG 层（渲染器）：

   • 在 <circle> 圆点上使用 <animateMotion> 元素
   • 路径数据来自连接线路由
   • 持续时间因变体和索引而异，以呈现视觉变化

向后兼容性

• 不带动画的现有图表仍可正常使用
• 动画仅为附加功能，不会造成破坏性变更
• 所有主题切换和导出功能仍完全可用

4. 计算所有 SVG 元素的 max(y + height)：viewBox 高度必须比该值至少大 20px；x/width 也采用同样规则。
5. 图例的 y 坐标低于所有边界的 y + height。
6. .toolbar、<script> 块以及 :root / [data-theme] CSS 均保持不变——它们就是主题切换和导出菜单。

输出

一个独立的 .html 文件：内嵌 CSS（Google Fonts 异步加载，离线时降级为系统等宽字体）、内联 SVG、内嵌的 gif.js 库和用于导出动画 GIF 的 worker，以及约 60KB 的内嵌 JS，用于主题、导出和动画。它可直接在任何现代浏览器中渲染。栅格导出最高按 viewBox 的 4 倍分辨率原生渲染（大型图表会降至 3 倍或 2 倍，以避免超出画布限制）；SVG 下载文件为同时支持双主题的独立文件，并遵循宿主的 prefers-color-scheme（可通过 svg[data-theme="..."] 手动覆盖）。动画 GIF/WebM 导出会捕获流动动画，并支持用户配置分辨率、帧率和时长。