候鸟浏览器控制端对接
MBAgent 之所以能"真的操作候鸟浏览器"，靠的是一套名为 候鸟客户端 ControlV2 的通信协议。本篇详细介绍 MBAgent 如何与候鸟浏览器建立连接，以及常见问题排查。
NOTE
截图说明：MBAgent 与候鸟浏览器同时运行时的"双控制端"截图（候鸟浏览器主窗口 + MBAgent 主窗口并排显示）将在 v1.x 版本陆续补充。本节先用文字描述两者的协作关系。
一、什么是候鸟浏览器控制端？
候鸟浏览器控制端（Houniao Client ControlV2）是候鸟浏览器对外提供的一套双向通信协议，让其他程序（包括 MBAgent）可以：
- 🔍 发现本地运行的候鸟实例
- 🤝 与候鸟实例握手
- 🔑 通过候鸟账号登录
- 📦 加载候鸟配置（环境、代理、指纹）
- 🚀 启动 / 停止候鸟环境
- 🌐 操作候鸟环境里的网页
NOTE
类比：可以把 ControlV2 理解为候鸟浏览器的"遥控器协议"。MBAgent 是个遥控器，候鸟浏览器是电视机。
二、MBAgent 与候鸟的三种连接模式
1. MBAgent 控制端（推荐）
MBAgent 启动时自动在本地启动一个候鸟控制端服务，候鸟浏览器作为客户端连接过来。
适用场景：
- 单一候鸟实例
- 大多数个人用户
- 候鸟 + MBAgent 同机运行
2. ApiServer 控制端
通过候鸟浏览器内置的 ApiServer 接口（http://127.0.0.1:8186）连接。
适用场景：
- 远程控制候鸟
- 候鸟浏览器在另一台机器
- 自动化脚本（Selenium / Puppeteer / Playwright）
3. 同一实例
MBAgent 和候鸟浏览器在同一个客户端实例里，直接内部通信。
适用场景：
- 开发调试
- 性能敏感场景
三、首次连接候鸟浏览器
前置条件
✅ 候鸟浏览器已启动并登录账号 ✅ MBAgent 已安装 ✅ MBAgent 启动时选择的工作目录有权限
自动连接流程
MBAgent 启动时会自动执行以下流程：
[1] 启动本地 ControlV2 服务
↓
[2] 扫描本地候鸟实例
- 通过 UDP 广播 / 本地端口扫描
- 找到候鸟浏览器的 ControlV2 端口
↓
[3] 握手
- 交换协议版本号
- 协商加密方式
↓
[4] 账号登录
- MBAgent 用候鸟账号登录 ControlV2
- 自动读取 Token
↓
[5] 配置加载
- 加载候鸟账号下的所有环境
- 加载候鸟账号下的代理配置
↓
[6] 能力检测
- 测试启动 / 停止环境
- 测试网页接管
- 测试文件操作
↓
[7] 连接成功 ✅查看连接状态
- 进入 "设置 → 官方服务检测"
- 点击 "候鸟客户端 ControlV2" 选项
- 点击 "开始检测"
- 几秒后显示：
- ✅ 正常：所有检查通过
- ⚠️ 异常：具体哪一步失败
- ⚪ 未启用：未开启 ControlV2
- ⏳ 检测中：正在检测
四、检测结果解读
✅ 正常
显示：
候鸟客户端 ControlV2 可正常使用
实时就绪往返检测已验证连接、登录、配置及可执行能力。表示 MBAgent 可以正常操作候鸟浏览器。
⚠️ 异常：连接失败
可能原因：
- 候鸟浏览器未启动
- ControlV2 端口被占用
- 防火墙拦截
排查：
- 确认候鸟浏览器已启动
- 检查候鸟浏览器 → 设置 → ControlV2 是否开启
- 关闭防火墙 / 杀毒软件再试
⚠️ 异常：账号未登录
可能原因：
- 候鸟账号 Token 过期
- MBAgent 没读取到 Token
排查：
- 在候鸟浏览器里重新登录账号
- 重启 MBAgent
⚠️ 异常：配置加载失败
可能原因：
- 候鸟账号下没有创建环境
- 候鸟数据库连接失败
排查：
- 在候鸟浏览器里创建一个环境
- 重启 MBAgent
⚠️ 异常：可执行能力未通过
可能原因：
- 候鸟浏览器版本与 MBAgent 不兼容
- 系统权限不足
排查：
- 确认候鸟浏览器是最新版
- 用管理员权限启动 MBAgent
- 联系候鸟客服
五、切换候鸟控制实例
如果您本地有多个候鸟浏览器实例（开发场景），可以切换：
第一步：查看所有候鸟实例
- 进入 "设置 → 候鸟客户端 ControlV2"
- 点击 "候鸟实例" 选项
- 显示当前发现的候鸟实例列表：
候鸟实例 #1 (默认)
- 端口: 8186
- 版本: v3.0.0
- 状态: 已连接
候鸟实例 #2 (开发)
- 端口: 8286
- 版本: v3.0.0
- 状态: 未连接第二步：切换
- 选中目标候鸟实例
- 点击 "切换" 按钮
- MBAgent 会断开当前实例、连接新实例
- 注意：切换会停止当前所有候鸟操作
TIP
日常使用：99% 的用户只需要一个候鸟实例，不需要切换。
六、AI 操作候鸟浏览器的过程
当 MBAgent 接收到"操作候鸟"的指令时，会自动执行以下流程：
[1] AI 解析任务
"打开 223223 这个店铺，检查今日订单"
↓
[2] 调用 ControlV2 接口
- control.browser.start({ environment_id: "223223" })
↓
[3] 候鸟浏览器启动环境
- 创建 / 复用 223223 环境
- 应用指纹 / 代理 / Cookie
- 返回 browser_handle
↓
[4] MBAgent 通过 CDP 接管页面
- attach({ handle })
- 接收页面截图、DOM 结构
↓
[5] AI 分析页面 + 决策下一步
"看到了订单页面，下一步提取数字"
↓
[6] 执行动作
- click / type / extract
↓
[7] 完成任务，关闭环境（或保持打开）
↓
[8] 整理结果给用户
"今日订单 23 单，金额 $1234.56"关键概念
- handle（句柄）：候鸟浏览器给 MBAgent 返回的"环境句柄"，用来引用一个具体的环境
- attach（附着）：MBAgent 接管一个候鸟环境的页面
- CDP：Chrome DevTools Protocol，候鸟浏览器底层用的协议
七、常见问题
Q1：MBAgent 启动后显示"等待候鸟 CDP"
原因：候鸟浏览器没有启动，或者环境未启动。
解决：
- 确认候鸟浏览器已启动并登录
- 在候鸟浏览器里手动启动一个环境
- MBAgent 自动会接管
Q2：AI 操作候鸟环境总是失败
可能原因：
- ControlV2 异常（看官方服务检测）
- 候鸟账号额度用完
- 候鸟环境已损坏
排查：
- 在 设置 → 官方服务检测 看 ControlV2 是否正常
- 检查候鸟账号 AI 额度
- 在候鸟浏览器里手动测试该环境
Q3：接管候鸟页面后画面是黑的
可能原因：
- 候鸟浏览器刚启动，环境还没就绪
- 候鸟账号需要二次验证
解决：
- 等待 5-10 秒再试
- 在候鸟浏览器里手动完成验证
Q4：能否让 MBAgent 控制远程的候鸟浏览器？
❌ 不可以。MBAgent 的候鸟客户端 ControlV2 连接在实现层硬性限定为 127.0.0.1（ControlClientError::NonLoopbackEndpoint），不接受任何非 loopback 的 IP 地址。即便把候鸟浏览器的 ControlV2 端口对外暴露（例如 0.0.0.0:8186），MBAgent 也会在握手阶段直接拒绝连接。
正确的远程候鸟控制方式：
- 使用 Selenium / Puppeteer / Playwright 等脚本，通过候鸟浏览器内置的 ApiServer（
http://127.0.0.1:8186）远程调用——详见上文"二、MBAgent 与候鸟的三种连接模式 → 2. ApiServer 控制端" - 这类场景下，MBAgent 不参与，仅作为普通的 HTTP 客户端调用候鸟 ApiServer 接口
NOTE
为什么限定 loopback：
- ControlV2 协议本身没有强身份校验，TCP 端口暴露在公网等于"候鸟账号控制权交给任何人"
- MBAgent 与候鸟浏览器假设运行在同一台机器、同一个账号上下文下，loopback 是最低风险的边界
Q5：MBAgent 不操作候鸟浏览器也能用吗？
✅ 完全可以。MBAgent 的核心功能（聊天、文档、代码、知识库）不依赖候鸟浏览器。只有当您明确要求操作候鸟账号环境时，才会建立 ControlV2 连接。
八、最佳实践
启动顺序
推荐启动顺序：
- 候鸟浏览器（先启动并登录）
- MBAgent（后启动，自动连接）
不要反过来。
长时间不用时
如果您长时间不用候鸟浏览器操作：
- 关闭 MBAgent 里的"候鸟 RAG 知识库"和"候鸟客户端 ControlV2"侧栏入口
- 在任务里减少候鸟操作
- 节约候鸟账号的资源占用
多人协作
如果团队多人共享一个候鸟账号：
- 每个人的 MBAgent 都能独立连接
- 但同时操作一个环境会冲突
- 建议错峰使用，或为每个人开独立候鸟子账号
下一步：权限管理与安全使用 → 放心地让 AI 干活。