dsh-plugin-deck-studio 0.2.8 → 0.2.9

package/index.js

@@ -11,7 +11,8 @@
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { execFile } from "node:child_process";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { PLUGIN_DIR, mergeConfig, repoRootFrom } from "./lib/config.js";
 import { createRuntimeStore } from "./lib/store.js";
 import { createDeckWorkspace, scriptSectionRange } from "./lib/deck-workspace.js";
@@ -33,7 +34,26 @@ 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 { editEndpointFor, selectRenderer } from "./lib/render.js";
+import { buildPrompt, editEndpointFor, selectRenderer } from "./lib/render.js";
+import { readDeckBrief } from "./lib/deck-brief.js";
+import { detectProfileDir, installModeOf, isNewer, latestFromRegistry, repoLinksOf } from "./lib/update-check.js";
+
+/** 跑一个外部命令（异步、带超时、合并 stdout/stderr；失败时把输出带进错误信息）。 */
+function runCommand(command, args, { cwd = "", timeoutMs = 120000 } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, { cwd: cwd || undefined, timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024, env: process.env }, (error, stdout, stderr) => {
+      const output = `${stdout ?? ""}${stderr ?? ""}`.trim();
+      if (error) {
+        const failure = new Error(`${command} ${args.join(" ")} 失败：${error.message}${output ? `
+${output.slice(-2000)}` : ""}`);
+        failure.output = output;
+        reject(failure);
+        return;
+      }
+      resolve(output);
+    });
+  });
+}
 
 /** 稳定 Cordis 插件名。 */
 export const name = "deck-studio";
@@ -51,6 +71,7 @@ export const ROUTES = {
   docfile: "/api/deck-studio.docfile",
   export: "/api/deck-studio.export",
   pageEdit: "/api/deck-studio.page-edit",
+  pagePrompt: "/api/deck-studio.page-prompt",
   pageSave: "/api/deck-studio.page-save",
   media: "/api/deck-studio.media",
   renderModel: "/api/deck-studio.render-model",
@@ -78,6 +99,9 @@ export const ROUTES = {
   manual: "/api/deck-studio.manual",
   manualDoc: "/api/deck-studio.manual-doc",
   docsAsset: "/api/deck-studio.docs-asset",
+  // F-188：顶栏「更新」按钮——查 npm 最新版 / 一键更新到最新版（只在 npm 安装模式下执行）
+  updateCheck: "/api/deck-studio.update-check",
+  update: "/api/deck-studio.update",
 };
 
 /** 出图资产 MIME（image deck 只有图片；svg 仅 fake 测试用）。 */
@@ -198,6 +222,117 @@ function pluginVersion() {
   return versionCache;
 }
 
+  /** 插件自己的 package.json（版本 / 仓库链接来源；只读一次）。 */
+  let pluginMetaCache = null;
+  function pluginMeta() {
+    if (pluginMetaCache) return pluginMetaCache;
+    let pkg = {};
+    try {
+      pkg = JSON.parse(readFileSync(join(PLUGIN_DIR, "package.json"), "utf8"));
+    } catch {
+      pkg = {};
+    }
+    pluginMetaCache = {
+      name: String(pkg.name ?? "dsh-plugin-deck-studio"),
+      version: String(pkg.version ?? pluginVersion()),
+      links: repoLinksOf(pkg),
+    };
+    return pluginMetaCache;
+  }
+
+  /** 本机 profile 目录：先按插件真实路径反推（npm 布局），再退回 DSH 注入的 env。 */
+  function profileDirHint() {
+    const env = typeof process !== "undefined" ? process.env : {};
+    const meta = pluginMeta();
+    const found = detectProfileDir({ pluginDir: PLUGIN_DIR, packageName: meta.name, env });
+    if (found) return found;
+    const home = env.DSH_HOME ? String(env.DSH_HOME) : "";
+    const profile = env.DSH_PROFILE ? String(env.DSH_PROFILE) : "";
+    return home && profile ? join(home, "profiles", profile) : "";
+  }
+
+  /** 更新相关的静态信息（不发网络请求；workbench 首屏用）。 */
+  function updateBrief() {
+    const meta = pluginMeta();
+    const install = installModeOf({ profileDir: profileDirHint(), packageName: meta.name });
+    const env = typeof process !== "undefined" ? process.env : {};
+    return {
+      currentVersion: meta.version,
+      installMode: install.mode,
+      installSpec: install.spec,
+      installReason: install.reason,
+      profile: (() => {
+        const dir = profileDirHint();
+        return dir ? basename(dir) : String(env.DSH_PROFILE ?? "");
+      })(),
+      repo: meta.links.repo,
+      issues: meta.links.issues,
+      suggest: meta.links.suggest,
+      registry: `https://registry.npmjs.org/${encodeURIComponent(meta.name)}`,
+    };
+  }
+
+  /** 查 npm 上的最新版本（6s 超时；离线 / 超时不抛，只在 payload 里报错）。 */
+  async function updateStatus() {
+    const brief = updateBrief();
+    const payload = { ...brief, latestVersion: "", hasUpdate: false, checkedAt: new Date().toISOString(), error: "" };
+    try {
+      const res = await fetch(`${brief.registry}/latest`, {
+        headers: { accept: "application/json" },
+        signal: AbortSignal.timeout(12000),
+      });
+      if (!res.ok) throw new Error(`registry HTTP ${res.status}`);
+      const latest = latestFromRegistry(await res.json());
+      if (!latest) throw new Error("registry 返回里没有 latest 版本");
+      payload.latestVersion = latest;
+      payload.hasUpdate = isNewer(latest, brief.currentVersion);
+      payload.command = brief.installMode === "npm"
+        ? `dsh plugin --profile ${brief.profile || "<profile>"} add ${pluginMeta().name}@${latest}`
+        : "";
+      if (brief.installMode === "linked") payload.note = "本机是开发链接安装，更新走仓库（git pull）；界面不执行 pnpm。";
+    } catch (error) {
+      const message = String(error?.message ?? error);
+      const timedOut = error?.name === "TimeoutError" || /abort|timeout/i.test(message);
+      payload.error = timedOut
+        ? "检查更新超时：连不上 npm registry（网络 / 代理问题），可以直接用命令手动更新。"
+        : `检查更新失败：${message}`;
+    }
+    return payload;
+  }
+
+  /** 一键更新：npm 安装模式下在 profile 目录跑 pnpm add <name>@<latest>（超时 240s）。 */
+  async function runSelfUpdate() {
+    const brief = updateBrief();
+    if (brief.installMode !== "npm") {
+      throw new Error(
+        brief.installMode === "linked"
+          ? "本机是开发链接安装（link:/file:），界面不执行更新；请在仓库里 git pull 后重启 DSH。"
+          : "没识别出 profile 的安装方式，无法自动更新；请手动执行 dsh plugin --profile <profile> add dsh-plugin-deck-studio@latest。",
+      );
+    }
+    const status = await updateStatus();
+    if (status.error) throw new Error(status.error);
+    if (!status.latestVersion) throw new Error("没查到 npm 上的最新版本");
+    const target = `${pluginMeta().name}@${status.latestVersion}`;
+    const output = await runCommand("pnpm", ["add", target], { cwd: brief.profile, timeoutMs: 240000 });
+    store.recordEvent({
+      type: "plugin.update",
+      deckId: "",
+      actor: "user",
+      status: "succeeded",
+      payload: { from: brief.currentVersion, to: status.latestVersion, target },
+    });
+    return {
+      ok: true,
+      from: brief.currentVersion,
+      to: status.latestVersion,
+      target,
+      restarted: false,
+      restartHint: "更新已写入 profile，重启 DSH 后生效（当前进程仍是旧版本）。",
+      output,
+    };
+  }
+
 function json(payload, status = 200) {
   return Response.json(payload, { status, headers: { "cache-control": "no-store" } });
 }
@@ -1464,6 +1599,39 @@ export function createService(config, logger, env = process.env) {
     return pageEditView(adapter, pageId);
   }
 
+  /**
+   * F-189：某页「拼装后的完整出图 prompt」（只读，脚本页折叠展示用）。
+   * 与出图工具同一套拼装：deck 关联 design 的 styleBrief + 图上文字清单 + 讲述用正文 + 画面要求。
+   */
+  function pagePrompt(deckId, pageId) {
+    const adapter = adapterOf(deckId);
+    if (!adapter?.available()) return null;
+    const deck = workspace.manifest(deckId);
+    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;
+    let styleBrief = config.styleBrief;
+    const association = designRegistry.deckDesignFor(deckId);
+    const design = association?.designId ? designRegistry.findDesign(association.designId) : null;
+    if (design) {
+      let definition = null;
+      try {
+        definition = readStyleDefinition(adapter.sourceRoot, design.abbr ?? "", design);
+      } catch {
+        definition = null;
+      }
+      const brief = String(design.styleBrief || definition?.styleBrief || definition?.description || design.description || "").trim();
+      const constraints = String(design.constraints || definition?.constraints || "").trim();
+      if (brief) styleBrief = [brief, constraints ? `不要什么：${constraints}` : ""].filter(Boolean).join("\n");
+    }
+    return {
+      deckId,
+      pageId: slide.id,
+      design: design?.abbr ?? null,
+      prompt: buildPrompt(slide, styleBrief, { brief: readDeckBrief(adapter.sourceRoot) }),
+    };
+  }
+
   /**
    * 页面微调保存：写回源 script.md / prompts/Pnn.txt，重建 manifest，并自动 git 提交。
    * 这是唯一允许直接写源 deck 的动作（ADR-0006 的例外，见 ADR-0008）。
@@ -2105,6 +2273,8 @@ export function createService(config, logger, env = process.env) {
       designProjects: designProjects(),
       bindings: listBindings(),
       proposals: base.pendingProposals,
+      // F-188：顶栏「更新 / GitHub」按钮首屏数据（不打网络，检查更新另调 update-check）
+      update: updateBrief(),
     };
   }
 
@@ -2114,7 +2284,7 @@ export function createService(config, logger, env = process.env) {
     bootstrapDesignStyles();
   }
 
-  return { config, store, workspace, adapters, status, state, workbench, readManual, readUserName: () => config.userName, saveUserName, readDoc, docsAsset, setDeckDensity, renderSettings, saveRenderConfig, isLocalDeck: (deckId) => localDeckIds().has(String(deckId ?? "")), assetFile, slideRenderInfo, deckCoverUrl, deckRevisions, deckDocs, deckDoc, deckDocsScaffold, deckDocFile, pageForEdit, savePage, exportDeckFile, designSamples, sourceFile, homeCatalog, mediaFile, renderState, setRenderSelection, renderRuntime, createDeck, createDesign, createStyleFromDeck, designProjects, designStyle, updateDesignStyle, backfillStyleBriefs, listBindings, bindSession, unbindSession, deleteDesign, deleteDeck, setDeckDesign, addDesignSamples, seedStyleDesigns, renderStatus, exportHandoff }
+  return { config, store, workspace, adapters, status, state, workbench, readManual, readUserName: () => config.userName, saveUserName, readDoc, docsAsset, setDeckDensity, renderSettings, saveRenderConfig, isLocalDeck: (deckId) => localDeckIds().has(String(deckId ?? "")), assetFile, slideRenderInfo, deckCoverUrl, deckRevisions, deckDocs, deckDoc, deckDocsScaffold, deckDocFile, pageForEdit, pagePrompt, savePage, exportDeckFile, designSamples, sourceFile, homeCatalog, mediaFile, renderState, setRenderSelection, renderRuntime, createDeck, createDesign, createStyleFromDeck, designProjects, designStyle, updateDesignStyle, backfillStyleBriefs, listBindings, bindSession, unbindSession, deleteDesign, deleteDeck, setDeckDesign, addDesignSamples, seedStyleDesigns, renderStatus, exportHandoff, updateBrief, updateStatus, runSelfUpdate }
 }
 
 /**
@@ -2191,6 +2361,12 @@ export function apply(ctx, rawConfig) {
     return view ? json({ ok: true, ...view }) : json({ ok: false, error: { message: "page not found" } }, 404);
   });
 
+  registerRoute(ROUTES.pagePrompt, (request) => {
+    const url = new URL(request?.url ?? "/", "http://localhost");
+    const view = service.pagePrompt(url.searchParams.get("deckId") ?? "", url.searchParams.get("pageId") ?? "");
+    return view ? json({ ok: true, ...view }) : json({ ok: false, error: { message: "page not found" } }, 404);
+  });
+
   registerRoute(ROUTES.pageSave, async (request) => {
     const body = await request.json().catch(() => ({}));
     const result = service.savePage(body.deckId ?? "", body.pageId ?? "", body.fields ?? body);
@@ -2415,6 +2591,19 @@ export function apply(ctx, rawConfig) {
     });
   });
 
+  // F-188：顶栏「更新」按钮——GET 查 npm 最新版（6s 超时，离线只报错不抛）。
+  registerRoute(ROUTES.updateCheck, async () => json({ ok: true, ...(await service.updateStatus()) }), ["GET"]);
+
+  // F-188：一键更新到最新版（只在 npm 安装模式执行；开发链接安装返回 400 说明原因）。
+  registerRoute(ROUTES.update, async (request) => {
+    if ((request?.method ?? "POST").toUpperCase() !== "POST") return json({ ok: false, error: { message: "POST only" } }, 405);
+    try {
+      return json(await service.runSelfUpdate());
+    } catch (error) {
+      return json({ ok: false, error: { message: String(error?.message ?? error) } }, 400);
+    }
+  }, ["POST"]);
+
   registerRoute(ROUTES.faq, (request) => {
     const url = new URL(request?.url ?? "/", "http://localhost");
     const query = String(url.searchParams.get("q") ?? "").trim();

package/lib/render.js

@@ -19,37 +19,119 @@ const SECRET_PATTERNS = [
   [/password\s*[=:：]\s*\S+/i, "password 赋值"],
 ];
 
+/**
+ * 从正文里抽「要点」短句（F-189）：图上只放短句，不排长段。
+ * 切块优先级：空行分段 → ①②③ 编号 → 句号；每块取冒号前的标签 + 后半句短描述，压到 ~28 字。
+ * @param {string} body
+ * @param {number} [limit]
+ * @returns {string[]}
+ */
+/** 把一句压到 limit 字内：优先在标点处断（不出现省略号——画面上的省略号会被当成内容印出来）。 */
+function shortenClause(text, limit = 28) {
+  const value = String(text ?? "").trim();
+  if (value.length <= limit) return value;
+  const cut = value.slice(0, limit);
+  let best = -1;
+  for (const punct of ["，", "、", "；", "：", "。"]) {
+    best = Math.max(best, cut.lastIndexOf(punct));
+  }
+  const base = best >= 10 ? cut.slice(0, best) : cut;
+  return base.replace(/[，、；：。]$/u, "").trim();
+}
+
+export function bodyKeyPoints(body, limit = 4) {
+  const text = String(body ?? "").trim();
+  if (!text) return [];
+  const blocks = text
+    .split(/\n{2,}|[①②③④⑤⑥⑦⑧⑨⑩]/u)
+    .map((block) => block.trim())
+    .filter(Boolean);
+  const points = [];
+  for (const block of blocks) {
+    const first = block.split(/(?<=[。！？])/u)[0].trim().replace(/[。！？]$/u, "");
+    if (!first) continue;
+    // 「标签（补充）：说明」→ 保留标签 + 说明的首个短句，图上才读得完
+    const match = first.match(/^([^：]{1,14}：)\s*(.+)$/u);
+    const point = match ? `${match[1]}${shortenClause(match[2], 20)}` : shortenClause(first);
+    if (point) points.push(point);
+    if (points.length >= limit) break;
+  }
+  return points;
+}
+
+/**
+ * 「这一页必须在画面上印出的文字」清单（F-189）。
+ * 出图模型只认「要印什么」，把字段名换成口语会漏印——所以这里给出逐字清单，供 prompt 与 QA 共用。
+ * @param {object} slide
+ * @returns {{title:string, subtitle:string, claim:string, bullets:string[]}}
+ */
+export function onImageText(slide) {
+  const text = (value) => String(value ?? "").trim();
+  const title = text(slide?.title);
+  const subtitle = text(slide?.question);
+  const claim = text(slide?.claim);
+  return {
+    title,
+    subtitle,
+    // 主张超过 40 字就别整句塞画面（读不完），让副标题 + 要点承担信息。
+    claim: claim.length > 40 ? `${claim.slice(0, 39)}…` : claim,
+    bullets: bodyKeyPoints(slide?.body),
+  };
+}
+
+const ON_IMAGE_HEAD = "【这一页必须在画面上印出的文字：逐字照排，不要改写、翻译、缩写或省略】";
+
+/** 把清单渲染成 prompt 行（QA 只检查 head 存在与关键行逐字命中）。 */
+function onImageLines(list) {
+  const lines = [ON_IMAGE_HEAD];
+  if (list.title) lines.push(`主标题：${list.title}`);
+  if (list.subtitle) lines.push(`副标题（标题下方一行，字号小于主标题）：${list.subtitle}`);
+  if (list.claim) lines.push(`一句话主张：${list.claim}`);
+  if (list.bullets.length) {
+    lines.push("要点（逐条列出，每条一行短句）：");
+    list.bullets.forEach((point, index) => lines.push(`${index + 1}. ${point}`));
+  }
+  return lines;
+}
+
 /**
  * 由 slide 字段 + 全局风格 preset 组 prompt。
  * F-158：封面页单列一套版式纪律（只放标题/副标题/作者/日期，不堆正文）；
  * 普通页带上 intent 的受众 / 目的，避免「图很漂亮但讲错人」。
+ * F-189：文字不再是「语境」，而是显式「图上文字清单」——副标题 / 主张 / 要点逐字列出，
+ * 并声明与 visualBrief 的排他指令冲突时文字优先（否则「画面上只出现 XX 标签」会把副标题吞掉）。
  * @param {object} slide manifest slide
  * @param {string} styleBrief
  * @param {{brief?: object}} [context] readDeckBrief() 的结果
  */
 export function buildPrompt(slide, styleBrief, context = {}) {
   const brief = context.brief ?? {};
+  const list = onImageText(slide);
   const isCover = slide?.type === "cover" || Number(slide?.order) === 1;
   if (isCover) {
-    const parts = [styleBrief, "封面页（16:9）：只放标题信息", `主标题：${slide?.title ?? ""}`];
-    if (slide?.question) parts.push(`副标题：${slide.question}`);
+    const parts = [styleBrief, "封面页（16:9）：只放标题信息", ...onImageLines({ ...list, bullets: [] })];
     parts.push(...coverPromptLines(brief));
     parts.push("版式纪律：只放主标题 / 副标题 / 作者 / 日期；正文不超过一行；不要目录、要点清单、数据图表、大段文字；留白为主。");
     if (slide?.visualBrief) parts.push(`画面要求：${slide.visualBrief}`);
+    parts.push("文字优先：上面【图上文字】的每一行都必须出现在画面里；画面要求与它冲突时，以上面为准。");
     return parts.filter(Boolean).join("\n");
   }
-  const parts = [styleBrief, `页面标题：${slide.title ?? ""}`];
-  if (slide.question) parts.push(`这页回答：${slide.question}`);
-  if (slide.claim) parts.push(`主张：${slide.claim}`);
-  const body = String(slide.body ?? "").trim();
-  if (body) parts.push(`正文要点：${body.slice(0, 300)}`);
-  if (slide.visualBrief) parts.push(`画面要求：${slide.visualBrief}`);
+  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}`);
+  parts.push("文字优先：上面【图上文字】的每一行都必须印出来（可换行、可分层，但不得省略）；画面要求若写「只出现 XX」，XX 之外仍要保留主标题与副标题。");
   parts.push(...briefPromptLines(brief));
   return parts.filter(Boolean).join("\n");
 }
 
-/** QA 门禁。返回 {ok, checks:[{name, ok, detail}]}。 */
-export function qaCheck(prompt, size) {
+/**
+ * QA 门禁。返回 {ok, checks:[{name, ok, detail}]}。
+ * @param {string} prompt 最终 prompt
+ * @param {string} size 尺寸
+ * @param {object} [slide] 传了就额外检查「图上文字」是否都在 prompt 里（F-189）
+ */
+export function qaCheck(prompt, size, slide) {
   const checks = [];
   const promptOk = typeof prompt === "string" && prompt.trim().length >= 8;
   checks.push({ name: "prompt-exists", ok: promptOk, detail: promptOk ? `${prompt.trim().length} chars` : "prompt 为空或过短" });
@@ -57,6 +139,15 @@ export function qaCheck(prompt, size) {
   checks.push({ name: "size-valid", ok: sizeOk, detail: String(size ?? "") });
   const secretHit = SECRET_PATTERNS.find(([pattern]) => pattern.test(prompt ?? ""));
   checks.push({ name: "no-secrets", ok: !secretHit, detail: secretHit ? `疑似敏感串：${secretHit[1]}` : "clean" });
+  if (slide) {
+    const list = onImageText(slide);
+    const missing = [];
+    if (!String(prompt ?? "").includes(ON_IMAGE_HEAD)) missing.push("图上文字清单");
+    if (list.title && !String(prompt ?? "").includes(list.title)) missing.push("主标题");
+    if (list.subtitle && !String(prompt ?? "").includes(list.subtitle)) missing.push("副标题");
+    if (list.claim && !String(prompt ?? "").includes(list.claim)) missing.push("主张");
+    checks.push({ name: "on-image-text", ok: missing.length === 0, detail: missing.length ? `prompt 缺：${missing.join(" / ")}` : `${list.title ? "标题" : ""}${list.subtitle ? "+副标题" : ""}${list.claim ? "+主张" : ""}${list.bullets.length ? `+${list.bullets.length} 要点` : ""}` || "clean" });
+  }
   return { ok: checks.every((check) => check.ok), checks };
 }
 

package/lib/tools.js

@@ -1214,7 +1214,7 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
           ? [linked.brief, linked.constraints ? `不要什么：${linked.constraints}` : ""].filter(Boolean).join("\n")
           : config.styleBrief;
         const prompt = buildPrompt(slide, styleBrief, { brief: readDeckBrief(renderAdapter.sourceRoot) });
-        const qa = qaCheck(prompt, size);
+        const qa = qaCheck(prompt, size, slide);
         if (!qa.ok) {
           store.recordEvent({ type: "deck.qa", sessionId, taskId: task.taskId, deckId: deck.id, slideIds: [pageId], actor: "system", status: "failed", payload: { gate: "qa", qa } });
           return tryFinish({ status: "failed", error: "qa-gate", value: { taskId: task.taskId, deckId: deck.id, slideIds: [pageId], qa, text: `QA 门禁未通过：${qa.checks.filter((check) => !check.ok).map((check) => `${check.name}(${check.detail})`).join("；")}` } });
@@ -1380,6 +1380,7 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
       };
       try {
         const prompt = `# 修图（局部修改，其余保持不变）\n${instruction}\n\n要求：只改点名的地方；不换整页构图；图里的文字保持可读，不要新增没提到的文字或 logo。`;
+        // 修图是「以现有图为底图」的局部指令，不走「图上文字清单」检查（那是整页出图的门禁）。
         const qa = qaCheck(prompt, size);
         if (!qa.ok) {
           store.recordEvent({ type: "deck.qa", sessionId, taskId: task.taskId, deckId: deck.id, slideIds: pageId ? [pageId] : [], actor: "system", status: "failed", payload: { gate: "qa", qa } });

package/lib/update-check.js

@@ -0,0 +1,166 @@
+/**
+ * 插件自更新：版本比较 + 安装方式判断 + 更新命令（F-188）。
+ *
+ * 背景：插件装好之后没有「检查更新 / 一键更新」入口，用户只能自己去终端 `dsh plugin add`。
+ * 工作台顶栏给一个刷新按钮（有新版时带小圆点），点了能看版本差异并直接更新；旁边是仓库入口（提 issue）。
+ *
+ * 纪律：
+ * - **只在 npm 安装模式下执行更新**；本机 `link:` / `file:` 开发安装一律拒绝执行，只解释原因
+ *   （开发树里跑 pnpm add 会把本地 link 换成 registry 版本，把人正在改的代码顶掉）。
+ * - 更新只改 profile 里的依赖，**不改运行中的进程**：跑完提示重启 DSH 才生效。
+ * - 版本比较按 semver 的「主.次.补 + 预发」做，不引第三方依赖。
+ *
+ * @module dsh-plugin-deck-studio/update-check
+ */
+
+
+const clamp = (value) => String(value ?? "").trim();
+
+/** 解析 "1.2.3-rc.4" → { main:[1,2,3], pre:["rc","4"] }；非法返回 null。 */
+export function parseVersion(raw) {
+  const text = clamp(raw).replace(/^v/i, "");
+  const match = text.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!match) return null;
+  return {
+    main: [Number(match[1]), Number(match[2]), Number(match[3])],
+    pre: match[4] ? match[4].split(".") : [],
+  };
+}
+
+/** semver 优先级比较：a>b 返回 1，a<b 返回 -1，相等 0（含预发版规则）。非法版本抛错。 */
+export function compareVersions(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left) throw new Error(`版本号不合法：${a}`);
+  if (!right) throw new Error(`版本号不合法：${b}`);
+  for (let i = 0; i < 3; i += 1) {
+    if (left.main[i] !== right.main[i]) return left.main[i] > right.main[i] ? 1 : -1;
+  }
+  // 有预发标记的版本低于同号正式版（0.3.0-rc.1 < 0.3.0）
+  if (!left.pre.length && !right.pre.length) return 0;
+  if (!left.pre.length) return 1;
+  if (!right.pre.length) return -1;
+  const size = Math.max(left.pre.length, right.pre.length);
+  for (let i = 0; i < size; i += 1) {
+    const x = left.pre[i];
+    const y = right.pre[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x === y) continue;
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) return Number(x) > Number(y) ? 1 : -1;
+    if (xn) return -1; // 数字标识符优先级低于字母
+    if (yn) return 1;
+    return x > y ? 1 : -1;
+  }
+  return 0;
+}
+
+/** latest 比 current 新才返回 true；任一版本号非法时返回 false（宁可不动）。 */
+export function isNewer(latest, current) {
+  try {
+    return compareVersions(latest, current) > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** 从 registry 的 packument / version 文档里取 latest 版本（兼容 dist-tags 与单版本文档）。 */
+export function latestFromRegistry(payload) {
+  if (!payload || typeof payload !== "object") return "";
+  const tagged = clamp(payload["dist-tags"]?.latest);
+  if (tagged && parseVersion(tagged)) return tagged; // 坏 tag（"abc"）不许当版本
+  const single = clamp(payload.version);
+  return parseVersion(single) ? single : "";
+}
+
+/**
+ * 判断插件是怎么装进 profile 的：
+ * - `linked`：`link:` / `file:` / `portal:` 等本地路径 —— 开发模式，更新走 git，不执行 pnpm
+ * - `npm`：semver 版本（或 `^` / `~` / `latest` 等 tag）—— 可以 `pnpm add <pkg>@latest`
+ * - `unknown`：找不到 profile 或依赖缺失
+ */
+export function installModeOf({ profileDir = "", packageName = "" } = {}) {
+  if (!profileDir || !packageName) return { mode: "unknown", spec: "", reason: "拿不到 profile 目录或包名" };
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(join(profileDir, "package.json"), "utf8"));
+  } catch {
+    return { mode: "unknown", spec: "", reason: `读不到 ${join(profileDir, "package.json")}` };
+  }
+  const spec = clamp(pkg?.dependencies?.[packageName]);
+  if (!spec) return { mode: "unknown", spec: "", reason: `profile 的 dependencies 里没有 ${packageName}` };
+  if (/^(link|file|portal|workspace):/i.test(spec) || spec.startsWith(".") || spec.startsWith("/")) {
+    return { mode: "linked", spec, reason: "本机是开发链接安装（link:/file:），更新走仓库，不在界面里执行" };
+  }
+  return { mode: "npm", spec, reason: "" };
+}
+
+/**
+ * 找出插件所在的 profile 目录（更新命令要在那里跑 pnpm）：
+ * 1. 从插件真实路径往上走，哪一级 package.json 的 dependencies 声明了这个包，哪一级就是 profile
+ *    —— npm 布局下插件在 `<profile>/node_modules/<pkg>`，这一条就够，不依赖 env；
+ * 2. 退而用 env.DSH_PROFILE_DIR（DSH 启动时注入），要求它确实声明了这个依赖；
+ * 3. 都没有返回 ""（界面只解释、不执行）。
+ */
+export function detectProfileDir({ pluginDir = "", packageName = "", env = {} } = {}) {
+  if (!pluginDir || !packageName) return "";
+  const declares = (dir) => {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+      return Boolean(pkg?.dependencies?.[packageName]);
+    } catch {
+      return false;
+    }
+  };
+  let dir = "";
+  try {
+    dir = realpathSync(pluginDir);
+  } catch {
+    dir = pluginDir;
+  }
+  // 逐级向上（最多 6 层，避免走到磁盘根）
+  for (let depth = 0; depth < 6; depth += 1) {
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    if (declares(parent)) return parent;
+    dir = parent;
+  }
+  const hinted = clamp(env?.DSH_PROFILE_DIR);
+  if (hinted && declares(hinted)) return hinted;
+  // 开发链接安装：插件不在 profile 里，扫 DSH_HOME/profiles/*，挑一个确实声明了依赖的
+  const root = clamp(env?.DSH_HOME) ? join(clamp(env?.DSH_HOME), "profiles") : "";
+  if (root) {
+    try {
+      const candidates = readdirSync(root)
+        .map((entry) => join(root, entry))
+        .filter((dir) => declares(dir));
+      if (candidates.length) {
+        const named = env?.DSH_PROFILE ? candidates.find((dir) => dir.endsWith(`/${env.DSH_PROFILE}`)) : null;
+        return named ?? candidates[0];
+      }
+    } catch {
+      /* profiles 目录不存在就算了 */
+    }
+  }
+  return "";
+}
+
+/** 插件包里仓库相关链接（用于顶栏「GitHub」按钮）；没有就留空。 */
+export function repoLinksOf(packageJson = {}) {
+  const repo = packageJson.repository;
+  const raw = typeof repo === "string" ? repo : clamp(repo?.url);
+  const url = raw
+    .replace(/^git\+/, "")
+    .replace(/^git@github\.com:/, "https://github.com/")
+    .replace(/\.git$/, "");
+  const homepage = clamp(packageJson.homepage) || url;
+  const bugs = typeof packageJson.bugs === "string" ? packageJson.bugs : clamp(packageJson.bugs?.url);
+  const issues = bugs ? bugs.replace(/\/+$/, "") : url ? `${url}/issues` : "";
+  const suggest = issues.endsWith("/issues") ? `${issues}/new/choose` : url ? `${url}/issues/new/choose` : "";
+  return { repo: url, homepage, issues, suggest };
+}
+
+import { readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "dsh-plugin-deck-studio",
-  "version": "0.2.8",
-  "private": false,
+  "version": "0.2.9",
   "description": "Deckline：DSH 的 image deck / PPT 工作台插件——原生 Chat + 整页图片 deck 工作区 + 设计风格库；用对话做 PPT、按页出图、版本可追踪、导出 PDF/PPTX。",
+  "homepage": "https://github.com/yuna78/dsh-deck-studio#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuna78/dsh-deck-studio.git",
+    "directory": "plugin/deck-studio"
+  },
+  "bugs": {
+    "url": "https://github.com/yuna78/dsh-deck-studio/issues"
+  },
+  "private": false,
   "license": "MIT",
   "type": "module",
   "main": "./index.js",
@@ -52,15 +61,6 @@
       ]
     }
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/yuna78/dsh-deck-studio.git",
-    "directory": "plugin/deck-studio"
-  },
-  "homepage": "https://github.com/yuna78/dsh-deck-studio#readme",
-  "bugs": {
-    "url": "https://github.com/yuna78/dsh-deck-studio/issues"
-  },
   "peerDependencies": {
     "@deepseek-ai/dsh": ">=0.2.1-rc.2 <0.3.0"
   },

package/seeds/docs/manual.en.md

@@ -292,3 +292,20 @@ fabrication, explicit confirmation); suspicious instructions are flagged, never
 | `exports/` | exported PDF / PPTX / handoff bundles. |
 
 `.deck/` and `exports/` are gitignored; the repository only ships code, docs, samples and preset styles.
+## 13. Updating the plugin & giving feedback
+
+Three always-on buttons live in the top-right of the workbench header:
+
+| Button | What it does |
+|---|---|
+| **⚙** | Jumps to the settings panel (render node / model / API key source / size); from the home page it returns to the current deck first |
+| **↻ vX.Y.Z** | Checks npm for the latest release: up to date → tells you the version; newer → asks "current vX → vY", then runs `dsh plugin add` for you (restart DSH to apply). A `link:` / `file:` dev install is never auto-updated — it explains to pull the repo instead, so your local link is not replaced by a registry copy |
+| **GitHub** | Opens the repo's new-issue page (feature requests / bug reports) |
+
+Command-line equivalent:
+
+```sh
+dsh plugin --profile deckline add dsh-plugin-deck-studio@latest
+```
+
+If npm is unreachable the button says so ("check timed out") instead of hanging.

package/seeds/docs/manual.md

@@ -256,3 +256,20 @@ key 值只存在本机数据文件里，任何接口都不会回显。
 | `exports/` | 导出产物（PDF / PPTX / 交接包）。 |
 
 `.deck/` 与 `exports/` 都在 `.gitignore` 里；仓库只带代码、文档、示例与预设风格。
+## 13. 更新插件与反馈
+
+工作台顶栏右上角三个常驻按钮，装好之后不用记命令：
+
+| 按钮 | 行为 |
+|---|---|
+| **⚙** | 直接切到右栏「设置」页（出图节点 / 模型 / key 来源 / 尺寸）；在首页时先回到当前 deck 再切 |
+| **↻ vX.Y.Z** | 点一下查 npm 最新版：已是最新 → 提示版本号；有新版 → 弹「当前 vX → vY」确认，点「更新」直接跑 `dsh plugin add`，完成后**重启 DSH 生效**；本机 `link:` / `file:` 开发安装只解释「更新走仓库」，不会把本地链接换成 registry 包 |
+| **GitHub** | 打开仓库的「新建 issue」页（提建议 / 报问题） |
+
+命令行的等价写法：
+
+```sh
+dsh plugin --profile deckline add dsh-plugin-deck-studio@latest
+```
+
+不上网时点 ↻ 会明确提示「检查更新超时：连不上 npm registry」，不会卡住界面。

package/ui/workbench.css

@@ -83,11 +83,16 @@
 .tool-line.err{border-left-color:#c0533f;background:#faf0ed;color:#8c3a2c;white-space:normal}
 
 /* 8 份必备文档（中间区标签） */
-.doc-head{display:flex;align-items:flex-start;gap:12px;flex-wrap:wrap;margin-bottom:10px}
-.doc-head h2{margin:6px 0 0;font-family:"Noto Serif SC",Georgia,serif;font-size:22px;color:var(--ink)}
-.doc-head .doc-file{margin-left:auto;color:#8a9599;font-size:10.5px;align-self:center}
-/* F-187：审稿页的相关文件切换（听众读后感 / 意图差距 / 工程口径 …） */
-.doc-head .doc-files{margin-left:auto;display:flex;gap:6px;flex-wrap:wrap;justify-content:flex-end;max-width:70%}
+.doc-head{display:flex;flex-direction:column;gap:6px;margin-bottom:10px}
+.doc-head-top{display:flex;align-items:flex-start;gap:12px;flex-wrap:wrap}
+.doc-head-top h2{margin:6px 0 0;font-family:"Noto Serif SC",Georgia,serif;font-size:22px;color:var(--ink)}
+.doc-head-side{margin-left:auto;display:flex;flex-direction:column;align-items:flex-end;gap:5px;text-align:right}
+.doc-head .doc-file{color:#8a9599;font-size:10.5px}
+/* F-187：审稿页的相关文件切换（听众读后感 / 意图差距 / 工程口径 …）
+   F-188 后续：一轮评审有 5 个 chip，跟标题挤一行会右对齐折成两截，改成独立一行、左对齐。 */
+.doc-head-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap;margin-top:2px}
+.doc-head .doc-files{margin:0;display:flex;gap:6px;flex-wrap:wrap;justify-content:flex-start;max-width:100%}
+.doc-head-extra{display:flex;align-items:center;gap:8px;flex-wrap:wrap;justify-content:flex-end}
 .doc-file-chip{border:1px solid #d7dee0;background:#fff;color:#5a6a70;border-radius:999px;padding:3px 10px;font-size:10.5px;cursor:pointer}
 .doc-file-chip:hover{border-color:#0f6f7a;color:#0f6f7a}
 .doc-file-chip.active{background:#0f6f7a;border-color:#0f6f7a;color:#fff}
@@ -690,3 +695,15 @@ body.presenting{overflow:hidden}
 .source-title .doc-status{margin-left:8px;font-size:9px;font-weight:400;vertical-align:2px}
 .doc-status.optional{color:#7a7f7c;background:#efece3;border:1px solid #e0dbcd;border-radius:8px;padding:0 6px;line-height:16px}
 .source-hint{font-size:10px;color:#8b8f8b;margin-top:3px;line-height:1.5}
+
+/* F-188：顶栏「更新 / GitHub」小按钮 + 临时提示（顶栏是深色，沿用 .top button 的浅色底） */
+.top .dl-icon-btn{position:relative;display:inline-flex;align-items:center;gap:5px;padding:6px 9px;cursor:pointer;font:inherit;font-size:12px;line-height:1}
+.top .dl-icon-btn:hover{background:#ffffff2e}
+.top .dl-icon-btn:active{transform:translateY(1px)}
+.top .dl-icon-btn.busy svg{animation:dl-spin 1s linear infinite}
+.top .dl-icon-btn svg{flex:0 0 auto;opacity:.85}
+.top .dl-icon-ver{opacity:.72;font-size:11px;font-variant-numeric:tabular-nums}
+.top .dl-icon-dot{position:absolute;top:3px;right:4px;width:7px;height:7px;border-radius:50%;background:#e8b45c;box-shadow:0 0 0 2px var(--ink)}
+.dl-toast{position:fixed;left:50%;top:66px;transform:translateX(-50%) translateY(-6px);z-index:80;max-width:min(560px,90vw);padding:9px 14px;border:1px solid var(--line);border-radius:10px;background:#fffdf7;color:#2c2a26;font-size:13px;line-height:1.5;box-shadow:0 10px 28px rgba(0,0,0,.18);opacity:0;pointer-events:none;transition:opacity .16s ease,transform .16s ease;white-space:pre-wrap}
+.dl-toast.show{opacity:1;transform:translateX(-50%) translateY(0)}
+@keyframes dl-spin{to{transform:rotate(360deg)}}

package/ui/workbench.html

@@ -92,6 +92,19 @@
   <span class="project">AI Image Deck Studio</span>
   <span class="spacer"></span>
   <span id="save">DSH 会话 · 连接中…</span>
+  <!-- F-188：更新 / 仓库 / 设置入口（点刷新查 npm 最新版，有新版带小圆点） -->
+  <button id="settingsBtn" class="dl-icon-btn" title="设置（出图节点 / 模型 / 尺寸）" aria-label="设置">
+    <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true"><path fill="currentColor" d="M19.4 13a7.7 7.7 0 0 0 0-2l2-1.6-2-3.4-2.4 1a7.7 7.7 0 0 0-1.7-1L15 3.5h-4l-.3 2.5a7.7 7.7 0 0 0-1.7 1l-2.4-1-2 3.4 2 1.6a7.7 7.7 0 0 0 0 2l-2 1.6 2 3.4 2.4-1a7.7 7.7 0 0 0 1.7 1l.3 2.5h4l.3-2.5a7.7 7.7 0 0 0 1.7-1l2.4 1 2-3.4-2-1.6zM12 15.2A3.2 3.2 0 1 1 12 8.8a3.2 3.2 0 0 1 0 6.4z"/></svg>
+  </button>
+  <button id="updateBtn" class="dl-icon-btn" title="检查更新" aria-label="检查更新">
+    <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true"><path fill="currentColor" d="M12 4V1.5L7.5 6l4.5 4.5V8a5 5 0 1 1-5 5H5a7 7 0 1 0 7-9z"/></svg>
+    <span class="dl-icon-ver" id="updateVer">—</span>
+    <i class="dl-icon-dot" id="updateDot" hidden></i>
+  </button>
+  <button id="repoBtn" class="dl-icon-btn" title="GitHub 仓库 / 提建议" aria-label="GitHub 仓库">
+    <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>
+  </button>
+  <div id="dlToast" class="dl-toast" hidden></div>
   <button id="shellSidebarBtn" title="显示 / 收起 DSH 侧栏（会话 · 插件 · 设置）" hidden>☰ DSH</button>
 </header>
 
@@ -1044,6 +1057,137 @@ async function postJson(routeName, body) {
   return data;
 }
 
+/** GET 一个插件路由（失败抛后端 message）。 */
+async function getJson(routeName) {
+  const res = await fetch("/api/deck-studio." + routeName, { headers: { accept: "application/json" } });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok || data?.ok === false) throw new Error(data?.error?.message || "HTTP " + res.status);
+  return data;
+}
+
+/** 顶栏临时提示（不打断操作）。 */
+let DL_TOAST_TIMER = null;
+function dlToast(text, ms = 4200) {
+  const box = getEl("dlToast");
+  if (!box) return;
+  box.textContent = text;
+  box.hidden = false;
+  box.classList.add("show");
+  clearTimeout(DL_TOAST_TIMER);
+  DL_TOAST_TIMER = setTimeout(() => {
+    box.classList.remove("show");
+    box.hidden = true;
+  }, ms);
+}
+
+/** F-188：更新状态（版本 / 安装方式 / 仓库链接）由 workbench payload 带下来。 */
+const UPDATE = { current: "", latest: "", hasUpdate: false, installMode: "", repo: "", suggest: "", note: "" };
+
+function paintUpdate() {
+  const ver = getEl("updateVer");
+  if (ver) ver.textContent = UPDATE.current ? `v${UPDATE.current}` : "—";
+  const dot = getEl("updateDot");
+  if (dot) dot.hidden = !UPDATE.hasUpdate;
+  const btn = getEl("updateBtn");
+  if (btn) {
+    btn.title = UPDATE.hasUpdate
+      ? `有新版 v${UPDATE.latest}（当前 v${UPDATE.current}）`
+      : UPDATE.installMode === "linked"
+        ? "本机是开发链接安装：更新走 git pull"
+        : "检查更新";
+  }
+}
+
+function absorbUpdate(payload) {
+  const brief = payload?.update ?? {};
+  if (brief.currentVersion) UPDATE.current = brief.currentVersion;
+  if (brief.installMode) UPDATE.installMode = brief.installMode;
+  if (brief.repo) UPDATE.repo = brief.repo;
+  if (brief.suggest) UPDATE.suggest = brief.suggest;
+  if (brief.issues) UPDATE.issues = brief.issues;
+  paintUpdate();
+}
+
+async function runPluginUpdate() {
+  try {
+    const data = await postJson("update", {});
+    UPDATE.current = data.to || UPDATE.current;
+    UPDATE.hasUpdate = false;
+    paintUpdate();
+    openConfirm({
+      title: `已更新到 v${data.to}`,
+      desc: `${data.restartHint || "重启 DSH 后生效。"}\n\n${data.output ? String(data.output).slice(-600) : ""}`,
+      okLabel: "知道了",
+      onOk: null,
+    });
+  } catch (error) {
+    dlToast(String(error?.message || error), 8000);
+  }
+}
+
+/** 点刷新：先查 npm 最新版，再决定是提示「已是最新」、解释开发链接、还是弹更新确认。 */
+async function checkPluginUpdate() {
+  const btn = getEl("updateBtn");
+  if (btn) btn.classList.add("busy");
+  try {
+    const data = await getJson("update-check");
+    UPDATE.latest = data.latestVersion || "";
+    UPDATE.hasUpdate = Boolean(data.hasUpdate);
+    UPDATE.installMode = data.installMode || UPDATE.installMode;
+    if (data.note) UPDATE.note = data.note;
+    paintUpdate();
+    if (data.error) {
+      dlToast(data.error, 6000);
+      return;
+    }
+    if (!UPDATE.hasUpdate) {
+      dlToast(`已是最新版本 v${data.currentVersion}`);
+      return;
+    }
+    if (data.installMode === "linked") {
+      dlToast(data.note || "本机是开发链接安装，更新走仓库（git pull）。", 7000);
+      return;
+    }
+    if (data.installMode !== "npm") {
+      dlToast("没识别出 profile 的安装方式，无法一键更新；请手动 dsh plugin add。", 7000);
+      return;
+    }
+    openConfirm({
+      title: `更新到 v${data.latestVersion}`,
+      desc: `当前 v${data.currentVersion} → v${data.latestVersion}。会在 profile 里执行 pnpm add，下载完成后重启 DSH 生效。`,
+      okLabel: "更新",
+      onOk: runPluginUpdate,
+    });
+  } catch (error) {
+    dlToast(`检查更新失败：${String(error?.message || error)}`, 6000);
+  } finally {
+    if (btn) btn.classList.remove("busy");
+  }
+}
+
+/** 顶栏齿轮：直接切到右栏「设置」（首页时先回到当前 deck 的工作台）。 */
+async function openSettingsPanel() {
+  const deckId = STATE.data?.active?.deckId;
+  if (!deckId) {
+    dlToast("先在 Decks 里打开一本 deck，右栏就有设置（出图节点 / 模型 / 尺寸）", 6000);
+    return;
+  }
+  if (STATE.view === "home") await showDeck(deckId);
+  activateRightTab("settings");
+  const panel = getEl("settings");
+  if (panel) panel.scrollIntoView({ block: "start" });
+}
+
+/** 打开仓库 / 提建议页（新标签）。 */
+function openRepo() {
+  const url = UPDATE.suggest || UPDATE.issues || UPDATE.repo;
+  if (!url) {
+    dlToast("插件包里没配 repository 链接", 5000);
+    return;
+  }
+  window.open(url, "_blank", "noopener");
+}
+
 let CONFIRM_OK = null;
 
 /** 通用确认弹层（删除等破坏性操作用）。 */
@@ -1407,12 +1551,24 @@ function emptyDoc(doc) {
 }
 
 function docHeader(doc, extra = "") {
+  // 只有「多个可切换的文档」才出 chip：目录（prompts/ 之类）、不存在的相关文件都不算。
+  // 以前脚本页右侧也挂着 script.md / prompts/ 两个 chip，看着像能切，其实没内容可切。
+  const switchable = (doc.files || []).filter((file) => !String(file.name || "").endsWith("/") && file.exists !== false);
+  const chips = switchable.length > 1
+    ? `<div class="doc-files">${switchable.map((file) => `<button type="button" class="doc-file-chip${file.name === doc.primary ? " active" : ""}" data-doc-file="${esc(file.name)}" title="${esc(file.name)}">${esc(file.name.replace(/^docs\//, ""))}</button>`).join("")}</div>`
+    : "";
+  // 两行：第一行标题 + 徽标，右上角是主文件路径与草案说明 / 动作；第二行只有文件 chips（左对齐，可换行）。
+  // 一轮审稿会有 review.md / readers / gap / experts / images / scores 六个 chip，跟标题挤一行会被挤到右侧折成两截，很难读。
   return `<div class="doc-head">
-    <div><div class="eyebrow">Deck Document</div><h2>${esc(doc.label)}</h2></div>
-    ${docBadge(doc.status)}
-    <span class="small doc-file">${esc(doc.primary || "无文件")}</span>
-    ${(doc.files || []).length > 1 ? `<div class="doc-files">${doc.files.map((file) => `<button type="button" class="doc-file-chip${file.name === doc.primary ? " active" : ""}" data-doc-file="${esc(file.name)}" title="${esc(file.name)}">${esc(file.name.replace(/^docs\//, ""))}</button>`).join("")}</div>` : ""}
-    ${extra}
+    <div class="doc-head-top">
+      <div><div class="eyebrow">Deck Document</div><h2>${esc(doc.label)}</h2></div>
+      ${docBadge(doc.status)}
+      <span class="doc-head-side">
+        <span class="small doc-file">${esc(doc.primary || "无文件")}</span>
+        ${extra ? `<span class="doc-head-extra">${extra}</span>` : ""}
+      </span>
+    </div>
+    ${chips ? `<div class="doc-head-row">${chips}</div>` : ""}
   </div>`;
 }
 
@@ -1650,6 +1806,7 @@ function renderDoc(doc, index) {
         })()}
         ${bodyText ? `<div class="page-content md${placeholderContent ? " is-placeholder" : ""}">${placeholderContent ? esc(bodyText) : mdToHtml(bodyText)}</div><p class="density-line">${densityBadge("body", bodyText)}</p>` : `<p class="engine-note">（这页没有正文）</p>`}
         <details class="prompt-details"><summary>提示词（${placeholderPrompt ? "待补" : `${String(promptText).length} 字符`}${densityTarget && !placeholderPrompt ? ` · 目标 ${densityTarget.briefMin}–${densityTarget.briefMax} 字` : ""}）</summary><div class="prompt-quote">${esc(promptText || "（缺提示词）")}${placeholderPrompt ? pendingHint(["visualBrief"]) : ""}</div></details>
+        <details class="prompt-details" data-assembled-prompt="${esc(slide.id)}"><summary>出图时拼装的完整 prompt（含图上文字清单，展开时读取）</summary><div class="prompt-quote" data-assembled-body="${esc(slide.id)}">展开读取…</div></details>
         ${proposalBlock}
       </div></div>`;
     }).join("")}</div>` + docFooter(doc, content);
@@ -1929,6 +2086,29 @@ async function rollbackFirstDraft(revision) {
 }
 
 function bindDocActions(root) {
+  root.querySelectorAll("details[data-assembled-prompt]").forEach((details) => {
+    details.addEventListener("toggle", async () => {
+      if (!details.open) return;
+      const pageId = details.getAttribute("data-assembled-prompt");
+      const body = details.querySelector("[data-assembled-body]");
+      if (!pageId || !body || body.dataset.loaded === "1") return;
+      const deckId = STATE.data?.active?.deckId;
+      if (!deckId) return;
+      body.textContent = "读取中…";
+      try {
+        const res = await fetch(`/api/deck-studio.page-prompt?` + new URLSearchParams({ deckId, pageId }), { headers: { accept: "application/json" } });
+        const data = await res.json().catch(() => ({}));
+        if (res.ok && data?.ok && data.prompt) {
+          body.textContent = data.prompt;
+          body.dataset.loaded = "1";
+        } else {
+          body.textContent = `读取失败：${data?.error?.message || "未知错误"}`;
+        }
+      } catch (error) {
+        body.textContent = `读取失败：${String(error?.message ?? error)}`;
+      }
+    });
+  });
   root.querySelectorAll("[data-doc-file]").forEach((btn) => btn.addEventListener("click", () => {
     const file = btn.getAttribute("data-doc-file") || "";
     if (file) openDocFile(STATE.tab, file);
@@ -4678,6 +4858,10 @@ function backToManual(box) {
   }
   getEl("embedBack").addEventListener("click", () => window.parent?.postMessage({ type: "dsh-deck-studio:close" }, "*"));
   await loadWorkbench();
+  absorbUpdate(STATE.data);
+  getEl("settingsBtn").addEventListener("click", openSettingsPanel);
+  getEl("updateBtn").addEventListener("click", checkPluginUpdate);
+  getEl("repoBtn").addEventListener("click", openRepo);
   await refreshSessions();
   getEl("save").textContent = EMBED ? "对话在 DSH 原生 Chat" : "对话在左侧 · DSH 原生";
   // F-69：只有 profile 开了 hideShellSidebar，宿主左侧栏才会默认收起；此时顶栏给一个切换入口。