@klarkxy/dsh-web-search-manager 0.1.1 → 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 +17 -65
- package/docs/README.zh-CN.md +51 -0
- package/package.json +3 -3
- package/README.zh-CN.md +0 -75
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
|
-
[简体中文](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/README.zh-CN.md)
|
|
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)
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# @klarkxy/dsh-web-search-manager
|
|
2
|
+
|
|
3
|
+
在一个设置页中配置 DSH 网络搜索与网页读取。
|
|
4
|
+
|
|
5
|
+
[English](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/README.md)
|
|
6
|
+
|
|
7
|
+
## 安装
|
|
8
|
+
|
|
9
|
+
需要 Node.js ≥22、DSH `0.1.5-rc.2`，无需构建本仓库。
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
dsh plugin --profile web add @klarkxy/dsh-web-search-manager
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
重启 DSH Web，打开「设置 → 网络搜索」。模型需要使用搜索工具时，在所用 `agent.cordis.yml` 的插件列表加入：
|
|
16
|
+
|
|
17
|
+
```yaml
|
|
18
|
+
- name: '@klarkxy/dsh-web-search-manager/tools'
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
DSH Editor 已内置此插件、模型工具及 Tavily 适配器。
|
|
22
|
+
|
|
23
|
+
## 配置搜索
|
|
24
|
+
|
|
25
|
+
默认开启 DuckDuckGo，无需密钥。需要其它后端时在设置中开启并填写凭据；一个可用后端即可。DeepSeek 共用模型设置中的密钥，可能产生额外搜索费用。
|
|
26
|
+
|
|
27
|
+
按优先级使用第一个就绪后端，缺密钥的跳过，失败不自动换家。开启搜索也会启用公开网页读取。连接测试发送固定查询，不发送作品内容，可能产生一次调用费用。
|
|
28
|
+
|
|
29
|
+
安装 [@klarkxy/dsh-zhihu](https://www.npmjs.com/package/@klarkxy/dsh-zhihu) 后，「知乎全网搜索」共用知乎设置中的 Access Secret。
|
|
30
|
+
|
|
31
|
+
只配置可信 HTTPS 端点，密钥会发送到该地址。凭据由 DSH 保存，落盘保护取决于其后端配置。用量计数是调用尝试，不等于账单或消费上限。
|
|
32
|
+
|
|
33
|
+
关闭受管后端会取消其请求，但不能阻止其它插件自行联网。搜索结果是外部资料，不授权修改稿件。
|
|
34
|
+
|
|
35
|
+
若部署环境的供应商覆盖与设置页冲突，移除冲突的覆盖配置。设置保存失败时，受管联网会暂停，成功保存后恢复。
|
|
36
|
+
|
|
37
|
+
## 扩展与开发
|
|
38
|
+
|
|
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()` 只检查本地状态，不发送网络请求。
|
|
40
|
+
|
|
41
|
+
在仓库根运行：
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
pnpm --filter @klarkxy/dsh-web-search-manager typecheck
|
|
45
|
+
pnpm exec vitest run packages/dsh-web-search-manager/src
|
|
46
|
+
pnpm --filter @klarkxy/dsh-web-search-manager build
|
|
47
|
+
```
|
|
48
|
+
|
|
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",
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"lib",
|
|
35
35
|
"cordis.patch.yml",
|
|
36
36
|
"README.md",
|
|
37
|
-
"README.zh-CN.md",
|
|
37
|
+
"docs/README.zh-CN.md",
|
|
38
38
|
"LICENSE"
|
|
39
39
|
],
|
|
40
40
|
"dsh": {
|
|
@@ -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",
|
package/README.zh-CN.md
DELETED
|
@@ -1,75 +0,0 @@
|
|
|
1
|
-
# @klarkxy/dsh-web-search-manager
|
|
2
|
-
|
|
3
|
-
[English](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/README.md)
|
|
4
|
-
|
|
5
|
-
DSH `0.1.5-rc.2` 的独立网络搜索管理插件。提供设置页、明确授权、供应商管理描述和生命周期控制；不实现第二套搜索执行服务。
|
|
6
|
-
|
|
7
|
-
## 安装到 DSH Web
|
|
8
|
-
|
|
9
|
-
需要 Node.js 22 或更高版本，以及 DSH `0.1.5-rc.2` 的 Web profile。npm 包名是 `@klarkxy/dsh-web-search-manager`（`web-search` 之间有连字符）。
|
|
10
|
-
|
|
11
|
-
```sh
|
|
12
|
-
dsh plugin --profile web add @klarkxy/dsh-web-search-manager
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
安装后重启 `dsh web`，进入 **设置 → 网络搜索**。模型需要使用搜索工具时，还需在所用 `agent.cordis.yml` 的插件列表中加入：
|
|
16
|
-
|
|
17
|
-
```yaml
|
|
18
|
-
- name: "@klarkxy/dsh-web-search-manager/tools"
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
包内附带编译后的 Host、Web 客户端、类型声明与 `cordis.patch.yml`，安装时无需克隆或构建本仓库。发布状态与市场收录见[插件发布与发现](https://github.com/klarkxy/dsh-editor/blob/main/docs/plugin-distribution.md)。
|
|
22
|
-
|
|
23
|
-
## 使用
|
|
24
|
-
|
|
25
|
-
桌面默认组合安装此插件，Tavily 与其它搜索供应商一同内置。进入 **设置 → 网络搜索**：只需开启一个后端。默认只打开 DuckDuckGo；Brave、博查、Serper、Firecrawl、Exa、DeepSeek、Tavily 需自行注册（各有注册链接）。同一 profile 若还装了知乎资料，会多出一个「知乎全网搜索」后端，与知乎设置共用 Access Secret。打开后按优先级选用第一个已就绪的后端；缺 Key 的跳过，单次失败不换家。模型只看到官方 `web_search`。打开搜索时会同时挂上本机公开网页读取。DeepSeek 搜索复用模型设置中的 API Key，并可能产生额外搜索费用。测试连接是用户主动触发的固定查询，可能产生一次供应商调用费用，不发送作品内容。
|
|
26
|
-
|
|
27
|
-
DeepSeek 搜索复用 `@deepseek-ai/dsh-web-search-deepseek`（Anthropic 兼容 `web_search`），Exa 复用官方 `ExaSearchProvider`，HTTP 读取复用 `HttpFetchProvider` 的公开地址、DNS 固定和重定向安全策略。DuckDuckGo 无需 Key；其它供应商不会在鉴权或额度失败时自动切换。供应商可配置可信 HTTPS API 端点，密钥将发送到该端点。
|
|
28
|
-
|
|
29
|
-
模型工具由 `@klarkxy/dsh-web-search-manager/tools` 在会话上下文内按授权状态挂载官方 `dsh-tool-web`。关闭、切换配置或卸载供应商会取消正在进行的受管请求。其他业务插件继续使用：
|
|
30
|
-
|
|
31
|
-
```ts
|
|
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
|
-
```
|
|
35
|
-
|
|
36
|
-
Tavily 沿用凭据引用 `DSH_EDITOR_WEB_TAVILY_API_KEY`、供应商 ID `tavily` 与原有排序和端点配置。使用 basic 搜索，不自动升级深度、不重试计费请求、不跟随重定向转发密钥。无需额外安装 Tavily 插件。
|
|
37
|
-
|
|
38
|
-
## 扩展供应商
|
|
39
|
-
|
|
40
|
-
独立插件注入 `webSearchManager`，使用管理注册接口贡献描述和工厂。管理层把受授权保护的标准 `WebSearchProvider` 注册到 **现有 `ctx.web`**；供应商选择和结果协议仍归 DSH 管理。
|
|
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
|
-
```
|
|
52
|
-
|
|
53
|
-
工厂遵循 `ProviderOptions`，返回标准 `WebSearchProvider`，必须传递取消信号。`available()` 只检查本地状态，不进行联网测试。无 Key 的搜索后端可以不声明凭据引用。纯网页读取供应商可通过 `registerFetchProvider` 注册；Editor 在启用搜索时同时挂上本机 HTTP 读取。内置 Tavily 适配器位于 `src/tavily.ts`。
|
|
54
|
-
|
|
55
|
-
独立 DSH 部署还需在所用的 `agent.cordis.yml` 加入 `name: "@klarkxy/dsh-web-search-manager/tools"`。Editor 的组合构建会为已选择该能力的应用自带写作预设加入这一入口；未选择该插件的组合不会产生悬空引用。
|
|
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
|
-
## 验证
|
|
68
|
-
|
|
69
|
-
```sh
|
|
70
|
-
pnpm --filter @klarkxy/dsh-web-search-manager typecheck
|
|
71
|
-
pnpm exec vitest run packages/dsh-web-search-manager/src
|
|
72
|
-
pnpm --filter @klarkxy/dsh-web-search-manager build
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
测试使用模拟 Key 和响应，不产生真实搜索费用。
|