v2.31.0 to v2.32.0

---

name: kai-slide-creator

description: 生成HTML演示文稿/幻灯片 — 稳定生成器覆盖核心风格，播放/演讲者模式。适用于路演、产品发布、技术分享、方案宣讲等场景。

metadata: {"openclaw":{"emoji":"🎞","os":["darwin","linux","windows"],"homepage":"https://github.com/kaisersong/slide-creator","requires":{"bins":["python3"]},"install":[]}}

---

# kai-slide-creator

生成零依赖 HTML 演示文稿，纯浏览器运行。主路径是 IR-first：`user prompt → BRIEF.json → HTML → validate`。

## 安装

**Claude Code:** 告诉 Claude「安装 https://github.com/kaisersong/slide-creator」

**OpenClaw:** `clawhub install kai-slide-creator`

生成器需要 Python 3.10+ 与 `beautifulsoup4`；安装运行包后，在 Python 虚拟环境执行 `python -m pip install -r scripts/requirements-runtime.txt`。生成与契约查询使用该环境的 Python 可执行路径。生成后的 HTML 无需 Python，直接由浏览器运行。

## 使用方式

`/slide-creator ...` 是 Claude/OpenClaw 的 slash 技能调用，不是 bash 命令。

**规划深度：**

- `自动` (Auto) — 快速出稿，约 3-6 分钟

- `精修` (Polish) — 深度规划，约 8-15 分钟，自动执行 Review

**内容类型 → 风格推荐：**

| 内容类型 | 推荐风格 |

|---|---|

| 数据报告 / KPI 看板 | Data Story、Enterprise Dark、Swiss Modern |

| 商业路演 / VC Deck | Enterprise Dark、Blue Sky、Swiss Modern |

| 产品发布 / SaaS | Blue Sky、Enterprise Dark、Data Story |

| 开发工具 / API 文档 | Data Story、Blue Sky、Enterprise Dark |

| 研究 / 思想领导力 | Swiss Modern、Data Story、Chinese Chan |

| 创意 / 个人品牌 | Blue Sky、Swiss Modern、Chinese Chan |

| 哲学 / 思想 | Chinese Chan、Swiss Modern |

| 咨询报告 / 战略方案 | Enterprise Dark、Swiss Modern、Data Story |

## 命令路由

`自动` (Auto) — 快速出稿 | `精修` (Polish) — 深度规划，自动执行 Review

| 命令 | 加载内容 | 行为 |

|------|----------|------|

| `--plan [prompt]` | `references/brief-template.json`；如用户指定了 custom theme，同步加载 `themes/<name>/reference.md` | 创建 `BRIEF.json`；仅在用户明确要求时额外派生 `PLANNING.md` |

| `--generate` | `references/generation-contract.md` + `python3 main.py --model-context --preset <已选风格>` 的 JSON；技术文稿再读 `references/technical-language.md`。`references/title-quality.md` / `references/impeccable-anti-patterns.md` 仅深度精修/review 按需加载 | 模型只写完整 `BRIEF.json`，程序读取全部风格与 runtime 并生成 HTML，执行写入前门禁；用户显式要求 `eval` 时产出单 deck 评测 JSON |

| `--review [file.html]` | `references/review-checklist.md` + 目标 HTML | 执行 17 项检查点 → 确认窗口 → 修复/报告 |

| 无 flag (交互式) | `references/workflow.md` + 其他按需 | 遵循 Phase 0-5 |

| 直接给内容 + 风格 | 同 `--generate` | 先落一个有效 `BRIEF.json`，再按 preset 能力路由到 native deterministic renderer、统一 profile renderer 或 custom theme renderer，并执行 strict 写入前门禁；禁止绕过 BRIEF 手拼最终 HTML |

**渐进式披露：** 每个命令只加载所需文件。`--plan` 只提炼 IR，不接触 CSS。正常生成时，模型不读取完整 starter、CSS/JS、HTML 模板或 renderer 源码；程序仍完整读取这些实现。精简契约缺少某个具体设计决策时，才按需打开已选风格的相关章节。

**技术语言：** 技术文稿遵循 `references/technical-language.md`，ASD-STE100 对齐项目评分尽量达到 ≥80/100，作为观察项；内容事实和质量优先。英文使用简化技术英语，中文按同样清晰度原则适配；保留用户指定语言、技术名称、事实与条件。非技术文稿不强制 STE。这个分数不是标准认证，完整词典合规不得未经核验声称通过。

## 核心规则（按优先级）

1. **风格强制**

所有颜色、字体、组件、背景、动画、图表色、signature elements 都**必须且只能**来自选中的风格文件。模板里的 `[from style file]` 和示例值只是占位，禁止直接使用。

当前稳定生成器覆盖：`Swiss Modern / Enterprise Dark / Data Story / Blue Sky / Chinese Chan`。所有内置风格在用户显式选择时都必须可生成。五个 native deterministic core 是最稳定生成面；默认推荐面只包含 `Swiss Modern / Enterprise Dark / Data Story / Blue Sky`，`Chinese Chan` 仅作为 contextual recommendation。其他完整 reference-backed 风格走统一 profile renderer，共享 `BRIEF.json`、shared runtime、strict validation 和 eval/release gate。非核心 profile 必须通过 historical demo parity gate，才可描述为恢复到历史风格保真；但它们仍不冒充 native deterministic core，也不进入默认推荐面。只有 reference 缺失、已归档、custom theme 无效、或 strict validation 无法修复通过时才 fail closed，并给出最接近的可稳定生成替代项。

Custom theme（`themes/<name>/reference.md`）与 generator-ready / unified profile preset 同等可显式渲染。`BRIEF.json` 的 `style.preset` 支持四种值：native core 内置 preset 名、profile-rendered 内置 preset 名、custom theme 文件夹名、或 `themes/<name>/reference.md` 路径。代码层会自动归一化解析；内置 canonical 名优先解析为内置 preset，`custom:<name>` 强制选择自定义主题。

**Swiss Modern 额外要求 canonical export path**：面板保持 `.slide` direct child，token 保持 `--bg/--text/--red`，使用 canonical 类（`.left-panel/.right-panel/.stat-row/.cta-block`），并写入 `data-export-role`；不得生成 `.left-col/.right-col` 或 `--bg-primary/--accent` 这类兼容别名。

2. **叙事弧线**

先锁内容结构，再锁 composition route。每页都要有明确 page role、不同布局意图和足够的信息推进；不要先拼播放/编辑壳子，再回头补故事。内部 route 名称属于实现细节，不要挤占用户入口层。

3. **标题质量**

标题必须是断言式，禁止 Overview / Introduction / Summary / 结论 / 概览 这类通用标签。多行标题必须平衡，不能出现孤儿行、塌陷中间行或靠过窄 measure 硬挤换行。规则和示例只看 `references/title-quality.md`。

4. **运行时与壳子基线**

非 Blue Sky 风格必须走共享壳子：`body[data-preset]`、`scroll-snap`、`SlidePresentation`、`PresentMode`、首屏 `.visible` 修复、`data-notes`、shell markers。Blue Sky 是唯一允许保留自身 `#stage/#track` 架构的 preset。

5. **可降级功能**

播放模式、编辑模式、水印都默认开启，但优先级低于风格、叙事和标题。

- 播放模式：默认开启

- 编辑模式：默认开启，**可省略编辑模式**，尤其在用户明确说不要或 existing HTML/导入场景受约束时

- 水印：默认保留，但必须是 JS 注入到最后一页，`position: absolute`，禁止 `position: fixed`

实现细节见 `references/html-template.md`，由 renderer 读取并执行。正常生成必读 `references/generation-contract.md`，无需让模型重复读取完整 HTML/CSS/JS。

**Direct-route guard:** 无论是 `--generate` 还是“直接给内容 + 风格”，都必须先 materialize 一个有效 `BRIEF.json`，再按能力路由：native core、统一 profile renderer、custom theme 都走同一 `render_from_brief()` 产品路径。写出最终文件前必须通过 `python3 scripts/validate_html.py "$TMP_HTML" --strict`。禁止手拼最终 HTML；禁止在交互式路径里绕过 BRIEF/style contract 手拼最终 HTML。

**User-preset guard:** 用户显式指定风格时，先在本次工作目录保存 `SLIDE_REQUEST.json`（`{"version":1,"preset":"用户原始指定值"}`），再编写 BRIEF。生成器自动读取并核对，不依赖模型记得传参数；冲突时拒绝写出且保留已有产物。收到 `PRESET MISMATCH` 必须修正 `BRIEF.style.preset` 后重新 canonical render，不能修改用户请求来绕过。调用方也可用 `--requested-preset` 或 `--request-file` 提供约束；别名按实际 reference 归一化。新任务不能沿用旧任务请求；用户未指定时保持原有推荐流程。

**Existing-deck restyle guard:** 只修改现有 deck 的文案、数据或同风格组件时，可以直接编辑 HTML 后运行该 preset 的 strict gate。只要用户要求更换或重新套用 preset，就必须先把现有内容提取为合法 `BRIEF.json`，再调用 `render_from_brief()` 重建；禁止向旧 DOM 注入新 preset 的 CSS/runtime 壳子来冒充重套风格。全页图片只能作为 renderer composition 内的资产，不能覆盖或替代 preset-specific 内容 DOM。

**Optional eval artifact:** 当用户显式要求 `eval` / `评测` 时，生成链路应在 strict gate 通过后额外写出单 deck 评测 JSON。原始 CLI 对应 `--eval`（默认写同名 `.eval.json`）或 `--eval-out <path>`；评测至少包含 `style_score (= style_signature_coverage)`、quality gates、hard failures 与关键 diagnostics。

## Pre-Write Validation Pipeline（写入前门禁）

组装完整 HTML 后，先写入临时文件，再运行：

任一失败都算生成失败，必须修复或重生直到通过。

**核心门禁顺序：**

1. **风格强制 / canonical export**

选中风格的 Signature Elements、Typography、Components、Background 必须完整注入；不得遗漏 checklist 项。Blue Sky 例外：使用 `blue-sky-starter.html` 基底。

2. **叙事弧线 / composition route**

页数、page roles、composition route 必须完整；连续两页不得使用相同布局；每页至少使用 2-3 种组件类型，不得只用 `.g` + `.bl` 堆砌。单页列表项 ≤ 5 条；标题 + 正文段落 + 列表三者不得同时出现在同一页（内容过多时拆页）。

3. **标题质量**

标题规则见 `references/title-quality.md`。

4. **架构隔离 / runtime**

非 Blue Sky 风格必须使用 `scroll-snap-type: y mandatory` + `SlidePresentation`。`#stage/#track`/`translateX` 只允许 Blue Sky。

5. **Preset metadata / shell markers**

`body[data-preset]` 必须存在且非占位；写出 `id="slide-N"`、`#brand-mark`、`.nav-dots`、`.progress-bar`、`.slide-num-label`、`data-export-role`。

6. **对比度 / token 使用**

文字对比必须正确；浅底不用浅字，深底不用深字；优先用风格 token，不要发明局部颜色。

7. **字体 / CJK**

Google Fonts 合并为单一链接；`<style>` 开头要有 `body { background-color: ... }` 回退；CJK 页面追加对应 `Noto Sans SC/JP/KR`。

8. **CSS 工程**

布局、背景、间距通过 CSS 选择器定义；inline `style=""` ≤ 5 处，目标 0。

9. **低级错误与模板完整性**

禁止 U+FE0F。Blue Sky 模板路径还要检查 REQUIRED BLOCK、`@keyframes`、以及 `go()` 返回 boolean。

> 更多视觉和内容规则在 `--review` / Phase 3.5 Review 中执行。完整反模式映射表见 `references/impeccable-anti-patterns.md`。

## 风格参考

只读取已选风格的文件：

- **内置预设**：完整列表、风格说明和选择建议都在 `references/style-index.md`

- **支持层级**：默认推荐面与 support tier 定义在 `references/preset-support-tiers.json`

- **内置风格文件位置**：统一在 `references/` 下；Blue Sky 例外，使用 `references/blue-sky-starter.html`

- **自定义主题**：`themes/<name>/reference.md`

- 风格选择器：`references/style-index.md`

- 视口与共享 CSS：`references/base-css.md`

- 设计质量基线：`references/design-quality.md`

- 标题规则：`references/title-quality.md`

- 反模式：`references/impeccable-anti-patterns.md`

- `BRIEF.json` 已存在 → 直接读取并作为真相源

- 只有在用户明确要求人工审阅时才派生 `PLANNING.md`

- 现有 HTML 增强遵循 `references/workflow.md` 的 Enhancement Mode

## 相关技能

- **kai-html-export** — 导出 PPT（图片模式或 Native 模式）