安裝 HyperFrames
一次性重現將 HyperFrames 作為影片提供者的整合,遵循 CLAUDE.md 中定義的三步驟新增提供者合約。這是一份自包含的檢查清單,列出所有必須存在的成品;會驗證每個成品,並僅建立缺少的部分。
請執行此技能,而不是從頭開始重新推導整合。它是此儲存庫中「HyperFrames 已啟用」的權威記錄。
何時呼叫
- 全新的行銷引擎複製品尚未包含 HyperFrames 支援時。
- 因 rebase 或合併遺漏了下列任何成品(
router:check報錯、影片路由因排版任務回退至higgsfield,或.skills/hyperframes*/目錄遺失)時。 - 新客戶需要程式化短片 / 動態排版 / 資料視覺化輪播,且路由矩陣需要為這三種任務類型建立連線時。
- 在培訓新操作員時,需要一個可透過單一指令執行的操作手冊,而不是閱讀三個提交記錄時。
輸入
repo_root:字串。行銷引擎複製品的絕對路徑。預設為process.cwd()。branch:字串,可選。要提交的分支名稱。預設為claude/install-hyperframes。若分支不存在則建立;絕不在main分支上提交。dry_run:布林值,可選。若為 true,則僅列印計劃的變更並退出,不實際寫入任何內容。
流程
依序執行每個步驟。每個步驟都具備冪等性——在已整合的儲存庫上重新執行時,該步驟不會產生任何效果。
步驟 1 — 前置檢查
- 確認
repo_root包含CLAUDE.md,且其中含有## How to Add a New Provider這一行。若缺少則拒絕執行——這不是行銷引擎儲存庫。 - 確認
lib/providers/video.ts、lib/providers/matrix.ts、lib/providers/types.ts和lib/providers/__mocks__/video.ts都存在。若缺少任何一個則拒絕執行。 - 確認目前分支不是
main。如果在main上,則先建立並切換到branch。
步驟 2 — 新增三個執行時期技能
建立這三個目錄及其中的 SKILL.md 檔案。每個檔案都已存在於樹狀結構中的標準版本中——請直接從下方的參考成品集一節複製。如果某個檔案已存在且其 frontmatter 中的 name 相符,則跳過該檔案。
.skills/hyperframes/SKILL.md— 合成編寫規則(佈局優先於動畫、時間軸暫停並註冊在window.__timelines上、不使用Math.random()或時間相關邏輯、變數透過data-composition-variables宣告)。.skills/hyperframes-cli/SKILL.md—npx hyperframeslint → inspect → render 開發循環。一律使用--strict --strict-variables進行渲染。.skills/hyperframes-prompt-builder/SKILL.md— 專用提示建構器,當路由矩陣解析為hyperframes時,由video-prompt-builder呼叫;從clients/<slug>/design.md載入品牌代碼,根據task_kind選擇範本,傳回合成規格與渲染參數。
步驟 3 — 更新調度器技能
在 .skills/video-prompt-builder/SKILL.md 中:
- 在開頭段落和相關技能區域中,將
hyperframes-prompt-builder加入專用技能清單。 - 將
task_kind輸入列舉擴充為包含motion_typography、data_viz_reel、programmatic_short。 - 在驗證環境變數的流程步驟中,將
HYPERFRAMES_ACTIVE加入清單。 - 在提供者→專用技能的對應表中,加入
Hyperframes -> hyperframes-prompt-builder這一行。 - 新增一個範例:一個路由到 HyperFrames、
task_kind為programmatic_short的每週 KPI 輪播。
跳過任何目標字串已存在的子步驟。
步驟 4 — 擴充提供者層
在 lib/providers/types.ts 中,將三個成員加入 VideoTask 聯合型別:
| "motion-typography"
| "data-viz-reel"
| "programmatic-short"
在 lib/providers/matrix.ts 中:
- 在
EMBEDDED_DEFAULTS.video中加入三行:motion-typography、data-viz-reel、programmatic-short—— 每個預設值均為hyperframes。 - 在
TASK_LABEL_MAP中加入標籤別名:"motion typography"、"kinetic typography"、"data viz reel"、"data-viz reel"、"programmatic short"、"parametrized short"。
在 lib/providers/video.ts 中:
- 新增一個
HyperframesVideoProvider類別,繼承RealVideoBase,並以process.env.HYPERFRAMES_ACTIVE === "true"作為守衛條件,在realGenerate中拋出一個「需要呼叫端環境中的本機 CLI 渲染;此為暫存」的錯誤(比照現有的 higgsfield/topview 暫存模式)。 - 在
REAL_VIDEO_REGISTRY中註冊hyperframes: () => new HyperframesVideoProvider()。
在 lib/providers/__mocks__/video.ts 中:
- 新增一個
MockHyperframesVideoProvider類別,繼承BaseMockVideo,name設定為"hyperframes"。 - 在
MOCK_VIDEO_REGISTRY中註冊hyperframes: () => new MockHyperframesVideoProvider()。
步驟 5 — 更新路由矩陣檔案
在 .specs/architecture/PROVIDERS.md 中,將三行附加到影片路由表格:
| 動態排版 (Motion typography) | hyperframes | HTML/GSAP 動態文字,忠於品牌,具確定性 |
| 資料視覺化輪播 (Data viz reel) | hyperframes | 宣告式變數 → 可重新渲染的圖表(紐約時報風格) |
| 程式化短片 (Programmatic short) | hyperframes | 參數化的 HTML 合成;位元組完全相同的重新渲染 |
步驟 6 — 更新 .env.example
在 WAVESPEED_API_KEY= 之後附加:
# HyperFrames 是一個本機 HTML→MP4 渲染器;不需要 API 金鑰。
# 當 `npx hyperframes doctor` 在本機通過後,將 HYPERFRAMES_ACTIVE 設定為 true
# (需要 Node >= 22 且 FFmpeg 在 PATH 中)。詳見 https://github.com/wesleysimplicio/hyperframes
HYPERFRAMES_ACTIVE=false
步驟 7 — 更新 CLAUDE.md
- 在技術棧表格中,將
Video列的提供者儲存格變更為包含hyperframes (local HTML→MP4)。 - 在可用技能中,在
wavespeed-batch之後插入三行:hyperframes— 以 HTML 為真相來源的動態合成編寫。hyperframes-cli— 執行npx hyperframeslint/inspect/preview/render。hyperframes-prompt-builder— 當路由矩陣解析為hyperframes時,由video-prompt-builder選用。
步驟 8 — 驗證
- 透過下列測試解析
.specs/architecture/PROVIDERS.md,並斷言motion-typography、data-viz-reel、programmatic-short都解析為hyperframes。 - 執行
npm run typecheck—— 接受任何與變更無關的既有失敗(例如缺少@types/node);若有新的 TypeScript 錯誤涉及提供者層,則判定失敗。 - 如果儲存庫中存在
.env,則執行npm run router:check;否則跳過(該指令碼需要.env,且與整合形狀無關)。 - 確認
git status僅顯示預期的檔案。
node --input-type=module -e "
import { readFileSync } from 'node:fs';
const text = readFileSync('.specs/architecture/PROVIDERS.md', 'utf8');
const expected = ['motion-typography', 'data-viz-reel', 'programmatic-short'];
for (const key of expected) {
if (!text.toLowerCase().includes(key.replace(/-/g, ' '))) {
console.error('MISSING:', key); process.exit(1);
}
}
console.log('PROVIDERS.md OK');
"
步驟 9 — 提交並推送
- 僅暫存此技能觸及的檔案。絕對不要使用
git add -A。 - 使用標準提交訊息進行提交:
並附上描述三步驟合約執行的內文(請參考已合併的參考提交記錄中的措辭)。feat(skills): 將 HyperFrames 作為影片提供者啟用 - 推送至
origin <branch>。若該分支尚無草稿拉取請求,則建立一個。
輸出
branch:字串。保存提交的分支名稱。pr_url:字串。草稿拉取請求的 URL(如果已建立或已存在)。files_written:陣列,包含實際建立或修改的相對路徑。files_skipped_idempotent:陣列,包含因已正確而跳過的相對路徑。verification:{ providers_md_pass: boolean, typecheck_pass: boolean, router_check: "pass" | "skipped" | "fail" }。
不可協商的規則
- 冪等性。 在已整合的儲存庫上重新執行時,不會觸及任何檔案。
- 絕不在
main上提交。 先建立功能分支;引擎的分支政策在上游強制執行。 - 技能本體中,除了合約條款外,不得提及
hyperframes。 提供者選擇仍透過PROVIDERS.md+lib/router.ts進行。此技能是引導程式;執行時期的選擇仍與提供者無關。 - 請勿編輯任何已渲染的 MP4 或
outputs/目錄下的任何檔案。 此技能僅變更引擎的內部機制。 - 絕不刪除現有的
compliance-<客戶名稱>技能或任何客戶專用的成品。 此整合僅為附加性質。
失敗模式
- 步驟 1 前置檢查失敗(非行銷引擎儲存庫):顯示缺少的檔案並停止。不要嘗試「修復」它。
- 某個檔案已存在但內容衝突(例如
.skills/hyperframes/SKILL.md曾被手動編輯):與標準內容進行比對;顯示差異;在覆寫前詢問操作員。 npm run typecheck報告lib/providers/中有新的 TypeScript 錯誤:停止,顯示錯誤,不進行提交。git push因非網路原因失敗:停止。網路失敗則依專案的 git 政策重試(2 秒、4 秒、8 秒、16 秒的退避間隔,最多重試 4 次)。
相關技能
hyperframes:執行時期編寫(此技能在步驟 2 中安裝)。hyperframes-cli:執行時期 lint/inspect/render(此技能在步驟 2 中安裝)。hyperframes-prompt-builder:執行時期專用提示建構器(此技能在步驟 2 中安裝)。video-prompt-builder:此技能在步驟 3 中更新的調度器。llm-router:無關;LLM 提供者路由是另一個並行的調度器。
參考成品集
此技能所寫入的每個檔案的標準內容,都存在於 main 分支的已合併提交中:
- 技能:
.skills/hyperframes/SKILL.md、.skills/hyperframes-cli/SKILL.md、.skills/hyperframes-prompt-builder/SKILL.md - 提供者層:
lib/providers/types.ts、lib/providers/matrix.ts、lib/providers/video.ts、lib/providers/__mocks__/video.ts - 路由矩陣:
.specs/architecture/PROVIDERS.md - 環境變數:
.env.example - 專案章程:
CLAUDE.md
如有疑問,請與 origin/main 比對到已合併的參考提交,並逐字複製標準版本。請勿憑記憶重新輸入。