中文 | English

dsh-web-search-exa

Exa 驱动的 web_search 提供商插件，挂在 DeepSeek Harness 的 web 能力 seam（ctx.web）上。调用 Exa REST API（POST https://api.exa.ai/search，神经/关键词/自动搜索），把结果归一化成 seam 的可引用来源结构（url / title / snippet / publishedAt），替代或补充官方自带的 DeepSeek 原生搜索。

快速开始（小白版）

你需要准备：

• 一台装好 DeepSeek Harness（dsh）并能正常打开 Web 界面的电脑
• 一个 Exa 账号（exa.ai 注册，免费额度就够用）
• 大约 3 分钟时间

第 1 步：安装插件（一条命令）

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

第 2 步：拿到 Exa API key

1. 打开 exa.ai，注册并登录
2. 进入 Dashboard → API Keys → 新建一个 key
3. 复制 key（形如 exa-xxxxxxxxxxxx 的一串字符）

第 3 步：把 key 告诉 dsh

最简单的方式是用环境变量。在启动 dsh web 的那个终端里执行：

macOS / Linux：

export EXA_API_KEY="exa-你的key"

Windows PowerShell：

$env:EXA_API_KEY="exa-你的key"

如果你不是从终端启动 dsh（比如点了桌面图标），就把 EXA_API_KEY 加到系统环境变量里，再重启 dsh。

第 4 步：把默认搜索换成 Exa

打开 ~/.dsh/profiles/web/cordis.patch.yml（Windows 为 %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml），在文件末尾加上：

- id: web
  config:
    searchProvider: exa

第 5 步：重启 dsh web

关掉再重新启动（改配置后必须重启才生效）。

第 6 步：验证

在对话里随便问一句（比如"今天有什么新闻？"），如果搜索结果带来源链接，说明 Exa 搜索已经生效。服务日志里没有 WEB_PROVIDER_UNAVAILABLE / WEB_PROVIDER_CREDENTIAL_MISSING 报错即成功。

常见问题

• 搜出来的还是原来的结果？ → 检查第 4 步的两行配置有没有写进文件末尾，并确认第 5 步重启过。
• 报 WEB_PROVIDER_CREDENTIAL_MISSING？ → 第 3 步的 key 没生效：检查环境变量名是否拼写为 EXA_API_KEY，且启动 dsh 的终端里执行过 export。
• 想换回 DeepSeek 默认搜索？ → 删掉第 4 步加的两行，重启即可。

---

安装

把插件装进 web profile（$DSH_HOME/profiles/web）。推荐从 npm 安装：

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

该命令会把 dsh-web-search-exa 写入 profile 的 dependencies 并自动追加到 dsh.profile.bundles；插件自带的 cordis.patch.yml 会把 provider 挂进 ctx.web，注册 id 为 exa。

本地开发（改代码即时生效）用 link 方式：

# 1. 依赖 shim：link 方式安装时 Node 从插件真实路径解析子依赖，
#    需要在包内建指向 dsh 安装的符号链接（与宿主共享同一份模块实例）
node scripts/link-deps.mjs   # 在插件目录内执行

# 2. 本地 link
dsh plugin --profile web add link:<本机插件绝对路径，如 /path/to/dsh-web-search-exa>

切换到 Exa 搜索

编辑 profile 用户层 ~/.dsh/profiles/web/cordis.patch.yml，把 seam 的 searchProvider 指向 exa：

- id: web
  config:
    searchProvider: exa

（base 层默认是 deepseek-official；用户层按行整体替换 config，所以这里 只写这一项即可。改回 DeepSeek 就把这条删掉。）

配置 API key（三选一）

1. 环境变量（默认）：启动 dsh web 前导出 EXA_API_KEY。
2. 凭据服务：$DSH_HOME/.credentials.yaml 里按凭据名 EXA_API_KEY 存， 或走 Web 的凭据管理入口。
3. 字面量（不推荐，会进配置文件）：$DSH_HOME/settings.yaml：

web-search-exa:
  apiKey: exa-xxxxxxxx

可选设置（settings.yaml 热更新，无需重启）：

web-search-exa:
  apiKeyEnv: EXA_API_KEY   # 凭据引用名，默认 EXA_API_KEY
  baseURL: https://api.exa.ai   # 默认；或环境变量 EXA_SEARCH_BASE_URL
  numResults: 5            # 每次搜索向 Exa 请求的结果数，1–10，默认 5

验证

重启 dsh web 后在对话里让 agent 搜一下，或看服务日志中 provider 选择： 没有报 WEB_PROVIDER_UNAVAILABLE / WEB_PROVIDER_AMBIGUOUS 即挂载成功。 搜索卡片（WebSearchCard）只显示官方 web-search-deepseek 的面板；本插件的 设置走 settings.yaml（热更新），不依赖该卡片。

说明

• 每个请求发送 x-api-key 头到 {baseURL}/search，请求体带 query / numResults / contents.text.maxCharacters=600。
• request.maxResults（工具层下发的上限）会作为 numResults 下发到 Exa， 省成本；seam 仍会做最终截断。
• 错误码沿用 seam 约定：WEB_PROVIDER_ERROR、WEB_PROVIDER_CREDENTIAL_MISSING、 WEB_ABORTED。