kai-slide-creator · v2.30.0 · 2026-08-16 · sha256 ee504fa44c218b3a
kai-slide-creator v2.30.0A

Name: kai-slide-creator
Author: kaisersong
Immutable. This exact content is served forever at /api/v1/blob/ee504fa44c218b3a.
---
name: kai-slide-creator
description: 生成HTML演示文稿/幻灯片 — 稳定生成器覆盖核心风格，播放/演讲者模式。适用于路演、产品发布、技术分享、方案宣讲等场景。
version: 2.30.0
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`

## 使用方式

`/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` | SKILL.md + 已选风格文件（内置 `references/*.md` / `blue-sky-starter.html`；自定义 `themes/<name>/reference.md`）+ composition 源 + `references/title-quality.md` + `references/html-template.md` + `references/js-engine.md` + `references/base-css.md` + `references/impeccable-anti-patterns.md` | 从 `BRIEF.json` 生成 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。

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

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`。生成任何 HTML 前必读此文件。

**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。

**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 模式）