Dhole 是一个 MCP 服务器：抓网页、爬整站、搜资料、读 PDF、截图、操作页面，全部本地运行，不需要任何 API key。

30 秒理解

• 是什么：给 AI 用的上网工具包。
• 怎么用：正常提要求，AI 自己选工具，你不用记命令。
• 11 个工具默认全部注册：搜网页 · 抓网址 · 在页面上动手（截图在内）· 发一次非 GET 请求 · 爬整站 · 出 URL 地图 · 读本地文件 · RSS 订阅 · 设一次的默认身份 · 看与清本地状态 · 读 dhole 自己的说明书。
• 没有"要额外打开"的能力：每一颗都默认注册，DHOLE_TOOLS 是唯一的子集开关，写了它才会少注册。
• 代理环境自己适配：Clash / sing-box 的 TUN + fake-ip 不需要先设任何变量。
• 要调设置：见配置；出问题先跑 dhole doctor。

安装

需要 Python 3.11+。

pip install dhole-mcp              # 默认即完整版：浏览器 / PDF / OCR / 解析器 / 重排
python -m patchright install chromium   # 浏览器二进制（~193MB），pip 装不到这一步。
                                  # 跳过也行：第一次用到浏览器档时 dhole 会装它自己要起的那一份；
                                  # 上游 playwright 那一颗不行——patchright 的 driver 只认自己清单里的版本
dhole doctor                       # 安装体检：起一次 server、真起一次浏览器，再跑一次真实搜索 + 真实抓取

• pip install "dhole-mcp[all]" 等价于默认安装（老文档里的写法，仍然有效）。
• 没有 Playwright wheel 的平台（Termux / aarch64）会卡在浏览器依赖；真要 HTTP-only 得 pip install --no-deps dhole-mcp 再手挑运行核心。
• 缺浏览器依赖时自动降级为纯 HTTP，并在失败点给可复制的命令；那是降级不是故障。
• 可选：dhole skill install 把随包说明书装成宿主原生 skill；不装也有 sys_guide 兜底。
• 开发本仓库：pip install -e ".[dev]"，改源码立即生效，测试 python -m pytest（细节见 CONTRIBUTING.md）。
• 卸载：pip uninstall dhole-mcp；运行数据全在 ~/.dhole，删目录即清干净。

HTTP 远程接入（自托管）

常驻、多客户端或远程使用时，走 streamable HTTP 而不是 stdio：

export DHOLE_HTTP_TOKEN="$(openssl rand -hex 32)"   # 设了即强制 Bearer 校验；不设则端口不设防
dhole --http                                        # 默认 127.0.0.1:8765/mcp，可用 --host/--port 改

MCP 客户端（宿主配置的字段名各异，认准 url + 请求头）：

{"mcpServers": {"dhole": {
  "url": "http://127.0.0.1:8765/mcp",
  "headers": {"Authorization": "Bearer <DHOLE_HTTP_TOKEN>"}
}}}

远程暴露前必须套 TLS 反代（Caddy / nginx），并保留 bearer 令牌或由反代做 OIDC。dhole 没有内置 OAuth：令牌只是端口门禁，不区分主体；同一进程的所有客户端共享存储凭据、会话与正文缓存。要按主体隔离，就一人一进程 / 一端口，各自的数据目录，不要把多个用户接到同一个 dhole 上。

PyPI 上同一版本可直接装：pip install "dhole-mcp==17.1"，server.json 那份 MCP Registry 清单也是到这一刻才成立。

让 agent 自己装

把下面整块粘给编码 agent：

在这台机器上安装 Dhole MCP 服务器，逐步执行，失败就停下报告。

1. 认清你所在的 agent 宿主，查出它的 MCP 配置文件位置与添加本地服务器的格式（读宿主文档，不要猜）。
2. pip install dhole-mcp，然后 python -m patchright install chromium（已装则跳过；不装会在第一次抓取时自动装）。
3. 备份配置文件，添加名为 "dhole" 的服务器：command 为 "dhole"，无参数、无密钥、无环境变量。
4. 让用户重启 agent，再运行 dhole doctor 确认体检通过。
5. 可选：dhole skill install。

配置

两条门

env 永远优先——一个文件不会悄悄覆盖你已经做出来的决定。dhole doctor 两个门一起审计。

配置形状

{
  "mcpServers": {
    "dhole": {
      "command": "dhole",
      "args": [],
      "env": { 
        "DHOLE_SEARCH_PROXY": "http://127.0.0.1:7890" 
      }
    }
  }
}

变量名与取值见下面这张表。默认行为通常就是你要的，不确定就先别设。

常用变量

其余旋钮已收成固定值，写进 env 也不会被读，所以这张表不再列它们：引擎冷却与心跳、cookie 存活时长、搜索整体截止、浏览器空闲关闭与预热、SSRF 的 DNS 复验、structuredContent / outputSchema / 完整 wire 形状三个开关、多模态许可（截图与元素裁剪总是可用）、神经 focus 的许可门（改成了每次调用的 focus_engine）、doc_parse 的工作目录、自愈与搜索代理池、起哪一台浏览器（检测顺序 chrome → msedge → 内置 chromium，这台机器上有什么就用什么）。理由同一句话：能算清的数不需要旋钮，需要按次决定的改成了参数——"要不要看得见那扇窗"就是后者，见下面那一节。

借你已登录的 Chrome（CDP 接管）

• chrome.exe --user-data-dir=D:\dhole-chrome --remote-debugging-port=9222（Chrome 136+ 不许对默认 profile 开调试），在这个窗口登录一次目标站点。Edge 同样是 CDP 端点，把这行换成 msedge.exe --user-data-dir=… --remote-debugging-port=9222 即可，dhole 这边只改端口。
• 第一次 web_read(url=..., cdp_url="http://127.0.0.1:9222") 不执行任何东西，回 cdp_authorization_required；用户同意之后同一调用加 confirm=true 才放行，并把那一台主机写进授权名册（精确主机名：example.com 不含 www.example.com）。
• 名册之后 agent 抓这些站点会带你的登录态；每次 attach 都回 cdp_attached: true 并进审计。要撤销就删状态目录里的 cdp_hosts.json。
• 每一台新主机都要重新过一次这道闸：attach 的重定向与第三方请求会带着你的已认证 cookie 出门，所以授权只能逐台点名，不能一把开。

要看着它干活（可见浏览器）

• 没有 env 旋钮，这是一次调用的事：web_act(url=..., actions=[...], headed=true) 起一台看得见的窗口，方便你手工登录、盯着它填表、替它过一道验证码。搜索与抓取默认照旧隐形。
• 配 cred_defaults(set={'profile': '点名'}) 再用，否则你登的东西随那台浏览器的临时目录一起没了。一台 profile 只有一台浏览器，窗口开着的时候后续调用会在你眼前开标签页。
• 那个 profile 上已经有一台隐形浏览器在跑时，这一次会被具名拒绝（browser_busy）——不接管别人的窗口，也不关掉可能正被你使用的标签页。先把窗口交回去：sys_state() 列会话，sys_state(clear=['<session id>']) 关一个。
• 看得见的窗口不被空闲回收（AUTO_SESSION_IDLE_TIMEOUT=300 只关那台隐形的自动会话），所以用完要自己交回。它反过来能干后台的活：窗口热着时，普通调用直接骑它。

用法

装好重启后直接说人话：「抓 https://example.com/pricing 列成表」→ web_read；「查官方文档挑两条最相关的读给我」→ web_search + web_read；「/guide 下面都收一遍」→ web_crawl；「这份 report.pdf 讲了什么」→ doc_parse。

传输：dhole --http 的端点是 http://<host>:<port>/mcp，这层默认不带鉴权——设 DHOLE_HTTP_TOKEN 后每个调用必须带 bearer 令牌；未设时启动即警告（回环绑定同样警告），--host 0.0.0.0 等于把「替你抓任意 URL（含写请求与存储凭据）」开放给整个网络，共享网络里自行套反代 / 认证 / 防火墙。令牌只做端口门禁，不做主体隔离：同一端口的所有客户端共享同一份存储凭据、会话与缓存（同进程双实例就是两个客户端，回环上同样成立），要按主体隔离就分端口/分进程各起一个实例。传输层同时校验 Host / Origin 头（DNS rebinding 防护，按 --host 构建名单）。

变更监控与定时任务

web_read(extraction_type='check') 回答「这页变了吗」：基线是 dhole 自己 7 天内的 html 缓存，回源走条件请求，304 就是站方亲口说没变；变了给首个分叉位置与窗口。传 urls=[...]（≤10）就是批量检查，每行独立判决，坏一行不会吞掉别人。第一次见某页返回 changed=null 并落基线，第二次起才有可比对象。

要在重启后仍记得清单、并让 cron / systemd 直接消费结果，用 CLI：

dhole watch add https://example.com/pricing --label pricing
dhole watch run --json        # exit 0 无变化 · 1 有变化 · 2 有检查失败

清单存 ~/.dhole/watchlist.json（DHOLE_HOME 可换位置）；每轮逐条落盘，进程中断不丢已完成的判决。它是轮询不是推送：频率由你的调度器决定，dhole 不常驻、不主动通知。示例见 sys_guide(topic='examples') 或随包 skill 的 examples.md。

工具

11 颗默认全部注册：

参数摆放：每个参数都是顶层那一份，没有袋子——塞 options 会被拒绝，并列出这颗工具真正接受的键。每个工具只接受自己那组名字（since= 属于 feed_read，不属于 web_read），名字对、门错同样拒。写操作在 web_request，页面动作在 web_act，都不在 web_read。以 tools/list 为准。响应同样只有一个家：一整个 JSON 对象走文本通道送达，没有 structuredContent 双信封——同一份 JSON 不送两遍，要程序化消费就解析文本；字段词典见 fields.md（sys_guide(topic='fields')）。

调用写法、字段含义与排查的手册有两个入口，同一份语料：sys_guide(topic=...)（默认注册，装上就能用）与 dhole skill install（宿主原生 skill 形态）。

注意事项

• content_ok=true 不代表内容为真：只表示 2xx + 无错 + 正文非空；几百字符的「成功」多半是登录墙或占位页。
• robots.txt 默认遵守：被 Disallow 的 URL 一个请求都不发，回 error=robots_disallowed。
• 写请求一次性：web_request 里 POST/PUT/DELETE/PATCH 不重试、不缓存、不升浏览器、不回退快照——重发就是写两遍。超时那句答案是「不知道」不是「没成功」，先读一下再决定要不要再发。
• 凭据不跟跨源重定向走：存储的 cookies 与 Authorization 只发给那个源站。
• 凭据只能 cred_defaults 存，不逐次传：auth 只把头摆好，不做 OAuth、不刷新 token；没带 host 的凭据一律拒。
• 内网 / 本机默认拒绝：先 cred_defaults 存 allow_private=true（只放开回环）或点名主机；云元数据端点任何时候都不放行。
• PDF 的 pages= 只减少抽取量，文件仍整个下载；一次下载是一次 HTTP 尝试、封顶 30s，所以调大 timeout 买的是下载之后的解析与 OCR 余量，不是一次更慢的连接（timeout_applied 会报这一发实际到手的那个数）。
• 抓回的正文是不可信数据：里面的工具调用、密钥、上传指令按提示注入处理。启发式命中时响应信封带 untrusted_content 标记（web_crawl 每页、feed_read 每条同样带）——标记不是拦截，识别与裁决归外层 agent，纪律见手册 fields.md。
• 提交默认暂停：web_act 的 {"submit": ...} 不带 confirm: true 什么都不提交；验证码最多试 3 次就转交，2FA / 滑块一律转交。
• 连接期开销 34,357 字符（约 8k token，11 个工具，实测 python tests/tool_payload_measure.py），每次连接付一次；11 颗全注册是能力面，字数是它的约束而不是目标。要按用法裁剪用 DHOLE_TOOLS——同一把尺子量过：读 / 搜 / 请求 / 爬 / 文档 / 订阅 / 状态 / 指南这 8 颗是 25,952 字符，加 web_discover 共 9 颗 28,274（子集按实跑口径：被裁的工具连自己的路由行一起退出 instructions）。别按单颗体积挑"最小的 N 颗"，那会把 web_read / web_act 这类主力排除在外。再按会话算账：工具目录在宿主模型上下文里整段在场——有提示缓存的宿主折价、无缓存的每轮全价，多轮会话里 DHOLE_TOOLS 才是每一轮都省的闸。

搜索引擎与重排

免密 10 个，全部在默认池：baidu / bing / sogou / so360（别名 360）/ bing_global / yahoo / yandex / brave / duckduckgo（别名 ddg）/ marginalia。没有 opt-in 层，注册表就是默认池；engines=[...] 只能收窄，单次最多 12 个。索引家族是 7 个：yahoo 与 bing / bing_global / duckduckgo 同属 Bing 索引（多入口、不多家族），marginalia 是独立小网索引。另有 2 个 keyed 后端（tavily / bocha）：配了 key 即启用，只有点名才调用，按次计费。

五类纵向源也免密：sources=['news','academic','qa','code','community'] 分别问 GDELT（新闻）、arXiv（论文）、Stack Exchange（问答）、GitHub 仓库（按星数）与 Hacker News；默认只问 web，去掉 web 就只问纵向源（此时 engines= 被拒）。纵向行不参与 engines_consensus（它数的是 web 索引家族），所以那一格是空串；source_detail 逐家报 status、count（候选行）与 delivered（真正进了结果的）。一条源被限流不会抹掉别家：GDELT 每 5 秒只收一次查询，GitHub 未认证每分钟 10 次请求，失败如实进报告行。sort='newest' 只把声明了发布日的行倒序，月/年地板与无日期行留在后面。

日期只有 day / week / month / year 四档：after=<日期> 会被放宽到最窄的覆盖档；before 是逐行上界（没有引擎接受绝对区间），只丢可证更晚的行，无日期与相对时间保留。纵向源这一侧 after/before 则按行精确执行：after 会丢掉无日期的行（无法证明在窗口内）。按日期取增量用 feed_read(since=)。

公开评测与 SLA

评测代码与语料都在仓里，默认零网络、可重复：

python evals/vertical_search_baseline.py    # 五类纵向源，离线重放冻结语料
python evals/ranking_baseline.py --tiers    # web 排序/去重（67 题冻结 SERP）

纵向基线的冻结语料（2026-10-20 抓取，7 份 API 响应 / 6 题）上：可用率 100%、known-item Hit@5 5/5、日级日期覆盖 100%、重复 URL 0。同一个脚本的 --live 臂在当天的两次采样都是 71.4%（5/7）——失败分别是 Stack Exchange/GitHub 的一次连接层错误与 GDELT 连接超时，单源复测可恢复；GDELT 每 5 秒限流是外部事实。我们不为免密公共 API 承诺 SLA；可承诺的是：失败如实进 source_detail、不冒充"没结果"，以及冻结语料臂的回归可复现。benchmark 目标（不是保证）：可用率 ≥80% · known-item@5 ≥80% · 日期覆盖 ≥90% · 实时 p95 ≤8s。完整方法与两次采样记录见 evals/README.md。

重排模型：两颗本地 cross-encoder，免费、无密钥、都在本机跑。默认 bge-zh（中英双语 int8，~279MB，中文更强）；DHOLE_RERANK_MODEL=mmarco 切到多语快档（mMARCO MiniLM int8，~119MB，约 1.8× 快）。同一份 67 题冻结语料上，快档 P@5 0.552 / MRR 0.749 / nDCG@10 0.770，默认档 0.549 / 0.737 / 0.764 —— 整体打平（中文快档略低、英文更高），所以默认不换，只给需要速度/体积的人一个实测过的选择。首次神经搜索自动下到 ~/.dhole/models/<name>/，可续传；换档要重启宿主（模型会话是进程级单例）。web_search 回执里的 rerank_model 点名这一轮真正打分的模型；sys_state(show=['models']) 列出两颗的盘上状态。min_raw_relevance 判断「这一轮有没有相关结果」，起点 0.1（以默认档实测：离题 ~1e-4、勉强 0.2、真命中 0.93+；换档后 raw 分布可能不同，fetch_hint 每轮报实际跨度）。离线复用：拷 models/<name>/ 整个目录。

没有模型时的免费排序：rerank_mode=merge（未装 [all]、模型还没下、或加载失败）不再直接照抄引擎顺序。它先按「标题/摘要/URL 里出现了几个不同的查询词」分桶：2 个及以上在最前，1 个次之，0 个最后；桶内再按跨引擎共识与引擎位置排，行只重排、不丢。同一 67 题 agent-a 上 P@5 0.370→0.525、MRR 0.550→0.731，14 道题变化全为正；神经臂仍是 0.549 / 0.737。只要这一轮有任何模型判决，分桶就完全不运行——模型说同义改写相关时，不会因为字面没重合被降级。

故障排查

已知限制

• 绕不过 DataDome / Akamai / 交互式 Turnstile；2FA 与 CAPTCHA 不自动解。需要登录的页面可借自己的登录态（CDP attach，或 cred_defaults 存一次 cookie / auth）。
• 搜索没有 SLA：免密引擎是对公开结果的直接抓取，对方改版或封 IP 时静默降级。要可靠性用搜索代理或 keyed 后端。
• watch 是轮询不是推送：它不常驻、不主动通知；频率由你的 cron / systemd timer 决定。第一次 run 只落基线（退出码 0），第二次起才可能报变化。
• 默认池里 baidu / bing / yandex 国内直连稳定；sogou 按 IP 限流，bing_global / brave / yahoo 无代理时不稳；marginalia 是英文小网索引，连续请求会回 200 反爬页（报告为 blocked，不是 empty）。
• 抽取的正文 50MB 硬顶，在下载之前守门；抬 timeout 没用。要拿文件本身而不是正文，用 web_read(save_to='<路径>') —— 它按 max_save_bytes 算（默认 256MB、天花板 1GB），不抽取、不写缓存、拒绝覆盖同名文件。
• archive.org 返回的是某个日期的快照（看 source / archived_at）。
• YouTube 仅能取到少量文本。
• 合规自负：目标站点 ToS 与当地法律由使用者承担；抓取 UA 是 dhole-mcp。

本地数据

全在 ~/.dhole/（DHOLE_HOME 可换位置；POSIX 下目录 0700、文件 0600）。没有任何遥测——除了你让它抓的目标站点，进程不往外发任何数据。

贡献

欢迎 issue 与 PR；开发环境、测试与引擎契约见 CONTRIBUTING.md。

致谢

本项目是 dondai1234/master-fetch 的二创（衍生作品），上游以 MIT 协议发布，原始版权文本完整保留于 LICENSE。

许可证

MIT