@biunow/agent-biuart 0.0.0-stage → 0.1.0

package/lib/render-bridge.mjs

@@ -0,0 +1,543 @@
+/**
+ * BiuArt 渲染桥：用 Node 驱动 Chromium 逐帧抓 canvas，再交给 ffmpeg 编码。
+ * 只做调度，不改引擎内部；像素链路与 huashu render.py 保持一致：
+ *   canvas.toDataURL('image/png') → image2pipe → libx264 / ProRes 4444
+ */
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const FRAME_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp']);
+const PRESETS = new Set(['neutral', 'bun', 'author']);
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.mp4': 'video/mp4',
+  '.mov': 'video/quicktime',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+};
+
+export function resolveEngineRoot(explicit = '') {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    explicit,
+    process.env.ENGINE_ROOT,
+    path.resolve(here, '..', 'engine'),
+  ].filter(Boolean);
+  for (const dir of candidates) {
+    if (fs.existsSync(path.join(dir, 'index.html')) && fs.existsSync(path.join(dir, 'clip.html'))) {
+      return path.resolve(dir);
+    }
+  }
+  return '';
+}
+
+export function ffmpegBin() {
+  if (process.env.BIUART_FFMPEG) return process.env.BIUART_FFMPEG;
+  if (process.env.EXPLAINROO_FFMPEG) return process.env.EXPLAINROO_FFMPEG;
+  return 'ffmpeg';
+}
+
+function isUrl(value) {
+  return typeof value === 'string' && /^(data:|https?:)/i.test(value);
+}
+
+function toFileUrl(absPath) {
+  return `/__file__/${encodeURIComponent(absPath)}`;
+}
+
+function fileInBase(value, base, allowed, what) {
+  if (!value) return value;
+  if (isUrl(value)) return value;
+  const abs = path.resolve(base, String(value));
+  let st;
+  try {
+    st = fs.statSync(abs);
+  } catch {
+    throw new Error(`spec 里的${what}不存在：${value}（相对 ${base}）`);
+  }
+  if (!st.isFile()) throw new Error(`spec 里的${what}不是文件：${value}（相对 ${base}）`);
+  allowed.add(abs);
+  return toFileUrl(abs);
+}
+
+function dirFrames(value, base, what) {
+  const dir = path.resolve(base, String(value));
+  let st;
+  try {
+    st = fs.statSync(dir);
+  } catch {
+    throw new Error(`spec 里的${what}目录不存在：${value}（相对 ${base}）`);
+  }
+  if (!st.isDirectory()) return null;
+  const files = fs.readdirSync(dir)
+    .filter((name) => FRAME_EXT.has(path.extname(name).toLowerCase()))
+    .sort()
+    .map((name) => path.join(dir, name));
+  if (!files.length) throw new Error(`spec 里的${what}目录是空的：${value}`);
+  return files;
+}
+
+/** 把 spec 里的本地素材路径改写成本地服务可取的 URL（对应 spec_assets.py）。 */
+export function localizeSpec(input, baseDir) {
+  const spec = JSON.parse(JSON.stringify(input));
+  const base = path.resolve(baseDir);
+  const allowed = new Set();
+  for (const cue of spec.cues || []) {
+    if (cue.image) cue.image = fileInBase(cue.image, base, allowed, '图片');
+    if (typeof cue.frames === 'string') {
+      const files = dirFrames(cue.frames, base, '帧序列');
+      if (!files) throw new Error(`spec 里的帧序列目录不存在：${cue.frames}（相对 ${base}）`);
+      cue.frames = files.map((file) => {
+        allowed.add(file);
+        return toFileUrl(file);
+      });
+    } else if (Array.isArray(cue.frames)) {
+      if (!cue.frames.length) throw new Error('spec 里的 frames 是空数组');
+      cue.frames = cue.frames.map((file) => fileInBase(file, base, allowed, '视频帧'));
+    }
+  }
+  const data = spec.data || {};
+  if (data.image) data.image = fileInBase(data.image, base, allowed, '图片');
+  const character = data.character;
+  if (typeof character === 'string' && !PRESETS.has(character)) {
+    const files = dirFrames(character, base, '角色帧库');
+    if (!files) throw new Error(`data.character 既不是预设也不是帧库目录：${character}`);
+    data.character = {
+      frames: Object.fromEntries(files.map((file) => {
+        allowed.add(file);
+        return [path.basename(file, path.extname(file)), toFileUrl(file)];
+      })),
+    };
+  } else if (character && typeof character === 'object') {
+    const frames = character.frames;
+    if (typeof frames === 'string') {
+      const files = dirFrames(frames, base, '角色帧库');
+      if (!files) throw new Error(`data.character.frames 目录不存在：${frames}`);
+      character.frames = Object.fromEntries(files.map((file) => {
+        allowed.add(file);
+        return [path.basename(file, path.extname(file)), toFileUrl(file)];
+      }));
+    } else if (frames && typeof frames === 'object') {
+      for (const [pose, value] of Object.entries(frames)) {
+        frames[pose] = fileInBase(value, base, allowed, `角色帧「${pose}」`);
+      }
+    }
+  }
+  return { spec, allowed };
+}
+
+function serveFile(res, file) {
+  let st;
+  try {
+    st = fs.statSync(file);
+  } catch {
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('not found');
+    return;
+  }
+  if (st.isDirectory()) {
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('not found');
+    return;
+  }
+  res.writeHead(200, {
+    'content-type': MIME[path.extname(file).toLowerCase()] || 'application/octet-stream',
+    'content-length': st.size,
+    'cache-control': 'no-store',
+    'access-control-allow-origin': '*',
+  });
+  fs.createReadStream(file).pipe(res);
+}
+
+function startStaticServer(engineRoot, allowed) {
+  const root = path.resolve(engineRoot);
+  const server = http.createServer((req, res) => {
+    try {
+      const url = new URL(req.url || '/', 'http://local');
+      let pathname;
+      try {
+        pathname = decodeURIComponent(url.pathname);
+      } catch {
+        pathname = url.pathname;
+      }
+      if (pathname.startsWith('/__file__/')) {
+        const file = path.resolve(pathname.slice('/__file__/'.length));
+        if (!allowed.has(file)) {
+          res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+          res.end('forbidden');
+          return;
+        }
+        serveFile(res, file);
+        return;
+      }
+      let file = path.resolve(root, `.${pathname}`);
+      if (file !== root && !file.startsWith(root + path.sep)) {
+        res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end('forbidden');
+        return;
+      }
+      if (fs.existsSync(file) && fs.statSync(file).isDirectory()) file = path.join(file, 'index.html');
+      serveFile(res, file);
+    } catch (error) {
+      res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
+      res.end(String(error?.message || error));
+    }
+  });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      resolve({ server, port: server.address().port });
+    });
+  });
+}
+
+async function loadPlaywright(engineRoot) {
+  const normalize = (mod) => (mod?.chromium ? mod : (mod?.default?.chromium ? mod.default : mod));
+  const tries = ['playwright-core', 'playwright'];
+  for (const name of tries) {
+    try {
+      return normalize(await import(name));
+    } catch {
+      /* try next */
+    }
+  }
+  const local = path.join(engineRoot, 'node_modules', 'playwright-core', 'index.js');
+  if (fs.existsSync(local)) return normalize(await import(pathToFileURL(local).href));
+  throw new Error('缺少 playwright-core：请安装共享运行时 biuart-npm@1，或在产品目录执行 npm install');
+}
+
+function chromiumCandidates() {
+  const out = [
+    process.env.BIUART_CHROME,
+    process.env.EXPLAINROO_CHROME,
+    process.env.PANEL_CHROME,
+    process.env.CHROME_PATH,
+  ].filter(Boolean);
+  const roots = [
+    process.env.PLAYWRIGHT_BROWSERS_PATH,
+    process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'ms-playwright'),
+    path.join(os.homedir(), '.cache', 'ms-playwright'),
+    path.join(os.homedir(), 'Library', 'Caches', 'ms-playwright'),
+  ].filter(Boolean);
+  const suffixes = [
+    ['chrome-win', 'chrome.exe'],
+    ['chrome-win64', 'chrome.exe'],
+    ['chrome-linux', 'chrome'],
+    ['chrome-mac', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'],
+    ['chrome-mac-arm64', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'],
+    ['chrome-win', 'headless_shell.exe'],
+    ['chrome-win64', 'headless_shell.exe'],
+    ['chrome-linux', 'headless_shell'],
+    ['chrome-headless-shell-win64', 'chrome-headless-shell.exe'],
+    ['chrome-headless-shell-win', 'chrome-headless-shell.exe'],
+    ['chrome-headless-shell-linux64', 'chrome-headless-shell'],
+    ['chrome-headless-shell-mac-arm64', 'chrome-headless-shell'],
+    ['chrome-headless-shell-mac-x64', 'chrome-headless-shell'],
+  ];
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    for (const name of fs.readdirSync(root)) {
+      if (!/^chromium/.test(name)) continue;
+      for (const suffix of suffixes) {
+        const file = path.join(root, name, ...suffix);
+        if (fs.existsSync(file)) out.push(file);
+      }
+    }
+  }
+  out.push(
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files\\Chromium\\Application\\chrome.exe',
+  );
+  return out;
+}
+
+function findChromium() {
+  for (const file of chromiumCandidates()) {
+    try {
+      if (fs.existsSync(file)) return file;
+    } catch {
+      /* skip */
+    }
+  }
+  return '';
+}
+
+function roundFrames(seconds, fps) {
+  return Math.round(seconds * fps);
+}
+
+function writeFrame(stream, buffer) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => {
+      stream.off('drain', onDrain);
+      reject(error);
+    };
+    const onDrain = () => {
+      stream.off('error', onError);
+      resolve();
+    };
+    const ok = stream.write(buffer, (error) => {
+      if (error) {
+        stream.off('drain', onDrain);
+        reject(error);
+      }
+    });
+    if (ok) {
+      stream.off('error', onError);
+      resolve();
+    } else {
+      stream.once('drain', onDrain);
+      stream.once('error', onError);
+    }
+  });
+}
+
+function runProcess(command, args, { onStderr } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { windowsHide: true });
+    let stderr = '';
+    child.stderr?.on('data', (chunk) => {
+      stderr += chunk.toString();
+      onStderr?.(chunk.toString());
+    });
+    child.once('error', reject);
+    child.once('close', (code) => {
+      if (code === 0) resolve({ code, stderr });
+      else reject(new Error(`${command} 退出码 ${code}\n${stderr.slice(-4000)}`));
+    });
+  });
+}
+
+function ffmpegVideoArgs({ alpha, fps, crf, isSpec, out }) {
+  if (alpha) {
+    return ['-c:v', 'prores_ks', '-profile:v', '4444', '-pix_fmt', 'yuva444p10le', '-alpha_bits', '16', out];
+  }
+  return [
+    '-c:v', 'libx264',
+    '-preset', 'slow',
+    '-crf', String(crf),
+    '-pix_fmt', 'yuv420p',
+    '-movflags', '+faststart',
+    ...(isSpec ? ['-g', String(fps), '-keyint_min', String(fps), '-sc_threshold', '0'] : []),
+    out,
+  ];
+}
+
+async function muxAudio({ video, audio, t0, t1, out }) {
+  await runProcess(ffmpegBin(), [
+    '-y', '-v', 'error',
+    '-i', video,
+    '-ss', String(t0), '-t', String(t1 - t0), '-i', audio,
+    '-map', '0:v', '-map', '1:a',
+    '-c:v', 'copy', '-c:a', 'aac', '-b:a', '256k', '-shortest',
+    out,
+  ]);
+}
+
+/**
+ * 渲染参数化片段、单个场景或整片。
+ * options: { engineRoot, specPath|spec, solo, film, out, fps, from, to,
+ *            width, height, stills, alpha, audio, crf, counter, onProgress, signal }
+ */
+export async function render(options) {
+  const engineRoot = resolveEngineRoot(options.engineRoot);
+  if (!engineRoot) throw new Error('找不到引擎目录：请设置 ENGINE_ROOT 或把引擎放到产品 engine/');
+  const {
+    out, stills, audio, crf = 14, onProgress, signal,
+    solo, film = '', counter = true,
+  } = options;
+  if (!out) throw new Error('缺少 --out');
+
+  let spec = options.spec || null;
+  let allowed = new Set();
+  let baseDir = process.cwd();
+  if (options.specPath) {
+    const specFile = path.resolve(options.specPath);
+    spec = JSON.parse(fs.readFileSync(specFile, 'utf8'));
+    baseDir = path.dirname(specFile);
+  }
+  if (spec) {
+    const localized = localizeSpec(spec, baseDir);
+    spec = localized.spec;
+    allowed = localized.allowed;
+    if (options.alpha) spec.alpha = true;
+    if (options.width || options.height) {
+      spec.width = options.width || spec.width || 1920;
+      spec.height = options.height || spec.height || 1080;
+    }
+  }
+
+  const { server, port } = await startStaticServer(engineRoot, allowed);
+  const { chromium } = await loadPlaywright(engineRoot);
+  const executablePath = findChromium();
+  const browser = await chromium.launch({
+    headless: true,
+    ...(executablePath ? { executablePath } : {}),
+    args: ['--disable-web-security', '--enable-gpu-rasterization', '--ignore-gpu-blocklist'],
+  });
+  const errors = [];
+  let page;
+  try {
+    page = await browser.newPage({
+      viewport: { width: options.width || 1920, height: options.height || 1080 },
+      deviceScaleFactor: 1,
+    });
+    page.on('console', (message) => {
+      if (message.type() === 'error') {
+        errors.push(message.text());
+        console.error('[page]', message.text());
+      }
+    });
+    page.on('pageerror', (error) => {
+      errors.push(String(error));
+      console.error('[pageerror]', String(error));
+    });
+
+    let grab;
+    let t0 = options.from == null ? 0 : Number(options.from);
+    let t1 = options.to == null ? null : Number(options.to);
+    let fps = Number(options.fps || 60);
+
+    if (spec) {
+      const width = spec.width || 1920;
+      const height = spec.height || 1080;
+      await page.setViewportSize({ width, height });
+      await page.addInitScript(`window.CLIP_SPEC = ${JSON.stringify(spec)};`);
+      await page.goto(`http://127.0.0.1:${port}/clip.html?render=1`, { waitUntil: 'load' });
+      fps = Number(spec.fps || 30);
+      t0 = options.from == null ? 0 : Number(options.from);
+      t1 = options.to == null ? Number(spec.duration) : Math.min(Number(spec.duration), Number(options.to));
+      grab = async (t) => page.evaluate(async (time) => {
+        await window.prepare(time);
+        window.renderFrame(time);
+        return window.__canvas.toDataURL('image/png').split(',')[1];
+      }, t);
+    } else {
+      const width = options.width || 1920;
+      const height = options.height || 1080;
+      await page.setViewportSize({ width, height });
+      const query = [
+        'render=1',
+        film ? `film=${encodeURIComponent(film)}` : '',
+        options.width || options.height ? `w=${width}&h=${height}` : '',
+      ].filter(Boolean).join('&');
+      await page.goto(`http://127.0.0.1:${port}/index.html?${query}`, { waitUntil: 'load' });
+      if (solo) {
+        grab = async (t) => page.evaluate(async ({ id, time, drawCounter }) => {
+          window.renderSolo(id, time, { counter: drawCounter });
+          return window.__canvas.toDataURL('image/png').split(',')[1];
+        }, { id: solo, time: t, drawCounter: counter });
+        if (t1 == null) {
+          t1 = await page.evaluate((id) => {
+            const entry = (window.ERAS || []).find((item) => item.id === id);
+            if (!entry) throw new Error(`renderSolo: 没有这一段 ${id}`);
+            if (entry.dur != null) return Number(entry.dur);
+            return Number(entry.t1) - Number(entry.t0 ?? 0);
+          }, solo);
+        }
+      } else {
+        grab = async (t) => page.evaluate(async (time) => {
+          await window.prepare(time);
+          window.renderFrame(time);
+          return window.__canvas.toDataURL('image/png').split(',')[1];
+        }, t);
+        if (t1 == null) t1 = Number(await page.evaluate(() => window.__total));
+      }
+    }
+
+    await page.waitForFunction('window.__ready === true || !!window.__bootFailed', null, { timeout: 120000 });
+    const bootFailed = await page.evaluate(() => window.__bootFailed || null);
+    if (bootFailed) throw new Error(`场景加载失败，拒绝渲染：\n${bootFailed}`);
+    if (!(t1 > t0)) throw new Error(`渲染区间无效：${t0} → ${t1}`);
+
+    if (stills) {
+      const dir = path.resolve(out);
+      fs.mkdirSync(dir, { recursive: true });
+      const times = String(stills).split(',').map(Number).filter(Number.isFinite);
+      for (const time of times) {
+        const base64 = await grab(time);
+        fs.writeFileSync(path.join(dir, `t${time.toFixed(2).padStart(6, '0')}.png`), Buffer.from(base64, 'base64'));
+      }
+      return { out: dir, mode: 'stills', frames: times.length, stills: times, errors, engineRoot };
+    }
+
+    fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+    const alpha = !!(spec && spec.alpha);
+    const videoOut = audio && !alpha ? `${out}.noaudio.mp4` : out;
+    const args = [
+      '-y', '-v', 'error',
+      '-f', 'image2pipe', '-framerate', String(fps), '-c:v', 'png', '-i', '-',
+      ...ffmpegVideoArgs({ alpha, fps, crf, isSpec: !!spec, out: videoOut }),
+    ];
+    const ff = spawn(ffmpegBin(), args, { windowsHide: true, stdio: ['pipe', 'ignore', 'pipe'] });
+    let ffErr = '';
+    ff.stderr.on('data', (chunk) => {
+      ffErr += chunk.toString();
+    });
+    const finished = new Promise((resolve, reject) => {
+      ff.once('error', reject);
+      ff.once('close', (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`ffmpeg 编码失败（退出码 ${code}）\n${ffErr.slice(-4000)}`));
+      });
+    });
+
+    const n0 = roundFrames(t0, fps);
+    const n1 = roundFrames(t1, fps);
+    const started = Date.now();
+    for (let i = n0; i < n1; i += 1) {
+      if (signal?.aborted) throw new Error('渲染已取消');
+      const base64 = await grab(i / fps);
+      await writeFrame(ff.stdin, Buffer.from(base64, 'base64'));
+      if ((i - n0) % 30 === 0 || i === n1 - 1) {
+        onProgress?.({
+          frame: i - n0 + 1,
+          total: n1 - n0,
+          seconds: (Date.now() - started) / 1000,
+          time: i / fps,
+        });
+      }
+    }
+    ff.stdin.end();
+    await finished;
+    if (audio) await muxAudio({ video: videoOut, audio, t0, t1, out });
+    if (audio && videoOut !== out) fs.rmSync(videoOut, { force: true });
+    return {
+      out: path.resolve(out),
+      mode: spec ? 'spec' : (solo ? 'solo' : 'film'),
+      frames: n1 - n0,
+      duration: t1 - t0,
+      fps,
+      width: spec ? spec.width || options.width || 1920 : options.width || 1920,
+      height: spec ? spec.height || options.height || 1080 : options.height || 1080,
+      errors,
+      engineRoot,
+      chrome: executablePath || 'playwright-default',
+    };
+  } finally {
+    try {
+      await browser.close();
+    } catch {
+      /* ignore */
+    }
+    await new Promise((resolve) => server.close(resolve));
+  }
+}

package/lib/render-cli.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * BiuArt 渲染 CLI（给 DSH 里的 Agent 用）
+ *
+ *   node lib/render-cli.mjs --out out/clip.mp4 --spec clip.json
+ *   node lib/render-cli.mjs --out out/cave.mp4 --solo 01_cave --from 0 --to 4
+ *   node lib/render-cli.mjs --out out/stills --solo 09_postimp --stills 0.5,2,3.5
+ *
+ * 引擎默认取 ENGINE_ROOT 或产品 engine/；也可用 --engine 指定。
+ * 成功时 stdout 输出一行 JSON 结果，进度写 stderr。
+ */
+import path from 'node:path';
+import { render, resolveEngineRoot } from './render-bridge.mjs';
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      args[key] = next;
+      i += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help || args.h) {
+  console.log([
+    'BiuArt render CLI',
+    '  --out <file|dir>          必填。--stills 时是目录',
+    '  --spec <clip.json>        参数化片段',
+    '  --solo <sceneId>          只渲一个场景（时间为本段局部时间）',
+    '  --film <name>             段落表：默认 eras.js；style_studies 读 eras_style_studies.js',
+    '  --from <sec> --to <sec>   片段区间；--solo 默认整段',
+    '  --fps <n>                 默认 60（spec 用自己的 fps）',
+    '  --width <px> --height <px>',
+    '  --stills <0.5,2.0>        只导出这些时刻的 png',
+    '  --alpha                   透明底 ProRes 4444（配 --spec，输出 .mov）',
+    '  --audio <file>            混入音轨',
+    '  --crf <n>                 默认 14',
+    '  --no-counter              场景角标不画',
+    '  --engine <dir>            引擎目录（默认 ENGINE_ROOT / 产品 engine）',
+  ].join('\n'));
+  process.exit(0);
+}
+
+const engineRoot = resolveEngineRoot(String(args.engine || ''));
+if (!engineRoot) {
+  console.error('找不到引擎目录：用 --engine 指定，或设置 ENGINE_ROOT。');
+  process.exit(2);
+}
+if (!args.out) {
+  console.error('缺少 --out');
+  process.exit(2);
+}
+if (!args.spec && !args.solo && args.to == null) {
+  console.error('整片渲染必须给 --to（或改用 --solo / --spec）');
+  process.exit(2);
+}
+
+const controller = new AbortController();
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => controller.abort());
+}
+
+try {
+  const result = await render({
+    engineRoot,
+    out: path.resolve(String(args.out)),
+    specPath: args.spec ? String(args.spec) : '',
+    solo: args.solo ? String(args.solo) : '',
+    film: args.film ? String(args.film) : '',
+    from: args.from,
+    to: args.to,
+    fps: args.fps,
+    width: args.width ? Number(args.width) : undefined,
+    height: args.height ? Number(args.height) : undefined,
+    stills: args.stills,
+    alpha: !!args.alpha,
+    audio: args.audio ? path.resolve(String(args.audio)) : '',
+    crf: args.crf ? Number(args.crf) : 14,
+    counter: !args['no-counter'],
+    signal: controller.signal,
+    onProgress: (progress) => {
+      console.error(`[biuart] ${progress.frame}/${progress.total}  ${progress.seconds.toFixed(0)}s`);
+    },
+  });
+  console.log(JSON.stringify({ ok: true, ...result }));
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, error: error?.message || String(error) }));
+  process.exit(1);
+}

package/lib/storyboard-lint.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * BiuArt 镜头表红线检查。
+ *   node lib/storyboard-lint.mjs storyboard.md
+ * 退出码 1 = 红灯，禁止进入渲染。
+ */
+import fs from 'node:fs';
+
+const file = process.argv[2];
+if (!file) {
+  console.error('用法：node lib/storyboard-lint.mjs <storyboard.md>');
+  process.exit(2);
+}
+const text = fs.readFileSync(file, 'utf8');
+const blocks = text.split(/^##\s+/m).slice(1);
+const problems = [];
+const warnings = [];
+
+if (!blocks.length) problems.push('没有镜头：每个镜头用 "## S01 · 0.0–3.5s" 开头');
+const FIELDS = ['物', '动作', '镜头', '做法'];
+let cardEnding = 0;
+let staticShots = 0;
+
+for (const block of blocks) {
+  const title = block.split('\n')[0].trim() || '(未命名镜头)';
+  const line = (name) => {
+    const match = block.match(new RegExp(`^\\s*[-*]\\s*${name}\\s*[：:]\\s*(.+)$`, 'm'));
+    return match ? match[1].trim() : '';
+  };
+  for (const field of FIELDS) {
+    if (!line(field)) problems.push(`${title}：缺少「${field}」`);
+  }
+  const action = line('动作');
+  if (/^(无|静止|不动|固定)$/.test(action)) problems.push(`${title}：动作不能是「${action}」，每镜必须有镜头内动作`);
+  if (/字卡|纯文字|标题卡/.test(line('做法'))) cardEnding += 1;
+  if (/死背景|空镜/.test(action)) staticShots += 1;
+  if (!/(→|->|，|,|；|;)/.test(action) && action.length < 6) {
+    warnings.push(`${title}：动作描述偏短，建议写清「什么物 + 怎么动」`);
+  }
+}
+
+if (blocks.length >= 3 && cardEnding / blocks.length > 0.2) {
+  problems.push(`字卡镜头占 ${cardEnding}/${blocks.length}，超过 20%：用画面叙事，不要用字卡凑时长`);
+}
+if (blocks.length >= 3 && staticShots === blocks.length) {
+  problems.push('所有镜头都是死背景：至少让背景或主体持续运动');
+}
+if (!/色板|palette/i.test(text)) {
+  warnings.push('没有写色板：建议在镜头表开头锁定一套色板与画风');
+}
+
+const report = { file, shots: blocks.length, problems, warnings, red: problems.length > 0 };
+console.log(JSON.stringify(report, null, 2));
+if (report.red) process.exit(1);