1仕組みと動作原理

核となるのは「単一動詞」の CLI アーキテクチャ：SKILL.md は BGM／SFX／画像／アイコン／ロゴ／音声／カラーグレーディング／LUT の 8 種類のメディア要求をすべて 1 つの `resolve` コマンドに集約。エージェントはユーザーの意図を `--intent` に変換し、検索ノイズはすべてディスクに書き出し、出力は 1 行の結果のみを返します。

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）パスを経由し、heygen CLI の事前インストールおよび OAuth ログイン、ならびに `--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」、画像は「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 にフォールバック。音声は HeyGen TTS またはローカルの Kokoro、画像はローカルの mflux、動画はローカルの 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 のツール一覧を参照）。

ロゴの解決は「svgl → simple-icons → GitHub アバター → ドメインの favicon」チェーンを経由し、決して手描きトレースは行いません。これらはネットワークリクエストを伴う実際のリクエストプロバイダーです（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 やアイコンサービスです。

メディア操作（カット／リフレーム／変形／ダッキング／ラウドネス／字幕分割／誤差拡散／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 コンテンツアドレス指定キャッシュ）。設定やレシピパッケージ全体がプロジェクト単位および個人単位の 2 段階で永続化され、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 イベントにはメディアタイプ／ソース／プロバイダーのみが含まれ、意図テキストやパスは含まれません。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）。これは当スキル内で「デフォルトで外部送信を行う」唯一の経路です。

2コア機能

018 種類のメディアを 1 回の resolve で解決：bgm/sfx/image/icon/logo/voice/grade/lut の統一検索エントリポイント

02素材生成：カタログに存在しない場合、TTS／音楽／画像モデルによるフォールバック生成（HeyGen TTS、Lyria/MusicGen、mflux、LTX）

03共有オーディオエンジン：ボイスオーバー／文字起こし／字幕／背景音除去（audio/ エンジン + heygen-tts + parakeet/whisper）

04メディア操作とトランスコード：カット／リフレーム／変形、高精度な誤差拡散、HEVC、ダッキング、ラウドネス正規化

05プロジェクト間の再利用と記憶：--candidates/--reuse によるグローバルキャッシュの再利用、prefs/recipe によるユーザー好みの保持

06メディア表現機会のスキャン（opportunity pass）：1 回の現状スキャン + 1 回の確認確認。根拠に基づく（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。エージェントが直接実行）
网络端点: 外部ネットワークアクセスの宣言: api.heygen.com/v3（カタログ／TTS／アバター、X-HeyGen-Client-Source: media-use 帰属ヘッダー付き）
本地工作目录: ファイルの読み書きと成果物の出力: プロジェクト内 `.media/`：manifest.jsonl、index.md、preferences.json、recipes/<name>/、素材のローカル保存

監査ノート： 影響範囲は media-use に集中しています：複数ソースからの認証情報の読み取り（環境変数 API キー、直近の .env、~/.heygen credentials、OAuth セッション）、複数のサードパーティエンドポイントへの外部送信（HeyGen API、Google Lyria、PostHog テレメトリ、ロゴ CDN、モデルダウンロード）、および必要に応じた pip/uv/git によるサードパーティ製ローカルモデルのインストール。緩和策：HeyGen の無料利用 OAuth パスをデフォルト採用、ローカルモデルはオプトイン制、--local-only による完全オフライン対応、SSRF 対策の単体テスト実施、テレメトリの無効化対応および送信内容の粗粒度化、有料呼び出し前のエージェント確認必須化。トリガー条件：ユーザーが 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 容量に応じた分類により低スペック環境でも実行可能なサブセットを提供

規律あるメディア表現の提案：根拠に基づき、確認は一度のみ、暗黙の変更は決して行わない設計で、エージェントが独断で演出を追加するのを防止

明確なコストガードレール：エージェント起点の有料生成には事前確認を必須とし、クライアント帰属ヘッダーを付与して呼び出し

最適な用途： HyperFrames プロジェクト（または任意の HTML-to-video ワークフロー）において、メディアアセットの「検索／生成／編集／記憶」を必要とするエージェントセッションに最適：製品ビデオ、解説動画、BGM／SFX／ナレーション／アイコンを要するコンテンツ制作。また、「プロバイダー API、ローカルモデル、記憶、テレメトリを組み合わせて単一のテスト可能な CLI スキルを構築する方法」を研究したい開発者のリファレンスとしても適しています。

不向きな用途： ネットワークなし／認証情報ゼロの完全な隔離環境（--local-only を指定しローカルモデルを事前インストールするか、プロバイダー不要の純粋なオーケストレーションスキルを選択すべきです）。外部送信やアカウント連携を一切望まないユーザー（テレメトリの手動無効化が必要）。メディア処理はおまけ程度でプロンプトの指示のみで十分とする軽量な用途（本スキルは CLI、アカウント、ffmpeg の依存関係を前提とします）。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload media-use.tar.gz

sha256: e19482b5849526de…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit b8328f9573.