首先,保持此技能最新——在使用前先執行以下指令確認:
npx hyperframes skills update slideshow。當一切為最新狀態時,此指令為無操作;否則會更新此技能及其依賴的核心領域技能,然後再依賴它們。
figma 來源:如果投影片的內容或故事板來自 figma.com 網址,請先執行
/figma——匯出素材、品牌權杖,以及如果來源是一系列場景影格,則重建故事板——然後再根據其輸出進行建置。不要直接透過原始 MCP 工具驅動 Figma:這樣會跳過 SVG 清理、.media/manifest.jsonl出處,以及品牌權杖的var()繫結,導致日後品牌變更無法傳播,需要完整重新匯入。
投影片創作合約
HyperFrames 投影片是一種標準的 HyperFrames 組合——場景、片段、GSAP 時間軸——外加一個額外成分:一個JSON island,宣告哪些場景是投影片以及它們如何連接。播放器的 SlideshowController 讀取此 island,並將連續的 GSAP 時間軸轉換為離散、可導覽的投影片。
請先閱讀 /hyperframes-core,了解基礎組合合約(片段、軌道、data-* 屬性、確定性規則)。此技能僅涵蓋新增的部分:island 架構、投影片撰寫規則、片段、分支、驗證,以及包裝元件。
輸出——可導覽的投影片,非線性 MP4
投影片的輸出是執行的投影片:使用 hyperframes present <project-dir>(或 Studio 簡報模式)來提供服務——播放器的 SlideshowController 讀取 island 並驅動導覽、片段、分支和簡報者模式。請參閱下方的簡報與交接。
不要對投影片執行 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>
分支投影片(僅可透過熱點到達,排除在主線之外)以完全相同的方式宣告——它們只會出現在 island 的 slideSequences 條目中,而不是主 slides 陣列中。
2. JSON island——每個組合一個 script 區塊
在組合 HTML 中新增一個 <script type="application/hyperframes-slideshow+json"> 區塊。它包含所有投影片元資料:
<script type="application/hyperframes-slideshow+json">
{
"slides": [...],
"slideSequences": [...]
}
</script>
Island 是投影片順序、備註、片段保持點、熱點和分支序列的單一事實來源。將其放在 <body> 頂部附近,位於場景 div 之前,以方便查找。
不要將投影片清單隱藏在替代的 <script type="application/json"> 區塊加上在執行時期建立 island 的程式碼後面。present 指令會靜態讀取組合 HTML,並期望即時存在真正的 application/hyperframes-slideshow+json island。
架構
SlideshowManifest(頂層 island 物件)
{
"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」。句子應能在忽略視覺效果的情況下獨立存在。
- 每個投影片一個想法 + 一個視覺效果。 如果您想加入第二個要點群組或第二個圖表,請分割投影片。
- 先說結論。 最有力的觀點放在第一位——在投影片上和投影片順序中皆然。投資者從左到右、從上到下閱讀,而且他們會停止。
- 僅限由下往上估算市場規模。 永遠不要寫「$50B TAM」而不展示計算過程。從單位經濟學向上建構:帳戶數 × ACV,或交易數 × 抽成率。
- 字型最小相當於 30pt。 在 1920×1080 解析度下,標題為 72–96px;內文為 48px。對於觀眾必須閱讀的任何文字,切勿低於 40px。
- 在手工建置任何具名視覺效果之前,先搜尋即時目錄。 對於投影片所需的每個外觀、效果、圖表、處理方式或轉場——「CRT scanlines」、「glitch」、「bar chart race」、「shimmer sweep」、「terminal window」——在撰寫投影片的片段之前,請執行
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(...)保留為字型系列值。 - 審計來源中非典型的頁面移動,特別是受捲動、滾輪、觸控、雜湊狀態、調整大小或 requestAnimationFrame 迴圈驅動的行為。將具有平移/縮放的「世界」圖層、視差、固定面板、水平捲動器、捲動清除時間軸、章節對齊和縮放至元素相機的固定視區視為來源行為。捲動通常是來源的轉場觸發器,因此請透過擷取其進度停止點、緩動和相機/焦點狀態來保留轉場,然後透過時間軸位置、片段或可重複使用的播放器/掛鉤,將該動畫重新託管在投影片導覽上。跳轉到投影片保持點的獨立包裝器仍然需要一個明確的導覽-相機轉場掛鉤;計算每個投影片的相機變換是不夠的。不要在投影片內部模擬文字頁面向下捲動的轉場;觀眾應該感受到從一個焦點到另一個焦點的相機移動/變焦,而不是看到一個網頁正在被捲動。保持每次投影片到投影片的相機移動連續:避免中間路徑點反轉 x/y 方向或縮小…
…[為翻譯而截斷]