网页搜索++（dsh-web-search-plus）

为 DSH 的联网搜索提供提供方优先级：在 Tavily 第三方搜索 与 DeepSeek 原生搜索 之间自由排序，前一个失败时自动回退到下一个；Tavily 侧可配置多个密钥自动轮换，用来分摊免费版的每日额度上限。

项目地址：https://github.com/polan-prologue/dsh-web-search-plus · 许可证：MIT

---

快速开始

# 从 GitHub 安装（推荐：锁定 tag，升级由你决定）
dsh plugin --profile desktop add github:polan-prologue/dsh-web-search-plus#v0.1.0

# 从本地目录安装（二次开发时用这个）
dsh plugin --profile desktop add <插件目录>

装完刷新一次浏览器页面，客户端半侧才会出现；然后按下面「使用」一节点「立即接管」。

本插件需要 Tavily 密钥才能走 Tavily 那条搜索线。密钥只写入你自己的 DSH 凭据域， 不进本仓库、不进日志；没有密钥时它会如实报「未配置」，并按优先级回退到 DeepSeek 原生搜索。

---

为什么需要这个插件

DSH 的联网搜索统一走 ctx.web seam，而 seam 只支持「按 id 固定一个提供方」：

情况	seam 的行为
配置了提供方 id	只用它，失败即失败
未配置 id，恰好一个可用	用它
未配置 id，多个可用	直接报 WEB_PROVIDER_AMBIGUOUS

也就是说，seam 本身没有优先级链。本插件向 seam 注册一个提供方 web-search-plus，由它在内部按你配置的顺序依次尝试真正的后端：

web_search 工具
   └─ ctx.web（固定指向 web-search-plus）
        └─ 网页搜索++ 优先级链
             1. Tavily 搜索（多密钥轮换：K1 → K2 → …）
             2. DeepSeek 原生搜索（deepseek-official）

DeepSeek 节点复用官方提供方实例，所以它的密钥、账号令牌、接口地址与搜索次数上限继续沿用官方「设置 → 插件 → 网页搜索」页的配置，本插件不重复实现一份会与上游漂移的调用逻辑。

安装

它需要作为组合包装入 profile。先确定你自己的插件目录（克隆或解压出来的、里面有 package.json 的那一层），下文用 <插件目录> 代指：

# 把 <插件目录> 换成你自己的绝对路径，例如 %USERPROFILE%\plugins\dsh-web-search-plus
dsh plugin --profile desktop add <插件目录>

也可以从 GUI 的「插件」页安装，spec 填你自己的插件目录绝对路径。安装后 shell 会加载它；首次需要刷新一次浏览器页面，客户端半侧才会出现。

使用

打开 侧栏 → 插件 → 官方分组 → 「网页搜索++」（就在官方「网页搜索」卡片旁边）。

1. 使用优先级：用「上移 / 下移」调整顺序。默认是 Tavily → DeepSeek。
2. 接管：点「立即接管」。这一步把 profile 里 web 行的 searchProvider 指向 web-search-plus——没有这一步，优先级不会生效，页面会以红色提示如实告诉你当前没接管。
3. Tavily 密钥：
   • 「添加密钥槽位」增加一个槽位（凭据名依次为 TAVILY_API_KEY、TAVILY_API_KEY_2……，也可以自定义成任意合法的环境变量名）；
   • 在每个槽位填入密钥后点「保存密钥」；
   • 密钥只写入凭据域（$DSH_HOME/.credentials.yaml），不写入设置文件，也绝不出现在任何响应里；
   • 「检测各密钥额度」会逐个查询 Tavily /usage，显示每个密钥的已用量与上限。
4. 试一次搜索：真跑一次搜索，并展示本次实际经过了哪些节点、命中哪一个——用来确认优先级确实按你的设置在工作。
5. 重置冷却：手动清除所有密钥的冷却与失效标记。

优先级与回退的实际行为

场景	结果
Tavily 成功	直接返回，不触碰 DeepSeek
Tavily 首选密钥限流 / 额度耗尽	自动改用下一个可用密钥
Tavily 某个密钥无效（401）	该密钥本次运行内标记失效，改用下一个
Tavily 全部密钥失败	回退到链上下一个节点（如 DeepSeek 原生）
链上每个节点都失败	抛 WEB_SEARCH_CHAIN_EXHAUSTED，消息逐条列出每个节点的失败原因
你在设置页取消了当前搜索	立即中止，不回退（回退只针对提供方自身的失败）
首选节点返回 0 结果	默认视为有效答案；打开 fallbackOnEmpty 后改为继续下一个节点

密钥状态的错误分类

分类依据实测的 Tavily 行为，而不是 HTTP 语义的教科书含义：

状态码	含义	动作
401 / 403	该密钥无效	标记失效，换下一个
429	该密钥限流	按冷却时长（默认 60 秒，或响应里的 Retry-After）冷却
432 / 433	该密钥额度/套餐上限用尽	冷却（默认到次日零点）
400	该密钥不接受此次请求（如查询过短）	换下一个密钥
422	请求体不符合接口 schema	不轮换，直接上抛——换密钥不会让非法请求变合法
5xx / 网络错误	上游临时故障	换下一个密钥

实测数据：无效密钥 + 正常查询 → 401；有效密钥 + 单字符查询 → 400。因此 400 归入「可轮换」。

配置项

全部字段都是 volatile 字段，可以直接在插件页改，也可以写进 profile 的 cordis.patch.yml：

字段	默认值	含义
priority	[tavily, deepseek-official]	提供方尝试顺序
tavilyKeyRefs	[TAVILY_API_KEY]	密钥槽位的凭据引用名（最多 20 个）
tavilyBaseURL	https://api.tavily.com	Tavily 接口地址
tavilyMaxResults	8	单次结果上限（1–20）
tavilySearchDepth	basic	basic / fast / ultra-fast / advanced（advanced 消耗 2 倍额度）
tavilyIncludeAnswer	true	是否请求摘要答案（映射为结果的 content）
tavilyTimeoutMs	30000	单次请求超时
tavilyRateLimitCooldownMs	60000	429 后的冷却时长；0 表示不自动恢复
tavilyQuotaCooldownMs	0	432/433 后的冷却时长；0（默认）表示额度耗尽后保持冷却，仅手动重置可恢复
fallbackOnEmpty	false	0 结果时是否继续下一个节点

交还与恢复

• 插件页的「交还官方搜索」会把 web 行的 searchProvider 改写为显式 deepseek-official，即回到官方搜索。

  为什么不是"删掉覆盖"：seam 只有在「显式指定了提供方」或「注册表里恰好只有一个可用提供方」时才不歧义。本插件始终把自己注册进注册表，一旦删掉字段就会变成「两个可用提供方 + 无显式选择」，宿主抛 WEB_PROVIDER_AMBIGUOUS，联网搜索彻底不可用——而且接口仍返回 ok=true，只有真正搜索时才暴露。写回显式 id 才能同时满足"用官方搜索"和"不歧义"。

• 快照里的 takeover.ambiguous 会标出这种歧义状态，界面上也会明确提示「搜索当前不可用」，不会假装成"自动选择"。
• 也可以手工编辑 profile 的 cordis.patch.yml，把 id: web 那个覆盖块的 searchProvider 改成 deepseek-official。 该文件在 %DSH_HOME%\profiles\<profile 名>\cordis.patch.yml；%DSH_HOME% 默认是 %USERPROFILE%\.dsh （PowerShell 里等价写法：Join-Path $env:USERPROFILE '.dsh\profiles\desktop\cordis.patch.yml'， 设过 $env:DSH_HOME 时以它为准）。不想找文件就直接在上面的插件页点「交还官方搜索」。
• 卸载插件：dsh plugin --profile desktop remove dsh-web-search-plus。

注意：profile patch 是按 id 整体替换、不做深度合并。所以接管时必须重述 fetchProvider: http，插件已经这么做了；手工编辑时也请保留它。

开发

完整的故障档案见 docs/开发踩坑记录.md —— 按「环境搭建 / 骨架接线 / schema / 宿主契约 / 开发调试 / 测试关卡 / 打包发布 / 端到端验收」组织，每条给出现象 / 原因 / 解决 / 证据。接手前建议先读第十节「一页速查」。

# 单元测试（纯逻辑，不需要网络与密钥）
node --test "tests/*.test.mjs"

# 真实联网验收（需要真实密钥）
$env:DSH_WSP_TEST_KEY='tvly-xxx'; node tests/live-check.mjs

模块	职责
lib/errors.js	稳定错误码；WebError 的动态导入与本地回退
lib/config.js	配置词汇与归一化（纯函数）
lib/schema.js	schemastery Config 与 volatile 字段读取
lib/tavily.js	KeyRing（多密钥的粘滞选择、失效与冷却状态机）、Tavily 调用、响应映射、错误分类
lib/chain.js	优先级链式提供方（注册进 ctx.web 的那一个）
lib/routes.js	/api/dsh-web-search-plus 管理路由族
lib/index.js	宿主入口：装配 provider、路由与设置页策略
lib/client.js	浏览器半侧：插件页卡片与设置页面

已知限制

• web_fetch 不走本插件：链式提供方只接管搜索；抓取仍是 http 提供方。
• 依赖官方提供方实例：DeepSeek 节点从 ctx.web 的注册表按 id deepseek-official 取实例。若官方行被禁用，该节点会被标记为「未注册」并跳过（页面会如实显示），而不是静默出错。
• 管理接口只接受本机请求：非回环地址一律 403。
• Tavily 免费版可能不上报 plan_limit：此时「检测额度」显示「未报告上限」，轮换策略不依赖该值，只依赖实际错误码。