libinghui55/dsh-tavily-search

dsh-tavily-search

一个由 Tavily 提供支持的 网页搜索提供程序 插件，用于
DeepSeek Harness（dsh）。它将 harness 的
网页搜索接缝路由到 Tavily API，并在 设置 → 插件 中附带一个 GUI 配置卡片，
你可以在其中开启/关闭该提供程序并存储你的 Tavily API 密钥。

一切皆插件：此包组合了一个 Cordis 宿主插件（搜索提供程序）和一个 Web 客户端
bundle（设置卡片）。

功能特性

- 注册一个 id 为 tavily 的网页搜索提供程序，并通过 bundle 补丁
（cordis.patch.yml）将 harness 的网页接缝指向它。
- 名为 tavily-search 的 GUI 配置卡片（设置 → 插件），包含：
- 一个 开/关开关 —— 关闭时，提供程序报告自身不可用并拒绝搜索；
- 一个 API 密钥字段，通过 harness 凭据服务写入（绝不存储在设置文件中，
也绝不回显给客户端）。
- API 密钥解析顺序：
1. 在 web-search-tavily 设置区段中配置的字面量 apiKey；
2. harness 凭据服务，位于由 apiKeyEnv 命名的凭据引用下
（默认 TAVILY_API_KEY）；
3. 启动环境（TAVILY_API_KEY）。
- 可通过 baseURL 配置 Tavily 端点（默认 https://api.tavily.com）。

要求

- 一个已组合网页搜索接缝的 DeepSeek Harness（dsh）安装。
- 来自  的 Tavily API 密钥。

安装

dsh 插件是一个 通过 profile 的 dsh.profile.bundles 层栈组合进 profile 的
npm 包 —— 不存在可放入文件夹的单独“插件目录”。此包所需的一切都在其自身的
dependencies 中声明（固定为精确版本，见 package.json），因此向 profile 中
执行一次安装即可。

请以网页搜索接缝已组合的 profile 为目标 —— 默认的 web profile（bundle 为
@deepseek-ai/dsh-base + @deepseek-ai/dsh-web-app）是通常的选择。

从源码检出开始：

git clone https://github.com/libinghui55/dsh-tavily-search.git
cd dsh-tavily-search
npm ci

然后使用 dsh CLI 将该包添加到 profile：

dsh plugin --profile web add

（ 可以是绝对路径、link:...、git 规格，或者如果
你发布了它，也可以是 npm 注册表名称。）

dsh plugin 会做什么：

1. 在首次使用时初始化 profile。
2. 在 profile 目录内运行 pnpm add ，将该包（及其精确固定的依赖项）
安装到 profile 的 node_modules 中。
3. 根据已安装状态协调 profile 的 dsh.profile.bundles 层栈：任何已安装且其
清单声明了 dsh.bundle 的依赖项 —— 本包即是如此 —— 都会 *按依赖顺序作为
profile 层追加，之后执行 dsh plugin --profile web remove
dsh-tavily-search 会将其移除。
因为这个包声明了 dsh.bundle.patch: ./cordis.patch.yml，加入层栈时会引入捆绑的补丁，该补丁会：

1. 设置 web.searchProvider = tavily，使 web 接缝通过 Tavily 进行搜索；
2. 插入一行 web-search-tavily 宿主插件，其配置将 apiKeyEnv 指向 TAVILY_API_KEY。

手动替代方案（不使用 dsh CLI）

手动将包添加到目标配置文件的 package.json，并在该目录下运行 pnpm install：

{
"dependencies": { "dsh-tavily-search": "0.1.0" },
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-tavily-search"] } }
}

在配置文件中运行 pnpm install 会将其实体化，并且由于该包列在 dsh.profile.bundles 中，harness 会应用 cordis.patch.yml。

提供你的 API 密钥

选择以下其中一种方式：

A. GUI（推荐） — 打开 设置 → 插件，展开 tavily-search，在 API key 字段中输入你的密钥，然后点击 Save。密钥会通过 harness 凭据服务写入（例如 ~/.dsh/.credentials.yaml）。

B. 凭据文件 — 在凭据存储中添加一行：

TAVILY_API_KEY: tvly-xxxxxxxx

C. 环境变量 — 在启动环境中导出 TAVILY_API_KEY。

关于环境变量遮蔽的说明： 如果进程环境中存在 TAVILY_API_KEY，凭据服务会将其报告为继承的（writable: false），因此 GUI 卡片会禁用其密钥字段——来自环境变量的值无法从 UI 覆盖。如果你想从卡片中编辑密钥，请将其存储在文件中（选项 A 或 B），而不是环境变量中。

配置

该插件拥有一个设置命名空间 web-search-tavily，其 schema 如下：

| 字段       | 类型     | 默认值                 | 描述                                          |
| ---------- | -------- | --------------------- | -------------------------------------------- |
| enabled  | boolean  | true                | 主开关；false 会使提供程序不可用。          |
| apiKey   | secret   | —                     | 字面 API 密钥（通过凭据写入）。               |
| apiKeyEnv| string   | TAVILY_API_KEY      | 未设置字面密钥时解析的凭据引用。              |
| baseURL  | string   | https://api.tavily.com | Tavily 端点覆盖。                          |

示例 .yml 配置：

dsh.config / bundle patch
web-search-tavily:
enabled: true
apiKeyEnv: TAVILY_API_KEY

包内容

- index.js — 宿主侧 web 搜索提供程序（TavilySearchProvider）以及 web-search-tavily 设置部分。
- client.js — web 客户端包：插件配置卡片（settings.plugin.item 插槽，以 web-search-tavily 命名空间为键）。
- cordis.patch.yml — 将提供程序捆绑到 web 接缝中并解析 API 密钥引用。

开发

从已安装该插件的配置文件中运行离线冒烟测试（它会导入配置文件中安装的副本，以便 @deepseek-ai/ 依赖能够解析）。该
smoke 脚本是一个仅限本地、被 gitignore 忽略的辅助工具；将它指向安装了该包的 profile：

node /node_modules/dsh-tavily-search/smoke.mjs

该测试验证：provider id 为 tavily、可用性、一次真实的 Tavily 搜索，以及 enabled: false 会使该 provider 不可用并拒绝搜索。

由于 Web 客户端由其自身的 bundle 提供服务，对 client.js 的更改需要重启 harness，才能被 dsh-client-modules 重新加载。

许可证

MIT