media-use

1实现原理 · 为什么它能做到

核心是「一个动词」的 CLI 架构：SKILL.md 把 BGM/SFX/图/图标/logo/人声/校色/LUT 八类媒体需求全部收敛为一条 `resolve` 命令，agent 把用户意图转成 `--intent`，搜索噪音全部落盘、只回一行结果。

skills/media-use/SKILL.md

```bash node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir> ``` Returns one line: `resolved <id> → <path> (<type>, <metadata>)`. All search noise stays on disk.

注：这里在做什么：把「查素材」抽象成类型+意图的一次调用；实现是 skills/media-use/scripts/resolve.mjs 及其 lib/（provider cascade、candidates、adopt、manifest 均由 lib/ 承担），而不是纯提示词承诺。

查找类能力（bgm/sfx/image/icon/voice）默认走 HeyGen 目录的 free-usage 路径，要求先安装并 OAuth 登录 heygen CLI，并以 --doctor 自检，否则不工作。

skills/media-use/SKILL.md

First run: install and sign in to the `heygen` CLI (the free-usage path), then verify with `node <SKILL_DIR>/scripts/resolve.mjs --doctor`.

注：能力真实性依赖外部 CLI 与账号：bgm 是『HeyGen catalog, 10k+ tracks』、image 是『HeyGen asset search, 75k+ vectors』（SKILL.md 同表）；SKILL 内嵌安装/登录步骤（references/setup-providers.md 的 `heygen auth login --oauth`）。

生成类能力是「服务端默认 + 本地可选」双轨：BGM 生成用 Google Lyria（需 $GOOGLE_API_KEY/$GEMINI_API_KEY）失败回退本地 MusicGen；voice 用 HeyGen TTS 或本地 Kokoro；image 本地 mflux；video 本地 LTX——全部经 lib/ 脚本执行。

skills/media-use/audio/scripts/lyria-recipe.py

Generate BGM using Google Lyria RealTime API. Usage: python lyria-recipe.py --output <path> --duration <seconds> [tuning flags] Requires: $GOOGLE_API_KEY or $GEMINI_API_KEY environment variable (treated as aliases).

注：bgm.mjs 注释同源：『Lyria (cloud, $GEMINI_API_KEY/$GOOGLE_API_KEY + google-genai) preferred』；本地模型靠 pip/uv 装（mflux==0.9.6、parakeet-mlx、git clone ltx-2-mlx），见 setup-providers.md 工具表。

logo 解析走『svgl → simple-icons → GitHub 头像 → 域名 favicon』链，绝不手绘商标；这些是带网络请求的真实 provider（logo-provider.mjs）。

skills/media-use/scripts/lib/logo-provider.mjs

https://api.svgl.app https://cdn.jsdelivr.net/npm/simple-icons

注：SKILL.md 类型表自述 `logo` 为『official brand marks (svgl → simple-icons → GitHub avatar → favicon; never redrawn)』——外发端点是第三方 CDN/图标服务。

媒体操作（cut/reframe/transform/duck/loudness/字幕切分/错误扩散/HEVC）由自研 node 脚本 + ffmpeg 落地，例如 freeze.mjs 对『冻结远程 URL』做了 SSRF 防护（拒绝 localhost/内网/链路本地）。

skills/media-use/scripts/lib/freeze.mjs

/^(localhost|.*\.local|.*\.internal|127\.|10\.|0\.|169\.254\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|\[?(::1|::ffff:127\.|f[cd][0-9a-f]{2}:|fe80:))/i;

注：同目录配套 freeze.test.mjs 对 youtube/vimeo/x 白名单、对 http://169.254.169.254/a.mp4 等内网地址断言拦截——把 SSRF 防线写成了可测代码。

跨项目记忆/缓存是真实文件系统结构：项目 `.media/` + 全局 `~/.media/`（SHA-256 内容寻址缓存），偏好与整包 recipe 分项目/个人两档持久化，由 prefs.mjs/recipe.mjs 读写。

skills/media-use/references/memory.md

- `.media/manifest.jsonl`: machine SSOT, one JSON record per line - `~/.media/`: global cross-project reuse cache (content-addressed, SHA-256)

注：SKILL.md 声称『reuse assets across projects』的实现基础即此：先 `--candidates` 列出可复用资产、`--reuse <sha>` 从全局缓存导入（resolve.md Flags 表）。

遥测默认开启但内容刻意粗粒度：PostHog 事件只含媒体类型/来源/provider，不带 intent 文本与路径，有 DO_NOT_TRACK / HYPERFRAMES_NO_TELEMETRY / CI / dev 退出开关，与 hyperframes CLI 共用 ~/.hyperframes/config.json 身份。

skills/media-use/references/meta.md

It records only the media TYPE, the resolution SOURCE, and the winning PROVIDER: never the intent text, file names, or paths, and `$ip:null` so no IP is stored. Best-effort and non-blocking (a resolve never waits on or fails from telemetry).

注：实现对应 scripts/lib/telemetry.mjs：`POSTHOG_HOST = "https://us.i.posthog.com"`，写 ~/.hyperframes/config.json（anonymousId/telemetryNoticeShown），是 skill 内唯一『默认对外发数据』的路径。

2核心能力

01八类媒体一次 resolve：bgm/sfx/image/icon/logo/voice/grade/lut 统一查找入口

02素材生成：TTS/音乐/图像模型在目录缺失时兜底生成（HeyGen TTS、Lyria/MusicGen、mflux、LTX）

03共享音频引擎：voiceover/转写/字幕/背景音移除（audio/ 引擎 + heygen-tts + parakeet/whisper）

04媒体操作与转码：cut/reframe/transform、exact error diffusion、HEVC、duck、loudness

05跨项目复用与记忆：--candidates/--reuse 复用全局缓存，prefs/recipe 记住用户偏好

06媒体表现力机会扫描（opportunity pass）：一次落地扫描 + 一次征询，grounded/opinionated/never silently mutate

3外部依赖

类型	依赖
cli	heygen CLI（HeyGen，OAuth free-usage / api-key）
cli	ffmpeg/ffprobe（adopt 探测、signalstats、cut、duck bake、loudnorm）
cli	mflux-generate / parakeet-mlx / ltx-2-mlx / codex（本地或订阅生成器，opt-in）
api	HeyGen REST API
api	Google Lyria RealTime（BGM 生成，google-genai）
api	ElevenLabs TTS（可选，tts.mjs 分支）
network	PostHog 遥测
network	logo 源：svgl / simple-icons(jsdelivr) / GitHub 头像 / DuckDuckGo favicon
network	LUT CDN
network	本地模型下载/安装（Hugging Face、uv/pip、git）
package	@hyperframes CLI 内联能力（Kokoro TTS、remove-background 等）

4风险提醒风险提醒：橙色 · 评估后使用

风险提醒：橙色 · 评估后使用

凭证接触面广：读取 env API keys、就近 .env、~/.heygen、OAuth 会话并写 ~/.hyperframes/config.json — 在不可信项目目录中运行会读取该目录 .env（最多上溯 5 层）；agent 宿主若放行，等于把这些密钥暴露给 skill 的执行环境。评估使用，勿在共享/陌生环境无防跑。
默认启用网络遥测（PostHog），账号登录后事件与 HeyGen 账号关联 — 可 DO_NOT_TRACK=1 / HYPERFRAMES_NO_TELEMETRY=1 关闭；内容不含 intent/路径，但安装 id 与账号画像对隐私敏感用户仍需知情。
依赖大量第三方供应链（heygen CLI、pip/uv 包、git clone 模型、CDN 素材），任一源被投毒都影响产出或环境 — 本地模型为 opt-in 缓解；heygen CLI 安装走官方 release；仍建议校验来源与版本。
远程 URL 冻结虽防 SSRF，但下载素材来源多样，版权/许可需 agent 自行把关 — SFX 库自带 CREDITS（pixabay），logo 链取官方源；用户提供的 URL 素材合规由宿主工作流负责。

风险提醒：橙色，评估后使用。接触面集中在 media-use：读取多来源凭证（环境变量 API keys、就近 .env、~/.heygen credentials、OAuth 会话），外发到多个第三方端点（HeyGen API、Google Lyria、PostHog 遥测、logo CDN、模型下载），并按需 pip/uv/git 安装第三方本地模型。缓解项：默认走 HeyGen free-usage OAuth 路径、本地模型 opt-in、--local-only 完全断网、SSRF 拦截有测试、遥测可关且内容粗粒度、付费调用需 agent 先确认。触发条件：用户请求 resolve/generate/operate 类媒体任务时才会执行脚本与外发。

5第二遍独立确认

[ok] external_deps 中每个 CLI/API/网络端点的调用点真实存在 — 逐一反查：heygen CLI（setup-providers.md 安装/登录段）、ffmpeg（工具表）、Lyria（lyria-recipe.py 头部 docstring + bgm.mjs lyriaConfigured）、PostHog（telemetry.mjs 常量）、logo 源（logo-provider.mjs URL 常量）、LUT CDN（luts/index.json 记录）均有源码落点。
[ok] 安全结论有无漏网网络调用 — URL 全量扫描覆盖 scripts/audio/luts/references；未发现扫描范围外的域；遥测为默认唯一自发性外发，opt-out 与注释一致。
[ok] 凭证读取面是否如描述（env/.env/~/.heygen） — heygen.mjs 头注释与 loadEnvFromDir 实现（walk ≤5 dirs、shell env 优先）与描述一致；audio/scripts/lib/{heygen,tts,bgm}.mjs 分别读 HEYGEN/ELEVENLABS/GEMINI key。
[ok] SSRF 防护声称 — freeze.mjs 第 57 行正则实际拦截 localhost/*.local/*.internal/127./10./169.254./192.168./172.16-31 与 IPv6 环回；freeze.test.mjs 同时断言拦截内网样例。
[ok] 是否有将远程内容当指令/可执行代码的路径 — 下载资产均为数据文件（audio/image/cube）；脚本为随包源码；未发现下载即执行路径。
[ok] 功能声明夸大检查（media treatments、10k+ 曲库、75k+ 向量） — 目录规模数字来自 HeyGen 服务端宣称（SKILL.md 表格原文），skill 侧可验证的是调用点与回退链存在；『produce voiceover…background removal』对应 audio/ 引擎脚本与 provider 表。超出本地可验证的部分按供应商宣称标注。

6结论

把 8 类媒体需求收敛为一个可审计的 resolve 动词，所有实现落在可测 node/python 代码而非提示词承诺

安全工程意识在同生态内最高：SSRF 拦截写进代码并带测试、.env 读取不覆盖既有环境、遥测内容粗粒度可一键关闭

默认走免费路径与本地可选模型并存的务实分层，RAM 分级让低配环境也有可运行子集

媒体表现力建议纪律化：grounded/一次征询/永不静默改动，防止 agent 自作主张加料

明确成本护栏：agent 发起的付费生成需先确认，调用带客户端归因头

适合：适合在 HyperFrames 项目（或任意 HTML-to-video 工作流）里需要『找/生成/改/记住』媒体资产的 agent 会话：产品视频、解说视频、需要 BGM/SFX/旁白/图标的创作。也适合想研究『skill 如何把供应商 API + 本地模型 + 记忆 + 遥测织成一个可测 CLI』的开发者当范本。

不适合：不适合零网络/零凭证的完全隔离环境（应改用 --local-only 且预装本地模型，或选无 provider 的纯编排技能）；不适合不想产生任何外发与账号关联的用户（遥测需手动关）；不适合把媒体素材处理当副业、只要 prompt 指引的轻量场景（本 skill 强制 CLI+账号+ffmpeg 依赖）。

安装 agent 直装可复制

① 本站镜像更新 2026-09-09

方式 A · 人下载镜像包下载 media-use.tar.gz

sha256: e19482b5849526de…

方式 B · JSON 格式安装指南，复制给 agent

安装指南

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② 上游 GitHub · 原始来源

能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗

本页镜像锁定 commit b8328f9573；上游为实时仓库。

来源信息 GitHub 原始

作者 / 仓库heygen-com / heygen-com/hyperframes

原始 GitHubheygen-com/hyperframes ↗

Stars48297

最近推送2026-09-09

本 skill commitb8328f9573

许可Apache-2.0（仓库根 LICENSE，GitHub API spdx Apache-2.0）

本站信息

收录日期2026-09-06

分类内容创作

侦查报告2026-09-06 · 2 遍

本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。

1实现原理 · 为什么它能做到

2核心能力

3外部依赖

4风险提醒 风险提醒：橙色 · 评估后使用

5第二遍独立确认

6结论

4风险提醒风险提醒：橙色 · 评估后使用