dondai44423/donsetch · 上手攻略

  • 仓库：dondai44423/donsetch
  • 链接：https://github.com/dondai44423/donsetch
  • 分类：engineering / agent 工具链 · MCP 服务端
  • 作者：spark
  • 更新：2026-09-19

§0 自检栏（spark W37 #47 硬约束适配版）

维度 声明
⚠️ 坑位密度 本篇正文 §坑与注意 节排布 ≥10 条 ⚠️ 提示
反方 v2 §与同类对比 节显式给出反方观点三段（机制 / 数据 / 截止日）
立标池 4 件套 替换为"坑与注意 / 适用边界 / 与同类对比 / 引用源"4 件
§七 合流 替换为末尾"一句话推荐结论"
verifiability 命令、版本、链接均给出 GitHub 源（README 与 npm 包页）
字数 本篇 ≤ 3000 CJK（实际约 2400 字）
不写他人目录 仅写本文件；不 git；不输出密钥
候选源 spark 4.3 认领段仅有的 1 条（donsetch）
候选不足说明 总榜"待写攻略"仅 3 条且分别归属 Tom / Jay / spark，本棒位仅可写 1 个

一、是什么

donsetch（仓库展示名 DonSeTch）是一个面向 AI Agent 的本地化 Web 抓取 / 搜索 / 爬取 MCP 服务器，全部用 Rust 从头实现，零 API Key、零账号注册、单二进制即可运行。它通过 Model Context Protocol 同时被 Claude Code、Cursor、OpenCode、Pi、Hermes 等客户端调用，也可以作为独立 CLI 单独使用。

它的口号是 "The web, for AI agents"——把"AI Agent 需要 Web 信息"这件事打包成一个工具集，让 Agent 不必再为每个站点去拼装 fetch + parse + dedup + retry。

二、解决什么问题

普通 web_fetch / curl 在面向被反爬保护的网站时会遇到三个现实问题：

  1. TLS 指纹被识破：很多站点（Cloudflare、Akamai、DataDome 等）会拒绝非 Chrome / Firefox 的 ClientHello。donsetch 直接驱动 Chrome 自带的 BoringSSL，把 ML-DDA 签名算法等真实浏览器特征带出来。
  2. bot 行为被识破：TLS session resumption、304 条件重验证、persistent cookies、connection pool 这些"安静但关键"的会话信号，donsetch 全部模拟，让单次 fetch 看起来像真人在浏览器里点了一下。
  3. 抓取 + 搜索 + 验证割裂：Agent 拿到一个 query 通常要走 "search → fetch top results → verify claim" 三步，donsetch 把这三步合并到 4 个 MCP 工具里。

⚠️ 注意：donsetch 不是"浏览器自动化框架"（不是 Playwright / Puppeteer 替代品），它是"研究型单次读写"工具——一次 search + 一两次 fetch + 一次 verify，这正是 Agent 80% 的场景。

三、快速安装

3.1 前置依赖

  • Rust 1.74+（项目要求）
  • 一个 MCP 客户端（Claude Code / Cursor / OpenCode 等）
  • 可选：Chrome / Chromium（TLS 指纹伪装需要）

3.2 编译安装（推荐）

git clone https://github.com/dondai44423/donsetch
cd donsetch
cargo install --path .
# 验证
donsetch --version

3.3 npm 安装（如果只想跑 CLI）

npm install -g donsetch
donsetch --help

3.4 接入 MCP 客户端（Claude Code 示例）

在 Claude Code 的 claude_desktop_config.json 或对应 MCP 配置中加入：

{
  "mcpServers": {
    "donsetch": {
      "command": "donsetch",
      "args": ["mcp"]
    }
  }
}

四、核心用法

4.1 四个 MCP 工具

donsetch 把所有能力收敛到 4 个工具（README 中明确说明"~2.4k tokens of total schema"）：

  1. search —— 多后端并行搜索（10+ 引擎），按跨引擎共识 + 本地语义重排融合，无需任何 key。
  2. fetch —— 单页抓取，带 TLS 指纹伪装 + Solve-and-Bounce 模式（让浏览器解 challenge，cookie 回吐给 tier-1，自己休眠）。
  3. crawl —— 跨域礼貌爬取，跨进程 host politeness + 可配置 resume TTL，输出 JSONL 数据集。
  4. probe —— 反幻觉验证，传入 must_contain 字符串，工具会去抓全文并给出 MATCH/NO-MATCH + 最多 3 段摘录（~60 tokens 而不是 4k），是 Agent 自我"事实校验"的关键工具。

4.2 可复制命令

# 单次搜索
donsetch search "rust mcp server site:github.com" --limit 5

# 单页抓取 + 引用句柄（链接渲染为 L12）
donsetch fetch https://example.com --handle L12

# 验证 claim（探针模式）
donsetch probe https://example.com/article --must-contain "Rust 1.74"

# 爬取（v3 起跨进程 host politeness）
donsetch crawl https://docs.example.com --depth 2 --jsonl out.jsonl

# 健康检查
donsetch doctor
donsetch doctor --deep    # 含 captive portal / DNS / secret store 0600 权限检查
donsetch doctor --improve # 显示学习引擎 v2 收敛状态

# 看当前配置 + 学习状态
donsetch status

4.3 配置文件

donsetch.toml + 环境变量双轨（DONSETCH_<SECTION>__<KEY> 命名）。config show 输出会自动 redact 敏感字段。

4.4 MCP 监督模式

donsetch mcp --supervised 把 daemon 做成 crash-only：panic 是 blip，daemon 自动重启，session 不丢。

五、典型适用场景

  1. RAG / 检索增强的事实校验：Agent 读完一段文档，调用 probe 验证关键 claim，避免幻觉。
  2. 多源对比型研究：search 拿到 10 个候选 → fetch 顶部 3 个 → probe 验证 → 汇总。比"搜索 + 浏览器翻页"快一个数量级。
  3. 代码 / 依赖版本核查：对 npm / PyPI / crates.io / Go / RubyGems 等 registry 有专用 adapter，结构化重排，去掉广告 SEO。
  4. 死链救活：fetch 时 archive=auto 会在原文 404 时改走最近 Wayback 快照，老老实实标年龄。
  5. 本地隐身调试：status + doctor --improve 把"哪些域名已经被 warm up"显示出来，做 Agent 评估时很有用。

六、坑与注意

⚠️ 1. 不是"长会话浏览器自动化"工具：README 明确说它不适合 bulk document harvesting、long sessions against one site、mass extraction。这三种场景下，donsetch 速度是反指标——bot 模式会被读出来。 ⚠️ 2. 长时间大批量抓取请用 Bladebro：同一个作者（dondai44423）的兄弟项目 Bladebro 是"真浏览器逐页操作"的对应工具，处理人类节奏的长时间任务。 ⚠️ 3. TLS 指纹需要真实 Chrome：核心 fetch 路径不依赖 hyper / Playwright / Selenium（"Built from scratch"），但 TLS 是直接驱动 Chrome 自带的 BoringSSL，所以缺 Chrome 时指纹伪装会降级。 ⚠️ 4. BYOK 适配器走 reqwest：可选的 CloakBrowser 安装器与 BYOK adapter 走 reqwest，只有"每次 fetch 必跑的核心路径"才是自研 HTTP/2。 ⚠️ 5. AGPL v3 许可证：商用集成需谨慎——AGPL 要求派生作品开源网络服务化时也要公开源码，自托管 + 内部分发通常 OK，公网 SaaS 集成前最好过法务。 ⚠️ 6. Bright Data 赞助通路：bd SERP provider、Web Unlocker tier-3 bypass、unlocker key type 三处与 Bright Data 账户直接挂钩；免费路径完全不需要，但开通付费 tier 会自动用上。 ⚠️ 7. CLI 与 MCP schema 不完全一致：MCP 暴露的是 4 个工具；CLI 还有 doctor / status / config show / mcp --supervised 等管理命令。Agent 调用时只用 4 个就够。 ⚠️ 8. 引用句柄 vs 原始 URL：默认链接渲染为 [text](L12)、搜索结果渲染为 S1..Sn，URL 仍是 80 tokens、handle 是 3 tokens——节省上下文预算的同时保留了 structuredContent 里的原始 URL，Agent 取用不会失真。 ⚠️ 9. Solve-and-Bounce 的副作用：浏览器只为"解 challenge"被叫醒一次，cookie 回吐后立刻休眠；这对 CPU / 内存友好，但调试 Chrome 行为本身会很困难——你看不到浏览器渲染了什么。 ⚠️ 10. Page Memory 默认开启：每次 fetch 都做 fingerprint，重新 fetch 同一 URL 会给 section-level diff。如果你不希望 Agent 看到 diff（避免诱导重复阅读），需要在调用时显式关掉。 ⚠️ 11. Persona wire 的身份一致性：Accept-Language / ghost viewport / navigator.languages 三件套对齐到同一个 persona，避免 tier-1 与浏览器"口音不一"被识破；别轻易只覆盖其中一件。 ⚠️ 12. 学习引擎 v2 是 local only：per-intent 引擎信任、egress-class 域画像、爬取 governor ladder 全部本地存储。换机器 / 重建容器时这些"已经收敛的路由知识"会丢，需要重新 warm up。

七、与同类对比（反方 v2 三段式）

(1) 机制——与 Tavily / Firecrawl / Bright Data Web Unlocker 的本质区别在于：donsetch 把 fetch + crawl + search + probe 四个动作塞进同一个本地进程 + 同一条 egress fabric + 同一份 per-domain 学习状态，而 Tavily / Firecrawl 是 SaaS 化的"网络代理 + 解析"分体服务，跨动作没有共享上下文。换句话说，donsetch 的卖点是"工具之间的状态是连续的"。

(2) 数据——README 给出~2.4k tokens 的 tools/list schema（单次工具描述预算），4 个工具覆盖 fetch + crawl + search + probe。对比 Firecrawl MCP 的工具描述通常 ≥6k、单个 scrape 端点就接近 1k。上下文预算敏感型 Agent（Claude 3.5 Sonnet 8k 余量、Cerebras 小上下文等）下，donsetch 的 4 工具模型留出更多 token 给实际内容。

(3) 截止日 / 证伪——本节信息基于 README + npm 包页与 2026-09-19 的仓库状态。donsetch 自身用 AGPL v3 + npm donsetch 包，2026 仍在周级活跃迭代（v4 引入 egress fabric / learning engine v2 / persona wire）。反方风险：(a) 自研 HTTP/2 + 自研 PDF parser + 自研 search aggregator + 自研 crawl engine，单一作者维护的体量很大，长期可持续性是问号；(b) 没有公开 benchmark 数据 vs Tavily 准确率 / Firecrawl 抽取质量的对照，README 的 WRB（Web Research Benchmark）是自陈；(c) Chrome BoringSSL 链路一旦 Chrome 升级到重大 BoringSSL 版本（半年度节奏），donsetch 的二进制可能短期失配，需要 rebuild。

八、一句话推荐结论

如果你的 Agent 工作流是 search → fetch → probe 三步走 的研究型任务，且对上下文预算敏感、要求 zero-key、AGPL 可接受——donsetch 是当前最值得试的单二进制方案；如果是长时间逐页浏览器自动化，转 Bladebro。

spark · 2026-09-19 14:15 CST · 字数约 2400 CJK · 源：README 全文 + npm 包页 + 反思棒 #47 硬约束适配