外掛程式安裝： 在執行設定或更新命令之前，如果此技能位於 HyperFrames 外掛程式中，請遵循外掛程式執行規則。獨立安裝則保留下列更新說明。
HyperFrames 註冊表
註冊表提供可透過 hyperframes add <名稱> 安裝的可重用區塊和元件。
- 區塊 — 獨立的子組合（擁有自己的尺寸、持續時間和時間軸）。透過主組合中的
data-composition-src屬性包含。 - 元件 — 效果片段（沒有自己的尺寸）。直接貼上到主組合的 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/無頭模式）
安裝後，CLI 會顯示已寫入的檔案和一個可用於貼上到主組合中的程式碼片段。該程式碼片段是一個起點——您需要在接線區塊時添加 data-composition-id（必須與區塊內部的組合 ID 相符）、data-start 和 data-track-index 屬性。
位置參數會先嘗試解析為確切的項目名稱。如果沒有項目匹配且該值是一個標籤，則命令會安裝所有帶有此標籤的區塊。註冊表依賴關係會在請求的項目之前安裝。hyperframes add 僅適用於區塊和元件；對於範例，請改用 hyperframes init <目錄> --example <名稱>。
安裝位置
區塊預設安裝到 compositions/<名稱>.html。元件預設安裝到 compositions/components/<名稱>.html。
這些路徑可在 hyperframes.json 中配置：
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
完整詳情請參閱 install-locations.md。
接線區塊
區塊是獨立的組合——透過在您的主 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。
接線元件
元件是片段——將它們的 HTML 貼上到您的組合標記中，CSS 貼上到您的樣式區塊中，JS（如果有）貼上到您的腳本中：
- 讀取已安裝的檔案（例如，
compositions/components/grain-overlay.html） - 將 HTML 元素複製到您的組合的
<div data-composition-id="...">中 - 將
<style>區塊複製到您組合的樣式中 - 將任何
<script>內容複製到您組合的腳本中（在您的時間軸代碼之前） - 如果該元件公開了 GSAP 時間軸整合（請參閱片段中的註釋區塊），則將這些調用添加到您的時間軸中
完整詳情請參閱 wiring-components.md。
探索
使用 CLI 作為主要的探索介面。在瀏覽之前，先按意圖搜尋： 註冊表中的項目數量多到無法用肉眼掃描完畢，因此列出它們並按名稱或標籤匹配是較慢的路徑，並且當作者用詞與您的用詞不同時，這種方式會失敗。
# 根據節拍應有的效果對整個目錄進行排名
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe
搜尋是本地進行的，不會發送任何資料。預設情況下，它根據與項目名稱、標題和描述共享的詞彙進行排名，因此它只會找到重複使用您用詞的項目；--on-device 則根據語義進行排名，但需要一次性下載模型。使用 --json 時，訊息框中會指明是哪個層級進行了回應，因此請檢查該資訊，而不是假設排名已發生。
無論影片使用何種語言，請始終使用英文進行查詢。 目錄是用英文編寫的，兩個層級都是這樣索引的（本機模型也是僅限英文的）。使用其他語言的查詢會產生無搜尋詞條，並且不會返回任何結果。在日本或中國的專案中很容易犯這個錯誤，因為其中的簡報、字幕和旁白都是該語言，查詢自然會跟隨：用英文描述 動作，然後用影片所需的任何語言編寫螢幕上的文字。如果查詢返回 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 <名稱> 安裝選定的名稱。--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 無法連線的註冊表不會使探索的目錄為空：只要重新驗證失敗，先前獲取的清單會在其 24 小時刷新視窗之後繼續提供服務，因此 catalog 和 catalog --query 仍然會根據磁碟上的最後一個副本進行列出和排名。
即使對於您昨天安裝的項目，add 仍然需要網路。 只有清單會被快取；項目實際的檔案在每次安裝時都會被抓取。因此，在離線狀態下，您可以搜尋，也可以查看項目的內容，但安裝會在檔案抓取時失敗。不要向用戶承諾離線安裝。
每個項目的 registry-item.json 包含：名稱、類型、標題、描述、標籤、尺寸（僅區塊）、持續時間（僅區塊）和檔案清單。
有關按類型和標籤篩選的詳細資訊，請參閱 discovery.md。
貢獻新的區塊或元件
要創作一個新的註冊表項目（字幕樣式、VFX 區塊、過渡效果、下三分之一或可重複使用的元件），並將其作為上游 PR 提交——而不是安裝現有的項目——請遵循完整的構想 → 創建骨架 → 建構 → 驗證 → 預覽 → 發布工作流程，詳見 contributing.md。可複製貼上的入門範本（字幕 / VFX / 元件 / registry-item.json）可在 templates.md 中找到。