@klarkxy/dsh-web-search-manager 0.1.11 → 0.2.1

package/README.md

@@ -1,29 +1,34 @@
 # @klarkxy/dsh-web-search-manager
 
+<!-- release-state-note -->
+The [repository registry](../../README.md#plugin-lifecycle) tracks Draft → Testing → Published, moving forward only. Fixes, testing and version updates keep published packages Published; each update still passes release checks. First publication explicitly selects Testing packages and records Published only after npm archive verification. See the [release guide](../../RELEASING.md).
+
 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.
 
 [简体中文](docs/README.zh-CN.md)
 
-Requires Node.js ≥22 and DSH `0.1.7-rc.2`. No repository build is needed.
+Requires Node.js ≥22 and DSH `0.2.0-rc.2`. No repository build is needed.
 
 ## Install
 
-```sh
-npm install @klarkxy/dsh-web-search-manager
-```
-
-Then load it:
+Install the published package into the target profile:
 
 ```sh
 dsh plugin --profile web add @klarkxy/dsh-web-search-manager
 ```
 
-Restart DSH Web and open **Plugins → Web search**.
+Replace `web` with your profile name. Restart DSH Web and open **Plugins → Web search**. To uninstall, run `dsh plugin --profile web remove @klarkxy/dsh-web-search-manager`.
 
 ## Configure search
 
 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.
 
+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.
+
+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.
+
+Bundled adapters register natively too. If the official DeepSeek/HTTP id is absent at startup, fallback adapters use `deepseek-managed` / `http-managed`, allowing official providers to register later. Existing choices and endpoints for the old bundle-owned ids migrate in memory without a request or storage write; the next explicit save persists them. If a native provider already owns an old id, its own settings apply and any unchanged old manager endpoint remains stored without being forwarded to that provider.
+
 Built-in search backends:
 
 - **DuckDuckGo**: no registration and no key; the default backend, free of charge.
@@ -37,7 +42,7 @@ Built-in search backends:
 
 ## Read public pages
 
-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.
+Web page fetching has its own switch and selector. If the host already registers `http`, its native fetch behavior and configuration are used. Otherwise this bundle supplies `http-managed`, the existing Jina-first adapter. That adapter 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.
 
 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.
 
@@ -57,7 +62,23 @@ Once that entry is enabled, the agent receives the official `web_search` and `we
 
 ## Extend or develop
 
-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. Provider extensions can supply `pricing`, an HTTPS `pricingUrl`, and `credentialHint` for a shared credential in their registration metadata.
+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.
+
+```ts
+const provider = {
+  id: 'my-search',
+  dshWebManagement: {
+    id: 'my-search', label: 'My search', description: 'Custom search service',
+    billing: 'request', configurationOwner: '@example/my-plugin',
+    configurationUrl: '/plugins/my-plugin',
+  },
+  available: () => locallyConfigured(),
+  search: (request, signal) => searchWithOwnConfiguration(request, signal),
+}
+ctx.web.registerSearchProvider(provider)
+```
+
+DSH 0.2.0-rc.2 has no public registry enumeration or dynamic selection API. This package isolates a compatibility bridge in `web-registry.ts`: it observes the actual host Maps, manages availability and temporarily takes over selection, then restores provider instances and prior config/environment selection on unload. Unsupported host structures fail explicitly instead of omitting providers. Providers can announce local availability changes through the repository extension event `web/provider-availability-updated` (arguments: `search`/`fetch`, id); this is not an official DSH event. Status refreshes and execution also recheck `available()`. After saving migrated adapter ids, downgrading the manager requires reselecting the old routes; credential references and legacy endpoint keys remain stored.
 
 From the repository root:
 
@@ -77,7 +98,7 @@ Tests use mock credentials and responses and incur no search charges.
 - Target URLs are sent to Jina, a third-party service; do not submit URLs containing private tokens or other sensitive data.
 - Disabling a managed provider cancels its requests, but it does not sandbox HTTP calls made directly by other plugins.
 - Search results are external material and cannot authorize changes to manuscripts.
-- If deployment environment overrides conflict with the settings selection, remove the conflicting overrides.
+- While the manager is attached, saved manager selection applies; unloading restores the host’s original config/environment selection.
 - If saving the configuration fails, managed network access pauses until the settings are saved successfully.
 
 [Publishing](../PUBLISHING.md) · [License](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/LICENSE)

package/cordis.patch.yml

@@ -1,11 +1,4 @@
-# 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
+# Keep native provider rows and their own configuration. The manager observes ctx.web.
 - id: tool-web
   disabled: true
 - insert:

package/docs/README.zh-CN.md

@@ -1,29 +1,34 @@
 # @klarkxy/dsh-web-search-manager
 
+<!-- release-state-note -->
+插件生命周期见[仓库状态清单](../../../README.zh-CN.md#插件生命周期)：草稿 → 测试中 → 已发布，只向前推进。已发布插件的修复、测试和升版保持已发布；每次更新仍须通过发布检查。首次发布须明确选择测试中的包，并在 npm 归档验证成功后登记。详见[发布规则](../../../RELEASING.zh-CN.md)。
+
 在一个设置页里挑选用哪个服务回答模型的网络搜索、设定每次请求的上限，并让模型读取公开网页。
 
 [English](../README.md)
 
-需要 Node.js ≥22、DSH `0.1.7-rc.2`，无需构建本仓库。
+需要 Node.js ≥22、DSH `0.2.0-rc.2`，无需构建本仓库。
 
 ## 安装
 
-```sh
-npm install @klarkxy/dsh-web-search-manager
-```
-
-然后加载：
+把已发布包装进目标 profile：
 
 ```sh
 dsh plugin --profile web add @klarkxy/dsh-web-search-manager
 ```
 
-重启 DSH Web，打开「插件 → 网页搜索」。
+把 `web` 换成你的 profile 名。重启 DSH Web，打开「插件 → 网页搜索」。卸载用 `dsh plugin --profile web remove @klarkxy/dsh-web-search-manager`。
 
 ## 配置搜索
 
 设置页分两个标签页：「搜索服务」管理供应商，「请求限制」设置请求限额。默认开启 DuckDuckGo，无需密钥。需要其它后端时在设置中开启并填写凭据；一个可用后端即可。拖拽列表调整顺序，每次请求由顺序中第一个就绪的后端处理。缺密钥的后端直接跳过，失败也不会自动换家。
 
+列表区分本地「可用 / 暂不可用」、是否参与排序（开关），以及仅在真正提供服务时出现的「当前使用」。可用表示本地 `available()` 或凭据状态，不是一次已计费的连通验证。已保存但尚未注册的 id 会留在原位并标为「未加载，保留选择」，直到你关掉它的开关；普通搜索开关、排序和 Key/限制保存不会删掉这些选择，清空顺序也不会把 DuckDuckGo 加回来。
+
+管理器从当前 profile 的 `ctx.web` 发现搜索和抓取服务，包括官方插件和自定义插件在管理器启动前后注册的服务。新发现的服务不会自动加入已启用的搜索顺序。页面在可见时大约每三秒刷新注册和本地可用性，隐藏或卸载后停止。外部服务的配置和凭据仍在所属插件中维护。若提供安全的 `configurationUrl`（HTTPS、同宿主 `/…` 路径或 `#…` 片段），本页给出「打开配置」链接；否则显示配置所属插件名称，未知所属时提示到该服务的插件中配置。本页不会根据 id 或 owner 猜测宿主路由，也不重复编辑其凭据。
+
+内置适配器也走原生注册。如果启动时尚无官方 DeepSeek/HTTP 服务，补充适配器使用 `deepseek-managed` / `http-managed`，让官方服务稍后也能正常注册。旧版内置适配器的选择和端点只在内存中迁移，不发送请求、不写存储；下次用户保存时才持久化。旧 id 已由原生服务占用时使用它自己的设置，原管理器端点原样保留，但不转交给原生服务。
+
 内置搜索后端：
 
 - **DuckDuckGo**：无需注册、无需密钥，默认后端，免费。
@@ -37,7 +42,7 @@ dsh plugin --profile web add @klarkxy/dsh-web-search-manager
 
 ## 读取公开网页
 
-开启搜索也会启用公开网页读取。内置 `http` 路由优先匿名请求 `https://r.jina.ai/<目标 URL>`，返回 Reader 的文本/Markdown；HTTP 错误（含 429）、Reader 超时、网络失败、空内容或无效响应时，回退一次到原有 HTTP 直连读取。此回退只作用于网页读取，不改变搜索后端的选择。无需注册 Jina、配置 API Key 或计费设置，也不增加依赖。
+「网页读取」可单独开启，并选择当前已注册的抓取服务。同名服务优先沿用宿主或其他插件已注册的实例与配置。宿主已有 `http` 时沿用其读取方式；只有未注册 `http` 时，本插件才补充原有 Jina 优先适配器。该适配器优先匿名请求 `https://r.jina.ai/<目标 URL>`，返回 Reader 的文本/Markdown；HTTP 错误（含 429）、Reader 超时、网络失败、空内容或无效响应时，回退一次到原有 HTTP 直连读取。此回退只作用于网页读取，不改变搜索后端的选择。无需注册 Jina、配置 API Key 或计费设置，也不增加依赖。
 
 请求不附带 Cookie 或授权头。IP 字面量、明显的本地主机名、带用户名密码的 URL，以及已经带 Reader 前缀的地址跳过 Jina，继续受原 HTTP 读取器的策略约束。两个阶段复用同一套 HTTP 传输，Reader 阶段最多使用 `timeoutMs` 的一半且不超过 15 秒，为直连回退留出时间。用户取消、关闭联网或总超时到期时直接停止，不再发起回退。结果保留请求的目标 URL，不把 Reader 代理地址当作来源。
 
@@ -57,7 +62,23 @@ dsh plugin --profile web add @klarkxy/dsh-web-search-manager
 
 ## 扩展与开发
 
-复用 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()` 只检查本地状态，不发送网络请求。扩展后端可在注册描述中提供 `pricing`、HTTPS `pricingUrl`；共用凭据时可提供 `credentialHint`，由后端维护自己的设置页文案。
+供应商插件直接调用 `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 注册方法保留为兼容入口，新插件走原生注册。
+
+```ts
+const provider = {
+  id: 'my-search',
+  dshWebManagement: {
+    id: 'my-search', label: 'My search', description: 'Custom search service',
+    billing: 'request', configurationOwner: '@example/my-plugin',
+    configurationUrl: '/plugins/my-plugin',
+  },
+  available: () => locallyConfigured(),
+  search: (request, signal) => searchWithOwnConfiguration(request, signal),
+}
+ctx.web.registerSearchProvider(provider)
+```
+
+DSH 0.2.0-rc.2 尚无公开注册表枚举及动态选择接口，本包将兼容逻辑集中在 `web-registry.ts`：观察宿主实际 Map、管理可用性、临时接管选择，卸载时恢复实例和原有配置/环境选择。不匹配的宿主结构会明确报错，避免遗漏已注册服务。供应商的本地可用性变化可发出本仓库扩展事件 `web/provider-availability-updated`（参数：`search`/`fetch`、id）；它不是官方 DSH 事件。状态刷新和每次执行也会重新检查 `available()`。保存迁移后的适配器 id 后，降级管理器需要重新选择旧路由；凭据引用和旧端点键仍保留。
 
 在仓库根运行：
 
@@ -77,7 +98,7 @@ pnpm --filter @klarkxy/dsh-web-search-manager build
 - 目标 URL 会发送给第三方服务 Jina，请勿提交含私密令牌或其它敏感信息的 URL。
 - 关闭受管后端会取消其请求，但不能阻止其它插件自行联网。
 - 搜索结果是外部资料，不授权修改稿件。
-- 若部署环境的供应商覆盖与设置页的选择冲突，移除冲突的覆盖配置。
+- 管理器运行期间使用已保存的选择；卸载后恢复宿主原有配置和环境变量的选择。
 - 设置保存失败时，受管联网会暂停，成功保存后恢复。
 
 [发布维护](../../PUBLISHING.md) · [许可证](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-web-search-manager/LICENSE)