@wagemule/daemon 0.1.2 → 0.1.4

package/dist/skills/larksuite/lark-whiteboard/references/schema.md

@@ -0,0 +1,357 @@
+# DSL Schema
+
+> 本文件只说明 **DSL 里能写什么**：节点类型、字段、枚举值、硬约束。布局策略、组合方法、Dagre/Flex 心智模型统一放在 `references/layout.md`。  
+> `?` 表示该字段在 schema 层是 optional；若需要稳定产出，再参考对应 scene 或 layout 文件中的最佳实践。
+
+**📝 布局引擎核心法则**：
+- **基本行为与 Flexbox 等同**：Frame 布局基于 Yoga 引擎。`layout: 'horizontal'` = `flex-direction: row`，`fill-container` = `flex: 1`，`fit-content` = `width: auto`，`gap` / `padding` / `alignItems` / `justifyContent` 语义相同。
+- **枚举值无 flex- 前缀**：一律使用 `'start'` / `'end'` 而非原生 CSS 的 `'flex-start'` / `'flex-end'`。
+- **默认对齐的差异**：`alignItems` 的默认值是 `'start'`（原生 CSS 默认是 `stretch`）。所以同排卡片需要等高时，**必须显式声名** `alignItems: 'stretch'`。
+- **Dagre 引擎的特殊性**：`layout: 'dagre'` 作为专属拓扑连线引擎，自身不支持 `fill-container` 宽高，对其父容器而言，它是一个自适应（打包裹）的黑盒。
+
+## WBDocument
+
+```typescript
+interface WBDocument {
+  version: 2;
+  nodes: WBNode[];   // 顶层节点。connector 必须放在这里，不能嵌套在 children 中
+}
+```
+
+## 节点类型
+
+### Frame（容器）
+
+唯一可以包含子节点的类型。用于分组、布局、背景。
+
+```typescript
+{
+  type: 'frame';
+  id?: string;
+  x?: number; y?: number;       // Flex 子节点不需要 x/y
+  width: WBSizeValue;
+  height: WBSizeValue;
+  layout: 'horizontal' | 'vertical' | 'none' | 'dagre';  // 布局模式
+  gap: number;                    // 必须显式写（不写节点会粘连，容易出 bug）
+  padding: number | [number, number] | [number, number, number, number]; // 必须显式写（不写内容贴边）
+  justifyContent?: 'start' | 'center' | 'end' | 'space-between' | 'space-around';
+  alignItems?: 'start' | 'center' | 'end' | 'stretch';
+  layoutOptions?: {                 // 仅当 layout 为 'dagre' 时生效
+    rankdir?: 'TB' | 'BT' | 'LR' | 'RL';
+    nodesep?: number;
+    edgesep?: number;
+    ranksep?: number;
+    edges?: Array<[string, string] | [string, string, string]>; // [fromId, toId, label?] 引擎自动排版子节点并生成贝塞尔曲线连线
+    isCluster?: boolean;            // 透明子图。为 true 时子节点参与父级 Dagre 拓扑运算，连线可穿越边界
+    clusterTitle?: string;          // 子图悬浮标题（自动吸附左上角）
+    clusterTitleColor?: string;     // 标题颜色 (HEX格式，如 "#8B5CF6")
+  };
+  fillColor?: string;
+  borderColor?: string;
+  borderWidth?: number;
+  borderDash?: 'solid' | 'dashed' | 'dotted';
+  borderRadius?: number;
+  children?: WBNode[];           // 不能包含 connector
+}
+```
+
+**Dagre 嵌套排版规则**：
+
+1. **不透明节点（Opaque Node）**：Dagre 内的子容器，无论 `layout` 是 `flex`、`absolute` 还是 `dagre`，只要未声明 `isCluster: true`，对外层 Dagre 就是具有确定宽高的不透明原子节点。外层连线无法寻址其内部子节点。
+2. **连线兜底重定向（Edge Redirect Fallback）**：当 `edges` 引用了某不透明节点内部的子节点 ID 时，引擎自动将该连线端点重定向至其最近的不透明祖先节点。不报错，不产生悬空连线。
+3. **透明子图（Compound Cluster）**：子容器同时声明 `layout: "dagre"` 与 `layoutOptions: { isCluster: true }` 时，成为外层 Dagre 的复合子图。其内部子节点直接参与外层拓扑运算，连线可穿越子图边界。子图自身不执行独立排版，尺寸由外层 Dagre 根据内部节点包围盒自动撑开。
+
+**isCluster 最小用法**：
+```json
+{
+  "type": "frame", "id": "cluster_a",
+  "layout": "dagre", "layoutOptions": { "isCluster": true },
+  "fillColor": "#F0FDF4", "borderColor": "#86EFAC", "borderWidth": 2, "borderDash": "dashed", "borderRadius": 16,
+  "children": [
+    { "type": "text", "text": "区域标题", "fontSize": 11, "textColor": "#15803D" },
+    { "type": "rect", "id": "node_inside", "width": 120, "height": 40, "text": "内部节点" }
+  ]
+}
+```
+> 注意：`edges` 必须写在**最外层的根 Dagre** 的 `layoutOptions` 中，不要写在 cluster 内部。
+**其他约束**：
+- `layout / gap / padding` 在 schema 层是 optional，但实际生成时推荐显式写出，避免依赖默认行为。
+- `layoutOptions` 仅在 `layout: 'dagre'` 时生效。
+- `children` 里不能出现 `connector`。
+
+> **虚拟 frame 陷阱**：没有 `fillColor`、`borderColor`、`borderWidth` 的 frame 在编译时可能被当作纯布局容器跳过（子节点直接提升到父级）。如果给这种 frame 设了 `id` 并让外部 connector 连接它，编译后 frame 消失，connector 引用会失效。需要保留这个 frame 时，请给它加上不会被优化掉的外观属性。
+
+### 基础图形
+
+```typescript
+{
+  type: 'rect' | 'ellipse' | 'cylinder' | 'diamond' | 'triangle' | 'trapezoid';
+  id?: string;
+  x?: number; y?: number;
+  opacity?: number;              // 0-1，仅影响 fillColor 的透明度（对 frame/text/stickyNote 无效）
+  vFlip?: boolean;
+  hFlip?: boolean;
+  width: WBSizeValue;
+  height: WBSizeValue;
+  fillColor?: string;
+  borderColor?: string;
+  borderWidth?: number;
+  borderDash?: 'solid' | 'dashed' | 'dotted';
+  borderRadius?: number;
+  topWidth?: number;             // 仅对 triangle / trapezoid 有效，梯形顶边宽度或三角形顶角截断宽度
+  text?: string | WBTextRun[];   // 纯文本或富文本
+  fontSize?: number;
+  textColor?: string;
+  textAlign?: 'left' | 'center' | 'right';     // Shape 默认 'center'（与 CSS 不同）
+  verticalAlign?: 'top' | 'middle' | 'bottom';  // Shape 默认 'middle'（与 CSS 不同）
+}
+```
+
+> **cylinder 约束**：cylinder 的弧度固定 16px，不随宽度缩放。宽度过大会变成扁椭圆。禁止 `width: "fill-container"`，必须用固定宽度 + `height: "fit-content"`。宽度根据文字长度选择，通常 120-200px。
+
+> **Shape 内边距（TEXT_INSET）**：Shape 节点有强制内边距，fit-content 会自动补偿。
+> - rect / ellipse / diamond / triangle：上下左右各 12px
+> - cylinder：顶部弧形 32px + 底部弧形 10px（垂直 +42px），水平各 7px
+>
+> 需要手算固定尺寸时：`实际文字宽/高 + 对应 inset`。
+> 例：rect 内 14px 字号两行文字高 ~32px → `height >= 32 + 24 = 56px`
+
+### Image（图片节点）
+
+图片节点用于在画板中展示图片。图片不能直接使用 URL，必须先上传到飞书获取 media token。
+
+```typescript
+{
+  type: 'image';
+  id?: string;
+  x?: number; y?: number;
+  width: WBSizeValue;           // 固定宽度，推荐 240 或 200
+  height: WBSizeValue;          // 固定高度，推荐按 3:2 比例（如 240×160 或 200×133）
+  image: {
+    src: string;                // media token（通过 docs +media-upload --parent-type whiteboard 上传获取）
+  };
+}
+```
+
+> **关键约束**：
+> - `image.src` 必须是通过 `docs +media-upload --parent-type whiteboard --parent-node <画板token>` 上传后返回的 **media token**，不能是 URL 或 Drive file token
+> - 图片必须上传到**目标画板**，跨画板的 token 不可用
+> - 同一画板内所有 image 节点应使用统一的 width/height，保持视觉一致
+> - 图片宽高比推荐 3:2（如 240×160），避免变形
+> - 详细上传流程见 [`references/image.md`](image.md)
+
+### Text（纯文本节点）
+
+```typescript
+{
+  type: 'text';
+  id?: string;
+  x?: number; y?: number;
+  width: WBSizeValue;
+  height: WBSizeValue;
+  text?: string | WBTextRun[];
+  fontSize?: number;
+  textColor?: string;
+  textAlign?: 'left' | 'center' | 'right';
+  verticalAlign?: 'top' | 'middle' | 'bottom';
+}
+```
+
+### StickyNote（便签）
+
+```typescript
+{
+  type: 'stickyNote';
+  id?: string;
+  x?: number; y?: number;
+  width: WBSizeValue;
+  height: WBSizeValue;
+  fillColor?: '#FEF1CE' | '#F5D1A7' | '#DFF5E5' | '#CDF7CC' | '#C9E8EF' | '#D6DCF3' | '#D3CCEE' | '#F1C5E7' | '#F6C8C8'; // 便签底色（仅支持这 9 种）
+  text?: string | WBTextRun[];
+  fontSize?: number;
+  textColor?: string;
+  textAlign?: 'left' | 'center' | 'right';
+  verticalAlign?: 'top' | 'middle' | 'bottom';
+}
+```
+
+### Connector（连线）
+
+必须放在顶层 `nodes` 数组中，不能嵌套在 frame 的 `children` 里。
+
+```typescript
+{
+  type: 'connector';
+  id?: string;
+  connector: {
+    from: string | { x: number; y: number };   // 节点 id 或坐标
+    to:   string | { x: number; y: number };
+    fromAnchor?: 'top' | 'right' | 'bottom' | 'left';
+    toAnchor?:   'top' | 'right' | 'bottom' | 'left';
+    lineShape?:  'straight' | 'polyline' | 'curve' | 'rightAngle'; // 直线、圆角折线、曲线、直角折线
+    lineColor?: string;
+    lineWidth?: number;
+    lineStyle?: 'solid' | 'dashed' | 'dotted';
+    startArrow?: 'none' | 'arrow' | 'triangle' | 'circle' | 'diamond';
+    endArrow?:   'none' | 'arrow' | 'triangle' | 'circle' | 'diamond';
+    waypoints?: { x: number; y: number }[];  // polyline 途经点
+    label?: string;                          // 连线中间的标签文字
+    labelPosition?: number;                  // 标签位置，0-1，默认 0.5（中点）
+  };
+}
+```
+
+### SVG
+
+```typescript
+{
+  type: 'svg';
+  id?: string;
+  x?: number; y?: number;
+  opacity?: number;
+  width: WBSizeValue;
+  height: WBSizeValue;
+  svg: { code: string };         // SVG 代码字符串
+}
+```
+
+#### 渲染规范
+
+SVG 通过 `image/svg+xml` Blob 加载到画布，**不在 HTML DOM 中**，因此存在严格限制：
+
+**必须**：
+- 包含 `viewBox` 属性（如 `viewBox="0 0 24 24"`），引擎依赖它确定坐标系
+- 包含 `xmlns="http://www.w3.org/2000/svg"`（SVG 作为独立 `image/svg+xml` 解析时，XML 规范要求声明命名空间）
+
+**允许的元素**（纯几何绘制）：
+- 基本图形：`<rect>` `<circle>` `<ellipse>` `<line>` `<polyline>` `<polygon>` `<path>`
+- 渐变/滤镜：`<defs>` `<linearGradient>` `<radialGradient>` `<filter>` `<feGaussianBlur>` `<feMerge>`
+- 结构：`<g>` `<clipPath>` `<mask>` `<use>`
+
+**禁止的元素**（字体和外部资源在 Blob 沙箱中无法加载）：
+- `<text>` `<tspan>`（用同层 DSL rect 节点 + text 属性替代）
+- `<image>`（用同层 DSL image 节点替代）
+- `<foreignObject>`
+- 任何引用外部 URL 的属性（`xlink:href` 指向远程资源等）
+
+#### 两种典型用法
+
+**1. 背景装饰 SVG**（大尺寸，与 frame 同大小）
+
+用于绘制连线、曲线、发光效果等几何背景。文字信息通过同一 frame 内的 rect 节点叠加：
+
+```json
+{
+  "type": "frame", "width": 1400, "height": 680, "layout": "none",
+  "children": [
+    { "type": "svg", "x": 0, "y": 0, "width": 1400, "height": 680,
+      "svg": { "code": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1400 680\" ...>...</svg>" } },
+    { "type": "rect", "x": 100, "y": 50, "width": 200, "height": 40,
+      "text": "Label", "fillColor": "transparent" }
+  ]
+}
+```
+
+**2. 内联图标 SVG**（24-48px，Feather/Lucide 风格）
+
+用于卡片/按钮中的小图标，纯 stroke 线条：
+
+```json
+{ "type": "svg", "width": 32, "height": 32,
+  "svg": { "code": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"#3B82F6\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"12\" cy=\"12\" r=\"10\"/><polyline points=\"12 6 12 12 16 14\"/></svg>" } }
+```
+
+### Icon（内置图标）
+
+引用画板内置图标库的图标。比手写 SVG 更简单——只需指定 `name`。
+
+```typescript
+{
+  type: 'icon';
+  id?: string;
+  x?: number; y?: number;
+  width?: WBSizeValue;          // 默认 48
+  height?: WBSizeValue;         // 默认 48，保持正方形
+  name: string;                 // 图标名称，从 npx -y @larksuite/whiteboard-cli@^0.2.11 --icons 输出中选取
+  color?: string;               // 可选颜色覆盖，hex 格式如 '#FF6600'
+}
+```
+
+**获取可用图标**：规划好内容和布局后，运行以下命令查看所有可用图标名，从中选取：
+```bash
+npx -y @larksuite/whiteboard-cli@^0.2.11 --icons
+```
+
+用法：
+```json
+{ "type": "icon", "id": "db", "name": "database", "width": 48, "height": 48 }
+```
+
+**使用建议**：
+- 当图表中的节点代表具体事物（服务器、用户、数据库等）时，用图标比纯文字方块更直观
+- 一张图 3-8 个图标为宜，为关键组件配图标，次要节点用普通形状
+- 用 `color` 为图标指定合适的颜色, 比如与所在容器的配色一致
+- 图标可放在 frame 子元素中参与 flex 布局，连线可通过 id 连接到图标
+- 图标+文字组合：frame(vertical) 中放 icon + text，形成富组件
+
+```json
+{
+  "type": "frame", "layout": "vertical", "gap": 8, "padding": 12,
+  "alignItems": "center", "fillColor": "#F0F5FF", "borderColor": "#ADC6FF",
+  "children": [
+    { "type": "icon", "id": "db-icon", "name": "database", "width": 36, "height": 36 },
+    { "type": "text", "text": "PostgreSQL", "fontSize": 12, "width": "fit-content", "height": "fit-content" }
+  ]
+}
+```
+
+---
+
+## 富文本 WBTextRun
+
+`text` 字段可以是纯字符串或 `WBTextRun[]` 数组。类似 HTML 内联样式：bold 对应 `<b>`，italic 对应 `<i>`，listType 对应 `<ol>/<ul>`。每个 run 是一段带样式的文字：
+
+```typescript
+interface WBTextRun {
+  content: string;               // 文字内容，可含 \n 换行
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strikeThrough?: boolean;
+  fontSize?: number;
+  color?: string;                // 文字颜色
+  backgroundColor?: string;     // 文字高亮背景
+  hyperlink?: string;
+  listType?: 'none' | 'ordered' | 'unordered';
+  indent?: number;               // 缩进级数
+  quote?: boolean;               // 引用块
+}
+```
+
+示例：
+
+```json
+{
+  "text": [
+    { "content": "标题文字\n", "bold": true, "fontSize": 16 },
+    { "content": "正文内容，", "fontSize": 14 },
+    { "content": "高亮部分", "backgroundColor": "#FEF1CE", "fontSize": 14 }
+  ]
+}
+```
+
+`text` 和 `content` 中出现的双引号必须写成 `\"`，这是 JSON 规范要求。换行用 `\n`（JSON 中写为 `"第一行\n第二行"`，不要双重转义为 `\\n`）。
+
+---
+
+## 尺寸值 WBSizeValue
+
+| 值                    | 含义                        | 注意                                   |
+| --------------------- | --------------------------- | -------------------------------------- |
+| `number`              | 固定像素                    | 任何场景                               |
+| `'fit-content'`       | 由内容决定大小              | 父级需要 Flex 布局                     |
+| `'fit-content(N)'`    | 同上，无内容时 fallback N   | 同上                                   |
+| `'fill-container'`    | 填满父级剩余空间            | 父级需要 Flex 布局，且祖先链有固定宽度 |
+| `'fill-container(N)'` | 同上，无 Flex 时 fallback N | —                                      |
+
+`fill-container` 在 `layout: 'none'`（绝对定位）下无效。`fit-content` 仍可用于含文字节点（引擎通过 Yoga measureFunc 测量文字尺寸）。

package/dist/skills/larksuite/lark-whiteboard/references/style.md

@@ -0,0 +1,318 @@
+# 配色系统
+
+## 怎么上色（最重要）
+
+上色步骤：
+
+1. **找出图中有几个分组**（层级、分支、类别、阶段...）
+2. **为每个分组选一种不同颜色**（从色板中选 2-4 种颜色）
+3. **分组容器**用浅色填充 — 告诉读者"这块是一个整体"
+4. **分组内节点**用白色填充 + 该分组的深色 borderColor — 告诉读者"这些属于这个分组"
+
+具体映射（经典色板）：
+
+| 分组 | 层容器 fillColor | 层容器 borderColor | 内部节点 borderColor |
+|------|----------------|-------------------|---------------------|
+| 第 1 组 | #F0F4FC（浅蓝） | #5178C6 | #5178C6 |
+| 第 2 组 | #EAE2FE（浅紫） | #8569CB | #8569CB |
+| 第 3 组 | #DFF5E5（浅绿） | #509863 | #509863 |
+| 第 4 组 | #FEF1CE（浅黄） | #D4B45B | #D4B45B |
+| 第 5 组 | #FEE3E2（浅红） | #D25D5A | #D25D5A |
+| 内部节点 | #FFFFFF | 跟随所属分组 | — |
+
+**各类图表怎么上色**：
+- 架构图有 3 层 → 每层一种颜色，层背景浅色填充，层内节点白色+深色边框
+- 对比表有 3 列 → 每列表头一种颜色，该列数据单元格用同色边框
+- 组织架构有 4 个部门 → 每个部门一种颜色，子部门白色+同色边框
+- 流程图 → 起止节点一种颜色，判断节点一种颜色，步骤节点白色
+
+> [!IMPORTANT]
+> **用户配色优先。** 用户指定了色值/风格时以用户为准。用户只给 1-2 个色值时，推导完整色板：主色→浅底→深边框→灰调连线色。
+> 用户**未指定**配色时，必须从上方色板表中选取颜色，不要使用表中没有的自创色值（如 `#E8F3FF`、`#1664FF`、`#14C9C9` 等都不在色板中）。
+
+---
+
+## 结构规则
+
+### 分组 — 不同层/分组必须用不同颜色
+
+选 2-4 种颜色，每种代表一个分组。同组节点视觉完全一致（fillColor、borderColor 相同）。
+
+### 分层 — 外重内轻
+
+- 外层（大分区）：浅色填充背景
+- 内层（具体节点）：白色填充 + 分组色边框
+
+### 清晰
+
+- 所有节点有边框（borderWidth=2）
+- 间距不粘连（gap >= 8，有连线时 >= 40）
+- 文字在背景上清晰可读（fontSize >= 14）。文字与背景色对比度应足够（参考 WCAG 2.1：正文至少 4.5:1，标题至少 3:1）
+- 不要仅靠颜色区分信息——同时使用边框、形状或文字标签辅助，确保色觉障碍用户也能理解
+- 连线用灰色（#BBBFC4），不抢节点注意力
+
+### 统一参数
+
+| 参数 | 值 | 为什么 |
+|------|---|--------|
+| borderWidth | 2 | 让边框清晰可见 |
+| borderRadius | 8 | 统一的圆角，整洁 |
+| gap（最小值） | 8 | 元素不粘连 |
+| padding（最小值） | 8 | 内容不贴边 |
+| gap（有连线时） | 40 | 给箭头留空间 |
+| fontSize（正文） | >= 14 | 可读 |
+| fontSize（标题） | >= 24 | 醒目 |
+| fontSize（辅助） | >= 13 | 不费眼 |
+
+---
+
+## 色板选择指南
+
+根据用户需求的关键词或场景选择合适的色板。未指定时默认使用"经典"色板。
+
+| 色板 | 适用场景 | 关键词 |
+|------|---------|-------|
+| 经典 | 通用图表、说明文档 | 默认、通用 |
+| 商务 | 汇报、企业架构、正式文档 | 专业、正式、给老板看 |
+| 科技 | 技术架构、DevOps、监控 | 技术、炫酷、暗色 |
+| 清新 | 流程图、用户旅程、教程 | 清新、自然、轻松 |
+| 极简 | 论文配图、学术报告 | 学术、极简、黑白 |
+
+---
+
+## 预设色板
+
+每套色板定义 7 个角色的颜色。**连线色是色板的一部分**，不同色板的连线色不同。
+
+### 经典
+
+| 角色 | fillColor | borderColor | textColor |
+|------|-----------|-------------|-----------|
+| 分区背景 | #F0F4FC | #5178C6 | #1F2329 |
+| 分组标题 | #EAE2FE | #8569CB | #1F2329 |
+| 内容节点 | #FFFFFF | #5178C6 | #1F2329 |
+| 第二分组 | #DFF5E5 | #509863 | #1F2329 |
+| 第三分组 | #FEF1CE | #D4B45B | #1F2329 |
+| 第四分组 | #FEE3E2 | #D25D5A | #1F2329 |
+| 强调/表头 | #1F2329 | #1F2329 | #FFFFFF |
+| 连线 | -- | -- | #BBBFC4 |
+
+### 商务
+
+| 角色 | fillColor | borderColor | textColor |
+|------|-----------|-------------|-----------|
+| 分区背景 | #EDF2F7 | #4A6FA5 | #1A202C |
+| 分组标题 | #D4E0ED | #4A6FA5 | #1A202C |
+| 内容节点 | #FFFFFF | #718BAE | #1A202C |
+| 第二分组 | #E8EDF3 | #5A7B9A | #1A202C |
+| 第三分组 | #F0F0F0 | #8895A7 | #1A202C |
+| 强调/表头 | #2D4A7A | #2D4A7A | #FFFFFF |
+| 连线 | -- | -- | #718BAE |
+
+### 科技
+
+| 角色 | fillColor | borderColor | textColor |
+|------|-----------|-------------|-----------|
+| 画布/分区背景 | #0F172A | #1E293B | #E2E8F0 |
+| 分组标题 | #1E293B | #3B82F6 | #E2E8F0 |
+| 内容节点 | #1E293B | #334155 | #E2E8F0 |
+| 第二分组 | #1E293B | #8B5CF6 | #E2E8F0 |
+| 第三分组 | #1E293B | #10B981 | #E2E8F0 |
+| 强调 | #2563EB | #3B82F6 | #FFFFFF |
+| 连线 | -- | -- | #475569 |
+
+### 清新
+
+| 角色 | fillColor | borderColor | textColor |
+|------|-----------|-------------|-----------|
+| 分区背景 | #F0FDF4 | #86EFAC | #14532D |
+| 分组标题 | #DCFCE7 | #4ADE80 | #14532D |
+| 内容节点 | #FFFFFF | #86EFAC | #14532D |
+| 第二分组 | #ECFDF5 | #6EE7B7 | #14532D |
+| 第三分组 | #F0FDFA | #5EEAD4 | #134E4A |
+| 强调 | #16A34A | #16A34A | #FFFFFF |
+| 连线 | -- | -- | #86EFAC |
+
+### 极简
+
+| 角色 | fillColor | borderColor | textColor |
+|------|-----------|-------------|-----------|
+| 分区背景 | #F8F9FA | #DEE2E6 | #212529 |
+| 分组标题 | #E9ECEF | #ADB5BD | #212529 |
+| 内容节点 | #FFFFFF | #CED4DA | #212529 |
+| 第二分组 | #F1F3F5 | #868E96 | #212529 |
+| 第三分组 | #F8F9FA | #ADB5BD | #212529 |
+| 强调/表头 | #495057 | #495057 | #FFFFFF |
+| 连线 | -- | -- | #ADB5BD |
+
+---
+
+## 各元素怎么画
+
+> 以下示例使用经典色板。如果选了其他色板，替换对应颜色即可，结构保持不变。
+
+### 图表标题
+
+告诉读者"这张图讲什么"。大号深色文字，居中。
+
+```json
+{ "type": "text", "fontSize": 24, "textColor": "#1F2329", "textAlign": "center" }
+```
+
+### 分区背景
+
+把相关的内容圈在一起，告诉读者"这些属于同一个大类"。浅色做 fillColor，对应深色做 borderColor。内部放白色节点。
+
+```json
+{ "fillColor": "#F0F4FC", "borderColor": "#5178C6", "borderWidth": 2, "borderRadius": 8, "padding": 20 }
+```
+
+### 分区标签
+
+给分区一个名字。用独立 text 节点，不要用 frame 的 `title` 属性（会被渲染为极小标题栏）。
+
+**所有分区标签统一用深色文字 `#1F2329`**，不要给每个标签用不同颜色——颜色区分通过层容器背景和边框体现，标签文字颜色保持一致。
+
+```json
+{ "type": "text", "width": 180, "height": "fit-content", "text": "Access layer", "fontSize": 20, "textColor": "#1F2329", "textAlign": "right" }
+```
+
+### 分组标题
+
+告诉读者"这个子分组叫什么"。色板色填充 + 同色系深色边框。
+
+```json
+{ "fillColor": "#EAE2FE", "borderColor": "#8569CB", "borderWidth": 2, "borderRadius": 8, "fontSize": 14, "textColor": "#1F2329" }
+```
+
+### 内容节点
+
+具体的信息项。白色填充，边框颜色跟随所属分组。
+
+```json
+{ "fillColor": "#FFFFFF", "borderColor": "#5178C6", "borderWidth": 2, "borderRadius": 8, "fontSize": 14, "textColor": "#1F2329" }
+```
+
+白色节点的 borderColor 取决于它所属的分组：
+```
+属于蓝色分组: fillColor="#FFFFFF"  borderColor="#5178C6"  borderWidth=2
+属于紫色分组: fillColor="#FFFFFF"  borderColor="#8569CB"  borderWidth=2
+独立节点:     fillColor="#FFFFFF"  borderColor="#DEE0E3"  borderWidth=2
+```
+（注：以上为经典色板的值，其他色板替换对应的 borderColor）
+
+### 表头
+
+告诉读者"这一列/行是什么维度"。深色填充 + 白色文字。
+
+```json
+{ "fillColor": "#1F2329", "borderColor": "#1F2329", "borderWidth": 2, "borderRadius": 0, "fontSize": 15, "textColor": "#FFFFFF", "textAlign": "center" }
+```
+
+### 图标组件
+
+icon + text 的组合卡片。icon 的 `color` 跟随所属分组的 borderColor，与其他节点视觉一致。
+
+```json
+{
+  "type": "frame", "layout": "vertical", "gap": 4, "padding": 12,
+  "alignItems": "center", "fillColor": "#FFFFFF", "borderColor": "#5178C6", "borderWidth": 2, "borderRadius": 8,
+  "children": [
+    { "type": "icon", "name": "server", "width": 36, "height": 36, "color": "#5178C6" },
+    { "type": "text", "width": "fit-content", "height": "fit-content", "text": "应用服务器", "fontSize": 12 }
+  ]
+}
+```
+
+icon color 需要结合上下文选择合适的颜色, 比如: 使用所属分组的borderColor
+
+### textColor 规则
+
+```
+- 正文：#1F2329（深色，在白底/浅色底上清晰）
+- 辅助说明：#646A73（弱化，不抢注意力）
+- 深色底上：#FFFFFF（反色，清晰可读）
+（以上为经典色板的值，其他色板参考对应 textColor 列）
+```
+
+### 辅助说明
+
+补充信息，不抢主角的注意力。灰色小字。
+
+```json
+{ "fontSize": 13, "textColor": "#646A73" }
+```
+
+### 连线
+
+表达元素之间的关系或流向。使用色板中的连线色。
+
+```json
+{ "lineColor": "#BBBFC4", "lineWidth": 2 }
+```
+
+### 布局容器
+
+纯粹用来排版的 frame，读者看不见它。不设 fillColor、borderColor。
+
+```json
+{ "type": "frame", "layout": "vertical", "gap": 28, "padding": 32 }
+```
+
+### 分组容器
+
+用虚线框圈定一组节点，比分区背景更轻量。
+
+```json
+{ "borderColor": "#DEE0E3", "borderWidth": 2, "borderDash": "dashed", "borderRadius": 8 }
+```
+
+---
+
+## 常见错误
+
+错误：每个节点一种颜色 -> 读者分不清谁和谁是一组
+```json
+{ "fillColor": "#8569CB" }, { "fillColor": "#5178C6" }, { "fillColor": "#509863" }
+```
+正确：同组节点视觉一致 -> 读者一眼看出关系
+```json
+{ "fillColor": "#FFFFFF", "borderColor": "#8569CB" }, { "fillColor": "#FFFFFF", "borderColor": "#8569CB" }
+```
+
+错误：内外层都用重色 -> 读者不知道先看哪里
+```json
+{ "type": "frame", "fillColor": "#5178C6", "children": [{ "fillColor": "#8569CB" }] }
+```
+正确：外层浅色内层白色 -> 读者先看结构再看细节
+```json
+{ "type": "frame", "fillColor": "#F0F4FC", "children": [{ "fillColor": "#FFFFFF", "borderColor": "#5178C6" }] }
+```
+
+错误：连线用和节点一样的彩色 -> 和节点颜色抢注意力
+```json
+{ "connector": { "lineColor": "#5178C6" } }
+```
+正确：连线用色板中的连线色 -> 衬托节点
+```json
+{ "connector": { "lineColor": "#BBBFC4" } }
+```
+
+错误：节点没边框 -> 和背景融为一体，看不清边界
+```json
+{ "fillColor": "#FFFFFF" }
+```
+正确：节点有边框 -> 边界清晰
+```json
+{ "fillColor": "#FFFFFF", "borderColor": "#DEE0E3", "borderWidth": 2 }
+```
+
+错误：全图黑白灰，没有颜色区分 -> 读者无法快速识别分组
+```json
+{ "fillColor": "#FFFFFF", "borderColor": "#DEE0E3" }
+```
+正确：不同分组用不同颜色 -> 一眼看出结构（蓝色分组 + 紫色分组）
+```json
+{ "fillColor": "#F0F4FC", "borderColor": "#5178C6" }
+{ "fillColor": "#EAE2FE", "borderColor": "#8569CB" }
+```