@xiaobuyu/nodesign 0.0.1

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

@@ -0,0 +1,280 @@
+/**
+ * helpers/shot-pipeline.js — 截图管线的纯 helper（2026-08-19 从 screenshot.js 拆出，行数棘轮）
+ *
+ * screenshot_canvas / screenshot_url / browse 共用的一段：出图归一化、渲染保真探针、
+ * 页面诊断收集（console / 失败请求）、waitFor / beforeShot 等待语义。
+ * 全部只依赖 playwright Page 与 sharp，不碰工作区寻址 —— 拆出来是搬家不是重写。
+ */
+
+// ── 出图归一化（2026-07-29 立，2026-08-21 按新视觉档重算）──
+// 背景：fullPage 截长站点页时 PNG 会超 API 的图片上限，整个工具调用直接报错；
+// 本地先缩到模型真用得上的规格，传输体积小一个量级、永远不触发上限。编码统一 webp。
+//
+// 08-21 重算（会话模型 Opus 5 / Sonnet 5 / Opus 4.7+ 都是高分辨率档）：
+//   - 该档位 token = ⌈w/28⌉ × ⌈h/28⌉，上限 4784 token ≈ 3.75MP；长边上限 2576。
+//     旧值 1568 / 1.15MP 是 Opus 4.6 及以前的档，对现役模型是把画面白白缩掉 40% 长边。
+//   - 长边**定 2000 不定 2576**：一个请求里超过 20 张图时，每张都按"任一边 ≤2000px"
+//     严格限制（否则整个请求被拒）。agent 会话里截图攒到 20 张以上是常态，2000 是
+//     无论上下文里有多少张都安全的值。代价：极端长图（1440 宽的整页站）长边压到 2000，
+//     仍比旧的 1568 多 27%。
+//   - 非订阅通路（中转 gemini / 本地 qwen）在 model-ingress 另有 VISION_MAX_DIM=1568
+//     再压一道，这里放宽不影响它们。
+//   - 成本：1366×768 → 49×28=1372 token（旧算法 1399，几乎不变）；1920×1080 全幅
+//     → 69×39=2691（旧档会先缩到 1568×882 → 1792）；2000×1125 → 72×41=2952。
+const API_LONG_EDGE = 2000;
+const API_MAX_PIXELS = 3_750_000;
+/** 导出给"坐标 1:1"断言和产物会话的 frame 计算用（两处都要和这里同一套算法） */
+export const API_IMAGE_LIMITS = { longEdge: API_LONG_EDGE, maxPixels: API_MAX_PIXELS };
+/** 高分辨率档的 token 估算（⌈w/28⌉×⌈h/28⌉），给 caption 报成本用 */
+export const visionTokens = (w, h) => Math.ceil(w / 28) * Math.ceil(h / 28);
+
+// ── 渲染层保真（2026-08-07）──
+// 2026-08-05 事故：一次 screenshot_canvas 的位图整体呈暗色反转（深棕底米白字），
+// 同一 page 里 beforeShot 读的 getComputedStyle 却全程浅色真值，内联 #ff0000
+// 还原样出红——computed style 不动、paint 被变换、高饱和色豁免，指纹指向
+// Chromium 的强制暗色（Auto Dark）。事后无法稳定复现，但这一类"渲染层替页面
+// 做主"的来源可以确定性关掉，launch 参数全局带上：
+// 定义在同目录 perception-page.js（三个感知工具当时是裸奔的，收成一份）；
+// 这里原样再导出，screenshot-url.js 等调用方一站取齐。
+export { FIDELITY_LAUNCH_ARGS } from './perception-page.js';
+
+/**
+ * 渲染保真探针：主图截完后，往页面塞一块已知色 (#f5f0e4) 的 16px 方块单截，
+ * 看栅格出来的像素还认不认账。位图和 computed style 是两条独立感知通道——
+ * 渲染层若在做颜色变换，页面内任何 JS 读数都测不到，只有这种"已知输入对
+ * 已知输出"的探针测得到。亮度掉一半才报警（抗锯齿/有损压缩的小偏差不算）。
+ * 2026-08-05 那次事故 agent 连烧 8 张截图排查自己的 CSS 才怀疑到管线头上——
+ * 这个警告就是把那 8 张图省下来的。
+ */
+export async function detectPaintTransform(page) {
+  try {
+    await page.evaluate(() => {
+      const d = document.createElement('div');
+      d.id = '__nd_paint_probe__';
+      d.style.cssText = 'position:fixed;left:0;top:0;width:16px;height:16px;'
+        + 'background:#f5f0e4;z-index:2147483647;pointer-events:none';
+      document.documentElement.appendChild(d);
+    });
+    const buf = await page.locator('#__nd_paint_probe__').screenshot({ type: 'png' });
+    await page.evaluate(() => document.getElementById('__nd_paint_probe__')?.remove());
+    const { default: sharp } = await import('sharp');
+    const stats = await sharp(buf).stats();
+    const [r, g, b] = stats.channels.map((c) => c.mean);
+    const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;   // #f5f0e4 本色 ≈ 239
+    if (lum < 128) {
+      return '⚠ paint-layer color transform detected: a #f5f0e4 probe rasterized to '
+        + `rgb(${r | 0},${g | 0},${b | 0}). This bitmap does NOT faithfully show the page's own colors, `
+        + 'and computed styles will keep reporting the authored values — the mismatch is in the '
+        + 'rasterizer, not your CSS. Do not debug colors from this shot; report via report_issue '
+        + 'and ask the user to eyeball the page in their own browser.';
+    }
+    return null;
+  } catch {
+    return null;   // 探针挂了不挡截图
+  }
+}
+
+/** PNG buffer → { data, mimeType, note }。失败时原样回退 PNG（宁可大也别丢图）。 */
+export async function normalizeShot(buf) {
+  try {
+    const { default: sharp } = await import('sharp');
+    const meta = await sharp(buf).metadata();
+    const w = meta.width || 0;
+    const h = meta.height || 0;
+    if (!w || !h) return { data: buf.toString('base64'), mimeType: 'image/png', note: null };
+    const scale = Math.min(1, API_LONG_EDGE / Math.max(w, h), Math.sqrt(API_MAX_PIXELS / (w * h)));
+    const tw = Math.max(1, Math.round(w * scale));
+    const th = Math.max(1, Math.round(h * scale));
+    let img = sharp(buf);
+    if (scale < 1) img = img.resize(tw, th);
+    const out = await img.webp({ quality: 82 }).toBuffer();
+    let note = scale < 1
+      ? `image normalized ${w}x${h} -> ${tw}x${th} webp ${(out.length / 1024).toFixed(0)}KB (vision limit: long edge ${API_LONG_EDGE}px / ~${(API_MAX_PIXELS / 1e6).toFixed(2)}MP; ≈${visionTokens(tw, th)} tokens)`
+      : null;
+    // 极端长图：整体缩完细节所剩无几，提示换姿势而不是硬看
+    if (scale < 0.35 && Math.max(w, h) / Math.min(w, h) > 4) {
+      note += ' — long page squeezed hard; details are unreadable at this scale. Prefer sectioned shots (viewport + beforeShot scroll) or pageIndex/device over fullPage.';
+    }
+    return { data: out.toString('base64'), mimeType: 'image/webp', note };
+  } catch (err) {
+    return { data: buf.toString('base64'), mimeType: 'image/png', note: `image normalize skipped: ${err?.message || err}` };
+  }
+}
+
+// ── 页面诊断收集（2026-07-29）──
+// 背景：agent 塞了 GSAP/Lenis CDN 却不知道有没有加载成功——截图上看不出来。
+// 挂 4 个 playwright listener，截图 caption 里回传 console 错误 + 加载失败资源。
+// 上限/截断防止一个疯狂报错的页面把 caption 撑爆。
+const DIAG_MAX_ENTRIES = 15;
+const DIAG_MAX_TEXT = 300;
+const DIAG_MAX_LOGS = 10;   // console:'all' 时 log 级单独一桶，别把真错误挤出去
+
+/**
+ * @param {import('playwright').Page} page
+ * @param {object} [opts]
+ * @param {'warn'|'all'} [opts.console] 默认 'warn' 只收 warning/error。
+ *   'all' 把 log/info/debug 也带回（单独一桶，capped）。默认档下被滤掉的
+ *   log 条数会写进 summary —— agent 上报过：console.log 被静默吞掉，
+ *   它以为代码没执行到，白改了两轮（iss_msz24e0q_vfwf）。
+ */
+export function attachPageDiagnostics(page, opts = {}) {
+  const wantAll = opts.console === 'all';
+  // ⭐ 聚合按（归一化原因 × 主机）分组，不逐条罗列（agent 上报逮到：一页 30 张
+  // 字体请求失败会把 caption 撑成 30 行同一句话，真正独特的那条错误被淹没）。
+  // 归一化 = 把消息里的 URL 收成主机名：同一家 CDN 挂 30 个文件是**一个**故障。
+  const hostOf = (u) => { try { return new URL(u).hostname; } catch { return u; } };
+  const normText = (t) => t.replace(/https?:\/\/[^\s"')]+/g, (u) => `${hostOf(u)}/…`);
+
+  const consoleEntries = [];      // { type, text, count }，text 是该组第一条原文
+  const seenConsole = new Map();  // 归一化文本 → entry
+  const noteConsole = (type, rawText) => {
+    const text = String(rawText || '').slice(0, DIAG_MAX_TEXT);
+    const key = `${type}|${normText(text)}`;
+    const prev = seenConsole.get(key);
+    if (prev) { prev.count += 1; return; }
+    const entry = { type, text, count: 1 };
+    seenConsole.set(key, entry);
+    if (consoleEntries.length < DIAG_MAX_ENTRIES) consoleEntries.push(entry);
+  };
+
+  const failedGroups = new Map();  // `${host}|${detail}` → { method, url, detail, host, count }
+  const noteFailed = (method, url, detail) => {
+    const key = `${hostOf(url)}|${detail}`;
+    const prev = failedGroups.get(key);
+    if (prev) { prev.count += 1; return; }
+    if (failedGroups.size >= DIAG_MAX_ENTRIES) return;
+    failedGroups.set(key, { method, url: url.slice(0, DIAG_MAX_TEXT), detail, host: hostOf(url), count: 1 });
+  };
+
+  // log 级单独一桶（'all' 才收），同样按归一化文本分组
+  const logEntries = [];
+  const seenLogs = new Map();
+  let filteredLogs = 0;
+  const noteLog = (type, rawText) => {
+    const text = String(rawText || '').slice(0, DIAG_MAX_TEXT);
+    const key = `${type}|${normText(text)}`;
+    const prev = seenLogs.get(key);
+    if (prev) { prev.count += 1; return; }
+    const entry = { type, text, count: 1 };
+    seenLogs.set(key, entry);
+    if (logEntries.length < DIAG_MAX_LOGS) logEntries.push(entry);
+  };
+
+  page.on('console', (msg) => {
+    const type = msg.type();
+    if (type === 'error' || type === 'warning') { noteConsole(type, msg.text()); return; }
+    if (wantAll) noteLog(type, msg.text());
+    else filteredLogs += 1;
+  });
+  page.on('pageerror', (err) => noteConsole('pageerror', err?.message || err));
+  page.on('requestfailed', (req) => noteFailed(req.method(), req.url(), req.failure()?.errorText || 'failed'));
+  page.on('response', (res) => {
+    if (res.status() < 400) return;
+    noteFailed(res.request().method(), res.url(), `HTTP ${res.status()}`);
+  });
+
+  return {
+    /** 汇成 caption 附加段。干净时给正向确认（"不知道有没有挂"跟"确认没挂"是两回事）。 */
+    summary() {
+      const failed = [...failedGroups.values()];
+      // 被滤掉的 log 条数必须可见 —— "没显示"和"没发生"是两回事
+      const filteredNote = filteredLogs > 0
+        ? `${filteredLogs} log-level line(s) filtered — pass console:'all' to see them` : null;
+      if (!consoleEntries.length && !failed.length && !logEntries.length) {
+        return filteredNote
+          ? `console clean (${filteredNote}), all requests OK`
+          : 'console clean, all requests OK';
+      }
+      const lines = [];
+      if (consoleEntries.length) {
+        const total = consoleEntries.reduce((n, e) => n + e.count, 0);
+        lines.push(`console (${total}${total > consoleEntries.length ? ` in ${consoleEntries.length} groups` : ''}):`);
+        for (const e of consoleEntries) {
+          lines.push(`  [${e.type}] ${e.text}${e.count > 1 ? ` (×${e.count} similar)` : ''}`);
+        }
+      }
+      if (logEntries.length) {
+        const total = logEntries.reduce((n, e) => n + e.count, 0);
+        lines.push(`console logs (${total}${total > logEntries.length ? ` in ${logEntries.length} groups` : ''}):`);
+        for (const e of logEntries) {
+          lines.push(`  [${e.type}] ${e.text}${e.count > 1 ? ` (×${e.count} similar)` : ''}`);
+        }
+      }
+      if (filteredNote) lines.push(`(${filteredNote})`);
+      if (failed.length) {
+        const total = failed.reduce((n, f) => n + f.count, 0);
+        lines.push(`failed requests (${total}${total > failed.length ? ` in ${failed.length} groups` : ''}):`);
+        for (const f of failed) {
+          // 每组给一条样本 URL；同主机同原因的其余只报数
+          lines.push(`  ${f.method} ${f.url} — ${f.detail}${f.count > 1 ? ` (×${f.count} from ${f.host})` : ''}`);
+        }
+      }
+      return lines.join('\n');
+    },
+  };
+}
+
+/**
+ * beforeShot 执行（2026-07-29）：截图环境不滚动 → ScrollTrigger/IO 入场动画永远
+ * 不触发 → agent 为"能被截图"反过来阉割设计。给截图前跑一段交互的能力。
+ *  - 'scrollToBottom'：分步滚到底再回顶（所有 scroll-linked 动画都触发过一遍）
+ *  - 其他字符串：当 JS 片段在页面上下文执行（支持 await），超时兜底
+ *
+ * 超时 5s→10s（2026-08-19）：重 3D 站 boot 就要 3.5~5 秒，agent 一个会话里
+ * 十几次超时还误判功能坏了（iss_msz236jw_9eui）。"等页面就位"这半件事
+ * 已经拆给 waitFor 参数（runWaitFor，独立计时），beforeShot 只该剩设置动作。
+ */
+const BEFORE_SHOT_TIMEOUT_MS = 10000;
+
+/**
+ * waitFor：截图前轮询一个页面表达式直到为真（独立 15s 预算，不挤占 beforeShot）。
+ * 慢启动页面的正确姿势：waitFor:"window.__game" 等就位，beforeShot 只做设置。
+ * 超时不挡截图 —— note 写明没等到，agent 自己判断画面可不可信。
+ */
+export const WAIT_FOR_TIMEOUT_MS = 15000;
+export async function runWaitFor(page, expr) {
+  if (!expr) return null;
+  try {
+    await page.waitForFunction(expr, undefined, { timeout: WAIT_FOR_TIMEOUT_MS, polling: 100 });
+    return null;
+  } catch (err) {
+    const why = /Timeout/i.test(String(err?.message))
+      ? `waitFor not truthy within ${WAIT_FOR_TIMEOUT_MS / 1000}s`
+      : `waitFor error: ${err?.message || err}`;
+    return `${why} (${String(expr).slice(0, 80)}) — captured anyway, the page may not be in the state you expect`;
+  }
+}
+
+export async function runBeforeShot(page, beforeShot) {
+  if (!beforeShot) return null;
+  try {
+    if (beforeShot === 'scrollToBottom') {
+      await page.evaluate(async () => {
+        const doc = document.scrollingElement || document.documentElement;
+        const step = Math.max(200, window.innerHeight * 0.8);
+        for (let y = 0; y <= doc.scrollHeight; y += step) {
+          window.scrollTo(0, y);
+          await new Promise((r) => setTimeout(r, 120));
+        }
+        window.scrollTo(0, doc.scrollHeight);
+        await new Promise((r) => setTimeout(r, 250));
+        window.scrollTo(0, 0);
+      });
+      // 回顶后给 reveal/settle 动画一点时间
+      await page.waitForTimeout(400);
+    } else {
+      await Promise.race([
+        page.evaluate(`(async () => { ${beforeShot} })()`),
+        new Promise((_, rej) => setTimeout(
+          () => rej(new Error(`beforeShot timeout (${BEFORE_SHOT_TIMEOUT_MS / 1000}s) — if you were waiting for the page to boot, use waitFor instead`)),
+          BEFORE_SHOT_TIMEOUT_MS,
+        )),
+      ]);
+      await page.waitForTimeout(200);
+    }
+    return null;
+  } catch (err) {
+    // beforeShot 挂了不挡截图 —— 把错误带回 caption 让 agent 知道
+    return `beforeShot error: ${err?.message || err}`;
+  }
+}

package/server/engine/mcp/tools/highlight.js

@@ -0,0 +1,68 @@
+/**
+ * mcp/tools/highlight.js — highlight MCP tool
+ *
+ * 让 agent 在前端 canvas 上短暂 pulse 一个元素（默认 1500ms），用来"我建议
+ * 改这块"时给用户视觉锚点 — 不污染 DOM、不改样式、纯动画 overlay。
+ *
+ * 实现：emit run.canvas_highlight 事件 → 前端在 InspectFloatingCard 同层
+ * 挂 pulse overlay 短暂动画。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+
+/**
+ * @param {object} deps
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeHighlightTool({ ctx }) {
+  return tool(
+    'highlight',
+    `Briefly pulse-highlight an element in the user's canvas (does not modify
+DOM or styles, just an animated overlay).
+
+Use this when:
+- You're suggesting a change to a specific element and want the user to
+  see exactly which one
+- You just modified an element and want to draw attention to the result
+
+The frontend will resolve the selector inside iframe.contentDocument and
+animate a glow ring on it.`,
+    {
+      selector: z
+        .string()
+        .min(1)
+        .describe('CSS selector inside the canvas iframe (e.g., \'section[data-page="2"] h1\', \'[data-anchor="cover-title"]\')'),
+      durationMs: z
+        .number()
+        .int()
+        .min(200)
+        .max(10000)
+        .optional()
+        .describe('How long the pulse lasts; default 1500ms'),
+    },
+    async ({ selector, durationMs }) => {
+      try {
+        ctx?.emit?.({
+          type: 'run.canvas_highlight',
+          selector,
+          durationMs: durationMs ?? 1500,
+        });
+        return {
+          content: [{
+            type: 'text',
+            text: `Highlight pulse sent: ${selector} (${durationMs ?? 1500}ms)`,
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text',
+            text: `highlight failed: ${err?.message || String(err)}`,
+          }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

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

@@ -0,0 +1,222 @@
+/**
+ * mcp/tools/list-pages.js — list_pages MCP tool
+ *
+ * 加载 canvas.html 用 playwright headless，扫所有 `<section data-page="N">`
+ * 返回每页的元信息（index / layout / data-anchor / 标题 / bbox）。比 read_page
+ * 轻 —— read_page 给整段 outerHTML，list_pages 只给每页 1 行摘要。
+ *
+ * 典型场景：agent 想知道"这 deck 有多少页 / 每页大致是什么主题"，做总览决策时调。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { openArtifactPage, launchPerceptionBrowser, degradedNote } from './helpers/perception-page.js';
+import { resolveDeckSize, extractDeckAspect } from '../../../shared/deck.js';
+import {
+  resolveCanvasTarget, CANVAS_PATH_DESC, KIND_SITE, taskManifest, requireBrowsable,
+} from '../../../lib/artifact-target.js';
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeListPagesTool({ workspaceRoot, projectId, sessionId, ctx: _ctx }) {
+  return tool(
+    'list_pages',
+    `List the pages of the current artifact.
+
+DECK — one entry per <section data-page="N">: { index, layout, anchor, title, bbox }.
+SITE — one entry per html file in the task folder: { file, title, headings, links, bytes },
+plus a broken internal-link report.
+The tool figures out which kind it is; you do not pass it.
+
+Use when:
+- You want a quick overview before deciding what to change
+- You need the page count (deck) or the site map (site)
+- Verifying structure after a restructure
+
+Lighter than read_page (which returns full outerHTML of one page).`,
+    {
+      path: z.string().optional().describe(CANVAS_PATH_DESC),
+    },
+    async ({ path: relPath }) => {
+      if (!workspaceRoot) {
+        return {
+          content: [{ type: 'text', text: 'No workspace bound; cannot list pages.' }],
+          isError: true,
+        };
+      }
+      const target = await resolveCanvasTarget(workspaceRoot, relPath, sessionId);
+      if (!target.ok) return { content: [{ type: 'text', text: target.message }], isError: true };
+      const notBrowsable = requireBrowsable(target);
+      if (notBrowsable) return { content: [{ type: 'text', text: notBrowsable }], isError: true };
+
+      // 站点：「页」是独立文件，不是同一份文档里的 section。硬按 deck 那套扫
+      // `section[data-page]` 会 0 命中，然后回一句"这份画布没有页面"—— 一个内容
+      // 完整的站点会被 agent 读成空文件，这正是要避免的静默失败。
+      if (target.kind === KIND_SITE && target.taskDir) {
+        return listSiteStructure(target);
+      }
+
+      const canvasPath = target.absPath;
+      let html;
+      try {
+        html = await fs.readFile(canvasPath, 'utf8');
+      } catch {
+        return { content: [{ type: 'text', text: `${target.relPath} not found in workspace.` }], isError: true };
+      }
+      const dims = resolveDeckSize(extractDeckAspect(html));
+
+      let browser;
+      try {
+        browser = await launchPerceptionBrowser();
+        // 走 http（与用户预览同源），不再 file://；理由见 helpers/perception-page.js
+        const opened = await openArtifactPage(browser, {
+          projectId, workspaceRoot, absPath: canvasPath,
+          viewport: { width: dims.width, height: dims.height },
+        });
+        const page = opened.page;
+        await opened.goto();
+
+        const pages = await page.$$eval('section[data-page]', (sections) => {
+          return sections.map((s, i) => {
+            const r = s.getBoundingClientRect();
+            const idxAttr = s.getAttribute('data-page');
+            const heading = s.querySelector('h1, h2, h3, h4');
+            return {
+              index: idxAttr ? parseInt(idxAttr, 10) : (i + 1),
+              layout: s.getAttribute('data-layout') || null,
+              anchor: s.getAttribute('data-anchor') || null,
+              title: heading ? (heading.textContent || '').trim().slice(0, 100) : null,
+              bbox: { x: r.x, y: r.y, w: r.width, h: r.height },
+            };
+          });
+        });
+
+        if (pages.length === 0) {
+          return {
+            content: [{
+              type: 'text',
+              text: `${target.relPath} has no <section data-page="N"> elements.`,
+            }],
+          };
+        }
+
+        // thumbnail 与真实 src 的差别 08-21 起只在 generate-image cookbook 里说一次，不再每次 list_pages 都带
+        const thumbnailHint = '';
+
+        const degraded = degradedNote(opened);   // 契约：note 非空必须写进返回文本
+        return {
+          content: [{
+            type: 'text',
+            text: `${degraded ? `${degraded}\n\n` : ''}${thumbnailHint}${pages.length} page(s):`
+              + `\n\n${JSON.stringify(pages, null, 2)}`,
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `list_pages failed: ${err?.message || String(err)}` }],
+          isError: true,
+        };
+      } finally {
+        if (browser) {
+          try { await browser.close(); } catch { /* ignore */ }
+        }
+      }
+    },
+  );
+}
+
+/**
+ * 站点结构：产物根里每个 html 一条，带标题 / 小标题 / 站内外链接 / 体积。
+ *
+ * 纯文本解析，不开 playwright —— 站点是多文件，逐个起浏览器既慢又没必要；
+ * agent 要的是"这站有哪些页、彼此怎么连"，那是源码里就有的信息。
+ * 顺带查断链：站内链接指到不存在的文件是站点最常见、也最容易漏的错。
+ *
+ * 扫的是**产物根**（构建型站点 = dist/ 之类）：预览和发布看的是它，源目录的
+ * md / 模板在这里没有意义。`_drafts/` 的试作不算站点页面，单独提一句。
+ */
+async function listSiteStructure(target) {
+  const manifest = await taskManifest(target.taskDir);
+  // 多产物平权：报的是**这个站点实例**的结构（resolve 已判好路径属于哪个产物）
+  const art = target.artifact
+    || manifest?.artifacts?.find(a => a.kind === 'site' && !a.single)
+    || null;
+  const pages = art?.pages || [];
+  const baseDir = target.artifactDir || target.taskDir;
+  if (pages.length === 0) {
+    return {
+      content: [{
+        type: 'text',
+        text: `${target.task} 里这个站点（${art?.root ? `产物根 ${art.root}/` : '任务根'}）还没有 html 页面。`
+          + (art?.root ? '（源写完了的话，先跑构建让产物落进去。）' : ''),
+      }],
+    };
+  }
+  const out = [];
+  for (const rel of pages) {
+    let raw = '';
+    try { raw = await fs.readFile(path.join(baseDir, rel), 'utf8'); } catch { continue; }
+    const titleM = raw.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    const headings = [...raw.matchAll(/<h([1-3])\b[^>]*>([\s\S]*?)<\/h\1>/gi)]
+      .map(m => m[2].replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim())
+      .filter(Boolean)
+      .slice(0, 8);
+    const links = [...new Set([...raw.matchAll(/<a\b[^>]*?\bhref\s*=\s*(?:"([^"]+)"|'([^']+)')/gi)]
+      .map(m => (m[1] || m[2]).trim())
+      .filter(Boolean))];
+    const internal = links.filter(h => !/^(?:[a-z][a-z0-9+\-.]*:|\/\/|#)/i.test(h));
+    const stylesheets = [...new Set(
+      [...raw.matchAll(/<link\b[^>]*?href\s*=\s*(?:"([^"]+)"|'([^']+)')[^>]*>/gi)]
+        .filter(m => /stylesheet/i.test(m[0]))
+        .map(m => m[1] || m[2]),
+    )];
+    out.push({
+      file: rel,
+      title: titleM ? titleM[1].replace(/\s+/g, ' ').trim().slice(0, 100) : null,
+      headings,
+      internalLinks: internal,
+      externalLinkCount: links.length - internal.length,
+      stylesheets,
+      bytes: Buffer.byteLength(raw),
+    });
+  }
+
+  const known = new Set(pages);
+  const broken = [];
+  for (const p of out) {
+    for (const href of p.internalLinks) {
+      const clean = href.split('#')[0].split('?')[0];
+      if (!clean || !/\.html?$/i.test(clean)) continue;
+      const dir = p.file.includes('/') ? p.file.slice(0, p.file.lastIndexOf('/') + 1) : '';
+      const stack = [];
+      for (const seg of (dir + clean).split('/')) {
+        if (seg === '.' || seg === '') continue;
+        if (seg === '..') stack.pop();
+        else stack.push(seg);
+      }
+      if (!known.has(stack.join('/'))) broken.push(`${p.file} → ${href}`);
+    }
+  }
+  const brokenNote = broken.length
+    ? `\n\n⚠️ 站内链接指向不存在的页面（${broken.length} 条）：\n${broken.map(b => `- ${b}`).join('\n')}`
+    : '';
+  const rootNote = art?.root ? `（产物根 ${art.root}/，改源后要重新构建）` : '';
+  // 任务里的其他平等产物（别的站 / deck / 单页）提一句，agent 知道全貌
+  const siblings = (manifest?.artifacts || []).filter(a => a.entryRel !== art?.entryRel);
+  const siblingNote = siblings.length
+    ? `\n\n同任务的其他产物（平等，各自寻址）：${siblings.map(a => a.entryRel).join(' / ')}`
+    : '';
+
+  return {
+    content: [{
+      type: 'text',
+      text: `站点 ${target.task} · ${out.length} 个页面（入口 ${pages[0]}）${rootNote}：\n\n`
+        + `${JSON.stringify(out, null, 2)}${brokenNote}${siblingNote}`,
+    }],
+  };
+}

package/server/engine/mcp/tools/lookup-tags.js

@@ -0,0 +1,59 @@
+/**
+ * mcp/tools/lookup-tags.js — lookup_tags MCP tool（2026-08-20）
+ *
+ * danbooru 系模型（noobai / noobai-eps / pony）的标签写错不报错、只静默失效。
+ * 08-18 起 paint_still **画完之后**会体检；这个工具把查的动作挪到**画之前**，
+ * 配手册里的起手纪律：先从用户的话里理解要画什么 → 把每个概念想成候选标签 →
+ * 一次 lookup_tags 拿真实收录量和候选替换 → 再 paint_still。
+ *
+ * 薄壳：逻辑全在 lib/danbooru-tags.js（和体检共用一份，别分叉）。
+ * fail-open：danbooru 查不到就明说查不到，不挡出图。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { lookupTags, formatLookup } from '../../../lib/danbooru-tags.js';
+
+export function makeLookupTagsTool() {
+  return tool(
+    'lookup_tags',
+    `Check danbooru tags BEFORE painting with noobai / noobai-eps / pony
+(paint_still). These models only understand danbooru tags; a misspelled or
+unused tag fails SILENTLY — the model receives nothing and you burn a whole
+batch before anyone notices.
+
+Workflow: read what the user wants → list the concepts (subject, look,
+clothing, pose/expression, scene, lighting) → for each, write the danbooru
+tags you BELIEVE exist → call this ONCE with all of them in "tags" → keep the
+ones with post_count >= 1000, swap weak ones for the suggested candidates,
+then paint. Re-rolls of the same scene do not need another lookup.
+
+- tags:    exact names to verify (spaces or underscores both fine). Weak or
+           missing ones come back with real candidates ranked by post_count.
+- search:  free words when you do not know the tag at all ("makeup", "lick")
+           → matching tags ranked by post_count.
+- explain: tag names whose meaning you want (first lines of the danbooru wiki)
+           — useful to pick between near-synonyms.
+
+post_count < 1000 means WEAK, not forbidden: for mainstream needs pick the
+stronger candidate; when the user's taste is itself niche, use the weak tag and
+reinforce it with a related stronger one. Artist names always need checking.
+Results are hints — the prompt wording stays your call.`,
+    {
+      tags: z.array(z.string().min(1).max(80)).max(60).optional()
+        .describe('tag names to verify, e.g. ["long hair", "smeared lipstick", "artist:dairi"]'),
+      search: z.array(z.string().min(2).max(40)).max(10).optional()
+        .describe('free words to search tags by, e.g. ["makeup", "lick"]'),
+      explain: z.array(z.string().min(1).max(80)).max(8).optional()
+        .describe('tag names to get the wiki meaning of'),
+    },
+    async ({ tags = [], search = [], explain = [] }) => {
+      try {
+        const r = await lookupTags({ tags, search, explain });
+        return { content: [{ type: 'text', text: formatLookup(r) }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `lookup_tags 失败（不挡出图，照手册词表写）：${err.message}` }], isError: true };
+      }
+    },
+  );
+}