HyperFrames Registry

註冊表提供可重複使用的區塊和元件，可透過 hyperframes add <name> 安裝。

區塊 (Blocks) — 獨立子組合（有自己的尺寸、時長、時間軸）。透過主組合中的 data-composition-src 引入。
元件 (Components) — 效果片段（無獨立尺寸）。直接貼入主組合的 HTML 中。

快速參考

hyperframes add data-chart              # 安裝一個區塊
hyperframes add grain-overlay           # 安裝一個元件
hyperframes add captions                # 安裝所有標記為 captions 的區塊
hyperframes add shimmer-sweep --dir .   # 指定目標專案
hyperframes add data-chart --json       # 機器可讀輸出
hyperframes add data-chart --no-clipboard  # 跳過剪貼簿（CI/headless 環境）

安裝後，CLI 會列出已寫入的檔案以及一個可貼入主組合的片段。該片段僅為起點 — 接入區塊時，你仍需添加 data-composition-id（必須與區塊內部的組合 ID 相符）、data-start 和 data-track-index 屬性。

位置參數會先嘗試精確比對項目名稱。如果沒有名稱相符且該值是標籤，則命令會安裝所有帶該標籤的區塊。在請求項目之前，會先安裝其依賴項目。hyperframes add 僅適用於區塊和元件；對於範例，請改用 hyperframes init <dir> --example <name>。

安裝位置

區塊預設安裝到 compositions/<name>.html。元件預設安裝到 compositions/components/<name>.html。

這些路徑可在 hyperframes.json 中配置：

{
  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}

詳情請參閱 install-locations.md。

接入區塊 (Wiring blocks)

區塊是獨立的組合 — 在你的主 index.html 中透過 data-composition-src 引入：

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>

關鍵屬性：

data-composition-src — 區塊 HTML 檔案的路徑
data-composition-id — 必須與區塊內部的 ID 相符
data-start — 區塊在主時間軸上出現的時間（秒）
data-duration — 區塊播放的時長
data-width / data-height — 區塊的畫布尺寸
data-track-index — 圖層順序（數值越大越靠前）

詳情請參閱 wiring-blocks.md。

接入元件 (Wiring components)

元件是片段 — 將其 HTML 貼入組合的標記中，CSS 貼入樣式區塊，JS 貼入腳本（如有）：

讀取已安裝的檔案（例如 compositions/components/grain-overlay.html）
將 HTML 元素複製到組合的 <div data-composition-id="..."> 中
將 <style> 區塊複製到組合的樣式中
將任何 <script> 內容複製到組合的腳本中（在時間軸代碼之前）
如果元件提供了 GSAP 時間軸整合（請參閱片段中的註解區塊），將這些呼叫加入到你的時間軸中

詳情請參閱 wiring-components.md。

探索 (Discovery)

使用 CLI 作為主要的探索入口。先根據意圖搜尋，而非瀏覽： 註冊表中的項目遠多於肉眼所能掃描，因此列出所有項目並根據名稱或標籤進行比對是較慢的方法，而且當作者的用詞與你的用詞不同時，這種方式會失敗。

# 對整個目錄進行排名，找出最符合 Beat 需求的項目
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe

搜尋在本機進行，不會發送任何資料。預設情況下，它根據與項目名稱、標題和描述共享的詞彙進行排名，因此只會找到使用與你相同詞彙的項目；--on-device 則根據語義進行排名（需一次性下載模型）。搭配 --json 時，回傳的 envelope 會顯示是哪個層級回應的，因此請檢查該欄位，而非假設一定進行了排名。

無論影片使用何種語言，一律使用英文進行查詢。 目錄是用英文編寫的，兩個層級也是以英文索引（裝置端模型也只支援英文）。使用其他語言的查詢無法產生可搜尋的詞彙，結果將為空。在日本或中文專案中很容易犯這個錯，因為簡報、字幕和旁白都是該語言，查詢自然會跟隨該語言：請用英文描述動作，然後用影片所需的任何語言編寫畫面上的文字。如果查詢回傳 No searchable words in query，表示違反了此規則，而非缺少元件，這不值得提交缺口報告。

可安裝性是在排名之後才套用的，而非之前：向量模型所攜帶但此註冊表無法提供的名稱會從結果中移除，並計入 dropped 中，因此非零的 dropped 表示兩者屬於不同世代。請參閱 /hyperframes-cli 了解離線層級、同意閘門以及如何更新過期的索引。

若要瀏覽或篩選而非搜尋：

npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly

一般表格模式和 --json 模式僅列出符合項目；使用 hyperframes add <name> 安裝選定的項目。--human-friendly 會開啟互動式選擇器並立即安裝選定的項目。在 CI 或代理工作流程中，建議先使用 --json，然後再明確執行 add。

回報目錄中缺少的項目

當搜尋結果回傳，但其中沒有任何項目能滿足需求時，請在親手製作該效果之前先說明：

npx hyperframes feedback --search-miss "<你執行的查詢>" --wanted "<你需要的效果>" --tier on-device

catalog --query 會預先為你印出這一行，--json 則會將其作為 report_gap 攜帶 — 因此在你決定沒有合適項目的那一刻，它已經在你手邊了。

只要結果中沒有任何項目能滿足需求，就請回報，不論是哪個層級。 不要等待裝置端層級回應：它需要已同意的 33 MB 下載，因此除非明確選擇加入，否則代理執行時只會使用 words 層級，而如果只依賴 on-device 層級，幾乎所有報告都會被忽略。--tier 值會隨報告一起記錄，以便在閱讀時區分詞彙缺失與語義缺失。描述你需要的效果，而非你想像中的項目名稱：回傳的結果是一系列值得建立的效果清單，而回報一個不存在的項目名稱則無法提供任何有用的資訊。這是唯一會將查詢發送到任何地方的指令，正因如此，它是一個獨立的有意命令，而非搜尋本身自動執行的動作。它不包含評分，也絕不會進入評分指標。

這是整個目錄的需求訊號。跳過它意味著你所遇到的缺口只能從安裝次數來猜測，而這完全無法看到那些沒有人能夠安裝的效果。

如果 CLI 無法連線到已配置的註冊表，請使用以下指令檢查原始清單作為備份：

curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json

CLI 無法連線的註冊表不會讓目錄在探索時變空：之前取得的 manifest 在重新驗證失敗時，會繼續在 24 小時的重新整理視窗之後提供服務，因此 catalog 和 catalog --query 仍會列出並根據磁碟上的最後一個副本進行排名。

add 仍然需要網路連線，即使是你昨天才安裝過的項目。 只有 manifest 會被快取；項目的實際檔案在每次安裝時都會重新取得。因此，在離線狀態下你可以搜尋，也能看到項目的資訊，但安裝會因為無法獲取檔案而失敗。請勿向使用者承諾離線安裝。

每個項目的 registry-item.json 包含：名稱、類型、標題、描述、標籤、尺寸（僅限區塊）、時長（僅限區塊）以及檔案列表。

詳細的按類型與標籤篩選說明，請參閱 discovery.md。

貢獻新的區塊或元件

若要創作一個新的註冊表項目（字幕樣式、VFX 區塊、轉場、下三分之一、或可重複使用的元件）並將其作為上游 PR 提交 — 而非安裝現有項目 — 請遵循 contributing.md 中的完整 idea → scaffold → build → validate → preview → ship 工作流程。複製貼上用的入門模板（字幕 / VFX / 元件 / registry-item.json）可在 templates.md 中找到。

hyperframes-registry