@starreel/mcp 0.1.52 → 0.1.54

package/README.md

@@ -8,7 +8,7 @@
 [![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
 **StarReel** is a prepaid AI video-production pipeline. This MCP server exposes the
-whole factory — **80+ tools** covering every stage — so an AI agent can take a raw
+whole factory — **120+ tools** covering every stage — so an AI agent can take a raw
 script all the way to a finished `.mp4`:
 
 ```
@@ -120,8 +120,10 @@ See the [API docs](https://api.shortreelai.com/docs/mcp).
 
 | Stage | Tools (selection) |
 |---|---|
+| Orientation | `get_capabilities_guide` (free, local) — which entry point for which material, pipeline order, gates, billing |
 | Project setup | `create_drama` · `update_project_settings` · `list_project_options` |
 | Script | `set_script` · AI rewrite · `edit_rewritten_script` |
+| Bring your own material | `get_script_format_spec` · `check_script_format` · `adopt_external_script` (rewrite on any AI, then adopt verbatim) · `import_storyboard_table` (a finished shot list skips rewrite + breakdown) · `upload_*` (own portraits / scene / prop / shot images) |
 | Cast & world | asset extraction · `update_character` · `generate_world_concept` · `generate_art_bible` |
 | Identity anchors | `generate_portraits_and_sheets` (portraits + character sheets = the consistency anchor) |
 | Storyboards | `quote_storyboards` → `generate_storyboards` → `get_storyboards` |
@@ -149,6 +151,9 @@ Project types: `drama` / `ad` / `mv` / `brand_film`.
 
 [`SKILL.md`](./SKILL.md) ships inside the package — a platform-agnostic operating
 manual (full pipeline order + ten operating disciplines + a failure playbook).
+The server also announces the same guidance at connect time (MCP `instructions`)
+and exposes it as a tool, `get_capabilities_guide`, so an agent that has never
+seen this file still learns which entry point each kind of material takes.
 Skill-aware clients load it automatically; on platforms that can't run `npx`
 (Coze / Dify / GPTs / custom agents) paste it into the system prompt and drive
 the same pipeline over REST (`/v1/produce/*`).

package/SKILL.md

@@ -4,7 +4,8 @@ description: >-
   Operating skill for any AI agent driving the StarReel short-drama production
   pipeline (script → rewrite → extract → portraits + sheets → storyboards → frames →
   video → voiceover → final cut) over MCP or REST. Covers the ordered workflow,
-  the eleven operating disciplines (prepaid billing, quote-before-spend, retryable
+  the entry-point decision table (which channel each kind of customer material
+  takes), the eleven operating disciplines (prepaid billing, quote-before-spend, retryable
   failure handling, content compliance, tenancy), and a failure playbook.
 license: MIT
 homepage: https://api.shortreelai.com/docs/mcp
@@ -54,6 +55,29 @@ big-ticket image/video stages (portraits, storyboards, frames, videos,
 scene-images) carry a `quote_*`; the other metered steps have no quote and bill
 by usage — 402 mid-run if the balance can't cover them (never overdraft).
 
+## Which entry point? — match the customer's material first
+
+The most common agent mistake is not a wrong parameter but a wrong **entry
+point**: everything gets pushed through `set_script → rewrite_script`, even
+material that has its own channel. Decide this before calling anything. The
+server ships the same table as `get_capabilities_guide` (free, local, no
+network — call it whenever you are unsure what the platform can do) and
+announces a condensed version as MCP `instructions` at connect time.
+
+| The customer has | Use | Never |
+|---|---|---|
+| A novel / outline / synopsis (not yet a screenplay) | `set_script` → `rewrite_script` (creative rewrite builds hooks and beats) → `review_script` | — |
+| A finished screenplay (scene headers + dialogue lines) | `set_script` → `rewrite_script` (auto two-pass fidelity: dialogue byte-locked) → `review_script`; force with `rewrite_pipeline: "two_pass"`, `fidelity_enforce: 1` | pasting it into `edit_rewritten_script` (400) |
+| Wants to rewrite on another AI / says our rewrite "changed too much" | `get_script_format_spec` → external rewrite → `check_script_format` → `adopt_external_script` (exit A) or `set_script` + `rewrite_script` (exit B) | skipping the check; `edit_rewritten_script` |
+| A finished **shot list** (per-shot seconds / shot size / camera move) | `import_storyboard_table` → `autofill_storyboards` → `review_storyboards` | `rewrite_script` + `generate_storyboards` — strips every production parameter (measured: 8 shots / 36 s became 20 shots / 109 s) |
+| Their own portraits / scene / prop / shot images | `upload_image` · `set_character_portrait` · `upload_scene_image` · `upload_prop_sheet` · `upload_shot_frame` | rendering a "fix" elsewhere and uploading it — use `generate_shot_frame` |
+| A voice sample / a required voice | `clone_voice` → `speak_with_voice` → `set_character_voice` / `assign_voices` | cloning without the rights-holder's consent |
+| 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 `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) |
+| A multi-language release | `translate_subtitles` · `subtitle_secondary_lang` in project settings | — |
+
 ## Execution tiers — when to just do it vs. when to ask
 
 Don't ask the user at every step. Sort work into three tiers:
@@ -290,15 +314,30 @@ original." The answer is not to argue about rewrite quality — it is to hand
 them the format contract so **they** do the rewriting wherever they like, and
 our pipeline only has to accept it.
 
-Three steps, all free:
+First ask which of the two exits they want — it decides whether the external
+model must produce the production annotations:
+
+- **Exit A · adopt directly.** The external model produces the full draft
+  *including* production annotations (`[角色档案]`, `[外貌]`, `[道具]`,
+  `[SFX]/[BGM]/[VFX]`, the scene header's 4th lighting segment). Format check
+  passes → `adopt_external_script` stores it as the shooting script. Our AI
+  never touches it: instant, free, and what the user wrote stays byte-for-byte.
+- **Exit B · send through AI rewrite.** The external model produces the story
+  layer only (**no annotations at all**). `set_script` puts it in the source
+  slot, `rewrite_script` runs the two-pass fidelity rewrite and adds the
+  annotations. Note that on this path any annotation the user wrote is
+  **stripped by G1 and rewritten** — so on Exit B, tell the external model not
+  to write them.
+
+Then, all free:
 
 1. `get_script_format_spec` → returns `markdown` (the full contract),
-   `external_prompt` (a ready-to-forward task prompt for any external model),
-   and `skeleton` (a blank scene skeleton). Give the user the prompt plus the
-   markdown to send to the other platform along with their original draft.
-   The prompt already carries the four fidelity requirements: keep every
-   line of dialogue verbatim, keep every character, keep every action beat,
-   invent nothing.
+   `external_prompt` (a ready-to-forward task prompt), `skeleton` (a template
+   with 〈…〉 placeholders) and `filled_example` (a worked example). **Send the
+   worked example along with the prompt** — format accuracy comes from a
+   complete sample to imitate, not from rules prose. The prompt already carries
+   the fidelity requirements: keep every line of dialogue verbatim, keep every
+   character, keep every action beat, invent nothing.
 2. `check_script_format` on what comes back → a per-issue list.
    `errors` are what the platform rejects unconditionally (empty / too short /
    no scene headers / camera-movement words / end-card markers) and must be
@@ -306,19 +345,26 @@ Three steps, all free:
    `strictOnly` become rejections once the project turns on strict mode.
    Send the `message` list straight back to the external model and ask it to
    fix **only** those points, copying everything else verbatim. Re-check.
-3. `set_script` with the cleaned draft (it goes into the **source** slot),
-   then `rewrite_script` as usual. Because the source is now screenplay-shaped,
-   the fidelity route takes over automatically — dialogue is byte-locked and
-   the stored draft ends up nearly identical to what the user approved.
+3. Take the exit the user picked. **Exit A**: `adopt_external_script`
+   (the server re-runs the gate; `errors` non-empty → 400, so a draft that
+   fails the check cannot slip through). **Exit B**: `set_script` with the
+   cleaned draft, then `rewrite_script` as usual — because the source is now
+   screenplay-shaped, the fidelity route takes over automatically.
 
 Do **not** push an externally written draft into `edit_rewritten_script` — that
 endpoint rejects (400) an episode that has never been rewritten, by design.
 And do not skip step 2: a draft that fails the format gates is rejected at
 `save_script` anyway, wasting a full rewrite cycle.
 
-`check_script_format` checks **format only**. Whether the dialogue survived
-line-for-line is judged against the original at rewrite time — the checker has
-no source-side input.
+Two things about the checker worth knowing:
+
+- It checks **format only**. Whether the dialogue survived line-for-line is
+  judged against the original at rewrite time — the checker has no source-side
+  input. On Exit A there is no such comparison at all, so fidelity there is
+  whatever the external model delivered.
+- Scene length is measured on the **story layer**: `[角色档案]` / `[外貌]` /
+  `[道具]` / `[SFX]` lines do not count toward the 120-character budget. Never
+  tell a user to delete annotations to get a scene under the limit.
 
 ## After the first rewrite — 点改优先 (point-edit, don't re-run)
 
@@ -508,12 +554,17 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
 
 ## Quick tool reference
 
+- **Orientation (free, local)**: `get_capabilities_guide` — entry points by
+  material, the 10-step pipeline with billing, the review gates, QA tools by
+  symptom, and common customer requests
 - **Discover / create**: `list_project_options`, `create_drama`,
   `update_project_settings`
 - **Script**: `set_script`, `rewrite_script`, `get_script`,
   `edit_rewritten_script`, `extract_assets`,
-  `get_script_format_spec` + `check_script_format` (free — the format contract
-  to hand an external AI, and the pre-paste self-check)
+  `get_script_format_spec` + `check_script_format` + `adopt_external_script`
+  (free — the format contract to hand an external AI, the pre-paste self-check,
+  and the "adopt it verbatim" exit), `import_storyboard_table` (free — a
+  finished shot list becomes shots directly, skipping rewrite and breakdown)
 - **Identity & consistency**: `generate_character_portraits`, `upload_image`,
   `set_character_portrait`, `generate_character_sheet`, `extract_visual_lock`
 - **Shots → video**: `quote/generate_storyboards`, `get_storyboards`,

package/dist/index.js

@@ -12,6 +12,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StarReelClient } from './client.js';
 import { registerProduceTools } from './tools/produce.js';
+import { registerGuideTools } from './tools/guide.js';
+import { buildInstructions } from './tools/guide-data.js';
 const apiKey = process.env.STARREEL_API_KEY;
 if (!apiKey) {
     console.error('STARREEL_API_KEY is not set.\n' +
@@ -19,8 +21,12 @@ if (!apiKey) {
         '  claude mcp add starreel -e STARREEL_API_KEY=srk_live_... -- npx -y @starreel/mcp');
     process.exit(1);
 }
-const server = new McpServer({ name: 'starreel', version: '0.1.0' });
+// server 级 instructions:客户端 initialize 时拿到,多数客户端注入系统提示——agent 在看任何工具之前
+// 就先拿到「客户这种材料该走哪条入口」的决策树。全文与 get_capabilities_guide 同源(tools/guide-data.ts),
+// 后端哨兵测试钉住:引导里提到的每个工具名都必须真的注册了。
+const server = new McpServer({ name: 'starreel', version: '0.1.0' }, { instructions: buildInstructions() });
 const client = new StarReelClient(apiKey);
+registerGuideTools(server); // 功能地图(免费·本地·不联网):什么情况下该用哪个工具
 registerProduceTools(server, client); // 短剧编排产线(需 produce scope)——从剧本到成片
 // 出海本地化工具:translator worker 暂时离线(2026-08),发布版先不注册,免得客户拿到只会
 // 报错的工具。worker 重建后取消下一行注释即可(工具代码保留在 tools/localize.ts)。

package/dist/tools/guide-data.js

@@ -0,0 +1,328 @@
+/**
+ * 功能地图 —— 单一真相源。三个消费方都从这里取数：
+ *   · index.ts 的 server 级 instructions(客户端 initialize 时拿到、通常注入系统提示);
+ *   · get_capabilities_guide 工具(agent 主动查"你们能做什么/客户这种材料该走哪条通道");
+ *   · 后端哨兵测试(引导里提到的每个工具名都必须真的注册了,工具改名/下线时测试会红,
+ *     引导不会悄悄指向不存在的工具)。
+ *
+ * 为什么要有它:124 个工具各自的描述都很详细,但 agent 拿到工具清单后并不知道
+ * 「客户手上这种材料该走哪条通道」(格式范本 / 分镜表直通道 / 自有素材上传 / 交接包 …),
+ * 于是永远只走 set_script → rewrite_script 一条路——客户交的是成品分镜表也被改写成散文。
+ * 工具描述回答"这个工具做什么",本文件回答"什么情况下该用哪个"。
+ *
+ * ★本文件不 import SDK、不联网、不读环境,后端测试可直接 import。
+ * ★列表字段(use / tools / run / fix)里每一项以**工具名开头**,括号里写关键参数;
+ *   散文字段里的工具名用反引号包住——referencedTools() 靠这两条约定抽名字。
+ */
+export const GUIDE_VERSION = '2026-09-02';
+/** 按客户手上的材料选入口——这是 agent 最常缺的那张表。 */
+export const ENTRY_POINTS = [
+    {
+        customer_has: '小说 / 故事大纲 / 梗概(还不是剧本形态)',
+        use: [
+            'create_drama(建剧即设好 setting_brief/画幅/video_engine/image_model 等免费地基,别建空壳)',
+            'set_script',
+            'rewrite_script(auto 路由→创作型改写:AI 铺钩子与情感点)',
+            'review_script',
+        ],
+        note: '改写成功一次后所有修改只走 `edit_rewritten_script` 点改,别重跑 `rewrite_script`(整篇重来,已改好的地方会退回)。',
+    },
+    {
+        customer_has: '已写好的剧本(有场景头 + 对白行结构)',
+        use: [
+            'set_script',
+            'rewrite_script(auto 路由→两步保真:台词逐句机器锁定、AI 不加戏)',
+            'get_script(dramaturgy_suggestions 是 AI 识别到但没自动补的剧作缺口,转述给客户定)',
+            'review_script',
+        ],
+        note: '客户要求逐句保留 → `update_project_settings` 设 rewrite_pipeline=two_pass + fidelity_enforce=1。改写仍是必经步:把稿子直接塞进 `edit_rewritten_script` 会 400。',
+    },
+    {
+        customer_has: '想拿到别的 AI 平台自己改写 / 反馈「你们的 AI 改动太大」',
+        use: [
+            'get_script_format_spec(把 external_prompt + filled_example + markdown 连同原稿一起交给那个平台;务必带 filled_example)',
+            'check_script_format(拿回整理稿先自查;errors 清零再往下;免费可反复跑)',
+            'adopt_external_script(出口 A:外部稿含制作层标注 → 直接采用为可拍稿,我方 AI 不介入、秒级、不计费)',
+            'set_script(出口 B:外部只做了剧情层 → 灌回原稿位,再 rewrite_script 走保真两步补标注)',
+        ],
+        avoid: '别把外部整理稿塞进 `edit_rewritten_script`(未跑过改写会 400);也别跳过 `check_script_format` 直接灌——格式不合规照样被闸拦,白跑一轮。',
+        free: true,
+        flow: 'get_script_format_spec → 交给外部平台改 → check_script_format(errors 清零) → 出口A adopt_external_script(含标注·直接采用·免费) 或 出口B set_script + rewrite_script(只有剧情层·平台补标注)',
+    },
+    {
+        customer_has: '做完的成品分镜表(逐镜写了秒数 / 景别 / 运镜;常见于样片、交给电视台或品牌方的表)',
+        use: ['import_storyboard_table(不传 content 则读本集原始内容;本集已有分镜要 confirm_replace:true)'],
+        avoid: '绝不走 set_script→rewrite_script→generate_storyboards:改写会把秒数/景别/运镜/STYLE/字卡当非剧情内容剥掉(生产实测 8 镜 36 秒被拆成 20 镜 109 秒)。',
+        note: '导入后分镜还没有出图/视频提示词,先 `autofill_storyboards` 再出图;`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲,不出图不出视频)。',
+        free: true,
+    },
+    {
+        customer_has: '自有的定妆图 / 场景图 / 道具图 / 镜头图(客户真实素材)',
+        use: [
+            'upload_image',
+            'set_character_portrait(换定妆图后响应里的 stale_frames 就是被旧图污染、要逐镜重生的镜)',
+            'upload_scene_image',
+            'upload_prop_sheet',
+            'upload_shot_frame(只用于客户自有真实素材)',
+        ],
+        avoid: '要「改某一镜画面」走 `generate_shot_frame`(平台自动带该镜身份锚·场景道具参考·画风锚);别在外部工具画好再 `upload_shot_frame`——外部图没有任何锚,人物/服装/画风必漂。',
+        flow: 'upload_image · set_character_portrait · upload_scene_image · upload_prop_sheet · upload_shot_frame(仅客户自有素材;要改画面走 generate_shot_frame)',
+    },
+    {
+        customer_has: '自己的声音样本 / 指定音色',
+        use: [
+            'clone_voice(需客户对该声音有授权;按音色计费,失败自动退)',
+            'speak_with_voice(任意文本试听)',
+            'list_voices',
+            'set_character_voice(绑到角色;传 voice_id 如 lib:12)',
+            'assign_voices',
+        ],
+        note: '所有项目默认视频原声(use_clip_audio=true,跳过 TTS);要配音把它设 false,并主动告诉客户可切换。',
+        flow: 'clone_voice → speak_with_voice(试听) → set_character_voice / assign_voices',
+    },
+    {
+        customer_has: '歌曲 + 歌词(MV)',
+        use: [
+            'create_drama(project_type=mv)',
+            'set_mv_lyrics',
+            'generate_mv_story',
+            'generate_mv_script',
+            'get_mv',
+        ],
+        note: 'MV 不走标准 `rewrite_script`(会被拦),之后回到 extract_assets → 分镜 → 出图的标准链。',
+    },
+    {
+        customer_has: '产品 / 品牌(广告、品牌微电影)',
+        use: [
+            'create_drama(project_type=ad 或 brand_film)',
+            'add_product',
+            'generate_product_sheet',
+            'list_products',
+            'render_multi_aspect(成片一源多画幅)',
+        ],
+        note: '广告改写自动走广告改写 agent;文字卡/品牌文案别写成台词(会被念出来)。',
+    },
+    {
+        customer_has: '已生成的镜头 / 成片要改(改台词、裁剪、拆镜、重生某镜、换引擎)',
+        use: [
+            'scan_dialogue_coverage(先定病因:话没说完/念错/走到别的镜;免费)',
+            'scan_intra_shot_cuts(「切太快」先看厂商有没有在单镜内自行硬切;免费)',
+            'update_shot(景别/动作/台词/运镜等文本字段;character_ids 全量覆盖)',
+            'replace_shot_dialogue',
+            'repair_episode_dialogue(换音频不重生视频,按 TTS 费率,比重生便宜几个数量级)',
+            'split_shot',
+            'trim_shot',
+            'recommend_trim_window',
+            'regenerate_shot_video',
+            'edit_video_shot(就地编辑;get_edit_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: ['export_handoff_pack', 'get_handoff_toolchain', 'save_handoff_toolchain'],
+        note: '与 `compose_episode` 二选一。audio_contract.mode=tts 时裸片没有人声,对白轨单独发——漏掉整集是哑的。',
+    },
+    {
+        customer_has: '多语言发行',
+        use: ['translate_subtitles', 'update_project_settings(subtitle_secondary_lang 双语烧录 / subtitle_translation_only 仅译文)'],
+    },
+];
+/** 10 步产线(与 get_pipeline_status 的步序一致;不跳步)。 */
+export const PIPELINE = [
+    {
+        step: '1 建剧与项目设定',
+        tools: ['list_project_options', 'create_drama', 'update_project_settings'],
+        billing: '免费',
+        note: 'setting_brief(世界观/ERA LOCK)、画幅、video_engine、image_model、cinematography_prompt/art_bible/visual_lock 都在这一步定;收费步前服务端会要求 setting_brief≥30 字 + aspect_ratio。',
+    },
+    {
+        step: '2 灌本',
+        tools: ['set_script', 'import_storyboard_table(直通道:已有分镜表)', 'adopt_external_script(直通道:外部按范本产出的稿)'],
+        billing: '免费',
+    },
+    {
+        step: '3 AI 改写',
+        tools: ['rewrite_script', 'get_script', 'edit_rewritten_script'],
+        billing: '文本按 token 后付',
+        gate: 'review_script(改写稿审查;免费;extract_assets / generate_storyboards 前必过)',
+        note: '典型 2~4 分钟;60 秒内查不到不是失败,用 `get_run_status` 判断。',
+    },
+    {
+        step: '4 提取资产(角色/场景/道具)',
+        tools: ['extract_assets', 'get_characters', 'get_scenes', 'get_props', 'update_character', 'update_scene', 'update_prop', 'create_prop', 'mark_signature_prop'],
+        billing: '文本按 token 后付',
+        note: '角色外观唯一真相源 = 人物档案(`update_character` 改;客户确认后 profile_locked=1 锁定);别把角色外观写进 visual_lock/art_bible。',
+    },
+    {
+        step: '5 拆镜(纯文本,先于任何出图)',
+        tools: ['quote_storyboards', 'generate_storyboards', 'get_storyboards', 'get_health_report', 'autofill_storyboards', 'enhance_shot_prompts', 'complete_ending_motifs'],
+        billing: '报价确认后扣点',
+        gate: 'review_storyboards(分镜审查;免费;generate_frames 前必过)',
+        note: '每镜 5-7 秒是对 AI 出视频优化的正常时长,别因「镜偏长」重拆;`generate_storyboards` 替换整集分镜,已有分镜需 confirm_replace。',
+    },
+    {
+        step: '6 剧目级一致性资产(分镜后、出图前)',
+        tools: [
+            'quote_character_portraits', 'generate_portraits_and_sheets(定妆图+设定图,一致性锚)',
+            'generate_world_concept(默认必做,仍走报价)', 'generate_motion_templates', 'generate_color_script',
+            'generate_art_bible', 'extract_visual_lock', 'extract_setting_brief', 'generate_video_style',
+            'quote_scene_images', 'generate_scene_images', 'generate_prop_sheet',
+        ],
+        billing: '报价确认后扣点',
+        note: '分镜后建只给出场角色出图更省;动作模板本就必须分镜后。',
+    },
+    {
+        step: '7 出帧(镜头图)',
+        tools: ['run_precheck(免费,揪出必被厂商拒的镜)', 'quote_frames', 'generate_frames', 'quote_shot_frame', 'generate_shot_frame(单镜重生)', 'chain_frames', 'upload_shot_frame'],
+        billing: '报价确认后扣点',
+        gate: 'review_frames(镜头图审查;免费;generate_videos 前必过)',
+        note: '默认只出首帧;尾帧按需(frame_type=last_frame)。pending=还在生成,别重复调 `generate_frames`(重复扣费)。',
+    },
+    {
+        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', 'get_edit_capabilities'],
+        billing: '报价确认后扣点',
+        note: 'video_engine 必须在出视频前定(seedance-2.5 默认 / hailuo-3 降本 / wan3.0 风格化·绝不用于写实真人);切换不回溯已生成镜头。',
+    },
+    {
+        step: '9 音频',
+        tools: ['assign_voices', 'generate_tts(仅 use_clip_audio=false)', 'clone_voice', 'generate_bgm', 'get_bgm_status', 'generate_sfx', 'lipsync_shot', 'lipsync_episode', 'get_lipsync_status', 'set_shot_name_card'],
+        billing: '混合',
+        note: '默认视频原声跳过 TTS 三步(pipeline-status 里显示 not_required,不是没做完)。',
+    },
+    {
+        step: '10 成片与交付',
+        tools: ['compose_episode', 'get_final_cut', 'get_export', 'rerender_episode', 'get_deliverables', 'generate_deliverables', 'render_multi_aspect', 'generate_effects', 'generate_transitions', 'generate_episode_poster', 'generate_drama_poster', 'generate_cover', 'translate_subtitles', 'get_pipeline_status'],
+        billing: '免费',
+        note: '终拼免费(ffmpeg+COS);成片前用 `get_pipeline_status` 确认没有缺镜;配乐晚于成片(bgm_stale)重新 compose 即可。',
+    },
+];
+export const REVIEW_GATES = [
+    { after: '改写稿产出', run: 'review_script', before: ['extract_assets', 'generate_storyboards'] },
+    { after: '分镜产出', run: 'review_storyboards', before: ['generate_frames'] },
+    { after: '镜头图产出', run: 'review_frames', before: ['generate_videos'] },
+];
+export const REVIEW_GATE_RULE = '三道闸全部免费、服务端强制(跳过 → 400)。每次审查返回 review_token,把它随下游收费工具一起传;' +
+    'findings 逐条原样告诉客户(code=问题类型 · shots=命中镜号 · action=该调哪个工具修),按 action 修完复审再走。' +
+    '审查后又改了内容 → token 自动失效,复审一次即可。有 error 时默认拦截;只有客户知情并坚持才带 acknowledge_review:true——不要替客户做这个决定。' +
+    '`review_all` 是整集体检、不发 token。';
+export const QA_TOOLS = [
+    { symptom: '话没说完就切 / 台词跑到别的镜上', run: 'scan_dialogue_coverage', then: ['repair_episode_dialogue(首选:换音频不重生,便宜)', 'regenerate_shot_video(特写镜或画面也错时)', 'compose_episode'] },
+    { symptom: '切太快 / 一个镜头里画面跳来跳去', run: 'scan_intra_shot_cuts', then: ['update_project_settings(video_engine 改 seedance-2.5 或 hailuo-3)', 'regenerate_shot_video'] },
+    { symptom: '动作发生在裁剪窗口之外', run: 'recommend_trim_window', then: ['trim_shot'] },
+    { symptom: '画面多出一个人 / 多出一件道具', run: 'get_storyboards(先看该镜实际用的首帧)', then: ['generate_shot_frame(首帧本身就有→重生首帧再重生视频)', 'split_shot(帧干净、片中长出来→拆成 3~5 秒短镜)'] },
+    { symptom: '出图 / 出视频前想知道哪些镜会被厂商拒', run: 'run_precheck', then: ['update_shot', 'generate_shot_frame'] },
+    { symptom: '整集健康度 / 缺镜 / 进度', run: 'get_pipeline_status', then: ['get_health_report', 'review_all', 'get_storyboards', 'get_jobs', 'get_run_status'] },
+    { symptom: '预算 / 余额', run: 'get_budget_status', then: ['get_cost_estimate'] },
+];
+export const OPTIONAL_BOOSTS = [
+    { what: '世界观概念图', tool: 'generate_world_concept', when: '分镜后默认做(提升整剧一致性),仍走报价确认' },
+    { what: '美术圣经 / 视觉锁 / 世界观 Brief 抽取', tool: 'generate_art_bible', when: '建剧后;或 `extract_visual_lock` / `extract_setting_brief` 从剧本反推' },
+    { what: '动作模板(统一全片运动语言)', tool: 'generate_motion_templates', when: '分镜后、出图前;漏了动作会散乱' },
+    { what: '色彩脚本(统一色调)', tool: 'generate_color_script', when: '分镜后、出图前' },
+    { what: '场景图(空景基板)', tool: 'generate_scene_images', when: '出镜头图前;先 `quote_scene_images`' },
+    { what: '场景组(同场景多镜一次成组出视频)', tool: 'generate_scene_groups', when: '先 `get_scene_group_plan` 看方案' },
+    { what: '口型同步', tool: 'lipsync_episode', when: 'TTS 配音项目需要对口型时' },
+    { what: '海报 / 封面', tool: 'generate_episode_poster', when: '成片后;`generate_drama_poster` / `generate_cover` 同族' },
+    { what: '音效 / 特效 / 转场(本地库匹配)', tool: 'generate_sfx', when: '免费;`generate_effects` / `generate_transitions` 同族' },
+    { what: '配乐', tool: 'generate_bgm', when: '按整集情绪弧线生成;终拼自动接管' },
+    { what: '字幕翻译', tool: 'translate_subtitles', when: '出海;双语烧录在项目设定里开' },
+];
+export const BILLING = {
+    prepaid: '预付费、永不透支。余额不足返回 402(带 needed),停下来让客户充值,绝不循环重试。',
+    quote_flow: '大额步(定妆图 / 分镜 / 出帧 / 出视频 / 场景图)一律 quote_* → 把 estimated_points **原样**告诉客户 → 客户明确同意 → generate_*(带 quote_id)。' +
+        'quote_id 一次性、约 15 分钟过期;绝不擅自确认,视频报价可能上万点。',
+    pay_as_you_go: '文本步(改写 / 提取 / 自动填充 / 增强提示词)按 token 后付,无需报价但要事先告知。',
+    free_families: [
+        '所有 get_* / list_* / scan_* / review_* / check_* / recommend_* / get_capabilities_guide',
+        'compose_episode / rerender_episode / render_multi_aspect / generate_sfx / generate_effects / generate_transitions',
+        'import_storyboard_table / adopt_external_script / get_script_format_spec / check_script_format',
+        'update_* / edit_rewritten_script / split_shot / trim_shot / set_character_portrait / upload_*',
+    ],
+    tools: ['get_budget_status', 'get_cost_estimate'],
+};
+export const COMMON_REQUESTS = [
+    { customer_says: '你们能做什么 / 我该从哪开始', do: '先问客户手上有什么材料,对照 entry_points 选通道;建剧前 `list_project_options` 把项目类型/画幅/分辨率/引擎给客户挑。' },
+    { customer_says: 'AI 把我的剧本改偏了 / 改动太大', do: '① 确认完整原稿已进 `set_script`;② `update_project_settings` 设 rewrite_pipeline=two_pass 后重跑 `rewrite_script`;③ 客户确认外观后 `update_character` profile_locked=1。客户想自己掌控 → 走格式范本三步(`get_script_format_spec` → 外部改 → `check_script_format`)。' },
+    { customer_says: '我有分镜表了,直接出片', do: '`import_storyboard_table`,不要走改写;导入后 `autofill_storyboards` 补提示词再 `review_storyboards`。' },
+    { customer_says: '换了定妆图 / 换脸后镜头没变', do: '`set_character_portrait` 响应里的 stale_frames 逐镜 `generate_shot_frame`,再重生视频。' },
+    { customer_says: '图片一直没出来', do: '`get_storyboards` 看 frame_status:pending=在生成(每张几十秒到数分钟、整集十几分钟),别重复调 `generate_frames`;failed 才是失败,读 fail_reason / fail_hint。' },
+    { customer_says: '预算多少 / 怎么更便宜', do: '各步 quote_* + `get_cost_estimate`;降本:hailuo-3(约 1/3)或 wan3.0(约 4 折,仅风格化/空镜/产品镜,写实真人绝不选)+ 草稿期低分辨率。' },
+    { customer_says: '成片里话没说完 / 切太快', do: '先 `scan_dialogue_coverage` / `scan_intra_shot_cuts` 定病因,再按 qa_tools 的 then 修;别默认去加长镜头。' },
+    { customer_says: '我想自己剪', do: '`export_handoff_pack` + `get_handoff_toolchain`,不走 `compose_episode`。' },
+    { customer_says: '要配音 / 不要视频原声', do: '`update_project_settings` use_clip_audio=false → `assign_voices` → `generate_tts` → `compose_episode`。' },
+];
+export const HOW_TO_READ = '先按 entry_points 判客户手上的材料该走哪条通道(这是最常被跳过的一步),再按 pipeline 顺序推进、每道 review_gates 必过;' +
+    '收费步按 billing.quote_flow 报价确认;遇到质量投诉按 qa_tools 的 symptom 选检测工具先定病因。';
+export function buildGuide() {
+    return {
+        version: GUIDE_VERSION,
+        how_to_read: HOW_TO_READ,
+        entry_points: ENTRY_POINTS,
+        pipeline: PIPELINE,
+        review_gates: { rule: REVIEW_GATE_RULE, gates: REVIEW_GATES },
+        qa_tools: QA_TOOLS,
+        optional_boosts: OPTIONAL_BOOSTS,
+        billing: BILLING,
+        common_requests: COMMON_REQUESTS,
+    };
+}
+export const GUIDE_SECTIONS = ['entry_points', 'pipeline', 'review_gates', 'qa_tools', 'optional_boosts', 'billing', 'common_requests'];
+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]);
+/** 引导里引用到的全部工具名(去重)——哨兵测试用:每一个都必须真的注册了。 */
+export function referencedTools() {
+    const out = new Set();
+    const add = (v) => { if (v)
+        out.add(v); };
+    for (const e of ENTRY_POINTS) {
+        e.use.forEach((u) => add(head(u)));
+        [...inProse(e.avoid), ...inProse(e.note)].forEach(add);
+    }
+    for (const p of PIPELINE) {
+        p.tools.forEach((t) => add(head(t)));
+        if (p.gate)
+            add(head(p.gate));
+        inProse(p.note).forEach(add);
+    }
+    for (const g of REVIEW_GATES) {
+        add(g.run);
+        g.before.forEach(add);
+    }
+    inProse(REVIEW_GATE_RULE).forEach(add);
+    for (const q of QA_TOOLS) {
+        add(head(q.run));
+        q.then.forEach((t) => add(head(t)));
+    }
+    for (const b of OPTIONAL_BOOSTS) {
+        add(b.tool);
+        inProse(b.when).forEach(add);
+    }
+    BILLING.tools.forEach(add);
+    for (const c of COMMON_REQUESTS)
+        inProse(c.do).forEach(add);
+    return [...out].sort();
+}
+/**
+ * server 级 instructions:客户端 initialize 时拿到,多数客户端注入系统提示。
+ * 要短——只放入口决策树、产线顺序、硬闸与计费纪律;细节让 agent 调 get_capabilities_guide。
+ */
+export function buildInstructions() {
+    const entry = ENTRY_POINTS.map((e) => `· ${e.customer_has} → ${e.flow ?? e.use.map((u) => head(u)).filter(Boolean).join(' → ')}`).join('\n');
+    return [
+        'StarReel = 预付费 AI 短剧产线(剧本 → AI 改写 → 资产 → 分镜 → 镜头图 → 视频 → 音频 → 成片 .mp4),120+ 个工具,全部走本服务器。',
+        '',
+        '★第一步永远是判「客户手上有什么材料」——它决定入口,选错入口的返工都是真扣费(全表与要点:get_capabilities_guide):',
+        entry,
+        '',
+        '产线顺序(不跳步):create_drama(建剧即设好 setting_brief/画幅/video_engine/image_model/一致性锚,全免费) → set_script → rewrite_script → ★review_script → extract_assets → quote/generate_storyboards → ★review_storyboards → 定妆图+设定图 / 世界观图 / 动作模板 / 色彩脚本 → run_precheck → quote/generate_frames → ★review_frames → quote/generate_videos → 音频 → compose_episode → get_final_cut。用 get_pipeline_status 查进度。',
+        '三道免费硬闸(跳过 → 400):review_script(extract_assets/分镜前)· review_storyboards(出图前)· review_frames(出视频前);review_token 随下游收费工具传,findings 逐条原样告诉客户。',
+        '计费纪律:预付费不透支;大额步 quote_* → 把 estimated_points 原样告诉客户 → 客户同意后 generate_*(quote_id),绝不擅自确认;文本步按 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(免费、本地、不联网)。',
+    ].join('\n');
+}

package/dist/tools/guide.js

@@ -0,0 +1,21 @@
+/**
+ * 功能地图工具:get_capabilities_guide。纯本地、不联网、不扣费——数据在 guide-data.ts。
+ * 独立于 produce.ts 注册,好让 openapi 生成器把它列进 x-unmapped-tools(它没有 REST 对应面)。
+ */
+import { z } from 'zod';
+import { buildGuide, GUIDE_SECTIONS, GUIDE_VERSION, HOW_TO_READ } from './guide-data.js';
+export function registerGuideTools(server) {
+    server.tool('get_capabilities_guide', '★功能地图(免费 · 本地 · 不联网 · 不扣费)。**第一次接触本服务器、客户问「你们能做什么 / 该从哪开始」、' +
+        '或不确定客户这种材料该走哪个工具时,先调它**。返回:' +
+        'entry_points(客户手上是小说/成熟剧本/想去外部 AI 改写/成品分镜表/自有素材/声音样本/歌曲/产品/已有成片要改/想自己剪/多语言 → 各走哪些工具、别走哪条路)、' +
+        'pipeline(10 步产线每步的工具、免费还是收费、哪道审查闸)、review_gates(三道免费硬闸规则)、' +
+        'qa_tools(按客户描述的症状选检测工具与修法)、optional_boosts(可选增强及何时做)、billing(报价确认与免费族)、' +
+        'common_requests(客户常见原话 → 该做什么)。传 section 只取一段。' +
+        '★工具描述回答"这个工具做什么",本工具回答"什么情况下该用哪个"——客户交来的是成品分镜表却被 set_script→rewrite_script 改写成散文,就是没先看这张表。', {
+        section: z.enum(GUIDE_SECTIONS).optional().describe('只取某一段;不传返回全部'),
+    }, async ({ section }) => {
+        const guide = buildGuide();
+        const data = section ? { version: GUIDE_VERSION, how_to_read: HOW_TO_READ, [section]: guide[section] } : guide;
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/tools/produce.js

@@ -132,8 +132,11 @@ const WORKFLOW_HINT = '★三档执行策略(别把三档混着问客户):' +
     '★客户想在**别的 AI 平台**改写剧本(常见诉求:第三方模型评估我方改写"改动太大",客户想自己掌控改动幅度):' +
     '先调 get_script_format_spec 拿平台认可的格式契约(markdown 范本 + 可直接转发给外部模型的 external_prompt + 空白骨架),' +
     '把 external_prompt+范本+客户原稿一起交给那个平台;拿回整理稿后**先调 check_script_format 自查**(免费·纯规则·不调模型),' +
-    'errors 清零再用 set_script 灌回原稿位,然后照常 rewrite_script——原稿已是剧本形态,保真路由会自动接管,台词逐句锁定、几乎零改动落库。' +
+    '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_pipeline_status 查进度(按项目类型返回专属步骤)。';
 const ETHNICITY_CODES = [
     'east_asian', 'southeast_asian', 'south_asian', 'central_asian',
@@ -286,11 +289,17 @@ export function registerProduceTools(server, client) {
         script: z.string().min(1).describe('改好的可拍剧本(覆盖 AI 改写稿)'),
     }, async ({ episode_id, script }) => jsonResult(await client.producePut(`/episodes/${episode_id}/rewritten-script`, { script_content: script })));
     // ---------- 外部平台改写的对接面(格式契约 + 回填前自查,都免费) ----------
-    server.tool('get_script_format_spec', '取本平台**认可的剧本格式契约**:markdown 范本全文 + external_prompt(可整段转发给任意外部 AI 的任务提示词) + skeleton(空白骨架)。免费·静态·不扣费。' +
+    server.tool('get_script_format_spec', '取本平台**认可的剧本格式契约**:markdown 范本全文 + external_prompt(可整段转发给任意外部 AI 的任务提示词) + skeleton(带 〈…〉 占位的模板) + filled_example(填好的成品对照)。免费·静态·不扣费。' +
+        '★范本 v2 起把**制作层标注**全写进去了([角色档案] 六段格式/[外貌] 行首标记/[道具]/[SFX][BGM][VFX]/motif/场景头第四段光线/文末元信息)——' +
+        'v1 只写剧情层,外部 AI 因此产不出完整稿、反复过不了自检。转发时**务必把 filled_example 一起给**:LLM 的格式正确率靠可模仿的完整样例,不靠规则条文。' +
         '★什么时候用:客户想自己掌控改写幅度、要拿到别的 AI 平台去改写、或反馈"你们的 AI 把我的剧本改动太大"时。' +
-        '★怎么用(三步):① 本工具取 external_prompt + markdown,连同客户原稿一起交给那个平台;' +
-        '② 拿回整理稿先用 check_script_format 自查,errors 清零;③ 用 set_script 把整理稿灌回**原稿位**,再照常 rewrite_script——' +
-        '原稿已是剧本形态时保真路由自动接管(台词逐句机器锁定、AI 不加戏),改动幅度由客户在外部那一步自己定。' +
+        '★两条出口(先问客户要哪条,这决定外部 AI 要不要写标注):' +
+        '【A 直接采用】外部 AI 产出**含制作层标注**的完整稿 → check_script_format 全绿 → adopt_external_script 直接落为可拍稿,' +
+        '我方 AI 完全不介入、秒级、不计费,客户写的 [角色档案] 原样生效。适合已经把外部 AI 调顺、要求零改动的客户。' +
+        '【B 送 AI 改写】外部 AI 只产出剧情层(**不要写任何标注**) → set_script 灌回原稿位 → rewrite_script 走保真两步补标注。' +
+        '★B 路径下客户自己写的标注**会被 G1 剥掉重写**,等于白写——所以选 B 就要明确告诉外部 AI 别写标注。' +
+        '★怎么用(三步):① 本工具取 external_prompt + filled_example + markdown,连同客户原稿一起交给那个平台;' +
+        '② 拿回整理稿先用 check_script_format 自查,errors 清零;③ 按出口 A 调 adopt_external_script,或按出口 B 调 set_script + rewrite_script。' +
         '★契约内容含:场景头三段格式/地点命名律/环境首句三要素/角色首次出场外貌行/声音行前缀/单行台词长度/禁写运镜与片尾标记,' +
         '以及"台词逐句保留·人物不许丢·动作节拍不许丢·不许加戏"四条保真要求(已写进 external_prompt)。', {
         drama_title: z.string().optional().describe('仅用于范本抬头,不影响格式契约本身'),
@@ -306,9 +315,40 @@ export function registerProduceTools(server, client) {
     });
     server.tool('check_script_format', '**回填前的格式自查**:把一段剧本正文按平台判据跑一遍,逐条返回问题。免费·纯规则·不调模型·不落库·可反复跑。' +
         '★errors = 系统会**无条件拒收**的(空/过短/无场景头/含运镜词/含片尾编辑标记),必须清零再灌;' +
-        'warnings = 默认只告警(strictOnly=true 的那几条在项目开启严格模式后会变成拒收):场过长过短/无声音行/单行台词超上限/场景头缺段/场号跳号。' +
+        'warnings = 默认只告警(strictOnly=true 的那几条在项目开启严格模式后会变成拒收):场过长过短/无声音行/单行台词超上限/场景头缺段/场号跳号/' +
+        '[角色档案] 段数不对/写了档案却缺 [外貌] 行/说话人位混写年龄身份。' +
+        '★placeholder_left(残留 〈…〉 模板占位符)算 **error**:系统闸不查它,但占位符会原样落进正文被当画面内容,比被拒更糟。' +
+        '★场长按**剧情层**字数算([角色档案]/[外貌]/[道具]/[SFX] 等标注行不计入)——写全标注不会把场撑超 120 字,别为了过闸去删标注。' +
         '★典型用法:外部 AI 整理完 → 本工具自查 → 把返回的 message 清单原样发回那个平台让它"只修这些点、其余逐字照抄" → 再查一遍 → 全绿后 set_script。' +
         '★它只查**格式**;台词是否逐句保留、人物有没有丢这类保真判据要等 rewrite_script 时由平台对着原稿判(本工具没有原稿侧输入)。', { content: z.string().min(1).describe('要检查的剧本正文(一次一集,上限 3 万字)') }, async ({ content }) => jsonResult(await client.producePost('/script-format/lint', { content })));
+    server.tool('import_storyboard_table', '【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent。免费。' +
+        '★什么时候用:客户交来的不是剧本而是成品分镜表(逐镜写了秒数/景别/运镜,常见于给电视台/品牌方的样片)。' +
+        '走 set_script→rewrite_script→generate_storyboards 那条路会把这些制作参数当非剧情内容剥掉' +
+        '(生产实测:8 镜 36 秒的表跑完变成 20 镜 109 秒,STYLE 块与数据卡全丢),所以这类客户必须走本工具。' +
+        '★声明格式(每镜一行,字段用 | 或全角 ｜ 分隔):`[镜 001 | 4s | 微距 | 固定]`,' +
+        '也认客户已有的加粗写法 `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(不必让客户重打一遍)。' +
+        '顺序 = 镜号|秒数|景别|运镜|标记;标记 `不切` 表示该镜绝不可再拆、`★` 表示关键镜;' +
+        '运镜的「横移」映射 tracking、「摇」映射 pan(两者在反光面上的倒影行为不同,别混)。' +
+        '`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲黑底卡,不出图不出视频)。' +
+        '★不传 content 时读本集「原始内容」。没有任何逐镜声明会被 400 拒(那是剧本不是分镜表,请走正常拆镜)。' +
+        '★本集已有分镜时返回 409 并告知镜数,确认要替换再带 confirm_replace:true(旧镜转已删除状态、可恢复)。' +
+        '秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。', {
+        episode_id: z.number().int().positive(),
+        content: z.string().optional().describe('分镜表全文;不传则用本集「原始内容」'),
+        confirm_replace: z.boolean().optional().describe('本集已有分镜时必须显式传 true 才替换'),
+    }, async ({ episode_id, content, confirm_replace }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/import`, { ...(content ? { content } : {}), ...(confirm_replace ? { confirm_replace } : {}) })));
+    server.tool('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) 回捞。', {
+        episode_id: z.number().int().positive(),
+        content: z.string().min(1).describe('外部 AI 产出并已通过 check_script_format 的完整剧本正文'),
+    }, async ({ episode_id, content }) => jsonResult(await client.producePost(`/episodes/${episode_id}/script-format/adopt`, { content })));
     // ---------- 提取(角色/场景/道具) ----------
     server.tool('extract_assets', '从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)。后台异步,文本步后付不欠费。' +
         '前置:已 rewrite_script 产出改写稿(新项目强制;人物档案从改写稿提取才与剧本、分镜自洽)。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.52",
-    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → portraits & sheets → storyboards → 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). 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.52 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.54",
+    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → portraits & sheets → storyboards → 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). 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.54 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -2877,7 +2877,7 @@
       "post": {
         "operationId": "extract_assets",
         "summary": "从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)",
-        "description": "从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)。后台异步,文本步后付不欠费。前置:已 rewrite_script 产出改写稿(新项目强制;人物档案从改写稿提取才与剧本、分镜自洽)。★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60 秒当失败判据。\n★【改写稿审查硬闸·免费】本步前必须先调 review_script:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】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);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**三道硬闸(不过会被 400 拒)**:①改写稿产出后 → 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——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱);分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】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(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→★review_frames→videos→generate_tts→compose;★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;资产在分镜后建更省更准(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★分镜后的剧目级资产别漏——尤其 generate_motion_templates(动作模板:从分镜抽取统一全片运动语言,漏了动作会散乱)与 generate_color_script(色彩脚本:统一色调);分镜后、出图前一并做,仍走报价确认。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认香蕉2(Nano Banana 2 = gemini-3.1-flash-image·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认香蕉2;可选 gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0)/gpt-image-2(ChatGPT Image2);generate_frames 可临时覆盖某次。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 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(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);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 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\"),尾帧用 frame_type=last_frame 可批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/色彩脚本/动作模板/场景图/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(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 清零再用 set_script 灌回原稿位,然后照常 rewrite_script——原稿已是剧本形态,保真路由会自动接管,台词逐句锁定、几乎零改动落库。★别把外部整理稿塞进 edit_rewritten_script(未跑过改写会被 400 拒),也别跳过 check_script_format 直接灌——格式不合规的稿子进来照样被闸拦,白跑一轮。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。",
+        "description": "从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)。后台异步,文本步后付不欠费。前置:已 rewrite_script 产出改写稿(新项目强制;人物档案从改写稿提取才与剧本、分镜自洽)。★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60 秒当失败判据。\n★【改写稿审查硬闸·免费】本步前必须先调 review_script:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】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);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**三道硬闸(不过会被 400 拒)**:①改写稿产出后 → 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——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱);分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】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(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→★review_frames→videos→generate_tts→compose;★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;资产在分镜后建更省更准(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★分镜后的剧目级资产别漏——尤其 generate_motion_templates(动作模板:从分镜抽取统一全片运动语言,漏了动作会散乱)与 generate_color_script(色彩脚本:统一色调);分镜后、出图前一并做,仍走报价确认。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认香蕉2(Nano Banana 2 = gemini-3.1-flash-image·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认香蕉2;可选 gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0)/gpt-image-2(ChatGPT Image2);generate_frames 可临时覆盖某次。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 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(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);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 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\"),尾帧用 frame_type=last_frame 可批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/色彩脚本/动作模板/场景图/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(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_pipeline_status 查进度(按项目类型返回专属步骤)。",
         "tags": [
           "episodes"
         ],
@@ -3984,7 +3984,7 @@
       "post": {
         "operationId": "rewrite_script",
         "summary": "AI 改写:把原始剧本改写成可拍稿(读 content → 写 script_content)",
-        "description": "AI 改写:把原始剧本改写成可拍稿(读 content → 写 script_content)。按项目类型自动选改写 agent★保真自动路由:原稿已是剧本形态时自动走两步保真(台词逐句机器锁定、AI 不加戏,剧作缺口进 dramaturgy_suggestions 由客户决定);原稿是小说/大纲则走创作型改写。(广告走 ad 改写;MV 不走标准改写会被拦)。后台异步(分钟级),文本步按 token 后付、不欠费,无需报价。完成后用 get_script 审阅、edit_rewritten_script 改稿。★典型耗时 2~4 分钟(生产实测 ≈169 秒)。**60 秒内查不到结果是正常的,不是失败**——用 get_run_status 判断还在不在跑,别急着重发。★★**本工具是\"从原稿整篇重来\",不是\"再改一版\"**:已有可拍稿时重跑会把当前稿连同已做的所有修正一起覆盖,而且新一版**不保证保留旧版已经改好的地方**(生产三版实测:上一版拆好的长旁白段下一版又合回去、上一版正确的年代服装下一版漂走)。响应里的 overwrites_existing_script=true 就是这个意思。所以**首次改写成功之后,后续所有修改一律用 edit_rewritten_script 点改**——免费、秒级、只动指定的那几场,其余逐字不变,结果确定不抽卡;只有\"要一个完全不同的版本\"才重跑本工具。误重跑后用 get_script(include_previous=1) 取回上一版。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】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);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**三道硬闸(不过会被 400 拒)**:①改写稿产出后 → 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——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱);分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】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(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→★review_frames→videos→generate_tts→compose;★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;资产在分镜后建更省更准(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★分镜后的剧目级资产别漏——尤其 generate_motion_templates(动作模板:从分镜抽取统一全片运动语言,漏了动作会散乱)与 generate_color_script(色彩脚本:统一色调);分镜后、出图前一并做,仍走报价确认。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认香蕉2(Nano Banana 2 = gemini-3.1-flash-image·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认香蕉2;可选 gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0)/gpt-image-2(ChatGPT Image2);generate_frames 可临时覆盖某次。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 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(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);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 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\"),尾帧用 frame_type=last_frame 可批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/色彩脚本/动作模板/场景图/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(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 清零再用 set_script 灌回原稿位,然后照常 rewrite_script——原稿已是剧本形态,保真路由会自动接管,台词逐句锁定、几乎零改动落库。★别把外部整理稿塞进 edit_rewritten_script(未跑过改写会被 400 拒),也别跳过 check_script_format 直接灌——格式不合规的稿子进来照样被闸拦,白跑一轮。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。",
+        "description": "AI 改写:把原始剧本改写成可拍稿(读 content → 写 script_content)。按项目类型自动选改写 agent★保真自动路由:原稿已是剧本形态时自动走两步保真(台词逐句机器锁定、AI 不加戏,剧作缺口进 dramaturgy_suggestions 由客户决定);原稿是小说/大纲则走创作型改写。(广告走 ad 改写;MV 不走标准改写会被拦)。后台异步(分钟级),文本步按 token 后付、不欠费,无需报价。完成后用 get_script 审阅、edit_rewritten_script 改稿。★典型耗时 2~4 分钟(生产实测 ≈169 秒)。**60 秒内查不到结果是正常的,不是失败**——用 get_run_status 判断还在不在跑,别急着重发。★★**本工具是\"从原稿整篇重来\",不是\"再改一版\"**:已有可拍稿时重跑会把当前稿连同已做的所有修正一起覆盖,而且新一版**不保证保留旧版已经改好的地方**(生产三版实测:上一版拆好的长旁白段下一版又合回去、上一版正确的年代服装下一版漂走)。响应里的 overwrites_existing_script=true 就是这个意思。所以**首次改写成功之后,后续所有修改一律用 edit_rewritten_script 点改**——免费、秒级、只动指定的那几场,其余逐字不变,结果确定不抽卡;只有\"要一个完全不同的版本\"才重跑本工具。误重跑后用 get_script(include_previous=1) 取回上一版。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】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);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**三道硬闸(不过会被 400 拒)**:①改写稿产出后 → 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——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱);分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】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(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→★review_frames→videos→generate_tts→compose;★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;资产在分镜后建更省更准(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★分镜后的剧目级资产别漏——尤其 generate_motion_templates(动作模板:从分镜抽取统一全片运动语言,漏了动作会散乱)与 generate_color_script(色彩脚本:统一色调);分镜后、出图前一并做,仍走报价确认。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认香蕉2(Nano Banana 2 = gemini-3.1-flash-image·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认香蕉2;可选 gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0)/gpt-image-2(ChatGPT Image2);generate_frames 可临时覆盖某次。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 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(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);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 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\"),尾帧用 frame_type=last_frame 可批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/色彩脚本/动作模板/场景图/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(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_pipeline_status 查进度(按项目类型返回专属步骤)。",
         "tags": [
           "episodes"
         ],
@@ -4282,7 +4282,7 @@
       "put": {
         "operationId": "set_script",
         "summary": "给某一集设置**原始剧本**(content)",
-        "description": "给某一集设置**原始剧本**(content)。这是 AI 改写的输入,不是最终可拍稿。免费。梗概/大纲/自己写好的成品稿都放这里,设完**必须调 rewrite_script 做 AI 改写**——不能跳过改写直接把稿子贴进 edit_rewritten_script(会被拒)。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】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);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**三道硬闸(不过会被 400 拒)**:①改写稿产出后 → 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——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱);分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】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(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→★review_frames→videos→generate_tts→compose;★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;资产在分镜后建更省更准(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★分镜后的剧目级资产别漏——尤其 generate_motion_templates(动作模板:从分镜抽取统一全片运动语言,漏了动作会散乱)与 generate_color_script(色彩脚本:统一色调);分镜后、出图前一并做,仍走报价确认。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认香蕉2(Nano Banana 2 = gemini-3.1-flash-image·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认香蕉2;可选 gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0)/gpt-image-2(ChatGPT Image2);generate_frames 可临时覆盖某次。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 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(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);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 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\"),尾帧用 frame_type=last_frame 可批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/色彩脚本/动作模板/场景图/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(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 清零再用 set_script 灌回原稿位,然后照常 rewrite_script——原稿已是剧本形态,保真路由会自动接管,台词逐句锁定、几乎零改动落库。★别把外部整理稿塞进 edit_rewritten_script(未跑过改写会被 400 拒),也别跳过 check_script_format 直接灌——格式不合规的稿子进来照样被闸拦,白跑一轮。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。",
+        "description": "给某一集设置**原始剧本**(content)。这是 AI 改写的输入,不是最终可拍稿。免费。梗概/大纲/自己写好的成品稿都放这里,设完**必须调 rewrite_script 做 AI 改写**——不能跳过改写直接把稿子贴进 edit_rewritten_script(会被拒)。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】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);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**三道硬闸(不过会被 400 拒)**:①改写稿产出后 → 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——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱);分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】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(定妆图+设定图·分镜后建只给出场角色出图更省)→assign_voices(分配音色)→frames→★review_frames→videos→generate_tts→compose;★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;资产在分镜后建更省更准(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★分镜后的剧目级资产别漏——尤其 generate_motion_templates(动作模板:从分镜抽取统一全片运动语言,漏了动作会散乱)与 generate_color_script(色彩脚本:统一色调);分镜后、出图前一并做,仍走报价确认。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认香蕉2(Nano Banana 2 = gemini-3.1-flash-image·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认香蕉2;可选 gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0)/gpt-image-2(ChatGPT Image2);generate_frames 可临时覆盖某次。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 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(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);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 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\"),尾帧用 frame_type=last_frame 可批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/色彩脚本/动作模板/场景图/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(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_pipeline_status 查进度(按项目类型返回专属步骤)。",
         "tags": [
           "episodes"
         ],
@@ -4394,6 +4394,73 @@
         }
       }
     },
+    "/episodes/{episode_id}/script-format/adopt": {
+      "post": {
+        "operationId": "adopt_external_script",
+        "summary": "【出口 A】把外部 AI 按范本产出的稿子**直接采用为可拍稿**,我方 AI 完全不介入",
+        "description": "【出口 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) 回捞。",
+        "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": {
+                  "content": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "外部 AI 产出并已通过 check_script_format 的完整剧本正文"
+                  }
+                },
+                "required": [
+                  "content"
+                ]
+              }
+            }
+          }
+        },
+        "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}/sfx": {
       "post": {
         "operationId": "generate_sfx",
@@ -4719,6 +4786,71 @@
         }
       }
     },
+    "/episodes/{episode_id}/storyboards/import": {
+      "post": {
+        "operationId": "import_storyboard_table",
+        "summary": "【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent",
+        "description": "【已有分镜表时用这个】把客户**做完的分镜表**直接建成分镜，跳过改写与拆镜——中间没有任何 agent。免费。★什么时候用:客户交来的不是剧本而是成品分镜表(逐镜写了秒数/景别/运镜,常见于给电视台/品牌方的样片)。走 set_script→rewrite_script→generate_storyboards 那条路会把这些制作参数当非剧情内容剥掉(生产实测:8 镜 36 秒的表跑完变成 20 镜 109 秒,STYLE 块与数据卡全丢),所以这类客户必须走本工具。★声明格式(每镜一行,字段用 | 或全角 ｜ 分隔):`[镜 001 | 4s | 微距 | 固定]`,也认客户已有的加粗写法 `**镜 001 ｜ 4″ ｜ 微距 ｜ 摄影机固定不动**`(不必让客户重打一遍)。顺序 = 镜号|秒数|景别|运镜|标记;标记 `不切` 表示该镜绝不可再拆、`★` 表示关键镜;运镜的「横移」映射 tracking、「摇」映射 pan(两者在反光面上的倒影行为不同,别混)。`[字卡 9s] 行一 | 行二` 会建成卡镜(成片层直接渲黑底卡,不出图不出视频)。★不传 content 时读本集「原始内容」。没有任何逐镜声明会被 400 拒(那是剧本不是分镜表,请走正常拆镜)。★本集已有分镜时返回 409 并告知镜数,确认要替换再带 confirm_replace:true(旧镜转已删除状态、可恢复)。秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。",
+        "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": {
+                  "content": {
+                    "type": "string"
+                  },
+                  "confirm_replace": {
+                    "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}/storyboards/quote": {
       "post": {
         "operationId": "quote_storyboards",
@@ -5567,7 +5699,7 @@
       "post": {
         "operationId": "check_script_format",
         "summary": "**回填前的格式自查**:把一段剧本正文按平台判据跑一遍,逐条返回问题",
-        "description": "**回填前的格式自查**:把一段剧本正文按平台判据跑一遍,逐条返回问题。免费·纯规则·不调模型·不落库·可反复跑。★errors = 系统会**无条件拒收**的(空/过短/无场景头/含运镜词/含片尾编辑标记),必须清零再灌;warnings = 默认只告警(strictOnly=true 的那几条在项目开启严格模式后会变成拒收):场过长过短/无声音行/单行台词超上限/场景头缺段/场号跳号。★典型用法:外部 AI 整理完 → 本工具自查 → 把返回的 message 清单原样发回那个平台让它\"只修这些点、其余逐字照抄\" → 再查一遍 → 全绿后 set_script。★它只查**格式**;台词是否逐句保留、人物有没有丢这类保真判据要等 rewrite_script 时由平台对着原稿判(本工具没有原稿侧输入)。",
+        "description": "**回填前的格式自查**:把一段剧本正文按平台判据跑一遍,逐条返回问题。免费·纯规则·不调模型·不落库·可反复跑。★errors = 系统会**无条件拒收**的(空/过短/无场景头/含运镜词/含片尾编辑标记),必须清零再灌;warnings = 默认只告警(strictOnly=true 的那几条在项目开启严格模式后会变成拒收):场过长过短/无声音行/单行台词超上限/场景头缺段/场号跳号/[角色档案] 段数不对/写了档案却缺 [外貌] 行/说话人位混写年龄身份。★placeholder_left(残留 〈…〉 模板占位符)算 **error**:系统闸不查它,但占位符会原样落进正文被当画面内容,比被拒更糟。★场长按**剧情层**字数算([角色档案]/[外貌]/[道具]/[SFX] 等标注行不计入)——写全标注不会把场撑超 120 字,别为了过闸去删标注。★典型用法:外部 AI 整理完 → 本工具自查 → 把返回的 message 清单原样发回那个平台让它\"只修这些点、其余逐字照抄\" → 再查一遍 → 全绿后 set_script。★它只查**格式**;台词是否逐句保留、人物有没有丢这类保真判据要等 rewrite_script 时由平台对着原稿判(本工具没有原稿侧输入)。",
         "tags": [
           "script-format"
         ],
@@ -5622,8 +5754,8 @@
     "/script-format/spec": {
       "get": {
         "operationId": "get_script_format_spec",
-        "summary": "取本平台**认可的剧本格式契约**:markdown 范本全文 + external_prompt(可整段转发给任意外部 AI 的任务提示词) + skeleton(空白骨架)",
-        "description": "取本平台**认可的剧本格式契约**:markdown 范本全文 + external_prompt(可整段转发给任意外部 AI 的任务提示词) + skeleton(空白骨架)。免费·静态·不扣费。★什么时候用:客户想自己掌控改写幅度、要拿到别的 AI 平台去改写、或反馈\"你们的 AI 把我的剧本改动太大\"时。★怎么用(三步):① 本工具取 external_prompt + markdown,连同客户原稿一起交给那个平台;② 拿回整理稿先用 check_script_format 自查,errors 清零;③ 用 set_script 把整理稿灌回**原稿位**,再照常 rewrite_script——原稿已是剧本形态时保真路由自动接管(台词逐句机器锁定、AI 不加戏),改动幅度由客户在外部那一步自己定。★契约内容含:场景头三段格式/地点命名律/环境首句三要素/角色首次出场外貌行/声音行前缀/单行台词长度/禁写运镜与片尾标记,以及\"台词逐句保留·人物不许丢·动作节拍不许丢·不许加戏\"四条保真要求(已写进 external_prompt)。",
+        "summary": "取本平台**认可的剧本格式契约**:markdown 范本全文 + external_prompt(可整段转发给任意外部 AI 的任务提示词) + skeleton(带 〈…〉 占位的模板) + filled_example(填好的成品对照",
+        "description": "取本平台**认可的剧本格式契约**:markdown 范本全文 + external_prompt(可整段转发给任意外部 AI 的任务提示词) + skeleton(带 〈…〉 占位的模板) + filled_example(填好的成品对照)。免费·静态·不扣费。★范本 v2 起把**制作层标注**全写进去了([角色档案] 六段格式/[外貌] 行首标记/[道具]/[SFX][BGM][VFX]/motif/场景头第四段光线/文末元信息)——v1 只写剧情层,外部 AI 因此产不出完整稿、反复过不了自检。转发时**务必把 filled_example 一起给**:LLM 的格式正确率靠可模仿的完整样例,不靠规则条文。★什么时候用:客户想自己掌控改写幅度、要拿到别的 AI 平台去改写、或反馈\"你们的 AI 把我的剧本改动太大\"时。★两条出口(先问客户要哪条,这决定外部 AI 要不要写标注):【A 直接采用】外部 AI 产出**含制作层标注**的完整稿 → check_script_format 全绿 → adopt_external_script 直接落为可拍稿,我方 AI 完全不介入、秒级、不计费,客户写的 [角色档案] 原样生效。适合已经把外部 AI 调顺、要求零改动的客户。【B 送 AI 改写】外部 AI 只产出剧情层(**不要写任何标注**) → set_script 灌回原稿位 → rewrite_script 走保真两步补标注。★B 路径下客户自己写的标注**会被 G1 剥掉重写**,等于白写——所以选 B 就要明确告诉外部 AI 别写标注。★怎么用(三步):① 本工具取 external_prompt + filled_example + markdown,连同客户原稿一起交给那个平台;② 拿回整理稿先用 check_script_format 自查,errors 清零;③ 按出口 A 调 adopt_external_script,或按出口 B 调 set_script + rewrite_script。★契约内容含:场景头三段格式/地点命名律/环境首句三要素/角色首次出场外貌行/声音行前缀/单行台词长度/禁写运镜与片尾标记,以及\"台词逐句保留·人物不许丢·动作节拍不许丢·不许加戏\"四条保真要求(已写进 external_prompt)。",
         "tags": [
           "script-format"
         ],
@@ -6869,6 +7001,10 @@
     {
       "tool": "save_handoff_toolchain",
       "reason": "dir 必须是绝对路径(收到 \"__S_dir__\")。MCP 进程的工作目录与你的不一定相同,相对路径会写到意料之外的地方。"
+    },
+    {
+      "tool": "get_capabilities_guide",
+      "reason": "handler returned without HTTP call"
     }
   ]
 }

package/package.json

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