dsh-plugin-deck-studio 0.2.27 → 0.2.28

package/lib/proposal-decision.js

@@ -12,7 +12,7 @@
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { SCRIPT_FIELD_CELL, proposalNow, scriptSectionRange } from "./deck-workspace.js";
+import { SCRIPT_FIELD_CELL, pageIdFromNumber, pageNumberFromId, proposalNow, scriptSectionRange } from "./deck-workspace.js";
 import { commitFiles } from "./git-commit.js";
 import { isFirstDraft, writeAutoland } from "./first-draft.js";
 
@@ -28,7 +28,7 @@ export function createScriptToSourceSync({ adapters = [], isLocalDeck = null } =
     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 label = proposal?.kind === "script-add-page" ? "追加页" : proposal?.kind === "script-insert-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 未提交" };
   };
@@ -118,6 +118,108 @@ export function syncAddPageManifest(workspace, proposal, appliedPages) {
   workspace.saveManifest(deck);
 }
 
+/**
+ * 插页提案 → manifest 重编号 + 新页入表 + `slides/<pageId>/versions` 目录后移（F-208）。
+ *
+ * 顺序很重要：**先迁目录、再写 manifest**，所以下面先调 `workspace.shiftSlideDirs`
+ * （它内部失败会回滚已 rename 的目录），manifest 写盘在最后。这样任何一步抛错，
+ * 都不会出现「manifest 指向一个不存在的版本目录」的半截状态。
+ *
+ * slide 上补 `sourcePage`（原始源页号）：源 baseline 图按它取，插页改号不会让源图错位；
+ * 插页新增的页 `sourcePage: null`（源里没有 baseline 图，别去源里抓一张别人的图）。
+ */
+export function syncInsertPageManifest(workspace, proposal, applied) {
+  const deck = workspace.manifest(proposal.deckId);
+  if (!deck) throw new Error(`manifest 缺失：${proposal.deckId}`);
+  const slides = Array.isArray(deck.slides) ? deck.slides : [];
+  const atPage = Number(applied.at);
+  const shift = Number(applied.shift) || (applied.pages?.length ?? 0);
+  if (!Number.isInteger(atPage) || atPage < 1 || !Number.isInteger(shift) || shift < 1) {
+    throw new Error(`插页参数无效：at=${applied.at} shift=${applied.shift}`);
+  }
+  const oldCover = slides.find((slide) => Number(slide.order) === 1 && slide.type === "cover") ?? null;
+
+  // 1) 目录跟着内容后移（.deck/.../slides/p03 → p05 …）
+  const moved = workspace.shiftSlideDirs(deck.id, { fromPage: atPage, shift });
+
+  // 2) manifest 重编号：id 与 order 一起改，并把「原始源页」记到 sourcePage（只在第一次改号时记）。
+  const renumbered = slides.map((slide) => {
+    const order = Number(slide.order);
+    if (!(order >= atPage)) return slide;
+    const next = { ...slide, order: order + shift, id: pageIdFromNumber(order + shift) };
+    if (!Object.prototype.hasOwnProperty.call(slide, "sourcePage")) next.sourcePage = order;
+    return next;
+  });
+
+  // 3) 新页入表：插到第 1 页之前时，封面身份交给新页（老封面降级为 story，保持「一本只有一个封面」）。
+  // 占位判断用**重编号之后**的 id：新页要占的号原本属于被后移的页，那不是冲突。
+  const occupiedIds = new Set(renumbered.map((slide) => slide.id));
+  const inserted = (applied.pages ?? []).map((spec, index) => {
+    const pageId = pageIdFromNumber(spec.page);
+    if (occupiedIds.has(pageId)) {
+      throw new Error(`manifest 已有 ${pageId}，拒绝重复插入（manifest 与脚本页号不一致；先核对 deck.json 或跑 deck_script_repair 体检）`);
+    }
+    const takesCover = atPage === 1 && index === 0 && oldCover != null;
+    return {
+      id: pageId,
+      order: spec.page,
+      type: takesCover ? "cover" : "story",
+      title: spec.title,
+      question: spec.question,
+      claim: spec.claim,
+      source: "script.md",
+      asset: null,
+      visualBrief: spec.visualBrief,
+      // 源里没有这一页 → 没有 baseline 图；显式 null 防止回退到同号源页的图。
+      sourcePage: null,
+      inserted: true,
+    };
+  });
+  deck.slides = [...renumbered, ...inserted].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  if (atPage === 1 && oldCover != null) {
+    // 老封面整体后移到 1+shift，降级成 story（新第一页接管封面）。
+    const demoted = deck.slides.find((slide) => Number(slide.order) === 1 + shift && slide.type === "cover");
+    if (demoted) demoted.type = "story";
+  }
+  workspace.saveManifest(deck);
+  return { moved, fromPage: atPage, shift, insertedIds: inserted.map((slide) => slide.id) };
+}
+
+/**
+ * 插页确认后，把落在被后移页上的**待确认提案**改到新页号（F-208）。
+ * 不改就全落错页：提案里存的是旧 page/pageId，而工作副本已经重编号。
+ * 追加页 / 插页提案带自己的页号语义，不动（它们在落版时按当前脚本重算）。
+ */
+export function remapProposalsAfterInsert(workspace, deckId, { fromPage, shift, skipIds = [] }) {
+  const remapped = [];
+  for (const proposal of workspace.listProposals(deckId, "waiting-user")) {
+    if (skipIds.includes(proposal.proposalId)) continue;
+    if (proposal.kind === "script-add-page" || proposal.kind === "script-insert-page") continue;
+    const oldPage = Number(proposal.page);
+    const oldPageIds = Array.isArray(proposal.pageIds) ? proposal.pageIds : [];
+    const pageShifted = Number.isFinite(oldPage) && oldPage >= fromPage;
+    const idsShifted = oldPageIds.some((id) => {
+      const page = pageNumberFromId(id);
+      return page != null && page >= fromPage;
+    });
+    if (!pageShifted && !idsShifted) continue;
+    const patch = { renumberedAfterInsert: { from: oldPage, shift } };
+    if (pageShifted) {
+      patch.page = oldPage + shift;
+      patch.pageId = pageIdFromNumber(oldPage + shift);
+    }
+    if (oldPageIds.length) {
+      patch.pageIds = oldPageIds.map((id) => {
+        const page = pageNumberFromId(id);
+        return page != null && page >= fromPage ? pageIdFromNumber(page + shift) : id;
+      });
+    }
+    workspace.updateProposal(proposal, patch);
+    remapped.push({ proposalId: proposal.proposalId, from: proposal.pageId, to: patch.pageId ?? proposal.pageId });
+  }
+  return remapped;
+}
+
 /**
  * 批量落版（F-176 / 智力升级 I-18）：把一批 script 提案合成**一条** revision。
  * 首稿自动落版（F-173）与用户「接受并更新」勾选批次共用这一段，保证两条路径的写入语义一致。
@@ -129,10 +231,14 @@ function landProposalBatch({ store, workspace, proposals, decidedBy, quote = "",
   for (const proposal of list) {
     if (proposal.deckId !== deckId) throw new Error("批量落版只处理同一个 deck 的提案");
     if (proposal.status !== "waiting-user") throw new Error(`提案 ${proposal.proposalId} 状态为 ${proposal.status}，只有 waiting-user 可落版`);
-    if (proposal.kind !== "script" && proposal.kind !== "script-add-page" && proposal.kind !== "manifest") {
-      throw new Error(`批量落版不支持 ${proposal.kind} 类提案（只支持 script 正文 / 追加页 / visualBrief）`);
+    if (proposal.kind !== "script" && proposal.kind !== "script-add-page" && proposal.kind !== "script-insert-page" && proposal.kind !== "manifest") {
+      throw new Error(`批量落版不支持 ${proposal.kind} 类提案（只支持 script 正文 / 追加页 / 插页 / visualBrief）`);
     }
   }
+  // F-208：插页会让后面的页号整体后移；和别的提案混批时，那些提案里的 page 已经对不上工作副本。
+  if (list.some((proposal) => proposal.kind === "script-insert-page") && list.length > 1) {
+    throw new Error("插页提案要单独确认：它会让后面的页号整体后移，和别的提案混批会落到错页。请先单独确认插页提案，再处理其它提案。");
+  }
   const current = workspace.scriptCurrent(deckId);
   if (current == null) throw new Error(`script 工作副本缺失：${deckId}`);
   let text = current;
@@ -150,6 +256,15 @@ function landProposalBatch({ store, workspace, proposals, decidedBy, quote = "",
       manifestTouched = true;
       continue;
     }
+    if (proposal.kind === "script-insert-page") {
+      const applied = workspace.insertScriptPages(text, { at: proposal.at, pages: proposal.pages ?? [] });
+      if (!applied.pages.length) throw new Error(`提案 ${proposal.proposalId} 没有可插入的页`);
+      text = applied.text;
+      syncInsertPageManifest(workspace, proposal, applied);
+      remapProposalsAfterInsert(workspace, deckId, { fromPage: applied.at, shift: applied.shift, skipIds: [proposal.proposalId] });
+      proposal.pageCountAfter = applied.pageCount;
+      continue;
+    }
     if (proposal.kind === "script-add-page") {
       const applied = workspace.appendScriptPages(text, proposal.pages ?? []);
       if (!applied.pages.length) throw new Error(`提案 ${proposal.proposalId} 没有可追加的页`);
@@ -274,8 +389,8 @@ export function decideProposal({ store, workspace, proposal, confirmed, quote =
   // 判定放在这里（而不是 Agent 侧）：Agent 说错话也落不了有历史版本的稿子。
   const wantAutoland = autoland != null;
   if (wantAutoland) {
-    if (proposal.kind !== "script" && proposal.kind !== "script-add-page") {
-      throw new Error("自动落版只用于 script 内容（正文 / 追加页）；visualBrief 这类仍走提案确认。");
+    if (proposal.kind !== "script" && proposal.kind !== "script-add-page" && proposal.kind !== "script-insert-page") {
+      throw new Error("自动落版只用于 script 内容（正文 / 追加页 / 插页）；visualBrief 这类仍走提案确认。");
     }
     if (!isFirstDraft(workspace, proposal.deckId)) {
       throw new Error(`首稿自动落版被拒：${proposal.deckId} 已有已落版 revision。自动落版只用于第一次落库，这次请等用户确认后再落。`);
@@ -312,6 +427,22 @@ export function decideProposal({ store, workspace, proposal, confirmed, quote =
     syncAddPageManifest(workspace, proposal, applied.pages);
     proposal.pageCountAfter = applied.pageCount;
     appliedScriptText = applied.text;
+  } else if (proposal.kind === "script-insert-page") {
+    // F-208：插页 = 重编号 + 目录迁移。和追加页一样基于**当前**工作副本重算，避免提案后被别的
+    // revision 改过而覆盖；manifest / 目录 / 待确认提案的页号一起迁，已出的图跟着内容走。
+    const current = workspace.scriptCurrent(proposal.deckId);
+    if (current == null) throw new Error(`script 工作副本缺失：${proposal.deckId}`);
+    const applied = workspace.insertScriptPages(current, { at: proposal.at, pages: proposal.pages ?? [] });
+    if (!applied.pages.length) throw new Error(`提案 ${proposal.proposalId} 没有可插入的页`);
+    const synced = syncInsertPageManifest(workspace, proposal, applied);
+    revisionInfo = workspace.saveScriptRevision(
+      proposal.deckId,
+      applied.text,
+      `insert ${applied.pages.length} page(s) before P${String(applied.at).padStart(2, "0")}; ${synced.moved.length} page dir(s) shifted by ${applied.shift} by user confirmation (${proposal.proposalId})`,
+    );
+    remapProposalsAfterInsert(workspace, proposal.deckId, { fromPage: applied.at, shift: applied.shift, skipIds: [proposal.proposalId] });
+    proposal.pageCountAfter = applied.pageCount;
+    appliedScriptText = applied.text;
   } else {
     const deck = workspace.manifest(proposal.deckId);
     const slide = deck?.slides?.find((candidate) => candidate.id === proposal.pageId);
@@ -357,7 +488,7 @@ export function decideProposal({ store, workspace, proposal, confirmed, quote =
     slideIds: affectedSlideIds,
     actor: autolandRecord ? "agent" : "user",
     status: "succeeded",
-    payload: { proposalId: proposal.proposalId, outcome: "applied", confirmationQuote, quoteMissing, revision: revisionInfo?.revision ?? null, revisionPath: revisionInfo?.path ?? null, ...(autolandRecord ? { autoland: true, selfReview: autolandRecord.selfReview, draftRound: autolandRecord.draftRound } : {}), ...(sourceSync ? { sourceSync } : {}), ...(proposal.kind === "script-add-page" ? { field: "add-page", pages: proposal.pageIds, pageCountAfter: proposal.pageCountAfter ?? null } : {}) },
+    payload: { proposalId: proposal.proposalId, outcome: "applied", confirmationQuote, quoteMissing, revision: revisionInfo?.revision ?? null, revisionPath: revisionInfo?.path ?? null, ...(autolandRecord ? { autoland: true, selfReview: autolandRecord.selfReview, draftRound: autolandRecord.draftRound } : {}), ...(sourceSync ? { sourceSync } : {}), ...(proposal.kind === "script-add-page" ? { field: "add-page", pages: proposal.pageIds, pageCountAfter: proposal.pageCountAfter ?? null } : {}), ...(proposal.kind === "script-insert-page" ? { field: "insert-page", pages: proposal.pageIds, at: proposal.at ?? null, pageCountAfter: proposal.pageCountAfter ?? null } : {}) },
   });
 
   return {

package/lib/render.js

@@ -79,6 +79,87 @@ export function onImageText(slide) {
   };
 }
 
+/**
+ * 源 deck 完整 prompt 的脚手架清洗（F-209）。
+ * 源 `prompts/Pnn.txt` 是「STYLE + LAYOUT AND EXACT TEXT（含标题/正文）+ LAYOUT VISUALS + BOTTOM TAKEAWAY」
+ * 的完整独立 prompt（导入时原样进了 manifest.visualBrief）。原样拼进出图 prompt 时：
+ * - `### P02 · 标题` 会被模型当图上文字印出来（事故：页顶出现 `##P2`，p05 还出现 `P03 · …` 徽章）；
+ * - `STYLE:` / `LAYOUT AND EXACT TEXT:` / `**标题**：` 这些脚手架也可能被换个形式画到图上。
+ * 只删脚手架，**内容一字不动**（受控源 deck 的 manifest.body 常为空，图上正文来自这些内容段，
+ * 删内容会丢整页正文）。未识别成完整源 prompt 的文本（用户自己写的画面要求、单行 STYLE）原样返回：
+ * 幂等、零误伤。实测一本 21 页受控源 deck 的 p04：1005 → 295 字符（出图 prompt 1517 → 829）。
+ * @param {string} value
+ * @returns {string}
+ */
+export function stripVisualBriefScaffolding(value) {
+  const text = String(value ?? "").replace(/\r\n/g, "\n");
+  if (!text.trim()) return "";
+  const lines = text.split("\n");
+  // 只有「像完整源 prompt」时才洗；单行 STYLE / 用户自写画面要求一律不动（smoke 契约）。
+  const looksLikeSourcePrompt = lines.some((line) => {
+    const t = line.trim();
+    return /^LAYOUT AND EXACT TEXT\s*[:：]?\s*$/i.test(t)
+      || /^PAGE CONTENT\b/i.test(t)
+      || /^LAYOUT VISUALS\b/i.test(t)
+      || /^BOTTOM TAKEAWAY\s*[:：]/i.test(t)
+      || /^LAYOUT GUARD\s*[:：]/i.test(t)
+      || /^#{1,6}\s*P\d+\b/.test(t)
+      || /^TITLE, the largest\b/i.test(t);
+  });
+  if (!looksLikeSourcePrompt) return text.trim();
+
+  const MD_PAGE_HEAD = /^\s{0,3}#{1,6}\s*P\d+\b.*$/;
+  const STYLE_START = /^STYLE\s*[:：]/i;
+  const EXACT_HEAD = /^LAYOUT AND EXACT TEXT\s*[:：]?\s*$/i;
+  const ENGLISH_FIELD_HEADS = [/^PAGE CONTENT\b/i, /^LAYOUT VISUALS\b/i, /^LAYOUT GUARD\b/i];
+  const TAKEAWAY_HEAD = /^(?:BOTTOM TAKEAWAY|页脚收口)\s*[:：]\s*(.*)$/i;
+  const FIELD = /^\*\*([^*]+)\*\*\s*[：:]\s*(.*)$/;
+  const DROP_FIELDS = new Set(["标题", "副标题", "讲述意图", "页面内容", "正文", "画面说明"]);
+  const EN_TITLE_LINE = /^(TITLE|SUBTITLE)\b[^:：]*[:：]\s*「?(.*?)」?\s*$/i;
+  const EN_TAKEAWAY = /^BOTTOM TAKEAWAY\s*[:：]\s*(.*)$/i;
+
+  const kept = [];
+  let inStyle = false;
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\s+$/, "");
+    const t = line.trim();
+    if (!t) {
+      inStyle = false;
+      kept.push("");
+      continue;
+    }
+    if (STYLE_START.test(t)) {
+      inStyle = true;
+      continue;
+    }
+    if (inStyle) continue;
+    if (MD_PAGE_HEAD.test(t)) continue;
+    if (EXACT_HEAD.test(t)) continue;
+    if (ENGLISH_FIELD_HEADS.some((rx) => rx.test(t))) continue;
+    if (EN_TITLE_LINE.test(t)) continue;
+    const enTake = EN_TAKEAWAY.exec(t);
+    if (enTake) {
+      kept.push(`页脚通栏一句：「${enTake[1].trim()}」`);
+      continue;
+    }
+    const field = FIELD.exec(t);
+    if (field) {
+      const name = field[1].trim();
+      if (DROP_FIELDS.has(name)) continue;
+      const value = field[2].trim();
+      kept.push(value ? `${name}：${value}` : `${name}：`);
+      continue;
+    }
+    const take = TAKEAWAY_HEAD.exec(t);
+    if (take) {
+      kept.push(`页脚通栏一句：「${take[1].trim()}」`);
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
 const ON_IMAGE_HEAD = "【这一页必须在画面上印出的文字：逐字照排，不要改写、翻译、缩写或省略】";
 /** 反装饰：图例 / 清单面板 / 英文角标这类「看起来专业但跟本页无关」的元素，模型最容易凭空造。 */
 const CANVAS_DISCIPLINE =
@@ -112,11 +193,12 @@ export function buildPrompt(slide, styleBrief, context = {}) {
   const brief = context.brief ?? {};
   const list = onImageText(slide);
   const isCover = slide?.type === "cover" || Number(slide?.order) === 1;
+  const visualBrief = stripVisualBriefScaffolding(slide?.visualBrief);
   if (isCover) {
     const parts = [styleBrief, "封面页（16:9）：只放标题信息", ...onImageLines({ ...list, bullets: [] })];
     parts.push(...coverPromptLines(brief));
     parts.push("版式纪律：只放主标题 / 副标题 / 作者 / 日期；正文不超过一行；不要目录、要点清单、数据图表、大段文字；留白为主。");
-    if (slide?.visualBrief) parts.push(`画面要求：${slide.visualBrief}`);
+    if (visualBrief) parts.push(`画面要求：${visualBrief}`);
     parts.push(CANVAS_DISCIPLINE);
     parts.push("文字优先：上面【图上文字】的每一行都必须出现在画面里；画面要求与它冲突时，以上面为准。");
     return parts.filter(Boolean).join("\n");
@@ -124,7 +206,7 @@ export function buildPrompt(slide, styleBrief, context = {}) {
   const parts = [styleBrief, ...onImageLines(list)];
   const body = String(slide?.body ?? "").trim();
   if (body) parts.push(`讲述用正文（不要整段排进画面，只提炼成上面的要点；用来把握语气与例子）：${body.slice(0, 300)}`);
-  if (slide?.visualBrief) parts.push(`画面要求：${slide.visualBrief}`);
+  if (visualBrief) parts.push(`画面要求：${visualBrief}`);
   parts.push(CANVAS_DISCIPLINE);
   parts.push("文字优先：上面【图上文字】的主标题 / 副标题 / 主张必须完整印出（可换行、可分层，但不得省略、不得改写成别的说法）；画面要求若写「只出现 XX」，XX 之外仍要保留这三项与要点短语。");
   parts.push(...briefPromptLines(brief));

package/lib/tools.js

@@ -57,6 +57,28 @@ function sessionIdOf(exec) {
   return exec?.agent?.id ?? null;
 }
 
+/**
+ * F-209：新页与稿子里已有页「同标题」时给出明确提醒。
+ * 插页/追加都只新增、不替换——用户拿「追加」当「搬位置」时会出现两套内容（
+ * 事故：先追加 P22/P23，再插页同一内容到 P02/P03，deck 里就多出一套）。
+ * 只做提醒，不阻断（有时确实要两页同标题的不同版本）；文案要让 Agent 先说清楚、别默认重复。
+ */
+function duplicateContentNotes(deck, specs) {
+  const normalize = (value) => String(value ?? "").replace(/[\s，。！？、；："'“”‘’（）()]/g, "").trim();
+  const existing = (deck?.slides ?? [])
+    .map((slide) => ({ id: slide.id, order: Number(slide.order) || null, title: normalize(slide.title), rawTitle: String(slide.title ?? "").trim() }))
+    .filter((slide) => slide.title);
+  const notes = [];
+  for (const spec of specs ?? []) {
+    const title = normalize(spec?.title);
+    if (!title) continue;
+    const hit = existing.find((slide) => slide.title === title);
+    if (hit) notes.push(`P${String(hit.order ?? 0).padStart(2, "0")}「${hit.rawTitle}」`);
+  }
+  return notes;
+}
+
+
 /**
  * Agent 可读的参考资料白名单（F-71）。
  *
@@ -994,6 +1016,7 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
       const preview = workspace.appendScriptPages(current, specs);
       const pageIds = specs.map((spec) => `p${String(spec.page).padStart(2, "0")}`);
       const diff = scriptDiff(current, preview.text);
+      const duplicateNotes = duplicateContentNotes(deck, specs);
       const proposal = {
         proposalId: newProposalId(),
         deckId: deck.id,
@@ -1014,6 +1037,7 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
         status: "waiting-user",
         createdAt: proposalNow(),
         sessionId: sessionIdOf(exec),
+        ...(duplicateNotes.length ? { duplicatePages: duplicateNotes } : {}),
       };
       workspace.saveProposal(proposal);
 
@@ -1052,12 +1076,151 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
         diff,
         text:
           `追加页提案 ${proposal.proposalId} 已进入 waiting-user：${deck.slides.length} 页 → ${preview.pageCount} 页` +
-          `（新增 ${pageIds.join(" / ")}，只追加到末尾，既有页不动）。\n\n${diff || "(无文本差异)"}\n` +
+          `（新增 ${pageIds.join(" / ")}，只追加到末尾，既有页不动）。\n` +
+          `${duplicateNotes.length ? `\n⚠ 稿子里已经有同标题的页：${duplicateNotes.join(" / ")}。追加只新增、不替换也不移动——确认后会出现两套内容。如果目的是把已有页搬到末尾，请先跟用户说明当前还不能移动/删页，不要直接追加副本。\n` : ""}` +
+          `\n${diff || "(无文本差异)"}\n` +
           `请在 Chat 里确认；确认后才写 script revision + manifest。`,
       };
     }),
   });
 
+  // ── 3.6 deck_script_insert_page ─────────────────────────────────────────────
+  tools.push({
+    name: "deck_script_insert_page",
+    description:
+      "在任意位置插入页（F-208：用户要「插到第 N 页之后 / 放在 P02 和 P03 之间」时用它）。" +
+      "`at` = 插到第 N 页之前（1-based；at = 当前页数+1 等价追加到末尾，那种情况优先用 deck_script_add_page）。" +
+      "生成 `### Pxx` 分节 + diff 并进入 waiting-user，用户确认后再用 deck_revision_confirm 落版。" +
+      "确认后 >= at 的页号整体后移 k 页，manifest 的 slide id/order 与 slides/<pageId>/versions 目录一起迁移——" +
+      "**已出的图跟着各自内容走，不需要整份重出**，绝对不要建议用户整份重出图。" +
+      "一次最多插 20 页。",
+    parameters: {
+      type: "object",
+      properties: {
+        deckId: { type: "string" },
+        at: { type: "number", description: "插到第 N 页之前（1-based）。P02 之后插入 → at=3；P01 之前（新开场）→ at=1" },
+        pages: {
+          type: "array",
+          description: "要插入的页（按顺序；必填，最多 20 页）",
+          items: {
+            type: "object",
+            properties: {
+              title: { type: "string" },
+              question: { type: "string" },
+              claim: { type: "string" },
+              body: { type: "string" },
+              visualBrief: { type: "string" },
+            },
+            additionalProperties: false,
+          },
+        },
+        reason: { type: "string", description: "为什么插在这里（写进 trace）" },
+      },
+      required: ["deckId", "at", "pages"],
+      additionalProperties: false,
+    },
+    output: { schema: { type: "object", properties: { proposalId: { type: "string" }, status: { type: "string" }, pageCount: { type: "number" } } }, render: (_args, value) => [{ type: "text", text: String(value?.text ?? "") }] },
+    execute: withToolEvent(store, "deck_script_insert_page", async (args, exec) => {
+      const adapter = adapterFor(args.deckId);
+      const deck = workspace.ensureDeck(adapter, { styleBrief: config.styleBrief });
+      const current = workspace.scriptCurrent(deck.id);
+      if (current == null) throw new Error(`script 工作副本缺失：${deck.id}`);
+      const explicit = Array.isArray(args.pages) ? args.pages.filter(Boolean) : [];
+      if (!explicit.length) throw new Error("插页需要 pages（至少一页：title / question / claim / body / visualBrief）");
+      if (explicit.length > 20) throw new Error("一次最多插入 20 页（更多请拆成两次提案）");
+      const preview = workspace.insertScriptPages(current, {
+        at: args.at,
+        pages: explicit.map((page) => ({
+          title: page?.title,
+          question: page?.question,
+          claim: page?.claim,
+          body: page?.body,
+          visualBrief: page?.visualBrief,
+        })),
+      });
+      const pageIds = preview.pages.map((spec) => `p${String(spec.page).padStart(2, "0")}`);
+      const diff = scriptDiff(current, preview.text);
+      const renumberLabel = preview.renumberedPages.length
+        ? `原 ${preview.renumberedPages.map((item) => `P${String(item.from).padStart(2, "0")}`).join(" / ")} 后移为 ${preview.renumberedPages.map((item) => `P${String(item.to).padStart(2, "0")}`).join(" / ")}`
+        : "没有页需要后移（插在末尾）";
+      // 插过页的 deck 里已经出过图的页，确认后会在 manifest 记上原始源页，源 baseline 图不错位。
+      const duplicateNotes = duplicateContentNotes(deck, preview.pages);
+      const pending = workspace.listProposals(deck.id, "waiting-user");
+      const pendingShifted = pending.filter((proposal) => Number(proposal.page) >= preview.at && proposal.kind !== "script-add-page" && proposal.kind !== "script-insert-page");
+      const proposal = {
+        proposalId: newProposalId(),
+        deckId: deck.id,
+        pageId: pageIds[0],
+        page: preview.pages[0].page,
+        pageIds,
+        kind: "script-insert-page",
+        field: "insert-page",
+        at: preview.at,
+        shift: preview.shift,
+        before: "",
+        after: preview.text,
+        // 和追加页一致：插页没有「单字段纯值」，value 留空。
+        value: "",
+        pages: preview.pages,
+        renumberedPages: preview.renumberedPages,
+        pageCountBefore: deck.slides.length,
+        pageCountAfter: preview.pageCount,
+        diff,
+        reason: String(args.reason ?? ""),
+        status: "waiting-user",
+        createdAt: proposalNow(),
+        sessionId: sessionIdOf(exec),
+        ...(duplicateNotes.length ? { duplicatePages: duplicateNotes } : {}),
+      };
+      workspace.saveProposal(proposal);
+
+      const task = store.taskCreate({
+        kind: "edit",
+        deckId: deck.id,
+        slideIds: pageIds,
+        actor: "agent",
+        sessionId: proposal.sessionId,
+        inputRefs: [`script:${deck.id}#insert-page@P${String(preview.at).padStart(2, "0")}`],
+      });
+      store.taskUpdate(task.taskId, { status: "running", actor: "agent" });
+      store.taskUpdate(task.taskId, {
+        status: "waiting-user",
+        actor: "agent",
+        inputRefs: [`script:${deck.id}#insert-page@P${String(preview.at).padStart(2, "0")}`, `proposal:${proposal.proposalId}`],
+      });
+      store.recordEvent({
+        type: "deck.edit",
+        sessionId: proposal.sessionId,
+        taskId: task.taskId,
+        deckId: deck.id,
+        slideIds: pageIds,
+        actor: "agent",
+        status: "waiting-user",
+        payload: { proposalId: proposal.proposalId, field: "insert-page", at: preview.at, shift: preview.shift, reason: proposal.reason, diff, pages: preview.pages.map((spec) => spec.page) },
+      });
+
+      return {
+        proposalId: proposal.proposalId,
+        taskId: task.taskId,
+        deckId: deck.id,
+        slideIds: pageIds,
+        status: "waiting-user",
+        pageCount: preview.pageCount,
+        at: preview.at,
+        shift: preview.shift,
+        diff,
+        text:
+          `插入页提案 ${proposal.proposalId} 已进入 waiting-user：${deck.slides.length} 页 → ${preview.pageCount} 页` +
+          `（插到 P${String(preview.at).padStart(2, "0")} 之前，新增 ${pageIds.join(" / ")}；${renumberLabel}）。\n` +
+          `${duplicateNotes.length ? `\n⚠ 稿子里已经有同标题的页：${duplicateNotes.join(" / ")}。插页是新增副本、不会替换或移动它们——确认后会出现两套内容。如果目的是把已有页搬到这里，请先跟用户说明当前还不能移动/删页，不要直接插重复页。\n` : ""}` +
+          `确认后会迁移 slides/<pageId>/versions 目录——**已出的图跟着各自内容走，不需要重出整份**。` +
+          `${pendingShifted.length ? `\n另有 ${pendingShifted.length} 条待确认提案落在后移页上（${pendingShifted.map((item) => item.pageId).join(" / ")}），确认时会自动改到新页号。` : ""}` +
+          `\n\n${diff || "(无文本差异)"}\n` +
+          `请在 Chat 里确认；确认后才写 script revision + manifest + 目录迁移。`,
+      };
+    }),
+  });
+
   // ── 4. deck_revision_confirm ───────────────────────────────────────────────
   tools.push({
     name: "deck_revision_confirm",
@@ -1065,7 +1228,7 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
       "对 waiting-user 的提案执行用户裁决。confirmed=true 表示用户已确认（Chat 明确同意或工作台点了确认）；" +
       "confirmationQuote 引用用户原话最好，没带也能落版（会标 quoteMissing 留痕）——不要为了凑原话反复问用户；" +
       "写入 script revision（copy-on-write，不覆盖旧版）并同步 manifest。" +
-      "确认支持脚本字段（含 body 正文）与 visualBrief / 追加页；confirmed=false 记为用户驳回。",
+      "确认支持脚本字段（含 body 正文）与 visualBrief / 追加页 / 插页；confirmed=false 记为用户驳回。",
     parameters: {
       type: "object",
       properties: {
@@ -3401,7 +3564,9 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
           }
         }
         if (!sourceFile) {
-          const baseline = adapter.sourceImages?.()[slide.id];
+          // F-208：插过页的 deck 按原始源页取 baseline（sourcePage），否则会盖到源里同号那页的图上。
+          const sourceKey = workspace.sourcePageKey(deckId, slide.id);
+          const baseline = sourceKey ? adapter.sourceImages?.()[sourceKey] : null;
           if (baseline?.ext === ".png") {
             sourceFile = baseline.path;
             sourceRevision = "source";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-deck-studio",
-  "version": "0.2.27",
+  "version": "0.2.28",
   "description": "Deckline：DSH 的 image deck / PPT 工作台插件——原生 Chat + 整页图片 deck 工作区 + 设计风格库；用对话做 PPT、按页出图、版本可追踪、导出 PDF/PPTX。",
   "icon": "assets/icon.svg",
   "homepage": "https://github.com/yuna78/dsh-deck-studio#readme",