Agent-Browser 自动化操作教程

本教程将指导你如何使用 Agent-Browser 进行网页自动化操作，包括环境配置、浏览器启动和 AI 助手配置。

1. 获取本地配置

首先查看现有的 Chrome profiles，了解可用的浏览器配置。

1.1 列出所有 Profile

使用以下命令只列出 profile 目录：

ls -d "$HOME/Library/Application Support/Google/Chrome"/{Default,Profile*,"Guest Profile","System Profile"} 2>/dev/null | xargs -I {} basename {}

输出示例：

Default
Profile 1
Profile 2
Profile 3
Guest Profile
System Profile

常见的 profiles 包括：

Default - 默认配置
Profile 1, Profile 2, Profile 3 - 其他用户配置
Guest Profile - 访客配置
System Profile - 系统配置

1.2 获取 Profile 详细信息

使用 plutil 命令读取每个 profile 的配置信息：

获取单个 Profile 的名称：

plutil -extract profile.name raw "$HOME/Library/Application Support/Google/Chrome/Default/Preferences" 2>/dev/null || echo "Default Profile"

获取关联邮箱：

plutil -extract account_info.0.email raw "$HOME/Library/Application Support/Google/Chrome/Default/Preferences" 2>/dev/null

批量获取所有 Profile 信息：

for profile in "Default" "Profile 1" "Profile 2" "Profile 3"; do
  echo "=== $profile ==="
  echo "名称: $(plutil -extract profile.name raw "$HOME/Library/Application Support/Google/Chrome/$profile/Preferences" 2>/dev/null || echo "未设置")"
  echo "邮箱: $(plutil -extract account_info.0.email raw "$HOME/Library/Application Support/Google/Chrome/$profile/Preferences" 2>/dev/null || echo "未登录")"
  echo ""
done

输出示例：

=== Default ===
名称: 用户1
邮箱: z****@gmail.com

=== Profile 1 ===
名称: 用户2
邮箱: s****@gmail.com

=== Profile 2 ===
名称: 用户2
邮箱: z****@gmail.com

=== Profile 3 ===
名称: 用户2
邮箱: s****@tcc.edu.kg

根据输出信息，选择需要复制的 profile。

2. 复制配置

根据第一步获取的 profile 信息，选择需要复制的 profile。

2.1 复制 Profile 到项目目录

复制 Default profile：

cp -R "$HOME/Library/Application Support/Google/Chrome/Default" "$HOME/code/agent-browser/chrome/Agent"

复制其他 profile（例如 Profile 1）：

cp -R "$HOME/Library/Application Support/Google/Chrome/Profile 1" "$HOME/code/agent-browser/chrome/Agent"

这将创建一个独立的 profile 目录，包含所有浏览器数据：

账户信息
书签
历史记录
Cookies
扩展程序
本地存储

2.2 验证复制是否成功

检查目录是否创建成功：

ls -la "$HOME/code/agent-browser/chrome/Agent"

检查 Preferences 文件是否存在：

plutil -extract profile.name raw "$HOME/code/agent-browser/chrome/Agent/Preferences" 2>/dev/null

2.3 设置权限（如需要）

如果遇到权限问题，确保对目标目录有读写权限：

chmod -R 755 "$HOME/code/agent-browser/chrome/Agent"

3. 用 Debug 模式启动浏览器

3.1 关闭已运行的 Chrome（重要！）

在启动新的 Chrome 实例之前，必须先关闭所有正在运行的 Chrome 进程：

pkill -9 -f "Google Chrome"

注意： 此步骤非常重要，否则会导致端口冲突或 profile 锁定问题。

3.2 启动 Chrome（使用 Agent Profile）

使用以下命令启动 Chrome，开启 CDP 调试端口：

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/code/agent-browser/chrome" \
  --profile-directory="Agent"

参数说明：

参数	说明
`--remote-debugging-port=9222`	开启 CDP 调试端口，默认 9222
`--user-data-dir=...`	指定用户数据目录路径
`--profile-directory="Agent"`	指定使用的 profile 目录

3.3 验证是否成功

检查 CDP 服务是否正常启动：

curl -s http://127.0.0.1:9222/json/version

预期输出：

{
  "Browser": "Chrome/xxx.x.xxxx.xxx",
  "Protocol-Version": "1.3",
  "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/xxx.x.xxxx.xxx Safari/537.36",
  "V8-Version": "xxx.x.xxxx",
  "WebKit-Version": "xxx.x",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/xxx"
}

如果看到类似的 JSON 输出，说明 CDP 服务已成功启动。

3.4 常见问题

端口已被占用：

如果遇到端口占用错误，可以更换端口号：

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9223 \
  --user-data-dir="~/code/agent-browser/chrome" \
  --profile-directory="Agent"

Profile 锁定：

如果 Chrome 提示 profile 已被锁定，确保已执行步骤 3.1 关闭所有 Chrome 进程。

4. 配置 AI 助手

为了让 AI 助手（如 Trae IDE 的 AI）能够使用 Agent-Browser 进行自动化操作，需要配置项目规则文件。

4.1 编辑项目规则文件

编辑 $HOME/code/agent-browser/.trae/rules/project_rules.md 文件，添加以下内容：

## 浏览器自动化

使用 `agent-browser` 进行网页自动化。运行 `agent-browser --help` 查看所有命令。

核心工作流程：
1. `agent-browser connect 9222` - 连接到浏览器
2. `agent-browser open <url>` - 导航到页面
3. `agent-browser snapshot -i` - 获取交互元素及其引用（@e1, @e2）
4. `agent-browser click @e1` / `fill @e2 "text"` - 使用引用进行交互
5. 页面变化后重新获取快照

4.2 配置说明

这个配置文件告诉 AI 助手：

使用 agent-browser 进行网页自动化。运行 agent-browser --help 查看所有命令。

核心工作流程：

agent-browser connect 9222 - 连接到浏览器
agent-browser open <url> - 导航到页面
agent-browser snapshot -i - 获取交互元素及其引用（@e1, @e2）
agent-browser click @e1 / fill @e2 "text" - 使用引用进行交互
页面变化后重新获取快照

4.3 验证配置

确保配置文件已正确保存：

# trae 规则文件
cat $HOME/code/agent-browser/.trae/rules/project_rules.md

# AGENT.md 文件
cat $HOME/code/agent-browser/AGENT.md

5. 使用 Agent-Browser 进行自动化

5.1 查看帮助信息

首先查看 Agent-Browser 的所有可用命令：

agent-browser --help

5.2 核心工作流程示例

步骤 1：连接到浏览器

agent-browser connect 9222

步骤 2：导航到目标页面

agent-browser open https://www.google.com

步骤 3：获取页面快照和交互元素

agent-browser snapshot -i

这将返回页面的所有可交互元素，并分配引用（如 @e1, @e2, @e3...）

步骤 4：使用引用进行交互

点击元素：

agent-browser click @e1

填充输入框：

agent-browser fill @e2 "搜索内容"

步骤 5：页面变化后重新获取快照

agent-browser snapshot -i

5.3 完整示例：Google 搜索

# 1. 连接到浏览器
agent-browser connect 9222

# 2. 打开 Google
agent-browser open https://www.google.com

# 3. 获取页面元素
agent-browser snapshot -i

# 4. 填充搜索框（假设搜索框是 @e1）
agent-browser fill @e1 "Agent-Browser 教程"

# 5. 点击搜索按钮（假设按钮是 @e2）
agent-browser click @e2

# 6. 等待页面加载后重新获取快照
agent-browser snapshot -i

5.4 CDP 接口直接使用

除了使用 Agent-Browser 命令行工具，也可以直接使用 CDP 接口：

获取所有标签页：

curl -s http://127.0.0.1:9222/json/list

创建新标签页：

curl -s http://127.0.0.1:9222/json/new?https://www.google.com

关闭标签页：

curl -s http://127.0.0.1:9222/json/close/<tab-id>

附录

A. 自动化脚本

创建一个查询脚本 list_chrome_profiles.sh：

#!/bin/bash

echo "=========================================="
echo "   Chrome Profile 信息查询"
echo "=========================================="
echo ""

CHROME_DIR="$HOME/Library/Application Support/Google/Chrome"

# 自动检测所有存在的 profile 目录
PROFILES=$(ls -d "$CHROME_DIR"/{Default,Profile*,"Guest Profile","System Profile"} 2>/dev/null | xargs -I {} basename {} | sort)

for profile in $PROFILES; do
  PREFS_FILE="$CHROME_DIR/$profile/Preferences"
  
  if [ -f "$PREFS_FILE" ]; then
    echo "=== $profile ==="
    
    # 获取 Profile 名称
    NAME=$(plutil -extract profile.name raw "$PREFS_FILE" 2>/dev/null || echo "未设置")
    echo "名称: $NAME"
    
    # 获取关联邮箱
    EMAIL=$(plutil -extract account_info.0.email raw "$PREFS_FILE" 2>/dev/null || echo "未登录")
    echo "邮箱: $EMAIL"
    
    # 获取路径
    echo "路径: $CHROME_DIR/$profile"
    echo ""
  fi
done

echo "=========================================="

C. 注意事项

每次使用前务必关闭现有 Chrome 进程，避免端口冲突
CDP 端口（9222）不应暴露在公网，存在安全风险
复制的 profile 包含敏感信息（Cookies、密码等），请妥善保管
建议为不同的自动化任务使用独立的 profile 目录
确保 AI 助手能够访问 .trae/rules/project_rules.md 文件