dsh-plugin-deck-studio 0.2.4 → 0.2.6

package/lib/tools.js

@@ -19,6 +19,7 @@ import { readDeckRules, renderDeckRules } from "./deck-rules.js";
 import { readDeckBrief } from "./deck-brief.js";
 import { scriptStyleHints } from "./script-style.js";
 import { DEFAULT_MAX_REVIEWERS, HARD_MAX_REVIEWERS, deriveReviewers, mergeIssues, parseReviewerOutput, renderReviewMarkdown, reviewerPrompt } from "./review-personas.js";
+import { REVIEW_AGENT_PROVIDER } from "./review-agent.js";
 import { densityLine } from "./content-density.js";
 import { faqIndex, searchFaq } from "./faq.js";
 import { WATERMARK_POSITIONS, WATERMARK_POSITION_LABELS, findAsset, listAssets, positionLine, readPngFile, watermarkPng } from "./watermark.js";
@@ -138,7 +139,7 @@ const strEnum = (values) => ({ type: "string", enum: values });
  * @param {import('./config.js').mergeConfig} services.config
  * @param {NodeJS.ProcessEnv} [services.env]
  */
-export function defineDeckTools({ store, workspace, adapters, config, env = process.env, resolveRender = null, isLocalDeck = null, repoRoot = null, subagents = null, reviewPreset = null }) {
+export function defineDeckTools({ store, workspace, adapters, config, env = process.env, resolveRender = null, isLocalDeck = null, repoRoot = null, subagents = null }) {
   const resolveSubagents = () => (typeof subagents === "function" ? subagents() : subagents);
   const designs = createDesignRegistry({ dataRoot: config.dataRoot });
   const decksRegistryFile = join(config.dataRoot, "decks-registry.json");
@@ -2085,8 +2086,8 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
           reviewers: derived.reviewers,
           issues: [],
           text: textOnly(
-            "当前 profile 没有挂 subagent 服务（@deepseek-ai/dsh-subagent + dsh-subagent-spawn-in-process），无法起独立审稿人。\n" +
-              "在 profile 里挂上这三行后重试：dsh-subagent / dsh-subagent-spawn-in-process / dsh-tool-subagent。",
+            "当前 profile 没有挂 subagent 服务（@deepseek-ai/dsh-subagent），无法启动插件内置审稿人。\n" +
+              "请启用 DSH 子 Agent 服务后重试，不需要选择或安装审稿模式。",
           ),
         };
       }
@@ -2110,6 +2111,7 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
         else exec.signal?.addEventListener?.("abort", onAbort, { once: true });
         let timer;
         let activation;
+        const outcome = { reviewer, label: reviewer.label };
         const timeout = new Promise((_resolve, reject) => {
           timer = setTimeout(() => {
             controller.abort();
@@ -2118,7 +2120,7 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
         });
         try {
           activation = await runtime.startActivation({
-            provider: "spawn",
+            provider: REVIEW_AGENT_PROVIDER,
             label: `deck-review:${deck.id}:${reviewer.id}`,
             request: {
               prompt: [
@@ -2134,26 +2136,32 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
                 },
               ],
               parent: exec.agent,
-              ...(reviewPreset || config.review?.presetId ? { agentPreset: reviewPreset || config.review?.presetId } : {}),
             },
             signal: controller.signal,
             delivery: "caller",
           });
           const result = await Promise.race([activation.result, timeout]);
+          if (controller.signal.aborted) throw new Error("听众评审已取消或超时");
+          if (result?.stopReason !== "completed") throw new Error(`审稿人未正常完成（${result?.stopReason ?? "unknown"}）`);
           const text = activationResultText(result);
           const parsed = parseReviewerOutput(text);
-          return { reviewer, label: reviewer.label, parsed, text, stopReason: result?.stopReason ?? "" };
+          if (parsed.unparsed) throw new Error("审稿人未返回符合契约的 JSON 意见");
+          if (parsed.issues.some((issue) => !script.includes(issue.evidence))) {
+            throw new Error("审稿意见的证据不是稿件原文，已拒绝采纳");
+          }
+          Object.assign(outcome, { parsed, text, stopReason: result.stopReason });
         } catch (error) {
-          return { reviewer, label: reviewer.label, error: error instanceof Error ? error.message : String(error) };
+          outcome.error = error instanceof Error ? error.message : String(error);
         } finally {
           clearTimeout(timer);
           exec.signal?.removeEventListener?.("abort", onAbort);
           try {
             await activation?.dispose?.();
           } catch {
-            /* 清理失败不影响评审结果 */
+            outcome.error = "审稿执行清理失败，请检查 DSH 子任务状态";
           }
         }
+        return outcome;
       };
 
       // 审稿人并发跑：每个都是一次独立子 agent，互不影响；失败一个不拖垮整份评审。
@@ -2171,12 +2179,8 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
       const generatedAt = new Date().toISOString();
       const target = join(deckDir, "docs", "review.experts.md");
       let written = false;
-      if (args.write !== false) {
+      if (args.write !== false && !exec.signal?.aborted) {
         mkdirSync(dirname(target), { recursive: true });
-        const unparsed = ok
-          .filter((outcome) => outcome.parsed.unparsed)
-          .map((outcome) => `### ${outcome.label}\n\n${outcome.text.slice(0, 4000)}`)
-          .join("\n\n");
         const body = [
           renderReviewMarkdown({
             deckTitle: deck.title,
@@ -2186,7 +2190,6 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
             generatedAt,
             failed,
           }),
-          ...(unparsed ? ["", "## 未按 JSON 输出、原文保留", "", unparsed] : []),
         ].join("\n");
         writeFileSync(target, body.endsWith("\n") ? body : `${body}\n`, "utf8");
         written = true;
@@ -2213,7 +2216,7 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
       });
       const lines = issues.length
         ? issues.map((issue) => `${issue.severity} · ${issue.page || "—"} · ${issue.problem} → ${issue.suggestion}${issue.reviewer ? `（${issue.reviewer}）` : ""}`)
-        : ["没有可操作的问题（可能听众视角下确实没问题，也可能审稿人没读懂——先看 docs/review.experts.md 的原始评审）"];
+        : [ok.length ? "已完成评审，未发现有原文证据支持的可操作问题。" : "本次没有有效评审结果；不能据此判断稿件没有问题。"];
       const failureLine = failed.length
         ? `\n${failed.length} 位审稿人失败：${failed.map((item) => `${item.label}（${item.error}）`).join(" / ")}`
         : "";
@@ -2222,6 +2225,7 @@ export function defineDeckTools({ store, workspace, adapters, config, env = proc
         reviewers: derived.reviewers.map((reviewer) => ({ id: reviewer.id, label: reviewer.label, audience: reviewer.audience })),
         issues,
         bySeverity,
+        failed,
         written,
         text: `听众评审（${derived.reviewers.map((reviewer) => reviewer.label).join(" / ")}）：P0 ${bySeverity.P0} / P1 ${bySeverity.P1} / P2 ${bySeverity.P2}${failureLine}\n${lines.join("\n")}${written ? `\n已写入：${target}` : "\n（dry run，未写文件）"}\n这些是评审意见，不是已改稿：按 P0/P1 用 deck_script_propose_edits 提案，等用户确认后再落版。`,
       };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-deck-studio",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "private": false,
   "description": "Deckline：DSH 的 image deck / PPT 工作台插件——原生 Chat + 整页图片 deck 工作区 + 设计风格库；用对话做 PPT、按页出图、版本可追踪、导出 PDF/PPTX。",
   "license": "MIT",
@@ -30,7 +30,7 @@
   ],
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.1.7-0 <0.3.0"
+    "dsh": ">=0.2.1-rc.2 <0.3.0"
   },
   "scripts": {
     "verify": "node verify/smoke.mjs",
@@ -61,7 +61,7 @@
     "url": "https://github.com/yuna78/dsh-deck-studio/issues"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": ">=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0"
+    "@deepseek-ai/dsh": ">=0.2.1-rc.2 <0.3.0"
   },
   "author": "Yuna",
   "files": [

package/seeds/docs/compat.md

@@ -1,16 +1,16 @@
 # DSH 兼容矩阵（定期回归记录）
 
 > 口径：DSH 处于 prerelease 阶段，没有 stable 线；本项目**定期批次**回归，不逐 rc 跟。
-> 每个批次记录：证实的版本、验证范围、断点、复现方式。已知限制与路线见 [productization.md](productization.md) 与 [install.md](install.md)。
+> 每个批次记录：证实的版本、验证范围、断点、复现方式。已知限制见 [install.md](install.md) 的故障排查部分。
 
 ## 当前支持声明
 
 | 项 | 值 | 说明 |
 |---|---|---|
-| `peerDependencies["@deepseek-ai/dsh"]` | `>=0.1.7-0 <0.2.0 \|\| >=0.2.0-0 <0.3.0 \|\| >=0.2.1-0 <0.3.0` | 装到 0.3+ 会被 DSH 的 peer 检查拦下 |
-| `engines.dsh` | `>=0.1.7-0 <0.3.0` | 元数据口径，同 peer |
+| `peerDependencies["@deepseek-ai/dsh"]` | `>=0.2.1-rc.2 <0.3.0` | 装到 0.3+ 会被 DSH 的 peer 检查拦下 |
+| `engines.dsh` | `>=0.2.1-rc.2 <0.3.0` | 插件0.2.6起：内置审稿使用0.2.1 API，旧DSH请升级或保留插件0.2.5 |
 | `engines.node` | `^22.19.0 \|\| >=24.0.0` | 与 DSH 运行时要求一致；**Node 23 不在范围内** |
-| 已验证版本 | `0.1.7-rc.2`（旧基线）· `0.2.1-rc.2`（2026-10-21：隔离环境 + 本地全局升级后真机回归） | 见下表 |
+| 已验证版本 | `0.2.1-rc.2`（0.2.6：内置审稿真实服务19项、产品模型评审；此前版本还有0.1.7旧基线） | 历史批次不代表本版继续支持0.1.7 |
 
 ## 回归记录
 

package/seeds/docs/install.en.md

@@ -10,11 +10,13 @@ assets / conversations on the right. It is not a standalone app — it runs on a
 
 ## 0. Prerequisites
 
+Plugin 0.2.6+ requires DSH 0.2.1-rc.2 or a newer 0.2.x release. Restart DSH after upgrading. Remove any manually declared `preset-deck-critic` entry from your profile; legacy `review.presetId` is ignored. Reviews now run internally without selecting another mode.
+
 | Dependency | Version | Notes |
 |---|---|---|
 | Node.js | `^22.19` or `≥ 24` | Same as the DSH runtime; Node 23 is not supported |
 | pnpm | 10+ | DSH uses pnpm to manage profile dependencies |
-| DSH | `≥ 0.1.7 < 0.3` | `npm i -g @deepseek-ai/dsh`; verified on 0.1.7-rc.2 / 0.2.1-rc.2, see [compat.md](compat.md) |
+| DSH | `≥ 0.2.1-rc.2 < 0.3` (plugin 0.2.6+) | `npm i -g @deepseek-ai/dsh`; verified on 0.2.1-rc.2, see [compat.md](compat.md) |
 | An LLM provider key | — | e.g. `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` (configured in the profile, see DSH docs) |
 | An image node key | — | For real renders; the fake mode lets you try the flow first (section 4) |
 
@@ -77,16 +79,18 @@ The minimum (append to the profile's `cordis.patch.yml`):
   config:
     displayName: 'Deckline'
     userName: 'Yuna'
-    # where new decks are created; empty = the plugin's internal .deck/projects/<id>/source
-    projectsRoot: '/absolute/path/to/your/sharing'
+    # root for new deck source files; empty = <dataRoot>/projects/<deck-id>/source
+    projectsRoot: '/absolute/path/to/your/decks'
+    # workspacePath: '/absolute/path/to/your/workspace'  # DSH chat workspace, not storage
     decks:
       - id: my-deck
         label: 'My deck'
         sourceRoot: '/absolute/path/to/my-deck'
 ```
 
-> `decks[].sourceRoot` is read-only: Deckline never writes to the source directory; all edits and
-> revisions live in `.deck/`. You can also start with **＋ New Deck** if you have no deck yet.
+> `decks[].sourceRoot` is a managed source and always read-only: Deckline never writes to it; working copies,
+> revisions and renders live under `dataRoot`. A locally created deck is different: after user confirmation,
+> script / intent source files may be written back to that local project directory. You can also start with **＋ New Deck** if you have no deck yet.
 
 ### Per-deck project rules (optional)
 
@@ -105,8 +109,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
 
@@ -126,14 +129,15 @@ creating a deck, check this table first.
 - **`dataRoot` defaults to `$DSH_HOME/deckline`** (usually `~/.dsh/deckline`) — never inside the plugin
   package, so plugin upgrades do not touch it. Override with `dataRoot: '/your/path'` in the profile patch,
   or the `DSH_DECK_DATA_ROOT` env var.
-- **`projectsRoot`** decides where new decks are created; if unset they go to `<dataRoot>/projects/<deckId>/source`.
-- **Managed source decks are read-only**: Deckline never writes to a deck registered via `decks[].sourceRoot`.
+- **`projectsRoot`** decides where locally created deck source files live; if unset they go to `<dataRoot>/projects/<deckId>/source`. It does not select the chat workspace.
+- **`workspacePath`** selects the DSH workspace used for conversation binding; it is independent of `projectsRoot` / `dataRoot`. If unset, Deckline resolves it from the startup and source directories.
+- **Managed source decks are read-only**: Deckline never writes to a deck registered via `decks[].sourceRoot`; a confirmed local deck may write back to its own source files.
 - **Backup**: archive `dataRoot` and `projectsRoot` together (documents + images + events):
   ```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; keep `dataRoot` outside the source tree
+  in normal installs so runtime data is portable and plugin upgrades cannot overwrite it.
 
 ## 3. Start
 
@@ -217,7 +221,7 @@ bottom of the preview (paste / pick files work the same way).
 
 Samples live under `designs/<ABBR>/` (ABBR is your style abbreviation):
 
-- canvas directory (recommended): `.deck/projects/<canvasDeckId>/source/designs/<ABBR>/`;
+- canvas directory (recommended): `<dataRoot>/projects/<canvasDeckId>/source/designs/<ABBR>/`;
 - or `designs/<ABBR>/` inside any managed deck source (Deckline scans and merges them).
 
 Refresh the page afterwards. png / jpg / webp are supported; names are free-form
@@ -236,7 +240,7 @@ Swiss minimal / aurora gradient), each with samples. See [styles.md](styles.md).
 | Port already in use | `dsh --profile deckline --port 13100`; or kill the old process with `lsof -tiTCP:13090 -sTCP:LISTEN` |
 | Page 404 / blank | Make sure the plugin bundle is enabled: `dsh --profile deckline --dump-config \| grep deck-studio` |
 | No "render" button / render fails | Check the key state in Settings; confirm `render.mode: real`; `curl` the node endpoint |
-| New decks land in the wrong place | Set `projectsRoot`; otherwise they go to the plugin data directory `.deck/projects/` |
+| New decks land in the wrong place | Set `projectsRoot`; otherwise they go to `<dataRoot>/projects/` (by default `<DSH_HOME>/deckline/projects/`) |
 | Where are data / samples | See section 2.5: source decks in `projectsRoot`, working copies / renders in `dataRoot` (default `~/.dsh/deckline`) |
 | Upgrading the plugin | `dsh plugin --profile deckline install <spec>`, or `add` the new version again |
 

package/seeds/docs/install.md

@@ -11,11 +11,13 @@ Deckline（`dsh-plugin-deck-studio`）是 DeepSeek Harness（DSH）的 **image d
 
 ## 0. 前置条件
 
+插件0.2.6起需要 DSH 0.2.1-rc.2 或更新的0.2.x；升级后重启 DSH。若手写 profile 仍声明 `preset-deck-critic`，请移除；旧 `review.presetId` 已忽略，评审改由插件内部调度，不需选审稿模式。
+
 | 依赖 | 版本 | 说明 |
 |---|---|---|
 | Node.js | `^22.19` 或 `≥ 24` | 与 DSH 运行时一致；Node 23 不在支持范围 |
 | pnpm | 10+ | DSH 用 pnpm 管理 profile 依赖 |
-| DSH | `≥ 0.1.7 < 0.3`（0.1.5 不支持） | **用 npm 全局安装的发行版**：`npm i -g @deepseek-ai/dsh@0.2.1-rc.2`；已验证 0.2.1-rc.2，见 [compat.md](compat.md)。从源码自编译的 dsh 若缺内置包（如 `@deepseek-ai/dsh-agent-preset`）会启动失败，见 4.3 |
+| DSH | `≥ 0.2.1-rc.2 < 0.3`（插件0.2.6起） | **用 npm 全局安装的发行版**：`npm i -g @deepseek-ai/dsh@0.2.1-rc.2`；已验证 0.2.1-rc.2，见 [compat.md](compat.md)。从源码自编译的 dsh 若缺内置包（如 `@deepseek-ai/dsh-agent-preset`）会启动失败，见 4.3 |
 | 一个 LLM provider key | — | 例：`DEEPSEEK_API_KEY` / `OPENAI_API_KEY`（profile 里配置，见 DSH 文档） |
 | 一个 image 节点 key | — | 生成整页图用；可先用 fake 模式体验（见第 4 节） |
 
@@ -111,15 +113,17 @@ Deckline 的配置都在 **profile patch 层**：`~/.dsh/profiles/deckline/cordi
   config:
     displayName: 'Deckline'
     userName: ''            # 留空 = 首页只显示「欢迎你」；填了就显示「XX，欢迎你」
-    # 新建 deck 落盘根：留空 = 插件内部 .deck/projects/<id>/source
-    projectsRoot: '/absolute/path/to/your/sharing'
+    # 新建 deck 源文件根：留空 = <dataRoot>/projects/<deck-id>/source
+    projectsRoot: '/absolute/path/to/your/decks'
+    # workspacePath: '/absolute/path/to/your/workspace'  # DSH 会话工作区，不是保存位置
     decks:
       - id: my-deck
         label: '我的 deck'
         sourceRoot: '/absolute/path/to/my-deck'
 ```
 
-> `decks[].sourceRoot` 只读：Deckline 永远不写源目录，编辑产物和版本都在 `.deck/` 里。
+> `decks[].sourceRoot` 是受控源，始终只读：Deckline 不会写入它；编辑工作副本、版本和出图落在 `dataRoot`。
+> 通过「＋ 新建 Deck」创建的本机 deck 是另一种情况：用户确认后，script / intent 等源文件可以回写到该本机项目目录。
 > 没有现成 deck 也可以先用「＋ 新建 Deck」建一个。
 
 ### 每个 deck 的项目规则（可选）
@@ -137,7 +141,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 / 文档 / 图片 / 导出
 
@@ -155,13 +159,14 @@ Deckline 的数据分两处：**你的 deck 源**（`projectsRoot`，纯 md +
 
 - **`dataRoot` 默认 `$DSH_HOME/deckline`**（通常是 `~/.dsh/deckline`）——不在插件包里，升级插件不会覆盖；
   可在 profile patch 配 `dataRoot: '/your/path'`，或环境变量 `DSH_DECK_DATA_ROOT` 覆盖。
-- **`projectsRoot`** 决定新建 deck 落在哪；不配置时落在 `<dataRoot>/projects/<deckId>/source`。
-- **受控源 deck 只读**：`decks[].sourceRoot` 指向的已有 deck 目录，插件永远不写。
+- **`projectsRoot`** 决定本机新建 deck 的源文件落在哪；不配置时落在 `<dataRoot>/projects/<deckId>/source`。它不决定聊天会话绑定的工作区。
+- **`workspacePath`** 只决定会话绑定哪个 DSH workspace，与 `projectsRoot` / `dataRoot` 相互独立；未配置时插件按启动目录和源目录自动选择工作区。
+- **受控源 deck 只读**：`decks[].sourceRoot` 指向的已有 deck 目录，插件永远不写；本机新建 deck 在用户确认后可回写自己的源文件。
 - **备份**：把 `dataRoot` 和 `projectsRoot` 一起打包即可（文档 + 图 + 事件都在里面）：
   ```sh
   tar czf deckline-backup-$(date +%Y%m%d).tgz "$DSH_HOME/deckline" "<你的 projectsRoot>"
   ```
-- 工作台「设置」面板会显示当前数据目录；本仓库开发时数据根在仓库 `.deck/`（profile 里显式配置）。
+- 工作台「设置」面板会显示当前数据目录；开发环境也建议使用独立的 `dataRoot`，不要把运行数据写进仓库。
 - **preset 工具实例要和根挂载用同一个数据根**（F-98）：DSH 面板路由与 Agent 工具是两个实例，根挂载里覆盖了
   `dataRoot` / `projectsRoot` 时，preset 的 `deck-studio-tools` 也要写同一组值（推荐 YAML 锚点），
   否则新建 deck 只进一边的注册表，Agent 会报「未知 deck：…」。
@@ -194,7 +199,7 @@ Deckline 支持：
 3. 填：**模式**（fake / real）、**生图节点 endpoint**、**模型**、**key 环境变量名**（或 **key 文件路径**）、**出图尺寸**；
 4. 点 **保存并生效**。
 
-保存后写入本机数据目录 `~/.dsh/deckline/render-settings.json`（开发仓库里是 `.deck/render-settings.json`，
+保存后写入本机数据目录 `<dataRoot>/render-settings.json`（默认 `~/.dsh/deckline/render-settings.json`；
 已 gitignore）：节点可直存 API key（0600，界面只显示「已保存」，payload 不回显），也可改用变量名 / key 文件；
 下次启动自动生效，并覆盖 profile 里的 render 配置。
 
@@ -252,7 +257,7 @@ export DSH_DECK_IMAGE_API_KEY="sk-…"          # 只放在你的 shell / 密钥
 - 没配 key / 仍是 fake 模式时，设置面板会直接给出提示。
 - 模型名填你的中转实际开放的模型；常见 OpenAI 兼容名 `gpt-image-2` 系列的模型 id 以节点 `/v1/models` 为准。
 - 工作台「设置 → 出图节点」可以直接切换线路，也能**新增 / 编辑 / 删除节点**：填 名称 + 接口地址 + API Key +
-  模型名即可（key 存本机 `.deck/render-settings.json`，0600，不进 git；也可改用 env / key 文件）；
+  模型名即可（key 存本机 `<dataRoot>/render-settings.json`，0600，不进 git；也可改用 env / key 文件）；
   切换写当前 deck 的 `render-selection.json`，下一次出图生效，不用重启。
 - **修图**（`deck_image_edit`）需要节点支持 `POST /v1/images/edits`（multipart：`image` + `prompt` + `size` + `model`）。
   回车节点通常和出图同源；不填 `editEndpoint` 就按上面的规则派生，派生不出来（自定义路径）时工具会明确报错、不猜地址。
@@ -273,7 +278,7 @@ export DSH_DECK_IMAGE_API_KEY="sk-…"          # 只放在你的 shell / 密钥
 
 样张存在 `designs/<ABBR>/` 下（ABBR 是你的风格缩写）：
 
-- 画布目录（推荐）：`.deck/projects/<canvasDeckId>/source/designs/<ABBR>/`；
+- 画布目录（推荐）：`<dataRoot>/projects/<canvasDeckId>/source/designs/<ABBR>/`；
 - 或任何受控 deck 源里的 `designs/<ABBR>/`（Deckline 会自动扫描并合并展示）。
 
 放完刷新页面即可。支持 png / jpg / webp；命名随意（`sample-01.jpg` 之类便于排序）。
@@ -290,7 +295,7 @@ Designs 页 **＋ 导入预设风格** 会一次导入 8 个自带风格（商
 | 端口被占 | `dsh --profile deckline --port 13100`；或 `lsof -tiTCP:13090 -sTCP:LISTEN` 杀掉旧进程 |
 | 页面 404 / 白屏 | 确认插件组合包已启用：`dsh --profile deckline --dump-config \| grep deck-studio` |
 | 没有「生图」按钮 / 出图失败 | 设置面板看 key 是否配置；确认 `render.mode: real`；节点 endpoint 可 `curl` 通 |
-| 新 deck 目录落错位置 | 配 `projectsRoot`；否则落在插件数据目录 `.deck/projects/` |
+| 新 deck 目录落错位置 | 配 `projectsRoot`；否则落在 `<dataRoot>/projects/`（默认 `<DSH_HOME>/deckline/projects/`） |
 | 数据 / 样张在哪 | 见 §2.5：源 deck 在 `projectsRoot`，工作副本 / 出图在 `dataRoot`（默认 `~/.dsh/deckline`） |
 | 升级插件 | `dsh plugin --profile deckline install <spec>`，或重新 `add` 新版本 |
 

package/seeds/docs/styles.en.md

@@ -42,8 +42,8 @@ bottom of the preview (paste / pick files work the same way).
 ### Way 2: drop files directly
 
 Put images under `designs/<ABBR>/` (canvas directory
-`.deck/projects/<canvasDeckId>/source/designs/<ABBR>/`, or `designs/<ABBR>/` inside any managed deck
-source). png / jpg / webp are supported; refresh the page afterwards.
+`<dataRoot>/projects/<canvasDeckId>/source/designs/<ABBR>/`). Existing `designs/<ABBR>/` directories in managed sources are also scanned read-only.
+Prefer uploading new samples through the canvas rather than modifying managed sources. png / jpg / webp are supported; refresh the page afterwards.
 
 Fields of `style.json` (the plugin also writes one automatically):
 
@@ -104,7 +104,7 @@ node scripts/f74-regenerate-presets.mjs --only=BIZ --limit=1
 ```
 
 What the script does: sync `styleBrief` from `seeds/styles/<ABBR>.json` into the online design's
-`style.json` → back up old samples to `.deck/tmp/f74-old-samples/<ABBR>/` → render one image per
+`style.json` → back up old samples to `<dataRoot>/tmp/f74-old-samples/<ABBR>/` → render one image per
 `baselineBriefs` entry (prompt recorded in `samples.jsonl`) → downscale and write back into `seeds/samples/`.
 Refresh the Designs page afterwards; no service restart needed.
 

package/seeds/docs/styles.md

@@ -37,8 +37,8 @@ Designs 页 → **＋ 导入预设风格**：一次导入下面 8 个风格（
 
 ### 方式 2：直接放文件
 
-把图片放进 `designs/<ABBR>/` 目录（画布目录 `.deck/projects/<canvasDeckId>/source/designs/<ABBR>/`，
-或任何受控 deck 源里的 `designs/<ABBR>/`）。支撑 png / jpg / webp，刷新页面即可。
+把图片放进 `designs/<ABBR>/` 目录（画布目录 `<dataRoot>/projects/<canvasDeckId>/source/designs/<ABBR>/`，
+插件也会只读扫描已有源目录中的 `designs/<ABBR>/`）。新增样张优先通过画布上传，避免修改受控源。支持 png / jpg / webp，刷新页面即可。
 
 `style.json` 的字段（插件也会自动写一份）：
 
@@ -94,7 +94,7 @@ node scripts/f74-regenerate-presets.mjs --only=BIZ --limit=1
 ```
 
 脚本做的事：把 `seeds/styles/<ABBR>.json` 的 `styleBrief` 同步进线上 design 的 `style.json` →
-旧样张备份到 `.deck/tmp/f74-old-samples/<ABBR>/` → 按 `baselineBriefs` 逐张出图（prompt 落 `samples.jsonl`）→
+旧样张备份到 `<dataRoot>/tmp/f74-old-samples/<ABBR>/` → 按 `baselineBriefs` 逐张出图（prompt 落 `samples.jsonl`）→
 预览回写 `seeds/samples/`。重制后刷新 Designs 页即可看到新样张；不用重启服务。
 
 > 样张里的文字是示意（图像模型会糊字），不承诺逐字复刻；也不要把真实客户资料、品牌 logo 放进样例图。

package/ui/workbench.html

@@ -130,7 +130,7 @@
       <button class="modal-close" id="ndClose" title="关闭">✕</button>
     </div>
     <form class="modal-body newdeck-body" id="newDeckForm">
-      <p class="nd-tip">先定「讲给谁、讲什么、想带走什么」+ 视觉风格。创建后会开出源目录与 9 份文档骨架（新项目落在 <code>00_company/sharing/&lt;目录名&gt;/</code>），然后在对话里继续补资料、改 script，直到可以出图。</p>
+      <p class="nd-tip">先定「讲给谁、讲什么、想带走什么」+ 视觉风格。创建后会开出源目录与 9 份文档骨架，然后在对话里继续补资料、改 script，直到可以出图。<br>新项目保存位置：<code id="ndStoragePath">正在读取配置…</code>。<span id="ndStorageNote"></span></p>
       <label class="field"><span>主题 / 标题</span><input id="ndTitle" required placeholder="例：XX 业务场景的 AI 落地分享"></label>
       <label class="field"><span>项目目录名（可选，英文小写中划线；留空自动生成）</span><input id="ndDirName" placeholder="例：talk-ai-transformation-6-stages"></label>
       <label class="field"><span>页数（占位页 1–40；创建后还能在对话里追加）</span><input id="ndPages" type="number" min="1" max="40" inputmode="numeric" value="6"></label>
@@ -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;
   }
@@ -3434,11 +3468,23 @@ function renderDeckStyleChoices() {
   }
 }
 
+function newDeckStorageInfo(config = {}) {
+  const root = String(config?.projectsRoot || "").trim();
+  const dataRoot = String(config?.dataRoot || "").trim();
+  const append = (base, suffix) => `${base.replace(/[\\/]+$/, "")}/${suffix}`;
+  if (root) return { path: append(root, "<目录名或自动生成的 deck-id>/"), note: "由 profile 的 projectsRoot 配置；与会话工作区独立。" };
+  if (dataRoot) return { path: append(dataRoot, "projects/<deck-id>/source/"), note: "未配置 projectsRoot，使用插件数据目录；不会自动保存在当前工作区。" };
+  return { path: "暂时无法确定", note: "请等待工作台配置加载后重试；未配置 projectsRoot 时使用 <dataRoot>/projects/<deck-id>/source/。" };
+}
+
 function openNewDeckModal() {
   // F-112：profile 里配了 defaultStyleAbbr 就默认预选这个风格（用户仍可改/取消）。
   STATE.ndStyleAbbr = String(STATE.data?.config?.defaultStyleAbbr || "");
   getEl("newDeckForm").reset();
   getEl("ndState").textContent = "";
+  const storage = newDeckStorageInfo(STATE.data?.config);
+  getEl("ndStoragePath").textContent = storage.path;
+  getEl("ndStorageNote").textContent = storage.note;
   getEl("newDeckModal").hidden = false;
   renderDeckStyleChoices();
   setTimeout(() => getEl("ndTitle").focus(), 30);
@@ -3788,7 +3834,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 +3903,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 +3928,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 画布。 */