前言¶
DeepSeek Harness (DSH) 的 web_search 工具默认使用官方提供的搜索能力。在实际使用中，单一路由或单一提供方在额度管理、容错和灵活性上往往不够。dsh-tavily 插件通过 Tavily Search API 替换了 DSH 官方的网页搜索，提供多 API Key 管理、余额轮询和自动故障切换的能力。
这是什么¶
dsh-tavily 是一个用于 DeepSeek Harness 的持久化插件，由 Yuuz12 维护。它属于「联网工具」类别，遵循 MIT 许可证。
该插件旨在解决 DSH 官方网页搜索的单一性限制，允许用户在 DSH 界面中管理多个 Tavily Key，并根据余额或自定义顺序进行调用，同时具备本地用量统计和失败重试机制。
核心功能¶
- 替换官方网页搜索：在设置中切换后，模型调用
web_search工具时会走 Tavily API，关闭后自动回落到官方搜索。 - 多 API Key 池管理：支持添加任意数量的 Tavily API Key。
- 智能调度策略：
- 余额优先轮流：默认策略，按剩余额度排序，额度高的优先；额度并列的轮流使用。
- 手动顺序：支持自定义 Key 的使用顺序。
- 失败自动切换：当某把 Key 出现鉴权失败、额度用尽或限流（429）时，自动切换至下一把 Key。429 限流有 30 秒冷却，其他错误有 5 分钟冷却。
- 本地用量统计与刷新：本地记录调用次数、成功/失败及积分消耗，支持一键从 Tavily 官方接口刷新余额。
- 设置集成：配置项直接集成在 DSH 的「插件配置」界面卡片中。
- 安全集成：支持与
dsh-webui-auth集成，通过会话校验保护 API 端点。 - 零依赖：纯 JavaScript 实现，无构建步骤。
安装与启用¶
安装前请确保 DeepSeek Harness 版本不低于 0.1.2-alpha.2（DSH Desktop 2.0.4）。
使用官方推荐的 npm 安装命令：
npx @deepseek-ai/dsh plugin --profile web add @yuuz12/dsh-tavily
安装完成后必须重启 DSH 才能生效。如果已安装旧版本，建议先卸载再安装：
npx @deepseek-ai/dsh plugin --profile web remove @yuuz12/dsh-tavily
使用方法¶
- 打开 设置 → 插件 → 插件配置。
- 在卡片列表中找到「Tavily 网页搜索」并展开。
- 在密钥区域粘贴 Tavily API Key（可在 app.tavily.com 免费注册获取，每月 1000 积分），点击添加密钥。
- 点击密钥区右上角的刷新全部用量按钮，拉取每个 Key 的官方余额数据。
- 打开顶部的替换官方网页搜索开关。
- 调整多密钥策略（余额优先 / 手动顺序）、搜索深度、单次结果上限等参数。
多密钥调度规则¶
插件提供两种调度模式，具体行为如下：
| 策略 | 行为描述 |
|---|---|
| 余额优先（默认） | 剩余积分多的 Key 优先；无限额度的计划最优先；从未刷新过用量的 Key 排在已知余额之后作兜底；头部并列的密钥按请求次数轮流使用。 |
| 手动顺序 | 严格按列表自上而下使用，不做轮转。 |
| 失败切换 | 任一密钥出错时自动尝试下一把；全部失败才向模型报错。 |
| 冷却机制 | 401/403（鉴权失败）、432/433（超额）导致 5 分钟冷却；429（限流）导致 30 秒冷却。冷却中的密钥会沉底但继续参与 Failover。 |
数据与安全¶
- 存储位置：密钥与统计数据存储在本地。使用 npm 安装时，数据文件位于
<profile>/dsh-tavily.json。 - 隐私保护：密钥仅存储在本地，不会随 HTTP 响应返回完整内容。界面显示时已脱敏（如
tvly-…xxxx）。 - 数据安全：升级或重装插件不会丢失密钥与统计；插件卸载不会自动删除该文件。
- dsh-webui-auth 集成：插件会探测
sessions.jsonl文件以启用会话校验。若找到，所有/dsh-tavily/*端点将要求有效的dsh_wua_sessionCookie；未找到则保持开放。
结尾¶
dsh-tavily 通过引入多 Key 池和智能调度，为 DSH 用户提供了更可控的网页搜索能力。它不依赖外部构建工具，且所有敏感数据均本地化处理，适合需要精细管理搜索配额的场景。
