插件安装: 在执行设置或更新命令前,当此技能位于 HyperFrames 插件内部时,请遵循插件执行规则。独立安装则应保留下面的更新说明。
首先,请保持该技能为最新版本——在执行操作前与用户确认:
npx hyperframes skills update slideshow。当所有内容都为最新时,此命令会快速无操作;否则,它会在你依赖它们之前刷新该技能及其依赖的核心领域技能。
figma 源:如果 deck 的内容或故事板来自 figma.com URL,请先运行
/figma——进行资源导出、品牌令牌和(如果源是一系列场景帧组成的)故事板重构——然后再根据其输出来构建。不要直接通过原始的 MCP 工具来驱动 Figma:那样会跳过 SVG 清理、.media/manifest.jsonl来源追踪以及品牌令牌var()绑定,导致后续的品牌变更无法在没有完全重新导入的情况下传播。
幻灯片创作契约
一个 HyperFrames 幻灯片是一个常规的 HyperFrames 组合——场景、剪辑、GSAP 时间线——但多了一个额外成分:一个JSON 孤岛,它声明哪些场景是幻灯片以及它们如何连接。播放器的 SlideshowController 读取该孤岛,并将连续的 GSAP 时间线转换为一个离散的、可导航的 deck。
请先阅读 /hyperframes-core 以了解基础组合契约(剪辑、轨道、data-* 属性、确定性规则)。该技能仅涵盖新增内容:孤岛模式、幻灯片编写规则、片段、分支、验证以及包装组件。
输出——一个可导航的 deck,而非线性 MP4
幻灯片的输出是正在运行的 deck:使用 hyperframes present <project-dir>(或 Studio 的演示模式)来提供服务——播放器的 SlideshowController 会读取孤岛并驱动导航、片段、分支和演示者模式。请参阅下面的演示与交接。
不要对幻灯片使用 hyperframes render 来生成单个 MP4。 一个 deck 由几个顶层场景组件(每个幻灯片一个 data-composition-id)组成,并且没有包裹它们的主根组件,因此 render 只会解析第一个组件,并输出一个静默截断的 MP4(例如,一个 40 秒的 deck 只渲染 6 秒)。线性主线导出(仅主幻灯片,排除分支序列)已被推迟——在该功能发布之前,支持的输出是实时的 present deck 和每个幻灯片的 snapshot 静态图像。如果用户今天需要一个线性 MP4,请明确显示此限制,而不是将 render 指向该 deck。
意图确认
如果用户明确要求一个幻灯片、slideshow 或 HyperFrames slideshow,则继续执行此技能。当请求通过 /hyperframes 到达时,意图层的分流负责此确认——路由到这里意味着已经确认,因此无需再次询问;该层的运行形状问题不适用(交付物是 deck,而非渲染的视频)。BRIEF.md 文件(如果存在)包含了已确认的意图——请阅读它。
如果该技能是从一个相邻请求触发的,例如“演示文稿”、“推介 deck”、“deck”、“交互式 deck”或“转换此页面”,请在创作前暂停,并在请求确认前为用户呈现选择。简要解释什么是 HyperFrames 幻灯片:一个可运行的 deck,具有独立幻灯片、内置导航和演示者模式、可编辑的演讲者备注、共享媒体处理以及交接前的验证。对于源页面转换,还要提及目标是保留原始页面的视觉设计、交互、动效和媒体行为,同时将页面移动转化为幻灯片之间的过渡。
然后提出一个简短的确认问题:
您希望将其作为 HyperFrames 幻灯片吗?
如果环境提供了是/否选择界面,则使用它;否则以纯文本形式提问。
在用户表示“是”之前,不要实现幻灯片。如果他们回答“否”,则停止使用此技能——读取 /hyperframes 并让意图层重新路由。此确认是一个路由决策,而非偏好限制——根据 ../hyperframes/references/brief-contract.md § 1,它在自主模式(“给我惊喜”不会跳过它)下仍然有效:构建错误的交付物类型是质量失败,而非创意决定。
两个组成部分
1. 场景——以常规方式声明
每个幻灯片都由一个场景支持。使用 data-composition-id、data-start、data-duration 和 data-label 来声明场景:
<div
data-composition-id="problem"
data-start="0"
data-duration="8"
data-label="The problem"
data-width="1920"
data-height="1080"
>
<!-- 剪辑写在这里 -->
</div>
分支幻灯片(仅可通过热点访问,从主线路中排除)的声明方式完全相同——它们只出现在孤岛中的 slideSequences 条目中,而不是主 slides 数组中。
2. JSON 孤岛——每个组合一个脚本块
在组合 HTML 中精确添加一个 <script type="application/hyperframes-slideshow+json"> 块。它包含所有幻灯片元数据:
<script type="application/hyperframes-slideshow+json">
{
"slides": [...],
"slideSequences": [...]
}
</script>
该孤岛是幻灯片顺序、备注、片段保持点、热点和分支序列的唯一来源。将其放在 <body> 的顶部附近,场景 divs 之前,以便于查找。
不要将幻灯片清单隐藏在备用的 <script type="application/json"> 块以及运行时创建孤岛的代码后面。present 命令会静态读取组合 HTML,并期望真实的 application/hyperframes-slideshow+json 孤岛已经存在。
模式
SlideshowManifest(顶层孤岛对象)
{
"slides": [
/* SlideRef[] — 主线路,按顺序排列 */
],
"slideSequences": [
/* SlideSequence[] — 离线分支序列 */
]
}
SlideRef
{
"sceneId": "problem",
"notes": "Lead with the pain, not the company.",
"fragments": [3.5, 5.2, 7.0],
"hotspots": [
/* SlideHotspot[] */
],
"ttsScript": null,
"ttsAudioUrl": null,
"ttsDurationMs": null
}
| 字段 | 是否必需 | 备注 |
|---|---|---|
sceneId | 是 | 必须与场景的 data-composition-id 完全匹配(或提供显式的 startTime/endTime)。lint 规则通过 data-composition-id 解析场景。 |
notes | 否 | 仅演示者可见的文本。永远不会显示给观众。 |
fragments | 否 | 幻灯片 [start, end] 范围内的时间点(秒)数组——请参阅下面的“片段”。 |
hotspots | 否 | 触发分支的交互式覆盖层——请参阅下面的“分支”。 |
startTime | 否 | 可选。覆盖匹配场景的时间界限;默认为场景的开始/结束。 |
endTime | 否 | 可选。覆盖匹配场景的时间界限;默认为场景的开始/结束。 |
ttsScript, ttsAudioUrl, ttsDurationMs | 否 | 预留。 模式字段已存在但 TTS 播放尚未接入。除非你正在为未来构建预填充数据,否则请省略。 |
SlideHotspot
{
"id": "h1",
"label": "How did we calculate this?",
"target": "market-deep-dive",
"region": { "x": 60, "y": 10, "w": 35, "h": 20 }
}
| 字段 | 是否必需 | 备注 |
|---|---|---|
id | 是 | 在幻灯片内唯一。 |
label | 是 | 显示给观众的提示文本/按钮文字。 |
target | 是 | 必须与 slideSequences 中的 SlideSequence.id 匹配。 |
region | 否 | 幻灯片百分比边界框:{x, y, w, h},范围为 0–100。省略则将该热点渲染为全屏带标签按钮。 |
SlideSequence
{
"id": "market-deep-dive",
"label": "Market sizing methodology",
"slides": [{ "sceneId": "mkt-1" }, { "sceneId": "mkt-2" }]
}
序列中的 slides 使用与主线路相同的 SlideRef 形状。允许使用片段和嵌套热点。
幻灯片编写规则
这些是硬性约束,而非建议。违反规则的幻灯片在审核者看到时会被直接替换。
- 标题是完整的陈述句,而非标签。 写“SMBs spend 14 hours/week on manual scheduling”而不是“Scheduling problem”。这句话在忽略视觉效果时也应能独立存在。
- 每张幻灯片一个理念 + 一个视觉元素。 如果你忍不住想添加第二个项目符号簇或第二个图表,请拆分幻灯片。
- 开门见山。 最强的观点放在最前面——无论是在幻灯片上还是在 deck 顺序中。投资者从左到右、从上到下阅读,并且他们会停下来。
- 仅限自下而上的市场规模计算。 切勿在未展示计算过程的情况下写“$50B TAM”。从单位经济学开始构建:账户数 × ACV,或交易数 × 提成率。
- 字体最低 30pt 等效。 在 1920×1080 分辨率下,标题为 72–96px;正文为 48px。任何观众必须阅读的文本都不应低于 40px。
- 在手动构建任何命名的视觉元素之前,请搜索实时目录。 对于幻灯片需要的每一个外观、效果、图表、处理或过渡——“CRT scanlines”、“glitch”、“bar chart race”、“shimmer sweep”、“terminal window”——在编写幻灯片的剪辑之前,请运行
npx hyperframes catalog --query "<the visual, in plain English>" --json并阅读顶部结果。此搜索无需安装任何内容:无需项目、无需先前的add、无需账户。它会从任何目录对整个托管注册表(约 400 个块和组件)进行排名。npx hyperframes add <name>会将块的源代码放入 deck 中,你可以在其中就地自定义。当移植源页面时,这一点尤为重要:一个真实的块优于以下移植规则所禁止的简化近似。
移植源页面
当将现有页面转换为幻灯片时,源保真度是契约的一部分。不要用简化的近似替换源特有的小部件,除非用户明确要求重新设计。
- 尽可能接近地保留原始页面的视觉设计、动效语言、交互行为、媒体行为和展示功能。当幻灯片系统支持演示者模式时,请使用共享的可编辑备注行为而不是某个 deck 特定的实现来包含演讲者备注。
- 尽可能精确地从源 DOM/CSS/JS 移植机械视觉效果:自定义播放器、canvas 可视化工具、时间线、播放头、谱线、展开的圆圈、悬停状态以及其他交互式细节应能在转换后存活。
- 将原生
<video>/<audio>元素视为任何自定义媒体框架、canvas 可视化工具、波形、节拍网格或播放头的唯一真实来源。连接源的媒体事件(play、pause、timeupdate、seeking、seeked、ended、ratechange、volumechange)并从media.currentTime派生视觉状态;不要运行一个可能偏离实际播放的独立定时器。 - 每个带有
src的复制的<video>或<audio>在 lint 之前都必须具有 HyperFrames 时间属性:data-start和data-duration,以及当应保留可听的本地音频时的data-has-audio="true"。对于特定于幻灯片的媒体,使用场景的时间范围;对于可能从多个聚焦幻灯片播放的用户控制的证据视频,使用 deck 范围的范围。不要将preload="none"留在媒体上;使用metadata或auto。 - 在验证之前解析源字体令牌。如果要保留自定义源字体,请为本地/捕获的字体文件添加
@font-face规则。如果使用系统后备字体,请将令牌化的声明(如font-family: var(--f-body))替换为具体的、渲染安全的字体栈,如system-ui, sans-serif或ui-monospace, monospace;不要将var(...)作为字体系列值保留。 - 审核源中非典型的页面移动,尤其是由滚动、滚轮、触摸、哈希状态、调整大小或 requestAnimationFrame 循环驱动的行为。将带有平移/缩放的“世界”层的固定视口、视差、固定面板、水平滚动器、滚动擦洗时间线、区域对齐和缩放至元素的摄像机视为源行为。滚动通常是源的过渡触发器,因此通过提取其进度停止点、缓动和摄像机/焦点状态来保留过渡,然后将该动效通过时间线位置、片段或可重用的播放器/挂钩移动到幻灯片导航上。跳转到幻灯片保持点的独立包装器仍然需要一个显式的导航-摄像机过渡挂钩;仅计算每张幻灯片的摄像机变换是不够的。不要模拟逐字滚动到底的过渡。