可靠联网检索 dsh-plugin-db/dsh-reliable-web

dsh-reliable-web

为 DeepSeek Harness 提供免费、可靠的 web_search 和 web_fetch —— 不用付费搜索 API，不用注册，也不用针对某个模型做集成。它接入 Harness 的 web 接缝（ctx.web），所以只要能调用内置 web 工具的模型和智能体预设，都能拿到免费检索，工具 schema、结果卡片、超时策略和错误处理完全一致。

为什么这样设计

Harness 已经管住了面向模型的契约：@deepseek-ai/dsh-tool-web 定义 web_search / web_fetch 工具、参数校验、HTML→markdown 转换、结果展示和取消。本插件刻意不重写其中任何一项。它只在文档给出的扩展点上注册两个服务商：

| 能力 | 服务商 id | 注册方式 |
| 搜索 | reliable | ctx.web.registerSearchProvider() |
| 抓取 | reliable | ctx.web.registerFetchProvider() |

正是这个选择让它在 Harness 各版本间都能用：

- 不导入任何 @deepseek-ai/ 包，也没有 npm 依赖，所以即使 Harness 内部模块无法解析，配置档安装照样能跑；
- 只用文档给出的两个接缝方法，外加符合已发布结构的普通结果对象；
- 服务商错误使用文档给出的开放字符串 code 词表；
- Config 是 Standard Schema（~standard.validate），Cordis 原生校验 —— 不用引入 schema 库，也就不会出现版本漂移。

启用与服务商选择

内置组合把 web.searchProvider 固定为 deepseek-official，把 web.fetchProvider 固定为 http。如果静态补丁直接替换这些 id，之后禁用本插件就会留下悬空引用：配置档里每次 web 调用都会以 WEB_PROVIDER_CONFIGURED_MISSING 失败。

所以插件改为在运行时抢占选择，而且只在字段仍是它被明确允许替换的 id 时才动手（takeOverSearchIds / takeOverFetchIds），卸载时恢复原值。由 $DSH_WEB_SEARCH_PROVIDER / $DSH_WEB_FETCH_PROVIDER 设定的 id，或任何第三方固定的 id，都原样保留，只记一行日志。因此禁用插件只会退回到官方服务商，不会把搜索弄坏。

takeOver: false 可关掉这一行为；这时你需要自己把 web 行的服务商 id 设成 reliable。

搜索

一次查询会按 searchFanout 并发数分批扇出到多个免费后端。所有默认引擎都无需账号；其中几个在有 key 时也会用 key 提高限额，Brave 只在配置了 key 时才加入链路。

| 引擎 | Key | 说明 |
| exa | EXA_API_KEY 可选 | 公开的 Exa MCP 档位；语义索引 |
| parallel | PARALLEL_API_KEY 可选 | 公开的 Parallel 搜索 MCP 档位 |
| brave | BRAVE_API_KEY 必填 | 官方 API；每月免费额度（按标价约 1,000 次请求） |
| tavily | TAVILY_API_KEY 可选 | 免 key 访问模式 |
| keenable | KEENABLE_API_KEY 可选 | 公开的 /search/public 档位 |
| anysearch | ANYSEARCH_API_KEY 可选 | 无需密钥的公共端点 |
| firecrawl | FIRECRAWL_API_KEY 可选 | 无需密钥的月度额度 |
| duckduckgo | — | 独立 HTML 索引，最后的兜底 |
| wikipedia | — | 百科类兜底 |

Brave（可选）

Brave 是唯一按设计需要密钥的引擎：它有很强的独立索引，预付套餐包含每月免费额度（目前是 $5，按 $5/1,000 的标价约合 1,000 次请求；一些旧套餐显示的是固定的每月查询额度）。插件按以下顺序读取密钥：

1. 行配置里的 braveApiKey；
2. 进程环境变量里的 BRAVE_API_KEY（或 BRAVE_SEARCH_API_KEY）；
3. $DSH_HOME/secrets/brave.key，然后是 ~/.dsh/secrets/brave.key，再然后是 ~/.config/dsh-reliable-web/brave.key。

只使用文件里第一个非空行，所以末尾带换行没问题。文件权限保持 600。找不到密钥时，跳过该引擎并输出一行调试信息，无密钥链路保持不变。Brave 的每秒限额取决于套餐（免费档通常每秒一次请求），所以插件把 Brave 请求间隔拉开约 1.1s；单次查询不会延迟，多查询的 web_search 调用会排队，而不是触发 429。

绝不要提交密钥。 仓库忽略 .env、.secrets/ 和 *.key；推荐的位置都在仓库之外。

质量来自融合，而不是挑一个偏爱的引擎：

- 每个引擎对每条结果的贡献是 weight / (k + rank)，所以多个独立索引都排得靠前的文档，会胜过只有一个索引排第一的文档（倒数排名融合）；
- URL 会规范化后去重——片段和跟踪参数从键里剔除，www. 和协议折叠，末尾斜杠折叠，GitHub blob URL 跨分支/提交引用合并；展示的 URL 保留片段，但去掉跟踪参数；
- 摘要和标题取自返回该文档的最权威引擎，空缺由其他引擎补齐。

可靠性与质量分开处理：

- 失败、被限流或返回空的引擎会进入冷却（限流 60s，配额和鉴权 30min，瞬时错误 15s），链路继续；
- 所有引擎共享一份实际耗时预算（searchBudgetMs）；
- 短 TTL 缓存（5 分钟，256 条，LRU）服务重复查询，不触碰任何上游，这在按地址计费的免费档上很重要；
- truncated 是诚实的：它表示来源确实被丢弃，而不只是达到了请求的数量。

如果所有未冷却的引擎都失败，调用抛出结构化的 WEB_PROVIDER_ERROR，而不是假装网上没有结果。如果引擎返回空，则返回一个空的成功结果。

Fetch

只有在必须时才升级检索方式：

1. direct，SSRF 安全的 HTTP(S)。没有第三方看到 URL。返回 HTML 以 kind: 'html' 返回，交给 Harness 自带的转换器生成面向模型的 markdown。普通页面走这条快路径。
2. readers（jina、exa、firecrawl），并发启动，只在以下情况才用：direct 被拒绝（401/403/406/429/451/503）、遇到机器人挑战、页面是客户端渲染的空壳，或在传输层失败。它们在自家基础设施上渲染页面并返回 markdown，能找回 direct 抓取看不到的内容。
3. 像 404/410 这类明确的 direct 状态，直接作为结果返回——交给 reader 只会更慢地重复同一个结果。

能读到的成功结果，永远好过机器人墙或错误页。404 是结果，不是异常。整条链路共用一个截止时间（fetchBudgetMs，25s），在工具 30s 的协作预算下留出余量，这样超时能精确上报，而不是变成一个含糊的 TOOL_TIMEOUT。

SSRF 与资源安全

传输层自成一体，默认拒绝：

- 只允许 http:/https:，不允许内嵌凭据，URL 上限 2048 字符；
- 每一跳都重新解析、重新筛查、重新固定，重定向逃不出公网地址策略；
- 每个解析出的地址都必须是公网地址；loopback、私有、link-local、CGNAT、benchmark、multicast、documentation 和保留网段一律拒绝，字面量地址和解析出的域名同等对待；
- 连接固定到校验过的地址集合，DNS 答案无法在检查和连接之间变化；
- 响应字节数、重定向跳数、转换后的字符数都有上限；
- 解压有边界，压缩体无法无限膨胀。

allowPrivateNetwork: true 供本地/内网部署使用，默认关闭；它是唯一能让模型触达云元数据和本地服务的设置。

配置

配置行是 reliable-web。所有字段都可选。

- id: reliable-web
name: 'dsh-reliable-web'
config:
search
engineOrder: ['exa', 'parallel', 'brave', 'tavily', 'keenable', 'anysearch', 'firecrawl', 'duckduckgo', 'wikipedia']
disabledEngines: []
searchBudgetMs: 25000
searchFanout: 3
searchTimeoutMs: 12000
searchCacheTtlMs: 300000 # 0 disables the cache
braveApiKey: '' # prefer BRAVE_API_KEY or the secret file
fetch
readers: ['direct', 'jina', 'exa', 'firecrawl']
fetchBudgetMs: 25000
fetchTimeoutMs: 20000
fetchMaxRedirects: 5
fetchMaxBytes: 4000000
maxContentChars: 200000
maxHtmlChars: 200000
includeLinks: false
allowPrivateNetwork: false
activation
takeOver: true
takeOverSearchIds: ['deepseek-official']
takeOverFetchIds: ['http']

错误的值会回退到默认值，并记录为警告；插件仍会激活。一个拒绝加载的 web 服务商，比一个带着默认超时运行的服务商更糟。

除 Brave 外所有键都可选，且只提高单个引擎的上限；没有无密钥链要能工作，需要先完成配置。Brave 同样是可选项，但在提供密钥之前不会启用。密钥请设在进程环境或本地密钥文件里，不要写进受版本跟踪的配置文件。

安装

git clone https://github.com/dsh-plugin-db/dsh-reliable-web.git

然后把克隆下来的目录作为 bundle 安装到当前配置档。用插件管理器（install_bundle，target 填包的绝对路径），或者用 Web UI 的 Plugins 页面。安装会把包链接和 bundle 选择写入配置档，因此对每个会话都生效，重启后依然保留。

Brave 的密钥请放到 ~/.dsh/secrets/brave.key（权限 600），或者在启动 DSH 前导出 BRAVE_API_KEY。两者都不存在时，这个引擎会被跳过。

验证

node verify.mjs # offline checks + live search/fetch
node verify.mjs --offline # no network

测试套件会像 Cordis 那样通过 apply() 激活插件，检查注册、选择接管、配置回退、SSRF 拒绝、实时融合搜索、缓存命中、直接抓取，以及把 404 当作结果返回。

故障排查

| 现象 | 原因 / 处理 |
| 搜索仍在用付费服务商 | 另有服务商被显式固定（日志里会写明）。把 takeOverSearchIds 设为包含它，或者在补丁里固定 reliable。 |
| WEB_PROVIDER_CONFIGURED_UNKNOWN | takeOver: false，且组合里没有 searchProvider: reliable。 |
| 搜索很慢 | 对你的查询来说，少几个引擎可能就够了：调低 searchFanout，或者从 engineOrder 里去掉较慢的引擎。 |
| 全部被限流 | 免费额度按地址计算。链会冷却并回退到 DuckDuckGo/Wikipedia；等一会儿，或者给任意引擎加个密钥。 |
| Brave 从不出现在 status() 里 | 激活时没找到密钥。把密钥放进 ~/.dsh/secrets/brave.key 或 BRAVE_API_KEY，然后重新加载/重启插件。 |
| Brave 返回 401/403 | 密钥被拒绝或已轮换。更新密钥文件；认证失败后该引擎会冷却 30 分钟。 |
| 本地限流器还在，Brave 却返回 429 | 另一个进程共用同一密钥。该引擎冷却 60s，链的其余部分继续。 |
| 页面需要登录 | 没有阅读器能绕过需要认证的页面；只能取到公开内容。 |
| 访问内网主机时报 WEB_BLOCKED_URL | 这是设计如此。只在可信的本地部署上设 allowPrivateNetwork: true。 |

许可证

MIT。