agent-browser-automate

任务自动化 — 执行协议

内部模板。 入口：agent-browser 技能。

---

切勿

NEVER use `fill` when you want to append — it clears first; use `type` to append
NEVER upload a file with `click` then `fill` — use dedicated `upload <sel> <path>` command
NEVER submit a form without showing field values first — judgment gate required

---

身份验证设置（按优先级选择其一）

# Option 1 (recommended): Auth Vault — encrypted, reusable
agent-browser auth login <vault-name>
agent-browser open <url>

# Option 2: Persistent profile (local only)
agent-browser --profile ~/.myapp open <url>

# Option 3: Token injection
agent-browser open <url>
agent-browser storage local set authToken "<token>"
agent-browser reload

# Option 4: HTTP Basic Auth
agent-browser open <url>
agent-browser set credentials <user> <pass>

# Option 5: Bearer header
agent-browser --headers '{"Authorization":"Bearer <token>"}' open <url>

---

表单自动化流程

agent-browser snapshot -i                                    # get refs
agent-browser find label "Email" fill "[email protected]"
agent-browser find label "Password" fill "<password>"
agent-browser find role button click --name "Submit"
agent-browser wait --load networkidle
agent-browser screenshot --full step-complete.png           # evidence

---

文件操作

# Upload
agent-browser find label "Attachment" upload ./file.pdf

# Download (triggers on button click, waits for completion)
agent-browser find role button click --name "Export CSV"
agent-browser wait --download ~/report.csv

# Generate PDF
agent-browser pdf ./report.pdf

---

多标签页流程

agent-browser tab new
agent-browser open <second-url>
agent-browser tab 0       # switch back to first tab (0-based index)
agent-browser tab list    # see all tabs with URLs

---

剪贴板

# Read clipboard
agent-browser clipboard read

# Write to clipboard
agent-browser clipboard write "text to copy"

# Copy element text to clipboard
agent-browser clipboard copy @e3

# Paste clipboard into element
agent-browser clipboard paste @e5

# macOS: paste system clipboard into focused element
agent-browser keyboard inserttext "$(pbpaste)"

---

精细鼠标控制（画布 / 看板 / 绘图应用）

agent-browser mouse move <x> <y>
agent-browser mouse down
agent-browser mouse move <x2> <y2>   # drag
agent-browser mouse up

---

等待模式

# Page load
agent-browser wait --load networkidle

# Wait for element to appear
agent-browser wait "#success-toast"

# Wait for element to disappear (loading spinner)
agent-browser wait "#spinner" --state hidden

# Wait for URL to change (after form submit / redirect)
agent-browser wait --url "**/dashboard"

# Wait for text to appear
agent-browser wait --text "Upload complete"

# Wait for download to finish
agent-browser wait --download ./report.xlsx

---

恢复模式

故障	恢复方法
身份验证已过期	使用 auth login <name> 重新进行身份验证
Auth Vault 密码已更改	使用 auth delete <name>，然后使用 auth save <name>
出现意外弹窗/对话框	使用 dialog status 确认，然后使用 dialog dismiss
fill 覆盖现有内容	使用 type 追加内容
模态框无法滚动	使用 scroll down --selector ".modal-body"

---

判断关卡

以下情况请暂停：

• 即将提交表单（显示字段值 → 请求确认）
• 即将触发下载 / 删除 / 付款
• 重试后身份验证仍失败（需要新的凭据）

---

易犯错误

错误	修正方法
Auth Vault 密码已更改	再次执行 auth delete + auth save — 不支持原位更新
fill 意外清除内容	使用 type 追加内容
文件上传失败	使用 find label "..." upload <path>，不要先 click 再 fill
无法在模态框内滚动	使用 scroll down --selector ".modal-body"
未捕获下载	点击下载按钮后，使用 wait --download <path>
JS 对话框完全阻塞守护进程	Playwright 在 CDP 层拦截 — eval "window.confirm = () => true" 无效（JS 层覆盖无法触及 CDP）。唯一可靠的修复方法是：在 click 阻塞时，必须通过第二个并发进程调用 dialog accept。
快照中缺少只读 DOM 节点（没有 ARIA 角色的 <p>、<span>、<div>）	snapshot 只呈现无障碍树 — 仅包含可交互元素。使用 eval "document.querySelector('#id').textContent" 或 eval "document.querySelector('.class').innerText" 读取非交互节点内容。