@zyfgood/dsh-web-search-tavily

DeepSeek Harness（DSH）插件：把 web_search 的搜索后端从 DeepSeek 云换成
Tavily API。

> npm 包名：@zyfgood/dsh-web-search-tavily（配置里插件行的 name: 也必须写这个名字）。
> 注意 npm 上另有一个同名非 scope 包 dsh-web-search-tavily（他人维护），二者无关。

• 省配额：DSH 默认的 deepseek-official 搜索后端每次搜索 = 一次完整模型调用
  （烧 DeepSeek API 配额）；换 Tavily 后走 Tavily 独立配额（免费 1000 次/月）。
• 多 key 轮换：apiKey 支持逗号分隔多个 key（Hermes 同款 sticky 行为）——
  401/403/429/5xx 自动切下一个 key，成功后粘住；400 等坏请求 fail fast。
• 零侵入：走 ctx.web 官方 provider seam（registerSearchProvider），
  不改动 DSH 任何上游文件；与官方 dsh-web-search-exa / perplexity 同一模式。
• 密钥不落盘：apiKey 支持 env:VAR 引用，兜底读启动环境 $TAVILY_API_KEY。

English Summary

dsh-web-search-tavily replaces the DeepSeek Harness web_search backend with
the Tavily Search API — search stops costing a DeepSeek
cloud model call per query (Tavily free tier: 1000 credits/month).

Features

• Provider seam: registers a tavily search provider via ctx.web —
  no upstream DSH files modified (same pattern as the official
  dsh-web-search-exa / perplexity providers).
• Multi-key rotation: comma-separated apiKey values; sticky-first order,
  rotate on 401/403/429/5xx and transport errors, fail fast on 400s.
• Config: apiKey (env:VAR supported, falls back to $TAVILY_API_KEY),
  baseURL, searchDepth (basic/advanced), maxResults, includeAnswer.
• Cancel-safe: AbortSignal mapped to WEB_ABORTED; redirects and
  non-JSON error bodies surface as proper WebErrors.

Install

# Git channel (repo root is the plugin)
dsh plugin --profile  add "github:zyfgood/dsh-web-search-tavily#main&path:/"
# npm channel
dsh plugin --profile  add @zyfgood/dsh-web-search-tavily

Set TAVILY_API_KEY in the launch environment (e.g. ~/.dsh/.env), restart
dsh web, and web_search returns Tavily results. Manual mounting and every
config option: see the Chinese sections below.

License: MIT.

机制

DSH 的 web 能力是 provider seam（ctx.web.registerSearchProvider）。本插件注册
一个 tavily provider（POST /search，Bearer key），再把 web 行的
searchProvider 切到 tavily：

web_search 工具 (dsh-tool-web)
→ ctx.web.search()              # provider 可插拔 seam
→ searchProvider: tavily        # 本插件（原来是 deepseek-official）

字段映射：Tavily results[].content → snippet，published_date → publishedAt，
score 不可移植丢弃；可选的 answer（includeAnswer: true）→ 结果 content。
无 URL 或既无内容又无标题的脏结果直接丢弃。

安装

方式一：官方 CLI 一条命令安装（推荐）

# 安装前设置密钥环境变量（也可装后再设，重启前配置好即可）
export TAVILY_API_KEY=tvly-xxx      # Windows: 写入 %USERPROFILE%/.dsh/.env

dsh plugin --profile  add "github:zyfgood/dsh-web-search-tavily#main&path:/"
# 或 npm 渠道（已发布到 npmjs.org）：
dsh plugin --profile  add @zyfgood/dsh-web-search-tavily

> DeepSeek Harness Desktop 用户的 profile 名为 desktop，即
> dsh plugin --profile desktop add @zyfgood/dsh-web-search-tavily。

包内自带 cordis.patch.yml（dsh.bundle.patch），CLI 安装时自动挂载：插入插件行
并把 web 行切到 searchProvider: tavily，无需手工编辑配置文件。装完重启
dsh web 生效。

方式二：手工挂载（适用于任何托管位置）

1. profile package.json：

"dependencies": { "@zyfgood/dsh-web-search-tavily": "file:/path/to/dsh-web-search-tavily" },
"dsh": { "profile": { "bundles": [ "...", "@zyfgood/dsh-web-search-tavily" ] } }

2. %USERPROFILE%/.dsh/.env 加 TAVILY_API_KEY=tvly-xxx（loadLayeredEnv 启动注入）
3. profile cordis.patch.yml（完整示例见 cordis.patch.example.yml）：

- insert:
- id: web-search-tavily
name: '@zyfgood/dsh-web-search-tavily'
config:
apiKey: 'env:TAVILY_API_KEY'
- id: web
name: '@deepseek-ai/dsh-web'
config:
searchProvider: tavily
fetchProvider: http

（⚠️ - id: web 的 config 是整键替换：覆盖必须同时带 fetchProvider: http，
否则 web_fetch 丢失。）

配置项

验证要点

• 启动日志无 web-search-tavily 相关 warning / did not activate
• 会话事件里不再出现 web/deepseek-search-llm-request
• web_search 工具返回 Tavily 结果（标题/snippet/日期为 Tavily 口径）

常见问题

• 搜索报 WEB_PROVIDER_UNAVAILABLE：TAVILY_API_KEY 未设置或 apiKey 为空
  （env:VAR 引用的变量未设置时插件会直接报错指明变量名）。
• WEB_PROVIDER_AMBIGUOUS：web 行没固定 searchProvider 且同时有多个可用
  provider —— 确认 - id: web 覆盖行存在且带 searchProvider: tavily。
• invalid key / HTTP 401：key 无效；配了多 key 会自动轮换，全部失效才报错。
• 想切回 DeepSeek 官方搜索：把 web 行的 searchProvider 改回
  deepseek-official（或删掉本插件覆盖行恢复 base bundle 默认）。

开发与构建

npm install                      # 安装依赖（@deepseek-ai/* 已钉在 0.2.0-rc.2 作类型检查用）
npm run build                    # tsc → lib/
npm test                         # 冒烟测试（mock，不打网络）
TAVILY_API_KEY=xxx npm test -- --live   # 真实 API 验证（可选）

> DSH 版本兼容：本包在 DSH 0.2.0-rc.2（DeepSeek Harness Desktop 0.2.0-rc.2）上
> 验证通过，engines.dsh 与 @deepseek-ai/dsh-* peer 范围均声明为
> >=0.2.0-rc.2 <0.3.0-0。DSH 安装期用它做兼容性预检（不满足直接拒绝安装），
> 换到其它 DSH 版本时按实测结果调整该范围。
>
> 仓库中的 lib/ 为已构建产物（开箱即用）；修改 src/ 后运行 npm run build
> 重新生成。编译期类型依赖（@deepseek-ai/dsh-web 等 peer 包）通过仓库 checkout
> 的 node_modules 解析（dev junction）；运行时由 DSH loader 的
> installation-scope 解析，无需 profile node_modules 里有这些包。

源码结构：

• src/index.ts — 插件入口（Config 校验、env:VAR 密钥解析、provider 注册）
• src/provider.ts — TavilySearchProvider（多 key sticky 轮换、错误映射、取消）
• src/types.ts — Tavily wire 类型（仅本 provider 读取的字段）
• tests/smoke.mjs — 冒烟测试（npm test）
• cordis.patch.example.yml — profile patch 配置示例

License

MIT