dsh-plugin-deepsearch

给 DSH 内置的 web_search 加一个开关：走 DeepSeek Search API（POST /v1/tools/search），还是走 DSH 默认的账号搜索。附带自动回退、设置页、侧栏开关和模型工具。

English | 中文说明

• 开关 ON（deepseek-api） — 内置 web_search 改由 DeepSeek Search API 提供服务。这是付费接口：成功请求由 DeepSeek 计费，开启前请以 DeepSeek 控制台中的当前价格为准。
• 开关 OFF（builtin） — DSH 默认路线：由账号在服务端完成搜索（一次搜索消耗一次模型轮次）。
• 切换立即生效，重启后仍保留：状态落盘在 $DSH_HOME/deepsearch-mode.json。
• 不会让搜索不可用。 没有 key、401、网络错误、429/5xx 重试用尽时，提供方会回退到之前的（或其他可用的）搜索提供方，并在 lastError 里说明原因。
• 零运行时依赖 —— 只用 node: 内置模块和全局 fetch，没有构建步骤。
• 设置页与侧栏开关支持中英双语。

它做了什么

插件由两半组成，必须配合工作：

半侧	文件	职责
Host	index.js	注册模型工具 deepsearch、注册搜索提供方（默认 id deepseek-search-api）、将 web.searchProviderId 切到本插件/切回、暴露 /deepsearch/ 下的 4 个 HTTP 路由、解析 API key。
浏览器	client.js	通过 window.__ModuleLoader__.load(...) 加载的手写 bundle：设置页 tab + 侧栏底部开关。

cordis.patch.yml 是 bundle patch：用 dsh plugin add（或从插件市场）安装时，包会装进 profile 的 node_modules（并记在 profile package.json 的 dsh.profile.bundles 里），bundle 层在启动时应用它——不需要再手工改 profile 的 patch。

三个入口

入口	位置	用途
设置页	设置 → 内置插件 →「DeepSeek 搜索」	开关、状态详情、测试接口、API key 编辑
侧栏开关	左侧栏底部常驻	一键切换，显示当前路线（API / builtin）
模型工具	deepsearch（status / on / off / search / fetch / check）	在对话里切换路线或直接发起搜索

安装

从插件市场安装

在 DSH 插件市场里搜索 dsh-plugin-deepsearch（或「DeepSeek 搜索」）并安装。市场会用包里的 dsh.bundle.patch 自动注册 Host 半侧。安装后，设置页 tab 出现在 设置 → 内置插件 →「DeepSeek 搜索」（英文界面为 Settings → Built-in plugins → DeepSeek Search）；第一次安装后可能需要刷新一次页面，浏览器才会加载到新的 client bundle。

从命令行安装

# 装进默认 profile
dsh plugin add dsh-plugin-deepsearch

# 或显式指定 profile：`web` 对应 dsh web 服务端
dsh plugin --profile web add dsh-plugin-deepsearch

桌面端（Desktop app） 使用 desktop profile / 应用内的插件市场 UI 安装（桌面端会用自己的 DSH home 管理 profile，不需要手输用户目录路径）。插件的浏览器半侧声明了 dsh.client.platform: "web"，桌面端的 web 壳同样会加载它。

如果是从仓库源码安装而不是从 registry 安装：先 npm pack，再用 dsh plugin add 安装生成的 tgz。

从 0.1.x 升级

0.1.x 没有 bundle patch，是手工安装的：在 profile 的 cordis.patch.yml 里加一条 insert：

- insert:
    - id: deepsearch
      name: dsh-plugin-deepsearch

0.2.0 起带上了 dsh.bundle.patch（包根目录的 cordis.patch.yml）。dsh plugin add 或插件市场安装不会往 profile patch 里写 insert 记录：它把包装进 profile 的 node_modules，记到 profile package.json 的 dsh.profile.bundles 里，再由 bundle 层在启动时应用包自带的 cordis.patch.yml。在以 bundle 方式安装 0.2.0 之前，请先删掉手工加的那条 insert——手写的 insert 加上 bundle 安装会把同一个插件加载两次。$DSH_HOME 下的开关状态文件与 key 文件会保留，所以升级后开关状态和 key 都还在。

profile 名字因客户端而异：dsh web 服务端用 dsh plugin --profile web add dsh-plugin-deepsearch；桌面端用 desktop profile 和它的插件市场 UI。不要手写完整 profile 路径，让 dsh plugin 自己解析。

卸载

从 profile 卸载这个包（或在插件市场里卸载）即可，插件不会往 profile 里加别的文件。$DSH_HOME 下的 deepsearch-mode.json（状态）、deepsearch-diag.json（诊断）和可选的 deepsearch-key.txt（key 文件）可以删掉，也可以留着以后重装用。

配置

配置来自 profile patch 中本插件条目的 config 块；所有值都会被规范化，非法值回退默认值而不会抛错：

- insert:
    - id: deepsearch
      name: dsh-plugin-deepsearch
      config:
        apiKeyEnv: DEEPSEEK_API_KEY
        count: 8
        retryCount: 1

所有 key 都是可选的。下表与 Host 的配置 schema 一致，bundle 安装也可以携带同样的 config。

配置项	默认值	规范化 / 含义
apiKey	''	内联 API key。字符串，去首尾空白；空字符串表示未设置。不推荐：它会留在 patch 文件里。任何路由都不会回显它。
apiKeyEnv	'DEEPSEEK_API_KEY'	要解析的凭据引用 / 环境变量名。必须匹配 /^[A-Za-z_][A-Za-z0-9_]*$/，否则使用默认值。
baseURL	'https://api.deepseek.com'	API 根地址。去首尾空白；必须能解析为 http(s) URL；末尾斜杠会被去掉。
searchPath	'/v1/tools/search'	搜索接口路径（拼在 baseURL 后）。去空白、强制以 / 开头；含 ? 或 # 的值会被拒绝；空值回退默认。
fetchPath	'/v1/tools/fetch'	抓网页接口路径（规则同 searchPath）。
keyFile	''	文件形式的 key 路径。'' 表示 $DSH_HOME/deepsearch-key.txt；~/... 展开到用户主目录；相对路径解析到 $DSH_HOME 下；其他按绝对路径使用。
count	8	搜索结果条数。整数，夹取到 1..50。
needContent	false	是否让搜索接口返回正文（只影响直接调用 deepsearch search）。只有严格的 true 才开启。
timeoutMs	30000	单次 HTTP 请求超时。整数，夹取到 1000..120000。
retryCount	1	首次之外的重试次数（针对 408/429/5xx）。整数，夹取到 0..3。
retryDelayMs	1200	两次重试之间的等待时间。整数，夹取到 100..10000。
maxFetchChars	20000	fetch / 请求正文的 search 工具最多返回的字符数。整数，夹取到 1000..200000。
providerId	'deepseek-search-api'	注册的搜索提供方 id。必须匹配 /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/，且不能与已存在的其他提供方冲突（本插件自己的重复注册除外）。
fallbackProvider	''	关闭开关时优先回退到的提供方 id。空字符串表示自动判断（先前使用的提供方，然后是第一个可用的非本插件提供方）。
fallbackOnError	true	Search API 调用失败时是否回退到其他提供方。只有严格的 true 才开启。
language	'auto'	auto / en / zh。auto 依次读取 DSH_LANGUAGE、DSH_LOCALE、LANG、LC_ALL（中文 locale 解析为 zh，其余为 en）。
checkQuery	'DeepSeek'	「测试接口」按钮使用的查询词。去空白、非空、最长 128 个字符。

规范化后的 config 会通过插件状态（以及 deepsearch 工具的 status 动作）只读暴露，不含 apiKey。key 本身永远不会出现在诊断、日志或任何响应体里。

API Key

Search API 需要 DeepSeek 官方 API key。按以下顺序解析，命中即停：

1. patch config 里的 apiKey（内联，不推荐）。
2. DSH 凭据：apiKeyEnv（默认 DEEPSEEK_API_KEY）对应的凭据引用——与 DSH 自带的 设置 → 内置插件 → 网页搜索 页保存的是同一个引用，本插件复用它。
3. 环境变量 process.env[apiKeyEnv]。
4. key 文件（keyFile，默认 $DSH_HOME/deepsearch-key.txt，第一行是 key）。设置页可以帮你保存/清除这个文件。
5. $DSH_HOME/.env 里的一行 DEEPSEEK_API_KEY=sk-...（变量名跟随 apiKeyEnv）。

在设置页或 deepsearch status 里确认结果：key.configured 表示是否找到 key，key.kind 是 config、credentials、env、file、env-file 之一，key.source 给出具体来源（环境变量名或文件路径）；key.hint 会用当前界面语言给出同样的说明。

key 处理规则：

• key 只在发起请求时读取，不会被打印、记录日志、写进诊断文件，也不会被任何路由返回。
• 设置页提供密码输入框 + 保存 / 清除 按钮。保存会把 key 写到配置的 key 文件（尽力设置文件权限 0600）；保存后不会再渲染出 key 的值。
• 没有 key 也不会坏：开关可以保持 ON，提供方会回退到默认账号搜索并说明原因。

切换与回退

• 打开开关（ON）时，如果当前激活的搜索提供方不是本插件，会先把它记为 previousProviderId，再把 web.searchProviderId 设为本插件的提供方。
• 关闭开关（OFF）时按以下顺序恢复：记住的前一个提供方（若仍注册）→ 配置的 fallbackProvider → 第一个已注册、不是本插件且未被标记不可用的提供方 → 最后退而使用记住的前一个提供方（即使它已不在注册表里，作为最佳猜测）。如果没有任何其他提供方，保持当前提供方并返回错误，绝不清空 id。插件不会硬编码 deepseek-official。
• 提供方级错误回退： 若 fallbackOnError 为真且 Search API 调用失败（缺 key、401、网络错误、重试用尽），同样的解析逻辑会选一个其他提供方并返回其结果，记录 kind: 'provider.fallback'。fallbackOnError: false 时始终抛出原始的结构化错误。
• 取消和超时永不回退 —— 调用方已取消或请求已超时后，不会偷偷再跑一次账号搜索。
• 提供方的 available() 恒为 true：缺 key 或 API 故障不会让内置 web_search 消失，只会降级到回退。

设置页与侧栏开关

• 设置 → 内置插件 →「DeepSeek 搜索」：开关（role="switch" 并带 ARIA 属性）、状态行、「测试接口」按钮、详情网格（模式、当前提供方、key 来源、搜索/抓取接口、结果条数、最近调用、最近错误）、API key 编辑区、无 key 时的提示，以及诊断里的接线警告。页面每 5 秒轮询一次状态。
• 侧栏底部开关：一键切换，显示当前走 API 还是 builtin 路线，带本地化 tooltip。每 8 秒轮询一次。

所有页面文案都来自插件自己的 dsh-plugin-deepsearch locale 词典（中文 / 英文），会跟随 DSH 的语言设置。

模型工具

Host 注册一个面向模型的工具，名字是 deepsearch：

动作	作用
status	返回当前模式、提供方路由、key 状态（不含 key）、接口地址、最近结果/错误。
on / off	与 UI 开关走同一套逻辑切换路线。
search	直接调用 Search API，参数 { query, count?, needContent? }；开启回退时失败会自动回退。
fetch	通过 /v1/tools/fetch 抓取一个 URL，返回截断后的正文和元数据。
check	用一次最小查询验证接口连通性，供「测试接口」按钮和快速自检使用。

也可以直接在对话里说「打开 / 关闭 DeepSeek 搜索」，agent 会调用 deepsearch 工具切换；工具描述里会写明设置页的英文位置，以及配置写在 profile patch 里。

HTTP 路由

浏览器半侧通过 /deepsearch/ 下的四个路由与 Host 通信：

方法	路径	用途
GET	/deepsearch/state	状态快照（不含 key）。
POST	/deepsearch/mode	设置模式：{ "mode": "on" } / { "mode": "off" }。
POST	/deepsearch/check	单飞的接口连通性检查。
POST	/deepsearch/key	保存/清除 key 文件：{ "action": "save", "key": "..." } / { "action": "clear" }。绝不回显 key。

这些路由不走 DSH connection 鉴权，所以 Host 自行校验：只接受约定的 method；POST 必须 content-type: application/json、浏览器 Origin 与 Host 同源；拒绝 Sec-Fetch-Site: cross-site；/check 单飞（同时只允许一个请求）。这能挡一般 CSRF，但不替代鉴权——DSH 的 web 服务仍应只监听本机。

安全与可靠性

• apply() 永不抛错；坏配置会被规范化，而不是让宿主崩溃。
• API key 不会被记录日志、回显、由路由持久化，也不在状态快照里；唯一的写入是显式保存动作（文件权限 0600，Windows 上尽力而为）。
• 取消和超时不会触发回退搜索；回退目标失败时以结构化错误结束，而不是在别处静默重试。
• 重试只会在 408/429/5xx 上做 retryCount 次额外尝试，间隔可配置；401 映射为凭据错误，不会进入重试循环。
• lastError 用英文 scope 字符串记录，并在下一次成功调用时清掉，避免页面一直显示过期错误。
• 零运行时依赖、没有构建步骤：只用 Node 内置模块和全局 fetch。

兼容性

• DSH： >=0.1.7-rc.1 <0.2.0 || >=0.2.0-rc.1 <0.3.0-0（声明在 package.json 的 engines.dsh 里）。显式预发布分支让 0.2.0-rc.2 这类宿主能被正确解析；单个宽范围会静默排除预发布版本。
• Node： Host 半侧与测试套件要求 >=20（已在 Node 24 上验证）。
• Profile： web（浏览器访问的 DSH）与桌面端（Desktop app）；浏览器半侧声明 dsh.client.platform: "web"。
• 无第三方包、无 post-install 脚本，不需要 allowBuilds 之类的构建授权。

开发与测试

仓库是零依赖的纯 ESM 包，跑测试不需要安装任何东西。所有测试文件都是普通 Node 脚本，打印 ok/FAIL，失败时以非零码退出（不用测试框架）；测试全程离线，host/client 测试会 mock fetch。

node test/package.test.mjs   # 清单、bundle patch、文档与版本一致性
node test/host.test.mjs      # Host 半侧：假 Cordis ctx + mock fetch
node test/client.test.mjs    # 浏览器 bundle：假 module loader / react / locale

或者按顺序全部跑：

npm test

npm publish 会通过 prepublishOnly 跑同一套测试。CI 只需在 Node 20/22/24 上跑 npm test，不需要 npm install 步骤，就足以保证这个包始终处于可收录状态（见 PUBLISHING.md）。

文件

文件	作用
index.js	Host 半侧：deepsearch 工具、搜索提供方、路线切换、HTTP 路由、key 解析。
client.js	浏览器半侧：设置页 tab + 侧栏开关（手写 bundle，无构建步骤）。
cordis.patch.yml	Bundle patch：dsh plugin add 时注册 Host 半侧。
package.json	包清单、dsh.bundle / dsh.client 元数据、版本唯一来源。
README.md / README.zh.md	英文 / 中文文档（本文件与英文版）。
CHANGELOG.md	版本历史。
PUBLISHING.md	维护者清单：身份替换、npm 发布、市场投稿。
LICENSE	MIT。
icon.svg	插件市场使用的小方图标。
test/	打包、Host、浏览器三套测试。

许可证

MIT。Copyright (c) 2026 SeaViod。

问题或 bug 反馈：提交 issue。