Web 工具策略

遵循 ReAct 範式。四個工具不是層級關係，是分支決策：

┌─ 沒有 URL，需要搜尋 ──────→ web_search   （關鍵詞搜尋）
│
├─ 已知 URL，靜態內容 ──────→ web_fetch    （直取頁面）
│
├─ 以上失敗 / 不適用 ──────→ opencli      （CLI 結構化訪問，70+ 站點）
│
└─ 全都不行 ───────────────→ browser      （瀏覽器自動化，兜底）

先按場景選 web_search 或 web_fetch；失敗時先試 opencli，最後才上 browser。 每次切換工具告知使用者原因，不要靜默降級。

決策流程

有明確 URL？
├─ YES → 靜態內容（文章/文件/API/RSS）？
│        ├─ YES → web_fetch
│        │        失敗（空白/403/CAPTCHA）？→ opencli → browser
│        └─ NO（需要 JS/登入/互動/截圖）→ opencli → browser
└─ NO  → web_search
         ├─ 成功 → 對結果 URL 按上述邏輯選 fetch/opencli/browser
         ├─ 失敗（API 錯誤）→ 引導配置（見"web_search 失敗處理"）
         └─ 無結果/不適用 → opencli → browser

web_search

來源於7w4.net。

何時用：沒有明確 URL，需要搜尋資訊（新聞、熱點、查資料、比較資訊）。

怎麼用：直接呼叫 web_search，傳入搜尋關鍵詞。

結果處理：返回的 URL 按決策流程選 web_fetch、opencli 或 browser 深入獲取。

失敗時：見下方"web_search 失敗處理"。

web_fetch

何時用：已知 URL，頁面為靜態內容——新聞文章、部落格、技術文件、API 端點、RSS 源。

怎麼用：直接呼叫 web_fetch，傳入 URL。

失敗訊號：返回空白頁、403、CAPTCHA、骨架 HTML → 嘗試 opencli，仍不行再升級到 browser。

opencli（Fallback，優先於 browser）

何時用：web_search / web_fetch 失敗或不適用時，先試 opencli 再考慮 browser。覆蓋 70+ 主流網站，秒級返回結構化資料。

首次使用前：如果執行 opencli 提示 command not found，需要先執行安裝指令碼（冪等，可重複執行）：

bash {baseDir}/scripts/setup-opencli.sh

該指令碼會自動完成：安裝 opencli CLI → 編譯 Browser Bridge 外掛 → 重啟瀏覽器載入外掛。

漸進式發現（不需要記命令）：

opencli --help                    # 有沒有這個站？
opencli <site> --help             # 這個站能做什麼？
opencli <site> <command> --help   # 這個命令怎麼用？

詳細用法：read {baseDir}/references/opencli-guide.md

失敗時：告知使用者 opencli 失敗原因，降級到 browser。

browser（最後手段）

這是最重量級的工具，也是當前問題最多的場景。以下是詳細操作指引。

何時用

• JS 渲染頁面：SPA、動態載入內容（微博 feed、知乎回答、小紅書瀑布流）
• 需要登入態：登入後才可見的內容、管理後臺
• 頁面互動：點選按鈕、填寫表單、翻頁、滾動載入更多
• 截圖需求：需要頁面視覺資訊
• 其他工具全部失敗的兜底

操作流程

資訊獲取（只讀）：

1. 導航到目標 URL
2. 等待關鍵元素出現（不要用固定時間等待）
3. 提取所需內容（文本、連結、圖片等）
4. 返回結果給使用者

登入操作：

1. 查詢登入頁 URL → read {baseDir}/references/well-known-sites.json
2. 告知使用者即將執行登入操作，獲取確認
3. 導航到登入頁
4. 填寫憑證（使用者提供）或提示使用者掃碼
5. 等待登入成功，確認後繼續後續操作

頁面互動：

1. 導航到目標頁面
2. 使用 CSS 選擇器定位元素（輔以文本內容匹配）
3. 執行互動：點選、輸入、選擇、滾動
4. 等待響應/頁面變化
5. 提取結果或截圖

關鍵注意事項

• 登入操作必須獲得使用者授權 — 任何涉及賬號登入的操作前，先告知使用者並等待確認
• 敏感操作必須二次確認 — 發帖、刪除、支付等不可逆操作
• 優先 CSS 選擇器 — 比 XPath 更穩定，輔以文本匹配
• 智慧等待 — 等待目標元素出現，而非 sleep(3) 式固定等待
• CAPTCHA/驗證碼 — 無法自動處理時告知使用者需手動介入
• 頁面載入超時 — 設定合理超時，失敗時告知使用者並建議重試
• 多步操作保持狀態 — 登入後的後續操作複用同一瀏覽器上下文，不要重新開啟

web_search 失敗處理

當 web_search 返回錯誤時，不要靜默降級，必須引導配置：

1. read {baseDir}/references/web-search-config.md
2. 按檔案中 Step 1 原樣輸出配置引導給使用者（不要改寫表格或省略內容）
3. 等待使用者回覆：
   • 使用者提供 API Key → 再次 read {baseDir}/references/web-search-config.md，按 Step 2-5 執行
   • 使用者說"暫不配置" → 進入降級方案
   • 其他回覆 → 正常響應
4. 降級方案（僅在使用者明確拒絕配置後）：
   • read {baseDir}/references/well-known-sites.json 獲取常用網站 URL
   • 用 web_fetch 直接獲取目標網站內容
   • 仍不行 → 升級到 browser

常用網站

需要常用網站 URL 時（登入頁、搜尋引擎、熱搜榜等）：

read {baseDir}/references/well-known-sites.json

通過 key 查詢（如 social.weibo.login、search.baidu）。帶 {query} 的 URL 替換為實際搜尋詞。

這個 Skill 質量較好，工具使用策略清晰、失敗處理考慮周全、覆蓋網站範圍廣泛。優點是決策流程明確不易出錯，配置引導細緻人性化，對敏感操作有安全保護。不足之處是部分內容較為冗長，專業術語較多，對新手不太友好；另外瀏覽器自動化的操作指引相對簡單，遇到複雜場景時幫助有限。總體而言，這是一個實用且設計用心的 Skill，但對普通使用者來說需要一定學習成本。