候鳥 ApiServer 知識包 (Rules Package)

這是本專欄最核心的部分。通過將以下 Rules 知識包注入 Cursor 或 Antigravity，AI 模型將全量掌握候鳥 ApiServer 的所有接口、錯誤碼、附錄參數，確保在編寫腳本時絕不產生「幻覺」。

---

IMPORTANT

候鳥自動化核心建議： 在運行自動化腳本時，請務必將候鳥客戶端設置中的運行模式切換為 「本地模式」。

• 性能提升：本地模式會自動跳過網絡數據同步（上傳/下載環境數據），自動化開啟速度與腳本執行效率將提升 數十倍。
• 安全提醒：請養成每日備份本地數據的習慣。您的核心業務數據（環境、指紋、Cookie 等）均存儲在 MBDATA 目錄下，請定期對該文件夾進行異地備份。

---

如何使用

對於 Cursor 用戶

1. 在您的候鳥腳本項目根目錄創建一個文件 .cursor/rules/mbbrowser.mdc。
2. 將下方「候鳥 ApiServer Rules 知識包」的完整內容複製粘貼進去並保存。
3. 重新開啟 Cursor Chat (或開啟一個新對話)。
4. AI 會在接下來的每一次對話中自動攜帶這些知識。

對於 Antigravity 用戶

Antigravity (Google 的 Agent 優先 IDE) 有自己的規則體系，使用獨立的 .agent/rules/ 目錄。

操作步驟：

1. 在項目根目錄（工作區或 git 根目錄）下創文件夾 .agent/rules/ (如已存在則直接使用)。
2. 在該文件夾內創建一個文件 mbbrowser.md (後綴必須是 .md，純 Markdown 格式)。
3. 將下方「候鳥 ApiServer Rules 知識包」中的規範、接口詳解和代碼模板複製粘貼進去並保存。
4. 重啟 Antigravity 或重新打開項目 -> Agent 將自動加載 .agent/rules/ 下的所有 .md 文件並注入系統提示詞 (在工作區級別生效)。

文件結構示例：

your-project/
└── .agent/
    └── rules/
        └── mbbrowser.md   ← 在這裡粘貼規範內容

進階提示：

• 全量同步：如果您同時使用兩款工具，可以維護雙路徑：.cursor/rules/mbbrowser.mdc (供 Cursor 使用) + .agent/rules/mbbrowser.md (供 Antigravity 使用)。
• 字符限制：規則文件大小上限約為 12,000 字符，如果內容過多，建議拆分為多個 .md 文件。
• 全局生效：如果您希望在所有項目中生效，可以放入 ~/.gemini/GEMINI.md。

---

候鳥 ApiServer Rules 知識包

請複製下方全部內容並替換上述文件中的內容。

# 候鳥 (MBBrowser) + ApiServer 完整開發規範

## 1. 產品簡介

> [!IMPORTANT]
> **性能秘訣**：在大規模自動化運行前，請確保候鳥客戶端處於 **「本地模式」**。這將跳過雲端數據同步，環境開啟速度提升數十倍。請務必定期手動備份 **`MBDATA`** 業務數據文件夾。

候鳥 (MBBrowser) 是一款專業的防關聯指紋瀏覽器，用於多帳號環境隔離。每個「環境」(Session) 都有獨立的：瀏覽器指紋、代理 IP、Cookie、User-Agent、時區、語言等。
ApiServer (apiserver.exe) 是候鳥在本地開放的 HTTP API 服務，允許腳本通過編程方式控制瀏覽器環境。

## 2. ApiServer 啟動方式

```bash
apiserver.exe --port=8186 \
  --account=your_email@qq.com \
  --app_id=YOUR_APP_ID \
  --app_key=YOUR_APP_KEY \
  --hide=off \
  --return=on \
  --logs=on
```

參數說明：
- port: 監聽端口，默認 8186。
- account: 候鳥登錄帳號 (郵箱)。
- app_id: 從候鳥客戶端「個人中心 -> API 設置」中獲取。
- app_key: 從候鳥客戶端「個人中心 -> API 設置」中獲取。
- hide=off: 有頭模式 (推薦調試使用)；hide=on 為無頭後台模式。
- return=on: 在控制台顯示 API 返回數據。
- logs=on: 將 JSON 數據寫入日誌文件。

啟動成功後，API 地址為 http://127.0.0.1:8186。

## 3. 通訊規範

- 所有接口均為 HTTP POST 請求。
- Content-Type: application/json。
- 基礎 URL: http://127.0.0.1:8186。
- code=0 代表成功；code 為負數代表失敗，message 包含錯誤詳情。

標準返回格式：
```json
{
  "message": "Success",
  "code": 0,
  "data": { ... }
}
```

## 4. 帳號認證

### 4.1 帳號登錄 (切換帳號時使用)
POST /login
```json
{
  "APP_ID": "7e147176e1d756eb03c0e18e7b640c23",
  "APP_KEY": "YOUR_APP_KEY",
  "Account": "test01@qq.com",
  "return": "on",
  "logs": "on",
  "hide": "off"
}
```
返回：{"msg": "Login Success", "status": 0, "data": "Login Account: test01@qq.com"}
注意：ApiServer 啟動時已攜帶認證，此接口通常無需調用。

### 4.2 退出 ApiServer
POST /api/v1/quit
無請求參數。成功返回 code: 0 並關閉 ApiServer。

## 5. 核心接口：環境生命週期管理

### 5.1 開啟環境 (最核心接口)
POST /api/v1/browser/start
[最大頻率：不限，建議配合 --interval-seconds 控制]

請求參數：
```json
{
  "Session_ID": ["373808cb37bd63f5f7d92415e736e85f"],
  "isHeadless": false,
  "args": [
    "--disable-extensions",
    "--blink-settings=imagesEnabled=false",
    "--interval-seconds=2"
  ]
}
```

重點說明：
- Session_ID 為 Array，支持多環境同時啟動。
- isHeadless=false 為有頭模式 (可見視窗)，默認為 true。
- --interval-seconds 控制多個環境之間的啟動間隔秒數。
- --blink-settings=imagesEnabled=false 禁用圖片加載 (速度更快)。
- --disable-extensions 禁用瀏覽器插件 (自動化常用)。

啟動成功關鍵返回字段：
```json
{
  "message": "Success",
  "code": 0,
  "data": {
    "listid": [{
      "Session_Name": "業務環境 01",
      "Session_ID": "373808cb37bd63f5f7d92415e736e85f",
      "browser_CDP_Port": 46973,
      "webdriver": "C:\\Users\\Admin\\houniao\\Driver\\100\\chromedriver.exe",
      "status": 0
    }],
    "total": 1
  }
}
```

[極端重要] 各框架正確對接方式：

Python Playwright:
```python
port = env_data["browser_CDP_Port"]
ws_endpoint = f"ws://127.0.0.1:{port}/json/version"
from playwright.sync_api import sync_playwright
pw = sync_playwright().start()
browser = pw.chromium.connect_over_cdp(ws_endpoint)
context = browser.contexts[0]          # 必須取已有 Context！不能用 new_context()
page = context.pages[0] if context.pages else context.new_page()
```

JavaScript Playwright:
```javascript
const { chromium } = require('playwright');
const port = envData.browser_CDP_Port;
const wsEndpoint = `ws://127.0.0.1:${port}/json/version`;
const browser = await chromium.connectOverCDP(wsEndpoint);
const context = browser.contexts()[0];  // 必須取已有 Context！
const page = context.pages()[0] || await context.newPage();
```

Python Selenium:
```python
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service
options = Options()
# debuggerAddress 是 "IP:端口" 格式，不用 ws://
options.add_experimental_option("debuggerAddress", f"127.0.0.1:{env_data['browser_CDP_Port']}")
service = Service(executable_path=env_data['webdriver'])
driver = webdriver.Chrome(service=service, options=options)
```

JavaScript Puppeteer:
```javascript
const puppeteer = require('puppeteer');
const port = envData.browser_CDP_Port;
const wsEndpoint = `ws://127.0.0.1:${port}/json/version`;
const browser = await puppeteer.connect({
  browserWSEndpoint: wsEndpoint,
  defaultViewport: null
});
```

### 5.2 關閉環境
POST /api/v1/browser/stop
```json
{
  "Session_ID": "373808cb37bd63f5f7d92415e736e85f"
}
```
注意：此接口 Session_ID 為 String (不是數組)。
成功：{"message": "Success", "code": 0, "data": {"action": "StopSession_ID", "status": 0}}

### 5.3 強制關閉 (Kill)
POST /api/v1/browser/kill
```json
{
  "Session_ID": "373808cb37bd63f5f7d92415e736e85f"
}
```
注意：普通 stop 有時在使用某些擴展後會導致進程殘留，推薦用 kill 強制關閉確保配額回收。

### 5.4 檢查運行狀態
POST /api/v1/browser/status
```json
{
  "Session_ID": ["4e6d0dca26ef42be9bc4472779d2550f"],
  "Actived_Type": 0
}
```
Actived_Type: 0 為全部，1 為僅運行中，2 為僅未運行。
返回 Session_Actived=1 代表在運行，0 代表未運行。

## 6. 環境查詢接口

### 6.1 獲取環境列表 (多維度篩選)
POST /api/v1/session/listid
過濾參數 (均為可選)：
- Session_Name, Session_GroupName, Proxy_Ip, Proxy_Type 等。
- CurrentPage, ListNum (默認 50，最大 500)。

成功：
```json
{
  "code": 0,
  "data": {
    "listid": ["373808...", "705cc..."],
    "total": 2
  }
}
```

### 6.2 查詢指定 Session_ID 的配置數據
POST /api/v1/session/id_container
```json
{
  "Session_ID": ["373808cb37bd63f5f7d92415e736e85f"],
  "Session_container_type": 1
}
```
Session_container_type: 1 為全量詳情 (包含 browser_CDP_Port, webdriver, 完整指紋)。

## 7. 創建與更新接口

### 7.1 創建環境
POST /api/v1/session/create
[最大頻率：40 請求/分]
重要參數 `Automatic_Configure`:
- `0` (推薦): 快速創建 (自動從候鳥業務庫匹配指紋，不校驗代理)。
- `1`: 包含 IP 校驗，創建時間較長 (請求超時需設置 > 68s)。

### 7.2 更新基礎信息
POST /api/v1/session/update
包含 Session_Name, Session_Desc, Session_Group, Cookie (JSON 格式字符串) 等。

### 7.3 更新代理
POST /api/v1/session/proxy/update
[最大頻率：50 請求/分]
支持：HTTP, HTTPS, SSH, SOCKS4/5, Oxylabs, Luminati, smartproxy, noproxy。

### 7.4 刪除環境
POST /api/v1/session/delete
`Is_Delete_All: 1` 則全量清空。

## 8. Cookie 管理

### 8.1 導入 Cookie (路徑模式)
POST /api/v1/session/import-cookie
```json
{
  "Session_ID": "session_id",
  "Cookie_File": "C:\\cookies\\account1.txt"
}
```
支持 .txt (Netscape) 和 .json 格式。

### 8.2 導出 Cookie (到路徑)
POST /api/v1/session/export-cookie
使用 `Export_Cookie_File` 指定路徑。後綴為 .json 則導出為 JSON，否則為 Netscape。

## 9. 插件管理
- POST /api/v1/plugin/list (獲取帳號全量插件)
- POST /api/v1/session/id_plugin_list (獲取環境內插件)
- POST /api/v1/session/plugin_install (安裝插件)
- POST /api/v1/session/plugin_delete (刪除插件)

## 10. 自動化腳本管理
- POST /api/v1/session/id_script_list (查看環境腳本)
- POST /api/v1/session/id_script_add (從腳本庫分配)
- POST /api/v1/session/id_script_active (激活腳本)

---

## 11. 完整錯誤碼表

### CODE (請求層面)
0 成功；-1 登錄失敗；-105 代理校驗失敗；-106 時區異常；-108 分辨率錯誤。

### Status (開啟環境返回的狀態字段)
0 成功；-7 已在運行中；-22 Session_ID 未找到。

## 12. 附錄：合法值列表

### 12.1 SystemOS
Windows | iPhone | iPad | MacIntel | Android | Linux x86_64 等。

### 12.2 LanguageCode
zh-CN;zh;q=0.9 | en-US;en;q=0.9 | ja;q=0.9 | fr-FR;fr;q=0.9 等。

### 12.3 Session_Resolution
1920x1080 | 1440x900 | 1366x768 | 2560x1440 | 375x812 (iPhone X) 等。

## 13. 開發注意事項

1.  **Session_ID 類型**：/start and /id_container 用 Array；/stop, /update, /proxy/update 用 String。
2.  **Playwright context**：必須始終操作 `browser.contexts[0]`，不要使用 `new_context()`。
3.  **Selenium**：使用 `debuggerAddress` ("IP:PORT")，不要使用 ws。
4.  **併發**：單批次建議不超過 20 個環境。
5.  **狀態檢查**：/start 後務必校驗 `data.listid[0].status`。
6.  **代理校驗**：使用 /start 返回的 `Public_ip` 來驗證代理是否生效。
7.  **合法值**：分辨率/語言/時區必須使用附錄中的合法值，否則會觸發 -106/-107/-108/-110 等錯誤。

## 14. 完整 Python 腳本模板

```python
"""
候鳥瀏覽器 + Playwright Python 自動化模板
"""
import requests, threading
from playwright.sync_api import sync_playwright

def start_env(session_id: str):
    resp = requests.post("http://127.0.0.1:8186/api/v1/browser/start", 
                         json={"Session_ID": [session_id]}).json()
    return resp["data"]["listid"][0] if resp["code"] == 0 else None

def do_task(session_id):
    env_data = start_env(session_id)
    if not env_data: return
    with sync_playwright().start() as pw:
        # 通過 CDP 連接
        browser = pw.chromium.connect_over_cdp(f"ws://127.0.0.1:{env_data['browser_CDP_Port']}/json/version")
        context = browser.contexts[0] # 核心：取已有上下文
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        print(f"[{session_id}] 標題: {page.title()}")
        browser.close()
    requests.post("http://127.0.0.1:8186/api/v1/browser/stop", json={"Session_ID": session_id})

if __name__ == "__main__":
    sids = ["yoursid1", "yoursid2"]
    threads = [threading.Thread(target=do_task, args=(sid,)) for sid in sids]
    for t in threads: t.start()
    for t in threads: t.join()
```

---

配置生效驗證

配置完成後，在 Chat 中輸入：

請用 Python + 候鳥 ApiServer，實現獲取分組「測試組」下的所有 ID，
並併發啟動 (最大 10 個)，在每個環境中使用 Playwright 訪問 https://example.com，
截圖後關閉環境。要求包含完整的異常處理。

若 AI 能正確做到以下幾點，則說明配置成功：

• ✅ 正確使用了 POST /api/v1/session/listid。
• ✅ /start 中 Session_ID 使用了 Array。
• ✅ 正確使用了 browser.contexts[0]。
• ✅ /stop 中 Session_ID 使用了 String。