actionbook

适用场景

在用户遇到以下情况时启用：

• 需要在网站上执行任何操作（“发送一条 LinkedIn 消息”“预订 Airbnb”“在 Google 上搜索……”）
• 询问如何与某个网站交互（“如何发布一条推文？”“如何在 LinkedIn 上申请？”）
• 想要在特定网站上填写表单、点击按钮、导航、搜索、筛选或浏览
• 想要截取网页截图或监控变更
• 构建基于浏览器的 AI Agent、网页抓取工具或针对外部网站的 E2E 测试
• 自动化重复性的网页任务（数据录入、提交表单、发布内容）
• 需要同时操作多个网站或标签页

工作原理

Actionbook 为现代 Web 提供最新的操作手册。操作手册会准确告知 Agent 在页面上要做什么，无需解析，也无需猜测。

这很重要，原因如下：

• 快 10 倍——操作手册会预先提供选择器和页面结构。无需每一步都循环获取快照。
• 准确——可可靠地处理 SPA、流式组件、下拉菜单、日期选择器和动态内容。
• 支持并发——无状态架构，明确指定 --session/--tab。可并行操作数十个标签页。

工作流：

1. 启动浏览器会话
2. 导航到目标页面
3. 获取快照以取得包含元素引用的页面结构
4. 使用快照中的引用进行自动化操作

运行 actionbook <command> --help，查看任意命令的完整用法和示例。

浏览器自动化

每条浏览器命令都是无状态的——请明确传入 --session 和 --tab。没有“当前标签页”这一概念——你可以并行地在任何会话/标签页上运行命令。

启动会话

actionbook browser start --set-session-id s1

--session 和 --set-session-id 都会获取或创建会话：如果给定 ID 对应一个正在运行的会话，就会复用；如果找不到，则会创建一个。如果传入 --profile，但它与会话绑定的配置文件不匹配，命令将失败并返回 SESSION_PROFILE_MISMATCH。

核心工作流：获取快照、操作、等待

actionbook browser goto <url> --session s1 --tab t1
actionbook browser snapshot --session s1 --tab t1          # Get page structure with refs
actionbook browser fill @e3 "text" --session s1 --tab t1   # Use refs from snapshot
actionbook browser click @e7 --session s1 --tab t1
actionbook browser wait navigation --session s1 --tab t1   # Wait for page load

快照引用

snapshot 会为每个元素标注一个引用（例如 @e3、@e7）。在任意命令中都可以将这些引用用作选择器——这是定位元素的推荐方式。

引用在不同快照之间保持稳定——只要元素未发生变化，其引用就会保持不变。这样，你无需每一步之后都重新获取快照，即可连续执行多条命令。

命令类别

所有命令都支持 --help，可查看完整用法和示例。

类别	主要命令	帮助
搜索	search	actionbook search --help
手册	manual（别名：man）	actionbook manual --help
会话	start、close、restart、list-sessions、status	actionbook browser start --help
标签页	new-tab、close-tab、list-tabs	actionbook browser new-tab --help
导航	goto、back、forward、reload	actionbook browser goto --help
观察	snapshot、text、html、value、title、url、viewport、attr、attrs、box、styles、describe、state、inspect-point、screenshot、pdf	actionbook browser snapshot --help
交互	click、fill、type、press、select、hover、focus、scroll、drag、upload、eval、mouse-move、cursor-position	actionbook browser click --help
等待	wait element、wait navigation、wait network-idle、wait condition	actionbook browser wait element --help
Cookie	cookies list、cookies get、cookies set、cookies delete、cookies clear	actionbook browser cookies list --help
存储	local-storage list|get|set|delete|clear、session-storage ...	actionbook browser local-storage get --help
日志	logs console、logs errors	actionbook browser logs console --help
网络	network requests、network request <id>、network har start、network har stop	actionbook browser network requests --help
查询	query one|all|nth|count	actionbook browser query --help
批量	batch-new-tab、batch-snapshot、batch-click	actionbook browser batch-new-tab --help
扩展	extension status、extension ping、extension install、extension uninstall、extension path	actionbook extension status --help
守护进程	daemon restart	actionbook daemon restart --help

完整命令参考：command-reference.md

云服务提供商

使用 -p / --provider 配合 browser start，即可在远程浏览器上运行会话，而非启动本地 Chrome。支持的服务提供商：driver、hyperbrowser、browseruse。每个服务提供商都会从 shell 环境中读取各自的 <PROVIDER>_API_KEY。

export HYPERBROWSER_API_KEY="your-key"
actionbook browser start -p hyperbrowser --session s1
actionbook browser goto "https://example.com" --session s1 --tab t1
actionbook browser snapshot --session s1 --tab t1

无论使用哪种模式，所有浏览器命令的工作方式都相同。browser restart --session <id> 会创建一个新的远程会话，同时保留 session_id。

示例：端到端流程

用户请求：“在 Airbnb 上查找下周位于 SF 的房间”

actionbook browser start --set-session-id s1
actionbook browser goto "https://airbnb.com" --session s1 --tab t1
actionbook browser snapshot --session s1 --tab t1
actionbook browser fill @e3 "San Francisco" --session s1 --tab t1
actionbook browser click @e7 --session s1 --tab t1
actionbook browser wait navigation --session s1 --tab t1

Eval 输入来源

browser eval 接受以下三种互斥来源之一提供的表达式：

• 位置参数：actionbook browser eval "expr" ...
• --file：actionbook browser eval --file script.js ...
• 标准输入：echo 'expr' | actionbook browser eval - ...

Eval 错误处理

browser eval 失败时会返回结构化错误代码；应根据 error.code 进行分支处理，而不是解析错误消息：

• EVAL_RUNTIME_ERROR — JS 异常。重试前检查表达式。
• EVAL_CROSS_ORIGIN — 跨源 fetch 或 CSP 阻止。通过服务端代理请求。
• EVAL_RESPONSE_NOT_JSON / EVAL_RESPONSE_NOT_OK — 读取 error.details.body_head（响应正文的前 ≤256 个字符），以区分 403、挑战页面和 CORS 错误。不要盲目重试。
• EVAL_TIMEOUT — 表达式执行超时，超过了 --timeout。减少工作量或延长超时时间。
• EVAL_ARGS_CONFLICT — 输入来源有多个或没有输入来源。请提供且仅提供一个。
• EVAL_FILE_NOT_FOUND — --file 路径不可读。请检查路径。
• EVAL_STDIN_TTY — 使用了 -，但标准输入是终端。请通过管道传入表达式。
• EVAL_STDIN_EMPTY — 标准输入为空。请检查上游管道。

CDP 错误处理

与元素交互、进行导航或通过 CDP 通信的浏览器命令会返回结构化错误代码——根据 error.code 进行分支处理：

• CDP_NODE_NOT_FOUND — DOM 节点已失效。调用 snapshot 刷新引用，然后重试。
• CDP_NOT_INTERACTABLE — 元素存在，但无法操作。滚动到视图内、等待其可见，或关闭遮挡层。
• CDP_NAV_TIMEOUT — 导航超时。增大 --timeout，或确认 URL 可访问。可重试。
• CDP_TARGET_CLOSED — 标签页在命令执行期间跳转，或会话被中止。启动新会话。可重试。
• CDP_PROTOCOL_ERROR — CDP 响应格式异常。检查 details.reason 和 details.cdp_code。
• CDP_GENERIC — 未分类的 CDP 错误（传输/解析错误）。无特定解决方法。

CDP_NAV_TIMEOUT 和 CDP_TARGET_CLOSED 可重试（error.retryable == true）。所有其他 CDP 代码在重试前都需要调用方介入。若 error.code 是 CDP_* 代码，则 error.details 会在可用时包含 reason 和 cdp_code。

选择器

选择器应来自 actionbook browser snapshot，而不是先前的知识或记忆。始终先运行快照以获取当前引用，然后使用这些引用与页面交互。

登录页面处理

遇到登录/身份验证拦截页面（登录页面、密码提示、多重身份验证/一次性密码、CAPTCHA、账户选择器）时：

1. 暂停自动化并保持当前浏览器会话打开（同一标签页/配置文件/Cookie）。
2. 请用户在同一浏览器窗口中手动完成登录。
3. 用户确认登录完成后，在同一会话中继续操作。
4. 如果登录后的页面不同，请运行 actionbook browser snapshot，在继续操作前获取新页面结构。

不要仅因出现登录页面就切换工具。

会话清理

browser close 是幂等的——关闭未知或已关闭的会话时，会返回 ok: true，并在 meta.warnings 中附带警告，而非致命错误。会话 ID 拼写错误或会话已被中止，不再属于错误情况。

• 清理时可以直接调用 browser close，无需先检查会话是否存在。
• 查看 meta.warnings，区分刚关闭的会话和已不存在的会话。不要将 ok: true 响应中的警告视为会话仍处于活动状态的信号。
• 如果同一会话已有另一个关闭操作正在执行，该命令会返回 SESSION_CLOSING（致命错误）。

HAR 录制

network har start 接受 --max-entries N，用于设置环形缓冲区上限（默认值：10000）。当 har stop 检测到条目丢失（data.dropped > 0）时，响应封装中会包含 meta.truncated = true，并在 meta.warnings 中包含 HAR_TRUNCATED 警告。查看 data.max_entries 可了解已配置的上限。增大 --max-entries 或提前停止录制，以保留完整追踪记录。

参考资料

参考资料	说明
command-reference.md	完整的命令参考，包含所有标志和选项
authentication.md	登录流程、OAuth、双重身份验证处理、会话持久化