dsh-web-search-serper
Verified@dingpenghui/dsh-web-search-serper · v1.3.0 · MIT · Web UI
Serper.dev-backed web search provider for DSH (DeepSeek Harness) web capability seam (ctx.web) — works right after install with no config edits or restarts, needs only an API key (no tuning knobs), and falls back to another usable provider when Serper is
Install
dsh plugin add @dingpenghui/dsh-web-search-serper Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-web-search-serper
English | 中文
概述
@dingpenghui/dsh-web-search-serper 是一个基于 Serper.dev API 的 Web 搜索提供方插件,适配 DeepSeek Harness (DSH) 的 web 能力 seam(ctx.web,@deepseek-ai/dsh-web 0.2.0-rc.x)。本版本针对 DSH 0.2.0-rc.2 与 0.2.1-rc.2 构建与验证。
Serper.dev 是 Google 搜索的官方合作伙伴,提供高速、结构化的 Google 搜索结果 API。免费额度:每月 2,500 次查询,无需信用卡。
特性
- 🚀 高速搜索 — 1-2 秒响应,基于 Google 真实索引
- 📊 结构化结果 — JSON 格式返回,易于解析
- 🔒 隐私友好 — 不追踪用户,无 Cookie 收集
- 💰 免费额度高 — 每月 2,500 次查询,免费使用
- 🌍 多语言支持 — 支持全球多个国家/地区的搜索结果
- 🔧 装好即生效 — 安装后由插件自己在运行时接管
web.searchProvider,无需改任何配置、无需重启;key 每次搜索惰性解析(config → 环境变量 → 凭证库),改动同样无需重启 - 🛟 失败自动降级 — Serper 不可用时自动回退到其它可用搜索提供方,不会让
web_search整体失效 - ⚙️ 插件页内的设置界面 — 在「插件」列表点插件名(或行上的「配置」)即可编辑 API Key;保存后对下一次搜索即时生效,无需重启。只有这一个设置项,检索行为本身不需要调参
- 🔁 配置热读取 — 每次搜索都重读行 config(含
ctx.settings.describe()中以volatile()包装返回的值),所以在别处改动凭证或选项同样立即生效
快速开始
安装
# 方式一:从 npm 安装(推荐)
dsh plugin --profile web add @dingpenghui/dsh-web-search-serper
# 方式二:本地 bundle(link:)
# 1. 在 profile 的 package.json `dependencies` 加:
# "@dingpenghui/dsh-web-search-serper": "link:<本目录绝对路径>"
# 2. 同步 `dsh.profile.bundles` 加 "@dingpenghui/dsh-web-search-serper"
# 并让 pnpm 把本包自带的 cordis.patch.yml 作为 bundle patch 应用
# (也可以直接把 insert 行手动加到 profile 的 cordis.patch.yml)
pnpm install
pnpm run build
配置
装好即生效,无需任何手动配置,也无需重启。 插件自带的 cordis.patch.yml
只负责插入插件行:
- insert:
- id: web-search-serper
name: '@dingpenghui/dsh-web-search-serper'
接管搜索由插件运行时自己完成:apply() 注册完 serper provider 后,直接把
ctx.web.config.searchProvider 设为 serper。web seam 在每次 search() 时解析
选择、不缓存结果,所以插件一被加载就立刻被寻址。
为什么不再靠 patch 接管? 早期版本在 bundle patch 里写
- id: web整行替换config来接管。这条路有四个坑:① 整行替换会抹掉 dsh-base 的其它 key,宿主每加字段就漏;② profile 自己的cordis.patch.yml优先级更高,一句- id: web就能把接管静默顶掉;③cordis.patch.yml只在 进程启动时读取一次,装完不重启就不生效;④ 上述任一情况发生时,搜索会 安静地继续走内置后端、不报任何错。改为运行时接管后,这些坑全部消失。
换回内置搜索(或别的 provider)
插件会尊重你的显式选择,两种方式任选:
# 方式一:环境变量(seam 侧优先于 config,插件会主动让位)
export DSH_WEB_SEARCH_PROVIDER=deepseek-official
# 方式二:在 profile 的 cordis.patch.yml 里整行覆盖(patch 语义是替换 config,
# 必须重述该行拥有的每一个 key)
- id: web
name: '@deepseek-ai/dsh-web'
config:
searchProvider: deepseek-official
fetchProvider: http
API key 无需配置即可工作,每次搜索时按以下顺序惰性解析:
- 行
config.apiKey(显式配置,需给行加config块;插件详情页保存后经 volatile HMR 即时生效); - DSH 宿主进程的环境变量
SERPER_API_KEY; - DSH 凭证库中的
SERPER_API_KEY引用 ($DSH_HOME/.credentials.yaml的refs:—— 每次搜索实时解析,改动无需重启)。
在 composition 中固定 key(唯一的可配置项):
- id: web-search-serper
name: '@dingpenghui/dsh-web-search-serper'
config:
apiKey: your-serper-api-key
刻意没有其它设置。 旧版曾暴露
gl/cr/numResults/baseURL, 但它们只会让检索在用户无感知的情况下变样——比如gl: cn会让英文技术查询 返回中文站点,numResults会覆盖宿主工具下发的条数。现在这些开关已移除: 端点固定为 Serper 官方端点,条数由宿主web_search工具决定,区域跟随 Serper 默认。老 profile 里残留的这些值会被忽略,不影响检索。
运行行为:优先 Serper,失败自动降级
- 优先 — 只要 Serper 配置就绪(有 key、端点合法),一律走 Serper;
- 降级 — Serper 因任何原因失败(无 key、401/403 鉴权失败、429 限流、5xx、
网络异常、端点配置错误等)时,自动改用 seam 上其它已注册且可用的搜索提供方,
通常是
dsh-base自带的deepseek-official; - 不降级 — 用户主动取消(
WEB_ABORTED)不触发降级; - 两侧都失败 — 上抛
WEB_PROVIDER_ERROR,消息同时包含主后端与降级后端的 失败原因,降级错误挂在cause链上。
重启须知 — DSH 的
patchReload: live会热重载配置层(cordis.patch.yml),但插件代码本身(lib/index.js)是 ESM 模块,进程内缓存不会自动刷新。也就是说:升级插件版本、或改动插件源码后需要重启宿主;而首次安装后是否生效取决于插件行是否已被加载(见下方排障)。插件一旦加载,其内部逻辑与运行时接管无需再次重启。
降级在插件内部完成,因为 DSH 的 web seam 自身不做回退(配置了 id 就只用它)。
相应地,available() 在「Serper 侧不可用、但存在可降级目标」时仍返回 true ——
否则 seam 会在进入 search() 之前就以 WEB_PROVIDER_CONFIGURED_UNAVAILABLE
拦下,降级根本无从发生。
设置界面(插件页)
Client 半边把插件自己的配置页注册进「插件」页声明的两个 slot:
plugins.bundle.config(以 npm 包名为 key,显示在插件自己的页面上)与
plugins.row.config(以 @dingpenghui/dsh-web-search-serper#web-search-serper
为 key,行上的「配置」控件打开它)。两者都经 configForms.whileServed 跟随
Host 实际在 serve 的 settings 命名空间:命名空间被 serve 时才出现,不再
被 serve 时自动撤下。
可编辑项:仅 API Key。在 0.2.x 上:插件页(plugins.bundle.config)只承担
只读概览,真正的编辑与保存发生在行的「配置」页(plugins.row.config),经宿主
设置表单写入插件行 config。
由于每次搜索都会重读 ctx.settings.describe()(volatile() 字段在其中以
{ get(): value } 包装返回,插件按宿主 plainConfig 同样的方式解包),
保存后的值对下一次搜索立即生效,无需重启宿主。
排障:装了、配了,为什么搜索还是不走 Serper?
这是本插件最容易踩的坑,坑不在插件本身,而在 DSH 的配置加载时机。
profile 的 cordis.patch.yml 只在 DSH 进程启动时读取一次。
如果在 DSH 已经运行时才安装插件,当前进程不会重新加载插件层——插件处于
「装好了但没加载」的状态,而搜索会安静地继续走 DSH 内置后端,不会报任何错。
v1.2.8 起,只要插件层被加载,接管搜索就由插件自己在运行时完成,不再依赖
cordis.patch.yml里怎么写。因此剩下的唯一前置条件就是「插件行被加载」。
判断顺序(v1.2.7 起每步都有日志可查):
- 安装插件后重启 DSH。这是最常见的原因。
- 看宿主日志里有没有这一行(说明插件层确实加载了):
没有这行 → 插件层没加载,回到第 1 步。web-search-serper: registered search provider "serper" (key source: credential) - v1.2.8 起紧接着应出现(debug 级):
若改为出现下面任一条警告,才说明「加载了但不会被调用」:web-search-serper: took over web.searchProvider (was "deepseek-official")
第一条是你自己用环境变量显式指定了别的 provider;第二条只会在旧宿主 没有可写的web-search-serper: $DSH_WEB_SEARCH_PROVIDER is "xxx", not "serper" — respecting it web-search-serper: web.searchProvider is "deepseek-official", not "serper" — this plugin is loaded but will not be used until the web row selects itsearchProvider配置面时出现(此时仍需- id: web覆盖)。 - 若出现降级警告,说明 Serper 侧失败了、结果是别的后端给的:
常见原因:key 无效/欠费(401/403)、超配额(429)、网络不通。web-search-serper: fell back to "deepseek-official" — serper failed: <原因> - 编程方式读取状态(Host 侧):
import { readRuntimeStatus } from '@dingpenghui/dsh-web-search-serper' readRuntimeStatus() // { registered: true, calls: 12, serperHits: 12, fallbacks: 0, // last: { outcome: 'serper-ok', servedBy: 'serper', keySource: 'credential', ... } }registered: false或calls: 0分别对应上面第 2 步与第 3 步的问题。 该快照不含 key 值,只有keySource(config/env/credential/missing), 用于区分「我以为配了 key,其实读到的是另一个来源」。
一句话版本:装完/升级后重启一次 DSH,用日志里的
registered search provider确认它活了;之后一切自动生效,不用再碰配置。
兼容性
| DSH 运行时 | 插件版本 |
|---|---|
0.2.x(已在 0.2.0-rc.2 与 0.2.1-rc.2 上验证) |
1.2.3 |
0.1.7-rc.x |
1.2.0 |
1.2.3 起用 engines.dsh(>=0.2.0-rc.2 <0.3.0-0)统一表达 DSH 兼容范围,
并且不再把 @deepseek-ai/dsh-web / @deepseek-ai/dsh-llm 写进
peerDependencies。原因见下节。
为什么 1.1.1 装不上: DSH 的安装门禁(dsh-app-boot 的
evaluatePluginCompatibility)在没有 engines.dsh 时,会逐个检查
@deepseek-ai/dsh-* 的 peerDependencies,并用
semver.satisfies(runtime, range, { includePrerelease: true }) 判定。1.1.1 把
@deepseek-ai/dsh-web 钉成精确版本 0.2.0-rc.2,而在该规则下
0.2.1-rc.2 不满足 0.2.0-rc.2,于是安装被拒:
Plugin @dingpenghui/[email protected] is incompatible with dsh 0.2.1-rc.2:
requirements {"@deepseek-ai/dsh-web":"0.2.0-rc.2"}
1.2.3 让 engines.dsh 单独决定兼容性(存在 engines.dsh 时宿主只看它、忽略
peer),同时移除对 DSH 运行时包的 peer 声明——这些包由宿主提供,不应由插件再装
一份。smoke-test.mjs 增加了对应回归护栏:优先调用宿主自己的
evaluatePluginCompatibility,宿主不可用时回退到语义等价的实现,确保本插件在
0.2.0-rc.2 与 0.2.1-rc.2 上都判定为可安装、在 0.3.0 / 0.1.5 上被拒绝。
slot / 页面 API 方面,1.2.3 与 1.2.2 一致:plugins.bundle.config 只收到
view: 'page'(没有 form,因此渲染只读概览),plugins.row.config 才会
收到行自己的 form(state + mutate),是真正可编辑并保存的视图;两者都经
configForms.whileServed 跟随命名空间是否被 serve。
0.2.1-rc.2的客户端公共包已随包发布.d.ts;插件仍然在src/contracts.d.ts与src/client/*.d.ts里显式声明它消费的契约,以保证 跨版本线的类型稳定。
获取 API Key
- 访问 https://serper.dev
- 注册免费账户
- 在 Dashboard 获取 API Key
- 免费额度:每月 2,500 次查询
配置选项
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
apiKey |
string | 否 | $SERPER_API_KEY,再回退到凭证引用 SERPER_API_KEY |
Serper API 密钥(secret,volatile) |
baseURL |
string | 否 | https://google.serper.dev |
API 端点基址 |
gl |
string | 否 | - | 国家代码(如 us, cn, jp) |
cr |
string | 否 | - | 地区代码(如 us,作为 cr 参数发送) |
numResults |
number | 否 | 省略(Serper 默认 10) | 默认结果数量,上限 100 |
使用示例
基础搜索
import { apply } from '@dingpenghui/dsh-web-search-serper'
// 由 Cordis loader 调用;大多数部署无需直接调用。
// apply(ctx)
通过 ctx.web 搜索
const result = await ctx.web.search({
query: '2026年AI发展趋势',
maxResults: 5,
})
console.log(result.sources)
// [
// { url: '...', title: '...', snippet: '...' },
// ...
// ]
错误处理
| 错误码 | 含义 | 处理方式 |
|---|---|---|
WEB_PROVIDER_CONFIGURED_MISSING |
配置的 provider 未注册 | 检查插件是否正确加载 |
WEB_PROVIDER_CONFIGURED_UNAVAILABLE |
provider 已注册但没有可用 key | 检查 API Key:config / $SERPER_API_KEY / 凭证引用 |
WEB_ABORTED |
请求被中止 | 检查 AbortSignal |
WEB_PROVIDER_ERROR |
API 请求失败 | 检查网络 / API Key / 速率限制 |
只有降级目标同样不可用时,
WEB_PROVIDER_CONFIGURED_UNAVAILABLE与WEB_PROVIDER_ERROR才会冒泡到web_search;Serper 单独失败会被自动降级 吸收(见上文「运行行为」)。
限制与已知问题
- 免费额度限制 — 每月 2,500 次查询,超出后需付费
- 仅支持 Google 搜索 — 不支持 Bing、Baidu 等其他搜索引擎
- 无生成答案 — 仅返回搜索结果列表,不包含 AI 生成的摘要
- 需要 API Key — 必须通过配置、环境变量或凭证引用提供有效的 Serper API Key
- 一次只对一个 DSH 版本线 —
1.2.3支持 DSH0.2.x(>=0.2.0-rc.2 <0.3.0-0);换到其它版本线需要对应版本的插件(见「兼容性」)
相关项目
- DeepSeek Harness — DSH 主项目
- Serper.dev — Google Search API 服务
许可证
MIT License — 见 LICENSE 文件