网关网页搜索 vitas/dsh-web-search-gateway

dsh-web-search-gateway

为 DeepSeek Harness 提供有依据的网页搜索，跑在你已经付费的网关上。

为什么做这个

内置的 web_search 跑在 DeepSeek 自己的端点上，账单记在那个账号上——一次搜索就是完整一轮模型调用，因为 DeepSeek 没有提供专门的搜索端点。如果你的对话跑在更便宜的地方，搜索却不在。

这个插件把搜索调用挪到兼容 OpenRouter 的网关上，于是搜索的账单落在你对话已经在用的地方，按你网关的价格计费，模型也由你挑：

- 你的模型。 搜索模型和对话模型分开配置，便宜的小模型可以原样不动。
- 你的价格。 在 api.b.ai 上：对话用打折的 deepseek-v4.1-flash，搜索用 gpt-5.4-nano——那里真正会搜索的最便宜模型。
- 你的上限。 dsh-tool-web 的 searchMaxQueries（默认 4）能把一次工具调用变成四次搜索。设成 1，成本就是一次搜索。

面向模型的工具没有任何变化：同一个工具、同样的参数、同样可引用的结果。变的只是背后的引擎。

便宜模型通常不会搜索。 在 api.b.ai 上，DeepSeek、GLM、Qwen、MiniMax 和 MiMo 这些模型会接受请求，然后悄悄不搜索——所以在这个网关上，搜索模型必须和你的对话模型不同。插件会大声报错，而不是把模型的记忆当成搜索结果返回。见已验证的网关。

Web search 设置卡片，连接测试通过

安装

dsh plugin add dsh-web-search-gateway --profile web
dsh credential set OPENROUTER_API_KEY # or export it before launching dsh

包里带了一个 bundle 补丁，所以第一行就把一切组装好了：它把 web 接缝指向这个服务商，并插入服务商那一行。密钥是每次搜索时解析的（先查 credentials 服务，再查进程环境），所以轮换密钥不需要重启——但补丁和链接的主机条目在启动时读取，所以安装后重启一次 dsh web。

用 GitHub 或本地检出代替 npm

dsh plugin add github:vitas/dsh-web-search-gateway --profile web

git clone https://github.com/vitas/dsh-web-search-gateway.git
cd dsh-web-search-gateway && npm install && npm run build
dsh plugin add link:$PWD --profile web

快速开始

1. 安装，然后重启 dsh web。
2. Settings → Plugins → Web search (OpenRouter)。
3. 设置 Endpoint、Search model，粘贴 API key。
4. Test search —— 你会拿到来源数量、延迟，以及前几条命中结果。

已验证的网关

Web search 是服务端工具：网关必须为你指定的模型实现它，而且它不属于 OpenAI 兼容标准的一部分——兼容的只是消息结构。所以「OpenAI 兼容」这句话并不能说明搜索能不能用，这也是本文每一条结论都靠实测、而不是靠假设的原因。

为什么不直接把内置服务商指向我的网关？

内置的 dsh-web-search-deepseek 服务商兼容 Anthropic，也确实暴露了 baseURL 和 model，所以重新指向它是最先想到的办法。在 api.b.ai 上这行不通：请求会被接受，但搜索从不执行——deepseek-v4.1-flash 凭记忆作答（0 条结果，整个回合 44 个 input token），而 gpt-5.4-nano 拿回来的工具是客户端调用。在那里只有 /v1/responses 配合 OpenAI 原生工具才能搜索，而且只对 OpenAI 系列有效。实测数据见：docs/gateways.md。

api.b.ai（协议 openai）

在 /v1/responses 上配合 tools: [{ type: 'web_search' }] 可用；命中结果以 url_citation 注解的形式返回。按价格从低到高：

| 模型 | 引用数 | 备注 |
| gpt-5.4-nano | 2 | 已验证中最便宜；每次查询约 8.5k input token |
| gpt-5.4-mini | 4 | |
| gpt-5.5-instant | 8 | |
| gpt-5-mini | 4 | input token 数量很大 |
| gpt-6-astra、gpt-6-sol、gpt-5.6-sol、gpt-5.5 | 1–4 | |

不支持——glm-、deepseek-、qwen、minimax-、mimo- 和 gpt-5-nano 全都返回 HTTP 200，但完全没有搜索（它们没实现 OpenAI 的服务端工具，而 tools 里无法识别的条目会被丢弃，而不是被拒绝）；Gemini 和 Anthropic 在路由层就被拒，报 not supported on /v1/responses；:online、plugins: [{ id: 'web' }] 和 openrouter:web_search 都是 OpenRouter 的约定，这里不存在。

input token 能区分真搜索和静默空转。 真正跑过的搜索会把结果注入上下文，所以同一个提示词会突然贵出几千个 token：gpt-5.4-nano 是 4313，而 gpt-5-nano 只有 18，非 OpenAI 系列是 24–105。这就是服务商检查 searched、而不是看到 200 就放心的原因。各模型的失败情况和省钱手段见：docs/gateways.md。

openrouter.ai（协议 openrouter）

baseURL: https://openrouter.ai/api/v1，再加上一个带 web-search 徽标的模型。engine、searchContextSize、maxUses、maxTotalResults 和域名过滤条件会作为服务端工具的 parameters 透传。在非 OpenRouter 的网关上，这个协议会被拒绝——那是网关在说话，不是插件。

对 OpenAI 官方（https://api.openai.com/v1）来说，默认协议开箱即用；来源以 web_search_call.action.sources[] 的形式返回，走的是同一段代码路径。

协议

| protocol | 线上格式 | 适用场景 |
| openai （默认）* | tools: [{ type: 'web_search' }] | OpenAI、Azure，以及代理原生工具的聚合服务商（api.b.ai） |
| openrouter | tools: [{ type: 'openrouter:web_search', parameters }] | openrouter.ai，以及采用该服务端工具的网关 |
| plugin （已弃用） | plugins: [{ id: 'web', … }] | 从未采用服务端工具的旧网关 |

服务商还会读取 web_search_call.action.sources[]、
openrouter:web_search.action.sources[] 和 url_citation 注解 ——
网关没有发送摘录时，会从引用片段中切出摘要。

配置项

每个字段都能在卡片里编辑，也能从 composition 条目初始化。卡片的位置取决于你的 harness 版本：DSH 0.1.7 把它放在该行自己的页面上，位于 Plugins 下（侧边栏条目），DSH 0.1.5 放在 Settings → web-search-openrouter 下。编辑结果写入配置档的补丁，0.1.5 上则写入 settings.yaml。覆盖了 composition 条目的值会标记为 overridden，可以在卡片里重置。

| 字段 | 默认值 | 含义 |
| protocol | openai | 启用面（见上表） |
| baseURL | https://openrouter.ai/api/v1 | 网关基址；会追加 /responses |
| model | openai/gpt-5.2 | 在该网关上提供网页搜索的模型 |
| apiKeyEnv | OPENROUTER_API_KEY | 凭据引用，每次搜索时解析 |
| apiKey | — | 字面密钥；优先于 apiKeyEnv（别写进共享配置档） |
| maxResults | 5 | 请求的结果数，1–25；越低越便宜 |
| maxOutputTokens | 1024 | 单轮搜索的 max_output_tokens |
| includeAnswer | false | 同时把搜索模型的文本作为 content 返回 |
| allowedDomains、excludedDomains | — | 只保留或剔除这些主机名的结果 |
| engine、searchContextSize、maxUses、maxTotalResults | — | 仅 openrouter 协议；作为服务端工具参数透传 |
| referer、title | — | HTTP-Referer / X-Title 归属头 |

成本

按搜索模型的 token 计费，不按查询次数。可调的杠杆，从最省钱的开始：挑最便宜的能搜索的模型（而且只用它 —— 对话模型是分开的），把 searchMaxQueries: 1 设上，maxResults 保持低值，includeAnswer 关掉。实测数据：docs/gateways.md。

故障排查

| 现象 | 原因 |
| WEB_PROVIDER_CREDENTIAL_MISSING | apiKeyEnv 下没有密钥；在卡片里设置，或启动 dsh 前导出它。 |
| "the gateway ran no server-side search for model …" | 该模型在那个网关上不提供网页搜索。从上表里挑一个。 |
| "Invalid value: 'openrouter:web_search'" | 网关没有实现 OpenRouter 的服务端工具；把 protocol 换成 openai。 |
| 「节点只允许访问推理 API 路径」 | 网关侧的代理限制；检查 baseURL（多余的尾部斜杠以前会产生 //responses）。 |
| /responses 返回 HTTP 404 | 网关只支持 chat completions；这个服务商需要 Responses 端点。 |

开发

npm install # esbuild + typescript
npm run check # host syntax check + client typecheck
npm test # 35 tests, no network, no credentials (1 skipped: the live one)
npm run check-locales
npm run build # rebuild the committed lib/client.js (also runs on npm pack)

Live smoke test — opt-in, never in CI.
DSH_WEB_SEARCH_LIVE=1 OPENROUTER_API_KEY=sk-... \
DSH_WEB_SEARCH_BASE_URL=https://api.b.ai/v1 DSH_WEB_SEARCH_MODEL=gpt-5.4-nano \
node --test test/live.test.mjs

架构、接缝约定和发布流程见 docs/。三套协议；一张浏览器卡片（English / 中文 / Русский）；不引入 @deepseek-ai/* 运行时依赖；没有安装期脚本——打包产物已提交，一旦漂移 CI 就会失败。

隐私

不存储数据，不做后台任务。每次搜索向 baseURL 发一个 HTTPS 请求，带上你的查询、模型名和配置的参数；其余事项由网关自己的条款约束。密钥在调用时从 DSH 凭据存储读取，绝不写入设置、日志或浏览器。

许可证

Apache-2.0。