browser-use

浏览器使用

由 browser-use 库驱动的 AI 浏览器自动化工具，适用于网页交互、研究和数据提取。

适用场景

• 自动执行网页交互（填写表单、点击按钮、浏览页面）
• 跨多个网页来源开展深入研究
• 从网页中提取结构化数据
• 将浏览器工作流学习并重放为可复用技能
• 监控和管理长时间运行的浏览器自动化任务

核心工具

run_browser_agent

使用 AI 执行浏览器自动化任务。支持基于技能的执行、学习模式和后台任务执行。

参数：

• task（string，必需）- 对浏览器操作内容的自然语言描述
• max_steps（integer，可选）- Agent 的最大步数（默认值：来自设置）
• skill_name（string，可选）- 要使用的已学习技能的名称，用于提供提示
• skill_params（string or dict，可选）- 技能参数（JSON 字符串或 dict）
• learn（boolean，可选）- 启用学习模式以发现和提取 API
• save_skill_as（string，可选）- 保存已学习技能时使用的名称（需要 learn=True）

返回： 浏览器自动化任务的结果。在学习模式下，还会包含技能提取状态。

示例：

# Basic usage
Search for "Claude Code plugins" on Google and summarize the top 3 results

# With max steps
Fill out the contact form at https://example.com/contact with my information
max_steps: 20

# Learning mode - discover and save a skill
Go to GitHub trending page and extract the top 5 repositories
learn: true
save_skill_as: github_trending

# Using a learned skill
task: Get trending Python repositories
skill_name: github_trending
skill_params: {"language": "python", "limit": 10}

run_deep_research

使用 AI 引导的搜索和综合分析，对某个主题开展多来源研究。

参数：

• topic（string，必需）- 要调查的研究主题或问题
• max_searches（integer，可选）- 网页搜索的最大次数（默认值：来自设置）
• save_to_file（string，可选）- 用于保存研究报告的可选文件路径

返回： Markdown 格式的综合研究报告

示例：

# Basic research
What are the latest developments in AI-powered browser automation?

# With search limit
Research the security implications of CDP-based browser automation
max_searches: 10

# Save to file
Compare Playwright, Puppeteer, and Selenium for 2025
save_to_file: /path/to/research/browser-automation-comparison.md

技能管理工具

skill_list

列出所有可用的已学习浏览器技能及其使用统计信息。

参数： 无

返回： JSON 格式的技能摘要列表，包含名称、描述、成功率、使用次数和上次使用时间戳

示例：

{
  "skills": [
    {
      "name": "github_trending",
      "description": "Extract trending repositories from GitHub",
      "success_rate": 95.0,
      "usage_count": 20,
      "last_used": "2025-12-20T18:00:00"
    }
  ],
  "skills_directory": "/Users/user/.config/browser-skills"
}

skill_get

获取特定技能的完整详情，包括 API 端点、参数和执行提示。

参数：

• skill_name（string，必需）- 要获取的技能名称

返回： YAML 格式的完整技能定义

示例：

skill_name: github_trending

skill_delete

按名称删除已学习的技能。

参数：

• skill_name（string，必需）- 要删除的技能名称

返回： 成功或错误消息

示例：

skill_name: outdated_skill

任务管理工具

health_check

检查浏览器自动化服务是否正在运行，并获取系统统计信息。

参数： 无

返回： JSON 格式的数据，包含服务健康状态、运行时间、内存使用情况和正在运行的任务

示例响应：

{
  "status": "healthy",
  "uptime_seconds": 3600.5,
  "memory_mb": 256.3,
  "running_tasks": 2,
  "tasks": [
    {
      "task_id": "a1b2c3d4",
      "tool": "run_browser_agent",
      "stage": "navigating",
      "progress": "5/100",
      "message": "Searching Google..."
    }
  ],
  "stats": {
    "total_completed": 45,
    "total_failed": 2,
    "avg_duration_sec": 32.1
  }
}

task_list

列出最近的浏览器自动化和研究任务，并支持筛选。

参数：

• limit（integer，可选）- 要返回的最大任务数（默认值：20）
• status_filter（string，可选）- 按状态筛选："running"、"completed"、"failed"、"pending"

返回： JSON 格式的最近任务列表

示例：

# List recent tasks
limit: 10

# List only running tasks
status_filter: running
limit: 5

# List failed tasks
status_filter: failed

task_get

获取特定任务的详细信息，包括输入、输出和进度。

参数：

• task_id（string，必需）- 任务 ID（完整 UUID 或前缀匹配）

返回： JSON 格式的数据，包含完整任务详情、时间戳以及结果/错误信息

示例：

task_id: a1b2c3d4

task_cancel

取消正在运行的浏览器 Agent 或研究任务。

参数：

• task_id（string，必需）- 任务 ID（完整 UUID 或前缀匹配）

返回： JSON 格式的数据，包含成功状态和消息

示例：

task_id: a1b2c3d4

常见工作流

网页研究工作流

1. 使用 run_deep_research 处理研究问题
2. 查看综合分析后的 Markdown 报告
3. 使用 run_browser_agent 对特定来源开展后续探索
4. 检查 task_list 以监控进度

# Step 1: Deep research
run_deep_research
topic: What are the best practices for MCP server development in 2025?
max_searches: 8

# Step 2: Follow-up investigation
run_browser_agent
task: Go to the top-ranked article and extract code examples

表单自动化工作流

1. 使用 run_browser_agent，并在任务中描述表单
2. 如果知道 URL，请提供；否则让 Agent 搜索
3. Agent 导航到表单、填写字段并提交
4. 使用 task_get 验证是否完成

run_browser_agent
task: Fill out the contact form at https://example.com/contact with name "John Doe", email "[email protected]", and message "Request for demo"
max_steps: 30

学习和重用技能

1. 使用 learn: true 运行 run_browser_agent，以发现 API
2. Agent 记录网络调用并提取模式
3. 使用 save_skill_as 保存技能
4. 使用 skill_list 查看已学习的技能
5. 使用 skill_name 参数重用技能，以加快执行速度

# Step 1: Learn a skill
run_browser_agent
task: Go to Hacker News and extract the top 10 stories with titles, URLs, and scores
learn: true
save_skill_as: hackernews_top_stories

# Step 2: List learned skills
skill_list

# Step 3: Reuse the skill (faster direct execution)
run_browser_agent
task: Get current top stories from Hacker News
skill_name: hackernews_top_stories
skill_params: {"limit": 5}

长时间运行任务管理

1. 启动浏览器自动化任务（在后台运行）
2. 使用 task_list 查看状态
3. 使用 task_get 查看详细进度
4. 如有需要，使用 task_cancel

# Step 1: Start task
run_browser_agent
task: Research all articles on example.com blog and create a summary
max_steps: 200

# Step 2: Check progress
task_list
status_filter: running

# Step 3: Get details
task_get
task_id: a1b2c3d4

# Step 4: Cancel if needed
task_cancel
task_id: a1b2c3d4

高级功能

基于技能的执行

通过 API 端点学习技能后，便可支持直接执行，绕过 AI Agent，从而大幅提升运行速度：

• 首次运行：Agent 探索网站（60-120 秒）
• 学习技能：提取并保存 API 模式
• 后续运行：直接调用 API（2-5 秒）

**回退行为：**如果直接执行失败（需要身份验证、API 已更改），则自动回退到基于 Agent 的执行。

进度跟踪

run_browser_agent 和 run_deep_research 均支持实时进度跟踪：

• 逐步更新导航情况
• 进度百分比（当前步骤 / 总步骤数）
• 当前阶段（初始化、导航、提取、分析）
• 任务消息（当前操作说明）

后台任务支持

MCP 客户端请求时，长时间运行的任务会自动在后台运行：

• 在 SQLite 数据库中跟踪任务
• 服务器重启后仍会保留
• 随时使用 task_list 和 task_get 查询状态
• 使用 task_cancel 取消任务

配置

browser-use MCP 服务可通过 ~/.config/mcp-server-browser-use/config.json 或环境变量进行配置。主要设置：

• browser.headless - 以无头模式运行浏览器（默认值：true）
• browser.cdp_url - 通过 CDP 连接外部 Chrome（可选）
• agent.max_steps - 默认最大步数（默认值：100）
• research.max_searches - 默认研究搜索次数（默认值：5）
• skills.enabled - 启用技能学习和执行（默认值：true）
• skills.directory - 已学习技能的存储位置（默认值：~/.config/browser-skills/）

故障排除

服务无响应

# Check server health
health_check

# Check if server is running
# In terminal: mcp-server-browser-use status

任务卡住或失败

# List running tasks
task_list
status_filter: running

# Get task details
task_get
task_id: <task_id>

# Cancel if stuck
task_cancel
task_id: <task_id>

技能执行失败

# Get skill details to verify parameters
skill_get
skill_name: my_skill

# Try without skill to re-learn
run_browser_agent
task: <original task>
learn: true
save_skill_as: my_skill_v2

最佳实践

1. 先运行 health_check - 执行任务前确认服务已就绪
2. 使用描述清晰的任务名称 - 帮助 AI 清楚理解你的意图
3. 设置合理的 max_steps - 简单任务设为 30-50，复杂研究设为 100-200
4. 经常学习常用工作流 - 通过基于技能的执行节省时间
5. 监控长时间运行的任务 - 使用 task_list 和 task_get 跟踪进度
6. 清理失败的任务 - 使用 task_cancel 释放资源
7. 将研究结果保存到文件 - 使用 save_to_file 保留研究报告

限制

• 浏览器自动化要求 MCP 服务以守护进程方式运行
• 基于 CDP 的浏览器必须运行在 localhost 上（安全限制）
• 某些网站可能会阻止自动化（请遵守 robots.txt 和速率限制）
• 学习技能要求任务成功完成并发现 API
• 取消任务可能需要几秒钟才能正常完成