@gitruck/cli 0.2.4 → 0.2.7

package/dist/index.js

@@ -4196,8 +4196,8 @@ var {
 } = import__.default;
 
 // src/index.ts
-import { readFileSync as readFileSync4 } from "node:fs";
-import { join as join17 } from "node:path";
+import { readFileSync as readFileSync5 } from "node:fs";
+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"];
+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;
@@ -4295,19 +4302,19 @@ function installSkill(opts = {}) {
       log.warn(`skill 安装失败（${name}，不影响命令行使用）：${e instanceof Error ? e.message : String(e)}`);
     }
   }
-  log.info("在 Claude Code 里打 /gtrk-oralcut 或 /gtrk-splitter，也可直接说「帮我剪个口播 / 拆个分镜」触发（可能需重载会话）。");
+  log.info("在 Claude Code 里打 /gtrk-oralcut、/gtrk-splitter 或 /gtrk-style-maker，也可直接说「帮我剪个口播 / 拆个分镜 / 造我栏目的风格 skill」触发（可能需重载会话）。");
   return allOk;
 }
 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 });
   });
 }
 
 // src/commands/init.ts
-import { join as join7, resolve as resolve2 } from "node:path";
-import { existsSync as existsSync7 } from "node:fs";
+import { join as join9, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync8 } from "node:fs";
 
 // src/lib/user-config.ts
 import { join as join3 } from "node:path";
@@ -4466,808 +4473,1475 @@ async function promptConfirm(message, defaultYes = true) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
+import { join as join8 } from "node:path";
 
-// src/lib/ffmpeg.ts
-import { spawn as spawn2, spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
+// src/lib/column-config.ts
 import { join as join5 } from "node:path";
-var isWin = process.platform === "win32";
-var bin = (base) => isWin ? `${base}.exe` : base;
-var FFMPEG_INSTALL_HINT = `未找到 ffmpeg/ffprobe。请把二者放到 ${ffmpegDir()}（agent 可代办：先查本地确实缺失才拉，` + `面向国内用户优先国内加速站点——GitHub 代理 pass-through 拉 BtbN/gyan.dev 官方静态构建，或同合云自建镜像，` + `并做 sha256 校验），或用 --ffmpeg-path <目录> 指定已装位置。`;
-var _cache = new Map;
-function onSystemPath(cmd) {
-  try {
-    return spawnSync2(cmd, ["-version"], { stdio: "ignore" }).status === 0;
-  } catch {
-    return false;
-  }
+import { existsSync as existsSync5, readFileSync as readFileSync2 } from "node:fs";
+
+// src/lib/splitdoc.ts
+var BASE_TRACKS = ["真人出镜", "口播继续", "旁白主导"];
+var LANES = ["A_ROLL", "MG", "AI_DRAMA", "FILM_BROLL"];
+var NARRATIVES = [
+  "mirror-hook",
+  "demolition",
+  "container-translation",
+  "abyssal-fall",
+  "holding",
+  "reversal-elevation",
+  "callback-closure",
+  "typography-emphasis"
+];
+var CONTAINER_STAGES = [
+  "none",
+  "seed",
+  "expand",
+  "translate",
+  "rupture",
+  "flip",
+  "callback"
+];
+var IRREPLACEABILITY = ["必须真人出镜", "优先 MG", "可被 B-roll 替代", "可降级处理"];
+var AUX_TYPES = [
+  "quote-card",
+  "term-callout",
+  "network-diagram",
+  "archive-caption",
+  "pause-card",
+  "data-annotation",
+  "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 resolveFfmpeg(ffmpegPath) {
-  const key = ffmpegPath ?? "";
-  if (_cache.has(key))
-    return _cache.get(key) ?? null;
-  const dirs = [];
-  if (ffmpegPath)
-    dirs.push([ffmpegPath, ffmpegPath]);
-  dirs.push([ffmpegDir(), "~/.gitruck/ffmpeg"]);
-  let found = null;
-  for (const [dir, label] of dirs) {
-    const ff = join5(dir, bin("ffmpeg"));
-    const fp = join5(dir, bin("ffprobe"));
-    if (existsSync5(ff) && existsSync5(fp)) {
-      found = { ffmpeg: ff, ffprobe: fp, source: label };
-      break;
-    }
-  }
-  if (!found && onSystemPath("ffmpeg") && onSystemPath("ffprobe")) {
-    found = { ffmpeg: "ffmpeg", ffprobe: "ffprobe", source: "system" };
-  }
-  _cache.set(key, found);
-  return found;
+function isNonEmptyStr(v) {
+  return typeof v === "string" && v.trim().length > 0;
 }
-function requireFfmpeg(ffmpegPath) {
-  const r = resolveFfmpeg(ffmpegPath);
-  if (!r)
-    throw new Error(FFMPEG_INSTALL_HINT);
-  return r;
+function enumOk(v, list) {
+  return typeof v === "string" && list.includes(v);
 }
-function ffprobeJson(ffprobePath, args) {
-  const r = spawnSync2(ffprobePath, args, { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
-  if (r.status !== 0) {
-    throw new Error(`ffprobe 失败（code=${r.status}）：${(r.stderr || "").slice(-300)}`);
+function validateSplitDoc(doc, ctx) {
+  const errors = [];
+  const warnings = [];
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+    return { errors: ["拆分稿必须是一个 JSON 对象"], warnings };
   }
-  return JSON.parse(r.stdout || "{}");
-}
-function runFfmpeg(ffmpegPath, args, onLine) {
-  return new Promise((resolve2, reject) => {
-    const p = spawn2(ffmpegPath, args, { env: process.env });
-    let tail = "";
-    p.stderr.on("data", (buf) => {
-      const s = buf.toString("utf8");
-      tail = (tail + s).slice(-4000);
-      if (onLine) {
-        for (const ln of s.split(/\r?\n/))
-          if (ln)
-            onLine(ln);
+  const d = doc;
+  const vocab = ctx.vocab ?? {
+    narrative: NARRATIVES,
+    container_stage: CONTAINER_STAGES,
+    base_track: BASE_TRACKS
+  };
+  const freeVocab = vocab.unknown_narrative === "allow";
+  if (d.contract_version !== "v1") {
+    errors.push(`contract_version 必须为 "v1"（实际：${JSON.stringify(d.contract_version)}）`);
+  }
+  if (!isNonEmptyStr(d.transcript_hash)) {
+    errors.push("缺 transcript_hash（应从投影视图透传）");
+  } else if (d.transcript_hash !== ctx.transcriptHash) {
+    errors.push(`transcript_hash 不匹配：拆分稿 ${d.transcript_hash} ≠ 当前 transcript ${ctx.transcriptHash}——转写已变更，请重新导出视图并重拆`);
+  }
+  if (!Array.isArray(d.beats) || d.beats.length === 0) {
+    errors.push("beats 必须是非空数组");
+    return { errors, warnings };
+  }
+  const idIndex = new Map;
+  ctx.utteranceIds.forEach((id, i) => idIndex.set(id, i));
+  const ranges = [];
+  const seenBeatIds = new Set;
+  d.beats.forEach((raw, i) => {
+    const tag = (() => {
+      const bid = raw?.id;
+      return isNonEmptyStr(bid) ? bid : `beats[${i}]`;
+    })();
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      errors.push(`${tag}：beat 必须是对象`);
+      return;
+    }
+    const b = raw;
+    if (!isNonEmptyStr(b.id))
+      errors.push(`${tag}：缺 id`);
+    else if (!/^B\d{2,}$/.test(b.id))
+      errors.push(`${b.id}：id 须为 "B"+两位起序号（如 B01）`);
+    else if (seenBeatIds.has(b.id))
+      errors.push(`${b.id}：beat id 重复`);
+    else
+      seenBeatIds.add(b.id);
+    if (freeVocab) {
+      if (!isNonEmptyStr(b.base_track))
+        errors.push(`${tag}：缺 base_track`);
+      if (!isNonEmptyStr(b.narrative))
+        errors.push(`${tag}：缺 narrative`);
+      if (!isNonEmptyStr(b.container_stage))
+        errors.push(`${tag}：缺 container_stage`);
+    } else {
+      if (!enumOk(b.base_track, vocab.base_track))
+        errors.push(`${tag}：base_track 非法（栏目词表：${vocab.base_track.join(" | ")}）`);
+      if (!enumOk(b.narrative, vocab.narrative))
+        errors.push(`${tag}：narrative 非法（不在栏目词表内）`);
+      if (!enumOk(b.container_stage, vocab.container_stage))
+        errors.push(`${tag}：container_stage 非法（不在栏目词表内）`);
+    }
+    if (!normalizeLane(b.lane))
+      errors.push(`${tag}：lane 非法（四选一：${LANES.join(" | ")}）`);
+    if (!enumOk(b.irreplaceability, IRREPLACEABILITY))
+      errors.push(`${tag}：irreplaceability 非法（四枚举之一）`);
+    if (!isNonEmptyStr(b.rhythm))
+      errors.push(`${tag}：缺 rhythm（人读节奏标签）`);
+    if (!isNonEmptyStr(b.visual_task))
+      errors.push(`${tag}：缺 visual_task（一句话视觉任务）`);
+    const span = b.span;
+    let fromIdx = -1;
+    let toIdx = -1;
+    if (!span || !isNonEmptyStr(span.from) || !isNonEmptyStr(span.to)) {
+      errors.push(`${tag}：缺 span.from / span.to（utterance id 区间）`);
+    } else {
+      if (!idIndex.has(span.from))
+        errors.push(`${tag}：span.from 引用了不存在的 utterance id ${span.from}`);
+      else
+        fromIdx = idIndex.get(span.from);
+      if (!idIndex.has(span.to))
+        errors.push(`${tag}：span.to 引用了不存在的 utterance id ${span.to}`);
+      else
+        toIdx = idIndex.get(span.to);
+      if (fromIdx >= 0 && toIdx >= 0) {
+        if (fromIdx > toIdx)
+          errors.push(`${tag}：区间倒序（span.from ${span.from} 晚于 span.to ${span.to}）`);
+        else if (isNonEmptyStr(b.id))
+          ranges.push({ id: b.id, from: fromIdx, to: toIdx });
       }
-    });
-    p.on("error", (e) => reject(e));
-    p.on("close", (code) => {
-      if (code === 0)
-        resolve2();
+    }
+    validateHandoff(tag, b, errors, warnings);
+    if (b.aux_layers != null) {
+      if (!Array.isArray(b.aux_layers))
+        errors.push(`${tag}：aux_layers 必须是数组`);
       else
-        reject(new Error(`ffmpeg 退出码 ${code}：${tail.slice(-600)}`));
-    });
-  });
-}
-function probeCapabilities(res) {
-  const ver = spawnSync2(res.ffmpeg, ["-version"], { encoding: "utf8" });
-  const version = (ver.stdout || "").split(/\r?\n/)[0]?.trim() || "unknown";
-  const enc = spawnSync2(res.ffmpeg, ["-hide_banner", "-encoders"], {
-    encoding: "utf8",
-    maxBuffer: 16 * 1024 * 1024
-  });
-  const fil = spawnSync2(res.ffmpeg, ["-hide_banner", "-filters"], {
-    encoding: "utf8",
-    maxBuffer: 16 * 1024 * 1024
+        b.aux_layers.forEach((a, ai) => validateAux(`${tag}.aux[${ai}]`, a, idIndex, errors, warnings));
+    }
   });
-  const encoders = new Set;
-  for (const ln of (enc.stdout || "").split(/\r?\n/)) {
-    const m = ln.trim().match(/^\S+\s+(\S+)/);
-    if (m)
-      encoders.add(m[1]);
-  }
-  const filters = new Set;
-  for (const ln of (fil.stdout || "").split(/\r?\n/)) {
-    const m = ln.trim().match(/^\S+\s+(\S+)/);
-    if (m)
-      filters.add(m[1]);
+  const sorted = [...ranges].sort((a, b) => a.from - b.from || a.to - b.to);
+  for (let i = 1;i < sorted.length; i++) {
+    const prev = sorted[i - 1];
+    const cur = sorted[i];
+    if (cur.from <= prev.to) {
+      errors.push(`${prev.id} 与 ${cur.id}：utterance 区间重叠（beats 之间不允许交集）`);
+    }
   }
-  return {
-    version,
-    encoders,
-    filters,
-    hasLibx264: encoders.has("libx264"),
-    hasAac: encoders.has("aac"),
-    hasAfade: filters.has("afade"),
-    hasAresample: filters.has("aresample")
-  };
+  return { errors, warnings };
 }
-
-// src/lib/version.ts
-import { readFileSync as readFileSync2 } from "node:fs";
-import { join as join6 } from "node:path";
-var REGISTRY = "https://registry.npmjs.org/@gitruck%2Fcli";
-function currentVersion() {
-  try {
-    const { version } = JSON.parse(readFileSync2(join6(packageRoot(), "package.json"), "utf8"));
-    return version;
-  } catch {
-    return "0.0.0";
+function validateHandoff(tag, b, errors, warnings) {
+  const lane = b.lane;
+  const handoff = b.handoff;
+  if (lane === "A_ROLL") {
+    if (handoff != null)
+      warnings.push(`${tag}：A_ROLL 不应带 handoff，已忽略`);
+    return;
   }
-}
-async function latestVersion(timeoutMs = 5000) {
-  try {
-    const res = await fetch(REGISTRY, {
-      headers: { accept: "application/vnd.npm.install-v1+json" },
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    if (!res.ok)
-      return null;
-    const data = await res.json();
-    return data["dist-tags"]?.latest ?? null;
-  } catch {
-    return null;
+  if (lane === "MG" || lane === "RRV_MG") {
+    if (!handoff || typeof handoff.duration_hint !== "number") {
+      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;
+  }
+  if (lane === "FILM_BROLL") {
+    const q = handoff?.queries;
+    if (!Array.isArray(q) || q.length === 0 || !q.every((x) => isNonEmptyStr(x))) {
+      errors.push(`${tag}：FILM_BROLL 缺检索 query（handoff.queries 必须为非空字符串数组）`);
+    }
+    return;
   }
 }
-function cmpSemver(a, b) {
-  const norm = (s) => s.replace(/^v/, "").split("-")[0].split(".").map((n) => parseInt(n, 10) || 0);
-  const pa = norm(a);
-  const pb = norm(b);
-  for (let i = 0;i < 3; i++) {
-    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
-    if (d !== 0)
-      return d > 0 ? 1 : -1;
-  }
-  return 0;
-}
-
-// src/commands/doctor.ts
-function registerDoctor(program2) {
-  program2.command("doctor").description("体检：配置 / 云端连通 / 剪映目录 / 运行时是否就绪").action(async () => {
-    await runDoctor();
-  });
-}
-var MARK = { ok: "✅", warn: "⚠️ ", fail: "❌" };
-async function runDoctor() {
-  const rows = [];
-  const latestP = latestVersion(5000).catch(() => null);
-  const bunVer = process.versions.bun;
-  rows.push({
-    name: "运行时",
-    status: "ok",
-    detail: bunVer ? `bun ${bunVer}` : `node ${process.version}`
-  });
-  const uc = readUserConfig();
-  const apiKey = (process.env.GITRUCK_API_KEY ?? uc.apiKey ?? "").trim();
-  const apiBase = (process.env.GITRUCK_API_BASE ?? uc.apiBase ?? DEFAULT_API_BASE).trim().replace(/\/+$/, "");
-  rows.push({
-    name: "API Key",
-    status: apiKey ? "ok" : "fail",
-    detail: apiKey ? `已配（${apiKey.slice(0, 6)}…，来源 ${process.env.GITRUCK_API_KEY ? "环境变量" : "gtrk init"}）` : "未配 —— 跑 gtrk init"
-  });
-  rows.push({ name: "API 根地址", status: "ok", detail: apiBase });
-  let apiStatus = "warn";
-  let apiDetail = "跳过（未配 Key）";
-  if (apiKey) {
-    try {
-      const res = await fetch(`${apiBase}/user/get_user_info`, {
-        method: "POST",
-        headers: { accept: "application/json", Authorization: apiKey },
-        body: "",
-        signal: AbortSignal.timeout(8000)
-      });
-      const data = await res.json().catch(() => ({}));
-      if (data.code === 200) {
-        apiStatus = "ok";
-        apiDetail = "可达，鉴权通过";
-      } else {
-        apiStatus = "fail";
-        apiDetail = `可达，但鉴权失败（code=${data.code ?? res.status}${data.msg ? `，${data.msg}` : ""}）—— 检查 API Key`;
-      }
-    } catch (e) {
-      apiStatus = "fail";
-      apiDetail = `连不上：${e instanceof Error ? e.message : String(e)}`;
-    }
-  }
-  rows.push({ name: "云端连通 + 鉴权", status: apiStatus, detail: apiDetail });
-  const draftDir = resolveJianyingDraftDir(undefined);
-  const draftOk = !!draftDir && existsSync6(draftDir);
-  rows.push({
-    name: "剪映草稿目录",
-    status: draftOk ? "ok" : "warn",
-    detail: draftOk ? draftDir : "未配/未探到 —— 要剪映直开就跑 gtrk init 或加 --jianying-draft-dir"
-  });
-  rows.push({
-    name: "配置文件",
-    status: existsSync6(configPath()) ? "ok" : "warn",
-    detail: existsSync6(configPath()) ? configPath() : `未生成 —— 跑 gtrk init（${configPath()}）`
-  });
-  const ff = resolveFfmpeg();
-  if (ff) {
-    let hasX264 = false;
-    let ver = "";
-    try {
-      const cap = probeCapabilities(ff);
-      hasX264 = cap.hasLibx264;
-      ver = cap.version.replace(/^ffmpeg version\s*/i, "v");
-    } catch {}
-    rows.push({
-      name: "本地渲染 (ffmpeg)",
-      status: hasX264 ? "ok" : "warn",
-      detail: hasX264 ? `就绪（来源 ${ff.source}${ver ? `，${ver.split(/\s/)[0]}` : ""}）` : `找到 ffmpeg（${ff.source}）但缺 libx264 —— 本地渲染需换含 libx264 的构建`
-    });
-  } else {
-    rows.push({
-      name: "本地渲染 (ffmpeg)",
-      status: "warn",
-      detail: "未找到 —— 只出工程文件可忽略；要本地渲染成片，让 agent 装 ffmpeg/ffprobe 到 ~/.gitruck/ffmpeg 或 --ffmpeg-path"
-    });
-  }
-  const cur = currentVersion();
-  const latest = await latestP;
-  rows.splice(1, 0, {
-    name: "CLI 版本",
-    status: latest && cmpSemver(latest, cur) > 0 ? "warn" : "ok",
-    detail: latest && cmpSemver(latest, cur) > 0 ? `v${cur} —— 有新版 v${latest}，跑 gtrk upgrade 升级` : latest ? `v${cur}（已是最新）` : `v${cur}`
-  });
-  console.log(`
-gtrk 体检：
-`);
-  for (const r of rows)
-    console.log(`  ${MARK[r.status]} ${r.name}：${r.detail}`);
-  const failed = rows.some((r) => r.status === "fail");
-  console.log(failed ? `
-有项不通，按提示处理后再开剪。
-` : `
-一切就绪，可以开剪。
-`);
-  if (failed)
-    process.exitCode = 1;
-  return !failed;
-}
-
-// src/commands/init.ts
-var GUIDE_IMAGE = join7(packageRoot(), "assets", "jianying-draft-path.png");
-function registerInit(program2) {
-  program2.command("init").description("一次性配置：API Key + 剪映草稿目录（之后所有命令免重复配置）").option("--api-key <key>", "非交互：直接指定 API Key").option("--api-base <url>", "非交互：指定 API 根地址（缺省用默认生产地址）").option("--jianying-draft-dir <dir>", "非交互：剪映草稿目录（传 auto 则自动探测）").option("--reconfigure", "重走配置向导（默认：已配过则跳过、保留现有配置）").option("-y, --yes", "非交互：用传入值 + 自动探测，不弹任何提示").action(runInit);
-}
-async function runInit(opts) {
-  if (opts.yes || opts.apiKey)
-    return runInitNonInteractive(opts);
-  if (!process.stdin.isTTY) {
-    log.err("交互式 init 需要真实终端；脚本/agent 请用：gtrk init --api-key <KEY> -y");
-    process.exitCode = 1;
+function validateAux(tag, raw, idIndex, errors, warnings) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    errors.push(`${tag}：辅助层必须是对象`);
     return;
   }
-  const existing = readUserConfig();
-  const configured = !!existing.apiKey;
-  log.step("▶ gtrk 安装配置");
-  if (configured && !opts.reconfigure) {
-    log.info(`检测到已有配置：API Key ${mask(existing.apiKey)}｜根地址 ${existing.apiBase ?? DEFAULT_API_BASE}｜剪映目录 ${existing.jianyingDraftDir ?? "未配"}`);
-    if (await promptConfirm("保留现有配置、跳过重填？（要改配置选 N）", true)) {
-      log.info("已保留现有配置（要改配置随时跑 gtrk init --reconfigure）。");
-      return afterConfigDoctor();
-    }
-    log.info("好，重新配置——各项可直接回车沿用现有值。");
-  }
-  let apiKey = existing.apiKey ?? "";
-  const keyMsg = apiKey ? `粘贴新的 API Key，或直接回车沿用现有（${mask(apiKey)}）：` : "粘贴同合云 API Key（Ctrl+V 粘贴）：";
-  for (;; ) {
-    const entered = (await promptSecret(keyMsg)).trim();
-    if (entered) {
-      apiKey = entered;
-      break;
+  const a = raw;
+  if (!enumOk(a.type, AUX_TYPES))
+    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 (apiKey)
-      break;
-    log.warn("API Key 不能为空，再来一次");
-  }
-  const apiBase = (await promptText("云端 API 根地址（回车用默认）：", {
-    defaultValue: existing.apiBase ?? DEFAULT_API_BASE
-  })).trim();
-  let jianyingDraftDir;
-  if (existing.jianyingDraftDir && existsSync7(existing.jianyingDraftDir)) {
-    if (await promptConfirm(`剪映草稿目录现为 ${existing.jianyingDraftDir}，保留吗？`, true)) {
-      jianyingDraftDir = existing.jianyingDraftDir;
+    if (handoff && handoff.category !== undefined && !isKnownCategory(handoff.category)) {
+      warnings.push(`${tag}：handoff.category「${String(handoff.category)}」非已知品类（${MG_CATEGORIES.join("/")}），已透传但下游按 opaque 反推`);
     }
   }
-  if (!jianyingDraftDir) {
-    const probed = probeJianyingDraftDir();
-    if (probed && await promptConfirm(`自动找到剪映草稿目录：${probed}，用它吗？`, true)) {
-      jianyingDraftDir = probed;
+  const m = a.mount;
+  if (m === "same_beat")
+    return;
+  if (typeof m === "object" && m !== null) {
+    const mo = m;
+    if (isNonEmptyStr(mo.trigger)) {
+      if (!idIndex.has(mo.trigger))
+        errors.push(`${tag}：mount.trigger 引用了不存在的 utterance id ${mo.trigger}`);
+      return;
     }
-  }
-  if (!jianyingDraftDir) {
-    log.info("没自动找到（或你选了手动）。已打开一张指引图：剪映 → 全局设置 → 草稿 →「草稿位置」，把那一行路径复制过来；留空则跳过（剪映只产 draft_content.json、缺 meta、需手动导入）。");
-    openFile(GUIDE_IMAGE);
-    const manual = (await promptText("剪映草稿根目录（…\\com.lveditor.draft），留空跳过：")).trim();
-    if (manual) {
-      if (existsSync7(manual))
-        jianyingDraftDir = resolve2(manual);
-      else
-        log.warn(`目录不存在，已跳过：${manual}`);
+    if (isNonEmptyStr(mo.from) && isNonEmptyStr(mo.to)) {
+      if (!idIndex.has(mo.from))
+        errors.push(`${tag}：mount.from 引用了不存在的 utterance id ${mo.from}`);
+      if (!idIndex.has(mo.to))
+        errors.push(`${tag}：mount.to 引用了不存在的 utterance id ${mo.to}`);
+      if (idIndex.has(mo.from) && idIndex.has(mo.to) && idIndex.get(mo.from) > idIndex.get(mo.to)) {
+        errors.push(`${tag}：mount 区间倒序`);
+      }
+      return;
     }
   }
-  const patch = { apiKey, apiBase };
-  if (jianyingDraftDir)
-    patch.jianyingDraftDir = jianyingDraftDir;
-  writeUserConfig(patch);
-  log.ok(`配置已写入 ${configPath()}`);
-  if (!jianyingDraftDir) {
-    log.warn("未配剪映草稿目录：要剪映直接打开，之后可重跑 gtrk init，或单次加 --jianying-draft-dir");
-  }
-  return afterConfigDoctor();
+  errors.push(`${tag}：mount 非法（应为 "same_beat" | {from,to} | {trigger}）`);
 }
-function mask(key) {
-  return `${key.slice(0, 6)}…`;
+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);
 }
-async function afterConfigDoctor() {
-  const healthy = await runDoctor();
-  if (healthy) {
-    log.step("装好了！两种用法任选：");
-    log.info('① 命令行直接剪：gtrk oralcut "<毛片.mp4>" --script "<文字稿.txt>"（无稿就别加 --script）');
-    log.info("② 重启你常用的 AI agent（Claude / Codex / Trae / WorkBuddy 等），用 /gtrk-oralcut <你的口播剪辑需求>，一句话交给它，体验更智能的剪辑~");
-  } else {
-    log.warn("上面体检有项没通，按提示处理好再开剪（多半是 API Key 或剪映目录）。");
-  }
+function r3(n) {
+  return Math.round(n * 1000) / 1000;
 }
-async function runInitNonInteractive(opts) {
-  const existing = readUserConfig();
-  const apiKey = (opts.apiKey ?? existing.apiKey ?? "").trim();
-  if (!apiKey) {
-    log.err("非交互模式需要 --api-key（或改用交互式 gtrk init）");
-    process.exitCode = 1;
-    return;
+function buildLanding(doc, view, opts) {
+  const byId = new Map;
+  for (const id of opts.utteranceIds)
+    byId.set(id, []);
+  for (const u of view.utterances) {
+    if (u.dropped || u.track_st == null || u.track_ed == null)
+      continue;
+    if (!byId.has(u.id))
+      byId.set(u.id, []);
+    byId.get(u.id).push({ track_st: u.track_st, track_ed: u.track_ed });
   }
-  const apiBase = (opts.apiBase ?? existing.apiBase ?? DEFAULT_API_BASE).trim();
-  let jianyingDraftDir;
-  const dirOpt = opts.jianyingDraftDir;
-  if (dirOpt && dirOpt !== "auto")
-    jianyingDraftDir = resolve2(dirOpt);
-  else if (dirOpt === "auto" || !existing.jianyingDraftDir)
-    jianyingDraftDir = probeJianyingDraftDir();
-  else
-    jianyingDraftDir = existing.jianyingDraftDir;
-  const patch = { apiKey, apiBase };
-  if (jianyingDraftDir)
-    patch.jianyingDraftDir = jianyingDraftDir;
-  writeUserConfig(patch);
-  log.ok(`配置已写入 ${configPath()}`);
-  log.info(`剪映草稿目录：${jianyingDraftDir ?? "未配（剪映需手动导入，可加 --jianying-draft-dir）"}`);
-  await runDoctor();
-}
-
-// src/commands/install.ts
-function registerInstall(program2) {
-  program2.command("install").description("一条命令装全：安装 /gtrk-oralcut skill + 配置（对标飞书 lark-cli install）").option("--api-key <key>", "非交互：直接指定 API Key").option("--api-base <url>", "非交互：指定 API 根地址").option("--jianying-draft-dir <dir>", "非交互：剪映草稿目录（传 auto 则自动探测）").option("--skills-dir <dir>", "自定义 skills 目录（缺省 ~/.claude/skills）").option("--reconfigure", "重走配置向导（默认：已配过则保留现有配置、只刷新 skill）").option("-y, --yes", "非交互：用传入值 + 自动探测，不弹任何提示").action(async (opts) => {
-    log.step("① 安装 / 刷新 agent skill…");
-    installSkill({ dir: opts.skillsDir });
-    log.step("② 配置 + 体检…");
-    await runInit(opts);
-  });
+  const idIndex = new Map;
+  opts.utteranceIds.forEach((id, i) => idIndex.set(id, i));
+  const split = {
+    contract_version: doc.contract_version,
+    transcript_hash: doc.transcript_hash,
+    projected_at: opts.projectedAt,
+    ...opts.sourceIndex ? { material_id: opts.sourceIndex.materialId } : {},
+    beats: []
+  };
+  const dispatch = { mg: [], film_broll: [], ai_drama: [] };
+  const skipped = [];
+  const shrunk = [];
+  const unhandledLanes = new Set;
+  for (const beat of doc.beats) {
+    const fromIdx = idIndex.get(beat.span.from);
+    const toIdx = idIndex.get(beat.span.to);
+    const spanIds = opts.utteranceIds.slice(fromIdx, toIdx + 1);
+    const instances = spanIds.flatMap((id) => byId.get(id) ?? []);
+    const droppedCount = spanIds.filter((id) => (byId.get(id)?.length ?? 0) === 0).length;
+    if (instances.length === 0) {
+      skipped.push({ beat: beat.id, reason: "span 内全部 utterance 被剪，未落轨" });
+      continue;
+    }
+    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 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);
+      if (from && to && to.ed > from.st) {
+        metaBeat.source_ranges = [{ st: r3(from.st), ed: r3(to.ed) }];
+      }
+    }
+    if (isShrunk)
+      metaBeat.shrunk = true;
+    if (beat.narrative)
+      metaBeat.narrative = beat.narrative;
+    if (beat.container_stage)
+      metaBeat.container_stage = beat.container_stage;
+    if (beat.visual_task)
+      metaBeat.visual_task = beat.visual_task;
+    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) {
+      shrunk.push({ beat: beat.id, kept: spanIds.length - droppedCount, dropped: droppedCount, track_st, track_ed });
+    }
+    const h = beat.handoff ?? {};
+    const compositionId = `${opts.projectSlug}-${beat.id}`;
+    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 (lane === "FILM_BROLL") {
+      dispatch.film_broll.push({
+        beat: beat.id,
+        queries: Array.isArray(h.queries) ? h.queries : [],
+        shots: h.shots,
+        per_shot_sec: h.per_shot_sec,
+        exclude: h.exclude,
+        track_st,
+        track_ed
+      });
+    } else if (lane === "AI_DRAMA") {
+      dispatch.ai_drama.push({ beat: beat.id, ...h, track_st, track_ed });
+    } 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] };
 }
-
-// src/commands/oralcut.ts
-import { resolve as resolve3, join as join12, dirname as dirname2, basename as basename5, extname as extname2 } from "node:path";
-import { mkdir as mkdir4, writeFile as writeFile5, readFile as readFile3 } from "node:fs/promises";
-import { existsSync as existsSync11 } from "node:fs";
-
-// src/lib/config.ts
-function loadConfig() {
-  const uc = readUserConfig();
-  const apiKey = (process.env.GITRUCK_API_KEY ?? uc.apiKey ?? "").trim();
-  const base = (process.env.GITRUCK_API_BASE ?? uc.apiBase ?? DEFAULT_API_BASE).trim().replace(/\/+$/, "");
-  if (!apiKey) {
-    throw new Error("缺 API Key —— 先跑 `gtrk init` 配置（或设环境变量 GITRUCK_API_KEY）");
+function renderSplitMarkdown(doc, landing, meta) {
+  const L = [];
+  const metaById = new Map(landing.split.beats.map((b) => [b.id, b]));
+  const skippedIds = new Set(landing.skipped.map((s) => s.beat));
+  L.push(`# 视觉拆分稿（${meta.projectSlug}）`);
+  L.push("");
+  L.push(`- contract_version：\`${doc.contract_version}\``);
+  L.push(`- transcript_hash：\`${doc.transcript_hash}\``);
+  L.push(`- projected_at：\`${meta.projectedAt}\``);
+  L.push(`- beats：${doc.beats.length}（落轨 ${landing.split.beats.length} · 跳过 ${landing.skipped.length} · 收缩 ${landing.shrunk.length}）`);
+  L.push("");
+  L.push("# Beat Timeline");
+  L.push("");
+  for (const beat of doc.beats) {
+    const mb = metaById.get(beat.id);
+    L.push(`## ${beat.id}${skippedIds.has(beat.id) ? "（整段被剪 · 跳过）" : mb?.shrunk ? "（部分被剪 · 已收缩）" : ""}`);
+    L.push(`- 文稿范围：\`${beat.span.from} … ${beat.span.to}\``);
+    L.push(`- 底轨：\`${beat.base_track}\``);
+    L.push(`- 主层：\`${beat.lane}\``);
+    L.push(`- 叙事功能：\`${beat.narrative}\``);
+    L.push(`- 容器阶段：\`${beat.container_stage}\``);
+    if (beat.rhythm)
+      L.push(`- 节奏标签：\`${beat.rhythm}\``);
+    L.push(`- 视觉任务：${beat.visual_task}`);
+    L.push(`- 不可替代性：\`${beat.irreplaceability}\``);
+    if (mb)
+      L.push(`- 轨道时码：\`${mb.track_st}s … ${mb.track_ed}s\``);
+    if (beat.callback_of)
+      L.push(`- 回扣对象：\`${beat.callback_of}\``);
+    for (const a of beat.aux_layers ?? []) {
+      const mount = a.mount === "same_beat" ? "同 beat" : ("trigger" in a.mount) ? `触发 ${a.mount.trigger}` : `${a.mount.from} … ${a.mount.to}`;
+      L.push(`  - 辅助层 \`${a.type}\`（${mount}）：${a.role}`);
+    }
+    L.push("");
   }
-  return { base, apiKey };
+  L.push("# Production Queues");
+  L.push("");
+  L.push("## A_ROLL Queue");
+  for (const b of doc.beats.filter((x) => x.lane === "A_ROLL" && !skippedIds.has(x.id))) {
+    L.push(`- \`${b.id}\` ${b.visual_task}`);
+  }
+  L.push("");
+  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("");
+  L.push("## AI_DRAMA Queue");
+  for (const a of landing.dispatch.ai_drama)
+    L.push(`- \`${a.beat}\` ${a.track_st}s…${a.track_ed}s`);
+  L.push("");
+  L.push("## FILM_BROLL Queue");
+  for (const f of landing.dispatch.film_broll)
+    L.push(`- \`${f.beat}\` queries=[${f.queries.join(" / ")}]`);
+  L.push("");
+  return L.join(`
+`);
 }
 
-// src/lib/cloud.ts
-import { basename } from "node:path";
-import { writeFile, stat } from "node:fs/promises";
-import { createReadStream } from "node:fs";
-import { Readable } from "node:stream";
-import { randomBytes } from "node:crypto";
-
-class CloudError extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-    this.name = "CloudError";
+// src/lib/column-config.ts
+var DEFAULT_COLUMN_CONFIG = {
+  meta: { id: "real-roam-guide", name: "实在界漫游指南（内置默认）" },
+  vocab: {
+    narrative: [...NARRATIVES],
+    container_stage: [...CONTAINER_STAGES],
+    base_track: [...BASE_TRACKS]
+  },
+  lanes: { enabled: [...LANES] },
+  fallback: { unknown_narrative: "reject" }
+};
+function columnsDir() {
+  return join5(gitruckHome(), "columns");
+}
+var uniq = (xs) => [...new Set(xs)];
+function strArr(v) {
+  if (!Array.isArray(v))
+    return;
+  return v.filter((x) => typeof x === "string");
+}
+function foldColumnConfigs(layers) {
+  const out = {};
+  for (const l of layers) {
+    if (!l || typeof l !== "object" || Array.isArray(l))
+      continue;
+    if (l.meta && typeof l.meta === "object")
+      out.meta = { ...out.meta, ...l.meta };
+    if (l.vocab && typeof l.vocab === "object") {
+      out.vocab ??= {};
+      for (const k of ["narrative", "container_stage", "base_track"]) {
+        const add = strArr(l.vocab[k]);
+        if (add)
+          out.vocab[k] = uniq([...out.vocab[k] ?? [], ...add]);
+      }
+    }
+    if (l.lanes && typeof l.lanes === "object") {
+      out.lanes ??= {};
+      const en = strArr(l.lanes.enabled);
+      if (en)
+        out.lanes.enabled = uniq([...out.lanes.enabled ?? [], ...en]);
+      if (l.lanes.appearance && typeof l.lanes.appearance === "object") {
+        out.lanes.appearance = l.lanes.appearance;
+      }
+    }
+    if (l.broll && typeof l.broll === "object") {
+      out.broll ??= {};
+      const tags = strArr(l.broll.column_tag_ids);
+      if (tags)
+        out.broll.column_tag_ids = uniq([...out.broll.column_tag_ids ?? [], ...tags]);
+      const fa = strArr(l.broll.facet_allowed);
+      if (fa) {
+        out.broll.facet_allowed = out.broll.facet_allowed ? out.broll.facet_allowed.filter((x) => fa.includes(x)) : [...fa];
+      }
+      if (typeof l.broll.material_class_policy === "string")
+        out.broll.material_class_policy = l.broll.material_class_policy;
+      if (l.broll.facet_defaults && typeof l.broll.facet_defaults === "object")
+        out.broll.facet_defaults = l.broll.facet_defaults;
+    }
+    if (l.style !== undefined)
+      out.style = l.style;
+    if (l.fallback && typeof l.fallback === "object") {
+      const un = l.fallback.unknown_narrative;
+      if (un === "allow" || un === "reject")
+        out.fallback = { unknown_narrative: un };
+    }
   }
+  return out;
 }
-async function parseJson(res) {
+function readLocalColumn(columnId, dir, warnings) {
+  const p = join5(dir, `${columnId}.json`);
+  if (!existsSync5(p)) {
+    warnings.push(`栏目配置不存在：${p}，回落内置默认`);
+    return;
+  }
   try {
-    return await res.json();
+    const parsed = JSON.parse(readFileSync2(p, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      warnings.push(`栏目配置格式异常（非 JSON 对象）：${p}，回落内置默认`);
+      return;
+    }
+    return parsed;
   } catch {
-    throw new Error(`服务响应解析失败 (HTTP ${res.status})`);
+    warnings.push(`栏目配置损坏（JSON 解析失败）：${p}，回落内置默认`);
+    return;
   }
 }
-async function uploadFile(cfg, path) {
-  const size = (await stat(path)).size;
-  const boundary = `----gtrkFormBoundary${randomBytes(16).toString("hex")}`;
-  const head = Buffer.from(`--${boundary}\r
-` + `Content-Disposition: form-data; name="file"; filename="${basename(path)}"\r
-` + `Content-Type: application/octet-stream\r
-\r
-`, "utf8");
-  const tail = Buffer.from(`\r
---${boundary}--\r
-`, "utf8");
-  async function* multipart() {
-    yield head;
-    for await (const chunk of createReadStream(path))
-      yield chunk;
-    yield tail;
+function resolveColumnConfig(opts = {}) {
+  const warnings = [];
+  const layers = [DEFAULT_COLUMN_CONFIG];
+  if (opts.columnId) {
+    const l2 = readLocalColumn(opts.columnId, opts.columnsDir ?? columnsDir(), warnings);
+    if (l2)
+      layers.push(l2);
   }
-  const res = await fetch(`${cfg.base}/base/file/upload`, {
-    method: "POST",
-    headers: {
-      Authorization: cfg.apiKey,
-      "Content-Type": `multipart/form-data; boundary=${boundary}`,
-      "Content-Length": String(head.length + size + tail.length)
-    },
-    body: Readable.toWeb(Readable.from(multipart())),
-    duplex: "half"
-  });
-  const r = await parseJson(res);
-  const fid = r.data?.file_id ?? r.data?.id;
-  if (r.code === 200 && fid)
-    return String(fid);
-  throw new Error(`上传失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
+  const config = foldColumnConfigs(layers);
+  config.style = normalizeColumnStyle(config.style, warnings);
+  for (const n of producesNotices(config.style))
+    warnings.push(n);
+  return { config, warnings };
 }
-async function submitTask(cfg, taskType, payload) {
-  const res = await fetch(`${cfg.base}/task/${taskType}`, {
-    method: "POST",
-    headers: { Authorization: cfg.apiKey, "Content-Type": "application/json" },
-    body: JSON.stringify(payload)
-  });
-  const r = await parseJson(res);
-  if (r.code === 200 && r.data?.task_id)
-    return String(r.data.task_id);
-  throw new Error(`提交失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
+var HANDOFF_REGISTRY = LANES;
+var LEGACY_HANDOFF_ALIASES = { RRV_MG: "MG" };
+function normalizeHandoffType(v) {
+  return LEGACY_HANDOFF_ALIASES[v] ?? v;
 }
-async function getTaskResult(cfg, taskType, taskId) {
-  const res = await fetch(`${cfg.base}/task/${taskType}/${taskId}`, {
-    headers: { Authorization: cfg.apiKey }
-  });
-  const r = await parseJson(res);
-  if (r.code != null && r.code !== 200) {
-    throw new CloudError(r.code, `任务查询失败 (code=${r.code})：${r.msg ?? ""}`);
-  }
-  const data = r.data ?? {};
-  return {
-    status: String(data.status ?? ""),
-    progress: typeof data.progress === "number" ? data.progress : undefined,
-    output: data.output_result ?? {}
-  };
+function isRegisteredHandoff(v) {
+  return HANDOFF_REGISTRY.includes(normalizeHandoffType(v));
 }
-async function pollTask(cfg, taskType, taskId, onTick) {
-  const start = Date.now();
-  const TIMEOUT_MS = 30 * 60 * 1000;
-  const INTERVAL_MS = 5000;
-  for (;; ) {
-    if (Date.now() - start > TIMEOUT_MS) {
-      throw new Error("任务超时（超过 30 分钟）。可稍后在云端查任务或重试。");
-    }
-    await new Promise((r) => setTimeout(r, INTERVAL_MS));
-    let got;
-    try {
-      got = await getTaskResult(cfg, taskType, taskId);
-    } catch (e) {
-      if (e instanceof CloudError)
-        throw e;
-      continue;
+function normalizeEntries(list, kind, warnings) {
+  if (list === undefined)
+    return;
+  if (!Array.isArray(list)) {
+    warnings.push(`style.${kind} 非数组，已忽略`);
+    return;
+  }
+  const out = [];
+  list.forEach((e, i) => {
+    if (typeof e !== "object" || e === null || Array.isArray(e)) {
+      warnings.push(`style.${kind}[${i}] 非对象，已跳过`);
+      return;
     }
-    if (got.status === "completed")
-      return got.output;
-    if (got.status === "failed" || got.status === "cancelled") {
-      const out = got.output;
-      throw new Error(out?.error ?? (got.status === "failed" ? "任务失败" : "任务已取消"));
+    const o = e;
+    if (typeof o.id !== "string" || typeof o.ref !== "string" || !o.id || !o.ref) {
+      warnings.push(`style.${kind}[${i}] 缺 id/ref，已跳过`);
+      return;
     }
-    onTick?.(got.status || "处理中", got.progress);
+    out.push(e);
+  });
+  return out;
+}
+function normalizeColumnStyle(raw, warnings) {
+  if (raw === undefined)
+    return;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    warnings.push("style 块非对象，已忽略");
+    return;
   }
+  const r = raw;
+  const style = {};
+  const skills = normalizeEntries(r.skills, "skills", warnings);
+  if (skills)
+    style.skills = skills;
+  const shared = normalizeEntries(r.shared, "shared", warnings);
+  if (shared)
+    style.shared = shared;
+  if (typeof r.bundle_ref === "string")
+    style.bundle_ref = r.bundle_ref;
+  return style;
 }
-async function download(url, dest) {
-  const res = await fetch(url);
-  if (!res.ok)
-    throw new Error(`下载失败 HTTP ${res.status}：${url}`);
-  const buf = Buffer.from(await res.arrayBuffer());
-  await writeFile(dest, buf);
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0)
+    return n;
+  if (n === 0)
+    return m;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1;i <= m; i++) {
+    const cur = [i];
+    for (let j = 1;j <= n; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[n];
 }
-
-// src/lib/upload-cache.ts
-import { join as join8 } from "node:path";
-import { stat as stat3, mkdir, readFile, writeFile as writeFile2 } from "node:fs/promises";
-import { existsSync as existsSync8 } from "node:fs";
-
-// src/lib/chunk-upload.ts
-var import_hash_wasm = __toESM(require_index_umd(), 1);
-import { open, stat as stat2 } from "node:fs/promises";
-import { basename as basename2 } from "node:path";
-var CHUNK_THRESHOLD = 256 * 1024 * 1024;
-var CONCURRENCY = 3;
-var PART_RETRIES = 3;
-var BACKOFF_MS = [2000, 4000, 8000];
-var INCOMPLETE_ROUNDS = 2;
-var MAX_REBUILDS = 1;
-var CODE_SESSION_NOT_FOUND = 6024;
-var CODE_PART_INVALID = 6025;
-var CODE_CHECKSUM_MISMATCH = 6026;
-var CODE_INCOMPLETE = 6027;
-var FP_BUFFER = 8192;
-var FP_SKIP = 64 * 1024 * 1024;
-async function fastBlake3(path) {
-  try {
-    const hasher = await import_hash_wasm.createBLAKE3();
-    hasher.init();
-    const fh = await open(path, "r");
-    try {
-      const buf = Buffer.alloc(FP_BUFFER);
-      let count = 0;
-      let pos = 0;
-      for (;; ) {
-        const { bytesRead } = await fh.read(buf, 0, FP_BUFFER, pos);
-        if (bytesRead === 0)
-          break;
-        count += FP_BUFFER;
-        if (count >= FP_SKIP)
-          break;
-        hasher.update(buf.subarray(0, bytesRead));
-        pos += bytesRead;
+function producesValues(e) {
+  if (typeof e.produces === "string")
+    return [e.produces];
+  if (Array.isArray(e.produces))
+    return e.produces.filter((x) => typeof x === "string");
+  return [];
+}
+function producesNotices(style) {
+  const notices = [];
+  if (!style?.skills)
+    return notices;
+  const seen = new Set;
+  for (const e of style.skills) {
+    if (e.routing === "none")
+      continue;
+    for (const v of producesValues(e)) {
+      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) {
+        seen.add(v);
+        notices.push(`style.skills[${e.id}].produces="${v}" 疑似拼写（接近注册类型 "${near}"）；如确为管线外产物可设 routing:"none"`);
       }
-      return hasher.digest("hex");
-    } finally {
-      await fh.close();
     }
-  } catch {
-    return;
   }
+  return notices;
 }
-async function partBlake3(view) {
-  const hasher = await import_hash_wasm.createBLAKE3();
-  hasher.init();
-  hasher.update(view);
-  return hasher.digest("hex");
+function effectiveVocab(config) {
+  return {
+    narrative: config.vocab?.narrative ?? [...NARRATIVES],
+    container_stage: config.vocab?.container_stage ?? [...CONTAINER_STAGES],
+    base_track: config.vocab?.base_track ?? [...BASE_TRACKS],
+    unknown_narrative: config.fallback?.unknown_narrative
+  };
 }
 
-class SessionGoneError extends Error {
-  constructor() {
-    super("分片会话已失效");
-    this.name = "SessionGoneError";
+// src/lib/ffmpeg.ts
+import { spawn as spawn2, spawnSync as spawnSync2 } from "node:child_process";
+import { existsSync as existsSync6 } from "node:fs";
+import { join as join6 } from "node:path";
+var isWin = process.platform === "win32";
+var bin = (base) => isWin ? `${base}.exe` : base;
+var FFMPEG_INSTALL_HINT = `未找到 ffmpeg/ffprobe。请把二者放到 ${ffmpegDir()}（agent 可代办：先查本地确实缺失才拉，` + `面向国内用户优先国内加速站点——GitHub 代理 pass-through 拉 BtbN/gyan.dev 官方静态构建，或同合云自建镜像，` + `并做 sha256 校验），或用 --ffmpeg-path <目录> 指定已装位置。`;
+var _cache = new Map;
+function onSystemPath(cmd) {
+  try {
+    return spawnSync2(cmd, ["-version"], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
   }
 }
-function isTransient(e) {
-  const msg = String(e?.message ?? e);
-  return /fetch failed|ECONNRESET|ETIMEDOUT|EPIPE|UND_ERR|服务响应解析失败 \(HTTP 5/i.test(msg);
+function resolveFfmpeg(ffmpegPath) {
+  const key = ffmpegPath ?? "";
+  if (_cache.has(key))
+    return _cache.get(key) ?? null;
+  const dirs = [];
+  if (ffmpegPath)
+    dirs.push([ffmpegPath, ffmpegPath]);
+  dirs.push([ffmpegDir(), "~/.gitruck/ffmpeg"]);
+  let found = null;
+  for (const [dir, label] of dirs) {
+    const ff = join6(dir, bin("ffmpeg"));
+    const fp = join6(dir, bin("ffprobe"));
+    if (existsSync6(ff) && existsSync6(fp)) {
+      found = { ffmpeg: ff, ffprobe: fp, source: label };
+      break;
+    }
+  }
+  if (!found && onSystemPath("ffmpeg") && onSystemPath("ffprobe")) {
+    found = { ffmpeg: "ffmpeg", ffprobe: "ffprobe", source: "system" };
+  }
+  _cache.set(key, found);
+  return found;
 }
-async function sleep(ms) {
-  await new Promise((r) => setTimeout(r, ms));
+function requireFfmpeg(ffmpegPath) {
+  const r = resolveFfmpeg(ffmpegPath);
+  if (!r)
+    throw new Error(FFMPEG_INSTALL_HINT);
+  return r;
 }
-async function uploadChunked(cfg, path, opts) {
-  const size = (await stat2(path)).size;
-  const name = basename2(path);
-  for (let rebuilds = 0;; rebuilds++) {
-    try {
-      return await attemptOnce(cfg, path, name, size, opts);
-    } catch (e) {
-      if (e instanceof SessionGoneError && rebuilds < MAX_REBUILDS) {
-        await opts.store.clear(opts.fingerprint);
-        log.warn("云端分片会话已失效，自动重建整传一次");
-        continue;
-      }
-      throw e;
-    }
+function ffprobeJson(ffprobePath, args) {
+  const r = spawnSync2(ffprobePath, args, { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+  if (r.status !== 0) {
+    throw new Error(`ffprobe 失败（code=${r.status}）：${(r.stderr || "").slice(-300)}`);
   }
+  return JSON.parse(r.stdout || "{}");
 }
-async function attemptOnce(cfg, path, name, size, opts) {
-  const { fingerprint, store, force } = opts;
-  let session = force ? undefined : await store.load(fingerprint);
-  let missing;
-  if (session) {
-    const st = await chunkStatus(cfg, session.uploadId);
-    if (st === undefined) {
-      await store.clear(fingerprint);
-      session = undefined;
-    } else {
-      session = { ...session, partSize: st.part_size, totalParts: st.total_parts };
-      missing = st.missing;
-      if (missing.length < session.totalParts) {
-        log.info(`断点续传：云端已有 ${session.totalParts - missing.length}/${session.totalParts} 片，补 ${missing.length} 片`);
+function runFfmpeg(ffmpegPath, args, onLine) {
+  return new Promise((resolve2, reject) => {
+    const p = spawn2(ffmpegPath, args, { env: process.env });
+    let tail = "";
+    p.stderr.on("data", (buf) => {
+      const s = buf.toString("utf8");
+      tail = (tail + s).slice(-4000);
+      if (onLine) {
+        for (const ln of s.split(/\r?\n/))
+          if (ln)
+            onLine(ln);
       }
-    }
-  }
-  if (!session) {
-    const blake3Id = force ? undefined : await fastBlake3(path);
-    const body = { filename: name, size };
-    if (blake3Id)
-      body.blake3_id = blake3Id;
-    const res = await fetch(`${cfg.base}/base/file/upload/chunk/init`, {
-      method: "POST",
-      headers: { Authorization: cfg.apiKey, "Content-Type": "application/json" },
-      body: JSON.stringify(body)
     });
-    const r = await parseJson(res);
-    if (r.code !== 200) {
-      throw new Error(`分片上传 init 失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
-    }
-    if (r.data?.file_id != null) {
-      log.info("秒传命中：云端已有同内容文件，零字节上传");
-      return String(r.data.file_id);
-    }
-    if (r.data?.upload_id == null || !r.data.part_size || !r.data.total_parts) {
-      throw new Error("分片上传 init 响应缺字段（upload_id/part_size/total_parts）");
-    }
-    session = {
-      uploadId: String(r.data.upload_id),
-      partSize: r.data.part_size,
-      totalParts: r.data.total_parts,
-      size,
-      path,
-      createdAt: Date.now()
-    };
-    await store.save(fingerprint, session);
-    missing = undefined;
-  }
-  if (missing === undefined) {
-    missing = Array.from({ length: session.totalParts }, (_, i) => i);
-  }
-  await uploadParts(cfg, path, session, missing);
-  for (let round = 0;; round++) {
-    const res = await fetch(`${cfg.base}/base/file/upload/chunk/${session.uploadId}/complete`, { method: "POST", headers: { Authorization: cfg.apiKey } });
-    const r = await parseJson(res);
-    if (r.code === 200 && r.data?.file_id != null) {
-      await store.clear(fingerprint);
-      return String(r.data.file_id);
-    }
-    if (r.code === CODE_SESSION_NOT_FOUND)
-      throw new SessionGoneError;
-    if (r.code === CODE_INCOMPLETE && round < INCOMPLETE_ROUNDS) {
-      const st = await chunkStatus(cfg, session.uploadId);
-      if (st === undefined)
-        throw new SessionGoneError;
-      await uploadParts(cfg, path, session, st.missing);
-      continue;
-    }
-    throw new Error(`分片上传 complete 失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
-  }
+    p.on("error", (e) => reject(e));
+    p.on("close", (code) => {
+      if (code === 0)
+        resolve2();
+      else
+        reject(new Error(`ffmpeg 退出码 ${code}：${tail.slice(-600)}`));
+    });
+  });
 }
-async function chunkStatus(cfg, uploadId) {
-  const res = await fetch(`${cfg.base}/base/file/upload/chunk/${uploadId}`, {
-    headers: { Authorization: cfg.apiKey }
+function probeCapabilities(res) {
+  const ver = spawnSync2(res.ffmpeg, ["-version"], { encoding: "utf8" });
+  const version = (ver.stdout || "").split(/\r?\n/)[0]?.trim() || "unknown";
+  const enc = spawnSync2(res.ffmpeg, ["-hide_banner", "-encoders"], {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024
   });
-  const r = await parseJson(res);
-  if (r.code === CODE_SESSION_NOT_FOUND)
-    return;
-  if (r.code !== 200 || !r.data) {
-    throw new Error(`分片会话查询失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
+  const fil = spawnSync2(res.ffmpeg, ["-hide_banner", "-filters"], {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024
+  });
+  const encoders = new Set;
+  for (const ln of (enc.stdout || "").split(/\r?\n/)) {
+    const m = ln.trim().match(/^\S+\s+(\S+)/);
+    if (m)
+      encoders.add(m[1]);
   }
-  return r.data;
+  const filters = new Set;
+  for (const ln of (fil.stdout || "").split(/\r?\n/)) {
+    const m = ln.trim().match(/^\S+\s+(\S+)/);
+    if (m)
+      filters.add(m[1]);
+  }
+  return {
+    version,
+    encoders,
+    filters,
+    hasLibx264: encoders.has("libx264"),
+    hasAac: encoders.has("aac"),
+    hasAfade: filters.has("afade"),
+    hasAresample: filters.has("aresample")
+  };
 }
-async function uploadParts(cfg, path, session, indexes) {
-  if (indexes.length === 0)
-    return;
-  const { uploadId, partSize, totalParts, size } = session;
-  let done = totalParts - indexes.length;
-  const fh = await open(path, "r");
+
+// src/lib/version.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import { join as join7 } from "node:path";
+var REGISTRY = "https://registry.npmjs.org/@gitruck%2Fcli";
+function currentVersion() {
   try {
-    const queue = [...indexes];
-    const worker = async () => {
-      const buf = Buffer.alloc(partSize);
-      for (;; ) {
-        const idx = queue.shift();
-        if (idx === undefined)
-          return;
-        const offset = idx * partSize;
-        const len = idx === totalParts - 1 ? size - offset : partSize;
-        const { bytesRead } = await fh.read(buf, 0, len, offset);
-        if (bytesRead !== len) {
-          throw new Error(`本地文件读取不足（第${idx}片期望${len}字节实读${bytesRead}）——文件被改动？`);
-        }
-        const view = buf.subarray(0, len);
-        await putPart(cfg, uploadId, idx, view);
-        done++;
-        log.tick(`分片上传 ${done}/${totalParts}（${Math.round(done / totalParts * 100)}%）`);
-      }
-    };
-    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, indexes.length) }, worker));
-  } finally {
-    log.tickEnd();
-    await fh.close();
+    const { version } = JSON.parse(readFileSync3(join7(packageRoot(), "package.json"), "utf8"));
+    return version;
+  } catch {
+    return "0.0.0";
   }
 }
-async function putPart(cfg, uploadId, idx, view) {
-  const b3 = await partBlake3(view);
-  let lastErr;
-  for (let attempt = 0;attempt <= PART_RETRIES; attempt++) {
-    if (attempt > 0)
-      await sleep(BACKOFF_MS[Math.min(attempt - 1, BACKOFF_MS.length - 1)]);
+async function latestVersion(timeoutMs = 5000) {
+  try {
+    const res = await fetch(REGISTRY, {
+      headers: { accept: "application/vnd.npm.install-v1+json" },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!res.ok)
+      return null;
+    const data = await res.json();
+    return data["dist-tags"]?.latest ?? null;
+  } catch {
+    return null;
+  }
+}
+function cmpSemver(a, b) {
+  const norm = (s) => s.replace(/^v/, "").split("-")[0].split(".").map((n) => parseInt(n, 10) || 0);
+  const pa = norm(a);
+  const pb = norm(b);
+  for (let i = 0;i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0)
+      return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+// src/commands/doctor.ts
+function registerDoctor(program2) {
+  program2.command("doctor").description("体检：配置 / 云端连通 / 剪映目录 / 运行时是否就绪").action(async () => {
+    await runDoctor();
+  });
+}
+var MARK = { ok: "✅", warn: "⚠️ ", fail: "❌" };
+async function runDoctor() {
+  const rows = [];
+  const latestP = latestVersion(5000).catch(() => null);
+  const bunVer = process.versions.bun;
+  rows.push({
+    name: "运行时",
+    status: "ok",
+    detail: bunVer ? `bun ${bunVer}` : `node ${process.version}`
+  });
+  const uc = readUserConfig();
+  const apiKey = (process.env.GITRUCK_API_KEY ?? uc.apiKey ?? "").trim();
+  const apiBase = (process.env.GITRUCK_API_BASE ?? uc.apiBase ?? DEFAULT_API_BASE).trim().replace(/\/+$/, "");
+  rows.push({
+    name: "API Key",
+    status: apiKey ? "ok" : "fail",
+    detail: apiKey ? `已配（${apiKey.slice(0, 6)}…，来源 ${process.env.GITRUCK_API_KEY ? "环境变量" : "gtrk init"}）` : "未配 —— 跑 gtrk init"
+  });
+  rows.push({ name: "API 根地址", status: "ok", detail: apiBase });
+  let apiStatus = "warn";
+  let apiDetail = "跳过（未配 Key）";
+  if (apiKey) {
     try {
-      const res = await fetch(`${cfg.base}/base/file/upload/chunk/${uploadId}/${idx}?blake3=${b3}`, {
-        method: "PUT",
-        headers: { Authorization: cfg.apiKey, "Content-Type": "application/octet-stream" },
-        body: view
+      const res = await fetch(`${apiBase}/user/get_user_info`, {
+        method: "POST",
+        headers: { accept: "application/json", Authorization: apiKey },
+        body: "",
+        signal: AbortSignal.timeout(8000)
       });
-      const r = await parseJson(res);
-      if (r.code === 200)
-        return;
-      if (r.code === CODE_SESSION_NOT_FOUND)
-        throw new SessionGoneError;
-      if (r.code === CODE_CHECKSUM_MISMATCH || r.code === CODE_PART_INVALID) {
-        lastErr = new Error(`第${idx}片被拒 (code=${r.code})：${r.msg ?? ""}`);
-        continue;
+      const data = await res.json().catch(() => ({}));
+      if (data.code === 200) {
+        apiStatus = "ok";
+        apiDetail = "可达，鉴权通过";
+      } else {
+        apiStatus = "fail";
+        apiDetail = `可达，但鉴权失败（code=${data.code ?? res.status}${data.msg ? `，${data.msg}` : ""}）—— 检查 API Key`;
       }
-      throw new Error(`第${idx}片上传失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
     } catch (e) {
-      if (e instanceof SessionGoneError)
-        throw e;
-      if (!isTransient(e))
-        throw e;
-      lastErr = e;
+      apiStatus = "fail";
+      apiDetail = `连不上：${e instanceof Error ? e.message : String(e)}`;
     }
   }
-  throw lastErr instanceof Error ? lastErr : new Error(`第${idx}片重试${PART_RETRIES}次仍失败`);
-}
-
-// src/lib/upload-cache.ts
-var CACHE_DIR = gitruckHome();
-var CACHE_FILE = join8(CACHE_DIR, "upload-cache.json");
-var SESSION_FILE = join8(CACHE_DIR, "upload-sessions.json");
-async function fingerprint(path) {
-  const s = await stat3(path);
-  return `${s.size}:${Math.round(s.mtimeMs)}`;
-}
-async function load() {
-  if (!existsSync8(CACHE_FILE))
-    return {};
-  try {
-    return JSON.parse(await readFile(CACHE_FILE, "utf8"));
-  } catch {
-    return {};
+  rows.push({ name: "云端连通 + 鉴权", status: apiStatus, detail: apiDetail });
+  const draftDir = resolveJianyingDraftDir(undefined);
+  const draftOk = !!draftDir && existsSync7(draftDir);
+  rows.push({
+    name: "剪映草稿目录",
+    status: draftOk ? "ok" : "warn",
+    detail: draftOk ? draftDir : "未配/未探到 —— 要剪映直开就跑 gtrk init 或加 --jianying-draft-dir"
+  });
+  rows.push({
+    name: "配置文件",
+    status: existsSync7(configPath()) ? "ok" : "warn",
+    detail: existsSync7(configPath()) ? configPath() : `未生成 —— 跑 gtrk init（${configPath()}）`
+  });
+  const col = uc.defaultColumn;
+  const colFile = col ? join8(columnsDir(), `${col}.json`) : undefined;
+  rows.push({
+    name: "当前栏目",
+    status: "ok",
+    detail: col ? `${col}${colFile && existsSync7(colFile) ? `（${colFile}）` : `（⚠ 配置文件缺失：${colFile}，将回落内置默认）`}` : "内置默认 —— 想建自己栏目的风格体系，跑 /gtrk-style-maker（不建也能直接用默认）"
+  });
+  const ff = resolveFfmpeg();
+  if (ff) {
+    let hasX264 = false;
+    let ver = "";
+    try {
+      const cap = probeCapabilities(ff);
+      hasX264 = cap.hasLibx264;
+      ver = cap.version.replace(/^ffmpeg version\s*/i, "v");
+    } catch {}
+    rows.push({
+      name: "本地渲染 (ffmpeg)",
+      status: hasX264 ? "ok" : "warn",
+      detail: hasX264 ? `就绪（来源 ${ff.source}${ver ? `，${ver.split(/\s/)[0]}` : ""}）` : `找到 ffmpeg（${ff.source}）但缺 libx264 —— 本地渲染需换含 libx264 的构建`
+    });
+  } else {
+    rows.push({
+      name: "本地渲染 (ffmpeg)",
+      status: "warn",
+      detail: "未找到 —— 只出工程文件可忽略；要本地渲染成片，让 agent 装 ffmpeg/ffprobe 到 ~/.gitruck/ffmpeg 或 --ffmpeg-path"
+    });
   }
+  const cur = currentVersion();
+  const latest = await latestP;
+  rows.splice(1, 0, {
+    name: "CLI 版本",
+    status: latest && cmpSemver(latest, cur) > 0 ? "warn" : "ok",
+    detail: latest && cmpSemver(latest, cur) > 0 ? `v${cur} —— 有新版 v${latest}，跑 gtrk upgrade 升级` : latest ? `v${cur}（已是最新）` : `v${cur}`
+  });
+  console.log(`
+gtrk 体检：
+`);
+  for (const r of rows)
+    console.log(`  ${MARK[r.status]} ${r.name}：${r.detail}`);
+  const failed = rows.some((r) => r.status === "fail");
+  console.log(failed ? `
+有项不通，按提示处理后再开剪。
+` : `
+一切就绪，可以开剪。
+`);
+  if (failed)
+    process.exitCode = 1;
+  return !failed;
 }
-async function save(cache) {
-  await mkdir(CACHE_DIR, { recursive: true });
-  await writeFile2(CACHE_FILE, JSON.stringify(cache, null, 2));
-}
-async function invalidateUpload(path) {
-  const fp = await fingerprint(path);
-  const cache = await load();
-  if (cache[fp]) {
-    delete cache[fp];
-    await save(cache);
-  }
+
+// src/commands/init.ts
+var GUIDE_IMAGE = join9(packageRoot(), "assets", "jianying-draft-path.png");
+function registerInit(program2) {
+  program2.command("init").description("一次性配置：API Key + 剪映草稿目录（之后所有命令免重复配置）").option("--api-key <key>", "非交互：直接指定 API Key").option("--api-base <url>", "非交互：指定 API 根地址（缺省用默认生产地址）").option("--jianying-draft-dir <dir>", "非交互：剪映草稿目录（传 auto 则自动探测）").option("--reconfigure", "重走配置向导（默认：已配过则跳过、保留现有配置）").option("-y, --yes", "非交互：用传入值 + 自动探测，不弹任何提示").action(runInit);
 }
-async function loadSessions() {
-  if (!existsSync8(SESSION_FILE))
-    return {};
-  try {
-    return JSON.parse(await readFile(SESSION_FILE, "utf8"));
-  } catch {
-    return {};
+async function runInit(opts) {
+  if (opts.yes || opts.apiKey)
+    return runInitNonInteractive(opts);
+  if (!process.stdin.isTTY) {
+    log.err("交互式 init 需要真实终端；脚本/agent 请用：gtrk init --api-key <KEY> -y");
+    process.exitCode = 1;
+    return;
   }
-}
-async function saveSessions(sessions) {
-  await mkdir(CACHE_DIR, { recursive: true });
-  await writeFile2(SESSION_FILE, JSON.stringify(sessions, null, 2));
-}
-var fileSessionStore = {
-  async load(fp) {
-    return (await loadSessions())[fp];
-  },
-  async save(fp, rec) {
-    const sessions = await loadSessions();
-    sessions[fp] = rec;
-    await saveSessions(sessions);
-  },
-  async clear(fp) {
-    const sessions = await loadSessions();
-    if (sessions[fp]) {
-      delete sessions[fp];
-      await saveSessions(sessions);
+  const existing = readUserConfig();
+  const configured = !!existing.apiKey;
+  log.step("▶ gtrk 安装配置");
+  if (configured && !opts.reconfigure) {
+    log.info(`检测到已有配置：API Key ${mask(existing.apiKey)}｜根地址 ${existing.apiBase ?? DEFAULT_API_BASE}｜剪映目录 ${existing.jianyingDraftDir ?? "未配"}`);
+    if (await promptConfirm("保留现有配置、跳过重填？（要改配置选 N）", true)) {
+      log.info("已保留现有配置（要改配置随时跑 gtrk init --reconfigure）。");
+      return afterConfigDoctor();
     }
+    log.info("好，重新配置——各项可直接回车沿用现有值。");
   }
-};
-async function uploadCached(cfg, path, opts) {
-  const fp = await fingerprint(path);
-  const cache = await load();
-  const hit = cache[fp]?.fileId;
-  if (!opts?.force && hit)
-    return { fileId: hit, cached: true };
+  let apiKey = existing.apiKey ?? "";
+  const keyMsg = apiKey ? `粘贴新的 API Key，或直接回车沿用现有（${mask(apiKey)}）：` : "粘贴同合云 API Key（Ctrl+V 粘贴）：";
+  for (;; ) {
+    const entered = (await promptSecret(keyMsg)).trim();
+    if (entered) {
+      apiKey = entered;
+      break;
+    }
+    if (apiKey)
+      break;
+    log.warn("API Key 不能为空，再来一次");
+  }
+  const apiBase = (await promptText("云端 API 根地址（回车用默认）：", {
+    defaultValue: existing.apiBase ?? DEFAULT_API_BASE
+  })).trim();
+  let jianyingDraftDir;
+  if (existing.jianyingDraftDir && existsSync8(existing.jianyingDraftDir)) {
+    if (await promptConfirm(`剪映草稿目录现为 ${existing.jianyingDraftDir}，保留吗？`, true)) {
+      jianyingDraftDir = existing.jianyingDraftDir;
+    }
+  }
+  if (!jianyingDraftDir) {
+    const probed = probeJianyingDraftDir();
+    if (probed && await promptConfirm(`自动找到剪映草稿目录：${probed}，用它吗？`, true)) {
+      jianyingDraftDir = probed;
+    }
+  }
+  if (!jianyingDraftDir) {
+    log.info("没自动找到（或你选了手动）。已打开一张指引图：剪映 → 全局设置 → 草稿 →「草稿位置」，把那一行路径复制过来；留空则跳过（剪映只产 draft_content.json、缺 meta、需手动导入）。");
+    openFile(GUIDE_IMAGE);
+    const manual = (await promptText("剪映草稿根目录（…\\com.lveditor.draft），留空跳过：")).trim();
+    if (manual) {
+      if (existsSync8(manual))
+        jianyingDraftDir = resolve2(manual);
+      else
+        log.warn(`目录不存在，已跳过：${manual}`);
+    }
+  }
+  const patch = { apiKey, apiBase };
+  if (jianyingDraftDir)
+    patch.jianyingDraftDir = jianyingDraftDir;
+  writeUserConfig(patch);
+  log.ok(`配置已写入 ${configPath()}`);
+  if (!jianyingDraftDir) {
+    log.warn("未配剪映草稿目录：要剪映直接打开，之后可重跑 gtrk init，或单次加 --jianying-draft-dir");
+  }
+  return afterConfigDoctor();
+}
+function mask(key) {
+  return `${key.slice(0, 6)}…`;
+}
+async function afterConfigDoctor() {
+  const healthy = await runDoctor();
+  if (healthy) {
+    log.step("装好了！两种用法任选：");
+    log.info('① 命令行直接剪：gtrk oralcut "<毛片.mp4>" --script "<文字稿.txt>"（无稿就别加 --script）');
+    log.info("② 重启你常用的 AI agent（Claude / Codex / Trae / WorkBuddy 等），用 /gtrk-oralcut <你的口播剪辑需求>，一句话交给它，体验更智能的剪辑~");
+    log.info("想有自己栏目的风格体系？在 agent 里跑 /gtrk-style-maker 建一次「你的厨房」（skill 家族 + 栏目配置）；不建就直接用默认，照常开剪。");
+  } else {
+    log.warn("上面体检有项没通，按提示处理好再开剪（多半是 API Key 或剪映目录）。");
+  }
+}
+async function runInitNonInteractive(opts) {
+  const existing = readUserConfig();
+  const apiKey = (opts.apiKey ?? existing.apiKey ?? "").trim();
+  if (!apiKey) {
+    log.err("非交互模式需要 --api-key（或改用交互式 gtrk init）");
+    process.exitCode = 1;
+    return;
+  }
+  const apiBase = (opts.apiBase ?? existing.apiBase ?? DEFAULT_API_BASE).trim();
+  let jianyingDraftDir;
+  const dirOpt = opts.jianyingDraftDir;
+  if (dirOpt && dirOpt !== "auto")
+    jianyingDraftDir = resolve2(dirOpt);
+  else if (dirOpt === "auto" || !existing.jianyingDraftDir)
+    jianyingDraftDir = probeJianyingDraftDir();
+  else
+    jianyingDraftDir = existing.jianyingDraftDir;
+  const patch = { apiKey, apiBase };
+  if (jianyingDraftDir)
+    patch.jianyingDraftDir = jianyingDraftDir;
+  writeUserConfig(patch);
+  log.ok(`配置已写入 ${configPath()}`);
+  log.info(`剪映草稿目录：${jianyingDraftDir ?? "未配（剪映需手动导入，可加 --jianying-draft-dir）"}`);
+  await runDoctor();
+}
+
+// src/commands/install.ts
+function registerInstall(program2) {
+  program2.command("install").description("一条命令装全：安装 /gtrk-oralcut skill + 配置（对标飞书 lark-cli install）").option("--api-key <key>", "非交互：直接指定 API Key").option("--api-base <url>", "非交互：指定 API 根地址").option("--jianying-draft-dir <dir>", "非交互：剪映草稿目录（传 auto 则自动探测）").option("--skills-dir <dir>", "自定义 skills 目录（缺省 ~/.claude/skills）").option("--reconfigure", "重走配置向导（默认：已配过则保留现有配置、只刷新 skill）").option("-y, --yes", "非交互：用传入值 + 自动探测，不弹任何提示").action(async (opts) => {
+    log.step("① 安装 / 刷新 agent skill…");
+    installSkill({ dir: opts.skillsDir });
+    log.step("② 配置 + 体检…");
+    await runInit(opts);
+  });
+}
+
+// src/commands/oralcut.ts
+import { resolve as resolve3, join as join14, dirname as dirname2, basename as basename5, extname as extname2 } from "node:path";
+import { mkdir as mkdir4, writeFile as writeFile5, readFile as readFile3 } from "node:fs/promises";
+import { existsSync as existsSync12 } from "node:fs";
+
+// src/lib/config.ts
+function loadConfig() {
+  const uc = readUserConfig();
+  const apiKey = (process.env.GITRUCK_API_KEY ?? uc.apiKey ?? "").trim();
+  const base = (process.env.GITRUCK_API_BASE ?? uc.apiBase ?? DEFAULT_API_BASE).trim().replace(/\/+$/, "");
+  if (!apiKey) {
+    throw new Error("缺 API Key —— 先跑 `gtrk init` 配置（或设环境变量 GITRUCK_API_KEY）");
+  }
+  return { base, apiKey };
+}
+
+// src/lib/cloud.ts
+import { basename } from "node:path";
+import { writeFile, stat } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { Readable } from "node:stream";
+import { randomBytes } from "node:crypto";
+
+class CloudError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CloudError";
+  }
+}
+async function parseJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    throw new Error(`服务响应解析失败 (HTTP ${res.status})`);
+  }
+}
+async function uploadFile(cfg, path) {
+  const size = (await stat(path)).size;
+  const boundary = `----gtrkFormBoundary${randomBytes(16).toString("hex")}`;
+  const head = Buffer.from(`--${boundary}\r
+` + `Content-Disposition: form-data; name="file"; filename="${basename(path)}"\r
+` + `Content-Type: application/octet-stream\r
+\r
+`, "utf8");
+  const tail = Buffer.from(`\r
+--${boundary}--\r
+`, "utf8");
+  async function* multipart() {
+    yield head;
+    for await (const chunk of createReadStream(path))
+      yield chunk;
+    yield tail;
+  }
+  const res = await fetch(`${cfg.base}/base/file/upload`, {
+    method: "POST",
+    headers: {
+      Authorization: cfg.apiKey,
+      "Content-Type": `multipart/form-data; boundary=${boundary}`,
+      "Content-Length": String(head.length + size + tail.length)
+    },
+    body: Readable.toWeb(Readable.from(multipart())),
+    duplex: "half"
+  });
+  const r = await parseJson(res);
+  const fid = r.data?.file_id ?? r.data?.id;
+  if (r.code === 200 && fid)
+    return String(fid);
+  throw new Error(`上传失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
+}
+async function submitTask(cfg, taskType, payload) {
+  const res = await fetch(`${cfg.base}/task/${taskType}`, {
+    method: "POST",
+    headers: { Authorization: cfg.apiKey, "Content-Type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+  const r = await parseJson(res);
+  if (r.code === 200 && r.data?.task_id)
+    return String(r.data.task_id);
+  throw new Error(`提交失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
+}
+async function getTaskResult(cfg, taskType, taskId) {
+  const res = await fetch(`${cfg.base}/task/${taskType}/${taskId}`, {
+    headers: { Authorization: cfg.apiKey }
+  });
+  const r = await parseJson(res);
+  if (r.code != null && r.code !== 200) {
+    throw new CloudError(r.code, `任务查询失败 (code=${r.code})：${r.msg ?? ""}`);
+  }
+  const data = r.data ?? {};
+  return {
+    status: String(data.status ?? ""),
+    progress: typeof data.progress === "number" ? data.progress : undefined,
+    output: data.output_result ?? {}
+  };
+}
+async function pollTask(cfg, taskType, taskId, onTick) {
+  const start = Date.now();
+  const TIMEOUT_MS = 30 * 60 * 1000;
+  const INTERVAL_MS = 5000;
+  for (;; ) {
+    if (Date.now() - start > TIMEOUT_MS) {
+      throw new Error("任务超时（超过 30 分钟）。可稍后在云端查任务或重试。");
+    }
+    await new Promise((r) => setTimeout(r, INTERVAL_MS));
+    let got;
+    try {
+      got = await getTaskResult(cfg, taskType, taskId);
+    } catch (e) {
+      if (e instanceof CloudError)
+        throw e;
+      continue;
+    }
+    if (got.status === "completed")
+      return got.output;
+    if (got.status === "failed" || got.status === "cancelled") {
+      const out = got.output;
+      throw new Error(out?.error ?? (got.status === "failed" ? "任务失败" : "任务已取消"));
+    }
+    onTick?.(got.status || "处理中", got.progress);
+  }
+}
+async function download(url, dest) {
+  const res = await fetch(url);
+  if (!res.ok)
+    throw new Error(`下载失败 HTTP ${res.status}：${url}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  await writeFile(dest, buf);
+}
+
+// src/lib/upload-cache.ts
+import { join as join10 } from "node:path";
+import { stat as stat3, mkdir, readFile, writeFile as writeFile2 } from "node:fs/promises";
+import { existsSync as existsSync9 } from "node:fs";
+
+// src/lib/chunk-upload.ts
+var import_hash_wasm = __toESM(require_index_umd(), 1);
+import { open, stat as stat2 } from "node:fs/promises";
+import { basename as basename2 } from "node:path";
+var CHUNK_THRESHOLD = 256 * 1024 * 1024;
+var CONCURRENCY = 3;
+var PART_RETRIES = 3;
+var BACKOFF_MS = [2000, 4000, 8000];
+var INCOMPLETE_ROUNDS = 2;
+var MAX_REBUILDS = 1;
+var CODE_SESSION_NOT_FOUND = 6024;
+var CODE_PART_INVALID = 6025;
+var CODE_CHECKSUM_MISMATCH = 6026;
+var CODE_INCOMPLETE = 6027;
+var FP_BUFFER = 8192;
+var FP_SKIP = 64 * 1024 * 1024;
+async function fastBlake3(path) {
+  try {
+    const hasher = await import_hash_wasm.createBLAKE3();
+    hasher.init();
+    const fh = await open(path, "r");
+    try {
+      const buf = Buffer.alloc(FP_BUFFER);
+      let count = 0;
+      let pos = 0;
+      for (;; ) {
+        const { bytesRead } = await fh.read(buf, 0, FP_BUFFER, pos);
+        if (bytesRead === 0)
+          break;
+        count += FP_BUFFER;
+        if (count >= FP_SKIP)
+          break;
+        hasher.update(buf.subarray(0, bytesRead));
+        pos += bytesRead;
+      }
+      return hasher.digest("hex");
+    } finally {
+      await fh.close();
+    }
+  } catch {
+    return;
+  }
+}
+async function partBlake3(view) {
+  const hasher = await import_hash_wasm.createBLAKE3();
+  hasher.init();
+  hasher.update(view);
+  return hasher.digest("hex");
+}
+
+class SessionGoneError extends Error {
+  constructor() {
+    super("分片会话已失效");
+    this.name = "SessionGoneError";
+  }
+}
+function isTransient(e) {
+  const msg = String(e?.message ?? e);
+  return /fetch failed|ECONNRESET|ETIMEDOUT|EPIPE|UND_ERR|服务响应解析失败 \(HTTP 5/i.test(msg);
+}
+async function sleep(ms) {
+  await new Promise((r) => setTimeout(r, ms));
+}
+async function uploadChunked(cfg, path, opts) {
+  const size = (await stat2(path)).size;
+  const name = basename2(path);
+  for (let rebuilds = 0;; rebuilds++) {
+    try {
+      return await attemptOnce(cfg, path, name, size, opts);
+    } catch (e) {
+      if (e instanceof SessionGoneError && rebuilds < MAX_REBUILDS) {
+        await opts.store.clear(opts.fingerprint);
+        log.warn("云端分片会话已失效，自动重建整传一次");
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+async function attemptOnce(cfg, path, name, size, opts) {
+  const { fingerprint, store, force } = opts;
+  let session = force ? undefined : await store.load(fingerprint);
+  let missing;
+  if (session) {
+    const st = await chunkStatus(cfg, session.uploadId);
+    if (st === undefined) {
+      await store.clear(fingerprint);
+      session = undefined;
+    } else {
+      session = { ...session, partSize: st.part_size, totalParts: st.total_parts };
+      missing = st.missing;
+      if (missing.length < session.totalParts) {
+        log.info(`断点续传：云端已有 ${session.totalParts - missing.length}/${session.totalParts} 片，补 ${missing.length} 片`);
+      }
+    }
+  }
+  if (!session) {
+    const blake3Id = force ? undefined : await fastBlake3(path);
+    const body = { filename: name, size };
+    if (blake3Id)
+      body.blake3_id = blake3Id;
+    const res = await fetch(`${cfg.base}/base/file/upload/chunk/init`, {
+      method: "POST",
+      headers: { Authorization: cfg.apiKey, "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    const r = await parseJson(res);
+    if (r.code !== 200) {
+      throw new Error(`分片上传 init 失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
+    }
+    if (r.data?.file_id != null) {
+      log.info("秒传命中：云端已有同内容文件，零字节上传");
+      return String(r.data.file_id);
+    }
+    if (r.data?.upload_id == null || !r.data.part_size || !r.data.total_parts) {
+      throw new Error("分片上传 init 响应缺字段（upload_id/part_size/total_parts）");
+    }
+    session = {
+      uploadId: String(r.data.upload_id),
+      partSize: r.data.part_size,
+      totalParts: r.data.total_parts,
+      size,
+      path,
+      createdAt: Date.now()
+    };
+    await store.save(fingerprint, session);
+    missing = undefined;
+  }
+  if (missing === undefined) {
+    missing = Array.from({ length: session.totalParts }, (_, i) => i);
+  }
+  await uploadParts(cfg, path, session, missing);
+  for (let round = 0;; round++) {
+    const res = await fetch(`${cfg.base}/base/file/upload/chunk/${session.uploadId}/complete`, { method: "POST", headers: { Authorization: cfg.apiKey } });
+    const r = await parseJson(res);
+    if (r.code === 200 && r.data?.file_id != null) {
+      await store.clear(fingerprint);
+      return String(r.data.file_id);
+    }
+    if (r.code === CODE_SESSION_NOT_FOUND)
+      throw new SessionGoneError;
+    if (r.code === CODE_INCOMPLETE && round < INCOMPLETE_ROUNDS) {
+      const st = await chunkStatus(cfg, session.uploadId);
+      if (st === undefined)
+        throw new SessionGoneError;
+      await uploadParts(cfg, path, session, st.missing);
+      continue;
+    }
+    throw new Error(`分片上传 complete 失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
+  }
+}
+async function chunkStatus(cfg, uploadId) {
+  const res = await fetch(`${cfg.base}/base/file/upload/chunk/${uploadId}`, {
+    headers: { Authorization: cfg.apiKey }
+  });
+  const r = await parseJson(res);
+  if (r.code === CODE_SESSION_NOT_FOUND)
+    return;
+  if (r.code !== 200 || !r.data) {
+    throw new Error(`分片会话查询失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
+  }
+  return r.data;
+}
+async function uploadParts(cfg, path, session, indexes) {
+  if (indexes.length === 0)
+    return;
+  const { uploadId, partSize, totalParts, size } = session;
+  let done = totalParts - indexes.length;
+  const fh = await open(path, "r");
+  try {
+    const queue = [...indexes];
+    const worker = async () => {
+      const buf = Buffer.alloc(partSize);
+      for (;; ) {
+        const idx = queue.shift();
+        if (idx === undefined)
+          return;
+        const offset = idx * partSize;
+        const len = idx === totalParts - 1 ? size - offset : partSize;
+        const { bytesRead } = await fh.read(buf, 0, len, offset);
+        if (bytesRead !== len) {
+          throw new Error(`本地文件读取不足（第${idx}片期望${len}字节实读${bytesRead}）——文件被改动？`);
+        }
+        const view = buf.subarray(0, len);
+        await putPart(cfg, uploadId, idx, view);
+        done++;
+        log.tick(`分片上传 ${done}/${totalParts}（${Math.round(done / totalParts * 100)}%）`);
+      }
+    };
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, indexes.length) }, worker));
+  } finally {
+    log.tickEnd();
+    await fh.close();
+  }
+}
+async function putPart(cfg, uploadId, idx, view) {
+  const b3 = await partBlake3(view);
+  let lastErr;
+  for (let attempt = 0;attempt <= PART_RETRIES; attempt++) {
+    if (attempt > 0)
+      await sleep(BACKOFF_MS[Math.min(attempt - 1, BACKOFF_MS.length - 1)]);
+    try {
+      const res = await fetch(`${cfg.base}/base/file/upload/chunk/${uploadId}/${idx}?blake3=${b3}`, {
+        method: "PUT",
+        headers: { Authorization: cfg.apiKey, "Content-Type": "application/octet-stream" },
+        body: view
+      });
+      const r = await parseJson(res);
+      if (r.code === 200)
+        return;
+      if (r.code === CODE_SESSION_NOT_FOUND)
+        throw new SessionGoneError;
+      if (r.code === CODE_CHECKSUM_MISMATCH || r.code === CODE_PART_INVALID) {
+        lastErr = new Error(`第${idx}片被拒 (code=${r.code})：${r.msg ?? ""}`);
+        continue;
+      }
+      throw new Error(`第${idx}片上传失败 (code=${r.code ?? "?"})：${r.msg ?? "未知错误"}`);
+    } catch (e) {
+      if (e instanceof SessionGoneError)
+        throw e;
+      if (!isTransient(e))
+        throw e;
+      lastErr = e;
+    }
+  }
+  throw lastErr instanceof Error ? lastErr : new Error(`第${idx}片重试${PART_RETRIES}次仍失败`);
+}
+
+// src/lib/upload-cache.ts
+var CACHE_DIR = gitruckHome();
+var CACHE_FILE = join10(CACHE_DIR, "upload-cache.json");
+var SESSION_FILE = join10(CACHE_DIR, "upload-sessions.json");
+async function fingerprint(path) {
+  const s = await stat3(path);
+  return `${s.size}:${Math.round(s.mtimeMs)}`;
+}
+async function load() {
+  if (!existsSync9(CACHE_FILE))
+    return {};
+  try {
+    return JSON.parse(await readFile(CACHE_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function save(cache) {
+  await mkdir(CACHE_DIR, { recursive: true });
+  await writeFile2(CACHE_FILE, JSON.stringify(cache, null, 2));
+}
+async function invalidateUpload(path) {
+  const fp = await fingerprint(path);
+  const cache = await load();
+  if (cache[fp]) {
+    delete cache[fp];
+    await save(cache);
+  }
+}
+async function loadSessions() {
+  if (!existsSync9(SESSION_FILE))
+    return {};
+  try {
+    return JSON.parse(await readFile(SESSION_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function saveSessions(sessions) {
+  await mkdir(CACHE_DIR, { recursive: true });
+  await writeFile2(SESSION_FILE, JSON.stringify(sessions, null, 2));
+}
+var fileSessionStore = {
+  async load(fp) {
+    return (await loadSessions())[fp];
+  },
+  async save(fp, rec) {
+    const sessions = await loadSessions();
+    sessions[fp] = rec;
+    await saveSessions(sessions);
+  },
+  async clear(fp) {
+    const sessions = await loadSessions();
+    if (sessions[fp]) {
+      delete sessions[fp];
+      await saveSessions(sessions);
+    }
+  }
+};
+async function uploadCached(cfg, path, opts) {
+  const fp = await fingerprint(path);
+  const cache = await load();
+  const hit = cache[fp]?.fileId;
+  if (!opts?.force && hit)
+    return { fileId: hit, cached: true };
   const s0 = await stat3(path);
   const fileId = s0.size >= CHUNK_THRESHOLD ? await uploadChunked(cfg, path, {
     fingerprint: fp,
@@ -5288,8 +5962,8 @@ async function uploadCached(cfg, path, opts) {
 
 // src/lib/media.ts
 import { mkdir as mkdir2, stat as stat4 } from "node:fs/promises";
-import { existsSync as existsSync9 } from "node:fs";
-import { basename as basename3, extname, join as join9 } from "node:path";
+import { existsSync as existsSync10 } from "node:fs";
+import { basename as basename3, extname, join as join11 } from "node:path";
 function parseFps(rate) {
   if (typeof rate !== "string")
     return 0;
@@ -5339,12 +6013,12 @@ async function artifactPath(inputAbs, ext) {
   const s = await stat4(inputAbs);
   const base = basename3(inputAbs, extname(inputAbs));
   await mkdir2(audioCacheDir(), { recursive: true });
-  return join9(audioCacheDir(), `${base}.${s.size}_${Math.round(s.mtimeMs)}.${ext}`);
+  return join11(audioCacheDir(), `${base}.${s.size}_${Math.round(s.mtimeMs)}.${ext}`);
 }
 async function extractAudio(inputAbs, ffmpegPath) {
   const { ffmpeg } = requireFfmpeg(ffmpegPath);
   const out = await artifactPath(inputAbs, "mp3");
-  if (existsSync9(out))
+  if (existsSync10(out))
     return out;
   await runFfmpeg(ffmpeg, [
     "-y",
@@ -5368,7 +6042,7 @@ async function extractAudio(inputAbs, ffmpegPath) {
 async function compress720p(inputAbs, ffmpegPath) {
   const { ffmpeg } = requireFfmpeg(ffmpegPath);
   const out = await artifactPath(inputAbs, "720p.mp4");
-  if (existsSync9(out))
+  if (existsSync10(out))
     return out;
   await runFfmpeg(ffmpeg, [
     "-y",
@@ -5400,14 +6074,14 @@ function assertDurationConsistent(originalDuration, artifactAbs, ffmpegPath, tol
 }
 
 // src/lib/materialize.ts
-import { join as join11, basename as basename4 } from "node:path";
+import { join as join13, basename as basename4 } from "node:path";
 import { mkdir as mkdir3, cp, writeFile as writeFile4 } from "node:fs/promises";
 
 // src/lib/render.ts
 import { writeFile as writeFile3, unlink, readFile as readFile2 } from "node:fs/promises";
-import { existsSync as existsSync10 } from "node:fs";
+import { existsSync as existsSync11 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join as join10 } from "node:path";
+import { join as join12 } from "node:path";
 var AUDIO_SAMPLE_RATE = 48000;
 var AUDIO_LAYOUT = "stereo";
 var DEFAULT_CRF = 18;
@@ -5547,11 +6221,25 @@ function buildFilterGraph(gtrk, materialPaths, params = {}) {
   return { inputs, graph: chains.join(";"), total };
 }
 function materialPathsFromGtrk(gtrk) {
+  const used = new Set;
+  const sortedV = sortedTracks(gtrk.video_track || []);
+  const consumers = [sortedV[0], ...gtrk.audio_track || []];
+  for (const t of consumers) {
+    if (!t)
+      continue;
+    for (const c3 of t.track_timeline || []) {
+      const m = c3.material;
+      if (m != null)
+        used.add(String(m));
+    }
+  }
   const map = {};
   for (const m of gtrk.materials || []) {
+    if (!used.has(String(m.id)))
+      continue;
     if (!m.path)
       throw new Error(`gtrk 素材 ${m.id} 缺 path（source_path），无法本地渲染`);
-    if (!existsSync10(m.path))
+    if (!existsSync11(m.path))
       throw new Error(`gtrk 素材文件不存在：${m.path}`);
     map[String(m.id)] = m.path;
   }
@@ -5565,7 +6253,7 @@ async function renderGtrk(gtrk, outputPath, opts = {}) {
   const { ffmpeg } = requireFfmpeg(opts.ffmpegPath);
   const materialPaths = materialPathsFromGtrk(gtrk);
   const { inputs, graph, total } = buildFilterGraph(gtrk, materialPaths, { crf });
-  const filterFile = join10(tmpdir(), `gtrk-filter-${process.pid}-${inputs.length}.txt`);
+  const filterFile = join12(tmpdir(), `gtrk-filter-${process.pid}-${inputs.length}.txt`);
   await writeFile3(filterFile, graph, "utf8");
   try {
     const args = ["-y"];
@@ -5615,7 +6303,7 @@ async function materializeResult(opts) {
     throw new Error("任务无工程文件产物（检查 project_formats / 任务是否产出）");
   const errors = { ...output.errors ?? {} };
   await mkdir3(outDir, { recursive: true });
-  const resultPath = join11(outDir, "result.json");
+  const resultPath = join13(outDir, "result.json");
   const writeResult = async (extra) => {
     const r = {
       ok: Object.keys(errors).length === 0,
@@ -5637,9 +6325,9 @@ async function materializeResult(opts) {
   const byFormat = {};
   for (const f of files) {
     const base = baseFormat(f.format);
-    const fmtDir = join11(outDir, base);
+    const fmtDir = join13(outDir, base);
     await mkdir3(fmtDir, { recursive: true });
-    const dest = join11(fmtDir, f.filename);
+    const dest = join13(fmtDir, f.filename);
     try {
       await dl(f.download_url, dest);
       (byFormat[base] ??= []).push(dest);
@@ -5656,9 +6344,9 @@ async function materializeResult(opts) {
   let jianyingDraftPath = null;
   if (byFormat.jianying && opts.draftDir) {
     try {
-      jianyingDraftPath = join11(opts.draftDir, basename4(outDir));
+      jianyingDraftPath = join13(opts.draftDir, basename4(outDir));
       await mkdir3(jianyingDraftPath, { recursive: true });
-      await cp(join11(outDir, "jianying"), jianyingDraftPath, { recursive: true });
+      await cp(join13(outDir, "jianying"), jianyingDraftPath, { recursive: true });
       log.info(`剪映草稿已落到：${jianyingDraftPath}`);
     } catch (e) {
       jianyingDraftPath = null;
@@ -5675,7 +6363,7 @@ async function materializeResult(opts) {
       log.step("本地渲染成片（ffmpeg）…");
       const project = await readGtrkFile(gtrkPath);
       const name = opts.projName ?? gtrkSourceName(project) ?? taskId;
-      const outMp4 = join11(outDir, `${name}.mp4`);
+      const outMp4 = join13(outDir, `${name}.mp4`);
       const r = await renderGtrk(project, outMp4, {
         crf: opts.crf != null ? Number(opts.crf) : undefined,
         codec: opts.codec,
@@ -5697,7 +6385,7 @@ async function materializeResult(opts) {
       log.step("三方打开（产物已就位，按需自取）：");
     for (const base of Object.keys(byFormat)) {
       const meta = FORMAT_META[base];
-      const target = base === "jianying" ? jianyingDraftPath ?? join11(outDir, "jianying") : byFormat[base][0];
+      const target = base === "jianying" ? jianyingDraftPath ?? join13(outDir, "jianying") : byFormat[base][0];
       console.log(`   • ${meta?.label ?? base}：${meta?.openHint(target) ?? target}`);
     }
     if (rendered)
@@ -5765,18 +6453,18 @@ async function runOralCut(input, opts) {
     routeLogsToStderr();
   const cfg = loadConfig();
   const inputAbs = resolve3(input);
-  if (!existsSync11(inputAbs))
+  if (!existsSync12(inputAbs))
     throw new Error(`毛片不存在：${inputAbs}`);
   const projName = basename5(inputAbs, extname2(inputAbs));
   const formats = opts.formats.split(",").map((s) => s.trim()).filter(Boolean);
   if (opts.render && !formats.includes("gtrk"))
     formats.push("gtrk");
   const wantJianying = formats.some((f) => f === "jianying" || f === "capcut");
-  const outDir = resolve3(opts.out ?? join12(dirname2(inputAbs), `${projName}-video-project-${timestamp()}`));
+  const outDir = resolve3(opts.out ?? join14(dirname2(inputAbs), `${projName}-video-project-${timestamp()}`));
   let scriptPath = opts.script ? resolve3(opts.script) : undefined;
   if (!scriptPath) {
-    const sibling = join12(dirname2(inputAbs), `${projName}.txt`);
-    if (existsSync11(sibling)) {
+    const sibling = join14(dirname2(inputAbs), `${projName}.txt`);
+    if (existsSync12(sibling)) {
       scriptPath = sibling;
       log.info(`自动识别到同名文稿：${sibling}（按有稿剪辑；不想用就改名或显式 --script）`);
     }
@@ -5842,605 +6530,286 @@ async function runOralCut(input, opts) {
   }
   log.info(`task_id = ${taskId}`);
   await mkdir4(outDir, { recursive: true });
-  await writeFile5(join12(outDir, "task.json"), JSON.stringify({ taskId, taskType: TASK_TYPE, fileId: up.fileId, source: inputAbs, formats, createdAt: new Date().toISOString() }, null, 2));
+  await writeFile5(join14(outDir, "task.json"), JSON.stringify({ taskId, taskType: TASK_TYPE, fileId: up.fileId, source: inputAbs, formats, createdAt: new Date().toISOString() }, null, 2));
   log.step("④ 云端处理中（每 5s 轮询）…");
-  const result = await pollTask(cfg, TASK_TYPE, taskId, (status, progress) => {
-    log.tick(`${status}${progress != null ? ` ${Math.round(progress)}%` : ""}`);
-  });
-  log.tickEnd();
-  await materializeResult({
-    outDir,
-    output: result,
-    taskId,
-    fileId: up.fileId,
-    draftDir,
-    render: opts.render,
-    crf: opts.crf,
-    codec: opts.codec,
-    ffmpegPath: opts.ffmpegPath,
-    projName,
-    json: opts.json,
-    open: opts.open
-  });
-  log.ok(`闭环完成。产物目录：${outDir}`);
-}
-
-// src/commands/oralcut-result.ts
-import { resolve as resolve4, join as join13 } from "node:path";
-var TASK_TYPE2 = "cli/video_oral_cut_for_cli";
-function timestamp2() {
-  const d = new Date;
-  const p = (n) => String(n).padStart(2, "0");
-  return `${p(d.getFullYear() % 100)}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
-}
-function registerOralCutResult(program2) {
-  program2.command("oralcut-result <taskId>").description("按 task_id 取回已完成任务的报告 + 三方工程产物（可选 --render），不重跑云端").option("-o, --out <dir>", "产物目录（缺省 = <当前目录>/<taskId>-video-project-<时间戳>）").option("--render", "额外本地渲染成片（需原毛片仍在 gtrk 内嵌路径 + ffmpeg）").option("--crf <n>", "本地渲染 CRF 14-28（默认 18；需配 --render）").option("--codec <c>", "本地渲染编码（默认 h264；需配 --render）").option("--ffmpeg-path <dir>", "指定 ffmpeg/ffprobe 目录（缺省 ~/.gitruck/ffmpeg → 系统）").option("--jianying-draft-dir <dir>", "剪映草稿根目录；传路径或 auto（默认读配置 / 自动探测）").option("--no-open", "完成后不自动打开产物目录（默认会自动打开）").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON（给 agent/脚本解析）").action(async (taskId, opts) => {
-    await runOralCutResult(taskId, opts);
-  });
-}
-async function runOralCutResult(taskId, opts) {
-  if (opts.json)
-    routeLogsToStderr();
-  const cfg = loadConfig();
-  log.step(`▶ 按 task_id 取回口播剪辑结果：${taskId}`);
-  let got;
-  try {
-    got = await getTaskResult(cfg, TASK_TYPE2, taskId);
-  } catch (e) {
-    if (e instanceof CloudError) {
-      throw new Error(`取任务结果失败（code=${e.code}）：${e.message}。` + `注意：取结果需用「提交该任务的同一账号」的 API Key；异账号或已删任务会报 TASK_NOT_FOUND。`);
-    }
-    throw e;
-  }
-  if (got.status !== "completed") {
-    if (got.status === "failed" || got.status === "cancelled") {
-      const out = got.output;
-      throw new Error(`任务未成功（${got.status}）：${out?.error ?? "无产物可取回"}`);
-    }
-    const pct = got.progress != null ? ` ${Math.round(got.progress)}%` : "";
-    throw new Error(`任务尚未完成（当前 ${got.status || "未知"}${pct}），暂无法取回结果；请稍后再试。`);
-  }
-  const outDir = resolve4(opts.out ?? join13(process.cwd(), `${taskId}-video-project-${timestamp2()}`));
-  const draftDir = resolveJianyingDraftDir(opts.jianyingDraftDir);
-  await materializeResult({
-    outDir,
-    output: got.output,
-    taskId,
-    draftDir,
-    render: opts.render,
-    crf: opts.crf,
-    codec: opts.codec,
-    ffmpegPath: opts.ffmpegPath,
-    json: opts.json,
-    open: opts.open
-  });
-  log.ok(`已取回。产物目录：${outDir}`);
-}
-
-// src/commands/upgrade.ts
-import { spawnSync as spawnSync3 } from "node:child_process";
-var CLIENT_UPGRADE = "irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex";
-function run(cmd) {
-  const r = spawnSync3(cmd, { stdio: "inherit", shell: true });
-  return r.status ?? 1;
-}
-function registerUpgrade(program2) {
-  program2.command("upgrade").description("升级 gtrk CLI 到最新版 + 刷新 skill（配置保留）；--check 只查不装").option("--check", "只检查有没有新版本，不执行升级").action(async (opts) => {
-    const cur = currentVersion();
-    log.step(`当前 v${cur}，查询最新版…`);
-    const latest = await latestVersion();
-    if (!latest) {
-      log.warn("查不到最新版本（网络问题？）。手动升级：npm i -g @gitruck/cli@latest");
-      log.info(`客户端（桌面端）升级：${CLIENT_UPGRADE}`);
-      return;
-    }
-    if (cmpSemver(latest, cur) <= 0) {
-      log.ok(`已是最新版 v${cur}。`);
-      log.info(`客户端（桌面端）如需升级：${CLIENT_UPGRADE}`);
-      return;
-    }
-    log.info(`发现新版本 v${latest}（当前 v${cur}）。`);
-    if (opts.check) {
-      log.info("跑 `gtrk upgrade` 升级（会保留你现有的配置）。");
-      return;
-    }
-    log.step(`① 升级 CLI → v${latest}…`);
-    if (run("npm i -g @gitruck/cli@latest") !== 0) {
-      log.err("升级失败。手动重试：npm i -g @gitruck/cli@latest（若报权限，按你的 npm 全局目录权限处理）");
-      process.exitCode = 1;
-      return;
-    }
-    log.step("② 刷新 /gtrk-oralcut skill…");
-    if (run("gtrk skills install") !== 0) {
-      log.warn("skill 没刷成，手动跑一次：gtrk skills install");
-    }
-    log.ok(`已升级到 v${latest}。配置原样保留，直接接着用即可（gtrk doctor 可自检）。`);
-    log.info(`客户端（桌面端）如需一起升级：${CLIENT_UPGRADE}`);
-  });
-}
-
-// src/commands/render.ts
-import { resolve as resolve5, dirname as dirname3, join as join14, basename as basename6, extname as extname3 } from "node:path";
-import { existsSync as existsSync12 } from "node:fs";
-function registerRender(program2) {
-  program2.command("render <gtrk>").description("本地渲染：gtrk 工程按 EDL 用本地 ffmpeg 渲染成片 mp4（素材取原片本地路径）").option("-o, --out <file>", "输出 mp4 路径（缺省 = <gtrk 同目录>/<gtrk 名>.mp4）").option("--crf <n>", "视频质量 CRF 14-28（越小越清晰/文件越大，默认 18）").option("--codec <c>", "视频编码（默认 h264）").option("--ffmpeg-path <dir>", "指定 ffmpeg/ffprobe 所在目录（缺省 ~/.gitruck/ffmpeg → 系统）").option("--no-open", "完成后不自动打开产物目录").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON").action(async (gtrk, opts) => {
-    if (opts.json)
-      routeLogsToStderr();
-    const gtrkAbs = resolve5(gtrk);
-    if (!existsSync12(gtrkAbs))
-      throw new Error(`gtrk 工程不存在：${gtrkAbs}`);
-    const outMp4 = resolve5(opts.out ?? join14(dirname3(gtrkAbs), `${basename6(gtrkAbs, extname3(gtrkAbs))}.mp4`));
-    log.step(`▶ 本地渲染：${basename6(gtrkAbs)} → ${basename6(outMp4)}`);
-    const project = await readGtrkFile(gtrkAbs);
-    const result = await renderGtrk(project, outMp4, {
-      crf: opts.crf != null ? Number(opts.crf) : undefined,
-      codec: opts.codec,
-      ffmpegPath: opts.ffmpegPath,
-      onLine: (l) => {
-        const m = l.match(/time=(\S+)/);
-        if (m)
-          log.tick(`渲染中 ${m[1]}`);
-      }
-    });
-    log.tickEnd();
-    log.ok(`渲染完成：${outMp4}（${result.duration.toFixed(1)}s）`);
-    if (opts.open)
-      openFolder(dirname3(outMp4));
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: true, output: outMp4, duration: result.duration }));
-    }
-  });
-}
-
-// src/commands/split.ts
-import { resolve as resolve6, join as join16, dirname as dirname5, basename as basename8 } from "node:path";
-import { existsSync as existsSync13 } from "node:fs";
-import { readFile as readFile4, writeFile as writeFile6, mkdir as mkdir5 } from "node:fs/promises";
-import { createHash } from "node:crypto";
-
-// src/lib/projection.ts
-function r3(n) {
-  return Math.round(n * 1000) / 1000;
-}
-function normClip(c3) {
-  const clip_st = c3.clip_st ?? 0;
-  const track_st = c3.track_st ?? 0;
-  const dur = c3.duration ?? (c3.clip_ed != null ? c3.clip_ed - clip_st : 0);
-  const clip_ed = c3.clip_ed ?? clip_st + dur;
-  return { clip_st, clip_ed, track_st };
-}
-function pickMainVideoTrack(gtrk) {
-  const tracks = gtrk.video_track ?? [];
-  if (!tracks.length)
-    return;
-  let best = tracks[0];
-  let bestIdx = best.track_index ?? 0;
-  for (const t of tracks) {
-    const idx = t.track_index ?? 0;
-    if (idx < bestIdx) {
-      best = t;
-      bestIdx = idx;
-    }
-  }
-  return best;
-}
-function projectTranscript(transcript, gtrk, opts = {}) {
-  const materialId = String(transcript.material_id);
-  const mainTrack = pickMainVideoTrack(gtrk);
-  const clips = (mainTrack?.track_timeline ?? []).filter((c3) => c3.material != null && String(c3.material) === materialId).map(normClip);
-  const entries = [];
-  transcript.utterances.forEach((utt, sourceIndex) => {
-    const totalWords = utt.words?.length ?? 0;
-    const instances = [];
-    for (const clip of clips) {
-      const surviving = [];
-      for (const word of utt.words ?? []) {
-        const s = Math.max(word.st, clip.clip_st);
-        const e = Math.min(word.ed, clip.clip_ed);
-        if (e > s) {
-          surviving.push({
-            w: word.w,
-            track_st: r3(clip.track_st + (s - clip.clip_st)),
-            track_ed: r3(clip.track_st + (e - clip.clip_st))
-          });
-        }
-      }
-      if (surviving.length) {
-        instances.push({
-          track_st: Math.min(...surviving.map((x) => x.track_st)),
-          track_ed: Math.max(...surviving.map((x) => x.track_ed)),
-          kept_words: surviving.length,
-          words: surviving
-        });
-      }
-    }
-    if (!instances.length) {
-      entries.push({
-        id: utt.id,
-        text: utt.text,
-        dropped: true,
-        sourceIndex,
-        instIndex: 0,
-        track_st: null,
-        track_ed: null,
-        kept_words: 0,
-        total_words: totalWords,
-        words: [],
-        sortKey: 0
-      });
-    } else {
-      instances.sort((a, b) => a.track_st - b.track_st);
-      instances.forEach((inst, instIndex) => {
-        entries.push({
-          id: utt.id,
-          text: utt.text,
-          dropped: false,
-          sourceIndex,
-          instIndex,
-          track_st: inst.track_st,
-          track_ed: inst.track_ed,
-          kept_words: inst.kept_words,
-          total_words: totalWords,
-          words: inst.words,
-          sortKey: inst.track_st
-        });
-      });
-    }
-  });
-  let maxEd = 0;
-  for (const e of entries) {
-    if (e.dropped)
-      e.sortKey = maxEd;
-    else
-      maxEd = Math.max(maxEd, e.track_ed ?? maxEd);
-  }
-  entries.sort((a, b) => a.sortKey - b.sortKey || a.sourceIndex - b.sourceIndex || a.instIndex - b.instIndex);
-  const utterances = entries.map((e) => {
-    const u = {
-      id: e.id,
-      text: e.text,
-      track_st: e.track_st,
-      track_ed: e.track_ed,
-      dropped: e.dropped,
-      kept_words: e.kept_words,
-      total_words: e.total_words
-    };
-    if (opts.words)
-      u.words = e.words;
-    return u;
+  const result = await pollTask(cfg, TASK_TYPE, taskId, (status, progress) => {
+    log.tick(`${status}${progress != null ? ` ${Math.round(progress)}%` : ""}`);
   });
-  return {
-    transcript_hash: transcript.text_hash,
-    projected_at: opts.projectedAt ?? new Date().toISOString(),
-    utterances
-  };
+  log.tickEnd();
+  await materializeResult({
+    outDir,
+    output: result,
+    taskId,
+    fileId: up.fileId,
+    draftDir,
+    render: opts.render,
+    crf: opts.crf,
+    codec: opts.codec,
+    ffmpegPath: opts.ffmpegPath,
+    projName,
+    json: opts.json,
+    open: opts.open
+  });
+  log.ok(`闭环完成。产物目录：${outDir}`);
 }
 
-// src/lib/splitdoc.ts
-var BASE_TRACKS = ["真人出镜", "口播继续", "旁白主导"];
-var LANES = ["A_ROLL", "RRV_MG", "AI_DRAMA", "FILM_BROLL"];
-var NARRATIVES = [
-  "mirror-hook",
-  "demolition",
-  "container-translation",
-  "abyssal-fall",
-  "holding",
-  "reversal-elevation",
-  "callback-closure",
-  "typography-emphasis"
-];
-var CONTAINER_STAGES = [
-  "none",
-  "seed",
-  "expand",
-  "translate",
-  "rupture",
-  "flip",
-  "callback"
-];
-var IRREPLACEABILITY = ["必须真人出镜", "优先 MG", "可被 B-roll 替代", "可降级处理"];
-var AUX_TYPES = [
-  "quote-card",
-  "term-callout",
-  "network-diagram",
-  "archive-caption",
-  "pause-card",
-  "data-annotation",
-  "timeline-tag"
-];
-function isNonEmptyStr(v) {
-  return typeof v === "string" && v.trim().length > 0;
+// src/commands/oralcut-result.ts
+import { resolve as resolve4, join as join15 } from "node:path";
+var TASK_TYPE2 = "cli/video_oral_cut_for_cli";
+function timestamp2() {
+  const d = new Date;
+  const p = (n) => String(n).padStart(2, "0");
+  return `${p(d.getFullYear() % 100)}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
 }
-function enumOk(v, list) {
-  return typeof v === "string" && list.includes(v);
+function registerOralCutResult(program2) {
+  program2.command("oralcut-result <taskId>").description("按 task_id 取回已完成任务的报告 + 三方工程产物（可选 --render），不重跑云端").option("-o, --out <dir>", "产物目录（缺省 = <当前目录>/<taskId>-video-project-<时间戳>）").option("--render", "额外本地渲染成片（需原毛片仍在 gtrk 内嵌路径 + ffmpeg）").option("--crf <n>", "本地渲染 CRF 14-28（默认 18；需配 --render）").option("--codec <c>", "本地渲染编码（默认 h264；需配 --render）").option("--ffmpeg-path <dir>", "指定 ffmpeg/ffprobe 目录（缺省 ~/.gitruck/ffmpeg → 系统）").option("--jianying-draft-dir <dir>", "剪映草稿根目录；传路径或 auto（默认读配置 / 自动探测）").option("--no-open", "完成后不自动打开产物目录（默认会自动打开）").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON（给 agent/脚本解析）").action(async (taskId, opts) => {
+    await runOralCutResult(taskId, opts);
+  });
 }
-function validateSplitDoc(doc, ctx) {
-  const errors = [];
-  const warnings = [];
-  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
-    return { errors: ["拆分稿必须是一个 JSON 对象"], warnings };
-  }
-  const d = doc;
-  if (d.contract_version !== "v1") {
-    errors.push(`contract_version 必须为 "v1"（实际：${JSON.stringify(d.contract_version)}）`);
-  }
-  if (!isNonEmptyStr(d.transcript_hash)) {
-    errors.push("缺 transcript_hash（应从投影视图透传）");
-  } else if (d.transcript_hash !== ctx.transcriptHash) {
-    errors.push(`transcript_hash 不匹配：拆分稿 ${d.transcript_hash} ≠ 当前 transcript ${ctx.transcriptHash}——转写已变更，请重新导出视图并重拆`);
+async function runOralCutResult(taskId, opts) {
+  if (opts.json)
+    routeLogsToStderr();
+  const cfg = loadConfig();
+  log.step(`▶ 按 task_id 取回口播剪辑结果：${taskId}`);
+  let got;
+  try {
+    got = await getTaskResult(cfg, TASK_TYPE2, taskId);
+  } catch (e) {
+    if (e instanceof CloudError) {
+      throw new Error(`取任务结果失败（code=${e.code}）：${e.message}。` + `注意：取结果需用「提交该任务的同一账号」的 API Key；异账号或已删任务会报 TASK_NOT_FOUND。`);
+    }
+    throw e;
   }
-  if (!Array.isArray(d.beats) || d.beats.length === 0) {
-    errors.push("beats 必须是非空数组");
-    return { errors, warnings };
+  if (got.status !== "completed") {
+    if (got.status === "failed" || got.status === "cancelled") {
+      const out = got.output;
+      throw new Error(`任务未成功（${got.status}）：${out?.error ?? "无产物可取回"}`);
+    }
+    const pct = got.progress != null ? ` ${Math.round(got.progress)}%` : "";
+    throw new Error(`任务尚未完成（当前 ${got.status || "未知"}${pct}），暂无法取回结果；请稍后再试。`);
   }
-  const idIndex = new Map;
-  ctx.utteranceIds.forEach((id, i) => idIndex.set(id, i));
-  const ranges = [];
-  const seenBeatIds = new Set;
-  d.beats.forEach((raw, i) => {
-    const tag = (() => {
-      const bid = raw?.id;
-      return isNonEmptyStr(bid) ? bid : `beats[${i}]`;
-    })();
-    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-      errors.push(`${tag}：beat 必须是对象`);
+  const outDir = resolve4(opts.out ?? join15(process.cwd(), `${taskId}-video-project-${timestamp2()}`));
+  const draftDir = resolveJianyingDraftDir(opts.jianyingDraftDir);
+  await materializeResult({
+    outDir,
+    output: got.output,
+    taskId,
+    draftDir,
+    render: opts.render,
+    crf: opts.crf,
+    codec: opts.codec,
+    ffmpegPath: opts.ffmpegPath,
+    json: opts.json,
+    open: opts.open
+  });
+  log.ok(`已取回。产物目录：${outDir}`);
+}
+
+// src/commands/upgrade.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
+var CLIENT_UPGRADE = "irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex";
+function run(cmd) {
+  const r = spawnSync3(cmd, { stdio: "inherit", shell: true });
+  return r.status ?? 1;
+}
+function registerUpgrade(program2) {
+  program2.command("upgrade").description("升级 gtrk CLI 到最新版 + 刷新 skill（配置保留）；--check 只查不装").option("--check", "只检查有没有新版本，不执行升级").action(async (opts) => {
+    const cur = currentVersion();
+    log.step(`当前 v${cur}，查询最新版…`);
+    const latest = await latestVersion();
+    if (!latest) {
+      log.warn("查不到最新版本（网络问题？）。手动升级：npm i -g @gitruck/cli@latest");
+      log.info(`客户端（桌面端）升级：${CLIENT_UPGRADE}`);
       return;
     }
-    const b = raw;
-    if (!isNonEmptyStr(b.id))
-      errors.push(`${tag}：缺 id`);
-    else if (!/^B\d{2,}$/.test(b.id))
-      errors.push(`${b.id}：id 须为 "B"+两位起序号（如 B01）`);
-    else if (seenBeatIds.has(b.id))
-      errors.push(`${b.id}：beat id 重复`);
-    else
-      seenBeatIds.add(b.id);
-    if (!enumOk(b.base_track, BASE_TRACKS))
-      errors.push(`${tag}：base_track 非法（三选一：${BASE_TRACKS.join(" | ")}）`);
-    if (!enumOk(b.lane, LANES))
-      errors.push(`${tag}：lane 非法（四选一：${LANES.join(" | ")}）`);
-    if (!enumOk(b.narrative, NARRATIVES))
-      errors.push(`${tag}：narrative 非法（八枚举之一）`);
-    if (!enumOk(b.container_stage, CONTAINER_STAGES))
-      errors.push(`${tag}：container_stage 非法（七枚举之一）`);
-    if (!enumOk(b.irreplaceability, IRREPLACEABILITY))
-      errors.push(`${tag}：irreplaceability 非法（四枚举之一）`);
-    if (!isNonEmptyStr(b.rhythm))
-      errors.push(`${tag}：缺 rhythm（人读节奏标签）`);
-    if (!isNonEmptyStr(b.visual_task))
-      errors.push(`${tag}：缺 visual_task（一句话视觉任务）`);
-    const span = b.span;
-    let fromIdx = -1;
-    let toIdx = -1;
-    if (!span || !isNonEmptyStr(span.from) || !isNonEmptyStr(span.to)) {
-      errors.push(`${tag}：缺 span.from / span.to（utterance id 区间）`);
-    } else {
-      if (!idIndex.has(span.from))
-        errors.push(`${tag}：span.from 引用了不存在的 utterance id ${span.from}`);
-      else
-        fromIdx = idIndex.get(span.from);
-      if (!idIndex.has(span.to))
-        errors.push(`${tag}：span.to 引用了不存在的 utterance id ${span.to}`);
-      else
-        toIdx = idIndex.get(span.to);
-      if (fromIdx >= 0 && toIdx >= 0) {
-        if (fromIdx > toIdx)
-          errors.push(`${tag}：区间倒序（span.from ${span.from} 晚于 span.to ${span.to}）`);
-        else if (isNonEmptyStr(b.id))
-          ranges.push({ id: b.id, from: fromIdx, to: toIdx });
-      }
+    if (cmpSemver(latest, cur) <= 0) {
+      log.ok(`已是最新版 v${cur}。`);
+      log.info(`客户端（桌面端）如需升级：${CLIENT_UPGRADE}`);
+      return;
     }
-    validateHandoff(tag, b, errors, warnings);
-    if (b.aux_layers != null) {
-      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));
+    log.info(`发现新版本 v${latest}（当前 v${cur}）。`);
+    if (opts.check) {
+      log.info("跑 `gtrk upgrade` 升级（会保留你现有的配置）。");
+      return;
     }
-  });
-  const sorted = [...ranges].sort((a, b) => a.from - b.from || a.to - b.to);
-  for (let i = 1;i < sorted.length; i++) {
-    const prev = sorted[i - 1];
-    const cur = sorted[i];
-    if (cur.from <= prev.to) {
-      errors.push(`${prev.id} 与 ${cur.id}：utterance 区间重叠（beats 之间不允许交集）`);
+    log.step(`① 升级 CLI → v${latest}…`);
+    if (run("npm i -g @gitruck/cli@latest") !== 0) {
+      log.err("升级失败。手动重试：npm i -g @gitruck/cli@latest（若报权限，按你的 npm 全局目录权限处理）");
+      process.exitCode = 1;
+      return;
     }
-  }
-  return { errors, warnings };
-}
-function validateHandoff(tag, b, errors, warnings) {
-  const lane = b.lane;
-  const handoff = b.handoff;
-  if (lane === "A_ROLL") {
-    if (handoff != null)
-      warnings.push(`${tag}：A_ROLL 不应带 handoff，已忽略`);
-    return;
-  }
-  if (lane === "RRV_MG") {
-    if (!handoff || typeof handoff.duration_hint !== "number") {
-      errors.push(`${tag}：RRV_MG 的 handoff.duration_hint 必填（秒，数值）`);
+    log.step("② 刷新 /gtrk-oralcut skill…");
+    if (run("gtrk skills install") !== 0) {
+      log.warn("skill 没刷成，手动跑一次：gtrk skills install");
     }
-    return;
-  }
-  if (lane === "FILM_BROLL") {
-    const q = handoff?.queries;
-    if (!Array.isArray(q) || q.length === 0 || !q.every((x) => isNonEmptyStr(x))) {
-      errors.push(`${tag}：FILM_BROLL 缺检索 query（handoff.queries 必须为非空字符串数组）`);
+    log.ok(`已升级到 v${latest}。配置原样保留，直接接着用即可（gtrk doctor 可自检）。`);
+    log.info(`客户端（桌面端）如需一起升级：${CLIENT_UPGRADE}`);
+  });
+}
+
+// src/commands/render.ts
+import { resolve as resolve5, dirname as dirname3, join as join16, basename as basename6, extname as extname3 } from "node:path";
+import { existsSync as existsSync13 } from "node:fs";
+function registerRender(program2) {
+  program2.command("render <gtrk>").description("本地渲染：gtrk 工程按 EDL 用本地 ffmpeg 渲染成片 mp4（素材取原片本地路径）").option("-o, --out <file>", "输出 mp4 路径（缺省 = <gtrk 同目录>/<gtrk 名>.mp4）").option("--crf <n>", "视频质量 CRF 14-28（越小越清晰/文件越大，默认 18）").option("--codec <c>", "视频编码（默认 h264）").option("--ffmpeg-path <dir>", "指定 ffmpeg/ffprobe 所在目录（缺省 ~/.gitruck/ffmpeg → 系统）").option("--no-open", "完成后不自动打开产物目录").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON").action(async (gtrk, opts) => {
+    if (opts.json)
+      routeLogsToStderr();
+    const gtrkAbs = resolve5(gtrk);
+    if (!existsSync13(gtrkAbs))
+      throw new Error(`gtrk 工程不存在：${gtrkAbs}`);
+    const outMp4 = resolve5(opts.out ?? join16(dirname3(gtrkAbs), `${basename6(gtrkAbs, extname3(gtrkAbs))}.mp4`));
+    log.step(`▶ 本地渲染：${basename6(gtrkAbs)} → ${basename6(outMp4)}`);
+    const project = await readGtrkFile(gtrkAbs);
+    const result = await renderGtrk(project, outMp4, {
+      crf: opts.crf != null ? Number(opts.crf) : undefined,
+      codec: opts.codec,
+      ffmpegPath: opts.ffmpegPath,
+      onLine: (l) => {
+        const m = l.match(/time=(\S+)/);
+        if (m)
+          log.tick(`渲染中 ${m[1]}`);
+      }
+    });
+    log.tickEnd();
+    log.ok(`渲染完成：${outMp4}（${result.duration.toFixed(1)}s）`);
+    if (opts.open)
+      openFolder(dirname3(outMp4));
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, output: outMp4, duration: result.duration }));
     }
-    return;
-  }
+  });
 }
-function validateAux(tag, raw, idIndex, errors) {
-  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 非法（七类之一）`);
-  if (!isNonEmptyStr(a.role))
-    errors.push(`${tag}：缺 role（职责）`);
-  const m = a.mount;
-  if (m === "same_beat")
+
+// src/commands/split.ts
+import { resolve as resolve6, join as join18, dirname as dirname5, basename as basename8 } from "node:path";
+import { existsSync as existsSync14 } from "node:fs";
+import { readFile as readFile4, writeFile as writeFile6, mkdir as mkdir5 } from "node:fs/promises";
+import { createHash } from "node:crypto";
+
+// src/lib/projection.ts
+function r32(n) {
+  return Math.round(n * 1000) / 1000;
+}
+function normClip(c3) {
+  const clip_st = c3.clip_st ?? 0;
+  const track_st = c3.track_st ?? 0;
+  const dur = c3.duration ?? (c3.clip_ed != null ? c3.clip_ed - clip_st : 0);
+  const clip_ed = c3.clip_ed ?? clip_st + dur;
+  return { clip_st, clip_ed, track_st };
+}
+function pickMainVideoTrack(gtrk) {
+  const tracks = gtrk.video_track ?? [];
+  if (!tracks.length)
     return;
-  if (typeof m === "object" && m !== null) {
-    const mo = m;
-    if (isNonEmptyStr(mo.trigger)) {
-      if (!idIndex.has(mo.trigger))
-        errors.push(`${tag}：mount.trigger 引用了不存在的 utterance id ${mo.trigger}`);
-      return;
-    }
-    if (isNonEmptyStr(mo.from) && isNonEmptyStr(mo.to)) {
-      if (!idIndex.has(mo.from))
-        errors.push(`${tag}：mount.from 引用了不存在的 utterance id ${mo.from}`);
-      if (!idIndex.has(mo.to))
-        errors.push(`${tag}：mount.to 引用了不存在的 utterance id ${mo.to}`);
-      if (idIndex.has(mo.from) && idIndex.has(mo.to) && idIndex.get(mo.from) > idIndex.get(mo.to)) {
-        errors.push(`${tag}：mount 区间倒序`);
-      }
-      return;
+  let best = tracks[0];
+  let bestIdx = best.track_index ?? 0;
+  for (const t of tracks) {
+    const idx = t.track_index ?? 0;
+    if (idx < bestIdx) {
+      best = t;
+      bestIdx = idx;
     }
   }
-  errors.push(`${tag}：mount 非法（应为 "same_beat" | {from,to} | {trigger}）`);
+  return best;
 }
-function buildLanding(doc, view, opts) {
-  const byId = new Map;
-  for (const id of opts.utteranceIds)
-    byId.set(id, []);
-  for (const u of view.utterances) {
-    if (u.dropped || u.track_st == null || u.track_ed == null)
-      continue;
-    if (!byId.has(u.id))
-      byId.set(u.id, []);
-    byId.get(u.id).push({ track_st: u.track_st, track_ed: u.track_ed });
-  }
-  const idIndex = new Map;
-  opts.utteranceIds.forEach((id, i) => idIndex.set(id, i));
-  const split = {
-    contract_version: doc.contract_version,
-    transcript_hash: doc.transcript_hash,
-    projected_at: opts.projectedAt,
-    beats: []
-  };
-  const dispatch = { rrv_mg: [], film_broll: [], ai_drama: [] };
-  const skipped = [];
-  const shrunk = [];
-  for (const beat of doc.beats) {
-    const fromIdx = idIndex.get(beat.span.from);
-    const toIdx = idIndex.get(beat.span.to);
-    const spanIds = opts.utteranceIds.slice(fromIdx, toIdx + 1);
-    const instances = spanIds.flatMap((id) => byId.get(id) ?? []);
-    const droppedCount = spanIds.filter((id) => (byId.get(id)?.length ?? 0) === 0).length;
-    if (instances.length === 0) {
-      skipped.push({ beat: beat.id, reason: "span 内全部 utterance 被剪，未落轨" });
-      continue;
-    }
-    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 };
-    if (isShrunk)
-      metaBeat.shrunk = true;
-    if (beat.lane !== "A_ROLL" && beat.handoff)
-      metaBeat.handoff = beat.handoff;
-    split.beats.push(metaBeat);
-    if (isShrunk) {
-      shrunk.push({ beat: beat.id, kept: spanIds.length - droppedCount, dropped: droppedCount, track_st, track_ed });
+function projectTranscript(transcript, gtrk, opts = {}) {
+  const materialId = String(transcript.material_id);
+  const mainTrack = pickMainVideoTrack(gtrk);
+  const clips = (mainTrack?.track_timeline ?? []).filter((c3) => c3.material != null && String(c3.material) === materialId).map(normClip);
+  const entries = [];
+  transcript.utterances.forEach((utt, sourceIndex) => {
+    const totalWords = utt.words?.length ?? 0;
+    const instances = [];
+    for (const clip of clips) {
+      const surviving = [];
+      for (const word of utt.words ?? []) {
+        const s = Math.max(word.st, clip.clip_st);
+        const e = Math.min(word.ed, clip.clip_ed);
+        if (e > s) {
+          surviving.push({
+            w: word.w,
+            track_st: r32(clip.track_st + (s - clip.clip_st)),
+            track_ed: r32(clip.track_st + (e - clip.clip_st))
+          });
+        }
+      }
+      if (surviving.length) {
+        instances.push({
+          track_st: Math.min(...surviving.map((x) => x.track_st)),
+          track_ed: Math.max(...surviving.map((x) => x.track_ed)),
+          kept_words: surviving.length,
+          words: surviving
+        });
+      }
     }
-    const h = beat.handoff ?? {};
-    const compositionId = `${opts.projectSlug}-${beat.id}`;
-    if (beat.lane === "RRV_MG") {
-      dispatch.rrv_mg.push({
-        beat: beat.id,
-        composition_id: compositionId,
-        duration: typeof h.duration_hint === "number" ? h.duration_hint : null,
-        theme: h.theme,
-        bg: h.bg,
-        slug_hint: h.slug_hint,
-        track_st,
-        track_ed
+    if (!instances.length) {
+      entries.push({
+        id: utt.id,
+        text: utt.text,
+        dropped: true,
+        sourceIndex,
+        instIndex: 0,
+        track_st: null,
+        track_ed: null,
+        kept_words: 0,
+        total_words: totalWords,
+        words: [],
+        sortKey: 0
       });
-    } else if (beat.lane === "FILM_BROLL") {
-      dispatch.film_broll.push({
-        beat: beat.id,
-        queries: Array.isArray(h.queries) ? h.queries : [],
-        shots: h.shots,
-        per_shot_sec: h.per_shot_sec,
-        exclude: h.exclude,
-        track_st,
-        track_ed
+    } else {
+      instances.sort((a, b) => a.track_st - b.track_st);
+      instances.forEach((inst, instIndex) => {
+        entries.push({
+          id: utt.id,
+          text: utt.text,
+          dropped: false,
+          sourceIndex,
+          instIndex,
+          track_st: inst.track_st,
+          track_ed: inst.track_ed,
+          kept_words: inst.kept_words,
+          total_words: totalWords,
+          words: inst.words,
+          sortKey: inst.track_st
+        });
       });
-    } else if (beat.lane === "AI_DRAMA") {
-      dispatch.ai_drama.push({ beat: beat.id, ...h, track_st, track_ed });
-    }
-  }
-  return { split, dispatch, skipped, shrunk };
-}
-function renderSplitMarkdown(doc, landing, meta) {
-  const L = [];
-  const metaById = new Map(landing.split.beats.map((b) => [b.id, b]));
-  const skippedIds = new Set(landing.skipped.map((s) => s.beat));
-  L.push(`# 视觉拆分稿（${meta.projectSlug}）`);
-  L.push("");
-  L.push(`- contract_version：\`${doc.contract_version}\``);
-  L.push(`- transcript_hash：\`${doc.transcript_hash}\``);
-  L.push(`- projected_at：\`${meta.projectedAt}\``);
-  L.push(`- beats：${doc.beats.length}（落轨 ${landing.split.beats.length} · 跳过 ${landing.skipped.length} · 收缩 ${landing.shrunk.length}）`);
-  L.push("");
-  L.push("# Beat Timeline");
-  L.push("");
-  for (const beat of doc.beats) {
-    const mb = metaById.get(beat.id);
-    L.push(`## ${beat.id}${skippedIds.has(beat.id) ? "（整段被剪 · 跳过）" : mb?.shrunk ? "（部分被剪 · 已收缩）" : ""}`);
-    L.push(`- 文稿范围：\`${beat.span.from} … ${beat.span.to}\``);
-    L.push(`- 底轨：\`${beat.base_track}\``);
-    L.push(`- 主层：\`${beat.lane}\``);
-    L.push(`- 叙事功能：\`${beat.narrative}\``);
-    L.push(`- 容器阶段：\`${beat.container_stage}\``);
-    if (beat.rhythm)
-      L.push(`- 节奏标签：\`${beat.rhythm}\``);
-    L.push(`- 视觉任务：${beat.visual_task}`);
-    L.push(`- 不可替代性：\`${beat.irreplaceability}\``);
-    if (mb)
-      L.push(`- 轨道时码：\`${mb.track_st}s … ${mb.track_ed}s\``);
-    if (beat.callback_of)
-      L.push(`- 回扣对象：\`${beat.callback_of}\``);
-    for (const a of beat.aux_layers ?? []) {
-      const mount = a.mount === "same_beat" ? "同 beat" : ("trigger" in a.mount) ? `触发 ${a.mount.trigger}` : `${a.mount.from} … ${a.mount.to}`;
-      L.push(`  - 辅助层 \`${a.type}\`（${mount}）：${a.role}`);
     }
-    L.push("");
-  }
-  L.push("# Production Queues");
-  L.push("");
-  L.push("## A_ROLL Queue");
-  for (const b of doc.beats.filter((x) => x.lane === "A_ROLL" && !skippedIds.has(x.id))) {
-    L.push(`- \`${b.id}\` ${b.visual_task}`);
-  }
-  L.push("");
-  L.push("## RRV_MG Queue");
-  for (const r of landing.dispatch.rrv_mg) {
-    L.push(`- \`${r.beat}\` composition_id=\`${r.composition_id}\`${r.duration != null ? ` · ${r.duration}s` : ""}`);
+  });
+  let maxEd = 0;
+  for (const e of entries) {
+    if (e.dropped)
+      e.sortKey = maxEd;
+    else
+      maxEd = Math.max(maxEd, e.track_ed ?? maxEd);
   }
-  L.push("");
-  L.push("## AI_DRAMA Queue");
-  for (const a of landing.dispatch.ai_drama)
-    L.push(`- \`${a.beat}\` ${a.track_st}s…${a.track_ed}s`);
-  L.push("");
-  L.push("## FILM_BROLL Queue");
-  for (const f of landing.dispatch.film_broll)
-    L.push(`- \`${f.beat}\` queries=[${f.queries.join(" / ")}]`);
-  L.push("");
-  return L.join(`
-`);
+  entries.sort((a, b) => a.sortKey - b.sortKey || a.sourceIndex - b.sourceIndex || a.instIndex - b.instIndex);
+  const utterances = entries.map((e) => {
+    const u = {
+      id: e.id,
+      text: e.text,
+      track_st: e.track_st,
+      track_ed: e.track_ed,
+      dropped: e.dropped,
+      kept_words: e.kept_words,
+      total_words: e.total_words
+    };
+    if (opts.words)
+      u.words = e.words;
+    return u;
+  });
+  return {
+    transcript_hash: transcript.text_hash,
+    projected_at: opts.projectedAt ?? new Date().toISOString(),
+    utterances
+  };
 }
 
 // src/lib/gtrk-writeback.ts
-import { readFileSync as readFileSync3, statSync, writeFileSync as writeFileSync2, renameSync, unlinkSync } from "node:fs";
-import { dirname as dirname4, join as join15, basename as basename7 } from "node:path";
+import { readFileSync as readFileSync4, statSync, writeFileSync as writeFileSync2, renameSync, unlinkSync } from "node:fs";
+import { dirname as dirname4, join as join17, basename as basename7 } from "node:path";
 import { randomBytes as randomBytes2 } from "node:crypto";
 function readGtrk(path) {
-  const raw = readFileSync3(path, "utf8");
+  const raw = readFileSync4(path, "utf8");
   let gtrk;
   try {
     gtrk = JSON.parse(raw);
@@ -6464,7 +6833,23 @@ function writeStructMetaSplit(path, gtrk, splitObj, expectedMtimeMs) {
   }
   const nextStructMeta = { ...gtrk.struct_meta ?? {}, split: splitObj };
   const next = { ...gtrk, struct_meta: nextStructMeta };
-  const tmp = join15(dirname4(path), `.${basename7(path)}.${randomBytes2(6).toString("hex")}.tmp`);
+  const tmp = join17(dirname4(path), `.${basename7(path)}.${randomBytes2(6).toString("hex")}.tmp`);
+  try {
+    writeFileSync2(tmp, JSON.stringify(next, null, 2));
+    renameSync(tmp, path);
+  } catch (e) {
+    try {
+      unlinkSync(tmp);
+    } catch {}
+    throw e;
+  }
+}
+function writeGtrkAtomic(path, next, expectedMtimeMs) {
+  const cur = statSync(path).mtimeMs;
+  if (cur !== expectedMtimeMs) {
+    throw new Error("工程文件在 matrix 运行期间被外部修改（保存冲突），已拒绝写入；请关闭客户端未保存的工程或重跑（plan 与已下载代理均保留）");
+  }
+  const tmp = join17(dirname4(path), `.${basename7(path)}.${randomBytes2(6).toString("hex")}.tmp`);
   try {
     writeFileSync2(tmp, JSON.stringify(next, null, 2));
     renameSync(tmp, path);
@@ -6479,12 +6864,12 @@ function writeStructMetaSplit(path, gtrk, splitObj, expectedMtimeMs) {
 // src/commands/split.ts
 var TRANSCRIPT_MISSING = "工程目录内找不到 transcript.json（可能是旧任务产物）：请用新版本重跑 gtrk oralcut（恒出 transcript），" + "或（规划中）用 transcribe 生成后再拆分；本命令不做降级猜测。";
 function registerSplit(program2) {
-  program2.command("split [splitdoc]").description("视觉拆分派单器：无 positional=导出投影视图；带拆分稿=校验落地（写回 struct_meta.split + dispatch）").option("--project <dir>", "oralcut 产物目录（自动定位 gtrk/project.gtrk 与 transcript/transcript.json）").option("--gtrk <path>", "显式指定 .gtrk 工程文件（非标准布局兜底）").option("--transcript <path>", "显式指定 transcript.json（非标准布局兜底）").option("--md", "落地时额外渲染人读稿 split/visual-split.md").option("--words", "视图模式附字级明细（缺省只出句级）").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON").action(async (splitdoc, opts) => {
+  program2.command("split [splitdoc]").description("视觉拆分派单器：无 positional=导出投影视图；带拆分稿=校验落地（写回 struct_meta.split + dispatch）").option("--project <dir>", "oralcut 产物目录（自动定位 gtrk/project.gtrk 与 transcript/transcript.json）").option("--gtrk <path>", "显式指定 .gtrk 工程文件（非标准布局兜底）").option("--transcript <path>", "显式指定 transcript.json（非标准布局兜底）").option("--column <id>", "栏目配置 id（~/.gitruck/columns/<id>.json；缺省取 config defaultColumn，再缺省内置默认栏目）").option("--md", "落地时额外渲染人读稿 split/visual-split.md").option("--words", "视图模式附字级明细（缺省只出句级）").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON").action(async (splitdoc, opts) => {
     await runSplit(splitdoc, opts);
   });
 }
 function firstExisting(cands) {
-  return cands.find((p) => existsSync13(p));
+  return cands.find((p) => existsSync14(p));
 }
 function resolvePaths(opts) {
   const project = opts.project ? resolve6(opts.project) : undefined;
@@ -6492,20 +6877,20 @@ function resolvePaths(opts) {
   if (opts.gtrk) {
     gtrkPath = resolve6(opts.gtrk);
   } else if (project) {
-    gtrkPath = firstExisting([join16(project, "gtrk", "project.gtrk"), join16(project, "project.gtrk")]) ?? join16(project, "gtrk", "project.gtrk");
+    gtrkPath = firstExisting([join18(project, "gtrk", "project.gtrk"), join18(project, "project.gtrk")]) ?? join18(project, "gtrk", "project.gtrk");
   } else {
     throw new Error("需 --project <目录> 或显式 --gtrk <path>");
   }
-  if (!existsSync13(gtrkPath))
+  if (!existsSync14(gtrkPath))
     throw new Error(`找不到工程文件：${gtrkPath}`);
   let transcriptPath;
   if (opts.transcript)
     transcriptPath = resolve6(opts.transcript);
   else if (project)
     transcriptPath = firstExisting([
-      join16(project, "transcript", "transcript.json"),
-      join16(project, "json", "transcript.json"),
-      join16(project, "transcript.json")
+      join18(project, "transcript", "transcript.json"),
+      join18(project, "json", "transcript.json"),
+      join18(project, "transcript.json")
     ]);
   const baseDir = project ?? dirname5(gtrkPath);
   return { baseDir, gtrkPath, transcriptPath };
@@ -6530,15 +6915,15 @@ async function runSplit(splitdoc, opts) {
   return splitdoc ? runLand(resolve6(splitdoc), baseDir, gtrkPath, transcriptPath, opts) : runView(baseDir, gtrkPath, transcriptPath, opts);
 }
 async function runView(baseDir, gtrkPath, transcriptPath, opts) {
-  if (!transcriptPath || !existsSync13(transcriptPath))
+  if (!transcriptPath || !existsSync14(transcriptPath))
     throw new Error(TRANSCRIPT_MISSING);
   log.step("▶ 导出投影视图（transcript × 当刻 .gtrk）…");
   const transcript = await loadTranscript(transcriptPath);
   const { gtrk } = readGtrk(gtrkPath);
   const view = projectTranscript(transcript, gtrk, { words: opts.words });
-  const splitDir = join16(baseDir, "split");
+  const splitDir = join18(baseDir, "split");
   await mkdir5(splitDir, { recursive: true });
-  const viewPath = join16(splitDir, "view.json");
+  const viewPath = join18(splitDir, "view.json");
   await writeFile6(viewPath, JSON.stringify(view, null, 2));
   const dropped = view.utterances.filter((u) => u.dropped).length;
   log.ok(`投影视图已生成：${viewPath}（${view.utterances.length} 条，其中 ${dropped} 条被剪）`);
@@ -6556,16 +6941,24 @@ async function runView(baseDir, gtrkPath, transcriptPath, opts) {
   return result;
 }
 async function runLand(splitdocPath, baseDir, gtrkPath, transcriptPath, opts) {
-  if (!existsSync13(splitdocPath))
+  if (!existsSync14(splitdocPath))
     throw new Error(`找不到拆分稿：${splitdocPath}`);
-  if (!transcriptPath || !existsSync13(transcriptPath))
+  if (!transcriptPath || !existsSync14(transcriptPath))
     throw new Error(TRANSCRIPT_MISSING);
   log.step("▶ 校验拆分稿并落地…");
   const doc = JSON.parse(await readFile4(splitdocPath, "utf8"));
   const transcript = await loadTranscript(transcriptPath);
   const { gtrk, mtimeMs } = readGtrk(gtrkPath);
   assertGtrkV1(gtrk);
-  const ctx = { utteranceIds: transcript.utterances.map((u) => u.id), transcriptHash: transcript.text_hash };
+  const columnId = opts.column ?? readUserConfig().defaultColumn;
+  const resolved = resolveColumnConfig({ columnId });
+  for (const w of resolved.warnings)
+    log.warn(w);
+  const ctx = {
+    utteranceIds: transcript.utterances.map((u) => u.id),
+    transcriptHash: transcript.text_hash,
+    vocab: effectiveVocab(resolved.config)
+  };
   const { errors, warnings } = validateSplitDoc(doc, ctx);
   for (const w of warnings)
     log.warn(w);
@@ -6577,22 +6970,33 @@ async function runLand(splitdocPath, baseDir, gtrkPath, transcriptPath, opts) {
   const projectedAt = new Date().toISOString();
   const view = projectTranscript(transcript, gtrk, { projectedAt });
   const projectSlug = slugify(basename8(baseDir));
-  const landing = buildLanding(doc, view, { utteranceIds: ctx.utteranceIds, projectSlug, projectedAt });
+  const landing = buildLanding(doc, view, {
+    utteranceIds: ctx.utteranceIds,
+    projectSlug,
+    projectedAt,
+    sourceIndex: {
+      materialId: String(transcript.material_id),
+      utterances: new Map(transcript.utterances.map((u) => [u.id, { st: u.st, ed: u.ed }]))
+    }
+  });
   writeStructMetaSplit(gtrkPath, gtrk, landing.split, mtimeMs);
-  const splitDir = join16(baseDir, "split");
+  const splitDir = join18(baseDir, "split");
   await mkdir5(splitDir, { recursive: true });
-  const dispatchPath = join16(splitDir, "dispatch.json");
+  const dispatchPath = join18(splitDir, "dispatch.json");
   await writeFile6(dispatchPath, JSON.stringify(landing.dispatch, null, 2));
   let mdPath = null;
   if (opts.md) {
-    mdPath = join16(splitDir, "visual-split.md");
+    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)
     log.warn(`收缩 ${s.beat}：${s.dropped} 句被剪，按存活 ${s.kept} 句包络 → ${s.track_st}s…${s.track_ed}s（建议人工复核）`);
+  if (landing.unhandledLanes.length > 0) {
+    log.warn(`未派单 lane：${landing.unhandledLanes.join("、")}——通过校验却无 dispatch 分支，落地静默丢队列（新增 lane 时请同步 buildLanding 分派）`);
+  }
   const result = {
     ok: true,
     mode: "land",
@@ -6603,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
     }
@@ -6613,12 +7017,1166 @@ async function runLand(splitdocPath, baseDir, gtrkPath, transcriptPath, opts) {
   return result;
 }
 
+// src/commands/matrix.ts
+import { resolve as resolve7, join as join19, dirname as dirname6, basename as basename9 } from "node:path";
+import { existsSync as existsSync15 } from "node:fs";
+import { readFile as readFile5, writeFile as writeFile7, mkdir as mkdir6 } from "node:fs/promises";
+
+// src/lib/matrix-lay.ts
+var BROLL_PREVIEW_DIR = "assets/broll-preview";
+var BROLL_MATERIAL_PREFIX = "broll-";
+var BROLL_META_CANDIDATE_CAP = 12;
+var SHOT_TARGET_DEFAULT = 3;
+var MIN_SHOT_SEC = 1.2;
+var SCORE_FLOOR_DEFAULT = 0.2;
+var MAX_SLOTS_PER_BEAT = 32;
+function mergedCandidates(beat) {
+  const all = [];
+  for (const q of beat.queries)
+    for (const r of q.results ?? [])
+      all.push(r);
+  return all.sort((a, b) => b.score - a.score);
+}
+function previewUrlFor(result) {
+  const direct = result.preview_url;
+  if (typeof direct === "string" && direct)
+    return direct;
+  const cover = result.cover_url;
+  if (typeof cover === "string") {
+    const derived = cover.replace(/\/keyframe\/([^/]+)\/cover\.jpg.*$/, "/preview/$1.mp4");
+    if (derived !== cover)
+      return derived;
+  }
+  return null;
+}
+function previewDims(width, height) {
+  if (!width || !height || width <= 0 || height <= 0)
+    return;
+  if (width <= 640)
+    return [width, height];
+  const h = Math.max(2, Math.round(height * 640 / width / 2) * 2);
+  return [640, h];
+}
+var r33 = (n) => Math.round(n * 1000) / 1000;
+function buildQueryPools(beat, scoreFloor) {
+  const out = [];
+  for (const q of beat.queries) {
+    const pool = [];
+    for (const cand of q.results ?? []) {
+      if (cand.excluded_hint)
+        continue;
+      const segs = cand.segments?.length ? cand.segments : [{ start: 0, end: cand.duration ?? SHOT_TARGET_DEFAULT, best: (cand.duration ?? SHOT_TARGET_DEFAULT) / 2, score: cand.score }];
+      for (const seg of segs) {
+        if (seg.score < scoreFloor)
+          continue;
+        pool.push({ cand, seg, query: q.query, key: `${cand.clip_id}@${seg.start}` });
+      }
+    }
+    pool.sort((a, b) => b.seg.score - a.seg.score);
+    if (pool.length)
+      out.push({ query: q.query, pool });
+  }
+  return out;
+}
+function pairAvail(p) {
+  const dur = typeof p.cand.duration === "number" && p.cand.duration > 0 ? p.cand.duration : undefined;
+  return dur ?? Math.max(0, p.seg.end - p.seg.start);
+}
+function hashStr(s) {
+  let h = 2166136261;
+  for (let i = 0;i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = a + 1831565813 >>> 0;
+    let t = a;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function shotRange(beat, span) {
+  const shots = typeof beat.requested_shots === "number" && beat.requested_shots > 0 ? beat.requested_shots : undefined;
+  const anchor = typeof beat.per_shot_sec === "number" && beat.per_shot_sec > 0 ? beat.per_shot_sec : shots ? Math.min(Math.max(span / shots, 1.5), 6) : undefined;
+  if (anchor === undefined)
+    return [2, 4];
+  const lo = Math.max(1.5, anchor * 0.8);
+  const hi = Math.max(lo + 0.5, Math.min(8, anchor * 1.6));
+  return [lo, hi];
+}
+function fillBeatTrack(opts) {
+  const { beat, trackOrder, consumed, scoreFloor } = opts;
+  const span = beat.track_ed - beat.track_st;
+  if (!(span > 0))
+    return [];
+  const [shotMin, shotMax] = shotRange(beat, span);
+  const rand = mulberry32(hashStr(`${beat.beat}#${trackOrder}`));
+  const pools = buildQueryPools(beat, scoreFloor);
+  if (!pools.length)
+    return [];
+  const slots = [];
+  let cursor = beat.track_st;
+  let prevClip = null;
+  let lastPick = null;
+  let gapRun = 0;
+  for (let slotIdx = 0;slotIdx < MAX_SLOTS_PER_BEAT; slotIdx++) {
+    const remaining = beat.track_ed - cursor;
+    if (remaining < MIN_SHOT_SEC)
+      break;
+    let dTarget;
+    if (remaining <= shotMax)
+      dTarget = remaining;
+    else if (remaining < shotMax + shotMin)
+      dTarget = remaining / 2;
+    else
+      dTarget = shotMin + rand() * (shotMax - shotMin);
+    const minLen = Math.min(MIN_SHOT_SEC, remaining);
+    let pick = null;
+    for (let t = 0;t < pools.length && !pick; t++) {
+      const { pool } = pools[(slotIdx + t) % pools.length];
+      pick = pool.find((p) => !consumed.has(p.key) && p.cand.clip_id !== prevClip && pairAvail(p) >= minLen) ?? null;
+    }
+    if (!pick) {
+      gapRun++;
+      if (gapRun >= 2)
+        break;
+      cursor += Math.min(dTarget, remaining);
+      prevClip = null;
+      continue;
+    }
+    gapRun = 0;
+    const d = Math.min(dTarget, pairAvail(pick), remaining);
+    const dur = typeof pick.cand.duration === "number" && pick.cand.duration > 0 ? pick.cand.duration : undefined;
+    const lo = dur !== undefined ? 0 : pick.seg.start;
+    const hi = dur ?? pick.seg.end;
+    const maxSt = Math.max(lo, hi - d);
+    const clipSt = Math.min(Math.max(pick.seg.best - d / 2, lo), maxSt);
+    slots.push({
+      clip_id: pick.cand.clip_id,
+      query: pick.query,
+      score: pick.seg.score,
+      clip_st: r33(clipSt),
+      clip_ed: r33(clipSt + d),
+      track_st: r33(cursor),
+      track_ed: r33(cursor + d)
+    });
+    consumed.add(pick.key);
+    prevClip = pick.cand.clip_id;
+    lastPick = pick;
+    cursor += d;
+  }
+  const last = slots[slots.length - 1];
+  if (last && lastPick) {
+    const tail = beat.track_ed - last.track_ed;
+    if (tail > 0.000001 && tail < MIN_SHOT_SEC) {
+      const dur = typeof lastPick.cand.duration === "number" && lastPick.cand.duration > 0 ? lastPick.cand.duration : undefined;
+      const hi = dur ?? lastPick.seg.end;
+      const ext = Math.min(tail, Math.max(0, hi - last.clip_ed));
+      if (ext > 0.000001) {
+        last.clip_ed = r33(last.clip_ed + ext);
+        last.track_ed = r33(last.track_ed + ext);
+      }
+    }
+  }
+  return slots;
+}
+function planBeatFills(plan, lay, scoreFloor) {
+  const fills = new Map;
+  const clipIds = new Set;
+  const consumed = new Set;
+  for (const beat of plan.beats) {
+    const perTrack = [];
+    for (let k = 0;k < Math.max(0, lay); k++) {
+      const slots = fillBeatTrack({ beat, trackOrder: k, consumed, scoreFloor });
+      perTrack.push(slots);
+      for (const s of slots)
+        clipIds.add(s.clip_id);
+    }
+    fills.set(beat.beat, perTrack);
+  }
+  return { fills, clipIds };
+}
+function layBrollTracks(opts) {
+  const { gtrk, plan, lay, fills, downloads } = opts;
+  const videoTracks = [...gtrk.video_track ?? []];
+  const materials = [...gtrk.materials ?? []];
+  const structMeta = { ...gtrk.struct_meta ?? {} };
+  const prevBroll = structMeta.broll;
+  const prevIndices = new Set(Array.isArray(prevBroll?.lay_tracks) ? prevBroll.lay_tracks.filter((x) => typeof x === "number") : []);
+  const removedTracks = videoTracks.filter((t) => typeof t.track_index === "number" && prevIndices.has(t.track_index));
+  const keptTracks = videoTracks.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 m = c3.material;
+      if (typeof m === "string" && m.startsWith(BROLL_MATERIAL_PREFIX))
+        removedMaterialIds.add(m);
+    }
+  }
+  const keptMaterials = materials.filter((m) => !(typeof m.id === "string" && removedMaterialIds.has(m.id)));
+  const canvas = Array.isArray(gtrk.video_size) ? gtrk.video_size : [1920, 1080];
+  const baseIndex = keptTracks.reduce((mx, t) => Math.max(mx, typeof t.track_index === "number" ? t.track_index : 0), -1) + 1;
+  const candById = new Map;
+  for (const beat of plan.beats)
+    for (const c3 of mergedCandidates(beat))
+      if (!candById.has(c3.clip_id))
+        candById.set(c3.clip_id, c3);
+  const metaBeats = [];
+  const newMaterialsById = new Map;
+  const trackClips = new Map;
+  let laidClips = 0;
+  let beatsWithCandidates = 0;
+  for (const beat of plan.beats) {
+    const merged = mergedCandidates(beat);
+    if (merged.length > 0)
+      beatsWithCandidates++;
+    const perTrack = fills.get(beat.beat) ?? [];
+    const laid = [];
+    for (let k = 0;k < perTrack.length; k++) {
+      const slots = perTrack[k].filter((s) => downloads.has(s.clip_id));
+      if (!slots.length)
+        continue;
+      const trackIndex = baseIndex + k;
+      const bucket = trackClips.get(trackIndex) ?? [];
+      slots.forEach((s, i) => {
+        const materialId = `${BROLL_MATERIAL_PREFIX}${s.clip_id}`;
+        if (!newMaterialsById.has(materialId)) {
+          const cand = candById.get(s.clip_id);
+          const dims = previewDims(cand?.width, cand?.height);
+          const mat = { id: materialId, path: downloads.get(s.clip_id).rel };
+          if (typeof cand?.duration === "number")
+            mat.duration = cand.duration;
+          if (dims)
+            mat.video_size = dims;
+          if (typeof cand?.fps === "number")
+            mat.video_rate = cand.fps;
+          newMaterialsById.set(materialId, mat);
+        }
+        bucket.push({
+          clip_id: `${beat.beat}-broll-${k}-${i}`,
+          material: materialId,
+          clip_st: s.clip_st,
+          clip_ed: s.clip_ed,
+          track_st: s.track_st,
+          track_ed: s.track_ed,
+          duration: r33(s.track_ed - s.track_st)
+        });
+        laidClips++;
+      });
+      trackClips.set(trackIndex, bucket);
+      laid.push({ order: k, clip_id: slots[0].clip_id, track_index: trackIndex, slots });
+    }
+    const metaBeat = {
+      beat: beat.beat,
+      track_st: beat.track_st,
+      track_ed: beat.track_ed,
+      candidates: merged.slice(0, BROLL_META_CANDIDATE_CAP).map((c3) => {
+        const dl = downloads.get(c3.clip_id);
+        const seg = c3.segments?.[0];
+        return {
+          clip_id: c3.clip_id,
+          score: c3.score,
+          cover_url: c3.cover_url,
+          preview_path: dl?.rel ?? null,
+          source: dl?.source ?? null,
+          raw_url: c3.url,
+          seg: seg ? { start: seg.start, end: seg.end, best: seg.best } : null
+        };
+      }),
+      laid,
+      pinned: null
+    };
+    if (typeof beat.per_shot_sec === "number")
+      metaBeat.per_shot_sec = beat.per_shot_sec;
+    metaBeats.push(metaBeat);
+  }
+  const createdTracks = [...trackClips.entries()].filter(([, clips]) => clips.length > 0).sort((a, b) => a[0] - b[0]).map(([track_index, clips]) => ({
+    track_index,
+    track_size: [canvas[0], canvas[1]],
+    muted: false,
+    track_timeline: clips.sort((a, b) => a.track_st - b.track_st)
+  }));
+  const broll = {
+    contract_version: "v1",
+    generated_at: opts.generatedAt,
+    plan_path: opts.planPath,
+    lay_tracks: createdTracks.map((t) => t.track_index),
+    confirmed: false,
+    beats: metaBeats
+  };
+  const next = {
+    ...gtrk,
+    materials: [...keptMaterials, ...newMaterialsById.values()],
+    video_track: [...keptTracks, ...createdTracks],
+    struct_meta: { ...structMeta, broll }
+  };
+  return {
+    next,
+    summary: { laidTracks: broll.lay_tracks, laidClips, beatsWithCandidates },
+    broll
+  };
+}
+
+// src/lib/matrix.ts
+var URL_TTL_NOTE = "结果 url 带签名默认 24h 过期；过期后重跑 gtrk matrix 即重签（plan 幂等重生成）。";
+var ENDPOINTS = {
+  internal: "/task/custom/search",
+  external: "/task/video_clip_search"
+};
+function decideRoute(memberType) {
+  const tier = memberType === "internal" ? "internal" : "external";
+  return { tier, endpoint: ENDPOINTS[tier] };
+}
+var WIDE_RECALL_FACTOR = 3;
+var TOP_K_MIN = 10;
+var TOP_K_MAX = 50;
+var TOP_K_DEFAULT = 10;
+function asPositiveInt(v) {
+  return typeof v === "number" && Number.isInteger(v) && v > 0 ? v : undefined;
+}
+function asPositiveNum(v) {
+  return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined;
+}
+function shotsToTopK(shots, override) {
+  if (override && override > 0)
+    return Math.min(Math.max(Math.floor(override), 1), TOP_K_MAX);
+  const n = asPositiveInt(shots);
+  if (!n)
+    return TOP_K_DEFAULT;
+  return Math.min(Math.max(n * WIDE_RECALL_FACTOR, TOP_K_MIN), TOP_K_MAX);
+}
+function trimFacets(defaults, allowed) {
+  if (!defaults || typeof defaults !== "object")
+    return;
+  const entries = Object.entries(defaults).filter(([k]) => !allowed || allowed.includes(k));
+  return entries.length ? Object.fromEntries(entries) : undefined;
+}
+var MATERIAL_CLASSES = ["real_shot", "concept"];
+function buildSearchBody(tier, query, dispatch, broll, overrides = {}) {
+  const body = { query, top_k: shotsToTopK(dispatch?.shots, overrides.topK) };
+  const perShot = asPositiveNum(dispatch?.per_shot_sec);
+  if (perShot)
+    body.filters = { min_duration: perShot };
+  if (tier === "internal") {
+    if (broll?.column_tag_ids?.length)
+      body.column_tag_ids = [...broll.column_tag_ids];
+    const mc = overrides.materialClass ?? broll?.material_class_policy;
+    if (mc && MATERIAL_CLASSES.includes(mc))
+      body.material_class = mc;
+    const facets = trimFacets(broll?.facet_defaults, broll?.facet_allowed);
+    if (facets)
+      body.facets = facets;
+  }
+  return body;
+}
+function strArr2(v) {
+  if (!Array.isArray(v))
+    return;
+  const out = v.filter((x) => typeof x === "string");
+  return out.length ? out : undefined;
+}
+function markExcluded(results, exclude) {
+  if (!exclude?.length)
+    return;
+  for (const r of results) {
+    if (typeof r.note === "string" && r.note && exclude.some((w) => r.note.includes(w))) {
+      r.excluded_hint = true;
+    }
+  }
+}
+function dedupeBeatQueries(queries) {
+  const bestByClip = new Map;
+  for (let qi = 0;qi < queries.length; qi++) {
+    for (const r of queries[qi].results ?? []) {
+      const prev = bestByClip.get(r.clip_id);
+      if (!prev || r.score > prev.r.score)
+        bestByClip.set(r.clip_id, { qi, r });
+    }
+  }
+  for (let qi = 0;qi < queries.length; qi++) {
+    const q = queries[qi];
+    if (!q.results)
+      continue;
+    q.results = q.results.filter((r) => {
+      const best = bestByClip.get(r.clip_id);
+      if (best.qi === qi && best.r === r)
+        return true;
+      const list = best.r.also_matched_queries ??= [];
+      if (!list.includes(q.query))
+        list.push(q.query);
+      return false;
+    });
+  }
+}
+function buildPlanBeat(entry, outcomes) {
+  const beat = {
+    beat: entry.beat,
+    track_st: entry.track_st,
+    track_ed: entry.track_ed,
+    queries: []
+  };
+  const shots = asPositiveInt(entry.shots);
+  if (shots)
+    beat.requested_shots = shots;
+  const perShot = asPositiveNum(entry.per_shot_sec);
+  if (perShot)
+    beat.per_shot_sec = perShot;
+  const exclude = strArr2(entry.exclude);
+  if (exclude)
+    beat.exclude = exclude;
+  for (const o of outcomes) {
+    if (o.error) {
+      beat.queries.push({ query: o.query, error: o.error });
+      continue;
+    }
+    const results = (o.data?.results ?? []).map((r) => ({ ...r }));
+    markExcluded(results, exclude);
+    const pq = { query: o.query, results };
+    if (typeof o.data?.recalled === "number")
+      pq.recalled = o.data.recalled;
+    beat.queries.push(pq);
+  }
+  dedupeBeatQueries(beat.queries);
+  return beat;
+}
+function buildPlan(opts) {
+  const plan = {
+    plan_version: "v1",
+    generated_at: opts.generatedAt,
+    member_type: opts.memberType,
+    url_ttl_note: URL_TTL_NOTE,
+    beats: opts.beats
+  };
+  if (opts.projectSlug)
+    plan.project_slug = opts.projectSlug;
+  if (opts.columnId)
+    plan.column_id = opts.columnId;
+  return plan;
+}
+function classifyApiError(code, msg) {
+  switch (code) {
+    case 400:
+      return `请求体非法（网关校验）：${msg || "请求参数或请求体格式错误"}`;
+    case 6502:
+      return "鉴权失败——检查 API Key（gtrk init 重配）";
+    case 403:
+      return "非矩阵成员或身份可能已变更——矩阵成员口（custom/search）仅对 internal 档位开放";
+    case 6401:
+      return "检索上游故障，或检索参数/栏目配置非法（如 facets 值拼写）——稍后重试仍失败请检查栏目配置的 broll 块";
+    case 6402:
+      return "检索上游超时——稍后重试";
+    default:
+      return `云端错误 (code=${code ?? "?"})：${msg || "未知错误"}`;
+  }
+}
+var SEARCH_TIMEOUT_MS = 25000;
+async function probeMemberType(cfg) {
+  const res = await fetch(`${cfg.base}/user/get_user_info`, {
+    method: "POST",
+    headers: { accept: "application/json", Authorization: cfg.apiKey },
+    body: "",
+    signal: AbortSignal.timeout(SEARCH_TIMEOUT_MS)
+  });
+  const r = await parseJson(res);
+  if (r.code !== 200)
+    throw new CloudError(r.code, classifyApiError(r.code, r.msg));
+  return decideRoute(r.data?.matrix_member_type).tier;
+}
+function parseClipIdSafe(text, status) {
+  try {
+    return JSON.parse(text.replace(/"clip_id"\s*:\s*(\d+)/g, '"clip_id":"$1"'));
+  } catch {
+    throw new Error(`服务响应解析失败 (HTTP ${status})`);
+  }
+}
+async function searchOnce(cfg, tier, body) {
+  const res = await fetch(`${cfg.base}${ENDPOINTS[tier]}`, {
+    method: "POST",
+    headers: { accept: "application/json", "Content-Type": "application/json", Authorization: cfg.apiKey },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(SEARCH_TIMEOUT_MS)
+  });
+  const r = parseClipIdSafe(await res.text(), res.status);
+  if (r.code !== 200)
+    throw new CloudError(r.code, classifyApiError(r.code, r.msg));
+  return r.data ?? {};
+}
+
+// src/commands/matrix.ts
+function registerMatrix(program2) {
+  program2.command("matrix [words...]").description('B-roll 检索：无 positional=消费 split/dispatch.json 的 film_broll 队列产候选清单；`matrix search "<query>"`=单条 ad-hoc 检索').option("--project <dir>", "oralcut 产物目录（定位 split/dispatch.json 与产物落点）").option("--dispatch <path>", "显式指定 dispatch.json（非标准布局兜底）").option("--column <id>", "栏目配置 id（缺省取 config defaultColumn，再缺省内置默认栏目）").option("--top-k <n>", "每 query 候选数上限（覆盖派单 shots 翻译；服务端上限 50）").option("--material-class <c>", "素材类型 real_shot|concept（仅矩阵成员口；覆盖栏目 material_class_policy）").option("--lay <n>", "候选铺轨数：下载 preview 代理并在工程里平铺 N 条 B-roll 候选轨（默认 1；0=只出 plan 不铺轨）", "1").option("--score-floor <f>", "填充置信度地板：segment score 低于此值不采纳，槽位留空露主轨（默认 0.2）").option("--out <file>", "ad-hoc 模式：结果落文件（缺省输出 stdout）").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON").action(async (words, opts) => {
+    await runMatrix(parseAdhocQuery(words), opts);
+  });
+}
+function parseAdhocQuery(words) {
+  if (!words || words.length === 0)
+    return;
+  if (words[0] !== "search") {
+    throw new Error(`未知子命令「${words[0]}」——ad-hoc 检索用法：gtrk matrix search "<query>"；派单消费用法：gtrk matrix --project <dir>`);
+  }
+  const query = words.slice(1).join(" ").trim();
+  if (!query)
+    throw new Error('检索词不能为空：gtrk matrix search "<query>"');
+  return query;
+}
+async function runMatrix(searchQuery, opts) {
+  if (opts.json)
+    routeLogsToStderr();
+  const cfg = loadConfig();
+  log.step("▶ 身份探针（matrix_member_type）…");
+  const tier = await probeMemberType(cfg);
+  log.info(`档位：${tier}${tier === "internal" ? "（矩阵成员口 /task/custom/search）" : "（通用口 /task/video_clip_search）"}`);
+  const columnId = opts.column ?? readUserConfig().defaultColumn;
+  const resolved = resolveColumnConfig({ columnId });
+  for (const w of resolved.warnings)
+    log.warn(w);
+  const broll = resolved.config.broll;
+  const effectiveColumnId = columnId ?? resolved.config.meta?.id;
+  if (tier === "external") {
+    if (opts.materialClass === "concept") {
+      throw new Error("external 档位服务端固定 real_shot+有版权素材，concept 不可用（--material-class concept 无法满足）");
+    }
+    if (opts.materialClass) {
+      log.warn("external 档位服务端固定 real_shot+有版权素材，--material-class 参数不适用（已忽略）");
+    }
+    if (broll && (broll.column_tag_ids?.length || broll.material_class_policy || broll.facet_defaults)) {
+      log.warn("当前身份为 external，栏目检索偏好（column_tag_ids/material_class/facets）不适用");
+    }
+  }
+  const topK = opts.topK ? Number(opts.topK) : undefined;
+  const overrides = { topK, materialClass: opts.materialClass };
+  const brollForTier = tier === "internal" ? broll : undefined;
+  return searchQuery !== undefined ? runAdhoc(searchQuery, cfg, tier, brollForTier, overrides, effectiveColumnId, opts) : runPlanMode(cfg, tier, brollForTier, overrides, effectiveColumnId, opts);
+}
+async function runPlanMode(cfg, tier, broll, overrides, columnId, opts) {
+  let dispatchPath;
+  let baseDir;
+  if (opts.dispatch) {
+    dispatchPath = resolve7(opts.dispatch);
+    baseDir = dirname6(dirname6(dispatchPath));
+  } else if (opts.project) {
+    baseDir = resolve7(opts.project);
+    dispatchPath = join19(baseDir, "split", "dispatch.json");
+  } else {
+    throw new Error('需 --project <目录> 或显式 --dispatch <path>（ad-hoc 检索用：gtrk matrix search "<query>"）');
+  }
+  if (!existsSync15(dispatchPath))
+    throw new Error(`找不到派单清单：${dispatchPath}（先跑 gtrk split <拆分稿> 落地派单）`);
+  const dispatch = JSON.parse(await readFile5(dispatchPath, "utf8"));
+  const queue = Array.isArray(dispatch.film_broll) ? dispatch.film_broll : [];
+  log.step(`▶ B-roll 检索：${queue.length} 个 beat（${tier} 口）…`);
+  const beats = [];
+  let okCount = 0;
+  let errCount = 0;
+  let resultCount = 0;
+  for (const entry of queue) {
+    const outcomes = [];
+    for (const q of entry.queries) {
+      try {
+        const body = buildSearchBody(tier, q, entry, broll, overrides);
+        const data = await searchOnce(cfg, tier, body);
+        outcomes.push({ query: q, data });
+        okCount++;
+        resultCount += data.results?.length ?? 0;
+        log.info(`${entry.beat}「${q}」→ ${data.results?.length ?? 0} 条候选（召回 ${data.recalled ?? "?"}）`);
+      } catch (e) {
+        const code = e.code;
+        const msg = e instanceof Error ? e.message : String(e);
+        outcomes.push({ query: q, error: { ...code != null ? { code } : {}, msg } });
+        errCount++;
+        log.warn(`${entry.beat}「${q}」失败：${msg}`);
+      }
+    }
+    beats.push(buildPlanBeat(entry, outcomes));
+  }
+  const totalQueries = okCount + errCount;
+  if (queue.length === 0)
+    log.warn("无 B-roll 派单（film_broll 队列为空）——照常写出空 plan");
+  if (totalQueries > 0 && okCount === 0) {
+    throw new Error(`全部 ${totalQueries} 个 query 检索失败，未写入 plan（逐条原因见上方日志）`);
+  }
+  const projectSlug = slugify2(basename9(baseDir));
+  const plan = buildPlan({
+    generatedAt: new Date().toISOString(),
+    memberType: tier,
+    projectSlug,
+    columnId,
+    beats
+  });
+  const splitDir = join19(baseDir, "split");
+  await mkdir6(splitDir, { recursive: true });
+  const planPath = join19(splitDir, "broll-plan.json");
+  await writeFile7(planPath, JSON.stringify(plan, null, 2));
+  log.ok(`候选清单已生成：${planPath}（${beats.length} beat · ${okCount}/${totalQueries} query 成功 · ${resultCount} 条候选）`);
+  log.info("清单只含引用不含素材：cover_url 可直接预览；url 带签名默认 24h 过期，过期重跑本命令即重签。");
+  const layN = parseLay(opts.lay);
+  let laySummary;
+  if (layN > 0) {
+    laySummary = await layIntoProject(baseDir, plan, layN, parseScoreFloor(opts.scoreFloor));
+  }
+  const result = {
+    ok: true,
+    mode: "plan",
+    memberType: tier,
+    ...columnId ? { columnId } : {},
+    planPath,
+    ...laySummary ? { lay: laySummary } : {},
+    counts: { beats: beats.length, queries: totalQueries, results: resultCount, errors: errCount }
+  };
+  if (opts.json)
+    console.log(JSON.stringify(result));
+  return result;
+}
+function parseLay(raw) {
+  if (raw === undefined)
+    return 1;
+  const n = Number(raw);
+  if (Number.isInteger(n) && n >= 0)
+    return n;
+  log.warn(`--lay 取值非法（${raw}），按默认 1 处理`);
+  return 1;
+}
+function parseScoreFloor(raw) {
+  if (raw === undefined)
+    return SCORE_FLOOR_DEFAULT;
+  const n = Number(raw);
+  if (Number.isFinite(n) && n >= 0 && n <= 1)
+    return n;
+  log.warn(`--score-floor 取值非法（${raw}），按默认 ${SCORE_FLOOR_DEFAULT} 处理`);
+  return SCORE_FLOOR_DEFAULT;
+}
+function locateGtrk(baseDir) {
+  const cands = [join19(baseDir, "gtrk", "project.gtrk"), join19(baseDir, "project.gtrk")];
+  return cands.find((p) => existsSync15(p));
+}
+async function layIntoProject(baseDir, plan, layN, scoreFloor) {
+  const gtrkPath = locateGtrk(baseDir);
+  if (!gtrkPath) {
+    log.warn(`未找到工程文件（${join19(baseDir, "gtrk", "project.gtrk")}），跳过铺轨——plan 已产出，可后续在有工程的目录重跑`);
+    return;
+  }
+  const { gtrk, mtimeMs } = readGtrk(gtrkPath);
+  assertGtrkV1(gtrk);
+  const { fills, clipIds } = planBeatFills(plan, layN, scoreFloor);
+  const slotCount = [...fills.values()].flat().reduce((n, s) => n + s.length, 0);
+  log.step(`▶ 候选铺轨（${layN} 轨 · 平铺 ${slotCount} 槽位 · ${clipIds.size} 个 clip，preview 代理）…`);
+  const gtrkDir = dirname6(gtrkPath);
+  const previewDir = join19(gtrkDir, ...BROLL_PREVIEW_DIR.split("/"));
+  await mkdir6(previewDir, { recursive: true });
+  const prevSource = new Map;
+  const prevBroll = gtrk.struct_meta?.broll;
+  for (const b of prevBroll?.beats ?? []) {
+    for (const c3 of b.candidates ?? []) {
+      if (typeof c3.clip_id === "string" && c3.preview_path && (c3.source === "preview" || c3.source === "raw")) {
+        prevSource.set(c3.clip_id, c3.source);
+      }
+    }
+  }
+  const candById = new Map;
+  for (const beat of plan.beats)
+    for (const c3 of mergedCandidates(beat))
+      if (!candById.has(c3.clip_id))
+        candById.set(c3.clip_id, c3);
+  const downloads = new Map;
+  const dlStats = { preview: 0, raw: 0, reused: 0, failed: 0 };
+  for (const clipId of clipIds) {
+    const cand = candById.get(clipId);
+    if (!cand)
+      continue;
+    const rel = `${BROLL_PREVIEW_DIR}/${clipId}.mp4`;
+    const abs = join19(gtrkDir, ...rel.split("/"));
+    if (existsSync15(abs)) {
+      const prev = prevSource.get(clipId);
+      if (prev !== "raw") {
+        downloads.set(clipId, { rel, source: prev ?? "preview" });
+        dlStats.reused++;
+        continue;
+      }
+      const retried = await downloadProxy(cand, abs, { previewOnly: true });
+      if (retried === "preview") {
+        downloads.set(clipId, { rel, source: "preview" });
+        dlStats.preview++;
+        log.info(`clip ${clipId} 代理已补产,已从原片回落态换回 preview`);
+      } else {
+        downloads.set(clipId, { rel, source: "raw" });
+        dlStats.reused++;
+      }
+      continue;
+    }
+    const got = await downloadProxy(cand, abs);
+    if (got) {
+      downloads.set(clipId, { rel, source: got });
+      dlStats[got]++;
+    } else {
+      dlStats.failed++;
+    }
+  }
+  const { next, summary } = layBrollTracks({
+    gtrk,
+    plan,
+    lay: layN,
+    fills,
+    downloads,
+    generatedAt: new Date().toISOString(),
+    planPath: "split/broll-plan.json"
+  });
+  writeGtrkAtomic(gtrkPath, next, mtimeMs);
+  log.ok(`铺轨完成：${summary.laidTracks.length} 条候选轨（track_index ${summary.laidTracks.join("/") || "-"}）· 平铺 ${summary.laidClips} 个颗粒 / ${clipIds.size} 个 clip` + `（代理 ${dlStats.preview} · 原片回落 ${dlStats.raw} · 复用 ${dlStats.reused}${dlStats.failed ? ` · 失败 ${dlStats.failed}` : ""}）`);
+  log.info("opencut 打开工程即见候选轨：轨道头小眼睛可开关对比；确认下载原片属挑选 UI（E-P1）。");
+  if (dlStats.raw > 0) {
+    log.warn("部分候选无 preview 代理已回落原片（体积较大）——服务端 backfill 后重跑本命令可换回代理。");
+  }
+  return { laidTracks: summary.laidTracks, laidClips: summary.laidClips, downloads: dlStats };
+}
+async function downloadProxy(cand, absPath, opts = {}) {
+  const tryFetch = async (url) => {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(180000) });
+      if (!res.ok)
+        return null;
+      return Buffer.from(await res.arrayBuffer());
+    } catch {
+      return null;
+    }
+  };
+  const previewUrl = previewUrlFor(cand);
+  if (previewUrl) {
+    const bytes = await tryFetch(previewUrl);
+    if (bytes) {
+      await writeFile7(absPath, bytes);
+      return "preview";
+    }
+  }
+  if (opts.previewOnly)
+    return null;
+  const raw = await tryFetch(cand.url);
+  if (raw) {
+    await writeFile7(absPath, raw);
+    log.warn(`clip ${cand.clip_id} 无 preview 代理，已回落原片（${(raw.length / 1048576).toFixed(1)}MB）`);
+    return "raw";
+  }
+  log.warn(`clip ${cand.clip_id} 代理与原片均下载失败，该候选槽位跳过`);
+  return null;
+}
+async function runAdhoc(query, cfg, tier, broll, overrides, columnId, opts) {
+  log.step(`▶ ad-hoc 检索「${query}」（${tier} 口）…`);
+  const body = buildSearchBody(tier, query, undefined, broll, overrides);
+  const data = await searchOnce(cfg, tier, body);
+  const results = data.results ?? [];
+  log.ok(`${results.length} 条候选（召回 ${data.recalled ?? "?"}）`);
+  const result = {
+    ok: true,
+    mode: "search",
+    memberType: tier,
+    ...columnId ? { columnId } : {},
+    results,
+    counts: { beats: 0, queries: 1, results: results.length, errors: 0 }
+  };
+  if (opts.out) {
+    const outPath = resolve7(opts.out);
+    await writeFile7(outPath, JSON.stringify({ query, recalled: data.recalled, results }, null, 2));
+    log.ok(`结果已落盘：${outPath}`);
+    result.outPath = outPath;
+  } else if (!opts.json) {
+    for (const r of results.slice(0, 10)) {
+      const seg = r.segments?.[0];
+      log.info(`clip ${r.clip_id} · score ${r.score}${seg ? ` · 最佳段 ${seg.start}s–${seg.end}s（锚点 ${seg.best}s）` : ""}${r.note ? ` · ${String(r.note).slice(0, 40)}` : ""}`);
+    }
+  }
+  if (opts.json)
+    console.log(JSON.stringify(result));
+  return result;
+}
+function slugify2(name) {
+  const s = name.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "");
+  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(readFileSync4(join17(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);
@@ -6630,6 +8188,8 @@ registerSkills(program2);
 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)}`);