vitas/dsh-web-search-openrouter

dsh-web-search-openrouter

为 DeepSeek Harness 提供基于已有付费网关的接地式网页搜索。

CI
npm
license
node

@samebits/dsh-web-search-openrouter 在 harness 的 web 接缝（ctx.web）上注册一个搜索提供程序。内置的 web_search 工具随后在兼容 OpenRouter 的网关上服务端运行——与你的聊天模型使用相同的端点和相同的 API 密钥。面向模型的工具接口没有任何变化：相同的工具、相同的参数、相同的可引用结果。只是其背后的引擎从 harness 自带的 DeepSeek 搜索切换到了你自己的网关预算上。

- 三种协议，一个提供程序。 原生 OpenAI web_search、OpenRouter 的 openrouter:web_search 服务端工具，以及已弃用的 plugins: [{ id: 'web' }] 字段。选择你的网关所接受的那一种。
- 读取所有引用形态。 web_search_call.action.sources[]、openrouter:web_search.action.sources[] 以及 url_citation 注解——包括在网关未发送摘录时从被引用片段中切出的摘要。
- 运行时可编辑。 插件设置选项卡上的一张卡片（英文、中文、Русский），带有一个 Test search 按钮，可通过已保存的配置运行一次真实查询。
- 无服务器，无遥测。 唯一的出站请求就是搜索本身，发往你所配置的端点。不会向其他任何地方发送任何内容。
- 无依赖宿主。 没有 @deepseek-ai/ 运行时导入，因此它既能在链接的开发检出中工作，也能从注册表安装使用。

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

安装

dsh plugin add @samebits/dsh-web-search-openrouter --profile web

该包附带一个 bundle 补丁（dsh.bundle.patch），因此这一行就组合好了一切：它将 web 接缝指向此提供程序，并插入提供程序行。

其他安装方式

从 GitHub 安装，跟踪默认分支：

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

从本地检出安装（在编辑插件时很有用）：

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

然后存储密钥并重启一次：

dsh credential set OPENROUTER_API_KEY   # 或在启动 dsh 前将其导出

凭据引用在每次搜索时解析，通过 DSH 凭据
服务（设置 → 模型），然后是进程环境——因此轮换密钥永远不需要重启。捆绑补丁在启动时应用；链接的检出目录的主机条目也会在启动时导入，因此安装后的首次运行需要重启一次 dsh web。之后，卡片中的每次设置编辑都会实时生效。

快速开始

1. 安装包（见上文）。
2. 重启 dsh web，然后打开 设置 → 插件 → Web 搜索（OpenRouter）。
3. 设置 Endpoint、Search model，并粘贴你的 API key。
4. 按下 Test search——你应该会得到来源数量和首批命中结果。
5. 向 agent 询问一些时效性强的问题；它会像往常一样调用 web_search。

已验证的网关

Web 搜索是一个服务器工具：网关必须为你指定的模型实现它。插件会如实报告这一点——如果网关在没有搜索的情况下作答，搜索会以一个解释性错误失败，而不是静默返回模型的记忆。

api.b.ai（协议 openai）

已在 /v1/responses 上验证可用，使用 tools: [{ type: 'web_search' }]，命中结果以 url_citation 注释形式返回。按价格从低到高：

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

此网关不支持：gpt-5-nano、glm-、deepseek-、Anthropic 和 Gemini 路由、:online 后缀、plugins: [{ id: 'web' }] 以及 openrouter:web_search。

openrouter.ai（协议 openrouter）

使用服务器工具：

protocol: openrouter
baseURL: https://openrouter.ai/api/v1
model: openai/gpt-5.2   # any model with the web-search badge

engine（auto、native、exa、firecrawl、parallel）、searchContextSize（low、medium、high）、maxUses、maxTotalResults 以及域名过滤器会作为服务器工具的 parameters 透传。在非 OpenRouter 网关上，此协议会被拒绝——那是网关在说话，不是插件。

OpenAI 官方（协议 openai）

https://api.openai.com/v1 + tools: [{ type: 'web_search' }]；来源以 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', … }] | 从未采用该服务器工具的较旧网关 |

设置参考

每个字段都可以从设置卡片中编辑，也可以从 composition 条目中预置；在 settings.yaml 中设置的字段会在卡片中标记为已覆盖，并可在那里重置。

| 字段 | 默认值 | 含义 |
|---|---|---|
| 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 返回 |
| engine | — | 仅 openrouter 协议 |
| searchContextSize | — | 仅 openrouter 协议：low/medium/high |
| maxUses | — | 仅 openrouter 协议：限制服务器工具调用次数 |
| maxTotalResults | — | 仅 openrouter 协议 |
| allowedDomains | — | 将结果限制为这些主机名 |
| excludedDomains | — | 丢弃来自这些主机名的结果 |
| referer、title | — | HTTP-Referer / X-Title 归属标头 |

成本

web_search 按搜索模型的 token 计费——而非按查询计费。单次
工具调用可能会扇出：dsh-tool-web 的 searchMaxQueries（默认 4）会将一次
web_search 变成最多四次网关搜索，每次都有自己的输入上下文。
保持 maxResults 较低，选择你的网关所提供的最便宜的带搜索模型，
并且仅当你确实需要广度时才提高 searchMaxQueries。测量数据见
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。 |
| "node only allows access to inference API paths" | 网关侧代理限制；检查 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)

实时冒烟测试为可选启用，且从不在 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/。

隐私
该插件不存储任何数据，也不运行任何后台工作。每次搜索时，它会向 baseURL 发送一个 HTTPS 请求，其中包含你的查询、模型名称以及配置的参数；网关自身的条款决定了这些数据的处理方式。API 密钥在调用时从 DSH 凭据存储中读取，绝不会写入设置、日志或浏览器。

许可证

Apache-2.0。