@starreel/mcp 0.1.94 → 0.1.95

package/SKILL.md

@@ -959,6 +959,25 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   `get_bgm_prompt_guide`, `replace_shot_dialogue`
 - **Finish**: `compose_episode`, `get_final_cut`, `get_export`,
   `generate_episode_poster`, `generate_cover`
+- **What did this drama cost?** `get_drama_bill` — per kind `charged` / `refunded`
+  / `net`. **`net` is the spend** (same number as the web "spent on this drama"
+  and `get_budget_status`); `charged` includes failed calls that were refunded
+  automatically, so never report it as cost. `in_flight` = charged, result not
+  out yet (the platform charges on submit and refunds on failure — there is no
+  separate hold). `rework.video` = second-and-later successful videos of the
+  same shot. `account_level` = voice clones / designs / auditions that belong to
+  no drama — listed separately, **not** in the drama's total. Build a cost
+  write-up from this, not from your own tally.
+- **Every platform cut is versioned automatically.** Each `compose_episode` /
+  `rerender_episode` / multi-aspect render registers a `source=platform` entry in
+  `list_deliveries`: file sha256, and a manifest of what that render actually
+  used — per shot whether it was the raw clip, the composed clip, the re-voiced
+  clip or the lip-synced one (`source_kind`), which dialogue / music / SFX files,
+  subtitle count and text hash, plus the dialogue-audit tally at that moment.
+  Write delivery notes and "which version did we ship" answers **from that
+  manifest**, not from memory — notes written for v1 silently go stale by v4.
+  Platform entries never become the current delivery on their own;
+  `set_current_delivery` the one the customer actually gets.
 - **Delivered a cut you finished outside the platform** (re-voiced lines, trims,
   an ending card, music): `register_external_delivery` the exact file you hand to
   the customer — **every time**, including revisions. Otherwise the platform's

package/dist/tools/produce.js

@@ -745,7 +745,8 @@ export function registerProduceTools(server, client) {
     }, async ({ episode_id, force }) => jsonResult(await client.producePost(`/episodes/${episode_id}/compose`, force ? { force: true } : {})));
     server.tool('get_final_cut', '查某一集成片状态与下载链接。status=completed 时返回 download_url(我方 COS 直链,可直接下载)。免费。' +
         '★bgm_stale=true 表示配乐在成片之后生成/改动、尚未进成片:重新 compose_episode(免费)即可,别用 re-render。' +
-        '★若登记过外部交付版本(register_external_delivery),另返回 delivery——那才是客户实际收到的一版;download_url 仍是平台自己拼的成片。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/final-cut`)));
+        '★若设过当前交付版(register_external_delivery 登记的外部版,或 set_current_delivery 指定的平台版),另返回 delivery——那才是客户实际收到的一版;download_url 仍是平台最新一次拼的成片。' +
+        '要看每一版成片用了什么、哈希是多少,用 list_deliveries。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/final-cut`)));
     server.tool('get_export', '查某一集导出/母版状态(成片终拼后的可下载母版)。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/export`)));
     server.tool('review_final_cut', '**成片体检**:导出前把整集过一遍——没出图的镜、字幕一屏放不下、人物没有身份锚、'
         + '镜头连续性(跳轴)、以及一次错别字通读。'
@@ -1062,8 +1063,14 @@ export function registerProduceTools(server, client) {
             throw new Error('file_path 与 file_url 必须给一个');
         return jsonResult(await client.producePost(`/episodes/${episode_id}/deliveries`, { file_url: url, note, manifest }));
     });
-    server.tool('list_deliveries', '列本集已登记的外部交付版本(新→旧),每条含 sha256、时长、is_current 与完整交付清单(每镜来源 + 外部后期说明)。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/deliveries`)));
-    server.tool('set_current_delivery', '把本集的某个已登记交付版本设为当前(例如客户最终选了较早的一版)。免费。只影响 get_final_cut 的 delivery,不改平台成片。', { episode_id: z.number().int().positive(), delivery_id: z.number().int().positive() }, async ({ episode_id, delivery_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/deliveries/${delivery_id}/current`)));
+    server.tool('list_deliveries', '列本集**所有成片版本**(新→旧,平台成片与外部交付共用一条版本号),每条含 sha256、时长、is_current 与完整清单。免费。' +
+        '\n★source=platform:平台每出一版成片(compose_episode / rerender_episode / 多画幅)都会**自动登记**,清单记的是**渲染用的那份时间线**——' +
+        '每镜用的是原片/合成片/换轨产物/口型产物(source_kind)、对白/配乐/音效各用了哪些文件、字幕条数与文本哈希、文件 sha256,' +
+        '以及登记时刻的台词审计分族计数。写交付说明、核对「交出去的是哪一版」以它为准,别凭记忆。' +
+        '平台版本**不会自动成为当前交付版**;客户选定哪一版,用 set_current_delivery 指过去。' +
+        '\n★source=external:register_external_delivery 登记的外部后期成片。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/deliveries`)));
+    server.tool('set_current_delivery', '把本集的某个成片版本设为当前交付版(例如客户最终选了较早的一版)。免费。平台版本(source=platform)与外部版本都可以设。' +
+        '只影响 get_final_cut 的 delivery,不改平台成片。', { episode_id: z.number().int().positive(), delivery_id: z.number().int().positive() }, async ({ episode_id, delivery_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/deliveries/${delivery_id}/current`)));
     server.tool('upload_shot_footage', '用**客户自有的整段视频**（录屏 / 产品实拍 / 第三方成片）直接当某镜的视频——实拍素材镜。' +
         '登记后该镜不再 AI 出图/出视频（generate_videos 会跳过它,单镜重生会被拒),终拼原样使用,镜头时长按素材真实长度回写,' +
         '首/尾帧从素材抽帧供帧链与预览用。免费。适用:宣传片里的到账界面录屏、后台大屏实录、产品实拍、客户已有的成片片段。' +
@@ -1370,6 +1377,13 @@ export function registerProduceTools(server, client) {
     // ========== P1 · 任务进度 + 成本/预算 ==========
     server.tool('get_jobs', '查一部剧的任务队列进度(出图/出视频/合成各阶段的 pending/processing/done/failed)。' +
         '异步生成后用它看进度。免费。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/jobs`)));
+    server.tool('get_drama_bill', '本剧净费用账单(免费)。核账、回答「到底花了多少、钱花在哪、退了多少」时用它,别自己拼流水。' +
+        '\n· totals / by_kind:每类 charged(扣费)、refunded(已退回)、net(净额)、charges/refunds(笔数)。' +
+        '**net 才是花费**,与网页「本剧已花费」、get_budget_status 同源;charged 含失败后自动退回的空转,只用于核账。' +
+        '\n· in_flight:已扣费、结果还没出的任务(平台是提交即扣、失败再退,没有单独的预扣)。' +
+        '\n· rework.video:同一镜第 2 次起的成功出片(返工);出图不计(首帧/尾帧/best-of-N 候选本来就是同镜多张)。' +
+        '\n· account_level:音色库克隆/设计/试听等**不属于任何一部剧**的语音扣费,单列、counted_in_drama=false,不计入本剧。' +
+        '\n· available=false:账本暂时不可达,不给数字(不拿估算冒充),稍后重试。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/bill`)));
     server.tool('get_cost_estimate', '查一部剧的整体成本预估(点数)。免费。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/cost-estimate`)));
     server.tool('get_budget_status', '查一部剧的预算状态(预算/已花费/剩余)。免费。' +
         'spent 与网页「本剧已花费」同源(平台扣费账本净额,已减退款),by_kind 为按类分项(ai_image/ai_video/ai_text/ai_music/tts_local…)。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.94",
-    "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.94 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.95",
+    "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.95 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -1301,6 +1301,53 @@
         }
       }
     },
+    "/dramas/{drama_id}/bill": {
+      "get": {
+        "operationId": "get_drama_bill",
+        "summary": "本剧净费用账单(免费)",
+        "description": "本剧净费用账单(免费)。核账、回答「到底花了多少、钱花在哪、退了多少」时用它,别自己拼流水。\n· totals / by_kind:每类 charged(扣费)、refunded(已退回)、net(净额)、charges/refunds(笔数)。**net 才是花费**,与网页「本剧已花费」、get_budget_status 同源;charged 含失败后自动退回的空转,只用于核账。\n· in_flight:已扣费、结果还没出的任务(平台是提交即扣、失败再退,没有单独的预扣)。\n· rework.video:同一镜第 2 次起的成功出片(返工);出图不计(首帧/尾帧/best-of-N 候选本来就是同镜多张)。\n· account_level:音色库克隆/设计/试听等**不属于任何一部剧**的语音扣费,单列、counted_in_drama=false,不计入本剧。\n· available=false:账本暂时不可达,不给数字(不拿估算冒充),稍后重试。",
+        "tags": [
+          "dramas"
+        ],
+        "parameters": [
+          {
+            "name": "drama_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "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}/budget-status": {
       "get": {
         "operationId": "get_budget_status",
@@ -3326,8 +3373,8 @@
     "/episodes/{episode_id}/deliveries": {
       "get": {
         "operationId": "list_deliveries",
-        "summary": "列本集已登记的外部交付版本(新→旧),每条含 sha256、时长、is_current 与完整交付清单(每镜来源 + 外部后期说明)",
-        "description": "列本集已登记的外部交付版本(新→旧),每条含 sha256、时长、is_current 与完整交付清单(每镜来源 + 外部后期说明)。免费。",
+        "summary": "列本集**所有成片版本**(新→旧,平台成片与外部交付共用一条版本号),每条含 sha256、时长、is_current 与完整清单",
+        "description": "列本集**所有成片版本**(新→旧,平台成片与外部交付共用一条版本号),每条含 sha256、时长、is_current 与完整清单。免费。\n★source=platform:平台每出一版成片(compose_episode / rerender_episode / 多画幅)都会**自动登记**,清单记的是**渲染用的那份时间线**——每镜用的是原片/合成片/换轨产物/口型产物(source_kind)、对白/配乐/音效各用了哪些文件、字幕条数与文本哈希、文件 sha256,以及登记时刻的台词审计分族计数。写交付说明、核对「交出去的是哪一版」以它为准,别凭记忆。平台版本**不会自动成为当前交付版**;客户选定哪一版,用 set_current_delivery 指过去。\n★source=external:register_external_delivery 登记的外部后期成片。",
         "tags": [
           "episodes"
         ],
@@ -3373,8 +3420,8 @@
     "/episodes/{episode_id}/deliveries/{delivery_id}/current": {
       "post": {
         "operationId": "set_current_delivery",
-        "summary": "把本集的某个已登记交付版本设为当前(例如客户最终选了较早的一版)",
-        "description": "把本集的某个已登记交付版本设为当前(例如客户最终选了较早的一版)。免费。只影响 get_final_cut 的 delivery,不改平台成片。",
+        "summary": "把本集的某个成片版本设为当前交付版(例如客户最终选了较早的一版)",
+        "description": "把本集的某个成片版本设为当前交付版(例如客户最终选了较早的一版)。免费。平台版本(source=platform)与外部版本都可以设。只影响 get_final_cut 的 delivery,不改平台成片。",
         "tags": [
           "episodes"
         ],
@@ -4316,7 +4363,7 @@
       "get": {
         "operationId": "get_final_cut",
         "summary": "查某一集成片状态与下载链接",
-        "description": "查某一集成片状态与下载链接。status=completed 时返回 download_url(我方 COS 直链,可直接下载)。免费。★bgm_stale=true 表示配乐在成片之后生成/改动、尚未进成片:重新 compose_episode(免费)即可,别用 re-render。★若登记过外部交付版本(register_external_delivery),另返回 delivery——那才是客户实际收到的一版;download_url 仍是平台自己拼的成片。",
+        "description": "查某一集成片状态与下载链接。status=completed 时返回 download_url(我方 COS 直链,可直接下载)。免费。★bgm_stale=true 表示配乐在成片之后生成/改动、尚未进成片:重新 compose_episode(免费)即可,别用 re-render。★若设过当前交付版(register_external_delivery 登记的外部版,或 set_current_delivery 指定的平台版),另返回 delivery——那才是客户实际收到的一版;download_url 仍是平台最新一次拼的成片。要看每一版成片用了什么、哈希是多少,用 list_deliveries。",
         "tags": [
           "episodes"
         ],

package/package.json

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