@dsh-plus/web-search-services 0.1.8 → 0.1.9

package/lib/client.js

@@ -0,0 +1,867 @@
+window.__ModuleLoader__.load({
+	id: "@dsh-plus/web-search-services",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react = require("react");
+		let react_jsx_runtime = require("react/jsx-runtime");
+		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+		//#region ../shared/src/client/card.tsx
+		const IDLE_STATUS = {
+			kind: "idle",
+			text: ""
+		};
+		/** 状态行 + 动作按钮（两种形态共用，类名随形态切换度量）。 */
+		function CardFoot(props) {
+			const p = props.prefix;
+			const section = props.variant === "section";
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: section ? `${p}-sectionFooter` : `${p}-footer`,
+				children: [props.status !== void 0 && props.status.kind !== "idle" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: `${p}-status${props.status.kind === "error" ? ` ${p}-statusError` : ""}`,
+					role: "status",
+					children: props.status.text
+				}) : null, props.actions.map((action) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+					type: "button",
+					className: `${p}-btn ${action.variant === "primary" ? `${p}-btnPrimary` : `${p}-btnGhost`}`,
+					disabled: action.disabled === true,
+					onClick: action.onClick,
+					children: action.label
+				}, action.key))]
+			});
+		}
+		/** 只读提示 + 字段区 + 页脚（两种形态共用）。 */
+		function CardBody(props) {
+			const p = props.prefix;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+				props.readOnlyNotice !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: `${p}-readOnly`,
+					role: "status",
+					children: props.readOnlyNotice
+				}) : null,
+				props.children,
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)(CardFoot, { ...props })
+			] });
+		}
+		function CardChrome(props) {
+			const p = props.prefix;
+			const badge = props.statusBadge;
+			if (props.variant === "section") return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
+				className: `${p}-section`,
+				"aria-label": props.title,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: `${p}-sectionHead`,
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
+								className: `${p}-sectionTitle`,
+								children: props.title
+							}),
+							badge !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: `${p}-sectionBadge ${badge.on ? `${p}-statusOn` : `${p}-statusOff`}`,
+								children: badge.text
+							}) : null,
+							props.dirty ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: `${p}-pending`,
+								children: props.dirtyLabel
+							}) : null
+						]
+					}),
+					props.description === "" ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: `${p}-sectionDesc`,
+						children: props.description
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: `${p}-sectionBody`,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(CardBody, { ...props })
+					})
+				]
+			});
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", {
+				className: `${p}-card${props.open ? ` ${p}-cardOpen` : ""}`,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+					type: "button",
+					className: `${p}-header`,
+					"aria-expanded": props.open,
+					"aria-label": props.title,
+					onClick: () => props.onToggle(!props.open),
+					children: [
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+							className: `${p}-headText`,
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: `${p}-name`,
+								children: props.title
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: `${p}-description`,
+								children: props.description
+							})]
+						}),
+						badge !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: `${p}-statusBadge ${badge.on ? `${p}-statusOn` : `${p}-statusOff`}`,
+							children: badge.text
+						}) : null,
+						props.dirty ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: `${p}-pending`,
+							children: props.dirtyLabel
+						}) : null,
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutlineRegular, { className: `${p}-chevron${props.open ? ` ${p}-chevronOpen` : ""}` })
+					]
+				}), props.open ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					className: `${p}-body`,
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(CardBody, { ...props })
+				}) : null]
+			});
+		}
+		/** 取值未到达时的占位：与 CardChrome 同形态，避免宿主页里闪一次卡片外壳。 */
+		function CardLoading(props) {
+			if (props.variant === "section") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("section", {
+				className: `${props.prefix}-section`,
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: `${props.prefix}-readOnly`,
+					role: "status",
+					children: props.text
+				})
+			});
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", {
+				className: `${props.prefix}-card`,
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: `${props.prefix}-readOnly`,
+					role: "status",
+					children: props.text
+				})
+			});
+		}
+		//#endregion
+		//#region ../shared/src/client/config-slots.ts
+		/** dsh-plus 聚合 bundle 的包名（各插件 row 均经其补丁层插入 profile）。 */
+		const DSH_PLUS_BUNDLE = "@dsh-plus/bundle-main";
+		/**
+		* 视图 → 外壳形态：插件页 page 视图渲染在官方页面容器内（宿主已画标题、图标、
+		* 面包屑与页面级内边距），再套卡片会形成卡片套卡片并压缩移动端可用宽度，
+		* 故用无边框分节；summary 与 legacy 槽位保持卡片形态。
+		*/
+		function cardVariantFor(view) {
+			return view === "page" ? "section" : "card";
+		}
+		/**
+		* 把一张配置卡片同时注册进 legacy 与新版三个槽位。
+		* 任一槽位在当前 dsh 版本未声明时对应 inject 挂起等待，版本不命中即 no-op。
+		*/
+		function injectPluginConfigCard(slots, reg) {
+			const base = {
+				locale: reg.ns,
+				inject: reg.inject
+			};
+			slots.inject("settings.plugin.item", () => slots.register({
+				name: "settings.plugin.item",
+				key: reg.ns,
+				...base
+			}, reg.component));
+			slots.inject("plugins.row.config", () => slots.register({
+				name: "plugins.row.config",
+				key: `${DSH_PLUS_BUNDLE}#${reg.rowId}`,
+				...base
+			}, reg.component));
+			slots.inject("plugins.bundle.config", () => slots.register({
+				name: "plugins.bundle.config",
+				key: reg.pkg,
+				...base
+			}, reg.component));
+		}
+		//#endregion
+		//#region ../shared/src/client/draft.ts
+		/**
+		* 单命名空间 staged 草稿（简单配置卡片共用）：读 scope 快照、播种草稿、
+		* 脏判定、保存（revision fencing + 重新装载）与状态行。
+		*
+		* 语义与官方 staged 表单一致：Host 更新不覆盖在途编辑，只有保存才写回；
+		* 保存成功后按 Host 解析值重置草稿。`from`/`patch` 参与 effect 与 useMemo
+		* 依赖，必须是模块级稳定函数（不要内联箭头函数）。
+		* @module @dsh-plus/shared/client/draft
+		*/
+		function useNamespaceDraft(options) {
+			const { scope, api, from, patch, saveFailedLabel } = options;
+			const snapshot = (0, react.useSyncExternalStore)((listener) => scope.subscribe(listener), () => scope.getSnapshot());
+			const value = snapshot.value;
+			const [draft, setDraftState] = (0, react.useState)(null);
+			const [saving, setSaving] = (0, react.useState)(false);
+			const [status, setStatus] = (0, react.useState)(IDLE_STATUS);
+			(0, react.useEffect)(() => {
+				if (value === void 0 || draft !== null) return;
+				setDraftState(from(value));
+			}, [
+				value,
+				draft,
+				from
+			]);
+			const dirty = (0, react.useMemo)(() => value !== void 0 && draft !== null && JSON.stringify(patch(draft)) !== JSON.stringify(patch(from(value))), [
+				value,
+				draft,
+				from,
+				patch
+			]);
+			const setDraft = (next) => {
+				setDraftState(next);
+				setStatus(IDLE_STATUS);
+			};
+			const edit = (part) => {
+				if (draft === null) return;
+				setDraft({
+					...draft,
+					...part
+				});
+			};
+			const reset = () => {
+				if (value === void 0) return;
+				setDraft(from(value));
+			};
+			const save = () => {
+				if (draft === null) return;
+				setSaving(true);
+				const revision = scope.getSnapshot().revision;
+				api.update(patch(draft), revision).then(async () => {
+					await scope.load();
+					const next = scope.getSnapshot().value;
+					if (next !== void 0) setDraftState(from(next));
+					setStatus(IDLE_STATUS);
+				}).catch((error) => {
+					const message = error instanceof Error ? error.message : String(error);
+					setStatus({
+						kind: "error",
+						text: `${saveFailedLabel}${message}`
+					});
+				}).finally(() => setSaving(false));
+			};
+			return {
+				value,
+				draft,
+				dirty,
+				saving,
+				status,
+				disabled: !snapshot.writable,
+				setDraft,
+				edit,
+				reset,
+				save
+			};
+		}
+		//#endregion
+		//#region ../shared/src/client/fields.tsx
+		function TextField(props) {
+			const p = props.prefix ?? "dshp";
+			const invalid = props.invalid === true;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: `${p}-field`,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: `${p}-head`,
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
+							className: `${p}-label`,
+							htmlFor: props.id,
+							children: props.label
+						}), props.badge !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: `${p}-badge ${props.badge.set ? `${p}-badgeSet` : `${p}-badgeUnset`}`,
+							children: props.badge.text
+						}) : null]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+						id: props.id,
+						className: `${p}-input${invalid ? ` ${p}-inputInvalid` : ""}`,
+						type: props.password === true ? "password" : "text",
+						inputMode: props.numeric === true ? "numeric" : void 0,
+						autoComplete: props.password === true ? "off" : void 0,
+						"aria-invalid": invalid || void 0,
+						value: props.value,
+						disabled: props.disabled === true,
+						onChange: (event) => props.onEdit(event.target.value)
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: invalid ? `${p}-invalid` : `${p}-hint`,
+						children: invalid ? props.invalidLabel ?? "" : props.hint ?? ""
+					})
+				]
+			});
+		}
+		//#endregion
+		//#region ../shared/src/client/i18n.ts
+		/** 卡片通用文案（save/discard/unsaved/loading 等四插件共有键）。 */
+		const commonZh = {
+			save: "保存",
+			saving: "保存中…",
+			discard: "放弃",
+			unsaved: "未保存",
+			loading: "加载中…",
+			unavailable: "配置服务不可用。",
+			readOnly: "当前部署无 settings provider，配置为只读；请编辑 settings.yaml。",
+			invalidNumber: "请输入正整数。",
+			collapse: "收起",
+			expand: "展开",
+			enabledOn: "已启用",
+			enabledOff: "未启用",
+			saveFailed: "保存失败，请检查填写内容。",
+			confirm: "确认",
+			cancel: "取消"
+		};
+		const commonEn = {
+			save: "Save",
+			saving: "Saving…",
+			discard: "Discard",
+			unsaved: "Unsaved",
+			loading: "Loading…",
+			unavailable: "Settings service unavailable.",
+			readOnly: "No settings provider in this deployment; config is read-only. Edit settings.yaml.",
+			invalidNumber: "Enter a positive integer.",
+			collapse: "Collapse",
+			expand: "Expand",
+			enabledOn: "On",
+			enabledOff: "Off",
+			saveFailed: "Save failed; check the fields.",
+			confirm: "Confirm",
+			cancel: "Cancel"
+		};
+		/**
+		* own 覆盖同键合并（返回新对象，入参不可变）。
+		* 返回类型保留两侧键集合，调用方据此派生 DictKey。
+		*/
+		function mergeDict(base, own) {
+			return {
+				...base,
+				...own
+			};
+		}
+		//#endregion
+		//#region ../shared/src/client/scope.ts
+		/**
+		* remote.settings 直连实现的命名空间 scope（官方配置页 tab 同款模式）。
+		* 读：describe 取命名空间视图（脱敏 value/revision + 顶层 writable）；
+		* 刷新：remote `settings/document-updated`（按命名空间过滤）与
+		* `connection/reset`；generation 防旧读覆盖新发布。任何页面 origin
+		* （loopback 或 tailnet 信任域名）下行为一致。
+		* effect 归属调用方 fiber（label 需含插件名以便诊断）。
+		*/
+		function createSettingsScope(c, ns, label) {
+			const remote = c.get("remote");
+			let state = {
+				status: "loading",
+				value: void 0,
+				revision: void 0,
+				writable: false
+			};
+			const listeners = /* @__PURE__ */ new Set();
+			let generation = 0;
+			const publish = (next) => {
+				state = next;
+				for (const listener of [...listeners]) listener();
+			};
+			const load = async () => {
+				const gen = ++generation;
+				let view;
+				try {
+					const response = await remote.settings.describe();
+					if (!response.ok) return;
+					view = response.value;
+				} catch {
+					return;
+				}
+				if (gen !== generation) return;
+				const namespace = view.namespaces.find((candidate) => candidate.ns === ns);
+				if (namespace === void 0) {
+					publish({
+						status: "unavailable",
+						value: void 0,
+						revision: void 0,
+						writable: view.writable
+					});
+					return;
+				}
+				publish({
+					status: "ready",
+					value: namespace.value,
+					revision: namespace.revision,
+					writable: view.writable
+				});
+			};
+			const refresh = (namespace) => {
+				if (namespace !== void 0 && namespace !== ns) return;
+				load();
+			};
+			const disposers = [remote.$on("settings/document-updated", refresh), c.on("connection/reset", () => {
+				load();
+			})];
+			c.effect(() => () => {
+				for (const dispose of disposers) dispose();
+			}, label);
+			load();
+			return {
+				getSnapshot: () => state,
+				subscribe: (listener) => {
+					listeners.add(listener);
+					return () => {
+						listeners.delete(listener);
+					};
+				},
+				load
+			};
+		}
+		/** 以 remote.settings 构造命名空间绑定的 api 面。 */
+		function createNamespaceApi(remote, ns) {
+			return {
+				update: async (patch, expectedRevision) => {
+					const response = await remote.update(ns, patch, expectedRevision);
+					if (!response.ok) throw new Error(response.error.message ?? "settings update failed");
+				},
+				describe: async () => {
+					const response = await remote.describe();
+					if (!response.ok) throw new Error(response.error.message ?? "settings describe failed");
+					return response.value;
+				}
+			};
+		}
+		//#endregion
+		//#region ../shared/src/client/styles.ts
+		/**
+		* 配置卡片样式工厂（各插件 client 的公共收编版）。
+		* 视觉规则与迁移前逐字一致（类名前缀换为各插件自身，DOM 类名不变），
+		* 另补移动端与可达性增强（767px 断点 + pointer:coarse，对齐 ui-mobile-fit 约定）：
+		* - 窄屏 input/textarea 16px（防 iOS 聚焦缩放）、可点目标 ≥44px；
+		* - footer 按钮等宽换行、状态文字独占一行；
+		* - 展开态 body 底部 sticky 保存栏（长表单滚动中始终可达）。
+		* - 分节形态（-section，插件页 page 视图内嵌宿主页面）：无边框/背景、横向零
+		*   内边距，页脚不 sticky——官方插件页已提供页面级内边距，再叠一层卡片会
+		*   缩窄移动端可用宽度（卡片套卡片）。
+		* 沿用官方 data-plugin / data-plugin-css 约定（HMR 据此卸载），不覆盖上游选择器。
+		* @module @dsh-plus/shared/client/styles
+		*/
+		/** 生成全套卡片 CSS；prefix 为插件类名前缀（如 'dne'），extra 为插件特有规则。 */
+		function cardCss(prefix, extra = "") {
+			return `
+.${prefix}-card{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);border-radius:12px;list-style:none;transition:border-color .16s,background .16s}
+.${prefix}-card:hover{border-color:var(--dsw-alias-label-dimmed)}
+.${prefix}-cardOpen{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-label-dimmed)}
+.${prefix}-header{appearance:none;width:100%;font:inherit;color:inherit;text-align:left;cursor:pointer;background:0 0;border:0;border-radius:12px;align-items:center;gap:12px;padding:14px 16px;display:flex}
+.${prefix}-header:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:-2px}
+.${prefix}-headText{flex-direction:column;flex:1;gap:4px;min-width:0;display:flex}
+.${prefix}-name{color:var(--dsw-alias-label-primary);font-size:15px;font-weight:600;line-height:1.4}
+.${prefix}-description{color:var(--dsw-alias-label-tertiary);font-size:13px;line-height:1.5}
+.${prefix}-chevron{color:var(--dsw-alias-label-tertiary);flex:none;transition:transform .16s;display:inline-flex}
+.${prefix}-chevronOpen{transform:rotate(180deg)}
+.${prefix}-pending{white-space:nowrap;background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary);border-radius:999px;flex:none;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}
+.${prefix}-statusBadge{white-space:nowrap;border-radius:999px;flex:none;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}
+.${prefix}-statusOn{background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary)}
+.${prefix}-statusOff{color:var(--dsw-alias-label-tertiary)}
+.${prefix}-body{border-top:1px solid var(--dsw-alias-border-l2);margin:0 16px;padding-bottom:8px}
+.${prefix}-field{flex-direction:column;gap:6px;padding:12px 0;display:flex}
+.${prefix}-field+.${prefix}-field{border-top:1px solid var(--dsw-alias-border-l2)}
+.${prefix}-head{align-items:center;gap:8px;display:flex}
+.${prefix}-label{min-width:0;color:var(--dsw-alias-label-primary);flex:1;font-size:13px;font-weight:500;line-height:1.5}
+.${prefix}-badge{white-space:nowrap;border-radius:999px;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}
+.${prefix}-badgeSet{background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary)}
+.${prefix}-badgeUnset{color:var(--dsw-alias-label-tertiary)}
+.${prefix}-input{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);height:34px;font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 12px;font-size:13px;transition:border-color .18s,background .18s}
+.${prefix}-input:hover:not(:disabled):not(:focus-visible){border-color:var(--dsw-alias-label-dimmed)}
+.${prefix}-input:focus-visible{border-color:var(--dsw-alias-brand-primary);outline:none}
+.${prefix}-input:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}
+.${prefix}-inputInvalid{border-color:var(--dsw-alias-label-error)}
+.${prefix}-select{appearance:none;background:var(--dsw-alias-bg-module-platform);border:none;cursor:pointer;background-image:linear-gradient(45deg,transparent 50%,var(--dsw-alias-label-secondary) 50%),linear-gradient(135deg,var(--dsw-alias-label-secondary) 50%,transparent 50%);background-position:calc(100% - 16px) 50%,calc(100% - 11px) 50%;background-size:5px 5px;background-repeat:no-repeat;color:var(--dsw-alias-label-primary);font:inherit;font-size:13px;height:34px;box-sizing:border-box;border-radius:8px;padding:0 30px 0 12px;transition:background-color .18s}
+.${prefix}-select:hover:not(:disabled){background-color:var(--dsw-alias-interactive-bg-hover)}
+.${prefix}-hint{color:var(--dsw-alias-label-tertiary);margin:0;font-size:12px;line-height:1.5}
+.${prefix}-invalid{color:var(--dsw-alias-label-error);margin:0;font-size:12px;line-height:1.5}
+.${prefix}-checkRow{align-items:center;gap:10px;display:flex;padding:6px 0}
+.${prefix}-checkRow label{color:var(--dsw-alias-label-primary);font-size:13px;line-height:1.5;cursor:pointer;flex:1;min-width:0}
+/* 自绘圆角扁平开关（官方 UI 无可见原生 checkbox，选择类全走胶囊/菜单） */
+.${prefix}-checkRow input{appearance:none;-webkit-appearance:none;position:relative;box-sizing:border-box;background:var(--dsw-alias-bg-module-platform);border:none;border-radius:999px;width:34px;height:20px;flex:none;cursor:pointer;transition:background .18s;margin:0}
+.${prefix}-checkRow input::after{content:"";position:absolute;top:2px;left:2px;background:var(--dsw-alias-label-primary);border-radius:999px;width:16px;height:16px;transition:left .18s cubic-bezier(.4,0,.2,1)}
+.${prefix}-checkRow input:checked{background:var(--dsw-alias-brand-primary)}
+.${prefix}-checkRow input:checked::after{left:16px;background:var(--dsw-alias-bg-base)}
+.${prefix}-checkRow input:disabled{opacity:.4;cursor:default}
+.${prefix}-checkRow input:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:2px}
+/* 宿主内嵌分节形态（插件页 page 视图）：官方设置页同构——无边框/背景，
+   横向零内边距（宽度交给宿主页面容器），小节标题 13px/600，页脚非 sticky。 */
+.${prefix}-section{box-sizing:border-box;flex-direction:column;width:100%;min-width:0;padding:16px 0;display:flex}
+.${prefix}-sectionHead{align-items:center;gap:8px;min-width:0;display:flex}
+.${prefix}-sectionTitle{min-width:0;color:var(--dsw-alias-label-primary);flex:1;margin:0;font-size:13px;font-weight:600;line-height:1.5}
+.${prefix}-sectionBadge{white-space:nowrap;border-radius:999px;flex:none;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}
+.${prefix}-sectionDesc{color:var(--dsw-alias-label-tertiary);margin:4px 0 0;font-size:12px;line-height:1.5}
+.${prefix}-sectionBody{flex-direction:column;min-width:0;display:flex}
+.${prefix}-sectionFooter{align-items:center;gap:8px;padding-top:16px;display:flex;flex-wrap:wrap}
+.${prefix}-groupLabel{color:var(--dsw-alias-label-secondary);font-size:12px;font-weight:600;padding:12px 0 2px;margin:0}
+.${prefix}-readOnly{color:var(--dsw-alias-label-tertiary);margin:12px 0 0;font-size:12px;line-height:1.5}
+.${prefix}-warn{color:var(--dsw-alias-label-error);margin:12px 0 0;font-size:12px;line-height:1.5}
+.${prefix}-footer{border-top:1px solid var(--dsw-alias-border-l2);justify-content:flex-end;align-items:center;gap:8px;padding:12px 0 4px;display:flex;flex-wrap:wrap}
+.${prefix}-status{min-width:0;color:var(--dsw-alias-label-secondary);flex:1;margin:0;font-size:12px;line-height:1.5}
+.${prefix}-statusError{color:var(--dsw-alias-label-error)}
+.${prefix}-btn{appearance:none;font:inherit;cursor:pointer;border:1px solid #0000;border-radius:8px;padding:5px 14px;font-size:13px;line-height:1.5}
+.${prefix}-btnGhost{border-color:var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);background:0 0}
+.${prefix}-btnGhost:hover:not(:disabled){color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-dimmed)}
+.${prefix}-btnPrimary{background:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3)}
+.${prefix}-btn:disabled{opacity:.4;cursor:default}
+.${prefix}-btn:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:1px}
+@media (max-width:767px){
+.${prefix}-body{margin:0 10px}
+.${prefix}-header{padding:12px 12px}
+.${prefix}-input,.${prefix}-select{font-size:16px;height:40px}
+.${prefix}-checkRow{min-height:44px;padding:8px 0}
+.${prefix}-footer{position:sticky;bottom:0;background:var(--dsw-alias-bg-layer-2);margin:0 -10px;padding:10px 10px 6px;border-top:1px solid var(--dsw-alias-border-l2);border-bottom-left-radius:12px;border-bottom-right-radius:12px}
+.${prefix}-status{flex-basis:100%;flex:none}
+.${prefix}-btn{min-height:44px;flex:1;min-width:96px}
+.${prefix}-statusBadge{display:none}
+.${prefix}-sectionBadge{display:inline-block}
+.${prefix}-sectionFooter{position:static}
+}
+@media (pointer:coarse){
+.${prefix}-btn{min-height:44px}
+.${prefix}-checkRow{min-height:44px}
+.${prefix}-input,.${prefix}-select{height:40px}
+}
+${extra}
+`;
+		}
+		/**
+		* 幂等注入样式标签（官方 data-plugin-css 约定）；返回新标签，
+		* 已存在或环境无 document 时返回 null（调用方 effect 卸载用）。
+		*/
+		function injectCardStyle(pluginId, css) {
+			if (typeof document === "undefined") return null;
+			const tagId = `${pluginId}/card.css`;
+			if (document.querySelector(`style[data-plugin-css=${JSON.stringify(tagId)}]`) !== null) return null;
+			const tag = document.createElement("style");
+			tag.dataset.plugin = pluginId;
+			tag.dataset.pluginCss = tagId;
+			tag.textContent = css;
+			document.head.appendChild(tag);
+			return tag;
+		}
+		//#endregion
+		//#region src/ns.ts
+		/**
+		* settings 命名空间字面量（纯常量，零依赖）。
+		* 服务端以字面量注册 settings section（用户层配置落 $DSH_HOME/settings.yaml，
+		* 热生效）；与行级 cordis Config 共用同一份 schemastery schema（config.ts）。
+		* @module web-search-services/ns
+		*/
+		const SETTINGS_NS = "dsh-plus-web-search-services";
+		//#endregion
+		//#region src/client/draft.ts
+		/** 可选后端（与 config.ts 的 PRIORITY_ENTRY union 同源顺序）。 */
+		const SEARCH_BACKENDS = [
+			"tavily",
+			"exa",
+			"openai-chat"
+		];
+		/** 单次搜索子进程超时下限（与 config.ts 的 .min(1000) 一致）。 */
+		const TIMEOUT_MIN_MS = 1e3;
+		function draftFromValue(value) {
+			return {
+				scriptPath: value.scriptPath,
+				envFile: value.envFile,
+				python: value.python,
+				priorityText: value.priority.join("\n"),
+				timeoutMsText: String(value.timeoutMs)
+			};
+		}
+		/** 优先级文本 → 后端序列；顺带返回无法识别的行（供 UI 提示）。 */
+		function parsePriority(text) {
+			const backends = [];
+			const unknown = [];
+			const duplicated = [];
+			for (const raw of text.split("\n")) {
+				const line = raw.trim();
+				if (line === "") continue;
+				const match = SEARCH_BACKENDS.find((backend) => backend === line);
+				if (match === void 0) {
+					unknown.push(line);
+					continue;
+				}
+				if (backends.includes(match)) {
+					duplicated.push(line);
+					continue;
+				}
+				backends.push(match);
+			}
+			return {
+				backends,
+				unknown,
+				duplicated
+			};
+		}
+		/** 优先级是否可用：至少一个后端、无未知项、无重复项。 */
+		function priorityTextOk(text) {
+			const { backends, unknown, duplicated } = parsePriority(text);
+			return backends.length > 0 && unknown.length === 0 && duplicated.length === 0;
+		}
+		/** 超时是否可用：≥1000 的整数（对齐 schema 的 .natural().min(1000)）。 */
+		function timeoutTextOk(text) {
+			if (!/^\d+$/.test(text.trim())) return false;
+			return Number(text) >= TIMEOUT_MIN_MS;
+		}
+		/** 草稿 → 提交形状（调用方保证已通过校验）。 */
+		function toPatch(draft) {
+			return {
+				scriptPath: draft.scriptPath,
+				envFile: draft.envFile,
+				python: draft.python,
+				priority: parsePriority(draft.priorityText).backends,
+				timeoutMs: Number(draft.timeoutMsText)
+			};
+		}
+		//#endregion
+		//#region src/client/card.tsx
+		/**
+		* 「搜索后端聚合」配置卡片：经 injectPluginConfigCard 注册（legacy
+		* settings.plugin.item 与插件页 plugins.row.config / plugins.bundle.config，
+		* view 分发 summary/page）。
+		* 字段：scriptPath / envFile / python / priority（每行一个后端）/ timeoutMs。
+		* 密钥不走卡片：keys 段的 role(secret) 字段只允许 profile 行级注入，用户层
+		* 写入会被脱敏遮蔽——卡片改为把密钥来源（env 文件）与覆盖方式写在页面上。
+		* 外壳与控件走 @dsh-plus/shared/client 套件（CardChrome/TextField/
+		* useNamespaceDraft）；纯校验逻辑在同目录 draft.ts（node --test 可直测）。
+		* @module web-search-services/client/card
+		*/
+		function WebSearchServicesCard(props) {
+			const { t, scope, api } = props;
+			const { draft, dirty, saving, status, disabled, edit, reset, save } = useNamespaceDraft({
+				scope,
+				api,
+				from: draftFromValue,
+				patch: toPatch,
+				saveFailedLabel: t("saveFailed")
+			});
+			const [open, setOpen] = (0, react.useState)(props.view === "page");
+			if (props.view === "summary") return t("summaryLine");
+			const variant = cardVariantFor(props.view);
+			if (draft === null) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(CardLoading, {
+				prefix: "wsv",
+				variant,
+				text: t("loading")
+			});
+			const priorityInvalid = !priorityTextOk(draft.priorityText);
+			const timeoutInvalid = !timeoutTextOk(draft.timeoutMsText);
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(CardChrome, {
+				prefix: "wsv",
+				title: t("title"),
+				description: t("description"),
+				open,
+				onToggle: setOpen,
+				variant,
+				dirty,
+				dirtyLabel: t("unsaved"),
+				readOnlyNotice: disabled ? t("readOnly") : void 0,
+				status,
+				actions: [{
+					key: "discard",
+					label: t("discard"),
+					disabled: !dirty || saving,
+					onClick: reset
+				}, {
+					key: "save",
+					label: t(saving ? "saving" : "save"),
+					variant: "primary",
+					disabled: !dirty || priorityInvalid || timeoutInvalid || saving || disabled,
+					onClick: save
+				}],
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(TextField, {
+						prefix: "wsv",
+						id: "wsv-script",
+						label: t("scriptPath"),
+						hint: t("scriptPathHint"),
+						value: draft.scriptPath,
+						disabled,
+						onEdit: (v) => edit({ scriptPath: v })
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(TextField, {
+						prefix: "wsv",
+						id: "wsv-envfile",
+						label: t("envFile"),
+						hint: t("envFileHint"),
+						value: draft.envFile,
+						disabled,
+						onEdit: (v) => edit({ envFile: v })
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(TextField, {
+						prefix: "wsv",
+						id: "wsv-python",
+						label: t("python"),
+						hint: t("pythonHint"),
+						value: draft.python,
+						disabled,
+						onEdit: (v) => edit({ python: v })
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "wsv-field",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: "wsv-head",
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
+									className: "wsv-label",
+									htmlFor: "wsv-priority",
+									children: t("priority")
+								})
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("textarea", {
+								id: "wsv-priority",
+								className: "wsv-priority",
+								rows: 3,
+								value: draft.priorityText,
+								disabled,
+								onChange: (event) => edit({ priorityText: event.target.value })
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: priorityInvalid ? "wsv-invalid" : "wsv-hint",
+								children: priorityInvalid ? t("invalidPriority") : t("priorityHint")
+							})
+						]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(TextField, {
+						prefix: "wsv",
+						id: "wsv-timeout",
+						label: t("timeoutMs"),
+						hint: t("timeoutMsHint"),
+						value: draft.timeoutMsText,
+						numeric: true,
+						disabled,
+						invalid: timeoutInvalid,
+						invalidLabel: t("invalidTimeout"),
+						onEdit: (v) => edit({ timeoutMsText: v })
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "wsv-keys",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "wsv-keysTitle",
+								children: t("keysGroup")
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "wsv-hint",
+								children: t("keysHint")
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "wsv-hint",
+								children: t("keysUserLayerHint")
+							})
+						]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: "wsv-hint",
+						children: t("reloadHint")
+					})
+				]
+			});
+		}
+		//#endregion
+		//#region src/client/i18n.ts
+		/**
+		* 配置卡片文案（zh/en）。经 ctx.locale.register 注册、bind 取用。
+		* 公共键（save/discard/unsaved 等）来自 shared 的 common 字典，本文件只维护业务键。
+		* @module web-search-services/client/i18n
+		*/
+		const NS = "dsh-plus-web-search-services";
+		const ownZh = {
+			title: "搜索后端聚合",
+			description: "把 search-services skill 接成 dsh 的 web_search 后端：按优先级尝试 Tavily / Exa / OpenAI-compatible，失败自动回退。",
+			summaryLine: "web_search 免费后端聚合：优先级链 + 失败自动回退（密钥读 skill 的 env 文件）。",
+			scriptPath: "search.py 路径",
+			scriptPathHint: "留空 = 使用随包内置脚本；支持 ~ 展开。",
+			envFile: "密钥 env 文件",
+			envFileHint: "默认 ~/.config/search-services/env（skill 的单事实源）；留空表示不读该文件。支持 ~ 展开。",
+			python: "python 解释器",
+			pythonHint: "可含参数（如 py -3）；留空 = 自动发现（桌面捆绑运行时 → PATH → 平台兜底名）。",
+			priority: "后端优先级",
+			priorityHint: "每行一个，靠前先试，失败自动回退到下一个。可选值：tavily、exa、openai-chat；重复或未知值会被拒绝保存。",
+			timeoutMs: "单次搜索超时（毫秒）",
+			timeoutMsHint: "应低于 dsh-tool-web 的 searchTimeoutMs；下限 1000，默认 55000。",
+			invalidPriority: "请填写至少一个有效后端，且不要重复",
+			invalidTimeout: "请输入不小于 1000 的整数",
+			keysGroup: "密钥与覆盖项（本卡片不编辑）",
+			keysHint: "密钥主来源是上面的 env 文件，保持 skill 单事实源：TAVILY_API_KEY、EXA_API_KEY、SEARCH_OPENAI_API_KEY，以及可选的 SEARCH_OPENAI_BASE_URL、SEARCH_OPENAI_MODEL。",
+			keysUserLayerHint: "schema 里的 keys 段是行级覆盖逃生舱（role(secret) 字段只允许 profile 行级注入）；写入 settings.yaml 用户层会被脱敏遮蔽，因此配置卡片不提供编辑。需要覆盖时请改 env 文件，或在 profile 的 cordis.patch.yml 行级注入。",
+			reloadHint: "改动热生效（下一次 web_search 调用即用新配置）；scriptPath / python 变化无需重启。"
+		};
+		const ownEn = {
+			title: "Search backend aggregation",
+			description: "Bridges the search-services skill into dsh as a web_search backend: tries Tavily / Exa / OpenAI-compatible in priority order with automatic fallback.",
+			summaryLine: "web_search backend aggregation: priority chain with automatic fallback (keys from the skill env file).",
+			scriptPath: "search.py path",
+			scriptPathHint: "Empty uses the bundled copy; ~ is expanded.",
+			envFile: "Credential env file",
+			envFileHint: "Defaults to ~/.config/search-services/env (the skill’s single source); empty skips the file. ~ is expanded.",
+			python: "Python interpreter",
+			pythonHint: "May include arguments (e.g. py -3); empty auto-detects (desktop runtime → PATH → platform default).",
+			priority: "Backend priority",
+			priorityHint: "One per line, earlier first, with automatic fallback on failure. Allowed: tavily, exa, openai-chat; duplicates or unknown values block saving.",
+			timeoutMs: "Per-search timeout (ms)",
+			timeoutMsHint: "Keep it below dsh-tool-web’s searchTimeoutMs; minimum 1000, default 55000.",
+			invalidPriority: "Enter at least one valid backend without duplicates",
+			invalidTimeout: "Enter an integer of at least 1000",
+			keysGroup: "Credentials and overrides (not edited here)",
+			keysHint: "Credentials come from the env file above, keeping the skill as the single source: TAVILY_API_KEY, EXA_API_KEY, SEARCH_OPENAI_API_KEY, plus optional SEARCH_OPENAI_BASE_URL and SEARCH_OPENAI_MODEL.",
+			keysUserLayerHint: "The keys section in the schema is a line-level escape hatch (role(secret) fields accept profile-line injection only); values written to the settings.yaml user layer are masked, so this card offers no editor. To override, edit the env file or inject at the profile row in cordis.patch.yml.",
+			reloadHint: "Changes apply hot (the next web_search call uses them); scriptPath / python need no restart."
+		};
+		const zh = mergeDict(commonZh, ownZh);
+		const en = mergeDict(commonEn, ownEn);
+		//#endregion
+		//#region src/client/styles.ts
+		/**
+		* 配置卡片样式：基础规则走 @dsh-plus/shared/client 的 cardCss('wsv')，
+		* 本文件只补插件特有规则（优先级多行文本域、密钥说明块）。
+		* 沿用官方 data-plugin / data-plugin-css 约定（HMR 据此卸载）。
+		* @module web-search-services/client/styles
+		*/
+		const PLUGIN_ID = "@dsh-plus/web-search-services";
+		const cardCssAll = cardCss("wsv", `
+.wsv-priority{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:8px 12px;font-size:13px;line-height:1.6;min-height:72px;resize:vertical;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+.wsv-priority:focus-visible{border-color:var(--dsw-alias-brand-primary);outline:none}
+.wsv-priority:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}
+.wsv-keys{border:1px solid var(--dsw-alias-border-l2);border-radius:8px;margin:12px 0 0;padding:10px 12px}
+.wsv-keysTitle{color:var(--dsw-alias-label-secondary);margin:0;font-size:12px;font-weight:600}
+@media (max-width:767px){
+.wsv-priority{font-size:16px}
+}
+`);
+		/** 幂等注入样式标签；返回标签（已存在或环境无 document 时为 null）。 */
+		function injectStyle() {
+			return injectCardStyle(PLUGIN_ID, cardCssAll);
+		}
+		//#endregion
+		//#region src/client/client.ts
+		const name = "dsh-plus-web-search-services";
+		/** 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。 */
+		const inject = [
+			"slots",
+			"locale",
+			"remote",
+			"remote.settings"
+		];
+		function apply(ctx) {
+			const c = ctx;
+			const tag = injectStyle();
+			c.effect(() => () => {
+				tag?.remove();
+			}, "web-search-services: style");
+			c.effect(() => c.locale.register(NS, {
+				zh,
+				en
+			}), "web-search-services: locale");
+			const scope = createSettingsScope(c, SETTINGS_NS, "web-search-services: settings scope");
+			const api = createNamespaceApi(c.get("remote").settings, SETTINGS_NS);
+			injectPluginConfigCard(c.slots, {
+				ns: SETTINGS_NS,
+				rowId: "dsh-plus-web-search-services",
+				pkg: "@dsh-plus/web-search-services",
+				component: WebSearchServicesCard,
+				inject: () => ({
+					t: c.locale.bind(NS),
+					scope,
+					api
+				})
+			});
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		exports.name = name;
+		return module.exports;
+	}
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/web-search-services",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "dsh-plus service plugin: web_search 免费后端聚合——经官方 ctx.web provider 扩展点桥接 search-services skill（Tavily/Exa/OpenAI Chat 免费额度，优先级+自动回退+key 配置），官方 web_search 工具与输出格式零修改",
   "type": "module",
   "main": "lib/index.js",
@@ -10,6 +10,9 @@
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./client": {
+      "default": "./lib/client.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
@@ -18,8 +21,18 @@
     "src",
     "scripts"
   ],
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
   "dependencies": {
-    "@dsh-plus/shared": "0.1.30"
+    "@dsh-plus/shared": "0.1.31"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
@@ -33,12 +46,15 @@
     "@deepseek-ai/dsh-home-paths": "0.2.0-rc.1",
     "@deepseek-ai/dsh-settings": "0.2.0-rc.1",
     "@deepseek-ai/dsh-web": "0.2.0-rc.1",
-    "@deepseek-ai/schemastery": "3.18.4"
+    "@deepseek-ai/schemastery": "3.18.4",
+    "@types/react": "~18.3.31",
+    "react": "^18.2.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsdown src/index.ts -d lib --format esm --dts --no-fixed-extension"
+    "build": "tsdown",
+    "watch": "tsdown --watch"
   }
 }

package/src/client/card.tsx

@@ -0,0 +1,152 @@
+/**
+ * 「搜索后端聚合」配置卡片：经 injectPluginConfigCard 注册（legacy
+ * settings.plugin.item 与插件页 plugins.row.config / plugins.bundle.config，
+ * view 分发 summary/page）。
+ * 字段：scriptPath / envFile / python / priority（每行一个后端）/ timeoutMs。
+ * 密钥不走卡片：keys 段的 role(secret) 字段只允许 profile 行级注入，用户层
+ * 写入会被脱敏遮蔽——卡片改为把密钥来源（env 文件）与覆盖方式写在页面上。
+ * 外壳与控件走 @dsh-plus/shared/client 套件（CardChrome/TextField/
+ * useNamespaceDraft）；纯校验逻辑在同目录 draft.ts（node --test 可直测）。
+ * @module web-search-services/client/card
+ */
+
+import {
+  CardChrome,
+  CardLoading,
+  cardVariantFor,
+  type NamespaceSettingsApi,
+  type PluginConfigViewProps,
+  type Scope,
+  TextField,
+  useNamespaceDraft,
+} from '@dsh-plus/shared/client'
+import { type ReactElement, useState } from 'react'
+
+import {
+  type ConfigValue,
+  type Draft,
+  draftFromValue,
+  priorityTextOk,
+  timeoutTextOk,
+  toPatch,
+} from './draft.ts'
+import type { Translate } from './i18n.ts'
+
+export interface CardProps extends PluginConfigViewProps {
+  t: Translate
+  scope: Scope
+  api: NamespaceSettingsApi
+}
+
+export function WebSearchServicesCard(props: CardProps): ReactElement | string | null {
+  const { t, scope, api } = props
+  const { draft, dirty, saving, status, disabled, edit, reset, save } = useNamespaceDraft<
+    ConfigValue,
+    Draft
+  >({ scope, api, from: draftFromValue, patch: toPatch, saveFailedLabel: t('saveFailed') })
+  // 插件页 page 视图为表单落地页，默认展开；旧槽位无 view，保持折叠。
+  const [open, setOpen] = useState(props.view === 'page')
+
+  // 插件页 summary 视图只出一行简介（hooks 已全部落定，可安全提前返回）。
+  if (props.view === 'summary') return t('summaryLine')
+
+  // 插件页 page 视图内嵌宿主页面容器（已带页面级内边距与标题），用无边框分节。
+  const variant = cardVariantFor(props.view)
+  if (draft === null) return <CardLoading prefix="wsv" variant={variant} text={t('loading')} />
+
+  const priorityInvalid = !priorityTextOk(draft.priorityText)
+  const timeoutInvalid = !timeoutTextOk(draft.timeoutMsText)
+  return (
+    <CardChrome
+      prefix="wsv"
+      title={t('title')}
+      description={t('description')}
+      open={open}
+      onToggle={setOpen}
+      variant={variant}
+      dirty={dirty}
+      dirtyLabel={t('unsaved')}
+      readOnlyNotice={disabled ? t('readOnly') : undefined}
+      status={status}
+      actions={[
+        {
+          key: 'discard',
+          label: t('discard'),
+          disabled: !dirty || saving,
+          onClick: reset,
+        },
+        {
+          key: 'save',
+          label: t(saving ? 'saving' : 'save'),
+          variant: 'primary',
+          disabled: !dirty || priorityInvalid || timeoutInvalid || saving || disabled,
+          onClick: save,
+        },
+      ]}
+    >
+      <TextField
+        prefix="wsv"
+        id="wsv-script"
+        label={t('scriptPath')}
+        hint={t('scriptPathHint')}
+        value={draft.scriptPath}
+        disabled={disabled}
+        onEdit={(v) => edit({ scriptPath: v })}
+      />
+      <TextField
+        prefix="wsv"
+        id="wsv-envfile"
+        label={t('envFile')}
+        hint={t('envFileHint')}
+        value={draft.envFile}
+        disabled={disabled}
+        onEdit={(v) => edit({ envFile: v })}
+      />
+      <TextField
+        prefix="wsv"
+        id="wsv-python"
+        label={t('python')}
+        hint={t('pythonHint')}
+        value={draft.python}
+        disabled={disabled}
+        onEdit={(v) => edit({ python: v })}
+      />
+      <div className="wsv-field">
+        <div className="wsv-head">
+          <label className="wsv-label" htmlFor="wsv-priority">
+            {t('priority')}
+          </label>
+        </div>
+        <textarea
+          id="wsv-priority"
+          className="wsv-priority"
+          rows={3}
+          value={draft.priorityText}
+          disabled={disabled}
+          onChange={(event) => edit({ priorityText: event.target.value })}
+        />
+        <p className={priorityInvalid ? 'wsv-invalid' : 'wsv-hint'}>
+          {priorityInvalid ? t('invalidPriority') : t('priorityHint')}
+        </p>
+      </div>
+      <TextField
+        prefix="wsv"
+        id="wsv-timeout"
+        label={t('timeoutMs')}
+        hint={t('timeoutMsHint')}
+        value={draft.timeoutMsText}
+        numeric
+        disabled={disabled}
+        invalid={timeoutInvalid}
+        invalidLabel={t('invalidTimeout')}
+        onEdit={(v) => edit({ timeoutMsText: v })}
+      />
+      <div className="wsv-keys">
+        <p className="wsv-keysTitle">{t('keysGroup')}</p>
+        <p className="wsv-hint">{t('keysHint')}</p>
+        <p className="wsv-hint">{t('keysUserLayerHint')}</p>
+      </div>
+      <p className="wsv-hint">{t('reloadHint')}</p>
+    </CardChrome>
+  )
+}

package/src/client/client.ts

@@ -0,0 +1,51 @@
+/**
+ * 浏览器半入口：注册 locale 字典 + 注册「搜索后端聚合」卡片
+ * （injectPluginConfigCard 三槽位：legacy settings.plugin.item 与插件页
+ * plugins.row.config / plugins.bundle.config）。
+ * 构建产物为 window.__ModuleLoader__.load({id, factory}) 形式的 CJS factory
+ * （包装见 tsdown.config.ts）；样式沿用官方 data-plugin-css 约定，HMR 据此卸载。
+ * 配置读写经 ctx.remote.settings 直连（scope/api 来自 @dsh-plus/shared/client）；
+ * 密钥不经卡片（role(secret) 只允许行级注入），见 card.tsx 的说明块。
+ * @module web-search-services/client
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import {
+  createNamespaceApi,
+  createSettingsScope,
+  injectPluginConfigCard,
+  type PluginClientContext,
+} from '@dsh-plus/shared/client'
+
+import { SETTINGS_NS } from '../ns.ts'
+import { WebSearchServicesCard } from './card.tsx'
+import { type DictKey, en, NS, zh } from './i18n.ts'
+import { injectStyle } from './styles.ts'
+
+export const name = 'dsh-plus-web-search-services'
+
+/** 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。 */
+export const inject = ['slots', 'locale', 'remote', 'remote.settings'] as const
+
+/** 宿主窄面收编在 @dsh-plus/shared/client；TKey 传入本包 DictKey 使键名受检。 */
+type ClientContext = PluginClientContext<DictKey>
+
+export function apply(ctx: Context): void {
+  const c = ctx as unknown as ClientContext
+  const tag = injectStyle()
+  c.effect(
+    () => () => {
+      tag?.remove()
+    },
+    'web-search-services: style',
+  )
+  c.effect(() => c.locale.register(NS, { zh, en }), 'web-search-services: locale')
+  const scope = createSettingsScope(c, SETTINGS_NS, 'web-search-services: settings scope')
+  const api = createNamespaceApi(c.get('remote').settings, SETTINGS_NS)
+  injectPluginConfigCard(c.slots, {
+    ns: SETTINGS_NS,
+    rowId: 'dsh-plus-web-search-services',
+    pkg: '@dsh-plus/web-search-services',
+    component: WebSearchServicesCard,
+    inject: () => ({ t: c.locale.bind(NS), scope, api }),
+  })
+}

package/src/client/draft.ts

@@ -0,0 +1,92 @@
+/**
+ * 配置卡片草稿的纯逻辑（无 React/JSX，供 node --test 直接导入）：
+ * 解析值 → 草稿、草稿 → 提交形状，以及优先级列表与超时的校验。
+ * @module web-search-services/client/draft
+ */
+import type { SearchBackend } from '../config.ts'
+
+/** 可选后端（与 config.ts 的 PRIORITY_ENTRY union 同源顺序）。 */
+export const SEARCH_BACKENDS: readonly SearchBackend[] = ['tavily', 'exa', 'openai-chat']
+
+/** 默认后端顺序（与 config.ts 的 DEFAULT_PRIORITY 一致）。 */
+export const DEFAULT_PRIORITY: readonly SearchBackend[] = ['tavily', 'exa', 'openai-chat']
+
+/** 单次搜索子进程超时下限（与 config.ts 的 .min(1000) 一致）。 */
+export const TIMEOUT_MIN_MS = 1000
+
+/** settings 命名空间的解析值（keys 内 secret 字段已被 describe 层遮蔽，卡片不消费）。 */
+export interface ConfigValue {
+  scriptPath: string
+  envFile: string
+  python: string
+  priority: SearchBackend[]
+  timeoutMs: number
+}
+
+/** 编辑草稿：字符串字段原样，数组与数值以文本承载（保存时校验并折算）。 */
+export interface Draft {
+  scriptPath: string
+  envFile: string
+  python: string
+  priorityText: string
+  timeoutMsText: string
+}
+
+export function draftFromValue(value: ConfigValue): Draft {
+  return {
+    scriptPath: value.scriptPath,
+    envFile: value.envFile,
+    python: value.python,
+    priorityText: value.priority.join('\n'),
+    timeoutMsText: String(value.timeoutMs),
+  }
+}
+
+/** 优先级文本 → 后端序列；顺带返回无法识别的行（供 UI 提示）。 */
+export function parsePriority(text: string): {
+  backends: SearchBackend[]
+  unknown: string[]
+  duplicated: string[]
+} {
+  const backends: SearchBackend[] = []
+  const unknown: string[] = []
+  const duplicated: string[] = []
+  for (const raw of text.split('\n')) {
+    const line = raw.trim()
+    if (line === '') continue
+    const match = SEARCH_BACKENDS.find((backend) => backend === line)
+    if (match === undefined) {
+      unknown.push(line)
+      continue
+    }
+    if (backends.includes(match)) {
+      duplicated.push(line)
+      continue
+    }
+    backends.push(match)
+  }
+  return { backends, unknown, duplicated }
+}
+
+/** 优先级是否可用：至少一个后端、无未知项、无重复项。 */
+export function priorityTextOk(text: string): boolean {
+  const { backends, unknown, duplicated } = parsePriority(text)
+  return backends.length > 0 && unknown.length === 0 && duplicated.length === 0
+}
+
+/** 超时是否可用：≥1000 的整数（对齐 schema 的 .natural().min(1000)）。 */
+export function timeoutTextOk(text: string): boolean {
+  if (!/^\d+$/.test(text.trim())) return false
+  return Number(text) >= TIMEOUT_MIN_MS
+}
+
+/** 草稿 → 提交形状（调用方保证已通过校验）。 */
+export function toPatch(draft: Draft): Record<string, unknown> {
+  return {
+    scriptPath: draft.scriptPath,
+    envFile: draft.envFile,
+    python: draft.python,
+    priority: parsePriority(draft.priorityText).backends,
+    timeoutMs: Number(draft.timeoutMsText),
+  }
+}

package/src/client/i18n.ts

@@ -0,0 +1,74 @@
+/**
+ * 配置卡片文案（zh/en）。经 ctx.locale.register 注册、bind 取用。
+ * 公共键（save/discard/unsaved 等）来自 shared 的 common 字典，本文件只维护业务键。
+ * @module web-search-services/client/i18n
+ */
+import { commonEn, commonZh, mergeDict } from '@dsh-plus/shared/client'
+
+export const NS = 'dsh-plus-web-search-services'
+
+const ownZh = {
+  title: '搜索后端聚合',
+  description:
+    '把 search-services skill 接成 dsh 的 web_search 后端：按优先级尝试 Tavily / Exa / OpenAI-compatible，失败自动回退。',
+  summaryLine: 'web_search 免费后端聚合：优先级链 + 失败自动回退（密钥读 skill 的 env 文件）。',
+  scriptPath: 'search.py 路径',
+  scriptPathHint: '留空 = 使用随包内置脚本；支持 ~ 展开。',
+  envFile: '密钥 env 文件',
+  envFileHint:
+    '默认 ~/.config/search-services/env（skill 的单事实源）；留空表示不读该文件。支持 ~ 展开。',
+  python: 'python 解释器',
+  pythonHint: '可含参数（如 py -3）；留空 = 自动发现（桌面捆绑运行时 → PATH → 平台兜底名）。',
+  priority: '后端优先级',
+  priorityHint:
+    '每行一个，靠前先试，失败自动回退到下一个。可选值：tavily、exa、openai-chat；重复或未知值会被拒绝保存。',
+  timeoutMs: '单次搜索超时（毫秒）',
+  timeoutMsHint: '应低于 dsh-tool-web 的 searchTimeoutMs；下限 1000，默认 55000。',
+  invalidPriority: '请填写至少一个有效后端，且不要重复',
+  invalidTimeout: '请输入不小于 1000 的整数',
+  keysGroup: '密钥与覆盖项（本卡片不编辑）',
+  keysHint:
+    '密钥主来源是上面的 env 文件，保持 skill 单事实源：TAVILY_API_KEY、EXA_API_KEY、SEARCH_OPENAI_API_KEY，以及可选的 SEARCH_OPENAI_BASE_URL、SEARCH_OPENAI_MODEL。',
+  keysUserLayerHint:
+    'schema 里的 keys 段是行级覆盖逃生舱（role(secret) 字段只允许 profile 行级注入）；写入 settings.yaml 用户层会被脱敏遮蔽，因此配置卡片不提供编辑。需要覆盖时请改 env 文件，或在 profile 的 cordis.patch.yml 行级注入。',
+  reloadHint: '改动热生效（下一次 web_search 调用即用新配置）；scriptPath / python 变化无需重启。',
+} as const
+
+const ownEn = {
+  title: 'Search backend aggregation',
+  description:
+    'Bridges the search-services skill into dsh as a web_search backend: tries Tavily / Exa / OpenAI-compatible in priority order with automatic fallback.',
+  summaryLine:
+    'web_search backend aggregation: priority chain with automatic fallback (keys from the skill env file).',
+  scriptPath: 'search.py path',
+  scriptPathHint: 'Empty uses the bundled copy; ~ is expanded.',
+  envFile: 'Credential env file',
+  envFileHint:
+    'Defaults to ~/.config/search-services/env (the skill’s single source); empty skips the file. ~ is expanded.',
+  python: 'Python interpreter',
+  pythonHint:
+    'May include arguments (e.g. py -3); empty auto-detects (desktop runtime → PATH → platform default).',
+  priority: 'Backend priority',
+  priorityHint:
+    'One per line, earlier first, with automatic fallback on failure. Allowed: tavily, exa, openai-chat; duplicates or unknown values block saving.',
+  timeoutMs: 'Per-search timeout (ms)',
+  timeoutMsHint: 'Keep it below dsh-tool-web’s searchTimeoutMs; minimum 1000, default 55000.',
+  invalidPriority: 'Enter at least one valid backend without duplicates',
+  invalidTimeout: 'Enter an integer of at least 1000',
+  keysGroup: 'Credentials and overrides (not edited here)',
+  keysHint:
+    'Credentials come from the env file above, keeping the skill as the single source: TAVILY_API_KEY, EXA_API_KEY, SEARCH_OPENAI_API_KEY, plus optional SEARCH_OPENAI_BASE_URL and SEARCH_OPENAI_MODEL.',
+  keysUserLayerHint:
+    'The keys section in the schema is a line-level escape hatch (role(secret) fields accept profile-line injection only); values written to the settings.yaml user layer are masked, so this card offers no editor. To override, edit the env file or inject at the profile row in cordis.patch.yml.',
+  reloadHint:
+    'Changes apply hot (the next web_search call uses them); scriptPath / python need no restart.',
+} as const
+
+export type DictKey = keyof typeof commonZh | keyof typeof ownZh
+
+/** 卡片共用的翻译函数类型（slot 注入的 bind 结果按此消费）。 */
+export type Translate = (key: DictKey) => string
+
+// 标注为 Record<DictKey, string>：en 缺任一键即编译期报错（中英强制对齐）。
+export const zh: Record<DictKey, string> = mergeDict(commonZh, ownZh)
+export const en: Record<DictKey, string> = mergeDict(commonEn, ownEn)

package/src/client/styles.ts

@@ -0,0 +1,27 @@
+/**
+ * 配置卡片样式：基础规则走 @dsh-plus/shared/client 的 cardCss('wsv')，
+ * 本文件只补插件特有规则（优先级多行文本域、密钥说明块）。
+ * 沿用官方 data-plugin / data-plugin-css 约定（HMR 据此卸载）。
+ * @module web-search-services/client/styles
+ */
+import { cardCss, injectCardStyle } from '@dsh-plus/shared/client'
+
+export const PLUGIN_ID = '@dsh-plus/web-search-services'
+
+const extraCss = `
+.wsv-priority{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:8px 12px;font-size:13px;line-height:1.6;min-height:72px;resize:vertical;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+.wsv-priority:focus-visible{border-color:var(--dsw-alias-brand-primary);outline:none}
+.wsv-priority:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}
+.wsv-keys{border:1px solid var(--dsw-alias-border-l2);border-radius:8px;margin:12px 0 0;padding:10px 12px}
+.wsv-keysTitle{color:var(--dsw-alias-label-secondary);margin:0;font-size:12px;font-weight:600}
+@media (max-width:767px){
+.wsv-priority{font-size:16px}
+}
+`
+
+export const cardCssAll = cardCss('wsv', extraCss)
+
+/** 幂等注入样式标签；返回标签（已存在或环境无 document 时为 null）。 */
+export function injectStyle(): HTMLStyleElement | null {
+  return injectCardStyle(PLUGIN_ID, cardCssAll)
+}