参考 / Reference

命令参考

这是 chrome-use 全部命令、别名与旗标的完整速查表。按命令组组织，方便扫读与查证。 想先建立整体节奏，请看 核心循环；命令跑不通时，翻 故障排查。

ℹ️ 约定
交互命令里的 @e1、@e2 是 snapshot 输出的元素引用（ref）。 先跑 snapshot -i 拿到 ref，再用 ref 操作。带 @ref 的命令始终作用在快照运行时的当前活动标签页。

导航

打开、跳转、前进后退与关闭浏览器。open 不带 URL 时只启动浏览器、停在 about:blank，便于在首次真正导航之前先注册网络拦截、Cookie 或 init 脚本。

navigation 
# 只启动浏览器，不导航；停在 about:blank
$ chrome-use open
# 启动并导航（别名：goto, navigate）；无协议时自动补 https://
$ chrome-use open <url>
$ chrome-use back                # 后退
$ chrome-use forward             # 前进
$ chrome-use reload              # 重新加载
# SPA 客户端导航：自动探测 Next.js router.push，回退 history.pushState
$ chrome-use pushstate <url>
$ chrome-use close               # 关闭浏览器（别名：quit, exit）
$ chrome-use connect 9222        # 通过 CDP 端口连接

导航前的准备可以用 batch 在一轮里排好队 —— 先干净启动，再依次注册拦截 / Cookie，最后导航。 适合 SSR-only 调试（只放行 --resource-type script 之外）、受保护来源鉴权，或抓取干净的 react suspense / vitals 状态。

pre-navigation batch 
$ chrome-use batch \
    '["open"]' \
    '["network","route","*","--abort","--resource-type","script"]' \
    '["cookies","set","--curl","cookies.curl","--domain","localhost"]' \
    '["navigate","http://localhost:3000/target"]'

快照（页面分析）

snapshot 拿到页面的结构化可访问性视图，是所有交互的起点。 推荐 snapshot -i：只列可交互元素，输出精简、ref 齐全。

snapshot 
$ chrome-use snapshot            # 完整可访问性树
$ chrome-use snapshot -i         # 仅可交互元素（推荐）
$ chrome-use snapshot -c         # 精简输出
$ chrome-use snapshot -d 3       # 限制深度为 3
$ chrome-use snapshot -s "#main" # 限定到 CSS 选择器范围
✅ 小贴士
snapshot -i 只呈现可见、可交互的元素 —— 它不显示隐藏输入或控件的实际提交值。 表单"看起来填好了"却过不了校验时，别对着快照猜，直接用 eval 查 DOM。

交互操作

用 snapshot 拿到的 @ref 驱动真实浏览器：点击、输入、勾选、拖拽、上传。

interactions 
$ chrome-use click @e1           # 点击
$ chrome-use click @e1 --new-tab # 点击并在新标签打开
$ chrome-use dblclick @e1        # 双击
$ chrome-use focus @e1           # 聚焦元素
$ chrome-use fill @e2 "text"     # 清空后输入
$ chrome-use type @e2 "text"     # 直接输入（不清空）
$ chrome-use press Enter         # 按键（别名：key）
$ chrome-use press Control+a     # 组合键
$ chrome-use keydown Shift       # 按住键
$ chrome-use keyup Shift         # 释放键
$ chrome-use hover @e1           # 悬停
$ chrome-use check @e1           # 勾选复选框
$ chrome-use uncheck @e1         # 取消勾选
$ chrome-use select @e1 "value"   # 选择下拉项
$ chrome-use select @e1 "a" "b"   # 多选
$ chrome-use scroll down 500     # 滚动页面（默认 down 300px）
$ chrome-use scrollintoview @e1  # 滚动元素进入视口（别名：scrollinto）
$ chrome-use drag @e1 @e2        # 拖放
$ chrome-use upload @e1 file.pdf # 上传文件
⚠️ 点击"成功但没反应"
自动补全 / 菜单 <li> 项常在输入框失焦时关闭。若 click 报成功但页面没反应， 用 AGENT_BROWSER_CLICK_MODE=dom 重试该次点击 —— DOM 派发不会像真实指针那样移动焦点，选项仍会被选中。

读取信息

从元素或页面读取文本、HTML、属性、值、包围盒与计算样式。

get 
$ chrome-use get text @e1        # 元素文本
$ chrome-use get html @e1        # innerHTML
$ chrome-use get value @e1       # 输入框的值
$ chrome-use get attr @e1 href   # 属性
$ chrome-use get title           # 页面标题
$ chrome-use get url             # 当前 URL
$ chrome-use get cdp-url         # CDP WebSocket URL
$ chrome-use get count ".item"   # 匹配元素数量
$ chrome-use get box @e1         # 包围盒
$ chrome-use get styles @e1      # 计算样式（字体、颜色、背景等）

检查状态

is 
$ chrome-use is visible @e1      # 是否可见
$ chrome-use is enabled @e1      # 是否可用
$ chrome-use is checked @e1      # 是否勾选

截图与 PDF

screenshot / pdf 
$ chrome-use screenshot          # 保存到临时目录
$ chrome-use screenshot path.png # 保存到指定路径
$ chrome-use screenshot --full   # 整页截图
$ chrome-use pdf output.pdf      # 保存为 PDF

无头 Chromium 截图会隐藏原生滚动条以获得一致的图像输出。启动时传 --hide-scrollbars false 可保留原生滚动条。

录屏

record 
$ chrome-use record start ./demo.webm    # 开始录制
$ chrome-use click @e1                   # 执行操作
$ chrome-use record stop                 # 停止并保存
$ chrome-use record restart ./take2.webm # 停止当前 + 开始新录制

等待

在断言状态前等待元素、文本、URL、网络空闲或任意 JS 条件。

wait 
$ chrome-use wait @e1                     # 等待元素
$ chrome-use wait 2000                    # 等待毫秒数
$ chrome-use wait --text "Success"        # 等待文本（或 -t）
$ chrome-use wait --url "**/dashboard"    # 等待 URL 模式（或 -u）
$ chrome-use wait --load networkidle       # 等待网络空闲（或 -l）
$ chrome-use wait --fn "window.ready"     # 等待 JS 条件（或 -f）

鼠标控制

mouse 
$ chrome-use mouse move 100 200      # 移动鼠标
$ chrome-use mouse down left         # 按下按键
$ chrome-use mouse up left           # 释放按键
$ chrome-use mouse wheel 100         # 滚轮

语义定位器

ref 之外的另一种定位方式：按角色、文本、标签、占位符、alt、title、testid 或位置定位， 并直接跟上要执行的动作。

find 
$ chrome-use find role button click --name "Submit"
$ chrome-use find text "Sign In" click
$ chrome-use find text "Sign In" click --exact      # 仅精确匹配
$ chrome-use find label "Email" fill "user@test.com"
$ chrome-use find placeholder "Search" type "query"
$ chrome-use find alt "Logo" click
$ chrome-use find title "Close" click
$ chrome-use find testid "submit-btn" click
$ chrome-use find first ".item" click
$ chrome-use find last ".item" click
$ chrome-use find nth 2 "a" hover

浏览器设置

set 
$ chrome-use set viewport 1920 1080          # 视口尺寸
$ chrome-use set viewport 1920 1080 2        # 2x 视网膜（CSS 尺寸不变，截图分辨率更高）
$ chrome-use set device "iPhone 14"          # 模拟设备
$ chrome-use set geo 37.7749 -122.4194       # 地理位置（别名：geolocation）
$ chrome-use set offline on                  # 离线模式开关
$ chrome-use set headers '{"X-Key":"v"}'     # 额外 HTTP 头
$ chrome-use set credentials user pass       # HTTP 基本认证（别名：auth）
$ chrome-use set media dark                  # 模拟配色方案
$ chrome-use set media light reduced-motion  # 浅色 + 减少动效

Cookie 与存储

cookies / storage 
$ chrome-use cookies                     # 获取所有 Cookie
$ chrome-use cookies set name value      # 设置 Cookie
$ chrome-use cookies clear               # 清空 Cookie
$ chrome-use storage local               # 全部 localStorage
$ chrome-use storage local key           # 指定键
$ chrome-use storage local set k v       # 设置值
$ chrome-use storage local clear         # 全部清空

从 cURL 导入 Cookie

自动识别格式：{name, value} 的 JSON 数组、DevTools → Network → Copy as cURL 的转储， 或裸 Cookie 头。出错时绝不回显 Cookie 值。

cookies set --curl 
$ chrome-use cookies set --curl <file>                       # 自动识别 JSON / cURL / Cookie 头
$ chrome-use cookies set --curl <file> --domain example.com  # 限定域名

网络拦截

拦截、阻断、Mock 响应、改写请求，或编辑真实响应。深入用法见 核心循环 中的网络章节。

network 
$ chrome-use network route <url>              # 拦截请求
$ chrome-use network route <url> --abort      # 阻断请求
# Mock 响应（fulfill）
$ chrome-use network route <url> --body '{}' --status 200 --header K=V --content-type application/json
# 改写请求（continue）
$ chrome-use network route <url> --method POST --set-body '{}' --set-header K=V --rewrite-url <u>
# 编辑真实响应
$ chrome-use network route <url> --edit-status 503 --edit-header K=V --replace 'from=>to'
$ chrome-use network unroute [url]            # 移除路由
$ chrome-use network requests                 # 查看已跟踪的请求
$ chrome-use network requests --filter api    # 过滤请求

按资源类型拦截

network route --resource-type 
# 只阻断脚本（SSR-lock 模式）
$ chrome-use network route '*' --abort --resource-type script
# 用空响应替换图片和字体
$ chrome-use network route '*' --resource-type image,font --body ''

标签页与窗口

标签 id 是形如 t1、t2 的稳定字符串，会话内不重用。 位置整数不被接受 —— tab 2 会报错，请用 t2。 你也可以给标签起可读的 label（docs、app），与 id 通用。

tab / window 
$ chrome-use tab                              # 列出标签（含 tabId 与 label）
$ chrome-use tab new [url]                    # 新标签
$ chrome-use tab new --label docs [url]       # 带可读 label 的新标签
$ chrome-use tab t2                           # 按 id 切换
$ chrome-use tab docs                         # 按 label 切换
$ chrome-use tab close                        # 关闭当前标签
$ chrome-use tab close t2                     # 按 id 关闭
$ chrome-use tab close docs                   # 按 label 关闭
$ chrome-use window new                       # 新窗口
ℹ️ ref 属于快照时的活动标签
守护进程只维护单个活动标签，@eN 归属于快照运行时的那个标签。要操作另一个标签， 先切过去再快照。label 永不自动生成、导航后不改写、会话内唯一。

框架（iframe）

快照时自动检测 iframe，其内容会内联在 iframe 元素下方（一层嵌套）。 iframe 内的 ref 可直接操作；也可切换框架上下文做限定快照。

frame 
$ chrome-use frame "#iframe"     # 按 CSS 选择器切换到 iframe
$ chrome-use frame @e3           # 按元素 ref 切换到 iframe
$ chrome-use frame main          # 返回主框架

frame 接受三种输入：元素 ref（frame @e3）、 CSS 选择器（frame "#payment-iframe"）、以及 框架 name / URL（匹配浏览器的框架树）。

对话框

默认自动接受 alert 与 beforeunload，避免阻塞代理； confirm 和 prompt 仍需显式处理。用 --no-auto-dialog 关闭该行为。

dialog 
$ chrome-use dialog accept [text]  # 接受对话框
$ chrome-use dialog dismiss        # 取消对话框
$ chrome-use dialog status         # 检查是否有对话框打开

执行 JavaScript

eval 在页面 MAIN world 中运行，状态会持久、处理器会触发。 含嵌套引号或特殊字符时，用 -b / --stdin 更可靠 —— Shell 转义很容易出错。

eval 
$ chrome-use eval "document.title"          # 仅限简单表达式
$ chrome-use eval -b "<base64>"             # 任意 JS（base64 编码）
$ chrome-use eval --stdin                   # 从 stdin 读取脚本

# 多行脚本用 stdin + heredoc：
$ cat <<'EOF' | chrome-use eval --stdin
const links = document.querySelectorAll('a');
Array.from(links).map(a => a.href);
EOF

用 eval 调试表单 / 隐藏状态

form debugging 
# 导出每个字段 name → value，含隐藏输入与未选中的 radio
$ chrome-use eval "JSON.stringify([...document.forms[0].elements].map(e=>({name:e.name,type:e.type,value:e.value,checked:e.checked})).filter(e=>e.name))"
# 为什么提交不了？问浏览器自己的 validity API
$ chrome-use eval "[...document.forms[0].elements].filter(e=>!e.validity?.valid).map(e=>e.name+': '+e.validationMessage)"

单次成型脚本（batch / script）

多步流程不必一条命令一次往返。batch 把固定序列一次跑完；script 再加上 步骤间传值、循环、条件、断言。详见 单次成型脚本。

script 
# JSON op-list：值总线 {{name.path}} + waitUntil/forEach/assert/return，--dry-run 可预验
$ chrome-use script prog.json
$ chrome-use script - --dry-run < prog.json

# JS 形式：一段同步 JS，用 cu.* 助手驱动（ego 的 code base 写法）
$ chrome-use script --timeout 120000 <<'JS'
  cu.open('https://news.ycombinator.com');
  const rows = cu.eval("[...document.querySelectorAll('.athing')].length");
  return { count: rows };
JS

选项：--timeout <ms>、--dry-run（仅校验 JSON 程序）、--yes（脚本内自动确认）、 --arg k=v（预置变量）。退出码：0 成功、1 运行失败或断言不过、2 程序非法。

状态管理

state 
$ chrome-use state save auth.json    # 保存 Cookie、存储与鉴权状态
$ chrome-use state load auth.json    # 恢复已保存的状态

Init 脚本

init scripts 
$ chrome-use open --init-script <path>       # 首次导航前注册（可重复）
$ chrome-use addinitscript <js>            # 运行时注册（返回标识符）
$ chrome-use removeinitscript <id>         # 移除已注册的 init 脚本

React / Web Vitals

react ... 命令需要启动时带 --enable react-devtools； vitals 与 pushstate 与框架无关。

react / vitals 
$ chrome-use open --enable react-devtools <url>    # 带 React hook 启动
$ chrome-use react tree                            # 完整组件树
$ chrome-use react inspect <fiberId>               # props / hooks / state / source
$ chrome-use react renders start                   # 开始记录重渲染
$ chrome-use react renders stop [--json]           # 停止并打印渲染分析
$ chrome-use react suspense [--only-dynamic] [--json]  # Suspense 边界 + 分类器
$ chrome-use vitals [url] [--json]                 # LCP/CLS/TTFB/FCP/INP + hydration
$ chrome-use pushstate <url>                       # SPA 客户端导航（自动探测 Next router）

调试

console / errors 的捕获默认关闭 —— 活跃的 CDP Runtime 域是可被探测的 bot 信号。需要时用 AGENT_BROWSER_CAPTURE_CONSOLE=1 启动会话。

debugging 
$ chrome-use --headed open example.com   # 显示浏览器窗口
$ chrome-use --cdp 9222 snapshot         # 通过 CDP 端口连接
$ chrome-use connect 9222                # 另一种：connect 命令
$ chrome-use console                     # 查看控制台消息（需 AGENT_BROWSER_CAPTURE_CONSOLE=1）
$ chrome-use console --limit 20          # 只看最近 20 条控制台消息
$ chrome-use console --clear             # 清空控制台
$ chrome-use errors                      # 查看页面错误（需 AGENT_BROWSER_CAPTURE_CONSOLE=1）
$ chrome-use errors --clear              # 清空错误
$ chrome-use diagnose                    # 页面为何空白：查资源 404/MIME、挂载状态
$ chrome-use highlight @e1               # 高亮元素
$ chrome-use inspect                     # 打开本会话的 DevTools
$ chrome-use trace start                 # 开始记录 trace
$ chrome-use trace stop trace.zip        # 停止并保存
$ chrome-use profiler start              # 开始性能分析
$ chrome-use profiler stop trace.json    # 停止并保存 profile

查找用户保存的页面（find-url）

按关键词搜索本地 Chrome/Edge 书签 —— 用于公共搜索够不到的内部系统或先前保存的页面。 本地读取，无需浏览器 / 守护进程。结果按最近添加排序，跳过 javascript: / data: 书签。

find-url 
$ chrome-use find-url jira board          # 所有关键词都要命中（name 或 url）
$ chrome-use find-url --limit 10 invoices
$ chrome-use find-url --browser edge --profile "Profile 1" wiki
$ chrome-use find-url grafana --json      # {results:[{name,url,folder}], count}

驱动你真实的登录态 Chrome（扩展）

Chrome 136 封锁了默认配置文件上的 --remote-debugging-port，所以要驱动用户现有的登录窗口， chrome-use 走一个 Chrome 扩展 + 原生消息 —— 无端口、无令牌、无每次确认。 一次性安装写入原生消息宿主清单：

extension 
$ chrome-use extension install        # 写入原生消息宿主清单（一次性）
$ chrome-use extension connect        # 自动挂接到真实的登录标签
$ chrome-use tab                      # 列出它现在控制的真实标签
$ chrome-use tab t3                   # 把会话切到其中一个
$ chrome-use snapshot -i              # 像普通会话一样驱动它
$ chrome-use extension status         # 宿主是否已安装？
$ chrome-use extension uninstall      # 移除宿主清单
✅ 推荐从 Chrome 应用商店安装
商店版重启稳定、自动更新（store id knfcmbamhjmaonkfnjhldjedeobeafmk）。加载已解压的开发版可能在 Chrome 重启时被停用 / 丢弃，从而悄悄断掉中继 —— 无人值守场景请用商店版。
ℹ️ 安全
扩展↔宿主链路由 Chrome（扩展 id）认证；宿主↔chrome-use 的 CDP 链路用 0600 文件里的不可猜测 URL。 --extension <path> 无关 —— 那是把扩展加载进一个新启动的浏览器。

全局选项

这些旗标放在命令前，作用于整个会话。注意：无头模式被禁止（bot 信号）， 默认且始终有头（隐身）；无显示服务器上用 AGENT_BROWSER_ALLOW_HEADLESS=1。

global options 
$ chrome-use --session <name> ...    # 隔离的浏览器会话
$ chrome-use --json ...              # JSON 输出，便于解析
$ chrome-use --headed ...            # 默认且始终开启（隐身）
$ chrome-use --full ...              # 整页截图（-f）
$ chrome-use --cdp <port> ...        # 通过 CDP 连接
$ chrome-use -p <provider> ...        # 云浏览器提供商（--provider）
$ chrome-use --proxy <url> ...       # 使用代理服务器
$ chrome-use --proxy-bypass <hosts>   # 绕过代理的主机
$ chrome-use --headers <json> ...    # 限定到 URL 来源的 HTTP 头
$ chrome-use --executable-path <p>   # 自定义浏览器可执行文件
$ chrome-use --extension <path> ...  # 加载扩展（可重复）
$ chrome-use --ignore-https-errors   # 忽略 SSL 证书错误
$ chrome-use --hide-scrollbars false # 无头 Chromium 截图保留原生滚动条
$ chrome-use --help                  # 帮助（-h）
$ chrome-use --version               # 版本（-V）
$ chrome-use <command> --help       # 某个命令的详细帮助

环境变量

environment 
AGENT_BROWSER_SESSION="mysession"            # 默认会话名
AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # 自定义浏览器路径
AGENT_BROWSER_EXTENSIONS="/ext1,/ext2"       # 逗号分隔的扩展路径
AGENT_BROWSER_INIT_SCRIPTS="/a.js,/b.js"     # 逗号分隔的 init 脚本路径
AGENT_BROWSER_ENABLE="react-devtools"        # 逗号分隔的内置 init 特性
AGENT_BROWSER_HIDE_SCROLLBARS="false"        # 保留原生滚动条
AGENT_BROWSER_PROVIDER="browserbase"         # 云浏览器提供商
AGENT_BROWSER_STREAM_PORT="9223"             # 覆盖 WebSocket 流端口
AGENT_BROWSER_HOME="/path/to/chrome-use"     # 自定义安装位置
AGENT_BROWSER_CLICK_MODE="dom"               # 点击策略：""(默认) / "coord" / "dom"

隐身 / 反检测开关（fork）

stealth knobs 
AGENT_BROWSER_CAPTURE_CONSOLE="1"     # 启用 console/errors 捕获（默认关，Runtime 域是 bot 信号）
AGENT_BROWSER_TIMEZONE="Asia/Tokyo"   # 仅 --launch。原生时区覆盖（IANA id 或 "auto"）
AGENT_BROWSER_BLOCK_WEBRTC="1"        # 仅 --launch。经 WebRTC 隐藏本地 IP
AGENT_BROWSER_HIDE_CANVAS="1"         # 仅 --launch。会话稳定的 canvas/audio 指纹噪声
AGENT_BROWSER_ADAPTIVE_REF="0"        # 关闭自适应 @ref 重定位（默认开）
⚠️ console / errors 默认返回空
本隐身 fork 里，二者默认返回 {"messages":[]} / {"errors":[]} 加一条 hint，直到你用 AGENT_BROWSER_CAPTURE_CONSOLE=1 启动会话 —— 这样常见自动化路径下 CDP Runtime 域始终禁用。跑不通时可对照 故障排查。