@starreel/mcp 0.1.144 → 0.1.149

package/SKILL.md

@@ -2,8 +2,9 @@
 name: starreel-drama-production
 description: >-
   Operating skill for any AI agent driving the StarReel short-drama production
-  pipeline (script → rewrite → extract → portraits + sheets → storyboards → frames →
-  video → voiceover → final cut) over MCP or REST. Covers the ordered workflow,
+  pipeline (script → rewrite → extract → storyboards → portraits + sheets → color
+  script → scene images → frames → video → voiceover → final cut) over MCP or REST.
+  Covers the ordered workflow,
   the entry-point decision table (which channel each kind of customer material
   takes), the eleven operating disciplines (prepaid billing, quote-before-spend, retryable
   failure handling, content compliance, tenancy), and a failure playbook.
@@ -41,13 +42,17 @@ create_drama → set_script(raw) → rewrite_script(AI draft, user may edit)
   → scene-images(empty-set plates = the background anchor — every shot in a scene
     anchors on its plate; skip it and each scene's FIRST shot has no background
     anchor at all, and the backdrop drifts from shot to shot)
+  → prop sheets(generate_prop_sheet per referenced prop = the prop anchor)
+  → [review_assets]
   → frames(first frames → tail_frame_plan → tail frames)
   → seams(chain_frames dry_run → confirm → run; per-shot fixes via chain_shot_from*)
-  → [review_frames] → videos → generate_tts(voiceover) → compose_episode → final cut (.mp4 link)
+  → [review_frames] → videos → generate_tts(voiceover) → [review_videos]
+  → compose_episode → final cut (.mp4 link) → review_final_cut
 ```
 
-The three `[review_*]` steps are free and **enforced** — see discipline 11.
-Nothing downstream of them runs until you have reviewed that layer.
+The five `[review_*]` steps are free and **enforced** — see discipline 11.
+Nothing downstream of them runs until you have reviewed that layer **and done
+your own QC of it** (look at the materials yourself, then `submit_qc_report`).
 
 `project_type` picks the flavor at `create_drama`: `drama` / `ad` / `mv` /
 `brand_film`. MV replaces `rewrite_script` with
@@ -176,8 +181,23 @@ Don't ask the user at every step. Sort work into three tiers:
    contradict: portraits follow the profile, sheets follow the lock, and the
    consistency gate then rejects the sheet against the portrait **every single
    retry** — a structural dead loop that only burns money.
-2. **Pipeline backbone — metered; in order; quote-then-confirm.** portraits →
-   **character sheets** → scene images → frames → videos → TTS → compose.
+2. **Pipeline backbone — metered; in order; quote-then-confirm.** storyboards
+   (text-only, needs no image) → portraits → **character sheets** → color script
+   → scene images → frames → videos → TTS → compose. Build portraits and sheets
+   **after** storyboards, never before: storyboards need no image, and once they
+   exist you can see which visual characters never appear and `delete_character`
+   them first. `generate_portraits_and_sheets` renders **every undeleted visual
+   character** that still lacks an image / sheet — it does not consult shot
+   bindings — so an unused visual character left in the cast is billed like any
+   other. Pruning is **drama-wide, not per episode**: characters belong to the
+   drama, and `delete_character` removes the role from every episode's frame
+   assembly, so delete only a character that appears in no shot of **any**
+   episode and is not planned for a later one (confirm with the customer); when
+   in doubt keep it — one portrait costs far less than a missing identity anchor
+   in a later episode. Voice-only roles (`char_type` `voiceover`: narrator, phone
+   voice) are skipped by the portrait step and have no shot binding by design —
+   **keep them**, they still carry the dubbing. This is also the order
+   `get_pipeline_status` reports.
    Spending stages follow the normal quote → show the user → confirm flow
    (discipline 2). `quote_character_portraits` quotes **portraits only**; the
    sheets that must follow have no quote tool (billed by usage) — tell the user
@@ -259,7 +279,9 @@ content that will be rejected.
    speaks alone, at length, without music, and locks that as the character's
    voice — no customer recording needed. It locks only videos generated
    *afterwards*, so the cheapest order is: generate one shot per speaking
-   character, pick the voice, then generate the rest. `get_pipeline_status` →
+   character with `quote_regenerate_shot_video` → `regenerate_shot_video`
+   (`generate_videos` has no shot filter), pick the voice, then `generate_videos`
+   the rest. `get_pipeline_status` →
    `native_voice_anchor` lists `unanchored_speakers` (not locked yet) and
    `stale_shots` (made before the lock — `regenerate_shot_video` them). Decide
    the voice reference early; picking it after the whole episode is rendered
@@ -290,7 +312,18 @@ content that will be rejected.
    like `clone_voice`; the same candidate saved twice is charged once.
 
 6. **Follow the pipeline order — do not skip.** `set_script` → `rewrite_script`
-   → `extract_assets` → portraits **+ sheets** → storyboards → frames → videos.
+   → `extract_assets` → storyboards → portraits **+ sheets** → color script →
+   scene images → frames → videos. Storyboards are a text-only step that needs
+   no image, so build portraits / sheets / scene plates **after** them, once the
+   cast is settled: prune **visual** characters that appear in no shot of **any
+   episode** (and are not planned for a later one — characters are drama-wide,
+   `delete_character` removes them from every episode; confirm with the
+   customer, keep when in doubt) with `delete_character` before spending — the
+   portrait step renders **every undeleted visual character** without an image,
+   not just the ones bound to shots. Never prune voice-only roles (`char_type` `voiceover`: narrator, phone
+   voice): they are skipped by the portrait step, have no shot binding by design,
+   and the dubbing still needs them (motion templates must follow storyboards
+   anyway).
    **The rewrite step is mandatory and server-enforced**: put your raw material
    (outline, synopsis, or even a finished script you wrote) into `set_script`,
    then run `rewrite_script` — the platform rewrite produces a shootable draft
@@ -308,6 +341,12 @@ content that will be rejected.
    are the shot consistency anchor every frame references** — portraits alone
    leave characters drifting across angle / lighting / wardrobe.
    `generate_portraits_and_sheets` does both (portraits first, then sheets).
+   **`generate_videos` has no per-shot parameter** — it renders every shot of
+   the episode that still lacks a video, in one run. When a native-audio project
+   needs one seed shot per speaking character before locking voices, render those
+   seeds with the single-shot tools `quote_regenerate_shot_video` →
+   `regenerate_shot_video` (they work on a shot that has no video yet), lock the
+   voice with `set_voice_anchor_from_shot`, then `generate_videos` for the rest.
    **Frames take two passes.** `generate_frames` makes **first frames only** by
    default — never first + last in one call. Once the first frames have landed,
    **always call the free `tail_frame_plan`**: it names the shots that need their
@@ -490,20 +529,52 @@ content that will be rejected.
     key in an environment variable or secrets manager, never in code or logs.
     The 15-min token auto-re-exchanges; a leaked key is revoked in Settings.
 
-11. **Review every layer before you spend on the next one — free, and three of
+11. **Review every layer before you spend on the next one — free, and five of
     them are enforced.** Never run the pipeline straight through from
     `rewrite_script` to `compose_episode`. A flaw in the rewritten draft gets
     copied into character profiles, then storyboards, then frames, then video —
     by the time you see it in the final cut, the whole episode has to be redone,
     and every redo is another real charge. Reviewing costs nothing.
 
-    **Three hard gates** (the server returns `400` if you skip them):
+    **Five hard gates** (the server returns `400` if you skip them; the assets
+    and videos gates are rolled out per drama):
 
     | After you produce | Run | Before you call |
     |---|---|---|
     | the rewritten draft | `review_script` | `extract_assets`, `generate_storyboards` |
-    | storyboards | `review_storyboards` | `generate_frames` |
-    | shot frames | `review_frames` | `generate_videos` |
+    | storyboards | `review_storyboards` | `generate_frames`, `generate_shot_frame` |
+    | portraits, sheets, scene plates, prop sheets | `review_assets` | `generate_frames`, `generate_shot_frame` (pass its token as `asset_review_token`, alongside the storyboard `review_token`) |
+    | shot frames | `review_frames` | `generate_videos`, `regenerate_shot_video` |
+    | videos, voiceover, BGM | `review_videos` | `compose_episode` |
+
+    **Your own QC, on top of the platform's.** The platform can tell whether an
+    asset exists, is still generating, or was rejected; it cannot tell whether
+    it *looks right*. Every `review_*` response carries `agent_qc`: a checklist
+    for that layer and the materials to inspect (one `ref` each — script, every
+    shot, every on-screen character's portrait and sheet, every scene plate and
+    prop sheet, every frame, every video — with links). Open each one yourself
+    (download and view images, sample at least the start, middle and end of each
+    video, read text with the named tool), answer every checklist item
+    (`ok` / `issue` / `na`, with a note for each issue), list every `ref` you
+    inspected, and call `submit_qc_report`. The server only checks that the
+    report is complete — every item answered, every material listed, no "pass"
+    with issues in it — it does not judge your verdict. When
+    `agent_qc.required` is true the `review_token` is unusable until the report
+    is in, and a report with `verdict: "issues"` holds the gate exactly like a
+    platform error (only the user's explicit OK + `acknowledge_review: true`
+    lets it through). Relay your QC findings to the user verbatim. Listing a
+    `ref` you never opened is signing off on the user's money.
+
+    The per-shot tools are gated too (since 2026-10-14). A whole episode driven
+    shot by shot through `generate_shot_frame` / `regenerate_shot_video` used to
+    touch none of the gates; now each takes the same `review_token` as its batch
+    counterpart. A finished frame does **not** invalidate the storyboard token
+    (that fingerprint covers storyboard content only — prompts, dialogue, shot
+    size, bindings; not generated images). Only editing storyboards
+    (`update_shot`, imports, adding/removing shots, character bindings) requires
+    a fresh `review_storyboards`. A finished frame does change the *frames*
+    fingerprint, so run `review_frames` again before the next
+    `regenerate_shot_video`.
 
     Each review returns `{ pass, error_count, warning_count, findings[],
     review_token }`. Every finding carries `code` (problem type), `shots`

package/dist/i18n/instructions.en.md

@@ -17,8 +17,9 @@ StarReel = a prepaid AI short-drama production line (script → AI rewrite → a
 · They want to edit themselves and need a per-shot handoff pack (clean footage / dialogue track / SFX / music / subtitles) → export_handoff_pack → get_handoff_toolchain → save_handoff_toolchain
 · Multilingual release → translate_subtitles → update_project_settings
 
-Pipeline order (no skipping): create_drama (set setting_brief / aspect ratio / video_engine / image_model / consistency anchors at creation — all free) → set_script → rewrite_script → ★review_script → extract_assets → quote/generate_storyboards → ★review_storyboards → character sheets + design sheets / world concept / motion templates / color script → run_precheck → quote/generate_frames (first frames only by default) → tail_frame_plan (free · which shots need a separate last frame) → quote/generate_frames (frame_type=last_frame) → ★review_frames → quote/generate_videos → audio → compose_episode → get_final_cut. Track progress with get_pipeline_status.
-Three free hard gates (skipping → 400): review_script (before extract_assets / storyboards) · review_storyboards (before frames) · review_frames (before videos); pass the review_token to downstream paid tools and relay every finding to the customer verbatim.
+Pipeline order (no skipping): create_drama (set setting_brief / aspect ratio / video_engine / image_model / consistency anchors at creation — all free) → set_script → rewrite_script → ★review_script → extract_assets → quote/generate_storyboards → ★review_storyboards → character sheets + design sheets / scene plates / prop sheets / color script → ★review_assets → run_precheck → quote/generate_frames (first frames only by default) → tail_frame_plan (free · which shots need a separate last frame) → quote/generate_frames (frame_type=last_frame) → ★review_frames → quote/generate_videos → audio → ★review_videos → compose_episode → get_final_cut → review_final_cut. Track progress with get_pipeline_status.
+Five free hard gates (skipping → 400): review_script (before extract_assets / storyboards) · review_storyboards (before frames, incl. per-shot generate_shot_frame) · review_assets (before frames; pass its token as asset_review_token) · review_frames (before videos, incl. per-shot regenerate_shot_video) · review_videos (before compose_episode); pass the review_token to downstream paid tools (batch and per-shot alike) and relay every finding to the customer verbatim.
+★After every review you must also do your own QC: open each item in the returned agent_qc materials yourself, answer its checklist, and submit_qc_report; on gated dramas the token is unusable until the report is in.
 Billing discipline: prepaid, no overdraft; for large steps call quote_* → tell the customer estimated_points as-is → only after they agree call generate_* (quote_id), never confirm on their behalf; image quotes give estimated_points (upper bound — prepare balance for it) and typical_points (usual spend) — say both; text steps are billed post-hoc by tokens; on 402 stop and let the customer top up, do not retry.
 Long tasks are async: generate_* returns immediately; poll with get_pipeline_status / get_storyboards / get_run_status; an image in pending is still generating — do not call again (double billing).
 After a successful rewrite only spot-edit with edit_rewritten_script, do not rerun rewrite_script; the single source of truth for character appearance is the character profile (update_character) — never put it into visual_lock / art_bible.

package/dist/i18n/instructions.zh-CN.md

@@ -17,8 +17,9 @@ StarReel = 预付费 AI 短剧产线(剧本 → AI 改写 → 资产 → 分镜
 · 想自己剪:要逐镜素材包(裸片 / 对白轨 / 音效 / 配乐 / 字幕) → export_handoff_pack → get_handoff_toolchain → save_handoff_toolchain
 · 多语言发行 → translate_subtitles → update_project_settings
 
-产线顺序(不跳步):create_drama(建剧即设好 setting_brief/画幅/video_engine/image_model/一致性锚,全免费) → set_script → rewrite_script → ★review_script → extract_assets → quote/generate_storyboards → ★review_storyboards → 定妆图+设定图 / 世界观图 / 动作模板 / 色彩脚本 → run_precheck → quote/generate_frames(默认只出首帧) → tail_frame_plan(免费·哪几镜要独立尾帧) → quote/generate_frames(frame_type=last_frame) → ★review_frames → quote/generate_videos → 音频 → compose_episode → get_final_cut。用 get_pipeline_status 查进度。
-三道免费硬闸(跳过 → 400):review_script(extract_assets/分镜前)· review_storyboards(出图前)· review_frames(出视频前);review_token 随下游收费工具传,findings 逐条原样告诉客户。
+产线顺序(不跳步):create_drama(建剧即设好 setting_brief/画幅/video_engine/image_model/一致性锚,全免费) → set_script → rewrite_script → ★review_script → extract_assets → quote/generate_storyboards → ★review_storyboards → 定妆图+设定图 / 场景图 / 道具图 / 色彩脚本 → ★review_assets → run_precheck → quote/generate_frames(默认只出首帧) → tail_frame_plan(免费·哪几镜要独立尾帧) → quote/generate_frames(frame_type=last_frame) → ★review_frames → quote/generate_videos → 音频 → ★review_videos → compose_episode → get_final_cut → review_final_cut。用 get_pipeline_status 查进度。
+五道免费硬闸(跳过 → 400):review_script(extract_assets/分镜前)· review_storyboards(出图前,含单镜 generate_shot_frame)· review_assets(出图前,token 作 asset_review_token)· review_frames(出视频前,含单镜 regenerate_shot_video)· review_videos(compose_episode 前);review_token 随下游收费工具传(批量与单镜工具都要),findings 逐条原样告诉客户。
+★每层审查之后你还要亲自质检:按返回的 agent_qc 逐件看素材,submit_qc_report 提交报告;灰度剧没交报告进不了下一步。
 计费纪律:预付费不透支;大额步 quote_* → 把 estimated_points 原样告诉客户 → 客户同意后 generate_*(quote_id),绝不擅自确认;出图类报价给 estimated_points(上界,按它准备余额)与 typical_points(通常花费),两个都说;文本步按 token 后付;402 就停下让客户充值,别重试。
 长任务异步:generate_* 立即返回,用 get_pipeline_status / get_storyboards / get_run_status 轮询;图片 pending = 还在生成,别重复调(重复扣费)。
 改写成功后只 edit_rewritten_script 点改,别重跑 rewrite_script;角色外观唯一真相源是人物档案(update_character),别写进 visual_lock/art_bible。