@starreel/mcp 0.1.88 → 0.1.89

package/SKILL.md

@@ -87,7 +87,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) |
 | 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` | re-composing to fix what a clip *says* |
-| Wants to assemble the cut themselves | `export_handoff_pack` → `get_handoff_toolchain` | `compose_episode` (pick one) |
+| Wants to assemble the cut themselves | `export_handoff_pack` → `get_handoff_toolchain` → **`register_external_delivery`** when the cut is final | `compose_episode` (pick one); delivering a cut the platform has no record of |
 | A multi-language release | `translate_subtitles` · `subtitle_secondary_lang` in project settings | — |
 
 ### Customer-supplied images
@@ -325,6 +325,19 @@ content that will be rejected.
    seedance stays 720p (HD tiers off sale), hailuo-3 → 1080p (= 2K, 112 pts/s),
    WAN → 1080p (168 pts/s). hailuo-3 has no separate 480p tier (a 480p request
    still bills at 768P).
+   **Model strengths & weaknesses — ask `get_capabilities_guide` with
+   `section=model_guide`** before proposing a model: it carries measured data
+   per image model and video engine, a step-by-step choice list and ready-made
+   combos. The short version for images: `gpt-image-2.5-flare` has by far the
+   best first-try rate (60% vs 5% for Nano Banana 2 in the same period) and much
+   better hands / hand-held objects, so despite the higher unit price it costs
+   roughly 1/3 as much per *usable* image; its weak spots are a ~3× higher vendor
+   safety-refusal rate on violent scenes (the platform auto-retries once on
+   `gemini-3.1-flash-image`) and occasional drift toward an anime look on
+   photoreal dramas — redraw those single shots on `gemini-3.1-flash-image`.
+   Use `gpt-image-2.5-sunburst` for shots with readable Chinese text, the 31-pt
+   models (Lite / Seedream 5.0) only for drafts, and Nano Banana Pro for a few
+   key images. Compare models by cost per usable image, never by unit price.
    **Set the drama engine before generating any video**:
    switching never re-renders existing shots, and mixing engines inside one
    drama risks style/identity drift.
@@ -630,6 +643,22 @@ The table above is for **generation failures**. A different class of report is
 "the video generated fine, but the cut is wrong." These never surface as a
 `fail_reason` — nothing failed. Diagnose by symptom:
 
+### "成片里有两层字幕" / extra text burned into the picture
+
+On native-audio projects (the clip carries the voices) the video vendor sometimes
+ignores the "no subtitles" constraint and burns the spoken line into the picture —
+small, usually in the lower half, and **only for the second or two while that line
+is spoken**, so spot-checking a frame or two easily misses it. The platform then
+renders its own subtitles on top, and the viewer sees the line twice.
+
+Run **`scan_burned_subtitles`** before the final compose (or as soon as someone
+reports doubled text). It samples 12 frames per shot and makes one small vision
+call per shot (billed by usage). `matches_dialogue: true` means the text it read
+*is* that shot's line — treat that as confirmed. Text that physically exists in
+the scene (signs, book pages, screens) is not reported. Re-composing cannot remove
+burned-in text; `regenerate_shot_video` the flagged shots. After a non-dry-run scan,
+`compose_episode` lists them as advisory `vendor_burned_text`.
+
 ### "话没说完就切" / a line gets cut off mid-word
 
 **By far the most common cause is #2 — the vendor's clip never said the whole
@@ -855,6 +884,15 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   `get_bgm_prompt_guide`, `replace_shot_dialogue`
 - **Finish**: `compose_episode`, `get_final_cut`, `get_export`,
   `generate_episode_poster`, `generate_cover`
+- **Delivered a cut you finished outside the platform** (re-voiced lines, trims,
+  an ending card, music): `register_external_delivery` the exact file you hand to
+  the customer — **every time**, including revisions. Otherwise the platform's
+  records describe a cut the customer never received, and nobody can later tell
+  which version shipped or which generation each shot came from. The platform
+  re-hashes the file itself and snapshots every shot's source clip; put what you
+  changed outside in `manifest`. `get_final_cut` then returns it as `delivery`
+  next to the platform's own `download_url`; `list_deliveries` /
+  `set_current_delivery` manage versions.
 - **Assemble it yourself**: `export_handoff_pack`, `get_handoff_toolchain` —
   download the per-shot raw clips, dialogue tracks, SFX, BGM and subtitles, then
   decide transitions and assemble the cut on your own side. Use this instead of

package/dist/tools/guide-data.js

@@ -14,7 +14,7 @@
  * ★列表字段(use / tools / run / fix)里每一项以**工具名开头**,括号里写关键参数;
  *   散文字段里的工具名用反引号包住——referencedTools() 靠这两条约定抽名字。
  */
-export const GUIDE_VERSION = '2026-09-02';
+export const GUIDE_VERSION = '2026-09-25';
 /** 按客户手上的材料选入口——这是 agent 最常缺的那张表。 */
 export const ENTRY_POINTS = [
     {
@@ -378,6 +378,174 @@ export const LOCAL_POSTPRODUCTION = {
             '平台侧成片用 `get_final_cut` 取。',
     ],
 };
+/**
+ * v0.9.2018 — 模型选型指南。工具参数描述只列「型号 + 价格」,这里回答「哪个好、好在哪、坑在哪、该怎么配」。
+ * ★数字全部来自平台生产实测(带样本量),样本不足的维度如实写「未系统实测」,别替它补结论。
+ * ★型号集合与工具参数可选值由 test/mcp-model-guide.test.ts 双向钉住——新增/下架型号两处一起改。
+ */
+export const MODEL_GUIDE = {
+    principle: '模型是 drama 级设置(create_drama / update_project_settings 的 image_model、video_engine),整剧统一画风与身份;' +
+        '单镜可临时覆盖(图:`generate_shot_frame` 传 image_model,且须与 `quote_shot_frame` 传的同一个;视频编辑:`edit_video_shot` 传 model)。' +
+        '选型要主动讲给客户:把价差与优劣摆出来,让客户定,别默默用默认值。' +
+        '比较模型「贵不贵」要按**每张可用图/每条可用镜头**算,不是按单张单价——重抽次数差几倍时,单价低的反而更贵。',
+    image_models: [
+        {
+            id: 'gpt-image-2.5-flare', name: 'ChatGPT Image 2.5 Flare', is_default: true,
+            price: '基础 11 点 + 每张参考图 18 点(按实际送出的参考图计;常见 4~6 张 ≈ 80~120 点/张);报价是区间,按 estimated_points 备余额',
+            strengths: [
+                '一次过率最高:同期实测 60.1%(223 个镜位),中位 1 张就出可用图;Nano Banana 2 同口径 4.9%',
+                '手部、手持器物、接触关系结构明显更稳(同镜同参考图配对比较,6 对里 4 对明显胜出)',
+                '参考图最多 16 张:多人同框时每个角色的身份锚都送得到',
+                '竖屏出图 1088×1920,最贴近 9:16',
+                '算上重抽,每张可用图的实际花费约为 Nano Banana 2 的 1/3~1/4',
+            ],
+            weaknesses: [
+                '厂商安全拒绝率最高:约 2.61%(Nano Banana 2 约 0.83%),打斗/流血/武器场景更容易触发;平台会自动换 gemini-3.1-flash-image 重出一次',
+                '写实电影感剧偶发画风漂成日式动漫 CG(配对样本 6 对里 1 对)',
+                '单价随参考图张数浮动,报价只能给区间',
+            ],
+            best_for: '绝大多数剧的默认选择;近景/特写、手部动作、手持道具、多人同框镜尤其该用它',
+            avoid_for: '暴力场面密集且反复被安全拒的镜(那几镜单独换 gemini-3.1-flash-image)',
+        },
+        {
+            id: 'gpt-image-2.5-sunburst', name: 'ChatGPT Image 2.5 Sunburst',
+            price: '与 flare 同价(11 + 18/参考图)',
+            strengths: ['编辑精度优先,中文字形与细部更准', '其余能力同 flare(16 张参考图、1088×1920)'],
+            weaknesses: ['比 flare 慢约 5 秒/张', '平台内样本少,一次过率未单独实测;安全拒绝特性按同厂商同代推定与 flare 相近'],
+            best_for: '画面里要出现可读中文(招牌、字卡、屏幕、文件、海报)或细部特写要求高的镜',
+            avoid_for: '没有文字需求的整集批量——多等时间、无额外收益',
+        },
+        {
+            id: 'gemini-3.1-flash-image', name: 'Nano Banana 2',
+            price: '一口价:镜头帧 71 点/张(1K);定妆照、设定图等身份锚 119 点/张(2K);参考图不另收(最多 14 张)',
+            strengths: [
+                '画风锚定稳:写实电影感剧不容易漂成动漫风',
+                '安全拒绝率低(约 0.83%),GPT 2.5 被拒的镜换它通常能过',
+                '固定价,预算好算',
+            ],
+            weaknesses: [
+                '一次过率低:实测 4.9%(123 个镜位),中位要烧 6 张才出一张可用图——单价便宜但总花费反而高',
+                '手指、手持器物容易融合或崩坏,且平台的解剖审计对手部覆盖不足,坏手可能被放行,要人工看',
+                '≤720p 剧的镜头帧按 1K 档出(768×1376),细节上限低于 GPT 2.5',
+            ],
+            best_for: '群像/远景/氛围镜、需要稳住写实画风的镜;GPT 2.5 被安全拒的镜的替补',
+            avoid_for: '手部特写、手持道具、器物密集(托盘、线缆、算盘、卷轴一类)的近景',
+        },
+        {
+            id: 'gemini-3-pro-image', name: 'Nano Banana Pro',
+            price: '175 点/张一口价(2K)',
+            strengths: ['画面最精细', '安全拒绝实测 0 次(145 张)', '早期同口径成功率 88.2%,每镜位平均 2.4 张候选'],
+            weaknesses: ['最贵,是 flare 常见单价的约 1.5~2 倍', '样本量小(34 个镜位),与 GPT 2.5 的一次过率未做同窗口对比'],
+            best_for: '封面、海报、定妆锚这类少量关键图',
+            avoid_for: '整集批量出镜头帧',
+        },
+        {
+            id: 'gemini-3.1-flash-lite-image', name: 'Nano Banana 2 Lite',
+            price: '31 点/张(经济档,厂商恒 1K)',
+            strengths: ['最便宜档之一', '出图快,适合快速看构图'],
+            weaknesses: ['分辨率固定 1K,细节上限最低', '平台内未系统实测质量,不建议作交付帧'],
+            best_for: '草稿、试风格、分镜预览',
+            avoid_for: '交付用的镜头帧与定妆锚——交付前切回 flare',
+        },
+        {
+            id: 'doubao-seedream-5-0-260128', name: 'Seedream 5.0',
+            price: '31 点/张(经济档)',
+            strengths: ['经济档价格', '出图像素高(厂商最低约 1920×1920 级)', '安全拒绝实测 0 次(170 张)', '参考图最多 10 张'],
+            weaknesses: ['平台内样本少,一次过率与手部结构未系统实测', '与 GPT 2.5 / Nano Banana 画风差异明显,整剧中途换它会跳风格'],
+            best_for: '预算敏感、想低价试另一种画风的项目(从第一张图就用它,别中途换)',
+            avoid_for: '已经用别的模型出过大半集的剧',
+        },
+    ],
+    image_decision: [
+        '① 默认 gpt-image-2.5-flare,建剧时就定,整集统一。中途换模型会让同一集里出现两种画风和两种画幅。',
+        '② 画面里要出现可读中文(招牌/字卡/屏幕/海报)→ 这些镜用 gpt-image-2.5-sunburst。',
+        '③ 某镜反复被安全拒(打斗、流血、武器)→ 平台已自动换 Nano Banana 2 重出一次;仍不行就对那一镜 `quote_shot_frame` → `generate_shot_frame` 显式传 image_model=gemini-3.1-flash-image(两次必须同值,否则 400 IMAGE_MODEL_MISMATCH),同时把措辞中性化。',
+        '④ 写实电影感剧里某镜画风漂成动漫 → 这一镜换 gemini-3.1-flash-image 重画。',
+        '⑤ 手部/持物/多人同框镜出现坏手、手物融合 → 用(或换回) gpt-image-2.5-flare 重画;Nano Banana 系列在这类镜上明显更差。',
+        '⑥ 只是试风格、看构图 → gemini-3.1-flash-lite-image 或 Seedream 5.0(31 点),交付前切回主模型重出。',
+        '⑦ 封面/海报/定妆锚要最精细 → gemini-3-pro-image(175 点),只用在少量关键图上。',
+    ],
+    video_engines: [
+        {
+            id: 'seedance-2.5', name: 'Seedance 2.5', is_default: true,
+            price: '720p 约 212 点/秒(在售 480p/720p,高清档停售);单镜 2~30 秒',
+            strengths: [
+                '指令遵循与人脸细节最强,写实真人剧首选',
+                '能力最全:首尾帧链、场景组、关键帧组(组内每镜都送自己的首帧,只有它支持)、就地编辑含时间区间、延长、参考图锚',
+                '镜内自行跳切少(实测 1/6 镜),单镜叙事稳',
+                '台词念不全的比例最低:23%(294 镜)',
+            ],
+            weaknesses: [
+                '最贵:约为 hailuo-3 的 3 倍、wan3.0 的 2.5 倍',
+                '文本审核最严:打斗、流血一类措辞容易直接被拒,要中性化描述',
+                '写实角色要做一次虚拟人像核验(每个人物锁 200 点,只有本引擎收)',
+            ],
+            best_for: '写实真人剧、对白多的剧、要逐镜精确控制画面的剧',
+        },
+        {
+            id: 'hailuo-3', name: 'MiniMax H3',
+            price: '720p(=768P)70 点/秒、1080p(=2K)112 点/秒;无独立 480p 档(选了也按 768P 计);单镜 4~15 秒',
+            strengths: [
+                '约 1/3 成本,还能出 2K',
+                '就地编辑保真度高(改色调/改局部时人物服装构图保持得最好),可在 Seedance 剧里单镜借用它做编辑',
+                '镜内自行跳切最少(实测 0/5 镜)',
+                '原生对白与音效',
+            ],
+            weaknesses: [
+                '慢:单镜约 6 分钟',
+                '台词念不全的比例高:50%(26 镜),对白密集剧慎用',
+                '不支持关键帧组与时间区间编辑',
+                '提示词上限 7000 字符,平台会自动剥掉软性描述块,极长的镜头描述会丢细节',
+            ],
+            best_for: '写实真人剧但预算紧、对白不密集;单镜编辑(配合 `edit_video_shot` 的 model 参数)',
+            avoid_for: '对白密集、赶交付时间的项目',
+        },
+        {
+            id: 'wan3.0', name: 'WAN 3.0',
+            price: '480p 42 / 720p 84 / 1080p 168 点/秒;单镜 2~30 秒(2 秒起计费,无 4 秒地板)',
+            strengths: [
+                '约 4 折成本,2~3 秒短镜更省',
+                '快:单镜约 2 分钟,并发好',
+                '文本审核宽松,动作/打斗措辞基本能过',
+                '有首尾帧双锚或参考图时,风格化角色的风格、服装、道具都跟得住',
+            ],
+            weaknesses: [
+                '输出侧真人脸审核:写实人脸在 720p 及以上一致被拒,重试救不回',
+                '会在单个镜头内自行换机位硬切(实测 11/12 镜),叙事镜观感是「画面跳来跳去」,提示词拦不住',
+                '只有单张首帧时,强场景描述会把风格化角色拉向写实(漂移)',
+                '道具形状锁不住;台词完整度样本不足未测',
+            ],
+            best_for: '动画/3D 卡通/风格化剧、空镜、产品镜、短平快的剪辑节奏',
+            avoid_for: '写实真人剧(绝不选);对白多、要单镜稳定叙事的剧',
+        },
+        {
+            id: 'wan3.0-prime', name: 'WAN 3.0 Prime(高速版)',
+            price: '480p 63 / 720p 126 / 1080p 252 点/秒(wan3.0 的 1.5 倍)',
+            strengths: ['能力同 wan3.0,出片快约一倍(单镜约 1 分钟)'],
+            weaknesses: ['同 wan3.0:写实人脸 720p+ 被拒、镜内自剪', '价格是 wan3.0 的 1.5 倍'],
+            best_for: '风格化项目赶交付',
+            avoid_for: '同 wan3.0;不赶时间就用 wan3.0',
+        },
+    ],
+    video_decision: [
+        '① 先定「是不是写实真人」:是 → seedance-2.5(默认)或降本 hailuo-3;绝不选 wan3.0 / wan3.0-prime。',
+        '② 写实真人 + 对白密集 → seedance-2.5(台词念不全 23% vs hailuo-3 50%)。',
+        '③ 风格化/动画/3D/空镜/产品镜 → wan3.0,赶交付用 wan3.0-prime;但讲连贯故事、要单镜稳定的叙事剧仍优先 seedance-2.5(WAN 镜内自剪 11/12)。',
+        '④ 想让每一镜的首帧都进组视频(关键帧组)→ 只有 seedance-2.5 支持;其他引擎的场景组只送组首镜首帧。',
+        '⑤ 出视频前就把引擎定好:切换不会重做已生成的镜头,同一剧混用引擎会有风格/身份跳变。',
+        '⑥ 分辨率:草稿迭代用低档(WAN 剧 480p,其余 720p);交付 seedance-2.5 维持 720p、hailuo-3 用 1080p(=2K)、WAN 用 1080p。',
+        '⑦ 单镜保持 3~5 秒:镜头越长模型自由发挥越多,所有引擎通用,WAN 上最明显。生成后可用 `scan_intra_shot_cuts` 查镜内跳切。',
+        '⑧ 只想改一镜的色调/局部 → `edit_video_shot` 可以单独选 model=hailuo-3(保真、便宜),不用改剧引擎;但它不支持 start_sec/end_sec 区间。',
+    ],
+    combos: [
+        { scenario: '写实真人短剧(标准配置)', image_model: 'gpt-image-2.5-flare', video_engine: 'seedance-2.5', resolution: '720p', why: '出图一次过率最高 + 视频人脸与指令遵循最强,返工最少' },
+        { scenario: '写实真人短剧 · 预算紧、对白不多', image_model: 'gpt-image-2.5-flare', video_engine: 'hailuo-3', resolution: '草稿 720p / 交付 1080p', why: '视频成本约 1/3;对白多就回到 seedance-2.5' },
+        { scenario: '动画 / 3D 卡通 / 风格化剧', image_model: 'gpt-image-2.5-flare', video_engine: 'wan3.0', resolution: '草稿 480p / 交付 1080p', why: '视频约 4 折且快;记得出尾帧给双锚,风格才锁得住' },
+        { scenario: '广告 / 产品片 / 空镜为主', image_model: 'gpt-image-2.5-flare', video_engine: 'wan3.0', resolution: '480p 试片 / 1080p 交付', why: '无真人脸审核问题,短镜 2 秒起计费最省;赶工换 wan3.0-prime' },
+        { scenario: '画面文字多(招牌、屏幕、文件、字卡)', image_model: 'gpt-image-2.5-sunburst', video_engine: 'seedance-2.5', resolution: '720p', why: '中文字形更准;视频按剧的真人/风格化再按上面选' },
+        { scenario: '打斗、流血场面多的写实剧', image_model: 'gpt-image-2.5-flare', video_engine: 'seedance-2.5', resolution: '720p', why: '图被安全拒的镜平台自动换 Nano Banana 2;视频侧把血腥措辞改成中性描述(Seedance 文本审核严)。不要为了过审换 WAN——写实人脸会被拒' },
+    ],
+};
 export const HOW_TO_READ = '先按 entry_points 判客户手上的材料该走哪条通道(这是最常被跳过的一步),再按 pipeline 顺序推进、每道 review_gates 必过;' +
     '收费步按 billing.quote_flow 报价确认;遇到质量投诉按 qa_tools 的 symptom 选检测工具先定病因。';
 export function buildGuide() {
@@ -392,9 +560,10 @@ export function buildGuide() {
         billing: BILLING,
         common_requests: COMMON_REQUESTS,
         local_postproduction: LOCAL_POSTPRODUCTION,
+        model_guide: MODEL_GUIDE,
     };
 }
-export const GUIDE_SECTIONS = ['entry_points', 'pipeline', 'review_gates', 'qa_tools', 'optional_boosts', 'billing', 'common_requests', 'local_postproduction'];
+export const GUIDE_SECTIONS = ['entry_points', 'pipeline', 'review_gates', 'qa_tools', 'optional_boosts', 'billing', 'common_requests', 'local_postproduction', 'model_guide'];
 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]);
 /** 引导里引用到的全部工具名(去重)——哨兵测试用:每一个都必须真的注册了。 */
@@ -437,6 +606,10 @@ export function referencedTools() {
     }
     for (const r of [...LOCAL_POSTPRODUCTION.voice_rules, ...LOCAL_POSTPRODUCTION.not_verified_until])
         inProse(r).forEach(add);
+    [MODEL_GUIDE.principle, ...MODEL_GUIDE.image_decision, ...MODEL_GUIDE.video_decision].forEach((s) => inProse(s).forEach(add));
+    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));
+    }
     return [...out].sort();
 }
 /**
@@ -458,6 +631,7 @@ export function buildInstructions() {
             '文本步按 token 后付;402 就停下让客户充值,别重试。',
         '长任务异步: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(免费、本地、不联网)。',
     ].join('\n');
 }

package/dist/tools/guide.js

@@ -12,7 +12,8 @@ export function registerGuideTools(server) {
         'qa_tools(按客户描述的症状选检测工具与修法)、optional_boosts(可选增强及何时做)、billing(报价确认与免费族)、' +
         'common_requests(客户常见原话 → 该做什么)、' +
         'local_postproduction(★客户要把镜头下载到**自己电脑**上剪 / 配乐 / 烧字幕 / 优化转场 / 补旁白时的完整流程:' +
-        '阶段顺序、执行位置、逐镜逐句怎么核对声音、什么才算验收完成)。传 section 只取一段。' +
+        '阶段顺序、执行位置、逐镜逐句怎么核对声音、什么才算验收完成)、' +
+        'model_guide(★图片模型与视频引擎的实测优劣势、价格、选型决策步骤与推荐组合——建剧选型、客户问「哪个模型好 / 为什么手画坏了 / 怎么省钱」时先看)。传 section 只取一段。' +
         '★工具描述回答"这个工具做什么",本工具回答"什么情况下该用哪个"——客户交来的是成品分镜表却被 set_script→rewrite_script 改写成散文,就是没先看这张表。', {
         section: z.enum(GUIDE_SECTIONS).optional().describe('只取某一段;不传返回全部'),
     }, async ({ section }) => {

package/dist/tools/produce.js

@@ -219,7 +219,7 @@ const PROJECT_SETTINGS_FIELDS = {
     image_model: z.string().optional().describe('图片模型(★drama级·整剧统一画风·默认 ChatGPT Image 2.5 Flare)。可选:' +
         'gpt-image-2.5-flare(默认·基础11点+每张参考图18点)/gpt-image-2.5-sunburst(同价·中文字形与细节更准·慢约5秒)/' +
         '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(Seedream 5.0)。建剧即定、整剧统一;generate_frames 可临时覆盖某次出图'),
+        'doubao-seedream-5-0-260128(Seedream 5.0)。建剧即定、整剧统一;generate_frames 可临时覆盖某次出图。★各模型实测优劣(一次过率/手部结构/安全拒绝率/画风稳定度)与选型步骤见 get_capabilities_guide(section=model_guide)'),
     // drama 级视频引擎(整剧统一,单镜/批量/场景组/重生全走它)
     video_engine: z.enum(VIDEO_ENGINES).optional().describe('视频引擎(★drama级·整剧统一·AI必须按剧选型主动引导:写实真人剧→seedance-2.5 或降本 hailuo-3;风格化/动画/3D卡通/空镜/产品镜→wan3.0(赶交付 wan3.0-prime);写实真人剧绝不选 wan——720p+ 真人脸被厂商审核一致拒):' +
         'seedance-2.5(默认·全能力:帧链/场景组/就地编辑/延长/参考图锚·720p约212点/秒) / ' +
@@ -739,7 +739,8 @@ export function registerProduceTools(server, client) {
         force: z.boolean().optional().describe('true=预检有硬阻断也强制照拼(默认拦截)。缺视频的镜会被静默跳过,成片为部分'),
     }, async ({ episode_id, force }) => jsonResult(await client.producePost(`/episodes/${episode_id}/compose`, force ? { force: true } : {})));
     server.tool('get_final_cut', '查某一集成片状态与下载链接。status=completed 时返回 download_url(我方 COS 直链,可直接下载)。免费。' +
-        '★bgm_stale=true 表示配乐在成片之后生成/改动、尚未进成片:重新 compose_episode(免费)即可,别用 re-render。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/final-cut`)));
+        '★bgm_stale=true 表示配乐在成片之后生成/改动、尚未进成片:重新 compose_episode(免费)即可,别用 re-render。' +
+        '★若登记过外部交付版本(register_external_delivery),另返回 delivery——那才是客户实际收到的一版;download_url 仍是平台自己拼的成片。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/final-cut`)));
     server.tool('get_export', '查某一集导出/母版状态(成片终拼后的可下载母版)。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/export`)));
     server.tool('review_final_cut', '**成片体检**:导出前把整集过一遍——没出图的镜、字幕一屏放不下、人物没有身份锚、'
         + '镜头连续性(跳轴)、以及一次错别字通读。'
@@ -1039,6 +1040,25 @@ export function registerProduceTools(server, client) {
         const image_url = await client.uploadLocalFile(file_path, 'image');
         return jsonResult(await client.producePost(`/storyboards/${storyboard_id}/frame`, { image_url, frame_type: frame_type ?? 'first_frame' }));
     });
+    server.tool('register_external_delivery', '★后期在平台外完成(本地换旁白/裁剪/加片尾/配乐)后,把**最终交给客户的那一版成片**登记回平台。免费。' +
+        '不登记的话,平台里的成片记录并不代表客户实际收到的版本,事后无法追溯「交付的是哪一版、每镜用的哪次生成」。' +
+        '平台会自己下载复核 sha256/大小/时长(不采信你报的值),并自动快照每镜此刻的来源素材(当前视频、采用的生成 id 及其哈希、裁剪窗口)' +
+        '和最近一次平台成片;你可在 manifest 里附上外部后期做了什么(例如 {audio:{narration:"本地替换",music:"..."}, trims:[...], ending:"..."})。' +
+        '新登记即为当前交付版,版本号每集递增;不改平台成片(get_final_cut 的 download_url 不变,另返回 delivery)。' +
+        '传 file_path(本地视频,≤300MB,自动上传)或已用 upload-url(kind=footage)上传得到的 file_url,二选一。', {
+        episode_id: z.number().int().positive(),
+        file_path: z.string().optional().describe('本地成片路径(mp4/mov/webm/m4v,≤300MB)'),
+        file_url: z.string().optional().describe('已上传到本平台的 public_url(与 file_path 二选一)'),
+        note: z.string().max(500).optional(),
+        manifest: z.record(z.unknown()).optional().describe('外部后期做了什么(≤64KB),原样存进交付清单的 client 段'),
+    }, async ({ episode_id, file_path, file_url, note, manifest }) => {
+        const url = file_path ? await client.uploadLocalFile(file_path, 'footage') : file_url;
+        if (!url)
+            throw new Error('file_path 与 file_url 必须给一个');
+        return jsonResult(await client.producePost(`/episodes/${episode_id}/deliveries`, { file_url: url, note, manifest }));
+    });
+    server.tool('list_deliveries', '列本集已登记的外部交付版本(新→旧),每条含 sha256、时长、is_current 与完整交付清单(每镜来源 + 外部后期说明)。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/deliveries`)));
+    server.tool('set_current_delivery', '把本集的某个已登记交付版本设为当前(例如客户最终选了较早的一版)。免费。只影响 get_final_cut 的 delivery,不改平台成片。', { episode_id: z.number().int().positive(), delivery_id: z.number().int().positive() }, async ({ episode_id, delivery_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/deliveries/${delivery_id}/current`)));
     server.tool('upload_shot_footage', '用**客户自有的整段视频**（录屏 / 产品实拍 / 第三方成片）直接当某镜的视频——实拍素材镜。' +
         '登记后该镜不再 AI 出图/出视频（generate_videos 会跳过它,单镜重生会被拒),终拼原样使用,镜头时长按素材真实长度回写,' +
         '首/尾帧从素材抽帧供帧链与预览用。免费。适用:宣传片里的到账界面录屏、后台大屏实录、产品实拍、客户已有的成片片段。' +
@@ -1132,6 +1152,13 @@ export function registerProduceTools(server, client) {
         + '实测 WAN 11/12 镜有镜内跳切、Seedance 1/6、H3 0/5,且提示词层拦不住(负向约束已在其中)——'
         + '要根治只能 regenerate_shot_video 这些镜并换 seedance-2.5 或 hailuo-3。'
         + '组模式镜与显式快剪蒙太奇镜天然多机位,已自动排除(detail 里标 skipped)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/intra-shot-cuts`)));
+    server.tool('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 列出这些镜。', { episode_id: z.number().int().positive(), dry_run: z.boolean().optional() }, async ({ episode_id, dry_run }) => jsonResult(await client.producePost(`/episodes/${episode_id}/video-text-scan`, { dry_run: dry_run === true })));
     server.tool('scan_dialogue_coverage', '★客户报「话没说完就切 / 台词只念了一半」时先跑这个。默认**免费零扣费**(只读已落库的转录审计结果)。'
         + '把该集每个原声镜的视频音轨与台词做词级比对,按族给出结论:'
         + 'truncated(念到一半就停) / off_script(念的大半不是台词:自说自话、重复上一镜、只有环境音) / '

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.88",
-    "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.88 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.89",
+    "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.89 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -3248,6 +3248,109 @@
         }
       }
     },
+    "/episodes/{episode_id}/deliveries": {
+      "get": {
+        "operationId": "list_deliveries",
+        "summary": "列本集已登记的外部交付版本(新→旧),每条含 sha256、时长、is_current 与完整交付清单(每镜来源 + 外部后期说明)",
+        "description": "列本集已登记的外部交付版本(新→旧),每条含 sha256、时长、is_current 与完整交付清单(每镜来源 + 外部后期说明)。免费。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_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"
+          }
+        }
+      }
+    },
+    "/episodes/{episode_id}/deliveries/{delivery_id}/current": {
+      "post": {
+        "operationId": "set_current_delivery",
+        "summary": "把本集的某个已登记交付版本设为当前(例如客户最终选了较早的一版)",
+        "description": "把本集的某个已登记交付版本设为当前(例如客户最终选了较早的一版)。免费。只影响 get_final_cut 的 delivery,不改平台成片。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          },
+          {
+            "name": "delivery_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"
+          }
+        }
+      }
+    },
     "/episodes/{episode_id}/derive-pose-chain": {
       "post": {
         "operationId": "derive_pose_chain",
@@ -4138,7 +4241,7 @@
       "get": {
         "operationId": "get_final_cut",
         "summary": "查某一集成片状态与下载链接",
-        "description": "查某一集成片状态与下载链接。status=completed 时返回 download_url(我方 COS 直链,可直接下载)。免费。★bgm_stale=true 表示配乐在成片之后生成/改动、尚未进成片:重新 compose_episode(免费)即可,别用 re-render。",
+        "description": "查某一集成片状态与下载链接。status=completed 时返回 download_url(我方 COS 直链,可直接下载)。免费。★bgm_stale=true 表示配乐在成片之后生成/改动、尚未进成片:重新 compose_episode(免费)即可,别用 re-render。★若登记过外部交付版本(register_external_delivery),另返回 delivery——那才是客户实际收到的一版;download_url 仍是平台自己拼的成片。",
         "tags": [
           "episodes"
         ],
@@ -6642,6 +6745,68 @@
         }
       }
     },
+    "/episodes/{episode_id}/video-text-scan": {
+      "post": {
+        "operationId": "scan_burned_subtitles",
+        "summary": "★原声剧（视频自带人声）终拼前建议跑一次；客户报「成片里有两层字幕 / 画面里多出一行字」时先跑这个",
+        "description": "★原声剧（视频自带人声）终拼前建议跑一次；客户报「成片里有两层字幕 / 画面里多出一行字」时先跑这个。视频厂商有时会无视「不要字幕」的约束，把台词烧进画面——字小、通常只在说出那句台词的一两秒内出现，而平台成片还会再叠一层字幕，于是变成双字幕。重新拼接去不掉它，只能 regenerate_shot_video 重出该镜。每镜抽 12 帧、一次视觉审计，**按用量计费**（每镜一次小额 vision 调用）。返回 flagged[{shot, texts, matches_dialogue, frames}] / clean / errors。matches_dialogue=true 表示读出来的字就是本镜台词，基本可确认是厂商字幕；招牌、书页、屏幕等画面里本来就有的字不算。dry_run=true 只报告不写回；否则结果写回，compose_episode 的终拼预检会以 vendor_burned_text 列出这些镜。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "dry_run": {
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "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}/videos/generate": {
       "post": {
         "operationId": "generate_videos",
@@ -10104,6 +10269,10 @@
       "tool": "upload_shot_frame",
       "reason": "unmappable: local file upload flow"
     },
+    {
+      "tool": "register_external_delivery",
+      "reason": "unmappable: local file upload flow"
+    },
     {
       "tool": "upload_shot_footage",
       "reason": "unmappable: local file upload flow"

package/package.json

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