browserwing-admin

BrowserWing 管理技能

概述

BrowserWing 是一个智能浏览器自动化平台，可用于：

• 录制、创建和回放浏览器自动化脚本
• 使用 AI 自主探索网站并生成可回放脚本
• 通过 HTTP API 或 MCP 协议执行脚本
• 管理 AI 功能所用的大模型配置

API 基础 URL： http://localhost:8080/api/v1

身份验证： 使用 X-BrowserWing-Key: <api-key> 标头或 Authorization: Bearer <token>

---

1. 安装 Google Chrome（前置条件）

BrowserWing 需要在主机上安装 Google Chrome。

Linux（Debian/Ubuntu）

wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt-get update
sudo apt-get install -y google-chrome-stable

macOS

brew install --cask google-chrome

Windows

从此处下载并安装：https://www.google.com/chrome/

验证安装

google-chrome --version
# or on macOS:
# /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

使用远程 Chrome（替代方案）

如果 Chrome 在已启用调试功能的远程机器上运行：

google-chrome --remote-debugging-port=9222 --remote-debugging-address=0.0.0.0 --no-sandbox

然后配置 BrowserWing 的 config.toml：

[browser]
control_url = 'http://<remote-host>:9222'

---

2. 大模型配置

AI 功能（AI Explorer、Agent 聊天、智能提取）需要大模型配置。

列出大模型配置

curl -X GET 'http://localhost:8080/api/v1/llm-configs'

添加大模型配置

curl -X POST 'http://localhost:8080/api/v1/llm-configs' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-openai",
    "provider": "openai",
    "api_key": "sk-xxx",
    "model": "gpt-4o",
    "base_url": "https://api.openai.com/v1",
    "is_active": true,
    "is_default": true
  }'

支持的提供商： openai、anthropic、deepseek，或任何兼容 OpenAI 的端点。

测试大模型配置

curl -X POST 'http://localhost:8080/api/v1/llm-configs/test' \
  -H 'Content-Type: application/json' \
  -d '{"name": "my-openai"}'

更新大模型配置

curl -X PUT 'http://localhost:8080/api/v1/llm-configs/<config-id>' \
  -H 'Content-Type: application/json' \
  -d '{"api_key": "sk-new-key", "model": "gpt-4o-mini"}'

删除大模型配置

curl -X DELETE 'http://localhost:8080/api/v1/llm-configs/<config-id>'

---

3. AI 自主探索（自动生成脚本）

使用 AI 浏览网站、执行任务并自动生成可回放脚本。

开始探索

curl -X POST 'http://localhost:8080/api/v1/ai-explore/start' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_desc": "Go to bilibili.com, search for 'AI', and get the first page of video results",
    "start_url": "https://www.bilibili.com",
    "llm_config_id": "my-openai"
  }'

响应： 返回用于跟踪的会话 id。

流式传输探索事件（SSE）

curl -N 'http://localhost:8080/api/v1/ai-explore/<session-id>/stream'

返回实时服务器发送事件：thinking、tool_call、progress、error、script_ready、done。

停止探索

curl -X POST 'http://localhost:8080/api/v1/ai-explore/<session-id>/stop'

获取生成的脚本

curl -X GET 'http://localhost:8080/api/v1/ai-explore/<session-id>/script'

保存生成的脚本

curl -X POST 'http://localhost:8080/api/v1/ai-explore/<session-id>/save'

将生成的脚本保存到本地脚本库，以便日后回放。

---

4. 脚本管理

列出所有脚本

curl -X GET 'http://localhost:8080/api/v1/scripts'

返回所有本地脚本及其 id、name、description、actions、tags、group 等信息。

获取脚本详情

curl -X GET 'http://localhost:8080/api/v1/scripts/<script-id>'

获取脚本架构／摘要

curl -X GET 'http://localhost:8080/api/v1/scripts/summary'

返回所有脚本的简明摘要，包括名称、描述、输入参数（变量）和操作数量。适用于以编程方式发现脚本。

创建新脚本

curl -X POST 'http://localhost:8080/api/v1/scripts' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Search Bilibili",
    "description": "Search for a keyword on Bilibili",
    "url": "https://www.bilibili.com",
    "actions": [
      {"type": "navigate", "url": "https://www.bilibili.com"},
      {"type": "click", "identifier": ".nav-search-input"},
      {"type": "type", "identifier": ".nav-search-input", "value": "${keyword}"},
      {"type": "press_key", "key": "Enter"},
      {"type": "wait", "timeout": 3}
    ]
  }'

变量： 在操作值中使用 ${variable_name} 语法。执行脚本时，这些变量会成为输入参数。

更新脚本

curl -X PUT 'http://localhost:8080/api/v1/scripts/<script-id>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Updated Name", "description": "Updated description"}'

删除脚本

curl -X DELETE 'http://localhost:8080/api/v1/scripts/<script-id>'

将脚本导出为技能（转换为 SKILL.md）

将一个或多个脚本转换为 SKILL.md 文件，以便导入 AI Agent（例如 Claude、Cursor）。这样，其他 AI Agent 便可发现并执行你的 BrowserWing 脚本。

导出选定脚本

curl -X POST 'http://localhost:8080/api/v1/scripts/export/skill' \
  -H 'Content-Type: application/json' \
  -d '{
    "script_ids": ["script-id-1", "script-id-2", "script-id-3"]
  }'

将多个脚本合并为一个 SKILL.md，包含所有脚本的操作、变量和描述。

导出所有脚本

curl -X POST 'http://localhost:8080/api/v1/scripts/export/skill' \
  -H 'Content-Type: application/json' \
  -d '{"script_ids": []}'

传入空的 script_ids 数组，即可将所有脚本导出到一个 SKILL.md 中。

导出执行器技能（浏览器控制 API）

curl -X GET 'http://localhost:8080/api/v1/executor/export/skill'

将底层浏览器自动化 API 导出为技能，使 AI Agent 能够直接控制浏览器（导航、点击、输入、提取等）。

工作流：脚本 → 技能 → AI Agent

1. Create scripts (manually, by recording, or via AI exploration)
2. Export them as SKILL.md: POST /scripts/export/skill
3. Place the SKILL.md in your AI agent's skill directory
4. The AI agent can now discover and call your scripts via POST /scripts/<id>/play

---

5. 执行脚本

按 ID 运行脚本

curl -X POST 'http://localhost:8080/api/v1/scripts/<script-id>/play' \
  -H 'Content-Type: application/json' \
  -d '{
    "variables": {
      "keyword": "deepseek"
    }
  }'

变量： 为脚本操作中定义的 ${variable_name} 占位符传入值。

获取播放结果（提取的数据）

curl -X GET 'http://localhost:8080/api/v1/scripts/play/result'

返回上次脚本执行期间提取的数据（例如，从 execute_js 操作中抓取的内容）。

列出脚本执行历史

curl -X GET 'http://localhost:8080/api/v1/script-executions?page=1&page_size=20'

---

6. 脚本市场（远程脚本）

注意：远程脚本市场功能正在开发中。以下 API 可能尚不可用。

浏览市场

# TODO: curl -X GET 'http://localhost:8080/api/v1/marketplace/scripts?category=search&page=1'

从市场安装脚本

# TODO: curl -X POST 'http://localhost:8080/api/v1/marketplace/scripts/<remote-id>/install'

---

7. MCP（模型上下文协议）集成

BrowserWing 提供兼容 MCP 的端点，用于集成 AI Agent。

MCP SSE 端点

SSE:     http://localhost:8080/api/v1/mcp/sse
Message: http://localhost:8080/api/v1/mcp/sse_message

检查 MCP 状态

curl -X GET 'http://localhost:8080/api/v1/mcp/status'

列出 MCP 命令

curl -X GET 'http://localhost:8080/api/v1/mcp/commands'

显示所有已注册的 MCP 工具（浏览器工具 + 基于脚本的自定义命令）。

---

8. 提示词管理

系统提示词控制 AI 的行为。用户可以自定义这些提示词。

列出所有提示词

curl -X GET 'http://localhost:8080/api/v1/prompts'

获取特定提示词

curl -X GET 'http://localhost:8080/api/v1/prompts/<prompt-id>'

系统提示词 ID： system-extractor、system-formfiller、system-aiagent、system-get-mcp-info、system-ai-explorer

更新提示词

curl -X PUT 'http://localhost:8080/api/v1/prompts/<prompt-id>' \
  -H 'Content-Type: application/json' \
  -d '{"content": "Your custom prompt content here..."}'

---

9. 浏览器实例管理

列出浏览器实例

curl -X GET 'http://localhost:8080/api/v1/browser/instances'

启动浏览器实例

curl -X POST 'http://localhost:8080/api/v1/browser/instances/<id>/start'

停止浏览器实例

curl -X POST 'http://localhost:8080/api/v1/browser/instances/<id>/stop'

---

10. Cookie 管理

管理浏览器 Cookie — 查看已保存的 Cookie、导入 Cookie（例如，用于已认证的会话）以及删除 Cookie。

查看已保存的 Cookie

curl -X GET 'http://localhost:8080/api/v1/cookies/browser'

返回保存在 browser 存储 ID（默认存储）下的所有 Cookie。如有需要，可将 browser 替换为自定义存储 ID。

保存当前浏览器 Cookie

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/save'

将当前浏览器会话中的所有 Cookie 保存到数据库。需要浏览器正在运行。

导入 Cookie

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/import' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "cookies": [
      {
        "name": "session_id",
        "value": "abc123",
        "domain": ".example.com",
        "path": "/",
        "secure": true,
        "httpOnly": true,
        "sameSite": "Lax",
        "expires": 1735689600
      }
    ]
  }'

字段：name 和 value 为必填项。domain、path、secure、httpOnly、sameSite、expires 为可选项（path 默认为 /）。

删除单个 Cookie

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/delete' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "browser",
    "name": "session_id",
    "domain": ".example.com",
    "path": "/"
  }'

从指定的 Cookie 存储中删除由 name + domain + path 标识的特定 Cookie。

批量删除 Cookie

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/batch/delete' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "browser",
    "cookies": [
      {"name": "session_id", "domain": ".example.com", "path": "/"},
      {"name": "tracking", "domain": ".example.com", "path": "/"}
    ]
  }'

一次删除多个 Cookie。每个 Cookie 由 name + domain + path 标识。

---

11. 故障排除

出现问题时，请按照以下步骤诊断。

检查服务运行状况

curl -X GET 'http://localhost:8080/health'

查看日志

BrowserWing 日志存储在 config.toml 中 [log] file 配置的路径下。 默认位置：./log/browserwing.log

# View last 100 lines of logs
tail -n 100 ./log/browserwing.log

# Follow logs in real-time
tail -f ./log/browserwing.log

# Search for errors
grep -i 'error\|fail\|panic' ./log/browserwing.log | tail -20

常见问题

1. 浏览器无法启动

• 检查是否已安装 Google Chrome：google-chrome --version
• 在 Linux 上，确保使用 --no-sandbox 标志或以非 root 用户运行
• 检查用户数据目录中是否残留 Chrome 锁文件（SingletonLock、lockfile）
• 如果使用远程 Chrome，请检查 config.toml 中的 control_url
• 尝试终止现有 Chrome 进程：pkill -f chrome

2. AI 功能无法使用

• 确保已配置并启用大模型配置：GET /api/v1/llm-configs
• 测试大模型连接：POST /api/v1/llm-configs/test
• 检查 API 密钥是否有效，以及模型是否可用
• 检查日志中是否有与大模型相关的错误

3. 脚本执行失败

• 确认脚本存在：GET /api/v1/scripts/<id>
• 检查浏览器是否正在运行：GET /api/v1/browser/instances
• 查看执行历史：GET /api/v1/script-executions
• 确保在播放请求中提供所有必需的 ${variables}
• 目标网站可能已更改 — 尝试重新录制或更新脚本

4. 未找到页面元素

• 使用 GET /api/v1/executor/snapshot 查看当前页面元素
• 元素可能使用动态选择器 — 优先使用快照中的 RefID
• 页面可能尚未加载完成 — 使用等待操作

5. 端口冲突

• BrowserWing 默认端口：8080（可在 config.toml 的 [server] port 中配置）
• Chrome 调试端口：9222（或 control_url 中配置的端口）
• 检查端口占用情况：lsof -i :<port> 或 netstat -tlnp | grep <port>

---

快速入门工作流

以下是启动并运行的步骤：

1. Install Chrome (see Section 1)
2. Start BrowserWing: ./browserwing --port 8080
3. Add an LLM config (see Section 2)
4. Choose your approach:
   a) AI Exploration: POST /ai-explore/start with a task description
   b) Manual Creation: POST /scripts with actions array
   c) Web UI: Open http://<host>:8080 in browser to use the visual editor
5. Execute scripts: POST /scripts/<id>/play
6. View results: GET /scripts/play/result

API 快速参考

类别	方法	端点	描述
健康状态	GET	/health	检查服务状态
LLM	GET	/api/v1/llm-configs	列出 LLM 配置
LLM	POST	/api/v1/llm-configs	添加 LLM 配置
LLM	POST	/api/v1/llm-configs/test	测试 LLM 连接
探索	POST	/api/v1/ai-explore/start	开始 AI 探索
探索	GET	/api/v1/ai-explore/:id/stream	流式传输探索事件
探索	POST	/api/v1/ai-explore/:id/stop	停止探索
探索	POST	/api/v1/ai-explore/:id/save	保存生成的脚本
脚本	GET	/api/v1/scripts	列出所有脚本
脚本	GET	/api/v1/scripts/:id	获取脚本详情
脚本	POST	/api/v1/scripts	创建新脚本
脚本	PUT	/api/v1/scripts/:id	更新脚本
脚本	DELETE	/api/v1/scripts/:id	删除脚本
脚本	GET	/api/v1/scripts/summary	获取脚本架构/摘要
脚本	POST	/api/v1/scripts/export/skill	将脚本导出为 SKILL.md
执行	POST	/api/v1/scripts/:id/play	执行脚本
执行	GET	/api/v1/scripts/play/result	获取执行结果数据
执行	GET	/api/v1/script-executions	列出执行历史
提示词	GET	/api/v1/prompts	列出所有提示词
提示词	PUT	/api/v1/prompts/:id	更新提示词
浏览器	GET	/api/v1/browser/instances	列出浏览器实例
Cookie	GET	/api/v1/cookies/:id	查看已保存的 Cookie
Cookie	POST	/api/v1/browser/cookies/save	保存当前浏览器的 Cookie
Cookie	POST	/api/v1/browser/cookies/import	导入 Cookie
Cookie	POST	/api/v1/browser/cookies/delete	删除单个 Cookie
Cookie	POST	/api/v1/browser/cookies/batch/delete	批量删除 Cookie
MCP	GET	/api/v1/mcp/status	MCP 服务状态
MCP	GET	/api/v1/mcp/commands	列出 MCP 命令
执行器	GET	/api/v1/executor/help	执行器 API 帮助
执行器	GET	/api/v1/executor/snapshot	页面可访问性快照
技能	GET	/api/v1/executor/export/skill	导出执行器技能
技能	GET	/api/v1/admin/export/skill	导出此管理技能