chore(slides): update lark-slides skill to 0715 snapshot (#1933)

* chore(slides): update lark-slides skill to 0715 snapshot

* fix: 补回lark-share 内容

* fix: 补回一些内容

* fix: 移除豆包特有工具

* fix: 移除多余的xml版本头

* fix: 补回示例xml头

* fix: remove xml-format-guide

skills/lark-slides/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-slides
 version: 1.0.0
-description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。"
+description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard）、上传或下载普通文件（走 lark-drive）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -10,25 +10,82 @@ metadata:
 
 # slides (v1)
 
-**CRITICAL — 全局硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。**
+> 本技能文档较长，务必使用 Read 工具阅读两次，必须阅读完整全文。
 
-**CRITICAL — 图片至关重要：必须有意识的主动多用图片！素材图使用生图工具和搜图工具，缺图时用生图工具生成配图补足；背景图必须使用生图工具，且生图指令中必须明确要求不要出现任何文字。**
+## 权威经验
 
-**CRITICAL — 防文本溢出：所有承载突出信息和密集文字的 `<content>` 必须设置 `autoFit="normal-auto-fit"`，字号会在框内自动缩排以防溢出。**
+**权威经验是全局硬约束和高频易错点，必须牢记并严格遵守。**
+
+- 你有充足的时间完成这个 PPT，质量永远比速度重要。
+- PPT 的尺寸是 960x540，必须严格确保主体内容在页面边界内。
+- !!!禁止交付无图产物!!! 必须使用大量图片增强视觉效果!!! 禁止重复使用同一张图!!!
+- 封面页的主视觉必须是 `<img>`（来自生图工具或搜图工具），不要使用 `<shape>` 或 `<icon>` 拼出封面视觉。
+- 禁止用 `<shape>` 和 `<line>` 拟形具体物项，必须使用生图工具生成的 `<img>`。
+- 禁止在 `headline` 或 `title` 下方放置用于分隔或装饰的 `rect` 或 `<line>`。
+- 禁止在任何页面内部使用无意义的装饰线条或色块条带，页面任何一边都不要使用贴边窄条。
+- 生图工具的指令参数必须以“不要出现任何文字和颜色色号”结尾，避免生成的图片上出现干扰文字。
+- 禁止使用 emoji 图标，任何位置都不能出现。
+- 字号必须显式设置 `<content>` 的 `fontSize` 属性，不要依赖 `textType` 的默认字号兜底，这些兜底值明显偏大。
+- 大数字、字号大或字数多的 `<content>` 必须设置 `wrap="true" autoFit="normal-auto-fit"` 属性自动换行和缩排，避免文字溢出。
+- 文字颜色必须用 `<content>` 的 `color` 属性而不是 `fontColor` 属性。
+- 文字行间距必须设置 `<content>` 的 `lineSpacing="multiple:xx"` 或 `lineSpacing="fixed:xx"` 而不是 `lineSpacing="xx"`。
+- 图片必须用 `<img>` 而不是 `<image>`。
+- IconPark 图标必须填充颜色（设置 `<fill><fillColor color="rgba(R,G,B,A)"/></fill>`）并和背景有足够对比。
+- 绘制图表时原生图表（柱状、条形、折线、面积、饼（环）、雷达、组合图）用 `<chart>`，其他（漏斗图、金字塔图、象限图、矩阵图等）用 `<shape>` + `<line>` 模拟。
+- 隐藏 `<chart>` 的图例只能通过不写或删除 `<chartLegend>` 实现，`<chartLegend>` 不支持 `position="none"`。
+- 表格优先用 `rect` 和 `text` 模拟，其他用 `<table>`，没有 `<shape type="table">`。
+- 必须设置 `<table>` 的 `width` 和 `height` 固定表格大小，同时设置需要保留列宽或行高的 `<col>` 的 `width` 和 `<tr>` 的 `height`，其余自动分配。
+- `<td>` 直接子元素只有 `<fill>`（背景）、`<content>`（文字）和边框配置（一般不用），不能嵌套 `<shape>`、`<img>`、`<icon>`。
+- `<shape type="rect">` 只是形状不是容器，`<icon>`、`<img>`、`<shape type="text">` 和其他 `<shape>` 必须与它平级靠坐标叠放。
+- 填充渐变颜色必须用 `<fill><fillColor color="linear-gradient(135deg, rgba(R,G,B,A) 0%, rgba(R,G,B,A) 100%)"/></fill>`。
+- 编辑页面前必须阅读 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
+- 绘制图表前必须阅读 [`slides_chart_demo.xml`](references/slides_chart_demo.xml)。
+- 当用户要求无损复述历史上下文时，必须无损复述以上权威经验、必读的技能文档（需要重新阅读）和易错元素语法（尤其是 `<table>` 和 `<chart>`）。
+
+## 豆包设计原则
+
+适用范围：
+
+- 普通内容页的设计必须以豆包设计原则为最高准则，除非用户要求使用模板或直接提供设计方案。
+- 不适用于 `title-cover`、`section-divider`、`conclusion`、`quote-highlight` 和 `big-number`。
+
+核心要求：
+
+- 必须采用信息密度极高的图文卡片布局，追求充实饱满、图文丰富、可逐行细读的版面，宁可密而满，不要空而疏。
+- **!!!信息密度极高!!! 图多!!! 卡多!!! 字多!!!**
+
+排版布局：
+
+- 卡片布局：卡片按多行网格铺满页面，版面对称、均衡、不留白。网格数、图文比例按内容变化，避免每页雷同。使用更多卡片做细分承载，避免在单张卡片里堆砌大量文字（例如 8 张 50 字卡片优于 2 张 200 字卡片），多个要点必须拆分为多张子卡片。
+- 卡片样式：方角卡片 + 半透明填充 + 无边框 + 卡片贴边窄条（可选）；所有卡片必须使用相同的配色方案（少量需强调的卡片除外），禁止同页出现彩虹卡片（卡片颜色超过 3 种）。
+- 卡片结构：视觉锚点（关键词、编号或 IconPark 图标）+ 标题 + 内容（包括文字、图片、图表、子卡片）。
+- 文字卡片：多数页面必须满足 6-8 张文字卡片、200-400 文字数量，字数不足时必须扩写成长句或段落，文字卡片不要留白，必须充实饱满。文字卡片不是短标签，而是“标题 + 完整说明”，像浓缩的分析文稿。文字内容不得不用列表、分栏、关键词或短句时，必须保证层次清晰，更建议拆分为多张子卡片。
+- 图片卡片：多数页面必须满足 1-3 张图片卡片，缺少图片时必须用生图工具补充配图，图片卡片与文字卡片组成网格，确保图文丰富。
+- 图表卡片：数据信息不要在文字卡片中罗列，必须在图表卡片中可视化（包括表格、图表、时间线、流程图等），图表卡片与其他卡片组成网格，展现数据驱动。
+- 间距要求：所有边距都要左右对称，页面和内部内容的边距至少 40px（内容不要贴边），卡片和内部文字的边距至少 5px（文字不要贴边），卡片之间保持 20-40px 的间距。
+- 文字对齐：正文默认左对齐，只在封面、结尾或大号数字场景中使用居中；表格里的文字左对齐、数字右对齐、仅关键词或短句时居中对齐。
+
+视觉风格：
+
+- 美学：干净、明亮、清爽但信息饱满；靠卡片和对齐网格在高密度下维持秩序感；同排卡片文字数量应相近以保持观感整齐。
+- 字体：全篇以无衬线体（思源黑体）为主，封面或关键强调可少量使用衬线体。
+- 字号：标题 28-36pt、正文 12-14pt、注释 10-12pt，常规关键指标 16-32pt、核心指标用 36-52pt 数字，下面配 10-14pt 标签与简短解读，需要容纳更多文字时允许使用更小的字号。
+- 图标：内嵌 IconPark 图标（可用关键词或编号替代）作为视觉锚点，让高密度文字也有图形节奏，而不是成片纯文字块。
+- 配色：克制颜色数量，确保所有页面都只使用同样的 1 个背景色（偏好浅米白）、1 个主色、1 个强调色和 1 个辅助色；偏好莫兰迪配色，禁止彩虹配色（比如蓝配橙）。
 
 ## Quick Reference
 
 | 用户需求 | 优先动作 | 关键文档 / 命令 |
 |----------|----------|-----------------|
 | 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
-| 从模板创建或编辑已有本地 PPTX | 导入 PPTX 为 Slides | `lark-slides-pptx-template-workflows.md` |
+| 用户要求使用模板 | 将模板导入为 Slides 再编辑 | `lark-slides-pptx-template-workflows.md` |
 | 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
-| 读取或分析已有 PPT | 解析 slides/wiki token，用 shortcut 回读全文 XML 或读取单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`、`xml_presentation.slide.get` |
+| 读取或分析已有 PPT | 解析 slides/wiki token，用 shortcut 回读全文 XML 或读取单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`、`xml_presentation.slide.get`、`lark-slides-xml-presentations-get.md` |
 | 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面，一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.md` |
-| 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 |
-| 绘制图表 | 原生图表用 `<chart>`，其他用 `<shape>` + `<line>`，只有复杂 Mermaid、SVG 用 `<whiteboard>` | `xml-schema-quick-ref.md`、`slides_chart_demo.xml` |
+| 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`、`lark-slides-media-upload.md`，或 `+create --slides` 的 `@./path` 占位符 |
+| 绘制图表 | 原生图表（柱状、条形、折线、面积、饼（环）、雷达、组合图）用 `<chart>`，其他（漏斗图、金字塔图、象限图、矩阵图等）用 `<shape>` + `<line>` 模拟 | `xml-schema-quick-ref.md`、`slides_chart_demo.xml` |
 | 绘制表格 | 优先用 `rect` 和 `text` 模拟，其他用 `<table>` | `xml-schema-quick-ref.md` |
-| 使用图标 | 禁止盲猜 `iconType`，必须先检索 IconPark，再写 `<icon iconType="...">`，图标必须填充颜色并和背景有足够对比，禁止使用 emoji 图标 | `iconpark_tool.py search → resolve`、`iconpark.md` |
+| 使用图标 | 禁止盲猜 iconType，必须先检索 IconPark，再写 `<icon iconType="...">`，图标必须填充颜色并和背景有足够对比，禁止使用 emoji 图标 | `iconpark_tool.py search → resolve`、`iconpark.md` |
 | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。**
@@ -39,16 +96,18 @@ metadata:
 
 **CRITICAL — 新建演示文稿或大幅改写页面时，生成 XML 前 MUST 读取 [visual-planning.md](references/visual-planning.md)，确保 `layout_type`、`visual_focus`、`text_density` 实际改变页面几何、主视觉和文本量。**
 
-**CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)。**
+**CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。**
 
 **CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create --slides`、`xml_presentation.slide create` 或 `slides +replace-pages` 之前，MUST 先把待提交 XML 保存到本地文件并运行 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)；`summary.error_count` 必须为 0 才能调用接口。**
 
-**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险。**
+**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险；XML 语法和文本重叠静态检查优先使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)。**
 
 **CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**
 
 **编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；已有 Slides 的多页大改优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内批量重建页面，避免 `slides +create` 生成新链接。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
 
+**用户要求使用模板**：按 [lark-slides-pptx-template-workflows.md](references/lark-slides-pptx-template-workflows.md) 处理。
+
 ## 身份选择
 
 飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。
@@ -82,16 +141,17 @@ lark-cli auth login --domain slides
 按需再读：
 
 - 创建：[`lark-slides-create.md`](references/lark-slides-create.md)
+- 阅读：[`lark-slides-xml-presentations-get.md`](references/lark-slides-xml-presentations-get.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-replace-pages.md`](references/lark-slides-replace-pages.md)
 - 截图：[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)
 - 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
+- 图表：[`slides_chart_demo.xml`](references/slides_chart_demo.xml)
 - 图标：[`iconpark.md`](references/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py)
 - 排障：[`troubleshooting.md`](references/troubleshooting.md)
 - 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml)
 
-## Workflow
 
-> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要适当，排版要留白。
+## Workflow
 
 ### Design Ideas
 
@@ -100,38 +160,30 @@ lark-cli auth login --domain slides
 开始写 XML 前，先在 `slide_plan.json` 里确定 deck 级视觉策略：
 
 - **主题化配色**：配色必须服务本次主题、行业和受众，不要默认蓝色商务风。如果把同一套颜色换到另一个完全不同主题仍然成立，说明配色不够具体。
-- **主次比例**：选择 1 个主色承担约 60-70% 视觉权重，1-2 个辅助色承担结构和分区，1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。
-- **背景一致性**：先确定全 deck 的背景策略，默认保持同一明暗基调和底色体系；只有分节、转场或强调页才有意改变背景，并必须通过相同主色、纹理、边栏或 motif 让变化看起来属于同一套设计。无论深浅，都要保证正文、图标和线条对比充足。
-- **统一 motif**：选择一个可复用视觉母题贯穿全文，例如粗侧边栏、圆形图标底、半出血图片区、编号节点、卡片左上角色块或大号数字。不要每页换一套装饰语言。
+- **主次比例**：选择 1 个主色承担约 60-70% 视觉权重，1 个辅助色承担结构和分区，1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。
+- **背景一致性**：先确定全 deck 的背景策略，默认保持同一明暗基调和底色体系；无论深浅，都要保证内容和背景对比充足。
+- **统一 motif**：选择一个可复用视觉母题贯穿全文，例如编号节点、卡片处理方式、半出血图片区域、标题、页脚。不要每页换一套装饰语言。
 
-每页至少要有一个视觉元素：图片、图标、图表、表格、流程、对比结构、大号数字、示意图或由 shape 组成的抽象视觉。文本框本身不算主视觉。
+每页至少要有一个视觉元素：图片、图标、图表、表格、流程、对比结构或大号数字。文本框本身不算主视觉。
 
-可优先考虑这些页面形态：
+常见页面形态：
 
 - **双栏结构**：左文右图或左图右文，视觉区域占 35-45% 宽度。
 - **图标行**：图标在色块或圆形底中，右侧是短标题和一句解释。
-- **2x2 / 2x3 网格**：适合能力、模块、风险、行动项，每格内容保持同等层级。
-- **半出血视觉**：图片或抽象形状占据左/右半屏，文字覆盖或贴边排布。
-- **大数字卡片**：关键指标用 60-72pt 数字，下面配 10-14pt 标签。
+- **网格**：适合能力、模块、风险、行动项，每格内容保持同等层级。
+- **半出血视觉**：图片占据左/右半屏，文字覆盖或贴边排布。
+- **大数字卡片**：核心指标用大数字，下面配标签与简短解读。
 - **对比列**：before/after、方案 A/B、问题/解法用左右并列，标题和基线严格对齐。
 - **时间线/流程图**：步骤用节点和箭头表达，流程方向必须一眼可见。
 
-字体和间距建议：
-
-- 标题 36-44pt，关键结论可更大；正文 14-18pt；注释 10-12pt。
-- 正文默认左对齐；只在封面、结尾或大号数字场景中使用居中。
-- 页面边距至少 40px；内容块之间保持 24-40px 间距，并在同一 deck 内保持一致。
-- 卡片内边距要真实留出空间，不要让文字贴边；对齐 shape 和文字时要考虑文本框 padding。
-
 常见错误必须避免：
 
 - 不要所有页面复用同一种标题 + 三 bullets 版式。
 - 不要用低对比文字或低对比图标，例如浅灰字压在浅色背景上。
 - 不要让装饰线穿过文字，或让页脚、来源、编号挤压主体内容。
-- 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成 XML-native 视觉。
-- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。
-- 不要使用 emoji。
-- 不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。
+- 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成替代图片。
+- 不要在任何位置使用 emoji 图标。
+
 
 ### 创建方式选择
 
@@ -150,25 +202,26 @@ lark-cli auth login --domain slides
 ### 生成流程
 
 ```text
-Step 1: 需求澄清 & 读取知识
-  - 澄清主题、受众、页数、风格；若用户上传 PPTX 作为模板，按顶部『用户自定义模板』规则处理
+Step 1: 需求分析 & 读取知识
+  - 分析主题、受众、页数、风格；
+  - 若用户要求使用模板，按 lark-slides-pptx-template-workflows.md 处理
   - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md
+  - 涉及图表读取 slides_chart_demo.xml
 
-Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json
-  - 生成结构化大纲供用户确认
-  - 新建 / 大幅改写必须先创建目录并写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`
+Step 2: 生成大纲 → 写入 slide_plan.json
+  - 生成结构化大纲
+  - 新建 / 大幅改写必须先创建目录并写入 `slide_plan.json`
   - plan 字段、路径命名和 `asset_need` 结构按 planning-layer.md / asset-planning.md 执行
 
 Step 3: 按 slide_plan.json 生成 XML → 创建
   - 逐页消费 plan：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
-  - 缺少真实素材时必须用 `fallback_if_missing` 生成 XML-native 兜底视觉；不要留空
-  - 调用创建或整页替换接口前，先保存待提交 XML 并运行 xml_text_overlap_lint.py；error_count 不为 0 必须先修
+  - 缺少真实素材时必须用 `fallback_if_missing` 生成替代图片，不要留空
   - 创建方式按“创建方式选择”判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
 
 Step 4: 审查 & 交付
-  - 创建完成后，必须用 `slides +xml-get` 读取全文 XML，并按 validation-checklist.md 做显式验证记录
+  - 创建完成后，必须用 `slides +xml-get` 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
   - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
-  - 没问题 → 交付：告知用户演示文稿 ID 和访问方式
+  - 没问题 → 交付：使用 NotifyHuman 工具交付 PPT 链接
 ```
 
 ### jq 命令模板（编辑已有 PPT 时使用）
@@ -183,7 +236,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 等元素
   </data>
 </slide>' '{slide:{content:$content}}')"
 
@@ -200,7 +253,7 @@ lark-cli slides xml_presentation.slide create \
 
 ### 大纲模板
 
-生成大纲时使用以下格式，交给用户确认：
+生成大纲时使用以下格式：
 
 ```text
 [PPT 标题] — [定位描述]，面向 [目标受众]
@@ -257,7 +310,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 | Shortcut | 说明 |
 |----------|------|
 | [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `<img src="@./local.png">` 占位符自动上传） |
-| [`+xml-get`](references/lark-slides-xml-get.md) | 读取全文或单页 XML，并可保存到本地文件，避免终端输出被截断 |
+| [`+xml-get`](references/lark-slides-xml-presentations-get.md) | 读取全文 XML 并保存到本地文件，避免终端输出被截断 |
 | [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
 | [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
 | [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内批量重建多个页面：先创建新页到旧页前，再删除旧页；适合已有 Slides 的多页大改，不新建链接 |

skills/lark-slides/references/asset-planning.md

@@ -6,7 +6,8 @@
 
 ## Core Rules
 
-- Every planned asset must include a fallback visual plan. The fallback can use native charts, tables, whiteboard diagrams, placeholder regions, or XML shapes, text, and arrows as appropriate.
+- `asset_need` is metadata only. It can guide page design.
+- Every planned asset must include a fallback visual plan. The fallback can use native charts, tables, placeholder regions, or XML shapes, text, and arrows as appropriate.
 - 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.
@@ -42,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`: column, bar, line, area, radar, pie, doughnut/ring, or combo data visual. Note: `<chart>` does not support funnel or scatter — map those to `<whiteboard>` SVG at generation time.
+- `chart`: column, bar, line, area, radar, pie, doughnut/ring, or combo data visual. Note: `<chart>` does not support funnel or scatter.
 - `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.
@@ -66,7 +67,7 @@ Match asset type to slide role:
 For `asset_type: "chart"`:
 
 - If the visual is a supported standard data chart — column, bar, line, area, radar, pie, doughnut/ring, or combo — `fallback_if_missing` must still render as a native `<chart>`.
-- Do not imitate supported standard data visuals with manual drawing primitives or `<whiteboard>`.
+- Do not imitate supported standard data visuals with manual drawing primitives.
 - Choose the data source explicitly:
   - `user_provided`: when the user provides concrete values, tables, CSV, or metric lists, use those values and do not replace them with mock data.
   - `mock_placeholder`: when the user asks for a placeholder, template, example, or chart position to replace later, use mock data in a native `<chart>`.
@@ -129,7 +130,8 @@ 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 the planned XML-native element type. Supported standard data visuals still use native `<chart>`; other fallbacks may use shapes, text, lines, arrows, tables, whiteboard diagrams, or placeholder panels.
+2. If no asset exists, immediately render `fallback_if_missing` with the planned generated close-enough image. Supported standard data visuals still use native `<chart>`; other fallbacks may use the image generation tool to create an approximate image.
 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.
+6. If the image generation tool is unavailable or fails, degrade to an XML-native fallback instead of leaving a blank: native `<chart>` for data, otherwise a simple in-card shape/text placeholder sized to fill `visual_focus`.

skills/lark-slides/references/examples.md

@@ -1,91 +0,0 @@
-# 完整操作示例
-
-本文档提供与 CLI schema 一致的调用示例，XML 内容均遵循 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
-
-> **重要**：新建 PPT 请使用 `slides +create --slides`，传入由 `<slide>` XML 字符串组成的 JSON 数组；每个元素必须是一页完整的 `<slide>`。复杂内容建议先创建空白 PPT，再通过 `xml_presentation.slide.create` 逐页添加。完整 `<presentation>` XML 可用于本地 lint 或读取，但不能直接作为 `+create` 的提交参数。
-
-## 目录
-
-- [示例 1：可靠创建 6 页 PPT](#示例-1可靠创建-6-页-ppt)
-- [示例 7: +replace-slide + block_insert 给已有页加图](#示例-7-replace-slide--block_insert-给已有页加图)
-- [示例 8: +replace-slide + block_replace 替换一个块](#示例-8-replace-slide--block_replace-替换一个块)
-
-## 示例 1：可靠创建 6 页 PPT
-
-### 1. 写入规划文件
-
-```bash
-DECK_DIR=".lark-slides/plan/reliable-six-page-ppt"
-mkdir -p "$DECK_DIR"
-
-# 按 planning-layer.md 写入 "$DECK_DIR/slide_plan.json"，
-# 至少记录 6 页的顺序和标题。
-```
-
-### 2. 为每页保存独立 XML
-
-每个文件都是完整的 `<slide>`。下面的循环会生成 6 个独立 XML 文件；实际项目中可将每页主体替换为规划内容。
-
-```bash
-titles=("主题与结论" "问题背景" "核心方法" "关键数据" "执行计划" "总结与行动")
-for i in {1..6}; do
-  printf -v page '%02d' "$i"
-  cat > "$DECK_DIR/slide-$page.xml" <<XML
-<slide xmlns="http://www.larkoffice.com/sml/2.0"><style><fill><fillColor color="rgb(248,250,252)"/></fill></style><data><shape type="rect" topLeftX="56" topLeftY="56" width="12" height="428"><fill><fillColor color="rgb(37,99,235)"/></fill></shape><shape type="text" topLeftX="100" topLeftY="160" width="760" height="90"><content textType="title" autoFit="normal-auto-fit"><p>${titles[$((i-1))]}</p></content></shape><shape type="text" topLeftX="100" topLeftY="290" width="700" height="70"><content textType="body" autoFit="normal-auto-fit"><p>页面主体内容。</p></content></shape></data></slide>
-XML
-done
-```
-
-### 3. 逐页运行 lint
-
-提交前检查每个独立 XML。`summary.error_count` 必须为 `0`，否则先修复 XML 或布局问题。
-
-```bash
-for slide_xml in "$DECK_DIR"/slide-0{1,2,3,4,5,6}.xml; do
-  python3 skills/lark-slides/scripts/xml_text_overlap_lint.py \
-    --input "$slide_xml" | tee "${slide_xml%.xml}.lint.json"
-done
-
-test "$(jq -s 'map(.summary.error_count) | add' "$DECK_DIR"/slide-0{1,2,3,4,5,6}.lint.json)" = "0"
-```
-
-### 4. 使用 `+create` 创建 6 页 PPT
-
-`--slides` 接收由 6 个完整 `<slide>` XML 字符串组成的 JSON 数组；使用 `jq --rawfile` 避免手动处理 XML 引号和换行。
-
-```bash
-lark-cli slides +create --as user \
-  --title "可靠创建 6 页 PPT" \
-  --slides "$(jq -n \
-    --rawfile s1 "$DECK_DIR/slide-01.xml" \
-    --rawfile s2 "$DECK_DIR/slide-02.xml" \
-    --rawfile s3 "$DECK_DIR/slide-03.xml" \
-    --rawfile s4 "$DECK_DIR/slide-04.xml" \
-    --rawfile s5 "$DECK_DIR/slide-05.xml" \
-    --rawfile s6 "$DECK_DIR/slide-06.xml" \
-    '[$s1, $s2, $s3, $s4, $s5, $s6]')" \
-  > "$DECK_DIR/create.json"
-create_status=$?
-
-if [ "$create_status" -ne 0 ]; then
-  exit "$create_status"
-fi
-
-if ! PRESENTATION_ID=$(jq -er '.data.xml_presentation_id | strings | select(length > 0)' "$DECK_DIR/create.json"); then
-  echo "missing non-empty data.xml_presentation_id in $DECK_DIR/create.json" >&2
-  exit 1
-fi
-echo "$PRESENTATION_ID" > "$DECK_DIR/xml_presentation_id"
-```
-
-如果创建中途失败，先保存已经返回的 `xml_presentation_id`，再回读确认实际已创建页数。
-
-### 5. 用 `+xml-get` 回读全文 XML
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PRESENTATION_ID" \
-  --output "$DECK_DIR/readback.xml" \
-  --json | tee "$DECK_DIR/readback.json"
-```
-

skills/lark-slides/references/iconpark.md

@@ -25,8 +25,8 @@ python3 skills/lark-slides/scripts/iconpark_tool.py list-categories
 - 默认先检索：语义图标需求必须先用 `iconpark_tool.py search --limit 8` 或 `--limit 10`，让 agent 从候选里结合版面语义二次判断；不要阅读全文索引，也不要编造不存在的 `iconType`。
 - 图标用于概念提示、步骤、状态、指标、角色和导航；不要用无关装饰图标填充版面。
 - 常用尺寸：行内状态图标 16-24px，卡片标题图标 28-40px，主视觉图标 56-96px。
-- 视觉规范要求图标设置非透明 `fillColor`，显式指定颜色并和背景有足够对比；深色背景优先放在浅色圆形/方形底上，或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。
-- 查不到合适图标时，用 shape、line、text 画 XML-native fallback，不留空图标位。
+- 图标必须填充颜色并和背景有足够对比；深色背景优先放在浅色圆形/方形底上，或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。
+- 查不到合适图标时，从高频示例里选择替代图标（随机选择，不要千篇一律），不留空图标位。
 
 ## 高频示例
 

skills/lark-slides/references/lark-slides-create.md

@@ -1,8 +1,6 @@
 
 # slides +create（创建飞书幻灯片）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
 创建一个新的飞书幻灯片演示文稿，可选一步添加页面内容。
 
 - 禁止：从完整 <presentation> XML 解析/拆分/重序列化生成提交 payload。
@@ -153,4 +151,5 @@ lark-cli slides xml_presentation.slide create --as user \
 
 ## 相关命令
 
-- [slides +xml-get](lark-slides-xml-get.md) — 读取 PPT 内容并保存到本地文件
+- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 添加幻灯片页面
+- [slides +xml-get](lark-slides-xml-presentations-get.md) — 读取 PPT 内容并保存到本地文件

skills/lark-slides/references/lark-slides-media-upload.md

@@ -1,8 +1,6 @@
 
 # slides +media-upload（上传本地图片到飞书幻灯片）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
 把本地图片上传到指定演示文稿的 drive 媒体库，返回 `file_token`。**返回的 token 作为 `<img src="...">` 的值塞进 slide XML 即可显示图片。**
 
 ## 命令
@@ -125,3 +123,4 @@ lark-cli slides +replace-slide --as user \
 
 - [+create](lark-slides-create.md) — 新建 PPT（支持 `@` 占位符自动上传图片）
 - [+replace-slide](lark-slides-replace-slide.md) — 给已有页加图 / 换图（`block_insert` / `block_replace`）
+- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 创建 slide 页面（拿到 file_token 后塞进 XML）

skills/lark-slides/references/lark-slides-pptx-template-workflows.md

@@ -1,12 +1,12 @@
 # PPT Template Rewrite Principles
 
-本页只约束“用户指定 PPT 模板、底稿、已有 PPTX/PDF/Slides，并要求基于它二次创作”的场景。核心原则：模板不是风格参考，而是必须沿用的编辑底稿。
+核心原则：模板不是风格参考，而是必须沿用的编辑底稿。
 
 ## Import First
 
-用户指定 PPT 模板时，先把模板导入成 Lark Slides。后续写入目标是导入后的 Slides，不是新建一个脱离模板的 deck，也不是先在本地重画 PPTX 再导入。
+如果用户提供的模板是 PPTX 格式，先把模板导入成 Lark Slides。后续写入目标是导入后的 Slides，不是新建一个脱离模板的 deck，也不是先在本地重画 PPTX 再导入。
 
-直接使用以下命令，不需要先加载 `lark-drive` skill：
+直接使用以下命令，不需要先加载 `lark-drive` Skill：
 
 ```bash
 lark-cli drive +import --as user --file "<template.pptx>" --type slides --json
@@ -18,13 +18,9 @@ lark-cli drive +import --as user --file "<template.pptx>" --type slides --json
 lark-cli drive +task_result --scenario import --ticket <TICKET>
 ```
 
-导入后必须回读 Slides 内容，理解每页的真实版式、字体、层级、图片、图表、shape、表格和文本容器。回读结果是模板二创的事实来源。
-
 ## Read Before Editing
 
-编辑任何 PPT 页面前，必须先阅读该页面。
-
-如果当前上下文中没有该页内容，必须重新读取页面；这里的“当前上下文”不包含 System Prompt。不能只凭记忆、文件名、缩略图印象或模板整体风格判断来编辑具体页面。
+导入后必须阅读 Slides 内容，理解每页的真实版式、字体、层级、图片、图表、shape、表格和文本容器。阅读结果是后续编辑的事实来源。
 
 阅读页面时至少判断：
 
@@ -47,7 +43,7 @@ lark-cli drive +task_result --scenario import --ticket <TICKET>
 
 ## Preserve Design
 
-模板二创必须严格沿用原版式和字体，只改内容，不做设计。
+编辑必须严格沿用原版式和字体，只改内容，不做设计。
 
 默认保留：
 
@@ -56,7 +52,7 @@ lark-cli drive +task_result --scenario import --ticket <TICKET>
 - 背景图、图片、logo、图表、表格、装饰形状、线条、图标和页面结构。
 - 模板中不同页型之间的差异。
 
-不要把模板页改造成统一的通用卡片、白板、标题栏、三栏、2x2 卡片或大面积遮罩。不要把模板当作背景图后另起一套设计系统。
+不要把模板页改造成统一的通用卡片、空白板式布局、标题栏、三栏、2x2 卡片或大面积遮罩。不要把模板当作背景图后另起一套设计系统。
 
 ## Content Only
 
@@ -86,4 +82,4 @@ lark-cli drive +task_result --scenario import --ticket <TICKET>
 
 发现文字溢出时，优先凝练文字或缩减字号。发现遮挡时，调整 shape 顺序、局部位置或复用原有空白区域解决。只有在这些方法都不能满足内容表达时，才做局部新增或删除。
 
-模板二创的完成标准不是“生成了一套看起来统一的新 PPT”，而是“原模板的版式、字体和视觉结构仍清晰存在，内容已经被准确替换，并且回读后没有溢出和遮挡”。
+完成标准是“原模板的版式、字体和视觉结构仍清晰存在，内容已经被准确替换，并且回读后没有溢出和遮挡”。

skills/lark-slides/references/lark-slides-replace-slide.md

@@ -1,7 +1,5 @@
 # slides +replace-slide（块级替换 / 插入）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
 对指定 slide 做块级替换或插入。编辑已有 PPT 的主路径——`slide_id` 不变、页序不动、只影响被指定的块。
 
 相比直接调 `xml_presentation.slide.replace`，这个 shortcut 的四个额外价值：
@@ -88,7 +86,6 @@ 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) |
 
 **不可作为根元素**：
 

skills/lark-slides/references/lark-slides-screenshot.md

@@ -4,7 +4,7 @@
 
 获取幻灯片页面截图并保存为本地图片文件。默认用于已存在 PPT 页面截图；传入 `--content` 时用于直接渲染单个 `<slide>` XML 片段预览。本 shortcut 会在 CLI 进程内解码并写入文件，stdout 只返回文件路径、大小、页面 ID 等元信息，避免把图片 Base64 输出给模型。
 
-注意：该截图能力受应用白名单限制，绝大多数应用不可用。若截图失败，记录错误即可；不要引导用户申请 `slides:presentation:screenshot` 权限。后续按 `validation-checklist.md` 走非截图验证，不要声称已完成截图验收。
+注意：该截图能力受应用白名单限制，绝大多数应用不可用。截图失败时不要引导用户申请 `slides:presentation:screenshot` 权限；记录错误后降级到 XML 读回、结构 lint、文本重叠检查等非截图检查路径。
 
 ## 命令
 

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

@@ -1,331 +0,0 @@
-# Whiteboard 画板元素
-
-`<whiteboard>` 放在 `<data>` 内，内部可放 **SVG** 或 **Mermaid**，用于绘制流程图、时序图、架构图、散点图、漏斗图、自定义图标、装饰图案等 `<chart>` 和 `<shape>` 难以覆盖的视觉内容。
-
-普通柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图和组合图应优先使用原生 `<chart>`。除非用户明确要求像素级自定义，或图表类型确实不受 `<chart>` 支持，否则不要用 `<whiteboard>` + SVG / Mermaid 重画这些标准图表。
-
-> 前置条件：使用本文档前先阅读 [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 / Mermaid 手绘——原生渲染更省力、结构更稳定，也更容易被回读和后续编辑。
-
----
-
-## 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？
-
-选择分三步：**先排除原生 `<chart>`，再判断 whiteboard 类型，最后看当前模型身份**。
-
-### 第一步：先确认是否应该使用 `<chart>`
-
-如果内容是柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图或组合图，返回使用原生 `<chart>`，不要继续套用本文档的 SVG / Mermaid 路径。
-
-### 第二步：whiteboard 类型优先判断
-
-以下类型**推荐 Mermaid**，自动布局、代码简洁；如需精确匹配品牌配色或自定义节点样式，可改用 SVG：
-
-| 图表类型 | Mermaid 关键字 |
-|----------|--------------|
-| 流程图、决策树、架构图 | `flowchart TD` / `flowchart LR` |
-| 时序图 | `sequenceDiagram` |
-| 类图 | `classDiagram` |
-| 甘特图 | `gantt` |
-| 状态图 | `stateDiagram-v2` |
-| 思维导图 | `mindmap` |
-| ER 图 | `erDiagram` |
-
-### 第三步：非原生图表与装饰元素按模型身份选路径
-
-上表以外的场景（散点图、漏斗图、进度条、时间线、波浪背景、星点纹理等）需要精确控制坐标和配色，SVG 表达力更强，但各模型生成 SVG 的能力有差异：
-
-| 模型身份 | 路径 |
-|----------|------|
-| Claude / Gemini / GPT / GLM | **SVG** — 精确控制坐标、颜色、透明度 |
-| Doubao / Seed / Other | **Mermaid** — 用 `gantt`、`flowchart` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
-
-> **先自报身份再选路径**：在决定使用 SVG 之前，确认当前模型属于哪一类。不要跳过这一步。
-
----
-
-## 模式一：SVG
-
-### ⚠️ 设计品质要求
-
-在 slide 里嵌入 `<whiteboard>` 的目的是**表达原生 `<chart>` 或基础 `<shape>` 难以覆盖的视觉关系**，不是把标准数据图表手绘一遍。
-
-- **不要只用矩形加文字应付**：通篇纯白底色 + 方块 + 黑字等于白做，这是不及格输出
-- **非原生数据视觉必须有坐标系**：散点、漏斗等仍要有必要的坐标轴、刻度、数值标注或分段说明，不要只画点或色块
-- **字号必须有层级**：标题 ≠ 标签 ≠ 数值，混用同一字号会消灭视觉焦点
-- **配色要与 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**，而不是手动估值。适用范围包括散点、漏斗、装饰性点阵、等间距圆、重复图案等；普通柱状图、折线图、饼图仍应回到原生 `<chart>`。
-
-> **主动去算**：写 SVG 之前先运行脚本，把输出当注释贴在 `<svg>` 开头，再照着填坐标。估值几乎每次都需要反复调整，跳过这步反而更慢。
-
-**散点图 / 装饰性点阵范式**
-
-```python
-W, H = 360, 260
-origin_x, origin_y = 50, 216  # 左下角，SVG Y 轴向下
-cw, ch = 290, 184
-
-points = [(12, 40), (28, 80), (45, 65)]
-x_min, x_max, y_min, y_max = 0, 50, 0, 100
-for i, (xv, yv) in enumerate(points):
-    x = round(origin_x + (xv - x_min) / (x_max - x_min) * cw)
-    y = round(origin_y - (yv - y_min) / (y_max - y_min) * ch)
-    print(f"point-{i}: cx={x} cy={y}")
-```
-
-**装饰性元素（等间距范式）**
-
-```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),   # item-0
-    (107, 10, 80, 170),  # item-1
-    (204, 40, 80, 140),  # item-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` | 项目计划、里程碑 |
-| 类图 | `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 |
-| 甘特图 | 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)

skills/lark-slides/references/lark-slides-xml-get.md

@@ -1,100 +0,0 @@
-# slides +xml-get（读取 XML）
-
-读取已有演示文稿的完整 XML，或按 `slide_id` / 页码读取单页 XML。适合创建后验收、编辑前备份、获取 `slide_id` / `revision_id`，以及排查空白页、破图、文本溢出等问题。相比直接调用底层 `xml_presentations.get` / `xml_presentation.slide.get`，本 shortcut 会自动解析 Slides URL / Wiki URL，并可把 XML 保存到本地文件，避免终端输出被截断。
-
-## 命令
-
-
-```bash
-lark-cli slides +xml-get \
-  --as user \
-  --presentation <slides_url_or_xml_presentation_id> \
-  --output .lark-slides/plan/<deck-id>/readback.xml
-```
-
-## 参数
-
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
-| `--output` | 否 | 本地 XML 保存路径，必须是当前工作目录内的相对路径，不能传绝对路径。传入时 XML 内容保存到文件，stdout 只返回保存后的绝对路径、大小等简短元信息；省略时默认返回 JSON envelope |
-| `--slide-id` | 否 | 页面 short ID；传入后只读取该页 XML。不能和 `--slide-number` 同时使用 |
-| `--slide-number` | 否 | 1-based 页码；传入后只读取该页 XML。不能和 `--slide-id` 同时使用 |
-| `--revision-id` | 否 | 读取指定版本；默认 `-1`，表示最新版本 |
-| `--remove-attr-id` | 否 | 仅全文读取可用。移除返回 XML 中的 `id` 属性；适合只读检查，不适合精确块级编辑 |
-| `--raw` | 否 | 省略 `--output` 时直接把 XML 原文写到 stdout，不包 JSON envelope。不能和 `--output` / `--jq` / 非 json `--format` 同时使用 |
-| `--dry-run` | 否 | 预览将调用的 API 和输出方式，不读取真实 XML |
-
-## 输出到文件
-
-推荐普通工作流都传 `--output`，尤其是中大型 PPT。`--output` 必须是当前工作目录内的相对路径，例如 `.lark-slides/plan/$PID/readback.xml`，不要传 `/tmp/readback.xml` 这类绝对路径。XML 会写入本地文件，stdout 只保留元信息，便于后续脚本读取。
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" \
-  --output .lark-slides/plan/$PID/readback.xml
-```
-
-成功输出中的 `data` 类似：
-
-```json
-{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "path": "/abs/path/.lark-slides/plan/slides_example_presentation_id/readback.xml",
-  "size": 123456,
-  "content_saved": true,
-  "revision_id": 12
-}
-```
-
-其中 `path` 是 CLI 解析后的绝对路径。
-
-如果传入 `--remove-attr-id`，返回元信息中会包含 `"remove_attr_id": true`。
-
-## 读取单页
-
-已知页面 short ID 时，用 `--slide-id`：
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" \
-  --slide-id "$SID" \
-  --output .lark-slides/plan/$PID/slide-$SID.xml
-```
-
-已知页码时，用 `--slide-number`（页码从 1 开始）：
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" \
-  --slide-number 2 \
-  --output .lark-slides/plan/$PID/slide-2.xml
-```
-
-单页模式底层调用 `xml_presentation.slide.get`，返回或保存的是单个 `<slide>` XML 片段。`--slide-id` 和 `--slide-number` 不能同时传；`--remove-attr-id` 只支持全文读取。
-
-## 输出到终端
-
-省略 `--output` 时，CLI 默认输出 JSON envelope，XML 位于 `data.xml_presentation.content`（全文）或 `data.slide.content`（单页）。这个模式适合配合 `--jq` 临时提取：
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" \
-  --jq '.data.xml_presentation.content'
-```
-
-需要把 XML 原文直接写到 stdout 时，加 `--raw`：
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" \
-  --slide-number 2 \
-  --raw
-```
-
-## 相关命令
-
-- [slides +screenshot](lark-slides-screenshot.md) - 获取页面截图做视觉验证
-- [slides +replace-slide](lark-slides-replace-slide.md) - 局部替换或插入页面元素
-- [slides +replace-pages](lark-slides-replace-pages.md) - 多页整页重建
-- [xml_presentations get](lark-slides-xml-presentations-get.md) - 底层原生 API 参考

skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md

@@ -0,0 +1,219 @@
+# lark-slides xml_presentation.slide create
+
+## 用途
+
+在指定的 XML 演示文稿中创建新的幻灯片页面，通常用于给 `slides +create` 创建出的空白 PPT 逐页补充内容。
+
+## 命令
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '<json_params>' --data '<json_data>'
+```
+
+## 参数说明
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--params` | JSON string | 是 | 路径参数与查询参数 |
+| `--data` | JSON string | 是 | 请求体，包含新页面内容 |
+
+### params JSON 结构
+
+```json
+{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "revision_id": -1,
+  "tid": "idMock"
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `xml_presentation_id` | string | 是 | 目标演示文稿的唯一标识符 |
+| `revision_id` | integer | 否 | 演示文稿版本号，`-1` 表示最新版本 |
+| `tid` | string | 否 | 锁的事务 ID |
+
+### data JSON 结构
+
+```json
+{
+  "slide": {
+    "slide_id": "slide_example_id",
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\">...</slide>"
+  },
+  "before_slide_id": "slide_before_target"
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `slide.slide_id` | string | 否 | 幻灯片页面 short ID |
+| `slide.content` | string | 否 | 新幻灯片的 XML 内容 |
+| `before_slide_id` | string | 否 | 插入到指定页面之前 |
+
+## slide XML 结构
+
+`slide.content` 是一个完整的 `<slide>` 元素，遵循 SML 2.0 Schema：
+
+```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>
+```
+
+详细格式请参考 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
+
+## 使用示例
+
+### 在末尾添加幻灯片
+
+```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>"
+  }
+}'
+```
+
+### 在指定页面前插入幻灯片
+
+```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></data></slide>"
+  },
+  "before_slide_id": "slide_before_target"
+}'
+```
+
+### 带图形元素的幻灯片
+
+```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=\"520\" height=\"120\"><content textType=\"title\"><p>数据展示</p></content></shape><shape type=\"rect\" topLeftX=\"700\" topLeftY=\"100\" width=\"200\" height=\"150\"><fill><fillColor color=\"rgb(100, 149, 237)\"/></fill></shape></data></slide>"
+  }
+}'
+```
+
+### 从文件读取 XML
+
+```bash
+# 先创建 slide.xml 文件
+cat > slide.xml << 'EOF'
+<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>
+EOF
+
+# 然后创建幻灯片
+lark-cli slides xml_presentation.slide create --as user \
+  --params '{"xml_presentation_id":"slides_example_presentation_id"}' \
+  --data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')"
+```
+
+## 返回值
+
+成功时返回创建的幻灯片信息：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "slide_id": "slide_example_id",
+    "revision_id": 100
+  },
+  "msg": "success"
+}
+```
+
+### 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.slide_id` | string | 新幻灯片的唯一标识 |
+| `data.revision_id` | integer | 演示文稿最新版本号 |
+
+## slide 元素可用子元素
+
+| 元素 | 说明 |
+|------|------|
+| `<style>` | 页面样式（背景填充） |
+| `<data>` | 图形元素容器（shape、img、table、chart 等） |
+| `<note>` | 演讲者备注 |
+
+> [!IMPORTANT]
+> **本地图片必须先上传**：`xml_presentation.slide.create` 不识别 `@./local.png` 占位符（那是 `+create --slides` 的语法糖）。直接调本接口添加带图新页时，必须先用 [`slides +media-upload`](lark-slides-media-upload.md) 拿到 `file_token`，再写进 `<img src="<file_token>">`。
+>
+> 如果是从零开始建带图 PPT，**强烈建议改用 [`slides +create --slides '[...]'`](lark-slides-create.md#本地图片path-占位符)** 一步搞定（自动上传 + 替换 token）。
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
+| 400 | XML 格式错误 | 检查 `slide.content` 是否是完整 `<slide>` 元素 |
+| 400 | 请求体结构错误 | 检查是否按 `slide.content` 和 `before_slide_id` 包装 |
+| 403 | 权限不足 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope |
+| 3350001 | XML 非 well-formed 或服务端参数校验失败 | 优先检查未转义字符：文本 `Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2` |
+
+## 注意事项
+
+1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentation.slide.create` 查看最新的参数结构
+2. **slide.content 格式**: 必须是完整的 `<slide>` 元素，不是整个 presentation
+3. **命名空间建议**: 协议标准写法应带 `xmlns`，例如 `<slide xmlns="http://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
+4. **fill / border 写法**: 颜色填充使用 `<fill><fillColor color="..."/></fill>`，边框常用 `<border color="..." width="2"/>`
+5. **插入位置**: 通过 `before_slide_id` 指定插入目标，而不是用 `position`
+6. **JSON 转义**: 如果直接内联 XML，需要正确转义双引号
+7. **建议**: 先使用 `slides +xml-get` 获取现有结构，再添加新页面
+
+## 批量添加建议
+
+如果需要添加多张幻灯片，建议先明确每一页的 `before_slide_id`，或直接按最终顺序逐页追加：
+
+```bash
+#!/bin/bash
+
+PRESENTATION_ID="slides_example_presentation_id"
+
+declare -a 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>'
+  '<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>页面 3</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
+```
+
+## 相关命令
+
+- [slides +create](lark-slides-create.md) - 创建空白 PPT
+- [slides +xml-get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容并保存到本地文件
+- [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
+- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) - XML Schema 快速参考

skills/lark-slides/references/lark-slides-xml-presentation-slide-delete.md

@@ -64,11 +64,11 @@ lark-cli slides xml_presentation.slide delete --as user --params '{"xml_presenta
 
 ```json
 {
-  "ok": true,
-  "identity": "user",
+  "code": 0,
   "data": {
     "revision_id": 100
-  }
+  },
+  "msg": "success"
 }
 ```
 
@@ -121,5 +121,6 @@ done
 
 ## 相关命令
 
-- [slides +create](lark-slides-create.md) - 创建 PPT / 添加幻灯片页面
-- [slides +xml-get](lark-slides-xml-get.md) - 读取 PPT 内容并保存到本地文件
+- [slides +create](lark-slides-create.md) - 创建空白 PPT
+- [slides +xml-get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容并保存到本地文件
+- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面

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、chart、whiteboard 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：
+2. **block_id 提取**：返回 XML 里每个顶层块（shape、img、table、chart 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：
 
    ```bash
    lark-cli slides xml_presentation.slide get --as user \
@@ -106,5 +106,5 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 
 - [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐）
 - [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
-- [slides +xml-get](lark-slides-xml-get.md) — 读整个 PPT 并保存到本地文件
+- [slides +xml-get](lark-slides-xml-presentations-get.md) — 读整个 PPT 并保存到本地文件
 - [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环

skills/lark-slides/references/lark-slides-xml-presentation-slide-replace.md

@@ -173,13 +173,12 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 ## 注意事项
 
 1. **parts 原子事务**：任一条失败整批回滚，不会出现"前几条成功、后几条失败"的中间态。
-2. **block_id 的获取**：`slide.get` 返回的 XML 里每个块（shape、img、table、chart、whiteboard 等）会带 3 位 short element ID，用这个值填 `block_id` / `insert_before_block_id`。
+2. **block_id 的获取**：`slide.get` 返回的 XML 里每个块（shape、img、table、chart 等）会带 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. **`<whiteboard>` 返回结构不含内部数据**：`slide.get` 返回的 whiteboard 块只有外层标签和位置属性，SVG / Mermaid 内容不会随 XML 一起返回。但 `block_replace` 仍然可以强行覆盖——直接写入完整新 whiteboard XML 即可。
-8. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。
+7. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。
 
 ## 相关命令
 

skills/lark-slides/references/lark-slides-xml-presentations-get.md

@@ -4,13 +4,66 @@
 
 读取飞书幻灯片（PPT）演示文稿的完整 XML 内容信息。
 
+## Shortcut
+
+使用 `slides +xml-get` shortcut，可以把 XML 保存到本地文件，避免终端输出被截断。
+
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--presentation` | string | 是 | 演示文稿的唯一标识符 |
+| `--revision-id` | integer | 否 | 版本号，`-1` 表示最新版本 |
+| `--output` | string | 是 | 本地文件，必须使用相对路径 |
+| `--remove-attr-id` | flag | 否 | 移除 XML id 属性后读取 |
+| `--json` | flag | 是 | 必须按照 json 格式输出 |
+
+
+### 基础示例
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
+```
+
+### 指定版本读取
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --revision-id 10 \
+  --output .lark-slides/plan/slides_example_presentation_id/readback-r10.xml \
+  --json
+```
+
+### 移除 XML id 属性后读取
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --remove-attr-id \
+  --output .lark-slides/plan/slides_example_presentation_id/readback-no-id.xml \
+  --json
+```
+
+
 ## 底层原生命令形态
 
 ```bash
 lark-cli slides xml_presentations get --as user --params '<json_params>'
 ```
 
-## 参数说明
+### 参数说明
 
 | 参数 | 类型 | 必需 | 说明 |
 |------|------|------|------|
@@ -30,30 +83,8 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
 | `xml_presentation_id` | string | 是 | 演示文稿的唯一标识符 |
 | `revision_id` | integer | 否 | 版本号，`-1` 表示最新版本 |
 
-## 使用示例
 
-### 基础示例
-
-```bash
-lark-cli slides xml_presentations get --as user \
-  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":-1}'
-```
-
-### 指定版本读取
-
-```bash
-lark-cli slides xml_presentations get --as user \
-  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":10}'
-```
-
-### 移除 XML id 属性后读取
-
-```bash
-lark-cli slides xml_presentations get --as user \
-  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":-1,"remove_attr_id":true}'
-```
-
-## 返回值
+### 返回值
 
 成功时返回演示文稿的完整信息：
 
@@ -79,7 +110,7 @@ lark-cli slides xml_presentations get --as user \
 | `data.xml_presentation.revision_id` | integer | 版本号 |
 | `data.xml_presentation.content` | string | XML 格式的完整内容 |
 
-## 常见错误
+### 常见错误
 
 | 错误码 | 含义 | 解决方案 |
 |--------|------|----------|
@@ -87,13 +118,17 @@ lark-cli slides xml_presentations get --as user \
 | 403 | 权限不足 | 检查是否拥有 `slides:presentation:read` scope，或是否有访问权限 |
 | 400 | 参数格式错误 | 确保 `--params` 是合法的 JSON 字符串 |
 
-## 注意事项
 
-1. 直接调用底层 API 前，使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
-2. 返回的 XML 在 `data.xml_presentation.content` 字段中
-3. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
+### 注意事项
+
+1. lark-slides 工作流默认使用 `slides +xml-get`；只有必须直接调底层 API 时，才使用
+2. 直接调用底层 API 前，使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
+3. 返回的 XML 在 `data.xml_presentation.content` 字段中
+4. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
+5. 不要在普通工作流中把完整 XML 打到终端；用 `slides +xml-get --output` 保存文件
 
 ## 相关命令
 
-- [slides +create](lark-slides-create.md) - 创建 PPT / 添加幻灯片页面
+- [slides +create](lark-slides-create.md) - 创建空白 PPT
+- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面
 - [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面

skills/lark-slides/references/planning-layer.md

@@ -12,7 +12,8 @@
 4. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
 5. 读取 `xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。
 6. 按 plan、visual planning 和 asset planning 规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束，并把缺失素材转成可执行兜底视觉。
-7. 创建 PPT 后用 `slides +xml-get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
+7. 创建 PPT 后用 `slides +xml-get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系，空白 PPT 中没有 slide 元素。
+
 
 ## Plan Path
 
@@ -57,7 +58,7 @@ Exception:
   "theme_style": "Clean business style, light background, restrained blue accent, strong visual hierarchy.",
   "visual_system": {
     "background_strategy": "Content pages use one light base; cover and closing may use a related dark treatment with the same accent system.",
-    "motif": "A reusable left accent bar and consistent card/header treatments.",
+    "motif": "Consistent card style and numbered anchors.",
     "color_roles": {
       "primary": "Used for the dominant structural motif and about 60-70% of visual weight.",
       "secondary": "Used for grouped regions, comparison panels, or supporting categories.",
@@ -87,7 +88,7 @@ Exception:
         "asset_type": "logo",
         "purpose": "Signal product or team identity on the opening page.",
         "suggested_query": "product logo",
-        "fallback_if_missing": "Use a small text badge and abstract shape motif instead of a real logo."
+        "fallback_if_missing": "Create a close-enough image with the image generation tool instead of a real logo."
       },
       "text_density": "low",
       "speaker_intent": "Frame the decision and establish the deck's point of view."
@@ -137,7 +138,7 @@ Optional slide fields:
 }
 ```
 
-When `chart_contract.required == true`, XML generation must produce a `<chart>` element on that slide. A shape, line, polyline, or whiteboard approximation does not satisfy the plan.
+When `chart_contract.required == true`, XML generation must produce a `<chart>` element on that slide. A shape, line, or polyline approximation does not satisfy the plan.
 
 `data_source` must be one of:
 
@@ -181,7 +182,7 @@ Text density must be realistic for the planned geometry. If a page needs long ti
 Before generating XML, define a visual system that can survive the whole deck:
 
 - `background_strategy`: specify the default background for normal content pages, and which page roles may intentionally differ. Do not let pages drift through near-identical but inconsistent background colors.
-- `motif`: choose one or two reusable structural devices, such as a side bar, header rail, numbered node, card treatment, diagram lane, or section band. The motif should appear consistently enough that pages feel related.
+- `motif`: choose one reusable structural device, such as numbered node, card treatment, half-bleed image zone, headline, or footer. The motif should appear consistently enough that pages feel related.
 - `color_roles`: assign primary, secondary, and accent roles. The same color must not mean unrelated things across pages.
 - `cover_content_relationship`: if the cover uses a different dark or image-led treatment, state how it connects to content pages through shared colors, motifs, or geometry.
 - `closing_relationship`: if the closing page mirrors the cover, state that explicitly so it looks intentional rather than like a new theme.
@@ -203,22 +204,22 @@ Do not hard-code a page number just because a previous deck used that pattern. P
 
 ## Asset Planning
 
-`asset_need` is metadata. It can describe a desired figure, diagram, chart, icon, logo, screenshot, or fallback shape-based visual, but it must not require web search, local download, or media upload.
+`asset_need` is metadata. It can describe a desired figure, diagram, chart, icon, logo, screenshot, or fallback visual.
 
 Use an object for one planned asset, an array for multiple real needs, or `asset_type: "none"` when no asset is useful. Each planned asset must include:
 
 - `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, labels, tables, whiteboard diagrams, or placeholder panels.
+- `fallback_if_missing`: a plan to create a close-enough image with the image generation tool, or a native `<chart>` for data.
 - `chart_contract`: when `asset_type` is `chart` and the visual is a supported standard data chart, set this optional slide-level field so generation is locked to native `<chart>`.
 
 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 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":"architecture_diagram","purpose":"Explain component relationships.","suggested_query":"service architecture diagram","fallback_if_missing":"Render the component diagram with <shape> + <line>."}`
+- `{"asset_type":"logo","purpose":"Identify the customer context.","suggested_query":"customer logo","fallback_if_missing":"Create a close-enough image with the image generation tool instead of a real logo."}`
 - `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Render a native `<chart>` using the provided series when available; otherwise render a native `<chart>` with mock placeholder values and label it as 模拟数据，仅占位，待替换真实数据."}`
 
 ## XML Generation Contract
@@ -229,7 +230,7 @@ Before writing each slide XML, map the plan fields to concrete decisions:
 - `layout_type` determines the coordinate structure and element types. Use `visual-planning.md` for concrete layout rules.
 - `visual_focus` determines the largest visual region or emphasized object.
 - `text_density` caps visible text volume.
-- `asset_need` informs placeholder diagrams, icons, charts, screenshots, or shape-based fallback visuals only. Missing real assets must use `fallback_if_missing`, not blank regions.
+- `asset_need` informs placeholder diagrams, icons, charts, screenshots, or fallback visuals only. Missing real assets must use `fallback_if_missing`, not blank regions.
 - `chart_contract` locks supported standard data charts to native `<chart>` output. Manual approximations are allowed only when the planned chart type is unsupported by `<chart>` or when the visual is explicitly non-data/decorative.
 
 After creating the PPT, fetch the presentation and verify:

skills/lark-slides/references/slide-templates.md

@@ -1,201 +0,0 @@
-# Slide XML 模板
-
-可直接复制使用的 slide XML 模板。纯文本/形状模板可使用 `jq` 包装后传给 `xml_presentation.slide.create`：
-
-```bash
-lark-cli slides xml_presentation.slide create --as user \
-  --params '{"xml_presentation_id":"YOUR_ID"}' \
-  --data "$(jq -n --arg content 'PASTE_XML_HERE' '{slide:{content:$content}}')"
-```
-
-> **带图模板不要直接按上面的命令提交。** 新建 PPT 时可在 `+create --slides` 中使用 `src="@./local.png"`，CLI 会自动上传并替换为 `file_token`；给已有 PPT 添加或修改图片时，必须先用 `slides +media-upload` 拿到 `file_token`，再写进 `<img src="...">`。
-
-## 深色封面页
-
-```xml
-<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <style><fill><fillColor color="linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)"/></fill></style>
-  <data>
-    <shape type="text" topLeftX="80" topLeftY="160" width="800" height="70">
-      <content><p textAlign="center"><strong><span color="rgb(255,255,255)" fontSize="44">主标题</span></strong></p></content>
-    </shape>
-    <shape type="text" topLeftX="80" topLeftY="250" width="800" height="35">
-      <content><p textAlign="center"><span color="rgb(148,163,184)" fontSize="20">副标题</span></p></content>
-    </shape>
-    <shape type="text" topLeftX="80" topLeftY="420" width="800" height="25">
-      <content><p textAlign="center"><span color="rgb(100,116,139)" fontSize="14">底部信息</span></p></content>
-    </shape>
-  </data>
-</slide>
-```
-
-## 浅色内容页
-
-```xml
-<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <style><fill><fillColor color="rgb(248,250,252)"/></fill></style>
-  <data>
-    <shape type="rect" topLeftX="60" topLeftY="40" width="4" height="35">
-      <fill><fillColor color="rgb(59,130,246)"/></fill>
-    </shape>
-    <shape type="text" topLeftX="76" topLeftY="36" width="600" height="45">
-      <content><p><strong><span color="rgb(15,23,42)" fontSize="28">页面标题</span></strong></p></content>
-    </shape>
-    <shape type="text" topLeftX="60" topLeftY="100" width="840" height="380">
-      <content textType="body" lineSpacing="multiple:1.8">
-        <p><span color="rgb(51,65,85)" fontSize="15">正文段落</span></p>
-        <ul>
-          <li><p><span color="rgb(51,65,85)" fontSize="15">要点一</span></p></li>
-          <li><p><span color="rgb(51,65,85)" fontSize="15">要点二</span></p></li>
-          <li><p><span color="rgb(51,65,85)" fontSize="15">要点三</span></p></li>
-        </ul>
-      </content>
-    </shape>
-  </data>
-</slide>
-```
-
-## 数据卡片页（横排指标）
-
-```xml
-<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <style><fill><fillColor color="rgb(248,250,252)"/></fill></style>
-  <data>
-    <shape type="text" topLeftX="60" topLeftY="36" width="600" height="45">
-      <content><p><strong><span color="rgb(15,23,42)" fontSize="28">数据概览</span></strong></p></content>
-    </shape>
-    <!-- 卡片 1 -->
-    <shape type="rect" topLeftX="60" topLeftY="100" width="260" height="140">
-      <fill><fillColor color="rgb(255,255,255)"/></fill>
-      <border color="rgba(0,0,0,0.08)" width="1"/>
-    </shape>
-    <shape type="text" topLeftX="60" topLeftY="115" width="260" height="50">
-      <content><p textAlign="center"><strong><span color="rgb(59,130,246)" fontSize="36">数值</span></strong></p></content>
-    </shape>
-    <shape type="text" topLeftX="60" topLeftY="175" width="260" height="25">
-      <content><p textAlign="center"><span color="rgb(100,116,139)" fontSize="14">指标名称</span></p></content>
-    </shape>
-    <!-- 卡片 2：topLeftX="350" -->
-    <!-- 卡片 3：topLeftX="640" -->
-  </data>
-</slide>
-```
-
-## 带图版式
-
-> **关键提醒**：`<img>` 的 `width:height` = 原图比例时才不会被裁剪。每个模板都标注了图框比例和建议原图比例，**选模板前先对照你的素材比例**，不要硬塞（如把横图放进竖框，会被左右裁掉大半）。把 `@./your-image.jpg` 替换为实际路径（仅 `+create --slides` 支持 `@` 占位符；其他场景需先用 `slides +media-upload` 拿 `file_token`）。
-
-### 封面右图（左字右图）
-
-图框 400×225（**16:9**），建议原图：横幅 16:9（桌面壁纸、产品 banner、landscape 照片）
-
-```xml
-<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <style><fill><fillColor color="linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)"/></fill></style>
-  <data>
-    <shape type="text" topLeftX="60" topLeftY="180" width="450" height="80">
-      <content><p><strong><span color="rgb(255,255,255)" fontSize="44">主标题</span></strong></p></content>
-    </shape>
-    <shape type="text" topLeftX="60" topLeftY="270" width="450" height="40">
-      <content><p><span color="rgb(186,230,253)" fontSize="20">副标题</span></p></content>
-    </shape>
-    <line startX="60" startY="350" endX="180" endY="350">
-      <border color="rgb(59,130,246)" width="3"/>
-    </line>
-    <shape type="text" topLeftX="60" topLeftY="370" width="450" height="30">
-      <content><p><span color="rgb(203,213,225)" fontSize="13">底部信息</span></p></content>
-    </shape>
-    <!-- 图框 400×225 = 16:9；原图建议 16:9 横幅 -->
-    <img src="@./your-landscape.jpg" topLeftX="540" topLeftY="157" width="400" height="225"/>
-  </data>
-</slide>
-```
-
-### 三卡片带图（上图下文）
-
-每个图框 240×180（**4:3**），建议原图：4:3 或接近正方形的图（产品照、截图、icon 类）
-
-```xml
-<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <style><fill><fillColor color="rgb(248,250,252)"/></fill></style>
-  <data>
-    <shape type="text" topLeftX="60" topLeftY="40" width="600" height="45">
-      <content><p><strong><span color="rgb(15,23,42)" fontSize="28">核心亮点</span></strong></p></content>
-    </shape>
-    <line startX="60" startY="95" endX="140" endY="95">
-      <border color="rgb(59,130,246)" width="3"/>
-    </line>
-
-    <!-- 卡片 1 -->
-    <shape type="rect" topLeftX="60" topLeftY="130" width="270" height="360">
-      <fill><fillColor color="rgb(255,255,255)"/></fill>
-      <border color="rgba(0,0,0,0.08)" width="1"/>
-    </shape>
-    <!-- 图框 240×180 = 4:3；原图建议 4:3 -->
-    <img src="@./your-image-1.jpg" topLeftX="75" topLeftY="150" width="240" height="180"/>
-    <shape type="text" topLeftX="75" topLeftY="345" width="240" height="30">
-      <content><p><strong><span color="rgb(15,23,42)" fontSize="18">特性一</span></strong></p></content>
-    </shape>
-    <shape type="text" topLeftX="75" topLeftY="380" width="240" height="90">
-      <content><p><span color="rgb(71,85,105)" fontSize="14">简短描述文案，控制在两行以内。</span></p></content>
-    </shape>
-
-    <!-- 卡片 2：复制卡片 1，shape/img 的 topLeftX 改为 345 / 360 -->
-    <!-- 卡片 3：复制卡片 1，shape/img 的 topLeftX 改为 630 / 645 -->
-  </data>
-</slide>
-```
-
-### 左右分栏（图在左，文在右）
-
-图框 360×540（**2:3 竖幅**），建议原图：2:3 或 3:4 竖幅（人像照、产品竖拍、海报）
-
-> 如果你只有横幅图，不要硬塞进这个竖框 —— 改用"顶部横幅图 + 下方文字"的版式（把这里的图框改成 960×240 横条放在顶部）。
-
-```xml
-<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <style><fill><fillColor color="rgb(255,255,255)"/></fill></style>
-  <data>
-    <!-- 图框 360×540 = 2:3；原图建议 2:3 或 3:4 竖幅 -->
-    <img src="@./your-portrait.jpg" topLeftX="0" topLeftY="0" width="360" height="540"/>
-
-    <shape type="text" topLeftX="410" topLeftY="80" width="490" height="50">
-      <content><p><strong><span color="rgb(15,23,42)" fontSize="30">场景标题</span></strong></p></content>
-    </shape>
-    <line startX="410" startY="140" endX="490" endY="140">
-      <border color="rgb(59,130,246)" width="3"/>
-    </line>
-    <shape type="text" topLeftX="410" topLeftY="160" width="490" height="50">
-      <content><p><span color="rgb(71,85,105)" fontSize="16">一句话描述这个场景的价值。</span></p></content>
-    </shape>
-    <shape type="text" topLeftX="410" topLeftY="230" width="490" height="250">
-      <content textType="body" lineSpacing="multiple:1.8">
-        <ul>
-          <li><p><span color="rgb(51,65,85)" fontSize="15">要点一</span></p></li>
-          <li><p><span color="rgb(51,65,85)" fontSize="15">要点二</span></p></li>
-          <li><p><span color="rgb(51,65,85)" fontSize="15">要点三</span></p></li>
-        </ul>
-      </content>
-    </shape>
-  </data>
-</slide>
-```
-
-## 深色结尾页
-
-```xml
-<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <style><fill><fillColor color="linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)"/></fill></style>
-  <data>
-    <shape type="text" topLeftX="80" topLeftY="190" width="800" height="55">
-      <content><p textAlign="center"><strong><span color="rgb(255,255,255)" fontSize="36">感谢语或行动号召</span></strong></p></content>
-    </shape>
-    <line startX="410" startY="260" endX="550" endY="260">
-      <border color="rgb(59,130,246)" width="2"/>
-    </line>
-    <shape type="text" topLeftX="80" topLeftY="280" width="800" height="30">
-      <content><p textAlign="center"><span color="rgb(148,163,184)" fontSize="16">补充说明</span></p></content>
-    </shape>
-  </data>
-</slide>
-```

skills/lark-slides/references/slides_demo.xml

@@ -1,226 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" height="540" width="960">
-    <title>制造端智能升级</title>
-    <theme>
-        <textStyles>
-            <headline fontColor="rgb(255,255,255)" fontFamily="思源黑体" fontSize="36"/>
-            <sub-headline fontColor="rgb(229,231,235)" fontFamily="思源黑体" fontSize="20"/>
-            <body fontColor="rgb(229,231,235)" fontFamily="思源黑体" fontSize="16"/>
-        </textStyles>
-    </theme>
-    <slide>
-        <style>
-            <fill>
-                <fillColor color="linear-gradient(180deg, rgb(47, 79, 79) 0%, rgb(26, 26, 26) 100%)"/>
-            </fill>
-        </style>
-        <data>
-            <shape height="36" rotation="0" topLeftX="48" topLeftY="40" type="text" width="300">
-                <content>
-                    <p>
-                        <strong>
-                            <span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="28">时代背景</span>
-                        </strong>
-                    </p>
-                </content>
-            </shape>
-            <shape height="200" rotation="0" topLeftX="48" topLeftY="85" type="rect" width="864">
-                <fill>
-                    <fillColor color="rgba(0,0,0,0.2)"/>
-                </fill>
-            </shape>
-            <img alpha="0.4" alt="十月革命场景" height="180" rotation="0" src="https://example.com/images/scene-1.png" topLeftX="48" topLeftY="95" width="288">
-                <crop type="rect"/>
-            </img>
-            <img alpha="0.4" alt="列宁演讲油画" height="180" rotation="0" src="https://example.com/images/scene-2.png" topLeftX="336" topLeftY="95" width="288">
-                <crop type="rect"/>
-            </img>
-            <img alpha="0.4" alt="十月革命战斗场面" height="180" rotation="0" src="https://example.com/images/scene-3.png" topLeftX="624" topLeftY="95" width="288">
-                <crop type="rect"/>
-            </img>
-            <shape height="2" rotation="0" topLeftX="90" topLeftY="180" type="rect" width="780">
-                <fill>
-                    <fillColor color="rgba(255, 215, 0, 0.3)"/>
-                </fill>
-            </shape>
-            <shape height="10" rotation="0" topLeftX="120" topLeftY="176" type="ellipse" width="10">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-                <border color="rgb(255, 215, 0)" width="1"/>
-            </shape>
-            <shape height="24" rotation="0" topLeftX="60" topLeftY="140" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <strong>
-                            <span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="20">1917</span>
-                        </strong>
-                    </p>
-                </content>
-            </shape>
-            <shape height="22" rotation="0" topLeftX="60" topLeftY="200" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="16">十月革命</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="40" rotation="0" topLeftX="60" topLeftY="225" type="text" width="200">
-                <content verticalAlign="top">
-                    <p textAlign="center">
-                        <span color="rgb(156, 163, 175)" fontSize="12">沙皇专制终结，苏维埃政权建立</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="10" rotation="0" topLeftX="475" topLeftY="176" type="ellipse" width="10">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-                <border color="rgb(255, 215, 0)" width="1"/>
-            </shape>
-            <shape height="24" rotation="0" topLeftX="380" topLeftY="140" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <strong>
-                            <span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="20">1920s</span>
-                        </strong>
-                    </p>
-                </content>
-            </shape>
-            <shape height="22" rotation="0" topLeftX="380" topLeftY="200" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="16">国内战争</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="40" rotation="0" topLeftX="380" topLeftY="225" type="text" width="200">
-                <content verticalAlign="top">
-                    <p textAlign="center">
-                        <span color="rgb(156, 163, 175)" fontSize="12">革命与反革命的残酷斗争</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="10" rotation="0" topLeftX="830" topLeftY="176" type="ellipse" width="10">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-                <border color="rgb(255, 215, 0)" width="1"/>
-            </shape>
-            <shape height="24" rotation="0" topLeftX="740" topLeftY="140" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <strong>
-                            <span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="20">1930s</span>
-                        </strong>
-                    </p>
-                </content>
-            </shape>
-            <shape height="22" rotation="0" topLeftX="740" topLeftY="200" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="16">社会主义建设</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="40" rotation="0" topLeftX="740" topLeftY="225" type="text" width="200">
-                <content verticalAlign="top">
-                    <p textAlign="center">
-                        <span color="rgb(156, 163, 175)" fontSize="12">新经济政策与工业化探索</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="1" rotation="0" topLeftX="48" topLeftY="300" type="rect" width="864">
-                <fill>
-                    <fillColor color="rgba(255, 215, 0, 0.2)"/>
-                </fill>
-            </shape>
-            <shape height="24" rotation="0" topLeftX="48" topLeftY="320" type="text" width="280">
-                <content>
-                    <p>
-                        <span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="18">作者：奥斯特洛夫斯基</span>
-                    </p>
-                </content>
-            </shape>
-            <icon height="16" iconType="iconpark/Peoples/user.svg" topLeftX="52" topLeftY="360" width="16">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-            </icon>
-            <shape height="20" topLeftX="76" topLeftY="358" type="text" width="260">
-                <content verticalAlign="middle">
-                    <p>
-                        <span color="rgb(209, 213, 219)" fontSize="13">工人家庭出身，投身革命浪潮</span>
-                    </p>
-                </content>
-            </shape>
-            <icon height="16" iconType="iconpark/Sports/torch.svg" topLeftX="52" topLeftY="390" width="16">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-            </icon>
-            <shape height="20" topLeftX="76" topLeftY="388" type="text" width="260">
-                <content verticalAlign="middle">
-                    <p>
-                        <span color="rgb(209, 213, 219)" fontSize="13">战场负伤致残，生命陷入黑暗</span>
-                    </p>
-                </content>
-            </shape>
-            <icon height="16" iconType="iconpark/Health/first-aid-kit.svg" topLeftX="52" topLeftY="420" width="16">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-            </icon>
-            <shape height="20" topLeftX="76" topLeftY="418" type="text" width="260">
-                <content verticalAlign="middle">
-                    <p>
-                        <span color="rgb(209, 213, 219)" fontSize="13">全身瘫痪、双目失明</span>
-                    </p>
-                </content>
-            </shape>
-            <icon height="16" iconType="iconpark/Edit/edit.svg" topLeftX="52" topLeftY="450" width="16">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-            </icon>
-            <shape height="20" topLeftX="76" topLeftY="448" type="text" width="260">
-                <content verticalAlign="middle">
-                    <p>
-                        <span color="rgb(209, 213, 219)" fontSize="13">以文学为武器，口述完成创作</span>
-                    </p>
-                </content>
-            </shape>
-            <img alt="奥斯特洛夫斯基青年时期" height="213" rotation="0" src="https://example.com/images/ostrovsky.png" topLeftX="360" topLeftY="320" width="160">
-                <border color="rgba(255, 215, 0, 0.5)" width="2"/>
-                <crop type="rect"/>
-            </img>
-            <shape height="24" rotation="0" topLeftX="552" topLeftY="320" type="text" width="360">
-                <content>
-                    <p>
-                        <span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="18">创作动机</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="16" rotation="0" topLeftX="552" topLeftY="350" type="rect" width="2">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-            </shape>
-            <shape height="120" rotation="0" topLeftX="562" topLeftY="350" type="text" width="350">
-                <content lineSpacing="multiple:1.6" verticalAlign="top">
-                    <p>
-                        <span color="rgb(209, 213, 219)" fontSize="13">在双目失明、全身瘫痪的逆境中，奥斯特洛夫斯基以自身经历为蓝本，用顽强的意志口述完成了这部不朽巨著。他将文学创作视为生命的延续和战斗的武器，旨在通过保尔·柯察金的形象，向青年一代传递坚不可摧的革命信念和超越个人痛苦的崇高人生价值观。</span>
-                    </p>
-                </content>
-            </shape>
-        </data>
-        <note>
-            <content>
-                <p>各位好，这一页将我们带回《钢铁是怎样炼成的》这部巨著诞生的波澜壮阔的时代。</p>
-                <p>上半部分展示了从1917年十月革命到1930年代苏联社会主义建设的宏大历史画卷。这是一个充满剧烈社会变革和残酷斗争的年代，也是英雄主义和理想主义精神熊熊燃烧的年代。正是这样的背景，孕育了小说的灵魂。</p>
-                <p>下半部分，我们聚焦于作者奥斯特洛夫斯基的个人经历。他的一生，本身就是一部比小说更震撼人心的传奇。从投身革命的青年，到因伤致残的战士，再到与命运抗争的文学巨匠。他的创作动机源于自身不屈的战斗精神，他希望用保尔的故事激励后人，在任何困境中都不要放弃理想，要将有限的生命投入到无限的为人类解放而斗争的事业中去。</p>
-                <p>通过了解这段历史和作者的生平，我们能更深刻地理解《钢铁是怎样炼成的》这部作品的伟大之处。</p>
-            </content>
-        </note>
-    </slide>
-</presentation>

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/whiteboard/undefined)
+                - data: 页面元素容器(shape/line/polyline/img/table/icon/chart/undefined)
                 - note: 演讲者备注
             </xs:documentation>
         </xs:annotation>
@@ -960,7 +960,6 @@
                         <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>
@@ -3008,47 +3007,4 @@
         </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 包裹
-            适用场景: 流程图、时序图、思维导图、类图、甘特图、ER 图、用户旅程等结构图
-            特点: 用简短的文本声明描述图表逻辑, 由渲染引擎自动布局, 无需手动计算坐标
-            示例: &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>

skills/lark-slides/references/troubleshooting.md

@@ -1,16 +1,27 @@
 # Troubleshooting
 
-本文件覆盖 lark-slides 的 XML 排障和常见失败处理。
+本文件覆盖 lark-slides 的通用创建前自检、XML 排障和常见失败处理。命令专属问题优先看对应 reference，例如 `+replace-slide`、`+media-upload`、`xml_presentation.slide.create`。
+
+## XML Preflight
+
+在真正创建或替换前，至少检查：
+
+- 特殊字符已转义：正文和标题里的 `&`、`<`、`>` 不能裸写；属性值里的裸 `&` 也必须写成 `&amp;`。
+- 属性引号安全：XML 属性、shell 引号、JSON 字符串包装之间没有互相打断。
+- 结构合法：`<slide>` 下只放 `<style>`、`<data>`、`<note>`，文本都在 `<content>` 内。
+- 图片路径正确：`<img src="@...">` 只在 `+create --slides` 的支持链路中使用；直接调用 `xml_presentation.slide.create` 必须先拿到 `file_token`。
 
 ## Failure Order
 
 遇到 `invalid param`、某一页创建失败、页面空白或布局错乱时，按顺序处理：
 
-1. 先判断是否已有可用的 `xml_presentation_id`：从成功 stdout、错误 hint、用户给定链接或已保存上下文中获取；没有 ID 时不要回读，直接按当前错误处理。
-2. 如果有 `xml_presentation_id`，再用 `slides +xml-get` 尝试回读，确认是否存在演示文稿、是否已有部分页面写入、或是否只是空 presentation。
+1. 记录 `xml_presentation_id`，不要假设失败代表什么都没创建。
+2. 用 `slides +xml-get` 回读，确认是否已有部分页面写入。
 3. 检查失败页是否含未转义字符：`Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2`。
 4. 检查标签闭合、属性引号、`<content>` 结构，以及 `<slide>` 直接子元素。
-5. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide create` 逐页添加。
+5. 页面空白、溢出、重叠或越界时，按 [validation-checklist.md](validation-checklist.md) 运行 XML 文本重叠检查，并人工核对越界、截断、图文压盖等视觉风险；工具当前只会报告 `xml_not_well_formed` / `bbox_overlap`。
+6. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide.create` 逐页添加。
+7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时再用 `slide.delete` 旧页 + `slide.create` 新页。
 
 ## Symptom Fixes
 
@@ -23,9 +34,10 @@
 | 表格列宽不合理 | 调整 `colgroup` 中 `col` 的 `width` 值 |
 | 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1` / `dim2` 数据数量是否匹配 |
 | 图片被裁掉一部分 | `<img>` 的 `width` / `height` 是裁剪后尺寸；要整图显示就让 `width:height` 对齐原图比例 |
-| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符只在 `+create --slides` 中替换；直接调 `xml_presentation.slide create` 必须先用 `+media-upload` 拿 `file_token` |
+| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符只在 `+create --slides` 中替换；直接调 `xml_presentation.slide.create` 必须先用 `+media-upload` 拿 `file_token` |
 | 新插入的 `<img>` 挡住原有元素 | `slide.get` 读原页，对照已有块坐标挑空白位置；空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
 | 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)` |
+| 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
 
 ## Common Errors
 
@@ -34,12 +46,18 @@
 | 400 XML 格式错误 | XML 语法错误 | 检查标签闭合、属性引号、特殊字符转义 |
 | 400 请求包装错误 | `--data` 未按 schema 包装 | 检查是否传入 `xml_presentation.content` 或 `slide.content` |
 | 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--slides '[...]'` 的 shell 转义或长参数传递问题 | 改用两步创建，并在创建后立即读取 XML 验证 |
-| 403 权限不足 | 身份或 scope 不匹配 | 先检查是否误用了 bot 身份，再确认 scope 和文档权限；无权限时根据错误响应引导用户解决 |
+| 403 权限不足 | scope 或文档权限不匹配 | 确认 scope 和文档权限；无权限时根据错误响应引导用户解决 |
 | 404 演示文稿不存在 | `xml_presentation_id` 不正确或无权限 | 检查 token；wiki URL 需先解析真实 `obj_token` |
 | 404 幻灯片不存在 | `slide_id` 不正确 | 重新读取 presentation 或 slide，确认最新 ID |
 | 400 无法删除唯一幻灯片 | 演示文稿至少保留一页 | 先创建新页，再删除旧页 |
 | 1061002 媒体上传 params error | slides 媒体上传参数不符合约定 | 用 `slides +media-upload`，不要手拼原生 `medias/upload_all`；slides 唯一可用 `parent_type` 是 `slide_file` |
-| 1061004 forbidden | 当前身份对演示文稿无编辑权限 | 确认 user/bot 对目标 PPT 有编辑权限；bot 常见于 PPT 非该 bot 创建 |
+| 1061004 forbidden | 当前用户对演示文稿无编辑权限 | 确认当前用户对目标 PPT 有编辑权限 |
 | 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 replace 片段问题 | 优先检查未转义字符；replace 场景再看 `block_id` 和 `<content/>` |
 | 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新用 `slides +xml-get` 取最新 `revision_id` |
 | validation: unsafe file path | `--file` 给了绝对路径或上层路径 | `--file` 必须是 CWD 内相对路径；先 `cd` 到素材目录再执行 |
+
+## Command-Specific References
+
+- 图片上传、`@path` 占位符、`file_token`：见 [lark-slides-media-upload.md](lark-slides-media-upload.md) 和 [lark-slides-create.md](lark-slides-create.md)。
+- 块级替换、`block_id`、3350001 replace 细节：见 [lark-slides-replace-slide.md](lark-slides-replace-slide.md)。
+- 原生 `slide.create` 包装、`before_slide_id` 和 jq 模板：见 [lark-slides-xml-presentation-slide-create.md](lark-slides-xml-presentation-slide-create.md)。

skills/lark-slides/references/validation-checklist.md

@@ -27,16 +27,16 @@ lark-cli slides +xml-get --as user \
 
 ## Automated XML Text Overlap Lint
 
-提交前本地 XML 必须运行 XML 语法和文本重叠静态检查：
+`slides +xml-get` 保存 XML 到本地文件后，优先运行 XML 语法和文本重叠静态检查：
 
 ```bash
-python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentation-or-slide.xml>
+python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentation.xml>
 ```
 
 通过标准：
 
-- `summary.error_count == 0`。任何 error 都必须先修复再提交接口。
-- 当前工具检查 XML well-formed、SXSD tag/attr 支持情况、IconPark icon 类型和 icon 填充可见性、文本元素之间的明显重叠，以及 whiteboard 容器与外部 sibling 元素的可疑边界重叠；它不检查越界、文本高度不足、图文压盖、表格/图表压盖或底部拥挤。
+- `summary.error_count == 0`。任何 error 都必须先修复再交付。
+- 当前工具只检查 XML well-formed 和文本元素之间的明显重叠；它不检查越界、文本高度不足、图文压盖、表格/图表压盖或底部拥挤。
 - 该工具不能替代页数核对、关键内容核对或真实视觉验收。
 
 常见 code 的处理方向：
@@ -51,7 +51,35 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 | `icon_missing_fill_color` | 视觉规范要求 `<icon>` 设置 `<fill><fillColor color="..."/></fill>`，避免图标不可见 | 给 `<icon>` 添加显式非透明填充色，例如 `rgba(37, 99, 235, 1)` |
 | `icon_transparent_fill_color` | `<icon>` 的 `fillColor` 是透明色，不满足视觉可见性要求 | 改成与背景有足够对比的非透明颜色 |
 | `bbox_overlap` | 文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |
-| `whiteboard_external_overlap` | whiteboard 容器 bbox 与外部 sibling 元素跨边界重叠 | 按 lint `hint` 缩小或移动 whiteboard / 外部元素；若接受该风险，最终必须以截图 QA 或等价渲染视觉检查为准 |
+
+## Screenshot QA
+
+获取页面截图后，必须做视觉验收；不要只凭 XML 回读或静态 lint 结论声称截图验收通过。验收时假设页面存在问题，主动寻找并报告所有风险，包括轻微问题。
+
+```text
+请逐页目视检查这些幻灯片截图。先假设存在问题，并尽量找出它们。
+
+重点检查：
+- 元素重叠：文字与形状、图片或图表互相遮挡，线条穿过文字，卡片或标签堆叠。
+- 文本溢出或被裁切：靠近页面边缘、文本框边界或卡片边界处被截断。
+- 装饰元素位置错误：分割线、强调线或标签底板按单行文字布置，但标题或正文换行后压住文字或距离异常。
+- 来源标注、页脚或页码与上方内容碰撞。
+- 元素距离过近：相邻元素间距明显不足，卡片或分区几乎贴在一起；按 960x540 画布估算，小于约 15 px 的间隔通常要标记。
+- 间距不均：局部留白过大，另一处过于拥挤。
+- 页面边距不足：主体内容贴近幻灯片边缘；按 960x540 画布估算，小于约 30 px 的外边距通常要标记。
+- 列、卡片、图标或同类元素没有稳定对齐。
+- 图片或图表渲染异常：空白、变形、低清、关键内容不可读或预期图形缺失。
+- 文本对比度不足，例如浅灰文字放在米色或浅色背景上。
+- 图标对比度不足，例如深色图标放在深色背景上，且没有浅色圆形或底板承托。
+- 文本框过窄，导致不必要的频繁换行。
+- 残留占位符、模板默认文字或未替换内容。
+
+对每一页分别列出发现的问题或可疑区域，即使只是轻微问题也要记录。
+
+报告所有发现的问题，包括轻微问题。
+```
+
+必须根据问题严重度决定是否修复：空白页、破图、文字遮挡、明显裁切、低对比不可读、占位符残留等必须先修复再交付；轻微间距或对齐问题如果不修复，最终验证记录要说明已知风险。
 
 ## Page Count And Structure
 
@@ -85,14 +113,6 @@ 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`；lint 还会报告 whiteboard 容器与外部 sibling 元素的可疑边界重叠。
-- SVG 和 Mermaid 内容的正确性无法通过回读 XML 验证，需要人工视觉验收。
-- 不要在验证记录中声称 whiteboard 内容已验证，除非用户确认了视觉效果。
-
 ## Layout And Overflow Risk
 
 优先修复这些明显风险：

skills/lark-slides/references/visual-planning.md

@@ -7,27 +7,29 @@
 ## Core Rules
 
 - `layout_type` must change geometry: element positions, region sizes, alignment, and visual rhythm must differ across page types.
-- `visual_focus` determines the largest or highest-contrast region. It can be an image, diagram, metric, quote, table, or shape-based placeholder.
+- `visual_focus` determines the largest or highest-contrast region. It can be an image, diagram, metric, quote, or table.
 - `text_density` caps visible text:
   - `low`: title plus one short statement, or 1-3 labels.
   - `medium`: title plus 2-4 concise bullets or labeled regions.
   - `high`: use a table, columns, grouped labels, or annotations. Do not use one long bullet box.
 - Do not create a deck where every content page is title plus bullets. For 4 or more pages, use at least 4 different layout structures when the content allows.
-- Keep generous margins. Use `60-80` px outer margins on standard content pages unless a full-bleed image or cover treatment is intentional.
+- Keep safe outer margins around `40` px on standard content pages, and fill the content area densely with a card grid rather than leaving large empty space. Only go full-bleed for an intentional image or cover treatment.
 - Reserve vertical space for titles. A typical content title area is `y=36..90`; main content should usually start at `y>=110`.
 - Avoid crowding the bottom edge. Keep non-background content above `y=500` unless it is a footer.
-- Prefer fewer, larger objects over many small text boxes.
 - Keep backgrounds consistent with the deck's `visual_system.background_strategy`. Normal content pages should use the same base background unless there is a clear page-role reason to change.
 - Treat text fit as a layout constraint, not a cleanup step. If a text box is too small for the intended line count, shorten the text, split it, or allocate more space before creating XML.
+- Do not use `<shape>` to build pictorial visuals like mock photos or fake objects. Use the image generation tool instead.
+- Do not place a `rect` or `line` for dividing or decorative purposes directly under a `headline` or `title`.
+- Do not use section bands, horizontal bars, vertical bars, or page-edge strips.
 
 ## Background And Motif Consistency
 
 Decks can vary page backgrounds, but variation must be intentional and legible:
 
 - Pick one default background for ordinary content pages and reuse it exactly. Avoid near-identical drift such as several slightly different off-white values unless it encodes a clear section change.
-- Cover, section divider, emphasis, and conclusion pages may use a dark, image-led, or high-contrast background. They must still share the deck's primary color, motif, edge treatment, typography, or geometry.
+- Cover, section divider, emphasis, and conclusion pages may use a dark, image-led, or high-contrast background. They must still share the deck's primary color, motif, typography, or geometry.
 - If a cover uses a split composition, make the split visible in the background or layout. For example, reserve a darker text region and a related but distinct visual region instead of placing all elements on one flat field.
-- Reuse a small number of visual devices: side bar, card radius, node style, line weight, icon container, or footer treatment. Do not introduce a new decorative language on each page.
+- Reuse a small number of visual devices: card radius, node style, icon container, or footer treatment. Do not introduce a new decorative language on each page.
 - Insert background and motif shapes before content elements so they do not cover text, images, or diagrams.
 
 ## Text Fit Guardrails
@@ -38,11 +40,11 @@ Use these as conservative minimums on a 960 x 540 canvas. Increase height when u
 |----------|-------------------|----------------|
 | Caption, 1 line | 10-12 | 18 |
 | Caption, 2 lines | 10-12 | 30 |
-| Body, 1 line | 13-16 | 24 |
-| Body, 2 lines | 13-16 | 40 |
-| Body, 2 lines, bold | 15-18 | 48 |
-| Headline, 1 line | 24-32 | 42 |
-| Title, 2 lines | 34-44 | 110 |
+| Body, 1 line | 12-14 | 24 |
+| Body, 2 lines | 12-14 | 40 |
+| Body, 2 lines, bold | 12-14 | 48 |
+| Headline, 1 line | 20-28 | 42 |
+| Title, 2 lines | 28-36 | 110 |
 
 Additional rules:
 
@@ -62,11 +64,12 @@ Purpose: introduce the deck's point of view.
 Geometry:
 - Use one dominant title block, usually `x=70..120`, `y=150..250`, `width=700..820`.
 - Add one subtitle or context line, not a bullet list.
-- Optional visual focus can be a full-bleed background, large side image, accent band, or abstract shape motif.
-- If the cover has a right-side diagram, screenshot, or motif cluster, use a split layout: keep the title/subtitle region within the left or central text region, and reserve a separate visual region so labels and connectors do not cross the title.
+- Visual focus MUST be an `<img>`: a full-bleed background image or a large **full-height** side image (searched by the image search tool or generated by the image generation tool). Do NOT compose the cover visual from `<shape>` or `<icon>`.
+- If the cover has a large full-height side image, use a split layout: keep the title and subtitle in the text region on the opposite side, and reserve a separate visual region so the image does not overlap the title. Crop (size and place) the side image so it stays within its visual region and does not extend into the text region.
 - For split covers, make the background reinforce the composition, such as a darker text side and a related visual panel. Avoid one flat field where title and diagram compete for attention.
 - Keep source metadata to one short line where possible. If it wraps, shorten author lists or move details to notes.
 - The main title should be controlled, normally one or two lines. Do not let it occupy both the text region and the visual region.
+- Do not add a vertical accent bar, side rail, or decorative line/strip. 
 
 Text:
 - `low` only unless the user explicitly asks for detail.
@@ -78,7 +81,7 @@ Purpose: reset rhythm and mark a new chapter.
 Geometry:
 - Use a large section number, chapter label, or single centered claim.
 - Keep the page sparse. A divider is not a content page.
-- Visual focus can be one oversized number, a vertical accent bar, or a full-width band.
+- Visual focus can be one oversized number.
 
 Text:
 - Title plus one phrase. No bullets.
@@ -103,7 +106,7 @@ Purpose: let a visual establish context, with text explaining implication.
 Geometry:
 - Left visual region should occupy roughly `35-45%` of slide width, often full height or tall crop.
 - Right text region starts around `x=420` and should have a strong headline plus short support.
-- If no real image is available, create a shape-based placeholder visual that matches `asset_need`.
+- If no image is available, use the image generation tool to create an approximate image that matches `asset_need`.
 - For dense screenshots, paper figures, or product captures with small labels, allocate a larger visual region when possible: often `50-65%` of slide width or at least `320` px height.
 - Place screenshots in a deliberate frame or panel, and leave enough margin so axes, captions, and edge labels are not cropped by the slide boundary.
 
@@ -118,7 +121,7 @@ Purpose: lead with a message, then reinforce it with a visual.
 Geometry:
 - Left text region starts around `x=60..90`, width `400..460`.
 - Right visual region occupies roughly `35-45%` of slide width.
-- Align the image or placeholder with the main text block, not only with the title.
+- Align the image with the main text block, not only with the title.
 - For dense screenshots, paper figures, or product captures with small labels, increase the visual region and reduce text. A readable image is more valuable than a fully populated text column.
 
 Text:
@@ -130,8 +133,8 @@ Text:
 Purpose: make one metric or fact memorable.
 
 Geometry:
-- Reserve the largest object for the metric: font size often `64-110`, region at least `300 x 120`.
-- Set `autoFit="normal-auto-fit"` on the metric's `<content>` so an oversized number shrinks to fit its box instead of overflowing.
+- Reserve the largest object for the metric: font size often `40-52`.
+- MUST Set `wrap="true" autoFit="normal-auto-fit"` on the metric's `<content>` so an oversized number shrinks to fit its box.
 - Pair the number with one explanation and optional 2-3 small supporting labels.
 - Do not bury the number in a bullet list or small card.
 
@@ -169,7 +172,7 @@ Text:
 
 Purpose: explain components, dependencies, or system flow.
 
-Implementation: prefer Mermaid `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` as fallback.
+Implementation: use `<shape>` + `<line>`.
 
 Geometry:
 - Main visual area should be a diagram, not prose.
@@ -185,7 +188,7 @@ Text:
 
 Purpose: show operational steps, workflow, or cause-effect path.
 
-Implementation: prefer Mermaid `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` as fallback.
+Implementation: use `<shape>` + `<line>`.
 
 Geometry:
 - Use numbered steps connected by arrows or lines.
@@ -214,19 +217,19 @@ Purpose: close with decision, recommendation, or next action.
 
 Geometry:
 - Use one dominant closing statement or call to action.
-- Add up to 3 next-step cards, checklist items, or owner/date labels.
 - Visual focus should be the recommendation or action, not decorative filler.
+- When using a full-bleed background image, add a semi-transparent scrim between the image and the text so the text stays legible; verify contrast.
 
 Text:
 - Keep the final page easy to remember. Avoid recap overload.
-- Conclusion pages may mirror the cover background, but must clearly reuse the deck's motif or color roles so the ending feels intentional.
+- Conclusion pages may mirror the cover background.
 
 ## Screenshot And Paper Figure Pages
 
 When a page uses a real screenshot, chart, paper figure, or product capture:
 
 - Choose screenshot placement based on page role, not a fixed slide number. Method overview, evidence, comparison, and failure-analysis pages are common candidates; title, agenda, and conclusion pages usually are not.
-- Use the real asset only when it is readable at slide size. If the figure is too dense, crop to the relevant region, create a zoomed detail, or redraw the core message with native shapes.
+- Use the real asset only when it is readable at slide size. If the figure is too dense, crop to the relevant region, create a zoomed detail, or regenerate the core message with the image generation tool.
 - A screenshot should normally be the visual focus. Do not shrink it into a decorative thumbnail while surrounding it with dense text.
 - Pair the image with a small number of interpretive annotations that tell the audience what to notice.
 - Always include a short source caption when using external or paper-derived visuals.

skills/lark-slides/references/xml-format-guide.md

@@ -1,433 +0,0 @@
-# XML 格式指南
-
-本文档基于 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 整理，说明飞书 Slides XML Schema（SML 2.0）的核心结构和常用写法。
-
-## 基本结构
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
-  <title>演示文稿标题</title>
-  <slide>
-    <style>
-      <fill>
-        <fillColor color="rgb(245, 245, 245)"/>
-      </fill>
-    </style>
-    <data>
-      <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
-        <content textType="title">
-          <p>主标题</p>
-        </content>
-      </shape>
-    </data>
-    <note>
-      <content textType="body">
-        <p>这是演讲者备注。</p>
-      </content>
-    </note>
-  </slide>
-</presentation>
-```
-
-## 根元素
-
-### `<presentation>`
-
-协议标准写法应带命名空间 `http://www.larkoffice.com/sml/2.0`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证。
-
-**属性：**
-
-| 属性 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `width` | positiveInteger | 是 | 演示文稿宽度，如 `960` |
-| `height` | positiveInteger | 是 | 演示文稿高度，如 `540` |
-| `id` | string | 否 | 演示文稿标识 |
-
-**子元素：**
-
-| 元素 | 必需 | 说明 |
-|------|------|------|
-| `<title>` | 否 | 演示文稿标题 |
-| `<theme>` | 否 | 全局主题 |
-| `<slide>` | 是 | 幻灯片页面，至少 1 页，最多 100 页 |
-
-## 主题
-
-### `<theme>`
-
-`<theme>` 当前包含两部分：
-
-- `<background>`：演示文稿级背景填充
-- `<textStyles>`：主题文本样式集合
-
-`<textStyles>` 下可选子元素：
-
-- `<title>`
-- `<headline>`
-- `<sub-headline>`
-- `<body>`
-- `<caption>`
-
-这些元素定义的是主题默认样式，不是页面结构。常用属性：
-
-| 属性 | 说明 |
-|------|------|
-| `fontFamily` | 字体 |
-| `fontSize` | 字号 |
-| `fontColor` | 字体颜色 |
-
-## 幻灯片元素
-
-### `<slide>`
-
-单张幻灯片的结构比较严格。
-
-**属性：**
-
-| 属性 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `id` | string | 否 | 幻灯片标识 |
-
-**直接子元素只有：**
-
-| 元素 | 必需 | 说明 |
-|------|------|------|
-| `<style>` | 否 | 页面样式 |
-| `<data>` | 否 | 页面元素容器 |
-| `<note>` | 否 | 演讲者备注 |
-
-这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。
-
-## 文本内容模型
-
-### `<content>`
-
-实际页面文本通常通过 `<content>` 表达，常见位置有：
-
-- `shape` 内部
-- `table/td` 内部
-- `note` 内部
-
-**常用属性：**
-
-| 属性 | 说明 |
-|------|------|
-| `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
-| `verticalAlign` | 垂直对齐 |
-| `textAlign` | 水平对齐 |
-| `lineSpacing` | 行间距 |
-| `fontSize` | 字号 |
-| `fontFamily` | 字体 |
-| `color` | 字体颜色 |
-| `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 |
-| `wrap` | 是否自动换行 |
-
-**可包含的子元素：**
-
-- `<p>`
-- `<ul>`
-- `<ol>`
-
-### `<p>`
-
-`<p>` 是段落元素，可混排纯文本和内联标签：
-
-- `<br/>`
-- `<strong>`
-- `<em>`
-- `<u>`
-- `<span>`
-- `<del>`
-- `<a>`
-- `<shadow>`
-- `<outline>`
-
-示例：
-
-```xml
-<content textType="body" textAlign="left">
-  <p>普通文本 <strong>加粗</strong> <em>斜体</em> <a href="https://example.com">链接</a></p>
-  <ul>
-    <li><p>列表项 1</p></li>
-    <li><p>列表项 2</p></li>
-  </ul>
-</content>
-```
-
-## 常用页面元素
-
-所有页面元素都放在 `<data>` 中。
-
-### `<shape>`
-
-`shape` 可表示普通形状，也可表示文本框。文本框推荐使用 `type="text"`。
-
-```xml
-<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
-  <content textType="title">
-    <p>主标题</p>
-  </content>
-</shape>
-```
-
-```xml
-<shape type="rect" topLeftX="700" topLeftY="120" width="180" height="120">
-  <fill>
-    <fillColor color="rgba(100, 149, 237, 0.25)"/>
-  </fill>
-  <border color="rgb(100, 149, 237)" width="2"/>
-</shape>
-```
-
-**属性：**
-
-| 属性 | 必需 | 说明 |
-|------|------|------|
-| `type` | 是 | 形状类型，`text` 表示文本框 |
-| `topLeftX` | 是 | 左上角 X 坐标 |
-| `topLeftY` | 是 | 左上角 Y 坐标 |
-| `width` | 是 | 宽度 |
-| `height` | 是 | 高度 |
-| `rotation` | 否 | 旋转角度 |
-| `flipX` / `flipY` | 否 | 翻转 |
-| `alpha` | 否 | 透明度 |
-
-**可选子元素：**
-
-- `<fill>`
-- `<border>`
-- `<reflection>`
-- `<shadow>`
-- `<content>`
-
-### `<line>`
-
-```xml
-<line startX="100" startY="200" endX="420" endY="200">
-  <border color="rgb(43, 47, 54)" width="2"/>
-</line>
-```
-
-`line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。
-
-### `<img>`
-
-```xml
-<img src="file_token_or_url" topLeftX="100" topLeftY="220" width="320" height="180"/>
-```
-
-`img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
-
-`src` 只接受两种值：
-
-| `src` 形式 | 说明 |
-|---|---|
-| `file_token`（如 `boxcnXXXXXXXXXXXXXXXXXXXXXX`） | 通过 `slides +media-upload` 上传后返回的 token |
-| `@<本地路径>`（如 `@./assets/chart.png`） | **仅在 `slides +create --slides` 中可用**：CLI 会自动上传该文件并替换为 file_token |
-
-> **禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，`src="https://..."` 在 PPT 里通常显示破图。要用网图必须先 `curl`/下载到 CWD 内，再走上传流程拿 `file_token`。
-
-本地图片的两种姿势：
-
-- **新建带图 PPT**：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token
-- **给已有 PPT 加带图新页**：先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token，再用 token 写进 `xml_presentation.slide create` 的 XML
-
-### `<icon>`
-
-```xml
-<icon iconType="iconpark/Base/setting.svg" topLeftX="440" topLeftY="220" width="32" height="32"/>
-```
-
-### `<table>`
-
-表格结构为：
-
-- `<table>`
-- `<colgroup>` / `<tr>`
-- `<tr>` 内为 `<td>`
-- `<td>` 内可放 `<content>`
-
-`<table>` 可选设置 `width` 和 `height`，分别表示表格的目标总宽度和总高度：
-
-```xml
-<table topLeftX="80" topLeftY="120" width="800" height="300">
-  <colgroup>
-    <col width="240"/>
-    <col/>
-  </colgroup>
-  <tr height="80">
-    <td><content textType="body"><p>表头 1</p></content></td>
-    <td><content textType="body"><p>表头 2</p></content></td>
-  </tr>
-</table>
-```
-
-### `<chart>`
-
-图表元素必须至少包含：
-
-- `<chartPlotArea>`
-- `<chartData>`
-
-同时还可以包含：
-
-- `<chartTitle>`
-- `<chartSubTitle>`
-- `<chartStyle>`
-- `<chartLegend>`
-- `<chartTooltip>`
-
-完整图表类型覆盖示例见 [slides_chart_demo.xml](slides_chart_demo.xml)，其中包含柱状、条形、折线、面积、饼 / 环、雷达等原生 `<chart>` 示例，以及散点、气泡、漏斗、帕累托、瀑布等 `<whiteboard>` SVG 图表示例。
-
-组合图示例（来自 [slides_chart_demo.xml](slides_chart_demo.xml)）：
-
-```xml
-<chart width="556" height="350" topLeftX="42" topLeftY="132">
-  <chartPlotArea>
-    <chartPlot type="combo">
-      <chartExtra/>
-      <chartSeriesList>
-        <chartSeries index="1" comboType="column"/>
-        <chartSeries index="2" comboType="line" yAxisPosition="right">
-          <chartTooltip format="0%"/>
-        </chartSeries>
-      </chartSeriesList>
-    </chartPlot>
-    <chartAxes>
-      <chartAxis type="x">
-        <chartLabel fontSize="10"/>
-      </chartAxis>
-      <chartAxis type="y" position="left">
-        <chartGridLine color="rgb(226, 232, 240)"/>
-        <chartLabel fontSize="10"/>
-      </chartAxis>
-      <chartAxis type="y" position="right">
-        <chartLabel fontSize="10" format="0%"/>
-      </chartAxis>
-    </chartAxes>
-  </chartPlotArea>
-  <chartLegend position="bottom" fontSize="11"/>
-  <chartData>
-    <dim1>
-      <chartField name="季度">24Q1,24Q2,24Q3,24Q4,25Q1,25Q2,25Q3,25Q4</chartField>
-    </dim1>
-    <dim2>
-      <chartField name="营收">180,195,210,245,220,238,258,296</chartField>
-      <chartField name="增速">0.08,0.12,0.15,0.18,0.22,0.22,0.23,0.21</chartField>
-    </dim2>
-  </chartData>
-  <chartTitle fontSize="12" color="rgba(15, 30, 58, 1)" bold="true">营收（亿美元, 左轴） · 同比增速（%, 右轴）</chartTitle>
-  <chartStyle>
-    <chartBackground color="rgba(0, 0, 0, 0)"/>
-    <chartBorder color="rgb(222, 224, 227)" width="0"/>
-    <chartColorTheme>
-      <color value="rgb(28, 71, 120)"/>
-      <color value="rgb(240, 129, 54)"/>
-    </chartColorTheme>
-  </chartStyle>
-</chart>
-```
-
-## 样式元素
-
-### `<fill>`
-
-```xml
-<fill>
-  <fillColor color="rgb(100, 149, 237)"/>
-</fill>
-```
-
-### `<border>`
-
-```xml
-<border color="rgb(0, 0, 0)" width="2" dashArray="solid"/>
-```
-
-### 颜色格式
-
-```xml
-<fillColor color="rgb(255, 0, 0)"/>
-<fillColor color="rgba(255, 0, 0, 0.5)"/>
-<fillColor color="linear-gradient(90deg, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
-<fillColor color="radial-gradient(circle at 50% 50%, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
-```
-
-## 演讲者备注
-
-### `<note>`
-
-```xml
-<note>
-  <content textType="body">
-    <p>这是演讲者备注内容。</p>
-  </content>
-</note>
-```
-
-## 完整示例
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
-  <title>季度报告</title>
-  <theme>
-    <textStyles>
-      <title fontFamily="思源黑体" fontSize="54" fontColor="rgba(0, 0, 0, 1)"/>
-      <body fontFamily="思源黑体" fontSize="18" fontColor="rgba(43, 47, 54, 1)"/>
-    </textStyles>
-  </theme>
-  <slide>
-    <style>
-      <fill>
-        <fillColor color="rgb(245, 245, 245)"/>
-      </fill>
-    </style>
-    <data>
-      <shape type="text" topLeftX="80" topLeftY="72" width="760" height="100">
-        <content textType="title">
-          <p>2024 年第一季度报告</p>
-        </content>
-      </shape>
-      <shape type="text" topLeftX="80" topLeftY="200" width="520" height="180">
-        <content textType="body">
-          <p>核心指标</p>
-          <ul>
-            <li><p>用户增长：+25%</p></li>
-            <li><p>收入增长：+30%</p></li>
-            <li><p>市场份额：15%</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>
-</presentation>
-```
-
-## 最佳实践
-
-1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"`
-2. 用 `shape type="text"` + `content` 表达页面文本
-3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名
-4. 优先使用 `rgb` / `rgba` 颜色格式
-5. 特殊字符按 XML 规则转义
-6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"`
-
-## 参考文档
-
-- [xml-schema-quick-ref.md](xml-schema-quick-ref.md)
-- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)
-- [examples.md](examples.md)
-- [slides_demo.xml](slides_demo.xml)

skills/lark-slides/references/xml-schema-quick-ref.md

@@ -1,6 +1,6 @@
 # XML Schema 快速参考
 
-本文档是 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 的精简版摘要；如果两者不一致，以 XSD 原文为准。
+本文档是 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 的精简版摘要，并合并了常用 XML 格式写法；如果两者不一致，以 XSD 原文为准。
 
 ## 最重要的规则
 
@@ -30,25 +30,31 @@
 
 | 属性 | 必需 | 说明 |
 |------|------|------|
-| `width` | 是 | 演示文稿宽度，正整数 |
-| `height` | 是 | 演示文稿高度，正整数 |
+| `width` | 是 | 演示文稿宽度，正整数，标准 16:9 页面建议使用 `960` |
+| `height` | 是 | 演示文稿高度，正整数，标准 16:9 页面建议使用 `540` |
 | `id` | 否 | 演示文稿标识 |
 
 **子元素：** `<title>?`, `<theme>?`, `<slide>+`
 
-## slide 元素
-
-| 属性 | 必需 | 说明 |
-|------|------|------|
-| `id` | 否 | 幻灯片标识 |
-
-**子元素：**
-- `<style>?` - 页面样式，目前可放 `<fill>`
-- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`whiteboard`、`undefined`
-- `<note>?` - 演讲者备注，内部可放 `<content>`
+`<slide>` 至少 1 页，最多 100 页。
 
 ## theme 与文本类型
 
+`<theme>` 当前包含两部分：
+
+- `<background>`：演示文稿级背景填充
+- `<textStyles>`：主题文本样式集合
+
+`<textStyles>` 下可选子元素包括 `<title>`、`<headline>`、`<sub-headline>`、`<body>`、`<caption>`。这些元素定义的是主题默认样式，不是页面结构。
+
+常用属性：
+
+| 属性 | 说明 |
+|------|------|
+| `fontFamily` | 字体 |
+| `fontSize` | 字号 |
+| `fontColor` | 字体颜色 |
+
 XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出现在：
 
 - `<theme><textStyles>...</textStyles></theme>` 中，作为主题文本样式
@@ -64,6 +70,22 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | `body` | 16 |
 | `caption` | 12 |
 
+默认字号是省略 `fontSize` 时的兜底字号，不是推荐值。字号必须显式设置 `<content>` 的 `fontSize` 属性，不要依赖 `textType` 的默认字号兜底，这些兜底值明显偏大。
+
+## slide 元素
+
+| 属性 | 必需 | 说明 |
+|------|------|------|
+| `id` | 否 | 幻灯片标识 |
+
+**子元素：**
+
+- `<style>?` - 页面样式，目前可放 `<fill>`
+- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`undefined`
+- `<note>?` - 演讲者备注，内部可放 `<content>`
+
+这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。
+
 ## content 内容模型
 
 `<content>` 可出现在 `shape`、`table/td`、`note` 中，常用属性包括：
@@ -71,20 +93,44 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | 属性 | 说明 |
 |------|------|
 | `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
+| `verticalAlign` | 垂直对齐 |
 | `textAlign` | 文本对齐方式 |
 | `lineSpacing` | 行间距，schema 默认 `multiple:1.5` |
 | `fontSize` | 字号 |
 | `fontFamily` | 字体 |
 | `color` | 字体颜色 |
-| `bold` / `italic` / `underline` / `strikethrough` | 文本样式 |
+| `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 |
+| `wrap` | 是否自动换行 |
+| `autoFit` | 是否自动缩排 |
 
-`<content>` 的子元素只能是：
+注意事项：
+
+- 字号必须显式设置 `<content>` 的 `fontSize` 属性，不要依赖 `textType` 的默认字号兜底，这些兜底值明显偏大。
+- 大数字、字号大或字数多的 `<content>` 必须设置 `wrap="true" autoFit="normal-auto-fit"` 属性自动换行和缩排，避免文字溢出。
+- 文字颜色必须用 `<content>` 的 `color` 属性而不是 `fontColor` 属性。
+- 文字行间距必须设置 `<content>` 的 `lineSpacing="multiple:xx"` 或 `lineSpacing="fixed:xx"` 而不是 `lineSpacing="xx"`。
+
+`<content>` 直接子元素只有：
 
 - `<p>`
 - `<ul>`
 - `<ol>`
 
-### content 示例
+### p 段落与内联标签
+
+`<p>` 是段落元素，可混排纯文本和内联标签：
+
+- `<br/>`
+- `<strong>`
+- `<em>`
+- `<u>`
+- `<span>`
+- `<del>`
+- `<a>`
+- `<shadow>`
+- `<outline>`
+
+示例：
 
 ```xml
 <content textType="body" textAlign="left">
@@ -98,8 +144,20 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 ## data 常用元素
 
+所有页面元素都放在 `<data>` 中。
+
 ### shape
 
+`shape` 可表示普通形状，也可表示文本框。文本框推荐使用 `type="text"`。
+
+```xml
+<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+  <content textType="title">
+    <p>主标题</p>
+  </content>
+</shape>
+```
+
 ```xml
 <shape type="rect" topLeftX="120" topLeftY="120" width="240" height="120">
   <fill>
@@ -108,6 +166,8 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
   <border color="rgb(0, 0, 0)" width="2"/>
 </shape>
 ```
+`<shape type="rect">` 只是形状不是容器，`<icon>`、`<img>`、`<shape type="text">` 和其他 `<shape>` 必须与它平级靠坐标叠放。
+
 
 | 属性 | 必需 | 说明 |
 |------|------|------|
@@ -117,6 +177,16 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | `width` | 是 | 宽度 |
 | `height` | 是 | 高度 |
 | `rotation` | 否 | 旋转角度 |
+| `flipX` / `flipY` | 否 | 翻转 |
+| `alpha` | 否 | 透明度 |
+
+可选子元素：
+
+- `<fill>`
+- `<border>`
+- `<reflection>`
+- `<shadow>`
+- `<content>`
 
 ### line
 
@@ -126,55 +196,107 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 </line>
 ```
 
+`line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。
+
 ### img
 
 ```xml
 <img src="file_token_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>
 ```
 
+`img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
+
 `src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（仅 `+create --slides` 自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
 
+本地图片的两种姿势：
+
+- 新建带图 PPT：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token
+- 给已有 PPT 加带图新页：先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token，再用 token 写进 `xml_presentation.slide create` 的 XML
+
 > **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。
 
 ### icon
 
 ```xml
-<icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="120" width="32" height="32">
+<icon iconType="iconpark/Charts/chart-line.svg" topLeftX="80" topLeftY="120" width="32" height="32">
   <fill>
     <fillColor color="rgba(37, 99, 235, 1)"/>
   </fill>
 </icon>
 ```
 
-`iconType` 必须来自已验证的 IconPark 路径；视觉 lint 规范要求 `fillColor` 显式设置为非透明颜色，避免图标不可见。需要语义图标时，先运行 `scripts/iconpark_tool.py search --query "<语义>"`，不要凭记忆拼路径。更多规则见 [iconpark.md](iconpark.md)。
+图标必须填充颜色并和背景有足够对比。
 
-### whiteboard
+禁止盲猜 iconType，必须先检索 IconPark，再写 `<icon iconType="...">`。检索方式和更多规则见 [iconpark.md](iconpark.md)。
+
+
+### table
+
+表格结构为：
+
+- `<table>` 直接子元素只有 `<colgroup>` 和 `<tr>`，`width` 和 `height` 分别表示表格的目标总宽度和总高度。
+- `<colgroup>` 直接子元素只有 `<col width="...">`，width 定义列宽，默认 110。
+- `<tr height="...">` 直接子元素只有 `<td>`，height 定义行高，默认 37。
+- `<td>` 直接子元素只有 `<fill>`（背景）、`<content>`（文字）和边框配置（一般不用），不能嵌套 `<shape>`、`<img>`、`<icon>`。
+
+表头默认的白底白字视觉效果极差，必须设置背景和文字颜色，需在首行每个 `<td>` 上加 `<fill>`（配合 `bold` 与对比文字色）与正文行区分。
+
+表格里的文字默认是居中对齐，可以设置 `textAlign` 调整对齐方式。
+
+表格宽高设置：
+
+- 已设置的列宽和行高优先保留，未设置的列宽、行高会使用表格的目标总宽度、总高度分配剩余空间
+- **必须设置 `<table>` 的 `width` 和 `height` 固定表格大小，同时设置需要保留列宽或行高的 `<col>` 的 `width` 和 `<tr>` 的 `height`，其余自动分配。**
+
+不同字号的行高参考：
+
+| `fontSize` | 内容行数 | 紧凑 `height` | 适中 `height` | 宽松 `height` |
+|------|------|------|------|------|
+| 10 | 单行 | 16 | 20 | 24 |
+| 12 | 单行 | 20 | 24 | 28 |
+| 10 | 双行 | 32 | 36 | 42 |
+| 12 | 双行 | 36 | 42 | 48 |
+
+示例：
 
 ```xml
-<!-- SVG 模式：<chart> 不支持的图表或自定义视觉、装饰元素 -->
-<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>
+<table topLeftX="80" topLeftY="140" width="520" height="52">
+  <colgroup>
+    <col width="160"/>
+    <col width="120"/>
+    <col />
+  </colgroup>
+  <tr height="28">
+    <td>
+      <fill><fillColor color="rgba(30,60,114,1)"/></fill>
+      <content textType="body" fontSize="12" bold="true" color="rgba(255,255,255,1)" textAlign="center"><p>项目</p></content>
+    </td>
+    <td>
+      <fill><fillColor color="rgba(30,60,114,1)"/></fill>
+      <content textType="body" fontSize="12" bold="true" color="rgba(255,255,255,1)" textAlign="right"><p>营收</p></content>
+    </td>
+    <td>
+      <fill><fillColor color="rgba(30,60,114,1)"/></fill>
+      <content textType="body" fontSize="12" bold="true" color="rgba(255,255,255,1)" textAlign="left"><p>备注说明</p></content>
+    </td>
+  </tr>
+  <tr>
+    <td><content textType="body" fontSize="10" textAlign="center"><p>线上业务</p></content></td>
+    <td><content textType="body" fontSize="10" textAlign="right"><p>195</p></content></td>
+    <td><content textType="body" fontSize="10" textAlign="left"><p>同比增长 8%，主要来自新客</p></content></td>
+  </tr>
+</table>
 ```
 
-SVG 模式：`<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`，内容大小由子元素包围盒决定；`width`/`height`/`viewBox` 不影响渲染，仅当元素使用百分比属性值时需声明 `viewBox`。\
-Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->` 等字符破坏 XML 解析。\
-详细用法见 [lark-slides-whiteboard.md](lark-slides-whiteboard.md)。
+### chart
+
+图表语法十分复杂，必须阅读 [slides_chart_demo.xml](slides_chart_demo.xml)，直接照抄其中的柱状、条形、折线、面积、饼（环）、雷达、组合图。
+
+`<chart>` 直接子元素必须有 `<chartPlotArea>`（绘图区）和 `<chartData>`（数据）；`<chartTitle>`、`<chartSubTitle>`、`<chartStyle>`、`<chartLegend>`、`<chartTooltip>` 可选，如果想不展示标题、副标题、图例或悬浮提示，省略相应元素标签即可。
+
+隐藏 `<chart>` 的图例只能通过不写或删除 `<chartLegend>` 实现，`<chartLegend>` 不支持 `position="none"`。
+
+详细用法见 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
 
 ## 颜色与样式
 
@@ -235,12 +357,69 @@ Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->`
 </note>
 ```
 
+## 完整示例
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+  <title>季度报告</title>
+  <theme>
+    <textStyles>
+      <title fontFamily="思源黑体" fontSize="54" fontColor="rgba(0, 0, 0, 1)"/>
+      <body fontFamily="思源黑体" fontSize="18" fontColor="rgba(43, 47, 54, 1)"/>
+    </textStyles>
+  </theme>
+  <slide>
+    <style>
+      <fill>
+        <fillColor color="rgb(245, 245, 245)"/>
+      </fill>
+    </style>
+    <data>
+      <shape type="text" topLeftX="80" topLeftY="72" width="760" height="100">
+        <content textType="title">
+          <p>2024 年第一季度报告</p>
+        </content>
+      </shape>
+      <shape type="text" topLeftX="80" topLeftY="200" width="520" height="180">
+        <content textType="body">
+          <p>核心指标</p>
+          <ul>
+            <li><p>用户增长：+25%</p></li>
+            <li><p>收入增长：+30%</p></li>
+            <li><p>市场份额：15%</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>
+</presentation>
+```
+
+## 最佳实践
+
+1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"`
+2. 用 `shape type="text"` + `content` 表达页面文本
+3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名
+4. 优先使用 `rgb` / `rgba` 颜色格式；渐变必须使用 `rgba()` 且带百分比停靠点
+5. 特殊字符按 XML 规则转义
+6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"`
+
 ## 详细参考
 
 - [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)
-- [xml-format-guide.md](xml-format-guide.md)
-- [examples.md](examples.md)
-- [slides_demo.xml](slides_demo.xml)
+- [slides_chart_demo.xml](slides_chart_demo.xml)
 
 ## Schema 版本信息