@xiaobuyu/nodesign 0.0.6 → 0.0.7

package/server/engine/mcp/tools/helpers/codex-imagegen.js

@@ -0,0 +1,139 @@
+/**
+ * helpers/codex-imagegen.js — codex 生图桥的 prompt 组装 + 子进程执行
+ * （2026-08-24 从 generate-image.js 迁出：给棘轮腾行 + prompt 组装层归位一处）
+ *
+ * 两层各管一事：
+ *   - buildVariationPrompt：变体模式（variationOf）的 prompt 骨架。把"要保持的
+ *     东西逐项列出"从 agent 手写咒语变成参数 —— 32 张换装立绘实战里，漏写一项
+ *     （袜子）整行就坏，这套骨架把踩过的坑固化成默认禁止项。
+ *   - buildCodexBridgePrompt / runCodexImageGen：codex CLI 桥（原样迁出，
+ *     仅第 3 条在变体模式下改口径：参考图第 1 张是编辑基底，不是风格参照）。
+ */
+
+import fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+
+export const CODEX_BIN = process.env.NODESIGN_CODEX_BIN || 'codex';
+export const CODEX_IMAGE_TIMEOUT_MS = Number(process.env.NODESIGN_CODEX_IMAGE_TIMEOUT_MS) || 240_000;
+
+/**
+ * 变体模式的 preserve 词表。键是 agent 传的枚举值，值是展开进 prompt 的英文短语。
+ * 短语必须把"缺席也是要保持的"写死（no socks 的参考图，结果也必须 no socks）——
+ * 这是实战里最容易漂的一类。
+ */
+export const PRESERVE_PHRASES = {
+  pose: 'the exact same pose and body position',
+  framing: 'the same framing, camera distance and position of the subject in the frame',
+  proportions: 'the same height and body proportions',
+  face: 'the same face and the same expression',
+  hair: 'the same hairstyle and hair color',
+  hands: 'the same hand positions, holding the same things (empty hands stay empty)',
+  top: 'the same top garment — identical cut, color, sleeves, neckline and every detail',
+  bottom: 'the same bottom garment (skirt / trousers) — identical in every detail',
+  shoes: 'the same footwear, identical in every detail',
+  socks: 'the same socks / legwear (if the reference has none, the result has none)',
+  accessories: 'the same accessories — nothing added, nothing removed',
+  background: 'the same background',
+  lighting: 'the same lighting and color grading',
+  style: 'the same art style and rendering technique',
+};
+export const PRESERVE_KEYS = Object.keys(PRESERVE_PHRASES);
+
+// 不论 preserve 传什么都追加的通用军规 —— 全部是真实翻过车的：凭空长出背带、
+// 白袜整行消失、取景悄悄拉近。
+const VARIATION_HARD_RULES = [
+  'Do NOT invent anything that is not in the reference: no added straps, suspenders,'
+  + ' belts, hair ornaments, jewelry or extra garments.',
+  'Absences are part of the reference: whatever the reference does not have, the result must not have.',
+  'Do NOT change the subject\'s height, body proportions, or position in the frame.',
+].join('\n');
+
+/**
+ * variationOf 模式：把 change + preserve 展开成"只改一处、其余照搬"的固定骨架。
+ * @param {object} o
+ * @param {string} o.change     唯一要改的那一处（自然语言）
+ * @param {string[]} [o.preserve]  PRESERVE_KEYS 的子集；缺省 = 全部
+ * @param {string} [o.extra]    附注（agent 想额外说明的，放在骨架之后）
+ */
+export function buildVariationPrompt({ change, preserve, extra }) {
+  const keys = (preserve && preserve.length > 0) ? preserve : PRESERVE_KEYS;
+  const phrases = keys.map((k) => PRESERVE_PHRASES[k]).filter(Boolean);
+  return [
+    'Reproduce the reference illustration (the first reference image) with ONE single change.',
+    `THE ONLY CHANGE: ${change}`,
+    `Everything else must be identical to the reference: ${phrases.join('; ')}.`,
+    VARIATION_HARD_RULES,
+    ...(extra ? [extra] : []),
+  ].join('\n');
+}
+
+/**
+ * codex 桥接 prompt。必须写死"逐字传递零改写"——codex agent 默认会按自己的
+ * Augmentation rules 润色 prompt。变体模式下第 3 条改口径：第 1 张参考图是
+ * **编辑基底**，必须除指定改动外逐细节复现（"风格参照"的软口径会被当成
+ * style reference，收敛不住）。
+ */
+export function buildCodexBridgePrompt({ prompt, aspectRatio, absOut, refCount, variation = false }) {
+  let refLine;
+  if (refCount > 0 && variation) {
+    refLine = `3. 本消息附带 ${refCount} 张参考图。第 1 张是**编辑基底**：除 <image-prompt> 指定的那一处改动外，`
+      + '必须逐细节复现它的全部内容；其余参考图（如有）才是风格 / 一致性参照。';
+  } else if (refCount > 0) {
+    refLine = `3. 本消息附带 ${refCount} 张参考图，把它们作为图像生成的参考输入（风格 / 主体一致性参照）。`;
+  } else {
+    refLine = '3. 本次无参考图。';
+  }
+  return [
+    '你是图像生成管道的执行端，只做下面几件事，不做任何多余动作：',
+    '1. 调用你的图像生成工具生成一张图。<image-prompt> 标签内的内容必须逐字作为生成 prompt，禁止改写、增删、翻译或润色。',
+    `2. 输出比例：${aspectRatio}。优先用工具的比例/尺寸参数；工具没有对应参数时，作为补充说明传给工具，但不修改 <image-prompt> 原文。`,
+    refLine,
+    `4. 生成后把图片文件复制到精确路径 ${absOut}（目录已存在）。`,
+    '5. 最后只回复该绝对路径。',
+    '<image-prompt>',
+    prompt,
+    '</image-prompt>',
+  ].join('\n');
+}
+
+/**
+ * 跑一次 codex exec 生图，以目标文件落盘为成功标准（codex 的文本回复不可信），
+ * 失败自动重试一次。abort signal / 超时都 SIGKILL 子进程。
+ */
+export async function runCodexImageGen({ bridgePrompt, refPaths, cwd, signal, expectFile, timeoutMs = CODEX_IMAGE_TIMEOUT_MS }) {
+  const args = ['exec', '--skip-git-repo-check', '-s', 'workspace-write', '-C', cwd, bridgePrompt];
+  for (const p of refPaths) args.push('-i', p);
+
+  const runOnce = () => new Promise((resolve, reject) => {
+    const child = spawn(CODEX_BIN, args, { stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+    let stderrTail = '';
+    child.stdout.on('data', () => { /* 排空防背压 */ });
+    child.stderr.on('data', (d) => { stderrTail = (stderrTail + d.toString()).slice(-2000); });
+    const killTimer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch { /* */ }
+      reject(new Error(`codex exec timeout after ${Math.round(timeoutMs / 1000)}s`));
+    }, timeoutMs);
+    const onAbort = () => { try { child.kill('SIGKILL'); } catch { /* */ } };
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+    child.on('error', (err) => { clearTimeout(killTimer); reject(err); });
+    child.on('close', (code) => {
+      clearTimeout(killTimer);
+      signal?.removeEventListener?.('abort', onAbort);
+      if (signal?.aborted) return reject(new Error('aborted'));
+      if (code !== 0) return reject(new Error(`codex exec exited ${code}: ${stderrTail.slice(-300) || 'no stderr'}`));
+      resolve();
+    });
+  });
+
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    try {
+      await runOnce();
+      const st = await fs.stat(expectFile).catch(() => null);
+      if (st && st.size > 0) return;
+      throw new Error(`codex finished but target file missing/empty: ${expectFile}`);
+    } catch (err) {
+      if (attempt === 2 || signal?.aborted) throw err;
+      console.warn(`[generate-image] codex attempt ${attempt} failed (${err.message}), retrying once`);
+    }
+  }
+}

package/server/engine/mcp/tools/helpers/rembg.js

@@ -39,13 +39,18 @@ export const REMBG_SETUP_HINT = IS_WIN
   : 'cd server && python3 -m venv .venv-rembg && .venv-rembg/bin/python3 -m pip install rembg onnxruntime';
 const DEFAULT_PYTHON = REMBG_VENV_PYTHON;
 const DEFAULT_HELPER = path.join(__dirname, 'rembg-bridge.py');
-const DEFAULT_SOCKET = '/tmp/nodesign-rembg.sock';
 // fallback spawn 的 timeout——首次冷启 + 模型 load 留余量
 const DEFAULT_FALLBACK_TIMEOUT_MS = 60_000;
 
 function resolvePython() { return process.env.NODESIGN_REMBG_PYTHON || DEFAULT_PYTHON; }
 function resolveHelper() { return process.env.NODESIGN_REMBG_HELPER || DEFAULT_HELPER; }
-function resolveSocket() { return process.env.NODESIGN_REMBG_SOCKET || DEFAULT_SOCKET; }
+// socket 默认按**端口**派生（08-24 案：prod/exp 共用一个默认路径，exp 启动把生产的
+// 抠图服务当 stale 杀掉再自己占坑）。端口一实例一个，是现成的实例身份。
+// 这里是全仓唯一一份真相源，rembg-launcher.js import 它。
+export function resolveRembgSocket() {
+  return process.env.NODESIGN_REMBG_SOCKET || `/tmp/nodesign-rembg-${process.env.PORT || '4001'}.sock`;
+}
+function resolveSocket() { return resolveRembgSocket(); }
 
 // service health check 缓存（避免每次 request 都探一遍 /health）
 let serviceHealthCache = { ok: false, checkedAt: 0 };

package/server/engine/mcp/tools/helpers/shot-pipeline.js

@@ -278,3 +278,112 @@ export async function runBeforeShot(page, beforeShot) {
     return `beforeShot error: ${err?.message || err}`;
   }
 }
+
+/**
+ * 带兜底的整页/裁剪截图（iss_mt6tru7p：WebGL 持续动画页 + device:'mobile' 下
+ * page.screenshot 等稳定帧/字体 30s 必超时——rAF 每帧都在重绘，"稳定"永远
+ * 等不到）。先给 playwright 一次机会（15s，够正常页），超时改走 CDP
+ * Page.captureScreenshot：**抓当前帧不等任何东西**。持续动画页抓哪一帧都是
+ * 对的——它本来就没有"稳定帧"这回事。
+ *
+ * @returns {Promise<{buf: Buffer, degraded: boolean}>} degraded=true 走了 CDP 兜底
+ */
+export async function shotWithFallback(page, opts = {}) {
+  try {
+    return { buf: await page.screenshot({ ...opts, timeout: 15_000 }), degraded: false };
+  } catch (err) {
+    if (!/Timeout/i.test(String(err?.message))) throw err;
+    const cdp = await page.context().newCDPSession(page);
+    try {
+      const params = { format: 'png', captureBeyondViewport: !!opts.fullPage };
+      // CDP 的 clip：captureBeyondViewport 下是文档坐标，与我们 fullPage+clip 的语义一致
+      if (opts.clip) params.clip = { x: opts.clip.x, y: opts.clip.y, width: opts.clip.width, height: opts.clip.height, scale: 1 };
+      const { data } = await cdp.send('Page.captureScreenshot', params);
+      return { buf: Buffer.from(data, 'base64'), degraded: true };
+    } finally {
+      await cdp.detach().catch(() => {});
+    }
+  }
+}
+
+/**
+ * 超长页 fullPage → 滚动位置联络表（iss_mt0365b8）：48000px 的整页压进 API 长边
+ * 上限后只剩 47px 宽，什么都看不见——工具自己承认不可读还是把废图塞给了模型。
+ * 超过阈值改成：按滚动位置取 5 帧视口，拼一张带位置标注的联络表（跟胶片条同一
+ * 套版式，横轴从时间换成滚动位置）。一次调用看清整页节奏；要某段的原尺寸用
+ * scrollTo 参数去截那一段。
+ */
+export const LONG_PAGE_LIMIT = 12_000;
+
+export async function longPageSheet(page, { positions = [0, 0.22, 0.45, 0.68, 0.9] } = {}) {
+  const dims = await page.evaluate(() => ({
+    docH: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight || 0),
+    vpH: window.innerHeight, vpW: window.innerWidth, y0: window.scrollY,
+  }));
+  if (!(dims.docH > LONG_PAGE_LIMIT)) return null;
+  const shots = [];
+  for (const p of positions) {
+    const y = Math.round(p * (dims.docH - dims.vpH));
+    await page.evaluate((yy) => window.scrollTo(0, yy), y).catch(() => {});
+    await page.waitForTimeout(300);   // 给懒加载/reveal 一点点时间，不求全到
+    const { buf } = await shotWithFallback(page, { type: 'png' });
+    shots.push({ buf, label: `${Math.round(p * 100)}% y=${y}` });
+  }
+  await page.evaluate((yy) => window.scrollTo(0, yy), dims.y0).catch(() => {});
+
+  const { default: sharp } = await import('sharp');
+  const { sheetLayout } = await import('./motion-lab.js');
+  const meta = await sharp(shots[0].buf).metadata();
+  const L = sheetLayout(shots.length, meta.width, meta.height);
+  const composites = []; const labels = [];
+  for (let i = 0; i < shots.length; i += 1) {
+    const col = i % L.cols; const row = Math.floor(i / L.cols);
+    const left = L.gap + col * (L.cellW + L.gap);
+    const top = L.gap + row * (L.cellH + L.gap);
+    composites.push({ input: await sharp(shots[i].buf).resize(L.cellW, L.cellH, { fit: 'fill' }).png().toBuffer(), left, top });
+    labels.push({ left, top, label: shots[i].label });
+  }
+  const fontH = Math.max(13, Math.round(L.cellH * 0.055));
+  const escXml = (t) => String(t).replace(/[<>&]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;' }[c]));
+  const svg = [`<svg xmlns="http://www.w3.org/2000/svg" width="${L.sheetW}" height="${L.sheetH}">`,
+    ...labels.map((l) => `<rect x="${l.left}" y="${l.top}" width="${(l.label.length * fontH * 0.62 + 12).toFixed(0)}" height="${fontH + 10}" fill="#000" fill-opacity="0.72"/>`
+      + `<text x="${l.left + 6}" y="${l.top + fontH + 2}" font-size="${fontH}" fill="#fff" font-family="monospace">${escXml(l.label)}</text>`),
+    '</svg>'].join('');
+  const buf = await sharp({ create: { width: L.sheetW, height: L.sheetH, channels: 3, background: '#15150f' } })
+    .composite([...composites, { input: Buffer.from(svg), left: 0, top: 0 }]).png().toBuffer();
+  return {
+    buf,
+    mode: `long-page contact sheet (doc ${dims.docH}px, ${shots.length} viewports)`,
+    note: `整页高 ${dims.docH}px，fullPage 会压成不可读的细条 —— 已改为 ${shots.length} 帧滚动位置联络表（标注=滚动百分比与 y）。要某一段的原尺寸，用 scrollTo 参数（像素/百分比/选择器）单独截那一屏。`,
+  };
+}
+
+/**
+ * fullPage+clip 的"Clipped area is either empty or outside the resulting image"
+ * 兜底（iss_mszxp0zy）：Chromium 整页光栅有高度上限（~16384px 纹理），元素落在
+ * 超高页更深处时文档坐标 clip 会落到成图之外。兜底=滚到元素处，改用**视口坐标**
+ * clip 截当前屏（clip 语义两套：fullPage 下文档坐标 / 非 fullPage 视口坐标，
+ * 本机探针 08-19 定过案）。
+ */
+export async function clipShotWithFallback(page, { clip, selector }) {
+  try {
+    return await shotWithFallback(page, { fullPage: true, clip, type: 'png' });
+  } catch (err) {
+    if (!/Clipped area/i.test(String(err?.message)) || !selector) throw err;
+    await page.locator(selector).first().scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => {});
+    const r = await page.evaluate((sel) => {
+      const el = document.querySelector(sel);
+      if (!el) return null;
+      const b = el.getBoundingClientRect();
+      return { x: b.x, y: b.y, width: b.width, height: b.height, vw: window.innerWidth, vh: window.innerHeight };
+    }, selector);
+    if (!r) throw err;
+    const vClip = {
+      x: Math.max(0, r.x), y: Math.max(0, r.y),
+      width: Math.max(1, Math.min(r.width, r.vw - Math.max(0, r.x))),
+      height: Math.max(1, Math.min(r.height, r.vh - Math.max(0, r.y))),
+    };
+    const out = await shotWithFallback(page, { clip: vClip, type: 'png' });
+    return { ...out, degraded: true };
+  }
+}

package/server/engine/mcp/tools/list-pages.js

@@ -152,8 +152,8 @@ async function listSiteStructure(target) {
     return {
       content: [{
         type: 'text',
-        text: `${target.task} 里这个站点（${art?.root ? `产物根 ${art.root}/` : '任务根'}）还没有 html 页面。`
-          + (art?.root ? '（源写完了的话，先跑构建让产物落进去。）' : ''),
+        text: `这个站点（${art?.root ? `产物根 ${art.root}/` : '任务根'}）还没有 html 页面。`
+          + (art?.root ? '（源写完了的话，先跑构建让产物落进去；构建后确认产物真的落在这个目录。）' : ''),
       }],
     };
   }
@@ -186,6 +186,9 @@ async function listSiteStructure(target) {
     });
   }
 
+  // 输出统一成**工作区相对**路径：screenshot_canvas / artifact_open 收的就是这种。
+  // 以前 file 是产物根相对（index.html），agent 原样回喂必然 not found（08-24 案）
+  const prefix = art?.root ? `${art.root}/` : '';
   const known = new Set(pages);
   const broken = [];
   for (const p of out) {
@@ -199,7 +202,7 @@ async function listSiteStructure(target) {
         if (seg === '..') stack.pop();
         else stack.push(seg);
       }
-      if (!known.has(stack.join('/'))) broken.push(`${p.file} → ${href}`);
+      if (!known.has(stack.join('/'))) broken.push(`${prefix}${p.file} → ${href}`);
     }
   }
   const brokenNote = broken.length
@@ -212,11 +215,14 @@ async function listSiteStructure(target) {
     ? `\n\n同任务的其他产物（平等，各自寻址）：${siblings.map(a => a.entryRel).join(' / ')}`
     : '';
 
+  const outWs = prefix ? out.map(p => ({ ...p, file: prefix + p.file })) : out;
+
   return {
     content: [{
       type: 'text',
-      text: `站点 ${target.task} · ${out.length} 个页面（入口 ${pages[0]}）${rootNote}：\n\n`
-        + `${JSON.stringify(out, null, 2)}${brokenNote}${siblingNote}`,
+      text: `站点${art?.title ? ` ${art.title}` : ''} · ${out.length} 个页面（入口 ${prefix}${pages[0]}）${rootNote}`
+        + '，file 是工作区相对路径，可直接传给 screenshot_canvas / artifact_open：\n\n'
+        + `${JSON.stringify(outWs, null, 2)}${brokenNote}${siblingNote}`,
     }],
   };
 }

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

@@ -16,6 +16,8 @@
 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).
 
+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, stops at first failure.`,
     {
       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 = [];
+      const moves = [];
       let moved = 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 {
@@ -55,6 +66,20 @@ Batch: up to 16 items, moved in order, stops at first failure.`,
           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/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,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 } from '../../../projects/board-store.js';
+import { pinToZone, readBoard } from '../../../projects/board-store.js';
+import { layerOf } from '../../../lib/canvas-id.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
@@ -55,7 +49,7 @@ 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
+- 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,8 +58,7 @@ 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()
@@ -84,9 +77,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 +93,25 @@ 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 || {})));
         const { zone: placedZone, placed } = await pinToZone(projectId, { objectId, zoneId });
 
         try {

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

@@ -22,11 +22,13 @@ import { groupObjects, asciiMinimap, bboxOfRects, relationOf, columnsOf, viewpor
 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 path from 'node:path';
 
 /** 同一"行"的 y 容差：入座算法一行内顶对齐，40 世界像素内视作同行 */
 const ROW_TOLERANCE = 40;
 
-function describeEntry(board, id, entry, glyph = null, excerpts = null) {
+function describeEntry(board, id, entry, glyph = null, excerpts = null, staleIds = null) {
   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}] ` : '';
@@ -39,7 +41,9 @@ function describeEntry(board, id, entry, glyph = null, excerpts = null) {
     return `- ${g}[${md}] 「${t}」 ${at} (id: ${id})${entry.by === 'agent' ? ' ·你写的' : ''}${flags}`;
   }
   if (entry.kind === 'scribble') return `- ${g}[涂鸦] ${at} (id: ${id})${entry.by === 'agent' ? ' ·你画的' : ''}${flags}`;
-  return `- ${g}${id} ${at}${entry.by === 'agent' ? ' ·你摆的' : ''}${flags}`;
+  // 过期座位要明说（iss_mt38ucyq：旧路径条目被 agent 当"失效卡"差点建议删素材母版）
+  const stale = staleIds?.has(id) ? ' 〔⚠️磁盘上已无此路径 —— 多半被移动/改名了，以磁盘为准，别据此判失效或建议删除〕' : '';
+  return `- ${g}${id} ${at}${entry.by === 'agent' ? ' ·你摆的' : ''}${flags}${stale}`;
 }
 
 export function makeReadBoardTool({ projectId }) {
@@ -86,6 +90,16 @@ on the minimap and listed with what is inside it.`,
         .filter(({ id }) => !id.startsWith(`${CHALK_DIR}/`) || excerpts.has(id))
         .sort((a, b) => (a.entry.y - b.entry.y) || (a.entry.x - b.entry.x));
       const entryOf = new Map(items.map(it => [it.id, it.entry]));
+      // 座位 vs 磁盘对账（iss_mt38ucyq）：文件挪走后旧座位可能还挂几十秒
+      // （改名对账/前端回写有时差）。查一遍真身，过期的在条目上点名。
+      const root = getSharedDir(projectId);
+      const staleIds = new Set();
+      await Promise.all(items.map(async ({ id, entry }) => {
+        if (entry.kind === 'text' || entry.kind === 'scribble' || id === 'browse') return;
+        const bare = String(id).replace(/^(deck|site|docx):/, '');
+        if (!bare || bare.includes('..') || /^(text|scribble|b):/.test(bare)) return;
+        try { await fs.access(path.resolve(root, bare)); } catch { staleIds.add(id); }
+      }));
 
       // 小地图（用户视口画框）
       const vp = getViewpoint(projectId);
@@ -129,7 +143,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));
+          for (const { id, entry } of sorted) lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts, staleIds));
           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} 条线`);
         });
@@ -147,7 +161,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));
+            lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts, staleIds));
           }
         }
       }
@@ -183,7 +197,7 @@ on the minimap and listed with what is inside it.`,
         } catch { /* 关系读不到不挡座次 */ }
       }
 
-      lines.push('', '（口径：稀疏表只列摆过的；层归属为服务端近似；尺寸为形态估算）');
+      lines.push('', '（口径：稀疏表只列摆过的；层归属为服务端近似；尺寸为形态估算；带⚠️的条目=座位与磁盘对不上账）');
       return { content: [{ type: 'text', text: lines.join('\n') }] };
     },
   );

package/server/engine/mcp/tools/relate-on-board.js

@@ -16,10 +16,26 @@
  * 线不存坐标：端点是物件 id 或工作区 id，端点一移动线自己跟着走。
  */
 
+import path from 'node:path';
+import fs from 'node:fs/promises';
 import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
-import { patchBoard } from '../../../projects/board-store.js';
+import { patchBoard, readBoard } from '../../../projects/board-store.js';
 import { BINDING_TYPES, BINDING_TYPE_IDS, BINDING_MATERIALS } from '../../../lib/binding-types.js';
+import { normalizeCanvasId } from '../../../lib/canvas-id.js';
+
+/**
+ * 端点校验（08-23 案：不是 canvas id 的字符串照收，board.json 留悬空线）。
+ * 合法端点 = 板上有座位的 id，或者真实存在的工作区路径（带不带 kind 前缀都行）。
+ * write_on_board 的锚点早就这么查了，同一件事两个工具一个查一个不查是口径病。
+ */
+async function endpointExists(id, board, sharedRoot) {
+  if (board.objects?.[id]) return true;
+  if (/^doc:/.test(id)) return true;                       // 项目文档：固定名额
+  const bare = id.replace(/^(deck|site|docx|text|scribble):/, '');
+  if (!bare || bare.includes('..')) return false;
+  try { await fs.access(path.join(sharedRoot, bare)); return true; } catch { return false; }
+}
 
 /** 词汇表渲染成工具描述里的一段表，免得两处各写各的 */
 const VOCAB = BINDING_TYPE_IDS
@@ -29,7 +45,7 @@ const VOCAB = BINDING_TYPE_IDS
 let seq = 0;
 const nextId = () => `b:a${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
 
-export function makeRelateOnBoardTool({ projectId, ctx }) {
+export function makeRelateOnBoardTool({ sharedRoot, projectId, ctx }) {
   return tool(
     'relate_on_board',
     `Draw a relationship line between two things on the workbench canvas.
@@ -76,14 +92,36 @@ where the files live.`,
           isError: true,
         };
       }
+      // 端点先归一再校验：不存在的端点会在 board.json 里留一条悬空线，
+      // 画布上凭空多出从无到有的线（08-23 录 GIF 时真踩）
+      const nFrom = normalizeCanvasId(from);
+      const nTo = normalizeCanvasId(to);
+      if (!nFrom || !nTo) {
+        return { content: [{ type: 'text', text: `Bad endpoint id: ${!nFrom ? from : to}` }], isError: true };
+      }
+      const board = await readBoard(projectId);
+      for (const [raw, nid] of [[from, nFrom], [to, nTo]]) {
+        if (!(await endpointExists(nid, board, sharedRoot))) {
+          const seats = Object.keys(board.objects || {}).slice(0, 20);
+          return {
+            content: [{
+              type: 'text',
+              text: `端点 ${raw} 不在板上，也不是存在的工作区路径 —— 线没画。`
+                + `（read_board 可看全部；现有座位举例：${seats.join(', ') || '无'}）`,
+            }],
+            isError: true,
+          };
+        }
+      }
+      from = nFrom; to = nTo;
       const id = nextId();
       // by:'agent' 不只是记录出处 —— 用户画的线 agent 不该擅自删，反过来也一样
       const binding = { type, from, to, by: 'agent', ...(label ? { label } : {}), ...(material && material !== 'ink' ? { material } : {}) };
-      const board = await patchBoard(projectId, { bindings: { [id]: binding } });
+      const patched = await patchBoard(projectId, { bindings: { [id]: binding } });
 
       // 服务端会丢掉非法的线（未知 type / 自环）。**丢了要说**，否则 agent 以为
       // 画上了，用户看不到，两边都不知道发生了什么。
-      if (!board.bindings?.[id]) {
+      if (!patched.bindings?.[id]) {
         return {
           content: [{ type: 'text', text: `Relationship rejected by the board (bad type or endpoints): ${type} ${from} -> ${to}` }],
           isError: true,