dsh-web-search-plugin 0.2.0 → 0.3.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.
Files changed (12) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/README.md +118 -47
  3. package/cordis.patch.yml +1 -1
  4. package/lib/brave.js +1 -0
  5. package/lib/client.js +657 -96
  6. package/lib/index.js +195 -12
  7. package/lib/providers.js +212 -0
  8. package/lib/rest.js +325 -0
  9. package/lib/shared.js +1 -1
  10. package/lib/tavily.js +10 -2
  11. package/lib/usage.js +352 -0
  12. package/package.json +3 -3
package/CHANGELOG.md CHANGED
@@ -2,6 +2,52 @@
2
2
 
3
3
  本项目的重要变更都记录在此。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
4
4
 
5
+ ## [0.3.0] - 2026-08-25
6
+
7
+ ### 新增
8
+
9
+ - **内置 REST provider 元数据化**（`lib/providers.js` 静态表 + `lib/rest.js` 通用后端）：内置 REST 供应商由单一元数据表驱动，新增即"表里加一行 + 官方跳转链接"，零定制执行代码。
10
+ - 新增内置 provider：**Serper / SerpApi / Exa / SearXNG / Scavio / Firecrawl**（`provider` 值 `serper` / `serpapi` / `exa` / `searxng` / `scavio` / `firecrawl`）。
11
+ - Firecrawl 响应 `data.web[]` 走专用 `firecrawl` 解析分支；Scavio 复用 `organic_results` 解析。
12
+ - DuckDuckGo 无官方 API：下拉以禁用项提示经 SearXNG 使用，不提供独立后端。
13
+ - 元数据字段：`method`（GET/POST）/ `queryIn`（query-string / body）/ `queryParam` / `countParam` / `params[]`（`when: always` / `nonEmpty` / `keyed` / `keyless`，受限谓词清单）/ `auth.type`（bearer / header / none / **query**）/ `response` / `hooks` / `officialUrl`。
14
+ - 通用后端 `RestSearchProvider` 接管 brave / tavily / serper / serpapi / exa / searxng / scavio / firecrawl；`deepseek-official`（模型工具型）仍走专用 `lib/deepseek.js`。
15
+ - Tavily 额度回传、Brave 限流头/代理作为可选 hook 注入，通用体不写死业务逻辑。
16
+ - 设置卡对需要 key 的内置 provider 渲染「获取 API key ↗」跳官方控制台；免 key 的（SearXNG / Tavily keyless）不渲染。
17
+
18
+ ### 变更
19
+
20
+ - **默认引擎从 `tavily` 改为 `deepseek-official`**：schema 默认、服务端/客户端回退、bundle patch 初始值一致改为官方默认（已保存的显式 `provider` 不被覆盖）。
21
+ - `provider` 取值扩展为 `tavily` / `brave` / `deepseek-official` / `serper` / `serpapi` / `exa` / `searxng` / `scavio` / `firecrawl`。
22
+ - **修复 Tavily `include_answer` 类型错误**：`params[]` 布尔值不再强转字符串，请求体发真布尔（`true`/`false`），兼容 Tavily API 对 `include_answer` / `include_images` / `include_usage` 的类型要求。
23
+ - **修复 SearXNG 卡片误显「获取 API key ↗」**：仅需要 key 的 provider 才显示获取 key 跳转，免 key 的（SearXNG / Tavily keyless）不显示。
24
+ - **收紧未配置 key 的提示文案**：placeholder 缩短为「未配置密钥」，补充说明移至输入框下方提示，避免溢出。以下未纳入内置：TinyFish、Google CSE、SERPJET（官网不可访问）、DuckDuckGo（无官方 API，经 SearXNG 使用）。
25
+
26
+ ## [0.2.1] - 2026-08-18
27
+
28
+ 相对 0.2.0 的补丁：设置卡补上额度进度条、两列布局和输入校验，并收紧空态文案。
29
+
30
+ ### 新增
31
+
32
+ - 设置导航「网页搜索」补上地球 logo（与 dsh-credits 相同的 nav mask 做法）。
33
+ - **Tavily keyed 额度**：搜索请求带 `include_usage`，把本次 credits 累加到本地高水位；每 10 分钟拉一次 `GET /usage`（计划名 / `plan_limit`），显示 `max(本地, 远端)`。换计划或远端用量回落视为新周期。
34
+ - **Brave 额度**：从搜索响应的 `X-RateLimit-*` 解析月配额、剩余量和重置时间，写入本地缓存。
35
+ - 设置卡在搜索引擎切换下方展示进度条（已用/剩余、重置时间、绿/黄/红提醒）。DeepSeek 官方与 Tavily keyless 不展示。
36
+
37
+ ### 变更
38
+
39
+ - 设置卡同一区域的短配置改为两列（搜索引擎/认证、API key/凭据名、深度/主题、国家/语言、模型/版本等）；Base URL、代理仍单行。
40
+ - 去掉卡片顶部说明文案；**结果数量**改为 1–20 下拉。
41
+ - 国家/语言、代理的「留空…」改到输入框 placeholder，字段下方不再重复。Brave 额度卡把「月请求不限额 / 重置时间」收进卡片内。
42
+
43
+ ### 修复
44
+
45
+ - 保存按钮在「看起来可点、实际 disabled」时没有反馈。现在始终可点（只读或保存中除外），成功/无变更/失败都会弹出 toast，对齐 dsh-credits。
46
+ - 未保存草稿对齐官方插件卡：卡片右上角「未保存」角标、字段「已覆盖 / 恢复默认」，离开设置页再回来仍保留草稿，可继续保存或放弃。
47
+ - Tavily keyed 额度卡在 `plan_limit` 尚未拉到时会把已用量藏成「未公布限额 / —」。本地扣费现在会直接显示「已用 N」；首次填入套餐名不再把本地计数清零。
48
+ - Brave 月限额 `0` 的套餐按控制台 **Capacity** 展示每秒窗口（例如 50 次/秒），不再把月配额渲染成「已用 0 / 0」。Brave 没有花费/credits 接口。
49
+ - 数字框只接受不小于 1 的整数；非法输入用红色错误文案替换灰色 hint，保存会被拦住。超出 20 的结果数量会夹到上限。
50
+
5
51
  ## [0.2.0] - 2026-08-19
6
52
 
7
53
  ### 新增
@@ -56,6 +102,7 @@
56
102
  - Keyless 模式（`X-Tavily-Access-Mode: keyless`）与 keyed 模式（通过 `TAVILY_API_KEY` 凭据引用发送 Bearer token）。
57
103
  - DSH 插件配置页上的浏览器设置卡片。
58
104
 
105
+ [0.2.1]: https://github.com/X-C1811/dsh-web-search-plugin/compare/v0.2.0...v0.2.1
59
106
  [0.2.0]: https://github.com/X-C1811/dsh-web-search-plugin/compare/v0.1.2...v0.2.0
60
107
  [0.1.2]: https://github.com/X-C1811/dsh-web-search-plugin/compare/v0.1.1...v0.1.2
61
108
  [0.1.1]: https://github.com/X-C1811/dsh-web-search-plugin/compare/v0.1.0...v0.1.1
package/README.md CHANGED
@@ -1,16 +1,28 @@
1
1
  # dsh-web-search-plugin
2
2
 
3
- 面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) web 能力接缝（`ctx.web`）的统一网页搜索插件，内置 **DeepSeek（官方）/ Tavily / [Brave Search](https://brave.com/search/api/) 三个后端**。本包只向接缝注册 **一个** `WebSearchProvider`，稳定 id 为 `dsh-web-search`。在设置卡里切换引擎即可，不必再改 `web.searchProvider`。
4
-
5
- - **DeepSeek（官方）** — 走 DeepSeek 的 Anthropic 兼容 Messages API（原生 `web_search_20250305` 工具，凭据名 `DEEPSEEK_API_KEY`），一次搜索消耗一个模型轮次。
6
- - **Tavily（默认）** — `keyless`（免费、限流、无需账号）或 `keyed`（`TAVILY_API_KEY`，Bearer token）。
7
- - **Brave Search** — `GET https://api.search.brave.com/res/v1/web/search`，请求头 `X-Subscription-Token`（凭据名 `BRAVE_API_KEY`）。一次搜索就是一次 HTTP 请求，不走模型轮次。
3
+ 面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) web 能力接缝（`ctx.web`）的统一网页搜索插件，内置 **DeepSeek（官方，默认）/ Tavily / [Brave Search](https://brave.com/search/api/) / Serper / SerpApi / Exa / SearXNG / Scavio / Firecrawl 九个后端**。本包只向接缝注册 **一个** `WebSearchProvider`，稳定 id 为 `dsh-web-search`。在 **设置 → 网页搜索** 里切换引擎即可，不必再改 `web.searchProvider`。
4
+
5
+ - **DeepSeek（官方，默认）** — 走 DeepSeek 的 Anthropic 兼容 Messages API（原生 `web_search_20250305` 工具，凭据名 `DEEPSEEK_API_KEY`），一次搜索消耗一个模型轮次。
6
+ - **Tavily** — `keyless`（免费、限流、无需账号）或 `keyed`（`TAVILY_API_KEY`，Bearer token）。keyed 会在设置卡显示额度进度条。
7
+ - **Brave Search** — `GET https://api.search.brave.com/res/v1/web/search`，请求头 `X-Subscription-Token`（凭据名 `BRAVE_API_KEY`）。一次搜索就是一次 HTTP 请求，不走模型轮次；设置卡按响应头展示 Capacity / 月配额。
8
+ - **Serper** — Google 结果（`POST /search`，头 `X-API-KEY`，凭据名 `SERPER_API_KEY`）。
9
+ - **SerpApi** — `GET /search.json`，key 走 query（`api_key=`），凭据名 `SERPAPI_API_KEY`。
10
+ - **Exa** — 语义/神经搜索（`POST /search`，Bearer，凭据名 `EXA_API_KEY`）。
11
+ - **SearXNG** — 自建/协议免 key 的元搜索（`GET /search?format=json`），可填自托管实例地址。
12
+ - **Scavio** — Google SERP（`POST /api/v2/google`，Bearer，凭据名 `SCAVIO_API_KEY`），响应与 SerpApi 同构。
13
+ - **Firecrawl** — 搜索+抓取（`POST /v2/search`，Bearer，凭据名 `FIRECRAWL_API_KEY`），`sources: ["web"]`。
14
+ - **DuckDuckGo** — 无官方搜索 API，不提供独立后端；下拉中以禁用项提示：选 SearXNG 并指向聚合了 DuckDuckGo 的实例即可。
15
+ - **官方 key 跳转** — 需要 key 的内置 provider 在设置卡带「获取 API key ↗」一键跳官方控制台；免 key 的（SearXNG / Tavily keyless）不渲染。
8
16
  - **不写自定义 session 事件** — 工具结果已经走接缝自己的事件，无需多余信封。
9
17
 
10
18
  ## 特性
11
19
 
12
20
  - 与官方 `@deepseek-ai/dsh-web-search-deepseek` 相同的提供方约定：`inject: ['web']` + `installSettingsSection` + `ctx.web.registerSearchProvider`。
21
+ - 顶层 **设置 → 网页搜索** 分区：两列布局、未保存草稿、保存 toast；结果数量为 1–20 下拉。
22
+ - **默认引擎为 DeepSeek（官方）**：新装 / 未显式改动时，搜索直接走 `deepseek-official`，不再依赖 keyless 的 Tavily。
23
+ - 纯 REST 后端由**静态元数据表 + 通用后端**驱动，新增 provider 即"表里加一行 + 官方跳转链接"，无定制执行代码。
13
24
  - Tavily keyless 无需密钥即可用；Brave 需要订阅 token（若本机已有 `BRAVE_API_KEY` 凭据，可直接复用）。
25
+ - Tavily keyed / Brave 在设置卡展示额度进度条（DeepSeek 官方与 Tavily keyless / 其余 REST 后端不展示）。
14
26
  - 各引擎结果都规范化为接缝的 `WebSearchResult`（可选 `content` + `sources[]`），按 URL 去重。
15
27
  - 设置段 `dsh-web-search-plugin` 通过 rc.7 的 `settings.describe()` 动态暴露，不需要宿主白名单补丁，也不需要自建回环 settings 桥。
16
28
  - 错误映射为 `WEB_PROVIDER_ERROR` / `WEB_ABORTED` / `WEB_PROVIDER_CREDENTIAL_MISSING`。
@@ -30,32 +42,7 @@
30
42
  dsh plugin --profile web add dsh-web-search-plugin
31
43
  ```
32
44
 
33
- ### 从本地目录安装
34
-
35
- ```powershell
36
- dsh plugin --profile web add "path/to/dsh-web-search-plugin"
37
- ```
38
-
39
- 重启 DSH web 进程；浏览器刷新后会加载客户端 bundle。
40
-
41
- 用 `dsh --profile web --dump-config` 确认：组成树里应有 `dsh-web-search-plugin` 行，且 `web.searchProvider` 为 `dsh-web-search`。
42
-
43
- 若 profile 已经覆盖了 `web`（例如旧包 `@dsh-ltctfer/dsh-web-search-brave` 留下的 `brave-official`），后打的 patch 仍会生效。请改指向本插件，并卸掉旧包：
44
-
45
- ```yaml
46
- - id: web
47
- name: '@deepseek-ai/dsh-web'
48
- config:
49
- searchProvider: dsh-web-search
50
- ```
51
-
52
- ```powershell
53
- dsh plugin --profile web remove @dsh-ltctfer/dsh-web-search-brave
54
- ```
55
-
56
- 然后在 **设置 → 网页搜索** 里把引擎切到想要的提供方，即可继续使用对应的 API key。
57
-
58
- > **关于 `file:`（本地）安装** — pnpm 会把 `file:path` 依赖做成快照。改完本仓库后，需要再执行一次 `dsh plugin --profile web add "path/to/dsh-web-search-plugin"` 并重启。
45
+ > 从源码仓库本地安装（含 Windows 跨盘注意事项）见 [开发 → 本地安装与验证](#本地安装与验证)。
59
46
 
60
47
  ## 配置
61
48
 
@@ -63,12 +50,12 @@ dsh plugin --profile web remove @dsh-ltctfer/dsh-web-search-brave
63
50
 
64
51
  | 键 | 默认值 | 含义 |
65
52
  |---|---|---|
66
- | `provider` | `tavily` | `tavily`、`brave` 或 `deepseek-official` |
53
+ | `provider` | `deepseek-official` | `tavily`、`brave`、`deepseek-official`、`serper`、`serpapi`、`exa`、`searxng`、`scavio` 或 `firecrawl` |
67
54
  | `mode` | `keyless` | 仅 Tavily：`keyless` 或 `keyed` |
68
55
  | `apiKey` | — | Tavily API key 字面量（走凭据域，不会回显） |
69
56
  | `apiKeyEnv` | `TAVILY_API_KEY` | keyed Tavily 使用的凭据/环境变量名 |
70
57
  | `baseURL` | `https://api.tavily.com` | Tavily REST 基址；会再拼 `/search` |
71
- | `maxResults` | `8` | 每次搜索返回的源数量（1–20），三个后端共用 |
58
+ | `maxResults` | `8` | 每次搜索返回的源数量，各后端共用。设置卡为 1–20 下拉，超出上限会夹到 20 |
72
59
  | `searchDepth` | `basic` | 仅 Tavily：`basic` 或 `advanced` |
73
60
  | `includeAnswer` | `true` | 仅 Tavily：请求生成摘要，写入结果 `content` |
74
61
  | `topic` | `general` | 仅 Tavily：`general` 或 `news` |
@@ -82,13 +69,37 @@ dsh plugin --profile web remove @dsh-ltctfer/dsh-web-search-brave
82
69
  | `braveApiKey` | — | Brave 订阅 token 字面量（走凭据域） |
83
70
  | `braveApiKeyEnv` | `BRAVE_API_KEY` | Brave 使用的凭据/环境变量名 |
84
71
  | `braveBaseURL` | `https://api.search.brave.com/res/v1/web/search` | Brave 网页搜索接口 |
85
- | `country` | — | Brave 的 `country`（ISO 两位码，如 `cn`） |
86
- | `searchLang` | — | Brave 的 `search_lang`（如 `zh-hans`） |
72
+ | `country` | — | Brave 的 `country`（ISO 两位码，如 `cn`）；留空使用 Brave 默认 |
73
+ | `searchLang` | — | Brave 的 `search_lang`（如 `zh-hans`）；留空使用 Brave 默认 |
87
74
  | `freshness` | — | Brave 的 `freshness`：`pd` / `pw` / `pm` / `py` |
88
- | `proxy` | — | Brave 使用的 HTTP(S) 代理；未填则回退 `HTTPS_PROXY` / `HTTP_PROXY` |
75
+ | `proxy` | — | Brave 使用的 HTTP(S) 代理；留空回退 `HTTPS_PROXY` / `HTTP_PROXY` |
76
+ | `serperApiKey` / `serperApiKeyEnv` / `serperBaseURL` | — / `SERPER_API_KEY` / — | Serper 的 key 字面量 / 凭据引用名 / 端点覆盖 |
77
+ | `serpapiApiKey` / `serpapiApiKeyEnv` / `serpapiBaseURL` | — / `SERPAPI_API_KEY` / — | SerpApi 的 key 字面量 / 凭据引用名 / 端点覆盖 |
78
+ | `exaApiKey` / `exaApiKeyEnv` / `exaBaseURL` | — / `EXA_API_KEY` / — | Exa 的 key 字面量 / 凭据引用名 / 端点覆盖 |
79
+ | `searxngBaseURL` | — | SearXNG 自托管实例基址；留空用 `https://searx.be` |
80
+ | `scavioApiKey` / `scavioApiKeyEnv` / `scavioBaseURL` | — / `SCAVIO_API_KEY` / — | Scavio 的 key 字面量 / 凭据引用名 / 端点覆盖 |
81
+ | `firecrawlApiKey` / `firecrawlApiKeyEnv` / `firecrawlBaseURL` | — / `FIRECRAWL_API_KEY` / — | Firecrawl 的 key 字面量 / 凭据引用名 / 端点覆盖 |
82
+
83
+ ## 未纳入的服务
84
+
85
+ 以下服务**不内置**（在引擎下拉中不会出现，也不提供后端）：
86
+
87
+ | 服务 | 不做的原因 |
88
+ |---|---|
89
+ | **TinyFish** | 免费额度极小（每分钟 5 次）；其 Search + Fetch 形态超出"纯 REST 搜索"边界，仅搜索部分价值低 |
90
+ | **Google CSE** | 官方已对新用户关闭注册，并将于 2027-01-01 停用 |
91
+ | **SERPJET** | 官网当前不可访问，暂不接入 |
92
+ | **DuckDuckGo** | 无官方搜索 API（HTML/社区库抓取不符合元数据表"纯 REST"边界）。下拉中有禁用提示，指引经 SearXNG 使用 |
89
93
 
90
94
  环境变量：启动时 `DSH_WEB_SEARCH_PROVIDER=dsh-web-search` 会选中本接缝 id。未设置 `baseURL` 时，Tavily 基址回退 `$TAVILY_BASE_URL`。
91
95
 
96
+ ## 额度
97
+
98
+ - **Tavily keyless / DeepSeek 官方**：不展示额度条。前者是免费限流、没有账户配额；后者按次扣费、没有月度限额。
99
+ - **Tavily keyed**：搜索时请求 `include_usage`，把本次 credits 累加到 `%DSH_HOME%\storages\dsh-web-search-usage.json`。Host 每 10 分钟（以及设置卡点刷新）调用 `GET /usage`，用 `account.current_plan` / `plan_limit` 做限额，用量取本地累计与远端的较大值。换套餐或远端用量回落会重置本地计数。
100
+ - **Brave**：没有 usage / 花费接口。控制台 **Capacity** 就是响应头里的每秒窗口（例如 50 次/秒）。月限额 `0` 表示不限请求次数，不是额度用完。计费 credits 只能看 [Brave API 控制台](https://api-dashboard.search.brave.com/)。
101
+ - 浏览器只读 `GET /dsh-web-search/usage`（不直打上游）。进度条：剩余超过 20% 为绿色，不超过 20% 为黄色，不超过 10% 为红色。
102
+
92
103
  ## 切回内置 DeepSeek
93
104
 
94
105
  DeepSeek 已并入本插件（`provider: deepseek-official`），无需切回。若确要恢复 DSH 内置的 DeepSeek host 插件，请在 profile patch 里去掉对 `web-search-deepseek` 的 `disabled` 并把 `searchProvider` 设回 `deepseek-official`；本插件可以继续挂着，只是不会被选中。
@@ -96,24 +107,84 @@ DeepSeek 已并入本插件（`provider: deepseek-official`），无需切回。
96
107
  ## 工作方式
97
108
 
98
109
  - **DeepSeek** — `POST {deepseekBaseURL}/messages`，请求头 `x-api-key` / `authorization: Bearer`，工具 `web_search_20250305`。
99
- - **Tavily** — `POST {baseURL}/search`。keyless 发送 `x-tavily-access-mode: keyless`；keyed 发送 `authorization: Bearer <key>`。
100
- - **Brave** — `GET {braveBaseURL}?q=&count=`，请求头 `x-subscription-token`。不向 session 追加自定义事件。
110
+ - **纯 REST 类（Tavily / Brave / Serper / SerpApi / Exa / SearXNG）** — 由静态元数据表（`lib/providers.js`）+ 通用后端（`lib/rest.js`）驱动，无独立定制代码。请求方法 / 路径 / 查询字段名 / 鉴权（bearer / header / none / query）/ 固定参数 / 响应形态全部由表里的行决定。
111
+ - **Tavily** — `POST {baseURL}/search`。keyless 发送 `x-tavily-access-mode: keyless`；keyed 发送 `authorization: Bearer <key>`，并带 `include_usage` 回传 credits。
112
+ - **Brave** — `GET {braveBaseURL}?q=&count=`，请求头 `x-subscription-token`。不向 session 追加自定义事件。
113
+ - **Serper / SerpApi / Exa / SearXNG** — 按各自表的 `method` / `auth` / `params` 约定请求。
101
114
  - 非 2xx 映射为 `WEB_PROVIDER_ERROR`；调用方取消映射为 `WEB_ABORTED`。
102
115
 
103
116
  ## 仓库布局
104
117
 
105
118
  ```
106
- lib/index.js Host 插件：Config、分发提供方、设置段
107
- lib/deepseek.js DeepSeek 后端（Anthropic Messages + web_search_20250305）
108
- lib/tavily.js Tavily 后端
109
- lib/brave.js Brave 后端（不写自定义 session 事件）
119
+ lib/index.js Host 插件：Config、按元数据分发提供方、设置段、额度路由
120
+ lib/providers.js 静态元数据表：内置 REST provider 的请求/鉴权/响应/官方跳转（纯数据，无定制代码）
121
+ lib/rest.js 通用 REST 后端：按元数据驱动请求构造与响应规范化（可选 hooks）
122
+ lib/deepseek.js DeepSeek 后端（Anthropic Messages + web_search_20250305，模型工具型专用）
123
+ lib/tavily.js Tavily 选项解析 / 响应映射（额度由 Tavily hook 回传）
124
+ lib/brave.js Brave 选项解析 / 响应映射（解析 X-RateLimit-*）
125
+ lib/usage.js Tavily/Brave 用量本地缓存与 /usage 对账
110
126
  lib/shared.js 中止 / 凭据解析辅助
111
- lib/client.js 浏览器 bundle：顶层「网页搜索」分区 + 引擎切换表单
127
+ lib/client.js 浏览器 bundle：顶层「网页搜索」分区 + 引擎切换 + 官方 key 跳转 + 额度条
112
128
  cordis.patch.yml Bundle patch：插入 Host 行、设 searchProvider、禁用内置 deepseek
113
129
  ```
114
130
 
115
131
  ## 开发
116
132
 
133
+ ### 本地安装与验证
134
+
135
+ 改源码后本机验证，把仓库装进某个 profile（以 `web` 为例）。**同盘**可以直接用相对路径：
136
+
137
+ ```powershell
138
+ dsh plugin --profile web add ".\dsh-web-search-plugin"
139
+ ```
140
+
141
+ **Windows 跨盘不要 `dsh plugin add` 绝对路径。** Profile 在 `C:`、仓库在 `D:` 时，它会写成 `link:d:/...`；pnpm 把盘符当成相对路径，junction 会指到 `profiles\web\D:\...` 并链坏。也不要写 `file:D:/...`：pnpm 10 同样会把跨盘绝对路径拼进 profile 目录。
142
+
143
+ 正确做法是快照到与 profile **同盘**，再用 `file:`：
144
+
145
+ ```powershell
146
+ $dst = "$env:USERPROFILE\.dsh\profiles\web\.local\dsh-web-search-plugin"
147
+ New-Item -ItemType Directory -Force -Path $dst | Out-Null
148
+ robocopy "D:\sample\dsh-web-search-plugin" $dst /E /XD node_modules .git .github /NFL /NDL /NJH /NJS
149
+ ```
150
+
151
+ 在 profile 的 `package.json` 里：
152
+
153
+ ```json
154
+ "dsh-web-search-plugin": "file:.local/dsh-web-search-plugin"
155
+ ```
156
+
157
+ 并保证 `dsh.profile.bundles` 含本包，然后：
158
+
159
+ ```powershell
160
+ dsh plugin --profile web install
161
+ ```
162
+
163
+ `file:` 是快照：改完仓库后要再 robocopy + `install` 并重启 DSH。
164
+
165
+ 用 `dsh --profile web --dump-config` 确认：组成树里应有 `dsh-web-search-plugin` 行，且 `web.searchProvider` 为 `dsh-web-search`。
166
+
167
+ > **关于 `file:`（本地）安装** — pnpm 会把 `file:` 依赖做成快照。改完本仓库后，需要再同步快照并 `dsh plugin --profile web install`，然后重启。Windows 上 profile 与仓库不在同一盘时，用同盘 `file:.local/...`，不要 `link:` / `file:` 指向另一块盘。
168
+
169
+ ### 迁移旧后端包
170
+
171
+ 若 profile 已经覆盖了 `web`（例如旧包 `@dsh-ltctfer/dsh-web-search-brave` 留下的 `brave-official`），后打的 patch 仍会生效。请改指向本插件，并卸掉旧包：
172
+
173
+ ```yaml
174
+ - id: web
175
+ name: '@deepseek-ai/dsh-web'
176
+ config:
177
+ searchProvider: dsh-web-search
178
+ ```
179
+
180
+ ```powershell
181
+ dsh plugin --profile web remove @dsh-ltctfer/dsh-web-search-brave
182
+ ```
183
+
184
+ 然后在 **设置 → 网页搜索** 里把引擎切到想要的提供方，即可继续使用对应的 API key。
185
+
186
+ ### 语法检查
187
+
117
188
  ```powershell
118
189
  npm run check
119
190
  ```
@@ -122,15 +193,15 @@ npm run check
122
193
 
123
194
  ## 发布
124
195
 
125
- 发布由 GitHub Actions（`.github/workflows/publish.yml`）自动完成：**推送 `v*` 标签**（例如 `v0.2.0`）会带 provenance 发到 npm。向 `main` 的普通推送不会发布。
196
+ 发布由 GitHub Actions（`.github/workflows/publish.yml`）自动完成：**推送 `v*` 标签**（例如 `v0.3.0`）会带 provenance 发到 npm。向 `main` 的普通推送不会发布。
126
197
 
127
- 1. 确认 `package.json` 的 `version` 与即将推送的标签一致（例如 `0.2.0` → `v0.2.0`）。
198
+ 1. 确认 `package.json` 的 `version` 与即将推送的标签一致（例如 `0.3.0` → `v0.3.0`）。
128
199
  2. 在 GitHub **Settings → Secrets and variables → Actions** 里配置有 publish 权限的 npm automation token（仓库密钥 `NPM_TOKEN`），并允许 Actions 运行。
129
200
  3. 打标签并推送：
130
201
 
131
202
  ```powershell
132
- git tag v0.2.0
133
- git push origin v0.2.0
203
+ git tag v0.3.0
204
+ git push origin v0.3.0
134
205
  ```
135
206
 
136
207
  工作流会先核对标签与 `package.json` 的 `version`，再执行 `npm publish --provenance --access public`。
package/cordis.patch.yml CHANGED
@@ -22,5 +22,5 @@
22
22
  - id: dsh-web-search-plugin
23
23
  name: dsh-web-search-plugin
24
24
  config:
25
- provider: tavily
25
+ provider: deepseek-official
26
26
  mode: keyless
package/lib/brave.js CHANGED
@@ -101,6 +101,7 @@ export class BraveSearchProvider {
101
101
  if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
102
102
  throw new WebError(`Brave search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
103
103
  }
104
+ options.onRateLimit?.(response.headers);
104
105
  if (!response.ok) {
105
106
  let message = `Brave Search API error (HTTP ${response.status})`;
106
107
  try {