⚠️ 重要：所有输出内容必须使用中文 — 图表标题、节点标签、子标签、边线标签、卡片内容、图例文字等一律使用中文。技术术语（如 API、JSON、CSS）和代码标识符除外。

Archify 技能

创建专业的专业技术图表，生成独立 HTML 文件，内含内联 SVG、主题切换和内置图片/SVG 导出菜单。

每个图表都包含：暗色/亮色主题切换（保存到 localStorage，响应 prefers-color-scheme）、导出菜单（复制 PNG 到剪贴板；以最高 4 倍分辨率导出 PNG/JPEG/WebP 位图；下载双主题 SVG，自动跟随宿主环境的 prefers-color-scheme——适合 GitHub README）、以及CSS 变量色彩系统确保双主题一致。

安装（一次性，仅渲染器模式需要）

四种类型化渲染器通过 ajv 校验 JSON 与 schema 的一致性。在技能目录下执行：

npm install

不安装也能运行——渲染器会打印警告并跳过 schema 校验，但仍会执行自身的布局检查。生成的 HTML 没有任何外部依赖，仅渲染器需要依赖。

如果完全没有 shell 环境（例如技能作为项目知识添加），则对所有请求回退到 architecture 模式：按照下文的设计系统手动将 SVG 放入 assets/template.html，并在交付前运行自审清单。

选择图表类型

触发词：提到"架构/系统/云图" → architecture（除非明显是流程导向）。"工作流/流程/审批/运行手册/CI-CD/事件" → workflow。"时序/交互/调用链/谁调用谁" → sequence。"数据流/管道/ETL/血缘/PII/治理" → dataflow。"状态/生命周期/状态机/重试/终态" → lifecycle。

将 Mermaid 作为输入语言

当用户粘贴 Mermaid 代码时，不要机械地渲染或解析——从中读取结构信息，然后以对应的 archify 模式从头重新布局：

丢弃 Mermaid 的样式，只保留拓扑结构和含义。由你来决定分组、泳道顺序以及哪些地方需要重点突出——你的判断力本身就是产品价值所在。

渲染器模式（workflow / sequence / dataflow / lifecycle）

四种模式遵循相同的流程：

1. 先阅读：schema 文件（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 后重新运行；永远不要修改渲染器本身。

Schema 校验失败时以非零状态退出，并给出带路径前缀的错误信息，如 /nodes/3 (id/label: "router") must NOT have additional properties。渲染器还会在布局问题上快速失败：节点/状态重叠（包括跨泳道）、标签与节点或其他标签碰撞、标签宽于所属节点、列/行超出范围、边过短、图例超出 viewBox。中文文本自动按双倍宽度计算。

工作流（Workflow）

{
  "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 路径点。相邻步骤间的边线无标签；标签留给跨泳道转换、审批、异步写入和返回操作。

时序图（Sequence）

{
  "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"。

数据流图（Dataflow）

{
  "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 = 异步/批量。

生命周期（Lifecycle）

{
  "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 是必需的，映射到顶部阶段带（cols 0–4）；terminal 映射到底部结果带（cols 0–2）；其他所有泳道 id 共享中间的事件带（cols 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。

架构图模式（Architecture）

架构图模式与其它模式遵循相同的读 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-<同上> 加中性色 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> 箭头在文档顺序上均出现在所有组件矩形之前。
4. 计算所有 SVG 元素的最大 (y + height)：viewBox 高度必须超出其 ≥20px；x/width 同理。
5. 图例的 y 位置低于所有边界的 y + height。
6. .toolbar、<script> 块、以及 :root / [data-theme] CSS 未被修改——它们就是主题切换和导出菜单本身。

输出

生成单个自包含 .html 文件：内嵌 CSS（Google Fonts 异步加载，离线时回退到系统等宽字体）、内联 SVG、约 19KB 内嵌 JS 实现主题 + 导出。可在任意现代浏览器中直接渲染。位图导出以最高 4 倍 viewBox 原生渲染（大型图降至 3×/2× 以不超过画布限制）；SVG 下载为自包含的双主题文件，跟随宿主环境的 prefers-color-scheme（可通过 svg[data-theme="..."] 手动覆盖）。