🧩 它解决的核心问题：Agent 不该花时间在“找素材”上

用 AI Agent 做视频合成时，有一个环节特别消耗上下文：找素材。你需要一段背景音乐、一个 whoosh 音效、一张渐变背景图、一个火箭图标——Agent 得去搜索引擎翻半天，下载一堆候选文件，还得记住哪个文件对应哪个需求。

media-use 的设计目标就是把这个过程压缩成一个动词：resolve。你告诉它需要什么类型的媒体、用一句话描述意图，它替你搜索、下载、冻结到项目本地，最后只返回一行结果——文件路径。

搜索过程中的候选列表、相似度评分、来源溯源（provenance）这些“噪音”全部落在磁盘上，不进入 Agent 的上下文窗口。Agent 拿到的信息非常干净：resolved <id> → <path> (<type>, <metadata>)。

它面向七种媒体类型：

  • bgm——背景音乐，来自 HeyGen 媒体目录，10,000+ 首曲目。
  • sfx——音效，内置 19 个文件的音效库加上 HeyGen 目录。
  • image——照片和背景图，来自 HeyGen 素材搜索，75,000+ 矢量素材。
  • icon——图标和符号，透明背景。
  • logo——官方品牌标识，从 svgl、simple-icons、GitHub 头像和 favicon 按优先级获取，不重绘。
  • voice——TTS 配音，走 HeyGen 免费路径，也可以选本地 Kokoro 模型。
  • grade / lut——调色校正候选或用户提供的 .cube 文件。

除了“找和下载”，它还管“记住”。每次 resolve 完成后，资产会在项目 manifest 中登记一条记录，同时生成一个人可读的索引文件。这意味着你下次在同一个项目里需要类似的素材时，Agent 可以先查缓存，而不是重新搜索。

📦 第一次怎么装

media-use 是 HyperFrames 官方技能集的一部分，通过 skills CLI 安装。在项目根目录执行：

npx skills add heygen-com/hyperframes --skill media-use

如果你用的是白智云（AI SkillHub）的安装通道，命令略有不同：

npx bzskills add heygen-com/hyperframes --skill media-use

在 Claude Code 中，最简单的安装方式是直接把下面这句话发给它：

请帮我安装 media-use 技能：https://github.com/heygen-com/hyperframes，安装到 .claude/skills/ 目录。

安装完成后有一项必须做的配置：安装并登录 HeyGen CLI。media-use 的媒体搜索和 TTS 能力都依赖 HeyGen 的免费使用路径。首次运行时执行：

node <SKILL_DIR>/scripts/resolve.mjs --doctor

--doctor 会检查环境是否就绪，包括 ffprobe 是否可用、HeyGen CLI 是否已登录。如果提示未登录，按照终端指引完成 HeyGen 账号授权即可。

🛠️ 装好之后怎么用

media-use 的触发方式有两种。一种是在 Agent 对话里用自然语言描述需求，比如“用 media-use 帮这个项目解析一段轻快的科技感背景音乐”，Agent 会自动调用 resolve 命令。另一种是直接跑命令行，适合在脚本或 CI 中使用。

resolve 命令的基本形态：

node <SKILL_DIR>/scripts/resolve.mjs \
  --type bgm \
  --intent "轻快、有科技感、适合产品发布视频的背景音乐" \
  --project /path/to/project

成功执行后，终端只输出一行：

resolved bgm-20260911-001 → .media/bgm/upbeat-tech-01.mp3 (bgm, duration=45s, source=heygen)

几种常用参数：

  • --candidates——在正式解析之前，先列出可复用的候选资产。你可以查看候选列表后自己判断哪个最合适，而不是让模型替你做决定。
  • --from <path>——从本地已有文件“收录”一个资产，而不是从外部搜索。适合你手头已经有素材、只想把它登记到项目媒体库里的场景。
  • --json——输出机器可读的 JSON 结果，方便在脚本里解析。

关于 MCP：media-use 本身是一个 Agent Skill，不直接提供 MCP 服务器。它的设计目标是通过 skills CLI 安装到 Claude Code、Codex 等工具中，由 Agent 直接调用脚本。如果你需要 MCP 协议的支持，可以关注 HyperFrames 项目后续是否推出对应的 MCP 封装。

主要应用场景集中在 HyperFrames 视频合成工作流中：产品发布视频（解析背景音乐、过渡音效、火箭图标、品牌 Logo）、社交媒体短视频（快速获取配乐和视觉素材）、多项目素材复用（跨项目查询已解析的资产，避免重复下载）。

💡 几个让它更好用的技巧

  • 先查候选，再做决定。直接 resolve 会让模型替你选一个“最匹配”的资产，但匹配度判断不一定符合你的审美。加 --candidates 先看候选列表，你亲自挑一个更稳妥。这个习惯在音乐和图片类素材上尤其有用。
  • 利用多层级缓存省时间。resolve 的执行顺序是：项目缓存 → 全局跨项目缓存 → 本地已有资产 → 外部提供者。如果你之前已经在别的项目里解析过类似的素材，第二次会直接从缓存命中，速度会快很多。这也是它“跨项目复用”能力的来源。
  • Figma 导入的资产可以直接被 media-use 查询。从 HyperFrames v0.7.31 开始，每次 hyperframes figma asset 导入都会同步生成与 media-use 格式字节级一致的索引文件。导入时携带的 --description 和 --entity 元数据会进入 manifest，media-use 的实体查询可以跨过 icon/image 的类型边界直接命中。品牌标识（brand mark）的实体查询现在可以命中从 Figma 导入的 Logo。
  • 用实体名做查询。如果你在 Figma 导入时给某个资产指定了 --entity "Acme logo"，之后可以用这个实体名直接查询，不需要记住文件路径或资产 ID。这比按类型和关键词搜索精确得多。
  • 安装后重启 Agent 会话。如果安装完成后 Agent 没有响应 media-use 相关的指令，先确认 Skill 目录是否被当前 Agent 读取，然后重启或新建一个会话。这是 Agent Skill 类工具的常见行为。

🔗 可以配合什么使用

  • 配合 HyperFrames 做视频合成。media-use 是 HyperFrames 媒体工具链中的资产管理层。HyperFrames 负责视频合成和时间轴编排，media-use 负责“给合成提供素材”。两者是上下游关系：你先用 media-use 把需要的 BGM、音效、图片、图标解析到本地，再把它们接入 HyperFrames 的合成项目。
  • 配合 hyperframes-registry 使用。registry 负责安装和接线可复用的区块与组件，media-use 负责提供这些区块和组件所需的媒体素材。一个管“结构”，一个管“内容”。
  • 配合 Figma 做品牌资产同步。设计团队在 Figma 里维护品牌标识和视觉资产，开发团队通过 hyperframes figma asset 导入，导入的资产自动进入 media-use 的查询范围。设计变更后重新导入即可，不需要手动同步文件。
  • 配合本地 TTS 做配音。voice 类型默认走 HeyGen 的免费 TTS 路径，但如果你需要完全本地化，可以配置 Kokoro 本地模型。适合对隐私或离线运行有要求的场景。

🤖 适合哪些 AI 工具

media-use 是一个标准的 Agent Skill，本质上是一份 SKILL.md 文件，不绑定特定平台。它的官方文档明确列出了经过验证的兼容工具：Claude Code、Codex、GitHub Copilot、Cursor、OpenClaw / Hermes 风格 Agent，以及任何支持 Agent Skill 运行时的工具。

在 Claude Code 中，安装后输入 /media-use 即可手动触发，Agent 检测到媒体解析意图时也会自动调用。在 Cursor 和 Codex 中，Agent 会通过读取项目中的 skill 文件来获得调用能力。

需要留意的是，media-use 的搜索和下载能力依赖 HeyGen 媒体目录。这不是一个完全离线的工具——它需要访问 HeyGen 的 API 来检索 BGM、音效、图片和图标。如果你需要完全离线的素材管理方案，media-use 的缓存机制可以部分满足（已解析的资产在本地），但首次解析仍然需要联网。另外，它的定位是 HyperFrames 项目内的媒体资产管理，不是通用的素材库管理工具。如果你不在 HyperFrames 工作流里，它的许多能力（如与 Figma 导入的互操作）可能用不上。