1实现原理 · 为什么它能做到
产物定义先于一切：交出去的是「跑起来的 deck」而不是 MP4，并且明确禁止把 deck 交给 hyperframes render——因为 deck 由多个顶层 scene 合成、没有 master root，render 只解析第一个合成，会静默截断成很短的片子。
skills/slideshow/SKILL.md
**Do not `hyperframes render` a slideshow into a single MP4.**
这里在做什么：把渲染期最容易发生的静默错误写成红线（示例：40 秒的 deck 只出 6 秒），并声明线性导出「deferred」——在这之前支持的输出只有 present 的活 deck 与逐页 snapshot。
实现机制是「普通合成 + 一个声明式 JSON 岛」：合成仍是 HF 的 scenes/clips/GSAP，多出来的一块是 application/hyperframes-slideshow+json，播放器的 SlideshowController 读它，把连续时间线变成可离散导航的 deck。
skills/slideshow/SKILL.md
A HyperFrames slideshow is a normal HyperFrames composition — scenes, clips, GSAP timelines — with one extra ingredient: a **JSON island**
这里在做什么：把离散导航能力收敛到数据（slide 顺序、备注、片段时刻、热点、分支序列），而不是靠自定义导航脚本——所以 island 被定为唯一真源。
island 必须是真实存在的块、位置随意但要在 body 靠前：present 静态解析合成 HTML，若把 manifest 藏在别的 script 标签后由运行时代码生成，present 读不到。
skills/slideshow/SKILL.md
The `present` command reads the composition HTML statically and expects the real `application/hyperframes-slideshow+json` island to already be present.
这里在做什么：堵死「动态注入 island」这种看起来更优雅但会让 present 失效的做法，并要求 sceneId 与 data-composition-id 精确对应（lint 按后者解析）。
片段（fragments）是**绝对合成时间**上的揭示停点，导航由确定性 seek 驱动而不是播放：进入带片段的页会直接 seek 到 fragments[0] 停住，Next 依次 seek 到下一个停点。
skills/slideshow/SKILL.md
Navigation is seek-driven, not play-driven.
这里在做什么：把「翻页」从播放语义改成寻址语义，保证前后来回不出错；同时给无片段页规定停在页内静止帧（通常是中点）而不是 slide.end。
分支是真实存在的场景，只是不列进主线：点热点把 {sequenceId, slideIndex:0} 压栈进入分支首页，back 弹栈回父页、backToMain 清空栈；面包屑与计数器按序列作用域渲染。
skills/slideshow/SKILL.md
Clicking a hotspot pushes `{sequenceId, slideIndex: 0}` onto the nav stack and enters the branch's first slide.
这里在做什么：用一个显式的导航栈实现「答疑式跳转」，并禁止把分支 sceneId 写进主线 slides（lint 会判重叠）。
写作纪律是硬约束而非建议（完整句标题、一页一意、先讲最狠的点、市场测算必须自下而上、字号下限、动手前先搜 live catalog 找现成积木），并给出理由：违规的页会在评审时被直接替换。
skills/slideshow/SKILL.md
**Headline is a complete-sentence claim, not a label.**
这里在做什么：把「像投资人汇报」拆成可判定的规则（72–96px 标题、48px 正文、任何必须读的文字不低于 40px），并强调 catalog 搜索不需要项目、不需要安装。
移植既有页面时要求保真到机制层：以 native media 元素为唯一真相、由媒体事件与 media.currentTime 派生视觉状态、字体 token 必须落成具体字体栈、截图类内容按原比例 contain 而不能 cover。
skills/slideshow/SKILL.md
Treat native `<video>` / `<audio>` elements as the source of truth for any custom media chrome, canvas visualizer, waveform, beat grid, or playhead.
这里在做什么：把「照抄交互细节」列为契约（自定义播放器/可视化/滚动驱动的镜头运动都要迁），同时明确通用行为要放进播放器/控制器而不是每副 deck 的私有脚本。
讲者模式由共享组件拥有：Present 按钮/P 键、新开 audience 标签页、两个标签页用 BroadcastChannel 同步；备注在讲者视图里编辑并存 localStorage（覆盖 manifest 而不改合成文件）。
skills/slideshow/SKILL.md
**Presenter mode:** use the built-in Present icon button in the slideshow nav capsule, or press P.
这里在做什么：明确禁止自造 Present 按钮/静音按钮/备注脚本（共享组件拥有位置、图标、样式与 audience 模式隐藏），并把 Meet/Zoom 的分享方式写成可执行建议（分享 audience 标签页，不要分享整个屏）。
媒体清理与静音属于控制器职责且有跨 realm 细节：换页/换序列时由控制器调 stopMedia；同一页内的片段导航不清媒体；判断 iframe 媒体不能用父页的 instanceof（真实浏览器返回 false）。
skills/slideshow/SKILL.md
The slideshow controller owns slide-exit media cleanup.
这里在做什么：把「暂停/静音」的责任边界钉死，避免各 deck 自己写清理脚本；并强调这类修复必须在真实浏览器里验证，而不是单 realm 的单元测试。
standalone harness 是过渡方案而非正统：引擎托管路径（preview --slideshow / studio present mode）未落地之前，裸播放器打开的 demo 需要三个绕行（暴露可 seek 的 root 时间线、把 island 复制进 wrapper、wrapper 自持音频）。
skills/slideshow/references/standalone-harness.md
These patterns are a **temporary workaround** for standalone demos.
这里在做什么：给出一份带足坑清单（island 未复制 → 导航条不渲染；wrapper SFX 放 iframe → 静音；无自时钟 → 首屏错页；Three.js 遮挡 → 3D 不可见）的实现参考，同时反复声明「引擎路径落地后大部分内容会塌缩」。
2核心能力
01JSON island 授权：一个 application/hyperframes-slideshow+json 块声明主线 slides、分支 slideSequences、每页 notes / fragments / hotspots（TTS 三字段为保留位）
02片段揭示：把一页内的多个揭示停点写成绝对时间数组，导航逐点 seek 停住而不播放
03分支导航：热点（可带百分比区域或退化为全页按钮）触发进入分支序列，支持 back / backToMain、面包屑与序列作用域计数器
04讲者模式：Present 按钮/P 键开 audience 标签页，讲者视图含当前页缩略、下一页预览、备注与计时；两页用 BroadcastChannel 同步；备注编辑存 localStorage
05演示与交付：present 起本地服务（含 package.json dev 脚本示例）、Meet/Zoom 分享指引、换页自动清理媒体、可选全局静音覆盖 iframe 与顶层音频
06源页面移植：保留原站视觉/动效/交互与媒体行为，把滚动驱动的镜头运动重挂到幻灯片导航上，截图类证据内容按原比例 contain
07结构校验契约：lint 检查 sceneId 解析、热点 target 存在、片段落在页区间内、主线时间不重叠；check 再跑运行时校验
08standalone harness（过渡）：父壳复制 island、合成暴露 root 时间线 + 可见性控制器、postTimeline 消息桥、Three.js 独立 rAF 层、音频解锁与自持 SFX
09确认门禁：非明确要求幻灯片时先暂停并问一句「Do you want this as a HyperFrames slideshow?」，这是因为交付物类型错误属质量失败而非偏好问题
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | 官方 hyperframes CLI：present（起 deck 服务与讲者/观众同步）、lint、check、preview、snapshot（逐页静帧） |
| package | 播放器构建产物（本仓 packages/player/dist 的 hyperframes-player / hyperframes-slideshow 全局包；改播放器行为后需在 packages/player 跑 bun run build） |
| network | CDN 资源（harness 示例）：Three.js 模块从 jsdelivr 导入，供独立 demo 的 3D 背景层使用（产物期由浏览器拉取，按范式不判级） |
| package | 浏览器平台 API（非外部服务）：BroadcastChannel 讲者/观众同步、localStorage 备注持久化、postMessage 与 iframe 播放器通信、WebAudio/Audio 自持音效 |
| package | 兄弟 skill 关联：deck 内容来自 Figma 时必须先跑 /figma（资产导出/品牌令牌/分镜重建），基础合成契约在 /hyperframes-core，词级字幕规则在 /embedded-captions |
| cli | 官方 registry 搜索/安装（写页面前先 catalog 查现成视觉积木，需要时 add 进 deck） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: 本 skill 目录内**没有自带脚本**（2 个文件：SKILL.md + references/standalone-harness.md）；ha
- 网络端点: 声明外部网络访问: 产物期（按范式不判级，仅记录）：harness 的 Three.js 示例从 cdn.jsdelivr.net 导入 [email protected]，由浏
- 本地工作目录: 文件读写与工件输出: 项目文件（由 agent 写）：合成 HTML（含 island 与场景 div）、wrapper/index.html 与 composition/
审计说明： 。判级对象＝skill 自身目录：2 个 markdown，零脚本、零网络调用、零凭证读取、零写入指令；HTTP(S) 全域扫描只命中 1 处，且是 harness 示例里的 [email protected] CDN 导入（产物期由浏览器拉取，按范式不判级，已记入 reason 与 network_calls）。能力实现方式是「授权数据 + 本地 CLI 与服务」：写合成 HTML/JSON 岛、用 npx hyperframes present/lint/check/snapshot 在本地起服务与校验、产物通过本仓 packages/player/dist 的播放器包运行——属「仅本地 CLI 与本地读写」，与同仓先例 hyperframes-core（蓝）、talking-head-recut（蓝）同档。未达橙档：没有任何凭证/环境变量读取，也不把用户素材送往外部生成后端（无 TTS/图像生成调用，TTS 字段在 island 里明确是保留位）。未达红档：无沙箱关闭、TLS 降级、反自动化绕过或任意代码执行面（示例代码是给人采纳的参考实现，不是自动执行的脚本）。
5第二遍独立确认
- [ok] 网络面是否真如声明（蓝档判定的关键反例检查） — 全目录仅 1 处 http(s) 命中：standalone-harness.md 第 895 行的 [email protected] jsdelivr 导入（示例代码块内）；无 fetch(、无 process.env、无 child_process、无凭证关键词。SKILL.md 侧只有本地命令（present/lint/check/preview/snapshot）与浏览器 API（BroadcastChannel/localStorage/postMessage），均为本地或浏览器内行为。
- [ok] 「禁止 render」的声明是否与机理自洽（不是随口警告） — SKILL.md 给出原因：deck 由多个顶层 scene 合成（每页一个 data-composition-id）且**没有 master-root 合成**，所以 render 只解析第一个合成，产出静默截断的 MP4（举例 6s/40s）；并说明线性导出（仅主线、排除分支）目前是 deferred，故支持输出为 present 活 deck 与逐页 snapshot。声明与结构描述一致。
- [ok] island 的「静态可读」要求与 present 行为是否一致 — 文档明确 present 静态解析合成 HTML、期望真实的 application/hyperframes-slideshow+json 已存在，并禁止用另一个 application/json 块 + 运行时代码生成 island。这与「JSON 岛是唯一真源、sceneId 必须匹配 data-composition-id」的 lint 契约自洽。
- [ok] harness 内容是否被当成正统做法（避免误判为「本 skill 主张两套实现」） — harness 开头即写 interim framing（临时绕行）与「When that path ships, most of what follows collapses」，SKILL.md 亦写「Do not treat the patterns there as the blessed model」。两处口径一致，属过渡文档而非第二套正统。
- [ok] 是否存在夸大（把引擎/播放器能力算作本 skill 能力） — 文档反复把导航、presenter mode、媒体清理、静音归给共享播放器组件（<hyperframes-slideshow> / SlideshowController / hyperframes-player.stopMedia），本 skill 只声明 island 数据契约与写作/移植纪律，未见据他人之功。
6结论
适合： 适合要做可演讲的 deck 的人：融资/销售 pitch、内部评审、课程或技术分享，需要离散页、逐步揭示、答疑式分支（热点跳转到备用页再返回）、讲者备注与观众双屏同步；也适合把既有网页（含自定义播放器、可视化、滚动动效）转成一份保真的交互 deck，以及在本地用 present 起服务交付给他人打开。
不适合： 不适合：① 需要 MP4/视频文件交付的场景（本 skill 明确不支持，线性导出 deferred——要视频请走 /general-video 或对应工作流）；② 需要旁白配音的演示（TTS 未接线，应走 /hyperframes-audio 等音频工作流）；③ 只想要一页静态图或海报（用 snapshot/其他 skill 更直接）；④ 期待开箱即用的 Studio 编辑器内流程的人（本 skill 建议最终交付走 present 而非 Studio）；⑤ 不愿维护前端产物（deck 是活页面，长期可用性依赖播放器包与浏览器行为）。
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload slideshow.tar.gz
sha256:
Option B · Copy Guide for Agent034ea590dd179243…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d2f0bc7f34.