9router 网页搜索 lordraiden/dsh-9router-web-search

🌐 dsh-9router-web-search

为 DeepSeek Harness 提供由 9router 背书的网页搜索与抓取。
将原生 web_search 与 web_fetch 工具接入 9router 的 /v1/search 与 /v1/web/fetch 端点 —— 无需服务端搜索工具。

🇺🇸 English · 🇨🇳 简体中文

✨ 功能

- 🔎 搜索 provider — 将 DSH 原生 web_search 路由到 9router 的 /v1/search，返回去重后的 WebSource 结果（标题、摘要、发布日期）。
- 📄 抓取 provider — 将 DSH 原生 web_fetch 路由到 9router 的 /v1/web/fetch，返回干净的文本/Markdown 正文。
- 🎛️ 设置卡片 — 原生 DSH 设置面板，用于配置 API 密钥、基础地址、模型、超时与限额。
- 🧩 零配置接入 — bundle patch 已把 web seam 的 search 与 fetch 固定到 9router，无需手动配置 provider。
- 🔐 凭据感知、密钥可选 — 从 DSH 凭据服务（NINE_ROUTER_API_KEY）或字面配置值解析 API 密钥；无密钥的本地 9router 实例开箱即用；绝不提交到仓库。
- 🧱 零构建 — 纯 ESM，纯 JavaScript，无需打包器。

🧭 为什么需要它

DSH 默认的 web_search 使用 web-search-deepseek provider，它要求上游实现 Anthropic 的 web_search_20250305 服务端搜索工具并返回 web_search_tool_result 块。

9router 是一个 OpenAI 兼容网关：它把该工具定义当作普通函数交给模型，而不在服务端执行搜索 —— 因此它本身无法提供原生搜索。

| | web-search-deepseek（默认） | 9router（本插件） |
| 依赖 | Anthropic web_search_20250305 服务端工具 | 任意 9router 兼容网关 |
| 支持 9router | ❌ | ✅ |
| 搜索端点 | 由模型提供 | POST /v1/search |
| 抓取端点 | 由模型提供 | POST /v1/web/fetch |

本插件直接调用 9router 自有的端点，并将其响应映射为 DSH web seam 所期望的 WebSource 与 WebFetchBody 类型。

⚙️ 工作原理

web_search / web_fetch（原生 DSH 工具） │ ▼ ctx.web seam │ provider = "9router" ▼ dsh-9router-web-search ├── search → POST {baseURL}/search → WebSource[] └── fetch → POST {baseURL}/web/fetch → WebFetchBody │ ▼ 9router gateway │ ▼ 9router providers / model combos

错误会以机器可路由的 WebError 代码（WEB_PROVIDER_ERROR、WEB_TIMEOUT、WEB_ABORTED、WEB_PROVIDER_CREDENTIAL_MISSING）呈现，瞬态网络与 5xx 故障按退避重试，非 2xx 的抓取响应会作为结果返回 —— 绝不静默抛出。

🚀 快速开始

1. 安装插件

npx @deepseek-ai/dsh plugin --profile web add github:lordraiden/dsh-9router-web-search

2. 接入配置

- 插件的 bundle patch 已把 web.searchProvider 与 web.fetchProvider 固定为 9router —— 无需手动接入（profile 自己的 cordis.patch.yml 可覆盖该行）。
- 在设置卡片中设置 baseURL（或 NINE_ROUTER_BASE_URL 环境变量），指向你的 9router 网关 —— 没有隐式回退端点；未配置端点时 provider 会报告自身不可用。
- 如果你的 9router 实例需要密钥，将 NINE_ROUTER_API_KEY 存入 DSH 凭据服务 —— 设置卡片中的 API key 字段会写入该凭据 —— 或在插件设置中设置字面 apiKey。该密钥在 UI 中为只写，绝不会被存储到本仓库。无密钥的实例开箱即用。

3. 重启并刷新

重启 Harness，然后强制刷新浏览器。web 设置卡片中会出现 9router 选项。

🔒 可复现安装 — 追加发布标签（或 commit SHA）以锁定精确版本：

npx @deepseek-ai/dsh plugin --profile web add github:lordraiden/dsh-9router-web-search#v0.2.3

🛠️ 配置

| 键 | 类型 | 默认值 | 说明 |
| baseURL | string | — | 你的 9router 兼容 API 的基础地址（仅限 http/https）；解析顺序：显式设置 → NINE_ROUTER_BASE_URL 环境变量 → 缺失（provider 不可用） |
| searchModel | string | search-combo | 搜索端点使用的模型名 |
| fetchModel | string | fetch-combo | 抓取端点使用的模型名 |
| searchType | string | web | 发送到搜索端点的 search_type |
| defaultMaxResults | number | 8 | 仅当搜索请求未指定 maxResults 时使用的来源上限（DSH 接缝负责执行每操作限制） |
| timeoutMs | number | 30000 | 共享的每请求超时（各能力默认值） |
| searchTimeoutMs | number | 30000 | 仅搜索的超时；留空沿用 timeoutMs |
| fetchTimeoutMs | number | 30000 | 仅抓取的超时；留空沿用 timeoutMs |
| fetchFormat | string | markdown | 请求抓取端点返回的正文格式（markdown、text、html） |
| maxCharacters | number | 50000 | 抓取正文的字符上限；会发送给网关并在本地强制执行 |
| apiKey | secret | — | 字面 API 密钥（可选；无密钥 = 不发送 Authorization 头） |
| apiKeyEnv | credential-ref | NINE_ROUTER_API_KEY | 凭据服务的键名 |

自托管 9router 按自己的 provider 配置选择搜索/抓取后端，会忽略 searchModel/fetchModel；按模型路由的云网关请保留这两个字段。

端点优先级 — 显式 baseURL 设置优先于 NINE_ROUTER_BASE_URL 环境变量；两者都未设置时不存在端点，provider 会报告自身不可用。不会静默回退到仓库选定的远端。schema 会在任何请求发出前拒绝非 http(s) URL、空的模型/格式字符串和非正的数值限制。

凭据 — NINE_ROUTER_API_KEY 通过 DSH 凭据服务解析；字面 apiKey 可选，设置后优先。apiKeyEnv 是凭据服务中的引用名，不是密钥本身。该密钥在设置 UI 中为只写，绝不存储到 git，也不会出现在日志、诊断信息或错误消息中。

📌 DSH 兼容性

| | 版本 |
| 最低支持版本 | 0.1.7-rc.1（peer 范围 >=0.1.7-rc.1 <0.3.0） |
| 最新已验证版本 | 最新发布的 0.2.x —— CI 会安装它（当前为 0.2.0-rc.2）并针对其运行完整测试套件 |

CI 与发布工作流都会运行共享的兼容性检查（scripts/check-dsh-compat.mjs）：一次针对声明的最低版本，一次针对最新发布的 0.2.x。检查失败会在创建发布前停止工作流。声明范围之外的版本 —— 包括未来的 1.x 发布 —— 在以前述方式实际验证之前，不会声称兼容。

🛡️ 9router 安全

web_fetch 能力将 URL 提取与 SSRF 防护委托给 9router 服务端：插件把目标 URL 发送到 POST /v1/web/fetch，并信任网关的抓取边界。插件自身不实现任何本地 SSRF 策略。

请运行已打补丁的、当前版本的 9router —— 抓取端点存在已发布的安全公告：

- GHSA-qj3v-64wj-q825

🧪 开发

pnpm install # 安装依赖
pnpm test # 运行测试套件（node:test）
node scripts/validate-pack.mjs # 校验打包产物

Node >=20（CI 使用 Node 22）与 pnpm（CI 使用 pnpm 10）。

仓库结构

dsh-9router-web-search/
├── src/ # 服务端插件：index.js + nine-router-client.js ├── client.js # 设置卡片 ├── cordis.patch.yml # 注册插件的 bundle patch ├── test/ # node --test 契约测试套件 ├── scripts/ # validate-pack.mjs、sync-storefront.mjs ├── .github/workflows/ # CI（测试 + 打包、DSH 0.2.x 兼容）与发布 └── package.json # ESM 插件清单

发布 — 稳定版本以与 package.json 匹配的 v<version> GitHub Releases 发布；发布 workflow 会在发布前针对 tag 重新运行完整测试套件与打包校验。

Storefront 同步 — node scripts/sync-storefront.mjs 将插件条目同步到 storefront 仓库（手动执行；需要向已配置的 storefront fork 拥有推送权限）。

🌱 生态与发布

- 📦 分发 — GitHub 仓库是唯一的分发来源；稳定版本以 v<version> GitHub Releases 发布。
- 🐛 问题与需求 — 请提交 issue。

📄 许可证

MIT

🙏 致谢

本项目最初 fork 自 rebron1900/dsh-web-search-9router —— 感谢原作者为 DeepSeek Harness（DSH）提供 9router 背书的网页搜索与抓取 provider。