@klarkxy/dsh-web-search-manager 0.1.9 → 0.1.10

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 (10) hide show
  1. package/README.md +32 -19
  2. package/docs/README.zh-CN.md +31 -18
  3. package/lib/client.inner.cjs +942 -299
  4. package/lib/client.inner.cjs.map +1 -1
  5. package/lib/client.js +942 -299
  6. package/lib/index.js +51 -21
  7. package/lib/index.js.map +1 -1
  8. package/locale/en.json +6 -0
  9. package/locale/zh.json +6 -0
  10. package/package.json +13 -6
package/README.md CHANGED
@@ -1,12 +1,12 @@
1
1
  # @klarkxy/dsh-web-search-manager
2
2
 
3
- Configure DSH web search providers and page fetching from one settings page.
3
+ Choose which service answers the agent's web searches, set the limits every request runs under, and let the agent read public pages — all from one settings page.
4
4
 
5
- [简体中文](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/docs/README.zh-CN.md)
5
+ [简体中文](docs/README.zh-CN.md)
6
6
 
7
- ## Install
7
+ Requires Node.js ≥22 and DSH `0.1.7-rc.2`. No repository build is needed.
8
8
 
9
- Requires Node.js ≥22 and DSH `0.1.7-rc.2`. No repository build is needed. Install:
9
+ ## Install
10
10
 
11
11
  ```sh
12
12
  npm install @klarkxy/dsh-web-search-manager
@@ -18,15 +18,11 @@ Then load it:
18
18
  dsh plugin --profile web add @klarkxy/dsh-web-search-manager
19
19
  ```
20
20
 
21
- Restart DSH Web and open **Plugins → Web search**. For agent access, add this entry to the plugin list in its `agent.cordis.yml`:
22
-
23
- ```yaml
24
- - name: '@klarkxy/dsh-web-search-manager/tools'
25
- ```
21
+ Restart DSH Web and open **Plugins → Web search**.
26
22
 
27
23
  ## Configure search
28
24
 
29
- The settings page has two tabs: **搜索服务** manages providers, and **请求限制** sets request limits. DuckDuckGo is enabled by default and requires no key. Enable another provider and configure credentials in settings if needed; one ready provider is enough. Drag providers to reorder them; the first ready provider by priority handles each request. Missing credentials are skipped; failed requests do not automatically switch providers.
25
+ The settings page has two tabs: **搜索服务** manages the providers, **请求限制** sets the request limits. DuckDuckGo is enabled by default and needs no key. To add another backend, enable it and fill in its credentials in settings; one ready backend is enough. Drag the list to change the order, and each request is served by the first ready backend in that order. A backend whose key is missing is skipped, and a failed request does not silently move on to another one.
30
26
 
31
27
  Built-in search backends:
32
28
 
@@ -39,19 +35,25 @@ Built-in search backends:
39
35
  - **Firecrawl**: a web search and extraction API; requires `DSH_EDITOR_WEB_FIRECRAWL_API_KEY`.
40
36
  - **Tavily**: a Search API fixed to basic search depth, never auto-upgraded; requires `DSH_EDITOR_WEB_TAVILY_API_KEY`. The adapter is built into this plugin; the former standalone `dsh-web-search-tavily` package is retired.
41
37
 
42
- Enabling search also enables public-page fetching. The built-in `http` route first requests `https://r.jina.ai/<target URL>` anonymously and returns Reader's text/Markdown. HTTP errors (including 429), Reader timeouts, network failures, and empty or invalid responses fall back once to the existing direct HTTP fetcher. This fallback is only for page fetching; search backend selection is unchanged. No Jina registration, API key, billing configuration, or new dependency is required.
38
+ ## Read public pages
43
39
 
44
- Target URLs are sent to Jina, a third-party service; do not submit URLs containing private tokens or other sensitive data. No cookies or authorization headers are added. IP literals, obvious local hostnames, credentialed URLs, and already-prefixed Reader URLs skip Jina and remain subject to the original HTTP fetcher's policy. Both stages use the existing HTTP transport; the Reader stage uses at most half of `timeoutMs`, capped at 15 seconds, leaving time for direct fallback. Caller cancellation, disabling network access, or the overall deadline stops the request without starting a fallback. Results retain the requested URL rather than the Reader proxy URL.
40
+ Turning search on also enables public-page fetching. The built-in `http` route first requests `https://r.jina.ai/<target URL>` anonymously and returns Reader's text/Markdown. HTTP errors (including 429), Reader timeouts, network failures, and empty or invalid responses fall back once to the existing direct HTTP fetcher. This fallback covers page fetching only; it does not change how a search backend is picked. No Jina registration, API key, billing configuration, or new dependency is required.
45
41
 
46
- Request limits cap each query's results (`maxResults`), queries per tool call (`maxQueries`), the total request timeout (`timeoutMs`), and fetched page characters (`maxFetchChars`). Each HTTP response retains the 5 MB byte cap. A connection test sends a fixed query, not manuscript content, and may incur a provider charge.
42
+ The request carries no cookies or authorization headers. IP literals, obvious local hostnames, credentialed URLs, and URLs that already carry the Reader prefix skip Jina and stay subject to the original HTTP fetcher's policy. Both stages use the existing HTTP transport, and the Reader stage takes at most half of `timeoutMs`, capped at 15 seconds, so a direct fallback still has time to run. Caller cancellation, disabled network access, or an overall deadline stops the request without starting a fallback. Results keep the requested URL rather than the Reader proxy URL.
47
43
 
48
- With the tools entry enabled, the agent receives the official `web_search` and `web_fetch` tools from `@deepseek-ai/dsh-tool-web`, mounted only while search and fetching are enabled.
44
+ ## Request limits
49
45
 
50
- Only configure trusted HTTPS endpoints: API keys are sent to them. Credentials use DSH storage; protection at rest depends on its configured backend. Usage counters are call attempts, not billing statements or a spending cap.
46
+ The limits cap each query's results (`maxResults`), queries per tool call (`maxQueries`), the total request timeout (`timeoutMs`), and fetched page characters (`maxFetchChars`). Each HTTP response retains the 5 MB byte cap. A connection test sends a fixed query, not manuscript content, and may incur a provider charge.
51
47
 
52
- Disabling a managed provider cancels its requests, but does not sandbox HTTP calls made directly by other plugins. Search results are external material and cannot authorize changes to manuscripts.
48
+ ## Agent tools
53
49
 
54
- If deployment environment overrides conflict with the settings selection, remove the conflicting overrides. If saving configuration fails, managed network access pauses until settings are successfully saved.
50
+ For agent access, add this entry to the plugin list in the `agent.cordis.yml` you use:
51
+
52
+ ```yaml
53
+ - name: '@klarkxy/dsh-web-search-manager/tools'
54
+ ```
55
+
56
+ Once that entry is enabled, the agent receives the official `web_search` and `web_fetch` tools from `@deepseek-ai/dsh-tool-web`, mounted only while search and fetching are enabled.
55
57
 
56
58
  ## Extend or develop
57
59
 
@@ -61,10 +63,21 @@ From the repository root:
61
63
 
62
64
  ```sh
63
65
  pnpm --filter @klarkxy/dsh-web-search-manager typecheck
64
- pnpm exec vitest run packages/dsh-web-search-manager/src
66
+ pnpm --filter @klarkxy/dsh-web-search-manager test
65
67
  pnpm --filter @klarkxy/dsh-web-search-manager build
66
68
  ```
67
69
 
68
70
  Tests use mock credentials and responses and incur no search charges.
69
71
 
70
- [Publishing](https://github.com/klarkxy/dsh-editor/blob/main/packages/PUBLISHING.md) · [License](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/LICENSE)
72
+ ## Boundaries and limits
73
+
74
+ - Only configure trusted HTTPS endpoints: API keys are sent to them.
75
+ - Credentials are kept in DSH storage, and protection at rest depends on its configured backend.
76
+ - Usage counters are call attempts, not billing statements or a spending cap.
77
+ - Target URLs are sent to Jina, a third-party service; do not submit URLs containing private tokens or other sensitive data.
78
+ - Disabling a managed provider cancels its requests, but it does not sandbox HTTP calls made directly by other plugins.
79
+ - Search results are external material and cannot authorize changes to manuscripts.
80
+ - If deployment environment overrides conflict with the settings selection, remove the conflicting overrides.
81
+ - If saving the configuration fails, managed network access pauses until the settings are saved successfully.
82
+
83
+ [Publishing](../PUBLISHING.md) · [License](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/LICENSE)
package/docs/README.zh-CN.md CHANGED
@@ -1,12 +1,12 @@
1
1
  # @klarkxy/dsh-web-search-manager
2
2
 
3
- 在一个设置页中配置 DSH 网络搜索与网页读取。
3
+ 在一个设置页里挑选用哪个服务回答模型的网络搜索、设定每次请求的上限，并让模型读取公开网页。
4
4
 
5
- [English](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/README.md)
5
+ [English](../README.md)
6
6
 
7
- ## 安装
7
+ 需要 Node.js ≥22、DSH `0.1.7-rc.2`，无需构建本仓库。
8
8
 
9
- 需要 Node.js ≥22、DSH `0.1.7-rc.2`，无需构建本仓库。安装：
9
+ ## 安装
10
10
 
11
11
  ```sh
12
12
  npm install @klarkxy/dsh-web-search-manager
@@ -18,15 +18,11 @@ npm install @klarkxy/dsh-web-search-manager
18
18
  dsh plugin --profile web add @klarkxy/dsh-web-search-manager
19
19
  ```
20
20
 
21
- 重启 DSH Web，打开「插件 → 网络搜索」。模型需要使用搜索工具时，在所用 `agent.cordis.yml` 的插件列表加入：
22
-
23
- ```yaml
24
- - name: '@klarkxy/dsh-web-search-manager/tools'
25
- ```
21
+ 重启 DSH Web，打开「插件 → 网页搜索」。
26
22
 
27
23
  ## 配置搜索
28
24
 
29
- 设置页分两个标签页：「搜索服务」管理供应商，「请求限制」设置请求限额。默认开启 DuckDuckGo，无需密钥。需要其它后端时在设置中开启并填写凭据；一个可用后端即可。拖拽后端调整顺序；按优先级使用第一个就绪后端，缺密钥的跳过，失败不自动换家。
25
+ 设置页分两个标签页：「搜索服务」管理供应商，「请求限制」设置请求限额。默认开启 DuckDuckGo，无需密钥。需要其它后端时在设置中开启并填写凭据；一个可用后端即可。拖拽列表调整顺序，每次请求由顺序中第一个就绪的后端处理。缺密钥的后端直接跳过，失败也不会自动换家。
30
26
 
31
27
  内置搜索后端：
32
28
 
@@ -39,19 +35,25 @@ dsh plugin --profile web add @klarkxy/dsh-web-search-manager
39
35
  - **Firecrawl**：网页搜索与提取 API，需要 `DSH_EDITOR_WEB_FIRECRAWL_API_KEY`。
40
36
  - **Tavily**：Search API，固定 basic 检索深度，不自动升级；需要 `DSH_EDITOR_WEB_TAVILY_API_KEY`。适配器已并入本插件，原独立的 `dsh-web-search-tavily` 包已退役。
41
37
 
42
- 开启搜索也会启用公开网页读取。内置 `http` 路由优先匿名请求 `https://r.jina.ai/<目标 URL>`，返回 Reader 的文本/Markdown；HTTP 错误（含 429）、Reader 超时、网络失败、空内容或无效响应时，回退一次到原有 HTTP 直连读取。此回退仅用于网页读取，不改变搜索后端选择。无需注册 Jina、配置 API Key 或计费设置，也不增加依赖。
38
+ ## 读取公开网页
39
+
40
+ 开启搜索也会启用公开网页读取。内置 `http` 路由优先匿名请求 `https://r.jina.ai/<目标 URL>`，返回 Reader 的文本/Markdown；HTTP 错误（含 429）、Reader 超时、网络失败、空内容或无效响应时，回退一次到原有 HTTP 直连读取。此回退只作用于网页读取，不改变搜索后端的选择。无需注册 Jina、配置 API Key 或计费设置，也不增加依赖。
43
41
 
44
- 目标 URL 会发送给第三方服务 Jina，请勿提交含私密令牌或其它敏感信息的 URL。请求不附带 Cookie 或授权头。IP 字面量、明显的本地主机名、带用户名密码的 URL，以及已经带 Reader 前缀的地址跳过 Jina，继续受原 HTTP 读取器的策略约束。两阶段均复用原 HTTP 传输；Reader 最多使用 `timeoutMs` 的一半，且不超过 15 秒，为直连回退预留时间。用户取消、关闭联网或总超时到期时直接停止，不再发起回退。结果保留请求的目标 URL，不将 Reader 代理地址当作来源。
42
+ 请求不附带 Cookie 或授权头。IP 字面量、明显的本地主机名、带用户名密码的 URL，以及已经带 Reader 前缀的地址跳过 Jina，继续受原 HTTP 读取器的策略约束。两个阶段复用同一套 HTTP 传输，Reader 阶段最多使用 `timeoutMs` 的一半且不超过 15 秒，为直连回退留出时间。用户取消、关闭联网或总超时到期时直接停止，不再发起回退。结果保留请求的目标 URL，不把 Reader 代理地址当作来源。
43
+
44
+ ## 请求限制
45
45
 
46
46
  请求限制包括每条查询的结果上限（`maxResults`）、每次工具调用的查询上限（`maxQueries`）、整个请求的总超时（`timeoutMs`）和网页正文字符上限（`maxFetchChars`）。每次 HTTP 响应仍受 5 MB 字节上限约束。连接测试发送固定查询，不发送作品内容，可能产生一次调用费用。
47
47
 
48
- 加入 tools 入口后，模型获得 `@deepseek-ai/dsh-tool-web` 的官方 `web_search` 与 `web_fetch` 工具，仅在搜索与网页读取开启时挂载。
48
+ ## 模型工具
49
49
 
50
- 只配置可信 HTTPS 端点，密钥会发送到该地址。凭据由 DSH 保存，落盘保护取决于其后端配置。用量计数是调用尝试，不等于账单或消费上限。
50
+ 模型需要使用这些工具时，在所用 `agent.cordis.yml` 的插件列表加入：
51
51
 
52
- 关闭受管后端会取消其请求，但不能阻止其它插件自行联网。搜索结果是外部资料，不授权修改稿件。
52
+ ```yaml
53
+ - name: '@klarkxy/dsh-web-search-manager/tools'
54
+ ```
53
55
 
54
- 若部署环境的供应商覆盖与设置页冲突，移除冲突的覆盖配置。设置保存失败时，受管联网会暂停，成功保存后恢复。
56
+ 加入后，模型获得 `@deepseek-ai/dsh-tool-web` 的官方 `web_search` 与 `web_fetch` 工具，仅在搜索与网页读取开启时挂载。
55
57
 
56
58
  ## 扩展与开发
57
59
 
@@ -61,10 +63,21 @@ dsh plugin --profile web add @klarkxy/dsh-web-search-manager
61
63
 
62
64
  ```sh
63
65
  pnpm --filter @klarkxy/dsh-web-search-manager typecheck
64
- pnpm exec vitest run packages/dsh-web-search-manager/src
66
+ pnpm --filter @klarkxy/dsh-web-search-manager test
65
67
  pnpm --filter @klarkxy/dsh-web-search-manager build
66
68
  ```
67
69
 
68
70
  测试使用模拟凭据和响应，不产生搜索费用。
69
71
 
70
- [发布维护](https://github.com/klarkxy/dsh-editor/blob/main/packages/PUBLISHING.md) · [许可证](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/LICENSE)
72
+ ## 边界与限制
73
+
74
+ - 只配置可信 HTTPS 端点，密钥会发送到该地址。
75
+ - 凭据由 DSH 存储保存，落盘保护取决于其后端配置。
76
+ - 用量计数是调用尝试，不等于账单或消费上限。
77
+ - 目标 URL 会发送给第三方服务 Jina，请勿提交含私密令牌或其它敏感信息的 URL。
78
+ - 关闭受管后端会取消其请求，但不能阻止其它插件自行联网。
79
+ - 搜索结果是外部资料，不授权修改稿件。
80
+ - 若部署环境的供应商覆盖与设置页的选择冲突，移除冲突的覆盖配置。
81
+ - 设置保存失败时，受管联网会暂停，成功保存后恢复。
82
+
83
+ [发布维护](../../PUBLISHING.md) · [许可证](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/LICENSE)