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:
@@ -178,6 +178,7 @@ agent-browser open https://example.com
|
|||||||
|
|
||||||
# Everything works through your logged-in browser
|
# Everything works through your logged-in browser
|
||||||
agent-browser click "Post"
|
agent-browser click "Post"
|
||||||
|
agent-browser click 449 320 # …or click a raw viewport coordinate
|
||||||
agent-browser fill "Title" "Hello World"
|
agent-browser fill "Title" "Hello World"
|
||||||
agent-browser screenshot ./page.png
|
agent-browser screenshot ./page.png
|
||||||
```
|
```
|
||||||
|
|||||||
+7
-2
@@ -1261,14 +1261,19 @@ Examples:
|
|||||||
// === Core Actions ===
|
// === Core Actions ===
|
||||||
"click" => {
|
"click" => {
|
||||||
r##"
|
r##"
|
||||||
agent-browser click - Click an element
|
agent-browser click - Click an element or a coordinate
|
||||||
|
|
||||||
Usage: agent-browser click <selector> [--new-tab]
|
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,
|
Clicks on the specified element. The selector can be a CSS selector,
|
||||||
XPath, or an element reference from snapshot (e.g., @e1).
|
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:
|
Options:
|
||||||
|
--coords <x>,<y> Click a viewport coordinate (explicit form)
|
||||||
--new-tab Open link in a new tab instead of navigating current tab
|
--new-tab Open link in a new tab instead of navigating current tab
|
||||||
(only works on elements with href attribute)
|
(only works on elements with href attribute)
|
||||||
|
|
||||||
@@ -3034,7 +3039,7 @@ Start here (for AI agents):
|
|||||||
|
|
||||||
Core Commands:
|
Core Commands:
|
||||||
open <url> Navigate to URL
|
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
|
dblclick <sel> Double-click element
|
||||||
type <sel> <text> Type into element
|
type <sel> <text> Type into element
|
||||||
fill <sel> <text> Clear and fill
|
fill <sel> <text> Clear and fill
|
||||||
|
|||||||
@@ -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
|
that one with `AGENT_BROWSER_CLICK_MODE=dom agent-browser click ...`, or just
|
||||||
`agent-browser eval "<select the item via JS>"`.
|
`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)
|
## Waiting (read this)
|
||||||
|
|
||||||
Agents fail more often from bad waits than from bad selectors. Pick the
|
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
|
```bash
|
||||||
agent-browser tab # list open tabs (with stable tabId)
|
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 new https://docs... # open a new tab (and switch to it)
|
||||||
agent-browser tab t2 # switch to tab t2
|
agent-browser tab t2 # switch to tab t2
|
||||||
agent-browser tab close t2 # close 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
|
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
|
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
|
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
|
```bash
|
||||||
agent-browser network route "**/api/users" --body '{"users":[]}' # stub a response
|
agent-browser network route "**/api/users" --body '{"users":[]}' # stub a response
|
||||||
agent-browser network route "**/analytics" --abort # block entirely
|
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 requests # inspect what fired
|
||||||
agent-browser network har start # record all traffic
|
agent-browser network har start # record all traffic
|
||||||
# ... perform actions ...
|
# ... perform actions ...
|
||||||
@@ -571,6 +587,21 @@ agent-browser snapshot -i
|
|||||||
Some modals and cookie banners block other clicks. Snapshot, find the
|
Some modals and cookie banners block other clicks. Snapshot, find the
|
||||||
dismiss/close button, click it, then re-snapshot.
|
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**
|
**Fill / type doesn't work**
|
||||||
Some custom input components intercept key events. Try:
|
Some custom input components intercept key events. Try:
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user