docs(skill/help): document fork.51 features — coordinate click, aliases, stale-sessionId + @url drift checks

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
This commit is contained in:
leeguooooo
2026-06-12 09:56:02 +09:00
parent 0cf7de2dd6
commit 36f9b99549
3 changed files with 39 additions and 2 deletions
+1
View File
@@ -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
```
+7 -2
View File
@@ -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
+31
View File
@@ -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: