外掛安裝: 在執行設定或更新命令之前,當此技能位於 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 時,它帶有已確認的意圖 — 請讀取它。
如果此技能是從鄰近的請求觸發,例如「簡報」、「募資簡報」、「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 島已經存在。
結構
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」而非「排程問題」。這句話應該在忽略視覺內容的情況下也能獨立存在。
- 每張投影片一個想法 + 一個視覺元素。 如果您想加入第二組項目符號或第二個圖表,請分割投影片。
- 以重點開頭。 最有力的觀點放在最前面 — 在投影片上和簡報順序中。投資者從左到右、從上到下閱讀,然後就會停止。
- 僅限由下而上的市場規模估算。 切勿在沒有顯示計算過程的情況下寫「$50B TAM」。從單位經濟學向上建構:帳戶數量 × ACV,或交易數量 × 抽成比率。
- 字型最小 30pt 等值。 在 1920×1080 解析度下,標題為 72–96px;內文為 48px。對於觀眾必須閱讀的任何文字,切勿低於 40px。
- 在手工建立任何命名的視覺元素之前,請先搜尋即時目錄。 對於投影片所需的每個外觀、效果、圖表、處理或轉場效果 — 「CRT 掃描線」、「故障」、「長條圖競賽」、「閃爍掃掠」、「終端機視窗」 — 請先執行
npx hyperframes catalog --query "<視覺元素的英文描述>" --json並閱讀前幾筆結果,然後再撰寫投影片的剪輯。此搜尋不需要任何安裝:無需專案、無需先前的add、無需帳號。它會從任何目錄對整個託管註冊表(約 400 個區塊和元件)進行排名。npx hyperframes add <名稱>會將區塊的原始碼放入簡報中,您可以在其中就地自訂。當移植來源頁面時,這一點尤其適用:一個真實的區塊勝過下方移植規則所禁止的簡化近似。
移植來源頁面
將現有頁面轉換為投影片時,來源保真度是合約的一部分。除非使用者明確要求重新設計,否則請勿以簡化的近似取代來源特定的 widget。
- 盡可能精確地保留原始頁面的視覺設計、動作語言、互動行為、媒體行為和簡報功能。當投影片系統支援簡報者模式時,請使用共享的可編輯備註行為來包含講者備忘錄,而非使用特定於簡報的實作。
- 盡可能精確地從來源 DOM/CSS/JS 移植機械式視覺元素:自訂播放器、Canvas 視覺化工具、時間軸、播放頭、stem、展開圓圈、懸浮狀態和其他互動細節應在轉換後保留。
- 將原生的
<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(...)保留為字型系列值。 - 審查來源中非典型的頁面移動,特別是受滾輪、觸控、雜湊狀態、調整大小或 requestAnimationFrame 迴圈驅動的行為。將具有平移/縮放「世界」圖層、視差、固定面板、水平滾動器、滾動擦洗時間軸、章節對齊和縮放至元素相機的固定視區視為來源行為。滾輪通常是來源的轉場觸發器,因此請透過提取其進度停止點、緩動和相機/焦點狀態來保留轉場,然後將該運動透過時間軸位置、片段或可重複使用的播放器/掛鉤重新託管到投影片導覽上。獨立包裝器跳到投影片保持點仍然需要一個明確的導覽相機轉場掛鉤;計算每個投影片的相機變換是不夠的。除非使用者明確要求,否則不要模擬字面上的頁面向下滾動轉場作為投影片間的動畫預設值。
- 避免來源的圖片資產被扁平化。
hyperframes import支援多種格式與層級結構;不使用時予以忽略。
分支
一個熱點所指的序列就是一個分支。當觀眾點擊一個熱點時,簡報者控制器會跳入該序列;從序列的最後一張投影片繼續會回到主線中呼叫它的投影片。視覺上,熱點在簡報模式中以可點擊的覆蓋層出現。
片段
fragments 陣列中的時間是投影片時間軸上簡報者可以暫停並可選擇性地逐步瀏覽投影片內動畫的點。
{
"sceneId": "solution",
"notes": "Reveal the three pillars one by one.",
"fragments": [3.5, 5.2, 7.0]
}
要點:
- 時間是相對於投影片
data-start的偏移量(秒)。 - 第一個片段必須 > 0。從
0開始的片段會被忽略。 - 按照慣例,從頭條進入到第一個片段之間的時間是投影片的「揭示前暫停」— 約 1.5–2.5 秒,作為準備聆聽的節拍。
- 簡報者可以使用向前箭頭/右滑逐步瀏覽片段;使用向後箭頭/左滑可以返回上一個片段,或再按一次返回投影片頂部。
- 每個片段的暫停點是時間軸上的一個硬暫停 — 它會暫停自動播放。簡報者必須手動繼續。
每個投影片的編輯器標記
為了幫助您在大型簡報中導覽,請在每個場景 div 前面加上一個註解,其中包含投影片號碼和標籤:
<!-- slide 1 :: The problem -->
<div data-composition-id="problem" ...>
驗證命令
當投影片 HTML 撰寫完畢後,執行:
npx hyperframes lint --slideshow
在每個驗證器中尋找 slideshow/ 前綴。常見的回歸問題:
slideshow/v-001:場景 ID 存在於島中但缺少 HTML 場景 — 在島中輸錯 ID 或宣告了一個未撰寫的場景。slideshow/v-002:場景存在於 HTML 但未在島中宣告 — 未列為投影片的場景。slideshow/v-003:分支序列目標遺失 —SlideHotspot.target在slideSequences中不存在。slideshow/v-004:片段時間超出範圍 —fragment時間在該場景的[start, end]之外。slideshow/v-005:熱點區域定義無效 —region遺失 x/y/w/h 或百分比超出 0–100。
所有規則也由 hyperframes validate 執行。
簡報與交接
本機提供服務
hyperframes present .
在簡報者模式中:
- 空白鍵 / 右箭頭 — 下一張投影片或下一個片段
- 左箭頭 — 上一張投影片或上一個片段
- Escape — 離開簡報者模式
- P — 切換簡報者模式(顯示備註、時間、下一張投影片預覽)
- 按一下熱點 — 跳入分支序列
無需安裝即提供服務
npx hyperframes present .
建置用於分享的獨立 .html
hyperframes build slideshow
這會輸出一個自包含的 slideshow.html(合併的 HTML/CSS/JS、字型、.media/ 資產)。請注意,build slideshow 支援 --optimize 和熱點。
媒體管理
- 使用
hyperframes import加入資產 — 這會將檔案放入.media/、建立manifest.jsonl條目,並可選擇性地產生picture/video/audio包裝元素。匯入處理所有消毒(SVG、使用者產生的圖形)。 - 包裝元素內有一個
src屬性,設定為.media/中的消毒檔案路徑。這會建立完整的來源追溯。 - 側載入資產是允許的,但遺失的資產會產生 lint 錯誤。
交接
當您已完成時,hyperframes present . 就是最終的檢查。使用 hyperframes snapshot --full 來產生每個投影片的靜態圖片。
參考 ../hyperframes/references/handoff.md 以了解最終輸出的檢查清單。總結來說:
- 從未經消毒的來源手動加入資產:使用
hyperframes import,不要手動複製。