zz-mv-gongzuotai · 單 skill 的 MV 專案統籌

定位

這是整個 MV 專案的唯一入口 skill。
工作台只展示與統籌；生成由 agent 呼叫本 skill 的 scripts/ 完成。
流程到影片段落結束：不粗剪、不拼片、不做成片；影片段落 + handoff 交給下一階段剪輯。

命令裡的 mvwb 指安裝後的全局命令；如果 ~/.local/bin 不在 PATH，用 ~/.agents/skills/zz-mv-gongzuotai/start/mvwb（安裝時已複製並加執行位）；如果仍不可用，用 python3 ~/.agents/skills/zz-mv-gongzuotai/scripts/mvwb.py。

工作台與 Key（硬規則）

工作台是專案裡的靜態 workbench.html：直接雙擊/用瀏覽器打開 file://...；不啟動任何背景服務。
禁止 mvwb server、python -m http.server、埠、服務版。工作台是純查看頁，沒有任何設定入口。
使用者說「開啟工作台」：執行 mvwb open [--workspace NAME]，它只開啟本地 HTML。
初期只發 Router Key：學生把老師發的 zz-keys.json 放到專案根目錄（裡面通常只有 {"router": "..."}）；agent 執行 mvwb keys import --file <項目>/zz-keys.json --delete-source。匯入一次即全局生效，發放檔案匯入後刪除。
Key 不經過工作台：使用者匯入 zz-keys.json、雙擊 start/setup-keys.*，或終端 mvwb keys set；agent 執行 mvwb keys import --file <path> --delete-source。agent 只引導，不索要 Key；非互動環境不要呼叫 keys set。
備用 Key 走 B001 提醒：Router 同 10 分鐘內連續 ≥3 次失敗且未配備用時，agent 產生 B001 提醒塊；學生把提醒原文轉發給老師，由老師決定是否發放備用 zz-keys.json（含 runninghub/apimart 欄位）。發放後匯入即啟用，並重新整理餘額/工作台。agent 可用 mvwb keys watch 免二次對話。
提醒格式統一：所有失敗/阻塞/警告走 scripts/alerts.py（程式碼表見 references/alerts.md），學生只需整塊轉發提醒原文。禁止直接說「找老師要備用 Key」這類話；備用 Key 一律透過 B001 提醒由老師決定。
Key 不寫進 DATA、HTML、腳本、日誌或螢幕截圖；下載的匯入檔案匯入後必須刪除。使用者已經把 Key 發到對話裡時，提醒他作廢重發。
餘額/成本只看 Router（人民幣）：頂部只顯示 Router 餘額；所有成本折算為 ¥ 寫進 DATA（RunningHub 幣→CNY 匯率在 config/models.json 的 fx.rh_coin，由老師維護）。
每次產生/替換檔案後：更新 data.json → mvwb build → mvwb check --data ...。check 報缺失就是工作台不會顯示，不能算完成。

最終交付

每個 MV 一個目錄，音樂、資產、影片段落都在裡面：

workspaces/<project>/
├─ 原文/
│  ├─ lyric_original.md      甲方歌詞原文
│  ├─ story_script.md        甲方故事腳本原文（不拆鏡）
│  └─ lyric.json             L01… 行號映射
├─ workbench.html            專案工作台（唯讀展示 + 本地 Key 匯入）
├─ data.json                 工作台資料源（agent 更新）
└─ 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。每一步固定五件事：

步驟	先問（缺失才問）	產物	自檢	門
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。
自檢必須真跑並引用結果；失敗停在當前步，不靜默進入下一步。

四步

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 # 需要範例時：複製完整 demo
# 填 workspaces/my_project/原文/ 後，讓 agent 產生空工作台

Agent 用 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 條）。
每條多長？ 預設 30s（15/30/45/60s）。
什麼風格？ 預設按參考包（3D 皮克斯 / 真人短劇 / 日系治癒 / 甲方參考片）。
比例？ 預設 9:16 豎屏（1080×1920）。
人物/場景/產品參考？ 有圖給圖，沒有用文字描述。
預算上限？ 沒給就先報價，不提交。

輸出只回：產物路徑 + 自檢結果 + 這 7 項確認。門：批次參數確認。 此步不花錢。

時長契約（使用者目標 vs 音樂實際）

時長	誰定	用途
`target_duration`	使用者在第 2 步設定（如 45s）	音樂請求秒數、MV 總目標時長、預算/段數、框架計畫
`actual_duration` / `timeline_v1.json`	音樂產生後讀取	分鏡/影片段落實際時長、Muse `seconds`、H3 幀數、handoff

總時長按使用者設定：音樂產生時把 target_duration 傳給 ACE 的 116:value；框架的總時長、段數、預算都按它規劃。
每段時長按音樂實際：音樂出來後讀 actual_duration 和逐句 timeline，更新分鏡/影片段落的 duration；影片段落按實際句長產生，不按計畫時長硬切。
偏差處理：實際與目標差 >1s 或 >2% 時暫停，讓使用者選「接受實際 / 重產生音樂 / 後期裁」；不要偷偷用計畫時長產生影片。
只選影片沒音樂：先用 target_duration 做 provisional 計畫；補音樂後所有影片段落標記 stale，按實際時間軸重跑。
這樣既尊重使用者設定的總時長，又保證畫面與音樂逐句對齊。

Step 3 · MV 文字框架

建立 MV001…MV00N，每條：

比例預設 9:16 豎屏（工作台按 1080×1920，Muse 輸出 720×1280）；使用者明確指定才改。
先寫 genome：cast_id/outfit_id/face_seed、story_id、music、visual、edit；規則見 references/variation.md。同批任意兩條至少 3 個維度不同，禁止同一角色+同一穿搭、同一故事矛盾、同一 genre+BPM+vocal、同一場景包。
輸出一張差異化表（每條的 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

缺 Key / 餘額不足 / 查詢失敗：停。報價 = 數量 × 單價；使用者確認才跑。

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 差異化；資產鎖定前抽查兩條，避免「同一個人換件衣服就算新 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。
使用者說「定稿/通過」 → 對應 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`
四步執行契約	—	`references/step-contract.md`
變體/差異化/去重	—	`references/variation.md`
Key 發放/匯入	—	`references/key-distribution.md`
提醒/報警程式碼表	—	`references/alerts.md`
角色卡/風格/帥哥美女/治癒系	—	`references/prompts/casting-style.md`
交付欄位	—	`references/handoff.md`

影片按段確認模型；不同段可不同模型，但同一 MV 風格包/調色統一。
多參考圖：角色三視圖（不要四視圖）/場景板/道具/產品實拍；一圖一職；先跑 1 段樣板。

Key

唯一真源：~/.config/mv-workbench/keys.json（0600）。
設定：mvwb keys set runninghub、mvwb keys set router（終端隱藏輸入）。
餘額：mvwb keys balance --data workspaces/<project>/data.json → mvwb build。
原始 Key 不進 HTML/DATA/日誌；DATA.keys 只有遮罩和餘額快照。
產生命令統一經 mv_keys.py exec 注入；不要依賴 shell 殘留 Key。

常用命令

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 命令、一鍵配 Key
scripts/          mvwb、keys、alerts、build、timeline、providers
references/       workbench 契約、step 契約、提醒程式碼表、提示詞、provider
templates/        workbench.html
contracts/        timeline/storyboard/segments/mv 契約
demo/             原創 demo（可直接開啟）
config/           模型價格 / fx 匯率 / keys 範例
workspaces/       學生專案（每個專案一個目錄）

版本

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 精簡——移除頁內 Key 設定；餘額只顯數值不顯遮罩；刪 MV 頭部累計標誌；音樂/資產空態對齊；頁面「唯讀」字樣全部移除；頂欄順序產生時間→餘額。
v0.4.2（2026-11-14）：目錄重排歸類——入口類（安裝/mvwb/setup-keys）收進 start/，開發者檔案收進 dev/ 與 docs/；Key 範例改名 config/zz-keys.example.json；根目錄只留 SKILL/README/LICENSE/NOTICE。
v0.4.2（2026-11-14）：目錄歸類——入口類收進 start/，開發檔案收進 dev/、docs/；根目錄只留 4 個檔案；Key 範例改名 config/zz-keys.example.json。
v0.4.1（2026-11-14）：統一提醒格式（scripts/alerts.py + references/alerts.md 程式碼表）；備用 Key 改為 B001 提醒轉發給老師；keys/providers/check/build 全量接入；手冊新增「把提醒原文發給老師」。（2026-11-14）：Router 主鏈 + 備用 Key 按需發放；頂部只顯示 Router 餘額；成本一律折算 ¥（fx.rh_coin）；keys 層支援 apimart 獨立段；quote 輸出折算人民幣。
v0.3.9（2026-11-14）：老師發放的 Key 檔案統一命名為 zz-keys.json；watcher 同時識別 mv-keys-import*.json 和 zz-keys.json。
v0.3.8（2026-11-14）：發放 Key 的 JSON 簡化為兩個欄位 {"runninghub":"...","router":"..."}；issued_to/expires_at/mv_keys_import 改為可選，只在登記或 watcher 自動拾取時需要。
v0.3.7（2026-11-14）：新增老師發放 Key 的標準：zz-keys.json 放專案根目錄，keys import --delete-source；格式範例與發放規則見 references/key-distribution.md。
v0.3.6（2026-11-14）：新增 mvwb keys watch；agent 先監聽下載目錄，使用者在工作台填 Key 並下載後自動匯入/刪除，可選重新整理餘額並重建工作台。
v0.3.5（2026-11-14）：工作台右上角「設定 Key」本地填 Key → 下載 mv-keys-import.json → agent 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-13）：新增變體/差異化規則與角色風格提示詞包（小紅書穿搭/日系甜妹/韓系歐巴/治癒系電影/帥哥美女）；Step 3 要求 genome 與差異化表。
v0.3.2（2026-11-13）：與使用者手冊對齊：Key 由使用者本機輸入；補專案名/三步確認、音樂鎖定與時長偏差、資產 QA、大改報價、data.json 目錄。
v0.3.1（2026-11-13）：安裝升級保留 workspaces；init 預設空專案（--demo 複製 demo）；build/check 相對路徑回退 skill 根目錄；精簡包內文件。
v0.3.0（2026-11-13）：移除背景服務，工作台回歸純靜態；Key/餘額改 CLI；新增四步執行契約與 mvwb check；修復透傳參數。

zz-mv-gongzuotai

zz-mv-gongzuotai 是什麼？

在你喜歡的 AI 中提問

說明文件