@xiaobuyu/nodesign 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiaobuyu/nodesign",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "private": false,
   "type": "module",
   "description": "NoDesign — 面向独立创作者的 agent 创作工作台（本地分发版：npx nodesign）",

package/server/api/assets/helpers.js

@@ -7,12 +7,32 @@
  * 不会再随下一次拆分复发（谁也不用记得"这个函数该跟着谁走"）。
  */
 
+import { promises as fs } from 'node:fs';
+import { parseChalk } from '../../lib/chalk.js';
+
 /** 单层路径片段：不含分隔符、不含 `..`、不以点开头、长度可控 */
 export function safeSegment(s) {
   return typeof s === 'string' && !!s && s.length <= 200
     && !s.includes('/') && !s.includes('\\') && !s.includes('..') && !s.startsWith('.');
 }
 
+/**
+ * 便签/板书正文上卡（2026-08-23 从 assets.js 抽出）：frontmatter 带 nd: chalk 的是板书
+ * （agent/用户写在画布上的话，同一形态另一张脸），其余按便签头解析；正文 ≤4KB 截断。
+ * 读不到就静默（agent 正在写的文件可能半途消失）。
+ */
+export async function decorateNoteText(item, absPath) {
+  try {
+    const raw = await fs.readFile(absPath, 'utf8');
+    const parsed = parseChalk(raw);
+    const { body, sessionId } = parsed.chalk ? parsed : parseNoteFrontmatter(raw);
+    item.text = body.length > 4096 ? body.slice(0, 4096) + '…' : body;
+    if (sessionId) item.sessionId = sessionId;
+    if (parsed.chalk) item.chalk = parsed.chalk;
+  } catch { /* */ }
+  return item;
+}
+
 /** 便签 frontmatter：只认最简单的 `---\nsession: xxx\n---` 头，其余原样当正文 */
 export function parseNoteFrontmatter(raw) {
   const m = /^---\n([\s\S]{0,500}?)\n---\n?/.exec(raw);

package/server/api/assets/notes.js

@@ -13,6 +13,7 @@ import express from 'express';
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { safeSegment, parseNoteFrontmatter } from './helpers.js';
+import { patchBoard } from '../../projects/board-store.js';
 
 /**
  * @param {object} deps
@@ -123,6 +124,55 @@ export function mountNotesRoutes({ router, guardProject, getSharedDir, ensurePro
     } catch (err) { next(err); }
   });
   
+  /**
+   * 板书（notes/板书/<name>.md，2026-08-23）：用户侧改 / 删。名字是单段文件名，
+   * 目录固定 —— 跟便利贴同一套 safeNoteSegment 闸。
+   */
+  const resolveChalk = (pid, name) => {
+    const base = path.join(getSharedDir(pid), 'notes', '板书');
+    const file = path.resolve(base, name);
+    return file.startsWith(base + path.sep) ? file : null;
+  };
+  router.put('/:pid/chalk/:name', express.json(), async (req, res, next) => {
+    try {
+      if (!guardProject(req, res)) return;
+      const { name } = req.params;
+      if (!safeNoteSegment(name, { md: true })) return res.status(400).json({ error: 'invalid filename' });
+      const text = String(req.body?.text ?? '');
+      if (!text.trim()) return res.status(400).json({ error: 'text required' });
+      if (text.length > 20_000) return res.status(400).json({ error: 'too long (max 20k chars)' });
+      const file = resolveChalk(req.params.pid, name);
+      if (!file) return res.status(400).json({ error: 'invalid path' });
+      // frontmatter（nd:chalk/anchor/reply_to/tag）由服务端保住：正文只收正文。客户端拼头那条路
+      // 在 fetch 失败时会丢头、还会把 4KB 截断的展示副本写回（fable 08-23 P2）。
+      // 来的文本若自带头（老客户端拼过来的）剥掉，以磁盘上的头为准；磁盘上没有就保留来的头。
+      let head = '';
+      try { head = /^---\n[\s\S]{0,800}?\n---\n?/.exec(await fs.readFile(file, 'utf8'))?.[0] || ''; } catch { /* 新文件 */ }
+      const incomingHead = /^---\n[\s\S]{0,800}?\n---\n?/.exec(text)?.[0] || '';
+      const body = text.slice(incomingHead.length).replace(/^\n+/, '');
+      if (!body.trim()) return res.status(400).json({ error: 'text required' });
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      await fs.writeFile(file, `${head || incomingHead}${head || incomingHead ? '\n' : ''}${body.replace(/\n+$/, '')}\n`, 'utf8');
+      res.json({ ok: true, path: `notes/板书/${name}` });
+    } catch (err) { next(err); }
+  });
+  router.delete('/:pid/chalk/:name', async (req, res, next) => {
+    try {
+      if (!guardProject(req, res)) return;
+      const { name } = req.params;
+      if (!safeNoteSegment(name, { md: true })) return res.status(400).json({ error: 'invalid filename' });
+      const file = resolveChalk(req.params.pid, name);
+      if (!file) return res.status(400).json({ error: 'invalid path' });
+      try { await fs.unlink(file); } catch (err) {
+        if (err.code === 'ENOENT') return res.status(404).json({ error: 'not found' });
+        throw err;
+      }
+      // 座位和线一起清，别留指向已删文件的幽灵条目（read_board 会把它当"摆过的"列出来）
+      try { await patchBoard(req.params.pid, { objects: { [`notes/板书/${name}`]: null } }); } catch { /* 清不掉不挡删除 */ }
+      res.status(204).end();
+    } catch (err) { next(err); }
+  });
+
   /** DELETE /:pid/task-notes/:filename — 删便利贴 */
   router.delete('/:pid/task-notes/:filename', async (req, res, next) => {
     try {

package/server/api/assets.js

@@ -28,7 +28,8 @@ import { resolveArtifactFile, isServablePath } from '../lib/artifact-file-path.j
 import { getProjectCover } from '../lib/cover.js';
 import { makeDocxPageHandler, makeDocxPdfHandler } from './assets/docx-page.js';
 import { mountNotesRoutes } from './assets/notes.js';
-import { safeSegment, parseNoteFrontmatter } from './assets/helpers.js';
+import { safeSegment, decorateNoteText } from './assets/helpers.js';
+import { CHALK_DIR } from '../lib/chalk.js';
 import {
   sendImage, isThumbPath, findOriginalForThumbnail, imageCacheControl,
   THUMBNAIL_MAX_DIM, THUMBNAIL_QUALITY,
@@ -348,16 +349,8 @@ router.get('/:pid/artifacts', async (req, res, next) => {
             item.meta = JSON.parse(metaRaw);
           } catch { /* 无 sidecar（旧图）→ 无 meta */ }
         }
-        // 便签直接把正文带给前端渲卡片（≤4KB 截断，完整内容走 artifact-file）。
-        // frontmatter 里的 session 字段是分区归属（agent 写便签时按约定带上）。
-        if (kind === 'note' && ext === '.md') {
-          try {
-            const raw = await fs.readFile(path.join(dir, e.name), 'utf8');
-            const { body, sessionId } = parseNoteFrontmatter(raw);
-            item.text = body.length > 4096 ? body.slice(0, 4096) + '…' : body;
-            if (sessionId) item.sessionId = sessionId;
-          } catch { /* */ }
-        }
+        // 便签/板书把正文带给前端渲卡片（≤4KB 截断，完整内容走 artifact-file；见 helpers.decorateNoteText）
+        if (kind === 'note' && ext === '.md') await decorateNoteText(item, path.join(dir, e.name));
         artifacts.push(item);
       }
     };
@@ -497,6 +490,8 @@ router.get('/:pid/artifacts', async (req, res, next) => {
       // 24 条产物里 6 条重复，画布上就是一张卡叠着另一张同名卡。
       await scanDir(workspaceRoot, 'task-file', '', 0);
       await scanDir(path.join(workspaceRoot, 'notes'), 'note', 'notes');
+      // 板书住 notes/板书/（不进 notes/ 顶层：便利贴注入只列顶层，板书另有自己的注入）
+      await scanDir(path.join(workspaceRoot, CHALK_DIR), 'note', CHALK_DIR);
       for (const rel of folders) {
         await scanDir(path.join(workspaceRoot, rel), 'task-file', rel, 0);
       }

package/server/api/board.js

@@ -12,7 +12,10 @@
 import express from 'express';
 import { validateProjectId, getProject } from '../projects/store.js';
 import { guardProject } from './_guard.js';
-import { readBoard, replaceBoard, patchBoard } from '../projects/board-store.js';
+import { readBoard, replaceBoard, patchBoard, commitStaging, removeByTag } from '../projects/board-store.js';
+import { setViewpoint, getViewpoint } from '../projects/viewpoint-store.js';
+import { exportGraph, exportGraphZip } from '../lib/board-graph-export.js';
+import { getSharedDir } from '../projects/workspace.js';
 
 const router = express.Router();
 
@@ -54,4 +57,78 @@ router.put('/:pid/board', express.json({ limit: '600kb' }), async (req, res, nex
   }
 });
 
+/**
+ * 用户视点上报（2026-08-23 黑板）：前端节流 POST，服务端只留最近一份。
+ * 不广播、不落盘；失败也不该打扰用户（前端 fire-and-forget）。
+ */
+router.post('/:pid/viewpoint', express.json({ limit: '16kb' }), async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const v = setViewpoint(req.params.pid, req.body?.viewpoint, req.user?.id || null);
+    res.json({ ok: !!v });
+  } catch (err) { next(err); }
+});
+
+/** 读最近一份视点（排障用：看看服务端眼里"用户在看哪"；agent 走 read_user_view） */
+router.get('/:pid/viewpoint', async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    res.json({ viewpoint: getViewpoint(req.params.pid) });
+  } catch (err) { next(err); }
+});
+
+/** 草稿落定（用户也可以按组落定：黑板上 agent 的草稿半透明，点一下变实） */
+router.post('/:pid/board/commit', express.json({ limit: '16kb' }), async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const tag = typeof req.body?.tag === 'string' ? req.body.tag : null;
+    const { board, committed } = await commitStaging(req.params.pid, { tag });
+    res.json({ ok: true, committed, board });
+  } catch (err) { next(err); }
+});
+
+/** 黑板擦：按 #tag 整组删（只删画布原生物件与线；产物卡只摘标签） */
+router.post('/:pid/board/erase', express.json({ limit: '16kb' }), async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const tag = typeof req.body?.tag === 'string' ? req.body.tag : '';
+    if (!tag) return res.status(400).json({ error: 'tag required' });
+    const { board, removed } = await removeByTag(req.params.pid, tag);
+    res.json({ ok: true, removed, board });
+  } catch (err) { next(err); }
+});
+
+/**
+ * 连接图导出（2026-08-23 黑板）：?format=json|mermaid|svg&tag=&layer=
+ * 真相是 board.json，这里只派生。download=1 时带附件头。
+ */
+router.get('/:pid/board/graph', async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const format = String(req.query.format || 'json');
+    const tag = typeof req.query.tag === 'string' && req.query.tag ? req.query.tag.slice(0, 40) : null;
+    const layer = typeof req.query.layer === 'string' ? req.query.layer.slice(0, 300) : '';
+    const board = await readBoard(req.params.pid);
+    if (format === 'zip') {
+      const projectName = getProject(req.params.pid)?.name || '画布';
+      const { zip } = await exportGraphZip(board, { workspaceRoot: getSharedDir(req.params.pid), tag, layer, projectName });
+      const buf = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+      res.setHeader('Content-Type', 'application/zip');
+      res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(`board${tag ? `-${tag}` : ''}.zip`)}`);
+      return res.send(buf);
+    }
+    const { mime, body } = exportGraph(board, { format, tag, layer });
+    res.setHeader('Content-Type', mime);
+    if (req.query.download) {
+      const ext = format === 'mermaid' ? 'mmd' : format;
+      const name = `board${tag ? `-${tag}` : ''}.${ext}`;
+      res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(name)}`);
+    }
+    res.send(body);
+  } catch (err) {
+    if (err?.status === 400) return res.status(400).json({ error: err.message });
+    next(err);
+  }
+});
+
 export default router;

package/server/engine/agent/events.js

@@ -41,6 +41,7 @@
  *   run.rate_limit             { info }                                    rate limit 变化
  *   run.image_generated        { path, sizeBytes, prompt, assetRole, ... } generate_image 完成（Phase A）
  *   board.updated              { objectId, zoneId, summary }               pin_to_board 改画布布局（sessionId:null 广播，前端整份重拉 board.json）
+ *   board.focus                { rect, tag, layer }                        agent 落了一张草图（sessionId:null 广播；前端只在黑板模式跟镜头）
  *   project.active_session     { activeSessionId }                         项目级会话指针变更（故意不带 sessionId —— 见构造器注释）
  *
  * 外层把 EventBus 桥接到：

package/server/engine/agent/hooks/user-prompt-submit.js

@@ -26,6 +26,11 @@ import path from 'node:path';
 import { readUiConfigFile } from '../../../projects/ui-config.js';
 import { readAssetsSummary } from '../../../projects/assets-summary.js';
 import { relationsDigest } from '../../../lib/board-relations.js';
+import { getViewpoint, describeViewpoint } from '../../../projects/viewpoint-store.js';
+import { recentChalk, CHALK_DIR } from '../../../lib/chalk.js';
+import { readBoard } from '../../../projects/board-store.js';
+import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
+import { layerOf } from '../../../lib/canvas-id.js';
 import {
   getActiveArtifact, listWorkspaceArtifacts, taskManifest, kindDef,
   KIND_DECK, KIND_SITE, ENTRY_FILE,
@@ -107,6 +112,25 @@ async function collectSections({ workspaceRoot, sessionId, projectId }) {
   } catch { /* notes/ 不存在：noop */ }
 
   // 画布关系线：用户画的排前面
+  // 用户视点（2026-08-23 黑板）：一行，只在变化时进注入（renderTurnState 按 hash 判）。
+  // 视口矩形按 1/8 视口量化再进 hash，不然相机挪一像素就算"变了"。
+  try {
+    const vp = getViewpoint(projectId);
+    if (vp) {
+      const board = await readBoard(projectId);
+      const known = new Set(Object.keys(board.zones || {}));
+      const rects = Object.entries(board.objects || {})
+        .filter(([id, e]) => Number.isFinite(e?.x) && layerOf(id, e, known) === (vp.layer || ''))
+        .map(([id, e]) => ({ id, x: e.x, y: e.y, ...estimateSizeOn(board, id, e) }));
+      const q = vp.camera ? { ...vp, camera: {
+        x: Math.round(vp.camera.x / Math.max(1, vp.camera.w / 8)) * Math.round(vp.camera.w / 8),
+        y: Math.round(vp.camera.y / Math.max(1, vp.camera.h / 8)) * Math.round(vp.camera.h / 8),
+        w: vp.camera.w, h: vp.camera.h,
+      } } : vp;
+      const line = describeViewpoint(q, rects);
+      if (line) sections.push({ key: 'viewpoint', title: '用户视点', text: `用户此刻在画布上：${line}。他说「这个/这里/这张」多半指选中的 > 开着的窗 > 视口里的东西；要细节调 read_user_view。` });
+    }
+  } catch { /* 视点读不到就沉默 */ }
   try {
     const digest = await relationsDigest(projectId, { limit: 12 });
     if (digest) {
@@ -137,6 +161,25 @@ async function collectSections({ workspaceRoot, sessionId, projectId }) {
   } catch { /* 扫不动就不说 */ }
 
   // tweaks 开关：文件不存在 = 用户没碰过 = 沉默
+  // 最近板书（2026-08-23）：你/用户在画布上说过的最近几句 —— 对话在板上，得记得板上说了什么
+  try {
+    const recent = await recentChalk(workspaceRoot, { limit: 8 });
+    if (recent.length) {
+      const lines = recent.map(c => `  ${c.path}（${c.by === 'user' ? '用户' : '你'}${c.anchor ? `，关于 ${c.anchor}` : ''}${c.replyTo ? `，回应 ${c.replyTo.replace(`${CHALK_DIR}/`, '')}` : ''}）「${c.first}」`);
+      sections.push({ key: 'chalk', title: '最近板书', text: `画布上最近的板书（${CHALK_DIR}/，新在前；正文 Read 文件）：\n${lines.join('\n')}`, items: recent.map(c => c.path) });
+    }
+  } catch { /* 板书读不到就沉默 */ }
+  // 黑板模式（2026-08-23）：用户在画布上专注思考时开。这一节只在开着时注入，关着不提。
+  try {
+    const cfg = await readUiConfigFile(workspaceRoot);
+    if (cfg?.blackboard_mode === true) {
+      sections.push({ key: 'blackboard', title: '黑板模式', text:
+        '【黑板模式：开】用户此刻在画布上专注思考。这一轮默认这么做：想事情就画成图（sketch_on_board，'
+        + '小改动用 edit_sketch 原地改别重画）；做完一件东西在它旁边写一条板书（write_on_board near=）；'
+        + '用户标注了板上的东西就接在那条下面回（reply_to=）。侧栏照常回复，但板上已经写的别大段重复。'
+        + '尺寸守规范（0.8 倍一屏可读、正文 md 起、一条板书说一件事）；画完 look_at_board 看一眼再收。' });
+    }
+  } catch { /* 读失败：不注入 */ }
   try {
     const cfg = await readUiConfigFile(workspaceRoot);
     if (cfg) {

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.`,
+            + '',
         }],
       };
     },