为 `.stage` 生成离线资源包

有些 HTML deck 依赖外部图片、字体、CSS 或媒体。离线 mirror 会把可下载的外部资源折入 .stage，让 deck 在无网络环境中尽量保持一致播放。

什么时候需要 mirror

使用 mirror，当 deck：

• 引用了 CDN 图片、字体或 CSS。
• 需要在断网会议室播放。
• 要上传到长期归档系统。
• 要交给不能访问公网的团队。

如果 deck 已经只使用本地资源，不需要 mirror。

1. 准备 .stage

先生成普通 .stage：

pnpm convert pack ./my-deck --out ./my-deck.stage

或使用 slidestage-pack 生成。

2. 运行 mirror

在 SlideStageLite 仓库中运行：

pnpm mirror ./my-deck.stage -o ./my-deck.offline.stage

输出文件会写在 -o 指定路径。

3. 调整资源预算

默认策略会限制单个资源和总下载量。大型 deck 可以按需调整：

pnpm mirror ./my-deck.stage \
  -o ./my-deck.offline.stage \
  --max-asset-bytes 10485760 \
  --max-total-bytes 209715200

建议先压缩源资源，而不是无限提高预算。

4. 是否包含脚本和 iframe

默认不建议 mirror 外部脚本和 iframe。只有在来源可信时才开启：

pnpm mirror ./my-deck.stage \
  -o ./my-deck.offline.stage \
  --include-scripts \
  --include-iframes

外部脚本即使被镜像，播放时仍然运行在 deck sandbox 中。不要对不可信来源开启。

5. 生成报告

可以输出 Markdown 报告用于审计：

pnpm mirror ./my-deck.stage \
  -o ./my-deck.offline.stage \
  --report ./mirror-report.md

报告应说明：

• 成功镜像的 URL。
• 写入包内的路径。
• 跳过的 URL。
• 跳过原因，例如过大、不可达、被策略阻止。

6. 验收离线包

把 my-deck.offline.stage 拖入 Lite。

检查：

• 断网后图片和字体仍可显示。
• offline badge 或等价提示符合预期。
• speaker notes 和批注不受影响。
• 需要信任能力的 deck 仍会显示授权提示。

安全策略

Mirror 默认应拒绝：

• localhost。
• 私有网段。
• link-local 地址。
• 云元数据地址。
• 明显不可下载或超预算资源。

如果确实需要访问私有网络资源，应在隔离网络中运行，并明确记录原因。

常见问题

离线后仍有资源丢失

检查报告中的 skipped URLs。常见原因是资源过大、服务端拒绝下载、URL 由 JavaScript 动态生成。

JS 动态加载的资源没有被 mirror

Mirror 主要重写静态 HTML/CSS 引用。JavaScript 字符串、运行时 fetch()、动态 import() 不保证被发现。

输出包太大

压缩图片、裁剪视频，或降低 --max-total-bytes 让 mirror 显式跳过过大资源。