@starreel/mcp 0.1.121 → 0.1.123

package/SKILL.md

@@ -91,8 +91,9 @@ announces a condensed version as MCP `instructions` at connect time.
 | **No sample** — just an idea of the voice (a narrator, a character that deserves its own voice) | `design_voice` (one-sentence description, free) → `get_voice_design` until `done` (candidates arrive as local wav files — let the customer listen) → `save_designed_voice` (pick one; billed like a clone) → `set_character_voice` | generating every line straight from the description — each generation is a different person; naming a real person to imitate their voice |
 | A song + lyrics | `create_drama` (`project_type: "mv"`) → `set_mv_lyrics` → `generate_mv_story` → `generate_mv_script` | `rewrite_script` (blocked for MV) |
 | A product / brand | `create_drama` (`project_type: "ad"` or `"brand_film"`) → `add_product` → `generate_product_sheet` | writing brand copy as dialogue (it gets spoken) |
-| Generated shots / a cut that needs changes | `scan_dialogue_coverage` / `scan_intra_shot_cuts` first, then `get_shot_prompts` · `update_shot` · `replace_shot_dialogue` · `repair_episode_dialogue` · `split_shot` · `trim_shot` · `regenerate_shot_video` · `edit_video_shot` → `rerender_episode` | re-composing to fix what a clip *says* |
+| Generated shots / a cut that needs changes | `scan_dialogue_coverage` / `scan_intra_shot_cuts` first, then `get_shot_prompts` · `update_shot` · `replace_shot_dialogue` · `repair_episode_dialogue` · `split_shot` · `trim_shot` · `regenerate_shot_video` · `edit_video_shot` → `rerender_episode`. To retry **one shot on a different video engine**, pass `model` to `quote_regenerate_shot_video` (that shot, that regeneration only — the drama's `video_engine` is untouched; the quote pins the engine, so changing it means re-quoting) | re-composing to fix what a clip *says*; switching the whole drama's `video_engine` just to fix one shot |
 | Wants old portraits / sheets / a shot's old tail frame "deleted" | `set_character_portrait` (old assets listed in `old_assets`) · `clear_shot_frame` (old tail frame) → `regenerate_shot_video`; `list_unlinked_assets` lists the drama's unlinked old assets (a history list, not proof of ownership). Both only **unlink** — files are not deleted (`physically_deleted` is always empty; `in_history: false` means the platform kept no record, so save that URL if it matters). Tell the customer exactly that | telling the customer the old image was deleted; writing `last_frame_image: null` through the internal API |
+| Wants an old image **permanently** deleted from storage (not just unlinked) | `preview_delete_asset` → show the customer exactly what it says (blocking references, history that will break, copies) → only after an explicit "confirm delete" → `delete_asset` with the `confirm_token`. Irreversible; only the drama owner; only files with trusted provenance (generated for this drama, or uploaded through the platform with a grant record) | deleting without showing the preview; retrying automatically; treating `list_unlinked_assets` as proof the file is unused |
 | Cross-era drama (scenes in different periods) — checking props fit their period | `get_props` → read each prop's `era_audit` (`form_consistent`, `conflicting_scopes`, `violations`); `audit_prop_era` to re-check after a new sheet. On a conflict: `update_prop` with a precise `era_lock` (dynasty + physical form) → `generate_prop_sheet`, or bind a different prop to those shots. `run_precheck` also lists shots whose bound prop conflicts (`prop-era-conflict`) | trusting the prop's name or description alone; regenerating shot frames before the prop sheet is fixed |
 | Wants to assemble the cut themselves | `export_handoff_pack` → `get_handoff_toolchain` → **`register_external_delivery`** when the cut is final | `compose_episode` (pick one); delivering a cut the platform has no record of |
 | A multi-language release | `translate_subtitles` · `subtitle_secondary_lang` in project settings | — |

package/dist/client.js

@@ -119,6 +119,31 @@ export class StarReelClient {
             throw new Error(body?.message ?? body?.error ?? `HTTP ${res.status} on ${path}`);
         return (body?.data ?? body); // StarReel 信封 {code,data,message}
     }
+    /**
+     * 非 2xx 也不抛错：把状态码和完整响应体原样返回。给那些失败响应本身带结构化回执的端点用
+     * （如真删除的部分失败 502 回执——produce() 抛错只留 message，回执会被丢掉）。
+     */
+    async producePostRaw(path, body) {
+        let res;
+        try {
+            res = await this.authedFetch(`${AUTH_BASE}/v1/produce${path}`, {
+                method: 'POST', headers: { 'content-type': 'application/json' },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (e) {
+            throw new Error(`StarReel production pipeline unreachable (${AUTH_BASE}): ${e?.cause?.code ?? e?.message ?? e}. Retry later or check with StarReel.`);
+        }
+        const text = await res.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = { raw: text.slice(0, 300) };
+        }
+        return { http_status: res.status, ok: res.ok, body: parsed };
+    }
     produceGet(path) {
         return this.produce(path, { method: 'GET' });
     }

package/dist/tools/produce.js

@@ -232,13 +232,14 @@ const PROJECT_SETTINGS_FIELDS = {
         'gpt-image-2.5-flare(默认·基础11点+每张参考图18点)/gpt-image-2.5-sunburst(同价·中文字形与细节更准·慢约5秒)/' +
         'gemini-3.1-flash-image(香蕉2·71点)/gemini-3-pro-image(香蕉Pro·精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·31点)/' +
         'doubao-seedream-5-0-260128(Seedream 5.0)。建剧即定、整剧统一;generate_frames 可临时覆盖某次出图。★各模型实测优劣(一次过率/手部结构/安全拒绝率/画风稳定度)与选型步骤见 get_capabilities_guide(section=model_guide)'),
-    // drama 级视频引擎(整剧统一,单镜/批量/场景组/重生全走它)
+    // drama 级视频引擎(整剧统一,单镜/批量/场景组/重生全走它;单镜例外入口:quote_regenerate_shot_video 的 model / edit_video_shot 的 model)
     video_engine: z.enum(VIDEO_ENGINES).optional().describe('视频引擎(★drama级·整剧统一·AI必须按剧选型主动引导:写实真人剧→seedance-2.5 或降本 hailuo-3;风格化/动画/3D卡通/空镜/产品镜→wan3.0(赶交付 wan3.0-prime);写实真人剧绝不选 wan——720p+ 真人脸被厂商审核一致拒):' +
         'seedance-2.5(默认·全能力:帧链/场景组/就地编辑/延长/参考图锚·720p约212点/秒) / ' +
         'hailuo-3(MiniMax H3:约1/3成本 720p 70点/秒·原生对白与音效·支持2K·单镜约6分钟·支持就地编辑(强保真)与成片续写·关键帧组/时间戳区间暂不可用;编辑/续写输入视频另按秒计费) / ' +
         'wan3.0(WAN 3.0:约4折成本 720p 84点/秒·原生对白与音效·支持1080P·单次最长30秒·最短2秒计费·支持就地编辑(强语义)与成片续写·关键帧组/时间戳区间暂不可用;★写实真人720p+可能被厂商审核拒绝,风格化/动画剧适用;★★会在单个分镜片内自行换机位硬切(实测11/12镜)→叙事剧慎用,详见选型决策树④) / ' +
         'wan3.0-prime(WAN 3.0 高速版:能力同wan3.0·出片约2×·费率1.5×=720p 126点/秒;镜内自剪同 wan3.0)。' +
-        '★必须在出视频**前**设置——切换不回溯已生成的镜头,同剧混用引擎会有画风/身份漂移风险'),
+        '★必须在出视频**前**设置——切换不回溯已生成的镜头,同剧混用引擎会有画风/身份漂移风险。' +
+        '只想给个别镜换引擎别改这里:用 quote_regenerate_shot_video 的 model(只作用于那一镜那一次)'),
     // 整剧视觉一致性锚(注入所有出图/视频 prompt,决定跨镜一致)
     cinematography_prompt: z.string().optional().describe('摄影DNA:镜头/镜片/光圈/调色一揽子,注入所有出图/视频prompt,整剧镜头一致。' +
         '★★写**单镜**摄影规格,不要写整部剧的镜头序列:本字段会被原样注入**每一个分镜**,' +
@@ -1148,6 +1149,23 @@ export function registerProduceTools(server, client) {
     server.tool('list_unlinked_assets', '列出本剧「已解除引用」的旧资产(免费):清尾帧、换定妆图时被摘下来的旧尾帧/旧定妆图/旧设定图/发型·身体参考/视频锚,每个 URL 一条。' +
         '这些文件仍然存在于存储里。清单会尽量排除已被重新用上的图,但不保证完全排除——某张图是否还在别处被引用,' +
         '以平台的全库检查为准。客户问「旧图还在不在」时用它。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/unlinked-assets`)));
+    server.tool('preview_delete_asset', '预览「真删除」某个旧资产文件(免费、只读)。真删除会从存储里**永久删除**这张图的全部版本,不可撤销。' +
+        '返回 deletable(能不能删)、reasons(不能删的原因,如 still-referenced 仍被引用 / no-trusted-provenance 无法证明归属 / not-drama-owner 不是剧主)、' +
+        'blocking(还在引用它的位置)、history(会失效的历史记录条数)、copies(各存储桶里的版本数),能删时附 confirm_token(10 分钟内有效、只能用一次)。' +
+        '★必须把预览结果原样告诉客户,客户明确说「确认删除」后才能调 delete_asset;不要替客户做决定。' +
+        '只有剧主能删;只能删能证明归属的文件——平台为本剧生成的图,或客户通过平台上传(上传时有签发记录)的图;更早上传、没有签发记录的图删不了,只能解除引用。', { drama_id: z.number().int().positive(), url: z.string().describe('要删除的图片地址(通常来自 list_unlinked_assets 或解除引用回执)') }, async ({ drama_id, url }) => jsonResult(await client.producePost(`/dramas/${drama_id}/asset-delete/preview`, { url })));
+    server.tool('delete_asset', '★不可撤销:永久删除某个旧资产文件的全部版本(两个存储桶)。必须先 preview_delete_asset,把结果给客户看,客户明确确认后,' +
+        '带上同一个 url 与预览返回的 confirm_token 调用。执行前平台会重跑全部检查,影响范围和预览时不一致会拒绝(409),需要重新预览。' +
+        '部分副本删除失败会返回 502 与回执,文件可能还在,可重新预览后重试。不要自动重试、不要批量删除客户没逐个确认过的文件。', {
+        drama_id: z.number().int().positive(),
+        url: z.string(),
+        confirm_token: z.string().describe('preview_delete_asset 返回的一次性确认凭证'),
+    }, 
+    // 失败响应自带结构化回执（哪个桶删了几个版本、哪些失败）——用不抛错的调用原样交给 agent（#684 review）
+    async ({ drama_id, url, confirm_token }) => {
+        const r = await client.producePostRaw(`/dramas/${drama_id}/asset-delete`, { url, confirm_token });
+        return jsonResult(r.ok ? (r.body?.data ?? r.body) : { http_status: r.http_status, ...r.body });
+    });
     server.tool('clear_shot_frame', '清除某镜的尾帧(解除引用,免费)。用于换了定妆图/改了剧情后,旧尾帧会把旧人物/旧画面带进重生的视频时,先清掉它再 regenerate_shot_video。' +
         '只能清尾帧:首帧是出视频的起点,要换首帧用 generate_shot_frame 重生或 upload_shot_frame 替换。' +
         '★这是解除引用,不是删除:文件不会被删,响应里 unlinked[].in_history=true 的可在 get_asset_versions 找回,physically_deleted 恒为空——如实告诉客户。' +
@@ -1206,7 +1224,16 @@ export function registerProduceTools(server, client) {
         replace_user_footage: z.boolean().optional().describe('本镜是实拍素材镜(upload_shot_footage 传过)时,显式允许以它为源做编辑并用 AI 产物覆盖它。' +
             '不传则被守卫拒(409,带中文出路)。想保留素材就别传,改用 clear_shot_footage 换回 AI 生成。'),
     }, async ({ storyboard_id, ...rest }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/edit/generate`, rest)));
-    server.tool('quote_regenerate_shot_video', '报价:重生某镜视频要多少点。返回 quote_id。零扣费。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/regen/quote`)));
+    server.tool('quote_regenerate_shot_video', '报价:重生某镜视频要多少点。返回 quote_id。零扣费。' +
+        '\n★**按镜指定视频引擎**:传 model 即只为这一镜这一次重生换引擎(不改剧级 video_engine,其它镜照旧);' +
+        '报价按该引擎计价,quote_id 把引擎钉死,regenerate_shot_video 派发的就是它——要换引擎必须重新报价,生成时再传引擎无效。' +
+        '回执 video_engine = 实际派发的引擎,engine_overridden=true 表示盖过了剧引擎。' +
+        '★所选引擎必须支持本剧分辨率(seedance-2.5 只有 480p/720p;hailuo-3 只有 720p/1080p;wan3.0/wan3.0-prime 480p~1080p),不支持则 400 并列出可选引擎——不会悄悄换成别的引擎出片。' +
+        '适用:某镜在本剧引擎上反复失败/被厂商审核拒/镜内自剪,单独换一个引擎试。' +
+        '★同剧混用引擎有画风/身份漂移风险,换完先看这一镜再决定要不要推广;写实真人镜别换 wan3.0/wan3.0-prime(真人脸 720p+ 常被厂商拒)。', {
+        storyboard_id: z.number().int().positive(),
+        model: z.enum(VIDEO_ENGINES).optional().describe('本镜本次重生的视频引擎(缺省=跟随剧 video_engine)。seedance-2.5 / hailuo-3 / wan3.0 / wan3.0-prime,能力与单价见 update_project_settings 的 video_engine'),
+    }, async ({ storyboard_id, model }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/regen/quote`, model ? { model } : {})));
     server.tool('regenerate_shot_video', '确认后重生某镜视频(可选新 prompt)。' +
         '\n★收到 **409「本镜是用户上传的实拍素材」** = 该镜被 upload_shot_footage 登记成实拍素材镜,不是模型问题,换引擎无用;' +
         '要用 AI 视频覆盖它就带 replace_user_footage=true,要保留素材就别重生。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.121",
-    "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.121 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.123",
+    "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.123 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -1358,6 +1358,142 @@
         }
       }
     },
+    "/dramas/{drama_id}/asset-delete": {
+      "post": {
+        "operationId": "delete_asset",
+        "summary": "★不可撤销:永久删除某个旧资产文件的全部版本(两个存储桶)",
+        "description": "★不可撤销:永久删除某个旧资产文件的全部版本(两个存储桶)。必须先 preview_delete_asset,把结果给客户看,客户明确确认后,带上同一个 url 与预览返回的 confirm_token 调用。执行前平台会重跑全部检查,影响范围和预览时不一致会拒绝(409),需要重新预览。部分副本删除失败会返回 502 与回执,文件可能还在,可重新预览后重试。不要自动重试、不要批量删除客户没逐个确认过的文件。",
+        "tags": [
+          "dramas"
+        ],
+        "parameters": [
+          {
+            "name": "drama_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "url": {
+                    "type": "string"
+                  },
+                  "confirm_token": {
+                    "type": "string",
+                    "description": "preview_delete_asset 返回的一次性确认凭证"
+                  }
+                },
+                "required": [
+                  "url",
+                  "confirm_token"
+                ]
+              }
+            }
+          }
+        },
+        "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"
+          }
+        }
+      }
+    },
+    "/dramas/{drama_id}/asset-delete/preview": {
+      "post": {
+        "operationId": "preview_delete_asset",
+        "summary": "预览「真删除」某个旧资产文件(免费、只读)",
+        "description": "预览「真删除」某个旧资产文件(免费、只读)。真删除会从存储里**永久删除**这张图的全部版本,不可撤销。返回 deletable(能不能删)、reasons(不能删的原因,如 still-referenced 仍被引用 / no-trusted-provenance 无法证明归属 / not-drama-owner 不是剧主)、blocking(还在引用它的位置)、history(会失效的历史记录条数)、copies(各存储桶里的版本数),能删时附 confirm_token(10 分钟内有效、只能用一次)。★必须把预览结果原样告诉客户,客户明确说「确认删除」后才能调 delete_asset;不要替客户做决定。只有剧主能删;只能删能证明归属的文件——平台为本剧生成的图,或客户通过平台上传(上传时有签发记录)的图;更早上传、没有签发记录的图删不了,只能解除引用。",
+        "tags": [
+          "dramas"
+        ],
+        "parameters": [
+          {
+            "name": "drama_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "url": {
+                    "type": "string",
+                    "description": "要删除的图片地址(通常来自 list_unlinked_assets 或解除引用回执)"
+                  }
+                },
+                "required": [
+                  "url"
+                ]
+              }
+            }
+          }
+        },
+        "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"
+          }
+        }
+      }
+    },
     "/dramas/{drama_id}/assets": {
       "get": {
         "operationId": "get_assets",
@@ -11176,7 +11312,7 @@
       "post": {
         "operationId": "quote_regenerate_shot_video",
         "summary": "报价:重生某镜视频要多少点",
-        "description": "报价:重生某镜视频要多少点。返回 quote_id。零扣费。",
+        "description": "报价:重生某镜视频要多少点。返回 quote_id。零扣费。\n★**按镜指定视频引擎**:传 model 即只为这一镜这一次重生换引擎(不改剧级 video_engine,其它镜照旧);报价按该引擎计价,quote_id 把引擎钉死,regenerate_shot_video 派发的就是它——要换引擎必须重新报价,生成时再传引擎无效。回执 video_engine = 实际派发的引擎,engine_overridden=true 表示盖过了剧引擎。★所选引擎必须支持本剧分辨率(seedance-2.5 只有 480p/720p;hailuo-3 只有 720p/1080p;wan3.0/wan3.0-prime 480p~1080p),不支持则 400 并列出可选引擎——不会悄悄换成别的引擎出片。适用:某镜在本剧引擎上反复失败/被厂商审核拒/镜内自剪,单独换一个引擎试。★同剧混用引擎有画风/身份漂移风险,换完先看这一镜再决定要不要推广;写实真人镜别换 wan3.0/wan3.0-prime(真人脸 720p+ 常被厂商拒)。",
         "tags": [
           "storyboards"
         ],
@@ -11191,6 +11327,27 @@
             }
           }
         ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "model": {
+                    "type": "string",
+                    "enum": [
+                      "seedance-2.5",
+                      "hailuo-3",
+                      "wan3.0",
+                      "wan3.0-prime"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "description": "StarReel envelope",

package/package.json

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