@xiaobuyu/nodesign 0.0.7 → 0.0.8

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

@@ -0,0 +1,242 @@
+/**
+ * mcp/tools/open-sheet.js —— open_sheet 铺纸（2026-08-29 纸范式刀 2）
+ *
+ * 开工先铺纸：在画布上登记一块 0.75 倍缩放下等于用户一屏的矩形工作区。
+ * 铺在哪由机器定（第一张对准用户此刻的视口 —— 「agent 在用户眼皮底下开工」；
+ * 之后缺省铺在当前纸正下方，像往桌上接着铺稿纸）。铺完这张纸就是**当前纸**：
+ * write_on_board 的 at 坐标以它的版心左上角为原点，没给 at 的写入在纸内自动
+ * 往下排，写满自动翻下一张。
+ *
+ * 纸是分配纪律不是容器，**也不渲染**（用户拍板：纸只是位置范围的概念）——用户
+ * 看到的只有内容本身；纸的存在体现在落位秩序、翻纸导航和 read_board 的账本里。
+ * 用户可以把东西拖出纸外，组照旧由 tag/线派生。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { byOf } from '../actor.js';
+import { readBoard, patchBoard } from '../../../projects/board-store.js';
+import { TAG_RE } from '../../../projects/board-sanitize.js';
+import { obstaclesIn } from '../../../lib/board-obstacles.js';
+import { fitFor, capacityOf, DEFAULT_CHALK_W } from '../../../lib/sketch-layout.js';
+import { CARD_MAX_H } from '../../../lib/screen.js';
+import { getViewpoint } from '../../../projects/viewpoint-store.js';
+import {
+  sheetSizeFor, allocateSheetRect, nextSheetName, currentSheet, innerRect, SHEET_MARGIN,
+  membersInRect, sheetMembers,
+} from '../../../lib/board-sheets.js';
+import { setCurrentSheetId, currentSheetIdOf } from '../../../lib/sheet-state.js';
+import { Events } from '../../agent/events.js';
+
+/** 版位的 at：两轴各自可省 —— 省掉的轴由竖排糖补（below/接上一块）。
+ * ⛔ 不复用 write_on_board 的 SHEET_PT：它双轴必填，`at:{x:640}, below:"s1"`
+ * 这种半坐标会被 zod 整调用拒掉。 */
+const SLOT_AT = z.object({
+  x: z.number().min(0).max(12000).optional(),
+  y: z.number().min(0).max(12000).optional(),
+});
+
+/** 一块地（版位）。坐标/尺寸全是纸内局部像素 —— 跟 write_on_board 的 at 同一套
+ *（export 给 edit_board 的 replan 用 —— 版位的合法性只有这一份定义） */
+export const SLOT = z.object({
+  slot: z.string().regex(TAG_RE).describe('Name for this block, ASCII like main/aside/notes'),
+  at: SLOT_AT.optional().describe("Top-left of this block, pixels from the sheet's writable corner. OMIT it to stack this block right below the previous one in the list (or below the block named in `below`) — carve a column of slots without doing any y arithmetic. In a replan, omitting it on an EXISTING slot means resize in place (position kept)"),
+  below: z.string().regex(TAG_RE).optional().describe('Stack this block right under the named slot (24px gap). x follows that slot unless at.x says otherwise'),
+  w: z.number().min(48).max(12000).describe('Width in PIXELS (a default note column is 432)'),
+  h: z.number().min(24).max(12000).describe('Height in PIXELS (~26px per line of text)'),
+  about: z.string().max(60).optional().describe('What goes here (正文 / 人物小传 / 待办) — for your own map'),
+  for: z.literal('artifacts').optional()
+    .describe("Set to 'artifacts' on ONE block to make it this page's landing spot for generated files (images, docs, sites). Without it, files you produce have nowhere planned to go and the page fills up with them wherever there is room."),
+});
+
+/**
+ * 版面规划钳制（2026-08-29 刀 E；2026-08-30 抽出来给 replan 共用）：
+ * 开工先把这一屏切成几块地。坐标跟 at 同一套（纸内局部像素）。
+ * 越出版心的钳回来 —— 钳过如实报（规划错了要当场知道）。
+ *
+ * 竖排糖（2026-08-30 用户拍板「agent 自己定几个空位分段填」）：省掉 at（或点名
+ * `below`）＝接在上一块正下方 24px。**y 累加这道算术归机器**，几个空位怎么切、
+ * 每段写什么归 agent —— 分段的语义权不外包，只有几何外包。
+ * `prevSlots` 是 replan 时该纸已有的版位（below 可以引用它们；点名已有版位又
+ * 没给坐标＝原地改尺寸，不走竖排糖）。
+ */
+export function clampPlan(plan, inner0, prevSlots = {}) {
+  const slots = {};
+  const clampedSlots = [];
+  let prev = null;                       // 数组序上一块（本批的）
+  const refOf = (name) => slots[name] || prevSlots[name] || null;
+  for (const it of Array.isArray(plan) ? plan : []) {
+    const w = Math.min(Math.round(it.w), inner0.w);
+    const h = Math.min(Math.round(it.h), inner0.h);
+    // 点名**已有**版位又没给坐标 = 原地改尺寸（2026-08-30）：replan 想把 state 加高、
+    // 位置没提，此前走竖排糖落到 (0,0) 跟别的版位叠上 —— glm 真会话为这一下花了
+    // 三分钟理版面。竖排糖只对新版位生效。
+    const keep = !it.at && !it.below ? prevSlots[it.slot] : null;
+    const base = keep ? null : (it.below ? refOf(it.below) : (it.at ? null : prev));
+    const wantX = it.at?.x ?? keep?.x ?? base?.x ?? 0;
+    const wantY = it.at?.y ?? keep?.y ?? (base ? base.y + base.h + 24 : 0);
+    const x = Math.min(Math.max(0, Math.round(wantX)), Math.max(0, inner0.w - w));
+    const y = Math.min(Math.max(0, Math.round(wantY)), Math.max(0, inner0.h - h));
+    if (x !== Math.round(wantX) || y !== Math.round(wantY)
+      || w !== Math.round(it.w) || h !== Math.round(it.h)) clampedSlots.push(it.slot);
+    slots[it.slot] = { x, y, w, h, ...(it.about ? { about: it.about } : {}), ...(it.for === 'artifacts' ? { for: 'artifacts' } : {}) };
+    prev = slots[it.slot];
+  }
+  return { slots, clampedSlots };
+}
+
+/**
+ * 铺一张纸并登记（write_on_board 自动铺纸也走这一份 —— 分配纪律只有一份）。
+ * @returns {{ id, x, y, w, h, innerW, innerH, basis, overlapsLoose }}
+ */
+export async function openSheetFor(projectId, {
+  sessionId = null, by = 'agent', title = null, name = null, where = null, plan = null,
+} = {}) {
+  const board = await readBoard(projectId);
+  const vp = getViewpoint(projectId);
+  const fit = fitFor(vp);
+  const size = sheetSizeFor(fit);
+  let cur = currentSheet(board, currentSheetIdOf(sessionId));
+  // 缺省：还没有纸（或点名 viewport）→ 对准用户视口；有当前纸 → 铺在它正下方
+  const mode = where || (cur ? 'next' : 'viewport');
+  // 翻页裁纸（刀② 2026-08-30）：纸固定一屏高、下一张贴满高矩形正下方，上一张
+  // 只用了一半时内容之间就是几百像素的空白（proj_mtfpehm3 实测 268~557px，
+  // 设计间隔明明只有 48）。翻页那一刻把上一张裁到内容底 —— 纸是分配纪律不是
+  // 画出来的框，裁掉的只是"再也不会写进去的余白"；它的版位一并钳到新底。
+  let trimmed = null;
+  if (mode === 'next' && cur) {
+    const members = sheetMembers(board, cur.id);
+    const innerC = innerRect(cur);
+    const bottom = members.length ? Math.max(...members.map((m) => m.y + m.h)) : innerC.y;
+    const newH = Math.max(240, Math.ceil((bottom + SHEET_MARGIN - cur.y) / 24) * 24);
+    if (newH < cur.h - 24) {
+      const oldEntry = board.sheets[cur.id];
+      const newSlots = {};
+      for (const [nm, sl] of Object.entries(oldEntry.slots || {})) {
+        newSlots[nm] = { ...sl, h: Math.max(24, Math.min(sl.h, newH - SHEET_MARGIN * 2 - sl.y)) };
+      }
+      const patched = { ...oldEntry, h: newH, ...(Object.keys(newSlots).length ? { slots: newSlots } : {}) };
+      await patchBoard(projectId, { sheets: { [cur.id]: patched } });
+      trimmed = { id: cur.id, from: cur.h, to: newH };
+      board.sheets = { ...board.sheets, [cur.id]: patched };
+      cur = { ...cur, h: newH };
+    }
+  }
+  // 铺纸尽量不压散件。⛔ 不含文件夹/卷卡这类常驻家具：纸不渲染，纸矩形盖住文件夹
+  // 用户什么也看不见，而纸内落位照样会避开它 —— 算进来只会把第一张纸推离用户视口。
+  const obstacles = obstaclesIn(board, '', { furniture: false });
+  const rect = allocateSheetRect({
+    board, size,
+    viewport: mode === 'viewport' && vp?.camera && !vp.layer ? vp.camera : null,
+    nearSheet: mode === 'next' && cur ? cur.id : null,
+    obstacles,
+  });
+  const id = (name && TAG_RE.test(name) && !board.sheets?.[name]) ? name : nextSheetName(board);
+  const inner0 = innerRect({ x: rect.x, y: rect.y, w: rect.w, h: rect.h });
+  const { slots, clampedSlots } = clampPlan(plan, inner0);
+  const entry = {
+    x: rect.x, y: rect.y, w: rect.w, h: rect.h,
+    by, at: new Date().toISOString(), ...(title ? { title } : {}),
+    ...(Object.keys(slots).length ? { slots } : {}),
+  };
+  await patchBoard(projectId, { sheets: { [id]: entry } });
+  setCurrentSheetId(sessionId, id);
+  const inner = innerRect({ ...entry });
+  // 占地者点名（刀③ 2026-08-30）：铺纸不避家具（纸不渲染，压着文件夹用户什么也
+  // 看不见），但**必须说清这块地上已经住着谁** —— proj_mtfpehm3 首拍就是纸铺在
+  // 文件夹排上、agent 规划的版位下半截被占，连吃四发拒收却没人告诉它为什么。
+  const occupants = membersInRect({ ...board, sheets: board.sheets }, { x: rect.x, y: rect.y, w: rect.w, h: rect.h })
+    .map((m) => ({
+      id: m.id, folder: !!m.folder,
+      local: { x: m.x - inner.x, y: m.y - inner.y }, w: m.w, h: m.h,
+      slots: Object.entries(slots)
+        .filter(([, sl]) => m.x < inner.x + sl.x + sl.w && m.x + m.w > inner.x + sl.x
+          && m.y < inner.y + sl.y + sl.h && m.y + m.h > inner.y + sl.y)
+        .map(([nm]) => nm),
+    }));
+  return {
+    id, ...entry, innerW: inner.w, innerH: inner.h,
+    basis: rect.basis, overlapsLoose: rect.overlapsLoose, clampedSlots, occupants, trimmed,
+  };
+}
+
+const DESCRIPTION = `Lay a fresh SHEET on the board and make it the current one — do this before you
+start writing (like turning to a clean page). A sheet is one screen of the user's
+device at 75% zoom; the machine picks where it goes (the first sheet opens right
+under the user's current view; later ones stack below the current sheet).
+After this, write_on_board's at:{x,y} means PIXELS from this sheet's top-left
+writable corner, and writes without at flow top-to-bottom on it; when a sheet
+fills up a new one is opened for you automatically — call open_sheet yourself when
+you START A NEW TOPIC/CHAPTER, so each sheet reads as one page about one thing.
+The user can drag things off a sheet freely — the sheet constrains you, not them.`;
+
+export function makeOpenSheetTool({ projectId, sessionId, ctx }) {
+  return tool('open_sheet', DESCRIPTION, {
+    title: z.string().max(60).optional().describe('What this sheet is about (for read_board / your own map, e.g. 第二章 — sheets are invisible to the user)'),
+    name: z.string().regex(TAG_RE).optional().describe('Sheet name to refer to it later (ASCII like act2; default auto p1/p2/…)'),
+    where: z.enum(['next', 'viewport']).optional()
+      .describe("next = below the current sheet (default when sheets exist); viewport = right where the user is looking now (default for the first sheet — also use it to bring work back to the user's eyes)"),
+    plan: z.array(SLOT).max(24).optional()
+      .describe('PLAN THE WHOLE PAGE HERE, before writing anything: carve the sheet into named blocks (slots) and say what goes in each. Then write_on_board{slot:"main"} drops content into that block. A sheet is WIDE (landscape) — a single column down the left wastes most of it; think in columns and rows.'),
+  }, async (args, extra) => {
+    if (!projectId) return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
+    const by = byOf(extra);
+    const s = await openSheetFor(projectId, {
+      sessionId, by, title: args.title || null, name: args.name || null, where: args.where || null,
+      plan: args.plan || null,
+    });
+    try {
+      ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `铺了一张纸 ${s.id}` });
+      ctx?.emit?.(Events.boardFocus({ x: s.x, y: s.y, w: s.w, h: s.h }, { layer: '', soft: s.basis !== 'viewport', actor: by !== 'agent' ? by : null }));
+    } catch { /* fail-soft */ }
+    const colCap = capacityOf(DEFAULT_CHALK_W, s.innerH);
+    const cols = Math.max(1, Math.floor(s.innerW / (DEFAULT_CHALK_W + SHEET_MARGIN)));
+    const lines = [
+      `Sheet ${s.id} laid at world (${s.x},${s.y}) ${s.w}x${s.h}${s.title ? ` — “${s.title}”` : ''}; it is now the current sheet.`,
+      `Writable area: ${s.innerW}x${s.innerH}px, margin ${SHEET_MARGIN}. at:{x,y} means pixels from its top-left writable corner (x→right, y→down).`,
+      // 量纲（刀 D）：agent 手里的东西是字，护栏却全是像素 —— 让它自己换算
+      // ＝ 每次落笔前做一道做不准的算术，结果是写完才发现装不下。
+      `Scale: ~26px per line, ~${colCap.perLine} CJK chars per ${DEFAULT_CHALK_W}px-wide line. This sheet is ${colCap.lines} lines deep and ${cols} columns wide (≈${colCap.cjk * cols} CJK chars if you use all of it).`,
+    ];
+    const slotList = Object.entries(s.slots || {});
+    if (slotList.length) {
+      // 覆盖率（刀 E）：一张横着的纸只画一条竖栏，大半是空的 —— 把这个数直接报出来
+      const used = slotList.reduce((n, [, v]) => n + v.w * v.h, 0);
+      const pct = Math.round((used / (s.innerW * s.innerH)) * 100);
+      lines.push(`Planned ${slotList.length} slots covering ${pct}% of the sheet:`);
+      for (const [nm, v] of slotList) {
+        const c = capacityOf(v.w, v.h);
+        lines.push(`  ${nm}${v.about ? `（${v.about}）` : ''}: at (${v.x},${v.y}) ${v.w}x${v.h} — ~${c.lines} lines, ~${c.cjk} CJK chars`);
+      }
+      lines.push('write_on_board{slot:"<name>"} drops a note into a block (they stack downward inside it). Content that does not fit is REFUSED, not squeezed — re-plan or split it.');
+      if (pct < 45) lines.push(`⚠ ${100 - pct}% of this sheet is unplanned. A landscape sheet holds ${cols} columns side by side — carve more blocks rather than leaving it empty.`);
+      if (s.clampedSlots?.length) lines.push(`⚠ Clamped into the sheet (they stuck out): ${s.clampedSlots.join(', ')} — check their at/w/h.`);
+    } else {
+      lines.push(`No slots planned. Plan the page in one go — open_sheet{plan:[{slot,at,w,h,about}…]} — instead of writing one note at a time and hoping it lands well. This sheet takes ${cols} columns side by side; a single column down the left leaves ${Math.round((1 - 1 / cols) * 100)}% of it empty.`);
+    }
+    lines.push(s.basis === 'viewport' ? 'Opened under the user’s current view.' : (s.basis === 'below-sheet' ? 'Stacked below the current sheet.' : 'Placed below existing content.'));
+    if (s.trimmed) {
+      lines.push(`Previous sheet ${s.trimmed.id} was trimmed to its content (${s.trimmed.from}→${s.trimmed.to}px tall) so the pages sit close — its leftover blank is gone, not its content.`);
+      // 利用率点名（2026-08-30）：裁掉近半张纸 = 翻页翻快了。只点名不拦 ——
+      // 换场景翻新纸永远合法，这里治的是「每拍一张纸」的过度避险。
+      const waste = s.trimmed.from - s.trimmed.to;
+      if (waste >= 400) {
+        lines.push(`⚠ You left ~${waste}px of that sheet unused — pages are turning faster than they fill. Short beats can keep landing on the current sheet (they flow down; no slot needed). Turn the page for a scene change or a refusal, not for every beat.`);
+      }
+    }
+    // 占地者点名（刀③）：谁在纸上、占了哪块版位、该怎么办 —— 三样一次说清
+    if (s.occupants?.length) {
+      const named = s.occupants.slice(0, 6).map((o) =>
+        `${o.folder ? '📁 ' : ''}${o.id} at local (${Math.round(o.local.x)},${Math.round(o.local.y)}) ${o.w}x${o.h}${o.slots.length ? ` — sits in your slot "${o.slots.join('", "')}"` : ''}`);
+      lines.push(`⚠ ${s.occupants.length} item(s) ALREADY LIVE on this sheet's ground (they count against your space):`);
+      for (const n of named) lines.push(`   ${n}`);
+      if (s.occupants.length > 6) lines.push(`   …and ${s.occupants.length - 6} more (read_board lists them).`);
+      lines.push('   Options: plan/re-plan your blocks AROUND them (edit_board replan), move them somewhere'
+        + ' deliberate (edit_board move — they may be the user\'s, so keep them visible), or re-open with'
+        + ' where:"next" for clean ground. Do NOT just write over them.');
+    } else if (s.overlapsLoose) {
+      lines.push('⚠ Some loose items already sit in this area — they now read as “on this sheet”; move them (edit_board) if that is wrong.');
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  });
+}

package/server/engine/mcp/tools/organize-board.js

@@ -9,8 +9,8 @@
  * 实现 = **和用户拖拽「移动到…」同一份核心**（projects/move-entry.js）：
  * 磁盘先行、画布身份同步、转发表记账，一个字不重写。
  *
- * 批量制（同 roll_film / paint_still）：≤16 件、串行、**中途失败即停**
- * （后面的不动，报告哪件停的）。目标夹不存在就建 —— 归纳常配新夹。
+ * 批量制（同 roll_film / paint_still）：≤16 件、串行。**重名跳过、其余即停**
+ * （停了就报哪件停的，后面的不动）。目标夹不存在就建 —— 归纳常配新夹。
  */
 
 import { tool } from '@anthropic-ai/claude-agent-sdk';
@@ -33,7 +33,7 @@ at the moved items) are rewritten to the new paths automatically — the count o
 rewritten spots is reported per file so you can verify. Pass rewrite_refs:false
 to move only.
 
-Batch: up to 16 items, moved in order, stops at first failure.`,
+Batch: up to 16 items, moved in order. A name clash at the destination is skipped (that one is likely already filed) and the rest still move; any other failure stops the batch.`,
     {
       items: z.array(z.string().min(1)).min(1).max(16)
         .describe('Workspace-relative paths to move (files or folders), e.g. ["assets/generated/a.png", "旧稿.html"]'),
@@ -45,7 +45,7 @@ Batch: up to 16 items, moved in order, stops at first failure.`,
     async ({ items, into, rewrite_refs: rewriteRefs }) => {
       const lines = [];
       const moves = [];
-      let moved = 0;
+      let moved = 0; let skipped = 0;
       for (const item of items) {
         try {
           const out = await moveEntry(projectId, item, into, { createFolder: true });
@@ -61,8 +61,22 @@ Batch: up to 16 items, moved in order, stops at first failure.`,
           }
         } catch (err) {
           const why = err instanceof MoveError ? err.message : (err?.message || String(err));
+          /**
+           * 重名（MoveError 409）**不中断整批**：目标夹里已经有个同名的，说明这件
+           * 大概率已经收过一遍了，它挡不住后面十几件。其余错误照旧即停。
+           *
+           * 真案 proj_mtg61or1 19:37，用户说"把素材都收到一块，别四处丢"，agent
+           * 一次收 12 件，第 1 件重名 → 后面 11 件全没动，暂存架自始至终没清过。
+           * 收纳这个动词本来就不是事务性的（前面搬成的不会回滚），中途停下只是
+           * 让人分不清搬到哪儿了。
+           */
+          if (err instanceof MoveError && err.status === 409) {
+            skipped += 1;
+            lines.push(`· ${item}：${why}（跳过，接着搬后面的）`);
+            continue;
+          }
           lines.push(`✗ ${item}：${why}`);
-          lines.push(`（后面 ${items.length - moved - 1} 件没动 —— 修正后重调）`);
+          lines.push(`（后面 ${items.length - moved - skipped - 1} 件没动 —— 修正后重调）`);
           break;
         }
       }

package/server/engine/mcp/tools/paint-still.js

@@ -398,7 +398,7 @@ breakage; do not burn high-detail on every frame.`,
         negative: z.string().optional().describe('overrides the per-model default; no-op for krea2'),
         size: z.string().regex(/^\d{3,4}x\d{3,4}$/).default('1344x768'),
         seed: z.number().int().optional().describe('omit for fresh random per still; batch uses seed, seed+1, ...'),
-        name: z.string().regex(/^[\w-]{1,40}$/).default('still'),
+        name: z.string().regex(/^[\w一-鿿぀-ヿ-]{1,40}$/).default('still'),
         batch: z.number().int().min(1).max(8).optional()
           .describe('variations of this same prompt in one pass (default 1). Use 4-8 to roll for a keeper.'),
         lora: z.string().optional()

package/server/engine/mcp/tools/pin-to-board.js

@@ -29,8 +29,11 @@ import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import path from 'path';
 import { promises as fs } from 'fs';
-import { pinToZone, readBoard } from '../../../projects/board-store.js';
+import { pinToZone, readBoard, patchBoard } from '../../../projects/board-store.js';
 import { layerOf } from '../../../lib/canvas-id.js';
+import { currentSheet, slotRectOf, nextSpotInSlot, placeAtOnSheet } from '../../../lib/board-sheets.js';
+import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
+import { currentSheetIdOf } from '../../../lib/sheet-state.js';
 
 // （folderOfObjectId 08-24 拆除：它按 dirname 硬算，会给 assets/generated 这类
 //  前端不当层渲染的路径发"层"标签 —— 改问 layerOf + board.zones，跟渲染同口径）
@@ -41,7 +44,7 @@ import { layerOf } from '../../../lib/canvas-id.js';
  * @param {string} [deps.projectId]
  * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
  */
-export function makePinToBoardTool({ sharedRoot, projectId, ctx }) {
+export function makePinToBoardTool({ sharedRoot, projectId, sessionId = null, ctx }) {
   return tool(
     'pin_to_board',
     `Bring an item to the front of the user's canvas, at a free spot in whatever
@@ -49,6 +52,9 @@ folder it lives in. The canvas is their desktop: whatever you write appears
 there automatically — you do NOT need this tool for your own outputs.
 Use it only to deliberately surface something:
 
+- Place a staged arrival: new files land on the staging shelf (the vertical
+  strip of unplaced cards the status block names) — pin_to_board{path, slot}
+  moves one into a block you planned
 - Pull a reference (an uploaded asset, a memory note, an older image) into view
 - Restore something the user dragged off-screen, when they ask for it back
 
@@ -65,8 +71,14 @@ Paths are workspace-relative, exactly as they are on disk. Accepted forms:
         .min(1)
         .max(300)
         .describe('Item to surface — see accepted forms in the tool description'),
+      slot: z.string().max(40).optional()
+        .describe('Drop it into a planned block on the current sheet (names from open_sheet / read_board). This is how a produced file lands where you planned it instead of wherever there was room.'),
+      at: z.object({ x: z.number(), y: z.number() }).optional()
+        .describe('Exact spot on the sheet, pixels from its top-left writable corner. Use slot unless this one file needs a precise place.'),
+      sheet: z.string().max(40).optional()
+        .describe('Which sheet (default: the one you are working on)'),
     },
-    async ({ path: rawPath }) => {
+    async ({ path: rawPath, slot, at, sheet }) => {
       try {
         if (!projectId) {
           return { content: [{ type: 'text', text: 'No project bound; cannot pin.' }], isError: true };
@@ -112,6 +124,69 @@ Paths are workspace-relative, exactly as they are on disk. Accepted forms:
         // dirname 硬算的老写法会把 assets/generated 当层写进 zone，arrange 就此拒摆
         const boardNow = await readBoard(projectId);
         const zoneId = layerOf(objectId, null, new Set(Object.keys(boardNow.zones || {})));
+
+        /**
+         * 点名落位（2026-08-30 刀 G）：`slot` / `at` 给了就走纸上落位，跟 write_on_board
+         * 同一套几何。这是「产物也由 agent 规划位置」的那只手 —— 暂存架上的东西，
+         * agent 规划出地方之后就用它请下来（seat 改写成 agent，自然离架）。
+         */
+        if (slot || at) {
+          const sh = (sheet && boardNow.sheets?.[sheet])
+            ? { id: sheet, ...boardNow.sheets[sheet] }
+            : currentSheet(boardNow, currentSheetIdOf(sessionId));   // 会话正写的那张优先
+          if (!sh) {
+            return { content: [{ type: 'text', text: 'No sheet yet — open_sheet first (plan the page, then place things into its blocks).' }], isError: true };
+          }
+          const box = estimateSizeOn(boardNow, objectId, boardNow.objects?.[objectId] || null);
+          let spot = null; let where = '';
+          if (slot) {
+            const rect = slotRectOf(sh, slot);
+            if (!rect) {
+              const names = Object.keys(sh.slots || {});
+              return { content: [{ type: 'text', text: names.length
+                ? `Sheet ${sh.id} has no slot "${slot}". It has: ${names.join(', ')}.`
+                : `Sheet ${sh.id} has no slots planned. Plan the page first: open_sheet{plan:[{slot,at,w,h,about}…]}.` }], isError: true };
+            }
+            const p = nextSpotInSlot(boardNow, rect, box);
+            if (p.full) {
+              return { content: [{ type: 'text', text: `⛔ Slot "${slot}" on sheet ${sh.id} is full — ${objectId} needs ${box.h}px, ~${p.freeH}px left. `
+                + 'Nothing moved. Re-plan the page with a taller block, or point it at another slot.' }], isError: true };
+            }
+            spot = p; where = ` in slot "${slot}"`;
+          } else {
+            const p = placeAtOnSheet(sh, at, box);
+            spot = p; where = p.clamped ? ' (clamped into the sheet)' : '';
+          }
+          /**
+           * ⛔ 摆到纸上 = 摆到**根层**，zone 必须写 ''（不是文件所在的文件夹层）。
+           *
+           * spot 是 nextSpotInSlot 在根层纸矩形里算出来的**世界坐标**；zone 写成
+           * 文件夹层的话，这两个字段当场互相矛盾：前端 dirOf 按 zone 把它渲染进
+           * 那个文件夹里（世界坐标在那儿是没意义的局部坐标），根层画布上根本
+           * 看不见它 —— 而工具还报了「Placed on sheet p3 in slot refs at (24,2941)」。
+           *
+           * 更实的后果：rootObjects 只收根层，membersInRect 跟着看不见它，于是
+           * **下一件 pin 进同一个版位的东西算出来还是同一个坐标**。真案
+           * proj_mtg61or1 19:18 连 pin 五张官方参考图，后四张全落 (24,3405)，
+           * 工具四次都报 success。对照组（同样五张放根层）落点正常且装不下时
+           * 如实报「版位满」。
+           *
+           * 把文件夹里的文件 pin 到纸上，语义就是把它拎到桌面上摆着 —— 跟用户
+           * 从文件夹里拖一张卡出来是同一件事（前端注释：拖出来的写 ''）。
+           */
+          const prev = boardNow.objects?.[objectId] || {};
+          const nextPending = (boardNow.pending || []).filter(r => r !== objectId && `deck:${r}` !== objectId && `site:${r}` !== objectId);
+          await patchBoard(projectId, {
+            objects: { [objectId]: { ...prev, x: Math.round(spot.x), y: Math.round(spot.y), w: Math.round(box.w), h: Math.round(box.h), zone: '', seat: 'agent' } },
+            ...(nextPending.length !== (boardNow.pending || []).length ? { pending: nextPending } : {}),
+          });
+          try {
+            ctx?.emit?.({ type: 'board.updated', sessionId: null, objectId, zoneId: '', summary: `已把 ${objectId} 摆到 ${sh.id}${where}` });
+          } catch { /* emit fail-safe */ }
+          return { content: [{ type: 'text', text: `Placed ${objectId} on sheet ${sh.id}${where} at (${Math.round(spot.x)}, ${Math.round(spot.y)}).`
+            + (nextPending.length !== (boardNow.pending || []).length ? ` It is no longer waiting for a spot (${nextPending.length} still are).` : '') }] };
+        }
+
         const { zone: placedZone, placed } = await pinToZone(projectId, { objectId, zoneId });
 
         try {

package/server/engine/mcp/tools/read-board.js

@@ -16,47 +16,57 @@ import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import { readBoard } from '../../../projects/board-store.js';
 import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
-import { layerOf } from '../../../lib/canvas-id.js';
+import { layerOf, bareTag } from '../../../lib/canvas-id.js';
 import { relationsDigest, bindingLine } from '../../../lib/board-relations.js';
 import { groupObjects, asciiMinimap, bboxOfRects, relationOf, columnsOf, viewportRelation } from '../../../lib/board-groups.js';
+import { laneSummaries } from '../../../lib/board-lanes.js';
+import { capacityOf, DEFAULT_CHALK_W } from '../../../lib/sketch-layout.js';
+import { sheetSummaries, rollCardRect, slotRectOf, nextSpotInSlot, freeColumnsInSheet, latestSheetId } from '../../../lib/board-sheets.js';
 import { getViewpoint } from '../../../projects/viewpoint-store.js';
 import { chalkExcerpts, CHALK_DIR } from '../../../lib/chalk.js';
 import { getSharedDir } from '../../../projects/workspace.js';
 import { promises as fs } from 'node:fs';
+import { byOf, describeBy } from '../actor.js';
+import { listRoleNames } from '../../agent/role-card.js';
 import path from 'node:path';
 
 /** 同一"行"的 y 容差：入座算法一行内顶对齐，40 世界像素内视作同行 */
 const ROW_TOLERANCE = 40;
 
-function describeEntry(board, id, entry, glyph = null, excerpts = null, staleIds = null) {
+function describeEntry(board, id, entry, glyph = null, excerpts = null, staleIds = null, view = null) {
+  // view = { by: 当前读者, names: slug→展示名 }。读 read_board 的可能是主 agent，
+  // 也可能是常驻角色 —— 同一句「你写的」对两个读者含义相反，所以称呼要带视角。
+  const who = (b) => describeBy(b || 'agent', view?.by || 'agent', view?.names);
+  const mine = (b) => (b || 'agent') === (view?.by || 'agent');
   const sz = estimateSizeOn(board, id, entry);
   const at = `@(${Math.round(entry.x)},${Math.round(entry.y)}) ${Math.round(sz.w)}x${Math.round(sz.h)}`;
   const g = glyph ? `[${glyph}] ` : '';
   const flags = `${entry.staging ? ' 〔草稿〕' : ''}${entry.tag ? ` #${entry.tag}` : ''}`;
   const ch = excerpts?.get(id);
-  if (ch) return `- ${g}[板书·${ch.by === 'user' ? '用户' : '你'}写的] 「${ch.first}」 ${at} (path: ${id})${ch.anchor ? ` 关于 ${ch.anchor}` : ''}${ch.replyTo ? ` 回应 ${ch.replyTo}` : ''}${flags}`;
+  if (ch) return `- ${g}[板书·${who(ch.by)}写的] 「${ch.first}」 ${at} (path: ${id})${ch.anchor ? ` 关于 ${ch.anchor}` : ''}${ch.replyTo ? ` 回应 ${ch.replyTo}` : ''}${flags}`;
   if (entry.kind === 'text') {
     const t = String(entry.data?.t || '').replace(/\s+/g, ' ').slice(0, entry.data?.format === 'md' ? 60 : 24);
     const md = entry.data?.format === 'md' ? 'md' : '手写';
-    return `- ${g}[${md}] 「${t}」 ${at} (id: ${id})${entry.by === 'agent' ? ' ·你写的' : ''}${flags}`;
+    return `- ${g}[${md}] 「${t}」 ${at} (id: ${id})${entry.by ? ` ·${who(entry.by)}写的` : ''}${flags}`;
   }
-  if (entry.kind === 'scribble') return `- ${g}[涂鸦] ${at} (id: ${id})${entry.by === 'agent' ? ' ·你画的' : ''}${flags}`;
+  if (entry.kind === 'scribble') return `- ${g}[涂鸦] ${at} (id: ${id})${entry.by ? ` ·${who(entry.by)}画的` : ''}${flags}`;
   // 过期座位要明说（iss_mt38ucyq：旧路径条目被 agent 当"失效卡"差点建议删素材母版）
   const stale = staleIds?.has(id) ? ' 〔⚠️磁盘上已无此路径 —— 多半被移动/改名了，以磁盘为准，别据此判失效或建议删除〕' : '';
-  return `- ${g}${id} ${at}${entry.by === 'agent' ? ' ·你摆的' : ''}${flags}${stale}`;
+  return `- ${g}${id} ${at}${entry.by ? ` ·${who(entry.by)}摆的` : ''}${flags}${stale}`;
+  // eslint-disable-next-line no-unused-vars -- mine 留给后续按视角过滤用
 }
 
-export function makeReadBoardTool({ projectId }) {
+export function makeReadBoardTool({ projectId, sharedRoot = null }) {
   return tool(
     'read_board',
     `Read the workbench canvas: an ASCII minimap, then GROUPS (things linked by lines or
 sharing a #tag), then loose items row by row, then relation lines.
 
-Use this BEFORE arranging (arrange_on_board), writing notes (create_on_board) or
-sketching (sketch_on_board) — placement without looking is guessing. Coordinates are
-world pixels. Only seated items appear (fresh artifacts get a seat within a second).
+Use this BEFORE moving things (edit_board) or writing/sketching (write_on_board) —
+placement without looking is guessing. Coordinates are world pixels. Only seated items
+appear (files you just wrote are seated automatically within a couple of seconds).
 Items marked 〔草稿〕 are still staging (yours from this turn, half-transparent until
-finish_sketch / end of turn). The user's current viewport (if known) is drawn as a box
+edit_board commit / end of turn). The user's current viewport (if known) is drawn as a box
 on the minimap and listed with what is inside it.`,
     {
       layer: z.string().max(300).optional()
@@ -65,7 +75,11 @@ on the minimap and listed with what is inside it.`,
         .describe('Only list items/lines carrying this #tag (one group, e.g. a sketch you made)'),
       minimap: z.boolean().optional().describe('Also print an ASCII minimap (off by default — the relative-position summary is usually enough)'),
     },
-    async ({ layer, tag, minimap }) => {
+    async ({ layer, tag: rawTag, minimap }, extra) => {
+      const tag = rawTag ? bareTag(rawTag) : rawTag;   // #状态板 也认（查询侧统一剥 #）
+      // 视角：谁在读这块板。常驻角色读到自己写的板书才该显示「你写的」，
+      // 读到别人的显示那个人的名字（展示名只是渲染，判断一律用 slug）。
+      const view = { by: byOf(extra), names: await listRoleNames(sharedRoot) };
       if (!projectId) {
         return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
       }
@@ -86,6 +100,9 @@ on the minimap and listed with what is inside it.`,
       const excerpts = await chalkExcerpts(getSharedDir(projectId), (byLayer.get(want) || []).map(it => it.id));
       const items = (byLayer.get(want) || [])
         .filter(({ entry }) => !tag || entry.tag === tag)
+        // 收卷（2026-08-27 收纳器）：收着的组不逐件列 —— 版图里压成一行，这是 agent
+        // 上下文的收纳（跟画布收纳同一刀）。显式 tag= 点名看某组时照常展开列。
+        .filter(({ entry }) => tag || !entry.tag || !board.rolls?.[entry.tag])
         // 板书条目但文件已经没了 = 幽灵座位，别列给 agent（删文件那条路会清座位，这是兜底）
         .filter(({ id }) => !id.startsWith(`${CHALK_DIR}/`) || excerpts.has(id))
         .sort((a, b) => (a.entry.y - b.entry.y) || (a.entry.x - b.entry.x));
@@ -143,7 +160,7 @@ on the minimap and listed with what is inside it.`,
           lines.push('', `组 ${i + 1}${tags ? ` ${tags}` : ''}（${g.members.length} 件 ${g.edges.length} 线${staging ? '，草稿' : ''}）：`);
           const sorted = g.members.map(id => ({ id, entry: entryOf.get(id) }))
             .sort((a, b) => (a.entry.y - b.entry.y) || (a.entry.x - b.entry.x));
-          for (const { id, entry } of sorted) lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts, staleIds));
+          for (const { id, entry } of sorted) lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts, staleIds, view));
           for (const bid of g.edges.slice(0, 12)) lines.push(`    ${bindingLine(board.bindings[bid], board)} (line id: ${bid})`);
           if (g.edges.length > 12) lines.push(`    …还有 ${g.edges.length - 12} 条线`);
         });
@@ -161,7 +178,7 @@ on the minimap and listed with what is inside it.`,
               rowY = entry.y;
               lines.push(`— 行 y≈${Math.round(rowY)} —`);
             }
-            lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts, staleIds));
+            lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts, staleIds, view));
           }
         }
       }
@@ -174,7 +191,82 @@ on the minimap and listed with what is inside it.`,
           }).join('、')}`);
         }
       }
-      if (board.hero && !tag) lines.push('', `★ 显式主角：${board.hero}（arrange_on_board 的 feature/unfeature 管它）`);
+      if (board.hero && !tag) lines.push('', `★ 显式主角：${board.hero}（edit_board 的 feature/unfeature 管它）`);
+
+      // 纸的清单（2026-08-29 纸范式）：agent 的空间账本 —— 每张纸的名字/位置/件数/
+      // 剩余空地。at 坐标以当前纸版心左上为原点，这一节就是坐标系的地图。
+      if (!want && !tag) {
+        try {
+          const ss = sheetSummaries(board);
+          if (ss.length) {
+            const latest = latestSheetId(board);
+            lines.push('', '纸（sheet）：at:{x,y} 写的是纸内像素（版心左上为原点）。'
+              + '**写满不会自动翻页** —— 排不下时写入被拒收，下一页由你自己 open_sheet 规划：');
+            for (const s of ss) {
+              // 剩多少地方按**字**报（08-29 刀 D）：agent 手里的东西是字，
+              // 只给像素等于让它每次落笔前做一道做不准的算术
+              const cap = capacityOf(DEFAULT_CHALK_W, s.freeH);
+              lines.push(`  ${s.id}${s.id === latest ? '（当前）' : ''}${s.title ? `（${s.title}）` : ''}：世界 (${s.x},${s.y}) ${s.w}x${s.h}，${s.count} 件，剩 ~${s.freeH}px 高（≈${cap.lines} 行 / ${cap.cjk} 字）${s.lastId ? `，最新 ${s.lastId}` : ''}`);
+              // 规划过的块各剩多少（08-29 刀 E）：填到一半要知道还有哪块地是空的，
+              // 不然只能靠猜 —— 猜错的下场是写入被拒收，白跑一趟
+              // 这张纸还剩哪些空地（08-29 刀 F）：只报"最后一件下面剩多少"是不够的 ——
+              // 那一列到底了不等于这张纸满了，右边可能整片空着，而 agent 要靠这个
+              // 判断"还放不放得下、要不要开新一页"
+              const free = freeColumnsInSheet(board, s.id);
+              if (free.length > 1) {
+                const cells = free.map((f) => `x=${f.x} 剩 ${capacityOf(DEFAULT_CHALK_W, f.freeH).lines} 行`);
+                lines.push(`    空地：${cells.join(' / ')}`);
+              }
+              const sheet = board.sheets?.[s.id];
+              for (const [nm, sl] of Object.entries(sheet?.slots || {})) {
+                const r = slotRectOf({ ...sheet, id: s.id }, nm);
+                const spot = nextSpotInSlot(board, r, { w: 1, h: 1 });
+                const freeH = spot.full ? 0 : Math.max(0, r.y + r.h - spot.y);
+                const c = capacityOf(r.w, freeH);
+                lines.push(`    · ${nm}${sl.about ? `（${sl.about}）` : ''}${sl.for === 'artifacts' ? '【收产物】' : ''}：块内 (${sl.x},${sl.y}) ${sl.w}x${sl.h}，剩 ≈${c.lines} 行 / ${c.cjk} 字`);
+              }
+            }
+          }
+          // 暂存架（2026-08-30）：机器到货的默认座 —— 上了墙但还没进版面，等 agent 安置
+          const shelf = Object.entries(board.objects || {})
+            .filter(([, e]) => e?.seat === 'shelf' && !e.zone && Number.isFinite(e?.x))
+            .map(([id]) => id);
+          const pend = Array.isArray(board.pending) ? board.pending : [];
+          const unplaced = [...shelf, ...pend];
+          if (unplaced.length) {
+            lines.push('', `📦 暂存架上 ${unplaced.length} 件等安置（机器只码在架上，版面归你）：`);
+            for (const r of unplaced.slice(0, 8)) lines.push(`  ${r}`);
+            if (unplaced.length > 8) lines.push(`  …还有 ${unplaced.length - 8} 件`);
+            lines.push('  安置的手：open_sheet{plan:[{slot:"图",at:{…},w,h,for:"artifacts"}…]} 规划产物地，'
+              + '或逐件 pin_to_board{path,slot} / edit_board{ops:[{op:"move",…}]}。');
+          }
+        } catch { /* 纸读不出不挡座次 */ }
+      }
+
+      // 版图（2026-08-27 空间规划）：线 = 同 tag 的纵列。这是 agent 的符号地图 ——
+      // 摆放按关系（续哪条线/岔自哪条）声明，几何机器排，别按坐标猜。
+      if (!tag) {
+        const laneList = laneSummaries(board);
+        if (laneList.length) {
+          lines.push('', '线的清单（一条线 = 同一个 tag 的一纵列；{tag,chain:true} 接着写，open_lane 开新的一条）：');
+          for (const l of laneList) {
+            // 收着的线一行带过：细节不进上下文（要看就 read_board tag= 点名，或 unroll）
+            const roll = board.rolls?.[l.tag];
+            if (roll) {
+              const rc = rollCardRect(board, l.tag);
+              lines.push(`  #${l.tag}：已收卷${roll.label ? `（「${roll.label}」）` : ''}，${l.count} 件收在卷里`
+                + `${rc ? `，卷卡占位约 @(${rc.x},${rc.y}) ${rc.w}x${rc.h}` : ''}`
+                + ` —— 座位和文件都在（Read 照常），edit_board unroll 展开；别往收着的线里接新话`);
+              continue;
+            }
+            const dirTxt = '';
+            lines.push(l.registered
+              ? `  #${l.tag}：${l.count} 节${l.parent ? `，岔自 ${l.parent}` : ''}，列头 (${l.x},${l.y})`
+                + `${l.frontier ? `，接着写会落 (${l.frontier.x},${l.frontier.y}) 附近` : ''}${l.lastId ? `，最新 ${l.lastId}` : ''}${dirTxt}`
+              : `  #${l.tag}：${l.count} 件（未登记的野线 —— chain:true 照样能续）${dirTxt}`);
+          }
+        }
+      }
 
       // 用户视点（有上报才有）
       if (vp && !tag) {
@@ -197,7 +289,8 @@ on the minimap and listed with what is inside it.`,
         } catch { /* 关系读不到不挡座次 */ }
       }
 
-      lines.push('', '（口径：稀疏表只列摆过的；层归属为服务端近似；尺寸为形态估算；带⚠️的条目=座位与磁盘对不上账）');
+      lines.push('', '（口径：稀疏表只列摆过的；层归属为服务端近似；尺寸=存档真值优先、缺了按形态估；'
+        + '角色精灵贴着该角色最新一条板书（那条四周留了 60px 身位）；带⚠️的条目=座位与磁盘对不上账）');
       return { content: [{ type: 'text', text: lines.join('\n') }] };
     },
   );