@wagemule/daemon 0.1.2 → 0.1.3

package/dist/skills/larksuite/lark-whiteboard/scenes/comparison.md

@@ -0,0 +1,135 @@
+# 对比图 / 矩阵图
+
+适用于：方案对比、功能矩阵、技术选型等多选项按多维度比较的场景。
+
+## Content 约束
+
+- **每格内容要充实**：不要只写一个关键词，给出具体说明（如"MVCC 多版本并发控制，支持行级锁"而非仅"支持"）
+- 单格内容不同格子允许不同长度，但每格不超过 5 行
+- 长文本（超过 15 字）用 `textAlign: "left"`（不要居中）
+- 第一行是标题行（对象名称），第一列是维度标签列
+- 维度数量至少 4 个，充分展开对比维度
+
+## Layout 选型
+
+| 模式 | 适用条件 | 特征 |
+|------|---------|------|
+| **严格 grid（默认）** | 所有对比场景 | 表头行 + 数据行，每行 horizontal frame，行内 rect 等分 |
+| **卡片式对比（替代）** | 维度较少（2-3 个） | 每个对象做一张独立卡片，卡片内纵向列出各维度。卡片横向等分：外层 `layout: "horizontal"`，每张卡片 `width: "fill-container"` |
+
+## Layout 规则
+
+- 最外层 frame：`layout: "vertical"`，固定 `width`（如 1000），`height: "fit-content"`
+- 每行：horizontal frame，`width: "fill-container"`，`alignItems: "stretch"`
+- 行内单元格全部 `width: "fill-container"` 等分列宽
+- 行间 `gap >= 12`（不要 8，太紧）
+- 行内列间 `gap: 8-12`
+- 标题行：深色底白字（由 style 控制具体颜色）
+- 每列同色边框保持视觉一致性
+- 单元格 `height: "fit-content"`，不要写固定 height
+
+## 骨架示例
+
+### 3 列 4 行表格
+
+```json
+{
+  "version": 2,
+  "nodes": [
+    {
+      "type": "frame",
+      "width": 1000,
+      "height": "fit-content",
+      "layout": "vertical",
+      "gap": 12,
+      "padding": 0,
+      "children": [
+        {
+          "type": "text",
+          "id": "title",
+          "width": "fill-container",
+          "height": "fit-content",
+          "text": "[对比图标题]",
+          "fontSize": 24,
+          "textAlign": "center",
+          "verticalAlign": "middle"
+        },
+        {
+          "type": "frame",
+          "id": "header-row",
+          "width": "fill-container",
+          "height": "fit-content",
+          "layout": "horizontal",
+          "gap": 8,
+          "padding": 0,
+          "alignItems": "stretch",
+          "children": [
+            { "type": "rect", "id": "h-dim", "width": "fill-container", "height": "fit-content", "text": "[维度]", "fontSize": 15, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 0, "borderWidth": 2 },
+            { "type": "rect", "id": "h-col-1", "width": "fill-container", "height": "fit-content", "text": "[对象A]", "fontSize": 15, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "h-col-2", "width": "fill-container", "height": "fit-content", "text": "[对象B]", "fontSize": 15, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "h-col-3", "width": "fill-container", "height": "fit-content", "text": "[对象C]", "fontSize": 15, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 }
+          ]
+        },
+        {
+          "type": "frame",
+          "id": "data-row-1",
+          "width": "fill-container",
+          "height": "fit-content",
+          "layout": "horizontal",
+          "gap": 8,
+          "padding": 0,
+          "alignItems": "stretch",
+          "children": [
+            { "type": "rect", "id": "d1-dim", "width": "fill-container", "height": "fit-content", "text": "[维度1]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "d1-c1", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "d1-c2", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "d1-c3", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 }
+          ]
+        },
+        {
+          "type": "frame",
+          "id": "data-row-2",
+          "width": "fill-container",
+          "height": "fit-content",
+          "layout": "horizontal",
+          "gap": 8,
+          "padding": 0,
+          "alignItems": "stretch",
+          "children": [
+            { "type": "rect", "id": "d2-dim", "width": "fill-container", "height": "fit-content", "text": "[维度2]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "d2-c1", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "d2-c2", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "d2-c3", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 }
+          ]
+        },
+        {
+          "type": "frame",
+          "id": "data-row-3",
+          "width": "fill-container",
+          "height": "fit-content",
+          "layout": "horizontal",
+          "gap": 8,
+          "padding": 0,
+          "alignItems": "stretch",
+          "children": [
+            { "type": "rect", "id": "d3-dim", "width": "fill-container", "height": "fit-content", "text": "[维度3]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "d3-c1", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "d3-c2", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
+            { "type": "rect", "id": "d3-c3", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 陷阱
+
+- **行间距 8px 太紧**：行间 gap 至少 12，8 会让行与行视觉粘连。
+- **长文本居中对齐**：超过一行的文本应改为 `textAlign: "left"`，居中多行文本可读性差。
+- **列数太多导致每列太窄**：对比对象建议 ≤ 5 列（含维度列），超过时合并维度或拆分为多张表。
+- **列宽不等**：所有数据列必须用 `width: "fill-container"` 等分，不要给某列写固定宽度。
+- **行高不等**：每行 frame 必须 `alignItems: "stretch"`，否则同行单元格因文字行数不同高矮不齐。
+- **忘记维度标签列**：第一列放维度名称，标题行（维度列）用与数据列不同的视觉处理。
+- **单元格用固定 height**：单元格必须 `height: "fit-content"`，固定高度会导致文字截断。

package/dist/skills/larksuite/lark-whiteboard/scenes/fishbone.md

@@ -0,0 +1,238 @@
+# 鱼骨图（因果图）
+
+> **必须写脚本生成 JSON。** 鱼骨图的分支角度、原因小骨坐标需要三角函数计算，直接手写 JSON 极易导致节点重叠和连线穿模。请用下方脚本模板。
+
+## Content 约束
+
+- 分类 4-6 个
+- 每个分类的原因 ≤ 4
+- 总原因 ≤ 20（超过必须合并分类）
+
+## Layout 选型
+
+- **脚本生成坐标**（必须）：用 .cjs 脚本通过三角函数计算鱼骨坐标，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.11` 渲染
+
+## Layout 规则
+
+- 主干水平居中，从左向右延伸
+- 分类节点按 spineX 从左到右排列，奇数（第 1、3、5...）在上方，偶数（第 2、4...）在下方
+- 每个分类的原因沿斜线（分支骨）等距排列
+- 鱼头（中心问题）在右侧，用 ellipse
+- 主干连线带箭头指向鱼头，分支骨和原因小骨连线 endArrow: "none"
+- 原因小骨水平延伸到原因框右侧，Y 坐标精准对齐
+
+## 骨架示例
+
+**上下交替**：分类标签按 spineX 从左到右排列，奇数（第1、3、5...）在上方，偶数（第2、4...）在下方。
+
+**视觉同色系**：同一个分支的分类标签、连线及其下的所有原因节点，必须使用同一个色系（如相同的背景色与边框色组合），以保持图形风格统一和逻辑连贯。可以预定义一组颜色数组，按分支轮询使用。
+
+### 坐标计算脚本模板（必须严格参照此算法生成）
+
+以下 Node.js 脚本模板包含了完整的动态布局算法，能够自动适配任意数量的分类和原因，生成完美不重叠的鱼骨图：
+
+```javascript
+const fs = require('fs');
+
+const nodes = [];
+
+// 1. 数据定义 (根据用户需求填充)
+const categories = [
+  { id: "c0", text: "前端代码", reasons: ["未压缩资源", "冗余请求", "超大图片未懒加载"] },
+  { id: "c1", text: "后端服务", reasons: ["数据库慢查询", "缓存失效", "并发量过大"] },
+  { id: "c2", text: "网络环境", reasons: ["CDN配置错误", "DNS解析缓慢", "带宽限制", "网络抖动"] }
+];
+
+// 2. 动态布局计算
+const catWidth = 120;
+const catHeight = 40;
+const reasonWidth = 140; // 调整原因框宽度以适应长文本
+const reasonHeight = 32;
+const lineLength = 20; // 原因小骨连线的水平延伸长度
+const paddingX = 40; // 同侧节点间的水平安全间距
+
+// 预置的分支色系数组（分支骨分类和具体原因保持同一色系）
+const branchColors = [
+  { fill: "#E8F3FF", stroke: "#1664FF" }, // 蓝色系
+  { fill: "#E6FFED", stroke: "#00B42A" }, // 绿色系
+  { fill: "#FFF7E8", stroke: "#FF7D00" }, // 橙色系
+  { fill: "#FFECE8", stroke: "#F5319D" }, // 粉色系
+  { fill: "#F2E8FF", stroke: "#722ED1" }, // 紫色系
+  { fill: "#E8FFFF", stroke: "#14C9C9" }  // 青色系
+];
+
+let maxSpineY_up = 0;
+let maxSpineY_down = 0;
+
+// 第一步：计算每个 category 的内部尺寸和相对包围盒
+categories.forEach((cat, index) => {
+  const isTop = index % 2 === 0;
+  const numReasons = cat.reasons.length;
+
+  // 动态计算分支高度，确保原因小骨不会垂直重叠
+  // 每个原因需要 reasonHeight + 上下间距(约 16)
+  const requiredY = (numReasons + 1) * (reasonHeight + 16);
+  const branchDY = Math.max(160, requiredY);
+  const branchDX = -branchDY * 0.7; // 保持固定的倾斜角度向左延伸
+
+  cat.isTop = isTop;
+  cat.branchDX = branchDX;
+  cat.branchDY = branchDY;
+
+  // 记录最大分支高度，用于计算背景高度和主骨 Y 坐标
+  if (isTop) maxSpineY_up = Math.max(maxSpineY_up, branchDY + catHeight + 40);
+  else maxSpineY_down = Math.max(maxSpineY_down, branchDY + catHeight + 40);
+
+  // 计算该分类的相对包围盒的极值（相对于 spineX 锚点）
+  // 最左侧可能由分类框或原因框决定
+  cat.minX = Math.min(branchDX - catWidth / 2, branchDX - lineLength - reasonWidth);
+  // 最右侧为主骨挂载点 0 或 分类框右侧
+  cat.maxX = Math.max(0, branchDX + catWidth / 2);
+});
+
+// 第二步：计算每个 category 在主骨上的绝对 X 坐标 (spineX)
+let currentSpineX = 100; // 初始偏移
+for (let i = 0; i < categories.length; i++) {
+  const cat = categories[i];
+  let startX = currentSpineX;
+
+  // 需要和上一个同侧的 category 保持距离，防止水平重叠
+  if (i >= 2) {
+    const prevSameSideCat = categories[i - 2];
+    const requiredX = prevSameSideCat.spineX + prevSameSideCat.maxX - cat.minX + paddingX;
+    startX = Math.max(startX, requiredX);
+  }
+
+  // 确保左侧最长分支不会超出画布左边界
+  if (startX + cat.minX < 50) {
+    startX = 50 - cat.minX;
+  }
+
+  cat.spineX = startX;
+  // 每次略微向前推进，确保异侧节点也能稍微错开
+  currentSpineX = startX + 80;
+}
+
+// 第三步：计算全局画布尺寸
+const lastCat = categories[categories.length - 1];
+const spineY = maxSpineY_up + 50; // 动态推导主骨 Y 坐标
+const totalWidth = lastCat.spineX + 350; // 右侧留出鱼头的空间
+const totalHeight = spineY + maxSpineY_down + 50;
+
+// 4. 生成节点数据
+// 背景
+nodes.push({ type: "rect", x: 0, y: 0, width: totalWidth, height: totalHeight, fillColor: "#FFFFFF", borderWidth: 0 });
+
+// 鱼头
+const headWidth = 180;
+const headHeight = 80;
+const headX = totalWidth - headWidth - 40;
+const headY = spineY - headHeight / 2;
+nodes.push({ type: "ellipse", id: "head", x: headX, y: headY, width: headWidth, height: headHeight, text: "核心问题" });
+
+// 主骨连线
+const firstSpineX = categories[0].spineX + categories[0].minX;
+nodes.push({
+  type: "connector",
+  connector: { from: { x: firstSpineX, y: spineY }, to: "head", toAnchor: "left", lineShape: "straight", endArrow: "arrow" }
+});
+
+// 遍历生成分类和原因小骨
+categories.forEach((cat, index) => {
+  const isTop = cat.isTop;
+  const branchDY = cat.branchDY;
+  const branchDX = cat.branchDX;
+  const color = branchColors[index % branchColors.length];
+
+  // 分类标签
+  const catX = cat.spineX + branchDX - catWidth / 2;
+  const catY = spineY + (isTop ? -branchDY - catHeight : branchDY);
+
+  nodes.push({
+    type: "rect", id: cat.id, x: catX, y: catY, width: catWidth, height: catHeight, text: cat.text,
+    fillColor: color.fill, strokeColor: color.stroke
+  });
+  // 分支骨连线
+  nodes.push({
+    type: "connector",
+    connector: { from: { x: cat.spineX, y: spineY }, to: cat.id, toAnchor: isTop ? "bottom" : "top", lineShape: "straight", endArrow: "none", lineColor: color.stroke }
+  });
+
+  // 原因小骨
+  cat.reasons.forEach((reason, rIndex) => {
+    // 线性插值，均匀分布在分支骨上
+    const t = (rIndex + 1) / (cat.reasons.length + 1);
+    const attachX = cat.spineX + branchDX * t;
+    const attachY = spineY + (isTop ? -branchDY : branchDY) * t;
+
+    // 关键对齐：确保原因盒子完全在连线左侧，并且 Y 坐标中心精准对齐
+    const boxX = attachX - lineLength - reasonWidth;
+    const boxY = attachY - reasonHeight / 2;
+
+    const rId = `${cat.id}-r${rIndex}`;
+    nodes.push({
+      type: "rect", id: rId, x: boxX, y: boxY, width: reasonWidth, height: reasonHeight, text: reason,
+      fillColor: color.fill, strokeColor: color.stroke
+    });
+    // 原因小骨连线
+    nodes.push({
+      type: "connector",
+      connector: { from: { x: attachX, y: attachY }, to: rId, toAnchor: "right", lineShape: "straight", endArrow: "none", lineColor: color.stroke }
+    });
+  });
+});
+
+fs.writeFileSync('diagram.json', JSON.stringify({ version: 2, nodes }, null, 2));
+```
+
+## 连线格式与注意点
+
+所有 connector 都用 `{ "type": "connector", "connector": { ... } }` 格式。
+**注意：除了主骨外，其他所有连线（分支骨、原因小骨）都必须设置 `"endArrow": "none"`，否则会默认带箭头，导致方向混乱。**
+
+分支骨：从主骨上的绝对坐标点 → 分类标签节点：
+
+```json
+{
+  "version": 2,
+  "nodes": [
+    { "type": "rect", "x": 0, "y": 0, "width": "__totalWidth__", "height": "__totalHeight__" },
+
+    { "type": "ellipse", "id": "head", "x": "__headX__", "y": "__headY__",
+      "width": 180, "height": 80, "text": "[中心问题]" },
+
+    { "type": "connector", "connector": {
+      "from": { "x": "__spineStartX__", "y": "__spineY__" },
+      "to": "head", "toAnchor": "left",
+      "lineShape": "straight", "endArrow": "arrow"
+    }},
+
+    { "type": "rect", "id": "c0", "x": "__catX__", "y": "__catY__",
+      "width": 120, "height": 40, "text": "[分类A]" },
+    { "type": "connector", "connector": {
+      "from": { "x": "__spineX0__", "y": "__spineY__" },
+      "to": "c0", "toAnchor": "bottom",
+      "lineShape": "straight", "endArrow": "none"
+    }},
+
+    { "type": "rect", "id": "c0-r0", "x": "__reasonX__", "y": "__reasonY__",
+      "width": 140, "height": 32, "text": "[原因1]" },
+    { "type": "connector", "connector": {
+      "from": { "x": "__attachX__", "y": "__attachY__" },
+      "to": "c0-r0", "toAnchor": "right",
+      "lineShape": "straight", "endArrow": "none"
+    }}
+  ]
+}
+```
+
+上述骨架展示一个分类（上方）+ 一条原因的模式。完整鱼骨图重复此模式，上下交替。每个分类下可有多条原因，均匀插值分布在分支骨上。
+
+## 陷阱
+
+- **代码生成**：必须使用带有动态防重叠算法的脚本来计算坐标并输出 JSON。
+- **分支骨防重叠**：同一侧的相邻分支骨和原因框必须没有任何交叉。
+- **自适应高度**：原因数量较多时，分支骨自动拉长以容纳所有小骨。
+- **原因小骨水平**：原因框右侧的附着点必须与连线起点 Y 坐标一致。
+- **无箭头**：所有分类的分支连线、小骨连线均必须关闭箭头。
+- **同色系**：同一个分支骨、分类标签节点以及原因小骨节点和连线，必须使用同色系的颜色以保持视觉连贯性。

package/dist/skills/larksuite/lark-whiteboard/scenes/flowchart.md

@@ -0,0 +1,185 @@
+# 流程图 (Flowchart)
+
+适用于：各种业务流转图、决策树、审批流、时序控制逻辑、带条件判断的链路、系统架构拓扑等。
+
+通用字段语义详见 `references/schema.md`，通用布局原则详见 `references/layout.md`；本文件只描述流程图场景下的选型边界与范式。
+
+> [!IMPORTANT]
+> **流程图必须走 DSL 路径，不再使用 Mermaid！**
+> 复杂分支、判断、回路、跳级关系优先使用 `layout: "dagre"` 计算拓扑；如果只是规整的单线流水线，且卡片强对齐比自动拓扑更重要，也可以使用 Flex + 顶层 `connector` 组合实现。
+
+## 美学规范
+
+- **摒弃简陋节点，推崇全卡片化**：核心业务节点不要只用一个纯文本 `rect`。**应优先采用 Flex 组合卡片**（如：在 `vertical` frame 内上下组合【Emoji 标题项】和【补充说明项】），使得节点信息结构化、层级分明。
+- **语义化色彩编排**：节点底色严禁随机分配。必须按状态语义映射：常规链路用浅蓝/浅紫、核心风控/检查用预警黄、成功通过用生命绿、失败熔断用危险红。边框颜色可同色系加深，以凸显卡片边缘。
+- **统一判定逻辑**：条件分支必须使用 `diamond` 菱形节点，并且**严禁漏掉** `layoutOptions.edges` 边定义里的第三个标签参数（必须清晰写明"是/否"、"通过/拒绝"）。
+- **形状多样化**：合理搭配不同形状来表达语义 —— `ellipse` 用于外部实体/起终点、`diamond` 用于判断路由、`rect` 用于业务处理节点、`cylinder` 用于持久化存储。
+
+## Layout 选型
+
+| 模式             | 适用条件                                       | 核心配置                                                                                                 |
+| ---------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| **主体用 Dagre** | 有判断、分支、回路、回退、跳级关系的标准流程图 | 主体 frame 设定 `layout: "dagre"`，按需配置 `rankdir: "TB"` 或 `rankdir: "LR"`。                          |
+| **局部复合节点** | 流程中的某一步本身是一个小型 UI 组合体         | 外层仍用 `dagre`，复合步骤内部改用 `layout: "vertical"` / `"horizontal"`。此类节点为**不透明节点**，外层连线只能连到外壳。 |
+| **透明子图**     | 需按业务区域分组，且连线穿越区域边界           | 子容器声明 `layout: "dagre"` + `layoutOptions: { isCluster: true }`，成为透明子图。内部节点直接参与外层拓扑运算。 |
+| **规整流水线**   | 基本是单线 A → B → C → D，且卡片对齐要求极高   | 主体可用 Flex 排版，连线改用顶层 `connector`；不要为了"自动"而硬上 Dagre。                                  |
+
+## 核心属性
+
+- **`rankdir`**: `TB`（上下）或 `LR`（左右）。**强烈推荐优先使用 `LR`**，充分利用宽屏横向空间。
+- **`edges`**: 在根 Dagre 的 `layoutOptions.edges` 中按 `[fromId, toId, "标签"]` 声明。**支持反向连接**实现闭环。所有 edges 统一写在**最外层根 Dagre**，不要写在 cluster 内部。
+- **`ranksep` 与边文本**: 若边上标注了说明文字，**必须根据字数调大间距**：`ranksep = max(60, 字数 × 16)`。
+- **自适应尺寸**: dagre 容器**必须**设定 `width: "fit-content"` 和 `height: "fit-content"`。
+- **`clusterTitle`**: 透明子图可通过 `clusterTitle` 声明悬浮标题（自动吸附左上角、加粗 14px），搭配 `clusterTitleColor` 指定标题颜色。
+
+## 两种嵌套模式
+
+### 不透明节点（Opaque Node）
+Dagre 内的子容器，只要未声明 `isCluster: true`，对外层 Dagre 就是具有确定宽高的原子节点。外层连线无法寻址其内部子节点。适合封装复杂的组合卡片（如带图标、版本号、多行描述的业务模块）。
+
+### 透明子图（Compound Cluster）
+子容器同时声明 `layout: "dagre"` 与 `layoutOptions: { isCluster: true }` 时，成为外层 Dagre 的复合子图。其内部子节点直接参与外层拓扑运算，连线可穿越子图边界。适合划分网络区域、功能层级、命名空间等边界容器。推荐搭配 `borderDash: "dashed"` 虚线边框 + 淡色背景。
+
+## 骨架示例（推荐范本）
+
+以下是一个混合架构拓扑的完整示例。它同时展示了**透明子图**（Kubernetes Zone，连线可穿透）和**不透明复合节点**（DB 集群、AI 引擎，连线只能连外壳）的标准写法，以及多种形状（ellipse / diamond / rect / cylinder）和语义化配色规范。
+
+```json
+{
+  "version": 2,
+  "nodes": [
+    {
+      "type": "frame",
+      "id": "root",
+      "x": 20, "y": 20,
+      "layout": "dagre",
+      "width": "fit-content", "height": "fit-content",
+      "padding": 60,
+      "fillColor": "#F8FAFC",
+      "borderColor": "#CBD5E1",
+      "borderWidth": 1,
+      "borderRadius": 16,
+      "layoutOptions": {
+        "rankdir": "LR",
+        "nodesep": 60,
+        "ranksep": 120,
+        "edges": [
+          ["user", "k8s_ingress", "HTTPS request"],
+          ["k8s_ingress", "web_pod", "Route UI"],
+          ["k8s_ingress", "api_pod", "Route API"],
+          ["web_pod", "api_pod", "Internal REST"],
+          ["api_pod", "db_cluster", "SQL Query"],
+          ["api_pod", "ai_service", "gRPC Stream"]
+        ]
+      },
+      "children": [
+        {
+          "type": "ellipse", "id": "user", "text": "Global Users",
+          "width": 110, "height": 60,
+          "fillColor": "#E2E8F0", "borderColor": "#64748B", "borderWidth": 1,
+          "fontSize": 14, "textColor": "#334155"
+        },
+        {
+          "type": "frame", "id": "zone_k8s",
+          "layout": "dagre",
+          "layoutOptions": {
+            "isCluster": true,
+            "clusterTitle": "☸️ Kubernetes Zone (isCluster)",
+            "clusterTitleColor": "#2563EB"
+          },
+          "fillColor": "#EFF6FF", "borderColor": "#60A5FA",
+          "borderWidth": 2, "borderDash": "dashed", "borderRadius": 24,
+          "children": [
+            {
+              "type": "diamond", "id": "k8s_ingress", "text": "Nginx Ingress",
+              "width": 130, "height": 70,
+              "fillColor": "#DBEAFE", "borderColor": "#3B82F6", "borderWidth": 2,
+              "textColor": "#1E40AF"
+            },
+            {
+              "type": "rect", "id": "web_pod", "text": "Next.js SSR Pod",
+              "width": 140, "height": 48,
+              "fillColor": "#BFDBFE", "borderColor": "#2563EB", "borderWidth": 2,
+              "borderRadius": 8, "textColor": "#1E3A8A"
+            },
+            {
+              "type": "rect", "id": "api_pod", "text": "Go Lang API Pod",
+              "width": 140, "height": 48,
+              "fillColor": "#BFDBFE", "borderColor": "#2563EB", "borderWidth": 2,
+              "borderRadius": 8, "textColor": "#1E3A8A"
+            }
+          ]
+        },
+        {
+          "type": "frame", "id": "db_cluster",
+          "layout": "vertical", "gap": 16, "padding": [20, 24],
+          "alignItems": "center",
+          "fillColor": "#F0FDF4", "borderColor": "#22C55E",
+          "borderWidth": 2, "borderRadius": 16,
+          "children": [
+            {
+              "type": "text", "id": "db_title",
+              "text": "🗄️ Highly Available DB (不透明)", "fontSize": 14, "textColor": "#14532D"
+            },
+            {
+              "type": "frame", "id": "db_row", "layout": "horizontal", "gap": 20,
+              "children": [
+                {
+                  "type": "cylinder", "id": "db_master", "text": "Master",
+                  "width": 80, "height": 50,
+                  "fillColor": "#DCFCE7", "borderColor": "#16A34A", "borderWidth": 1,
+                  "textColor": "#166534"
+                },
+                {
+                  "type": "cylinder", "id": "db_replica", "text": "Replica",
+                  "width": 80, "height": 50,
+                  "fillColor": "#DCFCE7", "borderColor": "#16A34A", "borderWidth": 1,
+                  "textColor": "#166534"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "frame", "id": "ai_service",
+          "layout": "vertical", "gap": 10, "padding": [16, 20],
+          "alignItems": "center",
+          "fillColor": "#FAF5FF", "borderColor": "#A855F7",
+          "borderWidth": 2, "borderRadius": 12,
+          "children": [
+            {
+              "type": "text", "id": "ai_title",
+              "text": "🧠 Multi-Modal Engine (不透明)", "fontSize": 14, "textColor": "#6B21A8"
+            },
+            {
+              "type": "rect", "id": "ai_version",
+              "text": "v4.2.1-beta", "width": 90, "height": 22,
+              "fillColor": "#E9D5FF", "borderColor": "#C084FC", "borderWidth": 1,
+              "borderRadius": 4, "fontSize": 11, "textColor": "#581C87"
+            },
+            {
+              "type": "text", "id": "ai_desc",
+              "text": "Includes Vector Store\n& Transformer Blocks",
+              "fontSize": 12, "textColor": "#7E22CE", "textAlign": "center"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**范本要点**：
+- `zone_k8s` 是**透明子图**（`isCluster: true` + `clusterTitle`），外部连线穿越虚线边界直达 `k8s_ingress`、`web_pod`、`api_pod`。
+- `db_cluster` 和 `ai_service` 是**不透明节点**（`layout: "vertical"`），内部用 Flex 组合了多行结构化信息，对外层 Dagre 是固定宽高的原子。连线只能连到外壳 ID。
+- 所有 `edges` 统一写在最外层根 Dagre 的 `layoutOptions` 中。
+- 本范本中用到了 `ellipse`（外部实体）、`diamond`（路由判断）、`rect`（业务节点）、`cylinder`（数据库存储）四种形状。
+
+## 陷阱与常见报错防范
+
+- **误用 Mermaid**：只要用户没有带 `mermaid` 具体语法代码，哪怕描述明确是"流程图"，也**强制使用 DSL 框架下的 Dagre 模式**。
+- **重复画线**：`dagre` 里的所有子节点关系通过 `edges` 定义，引擎会自动生成连线。**绝对不要再去外层用 `connector` 节点重复连一次**。
+- **穿透黑盒**：普通子容器是不透明节点，外部连线无法直接寻址其内部子节点（引擎会自动重定向至外壳）。若需穿透，必须声明 `layout: "dagre"` 与 `layoutOptions: { isCluster: true }`。
+- **`id` 缺失**：只要是在 `edges` 里出现的标识符，`children` 里一定能找到同名 `id` 的节点对应，拼写必须完全一致。
+- **宽度灾难**：Dagre 内容器禁止子框使用 `fill-container`，因为 dagre 父容器本身是被内容撑开的。