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

package/lib/index.js

@@ -1,10 +1,11 @@
-import { WEB_SEARCH_RPC_CHANNEL, defaultSettings, migrateSearchOrder, pickActiveSearch, providerKey, resolveSearchOrder, validateBaseURL } from "./contracts.js";
+import { WEB_MANAGER_OWNER, WEB_SEARCH_RPC_CHANNEL, defaultSettings, migrateSearchOrder, pickActiveSearch, providerKey, resolveSearchOrder, safeConfigurationUrl, validateBaseURL } from "./contracts.js";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { WebError } from "@deepseek-ai/dsh-web";
 import { DEEPSEEK_DEFAULT_API_VERSION, DEEPSEEK_DEFAULT_BASE_URL, DEEPSEEK_DEFAULT_MAX_TOKENS, DEEPSEEK_DEFAULT_MAX_USES, DEEPSEEK_DEFAULT_MODEL, DeepSeekSearchProvider } from "@deepseek-ai/dsh-web-search-deepseek";
 import { ExaSearchProvider } from "@deepseek-ai/dsh-web-search-exa";
 import { HttpFetchProvider } from "@deepseek-ai/dsh-web-fetch-http";
 import { isIP } from "node:net";
+import { registerHostRpc } from "@klarkxy/dsh-plugin-kit/host-rpc";
 import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 import { z } from "zod";
 //#region src/jina-fetch.ts
@@ -547,225 +548,331 @@ var TavilySearchProvider = class {
 	}
 };
 //#endregion
-//#region src/builtins.ts
-function registerBuiltins(manager) {
-	const offEngine = manager.registerSearchProvider({
-		id: "ddg",
-		label: "DuckDuckGo",
-		billing: "none",
-		description: "无需注册。默认后端。"
-	}, () => new SearchEngineProvider());
-	const offDeepSeek = manager.registerSearchProvider({
-		id: "deepseek-official",
-		label: "DeepSeek 搜索",
-		description: "使用已配置的 DeepSeek API Key，可能产生额外搜索费用。",
-		defaultBaseURL: DEEPSEEK_DEFAULT_BASE_URL,
-		credentialRef: "DEEPSEEK_API_KEY",
-		credentialShared: true,
-		credentialHint: "与模型设置共用 Key",
-		billing: "model-and-tools",
-		signupUrl: "https://platform.deepseek.com/api_keys"
-	}, (options) => new DeepSeekSearchProvider(() => ({
-		apiKey: options.apiKey,
-		baseURL: options.baseURL ?? DEEPSEEK_DEFAULT_BASE_URL,
-		model: DEEPSEEK_DEFAULT_MODEL,
-		apiVersion: DEEPSEEK_DEFAULT_API_VERSION,
-		maxTokens: DEEPSEEK_DEFAULT_MAX_TOKENS,
-		maxUses: DEEPSEEK_DEFAULT_MAX_USES
-	})));
-	const offExa = manager.registerSearchProvider({
-		id: "exa",
-		label: "Exa",
-		description: "独立 Search API。",
-		defaultBaseURL: "https://api.exa.ai",
-		credentialRef: "DSH_EDITOR_WEB_EXA_API_KEY",
-		billing: "request",
-		signupUrl: "https://dashboard.exa.ai/api-keys"
-	}, (options) => new ExaSearchProvider({
-		apiKey: options.apiKey ?? "",
-		baseURL: options.baseURL ?? "https://api.exa.ai",
-		searchType: "auto",
-		highlightsPerResult: 1
-	}));
-	const offBrave = manager.registerSearchProvider({
-		id: "brave",
-		label: "Brave",
-		description: "Brave Search API。",
-		defaultBaseURL: "https://api.search.brave.com",
-		credentialRef: "DSH_EDITOR_WEB_BRAVE_API_KEY",
-		billing: "request",
-		signupUrl: "https://api.search.brave.com"
-	}, (options) => new BraveSearchProvider({
-		apiKey: options.apiKey ?? "",
-		baseURL: options.baseURL
-	}));
-	const offBocha = manager.registerSearchProvider({
-		id: "bocha",
-		label: "博查",
-		description: "中文网页搜索 API。",
-		defaultBaseURL: "https://api.bochaai.com",
-		credentialRef: "DSH_EDITOR_WEB_BOCHA_API_KEY",
-		billing: "request",
-		signupUrl: "https://open.bochaai.com"
-	}, (options) => new BochaSearchProvider({
-		apiKey: options.apiKey ?? "",
-		baseURL: options.baseURL
-	}));
-	const offSerper = manager.registerSearchProvider({
-		id: "serper",
-		label: "Serper",
-		description: "Google 结果的 Search API。",
-		defaultBaseURL: "https://google.serper.dev",
-		credentialRef: "DSH_EDITOR_WEB_SERPER_API_KEY",
-		billing: "request",
-		signupUrl: "https://serper.dev"
-	}, (options) => new SerperSearchProvider({
-		apiKey: options.apiKey ?? "",
-		baseURL: options.baseURL
-	}));
-	const offFirecrawl = manager.registerSearchProvider({
-		id: "firecrawl",
-		label: "Firecrawl",
-		description: "网页搜索与提取 API。",
-		defaultBaseURL: "https://api.firecrawl.dev",
-		credentialRef: "DSH_EDITOR_WEB_FIRECRAWL_API_KEY",
-		billing: "request",
-		signupUrl: "https://www.firecrawl.dev"
-	}, (options) => new FirecrawlSearchProvider({
-		apiKey: options.apiKey ?? "",
-		baseURL: options.baseURL
-	}));
-	const offTavily = manager.registerSearchProvider({
-		id: "tavily",
-		label: "Tavily",
-		defaultBaseURL: "https://api.tavily.com",
-		description: "Search API；固定 basic 检索，不自动升级搜索深度。",
-		credentialRef: "DSH_EDITOR_WEB_TAVILY_API_KEY",
-		billing: "request",
-		signupUrl: "https://app.tavily.com"
-	}, (options) => new TavilySearchProvider({
-		apiKey: options.apiKey ?? "",
-		baseURL: options.baseURL
-	}));
-	const offHttp = manager.registerFetchProvider({
-		id: "http",
-		label: "网页读取",
-		billing: "none",
-		description: "优先匿名 Jina Reader 读取，失败后本机 HTTP 直连；无需 Key。"
-	}, (options) => {
-		const limits = {
-			maxResponseBytes: 5e6,
-			maxBodyChars: options.maxFetchChars,
-			timeoutMs: options.timeoutMs,
-			maxRedirects: 5,
-			userAgent: "dsh-editor/managed-web"
-		};
-		const readerTimeoutMs = Math.min(15e3, Math.floor(options.timeoutMs / 2));
-		return new JinaFirstFetchProvider({
-			reader: new HttpFetchProvider({
-				...limits,
-				maxBodyChars: limits.maxResponseBytes,
-				timeoutMs: readerTimeoutMs
-			}),
-			direct: new HttpFetchProvider(limits),
-			readerTimeoutMs
+//#region src/native-providers.ts
+function validate(descriptor) {
+	if (!/^[a-z][a-z0-9-]{0,63}$/.test(descriptor.id) || !descriptor.label.trim()) throw new WebError("供应商标识或名称无效。", "WEB_INVALID_PROVIDER");
+	if (descriptor.credentialRef && !/^[A-Z][A-Z0-9_]{1,127}$/.test(descriptor.credentialRef)) throw new WebError("供应商凭据引用无效。", "WEB_INVALID_PROVIDER");
+	if (descriptor.defaultBaseURL) validateBaseURL(descriptor.defaultBaseURL);
+	for (const [value, label] of [[descriptor.signupUrl, "注册地址"], [descriptor.pricingUrl, "费用说明地址"]]) {
+		if (!value) continue;
+		try {
+			const url = new URL(value);
+			if (url.protocol !== "https:" || url.username || url.password) throw new Error();
+		} catch {
+			throw new WebError(`${label}须为 HTTPS。`, "WEB_INVALID_PROVIDER");
+		}
+	}
+}
+async function configuredCall(kind, descriptor, configuration, signal, run) {
+	let apiKey;
+	try {
+		signal?.throwIfAborted();
+		apiKey = descriptor.credentialRef ? await configuration.resolveCredential(descriptor.credentialRef) : void 0;
+		signal?.throwIfAborted();
+		if (descriptor.credentialRef && !apiKey?.trim()) throw new WebError("搜索凭据已删除或不可用，请重新配置。", "WEB_CREDENTIAL_MISSING");
+		const settings = configuration.settings();
+		return await run({
+			apiKey,
+			baseURL: settings.endpoints[providerKey(kind, descriptor.id)] ?? descriptor.defaultBaseURL,
+			timeoutMs: settings.timeoutMs,
+			maxFetchChars: settings.maxFetchChars
 		});
+	} catch (error) {
+		throw providerError(error, apiKey ? [apiKey] : []);
+	}
+}
+/** Bundle-owned adapters register through the same native ctx.web entry as any plugin. */
+function registerNativeSearch(web, configuration, descriptor, factory) {
+	validate(descriptor);
+	return web.registerSearchProvider({
+		id: descriptor.id,
+		dshWebManagement: Object.freeze({
+			...descriptor,
+			configurationOwner: WEB_MANAGER_OWNER
+		}),
+		available: () => true,
+		search: (request, signal) => configuredCall("search", descriptor, configuration, signal, (options) => {
+			const provider = factory(options);
+			if (!provider.available()) throw new WebError("供应商配置不可用。", "WEB_PROVIDER_ERROR");
+			return provider.search(request, signal);
+		})
+	});
+}
+function registerNativeFetch(web, configuration, descriptor, factory) {
+	validate(descriptor);
+	return web.registerFetchProvider({
+		id: descriptor.id,
+		dshWebManagement: Object.freeze({
+			...descriptor,
+			configurationOwner: WEB_MANAGER_OWNER
+		}),
+		available: () => true,
+		fetch: (request, signal) => configuredCall("fetch", descriptor, configuration, signal, (options) => {
+			const provider = factory(options);
+			if (!provider.available()) throw new WebError("供应商配置不可用。", "WEB_PROVIDER_ERROR");
+			return provider.fetch(request, signal);
+		})
 	});
-	return () => {
-		offHttp();
-		offTavily();
-		offFirecrawl();
-		offSerper();
-		offBocha();
-		offBrave();
-		offExa();
-		offDeepSeek();
-		offEngine();
-	};
 }
 //#endregion
-//#region src/host-rpc.ts
-function registerHostRpc(ctx, channel, call) {
-	return ctx.webServer.register({
-		kind: "prefix",
-		path: channel,
-		handler: async (req, res) => {
-			if (!ctx.connection.requestRejection) {
-				res.writeHead(503);
-				res.end();
-				return;
-			}
-			const rejection = ctx.connection.requestRejection(req);
-			if (rejection !== void 0) {
-				res.writeHead(rejection);
-				res.end();
-				return;
-			}
-			const pathname = new URL(req.url ?? "/", "http://dsh.internal").pathname;
-			const endpoint = pathname.startsWith(`${channel}/`) ? pathname.slice(channel.length + 1) : "";
-			if (req.method !== "POST" || !/^[a-z.]+$/.test(endpoint)) {
-				res.writeHead(404);
-				res.end();
-				return;
-			}
-			if (String(req.headers["content-type"] ?? "").split(";")[0]?.trim() !== "application/json") {
-				res.writeHead(415);
-				res.end();
-				return;
-			}
-			const controller = new AbortController();
-			res.on("close", () => {
-				if (!res.writableEnded) controller.abort();
+//#region src/web-registry.ts
+const owner = Symbol.for("@klarkxy/dsh-web-search-manager/registry-owner");
+/** The only private-host boundary. Verified against DSH 0.2.0-rc.2.
+* Keep the actual Maps: Cordis effects capture them for automatic unregistration.
+* Replace this bridge when the host exposes enumeration/selection publicly.
+*/
+function runtimeOf(web) {
+	const runtime = web;
+	if (!(runtime.searchProviders instanceof Map) || !(runtime.fetchProviders instanceof Map) || !Object.hasOwn(runtime, "searchProviderId") || !Object.hasOwn(runtime, "fetchProviderId")) throw new WebError("当前 ctx.web 不支持注册表管理，请使用兼容的 DSH 版本。", "WEB_REGISTRY_UNSUPPORTED");
+	return runtime;
+}
+function hasWebProvider(web, kind, id) {
+	return runtimeOf(web)[kind === "search" ? "searchProviders" : "fetchProviders"].has(id);
+}
+function observeWebRegistry(web, hooks) {
+	const runtime = runtimeOf(web);
+	const maps = [runtime.searchProviders, runtime.fetchProviders];
+	if (maps.some((map) => Object.hasOwn(map, owner))) throw new WebError("ctx.web 已由另一个搜索管理器管理。", "WEB_REGISTRY_MANAGED");
+	const undo = [];
+	try {
+		for (const [kind, map] of [["search", maps[0]], ["fetch", maps[1]]]) {
+			Object.defineProperty(map, owner, {
+				value: true,
+				configurable: true
 			});
-			try {
-				const chunks = [];
-				let size = 0;
-				for await (const chunk of req) {
-					const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-					size += buffer.length;
-					if (size > 65536) {
-						res.writeHead(413, { connection: "close" });
-						res.end();
-						req.destroy();
-						return;
+			undo.push(() => {
+				delete map[owner];
+			});
+			const originals = /* @__PURE__ */ new Map();
+			const set = map.set, remove = map.delete, clear = map.clear;
+			const wrap = (id, provider) => {
+				const wrapped = hooks.add(kind, provider);
+				originals.set(id, {
+					original: provider,
+					wrapped
+				});
+				return wrapped;
+			};
+			undo.push(() => {
+				for (const [id, row] of originals) if (map.get(id) === row.wrapped) set.call(map, id, row.original);
+			});
+			for (const [id, provider] of map) set.call(map, id, wrap(id, provider));
+			const replacements = {
+				set(id, provider) {
+					const wrapped = wrap(id, provider);
+					set.call(map, id, wrapped);
+					return map;
+				},
+				delete(id) {
+					const removed = remove.call(map, id);
+					if (removed) {
+						originals.delete(id);
+						hooks.remove(kind, id);
 					}
-					chunks.push(buffer);
-				}
-				let request;
-				try {
-					const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-					if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
-					request = parsed;
-				} catch {
-					res.writeHead(400);
-					res.end();
-					return;
-				}
-				if (request.type !== "client-request" || request.method !== endpoint || typeof request.rpcId !== "string") {
-					res.writeHead(400);
-					res.end();
-					return;
-				}
-				const result = await call(endpoint, request.payload, controller.signal);
-				if (!res.destroyed) {
-					res.writeHead(200, {
-						"content-type": "application/json",
-						"cache-control": "no-store"
-					});
-					res.end(JSON.stringify({
-						type: "server-response",
-						rpcId: request.rpcId,
-						result
-					}));
-				}
-			} catch {
-				if (!res.destroyed) {
-					res.writeHead(500);
-					res.end("network settings request failed");
+					return removed;
+				},
+				clear() {
+					const ids = [...map.keys()];
+					clear.call(map);
+					originals.clear();
+					for (const id of ids) hooks.remove(kind, id);
 				}
+			};
+			for (const key of [
+				"set",
+				"delete",
+				"clear"
+			]) {
+				const before = Object.getOwnPropertyDescriptor(map, key);
+				Object.defineProperty(map, key, {
+					value: replacements[key],
+					configurable: true,
+					writable: true
+				});
+				undo.push(() => {
+					if (map[key] !== replacements[key]) return;
+					if (before) Object.defineProperty(map, key, before);
+					else delete map[key];
+				});
 			}
 		}
-	});
+		for (const key of ["searchProviderId", "fetchProviderId"]) {
+			const before = Object.getOwnPropertyDescriptor(runtime, key);
+			Object.defineProperty(runtime, key, {
+				...before,
+				value: void 0
+			});
+			undo.push(() => {
+				if (runtime[key] === void 0) Object.defineProperty(runtime, key, before);
+			});
+		}
+	} catch (error) {
+		for (const restore of undo.reverse()) restore();
+		throw new WebError("无法接管 ctx.web 注册表，已恢复原状。", "WEB_REGISTRY_UNSUPPORTED", { cause: error });
+	}
+	let stopped = false;
+	return () => {
+		if (stopped) return;
+		stopped = true;
+		for (const restore of undo.reverse()) restore();
+	};
+}
+//#endregion
+//#region src/builtins.ts
+function registerBuiltins(web, configuration) {
+	const registered = [];
+	const registerSearch = (descriptor, factory) => {
+		if (descriptor.legacyId && hasWebProvider(web, "search", descriptor.legacyId)) return () => {};
+		if (hasWebProvider(web, "search", descriptor.id)) return () => {};
+		const off = registerNativeSearch(web, configuration, descriptor, factory);
+		registered.push(off);
+		return off;
+	};
+	const registerFetch = (descriptor, factory) => {
+		if (descriptor.legacyId && hasWebProvider(web, "fetch", descriptor.legacyId)) return () => {};
+		if (hasWebProvider(web, "fetch", descriptor.id)) return () => {};
+		const off = registerNativeFetch(web, configuration, descriptor, factory);
+		registered.push(off);
+		return off;
+	};
+	try {
+		registerSearch({
+			id: "ddg",
+			label: "DuckDuckGo",
+			billing: "none",
+			description: "无需注册。默认后端。"
+		}, () => new SearchEngineProvider());
+		registerSearch({
+			id: "deepseek-managed",
+			legacyId: "deepseek-official",
+			label: "DeepSeek 搜索",
+			description: "使用已配置的 DeepSeek API Key，可能产生额外搜索费用。",
+			defaultBaseURL: DEEPSEEK_DEFAULT_BASE_URL,
+			credentialRef: "DEEPSEEK_API_KEY",
+			credentialShared: true,
+			credentialHint: "与模型设置共用 Key",
+			billing: "model-and-tools",
+			signupUrl: "https://platform.deepseek.com/api_keys"
+		}, (options) => new DeepSeekSearchProvider(() => ({
+			apiKey: options.apiKey,
+			baseURL: options.baseURL ?? DEEPSEEK_DEFAULT_BASE_URL,
+			model: DEEPSEEK_DEFAULT_MODEL,
+			apiVersion: DEEPSEEK_DEFAULT_API_VERSION,
+			maxTokens: DEEPSEEK_DEFAULT_MAX_TOKENS,
+			maxUses: DEEPSEEK_DEFAULT_MAX_USES
+		})));
+		registerSearch({
+			id: "exa",
+			label: "Exa",
+			description: "独立 Search API。",
+			defaultBaseURL: "https://api.exa.ai",
+			credentialRef: "DSH_EDITOR_WEB_EXA_API_KEY",
+			billing: "request",
+			signupUrl: "https://dashboard.exa.ai/api-keys"
+		}, (options) => new ExaSearchProvider({
+			apiKey: options.apiKey ?? "",
+			baseURL: options.baseURL ?? "https://api.exa.ai",
+			searchType: "auto",
+			highlightsPerResult: 1
+		}));
+		registerSearch({
+			id: "brave",
+			label: "Brave",
+			description: "Brave Search API。",
+			defaultBaseURL: "https://api.search.brave.com",
+			credentialRef: "DSH_EDITOR_WEB_BRAVE_API_KEY",
+			billing: "request",
+			signupUrl: "https://api.search.brave.com"
+		}, (options) => new BraveSearchProvider({
+			apiKey: options.apiKey ?? "",
+			baseURL: options.baseURL
+		}));
+		registerSearch({
+			id: "bocha",
+			label: "博查",
+			description: "中文网页搜索 API。",
+			defaultBaseURL: "https://api.bochaai.com",
+			credentialRef: "DSH_EDITOR_WEB_BOCHA_API_KEY",
+			billing: "request",
+			signupUrl: "https://open.bochaai.com"
+		}, (options) => new BochaSearchProvider({
+			apiKey: options.apiKey ?? "",
+			baseURL: options.baseURL
+		}));
+		registerSearch({
+			id: "serper",
+			label: "Serper",
+			description: "Google 结果的 Search API。",
+			defaultBaseURL: "https://google.serper.dev",
+			credentialRef: "DSH_EDITOR_WEB_SERPER_API_KEY",
+			billing: "request",
+			signupUrl: "https://serper.dev"
+		}, (options) => new SerperSearchProvider({
+			apiKey: options.apiKey ?? "",
+			baseURL: options.baseURL
+		}));
+		registerSearch({
+			id: "firecrawl",
+			label: "Firecrawl",
+			description: "网页搜索与提取 API。",
+			defaultBaseURL: "https://api.firecrawl.dev",
+			credentialRef: "DSH_EDITOR_WEB_FIRECRAWL_API_KEY",
+			billing: "request",
+			signupUrl: "https://www.firecrawl.dev"
+		}, (options) => new FirecrawlSearchProvider({
+			apiKey: options.apiKey ?? "",
+			baseURL: options.baseURL
+		}));
+		registerSearch({
+			id: "tavily",
+			label: "Tavily",
+			defaultBaseURL: "https://api.tavily.com",
+			description: "Search API；固定 basic 检索，不自动升级搜索深度。",
+			credentialRef: "DSH_EDITOR_WEB_TAVILY_API_KEY",
+			billing: "request",
+			signupUrl: "https://app.tavily.com"
+		}, (options) => new TavilySearchProvider({
+			apiKey: options.apiKey ?? "",
+			baseURL: options.baseURL
+		}));
+		registerFetch({
+			id: "http-managed",
+			legacyId: "http",
+			label: "网页读取",
+			billing: "none",
+			description: "优先匿名 Jina Reader 读取，失败后本机 HTTP 直连；无需 Key。"
+		}, (options) => {
+			const limits = {
+				maxResponseBytes: 5e6,
+				maxBodyChars: options.maxFetchChars,
+				timeoutMs: options.timeoutMs,
+				maxRedirects: 5,
+				userAgent: "dsh-editor/managed-web"
+			};
+			const readerTimeoutMs = Math.min(15e3, Math.floor(options.timeoutMs / 2));
+			return new JinaFirstFetchProvider({
+				reader: new HttpFetchProvider({
+					...limits,
+					maxBodyChars: limits.maxResponseBytes,
+					timeoutMs: readerTimeoutMs
+				}),
+				direct: new HttpFetchProvider(limits),
+				readerTimeoutMs
+			});
+		});
+	} catch (error) {
+		for (const off of registered.reverse()) off();
+		throw error;
+	}
+	return () => {
+		for (const off of registered.splice(0).reverse()) off();
+	};
+}
+//#endregion
+//#region src/host-rpc.ts
+/** Keep the historical transport error text while sharing admission and request handling. */
+function registerHostRpc$1(ctx, channel, call) {
+	return registerHostRpc(ctx, channel, call, { errorBody: (status) => status === 500 ? "network settings request failed" : void 0 });
 }
 //#endregion
 //#region src/manager.ts
@@ -805,6 +912,9 @@ var WebSearchManager = class {
 	suspended = false;
 	disposed = false;
 	storageFailed = false;
+	refreshRevision = 0;
+	detach;
+	legacyRegistrations = /* @__PURE__ */ new Set();
 	constructor(options) {
 		this.options = options;
 		const initial = structuredClone(options.initial ?? defaultSettings());
@@ -813,6 +923,18 @@ var WebSearchManager = class {
 			...initial,
 			searchOrder: migrateSearchOrder(initial)
 		};
+		this.detach = observeWebRegistry(options.web, {
+			add: (kind, provider) => this.discover(kind, provider),
+			remove: (kind, id) => {
+				const key = providerKey(kind, id);
+				const entry = this.entries.get(key);
+				if (entry) {
+					this.abort(entry);
+					this.entries.delete(key);
+					this.notify();
+				}
+			}
+		});
 	}
 	subscribe(listener) {
 		this.listeners.add(listener);
@@ -832,7 +954,15 @@ var WebSearchManager = class {
 		return Boolean(this.entries.get(providerKey("search", id))?.descriptor.credentialRef);
 	}
 	configured(id) {
-		return Boolean(this.entries.get(providerKey("search", id))?.configured);
+		const entry = this.entries.get(providerKey("search", id));
+		return Boolean(entry && this.ready(entry));
+	}
+	ready(entry) {
+		try {
+			return entry.configured && entry.provider.available();
+		} catch {
+			return false;
+		}
 	}
 	searchOrder(settings = this.settings) {
 		return resolveSearchOrder(this.knownSearchIds(), settings, (id) => this.keyed(id));
@@ -841,7 +971,8 @@ var WebSearchManager = class {
 		return pickActiveSearch(this.searchOrder(settings), (id) => this.configured(id));
 	}
 	selected(entry) {
-		if (this.disposed || this.suspended || !entry.configured) return false;
+		if (this.disposed || this.suspended || !this.ready(entry)) return false;
+		if (this.entries.get(providerKey(entry.kind, entry.descriptor.id)) !== entry) return false;
 		if (entry.kind === "fetch") return this.settings.fetchEnabled && this.settings.fetchProvider === entry.descriptor.id && this.entries.get(providerKey("fetch", entry.descriptor.id)) === entry;
 		return this.settings.searchEnabled && this.activeSearchId() === entry.descriptor.id;
 	}
@@ -855,8 +986,9 @@ var WebSearchManager = class {
 			providers: entries.map((entry) => ({
 				...entry.descriptor,
 				kind: entry.kind,
-				configured: entry.configured,
-				baseURL: this.settings.endpoints[providerKey(entry.kind, entry.descriptor.id)] ?? entry.descriptor.defaultBaseURL,
+				configured: this.ready(entry),
+				configurationOwned: entry.descriptor.configurationOwner === WEB_MANAGER_OWNER,
+				baseURL: entry.descriptor.configurationOwner === "@klarkxy/dsh-web-search-manager" ? this.settings.endpoints[providerKey(entry.kind, entry.descriptor.id)] ?? entry.descriptor.defaultBaseURL : void 0,
 				calls: entry.calls,
 				failures: entry.failures
 			})).sort((a, b) => providerKey(a.kind, a.id).localeCompare(providerKey(b.kind, b.id)))
@@ -864,18 +996,20 @@ var WebSearchManager = class {
 	}
 	async refresh() {
 		const epoch = this.epoch;
+		const revision = ++this.refreshRevision;
 		await Promise.all([...this.entries.entries()].map(async ([key, entry]) => {
-			let configured = !entry.descriptor.credentialRef;
-			if (entry.descriptor.credentialRef) try {
+			let configured = true;
+			if (entry.descriptor.configurationOwner === "@klarkxy/dsh-web-search-manager" && entry.descriptor.credentialRef) try {
 				configured = Boolean((await this.options.resolveCredential(entry.descriptor.credentialRef))?.trim());
 			} catch {
 				configured = false;
 			}
-			if (this.disposed || epoch !== this.epoch || this.entries.get(key) !== entry) return;
+			if (this.disposed || epoch !== this.epoch || revision !== this.refreshRevision || this.entries.get(key) !== entry) return;
 			if (entry.configured !== configured) {
 				entry.configured = configured;
 				if (!configured) this.abort(entry);
 			}
+			if (!this.ready(entry)) this.abort(entry);
 		}));
 		this.notify();
 		return this.status();
@@ -883,99 +1017,97 @@ var WebSearchManager = class {
 	abort(entry) {
 		for (const target of entry ? [entry] : this.entries.values()) for (const controller of target.active) controller.abort();
 	}
-	add(kind, descriptor) {
-		if (this.disposed) fail("WEB_DISABLED", "网络搜索插件已停止。");
-		const key = providerKey(kind, descriptor.id);
-		if (!/^[a-z][a-z0-9-]{0,63}$/.test(descriptor.id) || !descriptor.label.trim()) fail("WEB_INVALID_PROVIDER", "供应商标识或名称无效。");
-		if (descriptor.credentialRef && !/^[A-Z][A-Z0-9_]{1,127}$/.test(descriptor.credentialRef)) fail("WEB_INVALID_PROVIDER", "供应商凭据引用无效。");
-		if (descriptor.defaultBaseURL) validateBaseURL(descriptor.defaultBaseURL);
-		for (const [value, label] of [[descriptor.signupUrl, "注册地址"], [descriptor.pricingUrl, "费用说明地址"]]) {
-			if (!value) continue;
-			try {
-				const url = new URL(value);
-				if (url.protocol !== "https:" || url.username || url.password) fail("WEB_INVALID_PROVIDER", `${label}须为 HTTPS。`);
-			} catch {
-				fail("WEB_INVALID_PROVIDER", `${label}须为 HTTPS。`);
-			}
-		}
-		if (this.entries.has(key)) fail("WEB_DUPLICATE_PROVIDER", "供应商标识已注册。");
+	discover(kind, provider) {
+		const key = providerKey(kind, provider.id);
+		const old = this.entries.get(key);
+		if (old) this.abort(old);
+		const metadata = provider.dshWebManagement;
+		const descriptor = {
+			id: provider.id,
+			label: typeof metadata?.label === "string" && metadata.label ? metadata.label : provider.id,
+			description: typeof metadata?.description === "string" ? metadata.description : "",
+			billing: [
+				"none",
+				"request",
+				"model-and-tools"
+			].includes(metadata?.billing ?? "") ? metadata.billing : "unknown",
+			configurationOwner: typeof metadata?.configurationOwner === "string" && metadata.configurationOwner ? metadata.configurationOwner : void 0,
+			configurationUrl: safeConfigurationUrl(metadata?.configurationUrl)
+		};
+		for (const field of [
+			"credentialHint",
+			"pricing",
+			"defaultBaseURL"
+		]) if (typeof metadata?.[field] === "string") descriptor[field] = metadata[field];
+		if (typeof metadata?.credentialRef === "string" && /^[A-Z][A-Z0-9_]{1,127}$/.test(metadata.credentialRef)) descriptor.credentialRef = metadata.credentialRef;
+		if (metadata?.credentialShared === true) descriptor.credentialShared = true;
+		for (const field of ["signupUrl", "pricingUrl"]) try {
+			const url = new URL(metadata?.[field] ?? "");
+			if (url.protocol === "https:" && !url.username && !url.password) descriptor[field] = metadata[field];
+		} catch {}
 		const entry = {
-			descriptor: Object.freeze({ ...descriptor }),
+			descriptor: Object.freeze(descriptor),
 			kind,
-			configured: !descriptor.credentialRef,
+			provider,
+			configured: descriptor.configurationOwner !== "@klarkxy/dsh-web-search-manager" || !descriptor.credentialRef,
 			calls: 0,
 			failures: 0,
-			unregister() {},
 			active: /* @__PURE__ */ new Set()
 		};
 		this.entries.set(key, entry);
-		return entry;
-	}
-	registration(entry, register) {
-		const key = providerKey(entry.kind, entry.descriptor.id);
-		try {
-			entry.unregister = register();
-		} catch (error) {
-			this.entries.delete(key);
-			throw error;
+		const legacy = metadata?.legacyId;
+		const expectedLegacy = kind === "search" && provider.id === "deepseek-managed" ? "deepseek-official" : kind === "fetch" && provider.id === "http-managed" ? "http" : void 0;
+		if (descriptor.configurationOwner === "@klarkxy/dsh-web-search-manager" && legacy === expectedLegacy && legacy && !this.entries.has(providerKey(kind, legacy))) {
+			if (kind === "search") {
+				this.settings.searchOrder = this.settings.searchOrder.map((id) => id === legacy ? provider.id : id);
+				if (this.settings.searchProvider === legacy) this.settings.searchProvider = provider.id;
+			} else if (this.settings.fetchProvider === legacy) this.settings.fetchProvider = provider.id;
+			const legacyKey = providerKey(kind, legacy);
+			if (this.settings.endpoints[legacyKey] && !this.settings.endpoints[key]) this.settings.endpoints[key] = this.settings.endpoints[legacyKey];
 		}
 		this.refresh();
-		let removed = false;
-		return () => {
-			if (removed) return;
-			removed = true;
-			this.abort(entry);
-			this.entries.delete(key);
-			entry.unregister();
-			this.notify();
-		};
-	}
-	registerSearchProvider(descriptor, factory) {
-		const entry = this.add("search", descriptor);
-		return this.registration(entry, () => this.options.web.registerSearchProvider({
-			id: descriptor.id,
-			available: () => this.selected(entry),
-			search: (request, signal) => {
-				if (typeof request.query !== "string" || !request.query.trim() || request.query.length > 4e3) fail("WEB_INVALID_REQUEST", "查询须为 1 至 4000 字符。");
-				const count = Math.min(bounded(request.maxResults ?? this.settings.maxResults, 1, 100, "结果数"), this.settings.maxResults);
-				return this.execute(entry, signal, async (options, combined) => {
-					const provider = factory(options);
-					if (!provider.available()) fail("WEB_PROVIDER_ERROR", "供应商配置不可用。");
-					const result = await provider.search({
-						query: request.query.trim(),
-						maxResults: count
-					}, combined);
-					const sources = result.sources.slice(0, count).filter((source) => {
-						try {
-							const url = new URL(source.url);
-							return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
-						} catch {
-							return false;
-						}
-					}).map((source) => ({
-						...source,
-						title: source.title?.slice(0, 1e3),
-						snippet: source.snippet?.slice(0, 8e3)
-					}));
-					return {
-						...result,
-						content: result.content?.slice(0, 4e4),
-						sources,
-						truncated: result.truncated || result.sources.length > count
-					};
-				});
-			}
-		}));
-	}
-	registerFetchProvider(descriptor, factory) {
-		const entry = this.add("fetch", descriptor);
-		return this.registration(entry, () => this.options.web.registerFetchProvider({
-			id: descriptor.id,
+		if (kind === "search") {
+			const search = provider;
+			return {
+				id: provider.id,
+				available: () => this.selected(entry),
+				search: (request, signal) => {
+					if (typeof request.query !== "string" || !request.query.trim() || request.query.length > 4e3) fail("WEB_INVALID_REQUEST", "查询须为 1 至 4000 字符。");
+					const count = Math.min(bounded(request.maxResults ?? this.settings.maxResults, 1, 100, "结果数"), this.settings.maxResults);
+					return this.execute(entry, signal, async (_options, combined) => {
+						const result = await search.search({
+							...request,
+							query: request.query.trim(),
+							maxResults: count
+						}, combined);
+						const sources = result.sources.slice(0, count).filter((source) => {
+							try {
+								const url = new URL(source.url);
+								return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
+							} catch {
+								return false;
+							}
+						}).map((source) => ({
+							...source,
+							title: source.title?.slice(0, 1e3),
+							snippet: source.snippet?.slice(0, 8e3)
+						}));
+						return {
+							...result,
+							content: result.content?.slice(0, 4e4),
+							sources,
+							truncated: result.truncated || result.sources.length > count
+						};
+					});
+				}
+			};
+		}
+		const fetch = provider;
+		return {
+			id: provider.id,
 			available: () => this.selected(entry),
 			fetch: (request, signal) => this.execute(entry, signal, async (options, combined) => {
-				const provider = factory(options);
-				if (!provider.available()) fail("WEB_PROVIDER_ERROR", "供应商配置不可用。");
-				const result = await provider.fetch(request, combined);
+				const result = await fetch.fetch(request, combined);
 				const content = result.body.content.slice(0, options.maxFetchChars);
 				return {
 					...result,
@@ -986,7 +1118,31 @@ var WebSearchManager = class {
 					truncated: result.truncated || content.length !== result.body.content.length
 				};
 			})
-		}));
+		};
+	}
+	/** @deprecated Provider plugins should register directly with ctx.web. */
+	registerSearchProvider(descriptor, factory) {
+		return this.legacyRegistration(() => registerNativeSearch(this.options.web, this.providerConfiguration(), descriptor, factory));
+	}
+	/** @deprecated Provider plugins should register directly with ctx.web. */
+	registerFetchProvider(descriptor, factory) {
+		return this.legacyRegistration(() => registerNativeFetch(this.options.web, this.providerConfiguration(), descriptor, factory));
+	}
+	providerConfiguration() {
+		return {
+			settings: () => structuredClone(this.settings),
+			resolveCredential: (ref) => this.options.resolveCredential(ref)
+		};
+	}
+	legacyRegistration(register) {
+		if (this.disposed) fail("WEB_DISABLED", "网络搜索插件已停止。");
+		const unregister = register();
+		const off = () => {
+			this.legacyRegistrations.delete(off);
+			unregister();
+		};
+		this.legacyRegistrations.add(off);
+		return off;
 	}
 	async execute(entry, signal, run) {
 		if (!this.selected(entry)) fail("WEB_DISABLED", "请在设置 → 网络搜索中配置凭据并启用。");
@@ -996,19 +1152,9 @@ var WebSearchManager = class {
 		const epoch = this.epoch;
 		entry.active.add(controller);
 		let started = false;
-		let apiKey;
 		try {
-			const ref = entry.descriptor.credentialRef;
-			apiKey = ref ? await abortable(() => this.options.resolveCredential(ref), combined) : void 0;
-			if (ref && !apiKey?.trim()) {
-				entry.configured = false;
-				this.abort(entry);
-				this.notify();
-				fail("WEB_CREDENTIAL_MISSING", "搜索凭据已删除或不可用，请重新配置。");
-			}
 			if (epoch !== this.epoch || !this.selected(entry)) fail("WEB_DISABLED", "网络访问设置已改变，请重新发起请求。");
 			const options = {
-				apiKey,
 				baseURL: this.settings.endpoints[providerKey(entry.kind, entry.descriptor.id)] ?? entry.descriptor.defaultBaseURL,
 				timeoutMs: this.settings.timeoutMs,
 				maxFetchChars: this.settings.maxFetchChars
@@ -1020,8 +1166,13 @@ var WebSearchManager = class {
 			return result;
 		} catch (error) {
 			if (started) entry.failures += 1;
+			if (error instanceof WebError && error.code === "WEB_CREDENTIAL_MISSING") {
+				entry.configured = false;
+				this.abort(entry);
+				this.notify();
+			}
 			if (combined.aborted && !(error instanceof WebError && error.code === "WEB_CREDENTIAL_MISSING")) throw new WebError("网络请求已取消或超时。", "WEB_ABORTED");
-			const safe = providerError(error, apiKey ? [apiKey] : []);
+			const safe = providerError(error);
 			throw new WebError(`[${entry.kind}:${entry.descriptor.id}] ${safe.message}`, safe.code);
 		} finally {
 			clearTimeout(timeout);
@@ -1042,7 +1193,7 @@ var WebSearchManager = class {
 			bounded(proposed.maxFetchChars, 1e3, 2e5, "正文长度");
 			for (const [key, value] of Object.entries(proposed.endpoints)) {
 				const entry = this.entries.get(key);
-				if (entry && !entry.descriptor.defaultBaseURL) fail("WEB_INVALID_CONFIG", "供应商不支持自定义地址。");
+				if (entry && (entry.descriptor.configurationOwner !== "@klarkxy/dsh-web-search-manager" || !entry.descriptor.defaultBaseURL) && value !== this.settings.endpoints[key]) fail("WEB_INVALID_CONFIG", "供应商不支持自定义地址。");
 				try {
 					proposed.endpoints[key] = validateBaseURL(value);
 				} catch {
@@ -1050,18 +1201,13 @@ var WebSearchManager = class {
 				}
 			}
 			await this.refresh();
-			proposed.searchOrder = this.searchOrder(proposed);
+			proposed.searchOrder = [...new Set(proposed.searchOrder)];
 			proposed.searchProvider = this.activeSearchId(proposed);
-			if (proposed.searchEnabled && !proposed.searchProvider) fail("WEB_CREDENTIAL_MISSING", "需选择已安装的供应商并填写有效凭据。");
-			if (proposed.searchEnabled && this.entries.get(providerKey("fetch", "http"))) {
-				proposed.fetchEnabled = true;
-				proposed.fetchProvider = "http";
-			}
-			if (!proposed.searchEnabled) proposed.fetchEnabled = false;
+			const activatingSearch = !this.settings.searchEnabled || JSON.stringify(proposed.searchOrder) !== JSON.stringify(this.settings.searchOrder);
+			if (proposed.searchEnabled && !proposed.searchProvider && activatingSearch) fail("WEB_CREDENTIAL_MISSING", "需选择已安装的供应商并填写有效凭据。");
 			if (proposed.fetchEnabled) {
 				const entry = this.entries.get(providerKey("fetch", proposed.fetchProvider));
-				if (!entry) proposed.fetchEnabled = false;
-				else if (!entry.configured) fail("WEB_CREDENTIAL_MISSING", "需选择已安装的供应商并填写有效凭据。");
+				if ((!this.settings.fetchEnabled || proposed.fetchProvider !== this.settings.fetchProvider) && (!entry || !this.ready(entry))) fail("WEB_CREDENTIAL_MISSING", "需选择已安装的供应商并填写有效凭据。");
 			}
 			this.suspended = true;
 			this.epoch += 1;
@@ -1088,10 +1234,11 @@ var WebSearchManager = class {
 		this.epoch += 1;
 		this.abort();
 		this.notify();
-		for (const entry of this.entries.values()) entry.unregister();
+		for (const off of [...this.legacyRegistrations]) off();
+		await this.pending;
+		this.detach();
 		this.entries.clear();
 		this.listeners.clear();
-		await this.pending;
 	}
 };
 //#endregion
@@ -1135,20 +1282,30 @@ const inject = [
 async function apply(ctx) {
 	const host = ctx;
 	const domain = await ctx.storageDomain.open(webSettingsDomain);
+	let managed;
+	ctx.effect(() => async () => {
+		await managed?.dispose();
+		await domain.close();
+	}, "web-search-manager.dispose");
 	const table = domain.table("settings");
-	const manager = new WebSearchManager({
+	const manager = managed = new WebSearchManager({
 		web: ctx.web,
 		initial: table.get("global"),
 		resolveCredential: async (ref) => (await host.credentials.resolve(credentialRef(ref)))?.value,
 		save: (settings) => table.put("global", settings)
 	});
-	ctx.effect(() => async () => {
-		await manager.dispose();
-		await domain.close();
-	}, "web-search-manager.dispose");
 	ctx.provide("webSearchManager", manager);
-	ctx.effect(() => registerBuiltins(manager), "web-search-manager.providers");
-	ctx.effect(() => registerHostRpc(host, WEB_SEARCH_RPC_CHANNEL, async (endpoint, payload, signal) => {
+	ctx.on("credentials/reference-updated", () => {
+		manager.refresh();
+	});
+	ctx.on("web/provider-availability-updated", () => {
+		manager.refresh();
+	});
+	ctx.effect(() => registerBuiltins(ctx.web, {
+		settings: () => manager.status().settings,
+		resolveCredential: async (ref) => (await host.credentials.resolve(credentialRef(ref)))?.value
+	}), "web-search-manager.providers");
+	ctx.effect(() => registerHostRpc$1(host, WEB_SEARCH_RPC_CHANNEL, async (endpoint, payload, signal) => {
 		try {
 			signal.throwIfAborted();
 			if (endpoint === "status") return {