dsh-exa-search 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 1.0.0
+## 1.0.1
 
 First public release: Exa-backed `web_search` / `web_fetch`, ten additional tools, and three access modes.
 
@@ -39,5 +39,4 @@ First public release: Exa-backed `web_search` / `web_fetch`, ten additional tool
 
 ### Notes
 
-- Early local builds stored credentials as `exa-api-key` / `exa-oauth`, which the credential service rejects at load time and can prevent Harness from starting. If you ran one, run `node scripts/repair-credentials.mjs --dry-run` and then `node scripts/repair-credentials.mjs` before starting Harness.
-- Tests (`node --test`), the CI workflow and the English README are in the repository; they are not part of the npm tarball.
+- Unit tests (`node --test`), the CI workflow and the English README live in the repository; they are not part of the npm tarball.

package/README.en.md

@@ -1,103 +1,136 @@
 # Exa Search for DeepSeek Harness
 
-Exa-backed `web_search` / `web_fetch` for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), with three access modes and per-mode tool registration.
+This plugin provides web search and page fetching for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) through [Exa](https://exa.ai). It supports three access modes — keyless, API key and Exa account — and registers tools according to the active mode.
 
-- The stock `web_search` / `web_fetch` tools keep their schemas but run on Exa.
-- Ten additional `exa_*` tools are registered **only when the active mode can call them**.
-- **Settings → Exa Search** switches modes, shows which tools each mode exposes, and can test the connection.
+Once installed:
+
+- `web_search` and `web_fetch` keep their existing arguments and behaviour; requests are served by Exa.
+- The plugin registers ten additional `exa_*` tools. A tool is exposed to the model only when the active mode can call it.
+- **Settings → Exa Search** switches modes and shows the availability of every tool under all three modes.
 
 ## Tool catalog
 
-| Group | Tool | What it does | Keyless | API key | Exa account |
+| Group | Tool | Purpose | Keyless | API key | Exa account |
 | --- | --- | --- | --- | --- | --- |
 | Search | `web_search` | Harness web search, served by Exa | ✓ | ✓ | ✓ |
-| Search | `exa_search` | Domain / category / date / text / subpage filters | ✓ | ✓ | ✓ |
+| Search | `exa_search` | Domain, category, date, text and subpage filters | ✓ | ✓ | ✓ |
 | Search | `exa_deep_search` | Deep Search: multi-step retrieval with a cited answer | — | ✓ | — |
 | Contents | `web_fetch` | Harness page fetch, served by Exa | ✓ | ✓ | ✓ |
-| Contents | `exa_fetch` | Up to 5 pages, optional highlights / summary / subpages, 3-way concurrency | ✓* | ✓ | ✓* |
-| Contents | `exa_find_similar` | Expand a known-good URL into similar pages | — | ✓ | — |
-| Answer | `exa_answer` | `/answer`: cited answer to a question | — | ✓ | — |
-| Research | `exa_research` | Exa Agent: research, list building, structured output; resume / cancel / stop | — | ✓ | per account |
-| Monitors | `exa_monitor` | Recurring or manual searches; list / create / update / trigger / delete | — | ✓ | — |
-| Websets | `exa_webset` | Verified datasets (Pro plan required) | — | ✓* | — |
-| Batch | `exa_batch` | Submit many search / agent requests (team feature) | — | ✓* | — |
-| Status | `exa_status` | Active mode, tool counts, spend estimate | ✓ | ✓ | ✓ |
+| Contents | `exa_fetch` | Up to five pages; optional highlights, summary and subpages (API key required for those three), three-way concurrency | ✓ | ✓ | ✓ |
+| Contents | `exa_find_similar` | Expands a known URL into similar pages | — | ✓ | — |
+| Answer | `exa_answer` | `/answer`: a cited answer to a question | — | ✓ | — |
+| Research | `exa_research` | Exa Agent: research, list building and structured output; resume, cancel, stop | — | ✓ | per account |
+| Monitors | `exa_monitor` | Monitors: scheduled or manual searches; list, create, update, trigger, delete | — | ✓ | — |
+| Websets | `exa_webset` | Websets: build and read verified datasets | — | ✓* | — |
+| Batch | `exa_batch` | Batch: submit many `/search` or `/agent/runs` requests | — | ✓* | — |
+| Status | `exa_status` | Reports the active mode, available tools and upstream tool list | ✓ | ✓ | ✓ |
+
+Twelve tools in total: ten registered by the plugin and two native Harness tools redirected to Exa.
+
+\* Websets requires a Pro plan; Batch must be enabled for the team. When an API key is active, the plugin performs one free probe for each. Features the team does not have are not registered as tools; the settings page marks them as unavailable instead of letting the model receive a 401 or 403.
+
+## Deprecated MCP tools
+
+The Exa MCP repository keeps eight deprecated entries in `toolRegistry.ts` (disabled by default). Their capabilities are covered by the current tools, so the plugin does not register them again:
+
+| Deprecated tool | Replacement |
+| --- | --- |
+| `get_code_context_exa` | `exa_search` with `category=github` |
+| `company_research_exa` | `exa_search` with `category=company` |
+| `people_search_exa` | `exa_search` with `category=people` |
+| `linkedin_search_exa` | `exa_search` with `category=linkedin profile` |
+| `deep_search_exa` | `exa_deep_search` |
+| `crawling_exa` | `exa_fetch` |
+| `deep_researcher_start` | `exa_research` |
+| `deep_researcher_check` | `exa_research` with `runId` |
 
-\* `exa_fetch` highlights/summary/subpages need an API key. Websets needs a Pro plan; Batch must be enabled for the team. The plugin probes both with free GETs and simply does not register tools the team cannot use.
+The same table appears at the bottom of the settings page.
 
 ## Access modes
 
 | Mode | Credential | Upstream | Notes |
 | --- | --- | --- | --- |
-| `keyless` | none | `mcp.exa.ai/mcp` | Free, rate-limited per IP. Advanced search is opted in through `?tools=` (Exa allows it unauthenticated); `agent_run` is not available. |
-| `apiKey` | saved key or `EXA_API_KEY` | `api.exa.ai` | Full REST surface: search, contents, find similar, answer, agent, monitors, websets, batch. |
-| `oauth` | browser sign-in | `mcp.exa.ai/mcp` with a bearer token | MCP tools follow the account; `agent_run` appears when the account exposes it. |
+| `keyless` | none | `https://mcp.exa.ai/mcp?tools=...` | Basic search, advanced search and fetching. Exa documents `web_search_advanced_exa` as usable without authentication, so it is enabled through the `tools` parameter. `agent_run` requires authentication and cannot be added to a keyless connection (the whole connection then returns 401). |
+| `apiKey` | key saved in Settings, or `EXA_API_KEY` | `https://api.exa.ai` | The full REST surface: Search, Contents, Find Similar, Answer, Agent, Monitors and Websets. |
+| `oauth` | browser sign-in | `https://mcp.exa.ai/mcp?tools=...` | MCP tools follow the account. `agent_run` is probed after sign-in; `exa_research` is registered only when it is present. |
 
-The matrix is live, not marketing: the OAuth research row is resolved from the server's real `tools/list` after sign-in.
+“Per account” means the tool is registered according to the real `tools/list` response after sign-in, not a fixed setting.
 
 ## Implementation notes
 
-- **MCP tool list**: keyless sends `?tools=web_search_exa,web_fetch_exa,web_search_advanced_exa`; OAuth adds `agent_run` and retries without it if the connection is rejected.
-- **Rate limits**: keyless answers with `_meta.ai.exa/rateLimited` or a plain text notice; both are translated into a clear error instead of being returned as results.
-- **Deep Search** only synthesizes when `outputSchema` is present. The tool sends a `{ "type": "text" }` schema by default and returns structured JSON if you pass your own.
-- **Websets** lives on its own mount point: `api.exa.ai/websets/v0/websets…`.
-- **Credentials** are stored under `exa-search/api-key` / `exa-search/oauth` (the service requires `<scope>/<id>`), resolved through an injection, and writes are validated before touching the vault.
-- **Request policy**: hard timeouts (search 30s, MCP 60s, Agent 240s), retries with backoff for 429/5xx and `Retry-After`, and one forced token refresh on a 401.
-- **Spend estimate**: accumulated from Exa's `costDollars`; Agent runs are counted once at a terminal status. OAuth MCP search responses carry no cost field, so the estimate covers REST calls and Agent runs.
+**MCP `tools` parameter.** The hosted Exa MCP endpoint exposes only `web_search_exa` and `web_fetch_exa` by default, and `agent_run` only on authenticated connections. The plugin builds the URL per mode:
 
-## Install
+- Keyless: `?tools=web_search_exa,web_fetch_exa,web_search_advanced_exa`
+- Exa account: `?tools=...,agent_run`; if the probe fails, the request is retried without `agent_run`.
 
-```bash
-dsh plugin add dsh-exa-search
-```
+**Rate limits.** When the keyless channel is rate limited, Exa returns `_meta.ai.exa/rateLimited` or a plain “free MCP rate limit” message rather than a JSON-RPC error. The plugin converts either into an explicit error that asks for an API key or sign-in; the text is never returned as a search result.
 
-Or install this directory from the plugin manager. A local directory install links the folder; moving or deleting it breaks the plugin.
+**Agent continuation.** `exa_research` waits at most `timeoutSeconds` per call (default 120, maximum 600). On timeout it returns `status: "running"` and a `runId`; a later call with that `runId` continues waiting. API key mode uses `POST /agent/runs` with polling; account mode uses the MCP `agent_run` tool.
 
-Installing pins the `web` row to the `exa` providers (`cordis.patch.yml`). That pin is required: with two usable search providers, `ctx.web` fails closed with `WEB_PROVIDER_AMBIGUOUS` instead of guessing.
+**Category mapping.** The REST API accepts category names such as `research paper` and `linkedin profile`, while advanced MCP search uses a strict enum. The plugin maps the former to `publication` and `people`; categories without a mapping are dropped rather than sent unchanged.
 
-## Configuration
+**Deep Search and `outputSchema`.** Exa synthesizes an answer only when the request contains `outputSchema`; without it, `type: deep` still returns only `results`. The plugin supplies `{ "type": "text" }` by default to obtain a prose answer and returns structured JSON when the caller passes an object schema.
 
-| Key | Default | Meaning |
-| --- | --- | --- |
-| `mode` | `keyless` | First-run mode; the settings page overrides it. |
-| `apiKeyEnv` | `EXA_API_KEY` | Environment fallback when no key is saved. |
-| `numResults` | `8` | Default number of sources. |
-| `searchType` | `auto` | REST search effort: `auto` / `lite` / `fast`. |
-| `maxCharacters` | `12000` | Per-page fetch cap. |
-| `mcpTools` | `null` | Overrides the MCP `tools` list (array or comma string). |
-| `toolGroups` | `null` | Initial per-group tool switches, e.g. `{ "answer": false }`. |
-| `locale` | `auto` | Message language: `auto` / `en` / `zh`. |
+**Websets mount point.** In the OpenAPI document, `/v0/websets` declares `servers: https://api.exa.ai/websets`; the effective path is `/websets/v0/websets…`. Without the prefix every request returns 404.
+
+**Entitlement probes.** Batch returns 403 when disabled and Websets returns 401 without a Pro plan. Both probes are free GETs; the plugin runs them at startup and on mode changes and does not register tools that the team cannot use.
+
+**Fetch formats.** `exa_fetch` supports `format: text`, `highlights` and `summary`. API key mode requests the corresponding Contents fields; keyless and account modes return body text only and report a clear error for other formats. Multiple URLs are fetched three at a time; a failed URL carries an `error` field and does not affect the remaining pages.
+
+**Monitor updates.** `exa_monitor` with `action=update` can rename a monitor, pause or resume it (`status: active | paused`), and change its query or interval. `manual: true` or `period: "none"` creates a monitor without a schedule, which runs only through `trigger`.
 
-## Data
+**Credential handling.** The credential service is resolved through `ctx.inject`, so a service that activates after the plugin does not cause a fallback to plaintext storage. Every write validates that the record key follows `<scope>/<id>`, which prevents records that the service cannot load at the next start. When a refresh token is revoked (`invalid_grant`), the plugin drops the grant and falls back to an API key or keyless mode instead of returning 401 indefinitely.
 
-- Mode and OAuth client registration: `<DSH_HOME>/exa-search/state.json`.
-- API key and OAuth token: the Harness credential service, under `exa-search/api-key` / `exa-search/oauth`. Only when the vault is unavailable do they fall back to `state.json` (mode 0600).
-- Nothing is written into the install directory, and no state ships with the package.
+**Request policy.** Every outbound request has a hard timeout (search 30s, contents 30s, MCP tools 60s, Agent 240s). 429/5xx responses and network failures are retried twice with exponential backoff, honouring `Retry-After`; a cancellation signal interrupts the wait immediately.
 
-### Repair after a failed start
+**OAuth token expiry.** On a 401 from MCP, the plugin force-refreshes the token and replays the request once; only a second failure is reported as a sign-in requirement.
+
+**Cancelling Agent runs.** `exa_research` supports `action: cancel | stop` with a `runId` (`cancel` stops immediately; `stop` keeps the results collected so far). This is available only in API key mode; OAuth tokens can call MCP only, which exposes no cancellation endpoint.
+
+**Spend estimate.** Exa reports `costDollars.total` on billed REST responses. The plugin accumulates it per process and shows it in `exa_status` and on the settings page. Agent runs are recorded once, when they reach a terminal status, so polling does not double-count. OAuth MCP search responses carry no cost field, so that mode estimates Agent runs only; the counter restarts at zero with the process.
+
+## Installation
+
+Install this directory through the Harness plugin manager, or install `dsh-exa-search` from npm.
+
+A local directory install stores a link rather than a copy in the profile; moving or deleting the source directory disables the plugin.
+
+Installation pins the `web` row to the `exa` provider (see `cordis.patch.yml`). The pin is required: with two usable search providers, `ctx.web` fails closed with `WEB_PROVIDER_AMBIGUOUS` rather than choosing one.
+
+## Configuration
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `mode` | `keyless` | Initial access mode; the settings page overrides it. |
+| `apiKeyEnv` | `EXA_API_KEY` | Environment variable read when no key is saved. |
+| `numResults` | `8` | Default number of sources. |
+| `searchType` | `auto` | REST search effort: `auto`, `lite` or `fast`. |
+| `maxCharacters` | `12000` | Per-page fetch limit. |
+| `locale` | `auto` | Message language: `auto` follows the system, or `en` / `zh`. |
+| `mcpTools` | `null` | Overrides the MCP `tools` list (array or comma-separated string). |
+| `toolGroups` | `null` | Initial per-group switches, e.g. `{ "answer": false, "webset": false }`. Changes made in Settings are stored in the state file and override this value. |
 
-If Harness refuses to start with `credential key "..." must be "<scope>/<id>"` (written by a pre-release local build), quit the app and run:
+Each group on the settings page has a switch. Disabling a group removes its `exa_*` tools from the model's tool list immediately; the `web_search` / `web_fetch` redirection is unaffected. The **Test connection** button at the top performs one minimal search with the active mode and reports latency and a sample result (one search is consumed).
 
-```bash
-node scripts/repair-credentials.mjs --dry-run
-node scripts/repair-credentials.mjs
-```
+## Data and credentials
 
-The script only renames those two record keys, backs the file up first, and refuses to guess if both forms exist.
+- Access mode and OAuth client registration: `<DSH_HOME>/exa-search/state.json`. The Host process does not guarantee `DSH_PROFILE_DIR`, so this state is stored per user rather than per profile.
+- API key and OAuth tokens: the Harness credential service (`ctx.credentials`), under the record keys `exa-search/api-key` and `exa-search/oauth`. They fall back to `state.json` (file mode 0600) only when the credential service is unavailable.
+- No credential is written into the installation directory, and no state file is shipped with the package.
 
 ## Routes
 
 The settings page uses same-origin routes instead of generated remotes:
 
-- `GET /exa-plugin/state` — mode, credentials (masked), upstream tools, matrix, counts;
-- `GET /exa-plugin/diagnostics` — redacted snapshot for bug reports;
-- `POST /exa-plugin/mode` / `api-key` / `login` / `logout` / `tools` / `test` — mutations, cross-origin requests rejected;
+- `GET /exa-plugin/state` — active mode, credential status, upstream tool list, tool matrix and per-mode counts;
+- `GET /exa-plugin/diagnostics` — a redacted snapshot for issue reports;
+- `POST /exa-plugin/mode` / `api-key` / `login` / `logout` / `tools` / `test` — mutations; cross-origin requests are rejected;
 - `GET /exa-plugin/oauth/callback` — OAuth callback.
 
-## Not covered
+## Scope
 
-Team management, webhooks/events, imports and Websets enrichments are account plumbing or plan-gated; they are not exposed as model tools.
+Team management, webhooks and events, imports and Websets enrichments are account or event-delivery plumbing and are not exposed as model tools. The search, contents, answer, research, monitor, dataset and batch workflows are complete.
 
 ## Uninstall
 
-`dsh plugin remove dsh-exa-search`. The `web` row falls back to the shipped default.
+`dsh plugin remove dsh-exa-search`. After removal, the `web` row is decided by the underlying bundles again.

package/README.md

@@ -1,39 +1,41 @@
 # Exa Search for DeepSeek Harness
 
-> **English** — full README in [README.en.md](./README.en.md). Short version: Exa-backed `web_search` / `web_fetch` with three access modes (keyless, API key, OAuth) and per-mode tool registration; install `dsh-exa-search`, then open **Settings → Exa Search**.
+> English documentation: [README.en.md](./README.en.md)
 
-把 Harness 的联网搜索交给 [Exa](https://exa.ai)。安装后：
+本插件为 DeepSeek Harness 提供基于 [Exa](https://exa.ai) 的联网搜索与网页抓取能力，支持免登录、API Key 与 Exa 账号三种接入方式，并按接入方式注册工具。
 
-- `web_search`、`web_fetch` 的 schema 不变，实际请求全部走 Exa；
-- 另外注册 10 个 Exa 工具，**按接入方式注册**：只有当前方式真能调用的工具才会出现在模型面前；
-- 「设置 → Exa 搜索」里可以切换接入方式，并按功能分组看到全部工具在三种方式下的可用性。
+安装后：
+
+- `web_search`、`web_fetch` 的调用方式与参数保持不变，实际请求由 Exa 提供；
+- 插件额外注册 10 个 `exa_*` 工具；仅当当前接入方式可以调用某个工具时，该工具才会暴露给模型；
+- 在「设置 → Exa 搜索」中可切换接入方式，并查看全部工具在三种方式下的可用性。
 
 ## 工具清单（按功能分组）
 
 | 分组 | 工具 | 作用 | 免登录 | API Key | Exa 账号 |
 | --- | --- | --- | --- | --- | --- |
-| 检索 | `web_search` | Harness 原生搜索，已改走 Exa | ✓ | ✓ | ✓ |
+| 检索 | `web_search` | Harness 原生搜索，由 Exa 提供 | ✓ | ✓ | ✓ |
 | 检索 | `exa_search` | 域名 / 分类 / 日期 / 文本 / 子页过滤 | ✓ | ✓ | ✓ |
-| 检索 | `exa_deep_search` | Deep Search：多步检索 + 带引用的综合答案 | — | ✓ | — |
-| 内容 | `web_fetch` | Harness 原生抓取，已改走 Exa | ✓ | ✓ | ✓ |
-| 内容 | `exa_fetch` | 抓取最多 5 个网页；可选取 highlights / summary / 子页（后三者需 API Key），并发 3 | ✓ | ✓ | ✓ |
-| 内容 | `exa_find_similar` | 由一篇已知好文扩展相似页面 | — | ✓ | — |
+| 检索 | `exa_deep_search` | Deep Search：多步检索与带引用的综合答案 | — | ✓ | — |
+| 内容 | `web_fetch` | Harness 原生抓取，由 Exa 提供 | ✓ | ✓ | ✓ |
+| 内容 | `exa_fetch` | 最多 5 个网页；可选取 highlights / summary / 子页（后三者需 API Key），3 路并发 | ✓ | ✓ | ✓ |
+| 内容 | `exa_find_similar` | 由一篇已知网址扩展相似页面 | — | ✓ | — |
 | 问答 | `exa_answer` | `/answer`：带引用的直接问答 | — | ✓ | — |
-| 研究 | `exa_research` | Exa Agent：研究、建名单、结构化输出（续等 / 取消 / 停止） | — | ✓ | 登录后按账号 |
+| 研究 | `exa_research` | Exa Agent：研究、名单构建、结构化输出（续等 / 取消 / 停止） | — | ✓ | 按账号 |
 | 监控 | `exa_monitor` | Monitors：定时或手动搜索，列表 / 新建 / 修改 / 触发 / 删除 | — | ✓ | — |
-| 数据集 | `exa_webset` | Websets：构建、读取经过验证的数据集 | — | ✓* | — |
+| 数据集 | `exa_webset` | Websets：构建与读取经过验证的数据集 | — | ✓* | — |
 | 批量 | `exa_batch` | Batch：批量提交 `/search` 或 `/agent/runs` | — | ✓* | — |
 | 状态 | `exa_status` | 报告当前方式、可用工具与上游工具表 | ✓ | ✓ | ✓ |
 
-合计 12 个，其中 10 个由插件注册、2 个是 Harness 原生的改道。
+合计 12 个工具，其中 10 个由插件注册，2 个为 Harness 原生工具的 Exa 改道。
 
-\* Websets 需要 Pro 计划，Batch 需要团队单独开通。启用 API Key 时插件会各发一次免费探测；团队没有的功能不会注册成工具，设置页注明「当前团队未开通」，而不是让模型调用后拿到 401/403。
+\* Websets 需要 Pro 计划，Batch 需要团队单独开通。启用 API Key 时，插件会分别执行一次免费探测；未开通的功能不会注册为工具，设置页会标注「当前团队未开通」，以避免模型调用后收到 401/403。
 
-## 旧版 MCP 工具的去向
+## 旧版 MCP 工具映射
 
-Exa MCP 仓库的 `toolRegistry.ts` 里还有 8 个已弃用条目（默认关闭）。它们的能力已被现代工具覆盖，所以不重复注册：
+Exa MCP 仓库的 `toolRegistry.ts` 中保留了 8 个已弃用条目（默认关闭）。这些能力已由现有工具覆盖，因此插件不再重复注册：
 
-| 旧工具 | 现在用 |
+| 旧工具 | 对应工具 |
 | --- | --- |
 | `get_code_context_exa` | `exa_search`，`category=github` |
 | `company_research_exa` | `exa_search`，`category=company` |
@@ -42,109 +44,95 @@ Exa MCP 仓库的 `toolRegistry.ts` 里还有 8 个已弃用条目（默认关
 | `deep_search_exa` | `exa_deep_search` |
 | `crawling_exa` | `exa_fetch` |
 | `deep_researcher_start` | `exa_research` |
-| `deep_researcher_check` | `exa_research`，传 `runId` |
+| `deep_researcher_check` | `exa_research`，传入 `runId` |
 
-设置页底部也列出了这张对照表，避免“看起来少了一个工具”。
+设置页底部同样列出该对照表，以便核对工具是否缺失。
 
-## 三种接入方式
+## 接入方式
 
-| 方式 | 凭据 | 上游 | 能覆盖到哪 |
+| 方式 | 凭据 | 上游 | 说明 |
 | --- | --- | --- | --- |
-| 免登录 `keyless` | 不需要 | `https://mcp.exa.ai/mcp?tools=...` | 基础搜索、高级搜索、抓取。Exa 明确说明 `web_search_advanced_exa` 不需要认证，所以用 `tools` 参数把它打开；`agent_run` 需要认证，不能放进免登录连接（否则整个连接 401）。 |
-| API Key `apiKey` | 设置页填入，或 `EXA_API_KEY` | `https://api.exa.ai` | 全部：Search、Contents、Find Similar、Answer、Agent、Monitors、Websets。 |
-| Exa 账号 `oauth` | 浏览器授权 | `https://mcp.exa.ai/mcp?tools=...` | MCP 工具随账号开放；`agent_run` 在登录后探测，能探测到才注册 `exa_research`。 |
+| 免登录 `keyless` | 不需要 | `https://mcp.exa.ai/mcp?tools=...` | 基础搜索、高级搜索与抓取。Exa 说明 `web_search_advanced_exa` 无需认证，因此通过 `tools` 参数启用；`agent_run` 需要认证，不能加入免登录连接（否则整个连接返回 401）。 |
+| API Key `apiKey` | 设置页填入，或环境变量 `EXA_API_KEY` | `https://api.exa.ai` | 全部接口：Search、Contents、Find Similar、Answer、Agent、Monitors、Websets。 |
+| Exa 账号 `oauth` | 浏览器授权 | `https://mcp.exa.ai/mcp?tools=...` | MCP 工具随账号开放；`agent_run` 在登录后探测，探测到才会注册 `exa_research`。 |
 
-工具矩阵里 `·` 表示“登录后才确定”，不是写死的宣传语：`exa_research` 在 OAuth 下是否出现，取决于登录后 `tools/list` 的真实返回。
+表格中的「按账号」表示该工具是否注册取决于登录后 `tools/list` 的实际返回，而非固定配置。
 
-## 实现要点
+## 实现说明
 
-**MCP 的 tools 参数**。Exa 的托管 MCP 默认只给 `web_search_exa`、`web_fetch_exa`；`agent_run` 默认只对有凭据的连接开放。插件按模式拼 URL：
+**MCP 的 `tools` 参数**。Exa 托管 MCP 默认仅提供 `web_search_exa` 与 `web_fetch_exa`，`agent_run` 仅对有凭据的连接开放。插件按接入方式拼接 URL：
 
 - 免登录：`?tools=web_search_exa,web_fetch_exa,web_search_advanced_exa`
-- 账号：`?tools=...,agent_run`（探测失败自动去掉 `agent_run` 重试）
+- Exa 账号：`?tools=...,agent_run`；若探测失败，则去掉 `agent_run` 重试。
 
-**限流识别**。免登录命中限额时 Exa 返回的是 `_meta.ai.exa/rateLimited` 或一段“free MCP rate limit”文本，而不是 JSON-RPC error。插件会把它翻译成明确错误，提示去配置 Key 或登录，而不是把限流文案当成搜索结果。
+**限流识别**。免登录通道触发限流时，Exa 返回 `_meta.ai.exa/rateLimited` 或一段 "free MCP rate limit" 文本，而非 JSON-RPC 错误。插件会将其转换为明确错误，并提示配置 API Key 或登录，不会将限流文本作为搜索结果返回。
 
-**Agent 续等**。`exa_research` 最多等 `timeoutSeconds`（默认 120，上限 600），超时返回 `status: "running"` 和 `runId`；再次调用并传入 `runId` 继续等。REST 走 `POST /agent/runs` + 轮询，OAuth 走 MCP 的 `agent_run`。
+**Agent 续等**。`exa_research` 单次最多等待 `timeoutSeconds`（默认 120，上限 600）；超时返回 `status: "running"` 与 `runId`，再次调用并传入该 `runId` 可继续等待。API Key 模式使用 `POST /agent/runs` 与轮询，Exa 账号模式使用 MCP 的 `agent_run`。
 
-**分类差异**。REST 接受 `research paper` / `linkedin profile` 这类分类名，MCP 高级搜索是严格枚举；插件把前者映射成 `publication` / `people`，映射不了的分类会被丢弃而不是原样发送。
+**分类映射**。REST 接口接受 `research paper`、`linkedin profile` 等分类名，MCP 高级搜索使用严格枚举。插件将前者映射为 `publication`、`people`；无法映射的分类会被丢弃，不会原样发送。
 
-**Deep Search 必须带 outputSchema**。Exa 只在请求里有 `outputSchema` 时才做综合——不带的话 `type: deep` 也只返回 `results`，没有 `output`。插件默认补一个 `{ type: "text" }` schema 拿散文答案，调用方传自己的对象 schema 就返回结构化 JSON。
+**Deep Search 的 `outputSchema`**。Exa 仅在请求包含 `outputSchema` 时生成综合答案；缺失时 `type: deep` 也只返回 `results`。插件默认补充 `{ "type": "text" }` 以获得散文答案；调用方传入对象 schema 时返回结构化 JSON。
 
-**Websets 有自己的挂载点**。OpenAPI 里 `/v0/websets` 的 `servers` 是 `https://api.exa.ai/websets`，真实地址是 `/websets/v0/websets...`；少这个前缀会一直是 404。
+**Websets 的挂载点**。OpenAPI 文档中 `/v0/websets` 的 `servers` 为 `https://api.exa.ai/websets`，实际地址为 `/websets/v0/websets…`；缺少该前缀会持续返回 404。
 
-**功能开通探测**。Batch 未开通返回 403、Websets 未开通返回 401（Pro 计划）；两者都是免费 GET，插件在切换/启动时探测，没有开通就不注册对应工具。
+**功能开通探测**。Batch 未开通返回 403，Websets 未开通返回 401（Pro 计划）。两者均为免费 GET；插件在启动或切换接入方式时探测，未开通则不注册对应工具。
 
-**抓取格式**。`exa_fetch` 的 `format` 支持 `text` / `highlights` / `summary`，API Key 模式下分别请求 Contents API 的 `text`、`highlights`、`summary` 对象；免登录/账号的 MCP 抓取只返回正文，请求其它格式会得到明确错误。多 URL 用 3 路并发，单个失败不影响其余页面（结果里带 `error`）。
+**抓取格式**。`exa_fetch` 的 `format` 支持 `text`、`highlights`、`summary`。API Key 模式下分别请求 Contents API 的对应字段；免登录与账号模式的 MCP 抓取仅返回正文，请求其他格式会返回明确错误。多 URL 抓取采用 3 路并发，单个 URL 失败不影响其余页面，失败信息以 `error` 字段返回。
 
-**监控更新**。`exa_monitor action=update` 支持改名、暂停/恢复（`status: active | paused`）、改查询和改周期；`manual: true` 或 `period: "none"` 创建不排期的监控，只能手动 `trigger`。
+**监控更新**。`exa_monitor` 的 `update` 操作支持修改名称、暂停 / 恢复（`status: active | paused`）、修改查询与周期；`manual: true` 或 `period: "none"` 可创建不排期的监控，仅能通过 `trigger` 手动执行。
 
-**凭据读写**。凭据服务通过 `ctx.inject` 解析，即使它比插件晚激活也不会退回明文；写入前会校验记录键必须是 `<scope>/<id>`，避免出现“能写入、下次启动才炸”的坏记录。刷新令牌被吊销时（`invalid_grant`）会丢弃授权并回退到 API Key 或免登录，而不是让联网一直 401。
+**凭据读写**。凭据服务通过 `ctx.inject` 解析，即使其激活晚于插件也不会退回明文存储；写入前会校验记录键必须符合 `<scope>/<id>`，避免产生无法在下次启动时加载的记录。刷新令牌被吊销（`invalid_grant`）时，插件会丢弃授权并回退到 API Key 或免登录，而非持续返回 401。
 
-**请求策略**。所有出站请求都带硬超时（搜索 30s、内容 30s、MCP 工具 60s、Agent 240s），429/5xx/网络失败按指数退避重试 2 次并尊重 `Retry-After`；取消信号会立刻中断等待。
+**请求策略**。所有出站请求均设置硬超时（搜索 30s、内容 30s、MCP 工具 60s、Agent 240s）；429/5xx 与网络失败按指数退避重试 2 次，并遵循 `Retry-After`；取消信号会立即中断等待。
 
-**OAuth 令牌失效**。MCP 返回 401 时不会直接把错误抛给用户：先强制刷新一次令牌并用新令牌重放，仍失败才报“需要重新登录”。
+**OAuth 令牌失效**。MCP 返回 401 时，插件先强制刷新令牌并使用新令牌重放请求；仅当刷新后仍失败时才提示重新登录。
 
-**取消 Agent**。`exa_research` 的 `action: cancel | stop` 配合 `runId` 可中止运行（`cancel` 立即取消，`stop` 保留已收集结果），仅 API Key 模式可用——OAuth 的令牌只能走 MCP，没有取消入口。
+**取消 Agent**。`exa_research` 的 `action: cancel | stop` 配合 `runId` 可中止运行（`cancel` 立即取消，`stop` 保留已收集结果），仅在 API Key 模式下可用；OAuth 令牌仅能通过 MCP 调用，没有取消入口。
 
-**费用估算**。Exa 在 REST 计费响应里返回 `costDollars.total`，插件按进程累计并在 `exa_status` 与设置页显示；Agent 运行只在到达终态时记一次，轮询不会重复计数。注意 OAuth 走 MCP 时搜索响应不带费用字段，所以账号模式的估算只覆盖 Agent 运行；进程重启后从 0 开始。
+**费用估算**。Exa 在 REST 计费响应中返回 `costDollars.total`，插件按进程累计，并在 `exa_status` 与设置页中显示；Agent 运行仅在到达终态时记录一次，轮询不会重复计数。OAuth 模式下搜索响应不包含费用字段，因此该模式的估算仅覆盖 Agent 运行；进程重启后从 0 开始。
 
 ## 安装
 
-在 Harness 的插件管理里安装本目录，或从 npm 安装发布后的包（`dsh-exa-search`）。
-以本地目录安装时，profile 里保存的是链接而不是拷贝——移动或删除源目录会让插件失效。
+可通过 Harness 插件管理安装本目录，或从 npm 安装 `dsh-exa-search`。
+使用本地目录安装时，profile 中保存的是链接而非副本；移动或删除源目录会导致插件失效。
 
-安装后 `web` 行被 pin 到 `exa` provider（见 `cordis.patch.yml`）——这是必须的：同时存在两个可用搜索 provider 时，`ctx.web` 会以 `WEB_PROVIDER_AMBIGUOUS` 拒绝选择，而不是猜。
+安装后，`web` 行会被固定到 `exa` provider（见 `cordis.patch.yml`）。这是必要配置：当存在两个可用搜索 provider 时，`ctx.web` 会以 `WEB_PROVIDER_AMBIGUOUS` 拒绝选择，而不会自动猜测。
 
 ## 配置
 
-`cordis.patch.yml` 里的行配置：
+`cordis.patch.yml` 中的行配置：
 
 | 键 | 默认 | 说明 |
 | --- | --- | --- |
 | `mode` | `keyless` | 首次运行的默认接入方式；设置页会覆盖它。 |
-| `apiKeyEnv` | `EXA_API_KEY` | 没有保存 Key 时读取的环境变量。 |
+| `apiKeyEnv` | `EXA_API_KEY` | 未保存 Key 时读取的环境变量。 |
 | `numResults` | `8` | 默认返回来源数。 |
 | `searchType` | `auto` | 检索强度：`auto` / `lite` / `fast`。 |
 | `maxCharacters` | `12000` | 单页抓取字符上限。 |
 | `locale` | `auto` | 消息语言：`auto` 跟随系统，或强制 `en` / `zh`。 |
 | `mcpTools` | `null` | 覆盖 MCP 的 `tools` 列表（数组或逗号分隔字符串）。 |
-| `toolGroups` | `null` | 分组开关的初始值，例如 `{ "answer": false, "webset": false }`；设置页的改动存进 state 并覆盖它。 |
-
-设置页每个分组右侧有一个开关，关掉后该组的 `exa_*` 工具立刻从模型工具表里移除；`web_search` / `web_fetch` 的改道不受影响。设置页顶部还有「测试连接」按钮，会用当前方式跑一次最小搜索并返回耗时与示例结果（消耗一次搜索）。
-
-## 数据落在哪
-
-- 接入方式、OAuth 客户端注册信息：`<DSH_HOME>/exa-search/state.json`。
-  Host 进程不保证有 `DSH_PROFILE_DIR`，所以这份状态按用户存放，而不是按 profile。
-- API Key 与 OAuth 令牌：Harness 凭据服务（`ctx.credentials`），记录键为 `exa-search/api-key`、`exa-search/oauth`；
-  只有凭据服务不可用时才退回上面的 `state.json`（文件权限 0600）。
-- 插件不会把任何凭据写进安装目录，也不会随包分发状态文件。
-
-> **如果你装过 1.0.0 之前的本地开发版**：旧版把凭据写成 `exa-api-key` / `exa-oauth`，而 Harness 的凭据服务只接受 `<scope>/<id>`，会在下次启动时解析失败并让整个应用起不来。关闭应用后运行下面的修复脚本，或手动改名/删除这两条记录。
-
-## 启动崩溃后的修复
+| `toolGroups` | `null` | 分组开关的初始值，例如 `{ "answer": false, "webset": false }`；设置页的改动存入 state 并覆盖它。 |
 
-如果 Harness 报 `credential key "..." must be "<scope>/<id>"` 而无法启动，先完全退出应用，再运行：
+设置页中每个分组右侧均有开关；关闭后，该分组下的 `exa_*` 工具会立即从模型工具表中移除，`web_search` / `web_fetch` 的 Exa 改道不受影响。设置页顶部的「测试连接」按钮会使用当前接入方式执行一次最小搜索，并返回耗时与示例结果（消耗一次搜索）。
 
-```bash
-node scripts/repair-credentials.mjs --dry-run   # 预演，只打印会改什么
-node scripts/repair-credentials.mjs             # 备份并把两个旧键改成 exa-search/*
-```
+## 数据与凭据
 
-脚本只动这两条记录键，写入前在同目录留一份 `.bak-<时间戳>`；如果新旧键同时存在会拒绝猜测并退出。默认路径是 `<DSH_HOME>/.credentials.yaml`，可用 `DSH_HOME` 或 `DSH_CREDENTIALS` 覆盖，也可以 `npm run repair-credentials`。
+- 接入方式与 OAuth 客户端注册信息：`<DSH_HOME>/exa-search/state.json`。Host 进程不保证存在 `DSH_PROFILE_DIR`，因此该状态按用户存储，而非按 profile。
+- API Key 与 OAuth 令牌：Harness 凭据服务（`ctx.credentials`），记录键为 `exa-search/api-key`、`exa-search/oauth`；仅当凭据服务不可用时，才退回上述 `state.json`（文件权限 0600）。
+- 插件不会将任何凭据写入安装目录，也不会随包分发状态文件。
 
 ## 路由
 
 设置页通过同源路由读写 Host，避免为纯 JS 插件生成 Remote 命名空间：
 
-- `GET  /exa-plugin/state` — 当前方式、凭据状态、上游工具表、工具矩阵、各方式计数；
-- `POST /exa-plugin/mode` / `api-key` / `login` / `logout` — 变更操作，拒绝跨源请求；
-- `GET  /exa-plugin/oauth/callback` — OAuth 回调。
+- `GET /exa-plugin/state` — 当前方式、凭据状态、上游工具表、工具矩阵与各方式计数；
+- `GET /exa-plugin/diagnostics` — 脱敏诊断快照，用于问题反馈；
+- `POST /exa-plugin/mode` / `api-key` / `login` / `logout` / `tools` / `test` — 变更操作，拒绝跨源请求；
+- `GET /exa-plugin/oauth/callback` — OAuth 回调。
 
-## 没覆盖的部分
+## 未覆盖范围
 
-Team Management、Webhooks/Events、Imports 属于账号与事件投递的底层接口，不注册为模型工具；检索、内容、问答、研究、监控、数据集、批量这条链路已经完整。
+Team Management、Webhooks / Events、Imports 属于账号与事件投递的底层接口，不注册为模型工具；检索、内容、问答、研究、监控、数据集、批量这条链路已经完整。
 
 ## 卸载
 

package/index.js

@@ -25,9 +25,16 @@ import path from 'node:path'
 import os from 'node:os'
 import { createHash, randomBytes } from 'node:crypto'
 
-// Read once at load; readFileSync (unlike require) does not keep a module-cache
-// entry, so a plugin reload after a version bump reports the current version.
-const PKG = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'))
+// Read on demand: the Host may keep this module cached across plugin reloads,
+// so a version baked in at load time can go stale after a bump.
+function packageInfo() {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'))
+    return { name: typeof pkg.name === 'string' ? pkg.name : 'dsh-exa-search', version: String(pkg.version || 'unknown') }
+  } catch {
+    return { name: 'dsh-exa-search', version: 'unknown' }
+  }
+}
 
 export const name = 'exa-search'
 export const inject = ['web', 'tools']
@@ -1625,7 +1632,7 @@ export function apply(ctx, config = {}) {
   async function diagnosticsPayload() {
     const payload = await statePayload()
     return {
-      plugin: { name: PKG.name, version: PKG.version },
+      plugin: packageInfo(),
       generatedAt: new Date().toISOString(),
       locale: activeLocale,
       mode: payload.mode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-exa-search",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Exa-powered web search for DeepSeek Harness: keyless free tier, your own API key, or a signed-in Exa account, with a settings page that shows which Exa tools each mode exposes.",
   "type": "module",
   "license": "MIT",
@@ -15,8 +15,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test",
-    "repair-credentials": "node scripts/repair-credentials.mjs"
+    "test": "node --test"
   },
   "exports": {
     ".": "./index.js",
@@ -33,8 +32,7 @@
     "README.md",
     "README.en.md",
     "LICENSE",
-    "CHANGELOG.md",
-    "scripts/repair-credentials.mjs"
+    "CHANGELOG.md"
   ],
   "dsh": {
     "bundle": {

package/scripts/repair-credentials.mjs

@@ -1,101 +0,0 @@
-#!/usr/bin/env node
-/**
- * Repair credential record keys written by pre-release local builds of
- * dsh-exa-search (the old keys were `exa-api-key` / `exa-oauth`).
- *
- * Older builds stored `exa-api-key` / `exa-oauth`. The Harness credential
- * service only accepts `<scope>/<id>`, and a single bad key makes the whole
- * vault fail to parse at startup — the app then refuses to launch.
- *
- * Usage:
- *   node scripts/repair-credentials.mjs --dry-run
- *   node scripts/repair-credentials.mjs
- *
- * The file is backed up next to the original before anything is written.
- * Override the location with DSH_CREDENTIALS, or the home directory with
- * DSH_HOME.
- */
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-const RENAMES = [
-  ['exa-api-key', 'exa-search/api-key'],
-  ['exa-oauth', 'exa-search/oauth'],
-]
-
-const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-
-/**
- * Compute the repaired document without touching the filesystem.
- * Returns `{ text, changes, conflicts }`; a conflict means both the old and the
- * scoped key exist, which needs a human decision.
- */
-export function planRepair(text) {
-  const source = String(text)
-  const lines = source.split(/\r?\n/)
-  const present = new Set()
-  for (const line of lines) {
-    const match = line.match(/^\s{2}([^\s:#][^:]*):\s*$/)
-    if (match) present.add(match[1].trim())
-  }
-
-  const conflicts = []
-  for (const [from, to] of RENAMES) {
-    if (present.has(from) && present.has(to)) conflicts.push({ from, to })
-  }
-  if (conflicts.length) return { text: source, changes: [], conflicts }
-
-  const changes = []
-  for (const [from, to] of RENAMES) {
-    if (present.has(from)) changes.push({ from, to })
-  }
-
-  let next = source
-  for (const { from, to } of changes) {
-    next = next.replace(new RegExp(`^(\\s{2})${escapeRegExp(from)}:\\s*$`, 'm'), `$1${to}:`)
-  }
-  return { text: next, changes, conflicts }
-}
-
-function main() {
-  const dryRun = process.argv.includes('--dry-run')
-  const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
-  const file = process.env.DSH_CREDENTIALS || path.join(home, '.credentials.yaml')
-
-  if (!existsSync(file)) {
-    console.error(`No credentials file at ${file}`)
-    process.exit(1)
-  }
-
-  const original = readFileSync(file, 'utf8')
-  const plan = planRepair(original)
-
-  if (plan.conflicts.length) {
-    for (const { from, to } of plan.conflicts) {
-      console.error(`Both "${from}" and "${to}" exist; resolve this by hand first.`)
-    }
-    process.exit(2)
-  }
-
-  if (!plan.changes.length) {
-    console.log('Nothing to repair: no legacy credential keys found.')
-    return
-  }
-
-  for (const { from, to } of plan.changes) {
-    console.log(`${dryRun ? 'would rename' : 'rename'} ${from} -> ${to}`)
-  }
-  if (dryRun) return
-
-  const backup = `${file}.bak-${Date.now()}`
-  copyFileSync(file, backup)
-  writeFileSync(file, plan.text, { mode: 0o600 })
-  console.log(`Backup written to ${backup}`)
-  console.log('Done. Start DeepSeek Harness again.')
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  main()
-}