@attson/atwebpilot-mcp 0.0.81 → 0.0.83

package/README.md

@@ -2,12 +2,15 @@
 
 让 Codex 或 Claude Code 经一个本地 ws 中继驱动 atwebpilot 浏览器扩展操作网页（读 / 写 / 采）。
 
-## 给用户：一行装
+## 给用户：安装
 
 Codex：
 
+    npx -y @attson/atwebpilot-mcp --install-codex-skill
     codex mcp add atwebpilot -- npx -y @attson/atwebpilot-mcp
 
+第一条命令把正式 Skill 安装到用户级 `~/.agents/skills/atwebpilot-browser/`，让 Codex 在真实网页验收、截图、调试、读取或交互任务中主动发现 AtWebPilot；它不会修改任何项目的 `AGENTS.md`。内容相同时重复执行是幂等的；若目标被手工修改会拒绝覆盖，确认替换时显式加 `--force`。安装后新开 Codex 会话。
+
 Claude Code：
 
     claude mcp add atwebpilot --scope user -- npx -y @attson/atwebpilot-mcp
@@ -17,8 +20,8 @@ Claude Code：
 **不需要手填端口。** 从 Plan 33 起是配对流程：
 
 1. 会话启动时**不绑任何端口** —— 不碰网页的会话零副作用。
-2. AI 第一次调 `list_tabs` 时才绑一个空闲端口，通过 MCP URL elicitation 请宿主打开配对页；不支持该能力的宿主回退到系统默认浏览器。`list_tabs` 最多等待 45 秒。
-3. 你在浏览器里点「允许」，扩展即接入；同一次 `list_tabs` 调用直接返回 tab，AI 无需让你回复「已连接」。只有等待超时才返回 `pairing_required + pair_url`；`pairing_status` 始终是立即返回的非阻塞状态检查。
+2. AI 第一次调 `browser_start` 时才绑一个空闲端口，通过 MCP URL elicitation 请宿主打开配对页；不支持该能力的宿主回退到系统默认浏览器。`browser_start` 最多等待 45 秒。
+3. 你在浏览器里点「允许」，扩展即接入；唯一 tab 可确定时同一次 `browser_start` 调用直接返回 ready session，多个候选时返回 `select_tab`，AI 带选中的 `tab_id` 再调用一次。无需让你回复「已连接」。只有等待超时才返回 `pairing_required + pair_url`；`pairing_status` 始终是立即返回的非阻塞状态检查。
 4. 之后本机的会话都免确认（信任是安装级的）；端口能复用时连配对页都不会弹。
 
 若宿主和系统都未弹出浏览器，可在超时结果中打开 `pair_url`。授权成功只以扩展实际建立连接并发送 `HELLO` 为准；打开配对页本身不代表已连接。
@@ -30,6 +33,7 @@ Coordinator 查看已接入的会话、单独断开，或撤销信任。
 
 - `ATWEBPILOT_WS_PORT`：固定端口（默认是自动选一个空闲端口并复用上次的）
 - `ATWEBPILOT_WS_TOKEN`：要求扩展带 `bearer.<token>` 子协议
+- `ATWEBPILOT_CODEX_SKILLS_DIR`：覆盖 Codex Skill 安装根目录（默认 `~/.agents/skills`）
 
 ## 给开发者：本地 monorepo
 
@@ -48,7 +52,7 @@ listen 端口的能力，所以方向只能如此。这也是配对页存在的
 
 ## 工具面
 
-- 控制面 5 个：`pairing_status / list_tabs / open_session / close_session / get_quota`
+- 控制面 6 个：`browser_start / pairing_status / list_tabs / open_session / close_session / get_quota`。常规网页任务从 `browser_start` 开始；`list_tabs` / `open_session` 保留为底层兼容入口。
 - 发现 1 个：`browser_discoverTools` —— 已知工具时直接传 `enable: [...]`，已知分组时直接传 `enableGroups: ["export", ...]`，也可用 `profile: "core" | "full"` 切换整套工具面；只有这些都未知时才不带参数读取目录。选中的工具会加入本进程的 `tools/list`（发送 `tools/list_changed`），并始终返回完整 schema，包括已经启用的工具。
 - 同轮执行桥 1 个：`browser_call({session_id, tool, args})` —— 某些宿主虽已刷新 `tools/list`，却不会在当前模型轮次注入新工具。AI 可在 `discoverTools` 后立刻通过该桥执行，不需要让用户回复“继续”；下一轮看到原生工具后仍优先使用原生工具。
 - 批量编排 1 个：`browser_runSteps({session_id, steps, return_bindings?})` —— 在步骤和参数已经明确时，把 1–20 个 safe/caution 工具合并为一次 MCP 调用；`${binding}` 可引用前序结果。整批先做工具支持、权限和配额预检，dangerous、脚本、截图、下载与 tab 生命周期操作保持单步。

package/dist/index.js

@@ -946,6 +946,20 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprot
 
 // src/control-tools.ts
 var CONTROL_TOOLS = [
+  {
+    name: "browser_start",
+    description: "Primary entry point for a live web page in the user's existing Chrome: localhost, screenshots/UI smoke, authenticated interaction, or console/network debugging. Pairs if needed and returns a ready session or tab candidates.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tab_id: { type: "string", description: "Exact id from browser_start/list_tabs" },
+        url: { type: "string", description: "Exact URL of an open tab" },
+        capabilities: { type: "array", items: { type: "string" }, description: "Optional capability scope" },
+        idle_timeout_min: { type: "number", description: "Optional idle timeout in minutes" }
+      },
+      additionalProperties: false
+    }
+  },
   {
     name: "pairing_status",
     description: "Start or check browser pairing without waiting. Returns connected or pairing_required with the pair URL.",
@@ -2389,6 +2403,53 @@ async function handleListTabs(deps, onPairingRequired, timeoutMs = LIST_TABS_PAI
   }
   return { status: "connected", tabs: worker.available_tabs };
 }
+function selectionResult(tabs, message) {
+  return { status: "select_tab", tabs, message };
+}
+async function handleBrowserStart(deps, args, onPairingRequired, timeoutMs = LIST_TABS_PAIRING_TIMEOUT_MS) {
+  const listed = await handleListTabs(deps, onPairingRequired, timeoutMs);
+  if (listed.status === "pairing_required") return listed;
+  const tabId = typeof args.tab_id === "string" && args.tab_id.length > 0 ? args.tab_id : void 0;
+  const url = typeof args.url === "string" && args.url.length > 0 ? args.url : void 0;
+  let selected;
+  if (tabId) {
+    selected = listed.tabs.find((tab) => tab.tab_id === tabId);
+    if (!selected) {
+      throw new Error(`InvalidArgs: browser_start tab_id ${JSON.stringify(tabId)} is not available`);
+    }
+    if (url && selected.url !== url) {
+      throw new Error("InvalidArgs: browser_start tab_id and url must identify the same tab");
+    }
+  } else if (url) {
+    const matches = listed.tabs.filter((tab) => tab.url === url);
+    if (matches.length === 1) {
+      [selected] = matches;
+    } else if (matches.length > 1) {
+      return selectionResult(
+        matches,
+        "Multiple tabs have that exact URL. Choose one and call browser_start again with tab_id."
+      );
+    } else {
+      return selectionResult(
+        listed.tabs,
+        "No exact URL match. Choose a tab and call browser_start again with tab_id."
+      );
+    }
+  } else if (listed.tabs.length === 1) {
+    [selected] = listed.tabs;
+  } else {
+    return selectionResult(
+      listed.tabs,
+      "Choose a tab and call browser_start again with tab_id."
+    );
+  }
+  const opened = await handleOpenSession(deps, {
+    tab_id: selected.tab_id,
+    ...Array.isArray(args.capabilities) ? { capabilities: args.capabilities } : {},
+    ...typeof args.idle_timeout_min === "number" ? { idle_timeout_min: args.idle_timeout_min } : {}
+  });
+  return { status: "ready", session_id: opened.session_id, tab: selected };
+}
 async function handleOpenSession(deps, args) {
   const { coordinator } = await deps.ensure();
   const worker_id = singleWorkerId(coordinator, deps.pairUrl());
@@ -2792,9 +2853,9 @@ var SKILL_DESCRIPTION = "Strategy + scenarios + safety rails for driving the AtW
 var TOPICS = {
   quickstart: `# AtWebPilot quickstart
 
-1. Call list_tabs once. On first use it opens the pairing page and waits for authorization, then normally returns connected tabs in the same call.
-2. If list_tabs times out and returns pairing_required, show pair_url and wait for browser approval. Use pairing_status for a later non-blocking status check; do not ask the user to reply just to continue.
-3. Choose a returned tab, then call open_session with its tab_id.
+1. Call browser_start once. On first use it opens the pairing page and waits for authorization; when one tab is unambiguous it returns a ready session in the same call.
+2. If browser_start returns select_tab, call browser_start again with one returned tab_id. list_tabs and open_session remain lower-level compatibility tools.
+3. If browser_start times out and returns pairing_required, show pair_url and wait for browser approval. Use pairing_status for a later non-blocking status check; do not ask the user to reply just to continue.
 4. For interaction use browser_getPageInfo then browser_takeSnapshot; for broad reading use browser_createPageIndex.
 5. When 2-20 safe/caution steps and their arguments are already known, use browser_runSteps to execute them in one MCP call. Keep dangerous actions and steps needing intermediate inspection as separate calls.
 6. Prefer purpose-built tools and verified results. Use browser_discoverTools only for capabilities outside the connected core surface. Its response always includes the selected schemas. If a newly enabled native tool is not visible in the current turn, call it immediately with browser_call; do not ask the user to send "continue".
@@ -2878,7 +2939,7 @@ var SKILL_TOOL = {
 // package.json
 var package_default = {
   name: "@attson/atwebpilot-mcp",
-  version: "0.0.81",
+  version: "0.0.83",
   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",
@@ -2987,6 +3048,7 @@ function createPairingPresenter(server, fallbackOpenUrl) {
 }
 
 // src/mcp-server.ts
+var MCP_INSTRUCTIONS = "Use AtWebPilot for tasks that require inspecting, testing, debugging, screenshotting, reading, or interacting with a live web page in the user's existing Chrome, including localhost and authenticated pages. Start with browser_start. When AtWebPilot is available, use it before probing or launching Playwright, Puppeteer, or Chrome remote debugging. Do not start the browser for pure code editing or static source analysis that does not require observing a live page.";
 var ALL_BROWSER_TOOLS = generateBrowserTools("full");
 var BROWSER_BY_NAME = new Map(ALL_BROWSER_TOOLS.map((t) => [t.name, t]));
 function createToolState(mode) {
@@ -3102,6 +3164,11 @@ async function dispatchCall(deps, name, args, state = DEFAULT_STATE, onListChang
       if (result.status === "connected") await revealBrowserSurface(state, onListChanged);
       return ok(result);
     }
+    if (name === "browser_start") {
+      const result = await handleBrowserStart(deps, args, onPairingRequired);
+      if (result.status !== "pairing_required") await revealBrowserSurface(state, onListChanged);
+      return ok(result);
+    }
     if (name === "open_session") {
       const result = await handleOpenSession(deps, args);
       await revealBrowserSurface(state, onListChanged);
@@ -3154,7 +3221,10 @@ async function revealBrowserSurface(state, onListChanged) {
 function createMcpServer(deps, state = DEFAULT_STATE, options = {}) {
   const server = new Server(
     { name: "atwebpilot-mcp", version: MCP_VERSION },
-    { capabilities: { tools: { listChanged: true }, logging: {} } }
+    {
+      capabilities: { tools: { listChanged: true }, logging: {} },
+      instructions: MCP_INSTRUCTIONS
+    }
   );
   const presentPairing = createPairingPresenter(server, options.fallbackOpenUrl);
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: buildToolList(deps, state) }));
@@ -3931,8 +4001,103 @@ async function defaultOpenUrl(url) {
   throw new Error(errors.join("; ") || "no browser opener available");
 }
 
+// src/skill-installer.ts
+import { access, mkdir, readFile as readFile2, rename, unlink, writeFile } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var SKILL_DIRECTORY_NAME = "atwebpilot-browser";
+function isMissing(error) {
+  return error?.code === "ENOENT";
+}
+async function atomicWrite(targetFile, content) {
+  const temporaryFile = `${targetFile}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(temporaryFile, content, { encoding: "utf8", mode: 420, flag: "wx" });
+    await rename(temporaryFile, targetFile);
+  } catch (error) {
+    await unlink(temporaryFile).catch(() => void 0);
+    throw error;
+  }
+}
+async function installCodexSkill(options) {
+  let source;
+  try {
+    source = await readFile2(options.sourceFile, "utf8");
+  } catch (error) {
+    if (isMissing(error)) {
+      throw new Error(`Skill source is missing: ${options.sourceFile}`);
+    }
+    throw error;
+  }
+  const targetDirectory = join3(options.skillsRoot, SKILL_DIRECTORY_NAME);
+  const targetFile = join3(targetDirectory, "SKILL.md");
+  let existing;
+  try {
+    existing = await readFile2(targetFile, "utf8");
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+  if (existing === source) return { status: "unchanged", targetFile };
+  if (existing !== void 0 && !options.force) {
+    throw new Error(
+      `Codex Skill already exists with different content at ${targetFile}; rerun with --force to overwrite it.`
+    );
+  }
+  await mkdir(targetDirectory, { recursive: true });
+  await atomicWrite(targetFile, source);
+  return {
+    status: existing === void 0 ? "installed" : "overwritten",
+    targetFile
+  };
+}
+function defaultCodexSkillsRoot(env = process.env, homeDirectory = homedir2()) {
+  return env.ATWEBPILOT_CODEX_SKILLS_DIR || join3(homeDirectory, ".agents", "skills");
+}
+async function resolveBundledSkillFile(moduleUrl = import.meta.url) {
+  const here = dirname2(fileURLToPath2(moduleUrl));
+  const candidates = [
+    join3(here, "skill", "SKILL.md"),
+    join3(here, "../../../skill/SKILL.md")
+  ];
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  throw new Error(`Skill source is missing; checked: ${candidates.join(", ")}`);
+}
+async function runSkillInstallCommand(args, overrides = {}) {
+  if (!args.includes("--install-codex-skill")) return { handled: false };
+  const supported = /* @__PURE__ */ new Set(["--install-codex-skill", "--force"]);
+  const unknown = args.filter((arg) => !supported.has(arg));
+  if (unknown.length > 0) {
+    throw new Error(`Unknown option for Skill installation: ${unknown.join(", ")}`);
+  }
+  const sourceFile = overrides.sourceFile ?? await resolveBundledSkillFile();
+  const skillsRoot = overrides.skillsRoot ?? defaultCodexSkillsRoot();
+  const result = await installCodexSkill({
+    sourceFile,
+    skillsRoot,
+    force: args.includes("--force")
+  });
+  return { handled: true, result };
+}
+
 // src/index.ts
 async function main() {
+  const args = process.argv.slice(2);
+  const install = await runSkillInstallCommand(args);
+  if (install.handled) {
+    process.stdout.write(`Codex Skill ${install.result.status}: ${install.result.targetFile}
+`);
+    return;
+  }
+  if (args.length > 0) {
+    throw new Error(`Unknown option: ${args.join(", ")}`);
+  }
   const explicitPort = process.env.ATWEBPILOT_WS_PORT ? Number(process.env.ATWEBPILOT_WS_PORT) : void 0;
   const token = process.env.ATWEBPILOT_WS_TOKEN || void 0;
   const clock = new DefaultClock();

package/dist/skill/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: atwebpilot-browser
+description: Use AtWebPilot when a task requires inspecting, testing, debugging, screenshotting, reading, or interacting with a live web page in the user's existing Chrome, including localhost and authenticated pages. Do not use it for pure code editing or static source analysis that does not require observing a live page.
+---
+
 # atwebpilot-browser skill
 
 A reusable strategy for agents that drive AtWebPilot's browser extension via
@@ -12,6 +17,10 @@ When this skill is loaded, you can drive any open tab through these tools
 
 ### Control plane
 
+- `browser_start({ tab_id?, url? })` — primary entry point for live-page work.
+  It pairs when needed and returns a ready session when exactly one tab can be
+  selected safely. When it returns `select_tab`, call it again with one listed
+  `tab_id`; it never guesses between tabs.
 - `pairing_status` — start/check pairing without waiting. When it reports
   `pairing_required`, show `pair_url` once; use it only as a later status check.
 - `list_tabs` — on first use, open the pairing page and wait up to 45 seconds
@@ -88,7 +97,7 @@ compatibility path; use the native tool once the host exposes it.
 
 ## Recommended flow
 
-1. **先建立连接**：调一次 `list_tabs`；首次配对时它会打开授权页并等待最多 45 秒，授权成功后同一次调用直接返回 tab，不要让用户回复「已连接」。只有超时才会返回 `pairing_required`；此时展示 `pair_url`，稍后用非阻塞的 `pairing_status` 检查，不要轮询 `list_tabs`。
+1. **先建立连接**：调一次 `browser_start`；首次配对时它会打开授权页并等待最多 45 秒，唯一 tab 可确定时同一次调用直接返回 ready session。返回 `select_tab` 时带 `tab_id` 再调一次；只有超时才会返回 `pairing_required`，此时展示 `pair_url`，稍后用非阻塞的 `pairing_status` 检查，不要轮询 `list_tabs`。
 2. **探查先于操作**：每次进入新页面，先 `getPageInfo` 确认位置，再 `takeSnapshot`（要点击/填表）或 `createPageIndex`（要读内容/抽字段）；`snapshotDOM` / `querySelector` 属于 legacy-dom 组，只在需要分析整页结构时通过 `browser_discoverTools` 启用。
 3. **最少充分验证**：危险或不可逆操作保持单步；多个独立字段用 `fillForm`。工具已返回 `verified` 或明确后置状态时，不要再用 `runJS` 重复验证。
 4. **dangerous 工具会被人工审核**：调用前用 `extractText` 给用户看上下文，让审批更顺。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attson/atwebpilot-mcp",
-  "version": "0.0.81",
+  "version": "0.0.83",
   "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",