DSH-freeweb

DSH freeweb

DSH 免费网页搜索 provider：把 DeepSeek 官方按量计费的 web_search 切换成 Parallel 免费搜索后端（匿名免 key，永久免费层）。

• 🆓 真·零依赖（插件本身）：纯全局 fetch + 标准 JS，没有任何 import——不存在装完缺依赖崩溃的问题 （⚠️ 但插件页 / CLI 安装这条路径需要系统里有 pnpm；手动挂载不需要，见安装章节）
• 🧯 完整错误处理：所有异常返回诊断信息，不静默失败
• 📦 组合包形态（本插件 0.2.0 起）：声明 dsh.bundle，可从 Web 插件页安装/启停/卸载，卡片显示为 dsh-freeweb
• 🧹 干净可逆：插件页卸载；或手动方式 = 1 个文件 + 2 行 patch，删掉即回退
• ⚠️ 手动方式下，插件通过 cordis.patch.yml 引用本地文件 ./freeweb-search.js，该文件必须存在；缺失时 DSH 启动会报错——回退时请先删 patch 行，再删文件。

免费后端：Parallel Search

Parallel Search MCP 官方免费提供：AI agents 匿名调用，无需账号、无需 API key。免费层有速率限制（个人日常使用足够）；要更高限额可注册账号。

安装

分发方式：本插件通过 GitHub 仓库分发，尚未发布到 npm。下面三种方式都以「你手上的这份源码目录」为前提。

前置条件

• DSH：手动挂载（方式 C）需要 ≥ 0.1.5；组合包安装（方式 A / B）建议 ≥ 0.2.0（组合包链路仅在 0.2.0-rc.2 上实测过，见下文「版本声明」）
• Node.js ≥ 18（插件依赖全局 fetch；DSH 本身要求更高的版本）
• pnpm：仅方式 A / B 需要（DSH 的插件安装器由 pnpm 驱动，安装与卸载都调它）。没有 pnpm 时用方式 C，功能完全相同

方式 A：插件页安装（推荐，DSH 0.2.0+）

1. 侧栏 插件 → 添加插件
2. 输入本目录的绝对路径（例：D:\plugins\DSH-freeweb）
3. Host 会先 inspect（读 package.json 确认声明了 dsh.bundle）→ 安装 → 立即启用
4. 之后在 已安装 分组里出现 dsh-freeweb 卡片：可整包启停/卸载；点进去可单独启停它的行 freeweb-search

方式 B：命令行安装

npx @deepseek-ai/dsh plugin --profile web add "<本目录绝对路径>"

与方式 A 等价：都会把包装进 profile 依赖，并写入 package.json 的 dsh.profile.bundles。

方式 C：手动挂载（零打包，最轻）

⚠️ 与方式 A / B 互斥：两种方式同时存在会注册两个 freeweb provider，seam 以 WEB_DUPLICATE_PROVIDER 拒绝第二个。二选一。

1. 把 freeweb-search.js 放进 profile 目录：

~/.dsh/profiles/web/freeweb-search.js     （Windows: C:\Users\<你>\.dsh\profiles\web\）

2. 在 profile 的 cordis.patch.yml 追加（见 example-cordis.patch.yml）：

- id: web
  config:
    searchProvider: freeweb
    fetchProvider: http      # ⚠️ 必须带：config 是整段替换，不写会丢掉 dsh-base 的 fetch provider

- insert:
    - id: freeweb-search
      name: ./freeweb-search.js

3. 重启 DSH，模型侧的 web_search 工具自动走免费搜索。

技术细节：插件文件是标准 CJS（module.exports = { inject, apply }）；Loader 用动态 import() 加载它，并会归一化 CJS / default 的导出形状。

验证安装成功

先看界面（最快）

1. 侧栏 插件 → 已安装 里能看到 dsh-freeweb 卡片
2. 设置 → 内置插件 里 include:freeweb-search 显示「已启用 / 运行中」

再实测一次：让 agent 搜一次，能正常返回来源列表即可。

技术判据（排障用，需要读会话日志）

官方 DeepSeek 搜索 provider 每次都会往会话日志写一条 web/deepseek-search-llm-request 事件；freeweb 不写。所以搜索后：

升级 / 降级

• 升级：DSH 目前不支持插件自动更新。先卸载再装新版 （插件页卸载 → 再「添加插件」，或 CLI dsh plugin --profile web add <路径>）
• 降级：同样操作，装回旧版本即可
• 手动挂载方式没有版本概念——把文件换掉即可
• 若将来发布到 npm，可直接用包名 spec（如 dsh-freeweb@<version>）

插件页开关 = 接管开关（0.2.1 起）

启用/停用本插件，就是"用免费搜索 / 回官方搜索"的开关：

• 启用：apply 把 web.searchProvider 写成 freeweb，覆盖官方设置页里选的那个 （延迟 3 秒等 settings 服务挂载；失败只降级，不影响 provider 注册）
• 停用：不做任何清理 —— 接管写入的 freeweb 恰好等于本 bundle 的 patch 默认值， DSH 会把它规范化成"清除覆盖"；插件停用后 bundle patch 消失，配置自然回落到官方默认
• 官方设置页再改也会被抢回：插件监听 settings/document-updated，改动后重新接管

已知限制：

回退官方

故障排查

已知限制与设计权衡

与 DSH 0.2.0 的适配说明

版本声明是「声明式」的（重要）

package.json 里声明了官方规范定义的 dsh.manifestVersion: 1 与 engines.dsh， 但官方当前并不强制校验它们——官方文档原话：

兼容性仅作声明。当前安装器和加载器不强制检查 dsh.manifestVersion 或 engines.dsh； 声明范围不会拒绝不兼容的宿主，也不会校验 SemVer 语法。

所以：

• 不要把它理解为「DSH 会自动拦住不兼容版本」——它不会
• 实际兼容下限见下表，由实测得出，而不是由字段保证

保守建议：组合包方式在 DSH ≥ 0.2.0 上使用；更早版本请用「方式 C 手动挂载」。

版本说明

定位与取舍

DSH freeweb 追求极致轻量化与 DSH 自身安全，因此功能不会很强：

• 它是一份快速、无安全负担的免费联网方案——单文件、零依赖、匿名免 key；
• 适合联网搜索要求不大的玩家长期使用，或高要求玩家作为临时备选（Parallel 免费层有速率限制，且索引偏向英文）。

如果你需要更强的搜索（更精准的中文、更高频的调用），建议评估带 key 的商用搜索方案。本插件的价值在于：用最轻的代价，把"联网"这个基本能力免费补上。

设计说明（为什么这么写）

本插件的设计哲学：最小冲击、故障透明、取舍明确。

• 零依赖：只用一个全局 fetch 和标准 JS，没有任何 import。本包自身不引入任何依赖 （「插件页 / CLI 安装」所需的 pnpm 属于系统前置，见安装章节；手动挂载连它也不需要）。
• 朴素装配：只用最简单的 - insert: 引用同包内的本地文件，不用 !!js 表达式做存在性检查（其语法有其风险）。代价是文件缺失时 DSH 会报错——由安装/回退流程管理（README 已写明顺序）。
• 故障透明：apply 和 search 的每个失败分支要么返回诊断信息（通过 content 字段给模型），要么 console.error 留日志（如注册失败）。绝不静默吞错——但不向 Loader 抛错，避免影响 DSH 启动。
• 按码点截断：查询和摘录用 Array.from(...) 按 Unicode 码点截断，避免把 emoji 的代理对劈成半个产生乱码。
• 去重：多查询返回的重复 URL 会合并。
• 无配置界面：刻意不做 Config —— require('@deepseek-ai/schemastery') 在 profile 里解析不到 （插件走 ESM 解析，拿不到 DSH 安装目录里的包），三次尝试均失败，最终改为硬编码接管： 开关就是插件页的启用/停用，配置就是 patch 里那两行。
• 保持 CJS：module.exports = { inject, apply } 让"组合包安装"和"手动挂载"两种方式都能工作；改 ESM 会引入 type: module / .mjs 的解析约束。

与社区标准的协作

本项目关注并支持 dsh-std 社区互操作标准（dsh-ecosystem-spec 基线的 apiVersion + kind 协议坐标），待其 manifest 格式稳定后，将补充协议声明（dsh-plugin.json）。在此之前，本插件保持零依赖的独立形态，不与草案格式绑定。

Credits

设计协作：DeepSeek V4 Flash 0731（AI 协作者） 组合包适配与文档：DeepSeek V4.1 Flash（AI 协作者）

License

MIT — see LICENSE