@xiaobuyu/nodesign 0.0.2 → 0.0.4

package/server/engine/agent/prompts/nodesign-prelude.md

@@ -160,13 +160,64 @@ index.html 直接在工作区根上的「根站」仍被识别，但**新站一
   的以用户为准，别来回拉扯。
 - `create_on_board` 在画布上落一条**手写便签**（和用户写的同款）。用于值得留在
   版面上的话（这版为什么这么改、一组东西的题注），带 near+relation 就是一次完整
-  的"标注"。不是聊天出口，每回合上限 4 条。
+  的"标注"。不是聊天出口。
 - `organize_board` 归纳收纳：把散在桌面上的东西（生成图 / 旧稿 / 文件夹）批量搬进
   文件夹（目标夹没有就建）。**真 mv** —— 和用户拖拽同一套语义，画布身份和关系线
   自动跟着走，比裸 Bash mv 稳。站点收素材搬进它的 `assets/` 子目录（站点根是产物
   不是收纳夹，搬不进去）。一轮产出多件同族素材时，收尾顺手归个夹。
 - 用户「＋加入上下文」的物件会作为附件出现在你下一条消息里，那是他指着东西说话。
 
+### 画布也是黑板（板书 / 头脑风暴 / 推理板）—— 能写板书就写，能画线就画
+整块画布就是一张侦探板：产物卡是证物，线是关系，空白处随时能写、能画。侧栏照常回复（那是
+用户的输入方式，别改），但**表现形式上要积极**：凡是值得留在版面上、贴着东西看的东西，都
+往板上写、往板上画 —— 板上有而侧栏没有的，是"跟东西贴在一起的上下文"和"读得出关系的版面"。
+- `write_on_board`：**能写就写**。做完一件东西立刻在它旁边写一条（`near=那张卡`：这是什么 /
+  为什么这么做 / 看哪里）；给出结论、建议、决定、待办，写一条；比较了几件东西，在它们旁边
+  写判语；用户在板上**标注**了你的板书或手写字（消息里带原文摘录和路径），用 `reply_to=那条
+  路径` 接在下面回，不要只在侧栏答。板书是真文件（`notes/板书/…md`，你能 Read/Grep/Edit），
+  一条 ≤1500 字、一条说一件事；侧栏里提一句"板上写了什么"即可，别大段重复。
+- `relate_on_board` / 草图里的 edges：**能画线就画**。两件东西有关系（改自 / 对照 / 接着 /
+  取材 / 关联 / 板书关于谁），线一定画上 —— 线是用户读版面的主要线索。还在论证中的关系用
+  丝线（yarn）。
+- 用户在**想事情**（对比方案、理流程、摆人物关系、列利弊、排时间线、拆问题）时，画成图
+  （sketch_on_board）—— 画出来比一段话清楚，也留得住。纯闲聊、一句话能答完的、长段技术排错、
+  要用户复制的东西，留在侧栏就好。
+- **步骤清单自动上板**：你用 TodoWrite 列的步骤会被镜像成画布上一条「这一轮的步骤」板书
+  （✓ 已做 / → 正在 / 待做，原地更新），每一步期间你写出的文件会自动连到这条清单上（「第 N 步」）。
+  所以多步任务**先 TodoWrite 列步骤**（三步以上就列），步骤写成人看得懂的话；不用再手写一份清单。
+- 用户开了「黑板模式」时，上面这些从"积极去做"变成"默认这么做"（每条消息前会注入提示）。
+- `sketch_on_board` **一次落一整张图**：节点（手写 或 `format:'md'` —— 要点/表格/
+  KaTeX 公式/```mermaid 围栏）、形状（rect/ellipse/circle/arrow/line/underline，手绘感
+  替你加好；或 path 自由路径）、线（语义×材质）。你只说结构：选模板（column/row/grid/
+  mindmap）或在网格上自己摆（1 格=24px，`layout:'free'` + `at`）。整张图落在 `near`
+  的旁边、用户视口里的空地、或桌面内容底下，坐标它算。它带一个 #tag，`read_board {tag}`
+  只读那一组，用户能整组选/整组擦。
+- `edit_sketch` **改已有的图**：按 id 挪（相对另一件东西的右/左/上/下，或网格位移）、改字、
+  加节点、加/改/删线、整组搬家。小改动一律用它，**不要擦掉重画**。位置永远说相对关系，
+  不给绝对坐标。
+- **两阶段**：落下去的是草稿（半透明）。检查完 `finish_sketch {tag}` 变实；忘了也在
+  回合结束自动落定；画坏了 `finish_sketch {tag, erase:true}` 整组擦掉重画。
+- **画完要看**：`look_at_board {tag}` 截一张真实画面（按需调用，不要每步都截）。
+  涂鸦和排布只有看过才算数 —— 画了不看等于没画。
+- **可读性与版式纪律**（板是给人读的，按人的阅读习惯排）：
+  - 用户在 80%~100% 缩放下看板。正文字号 md 起（sm 只给 ≤40 字题注）；一张图一屏装得下
+    （工具按他的屏幕算，超了会提醒），硬上限 2600×1700；大了拆两张、用一条线说关系。
+  - **先左后右、先上后下**。新东西排在已有内容的**右侧或下方**，不放左侧/上方（除非锚着
+    某件东西）。标题用 `title` 参数横跨顶端，别当普通节点摆进列里。
+  - 一张图最多两列；列宽 ≤18 格（432px）；每个节点一件事、正文 ≤4 行，写不下就拆节点。
+  - 相关的几张图之间留呼吸（40px+），用线说关系；板书贴着它说的东西（near），回应接在
+    被回应那条正下方（reply_to）。
+  - 不确定用户此刻看哪、屏幕多大：`read_user_view`。
+- 材质是与语义正交的第二个轴：`ink` 墨线 = 安静的归档线；`pencil` 手绘 = 顺手拉的一笔
+  （草图里的缺省）；`yarn` 丝线 = 侦探板上带图钉的红线，给**还在论证中**的假设/证据
+  关系。关系定了就用 ink 重画或落定时自然退场；`relate_on_board` 也收 `material`。
+- mermaid 与原生节点的分工：要跟真实产物连线的一律用节点+线；时序图、状态机这类
+  密而规整的图才装 mermaid 盒子。别把三个节点的关系图塞进 mermaid。
+- `read_user_view` 看用户此刻在看哪（视口/缩放/开着的窗/选中）。他说「这个/这里/这张」按
+  选中 > 开着的窗 > 视口里的东西 来解；新图默认落在他视口里的空地，让他不用动镜头。
+  每条用户消息前也会注入一行他的视点（只在变化时报）。
+- 黑板不是弹幕区：一张图说一件事（每张 ≤40 节点），一条板书说一件事。说完在回复里提一句「画布上画了 xxx」。
+
 ## 用户直接改画布时（DirectEdit）
 
 用户可以双击改字、选中元素写评论、拖移元素、**在预览上圈一块地方说事**。这些动作攒在
@@ -292,6 +343,7 @@ batch**，一页一个回合太慢；逛到不确定的地方（要不要进、
 `remove_background` · `web_search` · `expose_tweaks` · `export_handoff` ·
 `pin_to_board` · `relate_on_board` ·
 `read_board` · `arrange_on_board` · `create_on_board` · `organize_board` · `deliver_files` ·
+`write_on_board` · `sketch_on_board` · `edit_sketch` · `finish_sketch` · `look_at_board` · `read_user_view` ·
 `read_document` ·
 `crystallize_skill` ·
 `report_issue` · `roll_film` · `paint_still` · `lookup_tags` · `trace_motion` · `explain_style` · `profile_scroll`

package/server/engine/agent/session-loop.js

@@ -78,6 +78,7 @@ import { autoNameProjectFromSession } from '../../projects/auto-name.js';
 // getUserById/levelFor 是 main 的每用户内容尺度旋钮（78ceaac）；
 // main 的 listTasks 已随任务层退役，不再引入
 import { commitTaskWorkspace, commitWorkspace, PROJECTS_DATA_ROOT } from '../../projects/workspace.js';
+import { commitStaging } from '../../projects/board-store.js';
 import { taskManifest } from '../../lib/artifact-target.js';
 import { getUserById } from '../../auth/users-store.js';
 import { can, defaultModerationLevel } from '../../auth/tier.js';
@@ -727,6 +728,16 @@ export async function runSession({
     await commitWorkspace(projectId, sessionId, `turn ${status}: ${new Date().toISOString()}`, { author: 'agent' })
       .catch((err) => console.warn('[git] turn commit failed:', err.message));
 
+    // 黑板草稿兜底落定（2026-08-23）：agent 这一轮 sketch_on_board 留下的 staging
+    // 物件，没调 finish_sketch 也在回合结束时变实 —— 草稿态是"正在画"的信号，
+    // 回合都结束了还半透明就是幽灵。取消/出错同样落定：画了就是画了。
+    if (projectId) {
+      try {
+        const { committed } = await commitStaging(projectId);
+        if (committed > 0) sharedCtx.emit({ type: 'board.updated', sessionId: null, summary: `黑板草稿落定 ${committed} 件` });
+      } catch (err) { console.warn('[board] commitStaging failed:', err.message); }
+    }
+
     activeTurnRunId = null;
     turnStartedAt = 0;
     markSessionActivity(sessionId);  // turn 结束 = 活跃信号；下次 idle 计时重置

package/server/engine/mcp/index.js

@@ -65,6 +65,11 @@ import { makeRelateOnBoardTool } from './tools/relate-on-board.js';
 import { makeReadBoardTool } from './tools/read-board.js';
 import { makeArrangeOnBoardTool } from './tools/arrange-on-board.js';
 import { makeCreateOnBoardTool } from './tools/create-on-board.js';
+import { makeSketchOnBoardTool, makeFinishSketchTool } from './tools/sketch-on-board.js';
+import { makeEditSketchTool } from './tools/edit-sketch.js';
+import { makeWriteOnBoardTool } from './tools/write-on-board.js';
+import { makeLookAtBoardTool } from './tools/look-at-board.js';
+import { makeReadUserViewTool } from './tools/read-user-view.js';
 import { makeOrganizeBoardTool } from './tools/organize-board.js';
 import { makeReadDocumentTool } from './tools/read-document.js';
 import { makeReadTavernJsonTool } from './tools/read-tavern-json.js';
@@ -305,6 +310,13 @@ export function createNodesignMcpServer({ workspaceRoot, sharedRoot, projectId,
       makeArrangeOnBoardTool({ projectId, ctx }),
       makeCreateOnBoardTool({ projectId, ctx }),
       makeOrganizeBoardTool({ projectId, ctx }),
+      // 黑板（2026-08-23）：一次落一整张草图 / 落定或擦掉 / 看一眼 / 用户在看哪
+      makeSketchOnBoardTool({ projectId, ctx }),
+      makeFinishSketchTool({ projectId, ctx }),
+      makeEditSketchTool({ projectId, ctx }),
+      makeWriteOnBoardTool({ projectId, sharedRoot: workspaceRoot || sharedRoot, sessionId, ctx }),
+      makeLookAtBoardTool({ projectId, ctx }),
+      makeReadUserViewTool({ projectId }),
 
       // 注：Phase Image-2 的 request_image_approval 工具已废弃（2026-05-06）。
       // generate_image 的 CallToolResult 已返 image content block，前端自动渲染；

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

@@ -12,7 +12,7 @@
 import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import { readBoard, patchBoard } from '../../../projects/board-store.js';
-import { estimateSize } from '../../../lib/board-kind-sizes.js';
+import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
 import { normalizeCanvasId, layerOf } from '../../../lib/canvas-id.js';
 
 const GAP_X = 24;
@@ -94,8 +94,8 @@ drag things afterwards — their move wins, do not fight it.`,
         }
       }
 
-      const aSize = estimateSize(anchor, anchorEntry);
-      const sSize = estimateSize(subject, subjectEntry);
+      const aSize = estimateSizeOn(board, anchor, anchorEntry);
+      const sSize = estimateSizeOn(board, subject, subjectEntry);
       const want = action === 'beside'
         ? { x: Math.round(anchorEntry.x + aSize.w + GAP_X), y: Math.round(anchorEntry.y) }
         : { x: Math.round(anchorEntry.x), y: Math.round(anchorEntry.y + aSize.h + GAP_Y) };
@@ -103,7 +103,7 @@ drag things afterwards — their move wins, do not fight it.`,
       const obstacles = Object.entries(board.objects || {})
         .filter(([id, e]) => id !== subject && Number.isFinite(e?.x)
           && layerOf(id, e, known) === anchorLayer)
-        .map(([id, e]) => ({ ...estimateSize(id, e), x: e.x, y: e.y }));
+        .map(([id, e]) => ({ ...estimateSizeOn(board, id, e), x: e.x, y: e.y }));
       const pos = nudgeDown(want, sSize, obstacles);
 
       await patchBoard(projectId, {

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

@@ -12,16 +12,15 @@
  *   - 尺寸估算抄前端 handleCreateText 同款公式（约 26 全角字/行）
  *   - by:'agent' 出处，用户一眼分得出谁写的
  *
- * 护栏：每回合上限 4 条 —— 画布是版面不是弹幕区。
+ * 护栏：每回合上限 08-23 按用户意思撤了（只记数）；画布不是弹幕区这条写在 prelude 里。
  */
 
 import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import { readBoard, patchBoard, TEXT_FONTS } from '../../../projects/board-store.js';
-import { estimateSize } from '../../../lib/board-kind-sizes.js';
+import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
 import { normalizeCanvasId, layerOf } from '../../../lib/canvas-id.js';
 
-const MAX_PER_TURN = 4;
 const SIZE_PX = { sm: 13, md: 16, lg: 22, xl: 30 };
 
 let seq = 0;
@@ -44,7 +43,7 @@ export function makeCreateOnBoardTool({ projectId, ctx }) {
 
 Use it for remarks worth KEEPING on the board: why a version went this way, what
 to compare, a caption for a group. Not for conversation (that goes in your reply)
-and not for documents (write a .md instead). Hard cap: ${MAX_PER_TURN} notes per turn.
+and not for documents (write a .md instead).
 
 - near: anchor it beside a thing (and usually pass relation to draw the line —
   that is exactly the user's "annotation" gesture: a note + an annotates edge)
@@ -68,11 +67,9 @@ and not for documents (write a .md instead). Hard cap: ${MAX_PER_TURN} notes per
       }
       const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
 
-      const turn = ctx?.counters?.turns ?? -1;
+      // 回合闸 08-23 用户拍板先不设：只记数不拦
+      const turn = ctx?.runId ?? -1;
       if (turnStamp.turn !== turn) { turnStamp.turn = turn; turnStamp.count = 0; }
-      if (turnStamp.count >= MAX_PER_TURN) {
-        return err(`本回合便签额度用完（${MAX_PER_TURN} 条）—— 画布是版面不是弹幕区，要说的话说给用户听。`);
-      }
 
       const t = String(text).trim();
       if (!t) return err('空字不落板。');
@@ -89,12 +86,12 @@ and not for documents (write a .md instead). Hard cap: ${MAX_PER_TURN} notes per
           return err(`锚点 ${rawNear} 还没有座位（read_board 里看不到就锚不上）。`);
         }
         zone = layerOf(near, anchorEntry, known);
-        const aSize = estimateSize(near, anchorEntry);
+        const aSize = estimateSizeOn(board, near, anchorEntry);
         pos = { x: Math.round(anchorEntry.x + aSize.w + 24), y: Math.round(anchorEntry.y) };
         // 撞卡往下让（同 arrange 的避让）
         const obstacles = Object.entries(board.objects || {})
           .filter(([id, e]) => Number.isFinite(e?.x) && layerOf(id, e, known) === zone)
-          .map(([id, e]) => ({ ...estimateSize(id, e), x: e.x, y: e.y }));
+          .map(([id, e]) => ({ ...estimateSizeOn(board, id, e), x: e.x, y: e.y }));
         for (let g = 0; g < 40; g += 1) {
           const blocker = obstacles.find(o =>
             !(pos.x + box.w <= o.x || o.x + o.w <= pos.x || pos.y + box.h <= o.y || o.y + o.h <= pos.y));
@@ -106,7 +103,7 @@ and not for documents (write a .md instead). Hard cap: ${MAX_PER_TURN} notes per
         let bottom = 0;
         for (const [id, e] of Object.entries(board.objects || {})) {
           if (!Number.isFinite(e?.y) || layerOf(id, e, known) !== '') continue;
-          bottom = Math.max(bottom, e.y + estimateSize(id, e).h);
+          bottom = Math.max(bottom, e.y + estimateSizeOn(board, id, e).h);
         }
         for (const zz of Object.values(board.zones || {})) {
           if (Number.isFinite(zz?.y)) bottom = Math.max(bottom, zz.y + 150);
@@ -147,7 +144,7 @@ and not for documents (write a .md instead). Hard cap: ${MAX_PER_TURN} notes per
         content: [{
           type: 'text',
           text: `Note on board at (${pos.x},${pos.y})${relation ? ' with a line' : ''} (id: ${textId}).`
-            + ` ${MAX_PER_TURN - turnStamp.count} left this turn.`,
+            + '',
         }],
       };
     },

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 */ }
+      }
+      });
+    },
+  );
+}