@starreel/mcp 0.1.242 → 0.1.247

package/SKILL.md

@@ -104,7 +104,7 @@ announces a condensed version as MCP `instructions` at connect time.
 | A song + lyrics | `create_drama` (`project_type: "mv"`) → `set_mv_lyrics` → `generate_mv_story` → `generate_mv_script` | `rewrite_script` (blocked for MV) |
 | Lyrics only, no song (MV) | `create_drama` (`project_type: "mv"`) → `set_mv_lyrics` → `suggest_mv_song_styles` → `quote_mv_song` → `generate_mv_song` → `get_mv_song` → `select_mv_song` → `generate_mv_story` → `generate_mv_script` | Confirming lyric rights on the user's behalf (`lyrics_rights_confirmed` must come from the user); picking a candidate by QC text alone without letting the user listen |
 | A product / brand | `create_drama` (`project_type: "ad"` or `"brand_film"`) → `add_product` → `generate_product_sheet` | writing brand copy as dialogue (it gets spoken) |
-| Generated shots / a cut that needs changes | `scan_dialogue_coverage` / `scan_intra_shot_cuts` first, then `get_shot_prompts` · `update_shot` · `replace_shot_dialogue` · `repair_episode_dialogue` · `split_shot` · `trim_shot` · `regenerate_shot_video` · `edit_video_shot` → `rerender_episode`. To put **specific shots on a different video engine** in a whole-episode run, pass `shot_engines` (`{storyboard_id: engine}`) to `quote_videos` (a scene group that contains a picked shot is **split into per-shot generation** — listed in `shot_engines_ungrouped`; its other shots stay on the drama engine but lose the group's one-take continuity, so don't break a good group for one shot; a shot that already has a video is not re-run by the episode run, so picking an engine for it is rejected). Re-quoting after a partial run prices only the shots that will actually be dispatched (`shots_total`; already-finished ones are counted in `shots_already_done`, except that a scene group with any unfinished shot is re-run whole). To make a shot **always** use a different engine (single, batch and regen alike), set `video_engine` with `update_shot` (stored on the shot, shown in the web workbench; such a shot is never put in a scene group; explicit per-call parameters still win). To re-run **one scene group** (one request, keeps in-group continuity) — optionally on a different engine for that run — use `quote_regenerate_scene_group` (`shot_numbers` = exactly one group from `get_scene_group_plan`, optional `video_engine`; the whole group must fit that engine's single-clip limit) → `regenerate_scene_group`. To retry **one shot on a different video engine**, pass `model` to `quote_regenerate_shot_video` (that shot, that regeneration only — the drama's `video_engine` is untouched; the quote pins the engine, so changing it means re-quoting) | re-composing to fix what a clip *says*; switching the whole drama's `video_engine` just to fix one shot |
+| Generated shots / a cut that needs changes | `scan_dialogue_coverage` / `scan_intra_shot_cuts` first, then `get_shot_prompts` · `update_shot` · `replace_shot_dialogue` · `repair_episode_dialogue` · `split_shot` · `trim_shot` · `set_shot_post` (free per-shot finishing: mirror an axis-crossing shot incl. swapped L/R audio, grade groups + reference shot for matched exposure/white balance, J-cut lead; needs `compose_episode`, not `rerender_episode`) · `set_ambient_bed` (free continuous ambience bed across a run of shots, ducked under speech) · `regenerate_shot_video` · `edit_video_shot` → `rerender_episode`. To put **specific shots on a different video engine** in a whole-episode run, pass `shot_engines` (`{storyboard_id: engine}`) to `quote_videos` (a scene group that contains a picked shot is **split into per-shot generation** — listed in `shot_engines_ungrouped`; its other shots stay on the drama engine but lose the group's one-take continuity, so don't break a good group for one shot; a shot that already has a video is not re-run by the episode run, so picking an engine for it is rejected). Re-quoting after a partial run prices only the shots that will actually be dispatched (`shots_total`; already-finished ones are counted in `shots_already_done`, except that a scene group with any unfinished shot is re-run whole). To make a shot **always** use a different engine (single, batch and regen alike), set `video_engine` with `update_shot` (stored on the shot, shown in the web workbench; such a shot is never put in a scene group; explicit per-call parameters still win). To re-run **one scene group** (one request, keeps in-group continuity) — optionally on a different engine for that run — use `quote_regenerate_scene_group` (`shot_numbers` = exactly one group from `get_scene_group_plan`, optional `video_engine`; the whole group must fit that engine's single-clip limit) → `regenerate_scene_group`. To retry **one shot on a different video engine**, pass `model` to `quote_regenerate_shot_video` (that shot, that regeneration only — the drama's `video_engine` is untouched; the quote pins the engine, so changing it means re-quoting) | re-composing to fix what a clip *says*; switching the whole drama's `video_engine` just to fix one shot |
 | One person at several ages built as separate characters, and their portraits look like different people (or a mole switches sides) | pick the character whose portrait is right as the reference: `quote_derive_character_portrait` (`reference_character_id`, `age_stage`) → customer agrees → `derive_character_portrait` → `get_derived_portrait_candidates` (inspect each) → `adopt_derived_portrait` → `generate_character_sheet`. Check the target's `appearance` describes clothing for that age first — cross-character derivation dresses the target from its own profile, not the reference image | re-running batch portraits hoping the faces line up; editing the reference image elsewhere and uploading it |
 | Finished first / last frames are not used by the video (`frame_delivery` says `reference_video_exclusive`, or the quote has an `av_anchor_strips_frames` advisory) | `get_av_anchors` → show the customer which shot the costume video anchor was cut from (open `anchor_url`) → with their OK `clear_character_av_anchor` → re-quote. Removing it means dialogue shots no longer anchor to the clip's voice; `allow_auto_rebuild: true` re-enables automatic anchoring | regenerating frames again (they will be stripped again); removing the anchor without telling the customer about the voice trade-off |
 | Wants old portraits / sheets / a shot's old tail frame "deleted" | `set_character_portrait` (old assets listed in `old_assets`) · `clear_shot_frame` (old tail frame) → `regenerate_shot_video`; `list_unlinked_assets` lists the drama's unlinked old assets (a history list, not proof of ownership). Both only **unlink** — files are not deleted (`physically_deleted` is always empty; `in_history: false` means the platform kept no record, so save that URL if it matters). Tell the customer exactly that | telling the customer the old image was deleted; writing `last_frame_image: null` through the internal API |
@@ -1199,6 +1199,9 @@ shot whose voice drifted despite the anchor. Check them in this order:
    ≤0.05 s, so lip-sync and picture stay), skips shots that already carry the
    current anchor and match it, and keeps the original audio when QC fails.
    `preview_voice_unify` lets the customer listen to one shot first (free).
+   Choose the target voice with `set_voice_unify_target` (the shot whose voice
+   is right) rather than an IP voice anchor: the target is read only by voice
+   unification, so generation keeps locking first/last frames.
    Recompose (`rerender_episode`) for `applied` shots to reach the final cut.
 
 ### "话没说完就切" / a line gets cut off mid-word
@@ -1722,7 +1725,7 @@ Full reference: https://api.shortreelai.com/docs/mcp
 ### 资产引用与版本有效性
 
 - `get_storyboards.asset_versions` 对首帧、尾帧和视频分别返回四项事实：`generated`（已生成）、`input_consistent`（与当前输入一致）、`review_valid`（审核有效）、`adopted`（已采用）。`null` 表示证据不足，不能当作 true。
-- `ready` 和生成数量只表示产物存在；当前有效数量使用 `get_pipeline_status.asset_versions_summary.*.current_effective`。出图、出视频两步的 `status=done` 同样只表示已生成，旁边的 `validity` 拆出当前有效、生成后输入已变（`changed_by` 给出是哪类依赖变了）、无法判断、未审核、审核未过；`validity.note` 非空时先告知客户，再决定重出哪些镜，不要因输入变更就整集重出。换帧后旧视频仍可查看，但失效版本不能混入当前有效汇总。
+- `ready` 和生成数量只表示产物存在；当前有效数量使用 `get_pipeline_status.asset_versions_summary.*.current_effective`。出图、出视频两步的 `status=done` 同样只表示已生成，旁边的 `validity` 拆出当前有效、生成后输入已变（`changed_by` 给出是哪类依赖变了）、无法判断、未审核、审核未过；`validity.note` 非空时先告知客户，再决定重出哪些镜，不要因输入变更就整集重出。`validity.review_advised`（汇总里同样单列 `review_advised`，`stale` 不含它）是「只有角色外观文本被改写」的产物：画面身份由定妆图锚定，多半只是换了写法，请客户对照定妆图确认，不当作需重出；`review_advised_by` 按角色列出。换帧后旧视频仍可查看，但失效版本不能混入当前有效汇总。
 - `get_asset_versions(storyboard_id)` 查看历史版本链接、依赖 ID/版本哈希及各自状态。历史没有快照时不从当前绑定伪造依赖。
 - `get_image_dispatch(image_id)` 查一张镜头帧的派发台账：每张参考图的用途、所属角色、是否送达模型，派发前被剔的图在哪一步因什么被剔（如时代预检点名的冲突物件），以及最终发给模型的提示词。画面「不像某角色/少了某道具」时先查它，确认是参考没送到还是模型没画对，再决定改什么；`ledger` 不是 `full` 时缺失项为 `null`，不能当作已送达。
 - `get_frame_candidates(storyboard_id)` 一镜首帧/尾帧的全部候选（含被拒的原图）：`adopted` 标出当前在用那张；`reject.class` 区分要改内容（`needs_content_fix`）、内容问题但可重掷（`content_retryable`）、审核没审成或偶发（`transient`，不是画面不合格）；`audit.warnings` / `expected` / `derived_shot_type` / `boxes` 是审计证据（老候选为 `null`，不代表审过）。镜头反复被拒或客户问「被拒的长什么样」时先逐张看它，再决定改分镜、改参考还是重掷。

package/dist/i18n/tools.en.json

@@ -17,7 +17,7 @@
   "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.",
-  "get_pipeline_status": "Check the complete workflow progress for one episode(script_rewrite/extraction/storyboards/voice/image/video/compose/music/final merge… each step done/partial/pending/not_required). Follow it in order; do not skip. Free. ★For auto / custom mode(hosted rollout), also returns next_action(action=run do hosted step directly / wait_running background still running, wait for persistence and do not dispatch duplicate / wait_customer client-controlled step or no budget precheck, ask first / ask_customer pending questions, summarize and ask first / done all steps complete—first run tool=review_final_cut, fix issues and re-compose/re-review, then deliver report; tool=which tool to call) and pending_questions; advance exactly by next_action. asset_versions_summary separates generated, input_consistent, review_valid, adopted, and current_effective; do not treat generate_videos.completed as current valid count. ★generate_images / generate_videos status=done only means \"generated\", not deliverable: inspect validity for that step(current_effective / input_changed with changed_by listing drama-level settings, shot itself, or which character changed / input_unknown / unreviewed / review_failed). If validity.note is non-empty, tell the client first. Changed input may not affect visuals; do not regenerate whole episode paid just for that—use get_asset_versions per shot to inspect causes. ★not_required means this mode does not need the step(e.g. TTS steps for native-audio drama, generate_bgm when music disabled), not unfinished; do not fill it. Image/video denominators exclude blocked shots(shots_not_applicable). merge_episode.bgm_stale=true means music is newer than final cut; just compose_episode again.",
+  "get_pipeline_status": "Check the complete workflow progress for one episode(script_rewrite/extraction/storyboards/voice/image/video/compose/music/final merge… each step done/partial/pending/not_required). Follow it in order; do not skip. Free. ★For auto / custom mode(hosted rollout), also returns next_action(action=run do hosted step directly / wait_running background still running, wait for persistence and do not dispatch duplicate / wait_customer client-controlled step or no budget precheck, ask first / ask_customer pending questions, summarize and ask first / done all steps complete—first run tool=review_final_cut, fix issues and re-compose/re-review, then deliver report; tool=which tool to call) and pending_questions; advance exactly by next_action. asset_versions_summary separates generated, input_consistent, review_valid, adopted, and current_effective; do not treat generate_videos.completed as current valid count. ★generate_images / generate_videos status=done only means \"generated\", not deliverable: inspect validity for that step(current_effective / input_changed with changed_by listing drama-level settings, shot itself, or which character changed / input_unknown / unreviewed / review_failed). If validity.note is non-empty, tell the client first. Changed input may not affect visuals; do not regenerate whole episode paid just for that—use get_asset_versions per shot to inspect causes. validity.review_advised (also listed separately as review_advised in asset_versions_summary; stale excludes it) = only a character's appearance text was rewritten (usually re-extraction rephrasing): still counted as changed input, but visual identity is anchored by the portrait, so it is advisory review, listed per character in review_advised_by — ask the client to confirm against the portrait; do not treat it as needing regeneration. ★not_required means this mode does not need the step(e.g. TTS steps for native-audio drama, generate_bgm when music disabled), not unfinished; do not fill it. Image/video denominators exclude blocked shots(shots_not_applicable). merge_episode.bgm_stale=true means music is newer than final cut; just compose_episode again.",
   "quote_character_portraits": "Quote: how many credits to batch-generate character sheets for characters missing them. Returns portraits_to_generate, estimated_points, quote_id. No charge. Character sheets are identity consistency anchors(missing them makes characters drift); strongly recommended before video. ★This quote only covers character sheets; after character sheets are ready, you **must** also generate_character_sheets for turnarounds(no quote required · image step postpaid; response sheets_to_generate_after is pending count). Only character sheets without turnarounds will drift when characters change angle/lighting/clothing—tell client about this step during quote. ★Returns two numbers: estimated_points is the **upper bound**(estimated at max reference images, enough balance avoids mid-run 402), typical_points is **typical cost**. Tell the client both; only quoting upper bound makes it seem much more expensive. For fixed-price models(e.g. Nano Banana series), they are equal.",
   "generate_character_portraits": "After confirmation, batch-generate character sheets(★character sheets only): background async. A character sheet is a single identity anchor—shot consistency(especially wardrobe) also needs **turnarounds**. After this, strongly recommend generate_character_sheets, or use generate_portraits_and_sheets for both. Check progress via get_pipeline_status/get_storyboards. ⚠️ Batch quote-confirm flow: first call the corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id(quote confirmation by execution mode: pro / no confirmed plan / client-controlled step → tell client and get consent; hosted step → do not ask, follow get_production_plan.autopilot.default_decisions; platform logs in get_autopilot_log). Hosted quotes must fit within budget hard cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask client. ★**Image-generation quotes(character sheets/scene images/frames) return two numbers**: estimated_points is the **upper bound**(estimated at that model’s max reference images, prevents starting with too-low budget and hitting 402 mid-run); typical_points in same response is **typical cost**. Tell both—only upper bound sounds far too expensive(max-ref upper bound can exceed typical by 2x+), only typical may leave insufficient balance. For fixed-price models they are equal; then one number is enough.\n★[Post-completion QC · free] After images persist(poll corresponding get_*; if pending do not repeat call), run review_assets for asset-layer review(missing / generating / failed / rejected by consistency gate / prop era conflict / color script). Relay findings verbatim, fix per action and re-review; then personally inspect each image per agent_qc(does it match profile, same person, era correct; turnaround has all angles and correct proportions/structure; props and scene images make sense in story—compare used_in_shots). Submit QC with submit_qc_report. When generating shot images, pass its review_token as asset_review_token to generate_frames / generate_shot_frame.",
   "generate_character_sheets": "★Batch-generate turnarounds(multi-view) for all drama characters. Turnaround is the **root consistency anchor** referenced by shot frames/video—only character sheets without turnarounds cause drift when angle/lighting/clothing changes(2.5 directly slices turnarounds as bone-structure anchors). Generates only missing turnarounds(no duplicate charge). Prereq: character already has character sheet(missing blocks and tells you to generate character sheet first). Image step, postpaid by usage with no credit debt. Poll get_characters for sheet_status: pending=generating/auditing(turnaround ~2~4 minutes; do not click repeatedly); ready=persisted; **rejected=image generated but rejected by consistency gate**, read sheet_fail_hint for verdict—reroll once; if same reason repeats, anchor fields conflict with character profile, run_precheck before rerolling again.\n★[Post-completion QC · free] After images persist(poll corresponding get_*; if pending do not repeat call), run review_assets for asset-layer review(missing / generating / failed / rejected by consistency gate / prop era conflict / color script). Relay findings verbatim, fix per action and re-review; then personally inspect each image per agent_qc(does it match profile, same person, era correct; turnaround has all angles and correct proportions/structure; props and scene images make sense in story—compare used_in_shots). Submit QC with submit_qc_report. When generating shot images, pass its review_token as asset_review_token to generate_frames / generate_shot_frame.",
@@ -131,13 +131,17 @@
   "regenerate_shot_video": "After confirmation, regenerate video for a shot (optional new prompt).\n★If you get **409「本镜是用户上传的实拍素材」** = this shot was registered by upload_shot_footage as a live-action footage shot; not a model issue, changing engine is useless. To overwrite it with AI video, pass replace_user_footage=true; to keep the footage, do not regenerate.\n★If you get **409 + `in_flight_generation_id`** = this shot still has a generation unfinished, and it was not started with this exact content (you passed a new prompt / later changed the shot with update_shot / later changed this shot's first frame or last frame—regeneration, upload, and supplementary last-frame generation all count / the frames, reference assets, engine, or other params passed this time differ from that run / the in-flight task is an edit). This 409 can happen even if the prompt is unchanged. This regeneration was not submitted, no credits charged, quote invalidated. Wait for the in-flight task to finish, review the result, then re-quote and regenerate—otherwise the video you get is from old content (old prompt or old first/last frames), causing you to think the change had no effect.\n★Success but response includes **`reused_in_flight: true`** = the same content is already generating (resend/double-click/batch video generation already dispatched). No new task created, no new credits charged; the returned task is the in-flight one. Just monitor its progress; do not send again.\n★Autopilot final-cut pipeline stage: the same shot can regenerate video at most 3 times (combined with edit_video_shot). At the limit returns **409 AUTOPILOT_SHOT_REGEN_LIMIT** (not dispatched, no credits charged, quote not consumed)—do not bypass with another tool; stop and ask the customer: if the customer agrees to more regeneration, quote normally and pass customer_approved_more_regens:true when generating (grants another limit); if the customer accepts current state, proceed, and the next paid call must pass acknowledge_review:true to record confirmation. Professional mode and customer-controlled stages are not subject to this limit.\n★【Shot image review hard gate · free】Before this step, you must call review_frames: report the returned findings to the customer verbatim one by one (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass review_token into this tool. Without review, it will be rejected with 400. If content changes after review → token auto-invalidates; just review again (still free). When there is error, default is to block; only if the customer is informed and insists on continuing as-is, pass acknowledge_review:true—pushing ahead with issues will likely produce unusable video and still charge normally (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, including autopilot). In autopilot stages, only whitelisted heuristic error can be released with auto_acknowledge:true (platform decides; if not whitelisted returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause and ask customer, false = self-fix per action then re-review). ★For grayscale dramas, you (agent) must also personally QC: inspect assets item by item per agent_qc returned by review_frames, answer each checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has issues → blocked by default like error). ⚠️ Batch quote confirmation flow: first call the corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id (quote confirmation follows execution mode: professional mode / unconfirmed plan / this stage customer-controlled → explain to customer and proceed only after customer agrees; do not decide for the customer. This stage autopilot → do not ask customer; follow get_production_plan autopilot.default_decisions, platform records it in get_autopilot_log). Autopilot-stage quote must be within hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask customer. ★**Image-generation quotes (character sheet/scene image/frame generation) provide two numbers**: estimated_points is the **upper bound** (estimated by the model's max reference-image count, ensuring you do not start with too-low budget and hit 402 midway); typical_points in the same response is the **typical spend**. Tell the customer both—only stating the upper bound makes it look much more expensive (the upper bound with full reference images can be over 2x the typical value), while only stating the typical value may leave insufficient balance. For fixed-price models they are equal; then one number is enough. Video-generation quote and charge are the same function; no range.\n★【Post-completion QC · free】After generation, wait until it is stored (see video_status via get_storyboards / get_pipeline_status), then call review_videos to review video and dubbing layers (missing video / video generated from old frames / hard cut at end / unexpected human voice / missing dubbing / voice not assigned / original audio voice line expired), fix and re-review; then personally inspect each shot video and listen to dubbing per agent_qc (action correct, face stable, lines complete, voice right), submit via submit_qc_report; compose_episode must include its review_token.",
   "split_shot": "Split one shot into two shots by first/last frames (structural operation). Free.",
   "trim_shot": "Trim one shot duration (in_ms/out_ms). Free; after return, call rerender_episode to reassemble the final cut.",
+  "set_shot_post": "Per-shot finishing for the final cut (free, no regeneration, no charge): (1) mirror_h flips the shot horizontally and swaps left/right audio channels, to rescue axis-crossing shots; do not mirror shots with on-screen text (signs, burned-in subtitles). (2) grade_group: shots sharing the same group name get exposure and white balance matched automatically (default grouping is by scene; in a single-scene drama give dawn/dusk/night parts different group names); grade_ref=true makes this shot the group's reference that the others match (otherwise they match the group median). (3) audio_lead_in_ms (J-cut): this shot's sound starts this many ms before its picture, over the previous shot's tail (0-800, typically 300-500). For native-audio shots the early sound comes from the source before the in-point, so set an in-point with trim_shot (in_ms >= lead) first; with less headroom the lead is shortened automatically, with in_ms=0 it has no effect; seams with a dissolve or speed change are skipped. Send only the keys you change; an empty call returns the current values; grade_group=null removes the group. gray_on=false in the reply means this drama has not been opened for these features yet (values are saved and apply once opened). Run compose_episode afterwards (rerender_episode reuses the old timeline and will not pick it up).",
+  "set_ambient_bed": "Continuous ambience bed per scene (free, no regeneration, no charge): attach one ambience recording (wind, birds, room tone...) to a set of shots; at compose time adjacent shots sharing the same recording become **one continuous track** — no break at cuts, 0.4 s fades at both ends, about 5 dB lower while someone speaks. Fixes 'room tone jumps at every cut'. Each item of beds = {storyboard_ids, audio_url, gain_db?}: audio_url must be a public http(s) audio file (looped seamlessly if shorter than the run), gain_db -40..0, default -18; audio_url=null removes the bed from those shots. Use separate items for different times of day within one scene; leave out shots that should be quiet and the bed breaks there. The reply's runs are the merged runs in shot order; gray_on=false means not yet enabled for this drama (values are saved and apply once enabled). Run compose_episode afterwards (rerender_episode reuses the old timeline). Not applied to music videos.",
   "recommend_trim_window": "Trim-window action QC: for independently generated shots where declared duration < actual video duration, recommend in/out trim windows based on in-video activity detection—vendor output often has action in the second half, and trimming from 0 seconds by default can cut at a mid-action pose (e.g., hand raised but not yet struck). Free, zero charge. Not applicable to group-mode shots (group splitting is already content-aware; returns applicable=false). After receiving a recommendation, apply it with trim_shot.",
   "scan_intra_shot_cuts": "★When the customer reports \"shots cut too fast / the image jumps around inside one shot\", run this first. Free, zero charge. A storyboard should be **one continuous shot**, but the vendor may hard-cut camera positions inside the video (telescope close-up → aerial wide shot → character medium shot). These cuts are invisible in the storyboard table and timeline—they can only be found by scanning frames. Returns shots_with_cuts (shot numbers with intra-shot jump cuts) / total_cuts / engine_suspect / message; shots_with_terminal_cuts separately lists suspected short abrupt tail cuts, and detail.terminal_cut gives position and status. ★Interpretation: perceived final-cut cut points = seams between shots + intra-shot cuts reported here. If this accounts for most cuts, it is not an editing pace problem; resplitting shots or changing transitions will not help. engine_suspect=true means this drama's engine is a known high-frequency source (WAN); measured WAN 11/12 shots had intra-shot cuts, Seedance 1/6, H3 0/5, and prompts cannot block it (negative constraints are already included)—first verify actual cut points and narrative intent, then decide whether to adjust splitting or regenerate; do not retry paid generation solely because of the scan warning. Ordinary intra-shot multi-cut statistics still exclude group mode and explicit montage; however, single segments after group splitting are not exempt from tail-cut checks, so still inspect shots_with_terminal_cuts/detail.terminal_cut.",
   "scan_burned_subtitles": "★For original-voice dramas (video has built-in human speech), recommend running once before final assembly; when the customer reports \"the final cut has two subtitle layers / an extra line of text in the image\", run this first. Video vendors sometimes ignore \"no subtitles\" constraints and burn dialogue into the image—small text, usually appearing only for one or two seconds while the line is spoken. The platform final cut then overlays another subtitle layer, creating double subtitles. Reassembling cannot remove it; only regenerate_shot_video for that shot can. Samples 12 frames per shot, one vision audit, **usage-based billing** (one small vision call per shot). Returns flagged[{shot, texts, matches_dialogue, frames}] / clean / errors. matches_dialogue=true means the recognized text is this shot's dialogue, essentially confirming vendor subtitles; text naturally present in signs, book pages, screens, etc. does not count. dry_run=true reports only and does not write back; otherwise writes back, and compose_episode final-assembly precheck will list these shots as vendor_burned_text.",
   "scan_wardrobe_consistency": "★Run this when the customer reports \"the same character changed clothes / clothing color or style is wrong\"; also recommended before final assembly. For each shot, compare the used first frame and one mid-video frame against each character's design image in that shot (or character sheet if none) for clothing style and color. A common cause is distant small characters being drawn by the image model in different clothes—even when reference images and prompts are correct. Overall color cast from night scenes/warm lighting does not count as inconsistency. One vision audit per shot, **usage-based billing**. Returns flagged[{shot, characters:[{name, differences}]}] / clean / errors. dry_run=true reports only and does not write back; otherwise writes back, and compose_episode final-assembly precheck will list these shots as wardrobe_mismatch. Remedy: regenerate this shot's first frame (generate_shot_frame), then regenerate_shot_video; reassembling cannot remove it.",
   "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. To keep first/last frames (regenerating loses composition) use quote_voice_unify → unify_voices: post-hoc conversion of vocals to the voice anchor's timbre without regenerating video. Shots that went through voice unification carry voice_unify: similarity / coverage / loudness_db are all before→after; summary.voice_unified = shots already in the final cut.",
-  "quote_voice_unify": "★Use for native-audio dramas (vendor-voiced video) when \"the same character's voice differs across shots\" but you don't want to regenerate video for voice and lose first/last-frame composition. Free quote, read-only. Lists, for every dialogue shot in the episode, whether it needs post-hoc voice unification and why: to_process = no voice anchor was sent at generation / an old anchor was sent, always processed; conditional = the current anchor was sent, voiceprint is measured at execution and the shot is skipped free of charge if it matches; skipped = untouched (locked shot, real footage, existing track-replacement product, character has no voice anchor, etc.; see reason_text). Multi-speaker shots are judged per speaker; only the lines of the speaker that needs it are changed. Billed by seconds of converted speech: estimated_points is the upper bound, typical_points the usual cost—tell the customer both; after they agree call unify_voices with quote_id. Characters without a voice anchor: set_character_voice or set_voice_anchor_from_shot first (pick the shot whose voice is right as the reference). Per-drama gray release; returns 403 if not enabled.",
+  "quote_voice_unify": "★Use for native-audio dramas (vendor-voiced video) when \"the same character's voice differs across shots\" but you don't want to regenerate video for voice and lose first/last-frame composition. Free quote, read-only. Lists, for every dialogue shot in the episode, whether it needs post-hoc voice unification and why: to_process = no voice anchor was sent at generation / an old anchor was sent, always processed; conditional = the current anchor was sent, voiceprint is measured at execution and the shot is skipped free of charge if it matches; skipped = untouched (locked shot, real footage, existing track-replacement product, character has no voice anchor, etc.; see reason_text). Multi-speaker shots are judged per speaker; only the lines of the speaker that needs it are changed. Billed by seconds of converted speech: estimated_points is the upper bound, typical_points the usual cost—tell the customer both; after they agree call unify_voices with quote_id. Prefer set_voice_unify_target to choose the target voice (pick the shot whose voice is right; does not affect generation routing); otherwise the character's IP voice anchor is used. Per-drama gray release; returns 403 if not enabled.",
+  "set_voice_unify_target": "Set a character's \"unify target voice\": taken from the shot whose voice is right, used only by post-hoc voice unification (quote_voice_unify → unify_voices). Free. ★Difference from set_character_voice / set_voice_anchor_from_shot: those set the IP voice anchor, which native-audio generation sends as reference audio, so first/last frames may not be locked; this field is not read by generation routing, so the drama keeps \"first/last frames lock the picture, unify voice after generation\". Once set, every shot of the character is voiceprint-measured first and skipped free of charge if it already matches; the target shot itself is skipped. The shot must already have video and only this character may speak in it (a multi-speaker shot would mix other voices into the target; returns 400). Clear with clear_voice_unify_target. Per-drama gray release; returns 403 if not enabled.",
+  "clear_voice_unify_target": "Clear a character's \"unify target voice\" (set by set_voice_unify_target). Free. After clearing, voice unification falls back to the character's IP voice anchor; with neither, the character is skipped.",
   "unify_voices": "Run post-hoc voice unification (quote_voice_unify first; call with quote_id after the customer agrees). Only runs the shots in the quote, serially in the background (~1-2 min per shot). Per shot: separate vocals → locate that character's lines by dialogue and voiceprint → convert each line into the voice anchor's timbre (each line's duration changes by ≤0.05s; lip-sync and picture untouched, no video regeneration) → splice back, ambience and SFX kept as-is. If any QC check fails (transcript coverage drops / duration diff >0.1s / similarity to anchor not improved / loudness diff >1dB) the original audio is kept and that shot's charge is refunded. Use get_voice_unify_status for progress and per-shot before/after; shots with status=applied take effect after recomposing (rerender_episode).",
   "get_voice_unify_status": "Check voice-unification progress and per-shot results (free). summary: applied = unified (effective after recomposing the final cut) / kept_original = QC failed, original audio kept, charge refunded (reason says which check failed) / skipped = voiceprint already matched or no speech found for the character / errors = failed (charge refunded) / superseded = the shot was regenerated, switched or locked while processing; result discarded, not written back (charge refunded). Each shot carries similarity (before→after, to the voice anchor), coverage, loudness_db, points; stale = video or product changed since, result outdated.",
   "preview_voice_unify": "Preview voice unification on a single shot (free, not written back, not charged). Asynchronous: start=true launches it (~1-2 min); call again without start to get the result. productUrl in the result is the processed video (listen directly); checks are the four QC verdicts. By default the character's voice anchor is the target timbre; with reference_storyboard_id = the shot in the same episode whose voice is right, that shot's vocals become the target (useful before the character has an anchor; speaker selects which character to convert).",

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

@@ -17,7 +17,7 @@
   "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 重复付费。",
-  "get_pipeline_status": "查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 done/partial/pending/not_required)。照它按序推进、不跳步。免费。★一键 / 混合模式(托管灰度内)的剧额外返回 next_action(action=run 托管环节直接做 / wait_running 后台还在跑、等它落库别重复派 / wait_customer 客户把控环节或没有预算预检的步骤先问 / ask_customer 有待问事项先汇总问 / done 各步完成——先按 tool=review_final_cut 审成片、有问题修完重拼复审,再出交付报告;tool=该调哪个工具)与 pending_questions,照 next_action 推进。asset_versions_summary 将 generated、input_consistent、review_valid、adopted 和 current_effective 分开计数；不能把 generate_videos.completed 当当前有效数量。★generate_images / generate_videos 的 status=done 只表示「已生成」，不代表可交付：看同一步的 validity（current_effective 当前有效 / input_changed 生成后输入已变，changed_by 列出是剧级设定、镜头本身还是哪个角色变了 / input_unknown / unreviewed / review_failed），validity.note 不为空时先把它告诉客户。输入变了不一定影响画面，别据此整集重出（付费），先用 get_asset_versions 逐镜看原因。★not_required=当前模式不需要该步(如原声剧的 TTS 三步、关配乐的 generate_bgm),不是没做完,别去补做。图片/视频分母已剔除卡镜(shots_not_applicable);merge_episode.bgm_stale=true 表示配乐晚于成片,重新 compose_episode 即可。",
+  "get_pipeline_status": "查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 done/partial/pending/not_required)。照它按序推进、不跳步。免费。★一键 / 混合模式(托管灰度内)的剧额外返回 next_action(action=run 托管环节直接做 / wait_running 后台还在跑、等它落库别重复派 / wait_customer 客户把控环节或没有预算预检的步骤先问 / ask_customer 有待问事项先汇总问 / done 各步完成——先按 tool=review_final_cut 审成片、有问题修完重拼复审,再出交付报告;tool=该调哪个工具)与 pending_questions,照 next_action 推进。asset_versions_summary 将 generated、input_consistent、review_valid、adopted 和 current_effective 分开计数；不能把 generate_videos.completed 当当前有效数量。★generate_images / generate_videos 的 status=done 只表示「已生成」，不代表可交付：看同一步的 validity（current_effective 当前有效 / input_changed 生成后输入已变，changed_by 列出是剧级设定、镜头本身还是哪个角色变了 / input_unknown / unreviewed / review_failed），validity.note 不为空时先把它告诉客户。输入变了不一定影响画面，别据此整集重出（付费），先用 get_asset_versions 逐镜看原因。validity.review_advised（asset_versions_summary 里同样单列 review_advised，stale 不含它）= 只有角色外观文本被改写（多是重新提取时换了写法）：仍算输入已变，但画面身份由定妆图锚定，属「建议复核」，review_advised_by 按角色列出——请客户对照定妆图确认，不要当作需重出。★not_required=当前模式不需要该步(如原声剧的 TTS 三步、关配乐的 generate_bgm),不是没做完,别去补做。图片/视频分母已剔除卡镜(shots_not_applicable);merge_episode.bgm_stale=true 表示配乐晚于成片,重新 compose_episode 即可。",
   "quote_character_portraits": "报价:给缺定妆图的角色批量出定妆图要多少点。返回 portraits_to_generate、estimated_points、quote_id。零扣费。定妆图是身份一致性的锚(缺它角色会漂移),强烈建议出视频前先出。★本报价只含定妆图;定妆图就绪后**还必须** generate_character_sheets 出设定图(无需报价·图片步后付,响应里 sheets_to_generate_after 是待出数)。只出定妆图不出设定图,镜头人物换角度/换光/服装会漂——报价时把这一步一起告诉客户。★返回两个数:estimated_points 是**上界**(按参考图张数上限估,拿它准备余额就不会中途 402),typical_points 是**通常花费**。两个都告诉客户,只报上界会让人以为贵得多。固定价模型(如 Nano Banana 系列)下两者相等。",
   "generate_character_portraits": "确认后批量出角色定妆图(★仅定妆图):后台异步。定妆图只是单张身份锚——镜头一致性(尤其服装)还需**设定图**,出完定妆图强烈建议 generate_character_sheets;或直接用 generate_portraits_and_sheets 一步到位。用 get_pipeline_status/get_storyboards 查进度。⚠️ 批量报价确认流程:先调对应的 quote_* 工具拿 estimated_points 与 quote_id,再用 quote_id 调本工具(报价确认按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)。托管环节报价须在预算硬上限内,被 402 BUDGET_WOULD_EXCEED 拦下就停下问客户。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。\n★【完成后质检·免费】出完等图落库(轮询对应 get_* 看状态,pending 别重复调),再调 review_assets 审资产层(缺图 / 生成中 / 失败 / 被一致性闸拒收 / 道具时代冲突 / 色彩脚本),findings 原样告诉客户、按 action 修完复审;再按它返回的 agent_qc 亲自逐张看图(像不像档案、是不是同一个人、时代对不对;设定图本身各角度齐不齐、比例与结构对不对;道具与场景图放在剧情里合不合理——对照素材 used_in_shots 那几镜),submit_qc_report 提交质检报告;出镜头图时把它的 review_token 作为 asset_review_token 传给 generate_frames / generate_shot_frame。",
   "generate_character_sheets": "★批量给全剧角色出设定图(多视角 turnaround)。设定图是镜头帧/视频引用的**一致性根锚**——只出定妆图不出设定图,镜头人物换角度/换光/服装会漂移(2.5 更直接用设定图切片做骨相锚)。只对缺设定图的角色出(不重复扣费)。前置:角色须已有定妆图(缺则拦并提示先出定妆图)。图片步,按用量后付不欠费。轮询 get_characters 看 sheet_status:pending=生成/审计中(设定图约 2~4 分钟,别重复点);ready=入库;**rejected=图已出但被一致性闸拒收**,读 sheet_fail_hint 拒收判词——可重掷一次,连拒理由相同则是锚字段与人物档案冲突,先 run_precheck 再重掷。\n★【完成后质检·免费】出完等图落库(轮询对应 get_* 看状态,pending 别重复调),再调 review_assets 审资产层(缺图 / 生成中 / 失败 / 被一致性闸拒收 / 道具时代冲突 / 色彩脚本),findings 原样告诉客户、按 action 修完复审;再按它返回的 agent_qc 亲自逐张看图(像不像档案、是不是同一个人、时代对不对;设定图本身各角度齐不齐、比例与结构对不对;道具与场景图放在剧情里合不合理——对照素材 used_in_shots 那几镜),submit_qc_report 提交质检报告;出镜头图时把它的 review_token 作为 asset_review_token 传给 generate_frames / generate_shot_frame。",
@@ -34,7 +34,8 @@
   "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 的 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⚠️ 服务重启会让在途登记归零,重启期间发起的运行也会显示为无在途。",
+  "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⚠️ 服务重启会让 agent 在途登记归零,重启期间发起的运行也会显示为无在途。\n★generate_videos 整集出视频的接力链看返回里的 video_run 段(它落库,重启不会凭空消失):shots_total / shots_with_video / shots_remaining = 共几镜、已出几镜、剩几镜;running:true = 链在跑,别重发 generate_videos;resumed_after_restart>0 = 中途服务重启过、已自动续跑(已出视频与中断前已派发的镜不重出不重扣);status=interrupted = 重启后没自动续跑(interrupt_reason 写原因),重新 quote_videos 后 generate_videos 会跳过已出的镜;shots_dispatched_without_video = 派发过但没出片的镜,用 get_jobs 看原因、regenerate_shot_video 单补;status=cancelling / cancelled = 客户用 cancel_videos 停了这条链,cancelled_shot_numbers 是没出没扣费的镜。\n★批量出图(整集出帧 / 帧链 / 定妆图 / 设定图 / 场景图等)看 image_batches:每批 kind / status(running / done / cancelled)/ dispatched / in_flight / completed / targets_not_dispatched;status=cancelled = 客户用 cancel_images 停了这一批。",
+  "cancel_images": "(免费)停掉本剧还在跑的批量出图:整集出帧(generate_frames)、工作台出帧批次、帧链(chain_frames 与自动帧链)、定妆图、设定图、场景图、世界观图、角色变体图、锚图。语义:**已交给厂商的图照常出完、照常扣费(不退,含 best-of-N 已派出的候选)**;还没派的不再派、不扣费;之后的质量重试、补派、服务重启后的重排也不会再派;被取消的出帧批次重启后不续跑。可选 episode_id 只停这一集的批次、kind 只停一种(frames / frame_batch / frame_chain / portraits / sheets / scene_images / world_images / character_variants / anchors),不传 = 本剧全部。回执每批给 in_flight_items(已派出、会出完扣费)、completed_items(已出完)、cancelled_targets(没派、不扣费;null = 该批次没预先登记目标清单)。被取消的镜 / 角色 / 场景之后可以重新报价再发起对应的 generate_*(已出的会跳过),或单张重出。★只在客户明确要停时调用;单张出图(generate_shot_frame 等)不能取消;没有可取消的批次返回 409 NO_ACTIVE_IMAGE_BATCH。出视频的取消用 cancel_videos。",
   "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 上限,没扫完。",
   "plan_precheck_fix": "让平台**算出**该怎么改 run_precheck 揪出的「指令自相矛盾」类问题(第①步,只算不改)。按文本用量计费(很小),不走报价确认。\n★两段式,这一步不动任何数据:拿到提案后**逐条讲给客户**(哪一镜、把什么改成什么、为什么),再把采纳的那几条**原样**传给 apply_precheck_fix 落库(采纳哪几条,托管=全部采纳按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)。\n★**专业模式不要替客户决定**:这些判据有假阳,平台刻意不做「一键自动修」——曾实测同一批提案里近半是判据误报,静默改会把本来正确的分镜改坏。\n★返回的 blocked 列出「系统不替你改」的类别:那些要人工按 run_precheck 的提示调整分镜。看到 blocked 不等于没问题,反而是**必须人工处理**的那部分。\n不传 shot_id 就算整集;只想修某一镜就传它。",
@@ -62,6 +63,7 @@
   "adopt_local_frame_edit": "采用某个局部返修候选:把它写成这一镜的当前帧(免费)。与上传帧同一套后续处理:本镜视频标为待重生、相邻接缝跟着修。★只在客户看过并选定后调用。返修之后这一帧若已换过 → 409 BASE_FRAME_CHANGED(对当前帧重新发起);verdict=reject 的候选默认拒绝采用(409 CANDIDATE_REJECTED),客户看过坚持要用才带 accept_rejected:true。",
   "quote_videos": "报价:给某一集批量出视频要多少点(与实际扣费同函数,较准)。返回 estimated_points、quote_id。零扣费。⚠️ 视频是大额花费,务必把点数清楚告诉用户并等其确认。\n★**frame_delivery = 本次逐镜真正送到厂商的帧**:列出有独立尾帧的计价镜,以及首帧不送达的计价镜(带 reason,如 reference_video_exclusive=挂了定妆视频锚/运动参考);first_frame.verified=false = 预览没跑完、送不送未核验,别当已送达讲,可逐镜 quote_regenerate_shot_video 核对;没列出的计价镜 = 已核验首帧照常送达、无独立尾帧。advisories 里出现 av_anchor_strips_frames = 这些镜被角色定妆视频锚剥掉首尾帧,把镜号讲给客户,要保住首尾帧就 get_av_anchors 看来源、客户同意后 clear_character_av_anchor 摘锚再重新报价。\n★**只计这次真会派发的镜**:已出视频的镜整集续跑时跳过,不重出不计价——shots_total = 这次计价的镜数(不是集内总镜数),shots_already_done = 已出视频、这次跳过的镜数。例外:场景组只要有一镜没出视频就**整组重出**,组内已出的镜同样计价。全部已出视频 ⇒ 400(没有可派发的镜,要重出某镜用 regenerate_shot_video)。报价之后若有镜的视频被清空(变成待出视频),generate_videos 会 409 要求重新报价,不按报价外的镜扣费。\n★**按镜指定视频引擎**:传 shot_engines={分镜id: 引擎} 即只为这些镜、这一次整集生成换引擎(不改剧级 video_engine,其余镜照旧)。报价按它逐镜计价,quote_id 把引擎钉死,generate_videos 派发的就是它——要改引擎必须重新报价。回执 shot_engines = 实际生效的映射;shot_engines_ungrouped = 因含指定镜而**拆成逐镜出**的场景组(场景组的时长与多关键帧是按剧引擎规划的,换引擎整组出会丢镜/丢关键帧;拆组后组内其余镜仍按剧引擎逐镜出,失去组内一次成片的连贯性,所以别为一镜去拆一个好好的组——先看 get_scene_group_plan)。所选引擎必须支持本剧分辨率(seedance-2.5 只有 480p/720p;hailuo-3 只有 720p/1080p;wan3.0/wan3.0-prime 480p~1080p),且镜头时长不超过该引擎单镜上限(seedance-2.5/wan3.0 30s,hailuo-3 15s),否则 400(超长会被厂商截断,要么换引擎要么 split_shot)。指定引擎的镜必须这次会出视频:已出视频的镜整集生成不会重出,给它指定引擎 ⇒ 400;拆成逐镜的场景组只计没出视频的组员。只想重出个别已出过视频的镜,用 quote_regenerate_shot_video 的 model 更省。★响应可能带**未接缝提示**(不影响 review_token / 报价 / 状态码):review_frames 与 generate_videos 是 unchained_seam_advisory,quote_videos 是 advisories 里 code=unchained_seams。seams 列的是 chain_frames 会接、却还没接上的相邻缝(from_shot→to_shot),status=no_stamp(从没接过)/ pending(发起过衔接、还没落地或审计未出结论)/ stale_anchor(上次承接的锚已失效:上一镜尾帧在衔接之后又被重生过,需要重接)/ join_failed(上次发起的衔接重生被拒 / 失败 / 落选,没落地)/ audit_failed(衔接落地但审计判不连续,看 get_storyboards 的 seam_failed_dims)/ first_frame_regenerated(接缝审过之后下镜首帧又被重出、没走承接路径,原衔接已不算数)/ not_linked(规划器判没接上、原因证据不足);都按计划重接即可;video_locked 是下镜已出视频的同类缝,chain_frames 不再改它们,只能逐镜 chain_shot_from_prev / chain_shot_from 换首帧后 regenerate_shot_video(都先报价)。出视频前看到 seams 就先 chain_frames(dry_run:true) 把计划与报价告诉客户,客户同意再执行,执行后重调 review_frames。",
   "generate_videos": "确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)。要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url 逐镜填充即完成。\n★【镜头图片审查硬闸·免费】本步前必须先调 review_frames:把返回的 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_frames 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。⚠️ 批量报价确认流程:先调对应的 quote_* 工具拿 estimated_points 与 quote_id,再用 quote_id 调本工具(报价确认按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)。托管环节报价须在预算硬上限内,被 402 BUDGET_WOULD_EXCEED 拦下就停下问客户。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。\n★【完成后质检·免费】出完等它落库(get_storyboards 看 video_status / get_pipeline_status),再调 review_videos 审视频与配音层(缺视频 / 旧帧出的视频 / 片尾硬切 / 意外人声 / 配音缺失 / 音色未分配 / 原声声线过期),修完复审;再按 agent_qc 亲自逐镜看视频、听配音(动作到位、不变脸、台词念全、嗓音对),submit_qc_report 提交;compose_episode 要带它的 review_token。★响应可能带**未接缝提示**(不影响 review_token / 报价 / 状态码):review_frames 与 generate_videos 是 unchained_seam_advisory,quote_videos 是 advisories 里 code=unchained_seams。seams 列的是 chain_frames 会接、却还没接上的相邻缝(from_shot→to_shot),status=no_stamp(从没接过)/ pending(发起过衔接、还没落地或审计未出结论)/ stale_anchor(上次承接的锚已失效:上一镜尾帧在衔接之后又被重生过,需要重接)/ join_failed(上次发起的衔接重生被拒 / 失败 / 落选,没落地)/ audit_failed(衔接落地但审计判不连续,看 get_storyboards 的 seam_failed_dims)/ first_frame_regenerated(接缝审过之后下镜首帧又被重出、没走承接路径,原衔接已不算数)/ not_linked(规划器判没接上、原因证据不足);都按计划重接即可;video_locked 是下镜已出视频的同类缝,chain_frames 不再改它们,只能逐镜 chain_shot_from_prev / chain_shot_from 换首帧后 regenerate_shot_video(都先报价)。出视频前看到 seams 就先 chain_frames(dry_run:true) 把计划与报价告诉客户,客户同意再执行,执行后重调 review_frames。",
+  "cancel_videos": "(免费)停掉本集 generate_videos 发起的整集出视频接力链。语义:**已派给厂商的镜照常出完、照常扣费(不退)**;还没派的不再派、不扣费;取消后服务重启也不会自动续跑。回执里 in_flight_shot_numbers = 已派出、会照常出完扣费的镜;cancelled_shot_numbers = 被取消、没出没扣费的镜。status=cancelling 表示链会在当前镜之后停下,用 get_run_status 等 video_run.status 变成 cancelled。被取消的镜之后可以重新 quote_videos 再 generate_videos 接着做(会跳过已出视频的镜),或 quote_regenerate_shot_video / regenerate_shot_video 单镜补。★只在客户明确要停时调用。单镜在途的视频(regenerate_shot_video 等)不能中途取消;本集没有在跑的整批链会返回 409 NO_ACTIVE_VIDEO_RUN。",
   "compose_episode": "把某一集所有镜头视频拼成一条成片(终拼)。**免费**(纯拼接,无需报价确认),后台异步。发起前有终拼预检:缺视频的镜或仍在生成中的视频任务会 400 硬阻断并列出问题镜(blockers),补齐后重试;确要拼部分成片传 force=true(缺视频镜被跳过,成片缺镜,留痕)。响应里的 advisories(时长偏差/孤儿任务/缺TTS/post_production_pending 后期特效未完成)只提醒不阻断,建议逐条处理后再拼。发起后用 get_final_cut 轮询。\n★【视频与配音审查硬闸·免费】本步前必须先调 review_videos:把返回的 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_videos 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。\n★★【成片前自检·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 失效。\n★【完成后质检·免费】成片出来后跑 review_final_cut(缺镜/字幕放不下/身份锚/跳轴/错别字,proofread=false 则不扣费),结论讲给客户;客户确认后才 confirm_delivery_acceptance(交付验收任何执行模式都须客户明确同意,托管也不例外)。force 只越过终拼预检,不越过审查闸。",
   "get_final_cut": "查某一集成片状态与下载链接。status=completed 时返回 download_url(我方 COS 直链,可直接下载)。免费。★bgm_stale=true 表示配乐在成片之后生成/改动、尚未进成片:重新 compose_episode(免费)即可,别用 re-render。★若设过当前交付版(register_external_delivery 登记的外部版,或 set_current_delivery 指定的平台版),另返回 delivery——那才是客户实际收到的一版;download_url 仍是平台最新一次拼的成片。要看每一版成片用了什么、哈希是多少,用 list_deliveries。",
   "get_export": "查某一集导出/母版状态(成片终拼后的可下载母版)。免费。",
@@ -135,13 +137,17 @@
   "regenerate_shot_video": "确认后重生某镜视频(可选新 prompt)。\n★收到 **409「本镜是用户上传的实拍素材」** = 该镜被 upload_shot_footage 登记成实拍素材镜,不是模型问题,换引擎无用;要用 AI 视频覆盖它就带 replace_user_footage=true,要保留素材就别重生。\n★收到 **409 + `in_flight_generation_id`** = 这一镜还有一条生成没跑完,而且它不是按这次的内容发起的(你带了新 prompt / 之后用 update_shot 改过该镜 / 之后换过该镜的首帧或尾帧——重出、上传、补出尾帧都算 / 这次带的帧、参考素材或引擎等参数与那次不同 / 在途的是一次编辑)。prompt 没变也可能是这个 409。这次重生没提交、没扣费,quote 已作废。先等在途那条完成、看过结果,再重新 quote 并重生——否则拿到的视频是旧内容(旧提示词或旧首尾帧)出的,会误以为改动没效果。\n★成功但返回里带 **`reused_in_flight: true`** = 同样的内容已经在生成(重发/双击/批量出视频已派发),这次没有新建、没有新扣费,返回的就是在途那一条,看它的进度即可,不必再发。\n★一键出片托管环节:同一镜重出视频最多 3 次(与 edit_video_shot 合计),到上限回 **409 AUTOPILOT_SHOT_REGEN_LIMIT**(未派发、未扣费,quote 未消耗)——别换个工具绕,停下问客户:客户同意再出就照常报价、生成时带 customer_approved_more_regens:true(再给一份上限);客户接受现状就往下走,下一步收费调用带 acknowledge_review:true 记下确认。专业模式与客户把控的环节不受这个上限约束。\n★【镜头图片审查硬闸·免费】本步前必须先调 review_frames:把返回的 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_frames 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。⚠️ 批量报价确认流程:先调对应的 quote_* 工具拿 estimated_points 与 quote_id,再用 quote_id 调本工具(报价确认按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)。托管环节报价须在预算硬上限内,被 402 BUDGET_WOULD_EXCEED 拦下就停下问客户。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。\n★【完成后质检·免费】出完等它落库(get_storyboards 看 video_status / get_pipeline_status),再调 review_videos 审视频与配音层(缺视频 / 旧帧出的视频 / 片尾硬切 / 意外人声 / 配音缺失 / 音色未分配 / 原声声线过期),修完复审;再按 agent_qc 亲自逐镜看视频、听配音(动作到位、不变脸、台词念全、嗓音对),submit_qc_report 提交;compose_episode 要带它的 review_token。",
   "split_shot": "把某镜按首尾帧拆成两镜(结构操作)。免费。",
   "trim_shot": "裁剪某镜时长(in_ms/out_ms)。免费;返回后需 rerender_episode 重拼成片。",
+  "set_shot_post": "终拼后期(镜级,免费,不重生、不扣费):① mirror_h 单镜水平镜像——画面左右翻转并同时对调左右声道,补救过轴镜(人物站位/伸手方向与前后镜左右相反);画面里有字(招牌、烧录字幕)的镜不要镜像,字会反过来。② grade_group 调色分组名——同名的镜一起自动拉平曝光与白平衡(默认按场景分组;单场景剧里清晨/黄昏/夜这类不同时段要各起一个组名,否则会被拉成一锅);grade_ref=true 把本镜设为该组的参考镜,组内其它镜向它看齐(不设则向组内中位数看齐)。③ audio_lead_in_ms J-cut——本镜的声音比画面早这么多毫秒进来(压在上一镜尾部,上一镜声音随之淡出),0~800,常用 300~500;原声镜的提前声音取自本镜源片入点之前那一段,所以**本镜必须先用 trim_shot 设入点(in_ms)≥提前量**,不够会按入点余量自动缩短,入点为 0 则不生效;有叠化转场或变速的接缝不做。只传要改的键,空调用=查看当前值;grade_group 传 null 取消分组。回包 gray_on=false 表示本剧尚未开放这组后期(值已保存,开放后生效)。改完要 compose_episode 重新合成才生效(rerender_episode 沿用旧时间线,不会带上)。",
+  "set_ambient_bed": "整场环境声床(免费,不重生、不扣费):给一组镜挂同一条环境底噪素材(风声、鸟鸣、室内底噪等),终拼时相邻且同一条素材的镜合成**一条连续轨**——跨镜不断、整段两端各淡 0.4 秒、有人说话时自动压低约 5dB。用来解决「每镜环境声各不相同、一切镜底噪就跳」。beds 每项 = {storyboard_ids, audio_url, gain_db?}:audio_url 必须是公网 http(s) 音频(素材短于整段会无缝循环),gain_db 取 -40~0、缺省 -18;audio_url=null 取消这些镜的声床。同一场戏里不同时段要换素材就分成两项;中间想静一下的镜不放进任何一项,声床会在那里断开。回包 runs 是按镜序合成的段;gray_on=false 表示本剧尚未开放(值已保存,开放后生效)。改完要 compose_episode 重新合成才生效(rerender_episode 沿用旧时间线)。MV 不铺声床。",
   "recommend_trim_window": "裁剪窗口动作QC:对「声明时长<真实视频时长」的独立生成镜,按片内活动检测推荐 in/out 裁剪窗口——供应商产片动作常在后半段,默认从 0 秒裁会截在半动作态(如抬手没打下去)。免费零扣费。组模式镜不适用(组切分已内容感知,返回 applicable=false)。拿到推荐后用 trim_shot 应用。",
   "scan_intra_shot_cuts": "★客户报「镜头切太快 / 一个镜头里画面跳来跳去」时先跑这个。免费零扣费。一个分镜本应是**一个连续镜头**,但厂商可能在片内自行换机位硬切(望远镜特写→高空全景→人物中景),这类切点在分镜表和 timeline 里都看不到——只能扫画面。返回 shots_with_cuts(有镜内跳切的镜号)/total_cuts/engine_suspect/message；shots_with_terminal_cuts 单列疑似短促片尾切镜，detail.terminal_cut 给出位置和状态。★判读:成片观感切点 = 镜与镜的接缝 + 这里报的镜内跳切;若本项占了大头,那不是剪辑节奏问题,重新拆镜或改转场都没用。engine_suspect=true 表示本剧引擎是已知高发源(WAN),实测 WAN 11/12 镜有镜内跳切、Seedance 1/6、H3 0/5,且提示词层拦不住(负向约束已在其中)——先复核实际切点与叙事意图，再决定调整切分还是重新生成；不要因扫描告警直接重试收费生成。普通镜内多切统计仍排除组模式与显式蒙太奇；但组切分后的单段不能豁免片尾检查，需另看 shots_with_terminal_cuts/detail.terminal_cut。",
   "scan_burned_subtitles": "★原声剧（视频自带人声）终拼前建议跑一次；客户报「成片里有两层字幕 / 画面里多出一行字」时先跑这个。视频厂商有时会无视「不要字幕」的约束，把台词烧进画面——字小、通常只在说出那句台词的一两秒内出现，而平台成片还会再叠一层字幕，于是变成双字幕。重新拼接去不掉它，只能 regenerate_shot_video 重出该镜。每镜抽 12 帧、一次视觉审计，**按用量计费**（每镜一次小额 vision 调用）。返回 flagged[{shot, texts, matches_dialogue, frames}] / clean / errors。matches_dialogue=true 表示读出来的字就是本镜台词，基本可确认是厂商字幕；招牌、书页、屏幕等画面里本来就有的字不算。dry_run=true 只报告不写回；否则结果写回，compose_episode 的终拼预检会以 vendor_burned_text 列出这些镜。",
   "scan_wardrobe_consistency": "★客户报「同一个角色前后换了衣服 / 衣服颜色款式不对」时跑这个；终拼前也建议跑一次。逐镜把采用的首帧和视频中段一帧，与本镜每个角色的设定图（没有则用定妆图）比对衣服的款式与颜色。常见成因是远景小人物被出图模型画成了别的衣服——即使参考图和提示词都对。夜景/暖光的整体偏色不算不一致。每镜一次视觉审计，**按用量计费**。返回 flagged[{shot, characters:[{name, differences}]}] / clean / errors。dry_run=true 只报告不写回；否则写回，compose_episode 的终拼预检会以 wardrobe_mismatch 列出这些镜。处置：重出该镜首帧（generate_shot_frame）再 regenerate_shot_video；重新拼接去不掉。",
   "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 重出；要保住首尾帧（重出会丢构图）就走 quote_voice_unify → unify_voices，事后把人声转成声线锚的嗓音、不重生视频。做过声线统一的镜带 voice_unify：similarity / coverage / loudness_db 都是 before→after；summary.voice_unified=已进成片的镜号。",
-  "quote_voice_unify": "★原声剧（视频自带人声）「同一个角色前后嗓音不一样」、又不想为声线重出视频丢掉首尾帧构图时用。免费报价、只读。列出本集每个有台词的镜要不要做「事后声线统一」及原因：to_process=出片时没送声线锚 / 送的是旧锚，一定处理；conditional=出片时已送进当前锚，执行时先测声纹，对得上就跳过、不收费；skipped=不动（锁定镜、实拍、已有换轨产物、角色没有声线锚等，见 reason_text）。多人镜按说话人分别判，只改需要处理的那个人的句子。按转换的人声秒数计费：estimated_points 是上界、typical_points 是通常花费，两个都告诉客户，客户同意后带 quote_id 调 unify_voices。角色没有声线锚的先 set_character_voice 或 set_voice_anchor_from_shot（挑一镜嗓音最对的当基准）。逐剧灰度，未开通回 403。",
+  "quote_voice_unify": "★原声剧（视频自带人声）「同一个角色前后嗓音不一样」、又不想为声线重出视频丢掉首尾帧构图时用。免费报价、只读。列出本集每个有台词的镜要不要做「事后声线统一」及原因：to_process=出片时没送声线锚 / 送的是旧锚，一定处理；conditional=出片时已送进当前锚，执行时先测声纹，对得上就跳过、不收费；skipped=不动（锁定镜、实拍、已有换轨产物、角色没有声线锚等，见 reason_text）。多人镜按说话人分别判，只改需要处理的那个人的句子。按转换的人声秒数计费：estimated_points 是上界、typical_points 是通常花费，两个都告诉客户，客户同意后带 quote_id 调 unify_voices。目标嗓音优先用 set_voice_unify_target 指定（挑一镜嗓音最对的当基准；不影响出片路线），没指定就用角色的 IP 声线锚。逐剧灰度，未开通回 403。",
+  "set_voice_unify_target": "给角色指定「统一目标嗓音」：取自嗓音最对的那一镜，只给事后声线统一（quote_voice_unify → unify_voices）用。免费。★与 set_character_voice / set_voice_anchor_from_shot 的区别：那两个设的是 IP 声线锚，原声剧出片时会送参考音频，首尾帧可能锁不住；这个字段出片路由不读，设了它仍按「首尾帧锁画面、出完再统一声线」走。指定后，该角色每一镜都先测声纹，对得上就跳过、不收费；目标镜自己跳过。这一镜必须已有视频、且只有该角色在说话（多人镜会把别人的嗓音一起当成目标，回 400）。清除用 clear_voice_unify_target。逐剧灰度，未开通回 403。",
+  "clear_voice_unify_target": "清除角色的「统一目标嗓音」（set_voice_unify_target 设的）。免费。清除后声线统一改用角色的 IP 声线锚；两者都没有就跳过该角色。",
   "unify_voices": "执行事后声线统一（必须先 quote_voice_unify，客户同意后带 quote_id）。只跑报价里的镜，后台串行（每镜约 1~2 分钟）。每镜：分离人声 → 按台词与声纹定位该角色的句子 → 逐句转成声线锚的嗓音（每句时长只变 ≤0.05s，口型与画面不动、不重生视频）→ 回填，环境声与音效原样保留。质检任一不过（转写覆盖率下降 / 时长差 >0.1s / 与锚的相似度没提升 / 响度差 >1dB）就保留原音轨并退回该镜费用。用 get_voice_unify_status 看进度与每镜前后对比；status=applied 的镜重拼成片（rerender_episode）后生效。",
   "get_voice_unify_status": "查声线统一的进度与逐镜结果（免费）。summary：applied=已统一（重拼成片后生效）/ kept_original=质检没过、保留原音轨、费用已退（reason 写了哪项没过）/ skipped=测下来声纹本来就对得上或找不到该角色的人声 / errors=失败（费用已退）/ superseded=处理期间镜头被重出、换版本或锁定，结果作废未写回（费用已退）。每镜带 similarity（before→after，与声线锚的相似度）、coverage、loudness_db、points；stale=视频或产物换过、结论过期。",
   "preview_voice_unify": "对单镜试听声线统一效果（免费、不写回、不扣费）。异步：start=true 启动（约 1~2 分钟），之后不带 start 再调一次取结果；结果里 productUrl 是处理后的视频（可直接听），checks 是四项质检结论。默认用该角色的声线锚当目标嗓音；reference_storyboard_id=同一集里嗓音最对的那一镜时，改用那一镜的人声当目标（适合角色还没绑锚、先挑基准的情况，speaker 指定转哪个角色）。",
@@ -185,7 +191,7 @@
   "clear_character_av_anchor": "摘掉某角色的定妆视频锚并停用自动建锚。免费。★必须客户确认后再调,先用 get_av_anchors 把锚的来源讲给客户。后果两面都要讲清:①摘锚后含该角色的镜首帧恢复送达,不再因参考视频互斥被剥(尾帧仍按动作类型等常规规则判定,以重新报价的 frame_delivery 为准);②台词镜的声线不再锚定锚片里的嗓音,只靠厂商按文字和首帧生成,跨镜声线可能有差异;长相改由定妆照/首帧锚定。默认停用:之后出视频不再挂它,也不会自动重建。allow_auto_rebuild:true = 只清锚不停用(下次出视频平台自动重选一镜重建,首尾帧又会被剥),也是停用后的恢复入口。这是解除引用不是删除:锚片文件不删,回执 unlinked 列出摘下的 URL(list_unlinked_assets 可查)。已出的视频不受影响;摘完重新报价(quote_videos / quote_regenerate_shot_video)核对 frame_delivery 与 advisories。",
   "get_scenes": "读某一集的场景列表(名字/描述/场景图是否就绪)。免费。",
   "get_assets": "读一部剧的全部资产聚合(角色/场景/道具/图片)。免费。",
-  "get_jobs": "查一部剧的任务队列进度(出图/出视频/合成各阶段的 pending/processing/done/failed)。异步生成后用它看进度。免费。★整集出帧(generate_frames)是后台逐镜派发,被拒的镜不会出现在任务列表里——看响应的 frame_dispatch_rejections(每镜 storyboard_id/frame_type/code/message)。code=ERA_USER_REF_CONFLICT 表示客户上传的定妆图被时代审核判冲突:把 message 转告客户(allow_era_ref_conflict 任何执行模式都须客户明确同意,托管也不例外),客户确认后带 allow_era_ref_conflict=true 对那几镜 generate_shot_frame。重启后该列表清空。",
+  "get_jobs": "查一部剧的任务队列进度(出图/出视频/合成各阶段的 pending/processing/done/failed)。异步生成后用它看进度。免费。★整集出帧(generate_frames)是后台逐镜派发,被拒的镜不会出现在任务列表里——看响应的 frame_dispatch_rejections(每镜 storyboard_id/frame_type/code/message)。code=ERA_USER_REF_CONFLICT 表示客户上传的定妆图被时代审核判冲突:把 message 转告客户(allow_era_ref_conflict 任何执行模式都须客户明确同意,托管也不例外),客户确认后带 allow_era_ref_conflict=true 对那几镜 generate_shot_frame。重启后该列表清空。★image_batches = 最近 24 小时的批量出图批次(含 cancel_images 取消的,status=cancelled)。",
   "get_drama_bill": "本剧净费用账单(免费)。核账、回答「到底花了多少、钱花在哪、退了多少」时用它,别自己拼流水。\n· totals / by_kind:每类 charged(扣费)、refunded(已退回)、net(净额)、charges/refunds(笔数)。**net 才是花费**,与网页「本剧已花费」、get_budget_status 同源;charged 含失败后自动退回的空转,只用于核账。\n· in_flight:已扣费、结果还没出的任务(平台是提交即扣、失败再退,没有单独的预扣)。\n· rework.video:同一镜第 2 次起的成功出片计数(不证明浪费或失败);原因与图片费用用 get_cost_attribution 核验。旧统计出图不计(首帧/尾帧/best-of-N 候选本来就是同镜多张)。\n· account_level:音色库克隆/设计/试听等**不属于任何一部剧**的语音扣费,单列、counted_in_drama=false,不计入本剧。\n· available=false:账本暂时不可达,不给数字(不拿估算冒充),稍后重试。",
   "get_cost_attribution": "读取实际扣费与退款逐行归因。免费；净额仍以账本为准。图片和视频均显示任务、冻结输入版本、是否采用和明确登记的返工原因。未知和歧义不猜测；未采用不等于浪费。available=false 时没有可靠金额；complete=false 时明细有截断但 totals 是全额。历史 rework.video 只是重复成功出片的计数，不证明失败或浪费。",
   "classify_cost_reason": "按明确证据登记某一账本行原因，保留操作者和说明。免费，不改变任何扣费或退款；不能仅凭未采用、重试或报错就判为供应商失败。",

package/dist/tools/guide-data.js

@@ -167,6 +167,8 @@ export const ENTRY_POINTS = [
             'repair_episode_dialogue(换音频不重生视频,按 TTS 费率,比重生便宜几个数量级)',
             'split_shot',
             'trim_shot',
+            'set_shot_post(镜级终拼后期,免费:过轴镜水平镜像连声道对调 / 调色分组与参考镜拉平曝光白平衡 / J-cut 声音先于画面进;改完 compose_episode 重新合成)',
+            'set_ambient_bed(整场环境声床,免费:一组镜共用一条连续底噪,跨镜不断、说话时自动压低;改完 compose_episode 重新合成)',
             'recommend_trim_window',
             'preview_seams / get_seam_previews(每道接缝一段 2 秒短片 + 边缘帧对照,与终拼同逻辑;查转场不必导整片;免费)',
             'build_av_timing_contract / get_av_timing_contract(逐镜音画时长契约:实测源片时长/入出点/定格与低运动尾段/人声混入视频还是独立轨/终拼起止与转场;与终拼同逻辑;免费)',
@@ -320,6 +322,10 @@ export const QA_TOOLS = [
             'update_shot(speed_factor:只是成片里变速播放,不改厂商生成的内容——做慢镜氛围用,治不了「没演出来」)',
         ] },
     { symptom: '动作发生在裁剪窗口之外', run: 'recommend_trim_window', then: ['trim_shot'] },
+    { symptom: '镜头过轴(人物左右站位 / 伸手方向与前后镜相反)', run: 'set_shot_post(mirror_h=true,免费;画面翻转同时对调左右声道;画面里有字的镜别用)', then: ['compose_episode'] },
+    { symptom: '同一段戏相邻镜头忽明忽暗 / 冷暖不一', run: 'set_shot_post(grade_group 给同一时段的镜起同一个组名,grade_ref=true 指定参考镜;免费)', then: ['compose_episode'] },
+    { symptom: '一切镜环境声 / 底噪就跳、听着不连续', run: 'set_ambient_bed(同一段戏的镜挂同一条环境声素材,免费)', then: ['compose_episode'] },
+    { symptom: '切镜太生硬,想让下一镜的声音先进来(J-cut)', run: 'trim_shot(先给下一镜设入点 in_ms ≥ 提前量)', then: ['set_shot_post(audio_lead_in_ms=300~500)', 'compose_episode'] },
     { symptom: '转场 / 接缝看着不对(跳、重影、接不上)', run: 'preview_seams(免费;get_seam_previews 轮询,逐道缝看短片与对照图,别反复导出整片)', then: ['recommend_trim_window → trim_shot(动作没接上)', 'update_shot(transition_type / transition_duration_ms 改转场,免费;之后 compose_episode 重拼才生效)', 'preview_seams(改完只传那道缝的 seams 序号复查——叠化/插镜/遮挡这类补救常带出新问题)'] },
     { symptom: '画面多出一个人 / 多出一件道具', run: 'get_storyboards(先看该镜实际用的首帧)', then: ['local_frame_edit(首帧本身就有、其余都对→edit_kind=object_remove 只擦那一块;灰度剧)', 'generate_shot_frame(首帧本身就有→重生首帧再重生视频)', 'split_shot(帧干净、片中长出来→拆成 3~5 秒短镜)'] },
     { symptom: '镜头图只有一小块不对(脸不像 / 嘴张着 / 边缘毛边 / 手指畸形),其余已经确认', run: 'quote_local_frame_edit(框出那一块,报价免费)', then: ['local_frame_edit(框外像素原样保留;修脸带 character_id)', 'get_local_frame_edit(看 composited_url 与 verdict)', 'adopt_local_frame_edit(客户选定后才写帧)'] },

package/dist/tools/produce.js

@@ -639,6 +639,7 @@ export function registerProduceTools(server, client) {
         '★一键 / 混合模式(托管灰度内)的剧额外返回 next_action(action=run 托管环节直接做 / wait_running 后台还在跑、等它落库别重复派 / wait_customer 客户把控环节或没有预算预检的步骤先问 / ask_customer 有待问事项先汇总问 / done 各步完成——先按 tool=review_final_cut 审成片、有问题修完重拼复审,再出交付报告;tool=该调哪个工具)与 pending_questions,照 next_action 推进。' +
         'asset_versions_summary 将 generated、input_consistent、review_valid、adopted 和 current_effective 分开计数；不能把 generate_videos.completed 当当前有效数量。' +
         '★generate_images / generate_videos 的 status=done 只表示「已生成」，不代表可交付：看同一步的 validity（current_effective 当前有效 / input_changed 生成后输入已变，changed_by 列出是剧级设定、镜头本身还是哪个角色变了 / input_unknown / unreviewed / review_failed），validity.note 不为空时先把它告诉客户。输入变了不一定影响画面，别据此整集重出（付费），先用 get_asset_versions 逐镜看原因。' +
+        'validity.review_advised（asset_versions_summary 里同样单列 review_advised，stale 不含它）= 只有角色外观文本被改写（多是重新提取时换了写法）：仍算输入已变，但画面身份由定妆图锚定，属「建议复核」，review_advised_by 按角色列出——请客户对照定妆图确认，不要当作需重出。' +
         '★not_required=当前模式不需要该步(如原声剧的 TTS 三步、关配乐的 generate_bgm),不是没做完,别去补做。' +
         '图片/视频分母已剔除卡镜(shots_not_applicable);merge_episode.bgm_stale=true 表示配乐晚于成片,重新 compose_episode 即可。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/pipeline-status`)));
     // ---------- 角色定妆图(一致性锚) ----------
@@ -1758,6 +1759,21 @@ export function registerProduceTools(server, client) {
         in_ms: z.number().int().min(0).optional(),
         out_ms: z.number().int().min(0).optional(),
     }, async ({ storyboard_id, in_ms, out_ms }) => jsonResult(await client.producePut(`/storyboards/${storyboard_id}/trim`, { in_ms, out_ms })));
+    server.tool('set_shot_post', "终拼后期(镜级,免费,不重生、不扣费):① mirror_h 单镜水平镜像——画面左右翻转并同时对调左右声道,补救过轴镜(人物站位/伸手方向与前后镜左右相反);画面里有字(招牌、烧录字幕)的镜不要镜像,字会反过来。② grade_group 调色分组名——同名的镜一起自动拉平曝光与白平衡(默认按场景分组;单场景剧里清晨/黄昏/夜这类不同时段要各起一个组名,否则会被拉成一锅);grade_ref=true 把本镜设为该组的参考镜,组内其它镜向它看齐(不设则向组内中位数看齐)。③ audio_lead_in_ms J-cut——本镜的声音比画面早这么多毫秒进来(压在上一镜尾部,上一镜声音随之淡出),0~800,常用 300~500;原声镜的提前声音取自本镜源片入点之前那一段,所以**本镜必须先用 trim_shot 设入点(in_ms)≥提前量**,不够会按入点余量自动缩短,入点为 0 则不生效;有叠化转场或变速的接缝不做。只传要改的键,空调用=查看当前值;grade_group 传 null 取消分组。回包 gray_on=false 表示本剧尚未开放这组后期(值已保存,开放后生效)。改完要 compose_episode 重新合成才生效(rerender_episode 沿用旧时间线,不会带上)。", {
+        storyboard_id: z.number().int().positive(),
+        mirror_h: z.boolean().optional(),
+        grade_group: z.string().max(40).nullable().optional(),
+        grade_ref: z.boolean().optional(),
+        audio_lead_in_ms: z.number().int().min(0).max(800).optional(),
+    }, async ({ storyboard_id, ...rest }) => jsonResult(await client.producePut(`/storyboards/${storyboard_id}/compose-post`, rest)));
+    server.tool('set_ambient_bed', "整场环境声床(免费,不重生、不扣费):给一组镜挂同一条环境底噪素材(风声、鸟鸣、室内底噪等),终拼时相邻且同一条素材的镜合成**一条连续轨**——跨镜不断、整段两端各淡 0.4 秒、有人说话时自动压低约 5dB。用来解决「每镜环境声各不相同、一切镜底噪就跳」。beds 每项 = {storyboard_ids, audio_url, gain_db?}:audio_url 必须是公网 http(s) 音频(素材短于整段会无缝循环),gain_db 取 -40~0、缺省 -18;audio_url=null 取消这些镜的声床。同一场戏里不同时段要换素材就分成两项;中间想静一下的镜不放进任何一项,声床会在那里断开。回包 runs 是按镜序合成的段;gray_on=false 表示本剧尚未开放(值已保存,开放后生效)。改完要 compose_episode 重新合成才生效(rerender_episode 沿用旧时间线)。MV 不铺声床。", {
+        episode_id: z.number().int().positive(),
+        beds: z.array(z.object({
+            storyboard_ids: z.array(z.number().int().positive()).min(1).max(300),
+            audio_url: z.string().url().nullable(),
+            gain_db: z.number().min(-40).max(0).optional(),
+        })).min(1).max(50),
+    }, async ({ episode_id, beds }) => jsonResult(await client.producePut(`/episodes/${episode_id}/ambient-bed`, { beds })));
     server.tool('recommend_trim_window', '裁剪窗口动作QC:对「声明时长<真实视频时长」的独立生成镜,按片内活动检测推荐 in/out 裁剪窗口——'
         + '供应商产片动作常在后半段,默认从 0 秒裁会截在半动作态(如抬手没打下去)。免费零扣费。'
         + '组模式镜不适用(组切分已内容感知,返回 applicable=false)。拿到推荐后用 trim_shot 应用。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/trim/recommend`)));
@@ -1797,7 +1813,15 @@ export function registerProduceTools(server, client) {
         '列出本集每个有台词的镜要不要做「事后声线统一」及原因：to_process=出片时没送声线锚 / 送的是旧锚，一定处理；' +
         'conditional=出片时已送进当前锚，执行时先测声纹，对得上就跳过、不收费；skipped=不动（锁定镜、实拍、已有换轨产物、角色没有声线锚等，见 reason_text）。' +
         '多人镜按说话人分别判，只改需要处理的那个人的句子。按转换的人声秒数计费：estimated_points 是上界、typical_points 是通常花费，两个都告诉客户，客户同意后带 quote_id 调 unify_voices。' +
-        '角色没有声线锚的先 set_character_voice 或 set_voice_anchor_from_shot（挑一镜嗓音最对的当基准）。逐剧灰度，未开通回 403。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/voice-unify/quote`)));
+        '目标嗓音优先用 set_voice_unify_target 指定（挑一镜嗓音最对的当基准；不影响出片路线），没指定就用角色的 IP 声线锚。逐剧灰度，未开通回 403。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/voice-unify/quote`)));
+    server.tool('set_voice_unify_target', '给角色指定「统一目标嗓音」：取自嗓音最对的那一镜，只给事后声线统一（quote_voice_unify → unify_voices）用。免费。' +
+        '★与 set_character_voice / set_voice_anchor_from_shot 的区别：那两个设的是 IP 声线锚，原声剧出片时会送参考音频，首尾帧可能锁不住；' +
+        '这个字段出片路由不读，设了它仍按「首尾帧锁画面、出完再统一声线」走。指定后，该角色每一镜都先测声纹，对得上就跳过、不收费；目标镜自己跳过。' +
+        '这一镜必须已有视频、且只有该角色在说话（多人镜会把别人的嗓音一起当成目标，回 400）。清除用 clear_voice_unify_target。逐剧灰度，未开通回 403。', {
+        character_id: z.number().int().positive(),
+        storyboard_id: z.number().int().positive().describe('嗓音最对、且只有该角色说话的那一镜（同一部剧、已有视频）'),
+    }, async ({ character_id, storyboard_id }) => jsonResult(await client.producePut(`/characters/${character_id}/voice-unify-target`, { storyboard_id })));
+    server.tool('clear_voice_unify_target', '清除角色的「统一目标嗓音」（set_voice_unify_target 设的）。免费。清除后声线统一改用角色的 IP 声线锚；两者都没有就跳过该角色。', { character_id: z.number().int().positive() }, async ({ character_id }) => jsonResult(await client.produceDelete(`/characters/${character_id}/voice-unify-target`)));
     server.tool('unify_voices', '执行事后声线统一（必须先 quote_voice_unify，客户同意后带 quote_id）。只跑报价里的镜，后台串行（每镜约 1~2 分钟）。' +
         '每镜：分离人声 → 按台词与声纹定位该角色的句子 → 逐句转成声线锚的嗓音（每句时长只变 ≤0.05s，口型与画面不动、不重生视频）→ 回填，环境声与音效原样保留。' +
         '质检任一不过（转写覆盖率下降 / 时长差 >0.1s / 与锚的相似度没提升 / 响度差 >1dB）就保留原音轨并退回该镜费用。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.242",
-    "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.242 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.247",
+    "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.247 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -983,6 +983,118 @@
         }
       }
     },
+    "/characters/{character_id}/voice-unify-target": {
+      "put": {
+        "operationId": "set_voice_unify_target",
+        "summary": "给角色指定「统一目标嗓音」：取自嗓音最对的那一镜，只给事后声线统一（quote_voice_unify → unify_voices）用",
+        "description": "给角色指定「统一目标嗓音」：取自嗓音最对的那一镜，只给事后声线统一（quote_voice_unify → unify_voices）用。免费。★与 set_character_voice / set_voice_anchor_from_shot 的区别：那两个设的是 IP 声线锚，原声剧出片时会送参考音频，首尾帧可能锁不住；这个字段出片路由不读，设了它仍按「首尾帧锁画面、出完再统一声线」走。指定后，该角色每一镜都先测声纹，对得上就跳过、不收费；目标镜自己跳过。这一镜必须已有视频、且只有该角色在说话（多人镜会把别人的嗓音一起当成目标，回 400）。清除用 clear_voice_unify_target。逐剧灰度，未开通回 403。",
+        "tags": [
+          "characters"
+        ],
+        "parameters": [
+          {
+            "name": "character_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "storyboard_id": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "description": "嗓音最对、且只有该角色说话的那一镜（同一部剧、已有视频）"
+                  }
+                },
+                "required": [
+                  "storyboard_id"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "clear_voice_unify_target",
+        "summary": "清除角色的「统一目标嗓音」（set_voice_unify_target 设的）",
+        "description": "清除角色的「统一目标嗓音」（set_voice_unify_target 设的）。免费。清除后声线统一改用角色的 IP 声线锚；两者都没有就跳过该角色。",
+        "tags": [
+          "characters"
+        ],
+        "parameters": [
+          {
+            "name": "character_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      }
+    },
     "/dramas": {
       "post": {
         "operationId": "create_drama",
@@ -4909,6 +5021,108 @@
         }
       }
     },
+    "/episodes/{episode_id}/ambient-bed": {
+      "put": {
+        "operationId": "set_ambient_bed",
+        "summary": "整场环境声床(免费,不重生、不扣费):给一组镜挂同一条环境底噪素材(风声、鸟鸣、室内底噪等),终拼时相邻且同一条素材的镜合成**一条连续轨**——跨镜不断、整段两端各淡 0",
+        "description": "整场环境声床(免费,不重生、不扣费):给一组镜挂同一条环境底噪素材(风声、鸟鸣、室内底噪等),终拼时相邻且同一条素材的镜合成**一条连续轨**——跨镜不断、整段两端各淡 0.4 秒、有人说话时自动压低约 5dB。用来解决「每镜环境声各不相同、一切镜底噪就跳」。beds 每项 = {storyboard_ids, audio_url, gain_db?}:audio_url 必须是公网 http(s) 音频(素材短于整段会无缝循环),gain_db 取 -40~0、缺省 -18;audio_url=null 取消这些镜的声床。同一场戏里不同时段要换素材就分成两项;中间想静一下的镜不放进任何一项,声床会在那里断开。回包 runs 是按镜序合成的段;gray_on=false 表示本剧尚未开放(值已保存,开放后生效)。改完要 compose_episode 重新合成才生效(rerender_episode 沿用旧时间线)。MV 不铺声床。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "beds": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "storyboard_ids": {
+                          "type": "array",
+                          "items": {
+                            "type": "integer",
+                            "exclusiveMinimum": 0
+                          },
+                          "minItems": 1,
+                          "maxItems": 300
+                        },
+                        "audio_url": {
+                          "anyOf": [
+                            {
+                              "type": "string",
+                              "format": "uri"
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ]
+                        },
+                        "gain_db": {
+                          "type": "number",
+                          "minimum": -40,
+                          "maximum": 0
+                        }
+                      },
+                      "required": [
+                        "storyboard_ids",
+                        "audio_url"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "minItems": 1,
+                    "maxItems": 50
+                  }
+                },
+                "required": [
+                  "beds"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      }
+    },
     "/episodes/{episode_id}/asset-binding-repair-plan": {
       "get": {
         "operationId": "get_asset_binding_repair_plan",
@@ -8018,7 +8232,7 @@
       "get": {
         "operationId": "get_pipeline_status",
         "summary": "查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 done/partial/pending/not_required)",
-        "description": "查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 done/partial/pending/not_required)。照它按序推进、不跳步。免费。★一键 / 混合模式(托管灰度内)的剧额外返回 next_action(action=run 托管环节直接做 / wait_running 后台还在跑、等它落库别重复派 / wait_customer 客户把控环节或没有预算预检的步骤先问 / ask_customer 有待问事项先汇总问 / done 各步完成——先按 tool=review_final_cut 审成片、有问题修完重拼复审,再出交付报告;tool=该调哪个工具)与 pending_questions,照 next_action 推进。asset_versions_summary 将 generated、input_consistent、review_valid、adopted 和 current_effective 分开计数；不能把 generate_videos.completed 当当前有效数量。★generate_images / generate_videos 的 status=done 只表示「已生成」，不代表可交付：看同一步的 validity（current_effective 当前有效 / input_changed 生成后输入已变，changed_by 列出是剧级设定、镜头本身还是哪个角色变了 / input_unknown / unreviewed / review_failed），validity.note 不为空时先把它告诉客户。输入变了不一定影响画面，别据此整集重出（付费），先用 get_asset_versions 逐镜看原因。★not_required=当前模式不需要该步(如原声剧的 TTS 三步、关配乐的 generate_bgm),不是没做完,别去补做。图片/视频分母已剔除卡镜(shots_not_applicable);merge_episode.bgm_stale=true 表示配乐晚于成片,重新 compose_episode 即可。",
+        "description": "查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 done/partial/pending/not_required)。照它按序推进、不跳步。免费。★一键 / 混合模式(托管灰度内)的剧额外返回 next_action(action=run 托管环节直接做 / wait_running 后台还在跑、等它落库别重复派 / wait_customer 客户把控环节或没有预算预检的步骤先问 / ask_customer 有待问事项先汇总问 / done 各步完成——先按 tool=review_final_cut 审成片、有问题修完重拼复审,再出交付报告;tool=该调哪个工具)与 pending_questions,照 next_action 推进。asset_versions_summary 将 generated、input_consistent、review_valid、adopted 和 current_effective 分开计数；不能把 generate_videos.completed 当当前有效数量。★generate_images / generate_videos 的 status=done 只表示「已生成」，不代表可交付：看同一步的 validity（current_effective 当前有效 / input_changed 生成后输入已变，changed_by 列出是剧级设定、镜头本身还是哪个角色变了 / input_unknown / unreviewed / review_failed），validity.note 不为空时先把它告诉客户。输入变了不一定影响画面，别据此整集重出（付费），先用 get_asset_versions 逐镜看原因。validity.review_advised（asset_versions_summary 里同样单列 review_advised，stale 不含它）= 只有角色外观文本被改写（多是重新提取时换了写法）：仍算输入已变，但画面身份由定妆图锚定，属「建议复核」，review_advised_by 按角色列出——请客户对照定妆图确认，不要当作需重出。★not_required=当前模式不需要该步(如原声剧的 TTS 三步、关配乐的 generate_bgm),不是没做完,别去补做。图片/视频分母已剔除卡镜(shots_not_applicable);merge_episode.bgm_stale=true 表示配乐晚于成片,重新 compose_episode 即可。",
         "tags": [
           "episodes"
         ],
@@ -11560,7 +11774,7 @@
       "get": {
         "operationId": "quote_voice_unify",
         "summary": "★原声剧（视频自带人声）「同一个角色前后嗓音不一样」、又不想为声线重出视频丢掉首尾帧构图时用",
-        "description": "★原声剧（视频自带人声）「同一个角色前后嗓音不一样」、又不想为声线重出视频丢掉首尾帧构图时用。免费报价、只读。列出本集每个有台词的镜要不要做「事后声线统一」及原因：to_process=出片时没送声线锚 / 送的是旧锚，一定处理；conditional=出片时已送进当前锚，执行时先测声纹，对得上就跳过、不收费；skipped=不动（锁定镜、实拍、已有换轨产物、角色没有声线锚等，见 reason_text）。多人镜按说话人分别判，只改需要处理的那个人的句子。按转换的人声秒数计费：estimated_points 是上界、typical_points 是通常花费，两个都告诉客户，客户同意后带 quote_id 调 unify_voices。角色没有声线锚的先 set_character_voice 或 set_voice_anchor_from_shot（挑一镜嗓音最对的当基准）。逐剧灰度，未开通回 403。",
+        "description": "★原声剧（视频自带人声）「同一个角色前后嗓音不一样」、又不想为声线重出视频丢掉首尾帧构图时用。免费报价、只读。列出本集每个有台词的镜要不要做「事后声线统一」及原因：to_process=出片时没送声线锚 / 送的是旧锚，一定处理；conditional=出片时已送进当前锚，执行时先测声纹，对得上就跳过、不收费；skipped=不动（锁定镜、实拍、已有换轨产物、角色没有声线锚等，见 reason_text）。多人镜按说话人分别判，只改需要处理的那个人的句子。按转换的人声秒数计费：estimated_points 是上界、typical_points 是通常花费，两个都告诉客户，客户同意后带 quote_id 调 unify_voices。目标嗓音优先用 set_voice_unify_target 指定（挑一镜嗓音最对的当基准；不影响出片路线），没指定就用角色的 IP 声线锚。逐剧灰度，未开通回 403。",
         "tags": [
           "episodes"
         ],
@@ -14419,6 +14633,87 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/compose-post": {
+      "put": {
+        "operationId": "set_shot_post",
+        "summary": "终拼后期(镜级,免费,不重生、不扣费):① mirror_h 单镜水平镜像——画面左右翻转并同时对调左右声道,补救过轴镜(人物站位/伸手方向与前后镜左右相反);画面里有字(招牌、烧录字幕)的镜不要镜像,字会反过来",
+        "description": "终拼后期(镜级,免费,不重生、不扣费):① mirror_h 单镜水平镜像——画面左右翻转并同时对调左右声道,补救过轴镜(人物站位/伸手方向与前后镜左右相反);画面里有字(招牌、烧录字幕)的镜不要镜像,字会反过来。② grade_group 调色分组名——同名的镜一起自动拉平曝光与白平衡(默认按场景分组;单场景剧里清晨/黄昏/夜这类不同时段要各起一个组名,否则会被拉成一锅);grade_ref=true 把本镜设为该组的参考镜,组内其它镜向它看齐(不设则向组内中位数看齐)。③ audio_lead_in_ms J-cut——本镜的声音比画面早这么多毫秒进来(压在上一镜尾部,上一镜声音随之淡出),0~800,常用 300~500;原声镜的提前声音取自本镜源片入点之前那一段,所以**本镜必须先用 trim_shot 设入点(in_ms)≥提前量**,不够会按入点余量自动缩短,入点为 0 则不生效;有叠化转场或变速的接缝不做。只传要改的键,空调用=查看当前值;grade_group 传 null 取消分组。回包 gray_on=false 表示本剧尚未开放这组后期(值已保存,开放后生效)。改完要 compose_episode 重新合成才生效(rerender_episode 沿用旧时间线,不会带上)。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "mirror_h": {
+                    "type": "boolean"
+                  },
+                  "grade_group": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "maxLength": 40
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "grade_ref": {
+                    "type": "boolean"
+                  },
+                  "audio_lead_in_ms": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 800
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      }
+    },
     "/storyboards/{storyboard_id}/dialogue-replace": {
       "post": {
         "operationId": "replace_shot_dialogue",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.242",
+  "version": "0.1.247",
   "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.242",
+  "version": "0.1.247",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.242",
+      "version": "0.1.247",
       "transport": {
         "type": "stdio"
       },