@starreel/mcp 0.1.137 → 0.1.139

package/SKILL.md

@@ -85,6 +85,7 @@ announces a condensed version as MCP `instructions` at connect time.
 | Their own portraits / scene / prop / shot images | `upload_image` · `set_character_portrait` · `upload_scene_image` · `upload_prop_sheet` · `upload_shot_frame` — **check the image before uploading** (see *Customer-supplied images* below); after a portrait swap, `generate_character_sheet` for that character (the old sheet is invalidated and **not** regenerated automatically) | rendering a "fix" elsewhere and uploading it — use `generate_shot_frame`; uploading a group photo, a captioned/watermarked image, or a multi-view sheet as a portrait; uploading a scene photo with people in it |
 | Their own **footage** for a shot (screen recording, product b-roll, an existing clip) | `upload_shot_footage` → that shot is no longer AI-generated (frames/video skipped, final cut uses the clip as-is, duration written back from the clip); **it overwrites whatever AI video that shot already had**, and afterwards every AI video call on it (including `edit_video_shot`) is refused with **409** until you `clear_shot_footage` or pass `replace_user_footage: true` | pasting an externally AI-generated clip to "fix" a shot — it carries none of this film's identity / style anchors; use `regenerate_shot_video` instead |
 | A clip that should **drive the motion** of an AI shot (a blocking/previz pass, a dance or action reference) | `edit_video_shot` with `reference_video_urls` — the shot keeps its AI video and borrows the clip's movement. To make the clip itself the source and restyle it in place, `upload_shot_footage` it first, then `edit_video_shot` with `replace_user_footage: true` | `upload_shot_footage` alone — that registers the clip as the finished shot, so nothing gets restyled and every later AI call on it returns 409 |
+| A clip whose **motion should be kept while the people / outfits are redrawn** (video repaint) — their own footage or a shot already generated here | `get_repaint_capabilities` (is it enabled for this drama; `relayMaxSegments`) → for their own clip, `upload_shot_footage` it onto a shot first → `quote_repaint_shot_video` → `repaint_shot_video` (prompt + reference image; with no `reference_image_url` the shot's character portrait is used — without any reference the person is redrawn too) **or** `quote_reskin_shot_video` → `reskin_shot_video` (`first_frame_url` = an already-reskinned first frame that matches the original first frame's composition, pose and props exactly) → `get_repaint_status` with the returned id until `completed` → `restore_repaint_original` to switch back (free). Motion, lip timing and camera move follow the source and its audio is carried over. ≤5 s is one charge (billed as 5 s); with long-shot relay enabled, 5–~14 s is split into ≤3 relayed segments, one charge each, and the quote is the total and the charge cap. A quote is tied to the shot's current video — if that video changes, generating returns 409; re-quote (free) | `edit_video_shot` to swap the whole cast or wardrobe (it edits by instruction); clips longer than ~14 s (`split_shot` first) |
 | A scene plate that came out wrong (backdrop, era, light, layout) | `get_scene_prompt` → `update_scene` (`image_prompt`) → `quote_regenerate_scene_image` (tell the customer the points — it includes the lighting reference the platform auto-derives after a plate change when no wide-shot frame exists) → `regenerate_scene_image` with that `quote_id` (after `upload_scene_image` the platform does **not** auto-create the lighting reference — if the reply says `lighting_ref.needed`, quote it with `quote_scene_lighting_ref` and, once the customer agrees, `generate_scene_lighting_ref`); already-rendered shot frames still anchor on the old plate, so regenerate those shots too | re-running `generate_scene_images` (it only fills scenes that have **no** plate — it will not touch this one) |
 | A voice sample / a required voice | `clone_voice` → `speak_with_voice` → `set_character_voice` / `assign_voices` | cloning without the rights-holder's consent |
 | No sample, but a character already speaks in a rendered shot | `set_voice_anchor_from_shot` (free; native-audio dramas: locks the voice for later videos) → regenerate `stale_shots` | picking the voice after the whole episode is rendered |
@@ -963,6 +964,65 @@ The platform's default shot breakdown still asks for one continuous action per
 shot. Apply the beat approach shot by shot on complaints; don't rewrite a whole
 episode this way unprompted.
 
+### Action / fight / skill-showcase films (动作片 / 打斗 / 技能展示)
+
+When the customer wants a short whose point is the action and the effects (little
+or no dialogue), or brings a reference action clip and asks "can we make this",
+call `get_capabilities_guide` with `section=action_film` first. The short version,
+from an internal measured run (one character, 3 shots, 18 s, `hailuo-3`):
+
+- **Assets go through the normal trunk; only the storyboard is yours.** Put a
+  one-paragraph action synopsis in `set_script`, then `rewrite_script` →
+  `review_script` → `extract_assets` (with the review token — extraction on a
+  new drama is rejected without a rewritten script). Then skip
+  `generate_storyboards` (AI breakdown splits one continuous move into
+  fragments) and write the table yourself: `get_storyboard_table_spec` →
+  `check_storyboard_table` → `import_storyboard_table`. Scene headers must use
+  the extracted scene names to bind. The import auto-completes in the
+  background: poll `get_autofill_status` until done, make your `update_shot`
+  prompt edits, and only then run `review_storyboards` for the token that
+  `generate_frames` needs (completion or edits invalidate an earlier token).
+- **One big move per 5–7 s shot**, effects in `[VFX: …]` lines.
+- **First frame = wind-up, not impact.** In the measured run the "punch shatters
+  the wall" frame was drawn at the moment of impact, so the video could only
+  play the aftermath. Set `first_frame_prompt` to the wind-up pose before
+  generating frames.
+- **Adjacent continuous-action shots are generated as one group**, and their
+  durations get re-split by content (6 s + 5 s came back as ~8 s + 3.7 s). Check
+  `get_scene_group_plan` before generating videos.
+- **Tail frames only help shots generated on their own.** Check
+  `get_scene_group_plan` first: a grouped shot's tail frame is never sent to
+  the video model (only the group head's first frame is, except Seedance 2.5
+  keyframe groups), so generating it is wasted spend. If a shot truly needs an
+  end-state anchor, give it its own `video_engine` via `update_shot` (that
+  takes it out of the group). For standalone shots: after first frames, call
+  `tail_frame_plan`; for shots with
+  `terminal_desc_missing`, write `last_frame_prompt` via `update_shot`, then
+  run `review_storyboards` **again**, then per shot `quote_shot_frame` →
+  `generate_shot_frame(frame_type=last_frame)` — the edit invalidated the old
+  token. Don't batch tails with `generate_frames`: it ignores grouping and
+  bills grouped shots' tails too. Quotes are single-use; quote scene plates
+  with `quote_scene_images` before `generate_scene_images`.
+- **Wait between async steps:** `generate_portraits_and_sheets` needs two calls
+  (portraits, poll `get_characters` until ready, then sheets); poll
+  `get_storyboards` until first frames are ready before tail frames, and until
+  tail frames land before reviewing.
+- **Before videos, run `review_frames`** once all first and tail frames have
+  settled, and pass its token to `generate_videos` (the storyboard token only
+  authorizes frame generation). The guide's `sequence` field lists the whole
+  call order with every gate.
+- **Pacing:** generated shots tend to end with 2–3 s of lingering (charging,
+  dust settling). Cut it with `trim_shot` (free). Confirm all activity stays
+  inside the window: `recommend_trim_window` for independently generated
+  shots; it returns `applicable=false` for grouped shots — sample frames every
+  0.25–0.5 s instead and pick `out_ms` by eye.
+  `speed_factor` only speeds up the **whole** shot, including the hit itself.
+  **Per-segment speed ramps inside one shot are not supported**. Offer
+  trimming, or hand off with `export_handoff_pack` for local editing.
+- Cost reference for that run: about 3,360 points total (video 1,501, images
+  ~1,050, text ~810). Text steps are billed after use and add up. Tell the
+  customer in advance.
+
 ### Writing shots yourself — one main action per shot (动作过载 / "像快进")
 
 When you write storyboards yourself (`bulk_import_storyboards`, `update_shot`,
@@ -1191,7 +1251,7 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   and all subtitle/dialogue/SFX offsets are relative to **each shot's own trimmed
   start**, not to the final timeline — add whatever overlapping transitions you like
   and let `compile_timeline.py` expand them, never hand-compute the shift.
-- **Edit**: `edit_video_shot`, `regenerate_shot_video`, `split_shot`,
+- **Edit**: `edit_video_shot`, `repaint_shot_video` / `reskin_shot_video` (keep the motion, redraw people / outfits), `regenerate_shot_video`, `split_shot`,
   `trim_shot`, `rerender_episode`. One generation per shot at a time: a **409 with
   `in_flight_generation_id`** means that shot is still generating from *different*
   input (another prompt, an edit, a prompt or shot you changed since, a first/last frame

package/dist/tools/guide-data.js

@@ -14,7 +14,7 @@
  * ★列表字段(use / tools / run / fix)里每一项以**工具名开头**,括号里写关键参数;
  *   散文字段里的工具名用反引号包住——referencedTools() 靠这两条约定抽名字。
  */
-export const GUIDE_VERSION = '2026-09-25';
+export const GUIDE_VERSION = '2026-10-13';
 /** 按客户手上的材料选入口——这是 agent 最常缺的那张表。 */
 export const ENTRY_POINTS = [
     {
@@ -164,11 +164,25 @@ export const ENTRY_POINTS = [
             'recommend_trim_window',
             'regenerate_shot_video',
             'edit_video_shot(就地编辑;get_edit_capabilities 先看当前引擎支持什么)',
+            'repaint_shot_video / reskin_shot_video(保留原片动作、整体换人换装;get_repaint_capabilities 先看本剧开没开)',
             'rerender_episode(改完后免费重拼)',
         ],
         note: '改了台词而视频已存在 → 视频仍念旧词,必须 `regenerate_shot_video`,重拼救不了。',
         flow: 'scan_dialogue_coverage / scan_intra_shot_cuts 先定病因 → update_shot / replace_shot_dialogue / repair_episode_dialogue / split_shot / trim_shot / regenerate_shot_video / edit_video_shot → rerender_episode',
     },
+    {
+        customer_has: '一段现成视频(自有素材或已出的镜头),想保留动作、把人物 / 服装整体换掉(视频转绘)',
+        use: [
+            'get_repaint_capabilities(看本剧开没开、长镜头接力最多几段)',
+            'upload_shot_footage(自有视频先登记成某镜实拍素材;已是本剧镜头则跳过)',
+            'quote_repaint_shot_video → repaint_shot_video(按描述 + 参考图重画)',
+            'quote_reskin_shot_video → reskin_shot_video(给一张换好装、与原片首帧构图对齐的首帧)',
+            'get_repaint_status(按返回 id 查到完成)',
+            'restore_repaint_original(不满意切回原片,免费)',
+        ],
+        avoid: '别拿 edit_video_shot 做整体换人换装(那是按指令局部改);超过约 14 秒先 split_shot。',
+        flow: 'get_repaint_capabilities → upload_shot_footage(自有视频) → quote_repaint_shot_video / quote_reskin_shot_video → repaint_shot_video / reskin_shot_video → get_repaint_status',
+    },
     {
         customer_has: '想自己剪:要逐镜素材包(裸片 / 对白轨 / 音效 / 配乐 / 字幕)',
         use: ['export_handoff_pack', 'get_handoff_toolchain', 'save_handoff_toolchain'],
@@ -249,7 +263,7 @@ export const PIPELINE = [
     },
     {
         step: '8 出视频',
-        tools: ['quote_videos', 'generate_videos', 'get_scene_group_plan', 'generate_scene_groups', 'quote_regenerate_shot_video', 'regenerate_shot_video', 'quote_edit_video_shot', 'edit_video_shot', 'upload_shot_footage(实拍素材镜:客户录屏/产品实拍直接当该镜视频,不出视频不扣费)', 'get_edit_capabilities'],
+        tools: ['quote_videos', 'generate_videos', 'get_scene_group_plan', 'generate_scene_groups', 'quote_regenerate_shot_video', 'regenerate_shot_video', 'quote_edit_video_shot', 'edit_video_shot', 'upload_shot_footage(实拍素材镜:客户录屏/产品实拍直接当该镜视频,不出视频不扣费)', 'get_edit_capabilities', 'get_repaint_capabilities', 'quote_repaint_shot_video', 'repaint_shot_video', 'quote_reskin_shot_video', 'reskin_shot_video', 'get_repaint_status', 'restore_repaint_original'],
         billing: '报价确认后扣点',
         note: 'video_engine 必须在出视频前定(seedance-2.5 默认 / hailuo-3 降本 / wan3.0 风格化·绝不用于写实真人);切换不回溯已生成镜头。',
     },
@@ -340,6 +354,7 @@ export const COMMON_REQUESTS = [
     { customer_says: '成片里话没说完 / 切太快', do: '先 `scan_dialogue_coverage` / `scan_intra_shot_cuts` 定病因,再按 qa_tools 的 then 修;别默认去加长镜头。' },
     { customer_says: '下载原图或视频到本地调色、用第三方 AI 后期', do: '`export_handoff_pack` purpose=local_color；只有图片传 media_type=images；按 local_postproduction.color_handoff 执行。' },
     { customer_says: '我想自己剪', do: '`export_handoff_pack` + `get_handoff_toolchain`,不走 `compose_episode`。' },
+    { customer_says: '做动作片 / 打斗 / 技能展示 / 这条参考动作片我们能不能做', do: '先 `get_capabilities_guide` section=action_film:资产照常走 `rewrite_script` → `review_script` → `extract_assets`,分镜改用自己写的表(`import_storyboard_table`)而不是 AI 拆镜,首帧停在起势,拖沓尾段用 `trim_shot` 剪;平台不支持镜内分段变速。' },
     { customer_says: '要配音 / 不要视频原声', do: '`update_project_settings` use_clip_audio=false → `assign_voices` → `generate_tts` → `compose_episode`。' },
 ];
 /**
@@ -590,6 +605,55 @@ export const MODEL_GUIDE = {
         { scenario: '打斗、流血场面多的写实剧', image_model: 'gpt-image-2.5-flare', video_engine: 'seedance-2.5', resolution: '720p', why: '图被安全拒的镜平台自动换 Nano Banana 2;视频侧把血腥措辞改成中性描述(Seedance 文本审核严)。不要为了过审换 WAN——写实人脸会被拒' },
     ],
 };
+/**
+ * 动作片 / 打斗 / 技能展示片的制作引导。
+ * 出处:2026-10-13 内部测试剧实测(单角色、3 镜 18 秒、无对白的高速动作展示,MiniMax 出视频)。
+ * 叙事剧那条路(改写 → AI 拆镜)会把动作镜拆碎;下面每一条都是那次实测踩出来的。
+ * ★只写通用方法,不写任何具体角色/招式/剧名(通用 SaaS:钉死的内容会以 few-shot 污染所有租户)。
+ */
+export const ACTION_FILM = {
+    when: '客户要做动作 / 打斗 / 技能展示 / 特效爆发类短片(无对白或极少对白,看点是动作与特效),或拿来一条参考动作片问「能不能做出来」时走这条。' +
+        '有对白、讲连贯故事的剧仍按 pipeline 正常走,只把其中的打斗镜按下面 shot_design 写。',
+    setup: [
+        '建剧:`create_drama` 一次设好——画幅照参考片(横屏动作片 16:9);art_bible / video_style_prompt 写画风与特效质感(如「2D 动画质感、速度线、动态模糊、能量辉光」);video_negative_prompt 写要压掉的(「画面静止、动作缓慢」);**完全无人声**的片才设 creative_contract speech=forbidden(防厂商自己加台词)——有哪怕一句对白/旁白就别设,否则含台词的镜被预检拦下、视频被强制静音、TTS 也被拒;无配乐需求关 bgm_enabled,无台词再关 show_subtitles。',
+        '画风:动画/风格化动作片记得 `update_project_settings` 把 style 从默认 realistic 改成**平台认识的档位键**——日式 2D 动画 anime、国漫 guoman、3D 卡通 c3d(实测 anime 出图即为 2D 动画质感)。别填「2D 动画质感」这类自由描述:认不出的值会退回 realistic,出图提示词仍带着「写实照片」与画风圣经打架。奇幻/仙侠题材先 `set_era_contract` era=fantasy(发光能量、悬浮碎石不会被判「不合时代」)。',
+        '入口:资产照常走剧本主干,**只把分镜换成自己写的表**。① `set_script` 写一段动作梗概(人物外观 + 动作经过)→ `rewrite_script` → `review_script` → `extract_assets`(带 review_token;新剧不经改写稿提取会被 400 拒,这一段不能省)——这样才有角色与场景供导入按名字绑定;② 分镜**不调 `generate_storyboards`**(AI 拆镜会把一个连贯动作拆成多个碎镜),改走 `get_storyboard_table_spec` → `check_storyboard_table`(errors 清零)→ `import_storyboard_table`,镜数、秒数、景别、运镜由你定;场景头地点名要与提取出的场景名一致才绑得上。③ 导入默认后台自动补全:`get_autofill_status` 轮询到 done → 再按 shot_design 用 `update_shot` 改首帧/尾帧提示词 → **最后**才 `review_storyboards` 拿 review_token 去出帧(补全或改镜都会让先拿的 token 失效,出帧被 400 拒;改完再审一次即可,免费)。',
+        '资产照常齐备:定妆图 + 设定图(`generate_portraits_and_sheets`)、空景基板(`quote_scene_images` → `generate_scene_images`)、`generate_color_script`。提取后先 `get_scenes` 核对:改写可能给一段**连续**动作自行编出时间推进(如同一地点拆出两个时段),这种多出来的场景用 `delete_scene` 删掉、分镜表场景头统一用留下的那个(每个场景都要单独付费出一张基板);剧情里**真有**不同时段(昼夜变化)就保留各自的场景与基板,分镜表场景头的地点和时段要与之对应,否则绑不上或套错光照。',
+    ],
+    /** 从头到尾的完整调用顺序——三道审查闸与每次改镜后的复审都在里面;各条细节见下面几段。 */
+    sequence: '★通则:下面每个 rewrite / extract / generate_* 都是**异步**的,调完立即返回;一律轮询到完成再走下一步——文本 agent 看 `get_run_status`,图看 `get_characters` / `get_storyboards`,基板看 `get_pipeline_status`,视频看 `get_storyboards` 的 video_status。' +
+        '`create_drama`(+ `update_project_settings` style / `set_era_contract`)→ `set_script`(动作梗概)→ `rewrite_script` → `get_run_status` 到结束 → `review_script` → `extract_assets`(带 token)→ `get_run_status` 到结束 → `get_scenes` 核对场景 → ' +
+        '`check_storyboard_table` → `import_storyboard_table` → `get_autofill_status` 到 done → `update_shot`(首帧起势等)→ `review_storyboards` → ' +
+        '`generate_portraits_and_sheets`(第一次只派定妆图)→ `get_characters` 轮询到定妆图 ready → 再调一次 `generate_portraits_and_sheets` 出设定图 → 轮询到 sheet ready;基板 `quote_scene_images` → `generate_scene_images`;`generate_color_script` → `quote_frames` → `generate_frames`(首帧,带分镜 token)→ `get_storyboards` 轮询到首帧全部 ready(出图是异步的)→ ' +
+        '`get_scene_group_plan` × `tail_frame_plan` 取交集(只留单独生成、又需要尾帧的镜)→ `update_shot`(last_frame_prompt)→ `review_storyboards`(复审拿新 token)→ 逐镜 `quote_shot_frame` → `generate_shot_frame`(frame_type=last_frame;别用批量 `generate_frames` 出尾帧,它不看分组,会连组内镜一起出、白扣费)→ `get_storyboards` 轮询到尾帧全部落地(还在生成时审查,拿到的 token 会在图落地后失效)→ ' +
+        '`review_frames`(★出视频前必过,拿帧层 token)→ `quote_videos` → `generate_videos`(带帧层 token)→ `get_storyboards` 轮询到全部 video_status=ready → `scan_intra_shot_cuts` → `trim_shot` 剪拖沓尾段 → `compose_episode` → `get_final_cut`。' +
+        '任何一步之后改了镜,下一个收费步之前都要把对应的 review_* 再跑一次。',
+    shot_design: [
+        '一镜一个「大招」:5~7 秒写一个主动作 + 它的特效(冲刺/出拳碎物/坠击冲击波各一镜),比一镜塞三个招式稳得多。特效约束写进分镜表的 [VFX: …] 行(一条一行),会硬注入出图。',
+        '★首帧停在**起势**,别停在**命中**瞬间:实测「出拳击碎岩壁」一镜的首帧被画成了拳已命中,视频只能从命中往后演,蓄力和出拳过程消失。出帧前用 `update_shot` 写 first_frame_prompt(「拳收在腰侧蓄力、身体前压」这类起势姿态),命中与碎裂留给视频去演。',
+        '夸张造型(能量包覆的肢体、巨大化的拳头等)只靠首帧维持不住——实测首帧画出来了,视频里退回成普通手臂缠着能量。要它贯穿全镜,首帧与尾帧都要画出该造型,并在 video_prompt 里写明全程保持。',
+        '瞬移 / 闪现类效果模型能做(实测:近景 → 能量闪光 → 人消失 → 远处出现 → 冲回近景,4 秒内循环 3~4 次),在画面叙述里写清「消失—出现—留下光迹」三段即可。',
+        '大场面(坠击、冲击波、能量柱)用远景 + 拉远:实测能量柱、强闪白、环形冲击波、碎石与镜头后撤都做出来了;人物在画面里会很小,身份一致性靠定妆图与设定图兜住。',
+    ],
+    continuity: [
+        '相邻的连续动作镜会被自动并成**一组**一次生成(场景组),组内时长会按内容重分:实测 6 秒 + 5 秒两镜生成后变成约 8 秒 + 3.7 秒。这是好事——组内动作衔接最顺——但别拿报价时的秒数去卡剪辑点;出视频前用 `get_scene_group_plan` 看分组。',
+        '★尾帧只对**单独生成**的镜有用:先看 `get_scene_group_plan`——被并进组的镜,组视频只送组首镜首帧(唯一例外是 seedance-2.5 的关键帧组),给它出的尾帧根本不会送到视频模型,出了白扣费(实测那次就有一张尾帧落在组内、没被用上)。某镜确实需要终态锚,就让它单独出:`update_shot` 给该镜设 video_engine(设了引擎的镜不进场景组,代价是失去与相邻镜一次成片的连贯),否则接受组内由模型自由衔接、不出尾帧。' +
+            '单独生成的镜:首帧出完必调 `tail_frame_plan`:冲刺类「从 A 点到 B 点」的镜会被判为状态改变、需要独立尾帧。出尾帧前先看 `get_storyboards` 的 terminal_desc_missing,为 true 的镜用 `update_shot` 写 last_frame_prompt(结束时人在哪、什么姿态、身后留下什么痕迹),否则尾帧大概率被终态闸拒且照常扣费。写完**再跑一次 `review_storyboards`**,用新 token 逐镜 `quote_shot_frame` → `generate_shot_frame`(frame_type=last_frame)出尾帧——改镜会让出首帧时那个 token 失效;批量 `generate_frames` 出尾帧不看分组,剧里有组内状态改变镜时会一并出、白扣费。报价一次只能用一次,出首帧用掉的 quote_id 不能再拿来出尾帧。首尾帧都出齐后跑 `review_frames`,用它的 token 才能 `generate_videos`(分镜层 token 只放行出帧)。',
+        '出完视频用 `scan_intra_shot_cuts` 查镜内乱切;瞬移类的闪切是有意的,别当成故障去重生。',
+    ],
+    engines: '实测样本(单次,3 镜):hailuo-3 720p,3 镜 18 秒视频 1501 点,无镜内乱切,瞬移 / 碎物 / 冲击波都做出;短板是每镜结尾有 2~3 秒「余韵」(蓄力、烟尘扩散)偏慢,夸张造型不保持。' +
+        'seedance-2.5 同题报价约为 hailuo-3 的 3 倍,动作片未单独实测;wan3.0 最省且动作措辞容易过审,但会在镜内自行换机位(叙事剧实测 11/12 镜)——动作片里这有时反而像剪辑,有时是乱切,先出 1 镜看。' +
+        '只出 1 次样本不足以下定论,给客户推荐时说明这是单次实测;要比较引擎就同镜各出一版(`quote_regenerate_shot_video` 传 model)。',
+    pacing: [
+        '动作片的命门是节奏:参考片几乎每一秒都有动作,生成镜头的结尾常拖 2~3 秒。先抽帧看清楚哪一段在拖,再处理。',
+        '★拖沓的**尾段用 `trim_shot` 剪掉**(免费,in_ms/out_ms,之后 `compose_episode` 重拼):把镜头在动作结束、余韵刚起时收住。剪之前先确认保留窗口覆盖全部动作:独立生成的镜用 `recommend_trim_window` 看片内活动点(返回 applicable=true 时);**组内镜它返回 applicable=false**,改为下载该镜视频按 0.25~0.5 秒抽帧人工看动作在哪结束再定 out_ms;终拼预检报 trim_truncation_risk 只是提醒,活动点都在窗口内就可以照拼。',
+        'speed_factor(`update_shot`,0.5~2.0,免费不重生)只能**整镜**统一变速:会把大招本身一起加快,冲击感变飘。只在整镜都偏慢时用。',
+        '★平台**不支持镜内分段变速**(同一镜里大招原速、余韵快放)。客户要那种效果:要么接受 `trim_shot` 剪掉余韵(时长相近,只是剪掉而不是快放),要么 `export_handoff_pack` 把镜头交给客户在本地剪辑软件里做分段变速。`split_shot` 不是解法——拆出来的新镜要重出视频、要花钱。',
+        '0.1~0.3 秒级的快切蒙太奇平台不会自动做,走 `export_handoff_pack` 交本地后期。',
+    ],
+    cost_reference: '同一次实测的总花费约 3360 点:视频 1501(hailuo-3,与报价一致)、图片约 1050(定妆 + 设定 + 场景基板 + 3 首帧 + 1 尾帧,落在报价区间内;其中那张尾帧所在镜被并进了组,事后看是白花的)、文本约 810(改写 + 提取 + 导入补全 + 色彩脚本,调用约 60 次)。' +
+        '文本步按 token 后付、没有报价,但在这种短片里占比不小,事先要告诉客户。',
+};
 export const HOW_TO_READ = '先按 entry_points 判客户手上的材料该走哪条通道(这是最常被跳过的一步),再按 pipeline 顺序推进、每道 review_gates 必过;' +
     '收费步按 billing.quote_flow 报价确认;遇到质量投诉按 qa_tools 的 symptom 选检测工具先定病因。';
 export function buildGuide() {
@@ -605,9 +669,10 @@ export function buildGuide() {
         common_requests: COMMON_REQUESTS,
         local_postproduction: LOCAL_POSTPRODUCTION,
         model_guide: MODEL_GUIDE,
+        action_film: ACTION_FILM,
     };
 }
-export const GUIDE_SECTIONS = ['entry_points', 'pipeline', 'review_gates', 'qa_tools', 'optional_boosts', 'billing', 'common_requests', 'local_postproduction', 'model_guide'];
+export const GUIDE_SECTIONS = ['entry_points', 'pipeline', 'review_gates', 'qa_tools', 'optional_boosts', 'billing', 'common_requests', 'local_postproduction', 'model_guide', 'action_film'];
 const head = (s) => /^[a-z][a-z0-9_]*/.exec(s.trim())?.[0] ?? null;
 const inProse = (s) => [...(s ?? '').matchAll(/`([a-z][a-z0-9_]*)`/g)].map((m) => m[1]);
 /** 引导里引用到的全部工具名(去重)——哨兵测试用:每一个都必须真的注册了。 */
@@ -654,6 +719,10 @@ export function referencedTools() {
     for (const m of [...MODEL_GUIDE.image_models, ...MODEL_GUIDE.video_engines]) {
         [...m.strengths, ...m.weaknesses, m.best_for, m.avoid_for].forEach((s) => inProse(s).forEach(add));
     }
+    // 动作片段:全是散文,工具名都用反引号包住
+    ;
+    [ACTION_FILM.when, ACTION_FILM.sequence, ...ACTION_FILM.setup, ...ACTION_FILM.shot_design, ...ACTION_FILM.continuity, ACTION_FILM.engines, ...ACTION_FILM.pacing, ACTION_FILM.cost_reference]
+        .forEach((s) => inProse(s).forEach(add));
     return [...out].sort();
 }
 /**
@@ -676,6 +745,7 @@ export function buildInstructions() {
         '长任务异步:generate_* 立即返回,用 get_pipeline_status / get_storyboards / get_run_status 轮询;图片 pending = 还在生成,别重复调(重复扣费)。',
         '改写成功后只 edit_rewritten_script 点改,别重跑 rewrite_script;角色外观唯一真相源是人物档案(update_character),别写进 visual_lock/art_bible。',
         '选图片模型/视频引擎、客户问「哪个模型好 / 怎么更省」→ get_capabilities_guide(section=model_guide):各模型实测优劣、价格、决策步骤与推荐组合;建剧时就主动讲给客户定。',
+        '做动作 / 打斗 / 技能展示片 → get_capabilities_guide(section=action_film):分镜表直通道、首帧停在起势、并组与节奏剪裁。',
         '不确定该用哪个工具、客户问「你们能做什么」→ 先调 get_capabilities_guide(免费、本地、不联网)。',
     ].join('\n');
 }

package/dist/tools/guide.js

@@ -13,7 +13,8 @@ export function registerGuideTools(server) {
         'common_requests(客户常见原话 → 该做什么)、' +
         'local_postproduction(★客户要把镜头下载到**自己电脑**上调色 / 第三方 AI 后期 / 剪辑 / 配乐 / 烧字幕 / 优化转场 / 补旁白时的完整流程:' +
         '阶段顺序、执行位置、逐镜逐句怎么核对声音、什么才算验收完成)、' +
-        'model_guide(★图片模型与视频引擎的实测优劣势、价格、选型决策步骤与推荐组合——建剧选型、客户问「哪个模型好 / 为什么手画坏了 / 怎么省钱」时先看)。传 section 只取一段。' +
+        'model_guide(★图片模型与视频引擎的实测优劣势、价格、选型决策步骤与推荐组合——建剧选型、客户问「哪个模型好 / 为什么手画坏了 / 怎么省钱」时先看)、' +
+        'action_film(★动作 / 打斗 / 技能展示片的做法:资产照走改写主干而分镜用自己写的表、首帧停在起势、相邻动作镜并组、拖沓尾段怎么剪、引擎实测与花费参考——客户要做动作片或问「这条参考片能不能做」时先看)。传 section 只取一段。' +
         '★工具描述回答"这个工具做什么",本工具回答"什么情况下该用哪个"——客户交来的是成品分镜表却被 set_script→rewrite_script 改写成散文,就是没先看这张表。', {
         section: z.enum(GUIDE_SECTIONS).optional().describe('只取某一段;不传返回全部'),
     }, async ({ section }) => {

package/dist/tools/produce.js

@@ -1256,6 +1256,63 @@ export function registerProduceTools(server, client) {
         replace_user_footage: z.boolean().optional().describe('本镜是实拍素材镜(upload_shot_footage 传过)时,显式允许以它为源做编辑并用 AI 产物覆盖它。' +
             '不传则被守卫拒(409,带中文出路)。想保留素材就别传,改用 clear_shot_footage 换回 AI 生成。'),
     }, async ({ storyboard_id, ...rest }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/edit/generate`, rest)));
+    // ========== B2 · VACE 视频重绘 / 换装重绘(保留原片动作,重画人物与服装) ==========
+    const VACE_COMMON = '\n★与 edit_video_shot 的分工:edit 是按指令改画面(换背景/调色/局部改动);重绘/换装重绘是**以本镜现有视频为动作骨架,把人物与服装整体重画**,' +
+        '动作、口型时机、镜头运动跟原片走,音轨贴回原片。' +
+        '\n★**客户自己的视频也能转绘**:先 upload_shot_footage 把它登记成某镜的实拍素材(会抽出首尾帧、回写时长),再对该镜报价/发起即可;' +
+        '转绘结果写回后该镜不再是实拍素材镜。' +
+        '\n★时长:≤5 秒一单(按 5 秒计费);本剧开了长镜头接力(get_repaint_capabilities 的 relayMaxSegments>0)时 5~约14 秒自动切 ≤3 段接力,' +
+        '每段一单、报价是合计;再长先 split_shot。' +
+        '\n★异步:发起返回一条生成记录(接力时是段 1),用 get_repaint_status(storyboard_id, generation_id) 查到 completed/failed;' +
+        '接力进行中会带 relay.segments_done/segments。完成后本镜视频即换成转绘结果;不满意用 restore_repaint_original 切回原片(免费)。';
+    server.tool('get_repaint_capabilities', '查本剧能用哪些视频转绘:repaint(视频重绘)/ reskin(换装重绘)是否开放、单段源片上限 maxSourceSec、' +
+        '长镜头接力最多段数 relayMaxSegments(0=没开,>5 秒的镜不能转绘)。免费。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/vace-capabilities`)));
+    server.tool('quote_repaint_shot_video', '报价:对某镜做**视频重绘**(按描述 + 参考图重画人物与服装,保留原片动作)要多少点。返回 quote_id。零扣费。本镜须已有视频。' +
+        '报价只认本镜当前这段视频——之后视频被换(重生/上传/编辑完成),发起会 409,重新报价即可。' + VACE_COMMON, { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/repaint/quote`)));
+    server.tool('repaint_shot_video', '确认后对某镜做视频重绘。扣费上限 = 报价的 estimated_points(接力时为整条合计)。' +
+        '\n★参考图:不传 reference_image_url 时自动取本镜角色的(换装)定妆图——**不带参考图人也会被换掉**;' +
+        'auto_reference=false 表示明确不要参考图(只按描述画)。' +
+        '\n★keep_scene 缺省 true:把本镜场景/道具/动作补进描述,只换人与衣服;传 false = 连场景一起重画。' +
+        '\n★control:posebodyface(缺省,保口型,说话镜用它)/ posebody(不带脸,嘴不动)/ depth(按景深,纯色背景易出竖条纹)/ scribble(线稿)。' +
+        'strength 只收 0 或 1。' +
+        '\n★本镜绑了产品文字(需保留商品原文)时会被拒(重绘会重画画面里的字)。' + VACE_COMMON + CONFIRM_HINT, {
+        storyboard_id: z.number().int().positive(),
+        quote_id: z.string().describe('来自 quote_repaint_shot_video'),
+        prompt: z.string().describe('要画成什么样(人物外貌、服装、风格)。正向描述,别写「不要 X」'),
+        control: z.enum(['posebodyface', 'posebody', 'depth', 'scribble']).optional().describe('动作控制方式,缺省 posebodyface'),
+        strength: z.union([z.literal(0), z.literal(1)]).optional().describe('0 或 1,缺省 1'),
+        reference_image_url: z.string().optional().describe('主体参考图 URL(先 upload_image 拿);缺省自动取本镜角色定妆图'),
+        auto_reference: z.boolean().optional().describe('false = 明确不带参考图(人会按描述重画)'),
+        keep_scene: z.boolean().optional().describe('缺省 true:保留原片场景与道具,只换人和衣服'),
+    }, async ({ storyboard_id, ...rest }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/repaint/generate`, rest)));
+    server.tool('quote_reskin_shot_video', '报价:对某镜做**换装重绘**(给一张已换好装的首帧,按原片动作把整段视频续成这身打扮)要多少点。返回 quote_id。零扣费。' +
+        '本镜须已有视频;该功能按剧开放,先看 get_repaint_capabilities 的 reskin。' + VACE_COMMON, { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/reskin/quote`)));
+    server.tool('reskin_shot_video', '确认后对某镜做换装重绘。扣费上限 = 报价的 estimated_points。' +
+        '\n★first_frame_url 是**换好装的首帧**:必须与原片首帧**构图、人物姿势、道具位置逐一对齐**(只换衣服),' +
+        '否则整段会跑偏——实测失败都出在首帧。完成后它会成为本镜正式首帧。只收公网 https 图片(先 upload_image 拿)。' +
+        '\n★prompt 可留空(系统看首帧自动写);写的话别用「制服/军装」这类服装类别词,模型会自行加肩章条纹,直接描述颜色款式。' +
+        '\n★control:posebodyface(缺省,保口型)/ depth。本镜绑了产品文字时会被拒。' + VACE_COMMON + CONFIRM_HINT, {
+        storyboard_id: z.number().int().positive(),
+        quote_id: z.string().describe('来自 quote_reskin_shot_video'),
+        first_frame_url: z.string().describe('换好装的首帧 https URL,须与原片首帧构图对齐'),
+        prompt: z.string().optional().describe('可留空:系统看首帧自动写'),
+        control: z.enum(['posebodyface', 'depth']).optional().describe('缺省 posebodyface'),
+    }, async ({ storyboard_id, ...rest }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/reskin/generate`, rest)));
+    server.tool('get_repaint_status', '查一次视频重绘/换装重绘的进度。generation_id 用发起时返回的 id(接力时就是段 1 的 id,返回的是整条链的状态)。免费。' +
+        '\n· status=processing:进行中;接力时带 relay.segments_done/segments。' +
+        '\n· status=completed:本镜视频已换成转绘结果(video_url / local_path);接力完成时带 relay.final_generation_id——' +
+        '**切回原片要用这个 final_generation_id**,不是段 1 的 id。' +
+        '\n· status=completed 但 errorMsg 含「未写回」:任务期间本镜视频被换掉,结果存档在这条记录里、没覆盖本镜。' +
+        '\n· status=failed:errorMsg 是中文原因(接力会说明第几段失败),镜头未改动,已扣的按规则退。', {
+        storyboard_id: z.number().int().positive(),
+        generation_id: z.number().int().positive().describe('repaint_shot_video / reskin_shot_video 返回的 id'),
+    }, async ({ storyboard_id, generation_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/vace/${generation_id}`)));
+    server.tool('restore_repaint_original', '把某镜从转绘结果切回转绘前的原片(换装重绘连首帧一起恢复)。免费。' +
+        'generation_id = 本镜当前视频对应的那次转绘(接力取 get_repaint_status 的 relay.final_generation_id)。' +
+        '\n★409 = 之后本镜又出过别的视频,不覆盖(保护后来的结果);有视频任务在跑时也别切回,在跑那单会因源片不符被存档(白花钱)。', {
+        storyboard_id: z.number().int().positive(),
+        generation_id: z.number().int().positive(),
+    }, async ({ storyboard_id, generation_id }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/vace-restore`, { generation_id })));
     server.tool('quote_regenerate_shot_video', '报价:重生某镜视频要多少点。返回 quote_id。零扣费。' +
         '\n★**按镜指定视频引擎**:传 model 即只为这一镜这一次重生换引擎(不改剧级 video_engine,其它镜照旧);' +
         '报价按该引擎计价,quote_id 把引擎钉死,regenerate_shot_video 派发的就是它——要换引擎必须重新报价,生成时再传引擎无效。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.137",
-    "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.137 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.139",
+    "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.139 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -3236,6 +3236,53 @@
         }
       }
     },
+    "/dramas/{drama_id}/vace-capabilities": {
+      "get": {
+        "operationId": "get_repaint_capabilities",
+        "summary": "查本剧能用哪些视频转绘:repaint(视频重绘)/ reskin(换装重绘)是否开放、单段源片上限 maxSourceSec、长镜头接力最多段数 relayMaxSegments(0=没开,>5 秒的镜不能转绘)",
+        "description": "查本剧能用哪些视频转绘:repaint(视频重绘)/ reskin(换装重绘)是否开放、单段源片上限 maxSourceSec、长镜头接力最多段数 relayMaxSegments(0=没开,>5 秒的镜不能转绘)。免费。",
+        "tags": [
+          "dramas"
+        ],
+        "parameters": [
+          {
+            "name": "drama_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/{drama_id}/video-style": {
       "post": {
         "operationId": "generate_video_style",
@@ -12427,6 +12474,277 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/repaint/generate": {
+      "post": {
+        "operationId": "repaint_shot_video",
+        "summary": "确认后对某镜做视频重绘",
+        "description": "确认后对某镜做视频重绘。扣费上限 = 报价的 estimated_points(接力时为整条合计)。\n★参考图:不传 reference_image_url 时自动取本镜角色的(换装)定妆图——**不带参考图人也会被换掉**;auto_reference=false 表示明确不要参考图(只按描述画)。\n★keep_scene 缺省 true:把本镜场景/道具/动作补进描述,只换人与衣服;传 false = 连场景一起重画。\n★control:posebodyface(缺省,保口型,说话镜用它)/ posebody(不带脸,嘴不动)/ depth(按景深,纯色背景易出竖条纹)/ scribble(线稿)。strength 只收 0 或 1。\n★本镜绑了产品文字(需保留商品原文)时会被拒(重绘会重画画面里的字)。\n★与 edit_video_shot 的分工:edit 是按指令改画面(换背景/调色/局部改动);重绘/换装重绘是**以本镜现有视频为动作骨架,把人物与服装整体重画**,动作、口型时机、镜头运动跟原片走,音轨贴回原片。\n★**客户自己的视频也能转绘**:先 upload_shot_footage 把它登记成某镜的实拍素材(会抽出首尾帧、回写时长),再对该镜报价/发起即可;转绘结果写回后该镜不再是实拍素材镜。\n★时长:≤5 秒一单(按 5 秒计费);本剧开了长镜头接力(get_repaint_capabilities 的 relayMaxSegments>0)时 5~约14 秒自动切 ≤3 段接力,每段一单、报价是合计;再长先 split_shot。\n★异步:发起返回一条生成记录(接力时是段 1),用 get_repaint_status(storyboard_id, generation_id) 查到 completed/failed;接力进行中会带 relay.segments_done/segments。完成后本镜视频即换成转绘结果;不满意用 restore_repaint_original 切回原片(免费)。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "quote_id": {
+                    "type": "string",
+                    "description": "来自 quote_repaint_shot_video"
+                  },
+                  "prompt": {
+                    "type": "string",
+                    "description": "要画成什么样(人物外貌、服装、风格)。正向描述,别写「不要 X」"
+                  },
+                  "control": {
+                    "type": "string",
+                    "enum": [
+                      "posebodyface",
+                      "posebody",
+                      "depth",
+                      "scribble"
+                    ]
+                  },
+                  "strength": {
+                    "type": "number",
+                    "enum": [
+                      0,
+                      1
+                    ]
+                  },
+                  "reference_image_url": {
+                    "type": "string"
+                  },
+                  "auto_reference": {
+                    "type": "boolean"
+                  },
+                  "keep_scene": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "quote_id",
+                  "prompt"
+                ]
+              }
+            }
+          }
+        },
+        "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}/repaint/quote": {
+      "post": {
+        "operationId": "quote_repaint_shot_video",
+        "summary": "报价:对某镜做**视频重绘**(按描述 + 参考图重画人物与服装,保留原片动作)要多少点",
+        "description": "报价:对某镜做**视频重绘**(按描述 + 参考图重画人物与服装,保留原片动作)要多少点。返回 quote_id。零扣费。本镜须已有视频。报价只认本镜当前这段视频——之后视频被换(重生/上传/编辑完成),发起会 409,重新报价即可。\n★与 edit_video_shot 的分工:edit 是按指令改画面(换背景/调色/局部改动);重绘/换装重绘是**以本镜现有视频为动作骨架,把人物与服装整体重画**,动作、口型时机、镜头运动跟原片走,音轨贴回原片。\n★**客户自己的视频也能转绘**:先 upload_shot_footage 把它登记成某镜的实拍素材(会抽出首尾帧、回写时长),再对该镜报价/发起即可;转绘结果写回后该镜不再是实拍素材镜。\n★时长:≤5 秒一单(按 5 秒计费);本剧开了长镜头接力(get_repaint_capabilities 的 relayMaxSegments>0)时 5~约14 秒自动切 ≤3 段接力,每段一单、报价是合计;再长先 split_shot。\n★异步:发起返回一条生成记录(接力时是段 1),用 get_repaint_status(storyboard_id, generation_id) 查到 completed/failed;接力进行中会带 relay.segments_done/segments。完成后本镜视频即换成转绘结果;不满意用 restore_repaint_original 切回原片(免费)。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_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"
+          }
+        }
+      }
+    },
+    "/storyboards/{storyboard_id}/reskin/generate": {
+      "post": {
+        "operationId": "reskin_shot_video",
+        "summary": "确认后对某镜做换装重绘",
+        "description": "确认后对某镜做换装重绘。扣费上限 = 报价的 estimated_points。\n★first_frame_url 是**换好装的首帧**:必须与原片首帧**构图、人物姿势、道具位置逐一对齐**(只换衣服),否则整段会跑偏——实测失败都出在首帧。完成后它会成为本镜正式首帧。只收公网 https 图片(先 upload_image 拿)。\n★prompt 可留空(系统看首帧自动写);写的话别用「制服/军装」这类服装类别词,模型会自行加肩章条纹,直接描述颜色款式。\n★control:posebodyface(缺省,保口型)/ depth。本镜绑了产品文字时会被拒。\n★与 edit_video_shot 的分工:edit 是按指令改画面(换背景/调色/局部改动);重绘/换装重绘是**以本镜现有视频为动作骨架,把人物与服装整体重画**,动作、口型时机、镜头运动跟原片走,音轨贴回原片。\n★**客户自己的视频也能转绘**:先 upload_shot_footage 把它登记成某镜的实拍素材(会抽出首尾帧、回写时长),再对该镜报价/发起即可;转绘结果写回后该镜不再是实拍素材镜。\n★时长:≤5 秒一单(按 5 秒计费);本剧开了长镜头接力(get_repaint_capabilities 的 relayMaxSegments>0)时 5~约14 秒自动切 ≤3 段接力,每段一单、报价是合计;再长先 split_shot。\n★异步:发起返回一条生成记录(接力时是段 1),用 get_repaint_status(storyboard_id, generation_id) 查到 completed/failed;接力进行中会带 relay.segments_done/segments。完成后本镜视频即换成转绘结果;不满意用 restore_repaint_original 切回原片(免费)。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "quote_id": {
+                    "type": "string",
+                    "description": "来自 quote_reskin_shot_video"
+                  },
+                  "first_frame_url": {
+                    "type": "string",
+                    "description": "换好装的首帧 https URL,须与原片首帧构图对齐"
+                  },
+                  "prompt": {
+                    "type": "string"
+                  },
+                  "control": {
+                    "type": "string",
+                    "enum": [
+                      "posebodyface",
+                      "depth"
+                    ]
+                  }
+                },
+                "required": [
+                  "quote_id",
+                  "first_frame_url"
+                ]
+              }
+            }
+          }
+        },
+        "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}/reskin/quote": {
+      "post": {
+        "operationId": "quote_reskin_shot_video",
+        "summary": "报价:对某镜做**换装重绘**(给一张已换好装的首帧,按原片动作把整段视频续成这身打扮)要多少点",
+        "description": "报价:对某镜做**换装重绘**(给一张已换好装的首帧,按原片动作把整段视频续成这身打扮)要多少点。返回 quote_id。零扣费。本镜须已有视频;该功能按剧开放,先看 get_repaint_capabilities 的 reskin。\n★与 edit_video_shot 的分工:edit 是按指令改画面(换背景/调色/局部改动);重绘/换装重绘是**以本镜现有视频为动作骨架,把人物与服装整体重画**,动作、口型时机、镜头运动跟原片走,音轨贴回原片。\n★**客户自己的视频也能转绘**:先 upload_shot_footage 把它登记成某镜的实拍素材(会抽出首尾帧、回写时长),再对该镜报价/发起即可;转绘结果写回后该镜不再是实拍素材镜。\n★时长:≤5 秒一单(按 5 秒计费);本剧开了长镜头接力(get_repaint_capabilities 的 relayMaxSegments>0)时 5~约14 秒自动切 ≤3 段接力,每段一单、报价是合计;再长先 split_shot。\n★异步:发起返回一条生成记录(接力时是段 1),用 get_repaint_status(storyboard_id, generation_id) 查到 completed/failed;接力进行中会带 relay.segments_done/segments。完成后本镜视频即换成转绘结果;不满意用 restore_repaint_original 切回原片(免费)。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_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"
+          }
+        }
+      }
+    },
     "/storyboards/{storyboard_id}/split": {
       "post": {
         "operationId": "split_shot",
@@ -12588,6 +12906,129 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/vace-restore": {
+      "post": {
+        "operationId": "restore_repaint_original",
+        "summary": "把某镜从转绘结果切回转绘前的原片(换装重绘连首帧一起恢复)",
+        "description": "把某镜从转绘结果切回转绘前的原片(换装重绘连首帧一起恢复)。免费。generation_id = 本镜当前视频对应的那次转绘(接力取 get_repaint_status 的 relay.final_generation_id)。\n★409 = 之后本镜又出过别的视频,不覆盖(保护后来的结果);有视频任务在跑时也别切回,在跑那单会因源片不符被存档(白花钱)。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "generation_id": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0
+                  }
+                },
+                "required": [
+                  "generation_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"
+          }
+        }
+      }
+    },
+    "/storyboards/{storyboard_id}/vace/{generation_id}": {
+      "get": {
+        "operationId": "get_repaint_status",
+        "summary": "查一次视频重绘/换装重绘的进度",
+        "description": "查一次视频重绘/换装重绘的进度。generation_id 用发起时返回的 id(接力时就是段 1 的 id,返回的是整条链的状态)。免费。\n· status=processing:进行中;接力时带 relay.segments_done/segments。\n· status=completed:本镜视频已换成转绘结果(video_url / local_path);接力完成时带 relay.final_generation_id——**切回原片要用这个 final_generation_id**,不是段 1 的 id。\n· status=completed 但 errorMsg 含「未写回」:任务期间本镜视频被换掉,结果存档在这条记录里、没覆盖本镜。\n· status=failed:errorMsg 是中文原因(接力会说明第几段失败),镜头未改动,已扣的按规则退。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          },
+          {
+            "name": "generation_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "repaint_shot_video / reskin_shot_video 返回的 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"
+          }
+        }
+      }
+    },
     "/videos/edit-capabilities": {
       "get": {
         "operationId": "get_edit_capabilities",

package/package.json

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