前言¶

DeepSeek Harness（dsh）里，模型可以通过内置的 web_search 工具查网页，而不必把「上网」塞进模型上下文里额外烧 token。前提是 profile 里要有一个在 ctx.web 上注册好的 search provider。

dsh 0.2.1 前后插件接口有过变动：不少社区里的 Brave provider 会从 @deepseek-ai/dsh-settings 等宿主包 import 运行时符号，宿主移除导出后模块加载失败，表现就是插件「装了但搜索没用」。下面介绍维护者 thomasly 的 dsh-web-search-brave：单文件、零依赖，走官方 ctx.web 接缝，provider id 为 brave-search，复用你在凭据库里已有的 Brave API key。

这是什么¶

dsh-web-search-brave（GitHub：thomasly/dsh-web-search-brave）把 Brave Search API 接进 dsh 的网页搜索能力。它注册在 dsh 官方 ctx.web 搜索接缝上，因此所有模型都能通过 dsh 自带的 web_search 搜索，不绑定某一模型，也不靠模型自己「上网」。

• 直连 Brave 官方接口，不经过 LLM，不产生模型侧搜索费用。
• 复用 ~/.dsh/.credentials.yaml 里配置好的 Brave key，不在对话或日志里明文暴露。
• 单文件、零依赖、零 import 宿主包，降低因宿主接口变动或本地 link: 安装路径导致的加载失败。
• 结果带发布日期（publishedAt，来自 Brave 的 page_age），对时效性查询更有用。

适用版本：dsh 0.2.x（README 写明在 0.2.1-rc.2 上实测通过）。运行环境：Node.js ≥ 22.19（见 package.json 的 engines）。插件版本 1.0.0，许可证 MIT。

核心功能¶

与 dsh 的衔接方式¶

插件在 ctx.web 上注册 id 为 brave-search 的 search provider。profile 里把 web.searchProvider 设为 brave-search 后，模型调用 web_search 时会走 Brave 的 Web Search 端点（默认 https://api.search.brave.com/res/v1/web/search）。

实现上不写任何 import：只用运行时自带的 fetch、URL，以及 ctx.web、ctx.credentials、ctx.launchEnvironment。配置与 key 在每次搜索时重新读取，改凭据库或环境变量后不必重启 dsh 即可生效（bundle 仍须在安装后重启 web 进程才会挂载）。

返回给模型的字段¶

web_search 需要 { url, title?, snippet?, publishedAt? }。插件从 Brave 响应映射如下（摘要）：

可选配置项¶

bundle 在 cordis.patch.yml 中插入 web-search-brave-local 行；其下 config 全部可选，常见字段包括：

freshness 是整个 provider 级设置，不是每个 query 单独设置；dsh 的 web_search 入参只有 queries，若希望默认只看最近一周，可在 profile 里配 freshness: pw。

API Key 解析顺序¶

按顺序找到即用：

1. 行配置里的字面量 apiKey（不推荐，会进配置文件）；
2. 凭据库 refs.<apiKeyEnv>（默认 refs.BRAVE_API_KEY）；
3. dsh 启动环境快照中的 BRAVE_API_KEY（含 ~/.env）；
4. 当前进程环境变量 BRAVE_API_KEY。

手工写入凭据库示例：

refs:
  BRAVE_API_KEY: your-key-here

错误与限速¶

错误对象沿用接缝的 WebError 形状（如 WEB_PROVIDER_CREDENTIAL_MISSING、WEB_PROVIDER_RATE_LIMITED、WEB_PROVIDER_TIMEOUT 等）。收到 429 且 Retry-After 不超过 5 秒时会自动等一次再重试；插件默认串行节流，web_search 一次最多 4 个 query 会串行发送。

安装与启用¶

从 GitHub 安装（推荐）¶

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

装完后重启一次 dsh web（bundle 类插件需要重启才会挂载）。也可在 Web 界面 插件 → 安装 中填写同一 GitHub 地址。

选中 provider¶

在 ~/.dsh/profiles/web/cordis.patch.yml 中增加或合并：

- id: web
  config:
    searchProvider: brave-search
    fetchProvider: http

fetchProvider: http 表示 web_fetch 继续走 dsh 内置本地 HTTP 抓取，不额外为抓取选付费 provider。

确认是否生效¶

重启后问一句带时效的问题（例如 README 中的 latest AI model release），观察结果：

• 日期形如 (2026-11-01T10:55:46)（无 Z、无毫秒）通常表示 Brave 的 page_age 透传；
• 若报 configured web provider "brave-search" is not registered，先确认已重启，再执行：

dsh --profile web --dump-config | grep web-search-brave

应能看到 - id: web-search-brave-local。

本地目录开发安装时，README 说明可用 plugin_manager install_bundle 指向目录绝对路径，pnpm 以 link: 挂载；该目录之后不能删、不能移，否则搜索会失效。本文不展开 clone 流程，生产环境以 GitHub 安装为准。

典型用法¶

安装并完成 searchProvider: brave-search 后，在 dsh web 对话中正常提问即可触发 web_search；无需为每个模型单独配置搜索能力。

需要调参时，在 cordis.patch.yml 的 web-search-brave-local 插入块下追加 config，例如：

- insert:
    - id: web-search-brave-local
      name: dsh-web-search-brave
      config:
        providerId: brave-search
        apiKeyEnv: BRAVE_API_KEY
        count: 10
        safesearch: moderate

保存后下一次搜索会读取新配置（key 仍建议只放在凭据库或环境变量）。

适用场景与注意¶

适合谁：已在 Brave Search API 有订阅、希望在 dsh 0.2.x 里用统一 web_search、且希望与旧版「import 宿主包」Brave 插件脱钩的开发者。

分类：社区目录将其归为联网工具（目录页：skillhub.cn/plugins/thomasly/dsh-web-search-brave）。SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，安装来源以你信任的仓库与许可证为准。

安全与权限：插件以当前 dsh 进程权限运行，会向 Brave 官方 API 发起 HTTPS 请求；安装前请阅读 仓库源码 与 MIT 许可证，自行评估 key 存放方式（优先凭据库，避免字面量 apiKey 写进 patch）。

配额：Brave 的速率与月额度由账户决定；插件默认保守节流，不改变 Brave 侧额度。多 query 串行可能多等数秒。

故障提示：providerId 与 searchProvider 不一致、或多个 search provider 冲突时，可能出现 500 或注册失败；只保留一个 searchProvider 并保持 id 对齐。

结尾¶

dsh-web-search-brave 用零 import 的方式把 Brave Search 挂到官方 ctx.web 上，让各模型共用 web_search，并复用已有 BRAVE_API_KEY 凭据。经过上面的安装、启用与重启步骤，即可在 profile 里稳定选中 brave-search。

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