media-use
將媒體需求解析為凍結的本地檔案。一個指令、四種型別、零上下文雜訊。
使用時機
每當創作需要媒體（背景音樂、音效、圖片或圖示）時，請呼叫 resolve。media-use 會搜尋 HeyGen 目錄，下載最佳匹配項目，將其凍結到本地，並註冊到清單中。代理只會收到一行結果；所有搜尋雜訊都保留在磁碟上。
Resolve
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
回傳一行結果：resolved <id> → <path> (<type>, <metadata>)
型別
| 型別 | 功能 | 提供者 |
|---|---|---|
bgm | 背景音樂 | HeyGen 音訊目錄 (10k+ 首曲目) |
sfx | 音效 | 內建 19 個檔案庫 + HeyGen 目錄 |
image | 照片、背景圖 | HeyGen 素材搜尋 (75k+ 向量素材) |
icon | 圖示、標誌 | HeyGen 素材搜尋 (type=icon) |
範例
# 背景音樂
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
# 音效
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
# 圖片
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
# → resolved image_001 → .media/images/image_001.jpg (image)
# 圖示
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
旗標
| 旗標 | 說明 |
|---|---|
--type, -t | 媒體型別：bgm, sfx, image, icon |
--intent, -i | 需求描述（自然語言） |
--entity, -e | 用於快取比對的實體名稱（選填） |
--project, -p | 專案目錄（預設：.） |
--adopt | 批次匯入現有 assets/ 目錄到清單 |
--json | 輸出 JSON 格式而非一行結果 |
運作方式
- 檢查專案
.media/manifest.jsonl是否有完全吻合的提示詞 - 掃描現有
assets/目錄中未註冊且符合需求的檔案 - 檢查全域快取
~/.media/是否有可重複使用的素材 - 透過提供者搜尋（HeyGen 音訊目錄、HeyGen 素材搜尋）
- 將檔案凍結至
.media/<type>/，註冊到清單，重新產生index.md
代理只會收到一行結果。候選項目、分數、來源資訊都保留在磁碟上。
採用現有專案
大多數 HyperFrames 專案都已將素材放在 assets/ 中。media-use 可以採用它們：
node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
# → adopted 9 assets from assets/
# bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
# image_001 → assets/images/avatar.jpg (image, 400×400)
ffprobe 會提取真實的時長和尺寸。在解析過程中，assets/ 中未註冊且符合需求的檔案會被當場採用。
讀取庫存
解析或採用後，讀取 .media/index.md 即可查看完整庫存：
# .media · 4 assets
id type dur dims path description
bgm_001 bgm 25s — .media/audio/bgm/bgm_001.mp3 upbeat tech launch
sfx_001 sfx 0.6s — .media/audio/sfx/sfx_001.mp3 whoosh
image_001 image — 1920×1080 .media/images/image_001.jpg gradient tech background
icon_001 icon — 200×200 .media/images/icon_001.png rocket
跨專案重用
解析時會自動快取素材。後續對相同提示詞的解析會命中全域快取 ~/.media/ — 無需重新下載，無需呼叫提供者。使用 organize --promote <id> 明確推廣某個素材，使其可在所有專案中重用。
檔案
.media/manifest.jsonl— 機器單一真相來源，每行一條 JSON 記錄.media/index.md— 代理可讀的表格（id, type, dur, dims, path, description）~/.media/— 全域跨專案重用快取（以內容定址，SHA-256）
使用的 CLI 工具
| 工具 | 用途 | 必要？ |
|---|---|---|
ffprobe | 採用時探測時長、尺寸、編碼格式 | 是 |
heygen | 音訊目錄、素材搜尋 | 用於提供者 |
安裝 heygen CLI（單一靜態二進位檔，無需執行環境）並進行驗證：
curl -fsSL https://static.heygen.ai/cli/install.sh | bash # 安裝最新版至 ~/.local/bin
heygen update # 若已安裝：需 >= v0.1.6
export HEYGEN_API_KEY=<your-key> # 或：heygen auth login --key <key>
需要 heygen >= v0.1.6 — 提供者會使用已列入白名單的 --headers 'X-HeyGen-Client-Source: media-use' 旗標發送請求，此功能新增於 v0.1.6。asset search 是一個預發佈指令，不會顯示在 heygen --help 中，但仍可正常執行。如果 PATH 中沒有 heygen（或沒有有效的金鑰），提供者會向 stderr 輸出一行診斷訊息，解析將退回為「無提供者能解析」的狀態。