docs: add slides timeline demo reference

skills/lark-slides/SKILL.md

@@ -4,7 +4,7 @@ version: 1.0.0
 description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。"
 metadata:
   requires:
-    bins: ["lark-cli"]
+    bins: [ "lark-cli" ]
   cliHelp: "lark-cli slides --help"
 ---
 
@@ -12,198 +12,36 @@ metadata:
 
 ## Quick Reference
 
-| 用户需求 | 优先动作 | 关键文档 / 命令 |
-|----------|----------|-----------------|
-| 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
-| 已有 PPT 大幅改写 | 多页整页重建用 `+replace-pages`，单页局部编辑用 `+replace-slide` | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` |
-| 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
-| 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` |
-| 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面 | `slides +screenshot`、`lark-slides-screenshot.md` |
-| 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 |
-| 在 slide 中绘制柱/条/折线/面积/雷达/饼等有数据序列的图表 | 使用原生 `<chart>` 元素 | `xml-schema-quick-ref.md` |
-| 在 slide 中绘制流程图、时序图、架构图、散点图、漏斗图或装饰图案 | 必须先用 Read 工具读取参考文档，再生成 `<whiteboard>` 元素 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) |
-| 使用语义图标 | 先检索 IconPark，再写 `<icon iconType="...">` | `iconpark_tool.py search → resolve`、`iconpark.md` |
-| 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
+| 用户需求 | 指引 |
+|----------|------|
+| 读取 / 分析本地 PPTX 内容 | 文本用 `python -m markitdown presentation.pptx`；视觉总览用 `python3 scripts/thumbnail.py presentation.pptx`；原始 OOXML 用 `python3 scripts/office/unpack.py presentation.pptx unpacked/` |
+| 从模板创建或编辑已有本地 PPTX | 先读 `lark-slides-pptx-template-workflows.md` |
+| 从零新建飞书在线 PPT | 先读 `lark-slides-create-workflows.md` |
+| 获取在线 slides 内容、读取 / 分析已有在线 PPT | XML 内容优先用 `slides +xml-get` 保存到文件；页面视觉内容用 `slides +screenshot`，详见 `lark-slides-screenshot.md` |
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。**
+## 读取 / 分析内容
 
-**CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
-
-**CRITICAL — PPT 生成与模板编辑硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。多用生图，辅助搜图，必须要图文并茂。不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。生成背景图时必须在 prompt 中明确要求不要出现任何文字。用户指定 PPT 模板时，用 lark-drive 技能导入成 lark slides，回读理解每页版式后，直接在该 slides 上编辑，可以填改文字和图片、按需增删模板页，必须严格沿用原版式和字体，只改内容不做设计，完成后回读并微调，凝练文字或缩减字号消除文字溢出，调整 shape 顺序或位置避免文字遮挡。**
-
-**CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。**
-
-**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)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。**
-
-**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)。
-
-## 身份选择
-
-飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。
-
-- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权：
+### 在线 Slides
 
 ```bash
-lark-cli auth login --domain slides
+# 读取完整 XML 内容，优先保存到文件再分析
+lark-cli slides +xml-get --as user --presentation slides_example_presentation_id --output presentation.xml --json
+
+# 获取页面截图；必须指定 --slide-number 或 --slide-id，多个页面可重复传 --slide-number
+lark-cli slides +screenshot --as user --presentation slides_example_presentation_id --slide-number 1 --output-dir screenshots --json
 ```
 
-- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。
+在线 Slides 的截图参数和页码语义详见 [`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)；需要继续编辑在线 Slides 时，按 `lark-slides-create-workflows.md` / `lark-slides-replace-workflows.md` 选择创建或替换流程。
 
-**执行规则**：
+## 编辑 PPTX 工作流
 
-1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。
-2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。
-3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。
+**完整流程先读 [`lark-slides-pptx-template-workflows.md`](references/lark-slides-pptx-template-workflows.md)。**
 
-## 执行前必做
+## 从零创建
 
-> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。
+**完整流程先读 [`lark-slides-create-workflows.md`](references/lark-slides-create-workflows.md)。**
 
-高频只读：
-
-- [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)
-- [planning-layer.md](references/planning-layer.md)（新建 / 大幅改写）
-- [visual-planning.md](references/visual-planning.md)（新建 / 大幅改写）
-- [asset-planning.md](references/asset-planning.md)（新建 / 大幅改写）
-- [validation-checklist.md](references/validation-checklist.md)（创建 / 大幅改写后）
-
-按需再读：
-
-- 创建：[`lark-slides-create.md`](references/lark-slides-create.md)
-- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-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)
-- 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md)
-- 图标：[`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 是独立的视觉画面，信息密度要低，排版要留白。
-
-### Design Ideas
-
-不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。
-
-开始写 XML 前，先在 `slide_plan.json` 里确定 deck 级视觉策略：
-
-- **主题化配色**：配色必须服务本次主题、行业和受众，不要默认蓝色商务风。如果把同一套颜色换到另一个完全不同主题仍然成立，说明配色不够具体。
-- **主次比例**：选择 1 个主色承担约 60-70% 视觉权重，1-2 个辅助色承担结构和分区，1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。
-- **背景一致性**：先确定全 deck 的背景策略，默认保持同一明暗基调和底色体系；只有分节、转场或强调页才有意改变背景，并必须通过相同主色、纹理、边栏或 motif 让变化看起来属于同一套设计。无论深浅，都要保证正文、图标和线条对比充足。
-- **统一 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 视觉。
-- 不要留下占位文案、示例公司名、示例日期或与用户主题无关的内容。
-
-### 创建方式选择
-
-| 场景 | 推荐方式 |
-|------|----------|
-| 简单 XML（1-3 页、结构简单、几乎无复杂中文和特殊字符） | `slides +create --slides '[...]'` 一步创建 |
-| 复杂 XML（多页、含中文、大段文本、复杂布局、嵌套引号、特殊字符较多） | **两步创建**：先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide create` 逐页添加 |
-| 已有 PPT 继续追加或插入页面 | 使用 `xml_presentation.slide create`，必要时配合 `before_slide_id` |
-
-> [!WARNING]
-> `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议使用两步创建法。
-
-> [!IMPORTANT]
-> `slides +create --slides` 底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。
-
-```text
-Step 1: 需求澄清 & 读取知识
-  - 澄清主题、受众、页数、风格
-  - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md
-
-Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json
-  - 生成结构化大纲供用户确认
-  - 新建 / 大幅改写必须先创建目录并写入 `.lark-slides/plan/<deck-or-task-id>/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、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
-
-Step 4: 审查 & 交付
-  - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
-  - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
-  - 没问题 → 交付：告知用户演示文稿 ID 和访问方式
-```
-
-### jq 命令模板（编辑已有 PPT 时使用）
-
-新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
-
-```bash
-# 追加到末尾
-lark-cli slides xml_presentation.slide create \
-  --as user \
-  --params '{"xml_presentation_id":"YOUR_ID"}' \
-  --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、whiteboard 等元素
-  </data>
-</slide>' '{slide:{content:$content}}')"
-
-# 插到指定页之前：before_slide_id 必须在 --data body 里，与 slide 同级
-# ⚠️ 不要把 before_slide_id 写进 --params —— CLI 会当未知 query 参数静默下发，服务端忽略，新页跑到末尾
-lark-cli slides xml_presentation.slide create \
-  --as user \
-  --params '{"xml_presentation_id":"YOUR_ID"}' \
-  --data "$(jq -n --arg content '<slide ...>...</slide>' --arg before 'TARGET_SLIDE_ID' \
-    '{slide:{content:$content}, before_slide_id:$before}')"
-```
-
-> 渐变色必须使用 `rgba()` 格式并带百分比停靠点，如 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端回退为白色。
-
-### 大纲模板
-
-生成大纲时使用以下格式，交给用户确认：
-
-```text
-[PPT 标题] — [定位描述]，面向 [目标受众]
-
-页面结构（N 页）：
-1. 封面页：[标题文案]
-2. [页面主题]：[要点1]、[要点2]、[要点3]
-3. [页面主题]：[要点描述]
-...
-N. 结尾页：[结尾文案]
-
-风格：[配色方案]，[排版风格]
-```
+当没有本地 PPTX 模板 / 参考演示文稿，或目标是新建飞书 / Lark 在线 Slides 而不是本地 `.pptx` 文件时，使用该流程。
 
 ## 核心概念
 
@@ -240,35 +78,343 @@ Slides (演示文稿)
     └── slide_id (页面唯一标识)
 ```
 
-## Shortcuts 与 API
+## 身份选择
 
-Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。
 
-| Shortcut | 说明 |
-|----------|------|
-| [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `<img src="@./local.png">` 占位符自动上传） |
-| [`+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 的多页大改，不新建链接 |
-
-没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
+- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权：
 
 ```bash
-lark-cli schema slides.<resource>.<method>   # 调用 API 前必须先查看参数结构
-lark-cli slides <resource> <method> [flags] # 调用 API
+lark-cli auth login --domain slides
 ```
 
-> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。
 
-## 核心规则
+**执行规则**：
 
-1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`；风格和大纲只能作为规划输入，不能绕过规划层
-2. **创建流程**：简单短 XML（1-3 页、结构简单、特殊字符少）可用 `slides +create --slides '[...]'` 一步创建；复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符，或超过 10 页时，默认先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
-3. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
-4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
-5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
-6. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
-7. **编辑已有页面优先原链接更新**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；已有 Slides 的多页整页重建用 `+replace-pages`，不要用 `slides +create` 新建整份 PPT；只有没有 shortcut 覆盖的特殊单页整页操作才手动 `slide.create` + `slide.delete`
-8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
+1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。
+2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。
+3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。
 
-> **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。
+## 设计思路
+
+你要以顶级 PPT 设计专家的标准工作：先判断内容、受众、场景和叙事目标，再设计信息层级、视觉系统、版式、字体、配色和图文关系；不要只把内容排进页面，而要让每一页都像可交付的专业演示稿。
+
+### 内容先行
+
+- 每页只服务一个核心观点。内容页标题应写成带判断的结论句，而不是主题标签；读者只看标题就能知道这一页要证明什么。
+- 先判断这一页要完成的任务：提出判断、证明判断、比较选项、解释流程、展示阶段、呈现数据、建立情绪，或完成过渡。页面结构必须服务这个任务。
+- 受众和交付方式决定密度：演讲型 deck 更适合少字、强节奏、分步呈现；自读型 deck 必须在没有讲解和点击的情况下完整可读。
+- 并列观点要互不重叠、没有明显缺口，通常控制在 3-5 个，最多不要超过 7 个；排序只选一种逻辑：时间、结构或重要性。
+- 封面、章节页、内容页、结尾页承担不同任务。章节页只做过渡，不承载多点论证；短 deck 不要机械加入 agenda、Q&A 或多个收尾页。
+- 数据页必须先写清 takeaway，再选择图表或数字呈现方式。不要把图表标题写成指标名，而要写成图表证明的结论。
+
+### Visual Planning：从 `slide_plan` 到 XML 几何
+
+新建演示文稿或大幅改写页面时，在 `slide_plan.json` 完成后、生成 XML 前，必须把 `layout_type`、`visual_focus`、`text_density` 落到真实页面几何里。默认按 `960 x 540` 画布规划；已有页面回读 XML 可以影响坐标，但不能覆盖这些原则：页面要有主视觉区域，文本要受密度约束，不同 `layout_type` 必须产生明显不同的坐标结构。
+
+- `layout_type` 必须改变几何：元素位置、区域大小、对齐方式和视觉节奏都要随页面类型变化。去掉 plan 里的 `layout_type` 标签后，页面仍应能被辨认为对应结构。
+- `visual_focus` 决定页面最大或最高对比区域，可以是图片、图表、指标、引语、表格、diagram，或与 `asset_need` 匹配的 shape placeholder。
+- `text_density` 限制可见文本量：`low` 只放标题 + 一句短陈述，或 1-3 个标签；`medium` 放标题 + 2-4 个短 bullet 或标注区域；`high` 用表格、分栏、分组标签或 annotation，不能退化成一个长 bullet 框。
+- 4 页及以上的 deck，在内容允许时至少使用 4 种不同布局结构；不要让所有内容页都是标题 + bullets。
+- 标准内容页外边距通常保持 `60-80` px。标题区一般是 `y=36..90`，主内容通常从 `y>=110` 开始；非背景内容不要挤到 `y>500`，除非它是页脚。
+- 优先使用更少、更大的对象，而不是许多细碎文本框。文字适配是布局约束，不是事后清理：文本框太小时，先删减、拆分或增加空间，再生成 XML。
+- 普通内容页默认复用同一个基础背景；封面、章节、强调和结论页可以变化，但必须共享主色、母题、边缘处理、字体或几何语言。背景和母题形状要先于内容元素插入，避免盖住文字、图片或 diagram。
+
+文字框高度按保守下限规划，中文、加粗、中英混排或较大行距都要增加高度：
+
+| 文本用途 | 常见字号 | 最小高度 |
+|----------|----------|----------|
+| Caption，1 行 | 10-12 | 18 |
+| Caption，2 行 | 10-12 | 30 |
+| Body，1 行 | 13-16 | 24 |
+| Body，2 行 | 13-16 | 40 |
+| Body，2 行加粗 | 15-18 | 48 |
+| Headline，1 行 | 24-32 | 42 |
+| Title，2 行 | 34-44 | 110 |
+
+- 不要把长中文句子或长英文短语放进 `height=18` 或 `height=22` 的文本框；这些高度只适合短标签。
+- 页脚和来源通常保持一行。若必须换行，应上移成真实 caption block，而不是挤在页脚区。
+- 底部结论条一行强调至少 `40` px 高，两行至少 `54` px 高。
+- 多个 `<p>` 的文本框必须按多行显式给高度，不要假设渲染器会自动撑开；中英混排要预留更宽空间。
+
+常用 `layout_type` 的几何约束：
+
+| `layout_type` | 几何要求 | 文本要求 |
+|---|---|---|
+| `title-cover` | 使用主标题块，常见 `x=70..120`、`y=150..250`、`width=700..820`；可用全幅背景、侧图、accent band 或抽象母题。若有右侧 diagram / 截图 / 母题簇，必须做明确 split composition，让标题区和视觉区分离。 | 只放一条 subtitle 或 context，默认 `low`，不要做 bullet list。 |
+| `section-divider` | 使用大号章节编号、chapter label、居中 claim、竖向 accent bar 或全宽 band；页面保持稀疏。 | 标题 + 一句短语，不放 bullets。 |
+| `two-column` | 主区域拆成两个均衡列，例如左 `x=60,width=400`、右 `x=500,width=400`；每列有自己的 heading 或视觉锚点。 | `medium` 每列 2-3 个短项；`high` 用 grouped rows 或 mini table。 |
+| `image-left-text-right` | 左侧视觉区约占宽度 `35-45%`，可全高或高裁切；右侧文本通常从 `x=420` 左右开始。密集截图、论文图、产品图可扩大到 `50-65%` 宽或至少 `320` px 高。 | 右侧只放强 headline + 短支持，最多 4 bullets；截图页优先用 2-3 个解读卡片或 callout。 |
+| `image-right-text-left` | 左侧文本从 `x=60..90` 开始，宽 `400..460`；右侧视觉区约占 `35-45%` 宽，并与正文块对齐。密集素材优先放大视觉区、减少文本。 | 一条主 claim + 2-3 个支持点；callout 要短且并行。 |
+| `big-number` | 最大对象留给指标，字号常见 `64-110`，区域至少 `300 x 120`；不要把数字埋进 bullet 或小卡片。 | `low` 或 `medium`；补充信息用小标签、legend、mini-card，不与数字抢焦点。 |
+| `timeline` | 3-6 个 milestone 沿水平或垂直 spine 排列，每个节点有 dot / card / date，并由线或箭头连接；标题与序列分离。 | 每个节点短标签 + 可选一行说明，不写段落。 |
+| `comparison` | 使用 2-3 个 panel、column 或 table-like 结构，heading 对齐；用颜色、边框、图标或标签突出首选项或关键差异。 | 各列措辞平行，避免长短严重不均。 |
+| `architecture-diagram` | 主区域必须是组件、依赖或系统流图；优先用 `<whiteboard>`，fallback 才用 `<shape>` + `<line>`。 | 节点标签 1-5 个词，最多一个短说明块；两行标签要给足节点和文本框高度。 |
+| `process-flow` | 用 3-5 个编号步骤 + 明显方向箭头 / 连线；步骤更多时分组为阶段。优先用 `<whiteboard>`。 | 每步用动词开头标签 + 最多一个短描述；长解释移到侧注或 notes。 |
+| `quote-highlight` | 引语或 claim 是最大文本对象，留大量空白，可加 attribution 或 context badge。 | 一个 statement / quote + 可选 attribution，不放 bullets。 |
+| `conclusion` | 用一个主 closing statement 或 call to action，可加最多 3 个 next-step card / checklist / owner-date label；可呼应封面背景。 | 结尾要易记，不做 recap overload。 |
+
+截图、论文图、真实图表和产品截屏必须按页面角色使用：
+
+- 只有在素材可读时才作为视觉焦点；过密时裁到相关区域、做 zoom detail，或用原生 shape 重画核心信息。
+- 不要把截图缩成装饰 thumbnail 后再包围密集正文。配 2-3 个解释性标注，告诉读者该看哪里。
+- 外部或论文来源的视觉必须有短 source caption。
+- 最终 XML 必须包含支持的 image token 或创建时本地 placeholder，不能留下不支持的外链。
+
+生成每页 XML 前逐页检查：主视觉是否最大或最突出；几何是否匹配 `layout_type`；`text_density` 是否限制了段落、bullet、标签和文本框数量；背景策略是否和 deck 级视觉系统一致；所有文本框高度是否足够；截图或论文图是否足够大且有简短解读。创建后回读时继续检查：页面是否拥挤、是否依赖长 bullet 框、主 claim / 支撑细节 / 主视觉是否有清晰层级，静态 XML 是否存在短框长文、多段高度不足、页脚换行、标签压线等 text-fit 风险。
+
+### Asset Planning：轻量资产规划
+
+新建演示文稿或大幅改写页面时，在写入 `slide_plan.json` 前后都可以规划 `asset_need`，让 agent 主动识别有价值的图、图标、图表、流程图、时序图、架构图、装饰图案、截图或示意图需求。`asset_need` 只定义轻量资产规划，不是素材采集流程。
+
+- `asset_need` 只是元数据，可以指导页面设计，但不能要求 web search、本地下载、媒体上传或外部工具。`suggested_query` 只是未来查找提示，除非用户另行要求真实素材，否则不要执行搜索。
+- 每个 planned asset 都必须有 `fallback_if_missing`，确保没有真实素材时也能用 XML shapes、文本、箭头、表格、简单图表、`<whiteboard>` diagram 或 placeholder region 完整生成页面。
+- 资产需求必须服务该页 `key_message` 和 `visual_focus`；不要为装饰而加素材。优先规划少数高价值资产，而不是每页机械放一个 asset。6 页左右的技术或商业 deck，在内容允许时至少 3 页有 meaningful asset plan。
+- 如果真实本地素材已经存在，或用户明确提供了素材，可以走正常 media-upload / image workflow，但 plan 里仍要保留 `fallback_if_missing`。
+- 最终 XML 不能留下空白图片框。真实素材缺失时，立即渲染 fallback，并让 fallback 满足 `visual_focus`，成为真实页面元素，而不是小装饰。
+
+`asset_need` 可以是单个对象；一页确实需要多个资产时才用数组。对象保持紧凑：
+
+```json
+{
+  "asset_type": "architecture_diagram",
+  "purpose": "Show how API gateway, planner, XML generator, and Slides API interact.",
+  "suggested_query": "agent native slides runtime architecture diagram",
+  "fallback_if_missing": "Draw grouped boxes connected by arrows with short labels."
+}
+```
+
+没有有意义资产需求的页面，显式写 `none`：
+
+```json
+{
+  "asset_type": "none",
+  "purpose": "No external or simulated asset needed; the page is text-led.",
+  "suggested_query": "",
+  "fallback_if_missing": "Use typography, spacing, and simple accent shapes only."
+}
+```
+
+支持的 `asset_type`：`paper_figure`、`architecture_diagram`、`icon`、`logo`、`chart`、`infographic`、`screenshot`、`flow_diagram`、`none`。不要随意发明新类型；接近这些类型时选择最接近的一种，并在 `purpose` 里说明细节。`<chart>` 不支持 funnel 或 scatter，这类需求生成时映射到 `<whiteboard>` SVG。
+
+资产类型要匹配页面角色：
+
+- `architecture-diagram` 通常配 `architecture_diagram` 或 `flow_diagram`。
+- `process-flow` 通常配 `flow_diagram`、`icon` 或 `infographic`。
+- `comparison` 通常配 `icon`、`chart` 或 `infographic`。
+- `timeline` 通常配 `icon`、`chart` 或 shape-based milestone markers。
+- `big-number` 只有在资产支持指标表达时才配 `chart` 或 `infographic`。
+- `image-left-text-right` / `image-right-text-left` 可以配 `screenshot`、`paper_figure`、`logo` 或 `infographic`；缺失时使用大型 placeholder diagram 或 stylized panel。
+
+`fallback_if_missing` 必须具体到可直接生成 XML，例如：简化 attention matrix、client -> gateway -> service 的三组盒子与箭头、4 根柱子的 mini bar chart、带产品区域标签的 bordered placeholder panel。不要写“Use a placeholder”“Find another image”“Leave blank if unavailable”或“Use generic decoration”。
+
+生成 XML 时按这个顺序执行：真实素材存在且流程支持时，放入计划的主视觉区域；否则立刻用 XML-native fallback 渲染；fallback 的尺寸和位置必须满足 `visual_focus`；不要用更长 bullet 文本补偿缺失素材；创建后回读并确认资产页不空白，且缺失素材时 planned fallback 可见。
+
+### 视觉系统
+
+- 先根据内容主题、行业语境、受众和交付方式推导视觉方向，再确定配色、字体、图形语言和页面密度；不要套用通用高饱和模板色，也不要让用户在抽象风格词里做选择。
+- 样本中更稳定的高级感来自“中性底色 + 少量强调色”，而不是全页高饱和。优先使用白、浅灰、深灰、蓝灰、炭黑作为基底，再用绿色、红色、金色、橙色、蓝色等小面积强调关键数字、结论或状态。
+- 同一份 deck 要锁定一套视觉系统，并贯穿所有页面：主色、背景、正文颜色、强调色、标题处理、留白密度、图标/图形风格都要稳定。
+- 生成 XML 前先写出 deck 级颜色令牌并明确分工：`primary` 承担品牌/结构，`background` / `background_alt` 承担页面基底，`text_primary` / `text_body` / `muted` 保证阅读层级，`accent` 只用于关键数字、结论、风险、增长或行动点；后续页面复用这些令牌，不要每页临时发明新颜色。
+- 普通内容页默认使用同一明暗基调。封面、章节页、强调页可以改变背景，但必须保留同一主色、边栏、纹理、图形母题或标题处理方式。
+- 每页都必须显式写 `<style><fill>...</fill></style>`。背景策略要克制：纯色、渐变或图片三选一作为主背景，不要叠多层全页色块。
+- 深色、发光或科技感页面，应使用平整深色背景 + 局部发光元素，而不是半透明大渐变把页面洗白。
+- 正文和注释不要使用高饱和色；高饱和或高亮度颜色只作为小面积 `accent`，避免用于大段文字、大面积背景或整页高饱和渐变。
+- 所有文字、图标、线条和图表都必须与背景保持清晰可读的对比；不要把“对比充足”做成刺眼的纯黑/纯白/荧光色组合。弱化信息可以降低饱和度或透明度，但不能牺牲可读性。
+- 图片或渐变背景上放文字时，给文字区域加半透明遮罩、色块或足够留白；不要把正文直接压在复杂背景上。
+- 渐变色必须使用 `rgba()` 格式并带百分比停靠点，例如 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`；使用 `rgb()` 或省略停靠点可能导致服务端回退为白底。
+- 验证时逐页检查：背景是否显式填充且未无意变白，正文颜色是否可读，`accent` 是否过量，渐变是否可能回退。
+
+### 字体与字号
+
+- 标题字体可以有性格，正文字体必须清晰耐读；不要整份 deck 都默认 Arial。
+- 当前样本中中文正文最稳定的是现代无衬线系统，尤其接近 `Noto Sans SC` / 思源黑体方向；编辑感或文化感页面会使用 `Noto Serif SC` / 思源宋体方向，但不应全篇滥用。
+- 中英文混排时，字体族先写英文/拉丁字体，再写中文/CJK 字体，最后写通用 fallback；标题和正文各用一套稳定组合。
+- 字体选择要匹配视觉系统的类别和处理方式：衬线、无衬线、圆体、等宽、粗窄标题、全大写等风格不要随意互换。
+- 常用标题方向：`Playfair Display` / `EB Garamond` / `Lora` 适合编辑感和高级感；`Anton` / `Bebas Neue` / `Oswald` 适合强冲击标题；`DM Sans` / `Montserrat` / `Poppins` 适合现代产品和商业正文。
+- 常用中文方向：`思源宋体` 适合长文和编辑感；`思源黑体` / `黑体` / `Noto Sans SC` 适合中性现代；`寒蝉德黑体` 适合工业和科技；`寒蝉全圆体` / `资源圆体` 适合温暖亲和；书法类字体只用于少量标题。
+- 字号要形成清晰层级。标题、分区标题、正文、注释、Hero number 至少要有 3 个可见层级；不要让标题、标签和正文看起来几乎一样大。
+
+| 元素 | 建议字号 |
+|------|----------|
+| 封面标题 | 40-56px；纯标题页可到 64-96px |
+| 内容页标题 | 28-40px |
+| 副标题 / 分区标题 | 20-26px |
+| 正文一级 | 16-20px |
+| 正文二级 | 13-16px |
+| 注释 / 来源 | 11-13px |
+| Hero number | 80-140px |
+
+- 不要为了填满空页面而盲目放大字体；页面显得空时，优先补充有意义的信息、调整构图、强化边缘对齐或增加视觉锚点。
+- 标题文本框要预留足够宽度，避免本应单行的标题意外换行。正文过长时先删减内容，再考虑缩小字号。
+
+### 布局
+
+- 先判断内容关系，再设计版式。比较、流程、时间线、循环、层级、矩阵、漏斗、整体-部分、因果等关系，应通过位置、对齐、分组、比例和流向直接表达。
+- 高质量样本里最常见的稳定结构是“顶部结论标题 + 下方内容区”，以及“左文右图 / 左图右文”的双区布局。生成页面时优先明确标题区、证据区、解释区，而不是随手摆放元素。
+- 版式本身要承载逻辑：比较用并列和基线对齐，流程用方向和连接，层级用尺度和嵌套，矩阵用坐标和象限，因果用箭头和阅读顺序。
+- 每页都应围绕该页内容重新组织，不要从固定模板里盖章；同一 deck 可以复用视觉母题，但不要所有页面都是标题 + 三 bullets。
+- 页面要留呼吸感。内容块之间保持稳定间距，卡片内边距要真实存在；文字不要贴边，也不要被装饰线、图片或页脚挤压。
+- 相关元素之间距离更近，不相关元素之间距离更远。不要把所有间距做成平均值；间距本身就是分组和层级。
+- 并列内容尽量使用同宽、同高、同内边距的模块。卡片、列、表格、小图、多指标块必须共享网格和 slot 顺序，否则读者无法快速比较。
+- 正文默认左对齐；只有封面、章节页、结尾页、大号数字或少量仪式感页面适合居中。
+
+### 视觉元素与图表
+
+- 视觉元素必须承载意义或引导注意力，不做填空装饰。图片、图标、图表、表格、色块、连线都要解释内容关系、强调重点或改善阅读节奏。
+- 每个内容页至少应有一个非纯文本视觉锚点：图片、图标、图表、表格、流程、对比结构、大号数字、示意图或抽象 shape 组合。
+- 卡片只用于真正并列的内容。每张卡片应有相同的内部结构：图标/编号、标题、短说明、关键数字或状态；不要把不具备并列关系的段落硬塞进卡片。
+- 流程和时间线使用重复节点 + 克制连线。连线应表达顺序、依赖或阶段，不要穿过文字，不要用复杂箭头装饰页面。
+- 信息图、截图、图表等素材要保持原始比例；不要为了塞进版面强行裁切或拉伸。装饰性照片可以更自由，但仍要服务主题和构图。
+- 有真实数据序列时，先写清图表要证明的 takeaway，再选择图表类型；一张图只表达一个核心结论。单个数字或两项简单对比，优先用大号数字 callout，不必硬画图。
+- 数据页可以采用“Hero number + 解释 + 图表证据”的结构。大数字必须配单位、时间范围、比较对象或解释句，不能只放一个孤立数字。
+- 饼图 / 环图只适合表达明确的整体构成；不确定时优先使用排序条形图。多系列数据要控制数量，必要时合并为 Other。
+- 封面和结尾页的图片不要自带文字；文字应由 slide 渲染，避免图片中文字不可控、不可编辑或与语言风格冲突。
+
+### 动效
+
+- 动效服务节奏和注意力，不做炫技。只有在逐步解释、引导关键元素、展示流程 / 时间 / 变化时才使用。
+- 演讲型 deck 可以用少量 build 控制听众视线；自读型、正式汇报型、董事会/咨询风格 deck 应尽量静态，最多使用统一的页面转场。
+- 封面、章节页和结尾页默认静态。单页动效不超过 3 个 build，且同页尽量只使用一种效果；如果需要更多步骤，优先拆页。
+- 动效要让观众注意内容出现，而不是注意效果本身。优先使用淡入、出现、轻微上浮、擦入；避免旋转、弹跳、闪烁、远距离飞入等抢戏效果。
+
+### 基于模板或已有 PPT 编辑
+
+- 如果用户要求继续编辑、补页或修改已有 PPT，默认保留原页面内容、结构、字体、配色和视觉资产，只改用户要求的部分。
+- 除非用户明确要求重做，不要擅自美化、重排、加封面、换背景或从零复刻。
+- 如果用户把上传文件作为“参考风格”而不是“继续编辑原文件”，才可以抽取其视觉语言后重新创作。
+
+### 避免事项
+
+- 不要让版式先于内容；先判断这一页的逻辑关系，再决定几何结构。
+- 不要创建纯文本页；plain title + bullets 只能作为草稿，不是正式交付。
+- 不要只设计一页，其余页面保持 plain；视觉系统必须全篇贯彻，或者全篇保持有意克制。
+- 不要让普通内容页在深色、浅色、图片背景之间来回切换；背景明暗变化必须服务封面、章节、强调或总结等明确页面角色。
+- 不要混用太多字体、字号、圆角、阴影和强调色；变化必须有层级意义。
+- 不要用高饱和色填满背景、正文或大面积卡片；更稳定的做法是中性基底、清晰文字和小面积 accent。
+- 不要用图表承载多个结论，也不要因为有数字就机械画图。
+- 不要在标题下方画装饰强调线作为默认设计手法；优先用空间关系、局部低饱和色块、尺度、分区和对齐建立层级。
+- 不要把并列卡片、比较列、时间节点做成不同尺寸、不同内边距、不同标题层级；除非差异本身就是要表达的信息。
+
+## PPT 主题配色体系
+
+本章节用于根据不同 PPT 内容分类，选择匹配的视觉主题与配色方案。配色设计遵循三个原则：
+
+1. 内容气质优先：颜色服务于汇报场景，而不是单纯追求好看。
+2. 层级清晰：每套配色都区分背景色、正文色、主色、辅助色和强调色。
+3. 克制高级：大面积颜色低饱和，关键结论和数据才使用高识别度强调色。
+
+### 配色使用规则
+
+| 色槽 | 用途 |
+|---|---|
+| 背景色 | 页面底色、大面积留白区域、浅色模块背景 |
+| 正文色 | 正文、说明文字、页脚、图表标签 |
+| 主色 | 封面、章节页、标题、核心模块 |
+| 辅助色 | 图表、分组、信息卡片、二级视觉层级 |
+| 强调色 | 关键数字、结论标签、重点标注、行动按钮 |
+
+建议使用比例：
+
+| 类型 | 比例 | 说明 |
+|---|---:|---|
+| 背景色 | 70% | 保持页面干净、可读 |
+| 主色/辅助色 | 20% | 建立主题识别和结构层级 |
+| 强调色 | 10% | 只用于最关键的信息 |
+
+---
+
+### 一级分类主题配色表
+
+| 一级分类 | 推荐主题名 | 背景色 | 正文色 | 主色 | 辅助色 | 强调色 | 设计气质 |
+|---|---|---:|---:|---:|---:|---:|---|
+| 战略决策 | Midnight Capital | `#F6F7F9` | `#1B2430` | `#102A43` | `#486581` | `#C89B3C` | 专业、克制、资本感 |
+| 教学/科研 | Sage Lab | `#F7FAF8` | `#253B36` | `#2F6F68` | `#9DBFAD` | `#E6B450` | 清晰、可信、学术感 |
+| 工作总结与经验分享 | Slate System | `#F5F6F8` | `#1F2937` | `#3E4C59` | `#8A98A8` | `#2FA876` | 稳健、复盘、结构化 |
+| 商业增长 | Signal Growth | `#FFF7F1` | `#2B2B2B` | `#D94A2B` | `#F08A3C` | `#2563EB` | 活力、转化、增长感 |
+| 技术研发 | Electric Blueprint | `#F5F7FF` | `#172033` | `#273469` | `#4C63B6` | `#00A7B5` | 理性、工程、科技感 |
+| 职能管理 | Civic Order | `#F7F8F5` | `#24312F` | `#245B4F` | `#7D9188` | `#B9972F` | 规范、秩序、组织感 |
+| 个人提升与表达 | Soft Presence | `#FFF8F4` | `#2D2A28` | `#E76F51` | `#F2B8A2` | `#2A9D8F` | 亲和、成长、表达感 |
+
+---
+
+### 二级场景配色建议
+
+| 场景 | 推荐主题 | 配色说明 |
+|---|---|---|
+| 投资分析、投资报告、行业研究报告 | Midnight Capital | 使用深蓝建立专业感，铜金用于关键结论和核心数字 |
+| 咨询顾问、战略宣讲 | Midnight Capital | 适合逻辑严密、判断明确的商业分析型页面 |
+| 融资 Pitch Deck、商业计划书、项目路演 | Midnight Capital / Signal Growth | 若偏资本叙事用深蓝金，若偏增长故事用橙红蓝 |
+| 课程设计、教学课件 | Sage Lab | 青绿色降低阅读压力，适合长时间观看 |
+| 论文阐述、开题/答辩报告 | Sage Lab / Electric Blueprint | 学术型用青绿，技术型用靛蓝电青 |
+| 研究方向调研 | Sage Lab | 保持理性和可信，不宜过度商业化 |
+| 培训课件、述职晋升 | Slate System | 灰蓝体系更适合正式职场表达 |
+| 项目复盘、项目结项、阶段汇报 | Slate System | 用绿色强调进展、成果和正向结论 |
+| 工作总结、日报、周报、月报、年终总结 | Slate System | 稳定、清晰、适合高频汇报 |
+| 产品介绍、品牌宣传 | Signal Growth | 暖色建立吸引力，蓝色用于建立可信度 |
+| 招商加盟方案、增长方案提报 | Signal Growth | 强调行动、机会、转化和商业结果 |
+| 创意提案 | Signal Growth | 可提高强调色使用比例，增强视觉记忆点 |
+| 账号运营汇报 | Signal Growth / Slate System | 增长结果用橙红蓝，常规复盘用灰蓝绿 |
+| 市场分析报告、数据分析报告 | Midnight Capital / Slate System | 战略判断用深蓝金，过程分析用灰蓝绿 |
+| 功能说明、技术可行性分析报告 | Electric Blueprint | 靛蓝和电青适合表达技术结构与方案可信度 |
+| 设计提案 | Electric Blueprint / Soft Presence | 产品设计用科技蓝，体验表达可用柔和暖色 |
+| 政策解读、制度宣贯 | Civic Order | 墨绿和旧金显得庄重、规范 |
+| 党建工作总结 | Civic Order | 可适当加入深红作为局部强调，但不建议大面积使用 |
+| 新员工入职培训 | Civic Order / Slate System | 制度流程用墨绿，通用培训用灰蓝 |
+| 自我介绍、生活学习分享 | Soft Presence | 亲和、不压迫，适合轻表达场景 |
+| 调研总结 | Soft Presence / Slate System | 偏个人观察用暖色，偏工作结论用灰蓝 |
+
+---
+
+### 单页应用建议
+
+#### 封面页
+
+优先使用主色作为大标题或视觉主背景，强调色只用于副标题、关键词或日期。
+
+示例：
+
+- 战略决策：深蓝背景 + 铜金关键词
+- 教学科研：浅绿背景 + 深青标题
+- 商业增长：暖白背景 + 橙红标题 + 蓝色重点词
+
+#### 目录页
+
+使用主色标记章节编号，辅助色用于分隔线或图标，不建议使用过多强调色。
+
+#### 数据页
+
+正文和坐标轴使用正文色，主数据系列使用主色，重点数据使用强调色。
+
+#### 结论页
+
+可以适当提高主色和强调色占比，用于强化最终判断。
+
+---
+
+### 不建议的配色方式
+
+| 问题 | 原因 |
+|---|---|
+| 大面积使用高饱和红、橙、紫 | 容易显得廉价，且阅读压力高 |
+| 一页中同时出现 5 个以上高存在感颜色 | 视觉焦点分散，削弱专业感 |
+| 浅黄色、浅绿色直接承载正文 | 对比度不足，可读性差 |
+| 全套 PPT 只有同一色相的深浅变化 | 容易单调，缺少设计记忆点 |
+| 每页都使用强调色 | 强调色会失效，重点不再突出 |
+
+---
+
+### 推荐默认选择
+
+如果无法判断具体场景，优先使用以下默认方案：
+
+| 场景类型 | 默认主题 |
+|---|---|
+| 商业判断类 | Midnight Capital |
+| 学术教学类 | Sage Lab |
+| 工作汇报类 | Slate System |
+| 增长营销类 | Signal Growth |
+| 技术产品类 | Electric Blueprint |
+| 管理制度类 | Civic Order |
+| 个人表达类 | Soft Presence |

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

@@ -1,124 +0,0 @@
-# Asset Planning
-
-新建演示文稿或大幅改写页面时，在写入 `slide_plan.json` 前后都可以参考本文件。目标是让 agent 主动识别有价值的图、图标、图表、流程图、时序图、架构图、装饰图案、截图或示意图需求，同时保持 deck 在没有真实素材时也能完整执行。
-
-本文件只定义轻量资产规划。不要把它理解成素材采集流程。
-
-## Core Rules
-
-- `asset_need` is metadata only. It can guide page design, but it must not require web search, local download, media upload, or external tools.
-- Every planned asset must include a fallback visual plan so the slide can be generated with XML shapes, text, arrows, tables, simple charts, whiteboard diagrams, or placeholder regions.
-- Asset needs must serve the page's `key_message` and `visual_focus`. Do not add decorative assets that do not clarify the page.
-- Prefer a few high-value asset plans over one asset on every page. For a 6-page technical or business deck, plan assets on at least 3 pages when the content allows.
-- If a real local asset already exists or the user provides one, it can be used through the normal media-upload workflow. Still keep `fallback_if_missing` in the plan.
-- Do not leave blank image boxes in final XML. If the asset is missing, render the fallback visual.
-
-## JSON Shape
-
-Use an object for one planned asset, or an array when a page genuinely needs multiple assets. Keep each item compact.
-
-```json
-{
-  "asset_type": "architecture_diagram",
-  "purpose": "Show how API gateway, planner, XML generator, and Slides API interact.",
-  "suggested_query": "agent native slides runtime architecture diagram",
-  "fallback_if_missing": "Draw grouped boxes connected by arrows with short labels."
-}
-```
-
-For a page without a meaningful asset need, use:
-
-```json
-{
-  "asset_type": "none",
-  "purpose": "No external or simulated asset needed; the page is text-led.",
-  "suggested_query": "",
-  "fallback_if_missing": "Use typography, spacing, and simple accent shapes only."
-}
-```
-
-## Supported Asset Types
-
-- `paper_figure`: figure from a paper or technical article.
-- `architecture_diagram`: system components, data flow, dependency map, or model structure.
-- `icon`: small semantic symbol for a concept, step, role, or status.
-- `logo`: brand, product, team, or customer mark.
-- `chart`: line, bar, pie, radar, area, or combo data visual. Note: `<chart>` does not support funnel or scatter — map those to `<whiteboard>` SVG at generation time.
-- `infographic`: composed visual explanation, usually combining labels, numbers, and simple shapes.
-- `screenshot`: product UI, terminal output, workflow state, or page capture.
-- `flow_diagram`: process, sequence, decision tree, or mechanism diagram.
-- `none`: explicitly no asset needed.
-
-Do not invent new asset types unless the user asks for a special visual format. If a need is close to these types, choose the closest one and explain the detail in `purpose`.
-
-## Planning Guidance
-
-Match asset type to slide role:
-
-- `architecture-diagram` layout usually pairs with `architecture_diagram` or `flow_diagram`.
-- `process-flow` layout usually pairs with `flow_diagram`, `icon`, or `infographic`.
-- `comparison` layout often works with `icon`, `chart`, or `infographic`.
-- `timeline` layout often works with `icon`, `chart`, or shape-based milestone markers.
-- `big-number` layout often works with `chart` or `infographic`, but only if it supports the metric.
-- `image-left-text-right` and `image-right-text-left` can use `screenshot`, `paper_figure`, `logo`, or `infographic`; if missing, use a large placeholder diagram or stylized panel.
-
-`suggested_query` is only a future lookup hint. Write it as a short phrase a human or later workflow could search, but do not execute the search unless the user separately requests real assets.
-
-`fallback_if_missing` must be concrete enough to turn into XML, for example:
-
-- "Draw a simplified attention matrix with 5 token labels, semi-transparent cells, and arrows to output token."
-- "Use three grouped boxes with arrows from client to gateway to service; add small protocol labels."
-- "Render a mini bar chart with 4 bars using shapes and value labels."
-- "Use a bordered placeholder panel with product area labels, not an empty image."
-
-Weak fallbacks to avoid:
-
-- "Use a placeholder."
-- "Find another image."
-- "Leave blank if unavailable."
-- "Use generic decoration."
-
-## Examples
-
-Transformer Self-Attention page:
-
-```json
-{
-  "asset_type": "paper_figure",
-  "purpose": "Explain token-to-token attention and why each output token mixes context.",
-  "suggested_query": "Transformer self attention attention matrix diagram",
-  "fallback_if_missing": "Draw a simplified attention matrix with token labels, colored weights, and arrows from input tokens to one highlighted output token."
-}
-```
-
-System architecture page:
-
-```json
-{
-  "asset_type": "architecture_diagram",
-  "purpose": "Show the runtime path from user prompt to plan, XML generation, Slides API creation, and fetch verification.",
-  "suggested_query": "slides generation runtime architecture planner XML API verification",
-  "fallback_if_missing": "Draw four grouped boxes connected left-to-right with arrows; put verification as a return arrow from Slides API to agent."
-}
-```
-
-Business comparison page:
-
-```json
-{
-  "asset_type": "infographic",
-  "purpose": "Make before/after differences scannable without dense bullet lists.",
-  "suggested_query": "before after product workflow comparison infographic",
-  "fallback_if_missing": "Use two side-by-side panels with matching icon circles and three parallel rows of concise labels."
-}
-```
-
-## Plan To XML Contract
-
-When generating XML:
-
-1. If an asset exists and the workflow supports it, place it in the planned visual region.
-2. If no asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, whiteboard diagrams, or chart-like elements.
-3. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration.
-4. Keep text-density limits. Do not compensate for missing assets by adding long bullet text.
-5. After creation, fetch the presentation and verify asset pages are not blank and that each planned fallback is visible when no real asset was used.

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

@@ -0,0 +1,265 @@
+---
+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）。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli slides --help"
+---
+
+# slides (v1)
+
+## Quick Reference
+
+| 用户需求                                | 优先动作 | 关键文档 / 命令 |
+|-------------------------------------|----------|-----------------|
+| 新建 PPT                              | 先确定叙事、页序和视觉策略，再按复杂度选择一步或两步创建 | `SKILL.md` 设计思路、`slides +create` |
+| 已有 PPT 大幅改写                         | 多页整页重建用 `+replace-pages`，单页局部编辑用 `+replace-slide` | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` |
+| 编辑单个标题、文本块、图片或局部元素                  | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
+| 读取或分析已有 PPT                         | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` |
+| 获取幻灯片页面截图                           | 用 `slide_id` 或页号指定页面 | `slides +screenshot`、`lark-slides-screenshot.md` |
+| 上传或使用图片                             | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 |
+| 在 slide 中绘制柱/条/折线/面积/雷达/饼等有数据序列的图表  | 使用原生 `<chart>` 元素 | `xml-schema-quick-ref.md` |
+| 在 slide 中绘制流程图、时序图、架构图、散点图、漏斗图或装饰图案 | 必须先用 Read 工具读取参考文档，再生成 `<whiteboard>` 元素 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) |
+| 使用语义图标 | 先检索 IconPark，再写 `<icon iconType="...">` | `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 为准。**
+
+**CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
+
+**CRITICAL — PPT 生成与模板编辑硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。多用生图，辅助搜图，必须要图文并茂。不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。生成背景图时必须在 prompt 中明确要求不要出现任何文字。用户指定 PPT 模板时，用 lark-drive 技能导入成 lark slides，回读理解每页版式后，直接在该 slides 上编辑，可以填改文字和图片、按需增删模板页，必须严格沿用原版式和字体，只改内容不做设计，完成后回读并微调，凝练文字或缩减字号消除文字溢出，调整 shape 顺序或位置避免文字遮挡。**
+
+**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)。
+
+## 身份选择
+
+飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。
+
+- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权：
+
+```bash
+lark-cli auth login --domain slides
+```
+
+- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。
+
+**执行规则**：
+
+1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。
+2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。
+3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。
+
+## 执行前必做
+
+> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。
+
+高频只读：
+
+- [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)
+- [validation-checklist.md](references/validation-checklist.md)（创建 / 大幅改写后）
+
+按需再读：
+
+- 创建：[`lark-slides-create.md`](references/lark-slides-create.md)
+- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-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)
+- 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md)
+- 图标：[`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 是独立的视觉画面，信息密度要低，排版要留白。
+
+### Design Ideas
+
+不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。
+
+开始写 XML 前，先确定 deck 级视觉策略：
+
+- **主题化配色**：配色必须服务本次主题、行业和受众，不要默认蓝色商务风。如果把同一套颜色换到另一个完全不同主题仍然成立，说明配色不够具体。
+- **主次比例**：选择 1 个主色承担约 60-70% 视觉权重，1-2 个辅助色承担结构和分区，1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。
+- **背景一致性**：先确定全 deck 的背景策略，默认保持同一明暗基调和底色体系；普通内容页不要在深色、浅色、图片背景之间来回切换。只有分节、转场、强调页或总结页才有意改变背景，并必须通过相同主色、纹理、边栏或 motif 让变化看起来属于同一套设计。无论深浅，都要保证正文、图标和线条对比充足。
+- **统一 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 版式。
+- 不要用低对比文字或低对比图标，例如浅灰字压在浅色背景上。
+- 不要让装饰线穿过文字，或让页脚、来源、编号挤压主体内容。
+- 不要把素材缺失表现为空白图片框；必须用 XML-native 形状、图表、表格或 whiteboard 生成兜底视觉。
+- 不要留下占位文案、示例公司名、示例日期或与用户主题无关的内容。
+
+### 创建方式选择
+
+| 场景 | 推荐方式 |
+|------|----------|
+| 简单 XML（1-3 页、结构简单、几乎无复杂中文和特殊字符） | `slides +create --slides '[...]'` 一步创建 |
+| 复杂 XML（多页、含中文、大段文本、复杂布局、嵌套引号、特殊字符较多） | **两步创建**：先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide create` 逐页添加 |
+| 已有 PPT 继续追加或插入页面 | 使用 `xml_presentation.slide create`，必要时配合 `before_slide_id` |
+
+> [!WARNING]
+> `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议使用两步创建法。
+
+> [!IMPORTANT]
+> `slides +create --slides` 底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。
+
+```text
+Step 1: 需求澄清 & 读取知识
+  - 澄清主题、受众、页数、风格
+  - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时按 SKILL.md 的设计思路先锁定视觉系统
+
+Step 2: 生成大纲 → 用户确认
+  - 生成结构化大纲供用户确认
+  - 新建 / 大幅改写必须先明确 deck 目标、受众、页序、视觉系统和每页关键消息
+  - 每页确定 `key_message`、`layout_type`、`visual_focus`、`text_density`；素材需求只作为设计意图
+
+Step 3: 按已确认大纲生成 XML → 创建
+  - 逐页生成 XML：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
+  - 缺少真实素材时必须用 XML-native 形状、图表、表格或 whiteboard 生成兜底视觉；不要留空
+  - 创建方式按“创建方式选择”判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
+
+Step 4: 审查 & 交付
+  - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
+  - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
+  - 没问题 → 交付：告知用户演示文稿 ID 和访问方式
+```
+
+### jq 命令模板（编辑已有 PPT 时使用）
+
+新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
+
+```bash
+# 追加到末尾
+lark-cli slides xml_presentation.slide create \
+  --as user \
+  --params '{"xml_presentation_id":"YOUR_ID"}' \
+  --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、whiteboard 等元素
+  </data>
+</slide>' '{slide:{content:$content}}')"
+
+# 插到指定页之前：before_slide_id 必须在 --data body 里，与 slide 同级
+# ⚠️ 不要把 before_slide_id 写进 --params —— CLI 会当未知 query 参数静默下发，服务端忽略，新页跑到末尾
+lark-cli slides xml_presentation.slide create \
+  --as user \
+  --params '{"xml_presentation_id":"YOUR_ID"}' \
+  --data "$(jq -n --arg content '<slide ...>...</slide>' --arg before 'TARGET_SLIDE_ID' \
+    '{slide:{content:$content}, before_slide_id:$before}')"
+```
+
+> 渐变色必须使用 `rgba()` 格式并带百分比停靠点，如 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端回退为白色。
+
+### 大纲模板
+
+生成大纲时使用以下格式，交给用户确认：
+
+```text
+[PPT 标题] — [定位描述]，面向 [目标受众]
+
+页面结构（N 页）：
+1. 封面页：[标题文案]
+2. [页面主题]：[要点1]、[要点2]、[要点3]
+3. [页面主题]：[要点描述]
+...
+N. 结尾页：[结尾文案]
+
+风格：[配色方案]，[排版风格]
+```
+
+## 核心概念
+
+### URL 格式与 Token
+
+| URL 格式 | 示例 | Token 类型 | 处理方式 |
+|----------|------|-----------|----------|
+| `/slides/` | `https://example.larkoffice.com/slides/xxxxxxxxxxxxx` | `xml_presentation_id` | URL 路径中的 token 直接作为 `xml_presentation_id` 使用 |
+| `/wiki/` | `https://example.larkoffice.com/wiki/wikcnxxxxxxxxx` | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
+
+> `+replace-slide` 和 `+media-upload` shortcut 会自动解析以上两种 URL；直接调用原生 API 时仍需手动解析 wiki 链接。
+
+### Wiki 链接特殊处理（关键！）
+
+知识库链接（`/wiki/TOKEN`）不能直接当 `xml_presentation_id`。直接调用原生 API 前，先查询 wiki 节点，确认 `node.obj_type == "slides"`，再用 `node.obj_token` 作为真实 presentation ID。
+
+```bash
+lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}'
+```
+
+Shortcut `+replace-slide` 和 `+media-upload` 会自动解析 `/wiki/` URL；手动调用 `xml_presentations.*` / `xml_presentation.slide.*` 时才需要自己做这一步。
+
+### 资源关系
+
+```text
+Wiki Space (知识空间)
+└── Wiki Node (知识库节点, obj_type: slides)
+    └── obj_token → xml_presentation_id
+
+Slides (演示文稿)
+├── xml_presentation_id (演示文稿唯一标识)
+├── revision_id (版本号)
+└── Slide (幻灯片页面)
+    └── slide_id (页面唯一标识)
+```
+
+## Shortcuts 与 API
+
+Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `<img src="@./local.png">` 占位符自动上传） |
+| [`+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 的多页大改，不新建链接 |
+
+没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
+
+```bash
+lark-cli schema slides.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli slides <resource> <method> [flags] # 调用 API
+```
+
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+## 核心规则
+
+1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，先确定 deck 目标、受众、页序、视觉系统和每页关键消息；同时明确普通内容页的统一背景明暗基调，不要从用户提示直接跳到 XML
+2. **创建流程**：简单短 XML（1-3 页、结构简单、特殊字符少）可用 `slides +create --slides '[...]'` 一步创建；复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符，或超过 10 页时，默认先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
+3. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
+4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
+5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
+6. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
+7. **编辑已有页面优先原链接更新**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；已有 Slides 的多页整页重建用 `+replace-pages`，不要用 `slides +create` 新建整份 PPT；只有没有 shortcut 覆盖的特殊单页整页操作才手动 `slide.create` + `slide.delete`
+8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
+
+> **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。

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

@@ -0,0 +1,77 @@
+# PPT Template Rewrite Principles
+
+本页只约束“用户指定 PPT 模板、底稿、已有 PPTX/PDF/Slides，并要求基于它二次创作”的场景。核心原则：模板不是风格参考，而是必须沿用的编辑底稿。
+
+## Import First
+
+用户指定 PPT 模板时，先使用 `lark-drive` 技能把模板导入成 Lark Slides。后续写入目标是导入后的 Slides，不是新建一个脱离模板的 deck，也不是先在本地重画 PPTX 再导入。
+
+导入后必须回读 Slides 内容，理解每页的真实版式、字体、层级、图片、图表、shape、表格和文本容器。回读结果是模板二创的事实来源。
+
+## Read Before Editing
+
+编辑任何 PPT 页面前，必须先阅读该页面。
+
+如果当前上下文中没有该页内容，必须重新读取页面；这里的“当前上下文”不包含 System Prompt。不能只凭记忆、文件名、缩略图印象或模板整体风格判断来编辑具体页面。
+
+阅读页面时至少判断：
+
+- 该页原本承担的角色，例如封面、章节页、目录、流程、对比、数据、总结。
+- 该页的主要版式结构，例如图文关系、箭头、时间线、节点、表格、图表、左右对照、背景图或产品图。
+- 哪些文本框、shape 标签、表格单元格或图表标签承载内容。
+- 原页面的字体、字号、颜色、对齐、层级和留白关系。
+
+## Edit The Imported Slides Directly
+
+理解页面后，直接在导入后的 Slides 上编辑。允许的操作包括：
+
+- 填写、替换、凝练或删除文字。
+- 替换或补充图片。
+- 更新图表、表格、数字标签或节点标签里的内容。
+- 按需复制、删除或重排模板页。
+- 在源页面没有合适承载位置时，做局部、小范围新增元素。
+
+新增元素只能补足内容缺口，不能成为新的主版式。页面主体仍应由模板原有版式承载。
+
+## Preserve Design
+
+模板二创必须严格沿用原版式和字体，只改内容，不做设计。
+
+默认保留：
+
+- 页面布局、视觉层级、留白和对齐关系。
+- 原字体、字号体系、颜色、文本框位置和 shape 顺序。
+- 背景图、图片、logo、图表、表格、装饰形状、线条、图标和页面结构。
+- 模板中不同页型之间的差异。
+
+不要把模板页改造成统一的通用卡片、白板、标题栏、三栏、2x2 卡片或大面积遮罩。不要把模板当作背景图后另起一套设计系统。
+
+## Content Only
+
+内容必须优先进入原页面已有的文本框、shape 标签、节点、表格单元格、图表标签或注释容器。
+
+如果原容器空间不足，优先：
+
+- 凝练文字。
+- 降低字号但保持原字体体系。
+- 拆分到页面已有的邻近容器。
+- 使用模板已有的注释、标签或补充说明区域。
+- 复制同页或同模板中的原生容器样式做局部补充。
+
+不要为了容纳长文案而重画页面主体结构。不要用新增大卡片遮住原图表、箭头、图片、背景或关键 shape。
+
+## Readback And Tune
+
+完成编辑后必须回读结果，并逐页微调。
+
+回读时重点检查：
+
+- 文字是否溢出、截断、压线或超出容器。
+- 文本是否遮挡图片、图表、shape、箭头、节点或其他文字。
+- shape 顺序是否导致内容被覆盖或遮住。
+- 新内容是否仍然落在模板原有版式中，而不是覆盖模板结构。
+- 字体、字号、颜色、对齐和层级是否仍贴近原页。
+
+发现文字溢出时，优先凝练文字或缩减字号。发现遮挡时，调整 shape 顺序、局部位置或复用原有空白区域解决。只有在这些方法都不能满足内容表达时，才做局部新增或删除。
+
+模板二创的完成标准不是“生成了一套看起来统一的新 PPT”，而是“原模板的版式、字体和视觉结构仍清晰存在，内容已经被准确替换，并且回读后没有溢出和遮挡”。

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

@@ -237,4 +237,4 @@ lark-cli slides +replace-slide --as user \
 - [xml_presentation.slide get](lark-slides-xml-presentation-slide-get.md) — 读原页拿 `block_id` / `revision_id`
 - [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
 - [+media-upload](lark-slides-media-upload.md) — 上传图片拿 `file_token`
-- [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环 + 决策树
+- [lark-slides-edit-workflows.md](lark-slides-block-replace-workflows) — 读-改-写闭环 + 决策树

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

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

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

@@ -67,7 +67,7 @@ lark-cli slides xml_presentation.slide create --as user --params '<json_params>'
 </slide>
 ```
 
-详细格式请参考 [xml-format-guide.md](xml-format-guide.md) 和 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
+详细格式请参考 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
 
 ## 使用示例
 
@@ -216,5 +216,4 @@ done
 - [slides +create](lark-slides-create.md) - 创建空白 PPT
 - [xml_presentations get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容
 - [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
-- [xml-format-guide.md](xml-format-guide.md) - XML 格式详细规范
-- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) - Schema 快速参考
+- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) - XML 格式和 Schema 唯一 Markdown 入口

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

@@ -107,4 +107,4 @@ 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 参考
 - [xml_presentations get](lark-slides-xml-presentations-get.md) — 读整个 PPT
-- [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环
+- [lark-slides-edit-workflows.md](lark-slides-block-replace-workflows) — 读-改-写闭环

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

@@ -184,4 +184,4 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 - [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐，自动注入 id）
 - [xml_presentation.slide get](lark-slides-xml-presentation-slide-get.md) — 读原页拿 block short ID
 - [slides +media-upload](lark-slides-media-upload.md) — 上传图片拿 file_token
-- [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环 + 决策树
+- [lark-slides-edit-workflows.md](lark-slides-block-replace-workflows) — 读-改-写闭环 + 决策树

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

@@ -1,216 +0,0 @@
-# Planning Layer
-
-新建演示文稿或大幅改写页面时，必须先写 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。这个文件是 deck 的设计中间层，用来把叙事、页面角色、布局、视觉重点和文字密度固定下来，避免从用户提示直接跳到 XML。
-
-小型已有页编辑可豁免，例如只替换一个标题、改一个数字、插入一个块、上传并插入一张图。只要任务会重排多页、生成新 deck、替换整页结构，仍然需要规划层。
-
-## Required Flow
-
-1. 理解用户需求，必要时澄清主题、受众、页数、风格。
-2. 选择唯一 plan 目录：`.lark-slides/plan/<deck-or-task-id>/`。
-3. 先创建目录：`mkdir -p .lark-slides/plan/<deck-or-task-id>`。
-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 后用 `xml_presentations.get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
-
-## Plan Path
-
-Use a separate plan directory per deck or task so multiple presentations in the same workspace cannot overwrite each other.
-
-Recommended IDs:
-
-- New deck before creation: title slug plus date/time, such as `q3-review-20260507-1805`.
-- Existing PPT rewrite: the `xml_presentation_id`.
-- Ambiguous or untitled task: short task slug plus date/time.
-
-Rules:
-
-- Do not reuse `.lark-slides/plan/slide_plan.json` as a shared path.
-- Create the directory before writing the file.
-- Reuse the same plan path for XML generation and post-create verification for that deck.
-
-## Artifact Lifecycle
-
-`.lark-slides/` is local agent state. It supports recovery, iteration, and later edits, but it should not be treated as source code or committed by default.
-
-Keep:
-
-- `.lark-slides/plan/<deck-or-task-id>/slide_plan.json` after successful creation or major rewrite. The plan is the editable design state for the deck.
-- A small manifest when useful for follow-up work, such as `xml_presentation_id`, slide IDs, `revision_id`, plan path, and verification status.
-
-Clean or avoid keeping:
-
-- Transient XML payloads after successful creation and verification. Prefer `/tmp` for throwaway XML, or delete generated XML files after success.
-- Stale XML drafts that no longer match the current presentation state.
-
-Exception:
-
-- If creation fails or partially succeeds, keep the relevant XML/debug payloads until recovery is complete. Record `xml_presentation_id` first, then fetch current state before retrying.
-
-## JSON Shape
-
-```json
-{
-  "presentation_goal": "Explain the proposal and secure approval for the next phase.",
-  "audience": "Product and engineering leaders who know the domain but need a concise decision narrative.",
-  "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.",
-    "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.",
-      "accent": "Used only for key numbers, conclusions, or focus markers."
-    }
-  },
-  "typography_constraints": {
-    "title_max_lines": 2,
-    "body_max_lines_per_box": 2,
-    "footer_max_lines": 1,
-    "long_text_handling": "Shorten, split into multiple boxes, or move detail to speaker notes instead of shrinking into a tight box."
-  },
-  "verification_plan": {
-    "check_background_consistency": true,
-    "check_text_fit": true,
-    "check_visual_focus": true,
-    "check_asset_rendering": true
-  },
-  "slides": [
-    {
-      "page": 1,
-      "title": "Proposal Title",
-      "key_message": "The initiative is ready for a focused pilot.",
-      "layout_type": "title-cover",
-      "visual_focus": "Large title area with one concise supporting statement.",
-      "asset_need": {
-        "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."
-      },
-      "text_density": "low",
-      "speaker_intent": "Frame the decision and establish the deck's point of view."
-    }
-  ]
-}
-```
-
-## Required Fields
-
-Top-level fields:
-
-- `presentation_goal`: what the whole deck is trying to achieve.
-- `audience`: target readers or listeners and their assumed background.
-- `theme_style`: visual tone, palette direction, and professional style.
-- `visual_system`: deck-level visual rules that must stay stable across pages, including background strategy, recurring motif, and color roles.
-- `typography_constraints`: deck-level limits for line count, text box density, and how to handle long text before XML generation.
-- `verification_plan`: explicit checks to perform after creation or major edits; include background consistency, text fit, visual focus, and asset rendering when relevant.
-- `slides`: ordered page plans.
-
-Each slide must include:
-
-- `page`: 1-based page number.
-- `title`: slide title.
-- `key_message`: the one idea this page must land.
-- `layout_type`: planned page structure.
-- `visual_focus`: dominant visual object or region.
-- `asset_need`: planning-only structured asset metadata; no search, download, or upload required. Follow `asset-planning.md`.
-- `text_density`: `low`, `medium`, or `high`.
-- `speaker_intent`: why the speaker needs this page and how it advances the story.
-
-## Layout Vocabulary
-
-Use one of these `layout_type` values unless the user explicitly needs a custom structure:
-
-- `title-cover`
-- `section-divider`
-- `two-column`
-- `image-left-text-right`
-- `image-right-text-left`
-- `big-number`
-- `timeline`
-- `comparison`
-- `architecture-diagram`
-- `process-flow`
-- `quote-highlight`
-- `conclusion`
-
-The value must affect XML geometry, not just appear as a label. For example, `timeline` should create a horizontal or vertical sequence, `comparison` should create distinct side-by-side regions, and `big-number` should reserve dominant space for a large metric.
-
-## Text Density Rules
-
-- `low`: title plus 1 short statement, or 1-3 very short labels.
-- `medium`: title plus 2-4 concise bullets or labeled regions.
-- `high`: allowed only when the user needs detail; use tables, columns, or grouped regions instead of a long bullet list.
-
-Do not let all pages become title + bullet slides. For decks of 4 or more pages, aim for at least 4 different `layout_type` values when the content allows it.
-
-Text density must be realistic for the planned geometry. If a page needs long titles, bilingual labels, paper figure captions, legal disclaimers, or dense technical wording, record how the text will be shortened, split, or moved to speaker notes. Do not rely on small font sizes or tight boxes to make text fit.
-
-## Visual System Planning
-
-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.
-- `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.
-
-These are planning constraints, not decoration notes. They must affect coordinates, background fills, shape styles, and text placement in generated XML.
-
-## Iterative Deck State
-
-When continuing an existing deck, update the same plan path rather than creating a new disconnected plan. Keep the plan aligned with what has actually been created.
-
-Recommended optional fields for long-running work:
-
-- `deck_status`: current slide count, target slide count if known, and last verified revision or timestamp.
-- `created_slides`: page number, slide id when known, and the page role.
-- `assets_used`: source, local path when applicable, uploaded token when known, and which page uses it.
-- `open_issues`: known layout, text fit, asset, or consistency risks that still need correction.
-
-Do not hard-code a page number just because a previous deck used that pattern. Plan by page role and evidence need, such as "method overview pages should use a figure when the source has a readable figure" instead of binding screenshots, charts, or diagrams to a fixed page index. The plan should describe decision rules, not a rigid template sequence.
-
-## 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.
-
-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.
-
-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":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Draw a simple trend line chart with axis labels and data points."}`
-
-## XML Generation Contract
-
-Before writing each slide XML, map the plan fields to concrete decisions:
-
-- `key_message` determines the headline, dominant claim, or main takeaway.
-- `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.
-
-After creating the PPT, fetch the presentation and verify:
-
-- Page count matches the plan.
-- Every page has the planned title and key message represented.
-- At least several pages have visibly different XML layout structures.
-- Planned `visual_focus` appears as a dominant visual region or object.
-- Asset planning is proportional to the deck topic and length: technical, research, product, and analytical decks should include meaningful planned visuals where they clarify the story, and each planned asset has a visible fallback if no real asset was used.
-- `text_density` is reflected in the amount of visible text.
-- Pages are not crowded, and any planned `timeline`, `comparison`, or `architecture-diagram` page uses its matching visual structure.
-- The actual backgrounds match `visual_system.background_strategy`; any dark, image-led, or emphasis page has an intentional relationship to the rest of the deck.
-- Text boxes respect `typography_constraints`; long labels, captions, footer text, and conclusion bars are not squeezed into boxes that are too short for the intended line count.
-- If real assets are used, the final XML contains renderable asset tokens or supported local placeholders for creation, not http URLs, stale local paths, or blank image boxes.

skills/lark-slides/references/slides_template_workflow.md

@@ -0,0 +1,64 @@
+# Slides Template Workflow
+
+当用户提到"模板""套用模板""参考某种主题/风格/版式"，或需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），使用本文。
+
+## 核心规则
+
+- 必须先用 `scripts/template_tool.py search` 做模板检索，默认给出 2-3 个最匹配模板候选供用户选择。
+- 锁定模板后用 `summarize` 获取主题和布局摘要。
+- 只有需要具体布局骨架时才用 `extract` 裁切目标页型 XML。
+- 不要直接读取完整模板 XML。
+- 不要照搬模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。
+
+`scripts/template_tool.py` 需要 Python 3。`references/template-index.json` 是脚本缓存/轻量路由索引，不是默认给 agent 阅读的文档；`assets/templates/*.xml` 是机器资源，只应通过脚本摘要或裁切，不要全文读取。
+
+模板细则见 [template-catalog.md](template-catalog.md)。主流程只记住：先 `search`，锁定后 `summarize`，需要骨架时才 `extract`。
+
+```bash
+python3 skills/lark-slides/scripts/template_tool.py search --query "<用户需求原文>" --limit 3
+python3 skills/lark-slides/scripts/template_tool.py summarize --template <template-id> --label <封面|目录|分节|内容|结尾>
+python3 skills/lark-slides/scripts/template_tool.py extract --template <template-id> --label <页型> --out /tmp/template-slice.xml
+```
+
+## 生成流程
+
+```text
+Step 1: 需求澄清 & 读取知识
+  - 澄清主题、受众、页数、风格
+  - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时按 SKILL.md 的设计思路先锁定视觉系统
+  - 按本文检索模板并给出候选
+
+Step 2: 生成大纲 -> 用户确认
+  - 生成结构化大纲供用户确认；如使用模板，标明基于哪个模板改写
+  - 新建 / 大幅改写必须先明确 deck 目标、受众、页序、视觉系统和每页关键消息
+  - 模板只提供风格和局部布局骨架，不要照搬无关占位内容
+
+Step 3: 按已确认大纲生成 XML -> 创建
+  - 逐页生成 XML：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
+  - 缺少真实素材时必须用 `fallback_if_missing` 生成 XML-native 兜底视觉；不要留空
+  - 创建方式按 SKILL.md 的"创建方式选择"判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
+
+Step 4: 审查 & 交付
+  - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
+  - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
+  - 没问题 -> 交付：告知用户演示文稿 ID 和访问方式
+```
+
+## 大纲格式
+
+生成大纲时使用以下格式，交给用户确认：
+
+```text
+[PPT 标题] - [定位描述]，面向 [目标受众]
+
+模板：[未使用模板 / <category>/<template>.xml（推荐原因）]
+
+页面结构（N 页）：
+1. 封面页：[标题文案]
+2. [页面主题]：[要点1]、[要点2]、[要点3]
+3. [页面主题]：[要点描述]
+...
+N. 结尾页：[结尾文案]
+
+风格：[配色方案]，[排版风格]
+```

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

@@ -1,6 +1,6 @@
 # Validation Checklist
 
-创建或大幅改写演示文稿后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
+创建或大幅改写演示文稿后，必须做一次显式验证，如果只创建空白ppt则不用验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
 
 小型已有页编辑也要做对应范围的验证：至少读取被改页面或全文 XML，确认目标元素已更新且未破坏周边结构。
 
@@ -13,8 +13,9 @@
 5. 检查没有明显空白页、破损页、缺失标题或缺失主视觉。
 6. 检查页面不是全部退化为标题加 bullet list。
 7. 检查视觉层级：标题、主视觉、支撑信息三者可区分。
-8. 检查明显溢出和布局风险：重叠、越界、底部拥挤、长文本框。
-9. 在最终回复中给出简短验证记录。
+8. QA 检查：确保视觉系统一致性，普通内容页默认复用同一明暗基调和底色体系。
+9. 检查明显溢出和布局风险：重叠、越界、底部拥挤、长文本框。
+10. 在最终回复中给出简短验证记录。
 
 回读命令：
 
@@ -44,9 +45,40 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 | `xml_not_well_formed` | XML 语法错误或文本未转义 | 修复标签闭合、属性引号、`&` / `<` / `>` 转义 |
 | `bbox_overlap` | 文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |
 
+## Screenshot QA
+
+获取页面截图后，必须使用 subagent 做视觉验收；主 agent 不要只凭 XML 回读或静态 lint 结论声称截图验收通过。验收时假设页面存在问题，主动寻找并报告所有风险，包括轻微问题。
+
+把截图路径、每页预期内容和以下中文提示交给 subagent：
+
+```text
+请逐页目视检查这些幻灯片截图。先假设存在问题，并尽量找出它们。
+
+重点检查：
+- 元素重叠：文字与形状、图片或图表互相遮挡，线条穿过文字，卡片或标签堆叠。
+- 文本溢出或被裁切：靠近页面边缘、文本框边界或卡片边界处被截断。
+- 装饰元素位置错误：分割线、强调线或标签底板按单行文字布置，但标题或正文换行后压住文字或距离异常。
+- 来源标注、页脚或页码与上方内容碰撞。
+- 元素距离过近：相邻元素间距明显不足，卡片或分区几乎贴在一起；按 960x540 画布估算，小于约 25-30 px 的间隔通常要标记。
+- 间距不均：局部留白过大，另一处过于拥挤。
+- 页面边距不足：主体内容贴近幻灯片边缘；按 960x540 画布估算，小于约 45-50 px 的外边距通常要标记。
+- 列、卡片、图标或同类元素没有稳定对齐。
+- 图片、图表或 whiteboard 渲染异常：空白、变形、低清、关键内容不可读或预期图形缺失。
+- 文本对比度不足，例如浅灰文字放在米色或浅色背景上。
+- 图标对比度不足，例如深色图标放在深色背景上，且没有浅色圆形或底板承托。
+- 文本框过窄，导致不必要的频繁换行。
+- 残留占位符、模板默认文字或未替换内容。
+
+对每一页分别列出发现的问题或可疑区域，即使只是轻微问题也要记录。
+
+报告所有发现的问题，包括轻微问题。
+```
+
+subagent 返回后，主 agent 必须根据问题严重度决定是否修复：空白页、破图、文字遮挡、明显裁切、低对比不可读、占位符残留等必须先修复再交付；轻微间距或对齐问题如果不修复，最终验证记录要说明已知风险。
+
 ## Page Count And Structure
 
-- 实际页数必须等于用户要求或 `slide_plan.json` 的页数。
+- 实际页数必须等于用户要求或已确认大纲的页数。
 - 如果创建过程部分失败，先记录已创建的 `xml_presentation_id`，再回读确认哪些页已写入。
 - 每页都应包含 `<data>`，且 `<data>` 内至少有一个非背景主体元素。
 - 封面、章节页、总结页可以文字较少，但不能只有空背景。
@@ -54,7 +86,7 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 
 ## Expected Elements
 
-按 `slide_plan.json` 和用户要求逐页核对：
+按已确认大纲和用户要求逐页核对：
 
 - 标题或主结论存在，并能对应 `key_message`。
 - `layout_type` 对应的主要结构已生成。
@@ -84,6 +116,16 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - SVG 和 Mermaid 内容的正确性无法通过回读 XML 验证，需要人工视觉验收。
 - 不要在验证记录中声称 whiteboard 内容已验证，除非用户确认了视觉效果。
 
+## Visual System Consistency
+
+逐页检查 deck 级视觉系统是否稳定：
+
+- 普通内容页默认复用同一明暗基调和底色体系；不要在深色内容页和浅色内容页之间随意跳变。
+- 只有封面、章节页、强调页、总结页可以有意改变背景明暗，并且必须保留同一主色、边栏、纹理或视觉母题。
+- 主色、背景色、正文色和强调色沿用同一套令牌；`accent` 只用于关键数字、结论或行动点。
+- 字体族、标题处理、字号层级、圆角、阴影、图标/图形风格保持同一语言。
+- 留白密度、对齐方式和页面边距稳定；不要出现某几页像另一套模板。
+
 ## Layout And Overflow Risk
 
 优先修复这些明显风险：
@@ -92,7 +134,7 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - 多个主体元素在同一区域重叠，而不是有意叠加背景。
 - 重要内容越过画布边界，或贴近底部超过 `y=500`。
 - 高密度页使用单个长 bullet list，没有分栏、表格或分组。
-- 标题、主视觉、正文的字号和颜色差异太弱，视觉层级不清。
+- 标题、主视觉、正文没有通过字号、字重、位置、留白、分组或小面积 `accent` 建立清晰层级。
 - 所有内容页都是同一套标题加 bullets 坐标。
 
 ## Verification Record

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

@@ -1,254 +0,0 @@
-# Visual Planning
-
-新建演示文稿或大幅改写页面时，在 `slide_plan.json` 完成后、生成 XML 前读取本文件。目标是让 `layout_type`、`visual_focus`、`text_density` 变成实际页面几何，而不是只写在 plan 里。
-
-默认画布按 `960 x 540` 规划。已有页面回读 XML 可以影响具体坐标，但不能覆盖这些原则：页面要有主视觉区域、文本要受密度约束、不同 `layout_type` 必须产生明显不同的坐标结构。
-
-## 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.
-- `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.
-- 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.
-
-## 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.
-- 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.
-- Insert background and motif shapes before content elements so they do not cover text, images, or diagrams.
-
-## Text Fit Guardrails
-
-Use these as conservative minimums on a 960 x 540 canvas. Increase height when using bold text, Chinese text, mixed Chinese/English, or line spacing above default.
-
-| Text use | Typical font size | Minimum height |
-|----------|-------------------|----------------|
-| 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 |
-
-Additional rules:
-
-- Do not put long Chinese sentences or long English phrases into `height=18` or `height=22` boxes. Those heights are for short labels only.
-- Footer/source text should usually be one short line. If it needs more, make it a real caption block above the footer area.
-- Bottom conclusion bars should be at least `40` px tall for one emphasized line and at least `54` px tall for two lines.
-- Diagram labels should be short enough to fit the shape. Prefer two short lines over one cramped long line.
-- When a text block has more than one `<p>`, size the box for multiple lines explicitly. Do not assume the renderer will auto-expand.
-- If a line contains mixed Chinese and English, budget more width than either language alone; mixed text wraps less predictably.
-
-## Layout Types
-
-### `title-cover`
-
-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.
-- 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.
-
-Text:
-- `low` only unless the user explicitly asks for detail.
-
-### `section-divider`
-
-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.
-
-Text:
-- Title plus one phrase. No bullets.
-
-### `two-column`
-
-Purpose: compare two related ideas or pair explanation with evidence.
-
-Geometry:
-- Split main region into two balanced columns, for example left `x=60,width=400`, right `x=500,width=400`.
-- Each column needs its own heading or visual anchor.
-- Do not place one full-width bullet box under a normal title; that is not a two-column layout.
-
-Text:
-- `medium`: 2-3 short items per column.
-- `high`: use grouped rows or mini table structure inside columns.
-
-### `image-left-text-right`
-
-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`.
-- 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.
-
-Text:
-- Keep right-side text short. Avoid more than 4 bullets.
-- For screenshot explanation pages, prefer 2-3 interpretation cards or callouts instead of a paragraph block.
-
-### `image-right-text-left`
-
-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.
-- 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:
-- Use one main claim and 2-3 supporting points.
-- Keep callouts parallel and short. If a callout needs more than two lines, split it into a separate note or a new slide.
-
-### `big-number`
-
-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`.
-- 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.
-
-Text:
-- `low` or `medium`. If detail is needed, add small annotations around the metric.
-- Supporting labels must not compete with the number. Use compact labels, legends, or mini-cards rather than long explanatory bars.
-
-### `timeline`
-
-Purpose: show sequence, roadmap, history, or phases.
-
-Geometry:
-- Create a horizontal or vertical spine with 3-6 milestones.
-- Each milestone should have a dot/card/date label connected by a line or arrow.
-- Title is separate from the sequence. The sequence is the visual focus.
-
-Text:
-- Each milestone gets a short label and optional one-line explanation.
-- Do not use paragraph-length milestone descriptions.
-
-### `comparison`
-
-Purpose: make a choice, before/after, old/new, or option tradeoff clear.
-
-Geometry:
-- Use two or three distinct panels, columns, or a table-like structure.
-- Headings must be visually aligned so differences are easy to scan.
-- Use color, border, icon, or label treatment to highlight the preferred option or key difference.
-
-Text:
-- Use parallel wording across columns.
-- Avoid uneven long bullet lists that destroy comparability.
-
-### `architecture-diagram`
-
-Purpose: explain components, dependencies, or system flow.
-
-Implementation: prefer `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` only as fallback.
-
-Geometry:
-- Main visual area should be a diagram, not prose.
-- Use grouped boxes, lanes, arrows or lines, and short labels.
-- Keep diagram labels concise. Put explanation in notes or a small side caption if needed.
-
-Text:
-- Prefer labels of 1-5 words.
-- Use no more than one short explanatory text block.
-- If a node label needs two lines, size the node and the text box for two lines. Do not let labels overlap connectors.
-
-### `process-flow`
-
-Purpose: show operational steps, workflow, or cause-effect path.
-
-Implementation: prefer `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` only as fallback.
-
-Geometry:
-- Use numbered steps connected by arrows or lines.
-- 3-5 steps is ideal for one slide. If there are more, group them into phases.
-- The flow direction must be visually obvious.
-
-Text:
-- Each step gets a verb-led label and one short descriptor at most.
-- Step labels should be parallel in length and grammar. If one step needs a long explanation, move the explanation to a side note or speaker notes.
-
-### `quote-highlight`
-
-Purpose: emphasize a customer voice, principle, thesis, or decision statement.
-
-Geometry:
-- Quote or claim is the dominant text object.
-- Use large type, generous whitespace, and optional attribution or context badge.
-- Do not combine a quote-highlight page with a normal bullet section.
-
-Text:
-- One quote or statement, plus optional attribution. No bullets.
-
-### `conclusion`
-
-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.
-
-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.
-
-## 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.
-- 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.
-- Verify the final XML contains a supported image token or creation-time local placeholder, not an unsupported external URL.
-
-## Plan To XML Checklist
-
-Before creating XML for each page, answer these checks:
-
-1. Which region is the visual focus, and is it the largest or most prominent object?
-2. Does the XML geometry match the `layout_type` description above?
-3. Does `text_density` limit the number of paragraphs, bullets, labels, and text boxes?
-4. Would this page still be recognizable if the `layout_type` label were removed from the plan?
-5. Across the deck, do multiple pages use genuinely different structures?
-6. Does the background follow the planned deck strategy, and are any deviations intentional?
-7. Are all text boxes large enough for their intended font size and line count?
-8. If the page uses a screenshot or paper figure, is it large enough to read and accompanied by concise interpretation?
-
-After fetching the created presentation, verify:
-
-- Use `timeline`, `comparison`, and `architecture-diagram` only when the content calls for them; do not force irrelevant page types.
-- Any planned `timeline`, `comparison`, or `architecture-diagram` page uses the matching sequence, side-by-side comparison, or component-and-connection structure.
-- Pages are not crowded and do not rely on long bullet boxes.
-- Main claim, supporting detail, and visual focus have clear hierarchy.
-- Static XML inspection should include text-fit risk: very short text boxes containing long text, multi-paragraph boxes with insufficient height, footer text that may wrap, and labels placed directly over connectors.
-- Background and motif consistency should be checked across pages, not only within one slide.

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

@@ -1,369 +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>`
-
-### `<chart>`
-
-图表元素必须至少包含：
-
-- `<chartPlotArea>`
-- `<chartData>`
-
-同时还可以包含：
-
-- `<chartTitle>`
-- `<chartSubTitle>`
-- `<chartStyle>`
-- `<chartLegend>`
-- `<chartTooltip>`
-
-如果要写图表 XML，建议直接以 XSD 为准，不要自行发明更简化的 chart DSL。
-
-## 样式元素
-
-### `<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

@@ -8,6 +8,8 @@
 2. `<presentation>` 直接子元素只有 `<title>`、`<theme>`、`<slide>`
 3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`
 4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下
+5. 文本中的特殊字符必须按 XML 规则转义，例如 `&` 写成 `&amp;`，`<` / `>` 写成 `&lt;` / `&gt;`
+6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"`
 
 ## 最小可用示例
 
@@ -26,6 +28,12 @@
 </presentation>
 ```
 
+## 完整示例文件
+
+- [slides_demo.xml](slides_demo.xml) - 基础完整演示文稿示例
+- [slides_chart_demo.xml](slides_chart_demo.xml) - 原生 chart 与 whiteboard 图表示例
+- [slides_timeline_demo.xml](slides_timeline_demo.xml) - 8 页时间轴设计示例，展示线性、纵向、泳道、环形、阶段、分支与指标叠加等 timeline 表达；源码路径：`skills/lark-slides/references/slides_timeline_demo.xml`
+
 ## presentation 根元素
 
 | 属性 | 必需 | 说明 |
@@ -36,6 +44,8 @@
 
 **子元素：** `<title>?`, `<theme>?`, `<slide>+`
 
+`<slide>` 至少 1 页，最多 100 页。
+
 ## slide 元素
 
 | 属性 | 必需 | 说明 |
@@ -54,6 +64,19 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 - `<theme><textStyles>...</textStyles></theme>` 中，作为主题文本样式
 - `<content textType="...">` 中，作为内容的文本类型
 
+`<theme>` 当前可包含：
+
+- `<background>` - 演示文稿级背景填充
+- `<textStyles>` - 主题文本样式集合
+
+主题文本样式常用属性：
+
+| 属性 | 说明 |
+|------|------|
+| `fontFamily` | 字体 |
+| `fontSize` | 字号 |
+| `fontColor` | 字体颜色 |
+
 `textStyles` 的 schema 默认值如下：
 
 | textType | 默认字号 |
@@ -71,12 +94,14 @@ 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` | 文本样式 |
+| `wrap` | 是否自动换行 |
 
 `<content>` 的子元素只能是：
 
@@ -84,6 +109,8 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 - `<ul>`
 - `<ol>`
 
+`<p>` 可混排纯文本和内联标签：`<br/>`、`<strong>`、`<em>`、`<u>`、`<span>`、`<del>`、`<a>`、`<shadow>`、`<outline>`。
+
 ### content 示例
 
 ```xml
@@ -117,6 +144,10 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | `width` | 是 | 宽度 |
 | `height` | 是 | 高度 |
 | `rotation` | 否 | 旋转角度 |
+| `flipX` / `flipY` | 否 | 翻转 |
+| `alpha` | 否 | 透明度 |
+
+可选子元素：`<fill>`、`<border>`、`<reflection>`、`<shadow>`、`<content>`。
 
 ### line
 
@@ -126,12 +157,16 @@ 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)。
 
 > **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。
@@ -144,6 +179,57 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 `iconType` 必须来自已验证的 IconPark 路径。需要语义图标时，先运行 `scripts/iconpark_tool.py search --query "<语义>"`，不要凭记忆拼路径。更多规则见 [iconpark.md](iconpark.md)。
 
+### table
+
+表格结构为 `<table>`，内部可包含 `<colgroup>` / `<tr>`，`<tr>` 内为 `<td>`，`<td>` 内可放 `<content>`。
+
+### chart
+
+图表元素必须至少包含 `<chartPlotArea>` 和 `<chartData>`；还可包含 `<chartTitle>`、`<chartSubTitle>`、`<chartStyle>`、`<chartLegend>`、`<chartTooltip>`。复杂 chart XML 以 XSD 为准，不要自行发明简化 DSL。
+
+完整图表类型覆盖示例见 [slides_chart_demo.xml](slides_chart_demo.xml)，其中包含柱状、条形、折线、面积、饼 / 环、雷达等原生 `<chart>` 示例，以及散点、气泡、漏斗、帕累托、瀑布等 `<whiteboard>` SVG 图表示例。
+
+典型柱状图示例：
+
+```xml
+<chart topLeftX="80" topLeftY="120" width="420" height="260">
+  <chartTitle fontSize="16" bold="true" color="rgb(31, 35, 41)">季度收入</chartTitle>
+  <chartStyle>
+    <chartBackground color="rgba(255, 255, 255, 0)"/>
+    <chartFont size="10" color="rgb(100, 116, 139)"/>
+    <chartColorTheme>
+      <color value="rgb(58, 119, 255)"/>
+      <color value="rgb(255, 126, 35)"/>
+    </chartColorTheme>
+  </chartStyle>
+  <chartLegend position="bottom" fontSize="10" color="rgb(100, 116, 139)"/>
+  <chartPlotArea>
+    <chartPlot type="column">
+      <chartBars gap="0.28"/>
+    </chartPlot>
+    <chartAxes>
+      <chartAxis type="x">
+        <chartLabel fontSize="10" color="rgb(100, 116, 139)"/>
+        <chartAxisLine/>
+      </chartAxis>
+      <chartAxis type="y" min="0">
+        <chartLabel fontSize="10" color="rgb(100, 116, 139)"/>
+        <chartGridLine width="1" color="rgb(226, 232, 240)"/>
+      </chartAxis>
+    </chartAxes>
+  </chartPlotArea>
+  <chartData>
+    <dim1>
+      <chartField name="x" valueType="string">Q1,Q2,Q3,Q4</chartField>
+    </dim1>
+    <dim2>
+      <chartField name="收入" valueType="number">42,56,48,72</chartField>
+      <chartField name="成本" valueType="number">31,38,44,51</chartField>
+    </dim2>
+  </chartData>
+</chart>
+```
+
 ### whiteboard
 
 ```xml
@@ -231,13 +317,6 @@ Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->`
 </note>
 ```
 
-## 详细参考
-
-- [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)
-
 ## Schema 版本信息
 
 - **版本**: 2.0.0