gitruck/cli/gtrk-mg

MG 动态图铺轨（gtrk-mg）

把 gtrk split 派好的 MG 槽位（dispatch.mg），先由栏目的 MG 生产 skill 产成 html-particle 动态图颗粒，再交给 gtrk mg 命令 lint + 铺进 .gtrk 工程的 beat_track——叠在已经定稿的底轨之上（B-roll 三源全落齐、构图已核）。CLI 是手（lint / 铺轨 / 写回），你是脑（认 SOP 位置、驱动栏目生产 skill、管用户检查点、判 lint 该不该硬铺）。栏目生产 skill 只产纯净颗粒、不知 gtrk 命令，由你驱动。

本 skill 已含你需要的全部信息（SOP 位置、业务分离、逐槽位工作流、命令参数、lint 铁律、排错、交棒）。命令参数细节以 gtrk mg --help 为准；颗粒的视觉/内容规范不在这里——那是栏目资产，由栏目 MG 生产 skill 全权负责。

你在成片 SOP 的哪一步（先认位置，别抢跑）

成片是有序 SOP + 用户检查点，不是并行一次铺完。全序：

① /gtrk-oralcut（剪口播）→ ② /gtrk-splitter（拆分派单出 dispatch.json）→ ③ B-roll 底轨全铺齐（/gtrk-matrix 铺影视/本地素材 + /gtrk-ai-drama 产稿→外部出片→用户手动回铺，两条腿同一阶段）→ ④ 全局抽帧检查画面构图（用户确认） → ⑤ 本 skill：MG（含 ov）最后叠上 → gtrk subtitle lay 上字幕（快速成片模式必做）→ gtrk render 收口（会对未命中缓存的颗粒云渲、有计费，见末节）

你是第 ⑤ 步、也是最后一层。 MG 颗粒是唯一的叠加层——底下那整层底轨必须先定死（三源全落齐），否则你的排版避让是对着一个不完整的画面做的。

⚠️ AI 情景片段属于底轨 B-roll 画面家族，不是叠加层。先完成 AI 片段回铺，再依据最终底轨构图产出 MG，避免遮挡主体。

所以动手前先过前置硬门。

前置硬门（不满足就别铺，先回上一步）

1. 影视/本地素材 B-roll 已铺且用户已确认：若 dispatch.film_broll 非空，必须 ③ 已跑过 gtrk matrix 且用户已在 opencut 里挑选/调整确认。没确认 → 别铺 MG，先回 ③。（为空 = 本片没这条腿，看下一门。）
2. ★ AI 情景片段已回铺，或用户明示先跳过：若 dispatch.ai_drama 非空，必须已回铺完（用户已把外部平台出的片子拖进工程）或用户明示「先跳过 AI、先把 MG 铺上」。

• 外部平台抽卡可能数天，严格串行会把你无限期卡住，故留这个口子。
• 走跳过时你 MUST 付这个对价：把与 AI beat 相邻或重叠区间的 MG 颗粒逐一标记为「AI 回铺后待复查构图」，并在交棒 render 时把该清单复述给用户。MUST NOT 静默跳过 —— 用户得知道哪几颗将来可能要返工。
• （为空 = 本片没 AI 车道，此门自动通过。）

1. ★ ④ 全局抽帧检查已过、用户已确认构图：对三源合并后的最终底轨抽帧看主体位置 / 安全区 / 画面朝向 / 明暗，用户确认无误。这与 ③ 那次「挑选 B-roll」的确认是两次不同的确认，别拿前一次顶替。没做 → 先做 ④ 再回来。
2. 有 split 产物：需要一个跑过 gtrk split 的产物目录（含 split/dispatch.json 与工程 .gtrk）。没有 → 先回 ② /gtrk-splitter。
3. `dispatch.mg` 非空：为空 = 本片没有 MG 车道 → 别硬造，直接 gtrk render 收口（见末节；无颗粒 = 零计费）。
4. CLI 在：gtrk 找不到 → 让用户装 npm i -g @gitruck/cli@latest（需先有 Node.js）。

业务分离：谁产颗粒（栏目），谁铺轨（本 skill）

本框架 skill 不硬编任何栏目的视觉风格/生产内容。 MG 颗粒长什么样、用什么视觉语法，全由栏目的 MG 生产 skill 决定；本 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 → 别硬铺，给用户四选一（都不替他选）：

1. 建栏目：/gtrk-style-maker 沉淀自己的 MG 生产 skill（一次性，长期资产）；
2. 换栏目：--column <id> 指向已配置的栏目；
3. 用中性块：Hyperframes registry 的中性颗粒骨架（gtrk mg fetch，见下节「中性块工作流」）——没建栏目也能当场出 MG，但骨架不是成品，内容与审美 MUST 改写。
4. 用文字模板：同合云自家的文字特效模板库（gtrk mg fetch --source text，见下节「文字模板工作流」）。改字走 gtrk mg compile、改效果走 gtrk mg edit --say。

⚠️ 它的适用面由派单的 `visual_job` 决定，不由「省不省事」决定（见下「按 visual_job 路由」）。 另可查推荐目录（公约 §三‴）：gtrk skills recommend --scene mg-explainer 列第三方 MG 生产 skill，装完 gtrk skills add <owner/repo> --produces MG 登记即被本节解析到——本 skill 正文不点名任何仓、不点名任何块。 推荐目录另有一方排版技法族（gtrk skills recommend --scene technique）：技法不是生产者、不登记为 MG 车道（routing:none），某槽位的内容形态命中某技法（如引用文献页 / 截图局部强调）时由你按槽位取用——内容与节奏按口播定、栏目色未定时用技法自带的中性底；本 skill 正文同样不点名仓。

• 有匹配时中性块与文字模板缺省都不用：只当栏目 skill 明显不擅长某类（如数据图表 / 界面拟物 / 纯文字入场）时可提议「这一槽用中性块」或「这一槽用文字模板」，用户点头才用。技法族同理——槽位内容形态命中某技法时可提议「这一槽用技法」（gtrk skills recommend --scene technique），栏目色板与字体照栏目注入，用户点头才用。

★ 按 visual_job 路由（不是按省事路由）

每个 MG 槽位的派单里都有一个必填的 visual_job（gtrk split 判的，四档）。 它决定这一槽的候选集里有什么：

⚠️ `relation` / `data` 两档，`gtrk mg lint` 会硬拒文字模板颗粒（判据取产物内嵌的 v:"text-v0" IR，改名骗不过去）。这不是建议，是闸。

⚠️ 被禁的是「从库里捞一个套上」，不是「用文字」。 用排版画关系的手写颗粒 ——并置两列、中间破折号连起来、右列更重——正是这一档要的东西，它没有内嵌 IR，闸不拦。 区别不在媒介，在有没有为这个意思专门做设计。

relation 档的手做样例（照着改，别去库里找）

一块半透明面板，小标题 + 两行并置 + 落款：

┌─────────────────────────────┐
│        边界的姿态            │  ← 小标题，字重轻，字距开
│                             │
│    温柔  —  坚定             │  ← 两列同基线，中间破折号把它们连起来
│    和善  —  有立场           │     右列字重更重（它是「立场」那一侧）
│                             │
│  语气可以柔软，立场必须清楚    │  ← 落款，最小号
└─────────────────────────────┘

它是纯文字画的，但它表达的是一个关系（语气 vs 立场的对照）。 关系靠三样东西成立：同基线的两列、把两列连起来的破折号、右列更重的字重。 去掉任意一样，它就退回成四行不相干的字。

⚠️ 模板库给不出这个：103 件全是单 / 双槽位的标题与字幕， 结构化排版不在它的表达力射程内。这不是库没做好，是这一档本来就该手做。

⚠️ 这个样例留在图纸里是有目的的：没有样例，「自己做一个」那块肌肉会随图纸一起萎缩。 （正本：gitruck-infra/docs/同合云顶层设计文档/模板化对自由创意的侵蚀.md §三 第二种损失。）

⚠️ 排产顺序：先原创，后套用

gtrk mg fetch --source text（派单模式）在本片仍有 relation / data 槽位没产出源 HTML 时会拒绝执行，并列出是哪几个 beat。

为什么是顺序：连着看过十几颗现成品之后，「MG 该长什么样」的默认印象已经被那批东西定住了； 这时再自由发挥，发挥出来的多半还是它们的形状。顺序本身就是一道隔离。

⚠️ 它牺牲了「先铺一批模板看整体效果」这种工作法。要保留只能走 --allow-template-first --why "<一句话>"（一次性例外，不是开关）。 理由会写进 <工程>/split/mg-exceptions.json——终端会消失，工程文件不会， 日后翻这条片子的人查得出当初为什么按了例外。

文字模板工作流（同合云自家模板 → 改字/改效果 → lint → 铺）

与中性块是两条路，别混。中性块来自第三方、是骨架，要改字体换色板才合规（机械改写八条）；

文字模板是我方 clean-room 重写的成品，MUST NOT 做机械改写、MUST NOT 直接改 HTML。

为什么不能直接改 HTML：每颗文字模板都内嵌了产生它的 IR 与两个哈希，颗粒因此自带 「我是由这份 IR 编出来的」的证明（三态：ir 可云调 / detached 已脱离 / html 普通颗粒）。 手改一个字节，它就从 ir 掉到 detached——gtrk mg edit 和客户端属性面板都会拒绝它， 云端再也调不动。gtrk mg lint 会报非致命的 x-ir-detached 提醒你这件事。

逐槽位：

1. 候选：gtrk mg fetch --source text "<检索词>" --top 3 --json（中文词可用：开场 / 字卡 / 标题 / 字幕 / 强调 / 打字机 / 字条 / 引用 / 气泡 / 故障 / 竖排 / 闪光 / 清单 / 计数 …）。候选态离线可用；目录走远端择新、随包兜底，命令会明示这次用的是哪一版、从哪来的。
2. 取块：gtrk mg fetch --source text --pick <模板 id> --slot <beatId> --project <目录> --json，或独立模式 --as <composition_id> [--duration <坑位秒>] [--out <目录>]。落盘即可铺，不需要改写。

• 落点与时长由命令钉定，你不用管（fix-mg-fetch-text-slot-identity）：派单模式的 composition_id 取自 dispatch.mg 那条（<工程slug>-<beatId>，不是 --slot 收的 beat id），产物落 <产物目录>/mg/<composition_id>.html；颗粒内嵌 IR 的 id 与 canvas.duration 被一并钉到「期望 id」与「坑位包络 + 0.3s 余量」（铁律⑦），贴模板末尾的层跟着钉，然后走 mg compile 同一条本地编译链重编。产物因此仍是 ir 态（云端还能改），且 mg lint --dispatch 的 1-cid-expect 天然对得上。
• --slot 与 --duration 互斥：派单模式的包络由 track_st / track_ed 定，显式给时长会与它打架；独立模式才用 --duration。
• 出参里的 pinned 写明改了什么（id 的 from→to、duration 的 from→to、被钉的层）；两者都没改、且目标画幅就是模板的 1920×1080 时 changed:false 且原字节落盘（不重编）。
• 画幅也由命令定（fix-text-template-canvas-not-compiled）：派单模式按工程 .gtrk 的 video_size 编，出参 canvas / canvas_from 写明用了哪个画幅、从哪来；画幅不是 IR 改动，pinned 不记它。
• 满屏槽位拿不出实心底 ⇒ 致命 `x-category-opaque`，拒落盘（gate-fullscreen-slot-needs-solid-bed）。

判据只看产物——「这颗有没有满屏实心底」，不看它是不是模板颗粒。 ⚠️ 派单模式下通常不用你操心：dispatch.mg[].bg 写了底色的话，取块时会自动钉进 canvas.bg，声明当场兑现。撞上这条红一般意味着派单只声明了 `fullscreen` 却没给 `bg` —— 两条出路：① 这颗本来就该是叠加 ⇒ 改派单的 category 为 overlay； ② 确实要盖住画面 ⇒ 给派单补 bg，或手动在 IR 里写 canvas.bg（编译器会产成根下第一个全幅子层）。 MUST NOT 靠「加一层 shape 当底」绕过：那种写法的覆盖面取决于祖先定位与 transform， 静态判不出来，opaque 登记不上（画出来了但成片按透明叠加处理）。

• 反方向（槽位派 overlay、颗粒却是实心）仍是非致命告警：那只是多盖了底轨，看得见、改得动，

不是「以为有其实没有」的静默落空。两个方向后果不对称，判据也就不对称。

1. 改字（L0，0 积分）：把内嵌的 IR 存成 <id>.ir.json，改 slots 里的文字（也可改 colors / font / stroke / shadow / canvas.duration），然后 gtrk mg compile <id>.ir.json --out <目录>。竖屏 / 方形工程加 --canvas <工程画幅>（如 --canvas 1080x1920）——.ir.json 里不记画幅，不给就按 1920×1080 编；给颗粒 HTML 重置时缺省沿用那颗自己的画幅。
2. 改效果（2 积分/候选）：gtrk mg edit <particle.html> --say "打字机快一倍，副标改成青色" [--n 1|3]。--n 只收 1 或 3，它就是计费单位数。返回的候选带 scope：L1 = 在模板可调范围内，L2 = 越界了、等于新生成（不是失败）。服务端说做不到时会给一句 refusal，如实转述给用户——他要的是「为什么不能」，不是一个没有解释的错误。
3. lint → 铺：同中性块，gtrk mg lint 过致命项 → gtrk mg --project <目录>。
4. 竖屏 / 方形工程：文字模板按工程画幅现编（IR 住在 1920 参考系、画幅是编译入参），不用另做。

• 派单模式缺省就取工程 .gtrk 的 video_size，不用给 --canvas；给了却与工程不符命令会拒（跨比例挂载是非等比缩放，铺进去就是拉伸）。
• 找不到 .gtrk（只给了 --dispatch、或工程文件不在 gtrk/project.gtrk / project.gtrk）时会按 1920×1080 编并提示——竖屏工程看到这句提示就补 --canvas 1080x1920 重取。
• 独立模式没有工程可取：竖屏要显式 --canvas 1080x1920。
• 取完核一眼出参 canvas 等于工程画幅再铺；1.3.7 及更早的 CLI 无论给什么都出 1920×1080，见到竖屏工程里取来横屏颗粒先 gtrk upgrade。

中性块工作流（registry 骨架 → 改内容审美 → lint → 铺）

快照随包（钉 commit，候选态离线可用）；取块走三源（我方镜像优先，大陆可达）并校 sha256；改写八条是机械活（template 包裹 / 改 id / 去 data-start 贴坑位 / 实心底下沉 / GSAP 源 / 字体 / 时长贴坑位 / 信箱缩放），内容与审美不在机械活里。

逐槽位：

1. 候选：gtrk mg fetch "<按 handoff.theme 与 beat 语义组的检索词>" --top 3 --json（中文词可用：数据 / 图表 / 标题 / 字幕 / 转场 / 通知 / 代码 / 地图 / 手写 / 卡片 / 片头 …）。把 2–3 件候选连海报链接给用户选（候选选择是检查点，形状同 matrix 的 B-roll 候选）；快速成片模式取首选、铺完在抽帧检查里一并给用户看。[review] 件可选但 MUST 真渲验收（多为 canvas / 铁律 8 高危形态）；[excluded] 不在可取范围，命令会拒。
2. 取块改写：gtrk mg fetch --pick <块名> --slot <beatId> --project <目录> --json——从派单取 composition_id / 坑位包络 / category，产物直接落 <产物目录>/mg/<composition_id>.html。返回里的 editable（文案 / 数值数组 / 色值）就是你下一步要改的地方。
3. 改内容与审美（你的活，MUST 做）：按 beat 语义改文案与数据；色板与字体——有栏目 skill 按栏目的，没有按公约 §三「内容驱动的临场泛化」全片自洽一套；MUST NOT 把块的示例文案 / 示例数据 / 默认色板原样铺进成片。字体缺省已换成运行时镜像可证的 CJK 字体，要换用 --font。
4. lint → 铺：gtrk mg lint 过致命项 → gtrk mg --project <目录>（与栏目产颗粒同门槛）。
5. 竖屏 / 方形工程：registry 中性块只有 1920×1080 一种几何（块是手写 HTML、尺寸写死在块里，--canvas 给别的画幅会被拒），不适用。派单模式下工程 video_size 比例不是 16:9（容差 7%：4K 横屏与 DCI 17:9 照取）命令会在下载前拒、不落盘；改走 --source text（文字模板按工程画幅编，见上节）或栏目 skill 按工程画幅产颗粒，MUST NOT 拉伸。

独立模式（脱离派单补一颗）：gtrk mg fetch --pick <块名> --as <composition_id> --duration <坑位秒> [--category overlay|fullscreen] [--out <目录>]，随后同 gtrk mg render 的独立颗粒路。

生产 skill 是栏目的纯净资产：它只懂本栏目的视觉语法、只产 html-particle 颗粒，不知道 gtrk 命令、不知道产物落哪。由本 skill 驱动它、并由本 skill 负责让它以 `gtrk mg` 要读的路径为写入路径：颗粒 SHALL 直接写到 <产物目录>/mg/<composition_id>.html，MUST NOT 先写 agent 自有目录再拷入（中转本身即违规，见上「产物落点纪律」第 5 条）。举例（仅示意解析机制，非硬编）：real-roam-guide 栏目配置里 style.skills 有一条 {produces:"MG", ref:"…/real-roam-viz"} → 驱动它产颗粒；换个栏目、换个 ref，产颗粒的就是另一个生产 skill。本 skill 正文里不绑死任何栏目的生产 skill。

逐槽位工作流（产 → lint → 铺，循环到铺满）

产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）：

交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。

一切产物（颗粒 HTML / 成片 / 预览 / 素材 / 工程文件）只落工程目录（颗粒恒存 <产物目录>/mg/）或用户显式指定的输出路径；

MUST NOT 把成片、预览或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时用原路径引用，不做副本；

临时文件（抽帧图等）一律放系统 temp 且用完即删。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。

1. 看板起手：先看 dispatch.mg 有哪些槽位、铺到哪了

gtrk mg status --project "<split产物目录>" --json

• 汇总 MG 流水线：dispatch.mg beat 槽位总数 / 已产源 HTML 数 / 已铺进 .gtrk 数，并逐 beat 标注（缺 HTML / 已产未铺 / 已铺）。
• 每个槽位有 composition_id（主颗粒 = <工程slug>-<beatId>；overlay 叠层派生颗粒 = <工程slug>-<beatId>-aux<n>）与 handoff（theme / duration_hint（秒）/ category 等）。这些是你交给栏目生产 skill 的产片订单。

2. 逐槽位产颗粒（驱动栏目 MG 生产 skill）