Groundlane Series Part 5: Pitfalls and Best Practices — timeout, selector, render mode, version-change risk, and security boundaries

🌏 繁體中文版

This closing part converts the operational experience from the previous four parts into a reproducible checklist. Every item references an observable v0.1.0 behavior — from the self-described contracts, the default security limits listed as safeguards rather than tunable parameters, the provenance fields (finalUrl, engine, backend), and the fixed dual-auth mechanism — rather than a speculative future improvement. Where a recommendation depends on an unimplemented feature, it is explicitly labeled as not executable today.

The checklist structure (observable, executable)

Each checklist item follows the same structure to make verification executable: the observable trigger (what v0.1.0 behavior causes the pitfall), the verifiable evidence (which response field or document statement confirms it), and the executable action (what to do given the fixed boundary, without assuming it can be removed or tuned away).

Pitfall 1: truncated — treating partial retrieval as complete

• Observable trigger: The v0.1.0 self-description lists byte and output caps as default security limits (not configurable performance knobs). When web_fetch content exceeds these caps, truncated is set to true; the content field contains only the portion within the cap.
• Verifiable evidence: The response field truncated: true combined with finalUrl and engine/backend provenance. The cap applies regardless of render mode (direct HTTP or browser rendering) and is independent of URL complexity or page length.
• Executable action: Do not assume truncated can be removed by parameter adjustment. In any automated workflow, check truncated as a mandatory step. When true, treat the result as a partial sample: either use a more precise web_extract selector to target only the needed segment (reducing the likelihood of exceeding the cap), or document the limitation explicitly in the audit record (e.g. "partial retrieval — default byte cap applied; full content not verified"). Never present a truncated result as complete verification evidence.

Pitfall 2: render mode — switching to browser rendering without tracking provenance change

• Observable trigger: render: never produces engine: http and backend: direct; switching to render: auto or always changes backend to a rendering path (local Playwright or enabled Browserless), introduces rendering-time variability, and increases operational cost. The self-description confirms rendering is read-only, not interactive.
• Verifiable evidence: Compare engine and backend values between never and auto/always runs on the same URL. Also observe that rendering results depend on browser version, network latency, and dynamic page behavior — determinism decreases compared to direct retrieval.
• Executable action: Always run render: never first, preserving the engine/backend evidence (http/direct). Only switch to auto or always when the direct result is clearly insufficient (e.g. missing key content that requires JavaScript execution), and then record in the audit: source path changed (backend no longer direct), determinism risk increased, operational cost increased. Do not treat browser rendering as a default — it should remain an explicit fallback with documented provenance change.

Pitfall 3: selector errors — assuming the system will auto-correct DOM mismatches

• Observable trigger: web_extract relies solely on CSS selectors; there is no implicit model inference or auto-correction. If a selector does not match any node, the result is empty (null or empty structure) — not filled with a guessed value. The self-description confirms this is a design feature (determinism), not a failure mode.
• Verifiable evidence: A test call with a deliberately incorrect or overly broad selector returns empty or incorrect results without any hidden correction. The response contains no intermediate inference results — only the selector-matched values.
• Executable action: Before large-scale extraction, run a limited test with only the key selectors, preserving the selector-to-value mapping. If the test result does not match expectations (wrong nodes matched, or zero matches), adjust the selector — do not assume the system will fix it. For pages with known DOM instability (e.g. dynamically generated content, frequent redesign), document in the audit: selector results depend on current DOM structure; future changes may alter results. Never fill empty results with default values — an empty match means the field is absent in the current page, which is verifiable information, not an error.

Pitfall 4: automatic search merge — misreading multi-source provenance as single-source quality

• Observable trigger: Automatic web_search selects up to two complementary providers from the enabled set, applies RRF merge, and retains per-provider original rank evidence. The final merged order is not the same as any single provider's original ranking.
• Verifiable evidence: The response includes engine, backend, original rank per source, and the final merged rank. Comparing automatic results with a single pinned provider (tavily or exa only) shows different provenance and sometimes different ordering.
• Executable action: When using automatic mode, record the full provenance chain in the audit: which providers were selected, their original ranks, the RRF-merged final order, and any canonical deduplication evidence. Do not interpret the final merged rank as "this provider's quality" — it reflects the merge algorithm, not a single source's performance. When precise provider traceability is required, switch to an explicit provider parameter (single or specified list) and document the change.

Pitfall 5: version-change risk — operating without reproducible audit records

• Observable trigger: v0.1.0 is explicitly marked as an early preview with no stable contract guarantee. The docs/ and README reference future directions (compatibility fixtures, cache-aware routing, bounded crawl primitives) as "Next," not current features.
• Verifiable evidence: The version label in the repository (0.1.0), the self-description's preview warning, and the absence of features like automatic crawl or interactive browser control in the current docs.
• Executable action: For every workflow step, preserve the parameter set and the response structure snapshot (especially engine, backend, finalUrl, truncated, original and merged ranks, selector-to-value mappings). When updating to a future version, re-run the same parameter set and compare against the preserved snapshot. If differences appear (new fields, changed limit semantics, different provenance labels), update the workflow description rather than assuming backward compatibility. Never assume future capabilities (automatic crawl, expanded interaction, unlimited budgets) without direct verification from the updated source and docs.

Pitfall 6: security boundaries — attempting to bypass fixed limits

• Observable trigger: The default limits (URL policy, DNS/redirect inspection, single deadline, byte/output caps, concurrency limits, conservative monthly search budget) are described as safeguards in both the self-description and SECURITY.md. They are not listed as configurable parameters in the current docs.
• Verifiable evidence: There is no parameter (e.g. unlimited, no_deadline, infinite_budget) in the v0.1.0 contract that disables these limits. Attempts to exceed them result in truncated: true, timeout errors, or budget-related restrictions — not in successful unbounded execution.
• Executable action: Design workflows within these boundaries: for long content, plan for truncated checks and segmented retrieval (e.g. more precise selectors rather than full-page retrieval); for high-frequency search, monitor budget proximity and switch to single-provider or lower-frequency modes when needed; for concurrent operations, stage them rather than attempting full parallelization. Document these boundary-handling steps in the audit record, confirming that the workflow operates within the fixed security limits rather than attempting to bypass them.

Pitfall 7: in-site identity boundary violations — embedding secrets or assuming fixed paths

• Observable trigger: The .claude/skills/groundlane usage-modes.md explicitly requires: no embedded bearer tokens or expanded authorization headers; no fixed clone paths (use <groundlane-clone> and <deployment> placeholders); web-hosted agents must use registered remote endpoints (https://deployment>/mcp) rather than assuming localhost access; deprecated stealth_fetch must never be used.
• Verifiable evidence: Any file or prompt containing a hardcoded token, a fixed absolute clone path, or a stealth_fetch call violates the observable contract. The skill's judgment flow requires runtime verification (tool provenance check) rather than assumption.
• Executable action: In all in-site integration descriptions and audit records, use abstract identifiers (groundlane-clone>, <deployment>); verify the contract at runtime (mcp__groundlane__* with the full three-tool schema); if unavailable, label the fallback clearly (e.g. "environment's actual retrieval tool — not Groundlane, not deprecated stealth_fetch"). Never include bearer tokens, provider keys, or expanded headers in skills, prompts, notes, logs, or version-controlled files. Confirm that remote endpoint access is registered with managed connector storage when applicable.

Pitfall 8: reproducibility failure — operating without preserved parameters and results

• Observable trigger: The v0.1.0 preview status and the absence of automatic crawl or cache-aware routing (listed as future directions) mean that any workflow relying solely on memory or abstract descriptions cannot be verified after an update.
• Verifiable evidence: A workflow without preserved parameter snapshots (format, render, provider settings, selectors) and response snapshots (engine, backend, finalUrl, truncated, matched nodes) has no reproducible baseline for version comparison.
• Executable action: Preserve, for each significant step: (a) the exact parameter combination, (b) the expected response structure (key provenance and determinism fields), (c) the actual response summary or snapshot, and (d) the execution environment (local vs. remote endpoint, tool availability status). On version updates, re-run the preserved parameter set and compare results. Update the workflow description only when the comparison confirms consistent behavior; when differences appear, document them explicitly rather than assuming continuity.

Closing checklist (reproducible action pattern)

The series' shared principle — verifiable source references, observable contracts, no unimplemented assumptions — applies to this closing part as well. The checklist below is executable now (all items reference v0.1.0 observable behavior) and serves as the reproducibility baseline for future updates:

• Confirm truncated is checked in every web_fetch workflow; partial results are labeled, not treated as complete.
• Confirm render mode is documented with provenance change (engine/backend shift) and determinism/cost impact.
• Confirm web_extract selectors are preserved with node mappings; empty matches are labeled as "field absent," not filled implicitly.
• Confirm web_search automatic results include provider provenance (original ranks, RRF merge, canonical dedup) before interpretation.
• Confirm version-change verification uses preserved parameter and result snapshots; differences are documented, not ignored.
• Confirm all security limits (URL policy, deadline, byte/output caps, concurrency, budget) are treated as fixed; workflow handles them rather than attempting to bypass them.
• Confirm identity boundaries are maintained: no embedded secrets, abstract endpoint identifiers (deployment>), runtime contract verification (mcp__groundlane__* schema), deprecated-path exclusion (stealth_fetch never used), and clear fallback labeling when Groundlane is unavailable.
• Confirm every workflow step can be traced back to the v0.1.0 observable contracts and docs; no step relies on unimplemented future features (automatic crawl, interactive rendering, unbounded budgets, or cache-aware routing).

This checklist closes the series with the same principle established in Part 1: technical descriptions trace to verifiable source and docs; in-site applications rely on observable skills and contracts; any expectation beyond the current preview should be verified against the official documentation and source at that time, not taken from this series as a promise.

References

• Groundlane GitHub source (v0.1.0 self-description) — observable contracts, provenance fields (finalUrl, engine, backend), version preview warning
• docs/configuration.md — the fixed environment-variable limits behind Pitfalls 1, 6, and 8 (REQUEST_TIMEOUT_MS, MAX_RESPONSE_BYTES, MAX_OUTPUT_CHARS, MAX_CONCURRENCY, MAX_QUEUE)
• SECURITY.md — the URL policy, DNS/redirect inspection, and auth boundaries cited as safeguards, not tunable parameters
• .claude/skills/groundlane skill and usage-modes.md — judgment flow, deprecated-path exclusion, identity boundary rules, shareability requirements
• Previous series parts (Parts 1-4) — shared verifiable baseline, contract definitions, comparison dimensions, in-site workflow steps