dsh-plugin-deck-studio 0.0.0-stage → 0.2.2

package/lib/png.js

@@ -0,0 +1,275 @@
+/**
+ * 最小 PNG 编解码 + 缩放 + 叠加（F-125 水印用）。
+ *
+ * 为什么自己写：插件对外承诺「零第三方依赖」，而出图产物是 PNG（real renderer 写
+ * image.png）。水印只需要：读 PNG → 解码成 RGBA → 把 logo 缩放到目标尺寸 → alpha 叠加
+ * → 再编码回 PNG。用 node 内置 zlib 足够，不引 sharp / canvas。
+ *
+ * 支持范围（够用且明确报错，不静默出错）：
+ * - 解码：8 bit、非隔行；colorType 0/2/3/4/6（灰度 / RGB / 调色板 / 灰度+alpha / RGBA），
+ *   调色板带 tRNS 透明度；不支持 16 bit / Adam7 / APNG。
+ * - 编码：RGBA（colorType 6）+ filter 0。
+ *
+ * @module dsh-plugin-deck-studio/png
+ */
+
+import { deflateSync, inflateSync } from "node:zlib";
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buffer) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buffer.length; i += 1) c = CRC_TABLE[(c ^ buffer[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type, data) {
+  const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+  const out = Buffer.alloc(body.length + 8);
+  out.writeUInt32BE(data.length, 0);
+  body.copy(out, 4);
+  out.writeUInt32BE(crc32(body), body.length + 4);
+  return out;
+}
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}
+
+/**
+ * 解码 PNG → { width, height, data: Uint8Array RGBA }。
+ * 不认识的就抛错（调用方决定是否跳过该页），不返回半成品。
+ */
+export function decodePng(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 8 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
+    throw new Error("不是 PNG 文件");
+  }
+  let offset = 8;
+  let header = null;
+  let palette = null;
+  let transparency = null;
+  const idat = [];
+  while (offset + 8 <= buffer.length) {
+    const length = buffer.readUInt32BE(offset);
+    const type = buffer.toString("ascii", offset + 4, offset + 8);
+    const data = buffer.subarray(offset + 8, offset + 8 + length);
+    offset += 12 + length;
+    if (type === "IHDR") {
+      header = {
+        width: data.readUInt32BE(0),
+        height: data.readUInt32BE(4),
+        bitDepth: data[8],
+        colorType: data[9],
+        compression: data[10],
+        filter: data[11],
+        interlace: data[12],
+      };
+    } else if (type === "PLTE") {
+      palette = data;
+    } else if (type === "tRNS") {
+      transparency = data;
+    } else if (type === "IDAT") {
+      idat.push(data);
+    } else if (type === "IEND") {
+      break;
+    }
+  }
+  if (!header) throw new Error("PNG 缺 IHDR");
+  if (header.bitDepth !== 8) throw new Error(`暂不支持 ${header.bitDepth} bit PNG（水印需要 8 bit）`);
+  if (header.interlace !== 0) throw new Error("暂不支持隔行（Adam7）PNG");
+  if (header.compression !== 0 || header.filter !== 0) throw new Error("PNG 压缩 / 过滤方式不支持");
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[header.colorType];
+  if (!channels) throw new Error(`暂不支持 PNG colorType=${header.colorType}`);
+  const raw = inflateSync(Buffer.concat(idat));
+  const { width, height } = header;
+  const bpp = channels;
+  const rowBytes = width * bpp;
+  const stride = rowBytes + 1;
+  if (raw.length < stride * height) throw new Error("PNG 像素数据不完整");
+  const pixels = new Uint8Array(width * height * 4);
+  const prev = new Uint8Array(rowBytes);
+  const line = new Uint8Array(rowBytes);
+  const paletteEntries = palette
+    ? Array.from({ length: Math.floor(palette.length / 3) }, (_, index) => [palette[index * 3], palette[index * 3 + 1], palette[index * 3 + 2], transparency?.[index] ?? 255])
+    : null;
+
+  for (let y = 0; y < height; y += 1) {
+    const filter = raw[y * stride];
+    const srcRow = raw.subarray(y * stride + 1, y * stride + 1 + rowBytes);
+    for (let x = 0; x < rowBytes; x += 1) {
+      const left = x >= bpp ? line[x - bpp] : 0;
+      const up = prev[x];
+      const upLeft = x >= bpp ? prev[x - bpp] : 0;
+      let value = srcRow[x];
+      if (filter === 1) value += left;
+      else if (filter === 2) value += up;
+      else if (filter === 3) value += Math.floor((left + up) / 2);
+      else if (filter === 4) value += paeth(left, up, upLeft);
+      else if (filter !== 0) throw new Error(`PNG 行过滤类型不支持：${filter}`);
+      line[x] = value & 0xff;
+    }
+    for (let x = 0; x < width; x += 1) {
+      const target = (y * width + x) * 4;
+      const index = x * bpp;
+      if (header.colorType === 6) {
+        pixels[target] = line[index];
+        pixels[target + 1] = line[index + 1];
+        pixels[target + 2] = line[index + 2];
+        pixels[target + 3] = line[index + 3];
+      } else if (header.colorType === 2) {
+        pixels[target] = line[index];
+        pixels[target + 1] = line[index + 1];
+        pixels[target + 2] = line[index + 2];
+        pixels[target + 3] = 255;
+      } else if (header.colorType === 0) {
+        pixels[target] = pixels[target + 1] = pixels[target + 2] = line[index];
+        pixels[target + 3] = 255;
+      } else if (header.colorType === 4) {
+        pixels[target] = pixels[target + 1] = pixels[target + 2] = line[index];
+        pixels[target + 3] = line[index + 1];
+      } else if (header.colorType === 3) {
+        if (!paletteEntries) throw new Error("调色板 PNG 缺 PLTE");
+        const entry = paletteEntries[line[index]] ?? [0, 0, 0, 255];
+        pixels[target] = entry[0];
+        pixels[target + 1] = entry[1];
+        pixels[target + 2] = entry[2];
+        pixels[target + 3] = entry[3];
+      }
+    }
+    prev.set(line);
+  }
+  return { width, height, data: pixels };
+}
+
+/** 编码 RGBA（Uint8Array/Uint8ClampedArray）→ PNG Buffer。 */
+export function encodePng({ width, height, data }) {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) throw new Error("PNG 尺寸非法");
+  if (data.length !== width * height * 4) throw new Error("RGBA 数据长度与尺寸不匹配");
+  const stride = width * 4;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y += 1) {
+    raw[y * (stride + 1)] = 0; // filter 0
+    Buffer.from(data.buffer, data.byteOffset + y * stride, stride).copy(raw, y * (stride + 1) + 1);
+  }
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header[8] = 8; // bitDepth
+  header[9] = 6; // RGBA
+  header[10] = 0;
+  header[11] = 0;
+  header[12] = 0;
+  return Buffer.concat([
+    PNG_SIGNATURE,
+    chunk("IHDR", header),
+    chunk("IDAT", deflateSync(raw, { level: 9 })),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+/**
+ * 面积平均缩放（预乘 alpha，避免透明边缘发黑）。
+ * 放大用双线性近似（直接按最近邻会更脆；面积法放大同样可用）。
+ */
+export function resizeRgba(image, targetWidth, targetHeight) {
+  const { width, height, data } = image;
+  if (targetWidth === width && targetHeight === height) return { width, height, data: Uint8Array.from(data) };
+  const out = new Uint8Array(targetWidth * targetHeight * 4);
+  const scaleX = width / targetWidth;
+  const scaleY = height / targetHeight;
+  for (let y = 0; y < targetHeight; y += 1) {
+    const y0 = Math.floor(y * scaleY);
+    const y1 = Math.max(y0 + 1, Math.min(height, Math.ceil((y + 1) * scaleY)));
+    for (let x = 0; x < targetWidth; x += 1) {
+      const x0 = Math.floor(x * scaleX);
+      const x1 = Math.max(x0 + 1, Math.min(width, Math.ceil((x + 1) * scaleX)));
+      let r = 0;
+      let g = 0;
+      let b = 0;
+      let a = 0;
+      let count = 0;
+      for (let sy = y0; sy < y1; sy += 1) {
+        for (let sx = x0; sx < x1; sx += 1) {
+          const index = (sy * width + sx) * 4;
+          const alpha = data[index + 3] / 255;
+          r += data[index] * alpha;
+          g += data[index + 1] * alpha;
+          b += data[index + 2] * alpha;
+          a += alpha;
+          count += 1;
+        }
+      }
+      const target = (y * targetWidth + x) * 4;
+      if (a > 0) {
+        out[target] = Math.round(r / a);
+        out[target + 1] = Math.round(g / a);
+        out[target + 2] = Math.round(b / a);
+      }
+      out[target + 3] = Math.round((a / count) * 255);
+    }
+  }
+  return { width: targetWidth, height: targetHeight, data: out };
+}
+
+/**
+ * 把 logo 叠加到页面图上（原地生成新 buffer）。
+ * position：top-right / top-left / bottom-right / bottom-left / center；margin/scale 都是页面宽度的比例。
+ */
+export function compositeLogo({ page, logo, position = "top-right", opacity = 0.85, scale = 0.14, margin = 0.04 }) {
+  const pageWidth = page.width;
+  const pageHeight = page.height;
+  const logoWidth = Math.max(8, Math.round(pageWidth * Math.min(Math.max(scale, 0.02), 0.5)));
+  const logoHeight = Math.max(4, Math.round((logo.height / logo.width) * logoWidth));
+  const scaled = resizeRgba(logo, logoWidth, logoHeight);
+  const gap = Math.round(pageWidth * Math.min(Math.max(margin, 0), 0.2));
+  const positions = {
+    "top-right": [pageWidth - logoWidth - gap, gap],
+    "top-left": [gap, gap],
+    "bottom-right": [pageWidth - logoWidth - gap, pageHeight - logoHeight - gap],
+    "bottom-left": [gap, pageHeight - logoHeight - gap],
+    center: [Math.round((pageWidth - logoWidth) / 2), Math.round((pageHeight - logoHeight) / 2)],
+  };
+  const [originX, originY] = positions[position] ?? positions["top-right"];
+  const alphaScale = Math.min(Math.max(Number(opacity) || 0, 0), 1);
+  const out = Uint8Array.from(page.data);
+  for (let y = 0; y < logoHeight; y += 1) {
+    const pageY = originY + y;
+    if (pageY < 0 || pageY >= pageHeight) continue;
+    for (let x = 0; x < logoWidth; x += 1) {
+      const pageX = originX + x;
+      if (pageX < 0 || pageX >= pageWidth) continue;
+      const src = (y * logoWidth + x) * 4;
+      const srcAlpha = (scaled.data[src + 3] / 255) * alphaScale;
+      if (srcAlpha <= 0) continue;
+      const dst = (pageY * pageWidth + pageX) * 4;
+      out[dst] = Math.round(scaled.data[src] * srcAlpha + out[dst] * (1 - srcAlpha));
+      out[dst + 1] = Math.round(scaled.data[src + 1] * srcAlpha + out[dst + 1] * (1 - srcAlpha));
+      out[dst + 2] = Math.round(scaled.data[src + 2] * srcAlpha + out[dst + 2] * (1 - srcAlpha));
+      out[dst + 3] = 255;
+    }
+  }
+  return {
+    image: { width: pageWidth, height: pageHeight, data: out },
+    placement: { position, originX, originY, logoWidth, logoHeight, opacity: alphaScale, scale },
+  };
+}
+
+/** 读一张 PNG 文件 → 解码后的图（调用方自己兜异常）。 */
+export function readPng(buffer) {
+  return decodePng(buffer);
+}

package/lib/proposal-decision.js

@@ -0,0 +1,204 @@
+/**
+ * 提案裁决（F-108）：把「用户确认/驳回提案」的逻辑从工具里抽出来，
+ * 让 Agent 的 deck_revision_confirm 与工作台按钮（POST /api/deck-studio.proposal-decide）
+ * 走同一条写入路径——不会出现「UI 确认了但 revision/源文件没写」的两套账。
+ *
+ * 写入纪律不变：只追加 revision（copy-on-write），本机 deck 回写源 script.md，
+ * 受控客户源只读；每一步都留 `deck.edit` 事件与 task 状态。
+ *
+ * @module dsh-plugin-deck-studio/proposal-decision
+ */
+
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { SCRIPT_FIELD_CELL, proposalNow, scriptSectionRange } from "./deck-workspace.js";
+import { commitFiles } from "./git-commit.js";
+
+/**
+ * 本机新建 deck：确认后的脚本内容回写源 script.md + git 留痕（F-100 / ADR-0022）。
+ * 受控客户源（isLocalDeck=false）仍然只读：只写 .deck 工作副本，不回写源。
+ */
+export function createScriptToSourceSync({ adapters = [], isLocalDeck = null } = {}) {
+  return function syncScriptToSource(deckId, scriptText, proposal = null) {
+    if (typeof isLocalDeck !== "function" || !isLocalDeck(deckId)) return null;
+    const adapter = adapters.find((candidate) => candidate.id === deckId) ?? null;
+    const sourceRoot = String(adapter?.sourceRoot ?? "");
+    if (!sourceRoot || !existsSync(sourceRoot)) return null;
+    const file = join(sourceRoot, "script.md");
+    writeFileSync(file, scriptText.endsWith("\n") ? scriptText : `${scriptText}\n`, "utf8");
+    const label = proposal?.kind === "script-add-page" ? "追加页" : "改稿";
+    const git = commitFiles({ dir: sourceRoot, files: [file], message: `deck(${deckId})：${label}回写 script` });
+    return { path: file, ok: git?.ok === true, commit: git?.commit ?? null, error: git?.ok ? null : git?.error ?? "git 未提交" };
+  };
+}
+
+/** 把一条 waiting-user 提案落成 revision（或记为用户驳回）。 */
+export function decideProposal({ store, workspace, proposal, confirmed, quote = "", sessionId = null, syncScriptToSource = null }) {
+  if (!proposal) throw new Error("提案不存在");
+  if (proposal.status !== "waiting-user") throw new Error(`提案 ${proposal.proposalId} 状态为 ${proposal.status}，只有 waiting-user 可裁决`);
+
+  const task = store.taskList(200).find((candidate) => candidate.kind === "edit" && (candidate.inputRefs ?? []).includes(`proposal:${proposal.proposalId}`));
+
+  if (confirmed !== true) {
+    workspace.updateProposal(proposal, { status: "rejected", decidedAt: proposalNow(), decidedBy: "user", note: String(quote ?? "") });
+    if (task) store.taskUpdate(task.taskId, { status: "cancelled", actor: "user", error: "user-rejected" });
+    store.recordEvent({
+      type: "deck.edit",
+      sessionId,
+      taskId: task?.taskId ?? null,
+      deckId: proposal.deckId,
+      slideIds: [proposal.pageId],
+      actor: "user",
+      status: "failed",
+      payload: { proposalId: proposal.proposalId, outcome: "rejected", note: String(quote ?? "") },
+    });
+    return { proposalId: proposal.proposalId, status: "rejected", deckId: proposal.deckId, text: `提案 ${proposal.proposalId} 已按用户意思驳回并留痕。` };
+  }
+
+  // F-137：确认不再强制「必须引用原话」。用户在 Chat 说「就这样 / 可以」、或在工作台点「确认落版」都算确认；
+  // 拿不到原话时仍落版，但事件里记 quoteMissing=true 留痕（审计可查），并把警告回给 Agent。
+  const confirmationQuote = String(quote ?? "").trim();
+  const quoteMissing = !confirmationQuote;
+  const affectedSlideIds = Array.isArray(proposal.pageIds) && proposal.pageIds.length ? [...proposal.pageIds] : [proposal.pageId];
+
+  let revisionInfo = null;
+  let appliedScriptText = null;
+  if (proposal.kind === "script") {
+    const current = workspace.scriptCurrent(proposal.deckId);
+    if (current == null) throw new Error(`script 工作副本缺失：${proposal.deckId}`);
+    // 用行级替换：before 行 → after 行（提案生成时已定稿，避免重算）。
+    const lines = current.split("\n");
+    // before 行必须落在「这一页」的分节里；否则同页对面（或别的页）的相同占位行会被误改。
+    const range = scriptSectionRange(current, proposal.page);
+    const start = range ? range.start + 1 : 0;
+    const end = range ? range.end : lines.length;
+    let index = -1;
+    for (let i = start; i < end; i += 1) {
+      if (lines[i] === proposal.before) {
+        index = i;
+        break;
+      }
+    }
+    if (index < 0) throw new Error(`提案已过期：工作副本里找不到提案 ${proposal.proposalId} 的 before 行（已被其他 revision 改动）。请驳回这条提案，让 Agent 基于当前脚本重新提案。`);
+    lines[index] = proposal.after;
+    // F-120：改标题时把分节标题行 `### PNN · 旧标题` 一起改掉。历史 bug：只改 `**标题**` 行，
+    // 标题行一直留着旧标题，错位后没人看得出来，工作副本与 manifest 越走越远。
+    if (proposal.field === "title") {
+      const newTitle = String(proposal.value ?? proposal.after ?? "").replace(/^\s*\*\*[^*]+\*\*\s*[：:]\s*/, "").trim();
+      if (newTitle && range) {
+        for (let i = range.start; i < Math.min(range.start + 3, lines.length); i += 1) {
+          if (/^#{2,3}\s*P0*\d+\s*[·.\-–—:]/.test(lines[i].trim())) {
+            lines[i] = lines[i].replace(/(^#{2,3}\s*P0*\d+\s*[·.\-–—:]\s*).*$/, `$1${newTitle}`);
+            break;
+          }
+        }
+      }
+    }
+    appliedScriptText = lines.join("\n");
+    revisionInfo = workspace.saveScriptRevision(proposal.deckId, appliedScriptText, `apply ${proposal.proposalId} (${proposal.pageId}.${proposal.field}) by user confirmation`);
+    // 同步 manifest 的对应字段，保持 deck.json 与 script 一致。
+    const deck = workspace.manifest(proposal.deckId);
+    const slide = deck?.slides?.find((candidate) => candidate.id === proposal.pageId);
+    if (deck && slide) {
+      if (String(proposal.after ?? "").startsWith("|") && SCRIPT_FIELD_CELL[proposal.field] != null) {
+        // 表格惯例：after 是完整表格行，第 0 个 split 段是行首空串。
+        const cell = proposal.after.split("|")[SCRIPT_FIELD_CELL[proposal.field] + 1];
+        if (typeof cell === "string" && cell.trim()) slide[proposal.field] = cell.trim();
+        workspace.saveManifest(deck);
+      } else if (proposal.field === "title" || proposal.field === "question" || proposal.field === "claim" || proposal.field === "body") {
+        // 分节惯例（F-75 / F-109）：直接取提案里的纯值；老提案没有 value 就从 `**字段**：值` 里剥。
+        const value = proposal.value != null ? String(proposal.value).trim() : String(proposal.after ?? "").replace(/^\s*\*\*[^*]+\*\*\s*[：:]\s*/, "").trim();
+        if (value) slide[proposal.field] = value;
+        workspace.saveManifest(deck);
+      }
+    }
+  } else if (proposal.kind === "script-add-page") {
+    // F-99：追加页的写回分支。不复用上面的行级替换（before="" 会命中第一处空行），
+    // 而是基于**当前**工作副本重算追加结果，避免提案后又被别的 revision 改过而覆盖。
+    const current = workspace.scriptCurrent(proposal.deckId);
+    if (current == null) throw new Error(`script 工作副本缺失：${proposal.deckId}`);
+    const applied = workspace.appendScriptPages(current, proposal.pages ?? []);
+    if (!applied.pages.length) throw new Error(`提案 ${proposal.proposalId} 没有可追加的页`);
+    revisionInfo = workspace.saveScriptRevision(
+      proposal.deckId,
+      applied.text,
+      `append ${applied.pages.length} page(s) ${applied.pages.map((spec) => `P${String(spec.page).padStart(2, "0")}`).join(" ")} by user confirmation (${proposal.proposalId})`,
+    );
+    const deck = workspace.manifest(proposal.deckId);
+    if (!deck) throw new Error(`manifest 缺失：${proposal.deckId}`);
+    deck.slides = Array.isArray(deck.slides) ? deck.slides : [];
+    const existingIds = new Set(deck.slides.map((slide) => slide.id));
+    for (const spec of applied.pages) {
+      const pageId = `p${String(spec.page).padStart(2, "0")}`;
+      if (existingIds.has(pageId)) {
+        throw new Error(`manifest 已有 ${pageId}，拒绝重复追加（可能已确认过；请重新提案）`);
+      }
+      deck.slides.push({
+        id: pageId,
+        order: spec.page,
+        type: "story",
+        title: spec.title,
+        question: spec.question,
+        claim: spec.claim,
+        source: "script.md",
+        asset: null,
+        // 追加页默认没有画面要求；出图前先走 deck_script_propose_edit 补 visualBrief。
+        visualBrief: spec.visualBrief,
+      });
+    }
+    deck.slides.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+    workspace.saveManifest(deck);
+    proposal.pageCountAfter = applied.pageCount;
+    appliedScriptText = applied.text;
+  } else {
+    const deck = workspace.manifest(proposal.deckId);
+    const slide = deck?.slides?.find((candidate) => candidate.id === proposal.pageId);
+    if (!deck || !slide) throw new Error(`manifest 页不存在：${proposal.pageId}`);
+    slide.visualBrief = String(proposal.after ?? "").trim();
+    // F-114：记录这页画面要求是在哪个关联风格下写的（换风格时据此判断要不要刷新）。
+    slide.visualBriefDesign = proposal.writtenUnderDesign ?? null;
+    workspace.saveManifest(deck);
+  }
+
+  // F-100 / ADR-0022：本机新建 deck 的脚本改动回写源 script.md；受控客户源保持只读。
+  const sourceSync = appliedScriptText != null && typeof syncScriptToSource === "function"
+    ? syncScriptToSource(proposal.deckId, appliedScriptText, proposal)
+    : null;
+
+  if (quoteMissing) {
+    store.recordEvent({ type: "deck.edit", sessionId, taskId: task?.taskId ?? null, deckId: proposal.deckId, slideIds: affectedSlideIds, actor: "system", status: "succeeded", payload: { proposalId: proposal.proposalId, outcome: "applied", quoteMissing: true } });
+  }
+  workspace.updateProposal(proposal, { status: "applied", decidedAt: proposalNow(), decidedBy: "user", confirmationQuote, quoteMissing, revision: revisionInfo?.revision ?? null });
+  if (task) {
+    store.taskUpdate(task.taskId, {
+      status: "succeeded",
+      actor: "user",
+      outputRefs: [...(revisionInfo ? [`revision:${proposal.deckId}/script/${revisionInfo.revision}`] : []), `proposal:${proposal.proposalId}`],
+    });
+  }
+  store.recordEvent({
+    type: "deck.edit",
+    sessionId,
+    taskId: task?.taskId ?? null,
+    deckId: proposal.deckId,
+    slideIds: affectedSlideIds,
+    actor: "user",
+    status: "succeeded",
+    payload: { proposalId: proposal.proposalId, outcome: "applied", confirmationQuote, quoteMissing, revision: revisionInfo?.revision ?? null, revisionPath: revisionInfo?.path ?? null, ...(sourceSync ? { sourceSync } : {}), ...(proposal.kind === "script-add-page" ? { field: "add-page", pages: proposal.pageIds, pageCountAfter: proposal.pageCountAfter ?? null } : {}) },
+  });
+
+  return {
+    proposalId: proposal.proposalId,
+    status: "applied",
+    revision: revisionInfo?.revision ?? null,
+    revisionPath: revisionInfo?.path ?? null,
+    deckId: proposal.deckId,
+    ...(sourceSync ? { sourceSync } : {}),
+    ...(quoteMissing ? { quoteMissing: true } : {}),
+    text:
+      `提案 ${proposal.proposalId} 已应用${revisionInfo ? `，script revision ${revisionInfo.revision} 已写入（旧版保留）` : ""}` +
+      `。${sourceSync ? (sourceSync.ok ? `源 script.md 已回写并提交（${sourceSync.commit}）。` : `源 script.md 已回写，git 未提交：${sourceSync.error}。`) : ""}` +
+      `${quoteMissing ? "\n（这次没带用户原话，已按确认动作落版并标 quoteMissing 留痕；下次能引用原话更好。）" : ""}`,
+  };
+}

package/lib/render-nodes.js

@@ -0,0 +1,171 @@
+/**
+ * 出图节点与模型：多节点（url / key / model 列表）+ 当前 deck 的生效选择。
+ *
+ * 配置（profile 的 plugin config）：
+ *   render:
+ *     mode: real
+ *     default: main/gpt-image-2.5-sunburst       # 缺省选择：节点 id / 模型 id
+ *     nodes:
+ *       - id: main
+ *         name: 主节点（示例）
+ *         endpoint: https://your-image-relay.example.com/v1/images/generations
+ *         apiKeyEnv: DSH_DECK_IMAGE_API_KEY        # 只存 env 名 / key 文件路径，不存 key 本身
+ *         apiKeyFile: ~/.config/relays.secret.env
+ *         models: [gpt-image-2.5-sunburst, gpt-image-2.5-flare]
+ *
+ * 节点地址与 key 都只来自配置 / env / 本机 key 文件；仓库不携带任何真实节点地址（默认空）。
+ * 兼容旧配置：没有 nodes 时，用 render.endpoint / model / apiKeyEnv / apiKeyFile 生成一个默认节点。
+ * 所有对外 payload 只给 `keyConfigured` 布尔值，绝不返回 key。
+ * @module dsh-plugin-deck-studio/render-nodes
+ */
+
+import { existsSync } from "node:fs";
+
+const asTrimmed = (value) => (typeof value === "string" ? value.trim() : "");
+
+/**
+ * 归一化出图节点列表（过滤空节点/无模型节点；同时兼容旧的单节点配置）。
+ * @param {Record<string, unknown>} render - config.render
+ * @returns {Array<{id:string,name:string,endpoint:string,apiKeyEnv:string,apiKeyFile:string,models:string[]}>}
+ */
+export function normalizeRenderNodes(render = {}) {
+  const rawNodes = Array.isArray(render?.nodes) ? render.nodes : [];
+  const nodes = rawNodes
+    .filter((node) => node && typeof node === "object")
+    .map((node, index) => {
+      const id = asTrimmed(node.id) || `node-${index + 1}`;
+      const models = (Array.isArray(node.models) ? node.models : [])
+        .map((model) => (typeof model === "string" ? model.trim() : asTrimmed(model?.id)))
+        .filter(Boolean);
+      return {
+        id,
+        name: asTrimmed(node.name) || id,
+        // 节点字段缺省时回退到旧的顶层配置，保证老 profile 还能用
+        endpoint: asTrimmed(node.endpoint) || asTrimmed(render?.endpoint),
+        // 直接存在本机设置文件里的 key（F-146）：给「填名字 + 地址 + key + 模型」的小白流程用。
+        apiKey: asTrimmed(node.apiKey),
+        // 修图端点：不配就由 endpoint 派生（/v1/images/generations → /v1/images/edits）。
+        editEndpoint: asTrimmed(node.editEndpoint) || asTrimmed(render?.editEndpoint),
+        editTransport: asTrimmed(node.editTransport) || asTrimmed(render?.editTransport),
+        apiKeyEnv: asTrimmed(node.apiKeyEnv) || asTrimmed(render?.apiKeyEnv),
+        apiKeyFile: asTrimmed(node.apiKeyFile) || asTrimmed(render?.apiKeyFile),
+        models,
+      };
+    })
+    .filter((node) => node.models.length > 0);
+
+  if (nodes.length) return nodes;
+
+  // 旧配置：单个 endpoint + 单个 model
+  const legacyModel = asTrimmed(render?.model);
+  if (!render?.endpoint && !legacyModel) return [];
+  return [
+    {
+      id: "default",
+      name: "默认节点",
+      endpoint: asTrimmed(render?.endpoint),
+      apiKey: asTrimmed(render?.apiKey),
+      editEndpoint: asTrimmed(render?.editEndpoint),
+      editTransport: asTrimmed(render?.editTransport),
+      apiKeyEnv: asTrimmed(render?.apiKeyEnv),
+      apiKeyFile: asTrimmed(render?.apiKeyFile),
+      models: legacyModel ? [legacyModel] : [],
+    },
+  ].filter((node) => node.models.length > 0);
+}
+
+/**
+ * 配置里的缺省选择：`render.default`（nodeId/modelId）；兼容旧 `render.model`。
+ * @returns {{nodeId:string, model:string}|null}
+ */
+export function defaultSelection(render = {}) {
+  const nodes = normalizeRenderNodes(render);
+  if (!nodes.length) return null;
+  const raw = asTrimmed(render?.default);
+  if (raw) {
+    const slash = raw.indexOf("/");
+    const nodeId = slash > 0 ? raw.slice(0, slash) : "";
+    const model = slash > 0 ? raw.slice(slash + 1) : raw;
+    const node = nodes.find((item) => item.id === nodeId);
+    if (node && node.models.includes(model)) return { nodeId: node.id, model };
+    const fallbackNode = nodes.find((item) => item.models.includes(model));
+    if (fallbackNode) return { nodeId: fallbackNode.id, model };
+  }
+  const legacyModel = asTrimmed(render?.model);
+  if (legacyModel) {
+    const node = nodes.find((item) => item.models.includes(legacyModel));
+    if (node) return { nodeId: node.id, model: legacyModel };
+  }
+  return { nodeId: nodes[0].id, model: nodes[0].models[0] };
+}
+
+/**
+ * 校验一个选择是否合法；非法返回 null（调用方报错而不是悄悄用别的）。
+ * @returns {{nodeId:string, nodeName:string, node:object, model:string, endpoint:string, apiKeyEnv:string, apiKeyFile:string, label:string}|null}
+ */
+export function resolveSelection(render = {}, selection = null) {
+  const nodes = normalizeRenderNodes(render);
+  const wanted = selection && (selection.nodeId || selection.model)
+    ? {
+        nodeId: asTrimmed(selection.nodeId),
+        model: asTrimmed(selection.model),
+      }
+    : defaultSelection(render);
+  if (!wanted) return null;
+  const node = nodes.find((item) => item.id === wanted.nodeId) ?? nodes.find((item) => item.models.includes(wanted.model));
+  if (!node) return null;
+  if (wanted.model && !node.models.includes(wanted.model)) return null; // 显式指定了不存在的模型：拒绝，不悄悄替换
+  const model = wanted.model || node.models[0];
+  return {
+    nodeId: node.id,
+    nodeName: node.name,
+    node,
+    model,
+    endpoint: node.endpoint,
+    apiKey: node.apiKey,
+    editEndpoint: node.editEndpoint,
+    editTransport: node.editTransport,
+    apiKeyEnv: node.apiKeyEnv,
+    apiKeyFile: node.apiKeyFile,
+    label: `${node.name} / ${model}`,
+  };
+}
+
+/** key 是否已配置（env 变量存在或有 key 文件；不读、不返回 key 值本身）。 */
+export function keyConfigured(node, env = process.env) {
+  if (asTrimmed(node?.apiKey)) return true;
+  const envName = asTrimmed(node?.apiKeyEnv);
+  const file = asTrimmed(node?.apiKeyFile);
+  if (envName && env[envName]) return true;
+  return Boolean(file && existsSync(file));
+}
+
+/**
+ * 对外 payload（设置面板 / 工作台状态）：节点列表（含 key 配置状态）+ 当前生效选择。
+ * @param {Record<string, unknown>} render
+ * @param {object} [options]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {{nodeId:string, model:string}|null} [options.selection]
+ */
+export function renderModelPayload(render = {}, { env = process.env, selection = null } = {}) {
+  const nodes = normalizeRenderNodes(render);
+  const active = resolveSelection(render, selection) ?? resolveSelection(render, null);
+  return {
+    mode: asTrimmed(render?.mode) || "fake",
+    size: asTrimmed(render?.size),
+    active: active
+      ? { nodeId: active.nodeId, nodeName: active.nodeName, model: active.model, label: active.label }
+      : null,
+    nodes: nodes.map((node) => ({
+      id: node.id,
+      name: node.name,
+      endpoint: node.endpoint,
+      models: node.models,
+      apiKeyEnv: node.apiKeyEnv,
+      apiKeyFile: node.apiKeyFile,
+      keyConfigured: keyConfigured(node, env),
+      // saved = key 存在本机设置文件；env / file = 用环境变量或 key 文件；none = 没配
+      keySource: asTrimmed(node.apiKey) ? "saved" : node.apiKeyEnv && env[node.apiKeyEnv] ? "env" : node.apiKeyFile && existsSync(node.apiKeyFile) ? "file" : "none",
+    })),
+  };
+}