@memef1f1y/dsh-plugin-tavily

dsh plugin --profile web add @memef1f1y/dsh-plugin-tavily

dsh-plugin-tavily

[English](README.md) | 中文

基于 Tavily 的 web 搜索提供方插件，用于 DeepSeek Harness (dsh)。定位是面向进阶用户的专业版 Tavily 搜索插件：完整暴露 Tavily 请求参数，支持 WebUI 可视化调参与配置文件双模式。

它把 tavily 搜索提供方注册进 harness 的 ctx.web seam，让内置的 web_search 工具通过 Tavily 联网搜索；同时提供一张 设置卡片（设置 → 插件 → 网页搜索），在图形界面里粘贴 API Key、调节高级参数并测试连接。一次安装，两个半部。

功能

• 即装即用（无需手动配提供方）：安装本插件即通过其 cordis.patch.yml 自动把 web_search 提供方选为 Tavily。卡片里粘一个 Key 就能搜，无需改 yaml 或设 DSH_WEB_SEARCH_PROVIDER。
• Tavily/DeepSeek 引擎开关：GUI 开关让 web_search 由 Tavily（默认；无 Key 走 keyless）应答，或回退到官方 DeepSeek——无需卸载。这是真正切换提供方的开关，不是改配置。
• 服务端连通探针：POST /api/tavily-probe 让卡片能测试已保存的 Key（浏览器读不回已存密钥），无 Key 时走 keyless。
• 状态指示器：GET /api/tavily-status 用已保存的 Key 读取 Tavily GET /usage（不消耗搜索额度），卡片常驻显示 ✅ 正常 / ⚠️ 额度不足 / ✗ API 错误（或「未配置 Key」）徽标，由宿主机刷新、无需重新输入密钥。
• GUI 完整专业参数：API Key、API Base URL、maxResults、searchDepth（basic/advanced/fast/ultra-fast）、topic、includeAnswer、includeRawContent、timeout、days、chunksPerSource、timeRange、startDate/endDate、includeImages、includeDomains/excludeDomains、country 全部可在卡片编辑；高级参数收进默认折叠的 <details> 面板，普通用户不会被大量选项吓到。
• 参数预设模板：一键暂存一组高级参数——深度研究（advanced 深度、更多结果、返回原始内容）、快速摘要（basic 深度、少量结果、详细摘要）、新闻实时（news 主题、day 时间窗），点「保存」生效；被配置文件覆盖的字段自动跳过。
• 配置文件优先：cordis.patch.yml > WebUI > 代码默认值。yaml 显式设置的字段在卡片上置灰并显示「该参数已被配置文件覆盖」，WebUI 无法覆盖。
• API 连通测试：基础设置区提供独立「测试API连接」按钮，直接用当前填写的 key/baseUrl 发起轻量搜索并展示成功/报错信息，报错已分类（Key 无效 / 余额不足 / 限流 / 服务宕机 / 超时 / 网络）并给出对应解决文案。已保存的密钥因安全设计无法被浏览器读回，测试已配置密钥时需要重新输入一次（不会重复保存）。
• 用量与成本面板：卡片实时显示当前设置的每次搜索积分/token 预估，并提供「检查用量」按钮读取 Tavily GET /usage（剩余额度、搜索用量、套餐）。提供方另有宿主侧 usage() 方法可在已存密钥可用时读取同一数据。
• 页面抓取：基于 Tavily Extract 的 fetch 提供方（tavily-extract）从 URL 读取整页内容并返回干净的 text/html —— 选择一次后，URL 检索即由 Tavily 应答。
• 可选 Firecrawl 抓取：另一个 fetch 提供方（firecrawl）通过 Firecrawl POST /scrape（markdown、正文为主）抓取页面，适合 Tavily 提取质量差的页面。它有独立 id 与独立凭据（默认引用 FIRECRAWL_API_KEY）；搜索始终走 Tavily，Firecrawl 只负责 URL 检索。未选择时保持惰性。
• 持久化结果缓存：cacheFile 把 TTL/LRU 搜索缓存持久化到 JSON 文件（重启不丢；支持 ~/，相对路径按工作目录解析）。防抖、尽力而为——磁盘故障绝不阻断搜索。默认关闭。
• 限流重试与缓存：收到 429 后按 retry-after 做有界退避重试；可选 TTL 缓存让相同查询直接命中以节省额度——缓存带 LRU 上限（默认 200 条），且默认对时效敏感查询（news/finance 主题或任意时间窗口）完全跳过，「现在」类问题绝不命中陈旧快照。
• 精简调试日志：可选 debug 开关，每次搜索/抓取输出一行可读日志（查询节选、深度、积分、缓存状态、耗时、分类错误）——绝不记录密钥或原始响应体。
• 多密钥轮换 & 故障转移：apiKeyRefs 列出额外凭据引用（只存引用名，密钥仍在凭据库/环境变量中），与字面量 apiKey、apiKeyEnv 组成轮换环。搜索在 Key 级故障（429 / Key 无效 / 余额不足）时自动切到环中下一把 Key；连续失败 3 次的 Key 进入 60 秒冷却，保证健康 Key 接管。
• 脚注式引用（证据溯源）：citeFormat: footnote 在生成摘要后追加编号来源块（Sources:\n[1] 标题 — url…），模型可按编号引用来源；plain（默认）仅返回摘要原文。
• 自动兜底引擎：fallbackEngine: deepseek 在 Tavily 出现服务侧故障（超时 / 网络 / 5xx）时改由官方 DeepSeek 搜索应答；Key 级故障（429/401）不触发兜底——那是凭据问题，不是宕机。
• 凭据优先的密钥解析：每次搜索按 字面量 apiKey → 凭据服务（apiKeyEnv）→ process.env[apiKeyEnv] 的顺序解析。

安装

需要 dsh 0.2.0-rc.2 或更新版本（见下方「环境要求」）。从 npm 安装：

dsh plugin --profile web add "@memef1f1y/dsh-plugin-tavily"

开发期间可用本地路径安装：

dsh plugin --profile web add "file:/绝对路径/dsh-plugin-tavily"

或从仓库主分支安装（每次提交的最新状态）：

dsh plugin --profile web add "github:1624318455/dsh-plugin-tavily#main"

插件的 cordis.patch.yml 会把 web.config.searchProvider 设为 tavily，即自动选 Tavily 为提供方（无需手动改配置）。

启用

1. 安装并重启 dsh。插件已替你设置 web.config.searchProvider: tavily，无需手动选择提供方。

2. 设置 Tavily API key（可选）。打开 设置 → 插件 → 网页搜索，展开 网页搜索（Tavily） 卡片，把密钥粘贴进 API Key 输入框。没有 Key 时 Tavily 走 keyless（免费、限流），有 Key 走账号档。在 网页搜索引擎 开关里选 Tavily（默认）或 官方 DeepSeek。

3. 照常使用 web_search。面向模型的工具不变，只是后端换成 Tavily（或你切到的 DeepSeek）。

若日后你想在 yaml 里手动覆盖提供方，对应行是：

# ~/.dsh/profiles/web/cordis.patch.yml
- id: web
  config:
    searchProvider: tavily

启用抓取（Extract）提供方（可选）

插件同时注册一个基于 Tavily Extract 的 fetch 提供方（tavily-extract），用于从 URL 读取整页内容。默认不启用，需像搜索提供方一样选择：

export DSH_WEB_FETCH_PROVIDER=tavily-extract

或在 cordis.patch.yml 中：

- id: web
  config:
    searchProvider: tavily
    fetchProvider: tavily-extract

如需改用可选的 Firecrawl 页面抓取（需要自己的 Key，默认凭据引用 FIRECRAWL_API_KEY）：

export DSH_WEB_FETCH_PROVIDER=firecrawl

或把上面同一行的 fetchProvider 改为 firecrawl。未配置 Firecrawl Key 时，抓取会报 WEB_PROVIDER_CREDENTIAL_MISSING，其余时间保持惰性。

验证后端确实是 Tavily

web_search 工具的输出 schema 与提供方无关 —— 模型看不到提供方名称，且 API key 刻意存放在环境变量之外，所以"查环境变量"是错误探测方式。要确认当前后端：

• 提供方选择 —— ~/.dsh/profiles/web/cordis.patch.yml 中有 web 行且 searchProvider: tavily。
• 插件已加载 —— 组合后的 profile 树里存在 web-search-tavily 条目（dsh --profile web --dump-config）。
• 凭据在位 —— TAVILY_API_KEY 存在于凭据存储（~/.dsh/.credentials.yaml），不在环境变量中。
• 结果特征 —— Tavily 结果在 content 中携带生成式 answer 摘要；内置 DeepSeek provider 不产生该字段。

故障排查：仍然看到「没有 DeepSeek API key」报错

本插件现已自动选 Tavily（web.searchProvider: tavily），新装即由 Tavily 应答 web_search，正常使用不该再出现此错。若仍看到 DeepSeek key 报错：

• 你把引擎切到了「官方 DeepSeek」却没配 DeepSeek key。把卡片的「网页搜索引擎」切回 Tavily（或配置 DeepSeek key）。
• 你在 yaml 里覆盖了提供方。确保没有更靠后的 web patch 行把 searchProvider 指回 deepseek（插件自己的行已选 tavily）。
• 这是 agent/assistant 环境。聊天应用自己的 web_search 是另一套 web seam、并未安装本插件——它始终用默认 DeepSeek 后端，与你的 Tavily 安装无关。

🖥️ 图形界面使用（推荐普通用户）

打开 设置 → 插件 → 网页搜索，展开 网页搜索（Tavily） 卡片。

• 基础设置（默认展开）：
• 状态指示器 —— 常驻徽标（✅ 正常 / ⚠️ 额度不足 / ✗ API 错误 / 未配置 Key），由宿主机用已保存的 Key 检查（GET /api/tavily-status 读取 GET /usage，不消耗搜索额度）；「刷新」按钮强制重查（自动检查限每分钟一次）。
• 网页搜索引擎 —— Tavily（默认；无 Key 走 keyless）或 官方 DeepSeek。这是真正的提供方开关；插件已被自动选为提供方。
• API Key —— 粘贴你的 Tavily 密钥。密钥经凭据服务写入，绝不进入设置文件。
• API Base URL —— 留空使用 https://api.tavily.com；可填代理/自定义接口地址。
• 参数预设 —— 一键应用「深度研究 / 快速摘要 / 新闻实时」：多个高级字段被同时暂存（被配置文件覆盖的字段跳过），点「保存」生效。
• 测试API连接 —— 验证当前输入的 key/baseUrl；失败会分类提示（Key 无效 / 余额不足 / 限流 / 服务宕机 / 超时 / 网络）并附解决建议。测试会消耗一次 Tavily 搜索额度。如果已配

…(truncated)