前言¶

在 DeepSeek Harness（DSH）里做需要实时信息的智能体时，常见做法是写 skill、再让模型自己 curl 调搜索 API。路径长、返回格式也不统一，模型阅读和筛选成本都偏高。社区插件 dsh-brave-search（npm 包名 dsh-plugin-brave-search）把 Brave Search API 封成一组专用工具，并可选地接管 Harness 内置的 web_search，让联网检索变成可调用、可配置的正式能力。

这是什么¶

dsh-brave-search 由维护者 Llldmiao 发布，归类为联网工具。它基于官方 Brave Search API skills v1.5.0，为 DSH 提供网页、新闻、图片、视频的检索结果，以及面向 LLM 的页面上下文、带引用的 AI 回答、本地地点、搜索建议与拼写检查等能力。插件还会在 Harness 的 web 接缝上注册 id 为 brave 的搜索提供方，便于把默认 web_search 切到 Brave。

当前 npm 版本为 1.0.2，许可证 MIT。社区目录页：https://www.skillhub.cn/plugins/Llldmiao/dsh-brave-search；源码与说明：https://github.com/Llldmiao/dsh-brave-search。

核心功能¶

专用工具¶

各工具对应 Brave 的 REST 端点，返回结构中包含 endpoint、query、count、text 等字段；模型主要读 text，其余字段便于程序化调用（PTC 模式）。

插件按官方 API 限制各路由能力（例如 offset 仅用于 web/news/videos，goggles 不发给 images/videos 等），避免无效参数导致 422。

内置 web_search 提供方¶

除上述工具外，插件通过 ctx.web 注册 brave 提供方（默认 id 为 brave，可用 config.id 覆盖），使内置 web_search 走 Brave 的 /res/v1/web/search。启用后，web_search 通常只返回来源列表而无回答正文；brave_search 则返回渲染好的结果块。web_fetch 仍走本地 HTTP 提供方，行为不变。

环境与依赖¶

1. DeepSeek Harness Desktop：README 写明在 0.2.1-rc.3 上验证过。
2. Brave Search API 订阅：在 https://api.search.brave.com 创建密钥。不同端点对应不同套餐：web/news/images/videos/llm-context/pois/descriptions 需 Search 计划；place_search 需带 locations 的 Search；suggest 需 Suggest；spellcheck 需 Spellcheck；answers 需 Answers。套餐未覆盖时工具会返回 HTTP 401/403 及说明信息。

安装与启用¶

插件以当前 DSH 进程权限运行，安装前建议通读仓库源码与 MIT 许可证。密钥不应写入仓库，应放在 Harness 启动时加载的环境层。

第一步：配置 API Key¶

Harness 启动时读取 $DSH_HOME/.env（默认 ~/.dsh/.env）并注入 process.env。在 shell 中写入密钥后需重启 Harness：

printf 'BRAVE_SEARCH_API_KEY=%s\n' 'your-key' >> ~/.dsh/.env

在启动 shell 中 export 同名变量也可生效，且优先级更高。密钥不会从插件包或 patch 中读取。

第二步：安装插件¶

方式 B — 从 npm 安装（适合大多数机器）¶

使用 Harness 自带 CLI 添加包名 dsh-plugin-brave-search：

"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
  plugin --profile desktop add dsh-plugin-brave-search

随后在侧边栏 Plugins 页面打开 brave-search 行的开关。仅执行 CLI 只会下载包，必须在 Plugins 页启用才算打开。

Linux 等非 macOS 环境请把上述路径换成本机 DSH CLI 的实际路径（与桌面版捆绑的 dsh 一致即可）。

方式 A — 本地 link 安装（开发）¶

README 建议在本地 clone 仓库后，用 link:$HOME/... 形式 plugin add，以便改 index.js 后重启即可生效；也可在 Plugins 页通过「添加插件」指向目录。开发路径上的命令以 GitHub README 为准。

验证¶

重启后执行搜索应来自 Brave。若 Plugins 页显示异常，在详情「原因」中查看具体报错。

可选配置¶

在 patch 中 brave-search 条目支持下列字段（括号内为默认）：

- id: brave-search
  config:
    apiKeyEnv: BRAVE_SEARCH_API_KEY
    baseUrl: https://api.search.brave.com
    timeoutMs: 30000
    count: 10

Brave 各端点自身默认条数多为 20（图片 50 等）；插件默认 count: 10 便于阅读，各工具仍可通过参数 count 加大。baseUrl 可带路径前缀（如经网关转发），拼接路由时会保留前缀。研究型 answers 允许更长超时（README 提到最高约 330000 ms）。

将 Brave 设为默认 web_search¶

web 接缝每次只选一个提供方：若 patch 中 searchProvider 固定了已注册且可用的 id，则使用该提供方；否则在唯一可用提供方时自动选择，多个可用且未固定时会报 WEB_PROVIDER_AMBIGUOUS。

在 profile patch 中固定 Brave，并关闭要替换的提供方，例如：

- id: web
  config:
    searchProvider: brave
- id: web-search-deepseek
  config:
    enabled: false

注意：Brave 提供方通过 ctx.inject(['web'], ...) 懒挂载，不要在 bundle 顶层 inject 列表里写 web，否则在无 web 接缝的部署上可能导致整个 bundle 异常。

若希望 DeepSeek 官方与 Brave 并存，可保持两行均启用，通过 searchProvider 或环境变量 DSH_WEB_SEARCH_PROVIDER 在 brave 与 deepseek-official 之间切换。

提供方的 available() 仅检查 token 环境变量是否设置，不会发起网络探测。

安全与工具说明¶

工具描述中会提示：Brave 结果为外部不可信数据，不得当作指令执行（与内置 web_search 一致）。订阅 token 仅通过 X-Subscription-Token 发往配置的 baseUrl，不会出现在工具输出中；本插件目录不存储凭证。

适用场景与注意¶

• 适合：需要在 DSH 智能体中稳定调用 Brave 多类搜索、页面 grounding、带引用回答或本地 POI，并希望可选地把系统 web_search 统一到 Brave 的开发者。
• 注意：按 Brave 套餐规划端点，避免 401/403；研究型 brave_answers 耗时长、超时预算更大；多搜索提供方并存时必须用 searchProvider 固定其一。
• 生态：DSH 奉行「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系，本文介绍的是社区维护的联网工具插件。

结尾¶

dsh-brave-search 把 Brave Search API 收成 Harness 原生工具与可选 web_search 后端，减少手写 HTTP 与解析负担。安装时配置 BRAVE_SEARCH_API_KEY、通过 npm 或 link 添加插件并在 Plugins 页启用即可上手。

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