前言¶

在 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）现取，不缓存；新增密钥无需重启。

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 请访问：

• 目录页：https://www.skillhub.cn/plugins/Ryker0716/dsh-cascade-search
• 源码与 README：https://github.com/Ryker0716/dsh-cascade-search