media-use

media-use

将媒体需求解析为本地冻结文件。一个动词、四种类型、零上下文噪声。

使用时机

只要合成内容需要媒体——背景音乐、音效、图片或图标，就调用 resolve。media-use 会搜索 HeyGen 目录、下载最佳匹配项、将其冻结到本地，并在清单中注册。Agent 只会收到一行结果；所有搜索噪声都留在磁盘上。

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）

示例

# Background music
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)

# Sound effect
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)

# Image
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
# → resolved image_001 → .media/images/image_001.jpg (image)

# Icon
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，而不是单行结果

工作原理

1. 检查项目 .media/manifest.jsonl 中是否有精确提示词匹配项
2. 扫描现有 assets/ 目录，查找符合需求但尚未注册的文件
3. 检查全局缓存 ~/.media/，查找可复用资源
4. 通过提供方搜索（HeyGen 音频目录、HeyGen 资源搜索）
5. 将文件冻结到 .media/<type>/，在清单中注册，并重新生成 index.md

Agent 只会收到一行结果。候选项、评分和来源信息都保留在磁盘上。

导入现有项目

大多数 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 会提取真实时长和尺寸。执行 resolve 时，assets/ 中符合意图但尚未注册的文件会被即时导入。

查看资源清单

执行 resolve 或 adopt 后，读取 .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

跨项目复用

执行 resolve 时会自动缓存资源。后续对相同提示词执行 resolve 时，会命中 ~/.media/ 中的全局缓存——无需重新下载，也无需调用提供方。使用 organize --promote <id> 显式提升某个资源，即可在所有项目中复用。

文件

• .media/manifest.jsonl — 机器可读的 SSOT，每行一条 JSON 记录
• .media/index.md — Agent 可读的表格（id、type、dur、dims、path、description）
• ~/.media/ — 跨项目全局复用缓存（内容寻址，SHA-256）

使用的 CLI 工具

工具	用途	是否必需？
ffprobe	导入时探测时长、尺寸和编解码器	是
heygen	音频目录、资源搜索	用于提供方

安装 heygen CLI（单个静态二进制文件，无需运行时）并进行身份验证：

curl -fsSL https://static.heygen.ai/cli/install.sh | bash   # installs latest to ~/.local/bin
heygen update                                               # if already installed: needs >= v0.1.6
export HEYGEN_API_KEY=<your-key>                            # or: 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 输出一行诊断信息，而 resolve 最终会返回“no provider could resolve”。