@starreel/mcp 0.1.89 → 0.1.91

package/SKILL.md

@@ -659,6 +659,32 @@ the scene (signs, book pages, screens) is not reported. Re-composing cannot remo
 burned-in text; `regenerate_shot_video` the flagged shots. After a non-dry-run scan,
 `compose_episode` lists them as advisory `vendor_burned_text`.
 
+### "同一个角色前后换了衣服" / a character's outfit changes between shots
+
+The image model sometimes draws a character's clothing differently from the
+reference — most often a small figure in a wide shot — even when the reference
+images, the shot text and the wardrobe lock were all correct. Run
+**`scan_wardrobe_consistency`** (one vision call per shot, billed by usage): it
+compares each shot's opening frame and a mid-clip frame with every bound
+character's sheet (or portrait) and reports concrete `differences`. Overall
+night/lamp color cast is not a mismatch. Re-composing cannot fix it: regenerate
+the shot's frame (`generate_shot_frame`), then `regenerate_shot_video`.
+
+### "同一个角色前后嗓音不一样" / a character's voice drifts between shots
+
+On native-audio projects the voice comes from the video vendor, anchored by the
+character's bound voice sample. Two different things look the same to the ear:
+a shot generated **before** the voice was bound (it never had an anchor), and a
+shot whose voice drifted despite the anchor. Check them in this order:
+
+1. `get_pipeline_status` → `native_voice_anchor.stale_shots` lists shots whose
+   final clip was generated without the speaker's current voice anchor
+   (`not_attached` / `anchor_changed`). Regenerate those — no scan needed.
+2. For the rest, `scan_voice_consistency` (free, runs in the background ~10 min
+   per episode) then `get_voice_consistency`: `summary.voice_mismatch` are shots
+   whose voice does not sound like the character's anchor. `uncertain` means the
+   spoken part was too short to judge — not a defect.
+
 ### "话没说完就切" / a line gets cut off mid-word
 
 **By far the most common cause is #2 — the vendor's clip never said the whole
@@ -683,7 +709,11 @@ the mouth isn't readable (back turned, wide, off-screen) that is invisible; on
 sustained close-ups, regenerate instead. Reach for `regenerate_shot_video` when
 the shot is a close-up, or when the picture itself is also wrong.
 `repair_episode_dialogue` runs in the background — poll it with
-`get_dialogue_repair_status`.
+`get_dialogue_repair_status`. If the status carries `aborted`, the batch stopped
+early on an account-level failure (`credits` = out of points; `account_overdue` =
+the platform's upstream vendor account, not yours) and the `remaining` shots never
+ran. Resubmitting unchanged will fail the same way — top up for `credits`; for
+`account_overdue`, tell the user and retry later instead of looping.
 Either way, `compose_episode` afterwards — the final cut still holds the old audio until you do.
 
 Four distinct causes; they need **opposite** fixes, so identify the family first.

package/dist/tools/produce.js

@@ -1159,6 +1159,20 @@ export function registerProduceTools(server, client) {
         + '返回 flagged[{shot, texts, matches_dialogue, frames}] / clean / errors。'
         + 'matches_dialogue=true 表示读出来的字就是本镜台词，基本可确认是厂商字幕；招牌、书页、屏幕等画面里本来就有的字不算。'
         + 'dry_run=true 只报告不写回；否则结果写回，compose_episode 的终拼预检会以 vendor_burned_text 列出这些镜。', { episode_id: z.number().int().positive(), dry_run: z.boolean().optional() }, async ({ episode_id, dry_run }) => jsonResult(await client.producePost(`/episodes/${episode_id}/video-text-scan`, { dry_run: dry_run === true })));
+    server.tool('scan_wardrobe_consistency', '★客户报「同一个角色前后换了衣服 / 衣服颜色款式不对」时跑这个；终拼前也建议跑一次。' +
+        '逐镜把采用的首帧和视频中段一帧，与本镜每个角色的设定图（没有则用定妆图）比对衣服的款式与颜色。' +
+        '常见成因是远景小人物被出图模型画成了别的衣服——即使参考图和提示词都对。夜景/暖光的整体偏色不算不一致。' +
+        '每镜一次视觉审计，**按用量计费**。返回 flagged[{shot, characters:[{name, differences}]}] / clean / errors。' +
+        'dry_run=true 只报告不写回；否则写回，compose_episode 的终拼预检会以 wardrobe_mismatch 列出这些镜。' +
+        '处置：重出该镜首帧（generate_shot_frame）再 regenerate_shot_video；重新拼接去不掉。', { episode_id: z.number().int().positive(), dry_run: z.boolean().optional() }, async ({ episode_id, dry_run }) => jsonResult(await client.producePost(`/episodes/${episode_id}/wardrobe-scan`, { dry_run: dry_run === true })));
+    server.tool('scan_voice_consistency', '★原声剧（视频自带人声）客户报「同一个角色前后嗓音不一样 / 声线漂了」时跑这个。免费（本地推理，不调厂商）。' +
+        '对每个有台词的镜，听厂商生成的人声：台词念没念全，以及声音像不像该角色绑定的声线锚。' +
+        '**异步**：立即返回，后台整集约 10 分钟；同一集同时只跑一条（重复调用返回 started=false）。' +
+        '默认跳过已对当前视频扫过的镜，rescan=true 全部重扫。用 get_voice_consistency 查进度和逐镜结果。', { episode_id: z.number().int().positive(), rescan: z.boolean().optional() }, async ({ episode_id, rescan }) => jsonResult(await client.producePost(`/episodes/${episode_id}/voice-identity-scan`, { rescan: rescan === true })));
+    server.tool('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 重出。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/voice-identity-scan`)));
     server.tool('scan_dialogue_coverage', '★客户报「话没说完就切 / 台词只念了一半」时先跑这个。默认**免费零扣费**(只读已落库的转录审计结果)。'
         + '把该集每个原声镜的视频音轨与台词做词级比对,按族给出结论:'
         + 'truncated(念到一半就停) / off_script(念的大半不是台词:自说自话、重复上一镜、只有环境音) / '
@@ -1260,7 +1274,10 @@ export function registerProduceTools(server, client) {
     })));
     server.tool('get_dialogue_repair_status', '查台词修复的进度(免费)。repair_episode_dialogue 是后台异步串行跑的,用这个轮询。'
         + '\n★这个工具此前**不存在**,而 repair_episode_dialogue 的描述里却写着「进度用 '
-        + 'dialogue-repair-status 查」——第三方照着找会扑空(2026-09-21 由 MCP 覆盖闸抓出)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/dialogue-repair-status`)));
+        + 'dialogue-repair-status 查」——第三方照着找会扑空(2026-09-21 由 MCP 覆盖闸抓出)。'
+        + '\n★返回里带 **aborted** = 上一批因整账户级失败被提前中止(kind=account_overdue 平台上游账户欠费 / '
+        + 'credits 点数不足),remaining 镜未执行。此时**原样重提必然同因失败**:credits 先充值;'
+        + 'account_overdue 不是你的点数问题,停下告知用户稍后再试,别反复重提。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/dialogue-repair-status`)));
     server.tool('get_shot_name_card', '读这一镜的**人物名片**现值(免费):名字、头衔、显示位置那些。'
         + '\n★改之前先读一遍——set_shot_name_card 是**整体覆盖**,不读就改会把没打算动的字段清掉。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/name-card`)));
     server.tool('generate_bgm', '给整集生成/更换 AI 配乐(按情绪弧线)。后台异步,按用量后付不欠费。返回情绪弧线段数与预估耗时;' +
@@ -1488,8 +1505,10 @@ export function registerProduceTools(server, client) {
         aspects: z.array(z.enum(['9:16', '16:9', '1:1', '4:5'])).optional().describe('目标画幅集'),
     }, async ({ episode_id, aspects }) => jsonResult(await client.producePost(`/episodes/${episode_id}/render-multi-aspect`, aspects ? { aspects } : {})));
     // ========== P2 · 口型 / 海报封面 ==========
-    server.tool('lipsync_shot', '给单镜做口型同步(对白与人物嘴型对齐)。按用量后付。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/lipsync`)));
-    server.tool('lipsync_episode', '给整集批量口型同步。后台异步,按用量后付。用 get_lipsync_status 查进度。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/lipsync-batch`)));
+    const LIPSYNC_UNAVAILABLE_HINT = '\n★收到 **503 code=lipsync.unavailable** = 平台当前没有可用的口型服务,本次未提交、未扣费,重试无用;' +
+        '按返回的 alternatives 改走别的路(重生该镜视频 / 定向编辑 / 只换音频——最后一个不改嘴型)。';
+    server.tool('lipsync_shot', '给单镜做口型同步(对白与人物嘴型对齐)。按用量后付。' + LIPSYNC_UNAVAILABLE_HINT, { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/lipsync`)));
+    server.tool('lipsync_episode', '给整集批量口型同步。后台异步,按用量后付。用 get_lipsync_status 查进度。' + LIPSYNC_UNAVAILABLE_HINT, { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/lipsync-batch`)));
     server.tool('get_lipsync_status', '查整集口型同步进度。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/lipsync-status`)));
     server.tool('generate_episode_poster', '给某一集生成海报图。图片步,按用量后付。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/poster`)));
     server.tool('generate_drama_poster', '给整部剧生成海报图(KV)。图片步,按用量后付。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.producePost(`/dramas/${drama_id}/poster`)));

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.89",
-    "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.89 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.91",
+    "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.91 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -3543,7 +3543,7 @@
       "get": {
         "operationId": "get_dialogue_repair_status",
         "summary": "查台词修复的进度(免费)",
-        "description": "查台词修复的进度(免费)。repair_episode_dialogue 是后台异步串行跑的,用这个轮询。\n★这个工具此前**不存在**,而 repair_episode_dialogue 的描述里却写着「进度用 dialogue-repair-status 查」——第三方照着找会扑空(2026-09-21 由 MCP 覆盖闸抓出)。",
+        "description": "查台词修复的进度(免费)。repair_episode_dialogue 是后台异步串行跑的,用这个轮询。\n★这个工具此前**不存在**,而 repair_episode_dialogue 的描述里却写着「进度用 dialogue-repair-status 查」——第三方照着找会扑空(2026-09-21 由 MCP 覆盖闸抓出)。\n★返回里带 **aborted** = 上一批因整账户级失败被提前中止(kind=account_overdue 平台上游账户欠费 / credits 点数不足),remaining 镜未执行。此时**原样重提必然同因失败**:credits 先充值;account_overdue 不是你的点数问题,停下告知用户稍后再试,别反复重提。",
         "tags": [
           "episodes"
         ],
@@ -4629,7 +4629,7 @@
       "post": {
         "operationId": "lipsync_episode",
         "summary": "给整集批量口型同步",
-        "description": "给整集批量口型同步。后台异步,按用量后付。用 get_lipsync_status 查进度。",
+        "description": "给整集批量口型同步。后台异步,按用量后付。用 get_lipsync_status 查进度。\n★收到 **503 code=lipsync.unavailable** = 平台当前没有可用的口型服务,本次未提交、未扣费,重试无用;按返回的 alternatives 改走别的路(重生该镜视频 / 定向编辑 / 只换音频——最后一个不改嘴型)。",
         "tags": [
           "episodes"
         ],
@@ -6926,6 +6926,175 @@
         }
       }
     },
+    "/episodes/{episode_id}/voice-identity-scan": {
+      "post": {
+        "operationId": "scan_voice_consistency",
+        "summary": "★原声剧（视频自带人声）客户报「同一个角色前后嗓音不一样 / 声线漂了」时跑这个",
+        "description": "★原声剧（视频自带人声）客户报「同一个角色前后嗓音不一样 / 声线漂了」时跑这个。免费（本地推理，不调厂商）。对每个有台词的镜，听厂商生成的人声：台词念没念全，以及声音像不像该角色绑定的声线锚。**异步**：立即返回，后台整集约 10 分钟；同一集同时只跑一条（重复调用返回 started=false）。默认跳过已对当前视频扫过的镜，rescan=true 全部重扫。用 get_voice_consistency 查进度和逐镜结果。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "rescan": {
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "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"
+          }
+        }
+      },
+      "get": {
+        "operationId": "get_voice_consistency",
+        "summary": "查声线一致性扫描的进度与逐镜结果（scan_voice_consistency 启动的）",
+        "description": "查声线一致性扫描的进度与逐镜结果（scan_voice_consistency 启动的）。免费。summary.voice_mismatch=声音不像该角色声线锚的镜号（重点看）；dialogue_issues=台词没念完/念错/多出说话声的镜；not_scanned_or_stale=还没扫或视频换过需重扫。speaker_verdict=uncertain 表示人声太短判不了，不是问题。声线不一致的镜：先用 get_pipeline_status 的 native_voice_anchor 确认角色已绑声线，再 regenerate_shot_video 重出。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "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"
+          }
+        }
+      }
+    },
+    "/episodes/{episode_id}/wardrobe-scan": {
+      "post": {
+        "operationId": "scan_wardrobe_consistency",
+        "summary": "★客户报「同一个角色前后换了衣服 / 衣服颜色款式不对」时跑这个；终拼前也建议跑一次",
+        "description": "★客户报「同一个角色前后换了衣服 / 衣服颜色款式不对」时跑这个；终拼前也建议跑一次。逐镜把采用的首帧和视频中段一帧，与本镜每个角色的设定图（没有则用定妆图）比对衣服的款式与颜色。常见成因是远景小人物被出图模型画成了别的衣服——即使参考图和提示词都对。夜景/暖光的整体偏色不算不一致。每镜一次视觉审计，**按用量计费**。返回 flagged[{shot, characters:[{name, differences}]}] / clean / errors。dry_run=true 只报告不写回；否则写回，compose_episode 的终拼预检会以 wardrobe_mismatch 列出这些镜。处置：重出该镜首帧（generate_shot_frame）再 regenerate_shot_video；重新拼接去不掉。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "dry_run": {
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "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"
+          }
+        }
+      }
+    },
     "/episodes/{episode_id}/wardrobe-timeline": {
       "post": {
         "operationId": "build_wardrobe_timeline",
@@ -8924,7 +9093,7 @@
       "post": {
         "operationId": "lipsync_shot",
         "summary": "给单镜做口型同步(对白与人物嘴型对齐)",
-        "description": "给单镜做口型同步(对白与人物嘴型对齐)。按用量后付。",
+        "description": "给单镜做口型同步(对白与人物嘴型对齐)。按用量后付。\n★收到 **503 code=lipsync.unavailable** = 平台当前没有可用的口型服务,本次未提交、未扣费,重试无用;按返回的 alternatives 改走别的路(重生该镜视频 / 定向编辑 / 只换音频——最后一个不改嘴型)。",
         "tags": [
           "storyboards"
         ],

package/package.json

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