@starreel/mcp 0.1.153 → 0.1.156

package/SKILL.md

@@ -1399,6 +1399,7 @@ Full reference: https://api.shortreelai.com/docs/mcp
 - `get_asset_versions(storyboard_id)` 查看历史版本链接、依赖 ID/版本哈希及各自状态。历史没有快照时不从当前绑定伪造依赖。
 - `get_image_dispatch(image_id)` 查一张镜头帧的派发台账：每张参考图的用途、所属角色、是否送达模型，派发前被剔的图在哪一步因什么被剔（如时代预检点名的冲突物件），以及最终发给模型的提示词。画面「不像某角色/少了某道具」时先查它，确认是参考没送到还是模型没画对，再决定改什么；`ledger` 不是 `full` 时缺失项为 `null`，不能当作已送达。
 - `get_frame_candidates(storyboard_id)` 一镜首帧/尾帧的全部候选（含被拒的原图）：`adopted` 标出当前在用那张；`reject.class` 区分要改内容（`needs_content_fix`）、内容问题但可重掷（`content_retryable`）、审核没审成或偶发（`transient`，不是画面不合格）；`audit.warnings` / `expected` / `derived_shot_type` / `boxes` 是审计证据（老候选为 `null`，不代表审过）。镜头反复被拒或客户问「被拒的长什么样」时先逐张看它，再决定改分镜、改参考还是重掷。
+- `adopt_frame_candidate(storyboard_id, generation_id, frame_type)` 客户看过原图、确认是审计误判后，人工采用一张被拒/落选候选作为在用帧（免费）。必须客户明确同意才调，别为了让流程走下去自行放行；已有视频的镜会标待重生，上传/定稿帧要带 `replace_user_frame:true`。
 - `get_stale_portrait_frames(episode_id)` 换定妆图后查影响范围：列出在用帧仍基于角色旧资产的镜头，每条附证据（`ledger-old-asset` / `references-previous-asset` / `portrait-born-after-frame`）。`unknown` 是证据不足，不是已过期，不要据此批量重出。先把 `stale` 清单和 `has_video` 告诉客户，由客户决定重出哪些镜——重出帧和视频都要付费。
 - `get_asset_binding_repair_plan(episode_id)` 只返回缺失场景绑定的候选和依据，`applied=false`。必须逐项审核，不按名字自动回填，也不自动重新生成客户已完成的片子。
 

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

@@ -26,7 +26,8 @@
   "generate_storyboards": "确认后拆镜:后台跑(分钟级),立即返回 status:generating。用 get_storyboards 轮询。★注意:拆镜会**替换整集所有已有分镜**(已调好/已出图的全丢、要重花钱重来)。每镜 5-7 秒是对 AI 出视频优化的**正常**时长,别因「一镜偏长」觉得有问题就重拆。已有分镜时后端会拦,确认重拆才带 confirm_replace=true。★典型耗时 5~10 分钟(生产实测 7~8.4 分钟;**单次 LLM 调用就可能 3~7 分钟**)。**60 秒、甚至 3 分钟内查不到分镜都是正常的**——用 get_run_status 判断是否还在跑。running:true 就继续等;重发一次等于把整集分镜重来一遍。\n★【改写稿审查硬闸·免费】本步前必须先调 review_script:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。★灰度剧还要你(agent)亲自质检:按 review_script 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
   "get_frame_retry_diagnosis": "免费只读查询图片任务的连败诊断、证据任务 ID 和下一步动作。diagnosis_required 时先调用本工具：审计故障重审已有候选，未知原因先复核；不得原样重抽或擅自改剧本。",
   "get_image_dispatch": "免费只读查询一张镜头帧的派发台账：实际用了哪几张参考图、每张的用途与所属角色、是否送达模型、没送达或派发前被剔除的是哪一步因什么被剔（如时代预检点名的冲突物件），以及真正发给图片模型的最终提示词。用于回答「到底用了哪张图、为什么画面不像」；先查清再决定是否重出，别靠猜反复付费重抽。ledger=partial/none 表示该图生成于台账上线前，缺失字段如实为 null。",
-  "get_frame_candidates": "免费只读：一个镜头首帧/尾帧的**全部候选**（出图验收工作台同一份数据）。每张候选给原图地址（被拒的也在，可直接打开看原尺寸）、状态、是否为当前在用（adopted）、拒因 reject（main 主码 / code 具体病因 / details 明细 / class 分流：needs_content_fix=要改内容、content_retryable=内容问题但重掷约 1/3 能成、transient=审核没审成或偶发——不是画面不合格）、审计证据 audit（warnings 中文结论、expected 设计要求、derived_shot_type 画面推出的景别及依据、boxes 主体与身体部位在画面里的位置框；2026-10-07 前的候选无存档为 null，不代表审过）、以及这张图实际用了哪些参考图（references：用途/所属角色/是否送达）。storyboard.tail_endstate 是「尾帧≈首帧」检查结论（current=false 表示结论对应的不是现在这两张图）。★镜头反复被拒、或客户问「被拒的那几张到底什么样 / 为什么不采用」时先调它：逐张看原图和证据，再决定改分镜、改参考还是重掷——别盲目付费重抽。要看某张的最终提示词用 get_image_dispatch(generation_id)。",
+  "get_frame_candidates": "免费只读：一个镜头首帧/尾帧的**全部候选**（出图验收工作台同一份数据）。每张候选给原图地址（被拒的也在，可直接打开看原尺寸）、状态、是否为当前在用（adopted）、拒因 reject（main 主码 / code 具体病因 / details 明细 / class 分流：needs_content_fix=要改内容、content_retryable=内容问题但重掷约 1/3 能成、transient=审核没审成或偶发——不是画面不合格）、审计证据 audit（warnings 中文结论、expected 设计要求、derived_shot_type 画面推出的景别及依据、boxes 主体与身体部位在画面里的位置框；2026-10-07 前的候选无存档为 null，不代表审过）、以及这张图实际用了哪些参考图（references：用途/所属角色/是否送达）。storyboard.tail_endstate 是「尾帧≈首帧」检查结论（current=false 表示结论对应的不是现在这两张图）。★镜头反复被拒、或客户问「被拒的那几张到底什么样 / 为什么不采用」时先调它：逐张看原图和证据，再决定改分镜、改参考还是重掷——别盲目付费重抽。要看某张的最终提示词用 get_image_dispatch(generation_id)。客户看过原图确认画面没问题、是审计误判时，用 adopt_frame_candidate 人工采用（免费）；manual_adoption 非空 = 该候选是人工放行的。",
+  "adopt_frame_candidate": "免费：人工采用一张被审计拒掉（rejected）或落选（dismissed）的首帧/尾帧候选，作为本镜在用帧——审计误判时的人工兜底（例如作者契约写明的设定被判成冲突）。★必须先用 get_frame_candidates 让客户看过原图和拒因、客户明确同意采用后才调；不许为了让流程走下去自行放行。只能采用本镜本帧位、有画面、且不是当前在用的那张；会在该候选上记录人工放行（谁/何时/原拒因），原拒因保留供统计。本镜已有视频的会标成待重生（视频是按旧帧出的，需 regenerate_shot_video）。本镜该帧是客户上传或已定稿的，要带 replace_user_frame:true 才会替换（并解除定稿）。同帧位有在途出图或本镜视频在途时返回 409，等它结束再采用。",
   "get_stale_portrait_frames": "免费只读查询一集里哪些镜头的在用首帧/尾帧，是拿角色已被换掉的旧资产（旧定妆图、旧设定图、旧身体/发型图）画的。换定妆图后用它确认影响范围，再由客户决定重出哪些镜（重出要付费，本工具不改任何数据）。verdict=stale 必附证据：ledger-old-asset（派发台账直接记录用了旧图）/ references-previous-asset（参考图里有该角色以前的旧资产）/ portrait-born-after-frame（当前定妆图晚于该帧诞生）；证不了的标 unknown 并给原因，不当作已过期。has_video=true 表示该镜视频也基于旧帧，重出帧后视频需重生。",
   "get_asset_versions": "只读查询一个镜头的全部图片/视频版本、历史查看链接、依赖 ID 与版本哈希，以及已生成→与当前输入一致→审核有效→已采用四项独立事实。历史缺少依赖记录时显示未知，不补造快照。免费。",
   "get_asset_binding_repair_plan": "只读生成一集历史缺失场景绑定的可审核修复提案。返回原始地点/时段、候选 ID、匹配依据、歧义和 proposed_scene_id；applied=false，绝不按名字自动回填。逐项核对后才由客户决定是否改绑。免费。",
@@ -179,7 +180,7 @@
   "set_era_contract": "设**本集**的时代契约(免费,纯文本写库)。★这是唯一压得过视觉锁的时代机制——古装/民国/仙侠类项目**出图前必设**,不设的话平台只能靠提示词正文堆字对抗,时代错乱(现代物件混进古代画面、仙境被画成写实古代)基本都是这里空着导致的。\n四档怎么选:\n· modern —— 现代/当代都市。不确定时用这档。\n· republican —— 民国、二十世纪早期。\n· historical —— 可考据的历史朝代;这档会要求画面向**考据写实**靠拢。\n· fantasy —— ★仙侠/奇幻/仙境:修真世界、妖灵化形一类**非写实**的东方奇幻。这类项目**别填 historical**——那档要求考据写实,会把发光灵气、悬浮地貌、非人化形一并判成「不合时代」,把画面往写实古代拽。\n★设完不会自动重出已生成的图:要让画面跟上,得再调 generate_frames / regenerate_scene_image。★某一场要破例,用 update_scene 的 era_contract 单独覆写(场级压过集级)。",
   "get_era_contract": "读本集的时代契约现值 + 各场的场级覆写清单 + 四个可选档位的用途说明。免费。改之前先读一次:能看清「集级设的是哪档、哪几场被单独覆写过」,避免整集统一的时代被逐场填乱。★era_contract 为 null 就是**没设**——古装/仙侠项目看到 null 应当先 set_era_contract 再出图。",
   "get_scene_prompt": "读某一场**场景图(空景基板)**的提示词正文,供直接微调后用 update_scene 的 image_prompt 写回。免费。★逐场按需:改哪场读哪场(整集列表 get_scenes 是纯资产视图,不含提示词)。★这是场景表里的正文层;出图时平台还会在其上拼画风块、空景约束与时代锁(不在此处,也无需你写)。回执的 has_image 说明这一场是否已有图。",
-  "quote_scene_lighting_ref": "给某个场景补一张打光参考图的报价(免费,不出图)。打光参考图=只复现该场景光线的中性人脸特写,近景/特写镜看不到场景图时靠它统一光线。场景缺它时(例如上传了新场景图后)才需要补;有宽景镜但还没出首帧的场景不必补(宽景镜出帧时平台自动派生)。不够格时返回 400 并说明原因。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
+  "quote_scene_lighting_ref": "给某个场景补一张打光参考图的报价(免费,不出图)。打光参考图=只复现该场景光线、不当身份参考的图:新版是无身份光照探针(中性灰背景上两只哑光标定球,不含任何人物),平台尚未对该剧切换新版时仍是中性人脸特写;报价返回的 note 会说明本剧这次出的是哪一种。近景/特写镜看不到场景图时靠它统一光线。场景缺它时(例如上传了新场景图后)才需要补;有宽景镜但还没出首帧的场景不必补(宽景镜出帧时平台自动派生)。不够格时返回 400 并说明原因。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
   "generate_scene_lighting_ref": "按报价补这一场的打光参考图(后台出图,按用量扣点)。完成后 get_scenes 里该场景的打光参考图字段会有值。",
   "quote_regenerate_scene_image": "单场景图重出的报价(免费,不出图)。返回 estimated_points(上界)/typical_points,含场景图一张,以及换图后平台会不会自动派生一张打光参考图(lighting_ref.will_generate,给近景镜统一光线,同样扣点)。拿到 quote_id 后传给 regenerate_scene_image。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
   "regenerate_scene_image": "按当前提示词重出**这一场**的场景图(改完 image_prompt 让画面跟上)。图片步,按用量后付不欠费。★先调 quote_regenerate_scene_image 拿报价、把点数告诉客户,再带 quote_id 调本工具:换了场景图后,没有可用宽景镜首帧的场景平台会自动再出一张打光参考图(另扣一张图的点数),报价里已含。★覆盖式:出好后本场旧图被换掉(要留档先 get_scene_prompt/资产列表拿旧图 URL)。★已生成的镜头帧不会自动跟着重出——它们仍拿旧场景图当背景锚,要跟上得逐镜重出。★与 generate_scene_images 的区别:那个是整剧批量、只补**缺图**的场景,已有图的一律跳过;这个是单场景强制重出。客户自己上传过的场景图也会被覆盖,先确认是不是要保留。★episode_id 通常不必传(平台按场景归属、再按引用它的分镜自动推导)。只有回执报「本场景被多集分镜共用」时才需要点名:那说明同一地点跨集复用,平台不猜该按哪一集的时代/世界观出图——猜错就是画面年代静默错掉。\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。",

package/dist/tools/produce.js

@@ -585,7 +585,18 @@ export function registerProduceTools(server, client) {
         '拒因 reject（main 主码 / code 具体病因 / details 明细 / class 分流：needs_content_fix=要改内容、content_retryable=内容问题但重掷约 1/3 能成、transient=审核没审成或偶发——不是画面不合格）、' +
         '审计证据 audit（warnings 中文结论、expected 设计要求、derived_shot_type 画面推出的景别及依据、boxes 主体与身体部位在画面里的位置框；2026-10-07 前的候选无存档为 null，不代表审过）、' +
         '以及这张图实际用了哪些参考图（references：用途/所属角色/是否送达）。storyboard.tail_endstate 是「尾帧≈首帧」检查结论（current=false 表示结论对应的不是现在这两张图）。' +
-        '★镜头反复被拒、或客户问「被拒的那几张到底什么样 / 为什么不采用」时先调它：逐张看原图和证据，再决定改分镜、改参考还是重掷——别盲目付费重抽。要看某张的最终提示词用 get_image_dispatch(generation_id)。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/frame-workbench`)));
+        '★镜头反复被拒、或客户问「被拒的那几张到底什么样 / 为什么不采用」时先调它：逐张看原图和证据，再决定改分镜、改参考还是重掷——别盲目付费重抽。要看某张的最终提示词用 get_image_dispatch(generation_id)。' +
+        '客户看过原图确认画面没问题、是审计误判时，用 adopt_frame_candidate 人工采用（免费）；manual_adoption 非空 = 该候选是人工放行的。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/frame-workbench`)));
+    server.tool('adopt_frame_candidate', '免费：人工采用一张被审计拒掉（rejected）或落选（dismissed）的首帧/尾帧候选，作为本镜在用帧——审计误判时的人工兜底（例如作者契约写明的设定被判成冲突）。' +
+        '★必须先用 get_frame_candidates 让客户看过原图和拒因、客户明确同意采用后才调；不许为了让流程走下去自行放行。' +
+        '只能采用本镜本帧位、有画面、且不是当前在用的那张；会在该候选上记录人工放行（谁/何时/原拒因），原拒因保留供统计。' +
+        '本镜已有视频的会标成待重生（视频是按旧帧出的，需 regenerate_shot_video）。本镜该帧是客户上传或已定稿的，要带 replace_user_frame:true 才会替换（并解除定稿）。' +
+        '同帧位有在途出图或本镜视频在途时返回 409，等它结束再采用。', {
+        storyboard_id: z.number().int().positive(),
+        generation_id: z.number().int().positive().describe('get_frame_candidates 返回的候选 generation_id'),
+        frame_type: z.enum(['first_frame', 'last_frame']),
+        replace_user_frame: z.boolean().optional().describe('本镜该帧是上传/定稿帧时，确认替换才传 true'),
+    }, async ({ storyboard_id, ...body }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/frame-workbench/adopt`, body)));
     server.tool('get_stale_portrait_frames', '免费只读查询一集里哪些镜头的在用首帧/尾帧，是拿角色已被换掉的旧资产（旧定妆图、旧设定图、旧身体/发型图）画的。换定妆图后用它确认影响范围，再由客户决定重出哪些镜（重出要付费，本工具不改任何数据）。verdict=stale 必附证据：ledger-old-asset（派发台账直接记录用了旧图）/ references-previous-asset（参考图里有该角色以前的旧资产）/ portrait-born-after-frame（当前定妆图晚于该帧诞生）；证不了的标 unknown 并给原因，不当作已过期。has_video=true 表示该镜视频也基于旧帧，重出帧后视频需重生。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/stale-portrait-frames`)));
     server.tool('get_asset_versions', '只读查询一个镜头的全部图片/视频版本、历史查看链接、依赖 ID 与版本哈希，以及已生成→与当前输入一致→审核有效→已采用四项独立事实。历史缺少依赖记录时显示未知，不补造快照。免费。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/asset-versions`)));
     server.tool('get_asset_binding_repair_plan', '只读生成一集历史缺失场景绑定的可审核修复提案。返回原始地点/时段、候选 ID、匹配依据、歧义和 proposed_scene_id；applied=false，绝不按名字自动回填。逐项核对后才由客户决定是否改绑。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/asset-binding-repair-plan`)));
@@ -1962,8 +1973,9 @@ export function registerProduceTools(server, client) {
         '★逐场按需:改哪场读哪场(整集列表 get_scenes 是纯资产视图,不含提示词)。' +
         '★这是场景表里的正文层;出图时平台还会在其上拼画风块、空景约束与时代锁(不在此处,也无需你写)。' +
         '回执的 has_image 说明这一场是否已有图。', { scene_id: z.number().int().positive() }, async ({ scene_id }) => jsonResult(await client.produceGet(`/scenes/${scene_id}/prompt`)));
-    server.tool('quote_scene_lighting_ref', '给某个场景补一张打光参考图的报价(免费,不出图)。打光参考图=只复现该场景光线的中性人脸特写,' +
-        '近景/特写镜看不到场景图时靠它统一光线。场景缺它时(例如上传了新场景图后)才需要补;' +
+    server.tool('quote_scene_lighting_ref', '给某个场景补一张打光参考图的报价(免费,不出图)。打光参考图=只复现该场景光线、不当身份参考的图:' +
+        '新版是无身份光照探针(中性灰背景上两只哑光标定球,不含任何人物),平台尚未对该剧切换新版时仍是中性人脸特写;' +
+        '报价返回的 note 会说明本剧这次出的是哪一种。近景/特写镜看不到场景图时靠它统一光线。场景缺它时(例如上传了新场景图后)才需要补;' +
         '有宽景镜但还没出首帧的场景不必补(宽景镜出帧时平台自动派生)。不够格时返回 400 并说明原因。' + CONFIRM_HINT, { scene_id: z.number().int().positive() }, async ({ scene_id }) => jsonResult(await client.producePost(`/scenes/${scene_id}/lighting-ref/quote`)));
     server.tool('generate_scene_lighting_ref', '按报价补这一场的打光参考图(后台出图,按用量扣点)。完成后 get_scenes 里该场景的打光参考图字段会有值。', { scene_id: z.number().int().positive(), quote_id: z.string().describe('来自 quote_scene_lighting_ref') }, async ({ scene_id, quote_id }) => jsonResult(await client.producePost(`/scenes/${scene_id}/lighting-ref/generate`, { quote_id })));
     server.tool('quote_regenerate_scene_image', '单场景图重出的报价(免费,不出图)。返回 estimated_points(上界)/typical_points,含场景图一张,' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.153",
-    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`). For video, quote == actual charge. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.153 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.156",
+    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`). For video, quote == actual charge. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.156 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -10789,7 +10789,7 @@
       "post": {
         "operationId": "quote_scene_lighting_ref",
         "summary": "给某个场景补一张打光参考图的报价(免费,不出图)",
-        "description": "给某个场景补一张打光参考图的报价(免费,不出图)。打光参考图=只复现该场景光线的中性人脸特写,近景/特写镜看不到场景图时靠它统一光线。场景缺它时(例如上传了新场景图后)才需要补;有宽景镜但还没出首帧的场景不必补(宽景镜出帧时平台自动派生)。不够格时返回 400 并说明原因。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
+        "description": "给某个场景补一张打光参考图的报价(免费,不出图)。打光参考图=只复现该场景光线、不当身份参考的图:新版是无身份光照探针(中性灰背景上两只哑光标定球,不含任何人物),平台尚未对该剧切换新版时仍是中性人脸特写;报价返回的 note 会说明本剧这次出的是哪一种。近景/特写镜看不到场景图时靠它统一光线。场景缺它时(例如上传了新场景图后)才需要补;有宽景镜但还没出首帧的场景不必补(宽景镜出帧时平台自动派生)。不够格时返回 400 并说明原因。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
         "tags": [
           "scenes"
         ],
@@ -12137,7 +12137,7 @@
       "get": {
         "operationId": "get_frame_candidates",
         "summary": "免费只读：一个镜头首帧/尾帧的**全部候选**（出图验收工作台同一份数据）",
-        "description": "免费只读：一个镜头首帧/尾帧的**全部候选**（出图验收工作台同一份数据）。每张候选给原图地址（被拒的也在，可直接打开看原尺寸）、状态、是否为当前在用（adopted）、拒因 reject（main 主码 / code 具体病因 / details 明细 / class 分流：needs_content_fix=要改内容、content_retryable=内容问题但重掷约 1/3 能成、transient=审核没审成或偶发——不是画面不合格）、审计证据 audit（warnings 中文结论、expected 设计要求、derived_shot_type 画面推出的景别及依据、boxes 主体与身体部位在画面里的位置框；2026-10-07 前的候选无存档为 null，不代表审过）、以及这张图实际用了哪些参考图（references：用途/所属角色/是否送达）。storyboard.tail_endstate 是「尾帧≈首帧」检查结论（current=false 表示结论对应的不是现在这两张图）。★镜头反复被拒、或客户问「被拒的那几张到底什么样 / 为什么不采用」时先调它：逐张看原图和证据，再决定改分镜、改参考还是重掷——别盲目付费重抽。要看某张的最终提示词用 get_image_dispatch(generation_id)。",
+        "description": "免费只读：一个镜头首帧/尾帧的**全部候选**（出图验收工作台同一份数据）。每张候选给原图地址（被拒的也在，可直接打开看原尺寸）、状态、是否为当前在用（adopted）、拒因 reject（main 主码 / code 具体病因 / details 明细 / class 分流：needs_content_fix=要改内容、content_retryable=内容问题但重掷约 1/3 能成、transient=审核没审成或偶发——不是画面不合格）、审计证据 audit（warnings 中文结论、expected 设计要求、derived_shot_type 画面推出的景别及依据、boxes 主体与身体部位在画面里的位置框；2026-10-07 前的候选无存档为 null，不代表审过）、以及这张图实际用了哪些参考图（references：用途/所属角色/是否送达）。storyboard.tail_endstate 是「尾帧≈首帧」检查结论（current=false 表示结论对应的不是现在这两张图）。★镜头反复被拒、或客户问「被拒的那几张到底什么样 / 为什么不采用」时先调它：逐张看原图和证据，再决定改分镜、改参考还是重掷——别盲目付费重抽。要看某张的最终提示词用 get_image_dispatch(generation_id)。客户看过原图确认画面没问题、是审计误判时，用 adopt_frame_candidate 人工采用（免费）；manual_adoption 非空 = 该候选是人工放行的。",
         "tags": [
           "storyboards"
         ],
@@ -12180,6 +12180,84 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/frame-workbench/adopt": {
+      "post": {
+        "operationId": "adopt_frame_candidate",
+        "summary": "免费：人工采用一张被审计拒掉（rejected）或落选（dismissed）的首帧/尾帧候选，作为本镜在用帧——审计误判时的人工兜底（例如作者契约写明的设定被判成冲突）",
+        "description": "免费：人工采用一张被审计拒掉（rejected）或落选（dismissed）的首帧/尾帧候选，作为本镜在用帧——审计误判时的人工兜底（例如作者契约写明的设定被判成冲突）。★必须先用 get_frame_candidates 让客户看过原图和拒因、客户明确同意采用后才调；不许为了让流程走下去自行放行。只能采用本镜本帧位、有画面、且不是当前在用的那张；会在该候选上记录人工放行（谁/何时/原拒因），原拒因保留供统计。本镜已有视频的会标成待重生（视频是按旧帧出的，需 regenerate_shot_video）。本镜该帧是客户上传或已定稿的，要带 replace_user_frame:true 才会替换（并解除定稿）。同帧位有在途出图或本镜视频在途时返回 409，等它结束再采用。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "generation_id": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "description": "get_frame_candidates 返回的候选 generation_id"
+                  },
+                  "frame_type": {
+                    "type": "string",
+                    "enum": [
+                      "first_frame",
+                      "last_frame"
+                    ]
+                  },
+                  "replace_user_frame": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "generation_id",
+                  "frame_type"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      }
+    },
     "/storyboards/{storyboard_id}/frame/clear": {
       "post": {
         "operationId": "clear_shot_frame",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.153",
+  "version": "0.1.156",
   "mcpName": "ai.starreel/starreel",
   "description": "StarReel MCP server — drive the AI short-drama production pipeline (script → storyboards → frames → video → final cut) from Claude, Cursor, or any MCP client",
   "license": "MIT",

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "ai.starreel/starreel",
   "description": "Turn a script into a finished, downloadable short-drama episode — via MCP or REST.",
-  "version": "0.1.153",
+  "version": "0.1.156",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.153",
+      "version": "0.1.156",
       "transport": {
         "type": "stdio"
       },