@glittering0717/ai-browser 1.3.1 → 2.1.0

package/README.md

@@ -205,13 +205,38 @@ small surface, since every tool schema is injected into your agent's context on
 | `browse_evaluate` | Run a JS *expression* in page context (5000-char cap, Node identifiers rejected). |
 | `browse_scroll` | Scroll the page, or scroll an element into view. |
 | `browse_wait` | Poll until `button_enabled` / `modal_appeared` / `text_contains` / `url_contains`. |
-| `browse_list_tabs` | List open tabs (id, url, title, active). |
-| `browse_new_tab` | Open a new tab, optionally at a URL. |
-| `browse_close_tab` | Close a tab by id. |
-| `browse_set_active_tab` | Switch which tab subsequent calls act on. |
+| `browse_tabs` | Tabs: `list` / `new` / `close` / `switch`. `switch` sets the default target for later calls. |
 | `browse_network` | Chrome-DevTools-style network inspection: `list` (filter by method / URL / status / type), `get` (request + response headers and bodies), `clear`, `configure`. |
 | `browse_quit` | Shut the whole browser down and release the process. |
 
+### What every act result already tells you: `effect_state`
+
+`browse_act` no longer leaves you guessing whether your input reached the page. Every result
+carries an explicit verdict:
+
+| `effect_state` | Meaning | `retry` |
+|---|---|---|
+| `committed` | dispatched and acked by the page | `no` |
+| `none` | provably nothing happened (no such target, bad params, CDP down) | `safe` |
+| `unknown` | cannot prove nothing happened — timeout, paste dispatched but never consumed, half a key sequence | `verify_first` |
+
+The default is `unknown`, not `none`: when the browser cannot tell, it says so. Retrying an
+`unknown` blindly is how a form gets submitted twice — read the page first. `unknown` results
+also carry a one-sentence `effect_hint` saying exactly that.
+
+When a `target` cannot be found, the result adds `stale_ref` / `ref_epoch` / `tree_epoch` /
+`ref_diagnosis`, because "no such target" hides three very different situations:
+
+- `ref_diagnosis: "stale"` — the page was re-read after you took that ref (`ref_epoch` <
+  `tree_epoch`). Get a fresh one; retrying the same ref will keep failing.
+- `ref_diagnosis: "never_seen"` — the ref has never been in any tree read so far. Re-reading
+  will not help: wrong value (visible text instead of a `data-ai-id`), a typo, or another tab's ref.
+- `ref_diagnosis: "present_in_tree"` — in the current tree but not found in the DOM: iframe,
+  shadow root, or a detached node.
+
+All three report `effect_state: "none"` (nothing happened) with `retry: "verify_first"` — no side
+effects, but repeating the identical call is pointless.
+
 ### Prove it happened: `browse_diff`
 
 A tool reporting `success` is **not** evidence that anything changed — the browser will happily
@@ -396,6 +421,22 @@ MCP is a thin stdio adapter. Anything MCP can do is reachable directly over JSON
 `ws://localhost:9223` from any language. Source of truth: the method switch in
 [`src/main/ws_server.js`](src/main/ws_server.js).
 
+You do not have to write a client to do this. The CLI speaks the same protocol:
+
+```bash
+ai-browser status                                   # running? pid / port / tabs
+ai-browser call ui.list_tabs
+ai-browser call ui.get_tree '{"subset":"interactive"}'
+ai-browser call ui.navigate '{"url":"https://example.com"}'
+echo '{"url":"https://example.com"}' | ai-browser call ui.navigate -
+```
+
+`call` prints the raw `result` as one line of JSON (pipe it into `jq`), exits `0` on success,
+`1` when the call failed, `2` on a bad command line. `--port`, `--timeout`, `--pretty` are available.
+
+So there are three doors to one implementation — MCP stdio (`ai-browser mcp`), JSON-RPC over
+WebSocket, and this CLI. None of them is a separate code path.
+
 | Method | Purpose | Maps to |
 |---|---|---|
 | `ui.get_tree` | Semantic tree (+ context). Params: `focusedOnly`, `ax`, `subset`, `mode`, `tab` | `browse_get_tree` |
@@ -407,7 +448,7 @@ MCP is a thin stdio adapter. Anything MCP can do is reachable directly over JSON
 | `ui.evaluate` | Run JS in page context, same guard as MCP | `browse_evaluate` |
 | `ui.scroll` | Scroll page or element (`direction`, `amount`, `target`). **Document scrolling only** — for canvas apps use `ui.act{action:'wheel'}`. | `browse_scroll` |
 | `ui.wait` | Poll until a condition or timeout | `browse_wait` |
-| `ui.new_tab` / `ui.close_tab` / `ui.list_tabs` / `ui.set_active_tab` | Tab management | `browse_*_tab` |
+| `ui.new_tab` / `ui.close_tab` / `ui.list_tabs` / `ui.set_active_tab` | Tab management (the four are merged into `browse_tabs{op}` on the MCP side) | `browse_tabs` |
 | `ui.subscribe` / `ui.unsubscribe` | Event subscription; `params.events`, `"*"` for all | — (WS only — see below) |
 | `ui.downloads` | This tab's downloads with on-disk paths (`state`, `received_bytes`, `dir`) | `browse_downloads` |
 | `ui.get_focused` | The focused element subtree | — |
@@ -660,6 +701,16 @@ It exits non-zero below 80% so you can drop it into CI. Measured on 2026-10-17 (
 CSDN): **82% / 97% / 88%** before the click-boundary fix, **100% / 100% / 100%** after, at ~40ms
 per `ui.get_tree`.
 
+> **Those three numbers were measuring the wrong denominator.** Until 2026-10-19 the tool only
+> counted the top document: on a page whose body lives in a cross-process iframe it reported
+> "4 click targets, 100% usable, 0 gaps" while the entire course catalogue was invisible. It now
+> measures every `frame-N` it can reach and **prints how many frames it could not** — an
+> unmeasured area inside the denominator is worse than a wrong measurement. Re-measured
+> 2026-10-19: Baidu 100%, CSDN 99% (8 cross-process frames now counted, 2 residual gaps),
+> and the 超星 course page 82% with the 2 remaining gaps named explicitly. The write-up of this
+> class of mistake — a metric that silently excludes the part that matters — is
+> [`docs/POSTMORTEM_FRAME_VISIBILITY.md`](docs/POSTMORTEM_FRAME_VISIBILITY.md).
+
 Two things the numbers do **not** cover, so you do not chase them: an element the page gives no
 readable name (image-only links with no `alt` — 53% of Bilibili's clickable nodes) can never get a
 label without inventing one, and a canvas has no DOM to read at all. Those are genuine boundaries,

package/bin/ai-browser.cjs

@@ -4,6 +4,7 @@
 //   ai-browser            launch the visible browser window (foreground)
 //   ai-browser start      same
 //   ai-browser mcp        run the MCP stdio server (used by MCP clients)
+//   ai-browser skill      list / install bundled agent skills
 //   ai-browser --version
 //   ai-browser --help
 //
@@ -19,13 +20,24 @@ const HELP = `ai-browser ${pkg.version}
 
 Usage:
   ai-browser [start]          Launch the visible AI Browser window
-  ai-browser mcp              Run the MCP stdio server (20 browse_* tools)
+  ai-browser mcp              Run the MCP stdio server (17 browse_* tools)
+  ai-browser skill [list|install|print]
+                              Install the bundled agent skills into your client
+  ai-browser call <method> [json|-]
+                              Call one JSON-RPC method and print the result
+                              (starts the browser first if it is not running)
+  ai-browser ensure           Start the browser if needed, then exit (idempotent)
+  ai-browser status           Is the browser running? pid / port / tabs
   ai-browser --version        Print version
   ai-browser --help           Show this help
 
-The browser exposes:
-  • MCP server over stdio (this command's "mcp" subcommand)
-  • Raw WebSocket JSON-RPC on ws://localhost:9223 (ui.* methods)
+The browser exposes one implementation through three thin doors:
+  • MCP server over stdio  → ai-browser mcp        (for agent clients)
+  • WebSocket JSON-RPC     → ws://127.0.0.1:9223   (ui.* methods)
+  • This CLI              → ai-browser call ui.list_tabs
+
+Agent skills ship in this package. Install them once with "ai-browser skill install"
+and every new session picks them up automatically — no manual instruction pasting.
 
 Docs: https://github.com/Glittering/ai-browser
 `;
@@ -55,6 +67,31 @@ async function main() {
       await import(pathToFileURL(serverPath).href);
       break;
     }
+    case 'skill': {
+      // 技能装进客户端的技能目录 —— 装一次，之后每次新会话自动发现。
+      const { run } = require('../scripts/skill.cjs');
+      process.exit(run(argv.slice(1)));
+      break;
+    }
+    case 'call': {
+      // 命令行直接调一条 JSON-RPC。存在的理由：以前想从 shell 问一句"有哪些标签页"
+      // 都得先 npm i ws 再写脚本。见 scripts/cli_call.cjs 顶部注释。
+      const { runCall } = require('../scripts/cli_call.cjs');
+      process.exit(await runCall(argv.slice(1)));
+      break;
+    }
+    case 'status': {
+      const { runStatus } = require('../scripts/cli_call.cjs');
+      process.exit(await runStatus(argv.slice(1)));
+      break;
+    }
+    case 'ensure': {
+      // 只把浏览器弄到"能连"的状态，然后退出。存在的理由：让 `call` 之外还有一条
+      // **显式**的启动动作，脚本/CI 里想先起再调时用它（幂等，已在跑就是 no-op）。
+      const { runEnsure } = require('../scripts/cli_call.cjs');
+      process.exit(await runEnsure(argv.slice(1)));
+      break;
+    }
     case '--version':
     case '-v':
     case 'version':

package/examples/AGENT_INSTRUCTIONS.md

@@ -1,186 +1,71 @@
-# AI Browser — Agent Instructions
+# AI Browser — agent 接入
 
-把下面**任意一节**里的代码块整段复制，粘贴进你的 agent 的 memory / instructions / system prompt
-（Claude Code 的 `CLAUDE.md`、Cursor Rules、Codex `AGENTS.md`、或任意 MCP 客户端的自定义指令）。
-不需要改任何东西——浏览器由 agent 自己在第一次调用时拉起。
+## 先别贴这份文件
 
-* [中文版](#中文版copy-paste) · [English](#english-copy-paste)
-* [配置 MCP 服务器](#配置-mcp-服务器) · [参数速查](#参数速查) · [人工介入到底是怎么发生的](#人工介入到底是怎么发生的)
+```bash
+npx -y @glittering0717/ai-browser skill install
+```
 
-> 配套文件：`mcp-config.json`（客户端配置）、`raw-ws.mjs`（不用 MCP 的最小例子）、
-> `read-page.mjs`（读一页并列出可交互元素）、`with-human.mjs`（需要人介入时的完整流程）。
+装一次，之后**每次新会话客户端会自动发现**这些技能，不需要你在对话里重新教一遍、也不用把
+下面任何内容粘进 system prompt：
 
----
+| 技能 | 干什么 |
+|---|---|
+| `ai-browser` | 最小循环、卡住时的第一反应、难搞页面的处理 |
+| `content-publish` | 把文章发布到 CSDN / 知乎 / 掘金 |
+| `read-webpage` | 读一篇文章正文并总结 |
+| `web-network-monitor` | 长时间盯某个页面的请求 |
 
-## 中文版（copy-paste）
+不装技能也能用——20 个 `browse_*` 工具的 schema 本身自带说明。技能只是把"怎么组合"讲清楚。
 
-```text
-我可以用 AI Browser 浏览网页。它提供 MCP 服务（20 个 browse_* 工具），第一次调用时会自动
-拉起一个真实可见的浏览器窗口，用完调用 browse_quit 释放。页面以结构化语义树返回，不是截图。
-
-标准循环：
-1. browse_navigate { url }                 打开页面
-2. browse_get_tree                         读页面，返回语义树：每个节点有 role / label / value /
-                                           states / actions
-3. browse_act { action, target }           操作元素，target 填第 2 步节点里的 id（即 data-ai-id）
-                                           action 可选：click / type（光标处追加）/ setContent
-                                           （整体替换）/ clear / focus / hover / scroll_to /
-                                           upload / get_value（只读回读全文）/ drag / press / wheel
-4. browse_wait { condition }               等待条件成立：button_enabled / modal_appeared /
-                                           text_contains / url_contains
-5. browse_evaluate { js }                  在页面上下文跑 JS 表达式（上限 5000 字符，
-                                           禁用 process. / require / child_process）
-6. browse_errors                           出事了先看这里：主进程异常 / 崩溃 / 导航失败 /
-                                           RPC 报错的最近记录（含调用上下文与日志路径）
-
-省 token（browse_get_tree 参数）：
-- { "subset": "interactive" }  只保留可交互节点，砍掉纯布局分支 —— 默认就该带上
-- { "ax": true }               走 AX 语义层，链接会带 url
-- { "mode": "diff" }           只看上次读取以来新增 / 消失的可交互节点
-
-验证写操作（success 不等于做成了）：browse_diff 先 snapshot 基线，写操作之后再 diff，
-verdict 显式给出 changed / unchanged。
-
-找不到元素 / 点了没反应时的排查顺序（**别一上来就写站点专用选择器**）：
-1. 重读 browse_get_tree，或先 browse_wait —— SPA 常常只是还没渲染完
-2. 节点在树里但操作失败 → 是**动作层**问题（跨进程 iframe、canvas、需要受信输入、
-   上传控件未挂载），写选择器解决不了
-3. 树里没有、页面上明明有 → 是**读层**缺口，属于浏览器该修的东西；先跑
-   tools/coverage_probe.cjs <url> 量化，再考虑绕过
-4. 以上都不成立，才在自己脚本里用选择器兜底；别把"某个站点的选择器"记成通用知识
-
-其他：browse_scroll 滚动文档（画布类页面用 browse_act 的 wheel）；browse_list_tabs /
-browse_new_tab / browse_close_tab / browse_set_active_tab 管标签页；browse_network 拉取网络
-请求（含 POST body，免订阅）；browse_capabilities 一次探明页面该走哪条路（结构化数据 /
-语义树 / 指针手势）；browse_canvas 读 canvas 绘制调用里的文本（不是 OCR）；
-browse_downloads 查下载文件落盘路径；browse_repaint 在窗口画面陈旧时强制重绘。
-
-需要人帮忙时（登录、扫码、短信验证码、滑块 / 人机验证，以及任何我做不了的操作）：
-浏览器窗口是真实可见的，人随时可以用鼠标键盘操作。我应该在对话里直接说一句人话请用户去窗口里
-完成，例如"请在浏览器窗口里扫码登录，完成后回复我'好了'"，然后停下来等用户回复；收到"好了"之后
-重新 browse_get_tree 确认状态再继续。不要编造登录凭据，也不要反复重试那些注定失败的点击。
-浏览器侧没有任何"交接"接口，也不需要——人机协作就发生在我们的对话里。
-
-收尾：任务完成后调用 browse_quit（会关闭整个浏览器窗口和进程，释放资源）。
-```
+---
 
-## English (copy-paste)
+## 兜底：客户端不支持技能时
+
+把下面这段贴进 `CLAUDE.md` / `AGENTS.md` / 自定义指令。**只需要这几行**，其余按需查技能里的
+`references/`。
 
 ```text
-I can browse the web with AI Browser. It exposes an MCP server (20 browse_* tools), auto-starts a
-real, visible browser window on my first call, and I release it with browse_quit when done. Pages come
-back as a structured semantic tree — no screenshots, no OCR.
-
-Standard loop:
-1. browse_navigate { url }                 load a page
-2. browse_get_tree                         read the page: nodes carry role / label / value / states /
-                                           actions
-3. browse_act { action, target }           act on an element; target is the node's id (its data-ai-id)
-                                           action: click / type (append at caret) / setContent
-                                           (replace all) / clear / focus / hover / scroll_to /
-                                           upload / get_value (read-only) / drag / press / wheel
-4. browse_wait { condition }               block until: button_enabled / modal_appeared /
-                                           text_contains / url_contains
-5. browse_evaluate { js }                  run a JS expression in page context (5000-char cap;
-                                           process. / require / child_process are rejected)
-
-Saving tokens (browse_get_tree params):
-- { "subset": "interactive" }   drop layout-only branches — use this by default
-- { "ax": true }                AX semantic layer; links carry url
-- { "mode": "diff" }            only interactive nodes added/hidden since my last read
-
-Verifying writes (success is not evidence): browse_diff snapshots a baseline, then diffs after the
-write and returns an explicit verdict of changed / unchanged.
-
-When an element cannot be found, or a click does nothing — work down this list, do **not** reach for a
-site-specific selector first:
-1. re-read with browse_get_tree, or browse_wait — an SPA usually just has not rendered yet
-2. the node is in the tree but the action fails → an **action-layer** gap (cross-process iframe,
-   canvas, trusted input, unmounted upload input); a selector will not fix it
-3. the node is missing though the page clearly renders it → a **read-layer** gap, i.e. something the
-   browser should fix; quantify it with `tools/coverage_probe.cjs <url>` before working around it
-4. only then pin it with a selector inside your own script — and never record "the selector for site X"
-   as general knowledge
-
-Also: browse_scroll (document scrolling; use the wheel action on canvas apps); browse_list_tabs /
-browse_new_tab / browse_close_tab / browse_set_active_tab for tabs; browse_network for captured
-requests including POST bodies (no subscription); browse_capabilities to pick a route on an
-unfamiliar page (structured data / semantic tree / pointer gestures); browse_canvas reads text
-straight from canvas draw calls (no OCR); browse_downloads for on-disk download paths;
-browse_repaint when the window shows a stale page.
-
-When I need a human (login, QR code, SMS code, slider/CAPTCHA, or anything I genuinely cannot do):
-the browser window is real and visible — the user can just use their mouse and keyboard in it. I should
-say so plainly in the conversation (e.g. "please scan the QR code in the browser window and reply
-'done'"), then stop and wait for that reply. After "done", I re-read with browse_get_tree and continue.
-I never invent credentials or loop on clicks that cannot work. There is no hand-off API on the browser
-side, and none is needed — the collaboration happens right here in our conversation.
-
-Wrap up: call browse_quit when the task is finished (it closes the window and exits the process).
-```
+我可以用 ai-browser 操作一个真实可见的浏览器（MCP: browse_* 工具）。
 
----
+循环：browse_navigate {url} → browse_get_tree {subset:"interactive"} 取节点 id →
+      browse_act {action:"click"|"type", target:id, text?}
 
-## 配置 MCP 服务器
+success:true 只代表动作发出去了，不代表页面变了。要证明生效：browse_diff 先 snapshot、
+操作后 diff，看 verdict。unchanged 说明要么点错了、要么页面没响应，别接着瞎点。
 
-把下面配置复制到你的客户端配置文件里（Claude Desktop `claude_desktop_config.json`、
-项目根目录 `.mcp.json`、Cursor `~/.cursor/mcp.json`、Codex 等）。npm 包方式无需任何本地路径：
+卡住时的顺序：节点没有 → browse_wait 再重读树；有节点但操作失败 → 动作层问题（iframe /
+canvas / 富文本），换动作不是换选择器；点了没反应 → browse_screenshot 看视觉 或
+browse_network 看请求；怀疑掉登录 → browse_auth_state；都不是 → browse_errors。
 
-```json
-{
-  "mcpServers": {
-    "ai-browser": {
-      "command": "npx",
-      "args": ["-y", "@glittering0717/ai-browser", "mcp"]
-    }
-  }
-}
+需要人（登录/扫码/滑块/支付）：在对话里直接请用户在窗口里操作，收到"好了"再 browse_get_tree
+确认。不要编造凭据，不要重试注定失败的点击。窗口是真的，人随时能抢鼠标。
+
+收尾：browse_quit 关掉窗口和进程（人正在操作时不要调）。
 ```
 
-从源码运行时改用 `"command": "node"`，args 指向
-`/你的/绝对路径/ai-browser/src/main/mcp_server.js`（必须是绝对路径）。
+---
 
-* 首次启动会准备 Electron 引擎（约 100 MB，仅一次）；网络慢可在客户端的环境变量里设
-  `ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/`。
-* 无需事先启动浏览器：MCP 服务器会探测 `9223` 端口，没人在监听就自己 spawn Electron（最多等 30 秒）。
-* 想常驻浏览器也可以：在项目根目录跑 `npm start`，之后所有客户端共用这一个窗口。
-* 不装 MCP 也能用：原始 WebSocket JSON-RPC 在 `ws://localhost:9223`，见 `raw-ws.mjs`。
+## 详细内容在哪
 
----
+按需读，不要一次读完：
 
-## 参数速查
-
-| 工具 | 关键参数 | 说明 |
-|---|---|---|
-| `browse_navigate` | `url`, `tab?` | 打开 URL |
-| `browse_get_tree` | `subset`, `ax`, `mode`, `focused_only`, `tab` | 读语义树 + `context`（弹窗、必填提示、toast、登录态、统计） |
-| `browse_act` | `action`, `target`, `text?`, `value?`, `url?`, `keep_tab?`, `file?`, `tab?` | `target` = 节点 `id`（`data-ai-id`） |
-| `browse_evaluate` | `js`, `tab?` | 表达式（非语句），5000 字符上限 |
-| `browse_scroll` | `direction`, `amount`, `target`, `tab` | 滚页面或滚到某元素 |
-| `browse_wait` | `condition`, `target?`, `text?`, `timeout_ms?` | 轮询直到成立或超时 |
-| `browse_diff` | `operation` (`snapshot`/`diff`), `js?`, `snapshot?`, `rearm?`, `forget?` | 快照基线 + 比对，证明写操作真的生效 |
-| `browse_capabilities` | `include_network?`, `network_limit?` | 探明页面路线：L1 结构化数据 / L2 语义树 / L3 指针手势 |
-| `browse_network` | `operation` (`list`/`get`/`clear`/`configure`), `method?`, `url_contains?`, `status_min/max?` | 网络请求检查，含 POST body，默认免订阅 |
-| `browse_canvas` | `operation` (`list`/`read`/`configure`/`capture`), `canvas_id?` | 读 canvas 绘制调用文本；WebGL 才用 `capture` |
-| `browse_downloads` | — | 查下载项与落盘路径（下载异步，点完后轮询） |
-| `browse_repaint` | — | 窗口画面陈旧时强制合成器重绘，返回 `repaint_count` |
-| `browse_list_tabs` / `browse_new_tab` / `browse_close_tab` / `browse_set_active_tab` | `tab?`, `url?` | 标签页管理 |
-| `browse_quit` | — | 关闭窗口并退出进程 |
-
-> 实时事件订阅（`dom_change` / `network_response` / `js_error` 等）只在原始 WebSocket 层
-> 提供（`ui.subscribe`），MCP stdio 不支持 server→client 通知，所以没有 `browse_subscribe`；
-> 拉取式的检查一律用 `browse_network`。
+| 想知道 | 读 |
+|---|---|
+| 失败排查顺序、四条别做、省 token 的读树参数 | `skills/ai-browser/references/troubleshooting.md` |
+| canvas / 富文本 / 跨进程 iframe / 上传 | `skills/ai-browser/references/hard-pages.md` |
+| 抓请求、从页面取结构化数据 | `skills/ai-browser/references/network.md` |
+| 登录、表单、多标签、证明生效 | `skills/ai-browser/references/tasks.md` |
+| 全部参数 | 工具的 `inputSchema`（每轮都在，不用另读） |
 
----
+## 配置 MCP 服务器
 
-## 人工介入到底是怎么发生的
+见 `examples/mcp-config.json`，或：
 
-这是本项目最容易被误解的一点，说清楚：
+```json
+{ "mcpServers": { "ai-browser": {
+  "command": "npx", "args": ["-y", "@glittering0717/ai-browser", "mcp"]
+} } }
+```
 
-1. 浏览器窗口**真实可见**，人随时可以用鼠标键盘操作它——登录、扫码、滑块验证码都行。
-2. agent 做不了的事，**在对话里说一句人话请求用户去做**，然后停下来等回复。
-3. 用户做完回一句"好了"，agent 重新 `browse_get_tree` 确认状态，继续往下走。
-4. **浏览器侧没有任何"交接"接口，也不需要。** 交接是一个对话协议，不是一个 API。
-   脚本版的等价实现见 `with-human.mjs`：它只是 `readline` 打印一句提示 + 等回车，
-   浏览器对此毫不知情。
-5. 登录态存在 `persist:` partition 里，重启浏览器也还在，通常只需人工介入一次。
+浏览器由 agent 在第一次调用时自己拉起，不需要你手动开。

package/llms-install.md

@@ -11,8 +11,9 @@ semantic tree (roles / labels / values / actions, stable `data-ai-id` per elemen
 not screenshots. Input is trusted CDP keyboard/mouse events. A human can use the
 window's mouse and keyboard at any time (login, QR scan, CAPTCHA, payment).
 
-Two equivalent interfaces: **MCP stdio** (20 `browse_*` tools) and a raw WebSocket
-JSON-RPC API at `ws://localhost:9223` (`ui.*` methods).
+Two equivalent interfaces: **MCP stdio** (17 `browse_*` tools) and a raw WebSocket
+JSON-RPC API at `ws://localhost:9223` (`ui.*` methods). A CLI (`ai-browser call ui.xxx`) speaks
+the same JSON-RPC and needs **no registration at all** — see "Fastest path" below.
 
 ## Requirements
 
@@ -65,6 +66,28 @@ ls node_modules/electron/dist   # must contain Electron.app (macOS)
 Optional end-to-end check: `npx -y @glittering0717/ai-browser start` (or `npm start` from source) opens
 a 1280×800 window and logs `AI Browser WS server listening on ws://localhost:9223`.
 
+## Fastest path — works with zero registration
+
+If you just need to drive the browser now, skip the MCP section entirely. The CLI reaches the
+same engine, and **starts the browser itself if it is not running** (idempotent; no separate
+`start` step):
+
+```bash
+npm i -g @glittering0717/ai-browser     # or: npm link  (from a source checkout)
+ai-browser call ui.navigate '{"url":"https://example.com"}'
+ai-browser call ui.get_tree '{"subset":"interactive"}'
+ai-browser call ui.act '{"action":"click","target":"e:a-3"}'
+```
+
+No global install? Prefix every command with `npx -y @glittering0717/ai-browser`.
+
+Why this matters more than it looks: registering an MCP server passes through **three gates the
+agent does not control** — the config file, a one-time trust/approval for executing a local
+program, and the client's tool snapshot taken at session start. If any one of them has not
+completed, `browse_*` simply does not exist in the tool list, and the symptom is identical to
+"the capability is not installed". A weaker model then spends a long time concluding it is
+misconfigured. The CLI has none of those gates: it only needs the command to run.
+
 ## Register as an MCP server
 
 Add this to the client config (Claude Desktop config, `~/.cursor/mcp.json`, project `.mcp.json`,
@@ -84,13 +107,28 @@ Cline, etc.):
 From-source alternative: `"command": "node"` with the absolute path to
 `src/main/mcp_server.js`.
 
+> **Match the version, or nothing lines up.** The skill shipped in this package documents the
+> tool surface of the *same* version. Before pasting `npx` above, compare
+> `npm view @glittering0717/ai-browser version` with this repo's `package.json`. If they differ
+> (they have: npm 1.3.1 vs repo 2.0.0), use the from-source form with the source path — a 1.x
+> server behind a 2.x skill means every tool name and parameter in the skill is wrong, and a
+> small model cannot tell that apart from "the MCP server is down". A concrete field report:
+> a 35B local model spent a long session concluding "the skill is installed but the MCP server
+> is not mounted", correctly diagnosing a missing config entry while the real trap was that
+> nothing had been registered at all — see the `ai-browser` entry in the client's `mcp.json`.
+>
+> **No MCP at all?** The CLI speaks the same JSON-RPC and needs no registration:
+> `ai-browser status`, `ai-browser call ui.navigate '{"url":"..."}'`. Installing the package
+> globally (`npm i -g @glittering0717/ai-browser`) puts that binary on PATH; from a source
+> checkout, `npm link` does the same.
+
 Do **not** launch the browser yourself first: on the first `browse_*` call the MCP server probes
 port 9223, spawns Electron detached if nothing is listening, and waits up to 30 s (the very first
 call can take longer if the engine download hasn't happened yet — the progress goes to stderr).
 A long-lived shared window is also fine — run the `start` command manually; a second launch only
 focuses the existing window (single instance lock).
 
-## The 20 tools
+## The 17 tools
 
 - `browse_navigate` — load a URL in the active or given tab.
 - `browse_get_tree` — semantic tree + context (modals, toasts, required-field
@@ -100,6 +138,11 @@ focuses the existing window (single instance lock).
   `setContent` (replace all), `clear`, `focus`, `hover`, `scroll_to`, `upload`,
   `get_value` (read-only full value; tree truncates at 200 chars), `drag`,
   `press`, `wheel`.
+  Every result carries `effect_state: "committed" | "none" | "unknown"` plus a
+  `retry` verdict (`no` / `safe` / `verify_first`). Treat `unknown` as "read the
+  page before touching it again" — a blind retry can submit twice. A missing
+  target adds `stale_ref` + `ref_diagnosis` (`stale` → re-read the tree;
+  `never_seen` → the ref itself is wrong; `present_in_tree` → iframe/shadow DOM).
 - `browse_diff` — `snapshot` a baseline, then `diff`; returns an explicit
   `verdict: "changed" | "unchanged"` with before/after JSON paths. Wrap every
   write with this — a success return is not evidence the write worked.
@@ -118,10 +161,29 @@ focuses the existing window (single instance lock).
 - `browse_repaint` — force compositor redraw when the window shows a stale page.
 - `browse_downloads` — list downloads with on-disk paths (poll after clicking
   export/download; downloads are asynchronous).
-- `browse_list_tabs`, `browse_new_tab`, `browse_close_tab`,
-  `browse_set_active_tab` — tab management.
+- `browse_tabs` — tab management: `{op: "list" | "new" | "close" | "switch"}`.
+  `switch` sets the default target for later calls, so you rarely pass `tab`.
 - `browse_quit` — shut the whole browser down and release the process.
 
+**Which door should you use?** Prefer the **CLI** unless the tool list already contains
+`browse_*`. MCP is a nicer interface (schemas are self-describing) but it is not under your
+control; the CLI is. Both hit one implementation (`page_manager`) — there is no capability that
+only exists over MCP.
+
+```bash
+ai-browser status                                   # is it running? pid / port / tabs
+ai-browser ensure                                   # start it if needed, then exit
+ai-browser call ui.list_tabs
+ai-browser call ui.navigate '{"url":"..."}'
+```
+
+CLI method names are the tool names with `browse_` → `ui.` (`get_tree`, `act`, `navigate`,
+`evaluate`, `scroll`, `wait`, `screenshot`, `errors`, `capabilities`, `downloads`, `quit`,
+`auth_state`, `repaint`). The four that do not map one-to-one: `tabs` → `ui.list_tabs` /
+`ui.new_tab` / `ui.close_tab` / `ui.set_active_tab`; `network` → `ui.network_list` /
+`ui.network_get`; `canvas` → `ui.canvas_list` / `ui.canvas_read` / `ui.canvas_capture` /
+`ui.canvas_configure`; `diff` → `ui.snapshot` / `ui.diff`.
+
 There is no `browse_subscribe` and no `browse_network_body`: real-time events are
 raw-WebSocket only (`ui.subscribe`), because MCP stdio drops server→client
 notifications. Use `browse_network` for pull-based inspection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittering0717/ai-browser",
-  "version": "1.3.1",
+  "version": "2.1.0",
   "description": "AI-native browser — renders pixels for humans, structured semantic-tree API for agents. No screenshots, no OCR, no coordinate guessing.",
   "main": "src/main/index.js",
   "bin": {
@@ -10,6 +10,7 @@
     "bin",
     "scripts",
     "src",
+    "skills",
     "tools/coverage_probe.cjs",
     "examples/AGENT_INSTRUCTIONS.md",
     "examples/mcp-config.json",
@@ -70,6 +71,7 @@
     "nav": "node e2e/nav_ws.cjs",
     "audit": "node e2e/audit_ws.cjs",
     "e2e:all": "node e2e/run_all.cjs",
+    "readcov": "node e2e/readcov_ws.cjs",
     "coverage": "node tools/coverage_probe.cjs"
   },
   "dependencies": {