@xiaobuyu/nodesign 0.0.2 → 0.0.4

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(); }

package/server/index.js

@@ -153,6 +153,9 @@ if (platform.serveWeb) {
   });
 }
 
+// /api 下没路由接住的一律回 JSON 404（express 默认是 HTML，前端 jsonRequest 拿到的是解析错误不是 {error}）
+app.use('/api', (req, res) => res.status(404).json({ error: `not found: ${req.method} ${req.originalUrl}`, code: 'NOT_FOUND' }));
+
 // ── 错误兜底 ──
 app.use((err, _req, res, _next) => {
   console.error('[server] error:', err);

package/server/lib/binding-types.js

@@ -55,6 +55,18 @@ export const BINDING_TYPES = {
 /** 词汇表 id 列表，校验和 parity 断言都用它。 */
 export const BINDING_TYPE_IDS = Object.keys(BINDING_TYPES);
 
+/**
+ * 材质（2026-08-23 黑板）：与语义正交的第二个轴。
+ *   ink     墨线 —— 版面线的默认材质，安静
+ *   pencil  手绘 —— 铅笔抖动，像人顺手拉的一笔
+ *   yarn    丝线 —— 侦探板上的红线 + 图钉，推理态、声量大
+ * 前端 board-bindings.js 的 BINDING_MATERIALS 必须与这份 id 一一对应（parity 测试）。
+ */
+export const BINDING_MATERIALS = ['ink', 'pencil', 'yarn'];
+export function isBindingMaterial(m) {
+  return BINDING_MATERIALS.includes(m);
+}
+
 export function isBindingType(t) {
   return Object.prototype.hasOwnProperty.call(BINDING_TYPES, t);
 }

package/server/lib/board-graph-export.js

@@ -0,0 +1,191 @@
+/**
+ * server/lib/board-graph-export.js —— 连接图导出（2026-08-23 黑板）
+ *
+ * 真相是 board.json（节点 + 线 + 位置 + 标签），由它派生三种形态：
+ *   json     结构原样（给程序 / 备份）
+ *   mermaid  flowchart 文本（给别的工具吃；位置丢掉，语义留着）
+ *   svg      一张能看的图：卡片画成带名字的方框、手写字照排、涂鸦照路径、线照语义
+ *            —— 这是**导出保真度**的渲染，不是画布本体（画布本体只有前端那一份）
+ * 可按 #tag 只导一组。带产物的 zip 另议（zip 要搬文件，是交付层的事）。
+ */
+import { BINDING_TYPES } from './binding-types.js';
+import { estimateSizeOn } from './board-kind-sizes.js';
+import { layerOf } from './canvas-id.js';
+import { describeEndpoint } from './board-relations.js';
+
+function pick(board, { tag = null, layer = '' } = {}) {
+  const known = new Set(Object.keys(board.zones || {}));
+  const nodes = [];
+  for (const [id, e] of Object.entries(board.objects || {})) {
+    if (!Number.isFinite(e?.x)) continue;
+    if (layerOf(id, e, known) !== layer) continue;
+    if (tag && e.tag !== tag) continue;
+    const sz = estimateSizeOn(board, id, e);
+    nodes.push({
+      id, kind: e.kind || kindOfId(id), x: e.x, y: e.y, w: sz.w, h: sz.h,
+      ...(e.kind === 'text' ? { text: e.data?.t || '', format: e.data?.format || 'plain', font: e.data?.font, size: e.data?.size, color: e.data?.color } : {}),
+      ...(e.kind === 'scribble' ? { d: e.data?.d || '', color: e.data?.color, width: e.data?.width } : {}),
+      ...(e.tag ? { tag: e.tag } : {}), ...(e.staging ? { staging: true } : {}), ...(e.by ? { by: e.by } : {}),
+    });
+  }
+  const ids = new Set(nodes.map(n => n.id));
+  const edges = [];
+  for (const [id, b] of Object.entries(board.bindings || {})) {
+    if (!ids.has(b.from) || !ids.has(b.to)) continue;
+    if (tag && b.tag !== tag && !(ids.has(b.from) && ids.has(b.to))) continue;
+    edges.push({ id, type: b.type, from: b.from, to: b.to, ...(b.label ? { label: b.label } : {}), material: b.material || 'ink', ...(b.by ? { by: b.by } : {}), ...(b.tag ? { tag: b.tag } : {}) });
+  }
+  return { nodes, edges };
+}
+
+function kindOfId(id) {
+  const m = /^(deck|site|docx|doc):/.exec(id);
+  if (m) return m[1];
+  if (/\.(png|jpe?g|webp|gif|svg|avif)$/i.test(id)) return 'image';
+  if (/\.(mp4|webm|mov)$/i.test(id)) return 'video';
+  if (/\.(md|txt)$/i.test(id)) return 'note';
+  return 'file';
+}
+
+export function exportGraph(board, { format = 'json', tag = null, layer = '' } = {}) {
+  const g = pick(board, { tag, layer });
+  if (format === 'json') return { mime: 'application/json', body: JSON.stringify({ version: 1, tag, layer, ...g }, null, 2) };
+  if (format === 'mermaid') return { mime: 'text/plain; charset=utf-8', body: toMermaid(g, board) };
+  if (format === 'svg') return { mime: 'image/svg+xml; charset=utf-8', body: toSvg(g, board) };
+  throw Object.assign(new Error('unknown format'), { status: 400 });
+}
+
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+function nodeTitle(n, board) {
+  if (n.kind === 'text') return String(n.text || '').replace(/^#+\s*/gm, '').replace(/\s+/g, ' ').trim().slice(0, 60);
+  if (n.kind === 'scribble') return '（涂鸦）';
+  return describeEndpoint(n.id, board).replace(/（[a-z]+）$/, '');
+}
+
+export function toMermaid(g, board) {
+  const key = new Map(g.nodes.map((n, i) => [n.id, `n${i}`]));
+  const lines = ['flowchart LR'];
+  for (const n of g.nodes) {
+    if (n.kind === 'scribble') continue;
+    const t = nodeTitle(n, board).replace(/["[\]{}()|]/g, ' ').trim() || n.id;
+    const shape = n.kind === 'text' ? `("${t}")` : `["${t}"]`;
+    lines.push(`  ${key.get(n.id)}${shape}`);
+  }
+  for (const e of g.edges) {
+    const t = BINDING_TYPES[e.type];
+    const word = (e.label || t?.label || e.type).replace(/["|]/g, ' ');
+    const arrow = t?.directed ? `-- ${word} -->` : `--- ${word} ---`;
+    if (!key.has(e.from) || !key.has(e.to)) continue;
+    lines.push(`  ${key.get(e.from)} ${arrow} ${key.get(e.to)}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+const PAPER = { paper: '#F0EADB', ink: '#2B2117', ink2: '#5F5142', pencil: '#A39882', red: '#A8362B', brass: '#b08c4f', card: '#FFFEF6' };
+const INK = { ink: PAPER.ink, red: PAPER.red, pencil: PAPER.pencil, brass: PAPER.brass };
+const SIZE_PX = { sm: 13, md: 16, lg: 22, xl: 30 };
+
+function edgePoint(a, b) {
+  const ac = { x: a.x + a.w / 2, y: a.y + a.h / 2 }; const bc = { x: b.x + b.w / 2, y: b.y + b.h / 2 };
+  const dx = bc.x - ac.x; const dy = bc.y - ac.y;
+  const pt = (r, c, ddx, ddy) => {
+    const tx = ddx === 0 ? Infinity : (r.w / 2) / Math.abs(ddx); const ty = ddy === 0 ? Infinity : (r.h / 2) / Math.abs(ddy);
+    const t = Math.min(tx, ty); return { x: c.x + ddx * t, y: c.y + ddy * t };
+  };
+  return { from: pt(a, ac, dx, dy), to: pt(b, bc, -dx, -dy) };
+}
+
+export function toSvg(g, board, { hrefOf = null } = {}) {
+  if (!g.nodes.length) return '<svg xmlns="http://www.w3.org/2000/svg" width="200" height="60"><text x="10" y="35" font-size="14">（空）</text></svg>';
+  const PAD = 40;
+  const x0 = Math.min(...g.nodes.map(n => n.x)) - PAD; const y0 = Math.min(...g.nodes.map(n => n.y)) - PAD;
+  const x1 = Math.max(...g.nodes.map(n => n.x + n.w)) + PAD; const y1 = Math.max(...g.nodes.map(n => n.y + n.h)) + PAD;
+  const W = Math.round(x1 - x0); const H = Math.round(y1 - y0);
+  const byId = new Map(g.nodes.map(n => [n.id, n]));
+  const out = [];
+  out.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="${x0} ${y0} ${W} ${H}" font-family="'Kaiti SC','KaiTi','STKaiti',serif">`);
+  out.push(`<rect x="${x0}" y="${y0}" width="${W}" height="${H}" fill="${PAPER.paper}"/>`);
+  out.push('<defs><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto" markerUnits="userSpaceOnUse"><path d="M 1 1 L 9 5 L 1 9 z" fill="context-stroke"/></marker><marker id="dot" markerWidth="8" markerHeight="8" refX="4" refY="4" markerUnits="userSpaceOnUse"><circle cx="4" cy="4" r="3" fill="context-stroke"/></marker></defs>');
+  // 线在物件下面
+  for (const e of g.edges) {
+    const a = byId.get(e.from); const b = byId.get(e.to); if (!a || !b) continue;
+    const p = edgePoint(a, b);
+    const dx = p.to.x - p.from.x; const dy = p.to.y - p.from.y; const dist = Math.hypot(dx, dy) || 1;
+    const yarn = e.material === 'yarn';
+    const lift = yarn ? 0 : Math.min(dist * 0.14, 46);
+    const cx = (p.from.x + p.to.x) / 2 + (yarn ? 0 : (-dy / dist) * lift);
+    const cy = (p.from.y + p.to.y) / 2 + (yarn ? Math.min(dist * 0.11, 56) : (dx / dist) * lift);
+    const t = BINDING_TYPES[e.type];
+    const stroke = yarn ? PAPER.red : (e.type === 'contrast' ? PAPER.brass : e.type === 'ref' ? PAPER.pencil : e.type === 'derives-from' ? PAPER.ink : PAPER.ink2);
+    const width = yarn ? 2.6 : e.type === 'derives-from' ? 2.4 : e.type === 'annotates' ? 1.4 : 2;
+    const dash = !yarn && e.type === 'annotates' ? ' stroke-dasharray="3 4"' : !yarn && e.type === 'ref' ? ' stroke-dasharray="1 5"' : '';
+    const marker = yarn ? '' : (t?.directed ? ' marker-end="url(#arrow)"' : (e.type === 'link' ? ' marker-end="url(#dot)" marker-start="url(#dot)"' : ''));
+    out.push(`<path d="M ${p.from.x} ${p.from.y} Q ${cx} ${cy} ${p.to.x} ${p.to.y}" fill="none" stroke="${stroke}" stroke-width="${width}" stroke-linecap="round"${dash}${marker}/>`);
+    if (yarn) for (const q of [p.from, p.to]) out.push(`<circle cx="${q.x}" cy="${q.y}" r="4.6" fill="${PAPER.red}" stroke="${PAPER.ink}" stroke-width="0.8"/>`);
+    const word = e.label || (e.type !== 'annotates' ? t?.label : null);
+    if (word) {
+      const mx = 0.25 * p.from.x + 0.5 * cx + 0.25 * p.to.x; const my = 0.25 * p.from.y + 0.5 * cy + 0.25 * p.to.y;
+      out.push(`<text x="${mx}" y="${my}" font-size="11" text-anchor="middle" dominant-baseline="middle" fill="${PAPER.ink2}" stroke="${PAPER.paper}" stroke-width="4" paint-order="stroke">${esc(word)}</text>`);
+    }
+  }
+  for (const n of g.nodes) {
+    const op = n.staging ? ' opacity="0.55"' : '';
+    if (n.kind === 'scribble') {
+      out.push(`<g transform="translate(${n.x} ${n.y})"${op}><path d="${esc(n.d)}" fill="none" stroke="${INK[n.color] || PAPER.ink}" stroke-width="${n.width || 2}" stroke-linecap="round" stroke-linejoin="round"/></g>`);
+      continue;
+    }
+    if (n.kind === 'text') {
+      const px = SIZE_PX[n.size] || 16; const fill = INK[n.color] || PAPER.ink;
+      const lines = String(n.text || '').split('\n').slice(0, 24);
+      out.push(`<g transform="translate(${n.x + 6} ${n.y + 4})"${op}>` + lines.map((l, i) => `<text x="0" y="${Math.round((i + 0.85) * px * 1.6)}" font-size="${px}" fill="${fill}">${esc(l.replace(/^#+\s*/, '').replace(/\*\*/g, ''))}</text>`).join('') + '</g>');
+      continue;
+    }
+    const title = nodeTitle(n, board);
+    const href = hrefOf ? hrefOf(n) : null;
+    out.push(`${href ? `<a href="${esc(href)}">` : ''}<g${op}><rect x="${n.x}" y="${n.y}" width="${n.w}" height="${n.h}" rx="10" fill="${PAPER.card}" stroke="rgba(43,33,23,0.18)"/>`
+      + `<text x="${n.x + 12}" y="${n.y + 20}" font-size="13" fill="${PAPER.ink}">${esc(title)}</text>`
+      + `<text x="${n.x + 12}" y="${n.y + n.h - 10}" font-size="10" fill="${PAPER.pencil}">${esc(n.kind)}</text></g>${href ? '</a>' : ''}`);
+  }
+  out.push('</svg>');
+  return out.join('\n');
+}
+
+/* ── 带产物的 zip（2026-08-23）────────────────────────────────────────────
+ * 真相仍是 board.json；zip 里：board/graph.json + graph.svg（卡片可点，链到 zip 里的文件）+
+ * graph.mmd + index.html（内嵌 svg 的静态重放页）+ 节点指向的产物文件（走 export-collect
+ * 同一套寻址：站点整目录、deck 的 html、图片、板书 .md…）。画布原生的手写字/涂鸦没有文件，
+ * 它们的内容都在 graph.json/svg 里。
+ */
+export async function exportGraphZip(board, { workspaceRoot, tag = null, layer = '', projectName = '画布' } = {}) {
+  const [{ default: JSZip }, { collectCards }, fsm] = await Promise.all([
+    import('jszip'), import('./export-collect.js'), import('node:fs/promises'),
+  ]);
+  const g = pick(board, { tag, layer });
+  const fileIds = g.nodes.filter(n => n.kind !== 'text' && n.kind !== 'scribble').map(n => n.id);
+  const { bundles, skipped } = await collectCards({ workspaceRoot, cardIds: fileIds });
+  const zip = new JSZip();
+  const relOfNode = new Map();
+  for (const b of bundles) {
+    for (const f of [...(b.files || []), ...(b.assets || [])]) {
+      try { zip.file(f.rel, await fsm.readFile(f.abs)); } catch { /* 读不到就跳，写进 manifest */ }
+    }
+  }
+  // collectCard 不回 cardId：按顺序对齐（collectCards 按 cardIds 顺序 push，跳过的在 skipped）
+  const skippedIds = new Set(skipped.map(s => s.cardId));
+  let bi = 0;
+  for (const id of fileIds) {
+    if (skippedIds.has(id)) continue;
+    const b = bundles[bi++]; if (!b) break;
+    relOfNode.set(id, b.files?.[0]?.rel || b.assets?.[0]?.rel || null);
+  }
+  const hrefOf = (n) => { const r = relOfNode.get(n.id); return r ? `../${r.split('/').map(encodeURIComponent).join('/')}` : null; };
+  const svg = toSvg(g, board, { hrefOf });
+  zip.file('board/graph.json', JSON.stringify({ version: 1, tag, layer, ...g, files: Object.fromEntries(relOfNode), skipped }, null, 2));
+  zip.file('board/graph.svg', svg);
+  zip.file('board/graph.mmd', toMermaid(g, board));
+  zip.file('index.html', `<!doctype html><html lang="zh"><head><meta charset="utf-8"><title>${esc(projectName)} · 画布</title>
+<style>html,body{margin:0;background:#F0EADB;font-family:'Kaiti SC','KaiTi',serif}header{padding:12px 20px;color:#2B2117;font-size:14px}main{overflow:auto;padding:0 20px 20px}svg{max-width:100%;height:auto;display:block}a:hover rect{stroke:#b08c4f;stroke-width:2}</style></head>
+<body><header>${esc(projectName)} · 画布导出${tag ? ` · #${esc(tag)}` : ''} · ${g.nodes.length} 件 ${g.edges.length} 线 · 点卡片打开文件</header><main>${svg.replace(/\.\.\//g, '')}</main></body></html>`);
+  return { zip, skipped, count: { nodes: g.nodes.length, edges: g.edges.length, files: relOfNode.size } };
+}