Yuuz12/dsh-tavily

dsh-tavily

用 Tavily 替换 DeepSeek Harness（DSH）官方网页搜索的持久化插件。

模型的 web_search 工具不再调用 DSH 内置的搜索提供方，而是改走 Tavily Search API。支持：

- 随时开关：在 设置 → 插件 → 插件配置 的「Tavily 搜索」卡片里一键切换；关闭后立即回落到官方搜索，无需重启。
- 多 API Key 池：添加任意多个 Tavily Key，分别查看每个 Key 的用量统计与余额。
- 余额优先轮流：自动按剩余额度排序，额度多的先用；剩余额度并列的密钥轮流使用。
- 手动顺序：也可切换为按自定义顺序从上到下使用。
- 失败自动切换（failover）：某把钥匙鉴权失败 / 额度用尽 / 限流时自动换下一把；硬失败会进入 5 分钟冷却（429 限流冷却 30 秒），沉到队尾。
- 用量统计：本地记录每个 Key 的调用数、成功/失败、积分消耗、最近错误与耗时；并可一键从 Tavily 官方 Usage 端点刷新真实余额。

零依赖、纯 JS、无构建步骤。

安装 / 卸载

使用者：从 npm 安装（推荐）
npx @deepseek-ai/dsh plugin --profile web add @yuuz12/dsh-tavily

维护者 / 本地开发（link 模式，改源码后重启 DSH 即生效）
npx @deepseek-ai/dsh plugin --profile web add D:/Project/dsh-tavily

使用者：从 GitHub 或 tarball
npx @deepseek-ai/dsh plugin --profile web add github:Yuuz12/dsh-tavily
npx @deepseek-ai/dsh plugin --profile web add ./yuuz12-dsh-tavily-0.1.0.tgz   # npm pack 产物

卸载
npx @deepseek-ai/dsh plugin --profile web remove @yuuz12/dsh-tavily

安装后重启 DSH 生效。目标 profile 若已装过旧版，先 remove 再 add。

关于 DSH 版本兼容：本插件 client 端依赖 @deepseek-ai/dsh-client-store（设置卡片渲染、createSnapshotStore）。该依赖对应 DSH ≥ 0.1.2-alpha.2（DSH Desktop 2.0.4）的客户端结构——更早版本没有这个包且使用已移除的 dsh-client-runtime，无法渲染设置卡片。

使用

打开 设置 → 插件 → 插件配置，展开「Tavily 网页搜索」卡片（与内置「终端」「Agent 循环」「网页搜索」卡片并列）。

使用步骤：

1. 粘贴一个或多个 Tavily API Key（在 app.tavily.com 免费注册即得，每把每月 1000 积分），点击添加密钥。
2. 点击密钥区右上角刷新全部用量拉取每个 Key 的官方余额数据。
3. 打开顶部的替换官方网页搜索开关——状态行显示「已接管网页搜索」即生效。

卡片内还可调整：多密钥策略（余额优先 / 手动顺序）、搜索深度（basic=1 积分、advanced=2 积分、fast、ultra-fast）、单次结果上限（1–20）、类别（general/news/finance）、AI 摘要回答（include_answer）。

多密钥调度规则

| 场景 | 行为 |
|---|---|
| 余额优先（默认） | 剩余积分多的先用；无限额度的计划最优先；从未刷新过用量的 Key 排在已知余额之后作兜底；头部并列的密钥按请求次数轮流 |
| 手动顺序 | 严格按列表自上而下（▲▼ 可调序），不做轮转 |
| 失败切换 | 任一密钥出错即尝试下一把；全部失败才向模型报错 |
| 冷却 | 401/403（鉴权失败）、432/433（超额）→ 5 分钟；429（限流）→ 30 秒；冷却中的密钥沉底但不会拒绝参与 failover |

每次成功调用的积分消耗（来自 Tavily 响应的 usage.credits）会即时累加到缓存的已用量上，让余额排序在不刷新的情况下也保持准确。

数据存储位置

| 安装方式 | 密钥/统计数据位置 | 开关与搜索参数位置 |
|---|---|---|
| link 本地目录 / junction | 插件目录下 dsh-tavily.json（见下方回退说明） | DSH 全局设置文档（~/.dsh/settings.yaml 的 dsh-tavily 节） |
| npm / GitHub / tgz | /dsh-tavily.json（用户数据，随 profile 持久） | 同上 |

- 密钥只存本机，绝不随 HTTP 响应返回完整内容（界面仅见 tvly-…xxxx 脱敏形式）。
- 升级 / 重装插件不会丢失密钥与统计；卸载插件也不会删除该文件，可手动备份或删除。
- 若插件目录被非常规加载（无法推导 profile 目录），数据文件会回退写到插件目录下的 dsh-tavily.json（已在 .gitignore 排除）。

与 dsh-webui-auth 的集成（安全）

DSH 的 webServer 按最长前缀派发路由，任何插件自定义前缀都会绕过网关级的统一认证前缀（如 dsh-webui-auth 守护的 /api、/plugins）。本插件对此做了自守卫：

- 启动时按以下顺序探测 dsh-webui-auth 的会话存储 sessions.jsonl：环境变量 DSH_WEBUI_AUTH_DATA_DIR → /node_modules/dsh-webui-auth/ → $DSH_HOME/dsh-webui-auth/ → 插件目录同级；
- 一旦找到，/dsh-tavily/* 全部端点要求有效的 dsh_wua_session 会话 Cookie（JSONL 重放校验，登出 / 改密撤销即时生效；浏览器同源请求自动携带，无感知）；
- 未找到（纯回环部署、未装认证插件）则保持开放。

日志中会出现「已启用 dsh-webui-auth 会话校验」一行表明守卫生效。

工作原理（替换机制）

DSH 的网页搜索走 ctx.web 能力缝：工具层每次执行时由 WebRuntime 解析搜索提供方——若配置了 searchProviderId 就用它，否则在“恰好只有一个可用提供方”时自动选择。本插件：

1. 通过公开 API ctx.web.registerSearchProvider() 注册 id 为 dsh-tavily 的搜索提供方；
2. 将实例字段 searchProviderId 重定义为可逆 accessor：开关开启且有可用密钥时读取值为 dsh-tavily，否则透传原基线值（未配置为 undefined；若设置了 $DSH_WEB_SEARCH_PROVIDER 环境变量则尊重之）。外部写入会更新基线；插件卸载时摘除 accessor 并还原原始属性描述符；
3. available() 与接管条件保持一致，因此即使未来版本不再读取该字段，自动选择也会优雅回落到官方提供方而不是报歧义错误。

Tavily 响应按 ctx.web 词汇投影：results[] → sources[]（url/title/snippet/publishedAt），answer → content。max_results 取工具请求与面板上限的较小值。

常见问题

- 开启后报 WEB_PROVIDER_AMBIGUOUS？ 说明当前运行时没有应用路由接管（见工作原理第 2 步的防御路径）。请反馈你的 DSH 版本；临时方案是关闭开关回到官方搜索。
- 没配 DeepSeek Key 的部署能用吗？ 能。此时本插件往往是唯一可用提供方，即使不依赖路由接管也能被自动选中。
- 测试按钮会花钱吗？ 会发起一次真实的 basic 搜索，消耗 1 积分。
- 多个 DSH profile 共享开关吗？ 开关存在全局 settings 文档里（跨 profile 共享）；密钥池按 profile 隔离。

开发与自检

node --check index.js && node --check lib/client.js   # 语法
node .scratch/selftest.mjs                            # 26 例离线自检（纯函数 + mock ctx 集成）

自检覆盖：配置归一化、密钥排序（余额/手动/冷却/轮转）、seam 响应映射、HTTP 路由表、注册与卸载还原、选择语义（含歧义防御）、failover 与积分记账、脱敏、持久化往返。

License

MIT