dsh-plugin-deck-studio 0.2.27 → 0.2.28

package/client.js

@@ -619,6 +619,47 @@ div[data-sidebar-collapsed]{grid-template-columns:0px minmax(0px,1fr) 0px!import
         );
       }
 
+      /**
+       * 会话行尾悬停按钮（`sidebar.workspaces.session.row.action`）：
+       * 点一下就把它绑定的 deck / 设计在 Deckline 打开——比"先点行开对话、再点 ⋯ 菜单"少两步。
+       * 宿主会拦掉点击不让它触发行选中，所以这里也显式 stopPropagation。
+       */
+      function OpenDecklineRowAction({ sessionId }) {
+        const [busy, setBusy] = React.useState(false);
+        const onOpen = (event) => {
+          event?.preventDefault?.();
+          event?.stopPropagation?.();
+          if (busy) return;
+          setBusy(true);
+          void openSessionInWorkbench(sessionId).finally(() => setBusy(false));
+        };
+        return h(
+          "button",
+          {
+            type: "button",
+            title: "在 Deckline 打开",
+            "aria-label": "在 Deckline 打开",
+            "data-deck-studio-row-open": "",
+            disabled: busy,
+            onClick: onOpen,
+            style: {
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center",
+              width: 22,
+              height: 22,
+              padding: 0,
+              border: 0,
+              background: "transparent",
+              color: "var(--dsw-alias-label-secondary, var(--dsw-alias-label-primary))",
+              borderRadius: "var(--dsw-radius-sm)",
+              cursor: busy ? "default" : "pointer",
+            },
+          },
+          h(DeckGlyph, { size: 14 }),
+        );
+      }
+
       const currentSessionId = () => {
         try {
           const raw = window.localStorage.getItem("dsh.sessions.current");
@@ -673,14 +714,23 @@ div[data-sidebar-collapsed]{grid-template-columns:0px minmax(0px,1fr) 0px!import
 
       /* 工作台 iframe → 宿主：把一条完整 prompt 发进当前会话的原生 Chat。 */
       ctx.effect(() => {
-        const sendToChat = async (text) => {
-          const sessionId = currentSessionId();
-          if (!sessionId) throw new Error("no current session");
-          return sendToSession(sessionId, text);
+        /**
+         * F-211：优先用工作台指定的会话。
+         *
+         * 以前只按 `dsh.sessions.current` 发——那是宿主主区（or web iframe）的当前会话。
+         * 桌面 Dock 模式（F-202B / ADR-0027）下，工作台左栏显示的是 `dsh-deck-studio:chat-session`
+         * 报上来的 deck 绑定会话，两者经常不是同一个：指令落进隔壁会话，界面却提示已发送。
+         * 2026-11-07 真机：指令进了未绑定的 session-a274e455，绑定的 session-e2eda8c9 什么都没收到。
+         */
+        const sendToChat = async (text, sessionId) => {
+          const target = String(sessionId ?? "").trim() || currentSessionId();
+          if (!target) throw new Error("no current session");
+          return sendToSession(target, text);
         };
         const onMessage = (event) => {
           if (event?.data?.type !== "dsh-deck-studio:prompt") return;
           const text = String(event.data.text ?? "");
+          const sessionId = String(event.data.sessionId ?? "").trim();
           if (!text.trim()) return;
           const reply = (payload) => {
             try {
@@ -689,8 +739,8 @@ div[data-sidebar-collapsed]{grid-template-columns:0px minmax(0px,1fr) 0px!import
               /* 跨窗口失效就忽略 */
             }
           };
-          sendToChat(text)
-            .then((sessionId) => reply({ ok: true, sessionId }))
+          sendToChat(text, sessionId)
+            .then((sentTo) => reply({ ok: true, sessionId: sentTo }))
             .catch((error) => {
               ctx.logger?.warn?.("deck-studio: prompt bridge failed", error);
               reply({ ok: false, reason: String(error?.message ?? error) });
@@ -732,10 +782,53 @@ div[data-sidebar-collapsed]{grid-template-columns:0px minmax(0px,1fr) 0px!import
           .filter((item) => normalize(path) === normalize(item.path) || normalize(path).startsWith(`${normalize(item.path)}/`))
           .sort((a, b) => b.path.length - a.path.length)[0];
         const register = async (path) => {
-          const workspace = await workspaces.create({ path });
-          if (!workspace?.workspaceId) throw new Error("工作区创建未返回 workspaceId");
-          return workspace.workspaceId;
+          // 0.2.28：`workspaces.create()` 的成功返回值是 `{ workspace, created }`（服务端 HTTP 契约就是
+          // `workspaceView(...)` 包一层）；以前直接读 `.workspaceId`，永远 undefined → 抛错 → 建会话失败。
+          // html-deck 那边一直是 `result.workspace ?? result` 再取 `workspaceId ?? id`，所以它没这问题。
+          const created = await workspaces.create({ path });
+          const row = created?.workspace ?? created;
+          const workspaceId = row?.workspaceId ?? row?.id;
+          if (!workspaceId) throw new Error("工作区创建未返回 workspaceId（返回：" + JSON.stringify(created)?.slice(0, 200) + "）");
+          return workspaceId;
+        };
+        const title = String(data.title ?? "").trim().slice(0, 60);
+        const desiredName = title ? `Deckline · ${title}` : "";
+        /**
+         * 给「deck 自己的工作区」命名（F-210）：侧栏要能一眼看出这是哪本 deck。
+         * 重名 / rename 失败只影响侧栏文案，绝不能让建会话失败（html-deck 同款容错）。
+         */
+        const nameDeckWorkspace = async (workspaceId) => {
+          if (!desiredName || typeof workspaces.rename !== "function") return workspaceId;
+          try {
+            const snapshot = workspaces.list?.getSnapshot?.();
+            const rows = snapshot?.phase === "ready" ? snapshot.items ?? [] : items;
+            const taken = rows.some((item) => String(item.name ?? "") === desiredName && (item.workspaceId ?? item.id) !== workspaceId);
+            if (!taken) await workspaces.rename(workspaceId, desiredName);
+          } catch {
+            /* 名字冲突 / 权限问题：会话照建 */
+          }
+          return workspaceId;
         };
+        /**
+         * 0.2.16 / F-210：**deck 自己的项目目录排第一**。
+         * 以前它排在 cwd / sourceRoot 之后，源目录挂在一个更大的工作区下时永远轮不到它——
+         * 于是会话落进「sharing」这种大工作区，侧栏永远看不到以 deck 命名的项目。
+         */
+        const projectPath = String(data.sessionWorkspacePath ?? "").trim();
+        if (projectPath) {
+          const exact = items.find((item) => normalize(item.path) === normalize(projectPath));
+          const exactId = exact?.workspaceId ?? exact?.id;
+          if (exactId) return nameDeckWorkspace(exactId);
+          try {
+            return nameDeckWorkspace(await register(projectPath));
+          } catch (error) {
+            // 建不了（路径非法 / 落在别的工作区里 / 权限）：退回父工作区，至少别让「开对话」失败。
+            const parent = containing(projectPath);
+            ctx.logger?.warn?.(`deck-studio: 建 deck 工作区失败（${projectPath}）：${error?.message ?? error}${parent ? "；退回父工作区" : ""}`);
+            if (parent?.workspaceId ?? parent?.id) return parent.workspaceId ?? parent.id;
+            throw error;
+          }
+        }
         const configured = String(data.workspacePath ?? "").trim();
         if (configured) return register(configured);
         const cwd = String(data.cwd ?? "").trim();
@@ -754,28 +847,6 @@ div[data-sidebar-collapsed]{grid-template-columns:0px minmax(0px,1fr) 0px!import
         const sourceRoot = String(data.sourceRoot ?? "").trim();
         const sourceWorkspace = sourceRoot ? containing(sourceRoot) : null;
         if (sourceWorkspace) return sourceWorkspace.workspaceId;
-        /**
-         * 0.2.16：deck 自己的项目目录（工作台载荷里的 sessionWorkspacePath）。
-         * 桌面宿主里上面几级会全落空——cwd 是 profile 目录被守卫挡掉、源目录还没登记成工作区、
-         * 客户端 workspaces 服务也没有 initializeDefault——结果是「从没有会话的 deck」
-         * 永远建不出会话、也就永远绑不上（点了 ＋ 没反应）。这里按 deck 项目目录建/复用工作区，
-         * 保证每本 deck 都有落点；工作区名只是侧栏文案，命名失败不影响建会话。
-         */
-        const projectPath = String(data.sessionWorkspacePath ?? "").trim();
-        if (projectPath) {
-          const existing = containing(projectPath);
-          if (existing) return existing.workspaceId;
-          const projectWorkspaceId = await register(projectPath);
-          const title = String(data.title ?? "").trim().slice(0, 60);
-          if (title && typeof workspaces.rename === "function") {
-            try {
-              await workspaces.rename(projectWorkspaceId, `Deckline · ${title}`);
-            } catch {
-              /* 工作区重名等失败只影响侧栏文案，会话照建 */
-            }
-          }
-          return projectWorkspaceId;
-        }
         const fallback = await workspaces.initializeDefault?.();
         if (fallback?.workspaceId) return fallback.workspaceId;
         throw new Error("无法确定启动工作区，未创建会话；请配置 workspacePath 后重试");
@@ -1033,6 +1104,32 @@ div[data-sidebar-collapsed]{grid-template-columns:0px minmax(0px,1fr) 0px!import
 
         // 唯一入口：侧栏面板行「Deckline」（与 plugins / schedules 等插件同一种形态，带图标）；
         // → 对话用工作台里的「← 回到对话」。
+        // 会话行「⋯」菜单 + 行尾悬停按钮：**不放进 hasRightbar / selectPanel 分支**。
+        // 这两个 slot 是宿主可选契约（旧 DSH 没有就只记一条警告）；但一旦被右栏服务门禁包住，
+        // 桌面宿主没加载 sidebar-right 时菜单会整个消失——用户看到的效果就是「点会话没反应」。
+        try {
+          ctx.effect(
+            () => ctx.slots.inject("sidebar.workspaces.session.menu.item", () =>
+              ctx.slots.register({
+                name: "sidebar.workspaces.session.menu.item",
+                id: "dsh-plugin-deck-studio.open-binding",
+                order: 150,
+              }, OpenDecklineMenuItem)),
+            "deck-studio: session menu entry",
+          );
+          ctx.effect(
+            () => ctx.slots.inject("sidebar.workspaces.session.row.action", () =>
+              ctx.slots.register({
+                name: "sidebar.workspaces.session.row.action",
+                id: "dsh-plugin-deck-studio.open-binding-row",
+                order: 150,
+              }, OpenDecklineRowAction)),
+            "deck-studio: session row action",
+          );
+        } catch (error) {
+          ctx.logger?.warn?.(`deck-studio: session menu slot unavailable: ${error?.message ?? error}`);
+        }
+
         if (hasRightbar) {
           if (layout?.selectPanel) {
             ctx.effect(
@@ -1040,21 +1137,6 @@ div[data-sidebar-collapsed]{grid-template-columns:0px minmax(0px,1fr) 0px!import
                 ctx.slots.register({ name: "sidebar.panellist", id: WORKBENCH_KEY, order: 46, label: () => "Deckline" }, DeckGlyph)),
               "deck-studio: workbench sidebar entry",
             );
-            // 会话行「⋯」菜单：把当前会话绑定的 deck 在工作台里打开（未绑定给可见提示）。
-            // 该槽位是宿主可选契约，旧版本没有时只记一条警告，不能影响面板本身注册。
-            try {
-              ctx.effect(
-                () => ctx.slots.inject("sidebar.workspaces.session.menu.item", () =>
-                  ctx.slots.register({
-                    name: "sidebar.workspaces.session.menu.item",
-                    id: "dsh-plugin-deck-studio.open-binding",
-                    order: 150,
-                  }, OpenDecklineMenuItem)),
-                "deck-studio: session menu entry",
-              );
-            } catch (error) {
-              ctx.logger?.warn?.(`deck-studio: session menu slot unavailable: ${error?.message ?? error}`);
-            }
           }
           ctx.logger?.info?.("deck-studio client: workbench-only mode");
         } else {

package/cordis.example.yml

@@ -186,7 +186,12 @@
             - 新建 deck：按弹窗填的意图 / 参考资料直接开始，先出图也行。叙事主线写进 intent.md 的「故事线」段
               （deck_doc_update，docId=intent）；台账字段有依据才写，没依据列成问题问用户，不要停留补文档。
               资料 ≥5 份 / 很长时再用 deck_research_plan 分批，读到可引用事实顺手写进调研台账。
-            - 加页：deck_script_add_page（可一次多页，只追加到末尾），产出提案，确认后落版；
+            - 加页 / 插页：末尾加页用 deck_script_add_page（可一次多页，只追加到末尾）；任意位置插页用
+              deck_script_insert_page（deckId、at、pages[]、reason?），at = 插到第 N 页之前（1-based，
+              at = 当前页数 + 1 等价追加）。两者都只出提案，确认后落一条 revision：>= at 的页号整体后移，
+              manifest 的 slide id/order 同步重编号、slides/<pageId>/versions 目录整体 rename——已出的图跟着内容走，
+              不需要重出整份，也不要让用户手动搬页。用户要求插页时不要回答「没有插入工具 / 只能整份重出」；
+              at 越界、空 pages、一次插超过 20 页要如实报错（表格惯例的 script 暂不支持中间插页）。
               新页没有 brief 可以直接出草稿图，再决定要不要补写。
             - 交付：用户要交付时建议跑一次 deck_review 自查成品问题（P0 优先）；导出 / 交接前再补交接文档。
               出图不需要文档齐全，docs_check 的分数不影响渲染。

package/cordis.patch.yml

@@ -172,7 +172,12 @@
                 - 新建 deck：按弹窗填的意图 / 参考资料直接开始，先出图也行。叙事主线写进 intent.md 的「故事线」段
                   （deck_doc_update，docId=intent）；台账字段有依据才写，没依据列成问题问用户，不要停留补文档。
                   资料 ≥5 份 / 很长时再用 deck_research_plan 分批，读到可引用事实顺手写进调研台账。
-                - 加页：deck_script_add_page（可一次多页，只追加到末尾），产出提案，确认后落版；
+                - 加页 / 插页：末尾加页用 deck_script_add_page（可一次多页，只追加到末尾）；任意位置插页用
+                  deck_script_insert_page（deckId、at、pages[]、reason?），at = 插到第 N 页之前（1-based，
+                  at = 当前页数 + 1 等价追加）。两者都只出提案，确认后落一条 revision：>= at 的页号整体后移，
+                  manifest 的 slide id/order 同步重编号、slides/<pageId>/versions 目录整体 rename——已出的图跟着内容走，
+                  不需要重出整份，也不要让用户手动搬页。用户要求插页时不要回答「没有插入工具 / 只能整份重出」；
+                  at 越界、空 pages、一次插超过 20 页要如实报错（表格惯例的 script 暂不支持中间插页）。
                   新页没有 brief 可以直接出草稿图，再决定要不要补写。
                 - 交付：用户要交付时建议跑一次 deck_review 自查成品问题（P0 优先）；导出 / 交接前再补交接文档。
                   出图不需要文档齐全，docs_check 的分数不影响渲染。

package/index.js

@@ -36,7 +36,7 @@ import { appendSampleRecord, readSampleRecords, readStyleDefinition, writeStyleD
 import { resolveMediaFile, scanDesignStyles, scanResources } from "./lib/home-catalog.js";
 import { defaultSelection, renderModelPayload, resolveSelection } from "./lib/render-nodes.js";
 import { applyRenderSettings, readRenderSettings, renderSettingsPayload, saveRenderSettings } from "./lib/render-settings.js";
-import { buildPrompt, editEndpointFor, selectRenderer } from "./lib/render.js";
+import { buildPrompt, editEndpointFor, selectRenderer, stripVisualBriefScaffolding } from "./lib/render.js";
 import { PDF_IMPORT_MAX_PAGES, applyImportedTitles, buildImportNote, extractIntentFields, headingsAsTitles, listImportDir, normalizeDpi, rasterizePdfToPng, scriptPagesFromMarkdown, titleFromPdfName } from "./lib/pdf-import.js";
 import { readDeckBrief } from "./lib/deck-brief.js";
 import { detectProfileDir, installModeOf, isNewer, latestFromRegistry, repoLinksOf } from "./lib/update-check.js";
@@ -1416,8 +1416,12 @@ export function createService(config, logger, env = process.env) {
     for (const pageId of pageIds.slice(0, 6)) {
       const info = slideRenderInfo(deckId, pageId);
       if (!info) continue;
+      // F-208：源 baseline 图按 slide 的原始源页取（插页重编号后 pageId ≠ 源页号）。
+      const sourceKey = workspace.sourcePageKey(deckId, pageId);
       const sourcePath = info.fromSource
-        ? sourceImages[pageId]?.path
+        ? sourceKey
+          ? sourceImages[sourceKey]?.path
+          : null
         : join(workspace.slideDir(deckId, pageId), "versions", info.revision, `image${info.ext}`);
       if (!sourcePath || !existsSync(sourcePath)) continue;
       const ext = String(info.ext ?? "png").replace(/^\./, "");
@@ -1851,7 +1855,45 @@ export function createService(config, logger, env = process.env) {
   function pageForEdit(deckId, pageId) {
     const adapter = adapterOf(deckId);
     if (!adapter?.available()) return null;
-    return pageEditView(adapter, pageId);
+    // F-209：插页重编号后「本地页号 ≠ 源页号」（本地 p04 的源是 P02）。逐页微调必须按
+    // slide.sourcePage 读源，否则 Inspector 显示的是源里同号那页（用户看到的「4、5 是以前的 4、5」）。
+    const deck = workspace.manifest(deckId);
+    const normalized = String(pageId ?? "").trim();
+    const pageNo = Number(normalized.replace(/^p/i, ""));
+    const slide = (deck?.slides ?? []).find(
+      (item) => item.id === normalized || (Number.isFinite(pageNo) && pageNo > 0 && item.order === pageNo),
+    );
+    if (!slide) return pageEditView(adapter, pageId);
+    // 本机新建 deck（ADR-0022）：源 script.md 是本地页序的镜像，sourcePage 只是 baseline 映射残留，
+    // 用本地页号才对应「源里同一内容」那一节；受控客户源停在原始页序，必须用 sourcePage。
+    const sourcePage = localDeckIds().has(deckId) ? Number(slide.order) : workspace.sourcePageOf(deckId, slide.id);
+    if (sourcePage == null) {
+      const order = Number(slide.order) || null;
+      return {
+        page: order,
+        pageId: slide.id,
+        unsupported: true,
+        reason: `P${String(order ?? 0).padStart(2, "0")} 是插页新增的页，源 script.md 里没有对应分节；逐页微调只能改源里已有的页。要改这页请让 Agent 用 deck_script_propose_edit 提案。`,
+      };
+    }
+    const view = pageEditView(adapter, `p${String(sourcePage).padStart(2, "0")}`);
+    if (!view) return null;
+    // 源里其实没有这一页分节（例如插页新增页被记了 baseline 映射、或源后来少了页）：
+    // 别把 pageEditView 的「表格惯例」原因甩给用户，明确说是源里没有这一节。
+    if (view.unsupported) {
+      const rawScript = typeof adapter.readScriptRaw === "function" ? String(adapter.readScriptRaw() ?? "") : "";
+      const sectionExists = new RegExp(`^#{2,3}\\s*P0*${sourcePage}\\b`, "m").test(rawScript);
+      if (!sectionExists) {
+        return {
+          ...view,
+          page: Number(slide.order) || view.page,
+          pageId: slide.id,
+          sourcePage,
+          reason: `源 script.md 里没有 P${String(sourcePage).padStart(2, "0")} 分节（这页是插页新增或源已更新），逐页微调不可用；改稿请让 Agent 用 deck_script_propose_edit 提案。`,
+        };
+      }
+    }
+    return { ...view, page: Number(slide.order) || view.page, pageId: slide.id, sourcePage, sourcePageId: view.pageId };
   }
 
   /**
@@ -1861,7 +1903,7 @@ export function createService(config, logger, env = process.env) {
   function pagePrompt(deckId, pageId) {
     const adapter = adapterOf(deckId);
     if (!adapter?.available()) return null;
-    const deck = workspace.manifest(deckId);
+    const deck = workspace.manifest(deckId) ?? workspace.ensureDeck(adapter, { styleBrief: config.styleBrief });
     const normalized = String(pageId ?? "").trim();
     const slide = (deck?.slides ?? []).find((item) => item.id === normalized || `p${String(item.order).padStart(2, "0")}` === normalized);
     if (!slide) return null;
@@ -1894,30 +1936,53 @@ export function createService(config, logger, env = process.env) {
   function savePage(deckId, pageId, patch) {
     const adapter = adapterOf(deckId);
     if (!adapter?.available()) throw new Error(`deck 不可用：${deckId}`);
-    const page = Number(String(pageId).replace(/^p/i, ""));
+    // F-209：写源必须用「原始源页号」而不是本地页号——插页重编号后两者不再相等，
+    // 按本地页号写会把内容写进源里同号的另一页（绑定层事故的根因之一）。
+    const manifestNow = workspace.manifest(deckId) ?? workspace.ensureDeck(adapter, { styleBrief: config.styleBrief });
+    const normalized = String(pageId ?? "").trim();
+    const pageNo = Number(normalized.replace(/^p/i, ""));
+    const slide = (manifestNow?.slides ?? []).find(
+      (item) => item.id === normalized || (Number.isFinite(pageNo) && pageNo > 0 && item.order === pageNo),
+    );
+    if (!slide) throw new Error(`页不存在：${pageId}`);
+    // 本机 deck 的源是本地页序镜像 → 用本地页号；受控客户源 → 用原始源页（F-209）。
+    const sourcePage = localDeckIds().has(deckId) ? Number(slide.order) : workspace.sourcePageOf(deckId, slide.id);
+    if (sourcePage == null) {
+      throw new Error(`P${String(slide.order).padStart(2, "0")} 是插页新增的页，源 script.md 里没有对应分节，不能直接写回源（会写错页）。要改这页请让 Agent 用 deck_script_propose_edit 提案。`);
+    }
     const result = savePageEdit({
       sourceRoot: adapter.sourceRoot,
-      page,
+      page: sourcePage,
       title: patch?.title ?? "",
       subtitle: patch?.subtitle ?? "",
       body: patch?.body ?? "",
       prompt: typeof patch?.prompt === "string" ? patch.prompt : undefined,
     });
     const deck = workspace.ensureDeck(adapter, { styleBrief: config.styleBrief, forceRebuild: true });
-    const message = `deck(${deckId})：微调 P${String(page).padStart(2, "0")}${patch?.title ? `「${String(patch.title).slice(0, 30)}」` : ""}`;
+    // 出图 prompt 来自 manifest.visualBrief；Inspector 改了提示词就要同步过去，否则「保存后重出」还是旧 prompt
+    // （forceRebuild 会保留本地 visualBrief，源 prompts 的改动进不来）。
+    if (typeof patch?.prompt === "string") {
+      const target = (deck?.slides ?? []).find((item) => item.id === slide.id);
+      if (target) {
+        target.visualBrief = stripVisualBriefScaffolding(patch.prompt);
+        workspace.saveManifest(deck);
+      }
+    }
+    const message = `deck(${deckId})：微调 P${String(slide.order).padStart(2, "0")}${patch?.title ? `「${String(patch.title).slice(0, 30)}」` : ""}`;
     const git = commitFiles({ dir: adapter.sourceRoot, files: result.files, message });
     store.recordEvent({
       type: "deck.script.save",
       deckId,
-      slideIds: [result.pageId],
+      slideIds: [slide.id],
       actor: "user",
       status: git.ok ? "succeeded" : "saved",
-      payload: { page: result.page, files: result.files, commit: git.commit ?? null, gitError: git.error ?? null },
+      payload: { page: Number(slide.order) || result.page, sourcePage, files: result.files, commit: git.commit ?? null, gitError: git.error ?? null },
     });
     return {
       deckId,
-      page: result.page,
-      pageId: result.pageId,
+      page: Number(slide.order) || result.page,
+      pageId: slide.id,
+      sourcePage,
       files: result.files.map((file) => file.replace(`${adapter.sourceRoot}/`, "")),
       commit: git.commit ?? null,
       gitOk: git.ok,
@@ -2029,7 +2094,9 @@ export function createService(config, logger, env = process.env) {
       const pageId = slide.id;
       const render = slideRenderInfo(deckId, pageId);
       const localFile = render ? assetFile(deckId, pageId, render.revision) : null;
-      const sourceFile = adapterOf(deckId)?.sourceImages?.()?.[pageId]?.path ?? null;
+      // F-208：源 baseline 图按原始源页取（插页重编号不影响）；插页新增的页没有源图。
+      const sourceKey = workspace.sourcePageKey(deckId, pageId);
+      const sourceFile = (sourceKey ? adapterOf(deckId)?.sourceImages?.()?.[sourceKey]?.path : null) ?? null;
       const file = localFile ?? sourceFile;
       if (!file) continue;
       const ext = extname(file).toLowerCase();
@@ -2339,15 +2406,21 @@ export function createService(config, logger, env = process.env) {
       }
     }
     // 2) 源里已出好的整页图作为 baseline（只读引用，不复制、不占双份空间）
-    const source = adapterOf(deckId)?.sourceImages?.()[pageId];
+    // F-208：插过页的 deck 按 slide.sourcePage（原始源页）取；插页重编号后若还按新 pageId 抓源图，
+    // 会把源里同号那页（别人的图）挂到这页上。
+    const sourceKey = workspace.sourcePageKey(deckId, pageId);
+    const source = sourceKey ? adapterOf(deckId)?.sourceImages?.()[sourceKey] : null;
     if (source) {
       return {
         revision: "source",
         ext: source.ext,
-        url: `${ROUTES.asset}?deckId=${encodeURIComponent(deckId)}&pageId=${encodeURIComponent(pageId)}&rev=source`,
+        // F-209：URL 带上解析后的源页（&sourcePage=p02）。插页前后 rev=source 的 URL 原本完全一样，
+        // 旧实例/旧 payload/旧缓存出的图和新的无法区分；带上源页后一眼能看出「这页取的是哪张源图」。
+        url: `${ROUTES.asset}?deckId=${encodeURIComponent(deckId)}&pageId=${encodeURIComponent(pageId)}&rev=source&sourcePage=${encodeURIComponent(sourceKey ?? "")}`,
         sizeBytes: source.sizeBytes,
         renderedAt: statSync(source.path).mtime.toISOString(),
         fromSource: true,
+        sourcePage: sourceKey ?? null,
       };
     }
     return null;
@@ -2389,7 +2462,8 @@ export function createService(config, logger, env = process.env) {
   /** 资产读取：只允许 versions/vNNN/image.<ext> 或源 baseline（rev=source），防目录穿越。 */
   function assetFile(deckId, pageId, revision) {
     if (revision === "source") {
-      const image = adapterOf(deckId)?.sourceImages?.()[pageId];
+      const sourceKey = workspace.sourcePageKey(deckId, pageId);
+      const image = sourceKey ? adapterOf(deckId)?.sourceImages?.()[sourceKey] : null;
       return image && existsSync(image.path) ? image.path : null;
     }
     if (!/^v\d+$/.test(revision ?? "")) return null;
@@ -2480,6 +2554,9 @@ export function createService(config, logger, env = process.env) {
           // ensureDeck 幂等：manifest 缺失时初始化；源变了且本地还没改过时按源刷新派生字段。
           deck = workspace.ensureDeck(adapter, { styleBrief: config.styleBrief });
         } catch (error) {
+          // F-209：manifest 损坏时不能吞掉错误退回「空 deck」（看起来像 0 页 / 像源 deck 丢了）。
+          // 明确抛给调用方（工作台报错、Agent 工具报错），让人先备份/修复 deck.json。
+          if (/manifest 损坏/.test(String(error?.message ?? error))) throw error;
           logger?.warn?.(`${name}: ensureDeck(${activeId}) 失败：${error?.message ?? error}`);
           deck = workspace.manifest(activeId);
         }
@@ -2513,6 +2590,8 @@ export function createService(config, logger, env = process.env) {
           visualBrief: slide.visualBrief ?? "",
           // F-114：这条画面要求写于哪个关联风格（换风格时 UI 标「旧风格 brief」）。
           visualBriefDesign: slide.visualBriefDesign ?? null,
+          // F-209：把「这页对应源 deck 的哪一页」暴露给工作台，插页重编号后排查错位不用猜。
+          sourcePage: workspace.sourcePageOf(activeId, slide.id),
           render: slideRenderInfo(activeId, slide.id),
         })),
         appendix: deck?.appendix ?? { count: view?.appendixCount ?? 0, rows: view?.appendixRows ?? [] },

package/lib/deck-docs.js

@@ -27,6 +27,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statS
 import { join } from "node:path";
 
 import { parseFrontmatter } from "./source-adapter.js";
+import { slideSourcePage } from "./deck-workspace.js";
 
 /* ------------------------------------------------------------------ *
  * 文档规格
@@ -585,19 +586,23 @@ export function resolveDeckDocs({ adapter, deckDir, render = {}, revisions = [],
       // F-110：画面要求（visualBrief）住在工作副本 manifest 里，不是源 prompts/Pxx.txt。
       // 以前只数 prompts/ 文件，新建 deck 永远显示「提示词覆盖 0/10」，把 Agent 和人都误导成「不能出图」。
       const manifest = readManifestJson(deckDir);
-      const briefOf = (page) => {
-        const pageId = `p${String(page.page).padStart(2, "0")}`;
-        const slide = (manifest?.slides ?? []).find((item) => item.id === pageId);
-        return String(slide?.visualBrief ?? "").trim();
-      };
-      const covered = pages.filter((page) => {
-        const pageId = `p${String(page.page).padStart(2, "0")}`;
-        const brief = briefOf(page);
-        const fieldPrompt = String(page.fields?.["提示词"] ?? "").trim();
-        return (brief && !isPlaceholder(brief)) || promptIds.includes(pageId) || (fieldPrompt && !isPlaceholder(fieldPrompt));
-      });
+      const manifestSlides = Array.isArray(manifest?.slides) ? manifest.slides : [];
+      // F-209：页数 / 画面要求覆盖率按 manifest 算（manifest 才有插页/追加后的完整页序）。
+      const covered = manifestSlides.length
+        ? manifestSlides.filter((slide) => {
+            const brief = String(slide.visualBrief ?? "").trim();
+            const sourcePage = slideSourcePage(slide);
+            const sourcePrompt = sourcePage != null ? prompts[`p${String(sourcePage).padStart(2, "0")}`] : "";
+            return (brief && !isPlaceholder(brief)) || (sourcePrompt && !isPlaceholder(sourcePrompt));
+          })
+        : pages.filter((page) => {
+            const pageId = `p${String(page.page).padStart(2, "0")}`;
+            const brief = String(manifest?.slides?.find((item) => item.id === pageId)?.visualBrief ?? "").trim();
+            const fieldPrompt = String(page.fields?.["提示词"] ?? "").trim();
+            return (brief && !isPlaceholder(brief)) || promptIds.includes(pageId) || (fieldPrompt && !isPlaceholder(fieldPrompt));
+          });
       doc.facts = {
-        pageCount: pages.length,
+        pageCount: manifestSlides.length || pages.length,
         promptCount: promptIds.length,
         promptCoverage: covered.length,
         // 故事线概览并入脚本页：分段表从 script 的 `## 段落 / 页码 / 任务` 解析，零副本。
@@ -867,24 +872,49 @@ export function readDeckDoc({ adapter, deckDir, docId, file = "", render = {}, r
     parsed.fields = doc.facts.fields;
     parsed.derived = doc.facts.derived;
   } else if (docId === "script") {
-    parsed.pages = pages.map((page) => {
-      const pageId = `p${String(page.page).padStart(2, "0")}`;
+    // F-209：页列表以 **manifest** 为准。插页/追加后的本地页在源 script 里可能没有对应分节
+    // （或源还停在原始页序）；按源 storyPages 枚举会缺页、串位（实测 25 页 deck 只显示 21 张卡）。
+    const manifestSlides = Array.isArray(readManifestJson(deckDir)?.slides) ? readManifestJson(deckDir).slides : [];
+    const sourceRowByPage = new Map(pages.map((page) => [page.page, page]));
+    const fromManifest = (slide) => {
+      const sourcePage = slideSourcePage(slide);
+      const row = sourcePage != null ? sourceRowByPage.get(sourcePage) : null;
+      const pageNo = Number(slide.order) || Number(String(slide.id ?? "").replace(/^p/i, "")) || 0;
+      const pageId = `p${String(pageNo).padStart(2, "0")}`;
       return {
         id: pageId,
-        page: page.page,
-        title: page.title,
-        subtitle: page.question,
-        claim: page.claim,
-        // F-108：正文既可能是 **正文** 字段行，也可能是标题行以下的散段；两处都取，
-        // 否则脚本页永远显示「（这页没有正文）」，用户在 UI 里看不到 Agent 写的内容。
-        content: [page.fields?.["正文"], page.content]
+        page: pageNo,
+        title: slide.title ?? row?.title ?? "",
+        subtitle: slide.question ?? row?.question ?? "",
+        claim: slide.claim ?? row?.claim ?? "",
+        // F-108：正文既可能是 manifest.body，也可能是源里 **正文** 字段 / 标题行以下散段。
+        content: [slide.body, row?.fields?.["正文"], row?.content]
           .map((part) => String(part ?? "").trim())
           .filter(Boolean)
           .join("\n\n"),
-        prompt: prompts[pageId] || page.fields?.["提示词"] || "",
-        source: page.source,
+        // 画面要求住在 manifest.visualBrief（F-110）；源 prompts 只作兜底（按原始源页取）。
+        prompt: String(slide.visualBrief ?? "").trim() || (sourcePage != null ? prompts[`p${String(sourcePage).padStart(2, "0")}`] : "") || row?.fields?.["提示词"] || "",
+        source: slide.source ?? row?.source ?? "manifest",
       };
-    });
+    };
+    parsed.pages = manifestSlides.length
+      ? manifestSlides.slice().sort((a, b) => (a.order ?? 0) - (b.order ?? 0)).map(fromManifest)
+      : pages.map((page) => {
+          const pageId = `p${String(page.page).padStart(2, "0")}`;
+          return {
+            id: pageId,
+            page: page.page,
+            title: page.title,
+            subtitle: page.question,
+            claim: page.claim,
+            content: [page.fields?.["正文"], page.content]
+              .map((part) => String(part ?? "").trim())
+              .filter(Boolean)
+              .join("\n\n"),
+            prompt: prompts[pageId] || page.fields?.["提示词"] || "",
+            source: page.source,
+          };
+        });
     parsed.segments = doc.facts.segments ?? [];
   } else if (docId === "design") {
     parsed.rules = doc.facts.rules;