@klarkxy/dsh-web-search-manager 0.1.0

package/LICENSE

@@ -0,0 +1,41 @@
+            The Star And Thank Author License (SATA)
+                  Version 2.1, September 2026
+
+Copyright © 2026 Klarkxy(278370456@qq.com)
+
+Project Url: https://github.com/klarkxy/dsh-editor
+             https://github.com/klarkxy/sata-license
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+And wait, one more thing — an invitation, not a condition: it would be best if
+you star/+1/like the project(s) in the project url section above, and thank the
+author(s) in the Copyright section. You may, and arguably you should — but the
+permissions above hold either way, star or no star.
+
+Here are some suggested ways:
+
+ - Email the authors a thank-you letter, and make friends with him/her/them.
+ - Report bugs or issues.
+ - Tell friends what a wonderful project this is.
+ - And, sure, you can just express thanks in your mind without telling the world.
+
+Contributors of this project by forking have the option to add his/her name and
+forked project url at copyright and project url sections, but shall not delete
+or modify anything else in these two sections.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @klarkxy/dsh-web-search-manager
+
+DSH `0.1.5-rc.2` 的独立网络搜索管理插件。提供设置页、明确授权、供应商管理描述和生命周期控制；不实现第二套搜索执行服务。
+
+## 安装到 DSH Web
+
+需要 Node.js 22 或更高版本，以及 DSH `0.1.5-rc.2` 的 Web profile。npm 包名是 `@klarkxy/dsh-web-search-manager`（`web-search` 之间有连字符）。
+
+```sh
+dsh plugin --profile web add @klarkxy/dsh-web-search-manager
+```
+
+安装后重启 `dsh web`，进入 **设置 → 网络搜索**。模型需要使用搜索工具时，还需在所用 `agent.cordis.yml` 的插件列表中加入：
+
+```yaml
+- name: "@klarkxy/dsh-web-search-manager/tools"
+```
+
+包内附带编译后的 Host、Web 客户端、类型声明与 `cordis.patch.yml`，安装时无需克隆或构建本仓库。发布状态与市场收录见[插件发布与发现](https://github.com/klarkxy/dsh-editor/blob/main/docs/plugin-distribution.md)。
+
+## 使用
+
+桌面默认组合安装此插件，Tavily 与其它搜索供应商一同内置。进入 **设置 → 网络搜索**：只需开启一个后端。默认只打开 DuckDuckGo；Brave、博查、Serper、Firecrawl、Exa、DeepSeek、Tavily 需自行注册（各有注册链接）。同一 profile 若还装了知乎资料，会多出一个「知乎全网搜索」后端，与知乎设置共用 Access Secret。打开后按优先级选用第一个已就绪的后端；缺 Key 的跳过，单次失败不换家。模型只看到官方 `web_search`。打开搜索时会同时挂上本机公开网页读取。DeepSeek 搜索复用模型设置中的 API Key，并可能产生额外搜索费用。测试连接是用户主动触发的固定查询，可能产生一次供应商调用费用，不发送作品内容。
+
+DeepSeek 搜索复用 `@deepseek-ai/dsh-web-search-deepseek`（Anthropic 兼容 `web_search`），Exa 复用官方 `ExaSearchProvider`，HTTP 读取复用 `HttpFetchProvider` 的公开地址、DNS 固定和重定向安全策略。DuckDuckGo 无需 Key；其它供应商不会在鉴权或额度失败时自动切换。供应商可配置可信 HTTPS API 端点，密钥将发送到该端点。
+
+模型工具由 `@klarkxy/dsh-web-search-manager/tools` 在会话上下文内按授权状态挂载官方 `dsh-tool-web`。关闭、切换配置或卸载供应商会取消正在进行的受管请求。其他业务插件继续使用：
+
+```ts
+const result = await ctx.web.search({ query: 'example', maxResults: 5 }, signal)
+const page = await ctx.web.fetch({ url: 'https://example.com' }, signal)
+```
+
+Tavily 沿用凭据引用 `DSH_EDITOR_WEB_TAVILY_API_KEY`、供应商 ID `tavily` 与原有排序和端点配置。使用 basic 搜索，不自动升级深度、不重试计费请求、不跟随重定向转发密钥。无需额外安装 Tavily 插件。
+
+## 扩展供应商
+
+独立插件注入 `webSearchManager`，使用管理注册接口贡献描述和工厂。管理层把受授权保护的标准 `WebSearchProvider` 注册到 **现有 `ctx.web`**；供应商选择和结果协议仍归 DSH 管理。
+
+```ts
+export const inject = ['webSearchManager']
+export function apply(ctx) {
+  ctx.effect(() => ctx.webSearchManager.registerSearchProvider({
+    id: 'example', label: 'Example Search', description: 'Independent REST search',
+    defaultBaseURL: 'https://search.example.com',
+    credentialRef: 'DSH_EDITOR_WEB_EXAMPLE_API_KEY', billing: 'request',
+  }, options => new ExampleProvider(options)))
+}
+```
+
+工厂遵循 `ProviderOptions`，返回标准 `WebSearchProvider`，必须传递取消信号。`available()` 只检查本地状态，不进行联网测试。无 Key 的搜索后端可以不声明凭据引用。纯网页读取供应商可通过 `registerFetchProvider` 注册；Editor 在启用搜索时同时挂上本机 HTTP 读取。内置 Tavily 适配器位于 `src/tavily.ts`。
+
+独立 DSH 部署还需在所用的 `agent.cordis.yml` 加入 `name: "@klarkxy/dsh-web-search-manager/tools"`。Editor 的组合构建会为已选择该能力的应用自带写作预设加入这一入口；未选择该插件的组合不会产生悬空引用。
+
+## 边界与安全
+
+- 设置通过 Host 的认证/来源检查，按版本号串行保存，配置不包含密钥。凭据写入现有 Host 凭据服务，每次请求重新解析，不复制到环境变量或模型上下文。现有凭据后端的落盘保护取决于 DSH 配置，本插件不宣称操作系统密钥库加密。
+- 默认只开启 DuckDuckGo。其它后端须手动打开并填写 Key。只需开启一个。打开后按优先级使用第一个已就绪的后端；缺 Key 的跳过。单次请求失败不会自动换下一家。
+- 全局 `ctx.web` 的环境供应商选择覆盖可能与管理页选择冲突，此时 DSH 会拒绝调用，不进行隐藏回退。移除这类部署覆盖再使用设置页选择供应商。
+- 管理接口的关闭操作约束受管供应商，不是任意第三方插件 HTTP 请求的网络沙箱。自行绕过管理注册直接发 HTTP 的插件不在此授权边界内。
+- API Key 输入不落本地存储。界面删除前先停用搜索；并发设置有 revision 冲突检查。配置保存失败时，本次 Host 运行暂停受管网络访问。
+- 网页和搜索结果是外部不可信资料，不授权模型执行网页内指令，也不改变写作提案和作者确认边界。
+- 查询数量、结果数、超时及正文长度有边界，但不是美元预算上限。当前运行的计数只统计适配器调用尝试，不保存查询或正文，不声称等于供应商账单。模型原生搜索的内部计费与精确账单仍应由对应扩展另行提供。
+
+## 验证
+
+```sh
+pnpm --filter @klarkxy/dsh-web-search-manager typecheck
+pnpm exec vitest run packages/dsh-web-search-manager/src
+pnpm --filter @klarkxy/dsh-web-search-manager build
+```
+
+测试使用模拟 Key 和响应，不产生真实搜索费用。

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# Explicit provider authorization replaces the base bundle's automatic DeepSeek path.
+# Keep DSH's registry; availability of each managed provider determines selection.
+- id: web
+  config: {}
+- id: web-search-deepseek
+  disabled: true
+- id: web-fetch-http
+  disabled: true
+- id: tool-web
+  disabled: true
+- insert:
+    - id: web-search-manager
+      name: '@klarkxy/dsh-web-search-manager'