@klarkxy/dsh-web-search-manager 0.1.2 → 0.1.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 +16 -64
- package/docs/README.zh-CN.md +20 -44
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,90 +1,42 @@
|
|
|
1
1
|
# @klarkxy/dsh-web-search-manager
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Configure DSH web search providers and page fetching from one settings page.
|
|
4
4
|
|
|
5
5
|
[简体中文](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/docs/README.zh-CN.md)
|
|
6
6
|
|
|
7
|
-
## Install
|
|
7
|
+
## Install
|
|
8
8
|
|
|
9
|
-
Requires Node.js 22
|
|
9
|
+
Requires Node.js ≥22 and DSH `0.1.5-rc.2`. No repository build is needed.
|
|
10
10
|
|
|
11
11
|
```sh
|
|
12
12
|
dsh plugin --profile web add @klarkxy/dsh-web-search-manager
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
Restart
|
|
15
|
+
Restart DSH Web and open **Settings → Web search**. For agent access, add this entry to the plugin list in its `agent.cordis.yml`:
|
|
16
16
|
|
|
17
17
|
```yaml
|
|
18
18
|
- name: '@klarkxy/dsh-web-search-manager/tools'
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
DSH Editor already includes the plugin, its tools, and the Tavily adapter.
|
|
22
22
|
|
|
23
|
-
##
|
|
23
|
+
## Configure search
|
|
24
24
|
|
|
25
|
-
DuckDuckGo is enabled by default and requires no
|
|
25
|
+
DuckDuckGo is enabled by default and requires no key. Enable another provider and configure credentials in settings if needed; one ready provider is enough. DeepSeek shares the key from model settings and may incur additional search charges.
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
The first ready provider by priority is used. Missing credentials are skipped; failed requests do not automatically switch providers. Enabling search also enables public-page fetching. A connection test sends a fixed query, not manuscript content, and may incur a provider charge.
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
With [@klarkxy/dsh-zhihu](https://www.npmjs.com/package/@klarkxy/dsh-zhihu) installed, **Zhihu global search** shares the Access Secret from Zhihu settings.
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
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.
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
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.
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
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.
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
## Extend or develop
|
|
38
38
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
```ts
|
|
42
|
-
const result = await ctx.web.search({ query: 'example', maxResults: 5 }, signal)
|
|
43
|
-
const page = await ctx.web.fetch({ url: 'https://example.com' }, signal)
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
DeepSeek uses `@deepseek-ai/dsh-web-search-deepseek` and its Anthropic-compatible `web_search` support. Exa uses the official `ExaSearchProvider`. Page fetching uses `HttpFetchProvider`, including its public-address checks, DNS pinning, and redirect restrictions.
|
|
47
|
-
|
|
48
|
-
The bundled Tavily adapter retains provider ID `tavily`, credential reference `DSH_EDITOR_WEB_TAVILY_API_KEY`, and existing priority and endpoint settings. It uses basic search, does not upgrade search depth automatically, does not retry billable requests, and does not forward keys through redirects. A separate Tavily plugin is not required.
|
|
49
|
-
|
|
50
|
-
## Add a provider
|
|
51
|
-
|
|
52
|
-
A plugin can inject `webSearchManager` and register a provider descriptor and factory. The manager registers an authorized standard `WebSearchProvider` with the existing `ctx.web` service; DSH retains provider selection and the search result contract.
|
|
53
|
-
|
|
54
|
-
The following sketch assumes you have implemented `ExampleProvider`:
|
|
55
|
-
|
|
56
|
-
```ts
|
|
57
|
-
export const inject = ['webSearchManager']
|
|
58
|
-
|
|
59
|
-
export function apply(ctx) {
|
|
60
|
-
ctx.effect(() => ctx.webSearchManager.registerSearchProvider({
|
|
61
|
-
id: 'example',
|
|
62
|
-
label: 'Example Search',
|
|
63
|
-
description: 'Independent REST search',
|
|
64
|
-
defaultBaseURL: 'https://search.example.com',
|
|
65
|
-
credentialRef: 'DSH_EDITOR_WEB_EXAMPLE_API_KEY',
|
|
66
|
-
billing: 'request',
|
|
67
|
-
}, options => new ExampleProvider(options)))
|
|
68
|
-
}
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
The factory accepts `ProviderOptions` and returns a standard `WebSearchProvider`. Providers must forward cancellation signals. Their `available()` method checks local state only; it must not make a network request. Providers that do not require a key can omit the credential reference.
|
|
72
|
-
|
|
73
|
-
Use `registerFetchProvider` to register a page-fetching provider. The built-in Tavily adapter in `src/tavily.ts` is a concrete search-provider example.
|
|
74
|
-
|
|
75
|
-
Standalone DSH deployments need the `/tools` entry shown above in each relevant `agent.cordis.yml`. DSH Editor's composition build adds it to bundled writing presets when this feature is selected.
|
|
76
|
-
|
|
77
|
-
## Credentials and authorization
|
|
78
|
-
|
|
79
|
-
- Settings use the host's authentication and origin checks. Saves are serialized and checked for revision conflicts. Provider configuration does not contain secrets.
|
|
80
|
-
- Credentials are stored through the existing DSH host credential service and resolved for each request. They are not copied into environment variables or model context. Protection at rest depends on the DSH credential backend; this plugin does not guarantee operating-system keychain encryption.
|
|
81
|
-
- API key inputs are not saved to browser local storage. The UI disables search before deleting a key. If saving configuration fails, managed network access is paused for the current host process.
|
|
82
|
-
- Global `ctx.web` environment overrides can conflict with the settings page's provider selection. DSH rejects the call in that case; remove the conflicting deployment override to use the settings selection.
|
|
83
|
-
- Disabling managed providers controls requests made through this registration API. It does not sandbox arbitrary HTTP calls made directly by other plugins.
|
|
84
|
-
- Search results and fetched pages are untrusted external material. They do not authorize instructions embedded in a page or change the application's author-confirmation requirements.
|
|
85
|
-
- Query count, result count, timeouts, and response length are bounded. These limits are not a monetary budget. Runtime counters track adapter call attempts without retaining queries or page bodies; they are not provider billing statements. Provider-specific extensions must supply exact billing or model-native search accounting where needed.
|
|
86
|
-
|
|
87
|
-
## Development
|
|
39
|
+
Use DSH's existing `ctx.web` service. For a provider extension, see [manager contracts](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/src/contracts.ts), [built-in registration](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/src/builtins.ts), and the [Tavily adapter](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/src/tavily.ts). Forward cancellation signals; `available()` must check local state without a network request.
|
|
88
40
|
|
|
89
41
|
From the repository root:
|
|
90
42
|
|
|
@@ -94,6 +46,6 @@ pnpm exec vitest run packages/dsh-web-search-manager/src
|
|
|
94
46
|
pnpm --filter @klarkxy/dsh-web-search-manager build
|
|
95
47
|
```
|
|
96
48
|
|
|
97
|
-
Tests use mock credentials and responses and
|
|
49
|
+
Tests use mock credentials and responses and incur no search charges.
|
|
98
50
|
|
|
99
|
-
|
|
51
|
+
[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)
|
package/docs/README.zh-CN.md
CHANGED
|
@@ -1,70 +1,44 @@
|
|
|
1
1
|
# @klarkxy/dsh-web-search-manager
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
在一个设置页中配置 DSH 网络搜索与网页读取。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[English](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/README.md)
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## 安装
|
|
8
8
|
|
|
9
|
-
需要 Node.js 22
|
|
9
|
+
需要 Node.js ≥22、DSH `0.1.5-rc.2`，无需构建本仓库。
|
|
10
10
|
|
|
11
11
|
```sh
|
|
12
12
|
dsh plugin --profile web add @klarkxy/dsh-web-search-manager
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
重启 DSH Web，打开「设置 → 网络搜索」。模型需要使用搜索工具时，在所用 `agent.cordis.yml` 的插件列表加入：
|
|
16
16
|
|
|
17
17
|
```yaml
|
|
18
|
-
- name:
|
|
18
|
+
- name: '@klarkxy/dsh-web-search-manager/tools'
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
DSH Editor 已内置此插件、模型工具及 Tavily 适配器。
|
|
22
22
|
|
|
23
|
-
##
|
|
23
|
+
## 配置搜索
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
默认开启 DuckDuckGo，无需密钥。需要其它后端时在设置中开启并填写凭据；一个可用后端即可。DeepSeek 共用模型设置中的密钥，可能产生额外搜索费用。
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
按优先级使用第一个就绪后端，缺密钥的跳过，失败不自动换家。开启搜索也会启用公开网页读取。连接测试发送固定查询，不发送作品内容，可能产生一次调用费用。
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
安装 [@klarkxy/dsh-zhihu](https://www.npmjs.com/package/@klarkxy/dsh-zhihu) 后，「知乎全网搜索」共用知乎设置中的 Access Secret。
|
|
30
30
|
|
|
31
|
-
|
|
32
|
-
const result = await ctx.web.search({ query: 'example', maxResults: 5 }, signal)
|
|
33
|
-
const page = await ctx.web.fetch({ url: 'https://example.com' }, signal)
|
|
34
|
-
```
|
|
31
|
+
只配置可信 HTTPS 端点，密钥会发送到该地址。凭据由 DSH 保存，落盘保护取决于其后端配置。用量计数是调用尝试，不等于账单或消费上限。
|
|
35
32
|
|
|
36
|
-
|
|
33
|
+
关闭受管后端会取消其请求，但不能阻止其它插件自行联网。搜索结果是外部资料，不授权修改稿件。
|
|
37
34
|
|
|
38
|
-
|
|
35
|
+
若部署环境的供应商覆盖与设置页冲突，移除冲突的覆盖配置。设置保存失败时，受管联网会暂停，成功保存后恢复。
|
|
39
36
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
```ts
|
|
43
|
-
export const inject = ['webSearchManager']
|
|
44
|
-
export function apply(ctx) {
|
|
45
|
-
ctx.effect(() => ctx.webSearchManager.registerSearchProvider({
|
|
46
|
-
id: 'example', label: 'Example Search', description: 'Independent REST search',
|
|
47
|
-
defaultBaseURL: 'https://search.example.com',
|
|
48
|
-
credentialRef: 'DSH_EDITOR_WEB_EXAMPLE_API_KEY', billing: 'request',
|
|
49
|
-
}, options => new ExampleProvider(options)))
|
|
50
|
-
}
|
|
51
|
-
```
|
|
37
|
+
## 扩展与开发
|
|
52
38
|
|
|
53
|
-
|
|
39
|
+
复用 DSH 的 `ctx.web`。扩展供应商可参照[管理接口](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/src/contracts.ts)、[内置注册](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/src/builtins.ts)和 [Tavily 适配器](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/src/tavily.ts)。须传递取消信号；`available()` 只检查本地状态，不发送网络请求。
|
|
54
40
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
## 边界与安全
|
|
58
|
-
|
|
59
|
-
- 设置通过 Host 的认证/来源检查，按版本号串行保存，配置不包含密钥。凭据写入现有 Host 凭据服务，每次请求重新解析，不复制到环境变量或模型上下文。现有凭据后端的落盘保护取决于 DSH 配置，本插件不宣称操作系统密钥库加密。
|
|
60
|
-
- 默认只开启 DuckDuckGo。其它后端须手动打开并填写 Key。只需开启一个。打开后按优先级使用第一个已就绪的后端；缺 Key 的跳过。单次请求失败不会自动换下一家。
|
|
61
|
-
- 全局 `ctx.web` 的环境供应商选择覆盖可能与管理页选择冲突，此时 DSH 会拒绝调用，不进行隐藏回退。移除这类部署覆盖再使用设置页选择供应商。
|
|
62
|
-
- 管理接口的关闭操作约束受管供应商，不是任意第三方插件 HTTP 请求的网络沙箱。自行绕过管理注册直接发 HTTP 的插件不在此授权边界内。
|
|
63
|
-
- API Key 输入不落本地存储。界面删除前先停用搜索；并发设置有 revision 冲突检查。配置保存失败时，本次 Host 运行暂停受管网络访问。
|
|
64
|
-
- 网页和搜索结果是外部不可信资料，不授权模型执行网页内指令，也不改变写作提案和作者确认边界。
|
|
65
|
-
- 查询数量、结果数、超时及正文长度有边界，但不是美元预算上限。当前运行的计数只统计适配器调用尝试，不保存查询或正文，不声称等于供应商账单。模型原生搜索的内部计费与精确账单仍应由对应扩展另行提供。
|
|
66
|
-
|
|
67
|
-
## 验证
|
|
41
|
+
在仓库根运行：
|
|
68
42
|
|
|
69
43
|
```sh
|
|
70
44
|
pnpm --filter @klarkxy/dsh-web-search-manager typecheck
|
|
@@ -72,4 +46,6 @@ pnpm exec vitest run packages/dsh-web-search-manager/src
|
|
|
72
46
|
pnpm --filter @klarkxy/dsh-web-search-manager build
|
|
73
47
|
```
|
|
74
48
|
|
|
75
|
-
|
|
49
|
+
测试使用模拟凭据和响应，不产生搜索费用。
|
|
50
|
+
|
|
51
|
+
[发布维护](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)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@klarkxy/dsh-web-search-manager",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "Opt-in web search settings and managed provider lifecycle over DSH ctx.web",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"type": "module",
|
|
@@ -109,7 +109,7 @@
|
|
|
109
109
|
"registry": "https://registry.npmjs.org/"
|
|
110
110
|
},
|
|
111
111
|
"dshRelease": {
|
|
112
|
-
"contentHash": "sha256-
|
|
112
|
+
"contentHash": "sha256-7e4c1b2f102f69e49b427bb574c0c858801dd8621d1072625c798e67565c141d"
|
|
113
113
|
},
|
|
114
114
|
"scripts": {
|
|
115
115
|
"build": "tsdown && node ../../scripts/wrap-client.mjs @klarkxy/dsh-web-search-manager",
|