dsh-free-search 0.4.24 → 0.4.26

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 (4) hide show
  1. package/README.md +27 -11
  2. package/lib/client.js +1053 -1012
  3. package/lib/index.js +2327 -2163
  4. package/package.json +22 -4
package/README.md CHANGED
@@ -29,11 +29,11 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
29
29
  ### 特性
30
30
 
31
31
  - **零成本** —— 多个免费引擎，无需 key、无需注册
32
- - **多引擎可选**：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、AnySearch、Exa、Tavily、Keenable、Perplexity、DeepSeek 官方
32
+ - **多引擎可选**：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、AnySearch、Exa、Tavily、Keenable、Firecrawl、Parallel、Perplexity、DeepSeek 官方
33
33
  - **网页设置页** —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）+ 中英文切换
34
34
  - **弹出式切换命令** —— 聊天框输入 `/free-search-engine`，弹出引擎选择窗口，点选即切换（等效设置页 + 保存）
35
35
  - **引擎测试** —— `free_search_test` 工具让 agent 一键测试所有引擎；设置页也有"测试引擎"按钮（直测当前引擎，不走回退链，付费引擎无 key 会明确报错）
36
- - **统一引擎回退** —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：首选引擎 → 其他引擎（exa/tavily/keenable 无 key 也会尝试，因为它们自带 keyless 免费额度）→ 剩余免费引擎，搜索永不直接失败；结果顶部注明实际生效的引擎（如 `Note: perplexity unavailable or failed, using exa.`）
36
+ - **统一引擎回退** —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：首选引擎 → 其他引擎（exa/tavily/keenable/firecrawl 无 key 也会尝试，因为它们自带 keyless 免费额度）→ 剩余免费引擎，搜索永不直接失败；结果顶部注明实际生效的引擎（如 `Note: perplexity unavailable or failed, using exa.`）
37
37
  - **时间过滤** —— `advanced_search` 工具支持 `timeRange`：固定档、自定义相对值、绝对日期三种形式（详见下方逻辑说明）
38
38
  - **系统提示词注入** —— agent 知道当前用哪个引擎、哪些需要 key
39
39
  - **版本号 + 检查更新** —— 设置卡片显示当前版本（v0.4.17），"检查更新"按钮直连 npm registry 对比最新版，有新版本时提示并可一键跳转
@@ -57,6 +57,8 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
57
57
  | `exa` | Exa | 免费 | **无 key 也可用**（MCP 匿名），配 key 提升额度 |
58
58
  | `tavily` | Tavily | 免费 | **无 key 也可用**（keyless 匿名），配 key 提升额度 |
59
59
  | `keenable` | Keenable | 免费 | **无 key 也可用**（MCP 匿名），配 key 提升额度 |
60
+ | `firecrawl` | Firecrawl | 免费 | **无 key 也可用**（官方免 key 匿名额度），配 key 提升限额 |
61
+ | `parallel` | Parallel | 付费 | 需 `PARALLEL_API_KEY`（platform.parallel.ai 有免费额度） |
60
62
  | `perplexity` | Perplexity | 付费 | 需 `PERPLEXITY_API_KEY` |
61
63
  | `deepseek-official` | DeepSeek 官方 | 付费 | 需 `DEEPSEEK_API_KEY` |
62
64
 
@@ -66,6 +68,7 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
66
68
  - Exa：<https://dashboard.exa.ai/api-keys>
67
69
  - Tavily：<https://app.tavily.com/home>
68
70
  - Keenable：<https://keenable.ai/login>
71
+ - Parallel：<https://platform.parallel.ai>
69
72
  - Perplexity：<https://www.perplexity.ai/settings/api>
70
73
  - DeepSeek：<https://platform.deepseek.com/api_keys>
71
74
 
@@ -75,6 +78,7 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
75
78
  - **Exa**：公开 MCP 端点（`mcp.exa.ai/mcp`）支持匿名调用，不配 key 也能用；配置 `EXA_API_KEY` 后可获得更高额度。
76
79
  - **Tavily**：通过 `x-tavily-access-mode: keyless` 头走 keyless 匿名额度，不配 key 即可用；配置 `TAVILY_API_KEY` 后走账号档，额度更高、结果质量更稳定。
77
80
  - **Keenable**：无 key 时走其公开 MCP 端点（`api.keenable.ai/mcp`）匿名调用；配置 `KEENABLE_API_KEY` 后走 REST API（`api.keenable.ai/v1/search`），额度更高、按组织限流。
81
+ - **Firecrawl**：其 `/v2/search` 端点**无需 key** 即可使用（官方文档明确说明，有匿名限流）；配置 `FIRECRAWL_API_KEY` 后可提高限额。支持 `tbs` 时间过滤（`qdr:h/d/w/m/y` 与自定义日期区间）。
78
82
 
79
83
  ### 安装
80
84
 
@@ -110,7 +114,7 @@ dsh web
110
114
  安装后，打开 **设置 → 插件 → 可配置** 标签页 → **Free Search** 卡片（官方设置页）：
111
115
 
112
116
  - **Search engine**：下拉框切换引擎，保存即生效
113
- - **API keys**：为 Exa / Tavily / Keenable / Perplexity / DeepSeek 填写 key（密码框，保存后只显示"已配置"）
117
+ - **API keys**：为 Exa / Tavily / Keenable / Firecrawl / Parallel / Perplexity / DeepSeek 填写 key（密码框，保存后只显示"已配置"）
114
118
  - **推荐**：付费引擎 key 建议写入 harness 凭据中心 `~/.dsh/.credentials.yaml`（如 `DEEPSEEK_API_KEY: sk-...`，与官方 LLM provider 一致，一处管理所有 key）。插件读取优先级：凭据中心 > 设置页 > 环境变量，设置页填的 key 仅作为遗留兼容。
115
119
  - **Test engine**：直测当前引擎可用性（不走回退链，付费引擎无 key 会明确报错）
116
120
  - **Use Bing default**：把当前搜索引擎切回稳定的免费 Bing；`Discard` 只撤销尚未保存的编辑
@@ -148,7 +152,7 @@ dsh web
148
152
 
149
153
  ```yaml
150
154
  free-search:
151
- provider: bing # ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / perplexity / deepseek-official
155
+ provider: bing # ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / firecrawl / parallel / perplexity / deepseek-official
152
156
  lang: zh # 设置页界面语言（zh / en）
153
157
  bingMarket: zh-CN # Bing 市场
154
158
  region: cn-zh # DuckDuckGo 区域（可选）
@@ -157,6 +161,8 @@ free-search:
157
161
  exaApiKey: ... # 或通过设置页填写
158
162
  tavilyApiKey: ... # 或通过设置页填写
159
163
  keenableApiKey: ... # 或通过设置页填写
164
+ firecrawlApiKey: ... # 或通过设置页填写
165
+ parallelApiKey: ... # 或通过设置页填写
160
166
  perplexityApiKey: ...
161
167
  deepseekApiKey: ...
162
168
  ```
@@ -191,13 +197,15 @@ Search engine test:
191
197
  | Exa | `startPublishedDate` | ✅ 精确 | 自定义天数转成 ISO 日期（N 天前），绝对日期原样传入 |
192
198
  | Keenable | `published_after` | ✅ 精确 | 相对值原样传（`12h/3d/2mo/1y`），绝对日期原样传 |
193
199
  | Tavily | `time_range` | ⚠️ 近似 | 只认固定档，自定义天数自动映射到最近似档位 |
200
+ | Firecrawl | `tbs` | ⚠️ 近似 | 固定档映射到 `qdr:d/w/m/y`；绝对日期用 `cdr:1,cd_min:M/D/YYYY`（精确） |
201
+ | Parallel | `source_policy.after_date` | ✅ 精确 | 自定义天数转成 ISO 日期（N 天前），绝对日期原样传入 |
194
202
  | SearXNG | `time_range` | ⚠️ 近似 | 同上 |
195
203
  | DuckDuckGo / Lite | `df` | ⚠️ 近似 | 同上 |
196
204
  | Bing / AnySearch | — | ❌ 忽略 | 无对应参数 |
197
205
 
198
206
  **"最近似档位"映射规则**：`≤2 天 → day`，`≤14 天 → week`，`≤90 天 → month`，否则 `year`。例如 `3d` 在 Tavily 上按 `day` 处理，`2mo` 按 `month` 处理。
199
207
 
200
- **引擎链优先级**：当带 timeRange 搜索时，支持时间过滤的引擎（tavily / exa / keenable / searxng / ddg / ddg-lite）会排到引擎链前面，确保过滤真正生效——即使首选引擎是 bing（不支持过滤），也会先尝试支持过滤的引擎。
208
+ **引擎链优先级**：当带 timeRange 搜索时，支持时间过滤的引擎（tavily / exa / keenable / firecrawl / parallel / searxng / ddg / ddg-lite）会排到引擎链前面，确保过滤真正生效——即使首选引擎是 bing（不支持过滤），也会先尝试支持过滤的引擎。
201
209
 
202
210
  示例对话：*"帮我搜最近 3 天关于 DSH 的新闻"* → agent 调用 `advanced_search`，`timeRange: "3d"`。
203
211
 
@@ -282,11 +290,11 @@ This plugin provides multiple free search engines with automatic fallback, compl
282
290
  ### Features
283
291
 
284
292
  - **Zero Cost** — Multiple free engines with no API key or registration required
285
- - **Multi-Engine Support** — DuckDuckGo (HTML / Lite), Bing, AnySearch AI, SearXNG (meta-search with custom instances), Exa, Tavily, Keenable, Perplexity, and DeepSeek Official
293
+ - **Multi-Engine Support** — DuckDuckGo (HTML / Lite), Bing, AnySearch AI, SearXNG (meta-search with custom instances), Exa, Tavily, Keenable, Firecrawl, Parallel, Perplexity, and DeepSeek Official
286
294
  - **Web Settings UI** — Engine switching, API key configuration (keys masked as "configured" in the UI), and a Chinese/English toggle
287
295
  - **Popup Switch Command** — Type `/free-search-engine` in the chat: a picker opens with all engines; click one to switch (equivalent to the settings page + save)
288
296
  - **Engine Testing** — `free_search_test` for the agent to check all engines in one call; the settings UI also has a "Test engine" button that tests the selected engine directly (no fallback chain; paid engines without a key report an explicit error)
289
- - **Unified Engine Fallback** — Any engine failure (paid or free, missing key, 401, rate limit, network error) automatically tries the next engine: the configured engine first, then other engines (exa/tavily/keenable are tried even without a key because they have built-in keyless quota), then the remaining free engines (Bing/AnySearch etc.) — with a note attached to the results naming the engine that actually served them (e.g. `Note: perplexity unavailable or failed, using exa.`). Search never fails outright.
297
+ - **Unified Engine Fallback** — Any engine failure (paid or free, missing key, 401, rate limit, network error) automatically tries the next engine: the configured engine first, then other engines (exa/tavily/keenable/firecrawl are tried even without a key because they have built-in keyless quota), then the remaining free engines (Bing/AnySearch etc.) — with a note attached to the results naming the engine that actually served them (e.g. `Note: perplexity unavailable or failed, using exa.`). Search never fails outright.
290
298
  - **Time Filtering** — The `advanced_search` tool supports `timeRange`: fixed tiers, custom relative values, or an absolute date (details below)
291
299
  - **System Prompt Injection** — The agent is aware of the currently active engine and which engines require API keys
292
300
  - **Version + Update Check** — The settings card shows the current version (v0.4.17), and a "Check update" button queries the npm registry to compare against the latest release, prompting a one-click jump when a newer version exists
@@ -310,15 +318,18 @@ If this plugin has been helpful, a ⭐ on [GitHub](https://github.com/DDDMUC/dsh
310
318
  | `exa` | Exa | Free | **Usable without a key** (anonymous MCP); configure a key for higher quota |
311
319
  | `tavily` | Tavily | Free | **Usable without a key** (keyless anonymous); configure a key for higher quota |
312
320
  | `keenable` | Keenable | Free | **Usable without a key** (anonymous MCP); configure a key for higher quota |
321
+ | `firecrawl` | Firecrawl | Free | **Usable without a key** (official keyless anonymous quota); configure a key for higher limits |
322
+ | `parallel` | Parallel | Paid | Requires `PARALLEL_API_KEY` (free tier available at platform.parallel.ai) |
313
323
  | `perplexity` | Perplexity | Paid | Requires `PERPLEXITY_API_KEY` |
314
324
  | `deepseek-official` | DeepSeek Official | Paid | Requires `DEEPSEEK_API_KEY` |
315
325
 
316
326
  - **Default engine is `bing`** (free and most stable), ready to use out of the box after installation.
317
- - **Auto-failover**: any engine failure (rate-limited free engine, or missing/invalid paid key, network error) automatically tries the next engine — the configured engine first, then other engines (exa/tavily/keenable are tried even without a key because they have built-in keyless quota), then the remaining free engines (Bing/AnySearch etc.) — with a note attached to the results naming the engine that actually served them (e.g. `Note: perplexity unavailable or failed, using exa.`). Search never fails outright because of engine issues.
327
+ - **Auto-failover**: any engine failure (rate-limited free engine, or missing/invalid paid key, network error) automatically tries the next engine — the configured engine first, then other engines (exa/tavily/keenable/firecrawl are tried even without a key because they have built-in keyless quota), then the remaining free engines (Bing/AnySearch etc.) — with a note attached to the results naming the engine that actually served them (e.g. `Note: perplexity unavailable or failed, using exa.`). Search never fails outright because of engine issues.
318
328
  - **Official Links in Settings**: Free engines display "Visit Website →", while paid engines display "Get API Key →" (opens in a new tab):
319
329
  - Exa: <https://dashboard.exa.ai/api-keys>
320
330
  - Tavily: <https://app.tavily.com/home>
321
331
  - Keenable: <https://keenable.ai/login>
332
+ - Parallel: <https://platform.parallel.ai>
322
333
  - Perplexity: <https://www.perplexity.ai/settings/api>
323
334
  - DeepSeek: <https://platform.deepseek.com/api_keys>
324
335
 
@@ -328,6 +339,7 @@ If this plugin has been helpful, a ⭐ on [GitHub](https://github.com/DDDMUC/dsh
328
339
  - **Exa**: its public MCP endpoint (`mcp.exa.ai/mcp`) supports anonymous requests, so it works without a key; configuring `EXA_API_KEY` grants a higher usage quota.
329
340
  - **Tavily**: offers keyless anonymous quota via the `x-tavily-access-mode: keyless` header — it works without a key; configuring `TAVILY_API_KEY` switches to the account tier for higher quota and more stable results.
330
341
  - **Keenable**: without a key it is called via its public MCP endpoint (`api.keenable.ai/mcp`); configuring `KEENABLE_API_KEY` switches to the REST API (`api.keenable.ai/v1/search`) for higher quota and organization-scoped rate limits.
342
+ - **Firecrawl**: its `/v2/search` endpoint works **without a key** out of the box (the official docs state "No API key needed to get started", with anonymous rate limits); configuring `FIRECRAWL_API_KEY` raises the limits. Supports `tbs` time filtering (`qdr:h/d/w/m/y` and custom date ranges).
331
343
 
332
344
  ### Installation
333
345
 
@@ -363,7 +375,7 @@ This plugin intentionally specifies `@deepseek-ai/dsh-settings` and `@deepseek-a
363
375
  After installation, navigate to **Settings → Plugins → Configurable** tab → **Free Search** card (the official settings page):
364
376
 
365
377
  - **Search engine**: Select an engine from the dropdown; changes take effect immediately upon saving.
366
- - **API keys**: Enter keys for Exa / Tavily / Keenable / Perplexity / DeepSeek (password fields; displayed as "configured" once saved).
378
+ - **API keys**: Enter keys for Exa / Tavily / Keenable / Firecrawl / Parallel / Perplexity / DeepSeek (password fields; displayed as "configured" once saved).
367
379
  - **Recommended**: store paid-engine keys in the harness credential center `~/.dsh/.credentials.yaml` (e.g. `DEEPSEEK_API_KEY: sk-...`, same as the official LLM providers — one place for all keys). Resolution order: credentials center > settings page > environment variable; the settings-page fields remain for backward compatibility.
368
380
  - **Test engine**: Tests the selected engine directly (no fallback chain; paid engines without a key report an explicit error).
369
381
  - **Use Bing default**: stage a switch back to the stable free Bing engine; `Discard` only cancels unsaved edits
@@ -401,7 +413,7 @@ Configuration is stored in `~/.dsh/settings.yaml`:
401
413
 
402
414
  ```yaml
403
415
  free-search:
404
- provider: bing # ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / perplexity / deepseek-official
416
+ provider: bing # ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / firecrawl / parallel / perplexity / deepseek-official
405
417
  lang: zh # settings UI language (zh / en)
406
418
  bingMarket: zh-CN # Bing market
407
419
  region: cn-zh # DuckDuckGo region (optional)
@@ -410,6 +422,8 @@ free-search:
410
422
  exaApiKey: ... # Or configure via the web settings UI
411
423
  tavilyApiKey: ... # Or configure via the web settings UI
412
424
  keenableApiKey: ... # Or configure via the web settings UI
425
+ firecrawlApiKey: ... # Or configure via the web settings UI
426
+ parallelApiKey: ... # Or configure via the web settings UI
413
427
  perplexityApiKey: ...
414
428
  deepseekApiKey: ...
415
429
  ```
@@ -444,13 +458,15 @@ Ask the agent for *"news from the last week"*, *"releases this month"*, *"update
444
458
  | Exa | `startPublishedDate` | ✅ precise | custom days become an ISO date (N days ago); absolute dates pass through |
445
459
  | Keenable | `published_after` | ✅ precise | relative values (`12h/3d/2mo/1y`) and absolute dates pass through |
446
460
  | Tavily | `time_range` | ⚠️ approximate | only fixed tiers; custom days map to the nearest tier |
461
+ | Firecrawl | `tbs` | ⚠️ approximate | fixed tiers map to `qdr:d/w/m/y`; absolute dates use `cdr:1,cd_min:M/D/YYYY` (precise) |
462
+ | Parallel | `source_policy.after_date` | ✅ precise | custom days become an ISO date (N days ago); absolute dates pass through |
447
463
  | SearXNG | `time_range` | ⚠️ approximate | same as above |
448
464
  | DuckDuckGo / Lite | `df` | ⚠️ approximate | same as above |
449
465
  | Bing / AnySearch | — | ❌ ignored | no corresponding parameter |
450
466
 
451
467
  **Nearest-tier mapping rule**: `≤2 days → day`, `≤14 days → week`, `≤90 days → month`, otherwise `year`. For example, `3d` becomes `day` on Tavily, and `2mo` becomes `month`.
452
468
 
453
- **Engine-chain priority**: when a `timeRange` is present, engines that support time filtering (tavily / exa / keenable / searxng / ddg / ddg-lite) are moved to the front of the fallback chain, so the filter actually takes effect — even if the preferred engine is bing (which does not support filtering), a filtering-capable engine is tried first.
469
+ **Engine-chain priority**: when a `timeRange` is present, engines that support time filtering (tavily / exa / keenable / firecrawl / parallel / searxng / ddg / ddg-lite) are moved to the front of the fallback chain, so the filter actually takes effect — even if the preferred engine is bing (which does not support filtering), a filtering-capable engine is tried first.
454
470
 
455
471
  Example: *"Find DSH news from the last 3 days"* → agent calls `advanced_search` with `timeRange: "3d"`.
456
472