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

package/lib/client.js

@@ -8,6 +8,47 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
 let react = require("react");
 let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/client-error.ts
+/** Local adapter diagnostics only; third-party descriptions remain verbatim. */
+const localErrors = {
+	"网络搜索设置格式无效。": "Invalid web search settings format.",
+	"未知操作。": "Unknown operation.",
+	"网络设置操作失败，请刷新后重试。": "The network settings operation failed. Refresh and try again.",
+	"查询须为 1 至 4000 字符。": "The query must contain 1 to 4,000 characters.",
+	"网络搜索插件已停止。": "The web search plugin has stopped.",
+	"请在设置 → 网络搜索中配置凭据并启用。": "Configure credentials and enable web search in Settings → Web search.",
+	"网络访问设置已改变，请重新发起请求。": "Network access settings changed. Start the request again.",
+	"网络请求已取消。": "The network request was cancelled.",
+	"网络请求已取消或超时。": "The network request was cancelled or timed out.",
+	"设置已被其他页面修改，请刷新后重试。": "Settings changed in another page. Refresh and try again.",
+	"供应商不支持自定义地址。": "The provider does not support a custom address.",
+	"供应商地址须为无凭据、无查询参数的 HTTPS 地址。": "The provider address must use HTTPS without credentials or query parameters.",
+	"需选择已安装的供应商并填写有效凭据。": "Choose an installed provider and enter valid credentials.",
+	"保存失败，本次运行已暂停网络访问以防意外联网。": "Saving failed. Network access is paused for this run to prevent unintended requests.",
+	"供应商未提供错误描述。": "The provider did not supply an error description.",
+	"供应商请求失败。": "Provider request failed.",
+	"搜索凭据已删除或不可用，请重新配置。": "Search credentials were deleted or are unavailable. Configure them again.",
+	"供应商配置不可用。": "Provider configuration is unavailable.",
+	"查询无效。": "Invalid query.",
+	"结果数须为 1 至 20。": "The result count must be from 1 to 20.",
+	"搜索已取消。": "Search cancelled.",
+	"Tavily 搜索已取消。": "Tavily search cancelled.",
+	"响应格式无效。": "Invalid response shape",
+	"响应缺失。": "Missing response",
+	"响应过大。": "Response too large",
+	"地址无效。": "Invalid endpoint"
+};
+function localErrorText(message, locale) {
+	const prefix = message.match(/^(\[(?:search|fetch):[^\]]+\] )(.*)$/s);
+	if (prefix) return prefix[1] + localErrorText(prefix[2], locale);
+	if (locale === "zh") return Object.entries(localErrors).find(([, english]) => english === message)?.[0] ?? message;
+	if (localErrors[message]) return localErrors[message];
+	const http = message.match(/^供应商请求失败（HTTP (\d{3})）。$/);
+	if (http) return `Provider request failed (HTTP ${http[1]}).`;
+	const config = message.match(/^(brave|bocha|firecrawl|serper|Tavily) 配置不可用。$/);
+	if (config) return `${config[1]} configuration is unavailable.`;
+	return message;
+}
 Object.values({
 	/** Surfaces, from the page up to the topmost nested card. */
 	surface: [
@@ -305,7 +346,7 @@ ${scope} {
   border: 0.5px solid var(--dsw-alias-border-l3);
   border-radius: var(--dsw-radius-md);
   background: var(--dsw-alias-bg-layer-1);
-  font-family: var(--ds-font-family-code, ui-monospace, 'Cascadia Mono', Consolas, monospace);
+  font-family: var(--ds-font-family-code);
   font-size: 12px;
   line-height: 20px;
   color: var(--dsw-alias-label-secondary);
@@ -468,6 +509,58 @@ const providerInfo = {
 		pricingUrl: "https://docs.tavily.com/documentation/api-credits"
 	}
 };
+const englishInfo = {
+	ddg: {
+		description: "Search public DuckDuckGo pages without registration or an API key.",
+		pricing: "Free to use; no search API fees."
+	},
+	bocha: {
+		description: "Search Chinese web content, returning titles, links and summaries.",
+		pricing: "Charged per request: listed price ¥0.036/request; trial credits depend on official offers."
+	},
+	brave: {
+		description: "Search web pages, news and more with Brave’s independent index.",
+		pricing: "$5 in monthly credits (about 1,000 requests); then $5/1,000 requests. A payment card is required to activate."
+	},
+	"deepseek-official": {
+		description: "Call built-in search through a DeepSeek model using the model API key.",
+		pricing: "Default Flash token pricing per million: input ¥1–2 (cache hits ¥0.02–0.04), output ¥4–8, varying by peak/off-peak hours. Platform terms govern promotional balance and tool fees."
+	},
+	exa: {
+		description: "Web search for AI with relevant pages and content snippets.",
+		pricing: "$20 on signup, then $10 monthly credits; $7/1,000 requests (up to 10 results each), plus $1/1,000 additional results beyond 10."
+	},
+	firecrawl: {
+		description: "Search the web and extract page content.",
+		pricing: "1,000 free credits/month; 2 credits per 10 search results. Hobby includes 5,000 credits/month at $16/month billed annually; extra credits cost $5/1,000."
+	},
+	serper: {
+		description: "Get Google web search results.",
+		pricing: "2,500 one-time signup requests; $50/50,000 requests ($1/1,000). Paid credits expire after 6 months."
+	},
+	tavily: {
+		description: "Web search for AI, currently using basic search.",
+		pricing: "1,000 free credits/month; basic search uses 1 credit/request. Pay as you go: $0.008/credit ($8/1,000 requests)."
+	}
+};
+const bundledDescriptions = {
+	ddg: ["无需注册。默认后端。", "No registration required. Default backend."],
+	"deepseek-official": ["使用已配置的 DeepSeek API Key，可能产生额外搜索费用。", "Uses the configured DeepSeek API key; additional search fees may apply."],
+	exa: ["独立 Search API。", "Independent Search API."],
+	brave: ["Brave Search API。", "Brave Search API."],
+	bocha: ["中文网页搜索 API。", "Chinese web search API."],
+	serper: ["Google 结果的 Search API。", "Search API for Google results."],
+	firecrawl: ["网页搜索与提取 API。", "Web search and extraction API."],
+	tavily: ["Search API；固定 basic 检索，不自动升级搜索深度。", "Search API using basic search; search depth is never upgraded automatically."]
+};
+/** Translate only manager-owned labels; externally supplied metadata stays verbatim. */
+function providerDisplayLabel(provider, locale) {
+	if (!bundledCatalogId(provider)) return provider.label;
+	if (provider.label === "DeepSeek 搜索") return locale === "zh" ? provider.label : "DeepSeek search";
+	if (provider.label === "博查") return locale === "zh" ? provider.label : "Bocha";
+	if (provider.label === "网页读取") return locale === "zh" ? provider.label : "Read web pages";
+	return provider.label;
+}
 function bundledCatalogId(provider) {
 	if (!(typeof provider.configurationOwned === "boolean" ? provider.configurationOwned : !provider.configurationOwner || provider.configurationOwner === "@klarkxy/dsh-web-search-manager")) return;
 	return provider.id === "deepseek-managed" ? "deepseek-official" : provider.id;
@@ -482,8 +575,13 @@ function usesBundledPricing(provider) {
 }
 function searchProviderInfo(provider, locale = "zh") {
 	const catalogId = bundledCatalogId(provider);
-	const known = catalogId && Object.hasOwn(providerInfo, catalogId) ? providerInfo[catalogId] : void 0;
-	const description = provider.description.trim() ? provider.description : known?.description ?? provider.description;
+	const base = catalogId && Object.hasOwn(providerInfo, catalogId) ? providerInfo[catalogId] : void 0;
+	const known = base && locale === "en" ? {
+		...base,
+		...englishInfo[catalogId]
+	} : base;
+	const ownedCopy = catalogId ? bundledDescriptions[catalogId] : void 0;
+	const description = ownedCopy && provider.description === ownedCopy[0] ? ownedCopy[locale === "zh" ? 0 : 1] : base && provider.description === base.description ? known.description : provider.description.trim() ? provider.description : known?.description ?? provider.description;
 	if (provider.pricing?.trim()) return {
 		description,
 		pricing: provider.pricing,
@@ -789,6 +887,26 @@ const copy = {
 		unknownOwner: "Configure this service in its plugin"
 	}
 };
+var UiError = class extends Error {
+	key;
+	constructor(key) {
+		super(key);
+		this.key = key;
+	}
+};
+function uiMessage(message, locale, providers = []) {
+	if (typeof message === "string") return localErrorText(message, locale);
+	if ("key" in message) return copy[locale][message.key];
+	if ("sources" in message) return testOkText(locale, message.sources);
+	if ("moved" in message) {
+		const provider = providers.find((item) => item.id === message.moved);
+		return movedText(locale, provider ? providerDisplayLabel(provider, locale) : message.moved, message.position);
+	}
+	return message.invalid.map((key) => {
+		const [, min, max] = LIMITS.find((item) => item[0] === key);
+		return limitInvalidText(locale, copy[locale][key], min, max);
+	}).join(" ");
+}
 function movedText(locale, label, position) {
 	return locale === "zh" ? `${label} 已移至第 ${position} 位` : `${label} moved to position ${position}`;
 }
@@ -974,7 +1092,7 @@ function NetworkSearchSettings({ client, hidden }) {
 			return next;
 		} catch (cause) {
 			if (!mountedRef.current || mine !== requestSeq.current) return;
-			setLoadError(cause instanceof Error && cause.message ? cause.message : text.failed);
+			setLoadError(cause instanceof Error && cause.message ? cause.message : { key: "failed" });
 			if (source === "poll") return;
 			throw cause;
 		} finally {
@@ -985,7 +1103,7 @@ function NetworkSearchSettings({ client, hidden }) {
 	(0, react.useEffect)(() => {
 		mountedRef.current = true;
 		readGate.reset();
-		load().catch((cause) => setLoadError(cause instanceof Error && cause.message ? cause.message : text.failed));
+		load().catch((cause) => setLoadError(cause instanceof Error && cause.message ? cause.message : { key: "failed" }));
 		const bind = () => bindStatusRefresh({
 			isHidden: () => isPageHidden(hiddenRef.current),
 			tick: async () => {
@@ -1040,7 +1158,7 @@ function NetworkSearchSettings({ client, hidden }) {
 		try {
 			await run();
 		} catch (cause) {
-			setError(cause instanceof Error && cause.message ? cause.message : text.failed);
+			setError(cause instanceof UiError ? { key: cause.key } : cause instanceof Error && cause.message ? cause.message : { key: "failed" });
 			await load().catch(() => {});
 		} finally {
 			busyRef.current = false;
@@ -1073,7 +1191,7 @@ function NetworkSearchSettings({ client, hidden }) {
 			const snapshot = keys[provider.id] ?? "";
 			const typed = snapshot.trim();
 			if (!ownsProviderConfiguration(provider) || !provider.credentialRef || !typed) continue;
-			if (writable[provider.credentialRef] === false) throw new Error(text.readOnly);
+			if (writable[provider.credentialRef] === false) throw new UiError("readOnly");
 			unwrap(await client.remote.credentials.set(provider.credentialRef, typed));
 			setKeys((current) => current[provider.id] === snapshot ? {
 				...current,
@@ -1089,14 +1207,14 @@ function NetworkSearchSettings({ client, hidden }) {
 			[provider.id]: ""
 		}));
 		await load();
-		setNote(text.keyDeleted);
+		setNote({ key: "keyDeleted" });
 	}
 	if (!status || !limitDraft) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
 		className: "web-search-settings ws-root dsh-ui-panel",
 		children: [loadError ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", {
 			role: "alert",
 			className: "dsh-ui-error",
-			children: [text.loadFailed, loadError]
+			children: [text.loadFailed, uiMessage(loadError, locale, status?.providers)]
 		}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 			role: "status",
 			className: "dsh-ui-hint",
@@ -1135,7 +1253,10 @@ function NetworkSearchSettings({ client, hidden }) {
 		pendingRef.current = next;
 		setPendingOrder(next);
 		if (keyboard) refocusRef.current = id;
-		setSortAnnouncement(movedText(locale, backends.find((provider) => provider.id === id)?.label ?? id, nextIndex + 1));
+		setSortAnnouncement({
+			moved: id,
+			position: nextIndex + 1
+		});
 		clearTimeout(timerRef.current);
 		timerRef.current = setTimeout(() => {
 			timerRef.current = void 0;
@@ -1156,13 +1277,13 @@ function NetworkSearchSettings({ client, hidden }) {
 			const value = parseLimit(limitDraft[key], min, max);
 			if (value === void 0) {
 				nextInvalid[key] = true;
-				messages.push(limitInvalidText(locale, text[key], min, max));
+				messages.push(key);
 			} else parsed[key] = value;
 		}
 		setInvalid(nextInvalid);
 		if (messages.length) {
 			setNote("");
-			setError(messages.join(" "));
+			setError({ invalid: messages });
 			return;
 		}
 		action(async () => {
@@ -1176,7 +1297,7 @@ function NetworkSearchSettings({ client, hidden }) {
 				expectedRevision: current.settings.revision
 			}), true);
 			await load();
-			setNote(text.saved);
+			setNote({ key: "saved" });
 		});
 	}
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
@@ -1203,19 +1324,19 @@ function NetworkSearchSettings({ client, hidden }) {
 				className: "ws-sr-only",
 				role: "status",
 				"aria-live": "polite",
-				children: sortAnnouncement
+				children: uiMessage(sortAnnouncement, locale, saved.providers)
 			}),
 			error && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 				role: "alert",
 				className: "dsh-ui-error",
-				children: error
+				children: uiMessage(error, locale, saved.providers)
 			}),
 			loadError ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: "dsh-ui-stack",
 				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", {
 					role: "alert",
 					className: "dsh-ui-error",
-					children: [text.loadFailed, loadError]
+					children: [text.loadFailed, uiMessage(loadError, locale, status?.providers)]
 				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
 					variant: "outline",
 					size: "sm",
@@ -1229,7 +1350,7 @@ function NetworkSearchSettings({ client, hidden }) {
 			note && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 				role: "status",
 				className: "dsh-ui-notice",
-				children: note
+				children: uiMessage(note, locale, saved.providers)
 			}),
 			saved.storageFailed && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 				role: "alert",
@@ -1355,7 +1476,7 @@ function NetworkSearchSettings({ client, hidden }) {
 											}),
 											draggable: !busy,
 											"aria-disabled": busy,
-											"aria-label": text.dragPrefix + provider.label,
+											"aria-label": text.dragPrefix + providerDisplayLabel(provider, locale),
 											title: text.dragHint,
 											onDragStart: (event) => {
 												if (busy) {
@@ -1387,7 +1508,7 @@ function NetworkSearchSettings({ client, hidden }) {
 													children: [
 														/* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", {
 															className: "dsh-ui-heading",
-															children: provider.label
+															children: providerDisplayLabel(provider, locale)
 														}),
 														/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 															className: "ws-provider-note",
@@ -1399,7 +1520,7 @@ function NetworkSearchSettings({ client, hidden }) {
 														}),
 														provider.signupUrl && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AppLink, {
 															url: provider.signupUrl,
-															label: provider.label + " " + text.signup,
+															label: providerDisplayLabel(provider, locale) + " " + text.signup,
 															children: text.signup
 														})
 													]
@@ -1408,7 +1529,7 @@ function NetworkSearchSettings({ client, hidden }) {
 													className: "web-search-provider-info",
 													children: [info.description ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", { children: info.description }) : null, /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", { children: [info.pricing, info.pricingUrl && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [" ", /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AppLink, {
 														url: info.pricingUrl,
-														label: provider.label + " " + text.pricing,
+														label: providerDisplayLabel(provider, locale) + " " + text.pricing,
 														children: provider.id === "ddg" ? text.website : text.pricing
 													})] })] })]
 												}),
@@ -1428,7 +1549,7 @@ function NetworkSearchSettings({ client, hidden }) {
 												}) : null,
 												shared && participating && owned ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("small", {
 													className: "dsh-ui-meta",
-													children: provider.credentialHint ?? text.sharedKey
+													children: provider.credentialHint === "与模型设置共用 Key" ? locale === "zh" ? provider.credentialHint : "Shares a key with model settings" : provider.credentialHint ?? text.sharedKey
 												}) : null,
 												showKey ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
 													className: "dsh-ui-field",
@@ -1458,7 +1579,7 @@ function NetworkSearchSettings({ client, hidden }) {
 														onClick: () => void action(async () => {
 															await saveKeys(provider);
 															await load();
-															setNote(text.keySaved);
+															setNote({ key: "keySaved" });
 														}),
 														children: text.saveKey
 													}) : null, needsKey && !shared && provider.configured ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ConfirmButton, {
@@ -1474,7 +1595,7 @@ function NetworkSearchSettings({ client, hidden }) {
 											className: "web-search-rank-move",
 											children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Switch, {
 												checked: participating,
-												label: provider.label,
+												label: providerDisplayLabel(provider, locale),
 												disabled: busy,
 												onChange: (next) => {
 													const following = next ? [...order, provider.id] : order.filter((id) => id !== provider.id);
@@ -1500,7 +1621,7 @@ function NetworkSearchSettings({ client, hidden }) {
 									await saveKeys();
 									const result = await call("test");
 									await load();
-									setNote(testOkText(locale, result.sources));
+									setNote({ sources: result.sources });
 								}),
 								children: text.test
 							})
@@ -1583,7 +1704,7 @@ function NetworkSearchSettings({ client, hidden }) {
 										]
 									}), saved.providers.filter((provider) => provider.kind === "fetch").map((provider) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("option", {
 										value: provider.id,
-										children: [provider.label, provider.configured ? "" : " · " + text.unavailable]
+										children: [providerDisplayLabel(provider, locale), provider.configured ? "" : " · " + text.unavailable]
 									}, provider.id))]
 								})]
 							}),

package/lib/contracts.d.ts

@@ -1,4 +1,5 @@
 import { WebFetchProvider, WebSearchProvider } from "@deepseek-ai/dsh-web";
+import { DshWebManagementDescriptor } from "@klarkxy/dsh-plugin-kit/contracts";
 //#region src/contracts.d.ts
 declare const WEB_SEARCH_RPC_CHANNEL = "/web-search-manager";
 type RpcResult<T = unknown> = {
@@ -13,31 +14,8 @@ type RpcResult<T = unknown> = {
   };
 };
 type ProviderKind = 'search' | 'fetch';
-/** Management metadata only. Execution and source vocabulary belong to ctx.web. */
-interface ProviderDescriptor {
-  readonly id: string;
-  readonly label: string;
-  readonly description: string;
-  readonly defaultBaseURL?: string;
-  readonly credentialRef?: string;
-  /** True when the key is shared with another surface. The page must not delete it. */
-  readonly credentialShared?: boolean;
-  /** Optional notice naming the settings surface that owns a shared credential. */
-  readonly credentialHint?: string;
-  readonly billing: 'request' | 'model-and-tools' | 'none' | 'unknown';
-  /** Optional provider-supplied billing summary. */
-  readonly pricing?: string;
-  /** Public HTTPS page explaining provider charges. */
-  readonly pricingUrl?: string;
-  /** Public HTTPS page where the user can create an API key. */
-  readonly signupUrl?: string;
-  /** Plugin that owns configuration. Native providers keep their settings there. */
-  readonly configurationOwner?: string;
-  /** Explicit settings link supplied by the provider, never inferred from its id. */
-  readonly configurationUrl?: string;
-  /** Fixed legacy route migrated by a bundle-owned adapter; not used by native plugins. */
-  readonly legacyId?: string;
-}
+/** Management metadata only. Field contract lives in plugin-kit; execution stays with ctx.web. */
+interface ProviderDescriptor extends DshWebManagementDescriptor {}
 declare const WEB_MANAGER_OWNER = "@klarkxy/dsh-web-search-manager";
 /** Optional display metadata on a provider registered directly with ctx.web. */
 type DiscoverableSearchProvider = WebSearchProvider & {

package/lib/contracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.js","names":[],"sources":["../src/contracts.ts"],"sourcesContent":["import type { WebFetchProvider, WebSearchProvider } from '@deepseek-ai/dsh-web'\n\nexport const WEB_SEARCH_RPC_CHANNEL = '/web-search-manager'\nexport type RpcResult<T = unknown> = { ok: true; value: T } | {\n  ok: false; error: { code: string; message: string; details: Record<string, unknown> }\n}\nexport type ProviderKind = 'search' | 'fetch'\n/** Management metadata only. Execution and source vocabulary belong to ctx.web. */\nexport interface ProviderDescriptor {\n  readonly id: string\n  readonly label: string\n  readonly description: string\n  readonly defaultBaseURL?: string\n  readonly credentialRef?: string\n  /** True when the key is shared with another surface. The page must not delete it. */\n  readonly credentialShared?: boolean\n  /** Optional notice naming the settings surface that owns a shared credential. */\n  readonly credentialHint?: string\n  readonly billing: 'request' | 'model-and-tools' | 'none' | 'unknown'\n  /** Optional provider-supplied billing summary. */\n  readonly pricing?: string\n  /** Public HTTPS page explaining provider charges. */\n  readonly pricingUrl?: string\n  /** Public HTTPS page where the user can create an API key. */\n  readonly signupUrl?: string\n  /** Plugin that owns configuration. Native providers keep their settings there. */\n  readonly configurationOwner?: string\n  /** Explicit settings link supplied by the provider, never inferred from its id. */\n  readonly configurationUrl?: string\n  /** Fixed legacy route migrated by a bundle-owned adapter; not used by native plugins. */\n  readonly legacyId?: string\n}\nexport const WEB_MANAGER_OWNER = '@klarkxy/dsh-web-search-manager'\n/** Optional display metadata on a provider registered directly with ctx.web. */\nexport type DiscoverableSearchProvider = WebSearchProvider & { readonly dshWebManagement?: ProviderDescriptor }\nexport type DiscoverableFetchProvider = WebFetchProvider & { readonly dshWebManagement?: ProviderDescriptor }\nexport interface ProviderOptions {\n  readonly apiKey?: string\n  readonly baseURL?: string\n  readonly timeoutMs: number\n  readonly maxFetchChars: number\n}\nexport type SearchProviderFactory = (options: ProviderOptions) => WebSearchProvider\nexport type FetchProviderFactory = (options: ProviderOptions) => WebFetchProvider\n/** Never store credential values here. Keys are resolved by reference per call. */\nexport interface WebSettings {\n  revision: number\n  searchEnabled: boolean\n  fetchEnabled: boolean\n  searchProvider: string\n  fetchProvider: string\n  searchOrder: string[]\n  maxResults: number\n  maxQueries: number\n  timeoutMs: number\n  maxFetchChars: number\n  endpoints: Record<string, string>\n}\nexport const DEFAULT_SEARCH_ORDER = ['ddg'] as const\n\nexport const defaultSettings = (): WebSettings => ({\n  revision: 0, searchEnabled: true, fetchEnabled: true,\n  searchProvider: 'ddg', fetchProvider: 'http', searchOrder: [...DEFAULT_SEARCH_ORDER],\n  maxResults: 5, maxQueries: 1,\n  timeoutMs: 30_000, maxFetchChars: 100_000, endpoints: {},\n})\n\n/** Keyed backends first, keyless last — same idea as OpenClaw auto-detect. */\nexport function defaultSearchOrder(ids: readonly string[], keyed: (id: string) => boolean): string[] {\n  return [...ids.filter(keyed), ...ids.filter(id => !keyed(id))]\n}\n\nexport function migrateSearchOrder(settings: { searchOrder?: string[]; searchProvider?: string }): string[] {\n  return settings.searchOrder ?? (settings.searchProvider ? [settings.searchProvider] : [...DEFAULT_SEARCH_ORDER])\n}\n\nexport function resolveSearchOrder(\n  knownIds: readonly string[],\n  settings: Pick<WebSettings, 'searchOrder' | 'searchProvider'>,\n  _keyed: (id: string) => boolean,\n): string[] {\n  return [...new Set(settings.searchOrder.filter(id => knownIds.includes(id)))]\n}\n\nexport function pickActiveSearch(order: readonly string[], configured: (id: string) => boolean): string {\n  return order.find(configured) ?? ''\n}\nexport interface ProviderView extends ProviderDescriptor {\n  kind: ProviderKind\n  configured: boolean\n  /** True only for configuration explicitly owned by this manager bundle. */\n  configurationOwned?: boolean\n  baseURL?: string\n  calls: number\n  failures: number\n}\nexport interface WebStatus {\n  settings: WebSettings\n  providers: ProviderView[]\n  searchActive: boolean\n  fetchActive: boolean\n  storageFailed: boolean\n}\nexport function providerKey(kind: ProviderKind, id: string): string { return `${kind}:${id}` }\nexport function safeConfigurationUrl(value: unknown): string | undefined {\n  if (typeof value !== 'string' || !value || /[\\u0000-\\u0020\\\\]/.test(value)) return\n  try {\n    const url = new URL(value, 'https://dsh.invalid')\n    if (url.username || url.password) return\n    if ((value.startsWith('/') && !value.startsWith('//')) || value.startsWith('#')) {\n      return url.origin === 'https://dsh.invalid' ? value : undefined\n    }\n    return /^https:\\/\\//i.test(value) && url.protocol === 'https:' ? value : undefined\n  } catch { return }\n}\nexport function validateBaseURL(value: string): string {\n  const url = new URL(value)\n  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) {\n    throw new Error('供应商地址必须是 HTTPS，且不能包含用户名、密码、查询参数或片段。')\n  }\n  return url.href.replace(/\\/+$/, '')\n}\n"],"mappings":";AAEA,MAAa,yBAAyB;AA8BtC,MAAa,oBAAoB;AA0BjC,MAAa,uBAAuB,CAAC,KAAK;AAE1C,MAAa,yBAAsC;CACjD,UAAU;CAAG,eAAe;CAAM,cAAc;CAChD,gBAAgB;CAAO,eAAe;CAAQ,aAAa,CAAC,GAAG,oBAAoB;CACnF,YAAY;CAAG,YAAY;CAC3B,WAAW;CAAQ,eAAe;CAAS,WAAW,CAAC;AACzD;;AAGA,SAAgB,mBAAmB,KAAwB,OAA0C;CACnG,OAAO,CAAC,GAAG,IAAI,OAAO,KAAK,GAAG,GAAG,IAAI,QAAO,OAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC/D;AAEA,SAAgB,mBAAmB,UAAyE;CAC1G,OAAO,SAAS,gBAAgB,SAAS,iBAAiB,CAAC,SAAS,cAAc,IAAI,CAAC,GAAG,oBAAoB;AAChH;AAEA,SAAgB,mBACd,UACA,UACA,QACU;CACV,OAAO,CAAC,GAAG,IAAI,IAAI,SAAS,YAAY,QAAO,OAAM,SAAS,SAAS,EAAE,CAAC,CAAC,CAAC;AAC9E;AAEA,SAAgB,iBAAiB,OAA0B,YAA6C;CACtG,OAAO,MAAM,KAAK,UAAU,KAAK;AACnC;AAiBA,SAAgB,YAAY,MAAoB,IAAoB;CAAE,OAAO,GAAG,KAAK,GAAG;AAAK;AAC7F,SAAgB,qBAAqB,OAAoC;CACvE,IAAI,OAAO,UAAU,YAAY,CAAC,SAAS,oBAAoB,KAAK,KAAK,GAAG;CAC5E,IAAI;EACF,MAAM,MAAM,IAAI,IAAI,OAAO,qBAAqB;EAChD,IAAI,IAAI,YAAY,IAAI,UAAU;EAClC,IAAK,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,WAAW,IAAI,KAAM,MAAM,WAAW,GAAG,GAC5E,OAAO,IAAI,WAAW,wBAAwB,QAAQ,KAAA;EAExD,OAAO,eAAe,KAAK,KAAK,KAAK,IAAI,aAAa,WAAW,QAAQ,KAAA;CAC3E,QAAQ;EAAE;CAAO;AACnB;AACA,SAAgB,gBAAgB,OAAuB;CACrD,MAAM,MAAM,IAAI,IAAI,KAAK;CACzB,IAAI,IAAI,aAAa,YAAY,IAAI,YAAY,IAAI,YAAY,IAAI,UAAU,IAAI,MACjF,MAAM,IAAI,MAAM,qCAAqC;CAEvD,OAAO,IAAI,KAAK,QAAQ,QAAQ,EAAE;AACpC"}
+{"version":3,"file":"contracts.js","names":[],"sources":["../src/contracts.ts"],"sourcesContent":["import type { WebFetchProvider, WebSearchProvider } from '@deepseek-ai/dsh-web'\nimport type { DshWebManagementDescriptor } from '@klarkxy/dsh-plugin-kit/contracts'\n\nexport const WEB_SEARCH_RPC_CHANNEL = '/web-search-manager'\nexport type RpcResult<T = unknown> = { ok: true; value: T } | {\n  ok: false; error: { code: string; message: string; details: Record<string, unknown> }\n}\nexport type ProviderKind = 'search' | 'fetch'\n/** Management metadata only. Field contract lives in plugin-kit; execution stays with ctx.web. */\nexport interface ProviderDescriptor extends DshWebManagementDescriptor {}\nexport const WEB_MANAGER_OWNER = '@klarkxy/dsh-web-search-manager'\n/** Optional display metadata on a provider registered directly with ctx.web. */\nexport type DiscoverableSearchProvider = WebSearchProvider & { readonly dshWebManagement?: ProviderDescriptor }\nexport type DiscoverableFetchProvider = WebFetchProvider & { readonly dshWebManagement?: ProviderDescriptor }\nexport interface ProviderOptions {\n  readonly apiKey?: string\n  readonly baseURL?: string\n  readonly timeoutMs: number\n  readonly maxFetchChars: number\n}\nexport type SearchProviderFactory = (options: ProviderOptions) => WebSearchProvider\nexport type FetchProviderFactory = (options: ProviderOptions) => WebFetchProvider\n/** Never store credential values here. Keys are resolved by reference per call. */\nexport interface WebSettings {\n  revision: number\n  searchEnabled: boolean\n  fetchEnabled: boolean\n  searchProvider: string\n  fetchProvider: string\n  searchOrder: string[]\n  maxResults: number\n  maxQueries: number\n  timeoutMs: number\n  maxFetchChars: number\n  endpoints: Record<string, string>\n}\nexport const DEFAULT_SEARCH_ORDER = ['ddg'] as const\n\nexport const defaultSettings = (): WebSettings => ({\n  revision: 0, searchEnabled: true, fetchEnabled: true,\n  searchProvider: 'ddg', fetchProvider: 'http', searchOrder: [...DEFAULT_SEARCH_ORDER],\n  maxResults: 5, maxQueries: 1,\n  timeoutMs: 30_000, maxFetchChars: 100_000, endpoints: {},\n})\n\n/** Keyed backends first, keyless last — same idea as OpenClaw auto-detect. */\nexport function defaultSearchOrder(ids: readonly string[], keyed: (id: string) => boolean): string[] {\n  return [...ids.filter(keyed), ...ids.filter(id => !keyed(id))]\n}\n\nexport function migrateSearchOrder(settings: { searchOrder?: string[]; searchProvider?: string }): string[] {\n  return settings.searchOrder ?? (settings.searchProvider ? [settings.searchProvider] : [...DEFAULT_SEARCH_ORDER])\n}\n\nexport function resolveSearchOrder(\n  knownIds: readonly string[],\n  settings: Pick<WebSettings, 'searchOrder' | 'searchProvider'>,\n  _keyed: (id: string) => boolean,\n): string[] {\n  return [...new Set(settings.searchOrder.filter(id => knownIds.includes(id)))]\n}\n\nexport function pickActiveSearch(order: readonly string[], configured: (id: string) => boolean): string {\n  return order.find(configured) ?? ''\n}\nexport interface ProviderView extends ProviderDescriptor {\n  kind: ProviderKind\n  configured: boolean\n  /** True only for configuration explicitly owned by this manager bundle. */\n  configurationOwned?: boolean\n  baseURL?: string\n  calls: number\n  failures: number\n}\nexport interface WebStatus {\n  settings: WebSettings\n  providers: ProviderView[]\n  searchActive: boolean\n  fetchActive: boolean\n  storageFailed: boolean\n}\nexport function providerKey(kind: ProviderKind, id: string): string { return `${kind}:${id}` }\nexport function safeConfigurationUrl(value: unknown): string | undefined {\n  if (typeof value !== 'string' || !value || /[\\u0000-\\u0020\\\\]/.test(value)) return\n  try {\n    const url = new URL(value, 'https://dsh.invalid')\n    if (url.username || url.password) return\n    if ((value.startsWith('/') && !value.startsWith('//')) || value.startsWith('#')) {\n      return url.origin === 'https://dsh.invalid' ? value : undefined\n    }\n    return /^https:\\/\\//i.test(value) && url.protocol === 'https:' ? value : undefined\n  } catch { return }\n}\nexport function validateBaseURL(value: string): string {\n  const url = new URL(value)\n  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) {\n    throw new Error('供应商地址必须是 HTTPS，且不能包含用户名、密码、查询参数或片段。')\n  }\n  return url.href.replace(/\\/+$/, '')\n}\n"],"mappings":";AAGA,MAAa,yBAAyB;AAOtC,MAAa,oBAAoB;AA0BjC,MAAa,uBAAuB,CAAC,KAAK;AAE1C,MAAa,yBAAsC;CACjD,UAAU;CAAG,eAAe;CAAM,cAAc;CAChD,gBAAgB;CAAO,eAAe;CAAQ,aAAa,CAAC,GAAG,oBAAoB;CACnF,YAAY;CAAG,YAAY;CAC3B,WAAW;CAAQ,eAAe;CAAS,WAAW,CAAC;AACzD;;AAGA,SAAgB,mBAAmB,KAAwB,OAA0C;CACnG,OAAO,CAAC,GAAG,IAAI,OAAO,KAAK,GAAG,GAAG,IAAI,QAAO,OAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC/D;AAEA,SAAgB,mBAAmB,UAAyE;CAC1G,OAAO,SAAS,gBAAgB,SAAS,iBAAiB,CAAC,SAAS,cAAc,IAAI,CAAC,GAAG,oBAAoB;AAChH;AAEA,SAAgB,mBACd,UACA,UACA,QACU;CACV,OAAO,CAAC,GAAG,IAAI,IAAI,SAAS,YAAY,QAAO,OAAM,SAAS,SAAS,EAAE,CAAC,CAAC,CAAC;AAC9E;AAEA,SAAgB,iBAAiB,OAA0B,YAA6C;CACtG,OAAO,MAAM,KAAK,UAAU,KAAK;AACnC;AAiBA,SAAgB,YAAY,MAAoB,IAAoB;CAAE,OAAO,GAAG,KAAK,GAAG;AAAK;AAC7F,SAAgB,qBAAqB,OAAoC;CACvE,IAAI,OAAO,UAAU,YAAY,CAAC,SAAS,oBAAoB,KAAK,KAAK,GAAG;CAC5E,IAAI;EACF,MAAM,MAAM,IAAI,IAAI,OAAO,qBAAqB;EAChD,IAAI,IAAI,YAAY,IAAI,UAAU;EAClC,IAAK,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,WAAW,IAAI,KAAM,MAAM,WAAW,GAAG,GAC5E,OAAO,IAAI,WAAW,wBAAwB,QAAQ,KAAA;EAExD,OAAO,eAAe,KAAK,KAAK,KAAK,IAAI,aAAa,WAAW,QAAQ,KAAA;CAC3E,QAAQ;EAAE;CAAO;AACnB;AACA,SAAgB,gBAAgB,OAAuB;CACrD,MAAM,MAAM,IAAI,IAAI,KAAK;CACzB,IAAI,IAAI,aAAa,YAAY,IAAI,YAAY,IAAI,YAAY,IAAI,UAAU,IAAI,MACjF,MAAM,IAAI,MAAM,qCAAqC;CAEvD,OAAO,IAAI,KAAK,QAAQ,QAAQ,EAAE;AACpC"}

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 import { FetchProviderFactory, ProviderDescriptor, ProviderOptions, SearchProviderFactory, WebSettings, WebStatus } from "./contracts.js";
 import { WebFetchProvider, WebSearchProvider } from "@deepseek-ai/dsh-web";
+import { WEB_PROVIDER_AVAILABILITY_EVENT } from "@klarkxy/dsh-plugin-kit/contracts";
 import { Context } from "@deepseek-ai/cordis";
 //#region src/web-registry.d.ts
 interface WebRegistry {
@@ -67,7 +68,7 @@ declare function apply(ctx: Context): Promise<void>;
 declare module '@deepseek-ai/cordis' {
   interface Events {
     /** Repository extension: native providers announce a local availability change. */
-    'web/provider-availability-updated'(kind: 'search' | 'fetch', id: string): void;
+    [WEB_PROVIDER_AVAILABILITY_EVENT](kind: 'search' | 'fetch', id: string): void;
   }
 }
 //#endregion

package/lib/index.js

@@ -1,6 +1,7 @@
 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 { WEB_PROVIDER_AVAILABILITY_EVENT } from "@klarkxy/dsh-plugin-kit/contracts";
 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";
@@ -129,7 +130,7 @@ function providerError(error, secrets = []) {
 	return new WebError(redactDescription(descriptions.join("；") || "供应商未提供错误描述。", secrets), redactDescription(code || "WEB_PROVIDER_ERROR", secrets));
 }
 const SEARCH_ENGINE_PAGE = "https://lite.duckduckgo.com/lite/";
-const MAX_RESPONSE_BYTES$2 = 2e6;
+const MAX_RESPONSE_BYTES$1 = 2e6;
 const USER_AGENT = "Mozilla/5.0 (compatible; dsh-editor-search/1.0)";
 function searchEngineUrl(query, page = SEARCH_ENGINE_PAGE) {
 	const url = new URL(page);
@@ -196,7 +197,7 @@ async function readText(response, signal) {
 			const { value, done } = await reader.read();
 			if (done) break;
 			size += value.length;
-			if (size > MAX_RESPONSE_BYTES$2) throw new Error("Response too large");
+			if (size > MAX_RESPONSE_BYTES$1) throw new Error("Response too large");
 			chunks.push(value);
 		}
 	} finally {
@@ -252,10 +253,10 @@ var SearchEngineProvider = class {
 		}
 	}
 };
-function record$1(value) {
+function record(value) {
 	return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
 }
-async function readJSON$1(response, signal) {
+async function readJSON(response, signal) {
 	const reader = response.body?.getReader();
 	if (!reader) throw new Error("Missing response");
 	let size = 0;
@@ -287,7 +288,7 @@ function httpsEndpoint(base, path = "") {
 	return `${url.href.replace(/\/+$/, "")}${path}`;
 }
 function sourceFrom(raw, urlKey, titleKey, snippetKey) {
-	const row = record$1(raw);
+	const row = record(raw);
 	if (typeof row?.[urlKey] !== "string") return;
 	let url;
 	try {
@@ -351,7 +352,7 @@ function createRestSearch(spec) {
 					await response.body?.cancel().catch(() => {});
 					throw new HttpStatusError(response.status);
 				}
-				const sources = spec.parse(await readJSON$1(response, signal));
+				const sources = spec.parse(await readJSON(response, signal));
 				return {
 					sources: sources.slice(0, count),
 					truncated: sources.length > count
@@ -374,7 +375,7 @@ const BraveSearchProvider = createRestSearch({
 		count: String(count)
 	}),
 	parse(payload) {
-		const results = record$1(record$1(payload)?.web)?.results;
+		const results = record(record(payload)?.web)?.results;
 		return Array.isArray(results) ? results.flatMap((row) => sourceFrom(row, "url", "title", "description") ?? []) : [];
 	}
 });
@@ -394,7 +395,7 @@ const BochaSearchProvider = createRestSearch({
 		summary: false
 	}),
 	parse(payload) {
-		const pages = record$1(record$1(record$1(payload)?.data)?.webPages)?.value ?? record$1(record$1(payload)?.webPages)?.value;
+		const pages = record(record(record(payload)?.data)?.webPages)?.value ?? record(record(payload)?.webPages)?.value;
 		return Array.isArray(pages) ? pages.flatMap((row) => sourceFrom(row, "url", "name", "snippet") ?? []) : [];
 	}
 });
@@ -412,7 +413,7 @@ const SerperSearchProvider = createRestSearch({
 		num: count
 	}),
 	parse(payload) {
-		const organic = record$1(payload)?.organic;
+		const organic = record(payload)?.organic;
 		return Array.isArray(organic) ? organic.flatMap((row) => sourceFrom(row, "link", "title", "snippet") ?? []) : [];
 	}
 });
@@ -430,47 +431,12 @@ const FirecrawlSearchProvider = createRestSearch({
 		limit: count
 	}),
 	parse(payload) {
-		const data = record$1(payload)?.data;
+		const data = record(payload)?.data;
 		return Array.isArray(data) ? data.flatMap((row) => sourceFrom(row, "url", "title", "description") ?? []) : [];
 	}
 });
 //#endregion
 //#region src/tavily.ts
-const MAX_RESPONSE_BYTES = 2e6;
-function endpoint(base) {
-	const url = new URL(base);
-	if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) throw new Error("Invalid endpoint");
-	return `${url.href.replace(/\/+$/, "")}/search`;
-}
-function record(value) {
-	return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
-}
-async function readJSON(response, signal) {
-	const reader = response.body?.getReader();
-	if (!reader) throw new Error("Missing response");
-	let size = 0;
-	const chunks = [];
-	try {
-		while (true) {
-			signal?.throwIfAborted();
-			const { value, done } = await reader.read();
-			if (done) break;
-			size += value.length;
-			if (size > MAX_RESPONSE_BYTES) throw new Error("Response too large");
-			chunks.push(value);
-		}
-		const bytes = new Uint8Array(size);
-		let offset = 0;
-		for (const chunk of chunks) {
-			bytes.set(chunk, offset);
-			offset += chunk.length;
-		}
-		return JSON.parse(new TextDecoder().decode(bytes));
-	} finally {
-		await reader.cancel().catch(() => {});
-		reader.releaseLock();
-	}
-}
 /** Direct REST adapter. No auxiliary LLM, retries, anonymous fallback or auto-depth. */
 var TavilySearchProvider = class {
 	options;
@@ -480,7 +446,7 @@ var TavilySearchProvider = class {
 	}
 	available() {
 		try {
-			endpoint(this.options.baseURL ?? "https://api.tavily.com");
+			httpsEndpoint(this.options.baseURL ?? "https://api.tavily.com", "/search");
 			return Boolean(this.options.apiKey.trim());
 		} catch {
 			return false;
@@ -493,7 +459,7 @@ var TavilySearchProvider = class {
 		if (!Number.isInteger(count) || count < 1 || count > 20) throw new WebError("结果数须为 1 至 20。", "WEB_INVALID_REQUEST");
 		try {
 			signal?.throwIfAborted();
-			const response = await (this.options.fetch ?? fetch)(endpoint(this.options.baseURL ?? "https://api.tavily.com"), {
+			const response = await (this.options.fetch ?? fetch)(httpsEndpoint(this.options.baseURL ?? "https://api.tavily.com", "/search"), {
 				method: "POST",
 				redirect: "error",
 				signal,
@@ -522,18 +488,12 @@ var TavilySearchProvider = class {
 			const sources = [];
 			for (const raw of payload.results) {
 				const row = record(raw);
-				if (typeof row?.url !== "string") continue;
-				let url;
-				try {
-					url = new URL(row.url);
-				} catch {
-					continue;
-				}
-				if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) continue;
+				const source = sourceFrom(row, "url", "title", "content");
+				if (!source || !row) continue;
 				sources.push({
-					url: url.href,
-					...typeof row.title === "string" ? { title: row.title.slice(0, 1e3) } : {},
-					...typeof row.content === "string" ? { snippet: row.content.slice(0, 8e3) } : {},
+					...source,
+					...row.title === "" ? { title: "" } : {},
+					...row.content === "" ? { snippet: "" } : {},
 					...typeof row.published_date === "string" && Number.isFinite(Date.parse(row.published_date)) ? { publishedAt: new Date(row.published_date).toISOString() } : {}
 				});
 			}
@@ -1298,7 +1258,7 @@ async function apply(ctx) {
 	ctx.on("credentials/reference-updated", () => {
 		manager.refresh();
 	});
-	ctx.on("web/provider-availability-updated", () => {
+	ctx.on(WEB_PROVIDER_AVAILABILITY_EVENT, () => {
 		manager.refresh();
 	});
 	ctx.effect(() => registerBuiltins(ctx.web, {