Brave 搜索加固 nedzen/dsh-web-search-brave

dsh-web-search-brave

DeepSeek Harness（dsh）的 Brave Search 服务商插件 —— 经过加固，web_search 再也不会卡死你的会话，多查询搜索也不会再被 HTTP 429 限流淹没。

这是 DeepSeek Harness ctx.web 搜索服务商接缝的独立实现。它面向官方服务商接口，结构参照官方 @deepseek-ai/dsh-web-search-deepseek 服务商，这也是编写接缝服务商的官方文档做法。它不是另行开发的 dsh-web-search-brave 包的分支 —— 见兼容性。

与 DeepSeek 无关联，也未获其背书。 @deepseek-ai/... 包名沿用 DeepSeek 对接缝服务商的第一方命名惯例；它不是 DeepSeek 官方包，也从未发布到 npm。服务商接口与模块脚手架源自官方 @deepseek-ai/dsh-web-search-deepseek（MIT，© 2026 DeepSeek）；Brave 集成部分为本包原创。

- 关键词： DeepSeek Harness、dsh、dsh 插件、Brave Search API、web search 服务商、 web_search 工具、HTTP 429 限流、请求超时、智能体工具调用卡死

修复的 bug

如果你的 dsh 会话曾在调用 web_search 工具时卡死 —— 转圈不停、对话记录里什么都没有、有时还得整个重启 —— 原因就在这里。

0.1.1 里的 BraveSearchProvider.search() 没有设置自己的计时器，只把调用方的 AbortSignal 交给 fetch。DeepSeek Harness 通过 @deepseek-ai/dsh-tool-call-timeout-policy 执行工具超时，而它是明确的协作式：它等待工具 promise，不与它竞速。所以请求一旦不返回，就永远不会有工具结果被记录，这一轮会无限等待，界面看起来就像卡死了。

实测复现，配置了 60 秒工具预算却从未生效：

| 调用 | 结果 |
| web_search，1 个查询 | 1.1 秒返回 |
| web_search，4 个查询 | 从未返回 —— 8 分 29.7 秒，直到用户手动中断 |

第二个问题让它雪上加霜。一次多查询 web_search 调用会扇出成 N 个并行请求 （扇出逻辑在 dsh-tool-web 里），而 Brave 按秒限流。在免费套餐下，这会把整个预算都花在 429 上：

| 4 个并发查询，无间隔 | 结果 |
| 上游 0.1.1 | 4 个全部失败（WEB_PROVIDER_ERROR，HTTP 429），耗时 731 毫秒 |

这个版本改了什么

三个可配置开关，全部受同一个硬性截止时间约束，所以什么都不会卡住：

| 设置 | 默认值 | 作用 |
| searchTimeoutMs | 15000 | 服务商层面的硬性截止时间。把你的 AbortSignal 和 AbortSignal.timeout() 融合在一起。这就是修复卡死的那个改动。 它在入队之前创建，所以排队等待也计入预算。 |
| minRequestIntervalMs | 1500 | 通过每进程队列把并发扇出串行化，一次一个请求，中间留间隔。1100 实测 3/4 成功；1500 实测 4/4。 |
| maxRetries | 2 | 针对 HTTP 429 的有界重试，遵守 Retry-After（上限 3 s）。受 searchTimeoutMs 约束，所以重试不会重新引入卡死。 |

截止时间到期会报为明确的 WEB_PROVIDER_ERROR 超时；调用方取消仍然报为 WEB_ABORTED。服务商契约的其他部分没有变化。

修复之后，在同一个线上 API 上：

| | 修复前 | 修复后 |
| 服务器停滞，调用方无信号 | 永不返回 | 4.0 s 内拒绝 |
| 4 个并发查询 | 0/4 | 4/4，用时 5.5 s |
| 1 个查询 | 903 ms | 843 ms |

安装

dsh plugin --profile web add github:nedzen/dsh-web-search-brave

或者从本地检出安装：

dsh plugin --profile web add file:$HOME/Sites/dsh-web-search-brave

然后在你的配置档 cordis.patch.yml 里把接缝固定到它。补丁会替换整个配置，所以要重述 web 这一行拥有的每一个键 —— 漏掉 fetchProvider 会悄悄把它丢掉，弄坏 web_fetch：

- id: web
config:
searchProvider: brave-search
fetchProvider: http # do not omit

- id: web-search-brave
name: "@deepseek-ai/dsh-web-search-brave"
config:
apiKeyEnv: BRAVE_SEARCH_API_KEY
baseURL: https://api.search.brave.com/res/v1
maxResults: 10
searchType: web
searchTimeoutMs: 15000 # optional overrides
minRequestIntervalMs: 1500
maxRetries: 2

API key 先从凭据服务解析，再从启动环境解析（.env 文件会自动分层加载）。把它存为 BRAVE_SEARCH_API_KEY，或者把 apiKeyEnv 指向你导出的任意名字。

验证是否生效

test/freeze-regression.mjs 用一个接受 TCP 连接、然后永不响应的服务器复现卡死。用例 A（服务器停滞，调用方无信号）和 C（扇出间隔）在 0.1.1 上是 RED，在这里是 GREEN。

cd ~/.dsh/profiles/web
set -a; . ~/.dsh/.env; set +a
node ~/Sites/dsh-web-search-brave/test/freeze-regression.mjs \
./node_modules/@deepseek-ai/dsh-web-search-brave/lib/index.js "0.1.3"

用 Node 而不是 Bun 是刻意的：dsh 在 Node 的 fetch 下运行这个服务商，而所断言的 abort/timeout 语义是 undici 的。

在实时会话里自检 —— 计时能告诉你加载的是哪个构建：

| 4 查询 web_search | 构建 |
| 1 s 内返回，通常是 HTTP 429 | 旧的 0.1.1 |
| 耗时 4.5 s 或更多，通常成功 | 这个构建 |

调优

- 大量并行查询会超时。 searchTimeoutMs 也覆盖排队等待。如果模型一次触发多个 web_search 调用（比如 maxParallelToolCalls 大于 3，每个调用带 4 条查询），尾部耗时可能超过 15 s，于是快速失败而不是挂住。把 searchTimeoutMs 调到 30000。
- Brave 付费套餐。 设置 minRequestIntervalMs: 0 和 maxRetries: 0，用健壮性换速度。
- 仍然被限流。 调大 minRequestIntervalMs，或者改用多服务商回退链，而不是只挂一个后端。

故障排查

我改了源码，却没有任何变化。 pnpm 会把 file: 依赖复制进配置档，pnpm install 报告「Already up to date」，同时保留那份过期的副本。删掉它再重装：

rm -rf ~/.dsh/profiles/web/node_modules/@deepseek-ai/dsh-web-search-brave
dsh plugin --profile web install

我重装了，但运行中的会话没变。 只有配置会热重载。插件 JavaScript 走 ESM 缓存，而 dsh-hmr 不带任何监听根目录（root: []），所以要重启 dsh 才能加载新的服务商代码。

WEB_DUPLICATE_PROVIDER。 已经有别的服务商注册了 brave-search 这个 id —— 检查是不是有两行都声明了这个 bundle。

兼容性

面向 0.1.x DeepSeek Harness 系列：@deepseek-ai/dsh-*@^0.1.1-rc.2 对等依赖。超时、间隔、重试这些设置是增量添加的，所以 dsh 0.2.x 应该也能用 —— 请拿你自己的构建验证，别想当然。

同名，不同插件。 dsh-web-search-brave 也是另外一些独立开发的包的名字，例如 cnChenKai/dsh-web-search-brave（npm dsh-web-search-brave，0.2.4）。它们是不同的实现，配置互不兼容：那个注册的服务商 id 是 brave，配置项是 count/safesearch/textDecorations；这个注册的是 brave-search，配置项是 maxResults/searchType。选一个用，别把两个都接进同一个配置档，也别指望配置能互相移植。

相关

- deepseek-ai/deepseek-harness —— 这个 harness，也是本插件遵循的官方服务商模板
- 0xsline/awesome-deepseek-harness —— 生态索引
- GitHub 话题 dsh-plugin —— 更多 dsh 插件
- 其他 web_search 后端：multi-provider、Exa、SearXNG
- 独立开发、同名：cnChenKai/dsh-web-search-brave

许可证

MIT。实现 © 2026 nedzen。服务商接口与模块脚手架源自官方 @deepseek-ai/dsh-web-search-deepseek（MIT，© 2026 DeepSeek）。见 LICENSE。