@attson/atwebpilot-mcp 0.0.73 → 0.0.75

package/README.md

@@ -17,11 +17,11 @@ Claude Code：
 **不需要手填端口。** 从 Plan 33 起是配对流程：
 
 1. 会话启动时**不绑任何端口** —— 不碰网页的会话零副作用。
-2. AI 第一次调 `list_tabs` / `browser_*` 时才绑一个空闲端口，尝试用系统默认浏览器打开配对页，并立即在 MCP 进度消息中显示配对 URL。
-3. 你在浏览器里点「允许」，扩展即接入；正在等待的调用会自动继续，无需告诉 AI 授权成功或手动重试。
+2. AI 第一次调 `list_tabs` / `pairing_status` 时才绑一个空闲端口，尝试用系统默认浏览器打开配对页，并立即返回 `pairing_required + pair_url`，不阻塞等待。
+3. 你在浏览器里点「允许」，扩展即接入；AI 用轻量 `pairing_status` 确认连接后再读取 tab，不重复阻塞式调用。
 4. 之后本机的会话都免确认（信任是安装级的）；端口能复用时连配对页都不会弹。
 
-首次调用默认等待授权 90 秒。若系统未弹出浏览器，可直接打开进度消息中的 URL；拒绝或超时也会返回明确错误和配对页地址。授权成功只以扩展实际建立连接并发送 `HELLO` 为准。
+若系统未弹出浏览器，可直接打开返回结果中的 `pair_url`。授权成功只以扩展实际建立连接并发送 `HELLO` 为准；打开配对页本身不代表已连接。
 
 多个 Codex / Claude Code 会话可以同时接入同一个浏览器，各自一条连接。可在扩展设置 →
 Coordinator 查看已接入的会话、单独断开，或撤销信任。
@@ -48,9 +48,9 @@ listen 端口的能力，所以方向只能如此。这也是配对页存在的
 
 ## 工具面
 
-- 控制面 4 个：`list_tabs / open_session / close_session / get_quota`
+- 控制面 5 个：`pairing_status / list_tabs / open_session / close_session / get_quota`
 - 发现 1 个：`browser_discoverTools` —— 已知工具时直接传 `enable: [...]`，已知分组时直接传 `enableGroups: ["export", ...]`；只有两者都未知时才不带参数读取目录。启用后会加入本进程的 `tools/list`（发送 `tools/list_changed`），并直接返回完整 schema。
-- 执行面默认 **core 31 个** `browser_*`：浏览 / 采集 / 填表 / 导航 / 截图 闭环所需的工具。其余 20 个由 AI 按需 `discoverTools` 拉取，用户不用配置。
+- 执行面在浏览器连接前不进入 `tools/list`；连接确认后加载默认 **core 31 个** `browser_*`。其余 20 个由 AI 按需 `discoverTools` 拉取，用户不用配置。
 - 不暴露 `askUser`（MCP 会话没有人在侧边栏应答）和 `attachTab` / `detachTab`（目标 tab 已由 `open_session` 绑定）。
 
 MCP 层的描述是精简英文（≈2.5k tokens for core），侧边栏内置 LLM 仍用中文长描述；两者共享同一份 `TOOL_DEFS`，靠 `mcp` 字段区分。
@@ -65,8 +65,8 @@ hover / uploadFile / scroll / waitFor`）；`browser_storage` 也不会列出，
 
 | 值 | 效果 |
 |---|---|
-| `core`（默认） | 31 个核心工具 + `browser_discoverTools`，其余按需发现 |
-| `full` | 一开始就全部列出（51 个），适合不想让 AI 多一步发现的用户 |
+| `core`（默认） | 连接前仅控制面；连接后 31 个核心工具 + `browser_discoverTools` |
+| `full` | 连接前仍仅控制面；连接后列出全部 51 个工具 |
 
 无法识别的值（包括已移除的 `parity`）按 `core` 处理，并往 stderr 打一条提示。
 
@@ -77,12 +77,14 @@ hover / uploadFile / scroll / waitFor`）；`browser_storage` 也不会列出，
 ```bash
 pnpm analyze:sessions
 pnpm analyze:sessions -- --since 7d --clients claude --format json
+pnpm analyze:sessions -- --since 24h --clients codex --latest-session
 ```
 
 分析器只读扫描 `~/.claude/projects` 与 `~/.codex/sessions` 中最近 30 天的
-JSONL，识别真实 AtWebPilot 工具调用及重复验证、固定等待、重复截图、可批量填表等
+JSONL，识别真实 AtWebPilot 工具调用及重复验证、固定等待、重复截图、可批量填表、配对超时与无状态重试等
 模式。输出只包含聚合计数、参数字段名与不可逆指纹；不会输出或保存 prompt、参数值、
-工具结果正文、凭证或绝对会话路径。使用 `--help` 查看目录覆盖等选项。
+工具结果正文、凭证或绝对会话路径。Codex 嵌套调用会关联 wait cell 的耗时、错误以及
+cached/uncached token；使用 `--latest-session` 只看最近一条真实使用记录。
 
 ### 从 0.0.70 及更早版本迁移
 

package/dist/index.js

@@ -895,7 +895,9 @@ var Coordinator = class {
     return session;
   }
   closeSession(id) {
+    const session = this.sessions.get(id);
     this.sessions.close(id);
+    if (session) this.notifySessionClosed(session);
   }
   // === Tool calls ===
   validateCall(input) {
@@ -920,8 +922,22 @@ var Coordinator = class {
   // === Periodic housekeeping ===
   tick() {
     const expired_sessions = this.sessions.tick();
+    for (const id of expired_sessions) {
+      const session = this.sessions.get(id);
+      if (session) this.notifySessionClosed(session);
+    }
     return { expired_sessions };
   }
+  notifySessionClosed(session) {
+    void this.hub.send(session.worker_id, {
+      type: "CLOSE_SESSION",
+      nonce: this.idGen.next("nonce"),
+      ts: this.clock.now(),
+      protocol_version: PROTOCOL_VERSION,
+      session_id: session.id
+    }).catch(() => {
+    });
+  }
 };
 
 // src/mcp-server.ts
@@ -930,14 +946,19 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprot
 
 // src/control-tools.ts
 var CONTROL_TOOLS = [
+  {
+    name: "pairing_status",
+    description: "Start or check browser pairing without waiting. Returns connected or pairing_required with the pair URL.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
   {
     name: "list_tabs",
-    description: "\u5217\u51FA\u6D4F\u89C8\u5668\u53EF\u7528\u6807\u7B7E\u9875\uFF1A[{tab_id,url,title}]\u3002\u82E5\u6269\u5C55\u5C1A\u672A\u8FDE\u63A5\uFF0C\u9996\u6B21\u8C03\u7528\u4F1A\u5C1D\u8BD5\u81EA\u52A8\u6253\u5F00\u914D\u5BF9\u9875\u5E76\u7B49\u5F85\u6388\u6743\uFF08\u6700\u591A 90 \u79D2\uFF09\uFF0C\u7B49\u5F85\u671F\u95F4\u4F1A\u901A\u77E5\u5B9E\u9645\u914D\u5BF9 URL\u3002\u5148\u8C03\u5B83\u62FF tab_id\u3002",
+    description: "List browser tabs. If pairing is needed, opens the pair page and immediately returns pairing_required with its URL; wait for user approval, then call pairing_status instead of retrying this tool.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false }
   },
   {
     name: "open_session",
-    description: "\u4E3A\u67D0\u4E2A tab \u5F00\u4E00\u4E2A\u4F1A\u8BDD\uFF0C\u8FD4\u56DE session_id\uFF1B\u540E\u7EED browser_* \u5DE5\u5177\u90FD\u5E26\u8FD9\u4E2A session_id\u3002capabilities \u7701\u7565=\u6388\u4E88\u5168\u90E8\u80FD\u529B\u3002",
+    description: "Open a session for a tab from list_tabs. Returns immediately with PAIRING_REQUIRED if the browser is not connected.",
     inputSchema: {
       type: "object",
       required: ["tab_id"],
@@ -2264,16 +2285,46 @@ function locate(source, offset) {
 }
 
 // src/handlers.ts
-async function handleListTabs(deps, onPairingRequired) {
+function singleWorkerId(c, pairUrl) {
+  const workers = c.workers.list();
+  if (workers.length === 0) {
+    throw new Error(
+      "PAIRING_REQUIRED: \u6D4F\u89C8\u5668\u5C1A\u672A\u8FDE\u63A5\u3002" + (pairUrl ? `\u8BF7\u5728\u6D4F\u89C8\u5668\u4E2D\u5B8C\u6210\u914D\u5BF9\uFF1A${pairUrl}` : "\u8BF7\u5148\u8C03\u7528 pairing_status \u83B7\u53D6\u914D\u5BF9\u9875\u3002")
+    );
+  }
+  if (workers.length > 1) throw new Error("\u68C0\u6D4B\u5230\u591A\u4E2A\u6D4F\u89C8\u5668\u8FDE\u5165\uFF1Bv1 \u4EC5\u652F\u6301\u5355 worker\uFF0C\u8BF7\u53EA\u4FDD\u7559\u4E00\u4E2A\u8FDE\u63A5");
+  return workers[0].id;
+}
+async function handlePairingStatus(deps) {
   const { coordinator } = await deps.ensure();
-  const workerId = await deps.waitForWorker(void 0, onPairingRequired);
-  const w = coordinator.workers.get(workerId);
-  if (!w) throw new Error(`worker ${workerId} disconnected while opening browser context`);
-  return { tabs: w.available_tabs };
+  const workers = coordinator.workers.list();
+  if (workers.length > 1) {
+    throw new Error("\u68C0\u6D4B\u5230\u591A\u4E2A\u6D4F\u89C8\u5668\u8FDE\u5165\uFF1Bv1 \u4EC5\u652F\u6301\u5355 worker\uFF0C\u8BF7\u53EA\u4FDD\u7559\u4E00\u4E2A\u8FDE\u63A5");
+  }
+  if (workers.length === 1) {
+    return { status: "connected", tab_count: workers[0].available_tabs.length };
+  }
+  const pairUrl = deps.pairUrl();
+  if (!pairUrl) throw new Error("PAIRING_REQUIRED: \u914D\u5BF9\u670D\u52A1\u5DF2\u542F\u52A8\uFF0C\u4F46\u914D\u5BF9\u9875\u5C1A\u4E0D\u53EF\u7528");
+  return { status: "pairing_required", pair_url: pairUrl };
+}
+async function handleListTabs(deps) {
+  const { coordinator } = await deps.ensure();
+  const workers = coordinator.workers.list();
+  if (workers.length > 1) {
+    throw new Error("\u68C0\u6D4B\u5230\u591A\u4E2A\u6D4F\u89C8\u5668\u8FDE\u5165\uFF1Bv1 \u4EC5\u652F\u6301\u5355 worker\uFF0C\u8BF7\u53EA\u4FDD\u7559\u4E00\u4E2A\u8FDE\u63A5");
+  }
+  const worker = workers[0];
+  if (!worker) {
+    const pairUrl = deps.pairUrl();
+    if (!pairUrl) throw new Error("PAIRING_REQUIRED: \u914D\u5BF9\u670D\u52A1\u5DF2\u542F\u52A8\uFF0C\u4F46\u914D\u5BF9\u9875\u5C1A\u4E0D\u53EF\u7528");
+    return { status: "pairing_required", pair_url: pairUrl, tabs: [] };
+  }
+  return { status: "connected", tabs: worker.available_tabs };
 }
-async function handleOpenSession(deps, args, onPairingRequired) {
+async function handleOpenSession(deps, args) {
   const { coordinator } = await deps.ensure();
-  const worker_id = await deps.waitForWorker(void 0, onPairingRequired);
+  const worker_id = singleWorkerId(coordinator, deps.pairUrl());
   const tab_id = String(args.tab_id);
   const requested = Array.isArray(args.capabilities) ? args.capabilities.map(String).filter(isCapability) : [];
   const scope = new Set(requested.length ? requested : CAPABILITIES);
@@ -2365,6 +2416,37 @@ import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 var SKILL_NAME = "atwebpilot-browser";
 var SKILL_DESCRIPTION = "Strategy + scenarios + safety rails for driving the AtWebPilot browser extension via MCP.";
+var TOPICS = {
+  quickstart: `# AtWebPilot quickstart
+
+1. Call list_tabs once. If it returns pairing_required, show pair_url and wait for the user to approve.
+2. After approval, call pairing_status. Do not retry list_tabs while status is unchanged.
+3. Call list_tabs when connected, choose a tab, then open_session with its tab_id.
+4. For interaction use browser_getPageInfo then browser_takeSnapshot; for broad reading use browser_createPageIndex.
+5. Prefer purpose-built tools and verified results. Use browser_discoverTools only for capabilities outside the connected core surface.
+6. Close the session when finished.
+`,
+  pairing: `# AtWebPilot pairing
+
+list_tabs and pairing_status never wait for browser authorization. A pairing_required result includes pair_url. Show that URL once and wait for the user to approve in the browser. Then call pairing_status; only call list_tabs after it reports connected. Never poll list_tabs or inspect the pair-page HTML.
+`,
+  reading: `# AtWebPilot reading
+
+Call browser_getPageInfo first. For articles, products, tables, and forms, use browser_createPageIndex, then browser_extractPageFields or browser_searchPageIndex, and read only the relevant block with browser_readPageBlock. Avoid browser_extractText on body and full-DOM reads. Use targeted screenshots only when visual evidence matters.
+`,
+  interaction: `# AtWebPilot interaction
+
+Refresh browser_takeSnapshot before each major action. Prefer uid-based browser_clickByUid/browser_fillByUid, and use browser_fillForm for independent fields. Use condition-based browser_waitFor rather than fixed delays. Keep submit, upload, storage, and credentialed network actions as explicit reviewed steps.
+`,
+  visual: `# AtWebPilot visual validation
+
+Use browser_resize and trust its actualViewport/verified result. Capture one browser_screenshot after the page settles; target a selector or page-index block and lower scale when detail permits. Do not follow browser_resize or browser_screenshot with browser_runJS that only re-reads viewport dimensions.
+`,
+  debugging: `# AtWebPilot debugging
+
+Read browser_consoleMessages first, then browser_networkRequests summaries. Arm recorder bodies only when needed, reproduce once, and fetch one browser_networkRequestDetail. Poll incrementally with sinceId. Check backend and degradedReason before treating missing events as proof.
+`
+};
 var cached = null;
 function locateSkillFile() {
   let here = dirname(fileURLToPath(import.meta.url));
@@ -2379,7 +2461,13 @@ function locateSkillFile() {
   }
   return join(dirname(fileURLToPath(import.meta.url)), "../../../skill/SKILL.md");
 }
-function readSkillBundle() {
+function readSkillBundle(rawTopic = "quickstart") {
+  const topic = rawTopic == null ? "quickstart" : String(rawTopic);
+  if (topic !== "full") {
+    const content = TOPICS[topic];
+    if (!content) throw new Error(`Unknown skill topic: ${topic}`);
+    return { name: SKILL_NAME, description: SKILL_DESCRIPTION, content };
+  }
   if (cached == null) {
     try {
       cached = readFileSync(locateSkillFile(), "utf-8");
@@ -2396,15 +2484,29 @@ ${SKILL_DESCRIPTION}
 }
 var SKILL_TOOL = {
   name: "atwebpilot_skill_read",
-  description: "Return the `atwebpilot-browser` skill bundle \u2014 a recommended tool-usage flow, scenarios, and safety rails for driving AtWebPilot's browser tools.",
-  inputSchema: { type: "object", properties: {}, required: [] }
+  description: "Return concise AtWebPilot guidance by topic. Defaults to quickstart; request full only when detailed reference is necessary.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      topic: {
+        type: "string",
+        enum: ["quickstart", "pairing", "reading", "interaction", "visual", "debugging", "full"],
+        description: "Guidance section; quickstart is the token-efficient default"
+      }
+    },
+    required: [],
+    additionalProperties: false
+  }
 };
 
 // src/mcp-server.ts
 var ALL_BROWSER_TOOLS = generateBrowserTools("full");
 var BROWSER_BY_NAME = new Map(ALL_BROWSER_TOOLS.map((t) => [t.name, t]));
 function createToolState(mode) {
-  return { advertised: new Set(generateBrowserTools(mode).map((t) => t.name)) };
+  return {
+    advertised: new Set(generateBrowserTools(mode).map((t) => t.name)),
+    browserSurfaceVisible: false
+  };
 }
 var DEFAULT_STATE = createToolState(readToolMode(process.env));
 var LEGACY_TOOLS = [
@@ -2438,7 +2540,7 @@ function workerToolSupport(deps) {
 }
 function buildToolList(deps, state = DEFAULT_STATE) {
   const supported = workerToolSupport(deps);
-  const browser = ALL_BROWSER_TOOLS.filter((t) => state.advertised.has(t.name)).filter((t) => !supported || t.builtinTools.every((b) => supported.has(b)));
+  const browser = state.browserSurfaceVisible || supported ? ALL_BROWSER_TOOLS.filter((t) => state.advertised.has(t.name)).filter((t) => !supported || t.builtinTools.every((b) => supported.has(b))) : [];
   return [
     { name: SKILL_TOOL.name, description: SKILL_TOOL.description, inputSchema: SKILL_TOOL.inputSchema },
     ...CONTROL_TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
@@ -2462,10 +2564,10 @@ function toolResult(gen, data) {
   return { content };
 }
 var fail2 = (message) => ({ content: [{ type: "text", text: message }], isError: true });
-async function dispatchCall(deps, name, args, onPairingRequired, state = DEFAULT_STATE, onListChanged) {
+async function dispatchCall(deps, name, args, state = DEFAULT_STATE, onListChanged) {
   try {
     if (name === SKILL_TOOL.name) {
-      const bundle = readSkillBundle();
+      const bundle = readSkillBundle(args.topic);
       return { content: [{ type: "text", text: bundle.content }] };
     }
     if (name === DISCOVER_TOOL.name) {
@@ -2479,8 +2581,21 @@ async function dispatchCall(deps, name, args, onPairingRequired, state = DEFAULT
       const { changed: _c, ...body } = r;
       return ok(body);
     }
-    if (name === "list_tabs") return ok(await handleListTabs(deps, onPairingRequired));
-    if (name === "open_session") return ok(await handleOpenSession(deps, args, onPairingRequired));
+    if (name === "pairing_status") {
+      const result = await handlePairingStatus(deps);
+      if (result.status === "connected") await revealBrowserSurface(state, onListChanged);
+      return ok(result);
+    }
+    if (name === "list_tabs") {
+      const result = await handleListTabs(deps);
+      if (result.status === "connected") await revealBrowserSurface(state, onListChanged);
+      return ok(result);
+    }
+    if (name === "open_session") {
+      const result = await handleOpenSession(deps, args);
+      await revealBrowserSurface(state, onListChanged);
+      return ok(result);
+    }
     if (name === "close_session") return ok(await handleCloseSession(deps, args));
     if (name === "get_quota") return ok(await handleGetQuota(deps, args));
     const gen = BROWSER_BY_NAME.get(name);
@@ -2490,33 +2605,19 @@ async function dispatchCall(deps, name, args, onPairingRequired, state = DEFAULT
     return fail2(e instanceof Error ? e.message : String(e));
   }
 }
+async function revealBrowserSurface(state, onListChanged) {
+  if (state.browserSurfaceVisible) return;
+  state.browserSurfaceVisible = true;
+  await onListChanged?.();
+}
 function createMcpServer(deps, state = DEFAULT_STATE) {
   const server = new Server(
     { name: "atwebpilot-mcp", version: "0.1.0" },
     { capabilities: { tools: { listChanged: true }, logging: {} } }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: buildToolList(deps, state) }));
-  server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const args = req.params.arguments ?? {};
-    const onPairingRequired = async (url) => {
-      const message = `\u7B49\u5F85\u6D4F\u89C8\u5668\u6388\u6743\uFF08\u6700\u591A 90 \u79D2\uFF09\u3002\u914D\u5BF9\u9875\uFF1A${url}\u3002\u5DF2\u5C1D\u8BD5\u81EA\u52A8\u6253\u5F00\uFF1B\u82E5\u672A\u5F39\u51FA\uFF0C\u8BF7\u624B\u52A8\u6253\u5F00\u3002`;
-      try {
-        const progressToken = extra._meta?.progressToken;
-        if (progressToken != null) {
-          await extra.sendNotification({
-            method: "notifications/progress",
-            params: { progressToken, progress: 0, total: 1, message }
-          });
-        } else {
-          await server.sendLoggingMessage({ level: "info", logger: "atwebpilot", data: message });
-        }
-      } catch (error) {
-        console.error(
-          "[atwebpilot-mcp] failed to report pairing URL:",
-          error instanceof Error ? error.message : String(error)
-        );
-      }
-    };
     const onListChanged = async () => {
       try {
         await server.sendToolListChanged();
@@ -2524,7 +2625,7 @@ function createMcpServer(deps, state = DEFAULT_STATE) {
         console.error("[atwebpilot-mcp] failed to send tools/list_changed:", error instanceof Error ? error.message : String(error));
       }
     };
-    return dispatchCall(deps, req.params.name, args, onPairingRequired, state, onListChanged);
+    return dispatchCall(deps, req.params.name, args, state, onListChanged);
   });
   return server;
 }
@@ -3011,6 +3112,7 @@ function processInfo(cwd = process.cwd()) {
 
 // src/ensure-hub.ts
 var DEFAULT_WORKER_WAIT_TIMEOUT_MS = 9e4;
+var SESSION_SWEEP_INTERVAL_MS = 3e4;
 function createHubEnsurer(d) {
   let bundle = null;
   let inflight = null;
@@ -3019,6 +3121,7 @@ function createHubEnsurer(d) {
   let opening = null;
   let hubIsClosed = false;
   let pendingDenial = false;
+  let sessionSweepTimer = null;
   let workerWait = null;
   const info = d.processInfo ?? processInfo();
   function connectedWorkerId(coordinator) {
@@ -3054,6 +3157,10 @@ function createHubEnsurer(d) {
   }
   function hubClosed() {
     hubIsClosed = true;
+    if (sessionSweepTimer) {
+      clearInterval(sessionSweepTimer);
+      sessionSweepTimer = null;
+    }
     if (workerWait) {
       finishWorkerWait({ error: new Error("\u6D4F\u89C8\u5668\u914D\u5BF9\u670D\u52A1\u5DF2\u5173\u95ED\u3002") });
     }
@@ -3082,6 +3189,8 @@ function createHubEnsurer(d) {
     }
     saveLastPort(port, d.identityDir);
     const coordinator = new Coordinator({ hub, clock: d.clock, idGen: d.idGen });
+    sessionSweepTimer = setInterval(() => coordinator.tick(), SESSION_SWEEP_INTERVAL_MS);
+    sessionSweepTimer.unref?.();
     installWire(hub, coordinator, d.clock, () => notifyWorkerReady(coordinator));
     pairUrlValue = `http://127.0.0.1:${port}/pair`;
     return { coordinator, hub, port };

package/dist/skill/SKILL.md

@@ -0,0 +1,261 @@
+# atwebpilot-browser skill
+
+A reusable strategy for agents that drive AtWebPilot's browser extension via
+MCP. Inspired by AIPex's [aipex-browser](https://github.com/AIPexStudio/AIPex)
+pattern: tool usage flow, common scenarios, safety rails — all in one bundle
+so an agent doesn't have to discover them from scratch.
+
+## Capabilities you have
+
+When this skill is loaded, you can drive any open tab through these tools
+(exposed by `@attson/atwebpilot-mcp`):
+
+### Control plane
+
+- `pairing_status` — start/check pairing without waiting. When it reports
+  `pairing_required`, show `pair_url` once and wait for browser approval.
+- `list_tabs` — enumerate Chrome tabs you can operate on. Entries carry `busy`
+  and `busy_label` when **another** Claude Code session is already driving that
+  tab, and `mine` for tabs you hold. This is advisory — nothing blocks you — but
+  contending for a tab another agent is typing into is rarely what you want.
+  Open your own with `browser_openTab` instead.
+- `open_session(tabId)` — pin a tab so subsequent calls target it
+- `close_session(sessionId)` — release the tab
+- `get_quota(sessionId)` — see remaining requests this minute
+
+### Browser-side built-ins (per session)
+
+All of these are prefixed `browser_` over MCP, e.g. `browser_takeSnapshot`.
+
+**Core — advertised after the browser connects (31):**
+
+| Class | Tools |
+|---|---|
+| page state（safe） | `takeSnapshot`, `findElements`, `getPageInfo`, `extractText` |
+| page index（safe） | `createPageIndex`, `searchPageIndex`, `readPageBlock`, `extractPageFields` |
+| interaction（caution） | `clickByUid`, `click`, `fillByUid`, `fillInput`, `fillForm`, `selectOption`, `setCheckbox`, `hover`, `pressKey`, `drag`, `drop`（files ⇒ dangerous）, `uploadFile`（dangerous） |
+| navigation / tabs | `navigate`（`action` 取 `back` / `forward` / `reload` / `goto`）, `listTabs`, `openTab`, `closeTab`, `resize`, `scroll` |
+| observation | `screenshot`, `waitFor`, `runJS`（static-scanned）, `consoleMessages`, `networkRequests` |
+
+**Discoverable — enable directly with `browser_discoverTools`:**
+
+| Group | Tools |
+|---|---|
+| `export` | `downloadImage`, `downloadSpreadsheet`（real `.xlsx`, multi-sheet） |
+| `network` | `httpRequest`（`withCredentials` ⇒ dangerous）, `networkRequestDetail`（dangerous）, `recorderConfig`, `handleDialog` |
+| `storage` | `storage`（`op` 取 `get` / `set`; dangerous） |
+| `browser-data` | `searchBookmarks`, `searchHistory` |
+| `inspect` | `inspectElement`, `highlight`（`text` or `selector`/`uid`）, `getValue`, `extractFormState` |
+| `legacy-dom` | `snapshotDOM`, `querySelector`, `querySelectorAll`, `extractImages`, `focus` |
+| `form` | `submitForm`（dangerous） |
+| `tabs` | `switchToTab`（只在用户明确要求把 Chrome 切到前台时使用） |
+
+`askUser`, `attachTab` and `detachTab` are **not** exposed: an MCP session has
+no human at the side panel, and its tab is already bound by `open_session`.
+
+### Getting more tools
+
+The default list is deliberately small. When a task needs something outside
+core — exporting a spreadsheet, calling an API with cookies, reading
+localStorage, inspecting a request body, searching history, debugging layout —
+do this, in order:
+
+1. If you know the tool, enable it directly with
+   `browser_discoverTools({ enable: ["browser_downloadSpreadsheet", ...] })`.
+   If you know only the group, use
+   `browser_discoverTools({ enableGroups: ["export"] })`.
+2. Call `browser_discoverTools({})` only when neither the tool nor group is
+   known. Enabled tools join `tools/list` (a `tools/list_changed` notification
+   is sent), and the response carries their full schemas for immediate use.
+
+**Do not** rebuild these capabilities with `runJS` (`fetch`, CSV blobs,
+`localStorage[...]`). It is slower, loses schema validation, and usually trips
+the dangerous-tier review that the purpose-built tool would have avoided.
+
+`ATWEBPILOT_MCP_TOOLS=full` advertises everything from the start for users who
+prefer to pay the context cost once.
+
+## Recommended flow
+
+1. **先建立连接**：调一次 `list_tabs`；若返回 `pairing_required`，展示 `pair_url` 并等待用户批准。批准后只调 `pairing_status`，它报告 `connected` 后再调 `list_tabs`，不要轮询 `list_tabs`。
+2. **探查先于操作**：每次进入新页面，先 `getPageInfo` 确认位置，再 `takeSnapshot`（要点击/填表）或 `createPageIndex`（要读内容/抽字段）；`snapshotDOM` / `querySelector` 属于 legacy-dom 组，只在需要分析整页结构时通过 `browser_discoverTools` 启用。
+3. **最少充分验证**：危险或不可逆操作保持单步；多个独立字段用 `fillForm`。工具已返回 `verified` 或明确后置状态时，不要再用 `runJS` 重复验证。
+4. **dangerous 工具会被人工审核**：调用前用 `extractText` 给用户看上下文，让审批更顺。
+5. **跑不动了就停下来问**：候选不唯一、缺关键信息、需要二次确认时，把问题写在回复里交给用户，不要瞎猜（MCP 会话没有 `askUser`）。
+6. **完成后给一个简洁的总结**：用户希望看到「做了 N 步，最终结果 X」，不希望看流水账。
+
+## Tool usage notes (moved here from the tool descriptions)
+
+- `snapshotDOM`: `{}` (maxDepth 3) / `{ root: '.main', maxDepth: 5 }` / `{ maxDepth: 8 }`. Prefer `takeSnapshot` when you will click or fill afterwards.
+- `querySelector` / `querySelectorAll`: `{ selector: 'button[type=submit]' }`, `{ selector: '.comment-item', limit: 50 }`.
+- `extractText`: `{ selector: 'h1', single: true }`, `{ selector: 'article p' }`. Never `body` — use `createPageIndex`.
+- `extractImages`: `{}` for the page, `{ root: '.product-gallery' }` for a region.
+- `scroll`: `{ to: 'bottom', max: 5 }` for lazy loading; `{ to: 'bottom', max: 10, untilSelector: '.item:nth-child(20)' }` to stop once content appears.
+- `waitFor`: `{ ms: 500 }` or `{ selector: '.lazy-loaded', timeoutMs: 8000 }`.
+- `fillInput`: `{ selector: 'input[name=email]', value: 'a@b.c' }`; `clear: false` appends.
+- `fillForm`: `{ fields: [{ selector: 'input[name=name]', value: '张三' }, { uid: 'el_5', value: 'mushroom' }] }` — much cheaper than repeated `fillInput`.
+- `pressKey`: `{ selector: 'input[name=q]', key: 'Enter' }` submits a form-less search; `{ key: 'Escape' }` closes a modal.
+- `navigate`: `{ action: 'back' }`, `{ action: 'goto', url: 'https://example.com/page' }`.
+- `switchToTab`: all tools already target the session-bound tab. Discover and call this only when the user explicitly asks to bring Chrome and that tab to the foreground; never use it as setup for click, wait, runJS, or screenshot.
+- `resize`: returns measured `actualViewport`, `devicePixelRatio`, and `verified`; do not follow it with a viewport-only `runJS` probe.
+- `screenshot`: the image block is followed by compact capture metadata (backend, dimensions and target when available); use that instead of probing the viewport again.
+- `httpRequest`: `{ url: '.../api/comments?page=2' }` (no cookies) vs `{ url, withCredentials: true }` (cookied, reviewed).
+- `consoleMessages`: `{ level: 'error', limit: 50 }`; incremental polling with `{ sinceId }`.
+- `networkRequestDetail`: arm bodies first with `recorderConfig({ bodies: true })` in main-world mode.
+- `drop`: `{ selector: '#dropzone', files: [{ name: 'a.csv', mimeType: 'text/csv', base64: '...' }] }`.
+- `downloadSpreadsheet`: `{ filename: 'items', sheets: [{ name: 'Sheet1', rows: [{ title: 'A', price: 12 }], columns: [{ key: 'title', header: '标题' }, { key: 'price' }] }] }`.
+- `storage`: `{ op: 'get', store: 'local', key: 'token' }`, `{ op: 'set', store: 'session', key: 'k', value: '{"a":1}' }`.
+- `highlight`: `{ text: 'Checkout' }` or `{ selector: '#pay' }` / `{ uid: 'el_3' }`; visual only, 3 s by default.
+
+## Scenarios
+
+### 总结此页
+
+```
+createPageIndex({})
+extractText({ selector: "main, article, .content" })
+→ 文本总结
+```
+
+### 填表 + 提交
+
+`submitForm` 属于 form 组，先 `browser_discoverTools({ enable: ["browser_submitForm"] })` 启用。
+
+```
+takeSnapshot()  // 找输入框
+fillInput({ selector: "#name", value: "张三" })
+setCheckbox({ selector: "#agree", checked: true })
+selectOption({ selector: "#city", value: "北京" })
+→ 在回复中向用户确认「确认提交吗？」
+→ submitForm()  // dangerous，用户确认后执行
+```
+
+### 翻页采集
+
+`snapshotDOM` 属于 legacy-dom 组，先 `browser_discoverTools({ enable: ["browser_snapshotDOM"] })` 启用。
+
+```
+snapshotDOM({ selector: "[data-pagination]" })  // 找翻页结构
+extractText({ selector: ".item", multiple: true })
+→ 累积到内存
+→ click({ selector: ".next" })
+waitFor({ selector: ".item:nth-child(N+1)" })
+→ 重复
+```
+
+### 跨 tab 协作
+
+```
+listTabs()
+openTab({ url: "https://example.com" })  // 自动 attach
+→ 在新 tab 操作
+```
+
+## Safety / quota rails
+
+- **Quota**：默认 60 请求/分钟。超过会被拒绝，到 60s 自动恢复。先 `get_quota` 看额度。
+- **Dangerous gating**：用户已在 sidepanel 配置了授权模式（read / default / trust / yolo），你不需要预判，调就是了，会被拦下来或自动通过。
+- **超时**：默认每步 30s。慢操作（大页面 snapshot、长等待）记得显式传 `timeoutMs`。
+
+## Don'ts
+
+- ❌ 不要在 `runJS` 里直接读 cookie / localStorage（会被静态扫描归 dangerous，每次问审批）
+- ❌ 不要循环调 `snapshotDOM`——单次抓全树用 `maxDepth` 而不是多次
+- ❌ 不要在回复里频繁向用户确认（每次都要用户手动响应）
+- ❌ 不要无视 `attachedTabs`——跨 tab 操作前确认目标 tab 未被其他会话占用（`list_tabs` 的 `busy`）
+
+## When to use
+
+- 用户要你「在网页上做某事」、「抓某站点数据」、「填某表单」
+- 用户给了一个 URL 让你看
+- 用户问「这页面在讲什么」
+
+## When NOT to use
+
+- 纯文本任务（写代码、改文件）不需要浏览器
+- 用户明确说「不要打开浏览器」
+- 网页需要复杂登录但用户没在浏览器里登录过
+
+## Reference
+
+- README: https://github.com/attson/atwebpilot
+- 工具完整 schema 由 mcp-server 的 `tools/list` 暴露
+
+## Observing a page: console, network, dialogs
+
+These read from a recorder that is running on the page already, so you can ask
+about things that happened *before* you called.
+
+**Two backends, and you must check which one you got.** Every result carries
+`backend`:
+
+- `main-world` (default) — patches installed in the page's own realm. Cannot
+  see messages emitted before the patches installed, browser-level CORS/CSP
+  errors, or requests made by a service worker.
+- `cdp` — `chrome.debugger`, opt-in from the extension settings. Sees all of
+  the above plus real response bodies.
+
+If a result carries `degradedReason`, a CDP session was expected but is gone
+(DevTools opened, or another extension took the tab). Treat the data as
+incomplete rather than concluding the page did nothing. If it carries
+`disabled`, the recorder is not on that page at all.
+
+**Response bodies are off by default.** They cost memory on every page the user
+visits, so arm them first and then reproduce:
+
+```
+browser_recorderConfig({ bodies: true })   → arm
+… trigger the request …
+browser_networkRequests({ urlPattern: "/api/" })
+browser_networkRequestDetail({ id: <id from above> })
+```
+
+Calling `networkRequestDetail` without arming returns metadata plus
+`bodyUnavailable` explaining the fix. Note this tool is **dangerous**: response
+headers routinely carry `Authorization`, `Set-Cookie`, and bearer tokens.
+
+**`handleDialog` is a pre-set policy on the default backend, not a reaction.**
+`alert`, `confirm`, and `prompt` are synchronous, so a patched implementation
+cannot pause and ask you. Declare what should happen *before* triggering the
+dialog:
+
+```
+browser_handleDialog({ accept: true, promptText: "yes", scope: "all" })
+… click the thing that opens the dialog …
+browser_handleDialog({ accept: true })   → also returns the recorded dialogs
+```
+
+Under the CDP backend the dialog genuinely suspends, and a `handleDialog` call
+answers the pending one immediately.
+
+Until you arm it, dialogs behave exactly as they would without the extension —
+the recorder never silently changes page behaviour.
+
+## Debugging flow
+
+When a page misbehaves, this ordering costs the least context:
+
+1. `browser_consoleMessages({ level: "error" })` — cheap, and already buffered.
+2. `browser_networkRequests({ status: 500 })` or `{ urlPattern: "/api/" }` —
+   summaries only.
+3. `browser_recorderConfig({ bodies: true })`, reproduce, then
+   `browser_networkRequestDetail({ id })` for the one request that matters.
+
+Poll incrementally with `sinceId` rather than re-reading the whole buffer. If a
+result reports `dropped > 0`, the ring overflowed and you are seeing a window,
+not the whole history.
+
+## Multiple sessions share one browser
+
+Several Claude Code sessions can be attached to the same browser at once, each
+through its own connection. Two consequences worth knowing:
+
+- **Pairing is non-blocking.** `list_tabs` lazily binds the port and opens a
+  confirmation page, then immediately returns `pairing_required` with
+  `pair_url`. Ask the user to click Allow. After they confirm, call
+  `pairing_status`; call `list_tabs` again only when it reports `connected`.
+  Never inspect the pair-page HTML or retry `list_tabs` while state is unchanged.
+  Once approved, later sessions on that machine connect silently.
+- **Pick a free tab.** `list_tabs` marks tabs held by other sessions as `busy`.
+  Prefer an unowned tab, or open your own — two agents typing into one form
+  produces failures that look like your own tool calls not working.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attson/atwebpilot-mcp",
-  "version": "0.0.73",
+  "version": "0.0.75",
   "license": "Apache-2.0",
   "description": "MCP server for the atwebpilot browser extension - let Codex or Claude Code drive your browser.",
   "homepage": "https://github.com/attson/atwebpilot#readme",
@@ -26,7 +26,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "build": "tsup",
+    "build": "tsup && node scripts/copy-skill.mjs",
     "start": "tsx src/index.ts",
     "analyze:sessions": "tsx src/session-analysis/cli.ts"
   },