docs: update lark slides planning guidance

2026-07-09 02:14:02 +08:00 · 2026-06-15 14:09:34 +08:00
parent ff23931da1
commit a48dc3cef8
5 changed files with 202 additions and 127 deletions
--- a/skills/lark-slides/SKILL.md
+++ b/skills/lark-slides/SKILL.md
@@ -30,22 +30,14 @@ metadata:

 **CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**

-**CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。**
+**CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。先创建对应目录；规划层、素材处理层、视觉规划和验证分别遵循 [planning-layer.md](references/planning-layer.md)、[asset-planning.md](references/asset-planning.md)、[visual-planning.md](references/visual-planning.md)、[validation-checklist.md](references/validation-checklist.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 和布局风险。**
-
-**CRITICAL — 如果用户提到“模板”“套用模板”“参考某种主题/风格/版式”，或用户需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），MUST 先用 [`scripts/template_tool.py`](scripts/template_tool.py) 的 `search` 做模板检索；默认给出 2-3 个最匹配模板候选供用户选择。锁定模板后用 `summarize` 获取主题和布局摘要；只有需要布局骨架时才用 `extract` 裁切目标页型 XML。不要直接读取完整模板 XML。**
+创建前自检或失败排障时，按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。

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

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

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

@@ -95,44 +87,6 @@ lark-cli auth login --domain slides

 > **这是演示文稿，不是文档。** 每页 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 视觉。
- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。
-
 ### 创建方式选择

 | 场景 | 推荐方式 |
--- a/skills/lark-slides/references/asset-planning.md
+++ b/skills/lark-slides/references/asset-planning.md
@@ -1,28 +1,111 @@
-# Asset Planning
+# Material And Asset Planning

-新建演示文稿或大幅改写页面时，在写入 `slide_plan.json` 前后都可以参考本文件。目标是让 agent 主动识别有价值的图、图标、图表、流程图、时序图、架构图、装饰图案、截图或示意图需求，同时保持 deck 在没有真实素材时也能完整执行。
+新建演示文稿或大幅改写页面时，planning layer 必须先激活本素材处理层，再写入或更新 `slide_plan.json`。目标是让 agent 先利用用户已经提供的本地素材和上下文，再决定是否需要内置模板、联网搜索或 XML-native 兜底。

-本文件只定义轻量资产规划。不要把它理解成素材采集流程。
+本文件覆盖两类对象：
+
+- `material_inventory`：deck 级素材盘点，记录本地素材、链接、缺口、用途和搜索策略。
+- `asset_need`：page 级视觉资产需求，记录每页是否需要图片、图表、截图、图标、文案来源或兜底视觉。

 ## 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.
+- 本地素材优先。用户给了文件、目录、截图、PDF、PPTX、文案、数据表、链接或已有 slides 时，先判断能否用它满足背景理解、风格参考、图片素材、文案输入或数据输入。
+- 没有合适本地素材时，才考虑联网搜索、内置模板、IconPark 或 XML-native 兜底。联网搜索只用于确实需要外部事实、图片、logo、公开截图或背景补充的场景。
+- 素材进入 plan 前必须分类并写清用途；不要把“有文件”直接等同于“应出现在页面上”。
+- 页面不能依赖不可获得素材才能完成。每个 `asset_need` 都必须有 `fallback_if_missing`。
+- 最终 XML 不能留下空白图片框。真实素材不可用时，立即使用 shape、text、line、table、chart、whiteboard 或图标生成可见兜底。
+- 真实图片进入 slides 前必须走支持的上传路径：`slides +media-upload` 或 `+create --slides` 的 `@./path` 占位符。禁止把 http(s) 外链直接写进 `<img src>`。

-## JSON Shape
+## Material Roles

-Use an object for one planned asset, or an array when a page genuinely needs multiple assets. Keep each item compact.
+将每个输入素材归入以下角色之一；一个素材可以有多个角色，但要分别说明用途。
+
+| Role | 用途 | 常见来源 | 默认处理 |
+|------|------|----------|----------|
+| `background_reference` | 补充主题背景、事实、约束、术语、受众信息 | PDF、文档、网页、PRD、报告、会议纪要 | 读取/摘要后影响叙事和页面重点 |
+| `style_reference` | 参考 PPT 风格、配色、版式、字体层级、页面流 | PDF、PPTX、已有 slides、内置模板 | 提取设计语言，不默认复制正文 |
+| `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` |
+
+## Source Priority
+
+1. 用户显式提供的本地素材。
+2. 当前工作区内与任务明确相关的素材。
+3. 用户给出的在线 slides/wiki/drive/doc 链接。
+4. 内置模板库和 IconPark。
+5. 联网搜索公开素材或背景信息。
+6. XML-native 兜底视觉。
+
+如果多个来源冲突，用户显式提供的素材优先；无法判断时，在 plan 的 `open_issues` 里记录需要用户确认。
+
+## Local Material Handling
+
+- `.pdf` / `.pptx` 作为风格参考或仿写模板：先用 `lark-drive` 的 `drive +import --type slides` 导入为在线 slides，再用 `slides xml_presentations.get` 回读 XML。导入是写操作，执行前必须确认用户意图。默认只提取页面流、配色、背景、字体层级、布局骨架和 motif，不复制原文案。
+- `.png` / `.jpg` / `.jpeg` 等图片：判断是可直接展示、需要裁切/缩放、还是只用于理解。进入 XML 前必须上传或使用 `@./path` 占位符。
+- `.csv` / `.xlsx` / 表格数据：优先转成 `<chart>`、表格或数字卡；不要截图化数据，除非用户提供的是不可解析的表格图片。
+- `.md` / `.txt` / 文档类内容：作为 `copy_source` 或 `background_reference`，提炼为低密度页面文案，不要整段搬进 slide。
+- 已有 online slides：直接回读 XML，把它作为 `style_reference` 或改写对象；不要再走导入。
+
+## Search Policy
+
+联网搜索不是默认动作。只有出现以下情况才搜索：
+
+- 用户要求查找公开事实、行业背景、竞品、logo、截图、图片或最新资料。
+- plan 中存在关键视觉缺口，本地素材和内置模板都不能满足。
+- 用户给出的主题需要真实世界背景才能避免空泛表达。
+
+搜索结果使用规则：
+
+- 图片素材必须先落到本地，再通过 slides 上传流程进入 XML。
+- 背景信息必须转化为 `background_reference` 摘要和页面结论，不要把长文本塞进页面。
+- 无法确认版权或来源可靠性时，只作为风格/信息参考，不直接作为可展示图片。
+- 如果搜索失败或不适合使用，按 `fallback_if_missing` 生成 XML-native 视觉。
+
+## Plan Shape
+
+Deck 级 `material_inventory` 示例：

 ```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."
+  "material_inventory": {
+    "local_first": true,
+    "inputs": [
+      {
+        "source": "./template.pdf",
+        "kind": "style_reference",
+        "usage": "Import as slides and extract palette, page flow, typography hierarchy, and motif.",
+        "status": "available"
+      },
+      {
+        "source": "./notes.md",
+        "kind": "copy_source",
+        "usage": "Condense into slide headlines and speaker intent.",
+        "status": "available"
+      }
+    ],
+    "missing": [
+      {
+        "need": "Product screenshot for workflow page",
+        "search_policy": "Use local screenshot if provided; otherwise search only if user wants real UI imagery.",
+        "fallback_if_missing": "Draw a simplified UI wireframe with labeled panels."
+      }
+    ]
+  }
+}
+```
+
+Page 级 `asset_need` 示例：
+
+```json
+{
+  "asset_type": "screenshot",
+  "source_preference": "local_first",
+  "purpose": "Show the target workflow state instead of describing it with bullets.",
+  "candidate_sources": ["./assets/workflow.png"],
+  "suggested_query": "product workflow screenshot",
+  "fallback_if_missing": "Draw a simplified UI wireframe with three panels and callout labels."
 }
 ```

@@ -31,7 +114,9 @@ For a page without a meaningful asset need, use:
 ```json
 {
  "asset_type": "none",
+  "source_preference": "none",
  "purpose": "No external or simulated asset needed; the page is text-led.",
+  "candidate_sources": [],
  "suggested_query": "",
  "fallback_if_missing": "Use typography, spacing, and simple accent shapes only."
 }
@@ -43,33 +128,35 @@ For a page without a meaningful asset need, use:
 - `architecture_diagram`: system components, data flow, dependency map, or model structure.
 - `icon`: small semantic symbol for a concept, step, role, or status.
 - `logo`: brand, product, team, or customer mark.
- `chart`: 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.
+- `chart`: line, bar, pie, radar, area, or combo data visual. Note: `<chart>` does not support funnel or scatter; map those to `<whiteboard>` 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.
+- `style_reference`: page-level use of a layout or motif from a template/reference deck.
+- `copy_source`: page-level source text to condense into slide copy.
 - `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:
+Match source 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`.
+- `comparison` layout often works with `icon`, `chart`, `infographic`, or `style_reference`.
 - `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.
+- `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.

-`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.
+`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.

 `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."
+- "Use a bordered UI wireframe with product area labels, not an empty image."

 Weak fallbacks to avoid:

@@ -78,47 +165,13 @@ Weak fallbacks to avoid:
 - "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.
+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.
--- a/skills/lark-slides/references/planning-layer.md
+++ b/skills/lark-slides/references/planning-layer.md
@@ -7,15 +7,17 @@
 ## Required Flow

 1. 理解用户需求，必要时澄清主题、受众、页数、风格。
-2. 如果适合模板，先用 `template_tool.py search` 检索，锁定模板后用 `summarize` 获取主题和页型信息。
+2. 激活素材处理层：按 `asset-planning.md` 盘点用户提供的本地素材、可引用链接和缺口素材；本地素材优先，没有合适本地素材时再使用内置模板或联网搜索。
 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 的对应关系。
+8. 创建或大幅改写后，按 `validation-checklist.md` 做显式验证；本文件只要求验证记录能说明 plan 到 XML 的对应关系。

-模板不能代替 plan。模板搜索和摘要只能影响 `theme_style`、页面流、布局选择和局部布局骨架；最终仍必须有 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
+素材和模板不能代替 plan。素材处理层只能影响背景理解、`theme_style`、`visual_system`、页面流、文案输入、布局选择和局部视觉骨架；最终仍必须有 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
+
+如果用户提供 `.pptx` 或 `.pdf`，并称其为 PPT 模板、幻灯片模板、版式/风格参考，先按 `lark-drive` 的 `drive +import --type slides` 导入为在线 slides，在这个slides上进行内容二次创作。

 ## Plan Path

@@ -58,6 +60,23 @@ Exception:
  "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.",
+  "material_inventory": {
+    "local_first": true,
+    "inputs": [
+      {
+        "source": "./reference.pdf",
+        "kind": "style_reference",
+        "usage": "Import as slides, then extract page flow, palette, typography hierarchy, and reusable motif.",
+        "status": "available"
+      }
+    ],
+    "missing": [
+      {
+        "need": "Product UI screenshot",
+        "search_policy": "Search only if no local screenshot is available; otherwise use XML-native fallback."
+      }
+    ]
+  },
  "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.",
@@ -106,9 +125,10 @@ 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.
+- `material_inventory`: planning-layer record of local inputs, linked references, chosen usage, missing materials, search policy, and fallbacks. Follow `asset-planning.md`.
 - `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.
+- `verification_plan`: plan-specific checks that must be reflected in the final verification record. Detailed post-create validation lives in `validation-checklist.md`.
 - `slides`: ordered page plans.

 Each slide must include:
@@ -178,7 +198,17 @@ Do not hard-code a page number just because a previous deck used that pattern. P

 ## Asset Planning

-`asset_need` is metadata. It can describe a desired figure, diagram, chart, icon, logo, screenshot, or fallback shape-based visual, but it must not require web search, local download, or media upload.
+`material_inventory` records deck-level source handling before XML generation. `asset_need` records page-level visual needs. Follow `asset-planning.md` for both.
+
+Local materials are preferred over remote search. Common material roles:
+
+- `background_reference`: files or links used to understand the topic, facts, audience, or constraints.
+- `style_reference`: PDF/PPTX/slides/templates used for palette, typography, layout, motif, and page flow.
+- `visual_asset`: images, screenshots, logos, icons, charts, diagrams, or figures that may appear on slides.
+- `copy_source`: text, outline, notes, PRD, report, or transcript used as content input.
+- `data_source`: tables, CSV/XLSX, metrics, or structured values used for charts or tables.
+
+If a local `.pdf` / `.pptx` is a style reference, use `lark-drive` to import it as online slides and then use `xml_presentations.get` to read the XML before planning. This is a write operation and requires user intent. Extract design language only by default; do not copy source text unless the user asks.

 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:

@@ -200,20 +230,15 @@ Good examples:
 Before writing each slide XML, map the plan fields to concrete decisions:

 - `key_message` determines the headline, dominant claim, or main takeaway.
+- `material_inventory` determines which local materials, imported style references, remote search results, or fallbacks are allowed to influence the page.
 - `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:
+After creating or rewriting the PPT, use `validation-checklist.md` as the source of truth for verification. The verification record should also mention the plan-specific mapping:

 - 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.
+- Planned `key_message`, `layout_type`, `visual_focus`, `text_density`, and `asset_need` are represented in XML.
+- `visual_system` and `typography_constraints` visibly affected backgrounds, structure, hierarchy, and text placement.
+- Any maintained `deck_status`, `created_slides`, `assets_used`, or `open_issues` fields are updated to match the current deck state.
--- a/skills/lark-slides/references/validation-checklist.md
+++ b/skills/lark-slides/references/validation-checklist.md
@@ -44,6 +44,10 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 | `xml_not_well_formed` | XML 语法错误或文本未转义 | 修复标签闭合、属性引号、`&` / `<` / `>` 转义 |
 | `bbox_overlap` | 文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |

+## Optional Screenshot Upgrade
+
+如果截图或可视化预览能力可用，优先获取页面截图辅助判断最终效果；截图不能替代 XML 回读和页数核对。
+
 ## Page Count And Structure

 - 实际页数必须等于用户要求或 `slide_plan.json` 的页数。
@@ -102,9 +106,10 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 ```text
 验证记录：
 - 回读：已执行 xml_presentations.get，实际页数 N / 预期 N。
+- 截图：截图能力可用时，已用截图辅助判断最终效果。
 - 关键页：架构解释 / Self-Attention / 对比或演进 / 总结页均存在。
 - 结构：检查了主要 shape/img/table/chart 元素，无明显空白页或破损页。
 - 布局：检查了标题层级、主视觉、重叠/越界/文本溢出风险。
 ```

-不要声称完成了人工视觉验收，除非确实打开或获取了可视化结果。仅从 XML 静态检查得出的结论，应表述为“静态检查未发现明显问题”。
+不要声称完成了截图或人工视觉验收，除非确实打开、获取截图或拿到了可视化结果。仅从 XML 静态检查得出的结论，应表述为“静态检查未发现明显问题”。
--- a/skills/lark-slides/references/visual-planning.md
+++ b/skills/lark-slides/references/visual-planning.md
@@ -4,6 +4,44 @@

 默认画布按 `960 x 540` 规划。模板 XML 可以覆盖具体坐标，但不能覆盖这些原则：页面要有主视觉区域、文本要受密度约束、不同 `layout_type` 必须产生明显不同的坐标结构。

+## 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 视觉。
+- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。
+
 ## Core Rules

 - `layout_type` must change geometry: element positions, region sizes, alignment, and visual rhythm must differ across page types.