前言¶
在 DeepSeek Harness（DSH）里做带联网能力的智能体时，ctx.web 的搜索能力通常只绑定一个 search provider id。环境变量 $DSH_WEB_SEARCH_PROVIDER 也只是覆盖同一字段，源码注释写明 “NOT a hidden priority chain”——宿主本身没有「先 A 后 B 再 C」的优先级链。若本地 Tavily 代理没起、第三方配额用尽、或某一后端超时，单源配置要么直接失败，要么只能手工改配置换源。
下面介绍的 dsh-cascade-search（维护者 Ryker0716）把三级网页搜索后端收进单个 provider，按顺序自动降级，并附带图形化设置页与 cordis.patch.yml bundle patch。插件归类为联网工具，当前 GitHub 星标为 0；npm 包版本 1.2.1，许可证 MIT，要求 Node.js >= 22。
这是什么¶
dsh-cascade-search 是面向 DSH 的插件：为 Harness 的 web_search 实现三级降级链，默认顺序为：
tavily-proxy → querit → deepseek-search-api
本地免费 第三方配额 官方计费 5元/1000次
前一级不可用（未配置、凭据读取失败、报错、超时、或返回 0 条且没有摘要）时自动尝试下一级，并写一条不含密钥的 warn 日志。官方 DeepSeek 搜索 API 作为最后一道防线；每级超时是单次请求的总等待上限（含响应正文），用户主动取消搜索会立即停止，不会继续调用后面的后端。
核心功能¶
降级逻辑¶
降级判断落在插件内部的 lib/cascade.js 引擎中，而非 DSH 宿主。Harness 的 WebRuntime.search() 只解析一个 configuredId；因此「链式回退」只能由单个 provider（本插件注册的 cascade-search）实现。
凭据与配置¶
密钥经 credentialRef 从 Harness credentials 服务（$DSH_HOME/.credentials.yaml）现取，不缓存；新增密钥无需重启。
| 后端 | 默认 ref |
|---|---|
| tavily-proxy | TAVILY_PROXY_AUTH_KEY（代理管理 authKey，不是 tvly-* 池 Key） |
| querit | QUERIT_API_KEY |
| deepseek | DEEPSEEK_API_KEY |
config 中没有 apiKey 字面量字段，避免密钥写入配置文件。
图形化设置（client 半侧）¶
安装后路径：插件 → 已安装插件 → dsh-cascade-search。面板可配置：
- 降级顺序（逗号分隔，可重排）
- 接管网页搜索开关（
adopt） - 每一级的启用、接口地址、密钥名称、密钥、超时
保存后立刻生效，无需重启。设置页由 lib/client.js 注册到 plugins.bundle.config slot。
adopt：接管默认搜索源¶
dsh.bundle.patch 先于用户 profile 应用；若 profile 或 GUI 把 web.config.searchProvider 钉成别的 id，会静默覆盖插件。插件在 apply() 时通过 volatile 配置引用把自己设为选中 provider（cascade-search）。同一会话内 GUI 再改搜索源不会覆盖该选择；要换策略应改本插件的 order。若希望 GUI 接管，将 adopt 设为 false，并自行保证 web.config.searchProvider 指向 cascade-search。
设计要点（节选）¶
available()恒返回true，避免 seam 抛出WEB_PROVIDER_CONFIGURED_UNAVAILABLE吞掉各级失败原因。- 空结果且无摘要才降级；有摘要但暂无来源时保留摘要。
- 取消时不降级，抛出宿主约定的
WEB_ABORTED。 maxResults按后端钳制：tavily 上限 20，querit/deepseek 上限 50。
安装与启用¶
npm 安装（推荐）¶
在 CLI 管理的 web profile 中执行：
dsh plugin --profile web add dsh-cascade-search
该命令从 npm 下载插件、加入 profile 依赖并自动登记 bundle；不需要事先全局 npm install -g 或改 npm 镜像。安装后重启 DSH，再在插件详情页配置凭据与链。
备选：从 GitHub 安装最新源码：
dsh plugin --profile web add github:Ryker0716/dsh-cascade-search
需要固定版本时优先使用 npm 包 1.2.1。
桌面 profile¶
桌面 profile 不能通过 CLI 改依赖。需编辑 ~/.dsh/profiles/desktop/package.json，在 dependencies 中追加 dsh-cascade-search（可用 link: 指向解压目录），在 dsh.profile.bundles 中追加 "dsh-cascade-search"，然后：
cd ~/.dsh/profiles/desktop
CI=true pnpm install --no-frozen-lockfile
只追加本插件，不要覆盖整个 package.json。
典型配置¶
等价于设置页的 cordis.patch.yml 片段示例（手改时注意：config 是整体替换，非深合并，改部分字段需写全整个 config 或使用 GUI）：
- id: cascade-search
name: dsh-cascade-search
config:
order: [tavily, querit, deepseek]
adopt: true
tavilyEnabled: true
tavilyUrl: http://localhost:9100
tavilyCredentialRef: TAVILY_PROXY_AUTH_KEY
tavilyTimeoutMs: 10000
tavilyDepth: basic
queritEnabled: true
queritUrl: https://api.querit.ai/v1/search
queritCredentialRef: QUERIT_API_KEY
queritTimeoutMs: 25000
deepseekEnabled: true
deepseekUrl: https://api.deepseek.com/v1/tools/search
deepseekCredentialRef: DEEPSEEK_API_KEY
deepseekTimeoutMs: 60000
不想用官方 API 兜底时，将 deepseekEnabled 设为 false，或从 .credentials.yaml 删除 DEEPSEEK_API_KEY。
适用场景与注意¶
适合谁： 希望在 DSH 智能体或 CLI web profile 中稳定使用网页搜索、又不想在单一后端故障时手工换源的用户；已有或可部署本地 tavily-proxy、并愿意按需配置 Querit 或 DeepSeek 官方搜索 API 的场景。
运行权限： 插件以当前 DSH 进程权限运行，会发起对外 HTTP 请求并读取本地凭据库。安装前应在 GitHub 仓库 查看源码与 MIT 许可证，确认符合你的安全与合规要求。
排障提示： 三级全失败时错误信息会汇总各级原因。例如 tavily-proxy: not configured 多为缺 TAVILY_PROXY_AUTH_KEY 或代理未监听 9100；deepseek-search-api: HTTP 404 常因 endpoint 应为 https://api.deepseek.com/v1/tools/search。
生态说明： DSH 奉行「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
经过上面的步骤，你会得到一个自带 GUI、可通过 npm 或 GitHub 安装的搜索 provider：本地优先、第三方次之、官方 API 兜底，且失败路径可观测。进一步了解与提 issue 请访问：
