dsh-exa-search

Readme

# dsh-exa-search

`dsh-exa-search` 是一个独立的 DeepSeek Harness（DSH）插件，通过 Exa 提供更详细的网页搜索能力。

插件注册 `exa_search` 工具，适合以下场景：

- 需要深入研究、技术调研或学术资料发现；
- 需要一次检索更多来源并保留标题、链接、作者、日期和摘要；
- 供应商模型不支持 Anthropic 协议，但能够使用 DSH 的工具调用能力；
- DSH 自带的 `web_search` 结果不够详细，需要更强的 Exa 搜索类型。

它与 DSH 自带的 `web_search` 并存：`web_search` 适合快速查找，`exa_search` 适合更深入的检索。插件不绑定特定模型或 GPU 运行时。

## 功能

- 使用 Exa `/search` API，支持 `auto`、`fast`、`instant`、`deep-lite`、`deep` 和 `deep-reasoning`；
- 支持模型传入 `query`、`numResults` 和 `type`；
- 对查询、结果数量、响应体大小和模型可见输出设置上限；
- 支持请求取消和超时；
- API 密钥不会写入请求日志，配置项会标记为敏感信息；
- 返回稳定的错误代码，便于日志分析和上层处理。

## 安装

### 从 npm 安装

```bash
dsh plugin --profile web add dsh-exa-search
```

### 从 GitHub 安装

```bash
dsh plugin --profile web add github:Kev-ZJY/dsh-exa-search
```

从 GitHub 安装时，DSH 会安装依赖并执行插件的 `prepare` 构建脚本，生成运行所需的 `lib` 目录。若包管理器提示是否允许运行构建脚本，请确认来源可信后再允许。

也可以先构建并打包：

```bash
npm install
npm run build
npm pack
dsh plugin --profile web add ./dsh-exa-search-0.1.0.tgz
```

## 配置 API 密钥

推荐使用环境变量：

```bash
export EXA_API_KEY="你的 Exa API 密钥"
```

也可以在 DSH 插件配置中填写 `apiKey`。插件配置优先级高于环境变量；密钥为空时才会回退到 `EXA_API_KEY`。请勿把真实密钥提交到仓库、配置补丁或日志中。

## 配置项

配置可以通过 DSH 设置界面或 bundle patch 覆盖。修改配置后需要重启对应的 DSH profile，确保工具描述中的默认值和限制同步更新。

| 配置项 | 默认值 | 说明 |
| --- | ---: | --- |
| `apiKey` | 空 | Exa API 密钥；为空时读取 `EXA_API_KEY` |
| `apiBaseUrl` | `https://api.exa.ai` | Exa API 地址，仅支持 HTTP/HTTPS |
| `timeoutMs` | `30000` | 单次请求超时，范围为 1–120000 毫秒 |
| `defaultType` | `auto` | 默认搜索类型 |
| `defaultNumResults` | `5` | 未指定时的结果数量 |
| `maxNumResults` | `25` | 单次最多请求的结果数量 |
| `maxOutputChars` | `40000` | 返回给模型的文本上限 |
| `maxResponseChars` | `1000000` | Exa 响应体大小上限 |

## 工具参数

模型可调用：

```json
{
  "query": "DeepSeek Harness plugin development requirements",
  "numResults": 8,
  "type": "deep"
}
```

`query` 不能为空；`numResults` 必须是整数，且不能超过 `maxNumResults`。工具结果包含 `query`、`resultCount`、`returnedCount`、`truncated` 和面向模型的 `text` 字段。

## 错误代码

插件会使用以下稳定错误代码：

`EXA_CONFIG_ERROR`、`EXA_API_KEY_MISSING`、`EXA_INVALID_ARGUMENT`、`EXA_ABORTED`、`EXA_TIMEOUT`、`EXA_REQUEST_ERROR`、`EXA_HTTP_ERROR`、`EXA_RESPONSE_TOO_LARGE` 和 `EXA_INVALID_RESPONSE`。

## 本地开发

环境要求：Node.js 20 或更高版本。

```bash
npm install
npm run typecheck
npm test
npm run build
npm pack --dry-run
```

测试使用模拟的 Exa 响应，不需要真实 API 密钥。

## 相关链接

- [DeepSeek Harness 插件开发文档](https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/)
- [Exa Search API 文档](https://exa.ai/docs/reference/search)
- [GitHub 仓库](https://github.com/Kev-ZJY/dsh-exa-search)

## 许可证

MIT