@xiaobuyu/nodesign 0.0.1 → 0.0.3

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

@@ -1,103 +1,190 @@
-/**
- * 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') }] };
-    },
-  );
-}
+/**
+ * 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 { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
+import { layerOf } from '../../../lib/canvas-id.js';
+import { relationsDigest, bindingLine } from '../../../lib/board-relations.js';
+import { groupObjects, asciiMinimap, bboxOfRects, relationOf, columnsOf, viewportRelation } from '../../../lib/board-groups.js';
+import { getViewpoint } from '../../../projects/viewpoint-store.js';
+import { chalkExcerpts, CHALK_DIR } from '../../../lib/chalk.js';
+import { getSharedDir } from '../../../projects/workspace.js';
+
+/** 同一"行"的 y 容差：入座算法一行内顶对齐，40 世界像素内视作同行 */
+const ROW_TOLERANCE = 40;
+
+function describeEntry(board, id, entry, glyph = null, excerpts = null) {
+  const sz = estimateSizeOn(board, id, entry);
+  const at = `@(${Math.round(entry.x)},${Math.round(entry.y)}) ${Math.round(sz.w)}x${Math.round(sz.h)}`;
+  const g = glyph ? `[${glyph}] ` : '';
+  const flags = `${entry.staging ? ' 〔草稿〕' : ''}${entry.tag ? ` #${entry.tag}` : ''}`;
+  const ch = excerpts?.get(id);
+  if (ch) return `- ${g}[板书·${ch.by === 'user' ? '用户' : '你'}写的] 「${ch.first}」 ${at} (path: ${id})${ch.anchor ? ` 关于 ${ch.anchor}` : ''}${ch.replyTo ? ` 回应 ${ch.replyTo}` : ''}${flags}`;
+  if (entry.kind === 'text') {
+    const t = String(entry.data?.t || '').replace(/\s+/g, ' ').slice(0, entry.data?.format === 'md' ? 60 : 24);
+    const md = entry.data?.format === 'md' ? 'md' : '手写';
+    return `- ${g}[${md}] 「${t}」 ${at} (id: ${id})${entry.by === 'agent' ? ' ·你写的' : ''}${flags}`;
+  }
+  if (entry.kind === 'scribble') return `- ${g}[涂鸦] ${at} (id: ${id})${entry.by === 'agent' ? ' ·你画的' : ''}${flags}`;
+  return `- ${g}${id} ${at}${entry.by === 'agent' ? ' ·你摆的' : ''}${flags}`;
+}
+
+export function makeReadBoardTool({ projectId }) {
+  return tool(
+    'read_board',
+    `Read the workbench canvas: an ASCII minimap, then GROUPS (things linked by lines or
+sharing a #tag), then loose items row by row, then relation lines.
+
+Use this BEFORE arranging (arrange_on_board), writing notes (create_on_board) or
+sketching (sketch_on_board) — placement without looking is guessing. Coordinates are
+world pixels. Only seated items appear (fresh artifacts get a seat within a second).
+Items marked 〔草稿〕 are still staging (yours from this turn, half-transparent until
+finish_sketch / end of turn). The user's current viewport (if known) is drawn as a box
+on the minimap and listed with what is inside it.`,
+    {
+      layer: z.string().max(300).optional()
+        .describe("Folder path to read ('' or omitted = the root desktop plus a folder list)"),
+      tag: z.string().max(40).optional()
+        .describe('Only list items/lines carrying this #tag (one group, e.g. a sketch you made)'),
+      minimap: z.boolean().optional().describe('Also print an ASCII minimap (off by default — the relative-position summary is usually enough)'),
+    },
+    async ({ layer, tag, minimap }) => {
+      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 excerpts = await chalkExcerpts(getSharedDir(projectId), (byLayer.get(want) || []).map(it => it.id));
+      const items = (byLayer.get(want) || [])
+        .filter(({ entry }) => !tag || entry.tag === tag)
+        // 板书条目但文件已经没了 = 幽灵座位，别列给 agent（删文件那条路会清座位，这是兜底）
+        .filter(({ id }) => !id.startsWith(`${CHALK_DIR}/`) || excerpts.has(id))
+        .sort((a, b) => (a.entry.y - b.entry.y) || (a.entry.x - b.entry.x));
+      const entryOf = new Map(items.map(it => [it.id, it.entry]));
+
+      // 小地图（用户视口画框）
+      const vp = getViewpoint(projectId);
+      const vpRect = (vp && (vp.layer || '') === want && vp.camera) ? vp.camera : null;
+      const rects = items.map(({ id, entry }) => ({ id, x: entry.x, y: entry.y, ...estimateSizeOn(board, id, entry) }));
+      const mini = asciiMinimap(rects, { viewport: vpRect });
+      const glyphOf = new Map(mini ? mini.legend : []);
+
+      lines.push(want ? `文件夹「${want}」的座次${tag ? `（只看 #${tag}）` : ''}：` : `桌面（根层）的座次${tag ? `（只看 #${tag}）` : ''}：`);
+      if (!items.length) {
+        lines.push('（这一层还没有摆过的东西）');
+      } else {
+        if (mini && minimap) {
+          lines.push(`小地图（一格≈${mini.cell}px，左上=(${mini.bbox.x},${mini.bbox.y})，范围 ${mini.bbox.w}x${mini.bbox.h}${vpRect ? '，┌┐└┘ 框=用户视口' : ''}）：`);
+          lines.push(mini.grid);
+        }
+        // 组：连通分量 + tag；≥2 件的才叫组，单件归「散件」按行列
+        const groups = groupObjects(items.map(it => it.id), board.bindings || {}, id => entryOf.get(id)?.tag || null);
+        const real = groups.filter(g => g.members.length >= 2);
+        const loose = groups.filter(g => g.members.length < 2).flatMap(g => g.members);
+        // 相对位置总览：每组的包围盒、列数、相对前一组/用户视口在哪（阅读顺序：先左后右、先上后下）
+        const rectOf = new Map(rects.map(r => [r.id, r]));
+        const boxes = real.map(g => bboxOfRects(g.members.map(id => rectOf.get(id)).filter(Boolean)));
+        const whole = bboxOfRects(rects);
+        if (whole) lines.push(`这一层内容范围：(${Math.round(whole.x)},${Math.round(whole.y)}) ${Math.round(whole.w)}x${Math.round(whole.h)}${vpRect ? `；用户视口 (${Math.round(vpRect.x)},${Math.round(vpRect.y)}) ${Math.round(vpRect.w)}x${Math.round(vpRect.h)}` : ''}`);
+        if (real.length) {
+          lines.push('各组位置（新东西默认排在已有内容的右侧或下方，顺着先左后右、先上后下的阅读顺序）：');
+          real.forEach((g, i) => {
+            const b = boxes[i]; if (!b) return;
+            const tags = [...g.tags].map(t => `#${t}`).join(' ') || `组 ${i + 1}`;
+            const cols = columnsOf(g.members.map(id => rectOf.get(id)).filter(Boolean));
+            const bits = [`(${Math.round(b.x)},${Math.round(b.y)}) ${Math.round(b.w)}x${Math.round(b.h)}`, cols.length > 1 ? `${cols.length} 列（${cols.map(c => c.n).join('/')} 件）` : '单列'];
+            if (i > 0 && boxes[0]) bits.push(`在 ${[...real[0].tags].map(t => `#${t}`).join(' ') || '组 1'} 的${relationOf(boxes[0], b)}`);
+            const vr = viewportRelation(vpRect, b); if (vr) bits.push(vr);
+            lines.push(`  ${tags}：${bits.join('；')}`);
+          });
+        }
+        real.forEach((g, i) => {
+          const tags = [...g.tags].map(t => `#${t}`).join(' ');
+          const staging = g.members.every(id => entryOf.get(id)?.staging);
+          lines.push('', `组 ${i + 1}${tags ? ` ${tags}` : ''}（${g.members.length} 件 ${g.edges.length} 线${staging ? '，草稿' : ''}）：`);
+          const sorted = g.members.map(id => ({ id, entry: entryOf.get(id) }))
+            .sort((a, b) => (a.entry.y - b.entry.y) || (a.entry.x - b.entry.x));
+          for (const { id, entry } of sorted) lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts));
+          for (const bid of g.edges.slice(0, 12)) lines.push(`    ${bindingLine(board.bindings[bid], board)} (line id: ${bid})`);
+          if (g.edges.length > 12) lines.push(`    …还有 ${g.edges.length - 12} 条线`);
+        });
+        if (groups.cross?.length) {
+          lines.push('', '组间线：');
+          for (const bid of groups.cross.slice(0, 12)) lines.push(`    ${bindingLine(board.bindings[bid], board)} (line id: ${bid})`);
+        }
+        if (loose.length) {
+          lines.push('', real.length ? '散件：' : '');
+          let rowY = null;
+          const sorted = loose.map(id => ({ id, entry: entryOf.get(id) }))
+            .sort((a, b) => (a.entry.y - b.entry.y) || (a.entry.x - b.entry.x));
+          for (const { id, entry } of sorted) {
+            if (rowY === null || Math.abs(entry.y - rowY) > ROW_TOLERANCE) {
+              rowY = entry.y;
+              lines.push(`— 行 y≈${Math.round(rowY)} —`);
+            }
+            lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts));
+          }
+        }
+      }
+      if (!want && !tag) {
+        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 && !tag) lines.push('', `★ 显式主角：${board.hero}（arrange_on_board 的 feature/unfeature 管它）`);
+
+      // 用户视点（有上报才有）
+      if (vp && !tag) {
+        const inside = vpRect ? rects.filter(r =>
+          !(r.x + r.w < vpRect.x || r.x > vpRect.x + vpRect.w || r.y + r.h < vpRect.y || r.y > vpRect.y + vpRect.h))
+          .map(r => r.id) : [];
+        const bits = [];
+        if (vpRect) bits.push(`视口 (${Math.round(vpRect.x)},${Math.round(vpRect.y)}) ${Math.round(vpRect.w)}x${Math.round(vpRect.h)} 缩放 ${vp.zoom ?? '?'}`);
+        if (vp.openWindow) bits.push(`开着窗：${vp.openWindow}${vp.openPage ? `（${vp.openPage}）` : ''}`);
+        if (vp.selected?.length) bits.push(`选中：${vp.selected.slice(0, 8).join('、')}`);
+        if (inside.length) bits.push(`视口里有：${inside.slice(0, 12).join('、')}${inside.length > 12 ? ' 等' : ''}`);
+        const age = Math.round((Date.now() - (vp.at || 0)) / 1000);
+        lines.push('', `用户此刻（${age}s 前上报）：${bits.join('；') || '只知道在看这一层'}`);
+      }
+
+      if (!tag) {
+        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

@@ -1,93 +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)}`);
-      }
-    },
-  );
-}
+/**
+ * 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)}`);
+      }
+    },
+  );
+}