# Slidemuse

> 将书籍、PDF、论文、报告或文字材料按固定三阶段流程制作成图片版 PPT，并在用户明确要求时继续还原为可编辑 PPTX。重点适用于竞赛 PPT（挑战杯/大挑/小挑、中国国际大学生创新大赛、全国大学生交通运输科技大赛/交科赛、三创赛、正大杯、大创等），同时适用于电影质感 PPT、创新创业路演、学术汇报、论文答辩、项目汇报、课程展示、读书分享和图片转可编辑 PPT；默认严格执行需求确认、内容大纲确认、四套幻灯片浏览视图选型、逐页图片生成和可选的 Scene v1 可编辑重建，不适用于直接修改已有可编辑 PPTX。

- Skill: `helloo1568/slidemuse` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add helloo1568/slidemuse`
- Raw SKILL.md: https://api.skillmd.com/api/skills/helloo1568/slidemuse/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: helloo1568 (https://skillmd.com/u/helloo1568)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/helloo1568/slidemuse

---


# SlideMuse · 2.2.1

本技能只有一条主流程：**内容提炼 → 图片 PPT 生成 → 可编辑 PPTX 还原**。
用户负责确认内容与风格，Agent 负责按已确认规格执行；不得把流程改写成“先做原生信息层”的编辑优先路线。

## 运行环境

- 通过仓库根目录的 `install.py` 安装时，技能目录会创建独立的 `.venv`，并在 `.skill-python` 中记录解释器绝对路径。
- 执行任何 `scripts/*.py` 前，若 `.skill-python` 存在，优先使用其中的解释器；否则使用可用的 Python 3.10+。
- 下文命令中的 `python` 均表示上述技能解释器，不要求用户把依赖安装进全局 Python 环境。
- 任务材料和产物必须放在独立工作目录，不得写入技能安装目录。

## 平台与生图后端

- **最佳推荐：Codex + GPT Image 2.5。** Codex 暴露模型选择时，风格探索优先使用 GPT Image 2.5 Flare，成品页与精确参考编辑优先使用 GPT Image 2.5 Sunburst。
- Codex 未暴露型号时调用其当前生图能力，不得声称指定了某个 2.5 子型号。
- 其他 Agent 必须调用该 Agent 自身提供或已连接的图像生成/编辑能力，不得假设存在 Codex 专属工具。
- 仓库脚本不负责生图、OCR 或视觉理解，也不自动调用收费 API。

## 强制流程契约

以下是本技能的默认流程；明确的跳过、代定或代选授权只改变对应环节，不扩大其他阶段的授权：

1. 每次行动前判断状态，只执行状态表允许的动作。
2. 五项需求未齐时只确认缺失项；可检查文件存在性和页数等元数据，不得阅读正文、提炼内容或生图。
3. 内容大纲必须单独展示。未获确认或明确代定授权时停止等待，不得生成风格总览；已获对应授权时记录后继续。
4. 风格未锁定时默认生成四张独立的幻灯片浏览视图并等待选择；具体豁免只按“风格门禁”执行，不得自行判断跳过。
5. 新材料必须先完成图片版。用户一开始要求可编辑版表示已授权最后阶段，但不能跳过图片版直接创作原生 PPTX。
6. Step 2 开始前必须创建并验证 `page-spec.json`。它保存已确认文字、数据、来源、元素意图和稳定 ID；Step 3 不得重新 OCR 或改写其中的已知内容。
7. “帮我做 PPT”“直接做一份”“按技能制作”不构成跳步授权。只按用户明确说出的跳过、代定或代选范围快进。
8. 用户新指令与旧规格冲突时，按[变更与恢复规则](references/workflow-updates.md)更新已有规格、回退状态并标记受影响产物；尚未创建的 Page Spec 不提前创建。
9. 当前 Agent 没有生图能力时停在对应状态并说明，不能用占位图冒充结果。

## 状态机

| 状态 | 进入条件 | 允许动作 | 阶段出口 |
|---|---|---|---|
| S0 需求未齐 | 五项需求至少一项未明确且无对应代定授权 | 询问缺失项；检查文件元数据 | 用户补充或明确授权 |
| S1 内容提炼 | 五项需求齐全或缺失项已获代定授权 | 阅读材料、创建规格、提炼并展示完整大纲 | 无内容授权进入 S2；已有对应授权进入 S3 |
| S2 等待内容确认 | 大纲已展示 | 接收确认或修改；按反馈改大纲 | 内容获确认或明确代定 |
| S3 风格方案 | 内容已确认 | 按风格门禁生成四套总览或记录合法豁免 | 总览已展示或风格已合法锁定 |
| S4 等待风格确认 | 四套总览已展示 | 接收选择/修改；已授权代选时记录选择 | 视觉规范锁定 |
| S5 图片版制作 | 内容和风格均锁定 | 创建 Page Spec、逐页生成、验收并合并图片版 | 图片版交付或进入已授权 S6 |
| S6 可编辑重建 | 用户明确要求可编辑，或要求从已有页面直接还原 | 分层、编写 Scene、编译、审查和渲染核对 | 可编辑交付完成 |
| DONE 已交付 | 已完成用户要求的交付范围 | 记录交付版本；收到修改时按变更表恢复 | 本轮交付结束 |

已有页面图片/扫描 PDF 要求还原时可从 S6 开始；先确认输入范围、原比例和编辑目标，再创建 `page-spec.json` 记录可见内容。
已有可编辑 PPTX 只做普通修改时不走本技能，应保留原生结构；本技能已有 Scene 的后续修改按变更表恢复 S6。

## S0：确认五项需求

一次集中询问尚未明确的项目，已提供的不得重复询问：

1. **源材料**：附件、路径、PDF、书籍或粘贴文字。
2. **参考风格**：模板/图片/文字描述，或明确“没有参考风格”。
3. **使用场景与受众**：课堂、读书分享、组会、周报、项目汇报、路演等。
4. **页数预期**：固定页数、范围，或明确授权根据内容推荐。
5. **交付范围**：图片版，或图片版完成后继续还原可编辑版。

“没有参考风格”“页数由你推荐”“其余由你决定”是有效授权，必须原样记录。

## 制作规格

进入 S1 或 S6 后，把 [规格模板](references/deck-spec-template.md) 复制到任务目录并填写为 `deck-spec.md`。任务目录与技能安装目录分离。

恢复任务、上下文压缩、用户改需求或阶段转换时，先读取并更新规格。用户修改或恢复到不同版本时读取[变更与恢复规则](references/workflow-updates.md)，核对基准图版本和已授权差异。规格记录状态、授权、确认版本、页序、生成状态、质量检查和交付路径。

## Step 1A：内容提炼与确认（S1 → S2）

进入后读取 [Prompt 1A](references/prompts.md)。

1. 阅读材料并形成完整页序；每页一个主要结论，准确保留人名、日期、数字、单位、引语和来源。
2. 把标题、核心结论、必须准确出现的内容和来源写入 `deck-spec.md`。
3. 单独向用户展示大纲和待确认项；按状态表判定出口。缺少对应确认或代定授权时进入 S2 并停止，已有授权时记录原文与版本后进入 S3。
4. 用户要求修改时只更新受影响页面并再次展示；明确指定的修改是对该变更的授权，未决定的内容仍按门禁等待。进入 S3 前先完成大纲展示。

## Step 1B：风格方案与确认（S3 → S4）

进入后读取 [Prompt 1B](references/prompts.md) 和[缩略图总览验收](references/style-options.md)，按以下确定规则执行：

| 用户指令 | 动作 |
|---|---|
| 无参考或只有宽泛风格方向 | 必须生成四套总览并等待选择 |
| 提供参考但未明确“一比一沿用/严格照此制作” | 基于参考生成四套不越界的演绎并等待选择 |
| 明确要求严格沿用指定模板/母版/页面风格 | 记录 `locked-reference`，不生成四套；把参考转成文字视觉规范 |
| 明确说“跳过四套预览” | 记录 `skipped` 和授权原文；使用已给风格或请求其授权代定 |
| 明确说“你代选” | 仍生成四套，Agent 选择并记录理由与 `delegated` |

四套总览必须使用同一组代表页和相同内容，只改变视觉系统：总页数不超过 8 页时展示全部，超过 8 页时选 6–8 个覆盖主要页面类型的代表页。缩略页沿用任务指定比例，网格按数量适配，不补造页面。分别保存并展示方案 1–4；不得把四套拼成一张四宫格或用纯文字替代。总页数为 1 时，每套自然只有一页。

总览默认采用横向 16:9 画布，缩略页等大、完整、留有间距，页码在缩略页下方；3 页采用 2×2 网格并留空一格，不做纵向整页长图。重试沿用原方案编号并明确说明替换哪一版，交付只列每套最新验收版，历史稿不作为新增方案。

每套直接用一次生图生成含全部代表页的缩略图总览，正常四套共四次调用。风格选定前不逐页生成高清成品，再拼成总览。仅尺寸、排列、边距或外部页码有问题时，使用 `build_style_overview.py` 对已有图片本地缩放排版；需要拆分长图时先视觉确认每页裁切框，不为排版再次调用生图。内容或视觉本身有错才考虑针对性生图修复，并记录额外调用。

实际生成四套时，把当前候选写入 `style-options.json`，逐张核对缩略页网格与内容，并执行以下检查。结构与视觉检查均通过后，才进入 S4 宣布当前四套方案已齐；不将修正中间稿计为新方案。合法豁免四套预览的任务不要求创建此清单。

```sh
python "<skill-dir>/scripts/validate_style_options.py" "<work>/style-options.json"
```

## Step 2：生成图片版 PPT（S5）

进入后读取 [Prompt 2](references/prompts.md)、[Page Spec](references/page-spec.md) 和 [模型说明](references/models.md)。

1. 把确认后的内容与锁定视觉规范写入 `page-spec.json`。每页为所有已知文字、数据、视觉主体和图表分配稳定 ID；位置可先写 `bbox_hint`。
2. 生成第一张图片前必须运行：

```sh
python "<skill-dir>/scripts/validate_page_spec.py" "<work>/page-spec.json" --strict
```

3. 按 `01-title.png`、`02-title.png` 的零填充序号逐页生成。每次提示包含锁定视觉规范、Page Spec 中的准确内容、页码和总页数。
4. 每页立即检查画幅、文字、数据、裁切、溢出和跨页一致性；通过后更新最终图片路径、状态、提示词和必要的 `bbox_hint`。失败只重做对应页。
5. 同一页文字连续两次不准确时停止重试：按 Prompt 2A 生成保留全部主视觉的无字页面，再用 `scripts/overlay_text.py` 叠加准确文字并栅格化；叠字前后核对主视觉未丢失。Step 2 不提前移除 Step 3 才需拆分的主体。
6. 全部页面通过后运行交付验证和合并：

```sh
python "<skill-dir>/scripts/validate_page_spec.py" "<work>/page-spec.json" --require-images --strict
python "<skill-dir>/scripts/build_image_ppt.py" "<work>/page-spec.json" "<work>/output/image-deck.pptx"
```

7. 导出按 Page Spec 的批准图片清单、页序和画幅进行；旧稿留在目录中不会加入成品。重新打开或渲染 PPTX，核对页数、页序、画幅和文件可打开性。未授权 S6 时记录 DONE 并交付；已授权时更新规格后进入 S6。

## Step 3：还原可编辑 PPTX（S6）

进入后读取 [Prompt 3](references/prompts.md)、[重建与分层](references/reconstruction.md) 和 [Scene 协议](references/scene-format.md)。

1. 以 `page-spec.json` 为语义事实源、验收后的页面图片为视觉事实源。直接还原任务先从可见页面建立 Page Spec；用户要求保留原内容即视为对转录目标的授权，不代表低置信度文字已确认。
2. Page Spec 已记录的文字、数据、来源和 ID 直接复用，不重新 OCR、改写或更换。按变更记录识别重建后的已授权修改；只有未记录或超出授权的图文冲突才请求确认。
3. 每次处理 1–3 页，补齐精确坐标、层级、素材和置信度。文字、简单几何、表格和可靠数据图使用原生对象；复杂视觉拆成独立图片对象。
4. 从背景移除所有原生化文字和已拆主体并补全背景。原始整页图片只作核对证据，不能作为可编辑版底图。
5. 按 [JSON Schema](references/scene.schema.json) 编写 `scene.json`，然后编译和审查：

```sh
python "<skill-dir>/scripts/build_editable_ppt.py" "<work>/scene.json" "<work>/output/editable.pptx"
python "<skill-dir>/scripts/audit_editability.py" "<work>/output/editable.pptx" --scene "<work>/scene.json" --output "<work>/output/editability.json"
```

6. 实际渲染并与基准图逐页核对；再抽查移动主体、修改文字和编辑图表数据。问题只修对应 Scene 元素或素材；同一问题连续两次无效时记录限制。

## 交付契约

- **图片版**：`image-deck.pptx`、有序页面图片、`page-spec.json`、实际预览/检查说明。
- **可编辑版**：在图片版基础上增加 `editable.pptx`、`scene.json`、引用的 `assets/`、`editability.json` 和渲染预览。
- 说明字体替代、低置信度识别、AI 补全、独立栅格对象和待人工处理项。
- 不能把整页截图加少量文本框、整页 SVG 或未拆分背景称作“每个元素可编辑”。
- 无渲染器时写明“仅完成结构验证”，不能声称视觉验收通过。

## 资源路由

- [prompts.md](references/prompts.md)：进入对应 Step 后只读该阶段提示词。
- [style-options.md](references/style-options.md)：仅 S3 生成、修正和验收四套缩略图总览时读取。
- [page-spec.md](references/page-spec.md)：仅 S5/S6 创建或更新 Page Spec 时读取。
- [workflow-updates.md](references/workflow-updates.md)：仅用户改需求、交付后修改或跨版本恢复时读取。
- [models.md](references/models.md)：S3/S5 生图，以及 S6 需要背景清理/主体分离时读取。
- [reconstruction.md](references/reconstruction.md) 与 [scene-format.md](references/scene-format.md)：仅 S6 读取。
- `validate_page_spec.py`：验证内容确认、页序、稳定 ID、画布边界和图片交付状态。
- `overlay_text.py`：仅作为 Step 2 图片页的准确文字兜底。
- `build_image_ppt.py`：仅用于 Step 2 图片版合并。