@xiaobuyu/nodesign 0.0.1 → 0.0.3

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

@@ -1,102 +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}`);
-      }
-    },
-  );
-}
+/**
+ * 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}`);
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/query-elements.js

@@ -1,195 +1,195 @@
-/**
- * mcp/tools/query-elements.js — query_elements MCP tool
- *
- * 用 CSS selector 在 canvas.html 里 querySelectorAll，返回每个元素的
- * { anchor, tag, text, bbox, layoutBox, dataAttrs } —— anchor schema 跟前端
- * lib/html-utils.js 的 serializeAnchor 一致，agent 可以直接拿这个 anchor
- * 喂回前端做精确选中（未来）或继续 query。
- *
- * 典型场景：
- *   - "把所有 H1 字号统一成 56" → query_elements({selector:'h1'}) 拿全清单
- *   - "找到 cover 上那个 cta 按钮" → query_elements({selector:'[data-anchor="cover-cta"]'})
- *
- * 限制：返回 max 50 条，溢出截断 + 文本提示。
- */
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-import { degradedNote } from './helpers/perception-page.js';
-import { acquireArtifactPage, LIVE_PARAM_DESC } from './helpers/acquire-page.js';
-import { resolveDeckSize, extractDeckAspect } from '../../../shared/deck.js';
-import { resolveCanvasTarget, CANVAS_PATH_DESC, KIND_SITE, requireBrowsable,
-} from '../../../lib/artifact-target.js';
-
-const MAX_RESULTS = 50;
-
-/**
- * @param {object} deps
- * @param {string} deps.workspaceRoot
- * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
- */
-export function makeQueryElementsTool({ workspaceRoot, projectId, sessionId, ctx: _ctx }) {
-  return tool(
-    'query_elements',
-    `Query elements in your artifact page (site page / deck) via CSS selector. Returns a list of
-matched elements with { anchor, tag, text, bbox, dataAttrs }.
-
-The anchor object (dataId / path / textHint / bbox) is the same schema used
-by the frontend selection system — you can reference it later to highlight
-or pin comments.
-
-Use when:
-- You need to inspect/operate on multiple elements matching a pattern
-  (all H1, all .cta, all data-anchor="page-N-title", etc.)
-- Before bulk-editing, get the current state list first
-- Verifying that a class / data-attr is applied where you expect
-
-Returns up to 50 matches; further results truncated with a hint.
-
-**bbox vs layoutBox** — bbox comes from getBoundingClientRect and INCLUDES CSS
-transforms; layoutBox (offsetTop/Left/Width/Height) is the layout box without
-them. Measure spacing with layoutBox, measure where-it-visually-sits with bbox.
-An element carrying an entry animation reports "transformed: true" — on those,
-bbox is offset by the animation and will give you impossible numbers.
-⚠️ **Plain CSS selectors only.** Playwright syntax (":has-text(...)", ">>",
-"nth=0") is NOT supported here and fails with a parser error. Use ASCII quotes,
-never HTML entities (""" reaches the selector literally and breaks it).`,
-    {
-      selector: z
-        .string()
-        .min(1)
-        .describe('CSS selector (e.g., "h1", ".accent", \'[data-anchor="cover-title"]\', \'section[data-page="2"] p\')'),
-      page: z
-        .number()
-        .int()
-        .min(1)
-        .optional()
-        .describe('Optional: scope query to a specific page (prepends section[data-page="N"] to selector)'),
-      path: z.string().optional().describe(CANVAS_PATH_DESC),
-      live: z.boolean().optional().describe(LIVE_PARAM_DESC),
-    },
-    async ({ selector, page: pageIndex, path: relPath, live }) => {
-      if (!workspaceRoot) {
-        return {
-          content: [{ type: 'text', text: 'No workspace bound; cannot query.' }],
-          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 };
-      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 };
-      }
-      // 站点没有 deck 比例：extractDeckAspect 找不到 __nd-deck-wrap 会静默回落到
-      // 16:9，于是按 1920x1080 量出来的盒子被当成真实布局报给 agent。站点按桌面档
-      // 1440 量，跟 screenshot_canvas 的 desktop 档一致。
-      const dims = target.kind === KIND_SITE
-        ? { width: 1440, height: 900 }
-        : resolveDeckSize(extractDeckAspect(html));
-
-      const finalSelector = pageIndex
-        ? `section[data-page="${pageIndex}"] ${selector}`
-        : selector;
-
-      let acq;
-      try {
-        // 页面从统一口拿（helpers/acquire-page.js）：live:true = 会话里现在这一页；否则新开走 http
-        acq = await acquireArtifactPage({ projectId, workspaceRoot, target, live, viewport: { width: dims.width, height: dims.height } });
-        const page = acq.page;
-        const opened = acq;
-
-        const result = await page.evaluate(({ sel, max }) => {
-          const els = Array.from(document.querySelectorAll(sel));
-          const total = els.length;
-          const slice = els.slice(0, max);
-
-          const computePath = (el) => {
-            const segments = [];
-            let cur = el;
-            while (cur && cur !== document.body && cur.nodeType === 1) {
-              const tag = cur.tagName.toLowerCase();
-              const parent = cur.parentNode;
-              if (!parent || parent.nodeType !== 1) break;
-              const sameType = Array.from(parent.children).filter(c => c.tagName === cur.tagName);
-              const idx = sameType.indexOf(cur) + 1;
-              segments.unshift(sameType.length > 1 ? `${tag}:nth-of-type(${idx})` : tag);
-              cur = parent;
-            }
-            return segments.join(' > ');
-          };
-
-          const items = slice.map((el) => {
-            const r = el.getBoundingClientRect();
-            // anchor 单写：dataId 字段值改读 data-anchor（跟前端 serializeAnchor 一致）
-            const dataId = el.getAttribute('data-anchor') || null;
-            const text = (el.textContent || '').trim();
-            const dataAttrs = {};
-            for (const a of Array.from(el.attributes)) {
-              if (a.name.startsWith('data-')) dataAttrs[a.name] = a.value;
-            }
-            // layoutBox / transformed（2026-08-18）：bbox 走 getBoundingClientRect，
-            // **CSS transform 算在里面**。带入场动画的页面（这平台上绝大多数页面）
-            // 元素静止态常挂着 translateY(26px)，量间距会得出物理上不可能的结果 ——
-            // 有个 agent 因此差点断言"最后一节和页脚重叠了"，靠 25≈26 这个巧合才
-            // 反应过来。offset* 是布局盒，不含 transform，两个都给就不会误判。
-            const cs = getComputedStyle(el);
-            const transformed = cs.transform !== 'none' && cs.transform !== '';
-            return {
-              anchor: {
-                dataId,
-                path: computePath(el),
-                textHint: text.slice(0, 50),
-                bbox: { x: r.x, y: r.y, w: r.width, h: r.height },
-              },
-              tag: el.tagName.toLowerCase(),
-              text: text.slice(0, 200),
-              bbox: { x: r.x, y: r.y, w: r.width, h: r.height },
-              layoutBox: { x: el.offsetLeft, y: el.offsetTop, w: el.offsetWidth, h: el.offsetHeight },
-              ...(transformed ? { transformed: true } : {}),
-              dataAttrs,
-            };
-          });
-
-          return { items, total };
-        }, { sel: finalSelector, max: MAX_RESULTS });
-
-        if (result.total === 0) {
-          return {
-            content: [{
-              type: 'text',
-              text: `No elements match selector: ${finalSelector}`,
-            }],
-          };
-        }
-
-        const truncatedNote = result.total > MAX_RESULTS
-          ? ` (showing first ${MAX_RESULTS} of ${result.total} matches)`
-          : '';
-
-        const degraded = degradedNote(opened);   // 契约：note 非空必须写进返回文本
-        return {
-          content: [{
-            type: 'text',
-            text: `${degraded ? `${degraded}\n\n` : ''}${acq.liveNote ? `${acq.liveNote}\n\n` : ''}Matched ${result.total} element(s)${truncatedNote}:`
-              + `\n\n${JSON.stringify(result.items, null, 2)}`,
-          }],
-        };
-      } catch (err) {
-        return {
-          content: [{ type: 'text', text: `query_elements failed: ${err?.message || String(err)}` }],
-          isError: true,
-        };
-      } finally {
-        await acq?.release?.();   // 一次性：关浏览器；live：松会话锁
-      }
-    },
-  );
-}
+/**
+ * mcp/tools/query-elements.js — query_elements MCP tool
+ *
+ * 用 CSS selector 在 canvas.html 里 querySelectorAll，返回每个元素的
+ * { anchor, tag, text, bbox, layoutBox, dataAttrs } —— anchor schema 跟前端
+ * lib/html-utils.js 的 serializeAnchor 一致，agent 可以直接拿这个 anchor
+ * 喂回前端做精确选中（未来）或继续 query。
+ *
+ * 典型场景：
+ *   - "把所有 H1 字号统一成 56" → query_elements({selector:'h1'}) 拿全清单
+ *   - "找到 cover 上那个 cta 按钮" → query_elements({selector:'[data-anchor="cover-cta"]'})
+ *
+ * 限制：返回 max 50 条，溢出截断 + 文本提示。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { degradedNote } from './helpers/perception-page.js';
+import { acquireArtifactPage, LIVE_PARAM_DESC } from './helpers/acquire-page.js';
+import { resolveDeckSize, extractDeckAspect } from '../../../shared/deck.js';
+import { resolveCanvasTarget, CANVAS_PATH_DESC, KIND_SITE, requireBrowsable,
+} from '../../../lib/artifact-target.js';
+
+const MAX_RESULTS = 50;
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeQueryElementsTool({ workspaceRoot, projectId, sessionId, ctx: _ctx }) {
+  return tool(
+    'query_elements',
+    `Query elements in your artifact page (site page / deck) via CSS selector. Returns a list of
+matched elements with { anchor, tag, text, bbox, dataAttrs }.
+
+The anchor object (dataId / path / textHint / bbox) is the same schema used
+by the frontend selection system — you can reference it later to highlight
+or pin comments.
+
+Use when:
+- You need to inspect/operate on multiple elements matching a pattern
+  (all H1, all .cta, all data-anchor="page-N-title", etc.)
+- Before bulk-editing, get the current state list first
+- Verifying that a class / data-attr is applied where you expect
+
+Returns up to 50 matches; further results truncated with a hint.
+
+**bbox vs layoutBox** — bbox comes from getBoundingClientRect and INCLUDES CSS
+transforms; layoutBox (offsetTop/Left/Width/Height) is the layout box without
+them. Measure spacing with layoutBox, measure where-it-visually-sits with bbox.
+An element carrying an entry animation reports "transformed: true" — on those,
+bbox is offset by the animation and will give you impossible numbers.
+⚠️ **Plain CSS selectors only.** Playwright syntax (":has-text(...)", ">>",
+"nth=0") is NOT supported here and fails with a parser error. Use ASCII quotes,
+never HTML entities (""" reaches the selector literally and breaks it).`,
+    {
+      selector: z
+        .string()
+        .min(1)
+        .describe('CSS selector (e.g., "h1", ".accent", \'[data-anchor="cover-title"]\', \'section[data-page="2"] p\')'),
+      page: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Optional: scope query to a specific page (prepends section[data-page="N"] to selector)'),
+      path: z.string().optional().describe(CANVAS_PATH_DESC),
+      live: z.boolean().optional().describe(LIVE_PARAM_DESC),
+    },
+    async ({ selector, page: pageIndex, path: relPath, live }) => {
+      if (!workspaceRoot) {
+        return {
+          content: [{ type: 'text', text: 'No workspace bound; cannot query.' }],
+          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 };
+      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 };
+      }
+      // 站点没有 deck 比例：extractDeckAspect 找不到 __nd-deck-wrap 会静默回落到
+      // 16:9，于是按 1920x1080 量出来的盒子被当成真实布局报给 agent。站点按桌面档
+      // 1440 量，跟 screenshot_canvas 的 desktop 档一致。
+      const dims = target.kind === KIND_SITE
+        ? { width: 1440, height: 900 }
+        : resolveDeckSize(extractDeckAspect(html));
+
+      const finalSelector = pageIndex
+        ? `section[data-page="${pageIndex}"] ${selector}`
+        : selector;
+
+      let acq;
+      try {
+        // 页面从统一口拿（helpers/acquire-page.js）：live:true = 会话里现在这一页；否则新开走 http
+        acq = await acquireArtifactPage({ projectId, workspaceRoot, target, live, viewport: { width: dims.width, height: dims.height } });
+        const page = acq.page;
+        const opened = acq;
+
+        const result = await page.evaluate(({ sel, max }) => {
+          const els = Array.from(document.querySelectorAll(sel));
+          const total = els.length;
+          const slice = els.slice(0, max);
+
+          const computePath = (el) => {
+            const segments = [];
+            let cur = el;
+            while (cur && cur !== document.body && cur.nodeType === 1) {
+              const tag = cur.tagName.toLowerCase();
+              const parent = cur.parentNode;
+              if (!parent || parent.nodeType !== 1) break;
+              const sameType = Array.from(parent.children).filter(c => c.tagName === cur.tagName);
+              const idx = sameType.indexOf(cur) + 1;
+              segments.unshift(sameType.length > 1 ? `${tag}:nth-of-type(${idx})` : tag);
+              cur = parent;
+            }
+            return segments.join(' > ');
+          };
+
+          const items = slice.map((el) => {
+            const r = el.getBoundingClientRect();
+            // anchor 单写：dataId 字段值改读 data-anchor（跟前端 serializeAnchor 一致）
+            const dataId = el.getAttribute('data-anchor') || null;
+            const text = (el.textContent || '').trim();
+            const dataAttrs = {};
+            for (const a of Array.from(el.attributes)) {
+              if (a.name.startsWith('data-')) dataAttrs[a.name] = a.value;
+            }
+            // layoutBox / transformed（2026-08-18）：bbox 走 getBoundingClientRect，
+            // **CSS transform 算在里面**。带入场动画的页面（这平台上绝大多数页面）
+            // 元素静止态常挂着 translateY(26px)，量间距会得出物理上不可能的结果 ——
+            // 有个 agent 因此差点断言"最后一节和页脚重叠了"，靠 25≈26 这个巧合才
+            // 反应过来。offset* 是布局盒，不含 transform，两个都给就不会误判。
+            const cs = getComputedStyle(el);
+            const transformed = cs.transform !== 'none' && cs.transform !== '';
+            return {
+              anchor: {
+                dataId,
+                path: computePath(el),
+                textHint: text.slice(0, 50),
+                bbox: { x: r.x, y: r.y, w: r.width, h: r.height },
+              },
+              tag: el.tagName.toLowerCase(),
+              text: text.slice(0, 200),
+              bbox: { x: r.x, y: r.y, w: r.width, h: r.height },
+              layoutBox: { x: el.offsetLeft, y: el.offsetTop, w: el.offsetWidth, h: el.offsetHeight },
+              ...(transformed ? { transformed: true } : {}),
+              dataAttrs,
+            };
+          });
+
+          return { items, total };
+        }, { sel: finalSelector, max: MAX_RESULTS });
+
+        if (result.total === 0) {
+          return {
+            content: [{
+              type: 'text',
+              text: `No elements match selector: ${finalSelector}`,
+            }],
+          };
+        }
+
+        const truncatedNote = result.total > MAX_RESULTS
+          ? ` (showing first ${MAX_RESULTS} of ${result.total} matches)`
+          : '';
+
+        const degraded = degradedNote(opened);   // 契约：note 非空必须写进返回文本
+        return {
+          content: [{
+            type: 'text',
+            text: `${degraded ? `${degraded}\n\n` : ''}${acq.liveNote ? `${acq.liveNote}\n\n` : ''}Matched ${result.total} element(s)${truncatedNote}:`
+              + `\n\n${JSON.stringify(result.items, null, 2)}`,
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `query_elements failed: ${err?.message || String(err)}` }],
+          isError: true,
+        };
+      } finally {
+        await acq?.release?.();   // 一次性：关浏览器；live：松会话锁
+      }
+    },
+  );
+}