@xiaobuyu/nodesign 0.0.6 → 0.0.8

package/server/engine/mcp/tools/generate-image.js

@@ -41,7 +41,6 @@
 
 import path from 'node:path';
 import fs from 'node:fs/promises';
-import { spawn } from 'node:child_process';
 import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { Events } from '../../agent/events.js';
 import { z } from 'zod';
@@ -49,6 +48,9 @@ import sharp from 'sharp';
 import {
   THUMBNAIL_MAX_DIM, THUMBNAIL_QUALITY, writeWebpSibling,   // 预热由 writeWebpSibling 顺带做
 } from '../../../lib/image-variant.js';
+import {
+  buildCodexBridgePrompt, runCodexImageGen, buildVariationPrompt, PRESERVE_KEYS,
+} from './helpers/codex-imagegen.js';
 
 // Thumbnail 配置（env 可调）。**原图不动**——保留 Gemini 输出的全分辨率（通常
 // 1080×1920+ PNG，6-8MB）让用户最终交付不损失质量。仅生成低清 thumbnail 给
@@ -136,71 +138,9 @@ const DEFAULT_DMXAPI_BASE = 'https://www.dmxapi.cn';
 const DEFAULT_CHANNEL = 'DMX';
 
 // ── codex 生图桥（2026-07-27：NoDesk 网关退役，codex 成为默认 provider）──
-// 骑 codex CLI 订阅（零 API 费）：spawn `codex exec` 让它调自带图像生成工具，
-// 图直接落到我们指定的绝对路径。实测单张 ~45-60s，参考图走 -i 附件（同样实测
-// 风格参照有效）。桥接 prompt 必须写死"逐字传递零改写"——codex agent 默认会
-// 按自己的 Augmentation rules 润色 prompt。
+// 桥的 prompt 组装 + 子进程执行 + 变体模式骨架都在 helpers/codex-imagegen.js
+// （2026-08-24 迁出）。这里只留 provider 分流开关。
 const IMAGE_PROVIDER = () => (process.env.NODESIGN_IMAGE_PROVIDER || 'codex').toLowerCase();
-const CODEX_BIN = process.env.NODESIGN_CODEX_BIN || 'codex';
-const CODEX_IMAGE_TIMEOUT_MS = Number(process.env.NODESIGN_CODEX_IMAGE_TIMEOUT_MS) || 240_000;
-
-function buildCodexBridgePrompt({ prompt, aspectRatio, absOut, refCount }) {
-  return [
-    '你是图像生成管道的执行端，只做下面几件事，不做任何多余动作：',
-    '1. 调用你的图像生成工具生成一张图。<image-prompt> 标签内的内容必须逐字作为生成 prompt，禁止改写、增删、翻译或润色。',
-    `2. 输出比例：${aspectRatio}。优先用工具的比例/尺寸参数；工具没有对应参数时，作为补充说明传给工具，但不修改 <image-prompt> 原文。`,
-    refCount > 0
-      ? `3. 本消息附带 ${refCount} 张参考图，把它们作为图像生成的参考输入（风格 / 主体一致性参照）。`
-      : '3. 本次无参考图。',
-    `4. 生成后把图片文件复制到精确路径 ${absOut}（目录已存在）。`,
-    '5. 最后只回复该绝对路径。',
-    '<image-prompt>',
-    prompt,
-    '</image-prompt>',
-  ].join('\n');
-}
-
-/**
- * 跑一次 codex exec 生图，以目标文件落盘为成功标准（codex 的文本回复不可信），
- * 失败自动重试一次。abort signal / 超时都 SIGKILL 子进程。
- */
-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`);
-    }
-  }
-}
 
 const PASSTHROUGH_PATH = '/default/passthrough';
 // model id 在 callGateway 时动态拼，因为支持 flash / pro 路由
@@ -413,6 +353,15 @@ REFERENCES:
   conversation. To iterate on a previous image, pass it back in referenceImages
   and restate the invariants every round.
 
+VARIATION MODE (series consistency — outfit swaps, one-detail edits):
+  Instead of hand-writing "change only X, keep Y" prompts, pass
+  variationOf (path of the base image) + change (the ONE thing to alter)
+  + optional preserve (which aspects must stay identical; default all).
+  The tool expands these into a battle-tested skeleton incl. standard
+  prohibitions (no invented straps/ornaments, absences preserved). Build
+  series as a tree: one anchor, then vary one axis per call. In this mode
+  prompt is optional (used as extra notes).
+
 WHEN TO USE:
   - You're building a deck / landing / report and want real imagery
   - You need a backdrop that pure CSS gradient can't achieve
@@ -424,15 +373,29 @@ WHEN NOT TO USE:
   - Data charts — use Recharts/ECharts/Mermaid via React mount
   - Simple inline icons (≤5 per page) — use lucide-react inline SVG
 
-ALWAYS pair generation with mcp__nodesign__record_decision so the prompt + role
-land on the shared decision sticky (notes/decisions). Its params are title +
-rationale (both required), scope, alternatives — there is no "topic" param.`,
+After a generation that settles style direction, record the settled anchor as a
+memory (记忆/, type: project) so later sessions inherit it.`,
     {
       prompt: z
         .string()
         .min(4)
         .max(3500)
-        .describe('Natural-language scene description. Describe, don\'t list keywords.'),
+        .optional()
+        .describe('Natural-language scene description. Describe, don\'t list keywords. Required unless variationOf is set (then it is appended as extra notes).'),
+      variationOf: z
+        .string()
+        .optional()
+        .describe('VARIATION MODE: workspace-relative path of the base image to reproduce with ONE change. Becomes the first reference image (edit target).'),
+      change: z
+        .string()
+        .min(4)
+        .max(500)
+        .optional()
+        .describe('VARIATION MODE: the single thing to alter, e.g. "裙子换成薄荷绿短裙，长度到膝盖以上". Required with variationOf.'),
+      preserve: z
+        .array(z.enum(PRESERVE_KEYS))
+        .optional()
+        .describe('VARIATION MODE: aspects that must stay identical. Omit = all of them (safest).'),
       aspectRatio: z
         .enum(ASPECT_RATIOS)
         .optional()
@@ -476,6 +439,9 @@ rationale (both required), scope, alternatives — there is no "topic" param.`,
     },
     async ({
       prompt,
+      variationOf,
+      change,
+      preserve,
       aspectRatio = '16:9',
       imageSize = '1K',
       referenceImages,
@@ -496,6 +462,19 @@ rationale (both required), scope, alternatives — there is no "topic" param.`,
           isError: true,
         };
       }
+      // 变体模式归一化：variationOf 只是 referenceImages[0] 的语义化别名，
+      // prompt 换成固定骨架 —— 下游（ref 解析 / -i 附件 / gateway inline）零改动。
+      const isVariation = Boolean(variationOf);
+      if (isVariation && !change) {
+        return { content: [{ type: 'text', text: 'generate_image failed: variationOf requires `change` (the ONE thing to alter).' }], isError: true };
+      }
+      if (!isVariation && !prompt) {
+        return { content: [{ type: 'text', text: 'generate_image failed: `prompt` is required (or use variationOf + change).' }], isError: true };
+      }
+      if (isVariation) {
+        prompt = buildVariationPrompt({ change, preserve, extra: prompt });
+        referenceImages = [variationOf, ...(referenceImages || [])];
+      }
       // 1. provider 分流（2026-07-27：NoDesk 网关退役，默认 codex 订阅生图；
       //    gateway 分支保留给显式 NODESIGN_IMAGE_PROVIDER=gateway 的场景）
       const provider = IMAGE_PROVIDER();
@@ -550,7 +529,7 @@ rationale (both required), scope, alternatives — there is no "topic" param.`,
         fileName = `${finalName}.png`;
         absOut = path.join(outDir, fileName);
         const bridgePrompt = buildCodexBridgePrompt({
-          prompt, aspectRatio, absOut, refCount: resolvedRefs.length,
+          prompt, aspectRatio, absOut, refCount: resolvedRefs.length, variation: isVariation,
         });
         try {
           await runCodexImageGen({
@@ -706,6 +685,7 @@ rationale (both required), scope, alternatives — there is no "topic" param.`,
           provider,
           model: provider === 'codex' ? 'codex' : model,
           referenceImageCount: resolvedRefs.length,
+          variationOf: variationOf || null,   // 变体血缘：产物墙 / 引用层能顺出系列树
           sessionId: ctx?.sessionId || null,
           runId: ctx?.runId || null,
           ts: new Date().toISOString(),

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/look-at-board.js

@@ -26,7 +26,7 @@ import { platform } from '../../../runtime/platform.js';
 import { launchPerceptionBrowser, PERCEPTION_ORIGIN } from './helpers/perception-page.js';
 import { readBoard } from '../../../projects/board-store.js';
 import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
-import { normalizeCanvasId } from '../../../lib/canvas-id.js';
+import { normalizeCanvasId, bareTag } from '../../../lib/canvas-id.js';
 
 const VIEW = { width: 1400, height: 900 };
 const READY_TIMEOUT_MS = 25_000;
@@ -46,7 +46,7 @@ export function makeLookAtBoardTool({ projectId }) {
   return tool(
     'look_at_board',
     `LOOK at the canvas (a real screenshot of the board as the user sees it). Use it after
-sketch_on_board / create_on_board / relate_on_board to check what you drew, or when the
+write_on_board / edit_board to check what you drew, or when the
 user talks about how things look on the board. Pick a region — the whole board shrunk
 into one image is unreadable:
 - tag: frame the group carrying this #tag (a sketch you made)
@@ -60,7 +60,8 @@ Costs a few seconds and ~1.7k tokens; don't call it in a loop.`,
       margin: z.number().min(0).max(2000).optional().describe('World px of margin around `around` (default 160)'),
       view: z.object({ x: z.number(), y: z.number(), w: z.number().min(50), h: z.number().min(50) }).optional(),
     },
-    async ({ tag, around, margin, view }) => {
+    async ({ tag: rawTag, around, margin, view }) => {
+      const tag = rawTag ? bareTag(rawTag) : rawTag;   // 同上：查询侧统一剥 #
       const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
       if (!projectId) return err('No project bound.');
       const origin = webOrigin();