diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index c0b6dac26..dd9466e08 100644 --- 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//slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。** +**CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan//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 视觉。 -- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。 - ### 创建方式选择 | 场景 | 推荐方式 | diff --git a/skills/lark-slides/references/asset-planning.md b/skills/lark-slides/references/asset-planning.md index 679d5d868..9c2559c61 100644 --- 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) 外链直接写进 ``。 -## 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` / 表格数据：优先转成 ``、表格或数字卡；不要截图化数据，除非用户提供的是不可解析的表格图片。 +- `.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: `` does not support funnel or scatter — map those to `` SVG at generation time. +- `chart`: line, bar, pie, radar, area, or combo data visual. Note: `` does not support funnel or scatter; map those to `` 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. diff --git a/skills/lark-slides/references/planning-layer.md b/skills/lark-slides/references/planning-layer.md index 51731fa03..62976a52f 100644 --- 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//`。 4. 先创建目录：`mkdir -p .lark-slides/plan/`。 5. 写入 `.lark-slides/plan//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//slide_plan.json`。 +素材和模板不能代替 plan。素材处理层只能影响背景理解、`theme_style`、`visual_system`、页面流、文案输入、布局选择和局部视觉骨架；最终仍必须有 `.lark-slides/plan//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. diff --git a/skills/lark-slides/references/validation-checklist.md b/skills/lark-slides/references/validation-checklist.md index a55ffaf99..2eeece29b 100644 --- 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 ` 转义 | | `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