@xiaobuyu/nodesign 0.0.2 → 0.0.3

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

@@ -0,0 +1,337 @@
+/**
+ * mcp/tools/sketch-on-board.js —— sketch_on_board / finish_sketch（2026-08-23 黑板）
+ *
+ * 让 agent 把画布当黑板：一次调用落一整张示意图（节点 + 形状 + 线），而不是
+ * 像 create_on_board 那样一条条写。设计要点（跟用户商定的形状）：
+ *   - **没有几何容器**：一张图 = 一批带同一 #tag 的普通物件和线。read_board 按
+ *     连通分量 + tag 分段读，用户可以整组选/整组擦，入座算法照旧绕着走
+ *   - **两阶段**：落下来的默认是 staging（半透明，"正在画"），finish_sketch 或
+ *     回合结束自动落定；落定只清 staging 位，tag 留着当逻辑分组
+ *   - **结构不是像素**：agent 给模板 + 网格坐标（1 格 = 24px），服务端算像素与落位
+ *   - **形状是涂鸦**：rect/ellipse/arrow… 在服务端生成带手绘抖动的路径，落成
+ *     普通 scribble 对象，前端零改动；自由路径（path）也收，同一白名单
+ *   - 线的材质缺省 pencil（手绘）—— 草图上的线是人顺手拉的；要丝线/墨线自己说
+ *
+ * 护栏：每回合 3 张图；每张 ≤ 40 节点 / 30 形状 / 60 线。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { readBoard, patchBoard, commitStaging, removeByTag, 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, SKETCH_FIT, SKETCH_MAX, textBox, shapePath, layoutNodes, bboxOf, findSpot, fitFor } from '../../../lib/sketch-layout.js';
+import { getViewpoint } from '../../../projects/viewpoint-store.js';
+
+const MAX_NODES = 40;
+const MAX_SHAPES = 30;
+const MAX_EDGES = 60;
+
+let seq = 0;
+const stamp = () => `${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
+const COLORS = ['ink', 'red', 'pencil', 'brass'];
+
+const LOCAL_ID = z.string().regex(/^[A-Za-z0-9_-]{1,24}$/, 'local id: letters/digits/_/-');
+const GRID_PT = z.object({ x: z.number().min(-400).max(400), y: z.number().min(-400).max(400) });
+
+export function makeSketchOnBoardTool({ projectId, ctx }) {
+  const turnStamp = { turn: -1, count: 0 };   // 只记数（返回里不再报余额）
+  return tool(
+    'sketch_on_board',
+    `Draw a whole sketch on the canvas in ONE call — notes, shapes and lines, laid out
+together: a comparison table, a flow, a mind map, a detective board linking real
+artifacts. The canvas is the blackboard; use it when thinking out loud with the user
+would be clearer as a picture than as prose.
+
+How it works
+- You describe STRUCTURE; the server does pixels. Pick a layout template (column /
+  row / grid / mindmap) or place nodes yourself on a grid (1 cell = ${UNIT}px, layout
+  'free', at:{x,y}). Whole sketch lands beside \`near\` (a canvas id from read_board)
+  or under the desktop's current content.
+- nodes: plain handwriting or format:'md' (Markdown + KaTeX $…$ + \`\`\`mermaid fences).
+  Use md for lists/tables/formulas; mermaid only for dense formal diagrams
+  (sequence/state) — anything that should connect to real artifacts must be nodes+edges.
+- shapes: rect / ellipse / circle / line / arrow / underline (hand-drawn look is
+  applied for you) or path (raw SVG M/L/Q in local px) — all in grid units.
+- edges: between local node ids and/or real canvas ids. type = the relation
+  vocabulary (link/annotates/flow/contrast/derives-from/ref); material = ink (quiet
+  archive line) / pencil (hand-drawn, default here) / yarn (detective red string + pins
+  for hypotheses and evidence).
+- Everything carries one #tag (a group): read_board {tag} reads just it, the user can
+  select/erase it as a whole, finish_sketch commits or erases it.
+- Items land as STAGING (half-transparent = you are still drawing). Call finish_sketch
+  when done, or they commit automatically when the turn ends. Look at the result with
+  look_at_board before you call it done — agent scribbles only make sense with eyes.
+- Readability rule: the user reads the board at 80–100% zoom. Body text stays md/lg
+  (sm only for captions ≤40 chars); one sketch ≤ ${SKETCH_FIT.w}x${SKETCH_FIT.h} world px (one screen at 80%),
+  hard limit ${SKETCH_MAX.w}x${SKETCH_MAX.h} — split into two tagged sketches instead of one huge one.
+- To change an existing sketch use edit_sketch (move/retext/add/remove by id) — do NOT
+  erase and redraw the whole thing for a small change.
+Per sketch: ≤${MAX_NODES} nodes, ${MAX_SHAPES} shapes, ${MAX_EDGES} edges (split big ones).`,
+    {
+      title: z.string().max(60).optional().describe('Optional heading written at the top of the sketch'),
+      tag: z.string().regex(/^[\w一-鿿぀-ヿ-]{1,40}$/).optional()
+        .describe('Group tag (letters/digits/_/-/CJK, ≤40). Default: auto "sk-<stamp>"'),
+      near: z.string().max(300).optional().describe('Canvas id to place the sketch beside (right side; falls back to below)'),
+      layout: z.enum(['auto', 'free', 'column', 'row', 'grid', 'mindmap']).optional()
+        .describe('auto = free if any node has at, else column (≤4) / grid'),
+      cols: z.number().int().min(1).max(8).optional().describe('grid columns'),
+      staging: z.boolean().optional().describe('Default true. false = land committed (solid) immediately'),
+      nodes: z.array(z.object({
+        id: LOCAL_ID.describe('Local id to reference from edges/shapes'),
+        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: GRID_PT.optional().describe('Grid position (layout free); top-left of the node'),
+        w: z.number().min(3).max(22).optional().describe('Width in grid units (md nodes; default by content; ≤22 = 528px — paragraphs grow down, not wide)'),
+      })).max(MAX_NODES).optional(),
+      shapes: z.array(z.object({
+        id: LOCAL_ID.optional(),
+        kind: z.enum(['rect', 'ellipse', 'circle', 'line', 'arrow', 'underline', 'path']),
+        at: GRID_PT.optional().describe('Grid position (top-left for rect/ellipse; start point for line/arrow). Or use around:'),
+        around: LOCAL_ID.optional().describe('rect/ellipse/circle/underline: wrap this node (pad applied) instead of at/w/h'),
+        w: z.number().min(0).max(200).optional().describe('grid units'),
+        h: z.number().min(0).max(200).optional().describe('grid units'),
+        to: GRID_PT.optional().describe('line/arrow end point (grid)'),
+        toNode: LOCAL_ID.optional().describe('line/arrow: aim at this node\'s center instead of to'),
+        d: z.string().max(8000).optional().describe('path kind: SVG path (M/L/Q/Z only) in local px'),
+        color: z.enum(['ink', 'red', 'pencil', 'brass']).optional(),
+        width: z.number().min(1).max(12).optional(),
+      })).max(MAX_SHAPES).optional(),
+      edges: z.array(z.object({
+        from: z.string().min(1).max(300).describe('local node id or canvas id'),
+        to: z.string().min(1).max(300).describe('local node id or canvas id'),
+        type: z.enum(BINDING_TYPE_IDS).optional().describe('default link'),
+        material: z.enum(BINDING_MATERIALS).optional().describe('default pencil'),
+        label: z.string().max(60).optional(),
+      })).max(MAX_EDGES).optional(),
+    },
+    async (args) => {
+      if (!projectId) return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
+      const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
+      // 回合闸 08-23 用户拍板先不设（「别设置限制吧先」）：只记数不拦
+      const turn = ctx?.runId ?? -1;
+      if (turnStamp.turn !== turn) { turnStamp.turn = turn; turnStamp.count = 0; }
+
+      const nodesIn = args.nodes || [];
+      const shapesIn = args.shapes || [];
+      const edgesIn = args.edges || [];
+      if (!nodesIn.length && !shapesIn.length) return err('空图不落板：至少给一个节点或形状。');
+      const tag = args.tag || `sk-${stamp()}`;
+      const staging = args.staging !== false;
+
+      // ── 节点身位 ──
+      const localIds = new Set();
+      const nodes = [];
+      if (args.title) {
+        nodes.push({ key: '__title', text: `## ${args.title}`, format: 'md', size: 'md', font: 'kai', color: 'ink', at: null, w: null });
+      }
+      for (const n of nodesIn) {
+        if (localIds.has(n.id)) return err(`节点 id 重复：${n.id}`);
+        localIds.add(n.id);
+        // 可读性规范：正文不低于 md（0.8 倍下 12.8 屏幕像素是底线）；sm 只给 ≤40 字的题注
+        const size = (n.size === 'sm' && n.text.length > 40) ? 'md' : (n.size || 'md');
+        nodes.push({ key: n.id, text: n.text, format: n.format || 'plain', size, font: n.font || 'pen', color: n.color || 'ink', at: n.at || null, w: n.w || null });
+      }
+      for (const n of nodes) {
+        const box = textBox(n.text, n.size, { md: n.format === 'md', wUnits: n.w });
+        n.w = box.w; n.h = box.h;
+      }
+      // 标题永远在最上面：free 模式给它 (0,-2)，模板模式它就是第一个
+      const titleNode = nodes.find(n => n.key === '__title');
+      let tpl = args.layout || 'auto';
+      if (tpl === 'auto') tpl = nodes.some(n => n.at) ? 'free' : (nodes.length - (titleNode ? 1 : 0) <= 4 ? 'column' : 'grid');
+      const layoutInput = titleNode && tpl === 'mindmap' ? nodes.filter(n => n !== titleNode) : nodes;
+      const pos = layoutNodes(layoutInput, { template: tpl, cols: args.cols });
+      if (titleNode && !pos.has('__title')) {
+        const bb = bboxOf([...pos.entries()].map(([k, p]) => ({ x: p.x, y: p.y, ...nodes.find(n => n.key === k) })));
+        pos.set('__title', { x: bb.x, y: bb.y - titleNode.h - 12 });
+      } else if (titleNode && tpl === 'free' && !titleNode.at) {
+        const bb = bboxOf([...pos.entries()].filter(([k]) => k !== '__title').map(([k, p]) => ({ x: p.x, y: p.y, ...nodes.find(n => n.key === k) })));
+        pos.set('__title', { x: bb.x, y: bb.y - titleNode.h - 12 });
+      }
+      const rectOfNode = (key) => { const n = nodes.find(x => x.key === key); const p = pos.get(key); return n && p ? { x: p.x, y: p.y, w: n.w, h: n.h } : null; };
+
+      // ── 形状（局部像素）──
+      const shapes = [];
+      for (let i = 0; i < shapesIn.length; i += 1) {
+        const s = shapesIn[i];
+        const sid = s.id || `s${i + 1}`;
+        if (localIds.has(sid) || shapes.some(x => x.key === sid)) return err(`形状 id「${sid}」跟节点/别的形状重名（形状缺省叫 s1,s2…，节点别用这类名）`);
+        const seed = `${tag}:${sid}`;
+        const color = COLORS.includes(s.color) ? s.color : (s.kind === 'arrow' || s.kind === 'line' ? 'ink2' : 'ink');
+        const width = s.width || 2;
+        let rect; let d;
+        if (s.kind === 'path') {
+          if (!s.d || !/^[\dMLQCZ ,.\-eE]+$/.test(s.d)) return err(`形状 ${sid}：path 只收 M/L/Q/Z 与数字`);
+          // 自由路径：算它的包围盒，平移到 (at 或 0,0)
+          const nums = s.d.match(/-?\d*\.?\d+(?:[eE][-+]?\d+)?/g)?.map(Number) || [];
+          const xs = nums.filter((_, k) => k % 2 === 0); const ys = nums.filter((_, k) => k % 2 === 1);
+          const w = Math.max(4, Math.max(...xs) - Math.min(0, Math.min(...xs))); const h = Math.max(4, Math.max(...ys) - Math.min(0, Math.min(...ys)));
+          rect = { x: (s.at?.x || 0) * UNIT, y: (s.at?.y || 0) * UNIT, w: w + 6, h: h + 6 };
+          d = s.d;
+        } else if (s.kind === 'line' || s.kind === 'arrow' || s.kind === 'underline') {
+          let a; let b;
+          if (s.kind === 'underline' && s.around) {
+            const r = rectOfNode(s.around); if (!r) return err(`形状 ${sid}：around 指向不存在的节点 ${s.around}`);
+            a = { x: r.x + 2, y: r.y + r.h - 2 }; b = { x: r.x + r.w - 2, y: r.y + r.h - 2 };
+          } else {
+            if (!s.at) return err(`形状 ${sid}：${s.kind} 要 at 起点`);
+            a = { x: s.at.x * UNIT, y: s.at.y * UNIT };
+            if (s.toNode) {
+              const r = rectOfNode(s.toNode); if (!r) return err(`形状 ${sid}：toNode 指向不存在的节点 ${s.toNode}`);
+              b = { x: r.x + r.w / 2, y: r.y + r.h / 2 };
+            } else if (s.to) b = { x: s.to.x * UNIT, y: s.to.y * UNIT };
+            else if (s.kind === 'underline') b = { x: a.x + (s.w || 4) * UNIT, y: a.y };
+            else return err(`形状 ${sid}：${s.kind} 要 to 或 toNode`);
+          }
+          const sp = shapePath(s.kind, { to: { x: b.x - a.x, y: b.y - a.y } }, seed);
+          rect = { x: Math.min(a.x, b.x) - 6, y: Math.min(a.y, b.y) - 6, w: sp.w, h: sp.h };
+          d = sp.d;
+        } else {
+          let box;
+          if (s.around) {
+            const r = rectOfNode(s.around); if (!r) return err(`形状 ${sid}：around 指向不存在的节点 ${s.around}`);
+            const pad = s.kind === 'rect' ? 8 : 14;
+            box = { x: r.x - pad, y: r.y - pad, w: r.w + pad * 2, h: r.h + pad * 2 };
+            if (s.kind === 'circle') { const dmax = Math.max(box.w, box.h); box = { x: box.x + (box.w - dmax) / 2, y: box.y + (box.h - dmax) / 2, w: dmax, h: dmax }; }
+          } else {
+            if (!s.at || !s.w) return err(`形状 ${sid}：${s.kind} 要 at + w（+h）或 around`);
+            box = { x: s.at.x * UNIT, y: s.at.y * UNIT, w: s.w * UNIT, h: (s.h || s.w) * UNIT };
+          }
+          const sp = shapePath(s.kind, { w: box.w, h: box.h }, seed);
+          rect = { x: box.x - 6, y: box.y - 6, w: sp.w, h: sp.h };
+          d = sp.d;
+        }
+        shapes.push({ key: sid, rect, d, color: COLORS.includes(color) ? color : 'ink', width });
+      }
+
+      // ── 先分配 id、解析线 ──
+      // 线要先于落位算：一条连到真实产物卡的线会改变**主角判断**（手画线 +0.5 焦点分），
+      // 那张卡可能因此放大 1.5 倍 —— 落位必须按"线画上去之后"的尺寸避让
+      // （08-23 首跑真踩：草图连了一条丝线到纸本站，纸本当场成主角，身体盖住半张图）。
+      const board = await readBoard(projectId);
+      const known = new Set(Object.keys(board.zones || {}));
+      const idOf = new Map();     // local → canvas id
+      for (const n of nodes) idOf.set(n.key, `text:a${stamp()}`);
+      for (const sh of shapes) idOf.set(sh.key, `scribble:a${stamp()}`);
+      const resolveEnd = (raw) => {
+        if (idOf.has(raw)) return idOf.get(raw);
+        const cid = normalizeCanvasId(raw);
+        if (cid && board.objects?.[cid]) return cid;
+        if (cid && board.zones?.[cid] !== undefined) return cid;
+        return null;
+      };
+      const bindings = {};
+      const badEdges = [];
+      for (const e of edgesIn) {
+        const from = resolveEnd(e.from); const to = resolveEnd(e.to);
+        if (!from || !to || from === to) { badEdges.push(`${e.from}→${e.to}`); continue; }
+        bindings[`b:a${stamp()}`] = {
+          type: e.type || 'link', from, to, by: 'agent', material: e.material || 'pencil', tag,
+          ...(staging ? { staging: true } : {}), ...(e.label ? { label: e.label } : {}),
+        };
+      }
+      // 落位用"线画上之后"的板来估尺寸（主角可能换人）
+      const after = { ...board, bindings: { ...(board.bindings || {}), ...bindings } };
+
+      // ── 宏观落位 ──
+      const local = bboxOf([
+        ...nodes.map(n => ({ ...pos.get(n.key), w: n.w, h: n.h })),
+        ...shapes.map(sh => sh.rect),
+      ]);
+      let zone = '';
+      let anchor = null;
+      if (args.near) {
+        const nid = normalizeCanvasId(args.near);
+        const e = nid ? board.objects?.[nid] : null;
+        if (!e || !Number.isFinite(e.x)) return err(`锚点 ${args.near} 还没有座位（read_board 里看不到就锚不上）。`);
+        zone = layerOf(nid, e, known);
+        anchor = { x: e.x, y: e.y, ...estimateSizeOn(after, nid, e) };
+      }
+      const obstacles = [];
+      let contentBottom = 0;
+      for (const [id, e] of Object.entries(board.objects || {})) {
+        if (!Number.isFinite(e?.x) || layerOf(id, e, known) !== zone) continue;
+        const r = { x: e.x, y: e.y, ...estimateSizeOn(after, id, e) };
+        obstacles.push(r); contentBottom = Math.max(contentBottom, r.y + r.h);
+      }
+      if (!zone) for (const zz of Object.values(board.zones || {})) if (Number.isFinite(zz?.y)) contentBottom = Math.max(contentBottom, zz.y + 240);
+      // 尺寸规范：硬上限直接拒（一张图说一件事），推荐上限以上给提醒
+      if (local.w > SKETCH_MAX.w || local.h > SKETCH_MAX.h) {
+        return err(`这张图太大了（${Math.round(local.w)}x${Math.round(local.h)} 世界像素，上限 ${SKETCH_MAX.w}x${SKETCH_MAX.h}）：用户在 80%~100% 缩放下看不全。拆成两张（各自一个 tag，之间用线连），或减节点/缩 w。`);
+      }
+      // 用户视口（同一层才算；黑板是主窗口时画在他眼前）+ 按他的屏幕算"一屏"
+      const vp = getViewpoint(projectId);
+      const vpRect = (vp && (vp.layer || '') === zone && vp.camera) ? vp.camera : null;
+      const fit = fitFor(vp);
+      const spot = findSpot({ w: local.w + 24, h: local.h + 24, near: anchor, obstacles, contentBottom, viewport: vpRect });
+      const ox = spot.x - local.x + 12; const oy = spot.y - local.y + 12;
+
+      // ── 落盘 ──
+      const objects = {};
+      const common = { z: 1, zone, by: 'agent', tag, ...(staging ? { staging: true } : {}) };
+      for (const n of nodes) {
+        const p = pos.get(n.key);
+        objects[idOf.get(n.key)] = {
+          x: Math.round(p.x + ox), y: Math.round(p.y + oy), w: n.w, h: n.h, kind: 'text',
+          data: { t: n.text, ...(n.format === 'md' ? { format: 'md' } : {}), font: TEXT_FONTS.includes(n.font) ? n.font : 'pen', size: n.size, color: n.color },
+          ...common,
+        };
+      }
+      for (const sh of shapes) {
+        objects[idOf.get(sh.key)] = { x: Math.round(sh.rect.x + ox), y: Math.round(sh.rect.y + oy), w: Math.round(sh.rect.w), h: Math.round(sh.rect.h), kind: 'scribble', data: { d: sh.d, color: sh.color, width: sh.width }, ...common };
+      }
+      const saved = await patchBoard(projectId, { objects, bindings });
+      const landed = Object.keys(objects).filter(id => saved.objects?.[id]).length;
+      if (!landed) return err('草图被 board 拒了（内容或字段不合法）。');
+      turnStamp.count += 1;
+      const world = { x: Math.round(local.x + ox), y: Math.round(local.y + oy), w: Math.round(local.w), h: Math.round(local.h) };
+      try {
+        ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `画了一张草图 #${tag}` });
+        // 镜头提示（前端只在黑板模式跟随；不是劫持，是"黑板是主窗口"的约定）
+        ctx?.emit?.({ type: 'board.focus', sessionId: null, tag, rect: world, layer: zone });
+      } catch { /* fail-soft */ }
+      const lines = [
+        `Sketch #${tag} landed${staging ? ' as STAGING (半透明)' : ''}: ${Object.keys(objects).length - shapes.length} nodes, ${shapes.length} shapes, ${Object.keys(bindings).length} lines; layout ${tpl}; at world (${world.x},${world.y}) ${world.w}x${world.h}${anchor ? ` (${spot.side} of ${args.near})` : ' (below current content)'}.`,
+        `ids: ${[...idOf].map(([k, v]) => `${k}=${v}`).join(', ')}`,
+      ];
+      if (badEdges.length) lines.push(`Skipped ${badEdges.length} edge(s) with unknown endpoints: ${badEdges.slice(0, 6).join(', ')}`);
+      if (world.w > fit.w || world.h > fit.h) lines.push(`⚠ Bigger than one screen at 80% zoom${fit.screen ? ` (user's screen ${fit.screen.w}x${fit.screen.h}px → ${fit.w}x${fit.h} world px fits)` : ` (${fit.w}x${fit.h} fits)`} — the user will have to pan. Split into two tagged sketches (side by side or stacked) next time.`);
+      if (vp?.zoom && vp.zoom < 0.8) lines.push(`User's zoom is ${vp.zoom} (<0.8): text this size is small on their screen. Keep nodes md/lg and say in one line that there is a sketch on the board.`);
+      lines.push(spot.side === 'viewport' ? 'Placed inside the user\'s current viewport.' : `Placed ${spot.side === 'bottom' ? 'below current content' : spot.side + ' of the anchor'}${vpRect ? ' (no room in the user\'s viewport)' : ''}.`);
+      lines.push(staging
+        ? 'Next: look_at_board {tag} to check it, then finish_sketch {tag} (or it commits at turn end). Mention the sketch to the user in one line.'
+        : 'Next: look_at_board {tag} to check it.');
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    },
+  );
+}
+
+export function makeFinishSketchTool({ projectId, ctx }) {
+  return tool(
+    'finish_sketch',
+    `Commit a staging sketch (make it solid) — or erase it. Pass the #tag from
+sketch_on_board; omit tag to commit everything still staging. erase:true deletes the
+whole group (its notes/shapes/lines; real artifact cards only lose the tag).`,
+    {
+      tag: z.string().max(40).optional(),
+      erase: z.boolean().optional(),
+    },
+    async ({ tag, erase }) => {
+      if (!projectId) return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
+      if (erase) {
+        if (!tag) return { content: [{ type: 'text', text: 'erase needs a tag.' }], isError: true };
+        const { removed } = await removeByTag(projectId, tag);
+        try { ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `擦掉了草图 #${tag}` }); } catch { /* */ }
+        return { content: [{ type: 'text', text: `Erased #${tag}: ${removed} item(s)/line(s) removed.` }] };
+      }
+      const { committed } = await commitStaging(projectId, { tag: tag || null });
+      if (committed) { try { ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `草图落定${tag ? ` #${tag}` : ''}` }); } catch { /* */ } }
+      return { content: [{ type: 'text', text: committed ? `Committed ${committed} item(s)${tag ? ` of #${tag}` : ''}.` : 'Nothing was staging.' }] };
+    },
+  );
+}

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

@@ -0,0 +1,130 @@
+/**
+ * mcp/tools/write-on-board.js —— write_on_board（2026-08-23 黑板三期）
+ *
+ * agent 在画布上**说话**的主通道：一段 md 板书，贴着它说的那件东西（`near`），或者
+ * 接在用户/自己的某条板书下面（`reply_to` = 线程）。本体是文件
+ * （notes/板书/<stamp>-<slug>.md，见 lib/chalk.js），board.json 只存位置和线。
+ *
+ * 落位纪律（gutter）：
+ *   - reply_to：落在被回应那条的**正下方**（同列、间距 12），自动连 flow 线（读序）
+ *   - near：落在锚点右侧、顶对齐，撞了往下让；自动连 annotates 线（这段话关于它）
+ *   - 都没有：用户视口里的空地 > 桌面内容底下
+ * 跟 create_on_board 的分工：那是"记号"（手写一句、画布原生、给人看），这是"话"
+ * （md、文件本体、agent 要能读回来、有线程）。黑板模式下回复的主体走这里。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { readBoard, patchBoard } from '../../../projects/board-store.js';
+import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
+import { layerOf, normalizeCanvasId } from '../../../lib/canvas-id.js';
+import { textBox, findSpot, SKETCH_FIT } from '../../../lib/sketch-layout.js';
+import { getViewpoint } from '../../../projects/viewpoint-store.js';
+import { renderChalk, chalkFileName, writeChalkFile, CHALK_DIR } from '../../../lib/chalk.js';
+
+let seq = 0;
+const stamp = () => `${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
+
+export function makeWriteOnBoardTool({ projectId, sharedRoot, sessionId, ctx }) {
+  const turnStamp = { turn: -1, count: 0 };
+  return tool(
+    'write_on_board',
+    `Say it ON THE BOARD: write a short Markdown note on the canvas, beside the thing it is
+about (near) or right under a note you are replying to (reply_to). This is your main way
+to talk to the user when they work on the canvas — the sidebar is the log, the board is
+the conversation. The note is a real file (${CHALK_DIR}/…md) you can Read/Grep/Edit later.
+
+- near: canvas id the note is about (an artifact card, an image, another note) → lands to
+  its right, top-aligned, with an annotates line. Use it right after you finish something:
+  "what this is / why this way / what to look at".
+- reply_to: path of a board note (yours or the user's) → lands right under it with a
+  flow line (a thread). When the user annotates one of your notes, answer with reply_to.
+- neither → lands in the user's viewport (or below current content).
+- text: Markdown (+KaTeX, lists, tables; ≤1500 chars, keep it one thought — long
+  analysis belongs in a .md the user opens). size 'md' default, 'lg' for headlines.
+Keep the chat reply short — a line pointing at the board is enough.`,
+    {
+      text: z.string().min(1).max(1500),
+      near: z.string().max(300).optional(),
+      reply_to: z.string().max(300).optional().describe(`path like ${CHALK_DIR}/20260823-070809-xxx.md`),
+      tag: z.string().regex(/^[\w一-鿿぀-ヿ-]{1,40}$/).optional(),
+      size: z.enum(['md', 'lg']).optional(),
+      width: z.number().min(8).max(30).optional().describe('grid units (24px); default by content, max 30'),
+    },
+    async ({ text, near, reply_to: replyTo, tag, size, width }) => {
+      const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
+      if (!projectId || !sharedRoot) return err('No project bound.');
+      // 回合闸 08-23 用户拍板先不设：只记数不拦
+      const turn = ctx?.runId ?? -1;
+      if (turnStamp.turn !== turn) { turnStamp.turn = turn; turnStamp.count = 0; }
+      const body = String(text).trim();
+      if (!body) return err('空话不上板。');
+
+      const board = await readBoard(projectId);
+      const known = new Set(Object.keys(board.zones || {}));
+      // 默认宽度：散文按 14 格（336px）排，短句按内容；太窄会把一句话折成三行
+      const em = (l) => [...l].reduce((n, c) => n + (/[\u3000-\u9fff\uff00-\uffef]/.test(c) ? 1 : 0.62), 0);
+      const longest = Math.max(...body.split('\n').map(em));
+      const wUnits = width || (longest <= 12 ? null : Math.max(12, Math.min(18, Math.ceil(longest * 16 / 24) + 1)));
+      const box = textBox(body, size || 'md', { md: true, wUnits });
+      let zone = '';
+      let pos = null;
+      let anchorId = null; let parentId = null;
+      const obstaclesOf = (z) => Object.entries(board.objects || {})
+        .filter(([id, e]) => Number.isFinite(e?.x) && layerOf(id, e, known) === z)
+        .map(([id, e]) => ({ id, x: e.x, y: e.y, ...estimateSizeOn(board, id, e) }));
+      const avoid = (p, obstacles, w, h) => {
+        for (let g = 0; g < 40; g += 1) {
+          const b = obstacles.find(o => !(p.x + w <= o.x || o.x + o.w <= p.x || p.y + h <= o.y || o.y + o.h <= p.y));
+          if (!b) break;
+          p.y = b.y + b.h + 12;
+        }
+        return p;
+      };
+      if (replyTo) {
+        const pid = normalizeCanvasId(replyTo);
+        const e = pid ? board.objects?.[pid] : null;
+        if (!e || !Number.isFinite(e.x)) return err(`reply_to ${replyTo} 不在板上（read_board 里看不到就接不上）。`);
+        parentId = pid; zone = layerOf(pid, e, known);
+        const ps = estimateSizeOn(board, pid, e);
+        pos = avoid({ x: e.x, y: e.y + ps.h + 12 }, obstaclesOf(zone), box.w, box.h);
+      } else if (near) {
+        const nid = normalizeCanvasId(near);
+        const e = nid ? board.objects?.[nid] : null;
+        if (!e || !Number.isFinite(e.x)) return err(`锚点 ${near} 还没有座位（read_board 里看不到就锚不上）。`);
+        anchorId = nid; zone = layerOf(nid, e, known);
+        const as = estimateSizeOn(board, nid, e);
+        pos = avoid({ x: e.x + as.w + 24, y: e.y }, obstaclesOf(zone), box.w, box.h);
+      } else {
+        const obstacles = obstaclesOf('');
+        let bottom = 0; for (const o of obstacles) bottom = Math.max(bottom, o.y + o.h);
+        for (const zz of Object.values(board.zones || {})) if (Number.isFinite(zz?.y)) bottom = Math.max(bottom, zz.y + 240);
+        const vp = getViewpoint(projectId);
+        const vpRect = (vp && !(vp.layer) && vp.camera) ? vp.camera : null;
+        const spot = findSpot({ w: box.w + 24, h: box.h + 24, obstacles, contentBottom: bottom, viewport: vpRect });
+        pos = { x: spot.x + 12, y: spot.y + 12 };
+      }
+
+      const fileName = chalkFileName(body);
+      const content = renderChalk({ body, by: 'agent', anchor: anchorId, replyTo: parentId, tag: tag || null, sessionId: sessionId || null });
+      const rel = await writeChalkFile(sharedRoot, fileName, content);
+
+      const objects = { [rel]: { x: Math.round(pos.x), y: Math.round(pos.y), z: 1, w: box.w, h: box.h, zone, by: 'agent', ...(tag ? { tag } : {}) } };
+      const bindings = {};
+      if (anchorId) bindings[`b:a${stamp()}`] = { type: 'annotates', from: rel, to: anchorId, by: 'agent', ...(tag ? { tag } : {}) };
+      if (parentId) bindings[`b:a${stamp()}`] = { type: 'flow', from: parentId, to: rel, by: 'agent', material: 'pencil', ...(tag ? { tag } : {}) };
+      await patchBoard(projectId, { objects, bindings });
+      turnStamp.count += 1;
+      const rect = { x: Math.round(pos.x), y: Math.round(pos.y), w: box.w, h: box.h };
+      try {
+        ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: parentId ? '回了一条板书' : '写了一条板书' });
+        ctx?.emit?.({ type: 'board.focus', sessionId: null, tag: tag || null, rect, layer: zone, soft: true, chalk: rel });
+      } catch { /* */ }
+      const big = box.h > SKETCH_FIT.h * 0.6;
+      return { content: [{ type: 'text', text:
+        `Wrote board note ${rel} at (${rect.x},${rect.y}) ${rect.w}x${rect.h}`
+        + (anchorId ? ` beside ${anchorId} (annotates line)` : parentId ? ` under ${parentId} (thread)` : ' in the user\'s view')
+        + `.${big ? ' ⚠ It is tall — next time split or shorten.' : ''} Mention it in one line in chat; the user can annotate it to reply.` }] };
+    },
+  );
+}

package/server/engine/plugins/nodesign/skills/deskskill-engine-mini/SKILL.md

@@ -190,3 +190,10 @@ IP、角色、真人、某个具体产品型号、小众品牌 —— 那种情
 > 工具用法、路径、标记规约、比例硬规则在 prelude；生图 cookbook / tweaks 语法 /
 > vision-checker 派发模板由 PreToolUse hook 首次调用时注入。
 > layout 骨架参考按需 Read `<plugin>/patterns/<role>.md`。
+
+## 板书（交稿纪律）
+做完这一轮的东西，在它旁边写一条板书（`write_on_board near=那张卡`）：这版是什么 / 为什么这么做 /
+看哪里。改了几处就写几条要点，一条说一件事。同一件东西出了新版本，画一条「改自」线
+（`relate_on_board` derives-from）；有参考来源画「取材」。用户在你的板书上标注了，用
+`write_on_board reply_to=` 接在那条下面回。多步任务先 TodoWrite 列步骤 —— 步骤清单会自动上板、
+每步的产物自动连过去。

package/server/engine/plugins/nodesign/skills/docx-craft/SKILL.md

@@ -160,3 +160,10 @@ screenshot_canvas →  看版式
 `raw` 就是那个 .docx 本身 —— **它就是交付物**，不是"导出的副产品"，这跟 deck /
 站点反过来。`pdf` 走 LibreOffice，是快速预览用的；要发出去的正式 PDF 让用户在
 Word 里导（域和字体都对）。
+
+## 板书（交稿纪律）
+做完这一轮的东西，在它旁边写一条板书（`write_on_board near=那张卡`）：这版是什么 / 为什么这么做 /
+看哪里。改了几处就写几条要点，一条说一件事。同一件东西出了新版本，画一条「改自」线
+（`relate_on_board` derives-from）；有参考来源画「取材」。用户在你的板书上标注了，用
+`write_on_board reply_to=` 接在那条下面回。多步任务先 TodoWrite 列步骤 —— 步骤清单会自动上板、
+每步的产物自动连过去。

package/server/engine/plugins/nodesign/skills/rp-craft/SKILL.md

@@ -226,3 +226,10 @@ gemini-3.7-flash：$0.75/M 入、$3.75/M 出（促销价，思考 token 计入
 - 页面里永远不出现任何密钥（不需要：端点靠 cookie）。
 - 页面不做定时轮询、自动重发 —— 限频闸会拦，但根上就别写。
 - 演出内容平台不审（chatai 无工具无副作用），尺度是用户和角色设定之间的事。
+
+## 板书（交稿纪律）
+做完这一轮的东西，在它旁边写一条板书（`write_on_board near=那张卡`）：这版是什么 / 为什么这么做 /
+看哪里。改了几处就写几条要点，一条说一件事。同一件东西出了新版本，画一条「改自」线
+（`relate_on_board` derives-from）；有参考来源画「取材」。用户在你的板书上标注了，用
+`write_on_board reply_to=` 接在那条下面回。多步任务先 TodoWrite 列步骤 —— 步骤清单会自动上板、
+每步的产物自动连过去。

package/server/engine/plugins/nodesign/skills/site-craft/SKILL.md

@@ -321,3 +321,10 @@ Read `patterns/page-transitions.md` —— **动手写第一个转场之前先
 > 目录约定、产物根、`_drafts/`、导出交付在站点技术参考（首次写站点 html 时注入）。
 > 抠图叠层配方按需 Read 本 skill 目录下的 `patterns/cutout-collage.md`。
 > 构建道（React / vite / Tailwind / 组件库）配方 Read `patterns/build-lane.md`。
+
+## 板书（交稿纪律）
+做完这一轮的东西，在它旁边写一条板书（`write_on_board near=那张卡`）：这版是什么 / 为什么这么做 /
+看哪里。改了几处就写几条要点，一条说一件事。同一件东西出了新版本，画一条「改自」线
+（`relate_on_board` derives-from）；有参考来源画「取材」。用户在你的板书上标注了，用
+`write_on_board reply_to=` 接在那条下面回。多步任务先 TodoWrite 列步骤 —— 步骤清单会自动上板、
+每步的产物自动连过去。

package/server/engine/runs/board-tasklist.js

@@ -0,0 +1,130 @@
+/**
+ * server/engine/runs/board-tasklist.js —— 把 agent 的步骤清单镜像成板书（2026-08-23）
+ *
+ * 用户定的文化：板书是基础设施。agent 开工时用 TodoWrite 列的步骤不该只活在侧栏的计划
+ * 面板里 —— 它是这一轮的骨架，该写在画布上、每一步产出的东西连到对应步骤。
+ * 这件事**由 harness 做，不靠 agent 记得**：
+ *   - run.todo.updated → 一条板书 `notes/板书/<stamp>-步骤.md`（一轮一条、原地更新），
+ *     Markdown 任务列表：✓ 已做 / → 正在（加粗）/ 待做；落定不走 staging
+ *   - run.file_changed（有"正在"的步骤时）→ 这条板书到那件产物的 annotates 线，label「第 N 步」，
+ *     by:'auto'（不算进主角焦点分；同一轮同一件只连一次）
+ *   - run.done/cancelled/error → 忘掉这一轮的状态（板书留着，它是过程记录）
+ * 挂在 project bus 上（broker.getProjectBus 建 bus 时调一次），与 live-turn 折叠器同级。
+ * 失败一律吞掉只 warn：镜像挂了不能影响 run。
+ */
+import path from 'node:path';
+import { readBoard, patchBoard } from '../../projects/board-store.js';
+import { getSharedDir } from '../../projects/workspace.js';
+import { estimateSizeOn } from '../../lib/board-kind-sizes.js';
+import { layerOf, normalizeCanvasId } from '../../lib/canvas-id.js';
+import { textBox, findSpot } from '../../lib/sketch-layout.js';
+import { getViewpoint } from '../../projects/viewpoint-store.js';
+import { renderChalk, writeChalkFile, CHALK_DIR } from '../../lib/chalk.js';
+
+const byRun = new Map();   // runId → { projectId, rel, fileName, items, linked:Set, session }
+const MAX_LINKS_PER_RUN = 24;
+
+function renderList(items) {
+  const lines = ['### 这一轮的步骤', ''];
+  items.forEach((it, i) => {
+    const text = String(it.content || it.activeForm || '').trim() || `步骤 ${i + 1}`;
+    if (it.status === 'completed') lines.push(`- [x] ${text}`);
+    else if (it.status === 'in_progress') lines.push(`- [ ] **→ ${it.activeForm || text}**`);
+    else lines.push(`- [ ] ${text}`);
+  });
+  return lines.join('\n');
+}
+
+/** 工作区相对路径 → 画布 id（产物卡的地址）：精确 > deck: > 站点/word 根 > 原样 */
+export function canvasIdForRel(board, rel) {
+  const r = String(rel || '').replace(/\\/g, '/').replace(/^\.\//, '');
+  if (!r) return null;
+  const objs = board.objects || {};
+  if (objs[r]) return r;
+  const norm = normalizeCanvasId(r);
+  if (norm && objs[norm]) return norm;
+  for (const id of Object.keys(objs)) {
+    const m = /^(site|docx):(.+)$/.exec(id);
+    if (!m) continue;
+    const root = m[2];
+    if (r === root || r.startsWith(`${root}/`)) return id;
+  }
+  // 还没上墙：按形态猜（seated 之后线自然画出来）
+  return norm || r;
+}
+
+async function upsert(st, items) {
+  st.items = items;
+  const body = renderList(items);
+  const content = renderChalk({ body, by: 'agent', tag: st.tag, sessionId: st.session || null });
+  const sharedRoot = getSharedDir(st.projectId);
+  if (!st.fileName) st.fileName = `${new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, '').replace('T', '-')}-步骤.md`;
+  st.rel = await writeChalkFile(sharedRoot, st.fileName, content, { overwrite: !!st.rel });
+  st.fileName = st.rel.split('/').pop();   // 首写可能被加了防撞序号，之后原地覆盖同一个文件
+  const board = await readBoard(st.projectId);
+  const box = textBox(body, 'md', { md: true, wUnits: 14 });
+  const prev = board.objects?.[st.rel];
+  if (prev && Number.isFinite(prev.x)) {
+    // 已有座位：只改高（行数变了）不碰宽 —— 宽由前端量过真值，回写会跟它来回抖（fable P2）
+    await patchBoard(st.projectId, { objects: { [st.rel]: { ...prev, h: box.h } } });
+    return;
+  }
+  // 首次落位：用户视口的空地 > 内容底下（跟 write_on_board 同口径）
+  const known = new Set(Object.keys(board.zones || {}));
+  const obstacles = Object.entries(board.objects || {})
+    .filter(([id, e]) => Number.isFinite(e?.x) && layerOf(id, e, known) === '')
+    .map(([id, e]) => ({ x: e.x, y: e.y, ...estimateSizeOn(board, id, e) }));
+  let bottom = 0; for (const o of obstacles) bottom = Math.max(bottom, o.y + o.h);
+  for (const zz of Object.values(board.zones || {})) if (Number.isFinite(zz?.y)) bottom = Math.max(bottom, zz.y + 240);
+  const vp = getViewpoint(st.projectId);
+  const vpRect = (vp && !vp.layer && vp.camera) ? vp.camera : null;
+  const spot = findSpot({ w: box.w + 24, h: box.h + 24, obstacles, contentBottom: bottom, viewport: vpRect });
+  await patchBoard(st.projectId, { objects: { [st.rel]: { x: spot.x + 12, y: spot.y + 12, z: 1, w: box.w, h: box.h, by: 'agent', tag: st.tag } } });
+}
+
+export function attachBoardTasklist(bus, projectId) {
+  const handle = async (evt) => {
+    if (!evt?.runId) return;
+    if (evt.type === 'run.todo.updated') {
+      const items = Array.isArray(evt.todos) ? evt.todos.filter(t => t && typeof t === 'object') : [];
+      if (!items.length) return;
+      let st = byRun.get(evt.runId);
+      if (!st) {
+        st = { projectId, rel: null, fileName: null, items: [], linked: new Set(), session: evt.sessionId || null, tag: `步骤-${String(evt.runId).slice(-6)}` };
+        byRun.set(evt.runId, st);
+      }
+      await upsert(st, items);
+      bus.publish({ type: 'board.updated', sessionId: null, runId: evt.runId, summary: '步骤清单上板' });
+      return;
+    }
+    if (evt.type === 'run.file_changed') {
+      const st = byRun.get(evt.runId);
+      if (!st?.rel || !evt.filePath) return;
+      const idx = st.items.findIndex(t => t.status === 'in_progress');
+      if (idx < 0) return;
+      // 只连工作区内、非隐藏目录的真产物；每轮封顶（否则 /tmp、.nd、.claude 里的写入会灌一堆
+      // 指向虚空的 auto 线，MAX_BINDINGS 一到用户自己的线都不收 —— fable 08-23 P2）
+      const rel = String(evt.filePath).replace(/\\/g, '/');
+      if (rel.startsWith('/') || rel.split('/').some(seg => seg === '..' || seg.startsWith('.') || seg === 'node_modules')) return;
+      if (rel.startsWith(`${CHALK_DIR}/`) || rel.startsWith('notes/')) return;
+      if (st.linked.size >= MAX_LINKS_PER_RUN) return;
+      const board = await readBoard(st.projectId);
+      const target = canvasIdForRel(board, evt.filePath);
+      if (!target || target === st.rel || target.startsWith(`${CHALK_DIR}/`)) return;
+      if (st.linked.has(target)) return;
+      st.linked.add(target);
+      const id = `b:auto:step:${String(evt.runId).slice(-6)}:${st.linked.size}`;
+      await patchBoard(st.projectId, { bindings: { [id]: { type: 'annotates', from: st.rel, to: target, by: 'auto', label: `第 ${idx + 1} 步`, tag: st.tag } } });
+      bus.publish({ type: 'board.updated', sessionId: null, runId: evt.runId, summary: `第 ${idx + 1} 步 → ${path.basename(target)}` });
+      return;
+    }
+    if (evt.type === 'run.done' || evt.type === 'run.cancelled' || evt.type === 'run.error') {
+      byRun.delete(evt.runId);
+    }
+  };
+  bus.subscribe('*', (evt) => {
+    handle(evt).catch(err => console.warn('[board-tasklist]', err?.message || err));
+  });
+}
+
+export function _resetBoardTasklist() { byRun.clear(); }