@dsh-plus/web-search-services 0.1.5 → 0.1.7

package/lib/index.d.ts

@@ -49,6 +49,24 @@ type WebSearchServicesConfigFields = Schemastery.TypeT<typeof Config>;
 /** 平面配置形态（消费面的读取形态，由活动引用解包得到）。 */
 type WebSearchServicesConfig = UnwrapVolatile<WebSearchServicesConfigFields>;
 //#endregion
+//#region src/python.d.ts
+/** 注入的文件系统视图（测试在 Linux 上覆盖 win32 形态）。 */
+interface PythonFs {
+  exists: (path: string) => boolean;
+  /** 列目录一层；目录不存在/不可读返回空表。 */
+  list: (path: string) => readonly {
+    name: string;
+    dir: boolean;
+  }[];
+}
+interface PythonDiscoveryEnv {
+  platform: NodeJS.Platform;
+  pathValue: string | undefined;
+  /** 桌面端捆绑运行时根；undefined = 无（跳过 BFS）。 */
+  bundledRoot: string | undefined;
+  fs: PythonFs;
+}
+//#endregion
 //#region src/runner.d.ts
 type SpawnFn = typeof spawn;
 //#endregion
@@ -58,8 +76,16 @@ declare class SearchServicesProvider implements WebSearchProvider {
   readonly id = "search-services";
   private readonly current;
   private readonly spawnFn;
-  constructor(current: () => WebSearchServicesConfig, spawnFn?: SpawnFn | undefined);
-  /** 廉价本地检查：脚本存在 + 优先级内至少一个后端有 key；不做网络调用。 */
+  private readonly discovery;
+  /** 候选链按 `${python}|${bundledRoot}` 记忆：PATH 与捆绑布局在进程内静态。 */
+  private readonly candidateCache;
+  constructor(current: () => WebSearchServicesConfig, spawnFn?: SpawnFn | undefined, discovery?: (() => PythonDiscoveryEnv) | undefined);
+  /** 解释器候选链（有序、记忆化）。 */
+  private candidates;
+  /**
+   * 廉价本地检查：脚本存在 + 至少一个【已验证】解释器候选（配置/捆绑/PATH，
+   * 未验证兜底名不算）+ 优先级内至少一个后端有 key；不做网络调用、不 spawn。
+   */
   available(): boolean;
   search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
   private childEnv;

package/lib/index.js

@@ -1,6 +1,7 @@
 import { unwrapVolatile } from "@dsh-plus/shared";
-import { existsSync, readFileSync } from "node:fs";
+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";
@@ -29,10 +30,10 @@ function buildSearchArgv(cfg, request) {
 * 文件缺失/不可读返回空表（envFile 是优化来源，不是硬依赖）。
 * @module web-search-services/env-file
 */
-/** 展开路径开头的 ~（仅 ~ 与 ~/ 两种形态，不借 shell）。 */
+/** 展开路径开头的 ~（支持 `~`、`~/`、`~\` 三种形态，与官方 dsh-home-paths 对齐，不借 shell）。 */
 function expandHome(path) {
 	if (path === "~") return homedir();
-	if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+	if (path.startsWith("~/") || path.startsWith("~\\")) return join(homedir(), path.slice(2));
 	return path;
 }
 function unquote(value) {
@@ -177,6 +178,182 @@ function normalizeSearchOutput(raw) {
 	}
 }
 //#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 杀进程。
@@ -185,6 +362,23 @@ function normalizeSearchOutput(raw) {
 */
 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";
@@ -200,6 +394,8 @@ function tail(text, max = 500) {
 /** 运行子进程并返回完整 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());
@@ -231,6 +427,11 @@ function runProcess(opts) {
 			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();
@@ -305,6 +506,14 @@ function keyOverridesEnv(keys) {
 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 });
@@ -314,14 +523,38 @@ var SearchServicesProvider = class {
 	id = PROVIDER_ID;
 	current;
 	spawnFn;
-	constructor(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;
 	}
-	/** 廉价本地检查：脚本存在 + 优先级内至少一个后端有 key；不做网络调用。 */
+	/**
+	* 廉价本地检查：脚本存在 + 至少一个【已验证】解释器候选（配置/捆绑/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() ?? "") !== ""));
 	}
@@ -340,18 +573,27 @@ var SearchServicesProvider = class {
 		};
 	}
 	async run(cfg, argv, signal) {
-		try {
+		const script = resolveScriptPath(cfg.scriptPath);
+		const env = this.childEnv(cfg);
+		let lastMissing;
+		for (const candidate of this.candidates()) try {
 			return await runProcess({
-				command: cfg.python,
-				args: [resolveScriptPath(cfg.scriptPath), ...argv],
-				env: this.childEnv(cfg),
+				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) {
-			throw toWebError(err);
+			if (!isMissingInterpreter(err)) throw toWebError(err);
+			lastMissing = err;
 		}
+		throw toWebError(lastMissing ?? /* @__PURE__ */ new Error("未找到可用的 python 解释器（配置 python 或安装 python3）"));
 	}
 	normalize(stdout) {
 		let raw;
@@ -402,7 +644,7 @@ const KeysSchema = z.object({
 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 可执行文件").default("python3").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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/web-search-services",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",
@@ -19,18 +19,20 @@
     "scripts"
   ],
   "dependencies": {
-    "@dsh-plus/shared": "0.1.23"
+    "@dsh-plus/shared": "0.1.27"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-settings": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-web": "^0.1.7-rc.1",
+    "@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"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-settings": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-web": "0.1.7-rc.1",
+    "@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"
   },
   "publishConfig": {

package/scripts/fetch_playwright.py

@@ -31,6 +31,7 @@ import fetch as local_fetch  # noqa: E402
 
 
 DEFAULT_SELECTOR = "main, article, [role='main'], .content, #content, .post, .entry-content"
+_IS_WINDOWS = os.name == "nt"
 _ACTIVE_PGIDS: set[int] = set()
 _ACTIVE_BROWSER_PIDS: set[int] = set()
 _TEMP_DIRS: set[str] = set()
@@ -52,46 +53,91 @@ class PlaywrightError(RuntimeError):
         self.details = details
 
 
+def _popen(cmd: list[str], **kwargs: Any) -> subprocess.Popen:
+    """启动子进程；Windows 上 .cmd/.bat 必须经 cmd.exe（CreateProcess 不直接执行批处理）。"""
+    if _IS_WINDOWS and cmd and cmd[0].lower().endswith((".cmd", ".bat")):
+        cmd = ["cmd", "/c", *cmd]
+    return subprocess.Popen(cmd, **kwargs)
+
+
+def _taskkill_tree(pid: int) -> None:
+    """Windows 进程树终止：taskkill /T /F（无 POSIX 信号语义，单杀父进程会留孤儿）。"""
+    try:
+        subprocess.run(
+            ["taskkill", "/PID", str(pid), "/T", "/F"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+            timeout=15,
+        )
+    except (OSError, subprocess.SubprocessError):
+        pass
+
+
+def _signal_group(pgid: int, *, force: bool) -> None:
+    """向进程组发信号（仅 POSIX；Windows 无 killpg/SIGKILL，直接返回）。"""
+    if _IS_WINDOWS:
+        return
+    try:
+        os.killpg(pgid, signal.SIGKILL if force else signal.SIGTERM)
+    except OSError:
+        pass
+
+
+def _signal_pid(pid: int, *, force: bool) -> None:
+    """终止单个进程：POSIX 走 SIGTERM→SIGKILL，Windows 统一 taskkill /T /F。"""
+    if _IS_WINDOWS:
+        _taskkill_tree(pid)
+        return
+    try:
+        os.kill(pid, signal.SIGKILL if force else signal.SIGTERM)
+    except OSError:
+        pass
+
+
+def _pid_alive(pid: int) -> bool:
+    """进程存活探测。Windows 上 os.kill(pid, 0) 会直接杀进程，绝不能用。"""
+    if _IS_WINDOWS:
+        try:
+            out = subprocess.run(
+                ["tasklist", "/FI", f"PID eq {pid}"],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                check=False,
+                timeout=15,
+                text=True,
+            )
+        except (OSError, subprocess.SubprocessError):
+            return False
+        return str(pid) in out.stdout
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
 def _safe_rmtree(path: str) -> None:
-    """只清理本脚本创建的 /tmp 临时目录，避免误删。"""
+    """只清理本脚本创建的临时目录（tempfile.gettempdir() 下 search-services-pw-*），避免误删。"""
 
+    root = os.path.realpath(tempfile.gettempdir())
     real = os.path.realpath(path)
-    if not real.startswith("/tmp/search-services-pw-"):
+    if not real.startswith(os.path.join(root, "search-services-pw-")):
         return
     shutil.rmtree(real, ignore_errors=True)
 
 
 def _cleanup() -> None:
     for pgid in list(_ACTIVE_PGIDS):
-        try:
-            os.killpg(pgid, signal.SIGTERM)
-        except ProcessLookupError:
-            pass
-        except OSError:
-            pass
+        _signal_group(pgid, force=False)
     time.sleep(0.1)
     for pgid in list(_ACTIVE_PGIDS):
-        try:
-            os.killpg(pgid, signal.SIGKILL)
-        except ProcessLookupError:
-            pass
-        except OSError:
-            pass
+        _signal_group(pgid, force=True)
     for pid in list(_ACTIVE_BROWSER_PIDS):
-        try:
-            os.kill(pid, signal.SIGTERM)
-        except ProcessLookupError:
-            pass
-        except OSError:
-            pass
+        _signal_pid(pid, force=False)
     time.sleep(0.1)
     for pid in list(_ACTIVE_BROWSER_PIDS):
-        try:
-            os.kill(pid, signal.SIGKILL)
-        except ProcessLookupError:
-            pass
-        except OSError:
-            pass
+        _signal_pid(pid, force=True)
     for temp_dir in list(_TEMP_DIRS):
         _safe_rmtree(temp_dir)
         _TEMP_DIRS.discard(temp_dir)
@@ -124,7 +170,8 @@ def _playwright_command_base() -> list[str]:
 
     codex_home = os.getenv("CODEX_HOME") or os.path.join(os.path.expanduser("~"), ".codex")
     wrapper = os.path.join(codex_home, "skills", "playwright-headless", "scripts", "playwright_cli.sh")
-    if os.path.exists(wrapper):
+    # .sh 包装依赖 POSIX shell，Windows 上直接跳过走 npx 兜底。
+    if not _IS_WINDOWS and os.path.exists(wrapper):
         return [wrapper]
 
     npx = shutil.which("npx")
@@ -180,37 +227,33 @@ def _run_checked_with_retries(cmd: list[str], *, timeout: float, cwd: str, retri
 
 
 def _run_command(cmd: list[str], *, timeout: float, cwd: str) -> tuple[int, str, str]:
-    proc = subprocess.Popen(
+    proc = _popen(
         cmd,
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         text=True,
         cwd=cwd,
-        start_new_session=True,
+        # Windows 无 setsid；进程树终止由 taskkill /T 承担。
+        start_new_session=not _IS_WINDOWS,
     )
-    try:
-        pgid = os.getpgid(proc.pid)
-        _ACTIVE_PGIDS.add(pgid)
-    except OSError:
-        pgid = None
+    pgid: Optional[int] = None
+    if not _IS_WINDOWS:
+        try:
+            pgid = os.getpgid(proc.pid)
+            _ACTIVE_PGIDS.add(pgid)
+        except OSError:
+            pgid = None
     try:
         stdout, stderr = proc.communicate(timeout=timeout)
         return proc.returncode, stdout, stderr
     except subprocess.TimeoutExpired as exc:
         if pgid is not None:
-            try:
-                os.killpg(pgid, signal.SIGTERM)
-            except ProcessLookupError:
-                pass
-            except OSError:
-                pass
+            _signal_group(pgid, force=False)
             time.sleep(0.2)
-            try:
-                os.killpg(pgid, signal.SIGKILL)
-            except ProcessLookupError:
-                pass
-            except OSError:
-                pass
+            _signal_group(pgid, force=True)
+        else:
+            # Windows（或 POSIX 取组失败）：端掉整棵子进程树而非单个进程。
+            _signal_pid(proc.pid, force=True)
         try:
             proc.wait(timeout=2)
         except subprocess.TimeoutExpired:
@@ -366,22 +409,12 @@ def fetch_one(
             except Exception:
                 pass
         if browser_pid is not None:
-            try:
-                os.kill(browser_pid, 0)
-            except ProcessLookupError:
-                _ACTIVE_BROWSER_PIDS.discard(browser_pid)
-            except OSError:
-                _ACTIVE_BROWSER_PIDS.discard(browser_pid)
-            else:
-                try:
-                    os.kill(browser_pid, signal.SIGTERM)
-                    time.sleep(0.2)
-                    os.kill(browser_pid, signal.SIGKILL)
-                except ProcessLookupError:
-                    pass
-                except OSError:
-                    pass
-                _ACTIVE_BROWSER_PIDS.discard(browser_pid)
+            # 存活探测必须走 _pid_alive：Windows 上 os.kill(pid, 0) 会直接杀进程。
+            if _pid_alive(browser_pid):
+                _signal_pid(browser_pid, force=False)
+                time.sleep(0.2)
+                _signal_pid(browser_pid, force=True)
+            _ACTIVE_BROWSER_PIDS.discard(browser_pid)
         _safe_rmtree(temp_dir)
         _TEMP_DIRS.discard(temp_dir)
 

package/src/config.ts

@@ -64,7 +64,13 @@ export const Config = z.object({
     .description('skill 密钥 env 文件路径（支持 ~ 展开）；空串表示不读 envFile')
     .default(DEFAULT_ENV_FILE)
     .volatile(),
-  python: z.string().description('python 可执行文件').default('python3').volatile(),
+  python: z
+    .string()
+    .description(
+      'python 解释器（可含参数，如 `py -3`）；空串 = 自动发现（配置外按 桌面捆绑运行时 → PATH → 平台兜底名 解析）',
+    )
+    .default('')
+    .volatile(),
   priority: z
     .array(PRIORITY_ENTRY)
     .description('后端优先级：靠前的先尝试，失败自动回退到下一个')

package/src/env-file.ts

@@ -8,10 +8,10 @@ import { readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
-/** 展开路径开头的 ~（仅 ~ 与 ~/ 两种形态，不借 shell）。 */
+/** 展开路径开头的 ~（支持 `~`、`~/`、`~\` 三种形态，与官方 dsh-home-paths 对齐，不借 shell）。 */
 export function expandHome(path: string): string {
   if (path === '~') return homedir()
-  if (path.startsWith('~/')) return join(homedir(), path.slice(2))
+  if (path.startsWith('~/') || path.startsWith('~\\')) return join(homedir(), path.slice(2))
   return path
 }
 

package/src/provider.ts

@@ -7,6 +7,7 @@
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
 import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web'
 import { WebError } from '@deepseek-ai/dsh-web'
 
@@ -14,6 +15,12 @@ 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 {
+  type PythonCandidate,
+  type PythonDiscoveryEnv,
+  pythonCandidates,
+  realPythonFs,
+} from './python.ts'
 import { isAbortError, runProcess, type SpawnFn } from './runner.ts'
 
 export const PROVIDER_ID = 'search-services'
@@ -49,6 +56,16 @@ function messageOf(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }
 
+/**
+ * 判定「解释器缺失」类失败（spawn ENOENT，runProcess 包装时保留 cause）：
+ * 候选链据此换下一个解释器；其余错误照常上抛。
+ */
+function isMissingInterpreter(err: unknown): boolean {
+  if (!(err instanceof Error)) return false
+  const cause = err.cause as { code?: unknown } | undefined
+  return cause?.code === 'ENOENT'
+}
+
 function toWebError(err: unknown): WebError {
   if (err instanceof WebError) return err
   if (isAbortError(err)) return new WebError('搜索已取消', 'WEB_ABORTED', { cause: err })
@@ -62,16 +79,47 @@ export class SearchServicesProvider implements WebSearchProvider {
 
   private readonly current: () => WebSearchServicesConfig
   private readonly spawnFn: SpawnFn | undefined
-
-  constructor(current: () => WebSearchServicesConfig, spawnFn?: SpawnFn | undefined) {
+  private readonly discovery: () => PythonDiscoveryEnv
+  /** 候选链按 `${python}|${bundledRoot}` 记忆：PATH 与捆绑布局在进程内静态。 */
+  private readonly candidateCache = new Map<string, PythonCandidate[]>()
+
+  constructor(
+    current: () => WebSearchServicesConfig,
+    spawnFn?: SpawnFn | undefined,
+    discovery?: (() => PythonDiscoveryEnv) | undefined,
+  ) {
     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(),
+      }))
   }
 
-  /** 廉价本地检查：脚本存在 + 优先级内至少一个后端有 key；不做网络调用。 */
+  /** 解释器候选链（有序、记忆化）。 */
+  private candidates(): PythonCandidate[] {
+    const cfg = this.current()
+    const env = this.discovery()
+    const key = `${cfg.python}|${env.bundledRoot ?? ''}`
+    const cached = this.candidateCache.get(key)
+    if (cached !== undefined) return cached
+    const resolved = pythonCandidates(env, cfg.python)
+    this.candidateCache.set(key, resolved)
+    return resolved
+  }
+
+  /**
+   * 廉价本地检查：脚本存在 + 至少一个【已验证】解释器候选（配置/捆绑/PATH，
+   * 未验证兜底名不算）+ 优先级内至少一个后端有 key；不做网络调用、不 spawn。
+   */
   available(): boolean {
     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() ?? '') !== ''),
@@ -95,18 +143,28 @@ export class SearchServicesProvider implements WebSearchProvider {
     argv: string[],
     signal: AbortSignal | undefined,
   ): Promise<string> {
-    try {
-      return await runProcess({
-        command: cfg.python,
-        args: [resolveScriptPath(cfg.scriptPath), ...argv],
-        env: this.childEnv(cfg),
-        timeoutMs: cfg.timeoutMs,
-        ...(signal !== undefined ? { signal } : {}),
-        ...(this.spawnFn !== undefined ? { spawnFn: this.spawnFn } : {}),
-      })
-    } catch (err) {
-      throw toWebError(err)
+    const script = resolveScriptPath(cfg.scriptPath)
+    const env = this.childEnv(cfg)
+    let lastMissing: unknown
+    // 候选链逐个尝试：仅解释器缺失（ENOENT）换下一个，其余错误立即上抛。
+    for (const candidate of this.candidates()) {
+      try {
+        return await runProcess({
+          command: candidate.command,
+          args: [...candidate.argsPrefix, script, ...argv],
+          env,
+          timeoutMs: cfg.timeoutMs,
+          ...(signal !== undefined ? { signal } : {}),
+          ...(this.spawnFn !== undefined ? { spawnFn: this.spawnFn } : {}),
+        })
+      } catch (err) {
+        if (!isMissingInterpreter(err)) throw toWebError(err)
+        lastMissing = err
+      }
     }
+    throw toWebError(
+      lastMissing ?? new Error('未找到可用的 python 解释器（配置 python 或安装 python3）'),
+    )
   }
 
   private normalize(stdout: string): WebSearchResult {

package/src/python.ts

@@ -0,0 +1,193 @@
+/**
+ * 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
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 候选来源：config=用户显式配置；bundled=桌面端捆绑运行时；path=PATH 扫描命中；fallback=未验证兜底名。 */
+export type PythonSource = 'config' | 'bundled' | 'path' | 'fallback'
+
+export interface PythonCandidate {
+  command: string
+  argsPrefix: readonly string[]
+  source: PythonSource
+}
+
+/** 注入的文件系统视图（测试在 Linux 上覆盖 win32 形态）。 */
+export interface PythonFs {
+  exists: (path: string) => boolean
+  /** 列目录一层；目录不存在/不可读返回空表。 */
+  list: (path: string) => readonly { name: string; dir: boolean }[]
+}
+
+export interface PythonDiscoveryEnv {
+  platform: NodeJS.Platform
+  pathValue: string | undefined
+  /** 桌面端捆绑运行时根；undefined = 无（跳过 BFS）。 */
+  bundledRoot: string | undefined
+  fs: PythonFs
+}
+
+interface PlatformCommand {
+  name: string
+  argsPrefix: readonly string[]
+}
+
+interface PlatformSpec {
+  /** PATH 扫描尝试的文件名（win32 带 .exe 后缀）。 */
+  pathNames: readonly PlatformCommand[]
+  /** 未验证兜底（PATH 扫描落空时信任 spawn 的 PATH 解析）。 */
+  fallbacks: readonly PlatformCommand[]
+  /** 捆绑运行时 BFS 中接受的解释器文件名。 */
+  bundledNames: ReadonlySet<string>
+}
+
+const POSIX_SPEC: PlatformSpec = {
+  pathNames: [
+    { name: 'python3', argsPrefix: [] },
+    { name: 'python', argsPrefix: [] },
+  ],
+  fallbacks: [
+    { name: 'python3', argsPrefix: [] },
+    { name: 'python', argsPrefix: [] },
+  ],
+  bundledNames: new Set(['python3', 'python']),
+}
+
+const WIN32_SPEC: PlatformSpec = {
+  pathNames: [
+    { name: 'python.exe', argsPrefix: [] },
+    { name: 'python3.exe', argsPrefix: [] },
+    // Python 启动器：-3 显式锁 Python 3，避免用户配置默认 py2。
+    { name: 'py.exe', argsPrefix: ['-3'] },
+  ],
+  fallbacks: [
+    { name: 'python', argsPrefix: [] },
+    { name: 'py', argsPrefix: ['-3'] },
+    { name: 'python3', argsPrefix: [] },
+  ],
+  bundledNames: 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: ReadonlySet<string> = new Set([
+  'Lib',
+  'lib',
+  'lib64',
+  'include',
+  'share',
+  'site-packages',
+  'test',
+  'tests',
+  'doc',
+  'docs',
+])
+
+function specOf(platform: NodeJS.Platform): PlatformSpec {
+  return platform === 'win32' ? WIN32_SPEC : POSIX_SPEC
+}
+
+/** 显式配置 → 单候选（按空白拆分，支持 `py -3` 形态）。 */
+function configCandidate(configPython: string): PythonCandidate | undefined {
+  const parts = configPython
+    .trim()
+    .split(/\s+/)
+    .filter((part) => part.length > 0)
+  const [command, ...argsPrefix] = parts
+  if (command === undefined) return undefined
+  return { command, argsPrefix, source: 'config' }
+}
+
+/** 在捆绑运行时根下浅层 BFS 找解释器文件（先按层扫文件名，再入队子目录）。 */
+function findBundled(root: string, env: PythonDiscoveryEnv): string | undefined {
+  if (!env.fs.exists(root)) return undefined
+  const spec = specOf(env.platform)
+  const queue: { dir: string; depth: number }[] = [{ dir: root, depth: 0 }]
+  let visits = 0
+  while (queue.length > 0 && visits < BUNDLED_MAX_VISITS) {
+    const item = queue.shift()
+    if (item === undefined) 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 })
+      }
+    }
+  }
+  return undefined
+}
+
+/** PATH 逐目录扫描（名字在外层：win32 任一处的 python.exe 优先于 python3.exe）。 */
+function scanPath(env: PythonDiscoveryEnv, spec: PlatformSpec): PythonCandidate[] {
+  // PATH 分隔符按【被发现的平台】而非宿主平台取：测试可在 Linux 上覆盖 win32 形态。
+  const listSep = env.platform === 'win32' ? ';' : ':'
+  const dirs = (env.pathValue ?? '').split(listSep).filter((dir) => dir.length > 0)
+  const out: PythonCandidate[] = []
+  const seen = new Set<string>()
+  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。
+ */
+export function pythonCandidates(env: PythonDiscoveryEnv, configPython: string): PythonCandidate[] {
+  const explicit = configCandidate(configPython)
+  if (explicit !== undefined) return [explicit]
+  const spec = specOf(env.platform)
+  const out: PythonCandidate[] = []
+  if (env.bundledRoot !== undefined) {
+    const bundled = findBundled(env.bundledRoot, env)
+    if (bundled !== undefined) 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 对不可读目录返回空表）。 */
+export function realPythonFs(): PythonFs {
+  return {
+    exists: (path: string) => existsSync(path),
+    list: (path: string) => {
+      try {
+        return readdirSync(path, { withFileTypes: true }).map((entry) => ({
+          name: entry.name,
+          dir: entry.isDirectory(),
+        }))
+      } catch {
+        return []
+      }
+    },
+  }
+}

package/src/runner.ts

@@ -7,6 +7,9 @@ import { spawn } from 'node:child_process'
 
 export type SpawnFn = typeof spawn
 
+/** 进程树终止器（Windows 用 taskkill 注入面；测试可替换）。 */
+export type KillTreeFn = (pid: number) => void
+
 export interface RunProcessOptions {
   command: string
   args: readonly string[]
@@ -16,11 +19,29 @@ export interface RunProcessOptions {
   signal?: AbortSignal | undefined
   maxBufferBytes?: number | undefined
   spawnFn?: SpawnFn | undefined
+  /** 平台（缺省 process.platform）：win32 的超时/中止走进程树终止而非信号。 */
+  platform?: NodeJS.Platform | undefined
+  /** win32 进程树终止实现（缺省 taskkill /T /F）。 */
+  killTree?: KillTreeFn | undefined
 }
 
 const DEFAULT_MAX_BUFFER = 8 * 1024 * 1024
 const KILL_GRACE_MS = 2_000
 
+/**
+ * Windows 进程树终止：`taskkill /PID <pid> /T /F`（Windows 无 POSIX 信号语义，
+ * 单纯 `child.kill()` 会遗留 npx/playwright 派生的子进程树；上游
+ * dsh-subprocess-local 同款做法）。error 监听防 taskkill 缺席成为未捕获异常。
+ */
+export const killWindowsTree: KillTreeFn = (pid) => {
+  const killer = spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' })
+  killer.on('error', (error) => {
+    // 无监听者的 'error' 会成为未捕获异常；终止是尽力而为，留上下文日志即可。
+    console.warn(`[web-search-services] taskkill 失败（pid ${pid}）: ${error.message}`)
+  })
+  killer.unref()
+}
+
 export function abortError(): Error {
   const err = new Error('search aborted')
   err.name = 'AbortError'
@@ -39,6 +60,8 @@ function tail(text: string, max = 500): string {
 /** 运行子进程并返回完整 stdout；任何失败以 Error 拒绝（消息含 stderr/退出码上下文）。 */
 export function runProcess(opts: RunProcessOptions): Promise<string> {
   const spawnFn = opts.spawnFn ?? spawn
+  const platform = opts.platform ?? process.platform
+  const killTree = opts.killTree ?? killWindowsTree
   return new Promise<string>((resolve, reject) => {
     if (opts.signal?.aborted === true) {
       reject(abortError())
@@ -68,6 +91,12 @@ export function runProcess(opts: RunProcessOptions): Promise<string> {
       fn()
     }
     const kill = (): void => {
+      if (platform === 'win32') {
+        // Windows 无 SIGTERM/SIGKILL 语义：taskkill /T /F 端掉整棵进程树。
+        if (child.pid !== undefined) killTree(child.pid)
+        else child.kill()
+        return
+      }
       child.kill('SIGTERM')
       graceTimer = setTimeout(() => child.kill('SIGKILL'), KILL_GRACE_MS)
       graceTimer.unref()