@starreel/mcp 0.1.72 → 0.1.73

package/SKILL.md

@@ -479,9 +479,9 @@ Map the reason to an action:
 | `insufficient_credits` | false | Balance too low for this call | Stop, prompt to recharge (402) |
 | `authorizing` | true | Face frame queuing for KYC (not a rejection) | Wait ~1 min, retry |
 | `transient` | true | BestOfN / quality-gate / rate-limit / network, or the audit itself failed to run | Back off, retry |
-| `contract_rejected` | true | A **content/contract** rejection (era, composition, shot size, head-count, readable text…) — **not** a network blip. Measured: a blind re-roll clears it about a third of the time | Retry once or twice; if the same reason keeps coming back, read `fail_hint` and change the shot or the contract instead of re-rolling |
-| `needs_content_fix` | false | A content/contract conflict that a re-roll almost never clears (measured ≤10%) — most often the character's wardrobe/accessory record conflicting with the approved portrait | Change the shot description / character record / visual contract **first**, then regenerate. A blind retry is a full-price repeat |
-| `repeat_rejected` | false | Same shot rejected for the same reason until the circuit breaker tripped (auto-clears after 24 h) | Change the prompt / references / contract **first**; a blind retry is a full-price repeat of the same rejection |
+| `contract_rejected` | true | A **content/contract** rejection (era, composition, shot size, head-count, readable text…) — **not** a network blip. Measured: a blind re-roll clears it about a third of the time | Retry once or twice; if the same reason keeps coming back, read `fail_hint` and change the shot (see *What you can actually change* below) instead of re-rolling |
+| `needs_content_fix` | false | A content/contract conflict that a re-roll almost never clears (measured ≤10%) — most often the character's wardrobe/accessory record conflicting with the approved portrait | Change the shot description / character record **first**, then regenerate. A blind retry is a full-price repeat |
+| `repeat_rejected` | false | Same shot rejected for the same reason until the circuit breaker tripped (auto-clears after 24 h) | Change the prompt / references / shot design **first** (see *What you can actually change* below); a blind retry is a full-price repeat of the same rejection |
 | `pair_collateral` | true | The **other** frame of this shot failed its audit; this frame was never judged bad — it was only closed out with the batch | Do **not** edit this frame. If the shot carries `reopen_pair_id`, pass it to `generate_shot_frame` to redo only the faulty side; otherwise regenerate the shot |
 | `unknown` | false | Unclassified | Read `fail_hint`; don't auto-retry |
 
@@ -491,6 +491,41 @@ repeatedly** (the verdict is recorded, not enforced) — the URL looks like any
 frame, but it needs a human look. If it is not acceptable, fix the input the
 `hint` names and regenerate that frame with `generate_shot_frame`.
 
+### What you can actually change when a shot keeps getting rejected
+
+**There is no tool that edits `frame_visual_contract`, and there is not meant to
+be.** It is an internal per-frame contract (subject mode, visible head-count,
+framing) derived by the platform; it drives a dozen downstream judgements, so the
+facade deliberately strips it from every write path. Do not go looking for it,
+and do not tell the customer to "fix the contract" — they cannot, and neither can
+you. What you *can* change, in the order worth trying:
+
+1. **`update_shot`** — `shot_type`, `description`, `action`, and the two prompt
+   bodies. This is usually the real fix: a shot whose `image_prompt` describes a
+   head-and-shoulders portrait but whose `shot_type` says 特写 will keep failing
+   the shot-size gate until one of the two is corrected to match the other.
+2. **`character_ids`** on that shot — binding is *narrative* attribution, but an
+   over-bound shot inflates what the frame audit expects to see.
+3. **References** — `set_character_portrait` / wardrobe records, when the
+   rejection is identity- or costume-shaped.
+4. **`run_precheck` — and run it *after* the failures too, not only before.**
+   Its description sells it as a pre-flight check, but it is just as useful once
+   a shot is already stuck: it reports the repeat-rejection circuit breaker and
+   contract self-inconsistency for shots that have been failing. Then
+   `plan_precheck_fix` → show the customer → `apply_precheck_fix`.
+
+Two contract conflicts the platform now resolves **by itself** (v0.9.1868), so
+they are never something to act on: a part/prop/environment shot that also
+declares visible people, and a tight-framing shot that declares more people than
+the frame can hold. Both are silently normalised at read time.
+
+If a shot still will not come out, say so plainly and leave it — **do not send
+the customer to an outside image tool.** Frames made elsewhere bypass the
+identity anchor, reference assembly, best-of-N and frame audit, so faces,
+wardrobe and art style drift; the customer will read that drift as *the
+platform's* quality. `upload_shot_frame` exists for genuinely external artwork,
+not as an escape hatch from a rejection loop.
+
 Three action classes, one decision: **moderation / identity / copyright → change
 content**; **overdue / token → not self-healable (tell user / wait)**; **network
 / timeout / transient → retry**. Failed spends are auto-refunded (pre-hold →

package/dist/tools/produce.js

@@ -496,6 +496,9 @@ export function registerProduceTools(server, client) {
         '★**怎么改不用你猜**:调 plan_precheck_fix 让平台算出提案(哪一镜、把什么改成什么),' +
         '讲给客户、客户点头后用 apply_precheck_fix 落库——比你自己用 update_shot 盲改稳,' +
         '那条路绕开了乐观锁与落库前复核。部分类别系统不替你改(提案里的 blocked),那些才需要人工调。\n' +
+        '★★**镜已经反复出不来时也回来跑这个**——本工具不只是事前预检。' +
+        '它同时报「同镜同因连拒已熔断(repeat-reject,24h 自动解除)」与「帧契约自相矛盾」,' +
+        '那正是"这一镜怎么重掷都出不来"的答案。**别盲重掷**:熔断在档时每次重掷都是全价重复同一个拒绝。\n' +
         '⚠️ 它**不**检查首帧是否处在"动作发生前"(平台暂无该契约字段),也不替代 get_health_report。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/precheck`)));
     server.tool('plan_precheck_fix', '让平台**算出**该怎么改 run_precheck 揪出的「指令自相矛盾」类问题(第①步,只算不改)。'
         + '按文本用量计费(很小),不走报价确认。\n'
@@ -575,6 +578,10 @@ export function registerProduceTools(server, client) {
         '★响应里的 frames_planned 是**计划数,不是已成功数**——本接口在后台派发循环开跑之前就返回了。' +
         '真实进度只看 get_storyboards 的 first_frame_image / get_jobs 的逐条生成记录;' +
         '余额不足(402)会中止整批,此时轮询再久也不会有结果,应去查余额而不是继续等。' +
+        '★★**个别镜反复出不来、其余镜都好了**:那不是等得不够久,是这几镜被内容闸连拒。' +
+        '看 get_storyboards 的 fail_reason(repeat_rejected / needs_content_fix / contract_rejected),' +
+        '然后**跑 run_precheck**(事后也能跑,会告诉你是哪种矛盾),按它的提示用 update_shot 改景别/描述/绑定角色再重生。' +
+        '别继续 generate_frames 空转,也别把客户支去外部工具做图——外部图绕开身份锚与帧审计,人脸服装画风必漂。' +
         REVIEW_GATE_HINT('review_storyboards', '分镜') + CONFIRM_HINT, {
         episode_id: z.number().int().positive(),
         quote_id: z.string().describe('来自 quote_frames'),

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.72",
-    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → portraits & sheets → storyboards → 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). 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.72 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.73",
+    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → portraits & sheets → storyboards → 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). 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.73 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -4113,7 +4113,7 @@
       "post": {
         "operationId": "generate_frames",
         "summary": "确认后批量出帧:后台异步",
-        "description": "确认后批量出帧:后台异步。用 get_storyboards 轮询,first_frame_image/last_frame_image 逐镜填充即完成。★图片生成较慢——每张几十秒到数分钟(尤其高清模型),整集可能十几分钟。轮询看 frame_status:**pending=还在生成(继续耐心等,别当失败、别重复调 generate_frames,重复触发=白花钱)**、ready=完成、failed=才是真失败。别因为「等了一会儿还没出」就判定生成失败或重试。出视频前必须先出帧,否则视频会退化成无一致性锚点的画面。frame_type 要与 quote_frames 用的一致(默认 first_frame)。★这是**批量补缺帧**:只给「缺该帧」的镜出图,已有首帧的镜会跳过——这是正常设计、不是\"系统拒绝重出\"。要**重出/重画某一镜已有的帧**(如换了定妆图要让新图生效),用 generate_shot_frame(单镜重生,平台带身份锚),不是这个工具、更不是自制图 upload_shot_frame。★尾帧能批量出:frame_type=last_frame 会给「已有首帧且缺尾帧」的镜批量补尾帧(尾帧只在想固定某镜结尾画面/大运镜时才需,常规只出首帧)。★响应里的 frames_planned 是**计划数,不是已成功数**——本接口在后台派发循环开跑之前就返回了。真实进度只看 get_storyboards 的 first_frame_image / get_jobs 的逐条生成记录;余额不足(402)会中止整批,此时轮询再久也不会有结果,应去查余额而不是继续等。\n★【分镜审查硬闸·免费】本步前必须先调 review_storyboards:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。",
+        "description": "确认后批量出帧:后台异步。用 get_storyboards 轮询,first_frame_image/last_frame_image 逐镜填充即完成。★图片生成较慢——每张几十秒到数分钟(尤其高清模型),整集可能十几分钟。轮询看 frame_status:**pending=还在生成(继续耐心等,别当失败、别重复调 generate_frames,重复触发=白花钱)**、ready=完成、failed=才是真失败。别因为「等了一会儿还没出」就判定生成失败或重试。出视频前必须先出帧,否则视频会退化成无一致性锚点的画面。frame_type 要与 quote_frames 用的一致(默认 first_frame)。★这是**批量补缺帧**:只给「缺该帧」的镜出图,已有首帧的镜会跳过——这是正常设计、不是\"系统拒绝重出\"。要**重出/重画某一镜已有的帧**(如换了定妆图要让新图生效),用 generate_shot_frame(单镜重生,平台带身份锚),不是这个工具、更不是自制图 upload_shot_frame。★尾帧能批量出:frame_type=last_frame 会给「已有首帧且缺尾帧」的镜批量补尾帧(尾帧只在想固定某镜结尾画面/大运镜时才需,常规只出首帧)。★响应里的 frames_planned 是**计划数,不是已成功数**——本接口在后台派发循环开跑之前就返回了。真实进度只看 get_storyboards 的 first_frame_image / get_jobs 的逐条生成记录;余额不足(402)会中止整批,此时轮询再久也不会有结果,应去查余额而不是继续等。★★**个别镜反复出不来、其余镜都好了**:那不是等得不够久,是这几镜被内容闸连拒。看 get_storyboards 的 fail_reason(repeat_rejected / needs_content_fix / contract_rejected),然后**跑 run_precheck**(事后也能跑,会告诉你是哪种矛盾),按它的提示用 update_shot 改景别/描述/绑定角色再重生。别继续 generate_frames 空转,也别把客户支去外部工具做图——外部图绕开身份锚与帧审计,人脸服装画风必漂。\n★【分镜审查硬闸·免费】本步前必须先调 review_storyboards:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。",
         "tags": [
           "episodes"
         ],
@@ -4755,7 +4755,7 @@
       "get": {
         "operationId": "run_precheck",
         "summary": "(★推荐·免费质量闸)出图/出视频前跑生成前预检,把会被拒的镜提前揪出",
-        "description": "(★推荐·免费质量闸)出图/出视频前跑生成前预检,把会被拒的镜提前揪出。免费、不扣费。强烈建议 generate_frames/generate_videos 前调,防白花钱被拒。\n查这几类:①真人肖像/克隆音色授权 ②图像审核高危词 ③配音覆盖与大空档 ④**指令自相矛盾(kind=prompt-conflict)**——同一镜里互斥的要求(如宽景别却标了特写主体、既要站立又要坐姿),这类镜**任何正确的图都满足不了**,不改就会反复被拒并反复扣费,出现时应先按提示改分镜再出图,而不是重试。\n★**怎么改不用你猜**:调 plan_precheck_fix 让平台算出提案(哪一镜、把什么改成什么),讲给客户、客户点头后用 apply_precheck_fix 落库——比你自己用 update_shot 盲改稳,那条路绕开了乐观锁与落库前复核。部分类别系统不替你改(提案里的 blocked),那些才需要人工调。\n⚠️ 它**不**检查首帧是否处在\"动作发生前\"(平台暂无该契约字段),也不替代 get_health_report。",
+        "description": "(★推荐·免费质量闸)出图/出视频前跑生成前预检,把会被拒的镜提前揪出。免费、不扣费。强烈建议 generate_frames/generate_videos 前调,防白花钱被拒。\n查这几类:①真人肖像/克隆音色授权 ②图像审核高危词 ③配音覆盖与大空档 ④**指令自相矛盾(kind=prompt-conflict)**——同一镜里互斥的要求(如宽景别却标了特写主体、既要站立又要坐姿),这类镜**任何正确的图都满足不了**,不改就会反复被拒并反复扣费,出现时应先按提示改分镜再出图,而不是重试。\n★**怎么改不用你猜**:调 plan_precheck_fix 让平台算出提案(哪一镜、把什么改成什么),讲给客户、客户点头后用 apply_precheck_fix 落库——比你自己用 update_shot 盲改稳,那条路绕开了乐观锁与落库前复核。部分类别系统不替你改(提案里的 blocked),那些才需要人工调。\n★★**镜已经反复出不来时也回来跑这个**——本工具不只是事前预检。它同时报「同镜同因连拒已熔断(repeat-reject,24h 自动解除)」与「帧契约自相矛盾」,那正是\"这一镜怎么重掷都出不来\"的答案。**别盲重掷**:熔断在档时每次重掷都是全价重复同一个拒绝。\n⚠️ 它**不**检查首帧是否处在\"动作发生前\"(平台暂无该契约字段),也不替代 get_health_report。",
         "tags": [
           "episodes"
         ],

package/package.json

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