@starreel/mcp 0.1.222 → 0.1.223

package/SKILL.md

@@ -998,7 +998,11 @@ the frame; writing a marker for an unbound character pulls that character's imag
 in; a `#variant` marker is the only source of that variant image. To take someone
 out of a shot, change `character_ids` (it is a full overwrite — read the current
 list first). If they only speak off-screen, keep them bound and mark them
-`voice_only` through `update_shot`'s `character_presence`. The prompt body
+`voice_only` through `update_shot`'s `character_presence`. Prop images work the
+same way: they follow the shot's `prop_ids`. A prop that the storyboard import
+missed is fixed with `update_shot`'s `prop_ids` (also a full overwrite — read the
+current list, add to it, send the whole list back), not by re-importing the
+episode, which would discard the autofilled fields. The prompt body
 is only the part you write: the platform still layers identity anchors and
 consistency constraints on top at generation time. Editing a prompt does not
 re-generate anything — regenerate the shot afterwards.

package/dist/i18n/tools.en.json

@@ -8,12 +8,12 @@
   "edit_rewritten_script": "★Preferred channel for revisions: edit the AI-rewritten shootable script(write script_content). Free, instant, deterministic—**after one successful rewrite, all modifications go here; do not rerun rewrite_script**(that restarts from raw source, loses fixes, may revert improvements). ★Point-edit method(3 steps, do not skip): ① get_script to fetch **full** rewritten_script; ② **only edit target scenes**—within them change wording/split scenes/delete wrong motif/add [SFX]/move hand-held objects to [道具], and copy all other scenes byte-for-byte including punctuation; ③ submit the **entire** modified script here(this is full overwrite; do not send snippets or let model “also polish” untouched parts). Typical fixes: scene too long/split needed, dialogue line breaks across shots, wrong time/era, motif attached to scene without element, [角色档案] clothing mixed with held object, missing [SFX]/[BGM]. Only edits AI-rewritten output; if rewrite_script has not run, 400—this is not a bypass. Recover with get_script(include_previous=1). Free.",
   "get_script_format_spec": "Fetch the platform-accepted **script format contract**: full markdown template + external_prompt(can forward verbatim to any external AI) + skeleton(with 〈…〉 placeholders) + filled_example. Free · static · no credits. ★Since template v2, **production-layer annotations** are included([角色档案] six-part format/[外貌] line prefix/[道具]/[SFX][BGM][VFX]/motif/fourth lighting segment in scene header/end metadata). v1 only covered story layer, causing external AI drafts to fail checks. When forwarding, **include filled_example**—LLM format accuracy depends on complete examples, not rules. ★Use when client wants to control rewrite degree, use another AI platform, or says “your AI changed my script too much”. ★Two exits(ask client first; determines whether external AI should write annotations): 【A Direct adoption】external AI produces complete script **with production annotations** → check_script_format all green → adopt_external_script as shootable script, no StarReel AI, instant, free, client [角色档案] preserved. For clients requiring zero changes. 【B Send to AI rewrite】external AI produces story layer only(**no annotations**) → set_script as raw → rewrite_script two-pass fidelity to add annotations. ★In B, client-written annotations **are stripped and rebuilt by G1**, so tell external AI not to write them. ★Workflow: ① get external_prompt + filled_example + markdown and send with raw script to other platform; ② run check_script_format on returned draft until errors=0; ③ use adopt_external_script for A, or set_script + rewrite_script for B. ★Contract includes scene header three-part format/location naming/environment first sentence three elements/first-appearance appearance line/sound line prefixes/single-line dialogue length/ban on camera moves and end-credit edit markers, plus four fidelity requirements(keep dialogue line by line, do not drop characters, do not drop action beats, do not add scenes) already in external_prompt.",
   "check_script_format": "**Format self-check before backfill**: run script text against platform rules and return issues. Free · rules-only · no model · no database write · repeatable. ★errors = unconditional rejection(empty/too short/no scene headers/contains camera-move terms/contains end-credit edit markers); must clear before import. warnings = warning by default(strictOnly=true becomes rejection if strict mode enabled): scene too long/short, no sound line, dialogue line over limit, incomplete scene header segments, skipped scene numbers, wrong [角色档案] segment count, profile exists but missing [外貌] line, speaker slot mixed with age/identity. ★placeholder_left(residual 〈…〉 template placeholders) is **error**: system gate may not catch it, but placeholders would enter script as visual content—worse than rejection. ★Scene length counts **story-layer** characters only([角色档案]/[外貌]/[道具]/[SFX] etc. excluded), so full annotations do not push scenes over 120 chars; do not delete annotations just to pass. ★Typical use: external AI draft → self-check → send returned message list back to that platform with “fix only these, copy rest exactly” → check again → all green then set_script. ★Only checks **format**; fidelity like dialogue preservation and missing characters is checked during rewrite_script against original source.",
-  "import_storyboard_table": "【Use for existing storyboard tables】Directly create storyboards from the client’s **finished storyboard table**, skipping rewrite and shot breakdown—no agent in between. Free. ★Three steps, do not import directly: ① get_storyboard_table_spec for template(shot type/camera-move whitelist, body placement, text-card syntax, external AI prompt); ② check_storyboard_table until errors=0 and inspect warnings(missing duration/unrecognized shot type/no visual description are imported as-is); ③ call this tool. ★Use when client provides finished storyboard table(per-shot duration/shot type/camera move, common for TV/brand samples). The set_script→rewrite_script→generate_storyboards path strips production params(test: 8 shots 36s became 20 shots 109s; STYLE blocks/data cards lost). ★Declaration format(one line per shot, fields separated by | or fullwidth ｜): `[镜 001 | 4s | 微距 | 固定]`; also recognizes bold form `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(no need to retype). Order = shot number|duration|shot type|camera move|markers; marker `不切` means must not split further, `★` key shot. Camera move “横移” maps tracking, “摇” maps pan(do not mix; reflections behave differently). `[字卡 9s] line one | line two` creates a text-card shot(final cut renders black card directly, no image/video). ★Props: `[道具] NameA、NameB` binds prop_ids by exact names in drama prop library; prop names fully appearing in body also bind automatically. Receipt prop_names_unresolved lists unbound names(create props first or rename). ★If content omitted, reads episode raw content. If no per-shot declarations, 400(that is a script, use normal breakdown). ★If storyboards already exist, returns 409 with shot count; pass confirm_replace:true only after confirmation(old shots marked deleted, recoverable). Shots missing duration/shot type still import but issues list them—system will not guess; wrong duration means wrong final cut length. ★After import, **auto_complete defaults on**(follows project “auto-fill auxiliary assets” switch): one background batch fills empty professional fields(shot intent/beat/subtext/J-L cut/voice line etc., fill-empty only) and expands platform base description into full image/video prompts. Text step postpaid by token, **tell client before call**. To import only, pass auto_complete:false(**cost: no composition contract generated**—visible count, subject person/partial/prop, shot type inferred only from text; hand insert and offscreen voice shots may render as full characters and fail review. Receipt contract_coverage lists missing shots and current viable fix; follow its note—if contract auto-fill is on, use autofill_storyboards). If auto_complete.started=true, poll get_autofill_status until done(each shot tens of seconds) **before** review_storyboards; autofill changes shots and invalidates prior token.",
+  "import_storyboard_table": "【Use for existing storyboard tables】Directly create storyboards from the client’s **finished storyboard table**, skipping rewrite and shot breakdown—no agent in between. Free. ★Three steps, do not import directly: ① get_storyboard_table_spec for template(shot type/camera-move whitelist, body placement, text-card syntax, external AI prompt); ② check_storyboard_table until errors=0 and inspect warnings(missing duration/unrecognized shot type/no visual description are imported as-is); ③ call this tool. ★Use when client provides finished storyboard table(per-shot duration/shot type/camera move, common for TV/brand samples). The set_script→rewrite_script→generate_storyboards path strips production params(test: 8 shots 36s became 20 shots 109s; STYLE blocks/data cards lost). ★Declaration format(one line per shot, fields separated by | or fullwidth ｜): `[镜 001 | 4s | 微距 | 固定]`; also recognizes bold form `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(no need to retype). Order = shot number|duration|shot type|camera move|markers; marker `不切` means must not split further, `★` key shot. Camera move “横移” maps tracking, “摇” maps pan(do not mix; reflections behave differently). `[字卡 9s] line one | line two` creates a text-card shot(final cut renders black card directly, no image/video). ★Props: `[道具] NameA、NameB` binds prop_ids by exact names in drama prop library; prop names fully appearing in body also bind automatically. Receipt prop_names_unresolved lists unbound names(create props first or rename). ★If content omitted, reads episode raw content. If no per-shot declarations, 400(that is a script, use normal breakdown). ★If storyboards already exist, returns 409 with shot count; pass confirm_replace:true only after confirmation(old shots marked deleted, recoverable). Shots missing duration/shot type still import but issues list them—system will not guess; wrong duration means wrong final cut length. ★★Check bindings first, then auto-complete: re-importing after autofill has run discards the auto-completion results and you pay again. If you are not sure characters/props/scenes will bind by name, import with auto_complete:false → check each shot's character_ids / scene_id / prop_ids from get_storyboards against the **customer's original script/storyboard** (receipt props_possibly_unbound lists shots whose visual text looks like it has an object but has no prop bound) → fix with update_shot → only then quote_autofill / autofill_storyboards. If you find a missing binding after import, fix it with update_shot (prop_ids / character_ids); **do not re-import the episode**. ★After import, **auto_complete defaults on**(follows project “auto-fill auxiliary assets” switch): one background batch fills empty professional fields(shot intent/beat/subtext/J-L cut/voice line etc., fill-empty only) and expands platform base description into full image/video prompts. Text step postpaid by token, **tell client before call**. To import only, pass auto_complete:false(**cost: no composition contract generated**—visible count, subject person/partial/prop, shot type inferred only from text; hand insert and offscreen voice shots may render as full characters and fail review. Receipt contract_coverage lists missing shots and current viable fix; follow its note—if contract auto-fill is on, use autofill_storyboards). If auto_complete.started=true, poll get_autofill_status until done(each shot tens of seconds) **before** review_storyboards; autofill changes shots and invalidates prior token.",
   "get_storyboard_table_spec": "Fetch the platform-accepted **storyboard table format contract**: full markdown template + external_prompt(can forward verbatim to external AI) + skeleton(〈…〉 placeholders) + filled_example + checklist + shot_types(shot-type whitelist) + movements(camera-move whitelist and recognized Chinese forms). Free · static · no credits. ★Use when client has a finished storyboard table(per-shot duration/shot type/camera move) or wants external AI/own tool to format shot design for us—call **before import_storyboard_table**. ★Contract essentials: one shot per line `[镜 001 | 4s | 特写 | 固定]`(bold/fullwidth bars/traditional forms accepted); shot type and camera move only accept whitelist terms(other terms left blank); text after declaration = visual description(at least one line or no image) + `Character: dialogue` + [SFX:]/[BGM:]/[VFX:] tags; full-screen text uses `[字卡 9s] line one | line two`; STYLE/NEG global style blocks **do not go in table**(put in project settings); `## non-scene heading` ends current shot. When forwarding to external AI, **include filled_example**—format correctness comes from examples.",
   "check_storyboard_table": "**Storyboard-table self-check before import**: run the exact same parser as the import endpoint, returning errors / warnings / stats / shots(per-shot parse preview: duration, shot type, camera move, markers, body length). Free · rules-only · no model · no DB write · repeatable. ★errors = import will 400(empty / no per-shot declaration = not a storyboard table) + residual 〈…〉 placeholders; must clear. ★warnings = import proceeds but result lacks data: missing duration(default 4s), unrecognized shot type(blank), unrecognized camera move(blank), no visual description after declaration(dead shot, cannot image), no scene header(no scene binding), data card not using text-card syntax(not in final cut), single shot >15s, STYLE block, duplicate shot numbers—send message list back to external AI and ask it to fix only these. ★If this is green, import_storyboard_table will have no issues(same code).",
   "get_bulk_import_spec": "Get the **bulk-import JSON format contract**: full markdown template + template(placeholder template; every <...> must be replaced) + filled_example(finished reference; copy the structure directly) + external_prompt(task prompt to forward to an external AI/your own tool) + checklist + enums(valid values for mode/role/char_type/shot_type/action_motion_class; same source as validator) + limits(array and field caps). Free · static · no credits. ★When to use: before **bulk_import_storyboards**, when the client can export structured data from their own tool/spreadsheet, or wants an external AI to output JSON that creates this episode’s storyboards in one pass. ★Difference from import_storyboard_table(one text line per shot): use JSON if the data is already structured; use that tool if the client has a text storyboard table. ★Contract basics: top level { mode, episode_meta?, characters?[], scenes?[], storyboards[] }; characters[]/scenes[] are **reference declarations only, not persisted**(characters/scenes/props are extracted from the script by extract_assets; import binds by name to existing assets, so extract first, then import; props are not characters—do not put them in characters[]); storyboards dedupe by storyboard_number; bound_characters references characters[].name(or existing character name in this drama), bound_props references prop names in this drama’s prop library(if omitted, prop names appearing in body text are auto-bound), scene_ref references scenes[] location+time—unresolved references are **silently skipped**; each shot needs at least one of action/description; dialogue is `speaker: line`, no stage directions(they will be spoken); image_prompt/video_prompt may be empty(platform builds a base description from shot size + scene + lighting + action); if supplied, they are used **verbatim** and never overwritten. frame_visual_contract is an internal frame contract and ignored on import.",
   "check_bulk_import": "**Pre-import JSON self-check**: validates with the **same zod schema** as the import endpoint, then converts the import route’s \"silent behavior\" into warnings. Returns errors / warnings / stats(shot count · total seconds · characters · scenes · mode · promptsToBuild). Free · not persisted · repeatable. ★errors = import would 400 or overwrite incorrectly: invalid JSON / schema failure(with per-item path, e.g. storyboards[2].shot_type) / duplicate shot numbers + leftover <...> placeholders; must be zero. ★warnings = import continues but something will be missing or have side effects: unresolved bound_characters/scene_ref(silently skipped) / no action+description(dead shot) / dialogue contains camera language(will be spoken) / single shot >15 seconds / action_overload(too many independent actions for the duration—about 2 beats in 3 seconds, 3 beats in 5 seconds; one main action per shot; split new events into next shot; can ignore if multiple people each do one thing) / shot-number gaps / mode=replace(replaces all storyboards in this episode) / no character binding at all(characters will drift). ★If this is green, bulk_import_storyboards should pass in one call.",
-  "bulk_import_storyboards": "Create/update this episode’s storyboards from one structured JSON payload in a single pass(dedupe/update by storyboard_number). **Does not create characters/scenes/props**—they are extracted from the script by extract_assets; import only binds by name to existing ones(receipt characters_unmatched / char_refs_unresolved lists unbound refs; extract first, then import). Free · deterministic · no AI call. ★Three steps: ① get_bulk_import_spec for contract and finished example; ② check_bulk_import until errors=0; ③ call this tool. ★mode=merge(default) keeps shots not mentioned; mode=replace replaces **all** storyboards in this episode(old shots and generated images/videos are archived and recoverable, not auto-relinked)—replace requires explicit client consent in any execution mode, including autopilot. ★If you want to write image_prompt / video_prompt yourself, put them on each shot; they are used **verbatim and not overwritten**. Empty shots get platform-built base descriptions(receipt base_prompts_built says how many); after import use get_shot_prompts to read and update_shot to edit. (frame_visual_contract is an internal frame contract and ignored on import.) ★After import: speech timing may raise durations for shots whose dialogue does not fit(receipt speech_duration_raised / speech_duration_overflow). ★After import, **auto-completion is on by default**(auto_complete, follows the drama’s \"auto-complete auxiliary assets\" switch, default on): one background batch fills empty professional fields across all shots(AI, fill-empty only) and expands full image/video prompts only for shots with no image_prompt that used a platform base description(client-written prompts are never overwritten; receipt auto_complete.prompt_shots). Text step is postpaid by token; **tell the client before calling**. If you only want import, pass auto_complete:false(**cost: no composition contract is generated**—visible headcount, subject type character/part/prop, and shot size can only be inferred from text; hand insert shots and off-screen narration shots are easily rendered/audited as full characters; receipt contract_coverage lists missing shots **and gives current viable fixes; trust its note**—when contract auto-complete is enabled it calls autofill_storyboards). If receipt started=true, poll get_autofill_status until done **before** review_storyboards.",
+  "bulk_import_storyboards": "Create/update this episode’s storyboards from one structured JSON payload in a single pass(dedupe/update by storyboard_number). **Does not create characters/scenes/props**—they are extracted from the script by extract_assets; import only binds by name to existing ones(receipt characters_unmatched / char_refs_unresolved lists unbound refs; extract first, then import). Free · deterministic · no AI call. ★Three steps: ① get_bulk_import_spec for contract and finished example; ② check_bulk_import until errors=0; ③ call this tool. ★mode=merge(default) keeps shots not mentioned; mode=replace replaces **all** storyboards in this episode(old shots and generated images/videos are archived and recoverable, not auto-relinked)—replace requires explicit client consent in any execution mode, including autopilot. ★If you want to write image_prompt / video_prompt yourself, put them on each shot; they are used **verbatim and not overwritten**. Empty shots get platform-built base descriptions(receipt base_prompts_built says how many); after import use get_shot_prompts to read and update_shot to edit. (frame_visual_contract is an internal frame contract and ignored on import.) ★After import: speech timing may raise durations for shots whose dialogue does not fit(receipt speech_duration_raised / speech_duration_overflow). ★★Check bindings first, then auto-complete: re-importing after autofill has run discards the auto-completion results and you pay again. If you are not sure characters/props/scenes will bind by name, import with auto_complete:false → check each shot's character_ids / scene_id / prop_ids from get_storyboards against the **customer's original script/storyboard** (receipt props_possibly_unbound lists shots whose visual text looks like it has an object but has no prop bound) → fix with update_shot → only then quote_autofill / autofill_storyboards. If you find a missing binding after import, fix it with update_shot (prop_ids / character_ids); **do not re-import the episode**. ★After import, **auto-completion is on by default**(auto_complete, follows the drama’s \"auto-complete auxiliary assets\" switch, default on): one background batch fills empty professional fields across all shots(AI, fill-empty only) and expands full image/video prompts only for shots with no image_prompt that used a platform base description(client-written prompts are never overwritten; receipt auto_complete.prompt_shots). Text step is postpaid by token; **tell the client before calling**. If you only want import, pass auto_complete:false(**cost: no composition contract is generated**—visible headcount, subject type character/part/prop, and shot size can only be inferred from text; hand insert shots and off-screen narration shots are easily rendered/audited as full characters; receipt contract_coverage lists missing shots **and gives current viable fixes; trust its note**—when contract auto-complete is enabled it calls autofill_storyboards). If receipt started=true, poll get_autofill_status until done **before** review_storyboards.",
   "get_autofill_status": "Check progress and receipt of this episode’s background completion batch (import auto_complete / autofill_storyboards AI one-click fill-empty): { status: running|done|failed|idle, total, done, ok, fail, skipped_no_gap, fields_written_counts, contract_coverage }. Free. ★The receipt is the evidence of what completion wrote: it writes internal narrative fields and composition contracts that get_storyboards / get_shot_prompts **do not return**, so seeing no change on read-back is normal—use these counts instead. skipped_no_gap = shots with no gaps that were skipped (no AI call, no charge); fields_written_counts = number of shots written per field name (e.g. {shot_intent: 44}); contract_coverage = {total, missing_contract} = image-generating shots in this episode and how many still lack a composition contract. Counts only, never field contents—tell the customer these numbers as-is. ★After import with auto-complete, wait for status=done before review_storyboards / generate_frames—the batch rewrites shot fields one by one, so any earlier review_token becomes invalid when content changes. Each shot takes tens of seconds; a full episode can take 10+ minutes. Poll interval ≥10 seconds; do not tight-loop. If status=failed or fail>0, inspect fail count; a few failed shots can be rerun with autofill_storyboards (in fill-empty mode, shots already filled are skipped with no AI call and no charge; only unfilled shots are billed).",
   "adopt_external_script": "[Exit A] Adopt a draft produced by an external AI from the template **directly as the shootable script**; StarReel AI does not intervene. Seconds, no charge. ★Hard pre-gate: server first runs a format self-check; non-empty errors return 400 with the list unchanged—use check_script_format until fully green before this tool. warnings do not block(same strictness as default lenient save_script). ★When to use: client demands \"do not change a single word\" and the external AI already produced a complete draft with production-layer annotations. ★When **not** to use: client only organized the story layer(no [角色档案]/[外貌])—direct adoption would leave downstream without character profiles and appearance anchors; use Exit B(set_script + rewrite_script) so the platform adds annotations. ★Difference from edit_rewritten_script: that is a point-edit channel for an **existing rewritten script**(400 if rewrite was never run). This tool is the **first script ingestion** channel, only for \"the script was prepared externally\". It is not a backdoor around rewriting—the server gate decides; if it fails, it fails. Old script is saved into previous_script; if adopted by mistake, recover with get_script(include_previous=1).",
   "extract_assets": "Extract characters/scenes/props from the shootable script (writes three tables in one pass; the foundation for downstream consistency). Backend async; text step postpaid, no arrears. Prerequisite: rewrite_script has produced the rewritten script (mandatory for new projects; character profiles must be extracted from the rewritten script to stay self-consistent with script and storyboards). ★Minute-level backend task; use get_run_status to decide whether it is still running; do not treat 60 seconds as failure.\n★【Rewritten-script review hard gate · free】Before this step, you must call review_script first: report every returned finding to the customer verbatim (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass review_token into this tool. Skipping review will be rejected with 400. If content changed after review → token auto-invalidates; review again once (still free). If there is error, block by default; only if the customer is informed and insists on continuing as-is may you pass acknowledge_review:true—pushing forward with known issues will likely produce unusable footage and is still charged normally (acknowledge_review only means the customer personally agreed; every execution mode still requires explicit customer consent, including managed mode); in managed steps, only allowlisted heuristic error can pass with auto_acknowledge:true (platform decides; if not allowlisted returns 400 AUTOPILOT_MUST_ASK:must_ask_customer=true then pause and ask customer, false = self-fix per action then review again). ★Gray-release dramas also require you (agent) to QC personally: inspect assets item by item per agent_qc returned by review_script, answer the checklist, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; bad report → blocked by default like error).★★【Execution-mode master rules · read before starting】For dramas with a confirmed opening plan, first get_production_plan and read autopilot: pro mode (pro, or autopilot.enabled=false, or no confirmed plan) → every later 'tell customer, proceed only after customer agrees' is literal; one-click (auto) / hybrid (custom) managed steps → do not ask customer: follow get_pipeline_status next_action in order, self-confirm quotes within the hard budget cap, after each layer still run review_* + agent QC, and let review/QC autopilot.next_step tell you how to proceed at this layer (allowlisted error with auto_acknowledge:true / which self-fix round / pause to ask customer); for choices follow autopilot.default_decisions; autopilot.never_auto_actions(mode=replace, deleting assets, overwriting customer-uploaded images, allow_era_ref_conflict, cloning voices, delivery acceptance) always require customer consent in every mode. ★In managed steps, regenerating frames for the same shot (generate_shot_frame) max 3 rounds, regenerating video (regenerate_shot_video / edit_video_shot) max 3 times; at the limit the platform returns 409 AUTOPILOT_SHOT_REGEN_LIMIT (not charged)—do not bypass with another tool; stop and ask customer: if customer approves more, quote normally and pass customer_approved_more_regens:true when generating (grants another limit); if customer accepts current state, continue, and pass acknowledge_review:true on the next paid call to record confirmation. 402 BUDGET_WOULD_EXCEED / 409 MODEL_UNAVAILABLE / 409 AUTOPILOT_SHOT_REGEN_LIMIT / 400 AUTOPILOT_MUST_ASK with must_ask_customer=true / non-empty pending_questions → pause and ask the customer the pending_questions from get_autopilot_log **summarized all at once**; customer-controlled steps follow pro mode. After final output, deliver to customer using the get_autopilot_log report. ★Three-tier execution strategy (do not mix the three when asking customer):①【Basic project settings · free · mandatory foundation · set when creating drama, do not create an empty shell】project_type/setting_brief(worldview · ERA LOCK)/ethnicity/aspect ratio resolution, plus consistency anchors cinematography_prompt(photography DNA)·art_bible(art bible)·visual_lock(visual lock)—all free, foundation for full-pipeline consistency; if not set properly, all later generation drifts and rework costs again. Set directly via create_drama/update_project_settings. ★visual_lock/art_bible only write image-level/world-level locks (shot language · environment · art tone · forbidden elements), **never pin clothing/hairstyle/appearance details for specific characters**—the single source of truth for character appearance is the character profiles produced by extract_assets (change via update_character); writing both places inevitably conflicts, character sheet vs profile, concept image vs visual lock, consistency gate rejects by character sheet → concept images/shot frames get **structurally rejected in chains**, no amount of rerolls passes, pure waste.★★【Era contract · free · required before image generation for non-contemporary or surreal subjects】The worldview in setting_brief is **free text**; it can provide background but cannot constrain images. The real override over visual_lock is the **structured era contract**: use set_era_contract to set this episode’s tier (modern/republican/historical/fantasy/surreal), get_era_contract to read current value. **Unset means empty**—the platform can only rely on prompt text to fight drift; modern objects entering ancient images or scene images drawn in the wrong era is usually caused by this being empty. ★Xianxia/fantasy/immortal-realm content **must use fantasy, not historical**: historical requires textual realistic accuracy and will classify glowing aura, floating landforms, and non-human transformations as 'era-inconsistent', pulling images toward realistic ancient style. To make an exception for one scene (e.g. a modern flashback inside a fantasy world), use update_scene era_contract to override at scene level; scene-level beats episode-level.★★【Per-stage review protocol · all free · main line to prevent unusable film, not optional】After every stage output, review first, report conclusions verbatim to customer, then proceed. **Five hard gates (not passing causes 400; ④⑤ and agent QC below)**:① after rewritten script → review_script (before extract_assets / generate_storyboards);② after storyboards → review_storyboards (before generate_frames);③ after shot images → review_frames (before generate_videos). Each review returns review_token; pass it with downstream paid tools; explain findings one by one to customer (code=issue type · shots=hit shot numbers · action=which tool to fix), fix per action, then **review again** before proceeding. If content changed after review → token auto-invalidates; review once again (free). If error exists, block by default; only if customer explicitly understands and insists may pass acknowledge_review:true (acknowledge_review only means customer personally agreed; every execution mode still needs explicit customer consent, including managed mode); in managed steps, only allowlisted heuristic error can pass auto_acknowledge:true (see 【Execution-mode master rules】). **Soft guidance (non-blocking but strongly recommended, also free)**: before image/video generation run run_precheck (catches shots vendors will definitely reject, preventing wasted credits)—★**to run whole-drama first use run_drama_precheck** (drama-level summary · free · read-only): get issue counts per episode and attention (which episodes to fix first), prioritize by it, then run run_precheck on those episodes for details; do not blindly scan episode by episode. Note not_covered—drama-level skips the only lint that requires images, so '0 whole-drama issues' ≠ 'everything checked'. ★After findings, do not blindly edit yourself: plan_precheck_fix lets platform compute proposals → apply_precheck_fix writes them (choose which to adopt; managed=adopt all per execution mode: pro mode / no confirmed plan / this step customer-controlled → tell customer and proceed only after consent; do not decide for customer; managed step → do not ask, follow get_production_plan autopilot.default_decisions, platform logs in get_autopilot_log); after storyboards run get_health_report; after character sheets use get_characters to verify every appearing character has image/sheet; after frames use get_storyboards to inspect frame_status and fail_reason/fail_hint (fix failed shots before continuing; do not make video from bad frames); after videos inspect video_status similarly; before final cut use get_pipeline_status to confirm no missing shots. ★**Never generate straight through**: pushing layer after layer without review amplifies issues at every layer, and the whole episode may need redoing—every repeated image/video generation is real charged. Reviews are all free; catching issues costs nothing. ★Clothing changes are structured bindings: update_shot active_wardrobe_id (whole shot) / appearance_wardrobes (multi-character per role), can override or clear—editing text descriptions does not change clothes, and do not send customer to web UI.②【Production mainline · sequential, no skipping · ★storyboards before assets】set_script→rewrite_script→★review_script→extract_assets→storyboards(first storyboards · pure-text shot breakdown)→★review_storyboards→★Script discipline (endpoint-enforced, cannot bypass): all raw material (synopsis/outline/finished script all count) goes into set_script, **must go through rewrite_script to produce AI rewritten script**—pasting your own finished script directly into edit_rewritten_script to bypass rewrite will be rejected 400 (no rewritten script means nothing to edit); extract_assets likewise requires the rewritten script. All post-rewrite changes must use the structured format of AI output: edit script via edit_rewritten_script (polish/correct), character profiles via update_character, storyboards via update_shot/replace_shot_dialogue—do not go back and replace the whole script or write another truth source in settings; dueling truth sources are the top cause of consistency failures.★★**After rewrite_script succeeds once, do not rerun rewrite_script**: it restarts from the original full manuscript, discarding all current edits, and the new version is not guaranteed to preserve prior fixes (three-version tests oscillate). To fix, use edit_rewritten_script point edits (get_script full text → change only those scenes, copy the rest verbatim → submit whole text), free, seconds-level, deterministic; if rerun by mistake use get_script(include_previous=1) to recover previous version. generate_portraits_and_sheets(character sheet + concept images · build after storyboards: first use delete_character to delete appearing characters who **do not appear in any episode of the whole drama and are not planned for later episodes** before image generation—characters are drama-level; once deleted, no episode’s frame assembly includes them; this cannot be judged from current episode storyboards alone, keep if unsure (one character sheet costs far less than losing identity anchors in a later episode); the character sheet step generates images for **all undeleted appearing characters**, ignoring storyboard bindings, so kept characters are charged normally; voiceover characters (char_type=voiceover narrators/phone voices) are not image-generated and have no storyboard binding; **do not delete** them, dubbing relies on them)→★generate_color_script(color script · unified grading)→assign_voices(assign voice types; if narrator/character library has no fit → design_voice by description, then set_character_voice after sample approval)→★quote_scene_images+generate_scene_images(empty scene plates · required before frames)→frames(default first frames only)→★tail_frame_plan(free · which shots need independent last frames)→frames(frame_type=last_frame)→★chain_frames(seams · dry_run:true first)→★review_frames→videos→generate_tts→compose;★★【Do not skip seams · after last-frame completion, before review_frames】After first/last frames are ready, call chain_frames(dry_run:true, free) to view platform seam plan and estimated_points (copy free, reframe one image per seam), tell customer and execute without dry_run after confirmation; already chained seams are not planned, repeated calls do not charge again. ★After execution, reframe is **async image generation**: use get_jobs to watch first_frame generation rows for planned shots; wait until all pending/processing finish (failed: check error_msg; use chain_shot_from to rechains a single seam), then review_frames—while old first frame remains, get_storyboards frame_status is still ready, so it cannot show whether the new image is generating or failed. After get_jobs is clear, use get_storyboards to verify seam_state: replacement images rejected from promotion will not remain in get_jobs; that seam remains unchained (review_frames also reports seam_unchained); rechains per its action. If you review before landing, you reviewed old first frames; the token becomes invalid after new first frames land. Episodes generated shot-by-shot/batch likely were not auto-chained (get_storyboards seam_state=unchained means so); skipping does not error—the cost is mismatch between adjacent shots and jump cuts throughout final cut.★★【Do not skip last frames · frames are two passes】generate_frames defaults to first frames only. About 30% of shots have **end state ≠ start state** (large camera moves/object released/state changes) and need an independent last frame; the criterion is platform-side and cannot be guessed from storyboard text—therefore after first frames finish, you must call the free tail_frame_plan once to get per-shot list, then fill frame_type=last_frame (shots_needing_last_frame in generate_frames response is this count; if not 0 do not go straight to review_frames). Skipping does not error or block—the cost is that videos for those shots have only one anchor, so the model invents the end state: actions fail, large camera moves end back at the starting composition. Production tests: in 32 episodes, 30 generated only first frames for the whole episode, and 23 went all the way through video.★★【When last frame is blocked by TERMINAL_DESC_GATE: edit text, do not retry】For shots reporting 'this shot is marked as state-changing, but nowhere describes what it looks like at the end', use update_shot to write **what the image looks like at the end** into that shot’s last_frame_prompt, then regenerate last frame. ★Better: **avoid hitting it**—before last-frame generation, first inspect get_storyboards; shots with terminal_desc_missing=true are listed for the whole episode at once (free), fill their last_frame_prompt before generating and avoid any rejection. Per-shot query also exists (get_shot_prompts same field), but do not do that for dozens of shots. Retrying without filling the description is useless—the vendor prompt has no terminal-state section, so it still draws the first-frame pose and will be rejected again by terminal review, and each attempt is charged normally (production tests: last-frame success 9.4% without terminal description, 40.2% with it). Only use generate_shot_frame allow_missing_terminal for shots that truly should be 'almost unchanged'.★★【Do not skip empty scene plates · this step is often missed by third parties】Scene images are **background anchors**: every shot frame in the same scene anchors on it. Frames can still generate without plates, with no error and no block—the cost is **the first shot of every scene has no background anchor at all** (platform fallback is 'if missing image is discovered, generate one in background'; that plate is used by subsequent shots in the same scene, but the triggering first shot cannot wait for it), and the first shot is often the tone-setter; later backgrounds drift too. It is paired with character sheets: character sheets anchor people, scene images anchor locations; whichever is missing drifts. Progress self-check: get_pipeline_status generate_scene_images step (completed/total); review_storyboards also reports scene_plate_missing before frame generation.★★【Do not skip concept images · character sheet ≠ concept image】A character sheet is a single-person identity anchor; concept image is the platform-generated multi-angle turnaround from the character sheet, the root consistency anchor for shot frames/videos (angles, lighting, clothing rely on it). Frames can still generate with only character sheets, with no error—the cost is characters drift when angle changes and clothing differs every shot. Use generate_portraits_and_sheets for one-click two-step (each call advances one step; after character sheets are complete, call again to create concept images), or generate_character_sheets after character sheets. Progress self-check: get_pipeline_status generate_character_sheets step (completed/total, portrait_only=characters with character sheet only). ★Customer images: character sheet must be single person, single image, single angle, no text; scene image must be empty location with no people and no overlaid text—set_character_portrait/upload_scene_image auto-checks and rejects invalid with 422. ★Do not create character visuals/prop concept images/action templates before storyboards—storyboards are pure text and do not depend on any images; after storyboards the cast is known, delete non-appearing characters before image generation to save cost (action templates must be after storyboards anyway). Paid steps follow existing quote confirmation flow. Ads additionally need add_product+generate_product_sheet; MV uses set_mv_lyrics→generate_mv_story→generate_mv_script (if no finished song: after set_mv_lyrics first suggest_mv_song_styles→quote_mv_song→generate_mv_song→get_mv_song→select_mv_song).★★【④⑤ two new hard gates + agent personal QC】④Asset layer: after character sheets/concept images/scene images/prop images finish → review_assets (before generate_frames / generate_shot_frame; its token is asset_review_token and passed together with storyboard-layer review_token);⑤Video and dubbing layer: after video/dubbing/music finish → review_videos (before compose_episode); after final cut, run review_final_cut. ★After every review layer you must also **personally QC**: inspect assets item by item per returned agent_qc (download images, sample video frames, read text), answer checklist item by item, submit via submit_qc_report; for gray-release dramas, a review_token cannot enter the next step without the report; bad report is blocked by default like error. Platform judges existence; you judge likeness and correctness.★★【Single-shot path is also gated by reviews】: generate_shot_frame also requires storyboard-layer review_token; regenerate_shot_video also requires shot-image-layer review_token—do not expect single-shot tools to bypass review (production observed a workflow generating all 25 shots with single-shot frame tools and no gates; all final rework was fully charged). Generated frames **do not** invalidate the storyboard-layer token (fingerprint only covers storyboard content); only storyboard content edits—update_shot / import / add-delete shots / change character bindings—require one more review (free, seconds). Generating one shot’s frames invalidates the **shot-image-layer** token; before regenerating the next shot video, review_frames once.★★【For native-audio dramas, lock voices before batch video】When use_clip_audio=true(default), each shot’s voice is sampled independently by the video vendor; if not locked it will drift, and unifying after the fact requires per-shot regeneration. If customer-authorized voice source exists → clone_voice+set_character_voice before generate_videos; if not → for each speaking character first use single-shot quote_regenerate_shot_video→regenerate_shot_video on a shot with longer dialogue (generate_videos has no per-shot parameters and only batch-fills missing-video shots; single-shot regeneration also works for shots without video), then use set_voice_anchor_from_shot to select the voice from that shot, then generate remaining shots. get_pipeline_status native_voice_anchor lists unanchored_speakers not yet locked and stale_shots generated before locking that need regeneration. ★Worldview concept image = required by default (improves whole-drama consistency; many third-party platforms miss it): after storyboards, call generate_world_concept by default; still follows quote confirmation (tell customer estimated credits, confirm before charging)—do not charge silently and do not skip.★★【Color script】generate_color_script unifies grading across the whole film; run after storyboards and before frames; text step has no quote_*, postpaid by usage. Progress self-check: get_pipeline_status generate_color_script; review_storyboards reports color-script gaps. ★Action templates are optional experimental: call generate_motion_templates(action template extraction) after storyboards only if customer explicitly requests; text step postpaid by usage. First/last frames do not inject action templates by default; missing templates need not be made up and do not block image/video/final cut. Video templates may be cropped; delivery or quality gain is not guaranteed. ★Scene Bible(detailed per-scene setting) comes **after scene image generation**—refine based on generated scene images (no MCP tool yet; do on official site); do not make Scene Bible before scene images. ★Audio defaults to video native audio (use_clip_audio default on; skip TTS and use AI video’s built-in audio): when creating/updating drama settings, AI should proactively tell customer 'default uses video native audio; set use_clip_audio false if TTS dubbing is needed' and let customer choose. ★Default image model is ChatGPT Image 2.5 Flare(gpt-image-2.5-flare · unified whole-drama style): set image_model in create_drama/update_project_settings; omitted means default. Options: gpt-image-2.5-sunburst(same price · better Chinese glyphs/details)/gemini-3.1-flash-image(Banana 2 · 71 credits)/gemini-3-pro-image(Banana Pro · finer · 175 credits)/gemini-3.1-flash-lite-image(Banana 2 Lite · cheap · 31 credits)/doubao-seedream-5-0-260128(Seedream5.0); generate_frames can temporarily override one run. ★2.5 charges by input volume (base 11 credits + 18 credits per reference image); Banana/Seedream are flat price—shots with many reference images must include this in budget. ★Four video engine choices (drama-level · when AI creates a drama it must proactively guide engine choice by drama type and quote price differences for customer decision):【Decision tree】★Call get_production_menu first: whether each engine is currently available for realistic live-action / anime and other subject classes is decided by the availability it returns (unavailable entries carry customer_note and expected_until—relay them to the customer verbatim); do not assume from this description that any model is unavailable, and do not recommend models the menu marks unavailable. ①Realistic live-action drama→seedance-2.5 (strongest instruction following / face detail · pricing baseline 720p = 1×), or hailuo-3 when budget-sensitive (about 1/3 cost, 720p ≈0.33× · strong fidelity editing · can output 2K · but about 6 minutes per shot); ★After choosing, pass video_engine explicitly in create_drama / update_project_settings (the one the menu lists as available for this subject class)—if omitted, the platform only applies a style-based fallback stamp that is not guaranteed to be an engine the menu marks available; ②Stylized/animation/3D cartoon dramas · empty shots · product shots→wan3.0(about 40% price, 720p ≈0.4× · max 30 sec · minimum 2 sec billing · about 2 minutes per shot), use wan3.0-prime for rush delivery (720p ≈0.6× · about 1 minute); ★Always quote prices as relative multiples (seedance-2.5 720p = 1×); call quote_* before giving the customer absolute credits;③★Never choose wan3.0/prime for realistic live-action dramas—WAN output-side human-face review consistently rejects at 720p+, retry cannot fix;④★★For narrative dramas (dialogue, continuous story, stable shot rhythm), choose wan3.0/prime cautiously: WAN may **hard-cut camera positions inside a single storyboard shot** (tests: 11/12 shots had intra-shot jump cuts, versus seedance-2.5 1/6 and hailuo-3 0/5); final cut feels like 'the image jumps around within one shot, cuts too fast'. This is weak vendor instruction following and cannot be blocked at prompt level (our negative constraints are already included and tested ineffective); afterwards the only fix is regenerating with another engine. WAN fits stylized/empty/product shots that are inherently short and fast; for stable single-shot narrative choose seedance-2.5 or hailuo-3. After generation use scan_intra_shot_cuts to check;④b★★Dialogue-heavy dramas should choose hailuo-3 cautiously (different from above 'intra-shot self-cut'; this is about **whether all lines are spoken**): native-audio engine stops speaking at shot end and may ad-lib; tests show 'dialogue not fully spoken' rates hailuo-3 **50%** (26 shots, all generated after 8-30 native-audio repair, so engine itself), seedance-2.5 **23%** (294 shots); wan3.0 sample **insufficient, untested** for this dimension (26 samples all before same repair, only 2 after)—do not infer WAN is bad. When customer reports 'line not finished', first run scan_dialogue_coverage by family; do not default to lengthening shots (even among sufficiently long shots, 32% still missed full lines);⑤★Shot length control (all engines, especially WAN): keep each shot 3~5 seconds. The longer the shot, the more room the model has to improvise—test: one 16-second shot (neighbors all 3~5 sec) changed scenes 4 times within the shot; character disappeared for 4 sec then grew back from frame edge; customer sees 'a person appeared from nowhere'. For long performances, split into multiple short shots and connect with frame chains; do not write single shots over 15 sec;【Resolution decision】Draft/iteration: WAN dramas 480p (≈0.2× cheapest), others 720p; final delivery: seedance dramas 720p (for HD delivery choose 1080p, about 2.5× 720p), hailuo-3 dramas 1080p(=2K · ≈0.53×), WAN dramas 1080p(≈0.8×); hailuo-3 has no separate 480p tier (if selected, billed as 768P); set video_engine/video_resolution in create_drama/update_project_settings, ★must be decided before video generation—switching does not retroactively affect generated shots, and mixing within one drama causes style/identity drift. ★Slow image generation ≠ failure: each image takes tens of seconds to minutes; whole episode may take 10+ minutes. Poll get_storyboards frame_status—pending=still generating (wait patiently; do not call generate_frames again and waste credits), ready=done, failed=real failure. ★To change one shot’s image / make new character sheet take effect, use **single-shot regeneration generate_shot_frame** (platform automatically includes identity anchors, scene/prop references, style anchors for that shot to preserve whole-film consistency); generate_frames only batch-fills shots with **missing frames** and skips shots that already have first frames (normal, not 'rejected'). ★After first frames finish, call free tail_frame_plan to see which shots need independent last frames, then batch-fill with frame_type=last_frame. After changing a character sheet (set_character_portrait), stale_frames in the response are shots polluted by the old image and must be regenerated shot by shot. ★Never use external tools to make first/last frames and upload_shot_frame to 'change the image'—external images lack identity/style anchors, so characters/clothing/style will drift; that is the real source of unusable film. upload_shot_frame is only for customer-owned real footage.③【Optional enhancements · AI proactively informs customer · do only after quote confirmation】Art bible generation / visual lock extraction / scene groups / lip sync / posters / sound effects / music / subtitle translation—these improve consistency/quality and are mostly paid. ★AI should proactively tell customer these are available and provide quote (whether to run depends on execution mode: pro mode / no confirmed plan / this step customer-controlled → tell customer and proceed only after consent; do not decide for customer; managed step → do not ask, follow get_production_plan autopilot.default_decisions, platform logs in get_autopilot_log); neither silently skip nor charge without authorization. ★Two locking rules:①**Aspect ratio** is set at create_drama, locked at drama level; all later image/video/final cut use it, **do not change midstream** (generated content will have inconsistent aspect ratio and drift); default 9:16 if unset.②**5-7 sec per shot in shot breakdown is normal length optimized for AI video**, do not wrongly re-split because 'shots are long'—generate_storyboards **replaces all storyboards in the episode**, wasting generated images; backend blocks when storyboards already exist unless confirm_replace is supplied. ★Rewrite fidelity (default auto smart routing): when the set_script original is **already script-shaped** (scene headers/dialogue-line structure), rewrite_script automatically uses two-pass fidelity—customer dialogue is machine-gate locked line by line (missing one line causes internal rejection and redo), AI never adds plot; dramaturgical gaps (hooks/emotional anchors) are not auto-filled, but written into dramaturgy_suggestions returned by get_script (whether to adopt follows execution mode: pro mode / no confirmed plan / this step customer-controlled → tell customer and proceed only after consent; do not decide for customer; managed step → do not ask, follow get_production_plan autopilot.default_decisions, platform logs in get_autopilot_log). If original is novel/outline, it auto uses creative rewrite (AI lays hooks/emotional beats); both customer types get intended behavior, no manual switch needed. To override default use update_project_settings rewrite_pipeline(auto/two_pass/single_forced) and fidelity_enforce(1=hard fidelity gate). When customer says 'AI changed my script too much':①confirm full original entered set_script;②set rewrite_pipeline two_pass to force fidelity, then rerun rewrite_script;③after customer confirms character appearance, use update_character profile_locked=1 to lock profiles and prevent later extraction from overwriting appearance and changing faces in character sheets. ★If customer wants to rewrite script on **another AI platform** (common: third-party model says our rewrite 'changed too much', customer wants control): first call get_script_format_spec to obtain platform-accepted format contract (markdown template + external_prompt directly forwardable to external model + blank skeleton), give external_prompt+template+customer original to that platform; after receiving organized draft, **first call check_script_format** self-check (free · rule-only · no model); after errors are zero, two exits:【A】adopt_external_script directly adopts as shootable script (our AI not involved · seconds · no charge, requires external draft contains production-layer annotations);【B】set_script puts it back into original slot + rewrite_script two-pass fidelity (choose when external only handles story layer; platform fills annotations; customer-written annotations are stripped and rewritten on this path). ★Do not put external organized draft into edit_rewritten_script (400 if rewrite not run), and do not skip check_script_format before ingestion—noncompliant scripts are still blocked by gates, wasting a run.★★If the customer’s material is **already a finished storyboard table** (per-shot durations/framing/camera moves), neither path applies—use import_storyboard_table directly to create storyboards and skip rewrite and shot breakdown. The rewrite path will strip durations/framing/camera moves/STYLE/text cards as non-story content (production test: 8 shots 36 sec → 20 shots 109 sec). ★Both import channels are deterministic—wrong input is created as-is, so **get contract, self-check, then import**: storyboard table path uses get_storyboard_table_spec → check_storyboard_table → import_storyboard_table; if customer tools/spreadsheets can export structured data, or external AI can directly produce JSON, use get_bulk_import_spec → check_bulk_import → bulk_import_storyboards (only creates storyboards; characters/scenes/props are extracted from script by extract_assets; import binds by name to existing ones—extract first, then import). Both imports default with auto_complete(background AI fills professional fields + image/video prompts, text step postpaid; tell customer before call): if receipt started=true, poll get_autofill_status until done, then review_storyboards—autofill changes shots, so any earlier review token invalidates. Use get_pipeline_status for progress (returns project-type-specific steps).★★【Opening plan · first thing after creating drama · free】First ask basic video parameters (project type/aspect ratio/episodes × minutes per episode/subject: realistic_human realistic live-action · stylized anime/stylized · product/empty shots · native audio or dubbing), then call get_production_menu to get **currently available** three packages (effect description + real-time estimate including text steps + recommended budget + excluded items) and explain to customer—do not recommend models from memory; some models may be temporarily unavailable for some subjects, menu already filters them. Then let customer choose execution mode (pro self-control every step / auto one-click final cut / custom managed selected steps), budget budget_points, and automatic overrun cap (0/10/20/30/50%): **default recommendation** budget=selected package recommended_budget (upper bound excluding text ×1.2 plus text estimate), overrun=menu recommended_overrun_pct(30%)—QC regenerations are not in upper bound and are covered by overrun; recommendation is only recommendation, final numbers are customer’s, and if customer changes them use customer values. Explain summary clearly; only after explicit customer consent call confirm_production_plan(customer_confirmed:true)—never confirm for customer. For dramas with confirmed plan: before paid dispatch the platform rechecks model availability and quote upper bound ≤ budget×(1+overrun%); if blocked (402 BUDGET_WOULD_EXCEED / 409 MODEL_UNAVAILABLE), stop and ask customer; do not change model or budget yourself. confirm returns 403 PRODUCTION_PLAN_NOT_OPEN = this drama not open (gray release), follow original step-by-step confirmation flow.\n★【Post-completion QC】After extraction, use get_characters / get_scenes / get_props to verify profiles (names, appearance, era) match the customer script; after character sheets/concept images/scene images/prop images finish, review_assets handles coverage and quality review uniformly.",
@@ -33,7 +33,7 @@
   "lock_shot_video": "Lock a shot's current video as the customer-accepted version (free; generates nothing, changes no asset). Use it when the customer has explicitly said \"keep this take\" and the shot's frames / scene / character were changed afterwards. While locked, asset changes no longer mark the shot stale: review_videos stops reporting video_stale (a warning video_locked_frames_changed instead), get_asset_versions shows acceptance_locked=true with the drift listed in drift_while_locked, native-voice stale_shots skip it, and the compose preflight does not flag it; regenerate_shot_video / edit_video_shot / repaint / reskin / footage upload or clear / a whole-episode generate_videos that would replace it all return 409 VIDEO_LOCKED. The lock freezes the video generation id and the inputs it was made from (first/last frame URLs, prompt, reference list). Only the video currently in use can be locked (a generation_id that is not it returns 409 NOT_CURRENT_VIDEO; no video returns 409 NO_VIDEO). If the video is swapped by another path, the lock lapses (video_lock.broken=true in get_asset_versions). Lock only after the customer explicitly confirms; never treat generation finishing or a model judgement as acceptance. To regenerate, get the customer's OK and call unlock_shot_video first.",
   "unlock_shot_video": "Remove a shot's accepted-video lock (free). The original verdict comes back immediately: a shot whose frames changed reports video_stale again and can be regenerated with regenerate_shot_video. Call only when the customer agrees to give up the locked take. Returns was_locked.",
   "get_asset_binding_repair_plan": "Read-only generation of an auditable repair proposal for missing historical scene bindings in an episode. Returns original location/time, candidate ID, match basis, ambiguity, and proposed_scene_id; applied=false, never auto-backfills by name. Only after item-by-item verification does the customer decide whether to rebind. Free.",
-  "get_storyboards": "Read an episode’s storyboard list (for review/progress). Includes readiness of each shot’s first frame (first_frame_image) and video (video_url). asset_versions separately reports for first frame/last frame/video: generated, input_consistent, review_valid, adopted, current_effective. null=missing evidence; ready only means an artifact exists, not that it is currently effective. Old assets remain viewable. ★Each shot includes **dialogue and speaker**: dialogue (raw text, null if no dialogue), dialogue_lines([{speaker,text}] line by line, split by the same parser as subtitles/voiceover—the speaker here is the one voiced in the final cut; stage directions removed), plus is_key_moment (1=key shot, uses high-end image model) and emotion_intensity (1-10). Use this single call to verify “whether dialogue is missing / who speaks / which shots are key / emotion curve”; no need to fetch per shot. After update_shot changes dialogue, verify here too. Visual/video/first-last-frame prompts are still only read per shot with get_shot_prompts. ★Each shot also includes **structured status**: frame_status/video_status (ready/pending/authorizing/rejected/failed/none/not_required). ★video_status=ready only means video generated, not that visual acceptance passed. If video_quality_issues contains terminal_cut: status=suspected means suspected abrupt end cut; cut_at_s/tail_duration_s give position; status=unavailable means detection not complete, not a pass. Both pause this run’s automatic last-frame writeback and continuation; review the video first. Field absence does not mean detection was performed, and do not directly retry paid generation. ★not_required=narration/end-card shot: frames and video are rendered at final-cut layer; this shot does not need generation—count it as completed when filling progress, do not retry. fail_reason (sensitive/text_sensitive/copyright/face_mismatch/account_overdue/quota_full/authorizing/insufficient_credits/transient/repeat_rejected/diagnosis_required/pair_collateral/model_unavailable/requote_required/needs_content_fix/contract_rejected/unknown), retryable (true=can retry; false=handle per fail_hint first, do not retry unchanged), fail_hint (human-readable). ★Failed video shots also carry video_charge_status (charged=video_charged_points were deducted / no_charge_recorded=the local ledger records no deduction / pending=billing not settled yet; field absent=charge state unknown). Only charged is definitive; no_charge_recorded does not mean refunded — do not promise a refund, confirm with get_drama_bill. ★requote_required=quote conditions changed, the shot was not dispatched or charged: re-quote with quote_videos (free) first. ★model_unavailable=selected image/video model vendor has paused or is temporarily unavailable: fail_hint lists currently available alternative models (whether credits were charged depends on error text; do not promise refunds on behalf of platform). Ask user, then use update_project_settings to change video_engine/image_model (or per shot use regenerate_shot_video model / generate_shot_frame image_model) before generating; retrying unchanged will only fail again. ★diagnosis_required=same input and same detailed cause failed repeatedly or existing candidates await judgment: inspect existing candidates and audit evidence first. For audit failure, re-review the same candidate first; for unknown reason, recheck first; do not directly change script or regenerate. Follow retryable to decide retry vs content change; do not parse Chinese. ★pair_collateral=other frame in same shot failed, this frame ended with the batch—**this frame itself was not judged bad, do not modify it**: if reopen_pair_id exists, use it to reroll only the faulty side; otherwise regenerate this shot directly. ★If a shot has degraded_frames:[{frame_type,reason,reason_label,since,hint}], this frame was **allowed through** by the system after same-cause repeated-rejection circuit break (criteria recorded, not rejected); URL is indistinguishable from a clean frame but requires manual review. If unsatisfied, follow hint to fix input then generate_shot_frame to regenerate that frame. ★terminal_desc_missing=true: this shot is marked as “state change” but none of three places says what it looks like at the end—this can be detected **before last-frame generation**, now for the whole episode at once (previously only get_shot_prompts could query per shot; nobody queries dozens of shots one by one). First use update_shot to write the ending state into last_frame_prompt, then generate the last frame: historical success rate when forced as-is is 9.4%, with terminal state written 40.2%, and each rejection still charges normally. Only for shots truly “almost unchanged” use generate_shot_frame allow_missing_terminal to pass. ★first_frame_source/last_frame_source='upload' means this frame is an **externally uploaded image** (bypassing identity anchors/style anchors/best-of-N/frame audit quality chain)—check these shots first when diagnosing character/clothing/style drift. Drift caused by external images is not a platform generation quality issue; correct fix is delete the external image and use generate_shot_frame for platform regeneration. ★If a shot has reopen_pair_id: when first/last frames were generated together, only one side truly had an issue and the other was innocent collateral rejection; pass it unchanged to generate_shot_frame parameter reopen_pair_id to reroll only the faulty side (saves half compute/cost; will not generate an image not intended for this rerun). If absent, follow fail_reason/retryable normal retry. Free. ★Each shot also includes **bindings** (IDs only): character_ids (characters bound to this shot), character_bindings[{character_id,presence}] (presence=on_screen visible in frame / voice_only voice only, not in frame), scene_id, prop_ids, active_wardrobe_id (shot-wide wardrobe), appearance_wardrobes[{character_id,wardrobe_id}] (per-character wardrobe anchor; only lists characters with declared wardrobe). These determine whose character sheet/which scene image/which prop images are injected for image generation; use get_characters for character-name lookup, get_props for prop-name lookup. Change bindings with update_shot character_ids (★full overwrite; read current values here before editing, omitted means unbind) and character_presence; change wardrobe with update_shot active_wardrobe_id / appearance_wardrobes (can overwrite, can pass null to clear); read this tool again after edits to verify. character_bindings absent = not read this time (not unbound); empty array means no bindings. ★When bilateral version review is enabled, seam_review.status is passed/failed/not_checked/stale; stale means evidence expired, not image failure, do not pay to regenerate for that alone. continuity_intent can be made explicit with update_shot. ★Each shot includes **seam_state** (seam between this shot and previous shot, same criteria as official site frame timeline): ok=chained (first frame is previous shot’s last frame, or platform performed first-last frame continuation, landed, and neither side regenerated afterward) / unchained=should be continuous but not connected (marked continuous but never connected, or platform-initiated continuation regeneration did not land: rejected/failed/still generating—this shot frame_status will be failed/processing; or after continuation passed, this shot’s first frame was regenerated) / broken=connected but discontinuous (seam_failed_dims gives discontinuous dimensions: characters/wardrobe/props/lighting/scene; seam_audit_status=stale with no dimensions = previous shot’s last frame regenerated after continuation, while this shot’s first frame still connects to old last frame) / intended=intentional cut (hard cut/scene change/time jump/large shot-size jump/insert shot/external uploaded frame), ignore / missing=frames missing on either side / unknown=no intent marked and never connected (system did not judge, not an issue) / na=first shot or narration card. seam_audit_status=pending means continuation landed but platform continuity audit not concluded yet. Before video generation only handle unchained and broken: episode-wide use chain_frames (dry_run first), single shot use chain_shot_from_prev / chain_shot_from.",
+  "get_storyboards": "Read an episode’s storyboard list (for review/progress). Includes readiness of each shot’s first frame (first_frame_image) and video (video_url). asset_versions separately reports for first frame/last frame/video: generated, input_consistent, review_valid, adopted, current_effective. null=missing evidence; ready only means an artifact exists, not that it is currently effective. Old assets remain viewable. ★Each shot includes **dialogue and speaker**: dialogue (raw text, null if no dialogue), dialogue_lines([{speaker,text}] line by line, split by the same parser as subtitles/voiceover—the speaker here is the one voiced in the final cut; stage directions removed), plus is_key_moment (1=key shot, uses high-end image model) and emotion_intensity (1-10). Use this single call to verify “whether dialogue is missing / who speaks / which shots are key / emotion curve”; no need to fetch per shot. After update_shot changes dialogue, verify here too. Visual/video/first-last-frame prompts are still only read per shot with get_shot_prompts. ★Each shot also includes **structured status**: frame_status/video_status (ready/pending/authorizing/rejected/failed/none/not_required). ★video_status=ready only means video generated, not that visual acceptance passed. If video_quality_issues contains terminal_cut: status=suspected means suspected abrupt end cut; cut_at_s/tail_duration_s give position; status=unavailable means detection not complete, not a pass. Both pause this run’s automatic last-frame writeback and continuation; review the video first. Field absence does not mean detection was performed, and do not directly retry paid generation. ★not_required=narration/end-card shot: frames and video are rendered at final-cut layer; this shot does not need generation—count it as completed when filling progress, do not retry. fail_reason (sensitive/text_sensitive/copyright/face_mismatch/account_overdue/quota_full/authorizing/insufficient_credits/transient/repeat_rejected/diagnosis_required/pair_collateral/model_unavailable/requote_required/needs_content_fix/contract_rejected/unknown), retryable (true=can retry; false=handle per fail_hint first, do not retry unchanged), fail_hint (human-readable). ★Failed video shots also carry video_charge_status (charged=video_charged_points were deducted / no_charge_recorded=the local ledger records no deduction / pending=billing not settled yet; field absent=charge state unknown). Only charged is definitive; no_charge_recorded does not mean refunded — do not promise a refund, confirm with get_drama_bill. ★requote_required=quote conditions changed, the shot was not dispatched or charged: re-quote with quote_videos (free) first. ★model_unavailable=selected image/video model vendor has paused or is temporarily unavailable: fail_hint lists currently available alternative models (whether credits were charged depends on error text; do not promise refunds on behalf of platform). Ask user, then use update_project_settings to change video_engine/image_model (or per shot use regenerate_shot_video model / generate_shot_frame image_model) before generating; retrying unchanged will only fail again. ★diagnosis_required=same input and same detailed cause failed repeatedly or existing candidates await judgment: inspect existing candidates and audit evidence first. For audit failure, re-review the same candidate first; for unknown reason, recheck first; do not directly change script or regenerate. Follow retryable to decide retry vs content change; do not parse Chinese. ★pair_collateral=other frame in same shot failed, this frame ended with the batch—**this frame itself was not judged bad, do not modify it**: if reopen_pair_id exists, use it to reroll only the faulty side; otherwise regenerate this shot directly. ★If a shot has degraded_frames:[{frame_type,reason,reason_label,since,hint}], this frame was **allowed through** by the system after same-cause repeated-rejection circuit break (criteria recorded, not rejected); URL is indistinguishable from a clean frame but requires manual review. If unsatisfied, follow hint to fix input then generate_shot_frame to regenerate that frame. ★terminal_desc_missing=true: this shot is marked as “state change” but none of three places says what it looks like at the end—this can be detected **before last-frame generation**, now for the whole episode at once (previously only get_shot_prompts could query per shot; nobody queries dozens of shots one by one). First use update_shot to write the ending state into last_frame_prompt, then generate the last frame: historical success rate when forced as-is is 9.4%, with terminal state written 40.2%, and each rejection still charges normally. Only for shots truly “almost unchanged” use generate_shot_frame allow_missing_terminal to pass. ★first_frame_source/last_frame_source='upload' means this frame is an **externally uploaded image** (bypassing identity anchors/style anchors/best-of-N/frame audit quality chain)—check these shots first when diagnosing character/clothing/style drift. Drift caused by external images is not a platform generation quality issue; correct fix is delete the external image and use generate_shot_frame for platform regeneration. ★If a shot has reopen_pair_id: when first/last frames were generated together, only one side truly had an issue and the other was innocent collateral rejection; pass it unchanged to generate_shot_frame parameter reopen_pair_id to reroll only the faulty side (saves half compute/cost; will not generate an image not intended for this rerun). If absent, follow fail_reason/retryable normal retry. Free. ★Each shot also includes **bindings** (IDs only): character_ids (characters bound to this shot), character_bindings[{character_id,presence}] (presence=on_screen visible in frame / voice_only voice only, not in frame), scene_id, prop_ids, active_wardrobe_id (shot-wide wardrobe), appearance_wardrobes[{character_id,wardrobe_id}] (per-character wardrobe anchor; only lists characters with declared wardrobe). These determine whose character sheet/which scene image/which prop images are injected for image generation; use get_characters for character-name lookup, get_props for prop-name lookup. Change bindings with update_shot character_ids (★full overwrite; read current values here before editing, omitted means unbind) and character_presence; change prop bindings with update_shot prop_ids (also full overwrite, [] clears); change wardrobe with update_shot active_wardrobe_id / appearance_wardrobes (can overwrite, can pass null to clear); read this tool again after edits to verify. character_bindings absent = not read this time (not unbound); empty array means no bindings. ★When bilateral version review is enabled, seam_review.status is passed/failed/not_checked/stale; stale means evidence expired, not image failure, do not pay to regenerate for that alone. continuity_intent can be made explicit with update_shot. ★Each shot includes **seam_state** (seam between this shot and previous shot, same criteria as official site frame timeline): ok=chained (first frame is previous shot’s last frame, or platform performed first-last frame continuation, landed, and neither side regenerated afterward) / unchained=should be continuous but not connected (marked continuous but never connected, or platform-initiated continuation regeneration did not land: rejected/failed/still generating—this shot frame_status will be failed/processing; or after continuation passed, this shot’s first frame was regenerated) / broken=connected but discontinuous (seam_failed_dims gives discontinuous dimensions: characters/wardrobe/props/lighting/scene; seam_audit_status=stale with no dimensions = previous shot’s last frame regenerated after continuation, while this shot’s first frame still connects to old last frame) / intended=intentional cut (hard cut/scene change/time jump/large shot-size jump/insert shot/external uploaded frame), ignore / missing=frames missing on either side / unknown=no intent marked and never connected (system did not judge, not an issue) / na=first shot or narration card. seam_audit_status=pending means continuation landed but platform continuity audit not concluded yet. Before video generation only handle unchained and broken: episode-wide use chain_frames (dry_run first), single shot use chain_shot_from_prev / chain_shot_from.",
   "get_run_status": "(★free · mandatory after long-running operations) Check whether an agent is currently running for this episode. rewrite_script / extract_assets / generate_storyboards are all **minute-level** background tasks; they only return status:\"generating\". This tool is the only way to distinguish “still running” from “finished”.\n★Typical duration (production measured): rewrite 2~4 minutes, storyboard splitting 5~10 minutes—**a single LLM call may take 3~7 minutes**. So no result within 60 seconds is completely normal, definitely not failure.\nUsage: after starting, call every 30~60 seconds. running:true = still running, keep waiting, **never resend** (resending storyboard splitting replaces the entire episode’s storyboards; all tuned/generated images are lost and must be paid again); running:false = that run has ended, only then call get_storyboards / get_script to see whether artifacts were persisted.\n⚠️ Service restart clears in-flight registration; runs started during restart may also show as no in-flight.",
   "run_precheck": "(★recommended · free quality gate) Run pre-generation precheck before image/video generation to catch shots that would be rejected. Free, no credits charged. Strongly recommended before generate_frames/generate_videos to avoid wasting money on rejections.\nChecks these categories: ① live-action portrait / cloned voice authorization ② high-risk image-review words ③ voiceover coverage and large gaps ④ **self-contradictory instructions (kind=prompt-conflict)**—mutually exclusive requirements within the same shot (e.g. wide shot but close-up subject marked, standing and sitting at once). No correct image can satisfy these shots; if not fixed they will be rejected repeatedly and charge repeatedly. When present, first edit the storyboard per hints, then generate images, rather than retrying.\n★**You do not need to guess how to fix**: call plan_precheck_fix for platform proposals (which shot, change what to what), then apply_precheck_fix to persist (choose which items to accept; autopilot=accept all per execution mode: professional mode / unconfirmed plan / this step controlled by customer → explain to customer and only do it after customer agrees, do not decide for them; this step autopilot → do not ask customer, execute per get_production_plan autopilot.default_decisions, platform records it in get_autopilot_log)—more stable than blindly using update_shot yourself, which bypasses optimistic lock and pre-persist recheck. Some categories are not auto-fixed by system (blocked in proposals); only those require manual handling.\n★★**Also come back and run this when a shot repeatedly cannot be generated**—this tool is not only a preflight check. It also reports “same-shot same-cause repeated rejection circuit-broken (repeat-reject, auto-clears in 24h)” and “frame contract contradiction”; that is exactly the answer to “why this shot never works no matter how we reroll”. **Do not blindly reroll**: while circuit break is active, every reroll repeats the same full-price rejection.\n⚠️ It does **not** check whether the first frame is “before the action happens” (platform has no contract field for this yet), and does not replace get_health_report.",
   "run_drama_precheck": "(★free · read-only) **Whole-drama** health summary: get in one call how many issues each episode has and which episodes to fix first. run_precheck is episode-level; for dozens of episodes you would need dozens of calls and manual aggregation—call this first when scanning the full drama.\nReturns: episodes[] with per-episode blockers/warnings/by_kind (counts by rule code), totals for whole drama, attention[] = episodes most worth fixing first (sorted by blocker count, warning count descending).\n★**How to use**: inspect attention to set priority → call run_precheck on those episodes for itemized details → use plan_precheck_fix / update_shot to fix → rerun this tool to confirm totals decreased.\n⚠️ **“whole drama 0 issues” does not mean “everything was checked”**: to finish in one request, drama-level forcibly skips the only lint that needs image inspection (25s wall-clock per episode). not_covered in response lists skipped categories; to check those, run run_precheck on the corresponding episode.\n⚠️ episodes[].failed=true means that episode **was not checked successfully** (not “no issues”); just retry. truncated=true means episode count exceeded limit and scan is incomplete.",
@@ -48,7 +48,7 @@
   "submit_qc_report": "Submit the QC report made by you (agent) after personally inspecting materials. Free. First call the corresponding review_* layer (script / storyboards / assets / frames / videos), open each returned agent_qc material in materials, answer every checklist item, then call this tool. ★The platform only verifies the report is **complete**, not whether your conclusions are correct: every checklist id must be answered (ok / issue / na; issue must include note explaining which item has what problem); every ref in materials must be listed in inspected (omit one and it is rejected with the missing refs named); if there are issues, set verdict=issues and list them in issues; reporting pass when issues exist will be rejected. ★Do not go through the motions: listing something in inspected without opening it means you signed off for the customer—wasted output will still be charged. ★When verdict=issues, this token cannot proceed to the next step by default: explain the problems to the customer, fix, then review + QC again; only if the customer is clearly informed and insists on proceeding as-is should the next step include acknowledge_review:true. ★suggestions (change suggestions): required at script layer when agent_qc.suggestions_required=true and issues were reported; optional for other layers. Each item includes problem + proposal; if text can be directly changed, also provide before/after; the response assigns each suggestion an id (s1…). Explain suggestions to the customer; the customer chooses accept some / execute all directly / proceed without changes (which route; autopilot = only execute priority=must suggestions that do not change the customer's original lines per execution mode: professional mode / unconfirmed plan / this step customer-controlled → explain to customer and only proceed after approval; do not decide for the customer. This step autopilot → do not ask customer; follow get_production_plan autopilot.default_decisions, recorded by the platform in get_autopilot_log). If content changes after the review, the report will be rejected; review again and QC against the new agent_qc.",
   "review_all": "(Recommended · free) Overall health check running three layers at once: script + storyboards + shot images. Use for initial assessment before work starts and recheck before delivery. ★It **does not issue review_token**—before paid steps, still run the corresponding review_script / review_storyboards / review_frames once each (the gate recognizes \"just reviewed against the current output\", not \"reviewed once sometime before\").",
   "quote_autofill": "Quote: credits for autofill_storyboards. No charge, changes no data. Same basis as the completion itself: in fill-empty mode, shots with no gaps are skipped and not billed; overwrite:true bills every shot. Returns { shots_to_fill (shots that will actually call AI), shots_skipped_no_gap (shots with no gaps, skipped and not charged), estimated_points (budget upper bound; prepare balance by this), typical_points (usual cost) }—tell the customer both point figures, and after consent call autofill_storyboards with the **same** overwrite / storyboard_ids. Completion is a postpaid text step; this quote issues no quote_id and does not lock the price.",
-  "autofill_storyboards": "(Recommended) AI one-click fills missing storyboard fields across the episode (or only the shots in storyboard_ids); by default it **only fills blanks and does not overwrite existing values** (only overwrites when overwrite=true). Improves storyboard completeness; do before image generation. Async in background, postpaid text step (billed per shot that actually calls AI). ★**Quote first with quote_autofill** (same overwrite / storyboard_ids), tell the customer shots_to_fill and estimated_points / typical_points, and **run this tool only after the customer agrees**. ★When done, read the receipt from get_autofill_status (which fields were written on how many shots, how many skipped, how many still lack contracts) and tell the customer—the internal fields written here are not readable via get_storyboards, so don’t let the customer think they were charged for nothing. ★The platform already completed one round when storyboards were saved: in fill-empty mode, shots with no gaps left (all six narrative text fields present, vocal direction present on shots with dialogue, and contract present when contract auto-fill is on) are skipped with no AI call and no charge; only overwrite:true reruns the whole episode and bills every shot. ★Completion writes narrative/rhythm internal fields and composition contracts; get_storyboards / get_shot_prompts do not return these fields, so no visible change on read-back is normal—check the counts in the get_autofill_status receipt; it **does not change** image/video prompt text. ★When platform contract auto-fill is enabled, it also tries to add contracts to shots **without composition contracts** (whether enabled is indicated by the note in the import receipt contract_coverage; visible headcount / subject range / shot size are judged by it for both image generation and review; with default overwrite:false, existing contracts are untouched; **overwrite:true also rewrites existing contracts**)—if auto_complete was off during import and the contract_coverage note points to this tool, call it once before image generation. If this episode already has autofill running, this run **will not queue** (prevents duplicate-click duplicate charges); newly imported shots must wait until get_autofill_status is done before calling again. ★To trial a small range first: pass storyboard_ids (1–50 shot ids of this episode, from get_storyboards); only those shots are filled, others make no AI call and are not charged; omit = whole episode. If a completion is already running in this episode, the subset does not start: the receipt returns started=false, reason=fill batch already running; call again after get_autofill_status reaches done.",
+  "autofill_storyboards": "(Recommended) AI one-click fills missing storyboard fields across the episode (or only the shots in storyboard_ids); by default it **only fills blanks and does not overwrite existing values** (only overwrites when overwrite=true). Improves storyboard completeness; do before image generation. Async in background, postpaid text step (billed per shot that actually calls AI). ★Before running, confirm character/scene/prop bindings (check get_storyboards character_ids / scene_id / prop_ids shot by shot against the customer's original). If a missing binding turns up after auto-completion, just fix it with update_shot; **do not re-import the episode**—re-import replaces the storyboards, discards the auto-completion and charges again. ★**Quote first with quote_autofill** (same overwrite / storyboard_ids), tell the customer shots_to_fill and estimated_points / typical_points, and **run this tool only after the customer agrees**. ★When done, read the receipt from get_autofill_status (which fields were written on how many shots, how many skipped, how many still lack contracts) and tell the customer—the internal fields written here are not readable via get_storyboards, so don’t let the customer think they were charged for nothing. ★The platform already completed one round when storyboards were saved: in fill-empty mode, shots with no gaps left (all six narrative text fields present, vocal direction present on shots with dialogue, and contract present when contract auto-fill is on) are skipped with no AI call and no charge; only overwrite:true reruns the whole episode and bills every shot. ★Completion writes narrative/rhythm internal fields and composition contracts; get_storyboards / get_shot_prompts do not return these fields, so no visible change on read-back is normal—check the counts in the get_autofill_status receipt; it **does not change** image/video prompt text. ★When platform contract auto-fill is enabled, it also tries to add contracts to shots **without composition contracts** (whether enabled is indicated by the note in the import receipt contract_coverage; visible headcount / subject range / shot size are judged by it for both image generation and review; with default overwrite:false, existing contracts are untouched; **overwrite:true also rewrites existing contracts**)—if auto_complete was off during import and the contract_coverage note points to this tool, call it once before image generation. If this episode already has autofill running, this run **will not queue** (prevents duplicate-click duplicate charges); newly imported shots must wait until get_autofill_status is done before calling again. ★To trial a small range first: pass storyboard_ids (1–50 shot ids of this episode, from get_storyboards); only those shots are filled, others make no AI call and are not charged; omit = whole episode. If a completion is already running in this episode, the subset does not start: the receipt returns started=false, reason=fill batch already running; call again after get_autofill_status reaches done.",
   "enhance_shot_prompts": "(Optional enhancement · ★not required · has side effects) AI batch-enhances the whole episode's image_prompt. ★It **rewrites existing prompts** (including manually edited ones); and **must be done before generate_frames**—changing prompts after image generation makes images stale and requires paid regeneration. Not required to get a film through the pipeline; do only if the customer explicitly requests it. Async in background, postpaid text step.",
   "complete_ending_motifs": "(Optional enhancement·★not required·conditional) Complete missing visual motifs in the ending segment (graft visual echoes onto ending shots). ★Prerequisite: this drama already has motifs (none = no-op); this will **modify ending shot action/descriptions**, so do it before generating images (otherwise already-generated ending shots become stale). Backend async, billed after the text step.",
   "tail_frame_plan": "★Free read-only: which shots in this episode **need independent last frames** (shots whose terminal state ≠ initial state—large camera move/object released/state change). It uses the same criteria the platform uses for video generation; you cannot guess this yourself, so call it once after first frames are done. Returns shots_needing_last_frame(total), ready(shots with first frames already available and can get last frames now), pending_first_frame(shots that need last frames but whose first frames are not ready yet—call this tool again after first frames finish). After getting the ready list: use quote_frames + generate_frames with frame_type=last_frame to batch-fill. ★After last frames are filled (or this tool reports 0), the next step is seams: chain_frames(dry_run:true) to view plan and estimate, execute after customer confirmation, then review_frames. ★Skipping last frames will not error, but those shots have only one first-frame anchor during video generation, so the model improvises the terminal state—bad action completion, large camera moves ending back at the starting composition, etc. usually come from this. Zero cost, callable anytime.",
@@ -138,7 +138,7 @@
   "scan_voice_consistency": "★For original-voice dramas (video has built-in human speech), run this when the customer reports \"the same character's voice differs across shots / voice drifted\". Free (local inference, no vendor call). For each shot with dialogue, listens to vendor-generated human speech: whether the dialogue was fully spoken, and whether the voice resembles the timbre anchor bound to that character. **Async**: returns immediately; background full-episode scan takes about 10 minutes. Only one scan per episode can run at the same time (repeat calls return started=false). By default skips shots already scanned for the current video; rescan=true rescans all. Use get_voice_consistency to check progress and per-shot results.",
   "get_voice_consistency": "Check progress and per-shot results of the voice consistency scan (started by scan_voice_consistency). Free. summary.voice_mismatch = shot numbers whose voice does not resemble the character timbre anchor (focus on these); dialogue_issues = shots where dialogue was incomplete/wrong/extra speech appeared; not_scanned_or_stale = not scanned yet or video changed and needs rescan. speaker_verdict=uncertain means the human speech is too short to judge; it is not an issue. For shots with inconsistent voice: first use get_pipeline_status native_voice_anchor to confirm the character has a bound voice, then regenerate_shot_video.",
   "scan_dialogue_coverage": "★When the customer reports \"cut before the line finished / only half the dialogue was spoken\", run this first. Default **free, zero charge** (read-only access to persisted transcription audit results). Compares each original-voice shot's video audio track against the dialogue at word level, and reports conclusions by family: truncated (stops halfway through the line) / off_script (most spoken content is not the dialogue: improvising, repeating previous shot, only ambience) / extra_speech (dialogue is fully spoken but extra speech is added) / minor_gap (sporadic missing words, transcription error, ignore) / ok. ★Interpretation: the three reportable families have **different remedies**; do not simply lengthen every shot—measurements show 21% of shots with sufficient length still fail to finish the line, so \"too short\" is rarely the real cause (the platform already auto-raises duration by dialogue when saving storyboards). The correct fix for truncated/off_script is regenerate_shot_video (how much the vendor says is random each time; rerolling often gets the full line); if the same drama repeatedly has off_script, switch engine. ★never_audited is the most important section of this report: those shots have never been checked; \"not checked\" does not mean \"no issue\". rescan=true will run ASR comparison for them (compute-intensive, not instant; limit controls per-run cap), default does not run. TTS-dubbed shots are out of scope (TTS necessarily reads the full line; low coverage can only be transcription error). If the same episode also has \"cuts too fast\", that is a separate issue; run scan_intra_shot_cuts.",
-  "update_shot": "Shot-by-shot edit: change a single storyboard shot's text content (shot size/action/dialogue/visual description/camera movement, etc.), facial expression (expression_hint), duration (duration), final cut speed (speed_factor), character binding (character_ids), voice-over marker (character_presence), and wardrobe binding (active_wardrobe_id / appearance_wardrobes). Send only fields to change; all others stay unchanged. ★Any shot edit (accepted or rejected) invalidates unconsumed quotes covering this shot; generation then returns 409 QUOTE_INVALIDATED—edit first, read back to verify, then quote. **Free** (pure text DB write). ★Changing dialogue automatically invalidates generated TTS voice-over and subtitles for this shot (tts must be regenerated); text edits do not auto-regenerate images/video. To make visuals follow text changes, edit then regen the corresponding shot. Use get_storyboards to inspect results (each shot includes character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes). ★★【Change clothes here, not in text】What appears in image generation is determined by **wardrobe binding**: single-character shots use active_wardrobe_id (one outfit for the whole shot); multi-character shots use appearance_wardrobes (per character). Writing \"wearing X clothes\" in description/action will not change clothes. Use list_wardrobe for wardrobe id; edits do not auto-regenerate images. To update visuals, regenerate this shot's first frame then video. ★★For native-audio shots (vendor-native audio), after changing dialogue the shot video is marked \"needs regeneration\"—because spoken lines are **baked into the video audio**. If you final-compose without regeneration, the final cut still speaks the old line (typical symptom: dialogue seems to have moved to another shot). compose_episode lists these shots under advisory `stale_video_after_edit`; correct handling is regenerate_shot_video before final compose. ★You may also directly edit this shot's four prompt bodies (image_prompt/video_prompt/first_frame_prompt/last_frame_prompt): read current values with get_shot_prompts first; do not overwrite from scratch. @char:N / @scene:M in the body are supplemental reference markers for image generation; keep them unchanged. ★Which character sheet is injected is determined by character_ids, and background by scene_id: deleting markers will not remove already-bound people from the image. To make someone not appear, edit character_ids; if they are voice-only, set character_presence to voice_only. Conversely, do not write @char markers for unbound characters—this will inject their image. ★★【If last-frame generation is blocked, edit here】If last-frame generation reports \"this shot is marked as a state change, but nowhere describes what it looks like at the end\" (TERMINAL_DESC_GATE), fix by writing **what the final image should look like** into this shot's last_frame_prompt, then regenerate the last frame. Do not retry image generation—shots of this type (action_motion_class=state_change without terminal state) historically succeed at 9.4%, versus 40.2% with terminal-state description; without adding the description, the vendor prompt has no terminal-state section, so it still draws the same as the first frame, is rejected again, and each regeneration still charges normally. terminal_desc_missing=true from get_shot_prompts is this signal.",
+  "update_shot": "Shot-by-shot edit: change a single storyboard shot's text content (shot size/action/dialogue/visual description/camera movement, etc.), facial expression (expression_hint), duration (duration), final cut speed (speed_factor), character binding (character_ids), prop binding (prop_ids; full overwrite, [] clears—use it to fix a prop missed at import instead of re-importing the whole episode; edits do not auto-regenerate frames/video), voice-over marker (character_presence), and wardrobe binding (active_wardrobe_id / appearance_wardrobes). Send only fields to change; all others stay unchanged. ★Any shot edit (accepted or rejected) invalidates unconsumed quotes covering this shot; generation then returns 409 QUOTE_INVALIDATED—edit first, read back to verify, then quote. **Free** (pure text DB write). ★Changing dialogue automatically invalidates generated TTS voice-over and subtitles for this shot (tts must be regenerated); text edits do not auto-regenerate images/video. To make visuals follow text changes, edit then regen the corresponding shot. Use get_storyboards to inspect results (each shot includes character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes). ★★【Change clothes here, not in text】What appears in image generation is determined by **wardrobe binding**: single-character shots use active_wardrobe_id (one outfit for the whole shot); multi-character shots use appearance_wardrobes (per character). Writing \"wearing X clothes\" in description/action will not change clothes. Use list_wardrobe for wardrobe id; edits do not auto-regenerate images. To update visuals, regenerate this shot's first frame then video. ★★For native-audio shots (vendor-native audio), after changing dialogue the shot video is marked \"needs regeneration\"—because spoken lines are **baked into the video audio**. If you final-compose without regeneration, the final cut still speaks the old line (typical symptom: dialogue seems to have moved to another shot). compose_episode lists these shots under advisory `stale_video_after_edit`; correct handling is regenerate_shot_video before final compose. ★You may also directly edit this shot's four prompt bodies (image_prompt/video_prompt/first_frame_prompt/last_frame_prompt): read current values with get_shot_prompts first; do not overwrite from scratch. @char:N / @scene:M in the body are supplemental reference markers for image generation; keep them unchanged. ★Which character sheet is injected is determined by character_ids, and background by scene_id: deleting markers will not remove already-bound people from the image. To make someone not appear, edit character_ids; if they are voice-only, set character_presence to voice_only. Conversely, do not write @char markers for unbound characters—this will inject their image. ★★【If last-frame generation is blocked, edit here】If last-frame generation reports \"this shot is marked as a state change, but nowhere describes what it looks like at the end\" (TERMINAL_DESC_GATE), fix by writing **what the final image should look like** into this shot's last_frame_prompt, then regenerate the last frame. Do not retry image generation—shots of this type (action_motion_class=state_change without terminal state) historically succeed at 9.4%, versus 40.2% with terminal-state description; without adding the description, the vendor prompt has no terminal-state section, so it still draws the same as the first frame, is rejected again, and each regeneration still charges normally. terminal_desc_missing=true from get_shot_prompts is this signal.",
   "rederive_shot_contract": "Using this shot's **current** prompt body and character binding, let the platform re-derive the composition contract (how many visible people, whether the subject is a person or a partial/object, shot size). The contract itself is internal: cannot be read or edited directly. This tool only returns outcome: updated (changed and effective) / unchanged (derived result same as current) / rejected (derived result self-contradictory, not adopted, original contract kept) / no_candidate (no usable result, original contract kept) / stale (shot changed during derivation, result not written; call again after edits), plus note for next step. Insufficient credits returns 402. ★When to use: image generation/precheck/review repeatedly says the number of people is wrong, or a partial shot (hand/prop close-up) is treated as a full-person shot in generation or review, and you have already edited text or bindings—the autofiller only fills blanks and does not overwrite existing contracts; without this tool, edits will not enter the contract. ★Correct order: first update_shot to make the image text correct (who is visible, who is voice-only via character_presence voice_only, unbind anyone who should not appear from character_ids), then call this tool; calling without text edits usually returns unchanged. ★One text AI call, postpaid by token (same chain as autofill_storyboards); inform the customer before calling. ★Only changes this one contract field; does not touch dialogue/prompts/other specialized fields. Generated first/last frames are not auto-regenerated; to update visuals, regenerate frames for this shot (quote first). ★updated invalidates unconsumed frame/video quotes for this shot and the same episode; quote again afterward.",
   "get_shot_prompts": "Read the four prompt **bodies** for one shot (image_prompt=first-frame image / video_prompt=dynamic performance / first_frame_prompt=what it looks like at start / last_frame_prompt=what it looks like at end), for direct fine-tuning then writing back with update_shot. Free. ★terminal_desc_missing=true in the response means this shot is marked as a \"state change\" but none of the three places describes the terminal state—last-frame generation will be blocked by the pre-gate. Fix by writing the end state into last_frame_prompt (do not retry image generation; retry will inevitably be rejected again and still charged). ★Also returns the current description (visual description) and lighting (shot lighting)—review_storyboards forbidden-term matches are often in description, so read it here before editing; write lighting into lighting. ★Also returns expression_hint (author-specified facial expression for this shot; null=unspecified, platform infers from dialogue). Edit it with update_shot. expression_inferred is the storyboard AI's inferred expression when the script did not specify expression (read-only; null=no inference, or this shot's dialogue/action/mood/description/intensity changed and the inference is expired and no longer used); it has lower priority than expression_hint—if inference is unsatisfactory, write expression_hint with update_shot to override it. ★Per-shot on demand: read only the shot you edit (episode list get_storyboards does not include prompts). ★Returned asset_tokens are supplemental reference markers in the body (@char:N / @scene:M); keep them unchanged when rewriting. Which character sheet is injected is determined by bindings (character_ids / scene_id in get_storyboards); deleting markers will not remove bound characters. Markers with #variant are the only source for that variant image. Writing a marker for an unbound character will inject that character's image. ★This is the body layer in the storyboard sheet; during image/video generation the platform also appends identity anchors, consistency constraints, and reference-image instructions (not here, and you do not need to write them). Changing prompts does not auto-regenerate images/video; to update visuals, regen the corresponding shot.",
   "rerender_episode": "Recompose the final cut from the current timeline (use after shot edits/cropping). **Free** (pure ffmpeg+COS), asynchronous in background.",

package/dist/i18n/tools.zh-CN.json

@@ -8,12 +8,12 @@
   "edit_rewritten_script": "★改稿的**首选通道**:改 AI 改写后的可拍稿(写 script_content)。免费、秒级、结果确定不抽卡——**改写成功一次之后,所有修改都走这里,不要重跑 rewrite_script**(那是从原稿整篇重来,当前稿的修正全丢、已改好的地方会退回去)。★怎么点改(三步,别跳):① get_script 取回 rewritten_script **全文**;② **只改要改的那几场**——目标场次内改动词句/拆场/删挂错的 motif/补 [SFX]/移器物到 [道具] 行,其余场次连标点都逐字照抄;③ 把改完的**整篇**提交本工具(本工具是全文覆盖,所以未改动部分必须原样带回,不能只发片段、也不要让模型\"顺手重写\"没让它改的场)。典型可点改的问题:场次太长要拆、台词跨镜断句、时段/年代写错、motif 挂在没有该元素的场、[角色档案] 服装段混进手持器物、缺 [SFX]/[BGM] 标注。只用于修改 AI 改写产出的稿;本集还没跑过 rewrite_script 时会被 400 拒——这不是绕过改写的通道,别把自己写好的剧本直接贴进来。改坏了可用 get_script(include_previous=1) 取回上一版。免费。",
   "get_script_format_spec": "取本平台**认可的剧本格式契约**:markdown 范本全文 + external_prompt(可整段转发给任意外部 AI 的任务提示词) + skeleton(带 〈…〉 占位的模板) + filled_example(填好的成品对照)。免费·静态·不扣费。★范本 v2 起把**制作层标注**全写进去了([角色档案] 六段格式/[外貌] 行首标记/[道具]/[SFX][BGM][VFX]/motif/场景头第四段光线/文末元信息)——v1 只写剧情层,外部 AI 因此产不出完整稿、反复过不了自检。转发时**务必把 filled_example 一起给**:LLM 的格式正确率靠可模仿的完整样例,不靠规则条文。★什么时候用:客户想自己掌控改写幅度、要拿到别的 AI 平台去改写、或反馈\"你们的 AI 把我的剧本改动太大\"时。★两条出口(先问客户要哪条,这决定外部 AI 要不要写标注):【A 直接采用】外部 AI 产出**含制作层标注**的完整稿 → check_script_format 全绿 → adopt_external_script 直接落为可拍稿,我方 AI 完全不介入、秒级、不计费,客户写的 [角色档案] 原样生效。适合已经把外部 AI 调顺、要求零改动的客户。【B 送 AI 改写】外部 AI 只产出剧情层(**不要写任何标注**) → set_script 灌回原稿位 → rewrite_script 走保真两步补标注。★B 路径下客户自己写的标注**会被 G1 剥掉重写**,等于白写——所以选 B 就要明确告诉外部 AI 别写标注。★怎么用(三步):① 本工具取 external_prompt + filled_example + markdown,连同客户原稿一起交给那个平台;② 拿回整理稿先用 check_script_format 自查,errors 清零;③ 按出口 A 调 adopt_external_script,或按出口 B 调 set_script + rewrite_script。★契约内容含:场景头三段格式/地点命名律/环境首句三要素/角色首次出场外貌行/声音行前缀/单行台词长度/禁写运镜与片尾标记,以及\"台词逐句保留·人物不许丢·动作节拍不许丢·不许加戏\"四条保真要求(已写进 external_prompt)。",
   "check_script_format": "**回填前的格式自查**:把一段剧本正文按平台判据跑一遍,逐条返回问题。免费·纯规则·不调模型·不落库·可反复跑。★errors = 系统会**无条件拒收**的(空/过短/无场景头/含运镜词/含片尾编辑标记),必须清零再灌;warnings = 默认只告警(strictOnly=true 的那几条在项目开启严格模式后会变成拒收):场过长过短/无声音行/单行台词超上限/场景头缺段/场号跳号/[角色档案] 段数不对/写了档案却缺 [外貌] 行/说话人位混写年龄身份。★placeholder_left(残留 〈…〉 模板占位符)算 **error**:系统闸不查它,但占位符会原样落进正文被当画面内容,比被拒更糟。★场长按**剧情层**字数算([角色档案]/[外貌]/[道具]/[SFX] 等标注行不计入)——写全标注不会把场撑超 120 字,别为了过闸去删标注。★典型用法:外部 AI 整理完 → 本工具自查 → 把返回的 message 清单原样发回那个平台让它\"只修这些点、其余逐字照抄\" → 再查一遍 → 全绿后 set_script。★它只查**格式**;台词是否逐句保留、人物有没有丢这类保真判据要等 rewrite_script 时由平台对着原稿判(本工具没有原稿侧输入)。",
-  "import_storyboard_table": "【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent。免费。★三步走，别直接导：① get_storyboard_table_spec 取范本（景别/运镜白名单、正文落点、字卡语法、外部 AI 提示词）；② check_storyboard_table 自检到 errors 清零、逐条看 warnings（缺秒数/景别没认出/没画面叙述都会原样建进去）；③ 再调本工具。★什么时候用:客户交来的不是剧本而是成品分镜表(逐镜写了秒数/景别/运镜,常见于给电视台/品牌方的样片)。走 set_script→rewrite_script→generate_storyboards 那条路会把这些制作参数当非剧情内容剥掉(生产实测:8 镜 36 秒的表跑完变成 20 镜 109 秒,STYLE 块与数据卡全丢),所以这类客户必须走本工具。★声明格式(每镜一行,字段用 | 或全角 ｜ 分隔):`[镜 001 | 4s | 微距 | 固定]`,也认客户已有的加粗写法 `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(不必让客户重打一遍)。顺序 = 镜号|秒数|景别|运镜|标记;标记 `不切` 表示该镜绝不可再拆、`★` 表示关键镜;运镜的「横移」映射 tracking、「摇」映射 pan(两者在反光面上的倒影行为不同,别混)。`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲黑底卡,不出图不出视频)。★道具:`[道具] 名A、名B` 行按**本剧道具库里的道具名**绑定 prop_ids,正文里完整出现的道具名也自动绑;回执 prop_names_unresolved 列出没绑上的名字(先建道具再导,或改名)。★不传 content 时读本集「原始内容」。没有任何逐镜声明会被 400 拒(那是剧本不是分镜表,请走正常拆镜)。★本集已有分镜时返回 409 并告知镜数,确认要替换再带 confirm_replace:true(旧镜转已删除状态、可恢复)。秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(镜头意图/节拍/潜台词/J-L cut/声线等,只填空)并把每镜由平台拼的基础描述扩写成完整出图/视频提示词——客户导完即可出图。文本步按 token 后付,**调用前告知客户**;只想导入不补传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 auto_complete.started=true 后用 get_autofill_status 轮询到 done(每镜数十秒)**再** review_storyboards——补全会改镜,先审查的 token 会失效。",
+  "import_storyboard_table": "【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent。免费。★三步走，别直接导：① get_storyboard_table_spec 取范本（景别/运镜白名单、正文落点、字卡语法、外部 AI 提示词）；② check_storyboard_table 自检到 errors 清零、逐条看 warnings（缺秒数/景别没认出/没画面叙述都会原样建进去）；③ 再调本工具。★什么时候用:客户交来的不是剧本而是成品分镜表(逐镜写了秒数/景别/运镜,常见于给电视台/品牌方的样片)。走 set_script→rewrite_script→generate_storyboards 那条路会把这些制作参数当非剧情内容剥掉(生产实测:8 镜 36 秒的表跑完变成 20 镜 109 秒,STYLE 块与数据卡全丢),所以这类客户必须走本工具。★声明格式(每镜一行,字段用 | 或全角 ｜ 分隔):`[镜 001 | 4s | 微距 | 固定]`,也认客户已有的加粗写法 `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(不必让客户重打一遍)。顺序 = 镜号|秒数|景别|运镜|标记;标记 `不切` 表示该镜绝不可再拆、`★` 表示关键镜;运镜的「横移」映射 tracking、「摇」映射 pan(两者在反光面上的倒影行为不同,别混)。`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲黑底卡,不出图不出视频)。★道具:`[道具] 名A、名B` 行按**本剧道具库里的道具名**绑定 prop_ids,正文里完整出现的道具名也自动绑;回执 prop_names_unresolved 列出没绑上的名字(先建道具再导,或改名)。★不传 content 时读本集「原始内容」。没有任何逐镜声明会被 400 拒(那是剧本不是分镜表,请走正常拆镜)。★本集已有分镜时返回 409 并告知镜数,确认要替换再带 confirm_replace:true(旧镜转已删除状态、可恢复)。秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。★★先核绑定、再补全:autofill 跑完之后再重导,补全结果作废、要重新付费。拿不准角色/道具/场景能不能按名字绑上时,传 auto_complete:false 导入 → 对照**客户原稿**逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids(回执 props_possibly_unbound 列出画面里像有物件、却一个道具都没绑的镜) → 用 update_shot 补绑 → 确认无误再 quote_autofill / autofill_storyboards。导入后才发现漏绑也用 update_shot 补(prop_ids / character_ids),**不要整集重导**。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(镜头意图/节拍/潜台词/J-L cut/声线等,只填空)并把每镜由平台拼的基础描述扩写成完整出图/视频提示词——客户导完即可出图。文本步按 token 后付,**调用前告知客户**;只想导入不补传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 auto_complete.started=true 后用 get_autofill_status 轮询到 done(每镜数十秒)**再** review_storyboards——补全会改镜,先审查的 token 会失效。",
   "get_storyboard_table_spec": "取本平台**认可的分镜表格式契约**：markdown 范本全文 + external_prompt(可整段转发给任意外部 AI 的任务提示词) + skeleton(〈…〉占位骨架) + filled_example(成品对照) + checklist + shot_types(景别白名单) + movements(运镜白名单与认得的中文写法)。免费·静态·不扣费。★什么时候用:客户手上是成品分镜表(逐镜秒数/景别/运镜)、或想让外部 AI/自己的工具把镜头设计整理成我们认的格式时——**在 import_storyboard_table 之前**先调它。★契约要点:一镜一行 `[镜 001 | 4s | 特写 | 固定]`(加粗式/全角竖线/繁体也认);景别与运镜只认白名单里的词(写别的会留空);声明之后的正文=画面叙述(至少一行,否则出不了图)+ `角色名：台词` + [SFX:]/[BGM:]/[VFX:] 标注;整屏文字用 `[字卡 9s] 行一 | 行二`;STYLE/NEG 全片风格块**不写进表**(写进项目设定);`## 非场景标题` 会结束当前镜。转发给外部 AI 时**务必把 filled_example 一起给**:格式正确率靠可模仿的完整样例。",
   "check_storyboard_table": "**导入前的分镜表自检**:用导入端点**同一个解析器**跑一遍,返回 errors / warnings / stats / shots(逐镜解析预览:每一镜会变成什么秒数·景别·运镜·标记·正文字数)。免费·纯规则·不调模型·不落库·可反复跑。★errors = 导入会 400 的(空 / 没有任何逐镜声明=这不是分镜表)+ 残留 〈…〉 占位符;必须清零。★warnings = 导入照常但结果会缺东西的:缺秒数(按 4 秒建)/景别没认出(留空)/运镜没认出(留空)/声明后没画面叙述(出不了图的死镜)/没有场景头(绑不上场景)/数据卡没用字卡语法(不进成片)/单镜>15 秒/STYLE 块/镜号重复——把 message 清单原样发回外部 AI 让它只修这些点。★这里绿了,import_storyboard_table 就不会有 issues(同一份代码)。",
   "get_bulk_import_spec": "取**批量导入 JSON 的格式契约**:markdown 范本全文 + template(占位符模板,<...> 必须替换) + filled_example(成品对照,可直接照结构填) + external_prompt(转发给外部 AI/自己工具的任务提示词) + checklist + enums(mode/role/char_type/shot_type/action_motion_class 的合法值,与校验器同源) + limits(数组与字段上限)。免费·静态·不扣费。★什么时候用:客户能从自己的工具/表格导出结构化数据、或要让外部 AI 直接产出 JSON 一次建好本集分镜时——**在 bulk_import_storyboards 之前**先调它。★与 import_storyboard_table(文本一镜一行)的分工:数据本来就是结构化的走 JSON;客户手上是文本分镜表走那条。★契约要点:顶层 { mode, episode_meta?, characters?[], scenes?[], storyboards[] };characters[]/scenes[] **只是引用声明、不落库**(角色/场景/道具由 extract_assets 从剧本提取,导入按名字绑定已有的,所以先 extract 再导;道具不是角色,别写进 characters[]);storyboards 按 storyboard_number 去重;bound_characters 引用 characters[].name(或本剧已有角色名)、bound_props 引用本剧道具库里的道具名(不传则按正文里出现的道具名自动绑)、scene_ref 引用 scenes[] 的 location+time——引用不到会**静默跳过**;每镜 action/description 至少一个;dialogue 是 `说话人：台词`、别写舞台指示(会被念出来);image_prompt/video_prompt 可不填(没填的镜由平台按景别+场景+光线+action 拼基础描述);填了就**逐字照用**,平台不覆盖。frame_visual_contract 是内部帧契约,导入时忽略。",
   "check_bulk_import": "**导入前的 JSON 自检**:用导入端点**同一份 zod schema** 校验,再把导入路由的\"静默行为\"变成 warning。返回 errors / warnings / stats(镜数·总秒·角色·场景·mode·promptsToBuild)。免费·不落库·可反复跑。★errors = 导入会 400 或会出错覆盖的:不是合法 JSON / schema 不过(逐条带 path,如 storyboards[2].shot_type)/ 镜号重复 + 残留 <...> 占位符;必须清零。★warnings = 导入照常但会缺东西或有副作用的:bound_characters/scene_ref 引用不到(静默跳过)/ 没有 action+description(死镜)/ dialogue 含镜头语言(会被念出来)/ 单镜>15 秒 / action_overload(一镜塞了超过时长承载量的独立动作——约 3 秒 2 拍、5 秒 3 拍;一镜一个主要动作,另起的事拆下一镜;多人各做一件事可忽略)/ 镜号跳号 / mode=replace(替换本集全部分镜)/ 全无角色绑定(人物会漂)。★这里绿了,bulk_import_storyboards 就能一次过。",
-  "bulk_import_storyboards": "把一份结构化 JSON 一次性建成本集的分镜(按 storyboard_number 去重更新)。**不建角色/场景/道具**——它们由 extract_assets 从剧本提取,导入只按名字绑定已有的(回执 characters_unmatched / char_refs_unresolved 列出没绑上的;先 extract 再导)。免费·确定性·不调 AI。★三步走:① get_bulk_import_spec 取契约与成品示例;② check_bulk_import 自检到 errors 清零;③ 再调本工具。★mode=merge(默认)保留未提到的镜;mode=replace 替换本集**全部**分镜(旧镜与已生成图/视频归档可恢复、不会自动重挂)——replace(任何执行模式都须客户明确同意,托管也不例外)。★image_prompt / video_prompt 想自己写就直接写在每镜里,**逐字照用不被覆盖**;没填的镜平台拼基础描述(回执 base_prompts_built 是拼了几镜),导入后可用 get_shot_prompts 读、update_shot 改。(frame_visual_contract 是内部帧契约,导入时忽略。)★导入后:语速律会抬高装不下台词的镜(回执 speech_duration_raised / speech_duration_overflow)。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(只填空),并只给**没填 image_prompt、由平台拼了基础描述**的镜扩写完整出图/视频提示词(客户自己写的绝不覆盖;回执 auto_complete.prompt_shots)。文本步按 token 后付,**调用前告知客户**;只想导入传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 started=true 后用 get_autofill_status 轮询到 done **再** review_storyboards。",
+  "bulk_import_storyboards": "把一份结构化 JSON 一次性建成本集的分镜(按 storyboard_number 去重更新)。**不建角色/场景/道具**——它们由 extract_assets 从剧本提取,导入只按名字绑定已有的(回执 characters_unmatched / char_refs_unresolved 列出没绑上的;先 extract 再导)。免费·确定性·不调 AI。★三步走:① get_bulk_import_spec 取契约与成品示例;② check_bulk_import 自检到 errors 清零;③ 再调本工具。★mode=merge(默认)保留未提到的镜;mode=replace 替换本集**全部**分镜(旧镜与已生成图/视频归档可恢复、不会自动重挂)——replace(任何执行模式都须客户明确同意,托管也不例外)。★image_prompt / video_prompt 想自己写就直接写在每镜里,**逐字照用不被覆盖**;没填的镜平台拼基础描述(回执 base_prompts_built 是拼了几镜),导入后可用 get_shot_prompts 读、update_shot 改。(frame_visual_contract 是内部帧契约,导入时忽略。)★导入后:语速律会抬高装不下台词的镜(回执 speech_duration_raised / speech_duration_overflow)。★★先核绑定、再补全:autofill 跑完之后再重导,补全结果作废、要重新付费。拿不准角色/道具/场景能不能按名字绑上时,传 auto_complete:false 导入 → 对照**客户原稿**逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids(回执 props_possibly_unbound 列出画面里像有物件、却一个道具都没绑的镜) → 用 update_shot 补绑 → 确认无误再 quote_autofill / autofill_storyboards。导入后才发现漏绑也用 update_shot 补(prop_ids / character_ids),**不要整集重导**。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(只填空),并只给**没填 image_prompt、由平台拼了基础描述**的镜扩写完整出图/视频提示词(客户自己写的绝不覆盖;回执 auto_complete.prompt_shots)。文本步按 token 后付,**调用前告知客户**;只想导入传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 started=true 后用 get_autofill_status 轮询到 done **再** review_storyboards。",
   "get_autofill_status": "查本集后台补全批次(导入 auto_complete / autofill_storyboards 发起的 AI 一键填空)的进度与回执:{ status: running|done|failed|idle, total, done, ok, fail, skipped_no_gap, fields_written_counts, contract_coverage }。免费。★回执就是「补全写了什么」的证据:补全写的是内部叙事字段与构图契约,get_storyboards / get_shot_prompts **读不到**,回读看不到变化属正常——看这里的计数即可。skipped_no_gap=没有空缺、跳过未调 AI 未扣费的镜数;fields_written_counts=按字段名计的写入镜数(如 {shot_intent: 44});contract_coverage={total, missing_contract}=本集出图镜数与仍缺构图契约的镜数。只给计数、不给字段内容,把这几个数原样告诉客户。★导入带自动补全后必须等 status=done 再 review_storyboards / generate_frames——补全逐镜改写字段,先审查的 review_token 会因内容变化失效。每镜数十秒,整集可能十几分钟;轮询间隔 ≥10 秒,别紧轮。status=failed 或 fail>0 时看 fail 数,少量失败的镜可直接 autofill_storyboards 重跑(只填空模式下已补过的镜跳过、不调 AI、不扣费;只有没补过的镜计费)。",
   "adopt_external_script": "【出口 A】把外部 AI 按范本产出的稿子**直接采用为可拍稿**,我方 AI 完全不介入。秒级、不计费。★前置硬闸:服务端会先跑一遍格式自检,errors 非空直接 400 并把清单原样返回——先用 check_script_format 改到全绿再调本工具。warnings 不拦(与默认宽松模式的 save_script 同尺度)。★什么时候用:客户要求「一个字都别改我的稿」、且外部 AI 已经产出含制作层标注的完整稿。★什么时候**不要**用:客户只整理了剧情层(没写 [角色档案]/[外貌])——那种稿子直接采用会让下游缺角色档案与外貌锚,走出口 B(set_script + rewrite_script)由平台补标注更稳。★与 edit_rewritten_script 的分工:那个是**改已有改写稿**的点改通道(没跑过改写会 400);本工具是**首次落稿**的通道,专为「稿子在外部做好了」这一种情形开的,不是绕过改写的后门——闸在服务端,过不了就是过不了。旧稿会存进 previous_script,采用错了用 get_script(include_previous=1) 回捞。",
   "extract_assets": "从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)。后台异步,文本步后付不欠费。前置:已 rewrite_script 产出改写稿(新项目强制;人物档案从改写稿提取才与剧本、分镜自洽)。★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60 秒当失败判据。\n★【改写稿审查硬闸·免费】本步前必须先调 review_script:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。单镜工具(generate_shot_frame / regenerate_shot_video)只核本镜与相邻镜:改了别的镜不用复审;本镜、相邻镜或共享资产变了才 400——这时带 base_review_token=<旧 token> 调审查工具做增量复审,只重审变更镜,质检也只看变更镜。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费(acknowledge_review 只代表客户本人同意,任何执行模式都须客户明确同意,托管也不例外);托管环节只有白名单内的启发式 error 能带 auto_acknowledge:true 放行(平台判,不在白名单回 400 AUTOPILOT_MUST_ASK:must_ask_customer=true 才暂停问客户,false = 按 action 自修复审)。★灰度剧还要你(agent)亲自质检:按 review_script 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。★★【执行模式总纲·开工先读】确认过开场方案的剧先 get_production_plan 读 autopilot:专业模式(pro,或 autopilot.enabled=false、未确认方案)→ 下文所有「讲给客户、客户同意才做」照字面执行;一键(auto)/ 混合(custom)的**托管环节** → 不问客户:照 get_pipeline_status 的 next_action 按序推进,报价在预算硬上限内自行确认,每层产出后照常 review_* + agent 质检,审查与质检返回的 autopilot.next_step 告诉你这一层怎么走(白名单 error 带 auto_acknowledge:true / 自修第几轮 / 暂停问客户),照做;遇到选择照 autopilot.default_decisions;autopilot.never_auto_actions(mode=replace、删资产、覆盖客户上传图、allow_era_ref_conflict、克隆声音、交付验收)任何模式都要客户同意。★托管环节同一镜重出帧(generate_shot_frame)最多 3 轮、重出视频(regenerate_shot_video / edit_video_shot)最多 3 次,到上限平台回 409 AUTOPILOT_SHOT_REGEN_LIMIT(未扣费)——别换个工具绕,停下问客户:客户同意再出就照常报价、生成时带 customer_approved_more_regens:true(再给一份上限);客户接受现状就往下走,下一步收费调用带 acknowledge_review:true 记下确认。402 BUDGET_WOULD_EXCEED / 409 MODEL_UNAVAILABLE / 409 AUTOPILOT_SHOT_REGEN_LIMIT / 400 AUTOPILOT_MUST_ASK 且 must_ask_customer=true / pending_questions 非空 → 暂停,把 get_autopilot_log 的 pending_questions **汇总后一次性**问客户;客户把控的环节照专业模式问。出完片用 get_autopilot_log 的 report 向客户交付。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【时代契约·免费·非当代或超现实题材出图前必设】setting_brief 里的世界观是**自由文本**,只能提供背景、压不住画面;真正能压过视觉锁的是**结构化时代契约**:用 set_era_contract 设本集档位(modern/republican/historical/fantasy/surreal),get_era_contract 读现值。**不设就是空着**——平台只能靠提示词正文堆字对抗,现代物件混进古代画面、场景图画成别的时代,基本都由这里空着导致。★仙侠/奇幻/仙境类**必须填 fantasy,别填 historical**:后者要求考据写实,会把发光灵气、悬浮地貌、非人化形一并判成「不合时代」,把画面往写实古代拽。某一场要破例(如奇幻世界里一场现代回忆)用 update_scene 的 era_contract 单独覆写,场级压过集级。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**五道硬闸(不过会被 400 拒;④⑤与 agent 质检见下文)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。有 error 时默认拦截,客户明确知情并坚持才带 acknowledge_review:true(acknowledge_review 只代表客户本人同意,任何执行模式都须客户明确同意,托管也不例外);托管环节只有白名单内的启发式 error 能带 auto_acknowledge:true(见【执行模式总纲】)。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱)——★**要跑全集就先 run_drama_precheck**(剧级汇总·免费·只读):一次拿到每集问题数与 attention(该先修哪几集),按它定优先级,再对那几集跑 run_precheck 拿逐条明细;别一集一集盲扫。注意它的 not_covered——剧级跳过唯一要看图的那道 lint,「全剧 0 条」≠「全查过了」。★揪出来之后别自己盲改:plan_precheck_fix 让平台算出提案 → apply_precheck_fix 落库(采纳哪几条,托管=全部采纳按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log);分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。★换服装改的是结构化绑定:update_shot 的 active_wardrobe_id(整镜)/ appearance_wardrobes(多人逐角色),可覆盖、可清空——改文字描述不换衣服,也不用让客户去网页改。②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——别回头整篇替换剧本或在设定字段里另写一套,两套真相源打架是一致性事故的头号根源。★★**改写成功一次后就别再重跑 rewrite_script**:它是从原稿整篇重来,当前稿的所有修正全丢,且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;误重跑用 get_script(include_previous=1) 回捞上一版。generate_portraits_and_sheets(定妆图+设定图·分镜后建:先用 delete_character 删掉**全剧任何一集都不出场、后续集也不打算用**的出镜角色再出图——角色是剧级的,删了每一集的出帧装配都不再带它,只看本集分镜判不出来、拿不准就留着(一张定妆图的钱远小于后面某集丢身份锚);定妆图步对**所有未删的出镜角色**出图、不看分镜绑定,留着的都照常扣费;画外音角色(char_type=voiceover 的旁白/电话音)本就不出图、也没有分镜绑定,**别删**,配音还靠它)→★generate_color_script(色彩脚本·统一调色)→assign_voices(分配音色;旁白/角色库里没合适的→design_voice 按描述造一个,定样后 set_character_voice)→★quote_scene_images+generate_scene_images(空景基板·出帧前必做)→frames(默认只出首帧)→★tail_frame_plan(免费·哪几镜要独立尾帧)→frames(frame_type=last_frame)→★chain_frames(接缝·先 dry_run:true)→★review_frames→videos→generate_tts→compose;★★【接缝别跳·尾帧补完、review_frames 之前】首尾帧齐了之后调 chain_frames(dry_run:true,免费)看平台的接缝计划与 estimated_points(copy 免费、reframe 每道一张图),讲给客户、确认后不带 dry_run 执行;已接好的缝不进计划,重复调不重复扣费。★执行后 reframe 是**异步出图**:用 get_jobs 看计划里那些镜的 first_frame 出图行,等 pending/processing 全部结束(failed 的看 error_msg,单道用 chain_shot_from 重接)再 review_frames——旧首帧还在时 get_storyboards 的 frame_status 仍是 ready,看不出新图在出还是失败了。get_jobs 清空后再用 get_storyboards 核对 seam_state:晋升被拒的替换图不留在 get_jobs 里,那道缝会仍是 unchained(review_frames 也会报 seam_unchained),按它的 action 重接。没落地就审,审的是旧首帧,token 在新首帧落地后作废。逐镜/批量出帧的集平台多半没自动接过(get_storyboards 的 seam_state=unchained 就是),跳过它不报错——代价是镜与镜之间画面对不上,成片一处一个跳切。接完还担心拼起来跳(人物左右位置、运动方向、景别对不上),出视频前可选 audit_seam_directions(查主体跳边/运动反向/景别跳级)(先 dry_run 报价,按 token 扣费,提示性不拦),结论用 get_seam_directions 读、讲给客户挑着修。★★【尾帧别跳·出帧是两趟】generate_frames 默认只出首帧。约三成的镜**末态≠首态**(大运镜/物体脱手/状态改变),这些镜需要一张独立尾帧,而判据在平台侧、你从分镜文本猜不出来——所以首帧出完必须调一次免费的 tail_frame_plan 拿逐镜清单,再 frame_type=last_frame 补上(generate_frames 的响应体里 shots_needing_last_frame 就是这个数,不为 0 别直接去 review_frames)。跳过不报错、不拦你——代价是那些镜出视频时只有首帧一个锚,末态由模型自由发挥:动作做不到位、大运镜结束又回到起点构图。生产实测 32 集里 30 集整集只出了首帧,其中 23 集一路出完了视频。★★【尾帧被 TERMINAL_DESC_GATE 拦下时:改文本,不是重试】报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」的镜,用 update_shot 把**结束时画面什么样**写进该镜 last_frame_prompt,再重出尾帧。★更好的是**别撞**:出尾帧前先 get_storyboards 看一眼,terminal_desc_missing=true 的镜整集一次就列出来了(免费),先把它们的 last_frame_prompt 补齐再出,一次都不用被拒。逐镜也能问(get_shot_prompts 同名字段),但一集几十镜别那么干。不补描述直接重试是无效的——送厂商的提示词里根本没有终态段,画出来仍是首帧那个姿态、必然再次被终态审核拒,而每次都照常扣费(生产实测:没写终态的镜尾帧成功率 9.4%,写了的 40.2%)。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★★【空景基板别跳·这一步长期被第三方漏掉】场景图是**背景锚**:同一场的每个镜头帧都锚在它上面。不出基板照样能出帧、不报错、不拦你——代价是**每个场景的第一镜完全没有背景锚**(平台的兜底补图是「发现缺图就后台补一张」,补的那张给同场景后续镜用,触发它的那一镜自己等不到),而首镜往往正是定调的那一镜;后续镜之间背景也会漂。它跟定妆图是一对:定妆图锚人、场景图锚景,缺哪个漂哪个。进度自检看 `get_pipeline_status` 的 generate_scene_images 步(completed/total),`review_storyboards` 也会在出帧前把缺口报成 scene_plate_missing。★★【设定图别跳·定妆图≠设定图】定妆图是单人单张的身份锚;设定图是平台据定妆图生成的多视角 turnaround,是镜头帧/视频的一致性根锚(换角度·换光·服装几乎全靠它)。只出定妆图照样能出帧、不报错——代价是人物一换角度就漂、服装每镜不一样。用 generate_portraits_and_sheets 一键两步(每调一次推进一步,定妆图齐了再调一次才出设定图),或定妆图后接 generate_character_sheets。进度自检看 get_pipeline_status 的 generate_character_sheets 步(completed/total,portrait_only=只有定妆图的角色数)。★客户自带图:定妆图须单人、单张单角度、无文字;场景图须空景无人、无叠加文字——set_character_portrait/upload_scene_image 会自动检查、不合规 422 拒收。★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;分镜后阵容才定,先删不出场角色再出图才省(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script(没有现成歌曲:set_mv_lyrics 后先 suggest_mv_song_styles→quote_mv_song→generate_mv_song→get_mv_song→select_mv_song)。★★【④⑤两道新硬闸 + agent 亲自质检】④资产层:定妆图/设定图/场景图/道具图出完 → review_assets(在 generate_frames / generate_shot_frame 之前,它的 token 作为 asset_review_token、与分镜层 review_token 一起传);⑤视频与配音层:视频/配音/配乐出完 → review_videos(在 compose_episode 之前);成片出来后跑 review_final_cut。★★【成片前自检·review_videos 通过后、compose_episode 之前】别靠反复导出整片、手工试转场来找问题——逐镜与接缝的问题有专门工具,拼之前按序过一遍:①这一集换过定妆图 / 设定图 / 场景图 / 镜头帧 → 先 get_stale_portrait_frames(episode_id,免费)看哪些镜的在用帧还基于旧资产,拿不准该用哪一版的镜再 get_asset_versions(storyboard_id,免费)逐镜看版本与依赖(unknown 是证据不足、不是已过期;重出要付费,清单讲给客户由客户定);②scan_intra_shot_cuts(episode_id,免费)查厂商在单镜内自行硬切的镜;③逐镜 recommend_trim_window(storyboard_id,免费)看冻结尾段与有效动作区间(组内镜返回 applicable=false,跳过),有推荐就 trim_shot 应用(免费);④audit_seams(episode_id)查相邻镜接缝的剪辑连续性:默认 dry_run 只列待审范围(免费),真执行按实际文本 token 计费,讲给客户、客户明确接受后才带 dry_run:false + confirm_usage_billing:true,结果看 get_storyboards 的 seam_review;⑤再 compose_episode。拼完成片发现跳切 / 拖尾 / 接不上,回到这几个工具按镜定位后只修那几镜,别整片反复导出试错。这些都是提示性检查,不过闸;裁剪与接缝审核不让 review_videos 的 token 失效。★每一层审查之后你还要**亲自质检**:按返回的 agent_qc 逐件看素材(图下载看、视频抽帧看、文本通读),逐条答清单,submit_qc_report 提交;灰度剧没交报告那张 review_token 进不了下一步,报告有问题与 error 同样默认拦。平台判有没有,你判像不像、对不对。★★【单镜路径同样受审查闸】:generate_shot_frame 同样要带分镜层 review_token,regenerate_shot_video 同样要带镜头图片层 review_token——别指望用逐镜工具绕开审查(实测有整集 25 镜全靠单镜出帧、一道闸都没碰到的做法,成片返工全是真扣费)。出完帧**不会**让分镜层 token 失效(指纹只看分镜内容);只有改了分镜内容——update_shot / 导入 / 增删镜 / 改角色绑定——才要复审一次(免费、秒级)。出完一镜的帧只让本镜与相邻镜的**镜头图片层** token 失效;要对它们 regenerate_shot_video 时带 base_review_token 增量 review_frames 即可。★★【原声剧先锁声线,再批量出视频】use_clip_audio=true(默认)时每镜嗓音由视频厂商各自采样,不锁必漂,事后统一要逐镜重出。有客户授权音源→clone_voice+set_character_voice,在 generate_videos 之前;没有→每个说话角色先用单镜工具 quote_regenerate_shot_video→regenerate_shot_video 出一镜台词较长的(generate_videos 没有按镜参数、只批量补缺视频的镜;单镜重生对还没有视频的镜同样可用),用 set_voice_anchor_from_shot 从那一镜选定声线,再出其余镜。get_pipeline_status 的 native_voice_anchor 会列出还没锁的 unanchored_speakers 和锁之前出的、需要重出的 stale_shots。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★★【色彩脚本】generate_color_script 统一全片调色,分镜后、出帧前做;文本步无 quote_*,按用量后付。进度自检看 get_pipeline_status 的 generate_color_script,review_storyboards 会报色彩脚本缺口。★动作模板为可选实验:generate_motion_templates(动作模板提取)仅客户明确要求时在分镜后调用,文本步按用量后付。首尾帧默认不注入动作模板;缺模板无需补做,不阻碍出图、出视频或成片。视频模板可能被裁剪,不承诺送达或增益。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认 ChatGPT Image 2.5 Flare(gpt-image-2.5-flare·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认它;可选 gpt-image-2.5-sunburst(同价·中文字形与细节更准)/gemini-3.1-flash-image(香蕉2·71点)/gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0);generate_frames 可临时覆盖某次。★2.5 按输入量计费(基础11点+每张参考图18点),香蕉/Seedream 是一口价——参考图多的镜头要把这笔算进预算。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】★先调 get_production_menu:各引擎对写实真人/动漫等题材当前是否可用,以 get_production_menu 返回的 availability 为准(不可用的带 customer_note 与 expected_until,原样转告客户),不要凭本说明预设哪个模型不可用;菜单里不可用的模型别推荐。①写实真人剧→seedance-2.5(指令遵循/人脸细节最强·价格基准 720p=1×),预算敏感可 hailuo-3(约1/3成本·720p 约0.33×·强保真编辑·可出2K·但单镜约6分钟);★选定引擎后在 create_drama / update_project_settings 显式传 video_engine(取菜单里该题材可用的那个)——不传时平台只按画风兜底盖章,不保证落在菜单可用的引擎上;②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折·720p 约0.4×·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(720p 约0.6×·约1分钟);★价格一律按相对倍数讲(以 seedance-2.5 720p 为 1×),要给客户绝对点数先调 quote_* 报价;③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;④★★叙事剧(有对白、讲连贯故事、镜头节奏要稳的)慎选 wan3.0/prime:WAN 会在**单个分镜片内自行换机位硬切**(实测 11/12 镜有镜内跳切,对照 seedance-2.5 仅 1/6、hailuo-3 为 0/5),成片观感是「一个镜头里画面跳来跳去、切太快」;这是厂商指令遵循弱、提示词层拦不住(我方负向约束早已在其中且实测无效),事后只能换引擎重生。WAN 适合镜头本就短平快的风格化/空镜/产品镜;要稳定单镜叙事请选 seedance-2.5 或 hailuo-3。生成后可用 scan_intra_shot_cuts 核查;④b★★对白密集剧慎选 hailuo-3(与上一条的「镜内自剪」是两回事,这条讲**说不说得全台词**):原生音频引擎会念到镜头结束就停、也会自说自话,实测「台词没念完整」占比 hailuo-3 **50%**(26 镜,均为 8-30 原生音频修复之后所生成,故是引擎本身)、seedance-2.5 **23%**(294 镜);wan3.0 该维度**样本不足未测**(26 个样本全在同一修复之前,修复后仅 2 镜)——不要据此认为 WAN 差。客户报「话没说完」时先跑 scan_dialogue_coverage 分族,别默认去加长镜头(实测镜长够的镜里仍有 32% 没念全);⑤★镜长控制(所有引擎通用,WAN 上尤其明显):单镜保持 3~5 秒。镜头越长模型自由发挥空间越大——实测一个 16 秒单镜(邻镜都是 3~5 秒)在片内换了 4 次场景、人物中途消失 4 秒后又从画面边缘长出来,客户看到的就是「凭空多出一个人」。要长表演请拆成多个短镜再靠帧链衔接,别写 15 秒以上的单镜;【分辨率决策】草稿/迭代期:WAN 剧 480p(约0.2×最省)、其余 720p;成片交付:seedance 剧 720p(要高清交付选 1080p,约 720p 的 2.5 倍)、hailuo-3 剧 1080p(=2K·约0.53×)、WAN 剧 1080p(约0.8×);hailuo-3 无独立 480p 档(选了也按 768P 计费);create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\")。★首帧出完调免费的 tail_frame_plan 看哪几镜要独立尾帧,再 frame_type=last_frame 批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价(跑不跑按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log);既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions(采不采纳按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)。原稿是小说/大纲则自动走创作型改写(AI 铺钩子造情感点),两种客户各得其所、无需手动切换。要覆盖默认用 update_project_settings 的 rewrite_pipeline(auto/two_pass/single_forced)与 fidelity_enforce(1=保真硬闸)。客户说「AI 把我的剧本改偏了」时的处置:①确认完整原稿已进 set_script;②rewrite_pipeline 设 two_pass 强制保真后重跑 rewrite_script;③客户确认角色外观后用 update_character 的 profile_locked=1 锁定档案,防后续提取覆盖外貌导致定妆图换脸。★客户想在**别的 AI 平台**改写剧本(常见诉求:第三方模型评估我方改写\"改动太大\",客户想自己掌控改动幅度):先调 get_script_format_spec 拿平台认可的格式契约(markdown 范本 + 可直接转发给外部模型的 external_prompt + 空白骨架),把 external_prompt+范本+客户原稿一起交给那个平台;拿回整理稿后**先调 check_script_format 自查**(免费·纯规则·不调模型),errors 清零后有两条出口:【A】adopt_external_script 直接落为可拍稿(我方 AI 不介入·秒级·不计费,前提是外部稿含制作层标注);【B】set_script 灌回原稿位 + rewrite_script 走保真两步(外部只做剧情层时选这条,标注由平台补;客户自写的标注在这条路上会被剥掉重写)。★别把外部整理稿塞进 edit_rewritten_script(未跑过改写会被 400 拒),也别跳过 check_script_format 直接灌——格式不合规的稿子进来照样被闸拦,白跑一轮。★★客户交来的**已经是成品分镜表**(逐镜写了秒数/景别/运镜)时,以上两条都不适用——直接用 import_storyboard_table 建分镜,跳过改写与拆镜。走改写那条路会把秒数/景别/运镜/STYLE/文字卡当非剧情内容剥掉(生产实测 8 镜 36 秒→20 镜 109 秒)。★两条导入通道都是确定性的——写错了也会原样建进去,所以**先取契约再自检再导**:分镜表走 get_storyboard_table_spec → check_storyboard_table → import_storyboard_table;客户自己的工具/表格能导出结构化数据、或让外部 AI 直接产 JSON 时走 get_bulk_import_spec → check_bulk_import → bulk_import_storyboards(只建分镜;角色/场景/道具由 extract_assets 从剧本提取,导入按名字绑定已有的——先 extract 再导)。两条导入默认带 auto_complete(后台 AI 补专业字段 + 出图/视频提示词,文本步后付,调用前告知客户):回执 started=true 就用 get_autofill_status 轮询到 done 再 review_storyboards——补全会改镜,先审的 token 会失效。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。★★【开场方案·建剧后第一件事·免费】先问基本视频参数(项目类型/画幅/集数×每集分钟/题材:写实真人 realistic_human·动漫风格化 stylized·产品空镜 product/原声还是配音),再调 get_production_menu 拿**当前可用**的三档套餐(效果说明+实时预估(含文本步)+建议预算+不计入项)讲给客户——别凭记忆推荐模型,某些模型对某些题材会临时不可用,菜单已过滤;然后让客户选执行模式(pro 每步自己把控 / auto 一键出片 / custom 选环节托管)、预算 budget_points 与自动追加上限(0/10/20/30/50%):**默认建议**预算=所选档的 recommended_budget(不含文本的上界×1.2 再加文本估计)、追加=菜单的 recommended_overrun_pct(30%)——质检重出不在上界里,由追加兜底;建议归建议,最终数字由客户定,客户改了就按客户的。把汇总讲清楚、客户明确同意后才调 confirm_production_plan(customer_confirmed:true)——不许替客户确认。确认过方案的剧:收费派发前平台复核模型仍可用、报价上界不超过预算×(1+追加%),被拦(402 BUDGET_WOULD_EXCEED / 409 MODEL_UNAVAILABLE)就停下问客户,别自己换模型或调预算。confirm 返回 403 PRODUCTION_PLAN_NOT_OPEN = 本剧未开放(灰度),照原流程逐步确认。\n★【完成后质检】提取完用 get_characters / get_scenes / get_props 核对档案(名字、外貌、时代)与客户剧本一致;定妆图/设定图/场景图/道具图出完后由 review_assets 统一审覆盖与质量。\n★【出图后自动检查·按用量后付】道具图落库(AI 出图或上传)后,平台会自动做一次道具外形分析(看图补尺寸提示,账单名「道具外形分析」),灰度阀开时还会自动做一次道具时代审核(结果见 get_props 的 era_audit)。两笔都是小额视觉审核,事先告诉客户;别再手动 audit_prop_era 重复付费。",
@@ -33,7 +33,7 @@
   "lock_shot_video": "锁定某镜当前在用的视频为客户已验收版本(免费,不生成、不改素材)。用于客户明确说「这一镜就用这条」之后,首尾帧/场景/角色又被改过的情形:锁定后资产变动不再把这镜判过期——review_videos 不报 video_stale(改报 warning video_locked_frames_changed)、get_asset_versions 里这条 acceptance_locked=true 仍算当前有效(漂移原因照实列在 drift_while_locked)、原声剧声线 stale_shots 不列它、终拼预检不报编辑后未重生;regenerate_shot_video / edit_video_shot / repaint / reskin / 上传或清除实拍 / 整集 generate_videos 会替换它时一律 409 VIDEO_LOCKED。锁里冻结视频行 id 与它当时的生成输入(首尾帧 URL、prompt、参考清单)。只能锁当前在用的那条(传 generation_id 时必须正好是它,否则 409 NOT_CURRENT_VIDEO;本镜没视频 409 NO_VIDEO)。视频被别的路径换掉后锁自动失效(get_asset_versions 的 video_lock.broken=true)。★只有客户明确确认沿用才锁,不得把生成完成或模型判断当客户验收;要重出须客户同意后先 unlock_shot_video。",
   "unlock_shot_video": "解除某镜的已验收视频锁(免费)。解锁后立刻恢复原判:帧改过的镜重新报 video_stale,可以 regenerate_shot_video 重出。★只在客户同意放弃锁定版本、要换新视频时调用。返回 was_locked。",
   "get_asset_binding_repair_plan": "只读生成一集历史缺失场景绑定的可审核修复提案。返回原始地点/时段、候选 ID、匹配依据、歧义和 proposed_scene_id；applied=false，绝不按名字自动回填。逐项核对后才由客户决定是否改绑。免费。",
-  "get_storyboards": "读某一集的分镜列表(供审阅/查进度)。含每镜首帧(first_frame_image)与视频(video_url)是否就绪。asset_versions 按首帧/尾帧/视频分别给出 generated(已生成)、input_consistent(与当前输入一致)、review_valid(审核有效)、adopted(已采用)、current_effective(当前有效)。null=缺少证据；ready 只表示存在产物，不代表当前有效。旧素材仍可查看。★每镜带**台词与说话人**:dialogue(原文,无台词为 null)、dialogue_lines([{speaker,text}] 逐行,与字幕/配音同一个解析器拆的——这里的 speaker 就是成片里被配音的那个;舞台提示已剥),以及 is_key_moment(1=关键镜,走高端图模)与 emotion_intensity(1-10)。核对「台词有没有丢/谁说的/关键镜是哪几镜/情绪曲线」用这一次调用即可,不用逐镜拉;update_shot 改完台词也在这里核对。画面/视频/首尾帧提示词仍只在 get_shot_prompts 逐镜读。★每镜还带**结构化状态**:frame_status/video_status(ready/pending/authorizing/rejected/failed/none/not_required)、★video_status=ready 只表示视频已生成，不等于画面验收通过。video_quality_issues 若含 terminal_cut：status=suspected 表示片尾疑似短促切镜，cut_at_s/tail_duration_s 给出位置；status=unavailable 表示探测未完成，不能当检测通过。两者均暂停本次自动尾帧回写与续接，先复核视频；字段缺席不代表做过检测，也不要直接重试收费生成。★not_required=旁白/片尾卡镜:帧与视频由成片层渲染,本镜不需要生成——数补齐进度时把它当已完成,别重试。fail_reason(sensitive/text_sensitive/copyright/face_mismatch/account_overdue/quota_full/authorizing/insufficient_credits/transient/repeat_rejected/diagnosis_required/pair_collateral/model_unavailable/requote_required/needs_content_fix/contract_rejected/unknown)、retryable(true=可重试;false=先按fail_hint处理,勿原样重试)、fail_hint(人读文案)。★视频失败的镜还带 video_charge_status(charged=已扣 video_charged_points 点/no_charge_recorded=本地流水未记扣费/pending=扣费结论未出;没有该字段=扣费状态未知)。只有 charged 是确定结论;no_charge_recorded 不等于已退款,别替平台承诺,要确认扣没扣用 get_drama_bill。★requote_required=报价条件已变、本镜未派发未扣费:先 quote_videos 重新报价(免费)再发起。★model_unavailable=所选图片/视频模型的厂商已暂停或暂不可用:fail_hint 里列了当前可用的替代模型(扣没扣费以错误文案为准,别替平台向用户承诺已退款),问用户后用 update_project_settings 改 video_engine/image_model(或只对本镜用 regenerate_shot_video 的 model / generate_shot_frame 的 image_model)再生成,原样重试只会再失败。★diagnosis_required=同输入同细因连败或已有候选等待判决:先查看已有候选及审计依据。审计故障先重审同一候选,原因未知先复核,不得直接改剧本或重复生成。照 retryable 判该重试还是该改内容,别解析中文。★pair_collateral=同镜另一帧未通过、本帧随批结束——**本帧自身没被判不合格,别去改它**:有 reopen_pair_id 就用它只重掷有过错的一侧,否则直接重生本镜。★若某镜带 degraded_frames:[{frame_type,reason,reason_label,since,hint}],表示该帧是系统在同因连拒熔断后**放行**的(判据照记未拒),URL 上与干净帧无区别但需人工复核;不满意按 hint 修正输入后 generate_shot_frame 重生该帧。★terminal_desc_missing=true:该镜标为「状态改变」却三处都没说结束时什么样——**出尾帧前**就能看出来,现在整集一次拿到(此前只有 get_shot_prompts 能逐镜问,一集几十次没人会去问)。先 update_shot 把结束状态写进 last_frame_prompt 再出尾帧:照现状硬出的历史成功率 9.4%,写了终态的 40.2%,而每次被拒都照常扣费。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★first_frame_source/last_frame_source='upload' 表示该帧是**外部上传图**(绕开了身份锚/画风锚/best-of-N/帧审计整条质量链路)——人物·服装·画风漂移排查先看这些镜;外部图导致的漂移不是平台生成质量问题,修复正路是删掉外部图改走 generate_shot_frame 平台重生。★若某镜带 reopen_pair_id:该镜首尾帧同时生成时只有一侧真的有问题、另一侧是无辜陪拒,原样传给 generate_shot_frame 的 reopen_pair_id 参数可以只重掷有问题的那一侧(省一半算力/费用,不会拿去生成一张这次根本没打算重做的图)。没有这个字段就按 fail_reason/retryable 走常规重试。免费。★每镜还带**绑定**(只有 ID):character_ids(本镜绑定的角色)、character_bindings[{character_id,presence}](presence=on_screen 在画面 / voice_only 只有声音、不进画面)、scene_id、prop_ids、active_wardrobe_id(整镜服装)、appearance_wardrobes[{character_id,wardrobe_id}](逐角色服装锚,只列声明了服装的角色)。出图注入谁的定妆图/哪张场景图/哪些道具图由这几项决定;角色名对照 get_characters、道具名对照 get_props。改绑用 update_shot 的 character_ids(★全量覆盖,先从这里读现值再改,漏传即解绑)与 character_presence;改服装用 update_shot 的 active_wardrobe_id / appearance_wardrobes(可覆盖、可传 null 清空);改完再读一次本工具核对。character_bindings 缺席 = 这次没读到(不是没绑),空数组才是没绑。★启用双边版本审核时，seam_review.status 为 passed/failed/not_checked/stale；stale 是证据过期，不是画面失败，不据此付费重生。continuity_intent 可用 update_shot 明确。★每镜带 **seam_state**(本镜与上一镜的镜间接缝,与官网帧时间线同一判据):ok=已续接(首帧就是上镜尾帧,或平台做过首尾帧衔接、已落地且之后两侧都没再重生) / unchained=该连续却没接上(标了连续从没接过,或平台发起的衔接重生没落地:被拒/失败/还在生成——本镜 frame_status 会是 failed/processing;或衔接审过之后本镜首帧又被重生过) / broken=接过但没接上(seam_failed_dims 给出哪几维不连续:characters/wardrobe/props/lighting/scene;seam_audit_status=stale 且没有维度 = 上一镜尾帧在衔接之后又重生过,本镜首帧接的还是旧尾帧) / intended=有意切换(硬切/换场/时间跳跃/景别大跳/插入镜/外部上传帧),不用管 / missing=两侧帧没齐 / unknown=没标意图也没接过(系统没判,不是有问题) / na=首镜或旁白卡。seam_audit_status=pending 表示衔接已落地、平台的衔接审计还没出结论。出视频前只需处理 unchained 与 broken:整集用 chain_frames(先 dry_run),单道用 chain_shot_from_prev / chain_shot_from。",
+  "get_storyboards": "读某一集的分镜列表(供审阅/查进度)。含每镜首帧(first_frame_image)与视频(video_url)是否就绪。asset_versions 按首帧/尾帧/视频分别给出 generated(已生成)、input_consistent(与当前输入一致)、review_valid(审核有效)、adopted(已采用)、current_effective(当前有效)。null=缺少证据；ready 只表示存在产物，不代表当前有效。旧素材仍可查看。★每镜带**台词与说话人**:dialogue(原文,无台词为 null)、dialogue_lines([{speaker,text}] 逐行,与字幕/配音同一个解析器拆的——这里的 speaker 就是成片里被配音的那个;舞台提示已剥),以及 is_key_moment(1=关键镜,走高端图模)与 emotion_intensity(1-10)。核对「台词有没有丢/谁说的/关键镜是哪几镜/情绪曲线」用这一次调用即可,不用逐镜拉;update_shot 改完台词也在这里核对。画面/视频/首尾帧提示词仍只在 get_shot_prompts 逐镜读。★每镜还带**结构化状态**:frame_status/video_status(ready/pending/authorizing/rejected/failed/none/not_required)、★video_status=ready 只表示视频已生成，不等于画面验收通过。video_quality_issues 若含 terminal_cut：status=suspected 表示片尾疑似短促切镜，cut_at_s/tail_duration_s 给出位置；status=unavailable 表示探测未完成，不能当检测通过。两者均暂停本次自动尾帧回写与续接，先复核视频；字段缺席不代表做过检测，也不要直接重试收费生成。★not_required=旁白/片尾卡镜:帧与视频由成片层渲染,本镜不需要生成——数补齐进度时把它当已完成,别重试。fail_reason(sensitive/text_sensitive/copyright/face_mismatch/account_overdue/quota_full/authorizing/insufficient_credits/transient/repeat_rejected/diagnosis_required/pair_collateral/model_unavailable/requote_required/needs_content_fix/contract_rejected/unknown)、retryable(true=可重试;false=先按fail_hint处理,勿原样重试)、fail_hint(人读文案)。★视频失败的镜还带 video_charge_status(charged=已扣 video_charged_points 点/no_charge_recorded=本地流水未记扣费/pending=扣费结论未出;没有该字段=扣费状态未知)。只有 charged 是确定结论;no_charge_recorded 不等于已退款,别替平台承诺,要确认扣没扣用 get_drama_bill。★requote_required=报价条件已变、本镜未派发未扣费:先 quote_videos 重新报价(免费)再发起。★model_unavailable=所选图片/视频模型的厂商已暂停或暂不可用:fail_hint 里列了当前可用的替代模型(扣没扣费以错误文案为准,别替平台向用户承诺已退款),问用户后用 update_project_settings 改 video_engine/image_model(或只对本镜用 regenerate_shot_video 的 model / generate_shot_frame 的 image_model)再生成,原样重试只会再失败。★diagnosis_required=同输入同细因连败或已有候选等待判决:先查看已有候选及审计依据。审计故障先重审同一候选,原因未知先复核,不得直接改剧本或重复生成。照 retryable 判该重试还是该改内容,别解析中文。★pair_collateral=同镜另一帧未通过、本帧随批结束——**本帧自身没被判不合格,别去改它**:有 reopen_pair_id 就用它只重掷有过错的一侧,否则直接重生本镜。★若某镜带 degraded_frames:[{frame_type,reason,reason_label,since,hint}],表示该帧是系统在同因连拒熔断后**放行**的(判据照记未拒),URL 上与干净帧无区别但需人工复核;不满意按 hint 修正输入后 generate_shot_frame 重生该帧。★terminal_desc_missing=true:该镜标为「状态改变」却三处都没说结束时什么样——**出尾帧前**就能看出来,现在整集一次拿到(此前只有 get_shot_prompts 能逐镜问,一集几十次没人会去问)。先 update_shot 把结束状态写进 last_frame_prompt 再出尾帧:照现状硬出的历史成功率 9.4%,写了终态的 40.2%,而每次被拒都照常扣费。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★first_frame_source/last_frame_source='upload' 表示该帧是**外部上传图**(绕开了身份锚/画风锚/best-of-N/帧审计整条质量链路)——人物·服装·画风漂移排查先看这些镜;外部图导致的漂移不是平台生成质量问题,修复正路是删掉外部图改走 generate_shot_frame 平台重生。★若某镜带 reopen_pair_id:该镜首尾帧同时生成时只有一侧真的有问题、另一侧是无辜陪拒,原样传给 generate_shot_frame 的 reopen_pair_id 参数可以只重掷有问题的那一侧(省一半算力/费用,不会拿去生成一张这次根本没打算重做的图)。没有这个字段就按 fail_reason/retryable 走常规重试。免费。★每镜还带**绑定**(只有 ID):character_ids(本镜绑定的角色)、character_bindings[{character_id,presence}](presence=on_screen 在画面 / voice_only 只有声音、不进画面)、scene_id、prop_ids、active_wardrobe_id(整镜服装)、appearance_wardrobes[{character_id,wardrobe_id}](逐角色服装锚,只列声明了服装的角色)。出图注入谁的定妆图/哪张场景图/哪些道具图由这几项决定;角色名对照 get_characters、道具名对照 get_props。改绑用 update_shot 的 character_ids(★全量覆盖,先从这里读现值再改,漏传即解绑)与 character_presence;改道具绑定用 update_shot 的 prop_ids(同样全量覆盖,[] 清空);改服装用 update_shot 的 active_wardrobe_id / appearance_wardrobes(可覆盖、可传 null 清空);改完再读一次本工具核对。character_bindings 缺席 = 这次没读到(不是没绑),空数组才是没绑。★启用双边版本审核时，seam_review.status 为 passed/failed/not_checked/stale；stale 是证据过期，不是画面失败，不据此付费重生。continuity_intent 可用 update_shot 明确。★每镜带 **seam_state**(本镜与上一镜的镜间接缝,与官网帧时间线同一判据):ok=已续接(首帧就是上镜尾帧,或平台做过首尾帧衔接、已落地且之后两侧都没再重生) / unchained=该连续却没接上(标了连续从没接过,或平台发起的衔接重生没落地:被拒/失败/还在生成——本镜 frame_status 会是 failed/processing;或衔接审过之后本镜首帧又被重生过) / broken=接过但没接上(seam_failed_dims 给出哪几维不连续:characters/wardrobe/props/lighting/scene;seam_audit_status=stale 且没有维度 = 上一镜尾帧在衔接之后又重生过,本镜首帧接的还是旧尾帧) / intended=有意切换(硬切/换场/时间跳跃/景别大跳/插入镜/外部上传帧),不用管 / missing=两侧帧没齐 / unknown=没标意图也没接过(系统没判,不是有问题) / na=首镜或旁白卡。seam_audit_status=pending 表示衔接已落地、平台的衔接审计还没出结论。出视频前只需处理 unchained 与 broken:整集用 chain_frames(先 dry_run),单道用 chain_shot_from_prev / chain_shot_from。",
   "get_run_status": "(★免费·长耗时操作后必用)查这一集当前有没有 agent 正在跑。rewrite_script / extract_assets / generate_storyboards 都是**分钟级**后台任务,它们只回一句 status:\"generating\",本工具是唯一能区分「还在跑」与「已经结束」的手段。\n★典型耗时(生产实测):改写 2~4 分钟、拆镜 5~10 分钟——**单次 LLM 调用就可能 3~7 分钟**。所以 60 秒内查不到结果是完全正常的,绝不是失败。\n用法:发起后每 30~60 秒调一次。running:true = 还在跑,继续等,**千万不要重发**(重发拆镜会替换整集分镜,已调好/已出图的全丢、要重花钱);running:false = 那次已经结束,这时才去 get_storyboards / get_script 看产物有没有落库。\n⚠️ 服务重启会让在途登记归零,重启期间发起的运行也会显示为无在途。",
   "run_precheck": "(★推荐·免费质量闸)出图/出视频前跑生成前预检,把会被拒的镜提前揪出。免费、不扣费。强烈建议 generate_frames/generate_videos 前调,防白花钱被拒。\n查这几类:①真人肖像/克隆音色授权 ②图像审核高危词 ③配音覆盖与大空档 ④**指令自相矛盾(kind=prompt-conflict)**——同一镜里互斥的要求(如宽景别却标了特写主体、既要站立又要坐姿),这类镜**任何正确的图都满足不了**,不改就会反复被拒并反复扣费,出现时应先按提示改分镜再出图,而不是重试。\n★**怎么改不用你猜**:调 plan_precheck_fix 让平台算出提案(哪一镜、把什么改成什么),再用 apply_precheck_fix 落库(采纳哪几条,托管=全部采纳按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)——比你自己用 update_shot 盲改稳,那条路绕开了乐观锁与落库前复核。部分类别系统不替你改(提案里的 blocked),那些才需要人工调。\n★★**镜已经反复出不来时也回来跑这个**——本工具不只是事前预检。它同时报「同镜同因连拒已熔断(repeat-reject,24h 自动解除)」与「帧契约自相矛盾」,那正是\"这一镜怎么重掷都出不来\"的答案。**别盲重掷**:熔断在档时每次重掷都是全价重复同一个拒绝。\n⚠️ 它**不**检查首帧是否处在\"动作发生前\"(平台暂无该契约字段),也不替代 get_health_report。",
   "run_drama_precheck": "(★免费·只读)**整部剧**的体检汇总:一次拿到每一集有多少问题、哪几集该先修。run_precheck 是集级的,几十集的剧要打几十次还得自己汇总 —— 要跑全集时先调这个。\n回什么:episodes[] 逐集的 blockers/warnings/by_kind(按判据码计数),totals 全剧合计,attention[] = 最该先修的几集(按阻断数、告警数降序)。\n★**怎么用**:先看 attention 定优先级 → 对那几集调 run_precheck 拿逐条明细 → plan_precheck_fix / update_shot 去改 → 改完重跑本工具确认总数下来了。\n⚠️ **「全剧 0 条」不等于「全查过了」**:剧级为了能在一个请求里跑完,强制跳过唯一要看图的那道 lint(一集 25s 墙钟)。返回体的 not_covered 列着跳过了哪一类,要查那一类就去对应集跑 run_precheck。\n⚠️ episodes[].failed=true 的集是**没查成**(不是没问题),重调一次即可。truncated=true 说明集数超过 limit 上限,没扫完。",
@@ -48,7 +48,7 @@
   "submit_qc_report": "提交你(agent)亲自看素材做的质检报告。免费。先调对应层的 review_*(script / storyboards / assets / frames / videos),按返回的 agent_qc 逐件打开 materials 看、逐条回答 checklist,再调本工具。★平台只校验报告**是否完整**,不评判你的结论:checklist 每个 id 都要答(ok / issue / na,issue 必须写 note 说清哪件什么问题);materials 里的每个 ref 都要列进 inspected(漏一件就拒收并点名漏了哪些);有问题就 verdict=issues 并在 issues 里逐条写,有问题却报 pass 会被拒。★别走过场:没打开看就列进 inspected,等于替客户签了字——出了废片照常扣费。★verdict=issues 时这张 token 默认进不了下一步:把问题讲给客户,修完重新 review + 质检;客户明确知情并坚持照现状继续,下一步才带 acknowledge_review:true。★suggestions(修改建议):剧本层(agent_qc.suggestions_required=true)报了问题就必须给,其它层可选。每条写 problem + proposal,能直接改字的再给 before/after;返回会给每条编号(s1…)。把建议讲给客户,客户选采纳几条 / 全部直接执行 / 不改直接往下做(选哪条路;托管=只执行 priority=must 且不改客户原台词的按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)。审查之后内容又变了,报告会被拒,重新 review 后按新的 agent_qc 再质检。",
   "review_all": "(推荐·免费)三层一次跑完的整体体检:剧本+分镜+镜头图片。开工前摸底、交付前复查用。★它**不发 review_token** —— 进收费步前仍需对应层的 review_script / review_storyboards / review_frames 各跑一次(闸认的是「针对当前产出物刚审过」,不是「审过一次」)。",
   "quote_autofill": "报价:autofill_storyboards 要多少点。零扣费、不改任何数据。口径与补全本身一致:只填空模式下已经没有空缺的镜跳过、不计费;overwrite:true 全部计费。返回 { shots_to_fill(会真正调 AI 的镜数), shots_skipped_no_gap(没有空缺、跳过不扣费的镜数), estimated_points(预算上沿,按它备余额), typical_points(通常花费) }——两个点数都告诉客户,客户同意后再用**同样的** overwrite / storyboard_ids 调 autofill_storyboards。补全是后付文本步,报价不发 quote_id,也不锁价。",
-  "autofill_storyboards": "(推荐)AI 一键给全集(或 storyboard_ids 指定的几镜)分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付(按实际调 AI 的镜计费)。★**先 quote_autofill 报价**(同样的 overwrite / storyboard_ids),把 shots_to_fill 与 estimated_points / typical_points 告诉客户,**客户同意再跑**本工具。★跑完用 get_autofill_status 看回执(写了哪些字段各几镜、跳过几镜、还缺几镜契约)告诉客户——补全写的内部字段 get_storyboards 读不到,别让客户以为白扣。★拆镜落库时平台已自动补过一轮:只填空模式下已没有空缺的镜(六个叙事文本字段都已有、有台词的镜声音方向也已有,契约阀开时契约也已有)直接跳过,不调 AI、不扣费;overwrite:true 才会整集重跑并逐镜计费。★补全写的是叙事/节奏类内部字段与构图契约,get_storyboards / get_shot_prompts 不返回这些字段,回读看不到变化属正常,看 get_autofill_status 回执里的计数即可;它**不改**出图/视频提示词正文。★平台开启契约自动补全时,也会尝试给**没有构图契约**的镜补上契约(是否开启以导入回执 contract_coverage 的 note 为准;可见人数/主体范围/景别,出图与审核都按它判;默认 overwrite:false 时已有契约不动,**overwrite:true 会连已有契约一起重写**)——导入时关了 auto_complete、回执 contract_coverage 的 note 指向本工具的,出图前调一次。本集已有补全在跑时本次**不排队**(防重复点击重复扣费),新导入的镜要等 get_autofill_status 到 done 后再调。★想先小范围试跑看效果:传 storyboard_ids(1~50 个本集镜 id,用 get_storyboards 取),只补这些镜,其它镜不调 AI、不扣费;不传 = 整集。本集已有补全在跑时子集不启动,回执 started=false、reason=fill batch already running,等 get_autofill_status 到 done 再调。",
+  "autofill_storyboards": "(推荐)AI 一键给全集(或 storyboard_ids 指定的几镜)分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付(按实际调 AI 的镜计费)。★跑之前先确认角色/场景/道具绑定无误(对照客户原稿逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids)。补全之后发现漏绑用 update_shot 补绑即可,**不要整集重导**——重导会替换分镜、补全结果作废、要重新付费。★**先 quote_autofill 报价**(同样的 overwrite / storyboard_ids),把 shots_to_fill 与 estimated_points / typical_points 告诉客户,**客户同意再跑**本工具。★跑完用 get_autofill_status 看回执(写了哪些字段各几镜、跳过几镜、还缺几镜契约)告诉客户——补全写的内部字段 get_storyboards 读不到,别让客户以为白扣。★拆镜落库时平台已自动补过一轮:只填空模式下已没有空缺的镜(六个叙事文本字段都已有、有台词的镜声音方向也已有,契约阀开时契约也已有)直接跳过,不调 AI、不扣费;overwrite:true 才会整集重跑并逐镜计费。★补全写的是叙事/节奏类内部字段与构图契约,get_storyboards / get_shot_prompts 不返回这些字段,回读看不到变化属正常,看 get_autofill_status 回执里的计数即可;它**不改**出图/视频提示词正文。★平台开启契约自动补全时,也会尝试给**没有构图契约**的镜补上契约(是否开启以导入回执 contract_coverage 的 note 为准;可见人数/主体范围/景别,出图与审核都按它判;默认 overwrite:false 时已有契约不动,**overwrite:true 会连已有契约一起重写**)——导入时关了 auto_complete、回执 contract_coverage 的 note 指向本工具的,出图前调一次。本集已有补全在跑时本次**不排队**(防重复点击重复扣费),新导入的镜要等 get_autofill_status 到 done 后再调。★想先小范围试跑看效果:传 storyboard_ids(1~50 个本集镜 id,用 get_storyboards 取),只补这些镜,其它镜不调 AI、不扣费;不传 = 整集。本集已有补全在跑时子集不启动,回执 started=false、reason=fill batch already running,等 get_autofill_status 到 done 再调。",
   "enhance_shot_prompts": "(可选增强·★非必须·有副作用)AI 批量增强全集 image_prompt。★会**改写已有 prompt**(含手调的);且**务必 generate_frames 之前**做——出图后再改 prompt 会让图陈旧、要重生浪费钱。非跑通一部片的必需,客户点名再做。后台异步,文本步后付。",
   "complete_ending_motifs": "(可选增强·★非必须·条件性)给结尾段补全缺失的视觉母题(嫁接视觉回响到结尾镜)。★前置:该剧已设 motifs(没设=空操作);会**改结尾镜 action/描述**,务必出图前做(否则结尾镜已出图会陈旧)。后台异步,文本步后付。",
   "tail_frame_plan": "★免费只读:这一集**哪几镜需要独立尾帧**(末态≠首态的镜——大运镜/物体脱手/状态改变)。判定用的就是平台出视频时那套判据,你自己是猜不出来的,所以出完首帧务必调一次。返回 shots_needing_last_frame(总数)、ready(已有首帧、现在就能补尾帧的镜)、pending_first_frame(还需要尾帧但首帧尚未落地的镜——等首帧出完再调一次本工具)。拿到 ready 清单后:quote_frames + generate_frames 带 frame_type=last_frame 即可批量补。★尾帧补完(或本工具报 0)之后的下一步是接缝:chain_frames(dry_run:true) 看计划与预估、客户确认后执行,再 review_frames。★跳过尾帧不会报错,但那些镜出视频时只有首帧一个锚,末态由模型自由发挥——动作做不到位、大运镜结束又回到起点构图,多半就是这么来的。零扣费,可随时调。",
@@ -142,7 +142,7 @@
   "scan_voice_consistency": "★原声剧（视频自带人声）客户报「同一个角色前后嗓音不一样 / 声线漂了」时跑这个。免费（本地推理，不调厂商）。对每个有台词的镜，听厂商生成的人声：台词念没念全，以及声音像不像该角色绑定的声线锚。**异步**：立即返回，后台整集约 10 分钟；同一集同时只跑一条（重复调用返回 started=false）。默认跳过已对当前视频扫过的镜，rescan=true 全部重扫。用 get_voice_consistency 查进度和逐镜结果。",
   "get_voice_consistency": "查声线一致性扫描的进度与逐镜结果（scan_voice_consistency 启动的）。免费。summary.voice_mismatch=声音不像该角色声线锚的镜号（重点看）；dialogue_issues=台词没念完/念错/多出说话声的镜；not_scanned_or_stale=还没扫或视频换过需重扫。speaker_verdict=uncertain 表示人声太短判不了，不是问题。声线不一致的镜：先用 get_pipeline_status 的 native_voice_anchor 确认角色已绑声线，再 regenerate_shot_video 重出。",
   "scan_dialogue_coverage": "★客户报「话没说完就切 / 台词只念了一半」时先跑这个。默认**免费零扣费**(只读已落库的转录审计结果)。把该集每个原声镜的视频音轨与台词做词级比对,按族给出结论:truncated(念到一半就停) / off_script(念的大半不是台词:自说自话、重复上一镜、只有环境音) / extra_speech(台词念全了但还多念) / minor_gap(零星缺词,属转写误差,不必管) / ok。★判读:三个可上报的族**处置方向不同**,别一律加长镜头——实测镜长够的镜里仍有 21% 没念全,「太短」很少是真因(平台保存分镜时已按台词自动抬时长)。truncated/off_script 的正解都是 regenerate_shot_video(厂商每次说多少是随机的,重掷常能拿到整句);同一剧反复 off_script 则换引擎。★never_audited 是本报告最重要的一栏:那些镜从没被检测过,「没测过」不等于「没问题」。rescan=true 会对它们补跑 ASR 比对(耗算力、非瞬时,limit 控制单次上限),默认不跑。TTS 配音镜不在范围内(TTS 必然念全,低覆盖率只会是转写误差)。同一集若还伴随「切太快」,那是另一回事,跑 scan_intra_shot_cuts。",
-  "update_shot": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、镜间转场(transition_type / transition_duration_ms)、角色绑定(character_ids)、画外音标记(character_presence)与服装绑定(active_wardrobe_id / appearance_wardrobes)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes)。★★【换衣服改这里,不是改文字】出图穿什么由**服装绑定**决定:单人镜用 active_wardrobe_id(整镜一件),多人同框各穿各的用 appearance_wardrobes(逐角色)。把「穿某某衣服」写进 description/action 不会换衣服。服装 id 用 list_wardrobe 查;改完不会自动重出图,要让画面跟上需重生本镜首帧再重生视频。★★原声镜(厂商原生音频)改 dialogue 后,本镜视频会被标记「待重生」——因为台词是**烤进视频人声**的,不重生就终拼,成片里念的仍是改动前的台词(典型现象:台词像是跑到了别的镜头上)。compose_episode 会以 advisory `stale_video_after_edit` 列出这些镜;正确处置是先 regenerate_shot_video 再终拼。★也可直接改本镜的四条提示词正文(image_prompt/video_prompt/first_frame_prompt/last_frame_prompt):改前先用 get_shot_prompts 读现值,别凭空覆盖——正文里的 @char:N / @scene:M 是出图时的补充参考标记,照原样保留即可。★注入谁的定妆图由 character_ids 决定、背景由 scene_id 决定:删标记不会让已绑定的人从画面消失,要让某人不出现就改 character_ids,他只有声音(画外音)就用 character_presence 标 voice_only;反过来别给未绑定的角色写 @char 标记——会把他的图注入进来。★★【出尾帧被拦下就是来改这里】出尾帧若报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」(TERMINAL_DESC_GATE),修法是把**结束时画面是什么样**写进本镜 last_frame_prompt,然后重新出尾帧。别去重试出图——这类镜(action_motion_class=state_change 却没写终态)的尾帧历史成功率 9.4%,有终态描述的是 40.2%;不补描述就重生,送厂商的提示词里根本没有终态段,画出来仍和首帧一样、还是会被拒,而每次重生都照常扣费。get_shot_prompts 的 terminal_desc_missing=true 就是这个信号。",
+  "update_shot": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、镜间转场(transition_type / transition_duration_ms)、角色绑定(character_ids)、道具绑定(prop_ids)、画外音标记(character_presence)与服装绑定(active_wardrobe_id / appearance_wardrobes)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes)。★★【换衣服改这里,不是改文字】出图穿什么由**服装绑定**决定:单人镜用 active_wardrobe_id(整镜一件),多人同框各穿各的用 appearance_wardrobes(逐角色)。把「穿某某衣服」写进 description/action 不会换衣服。服装 id 用 list_wardrobe 查;改完不会自动重出图,要让画面跟上需重生本镜首帧再重生视频。★★原声镜(厂商原生音频)改 dialogue 后,本镜视频会被标记「待重生」——因为台词是**烤进视频人声**的,不重生就终拼,成片里念的仍是改动前的台词(典型现象:台词像是跑到了别的镜头上)。compose_episode 会以 advisory `stale_video_after_edit` 列出这些镜;正确处置是先 regenerate_shot_video 再终拼。★也可直接改本镜的四条提示词正文(image_prompt/video_prompt/first_frame_prompt/last_frame_prompt):改前先用 get_shot_prompts 读现值,别凭空覆盖——正文里的 @char:N / @scene:M 是出图时的补充参考标记,照原样保留即可。★注入谁的定妆图由 character_ids 决定、背景由 scene_id 决定:删标记不会让已绑定的人从画面消失,要让某人不出现就改 character_ids,他只有声音(画外音)就用 character_presence 标 voice_only;反过来别给未绑定的角色写 @char 标记——会把他的图注入进来。★★【出尾帧被拦下就是来改这里】出尾帧若报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」(TERMINAL_DESC_GATE),修法是把**结束时画面是什么样**写进本镜 last_frame_prompt,然后重新出尾帧。别去重试出图——这类镜(action_motion_class=state_change 却没写终态)的尾帧历史成功率 9.4%,有终态描述的是 40.2%;不补描述就重生,送厂商的提示词里根本没有终态段,画出来仍和首帧一样、还是会被拒,而每次重生都照常扣费。get_shot_prompts 的 terminal_desc_missing=true 就是这个信号。",
   "rederive_shot_contract": "按本镜**当前**的正文与角色绑定,让平台重新推导构图契约(画面里可见几人、主体是人物还是局部/道具、景别)。契约本身不对外,读不到也改不了;本工具只回结论 outcome:updated(已改并生效)/ unchanged(推出来和原来一样)/ rejected(推出来自相矛盾,未采用,原契约保留)/ no_candidate(没拿到可用结果,原契约保留)/ stale(推导期间本镜又被改过,结果未写入,改完再调一次),附 note 说下一步。点数不足回 402。★什么时候用:出图/预检/审核反复说人数不对、局部镜(手部/道具特写)被当成完整人物出图或审核,而你已经改过正文或绑定——补全器只填空、不覆盖已有契约,不调本工具改动不会进契约。★正确顺序:先 update_shot 把画面写对(谁在画面里、谁只出声音用 character_presence 标 voice_only、不该出现的人从 character_ids 解绑),再调本工具;不改正文直接调多半回 unchanged。★一次文本 AI 调用,按 token 后付(与 autofill_storyboards 同链路),调用前告知客户。★只改契约这一个字段,不碰台词/提示词/其它专业字段;已出的首尾帧不会自动重出,要让画面跟上需对本镜重新出帧(先报价)。★updated 会作废本镜及同集未消费的出帧/出视频报价,之后要重新报价。",
   "get_shot_prompts": "读某一镜的四条提示词**正文**(image_prompt=首帧画面 / video_prompt=动态表演 / first_frame_prompt=开始时什么样 / last_frame_prompt=结束时什么样),供直接微调后用 update_shot 写回。免费。★回执里的 terminal_desc_missing=true 表示本镜标为「状态改变」却三处都没说终态——出尾帧会被前置闸拦下,修法是把结束状态写进 last_frame_prompt(别重试出图,重试必然重复被拒且照常扣费)。★pose_timeline_stale 非 null = 本镜动作起止姿态里的秒数时间轴超出了当前时长(多见于改短 duration 后),出视频时那一端已自动不送;新时间轴写进 video_prompt。★同时回 description(画面描述)与 lighting(本镜用光)现值——review_storyboards 的禁区词命中常在 description,改前先在这里读;用光写 lighting。★同时回 expression_hint(本镜作者指定的面部表情,null=未指定、由平台按台词反推),改它用 update_shot。expression_inferred 是拆镜 AI 在剧本没写神态时按本镜内容推断的表情(只读;null=没推断,或本镜台词/动作/氛围/描述/强度改过、推断已过期不再使用);它优先级低于 expression_hint——推断不合意就用 update_shot 写 expression_hint 覆盖它。★逐镜按需:改哪镜读哪镜(整集列表 get_storyboards 不含提示词)。★返回的 asset_tokens 是正文里的补充参考标记(@char:N / @scene:M),改写时原样保留即可:本镜注入谁的定妆图由绑定决定(get_storyboards 的 character_ids / scene_id),删标记不会让已绑定的人消失;带 #变体 的标记是那张变体图的唯一来源;给未绑定的角色写标记会把他的图注入进来。★这是分镜表里的正文层;出图/出视频时平台还会在其上拼身份锚、一致性约束与参考图指令(不在此处,也无需你写)。改完提示词不会自动重出图/视频,要让画面跟上得再 regen 对应镜。",
   "rerender_episode": "按当前 timeline 重拼成片(改完镜/裁剪后用)。**免费**(纯 ffmpeg+COS),后台异步。",

package/dist/tools/produce.js

@@ -545,6 +545,10 @@ export function registerProduceTools(server, client) {
         '★不传 content 时读本集「原始内容」。没有任何逐镜声明会被 400 拒(那是剧本不是分镜表,请走正常拆镜)。' +
         '★本集已有分镜时返回 409 并告知镜数,确认要替换再带 confirm_replace:true(旧镜转已删除状态、可恢复)。' +
         '秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。' +
+        '★★先核绑定、再补全:autofill 跑完之后再重导,补全结果作废、要重新付费。拿不准角色/道具/场景能不能按名字绑上时,' +
+        '传 auto_complete:false 导入 → 对照**客户原稿**逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids' +
+        '(回执 props_possibly_unbound 列出画面里像有物件、却一个道具都没绑的镜) → 用 update_shot 补绑 → 确认无误再 quote_autofill / autofill_storyboards。' +
+        '导入后才发现漏绑也用 update_shot 补(prop_ids / character_ids),**不要整集重导**。' +
         '★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段' +
         '(镜头意图/节拍/潜台词/J-L cut/声线等,只填空)并把每镜由平台拼的基础描述扩写成完整出图/视频提示词——客户导完即可出图。' +
         '文本步按 token 后付,**调用前告知客户**;只想导入不补传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 auto_complete.started=true 后' +
@@ -592,6 +596,10 @@ export function registerProduceTools(server, client) {
         '★image_prompt / video_prompt 想自己写就直接写在每镜里,**逐字照用不被覆盖**;没填的镜平台拼基础描述(回执 base_prompts_built 是拼了几镜),导入后可用 get_shot_prompts 读、update_shot 改。' +
         '(frame_visual_contract 是内部帧契约,导入时忽略。)' +
         '★导入后:语速律会抬高装不下台词的镜(回执 speech_duration_raised / speech_duration_overflow)。' +
+        '★★先核绑定、再补全:autofill 跑完之后再重导,补全结果作废、要重新付费。拿不准角色/道具/场景能不能按名字绑上时,' +
+        '传 auto_complete:false 导入 → 对照**客户原稿**逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids' +
+        '(回执 props_possibly_unbound 列出画面里像有物件、却一个道具都没绑的镜) → 用 update_shot 补绑 → 确认无误再 quote_autofill / autofill_storyboards。' +
+        '导入后才发现漏绑也用 update_shot 补(prop_ids / character_ids),**不要整集重导**。' +
         '★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(只填空),' +
         '并只给**没填 image_prompt、由平台拼了基础描述**的镜扩写完整出图/视频提示词(客户自己写的绝不覆盖;回执 auto_complete.prompt_shots)。' +
         '文本步按 token 后付,**调用前告知客户**;只想导入传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 started=true 后用 get_autofill_status 轮询到 done **再** review_storyboards。', {
@@ -743,7 +751,7 @@ export function registerProduceTools(server, client) {
         '(presence=on_screen 在画面 / voice_only 只有声音、不进画面)、scene_id、prop_ids、active_wardrobe_id(整镜服装)、' +
         'appearance_wardrobes[{character_id,wardrobe_id}](逐角色服装锚,只列声明了服装的角色)。' +
         '出图注入谁的定妆图/哪张场景图/哪些道具图由这几项决定;角色名对照 get_characters、道具名对照 get_props。' +
-        '改绑用 update_shot 的 character_ids(★全量覆盖,先从这里读现值再改,漏传即解绑)与 character_presence;' +
+        '改绑用 update_shot 的 character_ids(★全量覆盖,先从这里读现值再改,漏传即解绑)与 character_presence;改道具绑定用 update_shot 的 prop_ids(同样全量覆盖,[] 清空);' +
         '改服装用 update_shot 的 active_wardrobe_id / appearance_wardrobes(可覆盖、可传 null 清空);' +
         '改完再读一次本工具核对。character_bindings 缺席 = 这次没读到(不是没绑),空数组才是没绑。' +
         '★启用双边版本审核时，seam_review.status 为 passed/failed/not_checked/stale；stale 是证据过期，不是画面失败，不据此付费重生。continuity_intent 可用 update_shot 明确。' +
@@ -929,6 +937,8 @@ export function registerProduceTools(server, client) {
         ...(storyboard_ids ? { storyboard_ids } : {}),
     })));
     server.tool('autofill_storyboards', '(推荐)AI 一键给全集(或 storyboard_ids 指定的几镜)分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付(按实际调 AI 的镜计费)。' +
+        '★跑之前先确认角色/场景/道具绑定无误(对照客户原稿逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids)。' +
+        '补全之后发现漏绑用 update_shot 补绑即可,**不要整集重导**——重导会替换分镜、补全结果作废、要重新付费。' +
         '★**先 quote_autofill 报价**(同样的 overwrite / storyboard_ids),把 shots_to_fill 与 estimated_points / typical_points 告诉客户,**客户同意再跑**本工具。' +
         '★跑完用 get_autofill_status 看回执(写了哪些字段各几镜、跳过几镜、还缺几镜契约)告诉客户——补全写的内部字段 get_storyboards 读不到,别让客户以为白扣。' +
         '★拆镜落库时平台已自动补过一轮:只填空模式下已没有空缺的镜(六个叙事文本字段都已有、有台词的镜声音方向也已有,契约阀开时契约也已有)直接跳过,不调 AI、不扣费;overwrite:true 才会整集重跑并逐镜计费。' +
@@ -1756,7 +1766,7 @@ export function registerProduceTools(server, client) {
         const suffix = qs.toString() ? `?${qs.toString()}` : '';
         return jsonResult(await client.produceGet(`/episodes/${episode_id}/dialogue-coverage${suffix}`));
     });
-    server.tool('update_shot', '逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、镜间转场(transition_type / transition_duration_ms)、角色绑定(character_ids)、画外音标记(character_presence)与服装绑定(active_wardrobe_id / appearance_wardrobes)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。' +
+    server.tool('update_shot', '逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、镜间转场(transition_type / transition_duration_ms)、角色绑定(character_ids)、道具绑定(prop_ids)、画外音标记(character_presence)与服装绑定(active_wardrobe_id / appearance_wardrobes)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。' +
         '**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);' +
         '改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes)。' +
         '★★【换衣服改这里,不是改文字】出图穿什么由**服装绑定**决定:单人镜用 active_wardrobe_id(整镜一件),' +
@@ -1781,6 +1791,11 @@ export function registerProduceTools(server, client) {
         continuity_intent: z.enum(['continuous_action', 'shot_change', 'insert_detail', 'jump_cut']).optional().describe('本镜相对上镜的剪辑意图：连续动作、换景别、插入细节、有意跳切。改变后旧双边审核失效；不自动生成或补审。'),
         character_ids: z.array(z.number().int().positive()).optional()
             .describe('本镜出场角色 ID 列表(★全量覆盖式,非增量,漏传的角色会被解绑)。决定出图时注入哪些角色的定妆图/设定图——非人角色(动物/生物)也必须绑定,否则形象会漂移。id 必须来自当前集已关联角色'),
+        prop_ids: z.array(z.number().int().positive()).max(8).optional()
+            .describe('本镜绑定的道具 ID 列表(★全量覆盖式,非增量,漏传的道具会被解绑;[] = 清空)。决定出图时注入哪些道具的道具图——' +
+            '导入后发现某镜漏绑道具就用这里补,不用整集重导。先用 get_storyboards 读本镜现值 prop_ids、在它基础上增删再整体传回;道具 ID 用 get_props 查。' +
+            '每个 id 必须是本剧未删除的道具,每镜最多 8 个,否则 400 且本请求一个字段都不写。' +
+            '★改完不会自动重出:已有首帧/尾帧/视频里没有新道具,回执带 prop_ids_note 时按它走(先 review_storyboards 复审,再重出本镜首帧,首帧换了视频会标过期再重生视频,都先报价)'),
         character_presence: z.array(z.object({
             character_id: z.number().int().positive(),
             presence: z.enum(['on_screen', 'voice_only']),

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.222",
-    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`). For video, quote == actual charge. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.222 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.223",
+    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`). For video, quote == actual charge. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.223 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -10022,7 +10022,7 @@
       "get": {
         "operationId": "get_storyboards",
         "summary": "读某一集的分镜列表(供审阅/查进度)",
-        "description": "读某一集的分镜列表(供审阅/查进度)。含每镜首帧(first_frame_image)与视频(video_url)是否就绪。asset_versions 按首帧/尾帧/视频分别给出 generated(已生成)、input_consistent(与当前输入一致)、review_valid(审核有效)、adopted(已采用)、current_effective(当前有效)。null=缺少证据；ready 只表示存在产物，不代表当前有效。旧素材仍可查看。★每镜带**台词与说话人**:dialogue(原文,无台词为 null)、dialogue_lines([{speaker,text}] 逐行,与字幕/配音同一个解析器拆的——这里的 speaker 就是成片里被配音的那个;舞台提示已剥),以及 is_key_moment(1=关键镜,走高端图模)与 emotion_intensity(1-10)。核对「台词有没有丢/谁说的/关键镜是哪几镜/情绪曲线」用这一次调用即可,不用逐镜拉;update_shot 改完台词也在这里核对。画面/视频/首尾帧提示词仍只在 get_shot_prompts 逐镜读。★每镜还带**结构化状态**:frame_status/video_status(ready/pending/authorizing/rejected/failed/none/not_required)、★video_status=ready 只表示视频已生成，不等于画面验收通过。video_quality_issues 若含 terminal_cut：status=suspected 表示片尾疑似短促切镜，cut_at_s/tail_duration_s 给出位置；status=unavailable 表示探测未完成，不能当检测通过。两者均暂停本次自动尾帧回写与续接，先复核视频；字段缺席不代表做过检测，也不要直接重试收费生成。★not_required=旁白/片尾卡镜:帧与视频由成片层渲染,本镜不需要生成——数补齐进度时把它当已完成,别重试。fail_reason(sensitive/text_sensitive/copyright/face_mismatch/account_overdue/quota_full/authorizing/insufficient_credits/transient/repeat_rejected/diagnosis_required/pair_collateral/model_unavailable/requote_required/needs_content_fix/contract_rejected/unknown)、retryable(true=可重试;false=先按fail_hint处理,勿原样重试)、fail_hint(人读文案)。★视频失败的镜还带 video_charge_status(charged=已扣 video_charged_points 点/no_charge_recorded=本地流水未记扣费/pending=扣费结论未出;没有该字段=扣费状态未知)。只有 charged 是确定结论;no_charge_recorded 不等于已退款,别替平台承诺,要确认扣没扣用 get_drama_bill。★requote_required=报价条件已变、本镜未派发未扣费:先 quote_videos 重新报价(免费)再发起。★model_unavailable=所选图片/视频模型的厂商已暂停或暂不可用:fail_hint 里列了当前可用的替代模型(扣没扣费以错误文案为准,别替平台向用户承诺已退款),问用户后用 update_project_settings 改 video_engine/image_model(或只对本镜用 regenerate_shot_video 的 model / generate_shot_frame 的 image_model)再生成,原样重试只会再失败。★diagnosis_required=同输入同细因连败或已有候选等待判决:先查看已有候选及审计依据。审计故障先重审同一候选,原因未知先复核,不得直接改剧本或重复生成。照 retryable 判该重试还是该改内容,别解析中文。★pair_collateral=同镜另一帧未通过、本帧随批结束——**本帧自身没被判不合格,别去改它**:有 reopen_pair_id 就用它只重掷有过错的一侧,否则直接重生本镜。★若某镜带 degraded_frames:[{frame_type,reason,reason_label,since,hint}],表示该帧是系统在同因连拒熔断后**放行**的(判据照记未拒),URL 上与干净帧无区别但需人工复核;不满意按 hint 修正输入后 generate_shot_frame 重生该帧。★terminal_desc_missing=true:该镜标为「状态改变」却三处都没说结束时什么样——**出尾帧前**就能看出来,现在整集一次拿到(此前只有 get_shot_prompts 能逐镜问,一集几十次没人会去问)。先 update_shot 把结束状态写进 last_frame_prompt 再出尾帧:照现状硬出的历史成功率 9.4%,写了终态的 40.2%,而每次被拒都照常扣费。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★first_frame_source/last_frame_source='upload' 表示该帧是**外部上传图**(绕开了身份锚/画风锚/best-of-N/帧审计整条质量链路)——人物·服装·画风漂移排查先看这些镜;外部图导致的漂移不是平台生成质量问题,修复正路是删掉外部图改走 generate_shot_frame 平台重生。★若某镜带 reopen_pair_id:该镜首尾帧同时生成时只有一侧真的有问题、另一侧是无辜陪拒,原样传给 generate_shot_frame 的 reopen_pair_id 参数可以只重掷有问题的那一侧(省一半算力/费用,不会拿去生成一张这次根本没打算重做的图)。没有这个字段就按 fail_reason/retryable 走常规重试。免费。★每镜还带**绑定**(只有 ID):character_ids(本镜绑定的角色)、character_bindings[{character_id,presence}](presence=on_screen 在画面 / voice_only 只有声音、不进画面)、scene_id、prop_ids、active_wardrobe_id(整镜服装)、appearance_wardrobes[{character_id,wardrobe_id}](逐角色服装锚,只列声明了服装的角色)。出图注入谁的定妆图/哪张场景图/哪些道具图由这几项决定;角色名对照 get_characters、道具名对照 get_props。改绑用 update_shot 的 character_ids(★全量覆盖,先从这里读现值再改,漏传即解绑)与 character_presence;改服装用 update_shot 的 active_wardrobe_id / appearance_wardrobes(可覆盖、可传 null 清空);改完再读一次本工具核对。character_bindings 缺席 = 这次没读到(不是没绑),空数组才是没绑。★启用双边版本审核时，seam_review.status 为 passed/failed/not_checked/stale；stale 是证据过期，不是画面失败，不据此付费重生。continuity_intent 可用 update_shot 明确。★每镜带 **seam_state**(本镜与上一镜的镜间接缝,与官网帧时间线同一判据):ok=已续接(首帧就是上镜尾帧,或平台做过首尾帧衔接、已落地且之后两侧都没再重生) / unchained=该连续却没接上(标了连续从没接过,或平台发起的衔接重生没落地:被拒/失败/还在生成——本镜 frame_status 会是 failed/processing;或衔接审过之后本镜首帧又被重生过) / broken=接过但没接上(seam_failed_dims 给出哪几维不连续:characters/wardrobe/props/lighting/scene;seam_audit_status=stale 且没有维度 = 上一镜尾帧在衔接之后又重生过,本镜首帧接的还是旧尾帧) / intended=有意切换(硬切/换场/时间跳跃/景别大跳/插入镜/外部上传帧),不用管 / missing=两侧帧没齐 / unknown=没标意图也没接过(系统没判,不是有问题) / na=首镜或旁白卡。seam_audit_status=pending 表示衔接已落地、平台的衔接审计还没出结论。出视频前只需处理 unchained 与 broken:整集用 chain_frames(先 dry_run),单道用 chain_shot_from_prev / chain_shot_from。",
+        "description": "读某一集的分镜列表(供审阅/查进度)。含每镜首帧(first_frame_image)与视频(video_url)是否就绪。asset_versions 按首帧/尾帧/视频分别给出 generated(已生成)、input_consistent(与当前输入一致)、review_valid(审核有效)、adopted(已采用)、current_effective(当前有效)。null=缺少证据；ready 只表示存在产物，不代表当前有效。旧素材仍可查看。★每镜带**台词与说话人**:dialogue(原文,无台词为 null)、dialogue_lines([{speaker,text}] 逐行,与字幕/配音同一个解析器拆的——这里的 speaker 就是成片里被配音的那个;舞台提示已剥),以及 is_key_moment(1=关键镜,走高端图模)与 emotion_intensity(1-10)。核对「台词有没有丢/谁说的/关键镜是哪几镜/情绪曲线」用这一次调用即可,不用逐镜拉;update_shot 改完台词也在这里核对。画面/视频/首尾帧提示词仍只在 get_shot_prompts 逐镜读。★每镜还带**结构化状态**:frame_status/video_status(ready/pending/authorizing/rejected/failed/none/not_required)、★video_status=ready 只表示视频已生成，不等于画面验收通过。video_quality_issues 若含 terminal_cut：status=suspected 表示片尾疑似短促切镜，cut_at_s/tail_duration_s 给出位置；status=unavailable 表示探测未完成，不能当检测通过。两者均暂停本次自动尾帧回写与续接，先复核视频；字段缺席不代表做过检测，也不要直接重试收费生成。★not_required=旁白/片尾卡镜:帧与视频由成片层渲染,本镜不需要生成——数补齐进度时把它当已完成,别重试。fail_reason(sensitive/text_sensitive/copyright/face_mismatch/account_overdue/quota_full/authorizing/insufficient_credits/transient/repeat_rejected/diagnosis_required/pair_collateral/model_unavailable/requote_required/needs_content_fix/contract_rejected/unknown)、retryable(true=可重试;false=先按fail_hint处理,勿原样重试)、fail_hint(人读文案)。★视频失败的镜还带 video_charge_status(charged=已扣 video_charged_points 点/no_charge_recorded=本地流水未记扣费/pending=扣费结论未出;没有该字段=扣费状态未知)。只有 charged 是确定结论;no_charge_recorded 不等于已退款,别替平台承诺,要确认扣没扣用 get_drama_bill。★requote_required=报价条件已变、本镜未派发未扣费:先 quote_videos 重新报价(免费)再发起。★model_unavailable=所选图片/视频模型的厂商已暂停或暂不可用:fail_hint 里列了当前可用的替代模型(扣没扣费以错误文案为准,别替平台向用户承诺已退款),问用户后用 update_project_settings 改 video_engine/image_model(或只对本镜用 regenerate_shot_video 的 model / generate_shot_frame 的 image_model)再生成,原样重试只会再失败。★diagnosis_required=同输入同细因连败或已有候选等待判决:先查看已有候选及审计依据。审计故障先重审同一候选,原因未知先复核,不得直接改剧本或重复生成。照 retryable 判该重试还是该改内容,别解析中文。★pair_collateral=同镜另一帧未通过、本帧随批结束——**本帧自身没被判不合格,别去改它**:有 reopen_pair_id 就用它只重掷有过错的一侧,否则直接重生本镜。★若某镜带 degraded_frames:[{frame_type,reason,reason_label,since,hint}],表示该帧是系统在同因连拒熔断后**放行**的(判据照记未拒),URL 上与干净帧无区别但需人工复核;不满意按 hint 修正输入后 generate_shot_frame 重生该帧。★terminal_desc_missing=true:该镜标为「状态改变」却三处都没说结束时什么样——**出尾帧前**就能看出来,现在整集一次拿到(此前只有 get_shot_prompts 能逐镜问,一集几十次没人会去问)。先 update_shot 把结束状态写进 last_frame_prompt 再出尾帧:照现状硬出的历史成功率 9.4%,写了终态的 40.2%,而每次被拒都照常扣费。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★first_frame_source/last_frame_source='upload' 表示该帧是**外部上传图**(绕开了身份锚/画风锚/best-of-N/帧审计整条质量链路)——人物·服装·画风漂移排查先看这些镜;外部图导致的漂移不是平台生成质量问题,修复正路是删掉外部图改走 generate_shot_frame 平台重生。★若某镜带 reopen_pair_id:该镜首尾帧同时生成时只有一侧真的有问题、另一侧是无辜陪拒,原样传给 generate_shot_frame 的 reopen_pair_id 参数可以只重掷有问题的那一侧(省一半算力/费用,不会拿去生成一张这次根本没打算重做的图)。没有这个字段就按 fail_reason/retryable 走常规重试。免费。★每镜还带**绑定**(只有 ID):character_ids(本镜绑定的角色)、character_bindings[{character_id,presence}](presence=on_screen 在画面 / voice_only 只有声音、不进画面)、scene_id、prop_ids、active_wardrobe_id(整镜服装)、appearance_wardrobes[{character_id,wardrobe_id}](逐角色服装锚,只列声明了服装的角色)。出图注入谁的定妆图/哪张场景图/哪些道具图由这几项决定;角色名对照 get_characters、道具名对照 get_props。改绑用 update_shot 的 character_ids(★全量覆盖,先从这里读现值再改,漏传即解绑)与 character_presence;改道具绑定用 update_shot 的 prop_ids(同样全量覆盖,[] 清空);改服装用 update_shot 的 active_wardrobe_id / appearance_wardrobes(可覆盖、可传 null 清空);改完再读一次本工具核对。character_bindings 缺席 = 这次没读到(不是没绑),空数组才是没绑。★启用双边版本审核时，seam_review.status 为 passed/failed/not_checked/stale；stale 是证据过期，不是画面失败，不据此付费重生。continuity_intent 可用 update_shot 明确。★每镜带 **seam_state**(本镜与上一镜的镜间接缝,与官网帧时间线同一判据):ok=已续接(首帧就是上镜尾帧,或平台做过首尾帧衔接、已落地且之后两侧都没再重生) / unchained=该连续却没接上(标了连续从没接过,或平台发起的衔接重生没落地:被拒/失败/还在生成——本镜 frame_status 会是 failed/processing;或衔接审过之后本镜首帧又被重生过) / broken=接过但没接上(seam_failed_dims 给出哪几维不连续:characters/wardrobe/props/lighting/scene;seam_audit_status=stale 且没有维度 = 上一镜尾帧在衔接之后又重生过,本镜首帧接的还是旧尾帧) / intended=有意切换(硬切/换场/时间跳跃/景别大跳/插入镜/外部上传帧),不用管 / missing=两侧帧没齐 / unknown=没标意图也没接过(系统没判,不是有问题) / na=首镜或旁白卡。seam_audit_status=pending 表示衔接已落地、平台的衔接审计还没出结论。出视频前只需处理 unchained 与 broken:整集用 chain_frames(先 dry_run),单道用 chain_shot_from_prev / chain_shot_from。",
         "tags": [
           "episodes"
         ],
@@ -10069,7 +10069,7 @@
       "post": {
         "operationId": "autofill_storyboards",
         "summary": "(推荐)AI 一键给全集(或 storyboard_ids 指定的几镜)分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)",
-        "description": "(推荐)AI 一键给全集(或 storyboard_ids 指定的几镜)分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付(按实际调 AI 的镜计费)。★**先 quote_autofill 报价**(同样的 overwrite / storyboard_ids),把 shots_to_fill 与 estimated_points / typical_points 告诉客户,**客户同意再跑**本工具。★跑完用 get_autofill_status 看回执(写了哪些字段各几镜、跳过几镜、还缺几镜契约)告诉客户——补全写的内部字段 get_storyboards 读不到,别让客户以为白扣。★拆镜落库时平台已自动补过一轮:只填空模式下已没有空缺的镜(六个叙事文本字段都已有、有台词的镜声音方向也已有,契约阀开时契约也已有)直接跳过,不调 AI、不扣费;overwrite:true 才会整集重跑并逐镜计费。★补全写的是叙事/节奏类内部字段与构图契约,get_storyboards / get_shot_prompts 不返回这些字段,回读看不到变化属正常,看 get_autofill_status 回执里的计数即可;它**不改**出图/视频提示词正文。★平台开启契约自动补全时,也会尝试给**没有构图契约**的镜补上契约(是否开启以导入回执 contract_coverage 的 note 为准;可见人数/主体范围/景别,出图与审核都按它判;默认 overwrite:false 时已有契约不动,**overwrite:true 会连已有契约一起重写**)——导入时关了 auto_complete、回执 contract_coverage 的 note 指向本工具的,出图前调一次。本集已有补全在跑时本次**不排队**(防重复点击重复扣费),新导入的镜要等 get_autofill_status 到 done 后再调。★想先小范围试跑看效果:传 storyboard_ids(1~50 个本集镜 id,用 get_storyboards 取),只补这些镜,其它镜不调 AI、不扣费;不传 = 整集。本集已有补全在跑时子集不启动,回执 started=false、reason=fill batch already running,等 get_autofill_status 到 done 再调。",
+        "description": "(推荐)AI 一键给全集(或 storyboard_ids 指定的几镜)分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付(按实际调 AI 的镜计费)。★跑之前先确认角色/场景/道具绑定无误(对照客户原稿逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids)。补全之后发现漏绑用 update_shot 补绑即可,**不要整集重导**——重导会替换分镜、补全结果作废、要重新付费。★**先 quote_autofill 报价**(同样的 overwrite / storyboard_ids),把 shots_to_fill 与 estimated_points / typical_points 告诉客户,**客户同意再跑**本工具。★跑完用 get_autofill_status 看回执(写了哪些字段各几镜、跳过几镜、还缺几镜契约)告诉客户——补全写的内部字段 get_storyboards 读不到,别让客户以为白扣。★拆镜落库时平台已自动补过一轮:只填空模式下已没有空缺的镜(六个叙事文本字段都已有、有台词的镜声音方向也已有,契约阀开时契约也已有)直接跳过,不调 AI、不扣费;overwrite:true 才会整集重跑并逐镜计费。★补全写的是叙事/节奏类内部字段与构图契约,get_storyboards / get_shot_prompts 不返回这些字段,回读看不到变化属正常,看 get_autofill_status 回执里的计数即可;它**不改**出图/视频提示词正文。★平台开启契约自动补全时,也会尝试给**没有构图契约**的镜补上契约(是否开启以导入回执 contract_coverage 的 note 为准;可见人数/主体范围/景别,出图与审核都按它判;默认 overwrite:false 时已有契约不动,**overwrite:true 会连已有契约一起重写**)——导入时关了 auto_complete、回执 contract_coverage 的 note 指向本工具的,出图前调一次。本集已有补全在跑时本次**不排队**(防重复点击重复扣费),新导入的镜要等 get_autofill_status 到 done 后再调。★想先小范围试跑看效果:传 storyboard_ids(1~50 个本集镜 id,用 get_storyboards 取),只补这些镜,其它镜不调 AI、不扣费;不传 = 整集。本集已有补全在跑时子集不启动,回执 started=false、reason=fill batch already running,等 get_autofill_status 到 done 再调。",
         "tags": [
           "episodes"
         ],
@@ -10211,7 +10211,7 @@
       "post": {
         "operationId": "bulk_import_storyboards",
         "summary": "把一份结构化 JSON 一次性建成本集的分镜(按 storyboard_number 去重更新)",
-        "description": "把一份结构化 JSON 一次性建成本集的分镜(按 storyboard_number 去重更新)。**不建角色/场景/道具**——它们由 extract_assets 从剧本提取,导入只按名字绑定已有的(回执 characters_unmatched / char_refs_unresolved 列出没绑上的;先 extract 再导)。免费·确定性·不调 AI。★三步走:① get_bulk_import_spec 取契约与成品示例;② check_bulk_import 自检到 errors 清零;③ 再调本工具。★mode=merge(默认)保留未提到的镜;mode=replace 替换本集**全部**分镜(旧镜与已生成图/视频归档可恢复、不会自动重挂)——replace(任何执行模式都须客户明确同意,托管也不例外)。★image_prompt / video_prompt 想自己写就直接写在每镜里,**逐字照用不被覆盖**;没填的镜平台拼基础描述(回执 base_prompts_built 是拼了几镜),导入后可用 get_shot_prompts 读、update_shot 改。(frame_visual_contract 是内部帧契约,导入时忽略。)★导入后:语速律会抬高装不下台词的镜(回执 speech_duration_raised / speech_duration_overflow)。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(只填空),并只给**没填 image_prompt、由平台拼了基础描述**的镜扩写完整出图/视频提示词(客户自己写的绝不覆盖;回执 auto_complete.prompt_shots)。文本步按 token 后付,**调用前告知客户**;只想导入传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 started=true 后用 get_autofill_status 轮询到 done **再** review_storyboards。",
+        "description": "把一份结构化 JSON 一次性建成本集的分镜(按 storyboard_number 去重更新)。**不建角色/场景/道具**——它们由 extract_assets 从剧本提取,导入只按名字绑定已有的(回执 characters_unmatched / char_refs_unresolved 列出没绑上的;先 extract 再导)。免费·确定性·不调 AI。★三步走:① get_bulk_import_spec 取契约与成品示例;② check_bulk_import 自检到 errors 清零;③ 再调本工具。★mode=merge(默认)保留未提到的镜;mode=replace 替换本集**全部**分镜(旧镜与已生成图/视频归档可恢复、不会自动重挂)——replace(任何执行模式都须客户明确同意,托管也不例外)。★image_prompt / video_prompt 想自己写就直接写在每镜里,**逐字照用不被覆盖**;没填的镜平台拼基础描述(回执 base_prompts_built 是拼了几镜),导入后可用 get_shot_prompts 读、update_shot 改。(frame_visual_contract 是内部帧契约,导入时忽略。)★导入后:语速律会抬高装不下台词的镜(回执 speech_duration_raised / speech_duration_overflow)。★★先核绑定、再补全:autofill 跑完之后再重导,补全结果作废、要重新付费。拿不准角色/道具/场景能不能按名字绑上时,传 auto_complete:false 导入 → 对照**客户原稿**逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids(回执 props_possibly_unbound 列出画面里像有物件、却一个道具都没绑的镜) → 用 update_shot 补绑 → 确认无误再 quote_autofill / autofill_storyboards。导入后才发现漏绑也用 update_shot 补(prop_ids / character_ids),**不要整集重导**。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(只填空),并只给**没填 image_prompt、由平台拼了基础描述**的镜扩写完整出图/视频提示词(客户自己写的绝不覆盖;回执 auto_complete.prompt_shots)。文本步按 token 后付,**调用前告知客户**;只想导入传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 started=true 后用 get_autofill_status 轮询到 done **再** review_storyboards。",
         "tags": [
           "episodes"
         ],
@@ -10453,7 +10453,7 @@
       "post": {
         "operationId": "import_storyboard_table",
         "summary": "【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent",
-        "description": "【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent。免费。★三步走，别直接导：① get_storyboard_table_spec 取范本（景别/运镜白名单、正文落点、字卡语法、外部 AI 提示词）；② check_storyboard_table 自检到 errors 清零、逐条看 warnings（缺秒数/景别没认出/没画面叙述都会原样建进去）；③ 再调本工具。★什么时候用:客户交来的不是剧本而是成品分镜表(逐镜写了秒数/景别/运镜,常见于给电视台/品牌方的样片)。走 set_script→rewrite_script→generate_storyboards 那条路会把这些制作参数当非剧情内容剥掉(生产实测:8 镜 36 秒的表跑完变成 20 镜 109 秒,STYLE 块与数据卡全丢),所以这类客户必须走本工具。★声明格式(每镜一行,字段用 | 或全角 ｜ 分隔):`[镜 001 | 4s | 微距 | 固定]`,也认客户已有的加粗写法 `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(不必让客户重打一遍)。顺序 = 镜号|秒数|景别|运镜|标记;标记 `不切` 表示该镜绝不可再拆、`★` 表示关键镜;运镜的「横移」映射 tracking、「摇」映射 pan(两者在反光面上的倒影行为不同,别混)。`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲黑底卡,不出图不出视频)。★道具:`[道具] 名A、名B` 行按**本剧道具库里的道具名**绑定 prop_ids,正文里完整出现的道具名也自动绑;回执 prop_names_unresolved 列出没绑上的名字(先建道具再导,或改名)。★不传 content 时读本集「原始内容」。没有任何逐镜声明会被 400 拒(那是剧本不是分镜表,请走正常拆镜)。★本集已有分镜时返回 409 并告知镜数,确认要替换再带 confirm_replace:true(旧镜转已删除状态、可恢复)。秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(镜头意图/节拍/潜台词/J-L cut/声线等,只填空)并把每镜由平台拼的基础描述扩写成完整出图/视频提示词——客户导完即可出图。文本步按 token 后付,**调用前告知客户**;只想导入不补传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 auto_complete.started=true 后用 get_autofill_status 轮询到 done(每镜数十秒)**再** review_storyboards——补全会改镜,先审查的 token 会失效。",
+        "description": "【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent。免费。★三步走，别直接导：① get_storyboard_table_spec 取范本（景别/运镜白名单、正文落点、字卡语法、外部 AI 提示词）；② check_storyboard_table 自检到 errors 清零、逐条看 warnings（缺秒数/景别没认出/没画面叙述都会原样建进去）；③ 再调本工具。★什么时候用:客户交来的不是剧本而是成品分镜表(逐镜写了秒数/景别/运镜,常见于给电视台/品牌方的样片)。走 set_script→rewrite_script→generate_storyboards 那条路会把这些制作参数当非剧情内容剥掉(生产实测:8 镜 36 秒的表跑完变成 20 镜 109 秒,STYLE 块与数据卡全丢),所以这类客户必须走本工具。★声明格式(每镜一行,字段用 | 或全角 ｜ 分隔):`[镜 001 | 4s | 微距 | 固定]`,也认客户已有的加粗写法 `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(不必让客户重打一遍)。顺序 = 镜号|秒数|景别|运镜|标记;标记 `不切` 表示该镜绝不可再拆、`★` 表示关键镜;运镜的「横移」映射 tracking、「摇」映射 pan(两者在反光面上的倒影行为不同,别混)。`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲黑底卡,不出图不出视频)。★道具:`[道具] 名A、名B` 行按**本剧道具库里的道具名**绑定 prop_ids,正文里完整出现的道具名也自动绑;回执 prop_names_unresolved 列出没绑上的名字(先建道具再导,或改名)。★不传 content 时读本集「原始内容」。没有任何逐镜声明会被 400 拒(那是剧本不是分镜表,请走正常拆镜)。★本集已有分镜时返回 409 并告知镜数,确认要替换再带 confirm_replace:true(旧镜转已删除状态、可恢复)。秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。★★先核绑定、再补全:autofill 跑完之后再重导,补全结果作废、要重新付费。拿不准角色/道具/场景能不能按名字绑上时,传 auto_complete:false 导入 → 对照**客户原稿**逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids(回执 props_possibly_unbound 列出画面里像有物件、却一个道具都没绑的镜) → 用 update_shot 补绑 → 确认无误再 quote_autofill / autofill_storyboards。导入后才发现漏绑也用 update_shot 补(prop_ids / character_ids),**不要整集重导**。★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(镜头意图/节拍/潜台词/J-L cut/声线等,只填空)并把每镜由平台拼的基础描述扩写成完整出图/视频提示词——客户导完即可出图。文本步按 token 后付,**调用前告知客户**;只想导入不补传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 auto_complete.started=true 后用 get_autofill_status 轮询到 done(每镜数十秒)**再** review_storyboards——补全会改镜,先审查的 token 会失效。",
         "tags": [
           "episodes"
         ],
@@ -13261,7 +13261,7 @@
       "put": {
         "operationId": "update_shot",
         "summary": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、镜间转场(transition_type / transiti",
-        "description": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、镜间转场(transition_type / transition_duration_ms)、角色绑定(character_ids)、画外音标记(character_presence)与服装绑定(active_wardrobe_id / appearance_wardrobes)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes)。★★【换衣服改这里,不是改文字】出图穿什么由**服装绑定**决定:单人镜用 active_wardrobe_id(整镜一件),多人同框各穿各的用 appearance_wardrobes(逐角色)。把「穿某某衣服」写进 description/action 不会换衣服。服装 id 用 list_wardrobe 查;改完不会自动重出图,要让画面跟上需重生本镜首帧再重生视频。★★原声镜(厂商原生音频)改 dialogue 后,本镜视频会被标记「待重生」——因为台词是**烤进视频人声**的,不重生就终拼,成片里念的仍是改动前的台词(典型现象:台词像是跑到了别的镜头上)。compose_episode 会以 advisory `stale_video_after_edit` 列出这些镜;正确处置是先 regenerate_shot_video 再终拼。★也可直接改本镜的四条提示词正文(image_prompt/video_prompt/first_frame_prompt/last_frame_prompt):改前先用 get_shot_prompts 读现值,别凭空覆盖——正文里的 @char:N / @scene:M 是出图时的补充参考标记,照原样保留即可。★注入谁的定妆图由 character_ids 决定、背景由 scene_id 决定:删标记不会让已绑定的人从画面消失,要让某人不出现就改 character_ids,他只有声音(画外音)就用 character_presence 标 voice_only;反过来别给未绑定的角色写 @char 标记——会把他的图注入进来。★★【出尾帧被拦下就是来改这里】出尾帧若报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」(TERMINAL_DESC_GATE),修法是把**结束时画面是什么样**写进本镜 last_frame_prompt,然后重新出尾帧。别去重试出图——这类镜(action_motion_class=state_change 却没写终态)的尾帧历史成功率 9.4%,有终态描述的是 40.2%;不补描述就重生,送厂商的提示词里根本没有终态段,画出来仍和首帧一样、还是会被拒,而每次重生都照常扣费。get_shot_prompts 的 terminal_desc_missing=true 就是这个信号。",
+        "description": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、镜间转场(transition_type / transition_duration_ms)、角色绑定(character_ids)、道具绑定(prop_ids)、画外音标记(character_presence)与服装绑定(active_wardrobe_id / appearance_wardrobes)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes)。★★【换衣服改这里,不是改文字】出图穿什么由**服装绑定**决定:单人镜用 active_wardrobe_id(整镜一件),多人同框各穿各的用 appearance_wardrobes(逐角色)。把「穿某某衣服」写进 description/action 不会换衣服。服装 id 用 list_wardrobe 查;改完不会自动重出图,要让画面跟上需重生本镜首帧再重生视频。★★原声镜(厂商原生音频)改 dialogue 后,本镜视频会被标记「待重生」——因为台词是**烤进视频人声**的,不重生就终拼,成片里念的仍是改动前的台词(典型现象:台词像是跑到了别的镜头上)。compose_episode 会以 advisory `stale_video_after_edit` 列出这些镜;正确处置是先 regenerate_shot_video 再终拼。★也可直接改本镜的四条提示词正文(image_prompt/video_prompt/first_frame_prompt/last_frame_prompt):改前先用 get_shot_prompts 读现值,别凭空覆盖——正文里的 @char:N / @scene:M 是出图时的补充参考标记,照原样保留即可。★注入谁的定妆图由 character_ids 决定、背景由 scene_id 决定:删标记不会让已绑定的人从画面消失,要让某人不出现就改 character_ids,他只有声音(画外音)就用 character_presence 标 voice_only;反过来别给未绑定的角色写 @char 标记——会把他的图注入进来。★★【出尾帧被拦下就是来改这里】出尾帧若报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」(TERMINAL_DESC_GATE),修法是把**结束时画面是什么样**写进本镜 last_frame_prompt,然后重新出尾帧。别去重试出图——这类镜(action_motion_class=state_change 却没写终态)的尾帧历史成功率 9.4%,有终态描述的是 40.2%;不补描述就重生,送厂商的提示词里根本没有终态段,画出来仍和首帧一样、还是会被拒,而每次重生都照常扣费。get_shot_prompts 的 terminal_desc_missing=true 就是这个信号。",
         "tags": [
           "storyboards"
         ],
@@ -13391,6 +13391,14 @@
                       "exclusiveMinimum": 0
                     }
                   },
+                  "prop_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0
+                    },
+                    "maxItems": 8
+                  },
                   "character_presence": {
                     "type": "array",
                     "items": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.222",
+  "version": "0.1.223",
   "mcpName": "ai.starreel/starreel",
   "description": "StarReel MCP server — drive the AI short-drama production pipeline (script → storyboards → frames → video → final cut) from Claude, Cursor, or any MCP client",
   "license": "MIT",

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "ai.starreel/starreel",
   "description": "Turn a script into a finished, downloadable short-drama episode — via MCP or REST.",
-  "version": "0.1.222",
+  "version": "0.1.223",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.222",
+      "version": "0.1.223",
       "transport": {
         "type": "stdio"
       },