网页搜索直连 DOCUTEE/dsh-web-search-opencode-style

dsh-web-search-opencode-style

npm version
license

一个为 DeepSeek Harness（DSH）打造的 opencode 风格网页搜索提供程序。它向 ctx.web 注册单个 opencode-style 提供程序，因此来自 @deepseek-ai/dsh-tool-web 的面向模型的 web_search 工具可以继续工作（卡片、引用、超时、searchMaxResults），而不会触发 WEB_PROVIDER_AMBIGUOUS。

无需安装 MCP 服务器。无需 API 密钥。不消耗 LLM 额度。

工作原理

这是对 opencode 执行网页搜索方式的直接移植（packages/opencode/src/tool/websearch.ts + packages/opencode/src/tool/mcp-websearch.ts）：CLI 将 JSON-RPC tools/call 以 POST 直接发送到两个公共 MCP 端点，然后解析 MCP 响应（纯 JSON 或 SSE data: ... 行）：

- Exa：https://mcp.exa.ai/mcp → web_search_exa
- Parallel：https://search.parallel.ai/mcp → web_search

该插件零依赖：仅使用全局 fetch（Node >= 20）。

与 opencode 的一致性

1:1 移植，并对照 websearch.ts + mcp-websearch.ts 交叉核对：

- 相同的端点、工具名称、JSON-RPC 请求体（id: 1、tools/call）、accept 头、25 秒超时、默认 redirect（跟随）。
- 相同的默认参数：type: auto、numResults: 8、livecrawl: fallback，contextMaxCharacters 仅在设置时发送；numResults = request || config || 8（不做钳制，严格为 params.numResults || 8）。
- 与 selectWebSearchProvider() 相同的后端选择顺序：环境变量 OPENCODE_WEBSEARCH_PROVIDER → 配置 provider → 标志 enableExa/enableParallel（环境变量 OPENCODE_ENABLE_EXA、OPENCODE_ENABLE_PARALLEL、OPENCODE_EXPERIMENTAL 作为 RuntimeFlags）→ checksum(sessionID) % 2。会话来自 ctx.agents.currentInitiator()，因此同一会话内的每次搜索都会命中同一后端，与 opencode 完全一致。
- 发送给 Parallel 的相同字段：objective、search_queries、session_id（真实会话；没有会话时为 dsh_）、model_name（agent.options.model，截断至 100 个字符——对应 webSearchModelName）。
- 相同的解析方式：先解析原始 JSON，然后扫描 data: 行；不是 McpResult 的 {...} 载荷（JSON-RPC error、格式错误的 JSON）是错误，而不是静默的“无结果”。
- 相同的空结果语句： No search results found. Please try a different query.
- 相同的 FNV-1a base36 checksum（移植自 packages/core/src/util/encode.ts）。

无法从提供程序层复现的内容（DSH 架构限制）：

| 要点 | opencode | DSH |
| 由模型选择 numResults/livecrawl/type/contextMaxCharacters | 工具参数 | DSH 的 web_search 仅接受 queries[]；maxResults 由 tool-web 行（searchMaxResults）固定，其余为配置 |
| 搜索前请求许可 | ctx.ask({permission:'websearch'}) | dsh-tool-web 没有审批层；权限属于宿主，提供方没有通道 |
| 卡片标题 + metadata.provider | "Exa Web Search: " | 接缝的 WebSearchResult 没有元数据通道 |
| User-Agent（Parallel） | opencode/ | dsh-web-search-opencode-style/ —— 刻意不冒充其他产品 |

sources[] 是 opencode 没有的唯一转换步骤：接缝需要结构化数据来渲染卡片和引用。该插件优先解析结构化格式——先是 Parallel 的 JSON results[]（title、publish_date → publishedAt、excerpts → snippet），然后是 Exa 的 Title:/URL:/Published:/Highlights: 块——只有当文本不匹配任何已知格式时，才回退到扫描原始 URL。当提取到的来源数量超过 maxResults 时会设置 truncated，这样 web_search 就能提示模型优化查询。

错误码：WEB_PROVIDER_ERROR（HTTP 失败 / 网络失败 / 无法解析的响应体 / 响应大于 4 MiB）、WEB_SEARCH_TIMEOUT（超过 timeoutMs，消息与 opencode 相同： request timed out，名称族与 dsh-web-fetch-http 的 WEB_FETCH_TIMEOUT 相同）、WEB_ABORTED（调用方中止）。

安装（一条命令）

dsh plugin --profile web add dsh-web-search-opencode-style

这会在该 profile 内运行 pnpm add，并将该 bundle 接入 dsh.profile.bundles（通过 reconcilePlugins：任何声明了 dsh.bundle 的包都会自动加入栈）。该 bundle 补丁既挂载了提供方，又将 web 行覆盖为 searchProvider: opencode-style（环境变量 DSH_WEB_SEARCH_PROVIDER 仍然优先），因此不会与内置的 deepseek-official 发生 WEB_PROVIDER_AMBIGUOUS 冲突。重启 dsh --profile web，模型就会像之前一样看到 web_search——无需密钥，无需额外编辑文件。

回到旧的 DeepSeek 搜索：
DSH_WEB_SEARCH_PROVIDER=deepseek-official dsh --profile web。
固定某一个 opencode 后端：OPENCODE_WEBSEARCH_PROVIDER=exa|parallel。

改为从本地检出安装：

dsh plugin --profile web add /path/to/dsh-web-search-opencode-style

卸载：

dsh plugin --profile web remove dsh-web-search-opencode-style

配置

以下所有内容都可以在 设置 → 插件 → 插件配置（命名空间 web-search-opencode-style）中编辑：该插件注册了一个真正的设置区段，因此表单会列出每个键，更改会从下一次搜索起生效。该区段需要来自正在运行的 DSH 安装的 @deepseek-ai/schemastery；插件会从 $DSH_HOME/profiles/node_modules（DSH 的共享回退位置）加载它，因此通过符号链接的 dsh plugin add 安装无需任何额外操作即可工作。没有 schemastery 时插件仍然可用——只是缺少表单。

你也可以使用该行的 cordis.patch.yml（参见模板文件），或直接使用传给 apply() 的 config 对象：

| 键 | 默认值 | 含义 |
| provider | undefined（自动） | "exa" / "parallel" 用于固定；优先级低于环境变量 OPENCODE_WEBSEARCH_PROVIDER（顺序与 opencode 相同） |
| enableExa | 环境变量 OPENCODE_ENABLE_EXA / OPENCODE_EXPERIMENTAL_EXA / OPENCODE_EXPERIMENTAL | 强制使用 Exa，类似 RuntimeFlags.enableExa |
| enableParallel | 环境变量 OPENCODE_ENABLE_PARALLEL / OPENCODE_EXPERIMENTAL_PARALLEL | 强制使用 Parallel；在 enableExa 之前检查，与 opencode 相同 |
| exaApiKey | 环境变量 EXA_API_KEY | 可选——公共端点无需密钥即可使用 |
| parallelApiKey | 环境变量 PARALLEL_API_KEY | 可选 |
| numResults | 8 | 当调用方未发送 maxResults 时使用；实际上由 tool-web.searchMaxResults 决定 |
| type | "auto" | auto / fast / deep（Exa） |
| livecrawl | "fallback" | fallback / preferred（Exa） |
| contextMaxCharacters | _（不发送）_ | Exa 上下文上限 |
| timeoutMs | 25000 | 与 opencode 的 "25 seconds" 匹配 |
| enabled | true | false → available() 返回 false |

开发

该模块导出 name、inject、apply 和 Config——并且没有默认导出。cordis 的加载器使用 default ?? exports 规范化模块导出（cordis-plugin-loader），因此默认导出会遮蔽具名元数据，插件会丢失其 inject/Config（这曾导致 cannot get property "web" without inject）。仅当默认导出自身携带该元数据时才添加默认导出。

node --test test/.test.mjs # plugin.test.mjs (ported logic) + dsh-seam.test.mjs (real cordis + dsh-web)
DSH_INTEGRATION=1 node --test test/dsh-seam.test.mjs # plus one real search against Exa/Parallel

test/dsh-seam.test.mjs 将插件挂载到带有真实 ctx.web 接缝的真实 cordis 上下文上，并且仅对网络进行打桩，因此导出结构和设置接线也都被覆盖；当 PATH 上没有 dsh 安装时，它会跳过自身。

许可证

MIT