@xiaobuyu/nodesign 0.0.1

package/server/engine/mcp/tools/query-elements.js

@@ -0,0 +1,195 @@
+/**
+ * mcp/tools/query-elements.js — query_elements MCP tool
+ *
+ * 用 CSS selector 在 canvas.html 里 querySelectorAll，返回每个元素的
+ * { anchor, tag, text, bbox, layoutBox, dataAttrs } —— anchor schema 跟前端
+ * lib/html-utils.js 的 serializeAnchor 一致，agent 可以直接拿这个 anchor
+ * 喂回前端做精确选中（未来）或继续 query。
+ *
+ * 典型场景：
+ *   - "把所有 H1 字号统一成 56" → query_elements({selector:'h1'}) 拿全清单
+ *   - "找到 cover 上那个 cta 按钮" → query_elements({selector:'[data-anchor="cover-cta"]'})
+ *
+ * 限制：返回 max 50 条，溢出截断 + 文本提示。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { degradedNote } from './helpers/perception-page.js';
+import { acquireArtifactPage, LIVE_PARAM_DESC } from './helpers/acquire-page.js';
+import { resolveDeckSize, extractDeckAspect } from '../../../shared/deck.js';
+import { resolveCanvasTarget, CANVAS_PATH_DESC, KIND_SITE, requireBrowsable,
+} from '../../../lib/artifact-target.js';
+
+const MAX_RESULTS = 50;
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeQueryElementsTool({ workspaceRoot, projectId, sessionId, ctx: _ctx }) {
+  return tool(
+    'query_elements',
+    `Query elements in your artifact page (site page / deck) via CSS selector. Returns a list of
+matched elements with { anchor, tag, text, bbox, dataAttrs }.
+
+The anchor object (dataId / path / textHint / bbox) is the same schema used
+by the frontend selection system — you can reference it later to highlight
+or pin comments.
+
+Use when:
+- You need to inspect/operate on multiple elements matching a pattern
+  (all H1, all .cta, all data-anchor="page-N-title", etc.)
+- Before bulk-editing, get the current state list first
+- Verifying that a class / data-attr is applied where you expect
+
+Returns up to 50 matches; further results truncated with a hint.
+
+**bbox vs layoutBox** — bbox comes from getBoundingClientRect and INCLUDES CSS
+transforms; layoutBox (offsetTop/Left/Width/Height) is the layout box without
+them. Measure spacing with layoutBox, measure where-it-visually-sits with bbox.
+An element carrying an entry animation reports "transformed: true" — on those,
+bbox is offset by the animation and will give you impossible numbers.
+⚠️ **Plain CSS selectors only.** Playwright syntax (":has-text(...)", ">>",
+"nth=0") is NOT supported here and fails with a parser error. Use ASCII quotes,
+never HTML entities (""" reaches the selector literally and breaks it).`,
+    {
+      selector: z
+        .string()
+        .min(1)
+        .describe('CSS selector (e.g., "h1", ".accent", \'[data-anchor="cover-title"]\', \'section[data-page="2"] p\')'),
+      page: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Optional: scope query to a specific page (prepends section[data-page="N"] to selector)'),
+      path: z.string().optional().describe(CANVAS_PATH_DESC),
+      live: z.boolean().optional().describe(LIVE_PARAM_DESC),
+    },
+    async ({ selector, page: pageIndex, path: relPath, live }) => {
+      if (!workspaceRoot) {
+        return {
+          content: [{ type: 'text', text: 'No workspace bound; cannot query.' }],
+          isError: true,
+        };
+      }
+      const target = await resolveCanvasTarget(workspaceRoot, relPath, sessionId);
+      if (!target.ok) return { content: [{ type: 'text', text: target.message }], isError: true };
+      const notBrowsable = requireBrowsable(target);
+      if (notBrowsable) return { content: [{ type: 'text', text: notBrowsable }], isError: true };
+      const canvasPath = target.absPath;
+      let html;
+      try {
+        html = await fs.readFile(canvasPath, 'utf8');
+      } catch {
+        return { content: [{ type: 'text', text: `${target.relPath} not found in workspace.` }], isError: true };
+      }
+      // 站点没有 deck 比例：extractDeckAspect 找不到 __nd-deck-wrap 会静默回落到
+      // 16:9，于是按 1920x1080 量出来的盒子被当成真实布局报给 agent。站点按桌面档
+      // 1440 量，跟 screenshot_canvas 的 desktop 档一致。
+      const dims = target.kind === KIND_SITE
+        ? { width: 1440, height: 900 }
+        : resolveDeckSize(extractDeckAspect(html));
+
+      const finalSelector = pageIndex
+        ? `section[data-page="${pageIndex}"] ${selector}`
+        : selector;
+
+      let acq;
+      try {
+        // 页面从统一口拿（helpers/acquire-page.js）：live:true = 会话里现在这一页；否则新开走 http
+        acq = await acquireArtifactPage({ projectId, workspaceRoot, target, live, viewport: { width: dims.width, height: dims.height } });
+        const page = acq.page;
+        const opened = acq;
+
+        const result = await page.evaluate(({ sel, max }) => {
+          const els = Array.from(document.querySelectorAll(sel));
+          const total = els.length;
+          const slice = els.slice(0, max);
+
+          const computePath = (el) => {
+            const segments = [];
+            let cur = el;
+            while (cur && cur !== document.body && cur.nodeType === 1) {
+              const tag = cur.tagName.toLowerCase();
+              const parent = cur.parentNode;
+              if (!parent || parent.nodeType !== 1) break;
+              const sameType = Array.from(parent.children).filter(c => c.tagName === cur.tagName);
+              const idx = sameType.indexOf(cur) + 1;
+              segments.unshift(sameType.length > 1 ? `${tag}:nth-of-type(${idx})` : tag);
+              cur = parent;
+            }
+            return segments.join(' > ');
+          };
+
+          const items = slice.map((el) => {
+            const r = el.getBoundingClientRect();
+            // anchor 单写：dataId 字段值改读 data-anchor（跟前端 serializeAnchor 一致）
+            const dataId = el.getAttribute('data-anchor') || null;
+            const text = (el.textContent || '').trim();
+            const dataAttrs = {};
+            for (const a of Array.from(el.attributes)) {
+              if (a.name.startsWith('data-')) dataAttrs[a.name] = a.value;
+            }
+            // layoutBox / transformed（2026-08-18）：bbox 走 getBoundingClientRect，
+            // **CSS transform 算在里面**。带入场动画的页面（这平台上绝大多数页面）
+            // 元素静止态常挂着 translateY(26px)，量间距会得出物理上不可能的结果 ——
+            // 有个 agent 因此差点断言"最后一节和页脚重叠了"，靠 25≈26 这个巧合才
+            // 反应过来。offset* 是布局盒，不含 transform，两个都给就不会误判。
+            const cs = getComputedStyle(el);
+            const transformed = cs.transform !== 'none' && cs.transform !== '';
+            return {
+              anchor: {
+                dataId,
+                path: computePath(el),
+                textHint: text.slice(0, 50),
+                bbox: { x: r.x, y: r.y, w: r.width, h: r.height },
+              },
+              tag: el.tagName.toLowerCase(),
+              text: text.slice(0, 200),
+              bbox: { x: r.x, y: r.y, w: r.width, h: r.height },
+              layoutBox: { x: el.offsetLeft, y: el.offsetTop, w: el.offsetWidth, h: el.offsetHeight },
+              ...(transformed ? { transformed: true } : {}),
+              dataAttrs,
+            };
+          });
+
+          return { items, total };
+        }, { sel: finalSelector, max: MAX_RESULTS });
+
+        if (result.total === 0) {
+          return {
+            content: [{
+              type: 'text',
+              text: `No elements match selector: ${finalSelector}`,
+            }],
+          };
+        }
+
+        const truncatedNote = result.total > MAX_RESULTS
+          ? ` (showing first ${MAX_RESULTS} of ${result.total} matches)`
+          : '';
+
+        const degraded = degradedNote(opened);   // 契约：note 非空必须写进返回文本
+        return {
+          content: [{
+            type: 'text',
+            text: `${degraded ? `${degraded}\n\n` : ''}${acq.liveNote ? `${acq.liveNote}\n\n` : ''}Matched ${result.total} element(s)${truncatedNote}:`
+              + `\n\n${JSON.stringify(result.items, null, 2)}`,
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `query_elements failed: ${err?.message || String(err)}` }],
+          isError: true,
+        };
+      } finally {
+        await acq?.release?.();   // 一次性：关浏览器；live：松会话锁
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/read-board.js

@@ -0,0 +1,103 @@
+/**
+ * mcp/tools/read-board.js —— read_board（2026-08-14，agent 摆位批·读侧）
+ *
+ * 让 agent **看得见版面**。在这之前它对画布的了解只有关系线摘要 —— 每件东西
+ * 坐哪、挨着谁、谁是主角，全是盲区，"摆放"无从谈起。这个工具把 board.json
+ * 翻译成一张按层分组、按行排读的座次表。
+ *
+ * 口径说明（都写进输出，agent 不用猜）：
+ *   - 只列**摆过的**：board.json 是稀疏表，刚产出还没排座的产物没有条目
+ *     （前端首排后几百毫秒内落盘，通常都在）
+ *   - 层归属是服务端近似（zone 字段优先，其次沿路径找已知文件夹）
+ *   - 尺寸是形态估算（文字/涂鸦用存档实测值）
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { readBoard } from '../../../projects/board-store.js';
+import { estimateSize } from '../../../lib/board-kind-sizes.js';
+import { layerOf } from '../../../lib/canvas-id.js';
+import { relationsDigest } from '../../../lib/board-relations.js';
+
+/** 同一"行"的 y 容差：入座算法一行内顶对齐，40 世界像素内视作同行 */
+const ROW_TOLERANCE = 40;
+
+function describeEntry(id, entry) {
+  const sz = estimateSize(id, entry);
+  const at = `@(${Math.round(entry.x)},${Math.round(entry.y)}) ${Math.round(sz.w)}x${Math.round(sz.h)}`;
+  if (entry.kind === 'text') {
+    const t = String(entry.data?.t || '').replace(/\s+/g, ' ').slice(0, 24);
+    return `- [手写] 「${t}」 ${at} (id: ${id})${entry.by === 'agent' ? ' ·你写的' : ''}`;
+  }
+  if (entry.kind === 'scribble') return `- [涂鸦] ${at} (id: ${id})`;
+  return `- ${id} ${at}${entry.by === 'agent' ? ' ·你摆的' : ''}`;
+}
+
+export function makeReadBoardTool({ projectId }) {
+  return tool(
+    'read_board',
+    `Read the workbench canvas seating chart: what sits where, row by row, per folder layer.
+
+Use this BEFORE arranging anything (arrange_on_board) or writing notes near things
+(create_on_board) — placement without looking is guessing. Coordinates are world
+pixels; items listed top-to-bottom, left-to-right per row. Only items that have
+been seated appear (freshly produced artifacts get their seat within a second).`,
+    {
+      layer: z.string().max(300).optional()
+        .describe("Folder path to read ('' or omitted = the root desktop plus a folder list)"),
+    },
+    async ({ layer }) => {
+      if (!projectId) {
+        return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
+      }
+      const board = await readBoard(projectId);
+      const known = new Set(Object.keys(board.zones || {}));
+      const want = typeof layer === 'string' ? layer : '';
+
+      // 分层
+      const byLayer = new Map();
+      for (const [id, entry] of Object.entries(board.objects || {})) {
+        if (!Number.isFinite(entry?.x) || !Number.isFinite(entry?.y)) continue;
+        const l = layerOf(id, entry, known);
+        if (!byLayer.has(l)) byLayer.set(l, []);
+        byLayer.get(l).push({ id, entry });
+      }
+
+      const lines = [];
+      const renderLayer = (l) => {
+        const items = (byLayer.get(l) || []).sort((a, b) =>
+          (a.entry.y - b.entry.y) || (a.entry.x - b.entry.x));
+        if (!items.length) { lines.push('（这一层还没有摆过的东西）'); return; }
+        let rowY = null;
+        for (const { id, entry } of items) {
+          if (rowY === null || Math.abs(entry.y - rowY) > ROW_TOLERANCE) {
+            rowY = entry.y;
+            lines.push(`— 行 y≈${Math.round(rowY)} —`);
+          }
+          lines.push(describeEntry(id, entry));
+        }
+      };
+
+      lines.push(want ? `文件夹「${want}」的座次：` : '桌面（根层）的座次：');
+      renderLayer(want);
+      if (!want) {
+        const folders = Object.keys(board.zones || {}).sort();
+        if (folders.length) {
+          lines.push('', `文件夹卡：${folders.map(f => {
+            const zz = board.zones[f];
+            return `${f}@(${Math.round(zz.x)},${Math.round(zz.y)})`;
+          }).join('、')}`);
+        }
+      }
+      if (board.hero) lines.push('', `★ 显式主角：${board.hero}（arrange_on_board 的 feature/unfeature 管它）`);
+
+      try {
+        const digest = await relationsDigest(projectId, { limit: 16 });
+        if (digest) lines.push('', '关系线：', digest);
+      } catch { /* 关系读不到不挡座次 */ }
+
+      lines.push('', '（口径：稀疏表只列摆过的；层归属为服务端近似；尺寸为形态估算）');
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    },
+  );
+}

package/server/engine/mcp/tools/read-document.js

@@ -0,0 +1,93 @@
+/**
+ * mcp/tools/read-document.js — read_document MCP tool（2026-08-07）
+ *
+ * Word / Excel / PowerPoint 三种格式的读取口。
+ *
+ * 为什么需要它：用户往上下文托盘里拖一份 .docx（"照这份需求做一版海报"），
+ * agent 拿 Read 去读得到的是二进制乱码 —— **而且不报错**，它会当成一份读不懂
+ * 的文件继续往下干，交出一个跟需求无关的东西。这是最坏的一种失败：安静的。
+ *
+ * PDF 不走这里：SDK 的 Read 原生支持，2026-08-07 真跑验过。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { extractDocument, isExtractable, DOC_KINDS, MAX_CHARS } from '../../../lib/doc-extract.js';
+
+const EXT_LIST = Object.keys(DOC_KINDS).join(' / ');
+
+export function makeReadDocumentTool({ workspaceRoot, sharedRoot }) {
+  return tool(
+    'read_document',
+    `Read the text out of a Word / Excel / PowerPoint file (${EXT_LIST}).
+
+The plain Read tool CANNOT read these — they are zip archives, so Read returns
+binary garbage without failing, and you end up working from nothing. Whenever a
+user attaches or points at one of these files, use this tool instead.
+
+(PDF is different: the normal Read tool handles PDFs natively — use Read for those.)
+
+What you get back is text with structure markers, not layout:
+- .docx — the document text, headings/lists/tables flattened in reading order
+- .xlsx — one section per worksheet, rows as tab-separated cells
+- .pptx — one section per slide, in slide order
+
+Layout is deliberately not preserved. You are being asked what the document
+*says*; how it should look is your job to decide.
+
+Long files are cut at ${MAX_CHARS} characters and the result says so.`,
+    {
+      path: z.string().describe(
+        'Path to the file. Relative paths resolve against the session workspace, '
+        + 'then against the shared project dir (e.g. "assets/需求.docx").',
+      ),
+    },
+    async ({ path: rel }) => {
+      const fail = (text) => ({ content: [{ type: 'text', text }], isError: true });
+      try {
+        const raw = String(rel || '').trim();
+        if (!raw) return fail('read_document needs a path.');
+
+        // 绝对路径直接用；相对路径先会话工作区、再项目共享目录
+        const candidates = path.isAbsolute(raw)
+          ? [raw]
+          : [workspaceRoot && path.resolve(workspaceRoot, raw),
+             sharedRoot && path.resolve(sharedRoot, raw)].filter(Boolean);
+
+        let absPath = null;
+        for (const c of candidates) {
+          try { await fs.access(c); absPath = c; break; } catch { /* 下一个 */ }
+        }
+        if (!absPath) {
+          return fail(`File not found: ${raw}\nLooked in:\n${candidates.map(c => `  ${c}`).join('\n')}`);
+        }
+
+        if (!isExtractable(absPath)) {
+          const ext = path.extname(absPath).toLowerCase();
+          return fail(
+            ext === '.pdf'
+              ? 'PDFs are handled by the normal Read tool — call Read on this path instead.'
+              : `read_document only handles ${EXT_LIST}. For "${ext}" try the normal Read tool.`,
+          );
+        }
+
+        const { kind, text, chars, truncated, note } = await extractDocument(absPath);
+        if (!text) {
+          return {
+            content: [{ type: 'text', text: `${kind} ${path.basename(absPath)} 里没有可读的文字${note ? `（${note}）` : ''}。` }],
+          };
+        }
+        const head = [
+          `${kind}：${path.basename(absPath)}`,
+          `${chars} 字${truncated ? `，只给前 ${MAX_CHARS} 字` : ''}`,
+          note,
+        ].filter(Boolean).join(' · ');
+        return { content: [{ type: 'text', text: `${head}\n\n${text}` }] };
+      } catch (err) {
+        return fail(`read_document failed: ${err?.message || String(err)}`);
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/read-page.js

@@ -0,0 +1,264 @@
+/**
+ * mcp/tools/read-page.js — read_page MCP tool
+ *
+ * 让 agent 精确读 canvas.html 的某一页（`<section data-page="N">` 一段），
+ * 不必每次 Read 整个 canvas.html 然后自己切片。
+ *
+ * 行为：
+ *   - input: { page: number }（1-based，跟 data-page="N" 一致）
+ *   - 找 canvas.html 里 `<section[^>]*data-page="N"[^>]*>...</section>` 一段
+ *   - 返该段 outerHTML（含 attributes + 完整子树）
+ *   - **Hybrid 范式扩展（2026-05-06）**：检测 `<script type="text/babel">` 存在
+ *     时，section 里若有 `data-react-mount="xxx"` 或 React mount 用的 `id="xxx"`，
+ *     额外 grep babel script 里 `getElementById('xxx')` 上下文 (±20 行) 一并返
+ *     回——agent 想改 React 部分时不必再 Read 整个 babel script
+ *   - 找不到该页 → isError + 列出当前 canvas.html 实际有哪些 page
+ *   - canvas.html 不存在 → isError + 提示 agent 需要先 Write 创建
+ *
+ * 用 regex 而非 DOM parser：纯字符串匹配，避免 jsdom 等大依赖；
+ * canvas.html 是 agent 自己写的，section 嵌套不会出现（约定每页是 sibling section）。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { resolveCanvasTarget, CANVAS_PATH_DESC, KIND_SITE, requireBrowsable,
+} from '../../../lib/artifact-target.js';
+
+/**
+ * Thumbnail hint：检测 sectionHtml 是否含 `assets/generated/` 图 + thumbnails 目录存在
+ * 返 prepend hint 字符串（无需 hint 时返空）。
+ *
+ * 让 agent 知道：preview iframe 加载的 <img src> 是 thumbnail 快照（GET /canvas
+ * 路径透明改写），文件系统 / 这里返的 outerHTML 中 src 是真实 src，重生图后
+ * thumbnail 自动更新。
+ */
+async function detectThumbnailHint(workspaceRoot, sectionHtml) {
+  if (!workspaceRoot || !sectionHtml) return '';
+  if (!/assets\/generated\//.test(sectionHtml)) return '';
+  // thumbnail 与真实 src 的差别 08-21 起只在 generate-image cookbook 里说一次（每次 read_page 都带是 N 倍重复）
+  return '';
+}
+
+/**
+ * Hybrid 范式：从 section html 抽 mount id（data-react-mount + id 双源），
+ * 然后到 raw canvas.html 的 babel script 段里 grep `getElementById('<id>')` 上下文。
+ *
+ * 为什么取 ±20 行：覆盖 createRoot 调用 + 上方 component 函数定义大概率在这窗口内。
+ * agent 拿到这段后能直接看到 "<MyComponent .../>" 的调用 + 定义，不需要再 Read。
+ *
+ * @param {string} raw 整个 canvas.html
+ * @param {string} sectionHtml 当前 section outerHTML
+ * @returns {Array<{ mountId: string, snippet: string, startLine: number }>}
+ */
+function extractReactMountSources(raw, sectionHtml) {
+  // 1. 检测 hybrid（必有 babel script）
+  if (!/<script[^>]*type=["']text\/babel["']/i.test(raw)) return [];
+
+  // 2. 抽 section 里的 mount id —— data-react-mount 优先，id 兜底
+  const mountIds = new Set();
+  for (const m of sectionHtml.matchAll(/\bdata-react-mount\s*=\s*["']([^"']+)["']/gi)) mountIds.add(m[1]);
+  for (const m of sectionHtml.matchAll(/\bid\s*=\s*["']([^"']+)["']/gi)) mountIds.add(m[1]);
+  if (mountIds.size === 0) return [];
+
+  // 3. 抽出所有 <script type="text/babel">...</script> 段
+  const babelBlocks = [...raw.matchAll(/<script[^>]*type=["']text\/babel["'][^>]*>([\s\S]*?)<\/script>/gi)];
+  if (babelBlocks.length === 0) return [];
+
+  // 用整个 raw 行号做参考，方便 agent 知道 babel 段大概在文件哪里
+  const rawLines = raw.split('\n');
+  const segments = [];
+
+  for (const id of mountIds) {
+    // 在每个 babel 段里找 getElementById('<id>') 调用
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`getElementById\\s*\\(\\s*['"]${escaped}['"]\\s*\\)`, 'g');
+
+    for (const block of babelBlocks) {
+      const blockText = block[1];
+      if (!re.test(blockText)) { re.lastIndex = 0; continue; }
+      re.lastIndex = 0;
+
+      // 找 block 在 raw 中的起始行
+      const blockStartIdx = raw.indexOf(block[0]);
+      const blockStartLine = blockStartIdx >= 0 ? raw.slice(0, blockStartIdx).split('\n').length : 1;
+
+      // grep 行号（相对 block）
+      const blockLines = blockText.split('\n');
+      blockLines.forEach((line, i) => {
+        if (line.includes(`getElementById('${id}')`) || line.includes(`getElementById("${id}")`)) {
+          const start = Math.max(0, i - 20);
+          const end = Math.min(blockLines.length, i + 21);
+          const snippet = blockLines.slice(start, end).join('\n');
+          segments.push({
+            mountId: id,
+            snippet,
+            startLine: blockStartLine + start + 1,  // raw 文件行号
+          });
+        }
+      });
+      break;  // 一个 mount id 在第一个匹配的 block 找到就停（避免重复）
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeReadPageTool({ workspaceRoot, sessionId, ctx: _ctx }) {
+  return tool(
+    'read_page',
+    `DECK ONLY. Read a specific page (a single \`<section data-page="N">\`) from the deck .html.
+
+Use this instead of Read+Grep+offset/limit when you want to inspect or
+reason about one specific page in detail. Returns the outerHTML of that
+section (including attributes and full subtree).
+
+**Hybrid mode**: when the deck has \`<script type="text/babel">\` blocks
+(the Hybrid format from the deck starter canvas.template.html), this tool also
+returns the corresponding React mount source code for any
+\`data-react-mount\` / \`id\` attribute it finds in the section — so you
+don't need to Read the whole babel script just to find the component
+that renders to a mount point on this page.
+
+When to use:
+- "Show me what page 3 looks like in code" — read_page(3)
+- Before editing page N — read_page(N) to see exact current markup
+- Debugging why a specific page renders wrong
+
+When NOT to use:
+- Reading the whole deck structure → use Read on the deck .html with limit:50
+  to see all section openings
+- Finding a specific element across pages → use Grep
+- the deck file doesn't exist yet (creating from scratch) → use Write directly
+- sites: pages are separate files — Read them, or list_pages for the site map`,
+    {
+      page: z
+        .number()
+        .int()
+        .min(1)
+        .describe('Page number (1-based, matches data-page="N" attribute)'),
+      path: z.string().optional().describe(CANVAS_PATH_DESC),
+    },
+    async ({ page, path: relPath }) => {
+      try {
+        if (!workspaceRoot) {
+          return {
+            content: [{ type: 'text', text: 'No workspace bound; cannot read page.' }],
+            isError: true,
+          };
+        }
+
+        const target = await resolveCanvasTarget(workspaceRoot, relPath, sessionId);
+        if (!target.ok) return { content: [{ type: 'text', text: target.message }], isError: true };
+        const notBrowsable = requireBrowsable(target);
+        if (notBrowsable) return { content: [{ type: 'text', text: notBrowsable }], isError: true };
+        const canvasPath = target.absPath;
+        let raw;
+        try {
+          raw = await fs.readFile(canvasPath, 'utf8');
+        } catch (err) {
+          if (err.code === 'ENOENT') {
+            return {
+              content: [{
+                type: 'text',
+                text: 'That deck file does not exist yet. Use Write to create it first '
+                  + '(see SKILL.md for the section data-page="N" structure).',
+              }],
+              isError: true,
+            };
+          }
+          throw err;
+        }
+
+        // 匹配 `<section ... data-page="<page>" ...>...</section>`
+        // 双引号 / 单引号 / 不引号都接受。section 内不嵌套 section（约定）。
+        const pageStr = String(page);
+        const escaped = pageStr.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        // 三种 attribute quoting 尝试
+        const patterns = [
+          new RegExp(`<section\\b[^>]*\\bdata-page\\s*=\\s*"${escaped}"[^>]*>[\\s\\S]*?</section>`, 'i'),
+          new RegExp(`<section\\b[^>]*\\bdata-page\\s*=\\s*'${escaped}'[^>]*>[\\s\\S]*?</section>`, 'i'),
+          new RegExp(`<section\\b[^>]*\\bdata-page\\s*=\\s*${escaped}\\b[^>]*>[\\s\\S]*?</section>`, 'i'),
+        ];
+
+        let match = null;
+        for (const re of patterns) {
+          const m = raw.match(re);
+          if (m) { match = m; break; }
+        }
+
+        if (!match) {
+          // 列出 canvas.html 里实际有哪些 page，给 agent 反馈
+          const allPages = [...raw.matchAll(/<section\b[^>]*\bdata-page\s*=\s*['"]?(\d+)/gi)]
+            .map(m => m[1])
+            .filter((v, i, arr) => arr.indexOf(v) === i);
+          // 站点：分页读根本不适用，直说该怎么做，别丢一句"没有分页结构"让 agent
+          // 自己猜（它多半会改用 Read 全文件，把整份站点灌进上下文）
+          if (target.kind === KIND_SITE) {
+            return {
+              content: [{
+                type: 'text',
+                text: `${target.relPath} 是站点页面，没有 <section data-page="N"> 分页，read_page 的页码语义不适用。\n`
+                  + '站点这样读：先 list_pages 看站点结构（每页的标题 / 小标题 / 站内链接 / 断链），'
+                  + '要看某一页的实际内容用 query_elements 按 selector 取，或者直接 Read 那个文件（站点页面通常不大）。',
+              }],
+              isError: true,
+            };
+          }
+          const pagesList = allPages.length > 0
+            ? `Available pages: ${allPages.join(', ')}`
+            : `${target.relPath} has no <section data-page="N"> structure.`;
+          return {
+            content: [{
+              type: 'text',
+              text: `Page ${page} not found in ${target.relPath}. ${pagesList}`,
+            }],
+            isError: true,
+          };
+        }
+
+        const sectionHtml = match[0];
+
+        // Hybrid 范式扩展：检测 babel script + section 里的 mount id
+        // 找到 mount id 后从 babel script 抓 ±20 行上下文返给 agent
+        const hybridSegments = extractReactMountSources(raw, sectionHtml);
+
+        // Thumbnail hint：section 含 assets/generated/ 图 + thumbnails 目录存在 → prepend hint
+        const thumbnailHint = await detectThumbnailHint(workspaceRoot, sectionHtml);
+
+        const parts = [];
+        if (thumbnailHint) parts.push(thumbnailHint + '\n\n');
+        parts.push(`Page ${page} (${sectionHtml.length} chars):\n\n${sectionHtml}`);
+        if (hybridSegments.length > 0) {
+          parts.push(
+            `\n\n--- React mount sources for this page (${hybridSegments.length} mount${hybridSegments.length > 1 ? 's' : ''}) ---\n`
+            + hybridSegments.map(({ mountId, snippet, startLine }) =>
+                `\n## mount: ${mountId} (babel script line ~${startLine})\n\n\`\`\`tsx\n${snippet}\n\`\`\``
+              ).join('\n')
+          );
+        }
+
+        return {
+          content: [{
+            type: 'text',
+            text: parts.join(''),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text',
+            text: `read_page failed: ${err?.message || String(err)}`,
+          }],
+          isError: true,
+        };
+      }
+    },
+  );
+}