@starreel/mcp 0.1.113 → 0.1.115

package/SKILL.md

@@ -1166,7 +1166,9 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
 - **Edit**: `edit_video_shot`, `regenerate_shot_video`, `split_shot`,
   `trim_shot`, `rerender_episode`. One generation per shot at a time: a **409 with
   `in_flight_generation_id`** means that shot is still generating from *different*
-  input (another prompt, an edit, or a prompt you changed since) — nothing was
+  input (another prompt, an edit, a prompt or shot you changed since, a first/last frame
+  regenerated, uploaded or added since, or different frames / references / engine in this
+  request — so it can happen even when the prompt is unchanged) — nothing was
   submitted or charged and the quote is spent; wait for that generation, look at it,
   then quote and retry. A success carrying `reused_in_flight: true` means the same
   input was already generating — follow that generation, don't send it again.
@@ -1184,7 +1186,7 @@ Full reference: https://api.shortreelai.com/docs/mcp
 ### 资产引用与版本有效性
 
 - `get_storyboards.asset_versions` 对首帧、尾帧和视频分别返回四项事实：`generated`（已生成）、`input_consistent`（与当前输入一致）、`review_valid`（审核有效）、`adopted`（已采用）。`null` 表示证据不足，不能当作 true。
-- `ready` 和生成数量只表示产物存在；当前有效数量使用 `get_pipeline_status.asset_versions_summary.*.current_effective`。换帧后旧视频仍可查看，但失效版本不能混入当前有效汇总。
+- `ready` 和生成数量只表示产物存在；当前有效数量使用 `get_pipeline_status.asset_versions_summary.*.current_effective`。出图、出视频两步的 `status=done` 同样只表示已生成，旁边的 `validity` 拆出当前有效、生成后输入已变（`changed_by` 给出是哪类依赖变了）、无法判断、未审核、审核未过；`validity.note` 非空时先告知客户，再决定重出哪些镜，不要因输入变更就整集重出。换帧后旧视频仍可查看，但失效版本不能混入当前有效汇总。
 - `get_asset_versions(storyboard_id)` 查看历史版本链接、依赖 ID/版本哈希及各自状态。历史没有快照时不从当前绑定伪造依赖。
 - `get_image_dispatch(image_id)` 查一张镜头帧的派发台账：每张参考图的用途、所属角色、是否送达模型，派发前被剔的图在哪一步因什么被剔（如时代预检点名的冲突物件），以及最终发给模型的提示词。画面「不像某角色/少了某道具」时先查它，确认是参考没送到还是模型没画对，再决定改什么；`ledger` 不是 `full` 时缺失项为 `null`，不能当作已送达。
 - `get_stale_portrait_frames(episode_id)` 换定妆图后查影响范围：列出在用帧仍基于角色旧资产的镜头，每条附证据（`ledger-old-asset` / `references-previous-asset` / `portrait-born-after-frame`）。`unknown` 是证据不足，不是已过期，不要据此批量重出。先把 `stale` 清单和 `has_video` 告诉客户，由客户决定重出哪些镜——重出帧和视频都要付费。

package/dist/tools/produce.js

@@ -487,6 +487,7 @@ export function registerProduceTools(server, client) {
     server.tool('get_pipeline_status', '查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 ' +
         'done/partial/pending/not_required)。照它按序推进、不跳步。免费。' +
         'asset_versions_summary 将 generated、input_consistent、review_valid、adopted 和 current_effective 分开计数；不能把 generate_videos.completed 当当前有效数量。' +
+        '★generate_images / generate_videos 的 status=done 只表示「已生成」，不代表可交付：看同一步的 validity（current_effective 当前有效 / input_changed 生成后输入已变，changed_by 列出是剧级设定、镜头本身还是哪个角色变了 / input_unknown / unreviewed / review_failed），validity.note 不为空时先把它告诉客户。输入变了不一定影响画面，别据此整集重出（付费），先用 get_asset_versions 逐镜看原因。' +
         '★not_required=当前模式不需要该步(如原声剧的 TTS 三步、关配乐的 generate_bgm),不是没做完,别去补做。' +
         '图片/视频分母已剔除卡镜(shots_not_applicable);merge_episode.bgm_stale=true 表示配乐晚于成片,重新 compose_episode 即可。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/pipeline-status`)));
     // ---------- 角色定妆图(一致性锚) ----------
@@ -1194,9 +1195,11 @@ export function registerProduceTools(server, client) {
     server.tool('regenerate_shot_video', '确认后重生某镜视频(可选新 prompt)。' +
         '\n★收到 **409「本镜是用户上传的实拍素材」** = 该镜被 upload_shot_footage 登记成实拍素材镜,不是模型问题,换引擎无用;' +
         '要用 AI 视频覆盖它就带 replace_user_footage=true,要保留素材就别重生。' +
-        '\n★收到 **409 + `in_flight_generation_id`** = 这一镜还有一条生成没跑完,而且它不是按这次的提示词发起的' +
-        '(你带了新 prompt / 之后用 update_shot 改过该镜 prompt / 在途的是一次编辑)。这次重生没提交、没扣费,quote 已作废。' +
-        '先等在途那条完成、看过结果,再重新 quote 并重生——否则拿到的视频是旧提示词出的,会误以为新提示词没效果。' +
+        '\n★收到 **409 + `in_flight_generation_id`** = 这一镜还有一条生成没跑完,而且它不是按这次的内容发起的' +
+        '(你带了新 prompt / 之后用 update_shot 改过该镜 / 之后换过该镜的首帧或尾帧——重出、上传、补出尾帧都算 / ' +
+        '这次带的帧、参考素材或引擎等参数与那次不同 / 在途的是一次编辑)。prompt 没变也可能是这个 409。' +
+        '这次重生没提交、没扣费,quote 已作废。' +
+        '先等在途那条完成、看过结果,再重新 quote 并重生——否则拿到的视频是旧内容(旧提示词或旧首尾帧)出的,会误以为改动没效果。' +
         '\n★成功但返回里带 **`reused_in_flight: true`** = 同样的内容已经在生成(重发/双击/批量出视频已派发),' +
         '这次没有新建、没有新扣费,返回的就是在途那一条,看它的进度即可,不必再发。' +
         CONFIRM_HINT, {

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.113",
-    "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.113 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.115",
+    "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.115 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -5485,7 +5485,7 @@
       "get": {
         "operationId": "get_pipeline_status",
         "summary": "查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 done/partial/pending/not_required)",
-        "description": "查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 done/partial/pending/not_required)。照它按序推进、不跳步。免费。asset_versions_summary 将 generated、input_consistent、review_valid、adopted 和 current_effective 分开计数；不能把 generate_videos.completed 当当前有效数量。★not_required=当前模式不需要该步(如原声剧的 TTS 三步、关配乐的 generate_bgm),不是没做完,别去补做。图片/视频分母已剔除卡镜(shots_not_applicable);merge_episode.bgm_stale=true 表示配乐晚于成片,重新 compose_episode 即可。",
+        "description": "查某一集完整工作流的进度(script_rewrite/提取/分镜/语音/出图/出视频/合成/配乐/终拼…各步 done/partial/pending/not_required)。照它按序推进、不跳步。免费。asset_versions_summary 将 generated、input_consistent、review_valid、adopted 和 current_effective 分开计数；不能把 generate_videos.completed 当当前有效数量。★generate_images / generate_videos 的 status=done 只表示「已生成」，不代表可交付：看同一步的 validity（current_effective 当前有效 / input_changed 生成后输入已变，changed_by 列出是剧级设定、镜头本身还是哪个角色变了 / input_unknown / unreviewed / review_failed），validity.note 不为空时先把它告诉客户。输入变了不一定影响画面，别据此整集重出（付费），先用 get_asset_versions 逐镜看原因。★not_required=当前模式不需要该步(如原声剧的 TTS 三步、关配乐的 generate_bgm),不是没做完,别去补做。图片/视频分母已剔除卡镜(shots_not_applicable);merge_episode.bgm_stale=true 表示配乐晚于成片,重新 compose_episode 即可。",
         "tags": [
           "episodes"
         ],
@@ -10844,7 +10844,7 @@
       "post": {
         "operationId": "regenerate_shot_video",
         "summary": "确认后重生某镜视频(可选新 prompt)",
-        "description": "确认后重生某镜视频(可选新 prompt)。\n★收到 **409「本镜是用户上传的实拍素材」** = 该镜被 upload_shot_footage 登记成实拍素材镜,不是模型问题,换引擎无用;要用 AI 视频覆盖它就带 replace_user_footage=true,要保留素材就别重生。\n★收到 **409 + `in_flight_generation_id`** = 这一镜还有一条生成没跑完,而且它不是按这次的提示词发起的(你带了新 prompt / 之后用 update_shot 改过该镜 prompt / 在途的是一次编辑)。这次重生没提交、没扣费,quote 已作废。先等在途那条完成、看过结果,再重新 quote 并重生——否则拿到的视频是旧提示词出的,会误以为新提示词没效果。\n★成功但返回里带 **`reused_in_flight: true`** = 同样的内容已经在生成(重发/双击/批量出视频已派发),这次没有新建、没有新扣费,返回的就是在途那一条,看它的进度即可,不必再发。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
+        "description": "确认后重生某镜视频(可选新 prompt)。\n★收到 **409「本镜是用户上传的实拍素材」** = 该镜被 upload_shot_footage 登记成实拍素材镜,不是模型问题,换引擎无用;要用 AI 视频覆盖它就带 replace_user_footage=true,要保留素材就别重生。\n★收到 **409 + `in_flight_generation_id`** = 这一镜还有一条生成没跑完,而且它不是按这次的内容发起的(你带了新 prompt / 之后用 update_shot 改过该镜 / 之后换过该镜的首帧或尾帧——重出、上传、补出尾帧都算 / 这次带的帧、参考素材或引擎等参数与那次不同 / 在途的是一次编辑)。prompt 没变也可能是这个 409。这次重生没提交、没扣费,quote 已作废。先等在途那条完成、看过结果,再重新 quote 并重生——否则拿到的视频是旧内容(旧提示词或旧首尾帧)出的,会误以为改动没效果。\n★成功但返回里带 **`reused_in_flight: true`** = 同样的内容已经在生成(重发/双击/批量出视频已派发),这次没有新建、没有新扣费,返回的就是在途那一条,看它的进度即可,不必再发。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
         "tags": [
           "storyboards"
         ],

package/package.json

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