dsh-convert-core 0.1.0-alpha.1

package/src/media/models.ts

@@ -0,0 +1,124 @@
+/**
+ * 两个**专用小模型**的调用点:语音识别(whisper)与画面文字 OCR。
+ *
+ * 都不是大模型,也都不联网推理:模型下载一次后完全离线。helper 脚本随包发布
+ * (`scripts/*.py`,由 `uvx --with …` 按需拉起),所以这个包不把 Python/模型塞进 npm tarball,
+ * 但会把「要不要下载模型」这个决定**显式**交回调用方。
+ */
+
+import { execFile } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+import { MediaToMarkdownError, type MediaAsrOptions, type MediaCue, type MediaToolOptions } from './types.js'
+import { UVX_HINT } from './binaries.js'
+
+const execFileAsync = promisify(execFile)
+
+/** helper 脚本路径:`lib/*.js` → `scripts/*.py`。 */
+function helperPath(name: string): string {
+  return fileURLToPath(new URL(`../../scripts/${name}`, import.meta.url))
+}
+
+export const ASR_MODEL_SIZES: Record<string, string> = {
+  tiny: '约 75 MB',
+  base: '约 145 MB',
+  small: '约 460 MB',
+  medium: '约 1.5 GB',
+  'large-v3': '约 3 GB',
+  'large-v3-turbo': '约 1.5 GB',
+}
+
+export function describeModel(model: string): string {
+  return ASR_MODEL_SIZES[model] ?? '未知大小'
+}
+
+function uvxArgs(tools: MediaToolOptions | undefined, packages: string[], script: string, args: string[]): [string, string[]] {
+  const uvx = tools?.uvxPath?.trim() || process.env.MEDIA_TO_MD_UVX?.trim() || 'uvx'
+  const python = tools?.pythonVersion?.trim() || process.env.MEDIA_TO_MD_PYTHON?.trim() || '3.12'
+  return [uvx, ['--python', python, ...packages.flatMap(pkg => ['--with', pkg]), 'python', script, ...args]]
+}
+
+export interface TranscriptionResult {
+  cues: MediaCue[]
+  model: string
+  language?: string
+}
+
+/** 音频 → 带时间戳的转写。`allowModelDownload` 为 false 且本地无模型时抛 `ASR_MODEL_REQUIRED`。 */
+export async function transcribe(
+  audioFile: string,
+  scratch: string,
+  asr: MediaAsrOptions = {},
+  tools?: MediaToolOptions,
+  signal?: AbortSignal,
+): Promise<TranscriptionResult> {
+  const model = asr.model?.trim() || 'small'
+  const [cmd, args] = uvxArgs(tools, ['faster-whisper'], helperPath('asr.py'), [audioFile, model, asr.language?.trim() ?? ''])
+  let stdout: string
+  try {
+    ({ stdout } = await execFileAsync(cmd, args, {
+      maxBuffer: 64 * 1024 * 1024,
+      env: {
+        ...process.env,
+        ...(asr.device ? { MEDIA_TO_MD_ASR_DEVICE: asr.device } : {}),
+        ...(asr.computeType ? { MEDIA_TO_MD_ASR_COMPUTE: asr.computeType } : {}),
+        ...(asr.beamSize ? { MEDIA_TO_MD_ASR_BEAM: String(asr.beamSize) } : {}),
+      },
+      ...(signal ? { signal } : {}),
+    }))
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause)
+    const looksLikeDownload = /LocalEntryNotFoundError|ConnectError|SSL|Connection|snapshot_download/i.test(detail)
+    if (looksLikeDownload && asr.allowModelDownload === false) {
+      throw new MediaToMarkdownError(
+        'ASR_MODEL_REQUIRED',
+        `无字幕,转写需要下载本地 whisper 模型(${model},${describeModel(model)});当前未允许下载,已放弃转换。`,
+        `先取得模型再重试:设 allowModelDownload=true,或把模型放到本地目录后用 asr.model 指向它。中文建议 large-v3-turbo。`,
+      )
+    }
+    throw new MediaToMarkdownError(
+      'ASR_FAILED',
+      `本地转写失败:${detail}`,
+      '检查网络(首次需下载模型,国内可设 HF_ENDPOINT=https://hf-mirror.com)或预先下载模型目录并用 asr.model 指向它。',
+    )
+  }
+  const payload = JSON.parse(stdout.trim().split('\n').filter(Boolean).pop() ?? '{}') as {
+    segments?: Array<{ start: number; end?: number; text: string }>
+    language?: string
+  }
+  const cues = (payload.segments ?? [])
+    .map(segment => ({
+      seconds: Number(segment.start) || 0,
+      ...(Number(segment.end) ? { endSeconds: Number(segment.end) } : {}),
+      text: (segment.text ?? '').trim(),
+    }))
+    .filter(cue => cue.text.length > 0)
+  return { cues, model, ...(payload.language ? { language: payload.language } : {}) }
+}
+
+export interface OcrEntry {
+  path: string
+  lines: string[]
+  text: string
+}
+
+/** 图片(或关键帧) → 画面文字。仅在调用方显式开启时才该被调到。 */
+export async function ocrImages(
+  files: string[],
+  tools?: MediaToolOptions,
+  signal?: AbortSignal,
+): Promise<{ entries: OcrEntry[]; warnings: Array<{ code: string; message: string }> }> {
+  if (files.length === 0) return { entries: [], warnings: [] }
+  const [cmd, args] = uvxArgs(tools, ['rapidocr-onnxruntime'], helperPath('ocr.py'), files)
+  try {
+    const { stdout } = await execFileAsync(cmd, args, { maxBuffer: 32 * 1024 * 1024, ...(signal ? { signal } : {}) })
+    const entries = JSON.parse(stdout.trim().split('\n').filter(Boolean).pop() ?? '[]') as OcrEntry[]
+    return { entries, warnings: [] }
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause)
+    if (/ENOENT/.test(detail)) {
+      return { entries: [], warnings: [{ code: 'OCR_UNAVAILABLE', message: `未找到 uvx,跳过 OCR。${UVX_HINT}` }] }
+    }
+    return { entries: [], warnings: [{ code: 'OCR_FAILED', message: `OCR 失败:${detail}` }] }
+  }
+}

package/src/media/scanned.ts

@@ -0,0 +1,200 @@
+/**
+ * 轻量扫描档:纯图片页 PDF → 逐页本地 OCR → Markdown。
+ *
+ * 解决的**唯一**问题:扫描件里的字读不出来(anydoc 只吃文本层 PDF)。
+ * 刻意不做哪些事:
+ *
+ * - **不引入 docling / PaddlePaddle / MinerU**:那是 issues/0017 的"可选高质量档",
+ *   用来做版面顺序、表格结构、公式还原;代价是几百 MB ~ 20 GB 的依赖。
+ * - **不承诺版面**:输出就是"第 N 页 + 该页图片 + 该页文字",顺序 = 页序。
+ * - **不联网**:整条链只有两个本地组件 —— pypdfium2(渲染页图)与 RapidOCR(识别文字)。
+ *
+ * 渲染用 pypdfium2 而不是 poppler,是因为 `pdftoppm` 是外部二进制,不是每台机器都有
+ * (本机就没有);pypdfium2 是 pip wheel,自带 pdfium,由 uvx 按需拉起。
+ */
+
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { execFile } from 'node:child_process'
+import { mkdir, mkdtemp, readFile, rm, stat } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+import { UVX_HINT } from './binaries.js'
+import { buildScannedMarkdown } from './markdown.js'
+import { ocrImages } from './models.js'
+import {
+  MediaToMarkdownError,
+  type MediaToMarkdownResult,
+  type MediaToolOptions,
+  type MediaWarning,
+  type ScannedPage,
+  type ScannedPdfOptions,
+} from './types.js'
+
+const execFileAsync = promisify(execFile)
+
+function helperPath(name: string): string {
+  return fileURLToPath(new URL(`../../scripts/${name}`, import.meta.url))
+}
+
+function uvxCommand(tools: MediaToolOptions | undefined): { cmd: string; python: string } {
+  return {
+    cmd: tools?.uvxPath?.trim() || process.env.MEDIA_TO_MD_UVX?.trim() || 'uvx',
+    python: tools?.pythonVersion?.trim() || process.env.MEDIA_TO_MD_PYTHON?.trim() || '3.12',
+  }
+}
+
+async function sha256OfFile(file: string): Promise<string> {
+  const hash = createHash('sha256')
+  await new Promise<void>((resolve, reject) => {
+    createReadStream(file)
+      .on('data', chunk => hash.update(chunk))
+      .on('error', reject)
+      .on('end', () => resolve())
+  })
+  return `sha256:${hash.digest('hex')}`
+}
+
+interface RenderedPages {
+  pages: Array<{ index: number; path: string; width?: number; height?: number }>
+  totalPages: number
+}
+
+async function renderPages(file: string, scratch: string, dpi: number, maxPages: number, tools?: MediaToolOptions, signal?: AbortSignal): Promise<RenderedPages & { uvxVersion?: string }> {
+  const { cmd, python } = uvxCommand(tools)
+  const outDir = join(scratch, 'pages')
+  await mkdir(outDir, { recursive: true })
+  let stdout: string
+  try {
+    ({ stdout } = await execFileAsync(cmd, [
+      '--python', python, '--with', 'pypdfium2', '--with', 'pillow', 'python', helperPath('pdf_pages.py'),
+      file, outDir, String(dpi), String(maxPages),
+    ], { maxBuffer: 32 * 1024 * 1024, ...(signal ? { signal } : {}) }))
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause)
+    if (/ENOENT/.test(detail)) {
+      throw new MediaToMarkdownError(
+        'DEPENDENCY_MISSING',
+        '扫描档需要 uvx(用于拉起 pypdfium2 渲染页图与 RapidOCR 识别),本机没有找到。',
+        UVX_HINT,
+      )
+    }
+    throw new MediaToMarkdownError('PDF_RENDER_FAILED', `页图渲染失败:${detail}`)
+  }
+  const payload = JSON.parse(stdout.trim().split('\n').filter(Boolean).pop() ?? '{}') as RenderedPages
+  // uvx 版本只在能力上报里用;这里顺手探测一次,失败不影响主流程
+  let uvxVersion: string | undefined
+  try {
+    const version = await execFileAsync(cmd, ['--version'])
+    uvxVersion = /(\d+\.\d+\.\d+)/.exec(version.stdout)?.[1]
+  } catch {
+    /* 可选 */
+  }
+  return { ...payload, ...(uvxVersion ? { uvxVersion } : {}) }
+}
+
+/** 纯图片页 PDF → 逐页 OCR 的 Markdown(轻量档)。 */
+export async function convertScannedDocument(options: ScannedPdfOptions): Promise<MediaToMarkdownResult> {
+  const file = options.file
+  const fileInfo = await stat(file).catch(() => undefined)
+  if (!fileInfo?.isFile()) throw new MediaToMarkdownError('INPUT_NOT_A_FILE', `输入不是文件:${file}`)
+  if (extname(file).toLowerCase() !== '.pdf') {
+    throw new MediaToMarkdownError('INPUT_NOT_PDF', `扫描档只处理 PDF,收到:${extname(file) || '(无扩展名)'}`)
+  }
+
+  const title = options.title?.trim() || basename(file, extname(file))
+  const dpi = Math.min(300, Math.max(72, options.dpi ?? 150))
+  const maxPages = Math.max(1, options.maxPages ?? 50)
+  const pageImages = options.pageImages !== false
+  const report = (stage: Parameters<NonNullable<ScannedPdfOptions['onProgress']>>[0]['stage'], progress: number | null, message?: string): void => {
+    options.onProgress?.({ stage, progress, ...(message ? { message } : {}) })
+  }
+  const warnings: MediaWarning[] = []
+  const scratch = await mkdtemp(join(tmpdir(), 'media-to-md-scan-'))
+
+  try {
+    report('probing', 0.05, '渲染 PDF 页图')
+    const rendered = await renderPages(file, scratch, dpi, maxPages, options.tools, options.signal)
+    if (rendered.totalPages > rendered.pages.length) {
+      warnings.push({
+        code: 'PAGE_LIMIT_REACHED',
+        message: `PDF 共 ${rendered.totalPages} 页,本次只渲染并识别前 ${rendered.pages.length} 页(上限 ${maxPages});调大 maxPages 可覆盖更多。`,
+      })
+    }
+    if (rendered.pages.length === 0) {
+      warnings.push({ code: 'NO_PAGES', message: '该 PDF 没有可渲染的页面。' })
+    }
+
+    report('ocr', 0.4, `本地 OCR(${rendered.pages.length} 页)`)
+    const ocr = await ocrImages(rendered.pages.map(page => page.path), options.tools, options.signal)
+    warnings.push(...ocr.warnings)
+    const byPath = new Map(ocr.entries.map(entry => [entry.path, entry]))
+
+    const pages: ScannedPage[] = []
+    const assets: MediaToMarkdownResult['assets'] = []
+    let emptyPages = 0
+    for (const page of rendered.pages) {
+      const rel = `assets/page-${String(page.index).padStart(4, '0')}.png`
+      const entry = byPath.get(page.path)
+      const text = (entry?.text ?? '').trim()
+      if (!text) emptyPages += 1
+      pages.push({
+        index: page.index,
+        rel,
+        ...(page.width ? { width: page.width } : {}),
+        ...(page.height ? { height: page.height } : {}),
+        text,
+        ocrLines: entry?.lines.length ?? 0,
+      })
+      if (pageImages) {
+        assets.push({ rel, data: await readFile(page.path), contentType: 'image/png' })
+      }
+    }
+    const identified = pages.filter(page => page.text).length
+    warnings.push({
+      code: 'SCANNED_OCR_LOCAL',
+      message: `扫描档走本地 OCR:${identified}/${pages.length} 页识别到文字(${dpi} DPI);不联网、不做版面还原。`,
+    })
+    if (emptyPages > 0) {
+      warnings.push({ code: 'OCR_EMPTY_PAGES', message: `有 ${emptyPages} 页没有识别到文字(可能是空白页、手写体或图片型内容)。` })
+    }
+    if (!pageImages) {
+      warnings.push({ code: 'PAGE_IMAGES_SKIPPED', message: 'pageImages=false:只保留文字,未落地页图。' })
+    }
+
+    report('assembling', 0.9, '装配 Markdown')
+    const meta = {
+      sourceFormat: 'pdf' as const,
+      containerExtension: 'pdf',
+      durationSeconds: 0,
+      sizeBytes: fileInfo.size,
+      hasVideo: false,
+      hasAudio: false,
+      hasSubtitleTrack: false,
+      transcriptSource: 'none' as const,
+    }
+    const dependencyVersions: Record<string, string> = { pypdfium2: 'via uvx', rapidocr: 'via uvx' }
+    if (rendered.uvxVersion) dependencyVersions.uvx = rendered.uvxVersion
+
+    return {
+      title: title.slice(0, 300),
+      markdown: buildScannedMarkdown({
+        title,
+        totalPages: rendered.totalPages,
+        pageImages,
+        pages: pages.map(page => ({ index: page.index, rel: page.rel, text: page.text })),
+      }),
+      assets,
+      meta,
+      transcript: { source: 'none', cues: [] },
+      warnings,
+      dependencyVersions,
+      externalId: await sha256OfFile(file),
+      pages,
+    }
+  } finally {
+    if (!options.keepScratch) await rm(scratch, { recursive: true, force: true }).catch(() => undefined)
+  }
+}

package/src/media/types.ts

@@ -0,0 +1,171 @@
+/**
+ * media-to-md 的公开契约。
+ *
+ * 这个包只做一件事:把一个**本地**音视频/图片文件变成「知识就绪 Markdown + 本地图片」。
+ * 它刻意不认识任何宿主(转换内核、CLI、未来的桌面端),宿主拿到的就是一个纯函数:
+ *
+ *   convertMedia(options) → { markdown, assets[], meta, transcript, warnings, … }
+ *
+ * 全程本地:不调用云端 API、不调用大模型。用到的两个**专用小模型**(语音识别 whisper、
+ * 画面文字 OCR)都是可选档位,且是否允许下载由调用方显式给出(`allowModelDownload`)。
+ */
+
+export type MediaSourceFormat = 'video' | 'audio' | 'image' | 'pdf'
+
+/** 解析档位。`auto` = 有字幕用字幕,没有才考虑转写(且必须允许下载模型)。 */
+export type MediaMode = 'auto' | 'subtitle-only' | 'transcribe' | 'frames-only'
+
+export interface MediaAsrOptions {
+  /** whisper 模型名(tiny/base/small/medium/large-v3/large-v3-turbo)。 */
+  model?: string
+  /** 语言代码(zh/en…);省略则自动检测。 */
+  language?: string
+  /** faster-whisper 设备与量化,默认 cpu/int8。 */
+  device?: string
+  computeType?: string
+  beamSize?: number
+  /**
+   * 是否允许下载模型。默认 **false**:
+   * 无字幕又没有本地模型时会抛 `ASR_MODEL_REQUIRED`,把「要下多大」摊在调用方面前。
+   */
+  allowModelDownload?: boolean
+}
+
+export interface MediaFrameOptions {
+  /** 均匀采样帧数(保证任何视频都有基础覆盖)。 */
+  samples?: number
+  /** 关键帧上限。 */
+  maxFrames?: number
+  /** 场景切换阈值(0–1);硬切/翻页会额外抽帧。 */
+  sceneThreshold?: number
+}
+
+export interface MediaToolOptions {
+  /** uvx 可执行文件;默认 `uvx`。 */
+  uvxPath?: string
+  /** uvx 使用的 Python 版本;默认 `3.12`。 */
+  pythonVersion?: string
+}
+
+export interface MediaToMarkdownOptions {
+  /** 本地文件绝对路径。 */
+  file: string
+  /** 产物标题;默认取文件名(去扩展名)。 */
+  title?: string
+  mode?: MediaMode
+  asr?: MediaAsrOptions
+  frames?: MediaFrameOptions
+  tools?: MediaToolOptions
+  /** 对**图片**输入开启本地 OCR;默认 false(issue 0013:图片直接收录、靠多模态召回)。 */
+  imageOcr?: boolean
+  /** 对视频**关键帧**做画面文字 OCR;默认 false。 */
+  ocrFrames?: boolean
+  /** 保留中间目录(排障用)。 */
+  keepScratch?: boolean
+  /** 取消信号。 */
+  signal?: AbortSignal
+  onProgress?: (progress: MediaToMarkdownProgress) => void
+}
+
+/**
+ * 轻量扫描档:纯图片页 PDF → 逐页本地 OCR。
+ *
+ * 刻意**不引入 docling / PaddlePaddle 框架**:它只解决"扫描件里的字读不出来",
+ * 版面顺序与表格结构不在这一档的承诺范围内(见 issues/0017 的可选高质量档)。
+ */
+export interface ScannedPdfOptions {
+  file: string
+  title?: string
+  /** 最多渲染并识别的页数(默认 50);超出会写 warning,不静默截断。 */
+  maxPages?: number
+  /** 渲染 DPI(默认 150);越高越准,也越慢越大。 */
+  dpi?: number
+  /** 是否把逐页图片作为 assets 落地(默认 true;false 时只保留文字)。 */
+  pageImages?: boolean
+  tools?: MediaToolOptions
+  keepScratch?: boolean
+  signal?: AbortSignal
+  onProgress?: (progress: MediaToMarkdownProgress) => void
+}
+
+/** 扫描档的页级结果。 */
+export interface ScannedPage {
+  index: number
+  /** 该页图片在产物里的相对路径(未落地图片时为 `page-NNNN.png` 的约定名)。 */
+  rel: string
+  width?: number
+  height?: number
+  text: string
+  ocrLines: number
+}
+
+export interface MediaToMarkdownProgress {
+  stage: 'probing' | 'frames' | 'subtitles' | 'transcribing' | 'ocr' | 'assembling'
+  /** 0–1,未知时为 null。 */
+  progress: number | null
+  message?: string
+}
+
+export interface MediaAsset {
+  /** 相对产物根的路径,**含 `assets/` 前缀**,可直接写进 Markdown。 */
+  rel: string
+  data: Buffer
+  contentType?: string
+}
+
+export interface MediaCue {
+  seconds: number
+  /** 结束时间(字幕/SRT 有;自动转写也有)。缺失时按下一条的开始时间处理。 */
+  endSeconds?: number
+  text: string
+}
+
+export interface MediaMeta {
+  sourceFormat: MediaSourceFormat
+  /** 容器/图片扩展名(不含点),例如 `mp4`、`png` —— 宿主用它拼 parser 标识。 */
+  containerExtension?: string
+  durationSeconds: number
+  sizeBytes: number
+  width?: number
+  height?: number
+  fps?: number
+  videoCodec?: string
+  audioCodec?: string
+  hasVideo: boolean
+  hasAudio: boolean
+  hasSubtitleTrack: boolean
+  /** 实际用到的字幕来源。 */
+  transcriptSource: 'subtitle' | 'transcription' | 'none'
+}
+
+export interface MediaWarning {
+  code: string
+  message: string
+}
+
+export interface MediaToMarkdownResult {
+  title: string
+  /** Markdown 正文;**不含 front matter**(front matter 是宿主的契约)。 */
+  markdown: string
+  assets: MediaAsset[]
+  meta: MediaMeta
+  transcript: { source: MediaMeta['transcriptSource']; cues: MediaCue[] }
+  warnings: MediaWarning[]
+  dependencyVersions: Record<string, string>
+  /** 文件内容 hash(sha256:…),给宿主做幂等。 */
+  externalId: string
+  /** 扫描档才有:逐页文本与图片。 */
+  pages?: ScannedPage[]
+}
+
+/** 带可操作建议的错误:宿主(内核/CLI)应当原样展示 `code` 与 `suggestion`。 */export class MediaToMarkdownError extends Error {
+  readonly code: string
+  readonly suggestion?: string
+
+  constructor(code: string, message: string, suggestion?: string) {
+    super(message)
+    this.name = 'MediaToMarkdownError'
+    this.code = code
+    if (suggestion !== undefined) this.suggestion = suggestion
+  }
+}

package/src/server.ts

@@ -0,0 +1,85 @@
+/**
+ * Public entry point of the conversion kernel.
+ *
+ * Two integration shapes, one implementation:
+ *   const service = await createConvertService({ rootDir })
+ *   const server  = await startConvertServer({ port: 8787 })      // standalone
+ *   const handler = createRequestHandler({ service, basePath })    // embedded
+ */
+
+import { createServer, type Server } from 'node:http'
+import { createRequestHandler, type HandlerOptions } from './http.js'
+import { ConvertService, defaultConvertRoot, type ConvertServiceOptions } from './service.js'
+
+export * from './contract.js'
+export * from './service.js'
+export * from './delivery.js'
+export * from './adapters/index.js'
+export * from './adapters/types.js'
+export { createRequestHandler, type HandlerOptions } from './http.js'
+
+export interface CreateServiceOptions extends ConvertServiceOptions {}
+
+export async function createConvertService(options: CreateServiceOptions = {}): Promise<ConvertService> {
+  const service = new ConvertService({ rootDir: options.rootDir ?? defaultConvertRoot(), ...options })
+  await service.start()
+  return service
+}
+
+export interface StartServerOptions extends CreateServiceOptions {
+  port?: number
+  host?: string
+  basePath?: string
+  webRoot?: string
+  apiKey?: string
+}
+
+export interface RunningConvertServer {
+  service: ConvertService
+  server: Server
+  url: string
+  close: () => Promise<void>
+}
+
+/** Start the kernel standalone — the console is at `url`, the API under `url/api`. */
+export async function startConvertServer(options: StartServerOptions = {}): Promise<RunningConvertServer> {
+  const service = await createConvertService(options)
+  const handlerOptions: HandlerOptions = {
+    service,
+    basePath: options.basePath ?? '',
+    ...(options.webRoot ? { webRoot: options.webRoot } : {}),
+    ...(options.apiKey ? { apiKey: options.apiKey } : {}),
+  }
+  const handler = createRequestHandler(handlerOptions)
+  const server = createServer((req, res) => {
+    void handler(req, res).catch(() => {
+      if (!res.headersSent) {
+        res.statusCode = 500
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+      }
+      res.end(JSON.stringify({ ok: false, error: { code: 'INTERNAL_ERROR', message: '未捕获的服务端错误' } }))
+    })
+  })
+
+  const port = options.port ?? 8787
+  const host = options.host ?? '127.0.0.1'
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(port, host, () => {
+      server.off('error', reject)
+      resolve()
+    })
+  })
+  const address = server.address()
+  const actualPort = typeof address === 'object' && address ? address.port : port
+  const basePath = (options.basePath ?? '').replace(/\/+$/, '')
+  return {
+    service,
+    server,
+    url: `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${actualPort}${basePath}`,
+    close: async () => {
+      await service.close()
+      await new Promise<void>(resolve => server.close(() => resolve()))
+    },
+  }
+}