docs: tighten lark slides template preservation

2026-07-03 14:02:43 +08:00 · 2026-06-29 11:34:01 +08:00
parent c906fcac7e
commit efbb4f13e7
8 changed files with 202 additions and 50 deletions
--- a/skills/lark-slides/SKILL.md
+++ b/skills/lark-slides/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: lark-slides
 version: 1.0.0
-description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：本地 `.pptx` / `.pdf` 导入为 slides（走 `lark-drive` 的 `drive +import --type slides`）、云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。"
+description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用；当用户给定 PPTX/PDF 作为模板、底稿或视觉参考时，也用本 skill 统筹导入后的二次创作（导入命令本身走 `lark-drive` 的 `drive +import --type slides`）。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。"
 metadata:
  requires:
    bins: ["lark-cli"]
@@ -14,16 +14,17 @@ metadata:

 | 用户需求 | 优先动作 | 关键文档 / 命令 |
 |----------|----------|-----------------|
-| 新建 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` |
+| 用户提供 PDF/PPTX/slides 材料并要求生成或改写 PPT | 必须先导入/回读材料，并以导入后的 presentation 作为目标底稿二次创作；除非 PDF 明显是长文档/资料而非演示稿，不要跳过导入 | `drive +import --type slides`、`planning-layer.md`、`asset-planning.md`、`lark-slides-edit-workflows.md` |
+| 新建 PPT | 仅在没有用户提供可导入材料、用户明确要求另建，或导入失败/回读失败时，先规划 `slide_plan.json`，再按复杂度创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
+| 已有 PPT 大幅改写 | 优先用 `+replace-pages` 做页面级重建，哪怕只替换 1 页也传 1 个 page item；在完整新页 XML 里复用旧页背景、图片、图表、表格等素材 | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` |
+| 编辑单个标题、文本块、图片或局部元素 | 只有明确是小型块级编辑且拿到了最新 block_id 时才用 `+replace-slide` | `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` |
-| 用户提到模板、主题、版式 | 先检索模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` |
+| 用户提到模板、主题、版式但没有提供本地/在线模板材料 | 先检索内置模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` |
 | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |

 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。**
@@ -40,14 +41,16 @@ metadata:

 **CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**

-**CRITICAL — 如果用户提到“模板”“套用模板”“参考某种主题/风格/版式”，或用户需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），MUST 先用 [`scripts/template_tool.py`](scripts/template_tool.py) 的 `search` 做模板检索；默认给出 2-3 个最匹配模板候选供用户选择。锁定模板后用 `summarize` 获取主题和布局摘要；只有需要布局骨架时才用 `extract` 裁切目标页型 XML。不要直接读取完整模板 XML。**
+**CRITICAL — 用户提供 PPTX/PDF/slides 作为模板、底稿或视觉参考时，MUST 先导入或回读为 Slides，保存原 XML，并做素材清单：每页的 `<style>` 背景、`<img src="file_token">`、`<chart>`、`<table>`、`<whiteboard>`、关键 shape/motif。二次创作默认在同一个 `xml_presentation_id` 内用 `+replace-pages` 页面级替换；同一 presentation 内旧页的图片 file token 可在新页 XML 中复用。不要用 `slides +create` 新建脱离模板的 deck，除非导入或回读失败。**
+
+**CRITICAL — 如果用户提到“模板”“套用模板”“参考某种主题/风格/版式”，或用户需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），只有在用户没有提供本地/在线模板材料时，才用 [`scripts/template_tool.py`](scripts/template_tool.py) 的 `search` 做内置模板检索；默认给出 2-3 个最匹配模板候选供用户选择。锁定模板后用 `summarize` 获取主题和布局摘要；只有需要布局骨架时才用 `extract` 裁切目标页型 XML。不要直接读取完整模板 XML。**

 > [!NOTE]
 > `scripts/template_tool.py` 需要 Python 3。`references/template-index.json` 是脚本缓存/轻量路由索引，不是默认给 agent 阅读的文档；`assets/templates/*.xml` 是机器资源，只应通过脚本摘要或裁切，不要全文读取。

 **CRITICAL — 使用模板生成或改写页面时，MUST 先 `summarize` 目标页型；只有需要具体布局骨架时才 `extract`。**

-**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+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)。
+**编辑已有幻灯片页面**：页面级重写、导入模板二创、布局/素材保留优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内重建页面，避免 `slides +create` 生成新链接；[`+replace-slide`](references/lark-slides-replace-slide.md) 只用于单个标题、文本块、图片或局部元素的小型块级编辑。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。

 ## 身份选择

@@ -133,7 +136,9 @@ lark-cli auth login --domain slides
 - 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成 XML-native 视觉。
 - 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。

-### 创建方式选择
+### 无用户导入材料时的创建方式
+
+以下创建方式仅适用于没有用户提供可导入材料、用户明确要求另建 deck，或导入失败/`xml_presentations.get` 无法回读的异常场景。

 | 场景 | 推荐方式 |
 |------|----------|
@@ -149,7 +154,7 @@ lark-cli auth login --domain slides

 ### 模板与脚本优先流程

-模板细则见 [template-catalog.md](references/template-catalog.md)。主流程只记住：先 `search`，锁定后 `summarize`，需要骨架时才 `extract`；不要直接读取完整模板 XML 或照搬占位文案。
+模板细则见 [template-catalog.md](references/template-catalog.md)。仅在用户没有提供本地/在线模板材料时使用内置模板流程：先 `search`，锁定后 `summarize`，需要骨架时才 `extract`；不要直接读取完整模板 XML 或照搬占位文案。

 ```bash
 python3 skills/lark-slides/scripts/template_tool.py search --query "<用户需求原文>" --limit 3
@@ -159,28 +164,30 @@ python3 skills/lark-slides/scripts/template_tool.py extract --template <template

 ```text
 Step 1: 需求澄清 & 读取知识
-  - 澄清主题、受众、页数、风格；模板需求按“模板与脚本优先流程”处理
+  - 澄清主题、受众、页数、风格；没有用户提供模板材料时，模板需求按“模板与脚本优先流程”处理
  - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md
+  - 如果用户提供 PPTX/PDF/slides 附件、文件路径、素材目录或类似“附件文件路径：...”的文本，先按 asset-planning.md 解析路径；PPTX 必须导入为 slides，PDF 只在明显不是演示稿/模板时才跳过导入

 Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json
-  - 生成结构化大纲供用户确认；如使用模板，标明基于哪个模板改写
+  - 生成结构化大纲供用户确认；如使用用户附件、导入后的 slides 或模板材料，标明每类素材如何参与二次创作
  - 新建 / 大幅改写必须先创建目录并写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`
-  - plan 字段、路径命名、模板边界和 `asset_need` 结构按 planning-layer.md / asset-planning.md 执行
+  - plan 字段、路径命名、模板边界、导入底稿保留策略和 `asset_need` 结构按 planning-layer.md / asset-planning.md 执行

 Step 3: 按 slide_plan.json 生成 XML → 创建
  - 逐页消费 plan：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
+  - 如果 plan 有 `target_xml_presentation_id`，默认在该 presentation 内用 `+replace-pages` 替换页面；生成完整新页 XML 时复用源页 `<style>`、图片 file token、图表、表格、关键装饰 shape 等素材
  - 缺少真实素材时必须用 `fallback_if_missing` 生成 XML-native 兜底视觉；不要留空
-  - 创建方式按“创建方式选择”判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
+  - 只有无导入材料、用户明确要求另建，或导入失败/回读失败时，才按“无用户导入材料时的创建方式”新建 deck

 Step 4: 审查 & 交付
  - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
-  - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
+  - 失败或部分成功按 troubleshooting.md 处理；小型块级问题可用 `+replace-slide` 修正，页面级/素材保留问题继续用 `+replace-pages`
  - 没问题 → 交付：告知用户演示文稿 ID 和访问方式
 ```

 ### jq 命令模板（编辑已有 PPT 时使用）

-新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
+无用户导入材料的新建 PPT 可用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：

 ```bash
 # 追加到末尾
@@ -268,7 +275,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 | [`+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 的多页大改，不新建链接 |
+| [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内重建一个或多个页面：先创建新页到旧页前，再删除旧页；适合导入模板二创、页面级重写和素材保留，不新建链接 |

 没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。

@@ -281,13 +288,14 @@ lark-cli slides <resource> <method> [flags] # 调用 API

 ## 核心规则

-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. **用户材料默认作为二创底稿**：用户提供 PDF/PPTX/slides 材料并要求生成、改写、二创、压缩页数或保留材料风格/资产时，必须先导入或回读为 Slides；默认 `target_xml_presentation_id` 等于导入或已有材料的 `xml_presentation_id`，在该 presentation 内继续创作。“只作为模板/视觉线索”只表示不复制原文案，不表示可以跳过导入或新建脱离材料的 deck
+2. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`；模板、风格和大纲只能作为规划输入，不能绕过规划层
+3. **创建流程**：仅在没有用户提供可导入材料、用户明确要求新建 deck，或导入失败/`xml_presentations.get` 无法回读时，才使用 `slides +create` 新建目标 deck；页数多、内容不可用、只参考风格、布局复杂或 PDF 是正文资料都不是新建理由
+4. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
+5. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
+6. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
+7. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
+8. **编辑已有页面优先原链接更新**：页面级重写、导入模板二创、布局/素材保留优先用 `+replace-pages`；修改单个 shape/img 才用 `+replace-slide`（`block_replace` / `block_insert`）。不要用 `slides +create` 新建整份 PPT；不要手动编排 `slide.create` + `slide.delete` 来替代已有 shortcut
+9. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果 `file_token` 来自同一个 `xml_presentation_id` 的旧页，可以在 `+replace-pages` 的新页 XML 中直接复用；如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。

 > **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。
--- a/skills/lark-slides/references/asset-planning.md
+++ b/skills/lark-slides/references/asset-planning.md
@@ -10,9 +10,25 @@
 - 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.
+- 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 for genuinely missing new assets.
+- If the user provides PPTX/PDF/slides material and it has been imported/read back, its existing slide assets are not "missing assets." Record them in `source_asset_inventory` / `rewrite_contract` in `planning-layer.md` and reuse the original XML or file token in the replacement page.
+- `fallback_if_missing` must not replace an existing source `<img>`, `<table>`, `<chart>`, `<whiteboard>`, or locked motif. It only applies when the page needs a new asset that is absent from the source deck.
 - Do not leave blank image boxes in final XML. If the asset is missing, render the fallback visual.

+## Imported Slide Assets
+
+For imported or existing Slides rewrites, first inventory the source XML before writing new page XML. This inventory is a lock list, not a suggestion list:
+
+- Preserve `<style>` when it carries the template background, gradient, image fill, or visual tone.
+- Preserve `<img src="...">` when the image is part of the template, brand, product screenshot, chart export, decorative background, or layout.
+- Preserve `<chart>` / `<table>` when the user asked to keep data visuals or when they anchor the page design; update labels/data only if requested.
+- Preserve `<whiteboard>` position when it represents a diagram to keep, but remember readback XML may not include its inner SVG/Mermaid content.
+- Preserve recurring shape motifs such as side bars, section bands, numbered badges, separators, or card containers.
+
+When using `+replace-pages`, a reused `<img src>` from the same `xml_presentation_id` can be copied directly into the new `<slide>` content. Do not re-upload it and do not replace it with an external URL.
+
+Use `asset_need` for new desired assets. Use `source_asset_inventory` and `rewrite_contract.must_reuse` for old assets that must survive the rewrite. If an old asset should be removed, list that exact block in `rewrite_contract.discarded_blocks` with `type`, `id`, and reason; do not remove whole pages of assets with a broad "old graphics do not match" explanation.
+
 ## JSON Shape

 Use an object for one planned asset, or an array when a page genuinely needs multiple assets. Keep each item compact.
@@ -117,8 +133,9 @@ Business comparison page:

 When generating XML:

-1. If an asset exists and the workflow supports it, place it in the planned visual region.
-2. If no asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, 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.
+1. If an asset exists in the imported/current presentation and the page rewrite stays in that same `xml_presentation_id`, reuse the original XML block or file token in the planned visual region.
+2. Generate from source outward: copy source `<style>` and locked assets first, then replace placeholder text, then add new XML-native visuals.
+3. If no source or new real asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, whiteboard diagrams, or chart-like elements.
+4. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration.
+5. Keep text-density limits. Do not compensate for missing assets by adding long bullet text.
+6. After creation or replacement, fetch the presentation and verify asset pages are not blank, locked source assets are still present, and each planned fallback is visible only when no source or real asset was available.
--- a/skills/lark-slides/references/lark-slides-edit-workflows.md
+++ b/skills/lark-slides/references/lark-slides-edit-workflows.md
@@ -1,21 +1,51 @@
 # 编辑已有 PPT：读-改-写闭环

-局部编辑走 **shortcut [`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。已有 Slides 的多页整页重建走 **[`+replace-pages`](lark-slides-replace-pages.md)**，保持原 presentation 链接不变。
+页面级重写、导入模板二创、布局/素材保留优先走 **[`+replace-pages`](lark-slides-replace-pages.md)**，保持原 presentation 链接不变。只有很小的局部编辑才走 **[`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），并且必须先读原页拿最新 `block_id`。

 > 生成 XML 前**必读** [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。

-## 决策树：block_replace vs block_insert
+## 决策树：replace-pages vs replace-slide

 | 需求 | 推荐 action | 理由 |
 |------|------------|------|
+| 导入 PPTX/PDF 后二次创作、保留模板、背景、图片、图表或页面视觉语言 | `+replace-pages` | 生成完整 `<slide>`，可直接复用旧页 `<style>`、`<img src>` file token、`<chart>`、`<table>`、关键 motif，避开 block 级 patch 易失败点 |
+| 单页也要重排版式或替换大部分页面内容 | `+replace-pages`（pages 数组传 1 项） | 仓库代码命令名是复数；支持 1 个 item，按 create-before-delete-old 执行 |
+| 多页版式重建、整页坐标重排 | `+replace-pages` | 原 presentation 内批量 create-before/delete-old，不生成新 Slides 链接 |
 | 已知某块的 `block_id`，要换这块内容（改标题、换图、挪坐标） | `block_replace` | 精准替换，原子性好；`replacement` 根 `id` 由 CLI 自动注入为 `block_id` |
 | 只加 1~N 个元素、不动现有布局 | `block_insert` | 新增不覆盖，可选 `insert_before_block_id` 指定位置 |
 | 一次动多个元素（如：换标题 + 加图） | 单次 `--parts` 里拼多条 | 整批作为原子事务，任一失败整批不生效；`block_replace` 和 `block_insert` 可混用 |
-| 多页版式重建、整页坐标重排 | `+replace-pages` | 原 presentation 内批量 create-before/delete-old，不生成新 Slides 链接 |

 > **没有字段级 patch**：即便只想改一个 `shape` 的 `topLeftX`，也得把整个块的新 XML 写出来用 `block_replace`。这不是"微调"，是块级重写。

-## 最小读-改-写闭环
+## 导入 PPTX/PDF 后的保模板流程
+
+1. 用 `drive +import --type slides` 导入 PPTX/PDF；PPTX 必须导入，PDF 只有明显不是演示稿/模板时才跳过。
+2. 用 `xml_presentations.get` 回读导入后的 XML，保存到 `.lark-slides/plan/<id>/source.xml`。
+3. 为每页列 `source_asset_inventory`：`<style>`、`<img src>`、`<chart>`、`<table>`、`<whiteboard>`、关键 shape/motif 和 bbox。源素材默认是 locked assets。
+4. 在 `slide_plan.json` 里设置 `target_xml_presentation_id`，每页记录 `source_slide_id`、`rewrite_mode: "preserve_template"` 和 `rewrite_contract`。
+5. 生成完整新 `<slide>`：先复制源页 `<style>` 和 locked assets，再替换文案、调整布局、删除逐块列明的模板占位文字，最后补充新业务图形。
+6. 组装 `pages.json`，每项包含旧页 `slide_id` 和完整新页 `content`。
+7. 先跑 `+replace-pages --validate-only` 或 dry-run，再执行 `+replace-pages`。
+8. 回读全文 XML，核对 locked assets、图片 token、图表、表格、背景和页数；如果账号具备截图能力，可额外截图检查视觉效果。
+
+不要从空 `<slide>` 重画后再按感觉补素材。模板二创不是"复用 slide_id 的新 deck"，而是在源页 XML 之上做保留式改写。
+
+`rewrite_contract.discarded_blocks` 必须逐块列出 `type`、`id` 和原因。`discarded_blocks.type = "all"` 默认禁止；只有用户明确要求不保留模板素材或只参考风格重做时，才允许 `rewrite_mode: "style_reference_only"`，并在 plan 中记录用户原话或等价证据。
+
+`+replace-slide` 不作为导入模板二创主路径。它依赖当前页 `block_id`、单根 XML 片段和后端 block replace 约束，出现 3350001 时需要重新读页和修片段；页面级二创通常用 `+replace-pages` 更稳。
+
+最小 `pages.json` 形态：
+
+```json
+[
+  {
+    "slide_id": "old_slide_id",
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style>...</style><data>...</data></slide>"
+  }
+]
+```
+
+## 小型块级编辑闭环

 ```bash
 PID="xml_presentation_id_here"
--- a/skills/lark-slides/references/lark-slides-replace-pages.md
+++ b/skills/lark-slides/references/lark-slides-replace-pages.md
@@ -1,9 +1,11 @@
-# slides +replace-pages（多页整页重建）
+# slides +replace-pages（页面级重建）

-批量替换已有演示文稿里的多个页面，保持原 `xml_presentation_id` 和原 Slides 链接不变。适合多页版式大改、坐标重排、整页视觉重建；单个文本框、图片或 shape 的局部编辑仍优先用 [`+replace-slide`](lark-slides-replace-slide.md)。
+批量替换已有演示文稿里的一个或多个页面，保持原 `xml_presentation_id` 和原 Slides 链接不变。适合导入 PPTX/PDF 后二次创作、保留模板素材、版式大改、坐标重排、整页视觉重建；单个文本框、图片或 shape 的小型局部编辑才考虑 [`+replace-slide`](lark-slides-replace-slide.md)。

 > 重要：这是多步编排，不是后端原子事务。CLI 对每页执行“先创建新页到旧页前，再删除旧页”；创建失败时旧页会保留。删除失败时可能出现新旧页同时存在，需要按返回结果继续处理。

+> 命令名以仓库代码为准：当前 shortcut 是 `slides +replace-pages`（复数）。即使只替换一页，也传一个包含 1 个 item 的 `pages` 数组。
+
 ## 命令

 ```bash
@@ -45,6 +47,26 @@ lark-cli slides +replace-pages \
 - 同一批次不能重复 `slide_id`。
 - CLI 不会回读整份 presentation；如果 `slide_id` 已失效，create/delete 阶段会返回对应错误。

+## 保留导入模板素材
+
+导入 PPTX/PDF 或改写已有 Slides 时，先用 `xml_presentations.get` 保存当前 XML，再为每页盘点素材。源素材默认锁定保留，不是可随意替换的装饰：
+
+- `<style>`：页面背景、渐变、底色或图片底纹。
+- `<img src="...">`：同一个 `xml_presentation_id` 内的 file token 可直接复制到新页 XML。
+- `<chart>` / `<table>`：优先保留原结构；只在用户要求时改数据或标签。
+- `<whiteboard>`：可保留外层位置；注意回读 XML 可能不包含内部 SVG/Mermaid。
+- 关键 shape/motif：侧边栏、分节条、卡片底、编号徽章、分割线等模板视觉语言。
+
+在 `slide_plan.json` 中把这些事实写入 `source_asset_inventory`，并在每页 `rewrite_contract.must_reuse` 中绑定要保留的 locked assets。生成 replacement `content` 时，顺序必须是：
+
+1. 先复制源页 `<style>` 和 locked assets。
+2. 再替换模板占位文案和必要布局。
+3. 最后补充新业务图形。
+
+不要从空 `<slide>` 重画后再按感觉补素材。不要把导入底稿当成普通参考后重新 `slides +create` 一份脱离素材的新 deck。
+
+`discarded_blocks` 只能逐块删除源元素，必须写 `type`、`id` 和原因。`discarded_blocks.type = "all"` 默认非法；只有用户明确要求"不保留模板素材"或"只参考风格重做"时，才允许 `rewrite_mode: "style_reference_only"`。
+
 ## Dry Run

 ```bash
@@ -90,6 +112,7 @@ lark-cli slides +replace-pages --as user \
 ## 使用建议

 1. 大幅改写前先 `xml_presentations.get` 保存当前 XML，并记录要替换页面的 `slide_id`。
-2. 生成只含 `slide_id` 的 `pages.json` 后先跑 `--dry-run` 或 `--validate-only`。
-3. 默认不要开 `--continue-on-error`，除非能接受部分页面已替换。
-4. 替换后再回读全文 XML 并截图检查，确认页序、视觉和文本没有破损。
+2. 导入模板二创时，先在 plan 中记录每页要复用的背景、图片 token、图表、表格和 motif，再生成完整新页 XML。
+3. 生成只含 `slide_id` 和完整 `<slide>` content 的 `pages.json` 后先跑 `--dry-run` 或 `--validate-only`。
+4. 默认不要开 `--continue-on-error`，除非能接受部分页面已替换。
+5. 替换后再回读全文 XML，确认页序、背景、图片、图表、表格、locked motif 和文本没有破损；如果当前账号具备截图能力，可额外截图检查视觉效果。
--- a/skills/lark-slides/references/lark-slides-replace-slide.md
+++ b/skills/lark-slides/references/lark-slides-replace-slide.md
@@ -2,7 +2,9 @@

 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

-对指定 slide 做块级替换或插入。编辑已有 PPT 的主路径——`slide_id` 不变、页序不动、只影响被指定的块。
+对指定 slide 做块级替换或插入。适合小型局部编辑：`slide_id` 不变、页序不动、只影响被指定的块。
+
+导入 PPTX/PDF 后二次创作、模板素材保留、整页布局重建不要默认用本 shortcut；优先用 [`+replace-pages`](lark-slides-replace-pages.md) 生成完整新页 XML，并在同一个 presentation 内复用旧页背景、图片 file token、图表、表格和 motif。

 相比直接调 `xml_presentation.slide.replace`，这个 shortcut 的四个额外价值：

--- a/skills/lark-slides/references/planning-layer.md
+++ b/skills/lark-slides/references/planning-layer.md
@@ -7,16 +7,34 @@
 ## Required Flow

 1. 理解用户需求，必要时澄清主题、受众、页数、风格。
-2. 如果适合模板，先用 `template_tool.py search` 检索，锁定模板后用 `summarize` 获取主题和页型信息。
-3. 选择唯一 plan 目录：`.lark-slides/plan/<deck-or-task-id>/`。
-4. 先创建目录：`mkdir -p .lark-slides/plan/<deck-or-task-id>`。
-5. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
-6. 读取 `xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。
-7. 按 plan、visual planning 和 asset planning 规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束，并把缺失素材转成可执行兜底视觉。
-8. 创建 PPT 后用 `xml_presentations.get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
+2. 如果用户给了 PPTX/PDF/slides 材料，先导入或回读为 Slides；PPTX 必须导入，PDF 只有在明显是长文档/资料而不是演示稿、模板或视觉底稿时才跳过导入。
+3. 如果没有用户提供的模板材料、且适合内置模板，再用 `template_tool.py search` 检索，锁定模板后用 `summarize` 获取主题和页型信息。
+4. 选择唯一 plan 目录：`.lark-slides/plan/<deck-or-task-id>/`。
+5. 先创建目录：`mkdir -p .lark-slides/plan/<deck-or-task-id>`。
+6. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
+7. 读取 `xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。
+8. 按 plan、visual planning 和 asset planning 规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束；只有缺失的新素材才转成可执行兜底视觉，源页素材不算缺失素材。
+9. 创建或替换后用 `xml_presentations.get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。

 模板不能代替 plan。模板搜索和摘要只能影响 `theme_style`、页面流、布局选择和局部布局骨架；最终仍必须有 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。

+## Imported Deck Preservation
+
+当用户提供 PPTX/PDF/slides 作为模板、底稿、版式参考或二创对象时，plan 必须把导入后的 presentation 当成目标，而不是把它当成普通参考图。
+
+流程：
+
+1. 先用 `drive +import --type slides` 导入本地 PPTX/PDF，或用 `xml_presentations.get` 回读已有 Slides。
+2. 保存导入/回读 XML 到 plan 目录，记录 `target_xml_presentation_id`、`revision_id`、每页 `slide_id`。
+3. 做每页 `source_asset_inventory`：`<style>` 背景、`<img src="...">` file token、`<chart>`、`<table>`、`<whiteboard>`、关键 shape/motif 和它们的 bbox。这个清单是事实层，来自 `source.xml`，不要用模型偏好改写事实。
+4. 写 plan 时为每个目标页绑定 `source_slide_id`，并写 `rewrite_contract`。默认 `reuse_policy` 是 `preserve_by_default`：源页素材默认锁定保留。
+5. 生成完整 `<slide>` XML 时，先复制源页 `<style>` 和 locked assets，再替换模板占位文案，最后补充新业务图形。
+6. 默认用 `slides +replace-pages` 执行页面级替换。仓库代码中的命令名是复数 `+replace-pages`；即使只替换一页，也传一个包含 1 个 item 的 `pages` 数组。
+
+`+replace-slide` 只适合小型块级编辑：改一个标题、插入一个图、替换一个已知 block。导入模板二创不要默认走它，因为它依赖最新 `block_id` 和局部 XML 片段，更容易触发 3350001。
+
+禁止把模板二创理解成"按模板风格重画"。`discarded_blocks` 必须逐块列出 `type`、`id` 和具体原因；`discarded_blocks.type = "all"` 默认非法。只有用户明确说"不要保留模板素材"、"只参考风格重做"等同义要求时，才允许 `rewrite_mode: "style_reference_only"`，并必须在 plan 中记录 `user_intent_evidence`。
+
 ## Plan Path

 Use a separate plan directory per deck or task so multiple presentations in the same workspace cannot overwrite each other.
@@ -56,6 +74,27 @@ Exception:
 ```json
 {
  "presentation_goal": "Explain the proposal and secure approval for the next phase.",
+  "target_xml_presentation_id": "optional existing/imported presentation id for in-place rewrite",
+  "source_deck": {
+    "source_type": "pptx|pdf|slides|none",
+    "source_path_or_url": "optional original user material",
+    "source_xml_path": ".lark-slides/plan/example/source.xml",
+    "source_slide_count": 12
+  },
+  "source_asset_inventory": {
+    "generated_from": ".lark-slides/plan/example/source.xml",
+    "default_policy": "preserve_by_default",
+    "pages": [
+      {
+        "source_slide_id": "old1",
+        "locked_assets": [
+          {"type": "style", "id": "slide-style", "reason": "template background"},
+          {"type": "img", "id": "bPk", "src": "file_token", "reason": "template hero visual"},
+          {"type": "shape", "id": "bQr", "role": "motif", "reason": "layout structure"}
+        ]
+      }
+    ]
+  },
  "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": {
@@ -83,6 +122,15 @@ Exception:
    {
      "page": 1,
      "title": "Proposal Title",
+      "source_slide_id": "optional original slide id when rewriting an imported/existing deck",
+      "rewrite_mode": "preserve_template",
+      "rewrite_contract": {
+        "reuse_policy": "preserve_by_default",
+        "must_reuse": ["style:slide-style", "img:bPk", "shape:bQr"],
+        "discarded_blocks": [
+          {"type": "shape", "id": "bAb", "reason": "template placeholder text"}
+        ]
+      },
      "key_message": "The initiative is ready for a focused pilot.",
      "layout_type": "title-cover",
      "visual_focus": "Large title area with one concise supporting statement.",
@@ -104,6 +152,9 @@ Exception:
 Top-level fields:

 - `presentation_goal`: what the whole deck is trying to achieve.
+- `target_xml_presentation_id`: required when rewriting an imported or existing deck in place.
+- `source_deck`: required when user-provided PPTX/PDF/slides material was imported or read back.
+- `source_asset_inventory`: required when `source_deck.source_type` is `pptx`, `pdf`, or `slides`; record source-page assets before planning new page XML.
 - `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.
@@ -115,6 +166,9 @@ Each slide must include:

 - `page`: 1-based page number.
 - `title`: slide title.
+- `source_slide_id`: required when this page rewrites an imported/existing page.
+- `rewrite_mode`: `preserve_template` by default for imported/existing deck rewrites; use `style_reference_only` only when the user explicitly asked not to preserve template assets.
+- `rewrite_contract`: required when `source_slide_id` is present; list locked source assets to reuse and any individually discarded source blocks.
 - `key_message`: the one idea this page must land.
 - `layout_type`: planned page structure.
 - `visual_focus`: dominant visual object or region.
@@ -204,6 +258,8 @@ Before writing each slide XML, map the plan fields to concrete decisions:
 - `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.
+- `source_asset_inventory` determines which source XML blocks are locked by default. Copy source `<style>`, `<img src>` file tokens, charts, tables, whiteboards, and key motif shapes before generating new business visuals.
+- `rewrite_contract.discarded_blocks` only removes individually named source blocks. Do not use `type: "all"` unless `rewrite_mode` is `style_reference_only` and `user_intent_evidence` records the user's explicit instruction.

 After creating the PPT, fetch the presentation and verify:

@@ -217,3 +273,4 @@ After creating the PPT, fetch the presentation and verify:
 - 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.
+- For imported/template rewrites, replacement/readback XML still contains locked source assets from `source_asset_inventory`, especially background style, image tokens, charts, tables, whiteboards, and recurring motif blocks. If a locked source asset disappears, the plan must contain a block-level discard reason.
--- a/skills/lark-slides/references/troubleshooting.md
+++ b/skills/lark-slides/references/troubleshooting.md
@@ -21,7 +21,7 @@
 4. 检查标签闭合、属性引号、`<content>` 结构，以及 `<slide>` 直接子元素。
 5. 页面空白、溢出、重叠或越界时，按 [validation-checklist.md](validation-checklist.md) 运行 XML 文本重叠检查，并人工核对越界、截断、图文压盖等视觉风险；工具当前只会报告 `xml_not_well_formed` / `bbox_overlap`。
 6. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide.create` 逐页添加。
-7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时再用 `slide.delete` 旧页 + `slide.create` 新页。
+7. 小型局部问题用 `+replace-slide` 块级修正；整页结构要改、导入模板二创或需要保留页面素材时，用 `+replace-pages`，不要手写 `slide.delete` + `slide.create` 编排。

 ## Symptom Fixes

--- a/skills/lark-slides/references/validation-checklist.md
+++ b/skills/lark-slides/references/validation-checklist.md
@@ -14,7 +14,8 @@
 6. 检查页面不是全部退化为标题加 bullet list。
 7. 检查视觉层级：标题、主视觉、支撑信息三者可区分。
 8. 检查明显溢出和布局风险：重叠、越界、底部拥挤、长文本框。
-9. 在最终回复中给出简短验证记录。
+9. 如果是导入 PPTX/PDF/slides 后二创，必须做 XML 级素材核对：`source_asset_inventory` / `rewrite_contract.must_reuse` 中的 locked assets 是否仍在 replacement 或回读 XML 中。
+10. 在最终回复中给出简短验证记录。

 回读命令：

@@ -61,6 +62,17 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - `visual_focus` 是页面中最醒目或最大的信息区域之一。
 - `text_density` 影响了文本量，没有用长 bullet 框替代规划。
 - `asset_need` 有真实素材时已放入正确区域；没有真实素材时，`fallback_if_missing` 已用 XML 形状、线条、标签、表格或图表兜底。
+- 导入/模板二创任务中，`source_asset_inventory` 里的 `<style>`、`<img src>`、`<chart>`、`<table>`、`<whiteboard>` 或 motif shape 已在最终 XML 中保留，除非 `rewrite_contract.discarded_blocks` 逐块标记了 `type`、`id` 和原因。
+
+## Source Asset Preservation
+
+模板二创默认 `reuse_policy: "preserve_by_default"`。验证时不要只看新页是否有视觉元素，还要核对源素材是否被保留：
+
+- 源页 locked assets 必须出现在 `pages.json` replacement XML 或最终回读 XML 中。
+- 如果源页存在 `<img>`、`<table>`、`<chart>`、`<whiteboard>` 或关键 motif，replacement 里对应类型数量明显归零，且 plan 没有逐块 discard，视为失败。
+- `discarded_blocks.type = "all"` 默认不是有效说明。只有 `rewrite_mode: "style_reference_only"` 且 plan 记录了用户明确要求不保留模板素材时，才可接受。
+- `fallback_if_missing` 不能解释源素材消失；它只适用于源页没有可用素材时的新资产兜底。
+- 截图检查是可选增强能力，不是默认必需项；没有截图能力时，至少完成 XML 级素材核对。

 如果用户指定了关键页，例如“架构解释”“Self-Attention 机制解释”“对比或演进视角”“总结页”，最终验证记录必须逐项说明这些页已存在。

@@ -72,6 +84,8 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - 关键文本没有出现在回读 XML 中。
 - 图片仍是 `@./path`，或 `<img src>` 是 http(s) 外链。
 - 页面依赖的图片区域为空，且没有 fallback visual。
+- 导入模板的背景、核心图片、图表、表格或品牌/版式 motif 在最终 XML 中消失，且 plan 没有逐块说明丢弃原因。
+- 源页有 `<img>` / `<table>` 等素材，replacement 或最终回读 XML 中对应类型数量归零，且没有 `style_reference_only` 用户意图证据。
 - 返回 XML 缺页、页序明显错误，或某页内容被 shell 截断。
 - 大量形状坐标完全相同，导致主体内容重叠。
 - 渐变背景回退成空白或白底，导致文字不可读。
@@ -104,7 +118,8 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - 回读：已执行 xml_presentations.get，实际页数 N / 预期 N。
 - 关键页：架构解释 / Self-Attention / 对比或演进 / 总结页均存在。
 - 结构：检查了主要 shape/img/table/chart 元素，无明显空白页或破损页。
+- 素材：已核对 source_asset_inventory / rewrite_contract.must_reuse，导入底稿的背景、图片 token、图表/表格或 motif 已按 plan 保留；被删除素材均有逐块 discarded reason。
 - 布局：检查了标题层级、主视觉、重叠/越界/文本溢出风险。
 ```

-不要声称完成了人工视觉验收，除非确实打开或获取了可视化结果。仅从 XML 静态检查得出的结论，应表述为“静态检查未发现明显问题”。
+不要声称完成了人工视觉验收，除非确实打开或获取了可视化结果。仅从 XML 静态检查得出的结论，应表述为“静态检查未发现明显问题”。截图能力可能不可用，不要把截图作为默认交付门槛。