导航与定位
先找到，再动手。找不到就报错，不猜。
- 打开、后退、前进、刷新。地址规整；非 URL 文本走当前搜索引擎。
- XPath 或 CSS 选择器。点击、输入、选择必须恰好匹配一个；匹配多个直接失败，不取第一条。
- 穿透 Shadow DOM 与 iframe。pierce 查同源 iframe；顶层找不到时自动查跨域 iframe（OOPIF）。
- 画布与坐标点选。没有稳定节点时用视口坐标或截图坐标；page_hit 反查命中的元素。
Skip to content
v0.13.13标签栏分割线统一；上一版修复渲染进程崩溃后的页面恢复
MCP · 67 TOOLS · 0.13.13
让 Agent 用你登录好的浏览器，把网页上的事做完。浏览器里的事，交给 Agent。
一套环境一套登录。Agent 在同一扇窗口里点击、填表、等待、提取结果；你随时可以接管。 Windows / macOS / Linux，全部在本机。
一个真实任务：在 GitHub 的 browser-automation 话题页取前 5 个仓库，导出 CSV。 画面从工作流画布开始，经过填写参数、「Agent 正在操作浏览器」的遮罩与页面加载，到运行记录里的条数与文件路径。
35 秒 · 无声循环 · 实录01 输入在「GitHub 话题速览」里填 browser-automation，点执行。
02 窗口里的动作工作流在窗口里打开话题页、等仓库卡片出现、取前 5 条；遮罩上可随时接管。
03 结果运行记录写明 5 条与 CSV 路径，文件写到 exports 目录。
- 67MCP 工具tool-catalog.ts 的实际工具数
- 22工作流节点开始/结束/判断/循环都算在内
- 200运行记录上限界面列表最多显示 50 条
- 3并发与无头窗口默认各 3，设置里可调
01怎么工作
给目标，执行，看结果或接管
它不是录屏回放，也不是把每一步都交回给模型重新想。做通一次之后，步骤可以存成工作流， 下一次只调用一次 workflow_run。
01把目标交给 Agent 或工作流
在 Claude Code、Kimi Code、Cursor 里说一句要做什么；Agent 通过本机 MCP 调 BrowserPilot 的工具。做通一次后，也可以存成工作流，填参数直接执行。
02它在同一扇窗口里执行
打开页面、定位元素、等待渲染、点击与填写。Agent 操作时盖遮罩，点「接管」立刻交还。
03你看结果，或把它存成工作流
每次运行留下成功/失败、停在哪一步、输出与文件。做通一次的步骤可以写成工作流，之后一次调用跑完。
02能力清单
能做什么，逐条标证据
每条都对应一个 MCP 工具或一个已实现的界面行为。已支持 = 当前版本可用；实验性 = 有实现但依赖外部条件； 未支持 = 不承诺，建议交接给人。
表单与上传
把人的输入动作拆成可重放的步骤。
- 逐键输入与快捷键。默认走 CDP 可信输入；非拉丁字符用 Input.insertText。
- 选择、粘贴、上传文件。上传直接交给文件控件，不弹系统选择框。
- 精确拖拽。拖滑块或排序；轨迹带加减速、抖动与微过冲。
多标签与环境
登录留在环境里，不留在对话里。
- 一套环境一扇窗口。一套环境里多个网站共享登录；不同环境互不可见。
- 关窗不清登录。登录态在 Electron 的 persist 分区；只有删环境才清 Cookie。
- 标签全局唯一。开、关、切换、分组；Agent 用 tabId 指定，关掉的编号不复用。
- 无头只是窗口不显示。仍是同一个 Chromium，不是另一套 headless 内核；默认最多 3 扇。
等待与重试
不写死 sleep，让页面自己说什么时候好了。
- 等元素出现或消失。默认 10 秒，最长 60 秒；穿透模式同样可用。
- 点到目标出现为止。点击后等下一个目标，最多 3 次；滚动/滑动到目标最多 16/20 次。
- 盯住变化。元素文字或位置变了就返回前后快照，最长 120 秒。
- 失败留现场。工具失败自动附一张截图；工作流失败记录节点、错误、截图，有抓包时附 HAR。
结果提取
先把页面读成数据，再谈自动化。
- 无障碍树与批量查询。快照只对这一次有效；按同一定位取全部匹配与位置。
- 读 DOM 或原始响应。dom 是当前文档，response 是这次导航的 HTML。
- 页面脚本与跨域 iframe。返回 JSON；frame 填子框架 URL 的一段即可在跨域 iframe 里跑。
- 工作流直接写 CSV。extract + export，带 BOM，Excel 打开不乱码。
下载与媒体
网页触发的下载也接管。
- 下载管理器。进度、暂停/继续、重试、复制链接；所有网页下载进同一列表。
- 图片、音频、视频。直链直接下；B站/抖音/YouTube 抓 DASH 轨合并 mp4；m3u8 交 ffmpeg。
- 实时录页面视频。captureStream + MediaRecorder，任何能播的站都能录；代价是要实时播完。
- 标签级抓包。HTTP 记录、按 URL 过滤、导出 HAR；请求头可能含 Cookie，只留本机。
网络与调试
出问题时有现场，不靠猜。
- 抓包与 HAR。每个标签单独记录；正文与 Cookie 不离开本机。
- 请求拦截。按 URL 包含规则返回假数据，做接口测试和故障注入。
- 单条或批量 CDP。同一调试会话里按顺序发命令，可指定子框架会话。
验证码
只把能稳定做的写成熟支持。
- 极验 v4 滑块。cv → ddddocr → onnx 三引擎降级；拟人拖拽，失败换图重试。
- 其它类型交给看图 Agent。截图带回坐标映射，自己算点击位置；成功率取决于模型与题型。
- 英数文字验证码。ddddocr，需要本机 Python 与 pip install ddddocr。
- 图标点选、五子棋、交换消除。没有内置识别器，不承诺自动完成；建议 page_handoff 交给人。
·三种用法
同一套工具，三种用法
Agent 直连适合一次性任务；保存工作流适合重复操作；人机协作适合登录、核验和需要人把关的步骤。
在 Claude Code、Kimi Code、Cursor 里说一句，Agent 通过 MCP 逐步调用工具：快照、定位、点击、等待、提取。适合一次性任务和还没形成固定流程的事。
- 67 个工具导航、点击、表单、截图、抓包、媒体、验证码都在同一套工具里
- 失败留现场工具失败自动附 errorShot，Agent 下一轮能看着截图改定位
- 不写死 sleeppage_wait 等元素出现或消失，1–60 秒
- 随时接管页面遮罩上的「接管」一按，控制权回到人
03人在环上
它会停下来，你也能随时打断
终端和浏览器自动化最容易让人不放心的是控制权。下面写的是代码里的实际行为，不是承诺。
| 控制状态 | 页面上的表现 | 谁在操作 |
|---|---|---|
| agent | 盖一层「Agent 正在操作浏览器」，中央是「接管」。 | Agent；你点「接管」立刻交还。 |
| handoff | 遮罩去掉，页面顶部留一句提示；下一步目标出现时重新上锁。 | 人；工作流交接最多等 10 分钟（下一个节点有定位时）。 |
| shared | 没有遮罩。 | 人和 Agent 同时操作；任务不暂停。 |
逐次工具调用不会写单独的审计日志。要给业务方交代，用工作流的运行记录（成功/失败、节点、输出、文件、现场截图） 和抓包 HAR；这两样是按运行留的，不是按每一次点击留的。
接管不暂停
人点「接管」或 Agent 调 page_unlock 后，控制权变成 shared，任务继续。 工作流返回 takenOver: true，Agent 应该重新读页面再决定下一步。
需要人做一步时
用 page_handoff 或工作流「交接」节点。窗口如果是无头的，会先显示出来； 交接节点会等下一个目标出现，最长 10 分钟；下一个节点没有定位时会立即重新上锁。
凭据留在本机
登录态在 Electron 的 persist 分区；MCP 只监听 127.0.0.1，Bearer 令牌写在本机 mcp.json。应用不把 Cookie 发给云端。
导出的 Cookie 是明文
env_export 是给换机用的，文件里是完整 Cookie。只在本机传递，不要贴到对话、 仓库或工单里；不用时删掉。
04边界
我们做什么，不做什么
主动写清楚不做的部分，比说「什么都能做」更有用。下面每一条都能在代码或发布配置里找到对应。
做
- 本机桌面运行。一套环境一扇窗口，登录留在分区里，关窗不丢。
- 同窗口人机协作。遮罩、接管、交接，三种控制状态。
- 把步骤存成工作流。22 种节点，一次
workflow_run跑完整图。 - 极验 v4 滑块自动。cv / ddddocr / onnx 三引擎降级，失败换图重试。
- 本机 MCP 与 CLI。MCP 是主入口；CLI 目前按 Windows 路径读端点。
不做
- 不做指纹引擎。只去掉自己会加的自动化标记，不承诺绕过站点风控。
- 不做云端执行或账号托管。MCP 只听 127.0.0.1，任务数据不上传。
- 不做通用验证码识别。图标点选、五子棋、交换消除没有内置识别器。
- 不做内置定时器。要用定时，自己写系统计划任务调 CLI。
- 不做网卡级抓包。只有标签级 HTTP 记录。
- 不代管密码。登录由人在环境窗口里完成。
- 不做代码签名。安装包未签名，SmartScreen 与 macOS 拦截按文档处理。
05集成
Agent 走 MCP，人走界面
MCP 是主入口：Agent 通过它调用 67 个工具。CLI 是同一套工具的薄封装，适合脚本与计划任务。 应用内没有定时器。
MCP 客户端配置
streamable HTTP{
"mcpServers": {
"browserpilot": {
"type": "http",
"url": "http://127.0.0.1:39221/mcp",
"headers": { "Authorization": "Bearer REPLACE_WITH_TOKEN" }
}
}
} 先打开 BrowserPilot → 设置 → 通用 → MCP。REPLACE_WITH_TOKEN 换成 %APPDATA%\BrowserPilot\mcp.json 里的 token；不要贴到对话或仓库。
CLI
Windows"%LOCALAPPDATA%\Programs\BrowserPilot\resources\cli\browserpilot.exe" tools
"%LOCALAPPDATA%\Programs\BrowserPilot\resources\cli\browserpilot.exe" schema page_click
"%LOCALAPPDATA%\Programs\BrowserPilot\resources\cli\browserpilot.exe" call workflow_run --name "GitHub 话题速览" --json-file C:\tasks\github.json github.json 里写 {"话题":"browser-automation"}。CLI 目前只按 Windows 的 %APPDATA% 路径读 mcp.json；macOS / Linux 用 MCP。
批量输入
workflow_batch{
"workflow": "GitHub 话题速览",
"rows": [
{ "话题": "browser-automation" },
{ "话题": "headless-browser" }
],
"concurrency": 2
}并发上限 3。每行仍是一次完整的工作流运行，各自有运行记录；默认一行一行来。
系统计划任务
不是内置功能set BROWSERPILOT_EXE=%LOCALAPPDATA%\Programs\BrowserPilot\BrowserPilot.exe
"%LOCALAPPDATA%\Programs\BrowserPilot\resources\cli\browserpilot.exe" ^
call workflow_run --name "GitHub 话题速览" --json-file C:\tasks\github.json 存成 browserpilot-morning.bat，再用 schtasks /Create /SC DAILY /ST 09:00 /TN "BrowserPilot 早报" /TR "C:\tasks\browserpilot-morning.bat"。 CLI 会先等应用起来，最多 45 秒。
06对照
手写脚本、RPA、BrowserPilot
三者解决的不是同一类问题。下面只写客观差异，不排名。
窄屏可以左右滑动，查看完整对照。
| 维度 | 手写 Playwright / Puppeteer | 传统 RPA | BrowserPilot |
|---|---|---|---|
| 起步 | 写代码、装浏览器、处理驱动与启动参数。 | 装 RPA 软件，录制或拖流程；桌面版通常按席位收费。 | 装桌面应用，把本机 MCP 注册给 Agent；不需要写脚本也能先跑。 |
| 登录态 | 自己维护 storageState / Cookie，过期就重新登录。 | 常依赖桌面会话或内置浏览器，账号切换靠配置。 | 登录留在环境的 persist 分区；一套环境多个网站，关窗不丢。 |
| 网站改版 | 选择器失效，改代码、跑测试、发版。 | 元素路径失效，回编辑器改流程。 | 同样会失效；失败带匹配数、文字和现场截图，定位更快，但没有自动修复。 |
| 重复运行 | 脚本进 CI 或计划任务；需要自己写重试与报告。 | 自带计划任务与日志，适合固定流程。 | workflow_run 一次跑完整图；workflow_batch 多行输入，最多 3 并发。 |
| 谁决定下一步 | 你写的代码。 | 录好的流程。 | Agent 规划；做通后存成工作流回放。BrowserPilot 自身不带模型。 |
| 适合 | 工程团队、CI、需要版本化与代码评审的场景。 | 固定的内部系统、财务/人事等表单流程。 | 本机、已登录、需要人随时接管的网页任务；不适合无桌面的服务器。 |
07技术规格
给要评估接入的人
版本、驱动、定位方式、并发、凭据与数据落盘位置。数字来自仓库与当前安装包，不写估测。
| 版本 | 0.13.13（2026-10-09 tag） |
|---|---|
| 运行时 | Electron 44 · React 19 · TypeScript 5；Windows 安装包 117.6 MiB，解压后约 460 MB |
| 驱动方式 | Electron WebContentsView + Chrome DevTools Protocol（Input / DOM / Accessibility / Network） |
| 定位 | XPath 或 CSS；必须恰好匹配一个；可穿透 Shadow DOM、同源 iframe，顶层找不到时查跨域 iframe |
| 运行模式 | 有头优先；无头 = 窗口隐藏（同一 Chromium），默认上限 3 扇，可在设置里调 |
| 并发 | workflow_batch 最多 3 路（设置上限）；不同环境各自一扇窗口 |
| 凭据 | 登录态在 Electron 的 persist 分区；MCP 只监听 127.0.0.1，Bearer 令牌在本机 mcp.json |
| 平台 | Windows x64 · macOS（Apple Silicon）· Linux x64；CI 三端构建，当前素材在 Windows 采集 |
| 网络 | 应用无账号体系；市场目录从 GitHub 读取；媒体合并首次会从镜像下载 ffmpeg |
| 许可 | 仓库暂未附 LICENSE 文件；源码公开可读，再分发前请先确认授权 |
| 数据目录 | Windows %APPDATA%BrowserPilot；macOS ~/Library/Application Support/BrowserPilot；Linux ~/.config/BrowserPilot |
08界面
真实界面，不是重绘
下面五张都来自 0.13.13 的 Windows 运行，统一窗口 1440 × 900。没有 mockup。
任务与参数
保存好的工作流带参数；填完点执行，或交给 Agent 调 workflow_run。
Agent 操作中
页面盖遮罩，中央是「接管」；人点一下就能拿回控制权。
运行记录
成功/失败、停在哪一步、输出、文件；失败自动附现场截图。
工作流画布
22 种节点从左向右连；Agent 不点图，仍用 workflow_run 一次跑完。
设置 · 通用
MCP 只听 127.0.0.1，默认端口 39221；批量并发与无头窗口上限也在这里。
09源码与构建
自己构建，自己核对
主进程、界面、Go CLI 与工作流市场都在公开仓库里。三条命令起本地开发环境。
三条命令
$ git clone https://github.com/xy200303/browserpilot
$ npm install
$ npm run dev 构建：npm run build；类型检查：npm run typecheck； 打包：npm run dist:win（或 dist:mac / dist:linux）。
许可证与边界
- 仓库：xy200303/browserpilot
- 工作流市场：xy200303/browserpilot-market，应用只下载，不回传。
- 主进程、React 界面、Go CLI 同仓；没有服务端。
- Windows 安装包未做代码签名。
截至 v0.13.13，仓库没有 LICENSE 文件。源码公开可读，但在作者给出书面许可前， 不要把它当作 MIT / Apache 等开源许可再分发。许可证以仓库实际文件为准。
10更新日志
最近三个版本
只写仓库查得到的提交。这个项目的小版本很密，下面三条都是 2026-10-09 的。
v0.13.132026-10-09
- 标签栏统一显示分割线，最后一个标签不挂尾线。
- 纯界面调整，工具与工作流行为不变。
v0.13.122026-10-09
- 渲染进程崩溃后，检测 webContents.isDestroyed() 并自动重建视图，恢复页面。
- 修复的是崩溃后后续操作全灭的问题；提交记录里 BOSS 循环投递实测 13/13 成功。
v0.13.112026-10-09
- 标签间加分割线：激活标签及其相邻自动隐藏，Chrome 风格。
- 只改标签栏呈现，不影响标签编号与操作。
完整历史见 GitHub Releases。
11常见问题
常见问题
会不会误点付款按钮？
默认没有逐次点击确认——Agent 调 page_click 就会点。需要人把关的步骤，用 page_handoff 或工作流里的「交接」节点：遮罩去掉、页面留提示，人做完下一步才重新上锁。付款、删除、发布这类页面建议放在交接之后，只让 Agent 做只读操作。
登录态怎么保持？换机器怎么办？
一套环境就是一个 Electron persist 分区。登录一次，关掉窗口再打开还在；不同环境互不可见。删环境会清掉 Cookie。换机器用 env_export / env_import 导出导入 Cookie；导出文件是明文，只在本机用，不要发到对话或仓库里。
网站改版了怎么办？
选择器会失效，BrowserPilot 不会自动修复。失败时会带匹配个数、文字和现场截图；用 page_query 或 page_snapshot 重新找定位，再改工作流节点。运行记录里能看到停在哪一步。
能不能跑在服务器上？
不能。它是桌面应用，需要图形会话；所谓无头只是把窗口隐藏，仍是同一个 Chromium。MCP 只监听 127.0.0.1，不对外网开放。需要远程执行时，用远程桌面连到那台机器。
数据和截图存在哪？
都在本机用户数据目录：Windows 是 %APPDATA%BrowserPilot，macOS 是 ~/Library/Application Support/BrowserPilot，Linux 是 ~/.config/BrowserPilot。截图在 screenshots，运行记录在 runs.json，抓包 HAR 在 runs，导出 CSV 在 exports，下载在 downloads。应用没有账号与云端同步。
支持哪些验证码？
自动支持的是极验 v4 滑块：cv、ddddocr、onnx 三引擎降级，拟人拖拽并重试。其它类型用 captcha_panel 截图交给会看图的 Agent，成功率取决于题型和模型；英数文字可以用 ddddocr，需要本机 Python。图标点选、五子棋、交换消除没有内置识别器，建议交接给人。
多个账号能同时跑吗？
能。每个账号一套环境，各自一扇窗口、各自的登录。批量运行 workflow_batch 默认一行一行来，并发最多 3；同时开着的无头窗口默认也最多 3，可在设置里调。
会被网站识别成机器人吗？
BrowserPilot 去掉了自己会加的自动化标记：不带 --enable-automation，UA 用同版本 Chrome 标识、不出现 Electron 或 HeadlessChrome，默认输入走 CDP 的 Input 域。它不是指纹浏览器，不做指纹伪装，也不承诺绕过站点风控；判定在网站一侧。