@xiaobuyu/nodesign 0.0.1

package/server/engine/mcp/tools/get-computed-styles.js

@@ -0,0 +1,164 @@
+/**
+ * mcp/tools/get-computed-styles.js — get_computed_styles MCP tool
+ *
+ * 拿一组元素在 canvas.html 真实渲染后的 computed style（不是 inline 也不是
+ * CSS 文件里的 raw 值）—— agent 不用猜"用户看到的字号实际是多少 px"，直接调。
+ *
+ * 典型场景：
+ *   - "把 H1 字号缩小一点" → 先拿当前 H1 是多少 px 再决定改多少
+ *   - "对比度够不够" → 拿 color 和 background-color 算对比度
+ *
+ * 默认拿一组常用样式属性（color/fontSize/fontFamily/...）；agent 可以传
+ * props 数组只拿需要的（省 token）。
+ */
+
+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 DEFAULT_PROPS = [
+  'color', 'backgroundColor',
+  'fontSize', 'fontFamily', 'fontWeight', 'lineHeight', 'letterSpacing',
+  'textAlign', 'textTransform',
+  'padding', 'margin',
+  'borderRadius', 'borderWidth', 'borderColor',
+  'display', 'width', 'height',
+];
+
+const MAX_RESULTS = 30;
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeGetComputedStylesTool({ workspaceRoot, projectId, sessionId, ctx: _ctx }) {
+  return tool(
+    'get_computed_styles',
+    `Get the actual rendered computed styles for elements matching a CSS
+selector in your artifact page (site page / deck). Returns the post-CSS-cascade values (px / rgb()
+form), not raw stylesheet declarations.
+
+Use when:
+- Before changing a style property, check the current value (don't guess)
+- Verifying contrast ratios (need both color and backgroundColor)
+- Debugging why a layout looks wrong
+
+By default returns a generic style set; pass \`props\` to restrict to just
+the properties you care about (saves tokens).
+
+Returns up to 30 elements.`,
+    {
+      selector: z.string().min(1).describe('CSS selector to inspect. Plain CSS only — no playwright syntax (:has-text, >>, nth=), ASCII quotes not HTML entities (" breaks the parse)'),
+      props: z
+        .array(z.string())
+        .optional()
+        .describe('Optional: subset of CSS properties to read (camelCase, e.g. ["color","fontSize"]). Default: a generic set.'),
+      page: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Optional: scope to a specific page (prepends section[data-page="N"])'),
+      path: z.string().optional().describe(CANVAS_PATH_DESC),
+      live: z.boolean().optional().describe(LIVE_PARAM_DESC),
+    },
+    async ({ selector, props, page: pageIndex, path: relPath, live }) => {
+      if (!workspaceRoot) {
+        return {
+          content: [{ type: 'text', text: 'No workspace bound; cannot read computed styles.' }],
+          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;
+      const finalProps = (Array.isArray(props) && props.length > 0) ? props : DEFAULT_PROPS;
+
+      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, p, max }) => {
+          const els = Array.from(document.querySelectorAll(sel));
+          const total = els.length;
+          const slice = els.slice(0, max);
+          const items = slice.map((el) => {
+            const cs = getComputedStyle(el);
+            const styles = {};
+            for (const prop of p) {
+              try {
+                styles[prop] = cs[prop];
+              } catch {
+                styles[prop] = null;
+              }
+            }
+            return {
+              tag: el.tagName.toLowerCase(),
+              dataAnchor: el.getAttribute('data-anchor') || null,
+              text: (el.textContent || '').trim().slice(0, 80),
+              computed: styles,
+            };
+          });
+          return { items, total };
+        }, { sel: finalSelector, p: finalProps, 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})`
+          : '';
+
+        const degraded = degradedNote(opened);   // 契约：note 非空必须写进返回文本
+        return {
+          content: [{
+            type: 'text',
+            text: `${degraded ? `${degraded}\n\n` : ''}${acq.liveNote ? `${acq.liveNote}\n\n` : ''}Computed styles for ${result.total} element(s)${truncatedNote}:`
+              + `\n\n${JSON.stringify(result.items, null, 2)}`,
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `get_computed_styles failed: ${err?.message || String(err)}` }],
+          isError: true,
+        };
+      } finally {
+        await acq?.release?.();   // 一次性：关浏览器；live：松会话锁
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/get-pending-changes.js

@@ -0,0 +1,205 @@
+/**
+ * mcp/tools/get-pending-changes.js — get_pending_changes MCP tool
+ *
+ * 用户在 canvas 上的"直接编辑（双击文本改字）"和"评论"会被前端 push 到
+ * workspace/pending-changes.json。下次用户发 chat 消息时，turn.js 在
+ * composeUserMessage 里 prepend 一个 system 提示告诉 agent "有 N 处变更，
+ * 可调本工具查看详情"。agent 决定要不要拉详情。
+ *
+ * pending-changes.json schema：
+ *   {
+ *     items: [{
+ *       id: string,
+ *       kind: 'edit' | 'comment'
+ *           | 'pending-move' | 'pending-style' | 'pending-duplicate' | 'pending-delete'
+ *           | 'applied-move' | 'applied-style' | 'applied-duplicate',
+ *       anchor: { dataId, path, textHint, bbox },
+ *       aiContext: { tag, role?, pageInfo?, outerHtml?, computed?, siblings?,
+ *                    targetContainerTag?, alignmentHints? },
+ *       diff?: { oldText, newText },                          // edit 时有
+ *       text?: string,                                        // comment 时有
+ *       move?: { container: anchor, before: anchor|null },    // pending-move / -duplicate 时有
+ *       styleDelta?: { left?, top?, marginLeft?, ... },       // pending-style 时有
+ *       reactMount?: boolean,                                  // 涉及 React mount 区→改 JSX 源码
+ *       ts: ISO,
+ *     }]
+ *   }
+ *
+ * 2026-05-12 新增 4 个 pending-* kind（画布拖移工具产物）：
+ *   - pending-move      用户拖动元素跨/内容器；按 move.container + move.before 改 DOM 树位置
+ *   - pending-duplicate 用户 alt-drag 复制；先 clone source 再插入 target
+ *   - pending-style     用户 nudge / 调对齐；按 styleDelta 改 inline style 或 class
+ *   - pending-delete    用户按 Del 删元素；按 anchor 删 source 节点
+ *
+ *  reactMount=true 的 item 走 `<script id="__nd-app">` 里的 JSX 改动（不是改 HTML 段）。
+ *
+ * 2026-07-29 新增 applied-* kind（站点窗拖拽直接落盘）：用户在站点页拖完，
+ * 前端已把整页序列化写回文件 —— 这些是 FYI 记录（applied:true），**不要再应用一遍**，
+ * 只用来理解用户动了什么；有 path 字段指明改的是哪份文件。
+ *
+ * 拉完后建议调 mcp__nodesign__clear_pending_changes 清 buffer，避免重复处理。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+
+/** 一次调用最多附几张圈选截图（更早的留路径让 agent 按需自己读） */
+const MAX_REGION_SHOTS = 3;
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeGetPendingChangesTool({ workspaceRoot, ctx: _ctx }) {
+  return tool(
+    'get_pending_changes',
+    `Read the user's pending changes buffer — a list of direct edits, inline
+comments, and drag-tool moves the user made on the canvas in between chat
+turns.
+
+When to use:
+- You see a <system>用户在过去时段做了 N 处变更...</system> hint at the top
+  of the user's message → call this tool to read the actual changes.
+- The user references "the change I just made" / "the edit I did" / "the move
+  I just did" → check the buffer first.
+
+Each item has:
+- kind: one of
+    'edit'             (user changed text by double-clicking in the canvas —
+                        ALREADY saved to the file; informational)
+    'comment'          (user wrote a comment for an element)
+    'pending-move'     (user dragged an element to a new container/position)
+    'pending-duplicate'(user alt-dragged to copy an element to a new spot)
+    'pending-style'    (user nudged / adjusted alignment → inline style delta)
+    'pending-delete'   (user deleted an element)
+    'applied-move' / 'applied-style' / 'applied-duplicate'
+                       (user dragged inside a site page window — the frontend
+                        ALREADY serialized the page and wrote it to the file.
+                        Do NOT re-apply these; they are FYI so you know what
+                        the user changed. You may tidy the source afterwards
+                        — e.g. lift baked inline left/top into the stylesheet —
+                        but only if asked or clearly beneficial.)
+- path (optional): which file the change belongs to (workspace-relative, e.g. about.html or 稿件/about.html).
+  Absent = the current session's canvas.html.
+- anchor: stable element reference (dataId / path / textHint / bbox)
+- aiContext: element role, page info, outerHTML, computed styles, siblings,
+             plus targetContainerTag / alignmentHints for moves
+- diff (edit): { oldText, newText }
+- becameEmpty (edit): true means the user CLEARED that text. The element is still
+  in the source and still takes up vertical space — usually you should delete the
+  whole element, not just leave it empty. Ask if you are unsure.
+- text (comment): the comment body
+- linkedToEditId (comment, optional): when present, this comment is a follow-up
+  instruction tied to another pending edit (e.g. "for that drag I just did, keep
+  the neighbor element fixed"). Always read the linked edit and treat them as
+  one combined operation; both get cleared together.
+- move (pending-move / pending-duplicate): { container: anchor, before: anchor|null }
+- styleDelta (pending-style): { left?, top?, marginLeft?, ... }
+- reactMount: when true, the change touches a React mount subtree → modify
+              the JSX inside <script id="__nd-app"> rather than the static HTML
+
+'region-comment' items are different in shape — the user lassoed an AREA of
+the preview rather than clicking one element:
+- region: { x, y, w, h } in page CSS px, and viewport: the size they saw it at
+- elements: what sits inside that box, innermost-first, each with anchor / tag /
+  a text excerpt / its own rect / coverage (how much of it the box covers).
+  Containers much larger than the box are deliberately excluded — the user was
+  pointing at what's inside, not at the wrapper.
+- container: the innermost element that fully encloses the box — i.e. WHERE on
+  the page this is. The elements list alone can't tell you header from footer.
+- text: what they said about it (may be empty — the box itself is the message)
+- shot: a screenshot of that area (plus a little margin), attached to this
+  tool result as an image right after the JSON. Look at it: it is the ground
+  truth of what the user was looking at, and the elements list is only an
+  index into it.
+- docxPage (present when path is a .docx): the user lassoed on a rendered page
+  image of a word document — docxPage is the 1-based page number, region is in
+  page-image pixels, and there are NO elements/container (a page image has no
+  DOM). The shot is cropped from the same LibreOffice page render the user was
+  looking at. To act on it, edit the token JSON source and rebuild with
+  build_docx — never edit the .docx itself.
+
+After processing, call mcp__nodesign__clear_pending_changes to clear the
+buffer so subsequent turns don't see the same changes again.`,
+    {
+      // No params; reading is unconditional.
+      _placeholder: z.string().optional().describe('Unused; reserved for future filters'),
+    },
+    async () => {
+      try {
+        if (!workspaceRoot) {
+          return {
+            content: [{ type: 'text', text: 'No workspace bound; cannot read pending changes.' }],
+            isError: true,
+          };
+        }
+
+        const bufPath = path.join(workspaceRoot, 'pending-changes.json');
+        let buf = { items: [] };
+        try {
+          const raw = await fs.readFile(bufPath, 'utf8');
+          const parsed = JSON.parse(raw);
+          if (parsed && Array.isArray(parsed.items)) buf = parsed;
+        } catch (err) {
+          if (err.code !== 'ENOENT') throw err;
+          // file doesn't exist = empty buffer
+        }
+
+        const items = buf.items;
+        if (items.length === 0) {
+          return {
+            content: [{
+              type: 'text',
+              text: 'No pending changes. The user has not made any direct edits or comments since the last clear.',
+            }],
+          };
+        }
+
+        const content = [{
+          type: 'text',
+          text: `Pending changes (${items.length} item${items.length === 1 ? '' : 's'}):\n\n`
+            + JSON.stringify(items, null, 2),
+        }];
+
+        // 圈选的截图直接挂在结果里 —— 那张图就是用户当时看着的画面，让 agent
+        // 再去 Read 一次纯属多一跳，而且它多半不会主动去读。
+        // 只带最近 MAX_REGION_SHOTS 张：一次拉出十张图，token 全烧在这上面。
+        const shots = items.filter(it => it.kind === 'region-comment' && it.shot);
+        const attach = shots.slice(-MAX_REGION_SHOTS);
+        for (const it of attach) {
+          try {
+            const buf = await fs.readFile(path.join(workspaceRoot, it.shot));
+            content.push({ type: 'text', text: `↓ 圈选 ${it.id}（${it.path}）用户框住的那一块：`
+              + (it.shotNote ? `\n${it.shotNote}（所以这张图不等于用户当时看到的画面）` : '') });
+            content.push({ type: 'image', data: buf.toString('base64'), mimeType: 'image/webp' });
+          } catch (err) {
+            content.push({
+              type: 'text',
+              text: `圈选 ${it.id} 的截图读不到（${err?.code || err?.message}）—— 按 elements 清单和 region 坐标处理。`,
+            });
+          }
+        }
+        if (shots.length > attach.length) {
+          content.push({
+            type: 'text',
+            text: `另有 ${shots.length - attach.length} 张更早的圈选截图没有附上（一次最多 ${MAX_REGION_SHOTS} 张）。`
+              + `需要的话按 item 里的 shot 路径自己 Read。`,
+          });
+        }
+
+        return { content };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text',
+            text: `get_pending_changes failed: ${err?.message || String(err)}`,
+          }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/h3box-ssh.js

@@ -0,0 +1,84 @@
+/**
+ * mcp/tools/h3box-ssh.js — GPU 盒子 SSH 公用件（roll_film / paint_still 共用）
+ *
+ * 盒子 = featurize 按时租的 5090（.env NODESIGN_H3BOX_SSH/PORT/PASS，每次租机
+ * 都换）。密码走 sshpass -e（SSHPASS 环境变量），没配密码就当 key 认证。
+ */
+
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+
+/**
+ * 盒子总开关（2026-08-17）。
+ *
+ * 盒子是站主手动开关的物理机，但 SSH 地址常年配在 .env 里 —— 所以「机器关着」
+ * 跟「没配过」在代码里长得完全不一样：后者 boxConfig() 返回 null 能立刻兜底，
+ * 前者会一路 SSH 到超时才失败（paint_still 单张 240s、krea2 400s，整批还要乘
+ * 系数；roll_film 每镜 900s），agent 和用户一起干等几分钟，还看不出为什么。
+ *
+ * 这个开关让工具在**调用的第一行**就诚实说不可用。开机后把 .env 里那行改回 on
+ * （或整行删掉，默认就是 on）。它管的是整台机器：paint_still 的五个模型和
+ * roll_film 的 box 后端都住在上面。
+ */
+export const localBoxEnabled = () => (process.env.NODESIGN_LOCAL_BOX || 'on').toLowerCase() !== 'off';
+
+/** 关机时给 agent 的统一说辞：说清原因、给替代路径、明确别重试 */
+export const BOX_OFF_MSG = '本地 GPU 盒子当前关着（站主手动开关机）。这台机器上的东西'
+  + '现在都用不了：paint_still 的 noobai / noobai-eps / pony / anima / krea2 五个模型，'
+  + '以及 roll_film 的本地后端。转告用户，生图改走 generate_image；要用本地产线得先开机。'
+  + '别重试，重试也是同样的结果。';
+
+export function boxConfig() {
+  const target = process.env.NODESIGN_H3BOX_SSH || '';
+  if (!target) return null;
+  return {
+    target,
+    port: process.env.NODESIGN_H3BOX_PORT || '22',
+    pass: process.env.NODESIGN_H3BOX_PASS || '',
+  };
+}
+
+/** POSIX 单引号转义（远端 zsh/bash 规则相同） */
+export const shq = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;
+
+/**
+ * 跑一条 ssh/scp。永不 throw，resolve {code, out, err}；code=-1 表示本地 spawn 失败。
+ * @param {{target:string,port:string,pass:string}} box
+ * @param {'ssh'|'scp'} bin
+ */
+export function runBox(box, bin, args, { timeoutMs = 240_000, signal } = {}) {
+  return new Promise((resolve) => {
+    const env = { ...process.env };
+    let cmd = bin; let argv = args;
+    if (box.pass) {
+      env.SSHPASS = box.pass;
+      cmd = 'sshpass'; argv = ['-e', bin, ...args];
+    }
+    const child = spawn(cmd, argv, { stdio: ['ignore', 'pipe', 'pipe'], env });
+    let out = ''; let err = '';
+    child.stdout.on('data', (d) => { out = (out + d).slice(-8000); });
+    child.stderr.on('data', (d) => { err = (err + d).slice(-2000); });
+    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* */ } }, timeoutMs);
+    const onAbort = () => { try { child.kill('SIGKILL'); } catch { /* */ } };
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
+      resolve({ code, out, err });
+    });
+    child.on('error', (e) => { clearTimeout(timer); resolve({ code: -1, out, err: String(e.message) }); });
+  });
+}
+
+// 连接复用：首连付一次完整握手（跨境实测 ~4s），之后 10 分钟内的 ssh/scp 走同一条
+// 隧道，每次 ~0.1s。socket 名带主机+端口，换租新盒（端口必变）不会撞旧 socket；
+// master 空闲 10 分钟自灭，盒子重启后 auto 会自动弃掉死 socket 重连。
+const CTRL = [
+  '-o', 'ControlMaster=auto',
+  '-o', `ControlPath=${os.tmpdir()}/h3box-cm-%r@%h-%p`,
+  '-o', 'ControlPersist=600',
+];
+
+/** ssh 公共参数（-p 端口）；scp 用 scpArgs（-P 端口） */
+export const sshArgs = (box) => [...CTRL, '-o', 'StrictHostKeyChecking=no', '-o', 'ConnectTimeout=10', '-p', box.port, box.target];
+export const scpArgs = (box) => [...CTRL, '-o', 'StrictHostKeyChecking=no', '-o', 'ConnectTimeout=10', '-P', box.port];

package/server/engine/mcp/tools/helpers/acquire-page.js

@@ -0,0 +1,82 @@
+/**
+ * helpers/acquire-page.js — 感知工具拿到"那一页"的唯一出口（2026-08-21）
+ *
+ * 两条路一个形状：
+ *   - `live: true`  → 产物会话里**现在这一页**（engine/perception/session.js），
+ *                      状态保留，用完不关，只松锁
+ *   - 否则          → 新开一只保真 chromium，openArtifactPage，goto，用完关 —— 可复现
+ *
+ * 老工具以前各自抄 launch→open→goto→close（七份），"没走成 http 要把 note 写进返回"
+ * 那条契约也是各自记各自漏。现在 goto 的超时容忍、退化 note、viaHttp 都在这一处出。
+ *
+ * 返回：{ page, live, viewport, note, viaHttp, gotoNote, liveNote, release() }
+ *   - note      非空 = 没走成 http（退回 file://），调用方照旧用 degradedNote(acq) 拼进返回文本
+ *   - gotoNote  非空 = load/networkidle 没等到（照样继续，caption 要说）
+ *   - liveNote  live 模式下告诉 agent：视口/设备参数被忽略、会话视口是多少
+ *   - release   **必须在 finally 里调**：一次性模式关浏览器，live 模式松会话锁
+ */
+import { openArtifactPage, launchPerceptionBrowser } from './perception-page.js';
+import { lockSession } from '../../../perception/session.js';
+
+/**
+ * @param {object} o
+ * @param {string} o.projectId
+ * @param {string} o.workspaceRoot
+ * @param {{absPath:string, relPath:string}} o.target   resolveCanvasTarget 的结果
+ * @param {{width:number,height:number}} [o.viewport]   一次性模式用；live 模式忽略
+ * @param {number} [o.deviceScaleFactor]                一次性模式用
+ * @param {boolean} [o.live]
+ * @param {string} [o.waitUntil]                        默认 networkidle（老工具的口径）
+ * @param {number} [o.timeout]
+ */
+export async function acquireArtifactPage({
+  projectId, workspaceRoot, target, viewport, deviceScaleFactor = 1, live = false,
+  waitUntil = 'networkidle', timeout = 15000,
+}) {
+  if (live) {
+    const { entry, release } = await lockSession(projectId);
+    if (target?.absPath && entry.target.absPath !== target.absPath) {
+      release();
+      throw new Error(`The live session is on ${entry.target.relPath}, not ${target.relPath}. `
+        + 'Either omit path (to inspect the live page), artifact_open that file first, or drop live:true.');
+    }
+    const vp = entry.viewport;
+    // 会话里可能已经站内导航过（index → about），报现在的页，不报当初开的那个
+    let now = entry.target.relPath;
+    try {
+      const u = new URL(entry.page.url());
+      if (/\/artifact-file\//.test(u.pathname)) now = decodeURIComponent(u.pathname.replace(/^.*\/artifact-file\//, ''));
+    } catch { /* */ }
+    const liveNote = `live session page (now at ${now}, viewport ${vp.width}x${vp.height} — current interaction state, `
+      + 'not a fresh load; viewport/device params are ignored here)';
+    return {
+      page: entry.page, live: true, viewport: vp, note: entry.note, viaHttp: entry.viaHttp,
+      gotoNote: null, liveNote, release: async () => release(),
+    };
+  }
+
+  const browser = await launchPerceptionBrowser();
+  try {
+    const opened = await openArtifactPage(browser, {
+      projectId, workspaceRoot, absPath: target.absPath, viewport, deviceScaleFactor, waitUntil, timeout,
+    });
+    let gotoNote = null;
+    try { await opened.goto(); } catch (err) {
+      if (!/Timeout/i.test(String(err?.message))) throw err;
+      gotoNote = `${waitUntil} not reached in ${Math.round(timeout / 1000)}s (slow/looping network activity) — captured anyway`;
+    }
+    return {
+      page: opened.page, live: false, viewport, note: opened.note, viaHttp: opened.viaHttp,
+      gotoNote, liveNote: null,
+      release: async () => { try { await browser.close(); } catch { /* */ } },
+    };
+  } catch (err) {
+    try { await browser.close(); } catch { /* */ }
+    throw err;
+  }
+}
+
+/** live 参数的统一说明文字（五个工具共用一句，别各说各的） */
+export const LIVE_PARAM_DESC = 'Inspect the page currently open in the artifact session (artifact_open) — its present '
+  + 'interaction state (opened menus, typed input, game state) instead of a fresh load. Viewport/device params '
+  + 'are ignored in live mode (the session has its own). Default false = fresh reproducible load.';