@gitruck/cli 0.2.7 → 0.2.8

package/README.md

@@ -79,9 +79,11 @@ gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选
 | ③ | 「**先铺 B-roll**」 | `/gtrk-matrix` → `gtrk matrix` → 候选轨铺入 | **opencut 里挑选/调整 B-roll**（小眼睛切换对比） |
 | ④ | 「B-roll 定了，**铺 MG**」 | `/gtrk-mg` → `gtrk mg` → MG 颗粒叠在 B-roll 之上 | 精修颗粒（opencut 手调） |
 | ⑤ | 「**上 AI 再现**」 | `/gtrk-ai-drama`（skill，无命令）→ 四段描述稿（中英分块） | 外部平台出片、片段手动回铺 |
-| ⑥ | 「**渲成片**」 | `gtrk render`（或 opencut 打开精修） | 成片 mp4 |
+| ⑥ | 「**出成片**」 | 客户端出片链（多车道合成 + 颗粒云渲 / 导剪映）；`gtrk render` 只出**主轨快照预览** | 客户端里精修定稿 |
 
 > 次序有理由：**MG 叠在 B-roll 之上**，要先把底层 B-roll 定下来、你满意了再铺 MG；AI 再现最后上。用不到的车道跳过（`dispatch` 里该队列为空就不铺）。
+>
+> ③④⑤⑥ 都要**回到客户端**挑选 / 精修 / 回铺 / 出片——CLI 把料铺进 `.gtrk`，客户端把 `.gtrk` 出成片。详见下文「**CLI × 客户端**」小节。
 
 **遇到情况怎么办**
 
@@ -95,6 +97,33 @@ gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选
 | 连不上 / 配置出问题 | 「体检一下」→ `gtrk doctor`（配置 / 云端 / 剪映目录 / 版本一键自检） |
 | 有新版 | 「升级」→ `gtrk upgrade`（升 CLI + 刷 skill，配置保留） |
 
+## CLI × 客户端：手脑分工、一份 `.gtrk` 贯穿全程
+
+**标准工作流从来不是「只用 CLI」，而是 CLI + 桌面客户端相互配合——客户端是成片流程绕不过去的一环。** 二者分工：
+
+- **CLI = 无头装配器（手/机械活）**：把云端剪辑产物、检索到的 B-roll、栏目产的颗粒，确定性地装进工程、原子写回 `.gtrk`（剪口播 / 拆分派单 / 铺 B-roll 候选轨 / 铺 MG 颗粒）。不做审美判断、不出最终成片。
+- **桌面客户端 = 有头工作台（眼/精修活）**：打开**同一份 `.gtrk`**，让你看、挑、逐帧精修、回铺 AI 片段、出片。装法见上一节「升级 → 桌面客户端」的一键脚本（OpenCut Gitruck Edition）。
+
+**`.gtrk` 是两者之间的交接介质**——它是同合云的统一工程契约（timeline 真超集 + HTML 颗粒 + `struct_meta`），**CLI 写、客户端读，双向**。所以一条片子是 CLI 与客户端**交替推进**的：
+
+```
+CLI 写 .gtrk ─▶ 客户端打开(自动感知外部改动、先存脏改再刷新、不丢稿)
+   ─▶ 你在客户端挑/调/精修 ─▶ 需要就再喊 agent 让 CLI 写下一轮(铺 MG / 铺 AI…)
+   ─▶ … 反复 … ─▶ 客户端出片
+```
+
+**这几件事只能在客户端做（CLI 给不了）：**
+
+| 环节 | 为什么必须在客户端 |
+|---|---|
+| **B-roll 候选挑选** | `gtrk matrix` 铺 N 条候选轨，用轨道**小眼睛**逐条切换对比、选定、删多余——审美取舍只能人在客户端做 |
+| **MG / 颗粒精修** | 客户端里 html-particle **活颗粒透明预览** + Transform/Blending/Effects 参数逐帧微调 |
+| **口播精剪** | 磁性主轨 ripple、手动微调切点 / 停顿 / 分屏 |
+| **AI 再现回铺** | 外部平台出的 AI 片段**手动拖进 AI_DRAMA 车道**对齐区间（`/gtrk-ai-drama` 只吐描述稿，片在外部平台出，见 SOP ⑤） |
+| **最终出片** | 多车道合成（overlay / MG / particle 云渲叠起来）+ 剪映草稿导出，都在客户端出片链 |
+
+> **`gtrk render` ≠ 最终成片。** `gtrk render` 是本地 ffmpeg 出**主轨（口播粗剪）的快照预览**——只合主视频轨 + 音轨，**不合成 overlay（B-roll 候选）/ MG 颗粒 / AI 再现**。要出**真正的多车道成片**（各车道叠起来、颗粒云渲、导剪映草稿），走**客户端出片链**。一句话：**CLI 管「把料铺进工程」，客户端管「把工程出成片」。**
+
 ## 升级
 
 **CLI + skill**（配置原样保留）：

package/package.json

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

package/skills/gtrk-mg/SKILL.md

@@ -28,12 +28,12 @@ description: MG 动态图颗粒铺轨器——成片 SOP 第 ④ 步，在 B-rol
 
 **本框架 skill 不硬编任何栏目的视觉风格/生产内容。** MG 颗粒长什么样、用什么视觉语法，全由**栏目的 MG 生产 skill** 决定；本 skill 只负责「在对的时候、按派单、驱动它产，然后把成品铺进工程」。
 
-**车道 → 栏目生产 skill 的解析（照此，别猜）**：读**有效栏目配置**的 `style.skills[]`（配置文件 `~/.gitruck/columns/<id>.json`；栏目 id 由 `--column <id>` 或 config `defaultColumn` 选取，零配置 = 内置默认栏目 **real-roam-viz**）。在 `style.skills[]` 里取 **`produces` 归一后（旧 `RRV_MG` → `MG`）等于 `MG`** 的条目 → 触发它 `ref` 指向的 skill 产颗粒。
+**车道 → 栏目生产 skill 的解析（照此，别猜）**：读**有效栏目配置**的 `style.skills[]`（配置文件 `~/.gitruck/columns/<id>.json`；栏目 id 由 `--column <id>` 或 config `defaultColumn` 选取；零配置 = L0 内置默认栏目，**不携带 style 清单** → 必然走下方「无匹配」分支）。在 `style.skills[]` 里取 **`produces` 归一后（旧 `RRV_MG` → `MG`）等于 `MG`** 的条目 → 触发它 `ref` 指向的 skill 产颗粒。
 - 命中多条 → 按栏目约定取其一（一般栏目只登记一个 MG 生产 skill）。
 - 条目带 `routing:"none"`（管线外产物，如封面）→ 跳过，不当 MG 生产 skill。
 - **无匹配** = 本栏目没有 MG 生产 skill → 别硬铺；告诉用户「本栏目还没有 MG 生产 skill，先用 `/gtrk-style-maker` 建一个，或换个已配置的栏目（`--column`）」。
 
-> **生产 skill 是栏目的纯净资产**：它只懂本栏目的视觉语法、只产 html-particle 颗粒，**不知道 gtrk 命令、不知道产物落哪**。由本 skill 驱动它、并**由本 skill 负责把它产出的颗粒存到 `gtrk mg` 要读的路径**：`<产物目录>/mg/<composition_id>.html`。默认栏目 real-roam-viz 的生产 skill 即 `real-roam-viz`（produces=MG）。
+> **生产 skill 是栏目的纯净资产**：它只懂本栏目的视觉语法、只产 html-particle 颗粒，**不知道 gtrk 命令、不知道产物落哪**。由本 skill 驱动它、并**由本 skill 负责把它产出的颗粒存到 `gtrk mg` 要读的路径**：`<产物目录>/mg/<composition_id>.html`。举例（仅示意解析机制，非硬编）：`real-roam-guide` 栏目配置里 `style.skills` 有一条 `{produces:"MG", ref:"…/real-roam-viz"}` → 驱动它产颗粒；换个栏目、换个 ref，产颗粒的就是另一个生产 skill。**本 skill 正文里不绑死任何栏目的生产 skill。**
 
 ## 逐槽位工作流（产 → lint → 铺，循环到铺满）
 
@@ -89,7 +89,7 @@ gtrk mg --project "<split产物目录>" --json
 ## 交棒 ⑤（别停在铺完）
 
 `dispatch.mg` 全铺满、`gtrk mg status` 全绿后**别收工**——按 SOP 顺势接力到第 ⑤ 步 **AI 再现**：
-- `dispatch.ai_drama` 非空 → 触发 `/gtrk-ai-drama`（持通用分镜 craft + 读栏目 style-lock 产风格化分镜提示词，用户去 Sora / Veo / 可灵等外部平台出片回铺；**此车道产物即提示词、无 gtrk 命令**）。一句话交代即推进：「MG 颗粒已叠铺完，我接着安排最后一步 AI 再现」。
+- `dispatch.ai_drama` 非空 → 触发 `/gtrk-ai-drama`（持通用分镜 craft + 读栏目 style-lock，产 AI 再现分镜稿——四段描述 + 独立视觉基调 + 时长预算；用户去可灵 / Vidu 等外部平台出片回铺；**此车道产物即分镜稿、无 gtrk 命令**）。一句话交代即推进：「MG 颗粒已叠铺完，我接着安排最后一步 AI 再现」。
 - `dispatch.ai_drama` 为空 → 本片没有 AI 车道，可直接 `gtrk render` 收口成片。
 
 除非用户表示只铺这一版 MG、暂不往下。

package/skills/gtrk-splitter/SKILL.md

@@ -74,7 +74,7 @@ gtrk split --project "<oralcut产物目录>" --json
 - **handoff 按 lane 分型**（校验器会硬查）：
   - `MG` → `handoff:{slug_hint?, theme?, bg?, duration_hint}`，**`duration_hint`（秒）必填**；可选 `category`（overlay 透明叠加/fullscreen 不透明满屏,裁决⑩,供色带分层,详见 field-schema）。
   - `FILM_BROLL` → `handoff:{queries:[...非空], shots?, per_shot_sec?, exclude?}`，**`queries` 非空必填**；queries 写**英文长句场景描述**（一条一个意象，避多义动词），**exclude 保持中文**（细则见 field-schema）。
-  - `AI_DRAMA` → `handoff:{narrative?, theme?, emotion_stage?, platform?, shot_count?}`，全可选（下游 ai-drama-prompter 有推断默认）。
+  - `AI_DRAMA` → `handoff:{narrative?, theme?, emotion_stage?, platform?, shot_count?}`，全可选（下游框架 skill /gtrk-ai-drama 有推断默认）。
   - `A_ROLL` → **无 handoff**（写了会被警告忽略）。
 
 ### 4. 落地校验
@@ -115,7 +115,7 @@ dispatch 落地后**不要收工**——但下游各车道是**有先后的 SOP
 
 - **③ B-roll**（`dispatch.film_broll` 非空）：跑 `gtrk matrix --project <目录>`（检索 + 候选铺轨）→ **提示用户 opencut 里挑选/调整 B-roll**（小眼睛切换对比），确认后再进 ④。
 - **④ MG**（`dispatch.mg` 非空）：先由**栏目 MG 生产 skill** 按各槽位 `handoff`（theme/duration_hint/category）产 html-particle 颗粒，再跑 `gtrk mg --project <目录>`（lint + 铺轨，叠在 B-roll 上）。
-- **⑤ AI 再现**（`dispatch.ai_drama` 非空）：触发 `/gtrk-ai-drama` skill（持通用分镜 craft + 读栏目 style-lock）产风格化分镜提示词 → 用户去 Sora / Veo / 可灵 等外部平台出片、回铺（**此车道产物即提示词、无机械尾巴 → 只 skill、无 gtrk 命令**，同 `/gtrk-style-maker`）。
+- **⑤ AI 再现**（`dispatch.ai_drama` 非空）：触发 `/gtrk-ai-drama` skill（持通用分镜 craft + 读栏目 style-lock）产 AI 再现分镜稿（四段描述 + 独立视觉基调 + 时长预算）→ 用户去可灵 / Vidu 等外部平台出片、回铺（**此车道产物即分镜稿、无机械尾巴 → 只 skill、无 gtrk 命令**，同 `/gtrk-style-maker`）。
 
 **各车道的生产 skill 由栏目配置解析（业务分离）**：读 `style.skills[]`，取 `produces` 归一（旧 `RRV_MG`→`MG`）== 该车道 的条目 → 触发其 `ref` 指向的 skill；`routing:"none"` 跳过；无匹配 = 无生产 skill（B-roll 无需、A_ROLL 就是口播本身）。生产 skill 是栏目资产、留纯净、不知 gtrk 命令。
 

package/skills/gtrk-splitter/references/field-schema.md

@@ -65,7 +65,7 @@
 //   - **避多义/字面义强的动词**（"pointing" 会召回手指特写、"hunting" 召回猎人——改用 "giving suggestions in a meeting" 这类场景语义）
 //   - **exclude 保持中文**：负向过滤匹配的是服务端返回的中文 note，写英文会失效
 
-// lane === "AI_DRAMA"  —— 全可选（下游 ai-drama-prompter 有推断默认）
+// lane === "AI_DRAMA"  —— 全可选（下游框架 skill /gtrk-ai-drama 有推断默认）
 "handoff": { "narrative": "trauma-repetition", "theme": "freud-fort-da", "emotion_stage": "abyssal", "platform": "video-gen", "shot_count": 5 }
 
 // lane === "A_ROLL"  —— 无 handoff