dsh-tavily-pool

English | 简体中文

用 Tavily 替代 DeepSeek Harness 内置的 web 搜索与网页抓取：多密钥池、余额感知轮转、失败自动切换、冷却、官方 /usage 余额展示，搜索与抓取各有独立开关，全部在 DSH 设置面板内配置。

请勿与 SZMY-haruhi/dsh-tavily（单密钥 / 免密钥，无调度）或 @yuuz12/dsh-tavily（多密钥，但不接管抓取，且在运行时改写内部字段）混淆。本插件管理一个密钥池，按剩余余额调度，并同时接管 web_search 与 web_fetch。

功能

• 多密钥池 —— 单把或整批粘贴添加（一行一个）、备注、启停、排序、单把或批量删除；界面只显示脱敏形式
• 调度策略可配 —— 在余额优先与手动顺序之间切换，后者下列表顺序就是调度顺序
• 余额感知轮转 —— 剩余额度多的先用；余额三态（上限优先取 key.limit，为 null 时退回该密钥所属账号的 account.plan_limit；两级都明确为 null 才算无限并排最前，未知 → 垫底）
• 失败自动切换 —— 一把失败就交给下一把
• 冷却 —— 遵循上游 Retry-After；冷却期内硬排除，全部冷却时在预算内等待最早到期的一把
• 按状态码分别处理 —— 区分临时失败、密钥永久失效（看响应体，绝不只看状态码）与额度耗尽（432 / 433 同等处理：该密钥不被选中，直到 /usage 确认余额回升）
• 官方余额，使用时顺手刷新 —— 卡片上的积分是官方 /usage 的读数（上限 − 已用）。三种情形会自动重拉：本次真的被用到的那把读数已超过 1 小时、密钥刚添加、以及插件下一次被用到时把池内仍缺读数的密钥补齐。插件不做自己的积分记账：Tavily 的计费规则随时可能更改，本地算出来的数字会在某次规则调整后悄悄变成误导。两次读数之间的排序靠一个刻意粗糙、且从不作为独立数字展示的每次调用估算前推；它会推动界面上那个「已用」数字，因此卡片同时会说出「上次官方读数」有多旧。没有任何后台任务：不搜索、不抓取，就一次 /usage 都不会发
• 余额刷新 —— 拉取官方 /usage，按密钥做滑动窗口配额预占，不会触发 10 次 / 10 分钟的限流
• 搜索参数可配 —— 搜索深度、结果数上限、主题、是否生成答案，改动即时生效
• 抓取接管（默认关闭） —— 把 web_fetch 映射到 Tavily /extract，返回纯文本（绝不标成 HTML——那会让 DSH 再转换一次）；抽取深度与返回格式可配。想让 Tavily 也接管抓取时，在设置里打开它
• 调用历史与图表 —— 每次调用都留下记录（密钥、端点、结果、耗时、request_id），并画成 14 天的调用次数曲线；文件同时受条数上限与 30 天窗口约束
• 两个独立开关 —— 搜索与抓取可分别切回官方提供方
• 零运行时依赖 —— 纯 ESM，无构建步骤

已交付： spec 要的全部——搜索接管与它的开关、密钥池（单把录入、整批粘贴、批量删除）、 故障切换与冷却、搜索参数、调度策略、余额刷新、抓取接管与它自己的开关（默认关闭）、 调用历史与图表、每把密钥的调用统计与余额进度条、连通性测试，以及设置卡片及其 HTTP 接口。

安装

从 npm registry 安装：

dsh plugin add dsh-tavily-pool

或直接从 GitHub 安装——不需要 registry 账号。想要可复现的版本就 pin 住某个已发布的 tag， 可用的见 tags 页：

dsh plugin add github:stormbuf/dsh-tavily-pool
dsh plugin add github:stormbuf/dsh-tavily-pool#vX.Y.Z

两条路装到的文件相同：package.json 里的 files 白名单对 git 安装同样生效，因此不会捎带上 test/ 或 scripts/ 目录。

然后重启 DSH，打开 设置 → 插件 → dsh-tavily-pool，粘贴你的 Tavily API key。密钥只能通过面板录入——本插件不读取环境变量，也不读取 DSH 的 credentials 服务。

配置、调度行为、计费说明与手动回退步骤见 docs/usage.zh-CN.md。

兼容性

DeepSeek Harness 处于预览期，其架构与插件接口可能随版本变动。本插件把绝大多数宿主相关知识隔离在一层薄适配器（lib/dsh/）中，零构建客户端半边（lib/client.js）与 cordis.patch.yml 里的提供方 pin 另计；并在加载时探测宿主能力，使破坏性变更后的重适配成本保持低廉。

已测试版本：DSH 0.1.7-rc.2。 在更新的版本上可能需要重新适配；插件会在加载时探测宿主能力，报出明确指出缺失能力的错误，而不是静默失败。宿主 peer 区间只设下限，因此未经测试的 DSH 版本不会让插件拒绝加载——DSH 0.1.7 起新增了一道硬闸门，peer 区间不覆盖运行版本就整包跳过，一个过期的上限会变成「插件静默消失」。逐条重适配清单见 docs/dsh-upgrade.zh-CN.md。

经 dsh plugin add 安装后，本包会成为目标 profile 的一个 bundle 层（进入该 profile 的 dsh.profile.bundles，排在 DSH 各 bundle 之后），它的 cordis.patch.yml 因此能 pin 住提供方。 你自己的 profile patch 在所有 bundle 层之后应用，因此随时可以覆盖或停用本插件的行为—— 见手动回退。

许可

MIT