@starreel/mcp 0.1.61 → 0.1.63

package/SKILL.md

@@ -72,6 +72,7 @@ announces a condensed version as MCP `instructions` at connect time.
 | A finished **shot list** (per-shot seconds / shot size / camera move) | `get_storyboard_table_spec` (the contract: shot-size / camera-move vocabulary, body layout, text-card syntax, a prompt for the external AI) → `check_storyboard_table` (same parser as the import; clear `errors`, read every `warning` — a missing duration, an unrecognised shot size or an empty body all get imported as-is) → `import_storyboard_table` (defaults to `auto_complete`: one background batch fills the professional fields and expands every shot's platform-built base description into full image / video prompts — metered text, tell the customer first; `auto_complete: false` imports only) → `get_autofill_status` until `done` → `review_storyboards` | `rewrite_script` + `generate_storyboards` — strips every production parameter (measured: 8 shots / 36 s became 20 shots / 109 s); importing without the check; reviewing before the completion batch finishes (the token expires when shots change) |
 | **Structured data** — their own tool / spreadsheet export, or an external AI producing JSON (cast + scenes + shots in one go) | `get_bulk_import_spec` (contract + template + worked example + enums, same source as the validator) → `check_bulk_import` (same zod schema; unresolved character / scene references, dead shots and stage directions inside dialogue are surfaced) → `bulk_import_storyboards` (`mode: "replace"` only with the customer's explicit OK; defaults to `auto_complete`: professional fields for every shot, full image / video prompts only for shots that had no `image_prompt` — prompts you supply yourself are kept verbatim — metered text, tell the customer first) → `get_autofill_status` until `done` → `review_storyboards` | converting the JSON to text for `import_storyboard_table`; hand-building shots with `update_shot`; reviewing before the completion batch finishes |
 | Their own portraits / scene / prop / shot images | `upload_image` · `set_character_portrait` · `upload_scene_image` · `upload_prop_sheet` · `upload_shot_frame` | rendering a "fix" elsewhere and uploading it — use `generate_shot_frame` |
+| Their own **footage** for a shot (screen recording, product b-roll, an existing clip) | `upload_shot_footage` → that shot is no longer AI-generated (frames/video skipped, final cut uses the clip as-is, duration written back from the clip); `clear_shot_footage` to revert | pasting an externally AI-generated clip to "fix" a shot — it carries none of this film's identity / style anchors; use `regenerate_shot_video` instead |
 | A scene plate that came out wrong (backdrop, era, light, layout) | `get_scene_prompt` → `update_scene` (`image_prompt`) → `regenerate_scene_image`; already-rendered shot frames still anchor on the old plate, so regenerate those shots too | re-running `generate_scene_images` (it only fills scenes that have **no** plate — it will not touch this one) |
 | A voice sample / a required voice | `clone_voice` → `speak_with_voice` → `set_character_voice` / `assign_voices` | cloning without the rights-holder's consent |
 | A song + lyrics | `create_drama` (`project_type: "mv"`) → `set_mv_lyrics` → `generate_mv_story` → `generate_mv_script` | `rewrite_script` (blocked for MV) |
@@ -612,9 +613,17 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   decide transitions and assemble the cut on your own side. Use this instead of
   `compose_episode` when you want to judge each seam yourself; use
   `compose_episode` when you want the platform's finishing pipeline (pre-flight
-  checks, A/V duration parity, loudness mastering). Three facts that will bite you:
-  `audio_contract.mode="tts"` means the raw clips have **no voice** (dialogue ships
-  separately — skip it and the episode is silent); every shot must be cut to
+  checks, A/V duration parity, loudness mastering). Call
+  `get_capabilities_guide(section="local_postproduction")` for the full stage-by-stage
+  walkthrough. Three facts that will bite you: **where the voice lives is per-shot —
+  read `shots[].voice_track.location`, never the episode-level
+  `audio_contract.mode`** (that field is a declaration; fully-offscreen narration
+  shots get their voice mixed into the raw clip on our side, so even a `mode="tts"`
+  episode contains shots whose voice is already baked in — re-laying it says the line
+  twice, skipping it loses it, and `location="missing"` means we know the voice is
+  gone and you should regenerate that shot rather than paper over it). Check per line
+  with `shots[].spoken_lines[]`: subtitles are per-line but audio is per-shot, so
+  **having subtitles never means having sound**; every shot must be cut to
   `trim_head_ms`/`duration_ms` or you splice in frames the platform already QC'd out;
   and all subtitle/dialogue/SFX offsets are relative to **each shot's own trimmed
   start**, not to the final timeline — add whatever overlapping transitions you like

package/dist/client.js

@@ -18,7 +18,7 @@ import { assertSafeLocalMediaPath } from './path-guard.js'; // v0.1.37 — P0③
 const MIME_BY_EXT = {
     '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.webp': 'image/webp',
     '.gif': 'image/gif', '.bmp': 'image/bmp',
-    '.mp4': 'video/mp4', '.mov': 'video/quicktime',
+    '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm', '.m4v': 'video/x-m4v',
     '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.m4a': 'audio/mp4', '.aac': 'audio/aac',
     '.ogg': 'audio/ogg', '.flac': 'audio/flac',
 };
@@ -157,7 +157,7 @@ export class StarReelClient {
     }
     /**
      * 本地文件 → 我方 COS:presign(门面 /upload-url)→ 直传字节到预签名 URL → 返回 public_url。
-     * 字节不经我们的业务服务器,只走 COS。kind: image(默认)/video/audio。
+     * 字节不经我们的业务服务器,只走 COS。kind: image(默认)/video(参考视频)/audio/footage(实拍素材整段视频,额度更大)。
      */
     async uploadLocalFile(filePath, kind = 'image') {
         // v0.1.37 — P0③:媒体扩展名白名单 + 隐藏/系统目录拒绝(realpath 后判,防符号链接绕过)。

package/dist/path-guard.js

@@ -15,6 +15,8 @@ import { sep } from 'node:path';
 export const MEDIA_EXT_BY_KIND = {
     image: new Set(['.jpg', '.jpeg', '.png', '.webp', '.gif']),
     video: new Set(['.mp4', '.mov', '.webm', '.m4v']),
+    // 0.1.63 实拍素材镜（整段视频当某镜的成片）：格式同 video，额度更大（后端 presign kind=footage）
+    footage: new Set(['.mp4', '.mov', '.webm', '.m4v']),
     audio: new Set(['.mp3', '.wav', '.m4a', '.aac', '.flac', '.ogg']),
 };
 const SYSTEM_PREFIXES = ['/etc/', '/private/etc/', '/proc/', '/sys/'];
@@ -22,7 +24,7 @@ const SYSTEM_PREFIXES = ['/etc/', '/private/etc/', '/proc/', '/sys/'];
 export function assertSafeLocalMediaPath(filePath, kind, resolve = realpathSync) {
     const ext = (filePath.match(/\.[a-z0-9]+$/i)?.[0] || '').toLowerCase();
     if (!MEDIA_EXT_BY_KIND[kind].has(ext)) {
-        throw new Error(`file_path 只接受${kind === 'image' ? '图片' : kind === 'video' ? '视频' : '音频'}媒体文件`
+        throw new Error(`file_path 只接受${kind === 'image' ? '图片' : (kind === 'video' || kind === 'footage') ? '视频' : '音频'}媒体文件`
             + `(${[...MEDIA_EXT_BY_KIND[kind]].join('/')});收到 "${ext || '无扩展名'}"。`
             + '不要用本工具上传配置/密钥/文档类文件。');
     }

package/dist/tools/guide-data.js

@@ -81,9 +81,10 @@ export const ENTRY_POINTS = [
             'upload_scene_image',
             'upload_prop_sheet',
             'upload_shot_frame(只用于客户自有真实素材)',
+            'upload_shot_footage(客户自有整段视频当某镜成片:录屏/产品实拍/已有片段;登记后该镜不再 AI 出图出视频,终拼原样用,时长按素材回写;清除用 clear_shot_footage)',
         ],
         avoid: '要「改某一镜画面」走 `generate_shot_frame`(平台自动带该镜身份锚·场景道具参考·画风锚);别在外部工具画好再 `upload_shot_frame`——外部图没有任何锚,人物/服装/画风必漂。',
-        flow: 'upload_image · set_character_portrait · upload_scene_image · upload_prop_sheet · upload_shot_frame(仅客户自有素材;要改画面走 generate_shot_frame)',
+        flow: 'upload_image · set_character_portrait · upload_scene_image · upload_prop_sheet · upload_shot_frame(仅客户自有素材;要改画面走 generate_shot_frame) · upload_shot_footage(整段实拍/录屏当某镜成片)',
     },
     {
         customer_has: '自己的声音样本 / 指定音色',
@@ -141,7 +142,9 @@ export const ENTRY_POINTS = [
     {
         customer_has: '想自己剪:要逐镜素材包(裸片 / 对白轨 / 音效 / 配乐 / 字幕)',
         use: ['export_handoff_pack', 'get_handoff_toolchain', 'save_handoff_toolchain'],
-        note: '与 `compose_episode` 二选一。audio_contract.mode=tts 时裸片没有人声,对白轨单独发——漏掉整集是哑的。',
+        note: '与 `compose_episode` 二选一。★人声在哪要**逐镜**看 voice_track.location——整集的 audio_contract.mode 只是声明,' +
+            '不是逐镜真值(全画外旁白镜的旁白是平台在完成侧混进裸片的);逐句核对看 spoken_lines,有字幕不等于有声音。' +
+            '完整流程见 local_postproduction 段。',
     },
     {
         customer_has: '多语言发行',
@@ -202,7 +205,7 @@ export const PIPELINE = [
     },
     {
         step: '8 出视频',
-        tools: ['quote_videos', 'generate_videos', 'get_scene_group_plan', 'generate_scene_groups', 'quote_regenerate_shot_video', 'regenerate_shot_video', 'quote_edit_video_shot', 'edit_video_shot', 'get_edit_capabilities'],
+        tools: ['quote_videos', 'generate_videos', 'get_scene_group_plan', 'generate_scene_groups', 'quote_regenerate_shot_video', 'regenerate_shot_video', 'quote_edit_video_shot', 'edit_video_shot', 'upload_shot_footage(实拍素材镜:客户录屏/产品实拍直接当该镜视频,不出视频不扣费)', 'get_edit_capabilities'],
         billing: '报价确认后扣点',
         note: 'video_engine 必须在出视频前定(seedance-2.5 默认 / hailuo-3 降本 / wan3.0 风格化·绝不用于写实真人);切换不回溯已生成镜头。',
     },
@@ -277,6 +280,77 @@ export const COMMON_REQUESTS = [
     { customer_says: '我想自己剪', do: '`export_handoff_pack` + `get_handoff_toolchain`,不走 `compose_episode`。' },
     { customer_says: '要配音 / 不要视频原声', do: '`update_project_settings` use_clip_audio=false → `assign_voices` → `generate_tts` → `compose_episode`。' },
 ];
+/**
+ * v0.9.1371 — 本地后期引导:客户把镜头下载到**自己电脑**上剪。
+ * 与 `compose_episode` 二选一——那条是「平台替你拼、带平台级质量闸」,这条是「素材给你、你自己拼」。
+ * 不单开一个 guide 工具:入口越多,agent 越要先猜「该调哪个」。
+ */
+export const LOCAL_POSTPRODUCTION = {
+    when: '客户要把镜头下载到自己电脑上剪、配乐、烧字幕、优化转场、做字卡、补旁白时走这条;' +
+        '想让平台代拼并要平台级质量闸(终拼预检 / 音画等长 / 响度母带)用 `compose_episode`。两条二选一。',
+    where_it_runs: '★脚本与 ffmpeg 全部跑在**客户自己的机器**上,平台只发素材 URL 与工具链源码。' +
+        'manifest 里是远程 URL,不是服务器上的本地路径;`save_handoff_toolchain` 的 dir 也是客户机器上的绝对路径。' +
+        '别把服务器路径当成客户电脑上的路径,也别替客户声称"已经在本地跑完了"——真正执行的是客户那侧。',
+    tools: ['export_handoff_pack', 'save_handoff_toolchain', 'get_handoff_toolchain'],
+    stages: [
+        {
+            stage: '1 对需求',
+            do: '先问清:哪一集、目标时长、客户有没有自带配乐、字幕样式与排版要求。' +
+                '画幅、字幕样式这些项目里已经定过的,用 `get_drama` 读出来直接沿用——客户上一版确认过的偏好别每版重问。',
+        },
+        {
+            stage: '2 查环境',
+            do: '确认客户机器上有 ffmpeg(烧字幕要带 libass)、ffprobe、jq、python3,以及够放整集素材的磁盘。',
+            gotcha: '缺 libass 时字幕会**静默不烧**——成片看着正常,只是没有字幕。先查再跑,别等出片才发现。',
+        },
+        {
+            stage: '3 取包',
+            do: '`export_handoff_pack` 拿 manifest → `save_handoff_toolchain` 把三个脚本落到客户目录 → 跑 fetch_pack.py 下载素材并把内联字幕落成 SRT。',
+            gotcha: '素材 URL 到 expires_at 就失效;过期重新调 `export_handoff_pack`,别拿旧 manifest 硬跑。',
+        },
+        {
+            stage: '4 核声音',
+            do: '★动剪辑前先核对声音。**逐镜**读 voice_track.location 决定这镜该不该铺对白轨、能不能叠;' +
+                '**逐行**读 spoken_lines 逐句核对。location=unknown 的镜必须实际试听裸片。',
+            gotcha: '**有字幕不等于有声音**:字幕是逐句的、音频是逐镜的,粒度本来就对不上,' +
+                '别按「这镜有字幕」推定每句都有人念。voice_status=caption_no_voice 的行是字卡,本来就没有配音,不是缺失。',
+        },
+        {
+            stage: '5 判接缝',
+            do: '逐个接缝看前后画面,结合动作、景别、视线与声音选切点。scene_boundary="start" 是换场(适合给转场),' +
+                '"continue" 是同场景(平台默认硬切)。',
+            gotcha: '同场景逐镜叠化是"幻灯片拼凑感"的主因;缺失的交接动作**拉长叠化也补不出来**,该重生成就重生成。',
+        },
+        {
+            stage: '6 装配',
+            do: '先做代表性样段(字卡、混音各挑一两处)给客户看,再整集出片:compile_timeline.py 展开时间轴 → assemble.sh 装配。',
+            gotcha: '裁剪与重叠转场都会移动入点——字幕/对白/音效的绝对时间一律交给 compile_timeline.py 算,**别手算累加**。' +
+                '只改声音时保留视频码流(-c:v copy),别整片重编码。',
+        },
+        {
+            stage: '7 验收',
+            do: '看**真实成片**:画面、字幕位置、旁白完整性、每个接缝、峰值与音画同步。交付可播放文件 + 版本 + 检查结果。',
+            gotcha: '没做的试听或视觉检查要**明说没做**,不许默认通过。',
+        },
+    ],
+    voice_rules: [
+        'location=separate_file:对白在 dialogue_audio,必须自己铺轨,不铺这镜就没台词。',
+        'location=baked_in_clip:人声已在裸片音轨里,**再叠一遍是同一句说两遍**(全画外旁白镜最常见)。',
+        'location=missing:平台侧确认缺失。正解是回平台 `regenerate_shot_video` 重生成,或 `generate_tts` 补这句,' +
+            '音色复用已授权的克隆音(`list_voices` / `set_character_voice`),别在本地硬凑,也别拿转场掩盖。',
+        '人声与配乐分开控制:客户说"这句小一点"是调那句的对白轨增益,不是压整条 BGM;' +
+            '整体响度达标**不代表**每句都听得清。',
+        'clip.probed_has_audio_stream=false 表示平台实测这条裸片连音轨流都没有;反过来不成立——' +
+            '有音轨不代表有人声,全旁白镜的环境音本来就是要求厂商出的。',
+    ],
+    not_verified_until: [
+        '「素材下载完成」不是验收。',
+        '「脚本退出码 0 / 执行成功」不是验收——ffmpeg 跑完不等于成片对。',
+        '「自动转写通过」不等于试听过,别拿它冒充人工听过。',
+        '只有看过真实成片(画面 / 字幕位置 / 旁白完整 / 接缝 / 音画同步)才算验收完成;' +
+            '平台侧成片用 `get_final_cut` 取。',
+    ],
+};
 export const HOW_TO_READ = '先按 entry_points 判客户手上的材料该走哪条通道(这是最常被跳过的一步),再按 pipeline 顺序推进、每道 review_gates 必过;' +
     '收费步按 billing.quote_flow 报价确认;遇到质量投诉按 qa_tools 的 symptom 选检测工具先定病因。';
 export function buildGuide() {
@@ -290,9 +364,10 @@ export function buildGuide() {
         optional_boosts: OPTIONAL_BOOSTS,
         billing: BILLING,
         common_requests: COMMON_REQUESTS,
+        local_postproduction: LOCAL_POSTPRODUCTION,
     };
 }
-export const GUIDE_SECTIONS = ['entry_points', 'pipeline', 'review_gates', 'qa_tools', 'optional_boosts', 'billing', 'common_requests'];
+export const GUIDE_SECTIONS = ['entry_points', 'pipeline', 'review_gates', 'qa_tools', 'optional_boosts', 'billing', 'common_requests', 'local_postproduction'];
 const head = (s) => /^[a-z][a-z0-9_]*/.exec(s.trim())?.[0] ?? null;
 const inProse = (s) => [...(s ?? '').matchAll(/`([a-z][a-z0-9_]*)`/g)].map((m) => m[1]);
 /** 引导里引用到的全部工具名(去重)——哨兵测试用:每一个都必须真的注册了。 */
@@ -326,6 +401,15 @@ export function referencedTools() {
     BILLING.tools.forEach(add);
     for (const c of COMMON_REQUESTS)
         inProse(c.do).forEach(add);
+    // v0.9.1371 — 本地后期段同样纳入哨兵:漏了这几行,这段引导就能悄悄指向不存在的工具。
+    LOCAL_POSTPRODUCTION.tools.forEach(add);
+    [LOCAL_POSTPRODUCTION.when, LOCAL_POSTPRODUCTION.where_it_runs].forEach((s) => inProse(s).forEach(add));
+    for (const s of LOCAL_POSTPRODUCTION.stages) {
+        inProse(s.do).forEach(add);
+        inProse(s.gotcha).forEach(add);
+    }
+    for (const r of [...LOCAL_POSTPRODUCTION.voice_rules, ...LOCAL_POSTPRODUCTION.not_verified_until])
+        inProse(r).forEach(add);
     return [...out].sort();
 }
 /**

package/dist/tools/guide.js

@@ -10,7 +10,9 @@ export function registerGuideTools(server) {
         'entry_points(客户手上是小说/成熟剧本/想去外部 AI 改写/成品分镜表/自有素材/声音样本/歌曲/产品/已有成片要改/想自己剪/多语言 → 各走哪些工具、别走哪条路)、' +
         'pipeline(10 步产线每步的工具、免费还是收费、哪道审查闸)、review_gates(三道免费硬闸规则)、' +
         'qa_tools(按客户描述的症状选检测工具与修法)、optional_boosts(可选增强及何时做)、billing(报价确认与免费族)、' +
-        'common_requests(客户常见原话 → 该做什么)。传 section 只取一段。' +
+        'common_requests(客户常见原话 → 该做什么)、' +
+        'local_postproduction(★客户要把镜头下载到**自己电脑**上剪 / 配乐 / 烧字幕 / 优化转场 / 补旁白时的完整流程:' +
+        '阶段顺序、执行位置、逐镜逐句怎么核对声音、什么才算验收完成)。传 section 只取一段。' +
         '★工具描述回答"这个工具做什么",本工具回答"什么情况下该用哪个"——客户交来的是成品分镜表却被 set_script→rewrite_script 改写成散文,就是没先看这张表。', {
         section: z.enum(GUIDE_SECTIONS).optional().describe('只取某一段;不传返回全部'),
     }, async ({ section }) => {

package/dist/tools/produce.js

@@ -239,7 +239,7 @@ export function registerProduceTools(server, client) {
         ethnicity_note: z.string().optional().describe("ethnicity='custom' 时的自由文本(如 北欧/波斯);其余取值忽略"),
         project_type: z.enum(['drama', 'ad', 'mv', 'brand_film']).optional()
             .describe('项目类型(默认 drama)。ad=广告(改写走 ad_script_rewriter);mv=音乐(走歌词→故事→剧本子流程);brand_film=品牌微电影(默认16:9)'),
-        rewrite_mode: z.enum(['standard', 'director']).optional().describe('AI改写深度:standard 或 director(导演级)'),
+        rewrite_mode: z.enum(['standard', 'director']).optional().describe('AI改写深度(★默认 director):director=只做格式规范化与最小可拍性修正,不擅自补台词补动机;standard=按商业短剧剧作律优化,会主动加戏'),
         rewrite_pipeline: z.enum(['auto', 'two_pass', 'single_forced']).optional().describe('改写流水线:auto(默认,按原稿形态智能路由——剧本形态走两步保真,小说/大纲走创作改写)/two_pass(强制两步保真,客户自带成熟剧本必选)/single_forced(强制单步创作)'),
         fidelity_enforce: z.number().int().min(0).max(1).optional().describe('1=改写保真硬闸:丢台词/丢人物/丢动作节拍直接拒收重做(客户要求逐句保留时开)'),
         director_style: z.string().optional().describe('导演风格包 key'),
@@ -609,7 +609,7 @@ export function registerProduceTools(server, client) {
         director_style: z.string().optional(),
         theme_statement: z.string().optional().describe('一句话主题'),
         subtitle_preset: z.string().optional(),
-        scene_group_mode: z.boolean().optional().describe('长镜模式(连续动作/电影级长镜)'),
+        scene_group_mode: z.boolean().optional().describe('长镜模式(连续动作/电影级长镜·★所有类型建剧默认开):false=改回逐镜独立生成再拼接'),
         // 广告专属
         cta_text: z.string().optional(),
         target_duration_s: z.number().optional(),
@@ -687,6 +687,18 @@ export function registerProduceTools(server, client) {
         const image_url = await client.uploadLocalFile(file_path, 'image');
         return jsonResult(await client.producePost(`/storyboards/${storyboard_id}/frame`, { image_url, frame_type: frame_type ?? 'first_frame' }));
     });
+    server.tool('upload_shot_footage', '用**客户自有的整段视频**（录屏 / 产品实拍 / 第三方成片）直接当某镜的视频——实拍素材镜。' +
+        '登记后该镜不再 AI 出图/出视频（generate_videos 会跳过它,单镜重生会被拒),终拼原样使用,镜头时长按素材真实长度回写,' +
+        '首/尾帧从素材抽帧供帧链与预览用。免费。适用:宣传片里的到账界面录屏、后台大屏实录、产品实拍、客户已有的成片片段。' +
+        '⚠️ 别用它把外部 AI 生成的视频贴进来"改画面"——那不带本片身份锚/画风锚,人物·画风必漂;要改画面走 regenerate_shot_video。' +
+        '要换回 AI 生成请先 clear_shot_footage。', {
+        storyboard_id: z.number().int().positive(),
+        file_path: z.string().describe('本地视频路径(mp4/mov/webm/m4v,≤300MB)'),
+    }, async ({ storyboard_id, file_path }) => {
+        const video_url = await client.uploadLocalFile(file_path, 'footage');
+        return jsonResult(await client.producePost(`/storyboards/${storyboard_id}/footage`, { video_url }));
+    });
+    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', '用客户自有图片作为某场景的参考图。自动上传+登记。免费。', { scene_id: z.number().int().positive(), file_path: z.string().describe('本地场景图路径') }, async ({ scene_id, file_path }) => {
         const image_url = await client.uploadLocalFile(file_path, 'image');
         return jsonResult(await client.producePost(`/scenes/${scene_id}/image`, { image_url }));
@@ -1029,8 +1041,14 @@ export function registerProduceTools(server, client) {
         '写一份 plan.json;④ 用 get_handoff_toolchain 拿到 compile_timeline.py 展开时间轴、' +
         'assemble.sh 装配出成片。工具链已经把「加了重叠转场之后字幕/对白/音效怎么跟着位移」算好了。\n' +
         '\n【三个不看就会翻车的事实】\n' +
-        '① audio_contract.mode="tts" 时**裸片里没有人声**,对白在 dialogue_audio 里;不铺就是整集没台词。' +
-        'mode="clip" 时人声已烤在裸片音轨里,反过来**不要**再叠。\n' +
+        '① **人声在哪要逐镜读 `shots[].voice_track.location`,不能读整集的 audio_contract.mode**——' +
+        '后者是整剧级声明,而全画外旁白镜的旁白是平台在完成侧混进裸片的,同一集里逐镜可以不同。' +
+        '四种取值各有各的处置:`separate_file`=对白在 dialogue_audio,不铺这镜就没台词;' +
+        '`baked_in_clip`=已在裸片音轨里,再叠一遍会双声;' +
+        '`missing`=**平台侧确认缺失**(旁白补偿失败),字幕还在但声音哪都没有——回平台重生成该镜,' +
+        '拉长转场掩盖不了;`unknown`=有台词却查不到来源,**必须试听裸片**再决定。' +
+        '★有字幕从来不等于有声音:字幕是逐句的,音频是逐镜的。`conflicts_with_contract=true` 的镜' +
+        '以实测为准,notes 里已按镜号点名。\n' +
         '② 每镜必须按 trim_head_ms / duration_ms 裁剪再用;直接拼整条裸片会把平台已经 QC 掉的' +
         '首尾形变帧一起拼进去。\n' +
         '③ 字幕 cue、dialogue_audio.offset_ms、sfx[].offset_ms 的基准都是「该镜 trim 之后的第 0 毫秒」,' +
@@ -1042,6 +1060,15 @@ export function registerProduceTools(server, client) {
             assembly_guide: {
                 step_1_download: '按 shots[].clip.url / dialogue_audio.url / sfx[].url / bgm[].url 下载素材。' +
                     'URL 到 expires_at 失效,过期重新调本工具。',
+                step_1b_verify_voice: '★下载完先核对声音,再动剪辑。**逐镜**读 voice_track.location 决定这镜的人声该不该铺、' +
+                    '能不能叠;location="unknown" 的镜**必须实际试听裸片**,不能凭字幕存在推定有声音;' +
+                    'location="missing" 的镜先回平台重生成,别开始剪。' +
+                    'clip.probed_has_audio_stream=false 表示平台实测这条裸片连音轨流都没有——' +
+                    '注意反过来不成立:有音轨不代表有人声,全旁白镜的环境音本来就是要求厂商出的。\n' +
+                    '★再**逐行**读 shots[].spoken_lines[]:字幕是逐句的、音频是逐镜的,' +
+                    '「这镜有字幕」推不出「每句都有声音」。每行带 speaker / text / voice_status,' +
+                    '把它当逐句核对清单用。voice_status="caption_no_voice" 的行是字卡文本,' +
+                    '**本来就没有配音**(平台侧也是当独立字幕呈现的)——不是缺失,别去补一段不该存在的配音。',
                 step_2_decide_transitions: '自己分析画面决定每个接缝的转场。scene_boundary="start" 是换场(适合给转场),' +
                     '"continue" 是同场景(平台默认硬切——同场景逐镜叠化是"幻灯片拼凑感"的主因)。' +
                     'transition_hint 是平台建议,你可以覆盖。',
@@ -1054,6 +1081,11 @@ export function registerProduceTools(server, client) {
                     '  python3 compile_timeline.py ./pack --transitions plan.json\n' +
                     '  ./assemble.sh ./pack out.mp4 plan.json',
                 gotchas: [
+                    'voice_track.location="baked_in_clip" 的镜**不要**再铺 dialogue_audio,那一镜的人声已经在裸片音轨里,' +
+                        '叠上去是同一句话说两遍(全画外旁白镜最常见)。',
+                    'subtitle.cues 的文本已剥掉说话人前缀与画外标记(与平台烧字幕同一条清洗),直接烧即可,' +
+                        '别再自己解析「名:」——但 cues 的**切分**是按语音停顿来的,与 spoken_lines 的行不是一一对应,' +
+                        '逐句核对声音请用 spoken_lines,不要按 cue 条数推定句数。',
                     'clip.duration_source="authored" 的镜是 probe 失败退回声明时长的,请自行 ffprobe 校正,否则拼接有累积误差。',
                     'render_target.color_lut 非 null 时,裸片是**未调色**的:必须施加随包的 haldclut 查找表,' +
                         '否则你的成片与平台成片有色差。fetch_pack.py 会下载它、assemble.sh 会自动施加。',

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.61",
-    "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.61 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.63",
+    "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.63 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -3358,7 +3358,7 @@
       "get": {
         "operationId": "export_handoff_pack",
         "summary": "导出本集「素材交接包」清单:逐镜裸片 + 对白音轨 + 音效 + 配乐 + 字幕的可下载 URL,交给你在**自己那边**完成转场决策、拼接、混音、烧字幕——平台不参与终拼",
-        "description": "导出本集「素材交接包」清单:逐镜裸片 + 对白音轨 + 音效 + 配乐 + 字幕的可下载 URL,交给你在**自己那边**完成转场决策、拼接、混音、烧字幕——平台不参与终拼。免费,零扣费。\n\n【推荐流程】① 调本工具拿 manifest;② 按 clips[].url 把裸片下载到本地;③ 你自己看片判断每个接缝该用什么转场(manifest 给了 scene_boundary 场景边界作判据),写一份 plan.json;④ 用 get_handoff_toolchain 拿到 compile_timeline.py 展开时间轴、assemble.sh 装配出成片。工具链已经把「加了重叠转场之后字幕/对白/音效怎么跟着位移」算好了。\n\n【三个不看就会翻车的事实】\n① audio_contract.mode=\"tts\" 时**裸片里没有人声**,对白在 dialogue_audio 里;不铺就是整集没台词。mode=\"clip\" 时人声已烤在裸片音轨里,反过来**不要**再叠。\n② 每镜必须按 trim_head_ms / duration_ms 裁剪再用;直接拼整条裸片会把平台已经 QC 掉的首尾形变帧一起拼进去。\n③ 字幕 cue、dialogue_audio.offset_ms、sfx[].offset_ms 的基准都是「该镜 trim 之后的第 0 毫秒」,不是成片绝对时间。你加多少重叠转场都不用改它们——交给 compile_timeline.py 展开,别手算累加。\n\n想让平台代拼、要平台级质量闸(终拼预检/音画等长/响度母带),改用 compose_episode。",
+        "description": "导出本集「素材交接包」清单:逐镜裸片 + 对白音轨 + 音效 + 配乐 + 字幕的可下载 URL,交给你在**自己那边**完成转场决策、拼接、混音、烧字幕——平台不参与终拼。免费,零扣费。\n\n【推荐流程】① 调本工具拿 manifest;② 按 clips[].url 把裸片下载到本地;③ 你自己看片判断每个接缝该用什么转场(manifest 给了 scene_boundary 场景边界作判据),写一份 plan.json;④ 用 get_handoff_toolchain 拿到 compile_timeline.py 展开时间轴、assemble.sh 装配出成片。工具链已经把「加了重叠转场之后字幕/对白/音效怎么跟着位移」算好了。\n\n【三个不看就会翻车的事实】\n① **人声在哪要逐镜读 `shots[].voice_track.location`,不能读整集的 audio_contract.mode**——后者是整剧级声明,而全画外旁白镜的旁白是平台在完成侧混进裸片的,同一集里逐镜可以不同。四种取值各有各的处置:`separate_file`=对白在 dialogue_audio,不铺这镜就没台词;`baked_in_clip`=已在裸片音轨里,再叠一遍会双声;`missing`=**平台侧确认缺失**(旁白补偿失败),字幕还在但声音哪都没有——回平台重生成该镜,拉长转场掩盖不了;`unknown`=有台词却查不到来源,**必须试听裸片**再决定。★有字幕从来不等于有声音:字幕是逐句的,音频是逐镜的。`conflicts_with_contract=true` 的镜以实测为准,notes 里已按镜号点名。\n② 每镜必须按 trim_head_ms / duration_ms 裁剪再用;直接拼整条裸片会把平台已经 QC 掉的首尾形变帧一起拼进去。\n③ 字幕 cue、dialogue_audio.offset_ms、sfx[].offset_ms 的基准都是「该镜 trim 之后的第 0 毫秒」,不是成片绝对时间。你加多少重叠转场都不用改它们——交给 compile_timeline.py 展开,别手算累加。\n\n想让平台代拼、要平台级质量闸(终拼预检/音画等长/响度母带),改用 compose_episode。",
         "tags": [
           "episodes"
         ],
@@ -6612,6 +6612,53 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/footage": {
+      "delete": {
+        "operationId": "clear_shot_footage",
+        "summary": "清除某镜的实拍素材(video_url 置空、来源标记清掉),让这一镜恢复可 AI 生成视频",
+        "description": "清除某镜的实拍素材(video_url 置空、来源标记清掉),让这一镜恢复可 AI 生成视频。免费。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_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"
+          }
+        }
+      }
+    },
     "/storyboards/{storyboard_id}/frame/generate": {
       "post": {
         "operationId": "generate_shot_frame",
@@ -7536,6 +7583,10 @@
       "tool": "upload_shot_frame",
       "reason": "unmappable: local file upload flow"
     },
+    {
+      "tool": "upload_shot_footage",
+      "reason": "unmappable: local file upload flow"
+    },
     {
       "tool": "upload_scene_image",
       "reason": "unmappable: local file upload flow"

package/package.json

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