browser

name	browser
description	Use when building browser automation scripts that need to control Chrome via the AgentInBrowser REST API. Covers how to start/stop the server, send commands, and handle responses.

AgentInBrowser Skill

Overview

AgentInBrowser 是一个通过 REST API 远程控制 Chrome 浏览器的服务。它封装了 Selenium WebDriver，提供 HTTP 接口来执行浏览器操作（查找元素、点击、输入、截图、执行 JS 等）。

项目位置: D:\Develop\AgentInBrowser

When to Use

• 需要编写浏览器自动化脚本（自动登录、网课观看、表单填写等）
• 需要通过 HTTP 接口控制浏览器而非直接使用 Selenium
• 需要在后台运行浏览器任务且不被检测

Quick Reference

启动服务器

# 在项目目录下
cd D:\Develop\AgentInBrowser
python -m src.server

# 或安装包后使用命令
agent-in-browser

服务器监听地址: http://127.0.0.1:5000

检查服务器状态

import requests
resp = requests.get("http://127.0.0.1:5000/status")
# → {"status": "running", "browser_active": false, "current_url": null}

关闭服务器

requests.post("http://127.0.0.1:5000/shutdown")  # 关闭浏览器 + 退出服务器
requests.post("http://127.0.0.1:5000/quit")      # 仅关闭浏览器，服务器继续运行

API Endpoints

Endpoint	Method	Description
/status	GET	获取服务器状态
/env	GET	获取服务器环境信息（项目目录、venv 路径等）
/init	POST	初始化浏览器并访问 URL
/execute	POST	执行 Selenium 命令
/quit	POST	关闭浏览器（服务器继续）
/shutdown	POST	关闭浏览器并退出服务器

---

Agent 使用流程（重要！）

由于服务器使用 uv 管理依赖，虚拟环境 .venv 在项目目录内。Agent 的 bash 工具运行在局部目录，需要先获取服务器环境信息再激活 venv。

步骤 1: 查询服务器环境

import requests

env = requests.get("http://127.0.0.1:5000/env").json()
print(env)
# → {
#     "project_dir": "D:\\Develop\\AgentInBrowser",
#     "venv_path": "D:\\Develop\\AgentInBrowser\\.venv",
#     "python_executable": "D:\\Develop\\AgentInBrowser\\.venv\\Scripts\\python.exe",
#     "platform": "Windows",
#     "is_windows": true,
#     "activate_cmd": "D:\\Develop\\AgentInBrowser\\.venv\\Scripts\\activate.bat",
#     "activate_ps": "D:\\Develop\\AgentInBrowser\\.venv\\Scripts\\Activate.ps1"
#   }

步骤 2: 激活 venv（每次使用 CLI 前执行）

在 Agent 的 bash 命令中，先激活 venv 再使用 aib-client：

Windows:

# PowerShell
& "D:\Develop\AgentInBrowser\.venv\Scripts\Activate.ps1"
aib-client init https://example.com

# 或 cmd
D:\Develop\AgentInBrowser\.venv\Scripts\activate.bat && aib-client init https://example.com

Linux/macOS:

source /path/to/AgentInBrowser/.venv/bin/activate
aib-client init https://example.com

步骤 3: 使用 CLI 客户端

# 此时 aib-client 已可用
aib-client init https://example.com
aib-client find button
aib-client click 0
aib-client quit

---

Response Format

所有接口返回 JSON，统一格式：

// 成功
{"success": true, "data": {...}}

// 失败
{"success": false, "error": "错误信息"}

Commands via /execute

请求体格式：

{"cmd": "命令名", "params": {"key": "value"}}

元素查找

find — CSS 选择器查找元素

requests.post("http://127.0.0.1:5000/execute", json={
    "cmd": "find",
    "params": {"selector": "button.btn-primary"}
})
# → {"success": true, "data": {
#     "count": 3,
#     "elements": [
#       {"index": 0, "tag": "button", "text": "登录", "class": "btn-primary", "id": ""},
#       ...
//     ]
//   }}

注意: find 的结果会缓存，后续 click/send_keys/get_html 通过索引引用。

inputs — 获取所有 input 元素

requests.post("http://127.0.0.1:5000/execute", json={"cmd": "inputs"})
# → {"success": true, "data": {
#     "count": 2,
#     "inputs": [
//       {"index": 0, "type": "text", "name": "username", "placeholder": "用户名", ...},
//       ...
//     ]
//   }}

buttons — 获取所有 button 元素

requests.post("http://127.0.0.1:5000/execute", json={"cmd": "buttons"})
# → {"success": true, "data": {
#     "count": 1,
#     "buttons": [
//       {"index": 0, "text": "提交", "class": "submit-btn", "id": ""}
//     ]
//   }}

元素交互

click — 点击元素（按 find/inputs/buttons 的索引）

requests.post("http://127.0.0.1:5000/execute", json={
    "cmd": "click",
    "params": {"index": 0}
})
# → {"success": true, "data": {"current_url": "https://..."}}

自动滚动到元素可见区域，常规点击失败时回退到 JS 点击。自带随机延迟模拟人类行为。

send_keys — 向元素输入文本

requests.post("http://127.0.0.1:5000/execute", json={
    "cmd": "send_keys",
    "params": {"index": 0, "text": "hello"}
})
# → {"success": true, "data": {"success": true}}

先 clear() 再输入，自带随机延迟。

页面信息

page_info — 获取当前页面信息

requests.post("http://127.0.0.1:5000/execute", json={"cmd": "page_info"})
# → {"success": true, "data": {"url": "...", "title": "...", "source_length": 12345}}

get_text — 获取页面文本

requests.post("http://127.0.0.1:5000/execute", json={"cmd": "get_text"})
# → {"success": true, "data": {"text": "页面body文本内容（前2000字）"}}

get_html — 获取元素 innerHTML

requests.post("http://127.0.0.1:5000/execute", json={
    "cmd": "get_html",
    "params": {"index": 0}
})
# → {"success": true, "data": {"html": "...(最多5000字符)"}}

工具命令

screenshot — 截图

requests.post("http://127.0.0.1:5000/execute", json={
    "cmd": "screenshot",
    "params": {"filename": "my_screenshot.png"}  # 可选，默认时间戳文件名
})
# → {"success": true, "data": {"filename": "my_screenshot.png"}}

execute_script — 执行 JavaScript

requests.post("http://127.0.0.1:5000/execute", json={
    "cmd": "execute_script",
    "params": {"script": "return document.title"}
})
# → {"success": true, "data": {"result": "页面标题"}}

sleep — 等待（同时保存页面 HTML）

requests.post("http://127.0.0.1:5000/execute", json={
    "cmd": "sleep",
    "params": {"seconds": 5}
})
# → {"success": true, "data": {"slept": 5}}

窗口管理

switch_window — 切换窗口

requests.post("http://127.0.0.1:5000/execute", json={
    "cmd": "switch_window",
    "params": {"index": -1}  # -1 = 最新窗口，0/1/2 = 指定索引
})
# → {"success": true, "data": {"current_url": "...", "title": "...", "window_count": 2}}

close_window — 关闭当前窗口（自动切回主窗口）

requests.post("http://127.0.0.1:5000/execute", json={"cmd": "close_window"})
# → {"success": true, "data": {"current_url": "...", "title": "..."}}

Typical Workflow

1. 初始化浏览器并打开页面

import requests

SERVER = "http://127.0.0.1:5000"

# 初始化浏览器并访问 URL
resp = requests.post(f"{SERVER}/init", json={"url": "https://example.com"})
print(resp.json())

2. 查找并交互

# 查找所有链接
resp = requests.post(f"{SERVER}/execute", json={
    "cmd": "find", "params": {"selector": "a"}
})
elements = resp.json()["data"]["elements"]

# 点击第一个
requests.post(f"{SERVER}/execute", json={
    "cmd": "click", "params": {"index": 0}
})

# 等待页面加载
requests.post(f"{SERVER}/execute", json={
    "cmd": "sleep", "params": {"seconds": 3}
})

3. 填写表单

# 获取输入框
requests.post(f"{SERVER}/execute", json={"cmd": "inputs"})

# 填写
requests.post(f"{SERVER}/execute", json={
    "cmd": "send_keys", "params": {"index": 0, "text": "username"}
})
requests.post(f"{SERVER}/execute", json={
    "cmd": "send_keys", "params": {"index": 1, "text": "password"}
})

# 获取按钮并点击
requests.post(f"{SERVER}/execute", json={"cmd": "buttons"})
requests.post(f"{SERVER}/execute", json={
    "cmd": "click", "params": {"index": 0}
})

4. 处理新窗口（如弹窗登录）

# 切换到最新窗口
requests.post(f"{SERVER}/execute", json={
    "cmd": "switch_window", "params": {"index": -1}
})

# 在新窗口中操作...

# 关闭新窗口，回到主窗口
requests.post(f"{SERVER}/execute", json={"cmd": "close_window"})

5. 清理

# 关闭浏览器，服务器继续运行
requests.post(f"{SERVER}/quit")

# 或完全关闭
requests.post(f"{SERVER}/shutdown")

Important Notes

1. 元素索引是临时的 — 每次 find/inputs/buttons 都会重置内部缓存，后续 click/send_keys/get_html 引用的是最近一次查找的结果
2. 服务器必须先启动 — 客户端脚本应先检查 /status 确认服务器运行中
3. 浏览器反检测已内置 — 服务器自动注入反后台暂停脚本和反自动化检测，客户端无需处理
4. 自带随机延迟 — click 和 send_keys 内含随机延迟模拟人类行为
5. 日志自动记录 — 所有操作记录到运行目录下的 server_log.txt
6. 点击自动降级 — 常规点击失败时自动回退到 JavaScript 点击