zz-mv-gongzuotai · Single Skill MV Project Management

Positioning

This is the single entry point skill for the entire MV project.
The workbench only shows project overview; generation is done by the agent calling this skill's scripts/.
Workflow ends at video segments: no rough cut, no compilation, no final video; video segments + handoff go to the next editing phase.

In commands, mvwb refers to the installed global command. If ~/.local/bin is not in your PATH, use ~/.agents/skills/zz-mv-gongzuotai/start/mvwb (it was copied and made executable during installation). If that still doesn't work, use python3 ~/.agents/skills/zz-mv-gongzuotai/scripts/mvwb.py.

Workbench & Keys (Hard Rules)

The workbench is the static workbench.html in the project: open it directly by double-clicking or via a browser using file://.... Do not start any backend service.
Prohibited: mvwb server, python -m http.server, ports, service versions. The workbench is a pure view page with no configuration entry.
User says "open workbench": run mvwb open [--workspace NAME], which opens the local HTML file.
Initially only the Router Key is distributed: the student places the teacher's zz-keys.json in the project root directory (which usually contains only {"router": "..."}). The agent runs mvwb keys import --file <project>/zz-keys.json --delete-source. Import once, globally effective. The distributed file is deleted after import.
Keys do NOT go through the workbench: the user imports zz-keys.json, double-clicks start/setup-keys.*, or uses the terminal mvwb keys set. The agent runs mvwb keys import --file <path> --delete-source. The agent only guides, never asks for the key. Do not call keys set in non-interactive environments.
Backup keys go through B001 alerts: if the Router fails 3 or more times within 10 minutes consecutively and no backup is configured, the agent generates a B001 alert block. The student forwards the original alert text to the teacher, who decides whether to issue a backup zz-keys.json (containing runninghub/apimart fields). After distribution, import to enable, and refresh balance/workbench. The agent can use mvwb keys watch without a second conversation.
Alert format is unified: all failures/blocks/warnings go through scripts/alerts.py (code table in references/alerts.md). The student only needs to forward the original alert text as a block. Prohibited: directly saying "ask the teacher for a backup key". Backup keys are always decided by the teacher via B001 alerts.
Keys must not be written into DATA, HTML, scripts, logs, or screenshots. Downloaded import files must be deleted after import. If the user has already sent the key in the conversation, remind them to invalidate it and resend.
Balance/cost only looks at Router (CNY): only the Router balance is shown at the top. All costs are converted to ¥ and written into DATA (RunningHub coins to CNY exchange rate in config/models.json under fx.rh_coin, maintained by the teacher).
After each file generation/replacement: update data.json → mvwb build → mvwb check --data .... If check reports missing files, they will not be shown on the workbench, so the task cannot be considered complete.

Final Deliverable

One directory per MV, containing music, assets, and video segments:

workspaces/<project>/
├─ 原文/
│  ├─ lyric_original.md      Original client lyrics
│  ├─ story_script.md        Original client story script (not split into shots)
│  └─ lyric.json             L01… line number mapping
├─ workbench.html            Project workbench (read-only view + local key import)
├─ data.json                 Workbench data source (updated by agent)
└─ MV001/
   ├─ mv_manifest.json       Stage status/version/cost
   ├─ 00_framework.md        Music/asset/segment plan
   ├─ 01_music/
   │  ├─ song_v1.mp3
   │  └─ timeline_v1.json    Start/end seconds per line (for segmentation/delivery)
   ├─ 02_assets/
   │  ├─ assets_v1.json
   │  ├─ role_xxx.png
   │  ├─ scene_xxx.png
   │  └─ prop_xxx.png
   ├─ 03_segments/
   │  ├─ segments_v1.json    G1/G2… current version + history
   │  ├─ G1_v1.mp4
   │  ├─ G1_v2.mp4           History from review reruns
   │  └─ G2_v1.mp4 …
   └─ handoff_v1.json        Manifest for editing

handoff_v1.json contains only the fields needed for editing:

{
  "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": "Current version approved after review"
    }
  ]
}

Execution Contract (Required at Each Step)

See references/step-contract.md for detailed inputs/outputs/self-checks. Each step always involves five things:

Step	Ask First (only if missing)	Product	Self-Check	Gate
0 Init	Project name, quantity, duration, style, aspect ratio, budget	workspace + `data.json` + `workbench.html`	`mvwb check` = 0 missing	Parameter confirmation
1 Source	Lyrics/story script file	`原文/*` + `lyric.json`	Lines continuous/id, not split into shots	Source confirmation
2 Empty Workbench	Batch parameters	DATA + static HTML	build + check + double-click opens	Workbench confirmation
3 Framework	Review comments	manifest + framework + segments	Duration/missing lines/segments ≤10s	Framework confirmation + quote
4 Generate	Named item	Music/assets/video segments/handoff	File exists/duration/QA/timeline	Per-item locked

Dialogue output should be unified as "conclusion + product path + self-check result + pending confirmation", not the full JSON block.
Self-check must actually run and reference the result. If a step fails, stop there; do not silently proceed to the next step.

Four Steps

Step 1 · Source Material

First look for lyrics/scripts under 原文/, 甲方资料/, 输入/. Filenames containing 歌词, lyric, 脚本, script.
If found, read-only import. Do not rewrite, split lines, or "optimize."
If not found: ask the user if there is any client material. If none, guide them based on product/story/character/style/duration/reference to generate a draft.
Import:

原文/lyric_original.md   Song title/verse/chorus, original text
原文/story_script.md   Original story script, not split into shots
原文/lyric.json        L01… line number mapping

Gate: Source confirmation. After the user says "No problem / Use this version", lock it. Changing the source material means restarting the workbench.

Step 2 · Empty Workbench

mvwb init my_project          # Empty project: 原文/ pending, mvs=[], workbench.html generated
mvwb init demo_project --demo # When example needed: copy full demo
# After filling workspaces/my_project/原文/, let the agent generate an empty workbench

The agent rebuilds using 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

Open the static workbench:

mvwb open --workspace my_project

After generation, pause and ask (ask for whatever is missing, provide defaults for each):

What is the project name? Default: client name/date.
How many MVs to generate at once? Default: 1 sample (recommend 1–5 first).
How long per MV? Default: 30s (15/30/45/60s).
What style? Default: based on reference package (3D Pixar / live-action short drama / Japanese healing / client reference video).
Aspect ratio? Default: 9:16 vertical (1080×1920).
Character/scene/product reference? If available, provide images; otherwise, text description.
Budget cap? If not provided, quote first, do not submit.

Output only: product path + self-check result + confirmation of these 7 items. Gate: Batch parameter confirmation. This step costs nothing.

Duration Contract (User Goal vs. Actual Music Duration)

Duration	Who Decides	Use
`target_duration`	User sets in Step 2 (e.g., 45s)	Requested seconds for music, total MV target duration, budget/segment count, framework plan
`actual_duration` / `timeline_v1.json`	Read after music generation	Actual storyboard/video segment duration, Muse `seconds`, H3 frame count, handoff

Total duration follows user input: when generating music, pass target_duration to ACE's 116:value. Framework total duration, segment count, budget are all planned around it.
Per-segment duration follows actual music: after music is generated, read actual_duration and per-line timeline, update storyboard/video segment duration. Generate video segments according to actual line lengths, not by slicing the planned duration.
Deviation handling: if actual differs from target by >1s or >2%, pause and let the user choose "accept actual / regenerate music / edit later". Do not use planned duration to generate video segments secretly.
Only video, no music: first make a provisional plan with target_duration. After music is added, mark all video segments as stale and rerun according to the actual timeline.
This both respects the user's set total duration and ensures visual-audio alignment per line.

Step 3 · MV Text Framework

Create MV001…MV00N, each one:

Default aspect ratio: 9:16 vertical (workbench uses 1080×1920, Muse outputs 720×1280); only change if the user explicitly specifies.
First write the genome: cast_id/outfit_id/face_seed, story_id, music, visual, edit. Rules in references/variation.md. Any two MVs in the same batch must differ in at least 3 dimensions. Prohibit same character + same outfit, same story conflict, same genre+BPM+vocal, same scene package.
Output a differentiation table (cast/story/music/visual/edit per MV). If there is a duplicate combination, stop and pick the next from the pool. Do not start work.
mv_manifest.json: stages all not_started. genome, cost/spent=0.
00_framework.md: music plan, asset list, standard storyboard, video segment plan. duration here is the plan value, with target_duration as the overall goal.
The asset list is for user review: character three-view drawings/scene empty shots/props, to ensure consistency in subsequent videos. Not optional. Explain to the user: "Without asset images, every video's characters/scenes will drift."
03_segments/segments_v1.json: first write the plan, videos: [].
Update DATA.mvs: music/assets empty, storyboard/segments have plan. Keep keys snapshot.

Show the user the framework summary:

Any changes to the framework? Which MV, which shot, which line? Only change what you point out.

Gate: Framework review approval + generation scope/quote confirmation.

Step 4 · Generation & Review

4.0 Pre-check

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

Missing key / insufficient balance / query failure: stop. Quote = quantity × unit price. Run only after user confirmation.

4.1 Sequence: Music → Timeline → Assets → Video Segments

Step	Command	Product
Music	`mvwb rh --app 2075301815628943362 ...`	`01_music/song_v1.mp3`
Timeline	`mvwb timeline ...`	`01_music/timeline_v1.json`
Assets	`mvwb rh --app 2116462203997081601 ...`	`02_assets/*` + `assets_v1.json`
H3 Video	`mvwb rh --wf 2110943749894402050 ...`	`03_segments/G*_v1.mp4`
Muse Video	`mvwb muse --prompt ... --seconds N --size 720x1280 --out ...`	`03_segments/G*_v1.mp4`
Music/Assets (Router)	`tokentech_task.py music	image ...` (protocol in references/providers/router.md)
Delivery	Write `handoff_v1.json`	For editing

Lock the music first; after reading actual duration/timeline, update segment durations. Assets follow the reference package. Video segments are generated per actual line lengths.
Generate assets by character card: character three-view drawings use the template from references/prompts/casting-style.md + style package. MOSS rule: left panel face, middle panel full body but head completely out of frame, right panel back. Generate 4 candidates per character, select 1 then lock.
Consistent character within the same MV: all assets/video segments reference the same cast_id character card and outfit_id. Wardrobe changes only happen when the story requires it, and are recorded.
No duplication across MVs: cast_id, story, music, scene package of the same batch are differentiated by genome. Spot-check two before locking assets to avoid "same person in different clothes = new MV."
Each segment can generate multiple videos: the first is current, history appends G1_v2.mp4.
New versions write *_v{n+1}.json, do not overwrite previous versions.
Update stages/status/spent, rebuild DATA.
After rebuild, must self-check: mvwb build --data ... --out ... && mvwb check --data .... Missing file count must be 0. Otherwise, fix paths or regenerate.
The page is static file://. Relative paths are relative to the directory containing workbench.html. Do not manually change to absolute paths.

4.2 Review Loop

Generation complete? What needs changes? Which MV, which video segment, which image/which song?

Only rerun the named items. New version + history.
Music locked cannot be changed. Changing music = create a new MV.
Within the same batch, music should be approximately de-duplicated: cannot have identical genre + BPM tier + vocal. If the first 10 seconds sound like the same song, change the music_id.
Assets qa: pass / warn / fail: fail must be rerun. warn requires user confirmation before use.
Asset change → video segments dependent on it are marked stale.
Storyboard/video segment plan change → corresponding video segments stale.
User says "finalize/pass" → corresponding stage locked.

4.3 Delivery

After all video segments are locked:

Write handoff_v1.json (or handoff_v1.csv).
Check each segment: video_file exists, duration ≤10s, music_start/end aligned with timeline.
Project ends. The editor takes the video segments and handoff to the next phase.

Next MV: within the same workbench, continue with MV002, reuse locked music/asset rules. Output the framework first, then generate. Change lyrics/client: use mvwb init <project_name> to create a new workspace. Do not overwrite old projects.

Review/Version Rules

Status	Meaning	UI
`not_started`	Not generated	Gray ring
`draft`	Has product pending review	Amber ring
`locked`	Finalized	Green ring
`stale`	Upstream changed, needs rerun	Orange ring
`failed`	Failed	Red ring

If upstream is not locked, downstream does not start.
Only change what is pointed out. Preserve everything else verbatim.
History is not overwritten. spent accumulates historical costs.
The workbench only shows ring colors, not status text.

Model & Prompt Routing

Phase	Default	Reference
Music ACE-Step	`2075301815628943362`	`references/prompts/ace.md`
Assets MOSS	`2116462203997081601`	`references/prompts/moss.md`
H3 Multi-param Video	`2110943749894402050`	`references/prompts/h3.md`
Muse Video (Router)	`muse-video-ext`	`references/prompts/muse.md`
S2V Lip Sync	`1979183169033375745`	`references/prompts/h3.md`
RunningHub API	—	`references/providers/runninghub.md`
Router API/Balance	—	`references/providers/router.md`
Workbench DATA Contract	—	`references/workbench-contract.md`
Four-Step Execution Contract	—	`references/step-contract.md`
Variation/Differentiation/Dedup	—	`references/variation.md`
Key Distribution	—	`references/key-distribution.md`
Alert/Error Code Table	—	`references/alerts.md`
Character Card/Style/Beautiful People/Healing	—	`references/prompts/casting-style.md`
Delivery Fields	—	`references/handoff.md`

Video per segment confirms the model. Different segments can use different models, but the same MV style package/color palette should be unified.
Multiple reference images: character three-view (not four-view)/scene boards/props/product photos. One image per purpose. First run 1 sample segment.

Key

Single source of truth: ~/.config/mv-workbench/keys.json (0600).
Configuration: mvwb keys set runninghub, mvwb keys set router (terminal hidden input).
Balance: mvwb keys balance --data workspaces/<project>/data.json → mvwb build.
Original keys do not enter HTML/DATA/logs. DATA.keys only has mask and balance snapshot.
Generation commands are uniformly injected via mv_keys.py exec. Do not rely on shell-residual keys.

Common Commands

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>

What Not To Do

No rough cut, no compilation, no subtitles/mixing/final video.
No automatic review; when the user requests changes, only rerun the named items.
Do not submit client lyrics/scripts/assets to public repositories.

Files

SKILL.md          Agent entry point (this file)
start/            Human entry point: installation, mvwb commands, one-click key setup
scripts/          mvwb, keys, alerts, build, timeline, providers
references/       Workbench contract, step contract, alert code table, prompts, providers
templates/        workbench.html
contracts/        Timeline/storyboard/segments/mv contracts
demo/             Original demo (can be opened directly)
config/           Model prices / fx exchange rates / keys example
workspaces/       Student projects (one directory per project)

Version

v0.4.4 (2026-11-14): Router task protocol tested end-to-end (moss image generation / ace music generation): POST /v1/responses + metadata.nodeInfoList direct to RunningHub nodes. Added scripts/providers/tokentech_task.py. Duration/BPM/lyrics/style/negative/seed fully parameterized. Billing deducted by RH runtime.
v0.4.3 (2026-11-14): Workbench UI streamlined — removed in-page key configuration; balance shows value only, no mask; removed cumulative badge from MV header; aligned empty state for music/assets; removed all "read-only" text from pages; top bar order changed to generation time → balance.
v0.4.2 (2026-11-14): Directory restructured — entry files (installation/mvwb/setup-keys) moved to start/, developer files moved to dev/ and docs/. Key example renamed to config/zz-keys.example.json. Root directory contains only SKILL/README/LICENSE/NOTICE.
v0.4.2 (2026-11-14): Directory categorization — entry files moved to start/, development files moved to dev/, docs/. Root directory contains only 4 files. Key example renamed to config/zz-keys.example.json.
v0.4.1 (2026-11-14): Unified alert format (scripts/alerts.py + references/alerts.md code table). Backup keys changed to B001 alert forwarded to teacher. keys/providers/check/build fully integrated. Manual updated with "forward the original alert text to the teacher." (2026-11-14): Router main chain + backup keys issued on demand. Only Router balance shown at top. All costs converted to ¥ (fx.rh_coin). keys layer supports apimart independent segment. quote outputs converted CNY.
v0.3.9 (2026-11-14): Teacher-issued key files uniformly named zz-keys.json. Watcher recognizes both mv-keys-import*.json and zz-keys.json.
v0.3.8 (2026-11-14): Issued key JSON simplified to two fields {"runninghub":"...","router":"..."}. issued_to/expires_at/mv_keys_import made optional, only needed for registration or watcher auto-pickup.
v0.3.7 (2026-11-14): Added standard for teacher-issued keys: place zz-keys.json in project root, keys import --delete-source. Format example and distribution rules in references/key-distribution.md.
v0.3.6 (2026-11-14): Added mvwb keys watch. Agent first monitors the download directory. After user fills in key on workbench and downloads, automatically import/delete, optionally refresh balance and rebuild workbench.
v0.3.5 (2026-11-14): Workbench top-right "Configure Key" — fill in locally on workbench → download mv-keys-import.json → agent keys import --delete-source. No service, no network.
v0.3.4 (2026-11-14): One-click setup-keys (Mac/Win). keys set in non-interactive environment rejects with message instead of traceback. Workbench video thumbnail shows first frame. keys init prompt changed to --data.
v0.3.3 (2026-11-14): Added variation/differentiation rules and character style prompt packages (Xiaohongshu outfit / Japanese cute girl / Korean handsome guy / healing film / beautiful people). Step 3 requires genome and differentiation table.
v0.3.2 (2026-11-14): Aligned with user manual: keys entered locally by user. Added project name/three-step confirmation, music lock and duration deviation, asset QA, major change quote, data.json directory.
v0.3.1 (2026-11-14): Installation upgrade preserves workspaces. init defaults to empty project (--demo copies demo). build/check fallback relative paths to skill root directory. Simplified package documents.
v0.3.0 (2026-11-14): Removed backend service, workbench restored to pure static. Keys/balance changed to CLI. Added four-step execution contract and mvwb check. Fixed passthrough parameters.

zz-mv-gongzuotai

What is zz-mv-gongzuotai?

Ask in your favorite AI

Documentation