zz-mv-gongzuotai · シングルスキルの MV プロジェクト統括

位置づけ

これは MV プロジェクト全体の唯一のエントリースキルです。
ワークベンチは統括情報の表示のみ行います。生成処理はエージェントが本スキルの scripts/ を呼び出して実行します。
フローはビデオセグメントで終了します。粗編集、結合、完成版は作りません。ビデオセグメント + handoff は次の段階の編集に引き継ぎます。

コマンド内の mvwb はインストール後のグローバルコマンドです。~/.local/bin が PATH にない場合は、~/.agents/skills/zz-mv-gongzuotai/start/mvwb（インストール時にコピーされ実行権限が付与されます）を使用します。それでも使えない場合は、python3 ~/.agents/skills/zz-mv-gongzuotai/scripts/mvwb.py を使用します。

ワークベンチとキー（ハードルール）

ワークベンチはプロジェクト内の静的な workbench.html です。ダブルクリックまたはブラウザで file://... を直接開きます。バックグラウンドサービスは一切起動しません。
禁止: mvwb server、python -m http.server、ポート、サービス版。ワークベンチは純粋な閲覧ページであり、設定の入り口はありません。
ユーザーが「ワークベンチを開いて」と言った場合: mvwb open [--workspace NAME] を実行します。ローカルの HTML を開くだけです。
初期は Router キーのみ配布: 学生は教師から送られた zz-keys.json をプロジェクトのルートディレクトリに配置します（通常 {"router": "..."} のみ）。エージェントは mvwb keys import --file <プロジェクト>/zz-keys.json --delete-source を実行します。一度インポートすればグローバルに有効になり、配布されたファイルはインポート後に削除されます。
キーはワークベンチを経由しません: ユーザーは zz-keys.json をインポートするか、start/setup-keys.* をダブルクリックするか、端末で mvwb keys set を実行します。エージェントは mvwb keys import --file <path> --delete-source を実行します。エージェントは導線を提供するだけで、キーを要求しません。非対話環境では keys set を呼び出さないでください。
予備キーは B001 アラート経由: Router が同じ10分以内に連続3回以上失敗し、かつ予備キーが設定されていない場合、エージェントは B001 アラートブロック を生成します。学生はアラート原文をそのまま教師に転送し、教師が予備の zz-keys.json（runninghub/apimart フィールドを含む）を発行するかどうかを決定します。発行後、インポートするとすぐに有効になり、残高/ワークベンチが更新されます。エージェントは mvwb keys watch を使用して2回目の対話を省略できます。
アラート形式は統一: すべての失敗/ブロック/警告は scripts/alerts.py（コード表は references/alerts.md）を経由します。学生はアラート原文をブロックごと転送するだけで済みます。「教師に予備キーをもらってきて」などの直接的な表現は禁止。予備キーは一律 B001 アラートを通じて教師が判断します。
キーは DATA、HTML、スクリプト、ログ、スクリーンショットに書き込んではいけません。ダウンロードしたインポートファイルはインポート後に必ず削除します。ユーザーがすでにキーを会話に送信してしまった場合は、無効にして再送信するよう促します。
残高/コストは Router（人民元）のみ: 上部には Router の残高のみを表示します。すべてのコストは人民元換算で DATA に書き込みます（RunningHub コイン→CNY のレートは config/models.json の fx.rh_coin にあり、教師が管理します）。
ファイルを生成/置換するたびに: data.json を更新 → mvwb build → mvwb check --data ... を実行します。check で不足ファイルが報告されたら、ワークベンチに表示されないため、完了とは見なせません。

最終成果物

MV ごとに1つのディレクトリに、音楽、アセット、ビデオセグメントを格納します:

workspaces/<project>/
├─ 原文/
│  ├─ lyric_original.md      クライアント歌詞原文
│  ├─ story_script.md        クライアントストーリースクリプト原文（カット分割しない）
│  └─ lyric.json             L01… 行番号マッピング
├─ workbench.html            プロジェクトワークベンチ（読み取り専用表示 + ローカルキーインポート）
├─ data.json                 ワークベンチデータソース（エージェントが更新）
└─ MV001/
   ├─ mv_manifest.json       ステージ状態/バージョン/コスト
   ├─ 00_framework.md        音楽/アセット/セグメント計画
   ├─ 01_music/
   │  ├─ song_v1.mp3
   │  └─ timeline_v1.json    各行の開始・終了秒（セグメント分割/引き渡し用）
   ├─ 02_assets/
   │  ├─ assets_v1.json
   │  ├─ role_xxx.png
   │  ├─ scene_xxx.png
   │  └─ prop_xxx.png
   ├─ 03_segments/
   │  ├─ segments_v1.json    G1/G2… 現在のバージョン + 履歴
   │  ├─ G1_v1.mp4
   │  ├─ G1_v2.mp4           審査で再実行された履歴
   │  └─ G2_v1.mp4 …
   └─ handoff_v1.json        編集に渡す一覧

handoff_v1.json は編集に必要なフィールドのみを含みます:

{
  "mv_id": "MV001",
  "status": "ready",
  "segments": [
    {
      "segment_id": "G1",
      "line_ids": ["L01", "L02"],
      "music_start": 0.0,
      "music_end": 6.0,
      "duration": 6.0,
      "video_file": "03_segments/G1_v1.mp4",
      "model": "muse-video-ext",
      "resolution": "720x1280",
      "notes": "審査通過の現在バージョン"
    }
  ]
}

実行契約（各ステップで必須）

詳細な入力/出力/自己チェックは references/step-contract.md を参照。各ステップは固定の5項目:

ステップ	最初に質問（不足時のみ）	成果物	自己チェック	ゲート
0 初期化	プロジェクト名、数量、長さ、スタイル、アスペクト比、予算	workspace + `data.json` + `workbench.html`	`mvwb check` = 0 不足	パラメータ確認
1 原文	歌詞/スクリプトファイル	`原文/*` + `lyric.json`	行数/id 連続性/カット未分割	原文確認
2 空ワークベンチ	バッチパラメータ	DATA + 静的 HTML	build + check + ダブルクリックで開ける	ワークベンチ確認
3 フレームワーク	審査意見	manifest + framework + segments	長さ/行漏れ/セグメント≤10s	フレームワーク確認 + 見積もり
4 生成	指定項目	音楽/アセット/ビデオセグメント/handoff	ファイル存在/長さ/QA/タイムライン	項目ごとに locked

会話出力は「結論 + 成果物パス + 自己チェック結果 + 確認待ち」に統一します。JSON 全体を貼り付けません。
自己チェックは必ず実際に実行し、結果を引用します。失敗した場合は現在のステップに留まり、静かに次のステップに進みません。

4つのステップ

Step 1 · 原文

まず 原文/、甲方資料/、輸入/ の下にある歌詞/スクリプトを探します。ファイル名に 歌詞、lyric、脚本、script が含まれているものを探します。
見つかったら読み込んでデータベースに格納するだけで、書き換えたり、行を分割したり、「最適化」したりしません。
見つからなかった場合: まずユーザーにクライアント資料があるかどうかを尋ねます。なければ、製品/ストーリー/人物/スタイル/長さ/参考情報に基づいて誘導し、下書きを生成します。
格納:

原文/lyric_original.md   曲名/メインパート/サビ、原文
原文/story_script.md     ストーリースクリプト原文、カット分割しない
原文/lyric.json          L01… 行番号マッピング

ゲート: 原文確認。 ユーザーが「問題ない/このバージョンで」と言ったらロックします。原文を変更 = ワークベンチを最初からやり直し。

Step 2 · 空ワークベンチ

mvwb init my_project          # 空プロジェクト: 原文/ は未記入、mvs=[]、workbench.html を生成済み
mvwb init demo_project --demo # サンプルが必要な場合: 完全なデモをコピー
# workspaces/my_project/原文/ に記入後、エージェントに空ワークベンチを生成させる

エージェントは templates/workbench.html + DATA.json を使って再構築:

python3 scripts/build_workbench.py \
  --template templates/workbench.html \
  --data workspaces/my_project/data.json \
  --out workspaces/my_project/workbench.html

静的ワークベンチを開く:

mvwb open --workspace my_project

生成後、立ち止まって質問します（不足しているものがあればそれぞれ質問し、各項目にデフォルト値を提示します）:

プロジェクト名は何ですか？ デフォルトは顧客名/日付。
一度に何本生成しますか？ デフォルトは1本のサンプル（最初は1～5本を推奨）。
各MVの長さは？ デフォルトは30秒（15/30/45/60秒）。
どんなスタイルですか？ デフォルトは参考パッケージ（3Dピクサー / 実写ショートドラマ / 和風癒やし系 / クライアント参考作品）。
アスペクト比は？ デフォルトは9:16縦長（1080×1920）。
人物/シーン/製品の参考画像は？ 画像があればその画像、なければテキストで説明。
予算上限は？ 指定がなければ、まず見積もりを提示し、提出はしません。

出力は次のみ: 成果物パス + 自己チェック結果 + これら7項目の確認。ゲート: バッチパラメータ確認。 このステップでは費用は発生しません。

長さの契約（ユーザー目標 vs 音楽実際）

長さ	誰が決める	用途
`target_duration`	ユーザーがStep 2で設定（例: 45s）	音楽要求秒数、MV 総目標時間、予算/セグメント数、フレームワーク計画
`actual_duration` / `timeline_v1.json`	音楽生成後に読み取り	絵コンテ/ビデオセグメント実際時間、Muse `seconds`、H3 フレーム数、handoff

総時間はユーザー設定に従う: 音楽生成時に target_duration を ACE の 116:value に渡します。フレームワークの総時間、セグメント数、予算はすべてこれに基づいて計画します。
各セグメントの長さは音楽実際に従う: 音楽が出来上がったら actual_duration と各行の timeline を読み取り、絵コンテ/ビデオセグメントの duration を更新します。ビデオセグメントは実際の歌詞の長さに基づいて生成し、計画時間で強制的にカットしません。
偏差の処理: 実際と目標の差が >1秒または >2% の場合、一時停止し、ユーザーに「実際の長さを受け入れる / 音楽を再生成する / 後で編集で調整する」を選択させます。こっそり計画時間でビデオを生成しないでください。
ビデオのみで音楽がない場合: まず target_duration で暫定計画を作成します。音楽が追加された後、すべてのビデオセグメントを stale とマークし、実際のタイムラインに基づいて再実行します。
これにより、ユーザーが設定した総時間を尊重しつつ、画面と音楽が各行で一致することを保証します。

Step 3 · MV テキストフレームワーク

MV001…MV00N を作成します。各MV:

アスペクト比のデフォルトは9:16縦長（ワークベンチは1080×1920、Muse 出力は720×1280）。ユーザーが明示的に指定した場合のみ変更します。
まず genome を書く: cast_id/outfit_id/face_seed、story_id、music、visual、edit。ルールは references/variation.md を参照。同じバッチ内の任意の2つのMVで少なくとも3つの次元が異なる必要があります。同一キャラクター+同一衣装、同一ストーリーの矛盾、同一 genre+BPM+vocal、同一シーンパッケージは禁止です。
差分表を1つ出力します（各MVの cast/story/music/visual/edit）。重複する組み合わせがあれば停止し、プール内の次のものを使用します。作業を開始しないでください。
mv_manifest.json: stages はすべて not_started。genome、cost/spent=0。
00_framework.md: 音楽計画、アセット一覧、標準絵コンテ、ビデオセグメント計画。ここでの duration は計画値であり、target_duration を総目標とします。
アセット一覧はユーザーが審査するためのものです: 人物三面図/シーン空ショット/小道具。これにより、後続のビデオの一貫性を固定します。オプションではありません。ユーザーに「アセット図がないと、各ビデオの人物/シーンが変わってしまいます」と説明します。
03_segments/segments_v1.json: まず計画を書き込み、videos: []とします。
DATA.mvs を更新: 音楽/アセットは空、絵コンテ/セグメントは計画あり。keys スナップショットを保持します。

ユーザーにフレームワークの概要を見せます:

フレームワークに変更はありますか？どの MV、どのカット、どの行を変更しますか？指定された部分のみ変更します。

ゲート: フレームワーク審査通過 + 生成範囲/見積もり確認。

Step 4 · 生成と審査

4.0 事前チェック

mvwb keys status
mvwb keys import --file workspaces/my_project/zz-keys.json --delete-source
mvwb keys watch --timeout 600 --data workspaces/my_project/data.json
mvwb keys balance --data workspaces/my_project/data.json
mvwb quote --model muse-video-ext --seconds 2

キー不足 / 残高不足 / クエリ失敗: 停止。見積もり = 数量 × 単価。ユーザーが確認してから実行します。

4.1 順序: 音楽 → タイムライン → アセット → ビデオセグメント

ステップ	コマンド	成果物
音楽	`mvwb rh --app 2075301815628943362 ...`	`01_music/song_v1.mp3`
タイムライン	`mvwb timeline ...`	`01_music/timeline_v1.json`
アセット	`mvwb rh --app 2116462203997081601 ...`	`02_assets/*` + `assets_v1.json`
H3 ビデオ	`mvwb rh --wf 2110943749894402050 ...`	`03_segments/G*_v1.mp4`
Muse ビデオ	`mvwb muse --prompt ... --seconds N --size 720x1280 --out ...`	`03_segments/G*_v1.mp4`
音楽/アセット（Router）	`tokentech_task.py music	image ...`（プロトコルは` references/providers/router.md` 参照）
成果物	`handoff_v1.json` を書き込む	編集に渡す

音楽を最初にロック。実際の duration/timeline を読み取り、セグメント長を更新します。アセットは参考パッケージに従います。ビデオセグメントは実際の歌詞の長さに基づいて各セグメントを生成します。
アセットはキャラクターカードに基づいて生成: キャラクター三面図は references/prompts/casting-style.md のテンプレート + スタイルパッケージを使用します。MOSS のルールは、左枠が顔、中央枠が全身だが頭部は完全にフレーム外、右枠が背面です。各キャラクターについてまず4枚の候補を生成し、1枚を選択してからロックします。
同一 MV 内でキャラクターの一貫性を保つ: すべてのアセット/ビデオセグメントは同一の cast_id のキャラクターカードと outfit_id を参照します。着替えはストーリー上必要な場合のみ発生し、記録されます。
MV 間での重複禁止: 同じバッチ内の cast_id、ストーリー、音楽、シーンパッケージは genome に従って差別化します。アセットロック前に2本をサンプリングチェックし、「同じ人物が服を変えただけの新しいMV」を防ぎます。
各セグメントで複数のビデオを生成可能: 現在の最初のもの、履歴に G1_v2.mp4 を追加。
新しいバージョンは *_v{n+1}.json に書き込み、旧バージョンを上書きしません。
stages/status/spent を更新し、DATA を再構築します。
再構築後は必ず自己チェック: mvwb build --data ... --out ... && mvwb check --data ...。不足ファイル数が0でなければならない。そうでなければ、まずパスを修正するか再生成します。
ページは静的 file:// であり、相対パスは workbench.html があるディレクトリを基準とします。手動で絶対パスに変更しないでください。

4.2 審査サイクル

生成が完了しました。どこを変更しますか？どの MV、どのビデオセグメント、どの画像/どの曲を変更しますか？

指定された項目のみ再実行。新しいバージョン + 履歴。
音楽が locked になったら変更不可。音楽を変更 = 新しい MV を作成。
同じバッチ内の音楽はまず近似重複チェック: genre + BPM 帯域 + vocal がすべて同じであってはなりません。最初の10秒が同じ曲に聞こえる場合は music_id を変更します。
アセット qa: pass / warn / fail: fail は必ず再実行。warn はユーザー確認後に使用可能。
アセット変更 → 依存するビデオセグメントを stale とマーク。
絵コンテ/ビデオセグメント計画変更 → 対応するビデオセグメントを stale とマーク。
ユーザーが「確定/OK」と言ったら → 対応する stage を locked に設定。

4.3 引き渡し

すべてのビデオセグメントが locked になったら:

handoff_v1.json（または handoff_v1.csv）を書き込みます。
各セグメントをチェック: video_file が存在する、duration ≤10s、music_start/end がタイムラインと一致する。
プロジェクト終了。編集担当者はビデオセグメントと handoff を受け取り、次の段階に進みます。

次の MV: 同じワークベンチ内で MV002 を続行し、既にロックされた音楽/アセットルールを再利用します。まずフレームワークを出力してから生成します。歌詞/クライアントが変わった場合は mvwb init <プロジェクト名> で新しい workspace を作成し、旧プロジェクトを上書きしないでください。

審査/バージョンルール

状態	意味	UI
`not_started`	未生成	グレーのリング
`draft`	成果物あり、審査待ち	琥珀色のリング
`locked`	確定済み	緑のリング
`stale`	上流が変更されたため、再実行が必要	オレンジのリング
`failed`	失敗	赤のリング

上流が locked でなければ、下流は開始しません。
指定された部分のみ変更。それ以外の文字はそのまま保持します。
履歴は上書きしません。spent は履歴コストを累積します。
ワークベンチにはリングの色のみ表示し、状態テキストは表示しません。

モデルとプロンプトルーティング

段階	デフォルト	参照する reference
音楽 ACE-Step	`2075301815628943362`	`references/prompts/ace.md`
アセット MOSS	`2116462203997081601`	`references/prompts/moss.md`
H3 マルチパラメータビデオ	`2110943749894402050`	`references/prompts/h3.md`
Muse ビデオ（Router）	`muse-video-ext`	`references/prompts/muse.md`
S2V リップシンク	`1979183169033375745`	`references/prompts/h3.md`
RunningHub API	—	`references/providers/runninghub.md`
Router API/残高	—	`references/providers/router.md`
ワークベンチ DATA 契約	—	`references/workbench-contract.md`
4ステップ実行契約	—	`references/step-contract.md`
バリエーション/差別化/重複除去	—	`references/variation.md`
キー配布/インポート	—	`references/key-distribution.md`
アラート/エラーコード表	—	`references/alerts.md`
キャラクターカード/スタイル/イケメン美女/癒やし系	—	`references/prompts/casting-style.md`
引き渡しフィールド	—	`references/handoff.md`

ビデオはセグメントごとにモデルを確認します。異なるセグメントで異なるモデルを使用できますが、同じ MV のスタイルパッケージ/カラーパレットは統一します。
複数参照画像: キャラクター三面図（四面図は不可）/シーンボード/小道具/製品実写。1画像1用途。まず1セグメントのサンプルを実行します。

キー

唯一の真のソース: ~/.config/mv-workbench/keys.json（0600）。
設定: mvwb keys set runninghub、mvwb keys set router（端末で非表示入力）。
残高: mvwb keys balance --data workspaces/<project>/data.json → mvwb build。
生のキーは HTML/DATA/ログに入れません。DATA.keys にはマスクと残高スナップショットのみ含まれます。
生成コマンドは一律 mv_keys.py exec を経由して注入します。シェルに残ったキーに依存しないでください。

よく使うコマンド

mvwb doctor
mvwb open
mvwb open --workspace my_project
mvwb init my_project
mvwb keys status
mvwb keys import --file workspaces/my_project/zz-keys.json --delete-source
mvwb keys watch --timeout 600 --data workspaces/my_project/data.json
mvwb keys balance --data workspaces/my_project/data.json
mvwb quote --model muse-video-ext --seconds 2
mvwb build --data workspaces/my_project/data.json --out workspaces/my_project/workbench.html
mvwb check --data workspaces/my_project/data.json
mvwb rh --app <id> --name <tag> --overrides <json> --out <dir>
mvwb muse --prompt "..." --seconds 2 --size 720x1280 --out out.mp4
python3 scripts/providers/tokentech_task.py image --prompt "..." --seed 123 --out out.png
python3 scripts/providers/tokentech_task.py music --lyrics "..." --style "..." --seconds 60 --out out.mp3
mvwb timeline <lyric.json> <audio.mp3> --out <dir>

やらないこと

粗編集、結合、字幕/ミキシング/完成版は作りません。
自動審査は行いません。ユーザーが修正を依頼した場合、指定された項目のみ再実行します。
クライアントの歌詞/スクリプト/素材を公開リポジトリに提出しません。

ファイル

SKILL.md          agent エントリー（このファイル）
start/            人間のエントリー: インストール、mvwb コマンド、ワンクリックキー設定
scripts/          mvwb、keys、alerts、build、timeline、providers
references/       workbench 契約、step 契約、アラートコード表、プロンプト、provider
templates/        workbench.html
contracts/        timeline/storyboard/segments/mv 契約
demo/             オリジナルデモ（直接開くことができます）
config/           モデル価格 / fx レート / keys サンプル
workspaces/       学生プロジェクト（プロジェクトごとに1つのディレクトリ）

バージョン

v0.4.4（2026-11-14）: Router タスクプロトコル実機疎通完了（moss 画像生成 / ace 音楽生成）: POST /v1/responses + metadata.nodeInfoList で RunningHub ノードに直通。scripts/providers/tokentech_task.py を新規追加。長さ/BPM/歌詞/スタイル/ネガティブプロンプト/seed の全パラメータ制御可能。課金は RH 実行時間に基づいて実費控除。
v0.4.3（2026-11-14）: ワークベンチ UI 簡素化 — ページ内キー設定を削除。残高は数値のみ表示、マスクは非表示。MV ヘッダーの累積バッジを削除。音楽/アセットの空状態を統一。「読み取り専用」の文字をすべて削除。上部バーの順序は生成時間→残高。
v0.4.2（2026-11-14）: ディレクトリ再編成・分類 — エントリー系（インストール/mvwb/setup-keys）は start/ に、開発者ファイルは dev/ と docs/ に。キーサンプルは config/zz-keys.example.json に名称変更。ルートディレクトリには SKILL/README/LICENSE/NOTICE のみ。
v0.4.2（2026-11-14）: ディレクトリ分類 — エントリー系は start/ に、開発ファイルは dev/、docs/ に。ルートディレクトリには4ファイルのみ。キーサンプルは config/zz-keys.example.json に名称変更。
v0.4.1（2026-11-14）: アラート形式を統一（scripts/alerts.py + references/alerts.md コード表）。予備キーは B001 アラート経由で教師に転送する方式に変更。keys/providers/check/build の全量接続。マニュアルに「アラート原文を教師に転送」を追加。
（2026-11-14）: Router メインチェーン + 予備キーの必要に応じた配布。上部には Router 残高のみ表示。コストは一律人民元換算（fx.rh_coin）。keys 層は apimart 独立セグメントをサポート。quote 出力は人民元換算。
v0.3.9（2026-11-14）: 教師が配布するキーファイルの名称を zz-keys.json に統一。watcher は mv-keys-import*.json と zz-keys.json の両方を認識。
v0.3.8（2026-11-14）: キー配布用 JSON を2つのフィールド {"runninghub":"...","router":"..."} に簡略化。issued_to/expires_at/mv_keys_import はオプションとし、登録時または watcher の自動取得時のみ必要。
v0.3.7（2026-11-14）: 教師によるキー配布の標準を新設: zz-keys.json をプロジェクトルートに置き、keys import --delete-source でインポート。形式サンプルと配布ルールは references/key-distribution.md に記載。
v0.3.6（2026-11-14）: mvwb keys watch を新規追加。エージェントはまずダウンロードディレクトリを監視し、ユーザーがワークベンチでキーを入力してダウンロードした後、自動でインポート/削除。オプションで残高を更新しワークベンチを再構築。
v0.3.5（2026-11-14）: ワークベンチ右上「キー設定」でローカルに入力したキーが mv-keys-import.json としてダウンロード → エージェントが keys import --delete-source を実行。サーバー不要、ネットワーク不要。
v0.3.4（2026-11-14）: ワンクリック setup-keys（Mac/Win）。keys set は非対話環境では traceback ではなく拒否。ワークベンチのビデオサムネイルに先頭フレームを表示。keys init のプロンプトを --data に変更。
v0.3.3（2026-11-14）: バリエーション/差別化ルールとキャラクタースタイルプロンプトパッケージを新規追加（小紅書コーデ/和風可愛い系/韓流イケメン/癒やし系映画/イケメン美女）。Step 3 で genome と差分表を要求。
v0.3.2（2026-11-14）: ユーザーマニュアルと整合: キーはユーザーがローカルで入力。プロジェクト名 / 3ステップ確認、音楽ロックと長さ偏差、アセット QA、大幅変更時の見積もり、data.json ディレクトリなどを追加。
v0.3.1（2026-11-13）: インストール/アップグレード時に workspaces を保持。init はデフォルトで空プロジェクト（--demo でデモをコピー）。build/check の相対パスは skill ルートディレクトリにフォールバック。パッケージ内ドキュメントを整理。
v0.3.0（2026-11-13）: バックグラウンドサービスを削除し、ワークベンチを純粋な静的ファイルに戻す。キー/残高を CLI に変更。4ステップ実行契約と mvwb check を新規追加。透過パラメータを修正。

zz-mv-gongzuotai · MV プロジェクト統括