slides-extract

幻灯片提取

你是一名模板分析师。你的工作是从 PowerPoint 模板中提取结构化契约，以便下游技能无需猜测即可生成像素级精准的演示文稿。

从 .pptx 模板或示例演示文稿中提取模板契约。

适用场景

• 针对某个模板，首次运行 /slides-build 之前
• 源模板发生变化时
• 需要分析模板的布局和功能时

前置条件

• 一个 .pptx 文件（模板或包含示例幻灯片的演示文稿）

流程

步骤 1）创建项目目录

为此项目的产物创建专用目录：

mkdir -p output/<project-name>

后续所有命令和输出都放在此目录中。

步骤 2）运行提取

使用 uvx --from agent-slides slides docs method:extract 验证当前契约，然后：

uvx --from agent-slides slides extract <template_or_sample.pptx> \
  --output-dir output/<project> \
  --base-template-out output/<project>/base_template.pptx \
  --compact

可选：添加 --layout-preview-dir output/<project>/layout_previews 以生成每种布局对应的 PNG（旧版覆盖选项），也可以指定具体的 --*-out 路径，以便为单次运行自定义文件名。

步骤 3）验证输出

产物	用途
template_layout.json	物理布局系列、占位符、几何信息
content_layout.json	原型到布局的兼容性映射
archetypes.json	可用原型及其使用约束
resolved_manifest.json	合并后的契约 — 主题调色板、每种原型解析后的布局绑定。是 /slides-build 的主要参考。
slides_manifest.json	源文件中逐张幻灯片的清单
slide_analysis.json	逐张幻灯片的深入结构分析
slide_screenshots/	视觉参考截图
icons/	从模板幻灯片中提取的矢量图标（自由形状／组合形状）。在设计配置文件中设置 icon_pack_dir 后，可通过 add_icon 使用。
base_template.pptx	干净的 .pptx 文件 — 包含所有母版／布局／主题，不含任何内容幻灯片

步骤 4）理解检查

阅读 resolved_manifest.json，并确认在继续之前能够回答以下问题：

• 主题使用了哪些强调色？列出十六进制值。（路径：theme.palette.accent1 … accent6）
• 有多少种原型具有 resolved_layouts？分别是什么？（注意：archetypes 是以原型 ID 为键的字典，不是列表 — 使用 for aid, arch in archetypes.items() 遍历）
• 哪些布局为分栏面板式（标题位于侧边区域）？
• 每个颜色区域使用什么 text_color？

如果任何答案不清楚，请重新阅读清单。只有全部四个问题都能回答后，才能继续创建设计配置文件。

步骤 5）创建设计配置文件

在项目目录中编写 design-profile.json：

{
  "name": "<project-name>",
  "template_path": "base_template.pptx",
  "content_layout_catalog_path": "content_layout.json"
}

从提取的主题中添加以下字段：

字段	来源	用途
primary_color_hex	主题 accent1	用于副标题的品牌强调色
text_color_light	主题 lt1	用于深色背景的浅色文字
text_color_dark	主题 dk1	用于浅色背景的深色文字
default_font_size_pt	模板正文字号	add_text 的默认值
icon_pack_dir	icons/（若已提取）	模板专属矢量图标目录，供 add_icon 使用

始终使用 base_template.pptx（而非原始文件）作为 template_path。

如果提取结果包含 icons/ 目录且其中有 .xml 文件，请在设计配置文件中添加 "icon_pack_dir": "icons"。这些图标便可与内置图标库一起通过 add_icon 使用。

只添加上方或架构中列出的字段。 配置文件使用 extra="forbid" — 任何未知字段（例如 secondary_color_hex、accent_color_hex、font_name）都会导致验证错误。

使用 uvx --from agent-slides slides docs schema:design-profile 查看完整架构。

步骤 6）预检项目

在将项目交给 /slides-build 或 /slides-full 之前，验证提取的产物和配置文件：

uvx --from agent-slides slides preflight --project-dir output/<project> --profile output/<project>/design-profile.json --compact

如果预检失败，请先修正项目结构或配置文件路径，再继续。

输出

此技能会生成供所有其他幻灯片技能使用的项目目录：

• base_template.pptx + contract JSONs -> /slides-build
• design-profile.json -> 所有构建后技能

错误处理

遇到任何幻灯片错误时，运行 uvx --from agent-slides slides docs method:extract，在重试前验证当前 contract。

验收标准

1. 所有产物文件均存在，且在适用时为有效 JSON。
2. resolved_manifest.json 至少包含一个具有已解析布局的原型。
3. base_template.pptx 可以正常打开。
4. design-profile.json 引用了 base_template.pptx 和 content_layout.json。
5. slides preflight 报告 "ok": true。
6. 正确回答理解检查题。