@dsh-plus/web-search-services 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agguy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/index.d.ts

@@ -0,0 +1,72 @@
+import z from "@deepseek-ai/schemastery";
+import { WebSearchProvider, WebSearchRequest, WebSearchResult } from "@deepseek-ai/dsh-web";
+import { spawn } from "node:child_process";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/config.d.ts
+declare const SETTINGS_NS = "dsh-plus-web-search-services";
+declare const Config: z<Schemastery.ObjectS<{
+  scriptPath: z<string, string>;
+  envFile: z<string, string>;
+  python: z<string, string>;
+  priority: z<("exa" | "openai-chat" | "tavily")[], ("exa" | "openai-chat" | "tavily")[]>;
+  timeoutMs: z<number, number>;
+  keys: z<Schemastery.ObjectS<{
+    tavily: z<string, string>;
+    exa: z<string, string>;
+    openaiApiKey: z<string, string>;
+    openaiBaseUrl: z<string, string>;
+    openaiModel: z<string, string>;
+  }>, Schemastery.ObjectT<{
+    tavily: z<string, string>;
+    exa: z<string, string>;
+    openaiApiKey: z<string, string>;
+    openaiBaseUrl: z<string, string>;
+    openaiModel: z<string, string>;
+  }>>;
+}>, Schemastery.ObjectT<{
+  scriptPath: z<string, string>;
+  envFile: z<string, string>;
+  python: z<string, string>;
+  priority: z<("exa" | "openai-chat" | "tavily")[], ("exa" | "openai-chat" | "tavily")[]>;
+  timeoutMs: z<number, number>;
+  keys: z<Schemastery.ObjectS<{
+    tavily: z<string, string>;
+    exa: z<string, string>;
+    openaiApiKey: z<string, string>;
+    openaiBaseUrl: z<string, string>;
+    openaiModel: z<string, string>;
+  }>, Schemastery.ObjectT<{
+    tavily: z<string, string>;
+    exa: z<string, string>;
+    openaiApiKey: z<string, string>;
+    openaiBaseUrl: z<string, string>;
+    openaiModel: z<string, string>;
+  }>>;
+}>>;
+type WebSearchServicesConfig = Schemastery.TypeT<typeof Config>;
+//#endregion
+//#region src/runner.d.ts
+type SpawnFn = typeof spawn;
+//#endregion
+//#region src/provider.d.ts
+declare const PROVIDER_ID = "search-services";
+declare class SearchServicesProvider implements WebSearchProvider {
+  readonly id = "search-services";
+  private readonly current;
+  private readonly spawnFn;
+  constructor(current: () => WebSearchServicesConfig, spawnFn?: SpawnFn | undefined);
+  /** 廉价本地检查：脚本存在 + 优先级内至少一个后端有 key；不做网络调用。 */
+  available(): boolean;
+  search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+  private childEnv;
+  private run;
+  private normalize;
+}
+//#endregion
+//#region src/index.d.ts
+declare const name = "dsh-plus-web-search-services";
+/** 行级 inject：dsh-web 服务激活后才应用本行（provider 注册即需 ctx.web）。 */
+declare const inject: readonly ['web'];
+declare function apply(ctx: Context, config: WebSearchServicesConfig): void;
+//#endregion
+export { Config, PROVIDER_ID, SETTINGS_NS, SearchServicesProvider, apply, inject, name };

package/lib/index.js

@@ -0,0 +1,419 @@
+import z from "@deepseek-ai/schemastery";
+import { existsSync, readFileSync } from "node:fs";
+import { WebError } from "@deepseek-ai/dsh-web";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+//#endregion
+//#region src/config.ts
+/**
+* 配置单一事实源：cordis 行级 Config（组合默认值，patch 层可覆盖）与 settings
+* namespace（用户层 $DSH_HOME/settings.yaml，热生效）共用同一 schemastery schema。
+*
+* 密钥主来源是 search-services skill 的 env 文件（envFile，默认
+* ~/.config/search-services/env），保持 skill 单事实源、零搬迁。行级 keys 仅为
+* 覆盖逃生舱；按存储规范 role('secret') 字段只允许行级注入，settings 用户层勿填。
+* @module web-search-services/config
+*/
+const SETTINGS_NS = "dsh-plus-web-search-services";
+const DEFAULT_SCRIPT_PATH = "~/.dsh/skills/search-services/scripts/search.py";
+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-services skill 的 search.py 路径（支持 ~ 展开）").default(DEFAULT_SCRIPT_PATH),
+	envFile: z.string().description("skill 密钥 env 文件路径（支持 ~ 展开）；空串表示不读 envFile").default(DEFAULT_ENV_FILE),
+	python: z.string().description("python 可执行文件").default("python3"),
+	priority: z.array(PRIORITY_ENTRY).description("后端优先级：靠前的先尝试，失败自动回退到下一个").default([...DEFAULT_PRIORITY]),
+	timeoutMs: z.natural().min(1e3).description("单次搜索子进程超时（毫秒），应低于 dsh-tool-web 的 searchTimeoutMs").default(DEFAULT_TIMEOUT_MS),
+	keys: KeysSchema.default({
+		tavily: "",
+		exa: "",
+		openaiApiKey: "",
+		openaiBaseUrl: "",
+		openaiModel: ""
+	})
+});
+/** 由 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
+*/
+/** 展开路径开头的 ~（仅 ~ 与 ~/ 两种形态，不借 shell）。 */
+function expandHome(path) {
+	if (path === "~") return homedir();
+	if (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 : [];
+}
+function makeSource(url, title, snippet, publishedAt) {
+	return {
+		url,
+		...title !== void 0 ? { title } : {},
+		...snippet !== void 0 ? { snippet } : {},
+		...publishedAt !== void 0 ? { publishedAt } : {}
+	};
+}
+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 sources = sourcesFromResults(raw.results, (item) => {
+		const url = asNonEmptyString(item.url);
+		if (url === void 0) return void 0;
+		return makeSource(url, asNonEmptyString(item.title), asNonEmptyString(item.content), asNonEmptyString(item.published_date));
+	});
+	return finish(asNonEmptyString(raw.answer), sources);
+}
+function normalizeExa(raw) {
+	return finish(void 0, sourcesFromResults(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 ? 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/runner.ts
+/**
+* 子进程执行器：spawn 脚本、收集 stdout、超时/abort 杀进程。
+* spawn 依赖注入以便单测 mock（禁网络铁律下测试绝不真实启动搜索脚本）。
+* @module web-search-services/runner
+*/
+const DEFAULT_MAX_BUFFER = 8388608;
+const KILL_GRACE_MS = 2e3;
+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;
+	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 = () => {
+			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";
+/** 各后端在合并环境（进程 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);
+}
+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;
+	constructor(current, spawnFn) {
+		this.current = current;
+		this.spawnFn = spawnFn;
+	}
+	/** 廉价本地检查：脚本存在 + 优先级内至少一个后端有 key；不做网络调用。 */
+	available() {
+		const cfg = this.current();
+		if (!existsSync(expandHome(cfg.scriptPath))) 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) {
+		try {
+			return await runProcess({
+				command: cfg.python,
+				args: [expandHome(cfg.scriptPath), ...argv],
+				env: this.childEnv(cfg),
+				timeoutMs: cfg.timeoutMs,
+				...signal !== void 0 ? { signal } : {},
+				...this.spawnFn !== void 0 ? { spawnFn: this.spawnFn } : {}
+			});
+		} catch (err) {
+			throw toWebError(err);
+		}
+	}
+	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/index.ts
+const name = "dsh-plus-web-search-services";
+/** 行级 inject：dsh-web 服务激活后才应用本行（provider 注册即需 ctx.web）。 */
+const inject = ["web"];
+function apply(ctx, config) {
+	const provider = new SearchServicesProvider(configSource(ctx, config));
+	ctx.effect(() => ctx.web.registerSearchProvider(provider), "dsh-plus-web-search-services: register search provider");
+}
+/**
+* 配置源：settings 用户层（$DSH_HOME/settings.yaml，热生效）在时优先生效，
+* 缺席/detach 回落 cordis 行级 config（官方 installSection 可选消费范式）。
+*/
+function configSource(ctx, rowConfig) {
+	let current = () => rowConfig;
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.installSection(ctx, SETTINGS_NS, Config, rowConfig, {
+			setSource: (source) => {
+				current = source;
+			},
+			onChange: () => {}
+		});
+	});
+	return () => current();
+}
+//#endregion
+export { Config, PROVIDER_ID, SETTINGS_NS, SearchServicesProvider, apply, inject, name };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dsh-plus/web-search-services",
+  "version": "0.1.0",
+  "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",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-web": "^0.1.6-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-settings": "0.1.6-alpha.2",
+    "@deepseek-ai/dsh-web": "0.1.6-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts -d lib --format esm --dts --no-fixed-extension"
+  }
+}

package/src/args.ts

@@ -0,0 +1,30 @@
+/**
+ * search.py 子命令参数组装（纯函数）。
+ * 优先级直接透传 --service：search.py 自带链内 fallback 与 Tavily 多 key 轮转，
+ * 插件不重复实现回退编排。
+ * @module web-search-services/args
+ */
+import type { WebSearchRequest } from '@deepseek-ai/dsh-web'
+
+import type { WebSearchServicesConfig } from './config.ts'
+
+/** dsh-tool-web 之外的调用方未给 maxResults 时的请求层缺省。 */
+export const FALLBACK_MAX_RESULTS = 8
+
+/** 由 web 请求 + 插件配置生成 search.py 的 argv（不含解释器与脚本路径）。 */
+export function buildSearchArgv(cfg: WebSearchServicesConfig, request: WebSearchRequest): string[] {
+  const query = request.query.trim()
+  if (query === '') {
+    throw new Error('query must be a non-empty string')
+  }
+  const maxResults = request.maxResults ?? FALLBACK_MAX_RESULTS
+  return [
+    'search',
+    '--query',
+    query,
+    '--service',
+    cfg.priority.join(','),
+    '--max-results',
+    String(maxResults),
+  ]
+}

package/src/config.ts

@@ -0,0 +1,80 @@
+/**
+ * 配置单一事实源：cordis 行级 Config（组合默认值，patch 层可覆盖）与 settings
+ * namespace（用户层 $DSH_HOME/settings.yaml，热生效）共用同一 schemastery schema。
+ *
+ * 密钥主来源是 search-services skill 的 env 文件（envFile，默认
+ * ~/.config/search-services/env），保持 skill 单事实源、零搬迁。行级 keys 仅为
+ * 覆盖逃生舱；按存储规范 role('secret') 字段只允许行级注入，settings 用户层勿填。
+ * @module web-search-services/config
+ */
+import z from '@deepseek-ai/schemastery'
+
+import { SETTINGS_NS as NS_LITERAL } from './ns.ts'
+
+export const SETTINGS_NS = NS_LITERAL
+
+export const DEFAULT_SCRIPT_PATH = '~/.dsh/skills/search-services/scripts/search.py'
+export const DEFAULT_ENV_FILE = '~/.config/search-services/env'
+export const DEFAULT_TIMEOUT_MS = 55_000
+export const DEFAULT_PRIORITY: readonly SearchBackend[] = ['tavily', 'exa', 'openai-chat']
+
+export type SearchBackend = '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(''),
+})
+
+export const Config = z.object({
+  scriptPath: z
+    .string()
+    .description('search-services skill 的 search.py 路径（支持 ~ 展开）')
+    .default(DEFAULT_SCRIPT_PATH),
+  envFile: z
+    .string()
+    .description('skill 密钥 env 文件路径（支持 ~ 展开）；空串表示不读 envFile')
+    .default(DEFAULT_ENV_FILE),
+  python: z.string().description('python 可执行文件').default('python3'),
+  priority: z
+    .array(PRIORITY_ENTRY)
+    .description('后端优先级：靠前的先尝试，失败自动回退到下一个')
+    .default([...DEFAULT_PRIORITY]),
+  timeoutMs: z
+    .natural()
+    .min(1000)
+    .description('单次搜索子进程超时（毫秒），应低于 dsh-tool-web 的 searchTimeoutMs')
+    .default(DEFAULT_TIMEOUT_MS),
+  keys: KeysSchema.default({
+    tavily: '',
+    exa: '',
+    openaiApiKey: '',
+    openaiBaseUrl: '',
+    openaiModel: '',
+  }),
+})
+
+export type WebSearchServicesConfig = Schemastery.TypeT<typeof Config>
+export type KeysConfig = WebSearchServicesConfig['keys']

package/src/env-file.ts

@@ -0,0 +1,49 @@
+/**
+ * search-services skill env 文件解析（纯函数）。
+ * 只解析不执行：按行提取 KEY=VALUE，不展开 $ 变量、不运行 shell，畸形行跳过；
+ * 文件缺失/不可读返回空表（envFile 是优化来源，不是硬依赖）。
+ * @module web-search-services/env-file
+ */
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** 展开路径开头的 ~（仅 ~ 与 ~/ 两种形态，不借 shell）。 */
+export function expandHome(path: string): string {
+  if (path === '~') return homedir()
+  if (path.startsWith('~/')) return join(homedir(), path.slice(2))
+  return path
+}
+
+function unquote(value: string): string {
+  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
+}
+
+export function parseEnvText(text: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (line === '' || line.startsWith('#')) continue
+    const body = line.startsWith('export ') ? line.slice('export '.length).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
+}
+
+export function loadEnvFile(path: string): Record<string, string> {
+  if (path.trim() === '') return {}
+  try {
+    return parseEnvText(readFileSync(expandHome(path), 'utf8'))
+  } catch {
+    return {}
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * dsh-plus 插件：web_search 免费后端聚合（search-services skill 桥接）。
+ *
+ * 经官方 ctx.web provider 扩展点注册 id=search-services 的搜索后端：web_search /
+ * web_fetch 工具、渲染层与提示词零修改，模型可见输出格式与官方 provider 逐字节
+ * 一致。优先级与自动回退由 skill 的 search.py 编排（含 Tavily 多 key 轮转）；
+ * Context7 仅支持带库名的 docs 查询，web_search 契约无 library 概念，不进搜索链。
+ * @module @dsh-plus/web-search-services
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-settings'
+import type {} from '@deepseek-ai/dsh-web'
+
+import { Config, SETTINGS_NS, type WebSearchServicesConfig } from './config.ts'
+import { SearchServicesProvider } from './provider.ts'
+
+export const name = 'dsh-plus-web-search-services'
+
+/** 行级 inject：dsh-web 服务激活后才应用本行（provider 注册即需 ctx.web）。 */
+export const inject = ['web'] as const
+
+export { PROVIDER_ID, SearchServicesProvider } from './provider.ts'
+export { Config, SETTINGS_NS }
+
+export function apply(ctx: Context, config: WebSearchServicesConfig): void {
+  const provider = new SearchServicesProvider(configSource(ctx, config))
+  ctx.effect(
+    () => ctx.web.registerSearchProvider(provider),
+    'dsh-plus-web-search-services: register search provider',
+  )
+}
+
+/**
+ * 配置源：settings 用户层（$DSH_HOME/settings.yaml，热生效）在时优先生效，
+ * 缺席/detach 回落 cordis 行级 config（官方 installSection 可选消费范式）。
+ */
+function configSource(
+  ctx: Context,
+  rowConfig: WebSearchServicesConfig,
+): () => WebSearchServicesConfig {
+  let current: () => WebSearchServicesConfig = () => rowConfig
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.installSection(ctx, SETTINGS_NS, Config, rowConfig, {
+      setSource: (source) => {
+        current = source
+      },
+      onChange: () => {},
+    })
+  })
+  return () => current()
+}

package/src/normalize.ts

@@ -0,0 +1,154 @@
+/**
+ * search.py 输出 → dsh-web 标准 WebSearchResult 归一化（纯函数）。
+ *
+ * skill 各后端 payload 形状不同：tavily/exa 是原生 API 形状（results[]），
+ * openai-chat 是生成式回答（data.answer）。按 selectedService 归一；
+ * 字段缺失降级而非报错（对 skill 脚本版本漂移保持容差）。
+ * @module web-search-services/normalize
+ */
+import type { WebSearchResult, WebSearchSource } from '@deepseek-ai/dsh-web'
+
+type JsonObject = Record<string, unknown>
+
+function asObject(value: unknown): JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as JsonObject)
+    : {}
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() !== '' ? value : undefined
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+function makeSource(
+  url: string,
+  title?: string,
+  snippet?: string,
+  publishedAt?: string,
+): WebSearchSource {
+  return {
+    url,
+    ...(title !== undefined ? { title } : {}),
+    ...(snippet !== undefined ? { snippet } : {}),
+    ...(publishedAt !== undefined ? { publishedAt } : {}),
+  }
+}
+
+function finish(content: string | undefined, sources: WebSearchSource[]): WebSearchResult {
+  const seen = new Set<string>()
+  const deduped = sources.filter((source) => {
+    if (seen.has(source.url)) return false
+    seen.add(source.url)
+    return true
+  })
+  return {
+    ...(content !== undefined ? { content } : {}),
+    sources: deduped,
+    truncated: false,
+  }
+}
+
+function sourcesFromResults(
+  results: unknown,
+  pick: (item: JsonObject) => WebSearchSource | undefined,
+): WebSearchSource[] {
+  const out: WebSearchSource[] = []
+  for (const entry of asArray(results)) {
+    const source = pick(asObject(entry))
+    if (source !== undefined) out.push(source)
+  }
+  return out
+}
+
+function normalizeTavily(raw: JsonObject): WebSearchResult {
+  const sources = sourcesFromResults(raw.results, (item) => {
+    const url = asNonEmptyString(item.url)
+    if (url === undefined) return undefined
+    return makeSource(
+      url,
+      asNonEmptyString(item.title),
+      asNonEmptyString(item.content),
+      asNonEmptyString(item.published_date),
+    )
+  })
+  return finish(asNonEmptyString(raw.answer), sources)
+}
+
+function normalizeExa(raw: JsonObject): WebSearchResult {
+  const sources = sourcesFromResults(raw.results, (item) => {
+    const url = asNonEmptyString(item.url) ?? asNonEmptyString(item.id)
+    if (url === undefined) return undefined
+    const highlights = asArray(item.highlights)
+      .map((h) => asNonEmptyString(h))
+      .filter((h): h is string => h !== undefined)
+    return makeSource(
+      url,
+      asNonEmptyString(item.title),
+      highlights.length > 0 ? highlights.join(' ') : undefined,
+      asNonEmptyString(item.publishedDate),
+    )
+  })
+  return finish(undefined, sources)
+}
+
+const MARKDOWN_LINK = /\[([^\]]*)\]\((https?:\/\/[^)\s]+)\)/g
+
+/** 从生成式回答的 markdown 链接提取可引用来源（DeepSeek 官方 provider 同样只给
+ *  URL/标题）。无链接时返回空表——content-only 结果在 WebSearchResult 合法。 */
+export function extractMarkdownLinks(markdown: string, limit: number): WebSearchSource[] {
+  const seen = new Set<string>()
+  const out: WebSearchSource[] = []
+  for (const match of markdown.matchAll(MARKDOWN_LINK)) {
+    const url = match[2]
+    if (url === undefined || seen.has(url)) continue
+    seen.add(url)
+    const label = match[1] ?? ''
+    out.push(makeSource(url, label.trim() !== '' ? label : undefined))
+    if (out.length >= limit) break
+  }
+  return out
+}
+
+function normalizeOpenAiChat(raw: JsonObject): WebSearchResult {
+  const answer = asNonEmptyString(asObject(raw.data).answer)
+  if (answer === undefined) {
+    throw new Error('openai-chat 结果缺少 data.answer')
+  }
+  return finish(answer, extractMarkdownLinks(answer, 16))
+}
+
+function formatAttempts(attempts: unknown): string {
+  const summary = asArray(attempts)
+    .map((entry) => {
+      const item = asObject(entry)
+      const service = asNonEmptyString(item.service) ?? '?'
+      const message = asNonEmptyString(item.error) ?? 'unknown'
+      return `${service}: ${message}`
+    })
+    .join('; ')
+  return summary === '' ? '' : `（尝试过: ${summary}）`
+}
+
+/** 归一化 search.py 的完整 stdout JSON；失败以 Error 抛出（provider 层包 WebError）。 */
+export function normalizeSearchOutput(raw: unknown): WebSearchResult {
+  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)}`)
+  }
+}

package/src/ns.ts

@@ -0,0 +1,7 @@
+/**
+ * settings 命名空间字面量（纯常量，零依赖）。
+ * 服务端以字面量注册 settings section（用户层配置落 $DSH_HOME/settings.yaml，
+ * 热生效）；与行级 cordis Config 共用同一份 schemastery schema（config.ts）。
+ * @module web-search-services/ns
+ */
+export const SETTINGS_NS = 'dsh-plus-web-search-services'

package/src/provider.ts

@@ -0,0 +1,119 @@
+/**
+ * dsh-web 搜索 provider：把 ctx.web.search 桥接到 search-services skill 的
+ * search.py（Tavily / Exa / OpenAI Chat 免费额度后端）。官方 web_search 工具、
+ * 渲染与提示词零修改——本 provider 只产出标准 WebSearchResult，格式化天然一致。
+ * @module web-search-services/provider
+ */
+import { existsSync } from 'node:fs'
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web'
+import { WebError } from '@deepseek-ai/dsh-web'
+
+import { buildSearchArgv } from './args.ts'
+import type { SearchBackend, WebSearchServicesConfig } from './config.ts'
+import { expandHome, loadEnvFile } from './env-file.ts'
+import { normalizeSearchOutput } from './normalize.ts'
+import { isAbortError, runProcess, type SpawnFn } from './runner.ts'
+
+export const PROVIDER_ID = 'search-services'
+
+/** 各后端在合并环境（进程 env ⊕ envFile ⊕ 行级 keys）中的可用性判定变量。 */
+const BACKEND_KEY_VARS: Readonly<Record<SearchBackend, readonly string[]>> = {
+  tavily: ['TAVILY_API_KEY', 'TAVILY_API_KEYS'],
+  exa: ['EXA_API_KEY'],
+  'openai-chat': ['SEARCH_OPENAI_API_KEY'],
+}
+
+/** 行级 keys 覆盖 → 子进程环境变量；空串不注入（保持 envFile 单事实源优先）。 */
+export function keyOverridesEnv(keys: WebSearchServicesConfig['keys']): Record<string, string> {
+  const out: Record<string, string> = {}
+  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: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+function toWebError(err: unknown): WebError {
+  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,
+  })
+}
+
+export class SearchServicesProvider implements WebSearchProvider {
+  readonly id = PROVIDER_ID
+
+  private readonly current: () => WebSearchServicesConfig
+  private readonly spawnFn: SpawnFn | undefined
+
+  constructor(current: () => WebSearchServicesConfig, spawnFn?: SpawnFn | undefined) {
+    this.current = current
+    this.spawnFn = spawnFn
+  }
+
+  /** 廉价本地检查：脚本存在 + 优先级内至少一个后端有 key；不做网络调用。 */
+  available(): boolean {
+    const cfg = this.current()
+    if (!existsSync(expandHome(cfg.scriptPath))) return false
+    const env = this.childEnv(cfg)
+    return cfg.priority.some((backend) =>
+      BACKEND_KEY_VARS[backend].some((name) => (env[name]?.trim() ?? '') !== ''),
+    )
+  }
+
+  async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult> {
+    const cfg = this.current()
+    const argv = buildSearchArgv(cfg, request)
+    const stdout = await this.run(cfg, argv, signal)
+    return this.normalize(stdout)
+  }
+
+  private childEnv(cfg: WebSearchServicesConfig): NodeJS.ProcessEnv {
+    const fromFile = cfg.envFile.trim() === '' ? {} : loadEnvFile(cfg.envFile)
+    return { ...process.env, ...fromFile, ...keyOverridesEnv(cfg.keys) }
+  }
+
+  private async run(
+    cfg: WebSearchServicesConfig,
+    argv: string[],
+    signal: AbortSignal | undefined,
+  ): Promise<string> {
+    try {
+      return await runProcess({
+        command: cfg.python,
+        args: [expandHome(cfg.scriptPath), ...argv],
+        env: this.childEnv(cfg),
+        timeoutMs: cfg.timeoutMs,
+        ...(signal !== undefined ? { signal } : {}),
+        ...(this.spawnFn !== undefined ? { spawnFn: this.spawnFn } : {}),
+      })
+    } catch (err) {
+      throw toWebError(err)
+    }
+  }
+
+  private normalize(stdout: string): WebSearchResult {
+    let raw: unknown
+    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,
+      })
+    }
+  }
+}

package/src/runner.ts

@@ -0,0 +1,111 @@
+/**
+ * 子进程执行器：spawn 脚本、收集 stdout、超时/abort 杀进程。
+ * spawn 依赖注入以便单测 mock（禁网络铁律下测试绝不真实启动搜索脚本）。
+ * @module web-search-services/runner
+ */
+import { spawn } from 'node:child_process'
+
+export type SpawnFn = typeof spawn
+
+export interface RunProcessOptions {
+  command: string
+  args: readonly string[]
+  env: NodeJS.ProcessEnv
+  cwd?: string | undefined
+  timeoutMs: number
+  signal?: AbortSignal | undefined
+  maxBufferBytes?: number | undefined
+  spawnFn?: SpawnFn | undefined
+}
+
+const DEFAULT_MAX_BUFFER = 8 * 1024 * 1024
+const KILL_GRACE_MS = 2_000
+
+export function abortError(): Error {
+  const err = new Error('search aborted')
+  err.name = 'AbortError'
+  return err
+}
+
+export function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === 'AbortError'
+}
+
+function tail(text: string, max = 500): string {
+  const trimmed = text.trim()
+  return trimmed.length <= max ? trimmed : `…${trimmed.slice(-max)}`
+}
+
+/** 运行子进程并返回完整 stdout；任何失败以 Error 拒绝（消息含 stderr/退出码上下文）。 */
+export function runProcess(opts: RunProcessOptions): Promise<string> {
+  const spawnFn = opts.spawnFn ?? spawn
+  return new Promise<string>((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 !== undefined ? { cwd: opts.cwd } : {}),
+    })
+
+    const maxBuffer = opts.maxBufferBytes ?? DEFAULT_MAX_BUFFER
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    let graceTimer: NodeJS.Timeout | undefined
+
+    const cleanup = (): void => {
+      clearTimeout(timer)
+      if (graceTimer !== undefined) clearTimeout(graceTimer)
+      opts.signal?.removeEventListener('abort', onAbort)
+    }
+    const settle = (fn: () => void): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      fn()
+    }
+    const kill = (): void => {
+      child.kill('SIGTERM')
+      graceTimer = setTimeout(() => child.kill('SIGKILL'), KILL_GRACE_MS)
+      graceTimer.unref()
+    }
+    const onAbort = (): void => {
+      kill()
+      settle(() => reject(abortError()))
+    }
+    const timer = setTimeout(() => {
+      kill()
+      settle(() => reject(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: Buffer | string) => {
+      stdout += chunk.toString()
+      if (stdout.length > maxBuffer) {
+        kill()
+        settle(() => reject(new Error(`stdout exceeded ${maxBuffer} bytes`)))
+      }
+    })
+    child.stderr?.on('data', (chunk: Buffer | string) => {
+      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(new Error(`exited with code ${code ?? 'null'}: ${detail}`)))
+    })
+  })
+}