Communitygithub.com

kitfunso/claude-config

安裝、探索與串接 HyperFrames Registry 的區塊與元件。可用於 hyperframes add、catalog、index.html 配線、hyperframes.json。

claude-config 是什麼?

這個技能可讓 AI 代理(如 Claude Code、Cursor 或 Codex)直接與 HyperFrames Registry 互動。HyperFrames 是一個可複用區塊(獨立子合成)與元件(效果片段)的目錄,專為 Heygen 影片合成而設計。技能提供完整的 CLI 操作,包括透過 `hyperframes add <name>` 安裝區塊或元件、設定安裝路徑(預設區塊在 `compositions/`,元件在 `compositions/components/`),以及透過 `hyperframes catalog` 與語意查詢探索目錄。搜尋功能支援英文關鍵字查詢,並可使用 `--on-device` 選項進行離線模型語意比對。安裝後,CLI 會提供配線用的 HTML 片段,協助開發者在 `index.html` 中正確設定 `data-composition-src`、`data-start`、`data-duration` 等屬性。當目錄無法滿足需求時,技能鼓勵使用者透過 `hyperframes feedback` 回報缺口,以幫助擴充目錄。這個技能在多種開發環境(CLI、CI/CD、AI 代理)中都能穩定運作。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kitfunso/claude-config/tree/HEAD/skills/hyperframes-registry

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

HyperFrames Registry

此 Registry 提供可複用的區塊與元件,可透過 hyperframes add <名稱> 安裝。

  • 區塊 (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/無頭模式)

安裝完成後,CLI 會顯示寫入了哪些檔案,以及可供貼入主合成的程式碼片段。該片段是起點——在配線區塊時,你需要自行加入 data-composition-id(必須與區塊內部的合成 ID 相符)、data-start 和 data-track-index 屬性。

位置參數會先被解析為精確的項目名稱。如果沒有相符的項目,該值會被視為標籤,並安裝所有帶有該標籤的區塊。Registry 相依項目會在請求的項目之前先行安裝。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 貼入腳本區塊(如果有的話):

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

詳細資訊請參閱 wiring-components.md。

探索

將 CLI 當作主要的探索介面。先以意圖搜尋,再瀏覽: Registry 中的項目數量遠超過肉眼可掃描的範圍,因此僅列出並比對名稱或標籤是慢速方法,且當作者的用詞與你的用詞不同時就會失敗。

# 將整個目錄與效果的目標進行排序
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe

搜尋為本地端執行,不會傳送任何資料。預設情況下,它會根據與項目名稱、標題和描述共享的詞彙進行排序,因此只會找到包含你的詞彙的項目;--on-device 則根據語意排序(需一次性下載模型)。使用 --json 時,信封會標明回答的是哪個層級,因此請檢查這個標記,而不是假設已進行排序。

無論影片使用何種語言,請一律使用英文查詢。 目錄是以英文撰寫,兩個層級都以此進行索引(on-device 模型也只支援英文)。使用其他語言的查詢不會產生任何可搜尋的詞彙,而且不會傳回任何結果。在日文或中文專案中,由於簡報、字幕和旁白都是該語言,而查詢自然會順應使用該語言,因此很容易出錯:請用英文描述 動作,然後再以影片所需的語言撰寫畫面上的文字。如果查詢結果顯示 No searchable words in query,這就是這個規則所致,而不是缺少元件,因此不值得撰寫缺口報告。

可安裝性是在排序之後才套用,而不是之前:向量攜帶但此 Registry 無法提供的名稱會從結果中移除,並計入 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 攜帶——因此在你決定沒有任何項目符合需求時,這個資訊已經在你手邊。

只要結果中沒有任何項目符合需求,無論是哪個層級,都請回報。 不要等到 on-device 層級回答:它需要經過同意的 33 MB 下載,因此除非明確選擇啟用,否則代理執行將使用 words 層級,而僅限於 on-device 會讓幾乎所有的回報都無法發出。--tier 數值會一併攜帶,因此在讀取時可以區分詞彙遺漏與語意遺漏。請描述你想要的效果,而不是你想像的項目名稱:回傳的是值得建立的效果列表,而回報一個不存在的項目名稱無法提供任何資訊。這是唯一會將查詢傳送到任何地方的路徑,也正是它是一個獨立、有意的指令而非搜尋自動執行的事項的原因。它不攜帶評分,也絕不會進入評分指標。

這是目錄的整個需求訊號。跳過它意味著您遇到的缺口只能透過安裝次數來推測,而安裝次數無法看出沒有人能安裝的效果。

如果 CLI 無法連線到設定的 Registry,請檢查原始清單作為備案:

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

CLI 無法連線的 Registry 並不會讓目錄在探索時變成空的:只要重新驗證失敗,先前擷取的清單會繼續在 24 小時的重新整理視窗之外提供服務,因此 catalog 和 catalog --query 仍會針對磁碟上的最後一個副本進行列出和排序。

即使是你昨天安裝過的項目,add 仍然需要網路。 只有清單會被快取;項目本身的檔案會在每次安裝時重新擷取。因此,你可以在離線狀態下搜尋,也可以查看項目的說明,但安裝會因為無法取得檔案而失敗。請不要向使用者承諾可以離線安裝。

每個項目的 registry-item.json 包含:名稱、類型、標題、描述、標籤、尺寸(僅限區塊)、持續時間(僅限區塊)以及檔案列表。

依類型和標籤篩選的詳細資訊請參閱 discovery.md。

貢獻新的區塊或元件

若要創作一個新的 Registry 項目(字幕樣式、VFX 區塊、轉場、下三分之一或可複用的元件)並以上游 PR 的形式送出——而非安裝現有項目——請遵循 contributing.md 中的完整構想 → 建立骨架 → 建置 → 驗證 → 預覽 → 發布工作流程。複製貼上用的入門範本(字幕 / VFX / 元件 / registry-item.json)位於 templates.md。

相關技能