dsh-plugin-deck-studio 0.2.4 → 0.2.5

package/client.js

@@ -361,9 +361,88 @@ div[data-sidebar-collapsed]{grid-template-columns:0px minmax(0px,1fr) 0px!import
         return () => window.removeEventListener("message", onMessage);
       }, "deck-studio: prompt bridge");
 
+      /**
+       * F-164：自动新建的会话要落进一个 DSH 工作区，而不是「未分组」。
+       * F-165：显式 workspacePath → 启动目录所属工作区 / 登记启动目录 → 源目录工作区 → 默认工作区。
+       * 工作区创建失败必须报错，不能悄悄建立未分组会话。
+       */
+      /** 取一个可选服务：没 inject 的服务用 ctx.xxx 直取会 throw，这里统一吞掉。 */
+      function optionalService(name) {
+        try {
+          const viaGet = ctx.get?.(name);
+          if (viaGet) return viaGet;
+        } catch {
+          /* ctx.get 不可用 */
+        }
+        try {
+          return ctx[name] ?? null;
+        } catch {
+          return null;
+        }
+      }
+
+      async function resolveSessionWorkspace(data) {
+        const workspaces = optionalService("workspaces");
+        if (!workspaces?.list?.getSnapshot || !workspaces?.create) {
+          throw new Error("工作区服务不可用，未创建会话；请检查 DSH 版本并重试");
+        }
+        await workspaces.refresh?.();
+        const items = workspaces.list.getSnapshot().items ?? [];
+        const normalize = (path) => String(path ?? "").replace(/\\/g, "/").replace(/\/+$/, "");
+        const containing = (path) => items
+          .filter((item) => normalize(path) === normalize(item.path) || normalize(path).startsWith(`${normalize(item.path)}/`))
+          .sort((a, b) => b.path.length - a.path.length)[0];
+        const register = async (path) => {
+          const workspace = await workspaces.create({ path });
+          if (!workspace?.workspaceId) throw new Error("工作区创建未返回 workspaceId");
+          return workspace.workspaceId;
+        };
+        const configured = String(data.workspacePath ?? "").trim();
+        if (configured) return register(configured);
+        const cwd = String(data.cwd ?? "").trim();
+        if (cwd) {
+          const hit = containing(cwd);
+          if (hit) return hit.workspaceId;
+          // 不把插件安装目录或 DSH 私有数据目录登记成用户工作区。
+          const path = normalize(cwd);
+          const internal = /(^|\/)node_modules(\/|$)|(^|\/)\.dsh(\/|$)/.test(path);
+          if (path && path !== "/" && !internal) return register(cwd);
+        }
+        const sourceRoot = String(data.sourceRoot ?? "").trim();
+        const sourceWorkspace = sourceRoot ? containing(sourceRoot) : null;
+        if (sourceWorkspace) return sourceWorkspace.workspaceId;
+        const fallback = await workspaces.initializeDefault?.();
+        if (fallback?.workspaceId) return fallback.workspaceId;
+        throw new Error("无法确定启动工作区，未创建会话；请配置 workspacePath 后重试");
+      }
+
+      async function ensureConversationSession(data) {
+        const sessions = ctx.sessions;
+        if (!sessions?.create) throw new Error("sessions service unavailable");
+        const sessionId = String(data.sessionId ?? "").trim();
+        if (sessionId) {
+          await sessions.refresh?.();
+          const readPreset = () => {
+            const state = sessions.list?.getSnapshot?.();
+            const row = state?.byId?.[sessionId] || state?.items?.find((item) => (item.sessionId || item.id) === sessionId);
+            return row?.projectionValues?.agentPreset ?? row?.projections?.values?.agentPreset
+              ?? state?.projectionsBySession?.[sessionId]?.values?.agentPreset;
+          };
+          await sessions.refreshProjections?.(sessionId);
+          const preset = readPreset();
+          if (preset === "deck-studio") return sessionId;
+          if (!preset) throw new Error("无法核对会话模式，请刷新后重试；原会话已保留");
+          // 已有非空会话不能换 preset：保留原历史，另建制作会话，工作台负责追加绑定。
+        }
+        const workspaceId = await resolveSessionWorkspace(data);
+        const created = await sessions.create({ workspaceId, agentPreset: "deck-studio" });
+        if (!created) throw new Error("session create returned no id");
+        return created;
+      }
+
       /* 工作台 → 宿主：建/切会话并绑定 deck|design（F-43：每个会话必须有绑定）。
        * - action=open：切到给定 sessionId；
-       * - action=ensure：有 sessionId 就切过去；没有就 sessions.create({cwd}) 新建再切，
+       * - action=ensure：核对制作模式后复用，否则指定工作区和 Deckline preset 新建再切，
        *   然后可选地把首条 prompt 发进去（design 会话确认后「chat 开始工作」）。 */
       ctx.effect(() => {
         const onMessage = async (event) => {
@@ -377,19 +456,15 @@ div[data-sidebar-collapsed]{grid-template-columns:0px minmax(0px,1fr) 0px!import
             }
           };
           try {
-            const uiWorkspace = ctx.uiWorkspace ?? ctx.get?.("uiWorkspace");
+            const uiWorkspace = optionalService("uiWorkspace");
             if (!uiWorkspace?.openSession) throw new Error("uiWorkspace service unavailable");
             let sessionId = String(data.sessionId ?? "").trim();
-            if (data.action === "ensure" && !sessionId) {
-              const sessions = ctx.sessions;
-              if (!sessions?.create) throw new Error("sessions service unavailable");
-              // 注意：客户端 sessions.create 直接 resolve 新 sessionId，失败才 throw（不是 {ok,value}）。
-              sessionId = await sessions.create({ cwd: String(data.cwd ?? "") || undefined });
-              if (!sessionId) throw new Error("session create returned no id");
-            }
+            if (data.action === "ensure") sessionId = await ensureConversationSession(data);
             if (!sessionId) throw new Error("没有目标会话");
             if (data.action === "open" || data.action === "ensure") uiWorkspace.openSession(sessionId);
-            if (data.prompt && data.action === "ensure") await sendToSession(sessionId, String(data.prompt));
+            if (data.prompt && data.action === "ensure" && sessionId !== String(data.sessionId ?? "")) {
+              await sendToSession(sessionId, String(data.prompt));
+            }
             reply({ ok: true, sessionId });
           } catch (error) {
             ctx.logger?.warn?.("deck-studio: conversation bridge failed", error);

package/cordis.example.yml

@@ -16,6 +16,9 @@
     # dataRoot: '~/.dsh/deckline'
     # 可选：默认收起 DSH 外壳左侧栏（只建议在专门的产品 profile 里开；默认 false）
     hideShellSidebar: true   # 收起 DSH 外壳左侧栏（工作区/会话）；不想收就改 false
+    # F-164：工作台自动新建的会话落在哪个 DSH 工作区。留空 = 自动：
+    # 宿主启动目录所属工作区（没有则登记）→ deck 源目录所在工作区 → DSH 默认工作区。
+    # workspacePath: '~/Documents/我的 deck'
     bootstrap: true          # 首次启动自动登记示例 deck / 资源库 / 预设风格
     userName: ''  # 留空 = 首页只显示「欢迎你」
     # 新建 deck 的落盘根；留空 = 插件数据目录 .deck/projects/<id>/source

package/cordis.patch.yml

@@ -12,6 +12,10 @@
         userName: ''  # 留空 = 首页只显示「欢迎你」；填了就显示「XX，欢迎你」
         # F-157：产品默认收起 DSH 外壳左侧栏（工作区/会话那栏），要保留就改 false。
         hideShellSidebar: true
+        # F-164：工作台自动新建的会话落在哪个 DSH 工作区（目录）。
+        # 留空 = 自动：宿主启动目录所属工作区（没有则登记）→ deck 源目录所在工作区 → DSH 默认工作区。
+        # 想固定就填绝对路径（如 '~/Documents/我的 deck'），会自动登记成工作区。
+        # workspacePath: ''
         # F-157：首次启动自动登记示例 deck / 拷资源库 / 导入 8 个预设风格；不想要就改 false。
         bootstrap: true
         # 新建 deck 落盘根：留空 = 插件数据目录 .deck/projects/<id>/source

package/index.js

@@ -1705,6 +1705,7 @@ export function createService(config, logger, env = process.env) {
       uiVersion: uiVersion(),
       displayName: config.displayName,
       hideShellSidebar: config.hideShellSidebar === true,
+      workspacePath: config.workspacePath,
       dataRoot: config.dataRoot,
       toolsMounted: config.tools,
       renderMode: config.render.mode,
@@ -1968,7 +1969,10 @@ export function createService(config, logger, env = process.env) {
     }
     return {
       ...base,
-      cwd: repoRootFrom(PLUGIN_DIR),
+      // F-164：会话默认落在哪个目录 / 工作区。npm 布局下 repoRootFrom 会退到插件包内的 seeds/，
+      // 不能拿来当会话 cwd（会落到「未分组」）。优先显式配置的 workspacePath，否则用宿主启动目录。
+      cwd: config.workspacePath || process.cwd(),
+      workspacePath: config.workspacePath,
       config: {
         preset: "deck-studio",
         renderMode: config.render.mode,
@@ -2273,9 +2277,16 @@ export function apply(ctx, rawConfig) {
     const url = new URL(request?.url ?? "/", "http://localhost");
     const deckId = url.searchParams.get("deckId") ?? "";
     const docId = url.searchParams.get("docId") ?? "";
-    const doc = service.deckDoc(deckId, docId);
-    if (!doc) return json({ ok: false, error: { message: "unknown deck or doc" } }, 404);
-    return json({ ok: true, deckId, ...doc });
+    // F-163：读取失败要把真实原因吐给前端，不能 500 空手而归（前端以前会一直转圈）。
+    try {
+      const doc = service.deckDoc(deckId, docId);
+      if (!doc) return json({ ok: false, error: { message: `unknown deck or doc：deckId=${deckId || "(空)"} docId=${docId || "(空)"}` } }, 404);
+      return json({ ok: true, deckId, ...doc });
+    } catch (error) {
+      const message = String(error?.message ?? error);
+      logger?.warn?.(`deck-studio.doc 读取失败 deckId=${deckId} docId=${docId}：${message}`);
+      return json({ ok: false, error: { message } }, 500);
+    }
   });
 
   registerRoute(ROUTES.docfile, (request) => {

package/lib/config.js

@@ -18,7 +18,7 @@ import { fileURLToPath } from "node:url";
 export const PLUGIN_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
 
 /**
- * 资产根：开发仓库根 `<repo>/plugin/deck-studio/` 的上一级。
+ * 资产根：源码树根 `<repo>/plugin/deck-studio/` 的上一级。
  *
  * npm 安装时插件在 `<profile>/node_modules/dsh-plugin-deck-studio`，上两级是 node_modules，
  * 那里没有 samples / docs；公开包把手册与示例 deck 一起打进包内 `seeds/`（prepack 生成），
@@ -82,7 +82,7 @@ function normalizeDeck(raw, env) {
 }
 
 /** 展开 `~/` 前缀；其余原样。 */
-/** 默认数据根：安装用户的可写位置（不落进插件包 / node_modules）。开发仓库可在 profile 里显式配 dataRoot。 */
+/** 默认数据根：安装用户的可写位置（不落进插件包 / node_modules）。源码调试时可在 profile 里显式配 dataRoot。 */
 export function defaultDataRoot(env = process.env) {
   return join(expandHome(env.DSH_HOME || "~/.dsh", env), "deckline");
 }
@@ -179,6 +179,17 @@ export function mergeConfig(raw, options = {}) {
      * 开发/其他 profile 的 DSH 界面不受影响。
      */
     hideShellSidebar: input.hideShellSidebar === true,
+    /**
+     * F-164：工作台自动新建的会话落在哪个 DSH 工作区（目录）。
+     * 留空 = 自动：先找 deck 源目录所在工作区，再找宿主 cwd 工作区，再退回 DSH 默认工作区；
+     * 填了就把这个目录登记/复用一个工作区，会话固定落在那里（不再出现「未分组」）。
+     */
+    workspacePath: expandHome(
+      typeof input.workspacePath === "string" && input.workspacePath.trim()
+        ? input.workspacePath.trim()
+        : (env.DSH_DECK_WORKSPACE_PATH ?? ""),
+      env,
+    ),
     /**
      * 新建 Deck 弹窗默认预选的登记风格（F-112）：填 design 缩写（如 GRD）。
      * 留空 = 不预选。只在 UI 预选，不改变任何已有 deck 的关联风格。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-deck-studio",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "private": false,
   "description": "Deckline：DSH 的 image deck / PPT 工作台插件——原生 Chat + 整页图片 deck 工作区 + 设计风格库；用对话做 PPT、按页出图、版本可追踪、导出 PDF/PPTX。",
   "license": "MIT",

package/seeds/docs/compat.md

@@ -1,7 +1,7 @@
 # DSH 兼容矩阵（定期回归记录）
 
 > 口径：DSH 处于 prerelease 阶段，没有 stable 线；本项目**定期批次**回归，不逐 rc 跟。
-> 每个批次记录：证实的版本、验证范围、断点、复现方式。已知限制与路线见 [productization.md](productization.md) 与 [install.md](install.md)。
+> 每个批次记录：证实的版本、验证范围、断点、复现方式。已知限制见 [install.md](install.md) 的故障排查部分。
 
 ## 当前支持声明
 

package/seeds/docs/install.en.md

@@ -105,8 +105,7 @@ Drop a `deck.rules.md` at the root of a deck project to describe the creative co
 - It **cannot override** the product's hard rules (read-only source decks / QA gates / no fabrication /
   user confirmation). In a conflict the hard rules win and the agent says so.
 - Max 8 KB; it is never written back and never triggers any automatic action.
-- Do not name it `AGENTS.md`: that belongs to DSH workspace instructions and Deckline does not depend on it
-  (see `docs/adr/0020` in the development repo).
+- Do not name it `AGENTS.md`: that belongs to DSH workspace instructions and Deckline does not depend on it.
 
 ## 2.5 Where the data lives: source deck / documents / images / exports
 
@@ -132,8 +131,8 @@ creating a deck, check this table first.
   ```sh
   tar czf deckline-backup-$(date +%Y%m%d).tgz "$DSH_HOME/deckline" "<your projectsRoot>"
   ```
-- The workbench **Settings** panel shows the current data directory; in the development repo the data root
-  is the repo's `.deck/` (configured explicitly in the profile).
+- The workbench **Settings** panel shows the current data directory; a dev profile may point `dataRoot` at
+  a directory inside the source tree (e.g. `.deck/`) explicitly.
 
 ## 3. Start
 

package/seeds/docs/install.md

@@ -137,7 +137,7 @@ Deck Agent 每次 `deck_source_overview` 时会读到并遵守：
 - 只约束**这一份 deck**，不影响其他 deck；不写就等于没有规则（可选能力）。
 - 它**不能覆盖**产品硬纪律（客户源只读 / QA 门禁 / 不编造 / 需用户确认）——冲突时以硬纪律为准，Agent 会说明。
 - 上限 8 KB；读取时不会回写，也不会因为文件内容自动执行任何操作。
-- 不叫 `AGENTS.md`：`AGENTS.md` 属于 DSH 的工作区指令，Deckline 不依赖它（见开发仓库的 `docs/adr/0020`）。
+- 不叫 `AGENTS.md`：`AGENTS.md` 属于 DSH 的工作区指令，Deckline 不依赖它。
 
 ## 2.5 数据在哪里：源 deck / 文档 / 图片 / 导出
 
@@ -194,7 +194,7 @@ Deckline 支持：
 3. 填：**模式**（fake / real）、**生图节点 endpoint**、**模型**、**key 环境变量名**（或 **key 文件路径**）、**出图尺寸**；
 4. 点 **保存并生效**。
 
-保存后写入本机数据目录 `~/.dsh/deckline/render-settings.json`（开发仓库里是 `.deck/render-settings.json`，
+保存后写入本机数据目录 `~/.dsh/deckline/render-settings.json`（开发调试时也可用 profile 显式配 `dataRoot`，例如仓库内 `.deck/`；
 已 gitignore）：节点可直存 API key（0600，界面只显示「已保存」，payload 不回显），也可改用变量名 / key 文件；
 下次启动自动生效，并覆盖 profile 里的 render 配置。
 

package/ui/workbench.html

@@ -1411,14 +1411,30 @@ async function fetchDoc(docId) {
   if (STATE.docCache[docId]) return STATE.docCache[docId];
   if (STATE.docLoading === docId) return null;
   STATE.docLoading = docId;
+  const deckId = STATE.data?.active?.deckId ?? "";
+  // F-163：加载失败必须可见。以前只 throw，中间的 spinner 永远不停，用户不知道是 404、500 还是超时。
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), 15000) : null;
   try {
-    const deckId = STATE.data.active.deckId;
-    const res = await fetch(`/api/deck-studio.doc?` + new URLSearchParams({ deckId, docId }));
-    if (!res.ok) throw new Error("HTTP " + res.status);
-    const doc = await res.json();
-    if (doc.ok) STATE.docCache[docId] = doc;
+    const res = await fetch(
+      `/api/deck-studio.doc?` + new URLSearchParams({ deckId, docId }),
+      controller ? { signal: controller.signal } : undefined,
+    );
+    const text = await res.text();
+    let doc = null;
+    try { doc = JSON.parse(text); } catch { doc = null; }
+    if (!res.ok || !doc || doc.ok === false) {
+      const detail = doc?.error?.message || text.replace(/\s+/g, " ").trim().slice(0, 200) || res.statusText;
+      throw new Error(`${res.status} · ${detail}`);
+    }
+    STATE.docCache[docId] = doc;
     return doc;
+  } catch (error) {
+    const message = error?.name === "AbortError" ? "请求超时（15 秒没有响应）" : String(error?.message ?? error);
+    console.warn(`[deck-studio] 读取文档失败 docId=${docId} deckId=${deckId}：${message}`);
+    return { ok: false, docId, error: { message } };
   } finally {
+    if (timer) clearTimeout(timer);
     STATE.docLoading = null;
   }
 }
@@ -1430,6 +1446,18 @@ async function renderDocTab(docId) {
   if (!cached) view.innerHTML = `<div class="observe-body"><div class="doc-loading">读取 ${esc(index?.label ?? docId)} …</div></div>`;
   const doc = cached ?? (await fetchDoc(docId));
   if (!doc || STATE.tab !== docId) return; // 加载期间用户已切走
+  if (doc.ok === false) {
+    view.innerHTML = `<div class="observe-body">
+      <div class="doc-loading">读取「${esc(index?.label ?? docId)}」失败：${esc(doc.error?.message || "未知错误")}</div>
+      <p style="text-align:center;margin-top:10px"><button type="button" class="btn" data-doc-retry="${esc(docId)}">重试</button></p>
+      <p class="small" style="text-align:center">先在终端看服务端日志；若一直失败，把上面这行错误发我。</p>
+    </div>`;
+    view.querySelectorAll("[data-doc-retry]").forEach((btn) => btn.addEventListener("click", () => {
+      STATE.docCache[docId] = null;
+      renderDocTab(docId);
+    }));
+    return;
+  }
   view.innerHTML = `<div class="observe-body">${renderDoc(doc, index)}</div>`;
   bindDocActions(view);
 }
@@ -2780,15 +2808,19 @@ async function ensurePromptConversation() {
   if (!target) return;
   const bound = chatSessionsForTarget(target);
   if (bound.length) {
-    const current = currentChatSessionId();
-    if (bound.some((session) => session.sessionId === current)) return;
-    await openBoundConversation(bound[0].sessionId);
+    // 发送操作也要核对 preset，不能只因绑定存在就向标准模式发制作指令。
+    const result = target.kind === "deck"
+      ? await ensureDeckConversation(target.id)
+      : await openDesignProject(target.id);
+    if (!result?.ok) throw new Error(result?.reason || "无法打开 Deckline 制作会话");
     await new Promise((resolve) => setTimeout(resolve, 250));
     return;
   }
   const active = STATE.data?.active;
-  if (active?.kind === "design-canvas") await openDesignProject(active.designId);
-  else if (active?.deckId) await ensureDeckConversation(active.deckId);
+  const result = active?.kind === "design-canvas"
+    ? await openDesignProject(active.designId)
+    : active?.deckId ? await ensureDeckConversation(active.deckId) : null;
+  if (!result?.ok) throw new Error(result?.reason || "无法打开 Deckline 制作会话");
   await new Promise((resolve) => setTimeout(resolve, 250));
 }
 
@@ -2809,6 +2841,8 @@ async function sendAgentPrompt() {
     }
     state.textContent = "已发送到左侧对话 ✓";
     setTimeout(closeAgentPrompt, 900);
+  } catch (error) {
+    state.textContent = `未能发送：${error?.message || error}`;
   } finally {
     button.disabled = false;
   }
@@ -3788,7 +3822,14 @@ function requestConversation(payload) {
       resolve({ ok: Boolean(event.data.ok), sessionId: event.data.sessionId || "", reason: event.data.reason || "" });
     };
     window.addEventListener("message", onAck);
-    target.postMessage({ type: "dsh-deck-studio:conversation", requestId, cwd: STATE.data?.cwd || "", ...payload }, "*");
+    target.postMessage({
+      type: "dsh-deck-studio:conversation",
+      requestId,
+      cwd: STATE.data?.cwd || "",
+      workspacePath: STATE.data?.workspacePath || "",
+      sourceRoot: STATE.data?.active?.sourceRoot || "",
+      ...payload,
+    }, "*");
     setTimeout(() => {
       if (settled) return;
       cleanup();
@@ -3850,14 +3891,17 @@ async function ensureDeckConversation(deckId) {
   const chosen = bound[0] || null;
   const binding = chosen ? { sessionId: chosen.sessionId } : null;
   const result = await requestConversation({
-    action: chosen ? "open" : "ensure",
+    action: "ensure",
     sessionId: chosen?.sessionId || "",
     kind: "deck",
     id: deckId,
     title: label,
-    prompt: chosen ? "" : `本对话绑定 deck ${deckId}（${label}）。后续所有修改都在这个 deck 上进行；先读 intent 与 script 概要，等我的指令，不要直接出图。`,
+    prompt: `本对话绑定 deck ${deckId}（${label}）。后续所有修改都在这个 deck 上进行；先读 intent 与 script 概要，等我的指令，不要直接出图。`,
   });
-  if (!result.ok) return result;
+  if (!result.ok) {
+    getEl("chatBindChip").textContent = `会话打开失败：${result.reason || "未知原因"}`;
+    return result;
+  }
   if (!binding || binding.sessionId !== result.sessionId) {
     await bindConversation({ sessionId: result.sessionId, kind: "deck", id: deckId, title: label });
   }
@@ -3872,25 +3916,28 @@ async function openDesignProject(designId) {
   const project = (STATE.data?.designProjects || []).find((item) => item.designId === designId);
   if (!project) return;
   showDeck(project.canvasDeckId);
-  const binding = bindingOf("design", designId);
+  const target = chatTargetForBinding({ kind: "design", id: designId });
+  const binding = chatSessionsForTarget(target)[0] || null;
   const title = `风格 · ${project.name}`;
   const result = await requestConversation({
-    action: binding ? "open" : "ensure",
+    action: "ensure",
     sessionId: binding?.sessionId || "",
     kind: "design",
     id: designId,
     title,
-    prompt: binding ? "" : buildDesignPrompt(project, project.canvasDeckId),
+    prompt: buildDesignPrompt(project, project.canvasDeckId),
   });
   if (result.ok && (!binding || binding.sessionId !== result.sessionId)) {
     await bindConversation({ sessionId: result.sessionId, kind: "design", id: designId, title });
   } else if (!result.ok) {
     STATE.lastConvError = result.reason || "未知原因";
+    getEl("chatBindChip").textContent = `会话打开失败：${STATE.lastConvError}`;
   }
   if (result.ok) {
     STATE.chatSessionId = result.sessionId;
     renderChatHeader();
   }
+  return result;
 }
 
 /** Conversations 页点会话：切过去，并把工作台切到它绑定的 deck / design 画布。 */

package/seeds/docs/productization.en.md

@@ -1,212 +0,0 @@
-# Productization plan (Deckline · DSH image-deck plugin)
-
-简体中文 · [English](productization.en.md)
-
-> Goal: turn "a DSH plugin that works on Yuna's machine" into a product that **anyone can install in
-> 5 minutes, configure with their own decks and image key, and start using**.
->
-> This document is the full plan + current-state inventory + phased acceptance. Execution is tracked in
-> `docs/feedback.md` (F-54…F-57) and `tasks.md` (P27).
-
-## 1. Product shape and positioning
-
-- **Shape**: a DSH (DeepSeek Harness) **bundle plugin** + a dedicated profile (`deckline`).
-  Not a standalone app; DSH owns chat / models / permissions, Deckline owns the "full-page image deck"
-  workbench.
-- **One-liner**: turn "who is this for, what is the point, how do slides get made" into a traceable
-  pipeline — discuss in chat → script / intent / governance documents → per-page image prompt →
-  one-page renders + revisions → export / handoff.
-- **Non-goals**: no HTML deck renderer (separate project); no default batch rendering of a whole deck;
-  never modify the user's deck source directory.
-- **Target users**: consultants / trainers / internal communicators / content creators who already use
-  DSH or are willing to install it.
-
-## 2. Current state (available / gaps)
-
-| Capability | Current state | Productization gap |
-|---|---|---|
-| DSH plugin form | ✅ bundle + preset + client panel | Package metadata is clean (MIT / direct name / no personal paths, see §10) |
-| Installation | ✅ three ways: npm direct name / git subdirectory / local clone (`docs/install.md`) | npm not published yet (owner action) |
-| Configuration | ✅ profile patch + `cordis.example.yml` + env conventions (personal paths all moved to the local patch) | Team-shared config templates (Phase 3) |
-| Image key | ✅ `apiKeyEnv` / `apiKeyFile`; UI only shows whether a key is configured | Docs + clearer guidance in the Settings panel |
-| Styles | ✅ add style (paste/upload/drag) + 8 presets | Presets ship with the plugin + one-click import (done) |
-| Data | ✅ `.deck/` fully gitignored, source decks read-only | "where is data / how to back up / how to migrate" docs |
-| Verification | ✅ smoke 46 + harness gate + 16-scenario agent eval + real-machine Playwright checks | CI / public fixtures (Phase 1) |
-| Docs | ✅ README (zh/en) + install / styles / sample-deck docs (zh/en) + compatibility matrix | productization English, contributing guide, screenshots (Phase 2) |
-
-## 3. Phased plan (recommended cadence)
-
-### Phase 0 · Installable (v0.1, 1–2 days)
-
-- [x] Plugin package metadata: `repository` / `homepage` / `keywords` / `peerDependencies`;
-- [x] Default config template: `plugin/deck-studio/cordis.example.yml` (decks / projectsRoot / render nodes);
-- [x] Install docs `docs/install.md` (npm / git / local, key config, troubleshooting);
-- [x] README made public-facing (intro / 5-minute install / config / adding a design / styles);
-- [x] Preset styles ship with the plugin: `seeds/styles/*.json` + `seeds/samples/*.jpg` + "＋ Import preset styles";
-- [x] Adding a design supports paste / drag / file picker; existing styles can take more samples;
-- [x] Image key: Settings panel shows nodes + "key configured" + missing-key hints;
-- [x] Moved personal config from the **plugin default patch** into the profile patch (distributable defaults) — migrated and verified via `--dump-config`.
-
-**Acceptance**: a clean machine (macOS/Linux, Node `^22.19` or `≥24` + pnpm + DSH) following the README
-can: start → create a deck → create a style (paste an image) → see key status in Settings → run one render
-in fake mode.
-
-### Phase 1 · Distributable (v0.1.0, ready; release awaits the owner)
-
-- [x] **License: MIT** (owner decision, 2026-10-21) — `LICENSE` in the repo, package metadata aligned;
-- [x] **Direct package name**: `dsh-plugin-deck-studio`, no org / scope; `private: false`;
-- [x] **Public scope** (owner decision): plugin + public docs + preset designs (seeds) + 1 sample deck + 1 sample logo;
-  → `scripts/build-public-bundle.mjs` produces a **whitelisted clean directory** (no internal ledgers / client
-  names / personal paths / git history);
-- [x] Sample logo: `assets/logo/deckline-logo.svg|png` + mark; referenced at the top of README;
-- [x] Sample deck: `samples/deckline-intro/` (10-page Deckline product handbook source + paste-ready
-  walkthrough in `docs/sample-deck.md`);
-- [x] Privacy scan: plugin code sanitized (all client names / personal paths / key names replaced), the
-  bundler has a built-in forbidden-word scan;
-- [x] `CHANGELOG.md` + v0.1.0;
-- [ ] **Publish the repository**: `gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push`
-  (after owner confirmation; do not push the development repo — its history contains internal process docs and client information);
-- [ ] `npm publish dsh-plugin-deck-studio` (npm account + 2FA required);
-- [ ] Add 3 real screenshots/GIF at the top of README (before going public);
-- [ ] GitHub Actions:
-  - `ci.yml`: `node --check` + smoke (`plugin/deck-studio/verify/smoke.mjs`) + commit message lint;
-  - `release.yml`: `npm publish` on tag (via `NPM_TOKEN` secret);
-- [x] Version compatibility: `peerDependencies` / `engines.dsh` declare `0.1.7–0.2.x`; `docs/compat.md`
-  records two regression batches (0.1.7-rc.2 / 0.2.1-rc.2).
-
-### Phase 2 · Easy onboarding (v0.3, 1 week)
-
-- [ ] First-run wizard: when there are no decks, guide through "new deck / import preset styles / configure key";
-- [ ] "New Deck" form can pick a preset style (currently free-text only);
-- [ ] Style library page: preview / search / tags (business, fancy, Japanese…), apply to a new deck in one click;
-- [ ] Data management: visualize the `.deck` location, backup/export button (zip);
-- [ ] i18n: Chinese + English (DSH itself supports multiple languages) — public docs are bilingual; UI strings pending;
-- [ ] Error reporting: actionable render failure reasons (key / quota / model name / size).
-
-### Phase 3 · Collaborative (v0.4+)
-
-- [ ] Multi-user / team-shared profile config templates (keys never shared);
-- [ ] Style-pack marketplace (community contributes `seeds/styles`, PRs validated for schema + samples);
-- [ ] Render cost estimation / usage stats (per node);
-- [ ] Deck source adapters for more directory conventions (currently scans `outputs/full/final`, `outputs/final`, `pages`, `images`, `exports`).
-
-### Phase 4 · Optional (on demand)
-
-- Desktop build (DSH desktop already exists), Docker image, SaaS hosting;
-- Object storage / image CDN integration (renders go straight to a CDN);
-- HTML deck renderer (separate project, not in this repository).
-
-## 4. How the Git repo goes public (concrete steps)
-
-> Owner decision: **public scope = plugin + public docs + preset designs + 1 sample deck + 1 sample logo**.
-> The current development repo's git history contains internal ledgers (feedback / tasks / client names /
-> personal paths) and **must not be pushed directly**. Generate a clean whitelisted directory, then create
-> a new public repository from it.
-
-```sh
-# 1) Generate the clean directory (whitelist + privacy scan; output in dist/public, gitignored)
-node scripts/build-public-bundle.mjs
-#    ✔ whitelist + privacy scan pass (see script output), no /Users/ paths, no client names, no keys
-
-# 2) Create the public repo (after owner confirmation; account yuna78)
-gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push
-
-# 3) Fill in repo metadata: About = "DSH image deck workbench plugin",
-#    Topics = deepseek-harness, dsh-plugin, image-deck, presentation, deck
-# 4) Tag / release
-cd dist/public && git tag v0.1.0 && git push origin v0.1.0
-gh release create v0.1.0 --notes "First public release: install via dsh plugin add dsh-plugin-deck-studio"
-
-# 5) npm publish (Phase 1)
-cd plugin/deck-studio
-npm publish --access public     # npm account + 2FA required
-```
-
-**Public bundle contents (whitelist)**:
-
-- `README.md` / `LICENSE` / `CHANGELOG.md`;
-- `docs/`: `productization.md` + `productization.en.md`, `install.md` + `install.en.md`, `styles.md` + `styles.en.md`,
-  `sample-deck.md` + `sample-deck.en.md`, `compat.md`;
-- `plugin/deck-studio/`: the plugin itself (host + client + ui + lib + seeds preset styles/samples + verify smoke);
-- `samples/deckline-intro/`: sample deck source (README / intent / script);
-- `assets/logo/`: sample logo (svg + png).
-
-**Not public**: `CURRENT.md` / `HANDOVER.md` / `tasks.md` / `docs/feedback.md` / `docs/architecture.md` /
-`docs/adr/` / `docs/research/` / `fixtures/` (contain local references to client material) / `.deck/` (runtime
-data) / git history.
-
-**Cleanup already done**:
-
-1. Personal paths in `cordis.patch.yml` → profile patch; the repo carries a generic bundle patch + `cordis.example.yml`;
-2. Plugin `package.json`: `private: false`, MIT, direct package name, repository / homepage / peerDependencies;
-3. Plugin code sanitized: client names, personal paths and env var names in `client.js` / `lib/config.js` /
-   `lib/deck-workspace.js` / `lib/render-nodes.js` / `lib/source-adapter.js` / `lib/tools.js` / `verify/smoke.mjs`
-   replaced with generic examples;
-4. The bundler has a built-in forbidden-word scan (client names / `/Users/` / `sk-` / private key names); a hit
-   aborts the build.
-
-## 5. Install and distribution matrix
-
-| Method | Command | For |
-|---|---|---|
-| npm | `dsh plugin --profile deckline add dsh-plugin-deck-studio` | Regular users (after publish) |
-| Git | `dsh plugin --profile deckline add "github:yuna78/dsh-deck-studio#path:/plugin/deck-studio"` | People tracking main |
-| Local clone | `dsh plugin --profile deckline add "$PWD/plugin/deck-studio"` | Developers / customization |
-
-All three land in `~/.dsh/profiles/deckline/`; after installing, users only edit the **profile patch**
-(decks / projectsRoot / render nodes) and never the plugin package — that boundary is what makes
-"anyone can install it" true.
-
-## 6. Configuration conventions (image key)
-
-- Configuration exists in exactly two places: the **profile patch** (structure) and **env vars / key files** (credentials);
-- The structure only holds `apiKeyEnv` (variable name) or `apiKeyFile` (local path), **never a plaintext key**;
-- The workbench Settings panel only shows the `keyConfigured` boolean + source name;
-- Multiple nodes supported (primary / backup / different models), each with its own key;
-- Missing key: fake mode still runs the full flow; real mode reports where to configure it.
-
-## 7. Style ecosystem (the productization differentiator)
-
-- **Preset bundle ships with the plugin**: `plugin/deck-studio/seeds/styles/<ABBR>.json` (definitions with
-  `styleBrief` + `baselineBriefs`) + `seeds/samples/<ABBR>-0{1,2,3}.jpg` (3 baseline samples);
-- **One-click import**: Designs page "＋ Import preset styles", existing abbreviations are skipped (idempotent);
-- **Add your own**: paste/upload/drag in the UI; or drop images into `designs/<ABBR>/`;
-- **Contribute**: a PR adds one JSON + 3 baseline samples (schema: abbr / name / description / constraints /
-  reference / styleBrief / baselineBriefs);
-- Known limitation: samples illustrate a style, not guarantee verbatim reproduction of their text (a general
-  image-model limitation); for exact text, overlay HTML/Mermaid text afterwards.
-
-## 8. Risks and boundaries
-
-| Risk | Description | Mitigation |
-|---|---|---|
-| DSH plugin API changes | The plugin depends on the DSH version | Declared peer range + CI smoke + compatibility docs |
-| Credential leakage | Users paste a key into the patch | Docs stress apiKeyEnv / apiKeyFile; Settings never echoes keys |
-| Runaway render cost | Users batch-render everything | Named batches / whole-deck renders are allowed (per-page revisions, single-page retries); no one-click button, to avoid accidents |
-| Client data | Deck sources may be sensitive | Sources read-only, output local under `.deck`, repo carries no data; export packages sanitized |
-| Model quality | Garbled text, broken layouts | Style prompt constraints + "little text, English" advice + post-edit overlays |
-
-## 9. Milestones (suggested)
-
-- **M1 (this week)**: Phase 0 complete + 8 preset styles imported and usable locally;
-- **M2 (next week)**: repository public + v0.1.0 release + 2 external users install successfully;
-- **M3 (within two weeks)**: npm publish + CI + first-run wizard;
-- **M4 (one month)**: style library page + bilingual UI + community style packs.
-
-## 10. Decisions made (2026-10-21)
-
-| # | Decision | Outcome | Implementation |
-|---|---|---|---|
-| 1 | License | **MIT** | `LICENSE` + package.json `license: MIT` |
-| 2 | Package name | **Direct, no org**: `dsh-plugin-deck-studio` | package.json `name` / `private: false` |
-| 3 | Public scope | Plugin + docs + preset designs + **1 sample deck** + **1 sample logo** | `scripts/build-public-bundle.mjs` whitelist; no internal ledgers or history |
-| 4 | Brand | **Deckline** confirmed (repo name stays `dsh-deck-studio`) | README / UI / logo |
-| 5 | Public account | GitHub `yuna78`; repo `yuna78/dsh-deck-studio` (public) | `gh repo create` + push after owner confirmation |
-
-**Two actions still waiting on the owner**:
-
-1. Confirm going public: run `node scripts/build-public-bundle.mjs`, then
-   `gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push`;
-2. npm publish: `cd plugin/deck-studio && npm publish --access public` (needs npm login + 2FA).
-
-CI / release / screenshots come in the iterations after this round.

package/seeds/docs/productization.md

@@ -1,193 +0,0 @@
-# 产品化计划（Deckline · DSH image deck 插件）
-
-简体中文 · [English](productization.en.md)
-
-> 目标：把现在这个「在 Yuna 机器上跑通的 DSH 插件」变成**任何人在自己机器上 5 分钟内装好、
-> 配好自己的 deck 和生图 key、开始用**的产品。
->
-> 本文是完整计划 + 现状盘点 + 分阶段验收。执行登记见 `docs/feedback.md` F-54…F-57、`tasks.md` P27。
-
-## 1. 产品形态与定位
-
-- **形态**：DSH（DeepSeek Harness）的 **bundle 插件** + 一个专用 profile（`deckline`）。
-  不是独立 App；DSH 负责 chat / 模型 / 权限，Deckline 负责「整页图片 deck」的工作台。
-- **一句话**：把「讲给谁、讲什么、怎么出图」变成一条可追踪的产线——
-  Chat 里讨论 → script / intent / 治理文档 → 逐页 image prompt → 单页出图 + 版本 → 导出 / 交接。
-- **不做什么**：不做 HTML deck 渲染器（另立项目）；不默认批量出整套图；不改用户 deck 源目录。
-- **目标用户**：咨询 / 培训 / 内部汇报 / 内容创作者，已经有 DSH 或愿意装 DSH 的人。
-
-## 2. 现状盘点（已具备 / 缺口）
-
-| 能力 | 现状 | 产品化缺口 |
-|---|---|---|
-| DSH 插件形态 | ✅ bundle + preset + 客户端面板 | 包元数据已整理（MIT / 直发名 / 无个人路径，见 §10） |
-| 安装 | ✅ npm 直发包名 / git 子目录 / 本地 clone 三种方式（`docs/install.md`） | npm 尚未发布（负责人执行） |
-| 配置 | ✅ profile patch + `cordis.example.yml` + env 口径（个人路径已全部下沉到本机 patch） | 团队共享配置模板（Phase 3） |
-| 生图 key | ✅ `apiKeyEnv` / `apiKeyFile`，界面只显示是否配置 | 缺文档 + 设置面板更明确的引导 |
-| 风格 | ✅ 添加风格（贴图/上传/拖拽/粘贴）+ 8 个预设 | 预设需要随插件分发 + 一键导入（已做） |
-| 数据 | ✅ `.deck/` 全部 gitignore，源 deck 只读 | 缺「数据在哪 / 怎么备份 / 怎么迁移」说明 |
-| 验证 | ✅ smoke 46 项 + harness 门禁 + Agent 评估 16 场景 + 真机 Playwright 验证 | CI / 公开 fixture（Phase 1） |
-| 文档 | ✅ README（中/英）+ 安装 / 风格目录 / 示例 deck 文档（中/英）+ 兼容矩阵 | productization 英译、贡献指南、截图（Phase 2） |
-
-## 3. 分阶段计划（建议按此节奏）
-
-### Phase 0 · 可安装（v0.1，1–2 天）
-
-- [x] 插件包元数据：加 `repository` / `homepage` / `keywords` / `peerDependencies`（`private: true` + `UNLICENSED` 暂留防误发，license 拍板后改）；
-- [x] 默认配置模板：`plugin/deck-studio/cordis.example.yml`（decks / projectsRoot / render 节点）；
-- [x] 安装文档 `docs/install.md`（npm / git / 本地 三种方式 + key 配置 + 排障）；
-- [x] README 对外化（产品介绍 / 5 分钟安装 / 配置 / 加 design / 风格）；
-- [x] 预设风格随插件分发：`seeds/styles/*.json` + `seeds/samples/*.jpg` + 「＋ 导入预设风格」；
-- [x] 添加 design 支持贴图 / 拖拽 / 选文件；已有风格可继续加样张；
-- [x] 生图 key：工作台设置面板显示节点 + 「key 是否配置」+ 缺 key 提示；
-- [x] 把当前机器上的个人配置从**插件默认 patch** 挪到 profile patch（保证默认包可分发）——已迁移并用 `--dump-config` 验证。
-
-**验收**：一台干净机器（macOS/Linux，Node `^22.19` 或 `≥24` + pnpm + DSH）按 README 走完能：启动 → 建 deck →
-建风格（贴图）→ 设置里看到 key 状态 →（fake 模式）走完一次出图。
-
-### Phase 1 · 可分发（v0.1.0，已就绪，待负责人执行发布）
-
-- [x] **许可证：MIT**（负责人 2026-10-21 拍板）——`LICENSE` 已落仓库，包元数据同步；
-- [x] **包名直发**：`dsh-plugin-deck-studio`，无 org / scope；`private: false`；
-- [x] **公开范围**（负责人拍板）：插件 + 对外 docs + 预设 design（seeds）+ 1 个 sample deck + 1 个 sample logo；
-  → 用 `scripts/build-public-bundle.mjs` 生成**白名单干净目录**（不含内部台账 / 客户名 / 个人路径 / git 历史）；
-- [x] sample logo：`assets/logo/deckline-logo.svg|png` + mark；README 顶部已引用；
-- [x] sample deck：`samples/deckline-intro/`（Deckline 产品说明手册 10 页源 + 可粘贴跑通流程文案 `docs/sample-deck.md`）；
-- [x] 隐私扫描：插件代码已脱敏（客户名 / 个人路径 / key 名全部换掉），打包脚本内置禁用词扫描；
-- [x] `CHANGELOG.md` + v0.1.0；
-- [ ] **仓库公开**：`gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push`
-  （需负责人确认后执行；不要推当前开发仓库——它的 git 历史含内部过程文档与客户信息）；
-- [ ] `npm publish dsh-plugin-deck-studio`（需 npm 账号 + 2FA）；
-- [ ] README 顶部补 3 张真机截图/GIF（公开前）；
-- [ ] GitHub Actions：
-  - `ci.yml`：`node --check` + smoke（`plugin/deck-studio/verify/smoke.mjs`）+ 提交信息规范；
-  - `release.yml`：tag 时 `npm publish`（用 `NPM_TOKEN` secret）；
-- [x] 版本兼容：`peerDependencies` / `engines.dsh` 声明 `0.1.7–0.2.x`；`docs/compat.md` 记录 0.1.7-rc.2 / 0.2.1-rc.2 两批回归。
-
-### Phase 2 · 好上手（v0.3，1 周）
-
-- [ ] 首次启动向导：无 deck 时引导「新建 deck / 导入预设风格 / 配 key」三步；
-- [ ] 「新建 Deck」表单支持从预设风格里选（现在只能手填风格）；
-- [ ] 风格库页面：预览 / 搜索 / 标签（商务、fancy、日系…），一键套用到新 deck；
-- [ ] 数据管理：`.deck` 位置可视化、备份/导出按钮（zip）；
-- [ ] i18n：中文 + English（DSH 本身支持多语言）——公开文档已中英双语，UI 文案待做；
-- [ ] 错误上报：出图失败给出可操作原因（key / 配额 / 模型名 / 尺寸）。
-
-### Phase 3 · 可协作（v0.4+）
-
-- [ ] 多用户 / 团队共享 profile 配置模板（不共享 key）；
-- [ ] 风格包 marketplace（社区贡献 `seeds/styles`，PR 校验 schema + 样张）；
-- [ ] 出图成本估算 / 用量统计（按节点）；
-- [ ] Deck 源适配更多目录约定（现在扫描 `outputs/full/final`、`outputs/final`、`pages`、`images`、`exports`）。
-
-### Phase 4 · 可选（视需求）
-
-- 桌面版（DSH desktop 已有）、Docker 镜像、SaaS 托管；
-- 与对象存储 / 图床集成（出图直接进 CDN）；
-- HTML deck 渲染器（独立项目，不在本仓库）。
-
-## 4. Git 如何公开（具体步骤）
-
-> 负责人已拍板：**公开范围 = 插件 + 对外 docs + 预设 design + 1 个 sample deck + 1 个 sample logo**。
-> 当前开发仓库的 git 历史含内部台账（feedback / tasks / 客户名 / 个人路径），**不能直接 push**。
-> 用白名单脚本生成干净目录，再创建一个新的公开仓库。
-
-```sh
-# 1) 生成干净目录（白名单 + 隐私扫描；产物在 dist/public，已 gitignore）
-node scripts/build-public-bundle.mjs
-#    ✔ 白名单 + 隐私扫描通过（以脚本输出为准），无 /Users/ 个人路径、无客户名、无 key
-
-# 2) 建公开仓库（负责人确认后执行；账号 yuna78）
-gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push
-
-# 3) 补仓库元信息：About = "DSH image deck workbench plugin"，
-#    Topics = deepseek-harness, dsh-plugin, image-deck, presentation, deck
-# 4) 打 tag / 发 Release
-cd dist/public && git tag v0.1.0 && git push origin v0.1.0
-gh release create v0.1.0 --notes "First public release: install via dsh plugin add dsh-plugin-deck-studio"
-
-# 5) npm 发布（Phase 1）
-cd plugin/deck-studio
-npm publish --access public     # 需要 npm 账号 + 2FA
-```
-
-**公开包内容（白名单）**：
-
-- `README.md` / `LICENSE` / `CHANGELOG.md`；
-- `docs/`：`productization.md`、`install.md` + `install.en.md`、`styles.md` + `styles.en.md`、`sample-deck.md` + `sample-deck.en.md`、`compat.md`；
-- `plugin/deck-studio/`：插件本体（宿主 + 客户端 + ui + lib + seeds 预设风格/样张 + verify smoke）；
-- `samples/deckline-intro/`：示例 deck 源（README / intent / script）；
-- `assets/logo/`：sample logo（svg + png）。
-
-**不公开**：`CURRENT.md` / `HANDOVER.md` / `tasks.md` / `docs/feedback.md` / `docs/architecture.md` /
-`docs/adr/` / `docs/research/` / `fixtures/`（含客户材料的本地源引用）/ `.deck/`（运行数据）/ git 历史。
-
-**已完成的清理**：
-
-1. `cordis.patch.yml` 个人路径 → profile patch；仓库里是通用 bundle patch + `cordis.example.yml`；
-2. 插件 `package.json`：`private: false`、MIT、直发包名、repository / homepage / peerDependencies；
-3. 插件代码脱敏：`client.js` / `lib/config.js` / `lib/deck-workspace.js` / `lib/render-nodes.js` /
-   `lib/source-adapter.js` / `lib/tools.js` / `verify/smoke.mjs` 里的客户名、个人路径、环境变量名全部替换为通用示例；
-4. 白名单脚本内置禁用词扫描（客户名 / `/Users/` / `sk-` / 私有 key 名），命中即中止打包。
-
-## 5. 安装与分发矩阵
-
-| 方式 | 命令 | 适合 |
-|---|---|---|
-| npm | `dsh plugin --profile deckline add dsh-plugin-deck-studio` | 普通用户（发布后） |
-| Git | `dsh plugin --profile deckline add "github:yuna78/dsh-deck-studio#path:/plugin/deck-studio"` | 想跟 main 的人 |
-| 本地 clone | `dsh plugin --profile deckline add "$PWD/plugin/deck-studio"` | 开发者 / 定制 |
-
-三种方式都落在 `~/.dsh/profiles/deckline/`；安装后用户只需要改 **profile patch**（decks / projectsRoot / render 节点），
-不需要动插件包本身——这是「任何人可安装」的关键边界。
-
-## 6. 配置口径（生图 key）
-
-- 配置只存在于两处：**profile patch**（结构）与 **环境变量 / key 文件**（凭证）；
-- 结构里只写 `apiKeyEnv`（变量名）或 `apiKeyFile`（本机路径），**永远不写 key 明文**；
-- 工作台设置面板只显示 `keyConfigured` 布尔 + 来源名；
-- 支持多节点（主 / 备用 / 不同模型），每节点独立 key；
-- 缺 key 时：fake 模式仍可走通流程；real 模式报错信息直接给出配置位置。
-
-## 7. 风格生态（本产品化差异点）
-
-- **预设包随插件分发**：`plugin/deck-studio/seeds/styles/<ABBR>.json`（定义，含 `styleBrief` + `baselineBriefs`）
-  + `seeds/samples/<ABBR>-0{1,2,3}.jpg`（3 张基线样张）；
-- **一键导入**：Designs 页「＋ 导入预设风格」，已存在的缩写自动跳过（幂等）；
-- **自己加**：界面里贴图/上传/拖拽；或把图片放到 `designs/<ABBR>/`；
-- **贡献**：PR 新增一个 JSON + 3 张基线样张即可（schema：abbr / name / description / constraints / reference / styleBrief / baselineBriefs）；
-- 已知限制：样张是风格示意，不保证能逐字复刻其中的文字（图像模型通病）；要精确文字用 HTML/Mermaid 叠字。
-
-## 8. 风险与边界
-
-| 风险 | 说明 | 对策 |
-|---|---|---|
-| DSH 插件 API 变动 | 插件依赖 DSH 版本 | 声明 peer 范围 + CI 跑 smoke + 版本豁免文档 |
-| 凭证泄漏 | 用户误把 key 写进 patch | 文档强调 apiKeyEnv / apiKeyFile；设置面板不回显 |
-| 出图成本失控 | 用户批量出图 | 允许点名批量 / 整套（逐页留痕、失败单页重出）；不做一键按钮，避免误触 |
-| 客户数据 | deck 源可能含敏感内容 | 源只读、产物本地 `.deck`、仓库不含数据；导出交接包脱敏 |
-| 模型质量 | 文字糊、版式跑 | 风格 prompt 约束 + 「文字少而英文」建议 + 后期叠字 |
-
-## 9. 里程碑（建议时间）
-
-- **M1（本周）**：Phase 0 完成 + 本机导入 8 个预设风格可用；
-- **M2（下周）**：仓库公开 + v0.1.0 Release + 2 位外部用户装通；
-- **M3（两周内）**：npm 发布 + CI + 首次启动向导；
-- **M4（一个月）**：风格库页面 + UI 双语 + 社区风格包。
-
-## 10. 已拍板（2026-10-21）
-
-| # | 决策 | 结论 | 落地 |
-|---|---|---|---|
-| 1 | License | **MIT** | `LICENSE` + package.json `license: MIT` |
-| 2 | 包名 | **直发，无 org**：`dsh-plugin-deck-studio` | package.json `name` / `private: false` |
-| 3 | 公开范围 | 插件 + docs + 预设 design + **1 个 sample deck** + **1 个 sample logo** | `scripts/build-public-bundle.mjs` 白名单；不含内部台账与历史 |
-| 4 | 品牌 | **Deckline** 最终确认（仓库名仍 `dsh-deck-studio`） | README / UI / logo |
-| 5 | 公开账号 | GitHub `yuna78`；仓库 `yuna78/dsh-deck-studio`（public） | 待负责人确认后 `gh repo create` + push |
-
-**还等负责人执行的 2 个动作**：
-
-1. 确认公开：跑 `node scripts/build-public-bundle.mjs` 后 `gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push`；
-2. npm 发布：`cd plugin/deck-studio && npm publish --access public`（需登录 npm + 2FA）。
-
-之后 CI / Release / 截图由本轮之后的迭代补。