@xiaobuyu/nodesign 0.0.7 → 0.0.8

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

@@ -0,0 +1,108 @@
+/**
+ * mcp/tools/write-on-board-flow.js —— write_on_board 的 flow 档（2026-08-30 刀⑦，
+ * 行数棘轮拆件：主文件只留一个入口）。
+ *
+ * 「剩 15 行 vs 我这段几行」这道算术模型做不准也不该做（proj_mtfpehm3 真会话
+ * 14 发 board_batch 挂 6 发全是容量拒收）。flow 把它拿走：整段内容按段落边界
+ * 拆成一串 ≤ 一张卡高的小板书，链着往版位/纸里排，装到哪儿是哪儿 —— 装不下的
+ * **原样退回**（不挤 / 不丢 / 不替它翻页，刀 F 的拒收教义一条不破）。
+ */
+
+import { flowChunks } from '../../../lib/chalk-flow.js';
+import { textBox, capacityOf } from '../../../lib/sketch-layout.js';
+import { CARD_MAX_H } from '../../../lib/screen.js';
+import { UNIT } from '../../../lib/rect.js';
+import { renderChalk, chalkFileName, writeChalkFile } from '../../../lib/chalk.js';
+import { patchBoard } from '../../../projects/board-store.js';
+import { applyFollows } from '../../../lib/board-follow.js';
+import { Events } from '../../agent/events.js';
+
+/**
+ * flow 写入。返回工具结果；**返回 null = 用不上 flow**（守卫不过 / 一块就装下），
+ * 调用方接着走正常单条路径。
+ */
+export async function maybeFlowWrite({
+  projectId, sharedRoot, sessionId, by, ctx, args, body, wUnits, zone,
+  slotInfo, parentId, replyRect, anchorId, b2, obstaclesOf,
+  placeInSlot, placeOnSheets, describeSheetFull, stamp,
+}) {
+  const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
+  if (args.ink === 'hand') return err("flow 拆的是板书链，ink:'hand' 没有文件本体接不了链 —— 去掉其中一个。");
+  if (args.open_lane) return err('flow 跟 open_lane 分两步：先 open_lane 落线头，再 {tag, chain:true, flow:true} 续长文。');
+  if (zone) return err('flow 排的是纸，文件夹层没有纸 —— 在文件夹里逐条写。');
+  const chunks = flowChunks(body, { wUnits, size: args.size || 'md', maxH: CARD_MAX_H });
+  if (chunks.length <= 1) return null;   // 体积本来就小，正常单条路径
+
+  let live = b2;
+  const objects = {}; const bindings = {};
+  const written = [];
+  let prevRel = parentId; let prevRect = replyRect;
+  let leftover = 0; let fullMsg = null;
+  for (let i = 0; i < chunks.length; i += 1) {
+    const cBox = textBox(chunks[i], args.size === 'sm' ? 'md' : (args.size || 'md'), { md: true, wUnits });
+    const obs = obstaclesOf(live, '');
+    let p;
+    if (slotInfo) {
+      p = placeInSlot(live, { rect: slotInfo.rect, sheet: slotInfo.sheet, slotName: args.slot, box: cBox, obstacles: obs });
+      if (p.full) { leftover = chunks.length - i; fullMsg = p.message; break; }
+    } else {
+      p = await placeOnSheets(live, {
+        box: cBox, at: (i === 0 && args.at) ? args.at : null, sheetName: args.sheet || null,
+        replyRect: prevRect, anchorRect: null, side: null, obstacles: obs,
+      });
+      if (p.sheetFull) { leftover = chunks.length - i; fullMsg = describeSheetFull(live, p.sheetFull); break; }
+      if (p.opened) live = { ...live, sheets: { ...(live.sheets || {}), [p.opened.id]: { x: p.opened.x, y: p.opened.y, w: p.opened.w, h: p.opened.h, at: p.opened.at, by } } };
+    }
+    const content = renderChalk({
+      body: chunks[i], by, anchor: i === 0 ? anchorId : null,
+      replyTo: prevRel, tag: args.tag || null, sessionId: sessionId || null,
+    });
+    const rel = await writeChalkFile(sharedRoot, chalkFileName(chunks[i]), content);
+    const entry = {
+      x: Math.round(p.x), y: Math.round(p.y), z: 1, w: cBox.w, h: cBox.h,
+      zone: '', by, seat: 'agent', ...(args.tag ? { tag: args.tag } : {}),
+    };
+    objects[rel] = entry;
+    if (i === 0 && anchorId) {
+      const type = args.relation || 'annotates';
+      const [from, to] = type === 'flow' ? [anchorId, rel] : [rel, anchorId];
+      bindings[`b:a${stamp()}`] = { type, from, to, by, ...(args.tag ? { tag: args.tag } : {}) };
+    }
+    if (prevRel) bindings[`b:a${stamp()}`] = { type: 'flow', from: prevRel, to: rel, by, material: 'pencil', ...(args.tag ? { tag: args.tag } : {}) };
+    live = { ...live, objects: { ...(live.objects || {}), [rel]: entry } };
+    written.push({ rel, rect: { x: entry.x, y: entry.y, w: entry.w, h: entry.h } });
+    prevRel = rel; prevRect = written[written.length - 1].rect;
+  }
+  if (!written.length) return err(fullMsg || '⛔ 一条都没放下。');
+  await patchBoard(projectId, { objects, bindings });
+  if (args.tag) { try { await applyFollows(projectId, { tag: args.tag, newId: written[written.length - 1].rel }); } catch { /* */ } }
+  const xs = written.map((w) => w.rect.x); const ys = written.map((w) => w.rect.y);
+  const bbox = {
+    x: Math.min(...xs), y: Math.min(...ys),
+    w: Math.max(...written.map((w) => w.rect.x + w.rect.w)) - Math.min(...xs),
+    h: Math.max(...written.map((w) => w.rect.y + w.rect.h)) - Math.min(...ys),
+  };
+  try {
+    ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `写了一串板书（${written.length} 条）` });
+    ctx?.emit?.(Events.boardFocus(bbox, { tag: args.tag || null, layer: '', soft: true, chalk: written[0].rel, actor: by !== 'agent' ? by : null }));
+  } catch { /* fail-soft */ }
+  const lines = [
+    `Flowed into ${written.length} chained notes${args.slot ? ` in slot "${args.slot}"` : ''}:`,
+    ...written.map((w) => `  ${w.rel} at (${w.rect.x},${w.rect.y}) ${w.rect.w}x${w.rect.h}`),
+  ];
+  if (slotInfo) {
+    const last = written[written.length - 1].rect;
+    const freeH = Math.max(0, Math.round(slotInfo.rect.y + slotInfo.rect.h - (last.y + last.h) - UNIT));
+    const c = capacityOf(slotInfo.rect.w, freeH);
+    lines.push(`Slot "${args.slot}" now has ~${c.lines} lines (~${c.cjk} CJK chars, ${freeH}px) left.`);
+  }
+  if (leftover) {
+    const rest = chunks.slice(chunks.length - leftover);
+    const restH = rest.reduce((n, t) => n + textBox(t, 'md', { md: true, wUnits }).h, 0);
+    lines.push(`⚠ ${leftover} paragraph(s) did NOT fit (from 「${[...rest[0]].slice(0, 16).join('')}…」, ~${Math.ceil(restH / 26)} lines). They were returned untouched — nothing was squeezed or dropped.`);
+    if (fullMsg) lines.push(fullMsg.split('\n')[0]);
+    lines.push(`Continue them yourself: open the next page (open_sheet) or pick another slot, then write the REST again with {flow:true, chain:true${args.tag ? `, tag:"${args.tag}"` : ''}} — chain threads it onto ${written[written.length - 1].rel}.`);
+  }
+  lines.push('The user can annotate any of them to reply; answer with reply_to.');
+  return { content: [{ type: 'text', text: lines.join('\n') }] };
+}

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

@@ -0,0 +1,211 @@
+/**
+ * mcp/tools/write-on-board-place.js —— write_on_board 的纸上落位（2026-08-29 纸范式刀 2，
+ * 行数棘轮拆件：text 与 sketch 两条路共用同一份落位与返回文案）。
+ *
+ * 决策树（启发式引擎退役后仅存的分支）：
+ *   near+side 显式 → 精确贴放（语义要求；压上如实报）
+ *   slot          → 规划好的那块地里往下堆（装不下**拒收**，一个字不落盘）
+ *   reply_to      → 接楼正下方（纸满拒收）
+ *   at            → 纸内定点（钳进版心，钳了如实报）
+ *   什么都没有    → 纸内顺排（先往下、这一列到底往右；真的排不下才拒收）
+ * 文件夹层没有纸：线程/贴放照常，否则排在这一层内容底下。
+ */
+
+import {
+  currentSheet, toLocal, placeAtOnSheet, placeThread, placeBeside,
+  nextSpotInSheet, overlapIds, sheetOfPoint, slotRectOf, nextSpotInSlot,
+} from '../../../lib/board-sheets.js';
+import { capacityOf } from '../../../lib/sketch-layout.js';
+import { currentSheetIdOf, setCurrentSheetId } from '../../../lib/sheet-state.js';
+import { UNIT } from '../../../lib/rect.js';
+import { openSheetFor } from './open-sheet.js';
+
+export function makeSheetPlacer({ projectId, sessionId, by }) {
+  /**
+   * 版位解析（2026-08-29 刀 E）。**要在算板书宽度之前调** —— 一块地多宽，
+   * 写进去的东西就多宽，不再各自按内容估。
+   * @returns {{rect,sheet}|{error:string,message:string}}
+   */
+  const resolveSlot = (b, { slotName, sheetName }) => {
+    const sheets = b.sheets || {};
+    const sheet = (sheetName && sheets[sheetName])
+      ? { id: sheetName, ...sheets[sheetName] }
+      : currentSheet({ sheets }, currentSheetIdOf(sessionId));
+    if (!sheet) {
+      return { error: 'no-sheet', message: 'No sheet yet — open_sheet first (plan the page, then write into its slots).' };
+    }
+    const rect = slotRectOf(sheet, slotName);
+    if (!rect) {
+      const names = Object.keys(sheet.slots || {});
+      return {
+        error: 'no-slot',
+        message: names.length
+          ? `Sheet ${sheet.id} has no slot "${slotName}". It has: ${names.join(', ')}.`
+          : `Sheet ${sheet.id} has no slots planned. Plan the page first: open_sheet{plan:[{slot,at,w,h,about}…]}.`,
+      };
+    }
+    return { rect, sheet };
+  };
+
+  /**
+   * 版位内落位。装不下**拒收**（站主拍板：提示 agent 分块内容、重新布置）——
+   * 折叠/裁切/挤进去都是替它把问题藏起来，而它下一条还会照写不误。
+   */
+  const placeInSlot = (b, { rect, sheet, slotName, box, obstacles }) => {
+    const spot = nextSpotInSlot(b, rect, box);
+    if (spot.full) {
+      const left = capacityOf(rect.w, spot.freeH);
+      const whole = capacityOf(rect.w, rect.h);
+      // 量纲对齐（刀⑥ 2026-08-30）：两边都报 px + 行，还差多少直接说 —— 此前
+      // 「剩 ~15 行 / 要 ~15 行」被拒，在模型眼里就是量具坏了（真差 21px）。
+      const short = spot.needH - spot.freeH;
+      return {
+        full: true,
+        message: [
+          `⛔ Slot "${slotName}" on sheet ${sheet.id} cannot take this — short by ${short}px (~${Math.max(1, Math.ceil(short / 26))} line${short > 26 ? 's' : ''}).`,
+          `   Free: ${spot.freeH}px (~${left.lines} lines / ~${left.cjk} CJK chars); this note needs ${spot.needH}px.`
+            + `${spot.taken ? ` The ${rect.w}x${rect.h} slot (~${whole.cjk} CJK chars) already holds ${spot.taken} item(s).` : ''}`,
+          '   Nothing was written. Split it YOUR way: make this slot taller (replan it by name,',
+          '   omit at — it resizes in place) or carve fresh blocks (omit at to stack below) and fill them one',
+          '   note each. Or trim it. Lazy fallback: flow:true lets the machine split at paragraph breaks.',
+        ].join('\n'),
+      };
+    }
+    setCurrentSheetId(sessionId, sheet.id);
+    return {
+      x: spot.x, y: spot.y, resolution: 'slot', slot: slotName, sheetId: sheet.id,
+      pressed: overlapIds({ x: spot.x, y: spot.y, w: box.w, h: box.h }, obstacles),
+    };
+  };
+
+  /** 根层：纸上落位。返回 {x,y,resolution,sheetId,opened,clamped,pressed} */
+  const placeOnSheets = async (b, { box, at, sheetName, replyRect, anchorRect, side, obstacles }) => {
+    let sheets = b.sheets || {};
+    let opened = null;
+    const pick = () => {
+      if (sheetName && sheets[sheetName]) return { id: sheetName, ...sheets[sheetName] };
+      return currentSheet({ sheets }, currentSheetIdOf(sessionId));
+    };
+    /** 铺第一张纸（还一张都没有时）。**不用于翻页** —— 见下方 sheetFull。 */
+    const openFirst = async () => {
+      opened = await openSheetFor(projectId, { sessionId, by, where: null });
+      sheets = { ...sheets, [opened.id]: { x: opened.x, y: opened.y, w: opened.w, h: opened.h, at: opened.at, by: opened.by } };
+      return { id: opened.id, ...sheets[opened.id] };
+    };
+    const bWith = () => ({ ...b, sheets });
+    const done = (p, resolution, sheetId, clamped = false) => {
+      if (sheetId) setCurrentSheetId(sessionId, sheetId);
+      const pressed = overlapIds({ x: p.x, y: p.y, w: box.w, h: box.h }, obstacles);
+      return {
+        x: Math.round(p.x), y: Math.round(p.y), resolution, sheetId, opened, clamped, pressed,
+        overflowY: p.overflowY || 0,   // 纸从那个 y 往下不够高还差多少（换纸判据）
+        moved: !!p.moved,              // 这一列到底了、往右挪了一块空地
+      };
+    };
+    const sheetOf = (p) => {
+      const hit = sheetOfPoint(bWith(), { x: p.x + box.w / 2, y: p.y + box.h / 2 });
+      return hit ? hit.id : null;
+    };
+
+    // 显式贴放（near + side）：语义要求（题注在上方）的精确几何，不搜索
+    if (anchorRect && side) {
+      const p = placeBeside(anchorRect, box, side, UNIT);
+      return done(p, `beside-${side}`, sheetOf(p));
+    }
+    // 线程：正下方；接不下去就在同一张纸上顺排（真满了才翻页）
+    if (replyRect) {
+      const p = placeThread(bWith(), replyRect, box, { obstacles });
+      if (!p.sheetFull) return done(p, 'thread', p.sheetId);
+      /**
+       * ⚠️ placeThread 只认**正下方一个方向**，被挡住就往那件底下跳，一跳出纸底
+       * 就报 sheetFull —— 但这只说明"这条线接不下去"，不说明"这张纸满了"。
+       *
+       * 真案 proj_mtg61or1 19:13：p1 上母板书正下方杵着 960x628 的试作站点卡，
+       * 接楼跳过它就出了版心底（2437），于是报了
+       * 「⛔ Sheet p1 is full (all columns used) — nothing was written」。
+       * 同一张纸同一刻，nextSpotInSheet 返回 (1392,1512) —— 第 4 栏整栏空着。
+       * agent 信了这句话去 open_sheet，一场会话开出四张纸；每开一张，暂存架和
+       * 纸互相顶的那个棘轮就再转一格（见 lib/board-shelf.js bandHitsSheet）。
+       *
+       * 所以先在同一张纸上顺排。回复关系靠 reply_to 落的那条边保着，本来就
+       * 不依赖几何相邻 —— 挪一栏丢的只是"紧贴在下面"这个视觉暗示。
+       */
+      const flow = nextSpotInSheet(bWith(), p.sheetFull, box);
+      if (flow) return done(flow, 'thread-flow', p.sheetFull);
+      return { sheetFull: p.sheetFull };
+    }
+    // 定点 / 顺排：都要有一张纸
+    let s = pick();
+    if (!s) s = await openFirst();
+    if (at) {
+      const p = placeAtOnSheet(s, at, box);
+      return done(p, 'at', s.id, p.clamped);
+    }
+    const flow = nextSpotInSheet(bWith(), s.id, box);
+    if (flow) return done(flow, 'flow', s.id);
+    // 这张纸排满了。**不替它翻页**（2026-08-29 刀 F，站主拍板"每张纸规划一次"）：
+    // 机器悄悄翻页的话，agent 根本不知道自己换了页，新纸自然也没有版面 —— 真会话
+    // proj_mtfhey1x 里 p2 规划得好好的，写满翻到 p3 就散回顺排了。纸是它开的，
+    // 满了该由它决定下一页什么样。
+    return { sheetFull: s.id };
+  };
+
+  /** 文件夹层落位（没有纸）：线程/贴放照常，否则排在这一层内容底下 */
+  const placeInZone = ({ box, replyRect, anchorRect, side, obstacles }) => {
+    if (replyRect) {
+      const p = placeThread({ sheets: {} }, replyRect, box, { obstacles });
+      return { x: p.x, y: p.y, resolution: 'thread', pressed: [] };
+    }
+    if (anchorRect) {
+      const p = placeBeside(anchorRect, box, side || 'below', UNIT);
+      return { x: p.x, y: p.y, resolution: `beside-${side || 'below'}`, pressed: overlapIds({ x: p.x, y: p.y, w: box.w, h: box.h }, obstacles) };
+    }
+    const left = obstacles.length ? Math.min(...obstacles.map(o => o.x)) : 10;
+    const bottom = obstacles.reduce((m, o) => Math.max(m, o.y + o.h), 0);
+    return { x: Math.round(left), y: Math.round(bottom) + 40, resolution: 'below-content', pressed: [] };
+  };
+
+  /** 纸排满了的报文：不替它翻页，告诉它该规划下一页了 */
+  const describeSheetFull = (b, sheetId) => {
+    const sh = b.sheets?.[sheetId];
+    const inner = sh ? { w: sh.w - 48, h: sh.h - 48 } : { w: 0, h: 0 };
+    const landscape = inner.w > inner.h;
+    return [
+      `⛔ Sheet ${sheetId} is full${landscape ? ' (all columns used)' : ''} — nothing was written.`,
+      `   Open the next page yourself and plan it: open_sheet{title:"…", plan:[{slot,at,w,h,about}…]}.`,
+      `   Each sheet gets its own layout — decide what this next page is for before filling it.`,
+    ].join('\n');
+  };
+
+  /** 返回文案：从真实落点生成（"工具返回不许撒谎"—— 08-25 陷阱③ 的纪律不变） */
+  const describeSpot = (b, placed) => {
+    const bits = [];
+    if (placed.sheetId && b.sheets?.[placed.sheetId]) {
+      const s = { id: placed.sheetId, ...b.sheets[placed.sheetId] };
+      const l = toLocal(s, placed);
+      bits.push(`on sheet ${s.id}${s.title ? `（${s.title}）` : ''} at local (${Math.round(l.x)},${Math.round(l.y)})`);
+    }
+    if (placed.resolution === 'thread') bits.push('under the note it replies to (thread)');
+    else if (placed.resolution === 'flow') {
+      bits.push(placed.moved
+        ? 'the column you were in ran out — flowed into free space further right on the same sheet'
+        : 'flowed below the last item');
+    }
+    else if (placed.resolution === 'slot') bits.push(`in slot "${placed.slot}" (planned block)`);
+    else if (placed.resolution === 'at') {
+      // 换纸判据（08-29 刀 C）：光说"钳住了"不够 —— 钳住的结果是这条被压到贴着
+      // 纸底、跟上一条挤在一起，而 agent 不知道该翻页了。
+      bits.push(placed.overflowY
+        ? `at your spot but this sheet RAN OUT below that y (short by ${placed.overflowY}px) — it was pushed up to fit. Turn the page (open_sheet) or write it shorter`
+        : (placed.clamped ? 'at your spot, CLAMPED into the sheet (it stuck out)' : 'exactly where you asked'));
+    }
+    else if (placed.resolution?.startsWith('beside-')) bits.push(`${placed.resolution.slice(7)} of the anchor (exact — no auto-nudging)`);
+    else if (placed.resolution === 'lane-open') bits.push('at the head of its fresh sheet');
+    else if (placed.resolution === 'below-content') bits.push('below current content (folder layer has no sheets)');
+    if (placed.opened) bits.push(`opened sheet ${placed.opened.id} (${placed.opened.innerW}x${placed.opened.innerH} writable)`);
+    if (placed.pressed?.length) bits.push(`⚠ overlaps ${placed.pressed.slice(0, 4).join(', ')} — move yours (edit_board) if unintended`);
+    return bits.join('; ');
+  };
+
+  return { placeOnSheets, placeInZone, describeSpot, resolveSlot, placeInSlot, describeSheetFull };
+}

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

@@ -0,0 +1,48 @@
+/**
+ * mcp/tools/write-on-board-role-anchor.js —— 角色板书的缺省锚（2026-08-28；08-29 泛化成「这一拍」）
+ *
+ * 角色不带任何落位线索（reply_to/near/at/open_lane）时，机器替它选锚。两级：
+ *
+ * 1. **属于它的那条线**（预制摆位，用户拍板）：主持人用 open_lane 以角色名（slug 或
+ *    展示名）开过线 → 自动接在自己那条线上（reply_to 线内最新一条 + 着线的 tag）。
+ *    摆位和延伸方向是主持人预制的，角色的工作退化成「补一段话」。
+ * 2. **这一拍**（08-29）：角色没有专属线时，它这一段就是在回应**主持人最新写的那一条**
+ *    —— reply_to 它，再经侧挂直觉落到它身侧。「章节竖着走、同一拍的几个人横着排」
+ *    是从「在回应谁」这个语义里自己长出来的，不硬编版式。
+ *
+ *    08-28 时这一级只在 rounds 模式下开；模式概念 08-29 整个退役（谁接这一拍由主持人
+ *    每拍决定，不再是一个服务端状态），所以这一级对所有角色一律成立。
+ *
+ * 角色明确给了落位（比如回用户那条）时它的手优先，这里不抢。
+ */
+import { CHALK_DIR } from '../../../lib/chalk.js';
+import { listRoleNames } from '../../agent/role-card.js';
+
+/**
+ * @returns {Promise<{replyTo: string|null, tag: string|null}>}
+ *   replyTo 非空 = 用它当缺省锚；tag 非空 = 这条板书顺带着线的 tag（仅专属线路径给）。
+ */
+export async function roleDefaultAnchor({ board, by, sharedRoot }) {
+  // 属于它的那条线优先
+  if (board.lanes) {
+    let laneTag = board.lanes[by] ? by : null;
+    if (!laneTag) {
+      try {
+        const nm = (await listRoleNames(sharedRoot)).get(by);
+        if (nm && board.lanes[nm]) laneTag = nm;
+      } catch { /* 展示名查不到就只认 slug 线 */ }
+    }
+    if (laneTag) {
+      const inLane = Object.entries(board.objects)
+        .filter(([id, e]) => id.startsWith(`${CHALK_DIR}/`) && Number.isFinite(e?.x) && e.tag === laneTag)
+        .map(([id]) => id).sort();
+      if (inLane.length) return { replyTo: inLane[inLane.length - 1], tag: laneTag };
+    }
+  }
+  // 这一拍 = 主持人最新写的那一条
+  const beats = Object.entries(board.objects)
+    .filter(([id, e]) => id.startsWith(`${CHALK_DIR}/`) && Number.isFinite(e?.x) && (e.by || 'agent') === 'agent')
+    .map(([id]) => id).sort();   // 板书文件名以时间戳开头，路径序即时间序
+  if (beats.length) return { replyTo: beats[beats.length - 1], tag: null };
+  return { replyTo: null, tag: null };
+}

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

@@ -0,0 +1,125 @@
+/**
+ * write_on_board 的图形入参 schema（2026-08-28 从 write-on-board.js 拆出 —— 行数棘轮；
+ * 纯数据，跟落板逻辑零耦合）。上限是失控兜底不是风格闸：zod 硬拒（-32602 整调用作废）
+ * 是最贵的失败模式，可读性走返回值里的软提醒（08-25 用户拍板「移除画板上限」）。
+ */
+
+import { z } from 'zod';
+import { BINDING_TYPE_IDS, BINDING_MATERIALS } from '../../../lib/binding-types.js';
+import { TAG_RE } from '../../../projects/board-sanitize.js';
+import { CHALK_DIR } from '../../../lib/chalk.js';
+import { STENCIL_NAMES } from '../../../lib/sketch-stencils.js';
+
+const MAX_NODES = 200;
+const MAX_SHAPES = 120;
+const MAX_EDGES = 400;
+
+const LOCAL_ID = z.string().regex(/^[A-Za-z0-9_-]{1,48}$/, 'local id: letters/digits/_/-');
+const GRID_PT = z.object({ x: z.number().min(-2000).max(2000), y: z.number().min(-2000).max(2000) });
+export const WORLD_PT = z.object({ x: z.number().min(-1e6).max(1e6), y: z.number().min(-1e6).max(1e6) });
+/**
+ * 纸内坐标（2026-08-29 纸范式）：以当前纸版心左上角为原点的像素。越界**钳住不拒收**
+ * （schema 整单拒是最贵的失败模式；钳过在返回里如实报）。preprocess 在给模型看的
+ * JSON schema 里隐形 —— 文档照旧严格，垫片只当安全网。
+ */
+const clampN = (lo, hi) => (v) => (typeof v === 'number' && Number.isFinite(v) ? Math.max(lo, Math.min(hi, v)) : v);
+export const SHEET_PT = z.object({
+  x: z.preprocess(clampN(0, 12000), z.number().min(0).max(12000)),
+  y: z.preprocess(clampN(0, 12000), z.number().min(0).max(12000)),
+});
+
+export const NODES = z.array(z.object({
+  id: LOCAL_ID.describe('Local id to reference from edges/shapes'),
+  text: z.string().min(1).max(8000),
+  format: z.enum(['plain', 'md']).optional().describe('Default: md when the text carries markdown marks, else plain'),
+  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(120).optional().describe('Width in grid units (prefer ≤22 = 528px: paragraphs read better growing down than wide)'),
+})).max(MAX_NODES);
+
+export const SHAPES = z.array(z.object({
+  id: LOCAL_ID.optional(),
+  kind: z.enum(['rect', 'ellipse', 'circle', 'line', 'arrow', 'underline', 'path', 'stencil']),
+  at: GRID_PT.optional(),
+  name: z.enum(STENCIL_NAMES).optional()
+    .describe('stencil kind: which pictogram — a hand-tuned little drawing placed at at, scaled to w (h optional, defaults to its natural aspect). Use these instead of drawing common things stroke by stroke'),
+  flip: z.boolean().optional().describe('stencil: mirror horizontally (facing the other way)'),
+  around: LOCAL_ID.optional().describe('rect/ellipse/circle/underline: wrap this node instead of at/w/h'),
+  w: z.number().min(0).max(200).optional(),
+  h: z.number().min(0).max(200).optional(),
+  to: GRID_PT.optional(),
+  toNode: LOCAL_ID.optional(),
+  d: z.string().max(8000).optional().describe('path kind: SVG path, UPPERCASE absolute M/L/Q/C/Z only. Coordinates are in the SAME GRID UNITS as at/w/h (1 unit = 24px; decimals fine) — one coordinate space for the whole sketch. Hand-drawn wobble is applied for you; Q/C curves are how you draw anything smooth (a crescent moon, a wave, a sail)'),
+  color: z.enum(['ink', 'red', 'pencil', 'brass']).optional(),
+  width: z.number().min(1).max(12).optional(),
+  fill: z.enum(['hatch']).optional()
+    .describe('Shade the inside with hand-drawn 45° hatching — the line-art way to darken an area (a shadow side, water, a filled banner). Closed shapes only (rect/ellipse/circle, a path whose subpaths end with Z, closable stencils)'),
+  // ── 算子（一次挂一个；等距/对称/播撒这类算术归机器，每份笔迹各自抖）──
+  repeat: z.object({ n: z.number().int().min(2).max(24), dx: z.number().min(-200).max(200).optional(), dy: z.number().min(-200).max(200).optional() }).optional()
+    .describe('LINEAR ARRAY: n copies stepped by (dx,dy) grid units — a fence, windows, steps. Copies are re-inked, not stamped'),
+  ring: z.object({ n: z.number().int().min(2).max(24), cx: z.number().min(-2000).max(2000), cy: z.number().min(-2000).max(2000), upright: z.boolean().optional() }).optional()
+    .describe('CIRCULAR ARRAY: n copies around grid point (cx,cy). Draw ONE at its 12-o-clock spot. Default ROTATES each copy (petals, clock marks, top-down chairs facing a table); upright:true keeps them unrotated and just seats them round the circle (side-view things with gravity — tents or people round a fire)'),
+  mirror: z.object({ axis: z.enum(['x', 'y']), at: z.number().min(-2000).max(2000) }).optional()
+    .describe("SYMMETRY: adds a mirrored copy across the axis at grid position `at` (axis:'x' = vertical mirror line). Draw half a butterfly, get the whole one"),
+  scatter: z.object({ n: z.number().int().min(2).max(40), in: z.object({ x: z.number(), y: z.number(), w: z.number().min(1), h: z.number().min(1) }) }).optional()
+    .describe('SPRINKLE: n copies at seeded-random spots inside the grid rect, with slight size jitter — a starry sky, grass, pebbles. Same call replays identically'),
+})).max(MAX_SHAPES);
+
+export const 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);
+
+/**
+ * ⚠️ 字段顺序有意义（2026-08-29 占位契约刀 C）：模型是按 schema 声明顺序生成
+ * JSON 的，而入参是**流式**到达前端的 —— 位置字段排在 text 前面，画布才能在
+ * 第一个字到达时就把框立在真位置上，让正文流进去（排在后面的话，字已经流完了
+ * 位置才到，只能先画在一块空地上再跳过去 —— 那正是这一刀要治的）。
+ * 抽取规则在 agent-shared.js 的 TOOL_INPUT_STREAM_FIELDS.spot。
+ */
+export const WRITE_SCHEMA = {
+  slot: z.string().regex(TAG_RE).optional()
+    .describe('Drop this into a PLANNED BLOCK of the current sheet (names come from open_sheet{plan}). The block decides the width and where it lands; notes stack downward inside it. If it does not fit, the write is REFUSED with how much room is left — split the content or re-plan. Prefer this over at: plan the page first, then fill it.'),
+  at: SHEET_PT.optional()
+    .describe("Where on the CURRENT SHEET, in pixels from its top-left writable corner (x→right, y→down). Clamped into the sheet — the return says if it was. Omit it to flow top-to-bottom"),
+  sheet: z.string().regex(TAG_RE).optional()
+    .describe('Write on this sheet instead of the current one (names from open_sheet / read_board)'),
+  width: z.number().min(8).max(60).optional().describe('Single note width in grid units (24px). Default: the width the user last dragged chalk blocks to, else by content. Omit it unless this one block needs a different measure - the default already follows the user.'),
+  near: z.string().max(300).optional()
+    .describe('Canvas id or #tag this is ABOUT — draws an annotates line to it. Placement itself is by sheet (at / flow), not by near'),
+  side: z.enum(['right', 'left', 'above', 'below']).optional()
+    .describe('ONLY with near, when the SEMANTICS demand a side (e.g. a caption must sit above): exact placement beside the anchor. Normally omit — sheets flow downward'),
+  reply_to: z.string().max(300).optional().describe(`Thread: path of a board note (${CHALK_DIR}/…md) to answer under (lands right below it; a full sheet turns the page)`),
+  text: z.string().min(1).max(8000).optional()
+    .describe('The one-note shorthand: a short Markdown note (= a 1-piece board write). Give text OR nodes/shapes, not both'),
+  flow: z.boolean().optional()
+    .describe('Lazy FALLBACK for a ready-made long text: the machine splits it at paragraph breaks into a chain of card-sized notes, packs them as far as they fit, and returns the rest untouched (never squeezed, dropped, or auto-paged). PREFER carving slots yourself (open_sheet{plan}/replan, omit at to stack) and filling them one note each — you keep control of where each part breaks.'),
+  h: z.number().min(24).max(2000).optional()
+    .describe('Reserve this HEIGHT in pixels for the note box, placed before the text settles (plan the box, then fill it). Shorter content keeps the box; longer content overrides it. Ignored with flow.'),
+  relation: z.enum(BINDING_TYPE_IDS).optional()
+    .describe('Line type for the near line of a single note (default annotates; flow reads anchor→note)'),
+  chain: z.boolean().optional()
+    .describe('Single note: auto reply_to the latest board note of the same tag WRITTEN BY YOU (threads never cross authors — continuation rights)'),
+  open_lane: z.string().max(300).optional()
+    .describe("Open a NEW thread line named by tag: lays a fresh sheet for it and lands this note at its head. Value: a canvas id/#tag to BRANCH from (draws a flow line from it), or 'fresh' for a brand-new topic. Requires tag; continue with {tag, chain:true}."),
+  tag: z.string().regex(TAG_RE).optional()
+    .describe('Group tag. A 1-piece write stays untagged unless you pass one; ≥2 pieces auto-tag sk-<stamp>'),
+  ink: z.enum(['chalk', 'hand']).optional()
+    .describe("Single note body: 'chalk' (default) = a real file under notes/板书 (Read/Edit later; chain/reply threads live on these); 'hand' = canvas-native handwritten text — a light remark like the user's own handwriting, no file, no threading"),
+  font: z.enum(['pen', 'kai', 'sans', 'serif', 'mono']).optional().describe("Single note font (ink:'hand'; default kai)"),
+  color: z.enum(['ink', 'red', 'pencil', 'brass']).optional().describe("Single note color (ink:'hand')"),
+  size: z.enum(['sm', 'md', 'lg', 'xl']).optional().describe("Single note text size. Real for ink:'hand'; for chalk notes it only sizes the placement box (chalk renders at a fixed size)"),
+  title: z.string().max(60).optional().describe('Sketch: optional heading written at the top'),
+  layout: z.enum(['auto', 'free', 'column', 'row', 'grid', 'mindmap', 'flow']).optional()
+    .describe('Sketch layout. auto FOLLOWS YOUR EDGES: with edges it lays out in flow layers (roots on top, children below — give edges and placement is structure); mindmap picks the hub by degree. free needs at on EVERY node'),
+  cols: z.number().int().min(1).max(8).optional().describe('grid columns'),
+  staging: z.boolean().optional().describe('Sketch only: default true (translucent until commit/turn end). Ignored for single notes — they always land solid'),
+  nodes: NODES.optional(),
+  shapes: SHAPES.optional(),
+  edges: EDGES.optional(),
+};