@xiaobuyu/nodesign 0.0.6 → 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,13 +9,15 @@
  * 实现 = **和用户拖拽「移动到…」同一份核心**（projects/move-entry.js）：
  * 磁盘先行、画布身份同步、转发表记账，一个字不重写。
  *
- * 批量制（同 roll_film / paint_still）：≤16 件、串行、**中途失败即停**
- * （后面的不动，报告哪件停的）。目标夹不存在就建 —— 归纳常配新夹。
+ * 批量制（同 roll_film / paint_still）：≤16 件、串行。**重名跳过、其余即停**
+ * （停了就报哪件停的，后面的不动）。目标夹不存在就建 —— 归纳常配新夹。
  */
 
 import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import { moveEntry, MoveError } from '../../../projects/move-entry.js';
+import { rewriteWorkspaceRefs } from '../../../lib/rewrite-refs.js';
+import { getSharedDir } from '../../../projects/workspace.js';
 import { Events } from '../../agent/events.js';
 
 export function makeOrganizeBoardTool({ projectId, ctx }) {
@@ -26,20 +28,29 @@ export function makeOrganizeBoardTool({ projectId, ctx }) {
 Use for: grouping generated images into a folder, collecting a site's materials into <site>/assets/, un-cluttering the desktop root. Sticky notes (notes/*.md) may move too, but they become plain .md file cards outside notes/ — lose the flippable sticky form.
 Not for: site roots as destination (they are artifacts, not storage — a site takes materials in its assets/ subfolder).
 
-Batch: up to 16 items, moved in order, stops at first failure.`,
+After moving, references across the workspace (src/href in html/css/md pointing
+at the moved items) are rewritten to the new paths automatically — the count of
+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. 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"]'),
       into: z.string()
         .describe('Destination folder (workspace-relative), e.g. "素材" or "观察日志/assets". Created if missing. "" = workspace root (un-nest).'),
+      rewrite_refs: z.boolean().optional()
+        .describe('Also rewrite references to the moved items across workspace text files (default true).'),
     },
-    async ({ items, into }) => {
+    async ({ items, into, rewrite_refs: rewriteRefs }) => {
       const lines = [];
-      let moved = 0;
+      const moves = [];
+      let moved = 0; let skipped = 0;
       for (const item of items) {
         try {
           const out = await moveEntry(projectId, item, into, { createFolder: true });
           moved += 1;
+          if (out.moved) moves.push({ from: out.from, to: out.to });
           lines.push(out.moved ? `✓ ${out.from} → ${out.to}` : `· ${out.from}（已在原地）`);
           if (out.moved) {
             try {
@@ -50,11 +61,39 @@ 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;
         }
       }
+      // 「新建文件夹然后改个索引」的后半件（iss_mt38uih6）：把全工作区指向
+      // 被搬条目的引用改到新路径。改了多少处逐文件上报 —— 自动改写用户内容
+      // 必须可核对；报 0 也说一声，agent 不用再自己 grep。
+      if (moves.length > 0 && rewriteRefs !== false) {
+        try {
+          const rw = await rewriteWorkspaceRefs(getSharedDir(projectId), moves);
+          lines.push(rw.hits > 0
+            ? `引用改写：${rw.hits} 处 / ${rw.files} 个文件`
+            : '引用改写：全工作区没有指向这些条目的文本引用（0 处）');
+          lines.push(...rw.lines.slice(0, 12));
+        } catch (err) {
+          lines.push(`⚠️ 引用改写失败（文件已搬成，引用要自己 grep 修）：${err?.message || err}`);
+        }
+      }
       try {
         if (moved > 0) ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `归纳了 ${moved} 件到 ${into || '桌面根'}` });
       } catch { /* fail-soft */ }

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

@@ -8,7 +8,6 @@
  *   - 普通文件（图片 / 便签 / 数据）：路径本身，`assets/generated/a.webp`
  *   - deck：`deck:<路径>`，如 `deck:稿件/主稿.html`
  *   - 站点：`site:<目录>`
- *   - 项目文档：`doc:_root`（记忆）/ `doc:brand`（品牌档案）
  *
  * ## 2026-08-13：这个工具的职权范围缩小了
  *
@@ -30,16 +29,14 @@ import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import path from 'path';
 import { promises as fs } from 'fs';
-import { pinToZone } 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';
 
-/** 物件 id → 它住在哪个文件夹（与前端 stage.js 的 zoneOfObjectId 同一套规则） */
-function folderOfObjectId(objectId) {
-  if (objectId.startsWith('doc:')) return '';
-  const c = objectId.indexOf(':');
-  const p = (c > 0 && /^[a-z]+$/.test(objectId.slice(0, c))) ? objectId.slice(c + 1) : objectId;
-  const i = p.lastIndexOf('/');
-  return i > 0 ? p.slice(0, i) : '';
-}
+// （folderOfObjectId 08-24 拆除：它按 dirname 硬算，会给 assets/generated 这类
+//  前端不当层渲染的路径发"层"标签 —— 改问 layerOf + board.zones，跟渲染同口径）
 
 /**
  * @param {object} deps
@@ -47,7 +44,7 @@ function folderOfObjectId(objectId) {
  * @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
@@ -55,7 +52,10 @@ 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:
 
-- Pull a reference (an uploaded asset, the brand doc, an older image) into view
+- 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
 
 This does NOT change which folder the item belongs to — that is decided by
@@ -64,16 +64,21 @@ where the file is on disk. To move it, \`mv\` the file; the canvas follows.
 Paths are workspace-relative, exactly as they are on disk. Accepted forms:
 - any file path: 'assets/generated/hero.webp', 'notes/灵感.md', '稿件/数据.csv'
 - a deck: 'deck:<path>.html'   a site: 'site:<dir>'
-  (a bare '<path>.html' is read as a deck)
-- '.claude/agent-memory/memory.md' (project memory) / '.../brand/memory.md' (brand doc)`,
+  (a bare '<path>.html' is read as a deck)`,
     {
       path: z
         .string()
         .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 };
@@ -84,9 +89,7 @@ Paths are workspace-relative, exactly as they are on disk. Accepted forms:
         if (!objectId || objectId.includes('..')) {
           return { content: [{ type: 'text', text: 'Invalid path.' }], isError: true };
         }
-        if (objectId.endsWith('agent-memory/brand/memory.md')) objectId = 'doc:brand';
-        else if (objectId.endsWith('agent-memory/memory.md')) objectId = 'doc:_root';
-        else if (!/^(deck|site|doc):/.test(objectId)) {
+        if (!/^(deck|site):/.test(objectId)) {
           // 裸路径：.html 是一份 deck，其余（图片 / 便签 / 数据文件）id 就是路径。
           // 站点的目录要显式写 `site:` —— 光看路径分不出
           // "一个收纳文件夹"和"一件目录型产物"，猜错了钉上去的是个不存在的 id。
@@ -102,7 +105,88 @@ Paths are workspace-relative, exactly as they are on disk. Accepted forms:
           if (/\.html?$/i.test(objectId)) objectId = `deck:${objectId}`;
         }
 
-        const zoneId = folderOfObjectId(objectId);
+        // 可见性预检（08-21 案：钉 assets/ 深处的图报成功，用户画布上根本没有）。
+        // 画布扫描只认 assets 顶层 / assets/generated / assets/notes 这三个口，
+        // 更深的（references/web/… 之类）有座位也不渲染 —— 钉了等于没钉。
+        if (/^assets\//.test(objectId)
+          && !/^assets\/[^/]+$/.test(objectId)
+          && !/^assets\/(generated|notes)\/[^/]+$/.test(objectId)) {
+          return {
+            content: [{
+              type: 'text',
+              text: `${objectId} 在画布扫描范围之外（assets/ 只有顶层、generated/、notes/ 三个口上墙），pin 了用户也看不到。`
+                + '先把文件 cp 到工作区根或某个文件夹里再 pin（用户要看的素材放看得见的地方）。',
+            }],
+            isError: true,
+          };
+        }
+        // 层归属按**真实存在的层**算（'' 或 zones 里的文件夹）——跟前端渲染同口径。
+        // 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 {