@xiaobuyu/nodesign 0.0.1 → 0.0.2

package/server/engine/mcp/tools/pin-to-board.js

@@ -1,130 +1,130 @@
-/**
- * mcp/tools/pin_to_board — 把一件东西摆到用户画布上的某个位置。
- *
- * 写 board.json（board-store 单锁原子操作，与前端 PATCH 互不覆盖），然后广播
- * board.updated（sessionId: null → project 全连接都收到，前端整份重拉）。
- *
- * 物件 id 约定（与前端 BoardCanvas 派生一致）：**id = kind 前缀 + 工作区相对路径**
- *   - 普通文件（图片 / 便签 / 数据）：路径本身，`assets/generated/a.webp`
- *   - deck：`deck:<路径>`，如 `deck:稿件/主稿.html`
- *   - 站点：`site:<目录>`
- *   - 项目文档：`doc:_root`（记忆）/ `doc:brand`（品牌档案）
- *
- * ## 2026-08-13：这个工具的职权范围缩小了
- *
- * 以前它有个 `zone` 参数，语义是"放进哪块工作区"。**在 id = 路径的模型下这件事
- * 不成立** —— 一个物件属于哪个文件夹，答案就写在它的路径里。让工具单独写一个
- * "显式归属"字段，等于允许画布说"它在 A 文件夹"而磁盘说"它在 B 文件夹"，
- * 正是 2026-07-28 把「拖出工作区解绑」停用掉的那个理由（两边对不上，且很容易
- * 误触）。要换文件夹就 `mv` —— 那是真的搬，画布跟着走。
- *
- * 所以现在它只剩一件事：**给这件东西一个位置并置顶**（"把它摆到用户眼前"）。
- *
- * ⚠️ 顺带修掉的两个僵尸：`zone` 原来被校验成 `/^[A-Za-z0-9-]{8,64}$/`（= 一个
- * sessionId），于是任何中文文件夹名、任何带斜杠的嵌套路径都过不了，一律静默
- * 回落到 sessionId —— 然后在 board.json 里新建一块根本不存在的"工作区"。
- * agent 每帮一次忙就制造一条死数据。
- */
-
-import { tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-import path from 'path';
-import { promises as fs } from 'fs';
-import { pinToZone } from '../../../projects/board-store.js';
-
-/** 物件 id → 它住在哪个文件夹（与前端 stage.js 的 zoneOfObjectId 同一套规则） */
-function folderOfObjectId(objectId) {
-  if (objectId.startsWith('doc:')) return '';
-  const c = objectId.indexOf(':');
-  const p = (c > 0 && /^[a-z]+$/.test(objectId.slice(0, c))) ? objectId.slice(c + 1) : objectId;
-  const i = p.lastIndexOf('/');
-  return i > 0 ? p.slice(0, i) : '';
-}
-
-/**
- * @param {object} deps
- * @param {string} [deps.sharedRoot]   工作区根（校验文件存在用）
- * @param {string} [deps.projectId]
- * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
- */
-export function makePinToBoardTool({ sharedRoot, projectId, ctx }) {
-  return tool(
-    'pin_to_board',
-    `Bring an item to the front of the user's canvas, at a free spot in whatever
-folder it lives in. The canvas is their desktop: whatever you write appears
-there automatically — you do NOT need this tool for your own outputs.
-Use it only to deliberately surface something:
-
-- Pull a reference (an uploaded asset, the brand doc, an older image) into view
-- Restore something the user dragged off-screen, when they ask for it back
-
-This does NOT change which folder the item belongs to — that is decided by
-where the file is on disk. To move it, \`mv\` the file; the canvas follows.
-
-Paths are workspace-relative, exactly as they are on disk. Accepted forms:
-- any file path: 'assets/generated/hero.webp', 'notes/灵感.md', '稿件/数据.csv'
-- a deck: 'deck:<path>.html'   a site: 'site:<dir>'
-  (a bare '<path>.html' is read as a deck)
-- '.claude/agent-memory/memory.md' (project memory) / '.../brand/memory.md' (brand doc)`,
-    {
-      path: z
-        .string()
-        .min(1)
-        .max(300)
-        .describe('Item to surface — see accepted forms in the tool description'),
-    },
-    async ({ path: rawPath }) => {
-      try {
-        if (!projectId) {
-          return { content: [{ type: 'text', text: 'No project bound; cannot pin.' }], isError: true };
-        }
-
-        // 归一化成前端物件 id（id = kind 前缀 + 工作区相对路径）
-        let objectId = String(rawPath).trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
-        if (!objectId || objectId.includes('..')) {
-          return { content: [{ type: 'text', text: 'Invalid path.' }], isError: true };
-        }
-        if (objectId.endsWith('agent-memory/brand/memory.md')) objectId = 'doc:brand';
-        else if (objectId.endsWith('agent-memory/memory.md')) objectId = 'doc:_root';
-        else if (!/^(deck|site|doc):/.test(objectId)) {
-          // 裸路径：.html 是一份 deck，其余（图片 / 便签 / 数据文件）id 就是路径。
-          // 站点的目录要显式写 `site:` —— 光看路径分不出
-          // "一个收纳文件夹"和"一件目录型产物"，猜错了钉上去的是个不存在的 id。
-          if (sharedRoot) {
-            const abs = path.join(sharedRoot, objectId);
-            try { await fs.access(abs); } catch {
-              return {
-                content: [{ type: 'text', text: `File not found: ${objectId}. Paths are workspace-relative, same as on disk.` }],
-                isError: true,
-              };
-            }
-          }
-          if (/\.html?$/i.test(objectId)) objectId = `deck:${objectId}`;
-        }
-
-        const zoneId = folderOfObjectId(objectId);
-        const { zone: placedZone, placed } = await pinToZone(projectId, { objectId, zoneId });
-
-        try {
-          ctx?.emit?.({
-            type: 'board.updated',
-            sessionId: null,          // project 级广播：显式压掉 ctx 的 sessionId enrich
-            objectId,
-            zoneId,
-            summary: zoneId ? `已把 ${objectId} 摆到「${zoneId}」里` : `已把 ${objectId} 摆到桌面上`,
-          });
-        } catch { /* emit fail-safe */ }
-
-        const where = placedZone?.id ? `in ${placedZone.id}` : 'on the desktop';
-        return {
-          content: [{
-            type: 'text',
-            text: `Surfaced ${objectId} ${where} at (${placed.x}, ${placed.y}). The user's canvas updates live.`,
-          }],
-        };
-      } catch (err) {
-        return { content: [{ type: 'text', text: `pin_to_board failed: ${err.message}` }], isError: true };
-      }
-    },
-  );
-}
+/**
+ * mcp/tools/pin_to_board — 把一件东西摆到用户画布上的某个位置。
+ *
+ * 写 board.json（board-store 单锁原子操作，与前端 PATCH 互不覆盖），然后广播
+ * board.updated（sessionId: null → project 全连接都收到，前端整份重拉）。
+ *
+ * 物件 id 约定（与前端 BoardCanvas 派生一致）：**id = kind 前缀 + 工作区相对路径**
+ *   - 普通文件（图片 / 便签 / 数据）：路径本身，`assets/generated/a.webp`
+ *   - deck：`deck:<路径>`，如 `deck:稿件/主稿.html`
+ *   - 站点：`site:<目录>`
+ *   - 项目文档：`doc:_root`（记忆）/ `doc:brand`（品牌档案）
+ *
+ * ## 2026-08-13：这个工具的职权范围缩小了
+ *
+ * 以前它有个 `zone` 参数，语义是"放进哪块工作区"。**在 id = 路径的模型下这件事
+ * 不成立** —— 一个物件属于哪个文件夹，答案就写在它的路径里。让工具单独写一个
+ * "显式归属"字段，等于允许画布说"它在 A 文件夹"而磁盘说"它在 B 文件夹"，
+ * 正是 2026-07-28 把「拖出工作区解绑」停用掉的那个理由（两边对不上，且很容易
+ * 误触）。要换文件夹就 `mv` —— 那是真的搬，画布跟着走。
+ *
+ * 所以现在它只剩一件事：**给这件东西一个位置并置顶**（"把它摆到用户眼前"）。
+ *
+ * ⚠️ 顺带修掉的两个僵尸：`zone` 原来被校验成 `/^[A-Za-z0-9-]{8,64}$/`（= 一个
+ * sessionId），于是任何中文文件夹名、任何带斜杠的嵌套路径都过不了，一律静默
+ * 回落到 sessionId —— 然后在 board.json 里新建一块根本不存在的"工作区"。
+ * agent 每帮一次忙就制造一条死数据。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import path from 'path';
+import { promises as fs } from 'fs';
+import { pinToZone } from '../../../projects/board-store.js';
+
+/** 物件 id → 它住在哪个文件夹（与前端 stage.js 的 zoneOfObjectId 同一套规则） */
+function folderOfObjectId(objectId) {
+  if (objectId.startsWith('doc:')) return '';
+  const c = objectId.indexOf(':');
+  const p = (c > 0 && /^[a-z]+$/.test(objectId.slice(0, c))) ? objectId.slice(c + 1) : objectId;
+  const i = p.lastIndexOf('/');
+  return i > 0 ? p.slice(0, i) : '';
+}
+
+/**
+ * @param {object} deps
+ * @param {string} [deps.sharedRoot]   工作区根（校验文件存在用）
+ * @param {string} [deps.projectId]
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makePinToBoardTool({ sharedRoot, projectId, ctx }) {
+  return tool(
+    'pin_to_board',
+    `Bring an item to the front of the user's canvas, at a free spot in whatever
+folder it lives in. The canvas is their desktop: whatever you write appears
+there automatically — you do NOT need this tool for your own outputs.
+Use it only to deliberately surface something:
+
+- Pull a reference (an uploaded asset, the brand doc, an older image) into view
+- Restore something the user dragged off-screen, when they ask for it back
+
+This does NOT change which folder the item belongs to — that is decided by
+where the file is on disk. To move it, \`mv\` the file; the canvas follows.
+
+Paths are workspace-relative, exactly as they are on disk. Accepted forms:
+- any file path: 'assets/generated/hero.webp', 'notes/灵感.md', '稿件/数据.csv'
+- a deck: 'deck:<path>.html'   a site: 'site:<dir>'
+  (a bare '<path>.html' is read as a deck)
+- '.claude/agent-memory/memory.md' (project memory) / '.../brand/memory.md' (brand doc)`,
+    {
+      path: z
+        .string()
+        .min(1)
+        .max(300)
+        .describe('Item to surface — see accepted forms in the tool description'),
+    },
+    async ({ path: rawPath }) => {
+      try {
+        if (!projectId) {
+          return { content: [{ type: 'text', text: 'No project bound; cannot pin.' }], isError: true };
+        }
+
+        // 归一化成前端物件 id（id = kind 前缀 + 工作区相对路径）
+        let objectId = String(rawPath).trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
+        if (!objectId || objectId.includes('..')) {
+          return { content: [{ type: 'text', text: 'Invalid path.' }], isError: true };
+        }
+        if (objectId.endsWith('agent-memory/brand/memory.md')) objectId = 'doc:brand';
+        else if (objectId.endsWith('agent-memory/memory.md')) objectId = 'doc:_root';
+        else if (!/^(deck|site|doc):/.test(objectId)) {
+          // 裸路径：.html 是一份 deck，其余（图片 / 便签 / 数据文件）id 就是路径。
+          // 站点的目录要显式写 `site:` —— 光看路径分不出
+          // "一个收纳文件夹"和"一件目录型产物"，猜错了钉上去的是个不存在的 id。
+          if (sharedRoot) {
+            const abs = path.join(sharedRoot, objectId);
+            try { await fs.access(abs); } catch {
+              return {
+                content: [{ type: 'text', text: `File not found: ${objectId}. Paths are workspace-relative, same as on disk.` }],
+                isError: true,
+              };
+            }
+          }
+          if (/\.html?$/i.test(objectId)) objectId = `deck:${objectId}`;
+        }
+
+        const zoneId = folderOfObjectId(objectId);
+        const { zone: placedZone, placed } = await pinToZone(projectId, { objectId, zoneId });
+
+        try {
+          ctx?.emit?.({
+            type: 'board.updated',
+            sessionId: null,          // project 级广播：显式压掉 ctx 的 sessionId enrich
+            objectId,
+            zoneId,
+            summary: zoneId ? `已把 ${objectId} 摆到「${zoneId}」里` : `已把 ${objectId} 摆到桌面上`,
+          });
+        } catch { /* emit fail-safe */ }
+
+        const where = placedZone?.id ? `in ${placedZone.id}` : 'on the desktop';
+        return {
+          content: [{
+            type: 'text',
+            text: `Surfaced ${objectId} ${where} at (${placed.x}, ${placed.y}). The user's canvas updates live.`,
+          }],
+        };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `pin_to_board failed: ${err.message}` }], isError: true };
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/preview-deck.js

@@ -1,130 +1,130 @@
-/**
- * mcp/tools/preview-deck.js — preview_deck MCP tool（2026-07-28）
- *
- * agent 主动把做好的 deck 摊到用户眼前：等价于用户在工作台上双击那张 deck 卡
- * ——收起态就展开成内嵌渲染，已经展开就开成画布内的最大化窗口。
- *
- * 实现：纯 emit run.deck_preview 事件（跟 navigate_to_page 同款控制层套路），
- * 路径归一在前端做（lib/stage.js 的 resolveObjectId 已经认得 tasks/<任务>/canvas.html
- * 和会话 cwd 的 canvas.html 两种形态）。
- */
-
-import { tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-import { Events } from '../../agent/events.js';
-import { setActiveDeck } from '../../../lib/artifact-target.js';
-import fs from 'node:fs/promises';
-import nodePath from 'node:path';
-import { taskManifest } from '../../../lib/kinds/index.js';
-
-/**
- * @param {object} deps
- * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
- */
-export function makePreviewDeckTool({ ctx, sessionId, workspaceRoot }) {
-  return tool(
-    'preview_deck',
-    `Show a deck to the user on their workbench — the same thing that happens
-when they double-click the deck card themselves: a collapsed card expands into
-a live embedded preview, an already-expanded one opens as a maximized window
-over the desktop.
-
-Use this when:
-- You just finished (or substantially changed) a deck and want the user to look
-- The user asks "show me" / "let me see it"
-- You're about to discuss a deck and want it on screen first
-
-Do NOT use it to spam attention mid-work — one call when the thing is worth
-looking at. This does not replace screenshot_canvas: that one is for **you** to
-see the render, this one is for **the user**.`,
-    {
-      path: z
-        .string()
-        .optional()
-        .describe(
-          "Deck to show, workspace-relative (e.g. 'canvas.html' or '稿件/主稿.html'). Omit for the active artifact.",
-        ),
-    },
-    async ({ path: rawPath }) => {
-      try {
-        const p = typeof rawPath === 'string' ? rawPath.trim().replace(/^\.\//, '') : '';
-        // 绝对路径同拒：这个 path 直发前端当寻址依据（home 幽灵族的家规）
-        if (p.includes('..') || p.startsWith('/')) {
-          return { content: [{ type: 'text', text: 'Invalid path (workspace-relative only).' }], isError: true };
-        }
-        // ⭐ 2026-08-18：先查这个文件在不在。
-        // 以前这里只挡 `..` 和绝对路径，然后无条件 emit + 回一句 "Opened …"。
-        // 传一个不存在的路径、或者传站点的子页时，用户桌面上打开的是**本会话的
-        // 空 canvas.html**，而 agent 拿到的是成功 —— 它没有任何办法察觉用户
-        // 正对着一块空白（问题库 iss_msr8oki7_z9su：「静默成功是最伤的部分」）。
-        let siteNote = null;
-        if (p) {
-          const abs = nodePath.join(workspaceRoot || '', p);
-          try {
-            await fs.access(abs);
-          } catch {
-            return {
-              content: [{ type: 'text', text:
-                `path not found: ${p} —— 先写出这个文件，或者用 list_pages 看清楚现有产物。`
-                + '（没有打开任何东西，用户桌面没变。）' }],
-              isError: true,
-            };
-          }
-          // 站点的子页：站点是整站一扇窗，打开的是站不是那一页 —— 如实说
-          try {
-            const manifest = await taskManifest(workspaceRoot);
-            const arts = manifest?.artifacts || [];
-            // ⛔ 原判据是 `(a.root ? p.startsWith(`${a.root}/`) : true)`。**根站的
-            // root 是空字符串**（site.js 里 `out.push({ srcRoot:'', root, ... })`），
-            // 于是三元退化成"任意路径都算这个站的一页"。后果是 `preview_deck("报告.docx")`
-            // 和 `preview_deck("_drafts/试作.html")` 都被回一句自信的假话
-            // 「还不在这个站的页面清单里…用户看到的是入口 index.html」——
-            // 两句都假：docx 开在 DocxWindow，草稿开在自己那扇 single:true 的窗。
-            // 改动本意是消灭"静默成功"，结果换成了反向的自信错话。
-            //
-            // 先看有没有**别的产物正好就是这个路径**（单页站、docx、deck…）——
-            // 有就是它自己开，跟根站无关。
-            const ownedByOther = arts.some(a => a.entryRel === p || a.file === p
-              || (a.single && (a.pages || []).includes(p)));
-            const site = ownedByOther ? null : arts.find((a) => {
-              if (a.kind !== 'site' || a.single) return false;
-              if (a.root) return p.startsWith(`${a.root}/`);   // 目录即边界，前缀够用
-              // 根站没有目录边界可用，只能按"是不是一张网页"+页面清单判
-              if (!/\.html?$/i.test(p)) return false;
-              return true;
-            });
-            if (site && p !== (site.entryRel || 'index.html')) {
-              // 2026-08-18 起子页**真的**开在那一页上（前端 entry 一路传到 SiteWindow）。
-              // 但只有在产物清单认得这一页时才成立 —— 不在清单里（比如刚写出来还没
-              // 重拉）就还是退回入口，所以这句话要如实分两种说。
-              const known = (site.pages || []).includes(
-                site.root ? p.slice(site.root.length + 1) : p);
-              siteNote = known
-                ? `打开的是站点「${site.root || '工作区根'}」并停在 ${p} 这一页（整站一扇窗，用户可以在窗里翻别的页）。`
-                : `注意：${p} 还不在这个站的页面清单里（产物列表下次重拉才认它），`
-                  + `所以用户看到的是入口 ${site.entryRel || 'index.html'}。`
-                  + '站内给它加一条真链接，或者等一轮再试。';
-            }
-          } catch { /* manifest 读不出来不挡预览 */ }
-          setActiveDeck(sessionId, p);   // 摊给用户看的那份就是"当前 deck"
-        }
-        ctx?.emit?.(Events.deckPreview(p));
-        return {
-          content: [{
-            type: 'text',
-            text: [
-              p ? `Opened ${p} on the user's workbench.`
-                : "Opened this session's deck on the user's workbench.",
-              siteNote,
-            ].filter(Boolean).join('\n'),
-          }],
-        };
-      } catch (err) {
-        return {
-          content: [{ type: 'text', text: `preview_deck failed: ${err?.message || String(err)}` }],
-          isError: true,
-        };
-      }
-    },
-  );
-}
+/**
+ * mcp/tools/preview-deck.js — preview_deck MCP tool（2026-07-28）
+ *
+ * agent 主动把做好的 deck 摊到用户眼前：等价于用户在工作台上双击那张 deck 卡
+ * ——收起态就展开成内嵌渲染，已经展开就开成画布内的最大化窗口。
+ *
+ * 实现：纯 emit run.deck_preview 事件（跟 navigate_to_page 同款控制层套路），
+ * 路径归一在前端做（lib/stage.js 的 resolveObjectId 已经认得 tasks/<任务>/canvas.html
+ * 和会话 cwd 的 canvas.html 两种形态）。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { Events } from '../../agent/events.js';
+import { setActiveDeck } from '../../../lib/artifact-target.js';
+import fs from 'node:fs/promises';
+import nodePath from 'node:path';
+import { taskManifest } from '../../../lib/kinds/index.js';
+
+/**
+ * @param {object} deps
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makePreviewDeckTool({ ctx, sessionId, workspaceRoot }) {
+  return tool(
+    'preview_deck',
+    `Show a deck to the user on their workbench — the same thing that happens
+when they double-click the deck card themselves: a collapsed card expands into
+a live embedded preview, an already-expanded one opens as a maximized window
+over the desktop.
+
+Use this when:
+- You just finished (or substantially changed) a deck and want the user to look
+- The user asks "show me" / "let me see it"
+- You're about to discuss a deck and want it on screen first
+
+Do NOT use it to spam attention mid-work — one call when the thing is worth
+looking at. This does not replace screenshot_canvas: that one is for **you** to
+see the render, this one is for **the user**.`,
+    {
+      path: z
+        .string()
+        .optional()
+        .describe(
+          "Deck to show, workspace-relative (e.g. 'canvas.html' or '稿件/主稿.html'). Omit for the active artifact.",
+        ),
+    },
+    async ({ path: rawPath }) => {
+      try {
+        const p = typeof rawPath === 'string' ? rawPath.trim().replace(/^\.\//, '') : '';
+        // 绝对路径同拒：这个 path 直发前端当寻址依据（home 幽灵族的家规）
+        if (p.includes('..') || p.startsWith('/')) {
+          return { content: [{ type: 'text', text: 'Invalid path (workspace-relative only).' }], isError: true };
+        }
+        // ⭐ 2026-08-18：先查这个文件在不在。
+        // 以前这里只挡 `..` 和绝对路径，然后无条件 emit + 回一句 "Opened …"。
+        // 传一个不存在的路径、或者传站点的子页时，用户桌面上打开的是**本会话的
+        // 空 canvas.html**，而 agent 拿到的是成功 —— 它没有任何办法察觉用户
+        // 正对着一块空白（问题库 iss_msr8oki7_z9su：「静默成功是最伤的部分」）。
+        let siteNote = null;
+        if (p) {
+          const abs = nodePath.join(workspaceRoot || '', p);
+          try {
+            await fs.access(abs);
+          } catch {
+            return {
+              content: [{ type: 'text', text:
+                `path not found: ${p} —— 先写出这个文件，或者用 list_pages 看清楚现有产物。`
+                + '（没有打开任何东西，用户桌面没变。）' }],
+              isError: true,
+            };
+          }
+          // 站点的子页：站点是整站一扇窗，打开的是站不是那一页 —— 如实说
+          try {
+            const manifest = await taskManifest(workspaceRoot);
+            const arts = manifest?.artifacts || [];
+            // ⛔ 原判据是 `(a.root ? p.startsWith(`${a.root}/`) : true)`。**根站的
+            // root 是空字符串**（site.js 里 `out.push({ srcRoot:'', root, ... })`），
+            // 于是三元退化成"任意路径都算这个站的一页"。后果是 `preview_deck("报告.docx")`
+            // 和 `preview_deck("_drafts/试作.html")` 都被回一句自信的假话
+            // 「还不在这个站的页面清单里…用户看到的是入口 index.html」——
+            // 两句都假：docx 开在 DocxWindow，草稿开在自己那扇 single:true 的窗。
+            // 改动本意是消灭"静默成功"，结果换成了反向的自信错话。
+            //
+            // 先看有没有**别的产物正好就是这个路径**（单页站、docx、deck…）——
+            // 有就是它自己开，跟根站无关。
+            const ownedByOther = arts.some(a => a.entryRel === p || a.file === p
+              || (a.single && (a.pages || []).includes(p)));
+            const site = ownedByOther ? null : arts.find((a) => {
+              if (a.kind !== 'site' || a.single) return false;
+              if (a.root) return p.startsWith(`${a.root}/`);   // 目录即边界，前缀够用
+              // 根站没有目录边界可用，只能按"是不是一张网页"+页面清单判
+              if (!/\.html?$/i.test(p)) return false;
+              return true;
+            });
+            if (site && p !== (site.entryRel || 'index.html')) {
+              // 2026-08-18 起子页**真的**开在那一页上（前端 entry 一路传到 SiteWindow）。
+              // 但只有在产物清单认得这一页时才成立 —— 不在清单里（比如刚写出来还没
+              // 重拉）就还是退回入口，所以这句话要如实分两种说。
+              const known = (site.pages || []).includes(
+                site.root ? p.slice(site.root.length + 1) : p);
+              siteNote = known
+                ? `打开的是站点「${site.root || '工作区根'}」并停在 ${p} 这一页（整站一扇窗，用户可以在窗里翻别的页）。`
+                : `注意：${p} 还不在这个站的页面清单里（产物列表下次重拉才认它），`
+                  + `所以用户看到的是入口 ${site.entryRel || 'index.html'}。`
+                  + '站内给它加一条真链接，或者等一轮再试。';
+            }
+          } catch { /* manifest 读不出来不挡预览 */ }
+          setActiveDeck(sessionId, p);   // 摊给用户看的那份就是"当前 deck"
+        }
+        ctx?.emit?.(Events.deckPreview(p));
+        return {
+          content: [{
+            type: 'text',
+            text: [
+              p ? `Opened ${p} on the user's workbench.`
+                : "Opened this session's deck on the user's workbench.",
+              siteNote,
+            ].filter(Boolean).join('\n'),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `preview_deck failed: ${err?.message || String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}