docs: refine lark-slides imported material workflow

2026-07-08 02:00:19 +08:00 · 2026-06-23 19:07:44 +08:00
parent 2c302810f7
commit 50d5b38b18
4 changed files with 116 additions and 69 deletions
--- a/skills/lark-slides/SKILL.md
+++ b/skills/lark-slides/SKILL.md
@@ -14,7 +14,8 @@ metadata:

 | 用户需求 | 优先动作 | 关键文档 / 命令 |
 |----------|----------|-----------------|
-| 新建 PPT | 先解析并盘点用户附件，规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
+| 用户提供 PDF/PPTX/slides 材料并要求生成或改写 PPT | 必须先导入/回读材料，并以导入后的 presentation 作为目标底稿二次创作；即使材料“只作为模板/视觉线索”，也要在导入后的 presentation 内替换内容模块 | `drive +import --type slides`、`planning-layer.md`、`asset-planning.md` |
+| 新建 PPT | 仅在没有用户提供可导入材料、用户明确要求另建，或导入失败/回读失败时，先解析并盘点用户附件，规划 `slide_plan.json`，再按复杂度创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
 | 大幅改写页面 | 先回读现有 XML，写入新 plan，再替换或重建相关页面 | `xml_presentations.get`、`+replace-slide`、`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` |
@@ -23,7 +24,7 @@ metadata:
 | 在 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 为准。**
@@ -37,7 +38,7 @@ metadata:
 > [!NOTE]
 > `scripts/template_tool.py` 需要 Python 3。`references/template-index.json` 是脚本缓存/轻量路由索引，不是默认给 agent 阅读的文档；`assets/templates/*.xml` 是机器资源，只应通过脚本摘要或裁切，不要全文读取。

-使用模板生成或改写页面时，先 `summarize` 目标页型；只有需要具体布局骨架时才 `extract`。
+使用内置模板生成或改写页面时，先 `summarize` 目标页型；只有需要具体布局骨架时才 `extract`。如果用户已经提供本地/在线模板材料，优先按用户材料导入二创，不走内置模板检索。

 **编辑已有幻灯片页面**：优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。

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

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

 | 场景 | 推荐方式 |
 |------|----------|
@@ -139,7 +142,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
@@ -149,19 +152,19 @@ 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
  - 如果用户提供附件、文件路径、素材目录或类似“附件文件路径：...”的文本，先按 asset-planning.md 解析路径、枚举文件、读取/导入/上传可用素材；不要直接跳到大纲或 XML

 Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json
-  - 生成结构化大纲供用户确认；如使用用户附件、导入后的参考 slides 或模板，标明每类素材如何参与二次创作
+  - 生成结构化大纲供用户确认；如使用用户附件、导入后的 slides 或模板材料，标明每类素材如何参与二次创作
  - 新建 / 大幅改写必须先创建目录并写入 `.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 执行
+  - 如果 plan 有 `target_xml_presentation_id`，默认在该 presentation 内创建、替换或删除页面；只有无导入材料、用户明确要求另建，或导入失败/回读失败时，才按“无用户导入材料时的创建方式”新建 deck

 Step 4: 审查 & 交付
  - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
@@ -171,7 +174,7 @@ Step 4: 审查 & 交付

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

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

 ```bash
 # 追加到末尾
@@ -271,13 +274,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`），不要整页重建；只有需要替换整页结构时才用 `slide.delete` + `slide.create`
-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. **编辑已有页面优先块级替换**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；只有需要替换整页结构时才用 `slide.delete` + `slide.create`
+9. **`<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>` 输出不一致，以后两者为准。
--- a/skills/lark-slides/references/asset-planning.md
+++ b/skills/lark-slides/references/asset-planning.md
@@ -10,11 +10,11 @@
 ## Core Rules

 - 本地素材优先。用户给了文件、目录、截图、PDF、PPTX、文案、数据表、链接或已有 slides 时，先按 Attachment Resolution 解析并盘点用途；禁止忽略附件直接生成大纲或 XML。
- 没有合适本地素材时，才考虑联网搜索、内置模板、IconPark 或 XML-native 兜底。联网搜索只用于确实需要外部事实、图片、logo、公开截图或背景补充的场景。
+- 没有合适本地素材时，才考虑联网搜索、内置模板、IconPark 或 XML-native 兜底。用户已提供模板材料时，这些能力只能补缺，不能替代导入后的目标 presentation 或主视觉系统。
 - 素材进入 plan 前必须分类并写清用途；不要把“有文件”直接等同于“应出现在页面上”。
 - 页面不能依赖不可获得素材才能完成。每个 `asset_need` 都必须有 `fallback_if_missing`。
 - 真实图片进入 slides 前必须走支持的上传路径：`slides +media-upload` 或 `+create --slides` 的 `@./path` 占位符。禁止把 http(s) 外链直接写进 `<img src>`。
- `.pptx` / `.pdf` 被用户称为模板、风格参考、参考 PPT、教案 PPT、品牌手册、研究报告或含有页面截图/图表时，按 Local Material Handling 判断是否导入回读，用作二次创作素材。导入是写操作；如果用户已经明确要求“根据附件制作 PPT”，可视为已有意图，否则先确认。
+- `.pptx` / `.pdf` / online slides 参与制作或改写 PPT 时，按 Local Material Handling 先判断 `rewrite_source` / `copy_source`；可作为视觉底稿的材料必须导入或回读为 slides。

 ## Attachment Resolution

@@ -34,7 +34,7 @@

 - 文档/表格/图片/PPT/PDF 至少要记录 `source`、`resolved_path`、`kind`、`usage`、`status`。
 - 如果素材会进入页面，`asset_need.candidate_sources` 必须使用解析后的可用路径，而不是原始不可用的路径文本。
- 如果素材只用于理解或风格参考，也必须在 `material_inventory.inputs` 中出现，避免后续 XML 生成阶段遗忘。
+- 如果素材只用于理解或提供视觉线索，也必须在 `material_inventory.inputs` 中出现，避免后续 XML 生成阶段遗忘。

 ## Material Roles

@@ -42,13 +42,14 @@

 | Role | 用途 | 常见来源 | 默认处理 |
 |------|------|----------|----------|
-| `background_reference` | 补充主题背景、事实、约束、术语、受众信息 | PDF、文档、网页、PRD、报告、会议纪要 | 读取/摘要后影响叙事和页面重点 |
-| `style_reference` | 参考 PPT 风格、配色、版式、字体层级、页面流 | PDF、PPTX、已有 slides、内置模板 | 提取设计语言，不默认复制正文 |
+| `background_reference` | 补充主题背景、事实、约束、术语、受众信息 | 文档、网页、PRD、报告、会议纪要 | 读取/摘要后影响叙事和页面重点 |
 | `visual_asset` | 可直接进入页面的视觉素材 | 图片、截图、logo、图表、论文 figure | 上传后放入计划区域；不合适则重绘或兜底 |
 | `copy_source` | 文案、标题、大纲、讲稿、卖点、结论来源 | Markdown、TXT、Docx、用户 prompt、会议纪要 | 改写成低密度 slide 文案 |
 | `data_source` | 生成表格、指标卡、图表的数据来源 | CSV、XLSX、表格截图、结构化数据 | 转成 chart/table/数字卡 |
 | `brand_asset` | 品牌识别和视觉约束 | logo、VI 色板、品牌手册 | 影响 `theme_style` / `visual_system` |
-| `rewrite_source` | 需要在原内容、页序或框架基础上二次创作的原稿 | 用户已有 PPTX/PDF/slides、旧版汇报、待美化稿 | 导入/回读后逐页规划保留、精简、新增和重排 |
+| `rewrite_source` | 导入后承载二次创作的目标底稿 | 用户已有 PPTX/PDF/slides、背景模板、旧版汇报、待美化稿 | 导入/回读后作为 target presentation，规划保留、替换、删除和重排 |
+
+PDF/PPTX/slides 的主角色只能是 `rewrite_source` 或 `copy_source`。如需表达背景、视觉或品牌信息，只写进 `usage`，不能改变目标 presentation。

 ## Source Priority

@@ -63,15 +64,39 @@

 ## Local Material Handling

- `.pptx`：如果是模板或风格参考，先用 `lark-cli drive +import --type slides` 导入为 online slides，再用 `slides xml_presentations.get` 回读 XML，提取页面流、配色、背景、字体层级、布局骨架和 motif。先判断模板是否包含需要复用的背景图、装饰图、品牌图片或复杂图片版式：如果需要复用，优先把导入后的 slides 作为工作底稿做局部编辑，保留原有图片 token；如果只需要风格和布局骨架，再新建 XML-native 页面。默认不复制模板原文案；如果用户要求“结合模板内容”，再按页角色提取可复用结构。
- `.pptx` 作为待改写原稿：当用户说“在此基础上”“调整布局”“美化”“精简”“增加目录”“内容不用改”“不要随便修改内容”“保留框架”“已有一版 PPT”“根据这份 PPT 生成/丰富/修改”时，该 PPTX 不只是 `style_reference`，必须同时作为 `rewrite_source`。导入并回读全文 XML 后，规划时逐页说明原内容哪些保留、哪些精简、哪些新增、哪些重排。用户明确要求“内容不用改”或“不要随便修改内容”时，默认只改布局、视觉层次、图片/图表表达和页间组织，不改事实、数值和主要文案。优先保留导入页上的既有图片资产并做局部编辑；整页结构变化、换模板或导入页块级编辑不可靠时，才按源页重建 XML-native 页面，再替换或删除旧页。
- `.pdf`：如果是模板、品牌手册或包含可复用页面视觉，先用 `lark-cli drive +import --type slides` 导入并回读 XML，提取视觉系统或页面骨架；如果是论文、报告、PRD 或正文资料，先按内容角色读取/摘要。含可复用 figure/logo/品牌色时，优先作为 `visual_asset` 或 `brand_asset`，不能只用作普通背景文字。
- 已有 online slides：直接回读 XML，把它作为 `style_reference` 或 `rewrite_source`；不要再走导入。
+- `.pptx` / `.pdf` / online slides 若承担模板、背景模板、旧稿、待美化稿、品牌视觉或页面结构角色，默认是 `rewrite_source`：先导入或回读为 slides，`target_xml_presentation_id` 默认等于导入/已有 presentation，并在同一个 presentation 内创建、替换、删除或重排页面。
+- “内容不可用”“只作为背景模板”“不要使用模板文字”“只参考风格”只表示该材料不是 `copy_source`；它仍默认是 `rewrite_source`，用于保留或重绘背景、版式、图片资产和页面结构。
+- `.pdf` 若只是论文、报告、PRD、教案正文等内容资料，可以作为 `copy_source` 读取/摘要；但 `copy_source` 不得替代已有 `rewrite_source`，也不得成为新建 deck 的理由。
+- 用户明确说“只参考风格”时，不新增单独角色；仍把 PDF/PPTX/slides 作为 `rewrite_source` 导入/回读，只在 `usage` 中说明“不复制模板文案，仅沿用或重绘风格、版式和页面结构”。
+- 已有 online slides：直接回读 XML，默认把它作为 `rewrite_source`；不要再走导入。
 - `.png` / `.jpg` / `.jpeg` 等图片：判断是可直接展示、需要裁切/缩放、还是只用于理解。进入 XML 前必须上传或使用 `@./path` 占位符。
 - `.md` / `.txt` / 文档类内容：作为 `copy_source` 或 `background_reference`，提炼为低密度页面文案，不要整段搬进 slide。
 - `.docx` / `.doc`：通常是 `copy_source` 和 `background_reference`。先读取或转换提取正文、标题层级、表格和内嵌图片线索，再改写为 slide 叙事。用户要求“不要杜撰数据”时，数值和图表只能来自这类源文件或表格源；缺数据则在 plan 中标注缺口。
 - `.xlsx` / `.xls` / `.csv`：通常是 `data_source`。先识别工作表、列名、时间范围、指标和关键数值，再规划 `<chart>` / 表格 / 数字卡。用户明确要求精准图表时，必须让图表数据来自表格，不要手工编造。

+## PDF Template Pre-slicing
+
+大 PDF 模板用于二次创作时，可以先切出关键模板页生成小 PDF，再用 `drive +import --type slides` 导入小 PDF。这样减少导入和回读成本，同时仍保留在导入后的 presentation 内二创的主路径。
+
+仅在同时满足这些条件时才切割：
+
+- 任务是制作、改写、二创、压缩页数或替换内容模块，而不是单纯导入 PDF。
+- PDF 是 `rewrite_source`，只需要其中的视觉骨架、背景、版式、图片资产或页面结构。
+- 已能明确选择关键页，例如封面、目录、章节页、图谱/流程页、表格页、结尾页，通常保留 6-10 页或用户指定页。
+
+禁止切割的场景：
+
+- 用户只要求“导入 PDF 为 slides”“转换格式”“保留完整 PDF”“检查导入效果”。
+- 用户要求保留全部页序、全部页面内容或逐页迁移。
+- 无法判断关键页，且切割会丢失用户可能需要的视觉结构。
+
+切割后在 `material_inventory.inputs[]` 中记录原 PDF 和压缩 PDF 的关系：
+
+- 原 PDF 仍记录为 `source`，`usage` 说明只取关键视觉页。
+- 压缩 PDF 记录为实际导入对象，`status: "preprocessed"` 或 `"imported"`。
+- 记录 `selected_pages`、`preprocessed_path`、选择理由，以及后续导入得到的 `imported_xml_presentation_id` / `target_xml_presentation_id`。
+- 生成新页并回读成功后，再按计划删除或替换导入模板中的旧内容页。
+
 ## Image Asset Migration

 导入的 PPTX/PDF 页面里可能已有 `<img src="file_token">`、背景图或品牌图。这些图片 token 可以在同一个导入后的 presentation 内复用；只有跨到另一个新建 presentation 时，才不能直接复制旧 XML 里的 `<img src>`。
@@ -80,29 +105,27 @@

 - `preserve_imported_page`：模板页含需要复用的背景图、装饰图、品牌图或复杂图片版式。优先在导入页上用 `+replace-slide` / `block_insert` / `block_replace` 做局部编辑，保留现有 `<img>` token。
 - `rebuild_in_imported_presentation`：需要重做 XML-native 页面，但仍在同一个导入后的 presentation 内创建/替换页面。可以复用该 presentation 内已有图片 token，无需下载再上传；删除旧页前先确认新页已创建成功。
- `rebuild_new_presentation`：需要另建一个新 presentation。若要复用导入页图片，必须先把图片下载到本地，再上传到目标演示文稿，或在 `+create --slides` 中使用 `@./relative/path` 占位符让 CLI 为新文稿上传并替换 token。
 - `mixed`：同一 deck 中部分页面保留导入页图片资产，部分页面重建。每页在 plan 里说明来源页、目标 presentation、是否复用同一 presentation 的图片 token、是否需要重新上传。

-首次运行时先判断目标页是否仍在导入后的同一个 presentation 内。只要同一 presentation，就可以复用回读 XML 里的图片 token；跨 presentation 时才需要下载/重新上传。若不能确认目标 presentation，写入 `open_issues`，不要静默复制图片 token 到新文稿。
+首次运行时先判断目标页是否仍在导入后的同一个 presentation 内。只要同一 presentation，就可以复用回读 XML 里的图片 token；不要静默复制图片 token 到新文稿。异常新建只能由用户明确要求另建，或导入失败/回读失败触发；若需要复用导入页图片，必须记录下载/重新上传方案。

 如果选择 `preserve_imported_page`、`rebuild_in_imported_presentation` 或 `mixed`，且导入后的 slides 会作为最终交付物继续编辑，完成后必须把在线文件标题改成用户任务对应的新标题，避免仍保留导入时的模板/原附件名称。标题修改走 `lark-drive` 的 `drive files patch`，使用 `new_title` 字段；不要为了改标题重建整份 PPT。

-## Secondary Creation From Attachments
+## Imported Material As Draft

-用户要求“根据附件制作/改写/生成 PPT”时，附件不是可选参考，而是主要创作输入。默认执行以下策略：
+当用户提供 PDF/PPTX/slides 材料并要求制作或改写 PPT 时，先在 plan 中定两类来源：

- 先用文档类附件建立叙事和事实边界：标题层级、关键结论、数据、案例、限制条件。
- 再按 Local Material Handling 使用 PPTX/PDF/slides 类附件：作为 `rewrite_source` 时保留并重排原页内容；作为 `style_reference` 时提取页流、配色、版式、字体层级和图形 motif；作为内容资料时提取事实、结构和可复用图表。
- 再用图片/截图/logo/figure 建立页面视觉重点：可直接用的图片走上传；不适合直接用的图像改绘成 XML-native 图表、流程图或信息图。
- 表格数据优先生成真实 `<chart>`、表格或数字卡；禁止为了好看而杜撰趋势、比例或数值。
- 如果附件里有素材但 plan 没有使用，必须在 `material_inventory.inputs[].usage` 说明“不使用”的原因，例如低清晰度、与主题无关、重复、版权不明或数据不可解析。
+- `rewrite_source`：导入/回读后的目标视觉底稿，记录 `imported_xml_presentation_id`、`target_xml_presentation_id`、`template_asset_strategy` 和 `target_title`；默认策略是 `preserve_imported_page`、`rebuild_in_imported_presentation` 或 `mixed`。
+- `copy_source`：真正提供文案、事实、标题层级、数据或案例的材料。
+
+只有用户明确要求新建，或导入失败/`xml_presentations.get` 无法回读时，才允许新建 deck，并说明原因和图片资产迁移策略。“页数不超过 N 页”、内容不可用、只参考风格、PDF 是正文资料或布局复杂，都不是新建 deck 的理由。如果附件里有素材但 plan 没有使用，必须在 `material_inventory.inputs[].usage` 说明原因。

 ## Search Policy

 联网搜索不是默认动作。只有出现以下情况才搜索：

 - 用户要求查找公开事实、行业背景、竞品、logo、截图、图片或最新资料。
- plan 中存在关键视觉缺口，本地素材和内置模板都不能满足。
+- plan 中存在关键视觉缺口，且用户模板材料无法满足；搜索结果只能补缺，不能替代用户模板的主视觉系统。
 - 用户给出的主题需要真实世界背景才能避免空泛表达。

 搜索结果使用规则：
@@ -124,9 +147,15 @@ Deck 级 `material_inventory` 片段示例：
      {
        "source": "./template.pdf",
        "resolved_path": "./template.pdf",
-        "kind": "style_reference",
-        "usage": "Import as slides and extract palette, page flow, typography hierarchy, and motif.",
-        "status": "available"
+        "kind": "rewrite_source",
+        "usage": "Import key visual pages as slides and use as the target visual draft; do not copy placeholder text.",
+        "preprocessed_path": "./template_key_pages.pdf",
+        "selected_pages": [1, 2, 5, 8, 12, 20],
+        "status": "imported",
+        "imported_xml_presentation_id": "SOURCE_PRESENTATION_ID",
+        "target_xml_presentation_id": "SOURCE_PRESENTATION_ID",
+        "template_asset_strategy": "rebuild_in_imported_presentation",
+        "target_title": "New deck title"
      },
      {
        "source": "./notes.md",
@@ -138,8 +167,8 @@ Deck 级 `material_inventory` 片段示例：
      {
        "source": "./draft.pptx",
        "resolved_path": "./draft.pptx",
-        "kind": ["style_reference", "rewrite_source"],
-        "usage": "Import and read back XML; preserve source claims and restyle each page.",
+        "kind": "rewrite_source",
+        "usage": "Import and read back XML; preserve visual structure and restyle each page.",
        "status": "available"
      }
    ],
@@ -213,7 +242,7 @@ Match source type to slide role. Detailed geometry belongs in `visual-planning.m
 - `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`, `data_source`, or `infographic`.
- `image-left-text-right` and `image-right-text-left` can use `screenshot`, `paper_figure`, `logo`, `infographic`, or a style reference layout.
+- `image-left-text-right` and `image-right-text-left` can use `screenshot`, `paper_figure`, `logo`, `infographic`, or a layout derived from imported material.

 `suggested_query` is a future lookup hint. Execute the search only when the search policy says remote material is needed and local sources are insufficient.

@@ -235,9 +264,10 @@ Weak fallbacks to avoid:

 When generating XML:

-1. Apply `material_inventory` first: local style references, copy sources, data sources, and visual assets decide what each page can use.
-2. If a real visual asset exists and the workflow supports it, place it in the planned visual region.
-3. If no 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, fetch the presentation and verify asset pages are not blank and that each planned fallback is visible when no real asset was used.
+1. Apply `material_inventory` first: imported target material, copy sources, data sources, and visual assets decide what each page can use.
+2. If `target_xml_presentation_id` points to imported user material, create, replace, reorder, or delete pages in that presentation; do not call `slides +create` for a detached new deck unless the plan records an explicit user request to create a new deck or an import/readback failure.
+3. If a real visual asset exists and the workflow supports it, place it in the planned visual region.
+4. If no asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, whiteboard diagrams, or chart-like elements.
+5. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration.
+6. Keep text-density limits. Do not compensate for missing assets by adding long bullet text.
+7. 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.
--- a/skills/lark-slides/references/planning-layer.md
+++ b/skills/lark-slides/references/planning-layer.md
@@ -15,11 +15,13 @@
 7. 按规划文件、视觉规划和素材规划规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束，并把缺失素材转成可执行兜底视觉。
 8. 创建或大幅改写后，按 `validation-checklist.md` 做显式验证；本文件只要求验证记录能说明规划到 XML 的对应关系。

-素材和模板不能代替规划文件。素材处理层只能影响背景理解、`theme_style`、`visual_system`、页面流、文案输入、布局选择和局部视觉骨架；最终仍必须有 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
+素材和模板不能代替规划文件，但素材处理层可以决定材料角色、目标 presentation、改写方式和资产复用策略；最终仍必须有 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。

-如果用户提供 `.pptx` 或 `.pdf`，并称其为 PPT 模板、幻灯片模板、版式/风格参考，先按 `lark-drive` 的 `drive +import --type slides` 导入为在线幻灯片，并把回读 XML 作为 `style_reference`。模板/风格参考不等于一定重建新页：如果模板含需要复用的背景图、装饰图、品牌图片或复杂图片版式，优先把导入后的在线幻灯片作为工作底稿，保留图片令牌并局部编辑；如果只需要风格和布局骨架，再新建 XML 原生页面。导入是写操作；用户已经明确要求“根据该附件生成/改写 PPT”时可视为已有意图，否则先确认。
+可导入为 slides 的用户材料（`.pptx`、`.pdf` 或已有 online slides）参与制作/改写 PPT 时，默认是 `rewrite_source`：先导入或回读为 slides，`target_xml_presentation_id` 默认等于导入/已有 presentation，并在该 presentation 内继续创作。

-如果用户提供 `.pptx`，并要求“在此基础上修改 / 调整布局 / 美化 / 精简 / 增加目录 / 内容不用改 / 不要随便修改内容 / 保留框架 / 已有一版 PPT”，该文件是 `rewrite_source`，不是普通模板。导入并回读 XML 后，`slide_plan.json` 必须逐页记录原稿内容的保留、精简、新增和重排策略；优先保留导入页上的既有图片资产并局部编辑，整页结构变化、换模板或导入页块级编辑不可靠时，才按源页重建 XML 原生页面，再替换或删除旧页。不得直接新生成一套脱离原稿的页面。
+“内容不可用”“只作为背景模板”“不要使用模板文字”“只参考风格”只排除 `copy_source`，不排除 `rewrite_source`。这类材料仍要导入/回读，并在导入后的 presentation 内替换、插入或删除页面内容。只有用户明确要求另建，或导入失败/`xml_presentations.get` 无法回读时，才新建演示文稿，并在 plan 中写明原因。
+
+如果大 PDF 模板只用于二次创作的视觉底稿，可先按 `asset-planning.md` 选择关键模板页生成压缩版 PDF，再导入这个小 PDF。纯导入、归档、格式转换或用户要求保留完整 PDF 页序的任务，不做切割。

 不要把附件路径只当作提示词文本。像 `附件文件路径：path/to/report.docx` 这样的路径必须解析到真实文件；相对路径按当前工作目录和用户明确给出的素材根目录解析，不能硬编码某个固定附件目录。

@@ -70,9 +72,12 @@
      {
        "source": "./reference.pdf",
        "resolved_path": "./reference.pdf",
-        "kind": "style_reference",
-        "usage": "导入为在线幻灯片后，提取页面流、配色、字体层级和可复用视觉母题。",
-        "status": "available"
+        "kind": "rewrite_source",
+        "usage": "导入为在线幻灯片后，在导入 presentation 内二次创作。",
+        "status": "imported",
+        "imported_xml_presentation_id": "SOURCE_PRESENTATION_ID",
+        "target_xml_presentation_id": "SOURCE_PRESENTATION_ID",
+        "template_asset_strategy": "rebuild_in_imported_presentation"
      }
    ],
    "missing": [
@@ -207,12 +212,11 @@

 本地素材优先于远程搜索。常见素材角色：

- `background_reference`：用于理解主题、事实、受众或约束的文件或链接。
- `style_reference`：用于配色、字体、布局、母题和页面流的 PDF、PPTX、在线幻灯片或模板。
+- `background_reference`：用于理解主题、事实、受众或约束的非模板文档或链接。
 - `visual_asset`：可能出现在页面中的图片、截图、标志、图标、图表、示意图或论文图。
 - `copy_source`：作为内容输入的正文、提纲、笔记、PRD、报告或转写稿。
 - `data_source`：用于图表或表格的数据表、CSV/XLSX、指标或结构化数值。
- `rewrite_source`：需要保留、优化、精简、扩展或重组的已有 PPT/PDF/在线幻灯片，不应只当作宽泛风格参考。
+- `rewrite_source`：导入后承载二次创作的目标底稿，可提供背景、版式、图片资产和页面结构；即使其文案不可用，也不应只当作宽泛视觉线索。

 规划页面前，先解析所有附件路径，并写入 `material_inventory.inputs`。每个可用本地输入应包含：

@@ -223,13 +227,13 @@
 - `status`：`available`、`imported`、`uploaded`、`read`、`skipped` 或 `missing`。
 - `notes`：可选映射细节，例如“用户提供的相对路径已按指定素材目录解析”。

-如果附件是模板/风格演示文稿或 PDF，并已导入为在线幻灯片，在已知时还要记录 `imported_xml_presentation_id` 或 `import_ticket`，然后把导入 XML 作为 `style_reference`。
+如果附件是可导入为 slides 的用户材料，并已导入为在线幻灯片，在已知时记录 `imported_xml_presentation_id` 或 `import_ticket`。按 `asset-planning.md` 判断角色；默认把可作为视觉底稿的导入 XML 作为 `rewrite_source` 使用，并记录 `target_xml_presentation_id`。

-对导入的模板/风格演示文稿，还要按 `asset-planning.md` 记录 `template_asset_strategy`：`preserve_imported_page`、`rebuild_in_imported_presentation`、`rebuild_new_presentation` 或 `mixed`。在同一个已导入演示文稿内创建或替换页面时，可以复用导入页的图片令牌；不要把 `<img src>` 令牌直接复制到另一个新演示文稿，除非已经把图片下载并重新上传到目标演示文稿。如果导入的在线幻灯片文件会成为编辑后的最终交付物，记录 `target_title`，并在编辑完成后重命名在线文件，避免仍保留源模板或附件标题。
+对导入的用户材料，还要按 `asset-planning.md` 记录 `template_asset_strategy`：`preserve_imported_page`、`rebuild_in_imported_presentation` 或 `mixed`。在同一个已导入演示文稿内创建或替换页面时，可以复用导入页的图片令牌；不要把 `<img src>` 令牌直接复制到另一个新演示文稿。如果导入的在线幻灯片文件会成为编辑后的最终交付物，记录 `target_title`，并在编辑完成后重命名在线文件，避免仍保留源材料或附件标题。异常新建只能由用户明确要求另建，或导入失败/回读失败触发，并必须记录原因和图片资产迁移方式。

-如果附件是 `rewrite_source`，每个受影响页面计划都应说明来源页或来源章节，以及预期操作：`preserve`、`condense`、`expand`、`reorder`、`restyle` 或 `replace_visual_only`。对于“内容不用改”类请求，默认使用 `replace_visual_only` 或 `restyle`，并保持原始论断、数字、名称和页面意图不变。
+如果附件是 `rewrite_source`，每个受影响页面计划都应说明来源页或来源章节，以及预期操作：`preserve`、`condense`、`expand`、`reorder`、`restyle`、`replace_visual_only` 或 `delete`。对于“内容不用改”类请求，默认使用 `replace_visual_only` 或 `restyle`，并保持原始论断、数字、名称和页面意图不变。对于“材料页数多于目标页数”的任务，先规划要保留或改写的来源页，再删除无关页；不要因为需要压缩页数就另建脱离材料的新 deck。

-如果本地 `.pdf` / `.pptx` 是风格参考，使用 `lark-drive` 将其导入为在线幻灯片，再用 `xml_presentations.get` 读取 XML 后规划。这是写操作，需要用户意图。默认只提取设计语言；除非用户要求，否则不要复制源文本。
+用户提供的 PDF/PPTX/slides 即使只参考风格，也不能脱离导入后的 presentation 新建；除非用户明确要求另建，或导入失败/回读失败。

 单个计划素材使用对象，多个真实需求使用数组；没有有用素材时使用 `asset_type: "none"`。每个计划素材必须包含：

@@ -251,7 +255,7 @@
 写每页页面 XML 前，把规划字段映射成具体决策：

 - `key_message` 决定标题、主导论断或主要结论。
- `material_inventory` 决定哪些本地素材、导入风格参考、远程搜索结果或兜底方案允许影响页面。
+- `material_inventory` 决定哪些本地素材、导入材料、文案来源、远程搜索结果或兜底方案允许影响页面。
 - `layout_type` 决定坐标结构和元素类型。具体布局规则见 `visual-planning.md`。
 - `visual_focus` 决定最大视觉区域或被强调对象。
 - `text_density` 限制可见文字量。
--- a/skills/lark-slides/references/validation-checklist.md
+++ b/skills/lark-slides/references/validation-checklist.md
@@ -9,12 +9,15 @@
 1. 记录创建或编辑返回的 `xml_presentation_id`，以及已知的 `slide_id` / `revision_id`。
 2. 用 `xml_presentations.get` 回读全文 XML。
 3. 检查实际页数是否符合计划或用户要求。
-4. 检查每页 `<data>` 内是否有预期主要元素。
-5. 检查没有明显空白页、破损页、缺失标题或缺失主视觉。
-6. 检查页面不是全部退化为标题加 bullet list。
-7. 检查视觉层级：标题、主视觉、支撑信息三者可区分。
-8. 检查明显溢出和布局风险：重叠、越界、底部拥挤、长文本框。
-9. 在最终回复中给出简短验证记录。
+4. 如果计划基于导入 PDF/PPTX/slides 材料二次创作，检查最终 `xml_presentation_id` 是否等于 `target_xml_presentation_id`；如果另建了 presentation，必须在验证记录中说明用户明确要求另建或导入/回读失败原因。
+5. 如果用户材料只用于模板风格或视觉线索，检查它是否仍作为 `rewrite_source` 导入/回读，并确认最终没有交付脱离该材料的新 deck。
+6. 检查每页 `<data>` 内是否有预期主要元素。
+7. 检查没有明显空白页、破损页、缺失标题或缺失主视觉。
+8. 检查页面不是全部退化为标题加 bullet list。
+9. 检查视觉层级：标题、主视觉、支撑信息三者可区分。
+10. 检查没有遗留模板占位文案、示例公司名、示例日期或与用户主题无关的源模板文字。
+11. 检查明显溢出和布局风险：重叠、越界、底部拥挤、长文本框。
+12. 在最终回复中给出简短验证记录。

 回读命令：

@@ -65,6 +68,8 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - `visual_focus` 是页面中最醒目或最大的信息区域之一。
 - `text_density` 影响了文本量，没有用长 bullet 框替代规划。
 - `asset_need` 有真实素材时已放入正确区域；没有真实素材时，`fallback_if_missing` 已用 XML 形状、线条、标签、表格或图表兜底。
+- `template_asset_strategy` 为 `preserve_imported_page`、`rebuild_in_imported_presentation` 或 `mixed` 时，不能交付一份脱离导入材料的新 deck。
+- 如果计划声明保留材料背景、装饰图、品牌图或复杂图片版式，回读 XML 中应仍存在对应的 `<img src>`、背景图片或等效重绘结构；如果未保留，验证记录必须说明原因。

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

@@ -106,9 +111,13 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 ```text
 验证记录：
 - 回读：已执行 xml_presentations.get，实际页数 N / 预期 N。
+- 导入底稿：如使用导入材料二次创作，最终 presentation 与 target_xml_presentation_id 一致；如不一致，已说明用户明确要求另建或导入/回读失败原因。
+- 视觉底稿：如用户材料只提供模板风格或视觉线索，已确认它仍作为 rewrite_source 导入/回读并承载最终二创。
+- 内容来源：如模板材料内容不可用，已确认未复制其占位文案；正文来自计划中的 copy_source 或用户输入。
 - 截图：截图能力可用时，已用截图辅助判断最终效果。
 - 关键页：架构解释 / Self-Attention / 对比或演进 / 总结页均存在。
 - 结构：检查了主要 shape/img/table/chart 元素，无明显空白页或破损页。
+- 模板清理：未发现模板占位文案、示例公司名、示例日期或无关模板文字。
 - 布局：检查了标题层级、主视觉、重叠/越界/文本溢出风险。
 ```