ppt-maker-skill（PPT 制作技巧）

PPT Maker

本技能用于构建和编辑结构化 PPT，而不是将任意 HTML 强行转换成 PowerPoint。

核心工作流是：

用户输入 -> 创建项目文件夹 -> AI 生成 deck.json -> 预览渲染 -> 自然语言编辑 -> 导出 .pptx

ClawHub 版本说明

• 发布包默认不包含 node_modules、历史 projects/、示例导出文件、用户素材和本地虚拟环境。
• 首次使用先进入 {baseDir} 安装依赖；参考素材请放进 {baseDir}/materials/。

cd {baseDir}
npm install

当前系统新增了三层组织能力：

• template：控制整体视觉风格和推荐版式
• archetype：控制某类 PPT 的默认结构和起稿页序
• subskills/：为个人介绍、项目介绍等具体方向提供更窄的 workflow

何时使用

当用户提出以下需求时使用本技能：

• 根据一句话主题生成 PPT 大纲与页面
• 根据一段原文或 Markdown 生成演示文稿
• 修改某一页的标题、正文、配图、布局、主题或组件位置
• 为页面或组件增加分步出现动画，并预览动画节奏
• 预览 PPT 页面效果
• 用 skill 自带 viewer 预览指定项目，并查看页内区块信息
• 导出可编辑的 .pptx

核心原则

• 子技能优先（Subskill First）：在开始创建任何 PPT 前，必须先查看 subskills/ 目录下（或通过 scripts/list_catalog.js）是否已有为该场景定制的专属子技能。如果存在对应的子技能（如 english-lesson、personal-intro），必须优先阅读并严格遵循该子技能 SKILL.md 中的专属规范与工作流，绝不能用当前的通用兜底流程硬做。
• 不要让 AI 直接输出任意 HTML 页面作为最终真相来源
• 所有页面内容都必须落到 deck.json 的结构化组件模型里
• 预览与导出必须读取同一份 deck.json
• 默认优先保证可编辑性，复杂页面再考虑保真兜底
• 动画优先用结构化 animation 字段描述；HTML 预览真实播放，PPT 导出默认用 build slides 模拟

目录导航

• references/slide-schema.md

定义 deck.json 的结构与当前支持的组件。

• references/layout-rules.md

定义版式、字号、间距和溢出控制规则。

• references/template-catalog.md

定义当前模板、archetype 和版式变体目录。

• references/prompt-patterns.md

定义大纲生成、页面生成、编辑指令改写的提示词模式。

• scripts/list_catalog.js

列出模板、archetype、版式变体和已存在的子 skill。

• scripts/create_ppt_skill.js

根据新场景脚手架出新的 PPT 子 skill 和 archetype。注：AI 执行此操作时，须遵循 .agents/workflows/create-subskill.md 中定义的交互访谈流程。

• scripts/validate_deck.js

校验 deck 数据是否合法。

• scripts/init_project.js

为每个新 PPT 创建独立项目文件夹，并支持选择 template 和 archetype。

• scripts/build_project.js

在项目目录里一键校验和预览。加 --export 导出 .pptx。

• scripts/open_project_preview.js

为指定项目生成并打开 viewer 风格的 preview.html。加 --export 同时导出。

• scripts/render_preview.js

生成简洁的 viewer 预览页面，左侧为页列表，右侧为自动缩放的 slide 展示。

• scripts/export_ppt.js

单独导出 .pptx，文件名与项目目录名一致（如 lesson-23-24.pptx）。

• scripts/list_materials.js

列出 materials/ 目录下的参考素材文件。

• scripts/apply_edit.js

根据结构化编辑指令更新 deck。

• scripts/plan_edit.js

将自然语言修改命令翻译为结构化 operations。

• scripts/edit_with_command.js

一步完成“自然语言指令 -> deck 修改”。

• subskills/personal-intro

面向个人介绍类 PPT 的子 skill。

• subskills/project-intro

面向项目介绍类 PPT 的子 skill。

• subskills/english-lesson

面向英语课堂教学 PPT 的子 skill（10 分钟课堂结构）。

• materials/

存放用户上传的参考素材（教材 PDF、文稿、图片等），AI 从中提取内容生成 PPT。

推荐工作流

1. 预检（关键！）：如果用户要求做特定场景的 PPT，在创建之前，必须先阅读 subskills/ 目录或执行 node {baseDir}/scripts/list_catalog.js 检查是否有现成的专属子技能（例如用户要做英语备课，务必走 english-lesson 子技能的流程）。若存在，必须切换并遵守该子技能的 SKILL.md 或规范进行交付；若不存在，才适用当前的兜底通用流程。
2. 先创建独立项目目录，路径位于 {baseDir}/projects/<slug>/，并选择合适的 template / archetype。
3. 阅读 references/slide-schema.md，确认当前支持哪些页面和组件。
4. 如有参考素材，放入 {baseDir}/materials/ 目录。可用 node {baseDir}/scripts/list_materials.js 查看。
5. 根据用户输入在该项目目录里生成 deck.json。
6. 运行 node {baseDir}/scripts/build_project.js {baseDir}/projects/<slug> 校验和预览。
7. 需要查看页面时，使用 node {baseDir}/scripts/open_project_preview.js {baseDir}/projects/<slug> 打开项目 viewer。
8. 根据用户反馈继续修改该项目目录里的 deck.json。
9. 用户确认后，加 --export 导出 .pptx（文件名与项目名一致）。
10. 后续所有预览、编辑和导出都在同一项目文件夹内完成。

命令示例

在本技能目录下运行：

cd {baseDir}
npm install
npm run project:new
npm run validate
npm run preview
npm run export
npm run catalog
node scripts/list_materials.js
node scripts/build_project.js projects/lesson-23-24
node scripts/build_project.js projects/lesson-23-24 --export
node scripts/open_project_preview.js projects/lesson-23-24
node scripts/init_project.js openclaw-intro "OpenClaw 介绍"
node scripts/init_project.js founder-profile "创始人介绍" --template profile-editorial --archetype personal-intro
node scripts/create_ppt_skill.js customer-story "客户案例介绍" "适合客户案例复盘、售前演示和项目展示"

deck 生成要求

• 每个 slide 必须有稳定的 id
• 每个 component 必须有稳定的 id
• deck 建议同时带上 meta.template 和 meta.archetype
• 所有组件必须显式给出 x, y, w, h
• 坐标单位统一使用英寸，对齐 PowerPoint 宽屏页面
• 文本内容要控制长度，避免超出布局预算
• 如需动画，优先给组件增加 animation.effect 和 animation.build

自然语言编辑要求

当用户说“改第三页标题”或“把右上角图片放大一点”时：

• 先定位 slide
• 再定位 component
• 然后修改 deck.json
• 不要直接只改预览 HTML

对于常见的命令式编辑，优先走：

1. scripts/plan_edit.js 生成 operations
2. scripts/apply_edit.js 或 scripts/edit_with_command.js 应用修改

复杂页面如需保真导出，可以在后续扩展中增加整页位图模式，但默认先保持可编辑对象导出。

Viewer 约定

• 左侧固定展示 slide 列表与缩略页
• 右侧顶部精简工具栏：页码芯片 + 页面名称 + 导航按钮
• slide 画布自动缩放适配窗口大小（scale-to-fit）
• 悬停组件时显示 tooltip（名称 + 类型）
• 点击组件后自动复制识别信息，方便告诉 AI 修改。

模板与子 skill 约定

• template 负责视觉风格和推荐页型变体，不直接替代 theme
• archetype 负责某类 PPT 的默认起稿结构
• subskills/ 里的子 skill 应该只保留对应场景的简洁 workflow，不复制主技能的大量通用说明
• 新建场景优先用 scripts/create_ppt_skill.js，同时生成一个新的 archetype 脚手架

动画说明

• 预览层支持 fade-in、slide-up、zoom-in
• 导出层默认不依赖 PowerPoint 原生对象动画
• 如组件设置了 animation.build，导出时会按 build 顺序展开成多张连续幻灯片