@starreel/mcp 0.1.118 → 0.1.120

package/SKILL.md

@@ -92,6 +92,8 @@ announces a condensed version as MCP `instructions` at connect time.
 | 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* |
+| 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`. 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 |
+| 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/tools/guide-data.js

@@ -77,7 +77,8 @@ export const ENTRY_POINTS = [
         customer_has: '自有的定妆图 / 场景图 / 道具图 / 镜头图(客户真实素材)',
         use: [
             'upload_image',
-            'set_character_portrait(须单人·单张单角度·无文字;换图后按 next_step 重出设定图,stale_frames 是要逐镜重生的镜)',
+            'set_character_portrait(须单人·单张单角度·无文字;换图后按 next_step 重出设定图,stale_frames 是要逐镜重生的镜;旧图只是解除引用不删除,old_assets 逐项列出)',
+            'clear_shot_frame(清掉某镜旧尾帧再重生视频,免得旧人物被尾帧带回来;解除引用不删文件,still_referenced_by 列出仍用这张图的镜)',
             'upload_scene_image(须空景无人·无叠加文字)',
             'upload_prop_sheet',
             'upload_shot_frame(只用于客户自有真实素材)',

package/dist/tools/produce.js

@@ -1080,6 +1080,9 @@ export function registerProduceTools(server, client) {
         '★换图后响应含 stale_frames=[{storyboard_id,storyboard_number,frames}]——这些镜的首帧还是旧定妆图生成的、已被污染。' +
         '要让新定妆图生效:对每个 stale_frame 用 quote_shot_frame+generate_shot_frame 重生该镜(平台会自动以新定妆图/设定图/人脸锁作锚,保全片一致)。' +
         '不必逐镜自己指定模型/首尾帧。★千万别自制首尾帧再 upload_shot_frame——外部图没有角色身份锚/画风锚,人物·服装·画风必漂,那才是废片根源(不是"杜绝废片")。' +
+        '★换图只是**解除引用**,旧定妆图/设定图的文件不会被删除。响应里的 old_assets 逐项列出被解除的旧资产:' +
+        'unlinked=[{kind,url,in_history}](in_history=false 表示平台没留记录——典型是客户上传的旧定妆图,要留就把 url 存下来),' +
+        'physically_deleted 恒为空。客户说「删掉旧图」时,如实告诉他只是不再使用、文件仍在,别说成已删除。' +
         '传本地文件(file_path,自动上传 COS)或已托管的图片 URL(image_url),二选一。登记免费;内容检查是一次小额视觉审核,按用量后付。', {
         character_id: z.number().int().positive(),
         file_path: z.string().optional().describe('本地定妆图路径(与 image_url 二选一;自动上传 COS)'),
@@ -1142,6 +1145,14 @@ export function registerProduceTools(server, client) {
         const video_url = await client.uploadLocalFile(file_path, 'footage');
         return jsonResult(await client.producePost(`/storyboards/${storyboard_id}/footage`, { video_url }));
     });
+    server.tool('clear_shot_frame', '清除某镜的尾帧(解除引用,免费)。用于换了定妆图/改了剧情后,旧尾帧会把旧人物/旧画面带进重生的视频时,先清掉它再 regenerate_shot_video。' +
+        '只能清尾帧:首帧是出视频的起点,要换首帧用 generate_shot_frame 重生或 upload_shot_frame 替换。' +
+        '★这是解除引用,不是删除:文件不会被删,响应里 unlinked[].in_history=true 的可在 get_asset_versions 找回,physically_deleted 恒为空——如实告诉客户。' +
+        '本镜已有视频会被标为过期(video_stale)。尾帧已定稿(pinned)会返回 409,客户确认后带 release_pin:true(会一并解除定稿);尾帧正在生成也会 409,等它结束再清。' +
+        '响应的 still_referenced_by 列出同剧仍在用这张图的其它镜(典型:下一镜首帧是它的裸拷贝)——这些不会被连带清掉,需要的话逐镜重生。', {
+        storyboard_id: z.number().int().positive(),
+        release_pin: z.boolean().optional().describe('尾帧已定稿时,客户确认后传 true:清除并解除定稿'),
+    }, async ({ storyboard_id, release_pin }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/frame/clear`, { frame_type: 'last_frame', ...(release_pin ? { release_pin: true } : {}) })));
     server.tool('clear_shot_footage', '清除某镜的实拍素材(video_url 置空、来源标记清掉),让这一镜恢复可 AI 生成视频。免费。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceDelete(`/storyboards/${storyboard_id}/footage`)));
     server.tool('upload_scene_image', '用客户自有图片作为某场景的场景图(空景基板·背景锚:同场景每一镜都锚在它上面)。自动上传+登记。' +
         '★★图片规范(登记前平台会自动检查,不合规返回 422 且不登记):**空景,画面里不能有任何人物**' +
@@ -1612,7 +1623,14 @@ export function registerProduceTools(server, client) {
         '前置:该角色已有定妆图。图片步,按用量后付不欠费。', { character_id: z.number().int().positive(), episode_id: z.number().int().positive().optional() }, async ({ character_id, episode_id }) => jsonResult(await client.producePost(`/characters/${character_id}/sheet`, episode_id ? { episode_id } : {})));
     server.tool('generate_prop_sheet', '给道具 AI 出设定图。图片步,按用量后付不欠费。', { prop_id: z.number().int().positive() }, async ({ prop_id }) => jsonResult(await client.producePost(`/props/${prop_id}/generate-sheet`)));
     // ========== 剧目级资产:道具库 CRUD + 色彩脚本/动作模板读取 ==========
-    server.tool('get_props', '列剧目道具库(每个道具名称/类型/描述/设定图)。★道具库≠广告商品库(add_product/list_products 是带货商品);道具库是剧目道具。免费。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/props`)));
+    server.tool('get_props', '列剧目道具库(每个道具名称/类型/描述/设定图)。★道具库≠广告商品库(add_product/list_products 是带货商品);道具库是剧目道具。免费。' +
+        '★每个道具带 era_audit(道具图的时代/形制审核结论,图换过则为 null):form_consistent=false 表示道具图与它的 era_lock 不符,' +
+        'conflicting_scopes 列出它被绑定却时代不合的场景/分集(scope 形如 scene:12 / episode:3),violations 点名具体冲突特征。' +
+        '有冲突时:先 update_prop 改 era_lock(写清朝代与形制)再 generate_prop_sheet 重出道具图;或者给那些镜换用合适的道具。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/props`)));
+    server.tool('audit_prop_era', '重审某个道具图的时代/形制(一次小额视觉审核,按用量后付)。依据该道具的 era_lock,以及它被绑定的各镜所在场景/分集的时代契约。' +
+        '跨时代剧(不同场景属于不同朝代/年代)出完或换完道具图后跑一次;结果同 get_props 里的 era_audit。' +
+        '道具还没有图、或既没写 era_lock 也没被绑到带时代契约的镜头上时返回 400(没有可比的依据)。' +
+        '只有点名了具体冲突特征才判冲突;笼统的「不像那个年代」不算。', { prop_id: z.number().int().positive() }, async ({ prop_id }) => jsonResult(await client.producePost(`/props/${prop_id}/era-audit`, {})));
     server.tool('create_prop', '往道具库加一个道具。extract_assets 会自动提取道具,这里供手动补建。跨时代剧建道具时就把 era_lock 填上(建完会自动触发出设定图,补填要重出才生效)。免费(建条目;填了 description 会自动触发出设定图、后付)。', {
         drama_id: z.number().int().positive(),
         name: z.string().min(1).describe('道具名'),
@@ -1629,7 +1647,8 @@ export function registerProduceTools(server, client) {
             .describe("道具级时代锁：这件道具属于哪个年代、材质工艺该读作什么年代（跨时代剧必填，否则名字中性的道具年代随机）。'' 清空"),
         episode_id: z.number().int().positive().optional(),
     }, async ({ drama_id, ...fields }) => jsonResult(await client.producePost(`/props`, { drama_id, ...fields })));
-    server.tool('update_prop', '改道具(名称/类型/描述/prompt/尺寸/多视角参考图/时代锁)。跨时代剧务必填 era_lock，否则名字中性的道具年代随机。免费。', {
+    server.tool('update_prop', '改道具(名称/类型/描述/prompt/尺寸/多视角参考图/时代锁)。跨时代剧务必填 era_lock，否则名字中性的道具年代随机。免费。' +
+        '★改了 era_lock 不会自动重出道具图——要 generate_prop_sheet 重出,重出后若 get_props 的 era_audit 为 null(还没审过新图),用 audit_prop_era 审一次。', {
         prop_id: z.number().int().positive(),
         name: z.string().optional(),
         type: z.string().optional(),

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.118",
-    "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.118 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.120",
+    "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.120 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -373,7 +373,7 @@
       "post": {
         "operationId": "set_character_portrait",
         "summary": "用客户自有图片作为角色定妆图(身份锚,优先级高于 AI 生成;之后 AI 重生默认不覆盖)",
-        "description": "用客户自有图片作为角色定妆图(身份锚,优先级高于 AI 生成;之后 AI 重生默认不覆盖)。★★图片规范(登记前平台会自动检查,不合规返回 422 且不登记):**只有该角色一人**(不能有其他人/合影/背景路人);**单张单一角度**(不是拼图/九宫格/多视角设定图——设定图由平台据定妆图生成);正面或 3/4 侧、面部清晰无遮挡、干净背景;**图上无任何文字**(水印/字幕/名字标签/logo/衣服印字都不行,字样会被复刻进每一镜)。上传前先看一眼客户给的图,不合规就先请客户换图,别直接传。被拒时把 message 里的问题原样告诉客户;只有客户看过问题后明确坚持用这张图,才带 allow_issues:true 重传(自动检查可能误判)。★换图会失效原有派生资产(设定图/多角度头像/发型·身材参考)并重建人脸锁,但**设定图不会自动重出**——换完必须 generate_character_sheet(character_id) 据新定妆图重出设定图(响应里的 next_step 会提示),否则该角色只剩定妆图一个锚。★换图后响应含 stale_frames=[{storyboard_id,storyboard_number,frames}]——这些镜的首帧还是旧定妆图生成的、已被污染。要让新定妆图生效:对每个 stale_frame 用 quote_shot_frame+generate_shot_frame 重生该镜(平台会自动以新定妆图/设定图/人脸锁作锚,保全片一致)。不必逐镜自己指定模型/首尾帧。★千万别自制首尾帧再 upload_shot_frame——外部图没有角色身份锚/画风锚,人物·服装·画风必漂,那才是废片根源(不是\"杜绝废片\")。传本地文件(file_path,自动上传 COS)或已托管的图片 URL(image_url),二选一。登记免费;内容检查是一次小额视觉审核,按用量后付。",
+        "description": "用客户自有图片作为角色定妆图(身份锚,优先级高于 AI 生成;之后 AI 重生默认不覆盖)。★★图片规范(登记前平台会自动检查,不合规返回 422 且不登记):**只有该角色一人**(不能有其他人/合影/背景路人);**单张单一角度**(不是拼图/九宫格/多视角设定图——设定图由平台据定妆图生成);正面或 3/4 侧、面部清晰无遮挡、干净背景;**图上无任何文字**(水印/字幕/名字标签/logo/衣服印字都不行,字样会被复刻进每一镜)。上传前先看一眼客户给的图,不合规就先请客户换图,别直接传。被拒时把 message 里的问题原样告诉客户;只有客户看过问题后明确坚持用这张图,才带 allow_issues:true 重传(自动检查可能误判)。★换图会失效原有派生资产(设定图/多角度头像/发型·身材参考)并重建人脸锁,但**设定图不会自动重出**——换完必须 generate_character_sheet(character_id) 据新定妆图重出设定图(响应里的 next_step 会提示),否则该角色只剩定妆图一个锚。★换图后响应含 stale_frames=[{storyboard_id,storyboard_number,frames}]——这些镜的首帧还是旧定妆图生成的、已被污染。要让新定妆图生效:对每个 stale_frame 用 quote_shot_frame+generate_shot_frame 重生该镜(平台会自动以新定妆图/设定图/人脸锁作锚,保全片一致)。不必逐镜自己指定模型/首尾帧。★千万别自制首尾帧再 upload_shot_frame——外部图没有角色身份锚/画风锚,人物·服装·画风必漂,那才是废片根源(不是\"杜绝废片\")。★换图只是**解除引用**,旧定妆图/设定图的文件不会被删除。响应里的 old_assets 逐项列出被解除的旧资产:unlinked=[{kind,url,in_history}](in_history=false 表示平台没留记录——典型是客户上传的旧定妆图,要留就把 url 存下来),physically_deleted 恒为空。客户说「删掉旧图」时,如实告诉他只是不再使用、文件仍在,别说成已删除。传本地文件(file_path,自动上传 COS)或已托管的图片 URL(image_url),二选一。登记免费;内容检查是一次小额视觉审核,按用量后付。",
         "tags": [
           "characters"
         ],
@@ -2576,7 +2576,7 @@
       "get": {
         "operationId": "get_props",
         "summary": "列剧目道具库(每个道具名称/类型/描述/设定图)",
-        "description": "列剧目道具库(每个道具名称/类型/描述/设定图)。★道具库≠广告商品库(add_product/list_products 是带货商品);道具库是剧目道具。免费。",
+        "description": "列剧目道具库(每个道具名称/类型/描述/设定图)。★道具库≠广告商品库(add_product/list_products 是带货商品);道具库是剧目道具。免费。★每个道具带 era_audit(道具图的时代/形制审核结论,图换过则为 null):form_consistent=false 表示道具图与它的 era_lock 不符,conflicting_scopes 列出它被绑定却时代不合的场景/分集(scope 形如 scene:12 / episode:3),violations 点名具体冲突特征。有冲突时:先 update_prop 改 era_lock(写清朝代与形制)再 generate_prop_sheet 重出道具图;或者给那些镜换用合适的道具。",
         "tags": [
           "dramas"
         ],
@@ -8722,7 +8722,7 @@
       "put": {
         "operationId": "update_prop",
         "summary": "改道具(名称/类型/描述/prompt/尺寸/多视角参考图/时代锁)",
-        "description": "改道具(名称/类型/描述/prompt/尺寸/多视角参考图/时代锁)。跨时代剧务必填 era_lock，否则名字中性的道具年代随机。免费。",
+        "description": "改道具(名称/类型/描述/prompt/尺寸/多视角参考图/时代锁)。跨时代剧务必填 era_lock，否则名字中性的道具年代随机。免费。★改了 era_lock 不会自动重出道具图——要 generate_prop_sheet 重出,重出后若 get_props 的 era_audit 为 null(还没审过新图),用 audit_prop_era 审一次。",
         "tags": [
           "props"
         ],
@@ -8848,6 +8848,64 @@
         }
       }
     },
+    "/props/{prop_id}/era-audit": {
+      "post": {
+        "operationId": "audit_prop_era",
+        "summary": "重审某个道具图的时代/形制(一次小额视觉审核,按用量后付)",
+        "description": "重审某个道具图的时代/形制(一次小额视觉审核,按用量后付)。依据该道具的 era_lock,以及它被绑定的各镜所在场景/分集的时代契约。跨时代剧(不同场景属于不同朝代/年代)出完或换完道具图后跑一次;结果同 get_props 里的 era_audit。道具还没有图、或既没写 era_lock 也没被绑到带时代契约的镜头上时返回 400(没有可比的依据)。只有点名了具体冲突特征才判冲突;笼统的「不像那个年代」不算。",
+        "tags": [
+          "props"
+        ],
+        "parameters": [
+          {
+            "name": "prop_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {}
+              }
+            }
+          }
+        },
+        "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"
+          }
+        }
+      }
+    },
     "/props/{prop_id}/generate-sheet": {
       "post": {
         "operationId": "generate_prop_sheet",
@@ -10424,6 +10482,72 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/frame/clear": {
+      "post": {
+        "operationId": "clear_shot_frame",
+        "summary": "清除某镜的尾帧(解除引用,免费)",
+        "description": "清除某镜的尾帧(解除引用,免费)。用于换了定妆图/改了剧情后,旧尾帧会把旧人物/旧画面带进重生的视频时,先清掉它再 regenerate_shot_video。只能清尾帧:首帧是出视频的起点,要换首帧用 generate_shot_frame 重生或 upload_shot_frame 替换。★这是解除引用,不是删除:文件不会被删,响应里 unlinked[].in_history=true 的可在 get_asset_versions 找回,physically_deleted 恒为空——如实告诉客户。本镜已有视频会被标为过期(video_stale)。尾帧已定稿(pinned)会返回 409,客户确认后带 release_pin:true(会一并解除定稿);尾帧正在生成也会 409,等它结束再清。响应的 still_referenced_by 列出同剧仍在用这张图的其它镜(典型:下一镜首帧是它的裸拷贝)——这些不会被连带清掉,需要的话逐镜重生。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "frame_type": {
+                    "type": "string",
+                    "description": "(assembled by the client from tool args — see tool 'clear_shot_frame')"
+                  },
+                  "release_pin": {
+                    "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"
+          }
+        }
+      }
+    },
     "/storyboards/{storyboard_id}/frame/generate": {
       "post": {
         "operationId": "generate_shot_frame",

package/package.json

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