Documenso 中的 agent-browser 命令参考AI Agent 浏览器自动化 CLI 全解析【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso在 Documenso 仓库的.agents/skills/agent-browser/目录下沉淀了一套供 AI Agent 调用的浏览器自动化技能。它的核心是一份命令行工具agent-browser的完整命令参考见 references/commands.md以及一份教 Agent「如何把任务拆成命令序列」的技能说明 SKILL.md。阅读本文后你将掌握如何用snapshotref的快照-交互范式稳定操作网页如何用state save/load复用登录态如何用network、find、eval等命令应对复杂页面以及调试、代理、环境变量等进阶能力——这套范式可直接迁移到 Documenso 的表单填写、登录验证、数据抓取与 E2E 取证等场景。设计定位为什么用「快照 引用」而非选择器在展开具体命令前先理解这套工具的设计取向它决定了后面所有命令的用法。传统的浏览器自动化让 AI 解析完整 DOM 再生成 CSS 选择器一次约消耗 3000~5000 token而agent-browser的snapshot命令会把页面压缩成一棵「可交互元素引用树」为每个元素分配e1、e2这样的短引用直接交互一次约 200~400 token见 references/snapshot-refs.md。由此形成 Documenso 中推荐的四步核心工作流来自 SKILL.md导航agent-browser open url快照agent-browser snapshot -i拿到e1、e2等引用交互用引用来点击、填充、选择重快照在页面跳转或 DOM 变化后重新获取新引用agent-browser open https://example.com/form agent-browser snapshot -i # 输出: e1 [input typeemail], e2 [input typepassword], e3 [button] Submit agent-browser fill e1 userexample.com agent-browser fill e2 password123 agent-browser click e3 agent-browser wait --load networkidle agent-browser snapshot -i # 检查结果关键约束引用ref在页面变化后会失效。凡是有导航跳转、表单提交、动态内容加载下拉、弹窗都必须重新snapshot后再操作。这是理解全部命令的底层前提。导航与页面控制agent-browser open url # 导航到 URL别名: goto, navigate # 支持: https://, http://, file://, about:, data:// # 未给协议时自动补 https:// agent-browser back # 后退 agent-browser forward # 前进 agent-browser reload # 刷新 agent-browser close # 关闭浏览器别名: quit, exit agent-browser connect 9222 # 通过 CDP 端口连接已有浏览器open是几乎所有流程的起点。它支持file://本地文件意味着在 Documenso 这类以 PDF/文档为核心资产的项目里可以直接打开本地生成的 PDF 预览页来验证渲染结果而不必起一个 HTTP 服务。connect 9222与全局选项--cdp port是等价的两种接法用于挂载到一个已用远程调试端口启动的 Chromium 实例上。快照与页面分析快照是引用体系的数据来源提供若干调节参数来平衡信息量与 token 消耗agent-browser snapshot # 完整可访问性树accessibility tree agent-browser snapshot -i # 仅可交互元素推荐 agent-browser snapshot -c # 紧凑输出 agent-browser snapshot -d 3 # 限制树深度为 3 层 agent-browser snapshot -s #main # 限定到某个 CSS 选择器范围对于 Documenso 这种结构复杂侧边栏、命令面板、弹窗、表单嵌套的应用-s #main可以把快照范围锁定到主内容区-d 3可以限制深度避免一次性把整棵 DOM 塞进上下文。快照输出的标准格式如下每一行都携带了标签、关键属性与可见文本Page: Example Site - Home URL: https://example.com e1 [header] e2 [nav] e3 [a] Home e6 [button] Sign In e7 [main] e8 [h1] Welcome e9 [form] e10 [input typeemail] placeholderEmail e11 [input typepassword] placeholderPassword e12 [button typesubmit] Log In引用记法的结构是e1 [标签 关键属性] 可见文本 附加属性。常见模式如e2 [input typeemail]邮箱输入、e5 [select]下拉框、e9 [checkbox] checked已勾选复选框帮助 Agent 在不看原始 HTML 的情况下判断元素类型与状态。交互命令基于 ref拿到引用后全部交互都围绕ref展开。以下命令完整继承自 references/commands.md 的交互段落agent-browser click e1 # 单击 agent-browser dblclick e1 # 双击 agent-browser focus e1 # 聚焦元素 agent-browser fill e2 text # 清空后输入 agent-browser type e2 text # 不清空直接追加输入 agent-browser press Enter # 按键别名: key agent-browser press Controla # 组合键 agent-browser keydown Shift # 按住某键 agent-browser keyup Shift # 释放某键 agent-browser hover e1 # 悬停 agent-browser check e1 # 勾选复选框 agent-browser uncheck e1 # 取消勾选 agent-browser select e1 value # 选择下拉选项 agent-browser select e1 a b # 选择多个选项 agent-browser scroll down 500 # 滚动页面默认 down 300px agent-browser scrollintoview e1 # 滚动使元素进入可视区别名: scrollinto agent-browser drag e1 e2 # 拖拽 agent-browser upload e1 file.pdf # 上传文件几个要点值得强调fill与type的区别fill会先清空再输入适合表单字段type不清空、直接追加适合在已有文本后继续输入的场景。upload对 Documenso 尤其实用文档上传是核心操作agent-browser upload e1 /path/to/file.pdf可以直接驱动文件选择框完成上传配合仓库assets/目录下现成的测试 PDF如 example.pdf可端到端验证上传链路。组合键与拖拽press Controla、drag e1 e2覆盖了全选、拖拽移动字段位置等编辑器常见交互正好对应 Documenso 信封编辑器中拖放字段的交互形态。读取信息与状态检查交互之后需要「读取结果」来验证这一组命令提供元素级与页面级的信息获取agent-browser get text e1 # 获取元素文本 agent-browser get html e1 # 获取 innerHTML agent-browser get value e1 # 获取输入框当前值 agent-browser get attr e1 href # 获取指定属性 agent-browser get title # 获取页面标题 agent-browser get url # 获取当前 URL agent-browser get count .item # 统计匹配元素数量 agent-browser get box e1 # 获取包围盒bounding box agent-browser get styles e1 # 获取计算样式字体、颜色、背景等以及一组断言式状态检查适合写成条件判断agent-browser is visible e1 # 是否可见 agent-browser is enabled e1 # 是否可用 agent-browser is checked e1 # 是否已勾选数据抓取与 JSON 解析是常见诉求推荐把get text重定向到文件或给任意命令加--json输出以便程序化处理agent-browser get text body page.txt # 抓取整页文本 agent-browser snapshot -i --json # 结构化快照 agent-browser get text e1 --json # 结构化文本截图、PDF 与视频录制对 Documenso 这类重视「渲染正确性」的产品截图与 PDF 导出是验证的关键手段agent-browser screenshot # 保存到临时目录 agent-browser screenshot path.png # 保存到指定路径 agent-browser screenshot --full # 整页截图 agent-browser pdf output.pdf # 另存为 PDF仓库里已经用视觉回归的方式沉淀了大量 PDF 字段渲染的基准图见packages/app-tests/visual-regression/目录下的field-meta-pdf-*.png、field-overflow-*.png等screenshot --full与pdf正是生成这类比对素材的能力来源。视频录制用于调试与取证record提供 start / stop / restart 三段控制详见 references/video-recording.mdagent-browser record start ./demo.webm # 开始录制 agent-browser click e1 # 执行操作 agent-browser record stop # 停止并保存 agent-browser record restart ./take2.webm # 停止当前 开始新录制录制产物默认 WebMVP8/VP9适合 CI 里作为 E2E 失败证据留存。等待Wait让异步页面稳定下来动态 SPA 的最大难点是「何时能操作」。wait提供六种等待语义覆盖从元素出现到 JS 条件满足agent-browser wait e1 # 等待某元素出现 agent-browser wait 2000 # 等待毫秒数 agent-browser wait --text Success # 等待文本出现或 -t agent-browser wait --url **/dashboard # 等待 URL 匹配或 -u agent-browser wait --load networkidle # 等待网络空闲或 -l agent-browser wait --fn window.ready # 等待 JS 条件成立或 -f其中--url采用 glob 通配如**/dashboard--load networkidle等待网络静默二者是表单提交后验证结果最常用的组合。在登录流程里wait --url **/dashboard配合get url判断是否落在登录页即可确认鉴权是否成功。鼠标控制与语义定位器低层鼠标控制用于ref难以覆盖的坐标级操作agent-browser mouse move 100 200 # 移动鼠标 agent-browser mouse down left # 按下按钮 agent-browser mouse up left # 释放按钮 agent-browser mouse wheel 100 # 滚轮滚动当引用不可用或不稳定时find系列提供「语义定位器」作为替代直接在命令里表达「按角色/文本/标签/占位符/testid 找到元素并执行动作」agent-browser find role button click --name Submit agent-browser find text Sign In click agent-browser find text Sign In click --exact # 仅精确匹配 agent-browser find label Email fill usertest.com agent-browser find placeholder Search type query agent-browser find alt Logo click agent-browser find title Close click agent-browser find testid submit-btn click agent-browser find first .item click agent-browser find last .item click agent-browser find nth 2 a hoverfind role ... --name、find testid等对 Documenso 这种大量使用可访问性角色与测试 id 的应用尤其友好可以绕开快照引用直接按业务语义定位。浏览器设置、Cookie 与存储一组set命令用于在会话中动态调整浏览器环境详见 references/session-management.md 的会话隔离说明agent-browser set viewport 1920 1080 # 设置视口尺寸 agent-browser set device iPhone 14 # 模拟设备 agent-browser set geo 37.7749 -122.4194 # 设置地理位置别名: geolocation agent-browser set offline on # 切换离线模式 agent-browser set headers {X-Key:v} # 额外 HTTP 头 agent-browser set credentials user pass # HTTP 基础认证别名: auth agent-browser set media dark # 模拟颜色方案 agent-browser set media light reduced-motion # 浅色模式 减少动效其中set media dark可用于验证 Documenso 深色主题下的渲染正确性set credentials则对应 HTTP 基础认证场景。Cookie 与本地存储的读写支撑「手动注入登录态」与「读取前端缓存」两类需求agent-browser cookies # 获取全部 cookie agent-browser cookies set name value # 设置 cookie agent-browser cookies clear # 清空 cookie agent-browser storage local # 读取全部 localStorage agent-browser storage local key # 读取指定 key agent-browser storage local set k v # 设置值 agent-browser storage local clear # 清空在鉴权场景里cookies set session_token abc123xyz可以直接把会话 token 注入后再访问受保护页面免去完整登录流程。网络拦截、Tab/窗口、iframe 与对话框网络层命令用于请求拦截、阻断与 Mock是调试与隔离依赖的利器agent-browser network route url # 拦截请求 agent-browser network route url --abort # 阻断请求 agent-browser network route url --body {} # Mock 响应 agent-browser network unroute [url] # 移除路由 agent-browser network requests # 查看已跟踪的请求 agent-browser network requests --filter api # 过滤请求多标签页、窗口、iframe 与 JS 对话框的控制agent-browser tab # 列出标签页 agent-browser tab new [url] # 新标签页 agent-browser tab 2 # 按索引切换标签页 agent-browser tab close # 关闭当前标签页 agent-browser tab close 2 # 按索引关闭 agent-browser window new # 新窗口 agent-browser frame #iframe # 切换到 iframe agent-browser frame main # 回到主框架 agent-browser dialog accept [text] # 接受对话框 agent-browser dialog dismiss # 取消对话框frame命令对嵌入第三方组件如 iframe 内的支付/表单的页面必不可少dialog处理alert/confirm/prompt这类会阻塞脚本的对话框。JavaScript 执行可靠地跑任意脚本eval支持直接执行页面内 JS但命令参考特别强调嵌套引号与特殊字符的 shell 转义极易出错因此推荐用 base64 或 stdin 传脚本而非内联字符串agent-browser eval document.title # 仅限简单表达式 agent-browser eval -b base64 # 任意 JSbase64 编码 agent-browser eval --stdin # 从 stdin 读脚本可靠执行的两种写法# 把脚本 base64 编码后传入 agent-browser eval -b ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ # 或用 heredoc 走 stdin适合多行脚本 cat EOF | agent-browser eval --stdin const links document.querySelectorAll(a); Array.from(links).map(a a.href); EOF示例中的 base64 解码后是document.querySelectorAll([src*_next])这类选择器查询印证了 Documenso 前端基于 Next.js 体系这一事实——这也说明该技能确实是在本项目真实前端栈下设计与验证的。状态管理与登录态复用state save/load把 cookie、storage 与鉴权态序列化到文件是「登录一次、多次复用」的基石详见 references/authentication.mdagent-browser state save auth.json # 保存 cookie、storage、鉴权态 agent-browser state load auth.json # 恢复已保存状态典型流程是登录页填写凭据 → 提交 →wait --url **/dashboard→state save后续会话state load后直接访问受保护页。安全要点来自参考文档状态文件含会话 token切勿提交入库可加入.gitignoreCI 场景优先用短生命周期会话、结束时close不留存。仓库里还提供了现成的可复用脚本模板可直接参考其结构form-automation.sh演示「快照-交互-验证」表单填写范式authenticated-session.sh登录一次、保存状态、失效自动重登capture-workflow.sh内容抓取 截图其中authenticated-session.sh的实现很能说明范式先检查是否存在状态文件存在则state load后get url判断是否仍停留在登录页命中则复用、否则删除状态文件走全新登录。全局选项、调试与环境变量全局选项决定了会话隔离、输出形态与运行环境是编写脚本时最常被用到的开关agent-browser --session name ... # 隔离的浏览器会话 agent-browser --json ... # JSON 输出便于解析 agent-browser --headed ... # 显示浏览器窗口非 headless agent-browser --full ... # 整页截图-f agent-browser --cdp port ... # 通过 CDP 连接 agent-browser -p provider ... # 云浏览器供应商--provider agent-browser --proxy url ... # 使用代理服务器 agent-browser --headers json ... # 限定到 URL origin 的 HTTP 头 agent-browser --executable-path p # 自定义浏览器可执行文件 agent-browser --extension path ... # 加载浏览器扩展可重复 agent-browser --ignore-https-errors # 忽略 SSL 证书错误 agent-browser --help # 查看帮助-h agent-browser --version # 查看版本-V agent-browser command --help # 查看某条命令的详细帮助--session支持并行多站点会话每个会话拥有独立的 cookie、localStorage/sessionStorage、IndexedDB、缓存、历史与标签页可并发抓取示例见 references/session-management.md。调试类命令组合起一套「可视化 诊断」工具链agent-browser --headed open example.com # 显示浏览器窗口 agent-browser --cdp 9222 snapshot # 通过 CDP 端口连接 agent-browser connect 9222 # 等价: connect 命令 agent-browser console # 查看控制台消息 agent-browser console --clear # 清空控制台 agent-browser errors # 查看页面错误 agent-browser errors --clear # 清空错误 agent-browser highlight e1 # 高亮某元素 agent-browser trace start # 开始录制 trace agent-browser trace stop trace.zip # 停止并保存 traceconsole/errors用于捕获前端报错highlight把引用对应的元素可视化trace则产出可用于性能与行为分析的 trace 包——排查「点击后没反应」这类问题时这三者基本是标配组合。环境变量用于在不改命令行的情况下固化默认值AGENT_BROWSER_SESSIONmysession # 默认会话名 AGENT_BROWSER_EXECUTABLE_PATH/path/chrome # 自定义浏览器路径 AGENT_BROWSER_EXTENSIONS/ext1,/ext2 # 逗号分隔的扩展路径 AGENT_BROWSER_PROVIDERbrowserbase # 云浏览器供应商 AGENT_BROWSER_STREAM_PORT9223 # WebSocket 流端口 AGENT_BROWSER_HOME/path/to/agent-browser # 自定义安装位置把命令串成工作流一个端到端示例下面把上述命令串成一个「登录 保存状态 受保护页验证」的完整流程对应 SKILL.md 中的 Authentication with State Persistence 模式# 首次登录并保存状态 agent-browser open https://app.example.com/login agent-browser wait --load networkidle agent-browser snapshot -i agent-browser fill e1 $USERNAME agent-browser fill e2 $PASSWORD agent-browser click e3 agent-browser wait --url **/dashboard agent-browser state save ./auth-state.json # 后续会话直接复用 agent-browser state load ./auth-state.json agent-browser open https://app.example.com/dashboard agent-browser snapshot -i # 验证已进入受保护页小结agent-browser命令参考的核心价值在于把「AI Agent 操作浏览器」抽象为一套可组合、可脚本化的原子命令——open起步、snapshot -i拿引用、click/fill/select交互、wait稳定、get/is验证、state save/load复用、console/errors/trace诊断。在 Documenso 这类以文档渲染、表单、鉴权与复杂 SPA 交互为核心的项目里这套范式既能支撑日常的表单自动化与数据抓取也能为视觉回归与 E2E 取证提供截图、PDF 与视频证据。配合仓库内现成的模板脚本templates 目录与各 references 文档可以快速把上述命令落地为可重复运行的自动化流程。【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Documenso 中的 agent-browser 命令参考：AI Agent 浏览器自动化 CLI 全解析
Documenso 中的 agent-browser 命令参考AI Agent 浏览器自动化 CLI 全解析【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso在 Documenso 仓库的.agents/skills/agent-browser/目录下沉淀了一套供 AI Agent 调用的浏览器自动化技能。它的核心是一份命令行工具agent-browser的完整命令参考见 references/commands.md以及一份教 Agent「如何把任务拆成命令序列」的技能说明 SKILL.md。阅读本文后你将掌握如何用snapshotref的快照-交互范式稳定操作网页如何用state save/load复用登录态如何用network、find、eval等命令应对复杂页面以及调试、代理、环境变量等进阶能力——这套范式可直接迁移到 Documenso 的表单填写、登录验证、数据抓取与 E2E 取证等场景。设计定位为什么用「快照 引用」而非选择器在展开具体命令前先理解这套工具的设计取向它决定了后面所有命令的用法。传统的浏览器自动化让 AI 解析完整 DOM 再生成 CSS 选择器一次约消耗 3000~5000 token而agent-browser的snapshot命令会把页面压缩成一棵「可交互元素引用树」为每个元素分配e1、e2这样的短引用直接交互一次约 200~400 token见 references/snapshot-refs.md。由此形成 Documenso 中推荐的四步核心工作流来自 SKILL.md导航agent-browser open url快照agent-browser snapshot -i拿到e1、e2等引用交互用引用来点击、填充、选择重快照在页面跳转或 DOM 变化后重新获取新引用agent-browser open https://example.com/form agent-browser snapshot -i # 输出: e1 [input typeemail], e2 [input typepassword], e3 [button] Submit agent-browser fill e1 userexample.com agent-browser fill e2 password123 agent-browser click e3 agent-browser wait --load networkidle agent-browser snapshot -i # 检查结果关键约束引用ref在页面变化后会失效。凡是有导航跳转、表单提交、动态内容加载下拉、弹窗都必须重新snapshot后再操作。这是理解全部命令的底层前提。导航与页面控制agent-browser open url # 导航到 URL别名: goto, navigate # 支持: https://, http://, file://, about:, data:// # 未给协议时自动补 https:// agent-browser back # 后退 agent-browser forward # 前进 agent-browser reload # 刷新 agent-browser close # 关闭浏览器别名: quit, exit agent-browser connect 9222 # 通过 CDP 端口连接已有浏览器open是几乎所有流程的起点。它支持file://本地文件意味着在 Documenso 这类以 PDF/文档为核心资产的项目里可以直接打开本地生成的 PDF 预览页来验证渲染结果而不必起一个 HTTP 服务。connect 9222与全局选项--cdp port是等价的两种接法用于挂载到一个已用远程调试端口启动的 Chromium 实例上。快照与页面分析快照是引用体系的数据来源提供若干调节参数来平衡信息量与 token 消耗agent-browser snapshot # 完整可访问性树accessibility tree agent-browser snapshot -i # 仅可交互元素推荐 agent-browser snapshot -c # 紧凑输出 agent-browser snapshot -d 3 # 限制树深度为 3 层 agent-browser snapshot -s #main # 限定到某个 CSS 选择器范围对于 Documenso 这种结构复杂侧边栏、命令面板、弹窗、表单嵌套的应用-s #main可以把快照范围锁定到主内容区-d 3可以限制深度避免一次性把整棵 DOM 塞进上下文。快照输出的标准格式如下每一行都携带了标签、关键属性与可见文本Page: Example Site - Home URL: https://example.com e1 [header] e2 [nav] e3 [a] Home e6 [button] Sign In e7 [main] e8 [h1] Welcome e9 [form] e10 [input typeemail] placeholderEmail e11 [input typepassword] placeholderPassword e12 [button typesubmit] Log In引用记法的结构是e1 [标签 关键属性] 可见文本 附加属性。常见模式如e2 [input typeemail]邮箱输入、e5 [select]下拉框、e9 [checkbox] checked已勾选复选框帮助 Agent 在不看原始 HTML 的情况下判断元素类型与状态。交互命令基于 ref拿到引用后全部交互都围绕ref展开。以下命令完整继承自 references/commands.md 的交互段落agent-browser click e1 # 单击 agent-browser dblclick e1 # 双击 agent-browser focus e1 # 聚焦元素 agent-browser fill e2 text # 清空后输入 agent-browser type e2 text # 不清空直接追加输入 agent-browser press Enter # 按键别名: key agent-browser press Controla # 组合键 agent-browser keydown Shift # 按住某键 agent-browser keyup Shift # 释放某键 agent-browser hover e1 # 悬停 agent-browser check e1 # 勾选复选框 agent-browser uncheck e1 # 取消勾选 agent-browser select e1 value # 选择下拉选项 agent-browser select e1 a b # 选择多个选项 agent-browser scroll down 500 # 滚动页面默认 down 300px agent-browser scrollintoview e1 # 滚动使元素进入可视区别名: scrollinto agent-browser drag e1 e2 # 拖拽 agent-browser upload e1 file.pdf # 上传文件几个要点值得强调fill与type的区别fill会先清空再输入适合表单字段type不清空、直接追加适合在已有文本后继续输入的场景。upload对 Documenso 尤其实用文档上传是核心操作agent-browser upload e1 /path/to/file.pdf可以直接驱动文件选择框完成上传配合仓库assets/目录下现成的测试 PDF如 example.pdf可端到端验证上传链路。组合键与拖拽press Controla、drag e1 e2覆盖了全选、拖拽移动字段位置等编辑器常见交互正好对应 Documenso 信封编辑器中拖放字段的交互形态。读取信息与状态检查交互之后需要「读取结果」来验证这一组命令提供元素级与页面级的信息获取agent-browser get text e1 # 获取元素文本 agent-browser get html e1 # 获取 innerHTML agent-browser get value e1 # 获取输入框当前值 agent-browser get attr e1 href # 获取指定属性 agent-browser get title # 获取页面标题 agent-browser get url # 获取当前 URL agent-browser get count .item # 统计匹配元素数量 agent-browser get box e1 # 获取包围盒bounding box agent-browser get styles e1 # 获取计算样式字体、颜色、背景等以及一组断言式状态检查适合写成条件判断agent-browser is visible e1 # 是否可见 agent-browser is enabled e1 # 是否可用 agent-browser is checked e1 # 是否已勾选数据抓取与 JSON 解析是常见诉求推荐把get text重定向到文件或给任意命令加--json输出以便程序化处理agent-browser get text body page.txt # 抓取整页文本 agent-browser snapshot -i --json # 结构化快照 agent-browser get text e1 --json # 结构化文本截图、PDF 与视频录制对 Documenso 这类重视「渲染正确性」的产品截图与 PDF 导出是验证的关键手段agent-browser screenshot # 保存到临时目录 agent-browser screenshot path.png # 保存到指定路径 agent-browser screenshot --full # 整页截图 agent-browser pdf output.pdf # 另存为 PDF仓库里已经用视觉回归的方式沉淀了大量 PDF 字段渲染的基准图见packages/app-tests/visual-regression/目录下的field-meta-pdf-*.png、field-overflow-*.png等screenshot --full与pdf正是生成这类比对素材的能力来源。视频录制用于调试与取证record提供 start / stop / restart 三段控制详见 references/video-recording.mdagent-browser record start ./demo.webm # 开始录制 agent-browser click e1 # 执行操作 agent-browser record stop # 停止并保存 agent-browser record restart ./take2.webm # 停止当前 开始新录制录制产物默认 WebMVP8/VP9适合 CI 里作为 E2E 失败证据留存。等待Wait让异步页面稳定下来动态 SPA 的最大难点是「何时能操作」。wait提供六种等待语义覆盖从元素出现到 JS 条件满足agent-browser wait e1 # 等待某元素出现 agent-browser wait 2000 # 等待毫秒数 agent-browser wait --text Success # 等待文本出现或 -t agent-browser wait --url **/dashboard # 等待 URL 匹配或 -u agent-browser wait --load networkidle # 等待网络空闲或 -l agent-browser wait --fn window.ready # 等待 JS 条件成立或 -f其中--url采用 glob 通配如**/dashboard--load networkidle等待网络静默二者是表单提交后验证结果最常用的组合。在登录流程里wait --url **/dashboard配合get url判断是否落在登录页即可确认鉴权是否成功。鼠标控制与语义定位器低层鼠标控制用于ref难以覆盖的坐标级操作agent-browser mouse move 100 200 # 移动鼠标 agent-browser mouse down left # 按下按钮 agent-browser mouse up left # 释放按钮 agent-browser mouse wheel 100 # 滚轮滚动当引用不可用或不稳定时find系列提供「语义定位器」作为替代直接在命令里表达「按角色/文本/标签/占位符/testid 找到元素并执行动作」agent-browser find role button click --name Submit agent-browser find text Sign In click agent-browser find text Sign In click --exact # 仅精确匹配 agent-browser find label Email fill usertest.com agent-browser find placeholder Search type query agent-browser find alt Logo click agent-browser find title Close click agent-browser find testid submit-btn click agent-browser find first .item click agent-browser find last .item click agent-browser find nth 2 a hoverfind role ... --name、find testid等对 Documenso 这种大量使用可访问性角色与测试 id 的应用尤其友好可以绕开快照引用直接按业务语义定位。浏览器设置、Cookie 与存储一组set命令用于在会话中动态调整浏览器环境详见 references/session-management.md 的会话隔离说明agent-browser set viewport 1920 1080 # 设置视口尺寸 agent-browser set device iPhone 14 # 模拟设备 agent-browser set geo 37.7749 -122.4194 # 设置地理位置别名: geolocation agent-browser set offline on # 切换离线模式 agent-browser set headers {X-Key:v} # 额外 HTTP 头 agent-browser set credentials user pass # HTTP 基础认证别名: auth agent-browser set media dark # 模拟颜色方案 agent-browser set media light reduced-motion # 浅色模式 减少动效其中set media dark可用于验证 Documenso 深色主题下的渲染正确性set credentials则对应 HTTP 基础认证场景。Cookie 与本地存储的读写支撑「手动注入登录态」与「读取前端缓存」两类需求agent-browser cookies # 获取全部 cookie agent-browser cookies set name value # 设置 cookie agent-browser cookies clear # 清空 cookie agent-browser storage local # 读取全部 localStorage agent-browser storage local key # 读取指定 key agent-browser storage local set k v # 设置值 agent-browser storage local clear # 清空在鉴权场景里cookies set session_token abc123xyz可以直接把会话 token 注入后再访问受保护页面免去完整登录流程。网络拦截、Tab/窗口、iframe 与对话框网络层命令用于请求拦截、阻断与 Mock是调试与隔离依赖的利器agent-browser network route url # 拦截请求 agent-browser network route url --abort # 阻断请求 agent-browser network route url --body {} # Mock 响应 agent-browser network unroute [url] # 移除路由 agent-browser network requests # 查看已跟踪的请求 agent-browser network requests --filter api # 过滤请求多标签页、窗口、iframe 与 JS 对话框的控制agent-browser tab # 列出标签页 agent-browser tab new [url] # 新标签页 agent-browser tab 2 # 按索引切换标签页 agent-browser tab close # 关闭当前标签页 agent-browser tab close 2 # 按索引关闭 agent-browser window new # 新窗口 agent-browser frame #iframe # 切换到 iframe agent-browser frame main # 回到主框架 agent-browser dialog accept [text] # 接受对话框 agent-browser dialog dismiss # 取消对话框frame命令对嵌入第三方组件如 iframe 内的支付/表单的页面必不可少dialog处理alert/confirm/prompt这类会阻塞脚本的对话框。JavaScript 执行可靠地跑任意脚本eval支持直接执行页面内 JS但命令参考特别强调嵌套引号与特殊字符的 shell 转义极易出错因此推荐用 base64 或 stdin 传脚本而非内联字符串agent-browser eval document.title # 仅限简单表达式 agent-browser eval -b base64 # 任意 JSbase64 编码 agent-browser eval --stdin # 从 stdin 读脚本可靠执行的两种写法# 把脚本 base64 编码后传入 agent-browser eval -b ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ # 或用 heredoc 走 stdin适合多行脚本 cat EOF | agent-browser eval --stdin const links document.querySelectorAll(a); Array.from(links).map(a a.href); EOF示例中的 base64 解码后是document.querySelectorAll([src*_next])这类选择器查询印证了 Documenso 前端基于 Next.js 体系这一事实——这也说明该技能确实是在本项目真实前端栈下设计与验证的。状态管理与登录态复用state save/load把 cookie、storage 与鉴权态序列化到文件是「登录一次、多次复用」的基石详见 references/authentication.mdagent-browser state save auth.json # 保存 cookie、storage、鉴权态 agent-browser state load auth.json # 恢复已保存状态典型流程是登录页填写凭据 → 提交 →wait --url **/dashboard→state save后续会话state load后直接访问受保护页。安全要点来自参考文档状态文件含会话 token切勿提交入库可加入.gitignoreCI 场景优先用短生命周期会话、结束时close不留存。仓库里还提供了现成的可复用脚本模板可直接参考其结构form-automation.sh演示「快照-交互-验证」表单填写范式authenticated-session.sh登录一次、保存状态、失效自动重登capture-workflow.sh内容抓取 截图其中authenticated-session.sh的实现很能说明范式先检查是否存在状态文件存在则state load后get url判断是否仍停留在登录页命中则复用、否则删除状态文件走全新登录。全局选项、调试与环境变量全局选项决定了会话隔离、输出形态与运行环境是编写脚本时最常被用到的开关agent-browser --session name ... # 隔离的浏览器会话 agent-browser --json ... # JSON 输出便于解析 agent-browser --headed ... # 显示浏览器窗口非 headless agent-browser --full ... # 整页截图-f agent-browser --cdp port ... # 通过 CDP 连接 agent-browser -p provider ... # 云浏览器供应商--provider agent-browser --proxy url ... # 使用代理服务器 agent-browser --headers json ... # 限定到 URL origin 的 HTTP 头 agent-browser --executable-path p # 自定义浏览器可执行文件 agent-browser --extension path ... # 加载浏览器扩展可重复 agent-browser --ignore-https-errors # 忽略 SSL 证书错误 agent-browser --help # 查看帮助-h agent-browser --version # 查看版本-V agent-browser command --help # 查看某条命令的详细帮助--session支持并行多站点会话每个会话拥有独立的 cookie、localStorage/sessionStorage、IndexedDB、缓存、历史与标签页可并发抓取示例见 references/session-management.md。调试类命令组合起一套「可视化 诊断」工具链agent-browser --headed open example.com # 显示浏览器窗口 agent-browser --cdp 9222 snapshot # 通过 CDP 端口连接 agent-browser connect 9222 # 等价: connect 命令 agent-browser console # 查看控制台消息 agent-browser console --clear # 清空控制台 agent-browser errors # 查看页面错误 agent-browser errors --clear # 清空错误 agent-browser highlight e1 # 高亮某元素 agent-browser trace start # 开始录制 trace agent-browser trace stop trace.zip # 停止并保存 traceconsole/errors用于捕获前端报错highlight把引用对应的元素可视化trace则产出可用于性能与行为分析的 trace 包——排查「点击后没反应」这类问题时这三者基本是标配组合。环境变量用于在不改命令行的情况下固化默认值AGENT_BROWSER_SESSIONmysession # 默认会话名 AGENT_BROWSER_EXECUTABLE_PATH/path/chrome # 自定义浏览器路径 AGENT_BROWSER_EXTENSIONS/ext1,/ext2 # 逗号分隔的扩展路径 AGENT_BROWSER_PROVIDERbrowserbase # 云浏览器供应商 AGENT_BROWSER_STREAM_PORT9223 # WebSocket 流端口 AGENT_BROWSER_HOME/path/to/agent-browser # 自定义安装位置把命令串成工作流一个端到端示例下面把上述命令串成一个「登录 保存状态 受保护页验证」的完整流程对应 SKILL.md 中的 Authentication with State Persistence 模式# 首次登录并保存状态 agent-browser open https://app.example.com/login agent-browser wait --load networkidle agent-browser snapshot -i agent-browser fill e1 $USERNAME agent-browser fill e2 $PASSWORD agent-browser click e3 agent-browser wait --url **/dashboard agent-browser state save ./auth-state.json # 后续会话直接复用 agent-browser state load ./auth-state.json agent-browser open https://app.example.com/dashboard agent-browser snapshot -i # 验证已进入受保护页小结agent-browser命令参考的核心价值在于把「AI Agent 操作浏览器」抽象为一套可组合、可脚本化的原子命令——open起步、snapshot -i拿引用、click/fill/select交互、wait稳定、get/is验证、state save/load复用、console/errors/trace诊断。在 Documenso 这类以文档渲染、表单、鉴权与复杂 SPA 交互为核心的项目里这套范式既能支撑日常的表单自动化与数据抓取也能为视觉回归与 E2E 取证提供截图、PDF 与视频证据。配合仓库内现成的模板脚本templates 目录与各 references 文档可以快速把上述命令落地为可重复运行的自动化流程。【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
