@xiaobuyu/nodesign 0.0.6 → 0.0.8

package/server/engine/mcp/tools/screenshot.js

@@ -19,7 +19,7 @@ import { can } from '../../../lib/kinds/index.js';
 import { screenshotDocx } from './screenshot-docx.js';
 import { SITE_DEVICE_W } from './helpers/perception-page.js';
 import { acquireArtifactPage, LIVE_PARAM_DESC } from './helpers/acquire-page.js';
-import { normalizeShot, detectPaintTransform, attachPageDiagnostics, runWaitFor, runBeforeShot } from './helpers/shot-pipeline.js';
+import { normalizeShot, detectPaintTransform, attachPageDiagnostics, runWaitFor, runBeforeShot, shotWithFallback, longPageSheet, clipShotWithFallback } from './helpers/shot-pipeline.js';
 import { recordMotion, pickNearestFrames, composeSheet, encodeWebm, motionCaptionLines } from './helpers/motion-lab.js';
 import { wheelScroll, elementMotionReport, elementMotionLines } from './helpers/motion-scroll.js';
 
@@ -87,7 +87,7 @@ to also read your own console.log output from the page (grouped, capped).
 
 FILMSTRIP — the eye for ANIMATION. A single still cannot show easing, overshoot,
 hard cuts between tweens, or "the whole move played off-screen". Pass
-frames (2-30 ms offsets, e.g. [0,120,240,400,700]) + trigger:"window.game.reload()" (JS that
+frames (2-30 ms offsets within a 30s window, e.g. [0,120,240,400,700]) + trigger:"window.game.reload()" (JS that
 starts the move) and you get ONE contact sheet: the same viewport at each of those
 moments, timestamped. One image = one motion curve — judge attack, overshoot,
 settle and cuts directly. click:"#start" performs a REAL trusted click instead
@@ -168,7 +168,7 @@ Do NOT use this tool when:
         .optional()
         .describe("Console capture level for the caption. Default 'warn' returns only warnings/errors (the count of filtered log lines is reported). Pass 'all' to also get console.log/info/debug output — the only way to read your own debug logging from the page."),
       frames: z
-        .array(z.number().min(0).max(15000))
+        .array(z.number().min(0).max(30000))
         .min(1)
         .max(30)
         .optional()
@@ -428,6 +428,8 @@ Do NOT use this tool when:
         // （系统 fit script 包 frame + scroll-snap），locator.screenshot 自动
         // 拿目标 section 的 bbox，不需要再操作 DOM。
         let buf;
+        let shotDegraded = false;
+        let longPageNote = null;
         let captureMode;
         const targetSelector = selector
           || (pageIndex ? `section[data-page="${pageIndex}"]` : null);
@@ -476,13 +478,19 @@ Do NOT use this tool when:
           };
           clip.width = Math.max(1, Math.min(rect.width, rect.docW - clip.x));
           clip.height = Math.max(1, Math.min(rect.height, rect.docH - clip.y));
-          buf = await page.screenshot({ fullPage: true, clip, type: 'png' });
+          ({ buf, degraded: shotDegraded } = await clipShotWithFallback(page, { clip, selector: targetSelector }));
           captureMode = `selector="${targetSelector}"`;
         } else {
-          buf = await page.screenshot({ fullPage: fp, type: 'png' });
-          captureMode = isSite
-            ? `site ${device || 'desktop'} ${vp.width}px, fullPage=${fp}`
-            : `fullPage=${fp}`;
+          // 超长页 fullPage → 滚动联络表（阈值与理由见 shot-pipeline.longPageSheet）
+          const sheet = fp ? await longPageSheet(page).catch(() => null) : null;
+          if (sheet) {
+            buf = sheet.buf; captureMode = sheet.mode; longPageNote = sheet.note;
+          } else {
+            ({ buf, degraded: shotDegraded } = await shotWithFallback(page, { fullPage: fp, type: 'png' }));
+            captureMode = isSite
+              ? `site ${device || 'desktop'} ${vp.width}px, fullPage=${fp}`
+              : `fullPage=${fp}`;
+          }
         }
         // live 页的 DPR 是会话的（1），detail:'normal' 的 0.6 光栅在这里事后缩
         if (acq.live && rasterScale < 1) {
@@ -537,7 +545,9 @@ Do NOT use this tool when:
         const shot = await normalizeShot(buf);
 
         const captionParts = [
-          `Screenshot of ${target.relPath} (layout ${vp.width}x${vp.height} @${rasterScale}x raster, ${captureMode})`,
+          `Screenshot of ${target.relPath} (layout ${vp.width}x${vp.height} @${rasterScale}x raster, ${captureMode})`
+          + (shotDegraded ? '（常规截图等稳定帧超时——页面在持续动画（WebGL/rAF），已改抓当前帧：画面是真实的某一瞬间，动画中间态属正常）' : '')
+          + (longPageNote ? `（${longPageNote}）` : ''),
         ];
         // 加载通道写进 caption：agent 不用再靠"把 location.protocol 写进 DOM 再截一张"
         // 去反推自己被什么方式打开了（问题库 iss_msxk2oci_0v0v 就是这么查了四轮）

package/server/engine/mcp/tools/set-vars.js

@@ -0,0 +1,150 @@
+/**
+ * mcp/tools/set-vars.js —— `set_vars`：改状态表里的几格（2026-08-30）
+ *
+ * ## 它跟 `edit_board set_text` 的分工
+ *
+ * set_text 是「重写这条板书的整篇正文」。状态板每拍都要动几个数字，用 set_text 就得
+ * 把整张卡连叙述带表格重写一遍 —— 那正是它老写漏、老写错的地方（改一个数字要重述
+ * 十几行，模型每次都在重新生成不该变的部分）。
+ *
+ * set_vars 只动表里那一格，别的一个字不碰。落盘走的是**跟 set_text 同一个**
+ * 重写函数（lib/chalk-rewrite.js），所以 frontmatter 保留、卡高重算、
+ * 用户拖出来的留白留得住这三条不会两边不一致。
+ *
+ * ## 为什么写口要大声失败，不 fail-soft
+ *
+ * 状态表的真相是一份**三方可写**的自由文本：set_vars、agent 的 set_text/Edit、
+ * 以及用户自己（chalk_edit 就是为让他随手改板书造的）。写口只守得住自己那一路。
+ * 所以这一路必须**看不懂就当场停**：表被改坏时若还 fail-soft 地"尽力写"，
+ * 结果是表被写成第二种坏格式，而且没有任何人知道。
+ * 读侧另有一层报警（每轮状态块的 vars 节，见 hooks/user-prompt-submit.js）。
+ *
+ * ⚠️ 笔权（只有作者能改自己的板书）在这里**不判**：状态表是场务件，不是谁的台词。
+ * 谁在管这一场，谁就该能改数字。这跟 edit_board 对叙事板书的规矩是两回事。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { readBoard, patchBoard } from '../../../projects/board-store.js';
+import { rewriteChalkBody } from '../../../lib/chalk-rewrite.js';
+import {
+  findStateTable, applyVars, parseStateTable, renderRows,
+  STATE_TABLE_TAG, VALUE_MAX, KEY_MAX,
+} from '../../../lib/state-table.js';
+
+/** 一次最多改几个键：再多就不是"改状态"是"重建状态表"，那该用 set_text */
+const MAX_KEYS = 20;
+
+export function makeSetVarsTool({ projectId, sharedRoot }) {
+  return tool(
+    'set_vars',
+    `Update values in the board's state table — the one chalk note tagged "${STATE_TABLE_TAG}".
+
+Use this every beat for anything that changed and must be remembered: HP, 好感度, 时间,
+线索, 持有物, 进度. It edits ONLY those cells; the rest of the note (your prose, the
+layout, other tables) is left byte-for-byte alone, and the card is re-measured for you.
+
+Why not edit_board set_text: that rewrites the whole note, so changing one number means
+regenerating a dozen lines that should not change. That is where numbers get silently lost.
+
+The table is plain markdown living in a note the user can see and edit:
+
+  | 键 | 值 |
+  | --- | --- |
+  | 好感度_苏绵 | 3 |
+
+Values you set here show up at the top of your NEXT turn, so you do not have to carry
+them in your head. Keys: letters/digits/CJK/_/-/·, max ${KEY_MAX} chars. Values are
+single-line, max ${VALUE_MAX} chars — long text belongs in the note body, not a cell.
+
+If there is no state table yet, this tool creates nothing: write one first with
+write_on_board (tag: "${STATE_TABLE_TAG}"), then set values here.`,
+    {
+      vars: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+        .describe('Keys to set, e.g. {"好感度_苏绵": 5, "时间": "戌时"}. Existing keys are updated, new ones appended.'),
+    },
+    async (args) => {
+      const fail = (msg) => ({ content: [{ type: 'text', text: msg }], isError: true });
+      if (!projectId || !sharedRoot) return fail('没有项目工作区，set_vars 不可用。');
+
+      const vars = args?.vars && typeof args.vars === 'object' ? args.vars : null;
+      const keys = vars ? Object.keys(vars) : [];
+      if (!keys.length) return fail('vars 是空的 —— 给至少一个键值对。');
+      if (keys.length > MAX_KEYS) {
+        return fail(`一次改了 ${keys.length} 个键，超过 ${MAX_KEYS} 上限。`
+          + `改这么多说明你在重建整张表 —— 那用 write_on_board / edit_board 的 set_text 重写更合适。`);
+      }
+
+      const found = await findStateTable(sharedRoot);
+      if (!found.found) {
+        if (found.reason === 'multiple') {
+          return fail(`板上有 ${found.rels.length} 条 tag 是「${STATE_TABLE_TAG}」的板书：${found.rels.join('、')}。`
+            + `状态表只能有一条 —— 先把多余的那条改掉 tag 或撤下来（edit_board remove），我不猜该改哪一条。`);
+        }
+        return fail(`板上还没有状态表。先用 write_on_board 落一条（\`tag: "${STATE_TABLE_TAG}"\`），`
+          + `正文里放一张两列的表：\n\n| 键 | 值 |\n| --- | --- |\n| 好感度_苏绵 | 3 |\n\n然后再来 set_vars。`);
+      }
+
+      let applied;
+      try {
+        applied = applyVars(found.body, vars);
+      } catch (err) {
+        // ⚠️ 两种失败要说成两句话（真工具探针当场抓到的：原来一律说"表看不懂"，
+        // 于是模型传了个坏键、却被指去修一张根本没坏的表）。
+        // 错误归因说错方向，比不报错好不了多少 —— 它会让人去改对的东西。
+        if (err.code === 'BAD_KEY') {
+          return fail(`这个键不能用，一个格都没改：${err.message}\n`
+            + `（表本身没问题，换个键名重来。）`);
+        }
+        // 大声失败：读不懂就停，绝不"尽力写" —— 写坏的表下一次会被写得更坏，
+        // 而这一路是三个写入方里唯一守得住的那个
+        return fail(`${found.rel} 的状态表看不懂，这次一个键都没改：${err.message}\n`
+          + `（先把表修好 —— 它是普通 markdown，Read 那个文件就能看见。）`);
+      }
+
+      if (!applied.changed.length && !applied.added.length) {
+        return { content: [{ type: 'text', text: `表里这几个键已经是这个值了，没动：${keys.join('、')}（${found.rel}）` }] };
+      }
+
+      // 落盘 + 板上重算：走跟 set_text 同一个函数，三条语义（frontmatter 保留 /
+      // 卡高重算 / 用户拖出来的留白留得住）不会两边不一致
+      const board = await readBoard(projectId);
+      const entry = board.objects?.[found.rel] || {};
+      let box;
+      try {
+        box = await rewriteChalkBody(found.abs, applied.body, entry);
+      } catch (err) {
+        return fail(`${found.rel} 写不进去（${err.message}）—— 表没改成。`);
+      }
+      if (board.objects?.[found.rel]) {
+        // patchBoard 收的是 diff 对象不是回调（board-store.js:85）
+        try {
+          await patchBoard(projectId, { objects: { [found.rel]: { ...entry, w: box.w, h: box.h } } });
+        } catch { /* 板上尺寸没跟上不影响真相（文件已经改了），下次 reflow 会对 */ }
+      }
+
+      const lines = [];
+      if (applied.changed.length) {
+        lines.push(`改了 ${applied.changed.length} 格：`
+          + applied.changed.map((c) => `${c.key} ${c.from || '（空）'} → ${c.to}`).join('；'));
+      }
+      if (applied.added.length) {
+        lines.push(`新增 ${applied.added.length} 格：`
+          + applied.added.map((c) => `${c.key} = ${c.value}`).join('；'));
+      }
+      if (applied.clamped.length) {
+        // 钳住但要说（入参不许静默改口径）
+        lines.push(`⚠️ 这几个值被清洗过（换行压成空格、竖线换成斜杠、超 ${VALUE_MAX} 字截断）：${applied.clamped.join('、')}`);
+      }
+      lines.push(`表在 ${found.rel}，现在共 ${applied.rows.length} 格。下一轮开头你会看到它。`);
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    },
+  );
+}
+
+/** 给测试与 SKILL 用的样板表（保持和工具描述里那段一致） */
+export function sampleStateTable(rows = [{ key: '好感度_苏绵', value: '3' }]) {
+  return renderRows(rows).join('\n');
+}
+
+export { parseStateTable };

package/server/engine/mcp/tools/sheet-replan.js

@@ -0,0 +1,46 @@
+/**
+ * mcp/tools/sheet-replan.js —— edit_board 的 replan op（2026-08-30 刀⑧，
+ * 行数棘轮拆件）。
+ *
+ * 版位原来只能在 open_sheet 那一刻定，写到一半发现规划错了只能整张重来 ——
+ * 「先画格子」得是能修正的动作。按名合并：点名的版位增改，没点名的原样保留；
+ * 新声明 for:'artifacts' 时旧的产物位摘牌（一张纸只有一个产物位）。
+ */
+
+import { innerRect, currentSheet } from '../../../lib/board-sheets.js';
+import { currentSheetIdOf } from '../../../lib/sheet-state.js';
+import { capacityOf } from '../../../lib/sketch-layout.js';
+import { clampPlan } from './open-sheet.js';
+
+/**
+ * @returns {{ error:string } | { sheetId:string, entry:object, report:string }}
+ *   entry = 该纸更新后的完整登记项（调用方放进 sheets patch）
+ */
+export function applyReplan({ board, sheetsPatch, sessionId, op }) {
+  const base = { ...board, sheets: { ...(board.sheets || {}), ...sheetsPatch } };
+  const sh = op.sheet && base.sheets?.[op.sheet]
+    ? { id: op.sheet, ...base.sheets[op.sheet] }
+    : currentSheet(base, currentSheetIdOf(sessionId));
+  if (!sh) return { error: '还没有纸 —— 先 open_sheet' };
+  const inn = innerRect(sh);
+  // prevSlots：below 可以引用纸上已有的版位（「在 main 底下补一块」是最常见的补法）
+  const { slots: addSlots, clampedSlots } = clampPlan(op.plan, { w: inn.w, h: inn.h }, base.sheets[sh.id].slots || {});
+  const merged = { ...(base.sheets[sh.id].slots || {}) };
+  if (Object.values(addSlots).some((sl) => sl.for === 'artifacts')) {
+    for (const nm of Object.keys(merged)) {
+      if (merged[nm].for === 'artifacts') { merged[nm] = { ...merged[nm] }; delete merged[nm].for; }
+    }
+  }
+  // 属性级合并（2026-08-30）：replan 只想改尺寸时不该把旧的 about / for 一并抹掉
+  for (const [nm, sl] of Object.entries(addSlots)) merged[nm] = { ...(merged[nm] || {}), ...sl };
+  const names = Object.entries(addSlots).map(([nm, sl]) => {
+    const c = capacityOf(sl.w, sl.h);
+    return `${nm} at (${sl.x},${sl.y}) ${sl.w}x${sl.h}（~${c.lines} 行 / ~${c.cjk} 字）`;
+  });
+  return {
+    sheetId: sh.id,
+    entry: { ...base.sheets[sh.id], slots: merged },
+    report: `· replan：纸 ${sh.id} 增改版位 ${names.join('；')}`
+      + `${clampedSlots.length ? `；⚠ 钳进版心：${clampedSlots.join(', ')}` : ''}。没点名的版位原样保留。`,
+  };
+}

package/server/engine/mcp/tools/web-search.js

@@ -393,6 +393,7 @@ Suggested flow for image-led pages:
         //    - 普通模式：tavily/exa/baidu/zhipu auto-route by language（CJK→baidu, EN→tavily）
         //    - include_images：zhipu 不支持图，从候选中剔除；其余按语言 auto-route
         let providerId;
+        let providerNote = '';
         if (include_images) {
           if (provider === 'zhipu') {
             return {
@@ -418,15 +419,13 @@ Suggested flow for image-led pages:
               };
             }
           } else {
+            // 点名的 provider 没配 key：换配了的顶上别硬失败（结果>供应商身份，iss_mt5z4s8j）
             providerId = provider;
             if (!getKey(providerId)) {
-              return {
-                content: [{
-                  type: 'text',
-                  text: `web_search failed: ${PROVIDERS[providerId].keyEnv} not set in .env.`,
-                }],
-                isError: true,
-              };
+              const alt = ((looksChinese(query) ? PRIORITY_CJK : PRIORITY_NON_CJK).filter(id => id !== 'zhipu')).find(id => getKey(id)) || null;
+              if (!alt) return { content: [{ type: 'text', text: `web_search failed: ${PROVIDERS[providerId].keyEnv} not set, and no other image-capable provider configured.` }], isError: true };
+              providerNote = `（provider "${provider}" 没配 key，已换用 ${alt}）`;
+              providerId = alt;
             }
           }
         } else {
@@ -443,13 +442,10 @@ Suggested flow for image-led pages:
             };
           }
           if (!getKey(providerId)) {
-            return {
-              content: [{
-                type: 'text',
-                text: `web_search failed: ${PROVIDERS[providerId].keyEnv} not set in .env.`,
-              }],
-              isError: true,
-            };
+            const alt = autoSelectProvider(query);   // 只挑配了 key 的
+            if (!alt || !getKey(alt)) return { content: [{ type: 'text', text: `web_search failed: ${PROVIDERS[providerId].keyEnv} not set, and no other provider configured.` }], isError: true };
+            providerNote = `（provider "${providerId}" 没配 key，已换用 ${alt}）`;
+            providerId = alt;
           }
         }
 
@@ -498,7 +494,7 @@ Suggested flow for image-led pages:
           // 落盘了就发 file_changed —— generate_image 一直在发，这里漏了，
           // 于是参考图落进工作区之后前端毫无感知（素材抽屉要刷新才看得见）
           for (const img of downloadedImages) {
-            try { ctx?.emit?.({ type: 'run.file_changed', path: img.relPath, change: 'add' }); } catch { /* */ }
+            try { ctx?.emit?.({ type: 'run.file_changed', filePath: img.relPath, event: 'add' }); } catch { /* */ }
           }
         }
 
@@ -518,7 +514,7 @@ Suggested flow for image-led pages:
         // count 张 + base64 体积。已在上一步通过 count 截断控量。
         const out = [{
           type: 'text',
-          text: formatMarkdown(query, providerId, hits, { images: downloadedImages }),
+          text: `${providerNote ? `${providerNote}\n` : ''}${formatMarkdown(query, providerId, hits, { images: downloadedImages })}`,
         }];
         for (const img of downloadedImages) {
           if (img.base64) {

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 };
+}