dsh-exa-tools 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.en-US.md +149 -0
- package/README.md +148 -2
- package/client.js +468 -0
- package/cordis.patch.yml +4 -0
- package/docs/TECHNICAL.en-US.md +220 -0
- package/docs/TECHNICAL.md +219 -0
- package/icon.svg +28 -0
- package/index.js +296 -0
- package/lib/exa-mcp.js +151 -0
- package/lib/exa-rest.js +71 -0
- package/lib/format.js +155 -0
- package/lib/http.js +70 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +68 -4
- package/pnpm-workspace.yaml +5 -0
- package/scripts/apply-test.mjs +74 -0
- package/scripts/client-test.mjs +111 -0
- package/scripts/smoke.mjs +84 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dsh-exa-tools contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.en-US.md
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# dsh-exa-tools
|
|
2
|
+
|
|
3
|
+
Exa web search and fetch tools for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). Adds two tools to every agent in the profile:
|
|
4
|
+
|
|
5
|
+
- **`exa_search`** — semantic web search: describe the ideal page in natural language, get back source URLs with titles and relevant excerpts.
|
|
6
|
+
- **`exa_fetch`** — read any webpage through Exa as clean text/markdown.
|
|
7
|
+
|
|
8
|
+
**No API key? It just works.** Without a key the tools use Exa's free hosted MCP endpoint (`mcp.exa.ai`, rate-limited). With a key they call the official Exa REST API (`api.exa.ai`) with your account's limits. Enter the key once under **Settings → Exa tools** — no config files, no restart.
|
|
9
|
+
|
|
10
|
+
[中文文档](README.md) · [Technical documentation](docs/TECHNICAL.en-US.md) · [技术文档](docs/TECHNICAL.md)
|
|
11
|
+
|
|
12
|
+
## Requirements
|
|
13
|
+
|
|
14
|
+
- DeepSeek Harness `>=0.1.7-rc.1` (Desktop or Web profile). The required APIs were verified against the published sources of every release line from 0.1.7-rc.1 to 0.2.2-rc.5, and fully exercised on 0.2.2-rc.5; no upper bound. The settings-page navigation icon needs `>=0.2.2-rc.1`; older releases show the default glyph. See [Version compatibility](docs/TECHNICAL.en-US.md#10-version-compatibility).
|
|
15
|
+
- Node.js `>=20.3` for the plugin code itself (global `fetch`, `AbortSignal.any/timeout`). DSH's own runtime requirement may be higher — current DSH ships Node 24.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
**Option 1: npm (recommended)**
|
|
20
|
+
|
|
21
|
+
**Plugins** → **Add plugin** → enter the package name `dsh-exa-tools`.
|
|
22
|
+
|
|
23
|
+
**Option 2: download a Release**
|
|
24
|
+
|
|
25
|
+
1. Grab the latest `dsh-exa-tools-<version>.tgz` from [Releases](https://github.com/Vikrant-Aleph/dsh-exa-tools/releases)
|
|
26
|
+
2. DSH sidebar **Plugins** → **Add plugin** → pick the tgz file (or paste the Release asset URL)
|
|
27
|
+
|
|
28
|
+
**Option 3: Git URL / local directory (developers)**
|
|
29
|
+
|
|
30
|
+
- Git URL: `https://github.com/Vikrant-Aleph/dsh-exa-tools.git`
|
|
31
|
+
- Local directory: `D:\path\to\dsh-exa-tools` (or `/path/to/dsh-exa-tools`)
|
|
32
|
+
- Or ask the agent: “install the plugin at `D:\path\to\dsh-exa-tools`”
|
|
33
|
+
|
|
34
|
+
> **Local directory installs:** DSH links the checkout instead of copying it. Run `pnpm install` (or `npm install`) in the project directory once before installing, so the plugin's `@deepseek-ai/schemastery` dependency resolves. The project uses a hoisted `node_modules` layout on purpose — see [Technical documentation](docs/TECHNICAL.en-US.md#module-resolution).
|
|
35
|
+
|
|
36
|
+
After installation the plugin is enabled immediately (HMR). Open a **new session** and the two tools are available to the agent.
|
|
37
|
+
|
|
38
|
+
## Set up the API key (optional)
|
|
39
|
+
|
|
40
|
+
1. Sidebar **Settings** → **Exa tools** (the plugin's page under **Plugins** carries the same form).
|
|
41
|
+
2. Paste your key into **API key** and press **Save**. Get a key at [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys).
|
|
42
|
+
3. The status line flips from *Free mode* to *API mode*. Changes apply to the next tool call — no restart.
|
|
43
|
+
|
|
44
|
+
**Clear API key** on the same page switches back to the free endpoint.
|
|
45
|
+
|
|
46
|
+
Without a key everything works out of the box on Exa's free tier; the free endpoint is rate-limited, and a rate-limit error tells the model (and you) to add a key.
|
|
47
|
+
|
|
48
|
+
### Where the key lives
|
|
49
|
+
|
|
50
|
+
The key is stored in your profile's `cordis.patch.yml` (the same place as other plugin settings). It is a *write-only secret* in the UI: DSH never sends the stored value back to the client — the input only shows whether a key is configured. Treat the profile directory like any other credential store: it is plain text on disk, protected by your OS user permissions.
|
|
51
|
+
|
|
52
|
+
## Tools
|
|
53
|
+
|
|
54
|
+
### `exa_search`
|
|
55
|
+
|
|
56
|
+
| Parameter | Type | Description |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| `query` | string, required | Natural-language description of the page you want to find, e.g. `"blog post comparing React and Vue performance"` — not keyword strings. |
|
|
59
|
+
| `num_results` | integer, optional | Results to return (default 5, capped by `searchMaxResults`, default 10). |
|
|
60
|
+
|
|
61
|
+
Returns a source list: `- [title](url) — excerpt (publishedDate)`, each excerpt capped at 800 characters, with the standing notice that results are external, untrusted data and should be cited as markdown links.
|
|
62
|
+
|
|
63
|
+
### `exa_fetch`
|
|
64
|
+
|
|
65
|
+
| Parameter | Type | Description |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| `url` | string, required | Absolute `http(s)` URL of the page to read. |
|
|
68
|
+
| `max_characters` | integer, optional | Page characters to return (default 20 000, capped by `fetchMaxCharacters`, default 50 000). |
|
|
69
|
+
|
|
70
|
+
Returns `Fetched <url>` plus the page body as clean text/markdown. Truncated content is marked so the model can fetch a more specific section.
|
|
71
|
+
|
|
72
|
+
Both tools coexist with DSH's built-in `web_search` / `web_fetch`; the system prompt tells the model what each returns and to treat the content as untrusted data.
|
|
73
|
+
|
|
74
|
+
## Configuration
|
|
75
|
+
|
|
76
|
+
The settings page (Settings → Exa tools) edits the live fields: API key, `searchMaxResults`, `fetchMaxCharacters`, `searchTimeoutMs`, `fetchTimeoutMs`. Deployment-level fields are edited in the profile's `cordis.patch.yml`:
|
|
77
|
+
|
|
78
|
+
```yaml
|
|
79
|
+
- id: exa-tools
|
|
80
|
+
name: dsh-exa-tools
|
|
81
|
+
config:
|
|
82
|
+
search: true # register exa_search
|
|
83
|
+
fetch: true # register exa_fetch
|
|
84
|
+
apiBaseUrl: https://api.exa.ai
|
|
85
|
+
mcpBaseUrl: https://mcp.exa.ai/mcp
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
| Field | Default | Editable on plugin page | Meaning |
|
|
89
|
+
|---|---|---|---|
|
|
90
|
+
| `apiKey` | *(empty)* | yes (write-only) | Exa API key; empty = free MCP endpoint |
|
|
91
|
+
| `searchMaxResults` | `10` | yes | Cap on sources per search (1–50) |
|
|
92
|
+
| `fetchMaxCharacters` | `50000` | yes | Cap on page characters per fetch (1 000–500 000) |
|
|
93
|
+
| `searchTimeoutMs` | `30000` | yes | Per-call search budget (ms) |
|
|
94
|
+
| `fetchTimeoutMs` | `60000` | yes | Per-call fetch budget (ms) |
|
|
95
|
+
| `search` / `fetch` | `true` | no (YAML) | Register each tool |
|
|
96
|
+
| `apiBaseUrl` / `mcpBaseUrl` | official endpoints | no (YAML) | Override for proxies or self-hosted MCP |
|
|
97
|
+
|
|
98
|
+
## Development
|
|
99
|
+
|
|
100
|
+
Plain ESM JavaScript — no build step.
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
index.js Host plugin: Config schema + tool registration
|
|
104
|
+
lib/http.js fetch with fused timeout/cancellation; REST error mapping
|
|
105
|
+
lib/exa-mcp.js minimal MCP streamable-HTTP client (free endpoint)
|
|
106
|
+
lib/exa-rest.js Exa REST client (/search, /contents)
|
|
107
|
+
lib/format.js MCP text parsing, canonical outputs, model-facing rendering
|
|
108
|
+
client.js client half: settings page + Plugins-page card (Web and Desktop)
|
|
109
|
+
cordis.patch.yml bundle patch inserting the exa-tools row
|
|
110
|
+
locale/ plugin display metadata (en, zh)
|
|
111
|
+
scripts/smoke.mjs backend smoke test against the live endpoints
|
|
112
|
+
scripts/apply-test.mjs integration test: apply() + execute() via a mock context
|
|
113
|
+
scripts/client-test.mjs client test: slot registrations + settings page render
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
pnpm install # once; hoisted layout (see pnpm-workspace.yaml)
|
|
118
|
+
pnpm smoke # free endpoint search + fetch, REST 401 error path
|
|
119
|
+
pnpm smoke:api # real REST calls; needs EXA_API_KEY in the environment
|
|
120
|
+
pnpm test:apply # registration, validation, both backends, rendering
|
|
121
|
+
pnpm test:client # settings page / nav icon / card registrations
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
See [docs/TECHNICAL.en-US.md](docs/TECHNICAL.en-US.md) for the architecture: bundle layout, the native tool-definition contract, the MCP handshake, secret redaction, and the settings transport.
|
|
125
|
+
|
|
126
|
+
## Limitations
|
|
127
|
+
|
|
128
|
+
- The free endpoint is rate-limited and shared; heavy use needs an API key.
|
|
129
|
+
- Search excerpts are capped (800 chars/source); use `exa_fetch` for full pages.
|
|
130
|
+
- Fetch truncation is detected by length reaching the requested budget, so an exactly-sized page may be marked truncated.
|
|
131
|
+
- The API key is stored in the profile patch (plain text on disk); DSH's credentials service is not used in this version.
|
|
132
|
+
- No `EXA_API_KEY` environment fallback yet — the key comes from the plugin page or the profile patch.
|
|
133
|
+
|
|
134
|
+
## Publishing
|
|
135
|
+
|
|
136
|
+
Pushing a `v*` version tag releases automatically: GitHub Actions verifies the tag matches `package.json`, installs dependencies, runs the client tests, packs the tarball, and creates a GitHub Release with the asset attached.
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
# 1. Bump version in package.json, commit and push
|
|
140
|
+
git tag v0.1.1
|
|
141
|
+
git push origin v0.1.1
|
|
142
|
+
# 2. Actions creates the Release (with tgz); also publishes to npm when NPM_TOKEN is set
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
One-time setup for npm publishing: add an `NPM_TOKEN` secret (an npmjs.com Automation token) under **Settings → Secrets and variables → Actions**. Without it the workflow skips npm and only creates the Release.
|
|
146
|
+
|
|
147
|
+
## License
|
|
148
|
+
|
|
149
|
+
[MIT](LICENSE)
|
package/README.md
CHANGED
|
@@ -1,3 +1,149 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-exa-tools
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH)接入 Exa 搜索的插件,为 profile 中的每个 agent 增加两个工具:
|
|
4
|
+
|
|
5
|
+
- **`exa_search`** —— 语义化网页搜索:用自然语言描述你想找的页面,返回来源 URL、标题和相关摘录。
|
|
6
|
+
- **`exa_fetch`** —— 通过 Exa 抓取任意网页,返回干净的正文(text/markdown)。
|
|
7
|
+
|
|
8
|
+
**没有 API Key 也能直接用。** 未填 Key 时走 Exa 免费托管 MCP 端点(`mcp.exa.ai`,有速率限制);填了 Key 则走 Exa 官方 REST API(`api.exa.ai`),使用你账户的限额。Key 只需在「设置 → Exa 搜索」填一次,不用改配置文件,不用重启。
|
|
9
|
+
|
|
10
|
+
[English](README.en-US.md) · [技术文档](docs/TECHNICAL.md) · [Technical documentation](docs/TECHNICAL.en-US.md)
|
|
11
|
+
|
|
12
|
+
## 环境要求
|
|
13
|
+
|
|
14
|
+
- DeepSeek Harness `>=0.1.7-rc.1`(Desktop 或 Web profile)。已对照 0.1.7-rc.1 至 0.2.2-rc.5 各发布线的源码核实所需 API 齐备,并在 0.2.2-rc.5 上完整实测;不设上限。设置页的导航图标需要 `>=0.2.2-rc.1`,更老版本显示默认图标。详见[技术文档的版本兼容一节](docs/TECHNICAL.md#10-版本兼容)。
|
|
15
|
+
- 插件代码本身需要 Node.js `>=20.3`(全局 `fetch`、`AbortSignal.any/timeout`)。DSH 自身的运行时要求可能更高——当前 DSH 自带 Node 24。
|
|
16
|
+
|
|
17
|
+
## 安装
|
|
18
|
+
|
|
19
|
+
**方式一:npm 安装(推荐)**
|
|
20
|
+
|
|
21
|
+
「插件」→「添加插件」,直接填包名 `dsh-exa-tools`。
|
|
22
|
+
|
|
23
|
+
**方式二:下载 Release 安装**
|
|
24
|
+
|
|
25
|
+
1. 到 [Releases](https://github.com/Vikrant-Aleph/dsh-exa-tools/releases) 下载最新版的 `dsh-exa-tools-<版本>.tgz`
|
|
26
|
+
2. DSH 侧边栏「插件」→「添加插件」,选择该 tgz 文件(或直接粘贴 Release 附件的 URL)
|
|
27
|
+
|
|
28
|
+
**方式三:Git 地址 / 本地目录(开发者)**
|
|
29
|
+
|
|
30
|
+
- Git 地址:`https://github.com/Vikrant-Aleph/dsh-exa-tools.git`
|
|
31
|
+
- 本地目录:`D:\path\to\dsh-exa-tools`(或 `/path/to/dsh-exa-tools`)
|
|
32
|
+
- 也可以直接让 agent 安装,例如「安装 `D:\path\to\dsh-exa-tools` 这个插件」
|
|
33
|
+
|
|
34
|
+
> **本地目录安装注意:** DSH 以链接(link)方式引用你的 checkout,而不是复制。安装前请先在项目目录里执行一次 `pnpm install`(或 `npm install`),让插件依赖的 `@deepseek-ai/schemastery` 可解析。项目刻意使用 hoisted 的 `node_modules` 布局,原因见[技术文档](docs/TECHNICAL.md#模块解析)。
|
|
35
|
+
|
|
36
|
+
安装后插件立即启用(HMR)。**新开一个会话**,agent 就能调用这两个工具。
|
|
37
|
+
|
|
38
|
+
## 填写 API Key(可选)
|
|
39
|
+
|
|
40
|
+
1. 侧边栏「设置」→「Exa 搜索」(「插件」页的本插件详情里也有同样的表单)。
|
|
41
|
+
2. 在 **API Key** 输入框粘贴密钥,点「保存」。密钥在 [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys) 获取。
|
|
42
|
+
3. 状态行从「免费模式」变为「API 模式」。下一次工具调用即生效,无需重启。
|
|
43
|
+
|
|
44
|
+
同一页面上的「清除 API Key」可切回免费端点。
|
|
45
|
+
|
|
46
|
+
不填 Key 时开箱即用(Exa 免费额度);免费端点有速率限制,触发限流时错误信息会提示填写 Key。
|
|
47
|
+
|
|
48
|
+
### Key 存在哪里
|
|
49
|
+
|
|
50
|
+
Key 保存在 profile 的 `cordis.patch.yml` 中(与其他插件设置同一位置)。它在界面上是**只写密钥**:DSH 从不把已保存的值回传给客户端,输入框只显示「是否已配置」。请像对待其他凭据文件一样对待 profile 目录:磁盘上是明文,安全性取决于你的系统用户权限。
|
|
51
|
+
|
|
52
|
+
## 工具说明
|
|
53
|
+
|
|
54
|
+
### `exa_search`
|
|
55
|
+
|
|
56
|
+
| 参数 | 类型 | 说明 |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| `query` | string,必填 | 用自然语言描述想找的页面,例如「对比 React 和 Vue 性能的博客文章」,不要只写关键词。 |
|
|
59
|
+
| `num_results` | integer,可选 | 返回条数(默认 5,上限由 `searchMaxResults` 控制,默认 10)。 |
|
|
60
|
+
|
|
61
|
+
返回来源列表:`- [标题](url) — 摘录 (发布日期)`,每条摘录最多 800 字符,并附带固定提示:结果为外部不可信数据,引用时请用 markdown 链接。
|
|
62
|
+
|
|
63
|
+
### `exa_fetch`
|
|
64
|
+
|
|
65
|
+
| 参数 | 类型 | 说明 |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| `url` | string,必填 | 要读取的页面绝对 `http(s)` URL。 |
|
|
68
|
+
| `max_characters` | integer,可选 | 返回的正文字符数(默认 20 000,上限由 `fetchMaxCharacters` 控制,默认 50 000)。 |
|
|
69
|
+
|
|
70
|
+
返回 `Fetched <url>` 加干净正文。内容被截断时会标注,模型可据此抓取更具体的章节。
|
|
71
|
+
|
|
72
|
+
两个工具与 DSH 内置的 `web_search` / `web_fetch` 并存;系统提示词会告诉模型各自的用途,并把返回内容视为不可信数据。
|
|
73
|
+
|
|
74
|
+
## 配置项
|
|
75
|
+
|
|
76
|
+
设置页(设置 → Exa 搜索)可实时修改:API Key、`searchMaxResults`、`fetchMaxCharacters`、`searchTimeoutMs`、`fetchTimeoutMs`。部署级字段在 profile 的 `cordis.patch.yml` 中编辑:
|
|
77
|
+
|
|
78
|
+
```yaml
|
|
79
|
+
- id: exa-tools
|
|
80
|
+
name: dsh-exa-tools
|
|
81
|
+
config:
|
|
82
|
+
search: true # 注册 exa_search
|
|
83
|
+
fetch: true # 注册 exa_fetch
|
|
84
|
+
apiBaseUrl: https://api.exa.ai
|
|
85
|
+
mcpBaseUrl: https://mcp.exa.ai/mcp
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
| 字段 | 默认值 | 插件页可改 | 含义 |
|
|
89
|
+
|---|---|---|---|
|
|
90
|
+
| `apiKey` | *(空)* | 是(只写) | Exa API Key;空 = 免费 MCP 端点 |
|
|
91
|
+
| `searchMaxResults` | `10` | 是 | 单次搜索来源上限(1–50) |
|
|
92
|
+
| `fetchMaxCharacters` | `50000` | 是 | 单次抓取字符上限(1 000–500 000) |
|
|
93
|
+
| `searchTimeoutMs` | `30000` | 是 | 单次搜索超时(毫秒) |
|
|
94
|
+
| `fetchTimeoutMs` | `60000` | 是 | 单次抓取超时(毫秒) |
|
|
95
|
+
| `search` / `fetch` | `true` | 否(YAML) | 是否注册对应工具 |
|
|
96
|
+
| `apiBaseUrl` / `mcpBaseUrl` | 官方端点 | 否(YAML) | 代理或自建 MCP 时覆盖 |
|
|
97
|
+
|
|
98
|
+
## 开发
|
|
99
|
+
|
|
100
|
+
纯 ESM JavaScript,无构建步骤。
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
index.js Host 插件:Config schema + 工具注册
|
|
104
|
+
lib/http.js 融合超时/取消的 fetch;REST 错误映射
|
|
105
|
+
lib/exa-mcp.js 极简 MCP streamable-HTTP 客户端(免费端点)
|
|
106
|
+
lib/exa-rest.js Exa REST 客户端(/search、/contents)
|
|
107
|
+
lib/format.js MCP 文本解析、规范化输出、面向模型的渲染
|
|
108
|
+
client.js 客户端:设置页 + Plugins 页卡片(Web/桌面通用)
|
|
109
|
+
cordis.patch.yml 插入 exa-tools 行的 bundle patch
|
|
110
|
+
locale/ 插件显示元数据(en、zh)
|
|
111
|
+
scripts/smoke.mjs 后端冒烟测试(真实端点)
|
|
112
|
+
scripts/apply-test.mjs 集成测试:mock context 下 apply() + execute()
|
|
113
|
+
scripts/client-test.mjs 客户端测试:插槽注册 + 设置页渲染
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
pnpm install # 首次;hoisted 布局(见 pnpm-workspace.yaml)
|
|
118
|
+
pnpm smoke # 免费端点搜索 + 抓取,REST 401 错误路径
|
|
119
|
+
pnpm smoke:api # 真实 REST 调用;需要环境里有 EXA_API_KEY
|
|
120
|
+
pnpm test:apply # 注册、参数校验、双后端、渲染
|
|
121
|
+
pnpm test:client # 设置页 / 导航图标 / 卡片注册
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
架构细节(bundle 结构、原生工具定义契约、MCP 握手、密钥脱敏、settings 传输)见[技术文档](docs/TECHNICAL.md)。
|
|
125
|
+
|
|
126
|
+
## 已知限制
|
|
127
|
+
|
|
128
|
+
- 免费端点有速率限制且为共享额度,重度使用需要 API Key。
|
|
129
|
+
- 搜索摘录有上限(每条 800 字符);需要全文请用 `exa_fetch`。
|
|
130
|
+
- 抓取截断按「长度达到请求预算」判断,恰好等长的页面可能被标记为截断。
|
|
131
|
+
- API Key 存于 profile patch(磁盘明文);本版本未使用 DSH 的 credentials 服务。
|
|
132
|
+
- 暂不支持 `EXA_API_KEY` 环境变量回退——Key 来自插件页面或 profile patch。
|
|
133
|
+
|
|
134
|
+
## 发布
|
|
135
|
+
|
|
136
|
+
推送 `v*` 版本标签即自动发布:GitHub Actions 会校验标签与 `package.json` 版本一致、安装依赖、跑客户端测试、打包 tgz,并创建带附件的 GitHub Release。
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
# 1. 修改 package.json 的 version,提交并推送
|
|
140
|
+
git tag v0.1.1
|
|
141
|
+
git push origin v0.1.1
|
|
142
|
+
# 2. Actions 自动建 Release(附 tgz);配置了 NPM_TOKEN 时同步发布 npm
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
npm 自动发布的一次性准备:仓库 **Settings → Secrets and variables → Actions** 新增 `NPM_TOKEN`(npmjs.com 的 Automation token)。未配置时 workflow 自动跳过 npm 发布,只建 Release。
|
|
146
|
+
|
|
147
|
+
## 许可证
|
|
148
|
+
|
|
149
|
+
[MIT](LICENSE)
|