cloveric/deepseek-harness-web-search-plugin

DeepSeek Harness 网页搜索增强插件

英文名称：DeepSeek Harness Web Search Plugin

CI
Release
License: MIT
DeepSeek Harness

把带来源链的 Brave + Tavily 实时网页搜索和 URL 正文抽取，作为 DeepSeek Harness 原生插件直接安装。

English · TaroCub · 安全说明 · Releases

这个插件向 Harness 的 web profile 安装一个原生 bundle，提供：

- web_search：Brave/Tavily 路由搜索；
- web_extract：Tavily 精确 URL 正文抽取；
- provider_status：不暴露密钥、不请求供应商的本地配置检查；
- health_check：显式执行 auth、quota、rate limit、timeout 实际探活；
- 可选的 /tarocub：与 TaroCub 网关联用时的配置和验收说明。

它可以独立用于 DeepSeek Harness，不要求安装 TaroCub。

为什么需要它

模型原生搜索仍然有价值，但严肃研究还需要稳定的工具协议和可审计来源链。本插件会返回 provider、domain、rank、访问时间、sourceLog、抽取哈希和明确的 fallback 提示，而不是把供应商路由隐藏起来。

| 工具 | 供应商路径 | 适合场景 |
|---|---|---|
| web_search quick | Brave 优先，Tavily 兜底 | 当前文档、URL、价格、新闻和广泛发现 |
| web_search deep | Tavily 优先，Brave 兜底 | 深度研究和正文导向回答 |
| web_search verify | Brave + Tavily 并行 | 需要交叉核验的重要结论 |
| web_extract | Tavily Extract | 读取用户已经给出的明确 URL |
| provider_status | 不发供应商请求 | 检查密钥是否可见 |
| health_check | 显式真实请求 | 排查鉴权、额度、限流或超时 |

单个供应商失败时，结果会包含 fallbacks 和 notice；抽取正文包含 contentHash。用户已经给出 URL 时，应先直接读取或抽取该 URL，搜索只用于发现链接或补充背景。

架构

DeepSeek Harness web profile
└── deepseek-harness-web-search-plugin
├── deepseek-harness-web-search  有边界的搜索指引
└── mcp-cctb-search         @deepseek-ai/dsh-mcp-client
└── node dist/search-mcp.js
├── Brave Search API
└── Tavily Search + Extract APIs

仓库已经提交自包含的 MCP bundle。通过 GitHub 安装时不需要现场构建，也不增加运行时 npm 依赖。

安装

前提：

- 已安装带 web profile 的 DeepSeek Harness dsh；
- Node.js 20 或更新版本；
- 至少一个 Brave 或 Tavily key，才能使用对应供应商工具。

dsh plugin --profile web add github:cloveric/deepseek-harness-web-search-plugin

安装后重启 Harness。安装成功不等于供应商密钥已配置，也不会创建飞书/Lark应用或启动 TaroCub。

配置供应商

在启动 Harness 的同一环境中设置一个或两个密钥：

export BRAVE_API_KEY="..."
export TAVILY_API_KEY="..."
dsh web

BRAVE_SEARCH_API_KEY 也可以作为 BRAVE_API_KEY 的别名。进程环境变量优先。为了兼容已有 TaroCub/Codex 环境，直接变量缺失时，MCP 只会尝试从 Codex MCP 环境段读取这几个同名变量。

插件绝不会把 key 写入 Harness profile、复制到 workspace，或通过 provider_status 返回。只有真正调用供应商工具，或显式调用 health_check 时，才会发起供应商请求。

验收

先确认 bundle 只贡献一个 Search MCP client：

dsh --profile web --dump-config | grep -A18 -B2 mcp-cctb-search

然后在 Harness 会话中调用 mcp__cctb_search__provider_status。这一步只检查配置可见性，不消耗供应商额度；只有需要真实排障时才调用 mcp__cctb_search__health_check。

应出现四个工具：

mcp__cctb_search__web_search
mcp__cctb_search__web_extract
mcp__cctb_search__provider_status
mcp__cctb_search__health_check

更新与卸载

dsh plugin --profile web update deepseek-harness-web-search-plugin
dsh plugin --profile web remove deepseek-harness-web-search-plugin

操作后重启 Harness，并重新执行 dsh --profile web --dump-config。

与 TaroCub 的关系

TaroCub 是另一个独立的、以飞书/Lark 为主平台的本地 agent 网关。它管理的 DeepSeek Host 会链接同一个 web profile。

- 安装当前插件后，TaroCub 会校验 capability marker、bundle 入口和 Harness patch 中的实际注册，再让插件接管 mcp-cctb-search。
- 迁移期间，TaroCub 仍会识别已安装的 tarocub-deepseek-harness-plugin。
- 没装插件、仍是旧 companion-only 插件、或入口/patch 损坏时，TaroCub 继续使用自己的私有 Search MCP 兜底。
- TaroCub 只在私有 Host 中设置 TAROCUB_SEARCH_MCP_OWNER=plugin 或 bridge，保证恰好只有一个 client 生效。
- 普通 Harness 不设置这个内部变量，因此插件默认启用。

正常使用 Harness 时不要手工设置 TAROCUB_SEARCH_MCP_OWNER。安装插件与部署 TaroCub 飞书服务是两件独立的事。

从旧包名迁移

项目已从 tarocub-deepseek-harness-plugin 更名，让用途明确表达为网页搜索增强。现有安装继续可被 TaroCub 识别，但不要在同一 profile 同时安装新旧两个包名。迁移一次后，后续升级统一使用新名称：

dsh plugin --profile web remove tarocub-deepseek-harness-plugin
dsh plugin --profile web add github:cloveric/deepseek-harness-web-search-plugin
dsh --profile web --dump-config | grep -c "id: mcp-cctb-search"

迁移后重启 Harness，最后计数必须是 1。

唯一维护源仍可从 TaroCub 的插件子目录安装：

dsh plugin --profile web add "github:cloveric/tarocub#path:deepseek-harness-plugin"

故障排查

| 现象 | 检查方法 |
|---|---|
| 看不到工具 | 重启 Harness，查看 --dump-config，确认插件安装在 web profile。 |
| provider_status 显示未配置 | key 必须存在于真正启动 dsh 的环境，而不是另一个无关 shell。 |
| 搜索返回鉴权、额度或限流错误 | 显式调用 health_check，查看脱敏后的状态。 |
| 出现两个 mcp-cctb-search | 删除手工添加的重复 patch；正常插件或 TaroCub Host 只会保留一个 owner。 |
| TaroCub 报入口或 patch 损坏 | 更新或重装插件；修复前 TaroCub 会安全使用 bridge fallback。 |
| 发生供应商 fallback | 用户答案中应保留返回的 notice。 |

边界与安全

这是 Search MCP 和 DeepSeek Harness 插件，不代理模型流量、不管理飞书/Lark 租户、不持久化供应商密钥，也不替代 Harness 原生插件或搜索。正文抽取只接受 HTTP(S) URL；MCP 返回的所有文本都会检查已配置密钥及常见鉴权格式并脱敏。密钥边界和漏洞报告方式见 SECURITY.md。

开发

npm ci
npm run verify

唯一维护源位于 TaroCub 的 deepseek-harness-plugin/，再通过 git subtree 发布到本仓库。详见 CONTRIBUTING.md。

许可证

MIT，见 LICENSE。