dsh-web-search-free
中文 | English — DSH 插件（dsh-plugin）· 免费网页搜索 provider + 设置开关 + MCP server（兼容 Claude Code / Codex）
把「DeepSeek 官方按量计费搜索」一键切换成 OpenCode 同款免费搜索（匿名免 key），
并且同一个免费搜索后端直接作为 MCP 服务器供 Claude Code、Codex 等任何 MCP
客户端使用。
- 🆓 免费后端：Parallel（默认） / Exa（备用）——都是 OpenCode 内置
websearch 工具的同款免费 MCP 端点，匿名可用、无需 API key、不扣任何余额。
- 🔄 DSH 设置开关：官方 ↔ 免费一键切换，自动维护 profile 补丁。
- 🔌 MCP server：零依赖，双传输（stdio + HTTP/SSE 双端口），
claude mcp add / codex mcp add 即装即用。
快速开始
已发布到 npm：@sheep233_/dsh-web-search-free
MCP server（无需 clone，一条命令接入）：
claude mcp add dsh-web-search -- npx -y @sheep233_/dsh-web-search-free
codex mcp add dsh-web-search -- npx -y @sheep233_/dsh-web-search-free
DSH 插件（官方安装方式，默认推荐）：用 dsh plugin CLI（官方入口，转发
pnpm 到 profile 目录）安装，再把包声明进 bundles：
# 安装依赖（等价于在 ~/.dsh/profiles/web/ 下执行 pnpm add）
dsh plugin --profile web add @sheep233_/dsh-web-search-free
再把包名加入 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles
（有序 patch 层栈，顺序 = 应用顺序），重启 DSH 生效：
{
"dsh": { "profile": { "bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
// ...其他 bundle...
"@sheep233_/dsh-web-search-free"
]}},
"dependencies": {
"@sheep233_/dsh-web-search-free": "^0.3.0"
}
}
用 dsh plugin --profile web install 可补装缺失依赖；
dsh --profile web --dump-config 可验证自己的层/行是否已进合成树。
其余安装方式（本机热装配 / 本地 link / tgz）见下文「安装」。
背景：为什么默认走 DeepSeek 官方 key
DSH 的 web_search 工具走 ctx.web 能力缝（seam）。默认装配的 provider 是
@deepseek-ai/dsh-web-search-deepseek（id = deepseek-official，由 dsh-base
依赖自动带入）：每次搜索调用 DeepSeek 官方 Anthropic 兼容 API
（https://api.deepseek.com/anthropic/v1/messages）的原生 web_search_20250305
服务端工具，复用 DEEPSEEK_API_KEY，按 token 计费。
功能
免费后端（DSH 内）
注册两个免费搜索 provider 到 ctx.web，模型侧 web_search 工具调用方式不变：
| provider id | 后端 | 端点 | 说明 |
|---|
parallel-free（默认） | Parallel Web Search | https://search.parallel.ai/mcp | 匿名免 key |
exa-free（备用） | Exa | https://mcp.exa.ai/mcp | 匿名免 key；设 EXA_API_KEY 可提升限额 |
设置开关（DSH 设置 → 插件设置 → 可配置 → 免费网页搜索）
- enabled 开关（默认关 = 官方搜索）：开启 → 免费；关闭 → 官方。
- 免费后端选择：Parallel（默认）/ Exa（备用），单选。
- 变更自动维护 profile 用户层补丁
~/.dsh/profiles/web/cordis.patch.yml 的
web 行 config.searchProvider（开 → 写入所选 provider id；关 → 删除覆盖块）。
不能写 ~/.dsh/.env：dsh-app-boot 拒绝 .env 里的任何 DSH_* 变量。
- 变更后重启 DSH 生效（
WebRuntime 启动时读取 web 行配置）。
MCP server（Claude Code / Codex / 任意 MCP 客户端）
独立的零依赖 MCP server（lib/mcp-server.js，不依赖 DSH），暴露 web_search
工具（参数：query 必填、provider 可选 parallel/exa、numResults 可选）。
支持双传输：stdio（默认）与 HTTP/SSE（监听端口，兼容 Streamable
HTTP POST / 与老式 GET /sse + POST /messages）。
传输一：stdio（默认，无需端口）
# 本地路径方式（clone 后）
claude mcp add dsh-web-search -- node /绝对路径/dsh-web-search-free/lib/mcp-server.js
codex mcp add dsh-web-search -- node /绝对路径/dsh-web-search-free/lib/mcp-server.js
# 或 npm 全局安装后（npx）
claude mcp add dsh-web-search -- npx -y @sheep233_/dsh-web-search-free
codex mcp add dsh-web-search -- npx -y @sheep233_/dsh-web-search-free
传输二：HTTP/SSE（监听端口，双端口模式）
# 启动 MCP server（默认 http://127.0.0.1:3100；可用 --host/--port 调整）
node /绝对路径/dsh-web-search-free/lib/mcp-server.js --http --port 3100
-
Claude Code（Streamable HTTP）：
claude mcp add --transport http dsh-web-search http://127.0.0.1:3100
-
Codex（OpenAI Codex CLI）：
codex mcp add --transport http dsh-web-search http://127.0.0.1:3100
-
老式 SSE 客户端（URL 指向 SSE 通道）：
# 客户端配置 http://127.0.0.1:3100/sse（GET /sse 建立通道，POST /messages 发请求）
-
验证：浏览器打开 http://127.0.0.1:3100/ 返回
{"name":"dsh-web-search-free","version":"0.3.0","transport":"http/sse","port":3100}。
其他 MCP 客户端
任何支持 stdio 或 HTTP/SSE 传输的 MCP 客户端都能接入（命令/URL 同上）。
可选环境变量：EXA_API_KEY（提升 Exa 匿名限额）。
安装（DSH 插件本体）
⚠️ 为什么别人装上设置里看不到卡片？ 设置卡片要显示需要同时满足：
- 包被声明进
dsh.profile.bundles（只把包放进 node_modules 是不够的）；
- 安装后重启 DSH（host 装配与 client 图都在启动时解析）；
- 打开设置前刷新浏览器页面；
- profile 是
web（tui/headless 无浏览器 UI）；
- 安装方式任选：本地路径 /
link: / tgz / npm i -g @sheep233_/dsh-web-search-free
（npx @sheep233_/dsh-web-search-free 也可用于 MCP server）。
装好后可用 dev_plugin_status 确认 client ✓，或直接看设置 → 插件设置 → 可配置。
界面效果（设置 → 插件设置 → 可配置 → 免费网页搜索）：
免费网页搜索设置卡片
方式一：dsh 官方安装（默认推荐）
dsh plugin --profile web add @sheep233_/dsh-web-search-free
再把 "@sheep233_/dsh-web-search-free" 加入 ~/.dsh/profiles/web/package.json
的 dsh.profile.bundles（格式见「快速开始」），重启 DSH 生效。
验证：dsh --profile web --dump-config 输出中应能看到插件行。
npm i -g @sheep233_/dsh-web-search-free # 可选：全局安装（配合 link: 或 MCP npx 使用）
方式二：本机热装配（dsh-super-injector，免重启）
dev_install_package # dir = 插件包目录（含 package.json 与 lib/）
方式三：本地路径 link（本地开发）
在 ~/.dsh/profiles/web/package.json 中声明：
{
"dsh": { "profile": { "bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
// ...其他 bundle...
"@sheep233_/dsh-web-search-free"
]}},
"dependencies": {
"@sheep233_/dsh-web-search-free": "link:/绝对路径/dsh-web-search-free"
}
}
方式四：tgz（离线环境）
npm run build && npm pack
# 把产物 tgz 加入 profile 依赖后重装（pnpm install），重启生效
验证
npm run verify # 补丁联动 + Parallel/Exa 真实搜索 + 选择矩阵 + MCP 冒烟
回退官方
设置里关闭 enabled 开关（覆盖块随即删除），重启 DSH。
（或手动删除 ~/.dsh/profiles/web/cordis.patch.yml 里
# >>> web-search-free 与 # <<< web-search-free 之间的块。）
权限说明（安全透明）
- DSH 插件：启用免费后，
web_search 请求仅发往 search.parallel.ai /
mcp.exa.ai；会修改 ~/.dsh/profiles/web/cordis.patch.yml（带边界标记的
web 行覆盖，格式见上），不触碰其他配置。无 key、无数据收集、无监听。
- MCP server：只调用上述免费端点，不读你的任何文件/环境（除可选
EXA_API_KEY）。stdio 模式不监听任何端口；HTTP/SSE 模式仅在你指定的
--host:--port（默认 127.0.0.1:3100）上提供 MCP 端点，默认只绑本机回环地址。
开发
bash scripts/build.sh # tsc 编译 host + core + mcp-server，复制 client 到 lib/
npm run verify # 端到端验证
结构：
src/core.ts # 零依赖搜索核心：Parallel + Exa（host 与 MCP 共用）
src/index.ts # host：双 provider 注册 + settings 开关 + profile 补丁联动
src/mcp-server.ts # MCP server：stdio + HTTP/SSE 双传输（bin：dsh-web-search-mcp）
src/client/client.js # client：设置面板「免费网页搜索」开关卡片（含后端选择）
scripts/build.sh # 构建（自动探测 DSH_CHECKOUT）
scripts/verify.mjs # 端到端验证脚本
cordis.patch.yml # bundle 装配层（含 web 行 searchProvider 解除固定）
License
MIT © sheep-programmer
