搜索中枢 Bin-top1/dsh-searchhub

🔍 dsh-searchhub

🇨🇳 中文说明（点击展开完整中文文档）

别再为 Agent 的联网搜索花钱了

dsh-searchhub 是给 DeepSeek Harness (DSH) 用的可插拔搜索中枢。它让你的 Agent 通过市面主流、即插即用的搜索服务商（挂在 DSH 的 web 能力接缝 ctx.web 后面）来联网搜索，而不用每次 web_search 都消耗付费的 DeepSeek 模型调用。

💸 不用再为搜索付费。 把内置的 web_search 工具接到真正的搜索 API，把模型预算留给真正的思考。

🧩 可插拔设计。 一个中枢，多家服务商。目前内置 Tavily；架构从一开始就为后续接入更多主流搜索引擎而设计——挑你喜欢的，随时替换。

🎁 免费起步。 Tavily 每月赠送 1000 个免费额度，无需信用卡即可开始，日常 Agent 检索完全够用。

✨ 做得精美。 不是一个干巴巴的配置开关——dsh-searchhub 自带手工打造的原生设置卡片：可折叠、带实时三态状态圆点、真正的显示/隐藏眼睛按钮、即时的密钥格式校验，以及一个可点击的取密钥链接。它看起来就像产品自带的功能，因为它就是照着这个标准做的。

📸 原生设置卡片

这是它在 设置 → 插件 里自带的精美卡片——实时状态圆点、真正的显示/隐藏按钮、行内格式校验，看起来就像产品原生功能。界面语言切到中文时，卡片文案全中文（对比上方英文效果，绝不混杂）：

✨ 功能亮点

- 🔌 可插拔搜索中枢 —— 干净的 provider 接缝，主流搜索引擎都能挂到 ctx.web 后面。目前内置 Tavily，并预留扩展空间。
- 💰 零模型调用成本 —— 替换内置的 web-search-deepseek provider，让 web_search 打到真正的搜索 API，而不是一次付费模型调用。
- 🎨 自带精美原生卡片 —— 在 设置 → 插件 → 插件配置 里作为独立、可折叠的卡片出现（端点、搜索深度、结果数、答案开关、API 密钥），带实时状态圆点、眼睛按钮、行内密钥格式校验。
- 🔐 密钥处理得当 —— API 密钥作为凭据引用存储（默认 TAVILY_API_KEY），从界面或环境变量录入，永远不必写进配置文件。
- ⚡ 一条命令安装 —— 以 dsh bundle 形式发布，npx @wilson.liu.cn/dsh-searchhub install 会用 npm（不需要 pnpm）装包并把本包写进 dsh.profile.bundles，无需手改 profile 的 patch 文件。
- 🧭 结果归一化 —— 把 provider 结果映射成接缝已认识的 { sources, truncated } 结构。

🚀 安装

方式 A —— 从 npm 安装（推荐，不需要 pnpm）

npx @wilson.liu.cn/dsh-searchhub install --profile web

这条命令从 npm registry 下载本包（@wilson.liu.cn/dsh-searchhub）并自动完成「安装 + 激活」。想只用 npm 手动装，见下方方式 B。

从本仓库 checkout 直接装（开发本插件时用，不经过 npm）：

node scripts/cli.mjs install

这一步会做三件事（就是 dsh plugin 的三步，但只用 npm）：

1. $DSH_HOME/profiles/web 不存在时，按 DSH 自己的模板初始化（package.json + cordis.patch.yml + pnpm-workspace.yaml）；
2. 在该目录里用 npm 安装本插件；
3. 把本包追加进 profile 的 dsh.profile.bundles 层列表，于是它的 cordis.patch.yml（把 ctx.web 切到 Tavily、禁用 web-search-deepseek、注册本插件的宿主端 + 浏览器端）在下次启动时生效。

常用子命令：

npx @wilson.liu.cn/dsh-searchhub status # 是否已安装 / 是否已激活 / 密钥是否配置
npx @wilson.liu.cn/dsh-searchhub install --dry-run # 只打印计划，不做任何改动
npx @wilson.liu.cn/dsh-searchhub uninstall # 卸载，并自动从 bundles 里摘掉
npx @wilson.liu.cn/dsh-searchhub install --spec github:Bin-top1/dsh-searchhub
npx @wilson.liu.cn/dsh-searchhub install --spec /path/to/dsh-searchhub # 本地 checkout：自动打包成 tarball 再装

然后重启 web profile（dsh web 或 dsh --profile web），打开 设置 → 插件，在 SearchHub 卡片里填入密钥（或导出 TAVILY_API_KEY）。

为什么不用 dsh plugin add？ dsh plugin 是 pnpm 的转发器（内部 spawnSync("pnpm", …)），机器上没有 pnpm 会直接失败。本安装器用你手上的 npm 完成同样的三步。

为什么 --spec 指向目录时先打包？ npm 对本地目录会建软链接，而软链接包的 @deepseek-ai/ 依赖会从仓库真实路径解析——那里没有宿主提供的这些包（或只有一份重复的），插件会加载失败。先打包成 tarball 再把副本装进 profile，依赖就会从 profile 向上走到 DSH 安装自己的依赖闭包，不会出现重复实例。

方式 B —— 手动 npm 安装 + 一行 bundles

cd "$DSH_HOME/profiles/web"
npm install @wilson.liu.cn/dsh-searchhub

然后把包名加进该 profile 的 dsh.profile.bundles（DSH 就是靠这个列表装配插件层的）：

"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@wilson.liu.cn/dsh-searchhub"]
}
}

方式 C —— 直接用 dsh plugin（需要 pnpm 在 PATH 上）

dsh plugin --profile web add @wilson.liu.cn/dsh-searchhub

方式 D —— 纯手工 patch（不写 bundles 列表也能生效）

$DSH_HOME/profiles/web/cordis.patch.yml
- id: web
config:
searchProvider: tavily
fetchProvider: http
- id: web-search-deepseek
disabled: true
- insert:
- id: searchhub
name: "@wilson.liu.cn/dsh-searchhub"

⚠️ 不要写 name: "file:///…/dsh-searchhub/lib/index.js" 去直接引用仓库里的文件：插件加载时会从仓库真实路径去找宿主提供的 @deepseek-ai/ 包，实测会 ERR_MODULE_NOT_FOUND。要用本地 checkout，请用方式 A 的 --spec <checkout>（先打包再安装）。

⚙️ 配置项

| 键 | 类型 | 默认值 | 说明 |
| apiKey | secret 字符串 | - | 明文密钥（建议改用 apiKeyEnv）。 |
| apiKeyEnv | 凭据引用 | TAVILY_API_KEY | 密钥存储所用的环境变量名。 |
| baseURL | 字符串 | https://api.tavily.com | Tavily API 基址；会追加 /search。 |
| searchDepth | basic \| advanced | basic | 越深消耗 Tavily 额度越多。 |
| maxResults | 数字 (1-20) | 5 | 每次查询请求的结果数。 |
| includeAnswer | 布尔 | false | 是否让 Tavily 附带生成式答案。 |

设置 API 密钥（三选一）：1) 原生设置卡片——在 设置 → 插件 → 插件配置 的 SearchHub 卡片里粘贴密钥，经凭据服务加密存储；2) 环境变量——启动 DSH 前导出 TAVILY_API_KEY；3) 明文配置——直接设 apiKey（不推荐）。在 <https://app.tavily.com/> 免费获取密钥与每月 1000 额度。

🌏 界面语言

设置卡片自带 英文 / 中文 两套完整文案，跟随 DSH 的界面语言自动切换——界面是中文就全中文、是英文就全英文，绝不中英混杂。

🛠️ 从源码构建

仓库已附带预构建的 lib/index.js（宿主端）与 lib/client.js（浏览器端），安装和使用都不需要构建：npm 只发布 lib/.js、scripts/cli.mjs、cordis.patch.yml 与文档。

只有维护者需要跑构建（生成类型声明）：

npm install # 仅 typescript 与宿主类型包，都是 devDependencies
npm run build # tsc -p tsconfig.json → lib/types/.d.ts
npm test # 安装器行为 + 打包不变量测试

宿主端类型源码在 src/types/，npm run build 产出 .d.ts（npm publish 前由 prepublishOnly 自动执行）；浏览器端 lib/client.js 是唯一权威手写源，按 DSH 客户端模块扫描器所需的注册形式编写（React 与 JSX runtime 由宿主种子经 require 提供），无需打包器，也没有一份会漂移的 .ts 副本。

🗺️ 路线图

dsh-searchhub 是一个中枢，而不是绑死单一引擎的壳子。Tavily 只是第一个 provider；接缝刻意做得通用，因此更多主流搜索后端都能挂到同一张卡片、走同一套 ctx.web 契约接入。欢迎贡献新的 provider。

以下为英文完整文档。

别再为智能体的网页搜索付费了。

dsh-searchhub 是 DeepSeek Harness (DSH) 的可插拔搜索中枢。它让你的智能体通过主流、开箱即用的搜索服务商搜索网页，全部走 DSH 网页能力接缝（ctx.web）——而不是烧掉付费的 DeepSeek 模型每次调用 web_search 都要开启一轮模型推理。

💸 不用再为搜索付费了。 把智能体内置的 web_search 工具指向真正的搜索 API，把模型开销留给真正的思考。

🧩 天生可插拔。 一个中枢，多个服务商。目前内置 Tavily；架构上会陆续接入市面上更多主流搜索引擎——挑你喜欢的那款换进来就行。

🎁 免费起步。 Tavily 每月送你 1,000 免费额度——开卡就能用，不用绑信用卡。日常智能体调研足够用了。

✨ 打磨到位。 不像那种光秃秃的配置开关，dsh-searchhub 自带亲手写的原生设置卡片——可折叠，带实时三态状态点、真正的显示/隐藏眼睛开关、即时的密钥格式校验，还有一条能点开去领密钥的链接。它看起来就像产品原生的，因为它本来就是照着这个标准做的。

📸 原生设置卡片

在 Settings → Plugins 下有它自己的精致卡片，带实时状态点、真正的显示/隐藏开关和行内校验——看起来就像产品原生的：

✨ 功能

- 🔌 可插拔搜索中枢——干净的 provider 接缝，主流搜索引擎都能换到 ctx.web 后面。目前已内置 Tavily，后续还有扩展空间。
- 💰 零模型轮次开销——替换内置的 web-search-deepseek provider，让 web_search 直接打真正的搜索 API，而不是烧一轮付费模型推理。
- 🎨 自带精致原生卡片——出现在 Settings → Plugins → Plugin configuration 下，是一张独立可折叠的卡片（endpoint、搜索深度、最大结果数、answer 开关、API key），带实时状态点、眼睛开关和行内密钥格式校验。
- 🔐 密钥处理得当——API key 以凭据引用形式存在（默认 TAVILY_API_KEY），从 UI 或环境变量填入；不必写死在配置文件里。
- ⚡ 一条命令安装——以 dsh bundle 形式发布，npx @wilson.liu.cn/dsh-searchhub install 用 npm 就能装（不需要 pnpm），并自动追加到 dsh.profile.bundles。不用手动改 profile patch 文件。
- 🧭 结果归一化——把各服务商的结果映射成接缝约定的 { sources, truncated } 结构，智能体本来就能看懂。

🚀 安装

方案 A —— 从 npm 安装（推荐，不需要 pnpm）

npx @wilson.liu.cn/dsh-searchhub install --profile web

这条命令会从 npm registry 下载包（@wilson.liu.cn/dsh-searchhub）并安装 + 激活。想用纯 npm 安装，见方案 B。

从本地检出安装（开发这个插件本身时）：

node scripts/cli.mjs install
它执行的三步和 dsh plugin 一样，只是用你机器上真正有的包管理器：

1. 当 $DSH_HOME/profiles/web 还不存在时初始化它，和 DSH 自带模板完全一致（package.json + cordis.patch.yml + pnpm-workspace.yaml）；
2. 用 npm 把这个包安装到该目录；
3. 把这个包追加到配置档的 dsh.profile.bundles 层列表，这样它的 cordis.patch.yml（把 ctx.web 切到 Tavily，禁用 web-search-deepseek，注册本插件的 host + browser 两半）会在下次启动时生效。

其他子命令：

npx @wilson.liu.cn/dsh-searchhub status # installed? activated? key configured?
npx @wilson.liu.cn/dsh-searchhub install --dry-run # print the plan, change nothing
npx @wilson.liu.cn/dsh-searchhub uninstall # remove it and drop its layer again
npx @wilson.liu.cn/dsh-searchhub install --spec github:Bin-top1/dsh-searchhub
npx @wilson.liu.cn/dsh-searchhub install --spec /path/to/dsh-searchhub # checkout → packed first

然后重启 web 配置档（dsh web 或 dsh --profile web），打开 Settings → Plugins；在 SearchHub 卡片里设置 API key（或者导出 TAVILY_API_KEY）。

为什么不用 dsh plugin add？ dsh plugin 是个 pnpm 转发器（内部走 spawnSync("pnpm", …)），机器上没有 pnpm 就直接失败。这个安装器用 npm 完成同样三步。

为什么 --spec 传目录时要先打包？ npm 安装本地目录时是建符号链接，而符号链接的包会从 checkout 的真实路径解析它的 @deepseek-ai/ 导入——那里没有 DSH 的 peer 包（或者存在重复副本）。把 checkout 打成 tarball，就会在配置档里装一份真实副本，这些导入便能沿配置档自己的 node_modules 链解析到 DSH 安装闭包。

方案 B — 手动 npm 安装 + 一行 manifest

cd "$DSH_HOME/profiles/web"
npm install @wilson.liu.cn/dsh-searchhub

然后把包名加到该配置档的 dsh.profile.bundles（DSH 用来组合插件的层列表）：

"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@wilson.liu.cn/dsh-searchhub"]
}
}

方案 C — dsh plugin 转发器（需要 PATH 上有 pnpm）

dsh plugin --profile web add @wilson.liu.cn/dsh-searchhub

方案 D — 手写补丁层（不依赖 bundles 列表也能用）

$DSH_HOME/profiles/web/cordis.patch.yml
- id: web
config:
searchProvider: tavily
fetchProvider: http
- id: web-search-deepseek
disabled: true
- insert:
- id: searchhub
name: "@wilson.liu.cn/dsh-searchhub"

⚠️ 千万不要把 name: 指向 checkout 里的文件（file:///…/dsh-searchhub/lib/index.js）：那样插件会解析它的宿主从 checkout 的真实路径提供 @deepseek-ai/ 导入，会失败并报 ERR_MODULE_NOT_FOUND（实测）。本地 checkout 请用方案 A 的 --spec <checkout>，它会先打包。

⚙️ 配置

| Key | Type | Default | Description |
| apiKey | secret string | - | 字面量密钥（建议改用 apiKeyEnv）。 |
| apiKeyEnv | credential ref | TAVILY_API_KEY | 密钥存放的环境变量名。 |
| baseURL | string | https://api.tavily.com | Tavily API 基址；会追加 /search。 |
| searchDepth | basic \| advanced | basic | 搜索越深，消耗的 Tavily 额度越多。 |
| maxResults | number (1-20) | 5 | 每次查询请求的结果数。 |
| includeAnswer| boolean | false | 让 Tavily 附带生成一段答案。 |

设置 API 密钥

任选一种：

1. 原生设置卡片 —— 打开 Settings → Plugins → Plugin configuration 下的 SearchHub 卡片，把密钥粘贴进 API key 输入框。密钥经凭据服务加密存储（默认存在 TAVILY_API_KEY 引用下）。
2. 环境变量 —— 启动 DSH 前导出 TAVILY_API_KEY（或你设置的任意 apiKeyEnv）。
3. 字面量配置 —— 直接设置 apiKey（不推荐；密钥会留在文件里）。

去 <https://app.tavily.com/> 领密钥，顺便领你的 每月 1,000 免费额度。

原生设置卡片（双面插件）

DSH Web 的 Plugin configuration 界面不会为任意插件自动生成卡片。只有两半 都在时，卡片才会出现：

1. 宿主侧在某个命名空间（searchhub）下安装设置区块 —— lib/index.js。
2. 浏览器侧向 settings.plugin.item 插槽注册 React 卡片，键名用同一个命名空间 —— lib/client.js。

本插件两半都带，所以有自己专属的精致卡片（不是借来的）。浏览器侧通过 package.json 声明给 DSH client-modules 扫描器：

{
"dsh": {
"bundle": { "patch": "./cordis.patch.yml" },
"client": { "platform": "web" }
},
"exports": {
".": { "default": "./lib/index.js" },
"./client": { "default": "./lib/client.js" }
}
}

扫描器把 lib/client.js 作为经典脚本发给浏览器，其唯一的顶层语句是一个
window.__ModuleLoader__.load({ id, factory })
调用。React 和 JSX 运行时是宿主提供的种子模块，通过工厂的同步 require 获取——浏览器端从不打包自己的 React。卡片的密钥输入通过 ctx.remote.credentials.set(...) 写入 TAVILY_API_KEY 凭据引用，宿主端在每次搜索时解析同一个引用。

🗺️ 路线图

dsh-searchhub 是枢纽，不是单引擎封装。Tavily 是第一个服务商；这层接缝刻意做成通用的，方便把市面上更多热门搜索后端加进来，共用同一张卡片和同一份 ctx.web 契约。欢迎贡献新服务商。

📦 发布（维护者）

npm login
npm publish

预构建的 lib/ 运行时和 cordis.patch.yml 通过 files 白名单一起发布，所以使用者不需要构建步骤。

🛠️ 从源码构建

安装或使用这个插件不需要构建任何东西：仓库自带预构建的 lib/index.js（宿主端）和 lib/client.js（浏览器端），npm 包里也只有这些，加上 scripts/cli.mjs、cordis.patch.yml 和文档。

维护者构建是为了生成发布的类型声明：

npm install # devDependencies only: typescript + the host type packages
npm run build # tsc -p tsconfig.json → lib/types/*.d.ts
npm test # installer behaviour + packaging invariants

- 宿主端： 带类型的源码在 src/types/（index.ts、provider.ts），通过 npm run build 编译成 .d.ts 声明，prepublishOnly 会在打包 tarball 前运行它。lib/index.js 是权威运行时。
- 浏览器端： lib/client.js 是唯一权威的手写源码——直接读它。它刻意写成 DSH client-modules 扫描器所服务的工厂注册形式（React 和 JSX 运行时通过 require 来自宿主种子），所以不需要打包器，也没有单独的 .ts 镜像会跟它不同步。

📄 许可证

MIT © Bin