dsh-plugin-deck-studio 0.2.8 → 0.2.10

package/README.md

@@ -1,53 +1,91 @@
-# Deckline · `dsh-plugin-deck-studio`
+![Deckline](../../assets/logo/deckline-logo.png)
 
-DSH（DeepSeek Harness）的 **image deck 工作台插件**：左侧原生 Chat、中间整页图片 deck、右侧资料 / Designs / 资源 / 会话。
-用对话改稿、按页出图（可点名批量连出）、版本留存、导出 PDF / PPTX / 交接包——不是又一个 PPT 编辑器。
+# Deckline · 用对话制作整页图片幻灯片
+
+**从「讲给谁、讲什么」到脚本、逐页出图、版本与交付，在 DSH 里完成。**
+
+Deckline 是 DeepSeek Harness（DSH）的 **image deck 工作台插件**，不是独立应用，也不是可编辑图层的 PPT 编辑器。对话留在 DSH 原生 Chat；工作台负责脚本、图片、设计风格、版本和资料。
+
+[安装与配置](../../docs/install.md) · [使用手册](../../docs/manual.md) · [示例 deck](../../samples/deckline-intro) · [English overview](../../README.en.md)
+
+## 先看看它怎么工作
+
+![Deckline 工作台：逐页图片、脚本编辑与版本操作](../../docs/assets/screenshots/02-deck-pages.png)
+
+*上图为内置公开示例：中间浏览整页图片，右侧查看与修改这一页的正文、画面要求和提示词。截图展示对应拍摄版本，具体控件以当前版本为准。*
+
+### 从想法到可交付的 deck
+
+| 你要做什么 | Deckline 提供什么 |
+|---|---|
+| 把想法讲清楚 | 从受众、意图与参考资料开始，组织故事线和逐页脚本 |
+| 做出整页画面 | 按页生成图片；点名多页时可连续出图，每页保留 prompt 与版本 |
+| 调整内容和画面 | 在 Chat 里改稿，查看提案；已有图片可做局部修图，生成新版本而不覆盖旧图 |
+| 统一视觉风格 | 内置风格与样张预览，也可创建自己的 Design、添加参考图并跨 deck 复用 |
+| 检查再交付 | 听众评审、资料与审稿文档；直接播放，或导出 PDF / PPTX / 交接包 |
+
+> **导出的 PPTX 每页是一张整页图片，不是可逐项编辑的文本和图表。** 真实出图需要自行配置兼容的 image API；默认 fake 模式用于体验流程。
+
+## 写完就能讲：直接全屏播放
+
+在工作台点击「全屏演示」，用方向键翻页、Esc 退出；不必为了预览先导出文件。
+
+![Deckline 全屏演示：直接播放图片幻灯片](../../docs/assets/screenshots/08-presentation.png)
+
+## Designs：不只选风格，还能维护自己的风格库
+
+预览内置样张、为 deck 选择风格；也可以创建自己的风格，管理画面描述、参考图和样张。这里的 Design 是可复用的视觉定义，**不是固定布局的 PPT 母版**。
+
+![Deckline 风格库：预设样张与风格选择](../../docs/assets/screenshots/09-style-library.png)
+
+![Deckline 风格管理：定义、提示词、样张与关联会话](../../docs/assets/screenshots/10-style-management.png)
+
+更多画面与流程见 [仓库首页](../../README.md)、[风格指南](../../docs/styles.md) 和 [完整示例](../../docs/sample-deck.md)。以上图片均来自公开示例或演示数据。
 
 ## 安装
 
+前置：Node.js `^22.19 或 ≥24`、pnpm 10+、DSH `≥0.2.1-rc.2 <0.3`。详细兼容范围见 [兼容说明](../../docs/compat.md)。
+
 ```sh
 # 1) 新建一个 profile（基于 DSH 自带 web 模板）
 dsh --profile deckline --from-default-profile web
 
-# 2) 安装本插件（安装后会自动注册 bundle，无需手动改配置文件）
-dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.4
+# 2) 安装 npm 最新版；安装后自动注册 bundle
+dsh plugin --profile deckline add dsh-plugin-deck-studio@latest
 
-# 国内网络建议走镜像（否则从 npmjs.org 拉 20 MB 包可能很慢）
-npm_config_registry=https://registry.npmmirror.com dsh plugin --profile deckline add dsh-plugin-deck-studio@0.2.4
+# 国内网络可按需使用镜像，注意镜像版本同步可能有延迟
+# npm_config_registry=https://registry.npmmirror.com dsh plugin --profile deckline add dsh-plugin-deck-studio@latest
 
-# 3) 启动，浏览器打开终端打印的带 token 链接
+# 3) 启动，打开终端打印的带 token 链接
 dsh --profile deckline --port 13090
 ```
 
-确认装上了（输出 `1` 才对）：
+也可以在 DSH「插件 → 发现」中添加索引源：
 
-```sh
-dsh --profile deckline --dump-config | grep -c "preset-deck-critic"
+```text
+https://cdn.jsdelivr.net/gh/yuna78/dsh-deck-studio@main/market-index.json
 ```
 
-在 npmjs.com 搜 `deckline` 或 `ppt dsh` 也能找到。也可以在 DSH「插件 → 发现」里加索引源 `https://cdn.jsdelivr.net/gh/yuna78/dsh-deck-studio@main/market-index.json` 后点安装。
-
-从源码 / Git 安装、Windows、以及完整配置（数据目录 / deck 源 / 出图节点 / key）见仓库文档：
+从源码 / Git 安装、Windows、模型与出图配置及排障见 [中文安装指南](../../docs/install.md) / [English installation](../../docs/install.en.md)。升级后重启 DSH；听众审稿由插件内部调用，不需要单独选择审稿 Mode。
 
-- [docs/install.md](https://github.com/yuna78/dsh-deck-studio/blob/main/docs/install.md)（中文）
-- [docs/install.en.md](https://github.com/yuna78/dsh-deck-studio/blob/main/docs/install.en.md)（English）
-- [示例 deck 与效果](https://github.com/yuna78/dsh-deck-studio/tree/main/samples/deckline-intro)
+## 快速开始
 
-## 快速开始（fake 模式，无需 key）
+1. 首页点「＋ 新建 Deck」，填写标题、受众和一句话意图，选择视觉风格。
+2. 在 Chat 中补充资料、起草故事线与逐页脚本，再按需修改和出图。
+3. 默认 fake 模式生成占位图；真实图片请在「设置」配置出图节点 endpoint、模型与 key。
+4. 在工作台查看页面和版本，直接全屏演示，或导出文件交付。
 
-1. 首页点「＋ 新建 Deck」，填标题 / 受众 / 一句话意图；
-2. 在 Chat 里让 Agent 起草 `intent.md` / `script.md`，确认后逐页出图；
-3. 默认 fake 模式出占位图，能走完整个流程；要看真图再进「设置」填出图节点 endpoint / 模型 / key。
+出图节点不内置。真实渲染需要配置 OpenAI 兼容的 `/v1/images/generations` 地址。节点 key 保存在本机数据目录的 `render-settings.json`（0600，不回显）；不要将 key 提交到 Git。
 
-出图节点不内置：real 模式必须自己配 OpenAI 兼容的 `/v1/images/generations` 地址（key 存本机，
-`~/.dsh/deckline/render-settings.json`，0600，不进 git、不回显）。
+## 数据与边界
 
-## 数据在哪
+- 工作副本、图片、版本与事件默认写 `$DSH_HOME/deckline`，可通过 `dataRoot` 覆盖。
+- 受控源 deck 的 `sourceRoot` **只读**；本机新建 deck 位于 `projectsRoot` 或 `<dataRoot>/projects/<deckId>/source`，有独立写入流程。
+- 每次出图保留版本，旧图片不会因新图生成而被覆盖。
+- 这是 DSH 插件，运行时依赖宿主与用户配置的模型服务；不承诺离线真实出图。
 
-- 运行数据（工作副本 / 出图 / 事件）：`$DSH_HOME/deckline`（可用 `dataRoot` 覆盖）；
-- 受控源 deck：`decks[].sourceRoot` 指向的目录，**只读**，Deckline 永不回写；
-- 新建 deck：`projectsRoot` 或 `<dataRoot>/projects/<deckId>/source`。
+## 许可与反馈
 
-## 许可
+MIT © 2026 Yuna (Deckline) · [LICENSE](../../LICENSE)
 
-MIT © 2026 Yuna (Deckline)。见仓库 [LICENSE](https://github.com/yuna78/dsh-deck-studio/blob/main/LICENSE)。
+[报告问题 / 提建议](https://github.com/yuna78/dsh-deck-studio/issues) · [发布记录](https://github.com/yuna78/dsh-deck-studio/releases)

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,125 @@ 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 = "【这一页必须在画面上印出的文字：逐字照排，不要改写、翻译、缩写或省略】";
+/** 反装饰：图例 / 清单面板 / 英文角标这类「看起来专业但跟本页无关」的元素，模型最容易凭空造。 */
+const CANVAS_DISCIPLINE =
+  "画面纪律：只画上面【图上文字】与「画面要求」点名的元素；不要新增图例 / 清单面板 / 装饰性英文标签 / 示意数据 / 与内容无关的图标；同一元素不要既画出来又列进清单（重复两遍）；同一信息只写一次，不要用双层括号，也不要既加括注又写注释行。";
+
+/** 把清单渲染成 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("要点（原句只作理解；画面上每条压成 ≤12 字短语贴到对应模块）：");
+    list.bullets.forEach((point, index) => lines.push(`${index + 1}. ${point}`));
+  }
+  lines.push("版式与字号预算：主标题最大；副标题紧接其下、约标题的 45% 字号；一句话主张做成通栏一行（字号小于副标题、大于要点）——这三项都必须完整印出，不得省略或用别的话替代。");
+  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(CANVAS_DISCIPLINE);
+    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(CANVAS_DISCIPLINE);
+  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 +145,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.10",
   "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/seeds/styles/TEC.json

@@ -4,7 +4,7 @@
   "description": "科技蓝图风：深海军蓝网格底、青白技术线条、等距系统/架构图、等宽字体标签、发光节点；像工程蓝图和架构白皮书。",
   "constraints": "不要照片、不要卡通、不要渐变光效泛滥、不要彩色斑块、不要写实人物、不要真实品牌 logo。",
   "reference": "架构白皮书 / 工程蓝图",
-  "styleBrief": "科技蓝图 / 等距架构图：深海军蓝底 #0A1628，叠加极淡青色网格（#1E3A5F）；主体是等距（isometric）线框模块：节点、服务器、数据库、云、客户端，用青白色 #7DD3FC 细线与发光边，节点间正交折线连接 + 小箭头；标签用等宽字体（monospace）全大写小字，外加带边框的图例 / 清单面板（不发光）。点缀极少量暖色 #F59E0B 强调关键节点。整体像工程蓝图 / 架构白皮书，信息密度高但网格秩序强；无照片、无卡通、无廉价霓虹。",
+  "styleBrief": "科技蓝图 / 等距架构图：深海军蓝底 #0A1628，叠加极淡青色网格（#1E3A5F）；主体是等距（isometric）线框模块：节点、服务器、数据库、云、客户端，用青白色 #7DD3FC 细线与发光边，节点间正交折线连接 + 小箭头；标签用等宽字体（monospace）全大写小字。图例 / 清单面板只在画面里确实有多种连线或符号需要解释时才加，且只列本页出现过的元素，不要为填充版面编造图例项。点缀极少量暖色 #F59E0B 强调关键节点。整体像工程蓝图 / 架构白皮书，信息密度高但网格秩序强；无照片、无卡通、无廉价霓虹。",
   "baselineBriefs": [
     {
       "title": "架构总览",

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，宿主左侧栏才会默认收起；此时顶栏给一个切换入口。