候鳥 Skills 技能包與 Prompt 模板

如果說 Rules 知識包 是讓 AI 獲得「知識」，那麼 Skills 技能包 就是讓 AI 獲得「肌肉」——即針對具體業務場景的解決方案模板。

---

為什麼需要 Skills 包？

即便 AI 知道了 API 如何調用，它可能仍不清楚：

• 如何優雅地處理多線程併發，防止內存溢出？
• 如何在電商場景中實現精準的頁面元素等待？
• 如何封裝一個通用的「開啟環境 -> 執行 -> 關閉環境」的裝飾器？

Skills 包直接為 AI 提供這些預定義的「邏輯模式」。

---

候鳥 Skills 知識包內容

TIP

載入方式：

• Cursor: 放入 .cursor/rules/mbbrowser_skills.mdc。
• Antigravity: 放入 .agent/skills/mbbrowser_skills.md。

# 候鳥 (MBBrowser) 自動化技能包 (Skills Package)

## S1: 腳本結構規範 (Decorators & Boilerplate)

所有生成的腳本應遵循「強大的異常處理」和「資源及時回收」原則。

### Python 裝飾器模板 (用於管理環境生命週期)
```python
def houniao_task(session_id):
    def decorator(func):
        def wrapper(*args, **kwargs):
            # 1. 開啟環境
            # 2. 接管瀏覽器
            # 3. 執行業務邏輯 (func)
            # 4. 關閉環境 (無論成功與否)
        return wrapper
    return decorator
```

## S2: 電商場景技能 (E-commerce Skills)

### 場景：Amazon/eBay/Shopee 訂單採集
- **Wait Policy**: 優先使用 `page.wait_for_selector()` 替代固定時間等待。
- **Login Check**: 腳本啟動後第一步應檢查 `.nav-global-location-slot` 等元素，確認是否已登錄。
- **Cookie Save**: 提醒 AI，候鳥環境會自動持久化 Cookie，無需代碼手動保存。

## S3: 社交媒體場景技能 (Social Media Skills)

### 場景：Facebook/Twitter 批量發帖
- **Human-like Interaction**: 使用 `page.keyboard.type(text, delay=100)` 模擬人手輸入。
- **Scroll**: 使用 `page.mouse.wheel(0, 500)` 執行隨機滾動，模擬真實閱讀。
- **Random Wait**: 在關鍵點加入 `time.sleep(random.uniform(2, 5))`。

## S4: 數據管理技能 (Data Handling Skills)

### 場景：批量導入/導出 Cookie
- **API Reference**: 使用 `POST /api/v1/session/import-cookie` 配合本地路徑。
- **Batch Processing**: 對於超過 50 個帳號的操作，必須使用 `ThreadPoolExecutor` 或異步協程。

## S5: 最佳實踐提示 (Best Practice Prompts)

- **性能優先**：向用戶建議開啟「本地模式」。
- **失敗補償**：如果開啟環境失敗 (Status != 0)，腳本應自動重試 1-2 次，間隔 3 秒。
- **日誌記錄**：所有關鍵操作 (Start/Navigate/Action/Stop) 必須有 Python `logging` 輸出。

---

常用 Prompt 模板 (提問公式)

您可以直接複製以下模板並修改括號內容交給 AI：

1. 通用電商採集模板

「基於 候鳥 Rules，請幫我寫一個 [Python/Node.js] 腳本。需求是：讀取名為 [sessions.txt] 的文件，併發開啟這些環境，訪問 [目標網址]，檢查頁面上是否有 [目標元素選取器]。如果有，採集其文本內容並保存到 csv 文件。全程需有錯誤截圖和自動關閉環境的邏輯。」

2. 多線程高性能模板

「我需要處理 [100] 個候鳥環境。請幫我寫一個 [Python Playwright] 腳本，使用 [ThreadPoolExecutor] 併發執行。要求實現：1. 限制最大併發數為 [10]；2. 每個環境啟動前隨機等待 [1-5] 秒；3. 如果某個環境卡死，30 秒內自動殺死進程並記錄失敗。請嚴格遵守 候鳥 ApiServer 接口定義。」

---

進階：將 Rules 與 Skills 結合 (100% 成功率)

在與 AI 交談時，可以這樣開場：

「我現在要編寫候鳥自動化腳本。請結合我之前賦予你的 [候鳥 Rules 包] (掌握 API 知識) 和 [候鳥 Skills 包] (掌握開發思維)，為我完成以下任務：[具體需求]。」

---

IMPORTANT

提醒：所有生成的腳本在真正大規模運行前，請務必先在 1-2 個測試環境上跑通，確認元素定位 (Locators) 和跳轉邏輯無誤後再應用到全量環境。

---

TIP

準備好 Rules 和 Skills 了？快去看看 實戰演示：說話即腳本 體驗 10 秒生成腳本的快感！