dsh-convert-core 0.1.0-alpha.1

package/src/http.ts

@@ -0,0 +1,394 @@
+/**
+ * Transport for the kernel: a plain `node:http` handler.
+ *
+ * It is mounted three ways — standalone (`bin/tita-convert.mjs`), inside the
+ * DSH web server (`/convert/*`), and from tests — which is exactly why the
+ * kernel owns a handler instead of a server.
+ */
+
+import { readFile } from 'node:fs/promises'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { extname, normalize, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { AdapterError } from './adapters/types.js'
+import type { ConvertRequest, ConvertTask } from './contract.js'
+import { ConvertService, contentTypeOf } from './service.js'
+
+export interface HandlerOptions {
+  service: ConvertService
+  /** Path prefix the handler answers on, e.g. `/convert`. Empty means `/`. */
+  basePath?: string
+  /** Directory holding the Vue console. Resolved relative to this module by default. */
+  webRoot?: string
+  /** Unauthenticated-local default; when set, every /api call must present it. */
+  apiKey?: string
+}
+
+const MAX_BODY_BYTES = 512 * 1024 * 1024
+
+export function defaultWebRoot(): string {
+  return resolve(fileURLToPath(new URL('../web/', import.meta.url)))
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body)
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(payload)
+}
+
+function sendError(res: ServerResponse, status: number, error: AdapterError | Error): void {
+  const code = error instanceof AdapterError ? error.code : 'INTERNAL_ERROR'
+  const suggestion = error instanceof AdapterError ? error.suggestion : undefined
+  sendJson(res, status, {
+    ok: false,
+    error: { code, message: error.message, ...(suggestion ? { suggestion } : {}) },
+  })
+}
+
+function ok<T>(data: T): { ok: true; data: T } {
+  return { ok: true, data }
+}
+
+async function readBody(req: IncomingMessage, limit = MAX_BODY_BYTES): Promise<Buffer> {
+  const chunks: Buffer[] = []
+  let bytes = 0
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))
+    bytes += buffer.length
+    if (bytes > limit) throw new AdapterError('REQUEST_TOO_LARGE', `请求体超过上限 ${limit} 字节。`)
+    chunks.push(buffer)
+  }
+  return Buffer.concat(chunks)
+}
+
+interface MultipartPart {
+  name: string
+  filename?: string
+  contentType?: string
+  data: Buffer
+}
+
+/** Minimal multipart/form-data reader: no dependency, no streaming, no surprises. */
+export function parseMultipart(body: Buffer, boundary: string): MultipartPart[] {
+  const delimiter = Buffer.from(`--${boundary}`)
+  const parts: MultipartPart[] = []
+  let index = body.indexOf(delimiter)
+  while (index >= 0) {
+    const start = index + delimiter.length
+    if (body.subarray(start, start + 2).toString() === '--') break
+    const headerEnd = body.indexOf('\r\n\r\n', start)
+    if (headerEnd < 0) break
+    const rawHeaders = body.subarray(start, headerEnd).toString('utf8')
+    const next = body.indexOf(delimiter, headerEnd)
+    if (next < 0) break
+    const content = body.subarray(headerEnd + 4, next - 2)
+    const name = /name="([^"]*)"/.exec(rawHeaders)?.[1] ?? ''
+    const filename = /filename="([^"]*)"/.exec(rawHeaders)?.[1]
+    const contentType = /content-type:\s*([^\r\n]+)/i.exec(rawHeaders)?.[1]?.trim()
+    parts.push({
+      name,
+      data: content,
+      ...(filename ? { filename } : {}),
+      ...(contentType ? { contentType } : {}),
+    })
+    index = next
+  }
+  return parts
+}
+
+function taskSummary(task: ConvertTask): Record<string, unknown> {
+  return {
+    id: task.id,
+    state: task.state,
+    inputKind: task.inputKind,
+    label: task.label,
+    sourceFormat: task.sourceFormat,
+    createdAt: task.createdAt,
+    updatedAt: task.updatedAt,
+    startedAt: task.startedAt,
+    finishedAt: task.finishedAt,
+    progress: task.progress,
+    stage: task.stage,
+    message: task.message,
+    error: task.error,
+    warnings: task.warnings,
+    attempts: task.attempts,
+    deliveryDir: task.deliveryDir,
+    assetCount: task.manifest?.assets.length ?? 0,
+    wordCount: task.manifest?.wordCount ?? 0,
+    parser: task.manifest?.parser,
+    contentHash: task.manifest?.contentHash,
+    externalId: task.manifest?.externalId,
+    title: task.manifest?.title ?? task.label,
+  }
+}
+
+/** Full task view, including the ingest payload the DSH layer forwards. */
+function taskDetail(task: ConvertTask): Record<string, unknown> {
+  return {
+    ...taskSummary(task),
+    manifest: task.manifest ?? null,
+    ingest: task.manifest?.ingest ?? null,
+    request: { ...task.request, text: task.request.text ? `${task.request.text.slice(0, 400)}…` : undefined },
+  }
+}
+
+function requestFromQuery(url: URL): ConvertRequest {
+  const kind = (url.searchParams.get('kind') ?? 'file') as ConvertRequest['kind']
+  const request: ConvertRequest = { kind }
+  const set = (key: keyof ConvertRequest, value: string | null): void => {
+    if (value === null || value === '') return
+    ;(request as unknown as Record<string, unknown>)[key] = value
+  }
+  set('title', url.searchParams.get('title'))
+  set('sourceType', url.searchParams.get('source_type'))
+  set('externalId', url.searchParams.get('external_id'))
+  set('adapter', url.searchParams.get('adapter'))
+  return request
+}
+
+export function createRequestHandler(options: HandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+  const { service } = options
+  const basePath = (options.basePath ?? '').replace(/\/+$/, '')
+  const webRoot = options.webRoot ?? defaultWebRoot()
+
+  const serveStatic = async (res: ServerResponse, relative: string): Promise<boolean> => {
+    const target = resolve(webRoot, normalize(relative).replace(/^([/\\])+/, ''))
+    if (target !== webRoot && !target.startsWith(webRoot + sep)) return false
+    try {
+      let data = await readFile(target)
+      // The console is served under an arbitrary prefix (standalone at `/`,
+      // inside DSH at `/convert`), so asset URLs are resolved at serve time.
+      if (relative === 'index.html') {
+        data = Buffer.from(data.toString('utf8').replaceAll('__CONVERT_BASE__', basePath), 'utf8')
+      }
+      res.statusCode = 200
+      res.setHeader('content-type', contentTypeOf(target) === 'application/octet-stream' ? guessWebType(target) : contentTypeOf(target))
+      res.setHeader('cache-control', 'no-cache')
+      res.end(data)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  return async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+    let pathname = url.pathname
+    if (basePath) {
+      if (pathname === basePath) pathname = '/'
+      else if (pathname.startsWith(`${basePath}/`)) pathname = pathname.slice(basePath.length)
+      else {
+        sendJson(res, 404, { ok: false, error: { code: 'NOT_FOUND', message: `未挂载在 ${basePath} 下` } })
+        return
+      }
+    }
+
+    try {
+      if (options.apiKey && pathname.startsWith('/api/') && req.headers['x-api-key'] !== options.apiKey) {
+        sendJson(res, 401, { ok: false, error: { code: 'UNAUTHORIZED', message: '缺少或错误的 X-Api-Key。' } })
+        return
+      }
+
+      // ---- console ---------------------------------------------------------
+      if (req.method === 'GET' && (pathname === '/' || pathname === '/index.html')) {
+        if (await serveStatic(res, 'index.html')) return
+        sendJson(res, 500, { ok: false, error: { code: 'CONSOLE_MISSING', message: `未找到内核控制台页面（${webRoot}）。请先执行 pnpm build。` } })
+        return
+      }
+      if (req.method === 'GET' && /^\/(app\.js|styles\.css|vendor\/[\w.-]+)$/.test(pathname)) {
+        if (await serveStatic(res, pathname.slice(1))) return
+        sendJson(res, 404, { ok: false, error: { code: 'NOT_FOUND', message: pathname } })
+        return
+      }
+
+      // ---- health & capabilities -------------------------------------------
+      if (req.method === 'GET' && pathname === '/api/health') {
+        sendJson(res, 200, ok({
+          service: 'dsh-convert-core',
+          version: '0.1.0',
+          rootDir: service.rootDir,
+          outDir: service.outDir,
+          tasks: service.list().length,
+        }))
+        return
+      }
+      if (req.method === 'GET' && pathname === '/api/capabilities') {
+        sendJson(res, 200, ok(await service.capabilities()))
+        return
+      }
+
+      // ---- server-sent events ----------------------------------------------
+      if (req.method === 'GET' && pathname === '/api/events') {
+        res.statusCode = 200
+        res.setHeader('content-type', 'text/event-stream; charset=utf-8')
+        res.setHeader('cache-control', 'no-cache')
+        res.setHeader('connection', 'keep-alive')
+        res.write(`event: hello\ndata: ${JSON.stringify({ tasks: service.list().map(taskSummary) })}\n\n`)
+        const unsubscribe = service.subscribe(task => {
+          res.write(`event: task\ndata: ${JSON.stringify(taskSummary(task))}\n\n`)
+        })
+        const heartbeat = setInterval(() => { res.write(': ping\n\n') }, 20_000)
+        req.on('close', () => {
+          clearInterval(heartbeat)
+          unsubscribe()
+        })
+        return
+      }
+
+      // ---- tasks ------------------------------------------------------------
+      if (pathname === '/api/tasks' && req.method === 'GET') {
+        sendJson(res, 200, ok({ tasks: service.list().map(taskSummary) }))
+        return
+      }
+
+      if (pathname === '/api/tasks' && req.method === 'POST') {
+        const task = await createTask(service, req, url)
+        sendJson(res, 202, ok(taskDetail(task)))
+        return
+      }
+
+      const taskMatch = /^\/api\/tasks\/([^/]+)(\/.*)?$/.exec(pathname)
+      if (taskMatch) {
+        const id = decodeURIComponent(taskMatch[1]!)
+        const rest = taskMatch[2] ?? ''
+        if (rest === '' && req.method === 'GET') {
+          const task = service.get(id)
+          if (!task) throw new AdapterError('TASK_NOT_FOUND', `任务不存在：${id}`)
+          sendJson(res, 200, ok(taskDetail(task)))
+          return
+        }
+        if (rest === '/cancel' && req.method === 'POST') {
+          sendJson(res, 200, ok(taskSummary(service.cancel(id))))
+          return
+        }
+        if (rest === '/retry' && req.method === 'POST') {
+          sendJson(res, 200, ok(taskSummary(await service.retry(id))))
+          return
+        }
+        if (rest === '/ingest' && req.method === 'GET') {
+          sendJson(res, 200, ok(await service.ingestPlan(id)))
+          return
+        }
+        if (rest === '/markdown' && req.method === 'GET') {
+          const file = await service.readDeliveryFile(id, 'index.md')
+          if (!file) throw new AdapterError('ARTIFACT_NOT_FOUND', '任务没有 index.md（可能未成功或已被清理）。')
+          res.statusCode = 200
+          res.setHeader('content-type', 'text/markdown; charset=utf-8')
+          res.end(file.data)
+          return
+        }
+        if (rest.startsWith('/files/') && req.method === 'GET') {
+          const relative = decodeURIComponent(rest.slice('/files/'.length))
+          const file = await service.readDeliveryFile(id, relative)
+          if (!file) throw new AdapterError('ARTIFACT_NOT_FOUND', `交付目录里没有该文件：${relative}`)
+          res.statusCode = 200
+          res.setHeader('content-type', file.contentType)
+          res.setHeader('cache-control', 'no-store')
+          res.end(file.data)
+          return
+        }
+        sendJson(res, 405, { ok: false, error: { code: 'METHOD_NOT_ALLOWED', message: `${req.method} ${pathname}` } })
+        return
+      }
+
+      sendJson(res, 404, { ok: false, error: { code: 'NOT_FOUND', message: pathname } })
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause))
+      const status = error instanceof AdapterError
+        ? error.code === 'TASK_NOT_FOUND' || error.code === 'ARTIFACT_NOT_FOUND' ? 404
+          : error.code === 'REQUEST_TOO_LARGE' || error.code === 'INPUT_TOO_LARGE' ? 413
+            : error.code === 'REQUEST_INVALID' || error.code === 'CONTENT_REQUIRED' || error.code === 'URL_REQUIRED' ? 400
+              : 409
+        : 500
+      sendError(res, status, error)
+    }
+  }
+}
+
+async function createTask(service: ConvertService, req: IncomingMessage, url: URL): Promise<ConvertTask> {
+  // Keep the raw header: a multipart boundary is case-sensitive, so lowercasing
+  // the whole content type silently breaks every upload.
+  const rawContentType = req.headers['content-type'] ?? ''
+  const contentType = rawContentType.toLowerCase()
+
+  if (contentType.startsWith('application/json')) {
+    const body = JSON.parse((await readBody(req)).toString('utf8')) as Record<string, unknown>
+    const request: ConvertRequest = {
+      kind: (body.kind as ConvertRequest['kind']) ?? 'text',
+      ...(typeof body.text === 'string' ? { text: body.text } : {}),
+      ...(typeof body.title === 'string' ? { title: body.title } : {}),
+      ...(typeof body.source_type === 'string' ? { sourceType: body.source_type } : {}),
+      ...(typeof body.adapter === 'string' ? { adapter: body.adapter } : {}),
+      ...(typeof body.local_path === 'string' && body.local_path.trim() ? { localPath: body.local_path.trim() } : {}),
+      ...(typeof body.external_id === 'string' ? { externalId: body.external_id } : {}),
+      ...(Array.isArray(body.source_type_candidates) ? { sourceTypeCandidates: body.source_type_candidates.map(String) } : {}),
+      ...(body.lineage && typeof body.lineage === 'object' ? { lineage: body.lineage as ConvertRequest['lineage'] } : {}),
+    }
+    if (typeof body.local_path === 'string' && body.local_path.trim()) {
+      return await service.submit({ ...request, kind: 'file' }, {
+        ...(typeof body.filename === 'string' ? { filename: body.filename } : {}),
+      })
+    }
+    if (typeof body.data === 'string' && body.data.length > 0) {
+      const data = Buffer.from(body.data, 'base64')
+      return await service.submit({ ...request, kind: request.kind ?? 'file' }, { data, ...(typeof body.filename === 'string' ? { filename: body.filename } : {}) })
+    }
+    return await service.submit(request)
+  }
+
+  const request = requestFromQuery(url)
+
+  if (contentType.startsWith('multipart/form-data')) {
+    const boundaryMatch = /boundary=(?:"([^"]+)"|([^;]+))/i.exec(rawContentType)
+    const boundary = (boundaryMatch?.[1] ?? boundaryMatch?.[2])?.trim()
+    if (!boundary) throw new AdapterError('REQUEST_INVALID', 'multipart 请求缺少 boundary。')
+    const parts = parseMultipart(await readBody(req), boundary)
+    const file = parts.find(part => part.filename)
+    for (const part of parts) {
+      if (part.filename) continue
+      const value = part.data.toString('utf8')
+      if (part.name === 'kind') request.kind = value as ConvertRequest['kind']
+      else if (part.name === 'title') request.title = value
+      else if (part.name === 'source_type') request.sourceType = value
+      else if (part.name === 'adapter') request.adapter = value
+      else if (part.name === 'text') request.text = value
+      else if (part.name === 'external_id') request.externalId = value
+    }
+    if (!file) {
+      if (request.kind === 'text' && request.text) return await service.submit(request)
+      throw new AdapterError('INPUT_REQUIRED', 'multipart 请求没有文件部件。')
+    }
+    return await service.submit(request, { data: file.data, filename: file.filename ?? 'upload.bin' })
+  }
+
+  // Raw body upload: the whole request body is the file.
+  const filename = url.searchParams.get('filename') ?? dispositionFilename(req.headers['content-disposition']) ?? 'upload.bin'
+  const data = await readBody(req)
+  if (data.length === 0) {
+    if (request.kind === 'text') return await service.submit(request)
+    throw new AdapterError('INPUT_REQUIRED', '请求体为空。')
+  }
+  return await service.submit({ ...request, kind: 'file' }, { data, filename })
+}
+
+function dispositionFilename(header: string | undefined): string | undefined {
+  if (!header) return undefined
+  const match = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(header)
+  return match ? decodeURIComponent(match[1]!) : undefined
+}
+
+function guessWebType(path: string): string {
+  switch (extname(path).toLowerCase()) {
+    case '.html': return 'text/html; charset=utf-8'
+    case '.js': return 'text/javascript; charset=utf-8'
+    case '.css': return 'text/css; charset=utf-8'
+    case '.svg': return 'image/svg+xml'
+    case '.json': return 'application/json; charset=utf-8'
+    default: return 'application/octet-stream'
+  }
+}
+
+export { taskSummary, taskDetail }

package/src/markdown.ts

@@ -0,0 +1,141 @@
+/**
+ * Markdown / front matter helpers.
+ *
+ * The serialization below is byte-compatible with the reader inside
+ * `plugins/dsh-data-domain-knowledge/src/runtime.ts` (`parseMarkdown`): one
+ * `key: value` line per field, strings raw, everything else JSON-encoded, and
+ * `yamlValue()` on the reading side un-quotes plain strings and JSON-parses
+ * `{...}` / `[...]` shapes.
+ */
+
+import { createHash } from 'node:crypto'
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/** Same shape the knowledge plugin accepts for identifiers. */
+export const SAFE_ID = /^[a-zA-Z0-9._:-]{1,160}$/
+
+export function sha256(value: string | Buffer): string {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+export function sha1(value: string | Buffer): string {
+  return createHash('sha1').update(value).digest('hex')
+}
+
+export function shortHash(value: string | Buffer, length = 24): string {
+  return sha256(value).slice(0, length)
+}
+
+/** Mirrors the knowledge plugin slugger so paths look the same on both sides. */
+export function slug(value: string, fallback = 'item'): string {
+  const normalized = value
+    .trim()
+    .replace(/[^\p{L}\p{N}._-]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+  return normalized.slice(0, 120) || `${fallback}-${Date.now().toString(36)}`
+}
+
+export function serializeFrontMatter(frontmatter: Record<string, unknown>): string {
+  const lines: string[] = []
+  for (const [key, value] of Object.entries(frontmatter)) {
+    if (value === undefined || value === null) continue
+    if (Array.isArray(value) && value.length === 0) continue
+    if (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0) continue
+    // A raw newline would break the line-based reader on the knowledge side.
+    const encoded = typeof value === 'string' ? value.replace(/\r?\n/g, ' ') : JSON.stringify(value)
+    if (encoded.length === 0) continue
+    lines.push(`${key}: ${encoded}`)
+  }
+  return `---\n${lines.join('\n')}\n---`
+}
+
+export function toMarkdownDocument(frontmatter: Record<string, unknown>, content: string): string {
+  return `${serializeFrontMatter(frontmatter)}\n\n${content.trim()}\n`
+}
+
+export function parseMarkdownDocument(source: string): { frontmatter: Record<string, unknown>; content: string } {
+  if (!source.startsWith('---')) return { frontmatter: {}, content: source.trim() }
+  const end = source.indexOf('\n---', 3)
+  if (end < 0) return { frontmatter: {}, content: source.trim() }
+  const header = source.slice(3, end).replace(/^\n/, '')
+  const frontmatter: Record<string, unknown> = {}
+  for (const line of header.split(/\r?\n/)) {
+    const separator = line.indexOf(':')
+    if (separator <= 0) continue
+    const key = line.slice(0, separator).trim()
+    frontmatter[key] = yamlValue(line.slice(separator + 1))
+  }
+  return { frontmatter, content: source.slice(end + 4).trim() }
+}
+
+function yamlValue(value: string): unknown {
+  const text = value.trim()
+  if (text === 'true') return true
+  if (text === 'false') return false
+  if (text === 'null') return null
+  if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text)
+  if ((text.startsWith('[') && text.endsWith(']')) || (text.startsWith('{') && text.endsWith('}'))) {
+    try {
+      return JSON.parse(text)
+    } catch {
+      /* keep the raw string */
+    }
+  }
+  return text.replace(/^['"]|['"]$/g, '')
+}
+
+/**
+ * Local image references in a Markdown body, resolved against `baseDir`.
+ * Same regex and same skip rules as the knowledge plugin, so the kernel can
+ * predict exactly what will reach the multimodal embedder.
+ */
+export function localImagePaths(content: string, baseDir: string): string[] {
+  const pattern = /!\[[^\]]*\]\(\s*(?:<([^>]+)>|([^\s)]+))/g
+  const found: string[] = []
+  for (const match of content.matchAll(pattern)) {
+    const raw = (match[1] ?? match[2] ?? '').trim()
+    if (!raw || raw.startsWith('data:') || /^https?:\/\//i.test(raw) || raw.startsWith('#')) continue
+    found.push(raw)
+  }
+  return [...new Set(found)]
+}
+
+export function wordCount(value: string): number {
+  const cjk = (value.match(/[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/g) ?? []).length
+  const latin = value
+    .replace(/[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/g, ' ')
+    .split(/\s+/)
+    .filter(Boolean).length
+  return cjk + latin
+}
+
+export async function writeTextAtomic(path: string, content: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
+  try {
+    await writeFile(temporary, content, 'utf8')
+    await rename(temporary, path)
+  } finally {
+    try {
+      await unlink(temporary)
+    } catch {
+      /* rename consumed it */
+    }
+  }
+}
+
+export async function writeBufferAtomic(path: string, content: Buffer): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
+  try {
+    await writeFile(temporary, content)
+    await rename(temporary, path)
+  } finally {
+    try {
+      await unlink(temporary)
+    } catch {
+      /* rename consumed it */
+    }
+  }
+}

package/src/media/binaries.ts

@@ -0,0 +1,67 @@
+/**
+ * 外部二进制探测。
+ *
+ * 这个包与文档类转换器的根本差别就在这里:它需要 `ffmpeg`/`ffprobe`,转写档还需要
+ * `uvx`(用来按需拉起 faster-whisper / RapidOCR)。探测结果既用于 `probe()`(宿主上报能力),
+ * 也用于错误信息里给出**可操作**的安装命令 —— 缺依赖要吵,但不能静默降级。
+ */
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+export interface ToolVersions {
+  ffmpeg?: string
+  ffprobe?: string
+  uvx?: string
+}
+
+export const FFMPEG_HINT = '装 ffmpeg(含 ffprobe):macOS `brew install ffmpeg`,Debian/Ubuntu `apt install ffmpeg`。'
+export const UVX_HINT = '安装 uv(内含 uvx):`curl -LsSf https://astral.sh/uv/install.sh | sh`;或用 tools.uvxPath 指向已有的 uvx。'
+
+export interface ProbeOptions {
+  uvxPath?: string
+}
+
+/** 每次都真跑一次 `-version`;调用方(宿主)自己缓存,别在这里藏状态。 */
+export async function probeTools(options: ProbeOptions = {}): Promise<ToolVersions> {
+  const versions: ToolVersions = {}
+  try {
+    const { stdout } = await execFileAsync('ffprobe', ['-version'])
+    const found = /ffprobe version (\S+)/.exec(stdout)?.[1]
+    if (found) versions.ffprobe = found
+  } catch {
+    /* 缺失由调用方汇报 */
+  }
+  try {
+    const { stdout } = await execFileAsync('ffmpeg', ['-version'])
+    const found = /ffmpeg version (\S+)/.exec(stdout)?.[1]
+    if (found) versions.ffmpeg = found
+  } catch {
+    /* 缺失由调用方汇报 */
+  }
+  try {
+    const uvx = options.uvxPath?.trim() || process.env.MEDIA_TO_MD_UVX?.trim() || 'uvx'
+    const { stdout } = await execFileAsync(uvx, ['--version'])
+    // `uvx --version` 形如 `uvx 0.11.6 (65950801c 2026-04-09 aarch64-apple-darwin)`,只取版本号。
+    const found = /(\d+\.\d+\.\d+)/.exec(stdout)?.[1]
+    if (found) versions.uvx = found
+  } catch {
+    /* 可选依赖:只有转写/OCR 档才要求 */
+  }
+  return versions
+}
+
+export async function runFfmpeg(args: string[], options: { allowFailure?: boolean } = {}): Promise<{ stdout: string; stderr: string }> {
+  try {
+    const { stdout, stderr } = await execFileAsync('ffmpeg', args, { maxBuffer: 32 * 1024 * 1024 })
+    return { stdout, stderr }
+  } catch (cause) {
+    if (options.allowFailure) {
+      const error = cause as { stdout?: string; stderr?: string }
+      return { stdout: error.stdout ?? '', stderr: error.stderr ?? '' }
+    }
+    throw cause
+  }
+}