@xiaobuyu/nodesign 0.0.2 → 0.0.3

package/server/engine/mcp/tools/edit-sketch.js

@@ -0,0 +1,167 @@
+/**
+ * mcp/tools/edit-sketch.js —— edit_sketch（2026-08-23 黑板二期）
+ *
+ * 改已有的图，不重画。原则抄用户自己的 AI-Annotation-demo 里那条「引用，不吐坐标」：
+ * agent 只引用画布 id，位置用**相对关系**表达（在某件东西的右边/下面/上面/左边、
+ * 或网格位移），像素由服务端解析 —— 让模型吐绝对坐标必幻觉。
+ *
+ * 一次调用一批操作（按序执行，一条坏了其余照做并在返回里报）：
+ *   set_text   改字（文字节点：内容/格式/字号/颜色）
+ *   move       挪一件：to {ref, side, gap?} 或 {dx, dy}（网格单位）
+ *   move_group 挪一组（同 tag 的全部，保持相对位置）：to 同上
+ *   remove     删一件画布原生物件（text/scribble）；产物卡不删（只能摘标签）
+ *   add_node   加一个文字节点，位置 at {ref, side, gap?}，归进 tag
+ *   add_edge / set_edge / remove_edge   线的增改删（线 id 见 read_board）
+ * 改完前端按 board.updated 整份重拉；默认不进 staging（改的是已落定的图）。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { readBoard, patchBoard, TEXT_FONTS } from '../../../projects/board-store.js';
+import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
+import { layerOf, normalizeCanvasId } from '../../../lib/canvas-id.js';
+import { BINDING_TYPE_IDS, BINDING_MATERIALS } from '../../../lib/binding-types.js';
+import { UNIT, textBox } from '../../../lib/sketch-layout.js';
+
+const MAX_OPS = 40;
+let seq = 0;
+const stamp = () => `${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
+
+const REL = z.object({
+  ref: z.string().min(1).max(300).describe('canvas id to place relative to'),
+  side: z.enum(['right', 'left', 'above', 'below']),
+  gap: z.number().min(0).max(40).optional().describe('grid units (default 1)'),
+});
+const DELTA = z.object({ dx: z.number().min(-200).max(200), dy: z.number().min(-200).max(200) }).describe('grid units');
+const TO = z.union([REL, DELTA]);
+
+const OP = z.discriminatedUnion('op', [
+  z.object({ op: z.literal('set_text'), id: z.string().min(1).max(300), text: z.string().min(1).max(4000).optional(), format: z.enum(['plain', 'md']).optional(), size: z.enum(['sm', 'md', 'lg', 'xl']).optional(), color: z.enum(['ink', 'red', 'pencil', 'brass']).optional(), font: z.enum(['pen', 'kai', 'sans', 'serif', 'mono']).optional() }),
+  z.object({ op: z.literal('move'), id: z.string().min(1).max(300), to: TO }),
+  z.object({ op: z.literal('move_group'), tag: z.string().min(1).max(40), to: TO }),
+  z.object({ op: z.literal('remove'), id: z.string().min(1).max(300) }),
+  z.object({ op: z.literal('add_node'), id: z.string().regex(/^[A-Za-z0-9_-]{1,24}$/).optional().describe('local handle to reference in later ops of this call'), text: z.string().min(1).max(4000), format: z.enum(['plain', 'md']).optional(), size: z.enum(['sm', 'md', 'lg', 'xl']).optional(), font: z.enum(['pen', 'kai', 'sans', 'serif', 'mono']).optional(), color: z.enum(['ink', 'red', 'pencil', 'brass']).optional(), at: REL, tag: z.string().max(40).optional() }),
+  z.object({ op: z.literal('add_edge'), from: z.string().min(1).max(300), to: z.string().min(1).max(300), type: z.enum(BINDING_TYPE_IDS).optional(), material: z.enum(BINDING_MATERIALS).optional(), label: z.string().max(60).optional(), tag: z.string().max(40).optional() }),
+  z.object({ op: z.literal('set_edge'), id: z.string().min(1).max(300), label: z.string().max(60).optional(), type: z.enum(BINDING_TYPE_IDS).optional(), material: z.enum(BINDING_MATERIALS).optional() }),
+  z.object({ op: z.literal('remove_edge'), id: z.string().min(1).max(300) }),
+]);
+
+export function makeEditSketchTool({ projectId, ctx }) {
+  return tool(
+    'edit_sketch',
+    `Edit what is already on the board — by id, without redrawing. Positions are RELATIVE
+(to {ref, side, gap} = beside/above/below another canvas id) or grid deltas ({dx,dy},
+1 cell = ${UNIT}px); you never give absolute coordinates. ids come from read_board
+(nodes: text:…/scribble:…, cards: deck:…/site:…/paths; lines: b:…).
+ops (run in order; a failing op is reported, the rest still apply):
+ set_text{id,text?,format?,size?,color?,font?} · move{id,to} · move_group{tag,to} ·
+ remove{id} · add_node{id?,text,at:{ref,side,gap?},…} · add_edge{from,to,type?,material?,label?} ·
+ set_edge{id,label?,type?,material?} · remove_edge{id}
+Use this for "move A under B", "rephrase that note", "add a branch", "delete the
+wrong line". For a brand-new diagram use sketch_on_board.`,
+    {
+      tag: z.string().max(40).optional().describe('Default tag for add_node/add_edge (the sketch you are editing)'),
+      ops: z.array(OP).min(1).max(MAX_OPS),
+    },
+    async ({ tag: defaultTag, ops }) => {
+      const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
+      if (!projectId) return err('No project bound.');
+      const board = await readBoard(projectId);
+      const known = new Set(Object.keys(board.zones || {}));
+      const objects = {}; const bindings = {};      // 增量 patch
+      const live = { ...board.objects };             // 本次调用内的"当前态"（让后一条 op 看见前一条的结果）
+      const local = new Map();                       // add_node 的本地句柄 → canvas id
+      const rid = (raw) => { if (local.has(raw)) return local.get(raw); const c = normalizeCanvasId(raw); return c && live[c] ? c : null; };
+      const rectOf = (id) => { const e = live[id]; return e ? { x: e.x, y: e.y, ...estimateSizeOn(board, id, e) } : null; };
+      const placeRel = (box, rel) => {
+        const r = rectOf(rid(rel.ref));
+        if (!r) return null;
+        const g = (rel.gap ?? 1) * UNIT;
+        if (rel.side === 'right') return { x: r.x + r.w + g, y: r.y };
+        if (rel.side === 'left') return { x: r.x - g - box.w, y: r.y };
+        if (rel.side === 'below') return { x: r.x, y: r.y + r.h + g };
+        return { x: r.x, y: r.y - g - box.h };
+      };
+      const report = []; let ok = 0;
+      const setObj = (id, e) => { live[id] = e; objects[id] = e; };
+
+      for (let i = 0; i < ops.length; i += 1) {
+        const o = ops[i];
+        const fail = (why) => report.push(`✗ #${i + 1} ${o.op}: ${why}`);
+        try {
+          if (o.op === 'set_text') {
+            const id = rid(o.id); const e = id && live[id];
+            if (!e || e.kind !== 'text') { fail(`${o.id} 不是文字节点`); continue; }
+            const data = { ...e.data };
+            if (o.text) data.t = o.text;
+            if (o.format) { if (o.format === 'md') data.format = 'md'; else delete data.format; }
+            if (o.size) data.size = o.size; if (o.color) data.color = o.color; if (o.font && TEXT_FONTS.includes(o.font)) data.font = o.font;
+            const box = textBox(data.t, data.size || 'md', { md: data.format === 'md' });
+            setObj(id, { ...e, data, w: box.w, h: box.h }); ok += 1;
+          } else if (o.op === 'move') {
+            const id = rid(o.id); const e = id && live[id];
+            if (!e) { fail(`${o.id} 不在板上`); continue; }
+            const box = rectOf(id);
+            const p = 'ref' in o.to ? placeRel(box, o.to) : { x: e.x + o.to.dx * UNIT, y: e.y + o.to.dy * UNIT };
+            if (!p) { fail(`参照 ${o.to.ref} 不在板上`); continue; }
+            setObj(id, { ...e, x: Math.round(p.x), y: Math.round(p.y) }); ok += 1;
+          } else if (o.op === 'move_group') {
+            const members = Object.entries(live).filter(([, e]) => e.tag === o.tag && Number.isFinite(e?.x));
+            if (!members.length) { fail(`没有 #${o.tag} 的东西`); continue; }
+            const bb = { x: Math.min(...members.map(([, e]) => e.x)), y: Math.min(...members.map(([, e]) => e.y)) };
+            const rects = members.map(([id]) => rectOf(id));
+            const w = Math.max(...rects.map(r => r.x + r.w)) - bb.x; const h = Math.max(...rects.map(r => r.y + r.h)) - bb.y;
+            const p = 'ref' in o.to ? placeRel({ w, h }, o.to) : { x: bb.x + o.to.dx * UNIT, y: bb.y + o.to.dy * UNIT };
+            if (!p) { fail(`参照 ${o.to.ref} 不在板上`); continue; }
+            const dx = Math.round(p.x - bb.x); const dy = Math.round(p.y - bb.y);
+            for (const [id, e] of members) setObj(id, { ...e, x: e.x + dx, y: e.y + dy });
+            ok += 1;
+          } else if (o.op === 'remove') {
+            const id = rid(o.id); const e = id && live[id];
+            if (!e) { fail(`${o.id} 不在板上`); continue; }
+            if (!e.kind) { fail(`${id} 是产物卡，不能从黑板删；要摘标签用 finish_sketch erase`); continue; }
+            delete live[id]; objects[id] = null; ok += 1;
+          } else if (o.op === 'add_node') {
+            const size = (o.size === 'sm' && o.text.length > 40) ? 'md' : (o.size || 'md');
+            const box = textBox(o.text, size, { md: o.format === 'md' });
+            const p = placeRel(box, o.at);
+            if (!p) { fail(`参照 ${o.at.ref} 不在板上`); continue; }
+            const refId = rid(o.at.ref);
+            const zone = layerOf(refId, live[refId], known);
+            const id = `text:a${stamp()}`;
+            const tag = o.tag || defaultTag || live[refId]?.tag || null;
+            setObj(id, {
+              x: Math.round(p.x), y: Math.round(p.y), z: 1, w: box.w, h: box.h, kind: 'text',
+              data: { t: o.text, ...(o.format === 'md' ? { format: 'md' } : {}), font: TEXT_FONTS.includes(o.font) ? o.font : 'pen', size, color: o.color || 'ink' },
+              zone, by: 'agent', ...(tag ? { tag } : {}),
+            });
+            if (o.id) local.set(o.id, id);
+            report.push(`+ node ${o.id ? `${o.id}=` : ''}${id}`); ok += 1;
+          } else if (o.op === 'add_edge') {
+            const from = rid(o.from); const to = rid(o.to);
+            if (!from || !to || from === to) { fail(`端点不在板上：${o.from} → ${o.to}`); continue; }
+            const id = `b:a${stamp()}`;
+            const tag = o.tag || defaultTag || live[from]?.tag || live[to]?.tag || null;
+            bindings[id] = { type: o.type || 'link', from, to, by: 'agent', ...(o.material && o.material !== 'ink' ? { material: o.material } : {}), ...(o.label ? { label: o.label } : {}), ...(tag ? { tag } : {}) };
+            report.push(`+ edge ${id}`); ok += 1;
+          } else if (o.op === 'set_edge') {
+            const b = board.bindings?.[o.id];
+            if (!b) { fail(`线 ${o.id} 不存在`); continue; }
+            const nb = { ...b };
+            if (o.label !== undefined) { if (o.label) nb.label = o.label; else delete nb.label; }
+            if (o.type) nb.type = o.type;
+            if (o.material) { if (o.material === 'ink') delete nb.material; else nb.material = o.material; }
+            bindings[o.id] = nb; ok += 1;
+          } else if (o.op === 'remove_edge') {
+            if (!board.bindings?.[o.id]) { fail(`线 ${o.id} 不存在`); continue; }
+            bindings[o.id] = null; ok += 1;
+          }
+        } catch (e) { fail(String(e?.message || e).slice(0, 120)); }
+      }
+      if (!ok) return err(`没有一条操作成功：\n${report.join('\n')}`);
+      await patchBoard(projectId, { objects, bindings });
+      try { ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `改了黑板（${ok} 处）` }); } catch { /* */ }
+      return { content: [{ type: 'text', text: `Applied ${ok}/${ops.length} op(s).${report.length ? `\n${report.join('\n')}` : ''}` }] };
+    },
+  );
+}

package/server/engine/mcp/tools/look-at-board.js

@@ -0,0 +1,124 @@
+/**
+ * mcp/tools/look-at-board.js —— look_at_board（2026-08-23 黑板）
+ *
+ * agent 的眼睛。在这之前它对画布只有文字座次表；画了涂鸦/草图看不见结果，
+ * 08-14 才会说"agent 画矢量笔迹没意义"。有了眼睛，涂鸦就是有回路的事：
+ * 画一笔、看一眼、改一笔。
+ *
+ * 怎么看：用常驻 chromium 打开**用户看的同一张画布页**（?eye=1 眼睛模式，见前端
+ * eye-mode.js），等页面把相机摆好打 data-eye-ready，截一张 PNG 回来。不另写服务端
+ * 渲染器 —— 同一件东西两个实例会分叉（最贵的一课）。
+ *
+ * 入口地址：hosted 模式下 SPA 由 nginx 发（node 只出 API），所以要 NODESIGN_WEB_ORIGIN
+ * 指到对外入口（exp: https://…:8443）；本地分发版 node 自己发 dist，走 127.0.0.1。
+ * 两者都没有 → 工具老实说看不了，别静默截一张 API 404 页。
+ *
+ * 代价：1 vCPU 上一张图几秒钟 + 一阵 CPU；token 按像素算（1400×900 ≈ 1.7k），
+ * 所以按需调用，不做每回合自动注入。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { getProject } from '../../../projects/store.js';
+import { getUserById } from '../../../auth/users-store.js';
+import { COOKIE_NAME, mintToken, authEnabled } from '../../../auth/session.js';
+import { platform } from '../../../runtime/platform.js';
+import { launchPerceptionBrowser, PERCEPTION_ORIGIN } from './helpers/perception-page.js';
+import { readBoard } from '../../../projects/board-store.js';
+import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
+import { normalizeCanvasId } from '../../../lib/canvas-id.js';
+
+const VIEW = { width: 1400, height: 900 };
+const READY_TIMEOUT_MS = 25_000;
+// 并发闸：一次只开一台 chromium 看板（1 vCPU 机器多会话同时看板 = 多个浏览器进程；fable 08-23 P2）。
+// 排队不拒绝，等前一个看完。
+let gate = Promise.resolve();
+const withGate = (fn) => { const run = gate.then(fn, fn); gate = run.catch(() => {}); return run; };
+
+export function webOrigin() {
+  const env = String(process.env.NODESIGN_WEB_ORIGIN || '').trim().replace(/\/+$/, '');
+  if (env) return env;
+  if (platform?.serveWeb) return PERCEPTION_ORIGIN;
+  return null;
+}
+
+export function makeLookAtBoardTool({ projectId }) {
+  return tool(
+    'look_at_board',
+    `LOOK at the canvas (a real screenshot of the board as the user sees it). Use it after
+sketch_on_board / create_on_board / relate_on_board to check what you drew, or when the
+user talks about how things look on the board. Pick a region — the whole board shrunk
+into one image is unreadable:
+- tag: frame the group carrying this #tag (a sketch you made)
+- around: frame this canvas id (and some margin)
+- view: explicit world rect {x,y,w,h} (coordinates from read_board)
+- none of the above: everything (overview only)
+Costs a few seconds and ~1.7k tokens; don't call it in a loop.`,
+    {
+      tag: z.string().max(40).optional(),
+      around: z.string().max(300).optional(),
+      margin: z.number().min(0).max(2000).optional().describe('World px of margin around `around` (default 160)'),
+      view: z.object({ x: z.number(), y: z.number(), w: z.number().min(50), h: z.number().min(50) }).optional(),
+    },
+    async ({ tag, around, margin, view }) => {
+      const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
+      if (!projectId) return err('No project bound.');
+      const origin = webOrigin();
+      if (!origin) {
+        return err('look_at_board 不可用：这台服务不知道画布页的入口地址（hosted 模式 SPA 由 nginx 发）。'
+          + '管理员在 .env 设 NODESIGN_WEB_ORIGIN=https://<域名>[:端口] 后重启即可。本地分发版自动可用。');
+      }
+      let box = view || null;
+      let what = 'whole board';
+      if (!box && around) {
+        const board = await readBoard(projectId);
+        const id = normalizeCanvasId(around);
+        const e = id ? board.objects?.[id] : null;
+        if (!e || !Number.isFinite(e.x)) return err(`${around} 还没有座位（read_board 里看不到就框不上）。`);
+        const sz = estimateSizeOn(board, id, e); const m = margin ?? 160;
+        box = { x: e.x - m, y: e.y - m, w: sz.w + m * 2, h: sz.h + m * 2 };
+        what = `around ${id}`;
+      }
+      if (tag && !box) what = `group #${tag}`;
+      if (box) what = `${what === 'whole board' ? 'rect' : what} (${Math.round(box.x)},${Math.round(box.y)}) ${Math.round(box.w)}x${Math.round(box.h)}`;
+
+      const q = new URLSearchParams({ eye: '1' });
+      if (box) q.set('view', [box.x, box.y, box.w, box.h].map(n => Math.round(n)).join(','));
+      else if (tag) q.set('tag', tag);
+      const url = `${origin}/projects/${encodeURIComponent(projectId)}/work?${q}`;
+
+      return withGate(async () => {
+      let browser = null;
+      try {
+        browser = await launchPerceptionBrowser();
+        const context = await browser.newContext({ viewport: VIEW, deviceScaleFactor: 1 });
+        if (authEnabled()) {
+          const ownerId = getProject(projectId)?.ownerId;
+          const owner = ownerId ? getUserById(ownerId) : null;
+          if (!ownerId || !owner || owner.disabled) return err('look_at_board：项目所有者账号不可用（不存在或已停用），拿不到看画布的身份。');
+          await context.addCookies([{ name: COOKIE_NAME, value: mintToken(ownerId), url: origin }]);
+        }
+        const page = await context.newPage();
+        const resp = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20_000 });
+        if (resp && resp.status() >= 400) return err(`画布页打不开：HTTP ${resp.status()}（${origin}）。NODESIGN_WEB_ORIGIN 指对了吗？`);
+        try {
+          await page.waitForSelector('html[data-eye-ready="1"]', { timeout: READY_TIMEOUT_MS });
+        } catch {
+          return err('画布页没在 25s 内就绪（data-eye-ready 没出现）。多半是入口不对或登录被拒；截图放弃。');
+        }
+        const png = await page.screenshot({ type: 'png', fullPage: false });
+        const data = png.toString('base64');
+        // 眼睛模式页面会把相机摆到的真实矩形写在 dataset 里（如果前端给了就报）
+        const shown = await page.evaluate(() => document.documentElement.dataset.eyeView || null).catch(() => null);
+        const text = `Board view: ${what}${shown ? ` — camera showed world rect ${shown}` : ''}. ${VIEW.width}x${VIEW.height} px. `
+          + 'Half-transparent items are still staging. Lines: red with pins = yarn, wobbly = pencil, plain = ink.';
+        return { content: [{ type: 'text', text }, { type: 'image', data, mimeType: 'image/png' }] };
+      } catch (e) {
+        return err(`look_at_board failed: ${String(e?.message || e).slice(0, 200)}`);
+      } finally {
+        try { await browser?.close(); } catch { /* noop */ }
+      }
+      });
+    },
+  );
+}

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

@@ -15,38 +15,53 @@
 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 { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
 import { layerOf } from '../../../lib/canvas-id.js';
-import { relationsDigest } from '../../../lib/board-relations.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(id, entry) {
-  const sz = estimateSize(id, entry);
+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, 24);
-    return `- [手写] 「${t}」 ${at} (id: ${id})${entry.by === 'agent' ? ' ·你写的' : ''}`;
+    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 `- [涂鸦] ${at} (id: ${id})`;
-  return `- ${id} ${at}${entry.by === 'agent' ? ' ·你摆的' : ''}`;
+  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 seating chart: what sits where, row by row, per folder layer.
+    `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 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).`,
+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 }) => {
+    async ({ layer, tag, minimap }) => {
       if (!projectId) {
         return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
       }
@@ -64,23 +79,79 @@ been seated appear (freshly produced artifacts get their seat within a second).`
       }
 
       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)} —`);
+      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));
           }
-          lines.push(describeEntry(id, entry));
         }
-      };
-
-      lines.push(want ? `文件夹「${want}」的座次：` : '桌面（根层）的座次：');
-      renderLayer(want);
-      if (!want) {
+      }
+      if (!want && !tag) {
         const folders = Object.keys(board.zones || {}).sort();
         if (folders.length) {
           lines.push('', `文件夹卡：${folders.map(f => {
@@ -89,12 +160,28 @@ been seated appear (freshly produced artifacts get their seat within a second).`
           }).join('、')}`);
         }
       }
-      if (board.hero) lines.push('', `★ 显式主角：${board.hero}（arrange_on_board 的 feature/unfeature 管它）`);
+      if (board.hero && !tag) lines.push('', `★ 显式主角：${board.hero}（arrange_on_board 的 feature/unfeature 管它）`);
 
-      try {
-        const digest = await relationsDigest(projectId, { limit: 16 });
-        if (digest) lines.push('', '关系线：', digest);
-      } catch { /* 关系读不到不挡座次 */ }
+      // 用户视点（有上报才有）
+      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-user-view.js

@@ -0,0 +1,59 @@
+/**
+ * mcp/tools/read-user-view.js —— read_user_view（2026-08-23 黑板）
+ *
+ * 「用户此刻在看哪」：视口世界矩形 + 缩放 + 当前层 + 开着的窗 + 选中集 +
+ * 视口里有哪些东西。前端节流上报、服务端只留最近一份（viewpoint-store）。
+ * UserPromptSubmit 注入一行摘要（只报变化）；细节走这个工具。
+ * 指代消解的顺序：选中的 > 开着的窗 > 视口中心附近的东西。
+ */
+
+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 { getViewpoint, describeViewpoint } from '../../../projects/viewpoint-store.js';
+import { describeEndpoint } from '../../../lib/board-relations.js';
+
+export function makeReadUserViewTool({ projectId }) {
+  return tool(
+    'read_user_view',
+    `What the user is looking at RIGHT NOW: viewport (world rect + zoom), which folder
+layer, which artifact window is open, what is selected, and which items are inside the
+viewport (sorted by distance to its centre). Use it to resolve "this / here / that one"
+and to decide where a sketch or note should land so the user actually sees it. Resolve
+pointers in this order: selected > open window > items near the viewport centre.`,
+    { _: z.string().max(1).optional().describe('(no arguments)') },
+    async () => {
+      if (!projectId) return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
+      const vp = getViewpoint(projectId);
+      if (!vp) return { content: [{ type: 'text', text: '还没有用户视点上报（用户没开着画布页，或上报过期 >10 分钟）。' }] };
+      const board = await readBoard(projectId);
+      const known = new Set(Object.keys(board.zones || {}));
+      const layer = vp.layer || '';
+      const rects = Object.entries(board.objects || {})
+        .filter(([id, e]) => Number.isFinite(e?.x) && layerOf(id, e, known) === layer)
+        .map(([id, e]) => ({ id, x: e.x, y: e.y, ...estimateSizeOn(board, id, e) }));
+      const lines = [`用户此刻（${Math.round((Date.now() - vp.at) / 1000)}s 前上报）：${describeViewpoint(vp, rects) || '未知'}`];
+      if (vp.camera) {
+        const c = vp.camera; const cx = c.x + c.w / 2; const cy = c.y + c.h / 2;
+        const inside = rects
+          .filter(r => !(r.x + r.w < c.x || r.x > c.x + c.w || r.y + r.h < c.y || r.y > c.y + c.h))
+          .map(r => ({ ...r, d: Math.hypot(r.x + r.w / 2 - cx, r.y + r.h / 2 - cy) }))
+          .sort((a, b) => a.d - b.d);
+        if (inside.length) {
+          lines.push('视口里（离中心由近到远）：');
+          for (const r of inside.slice(0, 20)) {
+            const e = board.objects[r.id];
+            const flags = `${e.staging ? ' 〔草稿〕' : ''}${e.tag ? ` #${e.tag}` : ''}`;
+            lines.push(`- ${describeEndpoint(r.id, board)} @(${Math.round(r.x)},${Math.round(r.y)}) ${Math.round(r.w)}x${Math.round(r.h)} (id: ${r.id})${flags}`);
+          }
+          if (inside.length > 20) lines.push(`…还有 ${inside.length - 20} 件`);
+        }
+        lines.push(`视口中心 = (${Math.round(cx)},${Math.round(cy)})；想让用户不用动镜头就看到，就把东西摆进这个矩形。`);
+      }
+      if (vp.selected?.length) lines.push(`选中：${vp.selected.map(id => describeEndpoint(id, board)).join('、')}`);
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    },
+  );
+}

package/server/engine/mcp/tools/relate-on-board.js

@@ -19,7 +19,7 @@
 import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import { patchBoard } from '../../../projects/board-store.js';
-import { BINDING_TYPES, BINDING_TYPE_IDS } from '../../../lib/binding-types.js';
+import { BINDING_TYPES, BINDING_TYPE_IDS, BINDING_MATERIALS } from '../../../lib/binding-types.js';
 
 /** 词汇表渲染成工具描述里的一段表，免得两处各写各的 */
 const VOCAB = BINDING_TYPE_IDS
@@ -63,8 +63,10 @@ where the files live.`,
       to: z.string().min(1).max(300).describe('Target canvas id — see forms above'),
       label: z.string().max(60).optional()
         .describe('Optional short words on the line. Omit to use the default for the type.'),
+      material: z.enum(BINDING_MATERIALS).optional()
+        .describe('How the line is drawn (orthogonal to type): ink = quiet archive line (default); pencil = hand-drawn; yarn = detective red string with pins, for hypotheses/evidence while reasoning. The whole canvas is a detective board — use yarn when the relation is still being argued, ink when it is settled.'),
     },
-    async ({ type, from, to, label }) => {
+    async ({ type, from, to, label, material }) => {
       if (!projectId) {
         return { content: [{ type: 'text', text: 'No project bound; cannot draw relationships.' }], isError: true };
       }
@@ -76,7 +78,7 @@ where the files live.`,
       }
       const id = nextId();
       // by:'agent' 不只是记录出处 —— 用户画的线 agent 不该擅自删，反过来也一样
-      const binding = { type, from, to, by: 'agent', ...(label ? { label } : {}) };
+      const binding = { type, from, to, by: 'agent', ...(label ? { label } : {}), ...(material && material !== 'ink' ? { material } : {}) };
       const board = await patchBoard(projectId, { bindings: { [id]: binding } });
 
       // 服务端会丢掉非法的线（未知 type / 自环）。**丢了要说**，否则 agent 以为