@gitruck/cli 1.3.15 → 1.3.17

package/docs/workflow.en.md

@@ -18,10 +18,11 @@ The per-source limit for `oralcut` / `long2short` is **2 hours**. Longer sources
 
 1. **Set the content and production plan.** Check footage, script, aspect ratio, voice and visual direction. Listen to and adjust a voiceover before building its timeline.
 2. **Create the project and transcript.** Rough-cut, select highlights or build from voiceover. Review pacing and content before packaging.
-3. **Arrange visuals.** Dispatch segments and search platform or local footage. B-roll and AI reenactment clips are both base visuals and can be prepared separately.
+3. **Arrange visuals.** Dispatch segments and search platform or local footage, and decide which spans get the whole frame re-laid out (handed to compositing). B-roll and AI reenactment clips are both base visuals and can be prepared separately.
 4. **Settle the composition.** Choose candidate tracks in the client and inspect faces, subjects and safe areas. You may explicitly defer missing AI clips, then revisit affected compositions when they return.
-5. **Add motion graphics.** Place titles, diagrams and transparent overlays around the settled footage without obscuring its subjects.
-6. **Music, captions and delivery.** Add captions after the timeline settles, then preview, check and export video or supported editing projects.
+5. **Add captions.** Once the base is settled, add captions; composite spans take over the captions and re-lay them out, so captions come before compositing.
+6. **Composite, then motion graphics.** Build the composites first (the whole frame re-laid out for a span: speaker in a small window, side-by-side contrasts, list cards), then add titles and transparent overlays outside those spans without obscuring the subjects.
+7. **Music and delivery.** Music can go on at any point; then preview, check and export video or supported editing projects.
 
 Optional stages can be skipped. Quick mode groups key decisions; ask for step-by-step progress when you want to review each stage. Checkpoints and cost confirmations follow the relevant Skill.
 

package/docs/workflow.md

@@ -18,10 +18,11 @@
 
 1. **确定内容和制作方案。** 核对素材、稿件、画幅、声音和视觉方向。配音先试听调整，满意后再建时间线。
 2. **拿到工程与文稿。** 粗剪、选段或从配音建工程；先检查节奏与内容，再继续包装。
-3. **安排画面。** 分段派单，检索平台或本地素材。B-roll 与 AI 再现片段都属于底层画面，可分别准备。
+3. **安排画面。** 分段派单，检索平台或本地素材，同时定下哪些段要整幅重排（交给合成）。B-roll 与 AI 再现片段都属于底层画面，可分别准备。
 4. **确定底层构图。** 在客户端挑选候选轨，检查人脸、主体和安全区。AI 片段未回轨时，可明确先跳过，并在回轨后复查相关构图。
-5. **叠加动效。** 按最终画面安排字卡、图解和透明叠层，避免遮住主体。
-6. **配乐、字幕与交付。** 时间线确定后上字幕，预览、质检、导出成片或支持的剪辑工程。
+5. **上字幕。** 底层定了就上字幕；合成段会接管字幕、按版式重排，所以字幕在合成之前。
+6. **合成与叠加动效。** 先做合成（一段时间里整幅画面重排：讲者缩窗、多画对照、并列卡片），再在合成段以外叠字卡与透明叠层，避免遮住主体。
+7. **配乐与交付。** 配乐随时可以上；预览、质检、导出成片或支持的剪辑工程。
 
 可选环节可以省略。快速成片会集中确认关键选择；需要逐步看结果时，对 Agent 说“逐步来”。具体检查点与费用确认以对应 Skill 为准。
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gitruck/cli",
-	"version": "1.3.15",
+	"version": "1.3.17",
 	"description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
 	"license": "MIT",
 	"author": "Gitruck (同合云)",

package/skills/gtrk-ai-drama/SKILL.md

@@ -22,15 +22,15 @@ return-v1 标准包由 `gtrk ai-drama lay` 确定性回填；其他平台没有
 
 成片是**有序 SOP + 用户检查点**，不是并行一把铺。次序：
 
-> ① oralcut 剪口播 → ② split 视觉拆分派单 → ③ **B-roll 底轨全铺齐**（`matrix` 铺影视/本地素材 + **本 skill 产稿→外部出片→`gtrk ai-drama lay` 回填**，**两条腿同一阶段**）→ ④ **全局抽帧检查画面构图**（用户确认）→ ⑤ **mg 铺 MG（含 ov，最后叠上）** → `gtrk subtitle lay` 上字幕（快速成片模式必做）→ `gtrk render` 收口
+> ① oralcut 剪口播 → ② split 视觉拆分派单（含版式窗口）→ ③ **B-roll 底轨全铺齐**（`matrix` 铺影视/本地素材 + **本 skill 产稿→外部出片→`gtrk ai-drama lay` 回填**，**两条腿同一阶段**）→ ④ **全局抽帧检查画面构图**（用户确认）→ ⑤ `gtrk subtitle lay` 上字幕 → ⑥ `/gtrk-composite` 合成（版，含满屏卡）→ ⑦ 叠层（`gtrk mg`）→ `gtrk render` 收口。BGM 不受顺序约束；位次正本 `production-order`，口径见《成片型图纸公约》§二⁗「画面三层」。
 
-**你与 `matrix` 同属第 ③ 步，MUST 在 MG 之前落位。** 理由：**AI 情景片段属于底轨 B-roll 画面家族，不是叠加层**——整条管线里唯一的叠加层是 MG（含 ov）。MG 的排版决策是「因势象形避主体」、**依赖底轨的最终画面构图**；若你的片段在 MG 之后才回铺，底轨构图就变了，先产的 MG 是对着「还没有 AI 画面的底轨」做的避让，你的片段落位后必然被避让错位、甚至被 MG 盖住画面主体。
+**你与 `matrix` 同属第 ③ 步，MUST 在合成与 MG 之前落位。** 理由：**AI 情景片段属于底轨画面（三层里的「底」），不是叠层**——它上面还有合成（版）与 MG（叠层、满屏卡）。它们的排版决策是「因势象形避主体」、**依赖底轨的最终画面构图**；若你的片段在它们之后才回铺，底轨构图就变了，先做的排版是对着「还没有 AI 画面的底轨」做的，你的片段落位后必然被避让错位、甚至被盖住画面主体。版式窗口里的 AI beat 照常出片：合成会把它当槽位画进去。
 
-> ⚠️ **工序顺序**：AI 情景片段必须先落位；它属于底轨 B-roll，不是最后叠加的图层。之后再做全局构图检查与 MG。
+> ⚠️ **工序顺序**：AI 情景片段必须先落位；它属于底轨，不在合成或叠层那一级。之后再做全局构图检查、字幕、合成与 MG。
 
-**异步等待的口子（你造成的那个）**：你产完描述后，用户要去外部平台出片、抽卡可能数天。严格串行会把 ④⑤ 无限期卡住，故约定：进 ⑤ 的硬门是「**AI 片段已回铺 ∨ 用户明示先跳过**」。走「明示跳过」时，下游 `/gtrk-mg` MUST 把与你的 beat 相邻/重叠区间的 MG 颗粒标记为「AI 回铺后待复查构图」并在收口时复述——**你在交代进度时也要把这个代价说清**，让用户知道跳过意味着将来可能返工那几颗。
+**异步等待的口子（你造成的那个）**：你产完描述后，用户要去外部平台出片、抽卡可能数天。严格串行会把后面几步无限期卡住，故约定：进 ⑥ 合成与 ⑦ MG 的硬门是「**AI 片段已回铺 ∨ 用户明示先跳过**」。走「明示跳过」时，下游 `/gtrk-mg` MUST 把与你的 beat 相邻/重叠区间的 MG 颗粒标记为「AI 回铺后待复查构图」并在收口时复述——**你在交代进度时也要把这个代价说清**，让用户知道跳过意味着将来可能返工那几颗。
 
-**你的下一步**：产完描述 → 用户拿去外部平台出片 → 若拿到 AI Drama Desk return-v1 导出目录，立即用 `gtrk ai-drama lay` 回填；其他平台没有标准包时才降级为用户手动回铺 → 三源齐了进 **④ 全局抽帧检查画面构图**（对最终底轨抽帧、用户确认）→ 过了才交棒 ⑤ `/gtrk-mg`。**MUST NOT 直接从你这里跳到 `render`** ——后面还有构图检查与 MG 两步。
+**你的下一步**：产完描述 → 用户拿去外部平台出片 → 若拿到 AI Drama Desk return-v1 导出目录，立即用 `gtrk ai-drama lay` 回填；其他平台没有标准包时才降级为用户手动回铺 → 三源齐了进 **④ 全局抽帧检查画面构图**（对最终底轨抽帧、用户确认）→ 过了才往 ⑤ 字幕 → ⑥ `/gtrk-composite` → ⑦ `/gtrk-mg` 走。**MUST NOT 直接从你这里跳到 `render`** ——后面还有构图检查、字幕、合成与 MG。
 
 ## 四条铁律（先记死）
 
@@ -261,8 +261,8 @@ face / hair / eyes / wardrobe / signature prop + do-not-change + one line on how
 
    命令会先按当刻口播工程重投影 beat 窗口，再把所有镜头复制到 `<gtrk目录>/assets/ai-drama/<slug>/`，共用一条新的 `video_track`；每个 beat 从起点顺排，最后一镜吸收到 beat 终点。既有 A-roll、BGM 与 B-roll 轨零改动。若已铺 AI 轨被用户手调过，缺省拒绝覆盖；只有用户明确同意丢弃手调时才加 `--replace-all`。
 3. **非标准平台才手动回铺**：外部平台没有 return-v1 清单时，才由用户把片段拖回 opencut 的 **AI_DRAMA 车道**，对齐该 beat 的 `track_st→track_ed`。AI 出片仍是外部异步、用户驱动；未拿到完整片段前要停下等用户，别替他假装出片 / 回轨完成。
-4. **回铺齐 ≠ 收口，还有两步**：你的片段回铺齐只意味着 **③ B-roll 底轨阶段**完成。接着 MUST 走 **④ 全局抽帧检查画面构图**（对三源合并后的最终底轨抽帧，看主体位置 / 安全区 / 画面朝向 / 明暗，**停下等用户确认**）→ 过了才交棒 **⑤ `/gtrk-mg`** 把 MG（含 ov）叠上 → 最后才 `gtrk render` 收口。
-   ⚠️ **MUST NOT 从你这里直接跳到 `render`**；先完成全局构图检查与 MG，再进入字幕和渲染。
+4. **回铺齐 ≠ 收口，后面还有几步**：你的片段回铺齐只意味着 **③ B-roll 底轨阶段**完成。接着 MUST 走 **④ 全局抽帧检查画面构图**（对三源合并后的最终底轨抽帧，看主体位置 / 安全区 / 画面朝向 / 明暗，**停下等用户确认**）→ 过了才 **⑤ 上字幕** → **⑥ `/gtrk-composite`**（拆分有版式窗口时，含满屏卡）→ **⑦ `/gtrk-mg`** 铺叠层 → 然后才 `gtrk render` 收口。
+   ⚠️ **MUST NOT 从你这里直接跳到 `render`**；先完成全局构图检查、字幕、合成与 MG，再渲染。
 
 > 原则：**agent 替用户跑 CLI / 接力 skill，用户只对话**。但 AI_DRAMA 车道天然有「用户去外部平台出片 + 手动拼回」的手工环节——那部分是外部的手，无法替跑；除此之外的解析、生成、落盘、交代，全由你（脑）一次做完，别让用户自己去拼描述。