@starreel/mcp 0.1.16 → 0.1.17

package/SKILL.md

@@ -96,12 +96,22 @@ content that will be rejected.
    video: a portrait is one image, but **character sheets (multi-view turnarounds)
    are the shot consistency anchor every frame references** — portraits alone
    leave characters drifting across angle / lighting / wardrobe.
-   `generate_portraits_and_sheets` does both (portraits first, then sheets). `generate_frames` makes **first frames only** — you do
+   `generate_portraits_and_sheets` does both (portraits first, then sheets). `generate_frames` makes **first frames only** by default — you do
    NOT generate first + last together. A **last frame** is optional and never
-   auto-made; upload it via `upload_shot_frame` (`frame_type=last_frame`) only to
-   pin a shot's ending (a big camera move or reveal). `generate_videos` needs at
+   auto-made; ask for one only to pin a shot's ending (a big camera move or
+   reveal), via `generate_frames` with `frame_type=last_frame` or, for a single
+   shot, `generate_shot_frame`. `generate_videos` needs at
    least one first frame in the episode.
 
+   **Redraw on-platform, never off-platform.** When a shot's image is wrong,
+   fix it with `quote_shot_frame` → `generate_shot_frame` (`frame_type`:
+   `first_frame` / `last_frame` / `both`). That path carries the shot's character
+   identity anchors, scene/prop references, style lock and frame audit, so the new
+   image still matches the rest of the film. Do **not** render the image in another
+   image tool and push it in with `upload_shot_frame` — that bypasses every anchor
+   (faces, wardrobe and style drift) and makes you hostage to that tool's queue.
+   `upload_shot_frame` is for art the customer already owns.
+
 7. **Poll, don't block; don't hammer.** Long steps return immediately as
    `status:generating`. Poll `get_pipeline_status` / `get_jobs` /
    `get_storyboards` with a backoff (start ~5–10s, widen on no change). Stable

package/dist/tools/produce.js

@@ -32,6 +32,8 @@ const ETHNICITY_CODES = [
 // 画幅/分辨率的可选值 —— create_drama 与 update_project_settings **共用同一源**,防两处漂移。
 // 与后端发现接口 produce-options.ts 的 ASPECT_RATIO_OPTIONS / VIDEO_RESOLUTION_OPTIONS 键集一致
 // (video_resolution 与后端 VIDEO_RES_WHITELIST 钉死;aspect_ratio 后端柔性,这里给同一策展集)。
+// 帧类型(与后端 produce-facade.parseFrameParam 同一枚举):整集/单镜出帧共用。
+const FRAME_TYPE_ARG = z.enum(['first_frame', 'last_frame', 'both']);
 const ASPECT_RATIOS = ['9:16', '16:9', '1:1', '4:5', '4:3', '21:9'];
 const VIDEO_RESOLUTIONS = ['480p', '720p', '1080p', '4k'];
 /** 把友好 ethnicity 枚举 + note 组装成后端认的结构化族裔锁 { code, note? }。 */
@@ -120,9 +122,33 @@ export function registerProduceTools(server, client) {
         'insufficient_credits/transient)、retryable(true=可重试;false=改内容换图,重试无效)、fail_hint(人读文案)。' +
         '照 retryable 判该重试还是该改内容,别解析中文。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/storyboards`)));
     // ---------- 出首帧(frames) ----------
-    server.tool('quote_frames', '报价:给某一集缺首帧的分镜批量出首帧要多少点。返回 frames_to_generate、estimated_points、quote_id。零扣费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/frames/quote`)));
-    server.tool('generate_frames', '确认后批量出首帧:后台异步。用 get_storyboards 轮询,first_frame_image 逐镜填充即完成。' +
-        '出视频前必须先出帧,否则视频会退化成无一致性锚点的画面。' + CONFIRM_HINT, { episode_id: z.number().int().positive(), quote_id: z.string().describe('来自 quote_frames') }, async ({ episode_id, quote_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/frames/generate`, { quote_id })));
+    server.tool('quote_frames', '报价:给某一集批量出帧要多少点。返回 frames_to_generate、estimated_points、quote_id。零扣费。' +
+        'frame_type 默认 first_frame(只给缺首帧的镜出);last_frame 只给「已有首帧且缺尾帧」的镜出;both 两者都补。', {
+        episode_id: z.number().int().positive(),
+        frame_type: FRAME_TYPE_ARG.optional().describe('默认 first_frame;last_frame=补尾帧;both=首尾都补'),
+    }, async ({ episode_id, frame_type }) => jsonResult(await client.producePost(`/episodes/${episode_id}/frames/quote`, { frame_type })));
+    server.tool('generate_frames', '确认后批量出帧:后台异步。用 get_storyboards 轮询,first_frame_image/last_frame_image 逐镜填充即完成。' +
+        '出视频前必须先出帧,否则视频会退化成无一致性锚点的画面。' +
+        'frame_type 要与 quote_frames 用的一致(默认 first_frame)。尾帧只在想固定某镜结尾画面时才补,常规只需首帧。' + CONFIRM_HINT, {
+        episode_id: z.number().int().positive(),
+        quote_id: z.string().describe('来自 quote_frames'),
+        frame_type: FRAME_TYPE_ARG.optional().describe('默认 first_frame,须与报价时一致'),
+    }, async ({ episode_id, quote_id, frame_type }) => jsonResult(await client.producePost(`/episodes/${episode_id}/frames/generate`, { quote_id, frame_type })));
+    // ---------- 单镜出帧/重生(改某一镜的画面走这里,别去外部平台出图再传回来) ----------
+    server.tool('quote_shot_frame', '报价:重画/补出**某一镜的某一帧**要多少点(一帧=一张图)。返回 estimated_points、quote_id。零扣费。' +
+        '客户说「第 N 镜画错了/要改」时用它,而不是拿别的图像平台出图再 upload_shot_frame。', {
+        storyboard_id: z.number().int().positive(),
+        frame_type: FRAME_TYPE_ARG.optional().describe('默认 first_frame;both=首尾各一张'),
+    }, async ({ storyboard_id, frame_type }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/frame/quote`, { frame_type })));
+    server.tool('generate_shot_frame', '确认后给**某一镜**出帧或重生该帧(异步)。这是修某一镜画面的正路:平台会带上该镜的角色身份锚、' +
+        '场景/道具参考图、画风锚与帧审计,重生出的图与全片一致;用外部工具出图再上传会绕开这整条链路,人物/服装/画风必漂。' +
+        '重生会覆盖该帧现有图(含此前上传的),并把本镜视频标为待重生。尾帧需本镜首帧已就绪(否则先用 first_frame 或 both)。' +
+        '完成判据:轮询 get_storyboards 看该镜 first_frame_image/last_frame_image 变化。' + CONFIRM_HINT, {
+        storyboard_id: z.number().int().positive(),
+        quote_id: z.string().describe('来自 quote_shot_frame'),
+        frame_type: FRAME_TYPE_ARG.optional().describe('默认 first_frame,须与报价时一致'),
+        replace_user_frame: z.boolean().optional().describe('默认 true(显式重生允许覆盖已上传帧);传 false 则保护已上传帧'),
+    }, async ({ storyboard_id, quote_id, frame_type, replace_user_frame }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/frame/generate`, { quote_id, frame_type, replace_user_frame })));
     // ---------- 出视频(videos,大额) ----------
     server.tool('quote_videos', '报价:给某一集所有分镜批量出视频要多少点(与实际扣费同函数,较准)。返回 estimated_points、quote_id。零扣费。' +
         '⚠️ 视频是大额花费,务必把点数清楚告诉用户并等其确认。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/videos/quote`)));
@@ -213,7 +239,9 @@ export function registerProduceTools(server, client) {
             throw new Error('file_path 或 image_url 至少提供一个');
         return jsonResult(await client.producePost(`/characters/${character_id}/portrait`, { image_url: url }));
     });
-    server.tool('upload_shot_frame', '用客户自有图片作为某镜的首帧(first_frame)或尾帧(last_frame)。尾帧可选、系统不自动生成——仅在想固定某镜结尾画面(大运镜/揭示镜)时传;常规只需首帧。会把该镜已有视频标为过期待重生。自动上传+登记。免费。', {
+    server.tool('upload_shot_frame', '用**客户自有图片**作为某镜的首帧(first_frame)或尾帧(last_frame)。尾帧可选——仅在想固定某镜结尾画面(大运镜/揭示镜)时传;常规只需首帧。会把该镜已有视频标为过期待重生。自动上传+登记。免费。' +
+        '⚠️ 只用于客户自己提供的素材。想「重画/修某一镜」请用 generate_shot_frame 让平台重生——' +
+        '外部工具出的图不带本片的身份锚与画风锚,贴进来人物/服装/画风会漂。', {
         storyboard_id: z.number().int().positive(),
         file_path: z.string().describe('本地帧图路径'),
         frame_type: z.enum(['first_frame', 'last_frame']).optional().describe('默认 first_frame'),

package/package.json

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