从 HTML Deck 到 Pro 团队资料库

本教程串起 SlideStage 的完整路径：从一份 HTML 幻灯片开始，生成 .stage，在 Lite 中验收播放，再上传到 Pro 团队资料库。

你会完成什么

完成后，你会得到：

一份经过校验的 .stage 文件。
一次 Lite 本地播放验收。
一份上传到 Pro 的团队 deck。

前提条件

你需要：

一份 HTML deck，例如 reveal.js、impress.js、huashu-design、html-ppt-skill 或普通 HTML。
可运行 slidestage-pack 的 Node.js 环境。
可访问的 SlideStage Lite。
一套已经部署好的 SlideStage Pro，并且你有账号。

1. 准备源目录

把 HTML deck 放在一个独立目录中。推荐至少包含一个入口文件：

my-talk/
  index.html
  assets/
  speaker-notes/

如果有 speaker notes，优先使用 sidecar Markdown 文件：

speaker-notes/
  01-cover.md
  02-demo.md

这样打包器可以把备注写进 manifest.slides[].notes，Lite 和 Pro 都能读取。

2. 探测框架

在 slidestage-pack 仓库或 skill 脚本所在环境运行：

node scripts/detect_framework.mjs ./my-talk

检查输出中的 kind 和 recommendedMode。

常见结果：

reveal：默认建议 wrap，保留 reveal runtime。
impress：默认建议 wrap，保留 3D 变换。
inline-deck：默认建议 split。
webcomponent-deck：默认建议 split。
router-html：默认建议 split。
plain-html：默认建议 single。

3. 打包 `.stage`

按推荐模式打包：

node scripts/pack_stage.mjs \
  --src ./my-talk \
  --out ./my-talk.stage

如果你确认要覆盖模式，可以显式传入：

node scripts/pack_stage.mjs \
  --src ./my-talk \
  --out ./my-talk.stage \
  --mode wrap

对 reveal.js 和 impress.js，除非你明确接受失去原框架运行时，否则优先使用 wrap。

4. 校验 `.stage`

上传或交给别人之前先校验：

node scripts/verify_stage.mjs ./my-talk.stage

如果校验失败，先修复源 deck 或打包参数，不要直接上传到 Pro。

5. 在 Lite 中验收

打开 SlideStage Lite，把 my-talk.stage 拖入页面。

验收时重点检查：

slide 顺序是否正确。
图片、字体、CSS 是否都能加载。
speaker notes 是否出现在演讲者视图。
reveal/impress 的交互是否符合预期。
如果出现信任提示，能力说明是否合理。

如果离线时资源丢失，先做 mirror pass，再重新验收。

6. 上传到 Pro

上传成功后，Pro 会：

校验 .stage zip 和 manifest。
计算 SHA-256。
保存 .stage blob。
创建 deck 和当前版本记录。
跳转到 deck 详情页。

7. 团队验收

在 Pro 中打开新 deck，检查：

标题是否来自 manifest 或上传时填写的标题。
slide 是否能正常播放。
笔记和批注是否能保存。
普通成员是否只能看到自己有权限访问的 deck。

何时重新打包

只要源 HTML、资源或 manifest 内容发生变化，就重新打包并重新校验。

重新打包后的 zip bytes 会改变，因此 deck 指纹也会改变。Lite 会把它视为新 deck；Pro 会把它作为新的上传版本保存。