@starreel/mcp 0.1.90 → 0.1.92

package/SKILL.md

@@ -709,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.
@@ -794,6 +798,33 @@ The platform's default shot breakdown still asks for one continuous action per
 shot. Apply the beat approach shot by shot on complaints; don't rewrite a whole
 episode this way unprompted.
 
+### Writing shots yourself — one main action per shot (动作过载 / "像快进")
+
+When you write storyboards yourself (`bulk_import_storyboards`, `update_shot`,
+`split_shot`), you bypass the platform's shot breakdown and its "one continuous
+action" rule, so apply it yourself **before any frame or video is generated** —
+post-production cannot fix it.
+
+- **One main action per shot.** The beats above are the *phases of that one
+  action* (wind-up → main action → settle), within the same budget: about
+  2 beats in 3 s, 3 beats in 5 s.
+- **A new thing is a new shot.** A discovery ("finds something in their hand",
+  "the person is gone"), a new goal, or turning to address someone else each
+  get their own shot — and the discovery shot needs room for the reaction.
+  Four independent actions in one 4–5 s shot (look back, answer, turn, notice
+  the other person has vanished) read as fast-forward or are simply not
+  performed.
+- **Write the joins.** State the pose the shot starts from and ends on
+  (`action_in` / `action_out`), so the next shot can start from it.
+- **Don't repair density with speed.** `speed_factor` slow-motion or longer
+  crossfades only stretch what the vendor animated; they cannot un-cram a
+  shot. Split it (`split_shot`) or cut actions, then regenerate.
+
+`check_bulk_import` and `review_storyboards` flag this as `action_overload`
+(advisory, never blocks). The count is word-based: several people each doing
+one thing, or one continuous chain (bend → reach → pick up), can trigger it —
+judge the flagged shot, don't split blindly.
+
 ### "画面里多出一个人 / 多出一件道具" — something appears that shouldn't be there
 
 Two completely different causes with opposite fixes. **Look at the shot's own

package/dist/tools/produce.js

@@ -435,7 +435,7 @@ export function registerProduceTools(server, client) {
         'image_prompt/video_prompt 可不填(没填的镜由平台按景别+场景+光线+action 拼基础描述);填了就**逐字照用**,平台不覆盖。frame_visual_contract 是内部帧契约,导入时忽略。', {}, async () => jsonResult(await client.produceGet('/bulk-import/spec')));
     server.tool('check_bulk_import', '**导入前的 JSON 自检**:用导入端点**同一份 zod schema** 校验,再把导入路由的"静默行为"变成 warning。返回 errors / warnings / stats(镜数·总秒·角色·场景·mode·promptsToBuild)。免费·不落库·可反复跑。' +
         '★errors = 导入会 400 或会出错覆盖的:不是合法 JSON / schema 不过(逐条带 path,如 storyboards[2].shot_type)/ 镜号重复 + 残留 <...> 占位符;必须清零。' +
-        '★warnings = 导入照常但会缺东西或有副作用的:bound_characters/scene_ref 引用不到(静默跳过)/ 没有 action+description(死镜)/ dialogue 含镜头语言(会被念出来)/ 单镜>15 秒 / 镜号跳号 / mode=replace(替换本集全部分镜)/ 全无角色绑定(人物会漂)。' +
+        '★warnings = 导入照常但会缺东西或有副作用的:bound_characters/scene_ref 引用不到(静默跳过)/ 没有 action+description(死镜)/ dialogue 含镜头语言(会被念出来)/ 单镜>15 秒 / action_overload(一镜塞了超过时长承载量的独立动作——约 3 秒 2 拍、5 秒 3 拍;一镜一个主要动作,另起的事拆下一镜;多人各做一件事可忽略)/ 镜号跳号 / mode=replace(替换本集全部分镜)/ 全无角色绑定(人物会漂)。' +
         '★这里绿了,bulk_import_storyboards 就能一次过。', { payload: z.union([z.string(), z.record(z.string(), z.unknown())]).describe('要检查的 JSON:对象,或 JSON 字符串(客户贴的文本)') }, async ({ payload }) => jsonResult(await client.producePost('/bulk-import/lint', { payload })));
     server.tool('bulk_import_storyboards', '把一份结构化 JSON 一次性建成本集的分镜(按 storyboard_number 去重更新)。**不建角色/场景/道具**——它们由 extract_assets 从剧本提取,导入只按名字绑定已有的(回执 characters_unmatched / char_refs_unresolved 列出没绑上的;先 extract 再导)。免费·确定性·不调 AI。' +
         '★三步走:① get_bulk_import_spec 取契约与成品示例;② check_bulk_import 自检到 errors 清零;③ 再调本工具。' +
@@ -623,7 +623,8 @@ export function registerProduceTools(server, client) {
         '分镜里的问题一旦整集出图就变成整集废图,单镜修不回来。按 findings.action 用 update_shot/split_shot 修完再复审。' +
         '★code=forbidden_term 的 finding 带 `terms` 字段(命中的具体词,如「背景音乐」「强光」)与 `shots`(镜号),' +
         '照着这两个去 update_shot 改掉即可,不用逐字猜。' +
-        '★禁区词判**否定语义**:写「无背景音乐」「不要配乐」不算违规(那是在遵守约束),不必为此改稿。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/storyboards`)));
+        '★禁区词判**否定语义**:写「无背景音乐」「不要配乐」不算违规(那是在遵守约束),不必为此改稿。' +
+        '★warnings 里的「动作过载」(action_overload,advisory 不拦):一镜塞了超过时长承载量的独立动作,出视频前用 split_shot 拆开或删动作——成片后靠慢放/叠化补救不了。多人各做一件事或本身连贯的一串可忽略。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/storyboards`)));
     server.tool('review_frames', '【第③道硬闸·免费】审查镜头图片层:角色身份锚覆盖(缺定妆图的角色在镜头里必漂)、出图失败率、' +
         '孤儿角色变体、场景图被人物污染。★generate_videos 之前必须先跑本工具——出视频是全链最贵的一步,' +
         '拿着漂移的首帧整集出视频是最典型的废片形态。按 findings.action 修完(多为 generate_character_portraits / ' +
@@ -1228,7 +1229,7 @@ export function registerProduceTools(server, client) {
         director_note: z.string().optional().describe('导演注释'),
         shot_intent: z.string().optional().describe('这镜为什么存在(叙事意图)'),
         duration: z.number().positive().optional().describe('本镜时长(秒,可带小数如 2.5)。上限=本剧视频引擎的单镜上限,超出直接拒并告知上限(更长内容用 split_shot 拆镜)。有台词时平台按语速律只抬不降,抬了会在回执 speech_duration_note 里说。★改时长不会自动重出视频:已有视频仍是旧长度,要厂商按新时长出就 regenerate_shot_video(报价按新时长算)。★别拿加长治「动作太慢」——同样的动作摊到更长时间里只会更慢,见 qa_tools「动作太慢」'),
-        speed_factor: z.number().positive().nullable().optional().describe('成片变速:<1 慢镜、>1 快放、null 清除(0.5–2.0,越界被钳到范围内)。只在终拼/剪映导出时变速播放(画面 setpts + 声音 atempo,音高不变),**不重出视频、不扣费**,但会改变本镜在成片里占的时长。适合做慢镜/升格氛围;治不了「动作没演出来」——那是视频内容本身,要改 video_prompt 重出。有台词的镜慎用(人声也跟着变快变慢)'),
+        speed_factor: z.number().positive().nullable().optional().describe('成片变速:<1 慢镜、>1 快放、null 清除(0.5–2.0,越界被钳到范围内)。只在终拼/剪映导出时变速播放(画面 setpts + 声音 atempo,音高不变),**不重出视频、不扣费**,但会改变本镜在成片里占的时长。适合做慢镜/升格氛围;治不了「动作没演出来」——那是视频内容本身,要改 video_prompt 重出;也治不了一镜塞太多动作(action_overload)——那要拆镜重出。有台词的镜慎用(人声也跟着变快变慢)'),
         image_prompt: z.string().optional().describe('首帧画面提示词**正文**(全量覆盖本镜现值)。★先 get_shot_prompts 读现值再改;★原样保留其中的 @char:N / @scene:M 引用标记,删了就不注入对应定妆图/场景图。出图时平台会在正文之上再拼身份锚与一致性约束,不必你写。★写法坑:别写「no X / without X / 不要 X / 没有 X」这类否定式约束——图像模型把名词当正向线索,反而把 X 画出来;要正向写出那块画面该有什么(材质/形状/颜色/远近)。保存响应带 image_prompt_negation_advisory 即命中,按其 note 改写'),
         video_prompt: z.string().optional().describe('视频(动态/运镜/表演)提示词**正文**(全量覆盖本镜现值)。★同 image_prompt:先读现值、保留 @char/@scene 标记'),
         first_frame_prompt: z.string().optional().describe('本镜**开始时**画面是什么样(首帧目标状态正文,全量覆盖现值)。送达提示词里作为 [START FRAME] 段排在最前,优先级高于 image_prompt——所以 image_prompt 改了不生效时,往往是这条在压着它。★同 image_prompt:先 get_shot_prompts 读现值、原样保留 @char/@scene 标记'),
@@ -1274,7 +1275,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 配乐(按情绪弧线)。后台异步,按用量后付不欠费。返回情绪弧线段数与预估耗时;' +
@@ -1502,8 +1506,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.90",
-    "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.90 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.92",
+    "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.92 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -137,7 +137,7 @@
       "post": {
         "operationId": "check_bulk_import",
         "summary": "**导入前的 JSON 自检**:用导入端点**同一份 zod schema** 校验,再把导入路由的\"静默行为\"变成 warning",
-        "description": "**导入前的 JSON 自检**:用导入端点**同一份 zod schema** 校验,再把导入路由的\"静默行为\"变成 warning。返回 errors / warnings / stats(镜数·总秒·角色·场景·mode·promptsToBuild)。免费·不落库·可反复跑。★errors = 导入会 400 或会出错覆盖的:不是合法 JSON / schema 不过(逐条带 path,如 storyboards[2].shot_type)/ 镜号重复 + 残留 <...> 占位符;必须清零。★warnings = 导入照常但会缺东西或有副作用的:bound_characters/scene_ref 引用不到(静默跳过)/ 没有 action+description(死镜)/ dialogue 含镜头语言(会被念出来)/ 单镜>15 秒 / 镜号跳号 / mode=replace(替换本集全部分镜)/ 全无角色绑定(人物会漂)。★这里绿了,bulk_import_storyboards 就能一次过。",
+        "description": "**导入前的 JSON 自检**:用导入端点**同一份 zod schema** 校验,再把导入路由的\"静默行为\"变成 warning。返回 errors / warnings / stats(镜数·总秒·角色·场景·mode·promptsToBuild)。免费·不落库·可反复跑。★errors = 导入会 400 或会出错覆盖的:不是合法 JSON / schema 不过(逐条带 path,如 storyboards[2].shot_type)/ 镜号重复 + 残留 <...> 占位符;必须清零。★warnings = 导入照常但会缺东西或有副作用的:bound_characters/scene_ref 引用不到(静默跳过)/ 没有 action+description(死镜)/ dialogue 含镜头语言(会被念出来)/ 单镜>15 秒 / action_overload(一镜塞了超过时长承载量的独立动作——约 3 秒 2 拍、5 秒 3 拍;一镜一个主要动作,另起的事拆下一镜;多人各做一件事可忽略)/ 镜号跳号 / mode=replace(替换本集全部分镜)/ 全无角色绑定(人物会漂)。★这里绿了,bulk_import_storyboards 就能一次过。",
         "tags": [
           "bulk-import"
         ],
@@ -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"
         ],
@@ -5504,7 +5504,7 @@
       "post": {
         "operationId": "review_storyboards",
         "summary": "【第②道硬闸·免费】审查分镜:禁区词(会被厂商审核拒、白扣费)、镜头时长分布、相邻构图重复、同场景角色站位漂移、情绪曲线峰谷、关键镜标记",
-        "description": "【第②道硬闸·免费】审查分镜:禁区词(会被厂商审核拒、白扣费)、镜头时长分布、相邻构图重复、同场景角色站位漂移、情绪曲线峰谷、关键镜标记。★generate_frames 之前必须先跑本工具——分镜里的问题一旦整集出图就变成整集废图,单镜修不回来。按 findings.action 用 update_shot/split_shot 修完再复审。★code=forbidden_term 的 finding 带 `terms` 字段(命中的具体词,如「背景音乐」「强光」)与 `shots`(镜号),照着这两个去 update_shot 改掉即可,不用逐字猜。★禁区词判**否定语义**:写「无背景音乐」「不要配乐」不算违规(那是在遵守约束),不必为此改稿。",
+        "description": "【第②道硬闸·免费】审查分镜:禁区词(会被厂商审核拒、白扣费)、镜头时长分布、相邻构图重复、同场景角色站位漂移、情绪曲线峰谷、关键镜标记。★generate_frames 之前必须先跑本工具——分镜里的问题一旦整集出图就变成整集废图,单镜修不回来。按 findings.action 用 update_shot/split_shot 修完再复审。★code=forbidden_term 的 finding 带 `terms` 字段(命中的具体词,如「背景音乐」「强光」)与 `shots`(镜号),照着这两个去 update_shot 改掉即可,不用逐字猜。★禁区词判**否定语义**:写「无背景音乐」「不要配乐」不算违规(那是在遵守约束),不必为此改稿。★warnings 里的「动作过载」(action_overload,advisory 不拦):一镜塞了超过时长承载量的独立动作,出视频前用 split_shot 拆开或删动作——成片后靠慢放/叠化补救不了。多人各做一件事或本身连贯的一串可忽略。",
         "tags": [
           "episodes"
         ],
@@ -9093,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.90",
+  "version": "0.1.92",
   "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.90",
+  "version": "0.1.92",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.90",
+      "version": "0.1.92",
       "transport": {
         "type": "stdio"
       },