Groundlane 實戰系列（篇 2）：三個 MCP 工具的參數、回傳與錯誤處理

🌏 English version

這篇不再重複篇 1 的架構說明（為什麼需要受控網路存取層、三工具責任分工），而是直接進入實戰層：每個工具在什麼參數組合下會回傳什麼結構、哪些欄位是確定性來源（可以逐行驗證）、哪些欄位是合成結果（需要理解其生成邏輯）。所有範例均以 Groundlane v0.1.0 自述與文件結構為依據，而非假設未來功能。

三工具的呼叫合約（簡要對照）

注意：web_search 需要至少一個已啟用的搜尋提供者金鑰（十個適配器為選用）；web_fetch 與 web_extract 不需要任何搜尋提供者金鑰，只要目標 URL 可直接存取即可運作（篇 1 已說明，此處僅重申作為操作前提）。

web_search：參數選擇與回傳解讀

自述提到自動搜尋的預設行為：最多兩個互補提供者、自動去重（canonical-URL）、RRF 合併、保留各提供者原始排名證據。這意味著即使你沒有明確指定提供者，系統也會在已啟用的提供者中選擇最多兩個進行合併，而非隨機或單一來源。

實際操作時，參數組合對結果的影響可以這樣理解：

• 不指定提供者（自動）：由本機路由邏輯從已啟用的提供者中選擇最多兩個互補來源，執行 RRF 合併，並在結果中保留每個來源的原始排名與最終合併後的排名。這對「快速驗證某主題是否有足夠來源」的場景最實用，因為你不需要事先知道哪個提供者對該主題表現最好。
• 指定單一提供者（例如 tavily）：結果為單一來源，不執行 RRF 合併，回傳結構較簡單（無多來源排名對照），適合需要精確追蹤某提供者行為或避免合併邏輯干擾的場景。
• 指定多個提供者（明確列表）：系統仍會執行合併，但僅限於你指定的集合；這讓你可以控制「互補範圍」，例如只合併 tavily 與 exa 而排除其他。

回傳結構的關鍵欄位（依據自述描述，而非推測）：

• finalUrl、title、snippet（或對應內容摘要）：來自提供者的原始回傳，經本機正規化。
• engine、backend：標註檢索來源與後端路徑（例如直接 HTTP、瀏覽器渲染、託管後備），這些欄位是「來源證據」，可用於審計與重現。
• rank（各提供者原始排名）與合併後的最終排名：若為自動合併，結果會包含每個來源的原始排名與 RRF 合併後的最終順序；若為單一來源，則僅有該來源的排名。
• canonical 去重證據：自動搜尋預設執行 canonical-URL 去重，因此同一內容若出現在多個提供者中，只會保留一個代表性結果，並在證據中標註去重依據。

實際操作建議（基於目前可驗證的行為，而非未來承諾）：先以自動模式執行一次，觀察回傳中有哪些提供者被選中、哪些欄位標註了來源證據；再根據需求固定為單一提供者（精確追蹤）或明確多提供者（控制互補範圍）。不要假設自動模式永遠選擇相同的提供者組合——提供者可用性與路由邏輯可能隨配置與網路狀態變化。

web_fetch：格式與渲染策略的實際差異

web_fetch 的參數中，format 決定輸出格式，render 決定是否啟用瀏覽器渲染。這兩個參數的組合直接影響回傳結構與確定性來源：

• format: markdown + render: never：輸出為本機 Readability 正規化後的 Markdown，來源為直接 HTTP（engine: http、backend: direct），不啟用瀏覽器或託管後備。這對「快速提取文章主體內容、驗證參考資料」最合適，因為結果不包含瀏覽器渲染的額外開銷，且來源證據明確。
• format: html + render: never：輸出為原始 HTML（未經 Readability 正規化），適合需要保留完整 DOM 結構（例如後續以 web_extract 進行選擇器擷取）的場景。
• format: markdown + render: always（或 auto 且目標頁面需要渲染）：系統會啟用瀏覽器渲染（本機 Playwright 或啟用的 Browserless），來源證據會標註 backend 為瀏覽器路徑，並可能包含渲染時間與資源使用資訊。這對需要執行 JavaScript 後才能取得內容的頁面必要，但會增加操作成本與確定性複雜度（因為渲染結果可能受瀏覽器版本、網路延遲與頁面動態行為影響）。
• format: text：輸出為純文字（通常為 Markdown 的簡化形式），適合快速預覽內容而不需要完整格式的場景。

回傳結構中的確定性欄位（可逐行驗證）：

• finalUrl：最終解析後的 URL（可能與輸入 URL 不同，若存在重導向）。
• title：由 Readability 或瀏覽器渲染提取的頁面標題，來源明確標註。
• content：正規化後的內容（Markdown / HTML / text），長度受位元組與輸出上限限制（預設限制為安全邊界，不可關閉）。
• truncated：布林值，標示內容是否因超出上限而被截斷。若為 true，表示回傳內容不完整，應視為部分結果而非完整擷取。
• engine、backend、finalUrl：這三個欄位共同構成「檢索來源證據」，可用於驗證結果是否來自預期路徑（例如直接 HTTP 而非託管後備，或瀏覽器渲染而非直接讀取）。

實際操作建議：先以 render: never 執行，確認內容可直接取得且來源證據符合預期（engine: http、backend: direct）；若內容不完整或缺少關鍵部分，再切換為 render: auto 並觀察 backend 是否變為瀏覽器路徑，以及 truncated 是否為 true。不要在未驗證直接讀取結果的情況下直接使用瀏覽器渲染，因為這會增加確定性風險與操作成本。

web_extract：確定性擷取與選擇器設計

web_extract 的核心原則（依據自述與文件）：不使用隱式 LLM 推論，而是以 CSS selector 結構為確定性來源。這意味著每個擷取結果都對應一個明確的選擇器，每個節點的值或屬性都可逐行解釋，且結果在不同執行間應可重現（假設目標頁面的 DOM 結構穩定）。

選擇器結構的設計方式（實際操作建議，而非推測）：

• 使用標準 CSS selector 語法（例如 .article h2、article > h2、#main .content p），而非自訂語言或隱式模式匹配。
• 對於需要提取屬性值（例如 href、src、data-*）的場景，明確指定屬性名稱（例如 a[href] 提取連結，img[src] 提取圖片來源），而非依賴內容推論。
• 對於需要提取多個節點並組合為結構化結果的場景，設計選擇器使每個節點對應一個明確的結構欄位（例如 title 對應 h1，summary 對應 .abstract p），而非讓系統自動判斷哪些節點屬於同一記錄。

回傳結構的確定性欄位：

• 每個選擇器結果對應一個節點，節點值為選擇器匹配的內容（文字或指定屬性值）。
• 若選擇器未匹配任何節點，結果為空（無隱式填充或推論），這讓你可以明確判斷「該欄位在當前頁面中不存在」而非「系統未找到該欄位」。
• 回傳結構不包含模型推論步驟的中間結果（例如「我認為這是標題」），僅包含選擇器匹配的原始值，這使得結果可逐行驗證且可重現。

實際操作建議：在正式大規模擷取前，先對目標頁面執行一次小範圍測試（僅擷取關鍵欄位的選擇器），驗證回傳結構是否與預期一致、選擇器是否匹配到正確節點、以及結果是否包含不必要的內容（例如廣告、導航元素）。若測試結果不一致，調整選擇器而非假設系統會自動修正——確定性擷取的前提是選擇器與 DOM 結構的一致性，而非系統的容錯能力。

錯誤邊界與操作限制（實際可驗證）

根據自述與文件提到的預設限制（這些是安全邊界，而非可關閉的選項）：

• URL 政策與 DNS / 重導向檢查：所有輸入 URL 都被視為不可信輸入，重導向與 DNS 回答會被檢查，這減少了 SSRF 風險，但也意味著某些重導向鏈可能被截斷（若超出預設限制或被視為可疑）。
• 單一期限（deadline）與位元組 / 輸出上限：每個工具呼叫都有時間與大小限制，若內容超出上限，truncated 會標註為 true，結果為部分內容而非完整內容。這是安全設計，而非可調整的性能參數。
• 併發限制：預設限制控制同時執行的請求數，這避免了資源耗盡，但也意味著大規模批次操作需要分批執行，而非並行大量呼叫。
• 搜尋提供者預算（budget）：自動搜尋預設有保守的每月嘗試預算，這是防護機制而非計費依據，不應作為提供者帳單預測的依據。

實際操作建議：在設計自動化流程時，將這些限制視為「不可改變的邊界條件」，而非可透過參數調整繞過的限制。例如，若需要完整長內容，應設計流程在 truncated: true 時執行額外步驟（例如分段擷取或切換到更精確的選擇器），而非假設可以關閉大小限制。同樣地，若需要大量搜尋，應設計流程在預算接近時切換為單一提供者或減少查詢頻率，而非假設預算可無限擴展。

三工具組合的實際操作模式

基於篇 1 與本篇的內容，一個實際可行的操作模式（非唯一方案，而是基於目前可驗證功能的建議）：

1. 初步驗證：使用 web_search（自動模式）快速確認目標主題是否有足夠來源，觀察回傳中的提供者組合與來源證據欄位。
2. 內容取得：對確認的目標 URL 使用 web_fetch（format: markdown、render: never），驗證內容可直接取得且來源證據為 engine: http、backend: direct。
3. 結構化擷取：對已驗證的內容使用 web_extract（明確 CSS selector），驗證每個欄位對應正確節點、結果可逐行解釋、且無 truncated 或隱式填充問題。
4. 審計與重現：保存每次操作的參數組合與回傳結構（特別是 engine、backend、finalUrl、truncated、原始排名與 RRF 合併證據），這讓後續驗證與重現成為可執行的步驟，而非記憶或推測。

這個模式不假設未來功能（例如自動爬取、緩存感知路由、無限制預算），僅依賴目前可驗證的三工具合約與預設限制，因此可在 v0.1.0 版本下安全執行，並在未來版本更新時透過保存的參數與回傳結構進行對照驗證。

參考資料

• Groundlane GitHub 原始碼（v0.1.0 自述與文件結構） — 三工具合約、十適配器、雙認證機制、預設限制與預算語義
• Groundlane 產品說明與文件 — web_search 自動合併（兩提供者、RRF、canonical 去重）、web_fetch 格式與渲染策略、web_extract 確定性擷取
• .claude/skills/groundlane 技能（站內 MCP 工具路由）
• Groundlane 安全說明（SECURITY.md） — SSRF 風險、預設限制、私有漏洞回報