# HTML 动态演示工作台｜学员使用说明

版本：2.1 · 2026-09-19

这个技能沉淀的是操作系统，不是老师的课程内容。你用自然语言讲思路，AI 帮你整理大纲、逐页制作；你拖动目录调整顺序，AI 按页面定位精准改稿，最后直接用浏览器演示。

## 1. 安装

解压后把完整的 `html-speaker-mode` 文件夹交给你的 AI 编程工具，告诉它：

> 请先阅读这个文件夹的 SKILL.md，把它安装为我的个人技能。如已有同名技能，先备份再升级，不修改其他技能。

Codex 常用目录为 `~/.codex/skills/html-speaker-mode/`；Claude Code 常用目录为 `~/.claude/skills/html-speaker-mode/`。Windows 中 `~` 表示个人用户目录。其他工具按其技能目录设置安装。当前交付验证的是通用网页运行及 Codex 技能格式，未逐一验证所有客户端。安装后新开对话，确认工具能发现技能。

无需把老师课件、个人照片、二维码放进技能；不要把 API 密钥放进分发包。

## 2. 开始制作

在支持技能的 AI 工具里说：

> 使用 $html-speaker-mode。我准备讲一个 20 分钟的主题，下面是我的口述想法……先整理大纲，等我确认后再生成。每页少文字，多用图形和动态演示，视觉由你设计。

确认大纲后说：

> 开始做。保留拖拽目录、可调布局、备注、分步播放与演示模式。打开本地预览，不部署。

已有材料：

> 使用 $html-speaker-mode 改造这份 index.html。内容和配色不变，只加编辑工作台和演示控制。

## 3. 精准修改，不用填一堆表单

点击“复制本页定位”，把定位和修改要求一起给 AI，例如：

> 第 2 页“让对比推动结论”，ID contrast：左侧保留，右侧换成一个流程图，分两次点击出现，其他页别动。

页码会因拖拽而变化，稳定 ID 不变。AI 应按 ID 修改文件，刷新同一预览标签验证。不需要重新生成整套材料。技能不是带聊天后端的独立 SaaS，AI 对话在你正在使用的编程工具里进行。

## 4. 编辑操作

- 拖拽左侧目录：改变页面顺序，编号随之变化。也可聚焦条目后按 Alt + ↑/↓。
- 分别拖动三条分隔线：目录宽度；当前页与下方区域高度；下一页和备注的宽度。
- 分隔线可用方向键微调，Shift 加大步长；双击复位，或点击“重置布局”。
- 在备注区写讲述要点和过渡句；不会出现在演示画面。
- 主页面是可交互的真实 HTML；下一页是小型只读预览。

## 5. 开始讲课

| 按键 | 作用 |
|---|---|
| F / 开始演示 | 隐藏编辑界面，只显示当前页 |
| Esc | 回到编辑模式，保留页和步骤 |
| 鼠标左键单击页面空白区域 | 本页下一步；完成后下一页 |
| → / ↓ / PageDown / 空格 / Enter | 本页下一步；完成后下一页 |
| ← / ↑ / PageUp / Backspace | 回退步骤；然后上一页 |
| Home / End | 第一页 / 最后一页 |
| B / W | 演示黑屏 / 白屏，再按恢复 |
| O / N | 编辑时打开目录总览 / 聚焦备注 |

翻页笔通常发送上述键值，课前用自己的设备试一次。鼠标点击按钮、链接、视频、二维码、输入控件或弹窗不会翻页；需要自定义交互区域时，可添加 `data-no-advance`。输入备注时不会误翻页。F 是网页内部干净播放，不强制关闭浏览器工具栏；如需整屏投影，再使用浏览器或应用的全屏功能。单屏镜像不要打开编辑界面给观众看；“独立观众屏”仅供双屏，可选使用。

## 6. 保存、交付和换电脑

当前版本分两类保存：

- **HTML 内容与素材**：在文件夹里，由 AI 修改。
- **拖拽顺序、备注、布局**：保存在当前浏览器和地址的本地存储里；刷新保留，但不会自动写回 HTML，换电脑/端口/浏览器不保证保留。

正式交付前点击“导出顺序”，把 JSON 给 AI：

> 请按这份顺序将源 HTML 顺序定稿；备份我的备注并写回对应稳定 ID，再检查页码、动效和首尾页。不要部署。

如果 AI 不能访问你的浏览器本地备注，就先从备注区复制给它，不要让它假装已同步。分享整个课件文件夹（index.html + assets），不能只拷贝 index.html。要单文件再明确要求 AI 内联素材并检查；网页嵌入、外链视频或 3D 资源可能仍需联网。

备注仅在演示界面隐藏，写在 HTML 文件里的讲稿不是加密内容。公开发布前检查敏感信息及素材授权。

## 7. 可选：自己快速运行样例

在技能目录打开终端，电脑有 Python 3 时运行：

```sh
python3 scripts/create_deck.py ./my-first-talk --title '我的第一次演讲'
python3 -m http.server 8144 --bind 127.0.0.1 --directory ./my-first-talk
```

浏览器打开 `http://127.0.0.1:8144/`。目标文件夹已存在时脚本会拒绝覆盖。端口占用请换一个，或继续使用已在运行的预览服务。停止服务在终端按 Ctrl+C。

## 8. 交给 AI 的最后检查

> 检查顺序、拖拽布局、刷新保存、备注、当前/下一页、键盘与鼠标点击推进、交互控件不误翻页、动效推进回退、F/Esc、窄窗口和素材加载。不要只做语法检查。告诉我哪些实际验证了，哪些（如真实翻页笔）还需要我试。