docs(slides): add whiteboard element documentation and improve slide guidance (#1029)

* feat(slides): add whiteboard element support and reference documentation - Add lark-slides-whiteboard.md covering SVG and Mermaid modes, routing rules, layout examples, known issues, and self-check checklist - Register <whiteboard> in slides_xml_schema_definition.xml; remove it from the undefined element type list - Update SKILL.md quick-reference table and按需再读 section to point to the new whiteboard reference - Update xml-schema-quick-ref.md with <whiteboard> syntax examples - Update slide create/get/replace references to include whiteboard as a valid <data> child element - Tighten fallback_if_missing descriptions in planning-layer.md and asset-planning.md: replace "shapes" wording with neutral intent language and add "whiteboard diagrams" to the fallback tool lists Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(slides): refine whiteboard reference doc structure and content - Restructure doc: common attributes and prerequisites moved to top - Move design quality rules under SVG mode section - Add z-order inline note to full-screen layout example - Replace JS coordinate script with Python, broaden scope to decorative elements - Delete redundant Mermaid examples (keep one complete whiteboard+flowchart) - Add prerequisite link and references section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(slides): clarify chart vs whiteboard selection and fix doc gaps - lark-slides-whiteboard: add chart vs whiteboard decision table at top; fix intro and SVG use-case list to remove bar/line (those belong to <chart>) - SKILL.md: split whiteboard quick-ref row into chart row + whiteboard row; fix sidebar link label to match actual scope - asset-planning: correct chart asset type — remove funnel/scatter (unsupported by <chart> XSD) and note they fall back to <whiteboard> SVG - visual-planning: add one-line whiteboard preference hint to architecture-diagram and process-flow layout types - validation-checklist: add Whiteboard Elements section noting slide.get does not return SVG/Mermaid content; content correctness requires manual visual sign-off Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(slides): add SVG decorative visibility principles Add two design rules to SVG quality requirements: check background luminance before writing SVG (dark bg requires higher contrast), and use non-linear brightness jumps (e.g. 0.10→0.40→0.70→1.0) instead of linear opacity stacking (0.04→0.08→0.12) which produces near-identical layers on dark backgrounds. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(slides): add custom icon use case to whiteboard SVG Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(slides): fix whiteboard SVG rendering rules - content area is determined by child element bounding box union, not svg width/height/viewBox/xmlns - viewBox only purpose: provide reference for percentage-based attribute values; omit when using absolute coords - remove redundant attributes from all svg examples, use bare <svg> tags - drop positive/negative coordinate guidance; rendering rule simplified to bounding-box auto-scale
2026-07-03 14:02:43 +08:00 · 2026-06-04 11:58:09 +08:00
parent 8ce38793a7
commit 7a0dbe057b
12 changed files with 437 additions and 17 deletions
--- a/skills/lark-slides/SKILL.md
+++ b/skills/lark-slides/SKILL.md
@@ -19,6 +19,8 @@ metadata:
 | 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
 | 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` |
 | 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 |
+| 在 slide 中绘制柱/条/折线/面积/雷达/饼等有数据序列的图表 | 使用原生 `<chart>` 元素 | `xml-schema-quick-ref.md` |
+| 在 slide 中绘制流程图、时序图、架构图、散点图、漏斗图或装饰图案 | 必须先用 Read 工具读取参考文档，再生成 `<whiteboard>` 元素 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) |
 | 用户提到模板、主题、版式 | 先检索模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` |
 | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |

@@ -80,6 +82,7 @@ lark-cli auth login --domain slides
 - 创建：[`lark-slides-create.md`](references/lark-slides-create.md)
 - 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)
 - 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
+- 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md)
 - 模板：[`template-catalog.md`](references/template-catalog.md)、[`scripts/template_tool.py`](scripts/template_tool.py)
 - 排障：[`troubleshooting.md`](references/troubleshooting.md)
 - 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml)
@@ -183,7 +186,7 @@ lark-cli slides xml_presentation.slide create \
  --data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
  <style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
  <data>
-    在这里放置 shape、line、table、chart 等元素
+    在这里放置 shape、line、table、chart、whiteboard 等元素
  </data>
 </slide>' '{slide:{content:$content}}')"

--- a/skills/lark-slides/references/asset-planning.md
+++ b/skills/lark-slides/references/asset-planning.md
@@ -1,13 +1,13 @@
 # Asset Planning

-新建演示文稿或大幅改写页面时，在写入 `slide_plan.json` 前后都可以参考本文件。目标是让 agent 主动识别有价值的图、图标、图表、截图或示意图需求，同时保持 deck 在没有真实素材时也能完整执行。
+新建演示文稿或大幅改写页面时，在写入 `slide_plan.json` 前后都可以参考本文件。目标是让 agent 主动识别有价值的图、图标、图表、流程图、时序图、架构图、装饰图案、截图或示意图需求，同时保持 deck 在没有真实素材时也能完整执行。

 本文件只定义轻量资产规划。不要把它理解成素材采集流程。

 ## Core Rules

 - `asset_need` is metadata only. It can guide page design, but it must not require web search, local download, media upload, or external tools.
- Every planned asset must include a fallback visual plan so the slide can be generated with XML shapes, text, arrows, tables, simple charts, or placeholder regions.
+- Every planned asset must include a fallback visual plan so the slide can be generated with XML shapes, text, arrows, tables, simple charts, whiteboard diagrams, or placeholder regions.
 - Asset needs must serve the page's `key_message` and `visual_focus`. Do not add decorative assets that do not clarify the page.
 - Prefer a few high-value asset plans over one asset on every page. For a 6-page technical or business deck, plan assets on at least 3 pages when the content allows.
 - If a real local asset already exists or the user provides one, it can be used through the normal media-upload workflow. Still keep `fallback_if_missing` in the plan.
@@ -22,7 +22,7 @@ Use an object for one planned asset, or an array when a page genuinely needs mul
  "asset_type": "architecture_diagram",
  "purpose": "Show how API gateway, planner, XML generator, and Slides API interact.",
  "suggested_query": "agent native slides runtime architecture diagram",
-  "fallback_if_missing": "Draw grouped boxes and arrows with XML shapes; use labels instead of an image."
+  "fallback_if_missing": "Draw grouped boxes connected by arrows with short labels."
 }
 ```

@@ -43,7 +43,7 @@ For a page without a meaningful asset need, use:
 - `architecture_diagram`: system components, data flow, dependency map, or model structure.
 - `icon`: small semantic symbol for a concept, step, role, or status.
 - `logo`: brand, product, team, or customer mark.
- `chart`: line, bar, pie, funnel, scatter, or chart-like data visual.
+- `chart`: line, bar, pie, radar, area, or combo data visual. Note: `<chart>` does not support funnel or scatter — map those to `<whiteboard>` SVG at generation time.
 - `infographic`: composed visual explanation, usually combining labels, numbers, and simple shapes.
 - `screenshot`: product UI, terminal output, workflow state, or page capture.
 - `flow_diagram`: process, sequence, decision tree, or mechanism diagram.
@@ -118,7 +118,7 @@ Business comparison page:
 When generating XML:

 1. If an asset exists and the workflow supports it, place it in the planned visual region.
-2. If no asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, or chart-like elements.
+2. If no asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, whiteboard diagrams, or chart-like elements.
 3. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration.
 4. Keep text-density limits. Do not compensate for missing assets by adding long bullet text.
 5. After creation, fetch the presentation and verify asset pages are not blank and that each planned fallback is visible when no real asset was used.
--- a/skills/lark-slides/references/lark-slides-replace-slide.md
+++ b/skills/lark-slides/references/lark-slides-replace-slide.md
@@ -88,10 +88,11 @@ lark-cli slides +replace-slide --as user \
 | `<table>` | 表格 | 整表替换会**重建内部 td id**，旧 td block_id 立即失效 |
 | `<td>` | 单元格局部替换 | 只能 `block_replace`，不能 `block_insert`；`block_id` 必须是最新 `slide.get` 拿到的 td id |
 | `<chart>` | 图表（line/bar/column/pie/area/radar/combo） | 必须嵌 `<chartPlotArea>` + `<chartData>` + `<dim1>/<dim2>/<chartField>` |
+| `<whiteboard>` | 画板（SVG 或 Mermaid） | 内嵌 `<svg>` 或 `<mermaid>`；`slide.get` 返回结构不含内部数据，但可直接写完整新 XML 做 `block_replace` 覆盖；详见 [`lark-slides-whiteboard.md`](lark-slides-whiteboard.md) |

 **不可作为根元素**：

- `<video>` / `<audio>` / `<whiteboard>` —— SML 2.0 没有这三个原生元素；`<undefined type="video|audio|whiteboard">` 是**导出时**的占位符（服务端遇到不支持的类型时用它代替），**不能写入**。尝试 insert/replace 都会返回 3350001。
+- `<video>` / `<audio>` —— SML 2.0 没有这两个原生元素；`<undefined type="video|audio">` 是**导出时**的占位符（服务端遇到不支持的类型时用它代替），**不能写入**。尝试 insert/replace 都会返回 3350001。

 ### 最小 XML 片段（JSON 嵌入时记得把 `"` 转义成 `\"`）

--- a/skills/lark-slides/references/lark-slides-whiteboard.md
+++ b/skills/lark-slides/references/lark-slides-whiteboard.md
@@ -0,0 +1,330 @@
+# Whiteboard 画板元素
+
+`<whiteboard>` 放在 `<data>` 内，内部可放 **SVG** 或 **Mermaid**，用于绘制流程图、时序图、架构图、散点图、漏斗图、自定义图标、装饰图案等 `<chart>` 和 `<shape>` 难以覆盖的视觉内容。
+
+> 前置条件：使用本文档前先阅读 [lark-slides SKILL.md](../SKILL.md)。
+
+---
+
+## `<chart>` 还是 `<whiteboard>`？
+
+**先判断内容类型，再进入本文档：**
+
+| 场景 | 推荐元素 |
+|------|---------|
+| 有结构化数据序列的柱/条/折线/面积/雷达/饼/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
+| 散点图、漏斗图（`<chart>` 不支持） | `<whiteboard>` SVG |
+| 流程图、时序图、架构图、类图、ER 图等拓扑图 | `<whiteboard>` Mermaid 或 SVG |
+| 自定义图标、徽标、示意性图形（需要 path/polygon 精确控制） | `<whiteboard>` SVG |
+| 进度条、波浪背景、装饰图案、像素级自定义可视化 | `<whiteboard>` SVG |
+
+> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG 手绘——原生渲染更省力且质量更高。
+
+---
+
+## whiteboard 公共属性
+
+| 属性 | 必需 | 说明 |
+|------|------|------|
+| `topLeftX` | 是 | 左上角 X 坐标（slide 坐标系，slide 默认宽 960） |
+| `topLeftY` | 是 | 左上角 Y 坐标（slide 坐标系，slide 默认高 540） |
+| `width` | 是 | 画板宽度（像素） |
+| `height` | 是 | 画板高度（像素） |
+
+> SVG 模式下 `<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`；内容大小由子元素包围盒决定，`width`/`height`/`viewBox` 不影响渲染（仅当元素属性使用百分比值时需要 `viewBox` 提供计算基准）。Mermaid 模式不需要额外属性。
+
+SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标系无关。
+
+---
+
+## SVG 还是 Mermaid？
+
+选择分两步：**先看图表类型，再看当前模型身份**。
+
+### 第一步：图表类型优先判断
+
+以下类型**推荐 Mermaid**，自动布局、代码简洁；如需精确匹配品牌配色或自定义节点样式，可改用 SVG：
+
+| 图表类型 | Mermaid 关键字 |
+|----------|--------------|
+| 流程图、决策树、架构图 | `flowchart TD` / `flowchart LR` |
+| 时序图 | `sequenceDiagram` |
+| 类图 | `classDiagram` |
+| 饼图 | `pie` |
+| 甘特图 | `gantt` |
+| 状态图 | `stateDiagram-v2` |
+| 思维导图 | `mindmap` |
+| ER 图 | `erDiagram` |
+
+### 第二步：数据图表与装饰元素按模型身份选路径
+
+上表以外的场景（散点图、漏斗图、进度条、时间线、波浪背景、星点纹理等）需要精确控制坐标和配色，SVG 表达力更强，但各模型生成 SVG 的能力有差异：
+
+| 模型身份 | 路径 |
+|----------|------|
+| Claude / Gemini / GPT / GLM | **SVG** — 精确控制坐标、颜色、透明度 |
+| Doubao / Seed / Other | **Mermaid** — 用 `pie`、`gantt` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
+
+> **先自报身份再选路径**：在决定使用 SVG 之前，确认当前模型属于哪一类。不要跳过这一步。
+
+---
+
+## 模式一：SVG
+
+### ⚠️ 设计品质要求
+
+在 slide 里嵌入 `<whiteboard>` 的目的是**提升视觉质量**，不是把数字堆进去。
+
+- **不要只用矩形加文字应付**：通篇纯白底色 + 方块 + 黑字等于白做，这是不及格输出
+- **数据图表必须有坐标系**：坐标轴、网格线、数值标注缺一不可，不要只画柱子或点
+- **字号必须有层级**：标题 ≠ 标签 ≠ 数值，混用同一字号会消灭视觉焦点
+- **配色要与 slide 主题呼应**：深色 slide 背景下图表用透明底或深色卡片；浅色背景下避免再加纯白底块
+- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、折线面积、点装饰等细节拉开与默认模板的差距
+- **写 SVG 前先判断背景亮度**：背景亮度 < 30% 时，装饰元素"对比不足"比"过强"危害更大，宁重勿轻；
+- **装饰层次用亮度跳跃，不用线性叠透明度**：`α=0.04→0.08→0.12` 的等差递增在深色底上几乎看不出差异（相邻层亮度差 ≈20）；正确做法是非线性跳跃如 `0.10→0.40→0.70→1.0`，相邻层亮度差 ≥60。
+
+### 语法
+
+```xml
+<whiteboard width="400" height="300" topLeftX="500" topLeftY="120">
+  <svg xmlns="http://www.w3.org/2000/svg">
+    <rect x="50" y="50" width="80" height="200" rx="4" fill="rgba(59,130,246,0.85)"/>
+    <text x="90" y="270" text-anchor="middle" font-size="12" fill="rgba(100,116,139,1)">ABC</text>
+  </svg>
+</whiteboard>
+```
+
+`<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`；`width`/`height`/`viewBox` 无需填写，若元素属性使用百分比值则需额外声明 `viewBox`。
+
+### ⚠️ 渲染包围盒规则
+
+whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内容区域，自适应缩放到容器。
+
+`<svg>` 上的 `width`、`height`、`viewBox` 不影响内容区域的计算，但 `viewBox` 有一个实际用途：**为百分比属性提供计算基准**。若元素使用 `width="50%"` 等百分比值，必须声明 `viewBox` 才能正确解析；绝对坐标元素则无需关心。推荐统一使用绝对坐标，避免引入百分比依赖。
+
+### 支持的 SVG 元素
+
+| 元素 | 说明 | 典型用途 |
+|------|------|---------|
+| `<rect>` | 矩形，支持 `rx` 圆角 | 柱图、卡片、进度条 |
+| `<circle>` | 圆 | 节点、装饰点、环形图 |
+| `<ellipse>` | 椭圆 | 自定义轮廓图形 |
+| `<line>` | 直线 | 坐标轴、分隔线 |
+| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、折线、弧形 |
+| `<text>` | 文本，支持中文 | 标签、数值 |
+| `<polygon>` | 多边形 | 箭头、星形、面积填充 |
+| `<g>` | 分组 | 批量变换、语义分组 |
+| `<linearGradient>` | 线性渐变定义，配合 `fill="url(#id)"` 使用 | 渐变背景、渐变填充 |
+
+**颜色：** 统一用 `rgba(R,G,B,A)`，对深浅背景都友好。  
+**虚线：** `stroke-dasharray="4,4"` 用于网格线 / 坐标轴。  
+**变换：** `transform="translate(x,y)"` / `rotate(deg cx cy)` / `scale(n)` 均支持。
+
+---
+### 元素计算
+
+SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围不限于数据图表——装饰性点阵、等间距圆、重复图案同样适用。
+
+> **主动去算**：写 SVG 之前先运行脚本，把输出当注释贴在 `<svg>` 开头，再照着填坐标。估值几乎每次都需要反复调整，跳过这步反而更慢。
+
+**数据图表（柱状图范式）**
+
+```python
+W, H = 360, 260
+origin_x, origin_y = 50, 216  # 左下角，SVG Y 轴向下
+cw, ch = 290, 184
+
+data, y_max = [120, 160, 90], 200
+bar_w = int(cw / len(data) * 0.62)
+for i, v in enumerate(data):
+    cx = round(origin_x + (i + 0.5) * cw / len(data))
+    y  = round(origin_y - v / y_max * ch)
+    print(f"bar-{i}: x={cx - bar_w//2} y={y} w={bar_w} h={round(origin_y - y)}")
+```
+
+折线图：`x = origin_x + i/(n-1)*cw`，`y = origin_y - (v-y_min)/(y_max-y_min)*ch`。
+
+**装饰性元素（等间距范式）**
+
+```python
+n, total_w, cy, r = 8, 340, 40, 4
+step = total_w / (n - 1)
+for i in range(n):
+    print(f"circle-{i}: cx={round(i * step)} cy={cy} r={r}")
+```
+
+**最大包围盒 → whiteboard 尺寸**
+
+所有元素坐标算完后，汇总出整体包围盒，直接作为 whiteboard 的 `width`/`height`：
+
+```python
+# 每个元素登记 (x, y, w, h)，含 stroke 外扩
+elements = [
+    (10, 20, 80, 160),   # bar-0
+    (107, 10, 80, 170),  # bar-1
+    (204, 40, 80, 140),  # bar-2
+    (0, 0, 300, 1),      # x-axis
+]
+
+xs = [x for x, y, w, h in elements]
+ys = [y for x, y, w, h in elements]
+x2 = [x + w for x, y, w, h in elements]
+y2 = [y + h for x, y, w, h in elements]
+
+wb_w = max(x2) - min(xs)
+wb_h = max(y2) - min(ys)
+print(f"whiteboard width={wb_w} height={wb_h}")
+```
+
+输出即 `<whiteboard width=... height=...>` 的值，无需手动估算。
+
+---
+### 布局模式
+
+**全屏装饰层**
+```xml
+<whiteboard width="960" height="540" topLeftX="0" topLeftY="0">
+  <svg xmlns="http://www.w3.org/2000/svg">
+    ...
+  </svg>
+</whiteboard>
+```
+
+> ⚠️ 全屏装饰 whiteboard 必须放在所有 `<shape>` / `<img>` / `<table>` 之前，否则会遮挡文字内容。XML 中元素位置越靠后，渲染层级越高。
+
+**侧栏图表（与文字 shape 并排）**
+```xml
+<!-- 左侧文字 -->
+<shape type="text" topLeftX="60" topLeftY="120" width="500" height="340">...</shape>
+<!-- 右侧图表 -->
+<whiteboard width="340" height="340" topLeftX="580" topLeftY="120">
+  <svg xmlns="http://www.w3.org/2000/svg">
+    ...
+  </svg>
+</whiteboard>
+```
+
+**底部装饰条**
+```xml
+<whiteboard width="960" height="100" topLeftX="0" topLeftY="440">
+  <svg xmlns="http://www.w3.org/2000/svg">
+    ...
+  </svg>
+</whiteboard>
+```
+
+---
+
+### 禁止使用的 SVG 特性
+
+以下特性在 slide `<whiteboard>` 渲染端不支持或行为不可预测，必须避免：
+
+| 禁止 | 原因 | 替代方案 |
+|------|------|---------|
+| `<radialGradient>` | 渲染失败 | 用 `<linearGradient>` 或 `rgba()` 透明度模拟深浅层次 |
+| `<filter>`（阴影、模糊等） | 渲染失败 | 用半透明 `<rect>` 叠加模拟阴影 |
+| `<clipPath>` / `<mask>` | 渲染失败 | 调整元素坐标和尺寸自然裁切 |
+| `<pattern>` | 渲染失败 | 手动铺 `<circle>` / `<rect>` 点阵 |
+| `skewX` / `skewY` / `matrix(...)` | 空间扭曲，降级渲染 | 用 `rotate` + `translate` 替代 |
+| `<image>` 外链 URL | 不支持外链 | 先上传得到 file_token，再用 `<img>` 元素 |
+
+---
+
+
+## 模式二：Mermaid
+
+### 语法
+
+```xml
+<whiteboard topLeftX="72" topLeftY="60" width="816" height="360">
+  <mermaid>
+    <![CDATA[
+        flowchart TD
+            A[检查 lark-cli 与 jq] --> B[编写每页 slide XML]
+            B --> C[通过 jq 生成 slides JSON]
+            C --> D[执行 slides +create]
+            D --> E[读取 xml_presentation_id]
+            E --> F[回读并验证创建结果]
+    ]]>
+  </mermaid>
+</whiteboard>
+```
+
+**关键点：**
+- 内容用 `<![CDATA[...]]>` 包裹——Mermaid 语法里的 `[`、`>`、`-->` 是 XML 特殊字符，CDATA 避免转义问题
+- whiteboard 只需 `topLeftX`、`topLeftY`、`width`、`height`
+
+### 支持的 Mermaid 图表类型
+
+| 类型 | 关键字 | 适用场景 |
+|------|--------|---------|
+| 流程图 | `flowchart TD` / `flowchart LR` | 业务流程、决策树、工作流 |
+| 时序图 | `sequenceDiagram` | 系统交互、API 调用链 |
+| 甘特图 | `gantt` | 项目计划、里程碑 |
+| 饼图 | `pie` | 占比数据 |
+| 类图 | `classDiagram` | 对象关系、架构设计 |
+| ER 图 | `erDiagram` | 数据库结构 |
+| 状态图 | `stateDiagram-v2` | 状态机、生命周期 |
+| 思维导图 | `mindmap` | 主题梳理、知识架构 |
+| 用户旅程 | `journey` | 用户体验路径 |
+
+### Mermaid 布局建议
+
+Mermaid 图表会自动撑满 whiteboard 区域。建议：
+- 流程图留足高度，节点较多时适当增加 height（比如 400-480）
+- 避免一页放超过 15 个节点，内容太密时考虑分页
+- 推荐尺寸参考：
+
+| 图表类型 | 建议 width | 建议 height |
+|---------|-----------|------------|
+| 流程图（5-8 节点） | 720-816 | 300-400 |
+| 时序图（3-5 参与者） | 720-816 | 320-420 |
+| 饼图 | 500-600 | 300-360 |
+| 甘特图 | 816 | 280-360 |
+| 思维导图 | 816 | 380-480 |
+
+---
+
+## 注意事项 & 已知问题
+
+### z-order（SVG 模式）
+
+whiteboard 在 XML 中的位置决定渲染层级：在 shape 前 → 在下层；在 shape 后 → 在上层。全屏装饰 whiteboard 应放在所有 shape 之前。
+
+### Mermaid CDATA 必要性
+
+Mermaid 语法包含 `[`、`>`、`-->`，不用 CDATA 直接写会破坏 XML 解析。始终使用 `<![CDATA[ ... ]]>`。
+
+---
+
+## 快速自检清单
+
+**SVG 模式——结构检查：**
+- [ ] `<svg>` 声明了 `xmlns="http://www.w3.org/2000/svg"`
+- [ ] whiteboard 的 `width`/`height` 由所有元素的最大包围盒（含 stroke 外扩）计算得出，不手动估值
+- [ ] `topLeftX + width ≤ 960`，`topLeftY + height ≤ 540`
+- [ ] 无 `<radialGradient>` / `<filter>` / `<clipPath>`
+- [ ] 文字 `y` 坐标为 baseline 位置，最小值 ≥ font-size（避免被裁切）
+
+**SVG 模式——视觉品质检查：**
+- [ ] 坐标轴、网格线、数值标注齐全，没有"裸柱子"或"裸折线"
+- [ ] 字号有层级：标题 > 数值 > 轴标签，非全部相同
+- [ ] 单一数据系列用同一颜色，多系列用不同颜色且对比充足
+- [ ] 轴标签与图表元素互不遮挡，留有足够空间
+- [ ] 坐标推导有注释（写明 originX/Y、chartW/H、数据映射公式）
+
+**Mermaid 模式：**
+- [ ] 内容包在 `<![CDATA[...]]>` 内
+- [ ] CDATA 结束符 `]]>` 不出现在 Mermaid 代码本身中
+- [ ] `topLeftX + width ≤ 960`，`topLeftY + height ≤ 540`
+- [ ] 节点数量合理（单图不超过 15-20 个节点）
+
+**通用：**
+- [ ] XML 标签全部闭合，属性引号完整
+- [ ] 如果失败，检查是否是偶发 5001000，重试一次
+
+---
+
+## 参考
+
+- [lark-slides SKILL.md](../SKILL.md)
--- a/skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md
+++ b/skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md
@@ -162,7 +162,7 @@ lark-cli slides xml_presentation.slide create --as user \
 | 元素 | 说明 |
 |------|------|
 | `<style>` | 页面样式（背景填充） |
-| `<data>` | 图形元素容器（shape、img、table、chart 等） |
+| `<data>` | 图形元素容器（shape、img、table、chart、whiteboard 等） |
 | `<note>` | 演讲者备注 |

 > [!IMPORTANT]
--- a/skills/lark-slides/references/lark-slides-xml-presentation-slide-get.md
+++ b/skills/lark-slides/references/lark-slides-xml-presentation-slide-get.md
@@ -94,7 +94,7 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 ## 注意事项

 1. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.get` 查看最新参数结构
-2. **block_id 提取**：返回 XML 里每个顶层块（shape、img、table 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：
+2. **block_id 提取**：返回 XML 里每个顶层块（shape、img、table、chart、whiteboard 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：

   ```bash
   lark-cli slides xml_presentation.slide get --as user \
--- a/skills/lark-slides/references/lark-slides-xml-presentation-slide-replace.md
+++ b/skills/lark-slides/references/lark-slides-xml-presentation-slide-replace.md
@@ -171,12 +171,13 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 ## 注意事项

 1. **parts 原子事务**：任一条失败整批回滚，不会出现"前几条成功、后几条失败"的中间态。
-2. **block_id 的获取**：`slide.get` 返回的 XML 里每个块（shape、img、table、chart 等）会带 3 位 short element ID，用这个值填 `block_id` / `insert_before_block_id`。
+2. **block_id 的获取**：`slide.get` 返回的 XML 里每个块（shape、img、table、chart、whiteboard 等）会带 3 位 short element ID，用这个值填 `block_id` / `insert_before_block_id`。
 3. **`<img>` 必须用 file_token**：不能用外链 URL——先 [`slides +media-upload`](lark-slides-media-upload.md) 拿 token。
 4. **不能字段级 patch**：要改一个块的某个属性（比如只改 `topLeftX`），得写整块新 XML 走 `block_replace`；API 不支持"只改一个字段"。
 5. **`block_replace` 要求 `replacement` 根元素带 `id="<block_id>"`**：底层 API 的硬约束，缺失会返回 3350001。推荐走 shortcut [`+replace-slide`](lark-slides-replace-slide.md)——它会自动把 `id` 注入到 `replacement` 根元素上，用户写 XML 时不用自己加。
 6. **`<shape>` 必须有 `<content/>` 子元素**：SML 2.0 schema 要求，缺失同样触发 3350001。shortcut [`+replace-slide`](lark-slides-replace-slide.md) 会自动注入 `<content/>`，直接调底层 API 需要自己加。
-7. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。
+7. **`<whiteboard>` 返回结构不含内部数据**：`slide.get` 返回的 whiteboard 块只有外层标签和位置属性，SVG / Mermaid 内容不会随 XML 一起返回。但 `block_replace` 仍然可以强行覆盖——直接写入完整新 whiteboard XML 即可。
+8. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。

 ## 相关命令

--- a/skills/lark-slides/references/planning-layer.md
+++ b/skills/lark-slides/references/planning-layer.md
@@ -185,15 +185,15 @@ Use an object for one planned asset, an array for multiple real needs, or `asset
 - `asset_type`: one of `paper_figure`, `architecture_diagram`, `icon`, `logo`, `chart`, `infographic`, `screenshot`, `flow_diagram`, or `none`.
 - `purpose`: why this asset helps the page's key message.
 - `suggested_query`: short future lookup hint only; do not execute it unless separately requested.
- `fallback_if_missing`: concrete XML-native visual plan using shapes, arrows, labels, tables, simple charts, or placeholder panels.
+- `fallback_if_missing`: concrete XML-native visual plan using shapes, labels, tables, whiteboard diagrams, or placeholder panels.

 For detailed rules and examples, read `asset-planning.md`.

 Good examples:

- `{"asset_type":"architecture_diagram","purpose":"Explain component relationships.","suggested_query":"service architecture diagram","fallback_if_missing":"Draw grouped boxes and arrows with short labels."}`
+- `{"asset_type":"architecture_diagram","purpose":"Explain component relationships.","suggested_query":"service architecture diagram","fallback_if_missing":"Draw a component diagram with grouped boxes, connector arrows, and short labels."}`
 - `{"asset_type":"logo","purpose":"Identify the customer context.","suggested_query":"customer logo","fallback_if_missing":"Use a text label in a small badge."}`
- `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Draw a simple line chart with shapes and value labels."}`
+- `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Draw a simple trend line chart with axis labels and data points."}`

 ## XML Generation Contract

--- a/skills/lark-slides/references/slides_xml_schema_definition.xml
+++ b/skills/lark-slides/references/slides_xml_schema_definition.xml
@@ -935,7 +935,7 @@
                单页幻灯片结构
                子元素:
                - style: 页面样式(背景色等), style的fill默认颜色为白色rgba(255, 255, 255, 1)
-                - data: 页面元素容器(shape/line/polyline/img/table/icon/chart/undefined)
+                - data: 页面元素容器(shape/line/polyline/img/table/icon/chart/whiteboard/undefined)
                - note: 演讲者备注
            </xs:documentation>
        </xs:annotation>
@@ -960,6 +960,7 @@
                        <xs:element ref="sml:table"/>
                        <xs:element ref="sml:icon"/>
                        <xs:element ref="sml:chart"/>
+                        <xs:element ref="sml:whiteboard"/>
                        <xs:element ref="sml:undefined"/>
                    </xs:choice>
                </xs:complexType>
@@ -1206,7 +1207,7 @@
                未定义元素, 用于处理不支持的形状类型, 当导出时遇到不支持的type数据时, 使用此元素替代
                属性说明:
                - id: 元素唯一标识符(可选)
-                - type: 原始的不支持的类型名称, 包括 video(视频), audio(音频), whiteboard(画板）
+                - type: 原始的不支持的类型名称, 包括 video(视频), audio(音频)
            </xs:documentation>
        </xs:annotation>
        <xs:complexType>
@@ -3001,4 +3002,48 @@
            <xs:attribute name="alpha" type="sml:AlphaType" use="optional" default="1"/>
        </xs:complexType>
    </xs:element>
+
+    <!-- 画板元素 -->
+    <xs:element name="whiteboard">
+      <xs:annotation>
+        <xs:documentation>
+          画板元素, 用于在幻灯片中嵌入 Mermaid 或 SVG 绘制内容。
+
+          属性说明:
+          - id: 画板唯一标识符(可选)
+          - topLeftX/topLeftY: 左上角坐标, 必须
+          - width/height: 宽高尺寸, 必须
+          - flipX/flipY: 水平/垂直翻转
+          - alpha: 不透明度[0,1]
+
+          子元素(mermaid 与 svg 二选一):
+          - mermaid: Mermaid 源码文本, 可使用 CDATA 包裹
+            适用场景: 流程图、时序图、思维导图、类图、甘特图、饼图等结构化图表
+            特点: 用简短的文本声明描述图表逻辑, 由渲染引擎自动布局, 无需手动计算坐标
+            示例: &lt;mermaid&gt;&lt;![CDATA[flowchart TD\n  A[开始] --&gt; B[结束]]]&gt;&lt;/mermaid&gt;
+          - svg: SVG 内容
+            适用场景: 需要精确控制坐标、配色、路径的自定义图形
+            特点: 像素级精确定位，支持 rect/circle/path/text/polygon/g/linearGradient 等元素；radialGradient/filter/clipPath/mask/pattern 不支持，需手动计算所有坐标
+            示例: &lt;svg xmlns="http://www.w3.org/2000/svg"&gt;...&lt;/svg&gt;（xmlns 必填；width/height/viewBox 不影响渲染，仅百分比属性值场景需声明 viewBox）
+          - border: 边框样式, 可选, 无border标签代表无边框, 空border标签代表使用默认样式
+        </xs:documentation>
+      </xs:annotation>
+      <xs:complexType>
+        <xs:sequence>
+          <xs:choice>
+            <xs:element name="mermaid" type="xs:string" />
+            <xs:any namespace="http://www.w3.org/2000/svg" processContents="skip"/>
+          </xs:choice>
+          <xs:element name="border" type="sml:BorderType" minOccurs="0"/>
+        </xs:sequence>
+        <xs:attribute name="id" type="xs:string" use="optional"/>
+        <xs:attribute name="topLeftX" type="sml:XType" use="required"/>
+        <xs:attribute name="topLeftY" type="sml:YType" use="required"/>
+        <xs:attribute name="width" type="sml:PositiveSize" use="required"/>
+        <xs:attribute name="height" type="sml:PositiveSize" use="required"/>
+        <xs:attribute name="flipX" type="xs:boolean" use="optional" default="false"/>
+        <xs:attribute name="flipY" type="xs:boolean" use="optional" default="false"/>
+        <xs:attribute name="alpha" type="sml:AlphaType" use="optional" default="1"/>
+      </xs:complexType>
+    </xs:element>
 </xs:schema>
--- a/skills/lark-slides/references/validation-checklist.md
+++ b/skills/lark-slides/references/validation-checklist.md
@@ -76,6 +76,14 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - 大量形状坐标完全相同，导致主体内容重叠。
 - 渐变背景回退成空白或白底，导致文字不可读。

+## Whiteboard Elements
+
+`slide.get` 回读 XML 时，`<whiteboard>` 块只返回位置属性（`topLeftX`、`topLeftY`、`width`、`height`），SVG / Mermaid 内容**不随 XML 返回**。
+
+- whiteboard 验证只能核对坐标是否越界：`topLeftX + width ≤ 960`，`topLeftY + height ≤ 540`。
+- SVG 和 Mermaid 内容的正确性无法通过回读 XML 验证，需要人工视觉验收。
+- 不要在验证记录中声称 whiteboard 内容已验证，除非用户确认了视觉效果。
+
 ## Layout And Overflow Risk

 优先修复这些明显风险：
--- a/skills/lark-slides/references/visual-planning.md
+++ b/skills/lark-slides/references/visual-planning.md
@@ -168,6 +168,8 @@ Text:

 Purpose: explain components, dependencies, or system flow.

+Implementation: prefer `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` only as fallback.
+
 Geometry:
 - Main visual area should be a diagram, not prose.
 - Use grouped boxes, lanes, arrows or lines, and short labels.
@@ -182,6 +184,8 @@ Text:

 Purpose: show operational steps, workflow, or cause-effect path.

+Implementation: prefer `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` only as fallback.
+
 Geometry:
 - Use numbered steps connected by arrows or lines.
 - 3-5 steps is ideal for one slide. If there are more, group them into phases.
--- a/skills/lark-slides/references/xml-schema-quick-ref.md
+++ b/skills/lark-slides/references/xml-schema-quick-ref.md
@@ -44,7 +44,7 @@

 **子元素：**
 - `<style>?` - 页面样式，目前可放 `<fill>`
- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`undefined`
+- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`whiteboard`、`undefined`
 - `<note>?` - 演讲者备注，内部可放 `<content>`

 ## theme 与文本类型
@@ -142,6 +142,34 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 <icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="120" width="32" height="32"/>
 ```

+### whiteboard
+
+```xml
+<!-- SVG 模式：数据图表、装饰元素 -->
+<whiteboard topLeftX="580" topLeftY="120" width="340" height="280">
+  <svg xmlns="http://www.w3.org/2000/svg">
+    <rect x="60" y="80" width="40" height="140" rx="3" fill="rgba(59,130,246,0.85)"/>
+    <text x="80" y="238" text-anchor="middle" font-size="11" fill="rgba(100,116,139,1)">ABC</text>
+  </svg>
+</whiteboard>
+
+<!-- Mermaid 模式：流程图、时序图等结构化图表 -->
+<whiteboard topLeftX="72" topLeftY="100" width="816" height="340">
+  <mermaid>
+    <![CDATA[
+      flowchart LR
+          A[开始] --> B{判断}
+          B -- 是 --> C[执行]
+          B -- 否 --> D[结束]
+    ]]>
+  </mermaid>
+</whiteboard>
+```
+
+SVG 模式：`<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`，内容大小由子元素包围盒决定；`width`/`height`/`viewBox` 不影响渲染，仅当元素使用百分比属性值时需声明 `viewBox`。\
+Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->` 等字符破坏 XML 解析。\
+详细用法见 [lark-slides-whiteboard.md](lark-slides-whiteboard.md)。
+
 ## 颜色与样式

 ### fill