DSH Hub / 插件 / dsh-web-tools A3Boy/dsh-web-tools ↗ ★ 0
dsh-web-tools Unified multi-provider web search and fetch for DeepSeek Harness — BYOK, per-provider credential pools, quota & health monitoring, deterministic fallback, native settings UI, and self-hosted search
包名 dsh-web-tools
版本 0.1.0
许可证 MIT
最近更新 2026年8月15日 GitHub ↗ 文档 ↗ 安装 $ npx -p @deepseek-ai/dsh dsh plugin --profile web add github:A3Boy/dsh-web-tools复制
一个 Web Tool Surface，统一管理所有搜索 Provider。
dsh-web-tools 是 DeepSeek Harness 的开源 Web Search / Fetch 聚合层，在保持 Agent 只使用原生 web_search / web_fetch 的同时，统一提供多 Provider、BYOK、多凭据、额度监控、健康状态、确定性故障切换和自托管搜索。
English | 简体中文
🖥️ 一图速览
能力 解决什么问题 🌐 统一搜索 Tavily / Exa / Brave / Firecrawl / Jina / You.com / SearXNG 统一接入 🔑 BYOK + 凭据池 每个 Provider 独立管理合法凭据，不需要共享 Key 📊 额度感知 官方余额 / Usage / Rate Limit / Best-effort 状态统一展示 ❤️ 健康监控 认证失败、限流、额度耗尽、超时等状态统一管理 🔄 确定性故障切换 Provider 故障时按明确顺序切换，不让 Agent 重规划 📖 搜索 + 抓取 搜索结果之后继续抓取正文，完成完整 Web Agent 链路 🏠 自托管 SearXNG 一等支持，不强依赖商业搜索服务 🖥️ 原生设置 UI Provider、Key、额度、Fallback、测试搜索全部在 DSH 设置页完成
✨ 为什么需要它？
DeepSeek Harness 已提供原生 Web capability（ctx.web）和多个搜索 Provider，但每个 Provider 的凭据、额度、健康状态、路由和配置仍然彼此独立——由你手动管理差异 ：
dsh-web-tools · DSH Hub
没有 dsh-web-tools
DSH
├── DeepSeek provider
├── Exa provider
├── Perplexity provider
├── Firecrawl community provider
└── ...
↓
用户自己管理配置、Key、状态和切换
有了 dsh-web-tools
DSH Agent
│
web_search / web_fetch
│
dsh-web-tools
│
├── Routing
├── Credential Pool
├── Quota
├── Health
├── Fallback
└── Diagnostics
│
┌────┼────┬─────┬─────┐
Tavily Exa Brave Firecrawl ...
dsh-web-tools 是 Web Provider 编排层 ——不是一个又一个搜索插件。
🔌 支持的 Provider
额度信息绝不参与搜索正确性。额度检测失败时，搜索依然可用。
计划中：Serper · Parallel · Perplexity · 更多社区 Provider（见 Provider 开发 ）。
🆓 免费额度与适用场景 截至 2026-08 各家官方免费额度——不用押注一家搜索服务 ，把每家的免费额度、搜索特色和自托管能力组合起来：
Provider 免费额度 周期 适合什么 Tavily 1,000 credits ♻️ 每月 ⭐ 默认 Agent 搜索 Exa $20 注册 + $10 ♻️ $10/月 🧠 语义 / Research Firecrawl 1,000 credits + 1,000 Search credits ♻️ 每月 📖 Search + Scrape Brave $5 ≈ 1,000 次搜索 ♻️ 每月 🌐 通用独立 Web 索引 You.com $100 🎁 新账号一次性 💰 大量免费实验 Jina 10M tokens 🎁 新账号一次性 📄 Search + Reader SearXNG 无平台配额 ♾️ 自托管 🏠 永久 fallback
不用押注一家搜索服务。 把每家的免费额度、搜索特色和自托管能力组合起来，让 web_search 在一个 Provider 用不了时仍然继续工作。
推荐默认顺序（也可作为 fallback 预设）：
通用 Agent ：Tavily → Exa → Brave → SearXNG深度读网页 ：Tavily / Exa 搜索 → Firecrawl / Jina 抓取最大化免费额度 ：You.com → Exa → Tavily → Brave → Firecrawl → SearXNG
📊 额度感知——官方时用官方，拿不到就诚实 不同引擎的额度语义完全不同。dsh-web-tools 如实展示每一种，绝不伪装成统一的"剩余百分比"：
Tavily 823 / 1,000 credits Official
Firecrawl 711 / 1,000 credits Official · Reset Sep 1
Brave 943 requests remaining Response Header · Updated 3 min ago
Jina 8.2M tokens left Best effort
Exa $3.82 used this month Account balance unavailable
SearXNG Self-hosted No provider quota
官方时用官方 ：Tavily /usage、Firecrawl credit-usage、You.com balance、Brave rate-limit 响应头（每次搜索自动捕获，零额外请求）。拿不到就诚实 ：Exa usage 需 Team Management 凭据；Jina 是 best-effort 解析；不支持的一律显示 Unavailable，绝不猜测。额度是观测，不是搜索依赖 ——额度失败绝不影响搜索。Quota-aware 路由只用权威数据跳过确认耗尽 的 Provider。
🔑 BYOK + 凭据池 无共享 Key——全部 Bring Your Own Key 。每个 Provider 可配置多个合法凭据，按最少使用优先 选择；失败凭据自动降级并维护健康状态。
Tavily
├─ Key A
├─ Key B
└─ Key C
适用于：团队 Workspace · 多个合法 API Key · Key rollover · 不同环境 · BYOK · 凭据故障隔离 · Key rotation。
凭据池服务于合法多 Key 场景——不用于规避配额。
🔄 确定性故障切换 Tavily
│
└─ HTTP 429
↓
Exa
│
└─ timeout
↓
Brave
│
└─ 5 results
↓
web_search success
可恢复故障触发切换：408 / 429 / 5xx · 网络 · 超时 · Provider 不可用 · 确认失效的凭据 · 权威确认耗尽的额度。400 / 配置错误不切换。顺序确定、对 Agent 透明——不产生额外 Tool Call、不重规划。
📖 搜索 + 抓取 web_search → 候选 URL → web_fetch → 网页正文 → 回答
具备原生提取能力的 Provider（Tavily、Exa、Firecrawl、Jina）直接使用；其余干净降级。
🖥️ 设置 UI 与测试搜索 一切都在 DSH 原生设置中完成——不需要 YAML、不需要 .env：
Settings → Plugins → Plugin configuration → dsh-web-tools
默认 Provider · fallback 顺序 · 结果数 · 超时
每 Provider 启用/禁用、API Key、多凭据池、Base URL
每 Provider 测试连接 （真实最小请求；区分 401 / 429 / 超时）
测试搜索 ——真实查询，看到实际 Provider、延迟与结果，无需先开 Agent 对话
🏠 自托管，一等支持 SearXNG 是一等 Provider，不是临时 fallback：
云搜索的 fallback：Tavily → Exa → Brave → SearXNG
或纯自托管 ：完全不配任何商业搜索 API
适合隐私优先、本地部署、Homelab、企业网络。
🚀 快速开始 dsh plugin --profile web add dsh-web-tools
重启 dsh web
→ Settings
→ Plugins
→ dsh-web-tools
就这么多。源码安装 / junction / peer 依赖说明见 开发 与 疑难排查 。
🏗️ 架构 DSH Agent
↓ 只见 web_search / web_fetch
dsh-tool-web（官方工具，由插件重新启用）
↓
ctx.web（searchProvider: dsh-web-tools）
↓
dsh-web-tools SearchHubProvider
├── Router 确定性 fallback + quota-aware skip
├── Pools 每引擎凭据轮换（最少使用优先）
├── Quota 官方 / 响应头 / best-effort / 本地估算
├── Health 运行时凭据与 Provider 状态
└── Providers Tavily · Exa · Firecrawl · Brave · You.com · Jina · SearXNG
设置卡 (client)
↓ fetch /web-tools/api/*（fenced，仅 loopback）
Host routes（config/save · credentials/set · test/* · quota/describe）
↓
ctx.settings（dsh-web-tools namespace，非敏感配置）
ctx.credentials（WEB_TOOLS_
，凭据池）
🛡️ 安全与隐私
凭据在 DSH Host 上解析。
完整 API Key 永不回传浏览器 ——只有 configured / 掩码状态。
日志与测试响应都会掩码凭据内容。
不向 dsh-web-tools 或任何地方发送使用遥测 。无共享 Key、无强制代理服务器。
配置写入限制在本地配置平面 （loopback 围栏）。
可完全不使用商业搜索服务，仅靠 SearXNG。
✅ 已验证 项目 状态 Host 类型检查 ✅ Client 类型检查 ✅ 单元测试（pool / fallback / Jina 余额 / Brave 响应头） ✅ 12 通过 路由冒烟（配置 · 凭据零泄漏 · 额度 · 测试 · 围栏 403） ✅ Tavily 真实搜索 + 官方额度 ✅ Exa 真实搜索（双 Key）+ 凭据池轮换 ✅ Firecrawl 真实搜索 + 抓取 + 官方额度 ✅ Web profile 安装（dsh --dump-config） ✅ 非 loopback 配置写入被拒绝 ✅
⚙️ 配置 Provider Credential ref 说明 Tavily WEB_TOOLS_TAVILY多 key 逗号分隔 Exa WEB_TOOLS_EXAhighlights 模式 Firecrawl WEB_TOOLS_FIRECRAWL/search + /scrape Brave WEB_TOOLS_BRAVEX-Subscription-Token You.com WEB_TOOLS_YOUUSD 余额 Jina WEB_TOOLS_JINAs.jina.ai + r.jina.ai SearXNG WEB_TOOLS_SEARXNGbaseUrl（自托管）
设置 namespace：dsh-web-tools（enabled、defaultProvider、maxResults、searchTimeoutMs、fallbackOrder、maxFallbackProviders、providerBaseUrls、providerEnabled）。
🧱 设计边界
一个新的 Agent
Web Search 规划器
MCP 代理
AI Provider 选择器
托管搜索网关
共享 API Key 服务
DSH web_search / web_fetch 的替代品
它是 DSH 原生 Web 能力背后的Provider 编排层 。
📦 安装 / 更新 / 移除 # 安装
dsh plugin --profile web add dsh-web-tools
# 更新
dsh plugin --profile web update dsh-web-tools
# 移除
dsh plugin --profile web remove dsh-web-tools
移除插件会干净地移除其运行时与 UI 集成，不修改 DSH core ——无残留 prompt、工具定义或全局钩子。
🤖 让 Agent 帮你安装 复制给 Codex / Claude Code / 任意编码 Agent：
安装 dsh-web-tools，来源：
https://github.com/A3Boy/dsh-web-tools
要求：
- 优先使用 `dsh plugin --profile web add dsh-web-tools`。
- 不要读取或打印 API Key 值。
- 不要修改 DeepSeek Harness core。
- 安装后用 `dsh --profile web --dump-config` 校验组合配置。
- 未经询问不要重启正在运行的 DSH 进程。
- 报告 dsh-web-tools 是否出现在 Web profile 中。
🔌 Provider 开发 新增 Provider 只需实现 ProviderAdapter 契约（src/host/providers/types.ts）并在 src/host/providers/index.ts 注册——Agent 工具面永不改变。详见 CONTRIBUTING.md 。
🗺️ Roadmap
V1.1 — Exa Team-Management usage 接入设置 UIV1.2 — Serper · Parallel（OAuth 余额）· Perplexity（实验性）V2 — 用量历史图表 · Provider 对比基准 · Brave 响应头进入 quota/describe
🛠️ 开发 npm install
npx tsc -p tsconfig.json --noEmit # Host 类型检查
npx tsc -p tsconfig.client.json --noEmit # Client 类型检查
npx tsc -p tsconfig.build.json # 构建 lib/
node --experimental-strip-types --test src/host/logic.test.ts # 单元测试
node --experimental-strip-types test/routes.smoke.mjs # 路由冒烟
本地开发需要可解析 DSH peer 依赖——用 junction 指向 DSH profile 的 node_modules 即可。
疑难排查
插件不在 --dump-config 中 ——确保 profile 的 package.json 的 dsh.profile.bundles 里有 dsh-web-tools（npm 安装会自动处理）。设置卡不显示 ——完全重启 dsh web；client bundle 在启动时加载。
🤝 贡献
📄 License 
