HyperFrames 幻灯片路由Slideshow Route构建可交互演示文稿的完整指南【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 的 slideshow 路由是一条面向 Agent 的创作路线输入一段简报、大纲或现有页面输出一份可运行、可导航的交互式演示文稿deck而不是一个线性的 MP4。本文以 skills/hyperframes/references/routes/slideshow.md 为核心骨架结合官方指南docs/guides/slideshow.mdx、docs/studio/slideshows.mdx与 packages/player、packages/parsers、packages/cli 的源码实现系统讲解该路由的输入输出契约、创作流程、核心配置JSON island 清单、底层导航状态机与 presenter 模式的实现原理帮助你理解并复用这套幻灯片即 HTML 组合composition的技术方案。一、路由契约输入、输出与触发词输入Input一份简报brief产品策略大纲、领导评审材料等文字材料或一份提纲outline或一个现有页面需要被改写成演示文稿的 HTML 页面或已有 deck。如果用户的请求中出现 slides、deck、convert this page 这类歧义表达Agent 应在正式创作前先向用户确认是否确实想要一个 HyperFrames slideshow。这是路由确认问题routing confirmation在 triage 阶段提出且在所有模式下都必须保留——错误路由本身就是质量问题。输出Output交付物是一个可运行的 HyperFrames composition外加供SlideshowController使用的JSON island。具体能力包括离散幻灯片discrete slides每一页对应组合时间轴中的一个场景区间片段揭示fragment reveals逐条揭示内容配合讲解节奏分支branching可选分支与返回路径热点hotspots页面上可点击的跳转按钮演示者模式presenter mode包含演讲者备注与计时器演讲者备注speaker notes辅助演讲者不重复幻灯片内容。一句话概括交付物形态可导航的 deck而不是 MP4。触发词Triggersmake a pitch deck做一个融资/提案演示文稿interactive presentation交互式演示convert this page into slides把这一页转成幻灯片slideshow with presenter mode带演示者模式的幻灯片路由面试Interview与前置能力该路由的面试只有一个问题——上面提到的路由确认本身。运行形态run-shape两者皆非交付物是可导航 deck不是渲染视频。前置能力展示front-door capability offer应跳过路由确认之后deck 工作流接管其余所有选择观众、核心结论、是否需要揭示/分支/备注等无需再展示能力菜单。二、创作流程从请求到可导航的 deck1. 提出请求把材料与演示文稿应支撑的决策一起交给 AgentUsing /hyperframes, turn this product strategy outline into a presentation for our leadership review: [paste outline]Agent 会确认观众、核心结论main outcome以及 deck 是否需要片段揭示、可选分支或演讲者备注。你无需在看到拟定结构之前预先规定每一页幻灯片。注意如果结果需要从头到尾无人值守地线性播放应改用普通视频工作流。slideshow 目前不能导出为单个线性 MP4。2. 一个关键警告不要在 deck 上执行hyperframes render官方指南明确警告不要在 deck 上运行hyperframes render。它不会失败——但 deck 没有主根组合master root composition渲染只会解析第一张幻灯片并写出一段被静默截断的 MP4。你可能拿到一段 40 秒 deck 中的 6 秒且没有任何缺失警告。正确操作是现场演示使用hyperframes present逐页静态图使用hyperframes snapshot。从源码角度看这个警告是有依据的SlideshowController以场景区间 保持帧的方式驱动播放器见下文底层状态机deck 的结构本身就不是为线性导出设计的。3. 演示者需要什么控制能力需求做法讲清楚故事每张幻灯片一个主张claim、一个有用的可视化、简洁的演讲者备注边讲边揭示需要演讲者控制讲解节奏处使用渐进式揭示progressive reveals提供可选细节主故事保持直接深层材料放在清晰的分支与热点后面转换交互页面保留其视觉语言把原有动效翻译成有意的幻灯片与揭示状态主故事清晰原则即使任何可选分支都没有被打开主故事也应自洽成立。4. 以演示者的视角评审每张幻灯片表达一个清晰的观点揭示有助于讲解热点显而易见但不分散注意力离开某张幻灯片时其中的内嵌媒体停止播放演讲者备注与观众视图保持分离完整 deck 可同时通过键盘、触摸与可见控件操作。之后可以用 Studio 的 Slideshow 面板调整顺序、备注、揭示与分支。三、演示 deckhyperframes present与 presenter 模式npx hyperframes present project-directory打开本地 URL 后点击Present或按P键。观众获得干净的全屏视图演讲者则保留当前幻灯片、下一张幻灯片、备注与计时器。Google Meet共享观众的标签页Zoom把观众标签页移动到独立窗口再共享该窗口。present 命令的可用参数根据 packages/cli/src/commands/present.ts 的实现该命令支持以下参数参数类型默认值说明dirpositional当前目录项目目录--portstring3004present 服务端口--openbooleantrue是否自动打开浏览器--no-open关闭--browser-pathstring—指定打开的浏览器可执行文件--user-data-dirstring—Chromium 兼容用户数据目录要求配合--browser-path--remote-debugging-portstring—Chromium 远程调试端口要求配合--browser-path与--user-data-dir命令说明Serve a slideshow deck and open it in presenter mode (with audience sync)——即启动一个本地服务并以演示者模式打开带观众同步。典型用法示例来自exampleshyperframes present # 演示当前 deck hyperframes present ./my-deck # 演示指定项目目录 hyperframes present --port 8080 # 自定义端口 hyperframes present --no-open # 不自动打开浏览器 hyperframes present --browser-path /usr/bin/chromium # 指定浏览器presenter 模式在浏览器里做了什么从 packages/player/src/slideshow/hyperframes-slideshow.ts 的实现看present()的流程是用 URL API而非字符串拼接在当前页面 URL 上追加modeaudience查询参数避免#fragment冲突导致观众标签页以未同步的第二个 presenter启动通过relnoopener noreferrer的锚点点击打开新标签页window.open带 features 字符串容易创建会被遮挡冻结的弹窗窗口故弃用为本元素设置data-hf-presentingtrue启动秒级计时器更新耗时读数通过SlideshowChannelBroadcastChannel向观众标签页广播位置与媒体状态。观众模式modeaudience或 URL 上的?modeaudience下不渲染导航控件只保留全屏切换观众窗口的syncTo通过通道消息静态恢复演示者当前位置。四、配置核心JSON island 清单与 Manifest 结构deck 的结构数据以JSON island的形式嵌入 composition HTML——即一个script typeapplication/hyperframes-slideshowjson标签。解析器位于 packages/parsers/src/slideshow/parseSlideshow.ts类型定义位于 packages/parsers/src/slideshow/slideshow.types.ts该模块从hyperframes/core/slideshow重导出以保持向后兼容见 packages/core/src/slideshow/index.ts。Manifest 顶层结构{ version: 1, slides: [ { sceneId: ..., notes: ..., fragments: [...], hotspots: [...], autoplay: false } ], slideSequences: [ { id: ..., label: ..., slides: [ ... ] } ] }version当前 schema 版本常量SLIDESHOW_MANIFEST_VERSION 1持久化时打上便于未来 schema 变更检测与迁移slides主路线main line的幻灯片引用数组必填slideSequences可选分支序列数组。SlideRef 字段说明字段类型说明sceneIdstring指向组合中场景的 ID必填startTime/endTimenumber幻灯片在场景时间轴上的起止可省略见下文时间解析notesstring演讲者备注fragmentsnumber[]片段揭示的保持点时间数组hotspotsSlideHotspot[]热点按钮数组autoplayboolean进入幻灯片时是否自动播放其首个video默认 false仅当视频是幻灯片主要内容时使用不作为背景/氛围片段ttsScript/ttsAudioUrl/ttsDurationMs为预留字段TTS 暂缓会被解析并携带但当前不被消费。SlideHotspot{ id: a1, label: 查看细节, target: branch-id, region: { x: 70, y: 20, w: 15, h: 8 } }id热点唯一标识label按钮文案同时用于 aria-labeltarget引用的SlideSequence.idregion相对幻灯片的百分比区域x/y为左上角用于定位浮动热点胶囊按钮。SlideSequence分支{ id: deep-dive, label: Deep dive, slides: [ { sceneId: ... } ] }时间解析规则resolveTimeRange见 parseSlideshow.ts 的resolveTimeRange两者都显式startTime且endTime直接使用无需场景参与两者都省略从场景解析{ start: scene.start, end: scene.start scene.duration }只给一个边界需要场景来补全另一个边界若场景缺失报错slide X sets startTime but endTime cannot be resolved (no scene X)之类清晰错误。resolveSlideshow还会做一系列校验并把错误收集到errors数组片段时间越界fragment X is outside range [start, end]endTime startTime的非法区间重复的分支序列 ID保留最后一个定义热点指向未知或空分支序列主路线幻灯片区间重叠。解析后的结构ResolvedSlide在SlideRef基础上追加{ start: number; end: number; fragments: number[]; // 恒存在、已排序、默认 [] hotspots: SlideHotspot[]; // 恒存在、默认 [] }ResolvedSlideshow形如{ slides: ResolvedSlide[], sequences: Recordstring, ResolvedSlideSequence }。五、底层状态机SlideshowController 的导航语义SlideshowControllerpackages/player/src/slideshow/SlideshowController.ts是整个 deck 的核心导航状态机。它维护一个导航栈StackFrame[]每个帧包含sequenceId主路线为MAIN、slideIndex、fragmentIndex-1表示首个片段之前/幻灯片开头。导航操作一览操作行为next()若当前片段未揭示完 → 揭示下一个片段否则 → 进入下一张幻灯片若在分支末尾 → 返回父时间线prev()回到上一张幻灯片若是分支第一张 → 返回父时间线goToSlide(index)跳转到当前序列的指定幻灯片enterBranch(sequenceId)压栈并进入分支第一张幻灯片back()弹栈返回父幻灯片并恢复保存的 fragmentIndex而非重置到开头backToMain()直接回主路线恢复精确位置syncTo(sequenceId, slideIndex, fragmentIndex)观众镜像无动画跳到绝对位置重设栈后静态恢复关键语义从不自动前进playTo(t)是纯同步 seekplayer.seek(t)直接驱动组合 iframe 的 GSAP 时间线__timelinesGSAP.seek()同步渲染该帧并保持暂停。因此一次 seek 同时完成重绘 保持包括后台窗口也确定性地生效——这正是幻灯片永远不会自动前进的实现保证对应的单元测试packages/player/src/slideshow/SlideshowController.test.ts包括构造时进入第一张幻灯片seek 到第一个片段保持点不自动播放永不自动播放——单次 seek 同时重绘与保持同幻灯片片段导航不停止媒体换幻灯片前停止媒体next 停在第一个片段而非直接跳下一张无片段时 next 直接进入下一张最后一张上的 next 是无操作prev 回到上一张幻灯片起点。无片段幻灯片的静止帧restFrame(slide)返回slide.start (slide.end - slide.start) * 0.5——即幻灯片中点而不是slide.end那是下一场景开始的边界会让第 1 页渲染出第 2 页的内容。这保证无片段幻灯片在静止时是可见的而不是冻结在其入场前帧。媒体处理进入幻灯片时若autoplay为真调用playSceneMedia(sceneId)自动播放该场景的video仍不自动前进演讲者点击 Next 才前进离开幻灯片next/prev/goToSlide会stopSlideMedia()确保内嵌媒体在离开时停止演示者与观众之间的媒体状态play/pause/seeking/seeked/ratechange/volumechange/ended/timeupdate通过OwnedMediaRegistry经 BroadcastChannel 镜像观众端媒体以静音播放并保留Play audience media muted解锁按钮应对浏览器自动播放策略。键盘与触摸交互键盘快捷键见onKey注意isTextEntryTarget会放过输入框内的按键避免打字触发翻页按键行为→/←下一张 / 上一张即使焦点不在 deck 上也可用多实例页面除外Space/Backspace下一张 / 上一张仅在 deck 获得焦点时避免劫持页面滚动/历史P进入 presenter 模式在任何时刻都立即生效包括控制器尚未绑定前F切换全屏触摸滑动要求主导水平手势|Δx| 40且|Δx| |Δy|避免斜向滚动误触翻页。六、Studio 中的 Slideshow 面板可视化编排当活动组合包含 HyperFrames slideshow 清单时Studio 中会出现Slideshow标签页详见 docs/studio/slideshows.mdx构建主路径在Slides中勾选属于主演示的场景用箭头调整顺序逐张确认每页只表达一个完整观点在Slide Inspector中添加有助于演讲者、而非重复幻灯片的备注。Studio 将 slideshow 变更保存进项目的 manifest。备注在短暂停顿后保存其余编辑立即保存并参与项目历史。添加片段揭示把播放头移动到演示应暂停的时刻在 Slide Inspector 点击Mark——该时间即成为所选幻灯片的片段保持点。片段用于需要逐条揭示的场景不需要为每个要点都设保持点。添加可选路径打开Branches命名分支并分配其幻灯片在出现选择的那张幻灯片上选中画布中的可见按钮或对象打开Hotspot Tool选择目标分支、添加有用标签并点击Make hotspot保持一条清晰的返回主故事路径。删除分支会同时删除该分支定义与其全部指向它的热点Studio 会先请求确认源场景保留在项目中。作为演示测试运行npx hyperframes present project-directory测试上/下导航、每个片段、每个热点、每个分支与返回路径。点击Present或按P打开同步的观众视图。七、Agent 创作时的检查清单可直接用于 prompt 工程把以下清单融入你的创作 prompt可获得符合契约的 deck先做路由确认涉及 slides/deck/convert this page 歧义时确认用户要的是 HyperFrames slideshow收集观众与核心结论确认是否需要 reveals / branches / presenter notes每张幻灯片一个主张 一个可视化 简洁备注主故事在不打开任何分支时依然完整深层材料放入分支 热点并保证可返回不要在 deck 上运行hyperframes render用present演示、用snapshot出逐页静态图输出物必须包含composition application/hyperframes-slideshowjsonislandslides / fragments / hotspots / sequences / notes / autoplay。八、相关资源路由契约原文skills/hyperframes/references/routes/slideshow.md官方指南docs/guides/slideshow.mdxStudio 面板docs/studio/slideshows.mdx导航状态机packages/player/src/slideshow/SlideshowController.ts 及测试 SlideshowController.test.ts自定义元素与 presenter 模式packages/player/src/slideshow/hyperframes-slideshow.ts清单解析与校验packages/parsers/src/slideshow/parseSlideshow.ts类型定义packages/parsers/src/slideshow/slideshow.types.ts演示命令packages/cli/src/commands/present.ts【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考