media-use

用途

media-use 用于把智能体的媒体需求（背景音乐、音效、图片、图标）解析为冻结的本地文件，并在项目清单中登记。每次调用只返回一行结果，搜索过程中的候选、评分和来源信息留在磁盘上，避免污染智能体上下文。

单一命令 resolve 处理四种媒体类型：bgm（背景音乐）、sfx（音效）、image（图片）、icon（图标）。
按顺序查找：项目 .media/manifest.jsonl 中的精确提示词匹配；assets/ 目录中未登记但符合需求的现有文件；全局缓存 ~/.media/ 中的可复用资源；最后通过提供方搜索（HeyGen 音频目录、HeyGen 资源搜索）。
命中后冻结文件到 .media/<type>/，登记到清单并重新生成 index.md。
支持 --adopt 批量导入已有 assets/ 资源，并用 ffprobe 提取真实时长与尺寸。
支持跨项目复用：解析时自动缓存到 ~/.media/，相同提示词后续命中缓存，不再下载或调用提供方；可通过 organize --promote <id> 显式提升资源以跨项目复用。
支持 --json 输出 JSON，而非单行结果。

命令形式：

node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>

返回示例：resolved <id> → <path> (<type>, <metadata>)

常用参数：--type/-t 指定媒体类型；--intent/-i 用自然语言描述需求；--entity/-e 指定用于缓存匹配的实体名（可选）；--project/-p 指定项目目录（默认 .）；--adopt 批量导入现有 assets/；--json 输出 JSON。

示例：

背景音乐：node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
音效：node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
图片：node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
图标：node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .

导入现有项目：node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .

解析或导入后，读取 .media/index.md 查看完整清单，包含 id、type、时长、尺寸、路径和描述。

ffprobe：用于在导入时探测时长、尺寸和编解码信息，必需。
heygen CLI：用于音频目录和资源搜索。安装与认证： curl -fsSL https://static.heygen.ai/cli/install.sh | bash heygen update export HEYGEN_API_KEY=<your-key> 或 heygen auth login --key <key>
要求 heygen >= v0.1.6。资源搜索是预发布命令，不出现在 heygen --help 中，但可运行。若 PATH 中没有 heygen 或密钥无效，提供方会向 stderr 输出一行诊断信息，resolve 最终回退为“no provider could resolve”。

适合需要为创作或合成任务准备媒体素材的项目，尤其是已有 assets/ 目录、希望统一登记并避免重复下载的场景。也适合需要跨项目复用媒体资源的智能体工作流。