@starreel/mcp 0.1.135 → 0.1.136

package/SKILL.md

@@ -1103,7 +1103,7 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
 - **Audio**: `generate_tts` (required before final cut), `clone_voice`,
   `design_voice` → `get_voice_design` → `save_designed_voice` (no sample needed),
   `speak_with_voice`, `set_character_voice`, `list_voices`, `delete_voice`,
-  `generate_bgm` (optional `prompt` steers the music; read `get_bgm_prompt_guide` first; optional `director` hard-locks mood / instruments / bpm / tonality for the whole episode or per act — call the free read-only `get_bgm_plan` first to see the acts; to let the client pick between full-length versions, `quote_bgm_candidates` → `generate_bgm` with `candidates` 2–3 + `quote_id` → `select_bgm_candidate`, each candidate billed per song),
+  `generate_bgm` (optional `prompt` steers the music; read `get_bgm_prompt_guide` first; optional `director` hard-locks mood / instruments / bpm / tonality for the whole episode or per act (saved per episode like `prompt`: omit it to reuse the last one, pass `null` to clear) — call the free read-only `get_bgm_plan` first to see the acts; to let the client pick between full-length versions, `quote_bgm_candidates` → `generate_bgm` with `candidates` 2–3 + `quote_id` → `select_bgm_candidate`, each candidate billed per song),
   `get_bgm_prompt_guide`, `replace_shot_dialogue`, `revoice_narration`
 - **Mix** (free; settings only — `compose_episode` again to hear them, `rerender_episode`
   reuses the old timeline): whole drama via `update_project_settings`

package/dist/tools/guide-data.js

@@ -290,7 +290,7 @@ export const OPTIONAL_BOOSTS = [
     { what: '口型同步', tool: 'lipsync_episode', when: 'TTS 配音项目需要对口型时' },
     { what: '海报 / 封面', tool: 'generate_episode_poster', when: '成片后;`generate_drama_poster` / `generate_cover` 同族' },
     { what: '音效 / 特效 / 转场(本地库匹配)', tool: 'generate_sfx', when: '免费;`generate_effects` / `generate_transitions` 同族' },
-    { what: '配乐', tool: 'generate_bgm', when: '按整集情绪弧线生成;终拼自动接管。客户想指定音乐方向就带 prompt(整集一条),写法先读 `get_bgm_prompt_guide`(免费);不带 prompt 就是全自动。客户给了明确参数(情绪/主奏配器/BPM/大小调)用 director 锁定(硬约束,可按幕;按幕前先 get_bgm_plan 免费看分幕)。客户想先听几版再定:candidates=2~3 出完整候选(每首单独计费,先 quote_bgm_candidates 报价),select_bgm_candidate 挑' },
+    { what: '配乐', tool: 'generate_bgm', when: '按整集情绪弧线生成;终拼自动接管。客户想指定音乐方向就带 prompt(整集一条),写法先读 `get_bgm_prompt_guide`(免费);不带 prompt 就是全自动。客户给了明确参数(情绪/主奏配器/BPM/大小调)用 director 锁定(硬约束,按集保存、下次不传沿用,可按幕;按幕前先 get_bgm_plan 免费看分幕)。客户想先听几版再定:candidates=2~3 出完整候选(每首单独计费,先 quote_bgm_candidates 报价),select_bgm_candidate 挑' },
     { what: '字幕翻译', tool: 'translate_subtitles', when: '出海;双语烧录在项目设定里开' },
 ];
 export const BILLING = {

package/dist/tools/produce.js

@@ -1488,6 +1488,8 @@ export function registerProduceTools(server, client) {
         '★director 可选=结构化锁定(硬约束):逐项指定 mood 情绪 / instruments 主奏配器 / bpm / tonality 大小调,' +
         '生成时**强制覆盖**配乐总监的判断(不像 prompt 只是方向,可能被护栏或 AI 取舍改写);没锁的项仍自动判断。' +
         '整集锁写在 director 顶层;只锁某一幕写进 director.acts[{act,…}](同名字段覆盖整集的)。' +
+        '★director 按集保存(同 prompt):这次传了就记下,下次不传沿用上次的(get_bgm_status 的 director 可查);传 null 清除。' +
+        '分镜改动后已存的幕号不存在了,那一条会被忽略并在 director_warnings 里说明,不拦生成。' +
         '幕是按情绪弧线自动分的:按幕锁之前先调 get_bgm_plan(免费,只读)看本集分几幕、每幕覆盖哪些镜。' +
         '参数拼错(bpm 越界、调性不是 major/minor/modal、幕号不存在)会 400;配器里写人声/环境声会被丢掉并在 director_warnings 点名。' +
         '客户说「要慢一点、小调、用古筝」这类**明确参数**用 director;说「整体更压抑」这类**方向**用 prompt;两者可同时用。\n' +
@@ -1508,11 +1510,11 @@ export function registerProduceTools(server, client) {
                 ...BGM_LOCK_FIELDS,
             }).strict()).optional().describe('按幕锁定;同名字段覆盖整集的,没写的继承整集'),
             // strict:拼错的字段(如 tempo)要报校验错误;zod 默认会静默剥掉它,转发出去的就是空锁 ⇒ 一次不受控的扣费生成
-        }).strict().optional().describe('结构化锁定(硬约束)。顶层字段整集生效;不传=全由配乐总监判断'),
+        }).strict().nullable().optional().describe('结构化锁定(硬约束),按集保存:传了就记下,下次不传沿用上次的;传 null 清除。顶层字段整集生效'),
     }, async ({ episode_id, prompt, prompt_mode, director, candidates, quote_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/bgm`, {
         ...(prompt === undefined ? {} : { prompt }),
         ...(prompt_mode ? { prompt_mode } : {}),
-        ...(director ? { director } : {}),
+        ...(director === undefined ? {} : { director }),
         ...(candidates === undefined ? {} : { candidates }),
         ...(quote_id ? { quote_id } : {}),
     })));

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.135",
-    "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.135 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.136",
+    "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.136 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -3693,7 +3693,7 @@
       "post": {
         "operationId": "generate_bgm",
         "summary": "给整集生成/更换 AI 配乐(按情绪弧线)",
-        "description": "给整集生成/更换 AI 配乐(按情绪弧线)。后台异步,按用量后付不欠费。返回情绪弧线段数与预估耗时;用 get_bgm_status 轮询生成进度。★配乐生成/改动**不会自动进已有成片**——完成后必须重新 compose_episode(免费)才能听到;get_final_cut 的 bgm_stale=true 就是在提示这一步。别用 re-render(吃旧时间线,不含新配乐)。\n★prompt 可选:不传=全自动(和以前一样)。传了就是在自动结果上再加方向,整集一条,系统仍按情绪弧线分幕。怎么写见 get_bgm_prompt_guide(免费);要点=只写音乐维度(情绪气质/主奏配器/速度动态/厚薄空间/风格参照),别写剧情(「主角发现真相时要紧张」→写「紧张,节奏推进感强」)。只出纯器乐:要人声/歌词/拟音当乐器都不会生效,会在 prompt_warnings 里点名但**不拦生成**。\n★prompt_mode: guide(默认)=你的要求与平台专业护栏(时代与题材匹配/配器节制/高潮保规模/段间差异)一起生效;override=直通,跳过护栏,只保留技术底线(纯器乐/时长/可循环)。override 效果自负,**先用 guide 试**,确实拧不过来再换。不传 prompt 时沿用该集上次填的(get_bgm_status 可查)。\n★director 可选=结构化锁定(硬约束):逐项指定 mood 情绪 / instruments 主奏配器 / bpm / tonality 大小调,生成时**强制覆盖**配乐总监的判断(不像 prompt 只是方向,可能被护栏或 AI 取舍改写);没锁的项仍自动判断。整集锁写在 director 顶层;只锁某一幕写进 director.acts[{act,…}](同名字段覆盖整集的)。幕是按情绪弧线自动分的:按幕锁之前先调 get_bgm_plan(免费,只读)看本集分几幕、每幕覆盖哪些镜。参数拼错(bpm 越界、调性不是 major/minor/modal、幕号不存在)会 400;配器里写人声/环境声会被丢掉并在 director_warnings 点名。客户说「要慢一点、小调、用古筝」这类**明确参数**用 director;说「整体更压抑」这类**方向**用 prompt;两者可同时用。\n★candidates 可选=候选整版对比:每幕出 2~3 首**完整**候选让客户挑(挑中的直接用,听到什么成片里就是什么)。每首单独按首计费 ⇒ 费用是单首的 N 倍,**必须先 quote_bgm_candidates 报价、把点数告诉客户、客户同意后**带 quote_id 调本工具。不传或传 1=原行为(每幕一首,无需报价)。生成后 get_bgm_status 的 candidate_groups 给每首的试听地址,select_bgm_candidate 挑选(免费),不挑默认第 1 首。",
+        "description": "给整集生成/更换 AI 配乐(按情绪弧线)。后台异步,按用量后付不欠费。返回情绪弧线段数与预估耗时;用 get_bgm_status 轮询生成进度。★配乐生成/改动**不会自动进已有成片**——完成后必须重新 compose_episode(免费)才能听到;get_final_cut 的 bgm_stale=true 就是在提示这一步。别用 re-render(吃旧时间线,不含新配乐)。\n★prompt 可选:不传=全自动(和以前一样)。传了就是在自动结果上再加方向,整集一条,系统仍按情绪弧线分幕。怎么写见 get_bgm_prompt_guide(免费);要点=只写音乐维度(情绪气质/主奏配器/速度动态/厚薄空间/风格参照),别写剧情(「主角发现真相时要紧张」→写「紧张,节奏推进感强」)。只出纯器乐:要人声/歌词/拟音当乐器都不会生效,会在 prompt_warnings 里点名但**不拦生成**。\n★prompt_mode: guide(默认)=你的要求与平台专业护栏(时代与题材匹配/配器节制/高潮保规模/段间差异)一起生效;override=直通,跳过护栏,只保留技术底线(纯器乐/时长/可循环)。override 效果自负,**先用 guide 试**,确实拧不过来再换。不传 prompt 时沿用该集上次填的(get_bgm_status 可查)。\n★director 可选=结构化锁定(硬约束):逐项指定 mood 情绪 / instruments 主奏配器 / bpm / tonality 大小调,生成时**强制覆盖**配乐总监的判断(不像 prompt 只是方向,可能被护栏或 AI 取舍改写);没锁的项仍自动判断。整集锁写在 director 顶层;只锁某一幕写进 director.acts[{act,…}](同名字段覆盖整集的)。★director 按集保存(同 prompt):这次传了就记下,下次不传沿用上次的(get_bgm_status 的 director 可查);传 null 清除。分镜改动后已存的幕号不存在了,那一条会被忽略并在 director_warnings 里说明,不拦生成。幕是按情绪弧线自动分的:按幕锁之前先调 get_bgm_plan(免费,只读)看本集分几幕、每幕覆盖哪些镜。参数拼错(bpm 越界、调性不是 major/minor/modal、幕号不存在)会 400;配器里写人声/环境声会被丢掉并在 director_warnings 点名。客户说「要慢一点、小调、用古筝」这类**明确参数**用 director;说「整体更压抑」这类**方向**用 prompt;两者可同时用。\n★candidates 可选=候选整版对比:每幕出 2~3 首**完整**候选让客户挑(挑中的直接用,听到什么成片里就是什么)。每首单独按首计费 ⇒ 费用是单首的 N 倍,**必须先 quote_bgm_candidates 报价、把点数告诉客户、客户同意后**带 quote_id 调本工具。不传或传 1=原行为(每幕一首,无需报价)。生成后 get_bgm_status 的 candidate_groups 给每首的试听地址,select_bgm_candidate 挑选(免费),不挑默认第 1 首。",
         "tags": [
           "episodes"
         ],
@@ -3726,90 +3726,97 @@
                     ]
                   },
                   "director": {
-                    "type": "object",
-                    "properties": {
-                      "mood": {
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        },
-                        "maxItems": 3,
-                        "description": "情绪词,最多 3 个,每个 ≤12 字(如 压抑、苍凉)"
-                      },
-                      "instruments": {
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        },
-                        "maxItems": 3,
-                        "description": "主奏乐器,最多 3 件,每件 ≤16 字(如 古筝、大提琴);人声/环境声会被丢掉"
-                      },
-                      "bpm": {
-                        "type": "number",
-                        "minimum": 40,
-                        "maximum": 160,
-                        "description": "速度 40~160"
-                      },
-                      "tonality": {
-                        "type": "string",
-                        "enum": [
-                          "major",
-                          "minor",
-                          "modal"
-                        ],
-                        "description": "major 大调明亮 / minor 小调暗色 / modal 调式色彩"
-                      },
-                      "acts": {
-                        "type": "array",
-                        "items": {
-                          "type": "object",
-                          "properties": {
-                            "act": {
-                              "type": "integer",
-                              "exclusiveMinimum": 0,
-                              "description": "幕序号,从 1 开始(get_bgm_plan 可查)"
+                    "anyOf": [
+                      {
+                        "type": "object",
+                        "properties": {
+                          "mood": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
                             },
-                            "mood": {
-                              "type": "array",
-                              "items": {
-                                "type": "string"
-                              },
-                              "maxItems": 3,
-                              "description": "情绪词,最多 3 个,每个 ≤12 字(如 压抑、苍凉)"
+                            "maxItems": 3,
+                            "description": "情绪词,最多 3 个,每个 ≤12 字(如 压抑、苍凉)"
+                          },
+                          "instruments": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
                             },
-                            "instruments": {
-                              "type": "array",
-                              "items": {
-                                "type": "string"
+                            "maxItems": 3,
+                            "description": "主奏乐器,最多 3 件,每件 ≤16 字(如 古筝、大提琴);人声/环境声会被丢掉"
+                          },
+                          "bpm": {
+                            "type": "number",
+                            "minimum": 40,
+                            "maximum": 160,
+                            "description": "速度 40~160"
+                          },
+                          "tonality": {
+                            "type": "string",
+                            "enum": [
+                              "major",
+                              "minor",
+                              "modal"
+                            ],
+                            "description": "major 大调明亮 / minor 小调暗色 / modal 调式色彩"
+                          },
+                          "acts": {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "properties": {
+                                "act": {
+                                  "type": "integer",
+                                  "exclusiveMinimum": 0,
+                                  "description": "幕序号,从 1 开始(get_bgm_plan 可查)"
+                                },
+                                "mood": {
+                                  "type": "array",
+                                  "items": {
+                                    "type": "string"
+                                  },
+                                  "maxItems": 3,
+                                  "description": "情绪词,最多 3 个,每个 ≤12 字(如 压抑、苍凉)"
+                                },
+                                "instruments": {
+                                  "type": "array",
+                                  "items": {
+                                    "type": "string"
+                                  },
+                                  "maxItems": 3,
+                                  "description": "主奏乐器,最多 3 件,每件 ≤16 字(如 古筝、大提琴);人声/环境声会被丢掉"
+                                },
+                                "bpm": {
+                                  "type": "number",
+                                  "minimum": 40,
+                                  "maximum": 160,
+                                  "description": "速度 40~160"
+                                },
+                                "tonality": {
+                                  "type": "string",
+                                  "enum": [
+                                    "major",
+                                    "minor",
+                                    "modal"
+                                  ],
+                                  "description": "major 大调明亮 / minor 小调暗色 / modal 调式色彩"
+                                }
                               },
-                              "maxItems": 3,
-                              "description": "主奏乐器,最多 3 件,每件 ≤16 字(如 古筝、大提琴);人声/环境声会被丢掉"
-                            },
-                            "bpm": {
-                              "type": "number",
-                              "minimum": 40,
-                              "maximum": 160,
-                              "description": "速度 40~160"
-                            },
-                            "tonality": {
-                              "type": "string",
-                              "enum": [
-                                "major",
-                                "minor",
-                                "modal"
+                              "required": [
+                                "act"
                               ],
-                              "description": "major 大调明亮 / minor 小调暗色 / modal 调式色彩"
-                            }
-                          },
-                          "required": [
-                            "act"
-                          ],
-                          "additionalProperties": false
+                              "additionalProperties": false
+                            },
+                            "description": "按幕锁定;同名字段覆盖整集的,没写的继承整集"
+                          }
                         },
-                        "description": "按幕锁定;同名字段覆盖整集的,没写的继承整集"
+                        "additionalProperties": false
+                      },
+                      {
+                        "type": "null"
                       }
-                    },
-                    "additionalProperties": false
+                    ]
                   },
                   "candidates": {
                     "type": "integer",

package/package.json

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