前言¶

在 DeepSeek Harness（DSH）里，模型通过官方 web 能力缝（ctx.web）调用 web_search 工具做联网检索。默认 bundled 的 DeepSeek 检索提供方，一次搜索往往要消耗一整轮模型调用，延迟和成本都偏高。若你已有 Brave Search API 订阅，或希望「一次搜索 = 一次 HTTP GET、不占用模型轮次」，可以把检索后端换成社区插件 huohua-dev/dsh-web-search-brave。下面介绍它的定位、安装方式与配置要点。

这是什么¶

dsh-web-search-brave（npm 包名 @huohua-dev/dsh-web-search-brave，当前版本 0.1.0）由 huohua-dev 维护，分类为 联网工具。它挂载在 DSH 官方 web 能力缝上，调用 Brave 官方端点 https://api.search.brave.com/res/v1/web/search，将响应中的 web.results[] 映射为缝约定的 WebSearchResult；对上层模型而言，工具名仍是稳定的 web_search，只是底层提供方变为 Brave。

与 README 中的表述一致：One search is one HTTP request — no model turn，相对 bundled DeepSeek 提供方更轻、更快。

• 目录页：https://www.skillhub.cn/plugins/huohua-dev/dsh-web-search-brave
• 源码与文档：https://github.com/huohua-dev/dsh-web-search-brave
• 许可证：MIT

环境与依赖¶

安装前请确认：

1. dsh 版本 0.1.1-rc.2 或更高；
2. Node.js >= 20.3.0；
3. 有效的 Brave Search API 订阅 Token（可在 api-dashboard.search.brave.com 申请，资料说明存在免费档）。

核心功能¶

以下能力均来自项目 README，仅作归纳说明。

纯检索、无模型轮次¶

每次 web_search 对应一次 HTTP GET，不向模型再开一轮对话来完成检索。

安全与请求约束¶

• 订阅 Token 仅通过请求头 X-Subscription-Token 发往 Brave，不出现在 URL 中，也不写入日志；
• baseURL 默认锁定官方端点；若改用自定义地址，须显式设置 allowCustomBaseURL: true 且使用 https，避免配置被注入后把密钥导向其它主机；
• 每次请求有硬超时 searchTimeoutMs（默认 30 秒），并尊重调用方的 abort signal。

结果与参数¶

• 调用方的 maxResults 在请求层生效，count 不超过配置值与 API 上限（20）；
• URL 去重；page_age 仅在能解析为日期时映射为 publishedAt。

代理与热更新¶

• 可选 proxy，默认读取启动环境中的 HTTPS_PROXY / HTTP_PROXY；在 api.search.brave.com 遭遇 DNS 污染等场景，可在代理侧解析主机名。实现上通过懒加载 undici（optional dependency），未配置代理则不加载该依赖。
• 已挂载后，配置段在搜索之间会重新读取，改 profile patch 无需重启 DSH；enabled: false 可暂停提供方而不卸载插件。

一键切换提供方¶

随包提供的 cordis.patch.yml 会挂载插件，并把 web.searchProvider 从 bundle 默认的 deepseek-official 切到 brave。

安装与启用¶

从 GitHub 安装（命令来自 README 原文）：

dsh plugin --profile web add github:huohua-dev/dsh-web-search-brave

安装完成后，bundle 的 patch 会自动挂载插件并选择 searchProvider: brave。若要改回官方 DeepSeek 提供方，可移除该插件，或在 profile 的 patch（$DSH_HOME/profiles/<profile>/cordis.patch.yml）中覆盖：

- id: web
  config:
    searchProvider: deepseek-official

注意： README 写明，新安装的插件需要重启 dsh 才会生效；运行中的 host 不会热挂载新插件。对已挂载插件的配置修改则支持热重载。

验证是否挂载成功：

dsh --profile web --dump-config   # 应能看到 web-search-brave 条目

API Key 配置¶

Token 在每次搜索时按「先命中者优先」解析：

1. DSH 凭据服务（推荐）：在 $DSH_HOME/.credentials.yaml 中追加 BRAVE_API_KEY: <your-token>；
2. 环境变量：启动 dsh 前 export BRAVE_API_KEY=<your-token>（可通过配置项 apiKeyEnv 改名）；
3. 插件配置中的字面量 apiKey（secret 角色，settings describe 输出中会脱敏）。

缺少密钥时，搜索失败并报 WEB_PROVIDER_CREDENTIAL_MISSING，错误信息会复述上述几种方式。

典型配置¶

所有字段可选，在 profile 的 cordis.patch.yml 里编辑 web-search-brave 条目，例如：

- id: web-search-brave
  config:
    apiKeyEnv: BRAVE_API_KEY
    count: 10
    country: cn
    searchLang: zh-hans

常用字段（默认值与说明以 README 表格为准）：

典型用法¶

1. 按上文完成安装、配置 BRAVE_API_KEY 并重启 dsh（若为新装插件）。
2. 执行 dsh --profile web --dump-config 确认 web-search-brave 已挂载且 searchProvider 为 brave。
3. 在对话中让模型使用 web_search 工具；对模型侧接口与 bundled 提供方一致，无需改 prompt 里的工具名。

开发侧自测（维护者文档）：

npm install
npm test    # vitest，README 称 43 个用例

包内为手写 ESM 源码，无额外 build 步骤。

适用场景与注意¶

适合谁

• 已在用或计划用 Brave Search API，希望 DSH 联网检索不占用模型轮次；
• 需要按 country / searchLang 等参数做区域化检索；
• 网络环境需经 HTTP 代理 访问 api.search.brave.com 的用户。

使用前请知悉

• DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。
• 插件在 当前 dsh 进程权限 下运行，出站目标仅为 Brave API（或你显式允许的 https 镜像）。安装前建议阅读源码与 MIT 许可证；README 说明无遥测、无 install hooks、随包 patch 中无 !!js 表达式。
• 项目 README 致谢了官方 DeepSeek 检索插件及社区同类实现；结构与错误语义对齐 @deepseek-ai/dsh-web-search-deepseek。

结尾¶

huohua-dev/dsh-web-search-brave 把 DSH 的 web_search 接到 Brave Search API：一次搜索一次 HTTP，Token 与端点策略偏保守，并支持代理与配置热更新。若你的 profile 已是 web，按 README 安装命令添加插件、配置 BRAVE_API_KEY 并重启即可切换提供方。

• 目录：https://www.skillhub.cn/plugins/huohua-dev/dsh-web-search-brave
• GitHub：https://github.com/huohua-dev/dsh-web-search-brave