`.stage` Manifest 参考 — SlideStage 文档

.stage 是 SlideStage 的演示包格式。它是一个 zip 文件，根目录必须包含 manifest.json，并包含 slide HTML、资源、缩略图和可选的离线镜像信息。

权威 schema 由 @slidestage/spec 定义。Lite、Pro 和 Pack 都应以它为单一事实来源。

最小合法 Manifest

{
  "schema": "slidestage@1.0",
  "id": "my-deck",
  "version": "1.0.0",
  "title": "My Deck",
  "subtitle": null,
  "author": null,
  "description": null,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "architecture": "multi-file",
  "dimensions": {
    "width": 1920,
    "height": 1080
  },
  "totalSlides": 1,
  "slides": [
    {
      "index": 1,
      "id": "cover",
      "label": "Cover",
      "file": "slides/01-cover.html",
      "thumbnail": null,
      "notes": null
    }
  ]
}

必填字段

字段	类型	说明
`schema`	string	必须是 `slidestage@1.0`。
`id`	string	deck 标识，1 到 128 个字符；不能包含 `/`、`\`、`..`、NUL 或控制字符。
`version`	string	deck 版本，建议使用 semver，但不是强制。
`title`	string	deck 标题。
`subtitle`	string 或 null	副标题，可为空。
`author`	string 或 null	作者，可为空。
`description`	string 或 null	描述，可为空。
`createdAt`	string	创建时间，建议 ISO 8601；可作为稳定 zip mtime。
`updatedAt`	string	更新时间，建议 ISO 8601。
`architecture`	enum	见下方 architecture 值。
`dimensions.width`	number	逻辑舞台宽度，必须为正数。
`dimensions.height`	number	逻辑舞台高度，必须为正数。
`totalSlides`	integer	slide 数量，最大 500；与 `slides.length` 不一致时会被归一化。
`slides[]`	array	非空 slide 列表，最大 500。

`slides[]` 字段

字段	类型	说明
`index`	integer	从 1 开始。若不是顺序值，解析器会按数组顺序重编号。
`id`	string	slide 标识。
`label`	string	slide 在 UI 中显示的标题。
`file`	string	指向包内 HTML 文件的相对路径。必须通过路径安全检查。
`thumbnail`	string 或 null	可选缩略图路径。
`notes`	string 或 null	可选 speaker notes，长度上限为 `MAX_NOTES_CHARS`。
`duration`	number	可选，建议表示秒数。
`transition`	string	可选，producer 自定义转场提示。

Architecture 值

值	含义
`multi-file`	每张 slide 一个 HTML 文件，通常位于 `slides/`。
`multi-file-flat`	每张 slide 一个 HTML 文件，但不要求位于 `slides/`。
`single-file-deckstage`	producer 从单个 `<deck-stage>` 形态生成多张 slide。
`single-file-html`	一个 HTML 文件渲染整个 deck，常见于 wrap 模式。

原始来源框架不应写进 architecture。它属于 provenance.sourceKind，例如 reveal、impress、inline-deck、router-html 或 plain-html。

常用可选字段

字段	说明
`compat.requires`	deck 需要的运行能力，例如 `same-origin-storage`、`broadcast-channel`、`window-open`。
`compat.notes`	给用户看的信任提示说明。
`provenance`	记录来源框架、转换模式、转换器名称和版本。
`offline`	mirror pass 结果，用于说明外部资源是否已折入包内。
`assets`	producer 自定义资源清单。
`runtime`	producer 提供给播放器的提示。
`platform`	兼容性 gate，例如最低 schema 版本。
`tokens`	producer 自定义设计 token。

Manifest schema 是 passthrough 的：未知字段会被保留，但运行时可以忽略它们。不要依赖未知字段在所有工具链中 round-trip。

Trust 能力

能力	sandbox 变化	用途
`same-origin-storage`	加入 `allow-same-origin`	允许 cookie、localStorage、IndexedDB 等同源存储能力。
`broadcast-channel`	加入 `allow-same-origin`	允许 deck 内使用 BroadcastChannel。
`window-open`	加入 `allow-popups` 和 `allow-popups-to-escape-sandbox`	允许从 slide 打开新窗口或标签页。

基础 sandbox 永远包含 allow-scripts。能力授权按 deck 指纹保存。

路径安全

所有包内路径都必须：

使用 / 作为分隔符。
相对包根目录。
不以 / 开头。
不包含 .. 段。
不包含 NUL 或控制字符。
指向普通文件。

路径违规应以 E_PATH_TRAVERSAL 拒绝。

指纹规则

SlideStage 使用 .stage zip bytes 的 SHA-256 作为 deck 身份，而不是 manifest.id 或 manifest.version。

因此，打包器如果希望相同输入得到稳定指纹，需要：

固定每个 zip entry 的 mtime。
固定 zip 全局 mtime。
按路径排序 entries。
避免在 manifest.json 之外写入时间戳类字段。

运行时的批注、备注、信任授权、上次播放位置等都以这个指纹为 key。

权威来源

本页是常用参考。完整字段、错误码、大小限制、fixtures 和版本规则以 packages/spec/README.md 以及 @slidestage/spec 导出的 schema 为准。