slidestage-pack CLI 参考

slidestage-pack 把 HTML 幻灯片目录、单文件 HTML、zip 或已有 .stage 打包成 SlideStage 可播放的 .stage 文件。

推荐流程永远是：

detect -> pack -> verify

detect

探测源目录或文件的框架类型。

node scripts/detect_framework.mjs <source>

输出包含：

• kind：识别到的源类型。
• rootHtml：入口 HTML。
• recommendedMode：推荐打包模式。
• hints：辅助说明。

常见 kind：

• slidestage@1.0
• reveal
• impress
• inline-deck
• webcomponent-deck
• router-html
• plain-html
• ambiguous
• empty

pack

打包为 .stage。

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

常用参数：

参数	说明
--src <path>	源目录、HTML、zip 或 .stage。
--out <path>	输出 .stage 路径。
--mode <mode>	显式指定 split、wrap、single 或 passthrough。
--title <text>	覆盖 manifest title。
--author <text>	写入 manifest author。
--id <id>	覆盖 manifest id。
--version <version>	覆盖 manifest version。
--width <px>	设置逻辑舞台宽度。
--height <px>	设置逻辑舞台高度。
--thumbnails	生成缩略图，需要 Playwright。
--fallback	写入可解压本地播放的 fallback 文件。
--strict	warnings 视为错误。
--strict-schema	使用 @slidestage/spec 做权威 schema 校验。
--use-core	委托给 @slidestage/core/converter。

verify

校验 .stage 是否可交付。

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

校验内容：

• zip 可解压。
• 根目录有 manifest.json。
• schema === "slidestage@1.0"。
• 必填字段存在。
• slide 文件都存在。
• 路径安全。
• 包大小、单文件大小、slide 数量不超过限制。
• totalSlides 与 slides.length 一致。
• slides[].index 顺序正确。

模式选择

模式	用途
split	每张 slide 输出一个独立 HTML，适合结构化 inline deck。
wrap	保留原框架 runtime，适合 reveal.js / impress.js。
single	普通 HTML 作为一张 slide。
passthrough	已有 .stage 重新校验/打包。

默认使用自动模式。只有你明确知道取舍时才手动覆盖。

何时使用 --use-core

如果当前环境已经能 import @slidestage/core，可以使用：

node scripts/pack_stage.mjs \
  --src ./my-deck \
  --out ./my-deck.stage \
  --use-core

这会让 Pack 复用 Lite/Core 的 converter pipeline，减少行为漂移。

何时使用 --strict-schema

当你要发布、上传或归档正式 deck 时，建议开启：

node scripts/pack_stage.mjs \
  --src ./my-deck \
  --out ./my-deck.stage \
  --strict-schema

它会使用 @slidestage/spec 的 Zod schema 校验最终 manifest。

交付报告

每次打包后，向用户报告：

• 输出路径。
• 文件大小。
• SHA-256。
• slide 数量。
• 源框架和模式。
• warnings。

不要交付未校验的 .stage。