前言¶
在 DeepSeek Harness（DSH）里，内置的 web_search 依赖部署选定的搜索后端。若只走单一索引，中文语境与全球覆盖面往往难以兼顾：官方 DeepSeek Search API 更贴中文、延迟更低，而 Google 索引在长尾与英文资料上更广。社区插件 dsh-serper-search（维护者 Minokun）把两路检索合成一个 WebSearchProvider，挂到 DSH 的 ctx.web 能力缝上，让每次 web_search 在配置齐全时并行发两次直连 HTTP 请求，按 URL 去重后以固定比例交错合并（默认 2:1），模型一次调用即可同时看到两套索引。README 中说明，同一组 query 下两路结果 URL 重叠约 1.3%，属于互补而非重复。
下面介绍插件定位、能力与安装验收步骤；安装命令与配置项均来自仓库 README 与 package.json（当前 npm 版本 0.4.0，MIT 许可证）。
这是什么¶
dsh-serper-search 是面向 DSH web profile 的搜索插件：注册 id 为 serper 的复合搜索提供方（与旧配置兼容），内部并行 DeepSeek Search API 与 serper.dev（Google 搜索）。v3 起不再通过 DeepSeek 原生 Messages 搜索（旧方案每次需一整轮模型调用）。安装后可将 searchProvider 指向本插件；自 v0.4.0 起，首次启动在满足条件时会自动写入用户层 pin，一般无需手改 cordis.patch.yml。
核心功能¶
双路并行与合并¶
native: true且两路 key 可用时，每次搜索发 两次直连检索（无辅助模型调用）；单路缺 key 或native: false时只发一次。- 结果按 URL 去重，按
ratio（默认2，即约 6 主 + 2 补）交错合并；primary决定主导路与去重保留优先级（默认deepseek）。 - 可选
demoteSocial、maxPerHost等控制来源多样性；官方侧可将summary注入 snippet（summaryMaxChars，默认 600）。
缓存与降级¶
- v0.4.0 起：成功结果默认缓存 5 分钟（
cacheMinutes，0 为关闭）；同一 query 重复搜索可 0 上游请求。 - 单路失败按类型进入冷却，并在降级时给模型一行
Note:；auth/quota 冷却 10 分钟、rate-limit/server 60 秒、timeout/network 30 秒；在设置卡片补填 key 后 auth 相关冷却可立即清除。
自动接管 searchProvider¶
首次启动时，若用户未对 searchProvider 表过态且当前仍为部署默认，插件会把 searchProvider: serper 写入 ~/.dsh/profiles/web/cordis.patch.yml，并写一次性标记 takeOverProvider: false。用户已在 GUI 或其它方式指定 provider 时，插件不会抢占，仅打 warn。环境变量 $DSH_WEB_SEARCH_PROVIDER 的语义为兜底；用户 patch 的 config 优先。
GUI 与自检¶
设置 → 插件 → dsh-serper-search 提供 serper API key（写入 credentials 域）、接口地址、gl/hl、结果条数、是否合并 DeepSeek Search API（native）等。v0.4.0 起卡片底部有四个按钮：测试双路、检查更新、设为本机默认搜索、恢复部署默认。测试双路对应 POST /api/dsh-serper-search/probe，并行各发 1 次真实请求（每路 3 条），成功显示如 1234ms · 3。
安装与启用¶
安装¶
dsh plugin --profile web add dsh-serper-search
也可在 设置 → 插件市场 搜索 dsh-serper-search 安装。
配置密钥¶
推荐在 ~/.dsh/.credentials.yaml 的 refs: 下增加：
SERPER_API_KEY: <serper key>DEEPSEEK_API_KEY: <deepseek key>（多数环境已有）
也可使用环境变量 SERPER_API_KEY / DEEPSEEK_API_KEY。没有 serper key 也能安装，但会退化为官方单路。
重启与确认¶
- 重启
dsh web（首次启动会写 pin）。 - 确认配置：
dsh --profile web --dump-config | grep -A4 "^- id: web$"
应看到 searchProvider: serper。
可选高级参数¶
在同一 profile 的 cordis.patch.yml 中覆盖 web-search-serper 条目，例如：
- id: web-search-serper
config:
serperTimeoutMs: 10000
cacheMinutes: 0
ratio: 1.5
primary: deepseek
autoLocale: true
ratio、primary、summaryMaxChars、各 *TimeoutMs、cacheMinutes 等不进 GUI，需通过 patch 调整。
典型用法与验收¶
给 Agent 的一句话¶
可将下面句子发给 DSH，由 Agent 按 README 五步执行安装与自检：
安装 dsh-serper-search 并跑一次双路自检，把结果告诉我
人工验收可简化为：装 → 搜 → 点「测试双路」。
会话内搜索¶
新会话调用一次 web_search，确认返回至少 1 条来源。日志前缀 web-search-serper: 中应出现 merged= 与 cache=store（命中缓存时行为以 README 为准）。若出现 Note: serper auth failed ...，说明 serper key 未配好，需在卡片或 credentials 中补全。
卸载与恢复¶
推荐先点「恢复部署默认」，再执行：
dsh plugin --profile web remove dsh-serper-search
若直接删除插件而 patch 仍保留 searchProvider: serper，可能出现 provider "serper" is not registered；删除 patch 中对应行或整段 - id: web 即可恢复。卸载后重装时，因 takeOverProvider: false 仍可能保留，需点「设为本机默认搜索」或调整该字段后重启才会重新自动接管。
适用场景与注意¶
适合谁：已在 DSH web profile 中使用 web_search、希望一次搜索同时利用 DeepSeek 自有索引与 Google（serper）索引的开发者与智能体编排场景；需要可观测双路健康状态、本地默认搜索切换与 5 分钟结果缓存时，0.4.0 的设置页较合适。
注意：
- 插件以当前 dsh 进程权限 运行，安装前应自行审阅 源码 与 MIT 许可证；凭据经 credentials 或环境变量注入，勿将 key 提交到版本库。
- 「测试双路」每次消耗 1 次 serper + 1 次 DeepSeek 搜索配额。
- 仅用 DeepSeek 账号登录、无 API key 时，官方一路在 HTTP 路由中可能显示「账号登录态只在对话内生效」，README 说明这不计为 auth 失败。
- SkillHub 目录为社区插件索引，与 DeepSeek / 幻方无官方从属关系；星标等元数据以各站点当时展示为准（GitHub 仓库当前为 1 star）。
结尾¶
dsh-serper-search 把 DeepSeek Search API 与 serper.dev 合成 DSH 上的一个搜索提供方：双路直连、比例交错合并、短缓存与失败冷却，并可通过设置页自检与切换本机默认搜索。需要细节时以 README 的配置表与「卸载与恢复」章节为准。
