@klarkxy/dsh-web-search-manager 0.2.2 → 0.2.3
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/README.md +17 -51
- package/docs/README.zh-CN.md +16 -50
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,79 +1,45 @@
|
|
|
1
|
-
|
|
1
|
+
# Web Search
|
|
2
2
|
|
|
3
3
|
<!-- release-state-note -->
|
|
4
4
|
|
|
5
|
-
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.
|
|
6
|
-
|
|
7
5
|
[简体中文](docs/README.zh-CN.md)
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
Choose which service answers the model's web searches, set request limits, and let the model read public web pages — all from one settings page.
|
|
10
8
|
|
|
11
9
|
## Install
|
|
12
10
|
|
|
13
|
-
Install the published package into the target profile:
|
|
14
|
-
|
|
15
11
|
```sh
|
|
16
12
|
dsh plugin --profile web add @klarkxy/dsh-web-search-manager
|
|
17
13
|
```
|
|
18
14
|
|
|
19
|
-
Replace `web` with your profile name
|
|
20
|
-
|
|
21
|
-
## Configure search
|
|
22
|
-
|
|
23
|
-
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.
|
|
24
|
-
|
|
25
|
-
Each row shows local availability (**Available** / **Unavailable**), whether it participates in the order (the switch), and **In use** only for the first ready backend that is actually serving requests. Availability is the local `available()` / credential state, not a billed test. Saved order ids that are not registered stay in place as **Not loaded; selection kept** until you turn that switch off; ordinary search toggles, reordering, and key/limit saves do not drop them, and clearing the order does not revive DuckDuckGo.
|
|
26
|
-
|
|
27
|
-
The manager discovers search and fetch providers in this profile’s `ctx.web`, including official and custom plugins registered before or after it starts. Newly discovered providers do not join the enabled search order automatically. The page refreshes registration and local availability about every three seconds while it is visible, and stops when it is hidden or unmounted. External providers keep their configuration and credentials in their own plugin. If they supply a safe `configurationUrl` (HTTPS, a same-host `/…` path, or a `#…` hash), this page links to it; otherwise it names the configuration owner, or asks you to configure the service in its plugin. This page does not guess host routes from an id or owner, and it does not edit those credentials.
|
|
15
|
+
Replace `web` with your profile name, restart DSH Web, and open **Plugins → Web Search**.
|
|
28
16
|
|
|
29
|
-
|
|
17
|
+
## Set up search
|
|
30
18
|
|
|
31
|
-
|
|
19
|
+
DuckDuckGo works out of the box with no key. You can also enable DeepSeek Search, Exa, Brave, Bocha, Serper, Firecrawl, or Tavily by entering their API keys. Drag the list to set the order; each search uses the first ready service. Search services added by other plugins, such as Zhihu, appear in the same list.
|
|
32
20
|
|
|
33
|
-
|
|
34
|
-
- **DeepSeek 搜索**: shares the DeepSeek API key from model settings (`DEEPSEEK_API_KEY`); may incur additional search charges on top of model usage.
|
|
35
|
-
- **Exa**: an independent Search API; requires its own key (`DSH_EDITOR_WEB_EXA_API_KEY`). The Exa provider is declared as a runtime dependency of this plugin.
|
|
36
|
-
- **Brave**: the Brave Search API; requires `DSH_EDITOR_WEB_BRAVE_API_KEY`.
|
|
37
|
-
- **博查**: a Chinese web search API; requires `DSH_EDITOR_WEB_BOCHA_API_KEY`.
|
|
38
|
-
- **Serper**: a Google results API; requires `DSH_EDITOR_WEB_SERPER_API_KEY`.
|
|
39
|
-
- **Firecrawl**: a web search and extraction API; requires `DSH_EDITOR_WEB_FIRECRAWL_API_KEY`.
|
|
40
|
-
- **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.
|
|
21
|
+
**Request limits** sets the number of results, queries per call, the total timeout, and the maximum page length.
|
|
41
22
|
|
|
42
|
-
## Read
|
|
23
|
+
## Read web pages
|
|
43
24
|
|
|
44
|
-
|
|
25
|
+
Turn on **Web fetch** to let the model read public pages. By default pages are read through the free Jina Reader, falling back to a direct request if that fails.
|
|
45
26
|
|
|
46
|
-
|
|
27
|
+
## Give the tools to the model
|
|
47
28
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
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
|
-
|
|
52
|
-
## Agent tools
|
|
53
|
-
|
|
54
|
-
For agent access, add this entry to the plugin list in the `agent.cordis.yml` you use:
|
|
29
|
+
Add this to the plugin list of the `agent.cordis.yml` you use:
|
|
55
30
|
|
|
56
31
|
```yaml
|
|
57
32
|
- name: '@klarkxy/dsh-web-search-manager/tools'
|
|
58
33
|
```
|
|
59
34
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
## Provider integration
|
|
63
|
-
|
|
64
|
-
Provider plugins call `ctx.web.registerSearchProvider(provider)` or `ctx.web.registerFetchProvider(provider)` directly, with no dependency on `webSearchManager`. Keep `available()` local, forward cancellation signals, and resolve configuration and credentials in the provider. Optional `dshWebManagement` display metadata on the provider can include `label`, `description`, `billing`, `configurationOwner`, `credentialHint`, `pricing`, an HTTPS `pricingUrl`, and an explicit `configurationUrl`. `configurationUrl` is the only settings link: HTTPS, a same-host `/…` path, or a `#…` hash. Do not expect this page to invent a route from `id` or `configurationOwner`. `credentialHint` is display text only. Providers without metadata are discovered under their id. Description and pricing from the provider win over any bundled notes with the same id; bundled adapters may still fall back to their known price list. Native services without pricing metadata show that none was provided. Metadata never contains credential values. The old manager factory methods remain as deprecated compatibility adapters; new plugins use native registration.
|
|
35
|
+
The model then gets `web_search` and `web_fetch` while search and fetch are turned on.
|
|
65
36
|
|
|
66
|
-
|
|
37
|
+
## Limits
|
|
67
38
|
|
|
68
|
-
|
|
39
|
+
- Paid services may charge for searches; the plugin's counts are not a bill.
|
|
40
|
+
- Fetched page addresses are sent to Jina; do not fetch URLs containing private tokens.
|
|
41
|
+
- Failed searches do not switch to another service automatically.
|
|
69
42
|
|
|
70
|
-
|
|
71
|
-
- Credentials are kept in DSH storage, and protection at rest depends on its configured backend.
|
|
72
|
-
- Usage counters are call attempts, not billing statements or a spending cap.
|
|
73
|
-
- Target URLs are sent to Jina, a third-party service; do not submit URLs containing private tokens or other sensitive data.
|
|
74
|
-
- Disabling a managed provider cancels its requests, but it does not sandbox HTTP calls made directly by other plugins.
|
|
75
|
-
- Search results are external material and cannot authorize changes to manuscripts.
|
|
76
|
-
- While the manager is attached, saved manager selection applies; unloading restores the host’s original config/environment selection.
|
|
77
|
-
- If saving the configuration fails, managed network access pauses until the settings are saved successfully.
|
|
43
|
+
## License
|
|
78
44
|
|
|
79
|
-
[License](
|
|
45
|
+
[SATA License 2.1](LICENSE)
|
package/docs/README.zh-CN.md
CHANGED
|
@@ -1,79 +1,45 @@
|
|
|
1
|
-
|
|
1
|
+
# 网页搜索
|
|
2
2
|
|
|
3
3
|
<!-- release-state-note -->
|
|
4
4
|
|
|
5
|
-
在一个设置页里挑选用哪个服务回答模型的网络搜索、设定每次请求的上限，并让模型读取公开网页。
|
|
6
|
-
|
|
7
5
|
[English](../README.md)
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
在一个设置页里选择由哪个服务回答模型的网络搜索、设置请求限制，并让模型读取公开网页。
|
|
10
8
|
|
|
11
9
|
## 安装
|
|
12
10
|
|
|
13
|
-
把已发布包装进目标 profile：
|
|
14
|
-
|
|
15
11
|
```sh
|
|
16
12
|
dsh plugin --profile web add @klarkxy/dsh-web-search-manager
|
|
17
13
|
```
|
|
18
14
|
|
|
19
|
-
把 `web` 换成你的 profile
|
|
15
|
+
把 `web` 换成你的 profile 名，重启 DSH Web 后打开「插件 → 网页搜索」。
|
|
20
16
|
|
|
21
17
|
## 配置搜索
|
|
22
18
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
列表区分本地「可用 / 暂不可用」、是否参与排序（开关），以及仅在真正提供服务时出现的「当前使用」。可用表示本地 `available()` 或凭据状态，不是一次已计费的连通验证。已保存但尚未注册的 id 会留在原位并标为「未加载，保留选择」，直到你关掉它的开关；普通搜索开关、排序和 Key/限制保存不会删掉这些选择，清空顺序也不会把 DuckDuckGo 加回来。
|
|
26
|
-
|
|
27
|
-
管理器从当前 profile 的 `ctx.web` 发现搜索和抓取服务，包括官方插件和自定义插件在管理器启动前后注册的服务。新发现的服务不会自动加入已启用的搜索顺序。页面在可见时大约每三秒刷新注册和本地可用性，隐藏或卸载后停止。外部服务的配置和凭据仍在所属插件中维护。若提供安全的 `configurationUrl`（HTTPS、同宿主 `/…` 路径或 `#…` 片段），本页给出「打开配置」链接；否则显示配置所属插件名称，未知所属时提示到该服务的插件中配置。本页不会根据 id 或 owner 猜测宿主路由，也不重复编辑其凭据。
|
|
28
|
-
|
|
29
|
-
内置适配器也走原生注册。如果启动时尚无官方 DeepSeek/HTTP 服务，补充适配器使用 `deepseek-managed` / `http-managed`，让官方服务稍后也能正常注册。旧版内置适配器的选择和端点只在内存中迁移，不发送请求、不写存储；下次用户保存时才持久化。旧 id 已由原生服务占用时使用它自己的设置，原管理器端点原样保留，但不转交给原生服务。
|
|
30
|
-
|
|
31
|
-
内置搜索后端：
|
|
19
|
+
DuckDuckGo 默认可用，无需密钥。也可以填写 API Key 启用 DeepSeek 搜索、Exa、Brave、博查、Serper、Firecrawl 或 Tavily。拖拽列表调整顺序，每次搜索使用第一个就绪的服务。其他插件提供的搜索服务（例如知乎）也会出现在同一列表中。
|
|
32
20
|
|
|
33
|
-
|
|
34
|
-
- **DeepSeek 搜索**：与模型设置共用 DeepSeek API Key（`DEEPSEEK_API_KEY`），可能在模型费用外产生额外搜索费用。
|
|
35
|
-
- **Exa**：独立 Search API，需要单独的 Key（`DSH_EDITOR_WEB_EXA_API_KEY`）。Exa 供应商已声明为本插件的运行时依赖。
|
|
36
|
-
- **Brave**：Brave Search API，需要 `DSH_EDITOR_WEB_BRAVE_API_KEY`。
|
|
37
|
-
- **博查**：中文网页搜索 API，需要 `DSH_EDITOR_WEB_BOCHA_API_KEY`。
|
|
38
|
-
- **Serper**：Google 结果 Search API，需要 `DSH_EDITOR_WEB_SERPER_API_KEY`。
|
|
39
|
-
- **Firecrawl**：网页搜索与提取 API，需要 `DSH_EDITOR_WEB_FIRECRAWL_API_KEY`。
|
|
40
|
-
- **Tavily**：Search API，固定 basic 检索深度，不自动升级；需要 `DSH_EDITOR_WEB_TAVILY_API_KEY`。适配器已并入本插件。
|
|
21
|
+
「请求限制」用于设置结果条数、每次调用的查询数、总超时和网页正文长度上限。
|
|
41
22
|
|
|
42
|
-
##
|
|
23
|
+
## 读取网页
|
|
43
24
|
|
|
44
|
-
|
|
25
|
+
打开「网页读取」后，模型可以读取公开网页。默认通过免费的 Jina Reader 读取，失败时改为直接请求一次。
|
|
45
26
|
|
|
46
|
-
|
|
27
|
+
## 让模型使用
|
|
47
28
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
请求限制包括每条查询的结果上限（`maxResults`）、每次工具调用的查询上限（`maxQueries`）、整个请求的总超时（`timeoutMs`）和网页正文字符上限（`maxFetchChars`）。每次 HTTP 响应仍受 5 MB 字节上限约束。连接测试发送固定查询，不发送作品内容，可能产生一次调用费用。
|
|
51
|
-
|
|
52
|
-
## 模型工具
|
|
53
|
-
|
|
54
|
-
模型需要使用这些工具时，在所用 `agent.cordis.yml` 的插件列表加入：
|
|
29
|
+
在所用 `agent.cordis.yml` 的插件列表中加入：
|
|
55
30
|
|
|
56
31
|
```yaml
|
|
57
32
|
- name: '@klarkxy/dsh-web-search-manager/tools'
|
|
58
33
|
```
|
|
59
34
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
## 供应商接入
|
|
63
|
-
|
|
64
|
-
供应商插件直接调用 `ctx.web.registerSearchProvider(provider)` 或 `ctx.web.registerFetchProvider(provider)`，无需依赖或调用 `webSearchManager`。`available()` 只检查本地状态；请求须传递取消信号，供应商自行读取自己的配置和凭据。可在供应商对象上添加可选的 `dshWebManagement` 展示元数据（`label`、`description`、`billing`、`configurationOwner`、`credentialHint`、`pricing`、HTTPS `pricingUrl`、显式 `configurationUrl` 等）。`configurationUrl` 是唯一的配置链接，允许 HTTPS、同宿主 `/…` 路径或 `#…` 片段；不要期待本页根据 `id` 或 `configurationOwner` 猜测路由。`credentialHint` 只作展示。不提供元数据也会被发现，列表使用供应商 id。供应商自己的介绍和费用优先；相同 id 的静态说明不会覆盖自定义/原生服务。无费用元数据时显示未提供，不会称为免费或已核对。元数据不携带凭据值。旧的管理器 factory 注册方法保留为兼容入口，新插件走原生注册。
|
|
35
|
+
搜索和网页读取开启时，模型会获得 `web_search` 与 `web_fetch` 工具。
|
|
65
36
|
|
|
66
|
-
|
|
37
|
+
## 限制
|
|
67
38
|
|
|
68
|
-
|
|
39
|
+
- 付费服务可能按次收费；插件的计数不是账单。
|
|
40
|
+
- 读取网页时，网址会发送给 Jina，请勿读取包含私密令牌的链接。
|
|
41
|
+
- 搜索失败时不会自动换用其他服务。
|
|
69
42
|
|
|
70
|
-
|
|
71
|
-
- 凭据由 DSH 存储保存，落盘保护取决于其后端配置。
|
|
72
|
-
- 用量计数是调用尝试，不等于账单或消费上限。
|
|
73
|
-
- 目标 URL 会发送给第三方服务 Jina，请勿提交含私密令牌或其它敏感信息的 URL。
|
|
74
|
-
- 关闭受管后端会取消其请求，但不能阻止其它插件自行联网。
|
|
75
|
-
- 搜索结果是外部资料，不授权修改稿件。
|
|
76
|
-
- 管理器运行期间使用已保存的选择；卸载后恢复宿主原有配置和环境变量的选择。
|
|
77
|
-
- 设置保存失败时，受管联网会暂停，成功保存后恢复。
|
|
43
|
+
## 许可证
|
|
78
44
|
|
|
79
|
-
[
|
|
45
|
+
[SATA License 2.1](../LICENSE)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@klarkxy/dsh-web-search-manager",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.3",
|
|
4
4
|
"description": "Web Search: manage web search providers and public-page fetching from one settings page.",
|
|
5
5
|
"icon": "./icon.svg",
|
|
6
6
|
"license": "SEE LICENSE IN LICENSE",
|
|
@@ -80,7 +80,7 @@
|
|
|
80
80
|
},
|
|
81
81
|
"dependencies": {
|
|
82
82
|
"@deepseek-ai/dsh-web-search-exa": ">=0.2.0-rc.2",
|
|
83
|
-
"@klarkxy/dsh-plugin-kit": "0.3.
|
|
83
|
+
"@klarkxy/dsh-plugin-kit": "0.3.2",
|
|
84
84
|
"zod": "^4.1.5"
|
|
85
85
|
},
|
|
86
86
|
"peerDependencies": {
|
|
@@ -149,6 +149,6 @@
|
|
|
149
149
|
"registry": "https://registry.npmjs.org/"
|
|
150
150
|
},
|
|
151
151
|
"dshRelease": {
|
|
152
|
-
"contentHash": "
|
|
152
|
+
"contentHash": "66df462c441df4ca97e830853013ebd47921f89ccd2d7ab96ed9fe0cec8fe89b"
|
|
153
153
|
}
|
|
154
154
|
}
|