用途
Groundhog 是面向 AI 智能体和爬虫的安全、自托管网页 grounding 工具，形式是一个 MCP 服务器。它通过真实、经过 stealth 补丁的 Chrome 浏览器，为智能体提供三类能力：网页搜索、页面读取和跨源研究，返回模型可以信任的干净 Markdown。
主要能力
隐藏文本剥离：Groundhog 渲染真实 DOM，可以评估计算样式，判断真人能看到什么，并在默认情况下剥离真人看不到的文本，每次剥离都在 threats 中报告其信号类型和简短摘录。它识别十二类信号，包括 display:none / visibility:hidden、content-visibility: hidden、opacity ≤ 0.05、字号小于 4px、零尺寸元素、display: contents 且内容不渲染、.sr-only / .visually-hidden 类的亚像素盒子、遗留的 clip: rect(...)、完全透明文字色、文字色与背景色接近 1:1 对比、被定位到渲染页面之外的元素（如 left: -9999px），以及浏览器布局但拒绝渲染的内容（如折叠的 <details>）。此外还剥除字符级隐藏内容：零宽字符、双向标记与 RTL 覆盖、以及 Unicode Tag 块（不可见 ASCII 镜像，是典型的提示注入走私渠道）。非平凡的 HTML 注释和 <template> 内容也会被报告。alt、aria-label、aria-description、title 属性中的文本会从标记中清除并在超过长度阈值时报告。
溯源凭证：每个来源都附带凭证，包括抽取内容的 SHA-256 哈希、规范 URL、语言、字数，以及页面声明时的作者/日期，使下游断言可追溯到确切读到的内容。read_url 还会返回 fetched_at 抓取时间。
安全默认：SSRF 防护在导航前解析每个主机，拒绝返回重定向到私有地址的 URL 内容。只读，带按域名限速。在研究场景中更重要，因为 URL 由第三方选择。
反自动化检测：Puppeteer/Playwright/Selenium 会启用 CDP 的 Runtime 域，可被反机器人检测（isAutomatedWithCDP）。Groundhog 通过原始 CDP 驱动浏览器，从不启用 Runtime / Console，因此该信号不存在。
真实指纹：使用真实 Chrome，具备真实的 TLS/HTTP2 指纹和真实 WebGL/canvas，而非 Python HTTP 客户端，因此指纹驱动的封锁会消失，廉价代理也能在其原本无法使用的地方工作。
无模型、无 API 密钥：research 返回抽取片段而非摘要，由调用方智能体进行综合。自托管且为 MIT 许可，抓取的页面不离开用户基础设施。
使用方式
添加到 MCP 客户端：在 Claude Desktop / Cursor / Windsurf（claude_desktop_config.json 或等价配置）中添加 Groundhog，首次抓取时 Groundhog 会启动本机已有的 Chrome，以 headless 模式运行在 ~/.groundhog/chrome 的独立配置文件中：无需 Docker、无需检出仓库、无窗口，因此工作时不会抢占焦点。它会在下次抓取时保持运行。Chrome（自 136 起）拒绝远程控制日常配置文件，因此用户自己的浏览、标签页和登录不会被触碰。
偏好加固浏览器时，设置 GROUNDHOG_BROWSER=stealth 会拉取并启动 stealth-browser 容器（需要 Docker 或 Podman）。该路径运行时会先移除名为 groundhog-browser 的陈旧容器；可访问的浏览器永不被触碰。
uvx 会在首次运行时从 PyPI 获取 groundhog-mcp。首次抓取会拉取浏览器镜像（一次，几分钟）；之后的抓取是即时的。没有容器运行时？状态工具和任何错误都会说明如何安装——或者将 CDP_URL 指向托管浏览器以实现零安装使用。
自行管理浏览器：启动它，Groundhog 会直接使用。设置 GROUNDHOG_AUTO_START_BROWSER=false 可禁用自动启动。从源码运行 MCP 服务器：cd mcp && uv sync && uv run groundhog-mcp。
使用任意 CDP 浏览器：CDP_URL 接收浏览器给出的地址并完全按给定使用。http:// 地址会被探测 /json/version；ws:// 或 wss:// 地址（托管浏览器给出的，常在查询中带密钥）则直接连接。自动启动只会在本地地址无响应时运行，因此 CDP_URL 指向的浏览器由用户自行管理。status 报告地址时会省略查询和凭证。
四个工具均标注 readOnlyHint，这使客户端无需每次调用确认即可运行。它们对数据只读：不写入任何内容，不改变远程状态。唯一例外：自动启动开启时，首次调用可能在 Groundhog 自己的配置文件中启动 Chrome——或在 GROUNDHOG_BROWSER=stealth 时拉取并运行浏览器容器，并先移除不可达的 groundhog-browser 容器。可访问的浏览器永不被触碰，GROUNDHOG_AUTO_START_BROWSER=false 可完全关闭该路径。
工具说明
read_url(url, format="markdown", max_tokens=None, query=None, include_hidden=False)：抓取页面并返回干净内容加溯源。传入 include_hidden=True 可保留被剥离文本，threats 仍会填充。每页最多返回 50 条发现（research 中每源 10 条），超出会追加 report_truncated 说明丢弃数量，不静默截断。两类发现独立设上限。传入 query 可用相关性排序的段落选择替代粗暴的头部截断：内容按 Markdown 结构分块，按词法（BM25）相关性排序，返回得分在最佳一半以内的段落，直到 token 预算。matches 给出每段标题、字符偏移和分数用于下游引用，set_aside 统计被阈值丢弃的评分段落。排序在净化后的内容上运行，因此隐藏文本注入载荷无法影响哪些段落浮现（include_hidden=True 除外）。
search(query, limit=10)：为查询查找页面并返回排序命中——title、url、snippet、engine、score、published——以及响应的后端。命中仅是链接：在将 URL 传给 read_url 前不会抓取任何内容。两种后端自动选择：设置 SEARXNG_URL 使用自己的 SearXNG 实例（最佳结果，需在其 settings.yml 中启用 formats: [html, json]）；未配置实例时，Groundhog 通过 stealth 浏览器渲染搜索页。用 GROUNDHOG_SEARCH_BACKEND=searxng|serp 强制。命中的所有文本字段都可能受攻击者影响，因此经过与页面内容相同的不可见字符剥离并做长度限制。URL 从不被改写；若清理会改变 URL、URL 非 http/https、携带凭证或超过 2048 字符，则该命中被直接丢弃。
research(query, max_sources=5, max_tokens=None)：一次调用完成“查找关于 X 的信息”：搜索、通过 stealth 浏览器读取顶级来源、返回与 query 最相关的段落，跨所有来源单次排序。返回 passages（各含 text、source_url、heading、score）和 sources（各含 url、title、status、page_status、threats、provenance）。status 是抓取结果（ok/blocked/timeout/error）；page_status 是已加载页面实际是什么，抓取未产生页面时为 null。page_status 表明正文是插页或错误页的来源不贡献段落，但仍出现在 sources 中说明原因。每个可注册域名最多一页以保证来源多样性。段落是抽取而非摘要。某来源失败不会使调用失败，会以 blocked/timeout/error 出现在 sources 中。max_sources 上限为 10。由于搜索结果由第三方选择且 SEO 投毒是已记录的真实攻击，每个抓取 URL 都经过与 read_url 相同的 SSRF 防护和隐藏文本剥离。失败来源的 provenance 为 null。threats 每源上限 10 条。它比基于 API 的研究工具慢：真实浏览器渲染每个来源，这是读取会拦截普通抓取器的页面并告知其中隐藏内容的代价。
status：报告 Groundhog 能否到达 stealth 浏览器，返回 browser_reachable、cdp_url，以及不可达时的修复提示。端点仅以 scheme、host 和 port 报告。
适用场景
适合需要安全、自托管网页 grounding 的 AI 智能体与爬虫场景，尤其是页面会拦截普通抓取器、需要判断页面是否隐藏了提示注入内容、以及需要可追溯来源凭证的研究任务。
限制
隐藏文本检测是强启发式而非证明；共享和 service worker 未被覆盖。stealth 镜像在 Xvfb 下以 headful 模式运行 Chrome。没有容器运行时可指向托管浏览器。threats 条目应视为不可信。research 比 API 驱动工具慢。其他具体未提及的收费、价格、平台或效果信息暂未提供。
