@starreel/mcp 0.1.31 → 0.1.33

package/dist/tools/produce.js

@@ -154,7 +154,9 @@ export function registerProduceTools(server, client) {
     // ---------- AI 改写 / 审阅 / 改稿 ----------
     server.tool('rewrite_script', 'AI 改写:把原始剧本改写成可拍稿(读 content → 写 script_content)。按项目类型自动选改写 agent' +
         '(广告走 ad 改写;MV 不走标准改写会被拦)。后台异步(分钟级),文本步按 token 后付、不欠费,无需报价。' +
-        '完成后用 get_script 审阅、edit_rewritten_script 改稿。' + WORKFLOW_HINT, { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/rewrite`)));
+        '完成后用 get_script 审阅、edit_rewritten_script 改稿。' +
+        '★典型耗时 2~4 分钟(生产实测 ≈169 秒)。**60 秒内查不到结果是正常的,不是失败**——' +
+        '用 get_run_status 判断还在不在跑,别急着重发。' + WORKFLOW_HINT, { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/rewrite`)));
     server.tool('get_script', '读某一集的原始内容 + AI 改写后的可拍稿 + 改写状态(供审阅、决定是否 edit_rewritten_script)。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/script`)));
     server.tool('edit_rewritten_script', '客户改 AI 改写后的可拍稿(写 script_content)。用于人工润色/纠正 AI 改写结果。免费。', {
         episode_id: z.number().int().positive(),
@@ -162,7 +164,8 @@ export function registerProduceTools(server, client) {
     }, async ({ episode_id, script }) => jsonResult(await client.producePut(`/episodes/${episode_id}/rewritten-script`, { script_content: script })));
     // ---------- 提取(角色/场景/道具) ----------
     server.tool('extract_assets', '从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)。后台异步,文本步后付不欠费。' +
-        '前置:已 rewrite_script(或至少 set_script)。' + WORKFLOW_HINT, { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/extract`)));
+        '前置:已 rewrite_script(或至少 set_script)。' +
+        '★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60 秒当失败判据。' + WORKFLOW_HINT, { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/extract`)));
     // ---------- 完整工作流进度 ----------
     server.tool('get_pipeline_status', '查某一集完整工作流 10 步的进度(script_rewrite/提取/分镜/出图/出视频/合成…各步 done/ready/pending)。' +
         '照它按序推进、不跳步。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/pipeline-status`)));
@@ -184,7 +187,10 @@ export function registerProduceTools(server, client) {
         '拿到后把点数告诉用户征求同意,再用 quote_id 调 generate_storyboards。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/quote`)));
     server.tool('generate_storyboards', '确认后拆镜:后台跑(分钟级),立即返回 status:generating。用 get_storyboards 轮询。' +
         '★注意:拆镜会**替换整集所有已有分镜**(已调好/已出图的全丢、要重花钱重来)。每镜 5-7 秒是对 AI 出视频' +
-        '优化的**正常**时长,别因「一镜偏长」觉得有问题就重拆。已有分镜时后端会拦,确认重拆才带 confirm_replace=true。' + CONFIRM_HINT, {
+        '优化的**正常**时长,别因「一镜偏长」觉得有问题就重拆。已有分镜时后端会拦,确认重拆才带 confirm_replace=true。' +
+        '★典型耗时 5~10 分钟(生产实测 7~8.4 分钟;**单次 LLM 调用就可能 3~7 分钟**)。' +
+        '**60 秒、甚至 3 分钟内查不到分镜都是正常的**——用 get_run_status 判断是否还在跑。' +
+        'running:true 就继续等;重发一次等于把整集分镜重来一遍。' + CONFIRM_HINT, {
         episode_id: z.number().int().positive(),
         quote_id: z.string().describe('来自 quote_storyboards'),
         confirm_replace: z.boolean().optional().describe('本集已有分镜时必须 true 才重拆(会替换整集所有分镜,已出图白费)'),
@@ -198,9 +204,24 @@ export function registerProduceTools(server, client) {
         '★若某镜带 reopen_pair_id:该镜首尾帧同时生成时只有一侧真的有问题、另一侧是无辜陪拒,' +
         '原样传给 generate_shot_frame 的 reopen_pair_id 参数可以只重掷有问题的那一侧(省一半算力/费用,' +
         '不会拿去生成一张这次根本没打算重做的图)。没有这个字段就按 fail_reason/retryable 走常规重试。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/storyboards`)));
+    // ---------- 在途运行状态(免费):区分「还在跑」和「已经死了」----------
+    server.tool('get_run_status', '(★免费·长耗时操作后必用)查这一集当前有没有 agent 正在跑。' +
+        'rewrite_script / extract_assets / generate_storyboards 都是**分钟级**后台任务,' +
+        '它们只回一句 status:"generating",本工具是唯一能区分「还在跑」与「已经结束」的手段。\n' +
+        '★典型耗时(生产实测):改写 2~4 分钟、拆镜 5~10 分钟——**单次 LLM 调用就可能 3~7 分钟**。' +
+        '所以 60 秒内查不到结果是完全正常的,绝不是失败。\n' +
+        '用法:发起后每 30~60 秒调一次。running:true = 还在跑,继续等,**千万不要重发**' +
+        '(重发拆镜会替换整集分镜,已调好/已出图的全丢、要重花钱);' +
+        'running:false = 那次已经结束,这时才去 get_storyboards / get_script 看产物有没有落库。\n' +
+        '⚠️ 服务重启会让在途登记归零,重启期间发起的运行也会显示为无在途。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/run-status`)));
     // ---------- 分镜级 AI 操作:2 个免费质量闸 + 3 个 AI 增强(★都在出图前做)----------
-    server.tool('run_precheck', '(★推荐·免费质量闸)出图/出视频前跑生成前预检:查合规/敏感/就绪度,把会被厂商拒的镜提前揪出。免费、不扣费。' +
-        '强烈建议 generate_frames/generate_videos 前调,防白花钱被拒。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/precheck`)));
+    server.tool('run_precheck', '(★推荐·免费质量闸)出图/出视频前跑生成前预检,把会被拒的镜提前揪出。免费、不扣费。' +
+        '强烈建议 generate_frames/generate_videos 前调,防白花钱被拒。\n' +
+        '查这几类:①真人肖像/克隆音色授权 ②图像审核高危词 ③配音覆盖与大空档 ' +
+        '④**指令自相矛盾(kind=prompt-conflict)**——同一镜里互斥的要求(如宽景别却标了特写主体、' +
+        '既要站立又要坐姿),这类镜**任何正确的图都满足不了**,不改就会反复被拒并反复扣费,' +
+        '出现时应先按提示改分镜再出图,而不是重试。\n' +
+        '⚠️ 它**不**检查首帧是否处在"动作发生前"(平台暂无该契约字段),也不替代 get_health_report。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/precheck`)));
     server.tool('get_health_report', '(★推荐·免费诊断)读分镜出体检报告:时长超标/母题覆盖不足/问题镜。纯读、免费。出图前查,识别问题先改再出、别出了片才发现。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/health-report`)));
     server.tool('autofill_storyboards', '(推荐)AI 一键给全集分镜补全空缺字段,默认**只填空缺、不覆盖已有**(overwrite=true 才覆盖)。提升分镜完整性,出图前做。后台异步,文本步后付。', { episode_id: z.number().int().positive(), overwrite: z.boolean().optional().describe('true=覆盖已有字段(默认 false 只填空缺)') }, async ({ episode_id, overwrite }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/autofill`, overwrite ? { overwrite } : {})));
     server.tool('enhance_shot_prompts', '(可选增强·★非必须·有副作用)AI 批量增强全集 image_prompt。★会**改写已有 prompt**(含手调的);且**务必 generate_frames 之前**做——' +
@@ -209,10 +230,13 @@ export function registerProduceTools(server, client) {
         '★前置:该剧已设 motifs(没设=空操作);会**改结尾镜 action/描述**,务必出图前做(否则结尾镜已出图会陈旧)。后台异步,文本步后付。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/complete-motifs`)));
     // ---------- 出首帧(frames) ----------
     server.tool('quote_frames', '报价:给某一集批量出帧要多少点。返回 frames_to_generate、estimated_points、quote_id。零扣费。' +
-        'frame_type 默认 first_frame(只给缺首帧的镜出);last_frame 只给「已有首帧且缺尾帧」的镜出;both 两者都补。', {
+        'frame_type 默认 first_frame(只给缺首帧的镜出);last_frame 只给「已有首帧且缺尾帧」的镜出;both 两者都补。' +
+        '★报价按**实际会用的模型与分辨率**分档,响应带 price_breakdown(逐档张数与单价);' +
+        '打算在 generate_frames 里临时换模型,报价时就要把同一个 image_model 传进来,否则两边不是一个价。', {
         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 })));
+        image_model: z.string().optional().describe('按这个模型报价(须与随后 generate_frames 传的一致;不传=用 drama 级设定,默认香蕉2)'),
+    }, async ({ episode_id, frame_type, image_model }) => jsonResult(await client.producePost(`/episodes/${episode_id}/frames/quote`, { frame_type, image_model })));
     server.tool('generate_frames', '确认后批量出帧:后台异步。用 get_storyboards 轮询,first_frame_image/last_frame_image 逐镜填充即完成。' +
         '★图片生成较慢——每张几十秒到数分钟(尤其高清模型),整集可能十几分钟。轮询看 frame_status:' +
         '**pending=还在生成(继续耐心等,别当失败、别重复调 generate_frames,重复触发=白花钱)**、' +
@@ -221,7 +245,10 @@ export function registerProduceTools(server, client) {
         'frame_type 要与 quote_frames 用的一致(默认 first_frame)。' +
         '★这是**批量补缺帧**:只给「缺该帧」的镜出图,已有首帧的镜会跳过——这是正常设计、不是"系统拒绝重出"。' +
         '要**重出/重画某一镜已有的帧**(如换了定妆图要让新图生效),用 generate_shot_frame(单镜重生,平台带身份锚),不是这个工具、更不是自制图 upload_shot_frame。' +
-        '★尾帧能批量出:frame_type=last_frame 会给「已有首帧且缺尾帧」的镜批量补尾帧(尾帧只在想固定某镜结尾画面/大运镜时才需,常规只出首帧)。' + CONFIRM_HINT, {
+        '★尾帧能批量出:frame_type=last_frame 会给「已有首帧且缺尾帧」的镜批量补尾帧(尾帧只在想固定某镜结尾画面/大运镜时才需,常规只出首帧)。' +
+        '★响应里的 frames_planned 是**计划数,不是已成功数**——本接口在后台派发循环开跑之前就返回了。' +
+        '真实进度只看 get_storyboards 的 first_frame_image / get_jobs 的逐条生成记录;' +
+        '余额不足(402)会中止整批,此时轮询再久也不会有结果,应去查余额而不是继续等。' + CONFIRM_HINT, {
         episode_id: z.number().int().positive(),
         quote_id: z.string().describe('来自 quote_frames'),
         frame_type: FRAME_TYPE_ARG.optional().describe('默认 first_frame,须与报价时一致'),
@@ -231,10 +258,12 @@ export function registerProduceTools(server, client) {
     }, async ({ episode_id, quote_id, frame_type, image_model }) => jsonResult(await client.producePost(`/episodes/${episode_id}/frames/generate`, { quote_id, frame_type, image_model })));
     // ---------- 单镜出帧/重生(改某一镜的画面走这里,别去外部平台出图再传回来) ----------
     server.tool('quote_shot_frame', '报价:重画/补出**某一镜的某一帧**要多少点(一帧=一张图)。返回 estimated_points、quote_id。零扣费。' +
-        '客户说「第 N 镜画错了/要改」时用它,而不是拿别的图像平台出图再 upload_shot_frame。', {
+        '客户说「第 N 镜画错了/要改」时用它,而不是拿别的图像平台出图再 upload_shot_frame。' +
+        '★响应带 billing_kind/unit_points(实际计费档与单价);要在 generate_shot_frame 里换模型,报价时传同一个 image_model。', {
         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 })));
+        image_model: z.string().optional().describe('按这个模型报价(须与随后 generate_shot_frame 传的一致;不传=用 drama 级设定,默认香蕉2)'),
+    }, async ({ storyboard_id, frame_type, image_model }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/frame/quote`, { frame_type, image_model })));
     server.tool('generate_shot_frame', '确认后给**某一镜**出帧或重生该帧(异步)。这是修某一镜画面的正路:平台会带上该镜的角色身份锚、' +
         '场景/道具参考图、画风锚与帧审计,重生出的图与全片一致;用外部工具出图再上传会绕开这整条链路,人物/服装/画风必漂。' +
         '重生会覆盖该帧现有图(含此前上传的),并把本镜视频标为待重生。尾帧需本镜首帧已就绪(否则先用 first_frame 或 both)。' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "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",