@starreel/mcp 0.1.155 → 0.1.157

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，或曾经在用后被换下的 completed），作为本镜在用帧——审计误判时的人工兜底（例如作者契约写明的设定被判成冲突），也可随时换回之前那张。★必须先用 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，绝不按名字自动回填。逐项核对后才由客户决定是否改绑。免费。",

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，或曾经在用后被换下的 completed），作为本镜在用帧——审计误判时的人工兜底（例如作者契约写明的设定被判成冲突），也可随时换回之前那张。' +
+        '★必须先用 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`)));

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.155",
-    "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.155 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.157",
+    "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.157 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -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，或曾经在用后被换下的 completed），作为本镜在用帧——审计误判时的人工兜底（例如作者契约写明的设定被判成冲突），也可随时换回之前那张",
+        "description": "免费：人工采用一张已出完的首帧/尾帧候选（被审计拒掉 rejected、落选 dismissed，或曾经在用后被换下的 completed），作为本镜在用帧——审计误判时的人工兜底（例如作者契约写明的设定被判成冲突），也可随时换回之前那张。★必须先用 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.155",
+  "version": "0.1.157",
   "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.155",
+  "version": "0.1.157",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.155",
+      "version": "0.1.157",
       "transport": {
         "type": "stdio"
       },