minimal-agent 0.8.2 → 0.10.0

package/skills/ai-image/scripts/generate_from_plan.mjs

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+/**
+ * generate_from_plan.mjs —— 按 img_plan.json 确定性生成 PPT 配图。
+ *
+ * 输入 plan 条目：
+ *   {file, mode:"text-to-image", aspect, prompt}
+ *   {file, mode:"image-to-image", source_file, aspect, prompt}
+ *
+ * 该脚本只负责循环、校验、调用 generate.mjs；真正请求体组装仍在 generate.mjs。
+ */
+
+import { access, copyFile, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { deflateSync } from 'node:zlib';
+
+const generateScript = fileURLToPath(new URL('./generate.mjs', import.meta.url));
+
+function parseArgs(argv) {
+  const out = {};
+  const keys = new Set([
+    'plan',
+    'assets',
+    'timeout-ms',
+    'size',
+    'model',
+    'dry-run',
+    'dry-run-request',
+    'wall-budget-ms',
+    'retry-degraded-report',
+    'max-rounds',
+    'concurrency',
+  ]);
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (!tok.startsWith('--')) continue;
+    const body = tok.slice(2);
+    const eq = body.indexOf('=');
+    let key;
+    let val;
+    if (eq !== -1) {
+      key = body.slice(0, eq);
+      val = body.slice(eq + 1);
+    } else {
+      key = body;
+      val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : '';
+    }
+    if (keys.has(key)) out[key] = val;
+  }
+  return out;
+}
+
+function err(msg) {
+  process.stderr.write(`${msg}\n`);
+}
+
+function isUrlOrData(value) {
+  return /^https?:\/\//i.test(value || '') || String(value || '').startsWith('data:image/');
+}
+
+function resolveUnder(baseDir, value, label) {
+  if (!value) throw new Error(`${label} 不能为空`);
+  if (isAbsolute(value)) return value;
+  const absBase = resolve(baseDir);
+  const abs = resolve(absBase, value);
+  // 跨平台包含判定：用 path.relative，**不要**硬编码分隔符。
+  // 旧逻辑 `abs.startsWith(`${absBase}/`)` 用正斜杠，但 Windows 上 path.resolve 产出反斜杠 `\`，
+  // 于是 assets 下任何子文件（enhanced_src_1.jpg / img_2.png）都被误判「跳出 assets 目录」而整批失败。
+  // relative(base, abs) 在 abs 越界时以 `..` 开头、跨盘符时返回绝对路径——据此判定，三平台一致。
+  const rel = relative(absBase, abs);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`${label} 不能跳出 assets 目录：${value}`);
+  }
+  return abs;
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function timeoutMs(args) {
+  const v = Number(args['timeout-ms']);
+  return Number.isFinite(v) && v > 0 ? Math.floor(v) : 600_000;
+}
+
+function validateItem(item, index) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) {
+    throw new Error(`img_plan[${index}] 必须是对象`);
+  }
+  const mode = item.mode || 'text-to-image';
+  if (mode !== 'text-to-image' && mode !== 'image-to-image') {
+    throw new Error(`img_plan[${index}].mode 非法：${mode}`);
+  }
+  if (typeof item.file !== 'string' || !item.file.trim()) {
+    throw new Error(`img_plan[${index}].file 必填`);
+  }
+  if (typeof item.prompt !== 'string' || !item.prompt.trim()) {
+    throw new Error(`img_plan[${index}].prompt 必填`);
+  }
+  if (mode === 'image-to-image' && (typeof item.source_file !== 'string' || !item.source_file.trim())) {
+    throw new Error(`img_plan[${index}] 为 image-to-image 时 source_file 必填`);
+  }
+  return mode;
+}
+
+function commandForItem(item, mode, assetsDir, args) {
+  const outPath = resolveUnder(assetsDir, item.file, `img_plan.file(${item.file})`);
+  const cmd = [
+    generateScript,
+    '--prompt',
+    item.prompt,
+    '--out',
+    outPath,
+    '--size',
+    args.size || '1K',
+  ];
+  if (item.aspect) cmd.push('--aspect', String(item.aspect));
+  if (args.model) cmd.push('--model', args.model);
+  if (mode === 'image-to-image') {
+    const src = isUrlOrData(item.source_file)
+      ? item.source_file
+      : resolveUnder(assetsDir, item.source_file, `img_plan.source_file(${item.source_file})`);
+    cmd.push('--input-image', src);
+  }
+  if (args['dry-run-request'] !== undefined) cmd.push('--dry-run-request');
+  return { cmd, outPath };
+}
+
+async function filterRetryPlan(plan, reportPath) {
+  if (!reportPath) return { plan, retryOf: null };
+  let report;
+  try {
+    report = JSON.parse(await readFile(reportPath, 'utf8'));
+  } catch (e) {
+    throw new Error(`读取 retry-degraded-report 失败：${e?.message ?? e}`);
+  }
+  const degraded = Array.isArray(report?.degraded) ? report.degraded : [];
+  const files = new Set(degraded.map((item) => item?.file).filter(Boolean));
+  return {
+    plan: plan.filter((item) => files.has(item?.file)),
+    retryOf: reportPath,
+  };
+}
+
+// ── 降级兜底：让「期望的图片文件永远存在」，AI 配图失败也绝不让 deck 坏图、绝不报错 ──
+// CRC32（PNG chunk 校验，避免依赖 zlib.crc32 的 Node 版本差异）。
+const _CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = _CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+function pngChunk(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 dimsForAspect(aspect) {
+  const m = String(aspect || '16:9').match(/^(\d+)\s*[:x×]\s*(\d+)$/);
+  let aw = 16;
+  let ah = 9;
+  if (m) {
+    aw = Number(m[1]) || 16;
+    ah = Number(m[2]) || 9;
+  }
+  const base = 1024;
+  return aw >= ah
+    ? [base, Math.max(64, Math.round((base * ah) / aw))]
+    : [Math.max(64, Math.round((base * aw) / ah)), base];
+}
+// 写一张确定性深色竖向渐变 PNG（纯 node:zlib，无第三方依赖、绿色版安全）作 AI 图兜底背景。
+async function writeGradientPng(outPath, aspect) {
+  const [w, h] = dimsForAspect(aspect);
+  const top = [30, 41, 59]; // 深蓝灰
+  const bot = [8, 11, 18]; // 近黑
+  const raw = Buffer.alloc(h * (1 + w * 3));
+  for (let y = 0; y < h; y++) {
+    const rowStart = y * (1 + w * 3);
+    raw[rowStart] = 0; // filter: none
+    const tt = h === 1 ? 0 : y / (h - 1);
+    const r = Math.round(top[0] + (bot[0] - top[0]) * tt);
+    const g = Math.round(top[1] + (bot[1] - top[1]) * tt);
+    const b = Math.round(top[2] + (bot[2] - top[2]) * tt);
+    for (let x = 0; x < w; x++) {
+      const p = rowStart + 1 + x * 3;
+      raw[p] = r;
+      raw[p + 1] = g;
+      raw[p + 2] = b;
+    }
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(w, 0);
+  ihdr.writeUInt32BE(h, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 2; // color type: RGB
+  const png = Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    pngChunk('IHDR', ihdr),
+    pngChunk('IDAT', deflateSync(raw)),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ]);
+  await writeFile(outPath, png);
+}
+// 单张图生成失败 → 写降级占位资产（图生图退回原图、文生图/无原图退渐变），永不抛。
+async function degradeFallback(item, mode, outPath, assetsDir, reason) {
+  try {
+    if (mode === 'image-to-image' && item?.source_file && !isUrlOrData(item.source_file)) {
+      const src = resolveUnder(assetsDir, item.source_file, `img_plan.source_file(${item.source_file})`);
+      if (await exists(src)) {
+        await copyFile(src, outPath);
+        return { file: item.file, source_file: item.source_file, mode, reason, fallback: 'copied-source' };
+      }
+    }
+    await writeGradientPng(outPath, item?.aspect);
+    return { file: item?.file, source_file: item?.source_file, mode, reason, fallback: 'gradient-png' };
+  } catch (e) {
+    try {
+      await writeGradientPng(outPath, item?.aspect);
+    } catch {
+      /* 兜底的兜底也失败就算了，绝不抛 */
+    }
+    return { file: item?.file, source_file: item?.source_file, mode, reason: `${reason}; fallback err ${e?.message ?? e}`, fallback: 'gradient-png' };
+  }
+}
+
+function spawnNode(cmd, ms) {
+  return new Promise((resolvePromise) => {
+    const captured = process.env.MINIMAL_AGENT_CAPTURED_STDIO === '1';
+    const child = spawn(process.execPath, cmd, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: process.env,
+    });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+    }, ms);
+    child.stdout.on('data', (d) => {
+      stdout += d.toString();
+      if (!captured) process.stdout.write(d);
+    });
+    child.stderr.on('data', (d) => {
+      stderr += d.toString();
+      if (!captured) process.stderr.write(d);
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      resolvePromise({ code: code ?? 1, signal, stdout, stderr });
+    });
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const planPath = args.plan || './build/img_plan.json';
+  const assetsDir = resolve(args.assets || dirname(planPath));
+
+  if (!(await exists(planPath))) {
+    console.log(`PLAN_EMPTY: ${planPath} 不存在，跳过生图。`);
+    return;
+  }
+
+  let plan;
+  try {
+    plan = JSON.parse(await readFile(planPath, 'utf8'));
+  } catch (e) {
+    err(`PLAN_ERROR: 读取/解析 ${planPath} 失败：${e?.message ?? e}`);
+    process.exit(2);
+  }
+  if (!Array.isArray(plan)) {
+    err(`PLAN_ERROR: ${planPath} 应是数组`);
+    process.exit(2);
+  }
+  if (plan.length === 0) {
+    console.log(`PLAN_EMPTY: ${planPath} 是空数组，跳过生图。`);
+    return;
+  }
+  const retryPlan = await filterRetryPlan(plan, args['retry-degraded-report']);
+  plan = retryPlan.plan;
+  if (args['retry-degraded-report'] && plan.length === 0) {
+    console.log(`PLAN_RETRY_EMPTY: ${args['retry-degraded-report']} 没有 degraded 条目需要重试。`);
+    return;
+  }
+
+  await mkdir(assetsDir, { recursive: true });
+  // hardErrors = 计划结构/安全校验失败（malformed plan / 路径越界）——这是计划 bug，仍响亮 exit 1。
+  // degraded = AI 生成失败（敏感内容/超时/网络/空输出）——写降级占位、恒 exit 0、绝不阻断（用户铁律：配图失败永不报错）。
+  const hardErrors = [];
+  const degraded = [];
+  const generated = [];
+  const attempts = [];
+
+  // 总时长自限：防整步耗时撞工具级超时被 SIGKILL（不够就把剩余全部降级、主动收尾）。
+  const startedAt = Date.now();
+  const wallBudgetMs = Number(args['wall-budget-ms']) > 0 ? Number(args['wall-budget-ms']) : 540_000;
+  // 成本不计、最大努力生图：单张预留放宽到 100s（原 70s），减少尾部图因预算临界被误降级。
+  const PER_IMAGE_RESERVE_MS = 100_000;
+  const maxRounds =
+    Number(args['max-rounds']) > 0
+      ? Math.floor(Number(args['max-rounds']))
+      : args['retry-degraded-report']
+        ? 3
+        : 1;
+
+  // 批内并发（--concurrency N，默认 1 = 顺序执行、行为与旧版一致）：31 张 ≈ 15min 的串行生图是
+  // ppt 工作流最大耗时项；provider 通常允许小并发（ppt.yaml 传 2）。共享数组（degraded/generated/
+  // attempts/nextPending）的 push 在 JS 单线程事件循环下天然原子；wall-budget 检查每张开跑前各自做，
+  // 预算耗尽时并发在飞的张各自收尾、其余降级——语义与串行版一致。
+  const concurrency = Math.max(1, Math.floor(Number(args.concurrency) || 1));
+
+  let pending = plan.map((item, index) => ({ item, index }));
+  for (let round = 1; round <= maxRounds && pending.length; round++) {
+    const nextPending = [];
+    const processOne = async (pendingItem) => {
+    const item = pendingItem.item;
+    const i = pendingItem.index;
+    let mode;
+    let command;
+    let outPath;
+    // ① 结构/安全校验（失败=计划 bug，hardError、不降级）
+    try {
+      mode = validateItem(item, i);
+      ({ cmd: command, outPath } = commandForItem(item, mode, assetsDir, args));
+    } catch (e) {
+      hardErrors.push({ file: item?.file || `#${i}`, reason: e?.message ?? String(e) });
+      return;
+    }
+
+    if (args['dry-run'] !== undefined) {
+      console.error(`[ai-image-plan] round ${round}/${maxRounds} ${i + 1}/${plan.length} ${mode} → ${item.file}`);
+      console.log(JSON.stringify({ file: item.file, mode, command: [process.execPath, ...command] }));
+      generated.push(item.file);
+      attempts.push({ file: item.file, mode, round, status: 'dry-run' });
+      return;
+    }
+
+    // ② 原图缺失（img2img）→ 降级（无法复制，写渐变占位）
+    if (mode === 'image-to-image' && !isUrlOrData(item.source_file)) {
+      const sourcePath = resolveUnder(assetsDir, item.source_file, `img_plan.source_file(${item.source_file})`);
+      if (!(await exists(sourcePath))) {
+        console.error(`[ai-image-plan] ${i + 1}/${plan.length} 原图不存在 → 降级占位 ${item.file}`);
+        const d = await degradeFallback(item, mode, outPath, assetsDir, `source_file 不存在：${sourcePath}`);
+        degraded.push({ ...d, round });
+        attempts.push({ file: item.file, mode, round, status: 'degraded', reason: d.reason, fallback: d.fallback });
+        return;
+      }
+    }
+
+    // ③ 总时长不足 → 剩余全部降级（绝不被 SIGKILL）
+    const remaining = wallBudgetMs - (Date.now() - startedAt);
+    if (remaining < PER_IMAGE_RESERVE_MS) {
+      console.error(`[ai-image-plan] ${i + 1}/${plan.length} 时间预算不足（剩 ${Math.round(remaining / 1000)}s）→ 降级占位 ${item.file}`);
+      const d = await degradeFallback(item, mode, outPath, assetsDir, '总时长预算耗尽');
+      degraded.push({ ...d, round });
+      attempts.push({ file: item.file, mode, round, status: 'degraded', reason: d.reason, fallback: d.fallback });
+      return;
+    }
+
+    // ④ 真正生成；失败（含敏感内容 400/超时/空输出）→ 降级，绝不 exit 1
+    console.error(`[ai-image-plan] round ${round}/${maxRounds} ${i + 1}/${plan.length} ${mode} → ${item.file}`);
+    const perImageMs = Math.min(timeoutMs(args), Math.max(30_000, remaining - 10_000));
+    const attemptStartedAt = Date.now();
+    const result = await spawnNode(command, perImageMs);
+    if (result.code !== 0) {
+      console.error(`[ai-image-plan] ${item.file} 生成失败（exit ${result.code}${result.signal ? ` ${result.signal}` : ''}）→ 降级占位`);
+      const d = await degradeFallback(item, mode, outPath, assetsDir, `generate.mjs exit ${result.code}${result.signal ? ` signal ${result.signal}` : ''}`);
+      attempts.push({
+        file: item.file,
+        mode,
+        round,
+        status: 'degraded',
+        reason: d.reason,
+        fallback: d.fallback,
+        durationMs: Date.now() - attemptStartedAt,
+      });
+      if (round < maxRounds) nextPending.push(pendingItem);
+      else degraded.push({ ...d, round });
+      return;
+    }
+    if (args['dry-run-request'] === undefined) {
+      try {
+        const st = await stat(outPath);
+        if (!st.isFile() || st.size <= 0) throw new Error('输出文件为空');
+      } catch (e) {
+        const d = await degradeFallback(item, mode, outPath, assetsDir, `输出校验失败：${e?.message ?? e}`);
+        attempts.push({
+          file: item.file,
+          mode,
+          round,
+          status: 'degraded',
+          reason: d.reason,
+          fallback: d.fallback,
+          durationMs: Date.now() - attemptStartedAt,
+        });
+        if (round < maxRounds) nextPending.push(pendingItem);
+        else degraded.push({ ...d, round });
+        return;
+      }
+    }
+    generated.push(item.file);
+    attempts.push({ file: item.file, mode, round, status: 'generated', durationMs: Date.now() - attemptStartedAt });
+    };
+    const queue = [...pending];
+    const worker = async () => {
+      for (;;) {
+        const next = queue.shift();
+        if (!next) return;
+        await processOne(next);
+      }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, queue.length)) }, worker));
+    pending = nextPending;
+  }
+
+  // 结构/安全失败仍响亮（计划 bug 该暴露）；但 AI 生成失败只降级、恒 exit 0。
+  if (hardErrors.length) {
+    err(`IMAGE_PLAN_FAILED: ${hardErrors.length}/${plan.length} 张结构/安全校验失败（非生成失败，请修 img_plan）`);
+    for (const f of hardErrors) err(`- ${f.file}: ${f.reason}`);
+    process.exit(1);
+  }
+  if (degraded.length) {
+    err(`IMAGE_PLAN_DEGRADED: ${degraded.length}/${plan.length} 张退化（已写占位资产兜底、不阻断工作流）`);
+    for (const d of degraded) err(`- ${d.file}: ${d.reason}${d.fallback ? ` [${d.fallback}]` : ''}`);
+  }
+  const reportPath = resolve(assetsDir, '..', 'image_generation_report.json');
+  await writeFile(
+    reportPath,
+    JSON.stringify(
+      {
+        ok: hardErrors.length === 0,
+        qualityOk: hardErrors.length === 0 && degraded.length === 0,
+        retryOf: retryPlan.retryOf,
+        plan,
+        generated,
+        degraded,
+        hardErrors,
+        attempts,
+      },
+      null,
+      2,
+    ),
+    'utf8',
+  );
+  console.log(
+    `IMAGE_PLAN_OK: ${generated.length}/${plan.length} 张真实生成${degraded.length ? `，${degraded.length} 张退化占位（不阻断）` : ''}`,
+  );
+}
+
+main().catch((e) => {
+  err(`IMAGE_PLAN_ERROR: ${e?.message ?? e}`);
+  process.exit(1);
+});

package/skills/ai-image/scripts/generate_from_plan_test.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const script = fileURLToPath(new URL('./generate_from_plan.mjs', import.meta.url));
+
+async function withTmp(fn) {
+  const dir = await mkdtemp(join(tmpdir(), 'ai-image-plan-'));
+  try {
+    return await fn(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+function run(args) {
+  return spawnSync(process.execPath, [script, ...args], {
+    encoding: 'utf8',
+  });
+}
+
+function jsonLines(stdout) {
+  return stdout
+    .trim()
+    .split(/\n+/)
+    .filter((line) => line.trim().startsWith('{'))
+    .map((line) => JSON.parse(line));
+}
+
+await withTmp(async (dir) => {
+  const assets = join(dir, 'assets');
+  const plan = join(dir, 'img_plan.json');
+  await mkdir(assets, { recursive: true });
+  await writeFile(
+    plan,
+    JSON.stringify([
+      {
+        file: 'hero.png',
+        mode: 'text-to-image',
+        aspect: '16:9',
+        prompt: 'clean product hero background, no text',
+      },
+    ]),
+  );
+
+  const res = run(['--plan', plan, '--assets', assets, '--dry-run']);
+  assert.equal(res.status, 0, res.stderr);
+  const [item] = jsonLines(res.stdout);
+  assert.equal(item.file, 'hero.png');
+  assert.equal(item.mode, 'text-to-image');
+  assert.ok(item.command.includes('--prompt'));
+  assert.ok(item.command.includes('--out'));
+  assert.ok(!item.command.includes('--input-image'));
+});
+
+await withTmp(async (dir) => {
+  const assets = join(dir, 'assets');
+  const plan = join(dir, 'img_plan.json');
+  const sourceRel = 'source photos/src 1.png';
+  await mkdir(join(assets, 'source photos'), { recursive: true });
+  await writeFile(join(assets, sourceRel), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+  await writeFile(
+    plan,
+    JSON.stringify([
+      {
+        file: 'enhanced_src_1.png',
+        mode: 'image-to-image',
+        source_file: sourceRel,
+        aspect: '4:3',
+        prompt: 'extend background, keep product clear, no text',
+      },
+    ]),
+  );
+
+  const res = run(['--plan', plan, '--assets', assets, '--dry-run']);
+  assert.equal(res.status, 0, res.stderr);
+  const [item] = jsonLines(res.stdout);
+  assert.equal(item.mode, 'image-to-image');
+  const idx = item.command.indexOf('--input-image');
+  assert.ok(idx > -1);
+  assert.equal(item.command[idx + 1], join(assets, sourceRel));
+});
+
+await withTmp(async (dir) => {
+  const assets = join(dir, 'assets');
+  const plan = join(dir, 'img_plan.json');
+  await mkdir(assets, { recursive: true });
+  await writeFile(
+    plan,
+    JSON.stringify([
+      {
+        file: 'bad.png',
+        mode: 'image-to-image',
+        prompt: 'missing source should fail',
+      },
+    ]),
+  );
+
+  const res = run(['--plan', plan, '--assets', assets, '--dry-run']);
+  assert.notEqual(res.status, 0);
+  assert.match(res.stderr, /source_file 必填/);
+});
+
+await withTmp(async (dir) => {
+  const assets = join(dir, 'assets');
+  const plan = join(dir, 'img_plan.json');
+  await writeFile(plan, '[]');
+
+  const res = run(['--plan', plan, '--assets', assets, '--dry-run']);
+  assert.equal(res.status, 0, res.stderr);
+  assert.match(res.stdout, /PLAN_EMPTY/);
+});
+
+// 跨平台路径包含判定（回归：Windows 上 path.resolve 产出反斜杠，旧逻辑硬编码 `/` 会把
+// assets 下的 bare 文件名误判「跳出 assets 目录」整批失败）。这里锁双向语义：
+//  - bare 文件名（assets 直属）必须被接受（三平台一致）；
+//  - 真正用 `../` 越界必须被拒绝。
+await withTmp(async (dir) => {
+  const assets = join(dir, 'assets');
+  const plan = join(dir, 'img_plan.json');
+  await mkdir(assets, { recursive: true });
+  await writeFile(
+    plan,
+    JSON.stringify([
+      { file: 'img_2.png', mode: 'text-to-image', aspect: '4:3', prompt: 'in-dir bare name must pass' },
+      { file: '../escape.png', mode: 'text-to-image', prompt: 'must be rejected' },
+    ]),
+  );
+
+  const res = run(['--plan', plan, '--assets', assets, '--dry-run']);
+  // 第一条产出合法命令、第二条越界 → 整批以失败收尾（status≠0），但 bare 名不是因「跳出」失败。
+  const items = jsonLines(res.stdout);
+  assert.ok(
+    items.some((it) => it.file === 'img_2.png' && it.command.includes('--out')),
+    'assets 直属的 bare 文件名应被接受并产出命令',
+  );
+  assert.match(res.stderr, /不能跳出 assets 目录：\.\.\/escape\.png/);
+  assert.doesNotMatch(res.stderr, /img_2\.png: .*不能跳出/);
+});
+
+// AI 生成失败 → 降级写占位资产 + 恒 exit 0（用户铁律：配图失败永不报错、绝不让 deck 坏图）。
+// img2img 失败→复制原图；文生图失败→写渐变 PNG。
+await withTmp(async (dir) => {
+  const assets = join(dir, 'assets');
+  const plan = join(dir, 'img_plan.json');
+  await mkdir(assets, { recursive: true });
+  await writeFile(join(assets, 'src_1.png'), Buffer.from([0x89, 0x50, 0x4e, 0x47, 1, 2, 3, 4, 5]));
+  await writeFile(
+    plan,
+    JSON.stringify([
+      { file: 'enhanced_src_1.jpg', mode: 'image-to-image', source_file: 'src_1.png', aspect: '16:9', prompt: 'x' },
+      { file: 'img_1.png', mode: 'text-to-image', aspect: '4:5', prompt: 'y' },
+    ]),
+  );
+  // 去掉图片 API env → generate.mjs 必失败 → 触发降级路径（而非真打 API）。
+  const env = { ...process.env };
+  for (const k of [
+    'OPENAI_IMAGE_BASE_URL',
+    'OPENAI_IMAGE_API_KEY',
+    'OPENAI_IMAGE_MODEL',
+    'MINIMAL_AGENT_BASE_URL',
+    'MINIMAL_AGENT_API_KEY',
+    'MINIMAL_AGENT_MODEL',
+  ]) {
+    delete env[k];
+  }
+  const res = spawnSync(process.execPath, [script, '--plan', plan, '--assets', assets], { encoding: 'utf8', env });
+  assert.equal(res.status, 0, '配图失败必须恒 exit 0、绝不报错：' + res.stderr);
+  assert.match(res.stderr, /IMAGE_PLAN_DEGRADED/);
+  const report = JSON.parse(await readFile(join(dir, 'image_generation_report.json'), 'utf8'));
+  assert.equal(report.ok, true);
+  assert.equal(report.qualityOk, false);
+  assert.ok(Array.isArray(report.attempts));
+  // img2img 降级 = 复制原图（字节一致）
+  const enh = await readFile(join(assets, 'enhanced_src_1.jpg'));
+  const src = await readFile(join(assets, 'src_1.png'));
+  assert.ok(enh.equals(src), 'img2img 降级应复制原图');
+  // 文生图降级 = 合法 PNG（魔数 89 50 4E 47）
+  const grad = await readFile(join(assets, 'img_1.png'));
+  assert.ok(
+    grad.length > 50 && grad[0] === 0x89 && grad[1] === 0x50 && grad[2] === 0x4e && grad[3] === 0x47,
+    '文生图降级应为合法渐变 PNG',
+  );
+});
+
+// 重试模式：只取上一次 report 里的 degraded 文件，避免整批图反复生成。
+await withTmp(async (dir) => {
+  const assets = join(dir, 'assets');
+  const plan = join(dir, 'img_plan.json');
+  const report = join(dir, 'image_generation_report.json');
+  await mkdir(assets, { recursive: true });
+  await writeFile(
+    plan,
+    JSON.stringify([
+      { file: 'ok.png', mode: 'text-to-image', aspect: '16:9', prompt: 'already generated' },
+      { file: 'bad.png', mode: 'text-to-image', aspect: '16:9', prompt: 'retry this one' },
+    ]),
+  );
+  await writeFile(report, JSON.stringify({ degraded: [{ file: 'bad.png', fallback: 'gradient-png' }] }));
+
+  const res = run(['--plan', plan, '--assets', assets, '--retry-degraded-report', report, '--dry-run']);
+  assert.equal(res.status, 0, res.stderr);
+  const items = jsonLines(res.stdout);
+  assert.equal(items.length, 1);
+  assert.equal(items[0].file, 'bad.png');
+});
+
+// 结构/安全校验失败（malformed plan）仍 hardError exit 1（与生成失败区分，计划 bug 要暴露）。
+await withTmp(async (dir) => {
+  const assets = join(dir, 'assets');
+  const plan = join(dir, 'img_plan.json');
+  await mkdir(assets, { recursive: true });
+  await writeFile(plan, JSON.stringify([{ file: '../escape.png', mode: 'text-to-image', prompt: 'z' }]));
+  const res = spawnSync(process.execPath, [script, '--plan', plan, '--assets', assets, '--dry-run'], { encoding: 'utf8' });
+  assert.notEqual(res.status, 0, '路径越界是结构/安全错误，应 hardError exit 1');
+  assert.match(res.stderr, /不能跳出 assets 目录/);
+});
+
+console.log('generate_from_plan_test PASSED');