box_of(".btn") → {x, y, w, h, visible, tag, text}

capture_screenshot() → base64 图 + 尺寸元信息。

click("css:.btn") / click("text:登录") / click("index:3") / click("xpath://button[contains(.,'登录')]") / click("placeholder:关键词") — 统一定位点击（借鉴 ego-lite 的 locator 语法）。一个入口覆盖所有定位形式， 不用在 click_selector / click_text / click_index 之间挑；nth:N; 前缀取第 N 个 匹配（nth:2;css:.btn），只对 css/xpath/placeholder 有效——text/index 走的是 扩展 op，扩展只回第一个匹配，给了 nth 会直接报 permanent 而不是悄悄点第一个。

click_at_xy(100, 200) — CDP 完整鼠标点击序列 (isTrusted:true)。 tab 指定目标标签（须已 attach）；不传打当前活动标签。

click_index(3) — CDP 真实坐标点击 (isTrusted:true)

click_ref(123) — 用 backendNodeId 点击（跨轮次稳定句柄）。

click_selector(".btn") — CDP 真实坐标点击 (isTrusted:true)

click_text("喜欢") — CDP 真实坐标点击 (isTrusted:true)

close_tab(123) — 关掉指定标签；tab 省略则关当前 attached tab。 走扩展 close_tab action（chrome.tabs.remove）。关掉活动标签后扩展会自动重连到 另一可用标签、经 attach 回调同步 active_tab_id。无标签可关 → ok:false。

close_tabs([1,2,3]) — 批量关标签，逐个走 close_tab，返回 {closed, failed}。 一张关不掉不影响其余（标签可能已被用户手动关掉）。

dialog_off() — JS 层覆盖 window.alert/confirm/prompt 为自动关闭（需在触发前注入， 盖不住 beforeunload / 已开的原生对话框）。想要兜底防挂用扩展的 CDP 层处置（见 get_last_dialog）——那个 attach 后一直生效、覆盖 beforeunload。

drain_events() → list — 拉取自上次 drain 后所有缓存的 CDP 事件。 每个事件为 {method, params, sessionId, tabId}（tabId 用于按标签过滤）。

ensure_real_tab() — 当前 tab 是 chrome:// 等内部页时自动导航到 about:blank。 返回 {url, title}。

ensure_tab("https://example.com") — 复用优先的导航（借鉴 ego-lite 的 browser.openOrReuseTab：名字即语义，不用调用方记得传 reuse=True）。

fill_input("#email", "a@b.com") — 框架感知填值。 走 scripting：原生 value setter 写值 + 派发 input/change，React/Vue 受控组件 能收到 onChange（type_text 的 Input.insertText 常绕不过框架 setter）。 非 input/textarea/contenteditable 或找不到元素 → ok:false，不伪造成功。 自定义组件要真实键入用 click_selector + type_text。

find_text("喜欢") → [{text, tag, match, w, h}]

get_cookies("https://example.com")

get_last_dialog() → {dialog} — 取最近一次被扩展自动处置的原生对话框，读后清。 attach 后扩展 Page.enable + 拦 Page.javascriptDialogOpening 立即处置（beforeunload 放行、alert/confirm/prompt 取消），防原生对话框冻结页面 JS 线程导致 evaluate 系 helper 挂死。dialog = {kind, message, url, defaultPrompt} 或 None（期间无对话框）。 仅事后观测，不能代答：需 confirm()===true 或特定 prompt 字符串的流程会被无条件取消。

get_markdown() → 页面内容转 Markdown

get_response_body("1234.5") → CDP 网络响应体

hover(".menu") — CSS 选择器悬停

hover_index(3) — 悬停 state() 列表的第 N 个元素

http_get("https://example.com") → 纯 HTTP GET 返回 HTML 字符串。用于静态页/API。

iframe_target("player") → 第一个 URL 含 url_substr 的 iframe 的 frameId。

js("document.title") — 在页面执行 JS，返回完成值。tab 不传打当前活动标签。 先按裸表达式/脚本 eval（document.title 直接返回标题）；顶层 return 触发 "Illegal return statement" 时自动包进函数重试（return x 也能用）。 不可 JSON 序列化的值（Infinity/NaN/-0/BigInt）解码回 Python 值，不再吐原始 dict。 页内异常 / eval 出错 → ok:false，不伪造成功。

list_site_actions() → 已固化的站点函数 + 载入失败的文件。

list_tabs() → nekoro 托管组里的标签 [{tabId,url,title,active,attached}]。 grouped: False 表示托管组还没建起来，这份清单其实是「所有非 chrome:// 标签」， 里面混着用户自己的标签——别拿它当「nekoro 开的标签」用（老版本扩展不带该字段）。

navigate("https://example.com") — 默认等 readyState==='complete' 再返回。 wait=False 立即返回（Page.navigate 一发出就走）。loaded 标记是否等到加载完成。

network_enable() — 启用 CDP 网络请求捕获

new_tab("https://example.com") — 开新标签，加入 nekoro 托管组，切过去并 attach； reuse=True 则优先复用托管组里已有的同站标签（登录态和页面状态都还在），不新开。

page_html() → 完整 HTML。tab 不传打当前活动标签。

page_info() → {title, url}。tab 不传打当前活动标签。

page_text() → 可见文本。tab 不传打当前活动标签。

press_key("Enter") / press_key("a") — 修饰键位: Alt=1 Ctrl=2 Meta=4 Shift=8。 tab 不传打当前活动标签。 特殊键（Enter/Tab/Arrow*/Backspace…）带 virtual key code，监听 e.keyCode/e.which/e.key 的页面（表单、老站）都能触发；单字符可打印键补发 char 事件（直接进 input，不走 insertText）； Alt/Ctrl/Meta 修饰时不发 char（让 Ctrl+A 走快捷键而非打出字符 'a'）。 移植 browser-harness press_key。

refs() → [{ref, tag, text}] — 可交互元素 + 稳定句柄（CDP backendNodeId）。 tab 不传取当前活动标签。

reload_agent_helpers() — 重新加载 agent_helpers.py，无需重启 daemon。

reload_extension() — 强制重载扩展（自愈用）

scroll_into_view("#target") — 滚动到可见

scroll_to(0, 500) — 滚动页面视口到坐标 (window.scrollTo)

scroll_wheel(0, 500) — CDP compositor 级 mouseWheel（能穿透 iframe/shadow DOM）。 fire-and-forget 修复后 CDP Input.dispatchMouseEvent 不再超时。

set_cookie("token", "abc", domain=".example.com")

sleep(2)

state() → [{index, changed, tag, text, box}] — 索引元素树

sweep_tabs() — 列出可清理的标签候选，默认只报不关。

switch_tab(123) — 把后续命令切到该标签（未 attach 则先 attach）。

type_text("hello") — CDP Input.insertText。tab 不传打当前活动标签。

upload_file("input[type=file]", r"C:\a.png") — 给文件输入框设文件。 走 CDP DOM.setFileInputFiles（触发 change 事件，框架能收到）；path 为绝对路径， 单个 str 或多个 list。文件不存在 / 找不到元素 / 元素非 file input → ok:false，不伪造成功。 注意：作用于当前 attached tab，nodeId 经 daemon.query_selector 解析。

wait_for_download(30) — 点击下载后等待完成（Page.downloadWillBegin/Progress 事件）。

wait_for_load(15) — poll document.readyState (无 listener 泄漏)。 tab 不传等当前活动标签。

wait_for_network_idle(0.5, 15) — 等待【当前活动标签】的 Network 请求静默 idle_time 秒。 只算 active_tab_id 的事件：其它 attached 标签（后台轮询/SSE 页）的 Network 事件也进全局 缓冲，不过滤会一直把 idle 窗口顶开、永不静默。

wait_selector(".modal", "visible", 15) — 等待元素状态

Raw CDP command, e.g. method='Page.navigate', params={'url': 'https://example.com'}.

Escape hatch: run arbitrary Python in the daemon namespace (all helpers pre-bound, top-level await allowed). Use when no single tool fits — e.g. multi-step flows in one round trip.