@amaster.ai/pi-lark 0.1.5 → 0.1.7

package/skills/lark-slides/references/examples.md

@@ -1,261 +0,0 @@
-# 完整操作示例
-
-本文档提供与 CLI schema 一致的调用示例，XML 内容均遵循 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
-
-> **重要**：创建 PPT 请优先使用 `slides +create`；实际页面内容请使用 `xml_presentation.slide.create` 逐页添加。
-
-## 目录
-
-- [示例 1: 使用 Shortcut 创建空白演示文稿](#示例-1-使用-shortcut-创建空白演示文稿)
-- [示例 2: 创建后添加第一页](#示例-2-创建后添加第一页)
-- [示例 3: 读取 XML 内容](#示例-3-读取-xml-内容)
-- [示例 4: 在指定页面前插入新幻灯片](#示例-4-在指定页面前插入新幻灯片)
-- [示例 5: 删除幻灯片](#示例-5-删除幻灯片)
-- [示例 6: 从文件读取 XML 后添加页面](#示例-6-从文件读取-xml-后添加页面)
-- [示例 7: +replace-slide + block_insert 给已有页加图](#示例-7-replace-slide--block_insert-给已有页加图)
-- [示例 8: +replace-slide + block_replace 替换一个块](#示例-8-replace-slide--block_replace-替换一个块)
-
-## 示例 1: 使用 Shortcut 创建空白演示文稿
-
-```bash
-lark-cli slides +create --title "项目汇报"
-```
-
-预期返回结构：
-
-```json
-{
-  "data": {
-    "xml_presentation_id": "slides_example_presentation_id",
-    "title": "项目汇报",
-    "revision_id": 1
-  }
-}
-```
-
-## 示例 2: 创建后添加第一页
-
-```bash
-PRESENTATION_ID=$(lark-cli slides +create --title "季度复盘" | jq -r '.data.xml_presentation_id')
-
-lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data '{
-  "slide": {
-    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style><fill><fillColor color=\"rgb(245, 245, 245)\"/></fill></style><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"72\" width=\"760\" height=\"90\"><content textType=\"title\"><p>2024 Q3 季度复盘</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"190\" width=\"520\" height=\"220\"><content textType=\"body\"><p>关键结论</p><ul><li><p>收入增长 30%</p></li><li><p>重点项目全部上线</p></li><li><p>用户满意度持续提升</p></li></ul></content></shape><shape type=\"rect\" topLeftX=\"660\" topLeftY=\"180\" width=\"180\" height=\"140\"><fill><fillColor color=\"rgba(100, 149, 237, 0.25)\"/></fill><border color=\"rgb(100, 149, 237)\" width=\"2\"/></shape></data><note><content textType=\"body\"><p>讲述时先给结论，再补充数据。</p></content></note></slide>"
-  }
-}'
-```
-
-## 示例 3: 读取 XML 内容
-
-```bash
-lark-cli slides xml_presentations get --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id"
-}'
-```
-
-提取 XML 内容：
-
-```bash
-lark-cli slides xml_presentations get --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id"
-}' | jq -r '.data.xml_presentation.content'
-```
-
-预期返回结构：
-
-```json
-{
-  "code": 0,
-  "data": {
-    "xml_presentation": {
-      "presentation_id": "slides_example_presentation_id",
-      "revision_id": 3,
-      "content": "<presentation xmlns=\"http://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
-    }
-  },
-  "msg": "success"
-}
-```
-
-## 示例 4: 在指定页面前插入新幻灯片
-
-```bash
-lark-cli slides xml_presentation.slide create --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id"
-}' --data '{
-  "slide": {
-    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新增页面</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"180\"><content textType=\"body\"><p>这是新增页面的正文。</p></content></shape></data></slide>"
-  },
-  "before_slide_id": "sld_before_target"
-}'
-```
-
-预期返回结构：
-
-```json
-{
-  "code": 0,
-  "data": {
-    "slide_id": "slide_example_id",
-    "revision_id": 100
-  },
-  "msg": "success"
-}
-```
-
-## 示例 5: 删除幻灯片
-
-```bash
-lark-cli slides xml_presentation.slide delete --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id"
-}'
-```
-
-预期返回结构：
-
-```json
-{
-  "code": 0,
-  "data": {
-    "revision_id": 101
-  },
-  "msg": "success"
-}
-```
-
-## 示例 6: 从文件读取 XML 后添加页面
-
-先准备 `slide.xml`：
-
-```xml
-<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <data>
-    <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
-      <content textType="title">
-        <p>从文件加载</p>
-      </content>
-    </shape>
-  </data>
-</slide>
-```
-
-先创建演示文稿：
-
-```bash
-PRESENTATION_ID=$(lark-cli slides +create --title "从文件添加页面" | jq -r '.data.xml_presentation_id')
-```
-
-再用 `jq` 组装请求体，从文件添加页面：
-
-```bash
-lark-cli slides xml_presentation.slide create --as user \
-  --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" \
-  --data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')"
-```
-
-## 示例 7: +replace-slide + block_insert 给已有页加图
-
-只想在已有页上加一张图、不动其他元素——走 shortcut `+replace-slide`，`block_insert` 追加到页末（或用 `insert_before_block_id` 指定位置）。
-
-```bash
-PID="slides_example_presentation_id"
-SID="slide_example_id"
-
-# 1. 上传图片拿 file_token
-TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PID" --as user \
-  | jq -r '.data.file_token')
-
-# 2. block_insert 到页面末尾（省略 insert_before_block_id）
-# 注：<img .../> 是自闭合标签，CLI 不会展开（只有 <shape/> 会被补 <content/>）
-lark-cli slides +replace-slide --as user \
-  --presentation "$PID" --slide-id "$SID" \
-  --parts "$(jq -n --arg token "$TOKEN" \
-    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")}]')"
-```
-
-预期返回：
-
-```json
-{
-  "ok": true,
-  "data": {
-    "xml_presentation_id": "slides_example_presentation_id",
-    "slide_id": "slide_example_id",
-    "parts_count": 1,
-    "revision_id": 102
-  }
-}
-```
-
-## 示例 8: +replace-slide + block_replace 替换一个块
-
-已知某块的 3 位 short element ID（从 `slide.get` 返回 XML 里读），整块换掉。`replacement` 根元素的 `id` 会由 CLI 自动注入为 `block_id`，无需手写；若写了 `<shape/>` 自闭合形式，CLI 也会自动补 `<content/>`。
-
-```bash
-lark-cli slides +replace-slide --as user \
-  --presentation slides_example_presentation_id \
-  --slide-id slide_example_id \
-  --parts '[
-    {
-      "action": "block_replace",
-      "block_id": "bab",
-      "replacement": "<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"
-    }
-  ]'
-# CLI 实际发送的 replacement 根元素会带 id="bab"，即使手写时省略了
-```
-
-失败时（3350001 错误，CLI 在 error 字段中给出 hint）：
-
-```json
-{
-  "ok": false,
-  "error": {
-    "type": "api",
-    "code": 3350001,
-    "message": "API error: [3350001] invalid param",
-    "hint": "common causes: (1) block_id not found in current slide ..."
-  }
-}
-```
-
-整批作为原子事务，任一 part 失败则整批不生效；按 `failed_part_index` 定位修正后重发。
-
-## 常见处理技巧
-
-### 获取最新 revision_id
-
-```bash
-lark-cli slides xml_presentations get --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id"
-}' | jq '.data.xml_presentation.revision_id'
-```
-
-### 批量插入多页
-
-```bash
-#!/bin/bash
-
-PRESENTATION_ID="slides_example_presentation_id"
-
-slides=(
-  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 1</p></content></shape></data></slide>'
-  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 2</p></content></shape></data></slide>'
-)
-
-for slide_xml in "${slides[@]}"; do
-  payload=$(jq -n --arg content "$slide_xml" '{slide:{content:$content}}')
-  lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data "$payload"
-done
-```
-
-### 本地校验 XML 基本语法
-
-```bash
-xmllint --noout presentation.xml
-```
-
-### 真实示例
-
-- [slides_demo.xml](slides_demo.xml) 提供了更完整的页面示例，包含 `theme`、渐变填充、图片、图标和备注内容。

package/skills/lark-slides/references/lark-slides-whiteboard.md

@@ -1,330 +0,0 @@
-# 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)