@glittering0717/ai-browser 1.3.1 → 2.0.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,22 @@ 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
+  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 +65,24 @@ 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 '--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

@@ -84,6 +84,21 @@ 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).
@@ -100,6 +115,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 +138,15 @@ 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.
 
+Prefer MCP when an agent client drives the browser. For shell / CI / debugging there is a CLI
+that speaks the same JSON-RPC: `ai-browser status`, `ai-browser call ui.list_tabs`,
+`ai-browser call ui.navigate '{"url":"..."}'`. One implementation, three doors — no separate
+script needed to call a method.
+
 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.0.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": {

package/scripts/cli_call.cjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// scripts/cli_call.cjs — 命令行直接调浏览器，**不用写任何客户端脚本**。
+//
+// 为什么要有这个（真实抱怨，2026-10-19）：
+//   「我看操作这个项目，经常需要写 cjs 代码，这是必须的吗？」
+//   不是必须的，但以前确实没有别的办法：对外只有两个入口 —— MCP stdio（给 agent
+//   客户端用）和裸 WebSocket JSON-RPC（ws://127.0.0.1:9223）。想从 shell 里问一句
+//   "现在有哪些标签页"，就得先 npm i ws、再写一个连上发 JSON 的小脚本、再等回包。
+//   一个本来只是一行命令的事情，被迫变成"写代码"。
+//
+// 所以这里补的是**通道**，不是新能力：它做的就是把一条 JSON-RPC 发出去、把 result
+// 打出来。所有能力仍然只有一套实现（page_manager），MCP 和 CLI 都是它的薄壳。
+//
+// 用法：
+//   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 -
+//   ai-browser call ui.act '{"action":"click","target":"e:a-1"}'
+//   ai-browser status
+//
+// 选项：
+//   --port <n>       默认 9223（也读 AI_BROWSER_WS_PORT）
+//   --timeout <ms>   默认 30000
+//   --compact        单行输出（默认就是紧凑 JSON，加这个只是显式）
+//   --pretty         缩进输出（给人看时用）
+'use strict';
+
+const WS_PORT_DEFAULT = 9223;
+const TIMEOUT_DEFAULT = 30000;
+
+function parseArgs(argv) {
+  const out = { port: null, timeout: TIMEOUT_DEFAULT, pretty: false, rest: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--port') { out.port = Number(argv[++i]); continue; }
+    if (a === '--timeout') { out.timeout = Number(argv[++i]); continue; }
+    if (a === '--pretty') { out.pretty = true; continue; }
+    if (a === '--compact') { out.pretty = false; continue; }
+    out.rest.push(a);
+  }
+  if (!out.port || !Number.isFinite(out.port)) {
+    const envPort = Number(process.env.AI_BROWSER_WS_PORT);
+    out.port = Number.isFinite(envPort) && envPort > 0 ? envPort : WS_PORT_DEFAULT;
+  }
+  if (!Number.isFinite(out.timeout) || out.timeout <= 0) out.timeout = TIMEOUT_DEFAULT;
+  return out;
+}
+
+/** 把命令行里的 JSON 载荷解析成对象；空/缺省 → {}。 */
+function parsePayload(text) {
+  if (text === undefined) return {};
+  const t = String(text).trim();
+  if (!t) return {};
+  let val;
+  try {
+    val = JSON.parse(t);
+  } catch (e) {
+    const err = new Error(`payload is not valid JSON: ${e.message}\n  got: ${t.slice(0, 120)}`);
+    err.code = 'bad_json';
+    throw err;
+  }
+  if (val === null || typeof val !== 'object' || Array.isArray(val)) {
+    const err = new Error('payload must be a JSON object, e.g. {"url":"https://example.com"}');
+    err.code = 'bad_json';
+    throw err;
+  }
+  return val;
+}
+
+/**
+ * 发一条 JSON-RPC 并等回包。**不在这里做重试/重连** —— CLI 是同步语义：
+ * 一条命令一个结果，失败就把原因原样报出来，别替调用方猜。
+ */
+function rpcCall({ port, timeout, method, params }) {
+  // require 放在函数里：只有真的要连的时候才需要 ws（--help 之类不该加载它）。
+  const WebSocket = require('ws');
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const done = (fn, arg) => { if (!settled) { settled = true; try { ws.close(); } catch (_) {} fn(arg); } };
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    const timer = setTimeout(() => {
+      done(reject, Object.assign(new Error(`no reply from ${method} within ${timeout}ms`), { code: 'timeout' }));
+    }, timeout);
+
+    ws.on('open', () => {
+      ws.send(JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }));
+    });
+    ws.on('message', (data) => {
+      let msg;
+      try { msg = JSON.parse(String(data)); } catch (_) { return; }  // 事件广播不是回包，忽略
+      if (msg.id !== 1) return;
+      clearTimeout(timer);
+      if (msg.error) {
+        // 带上方法名：服务端只会说 "Method not found"，不带名字的话调用方还得自己
+        // 回想刚才打的是哪个（一条命令里可能有变量拼出来的方法名）。
+        const why = msg.error.message || 'rpc error';
+        done(reject, Object.assign(new Error(`${why} (${method})`), { code: 'rpc_error', rpc: msg.error }));
+      } else {
+        done(resolve, msg.result);
+      }
+    });
+    ws.on('error', (e) => {
+      clearTimeout(timer);
+      const hint = /ECONNREFUSED/i.test(e.message)
+        ? `浏览器没在 127.0.0.1:${port} 上跑。先 \`ai-browser start\`（MCP 客户端会自己拉起），或用 --port 指定别的端口。`
+        : e.message;
+      done(reject, Object.assign(new Error(hint), { code: 'connect_failed' }));
+    });
+  });
+}
+
+function printResult(result, pretty) {
+  if (result === undefined) { process.stdout.write('null\n'); return; }
+  const text = pretty ? JSON.stringify(result, null, 2) : JSON.stringify(result);
+  process.stdout.write(text + '\n');
+}
+
+async function runCall(argv) {
+  const opt = parseArgs(argv);
+  const method = opt.rest[0];
+  if (!method) {
+    process.stderr.write('usage: ai-browser call <method> [json|-] [--port n] [--timeout ms] [--pretty]\n'
+      + '  e.g. ai-browser call ui.list_tabs\n'
+      + '       ai-browser call ui.get_tree \'{"subset":"interactive"}\'\n');
+    return 2;
+  }
+  let params;
+  try {
+    const raw = opt.rest[1] === '-' ? readStdin() : opt.rest[1];
+    params = parsePayload(raw);
+  } catch (e) {
+    process.stderr.write(`[ai-browser] ${e.message}\n`);
+    return 2;
+  }
+  try {
+    const result = await rpcCall({ port: opt.port, timeout: opt.timeout, method, params });
+    printResult(result, opt.pretty);
+    return 0;
+  } catch (e) {
+    process.stderr.write(`[ai-browser] ${e.message}\n`);
+    return 1;
+  }
+}
+
+async function runStatus(argv) {
+  const opt = parseArgs(argv);
+  try {
+    const info = await rpcCall({ port: opt.port, timeout: Math.min(opt.timeout, 5000), method: 'ui.server_info', params: {} });
+    let tabs = null;
+    try { tabs = await rpcCall({ port: opt.port, timeout: Math.min(opt.timeout, 5000), method: 'ui.list_tabs', params: {} }); } catch (_) {}
+    const out = {
+      running: true,
+      port: opt.port,
+      pid: info && info.pid,
+      started_at: info && info.started_at,
+      platform: info && info.platform,
+      tabs: tabs && tabs.tabs ? tabs.tabs.map((t) => ({ id: t.id, active: t.active, title: t.title, url: t.url })) : null,
+    };
+    printResult(out, opt.pretty);
+    return 0;
+  } catch (e) {
+    // 没跑**不是错误状态**：这是用户最常问的第一个问题，答案要清楚、可执行。
+    printResult({ running: false, port: opt.port, reason: e.message }, opt.pretty);
+    return 1;
+  }
+}
+
+// stdin 读成字符串（供 `... | ai-browser call ui.navigate -` 用）
+function readStdin() {
+  try {
+    return require('node:fs').readFileSync(0, 'utf8');
+  } catch (_) {
+    return '';
+  }
+}
+
+module.exports = { runCall, runStatus, parsePayload, parseArgs, rpcCall, WS_PORT_DEFAULT };