When to Use

The user wants a video made from an idea ("幫我做一支 30 秒介紹台灣茶的影片", "拍一段古裝武打片", "做個產品廣告"). They only state the intent: you make every craft decision and deliver out/final.mp4. Do not use it to edit the user's own camera footage (use ffmpeg directly for that).

The easiest way: the fixed workflow (prefer this)

run_workflow(name="video-production", inputs={"intent": "<the user's request, in their words>"}, wait=false)

Optional inputs: aspect (16:9 / 9:16 / 1:1), length (e.g. "30 秒"), draft_only (true = faster, no final render), kit (path of a production kit zip from an earlier film) and kit_mode (series = same characters/look, new story; remake = same film, change only what is asked).

The workflow then runs on its own:

1. A planner writes and checks the whole plan (script, profiles, locations, shots).
2. It renders and QCs drafts and makes a draft preview.
3. It asks the user to approve the costly final render. A "no" delivers the drafts.
4. It renders the final version and assembles it.
5. It exports the production kit out/<title>-kit.zip next to the film.

After starting it, tell the user it is running. Progress, the preview, approvals and the finished film all appear in the 工作 tab. You do not need to read the rest of this file unless the user wants to change something by hand.

The short way without the workflow (do exactly this)

1. Write the whole film as ONE JSON file with write_file: videos/<slug>/plan.json. Copy the structure of assets/example-film-duel.json (read it: skill_view(name="ai-video-production", path="assets/example-film-duel.json")). It holds title, genre, aspect, language, style, script.body, subjects (with the four profiling fields), environments and shots.

2. Run the skill on the folder: skill_run(name="ai-video-production", args="videos/<slug>") (no script needed: this runs scripts/run.py, the autopilot).

3. Read the answer's status and act on it:

   status	what you do
   needs_content	Fix plan.json: fill exactly the fields listed in missing, then repeat step 2.
   working	Renders are running on the GPU server. Repeat step 2 with the same args until the status changes (each call works up to ~4 min).
   blocked	Stop and tell the user what to start (the what field, e.g. ComfyUI or an SSH tunnel).
   error	Read error, fix the cause in plan.json, and repeat step 2. Never repeat an identical failing call.
   done	Send the user film (the .mp4 path). Look at the review images with read_file to describe it.

The autopilot does every mechanical step itself:

• narration audio and audio-locked timing;
• prompts and reference sheets;
• draft renders, QC with one automatic retake, final renders;
• assembly, mixing, subtitles and the final QC.

Your job is the content (plan.json) and the conversation with the user.

Rules that prevent the usual mistakes:

• Only plan.json. Put everything in videos/<slug>/plan.json. Other files (characters.txt, script.md…) are ignored.
• Use skill_run. Never run the scripts with shell and never invent commands ("profiling", "render project.json"…).
• What script is. script is only ever a file inside this skill (scripts/….py). Folders and project files go in args.
• Don't stop to ask. Do not stop after a step to ask whether to continue; keep calling until done, blocked or a real question for the user.

Production kit (素材包): export and reuse

Every finished film also produces videos/<slug>/out/<title>-kit.zip. Always give the user both the film and the kit. The kit holds:

In the zip	Content
script.md	劇本
characters.md	人物設定: appearance, wardrobe, the four profiling fields, voice
locations.md	場景設定: description, light, palette, materials
style.md	look, palette, camera habits, music direction, ambience, narrator voice, negative rules
shotlist.md	鏡頭語言: shot size, angle, lens, focus, composition, camera move, action, performance per shot
refs/, keyframes/	character sheets and location masters (the identity anchors), keyframes
audio/voice/, audio/music/	narration/dialogue audio and the background music
bible.json, kit.json	the machine-readable plan with seeds; manifest with checksums

Commands (all with skill_run(name="ai-video-production", script="scripts/kit.py", args="…")):

Goal	args
Export again (e.g. after edits; add --with-film to include the mp4)	export videos/<slug>
Look inside a kit the user attached	show <kit.zip>
Sequel: same characters, places, look, music, voices; new story	import <kit.zip> videos/<new-slug> --mode series
Remake: copy everything, then change what the user asked	import <kit.zip> videos/<new-slug> --mode remake

Using a kit the user gives you:

1. show it.
2. Import it into a NEW folder. --mode series is the default; use --mode remake when the user wants the same film changed.
3. Open the new plan.json. It already holds the kit's subjects, environments and style.
   • series: write the new title, intent, script.body and shots.
   • remake: edit only what the user asked for.
   • Ids: reuse the kit's ids (S1, E1, …) in the shots. Add new subjects or places only with new ids.
4. Run the autopilot as usual.

What stays locked:

• The kit's identity fields, locations, style, music and voices.
• They are restored after every merge (kit.lock.json), so do not try to change them.
• Only if the user explicitly wants a change, import again with --unlock subjects,environments,style (any of these).

The workflow does the same when its kit input is set.

Manual control (optional)

The single steps are separate scripts. Call them as skill_run(name="ai-video-production", script="scripts/<file>.py", args="<command> videos/<slug> …").

Script	Commands
project.py	init, set, merge, remove, timing, prompts, validate, plan
tts.py	<folder> or check
comfy_h3.py	check, sheet, master, keyframe, render, collect, generate
qc.py	project, clip
assemble.py	<folder>
next.py	<folder>: prints the exact next manual call
kit.py	export, import, lock, show (production kit, see above)

Use project.py set videos/<slug> <field.path> <value> for small edits. The field reference is references/project-schema.md.

Pipeline

[1] Script & audio-first timing -> [2] Profiling matrix -> [3] Asset anchors (subject / location / light)
        -> [4] Shot grammar & keyframes -> [5] Camera & subject dynamics (render) -> [6] Post & assembly

Procedure (what to put in plan.json, phase by phase)

1. Brief: decide everything from the intent without asking, unless the subject itself is unclear:

   • genre: film, documentary, vlog, commercial, music or explainer;
   • length: default 20-30 s, max ~60 s;
   • aspect: 16:9 by default, 9:16 for 短影音/Reels/Shorts, 1:1 for feeds;
   • language and tone.

   Put these in plan.json: title, genre, aspect, language, and intent (the user's words).

2. Fill in the rest of plan.json. It covers Phases 1-4 in one file:

   • script.body: the script as text, in the genre's format (references/script-formats.md).
   • subjects[]:
     • name (+ alias = the name you use in English actions), appearance, wardrobe;
     • the four profiling fields capability_ceiling, negative_boundary, linguistic_blueprint, kinematic_signature (references/profiling-matrix.md).
     • Every action you write must respect them.
   • environments[]: description, light (direction and time of day), palette, materials.
   • style: look, palette (3-5 hex colors), camera, motion_strength, ambience, music, negative.
   • shots[], 2-6 s each:
     • group (consecutive shots in one place, ≤ 15 s, rendered together), env, subjects, duration;
     • shot grammar (references/shot-grammar.md): shot_size, angle, lens, focus, composition;
     • action (English, one clear movement), performance, camera_move;
     • narration (voice-over) or dialogue (on camera), plus sfx and music.

3. Run the autopilot (skill_run(name="ai-video-production", args="videos/<slug>")) until done. It performs, in order:

   • tts.py for narration and dialogue, then project.py timing (audio-first shot lengths);
   • project.py prompts;
   • comfy_h3.py sheet / master for recurring subjects and locations;
   • comfy_h3.py render --quality draft, then qc.py project;
   • the final render, then assemble.py, then the final QC.

   Also:

   • Look at images. After sheet, keyframe and QC steps, read_file the images (refs/.png, keyframes/.png, qc/*.jpg) and check them against references/checklist.md.
   • Fix a bad unit. Change its shot fields (fewer moves, simpler action, a different seed or keyframe; see the fix table in references/h3-prompting.md), then comfy_h3.py render videos/<slug> --unit <id> --force.
   • Optional keyframe. For a unit whose opening image must be exact, run comfy_h3.py keyframe videos/<slug> --unit <id> --set before rendering.
   • Long renders. Several minutes per unit is normal. Pass timeout as next.py says. If a call times out, the render keeps going in ComfyUI; run next.py again (it will say collect).

4. Deliver. Send videos/<slug>/out/final.mp4 (and final.srt) and the kit out/<title>-kit.zip, with three lines:

   • what the film shows and its length;
   • what could be changed in another take;
   • that the kit makes a consistent sequel possible.

Gotchas

• H3 clip length:
  • One render (a group) lasts 5.2-15.1 s; shorter groups are rendered at 5.2 s and trimmed.
  • Split groups longer than 15 s.
  • Action and fight scenes: 2-3 s shots, one movement per shot, at most 2 fighters, each holding exactly one weapon. Say the weapon's look in the wardrobe text.
• Keep identity:
  • Same appearance/wardrobe strings in every shot, and the names in actions must match name/alias.
  • Use sheets or keyframes for recurring people.
• No generated text: the model must not draw on-screen text. Titles and subtitles come from post (assemble.py --subs burn).
• Hands, crowds and readable signs deform. Frame them out or keep them simple.
• Real people: never depict real, identifiable people, or make footage that could pass as real news. Label AI recreations in documentaries.

Verification

• next.py reports done: true.
• You looked at every QC sheet.
• out/final.mp4 exists, its duration matches project.py plan total_seconds (±0.2 s), and the user got the path.
• out/*-kit.zip exists and the user got its path too. Check it with kit.py show.