@xiaobuyu/nodesign 0.0.1 → 0.0.2

package/server/engine/mcp/param-sanitizer.js

@@ -1,142 +1,142 @@
-/**
- * mcp/param-sanitizer.js — 工具参数标签泄漏消毒（2026-08-19）
- *
- * 病根（jsonl 实锤，会话 008fe16c，claude-opus-5[1m]，订阅直连非中转站）：
- * 模型把工具调用的闭合标签写错（用参数名当标签），上游解析器抢救时把下一个
- * 参数整个吞进上一个字符串参数 —— tool_use.input 落地已经是：
- *
- *   rationale: "…正文</rationale>\n<parameter name=\"scope\">庄家（对手）"
- *   scope: （缺失）
- *
- * 同会话 record_decision 4/4 全中，泄漏进了用户画布上的决策便利贴。上游改
- * 不了，在自己边界拆回来。record_decision 只是被看见的那个 —— 同样的泄漏
- * 落在别的工具的长文本参数上会静默进产物，所以消毒挂在 MCP server 出口
- * （createNodesignMcpServer 包所有工具），不是只修一个工具。
- *
- * 判据收得窄，几乎不可能误伤正文里合法讨论 XML 的内容，三个条件全中才动手：
- *   1. 字符串值里出现 `</{本参数名}>` 且其后紧跟 `<parameter name="X">`
- *   2. X 是这个工具 schema 里真实存在的参数
- *   3. X 在这次调用里缺失，且 schema 声明它是字符串型
- * 拆完 recordIssue 记自动层一笔 —— 发生率必须可见，静默修复=永远不知道
- * 上游好没好。消毒本身 fail-soft：它绝不能变成新的故障源。
- */
-
-import { recordIssue, signatureOf } from '../../lib/issues-store.js';
-
-/** zod v4：拆掉 optional/nullable/default 的壳看里面是不是 string */
-function unwrapsToString(zodType) {
-  let t = zodType;
-  for (let i = 0; i < 6 && t; i += 1) {
-    const def = t._zod?.def;
-    if (!def) return false;
-    if (def.type === 'string') return true;
-    if (def.type === 'optional' || def.type === 'nullable' || def.type === 'default') {
-      t = def.innerType;
-      continue;
-    }
-    return false;
-  }
-  return false;
-}
-
-const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-/**
- * 单个字符串值的泄漏拆解。返回 null（没泄漏）或
- * { clean, recovered: { 参数名: 值 } }。
- *
- * 链式泄漏也拆：value 可能连吞多个参数（A</A><parameter name="B">b</B>
- * <parameter name="C">c…），逐段切；段尾多出的 `</当前参数名>` 一并剥掉。
- */
-export function splitLeakedParams(paramName, value, { stringKeys, presentKeys }) {
-  if (typeof value !== 'string') return null;
-  const boundaryOf = (name, s, from) => {
-    const re = new RegExp(`</${escapeRe(name)}>\\s*<parameter name="([A-Za-z0-9_-]{1,64})">`, 'g');
-    re.lastIndex = from;
-    let m;
-    while ((m = re.exec(s)) !== null) {
-      const next = m[1];
-      if (stringKeys.has(next) && !presentKeys.has(next)) return { index: m.index, end: re.lastIndex, next };
-      // 命中了形状但下一个名字不合格 —— 不是我们认识的泄漏，继续找不如收手：
-      // 这种"半像"的情况宁可不动（判据要窄）。
-      return null;
-    }
-    return null;
-  };
-
-  const first = boundaryOf(paramName, value, 0);
-  if (!first) return null;
-
-  const recovered = {};
-  const clean = value.slice(0, first.index);
-  let curKey = first.next;
-  let rest = value.slice(first.end);
-  for (let hops = 0; hops < 8; hops += 1) {
-    const nb = boundaryOf(curKey, rest, 0);
-    if (!nb) break;
-    recovered[curKey] = rest.slice(0, nb.index);
-    curKey = nb.next;
-    rest = rest.slice(nb.end);
-  }
-  // 最后一段：剥掉可能挂在尾巴上的 `</当前参数名>`
-  recovered[curKey] = rest.replace(new RegExp(`\\s*</${escapeRe(curKey)}>\\s*$`), '');
-  return { clean, recovered };
-}
-
-/**
- * 消毒一份 args（不改原对象）。返回 { args, leaks } —— leaks 为空数组表示没动。
- * @param {object} args        SDK 校验后的入参
- * @param {object} rawShape    tool() 的 inputSchema（zod raw shape）
- */
-export function desmearArgs(args, rawShape) {
-  const leaks = [];
-  if (!args || typeof args !== 'object' || !rawShape) return { args, leaks };
-  const stringKeys = new Set(Object.keys(rawShape).filter((k) => unwrapsToString(rawShape[k])));
-  const presentKeys = new Set(Object.keys(args).filter((k) => args[k] !== undefined));
-  let out = args;
-  for (const k of Object.keys(args)) {
-    if (!stringKeys.has(k)) continue;
-    const hit = splitLeakedParams(k, args[k], { stringKeys, presentKeys });
-    if (!hit) continue;
-    if (out === args) out = { ...args };
-    out[k] = hit.clean;
-    for (const [rk, rv] of Object.entries(hit.recovered)) {
-      out[rk] = rv;
-      presentKeys.add(rk);
-    }
-    leaks.push({ from: k, recovered: Object.keys(hit.recovered) });
-  }
-  return { args: out, leaks };
-}
-
-/**
- * 包一个 tool() 定义：handler 前置消毒。fail-soft —— 消毒抛错就原样放行。
- * @param {object} toolDef   tool() 的返回值（{ name, inputSchema, handler, … }）
- * @param {object} [deps]    { projectId, sessionId } 供 recordIssue 归因
- */
-export function withParamSanitizer(toolDef, deps = {}) {
-  const inner = toolDef.handler;
-  if (typeof inner !== 'function' || !toolDef.inputSchema) return toolDef;
-  toolDef.handler = async (args, extra) => {
-    let finalArgs = args;
-    try {
-      const { args: cleaned, leaks } = desmearArgs(args, toolDef.inputSchema);
-      if (leaks.length) {
-        finalArgs = cleaned;
-        try {
-          recordIssue({
-            source: 'auto',
-            toolName: toolDef.name,
-            summary: `工具参数标签泄漏（上游解析）：${toolDef.name} 的 ${leaks.map((l) => l.from).join(',')} 吞了 ${leaks.map((l) => l.recovered.join('+')).join(',')}，已在边界拆回`,
-            detail: `模型把闭合标签写错、上游解析器把后续参数吞进前一个字符串参数。本层已恢复。leaks=${JSON.stringify(leaks)}`,
-            projectId: deps.projectId,
-            sessionId: deps.sessionId,
-            signature: signatureOf(`param-leak|${toolDef.name}`),
-          });
-        } catch { /* 记账失败不挡工具 */ }
-      }
-    } catch { /* 消毒自身故障 → 原样放行 */ }
-    return inner(finalArgs, extra);
-  };
-  return toolDef;
-}
+/**
+ * mcp/param-sanitizer.js — 工具参数标签泄漏消毒（2026-08-19）
+ *
+ * 病根（jsonl 实锤，会话 008fe16c，claude-opus-5[1m]，订阅直连非中转站）：
+ * 模型把工具调用的闭合标签写错（用参数名当标签），上游解析器抢救时把下一个
+ * 参数整个吞进上一个字符串参数 —— tool_use.input 落地已经是：
+ *
+ *   rationale: "…正文</rationale>\n<parameter name=\"scope\">庄家（对手）"
+ *   scope: （缺失）
+ *
+ * 同会话 record_decision 4/4 全中，泄漏进了用户画布上的决策便利贴。上游改
+ * 不了，在自己边界拆回来。record_decision 只是被看见的那个 —— 同样的泄漏
+ * 落在别的工具的长文本参数上会静默进产物，所以消毒挂在 MCP server 出口
+ * （createNodesignMcpServer 包所有工具），不是只修一个工具。
+ *
+ * 判据收得窄，几乎不可能误伤正文里合法讨论 XML 的内容，三个条件全中才动手：
+ *   1. 字符串值里出现 `</{本参数名}>` 且其后紧跟 `<parameter name="X">`
+ *   2. X 是这个工具 schema 里真实存在的参数
+ *   3. X 在这次调用里缺失，且 schema 声明它是字符串型
+ * 拆完 recordIssue 记自动层一笔 —— 发生率必须可见，静默修复=永远不知道
+ * 上游好没好。消毒本身 fail-soft：它绝不能变成新的故障源。
+ */
+
+import { recordIssue, signatureOf } from '../../lib/issues-store.js';
+
+/** zod v4：拆掉 optional/nullable/default 的壳看里面是不是 string */
+function unwrapsToString(zodType) {
+  let t = zodType;
+  for (let i = 0; i < 6 && t; i += 1) {
+    const def = t._zod?.def;
+    if (!def) return false;
+    if (def.type === 'string') return true;
+    if (def.type === 'optional' || def.type === 'nullable' || def.type === 'default') {
+      t = def.innerType;
+      continue;
+    }
+    return false;
+  }
+  return false;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * 单个字符串值的泄漏拆解。返回 null（没泄漏）或
+ * { clean, recovered: { 参数名: 值 } }。
+ *
+ * 链式泄漏也拆：value 可能连吞多个参数（A</A><parameter name="B">b</B>
+ * <parameter name="C">c…），逐段切；段尾多出的 `</当前参数名>` 一并剥掉。
+ */
+export function splitLeakedParams(paramName, value, { stringKeys, presentKeys }) {
+  if (typeof value !== 'string') return null;
+  const boundaryOf = (name, s, from) => {
+    const re = new RegExp(`</${escapeRe(name)}>\\s*<parameter name="([A-Za-z0-9_-]{1,64})">`, 'g');
+    re.lastIndex = from;
+    let m;
+    while ((m = re.exec(s)) !== null) {
+      const next = m[1];
+      if (stringKeys.has(next) && !presentKeys.has(next)) return { index: m.index, end: re.lastIndex, next };
+      // 命中了形状但下一个名字不合格 —— 不是我们认识的泄漏，继续找不如收手：
+      // 这种"半像"的情况宁可不动（判据要窄）。
+      return null;
+    }
+    return null;
+  };
+
+  const first = boundaryOf(paramName, value, 0);
+  if (!first) return null;
+
+  const recovered = {};
+  const clean = value.slice(0, first.index);
+  let curKey = first.next;
+  let rest = value.slice(first.end);
+  for (let hops = 0; hops < 8; hops += 1) {
+    const nb = boundaryOf(curKey, rest, 0);
+    if (!nb) break;
+    recovered[curKey] = rest.slice(0, nb.index);
+    curKey = nb.next;
+    rest = rest.slice(nb.end);
+  }
+  // 最后一段：剥掉可能挂在尾巴上的 `</当前参数名>`
+  recovered[curKey] = rest.replace(new RegExp(`\\s*</${escapeRe(curKey)}>\\s*$`), '');
+  return { clean, recovered };
+}
+
+/**
+ * 消毒一份 args（不改原对象）。返回 { args, leaks } —— leaks 为空数组表示没动。
+ * @param {object} args        SDK 校验后的入参
+ * @param {object} rawShape    tool() 的 inputSchema（zod raw shape）
+ */
+export function desmearArgs(args, rawShape) {
+  const leaks = [];
+  if (!args || typeof args !== 'object' || !rawShape) return { args, leaks };
+  const stringKeys = new Set(Object.keys(rawShape).filter((k) => unwrapsToString(rawShape[k])));
+  const presentKeys = new Set(Object.keys(args).filter((k) => args[k] !== undefined));
+  let out = args;
+  for (const k of Object.keys(args)) {
+    if (!stringKeys.has(k)) continue;
+    const hit = splitLeakedParams(k, args[k], { stringKeys, presentKeys });
+    if (!hit) continue;
+    if (out === args) out = { ...args };
+    out[k] = hit.clean;
+    for (const [rk, rv] of Object.entries(hit.recovered)) {
+      out[rk] = rv;
+      presentKeys.add(rk);
+    }
+    leaks.push({ from: k, recovered: Object.keys(hit.recovered) });
+  }
+  return { args: out, leaks };
+}
+
+/**
+ * 包一个 tool() 定义：handler 前置消毒。fail-soft —— 消毒抛错就原样放行。
+ * @param {object} toolDef   tool() 的返回值（{ name, inputSchema, handler, … }）
+ * @param {object} [deps]    { projectId, sessionId } 供 recordIssue 归因
+ */
+export function withParamSanitizer(toolDef, deps = {}) {
+  const inner = toolDef.handler;
+  if (typeof inner !== 'function' || !toolDef.inputSchema) return toolDef;
+  toolDef.handler = async (args, extra) => {
+    let finalArgs = args;
+    try {
+      const { args: cleaned, leaks } = desmearArgs(args, toolDef.inputSchema);
+      if (leaks.length) {
+        finalArgs = cleaned;
+        try {
+          recordIssue({
+            source: 'auto',
+            toolName: toolDef.name,
+            summary: `工具参数标签泄漏（上游解析）：${toolDef.name} 的 ${leaks.map((l) => l.from).join(',')} 吞了 ${leaks.map((l) => l.recovered.join('+')).join(',')}，已在边界拆回`,
+            detail: `模型把闭合标签写错、上游解析器把后续参数吞进前一个字符串参数。本层已恢复。leaks=${JSON.stringify(leaks)}`,
+            projectId: deps.projectId,
+            sessionId: deps.sessionId,
+            signature: signatureOf(`param-leak|${toolDef.name}`),
+          });
+        } catch { /* 记账失败不挡工具 */ }
+      }
+    } catch { /* 消毒自身故障 → 原样放行 */ }
+    return inner(finalArgs, extra);
+  };
+  return toolDef;
+}

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

@@ -1,124 +1,124 @@
-/**
- * mcp/tools/arrange-on-board.js —— arrange_on_board（2026-08-14，agent 摆位批·写侧）
- *
- * 语义摆位，**不给裸坐标**（用户拍板）：agent 说的是"把 A 摆到 B 旁边"这种
- * 人话，坐标由这里算出来、写进跟用户拖拽**同一个 layout 权威**（board.objects
- * 的 x/y）—— 布局引擎、用户、agent 三方从此不打架。撞上已有的卡就往下让
- * （跟入座避让同一个精神），落盘带 by:'agent' 出处。
- *
- * feature/unfeature 立/撤主角：写 board.hero，前端 pickHero 的推断被它压过。
- */
-
-import { tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-import { readBoard, patchBoard } from '../../../projects/board-store.js';
-import { estimateSize } from '../../../lib/board-kind-sizes.js';
-import { normalizeCanvasId, layerOf } from '../../../lib/canvas-id.js';
-
-const GAP_X = 24;
-const GAP_Y = 16;
-
-const hit = (a, b) => !(a.x + a.w <= b.x || b.x + b.w <= a.x || a.y + a.h <= b.y || b.y + b.h <= a.y);
-
-/** 撞卡往下让：同一层的既有条目当障碍（subject 自己除外） */
-function nudgeDown(pos, size, obstacles) {
-  const r = { ...pos, ...size };
-  for (let guard = 0; guard < 60; guard += 1) {
-    const blocker = obstacles.find(o => hit(r, o));
-    if (!blocker) return { x: r.x, y: r.y };
-    r.y = blocker.y + blocker.h + GAP_Y;
-  }
-  return { x: r.x, y: r.y };
-}
-
-export function makeArrangeOnBoardTool({ projectId, ctx }) {
-  return tool(
-    'arrange_on_board',
-    `Move things on the canvas by MEANING, not pixels. Read the chart first (read_board).
-
-Actions:
-- beside:   put subject immediately right of anchor (same row)
-- below:    put subject under anchor (same column)
-- feature:  make subject THE hero of the desktop (rendered one size up); no anchor
-- unfeature: drop the explicit hero, back to automatic judgment; no subject needed
-
-Rules the tool enforces: subject and anchor must live in the same folder layer
-(move files with mv first); collisions push the subject downward; your placements
-are marked by:'agent' so the user can tell who seated what. The user can always
-drag things afterwards — their move wins, do not fight it.`,
-    {
-      action: z.enum(['beside', 'below', 'feature', 'unfeature'])
-        .describe('What to do (see list above)'),
-      subject: z.string().min(1).max(300).optional()
-        .describe('Canvas id of the thing to move / feature (required except for unfeature)'),
-      anchor: z.string().min(1).max(300).optional()
-        .describe('Canvas id to place the subject relative to (required for beside/below)'),
-    },
-    async ({ action, subject: rawSubject, anchor: rawAnchor }) => {
-      if (!projectId) {
-        return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
-      }
-      const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
-
-      if (action === 'unfeature') {
-        await patchBoard(projectId, { hero: null });
-        try { ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: '撤了显式主角' }); } catch { /* fail-soft */ }
-        return { content: [{ type: 'text', text: 'Hero override cleared — automatic judgment resumes.' }] };
-      }
-
-      const subject = normalizeCanvasId(rawSubject);
-      if (!subject) return err('subject id 不合法。');
-
-      if (action === 'feature') {
-        await patchBoard(projectId, { hero: subject });
-        try { ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `立了主角：${subject}` }); } catch { /* fail-soft */ }
-        return { content: [{ type: 'text', text: `Featured: ${subject} now renders as the hero.` }] };
-      }
-
-      const anchor = normalizeCanvasId(rawAnchor);
-      if (!anchor) return err('beside/below 需要 anchor。');
-      if (anchor === subject) return err('subject 和 anchor 是同一件东西。');
-
-      const board = await readBoard(projectId);
-      const anchorEntry = board.objects?.[anchor];
-      if (!anchorEntry || !Number.isFinite(anchorEntry.x)) {
-        return err(`锚点 ${anchor} 还没有座位（read_board 里看不到的东西没法当锚）。`);
-      }
-      const known = new Set(Object.keys(board.zones || {}));
-      const subjectEntry = board.objects?.[subject] || null;
-      const anchorLayer = layerOf(anchor, anchorEntry, known);
-      if (subjectEntry) {
-        const subjectLayer = layerOf(subject, subjectEntry, known);
-        if (subjectLayer !== anchorLayer) {
-          return err(`不同层（${subjectLayer || '根'} vs ${anchorLayer || '根'}）：先 mv 文件到同一个文件夹，画布跟着走。`);
-        }
-      }
-
-      const aSize = estimateSize(anchor, anchorEntry);
-      const sSize = estimateSize(subject, subjectEntry);
-      const want = action === 'beside'
-        ? { x: Math.round(anchorEntry.x + aSize.w + GAP_X), y: Math.round(anchorEntry.y) }
-        : { x: Math.round(anchorEntry.x), y: Math.round(anchorEntry.y + aSize.h + GAP_Y) };
-
-      const obstacles = Object.entries(board.objects || {})
-        .filter(([id, e]) => id !== subject && Number.isFinite(e?.x)
-          && layerOf(id, e, known) === anchorLayer)
-        .map(([id, e]) => ({ ...estimateSize(id, e), x: e.x, y: e.y }));
-      const pos = nudgeDown(want, sSize, obstacles);
-
-      await patchBoard(projectId, {
-        objects: { [subject]: { ...(subjectEntry || {}), x: pos.x, y: pos.y, by: 'agent' } },
-      });
-      try {
-        ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `摆了 ${subject}` });
-      } catch { /* fail-soft */ }
-      return {
-        content: [{
-          type: 'text',
-          text: `Placed ${subject} ${action} ${anchor} at (${pos.x},${pos.y})`
-            + (pos.y !== want.y ? ' (nudged down to avoid overlap)' : '') + '.',
-        }],
-      };
-    },
-  );
-}
+/**
+ * mcp/tools/arrange-on-board.js —— arrange_on_board（2026-08-14，agent 摆位批·写侧）
+ *
+ * 语义摆位，**不给裸坐标**（用户拍板）：agent 说的是"把 A 摆到 B 旁边"这种
+ * 人话，坐标由这里算出来、写进跟用户拖拽**同一个 layout 权威**（board.objects
+ * 的 x/y）—— 布局引擎、用户、agent 三方从此不打架。撞上已有的卡就往下让
+ * （跟入座避让同一个精神），落盘带 by:'agent' 出处。
+ *
+ * feature/unfeature 立/撤主角：写 board.hero，前端 pickHero 的推断被它压过。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { readBoard, patchBoard } from '../../../projects/board-store.js';
+import { estimateSize } from '../../../lib/board-kind-sizes.js';
+import { normalizeCanvasId, layerOf } from '../../../lib/canvas-id.js';
+
+const GAP_X = 24;
+const GAP_Y = 16;
+
+const hit = (a, b) => !(a.x + a.w <= b.x || b.x + b.w <= a.x || a.y + a.h <= b.y || b.y + b.h <= a.y);
+
+/** 撞卡往下让：同一层的既有条目当障碍（subject 自己除外） */
+function nudgeDown(pos, size, obstacles) {
+  const r = { ...pos, ...size };
+  for (let guard = 0; guard < 60; guard += 1) {
+    const blocker = obstacles.find(o => hit(r, o));
+    if (!blocker) return { x: r.x, y: r.y };
+    r.y = blocker.y + blocker.h + GAP_Y;
+  }
+  return { x: r.x, y: r.y };
+}
+
+export function makeArrangeOnBoardTool({ projectId, ctx }) {
+  return tool(
+    'arrange_on_board',
+    `Move things on the canvas by MEANING, not pixels. Read the chart first (read_board).
+
+Actions:
+- beside:   put subject immediately right of anchor (same row)
+- below:    put subject under anchor (same column)
+- feature:  make subject THE hero of the desktop (rendered one size up); no anchor
+- unfeature: drop the explicit hero, back to automatic judgment; no subject needed
+
+Rules the tool enforces: subject and anchor must live in the same folder layer
+(move files with mv first); collisions push the subject downward; your placements
+are marked by:'agent' so the user can tell who seated what. The user can always
+drag things afterwards — their move wins, do not fight it.`,
+    {
+      action: z.enum(['beside', 'below', 'feature', 'unfeature'])
+        .describe('What to do (see list above)'),
+      subject: z.string().min(1).max(300).optional()
+        .describe('Canvas id of the thing to move / feature (required except for unfeature)'),
+      anchor: z.string().min(1).max(300).optional()
+        .describe('Canvas id to place the subject relative to (required for beside/below)'),
+    },
+    async ({ action, subject: rawSubject, anchor: rawAnchor }) => {
+      if (!projectId) {
+        return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
+      }
+      const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
+
+      if (action === 'unfeature') {
+        await patchBoard(projectId, { hero: null });
+        try { ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: '撤了显式主角' }); } catch { /* fail-soft */ }
+        return { content: [{ type: 'text', text: 'Hero override cleared — automatic judgment resumes.' }] };
+      }
+
+      const subject = normalizeCanvasId(rawSubject);
+      if (!subject) return err('subject id 不合法。');
+
+      if (action === 'feature') {
+        await patchBoard(projectId, { hero: subject });
+        try { ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `立了主角：${subject}` }); } catch { /* fail-soft */ }
+        return { content: [{ type: 'text', text: `Featured: ${subject} now renders as the hero.` }] };
+      }
+
+      const anchor = normalizeCanvasId(rawAnchor);
+      if (!anchor) return err('beside/below 需要 anchor。');
+      if (anchor === subject) return err('subject 和 anchor 是同一件东西。');
+
+      const board = await readBoard(projectId);
+      const anchorEntry = board.objects?.[anchor];
+      if (!anchorEntry || !Number.isFinite(anchorEntry.x)) {
+        return err(`锚点 ${anchor} 还没有座位（read_board 里看不到的东西没法当锚）。`);
+      }
+      const known = new Set(Object.keys(board.zones || {}));
+      const subjectEntry = board.objects?.[subject] || null;
+      const anchorLayer = layerOf(anchor, anchorEntry, known);
+      if (subjectEntry) {
+        const subjectLayer = layerOf(subject, subjectEntry, known);
+        if (subjectLayer !== anchorLayer) {
+          return err(`不同层（${subjectLayer || '根'} vs ${anchorLayer || '根'}）：先 mv 文件到同一个文件夹，画布跟着走。`);
+        }
+      }
+
+      const aSize = estimateSize(anchor, anchorEntry);
+      const sSize = estimateSize(subject, subjectEntry);
+      const want = action === 'beside'
+        ? { x: Math.round(anchorEntry.x + aSize.w + GAP_X), y: Math.round(anchorEntry.y) }
+        : { x: Math.round(anchorEntry.x), y: Math.round(anchorEntry.y + aSize.h + GAP_Y) };
+
+      const obstacles = Object.entries(board.objects || {})
+        .filter(([id, e]) => id !== subject && Number.isFinite(e?.x)
+          && layerOf(id, e, known) === anchorLayer)
+        .map(([id, e]) => ({ ...estimateSize(id, e), x: e.x, y: e.y }));
+      const pos = nudgeDown(want, sSize, obstacles);
+
+      await patchBoard(projectId, {
+        objects: { [subject]: { ...(subjectEntry || {}), x: pos.x, y: pos.y, by: 'agent' } },
+      });
+      try {
+        ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `摆了 ${subject}` });
+      } catch { /* fail-soft */ }
+      return {
+        content: [{
+          type: 'text',
+          text: `Placed ${subject} ${action} ${anchor} at (${pos.x},${pos.y})`
+            + (pos.y !== want.y ? ' (nudged down to avoid overlap)' : '') + '.',
+        }],
+      };
+    },
+  );
+}