@gitruck/cli 0.2.6 → 0.2.8

package/AGENT.md

@@ -122,7 +122,7 @@ gtrk oralcut-result 88269671080189958 --render --out "D:/回收/某条"
 
 ## 2.2 视觉拆分派单器：`gtrk split`（成片 → 分镜派单）
 
-`oralcut` 出的是「剪好的口播成片」；`split` 把它拆成 **beat 级视觉分镜**并派单给下游四车道（真人 A-roll / RRV_MG 动态图 / AI_DRAMA 再现 / FILM_BROLL 影视素材）。**纯本地、同步、无云端任务**。上游依赖 `transcript.json`（oralcut 家族恒出的句级词表，源时基）。
+`oralcut` 出的是「剪好的口播成片」；`split` 把它拆成 **beat 级视觉分镜**并派单给下游四车道（真人 A-roll / MG 动态图 / AI_DRAMA 再现 / FILM_BROLL 影视素材）。**纯本地、同步、无云端任务**。上游依赖 `transcript.json`（oralcut 家族恒出的句级词表，源时基）。
 
 编排顺序（脑=`gtrk-splitter` skill / 手=本命令）：
 
@@ -147,7 +147,7 @@ gtrk split <拆分稿.json> --project <目录> --md --json  # ⑤ 校验落地
 - **dropped 处理**：beat 的 span 内 utterance 全被剪 → 跳过该 beat 并入报告；部分被剪 → 按存活句包络收缩、标 `shrunk`。均不使命令失败。
 - **transcript 缺失**（旧任务）→ 明确报错引导「用新版本重跑 oralcut（恒出 transcript）或 transcribe（规划中）」，不做降级猜测。
 - **只动 `struct_meta.split`**：写回不碰 materials/tracks，配合客户端「保存 → 发起 → 写回 → 重载」闭环（opencut 联动）。
-- **下游消费**：`dispatch.json` 的 `film_broll` 队列 → `gtrk matrix --project <dir>`（B-roll 双口检索 → `split/broll-plan.json` 候选清单;url 24h 过期,重跑即重签）；`rrv_mg` 槽位表 → real-roam-viz 产颗粒；`ai_drama` 队列 → ai-drama-prompter。
+- **下游消费**：`dispatch.json` 的 `film_broll` 队列 → `gtrk matrix --project <dir>`（B-roll 双口检索 → `split/broll-plan.json` 候选清单;url 24h 过期,重跑即重签）；`mg` 槽位表（去品牌化前 `rrv_mg`）→ `gtrk mg` 铺轨 / real-roam-viz 产颗粒；`ai_drama` 队列 → ai-drama-prompter。
 
 > **skill 分工**：拆 beat / 选 lane / 写 handoff 是脑（`gtrk-splitter` skill）的活；投影 / 校验 / 落地 / 写时码是手（本命令）的活。skill 铁律：只引用视图存在的 utterance id、不抄原文定位、不碰时码。
 

package/README.md

@@ -11,7 +11,7 @@
 - **一条命令出三方工程**：上传口播毛片 → 云端智能剪辑（剪废话 / 重复 / 长停顿）→ 拉回**客户端（gtrk）+ 剪映 + PR/FCP** 三方工程文件 → 自动打开产物目录。
 - **云端做重活、本地只装配**：识别、剪辑、对齐都在云端；本地只拿结果，**源视频不出本地**（路径写进工程、本地打开直接认素材）。
 - **为 agent 而生**：配套 skill `/gtrk-oralcut`，在 Claude Code 等工具里一句「帮我剪个口播」就能发起，CLI 是手、agent 是脑。
-- **专业可扩展**：单 binary + 子命令（对标飞书 `lark-cli`），后续长出 `render` / `struct` / `matrix` 等命令。
+- **通用工具箱**：单 binary + 平行子命令——每个 `gtrk <xyz>`（oralcut / split / mg / matrix / render…）都是一个**业务无关的通用驱动器/工具**，成片流程要哪个启哪个、用不到放着；后续可长更多驱动器。对标飞书 `lark-cli`。目前用它做人文社科视频，但设计上不绑任何栏目。
 
 ## 功能
 
@@ -21,10 +21,11 @@
 | ✂️ | `gtrk split [拆分稿]` | 视觉拆分派单器：成片 × transcript 投影 → beat 分镜校验落地（`struct_meta.split` + `dispatch.json`），驱动四车道派单；`--column <id>` 按栏目词表校验 |
 | ⚙️ | `gtrk init` | 引导式一次性配置（API Key + 剪映草稿目录），之后免管 |
 | 🩺 | `gtrk doctor` | 体检：配置 / 云端连通 / 剪映目录 / 运行时一键自检 |
-| 🤖 | `gtrk skills install` | 把 `/gtrk-oralcut`、`/gtrk-splitter`、`/gtrk-style-maker` skill 装进 Claude Code |
+| 🤖 | `gtrk skills install` | 把 6 个 CLI 自带 skill（`/gtrk-oralcut`·`/gtrk-splitter`·`/gtrk-matrix`·`/gtrk-mg`·`/gtrk-ai-drama`·`/gtrk-style-maker`）装进 Claude Code |
 | ⬆️ | `gtrk upgrade` | 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装 |
 | 🎞️ | `gtrk render` | 本地渲染 gtrk 工程（EDL）→ 成片 mp4（需 ffmpeg） |
 | 🔎 | `gtrk matrix` | B-roll 检索+**候选铺轨**：消费 FILM_BROLL 派单 → 产候选清单 + 下载 preview 代理铺 N 条候选轨（`--lay N` 默认 1，opencut 打开即可用轨道小眼睛对比；`--lay 0` 只出清单）；`matrix search "<词>"` 单条 ad-hoc |
+| 🎨 | `gtrk mg` | MG 动态图颗粒铺轨：消费 MG 派单 → 把 html-particle 颗粒（透明叠加 / 满屏底层，由你栏目的 MG 生产 skill 所产）铺进 `.gtrk` 的 beat_track；`mg lint <颗粒.html>` 六铁律静态校验、`mg status --project <dir>` 编排看板（缺 HTML / 已产未铺 / 已铺）；aux 叠层颗粒同段多铺（一 beat 派生主 + `-aux<n>`）。旧名 `gtrk rrv` 保留为弃用别名 |
 | 🚧 | `struct` | （规划中）已有 gtrk 转三方工程 |
 
 ---
@@ -58,6 +59,71 @@ gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选
 
 > **重复装不会重复填配置**：`gtrk install` / `gtrk init` 检测到已配好就默认保留、只刷新 skill；想改配置加 `--reconfigure`（Key / 剪映目录也都能回车沿用）。
 
+## 操作地图：从零到成片
+
+> **你只管对话，敲 CLI 的活交给 agent。** 下面是一条龙的走法——先做什么、后做什么、遇到情况怎么办。
+
+**一次性准备（装一次，之后免管）**
+
+1. **装 CLI**：`npm i -g @gitruck/cli@latest && gtrk install`（装 gtrk + skill + 填 API Key，一次配好）。
+2. **（可选）建栏目风格**：想要自己的视觉调性 / 词表，对 agent 说「**建我栏目的风格体系**」（`/gtrk-style-maker` 访谈式帮你落成你自己的 skill 家族 + 栏目配置）。**不建就用默认厨房**，端到端照常跑。
+
+**每片一条龙（有先后的 SOP，对 agent 说话、每步你可介入——不是一次性并行铺完）**
+
+各车道**按次序铺、每步留检查点**：先铺 B-roll 定底层 → 你调好 → 再把 MG 叠上去 → 最后上 AI 再现。你对话推进每一步，agent 替你跑对应命令。
+
+| 步 | 你对 agent 说 | agent 替你做 | 你可以介入 |
+|:--:|---|---|---|
+| ① | 「帮我把这条口播**剪一版**」 | `/gtrk-oralcut` → `gtrk oralcut` → 三方工程 + transcript | — |
+| ② | 「接着**拆分镜派单**」 | `/gtrk-splitter` → `gtrk split` → `dispatch.json` 四车道 | 核对派单结果 |
+| ③ | 「**先铺 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` 只出**主轨快照预览** | 客户端里精修定稿 |
+
+> 次序有理由：**MG 叠在 B-roll 之上**，要先把底层 B-roll 定下来、你满意了再铺 MG；AI 再现最后上。用不到的车道跳过（`dispatch` 里该队列为空就不铺）。
+>
+> ③④⑤⑥ 都要**回到客户端**挑选 / 精修 / 回铺 / 出片——CLI 把料铺进 `.gtrk`，客户端把 `.gtrk` 出成片。详见下文「**CLI × 客户端**」小节。
+
+**遇到情况怎么办**
+
+| 情况 | 怎么做（跟 agent 说，或 agent 自动） |
+|---|---|
+| 只想要剪辑工程、暂不做视觉 | 到「剪一版」就停：「先只要剪辑工程」 |
+| 报告丢了 / 换台机器再拉产物 | 「用 taskId 取回上次的」→ `gtrk oralcut-result <taskId>`（跳过重跑云端） |
+| 想在几个 B-roll 候选里挑 | 「B-roll 多铺几条候选」→ `gtrk matrix --lay N`，opencut 里用轨道小眼睛切换对比 |
+| B-roll 填充太差 / 有空槽 | 调 `--score-floor` / `--top-k` 重跑，或「单独搜个词」→ `matrix search "<词>"` 补 |
+| 画面 / 颗粒要逐帧精修 | opencut 打开工程手调（agent 铺好的是**可编辑工程**，不是死片） |
+| 连不上 / 配置出问题 | 「体检一下」→ `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**（配置原样保留）：
@@ -77,17 +143,32 @@ irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex
 
 ## 给 AI Agent 用
 
-`gtrk install` 已经把 `/gtrk-oralcut` skill 装进 `~/.claude/skills`（单独装用 `gtrk skills install`）。
+`gtrk install` 已经把 6 个 CLI 自带 skill（`/gtrk-oralcut`·`/gtrk-splitter`·`/gtrk-matrix`·`/gtrk-mg`·`/gtrk-ai-drama`·`/gtrk-style-maker`）装进 `~/.claude/skills`（单独装用 `gtrk skills install`）。
 
 然后在 Claude Code 里直接说「**帮我把这条口播剪一版**」或打 `/gtrk-oralcut`，agent 会问清毛片 / 文稿 / 节奏，调 `gtrk oralcut --json` 跑通闭环、验证产物、把三端打开方式回给你。完整可移植 playbook 见 [`AGENT.md`](./AGENT.md)。
 
-### Skills
+**一条龙都交给 agent**：不止剪口播——接着说「拆个分镜」「铺 B-roll」「铺 MG 颗粒」「渲成片」，agent 会配合各车道生产 skill 调 `gtrk split` / `gtrk matrix` / `gtrk mg` / `gtrk render` 跑完整条 **成片管线**。**你只管对话、敲 CLI 的活交给 agent**——下面的「命令参考」是给 agent 查参数用的，不用你自己去终端敲。
 
-| Skill | 触发 | 做什么 |
-|---|---|---|
-| `/gtrk-oralcut` | 斜杠，或「剪口播 / 智能剪辑 / 去掉废话停顿 / 出剪映草稿」 | 驱动 `oralcut` 闭环：云端剪辑 → 拉回三方工程 → 验证 → 回报三端打开方式 |
-| `/gtrk-splitter` | 「文稿视觉化拆分 / 派分镜 / beat 时间线」 | 产视觉拆分稿，交给 `gtrk split` 校验落地（时码永远归 CLI） |
-| `/gtrk-style-maker` | 「建我栏目的风格体系 / 把审美沉淀成 skill / 栏目配置怎么填」 | **能生产 skill 的 meta skill**：启发式访谈帮你把自己的视觉语法落成你自己的 skill 家族 + 栏目配置（见下节） |
+### agent 能驱动的能力（skill 驱动命令）
+
+**每个功能 = 一个 skill（脑，你触发、懂 SOP 位置与用户交互）驱动一个 gtrk 命令（手，确定性机械活）。** 成片是**有先后的 SOP、每步用户可介入**，不是一次性并行铺完——`/gtrk-X` skill 负责在对的时机、带着你的确认，去跑 `gtrk X`：
+
+| SOP | 驱动 skill（你对 agent 说） | 底层命令（agent 跑） | 做什么 |
+|:--:|---|---|---|
+| ① | `/gtrk-oralcut` | `gtrk oralcut` | 智能剪口播 → 客户端/剪映/PR 三方工程 + transcript |
+| ② | `/gtrk-splitter` | `gtrk split` | 拆分派单 → `dispatch.json`（A_ROLL/MG/AI_DRAMA/FILM_BROLL 四车道） |
+| ③ | `/gtrk-matrix` | `gtrk matrix` | **先铺 B-roll** 候选轨 → **用户调整/挑选**（opencut 小眼睛切换） |
+| ④ | `/gtrk-mg` | `gtrk mg` | **再铺 MG 颗粒**（叠在调好的 B-roll 之上） |
+| ⑤ | `/gtrk-ai-drama` | （无命令，纯创作） | **最后上 AI 再现**：产四段描述稿（故事背景/角色/分镜/原文，中英分块）→ 任意外部平台出片、手动回铺（产物即描述文本、无机械尾巴，同 `/gtrk-style-maker` 只 skill 无命令） |
+| — | `/gtrk-style-maker` | （无命令，建栏目） | 一次性访谈式建你栏目的风格体系（skill 家族 + 栏目配置，见下节） |
+| — | （收口） | `gtrk render` | 本地渲染 gtrk 工程 → 成片 mp4 |
+
+> **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ④ 步（B-roll 定了才铺 MG）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
+> 上面 6 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装）——`/gtrk-matrix`·`/gtrk-mg` 各驱动一个 gtrk 命令，`/gtrk-ai-drama`·`/gtrk-style-maker` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
+
+上面三个是 **CLI 自带的框架 skill**（`gtrk skills install` 装，业务无关）。
+
+**各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 再现什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
 
 ---
 
@@ -175,6 +256,60 @@ gtrk init --api-key <KEY> --jianying-draft-dir auto -y
 
 > 取结果需用**提交该任务的同一账号** API Key（异账号 / 已删任务报 `TASK_NOT_FOUND`）。报告存于任务记录、长期可取；底层产物文件约 **60 天**后被清理，届时仍能取回报告、但产物下载会 404（命令会提示、并照常落盘报告）。
 
+### `gtrk split [拆分稿]` — 视觉拆分派单器
+
+成片 × transcript 投影 → beat 分镜。**无 positional = 导出投影视图**（把当前 `.gtrk` 时间线 × transcript 投影成 beat 视图，供拆分/校对，不写回）；**带拆分稿 = 校验落地**（校验拆分稿机器契约 → 投影出 beat 时码 → 原子写回 `struct_meta.split` + 产 `split/dispatch.json` 派单清单，驱动 A_ROLL / MG / AI_DRAMA / FILM_BROLL 四车道）。时码永远归 CLI（拆分稿只描述「哪段做什么」、不写时码）。
+
+| 参数 | 作用 | 缺省 |
+|---|---|---|
+| `--project <dir>` | oralcut 产物目录（自动定位 `gtrk/project.gtrk` 与 `transcript/transcript.json`） | — |
+| `--gtrk <path>` / `--transcript <path>` | 显式指定工程 / transcript（非标准布局兜底） | 由 `--project` 推 |
+| `--column <id>` | 栏目配置 id（按你栏目词表校验 lane / category / produces） | config `defaultColumn` → 内置默认栏目 |
+| `--md` | 落地时额外渲染人读稿 `split/visual-split.md`（由 JSON 单向渲染） | 关 |
+| `--words` | 视图模式附字级明细 | 只出句级 |
+| `--json` | 机读：stdout 只输出结果 JSON | 关 |
+
+> 落地产物 `dispatch.json` 三队列 → 下游消费：`mg`（MG 颗粒）→ `gtrk mg` 命令、`film_broll` → `gtrk matrix` 命令、`ai_drama` → `/gtrk-ai-drama` skill（产四段描述稿·中英分块，纯创作、无命令）。配套 skill `/gtrk-splitter` 产拆分稿。
+
+### `gtrk matrix` — B-roll 检索 + 候选铺轨
+
+**无 positional = 派单消费**：读 `split/dispatch.json` 的 `film_broll` 队列 → 双口检索 → 产候选清单 `split/broll-plan.json` + 下载 preview 代理、在工程里平铺 N 条候选轨（opencut 打开即可用轨道小眼睛对比挑选）。**`matrix search "<query>"` = 单条 ad-hoc 检索**（不依赖派单）。
+
+| 参数 | 作用 | 缺省 |
+|---|---|---|
+| `--project <dir>` | oralcut 产物目录（定位 `split/dispatch.json` 与产物落点） | — |
+| `--dispatch <path>` | 显式指定 `dispatch.json` | 由 `--project` 推 |
+| `--column <id>` | 栏目配置 id（按你栏目 B-roll 检索偏好：标签 / material_class / facets） | config `defaultColumn` → 内置默认栏目 |
+| `--lay <n>` | 候选铺轨数：平铺 N 条 B-roll 候选轨（`0` = 只出 plan 不铺轨） | `1` |
+| `--top-k <n>` | 每 query 候选数上限（覆盖派单 shots；服务端上限 50） | 派单值 |
+| `--material-class <c>` | 素材类型 `real_shot` \| `concept`（仅矩阵成员口；覆盖栏目策略） | 栏目策略 |
+| `--score-floor <f>` | 填充置信度地板：segment score 低于此值不采纳、留空露主轨 | `0.2` |
+| `--out <file>` | ad-hoc 模式结果落文件 | stdout |
+| `--json` | 机读：stdout 只输出结果 JSON | 关 |
+
+> preview 代理 url 约 24h 过期，重跑即重签。
+
+### `gtrk mg` — MG 动态图颗粒（铺轨 / lint / status）
+
+消费 `gtrk split` 落地的 `dispatch.mg` 派单，把**你栏目的 MG 生产 skill** 产的 html-particle 颗粒铺进 `.gtrk` 工程的 `beat_track`。三种模式按首个 positional 分派：**无参 = 铺轨**、`mg lint <file>` = 单文件校验、`mg status` = 编排看板。旧名 `gtrk rrv` 保留为弃用别名（会打提示，建议改用 `gtrk mg`）。
+
+| 参数 | 作用 | 缺省 |
+|---|---|---|
+| `--project <dir>` | oralcut / split 产物目录（定位 `split/dispatch.json` 与工程 `.gtrk`） | — |
+| `--dispatch <path>` | 显式指定 `dispatch.json`（非标准布局兜底） | 由 `--project` 推 |
+| `--only <beat>` | 只跑单 beat（主 + 其 `-aux<n>` 叠层颗粒一并选） | 全部 |
+| `--lint-only` | 只 lint 校验，不铺轨不写回 | 关 |
+| `--json` | 机读：人读日志转 stderr，stdout 只输出结果 JSON | 关 |
+
+- **铺轨**（`gtrk mg --project <dir>`）：读 `dispatch.mg` → 逐 beat 从 `<project>/mg/<composition_id>.html` 取源颗粒 → lint → 铺进 `beat_track`，把 `struct_meta.mg` 原子写回 `.gtrk`（幂等登记自产轨 `lay_tracks`，重铺先剥旧自产物再 append、用户手加轨零连带）。「透明叠加 / 满屏底层」由颗粒 HTML 根 `background` 反推的 `opaque` 决定。缺 HTML / lint 失败的 beat 计入 `skipped`、不拦其余。
+- **lint**（`gtrk mg lint <颗粒.html> [--dispatch <path>]`）：纯本地静态校验颗粒 HTML 的六铁律机器可判定子集（`<template>` 包裹、`data-composition-id` + 1920×1080、`gsap.timeline({ paused: true })`、`window.__timelines` 注册、无 `Math.random` / `Date.now`、自包含无相对外链、根 `background` 与 `opaque` 自洽…）；给 `--dispatch` 时校验 `composition_id` 命中派单。任一致命项非 0 退出并逐条报因。
+- **status**（`gtrk mg status --project <dir>`）：汇总 MG 流水线——`dispatch.mg` beat 总数 / 已产源 HTML 数 / 已铺进 `.gtrk` 数，并逐 beat 标注（缺 HTML / 已产未铺 / 已铺）。
+
+`--json` 输出：`{ ok, mode:"lay"|"lint"|"status", … }`（各模式带对应字段，如铺轨的 `laid` / `skipped`、status 的逐 beat 状态）。
+
+> **aux 叠层颗粒**：`gtrk split` 若在某 beat 的 `aux_layers` 派了 `overlay` 颗粒，会派生 `<beat>-aux<n>` 合成条目进 `dispatch.mg`——`gtrk mg` 一并铺，实现「同段既有底轨主视觉、又叠透明概念图解」。
+> **双读兼容**：`dispatch.mg`（读旧 `rrv_mg`）、源目录 `mg/`（读旧 `rrv/`）、素材前缀 `mg-`（读旧 `rrv-`）——去品牌化前的既有工程零迁移。
+
 ### 其它
 
 - `gtrk install [--api-key … -y --skills-dir …]` — 一条命令装全（skill + 配置 + 体检），对标飞书 `lark-cli install`。
@@ -213,7 +348,7 @@ gtrk-cli/
 ├── src/index.ts              # commander 入口
 ├── src/commands/             # 子命令：install / init / oralcut / split / doctor / upgrade / skills
 ├── src/lib/                  # cloud / column-config / splitdoc / projection / user-config / jianying / …
-├── skills/                   # 打包的 agent skills：gtrk-oralcut / gtrk-splitter / gtrk-style-maker
+├── skills/                   # 打包的框架 skills：gtrk-oralcut / splitter / matrix / mg / ai-drama / style-maker
 ├── contracts/                # 框架契约库正本（gsap-emit v1 + handoff→契约映射表）
 ├── assets/                   # 剪映草稿目录指引图
 └── AGENT.md                  # 可移植 agent playbook（skill 底座）

package/contracts/README.md

@@ -11,4 +11,4 @@
 
 | 契约 | 版本 | 适用 handoff | 文档 |
 |---|---|---|---|
-| gsap-emit（HTML 动画颗粒逐帧 seek 合规） | v1 | RRV_MG | [gsap-emit-v1.md](gsap-emit-v1.md) |
+| gsap-emit（HTML 动画颗粒逐帧 seek 合规） | v1 | MG（去品牌化前 RRV_MG，消费方查表前归一） | [gsap-emit-v1.md](gsap-emit-v1.md) |

package/contracts/handoff-contracts.json

@@ -1,9 +1,9 @@
 {
   "version": 1,
-  "comment": "handoff 类型 → 契约映射表（handoff-contract-library spec）。消费方（含 gtrk-style-maker）查此表，不得硬编码映射。null = 暂无契约（产线可用，无合规绑定要求）。注册集当前 = 现行四车道（P2 注册表化前的过渡事实）。",
+  "comment": "handoff 类型 → 契约映射表（handoff-contract-library spec）。消费方（含 gtrk-style-maker）查此表，不得硬编码映射；消费方查表前先将遗留品牌值（如 RRV_MG）归一为中性名（MG）。null = 暂无契约（产线可用，无合规绑定要求）。注册集当前 = 现行四车道（P2 注册表化前的过渡事实）。",
   "mappings": {
     "A_ROLL": null,
-    "RRV_MG": { "contract": "gsap-emit", "version": "v1", "doc": "gsap-emit-v1.md" },
+    "MG": { "contract": "gsap-emit", "version": "v1", "doc": "gsap-emit-v1.md" },
     "AI_DRAMA": null,
     "FILM_BROLL": null
   }