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外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| 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管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: node <SKILL_DIR>/scripts/resolve.mjs（各 --type；agent 直接执行）
- 网络端点: 声明外部网络访问: api.heygen.com/v3（catalog/TTS/avatar，带 X-HeyGen-Client-Source: media-use 归因
- 本地工作目录: 文件读写与工件输出: 项目 `.media/`：manifest.jsonl、index.md、preferences.json、recipes/<name>/、素材落盘
审计说明： 。接触面集中在 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结论
适合： 适合在 HyperFrames 项目（或任意 HTML-to-video 工作流）里需要『找/生成/改/记住』媒体资产的 agent 会话：产品视频、解说视频、需要 BGM/SFX/旁白/图标的创作。也适合想研究『skill 如何把供应商 API + 本地模型 + 记忆 + 遥测织成一个可测 CLI』的开发者当范本。
不适合： 不适合零网络/零凭证的完全隔离环境（应改用 --local-only 且预装本地模型，或选无 provider 的纯编排技能）；不适合不想产生任何外发与账号关联的用户（遥测需手动关）；不适合把媒体素材处理当副业、只要 prompt 指引的轻量场景（本 skill 强制 CLI+账号+ffmpeg 依赖）。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload media-use.tar.gz
sha256:
Option B · Copy Guide for Agente19482b5849526de…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b8328f9573.