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

capture_screenshot() → base64 PNG

click_at_xy(100, 200) — CDP 完整鼠标点击序列 (isTrusted:true)

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

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。

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}。

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 targetId。

js("document.title") — 在当前页面执行 JS，返回完成值。 先按裸表达式/脚本 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}]。

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

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

new_tab("https://example.com") — 开新标签，加入 nekoro 托管组，切过去并 attach。 走扩展 navigate action：chrome.tabs.create + 分组 + waitTabLoad 等真实 load 事件， 尽量等到加载完（不像原来裸 Target.createTarget 直接返回、后续 wait 撞 about:blank stale-complete 竞态）；超时则 loaded=False。返回 {tabId, loaded}，之后 helper 直接 作用于新标签。注意：load 等待上限由扩展内部硬编码（~10s），timeout 只界定这条 RPC 的传输上限（取 max(timeout,10)+5，保证不早于扩展的 load 等待就超时），并不缩短扩展 侧的 load 等待预算。

page_html() → 完整 HTML

page_info() → {title, url}

page_text() → 可见文本

press_key("Enter") / press_key("a") — 修饰键位: Alt=1 Ctrl=2 Meta=4 Shift=8。 特殊键（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。

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}] — 索引元素树

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

type_text("hello") — CDP Input.insertText

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_load(15) — poll document.readyState (无 listener 泄漏)。

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.