@gitruck/cli 0.2.6 → 0.2.8

package/dist/index.js

@@ -4197,7 +4197,7 @@ var {
 
 // src/index.ts
 import { readFileSync as readFileSync5 } from "node:fs";
-import { join as join20 } from "node:path";
+import { join as join21 } from "node:path";
 
 // src/lib/paths.ts
 import { dirname, join } from "node:path";
@@ -4274,7 +4274,14 @@ var log = {
 };
 
 // src/commands/skills.ts
-var SKILL_NAMES = ["gtrk-oralcut", "gtrk-splitter", "gtrk-style-maker"];
+var SKILL_NAMES = [
+  "gtrk-oralcut",
+  "gtrk-splitter",
+  "gtrk-matrix",
+  "gtrk-mg",
+  "gtrk-ai-drama",
+  "gtrk-style-maker"
+];
 function installSkill(opts = {}) {
   const destRoot = opts.dir ?? join2(homedir2(), ".claude", "skills");
   let allOk = true;
@@ -4300,7 +4307,7 @@ function installSkill(opts = {}) {
 }
 function registerSkills(program2) {
   const skills = program2.command("skills").description("管理 agent skill（安装到 Claude Code）");
-  skills.command("install").description("把 /gtrk-oralcut 与 /gtrk-splitter 安装到 ~/.claude/skills（对标飞书 skills add）").option("--dir <dir>", "自定义 skills 目录（缺省 ~/.claude/skills）").action((opts) => {
+  skills.command("install").description("把 gtrk 全家框架 skill 安装到 ~/.claude/skills（对标飞书 skills add）").option("--dir <dir>", "自定义 skills 目录（缺省 ~/.claude/skills）").action((opts) => {
     installSkill({ dir: opts.dir });
   });
 }
@@ -4475,7 +4482,7 @@ import { existsSync as existsSync5, readFileSync as readFileSync2 } from "node:f
 
 // src/lib/splitdoc.ts
 var BASE_TRACKS = ["真人出镜", "口播继续", "旁白主导"];
-var LANES = ["A_ROLL", "RRV_MG", "AI_DRAMA", "FILM_BROLL"];
+var LANES = ["A_ROLL", "MG", "AI_DRAMA", "FILM_BROLL"];
 var NARRATIVES = [
   "mirror-hook",
   "demolition",
@@ -4503,8 +4510,17 @@ var AUX_TYPES = [
   "archive-caption",
   "pause-card",
   "data-annotation",
-  "timeline-tag"
+  "timeline-tag",
+  "overlay"
 ];
+var LEGACY_LANE_ALIASES = { RRV_MG: "MG" };
+function normalizeLane(v) {
+  if (typeof v !== "string")
+    return;
+  if (LANES.includes(v))
+    return v;
+  return LEGACY_LANE_ALIASES[v];
+}
 function isNonEmptyStr(v) {
   return typeof v === "string" && v.trim().length > 0;
 }
@@ -4573,7 +4589,7 @@ function validateSplitDoc(doc, ctx) {
       if (!enumOk(b.container_stage, vocab.container_stage))
         errors.push(`${tag}：container_stage 非法（不在栏目词表内）`);
     }
-    if (!enumOk(b.lane, LANES))
+    if (!normalizeLane(b.lane))
       errors.push(`${tag}：lane 非法（四选一：${LANES.join(" | ")}）`);
     if (!enumOk(b.irreplaceability, IRREPLACEABILITY))
       errors.push(`${tag}：irreplaceability 非法（四枚举之一）`);
@@ -4607,7 +4623,7 @@ function validateSplitDoc(doc, ctx) {
       if (!Array.isArray(b.aux_layers))
         errors.push(`${tag}：aux_layers 必须是数组`);
       else
-        b.aux_layers.forEach((a, ai) => validateAux(`${tag}.aux[${ai}]`, a, idIndex, errors));
+        b.aux_layers.forEach((a, ai) => validateAux(`${tag}.aux[${ai}]`, a, idIndex, errors, warnings));
     }
   });
   const sorted = [...ranges].sort((a, b) => a.from - b.from || a.to - b.to);
@@ -4628,9 +4644,12 @@ function validateHandoff(tag, b, errors, warnings) {
       warnings.push(`${tag}：A_ROLL 不应带 handoff，已忽略`);
     return;
   }
-  if (lane === "RRV_MG") {
+  if (lane === "MG" || lane === "RRV_MG") {
     if (!handoff || typeof handoff.duration_hint !== "number") {
-      errors.push(`${tag}：RRV_MG 的 handoff.duration_hint 必填（秒，数值）`);
+      errors.push(`${tag}：MG 的 handoff.duration_hint 必填（秒，数值）`);
+    }
+    if (handoff && handoff.category !== undefined && !isKnownCategory(handoff.category)) {
+      warnings.push(`${tag}：handoff.category「${String(handoff.category)}」非已知品类（${MG_CATEGORIES.join("/")}），已透传但下游按 opaque 反推`);
     }
     return;
   }
@@ -4642,16 +4661,25 @@ function validateHandoff(tag, b, errors, warnings) {
     return;
   }
 }
-function validateAux(tag, raw, idIndex, errors) {
+function validateAux(tag, raw, idIndex, errors, warnings) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     errors.push(`${tag}：辅助层必须是对象`);
     return;
   }
   const a = raw;
   if (!enumOk(a.type, AUX_TYPES))
-    errors.push(`${tag}：type 非法（七类之一）`);
+    errors.push(`${tag}：type 非法（八类之一）`);
   if (!isNonEmptyStr(a.role))
     errors.push(`${tag}：缺 role（职责）`);
+  if (a.type === "overlay") {
+    const handoff = a.handoff;
+    if (!handoff || typeof handoff.duration_hint !== "number" || !(handoff.duration_hint > 0)) {
+      errors.push(`${tag}：overlay aux 缺颗粒时长（handoff.duration_hint 必填且须为正数）`);
+    }
+    if (handoff && handoff.category !== undefined && !isKnownCategory(handoff.category)) {
+      warnings.push(`${tag}：handoff.category「${String(handoff.category)}」非已知品类（${MG_CATEGORIES.join("/")}），已透传但下游按 opaque 反推`);
+    }
+  }
   const m = a.mount;
   if (m === "same_beat")
     return;
@@ -4675,6 +4703,20 @@ function validateAux(tag, raw, idIndex, errors) {
   }
   errors.push(`${tag}：mount 非法（应为 "same_beat" | {from,to} | {trigger}）`);
 }
+var MG_CATEGORIES = ["overlay", "fullscreen", "subtitle", "title"];
+var CATEGORY_EXPECTED_OPAQUE = {
+  overlay: false,
+  fullscreen: true,
+  subtitle: false,
+  title: true,
+  "rrv-overlay": false,
+  "mg-fullscreen": true,
+  "explain-subtitle": false,
+  "op-ed-title": true
+};
+function isKnownCategory(v) {
+  return typeof v === "string" && Object.prototype.hasOwnProperty.call(CATEGORY_EXPECTED_OPAQUE, v);
+}
 function r3(n) {
   return Math.round(n * 1000) / 1000;
 }
@@ -4698,7 +4740,7 @@ function buildLanding(doc, view, opts) {
     ...opts.sourceIndex ? { material_id: opts.sourceIndex.materialId } : {},
     beats: []
   };
-  const dispatch = { rrv_mg: [], film_broll: [], ai_drama: [] };
+  const dispatch = { mg: [], film_broll: [], ai_drama: [] };
   const skipped = [];
   const shrunk = [];
   const unhandledLanes = new Set;
@@ -4715,7 +4757,8 @@ function buildLanding(doc, view, opts) {
     const track_st = Math.min(...instances.map((x) => x.track_st));
     const track_ed = Math.max(...instances.map((x) => x.track_ed));
     const isShrunk = droppedCount > 0;
-    const metaBeat = { id: beat.id, lane: beat.lane, span: beat.span, track_st, track_ed };
+    const lane = normalizeLane(beat.lane) ?? beat.lane;
+    const metaBeat = { id: beat.id, lane, span: beat.span, track_st, track_ed };
     if (opts.sourceIndex) {
       const from = opts.sourceIndex.utterances.get(beat.span.from);
       const to = opts.sourceIndex.utterances.get(beat.span.to);
@@ -4731,7 +4774,9 @@ function buildLanding(doc, view, opts) {
       metaBeat.container_stage = beat.container_stage;
     if (beat.visual_task)
       metaBeat.visual_task = beat.visual_task;
-    if (beat.lane !== "A_ROLL" && beat.handoff)
+    if (lane === "MG" && typeof beat.handoff?.category === "string")
+      metaBeat.category = beat.handoff.category;
+    if (lane !== "A_ROLL" && beat.handoff)
       metaBeat.handoff = beat.handoff;
     split.beats.push(metaBeat);
     if (isShrunk) {
@@ -4739,18 +4784,19 @@ function buildLanding(doc, view, opts) {
     }
     const h = beat.handoff ?? {};
     const compositionId = `${opts.projectSlug}-${beat.id}`;
-    if (beat.lane === "RRV_MG") {
-      dispatch.rrv_mg.push({
+    if (lane === "MG") {
+      dispatch.mg.push({
         beat: beat.id,
         composition_id: compositionId,
         duration: typeof h.duration_hint === "number" ? h.duration_hint : null,
+        ...h.category !== undefined ? { category: h.category } : {},
         theme: h.theme,
         bg: h.bg,
         slug_hint: h.slug_hint,
         track_st,
         track_ed
       });
-    } else if (beat.lane === "FILM_BROLL") {
+    } else if (lane === "FILM_BROLL") {
       dispatch.film_broll.push({
         beat: beat.id,
         queries: Array.isArray(h.queries) ? h.queries : [],
@@ -4760,10 +4806,69 @@ function buildLanding(doc, view, opts) {
         track_st,
         track_ed
       });
-    } else if (beat.lane === "AI_DRAMA") {
+    } else if (lane === "AI_DRAMA") {
       dispatch.ai_drama.push({ beat: beat.id, ...h, track_st, track_ed });
-    } else if (beat.lane !== "A_ROLL") {
-      unhandledLanes.add(beat.lane);
+    } else if (lane !== "A_ROLL") {
+      unhandledLanes.add(lane);
+    }
+    let auxN = 0;
+    for (const aux of beat.aux_layers ?? []) {
+      if (aux.type !== "overlay")
+        continue;
+      auxN += 1;
+      const auxTag = `${beat.id}-aux${auxN}`;
+      const mount = aux.mount;
+      let auxFromId;
+      let auxToId;
+      if (mount === "same_beat") {
+        auxFromId = beat.span.from;
+        auxToId = beat.span.to;
+      } else if ("from" in mount && "to" in mount) {
+        auxFromId = mount.from;
+        auxToId = mount.to;
+      } else {
+        skipped.push({ beat: auxTag, reason: "overlay aux 使用 {trigger} 点挂载，一期不支持（二期补合成窗口）" });
+        continue;
+      }
+      const auxFromIdx = idIndex.get(auxFromId);
+      const auxToIdx = idIndex.get(auxToId);
+      const auxSpanIds = opts.utteranceIds.slice(auxFromIdx, auxToIdx + 1);
+      const auxInstances = auxSpanIds.flatMap((id) => byId.get(id) ?? []);
+      if (auxInstances.length === 0) {
+        skipped.push({ beat: auxTag, reason: "overlay aux 源区间 utterance 全被剪，未落轨" });
+        continue;
+      }
+      const auxTrackSt = Math.min(...auxInstances.map((x) => x.track_st));
+      const auxTrackEd = Math.max(...auxInstances.map((x) => x.track_ed));
+      const auxCompositionId = `${opts.projectSlug}-${beat.id}-aux${auxN}`;
+      const ah = aux.handoff;
+      dispatch.mg.push({
+        beat: beat.id,
+        composition_id: auxCompositionId,
+        duration: ah && typeof ah.duration_hint === "number" ? ah.duration_hint : null,
+        category: "overlay",
+        theme: ah?.theme,
+        bg: ah?.bg,
+        slug_hint: ah?.slug_hint,
+        track_st: auxTrackSt,
+        track_ed: auxTrackEd
+      });
+      const auxMetaBeat = {
+        id: auxTag,
+        lane: "MG",
+        span: { from: auxFromId, to: auxToId },
+        track_st: auxTrackSt,
+        track_ed: auxTrackEd,
+        category: "overlay"
+      };
+      if (opts.sourceIndex) {
+        const sfrom = opts.sourceIndex.utterances.get(auxFromId);
+        const sto = opts.sourceIndex.utterances.get(auxToId);
+        if (sfrom && sto && sto.ed > sfrom.st) {
+          auxMetaBeat.source_ranges = [{ st: r3(sfrom.st), ed: r3(sto.ed) }];
+        }
+      }
+      split.beats.push(auxMetaBeat);
     }
   }
   return { split, dispatch, skipped, shrunk, unhandledLanes: [...unhandledLanes] };
@@ -4810,8 +4915,8 @@ function renderSplitMarkdown(doc, landing, meta) {
     L.push(`- \`${b.id}\` ${b.visual_task}`);
   }
   L.push("");
-  L.push("## RRV_MG Queue");
-  for (const r of landing.dispatch.rrv_mg) {
+  L.push("## MG Queue");
+  for (const r of landing.dispatch.mg) {
     L.push(`- \`${r.beat}\` composition_id=\`${r.composition_id}\`${r.duration != null ? ` · ${r.duration}s` : ""}`);
   }
   L.push("");
@@ -4928,6 +5033,13 @@ function resolveColumnConfig(opts = {}) {
   return { config, warnings };
 }
 var HANDOFF_REGISTRY = LANES;
+var LEGACY_HANDOFF_ALIASES = { RRV_MG: "MG" };
+function normalizeHandoffType(v) {
+  return LEGACY_HANDOFF_ALIASES[v] ?? v;
+}
+function isRegisteredHandoff(v) {
+  return HANDOFF_REGISTRY.includes(normalizeHandoffType(v));
+}
 function normalizeEntries(list, kind, warnings) {
   if (list === undefined)
     return;
@@ -5002,7 +5114,7 @@ function producesNotices(style) {
     if (e.routing === "none")
       continue;
     for (const v of producesValues(e)) {
-      if (HANDOFF_REGISTRY.includes(v) || seen.has(v))
+      if (isRegisteredHandoff(v) || seen.has(v))
         continue;
       const near = HANDOFF_REGISTRY.find((r) => r.toLowerCase() === v.toLowerCase() || editDistance(r.toUpperCase(), v.toUpperCase()) <= 2);
       if (near) {
@@ -6877,7 +6989,7 @@ async function runLand(splitdocPath, baseDir, gtrkPath, transcriptPath, opts) {
     mdPath = join18(splitDir, "visual-split.md");
     await writeFile6(mdPath, renderSplitMarkdown(doc, landing, { projectSlug, projectedAt }));
   }
-  log.ok(`落地完成：${landing.split.beats.length}/${doc.beats.length} beat 落轨` + `（RRV_MG ${landing.dispatch.rrv_mg.length} · FILM_BROLL ${landing.dispatch.film_broll.length} · AI_DRAMA ${landing.dispatch.ai_drama.length}）`);
+  log.ok(`落地完成：${landing.split.beats.length}/${doc.beats.length} beat 落轨` + `（MG ${landing.dispatch.mg.length} · FILM_BROLL ${landing.dispatch.film_broll.length} · AI_DRAMA ${landing.dispatch.ai_drama.length}）`);
   for (const s of landing.skipped)
     log.warn(`跳过 ${s.beat}：${s.reason}`);
   for (const s of landing.shrunk)
@@ -6895,7 +7007,7 @@ async function runLand(splitdocPath, baseDir, gtrkPath, transcriptPath, opts) {
     projected_at: projectedAt,
     beats: { total: doc.beats.length, landed: landing.split.beats.length, skipped: landing.skipped, shrunk: landing.shrunk },
     queues: {
-      rrv_mg: landing.dispatch.rrv_mg.length,
+      mg: landing.dispatch.mg.length,
       film_broll: landing.dispatch.film_broll.length,
       ai_drama: landing.dispatch.ai_drama.length
     }
@@ -7685,12 +7797,386 @@ function slugify2(name) {
   return s || "project";
 }
 
+// src/commands/mg.ts
+import { resolve as resolve8, join as join20, dirname as dirname7, basename as basename10 } from "node:path";
+import { existsSync as existsSync16 } from "node:fs";
+import { readFile as readFile6, mkdir as mkdir7, copyFile } from "node:fs/promises";
+
+// src/lib/mg-lint.ts
+var CDN_OK = [/lib\.baomitu\.com/i, /cdnjs\.cloudflare\.com/i, /unpkg\.com/i];
+var CDN_WARN = [/jsdelivr\.net/i];
+function rootTag(html) {
+  const m = html.match(/<[a-zA-Z][^>]*\bdata-composition-id\s*=[^>]*>/);
+  return m ? m[0] : null;
+}
+function attr(tag, name) {
+  const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*["']([^"']*)["']`, "i"));
+  return m ? m[1] : undefined;
+}
+function deriveOpaque(rootTagStr) {
+  if (!rootTagStr)
+    return { opaque: false, declared: false };
+  const style = attr(rootTagStr, "style") ?? "";
+  const bg = style.match(/background(?:-color)?\s*:\s*([^;"']+)/i);
+  if (!bg)
+    return { opaque: false, declared: false };
+  const val = bg[1].trim().toLowerCase();
+  const transparent = val === "transparent" || val === "none" || /rgba\([^)]*,\s*0\s*\)/.test(val);
+  return { opaque: !transparent, declared: true };
+}
+var CATEGORY_EXPECTED_OPAQUE2 = {
+  overlay: false,
+  fullscreen: true,
+  subtitle: false,
+  title: true,
+  "rrv-overlay": false,
+  "mg-fullscreen": true,
+  "explain-subtitle": false,
+  "op-ed-title": true
+};
+function lintParticle(html, opts = {}) {
+  const v = [];
+  const push = (law, fatal, msg) => v.push({ law, fatal, msg });
+  if (!/<template[\s>]/i.test(html))
+    push("1-template", true, "缺 <template> 包裹根元素（裸 div 整片渲染失败）");
+  const root = rootTag(html);
+  const cid = root ? attr(root, "data-composition-id") : undefined;
+  if (!root || !cid)
+    push("1-composition-id", true, "根元素缺 data-composition-id");
+  if (root) {
+    if (attr(root, "data-width") !== "1920")
+      push("1-width", true, `根 data-width 应为 "1920"（实为 ${attr(root, "data-width") ?? "缺"}）`);
+    if (attr(root, "data-height") !== "1080")
+      push("1-height", true, `根 data-height 应为 "1080"（实为 ${attr(root, "data-height") ?? "缺"}）`);
+  }
+  if (!/gsap\.timeline\s*\(\s*\{[^}]*\bpaused\s*:\s*true\b[^}]*\}\s*\)/.test(html))
+    push("2-paused", true, "缺 gsap.timeline({ paused: true })");
+  const regMatch = html.match(/window\.__timelines\s*\[\s*(["']([^"']+)["']|[A-Za-z_$][\w$]*)\s*\]\s*=/);
+  if (!regMatch)
+    push("2-register", true, "缺 window.__timelines[<id>] = 注册");
+  else {
+    let regId = regMatch[2];
+    if (regId === undefined) {
+      const ident = regMatch[1];
+      const vm = html.match(new RegExp(`(?:var|const|let)\\s+${ident}\\s*=\\s*["']([^"']+)["']`));
+      regId = vm?.[1];
+      if (!regId)
+        push("2-register", true, `__timelines[${ident}] 的 ${ident} 未见字面串赋值，无法静态判定注册 id`);
+    }
+    if (cid && regId !== undefined && regId !== cid)
+      push("2-id-match", true, `__timelines 注册 id "${regId}" 与 data-composition-id "${cid}" 不一致`);
+  }
+  if (/Math\.random\s*\(/.test(html))
+    push("3-random", true, "含 Math.random()（破 StaticGuard，逐帧不确定）");
+  if (/Date\.now\s*\(/.test(html))
+    push("3-date-now", true, "含 Date.now()");
+  if (/new\s+Date\s*\(\s*\)/.test(html))
+    push("3-new-date", true, "含无参 new Date()");
+  for (const m of html.matchAll(/<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi)) {
+    const src = m[1];
+    if (!/^https?:\/\//i.test(src))
+      push("4-script-rel", true, `<script src> 非 http(s) 绝对 url：${src}`);
+    else if (CDN_WARN.some((r) => r.test(src)))
+      push("5-cdn-jsdelivr", false, `CDN 用 jsdelivr（国内渲染机不稳，建议 lib.baomitu.com）：${src}`);
+    else if (!CDN_OK.some((r) => r.test(src)))
+      push("5-cdn-unknown", false, `CDN 不在已知可达白名单（渲染机可能拉不到）：${src}`);
+  }
+  for (const [re, tag] of [
+    [/<img\b[^>]*\bsrc\s*=\s*["'](?!https?:|data:)[^"']+["']/gi, "<img src>"],
+    [/<link\b[^>]*\bhref\s*=\s*["'](?!https?:|data:)[^"']+["']/gi, "<link href>"],
+    [/<use\b[^>]*\b(?:xlink:)?href\s*=\s*["'](?!#|https?:|data:)[^"']+["']/gi, "<use href>"],
+    [/\burl\(\s*["']?(?!https?:|data:|#)[^)"']+["']?\s*\)/gi, "css url()"]
+  ]) {
+    if (re.test(html))
+      push("4-rel-asset", true, `含相对外链 ${tag}（违反自包含，渲染机读不到）`);
+  }
+  const { opaque, declared } = deriveOpaque(root);
+  if (root && !declared)
+    push("4-bg-explicit", false, "根未显式声明 background（透明与否应明确；缺省按透明叠加 opaque=false 处理）");
+  if (/var\(\s*--/.test(html))
+    push("6-css-var", true, "含 CSS var(--...)（Hyperframes 不解析→整片全黑，须字面值）");
+  const effectiveCid = opts.compositionId ?? cid;
+  if (opts.dispatchIds && effectiveCid && !opts.dispatchIds.includes(effectiveCid))
+    push("x-dispatch", false, `composition_id "${effectiveCid}" 不在 dispatch.mg 派单中`);
+  if (opts.category && opts.category in CATEGORY_EXPECTED_OPAQUE2) {
+    const expect = CATEGORY_EXPECTED_OPAQUE2[opts.category];
+    if (expect !== opaque)
+      push("x-category-opaque", false, `category「${opts.category}」期望${expect ? "不透明满屏" : "透明叠加"}，但颗粒 HTML 反推为${opaque ? "不透明满屏" : "透明叠加"}（以 HTML 为准落 clip.opaque=${opaque}）`);
+  }
+  return { ok: !v.some((x) => x.fatal), violations: v, opaque, compositionId: cid };
+}
+
+// src/lib/mg-lay.ts
+var MG_MATERIAL_PREFIX = "mg-";
+var LEGACY_MATERIAL_PREFIX = "rrv-";
+var isOwnMaterialId = (id) => id.startsWith(MG_MATERIAL_PREFIX) || id.startsWith(LEGACY_MATERIAL_PREFIX);
+var r34 = (n) => Math.round(n * 1000) / 1000;
+function layTracksOf(prev) {
+  return Array.isArray(prev?.lay_tracks) ? prev.lay_tracks.filter((x) => typeof x === "number") : [];
+}
+function layMgTracks(opts) {
+  const { gtrk, items, generatedAt } = opts;
+  const beatTracks = [...gtrk.beat_track ?? []];
+  const materials = [...gtrk.materials ?? []];
+  const structMeta = { ...gtrk.struct_meta ?? {} };
+  const prevMg = structMeta.mg;
+  const prevRrv = structMeta.rrv;
+  const prevIndices = new Set([...layTracksOf(prevMg), ...layTracksOf(prevRrv)]);
+  const removedTracks = beatTracks.filter((t) => typeof t.track_index === "number" && prevIndices.has(t.track_index));
+  const keptTracks = beatTracks.filter((t) => !(typeof t.track_index === "number" && prevIndices.has(t.track_index)));
+  const removedMaterialIds = new Set;
+  for (const t of removedTracks) {
+    for (const c3 of t.track_timeline ?? []) {
+      const hm = c3.html_material;
+      if (typeof hm === "string" && isOwnMaterialId(hm))
+        removedMaterialIds.add(hm);
+    }
+  }
+  const keptMaterials = materials.filter((m) => !(typeof m.id === "string" && removedMaterialIds.has(m.id)));
+  const newMaterials = [];
+  const clips = [];
+  const metaBeats = [];
+  const allIndices = [
+    ...keptTracks,
+    ...gtrk.video_track ?? [],
+    ...gtrk.audio_track ?? []
+  ].map((t) => typeof t.track_index === "number" ? t.track_index : 0);
+  const newIndex = Math.max(9, ...allIndices) + 1;
+  for (const it of items) {
+    if (!(it.duration > 0)) {
+      metaBeats.push({ ...toMetaBeat(it), laid: null });
+      continue;
+    }
+    const materialId = `${MG_MATERIAL_PREFIX}${it.composition_id}`;
+    newMaterials.push({ id: materialId, path: it.html_rel });
+    clips.push({
+      clip_id: it.composition_id,
+      material: it.composition_id,
+      html_material: materialId,
+      opaque: it.opaque,
+      track_st: it.track_st,
+      duration: it.duration
+    });
+    metaBeats.push({ ...toMetaBeat(it), laid: { track_index: newIndex } });
+  }
+  const createdTracks = clips.length > 0 ? [
+    {
+      track_index: newIndex,
+      track_timeline: clips.sort((a, b) => a.track_st - b.track_st)
+    }
+  ] : [];
+  const mg = {
+    contract_version: "v1",
+    generated_at: generatedAt,
+    lay_tracks: createdTracks.map((t) => t.track_index),
+    beats: metaBeats
+  };
+  const nextStructMeta = { ...structMeta, mg };
+  delete nextStructMeta.rrv;
+  const next = {
+    ...gtrk,
+    materials: [...keptMaterials, ...newMaterials],
+    beat_track: [...keptTracks, ...createdTracks],
+    struct_meta: nextStructMeta
+  };
+  return {
+    next,
+    summary: { laidTrack: createdTracks[0]?.track_index ?? null, laidParticles: clips.length },
+    mg
+  };
+}
+function toMetaBeat(it) {
+  return {
+    beat: it.beat,
+    composition_id: it.composition_id,
+    track_st: it.track_st,
+    track_ed: r34(it.track_ed),
+    duration: it.duration,
+    html_path: it.html_rel,
+    ...it.category ? { category: it.category } : {}
+  };
+}
+
+// src/commands/mg.ts
+var MG_ASSET_DIR = "assets/mg";
+var MG_SRC_DIRS = ["mg", "rrv"];
+function registerMg(program2) {
+  program2.command("mg [words...]").alias("rrv").description("MG 颗粒铺轨：无 positional=消费 dispatch.mg 铺 html-particle；`mg lint <file>`=单文件 lint；`mg status`=看板").option("--project <dir>", "oralcut 产物目录（定位 split/dispatch.json 与工程）").option("--dispatch <path>", "显式指定 dispatch.json（非标准布局兜底）").option("--only <beat>", "只跑单 beat").option("--lint-only", "只 lint 校验，不铺轨不写回").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON").action(async (words, opts) => {
+    if (process.argv[2] === "rrv")
+      log.warn("`gtrk rrv` 已更名为 `gtrk mg`（去品牌化），别名仍可用但建议改用 `gtrk mg`。");
+    await runMg(words ?? [], opts);
+  });
+}
+async function runMg(words, opts) {
+  if (opts.json)
+    routeLogsToStderr();
+  const sub = words[0];
+  if (sub === "lint")
+    return runLint(words.slice(1), opts);
+  if (sub === "status")
+    return runStatus(opts);
+  if (sub)
+    throw new Error(`未知子命令「${sub}」——铺轨：gtrk mg --project <dir>；lint：gtrk mg lint <file>；看板：gtrk mg status`);
+  return runLay(opts);
+}
+function resolveDispatch(opts) {
+  if (opts.dispatch) {
+    const dispatchPath = resolve8(opts.dispatch);
+    return { dispatchPath, baseDir: dirname7(dirname7(dispatchPath)) };
+  }
+  if (opts.project) {
+    const baseDir = resolve8(opts.project);
+    return { dispatchPath: join20(baseDir, "split", "dispatch.json"), baseDir };
+  }
+  throw new Error("需 --project <目录> 或显式 --dispatch <path>");
+}
+function locateGtrk2(baseDir) {
+  return [join20(baseDir, "gtrk", "project.gtrk"), join20(baseDir, "project.gtrk")].find((p) => existsSync16(p));
+}
+function locateSrcHtml(baseDir, compositionId) {
+  for (const d of MG_SRC_DIRS) {
+    const p = join20(baseDir, d, `${compositionId}.html`);
+    if (existsSync16(p))
+      return p;
+  }
+  return;
+}
+async function readMgQueue(dispatchPath) {
+  if (!existsSync16(dispatchPath))
+    throw new Error(`找不到派单清单：${dispatchPath}（先跑 gtrk split 落地派单）`);
+  const dispatch = JSON.parse(await readFile6(dispatchPath, "utf8"));
+  const queue = dispatch.mg ?? dispatch.rrv_mg;
+  return Array.isArray(queue) ? queue : [];
+}
+async function runLay(opts) {
+  const { dispatchPath, baseDir } = resolveDispatch(opts);
+  let queue = await readMgQueue(dispatchPath);
+  if (opts.only)
+    queue = queue.filter((q) => q.beat === opts.only);
+  log.step(`▶ MG 颗粒铺轨：${queue.length} 个 beat…`);
+  const dispatchIds = queue.map((q) => q.composition_id);
+  const items = [];
+  const srcByComp = new Map;
+  const skipped = [];
+  for (const q of queue) {
+    const srcPath = locateSrcHtml(baseDir, q.composition_id);
+    if (!srcPath) {
+      skipped.push({ beat: q.beat, reason: "缺颗粒 HTML（未产出）" });
+      log.warn(`${q.beat}：缺 ${join20(baseDir, MG_SRC_DIRS[0], `${q.composition_id}.html`)}，跳过`);
+      continue;
+    }
+    const html = await readFile6(srcPath, "utf8");
+    const category = typeof q.category === "string" ? q.category : undefined;
+    const lint = lintParticle(html, { compositionId: q.composition_id, dispatchIds, category });
+    for (const vv of lint.violations)
+      (vv.fatal ? log.warn : log.info)(`${q.beat} lint ${vv.fatal ? "✗" : "·"} ${vv.law}: ${vv.msg}`);
+    if (!lint.ok) {
+      skipped.push({ beat: q.beat, reason: "lint 未过" });
+      log.warn(`${q.beat}：lint 未过，跳过`);
+      continue;
+    }
+    if (typeof q.duration !== "number" || !(q.duration > 0)) {
+      skipped.push({ beat: q.beat, reason: "duration 非正数" });
+      continue;
+    }
+    srcByComp.set(q.composition_id, srcPath);
+    items.push({
+      beat: q.beat,
+      composition_id: q.composition_id,
+      track_st: q.track_st,
+      track_ed: q.track_ed,
+      duration: q.duration,
+      opaque: lint.opaque,
+      html_rel: `${MG_ASSET_DIR}/${q.composition_id}.html`,
+      ...category ? { category } : {}
+    });
+  }
+  if (opts.lintOnly) {
+    log.ok(`lint-only：${items.length}/${queue.length} 通过，${skipped.length} 跳过（不铺轨）`);
+    return done(opts, { ok: skipped.length === 0, mode: "lay", lintOnly: true, passed: items.length, skipped });
+  }
+  const gtrkPath = locateGtrk2(baseDir);
+  if (!gtrkPath) {
+    log.warn(`未找到工程文件（${join20(baseDir, "gtrk", "project.gtrk")}），跳过铺轨——lint 已完成`);
+    return done(opts, { ok: true, mode: "lay", laid: 0, skipped, note: "工程缺失，未铺轨" });
+  }
+  const { gtrk, mtimeMs } = readGtrk(gtrkPath);
+  assertGtrkV1(gtrk);
+  const gtrkDir = dirname7(gtrkPath);
+  await mkdir7(join20(gtrkDir, ...MG_ASSET_DIR.split("/")), { recursive: true });
+  for (const it of items) {
+    await copyFile(srcByComp.get(it.composition_id), join20(gtrkDir, ...it.html_rel.split("/")));
+  }
+  const { next, summary } = layMgTracks({ gtrk, items, generatedAt: new Date().toISOString() });
+  writeGtrkAtomic(gtrkPath, next, mtimeMs);
+  log.ok(`铺轨完成：${summary.laidParticles} 颗粒 → beat_track ${summary.laidTrack ?? "-"}` + `${skipped.length ? `（${skipped.length} beat 跳过）` : ""}`);
+  log.info("opencut 打开工程即见 MG overlay 轨（预览需 add-particle-project-folder-preview 上线）；出片时客户端云渲。");
+  return done(opts, {
+    ok: true,
+    mode: "lay",
+    laid: summary.laidParticles,
+    laidTrack: summary.laidTrack,
+    skipped
+  });
+}
+async function runLint(args, opts) {
+  const file = args[0];
+  if (!file)
+    throw new Error("用法：gtrk mg lint <particle.html> [--dispatch <path>]");
+  const html = await readFile6(resolve8(file), "utf8");
+  let dispatchIds;
+  if (opts.dispatch && existsSync16(resolve8(opts.dispatch))) {
+    dispatchIds = (await readMgQueue(resolve8(opts.dispatch))).map((q) => q.composition_id);
+  }
+  const lint = lintParticle(html, { dispatchIds });
+  for (const vv of lint.violations)
+    (vv.fatal ? log.err : log.warn)(`${vv.fatal ? "✗" : "·"} ${vv.law}: ${vv.msg}`);
+  if (lint.ok)
+    log.ok(`lint 通过（${basename10(file)}；opaque=${lint.opaque}）`);
+  else
+    log.err(`lint 未过（${lint.violations.filter((v) => v.fatal).length} 项致命）`);
+  const result = { mode: "lint", ...lint, ok: lint.ok };
+  if (opts.json)
+    console.log(JSON.stringify(result));
+  if (!lint.ok)
+    process.exitCode = 1;
+  return result;
+}
+async function runStatus(opts) {
+  const { dispatchPath, baseDir } = resolveDispatch(opts);
+  const queue = await readMgQueue(dispatchPath);
+  const gtrkPath = locateGtrk2(baseDir);
+  let laidIds = new Set;
+  if (gtrkPath) {
+    const { gtrk } = readGtrk(gtrkPath);
+    const structMeta = gtrk.struct_meta;
+    const meta = structMeta?.mg ?? structMeta?.rrv;
+    laidIds = new Set((meta?.beats ?? []).filter((b) => b.laid).map((b) => b.composition_id));
+  }
+  const rows = queue.map((q) => {
+    const authored2 = locateSrcHtml(baseDir, q.composition_id) !== undefined;
+    const laid2 = laidIds.has(q.composition_id);
+    return { beat: q.beat, composition_id: q.composition_id, authored: authored2, laid: laid2, state: laid2 ? "已铺" : authored2 ? "已产未铺" : "缺 HTML" };
+  });
+  const authored = rows.filter((r) => r.authored).length;
+  const laid = rows.filter((r) => r.laid).length;
+  log.step(`▶ MG 看板：${queue.length} beat · ${authored} 已产 · ${laid} 已铺`);
+  for (const r of rows)
+    log.info(`${r.beat}（${r.composition_id}）→ ${r.state}`);
+  return done(opts, { ok: true, mode: "status", total: queue.length, authored, laid, rows });
+}
+function done(opts, result) {
+  if (opts.json)
+    console.log(JSON.stringify(result));
+  return result;
+}
+
 // src/index.ts
 try {
   process.loadEnvFile?.();
 } catch {}
 migrateLegacyHome();
-var { version } = JSON.parse(readFileSync5(join20(packageRoot(), "package.json"), "utf8"));
+var { version } = JSON.parse(readFileSync5(join21(packageRoot(), "package.json"), "utf8"));
 var program2 = new Command;
 program2.name("gtrk").description("同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通").version(version);
 registerInstall(program2);
@@ -7703,6 +8189,7 @@ registerUpgrade(program2);
 registerRender(program2);
 registerSplit(program2);
 registerMatrix(program2);
+registerMg(program2);
 program2.parseAsync(process.argv).catch((e) => {
   console.error(`
 ❌ ${e instanceof Error ? e.message : String(e)}`);