媒体使用 是做什么的?
将媒体需求解析为冻结的本地文件。一个动词,四种类型,零上下文噪音。
何时使用
当创作需要媒体时调用 resolve — 背景音乐、音效、图片或图标。媒体使用技能会搜索 HeyGen 目录,下载最佳匹配,在本地冻结,并在清单中注册。Agent 只返回一行;所有搜索噪音都保留在磁盘上。
解析
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
Agent 返回 一行。候选、评分、来源保留在磁盘上。
适配现有项目
大多数 HyperFrames 项目已在 assets/ 中有资源。媒体使用技能可以适配它们:
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— 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 # 安装最新版本到 ~/.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 打印一行诊断信息,解析将回退为“没有提供者能解析”。