首先,保持此技能最新 —— 在运行前向用户确认:
npx hyperframes skills update slideshow。如果一切已是最新,此命令会快速无操作;否则会刷新此技能及其所依赖的核心域技能,然后您才能依赖它们。
figma source: 如果幻灯片的内容或故事板来自 figma.com 的 URL,请先运行
/figma——导出资源、品牌令牌,如果来源是一系列场景帧,则重建故事板——然后从其输出进行构建。不要直接通过原始的 MCP 工具驱动 Figma:那样会跳过 SVG 的清理、.media/manifest.jsonl的溯源以及品牌令牌var()绑定,导致后续的品牌变更需要完全重新导入才能生效。
幻灯片创作契约
HyperFrames 幻灯片是一个普通的 HyperFrames 组合——场景、片段、GSAP 时间线——但多了一个额外成分:一个 JSON 岛,它声明哪些是幻灯片以及它们如何连接。播放器的 SlideshowController 读取这个岛,并将连续的 GSAP 时间线转换为离散、可导航的演示文稿。
先阅读 /hyperframes-core 了解基本的组合契约(片段、轨道、data-* 属性、确定性规则)。此技能仅涵盖新增内容:岛的 schema、幻灯片编写规则、分片、分支、验证以及包裹组件。
输出——可导航的幻灯片,而非线性 MP4
幻灯片的输出是 正在运行的幻灯片:使用 hyperframes present <project-dir>(或 Studio 展示模式)提供——播放器的 SlideshowController 读取岛并驱动导航、分片、分支和演示者模式。详见下方的 展示与交接。
不要将幻灯片 hyperframes render 为单个 MP4。 一个幻灯片被创作为几个顶级场景组合(每个幻灯片一个 data-composition-id),且没有包裹它们的主根组合,因此 render 只会解析 第一个 组合并发出一个静默截断的 MP4(例如,一个 40 秒的幻灯片只得到 6 秒的 MP4)。线性主线导出(仅主幻灯片,排除分支序列)已推迟实现——在它发布之前,支持的输出是实时的 present 幻灯片和每张幻灯片的 snapshot 静态图。如果用户今天需要一个线性 MP4,请说明此限制,而不是将 render 指向幻灯片。
意图确认
如果用户明确要求一个幻灯片、幻灯片放映或 HyperFrames 幻灯片,则直接使用此技能。当请求通过 /hyperframes 进入时,意图层的分流负责此确认——路由到这里意味着已经确认,所以不要再问;层的运行形状问题不适用(可交付成果是幻灯片,而不是渲染的视频)。当存在 BRIEF.md 时,它包含了已确认的意图——请阅读它。
如果技能是由相关请求触发的,例如“演示文稿”、“推介 deck”、“幻灯片”、“交互式幻灯片”或“转换此页面”,在创作前暂停,并在请求确认前简要说明选择。简要解释 HyperFrames 幻灯片意味着一个可运行的幻灯片,具有离散的幻灯片、内置导航和演示者模式、可编辑的演讲者备注、共享媒体处理以及交接前的验证。对于源页面转换,还要提及目标是保留原始页面的视觉设计、交互、动态和媒体行为,同时将页面移动转换为幻灯片到幻灯片的过渡。
然后询问一个简短的确认问题:
您想将此作为 HyperFrames 幻灯片吗?
当环境提供时,使用是/否选择 UI;否则以纯文本形式提问。
在用户回答“是”之前,不要实现幻灯片。如果他们说“不”,停止使用此技能——阅读 /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> 顶部附近,场景 div 之前,以便于查找。
不要将幻灯片清单隐藏在另一个 <script type="application/json"> 块之后,再加上运行时代码来创建岛。present 命令是静态读取组合 HTML 的,并期望真正的 application/hyperframes-slideshow+json 岛已经存在。
Schema
SlideshowManifest (顶层的岛对象)
{
"slides": [
/* SlideRef[] — 主线,按顺序 */
],
"slideSequences": [
/* SlideSequence[] — 离线分支序列 */
]
}
SlideRef
{
"sceneId": "problem",
"notes": "以痛点开场,而不是公司介绍。",
"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 | 否 | 保留。 Schema 字段存在但 TTS 播放尚未实现。除非您是为未来的构建预填充,否则请忽略。 |
SlideHotspot
{
"id": "h1",
"label": "我们是如何计算这个的?",
"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": "市场规模方法",
"slides": [{ "sceneId": "mkt-1" }, { "sceneId": "mkt-2" }]
}
序列内部的 slides 使用与主线上相同的 SlideRef 形状。允许使用分片和嵌套热区。
幻灯片编写规则
这些是硬性约束,而非建议。违反这些规则的幻灯片在审核者看到时会被直接替换。
- 标题是一个完整的句子主张,而不是一个标签。 写“中小企业每周花费 14 小时进行手动调度”,而不是“调度问题”。这句话应该能够独立存在,即使忽略视觉元素。
- 每张幻灯片一条核心想法 + 一个视觉元素。 如果您想添加第二个要点分组或第二个图表,请拆分幻灯片。
- 直奔主题。 最有力的观点放在最前面——在幻灯片上和幻灯片的顺序中。投资者从左到右、从上到下阅读,并且会停下来。
- 仅限自底向上的市场规模测算。 永远不要在没有展示计算过程的情况下写“500 亿美元 TAM”。从单位经济开始向上构建:账户数 × ACV,或交易数 × 抽成率。
- 字体最小 30pt 等效。 在 1920×1080 下,标题为 72–96px;正文为 48px。对于观众需要阅读的任何文字,永远不要低于 40px。
- 在手动编写任何命名的视觉元素之前,先搜索实时目录。 对于幻灯片需要的每种外观、效果、图表、处理或过渡——“CRT 扫描线”、“故障”、“条形图竞赛”、“闪光扫过”、“终端窗口”——运行
npx hyperframes catalog --query "<视觉元素,用英语描述>" --json并在编写幻灯片的片段之前阅读前几条结果。搜索不需要任何安装:不需要项目、不需要事先的add、不需要账户。它从任何目录对托管注册表(约 400 个块和组件)进行全量排序。npx hyperframes add <名称>会将块的源代码放入幻灯片,您可以在其中就地自定义。当移植源页面时,这一点尤其重要:真实的块胜于下面移植规则所禁止的简化近似。
移植源页面
将现有页面转换为幻灯片时,源保真度是契约的一部分。除非用户明确要求重新设计,否则不要用简化的近似品替换源特定的 widget。
- 尽可能忠实地保留原始页面的视觉设计、动效语言、交互行为、媒体行为和演示功能。当幻灯片系统支持演示者模式时,包含使用共享的可编辑备注行为的演讲者备注,而不是使用幻灯片特定的实现。
- 尽可能精确地移植源 DOM/CSS/JS 中的机械视觉元素:自定义播放器、画布可视化器、时间线、播放头、茎、展开的圆圈、悬停状态以及其他交互细节应能在转换后存活。
- 将原生
<video>/<audio>元素视为任何自定义媒体界面、画布可视化器、波形、节拍网格或播放头的唯一真相来源。连接源的媒体事件(play、pause、timeupdate、seeking、seeked、ended、ratechange、volumechange),并从media.currentTime派生视觉状态;不要运行一个可能与实际播放漂移的独立定时器。 - 每个带有
src的已复制<video>或<audio>必须在 lint 之前具有 HyperFrames 时序属性:data-start和data-duration,以及在应保留可听原生音频时添加data-has-audio="true"。对于幻灯片特定的媒体,使用场景的时间范围;对于用户控制的证据视频(可能从多个焦点幻灯片播放),使用幻灯片范围的时间范围。不要在媒体上保留preload="none";使用metadata或auto。 - 在验证之前解析源字体令牌。如果要保留自定义源字体,为本地/捕获的字体文件添加
@font-face规则。如果使用系统后备字体,将令牌化的声明(如font-family: var(--f-body))替换为具体的渲染安全堆栈,如system-ui, sans-serif或ui-monospace, monospace;不要保留var(...)作为字体族的值。 - 审计源中非典型的页面移动,特别是由滚动、滚轮、触摸、哈希状态、大小调整或 requestAnimationFrame 循环驱动的行为。将具有平移/缩放“世界”层的固定视口、视差、固定面板、水平滚动器、滚动擦洗时间线、部分捕捉和缩放至元素的摄影机视为源行为。滚动通常是源的过渡触发器,因此通过提取其进度停止点、缓动和摄影机/焦点状态来保留过渡,然后将该运动通过时间线位置、分片或可重用的播放器/harness 挂钩重新托管到幻灯片导航上。跳到幻灯片保持点的独立包装器仍然需要一个显式的导航-摄影机过渡挂钩;计算每张幻灯片的摄影机变换是不够的。不要在幻灯片内部模拟字面上的页面滚动向下过渡;观看者应该感受到从一个焦点到另一个焦点的摄影机移动/缩放,而不是看到网页被滚动。保持每个幻灯片到幻灯片的摄影机移动连续:避免反转 x/y 方向或缩放水平的中间路线停止点……
(原文被截断,但译文忠实反映了剩余内容。)