Skip to content

dsh-web-gateway

Verified

@goodandready/dsh-web-gateway · v0.2.3 · MIT · Web UI

Resilient web search and page extract tools for DeepSeek Harness with free-tier-first Firecrawl / Keenable / SearXNG / DuckDuckGo attempts, then Tavily / Brave / Exa keys, circuit breaker and SSRF-safe extract.

Install

dsh plugin add @goodandready/dsh-web-gateway

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Readme

📦 @goodandready/dsh-web-gateway

面向 DeepSeek Harness 的高可用网页搜索与 SSRF 安全页面提取回退链套件

npm version license DSH Plugin Node version

作者全部项目

🇬🇧 English • 🇨🇳 中文说明 • 🇷🇺 Русский

⭐ 如果您喜欢这个插件,请在 GitHub 上为它点亮 Star — 这能让我知道插件对您有用,并鼓励我继续开发和维护它。

🐛 如果您发现 Bug 或希望增加功能,请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议,并在后续版本中实现有价值的改进。

面向 DeepSeek Harness 的弹性 网页搜索 与 页面提取 工具。

当内置 web_search / web_fetch 遇到限流、验证码或空结果时,本插件提供另一套独立工具名的回退链(不会与核心工具注册冲突)。

概览 / 问题

DSH 自带 web_search / web_fetch,但单一上游可能限流、触发验证码或返回空结果。本插件提供独立的 web_gateway_* 工具:每个提供商展开为免费与密钥尝试,所有免费尝试先于密钥尝试,并逐条报告跳过/失败原因。插件不替换内置工具。

架构

graph LR
  A[Agent 工具调用] --> B[web_gateway_search / extract / research]
  B --> C[尝试展开:provider + mode]
  C --> D[免费:Firecrawl keyless、Keenable keyless、SearXNG、DuckDuckGo、Jina、readability]
  D --> E[密钥:Firecrawl、Keenable、Tavily、Brave、Exa、Crawl4AI]
  E --> F[Guards:按模式限额、熔断器、遥测]
  F --> G[结果、跳过原因、缓存]
  B --> H[URL 策略:公网 IP、同源重定向、响应体上限]
模块 职责
lib/index.js 宿主入口:Config、工具注册、health/update 路由
lib/attempts.js 将提供商顺序展开为 provider:mode 尝试;免费优先
lib/chain.js fallback / race / aggregate;单次超时与总预算
lib/guards.js 按模式限额、熔断器、遥测
lib/providers.js 提供商 HTTP 调用、有界 JSON 读取、截图、文档格式化
lib/url-policy.js URL 解析、公网 IP/DNS 策略、连接期安全 undici dispatcher
lib/updater.js 同源更新状态/安装路由
lib/client.js 设置卡片、health/updater、en/zh 本地化与样式

工具

工具 作用
web_gateway_search 网页搜索。免费通道:Firecrawl keyless → Keenable keyless → SearXNG → DuckDuckGo;然后密钥:Firecrawl → Keenable → Tavily → Brave → Exa
web_gateway_extract 将 URL 提取为 Markdown。免费通道:Firecrawl keyless → Jina → readability;然后密钥:Firecrawl → Tavily → Crawl4AI
web_gateway_research 搜索并提取多来源网页为精简 Markdown 摘要

HTTP API

设置卡片使用两个同源路由。回环请求始终允许;远程浏览器仅在 Sec-Fetch-Site: same-origin 或 Origin 与 Host 一致时允许。这样 LAN/Tailscale/反向代理下的 UI 可用,同时拒绝跨站请求。

路由 方法 访问 用途
/api/dsh-web-gateway/health GET, HEAD 回环或同源 凭证、端点、限额、熔断器、遥测
/api/dsh-web-gateway/health POST 回环或同源 重置遥测
/api/dsh-web-gateway/update GET, HEAD 回环或同源 版本检查
/api/dsh-web-gateway/update POST 回环或同源 + x-dsh-plugin-update: 1 安装精确版本

缺少密钥、空结果、HTTP 429/5xx 或网络错误时会跳过该提供商。内置熔断器 (Circuit Breaker) 会在多次连续失败后自动暂时隔离该提供商。结果可按 TTL 缓存在内存中。

免费额度优先

先消耗免费通道,再使用密钥:Firecrawl keyless → Keenable keyless → SearXNG → DuckDuckGo,然后 Firecrawl key → Keenable key → Tavily → Brave → Exa。provider 和 skipped 会显示模式(firecrawl:free、firecrawl:key#2)。

freeTierFirst=false 会按提供商交错免费与密钥尝试。要完全关闭 keyless,请设置 firecrawlKeylessSearch=false、firecrawlKeylessFetch=false、keenableEnabled=false。

升级后 Keenable 会加入默认顺序;设置 keenableEnabled=false 可退出。多个密钥可用逗号分隔,认证/限流/额度失败时会轮换。

当 allowInternalUrls=true 时,内网 URL 只由本地 readability 处理,云提供商会被跳过。

提取 URL 会校验:仅 http/https,禁止 URL 内嵌凭据,主机名必须解析为 公网 IP(回环 / RFC1918 / 链路本地 / 元数据地址默认拦截),并在连接时由 undici dispatcher 再次校验。仅在确实需要时才打开 allowInternalUrls。

安装

dsh plugin --profile web add @goodandready/dsh-web-gateway

安装后请重启 web 配置文件。

凭证

在 设置 → 凭证(或 $DSH_HOME/.credentials.yaml)中保存密钥。设置卡片只保存 凭证名称,不保存密钥本身。

FIRECRAWL_API_KEY 和 KEENABLE_API_KEY 可选:keyless 模式无需密钥。凭证值可包含多个以逗号分隔的密钥。

设置

在 设置 → 插件 → Web Gateway 中配置:

设置 默认值 含义
defaultLimit 5 默认搜索结果数
maxLimit 20 搜索硬上限
timeoutMs 30000 单次尝试超时;整条链预算由 searchDeadlineMs / extractDeadlineMs 控制
cacheTtlMs 600000 内存缓存 TTL(0 禁用)
searxngUrl / crawl4aiUrl 空 本地端点;空则禁用
freshness any any / day / week / month
freeTierFirst true 所有无密钥尝试先于密钥尝试
firecrawlKeylessSearch / firecrawlKeylessFetch true 允许无密钥 Firecrawl 搜索/提取
keenableEnabled / keenableApiKeyEnv true / KEENABLE_API_KEY Keenable 开关与凭证名
duckduckgoEnabled true 启用无密钥 DuckDuckGo
searchDeadlineMs / extractDeadlineMs 60000 单条链的总预算
circuitBreakerCooldownMs 300000 熔断后的冷却时长
dailyCap* 0 按 provider+mode 的日限额(0 = 不限)
dailyCapJina / dailyCapReadability 0 无密钥提取回退的日限额
searchProviderOrder firecrawl,keenable,searxng,duckduckgo,tavily,brave,exa 搜索提供商顺序
extractProviderOrder firecrawl,tavily,crawl4ai,jina,readability 提取提供商顺序
allowInternalUrls false 允许内网提取(仅本地提供商)

限制

  • 本地 readability 会明确拒绝 PDF/DOCX;文档解析请使用 Jina 或 Firecrawl。
  • 无密钥 Firecrawl / Keenable 会把公网查询/URL 发送到云端;如不接受请关闭。
  • 设置卡片与路由要求同源;反向代理必须保留 Origin / Host(或 Sec-Fetch-Site)。
  • 截图仅在 take_screenshot 时生成,单文件上限 5 MB。
  • 提供商超时会计入熔断器失败;连续超时会暂停该提供商。

与核心网页工具的关系

Harness 已通过 @deepseek-ai/dsh-tool-web 提供 web_search / web_fetch。本插件 不替换 它们,只额外提供 web_gateway_* 作为回退。

许可证

MIT © GooDAnDReaDY