@dsh-plus/web-search-services 0.1.20 → 0.2.0

package/lib/index.js

@@ -1,659 +1,24 @@
 import { unwrapVolatile } from "@dsh-plus/shared";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
-import { WebError } from "@deepseek-ai/dsh-web";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { spawn } from "node:child_process";
+import { DEFAULT_SEARCH_ENTRIES, SEARCH_ENTRY_PROVIDER_PREFIX as ENTRY_PROVIDER_PREFIX, SEARCH_PROVIDER_ID as PROVIDER_ID, SearchEntrySchema, createBackendHost, probeCredentialsFace, searchEntryAvailable, searchProvidersOf } from "@dsh-plus/web-providers-core";
 import z from "@deepseek-ai/schemastery";
-/** 由 web 请求 + 插件配置生成 search.py 的 argv（不含解释器与脚本路径）。 */
-function buildSearchArgv(cfg, request) {
-	const query = request.query.trim();
-	if (query === "") throw new Error("query must be a non-empty string");
-	const maxResults = request.maxResults ?? 8;
-	return [
-		"search",
-		"--query",
-		query,
-		"--service",
-		cfg.priority.join(","),
-		"--max-results",
-		String(maxResults)
-	];
-}
-//#endregion
-//#region src/env-file.ts
-/**
-* search-services skill env 文件解析（纯函数）。
-* 只解析不执行：按行提取 KEY=VALUE，不展开 $ 变量、不运行 shell，畸形行跳过；
-* 文件缺失/不可读返回空表（envFile 是优化来源，不是硬依赖）。
-* @module web-search-services/env-file
-*/
-/** 展开路径开头的 ~（支持 `~`、`~/`、`~\` 三种形态，与官方 dsh-home-paths 对齐，不借 shell）。 */
-function expandHome(path) {
-	if (path === "~") return homedir();
-	if (path.startsWith("~/") || path.startsWith("~\\")) return join(homedir(), path.slice(2));
-	return path;
-}
-function unquote(value) {
-	const first = value.charAt(0);
-	const last = value.charAt(value.length - 1);
-	if (value.length >= 2 && first === last && (first === "\"" || first === "'")) return value.slice(1, -1);
-	return value;
-}
-function parseEnvText(text) {
-	const out = {};
-	for (const rawLine of text.split(/\r?\n/)) {
-		const line = rawLine.trim();
-		if (line === "" || line.startsWith("#")) continue;
-		const body = line.startsWith("export ") ? line.slice(7).trim() : line;
-		const eq = body.indexOf("=");
-		if (eq <= 0) continue;
-		const key = body.slice(0, eq).trim();
-		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
-		out[key] = unquote(body.slice(eq + 1).trim());
-	}
-	return out;
-}
-function loadEnvFile(path) {
-	if (path.trim() === "") return {};
-	try {
-		return parseEnvText(readFileSync(expandHome(path), "utf8"));
-	} catch {
-		return {};
-	}
-}
-//#endregion
-//#region src/normalize.ts
-function asObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
-}
-function asNonEmptyString(value) {
-	return typeof value === "string" && value.trim() !== "" ? value : void 0;
-}
-function asArray(value) {
-	return Array.isArray(value) ? value : [];
-}
-/** snippet 截断上限：官方 deepseek provider 的摘录是短引文；Tavily content /
-*  Exa highlights 原始值可达整页文本，直接透传会撑爆工具结果上下文。 */
-const SNIPPET_MAX_CHARS = 500;
-function truncateSnippet(text) {
-	return text.length <= SNIPPET_MAX_CHARS ? text : `${text.slice(0, SNIPPET_MAX_CHARS)}…`;
-}
-function makeSource(url, title, snippet, publishedAt) {
-	return {
-		url,
-		...title !== void 0 ? { title } : {},
-		...snippet !== void 0 ? { snippet } : {},
-		...publishedAt !== void 0 ? { publishedAt } : {}
-	};
-}
-/** skill 各服务 request() 统一信封 {ok, service, status, data: <API 响应>}；
-* 取 data 为业务 payload，data 缺失/空对象时回退顶层（旧形状容差）。 */
-function payloadOf(raw) {
-	const data = asObject(raw.data);
-	return Object.keys(data).length > 0 ? data : raw;
-}
-function finish(content, sources) {
-	const seen = /* @__PURE__ */ new Set();
-	const deduped = sources.filter((source) => {
-		if (seen.has(source.url)) return false;
-		seen.add(source.url);
-		return true;
-	});
-	return {
-		...content !== void 0 ? { content } : {},
-		sources: deduped,
-		truncated: false
-	};
-}
-function sourcesFromResults(results, pick) {
-	const out = [];
-	for (const entry of asArray(results)) {
-		const source = pick(asObject(entry));
-		if (source !== void 0) out.push(source);
-	}
-	return out;
-}
-function normalizeTavily(raw) {
-	const payload = payloadOf(raw);
-	const sources = sourcesFromResults(payload.results, (item) => {
-		const url = asNonEmptyString(item.url);
-		const content = asNonEmptyString(item.content);
-		if (url === void 0) return void 0;
-		return makeSource(url, asNonEmptyString(item.title), content !== void 0 ? truncateSnippet(content) : void 0, asNonEmptyString(item.published_date));
-	});
-	return finish(asNonEmptyString(payload.answer), sources);
-}
-function normalizeExa(raw) {
-	return finish(void 0, sourcesFromResults(payloadOf(raw).results, (item) => {
-		const url = asNonEmptyString(item.url) ?? asNonEmptyString(item.id);
-		if (url === void 0) return void 0;
-		const highlights = asArray(item.highlights).map((h) => asNonEmptyString(h)).filter((h) => h !== void 0);
-		return makeSource(url, asNonEmptyString(item.title), highlights.length > 0 ? truncateSnippet(highlights.join(" ")) : void 0, asNonEmptyString(item.publishedDate));
-	}));
-}
-const MARKDOWN_LINK = /\[([^\]]*)\]\((https?:\/\/[^)\s]+)\)/g;
-/** 从生成式回答的 markdown 链接提取可引用来源（DeepSeek 官方 provider 同样只给
-*  URL/标题）。无链接时返回空表——content-only 结果在 WebSearchResult 合法。 */
-function extractMarkdownLinks(markdown, limit) {
-	const seen = /* @__PURE__ */ new Set();
-	const out = [];
-	for (const match of markdown.matchAll(MARKDOWN_LINK)) {
-		const url = match[2];
-		if (url === void 0 || seen.has(url)) continue;
-		seen.add(url);
-		const label = match[1] ?? "";
-		out.push(makeSource(url, label.trim() !== "" ? label : void 0));
-		if (out.length >= limit) break;
-	}
-	return out;
-}
-function normalizeOpenAiChat(raw) {
-	const answer = asNonEmptyString(asObject(raw.data).answer);
-	if (answer === void 0) throw new Error("openai-chat 结果缺少 data.answer");
-	return finish(answer, extractMarkdownLinks(answer, 16));
-}
-function formatAttempts(attempts) {
-	const summary = asArray(attempts).map((entry) => {
-		const item = asObject(entry);
-		return `${asNonEmptyString(item.service) ?? "?"}: ${asNonEmptyString(item.error) ?? "unknown"}`;
-	}).join("; ");
-	return summary === "" ? "" : `（尝试过: ${summary}）`;
-}
-/** 归一化 search.py 的完整 stdout JSON；失败以 Error 抛出（provider 层包 WebError）。 */
-function normalizeSearchOutput(raw) {
-	const obj = asObject(raw);
-	if (obj.ok === false) {
-		const detail = asNonEmptyString(obj.error) ?? "search.py 返回 ok=false";
-		throw new Error(`${detail}${formatAttempts(obj.attempts)}`);
-	}
-	const service = asNonEmptyString(obj.selectedService) ?? asNonEmptyString(obj.service);
-	switch (service) {
-		case "tavily": return normalizeTavily(obj);
-		case "exa": return normalizeExa(obj);
-		case "openai-chat": return normalizeOpenAiChat(obj);
-		default: throw new Error(`search.py 返回未知或不支持的 selectedService: ${JSON.stringify(service)}`);
-	}
-}
-//#endregion
-//#region src/python.ts
-/**
-* Python 解释器发现：Windows 与桌面端常无 `python3` 命令（桌面端自带的捆绑
-* 运行时落在 `$DSH_HOME/dsh-runtimes/dsh-primary-runtime`），按候选链解析——
-* 显式配置（可含参数，如 `py -3`）→ 捆绑运行时（浅层 BFS 找解释器）→
-* PATH 扫描 → 平台兜底名（未验证，交 spawn 时再判）。
-*
-* 全部为同步纯逻辑 + 注入文件系统视图，零 spawn：`available()` 是廉价本地检查，
-* 具体候选 spawn ENOENT 时由调用方逐个换下一个（见 provider.run）。
-* @module web-search-services/python
-*/
-const POSIX_SPEC = {
-	pathNames: [{
-		name: "python3",
-		argsPrefix: []
-	}, {
-		name: "python",
-		argsPrefix: []
-	}],
-	fallbacks: [{
-		name: "python3",
-		argsPrefix: []
-	}, {
-		name: "python",
-		argsPrefix: []
-	}],
-	bundledNames: /* @__PURE__ */ new Set(["python3", "python"])
-};
-const WIN32_SPEC = {
-	pathNames: [
-		{
-			name: "python.exe",
-			argsPrefix: []
-		},
-		{
-			name: "python3.exe",
-			argsPrefix: []
-		},
-		{
-			name: "py.exe",
-			argsPrefix: ["-3"]
-		}
-	],
-	fallbacks: [
-		{
-			name: "python",
-			argsPrefix: []
-		},
-		{
-			name: "py",
-			argsPrefix: ["-3"]
-		},
-		{
-			name: "python3",
-			argsPrefix: []
-		}
-	],
-	bundledNames: /* @__PURE__ */ new Set([
-		"python.exe",
-		"python3.exe",
-		"python3",
-		"python"
-	])
-};
-/** 捆绑运行时 BFS 的边界：层数与访问目录数双上限，防畸形布局拖慢 available()。 */
-const BUNDLED_MAX_DEPTH = 3;
-const BUNDLED_MAX_VISITS = 512;
-/** 与解释器无关的大目录（Windows CPython 的 Lib/site-packages 等），跳过。 */
-const NOISE_DIRS = /* @__PURE__ */ new Set([
-	"Lib",
-	"lib",
-	"lib64",
-	"include",
-	"share",
-	"site-packages",
-	"test",
-	"tests",
-	"doc",
-	"docs"
-]);
-function specOf(platform) {
-	return platform === "win32" ? WIN32_SPEC : POSIX_SPEC;
-}
-/** 显式配置 → 单候选（按空白拆分，支持 `py -3` 形态）。 */
-function configCandidate(configPython) {
-	const [command, ...argsPrefix] = configPython.trim().split(/\s+/).filter((part) => part.length > 0);
-	if (command === void 0) return void 0;
-	return {
-		command,
-		argsPrefix,
-		source: "config"
-	};
-}
-/** 在捆绑运行时根下浅层 BFS 找解释器文件（先按层扫文件名，再入队子目录）。 */
-function findBundled(root, env) {
-	if (!env.fs.exists(root)) return void 0;
-	const spec = specOf(env.platform);
-	const queue = [{
-		dir: root,
-		depth: 0
-	}];
-	let visits = 0;
-	while (queue.length > 0 && visits < BUNDLED_MAX_VISITS) {
-		const item = queue.shift();
-		if (item === void 0) break;
-		visits += 1;
-		for (const entry of env.fs.list(item.dir)) {
-			if (!entry.dir && spec.bundledNames.has(entry.name)) return join(item.dir, entry.name);
-			if (entry.dir && item.depth < BUNDLED_MAX_DEPTH && !entry.name.startsWith(".") && !NOISE_DIRS.has(entry.name) && !spec.bundledNames.has(entry.name)) queue.push({
-				dir: join(item.dir, entry.name),
-				depth: item.depth + 1
-			});
-		}
-	}
-}
-/** PATH 逐目录扫描（名字在外层：win32 任一处的 python.exe 优先于 python3.exe）。 */
-function scanPath(env, spec) {
-	const listSep = env.platform === "win32" ? ";" : ":";
-	const dirs = (env.pathValue ?? "").split(listSep).filter((dir) => dir.length > 0);
-	const out = [];
-	const seen = /* @__PURE__ */ new Set();
-	for (const { name, argsPrefix } of spec.pathNames) for (const dir of dirs) {
-		const full = join(dir, name);
-		if (seen.has(full)) continue;
-		seen.add(full);
-		if (env.fs.exists(full)) out.push({
-			command: full,
-			argsPrefix,
-			source: "path"
-		});
-	}
-	return out;
-}
-/**
-* 解析解释器候选链（有序）：显式配置独占；否则 捆绑运行时 → PATH 命中 → 平台兜底名。
-* 兜底名永远追加在末尾（供 spawn ENOENT 时逐个回退），但 `source: 'fallback'`
-* 不算「已验证」——`available()` 只信任 config/bundled/path。
-*/
-function pythonCandidates(env, configPython) {
-	const explicit = configCandidate(configPython);
-	if (explicit !== void 0) return [explicit];
-	const spec = specOf(env.platform);
-	const out = [];
-	if (env.bundledRoot !== void 0) {
-		const bundled = findBundled(env.bundledRoot, env);
-		if (bundled !== void 0) out.push({
-			command: bundled,
-			argsPrefix: [],
-			source: "bundled"
-		});
-	}
-	out.push(...scanPath(env, spec));
-	for (const { name, argsPrefix } of spec.fallbacks) if (!out.some((candidate) => candidate.command === name)) out.push({
-		command: name,
-		argsPrefix,
-		source: "fallback"
-	});
-	return out;
-}
-/** 生产文件系统视图（真实 fs；list 对不可读目录返回空表）。 */
-function realPythonFs() {
-	return {
-		exists: (path) => existsSync(path),
-		list: (path) => {
-			try {
-				return readdirSync(path, { withFileTypes: true }).map((entry) => ({
-					name: entry.name,
-					dir: entry.isDirectory()
-				}));
-			} catch {
-				return [];
-			}
-		}
-	};
-}
-//#endregion
-//#region src/runner.ts
-/**
-* 子进程执行器：spawn 脚本、收集 stdout、超时/abort 杀进程。
-* spawn 依赖注入以便单测 mock（禁网络铁律下测试绝不真实启动搜索脚本）。
-* @module web-search-services/runner
-*/
-const DEFAULT_MAX_BUFFER = 8388608;
-const KILL_GRACE_MS = 2e3;
-/**
-* Windows 进程树终止：`taskkill /PID <pid> /T /F`（Windows 无 POSIX 信号语义，
-* 单纯 `child.kill()` 会遗留 npx/playwright 派生的子进程树；上游
-* dsh-subprocess-local 同款做法）。error 监听防 taskkill 缺席成为未捕获异常。
-*/
-const killWindowsTree = (pid) => {
-	const killer = spawn("taskkill", [
-		"/PID",
-		String(pid),
-		"/T",
-		"/F"
-	], { stdio: "ignore" });
-	killer.on("error", (error) => {
-		console.warn(`[web-search-services] taskkill 失败（pid ${pid}）: ${error.message}`);
-	});
-	killer.unref();
-};
-function abortError() {
-	const err = /* @__PURE__ */ new Error("search aborted");
-	err.name = "AbortError";
-	return err;
-}
-function isAbortError(err) {
-	return err instanceof Error && err.name === "AbortError";
-}
-function tail(text, max = 500) {
-	const trimmed = text.trim();
-	return trimmed.length <= max ? trimmed : `…${trimmed.slice(-max)}`;
-}
-/** 运行子进程并返回完整 stdout；任何失败以 Error 拒绝（消息含 stderr/退出码上下文）。 */
-function runProcess(opts) {
-	const spawnFn = opts.spawnFn ?? spawn;
-	const platform = opts.platform ?? process.platform;
-	const killTree = opts.killTree ?? killWindowsTree;
-	return new Promise((resolve, reject) => {
-		if (opts.signal?.aborted === true) {
-			reject(abortError());
-			return;
-		}
-		const child = spawnFn(opts.command, [...opts.args], {
-			env: opts.env,
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			],
-			...opts.cwd !== void 0 ? { cwd: opts.cwd } : {}
-		});
-		const maxBuffer = opts.maxBufferBytes ?? DEFAULT_MAX_BUFFER;
-		let stdout = "";
-		let stderr = "";
-		let settled = false;
-		let graceTimer;
-		const cleanup = () => {
-			clearTimeout(timer);
-			if (graceTimer !== void 0) clearTimeout(graceTimer);
-			opts.signal?.removeEventListener("abort", onAbort);
-		};
-		const settle = (fn) => {
-			if (settled) return;
-			settled = true;
-			cleanup();
-			fn();
-		};
-		const kill = () => {
-			if (platform === "win32") {
-				if (child.pid !== void 0) killTree(child.pid);
-				else child.kill();
-				return;
-			}
-			child.kill("SIGTERM");
-			graceTimer = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS);
-			graceTimer.unref();
-		};
-		const onAbort = () => {
-			kill();
-			settle(() => reject(abortError()));
-		};
-		const timer = setTimeout(() => {
-			kill();
-			settle(() => reject(/* @__PURE__ */ new Error(`process timed out after ${opts.timeoutMs}ms`)));
-		}, opts.timeoutMs);
-		timer.unref();
-		opts.signal?.addEventListener("abort", onAbort, { once: true });
-		child.stdout?.on("data", (chunk) => {
-			stdout += chunk.toString();
-			if (stdout.length > maxBuffer) {
-				kill();
-				settle(() => reject(/* @__PURE__ */ new Error(`stdout exceeded ${maxBuffer} bytes`)));
-			}
-		});
-		child.stderr?.on("data", (chunk) => {
-			stderr += chunk.toString();
-		});
-		child.on("error", (err) => {
-			settle(() => reject(new Error(`failed to start ${opts.command}: ${err.message}`, { cause: err })));
-		});
-		child.on("close", (code) => {
-			if (settled) return;
-			if (code === 0) {
-				settle(() => resolve(stdout));
-				return;
-			}
-			const detail = tail(stderr) !== "" ? tail(stderr) : tail(stdout);
-			settle(() => reject(/* @__PURE__ */ new Error(`exited with code ${code ?? "null"}: ${detail}`)));
-		});
-	});
-}
-//#endregion
-//#region src/provider.ts
-/**
-* dsh-web 搜索 provider：把 ctx.web.search 桥接到 search-services skill 的
-* search.py（Tavily / Exa / OpenAI Chat 免费额度后端）。官方 web_search 工具、
-* 渲染与提示词零修改——本 provider 只产出标准 WebSearchResult，格式化天然一致。
-* @module web-search-services/provider
-*/
-const PROVIDER_ID = "search-services";
-/**
-* scriptPath 解析：空串 = 随包内置脚本副本（tgz 内 scripts/search.py，与 lib/
-* 同级；src 直跑时为包根 scripts/）。非空按 ~ 展开。
-*/
-function resolveScriptPath(scriptPath) {
-	if (scriptPath.trim() !== "") return expandHome(scriptPath);
-	return fileURLToPath(new URL("../scripts/search.py", import.meta.url));
-}
-/** 各后端在合并环境（进程 env ⊕ envFile ⊕ 行级 keys）中的可用性判定变量。 */
-const BACKEND_KEY_VARS = {
-	tavily: ["TAVILY_API_KEY", "TAVILY_API_KEYS"],
-	exa: ["EXA_API_KEY"],
-	"openai-chat": ["SEARCH_OPENAI_API_KEY"]
-};
-/** 行级 keys 覆盖 → 子进程环境变量；空串不注入（保持 envFile 单事实源优先）。 */
-function keyOverridesEnv(keys) {
-	const out = {};
-	if (keys.tavily !== "") out.TAVILY_API_KEY = keys.tavily;
-	if (keys.exa !== "") out.EXA_API_KEY = keys.exa;
-	if (keys.openaiApiKey !== "") out.SEARCH_OPENAI_API_KEY = keys.openaiApiKey;
-	if (keys.openaiBaseUrl !== "") out.SEARCH_OPENAI_BASE_URL = keys.openaiBaseUrl;
-	if (keys.openaiModel !== "") out.SEARCH_OPENAI_MODEL = keys.openaiModel;
-	return out;
-}
-function messageOf(err) {
-	return err instanceof Error ? err.message : String(err);
-}
-/**
-* 判定「解释器缺失」类失败（spawn ENOENT，runProcess 包装时保留 cause）：
-* 候选链据此换下一个解释器；其余错误照常上抛。
-*/
-function isMissingInterpreter(err) {
-	if (!(err instanceof Error)) return false;
-	return err.cause?.code === "ENOENT";
-}
-function toWebError(err) {
-	if (err instanceof WebError) return err;
-	if (isAbortError(err)) return new WebError("搜索已取消", "WEB_ABORTED", { cause: err });
-	return new WebError(`search-services 搜索失败: ${messageOf(err)}`, "WEB_PROVIDER_ERROR", { cause: err });
-}
-var SearchServicesProvider = class {
-	id = PROVIDER_ID;
-	current;
-	spawnFn;
-	discovery;
-	/** 候选链按 `${python}|${bundledRoot}` 记忆：PATH 与捆绑布局在进程内静态。 */
-	candidateCache = /* @__PURE__ */ new Map();
-	constructor(current, spawnFn, discovery) {
-		this.current = current;
-		this.spawnFn = spawnFn;
-		this.discovery = discovery ?? (() => ({
-			platform: process.platform,
-			pathValue: process.env.PATH ?? process.env.Path,
-			bundledRoot: dshHomePath("dsh-runtimes", "dsh-primary-runtime"),
-			fs: realPythonFs()
-		}));
-	}
-	/** 解释器候选链（有序、记忆化）。 */
-	candidates() {
-		const cfg = this.current();
-		const env = this.discovery();
-		const key = `${cfg.python}|${env.bundledRoot ?? ""}`;
-		const cached = this.candidateCache.get(key);
-		if (cached !== void 0) return cached;
-		const resolved = pythonCandidates(env, cfg.python);
-		this.candidateCache.set(key, resolved);
-		return resolved;
-	}
-	/**
-	* 廉价本地检查：脚本存在 + 至少一个【已验证】解释器候选（配置/捆绑/PATH，
-	* 未验证兜底名不算）+ 优先级内至少一个后端有 key；不做网络调用、不 spawn。
-	*/
-	available() {
-		const cfg = this.current();
-		if (!existsSync(resolveScriptPath(cfg.scriptPath))) return false;
-		if (!this.candidates().some((candidate) => candidate.source !== "fallback")) return false;
-		const env = this.childEnv(cfg);
-		return cfg.priority.some((backend) => BACKEND_KEY_VARS[backend].some((name) => (env[name]?.trim() ?? "") !== ""));
-	}
-	async search(request, signal) {
-		const cfg = this.current();
-		const argv = buildSearchArgv(cfg, request);
-		const stdout = await this.run(cfg, argv, signal);
-		return this.normalize(stdout);
-	}
-	childEnv(cfg) {
-		const fromFile = cfg.envFile.trim() === "" ? {} : loadEnvFile(cfg.envFile);
-		return {
-			...process.env,
-			...fromFile,
-			...keyOverridesEnv(cfg.keys)
-		};
-	}
-	async run(cfg, argv, signal) {
-		const script = resolveScriptPath(cfg.scriptPath);
-		const env = this.childEnv(cfg);
-		let lastMissing;
-		for (const candidate of this.candidates()) try {
-			return await runProcess({
-				command: candidate.command,
-				args: [
-					...candidate.argsPrefix,
-					script,
-					...argv
-				],
-				env,
-				timeoutMs: cfg.timeoutMs,
-				...signal !== void 0 ? { signal } : {},
-				...this.spawnFn !== void 0 ? { spawnFn: this.spawnFn } : {}
-			});
-		} catch (err) {
-			if (!isMissingInterpreter(err)) throw toWebError(err);
-			lastMissing = err;
-		}
-		throw toWebError(lastMissing ?? /* @__PURE__ */ new Error("未找到可用的 python 解释器（配置 python 或安装 python3）"));
-	}
-	normalize(stdout) {
-		let raw;
-		try {
-			raw = JSON.parse(stdout);
-		} catch (err) {
-			const preview = stdout.trim().slice(-200);
-			throw new WebError(`search.py 输出非 JSON: …${preview}`, "WEB_PROVIDER_ERROR", { cause: err });
-		}
-		try {
-			return normalizeSearchOutput(raw);
-		} catch (err) {
-			throw new WebError(`search.py 结果归一化失败: ${messageOf(err)}`, "WEB_PROVIDER_ERROR", { cause: err });
-		}
-	}
-};
 //#endregion
 //#region src/config.ts
 /**
-* 配置单一事实源：cordis 行级 Config（组合默认值，patch 层可覆盖）与 settings
-* namespace（用户层＝profile 行级覆盖层 cordis.patch.yml，热生效）共用同一 schemastery schema。
+* 配置单一事实源：cordis 行级 Config（组合默认值，profile patch 层可覆盖）与 settings
+* namespace（用户层＝profile 行级覆盖层 cordis.patch.yml，热生效）共用同一份
+* schemastery schema。
 *
-* 密钥主来源是 search-services skill 的 env 文件（envFile，默认
-* ~/.config/search-services/env），保持 skill 单事实源、零搬迁。行级 keys 仅为
-* 覆盖逃生舱；按存储规范 role('secret') 字段只允许行级注入，settings 用户层勿填。
+* 条目 schema 来自 `@dsh-plus/web-providers-core`（与后端实现同源，改后端不动插件）；
+* 密钥全部走官方 credentials seam（`$DSH_HOME/.credentials.yaml`），**不进 settings**
+* ——卡片只展示引用名，值经 `remote.credentials` 写入。
 * @module web-search-services/config
 */
 const SETTINGS_NS = "dsh-plus-web-search-services";
-const DEFAULT_ENV_FILE = "~/.config/search-services/env";
-const DEFAULT_TIMEOUT_MS = 55e3;
-const DEFAULT_PRIORITY = [
-	"tavily",
-	"exa",
-	"openai-chat"
-];
-const PRIORITY_ENTRY = z.union([
-	"tavily",
-	"exa",
-	"openai-chat"
-]);
-const KeysSchema = z.object({
-	tavily: z.string().role("secret").description("Tavily API key（覆盖 envFile 的 TAVILY_API_KEY；行级注入专用）").default(""),
-	exa: z.string().role("secret").description("Exa API key（覆盖 envFile 的 EXA_API_KEY；行级注入专用）").default(""),
-	openaiApiKey: z.string().role("secret").description("OpenAI-compatible API key（覆盖 SEARCH_OPENAI_API_KEY；行级注入专用）").default(""),
-	openaiBaseUrl: z.string().description("OpenAI-compatible base URL（覆盖 SEARCH_OPENAI_BASE_URL）").default(""),
-	openaiModel: z.string().description("OpenAI-compatible 搜索模型名（覆盖 SEARCH_OPENAI_MODEL）").default("")
-});
 const Config = z.object({
-	scriptPath: z.string().description("search.py 路径（支持 ~ 展开）；空串 = 使用随包内置脚本副本").default("").volatile(),
-	envFile: z.string().description("skill 密钥 env 文件路径（支持 ~ 展开）；空串表示不读 envFile").default(DEFAULT_ENV_FILE).volatile(),
-	python: z.string().description("python 解释器（可含参数，如 `py -3`）；空串 = 自动发现（配置外按 桌面捆绑运行时 → PATH → 平台兜底名 解析）").default("").volatile(),
-	priority: z.array(PRIORITY_ENTRY).description("后端优先级：靠前的先尝试，失败自动回退到下一个").default([...DEFAULT_PRIORITY]).volatile(),
-	timeoutMs: z.natural().min(1e3).description("单次搜索子进程超时（毫秒），应低于 dsh-tool-web 的 searchTimeoutMs").default(DEFAULT_TIMEOUT_MS).volatile(),
-	keys: KeysSchema.default({
-		tavily: "",
-		exa: "",
-		openaiApiKey: "",
-		openaiBaseUrl: "",
-		openaiModel: ""
-	}).volatile()
+	enabled: z.boolean().description("总开关：关闭后 web_search 不再选用本 provider（官方工具与提示词不变）").default(true).volatile(),
+	exposeEntries: z.boolean().description("是否额外注册每条目 provider（dsh-plus-search-<条目名>），便于按 id 钉住单个后端").default(false).volatile(),
+	proxy: z.string().description("全部后端共用的 HTTP(S) 代理；空 = 读环境变量 HTTP_PROXY/HTTPS_PROXY/NO_PROXY").default("").volatile(),
+	entries: z.array(SearchEntrySchema).description("后端链：按顺序尝试，失败自动回退到下一个（条目内 schema 见卡片）").default(DEFAULT_SEARCH_ENTRIES).volatile()
 });
 //#endregion
 //#region src/index.ts
@@ -661,8 +26,10 @@ const name = "dsh-plus-web-search-services";
 /** 行级 inject：dsh-web 服务激活后才应用本行（provider 注册即需 ctx.web）。 */
 const inject = ["web"];
 function apply(ctx, config) {
-	const provider = new SearchServicesProvider(() => unwrapVolatile(config));
-	ctx.effect(() => ctx.web.registerSearchProvider(provider), "dsh-plus-web-search-services: register search provider");
+	const current = () => unwrapVolatile(config);
+	const host = createBackendHost({ credentials: probeCredentialsFace(ctx) });
+	ctx.effect(() => () => host.dispose(), "dsh-plus-web-search-services: transport pool");
+	for (const provider of searchProvidersOf(current, host)) ctx.effect(() => ctx.web.registerSearchProvider(provider), `dsh-plus-web-search-services: register ${provider.id}`);
 }
 //#endregion
-export { Config, PROVIDER_ID, SETTINGS_NS, SearchServicesProvider, apply, inject, name };
+export { Config, ENTRY_PROVIDER_PREFIX, PROVIDER_ID, SETTINGS_NS, apply, inject, name, searchEntryAvailable };