dsh-plugin-deepsearch

dsh plugin --profile web add dsh-plugin-deepsearch

dsh-plugin-deepsearch

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

[English](README.md) | 中文说明

• 开关 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、网络错误、重试用尽），同样的解析逻

…(truncated)