@gitruck/cli 0.2.13 → 0.2.14

package/README.md

@@ -339,10 +339,13 @@ gtrk transcript "D:/素材/采访视频.mp4" --lang zh-CN --out "D:/文字稿/
 | `--top-k <n>` | 每 query 候选数上限（覆盖派单 shots；服务端上限 50） | 派单值 |
 | `--material-class <c>` | 素材类型 `real_shot` \| `concept`（仅矩阵成员口；覆盖栏目策略） | 栏目策略 |
 | `--score-floor <f>` | 填充置信度地板：segment score 低于此值不采纳、留空露主轨 | `0.2` |
+| `--no-black-bed` | 不铺纯黑底垫轨（默认铺一条） | 默认铺 |
 | `--out <file>` | ad-hoc 模式结果落文件 | stdout |
 | `--json` | 机读：stdout 只输出结果 JSON | 关 |
 
 > preview 代理 url 约 24h 过期，重跑即重签。
+>
+> **纯黑底垫轨**：默认在全部候选轨之下、口播主轨之上垫一条纯黑底轨（`struct_meta.broll.black_track` 记其 `track_index`），按已落成的 beat 包络整条铺满，使 B-roll 期间（含候选轨留空处）不漏出底下的口播画面。字节落 `assets/builtin/solid-000000-<W>x<H>.png`，与客户端内置纯色素材同 id 命名空间、幂等复用。删候选轨时别误删它；换片请拖到候选轨颗粒上、**别拖到黑底条上**——含拖拽保护的客户端会直接拒绝并提示，尚未升级到该版本的客户端会被误拖打出黑底破洞（该处漏口播）。不想要加 `--no-black-bed` 重跑即剥净。
 
 ### `gtrk mg` — MG 动态图颗粒（铺轨 / lint / status）
 

package/dist/index.js

@@ -5001,7 +5001,8 @@ function buildLanding(doc, view, opts) {
       dispatch.mg.push({
         beat: beat.id,
         composition_id: compositionId,
-        duration: typeof h.duration_hint === "number" ? h.duration_hint : null,
+        duration: r3(track_ed - track_st),
+        duration_hint: typeof h.duration_hint === "number" ? h.duration_hint : null,
         ...h.category !== undefined ? { category: h.category } : {},
         theme: h.theme,
         bg: h.bg,
@@ -5058,7 +5059,8 @@ function buildLanding(doc, view, opts) {
       dispatch.mg.push({
         beat: beat.id,
         composition_id: auxCompositionId,
-        duration: ah && typeof ah.duration_hint === "number" ? ah.duration_hint : null,
+        duration: r3(auxTrackEd - auxTrackSt),
+        duration_hint: ah && typeof ah.duration_hint === "number" ? ah.duration_hint : null,
         category: "overlay",
         theme: ah?.theme,
         bg: ah?.bg,
@@ -5130,7 +5132,9 @@ function renderSplitMarkdown(doc, landing, meta) {
   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` : ""}`);
+    const slot = r.duration != null ? ` · 坑位 ${r.duration}s` : "";
+    const hint = r.duration_hint != null ? ` · hint ${r.duration_hint}s` : "";
+    L.push(`- \`${r.beat}\` composition_id=\`${r.composition_id}\`${slot}${hint}`);
   }
   L.push("");
   L.push("## AI_DRAMA Queue");
@@ -7310,7 +7314,109 @@ async function runLand(splitdocPath, baseDir, gtrkPath, transcriptPath, opts) {
 // src/commands/matrix.ts
 import { resolve as resolve8, join as join19, dirname as dirname7, 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";
+import { readFile as readFile5, writeFile as writeFile7, mkdir as mkdir6, rename } from "node:fs/promises";
+
+// src/lib/solid-png.ts
+import { deflateSync } from "node:zlib";
+var BLACK_BED_HEX = "000000";
+var SOLID_MATERIAL_PREFIX = "ex-solid-";
+var BUILTIN_ASSET_DIR = "assets/builtin";
+var MAX_BED_DIM = 8192;
+var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+var CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0;n < 256; n++) {
+    let c3 = n;
+    for (let k = 0;k < 8; k++)
+      c3 = c3 & 1 ? 3988292384 ^ c3 >>> 1 : c3 >>> 1;
+    table[n] = c3 >>> 0;
+  }
+  return table;
+})();
+function crc32(buf) {
+  let c3 = 4294967295;
+  for (let i = 0;i < buf.length; i++)
+    c3 = (CRC_TABLE[(c3 ^ buf[i]) & 255] ^ c3 >>> 8) >>> 0;
+  return (c3 ^ 4294967295) >>> 0;
+}
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length, 0);
+  const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body), 0);
+  return Buffer.concat([len, body, crc]);
+}
+function normalizeHex(hex) {
+  const h = hex.replace(/^#/, "").toLowerCase();
+  return /^[0-9a-f]{6}$/.test(h) ? h : null;
+}
+function solidMaterialId({
+  hex,
+  width,
+  height
+}) {
+  const h = normalizeHex(hex);
+  if (!h)
+    throw new Error(`非法纯色 hex：${hex}`);
+  return `${SOLID_MATERIAL_PREFIX}${h}-${width}x${height}`;
+}
+function solidRelPath({
+  hex,
+  width,
+  height
+}) {
+  const h = normalizeHex(hex);
+  if (!h)
+    throw new Error(`非法纯色 hex：${hex}`);
+  return `${BUILTIN_ASSET_DIR}/solid-${h}-${width}x${height}.png`;
+}
+function isLayoutableCanvas(canvas) {
+  if (!Array.isArray(canvas) || canvas.length !== 2)
+    return false;
+  return canvas.every((v) => typeof v === "number" && Number.isInteger(v) && v > 0 && v <= MAX_BED_DIM);
+}
+function encodeSolidPng({
+  hex,
+  width,
+  height
+}) {
+  const h = normalizeHex(hex);
+  if (!h)
+    throw new Error(`非法纯色 hex：${hex}`);
+  if (!isLayoutableCanvas([width, height])) {
+    throw new Error(`纯色画布尺寸非法或超上限（${width}x${height}，上限 ${MAX_BED_DIM}）`);
+  }
+  const r = Number.parseInt(h.slice(0, 2), 16);
+  const g2 = Number.parseInt(h.slice(2, 4), 16);
+  const b = Number.parseInt(h.slice(4, 6), 16);
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 2;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+  const stride = 1 + width * 3;
+  const row = Buffer.alloc(stride);
+  row[0] = 0;
+  for (let x = 0;x < width; x++) {
+    const off = 1 + x * 3;
+    row[off] = r;
+    row[off + 1] = g2;
+    row[off + 2] = b;
+  }
+  const raw = Buffer.alloc(stride * height);
+  for (let y = 0;y < height; y++)
+    row.copy(raw, y * stride);
+  return Buffer.concat([
+    PNG_SIGNATURE,
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(raw, { level: 9 })),
+    chunk("IEND", Buffer.alloc(0))
+  ]);
+}
 
 // src/lib/matrix-lay.ts
 var BROLL_PREVIEW_DIR = "assets/broll-preview";
@@ -7320,6 +7426,21 @@ var SHOT_TARGET_DEFAULT = 3;
 var MIN_SHOT_SEC = 1.2;
 var SCORE_FLOOR_DEFAULT = 0.2;
 var MAX_SLOTS_PER_BEAT = 32;
+var BLACK_BED_MERGE_EPS = 0.001;
+function mergeBlackBedSegments(envelopes) {
+  const valid = envelopes.filter((e) => Number.isFinite(e.track_st) && Number.isFinite(e.track_ed) && e.track_ed > e.track_st).sort((a, b) => a.track_st - b.track_st);
+  const out = [];
+  for (const e of valid) {
+    const last = out[out.length - 1];
+    if (last && e.track_st - last.track_ed <= BLACK_BED_MERGE_EPS) {
+      if (e.track_ed > last.track_ed)
+        last.track_ed = e.track_ed;
+      continue;
+    }
+    out.push({ track_st: e.track_st, track_ed: e.track_ed });
+  }
+  return out.map((s) => ({ track_st: r33(s.track_st), track_ed: r33(s.track_ed) }));
+}
 function mergedCandidates(beat) {
   const all = [];
   for (const q of beat.queries)
@@ -7493,6 +7614,8 @@ function planBeatFills(plan, lay, scoreFloor) {
 }
 function layBrollTracks(opts) {
   const { gtrk, plan, lay, fills, downloads } = opts;
+  const blackBedOn = opts.blackBed !== false;
+  const warnings = [];
   const videoTracks = [...gtrk.video_track ?? []];
   const materials = [...gtrk.materials ?? []];
   const structMeta = { ...gtrk.struct_meta ?? {} };
@@ -7504,11 +7627,31 @@ function layBrollTracks(opts) {
   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))
+      if (typeof m === "string" && (m.startsWith(BROLL_MATERIAL_PREFIX) || m.startsWith(SOLID_MATERIAL_PREFIX))) {
         removedMaterialIds.add(m);
+      }
     }
   }
+  const stillReferenced = new Set;
+  for (const group of [keptTracks, gtrk.beat_track ?? [], gtrk.audio_track ?? []]) {
+    for (const t of group) {
+      for (const c3 of t.track_timeline ?? []) {
+        if (typeof c3.material === "string")
+          stillReferenced.add(c3.material);
+      }
+    }
+  }
+  for (const id of stillReferenced)
+    removedMaterialIds.delete(id);
   const keptMaterials = materials.filter((m) => !(typeof m.id === "string" && removedMaterialIds.has(m.id)));
+  for (const t of keptTracks) {
+    const clips = t.track_timeline ?? [];
+    if (!clips.length)
+      continue;
+    if (clips.every((c3) => typeof c3.material === "string" && c3.material.startsWith(SOLID_MATERIAL_PREFIX))) {
+      warnings.push(`检测到疑似手工纯色底轨（track_index=${t.track_index}）：新候选轨会落到它之下被遮住。建议删除该轨后重跑，或用 --no-black-bed。`);
+    }
+  }
   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;
@@ -7591,24 +7734,71 @@ function layBrollTracks(opts) {
     muted: false,
     track_timeline: clips.sort((a, b) => a.track_st - b.track_st)
   }));
+  let blackTrack = null;
+  let blackTrackObj = null;
+  if (blackBedOn && createdTracks.length > 0) {
+    if (!isLayoutableCanvas([canvas[0], canvas[1]])) {
+      warnings.push(`画布尺寸非法（${canvas[0]}x${canvas[1]}），跳过铺纯黑底轨（候选轨照常铺）。`);
+    } else {
+      const laidBeatEnvelopes = metaBeats.filter((b) => b.laid.length > 0).map((b) => ({ track_st: b.track_st, track_ed: b.track_ed }));
+      const segments = mergeBlackBedSegments(laidBeatEnvelopes);
+      if (segments.length > 0) {
+        const width = canvas[0];
+        const height = canvas[1];
+        const solidId = solidMaterialId({ hex: BLACK_BED_HEX, width, height });
+        newMaterialsById.set(solidId, {
+          id: solidId,
+          path: solidRelPath({ hex: BLACK_BED_HEX, width, height }),
+          video_size: [width, height]
+        });
+        blackTrack = baseIndex + lay;
+        blackTrackObj = {
+          track_index: blackTrack,
+          track_size: [width, height],
+          muted: false,
+          track_timeline: segments.map((s, i) => ({
+            clip_id: `blackbed-${i}`,
+            material: solidId,
+            clip_st: 0,
+            clip_ed: r33(s.track_ed - s.track_st),
+            track_st: s.track_st,
+            track_ed: s.track_ed,
+            duration: r33(s.track_ed - s.track_st)
+          }))
+        };
+      }
+    }
+  }
+  const laidTrackIndices = createdTracks.map((t) => t.track_index);
   const broll = {
     contract_version: "v1",
     generated_at: opts.generatedAt,
     plan_path: opts.planPath,
-    lay_tracks: createdTracks.map((t) => t.track_index),
+    lay_tracks: blackTrack === null ? laidTrackIndices : [...laidTrackIndices, blackTrack],
+    black_track: blackTrack,
     confirmed: false,
     beats: metaBeats
   };
+  const mergedMaterials = new Map;
+  for (const m of keptMaterials) {
+    if (typeof m.id === "string")
+      mergedMaterials.set(m.id, m);
+    else
+      mergedMaterials.set(`__anon_${mergedMaterials.size}`, m);
+  }
+  for (const [id, m] of newMaterialsById)
+    mergedMaterials.set(id, m);
   const next = {
     ...gtrk,
-    materials: [...keptMaterials, ...newMaterialsById.values()],
-    video_track: [...keptTracks, ...createdTracks],
+    materials: [...mergedMaterials.values()],
+    video_track: [...keptTracks, ...createdTracks, ...blackTrackObj ? [blackTrackObj] : []],
     struct_meta: { ...structMeta, broll }
   };
   return {
     next,
-    summary: { laidTracks: broll.lay_tracks, laidClips, beatsWithCandidates },
-    broll
+    summary: { laidTracks: laidTrackIndices, laidClips, beatsWithCandidates, blackTrack },
+    broll,
+    warnings
   };
 }
 
@@ -7799,7 +7989,7 @@ async function searchOnce(cfg, tier, body) {
 
 // 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) => {
+  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("--no-black-bed", "不铺纯黑底垫轨（默认铺一条，垫在候选轨之下、口播主轨之上，用于 B-roll 期间遮住口播画面）").option("--out <file>", "ad-hoc 模式：结果落文件（缺省输出 stdout）").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON").action(async (words, opts) => {
     await runMatrix(parseAdhocQuery(words), opts);
   });
 }
@@ -7907,7 +8097,7 @@ async function runPlanMode(cfg, tier, broll, overrides, columnId, opts) {
   const layN = parseLay(opts.lay);
   let laySummary;
   if (layN > 0) {
-    laySummary = await layIntoProject(baseDir, plan, layN, parseScoreFloor(opts.scoreFloor));
+    laySummary = await layIntoProject(baseDir, plan, layN, parseScoreFloor(opts.scoreFloor), opts.blackBed ?? true);
   }
   const result = {
     ok: true,
@@ -7944,7 +8134,7 @@ 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) {
+async function layIntoProject(baseDir, plan, layN, scoreFloor, blackBed) {
   const gtrkPath = locateGtrk(baseDir);
   if (!gtrkPath) {
     log.warn(`未找到工程文件（${join19(baseDir, "gtrk", "project.gtrk")}），跳过铺轨——plan 已产出，可后续在有工程的目录重跑`);
@@ -8006,22 +8196,57 @@ async function layIntoProject(baseDir, plan, layN, scoreFloor) {
       dlStats.failed++;
     }
   }
-  const { next, summary } = layBrollTracks({
+  let { next, summary, warnings } = layBrollTracks({
     gtrk,
     plan,
     lay: layN,
     fills,
     downloads,
     generatedAt: new Date().toISOString(),
-    planPath: "split/broll-plan.json"
+    planPath: "split/broll-plan.json",
+    blackBed
   });
+  if (summary.blackTrack !== null) {
+    const canvas = gtrk.video_size;
+    const spec = { hex: BLACK_BED_HEX, width: canvas[0], height: canvas[1] };
+    const rel = solidRelPath(spec);
+    const abs = join19(gtrkDir, ...rel.split("/"));
+    try {
+      if (!existsSync15(abs)) {
+        await mkdir6(dirname7(abs), { recursive: true });
+        const tmp = `${abs}.tmp-${process.pid}`;
+        await writeFile7(tmp, encodeSolidPng(spec));
+        await rename(tmp, abs);
+      }
+    } catch (e) {
+      log.warn(`纯黑底 PNG 落盘失败（${rel}）：${e.message} —— 本次不铺黑底垫轨，候选轨照常。`);
+      ({ next, summary, warnings } = layBrollTracks({
+        gtrk,
+        plan,
+        lay: layN,
+        fills,
+        downloads,
+        generatedAt: new Date().toISOString(),
+        planPath: "split/broll-plan.json",
+        blackBed: false
+      }));
+    }
+  }
   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}` : ""}）`);
+  const bedNote = summary.blackTrack !== null ? ` · 纯黑底垫轨 track_index ${summary.blackTrack}` : blackBed ? " · 未铺纯黑底垫轨" : " · 纯黑底垫轨已关闭（--no-black-bed）";
+  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}` : ""}）${bedNote}`);
   log.info("opencut 打开工程即见候选轨：轨道头小眼睛可开关对比；确认下载原片属挑选 UI（E-P1）。");
+  for (const w of warnings)
+    log.warn(w);
   if (dlStats.raw > 0) {
     log.warn("部分候选无 preview 代理已回落原片（体积较大）——服务端 backfill 后重跑本命令可换回代理。");
   }
-  return { laidTracks: summary.laidTracks, laidClips: summary.laidClips, downloads: dlStats };
+  return {
+    laidTracks: summary.laidTracks,
+    laidClips: summary.laidClips,
+    blackTrack: summary.blackTrack,
+    downloads: dlStats
+  };
 }
 async function downloadProxy(cand, absPath, opts = {}) {
   const tryFetch = async (url) => {
@@ -8124,6 +8349,42 @@ var CATEGORY_EXPECTED_OPAQUE2 = {
   "explain-subtitle": false,
   "op-ed-title": true
 };
+function estimateTimelineSec(html) {
+  const re = /\.\s*(?:to|from|fromTo|set|add)\s*\(([\s\S]*?)\)\s*;/g;
+  const calls = [];
+  let m;
+  while (m = re.exec(html)) {
+    const args = m[1] ?? "";
+    const lastBrace = args.lastIndexOf("}");
+    let pos = null;
+    if (lastBrace >= 0) {
+      const tail = args.slice(lastBrace + 1).replace(/^\s*,\s*/, "").trim();
+      if (tail)
+        pos = tail.replace(/^["']|["']$/g, "");
+    }
+    calls.push({ body: args, pos });
+  }
+  if (!calls.length)
+    return null;
+  let chain = 0;
+  let maxEnd = 0;
+  for (const c3 of calls) {
+    if (/\brepeat\s*:/.test(c3.body) || /\byoyo\s*:\s*true\b/.test(c3.body))
+      return null;
+    if (c3.pos !== null && !/^-?\d+(?:\.\d+)?$/.test(c3.pos))
+      return null;
+    const d = /\bduration\s*:\s*(-?\d+(?:\.\d+)?)/.exec(c3.body);
+    const dur = d ? Number(d[1]) : 0;
+    if (!Number.isFinite(dur) || dur < 0)
+      return null;
+    if (c3.pos !== null)
+      maxEnd = Math.max(maxEnd, Number(c3.pos) + dur);
+    else
+      chain += dur;
+  }
+  const est = Math.max(chain, maxEnd);
+  return est > 0 ? Math.round(est * 1000) / 1000 : null;
+}
 function lintParticle(html, opts = {}) {
   const v = [];
   const push = (law, fatal, msg) => v.push({ law, fatal, msg });
@@ -8193,6 +8454,12 @@ function lintParticle(html, opts = {}) {
     if (expect !== opaque)
       push("x-category-opaque", false, `category「${opts.category}」期望${expect ? "不透明满屏" : "透明叠加"}，但颗粒 HTML 反推为${opaque ? "不透明满屏" : "透明叠加"}（以 HTML 为准落 clip.opaque=${opaque}）`);
   }
+  if (typeof opts.slotDuration === "number" && opts.slotDuration > 0) {
+    const est = estimateTimelineSec(html);
+    if (est !== null && est < opts.slotDuration * 0.8) {
+      push("7-fill-slot", false, `时间线静态估长 ~${est}s，短于槽位包络 ${opts.slotDuration}s（铁律⑦：颗粒应占满坑位并终态驻留）——静态估算仅供参考，含 repeat/yoyo/相对定位时不作数`);
+    }
+  }
   return { ok: !v.some((x) => x.fatal), violations: v, opaque, compositionId: cid };
 }
 
@@ -8201,6 +8468,7 @@ 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;
+var slotEnvelope = (it) => r34(it.track_ed - it.track_st);
 function layTracksOf(prev) {
   return Array.isArray(prev?.lay_tracks) ? prev.lay_tracks.filter((x) => typeof x === "number") : [];
 }
@@ -8233,7 +8501,8 @@ function layMgTracks(opts) {
   ].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)) {
+    const envelope = slotEnvelope(it);
+    if (!(envelope > 0)) {
       metaBeats.push({ ...toMetaBeat(it), laid: null });
       continue;
     }
@@ -8245,7 +8514,7 @@ function layMgTracks(opts) {
       html_material: materialId,
       opaque: it.opaque,
       track_st: it.track_st,
-      duration: it.duration
+      duration: envelope
     });
     metaBeats.push({ ...toMetaBeat(it), laid: { track_index: newIndex } });
   }
@@ -8281,7 +8550,7 @@ function toMetaBeat(it) {
     composition_id: it.composition_id,
     track_st: it.track_st,
     track_ed: r34(it.track_ed),
-    duration: it.duration,
+    duration: slotEnvelope(it),
     html_path: it.html_rel,
     ...it.category ? { category: it.category } : {}
   };
@@ -8357,7 +8626,13 @@ async function runLay(opts) {
     }
     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 });
+    const slotDuration = Math.round((q.track_ed - q.track_st) * 1000) / 1000;
+    const lint = lintParticle(html, {
+      compositionId: q.composition_id,
+      dispatchIds,
+      category,
+      ...slotDuration > 0 ? { slotDuration } : {}
+    });
     for (const vv of lint.violations)
       (vv.fatal ? log.warn : log.info)(`${q.beat} lint ${vv.fatal ? "✗" : "·"} ${vv.law}: ${vv.msg}`);
     if (!lint.ok) {
@@ -8365,8 +8640,8 @@ async function runLay(opts) {
       log.warn(`${q.beat}：lint 未过，跳过`);
       continue;
     }
-    if (typeof q.duration !== "number" || !(q.duration > 0)) {
-      skipped.push({ beat: q.beat, reason: "duration 非正数" });
+    if (!(slotDuration > 0)) {
+      skipped.push({ beat: q.beat, reason: "槽位包络非正数" });
       continue;
     }
     srcByComp.set(q.composition_id, srcPath);
@@ -8375,7 +8650,6 @@ async function runLay(opts) {
       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 } : {}
@@ -10726,7 +11000,7 @@ function beatQuantized(natLens, analysis) {
 
 // src/lib/mad/data.ts
 import { createHash as createHash2 } from "node:crypto";
-import { mkdir as mkdir9, readFile as readFile7, rename, rm, writeFile as writeFile9, readdir } from "node:fs/promises";
+import { mkdir as mkdir9, readFile as readFile7, rename as rename2, rm, writeFile as writeFile9, readdir } from "node:fs/promises";
 import { existsSync as existsSync18 } from "node:fs";
 import { join as join23 } from "node:path";
 function madCacheDir() {
@@ -10754,7 +11028,7 @@ async function fetchWithTimeout(fetchFn, url, timeoutMs) {
 async function atomicWrite(dest, data) {
   const tmp = `${dest}.tmp-${process.pid}-${Date.now()}`;
   await writeFile9(tmp, data);
-  await rename(tmp, dest);
+  await rename2(tmp, dest);
 }
 async function verifyFile(path, sha256) {
   if (!existsSync18(path))
@@ -11264,7 +11538,7 @@ async function runMadInTool(inputArg, opts) {
 
 // src/commands/transcript.ts
 import { existsSync as existsSync21 } from "node:fs";
-import { mkdir as mkdir12, rename as rename2, rm as rm2, stat as stat6, writeFile as writeFile11 } from "node:fs/promises";
+import { mkdir as mkdir12, rename as rename3, rm as rm2, stat as stat6, writeFile as writeFile11 } from "node:fs/promises";
 import { basename as basename12, dirname as dirname10, extname as extname7, join as join26, resolve as resolve12 } from "node:path";
 
 // src/lib/transcript.ts
@@ -11425,7 +11699,7 @@ async function writeMarkdownAtomic(path, markdown) {
   const temp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
   try {
     await writeFile11(temp, markdown, "utf8");
-    await rename2(temp, path);
+    await rename3(temp, path);
   } finally {
     await rm2(temp, { force: true });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitruck/cli",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
   "license": "MIT",
   "author": "Gitruck (同合云)",
@@ -48,7 +48,7 @@
     "build": "bun build ./src/index.ts --target=node --outfile dist/index.js",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run build",
-    "test": "esbuild src/lib/chunk-upload.ts src/lib/upload-cache.ts src/lib/upload-submit.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/projection.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-lay.ts src/lib/mg-lint.ts src/lib/mg-lay.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-pricing.ts src/lib/transcript.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && node --test \"test/*.test.mjs\""
+    "test": "esbuild src/lib/chunk-upload.ts src/lib/upload-cache.ts src/lib/upload-submit.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/projection.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-lay.ts src/lib/solid-png.ts src/lib/mg-lint.ts src/lib/mg-lay.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-pricing.ts src/lib/transcript.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && node --test \"test/*.test.mjs\""
   },
   "devDependencies": {
     "@xmldom/xmldom": "^0.9.6",

package/skills/gtrk-matrix/SKILL.md

@@ -46,10 +46,11 @@ description: B-roll 检索铺轨器——成片管线里第一个铺的车道（
 | 每段多给几个候选 | `--top-k <n>` | 整数 · 派单 `shots` 值（服务端上限 50） | 覆盖派单里每 query 的候选数上限 |
 | 指定素材类型 | `--material-class <c>` | `real_shot` \| `concept` · 栏目策略 | 仅 internal 矩阵成员口；external 固定 real_shot、传 concept 报错 |
 | 填充太满/太差调门槛 | `--score-floor <f>` | 浮点 0–1 · `0.2` | segment score 低于此值不采纳、槽位留空露主轨 |
+| 不要那条纯黑底轨 | `--no-black-bed` | 开关 · 默认铺 | 默认在候选轨之下、口播主轨之上垫一条纯黑底轨，按 beat 包络整条铺满，B-roll 期间遮住底下的口播画面（含候选轨留空处）；不想要就传这个 |
 | ad-hoc 结果落文件 | `--out <file>` | 路径 · 缺省 stdout | 仅 `search` 模式 |
 | 机读（你必带） | `--json` | 开关 · 关 | 人读日志转 stderr，stdout 只出一行结果 JSON |
 
-> **因势象形举例**：「B-roll 多铺几条候选让我挑」→ `--lay 3`；「这段填得太杂、卡严点」→ `--score-floor 0.35`；「每段多给点候选」→ `--top-k 12`；「先只出清单别铺轨」→ `--lay 0`；「单独给『深夜地铁失神』搜一组」→ `gtrk matrix search "exhausted commuter staring blankly on a late night subway" --project <目录> --json`。
+> **因势象形举例**：「B-roll 多铺几条候选让我挑」→ `--lay 3`；「这段填得太杂、卡严点」→ `--score-floor 0.35`；「每段多给点候选」→ `--top-k 12`；「先只出清单别铺轨」→ `--lay 0`；「别给我垫那条黑底」→ `--no-black-bed`；「单独给『深夜地铁失神』搜一组」→ `gtrk matrix search "exhausted commuter staring blankly on a late night subway" --project <目录> --json`。
 
 ## 执行（每次都带 `--json`）
 
@@ -58,7 +59,7 @@ gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-
 ```
 
 - `--json`：人读日志走 stderr，**成功时 stdout 只有一行结果 JSON**：
-  `{ ok, mode:"plan", memberType:"internal"|"external", columnId?, planPath, lay:{ laidTracks:[…], laidClips, downloads:{preview,raw,reused,failed} }, counts:{ beats, queries, results, errors } }`
+  `{ ok, mode:"plan", memberType:"internal"|"external", columnId?, planPath, lay:{ laidTracks:[…], laidClips, blackTrack, downloads:{preview,raw,reused,failed} }, counts:{ beats, queries, results, errors } }`
   （`--lay 0` 时无 `lay` 字段；ad-hoc `search` 模式则是 `{ ok, mode:"search", results:[…], counts, outPath? }`）
 - 产物：候选清单 `<目录>/split/broll-plan.json`（只含引用不含素材，`cover_url` 可预览、签名 url 约 24h 过期，过期重跑即重签），铺轨则把候选轨写回工程 `gtrk/project.gtrk`。
 - **命令失败**（缺 `--dispatch`/派单、鉴权失败、全部 query 检索失败、参数越界等）→ **进程非 0 退出、报错打到 stderr、stdout 无 JSON**。先看退出码，非 0 就把 stderr 的报错如实回给用户，别当成功。
@@ -70,7 +71,8 @@ gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-
 
 - `counts`：`beats` 个 beat、`queries` 条检索（`errors` 条失败）、`results` 条候选——一句话概括这次铺了多大盘子。
 - `memberType`：`internal` = 矩阵成员口（栏目偏好/concept 生效）；`external` = 通用口（固定 real_shot + 有版权素材）——档位影响命中类型，若用户期望 concept 却是 external，明说「当前身份只能出实拍有版权素材」。
-- `lay.laidTracks` / `lay.laidClips`：铺了几条候选轨、共几个颗粒（`--lay 0` 时无此字段，只出了 plan）。
+- `lay.laidTracks` / `lay.laidClips`：铺了几条候选轨、共几个颗粒（`--lay 0` 时无此字段，只出了 plan）。**`laidTracks` 只含候选轨、不含黑底垫轨。**
+- `lay.blackTrack`：纯黑底垫轨的 `track_index`（未铺时 `null`，如传了 `--no-black-bed`、画布尺寸非法、或零候选轨落成）。
 - `lay.downloads`：`preview` 代理数 / `raw` **原片回落**数（无 preview 代理的候选回落下原片、体积大，服务端 backfill 后重跑本命令可换回代理）/ `reused` 复用 / `failed` 掉的槽位——`raw`/`failed` 非零时提一句。
 - **单 query 失败是局部化的**（`counts.errors > 0` 但 `ok:true`）：个别检索失败不拖垮整盘，如实说哪几段没检到、其余照铺。只有**全部 query 都失败**才会整体非 0 退出。
 - 工程缺失/非 v1 → 命令会**告警跳过铺轨但仍产 plan**（stderr 有提示）——这时 `lay` 字段缺失，告诉用户 plan 已出、可在有工程的目录重跑铺轨。
@@ -82,6 +84,7 @@ gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-
 - **在同合云桌面客户端（opencut / OpenCut Gitruck Edition）里打开这个工程**，B-roll 候选轨已经铺好。
 - **用轨道头的「小眼睛」开关逐条切换对比**：看哪条候选最贴这段口播的情绪/画面，留下满意的、关掉不要的。
 - 候选默认是 preview 代理（轻量预览）；**下载原片属挑选后的动作**（客户端挑选 UI），确认要哪条再拉原片。
+- **候选轨下方还垫了一条纯黑底轨**（`lay.blackTrack`），按 beat 包络整条铺满，作用是 B-roll 期间遮住底下的口播画面（含候选轨上的留空处）——删多余候选轨时**别误删它**；换片请拖到**候选轨的颗粒**上、**别拖到黑底条上**（含拖拽保护的客户端会直接拒绝并提示；尚未升级到该版本的客户端会被误拖打出黑底破洞、该处漏口播）。不想要黑底就加 `--no-black-bed` 重跑，会自动剥净。
 - 觉得填充有问题（太杂/太空/漏段）先别急着往下——**回来告诉我**，我按下面「常见情况」调参重铺。
 
 **用户明确说「B-roll 就这样、可以了」之后**，才交棒 ④。别自作主张替他拍板往下冲。
@@ -91,6 +94,7 @@ gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-
 | 情况 | 怎么做 |
 |---|---|
 | 想在多个候选里挑 | `--lay N` 多铺几条候选轨，opencut 小眼睛切换对比（N 越大越占轨、挑完可删多余轨） |
+| 不要那条黑底垫轨 | `--no-black-bed` 重跑，黑轨与黑底素材一并剥净、候选轨层级不受影响 |
 | 填充太差 / 命中太杂 | 调 `--score-floor`（调高更严、露主轨；调低更满、可能杂）重跑 |
 | 每段候选太少不够挑 | 调 `--top-k`（每 query 给更多候选）重跑 |
 | 某段有空槽 / 漏检 / 想补个特定意象 | `gtrk matrix search "<英文长句场景描述>" --project <目录> --json` 单条 ad-hoc 补检，把中意的候选记下、在 opencut 里手动铺进那段 |