瀏覽器控制權管理

MBAgent 通過 CDP（Chrome DevTools Protocol）連接並控制候鳥瀏覽器，這是 MBAgent 與本地瀏覽器交互的核心能力。

NOTE

截圖說明：本篇已為瀏覽器選擇、權限配置、實際操作等環節配圖。

一、什麼是瀏覽器控制權？

瀏覽器控制權是指 MBAgent 可以通過 CDP 協議操作候鳥瀏覽器實例，代替您完成網頁瀏覽、表單填寫、數據抓取、賬號登入等操作。

核心能力

🚀 打開任意網址：導航到指定頁面
📝 填寫表單：自動填寫輸入框、下拉選擇
🖱️ 點擊操作：點擊按鈕、鏈接、複選框
📸 截圖取證：捕獲頁面截圖供 AI 分析
📋 讀取內容：獲取頁面文本、HTML 結構
🔍 執行 JS：在頁面上下文執行 JavaScript
🍪 管理 Cookie：讀取、修改、刪除 Cookie
📦 下載文件：觸發文件下載
🔐 賬號登入：自動登入網站
🛡️ 繞過人機驗證：在授權下處理簡單驗證碼

二、前置準備：候鳥客戶端連接

啟動候鳥瀏覽器

確保候鳥瀏覽器（mbbrowser.exe）已啟動
在候鳥客戶端中創建或打開一個環境（環境即一個獨立的瀏覽器實例）
不要關閉該環境，MBAgent 會通過 CDP 連接這個環境

MBAgent 中的設置

在 MBAgent 設置中，選擇要控制的候鳥客戶端：

選擇候鳥客戶端

操作步驟

進入 "設置" → "瀏覽器" 標籤
從下拉框選擇候鳥客戶端（顯示本機所有運行的候鳥客戶端實例）
點擊 "驗證連接"
看到 ✅ 綠色對勾表示連接成功

客戶端狀態

狀態	含義	解決
✅ 已連接	MBAgent 可正常使用	-
⚠️ 未連接	MBAgent 沒有選擇客戶端	從下拉框選擇
❌ 連接失敗	客戶端已關閉或端口佔用	重啟候鳥瀏覽器
🚫 無客戶端	本機沒有運行候鳥瀏覽器	啟動候鳥瀏覽器

三、CDP 連接原理（簡述）

架構

┌────────────┐     CDP/WebSocket     ┌──────────────┐
│  MBAgent   │ ◄──────────────────► │  候鳥瀏覽器  │
│ (Rust)     │    127.0.0.1:xxxxx   │  (Chromium)  │
└────────────┘                       └──────────────┘

端口分配

候鳥瀏覽器為每個環境分配獨立 CDP 端口
MBAgent 通過 WebSocket 與該端口通信
一個 MBAgent 同時只能控制一個環境（一個 CDP 連接）

安全機制

只監聽 127.0.0.1（本機回環）
不對外網開放
每個連接都有獨立會話 ID

四、可執行操作範圍

受控操作清單

類別	操作	是否需要確認
導航	打開網址、前進、後退、刷新	否
讀取	讀取頁面文本、HTML、截圖	否
輸入	填寫輸入框、文本域	是（高風險操作）
點擊	點擊按鈕、鏈接	是
提交	提交表單	是
登入	賬號登入	是
支付	支付操作	是 + 二次確認
刪除	刪除賬號、刪除數據	是 + 二次確認
下載	下載文件	是
執行 JS	執行任意 JS	是
Cookie 操作	修改 Cookie	是

高風險操作

以下操作始終需要用戶確認：

💰 任何涉及資金的操作（支付、轉賬）
🔐 賬號密碼輸入
🗑️ 刪除類操作
⚙️ 修改賬號設置
📤 公開發布類操作（發帖、發郵件）
🚨 安全相關操作（修改密碼、綁定手機）

操作日誌

所有操作都會被記錄：

操作時間
操作類型
目標 URL
執行結果
截圖（可選）

可在 "歷史記錄" → "操作日誌" 中查看。

五、賬號登入

自動登入流程

MBAgent 可以通過幾種方式登入網站：

方式一：賬號密碼登入（需用戶確認）

AI 識別到登入頁面
詢問您是否提供賬號密碼
您確認後，AI 自動填寫並提交
AI 不會記住密碼（出於安全考慮）

您先在候鳥瀏覽器中手動登入
關閉瀏覽器
下次 MBAgent 啟動時會自動繼承 Cookie
無需重複登入

方式三：第三方登入（OAuth）

Google / GitHub / 微信等第三方登入
不支持自動登入（需要您手動完成）
AI 會提示您手動操作

六、人機驗證（CAPTCHA）處理

簡單驗證碼

類型	處理方式
圖形驗證碼（4-6 位字符）	AI 識別後自動填入
滑塊驗證	AI 控制滑塊完成
數學驗證碼（如 3+5=?）	AI 自動計算填入
文字點選（按順序點選漢字）	AI 識別後點選

複雜驗證碼

類型	處理方式
reCAPTCHA v2	需要您手動完成
hCaptcha	需要您手動完成
FunCaptcha	需要您手動完成
短信驗證碼	等待您收到後手動輸入
郵箱驗證碼	等待您收到後手動輸入

驗證碼處理原則

IMPORTANT

人機驗證處理原則：

簡單驗證碼：MBAgent 自動處理
複雜驗證碼：彈窗提示您手動完成
多次失敗：自動暫停，避免觸發風控

七、頁面截圖與分析

截圖模式

MBAgent 提供 3 種截圖模式：

1. 全頁截圖

捕獲整個頁面（包括滾動區域外）。

2. 可視區域截圖

只捕獲當前可視區域。

3. 元素截圖

只捕獲指定元素。

截圖用途

📊 數據提取：表格、列表可視化分析
🔍 錯誤排查：UI 異常截圖反饋
📋 內容確認：操作前確認頁面狀態
🧾 操作憑證：操作完成後留底

截圖保存位置

%LOCALAPPDATA%\mbagent\screenshots\

八、限制與注意事項

瀏覽器限制

WARNING

無法做到的事：

❌ 控制本地其他應用（VSCode、Photoshop 等）
❌ 控制手機 App
❌ 繞過登入態強行訪問
❌ 繞過網站反爬蟲機制
❌ 操作需要短信驗證的關鍵操作
❌ 處理高強度 CAPTCHA（reCAPTCHA v3 等）

安全限制

IMPORTANT

MBAgent 不會做以下事：

❌ 在用戶不知情下提交表單
❌ 自動輸入用戶沒提供的密碼
❌ 修改賬號安全設置
❌ 公開發布未經審核的內容
❌ 進行任何資金轉移

性能限制

一個 MBAgent 同時只能控制 一個環境
不支持多環境並發
單頁面操作超時為 30 秒
連續失敗 5 次會自動暫停任務

九、故障排查

問題 1：連接失敗

症狀：MBAgent 顯示 "無法連接到候鳥瀏覽器"

排查：

確認候鳥瀏覽器已啟動
確認候鳥瀏覽器中有至少一個環境
確認環境未關閉
檢查防火牆是否阻擋 127.0.0.1
重啟候鳥瀏覽器和 MBAgent

問題 2：操作失敗但頁面無變化

症狀：AI 報告"已點擊"，但頁面沒反應

排查：

讓 AI 提供截圖
檢查頁面是否需要滾動才能看到按鈕
檢查是否有遮罩層
嘗試刷新頁面重試

問題 3：賬號被風控

症狀：登入後立刻被踢出，要求重新驗證

排查：

暫停 AI 操作
手動登入並通過風控驗證
開啟候鳥瀏覽器的指紋保護
更換 IP 後重試

問題 4：頁面加載慢

症狀：AI 報告"頁面一直加載中"

排查：

檢查網絡
增加等待時間
嘗試強制刷新（Ctrl+F5）

十、最佳實踐

不推薦做法

❌ 讓 AI 在您不監控的情況下長時間運行
❌ 把賬號密碼直接告訴 AI
❌ 讓 AI 操作多個賬號（容易被風控）
❌ 在登入狀態下讓 AI 隨意操作

下一步：權限管理與安全使用 → 理解 MBAgent 的權限邊界。

瀏覽器控制權管理 ​

一、什麼是瀏覽器控制權？ ​

核心能力 ​

二、前置準備：候鳥客戶端連接 ​

啟動候鳥瀏覽器 ​

MBAgent 中的設置 ​

操作步驟 ​

客戶端狀態 ​

三、CDP 連接原理（簡述） ​

架構 ​

端口分配 ​

安全機制 ​

四、可執行操作範圍 ​

受控操作清單 ​

高風險操作 ​

操作日誌 ​

五、賬號登入 ​

自動登入流程 ​

方式一：賬號密碼登入（需用戶確認） ​

方式二：Cookie 注入（推薦） ​

方式三：第三方登入（OAuth） ​

六、人機驗證（CAPTCHA）處理 ​

簡單驗證碼 ​

複雜驗證碼 ​

驗證碼處理原則 ​

七、頁面截圖與分析 ​

截圖模式 ​

1. 全頁截圖 ​

2. 可視區域截圖 ​

3. 元素截圖 ​

截圖用途 ​

截圖保存位置 ​

八、限制與注意事項 ​

瀏覽器限制 ​

安全限制 ​

性能限制 ​

九、故障排查 ​

問題 1：連接失敗 ​

問題 2：操作失敗但頁面無變化 ​

問題 3：賬號被風控 ​

問題 4：頁面加載慢 ​

十、最佳實踐 ​

推薦做法 ​

不推薦做法 ​