From 36f9b995492c902830817b9a2354b1810e32263c Mon Sep 17 00:00:00 2001
From: leeguooooo <guoli@zhihu.com>
Date: Fri, 12 Jun 2026 09:56:02 +0900
Subject: [PATCH] =?UTF-8?q?docs(skill/help):=20document=20fork.51=20featur?=
 =?UTF-8?q?es=20=E2=80=94=20coordinate=20click,=20aliases,=20stale-session?=
 =?UTF-8?q?Id=20+=20@url=20drift=20checks?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SKILL.md + click --help + README now cover what agents could otherwise
only discover by trial:
- coordinate click (click <x> <y> / <x>,<y> / --coords) as a first-class form
- tabs / get-text aliases
- the 'stale sessionId … re-open your target URL' relay error and how to recover
- eval/screenshot/network '@ <url>' stamps as a per-read wrong-tab sanity check
- network requests --clear as the 'start capturing fresh' step
---
 README.md                |  1 +
 cli/src/output.rs        |  9 +++++++--
 skill-data/core/SKILL.md | 31 +++++++++++++++++++++++++++++++
 3 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ed097a0..21c971b 100644
--- a/README.md
+++ b/README.md
@@ -178,6 +178,7 @@ agent-browser open https://example.com
 
 # Everything works through your logged-in browser
 agent-browser click "Post"
+agent-browser click 449 320            # …or click a raw viewport coordinate
 agent-browser fill "Title" "Hello World"
 agent-browser screenshot ./page.png
 ```
diff --git a/cli/src/output.rs b/cli/src/output.rs
index 9ce40c8..db073b6 100644
--- a/cli/src/output.rs
+++ b/cli/src/output.rs
@@ -1261,14 +1261,19 @@ Examples:
         // === Core Actions ===
         "click" => {
             r##"
-agent-browser click - Click an element
+agent-browser click - Click an element or a coordinate
 
 Usage: agent-browser click <selector> [--new-tab]
+       agent-browser click <x> <y> | <x>,<y> | --coords <x>,<y>
 
 Clicks on the specified element. The selector can be a CSS selector,
 XPath, or an element reference from snapshot (e.g., @e1).
 
+A bare-number argument is treated as a viewport coordinate, not a
+selector — `click 449 320` clicks the pixel point (no element needed).
+
 Options:
+  --coords <x>,<y>     Click a viewport coordinate (explicit form)
   --new-tab            Open link in a new tab instead of navigating current tab
                        (only works on elements with href attribute)
 
@@ -3034,7 +3039,7 @@ Start here (for AI agents):
 
 Core Commands:
   open <url>                 Navigate to URL
-  click <sel>                Click element (or @ref)
+  click <sel|x y>            Click element/@ref, or a viewport coordinate
   dblclick <sel>             Double-click element
   type <sel> <text>          Type into element
   fill <sel> <text>          Clear and fill
diff --git a/skill-data/core/SKILL.md b/skill-data/core/SKILL.md
index a48523e..6844cea 100644
--- a/skill-data/core/SKILL.md
+++ b/skill-data/core/SKILL.md
@@ -270,6 +270,17 @@ classic for an autocomplete/menu `<li>` that closes on the input's blur — retr
 that one with `AGENT_BROWSER_CLICK_MODE=dom agent-browser click ...`, or just
 `agent-browser eval "<select the item via JS>"`.
 
+Click a raw pixel point when the only handle you have is a coordinate (canvas,
+a marker from a screenshot, a target with no stable selector):
+
+```bash
+agent-browser click 449 320            # click viewport point (x y)
+agent-browser click 449,320            # same, comma form
+agent-browser click --coords 449,320   # same, explicit flag
+```
+
+A bare-number argument is always a coordinate, never a selector.
+
 ## Waiting (read this)
 
 Agents fail more often from bad waits than from bad selectors. Pick the
@@ -433,11 +444,15 @@ Pass `--hide-scrollbars false` when launching to keep native scrollbars visible.
 
 ```bash
 agent-browser tab                      # list open tabs (with stable tabId)
+agent-browser tabs                     # alias for `tab` (lists too)
 agent-browser tab new https://docs...  # open a new tab (and switch to it)
 agent-browser tab t2                   # switch to tab t2
 agent-browser tab close t2             # close tab t2
 ```
 
+(`tabs` → the `tab` subcommand tree, and `get-text <sel>` → `get text <sel>` —
+common-guess aliases so you don't waste a round on the wrong spelling.)
+
 Tab ids are stable strings (`t1`, `t2`, …), never reused within a session, so
 the same id keeps referring to the same tab across commands. Positional
 integers are **not** accepted — use `t2`, not `2`. After switching, refs from a
@@ -476,6 +491,7 @@ extension (each with a distinct `--session`), not raw `--cdp`.
 ```bash
 agent-browser network route "**/api/users" --body '{"users":[]}'   # stub a response
 agent-browser network route "**/analytics" --abort                 # block entirely
+agent-browser network requests --clear                             # start capturing fresh
 agent-browser network requests                                     # inspect what fired
 agent-browser network har start                                    # record all traffic
 # ... perform actions ...
@@ -571,6 +587,21 @@ agent-browser snapshot -i
 Some modals and cookie banners block other clicks. Snapshot, find the
 dismiss/close button, click it, then re-snapshot.
 
+**`stale sessionId … re-open your target URL` (extension-relay mode)**
+Your tab was closed, navigated across processes, or its debugger detached
+(e.g. it landed on a `chrome://` or Chrome Web Store page, which Chrome
+forbids debugging). The session no longer has a live tab — re-run
+`agent-browser open <your URL>` to re-attach, then retry. This loud error
+replaces the old silent behaviour where the command ran on some *other*
+tab and returned wrong data.
+
+**Reads landing on the wrong page**
+`eval`, `screenshot`, and `network requests` print the page they ran
+against to stderr: `eval @ <url>`, `screenshot @ <url>`, `network @ <url>`.
+If that URL isn't the page you expected (the active tab drifted), re-`open`
+your target URL — don't trust the result. Treat the stamp as a built-in
+sanity check on every read.
+
 **Fill / type doesn't work**
 Some custom input components intercept key events. Try: