@starreel/mcp 0.1.221 → 0.1.223

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

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

package/dist/tools/guide-data.js

@@ -367,6 +367,7 @@ export const COMMON_REQUESTS = [
     { customer_says: '我有分镜表了,直接出片', do: '先 `get_storyboard_table_spec` 把契约给客户/外部工具,`check_storyboard_table` 自检全绿再 `import_storyboard_table`(默认 auto_complete,告知客户按文本计费),不要走改写;`get_autofill_status` 到 done 后 `review_storyboards` 再出图。' },
     { customer_says: '我的工具能导出表格 / 我想让别的 AI 直接生成结构化数据', do: '`get_bulk_import_spec`(契约 + 模板 + 成品示例给对方)→ `check_bulk_import`(errors 清零)→ `bulk_import_storyboards`;replace 模式先取得客户同意。' },
     { customer_says: '换了定妆图 / 换脸后镜头没变', do: '`set_character_portrait` 响应里的 stale_frames 逐镜 `generate_shot_frame`,再重生视频。' },
+    { customer_says: '同一人物不同年龄建成了几个角色,定妆图脸不像同一个人 / 痣换了边', do: '选定妆图合格的那个当参考:`quote_derive_character_portrait(character_id=目标, reference_character_id=参考, age_stage)` → 客户同意 → `derive_character_portrait` → `get_derived_portrait_candidates` 逐张看 → 客户挑中 `adopt_derived_portrait` → 按 next_step `generate_character_sheet`。派生前先核对目标角色 appearance 写的是该年龄的穿着。' },
     { 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: '`get_storyboards` 看 seam_state:unchained / broken 才要修(unknown 是系统没判、intended 是有意切换,都别动)。还没出视频:整集 `chain_frames`(先 dry_run),单道同景别 `chain_shot_from_prev`(免费)、景别有变化 `quote_chain_shot_from` → `chain_shot_from` mode=reframe。上一镜视频已出好、不想动本镜首帧:`quote_align_prev_shot` → `align_prev_shot`(重生上一镜视频)。改了首帧的镜视频要重生。' },

package/dist/tools/produce.js

@@ -545,6 +545,10 @@ export function registerProduceTools(server, client) {
         '★不传 content 时读本集「原始内容」。没有任何逐镜声明会被 400 拒(那是剧本不是分镜表,请走正常拆镜)。' +
         '★本集已有分镜时返回 409 并告知镜数,确认要替换再带 confirm_replace:true(旧镜转已删除状态、可恢复)。' +
         '秒数/景别缺失的镜照常导入但会在 issues 里列出——系统不替客户猜,猜错一个秒数就是成片时长错。' +
+        '★★先核绑定、再补全:autofill 跑完之后再重导,补全结果作废、要重新付费。拿不准角色/道具/场景能不能按名字绑上时,' +
+        '传 auto_complete:false 导入 → 对照**客户原稿**逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids' +
+        '(回执 props_possibly_unbound 列出画面里像有物件、却一个道具都没绑的镜) → 用 update_shot 补绑 → 确认无误再 quote_autofill / autofill_storyboards。' +
+        '导入后才发现漏绑也用 update_shot 补(prop_ids / character_ids),**不要整集重导**。' +
         '★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段' +
         '(镜头意图/节拍/潜台词/J-L cut/声线等,只填空)并把每镜由平台拼的基础描述扩写成完整出图/视频提示词——客户导完即可出图。' +
         '文本步按 token 后付,**调用前告知客户**;只想导入不补传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 auto_complete.started=true 后' +
@@ -592,6 +596,10 @@ export function registerProduceTools(server, client) {
         '★image_prompt / video_prompt 想自己写就直接写在每镜里,**逐字照用不被覆盖**;没填的镜平台拼基础描述(回执 base_prompts_built 是拼了几镜),导入后可用 get_shot_prompts 读、update_shot 改。' +
         '(frame_visual_contract 是内部帧契约,导入时忽略。)' +
         '★导入后:语速律会抬高装不下台词的镜(回执 speech_duration_raised / speech_duration_overflow)。' +
+        '★★先核绑定、再补全:autofill 跑完之后再重导,补全结果作废、要重新付费。拿不准角色/道具/场景能不能按名字绑上时,' +
+        '传 auto_complete:false 导入 → 对照**客户原稿**逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids' +
+        '(回执 props_possibly_unbound 列出画面里像有物件、却一个道具都没绑的镜) → 用 update_shot 补绑 → 确认无误再 quote_autofill / autofill_storyboards。' +
+        '导入后才发现漏绑也用 update_shot 补(prop_ids / character_ids),**不要整集重导**。' +
         '★导入后**默认自动补全**(auto_complete,跟随剧目「自动补齐辅助资产」开关、默认开):同一后台批次给全镜 AI 填空专业字段(只填空),' +
         '并只给**没填 image_prompt、由平台拼了基础描述**的镜扩写完整出图/视频提示词(客户自己写的绝不覆盖;回执 auto_complete.prompt_shots)。' +
         '文本步按 token 后付,**调用前告知客户**;只想导入传 auto_complete:false(**代价:不会生成构图契约**——可见人数、主体是人物/局部/道具、景别都只能靠文字推断,手部插入镜和画外配音镜容易被当完整人物出图和审核;回执 contract_coverage 列出缺几镜**并给出当前可行的补法,以它的 note 为准**——契约自动补全开着时是调 autofill_storyboards)。回执 started=true 后用 get_autofill_status 轮询到 done **再** review_storyboards。', {
@@ -743,7 +751,7 @@ export function registerProduceTools(server, client) {
         '(presence=on_screen 在画面 / voice_only 只有声音、不进画面)、scene_id、prop_ids、active_wardrobe_id(整镜服装)、' +
         'appearance_wardrobes[{character_id,wardrobe_id}](逐角色服装锚,只列声明了服装的角色)。' +
         '出图注入谁的定妆图/哪张场景图/哪些道具图由这几项决定;角色名对照 get_characters、道具名对照 get_props。' +
-        '改绑用 update_shot 的 character_ids(★全量覆盖,先从这里读现值再改,漏传即解绑)与 character_presence;' +
+        '改绑用 update_shot 的 character_ids(★全量覆盖,先从这里读现值再改,漏传即解绑)与 character_presence;改道具绑定用 update_shot 的 prop_ids(同样全量覆盖,[] 清空);' +
         '改服装用 update_shot 的 active_wardrobe_id / appearance_wardrobes(可覆盖、可传 null 清空);' +
         '改完再读一次本工具核对。character_bindings 缺席 = 这次没读到(不是没绑),空数组才是没绑。' +
         '★启用双边版本审核时，seam_review.status 为 passed/failed/not_checked/stale；stale 是证据过期，不是画面失败，不据此付费重生。continuity_intent 可用 update_shot 明确。' +
@@ -929,6 +937,8 @@ export function registerProduceTools(server, client) {
         ...(storyboard_ids ? { storyboard_ids } : {}),
     })));
     server.tool('autofill_storyboards', '(推荐)AI 一键给全集(或 storyboard_ids 指定的几镜)分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付(按实际调 AI 的镜计费)。' +
+        '★跑之前先确认角色/场景/道具绑定无误(对照客户原稿逐镜核对 get_storyboards 的 character_ids / scene_id / prop_ids)。' +
+        '补全之后发现漏绑用 update_shot 补绑即可,**不要整集重导**——重导会替换分镜、补全结果作废、要重新付费。' +
         '★**先 quote_autofill 报价**(同样的 overwrite / storyboard_ids),把 shots_to_fill 与 estimated_points / typical_points 告诉客户,**客户同意再跑**本工具。' +
         '★跑完用 get_autofill_status 看回执(写了哪些字段各几镜、跳过几镜、还缺几镜契约)告诉客户——补全写的内部字段 get_storyboards 读不到,别让客户以为白扣。' +
         '★拆镜落库时平台已自动补过一轮:只填空模式下已没有空缺的镜(六个叙事文本字段都已有、有台词的镜声音方向也已有,契约阀开时契约也已有)直接跳过,不调 AI、不扣费;overwrite:true 才会整集重跑并逐镜计费。' +
@@ -1430,6 +1440,43 @@ export function registerProduceTools(server, client) {
             throw new Error('file_path 或 image_url 至少提供一个');
         return jsonResult(await client.producePost(`/characters/${character_id}/portrait`, { image_url: url, ...(allow_issues ? { allow_issues: true } : {}) }));
     });
+    server.tool('quote_derive_character_portrait', '定妆图派生的报价(免费,不出图)。以一个角色的定妆图为参考做图生图:保留五官比例、脸型、眼型与面部标记(痣/疤)的位置,' +
+        '只把年龄推演到 age_stage。★典型用途:**同一人物的不同年龄建成了几个独立角色**——批量出定妆图时它们彼此没有身份锚,' +
+        '脸会画成不同的人、痣会换边;这时选其中定妆图合格的那个当参考(reference_character_id),给其余年龄的角色逐个派生。' +
+        '跨角色派生时穿着与发型按**目标角色档案**的外貌(appearance)与服装锁出,不沿用参考图的衣服——派生前先 get_characters 核对目标角色的 appearance 写对了年龄相应的穿着,' +
+        '不对先 update_character 改;不传 reference_character_id = 以目标角色自己的定妆图为参考、只改年龄、不注入服装。' +
+        '计价:每张候选 = 本剧图片模型带 1 张参考图的单价(如 gpt-image-2.5-flare 为 11+18=29 点)× count。' +
+        '拿到 quote_id 后传给 derive_character_portrait。' + CONFIRM_HINT, {
+        character_id: z.number().int().positive().describe('目标角色(要出新定妆图的那个)'),
+        reference_character_id: z.number().int().positive().optional()
+            .describe('参考角色(同剧、已有合格定妆图;通常是同一人物另一年龄的角色)。不传 = 目标角色自己'),
+        age_stage: z.string().describe('目标年龄,如「65」「65岁」「中年」'),
+        count: z.number().int().min(1).max(6).optional().describe('候选张数 1~6,默认 2;每张单独计费'),
+    }, async ({ character_id, reference_character_id, age_stage, count }) => jsonResult(await client.producePost(`/characters/${character_id}/derive-portrait/quote`, {
+        age_stage, ...(reference_character_id ? { reference_character_id } : {}), ...(count ? { count } : {}),
+    })));
+    server.tool('derive_character_portrait', '按报价派生定妆图候选(后台出图,按用量扣点)。只出候选,**不替换**目标角色现有定妆图;' +
+        '返回 image_generation_ids,用 get_derived_portrait_candidates 轮询到 completed 后把候选图给客户看,' +
+        '客户挑中一张再 adopt_derived_portrait 登记。参数一律以报价时为准(只传 quote_id 即可;另传不同参数会 409)。' +
+        '报价后参考角色换了定妆图或剧的图片模型被改 ⇒ 409,重新报价。', {
+        character_id: z.number().int().positive(),
+        quote_id: z.string().describe('来自 quote_derive_character_portrait'),
+    }, async ({ character_id, quote_id }) => jsonResult(await client.producePost(`/characters/${character_id}/derive-portrait`, { quote_id })));
+    server.tool('get_derived_portrait_candidates', '查定妆图派生候选的进度与图片(免费)。返回每张 {id,status,image_url,error_msg};pending/processing 是还在出,别重复派生(重复扣费)。' +
+        '全部 completed 后**亲自逐张看图**:是不是参考角色同一个人(五官、面部标记位置)、年龄对不对、穿着是否符合目标角色档案,把候选给客户挑。', {
+        character_id: z.number().int().positive(),
+        image_generation_ids: z.array(z.number().int().positive()).min(1).describe('derive_character_portrait 返回的 image_generation_ids'),
+    }, async ({ character_id, image_generation_ids }) => jsonResult(await client.produceGet(`/characters/${character_id}/derive-portrait/candidates?ids=${image_generation_ids.join(',')}`)));
+    server.tool('adopt_derived_portrait', '把客户选中的派生候选登记为目标角色的定妆图(免费登记;内容检查是一次小额视觉审核,按用量后付)。' +
+        '效果同 set_character_portrait:之后 AI 重生默认不覆盖;原设定图/多角度头像/全身参考失效且**不会自动重出**——' +
+        '登记后按响应里的 next_step 先 generate_character_sheet(character_id) 重出设定图;响应里的 stale_frames 是首帧还用着旧定妆图的镜,' +
+        '要用 quote_shot_frame + generate_shot_frame 逐镜重生。内容检查不合规返回 422 不登记,把问题原样告诉客户,客户坚持才带 allow_issues:true。' + ASSET_QC_HINT, {
+        character_id: z.number().int().positive(),
+        image_generation_id: z.number().int().positive().describe('get_derived_portrait_candidates 里客户选中的那张 id'),
+        allow_issues: z.boolean().optional().describe('内容检查报了问题、客户看过后仍明确坚持用这张图时才传 true'),
+    }, async ({ character_id, image_generation_id, allow_issues }) => jsonResult(await client.producePost(`/characters/${character_id}/derive-portrait/adopt`, {
+        image_generation_id, ...(allow_issues ? { allow_issues: true } : {}),
+    })));
     server.tool('upload_shot_frame', '用**客户自有图片**作为某镜的首帧(first_frame)或尾帧(last_frame)。尾帧可选——仅在想固定某镜结尾画面(大运镜/揭示镜)时传;常规只需首帧。会把该镜已有视频标为过期待重生。自动上传+登记。免费。' +
         '⚠️ 只用于客户自己提供的素材，或**本镜平台候选的局部修补**（recovery_options 的 upload_fixed：在 get_frame_candidates 给的原图上裁切/调色/修小瑕疵，客户确认后上传）。' +
         '想「重画某一镜」请用 generate_shot_frame 让平台重生——外部工具从头生成的图不带本片的身份锚与画风锚,贴进来人物/服装/画风会漂。', {
@@ -1719,7 +1766,7 @@ export function registerProduceTools(server, client) {
         const suffix = qs.toString() ? `?${qs.toString()}` : '';
         return jsonResult(await client.produceGet(`/episodes/${episode_id}/dialogue-coverage${suffix}`));
     });
-    server.tool('update_shot', '逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、镜间转场(transition_type / transition_duration_ms)、角色绑定(character_ids)、画外音标记(character_presence)与服装绑定(active_wardrobe_id / appearance_wardrobes)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。' +
+    server.tool('update_shot', '逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、镜间转场(transition_type / transition_duration_ms)、角色绑定(character_ids)、道具绑定(prop_ids)、画外音标记(character_presence)与服装绑定(active_wardrobe_id / appearance_wardrobes)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。' +
         '**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);' +
         '改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes)。' +
         '★★【换衣服改这里,不是改文字】出图穿什么由**服装绑定**决定:单人镜用 active_wardrobe_id(整镜一件),' +
@@ -1744,6 +1791,11 @@ export function registerProduceTools(server, client) {
         continuity_intent: z.enum(['continuous_action', 'shot_change', 'insert_detail', 'jump_cut']).optional().describe('本镜相对上镜的剪辑意图：连续动作、换景别、插入细节、有意跳切。改变后旧双边审核失效；不自动生成或补审。'),
         character_ids: z.array(z.number().int().positive()).optional()
             .describe('本镜出场角色 ID 列表(★全量覆盖式,非增量,漏传的角色会被解绑)。决定出图时注入哪些角色的定妆图/设定图——非人角色(动物/生物)也必须绑定,否则形象会漂移。id 必须来自当前集已关联角色'),
+        prop_ids: z.array(z.number().int().positive()).max(8).optional()
+            .describe('本镜绑定的道具 ID 列表(★全量覆盖式,非增量,漏传的道具会被解绑;[] = 清空)。决定出图时注入哪些道具的道具图——' +
+            '导入后发现某镜漏绑道具就用这里补,不用整集重导。先用 get_storyboards 读本镜现值 prop_ids、在它基础上增删再整体传回;道具 ID 用 get_props 查。' +
+            '每个 id 必须是本剧未删除的道具,每镜最多 8 个,否则 400 且本请求一个字段都不写。' +
+            '★改完不会自动重出:已有首帧/尾帧/视频里没有新道具,回执带 prop_ids_note 时按它走(先 review_storyboards 复审,再重出本镜首帧,首帧换了视频会标过期再重生视频,都先报价)'),
         character_presence: z.array(z.object({
             character_id: z.number().int().positive(),
             presence: z.enum(['on_screen', 'voice_only']),