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

package/README.md

@@ -1,5 +1,8 @@
 # @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)

package/docs/README.zh-CN.md

@@ -1,5 +1,8 @@
 # @klarkxy/dsh-web-search-manager
 
+<!-- release-state-note -->
+插件生命周期见[仓库状态清单](../../../README.zh-CN.md#插件生命周期)：草稿 → 测试中 → 已发布，只向前推进。已发布插件的修复、测试和升版保持已发布；每次更新仍须通过发布检查。首次发布须明确选择测试中的包，并在 npm 归档验证成功后登记。详见[发布规则](../../../RELEASING.zh-CN.md)。
+
 在一个设置页里挑选用哪个服务回答模型的网络搜索、设定每次请求的上限，并让模型读取公开网页。
 
 [English](../README.md)

package/lib/client.inner.cjs

@@ -2,6 +2,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: [
@@ -299,7 +340,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);
@@ -462,6 +503,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;
@@ -476,8 +569,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,
@@ -783,6 +881,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}`;
 }
@@ -968,7 +1086,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 {
@@ -979,7 +1097,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 () => {
@@ -1034,7 +1152,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;
@@ -1067,7 +1185,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,
@@ -1083,14 +1201,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",
@@ -1129,7 +1247,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;
@@ -1150,13 +1271,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 () => {
@@ -1170,7 +1291,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", {
@@ -1197,19 +1318,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",
@@ -1223,7 +1344,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",
@@ -1349,7 +1470,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) {
@@ -1381,7 +1502,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",
@@ -1393,7 +1514,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
 														})
 													]
@@ -1402,7 +1523,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
 													})] })] })]
 												}),
@@ -1422,7 +1543,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",
@@ -1452,7 +1573,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, {
@@ -1468,7 +1589,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);
@@ -1494,7 +1615,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
 							})
@@ -1577,7 +1698,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))]
 								})]
 							}),