dsh-web-search-tavily

面向 DeepSeek Harness（DSH）的 Tavily 搜索提供方插件，让 DSH 内置的 web_search 工具实际走 Tavily Search API。

这是什么

DSH 的 web_search 工具与具体搜索服务解耦，通过中间层 ctx.web 工作：

• @deepseek-ai/dsh-tool-web 只定义 web_search 工具的 schema、校验与展示，不碰搜索服务；
• 真正执行搜索的是注册到 ctx.web.registerSearchProvider(provider) 的「搜索提供方」；
• 通过 web 段配置 searchProvider（或环境变量 DSH_WEB_SEARCH_PROVIDER）选择提供方。

DSH 开箱只带一个搜索提供方 @deepseek-ai/dsh-web-search-deepseek（走 DeepSeek 的 Anthropic 兼容 Messages API），没有内置 Tavily。本项目补齐了这块：安装并接线后，即可把 web_search 切换到 Tavily。

特性

• 原生 fetch 直连 POST https://api.tavily.com/search
• results[] → sources[]、answer → content 的规范化映射
• 复用 DSH 的 credential seam（credentialRef），密钥只以引用形式出现、绝不明文写死
• 完整错误路径（缺失 key / 网络失败 / 取消），遵循 WebError 错误码规范
• 全程转发 AbortSignal 用于取消
• 纯 JS 实现、零构建步骤，函数/命名空间插件（inject: ['web']）

架构

本项目实现的是 seam 定义的 WebSearchProvider 接口：

interface WebSearchProvider {
  readonly id: string              // 本项目注册为 'tavily'
  available(): boolean             // 廉价本地检查，禁止发网络请求
  search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
}

安装

前置条件

• 已安装 DSH，并有一个 profile（下文以 web profile 为例）
• Node.js（DSH 运行环境自带）

步骤 1：安装插件

本地源码 / GitHub clone 后

# clone 本仓库后，把本地路径装进 profile
dsh plugin --profile web add file:D:/path/to/dsh-web-search-tavily

dsh plugin 底层就是转发给 pnpm；若未安装 pnpm，可等价地直接执行 npx pnpm add file:D:/path/to/dsh-web-search-tavily（在 profile 目录下）。

步骤 2：接线

编辑 profile 的补丁层（不是 node_modules 里的配置）：

• 路径：$DSH_HOME/profiles/web/cordis.patch.yml
• Windows 默认：C:\Users\<用户名>\.dsh\profiles\web\cordis.patch.yml

# 新增 Tavily 搜索提供方
- insert:
    - id: web-search-tavily
      name: '@deepseek-ai/dsh-web-search-tavily'
      config:
        apiKeyEnv: TAVILY_API_KEY

# 把 web 段的 searchProvider 从 deepseek-official 改为 tavily
- id: web
  name: '@deepseek-ai/dsh-web'
  config:
    searchProvider: tavily

步骤 3：配置 API Key

三种方式任选其一（优先级：启动环境变量 > credentials 文件 > .env）：

A（推荐）：写入 DSH 凭据文件 $DSH_HOME/.credentials.yaml（Windows 默认 C:\Users\<你>\.dsh\.credentials.yaml）：

TAVILY_API_KEY: tvly-你的key

B（持久环境变量，最高优先级）：

setx TAVILY_API_KEY "tvly-你的key"

C（临时，仅当前终端）：

$env:TAVILY_API_KEY = "tvly-你的key"

步骤 4：重启并验证

重启 DSH（关闭运行中的控制台窗口 / Ctrl+C，再按原方式启动），然后让模型执行一次 web_search（例如问「今天有什么新闻」）：

• 正常：结果来源来自 Tavily（返回 answer + sources[]）
• 故意不设 key：报 WEB_PROVIDER_CREDENTIAL_MISSING —— 这恰好证明选择逻辑已切到 Tavily，而非静默回退 DeepSeek

配置项

请求与映射

• 端点：POST https://api.tavily.com/search
• 请求头：Content-Type: application/json、Authorization: Bearer <TAVILY_API_KEY>
• 请求体：

{
  "query": "<query>",
  "search_depth": "advanced",
  "max_results": 8
}

响应映射：

truncated 恒为 false：provider 不主动截断，maxResults 由 seam 统一截断并置位。max_results 在请求层设置仅是成本/延迟优化。

错误码

项目结构

dsh-web-search-tavily/
├── package.json
├── README.md
└── lib/
    ├── index.js            # 插件入口 + provider + 映射 + 错误/取消助手
    └── types/
        ├── index.d.ts      # 插件导出 + Config 接口
        ├── provider.d.ts   # TavilySearchProvider + Options
        └── types.d.ts      # Tavily 线上响应/错误类型

License

MIT