搜索抓取工具 ansellchen-boop/deepseek-search-tools

Deepseek-Search-Tools

把 DeepSeek 专用搜索 / 抓取 API 接进 DeepSeek Harness，让 web_search 与 web_fetch 不再消耗模型轮次。

简体中文 · English

这是什么

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？ 余额不足与鉴权失败原样上报，不重试。

Deepseek-Search-Tools 把 DeepSeek 专用的 Tools API 接进 DeepSeek Harness（DSH），让内置的 web_search / web_fetch 直接打到 POST /v1/tools/search 和 POST /v1/tools/fetch——一次 HTTPS 调用，不用走一整轮模型，还带 date 和 authority 元数据，不产生任何 token。

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

它在 ctx.web 的两个注册表里各注册一个 provider（id 为 deepseek-tools），只接管无人认领或仍用默认值的 provider；遇到 403/404/超时退回普通 HTTP fetch；另外加一个双语 Search Tools 设置页（状态条、密钥管理、实时连接测试、逐次调用日志、用量汇总）。

跑离线检查：node --import ./test/register-loader.mjs test/harness.mjs（87 项检查，不需要 API key）。

许可

MIT © deepseek-search-tools contributors

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