搜索抓取 zou-hong-run/dsh-deepseek-search

dsh-deepseek-search

简体中文 ｜ English

一个 DeepSeek Harness 插件：在 ctx.web seam 上注册网页搜索和网页抓取两个 provider，后端使用 DeepSeek 原生的 Search / Fetch JSON API。

它接入 harness，而不是自带模型工具：模型侧 web_search / web_fetch 的 schema、provider 选择与结果渲染仍由 dsh-tool-web 负责；本包只提供两个后端。

功能

- 搜索 provider — POST <baseURL>/search，默认 https://api.deepseek.com/v1/tools/search，映射为 WebSearchResult 的 sources（url、title、snippet、publishedAt）。
- 抓取 provider — POST <baseURL>/fetch，返回 text 类型的正文，内容为服务方抽取出的 Markdown。
- 同一个 id 覆盖两类能力 — 都注册为 deepseek-search；bundle patch 把 searchProvider 和 fetchProvider 都指向它。
- 凭据分层 — 显式 apiKey → ctx.credentials（设置页写入的就是这里）→ 启动环境；每次调用解析，换 key 不需要重启。
- 实时配置 — 所有字段都是 volatile，provider 每次操作读一次；保存即对下一次调用生效。
- 检索请求 — 固定发送 need_content: false（只要摘要，不拉整页正文），并可按配置附带 ori_question：发起本轮的人类提问，压空白后截 128 字。
- 重试 — 对 408、429、500、502、503、504 指数退避，尊重 Retry-After（上限 8 秒）。
- 可取消 — 响应 seam 传入的 AbortSignal，取消后以 WEB_ABORTED 结束。
- 有上限的 I/O — 原始响应 8 MiB，解压后 16 MiB。
- 稳健解码 — 按魔数识别 gzip/zlib，宿主安装不同版本的 undici dispatcher 也不会让 response.json() 失效。

与自带 DeepSeek provider 的区别

DSH 0.2.1-rc.5 自带两个 DeepSeek 后端：

| | deepseek-official | deepseek-search-api / deepseek-fetch-api | 本插件 |
| 包 | dsh-web-search-deepseek | dsh-web-deepseek-api | dsh-deepseek-search |
| 搜索后端 | Anthropic 兼容的 web_search 工具 | 原生 POST /v1/tools/search | 原生 POST /v1/tools/search |
| 抓取后端 | 无 | 原生 POST /v1/tools/fetch | 原生 POST /v1/tools/fetch |
| 模型回合 | 有一次完整模型请求 | 无 | 无 |
| 自动重试 | 无 | 无 | 408/429/5xx 退避，可配 |
| DeepSeek Account 登录 | 支持 | 支持 | 不支持，只用 API key |
| 配置命名空间 | web-search-deepseek | web-deepseek-api | dsh-deepseek-search |

deepseek-search-api 自 0.2.1-rc.5 起覆盖了同样的两个端点，所以能力上本插件与它基本等价。选择本插件的理由只剩：需要可配置的重试/退避、希望使用独立的配置命名空间、或者不想动 profile 里官方行的配置。如果这些都不需要，直接用自带的 web-deepseek-api 即可（设置页 “Web search” 开关就能切换）。

环境要求

- DeepSeek Harness 0.2.1-rc.5 或同一 minor 内的版本（engines.dsh 与 peer 范围都是 ^0.2.1-rc.5）。
- 用 dsh CLI 操作时需要 Node.js 24+（CLI 入口用 import.meta.main，Node 22 会静默退出）；插件本身跑在宿主进程里，不额外要求 Node 版本。
- 一个可访问 /v1/tools/search 与 /v1/tools/fetch 的 DeepSeek API key。调用由 DeepSeek 计费。

安装

从 npm（推荐）

Plugins → Add plugin → dsh-deepseek-search

或者命令行 / 智能体工具：

dsh plugin --profile <profile> add dsh-deepseek-search

plugin_manager install_bundle target: dsh-deepseek-search@0.1.0

从 GitHub（不经过 npm）

dsh plugin --profile <profile> add github:zou-hong-run/dsh-deepseek-search

本地开发目录：传绝对路径，或 link:<目录>。

plugin_manager install_bundle target: C:\path\to\dsh-deepseek-search
包名是 dsh-deepseek-search（无 scope）。有些注册表站按仓库显示成 @zou-hong-run/dsh-deepseek-search，指的都是同一个仓库；安装请用 npm 名或上面的 github: 地址。

不要用 install_bundle 之外的手工 pnpm / 清单修改代替它，那会绕开版本检查与回滚。

安装后 bundle 会被选中，插件行立即出现（HMR 生效），无需重启。Plugins 清单里应显示 DeepSeek 搜索与抓取。

安装只会往 profile 里加这个包和它自己的依赖 @deepseek-ai/schemastery：profile 的 pnpm 配置是 autoInstallPeers: false，peer 不落盘；@deepseek-ai/dsh-web 等由 DSH 的运行时解析指向安装包自带的那一份，不会出现第二份，WebError 的类身份因此保持一致。

如果插件本身起不来，web 行仍然钉着 deepseek-search，web_search / web_fetch 会以 WEB_PROVIDER_CONFIGURED_MISSING 失败；在 Plugins 里禁用这个 bundle（或把自己 patch 里的 web 行改回官方 id）即可恢复，进程不受影响。

如果 profile 自己也钉了 web 行

profile 的 cordis.patch.yml 在所有 bundle 之后应用。如果那里已经把 web.searchProvider / fetchProvider 钉到官方 id，bundle patch 会被它覆盖 —— 插件装上了但不会被选中。把它改成 deepseek-search，或删掉那一行。

关于插件市场

插件市场（Discover）读的是用户自己配置的 JSON 索引（plugin-market 的 indexes），不是 npm 搜索。所以：

- 只把包发布到 npm 并不会让它出现在 Discover；
- 需要先发布（或托管 git 仓库），再让某个市场索引收录这个包和版本；
- 本机 desktop profile 默认没有挂载 plugin-market，也没有配置索引，Discover 里自然是空的。

本仓库自带一份索引 market/index.json（Pages 从仓库根目录发布，所以它在根下的 market/），发布后把这个地址加到 Plugins → Discover → 添加索引源：

https://zou-hong-run.github.io/dsh-deepseek-search/market/index.json

每次发版把新版本追加进 versions 数组（publishTimestamp 用发布时刻的 Unix 秒）。

验证

dsh --profile <profile> --dump-config

其中 web 行应包含：

- id: web
name: '@deepseek-ai/dsh-web'
config:
searchProvider: deepseek-search
fetchProvider: deepseek-search

之后在会话里调用 web_search 或 web_fetch 即可。本插件没有自己的模型工具名。

凭据

每次操作按以下顺序解析：

1. 插件配置里的 apiKey（字面量，慎用）
2. ctx.credentials 中 apiKeyEnv 指向的引用（默认 DEEPSEEK_API_KEY；设置页/Models 页写入的就是这里，.credentials.yaml 也由它支撑）
3. 启动环境里的同名变量

apiKeyEnv 必须是 POSIX 标识符（[A-Za-z_][A-Za-z0-9_]*），否则回落到默认名。旧版的 DEEPSEEK_SEARCH_API_KEY 快捷方式已移除：要沿用就设 apiKeyEnv: DEEPSEEK_SEARCH_API_KEY。

available() 只做本地检查（baseURL 能解析成 http/https、count 合法），不预检凭据。这是刻意的：凭据库是异步的，同步可用性检查没法定论，所以缺 key 时 search()/fetch() 以 WEB_PROVIDER_CREDENTIAL_MISSING 失败，给出可操作的提示，而不是让 seam 报 WEB_PROVIDER_CONFIGURED_UNAVAILABLE。官方 provider 也是这个取舍。

在启动环境里设置 key：

export DEEPSEEK_API_KEY=sk-...
dsh web

或在 profile patch 里覆盖插件条目：

- id: dsh-deepseek-search
config:
apiKey: sk-...

配置

| 键 | 默认值 | 作用 |
| apiKey | 未设置 | 字面量凭据，优先于凭据服务与环境变量 |
| apiKeyEnv | DEEPSEEK_API_KEY | 凭据引用名，经 ctx.credentials 解析，缺失时回落启动环境 |
| baseURL | https://api.deepseek.com/v1/tools | API 基地址，含路径前缀；自动拼接 /search 和 /fetch |
| count | 10 | 每次搜索的结果数上限（1–50）；请求的 maxResults 只能把它调小 |
| maxRetries | 2 | 首次尝试之后的重试次数 |
| retryDelayMs | 800 | 指数退避的基础延迟 |
| sendOriginalQuestion | true | 是否把发起本轮的人类提问作为 ori_question 发送 |

baseURL 的语义与官方 web-deepseek-api 一致：填到操作名前为止，默认值已经包含 /v1/tools。填成裸域 https://api.deepseek.com 会得到 /search，那是错的。

这些字段也能在 Plugins → 本 bundle 的详情页里直接编辑（bundle 自带配置页，保存后对下一次调用生效）；headless 部署继续用下面的 patch 写法。

覆盖示例：
- id: dsh-deepseek-search
config:
baseURL: https://api.deepseek.com/v1/tools
count: 5
maxRetries: 1

bundle patch 会整行替换 web 的 config。如果你的部署还需要在 web 行上保留其他键，请在自己的 patch 层里一并写回（用户 patch 在 bundle 之后应用）。

请求与字段映射

搜索 请求体：

{ "query": "...", "count": 5, "need_content": false, "ori_question": "..." }

ori_question 取发起本轮会话里的最后一条人类消息，压空白后截 128 字；没有会话、没有人类消息或 sendOriginalQuestion: false 时省略该字段。

seam 的词汇比 DeepSeek 响应窄，部分字段会被有意丢弃：

- snippet → snippet，date → publishedAt、title → title。
- summary 不进入 seam：服务方实测每条 1000–2300 字，作为 snippet 会把 web_search 的输出撑大好几倍；content（整页正文）同理。
- authority、rerankScore、siteName、siteIcon 在 seam 中没有对应字段。

抓取 返回 { kind: 'text', content }。WebFetchResult 没有标题字段，抽取出的 title 会被丢弃。statusCode 固定为 200：DeepSeek 报告的是自身抽取状态，不是源站 HTTP 状态（服务方在目标页无可用内容时直接返回错误状态）。truncated 保持 false，按结果数截断由 seam 负责。

结果数 — count = min(配置 count, 请求 maxResults ?? 配置 count)，再受 API 上限 50 约束。

错误码

| 错误码 | 来源 | 含义 |
| WEB_PROVIDER_ERROR | 本插件 | 参数非法、服务方报错，或响应无法解析；派发后的失败会附上实际端点与 dsh-deepseek-search.baseURL 的修复指引 |
| WEB_PROVIDER_CREDENTIAL_MISSING | 本插件 | 字面量、凭据服务、启动环境都拿不到 key |
| WEB_ABORTED | 本插件 | 调用方 signal 触发，或请求被中止 |
| WEB_PROVIDER_CONFIGURED_UNAVAILABLE | DSH seam | 配置的 id 已注册，但 available() 返回 false（baseURL 或 count 非法） |
| WEB_PROVIDER_CONFIGURED_MISSING | DSH seam | 配置的 id 没有注册 |
| WEB_PROVIDER_AMBIGUOUS | DSH seam | 没有固定 id，且有多个可用 provider |

DeepSeek 返回的错误信息会拼在 HTTP <status> 之后透出。

开发

pnpm install
pnpm test

测试使用 node:test 并 mock globalThis.fetch，不需要 key，也不会发起真实网络请求。覆盖：配置快照与实时读取、凭据优先级与失败路径、可用性判断、结果映射、请求体（含 need_content / ori_question）、结果数上限、重试与取消、gzip 解码、参数校验、provider 注册。

在 DSH 沙箱里 node --test 可能因 spawn EPERM 失败（测试运行器要起子进程），可以直接把测试文件当普通 ESM 跑：node test/providers.test.mjs。

目录结构：

dsh-deepseek-search/
cordis.patch.yml # bundle patch：插入插件、改写 web 行 package.json # dsh.bundle.patch、engines.dsh、peer 范围、locale/icon 导出 lib/index.js # Config schema、两个 provider、传输层、apply()
locale/{en,zh}.json # 插件清单里的标题与描述
icon.svg # 插件清单图标 test/providers.test.mjs

限制

- 不支持 DeepSeek Account 登录令牌，只用 API key；需要账号登录请用自带的 web-deepseek-api 或 web-search-deepseek。
- /v1/tools/search 与 /v1/tools/fetch 由服务方维护，可能变更或限流；本插件不做本地爬取或 HTML 解析。
- 抓取结果是 DeepSeek 抽取器的输出；抽取失败的页面会以 WEB_PROVIDER_ERROR 结束。
- 插件只做检索，不运行模型回合，也不生成答案文本。
- 已在 DSH 0.2.1-rc.5 上验证；其他版本可能改变 loader 或 seam 契约。

许可证

MIT，见 LICENSE。

这是第三方插件，与 DeepSeek 官方无隶属关系。

English README