From 894125f9118d830f219e0b560091a97fd53f9001 Mon Sep 17 00:00:00 2001 From: "huangwenbo.wb" Date: Tue, 19 May 2026 16:12:01 +0800 Subject: [PATCH 1/6] feat(slides): add whiteboard element support and reference documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add lark-slides-whiteboard.md covering SVG and Mermaid modes, routing rules, layout examples, known issues, and self-check checklist - Register 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 syntax examples - Update slide create/get/replace references to include whiteboard as a valid 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 --- skills/lark-slides/SKILL.md | 4 +- .../lark-slides/references/asset-planning.md | 6 +- .../references/lark-slides-replace-slide.md | 3 +- .../references/lark-slides-whiteboard.md | 328 ++++++++++++++++++ ...rk-slides-xml-presentation-slide-create.md | 2 +- .../lark-slides-xml-presentation-slide-get.md | 2 +- ...k-slides-xml-presentation-slide-replace.md | 5 +- .../lark-slides/references/planning-layer.md | 6 +- .../slides_xml_schema_definition.xml | 49 ++- .../references/xml-schema-quick-ref.md | 30 +- 10 files changed, 420 insertions(+), 15 deletions(-) create mode 100644 skills/lark-slides/references/lark-slides-whiteboard.md diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 3adc795ec..f3d7d43f6 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -19,6 +19,7 @@ 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 中绘制图表、流程图、时序图、架构图或装饰图案 | 用 `` 元素；SVG 或 Mermaid 的选择取决于图表类型和当前模型身份，详见参考文档 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) | | 用户提到模板、主题、版式 | 先检索模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` | | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` | @@ -80,6 +81,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 +185,7 @@ lark-cli slides xml_presentation.slide create \ --data "$(jq -n --arg content ' - 在这里放置 shape、line、table、chart 等元素 + 在这里放置 shape、line、table、chart、whiteboard 等元素 ' '{slide:{content:$content}}')" diff --git a/skills/lark-slides/references/asset-planning.md b/skills/lark-slides/references/asset-planning.md index d5af78ece..05e449197 100644 --- a/skills/lark-slides/references/asset-planning.md +++ b/skills/lark-slides/references/asset-planning.md @@ -7,7 +7,7 @@ ## 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." } ``` @@ -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. diff --git a/skills/lark-slides/references/lark-slides-replace-slide.md b/skills/lark-slides/references/lark-slides-replace-slide.md index c5220e7e7..56dc83ab4 100644 --- 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 \ | `` | 表格 | 整表替换会**重建内部 td id**，旧 td block_id 立即失效 | | `
` | 单元格局部替换 | 只能 `block_replace`，不能 `block_insert`；`block_id` 必须是最新 `slide.get` 拿到的 td id | | `` | 图表（line/bar/column/pie/area/radar/combo） | 必须嵌 `` + `` + `//` | +| `` | 画板（SVG 或 Mermaid） | 内嵌 `` 或 ``；`slide.get` 返回结构不含内部数据，但可直接写完整新 XML 做 `block_replace` 覆盖；详见 [`lark-slides-whiteboard.md`](lark-slides-whiteboard.md) | **不可作为根元素**： -- `` 元素 | + +--- + +### 坐标计算 + +含数据映射的图表（柱状图、折线图等），坐标值用脚本计算后再填入 SVG，**禁止直接拍像素**。 + +```js +// node calc_coords.js ← 运行后把输出粘贴到 SVG 注释，再写元素 +const W = 360, H = 260 +// 自行决定图表区域起点和尺寸（为轴标签、标题留出空间） +const originX = 50, originY = 216 // 图表左下角 +const cW = 290, cH = 184 // 图表宽高 + +const data = [120, 160, 90], yMax = 200 +const svgY = v => originY - (v / yMax) * cH +const barW = Math.floor(cW / data.length * 0.62) + +data.forEach((v, i) => { + const cx = Math.round(originX + (i + 0.5) * cW / data.length) + const y = Math.round(svgY(v)) + const h = Math.round(svgY(0) - y) + console.log(`bar-${i}(${v}): x=${cx - barW/2 | 0} y=${y} w=${barW} h=${h}`) +}) +``` + +折线图点坐标：`svgX(i) = originX + i/(n-1)*cW`，`svgY(v) = originY - (v-yMin)/(yMax-yMin)*cH`。 + +--- + +## 模式二：Mermaid + +### 语法 + +```xml + + + B[编写每页 slide XML] + B --> C[通过 jq 生成 slides JSON] + C --> D[执行 slides +create] + D --> E[读取 xml_presentation_id] + E --> F[回读并验证创建结果] + ]]> + + +``` + +**关键点：** +- 内容用 `` 包裹——Mermaid 语法里的 `[`、`>`、`-->` 是 XML 特殊字符，CDATA 避免转义问题 +- whiteboard 只需 `topLeftX`、`topLeftY`、`width`、`height`，无需 SVG 相关属性 +- `` 内不加 `xmlns` + +### 支持的 Mermaid 图表类型 + +| 类型 | 关键字 | 适用场景 | +|------|--------|---------| +| 流程图 | `flowchart TD` / `flowchart LR` | 业务流程、决策树、工作流 | +| 时序图 | `sequenceDiagram` | 系统交互、API 调用链 | +| 甘特图 | `gantt` | 项目计划、里程碑 | +| 饼图 | `pie` | 占比数据 | +| 类图 | `classDiagram` | 对象关系、架构设计 | +| ER 图 | `erDiagram` | 数据库结构 | +| 状态图 | `stateDiagram-v2` | 状态机、生命周期 | +| 思维导图 | `mindmap` | 主题梳理、知识架构 | +| 用户旅程 | `journey` | 用户体验路径 | + +### 常用 Mermaid 示例 + +**从左到右的流程图** +```mermaid +flowchart LR + A[开始] --> B{判断条件} + B -- 是 --> C[执行操作] + B -- 否 --> D[跳过] + C --> E[结束] + D --> E +``` + +**时序图** +```mermaid +sequenceDiagram + participant 用户 + participant 前端 + participant 后端 + 用户->>前端: 提交表单 + 前端->>后端: POST /api/submit + 后端-->>前端: 返回结果 + 前端-->>用户: 显示成功 +``` + +**饼图** +```mermaid +pie title 用户来源分布 + "直接访问" : 42 + "搜索引擎" : 28 + "社交媒体" : 18 + "其他" : 12 +``` + +**甘特图** +```mermaid +gantt + title 项目计划 + dateFormat YYYY-MM-DD + section 设计 + 需求分析 :a1, 2024-01-01, 7d + UI设计 :a2, after a1, 10d + section 开发 + 前端开发 :b1, after a2, 14d + 后端开发 :b2, after a2, 14d +``` + +**思维导图** +```mermaid +mindmap + root((核心主题)) + 子主题A + 细节1 + 细节2 + 子主题B + 细节3 + 子主题C +``` + +### 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 | + +--- + +## whiteboard 公共属性 + +| 属性 | 必需 | 说明 | +|------|------|------| +| `topLeftX` | 是 | 左上角 X 坐标（slide 坐标系，slide 默认宽 960） | +| `topLeftY` | 是 | 左上角 Y 坐标（slide 坐标系，slide 默认高 540） | +| `width` | 是 | 画板宽度（像素） | +| `height` | 是 | 画板高度（像素） | + +> SVG 模式需在 `` 上设置 `width`、`height`、`viewBox`、`xmlns`；`width`/`height` 通常与 whiteboard 相同，但可以不同——`viewBox` 控制内容坐标系，SVG 会自动缩放以适应 whiteboard 区域。Mermaid 模式不需要额外属性。 + +--- + +## 注意事项 & 已知问题 + +### z-order（SVG 模式） + +whiteboard 在 XML 中的位置决定渲染层级：在 shape 前 → 在下层；在 shape 后 → 在上层。全屏装饰 whiteboard 应放在所有 shape 之前。 + +### Mermaid CDATA 必要性 + +Mermaid 语法包含 `[`、`>`、`-->`，不用 CDATA 直接写会破坏 XML 解析。始终使用 ` ... `。 + +### 坐标系独立 + +SVG 内的坐标相对于 whiteboard 自身左上角（0,0），不是 slide 的坐标系。 + +--- + +## 快速自检清单 + +**SVG 模式——结构检查：** +- [ ] `` 设置了 `width`、`height`、`viewBox`、`xmlns` +- [ ] `topLeftX + width ≤ 960`，`topLeftY + height ≤ 540` +- [ ] 所有 SVG 元素坐标 + 尺寸在 viewBox 范围内（无溢出） +- [ ] 所有颜色用 `rgba()` 格式，无 `` / `` / `` +- [ ] 文字 `y` 坐标为 baseline 位置，最小值 ≥ font-size（避免被裁切） + +**SVG 模式——视觉品质检查：** +- [ ] 坐标轴、网格线、数值标注齐全，没有"裸柱子"或"裸折线" +- [ ] 字号有层级：标题 > 数值 > 轴标签，非全部相同 +- [ ] 单一数据系列用同一颜色，多系列用不同颜色且对比充足 +- [ ] 图表元素不超出 viewBox 边界，轴标签有足够空间 +- [ ] 坐标推导有注释（写明 originX/Y、chartW/H、数据映射公式） + +**Mermaid 模式：** +- [ ] 内容包在 `...` 内 +- [ ] CDATA 结束符 `]]>` 不出现在 Mermaid 代码本身中 +- [ ] `topLeftX + width ≤ 960`，`topLeftY + height ≤ 540` +- [ ] 节点数量合理（单图不超过 15-20 个节点） + +**通用：** +- [ ] XML 标签全部闭合，属性引号完整 +- [ ] 如果失败，检查是否是偶发 5001000，重试一次 diff --git a/skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md b/skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md index f0033ffb5..d636b0aa9 100644 --- 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 \ | 元素 | 说明 | |------|------| | `` 必须用 file_token**：不能用外链 URL——先 [`slides +media-upload`](lark-slides-media-upload.md) 拿 token。 4. **不能字段级 patch**：要改一个块的某个属性（比如只改 `topLeftX`），得写整块新 XML 走 `block_replace`；API 不支持"只改一个字段"。 5. **`block_replace` 要求 `replacement` 根元素带 `id=""`**：底层 API 的硬约束，缺失会返回 3350001。推荐走 shortcut [`+replace-slide`](lark-slides-replace-slide.md)——它会自动把 `id` 注入到 `replacement` 根元素上，用户写 XML 时不用自己加。 6. **`` 必须有 `` 子元素**：SML 2.0 schema 要求，缺失同样触发 3350001。shortcut [`+replace-slide`](lark-slides-replace-slide.md) 会自动注入 ``，直接调底层 API 需要自己加。 -7. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。 +7. **`` 返回结构不含内部数据**：`slide.get` 返回的 whiteboard 块只有外层标签和位置属性，SVG / Mermaid 内容不会随 XML 一起返回。但 `block_replace` 仍然可以强行覆盖——直接写入完整新 whiteboard XML 即可。 +8. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。 ## 相关命令 diff --git a/skills/lark-slides/references/planning-layer.md b/skills/lark-slides/references/planning-layer.md index 699f5a5c1..51731fa03 100644 --- 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 diff --git a/skills/lark-slides/references/slides_xml_schema_definition.xml b/skills/lark-slides/references/slides_xml_schema_definition.xml index 3340c4438..127f14fff 100644 --- 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: 演讲者备注 @@ -960,6 +960,7 @@ + @@ -1206,7 +1207,7 @@ 未定义元素, 用于处理不支持的形状类型, 当导出时遇到不支持的type数据时, 使用此元素替代 属性说明: - id: 元素唯一标识符(可选) - - type: 原始的不支持的类型名称, 包括 video(视频), audio(音频), whiteboard(画板） + - type: 原始的不支持的类型名称, 包括 video(视频), audio(音频) @@ -3001,4 +3002,48 @@ + + + + + + 画板元素, 用于在幻灯片中嵌入 Mermaid 或 SVG 绘制内容。 + + 属性说明: + - id: 画板唯一标识符(可选) + - topLeftX/topLeftY: 左上角坐标, 必须 + - width/height: 宽高尺寸, 必须 + - flipX/flipY: 水平/垂直翻转 + - alpha: 不透明度[0,1] + + 子元素(mermaid 与 svg 二选一): + - mermaid: Mermaid 源码文本, 可使用 CDATA 包裹 + 适用场景: 流程图、时序图、思维导图、类图、甘特图、饼图等结构化图表 + 特点: 用简短的文本声明描述图表逻辑, 由渲染引擎自动布局, 无需手动计算坐标 + 示例: <mermaid><![CDATA[flowchart TD\n A[开始] --> B[结束]]]></mermaid> + - svg: SVG 命名空间(http://www.w3.org/2000/svg)下的完整 SVG 内容 + 适用场景: 需要精确控制布局、样式、渐变、动画等视觉细节的自定义图形 + 特点: 像素级精确定位, 支持渐变/阴影/路径/滤镜等丰富视觉效果, 但需手动计算所有坐标 + 示例: <svg width="960" height="540" viewBox="0 0 960 540" xmlns="http://www.w3.org/2000/svg">...</svg> + - border: 边框样式, 可选, 无border标签代表无边框, 空border标签代表使用默认样式 + + + + + + + + + + + + + + + + + + + + diff --git a/skills/lark-slides/references/xml-schema-quick-ref.md b/skills/lark-slides/references/xml-schema-quick-ref.md index d7fab4fbd..7e3be2448 100644 --- a/skills/lark-slides/references/xml-schema-quick-ref.md +++ b/skills/lark-slides/references/xml-schema-quick-ref.md @@ -44,7 +44,7 @@ **子元素：** - `