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

package/src/normalize.ts

@@ -1,173 +0,0 @@
-/**
- * search.py 输出 → dsh-web 标准 WebSearchResult 归一化（纯函数）。
- *
- * skill 各服务 request() 统一信封 {ok, service, status, data: <API 原始响应>}：
- * tavily/exa 业务字段在 data 下（results/answer），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 : []
-}
-
-/** snippet 截断上限：官方 deepseek provider 的摘录是短引文；Tavily content /
- *  Exa highlights 原始值可达整页文本，直接透传会撑爆工具结果上下文。 */
-const SNIPPET_MAX_CHARS = 500
-
-export function truncateSnippet(text: string): string {
-  return text.length <= SNIPPET_MAX_CHARS ? text : `${text.slice(0, SNIPPET_MAX_CHARS)}…`
-}
-
-function makeSource(
-  url: string,
-  title?: string,
-  snippet?: string,
-  publishedAt?: string,
-): WebSearchSource {
-  return {
-    url,
-    ...(title !== undefined ? { title } : {}),
-    ...(snippet !== undefined ? { snippet } : {}),
-    ...(publishedAt !== undefined ? { publishedAt } : {}),
-  }
-}
-
-/** skill 各服务 request() 统一信封 {ok, service, status, data: <API 响应>}；
- * 取 data 为业务 payload，data 缺失/空对象时回退顶层（旧形状容差）。 */
-function payloadOf(raw: JsonObject): JsonObject {
-  const data = asObject(raw.data)
-  return Object.keys(data).length > 0 ? data : raw
-}
-
-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 payload = payloadOf(raw)
-  const sources = sourcesFromResults(payload.results, (item) => {
-    const url = asNonEmptyString(item.url)
-    const content = asNonEmptyString(item.content)
-    if (url === undefined) return undefined
-    return makeSource(
-      url,
-      asNonEmptyString(item.title),
-      content !== undefined ? truncateSnippet(content) : undefined,
-      asNonEmptyString(item.published_date),
-    )
-  })
-  return finish(asNonEmptyString(payload.answer), sources)
-}
-
-function normalizeExa(raw: JsonObject): WebSearchResult {
-  const payload = payloadOf(raw)
-  const sources = sourcesFromResults(payload.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 ? truncateSnippet(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/provider.ts

@@ -1,188 +0,0 @@
-/**
- * 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 { 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'
-
-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'
-
-/**
- * scriptPath 解析：空串 = 随包内置脚本副本（tgz 内 scripts/search.py，与 lib/
- * 同级；src 直跑时为包根 scripts/）。非空按 ~ 展开。
- */
-export function resolveScriptPath(scriptPath: string): string {
-  if (scriptPath.trim() !== '') return expandHome(scriptPath)
-  return fileURLToPath(new URL('../scripts/search.py', import.meta.url))
-}
-
-/** 各后端在合并环境（进程 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)
-}
-
-/**
- * 判定「解释器缺失」类失败（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 })
-  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
-  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(),
-      }))
-  }
-
-  /** 解释器候选链（有序、记忆化）。 */
-  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() ?? '') !== ''),
-    )
-  }
-
-  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> {
-    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 {
-    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/python.ts

@@ -1,193 +0,0 @@
-/**
- * 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

@@ -1,140 +0,0 @@
-/**
- * 子进程执行器：spawn 脚本、收集 stdout、超时/abort 杀进程。
- * spawn 依赖注入以便单测 mock（禁网络铁律下测试绝不真实启动搜索脚本）。
- * @module web-search-services/runner
- */
-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[]
-  env: NodeJS.ProcessEnv
-  cwd?: string | undefined
-  timeoutMs: number
-  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'
-  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
-  const platform = opts.platform ?? process.platform
-  const killTree = opts.killTree ?? killWindowsTree
-  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 => {
-      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()
-    }
-    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}`)))
-    })
-  })
-}