media-use

HyperFrames 的媒体 OS：resolve · generate · operate · remember —— 每一种媒体类型，一个技能，零上下文噪声。

首次运行：安装并登录 heygen CLI（免费使用路径），然后使用 node <SKILL_DIR>/scripts/resolve.mjs --doctor 验证。设置与提供商：references/setup-providers.md。

Resolve — 唯一动词

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

返回一行：resolved <id> → <path> (<type>, <metadata>)。所有搜索噪声都留在磁盘上。

| 类型 | 一行意图 | | ------- | ----------------------------------------------------------------------------------- | | bgm | 背景音乐（HeyGen 目录，10k+ 首曲目） | | sfx | 音效（内置 19 文件库 + 目录） | | image | 照片、背景（HeyGen 资产搜索，75k+ 矢量图） | | icon | 图标、符号（透明） | | logo | 官方品牌标识（svgl → simple-icons → GitHub avatar → favicon；绝不重新绘制） | | voice | TTS 旁白（HeyGen 免费使用路径；可选本地 Kokoro） | | grade | 基于测量的校正候选；广泛润色/风格化遵循 Media Treatments | | lut | 用户提供或显式选择的可复用已验证 .cube 文件 |

在重新解析之前，使用 --candidates 列出可复用候选，并自行判断适配度 —— 复用规则、所有 flags、ingest（--from）和 adopt 见 references/resolve.md。

将宽泛的视觉反馈视为媒体意图

当用户明确要求修复、润色、风格化、遮蔽、强调或揭示摄影媒体时，即使他们没有提到 color grading 或 effect，也要读取 references/media-treatments.md。检查真实的 <img>/<video>，选择一个主要意图，然后使用确定性持久化与验证。将匹配的 recipe 作为可选的已测试 seed，或检查 hyperframes media-treatment --capabilities --json，然后使用 --capability <id> 请求一个相关的 family/effect，并从 canonical controls 组装自定义 treatment。普通创作期间绝不加载 --all。一个 treatment 可以组合 correction、preset、finishing、兼容的 shader effects、支持的 keyframes 和可选的 Registry overlays。只添加有源依据的有界调优和兼容部分，绝不仅为了让结果看起来更复杂而添加 effects。使用 hyperframes media-treatment 持久化最终合并后的 payload。

使用一个逐步升级的工作流。对于视频，检查一个带标签的 early/middle/late contact sheet，而不是分别读取帧。对于普通校正或润色，应用一个候选并检查一张 after-sheet。仅当结果存在歧义、具有时间性、风格化、基于 LUT、对 HDR/LOG 敏感、涉及隐私或品牌关键时，才升级到单帧或动态草稿证据。

对于普通校正或润色，持久化最终 treatment 的 preset/adjustment JSON。不要仅仅为了编码 exposure、shadows、contrast 或 warmth 而生成 .cube LUT。只有在用户提供 LUT 或所选 treatment 显式拥有 LUT 时才使用 LUT。resolve --type grade --for ... --analyze 是测量证据，而不是用生成的 LUT 替换所选 treatment 的许可。不要用 CSS/SVG overlays 重新创建受支持的 vignette、grain、blur、pixelate、color 或 treatment effects；这会绕过 Studio controls 和 canonical preview/render shader path。

主动出击 — 执行一次媒体机会扫描

人类通常无法判断哪些媒体会提升作品。你可以。当你构建或审查 composition 时，只执行 一次 有依据的扫描，然后 只询问一次 —— 不要静默添加，也不要对每个资产唠叨。

只有在存在具体信号时才提出机会：

| 检测到的信号 | 提供 | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | 屏幕文本 / 没有旁白的脚本 | TTS 旁白（音频引擎） | | Emoji 或样式化为 icon 的 <div> | resolve 真正的 icons | | 图像是占位符、很小或看起来被放大 | 更好的 image（和/或 upscale — 见 references/operations.md） | | 没有声音的硬场景切分 / 转场 | transition sfx | | 时长约超过 ~10s 且没有音乐垫的作品 | bgm | | 看起来欠曝/过曝或偏色的素材 | 校正性 grade（使用 hyperframes media-treatment --selector '#hero' --analyze --json 检查） | | 视觉上平淡或离题的摄影媒体 | 一个特定的源适配 preset 或 custom treatment，并指明预期目标 | | 感觉静态的有意义媒体入场/reveal | 一个支持的 seek-safe treatment animation；除非请求也证明需要 preset，否则保留颜色 |

让这成为帮助而不是唠叨的规则：有依据，而非泛泛（没有信号 → 没有建议）；有主见 + 具体（提出带有已选 defaults 的具体修复 —— 由人类批准 全部 / 部分 / 无）；每个项目一次（一次合并询问；尊重 "leave it"）；只提出，绝不静默修改（尤其是 color grades：提出并预览 —— 灰世界的 "correction" 会毁掉有意为之的 sunset 或 neon 观感）。

到哪里查找 — 只读取任务需要的文件

| 任务 | 读取 | | ------------------------------------------------------------------------- | -------------------------------- | | resolve / reuse / adopt / ingest、flags、cascade、inventory | references/resolve.md | | color grading、LUTs、smart grade（--for）、grade-compare | references/grading.md | | voiceover / TTS、music、SFX、captions、transcription（audio engine） | references/audio.md | | cut / reframe / transform 现有媒体、exact error diffusion、HEVC | references/operations.md | | source-aware creative treatments、realtime effects、overlays、reveals | references/media-treatments.md | | install + auth、provider table、RAM ladders、--local-only、--provider | references/setup-providers.md | | 记忆偏好 + 冻结 recipes（user memory） | references/memory.md | | ownership matrix、usage stats、telemetry、privacy（maintainer-facing） | references/meta.md |