---

这是什么

DSH 自带的搜索要么走 dsh-free-search 的公开引擎，要么走官方 deepseek-official provider——后者把搜索塞进一次完整的 Anthropic Messages 调用（web_search_20250305 server tool），每次搜索都要跑一整个模型轮次并产生 token。

本插件直接调用 DeepSeek 专用工具 API，搜索与抓取都是一次普通的 HTTPS 请求：

工具	端点	返回
web_search	POST https://api.deepseek.com/v1/tools/search	results[]（title / url / snippet / summary / content / date / authority …）
web_fetch	POST https://api.deepseek.com/v1/tools/fetch	{ title, content }，content 为 Markdown

API 文档：https://api-docs.deepseek.com/zh-cn/guides/search　计费：搜索与抓取各 每 1,000 次成功请求 5 元，count 不影响价格，QPS 各 5。

插件在 ctx.web 的两个注册表各注册一个 provider（id 均为 deepseek-tools），所以整条链路只需切换一次 provider，不需要改动任何官方包。

特性

• 不花模型 token：返回的是 API 已整理好的 summary（600–800 字），并附带 date 与 authority。
• 无需钉死配置：apply 时自动接管「未设置 / 仍是出厂默认 / 被 dsh-free-search 抢先注册」的 provider；已被别人钉住时只留一行警告，绝不抢。
• 优雅降级：插件没加载，原本的 provider 继续工作；web_fetch 遇到 403/404/超时/空正文可退回匿名 HTTP 抓取。
• 设置页 Search Tools：生效状态条、密钥管理、真实连通性测试、逐条搜索明细、用量汇总（简中 / English 双语）。
• 一处记录：明细与用量写在 <DSH_HOME>/plugin-data/deepseek-search-tools/usage.json，原子写入，写失败也绝不影响搜索本身。

安装

前置：dsh plugin 只是把参数转发给 pnpm，所以 pnpm 必须在 PATH 里（npm i -g pnpm）。 DSH 桌面版自带一份 pnpm（resources/runtime/pnpm），但不会注入终端 PATH，命令行安装需要自己装。

名称说明：npm 上 searchtools 已被占用，本包发布名是 deepseek-search-tools； 安装命令里的标识就是这个包名。

从 npm（推荐）

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

从 GitHub

dsh plugin --profile web add github:ansellchen-boop/deepseek-search-tools

也可以直接装 release 附件（pnpm 支持 tarball 与 URL）：

dsh plugin --profile web add https://github.com/ansellchen-boop/deepseek-search-tools/releases/download/v0.1.0/deepseek-search-tools-0.1.0.tgz

启用 bundle

dsh plugin add 只做包安装（转发给 pnpm），还需要让 profile 加载它。编辑 ~/.dsh/profiles/web/package.json：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        // …
        "deepseek-search-tools"
      ]
    }
  }
}

或者从 DSH 设置页的 Plugins 页签启用它（该页会在安装成功后自动把声明了 dsh.bundle 的依赖写进 bundles）。

从旧包名 dsh-deepseek-tools 升级时，旧的明细日志会被自动接续读取，不需要手动搬移。

然后重启 dsh web（桌面端则重启应用）。重新打开会话问一个需要联网的问题，web_search 就会走 /v1/tools/search。

本地开发

dsh plugin --profile web add link:C:\path\to\deepseek-search-tools

link: 安装的包在 pnpm install 之后依然有效，改完 lib/client.js 只需在 GUI 里按 Ctrl+R（浏览器端 bundle 每次请求都从磁盘读），改 lib/index.js 才需要重启。

配置

# ~/.dsh/profiles/web/cordis.patch.yml（可选：想固定 provider 时再加）
- insert:
    - id: web-search-deepseek-tools
      name: deepseek-search-tools
      config:
        # apiKeyEnv: DEEPSEEK_API_KEY
        # baseUrl: https://api.deepseek.com
        # searchPath: /v1/tools/search
        # fetchPath: /v1/tools/fetch

键	默认	说明
apiKeyEnv	DEEPSEEK_API_KEY	要解析的凭据名称
baseUrl	https://api.deepseek.com	API 根地址（结尾斜杠自动去除）
searchPath	/v1/tools/search	搜索路径
fetchPath	/v1/tools/fetch	抓取路径
localization	""	非空时发送 localization（IP 提示，让结果更贴近当地）
includeContent	false	发送 need_content: true，结果直接带正文（token 更多）
fetchFallback	true	web_fetch 遇到 403/404/超时/空正文时退回 http provider
takeOverSearch	true	web.searchProviderId 未设置或仍为出厂默认时接管
takeOverFetch	true	同上，对象是 web.fetchProviderId
timeoutMs	60000	单次请求超时
maxSourceChars	4000	单条来源交给模型的上限
apiKey	""	直接写死的密钥，优先于凭据服务
enableSettingsPage	true	是否挂上设置页的「Search Tools」栏目
usageDataDir	""	用量记录目录，空串表示 <DSH_HOME>/plugin-data/deepseek-search-tools
usageLimit	2000	明细保留条数
usageDays	7	用量汇总的每日序列天数

不钉 web.searchProvider 是刻意的：- id: web 写进的是「配置」，配置活得比插件久；插件加载失败时 web_search 会变成每次都报 configured web provider "deepseek-tools" is not registered。运行期接管则是优雅的。真要「插件不见就大声失败」：

- id: web
  config:
    searchProvider: deepseek-tools
    fetchProvider: deepseek-tools   # 想保留匿名 HTTP 抓取就写 http

注意 patch 是整行覆盖（不 merge）。

凭据

依次尝试，第一个有值者胜出：

1. ctx.get("credentials").resolve(apiKeyEnv) —— 凭据服务（已存的 ref、启动环境、dotenv 兜底）；
2. process.env[apiKeyEnv]。

DEEPSEEK_API_KEY 通常已经在 ~/.dsh/.credentials.yaml 里，不需要额外配置。缺失时报 WEB_PROVIDER_CREDENTIAL_MISSING 并直接写出变量名。也可以直接在设置页保存 / 清除密钥，写入的是 Harness 自己的凭据服务。

设置页：Search Tools

settings.section（id: "tools"）下有三个月签：

页签	内容
API 管理	顶部生效状态条（生效中 / 已接管但没有密钥 / 部分生效 / 未生效，并指出实际 provider），当前凭据（ref、来源 file/env/literal、掩码值）、端点、超时；「测试连接」会真打一次 /v1/tools/search；可直接保存或清除密钥。
搜索明细	每条 web_search / web_fetch：时间、类型、内容、请求条数、返回条数、成功/失败、耗时；失败附 API 错误串；可按 全部 / 搜索 / 抓取 / 失败 筛选。
用量汇总	总调用、今日调用、成功率、平均延迟、累计返回条数、近 7 日柱状图、清除统计。

• 记录文件：<DSH_HOME>/plugin-data/deepseek-search-tools/usage.json（原子写入，默认保留 2000 条）。
• 主机端由 lib/bridge.js 挂出五条 loopback 路由：/api/deepseek-search-tools/{overview,test,key-set,key-unset,usage-clear}，只接受 POST，只允许本机来源（socket.remoteAddress + Host + Origin），body 上限 64 KB。
• 语言：右上角 中文 / English 切换，文案全部走 lib/client.js 里的同一张 STRINGS 表，中文一律简体；默认中文，除非 document.documentElement.lang 是 en*；选择存在 localStorage["deepseek-search-tools:lang"]。
• 导航图标：外壳按 section id 查固定表决定图标，settings.section 没有 icon 选项。插件给自己的导航格加 data-ddt-nav-icon，再用 mask 画出放大镜（隐藏齿轮），不动 React 节点，所以换语言或重绘都不会坏。
• 只想用 provider、不要记录时设 enableSettingsPage: false。

离线自检

不需要 API key，也不需要 DSH：

node --import ./test/register-loader.mjs test/harness.mjs

87 项检查覆盖：provider 注册与 id 冲突、接管/不抢/交还的各种组合、available() 必须同步返回布尔值、请求格式（bearer、count 夹取、need_content、localization）、响应映射、fetch 标题融合与 http 退回、429 重试、缺凭据错误码、SearchResult.truncated 必须为 false（否则 web_search 会回 value is not lossless JSON）、五条桥接路由与防护（非 loopback 403、非 POST 405）、用量记录（成功失败都记且确实落盘）、浏览器 bundle 的加载与栏目注册，最后用 React hook 替身把整个 Search Tools 页真正渲染一遍（载入数据后、切换每个页签后、四种生效状态各一次、切到 English 再切回简体）。

加 --live <apiKey> 会多跑三项真端到端检查：

node --import ./test/register-loader.mjs test/harness.mjs --live sk-xxxx

文件

lib/index.js        插件本体（provider、凭据解析、请求/重试、接管逻辑、设置桥挂载）
lib/client.js       设置页浏览器端 bundle（Search Tools 栏目）
lib/bridge.js       设置页 loopback 路由
lib/usage.js        用量记录与汇总
cordis.patch.yml    可贴进 profile 的 patch 片段
test/harness.mjs    离线 + live 自我检查
test/loader.mjs     @deepseek-ai/* 模块解析垫片（仅测试用）

常见问题

dsh plugin --profile web add deepseek-search-tools 装完没反应？ 还需要把包名加进 profile 的 dsh.profile.bundles（见上文），重启 dsh web。

桌面版 profile 改不动？ desktop profile 由 Electron 应用独占管理（dsh --profile desktop --dump-config 会直接拒绝），必须在应用内重启或按 Ctrl+R。

和 dsh-free-search 冲突吗？ 不冲突。本插件只接管被它趁默认值抢下的 web-search-free / fs-quality-fetch，它其它工具（advanced_search、multi_search、research、weather …）照常。

402 / 401？ 余额不足与鉴权失败原样上报，不重试。

---

English

Deepseek-Search-Tools wires DeepSeek's dedicated Tools API into DeepSeek Harness (DSH) so the built-in web_search / web_fetch hit POST /v1/tools/search and POST /v1/tools/fetch directly — one HTTPS call instead of a full model turn, with date and authority metadata and no generated tokens.

dsh plugin --profile web add deepseek-search-tools
# then add "deepseek-search-tools" to dsh.profile.bundles in ~/.dsh/profiles/web/package.json
# and restart `dsh web`

It registers a provider in both ctx.web registries (id deepseek-tools), takes over only unclaimed/default providers, falls back to plain HTTP fetch on 403/404/timeouts, and adds a bilingual Search Tools settings page (status strip, key management, live connection test, per-call log, usage summary).

Run the offline check with node --import ./test/register-loader.mjs test/harness.mjs (87 checks, no API key needed).

许可

MIT © deepseek-search-tools contributors

插件清单收录主题：deepseek-harness-plugins · dsh-plugin