@starreel/mcp 0.1.66 → 0.1.67

package/SKILL.md

@@ -624,6 +624,37 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   shots in one call)
 - **Identity & consistency**: `generate_character_portraits`, `upload_image`,
   `set_character_portrait`, `generate_character_sheet`, `extract_visual_lock`
+- **Wardrobe**: `list/create/get/update/delete_wardrobe`,
+  `regenerate_wardrobe_image`, and the two-step timeline
+  `build_wardrobe_timeline` (LLM, **billed** — computes per-shot change
+  suggestions, changes nothing) → walk the diff past the user → `apply_wardrobe_timeline`
+  (or `apply_wardrobe_appearances` when several characters share a frame).
+  **What an outfit actually is here is a structured binding**
+  (`active_wardrobe_id` / `appearances[].wardrobeAssetId`), not prose in the
+  shot description — editing the text via `update_shot` and leaving the binding
+  alone leaves the character in the old outfit.
+- **Continuity ledger**: `get_world_state` (which props / garments / injuries
+  are tracked, and where two shots disagree), `rebuild_world_state` (LLM,
+  **billed** — rerun it when `stale=true`), `add/delete_world_state_event`
+  (explain away a conflict the AI mis-read instead of editing shots),
+  `link_world_state_scene_variant`, `derive_pose_chain` (LLM, **billed** — fills
+  only the shots whose poses are blank, so cuts connect).
+- **Era contract**: `set_era_contract` / `get_era_contract` — see the project
+  settings tier above. Non-contemporary projects must set this before frames.
+- **Lengthen a finished cut**: `quote_extend_final` (free, quote first) →
+  `extend_final` (**billed** per round) → `get_extend_final` → `apply_extend_final`.
+  The extension is *not* the episode cut until you apply it, and applying
+  **replaces** the current cut. A 403 means the drama's video engine isn't
+  eligible — don't retry.
+- **Recover an older asset**: `get_asset_recovery` lists cuts and candidate
+  frames that were superseded. Reach for it when the user says "the previous
+  version was better". Apply them **one at a time, only after the user confirms
+  each**: `apply_recovered_final`, or `apply_recovered_candidate` (which
+  requires an explicit `target_storyboard_id` — the platform will not guess
+  which shot a recovered frame belongs to). `rollback_asset_recovery` undoes one.
+- **Marketing export**: `export_sheet_compare` / `get_sheet_compare` — the
+  character-sheet-vs-frame comparison sheet. **Off by default per drama**; a 403
+  or `enabled: false` means the user has to switch it on in the drama settings.
 - **Shots → video**: `quote/generate_storyboards`, `get_storyboards`,
   `quote/generate_frames`, `chain_frames`, `quote/generate_videos`
 - **Audio**: `generate_tts` (required before final cut), `clone_voice`,

package/dist/tools/produce.js

@@ -629,6 +629,154 @@ export function registerProduceTools(server, client) {
     server.tool('get_final_cut', '查某一集成片状态与下载链接。status=completed 时返回 download_url(我方 COS 直链,可直接下载)。免费。' +
         '★bgm_stale=true 表示配乐在成片之后生成/改动、尚未进成片:重新 compose_episode(免费)即可,别用 re-render。', { 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('get_asset_recovery', '列本集可恢复的**历史产物**(免费·只读):以前生成过、后来被覆盖掉的成片与候选帧。'
+        + '\n用途:客户说「上一版那个好」「前天那张图比现在这张好」时,从这里找回来。'
+        + '\n★这一步只看不改。把候选逐条讲给客户,**客户逐条点头**之后再 apply。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/asset-recovery`)));
+    server.tool('apply_recovered_final', '把某个**历史终拼**设为本集当前成片(免费,指针切换)。'
+        + '\n★这会**覆盖**本集现在对外的那一版成片。先用 get_asset_recovery 列出来、'
+        + '把是哪一版(时间/时长)讲清楚,**客户逐条确认**再调——不要凭「看起来更好」自己决定。'
+        + '\n★之后重新 compose_episode(终拼)会再把它覆盖回去。', {
+        episode_id: z.number().int().positive(),
+        merge_id: z.number().int().positive().describe('取自 get_asset_recovery 的 finals[].id'),
+    }, async ({ episode_id, merge_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/asset-recovery/finals/${merge_id}/apply`, {})));
+    server.tool('apply_recovered_candidate', '把某张**历史候选帧**回填到指定镜头(免费)。'
+        + '\n★**必须显式指定 target_storyboard_id**:这张图要回到哪一镜只有客户知道,平台不替你猜——'
+        + '猜错目标镜比不做更糟(会把另一镜正在用的帧换掉)。'
+        + '\n★同样是**逐条确认**:一次只回填一张,先把「哪张图、回到第几镜」讲给客户听。', {
+        episode_id: z.number().int().positive(),
+        generation_id: z.number().int().positive().describe('取自 get_asset_recovery 的 candidates[].id'),
+        target_storyboard_id: z.number().int().positive().describe('回填到哪一镜(必填,不猜)'),
+    }, async ({ episode_id, generation_id, target_storyboard_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/asset-recovery/candidates/${generation_id}/apply`, { target_storyboard_id })));
+    server.tool('rollback_asset_recovery', '把一次已应用的恢复**退回去**(免费)。apply 错了就用它撤销,恢复到应用之前的状态。', {
+        episode_id: z.number().int().positive(),
+        event_id: z.number().int().positive().describe('取自 get_asset_recovery 的恢复事件 id'),
+    }, async ({ episode_id, event_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/asset-recovery/events/${event_id}/rollback`, {})));
+    server.tool('list_wardrobe', '列本剧的**服装资产库**(免费)。每件服装是一个可被镜头引用的结构化资产,'
+        + '不是分镜里的文字描述。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/wardrobe`)));
+    server.tool('create_wardrobe', '新建一件服装资产(免费,纯文本写库)。建好之后要**绑到镜头上**才会影响出图——'
+        + '用 apply_wardrobe_timeline / apply_wardrobe_appearances,或在官网逐镜挑。', {
+        drama_id: z.number().int().positive(),
+        name: z.string().describe('这件服装叫什么(角色在剧里的某一身)'),
+        character_id: z.number().int().positive().optional().describe('属于哪个角色;通用服装可不填'),
+        episode_id: z.number().int().positive().optional(),
+        description: z.string().optional().describe('款式/材质/颜色等外观描述'),
+        palette_hint: z.any().optional().describe('配色提示'),
+        reference_image_urls: z.array(z.string()).optional().describe('参考图直链'),
+        notes: z.string().optional(),
+        product_id: z.number().int().positive().optional().describe('带货场景:关联商品'),
+        sort_order: z.number().int().optional(),
+    }, async (args) => jsonResult(await client.producePost('/wardrobe', args)));
+    server.tool('get_wardrobe', '读一件服装资产的详情(免费)。', { wardrobe_id: z.number().int().positive() }, async ({ wardrobe_id }) => jsonResult(await client.produceGet(`/wardrobe/${wardrobe_id}`)));
+    server.tool('update_wardrobe', '改服装资产(免费)。改完**不会**自动重出已生成的图:要让画面跟上得再调 regenerate_wardrobe_image,'
+        + '已出的镜头帧还要逐镜重出。', {
+        wardrobe_id: z.number().int().positive(),
+        name: z.string().optional(),
+        character_id: z.number().int().positive().optional(),
+        episode_id: z.number().int().positive().optional(),
+        description: z.string().optional(),
+        palette_hint: z.any().optional(),
+        reference_image_urls: z.array(z.string()).optional(),
+        notes: z.string().optional(),
+        product_id: z.number().int().positive().optional(),
+        sort_order: z.number().int().optional(),
+    }, async ({ wardrobe_id, ...fields }) => jsonResult(await client.producePut(`/wardrobe/${wardrobe_id}`, fields)));
+    server.tool('regenerate_wardrobe_image', '重出这件服装的资产图(**收费**,图片步按用量后付)。改完 description/参考图之后用它让图跟上。', { wardrobe_id: z.number().int().positive() }, async ({ wardrobe_id }) => jsonResult(await client.producePost(`/wardrobe/${wardrobe_id}/regenerate`, {})));
+    server.tool('delete_wardrobe', '软删一件服装资产(免费)。已绑定它的镜头不会被自动改,先确认没有镜头还在用。', { wardrobe_id: z.number().int().positive() }, async ({ wardrobe_id }) => jsonResult(await client.produceDelete(`/wardrobe/${wardrobe_id}`)));
+    server.tool('build_wardrobe_timeline', '算**服装时间线**:从剧本与分镜推出每个角色在各镜应该穿哪一身,并给出逐镜建议 diff。'
+        + '**要花钱**(走 LLM)。这是第①步,**只算不改**。\n'
+        + '★两段式:算完把 diff **逐条讲给客户**(哪一镜、从哪身换成哪身、为什么),'
+        + '客户勾选后再用 apply_wardrobe_timeline 落库。别替客户全盘应用。\n'
+        + '★**这一步解决的是「文字改了不生效」**:决定出图穿什么的是结构化绑定'
+        + '(active_wardrobe_id / appearances[].wardrobeAssetId),不是 update_shot 里的文字描述。'
+        + '只改文字、不改绑定,出图照旧穿原来那身。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/wardrobe-timeline`, {})));
+    server.tool('apply_wardrobe_timeline', '把客户勾选的换装建议落库(第②步,免费)。改的是每镜的 **active_wardrobe_id 结构化绑定**,'
+        + '不是文字描述——这正是「改了 update_shot 的文字却不生效」那个坑的正解。\n'
+        + '★只传客户点头的那几条;一次最多 200 条。\n'
+        + '★多角色同框的镜头单列装不下,那些走 apply_wardrobe_appearances。', {
+        episode_id: z.number().int().positive(),
+        items: z.array(z.any()).describe('build_wardrobe_timeline 给的建议,只放客户勾选的那几条'),
+    }, async ({ episode_id, items }) => jsonResult(await client.producePost(`/episodes/${episode_id}/wardrobe-timeline/apply`, { items })));
+    server.tool('apply_wardrobe_appearances', '逐角色回填 appearances 的服装绑定(第②步的多角色版,免费)。'
+        + '用于**多角色同框**的镜头:单个 active_wardrobe_id 装不下几个人各穿各的,'
+        + '这条按角色逐个绑。同样只传客户勾选的那几条,一次最多 200 条。', {
+        episode_id: z.number().int().positive(),
+        items: z.array(z.any()).describe('build_wardrobe_timeline 给的建议,只放客户勾选的那几条'),
+    }, async ({ episode_id, items }) => jsonResult(await client.producePost(`/episodes/${episode_id}/wardrobe-timeline/apply-appearances`, { items })));
+    server.tool('get_world_state', '读本集的**世界状态账本**：被追踪的实体(道具/服装/伤痕一类)在各镜之间的状态，'
+        + '以及对不上的地方(conflicts，带命中的两个镜号)。免费。'
+        + '\n★stale=true = 分镜改过但账本没重建，先 rebuild_world_state 再看，否则看的是旧账。'
+        + '\n★账本目前只是**报表**：不拦生成、也不自动注入出图。看到 conflicts 要自己决定'
+        + '改分镜(update_shot)还是加一条手工事件说明(add_world_state_event)。'
+        + '\n逐条事件的文字详情在官网面板看，这里给结构化概览。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/world-state`)));
+    server.tool('rebuild_world_state', '重建世界状态账本(**要花钱**：走 LLM 从分镜里抽取实体与状态变化)。'
+        + '\n改完分镜、或 get_world_state 回 stale=true 时才需要重建;没改过就别重复跑。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/world-state/rebuild`, {})));
+    server.tool('add_world_state_event', '往账本里加一条**手工事件**(免费)。用途：AI 没抽到、或抽错了的状态变化，由你补一条说明。'
+        + '\n典型场景：conflicts 报「同一件道具在两镜之间变了」，但剧情里确实发生过交接/损坏——'
+        + '补一条手工事件，冲突即被解释掉，不必去改分镜。', {
+        episode_id: z.number().int().positive(),
+        entity_key: z.string().describe('实体标识(与账本里的 entity_key 对齐)'),
+        shot_number: z.number().int().positive().optional().describe('这条事件发生在第几镜'),
+        description: z.string().optional().describe('发生了什么(给人看的说明)'),
+    }, async ({ episode_id, ...body }) => jsonResult(await client.producePost(`/episodes/${episode_id}/world-state/manual`, body)));
+    server.tool('delete_world_state_event', '删掉一条手工事件(免费)。只能删手工加的,AI 抽取出来的要靠 rebuild_world_state 重算。', {
+        episode_id: z.number().int().positive(),
+        event_id: z.number().int().positive(),
+    }, async ({ episode_id, event_id }) => jsonResult(await client.produceDelete(`/episodes/${episode_id}/world-state/manual/${event_id}`)));
+    server.tool('link_world_state_scene_variant', '把账本里的某条事件关联到一个**场景变体**(免费)。'
+        + '用途：同一场景在事件前后长得不一样(灯亮/灯灭、完好/破损),关联之后出图会取对应那版场景图。', {
+        episode_id: z.number().int().positive(),
+        event_id: z.number().int().positive(),
+        variant_id: z.number().int().positive().nullable().describe('传 null 解除关联'),
+    }, async ({ episode_id, event_id, variant_id }) => jsonResult(await client.producePut(`/episodes/${episode_id}/world-state/events/${event_id}/scene-variant`, { variant_id })));
+    server.tool('derive_pose_chain', '派生**姿态链**(Action Graph)：从相邻镜的动作推出每镜的起止姿态，让镜间衔接不跳。'
+        + '**要花钱**(走 LLM)。'
+        + '\n★只填**空着**的那些镜，已经写了姿态的不动;黑场镜自动跳过。'
+        + '\n出图前做，能减少「上一镜站着下一镜突然坐着」这类接不上的情况。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/derive-pose-chain`, {})));
+    server.tool('quote_extend_final', '★成片续写**报价**(免费·无副作用):在已有成片后面再接几轮 AI 生成的片段,把片子拉长。'
+        + '回 rounds(轮数)/duration_per_round(每轮秒数)/max_rounds(上限)/estimated_points(预估点数)。'
+        + '\n★**必须先报价、把点数讲给客户、客户确认后再调 extend_final**——每轮都真扣厂商的钱。'
+        + '\n★回 403 = 本剧没开这个能力(要求剧集视频引擎是 2.5 系)。这不是调用错误,别重试;'
+        + '告诉客户换引擎或走别的加长方式。', {
+        episode_id: z.number().int().positive(),
+        rounds: z.number().int().positive().describe('续写几轮'),
+        duration: z.number().positive().describe('每轮秒数'),
+        model: z.string().optional().describe('临时覆盖视频模型;不传用剧集设置'),
+    }, async ({ episode_id, rounds, duration, model }) => {
+        const qs = new URLSearchParams({ rounds: String(rounds), duration: String(duration) });
+        if (model)
+            qs.set('model', model);
+        return jsonResult(await client.produceGet(`/episodes/${episode_id}/extend-final/quote?${qs.toString()}`));
+    });
+    server.tool('extend_final', '发起成片续写(**收费**,每轮走视频生成扣费链)。后台串行跑,立即返回会话 id,用 get_extend_final 轮询。'
+        + '\n★调之前**必须**先 quote_extend_final 报价并让客户确认点数——不要替客户决定花钱。'
+        + '\n★续写只是「在成片后面接片段」,不改前面已有的内容;接出来的片段也**不会**自动成为本集成片,'
+        + '满意之后要显式调 apply_extend_final 才生效。'
+        + '\n★403 = 本剧没开(引擎需 2.5 系),别重试。', {
+        episode_id: z.number().int().positive(),
+        rounds: z.number().int().positive(),
+        duration: z.number().positive(),
+        model: z.string().optional(),
+    }, async ({ episode_id, ...body }) => jsonResult(await client.producePost(`/episodes/${episode_id}/extend-final`, body)));
+    server.tool('get_extend_final', '查本集所有续写会话的进度与产物。免费。'
+        + '每条会话回 status(pending/processing/completed/partial/failed)、rounds_completed、'
+        + 'final_url(产物直链)、applied(该产物**当前是不是**本集成片)、error_msg。'
+        + '\n★status=processing 时耐心轮询,别重复发起 extend_final(那会再扣一次钱)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/extend-final`)));
+    server.tool('apply_extend_final', '把某个续写产物**设为本集成片**(免费,纯指针切换)。'
+        + '\n★这一步会**覆盖**本集当前的成片链接:之前的成片不再是对外那一版。'
+        + '先用 get_extend_final 看 final_url、确认客户满意再调。'
+        + '\n★之后若重新 compose_episode(终拼),成片会被终拼结果覆盖回去,applied 自动变 false。', {
+        episode_id: z.number().int().positive(),
+        session_id: z.number().int().positive().describe('取自 get_extend_final 返回的 sessions[].id'),
+    }, async ({ episode_id, session_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/extend-final/${session_id}/apply`, {})));
+    server.tool('export_sheet_compare', '导出**设定图对照版**(角色设定图与成片画面的对照拼版,营销/交付用)。触发后台合成,用 get_sheet_compare 轮询。'
+        + '\n★这个能力**默认关**:它是剧集级开关(不是所有片子都允许这样对外输出),'
+        + '关着时回 **403**。看到 403 别重试、也别当成失败——告诉客户去官网的**剧集设置**里打开它。'
+        + '\n不传 character_id 就导出整集;传了只导这一个角色。', {
+        episode_id: z.number().int().positive(),
+        character_id: z.number().int().positive().optional().describe('只导这一个角色;不传=整集'),
+    }, async ({ episode_id, character_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/export/sheet-compare`, character_id ? { character_id } : {})));
+    server.tool('get_sheet_compare', '轮询设定图对照版的导出状态。免费。回 enabled(剧集开关是否打开)/processing/result/error。'
+        + '\n★enabled=false 就是那个剧集开关没开——不是出错,去官网剧集设置里打开再导。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/export/sheet-compare`)));
     // ========== 项目设定(建后可改)==========
     server.tool('update_project_settings', '建剧后修改项目设定。除画幅/分辨率/世界观Brief/族裔/题材/导演风格外,现覆盖★整剧视觉一致性锚' +
         '(摄影DNA cinematography_prompt/美术圣经 art_bible/视觉锁定 visual_lock/视频风格正负向词/视觉母题 motifs)、' +