@xiaobuyu/nodesign 0.0.1

package/server/engine/mcp/tools/pin-to-board.js

@@ -0,0 +1,130 @@
+/**
+ * mcp/tools/pin_to_board — 把一件东西摆到用户画布上的某个位置。
+ *
+ * 写 board.json（board-store 单锁原子操作，与前端 PATCH 互不覆盖），然后广播
+ * board.updated（sessionId: null → project 全连接都收到，前端整份重拉）。
+ *
+ * 物件 id 约定（与前端 BoardCanvas 派生一致）：**id = kind 前缀 + 工作区相对路径**
+ *   - 普通文件（图片 / 便签 / 数据）：路径本身，`assets/generated/a.webp`
+ *   - deck：`deck:<路径>`，如 `deck:稿件/主稿.html`
+ *   - 站点：`site:<目录>`
+ *   - 项目文档：`doc:_root`（记忆）/ `doc:brand`（品牌档案）
+ *
+ * ## 2026-08-13：这个工具的职权范围缩小了
+ *
+ * 以前它有个 `zone` 参数，语义是"放进哪块工作区"。**在 id = 路径的模型下这件事
+ * 不成立** —— 一个物件属于哪个文件夹，答案就写在它的路径里。让工具单独写一个
+ * "显式归属"字段，等于允许画布说"它在 A 文件夹"而磁盘说"它在 B 文件夹"，
+ * 正是 2026-07-28 把「拖出工作区解绑」停用掉的那个理由（两边对不上，且很容易
+ * 误触）。要换文件夹就 `mv` —— 那是真的搬，画布跟着走。
+ *
+ * 所以现在它只剩一件事：**给这件东西一个位置并置顶**（"把它摆到用户眼前"）。
+ *
+ * ⚠️ 顺带修掉的两个僵尸：`zone` 原来被校验成 `/^[A-Za-z0-9-]{8,64}$/`（= 一个
+ * sessionId），于是任何中文文件夹名、任何带斜杠的嵌套路径都过不了，一律静默
+ * 回落到 sessionId —— 然后在 board.json 里新建一块根本不存在的"工作区"。
+ * agent 每帮一次忙就制造一条死数据。
+ */
+
+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';
+
+/** 物件 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) : '';
+}
+
+/**
+ * @param {object} deps
+ * @param {string} [deps.sharedRoot]   工作区根（校验文件存在用）
+ * @param {string} [deps.projectId]
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makePinToBoardTool({ sharedRoot, projectId, ctx }) {
+  return tool(
+    'pin_to_board',
+    `Bring an item to the front of the user's canvas, at a free spot in whatever
+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
+- 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
+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)`,
+    {
+      path: z
+        .string()
+        .min(1)
+        .max(300)
+        .describe('Item to surface — see accepted forms in the tool description'),
+    },
+    async ({ path: rawPath }) => {
+      try {
+        if (!projectId) {
+          return { content: [{ type: 'text', text: 'No project bound; cannot pin.' }], isError: true };
+        }
+
+        // 归一化成前端物件 id（id = kind 前缀 + 工作区相对路径）
+        let objectId = String(rawPath).trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
+        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)) {
+          // 裸路径：.html 是一份 deck，其余（图片 / 便签 / 数据文件）id 就是路径。
+          // 站点的目录要显式写 `site:` —— 光看路径分不出
+          // "一个收纳文件夹"和"一件目录型产物"，猜错了钉上去的是个不存在的 id。
+          if (sharedRoot) {
+            const abs = path.join(sharedRoot, objectId);
+            try { await fs.access(abs); } catch {
+              return {
+                content: [{ type: 'text', text: `File not found: ${objectId}. Paths are workspace-relative, same as on disk.` }],
+                isError: true,
+              };
+            }
+          }
+          if (/\.html?$/i.test(objectId)) objectId = `deck:${objectId}`;
+        }
+
+        const zoneId = folderOfObjectId(objectId);
+        const { zone: placedZone, placed } = await pinToZone(projectId, { objectId, zoneId });
+
+        try {
+          ctx?.emit?.({
+            type: 'board.updated',
+            sessionId: null,          // project 级广播：显式压掉 ctx 的 sessionId enrich
+            objectId,
+            zoneId,
+            summary: zoneId ? `已把 ${objectId} 摆到「${zoneId}」里` : `已把 ${objectId} 摆到桌面上`,
+          });
+        } catch { /* emit fail-safe */ }
+
+        const where = placedZone?.id ? `in ${placedZone.id}` : 'on the desktop';
+        return {
+          content: [{
+            type: 'text',
+            text: `Surfaced ${objectId} ${where} at (${placed.x}, ${placed.y}). The user's canvas updates live.`,
+          }],
+        };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `pin_to_board failed: ${err.message}` }], isError: true };
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/preview-deck.js

@@ -0,0 +1,130 @@
+/**
+ * mcp/tools/preview-deck.js — preview_deck MCP tool（2026-07-28）
+ *
+ * agent 主动把做好的 deck 摊到用户眼前：等价于用户在工作台上双击那张 deck 卡
+ * ——收起态就展开成内嵌渲染，已经展开就开成画布内的最大化窗口。
+ *
+ * 实现：纯 emit run.deck_preview 事件（跟 navigate_to_page 同款控制层套路），
+ * 路径归一在前端做（lib/stage.js 的 resolveObjectId 已经认得 tasks/<任务>/canvas.html
+ * 和会话 cwd 的 canvas.html 两种形态）。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { Events } from '../../agent/events.js';
+import { setActiveDeck } from '../../../lib/artifact-target.js';
+import fs from 'node:fs/promises';
+import nodePath from 'node:path';
+import { taskManifest } from '../../../lib/kinds/index.js';
+
+/**
+ * @param {object} deps
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makePreviewDeckTool({ ctx, sessionId, workspaceRoot }) {
+  return tool(
+    'preview_deck',
+    `Show a deck to the user on their workbench — the same thing that happens
+when they double-click the deck card themselves: a collapsed card expands into
+a live embedded preview, an already-expanded one opens as a maximized window
+over the desktop.
+
+Use this when:
+- You just finished (or substantially changed) a deck and want the user to look
+- The user asks "show me" / "let me see it"
+- You're about to discuss a deck and want it on screen first
+
+Do NOT use it to spam attention mid-work — one call when the thing is worth
+looking at. This does not replace screenshot_canvas: that one is for **you** to
+see the render, this one is for **the user**.`,
+    {
+      path: z
+        .string()
+        .optional()
+        .describe(
+          "Deck to show, workspace-relative (e.g. 'canvas.html' or '稿件/主稿.html'). Omit for the active artifact.",
+        ),
+    },
+    async ({ path: rawPath }) => {
+      try {
+        const p = typeof rawPath === 'string' ? rawPath.trim().replace(/^\.\//, '') : '';
+        // 绝对路径同拒：这个 path 直发前端当寻址依据（home 幽灵族的家规）
+        if (p.includes('..') || p.startsWith('/')) {
+          return { content: [{ type: 'text', text: 'Invalid path (workspace-relative only).' }], isError: true };
+        }
+        // ⭐ 2026-08-18：先查这个文件在不在。
+        // 以前这里只挡 `..` 和绝对路径，然后无条件 emit + 回一句 "Opened …"。
+        // 传一个不存在的路径、或者传站点的子页时，用户桌面上打开的是**本会话的
+        // 空 canvas.html**，而 agent 拿到的是成功 —— 它没有任何办法察觉用户
+        // 正对着一块空白（问题库 iss_msr8oki7_z9su：「静默成功是最伤的部分」）。
+        let siteNote = null;
+        if (p) {
+          const abs = nodePath.join(workspaceRoot || '', p);
+          try {
+            await fs.access(abs);
+          } catch {
+            return {
+              content: [{ type: 'text', text:
+                `path not found: ${p} —— 先写出这个文件，或者用 list_pages 看清楚现有产物。`
+                + '（没有打开任何东西，用户桌面没变。）' }],
+              isError: true,
+            };
+          }
+          // 站点的子页：站点是整站一扇窗，打开的是站不是那一页 —— 如实说
+          try {
+            const manifest = await taskManifest(workspaceRoot);
+            const arts = manifest?.artifacts || [];
+            // ⛔ 原判据是 `(a.root ? p.startsWith(`${a.root}/`) : true)`。**根站的
+            // root 是空字符串**（site.js 里 `out.push({ srcRoot:'', root, ... })`），
+            // 于是三元退化成"任意路径都算这个站的一页"。后果是 `preview_deck("报告.docx")`
+            // 和 `preview_deck("_drafts/试作.html")` 都被回一句自信的假话
+            // 「还不在这个站的页面清单里…用户看到的是入口 index.html」——
+            // 两句都假：docx 开在 DocxWindow，草稿开在自己那扇 single:true 的窗。
+            // 改动本意是消灭"静默成功"，结果换成了反向的自信错话。
+            //
+            // 先看有没有**别的产物正好就是这个路径**（单页站、docx、deck…）——
+            // 有就是它自己开，跟根站无关。
+            const ownedByOther = arts.some(a => a.entryRel === p || a.file === p
+              || (a.single && (a.pages || []).includes(p)));
+            const site = ownedByOther ? null : arts.find((a) => {
+              if (a.kind !== 'site' || a.single) return false;
+              if (a.root) return p.startsWith(`${a.root}/`);   // 目录即边界，前缀够用
+              // 根站没有目录边界可用，只能按"是不是一张网页"+页面清单判
+              if (!/\.html?$/i.test(p)) return false;
+              return true;
+            });
+            if (site && p !== (site.entryRel || 'index.html')) {
+              // 2026-08-18 起子页**真的**开在那一页上（前端 entry 一路传到 SiteWindow）。
+              // 但只有在产物清单认得这一页时才成立 —— 不在清单里（比如刚写出来还没
+              // 重拉）就还是退回入口，所以这句话要如实分两种说。
+              const known = (site.pages || []).includes(
+                site.root ? p.slice(site.root.length + 1) : p);
+              siteNote = known
+                ? `打开的是站点「${site.root || '工作区根'}」并停在 ${p} 这一页（整站一扇窗，用户可以在窗里翻别的页）。`
+                : `注意：${p} 还不在这个站的页面清单里（产物列表下次重拉才认它），`
+                  + `所以用户看到的是入口 ${site.entryRel || 'index.html'}。`
+                  + '站内给它加一条真链接，或者等一轮再试。';
+            }
+          } catch { /* manifest 读不出来不挡预览 */ }
+          setActiveDeck(sessionId, p);   // 摊给用户看的那份就是"当前 deck"
+        }
+        ctx?.emit?.(Events.deckPreview(p));
+        return {
+          content: [{
+            type: 'text',
+            text: [
+              p ? `Opened ${p} on the user's workbench.`
+                : "Opened this session's deck on the user's workbench.",
+              siteNote,
+            ].filter(Boolean).join('\n'),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `preview_deck failed: ${err?.message || String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/profile-scroll.js

@@ -0,0 +1,305 @@
+/**
+ * mcp/tools/profile-scroll.js — profile_scroll（2026-08-18）
+ *
+ * ## 为什么有这个工具
+ *
+ * 用户说"往下滑动一顿一顿的"，这在设计工具里是最常见的反馈之一。而在这之前
+ * 平台给 agent 的全部观测能力是「截一张静态图」—— 帧时、掉帧、图片体积、
+ * 长任务一个都看不到。一个 agent 的实际绕路是：起 `python3 -m http.server`
+ * → 从仓库 node_modules 直接 import playwright → 手写 rAF 采样器 → 逐项关掉
+ * 嫌疑元素做 A/B。它量出来的结论一个都猜不出来：基线 63% 掉帧，单独关视差
+ * 64%（没用），单独关全屏胶片颗粒层 40%，两个都关 5% —— 是**叠加效应**，
+ * 真凶是「33.7MB 的 PNG + 一个带 mix-blend-mode 的全屏 fixed 层」这对组合。
+ * 没有测量，它大概率只会把用户新抱怨的那个功能拆掉交差，剩下 40% 的掉帧
+ * 原封不动留在站里。
+ *
+ * ## 数字怎么读
+ *
+ * ⚠️ 这台机器 1 vCPU，而且截图 worker 跟 server 抢同一颗核。**绝对值不代表
+ * 用户设备上的体验**，它的用处是 A/B：改一处、再量一次、看方向。返回文本里
+ * 会重复这句话，别让 agent 拿绝对数字去跟用户汇报。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { resolveCanvasTarget, CANVAS_PATH_DESC, requireBrowsable } from '../../../lib/artifact-target.js';
+import { openArtifactPage, launchPerceptionBrowser, degradedNote } from './helpers/perception-page.js';
+
+const DEVICE_W = { desktop: 1440, tablet: 834, mobile: 390 };
+const DEVICE_H = { desktop: 900, tablet: 1112, mobile: 844 };
+
+/**
+ * 页面里跑的采样器：**只测量，不自己滚**。
+ *
+ * ⛔ 前两版都是页面自己 `window.scrollBy` 推进的，两次都测错，原因不同：
+ *   v1「大跨步 + 每步 sleep」——合成器在步与步之间有空闲，坏页面照样报 3% 掉帧。
+ *   v2「rAF 里逐帧小步推」——压力对了，但**滚动方式还是假的**：程序化滚动
+ *      不派发 wheel 事件，于是一整类最常见的"一顿一顿"完全隐形：
+ *      wheel handler 里做视差、滚动劫持（scrolljacking）、平滑滚库
+ *      （Locomotive/Lenis 那种自己接管滚动的）。用户的手指走的是 wheel 那条路。
+ *      而且 `scroll-behavior: smooth` 会把程序化滚动变成动画，实测让量测范围
+ *      悄悄缩到 3.5% —— 看着"滚完了"，其实几乎没动。
+ * 现在：滚动由外面用 CDP 派发**真 wheel 事件**（≈60Hz），这里只逐帧记 rAF 间隔。
+ *
+ * ⭐ 顺带白拿一个诊断：派发了多少像素 vs 页面实际走了多少像素。差得远
+ *    = 滚动被劫持了，这本身就是答案。
+ */
+/* eslint-disable no-undef */
+function installSampler() {
+  const st = {
+    frames: [], longTasks: [], po: null, raf: 0, running: true,
+    startedAt: performance.now(), last: performance.now(),
+    container: null, startTop: 0,
+  };
+  window.__ndProf = st;
+  try {
+    st.po = new PerformanceObserver((l) => { for (const e of l.getEntries()) st.longTasks.push(e.duration); });
+    st.po.observe({ entryTypes: ['longtask'] });
+  } catch { /* 不支持就没有长任务数据 */ }
+
+  // 滚的可能不是 window：应用式版面常常是某个内层容器在滚。wheel 事件落在
+  // 指针下面那个元素上，所以内层容器**会**滚 —— 但 window.scrollY 不动，
+  // 按它判断就会误报"这页滚不动"。先认出真正在滚的那个。
+  const pickContainer = () => {
+    const cx = Math.floor(window.innerWidth / 2);
+    const cy = Math.floor(window.innerHeight / 2);
+    let el = document.elementFromPoint(cx, cy);
+    while (el && el !== document.body && el !== document.documentElement) {
+      const cs = getComputedStyle(el);
+      const scrollable = /(auto|scroll|overlay)/.test(`${cs.overflowY}`) && el.scrollHeight > el.clientHeight + 4;
+      if (scrollable) return el;
+      el = el.parentElement;
+    }
+    return document.scrollingElement || document.documentElement;
+  };
+  st.container = pickContainer();
+  st.startTop = st.container.scrollTop;
+
+  const tick = () => {
+    if (!st.running) return;
+    const now = performance.now();
+    st.frames.push(now - st.last);
+    st.last = now;
+    st.raf = requestAnimationFrame(tick);
+  };
+  st.raf = requestAnimationFrame(tick);
+  return {
+    scrollHeight: st.container.scrollHeight,
+    clientHeight: st.container.clientHeight,
+    isWindow: st.container === (document.scrollingElement || document.documentElement),
+  };
+}
+
+function collectSampler() {
+  const st = window.__ndProf;
+  if (!st) return null;
+  st.running = false;
+  cancelAnimationFrame(st.raf);
+  try { st.po?.disconnect(); } catch { /* */ }
+
+  const imgs = performance.getEntriesByType('resource')
+    .filter(e => e.initiatorType === 'img' || /\.(png|jpe?g|webp|avif|gif|svg)(\?|$)/i.test(e.name))
+    .map(e => ({
+      name: decodeURIComponent(e.name.split('?')[0].split('/').pop() || '').slice(0, 60),
+      // encodedBodySize 是**这次传输**的字节；transferSize 命中缓存时是 0。
+      // 感知通道现在带 X-ND-Raw，拿的是磁盘原图，所以这个数字就是交付站点的数字。
+      bytes: e.encodedBodySize || e.transferSize || 0,
+    }));
+  imgs.sort((a, b) => b.bytes - a.bytes);
+
+  return {
+    frames: st.frames.slice(2),                    // 头两帧含启动抖动
+    longTasks: st.longTasks,
+    elapsedMs: performance.now() - st.startedAt,
+    scrollHeight: st.container.scrollHeight,
+    clientHeight: st.container.clientHeight,
+    movedPx: st.container.scrollTop - st.startTop,
+    imgCount: imgs.length,
+    imgBytes: imgs.reduce((a, b) => a + b.bytes, 0),
+    topImgs: imgs.slice(0, 5),
+    layers: (() => {
+      // 「合成层嫌疑」：全屏定位 + 带混合模式/滤镜/半透明的那些，
+      // 就是那个真实案例里的另一半凶手
+      const out = [];
+      for (const el of document.querySelectorAll('*')) {
+        const cs = getComputedStyle(el);
+        if (cs.position !== 'fixed' && cs.position !== 'sticky') continue;
+        const r = el.getBoundingClientRect();
+        const big = r.width * r.height > window.innerWidth * window.innerHeight * 0.5;
+        const heavy = cs.mixBlendMode !== 'normal' || cs.filter !== 'none'
+          || cs.backdropFilter !== 'none' || (cs.opacity !== '1' && cs.opacity !== '');
+        if (big && heavy) {
+          const id = el.id ? `#${el.id}` : (typeof el.className === 'string' && el.className.trim()
+            ? `.${el.className.trim().split(/\s+/)[0]}` : el.tagName.toLowerCase());
+          out.push(`${id} [${cs.position}, blend=${cs.mixBlendMode}, filter=${cs.filter === 'none' ? '-' : 'yes'}, backdrop=${cs.backdropFilter === 'none' ? '-' : 'yes'}, opacity=${cs.opacity}]`);
+        }
+        if (out.length >= 5) break;
+      }
+      return out;
+    })(),
+  };
+}
+/* eslint-enable no-undef */
+
+const pct = (arr, p) => {
+  if (!arr.length) return 0;
+  const s = [...arr].sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))];
+};
+const kb = (b) => (b >= 1024 * 1024 ? `${(b / 1024 / 1024).toFixed(1)}MB` : `${Math.round(b / 1024)}KB`);
+
+export function makeProfileScrollTool({ workspaceRoot, projectId, sessionId }) {
+  return tool(
+    'profile_scroll',
+    `Measure how a page actually performs while scrolling. Loads it over http
+(same origin as the user preview), scrolls programmatically, and returns frame
+timing, dropped-frame ratio, long tasks, total image bytes and the heaviest
+images, plus any full-screen fixed/sticky layers with blend modes or filters.
+
+Scrolling is driven by REAL wheel events, so this also catches the other common
+cause of "one frame at a time": the page eating the wheel and scrolling itself
+(scroll hijacking, Lenis/Locomotive-style smooth scroll). The report says how
+many pixels were dispatched vs how many the page actually moved — if those
+disagree, that is your answer and frame times are beside the point.
+
+Use this the moment a user says scrolling feels heavy, janky, laggy or "one
+frame at a time" — do NOT start deleting features to guess which one it is.
+The one real case on record: baseline 63% dropped frames; killing the parallax
+alone changed nothing (64%); killing the full-screen grain layer alone got it to
+40%; killing both got 5%; hiding images got 3%. It was an additive effect
+between 33.7MB of PNGs and one blended full-screen layer. Guessing would have
+removed the wrong thing and left most of the jank in place.
+
+Also worth running before you hand over any image-heavy page: total image bytes
+is the single most common cause, and generate_image now writes a .webp sibling
+next to every PNG for exactly this reason.
+
+⚠️ This machine has 1 vCPU and the browser competes with the server for it. The
+absolute numbers are NOT what the user's device will see. Use them for A/B:
+measure, change one thing, measure again, compare direction. Never report the
+raw percentage to the user as if it were their experience.`,
+    {
+      path: z.string().optional().describe(CANVAS_PATH_DESC),
+      device: z.enum(['desktop', 'tablet', 'mobile']).optional()
+        .describe('Viewport preset (default desktop 1440×900). Mobile is where jank shows up worst.'),
+      frames: z.number().int().min(30).max(300).optional()
+        .describe('How many wheel steps to scroll across (default 120 ≈ a 2-second scroll at 60Hz). Real wheel events are dispatched at ~60Hz, the same rate a trackpad fires — so wheel handlers, scroll hijacking and smooth-scroll libraries are all in the measurement.'),
+    },
+    async ({ path: relPath, device, frames: framesArg }) => {
+      const asText = (text) => ({ content: [{ type: 'text', text }] });
+      const target = await resolveCanvasTarget(workspaceRoot, relPath, sessionId);
+      if (!target) return { content: [{ type: 'text', text: 'No page found to profile.' }], isError: true };
+      const guard = requireBrowsable(target);
+      if (guard) return { content: [{ type: 'text', text: guard }], isError: true };
+
+      const dev = device || 'desktop';
+      const viewport = { width: DEVICE_W[dev], height: DEVICE_H[dev] };
+      const nFrames = framesArg ?? 120;
+
+      let browser;
+      try {
+        browser = await launchPerceptionBrowser();
+        const opened = await openArtifactPage(browser, {
+          projectId, workspaceRoot, absPath: target.absPath, viewport,
+        });
+        await opened.goto();
+        const page = opened.page;
+
+        // 采样器先装上（它顺手认出真正在滚的那个容器），再从外面派发真 wheel
+        const geom = await page.evaluate(installSampler);
+        const scrollable = Math.max(0, geom.scrollHeight - geom.clientHeight);
+        // 每帧推进量：把可滚范围在 nFrames 帧里走完。下限 6px —— 太小的话短页面
+        // 一直停在原地，样本全是静止帧（那种"满分"没有意义）。
+        const perFrame = Math.max(6, Math.round(scrollable / nFrames));
+
+        // ⭐ 真 wheel，配速 ≈60Hz。配速是必要的：不配速的话 CDP 一秒能塞几百个
+        // wheel，任何页面都会显得卡（假警报），而真人的滚轮/触摸板就是 60-120Hz。
+        await page.mouse.move(Math.floor(viewport.width / 2), Math.floor(viewport.height / 2));
+        const t0 = Date.now();
+        for (let i = 0; i < nFrames; i += 1) {
+          await page.mouse.wheel(0, perFrame);
+          const wait = (t0 + (i + 1) * 16) - Date.now();
+          if (wait > 1) await page.waitForTimeout(wait);
+        }
+        await page.waitForTimeout(120);   // 让最后几帧和长任务落账
+        const r = await page.evaluate(collectSampler);
+
+        // ⛔ **不再过滤长帧**。原来是 `frames.filter(f => f > 0 && f < 2000)`，
+        // 于是一个 3017ms 的冻结**被当成脏数据剔掉**，剩下的帧算出 `dropped 0%`
+        // 且不作任何提示 —— 越卡越可能被删。A/B 甚至会反过来（把页面改得更卡
+        // 反而报得更好）。长帧正是要找的东西。
+        const frames = r.frames.filter(f => f > 0);
+        const dropped = frames.filter(f => f > 16.7 * 1.5).length;
+        const dropRatio = frames.length ? (dropped / frames.length) * 100 : 0;
+        const worst = frames.length ? Math.max(...frames) : 0;
+        const freezes = frames.filter(f => f > 250).length;
+        // 派发了多少 vs 真走了多少。差很多 = 滚动被劫持/被平滑滚库接管，
+        // 这本身就是"一顿一顿"的答案，不必再往下猜。
+        const askedPx = perFrame * nFrames;
+        const movedPx = Math.round(r.movedPx);
+        const followRatio = askedPx ? (movedPx / askedPx) * 100 : 100;
+        // 样本不足就说不足。原来这种情况报的是 `p50 0.0ms / dropped 0%` ——
+        // 一句"满分"，而真相是**什么都没量到**（溢出面板、短页、滚不动的页）。
+        const tooFew = frames.length < 20;
+        // 判据是**跟随率**不是绝对位移：实测那个劫持页走了 960px（不算"没动"），
+        // 但只跟上了派发量的 13% —— 用户手上的感觉就是"滚了半天没动"。
+        // 60% 是留给平滑滚库正常惯性的余量。
+        const hijacked = askedPx > 400 && followRatio < 60;
+
+        // 契约：note 非空必须写进返回文本。这个工具尤其不能漏 —— 它的描述铁口
+        // 直断"走 http 同源"，退回 file:// 后它按 Resource Timing 报的
+        // 「images 0 files 0KB」正好是它主诊断的反面。
+        const degraded = degradedNote(opened);
+        const lines = [
+          ...(degraded ? [degraded, ''] : []),
+          `profile_scroll — ${target.relPath} @ ${dev} ${viewport.width}×${viewport.height}`,
+          `scroll container ${geom.isWindow ? 'window' : 'an inner element (overflow:auto)'}`
+            + `, scrollable ${scrollable}px, real wheel events ${perFrame}px × ${nFrames} @60Hz`,
+          `moved ${movedPx}px of ${askedPx}px dispatched (${followRatio.toFixed(0)}% followed)`,
+          '',
+          ...(tooFew ? [
+            `⚠ ONLY ${frames.length} frames sampled — that is not enough to say anything.`,
+            '  Nothing below is a verdict. Usual causes: the page is barely taller than the',
+            '  viewport, or the thing that scrolls is not under the centre of the screen.',
+            '',
+          ] : []),
+          ...(hijacked ? [
+            `⚠ ${nFrames} real wheel events asked for ${askedPx}px; the page moved ${movedPx}px (${followRatio.toFixed(0)}%).`,
+            '  Something is EATING the scroll — a wheel handler doing custom scrolling,',
+            '  scroll hijacking, or a smooth-scroll library (Lenis/Locomotive). That IS the',
+            '  jank the user feels: their wheel and the page no longer agree. Look at wheel',
+            '  listeners before you look at images or layers.',
+            '',
+          ] : []),
+          `frame time  p50 ${pct(frames, 50).toFixed(1)}ms  p90 ${pct(frames, 90).toFixed(1)}ms  p99 ${pct(frames, 99).toFixed(1)}ms  (16.7ms = 60fps)`,
+          `dropped     ${dropRatio.toFixed(0)}% of ${frames.length} frames took >25ms`,
+          `worst frame ${worst.toFixed(0)}ms${freezes ? `  ·  ${freezes} frame(s) over 250ms = a visible freeze` : ''}`,
+          `long tasks  ${r.longTasks.length}${r.longTasks.length ? ` (worst ${Math.max(...r.longTasks).toFixed(0)}ms)` : ''}`,
+          '',
+          `images      ${r.imgCount} files, ${kb(r.imgBytes)} total (as delivered: originals, not preview variants)`,
+          ...(r.topImgs.length
+            ? [`heaviest    ${r.topImgs.map(i => `${i.name} ${kb(i.bytes)}`).join('  ·  ')}`]
+            : []),
+          ...(r.layers.length
+            ? ['', 'full-screen composited layers (a classic other half of the problem):',
+              ...r.layers.map(l => `  ${l}`)]
+            : []),
+          '',
+          r.imgBytes > 5 * 1024 * 1024
+            ? `⚠ ${kb(r.imgBytes)} of images is the first thing to fix — reference the .webp siblings instead of the PNG masters.`
+            : null,
+          dropRatio > 25 && r.layers.length
+            ? '⚠ Both heavy layers and dropped frames present. These are usually ADDITIVE — test removing them one at a time AND together before concluding.'
+            : null,
+          '',
+          'Numbers are for A/B comparison on this 1-vCPU box, not the user\'s device.',
+        ].filter(l => l !== null);
+        return asText(lines.join('\n'));
+      } catch (err) {
+        return { content: [{ type: 'text', text: `profile_scroll failed: ${err?.message || String(err)}` }], isError: true };
+      } finally {
+        await browser?.close().catch(() => {});
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/publish-site.js

@@ -0,0 +1,102 @@
+/**
+ * mcp/tools/publish-site.js — publish_site MCP tool（2026-08-02）
+ *
+ * agent 版的「一键上线」：把任务里的目录站点发到 Cloudflare Pages 公网。
+ * 与站点窗的上线按钮共用 lib/site-publish.js 的全部闸门 —— 额度和权限按
+ * **项目 owner** 算（basic 档不能发、pro 档每人 2 个；档位见 auth/tier.js），不是"谁触发算谁"。
+ *
+ * 发到公网是外发动作：工具描述里写死"用户明确要求才调"。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { getProject } from '../../../projects/store.js';
+import { getUserById } from '../../../auth/users-store.js';
+import { publishSite, unpublishSite, lookupPublished } from '../../../lib/site-publish.js';
+
+/**
+ * @param {object} deps
+ * @param {string} [deps.projectId]
+ */
+export function makePublishSiteTool({ projectId }) {
+  return tool(
+    'publish_site',
+    `Publish a site task to the public web (Cloudflare Pages), update an already
+published site, or take it offline.
+
+Call this ONLY when the user explicitly asks to put the site online / update the
+live version / take it down. Never publish unprompted — going public is the
+user's call, not yours.
+
+action:
+- "publish": deploy the current files. First publish returns the permanent URL
+  (a brand-new domain may take a minute or two to start resolving); republishing
+  keeps the same URL.
+- "unpublish": delete the deployment; the public URL dies immediately.
+- "status": just report whether this task is published and at which URL.
+
+If the workspace contains more than one site, the tool refuses to guess and lists
+the candidates — pass "root" to name the one to publish ("." = the workspace root).
+Each site holds ONE public URL, keyed by its own root directory.
+
+**The public domain**: by default it is derived from the site's root directory
+name; Chinese names slug down to nothing, so those fall back to a short hash
+("a1b2c3.share..."). Pass "slug" to choose a readable one — do that whenever the
+site has a name worth showing, because the URL is what the user hands to other
+people. A slug is claimed on first publish and reused on every republish.
+
+**Verifying a fresh publish**: a brand-new domain needs a certificate issued
+before https works; until then screenshot_url fails with an SSL error. This tool
+now waits for it and tells you whether it is ready. Also note Cloudflare Pages
+serves the site's own 404.html for unknown paths — an HTTP 200 does NOT prove a
+path exists, check the content type and body.
+
+The user's publish quota and permissions apply (basic-tier accounts cannot publish;
+pro accounts have a per-user site limit). If the tool returns a quota or
+permission error, relay it as-is — do not retry.`,
+    {
+      task: z.string().describe(
+        '站点标识：站点根目录的相对路径（工作区根上那个站传 "."）。'
+        + '不确定就传 "." —— 只有一个站时工具会自己认出来'),
+      action: z.enum(['publish', 'unpublish', 'status']).default('publish'),
+      root: z.string().optional().describe(
+        '有多个平行站点时点名要发布哪个（相对工作区根，根上那个站传 "."）。单站点省略'),
+      slug: z.string().optional().describe(
+        '自选公网域名前缀，如 "chenxi" → chenxi.share.<域>。'
+        + '小写字母开头、3-32 位小写字母/数字/连字符。被占用会明确报错让你换一个'),
+    },
+    async ({ task, action, root, slug }) => {
+      const asText = (text) => ({ content: [{ type: 'text', text }] });
+      try {
+        const project = getProject(projectId);
+        if (!project) return asText('错误：项目不存在');
+        const owner = project.ownerId ? getUserById(project.ownerId) : null;
+        if (!owner) return asText('错误：找不到项目归属用户，不能发布');
+
+        if (action === 'status') {
+          const site = await lookupPublished(projectId, task);
+          return asText(site
+            ? `已发布：${site.url}（站点根 ${site.task}，最近发布 ${site.lastPublishedAt}）`
+            : '未发布');
+        }
+        if (action === 'unpublish') {
+          const removed = await unpublishSite({ projectId, task });
+          return asText(removed ? '已下线，公网地址即刻失效。' : '本来就没有发布。');
+        }
+        const r = await publishSite({ projectId, task, root, slug, user: owner });
+        return asText([
+          `已上线：${r.site.url}`,
+          `发布的是 ${r.root === '.' ? '工作区根' : `${r.root}/`}，${r.files} 个文件，入口 ${r.entry || '(无 html)'}`,
+          r.certReady === true
+            ? '证书已就绪，现在就能 screenshot_url 自检。'
+            : (r.certReady === false
+              ? '⚠ 证书还没签发完（等了 150 秒，通常 2-3 分钟）—— 现在截图会拿到 SSL 错误，过一会儿再试。'
+              : '重新发布地址不变。'),
+          r.warning ? `注意：${r.warning}` : null,
+        ].filter(Boolean).join('\n'));
+      } catch (err) {
+        return asText(`发布操作失败：${err.message}`);
+      }
+    },
+  );
+}