前言¶
DeepSeek Harness（DSH）的理念是「一切皆插件」：模型侧的 web_search 工具、结果上限、引用展示由它自己的 web capability 负责，但具体去哪家搜索服务拿结果，取决于挂载的 searchProvider。如果你选定的搜索服务是博查（Bocha），按惯例就得自己实现一个 WebSearchProvider、注册进 Profile，再处理凭据解析和错误映射。
@bocha-ai/dsh-web-search-bocha 把这件事做成了可安装的 bundle：一条命令装进 Profile，ctx.web 的搜索就路由到博查的 Web Search API。下面介绍它的定位、安装步骤和配置方式。
这是什么¶
一句话定位：为 DeepSeek Harness 提供博查（Bocha）Web Search 驱动的 WebSearchProvider，附带一个可安装的 Profile bundle。
- 维护方：bocha-ai
- 包名：
@bocha-ai/dsh-web-search-bocha，当前版本 0.1.0 - 许可证：MIT
- 仓库：https://github.com/bocha-ai/dsh-web-search-bocha
它只负责搜索这一段。模型侧的 web_search 工具契约、结果边界、引用与错误展示仍由 Harness 掌握，插件不接管这些。
核心功能¶
1、注册 provider id 为 bocha 的 WebSearchProvider，调用博查的 POST /v1/web-search 接口。
2、携带 dsh.bundle 补丁（cordis.patch.yml），安装后将 web 行的 searchProvider 设为 bocha，并插入 web-search-bocha 行来加载本包。
3、每次搜索时通过 Harness credentials 服务解析 BOCHA_API_KEY，密钥轮换无需重启，即对下一次请求生效。
4、结果映射：将博查返回的 url/name/summary/datePublished 映射为 Harness 的 url/title/snippet/publishedAt；没有有效 URL 的条目被丢弃。
5、请求的 maxResults 覆盖默认 count，并在发送前截断至博查上限 50。
6、错误处理有明确映射：
- HTTP 错误、网络失败、非 200 响应、响应体不可解析 →
WEB_PROVIDER_ERROR（存在log_id时保留） - 中止 →
WEB_ABORTED - 凭据缺失 →
WEB_PROVIDER_CREDENTIAL_MISSING - 重定向在访问目标前被拒绝
安装与启用¶
先把 bundle 装进 web Profile：
dsh plugin --profile web add @bocha-ai/dsh-web-search-bocha
装完可以打印合成后的配置，确认补丁已生效（打印后退出，不启动服务）：
dsh --profile web --dump-config
然后启动 Web 应用：
dsh --profile web
插件需要博查（open.bocha.cn）的 API key 才能实际搜索，凭据配置两种方式二选一。
方式一：写入 DSH 凭据文档 $DSH_HOME/.credentials.yaml（通常是 ~/.dsh/.credentials.yaml）：
BOCHA_API_KEY: your-api-key
POSIX 下把文件权限收紧为仅属主可读写：
chmod 600 ~/.dsh/.credentials.yaml
方式二：启动前导出环境变量：
export BOCHA_API_KEY='your-api-key'
两者同时配置时，环境变量优先。卸载也是一条命令，会移除对应的 provider 行和 bundle 层：
dsh plugin --profile web remove @bocha-ai/dsh-web-search-bocha
配置项¶
插入的 web-search-bocha 行支持以下配置：
| 配置项 | 默认值 | 说明 |
|---|---|---|
apiKey |
— | 可选的明文 API key，更推荐走凭据方式，避免明文 key 进入 Profile 补丁 |
apiKeyEnv |
BOCHA_API_KEY |
经 Harness credentials 服务解析的凭据引用，每次搜索时解析 |
baseURL |
https://api.bocha.cn |
API 基地址 |
freshness |
noLimit |
搜索附带的时间过滤条件 |
summary |
true |
是否请求博查的每页摘要 |
count |
10 |
请求未带 maxResults 时的默认条数，取值 1–50 |
这些配置不需要改动包本身，通过后续 Profile patch 直接配置该行即可：
- id: web-search-bocha
config:
freshness: 2025-01-01..2025-04-06
summary: true
count: 10
经过上面的步骤，重新启动后 ctx.web 的搜索请求就会带着这些参数走博查。
适用场景与注意¶
适合的读者：已经在跑 DSH Web 应用、想让 web_search 走博查的部署者；需要按部署固定时间过滤（freshness）的团队；不想在主工程里手写 WebSearchProvider 的开发者。
使用前注意以下几点：
- 需要先在博查（open.bocha.cn）申请 API key，否则插件装上也搜不了。
- Node 引擎要求
^22.19.0 || >=24.0.0。 - 当前上游 DSH 内置 Plugins UI 不暴露第三方搜索设置，需通过 Profile 行配置，并把
BOCHA_API_KEY存于凭据文件或启动环境。 freshness是部署级配置，不是模型可传参数：Harness 的中立请求只携带query和maxResults，同一 provider 挂载下的每次请求使用同一个freshness值。- 单次 API 调用最多返回 50 条来源；该端点不返回生成式答案，所以
WebSearchResult.content省略；博查特有的siteName及图片、视频等媒体字段也被省略。 - 安全提示：插件以当前 dsh 进程的权限运行，安装前建议阅读源码并确认许可证（本项目为 MIT）符合你的部署要求。
想参与开发的话，仓库内可运行无 key 的测试与构建：
npm install
npm test
npm run build
npm pack --dry-run
有博查 key 时，可运行端到端冒烟测试：
BOCHA_API_KEY='your-api-key' npm run test:e2e
小结¶
这个插件解决的是一个很具体的问题：让 DSH 的 ctx.web 用上博查搜索，而且安装、配置、卸载都收敛在 Profile 和 bundle 机制里，凭据轮换不用重启。如果你的搜索服务选型恰好是博查，它是最直接的接法。
- 社区目录页：https://www.skillhub.cn/plugins/bocha-ai/dsh-web-search-bocha （目录为社区独立维护，与 DeepSeek / 幻方无官方从属关系）
- GitHub 仓库：https://github.com/bocha-ai/dsh-web-search-bocha
