# API 列表

> dsh-exa-mcp 对外接口全集：安装/加载接口、配置接口、工具接口、运行时接口。除注明外均为**实测验证**（dsh 0.1.0-rc.6 + 真实 Exa 端点）。

## 1. 安装与加载接口

| 方式 | 命令 / 文件 | 说明 |
|---|---|---|
| 标准安装 | `dsh plugin --profile <name> add <path-or-package-or-github>` | 初始化/更新 profile，pnpm 链接，追加 bundle 到 `dsh.profile.bundles` |
| 卸载 | `dsh plugin --profile <name> remove dsh-exa-mcp` | 移除依赖与 bundle 层，profile 其余部分不变 |
| 一次性覆盖 | `dsh web --patch <path>/cordis.patch.yml` | 不安装，仅本次运行生效 |
| 持久化（免安装） | 合并 insert 块到 `$DSH_HOME/profiles/<name>/cordis.patch.yml` | 长期生效 |
| npm 清单 | `package.json` 的 `dsh.bundle.patch: "./cordis.patch.yml"` | 声明 bundle 的补丁层 |

要求：dsh CLI 自带 `@deepseek-ai/dsh-mcp-client`；`dsh plugin` 需要机器上安装 pnpm。

## 2. 配置接口（`mcp-exa` 行）

行定义（继承 `@deepseek-ai/dsh-mcp-client` 的 Config schema，逐字段校验）：

| 字段 | 类型 | 必填 | 本插件值 | 说明 |
|---|---|---|---|---|
| `serverName` | string | 是 | `exa` | `[A-Za-z0-9_-]{1,32}`，决定 `mcp__exa__*` 命名 |
| `transport` | `"streamable-http"` | 是 | `streamable-http` | Exa 托管端点协议 |
| `url` | string | 是 | `https://mcp.exa.ai/mcp` | 可追加 `?tools=` / `?defaultSearchType=` 调参 |
| `headers` | object | 否 | `!!js` 条件表达式 | 有 `EXA_API_KEY` → `{"x-api-key": <key>}`；无 → `{}` |
| `toolCallTimeoutMs` | number | 否 | `180000` | 适配长耗时的 agent 研究 |
| `failOnStartupError` | boolean | 否 | （默认 false） | 初始失败仅记录并进入重连 |
| `reconnect.*` | object | 否 | （默认） | `enabled`/`initialDelayMs`/`maxDelayMs`/`maxAttempts` |

覆盖方法（dsh patch 层语义，需重写完整 config）：

```yaml
- id: mcp-exa
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: exa
    transport: streamable-http
    url: 'https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa,agent_run'
    headers: !!js 'process.env.EXA_API_KEY ? { "x-api-key": process.env.EXA_API_KEY } : {}'
    toolCallTimeoutMs: 300000
```

## 3. 工具接口（模型可见）

命名：`mcp__exa__<rawName>`。默认（匿名或有 key）均为 2 个基础工具；可选工具经 `?tools=` 白名单启用（详见 [SOLUTIONS.md 1.4](SOLUTIONS.md)）。

### 3.1 `mcp__exa__web_search_exa`（匿名可用，实测）

- 描述：语义化网页搜索，返回干净文本结果（标题/URL/发布时间/高亮）
- Schema（JSON Schema draft-07）：

```json
{
  "type": "object",
  "properties": {
    "query": { "type": "string", "minLength": 1,
      "description": "Natural language search query. Should be a semantically rich description of the ideal page, not just keywords. Optionally include category:<type> (company, people) to focus results" },
    "numResults": { "type": "number",
      "description": "Number of search results to return (default: 10)" }
  },
  "required": ["query"],
  "additionalProperties": false
}
```

### 3.2 `mcp__exa__web_fetch_exa`（匿名可用，实测）

- 描述：按已知 URL 抓取网页干净 markdown，支持批量
- Schema：

```json
{
  "type": "object",
  "properties": {
    "urls": { "type": "array", "items": { "type": "string" },
      "description": "URLs to read. Batch multiple URLs in one call." },
    "maxCharacters": { "type": "number", "minimum": 1,
      "description": "Maximum characters to extract per page (default: 3000)" }
  },
  "required": ["urls"],
  "additionalProperties": false
}
```

### 3.3 `mcp__exa__web_search_advanced_exa`（2026-08-14 实测通过）

- 高级筛选搜索：**匿名也可用**（白名单即启用，无需 key）；经 `?tools=web_search_exa,web_fetch_exa,web_search_advanced_exa` 启用；返回带 `requestId`/`resolvedSearchType`/`results[]`
- 参数（实测 27 个）：`query`/`numResults`/`type`/`category`；域名：`includeDomains`/`excludeDomains`；时间：`startPublishedDate`/`endPublishedDate`/`startCrawlDate`/`endCrawlDate`/`maxAgeHours`；文本：`includeText`/`excludeText`/`textMaxCharacters`/`contextMaxCharacters`；摘要/高亮：`enableSummary`/`summaryQuery`/`enableHighlights`/`highlightsMaxCharacters`/`highlightsNumSentences`/`highlightsPerUrl`/`highlightsQuery`；其他：`userLocation`/`moderation`/`additionalQueries`/`livecrawlTimeout`/`subpages`/`subpageTarget`
- 来源：[Exa MCP 文档](https://exa.ai/docs/reference/exa-mcp)

### 3.4 `mcp__exa__agent_run`（需鉴权 + 白名单，2026-08-14 实测通过）

- 多步自主研究 agent；`?tools=` 白名单启用（`web_search_exa,web_fetch_exa,agent_run`）；匿名调用报 `-32000 Authentication required`；**按用量计费**
- Schema 要点（实测）：`query`（必填其一）/ `runId`（`agent_run_*`，续跑同一次运行）/ `systemPrompt` / `outputSchema`（约束输出）/ `input`（`data`/`exclusion` 数组）
- 行为（实测）：返回 `{success, id, status, outputReady, output}`；`output.structured` 按 `outputSchema` 输出，`output.grounding` 带引用（URL/title/confidence）；任务耗时数秒至数分钟（实测最小任务 12.1s）
- 来源：[Exa MCP 文档](https://exa.ai/docs/reference/exa-mcp)

## 4. 运行时接口（dsh 侧可观察面）

### 4.1 会话日志事件（session log）

| 事件 | 关键字段（实测） | 说明 |
|---|---|---|
| `tool/call` | `data.name`、`data.arguments`（JSON 字符串）、`data.callId`、`data.turn/step` | 工具调用记录，`name` 为 `mcp__exa__*` 公开名 |
| `tool/result` | `data.message.content[0].content[0].text`、`...isError` | 结果或错误；`isError: true` 表示 MCP 错误（如 Exa 401/-32602）透传 |

### 4.2 日志（stderr）

`mcp-client(<serverName>): ...` 前缀：重连（warn）、恢复（info）、最终失败（error）。

## 5. 外部接口（不在本插件范围内）

- Exa REST API（`api.exa.ai`）：本插件经 MCP 端点访问，不直接调用 REST
- Exa OAuth（`auth.exa.ai`）：dsh mcp-client 桥不支持，请使用 API key

## 6. 版本

各组件版本与适配矩阵见 **[PROJECT.md §7 版本兼容](PROJECT.md)**（本表不重复维护）。