@starreel/mcp 0.1.217 → 0.1.219

package/dist/tools/guide-data.js

@@ -546,7 +546,7 @@ export const MODEL_GUIDE = {
     video_engines: [
         {
             id: 'seedance-2.5', name: 'Seedance 2.5', default_for: '动漫/风格化剧;写实真人剧在该题材可用时也默认它', // 视频引擎无全局默认:不传时后端按画风 + 2.5 写实开关兜底盖章(new-drama-video-engine.ts),不查菜单题材可用性
-            price: '720p 约 212 点/秒、1080p 约为 720p 的 2.5 倍(在售 480p/720p/1080p,无 4K;实价以 quote_* 报价为准);单镜 2~30 秒',
+            price: '价格基准:480p/720p/1080p 约 0.45×/1×/2.5×(以本引擎 720p 为 1×,无 4K;实价以 quote_* 报价为准);单镜 2~30 秒',
             strengths: [
                 '指令遵循与人脸细节最强,写实真人剧首选(以菜单当前可用为准)',
                 '能力最全:首尾帧链、场景组、关键帧组(组内每镜都送自己的首帧,只有它支持)、就地编辑含时间区间、延长、参考图锚',
@@ -562,7 +562,7 @@ export const MODEL_GUIDE = {
         },
         {
             id: 'hailuo-3', name: 'MiniMax H3', default_for: '写实真人剧(含未定画风)在 seedance-2.5 写实题材不可用时的默认',
-            price: '720p(=768P)70 点/秒、1080p(=2K)112 点/秒;无独立 480p 档(选了也按 768P 计);单镜 4~15 秒',
+            price: '720p(=768P)约 0.33×、1080p(=2K)约 0.53×(以 seedance-2.5 720p 为 1×,实价以报价为准);无独立 480p 档(选了也按 768P 计);单镜 4~15 秒',
             strengths: [
                 '约 1/3 成本,还能出 2K',
                 '就地编辑保真度高(改色调/改局部时人物服装构图保持得最好),可在 Seedance 剧里单镜借用它做编辑',
@@ -580,7 +580,7 @@ export const MODEL_GUIDE = {
         },
         {
             id: 'wan3.0', name: 'WAN 3.0',
-            price: '480p 42 / 720p 84 / 1080p 168 点/秒;单镜 2~30 秒(2 秒起计费,无 4 秒地板)',
+            price: '480p/720p/1080p 约 0.2×/0.4×/0.8×(以 seedance-2.5 720p 为 1×,实价以报价为准);单镜 2~30 秒(2 秒起计费,无 4 秒地板)',
             strengths: [
                 '约 4 折成本,2~3 秒短镜更省',
                 '快:单镜约 2 分钟,并发好',
@@ -598,7 +598,7 @@ export const MODEL_GUIDE = {
         },
         {
             id: 'wan3.0-prime', name: 'WAN 3.0 Prime(高速版)',
-            price: '480p 63 / 720p 126 / 1080p 252 点/秒(wan3.0 的 1.5 倍)',
+            price: '480p/720p/1080p 约 0.3×/0.6×/1.2×(wan3.0 的 1.5 倍,以 seedance-2.5 720p 为 1×,实价以报价为准)',
             strengths: ['能力同 wan3.0,出片快约一倍(单镜约 1 分钟)'],
             weaknesses: ['同 wan3.0:写实人脸 720p+ 被拒、镜内自剪', '价格是 wan3.0 的 1.5 倍'],
             best_for: '风格化项目赶交付',

package/dist/tools/produce.js

@@ -111,6 +111,14 @@ const ASSET_QC_HINT = '\n★【完成后质检·免费】出完等图落库(轮
     '再按它返回的 agent_qc 亲自逐张看图(像不像档案、是不是同一个人、时代对不对;设定图本身各角度齐不齐、比例与结构对不对;' +
     '道具与场景图放在剧情里合不合理——对照素材 used_in_shots 那几镜),submit_qc_report 提交质检报告;' +
     '出镜头图时把它的 review_token 作为 asset_review_token 传给 generate_frames / generate_shot_frame。';
+/**
+ * 道具图就绪后平台自动跑的两笔小额视觉检查(后台 fire-and-forget,不需要也不该手动再触发)。
+ * 2026-10-26 客户实测:账单里冒出没提示过的检查费,且道具那笔曾被标成「产品画面分析」。
+ */
+const PROP_IMAGE_AUTO_CHECKS_HINT = '\n★【出图后自动检查·按用量后付】道具图落库(AI 出图或上传)后,平台会自动做一次道具外形分析(看图补尺寸提示,账单名「道具外形分析」),' +
+    '灰度阀开时还会自动做一次道具时代审核(结果见 get_props 的 era_audit)。两笔都是小额视觉审核,事先告诉客户;别再手动 audit_prop_era 重复付费。';
+/** 角色外貌 / 道具描述改动后平台自动跑的设定一致性检查(防抖合并,同值保存不触发)。 */
+const SETTING_LINT_AUTO_HINT = '约 5 分钟后会自动做一次设定一致性检查(文本后付,账单名「设定一致性检查」;同一部剧 5 分钟内多次改动合并成一次,同值保存不触发)';
 /** 视频与配音生成工具的「完成后质检」引导。 */
 const VIDEO_QC_HINT = '\n★【完成后质检·免费】出完等它落库(get_storyboards 看 video_status / get_pipeline_status),再调 review_videos 审视频与配音层' +
     '(缺视频 / 旧帧出的视频 / 片尾硬切 / 意外人声 / 配音缺失 / 音色未分配 / 原声声线过期),修完复审;' +
@@ -267,8 +275,8 @@ export const WORKFLOW_HINT = AUTOPILOT_HINT +
     '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:' + MODEL_AVAILABILITY_NOTE + ';菜单里不可用的模型别推荐。①写实真人剧→seedance-2.5(指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·可出2K·但单镜约6分钟);★选定引擎后在 create_drama / update_project_settings 显式传 video_engine(取菜单里该题材可用的那个)——不传时平台只按画风兜底盖章,不保证落在菜单可用的引擎上;' +
-    '②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);' +
+    '【选型决策树】★先调 get_production_menu:' + MODEL_AVAILABILITY_NOTE + ';菜单里不可用的模型别推荐。①写实真人剧→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),成片观感是「一个镜头里画面跳来跳去、切太快」;' +
@@ -281,7 +289,7 @@ export const WORKFLOW_HINT = AUTOPILOT_HINT +
     '⑤★镜长控制(所有引擎通用,WAN 上尤其明显):单镜保持 3~5 秒。镜头越长模型自由发挥空间越大——' +
     '实测一个 16 秒单镜(邻镜都是 3~5 秒)在片内换了 4 次场景、人物中途消失 4 秒后又从画面边缘长出来,' +
     '客户看到的就是「凭空多出一个人」。要长表演请拆成多个短镜再靠帧链衔接,别写 15 秒以上的单镜;' +
-    '【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(要高清交付选 1080p,约 720p 的 2.5 倍)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);' +
+    '【分辨率决策】草稿/迭代期: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**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);' +
@@ -360,11 +368,11 @@ const PROJECT_SETTINGS_FIELDS = {
         'doubao-seedream-5-0-260128(Seedream 5.0)。建剧即定、整剧统一;generate_frames 可临时覆盖某次出图。★各模型实测优劣(一次过率/手部结构/安全拒绝率/画风稳定度)与选型步骤见 get_capabilities_guide(section=model_guide)'),
     // drama 级视频引擎(整剧统一,单镜/批量/场景组/重生全走它;按镜例外入口:quote_videos 的 shot_engines / quote_regenerate_shot_video 的 model / edit_video_shot 的 model)
     video_engine: z.enum(VIDEO_ENGINES).optional().describe('视频引擎(★drama级·整剧统一·AI必须按剧选型主动引导:写实真人剧→seedance-2.5 或降本 hailuo-3(' + MODEL_AVAILABILITY_NOTE + ');风格化/动画/3D卡通/空镜/产品镜→wan3.0(赶交付 wan3.0-prime);写实真人剧绝不选 wan——720p+ 真人脸被厂商审核一致拒):' +
-        'seedance-2.5(动漫/风格化剧默认·写实真人剧在该题材可用时也默认它·全能力:帧链/场景组/就地编辑/延长/参考图锚·720p约212点/秒) / ' +
+        'seedance-2.5(动漫/风格化剧默认·写实真人剧在该题材可用时也默认它·全能力:帧链/场景组/就地编辑/延长/参考图锚·价格基准 720p=1×) / ' +
         '★不传时平台按画风兜底:动漫/风格化→seedance-2.5;写实/未定画风→seedance-2.5 写实开关开着用它,否则 hailuo-3——这只是兜底盖章,不查菜单的题材可用性,所以按 get_production_menu 选定后要显式传。' +
-        'hailuo-3(MiniMax H3:约1/3成本 720p 70点/秒·原生对白与音效·支持2K·单镜约6分钟·支持就地编辑(强保真)与成片续写·关键帧组/时间戳区间暂不可用;编辑/续写输入视频另按秒计费) / ' +
-        'wan3.0(WAN 3.0:约4折成本 720p 84点/秒·原生对白与音效·支持1080P·单次最长30秒·最短2秒计费·支持就地编辑(强语义)与成片续写·关键帧组/时间戳区间暂不可用;★写实真人720p+可能被厂商审核拒绝,风格化/动画剧适用;★★会在单个分镜片内自行换机位硬切(实测11/12镜)→叙事剧慎用,详见选型决策树④) / ' +
-        'wan3.0-prime(WAN 3.0 高速版:能力同wan3.0·出片约2×·费率1.5×=720p 126点/秒;镜内自剪同 wan3.0)。' +
+        'hailuo-3(MiniMax H3:约1/3成本 720p 约0.33×·原生对白与音效·支持2K·单镜约6分钟·支持就地编辑(强保真)与成片续写·关键帧组/时间戳区间暂不可用;编辑/续写输入视频另按秒计费) / ' +
+        'wan3.0(WAN 3.0:约4折成本 720p 约0.4×·原生对白与音效·支持1080P·单次最长30秒·最短2秒计费·支持就地编辑(强语义)与成片续写·关键帧组/时间戳区间暂不可用;★写实真人720p+可能被厂商审核拒绝,风格化/动画剧适用;★★会在单个分镜片内自行换机位硬切(实测11/12镜)→叙事剧慎用,详见选型决策树④) / ' +
+        'wan3.0-prime(WAN 3.0 高速版:能力同wan3.0·出片约2×·费率为 wan3.0 的 1.5×=720p 约0.6×;镜内自剪同 wan3.0)。' +
         '★必须在出视频**前**设置——切换不回溯已生成的镜头,同剧混用引擎会有画风/身份漂移风险。' +
         '只想给个别镜换引擎别改这里:批量出视频用 quote_videos 的 shot_engines,重出单镜用 quote_regenerate_shot_video 的 model(都只作用于那一次)'),
     // 整剧视觉一致性锚(注入所有出图/视频 prompt,决定跨镜一致)
@@ -425,8 +433,8 @@ export function registerProduceTools(server, client) {
         description: z.string().optional(),
         aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('画幅比例(默认 9:16 竖屏短剧)。★drama级锁定:建剧即定、之后所有出图/出视频/成片都用它,别中途改(改了已生成内容画幅不一致、漂移)'),
         video_resolution: z.enum(VIDEO_RESOLUTIONS).optional().describe('视频分辨率(默认 720p;成本随分辨率上升)。按引擎选:' +
-            'seedance-2.5 在售 480p/720p/1080p(720p 212 点/秒,1080p 约其 2.5 倍,无 4K);hailuo-3 选 720p(=768P 70点/秒)或 1080p(=2K 112点/秒),无独立 480p 档;' +
-            'wan3.0/prime 三档全售(42/84/168,prime 63/126/252 点/秒)。草稿迭代用低档,成片交付才上高清'),
+            '倍数以 seedance-2.5 720p 为 1×,实价以 quote_* 报价为准。seedance-2.5 在售 480p/720p/1080p(约 0.45×/1×/2.5×,无 4K);hailuo-3 选 720p(=768P 约0.33×)或 1080p(=2K 约0.53×),无独立 480p 档;' +
+            'wan3.0/prime 三档全售(wan3.0 约 0.2×/0.4×/0.8×,prime 约 0.3×/0.6×/1.2×)。草稿迭代用低档,成片交付才上高清'),
         setting_brief: z
             .string()
             .optional()
@@ -593,7 +601,7 @@ export function registerProduceTools(server, client) {
     }, async ({ episode_id, payload, auto_complete }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/bulk-import`, { payload, ...(typeof auto_complete === 'boolean' ? { auto_complete } : {}) })));
     server.tool('get_autofill_status', '查本集后台补全批次(导入 auto_complete / autofill_storyboards 发起的 AI 一键填空)的进度:{ status: running|done|failed|idle, total, done, ok, fail }。免费。' +
         '★导入带自动补全后必须等 status=done 再 review_storyboards / generate_frames——补全逐镜改写字段,先审查的 review_token 会因内容变化失效。' +
-        '每镜数十秒,整集可能十几分钟;轮询间隔 ≥10 秒,别紧轮。status=failed 或 fail>0 时看 fail 数,少量失败的镜可直接 autofill_storyboards 重跑(只填空,不重复扣已填的)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/autofill-status`)));
+        '每镜数十秒,整集可能十几分钟;轮询间隔 ≥10 秒,别紧轮。status=failed 或 fail>0 时看 fail 数,少量失败的镜可直接 autofill_storyboards 重跑(只填空模式下已补过的镜跳过、不调 AI、不扣费;只有没补过的镜计费)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/autofill-status`)));
     server.tool('adopt_external_script', '【出口 A】把外部 AI 按范本产出的稿子**直接采用为可拍稿**,我方 AI 完全不介入。秒级、不计费。' +
         '★前置硬闸:服务端会先跑一遍格式自检,errors 非空直接 400 并把清单原样返回——先用 check_script_format 改到全绿再调本工具。' +
         'warnings 不拦(与默认宽松模式的 save_script 同尺度)。' +
@@ -612,7 +620,7 @@ export function registerProduceTools(server, client) {
         '★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60 秒当失败判据。' +
         REVIEW_GATE_HINT('review_script', '改写稿') + WORKFLOW_HINT +
         '\n★【完成后质检】提取完用 get_characters / get_scenes / get_props 核对档案(名字、外貌、时代)与客户剧本一致;' +
-        '定妆图/设定图/场景图/道具图出完后由 review_assets 统一审覆盖与质量。', { episode_id: z.number().int().positive(), ...REVIEW_ARGS }, async ({ episode_id, review_token, acknowledge_review, auto_acknowledge }) => jsonResult(await client.producePost(`/episodes/${episode_id}/extract`, { review_token, acknowledge_review, auto_acknowledge })));
+        '定妆图/设定图/场景图/道具图出完后由 review_assets 统一审覆盖与质量。' + PROP_IMAGE_AUTO_CHECKS_HINT, { episode_id: z.number().int().positive(), ...REVIEW_ARGS }, async ({ episode_id, review_token, acknowledge_review, auto_acknowledge }) => jsonResult(await client.producePost(`/episodes/${episode_id}/extract`, { review_token, acknowledge_review, auto_acknowledge })));
     // ---------- 完整工作流进度 ----------
     server.tool('get_pipeline_status', '查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 ' +
         'done/partial/pending/not_required)。照它按序推进、不跳步。免费。' +
@@ -842,8 +850,9 @@ export function registerProduceTools(server, client) {
     server.tool('review_storyboards', '【第②道硬闸·免费】审查分镜:禁区词(会被厂商审核拒、白扣费)、镜头时长分布、相邻构图重复、' +
         '同场景角色站位漂移、情绪曲线峰谷、关键镜标记。★generate_frames 之前必须先跑本工具——' +
         '分镜里的问题一旦整集出图就变成整集废图,单镜修不回来。按 findings.action 用 update_shot/split_shot 修完再复审。' +
-        '★code=forbidden_term 的 finding 带 `terms` 字段(命中的具体词,如「背景音乐」「强光」)与 `shots`(镜号),' +
-        '照着这两个去 update_shot 改掉即可,不用逐字猜。' +
+        '★code=forbidden_term 的 finding 一次列全所有命中(不再只报前几处),带 `hits`:[{shot 镜号, field 字段, term 命中词}],' +
+        'field 是 description / image_prompt / video_prompt / sound_effect 之一;先 get_shot_prompts 读该字段现值,再 update_shot 改掉那个词,不用逐字猜。' +
+        '★要表达用光(逆光/侧光/光线明暗)别写进画面描述或提示词,写进 update_shot 的 lighting 字段——它不在禁区词扫描范围,出视频与出图都读它。' +
         '★禁区词判**否定语义**:写「无背景音乐」「不要配乐」不算违规(那是在遵守约束),不必为此改稿。' +
         '★warnings 里的「动作过载」(action_overload,advisory 不拦):一镜塞了超过时长承载量的独立动作,出视频前用 split_shot 拆开或删动作——成片后靠慢放/叠化补救不了。多人各做一件事或本身连贯的一串可忽略。' + AGENT_QC_HINT, { episode_id: z.number().int().positive(), base_review_token: BASE_REVIEW_ARG }, async ({ episode_id, base_review_token }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/storyboards`, base_review_token ? { base_review_token } : undefined)));
     server.tool('review_frames', '【第③道硬闸·免费】审查镜头图片层:角色身份锚覆盖(缺定妆图的角色在镜头里必漂)、出图失败率、' +
@@ -905,8 +914,19 @@ export function registerProduceTools(server, client) {
     server.tool('review_all', '(推荐·免费)三层一次跑完的整体体检:剧本+分镜+镜头图片。开工前摸底、交付前复查用。' +
         '★它**不发 review_token** —— 进收费步前仍需对应层的 review_script / review_storyboards / review_frames 各跑一次' +
         '(闸认的是「针对当前产出物刚审过」,不是「审过一次」)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/all`)));
-    server.tool('autofill_storyboards', '(推荐)AI 一键给全集分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付。' +
-        '★平台开启契约自动补全时,也会尝试给**没有构图契约**的镜补上契约(是否开启以导入回执 contract_coverage 的 note 为准;可见人数/主体范围/景别,出图与审核都按它判;默认 overwrite:false 时已有契约不动,**overwrite:true 会连已有契约一起重写**)——导入时关了 auto_complete、回执 contract_coverage 的 note 指向本工具的,出图前调一次。本集已有补全在跑时本次**不排队**(防重复点击重复扣费),新导入的镜要等 get_autofill_status 到 done 后再调。', { episode_id: z.number().int().positive(), overwrite: z.boolean().optional().describe('true=覆盖已有字段(默认 false 只填空缺)') }, async ({ episode_id, overwrite }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/autofill`, overwrite ? { overwrite } : {})));
+    server.tool('autofill_storyboards', '(推荐)AI 一键给全集(或 storyboard_ids 指定的几镜)分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付(按实际调 AI 的镜计费)。' +
+        '★拆镜落库时平台已自动补过一轮:只填空模式下已没有空缺的镜(六个叙事文本字段都已有、有台词的镜声音方向也已有,契约阀开时契约也已有)直接跳过,不调 AI、不扣费;overwrite:true 才会整集重跑并逐镜计费。' +
+        '★补全写的是叙事/节奏类内部字段与构图契约,get_storyboards / get_shot_prompts 不返回这些字段,回读看不到变化属正常;它**不改**出图/视频提示词正文。' +
+        '★平台开启契约自动补全时,也会尝试给**没有构图契约**的镜补上契约(是否开启以导入回执 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 再调。', {
+        episode_id: z.number().int().positive(),
+        overwrite: z.boolean().optional().describe('true=覆盖已有字段(默认 false 只填空缺)'),
+        storyboard_ids: z.array(z.number().int().positive()).min(1).max(50).optional()
+            .describe('只补这些镜(本集镜 id,1~50 个),其它镜不调 AI、不扣费;不传 = 整集。含别集的镜 → 400'),
+    }, async ({ episode_id, overwrite, storyboard_ids }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/autofill`, {
+        ...(overwrite ? { overwrite } : {}),
+        ...(storyboard_ids ? { storyboard_ids } : {}),
+    })));
     server.tool('enhance_shot_prompts', '(可选增强·★非必须·有副作用)AI 批量增强全集 image_prompt。★会**改写已有 prompt**(含手调的);且**务必 generate_frames 之前**做——' +
         '出图后再改 prompt 会让图陈旧、要重生浪费钱。非跑通一部片的必需,客户点名再做。后台异步,文本步后付。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/enhance-prompts`)));
     server.tool('complete_ending_motifs', '(可选增强·★非必须·条件性)给结尾段补全缺失的视觉母题(嫁接视觉回响到结尾镜)。' +
@@ -1489,7 +1509,7 @@ export function registerProduceTools(server, client) {
         const image_url = await client.uploadLocalFile(file_path, 'image');
         return jsonResult(await client.producePost(`/scenes/${scene_id}/image`, { image_url, ...(allow_issues ? { allow_issues: true } : {}) }));
     });
-    server.tool('upload_prop_sheet', '用客户自有图片作为某道具的设定图。自动上传+登记。免费。' + ASSET_QC_HINT, { prop_id: z.number().int().positive(), file_path: z.string().describe('本地道具图路径') }, async ({ prop_id, file_path }) => {
+    server.tool('upload_prop_sheet', '用客户自有图片作为某道具的设定图。自动上传+登记。上传本身免费。' + PROP_IMAGE_AUTO_CHECKS_HINT + ASSET_QC_HINT, { prop_id: z.number().int().positive(), file_path: z.string().describe('本地道具图路径') }, async ({ prop_id, file_path }) => {
         const image_url = await client.uploadLocalFile(file_path, 'image');
         return jsonResult(await client.producePost(`/props/${prop_id}/sheet`, { image_url }));
     });
@@ -1730,7 +1750,10 @@ export function registerProduceTools(server, client) {
             '出场数据是旧格式时 409 APPEARANCES_NONCANONICAL(一字不写),单人镜改用 active_wardrobe_id。回执带 appearance_wardrobes(现值)与 appearance_wardrobes_effective:' +
             'false = 已落库但本剧尚未开启逐角色服装读取(灰度),出图暂不按它选——单人镜请改用 active_wardrobe_id'),
         title: z.string().optional().describe('镜头标题'),
-        description: z.string().optional().describe('画面描述'),
+        description: z.string().optional().describe('画面描述(现值用 get_shot_prompts 读)。★用光不要写进这里——写 lighting'),
+        lighting: z.string().optional().describe('本镜用光(如「逆光」「左侧窗光、脸一半在暗处」)。★用光写这里,不要写进画面描述(description)或提示词:' +
+            '那几个字段写光影词会被 review_storyboards 判 forbidden_term 拦下,这一条不在禁区词扫描范围。出视频时作为 [Lighting] 段送达,出图按它匹配场景光照变体。' +
+            '全量覆盖现值,现值用 get_shot_prompts 读;改完不会自动重出图/视频'),
         shot_type: z.string().optional().describe('景别(如 特写/中景/全景/远景)'),
         angle: z.string().optional().describe('机位角度'),
         camera_movement: z.string().optional().describe('运镜(推/拉/摇/移/跟/固定)'),
@@ -1780,6 +1803,7 @@ export function registerProduceTools(server, client) {
         '★回执里的 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 覆盖它。' +
@@ -1792,7 +1816,7 @@ export function registerProduceTools(server, client) {
     server.tool('rerender_episode', '按当前 timeline 重拼成片(改完镜/裁剪后用)。**免费**(纯 ffmpeg+COS),后台异步。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/re-render`)));
     server.tool('replace_shot_dialogue', '换某镜对白音色/声线(转写+克隆重配)。**同步调用**,约 1 分钟返回产物,按用量后付不欠费。要求本镜有原声视频+角色声线定妆音。' +
         '★它也是「这一镜台词没念完/念了别的」最经济的修法:用克隆音重配整句并静音原声段,' +
-        '**不重新生成视频**——按 TTS 档(千字符)计费,比 regenerate_shot_video(720p 212 点/秒)低几个数量级。' +
+        '**不重新生成视频**——按 TTS 档(千字符)计费,比 regenerate_shot_video(按秒计费,720p 每秒上百点)低几个数量级。' +
         '代价:画面口型是按原音演的,换音后可能对不上;口型看不清的镜(背身/远景/画外)几乎无损,大特写慎用。' +
         '★产物自动写回该镜(返回 persisted:true),但写回 ≠ 进成片:' +
         '以 get_dialogue_repair_status 的 productEffective 为准——true 就 rerender_episode 重拼;' +
@@ -2240,7 +2264,8 @@ export function registerProduceTools(server, client) {
         track_id: z.number().int().positive().describe('get_mv_song 返回的 candidates[].track_id'),
     }, async ({ drama_id, track_id }) => jsonResult(await client.producePost(`/dramas/${drama_id}/mv/song/select`, { track_id })));
     // ========== P1 · 资产精修(提取后改设定再出图)==========
-    server.tool('update_character', '改角色设定(名字/外貌/年龄段/族裔/性别/性格/戏份/档案锁定)。改后需重出定妆图/相关图。免费。' +
+    server.tool('update_character', '改角色设定(名字/外貌/年龄段/族裔/性别/性格/戏份/档案锁定)。改后需重出定妆图/相关图。' +
+        '本身免费;改了外貌(appearance 真的变了)' + SETTING_LINT_AUTO_HINT + ';只改 profile_locked 等其它字段不触发。' +
         '★profile_locked=1:客户确认外观后锁定档案,后续 AI 提取不再覆盖外貌/性格/描述——外貌锚着定妆图与人脸锁定,被覆盖=全片换脸;确认满意即锁,要再改先传 0 解锁。', {
         character_id: z.number().int().positive(),
         name: z.string().optional(),
@@ -2254,17 +2279,16 @@ export function registerProduceTools(server, client) {
         profile_locked: z.number().int().min(0).max(1).optional().describe('1=锁定档案(AI 提取不再覆盖外貌/性格/描述,防定妆图换脸);0=解锁'),
     }, async ({ character_id, ...fields }) => jsonResult(await client.producePut(`/characters/${character_id}`, fields)));
     server.tool('delete_character', '删除一个角色(提取误建/合并时用)。免费。', { character_id: z.number().int().positive() }, async ({ character_id }) => jsonResult(await client.produceDelete(`/characters/${character_id}`)));
-    server.tool('update_scene', '改场景设定(名字/描述/地点/时段/氛围),以及**场景图的出图提示词正文**(image_prompt)。免费(纯文本写库)。' +
+    server.tool('update_scene', '改场景设定(地点/时段/物理地点归并键/时代契约),以及**场景图的出图提示词正文**(image_prompt)。免费(纯文本写库)。' +
+        '★场景名就是 location;氛围、描述写进 image_prompt。改 time_of_day 后 import_storyboard_table 按「地点+时段」绑场景就能对上。' +
         '★场景图不满意时,改 image_prompt 才是直接手段——只改地点/时段是让平台重拼,拧不过来;' +
         '改前先用 get_scene_prompt 读现值,改完用 regenerate_scene_image 重出这一场的图。' +
         '★场景图变了不会自动重出已生成的镜头帧:那些帧仍拿旧场景图当背景锚,要跟上得逐镜重出。', {
         scene_id: z.number().int().positive(),
-        name: z.string().optional(),
-        description: z.string().optional(),
-        location: z.string().optional(),
-        physical_location: z.string().optional(),
-        time_of_day: z.string().optional(),
-        mood: z.string().optional(),
+        location: z.string().optional().describe('场景地点(即场景名),如「内景 · 地点」'),
+        physical_location: z.string().min(1).max(120).optional()
+            .describe('物理地点归并键:同一地点的不同写法填同一个键,平台按它认作同一处。与 location 同传时以它为准'),
+        time_of_day: z.string().optional().describe('时段,写入后 get_scene_prompt 的 time 读回同值'),
         image_prompt: z.string().optional()
             .describe('这一场**空景图**的提示词正文(全量覆盖本场现值)。★先 get_scene_prompt 读现值再改;★写空景——这张是场景基板,画面里不该有人物(人物由镜头帧那层注入)。出图时平台会在正文之上再拼画风块、空景约束与时代锁,不必你写'),
         era_contract: z.object({
@@ -2348,17 +2372,18 @@ export function registerProduceTools(server, client) {
     server.tool('delete_scene', '删除一个场景。免费。', { scene_id: z.number().int().positive() }, async ({ scene_id }) => jsonResult(await client.produceDelete(`/scenes/${scene_id}`)));
     server.tool('generate_character_sheet', '给**单个**角色出三视图设定图(镜头一致性根锚,所有镜头帧都会引用;比定妆图更完整)。整集批量用 generate_character_sheets。' +
         '前置:该角色已有定妆图。图片步,按用量后付不欠费。' + ASSET_QC_HINT, { character_id: z.number().int().positive(), episode_id: z.number().int().positive().optional() }, async ({ character_id, episode_id }) => jsonResult(await client.producePost(`/characters/${character_id}/sheet`, episode_id ? { episode_id } : {})));
-    server.tool('generate_prop_sheet', '给道具 AI 出设定图。图片步,按用量后付不欠费。' + ASSET_QC_HINT, { prop_id: z.number().int().positive() }, async ({ prop_id }) => jsonResult(await client.producePost(`/props/${prop_id}/generate-sheet`)));
+    server.tool('generate_prop_sheet', '给道具 AI 出设定图。图片步,按用量后付不欠费。' + PROP_IMAGE_AUTO_CHECKS_HINT + ASSET_QC_HINT, { prop_id: z.number().int().positive() }, async ({ prop_id }) => jsonResult(await client.producePost(`/props/${prop_id}/generate-sheet`)));
     // ========== 剧目级资产:道具库 CRUD + 色彩脚本/动作模板读取 ==========
     server.tool('get_props', '列剧目道具库(每个道具名称/类型/描述/设定图)。★道具库≠广告商品库(add_product/list_products 是带货商品);道具库是剧目道具。免费。' +
         '★每个道具带 era_audit(道具图的时代/形制审核结论,图换过则为 null):form_consistent=false 表示道具图与它的 era_lock 不符,' +
         'conflicting_scopes 列出它被绑定却时代不合的场景/分集(scope 形如 scene:12 / episode:3),violations 点名具体冲突特征。' +
         '有冲突时:先 update_prop 改 era_lock(写清朝代与形制)再 generate_prop_sheet 重出道具图;或者给那些镜换用合适的道具。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/props`)));
     server.tool('audit_prop_era', '重审某个道具图的时代/形制(一次小额视觉审核,按用量后付)。依据该道具的 era_lock,以及它被绑定的各镜所在场景/分集的时代契约。' +
-        '跨时代剧(不同场景属于不同朝代/年代)出完或换完道具图后跑一次;结果同 get_props 里的 era_audit。' +
+        '★出完或换完道具图后平台已自动审一次(灰度阀开时),先等它落库、看 get_props 的 era_audit,别马上手动再审(重复付费)。' +
+        '本工具用于:改了 era_lock 或道具的镜头绑定之后重审,或 era_audit 迟迟为 null(自动审没跑)时补审;结果同 get_props 里的 era_audit。' +
         '道具还没有图、或既没写 era_lock 也没被绑到带时代契约的镜头上时返回 400(没有可比的依据)。' +
         '只有点名了具体冲突特征才判冲突;笼统的「不像那个年代」不算。', { prop_id: z.number().int().positive() }, async ({ prop_id }) => jsonResult(await client.producePost(`/props/${prop_id}/era-audit`, {})));
-    server.tool('create_prop', '往道具库加一个道具。extract_assets 会自动提取道具,这里供手动补建。跨时代剧建道具时就把 era_lock 填上(建完会自动触发出设定图,补填要重出才生效)。免费(建条目;填了 description 会自动触发出设定图、后付)。', {
+    server.tool('create_prop', '往道具库加一个道具。extract_assets 会自动提取道具,这里供手动补建。跨时代剧建道具时就把 era_lock 填上(建完会自动触发出设定图,补填要重出才生效)。本身免费(建条目);填了 description 会自动触发出设定图(后付),填了 description/prompt 还会' + SETTING_LINT_AUTO_HINT + '。' + PROP_IMAGE_AUTO_CHECKS_HINT, {
         drama_id: z.number().int().positive(),
         name: z.string().min(1).describe('道具名'),
         type: z.string().optional().describe('类型(如 武器/信物/家具)'),
@@ -2374,8 +2399,10 @@ export function registerProduceTools(server, client) {
             .describe("道具级时代锁：这件道具属于哪个年代、材质工艺该读作什么年代（跨时代剧必填，否则名字中性的道具年代随机）。'' 清空"),
         episode_id: z.number().int().positive().optional(),
     }, async ({ drama_id, ...fields }) => jsonResult(await client.producePost(`/props`, { drama_id, ...fields })));
-    server.tool('update_prop', '改道具(名称/类型/描述/prompt/尺寸/多视角参考图/时代锁)。跨时代剧务必填 era_lock，否则名字中性的道具年代随机。免费。' +
-        '★改了 era_lock 不会自动重出道具图——要 generate_prop_sheet 重出,重出后若 get_props 的 era_audit 为 null(还没审过新图),用 audit_prop_era 审一次。', {
+    server.tool('update_prop', '改道具(名称/类型/描述/prompt/尺寸/多视角参考图/时代锁)。跨时代剧务必填 era_lock，否则名字中性的道具年代随机。' +
+        '本身免费;改了 description/prompt(真的变了)' + SETTING_LINT_AUTO_HINT + ';道具还没有图时改 description/prompt 会自动出设定图(后付)。' +
+        '★改了 era_lock 不会自动重出道具图——要 generate_prop_sheet 重出;新图落库后平台会自动做道具外形分析,灰度阀开时还会自动做时代审核,' +
+        '等一会儿再看 get_props 的 era_audit,别马上手动 audit_prop_era(会重复付费);只有 era_audit 迟迟为 null(自动审没跑)时才手动审一次。', {
         prop_id: z.number().int().positive(),
         name: z.string().optional(),
         type: z.string().optional(),