dsh-web-search-free

dsh-web-search-free

中文 | English

DeepSeek Harness (dsh) 的免费 Web Search / 网页抓取插件。它把 dsh 默认的 deepseek-official 通道换成多引擎 + 自动 fallback：按你排的顺序依次尝试已填 Key 的引擎，失败或额度用尽就换下一个；同一引擎可填多个 Key（每行一个），按序轮换。

• 不烧模型 token：直接调各引擎的检索端点，不经过任何 LLM。
• 装上即接管，卸载即回落：以 dsh bundle 层安装，无需手改 profile。
• 自带配置卡片：拖动排序、填 Key、测试 Key、查看用量，界面语言跟随 dsh。
• 请求只从宿主进程发出：浏览器侧只有配置卡片，不直接访问任何外部服务。

为什么是 "free"

官方通道 deepseek-official 的每次搜索都是一次完整的模型调用（带服务端 web_search 工具），搜索请求本身和回灌进上下文的 sources 都从 DEEPSEEK_API_KEY 余额扣 token。

如果你的对话模型走第三方渠道、没配 DEEPSEEK_API_KEY，官方通道仍会被选中，直到模型真正调用 web_search 才报 WEB_PROVIDER_CREDENTIAL_MISSING。本插件不依赖任何 LLM 凭据。

支持的引擎

表格顺序即默认调用顺序：按可持续免费次数从多到少（不限量 > 每日重置 > 每月重置 > 一次性），相当时注册/绑卡门槛低的优先。

• 抓取：只能搜索的引擎（✗）不参与抓取。没有可用的抓取引擎时，web_fetch 退回无 Key 的 Jina Reader 和 dsh 本地抓取（见高级设置）。
• 结果日期：决定模型能否判断时效。Brave 最全（实测 18/20）；Tavily 通用搜索不返回日期，Firecrawl、AnySearch 没有该字段。在意时效可把 Brave 往前挪。

安装

前置条件：dsh ≥ 0.1.2-rc.1，pnpm 在 PATH 上。

在 dsh 界面里安装：侧边栏「插件」→ 右上角「添加插件」→ 输入 dsh-web-search-free → 「安装」。

或用命令行安装。配置卡片只在 Web 界面出现，因此一般装到 web profile：

dsh plugin --profile web add dsh-web-search-free

安装后 dsh 自动对账 dsh.profile.bundles，插件即接管 web 搜索与抓取。

例外：如果 profile 的 cordis.patch.yml 里已经有一条 - id: web（打开过 dsh「插件 → 网页搜索 → 启用新版 Web 搜索 API」开关就会写入），它会覆盖插件的设置，插件装上了也不会被调用。插件会在日志和卡片顶部提示这种情况，处理方法见插件没有接管搜索。

pnpm install
pnpm build                          # 生成 dist/（已 gitignore）
dsh plugin --profile web add .

dsh ≤ 0.1.2-alpha.5 不挂载 web 工具，装本插件后只有搜索、没有 web_fetch，请改用插件 1.3.0。

配置

运行 dsh web，找到配置卡片：

1. 点击引擎行展开，粘贴 Key（每行一个）；行内「获取 API Key ↗」直达申请页。
2. 拖动 ⋮⋮ 手柄调整「调用顺序」：靠前的先调，失败按序 fallback。
3. 顶部开关 「启用 web_fetch」：关闭后模型调用 web_fetch 会收到明确的错误。
4. 点 保存，下一次搜索即生效，无需重启。

至少要配一个引擎，否则搜索报 No web search providers configured.

卡片还提供（需 dsh 支持插件路由，已在 0.2.0-rc.2 验证；旧版本自动隐藏）：

• 测试 Key：每个 Key 做一次小搜索，显示成功与否、条数、耗时或原始报错。每个 Key 消耗一次额度。
• 用量统计：按引擎、Key 显示调用次数、成功率、平均耗时、最近错误、冷却状态和缓存命中。仅存内存，重启清零。
• 检查更新：由宿主进程查询 npm registry，有新版时给出升级命令。

高级设置

卡片底部「高级设置」默认收起，不改也能用。顶部的快捷预设（省额度 / 速度优先 / 质量优先 / 中文优先 / 恢复默认）可叠加，保存后生效。

每次 (引擎, Key) 尝试单独限时（搜索 10 秒、抓取 20 秒）。返回 401/402/403/429 或提示额度用尽的 Key 会暂时排到链尾（429 为 2 分钟，其余 30 分钟）。全部失败时，报错会列出每次尝试的原因（Key 已打码）。

手动配置

找不到卡片时（浏览器控制台会打印 [web-search-free] no settings card mounted: …，欢迎贴到 issue），可以直接编辑 ~/.dsh/profiles/web/cordis.patch.yml。插件安装时已插入 web-search-free 行，这里按 id 覆盖它的 config，不要再写 insert：

- id: web-search-free
  config:
    tavilyApiKey: tvly-xxxxxxxx
    exaApiKey: |-
      key-1
      key-2
    providerOrder: [tavily, exa, tinyfish]
    searchStrategy: merge

字段名见 src/index.ts 的 Config：<引擎>ApiKey（多个 Key 用多行字符串）、enableFetch、providerOrder 以及上表字段。改完重启 dsh 生效。dsh ≥ 0.1.7 的卡片也写这个文件，保存时会覆盖同名字段。

升级到 dsh 0.1.7 后 Key 不见了

dsh 0.1.7 把配置从 ~/.dsh/settings.yaml 迁移到 profile 的 cordis.patch.yml，迁移只跑一次。如果当时插件没能启动（1.5.x 在 0.1.7 上会卡在 "Failed to load plugins"），Key 会留在 ~/.dsh/settings.yaml.imported 里。插件检测到这种情况时，会在日志和卡片上提示。可以在卡片里重新填 Key，或者把下面这段交给 dsh：

把 dsh 主目录（默认 ~/.dsh）下 settings.yaml.imported 里 web-search-free 段的所有字段，原样写进当前 profile 的 cordis.patch.yml，作为 id 为 web-search-free 的 entry 的 config；该 entry 不存在就新增。保留原文件的注释和格式，改动前先备份。

插件没有接管搜索

dsh 的配置分层叠加：各 bundle 的 patch → profile 的 cordis.patch.yml → --patch，同一 id 的 config 整段替换，后面的层胜出。本插件的 bundle patch 把 web 指向 web-search-free，但如果 profile 的 cordis.patch.yml 里已经有：

- id: web
  name: "@deepseek-ai/dsh-web"
  config:
    searchProvider: deepseek-search-api
    fetchProvider: deepseek-fetch-api

插件这一层就被盖掉了。把两个值改成 web-search-free，或者整条删掉，保存后立即生效。

更新与卸载

dsh plugin --profile web update dsh-web-search-free
dsh plugin --profile web remove dsh-web-search-free

卸载后 web 搜索/抓取回落到 deepseek-official。注意：

• 卸载前先点卡片底部「清空全部配置」，否则 Key 会留在 dsh 的配置文件里。
• 卸载后重启 dsh，否则搜索会报 WEB_PROVIDER_CONFIGURED_MISSING。

工作原理

插件是一个 dsh bundle 层：cordis.patch.yml 插入 web-search-free 行，并把 web 行的 searchProvider / fetchProvider 指向它。宿主半边（src/index.ts）注册搜索与抓取 provider，按 providerOrder 依次调用；客户端半边（src/client.tsx）提供配置卡片。实现细节见源码注释。

开发提示：@deepseek-ai/* 不能进 dependencies 或非 optional 的 peerDependencies，否则会在用户 profile 里装出一份私有副本、遮蔽宿主实例。改动 package.json 后请运行 pnpm run check（发布前也会自动检查）。

反馈

dsh 仍在快速迭代，插件可能有跟不上的时候。遇到问题请提 issue，附上 dsh 版本和报错信息。

许可证

MIT