Groundlane 實戰系列（篇 5）：踩坑與最佳實踐 — timeout、selector、render 模式與安全邊界

🌏 English version

這篇不重複前四篇的內容（概念、工具實戰、傳統對比、站內應用），而是把實際操作中最容易出錯的點整理為可執行的檢查清單。每條建議均可追溯至 v0.1.0 目前可驗證的行為（自述、文件結構、預設限制、安全說明），而非推測未來改進。若某項建議依賴未實作功能，會明確標示為「目前不可執行」而非建議執行。

操作陷阱清單（可驗證，每項有依據）

以下為實際操作中最常遇到的問題，按工具與維度分類。每項都包含「為什麼發生」（依據可驗證行為）與「可執行的處理方式」（依據同樣可驗證的邊界與流程）：

1. web_fetch 的 truncated（內容被截斷）

• 為什麼發生：v0.1.0 自述明確提到預設的位元組與輸出上限是安全邊界（非可調整參數）。當目標內容（特別是長文章、完整文件、包含大量圖片或表格的頁面）超出上限時，回傳的 content 為部分內容，truncated 設為 true。這不是錯誤，而是確定性邊界的可驗證表現。
• 可執行的處理方式：不要假設 truncated: false 永遠成立。在設計自動化流程時，將 truncated 檢查作為必須步驟：若為 true，則結果為部分內容，後續步驟（例如結構化擷取、內容引用、參考驗證）應標示為「基於部分內容」，而非假設為完整內容。同時，不要嘗試「關閉」或「繞過」該上限（依據安全說明，這些限制為固定邊界，不可繞過）；若需要完整長內容，應考慮分段檢索（例如針對特定區段執行更精確的選擇器擷取，而非依賴完整頁面擷取），或在驗證記錄中明確說明截斷限制。

2. web_fetch 的 render 模式切換（成本與確定性風險）

• 為什麼重要：render 參數（never、auto、always）直接影響兩個可驗證的結果：來源證據欄位（engine、backend 會從 direct 變為瀏覽器路徑）與操作成本（瀏覽器啟動與渲染時間增加，且結果受瀏覽器版本、網路延遲、頁面動態行為影響，確定性降低）。篇 2 已詳細說明這些差異，此處重申為操作檢查點。
• 可執行的處理方式：在任何自動化流程中，先執行一次 render: never 的測試，保存 engine 與 backend 的結果（應為 http 與 direct），並確認內容完整性（truncated 狀態）。僅當直接路徑的內容明顯不完整或缺少關鍵部分時，才切換為 render: auto（或 always，若明確需要渲染），並在驗證記錄中標註：來源已切換為瀏覽器路徑（backend 不再為 direct），操作成本增加，確定性降低（因渲染結果受環境影響）。不要在未驗證直接路徑結果的情況下直接使用 render: always，因為這會增加確定性風險與維運負擔，且來源證據會變得複雜（難以區分直接讀取與渲染結果的差異）。

3. web_extract 的選擇器設計錯誤（確定性依賴 DOM 穩定性）

• 為什麼重要：web_extract 的確定性完全依賴 CSS selector 與目標 DOM 結構的一致性。若選擇器設計不精確（例如過於寬泛的選擇器匹配到不相關節點，或過於嚴格的選擇器在 DOM 微調後無匹配），結果要麼包含錯誤內容，要麼為空（無匹配節點）。這不是系統錯誤，而是確定性設計的可驗證特性：系統不會自動修正選擇器，也不會對無匹配結果進行隱式填充。
• 可執行的處理方式：在正式大規模擷取前，執行小範圍測試（僅關鍵欄位的選擇器），保存每個欄位的選擇器與回傳節點值，並驗證：選擇器匹配的節點是否與預期一致（例如 h1 是否對應標題、.version 是否對應版本號，而非廣告或導航元素）；若目標頁面的 DOM 結構已知可能變化（例如網站改版、內容動態生成），則應在驗證記錄中標註：選擇器結果依賴當前 DOM 結構，未來變更可能導致結果變化。同時，若測試結果為空（選擇器無匹配），不要假設為「系統未找到欄位」而自動填充預設值；應明確標示為「該欄位在當前頁面中不存在（選擇器無匹配）」，並在後續步驟中處理該缺失（例如跳過該欄位、使用其他來源驗證、或標示為未驗證狀態）。

4. web_search 的自動合併結果解讀錯誤（提供者組合與 RRF 邏輯）

• 為什麼重要：自動搜尋（無明確提供者參數）的預設行為是：從已啟用的提供者中選擇最多兩個互補來源，執行 RRF 合併，並保留各提供者的原始排名與最終合併排名。這意味著回傳結果中會包含多個來源的證據欄位（engine、backend、原始 rank、合併後的最終順序），而非單一來源的簡單列表。若解讀時忽略這些多來源證據（例如僅看最終合併排名而不檢查原始來源），可能誤判結果的來源與確定性（例如將合併後的高排名誤認為單一提供者的高品質結果）。
• 可執行的處理方式：在使用自動搜尋結果時，保存並檢查每個結果的來源證據：哪些提供者被選中（可從回傳結構中確認）、每個提供者的原始排名為何、合併後的最終順序如何、canonical 去重是否生效（同一內容是否僅保留一個代表性結果）。若需要精確追蹤某提供者的行為（例如驗證特定搜尋引擎的回傳品質），則應切換為明確提供者參數（單一或明確列表），避免自動合併邏輯的干擾。同時，不要假設自動模式永遠選擇相同的提供者組合——提供者可用性與路由邏輯可能隨配置與網路狀態變化，因此每次執行都應保存實際選中的提供者組合作為驗證證據。

5. 版本變動風險（v0.1.0 早期預覽的可重現驗證方式）

• 為什麼重要：v0.1.0 自述明確標註為「early preview；no stable tool-contract guarantee yet」。這意味著未來版本可能修改工具合約（參數結構、回傳欄位、預設限制語義）、增加新功能（例如自動爬取、緩存感知路由、互動式瀏覽器控制）、或調整安全邊界。若操作流程依賴未來承諾（例如假設某功能將在下一版本實現），則在版本更新時無法驗證流程是否仍然有效。
• 可執行的處理方式：對每個操作步驟（參數組合、預期回傳結構、確定性證據欄位、限制邊界），保存可驗證的記錄（例如參數 JSON、回傳結構快照、finalUrl、engine、backend、truncated、選擇器與節點值）。當版本更新時，重新執行相同參數組合，對照保存的記錄與新回傳結構，驗證：合約是否一致（參數結構、欄位名稱）、確定性證據是否仍可解釋（engine/backend 標註是否仍明確）、限制邊界是否仍為固定安全邊界（而非可調整參數）。若對照顯示差異（例如新欄位出現、預設限制語義變化、確定性來源標註方式改變），則應更新操作流程與驗證記錄，而非假設「舊流程仍適用新版本」。同時，在所有應用說明中明確標註：本描述基於 v0.1.0 可驗證範圍，未來版本應重新驗證（依據官方文件與原始碼更新）。

6. 安全邊界不可繞過（預設限制的固定性與意義）

• 為什麼重要：自述與安全說明明確列出預設限制（URL 政策、DNS / 重導向檢查、單一期限、位元組與輸出上限、併發限制、搜尋預算）為「安全邊界」而非「可調整性能參數」。這意味著：這些限制不可透過參數修改繞過（例如無法設定「無上限」或「無期限」）；若操作需要超出這些限制（例如完整長文擷取、大量並行搜尋、無預算限制的自動合併），則必須在流程設計中處理這些限制（例如分段檢索、批次執行、預算監控與切換），而非假設可以關閉限制。
• 可執行的處理方式：在設計任何自動化流程時，將這些限制視為「不可改變的邊界條件」：若內容可能超出位元組上限，流程必須包含 truncated 檢查與後續處理步驟（例如更精確的選擇器、分段檢索、手動審查截斷內容）；若搜尋頻率可能接近預算限制，流程必須包含預算監控（例如切換為單一提供者、減少查詢頻率、或標示為預算接近時的操作限制）；若需要大量並行操作，流程必須分批執行（受併發限制控制），而非假設可無限並行。同時，在所有操作說明中明確標示：這些限制為安全邊界（依據 SECURITY.md 與自述），不可繞過，操作流程必須在這些邊界內設計與執行。

7. 站內應用的身份邊界與可分享性（憑證與路徑管理）

• 為什麼重要：站內 usage-modes.md 明確要求：憑證（GROUNDLANE_AUTH_TOKEN、提供者金鑰）不得寫入文件、設定、對話或版控；路徑必須使用抽象標識（<groundlane-clone>、<deployment>）；Web-hosted agent 必須使用已部署的遠端 endpoint（https://<deployment>/mcp），而非假設可連本機 localhost。若應用流程違反這些要求（例如在文章或腳本中嵌入明文 token、假設固定本機路徑、未標示遠端與本機差異），則身份邊界被破壞，可重現性與可分享性降低，且安全風險增加（例如 token 洩露、路徑依賴導致流程在不同環境失敗）。
• 可執行的處理方式：在所有站內應用文件與流程描述中，使用抽象標識（不寫個人路徑或私人 endpoint）；不在任何文件、腳本註解、設定檔或對話中包含憑證（包括展開後的 Authorization header）；明確區分本機與遠端執行環境（例如「本機模式使用 localhost:8080/mcp，遠端模式使用已部署的 HTTPS endpoint」），而非假設所有環境都可連同一 endpoint。同時，在驗證記錄中不包含憑證（僅包含工具使用與回傳結構的確定性證據），確保驗證結果可在不同環境重現（不依賴特定憑證或路徑）。

8. 操作流程的可重現性驗證（保存參數與結果）

• 為什麼重要：由於 v0.1.0 為早期預覽，合約與限制可能隨版本變化。若操作流程僅依賴記憶或抽象描述（而非保存的參數與結果），則在版本更新後無法驗證流程是否仍有效（例如參數結構是否變更、回傳欄位是否新增或移除、預設限制語義是否調整）。
• 可執行的處理方式：對每個操作步驟（特別是涉及參數組合、預期回傳結構、確定性證據欄位的步驟），保存可驗證的記錄：參數組合（例如 format: markdown、render: never、選擇器結構）、預期回傳結構（例如 finalUrl、engine、backend、truncated、選擇器與節點值）、實際回傳結果（或摘要與確定性欄位）、執行時間與環境（本機或遠端、工具可用性狀態）。當版本更新時，重新執行相同參數組合，對照保存記錄，驗證差異（若有），並更新流程說明。這讓操作流程成為可重現的實驗，而非依賴記憶或推測的習慣。

最佳實踐總結（簡要可執行清單）

基於前四篇與本篇的內容，以下為可直接執行的操作檢查清單（每項均可驗證，無假設功能）：

• 在任何 web_fetch 操作前，先執行 render: never 測試，保存 engine 與 backend（應為 http 與 direct），並檢查 truncated 狀態。
• 僅在直接路徑內容明顯不完整時切換為 render: auto（或 always），並在驗證記錄中標註來源已切換為瀏覽器路徑（backend 不再為 direct），成本與確定性風險已增加。
• 對 web_extract 操作，保存明確選擇器結構與每個欄位的節點值；若選擇器無匹配，明確標示為「欄位不存在（無匹配）」，而非隱式填充預設值。
• 對 web_search 自動合併結果，保存實際選中的提供者組合、原始排名與 RRF 合併證據；若需要精確追蹤，切換為明確提供者參數（單一或列表），避免自動合併邏輯的干擾。
• 對所有操作，將預設限制（位元組與輸出上限、單一期限、併發限制、搜尋預算）視為固定安全邊界（不可繞過）；設計流程時包含對這些邊界的處理步驟（例如 truncated 檢查、批次執行、預算監控與切換）。
• 對所有站內應用，遵守身份邊界規則（不嵌入憑證、不假設固定路徑、使用抽象標識、遠端與本機差異明確標註）與淘汰工具排除（不使用 stealth_fetch 或 web-fetch/fetch_page）。
• 對每個操作步驟，保存參數與結果記錄（確定性欄位為重點：finalUrl、engine、backend、truncated、選擇器與節點值）；在版本更新時重新執行驗證，對照差異並更新流程說明。
• 在所有應用與驗證說明中明確標註：本描述基於 v0.1.0 可驗證範圍，未來版本應重新驗證（依據官方文件與原始碼更新），且未引入任何未實作功能（自動爬取、緩存路由、互動式瀏覽器控制、無限制預算等）。

這些實踐不是「最佳化建議」，而是基於可驗證邊界的操作規則：它們確保每個步驟可重現、每個限制可解釋、每個差異可驗證，並在版本變化時提供可執行的對照機制。

參考資料

• Groundlane GitHub 原始碼（v0.1.0 自述與安全說明） — 預設限制語義（安全邊界而非可調參數）、預算語義（防護而非計費）、版本標註（早期預覽、無穩定合約保證）
• Groundlane 安全說明（SECURITY.md） — SSRF 風險、預設限制的安全設計意圖、身份邊界與憑證管理要求
• .claude/skills/groundlane 技能與 usage-modes.md — 工具判斷流程、身份邊界、淘汰工具排除、可分享性要求、遠端與本機差異
• 前四篇文章（篇 1 概念、篇 2 工具實戰、篇 3 傳統對比、篇 4 站內應用）— 可驗證的操作步驟與確定性證據欄位定義，作為本篇實踐的依據