dsh-deepseek-search

dsh plugin --profile web add dsh-deepseek-search

dsh-deepseek-search




简体中文 ｜ [English](README.en.md)

一个 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](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 写法。

覆盖示例：

…(truncated)