promptfigure 0.2.0

package/src/next.mjs

@@ -0,0 +1,125 @@
+// next.mjs — 🔴 状态路由器（2026-09-21 用户反馈"别人的 AI 根本不会用"）：
+// 冷启动 AI 面对几十条命令不知道下一步。本模块只做一件事：
+//   读项目当前状态 → 输出**唯一**一条可直接复制执行的下一步命令 + 为什么。
+// 所有歧义在这里消解：AI 不需要理解工作流，只要反复 `pf next` → 执行 → 再 `pf next`。
+//
+// 设计原则：
+//   - 命令必须是完整可执行的（占位符用 <尖括号> 明确标出要 AI 自己填的内容）
+//   - 优先级：精修 > 待审批 > 驳回 > 定稿缺失 > 新图 > 读文选位
+//   - 纯函数：CLI 与 cold-start-sim 共用同一份判断，插件改状态这里必须跟着改
+
+import fs from "node:fs";
+
+// 审批状态取本地图（daemon 挂了导航也不能挂）
+function reviewMap(docId, readReview) {
+  try { return readReview(docId) || {}; } catch { return {}; }
+}
+
+// 🔴 活跃修正 vs 最新 sidecar 对账（2026-09-21 子智能体实测发现的死路出口）：
+// AI 按 refine 重拼命令跑过 craft --fixes 后，若在等授权/沙盒（没有真渲染推进状态），
+// pf next 必须认出"修正已全部进入最新提示词"，指去 render 而不是永远卡在 refine。
+function sidecarCoversFixes(fig, fixes = []) {
+  try {
+    const scPath = fig?.versions?.at(-1)?.sidecar;
+    if (!scPath || !fs.existsSync(scPath)) return false;
+    const sc = JSON.parse(fs.readFileSync(scPath, "utf8"));
+    const norm = (s) => String(s || "").toLowerCase().replace(/\s+/g, " ").trim();
+    const scSet = String(sc.fixes || "").split(/[;；]/).map(norm).filter(Boolean);
+    if (!scSet.length) return false;
+    return (fixes || []).every((f) => {
+      const n = norm(f);
+      return scSet.includes(n) || scSet.some((s) => s && (s.includes(n) || n.includes(s)));
+    });
+  } catch { return false; }
+}
+
+// 单图阶段判定（2026-09-21 多图路由重构）：返回 {stage,cmd,why} 或 null（已定稿）。
+// 顺序：精修 > ready（对账出口）> 待核验 > 驳回 > 定稿缺失。
+export function figureNext(fig, rev = {}) {
+  const fid = fig.figureId;
+  const st = (rev[fid] || {}).status || "pending";
+
+  if ((fig.activeFixes || []).length > 0) {
+    if (sidecarCoversFixes(fig, fig.activeFixes)) {
+      return {
+        stage: "ready",
+        cmd: `pf render --at "${fig.at || "<原文位置>"}" --model standard --prompt-file <刚 craft --out 的文件名>.txt`,
+        why: `修正已全部写进最新提示词（对账 ${fig.activeFixes.length} 条 ✓）——直接渲染；真实渲染后新版本会自动清核验记录并重置审批（沙盒/排练用 --dry-run，但闭环要真图才能走完）`,
+      };
+    }
+    return {
+      stage: "refine",
+      cmd: `pf refine ${fid}`,
+      why: `图 ${fid} 有 ${fig.activeFixes.length} 条未消化修正——refine 会列出它们并自动重拼下一轮 craft 命令`,
+    };
+  }
+  if (st === "pending") {
+    return {
+      stage: "review",
+      cmd: `pf qa ${fid}`,
+      why: `图 ${fid} 等待核验——pf qa 输出任务包（体检数字+实体清单+核验清单），亲眼读图逐条核验后写回：pf qa ${fid} --pass --note "依据"（通过并写回审批）或 pf qa ${fid} --fail --note "缺陷1; 缺陷2"（驳回+缺陷自动进精修状态机）`,
+    };
+  }
+  if (st === "rejected") {
+    return {
+      stage: "fix",
+      cmd: `pf inspect ${fid} && pf qa-list ${fid}`,
+      why: `图 ${fid} 被驳回——先看自动体检数字（留白/白度/彩色占比），再用你的看图能力过核验清单；发现的缺陷用 pf refine ${fid} --fix "缺陷" 记入状态机`,
+    };
+  }
+  const last = fig.versions?.at(-1);
+  if (st === "approved" && last && last.model !== "premium") {
+    return {
+      stage: "finalize",
+      cmd: `pf prompt ${fid} --out <名字>.txt`,
+      why: `图 ${fid} 已通过还是草稿——pf prompt 把定稿提示词导出成文件，然后 pf render --at "<原文位置>" --model premium --prompt-file <名字>.txt 出定稿`,
+    };
+  }
+  return null; // approved + premium = 完工
+}
+
+export function computeNext({ docId = null, meta = null, cfg = {} } = {}, io = {}) {
+  const readReview = io.readReview;
+  const rev = docId && readReview ? reviewMap(docId, readReview) : {};
+
+  // ---- 0) 没配 key：一切免谈 ----
+  if (!cfg.key) {
+    return { stage: "login", cmd: "pf login", why: "还没配置 API key——先去控制台创建 pf_ 开头的 key，再跑 pf login <key>" };
+  }
+  // ---- 1) 没打开文档 ----
+  if (!docId || !meta) {
+    return { stage: "open", cmd: "pf open <论文路径.docx|.tex|.pdf>", why: "还没打开论文。open 会打印 docId 并自动打开预览窗口，之后的命令都要用到 docId" };
+  }
+
+  const figures = Object.values(meta.figures || {});
+  // 🔴 多图路由（2026-09-21 子智能体 E 实测：批量配图时 next 只盯"最新一张"，其他图做完
+  // craft/dry-run 它毫无感知）。改为按创建序轮询：第一张没完工的图就是下一步。
+  const ordered = figures.slice().sort((a, b) => (a.versions?.[0]?.at || "").localeCompare(b.versions?.[0]?.at || ""));
+
+  for (const fig of ordered) {
+    const r = figureNext(fig, rev);
+    if (r) return r;
+  }
+  if (ordered.length > 0) {
+    return {
+      stage: "done",
+      cmd: `pf doc figures`,
+      why: `全部 ${ordered.length} 张图已定稿 ✅——对照论文原图清单挑下一张要重画的；全部完成则收工`,
+    };
+  }
+
+  // ---- 3) 没图：读文 → 选位 → craft ----
+  const anchors = io.readAnchors ? (io.readAnchors(docId) || []) : [];
+  if (anchors.length === 0) {
+    return {
+      stage: "context",
+      cmd: `pf doc outline ${docId}  →  pf distill --at "<章节 段号>"`,
+      why: "还没选定配图位置——先 outline 看章节树（找特定内容用 pf doc search <关键词>；找数值用 pf doc data），再 distill 从原文抽实体/阶段素材（禁止跳过读原文直接编内容）",
+    };
+  }
+  return {
+    stage: "craft",
+    cmd: `pf craft --at "<章节 段号>" --intent "<图意，来自刚才读的原文>" --entities "<实体逗号分隔>" --stages "<标题 | show 画法 || …>" --figure-type <类型> --out <名字>.txt`,
+    why: "位置已定——craft 必带 --at（实体溯源会拿回原文对账，缺了直接拒绝）；质量分 <60 也会被拒绝；--out 会写伴随 JSON，render 自动继承画布比",
+  };
+}

package/src/plan.mjs

@@ -0,0 +1,112 @@
+// plan.mjs — 🔴 小白对齐器（2026-09-22 用户反馈"数模小白在 Codex/Z Code 里用不出好效果"）：
+// 前几轮把"门"焊死了（质量门/溯源/QA/审批），但小白用户的另一半问题在"门"之前——
+// 用户自己说不清要什么图，弱 AI 不问就闷头编：编实体（被溯源拒绝）或编完直接 render（钱白烧）。
+// plan 做一件事：把插件当前状态翻译成【发给用户的大白话问题卡】+【AI 拿到答复后的执行步骤】，
+// 问题卡里的选项全部来自真实文档（章节编号、候选图型），小白回个数字就能推进。
+// 纯函数：CLI 与测试共用。
+import { computeNext } from "./next.mjs";
+
+// 图型中文名（给小白看的人话，CLI 与 distill 确认卡共用）
+export function figureTypeBrief(ft = "") {
+  const M = {
+    pipeline: "流程图", flowchart: "判断流程图", architecture: "结构/架构图", mechanism: "机理/因果图",
+    comparison: "对比图", dataflow: "数据流图", hierarchy: "层级/组成图", timeline: "时间线",
+    teaser: "核心一图流", zoomin: "局部放大图", scene: "场景示意图", "result-style": "结果风格图",
+    "multi-panel": "多面板组合图",
+  };
+  return M[String(ft || "").trim()] || "示意图";
+}
+
+// goal 关键词 → 图型建议（确定性路由，弱 AI 不用自己猜"画什么图"）
+export function suggestFigureType(goal = "") {
+  const g = String(goal || "").toLowerCase();
+  if (/数据|结果|准确率|精度|提升|误差|灵敏度|收敛|对比实验|numerical|result/.test(g)) return { type: "result-style", note: "data" };
+  if (/机理|因果|促进|抑制|影响|作用|为什么|mechanism/.test(g)) return { type: "mechanism" };
+  if (/对比|比较|优缺点|before|after|改进|vs/.test(g)) return { type: "comparison" };
+  if (/组合|多面板|panel|分图|消融/.test(g)) return { type: "multi-panel" };
+  if (/组成|包含|分类|层级|体系|hierarchy/.test(g)) return { type: "hierarchy" };
+  if (/发展|历史|时间|演进|timeline/.test(g)) return { type: "timeline" };
+  if (/结构|架构|组成模块|architecture|framework/.test(g)) return { type: "architecture" };
+  if (/流程|步骤|pipeline|过程|算法流程/.test(g)) return { type: "pipeline" };
+  if (/核心|摘要|一图|teaser|概述/.test(g)) return { type: "teaser" };
+  return null;
+}
+
+// 真实章节选项（heading 块 → 编号清单；小白回数字，AI 按编号映射回 §路径）
+export function sectionOptions(blocks = [], { limit = 10 } = {}) {
+  const heads = blocks.filter((b) => b.type === "heading" && String(b.secPath || "") !== "0");
+  return heads.slice(0, limit).map((b, i) => ({ n: i + 1, at: `§${b.secPath}`, title: String(b.text || "").slice(0, 30) }));
+}
+
+export function buildPlan({ docId = null, meta = null, cfg = {}, goal = "" } = {}, io = {}) {
+  const userLines = [];
+  const steps = [];
+
+  // ---- 0) 没配 key ----
+  if (!cfg.key) {
+    userLines.push("开始出图前需要配置一次 promptFigure 的 API key（控制台 promptfigure.top 注册后创建，pf_ 开头）。");
+    userLines.push("把 key 发给我，或者自己去控制台建好告诉我一声。");
+    steps.push({ cmd: "pf login <pf_ 开头的 key>", why: "配置 key——之后所有出图计费都走它" });
+    steps.push({ cmd: "pf plan", why: "配好后重新跑计划，进入下一步" });
+    return { stage: "login", userLines, steps };
+  }
+
+  // ---- 1) 没打开文档 ----
+  if (!docId || !meta) {
+    userLines.push("请把论文文件发给我（支持 Word .docx / PDF / LaTeX .tex）。");
+    userLines.push("如果你手上是 .doc/.wps 老格式，先在 Word/WPS 里另存为 .docx。");
+    steps.push({ cmd: "pf open <论文文件路径>", why: "打开论文并打印 docId，之后的操作都自动作用于它" });
+    steps.push({ cmd: "pf plan", why: "打开后重新跑计划：我会列出真实章节让你挑配图位置" });
+    return { stage: "open", userLines, steps };
+  }
+
+  const blocks = meta.blocks || [];
+  const figures = Object.values(meta.figures || {});
+
+  // ---- 2) 已有图：报进度 + 路由下一步 ----
+  if (figures.length > 0) {
+    const r = computeNext({ docId, meta, cfg }, io);
+    const doneN = figures.filter((f) => {
+      const st = ((io.readReview?.(docId) || {})[f.figureId] || {}).status;
+      return st === "approved" && f.versions?.at(-1)?.model === "premium";
+    }).length;
+    userLines.push(`你的论文我正在配图：目前共 ${figures.length} 张，定稿 ${doneN} 张。`);
+    if (goal) {
+      const s = suggestFigureType(goal);
+      userLines.push(`你说的"${goal}"我记下了，会按${s ? figureTypeBrief(s.type) : "示意图"}来处理。`);
+    }
+    userLines.push("接下来这一步不需要你操作，我处理完会把图给你看。");
+    steps.push({ cmd: r.cmd, why: r.why });
+    steps.push({ cmd: "pf plan", why: "每做完一步重新跑计划，进度和下一步会跟着更新" });
+    return { stage: r.stage, userLines, steps };
+  }
+
+  // ---- 3) 还没图：真实章节选项 + 需求三问 ----
+  // 🔴 判断层归 AI（2026-09-22 去写死）：下面的问题卡与图型建议只是底稿——
+  // 关键词路由覆盖不到的语言/说法，AI 必须自己用 pf types 的选型决策来判断图型；
+  // 问题卡要用用户的语言转述（多语言用户的用户卡不是中文）。
+  const opts = sectionOptions(blocks);
+  const s = suggestFigureType(goal);
+  userLines.push("[向用户转述时用用户的语言，下面只是底稿]");
+  userLines.push("给论文配图前，先确认三件事（直接回复，不用专业术语）：");
+  userLines.push("① 图配在哪个部分？回复编号即可（0=说不清/整篇都行，我读全文后挑最值得画的部分给你确认）：" + (opts.length
+    ? opts.map((o) => `${o.n}=${o.title}`).join("；") + "。"
+    : "（没读到章节标题——把大概位置告诉我，比如\"第三章那一段\"）"));
+  userLines.push("② 这张图最想让读者记住什么？一句话就行。");
+  userLines.push("③ 图里必须出现的名字/术语有哪些？说不清就跳过，我会从原文里提取给你确认。");
+  if (s) {
+    userLines.push(`（插件按关键词猜了「${figureTypeBrief(s.type)}」——只是参考，你读原文后用 pf types 的选型决策自己定图型，猜测可以推翻）`);
+  }
+  if (s?.note === "data") {
+    userLines.push("⚠️ 你要的是数据结果图：精确数值的柱/线/热图我不会用 AI 重画（数字必错），我会先看你的绘图脚本，引导改样式；纯示意图才走 AI 出图。");
+  }
+  // 价格口径唯一来源（2026-09-22 子智能体实测：AI 自己报价报错——草稿说成 0.15）：
+  // 问题卡直接带上真实价格，AI 照抄即可
+  userLines.push("费用参考：草稿约 $0.02/张（可反复调），定稿约 $0.15/张（确认满意后才出）；先出草稿给你看。");
+  steps.push({ cmd: `pf distill --at "<用户选中的章节 §路径>"`, why: "从原文抽候选实体/阶段句/数据句（任何语言都支持），产出用户确认卡；候选是统计性的，逐个核对原文出处；用户回 0 = 你用 pf doc outline + pf doc data 自己挑最值得画的章节，挑完仍要走确认卡" });
+  steps.push({ cmd: "（把确认卡发给用户，等确认）", why: "渲染要花钱，先让用户确认要素和顺序" });
+  steps.push({ cmd: `pf craft --at "<章节>" --figure-type <你定的图型，pf types 查选型> … --out <名字>.txt`, why: "按确认过的素材拼合规提示词；质量门会挡空泛输入" });
+  steps.push({ cmd: `pf render --at "<章节>" --model standard --prompt-file <名字>.txt`, why: "standard 草稿先出图（~$0.02），premium 定稿要等审批通过" });
+  steps.push({ cmd: "pf plan", why: "图出来后计划会路由到核验（pf qa）环节" });
+  return { stage: "interview", userLines, steps };
+}

package/src/png-trim.mjs

@@ -0,0 +1,217 @@
+// png-trim.mjs — 白边自动裁剪（零依赖，Node 内置 zlib）
+//
+// 🔴 2026-09-21 V14 复盘：画布句命令"内容带撑满画布高度"premium 也不听（惯性构图，
+// 内容带仍只占 ~46% 高度，上下空白 >50%）。措辞路线到头了 —— 留白改由**确定性后处理保证**：
+// 解码 PNG → 扫描非白像素求内容包围盒 → 留白面积超阈值就裁到 bbox+窄边距 → 重编码回写。
+// 任何一步异常都保留原图跳过（宁可多留白，不可损坏图）。
+//
+// 适用：color type 2 (RGB) / 6 (RGBA)，bit depth 8，非隔行 —— premium/standard 产出均如此。
+
+import zlib from "node:zlib";
+
+const CHUNK_TYPE = (buf, off) => buf.toString("ascii", off, off + 4);
+
+// ---------- 解码（8-bit RGB/RGBA 非隔行）----------
+export function decodePng(buf) {
+  if (buf.readUInt32BE(0) !== 0x89504e47) throw new Error("not a PNG");
+  let off = 8;
+  let width = 0, height = 0, bitDepth = 0, colorType = 0, interlace = 0;
+  const idat = [];
+  while (off < buf.length) {
+    const len = buf.readUInt32BE(off);
+    const type = CHUNK_TYPE(buf, off + 4);
+    const data = buf.subarray(off + 8, off + 8 + len);
+    if (type === "IHDR") {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      bitDepth = data[8];
+      colorType = data[9];
+      interlace = data[12];
+    } else if (type === "IDAT") {
+      idat.push(data);
+    } else if (type === "IEND") break;
+    off += 12 + len;
+  }
+  if (bitDepth !== 8 || (colorType !== 2 && colorType !== 6) || interlace !== 0) {
+    throw new Error(`unsupported PNG: depth=${bitDepth} color=${colorType} interlace=${interlace}`);
+  }
+  const ch = colorType === 6 ? 4 : 3;
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const stride = width * ch;
+  const out = Buffer.alloc(width * height * ch);
+  // 反滤波（None/Sub/Up/Average/Paeth）
+  let prev = Buffer.alloc(stride);
+  for (let y = 0; y < height; y++) {
+    const f = raw[y * (stride + 1)];
+    const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+    const cur = out.subarray(y * stride, (y + 1) * stride);
+    for (let x = 0; x < stride; x++) {
+      const a = x >= ch ? cur[x - ch] : 0;
+      const b = prev[x];
+      const c = x >= ch ? prev[x - ch] : 0;
+      let v = line[x];
+      if (f === 1) v += a;
+      else if (f === 2) v += b;
+      else if (f === 3) v += (a + b) >> 1;
+      else if (f === 4) {
+        const p = a + b - c;
+        const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+        v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+      }
+      cur[x] = v & 0xff;
+    }
+    prev = cur;
+  }
+  return { width, height, ch, pixels: out };
+}
+
+// ---------- 内容包围盒（非白 = 任一色通道 <250；透明也算内容外？不——全白背景不透明）----------
+export function contentBbox({ width, height, ch, pixels }) {
+  let top = height, bottom = -1, left = width, right = -1;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const i = (y * width + x) * ch;
+      const nonWhite = pixels[i] < 250 || pixels[i + 1] < 250 || pixels[i + 2] < 250;
+      if (nonWhite) {
+        if (y < top) top = y;
+        if (y > bottom) bottom = y;
+        if (x < left) left = x;
+        if (x > right) right = x;
+      }
+    }
+  }
+  if (bottom < 0) return null;
+  return { top, bottom, left, right };
+}
+
+// ---------- 编码（filter 0 每行，RGB 输出）----------
+export function encodePng({ width, height, ch, pixels }) {
+  const stride = width * 3;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 0; // filter None
+    for (let x = 0; x < width; x++) {
+      const si = (y * width + x) * ch;
+      const di = y * (stride + 1) + 1 + x * 3;
+      raw[di] = pixels[si];
+      raw[di + 1] = pixels[si + 1];
+      raw[di + 2] = pixels[si + 2];
+    }
+  }
+  const crcTable = (() => {
+    const t = new Int32Array(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;
+    }
+    return t;
+  })();
+  const crc32 = (b) => {
+    let c = 0xffffffff;
+    for (const v of b) c = crcTable[(c ^ v) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  };
+  const chunk = (type, data) => {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(data.length, 0);
+    head.write(type, 4, "ascii");
+    const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(body), 0);
+    return Buffer.concat([head, data, crc]);
+  };
+  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;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", zlib.deflateSync(raw, { level: 6 })),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+// ---------- 量化体检（2026-09-21 定规：核验数字由插件算，AI 只做语义判断）----------
+// 留白占比 / 边缘带白度（纸张斑纹高发区）/ 彩色像素占比（黑白线稿风回归检测）
+export function pngStats(buf, { step = 4 } = {}) {
+  try {
+    const img = decodePng(buf);
+    const bbox = contentBbox(img);
+    if (!bbox) return null;
+    const cw = bbox.right - bbox.left + 1;
+    const chh = bbox.bottom - bbox.top + 1;
+    const wastePct = Number((100 * (1 - (cw * chh) / (img.width * img.height))).toFixed(1));
+
+    // 边缘带（外圈 1.5%）白度：背景不是纯白（纸张纹理/斑驳底）在这里最明显
+    const band = Math.max(4, Math.round(Math.min(img.width, img.height) * 0.015));
+    let edgeTotal = 0, edgeWhite = 0;
+    const isWhite = (i) => img.pixels[i] >= 248 && img.pixels[i + 1] >= 248 && img.pixels[i + 2] >= 248;
+    for (let y = 0; y < img.height; y += 2) {
+      for (let x = 0; x < img.width; x += 2) {
+        const inBand = x < band || x >= img.width - band || y < band || y >= img.height - band;
+        if (!inBand) continue;
+        edgeTotal++;
+        if (isWhite((y * img.width + x) * img.ch)) edgeWhite++;
+      }
+    }
+
+    // 彩色像素占比（下采样）：饱和度 max-min>32 视为彩色。黑白线稿风的图显著偏低
+    let total = 0, sat = 0;
+    for (let y = 0; y < img.height; y += step) {
+      for (let x = 0; x < img.width; x += step) {
+        const i = (y * img.width + x) * img.ch;
+        total++;
+        const mx = Math.max(img.pixels[i], img.pixels[i + 1], img.pixels[i + 2]);
+        const mn = Math.min(img.pixels[i], img.pixels[i + 1], img.pixels[i + 2]);
+        if (mx - mn > 32) sat++;
+      }
+    }
+    return {
+      w: img.width, h: img.height,
+      wastePct,
+      edgeWhitePct: Number((100 * edgeWhite / Math.max(1, edgeTotal)).toFixed(1)),
+      satPct: Number((100 * sat / Math.max(1, total)).toFixed(1)),
+    };
+  } catch {
+    return null;
+  }
+}
+// ---------- 裁剪主入口：留白面积占比 >maxWaste 才裁，边距留 ratio（占裁后短边比）----------
+// 返回 { buf, from:{w,h}, to:{w,h}, savedPct } 或 null（不值得裁/出错）
+export function trimWhitespace(pngBuf, { maxWaste = 0.3, marginRatio = 0.03 } = {}) {
+  try {
+    const img = decodePng(pngBuf);
+    const bbox = contentBbox(img);
+    if (!bbox) return null;
+    const cw = bbox.right - bbox.left + 1;
+    const chh = bbox.bottom - bbox.top + 1;
+    const waste = 1 - (cw * chh) / (img.width * img.height);
+    if (waste <= maxWaste) return null;
+    const margin = Math.max(8, Math.round(Math.min(cw, chh) * marginRatio));
+    const left = Math.max(0, bbox.left - margin);
+    const top = Math.max(0, bbox.top - margin);
+    const right = Math.min(img.width - 1, bbox.right + margin);
+    const bottom = Math.min(img.height - 1, bbox.bottom + margin);
+    const w2 = right - left + 1;
+    const h2 = bottom - top + 1;
+    const cropped = Buffer.alloc(w2 * h2 * img.ch);
+    for (let y = 0; y < h2; y++) {
+      img.pixels.copy(
+        cropped,
+        y * w2 * img.ch,
+        ((top + y) * img.width + left) * img.ch,
+        ((top + y) * img.width + right + 1) * img.ch
+      );
+    }
+    return {
+      buf: encodePng({ width: w2, height: h2, ch: img.ch, pixels: cropped }),
+      from: { w: img.width, h: img.height },
+      to: { w: w2, h: h2 },
+      savedPct: Number((100 * (1 - (w2 * h2) / (img.width * img.height))).toFixed(1)),
+    };
+  } catch {
+    return null; // 任何异常：保留原图
+  }
+}