插件安装: 在设置或执行 freshness 命令之前,如果该技能位于 HyperFrames 插件内部,请遵循 插件执行规则。独立安装则保留下面的更新说明。
首先,保持技能新鲜——请先与用户确认后再运行:
npx hyperframes skills update slideshow。如果所有内容都是最新的,这是一个快速无操作;否则,它将刷新此技能及其依赖的核心领域技能,然后再依赖它们。
figma 源:如果幻灯片的内容或故事板来自 figma.com 的 URL,请先运行
/figma——资产导出、品牌令牌,以及如果源是场景帧条带则进行故事板重建——然后根据其输出进行构建。不要直接通过原始 MCP 工具驱动 Figma:那会跳过 SVG 清理、.media/manifest.jsonl溯源以及品牌令牌var()绑定,因此以后的品牌变更无法传播,除非完全重新导入。
幻灯片创作合约
HyperFrames 幻灯片是一个普通的 HyperFrames 组合——场景、剪辑、GSAP 时间线——加上一个额外的成分:一个 JSON 数据岛,声明哪些场景是幻灯片以及它们如何连接。播放器的 SlideshowController 读取该数据岛,并将连续的 GSAP 时间线转化为离散、可导航的幻灯片。
先阅读 /hyperframes-core 了解基本组合合约(剪辑、轨道、data-* 属性、确定性规则)。本技能只涵盖新增内容:数据岛模式、幻灯片编写规则、片段、分支、验证和包装组件。
输出——可导航的幻灯片,而非线性的 MP4
幻灯片的输出是运行中的幻灯片:用 hyperframes present <project-dir>(或 Studio 演示模式)运行它——播放器的 SlideshowController 读取数据岛并驱动导航、片段、分支和演示者模式。请参阅下面的演示和交付。
不要用 hyperframes render 将幻灯片渲染成单个 MP4。 幻灯片是以几个顶级场景组合(每个幻灯片一个 data-composition-id)创作的, 没有 包裹它们的主根组合,因此 render 只会解析第一个组合并输出一个静默截断的 MP4(例如,一个 40 秒的幻灯片只输出 6 秒)。线性主线导出(仅限主幻灯片,排除分支序列)已推迟——在它推出之前,支持的输出是实时的 present 幻灯片和每个幻灯片的 snapshot 静态截图。如果用户今天需要一个线性 MP4,请说明此限制,而不是将 render 指向幻灯片。
意图确认
如果用户明确要求幻灯片、幻灯片放映或 HyperFrames 幻灯片,则使用本技能。当请求是通过 /hyperframes 到达时,意图层的分类拥有此确认——路由到这里意味着已经确认,所以不要再次询问;该层的运行形状问题不适用(交付物是幻灯片,不是渲染的视频)。当存在 BRIEF.md 时,它携带已确认的意图——请阅读它。
如果技能是从相关请求触发的,例如“演示文稿”、“融资路演”、“幻灯片”、“交互式幻灯片”或“转换此页面”,请在创作前暂停,并在要求确认前呈现选择。简要解释 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 数据岛——每个组合一个 script 块
在组合 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 数据岛已经存在。
模式
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 | 否 | 保留字段。 模式字段存在,但 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 <名称>将块的源代码放入幻灯片中,您可以在其中就地自定义。这在移植源页面时尤为重要:真正的块优于下面移植规则所禁止的简化近似。
移植源页面
将现有页面转换为幻灯片时,源忠实度是合约的一部分。除非用户明确要求重新设计,否则不要用简化近似替换源特定的控件。
- 尽可能紧密地保留原始页面的视觉设计、动画语言、交互行为、媒体行为和呈现功能。当幻灯片系统支持演示者模式时,请使用共享的可编辑备注行为(而非幻灯片特定的实现)包含演讲备注。
- 尽可能精确地移植源 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"。对于幻灯片特定的媒体,使用场景的时间范围;对于可能从多个聚焦幻灯片播放的用户控制的证据视频,使用整个幻灯片的时间范围。不要将媒体设置为preload="none";使用metadata或auto。 - 在验证前解析源字体令牌。如果要保留自定义源字体,请为本地/捕获的字体文件添加
@font-face规则。如果使用系统回退,请将诸如font-family: var(--f-body)之类的令牌化声明替换为具体的渲染安全堆栈,例如system-ui, sans-serif或ui-monospace, monospace;不要将var(...)保留为 font-family 值。 - 审计源中非典型的页面移动,尤其是由滚动、滚轮、触摸、哈希状态、调整大小或 requestAnimationFrame 循环驱动的行为。将具有平移/缩放“世界”层的固定视口、视差、固定面板、水平滚动条、滚动擦洗时间线、部分捕捉和缩放至元素相机视为源行为。滚动通常是源的过渡触发器,因此通过提取其进度停止点、缓动和相机/焦点状态来保留过渡,然后将该运动通过时间线位置、片段或可重用的播放器/挂钩重新托管到幻灯片导航上。仍然需要显式的导航-相机过渡挂钩来跳转到幻灯片保持点的独立包装器;计算每个幻灯片的相机变换是不够的。不要模拟字面上的页面向下滚动过渡