@sheep233_/dsh-web-search-free

Readme

# dsh-web-search-free

[![npm version](https://img.shields.io/npm/v/@sheep233_/dsh-web-search-free.svg)](https://www.npmjs.com/package/@sheep233_/dsh-web-search-free)
[![npm downloads](https://img.shields.io/npm/dm/@sheep233_/dsh-web-search-free.svg)](https://www.npmjs.com/package/@sheep233_/dsh-web-search-free)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

> **中文** | [**English**](README.en.md) — DSH 插件（[`dsh-plugin`](https://github.com/topics/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](https://www.npmjs.com/package/@sheep233_/dsh-web-search-free)**

**MCP server（无需 clone，一条命令接入）：**

```bash
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：

```bash
# 安装依赖（等价于在 ~/.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 生效：

```jsonc
{
  "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（默认，无需端口）

```bash
# 本地路径方式（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（监听端口，双端口模式）

```bash
# 启动 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）**：

  ```bash
  claude mcp add --transport http dsh-web-search http://127.0.0.1:3100
  ```

- **Codex（OpenAI Codex CLI）**：

  ```bash
  codex mcp add --transport http dsh-web-search http://127.0.0.1:3100
  ```

- **老式 SSE 客户端**（URL 指向 SSE 通道）：

  ```bash
  # 客户端配置 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 插件本体）

> ⚠️ **为什么别人装上设置里看不到卡片？** 设置卡片要显示需要同时满足：
> 1. 包被声明进 `dsh.profile.bundles`（**只把包放进 node_modules 是不够的**）；
> 2. 安装后**重启 DSH**（host 装配与 client 图都在启动时解析）；
> 3. 打开设置前**刷新浏览器页面**；
> 4. profile 是 `web`（`tui`/`headless` 无浏览器 UI）；
> 5. 安装方式任选：本地路径 / `link:` / tgz / `npm i -g @sheep233_/dsh-web-search-free`
>    （`npx @sheep233_/dsh-web-search-free` 也可用于 MCP server）。
> 装好后可用 `dev_plugin_status` 确认 `client ✓`，或直接看设置 → 插件设置 → 可配置。

**界面效果**（设置 → 插件设置 → 可配置 → 免费网页搜索）：

![免费网页搜索设置卡片](assets/settings-card.jpg)

**方式一：dsh 官方安装（默认推荐）**

```bash
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` 输出中应能看到插件行。

```bash
npm i -g @sheep233_/dsh-web-search-free   # 可选：全局安装（配合 link: 或 MCP npx 使用）
```

**方式二：本机热装配（dsh-super-injector，免重启）**

```bash
dev_install_package   # dir = 插件包目录（含 package.json 与 lib/）
```

**方式三：本地路径 link（本地开发）**

在 `~/.dsh/profiles/web/package.json` 中声明：

```jsonc
{
  "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（离线环境）**

```bash
npm run build && npm pack
# 把产物 tgz 加入 profile 依赖后重装（pnpm install），重启生效
```

## 验证

```bash
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
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