dsh-convert-core 0.1.0-alpha.1

package/src/adapters/iddoc.ts

@@ -0,0 +1,171 @@
+/**
+ * iddoc —— 音视频 / 图片 adapter(issue 0017 的 video 档)。
+ *
+ * 这个文件**只做契约映射**:能力全在同包的 `src/media/` 里(纯本地管线:
+ * ffmpeg 抽帧 + 可选的字幕/转写 + 可选的画面 OCR),这里负责
+ *
+ *   1. 把内核的 `AdapterContext` 翻译成该包的 options(**含 env 旋钮**);
+ *   2. 把 `MediaToMarkdownResult` 映射成 `AdapterOutput`(assets 交给内核写盘);
+ *   3. 把它抛出的错误原样转成 `AdapterError`,保留 `code` 与可操作建议。
+ *
+ * 与文档档(anydoc)一样:引擎独立于 adapter,内核只管契约。
+ *
+ * 环境变量(都是**显式**开关,默认不下载模型、不对图片做 OCR):
+ *   IDDOC_ASR=1              允许在无字幕时下载模型并本地转写
+ *   IDDOC_ASR_MODEL          whisper 模型(默认 small;中文建议 large-v3-turbo)
+ *   IDDOC_ASR_LANG           语言代码(默认自动检测;中文建议 zh)
+ *   IDDOC_OCR_FRAMES=1       对关键帧做画面文字 OCR
+ *   IDDOC_IMAGE_OCR=1        对图片输入做 OCR(默认关闭:图片直接收录)
+ *   IDDOC_UVX / IDDOC_PYTHON 自定义 uvx 与 Python 版本
+ *   IDDOC_SAMPLES / IDDOC_MAX_FRAMES / IDDOC_SCENE  抽帧参数
+ */
+
+import { stat } from 'node:fs/promises'
+import {
+  IMAGE_EXTENSIONS,
+  MediaToMarkdownError,
+  convertMedia,
+  probeTools,
+  type MediaAsset,
+  type MediaToMarkdownOptions,
+} from '../media/index.js'
+import type { ConvertWarning } from '../contract.js'
+import { AdapterError, type Adapter, type AdapterAvailability, type AdapterContext, type AdapterOutput, type PreparedAsset } from './types.js'
+
+export const IDDOC_VIDEO_EXTENSIONS = [
+  '.mp4', '.m4v', '.mov', '.mkv', '.webm', '.avi', '.flv', '.wmv', '.mpg', '.mpeg', '.ogv',
+]
+export const IDDOC_AUDIO_EXTENSIONS = [
+  '.mp3', '.m4a', '.wav', '.aac', '.flac', '.ogg', '.opus', '.aiff', '.aif', '.amr', '.wma',
+]
+export const IDDOC_IMAGE_EXTENSIONS = IMAGE_EXTENSIONS
+export const IDDOC_EXTENSIONS = [...IDDOC_VIDEO_EXTENSIONS, ...IDDOC_AUDIO_EXTENSIONS, ...IDDOC_IMAGE_EXTENSIONS]
+
+const INSTALL_HINT = '装 ffmpeg(含 ffprobe)后重试:macOS `brew install ffmpeg`,Debian/Ubuntu `apt install ffmpeg`。'
+
+function envFlag(name: string): boolean {
+  const value = (process.env[name] ?? '').trim().toLowerCase()
+  return value === '1' || value === 'true' || value === 'yes' || value === 'on'
+}
+
+function envInt(name: string): number | undefined {
+  const parsed = Number.parseInt((process.env[name] ?? '').trim(), 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined
+}
+
+function envFloat(name: string): number | undefined {
+  const parsed = Number.parseFloat((process.env[name] ?? '').trim())
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : undefined
+}
+
+/** 路由用的廉价同步检查;真正的探测在 probe() 与首次使用时。 */
+function availabilitySync(): AdapterAvailability {
+  return { available: true }
+}
+
+async function probeAvailability(): Promise<AdapterAvailability> {
+  const versions = await probeTools({ ...(process.env.IDDOC_UVX ? { uvxPath: process.env.IDDOC_UVX } : {}) })
+  if (!versions.ffprobe || !versions.ffmpeg) {
+    const missing = [!versions.ffprobe ? 'ffprobe' : null, !versions.ffmpeg ? 'ffmpeg' : null].filter(Boolean).join('、')
+    return { available: false, reason: `缺少外部二进制:${missing}`, suggestion: INSTALL_HINT }
+  }
+  const reported: Record<string, string> = {}
+  if (versions.ffmpeg) reported.ffmpeg = versions.ffmpeg
+  if (versions.ffprobe) reported.ffprobe = versions.ffprobe
+  if (versions.uvx) reported.uvx = versions.uvx
+  return { available: true, versions: reported }
+}
+
+function toOptions(context: AdapterContext, file: string): MediaToMarkdownOptions {
+  const model = (process.env.IDDOC_ASR_MODEL ?? '').trim() || 'small'
+  const language = (process.env.IDDOC_ASR_LANG ?? '').trim()
+  const frames = {
+    ...(envInt('IDDOC_SAMPLES') ? { samples: envInt('IDDOC_SAMPLES') } : {}),
+    ...(envInt('IDDOC_MAX_FRAMES') ? { maxFrames: envInt('IDDOC_MAX_FRAMES') } : {}),
+    ...(envFloat('IDDOC_SCENE') !== undefined ? { sceneThreshold: envFloat('IDDOC_SCENE') } : {}),
+  }
+  const tools = {
+    ...(process.env.IDDOC_UVX?.trim() ? { uvxPath: process.env.IDDOC_UVX.trim() } : {}),
+    ...(process.env.IDDOC_PYTHON?.trim() ? { pythonVersion: process.env.IDDOC_PYTHON.trim() } : {}),
+  }
+  return {
+    file,
+    ...(context.request.title?.trim() ? { title: context.request.title.trim() } : {}),
+    mode: 'auto',
+    asr: {
+      model,
+      ...(language ? { language } : {}),
+      allowModelDownload: envFlag('IDDOC_ASR'),
+    },
+    ...(Object.keys(frames).length > 0 ? { frames } : {}),
+    ...(Object.keys(tools).length > 0 ? { tools } : {}),
+    ...(envFlag('IDDOC_IMAGE_OCR') ? { imageOcr: true } : {}),
+    ...(envFlag('IDDOC_OCR_FRAMES') ? { ocrFrames: true } : {}),
+    ...(context.signal ? { signal: context.signal } : {}),
+    onProgress: progress => context.report(progress.progress, progress.stage, progress.message),
+  }
+}
+
+function toPreparedAssets(assets: MediaAsset[]): PreparedAsset[] {
+  return assets.map(asset => ({
+    rel: asset.rel,
+    data: asset.data,
+    ...(asset.contentType ? { contentType: asset.contentType } : {}),
+  }))
+}
+
+async function run(context: AdapterContext): Promise<AdapterOutput> {
+  if (!context.inputPath) {
+    throw new AdapterError('INPUT_REQUIRED', 'iddoc 只处理本地文件(kind=file):音频、视频或图片。')
+  }
+  const file = context.inputPath
+  const fileInfo = await stat(file).catch(() => undefined)
+  if (!fileInfo?.isFile()) throw new AdapterError('INPUT_NOT_A_FILE', `输入不是文件:${file}`)
+
+  const versions = await probeTools({ ...(process.env.IDDOC_UVX ? { uvxPath: process.env.IDDOC_UVX } : {}) })
+  if (!versions.ffprobe || !versions.ffmpeg) {
+    throw new AdapterError('DEPENDENCY_MISSING', 'iddoc 需要 ffmpeg 与 ffprobe。', INSTALL_HINT)
+  }
+
+  let result
+  try {
+    result = await convertMedia(toOptions(context, file))
+  } catch (cause) {
+    if (cause instanceof MediaToMarkdownError) {
+      throw new AdapterError(cause.code, cause.message, cause.suggestion)
+    }
+    throw new AdapterError('ADAPTER_FAILED', cause instanceof Error ? cause.message : String(cause))
+  }
+
+  const warnings: ConvertWarning[] = result.warnings.map(warning => ({ code: warning.code, message: warning.message }))
+  const suffix = result.meta.transcriptSource === 'subtitle'
+    ? '+subtitle'
+    : result.meta.transcriptSource === 'transcription' ? '+asr' : ''
+  // 文档类按格式命名(pdf/office),媒体类按容器命名(mp4/png),与既有 parser 约定保持一致。
+  const parserKind = result.meta.sourceFormat === 'image'
+    ? (result.meta.containerExtension ?? 'image')
+    : `${result.meta.sourceFormat}${suffix}`
+  const assets = toPreparedAssets(result.assets)
+
+  return {
+    title: result.title,
+    markdown: result.markdown,
+    sourceFormat: result.meta.sourceFormat,
+    parser: `iddoc@1/${parserKind}`,
+    sourcePath: file,
+    warnings,
+    dependencyVersions: result.dependencyVersions,
+    externalId: result.externalId,
+    ...(assets.length > 0 ? { assets } : {}),
+  }
+}
+
+export const iddocAdapter: Adapter = {
+  id: 'iddoc',
+  description: '本地音视频 / 图片 → Markdown 与本地图片(能力来自内核自带的 src/media/:字幕优先;转写需显式开启;图片直接收录)',
+  kinds: ['file'],
+  extensions: IDDOC_EXTENSIONS,
+  availability: availabilitySync,
+  probe: probeAvailability,
+  run,
+}

package/src/adapters/index.ts

@@ -0,0 +1,147 @@
+/**
+ * Adapter registry.
+ *
+ * Resolution order stays trivial and explicit: an explicit override, then the
+ * media adapter (`iddoc`, by extension), then the document engine, then the text
+ * pass-through. Unknown extensions are only treated as text when the bytes are
+ * actually textual — guessing there is how "converted successfully" becomes a lie.
+ *
+ * `.pdf` 默认仍走 anydoc(文本层最好、零依赖);只有显式 `SCANNED_OCR=1` 才改走
+ * `scanned`(纯图片页的轻量 OCR 档)。
+ */
+
+import { open } from 'node:fs/promises'
+import { extname } from 'node:path'
+import type { ConvertRequest } from '../contract.js'
+import { ANYDOC_EXTENSIONS, anydocAdapter, anydocAvailability } from './anydoc.js'
+import { IDDOC_EXTENSIONS, iddocAdapter } from './iddoc.js'
+import { SCANNED_EXTENSIONS, scannedAdapter, scannedPreferred } from './scanned.js'
+import { textAdapter, TEXT_EXTENSIONS } from './text.js'
+import { AdapterError, type Adapter, type AdapterAvailability } from './types.js'
+
+export const ADAPTERS: Adapter[] = [anydocAdapter, iddocAdapter, scannedAdapter, textAdapter]
+
+export function findAdapter(id: string): Adapter | undefined {
+  return ADAPTERS.find(adapter => adapter.id === id)
+}
+
+/** Cheap binary sniff: NUL bytes or invalid UTF-8 in the head means "not text". */
+export async function looksTextual(path: string): Promise<boolean> {
+  let handle
+  try {
+    handle = await open(path, 'r')
+  } catch {
+    return false
+  }
+  try {
+    const buffer = Buffer.alloc(4096)
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0)
+    if (bytesRead === 0) return true
+    const head = buffer.subarray(0, bytesRead)
+    if (head.includes(0)) return false
+    return !head.toString('utf8').includes('\uFFFD')
+  } finally {
+    await handle.close().catch(() => undefined)
+  }
+}
+
+export const SUPPORTED_EXTENSIONS = [...ANYDOC_EXTENSIONS, ...IDDOC_EXTENSIONS, ...TEXT_EXTENSIONS]
+
+export async function resolveAdapter(
+  request: ConvertRequest,
+  filename: string,
+  inputPath: string | undefined,
+): Promise<Adapter> {
+  if (request.adapter) {
+    const explicit = findAdapter(request.adapter)
+    if (!explicit) {
+      throw new AdapterError(
+        'ADAPTER_UNKNOWN',
+        `未知的 adapter：${request.adapter}`,
+        `可用 adapter：${ADAPTERS.map(adapter => adapter.id).join(', ')}`,
+      )
+    }
+    const availability = await (explicit.probe?.() ?? Promise.resolve(explicit.availability()))
+    if (!availability.available) {
+      throw new AdapterError('DEPENDENCY_MISSING', availability.reason ?? `${explicit.id} 当前不可用`, availability.suggestion)
+    }
+    return explicit
+  }
+
+  if (request.kind === 'text') return textAdapter
+
+  const extension = extname(filename).toLowerCase()
+  // 扫描档是显式 opt-in:默认仍让 anydoc 试文本层,失败了错误建议再指向 scanned。
+  if (SCANNED_EXTENSIONS.includes(extension) && scannedPreferred()) return scannedAdapter
+  if (ANYDOC_EXTENSIONS.includes(extension)) return anydocAdapter
+  if (IDDOC_EXTENSIONS.includes(extension)) return iddocAdapter
+  if (TEXT_EXTENSIONS.includes(extension)) return textAdapter
+  if (inputPath && (await looksTextual(inputPath))) return textAdapter
+
+  throw new AdapterError(
+    'FORMAT_UNSUPPORTED',
+    `不支持的输入格式：${extension || '(无扩展名)'}`,
+    `本版做文件类：${ANYDOC_EXTENSIONS.join(' ')}（文档）、${SCANNED_EXTENSIONS.join(' ')}（扫描件 OCR 档）、${IDDOC_EXTENSIONS.join(' ')}（音视频/图片）以及 ${TEXT_EXTENSIONS.join(' ')}（直通）；网页链接仍在 issues/0017。`,
+  )
+}
+
+export interface AdapterCapability {
+  id: string
+  description: string
+  kinds: ConvertRequest['kind'][]
+  extensions: string[]
+  availability: AdapterAvailability
+}
+
+export interface CapabilityReport {
+  adapters: AdapterCapability[]
+  /** Engine-level runtime facts; documents need no external binary, iddoc needs ffmpeg. */
+  runtime: Record<string, { available: boolean; version?: string; error?: string }>
+  defaults: Record<string, string>
+  /** Extensions the document engine covers. */
+  extensions: string[]
+}
+
+/** Everything the console and the DSH settings panel need to tell the truth. */
+export async function capabilityReport(): Promise<CapabilityReport> {
+  const adapters: AdapterCapability[] = []
+  const runtime: CapabilityReport['runtime'] = {}
+
+  for (const adapter of ADAPTERS) {
+    const availability = await (adapter.probe?.() ?? Promise.resolve(adapter.availability()))
+    adapters.push({
+      id: adapter.id,
+      description: adapter.description,
+      kinds: adapter.kinds,
+      extensions: adapter.extensions,
+      availability,
+    })
+    for (const [name, version] of Object.entries(availability.versions ?? {})) {
+      runtime[name] = { available: true, version }
+    }
+    if (adapter.probe && !availability.available) {
+      runtime[adapter.id] = { available: false, error: availability.reason }
+    }
+  }
+
+  const anydoc = await anydocAvailability()
+  if (runtime['@firecrawl/anydoc'] === undefined) {
+    runtime['@firecrawl/anydoc'] = anydoc.available
+      ? { available: true, ...(anydoc.versions?.['@firecrawl/anydoc'] ? { version: anydoc.versions['@firecrawl/anydoc'] } : {}) }
+      : { available: false, error: anydoc.reason }
+  }
+
+  return {
+    adapters,
+    runtime,
+    defaults: {
+      document: anydoc.available ? 'anydoc' : '（不可用）',
+      text: 'text',
+      video: 'iddoc',
+      audio: 'iddoc',
+      image: 'iddoc',
+      scannedPdf: 'scanned',
+    },
+    extensions: ANYDOC_EXTENSIONS,
+  }
+}

package/src/adapters/scanned.ts

@@ -0,0 +1,139 @@
+/**
+ * scanned —— 扫描件 / 纯图片页 PDF 的**轻量 OCR 档**(issue 0017 的扫描件线,轻量版)。
+ *
+ * 与 `anydoc` 的分工是明确的:
+ *
+ * - `.pdf` **默认仍走 anydoc**(文本层 PDF,零依赖、质量最好);
+ * - anydoc 报 `needsOcr`(整份是图片页)时,错误建议会指向本档;
+ * - 设 `SCANNED_OCR=1` 可让 `.pdf` 直接走本档(显式 opt-in,不做静默降级)。
+ *
+ * 本档**不做**版面还原:输出是"第 N 页 + 该页图片 + 该页文字"。版面顺序、表格结构、
+ * 公式属于 0017 的"可选高质量档"(docling / MinerU),不在这一档的承诺里。
+ *
+ * 能力来自同包 `src/media/` 的 `convertScannedDocument()`:
+ * pypdfium2 渲染页图(无系统 poppler 依赖)+ RapidOCR 本地识别,全程不联网。
+ *
+ * 环境变量:
+ *   SCANNED_OCR=1        让 `.pdf` 直接走本档(默认 false:先让 anydoc 试文本层)
+ *   SCANNED_MAX_PAGES    最多处理页数(默认 50)
+ *   SCANNED_DPI          渲染 DPI(默认 150)
+ *   SCANNED_NO_PAGE_IMAGES=1  只保留文字,不落地页图
+ *   SCANNED_UVX / SCANNED_PYTHON  自定义 uvx 与 Python 版本
+ */
+
+import { stat } from 'node:fs/promises'
+import {
+  MediaToMarkdownError,
+  convertScannedDocument,
+  probeTools,
+  UVX_HINT,
+  type MediaAsset,
+} from '../media/index.js'
+import type { ConvertWarning } from '../contract.js'
+import { AdapterError, type Adapter, type AdapterAvailability, type AdapterContext, type AdapterOutput, type PreparedAsset } from './types.js'
+
+export const SCANNED_EXTENSIONS = ['.pdf']
+
+function envFlag(name: string): boolean {
+  const value = (process.env[name] ?? '').trim().toLowerCase()
+  return value === '1' || value === 'true' || value === 'yes' || value === 'on'
+}
+
+function envInt(name: string): number | undefined {
+  const parsed = Number.parseInt((process.env[name] ?? '').trim(), 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined
+}
+
+/** 廉价同步检查:真正的依赖探测在 probe() 与首次使用时。 */
+function availabilitySync(): AdapterAvailability {
+  return { available: true }
+}
+
+async function probeAvailability(): Promise<AdapterAvailability> {
+  const versions = await probeTools({ ...(process.env.SCANNED_UVX ? { uvxPath: process.env.SCANNED_UVX } : {}) })
+  if (!versions.uvx) {
+    return {
+      available: false,
+      reason: '扫描档需要 uvx(用于拉起 pypdfium2 渲染页图与 RapidOCR 识别文字)',
+      suggestion: UVX_HINT,
+    }
+  }
+  return { available: true, versions: { uvx: versions.uvx } }
+}
+
+function toPreparedAssets(assets: MediaAsset[]): PreparedAsset[] {
+  return assets.map(asset => ({
+    rel: asset.rel,
+    data: asset.data,
+    ...(asset.contentType ? { contentType: asset.contentType } : {}),
+  }))
+}
+
+async function run(context: AdapterContext): Promise<AdapterOutput> {
+  if (!context.inputPath) {
+    throw new AdapterError('INPUT_REQUIRED', 'scanned 只处理本地 PDF 文件(kind=file)。')
+  }
+  const file = context.inputPath
+  const fileInfo = await stat(file).catch(() => undefined)
+  if (!fileInfo?.isFile()) throw new AdapterError('INPUT_NOT_A_FILE', `输入不是文件:${file}`)
+
+  const uvxPath = process.env.SCANNED_UVX?.trim()
+  const tools = {
+    ...(uvxPath ? { uvxPath } : {}),
+    ...(process.env.SCANNED_PYTHON?.trim() ? { pythonVersion: process.env.SCANNED_PYTHON.trim() } : {}),
+  }
+
+  let result
+  try {
+    result = await convertScannedDocument({
+      file,
+      ...(context.request.title?.trim() ? { title: context.request.title.trim() } : {}),
+      ...(envInt('SCANNED_MAX_PAGES') ? { maxPages: envInt('SCANNED_MAX_PAGES') } : {}),
+      ...(envInt('SCANNED_DPI') ? { dpi: envInt('SCANNED_DPI') } : {}),
+      ...(envFlag('SCANNED_NO_PAGE_IMAGES') ? { pageImages: false } : {}),
+      ...(Object.keys(tools).length > 0 ? { tools } : {}),
+      ...(context.signal ? { signal: context.signal } : {}),
+      onProgress: progress => context.report(progress.progress, progress.stage, progress.message),
+    })
+  } catch (cause) {
+    if (cause instanceof MediaToMarkdownError) {
+      throw new AdapterError(cause.code, cause.message, cause.suggestion)
+    }
+    throw new AdapterError('ADAPTER_FAILED', cause instanceof Error ? cause.message : String(cause))
+  }
+
+  const warnings: ConvertWarning[] = result.warnings.map(warning => ({ code: warning.code, message: warning.message }))
+  const identified = result.pages?.filter(page => page.text).length ?? 0
+  warnings.push({
+    code: 'SCANNED_TIER',
+    message: `扫描档(轻量 OCR):共 ${result.pages?.length ?? 0} 页,${identified} 页识别到文字;不做版面还原。如版面/表格错乱,见 issues/0017 的可选高质量档。`,
+  })
+
+  const assets = toPreparedAssets(result.assets)
+  return {
+    title: result.title,
+    markdown: result.markdown,
+    sourceFormat: 'pdf',
+    parser: 'scanned@1/pdf+ocr',
+    sourcePath: file,
+    warnings,
+    dependencyVersions: result.dependencyVersions,
+    externalId: result.externalId,
+    ...(assets.length > 0 ? { assets } : {}),
+  }
+}
+
+export const scannedAdapter: Adapter = {
+  id: 'scanned',
+  description: '扫描件 / 纯图片页 PDF → 逐页本地 OCR Markdown(轻量档:不出网、不做版面还原;需 uvx)',
+  kinds: ['file'],
+  extensions: SCANNED_EXTENSIONS,
+  availability: availabilitySync,
+  probe: probeAvailability,
+  run,
+}
+
+/** 路由用:是否让 `.pdf` 直接走扫描档(显式 opt-in)。 */
+export function scannedPreferred(): boolean {
+  return envFlag('SCANNED_OCR')
+}

package/src/adapters/text.ts

@@ -0,0 +1,146 @@
+/**
+ * Text-family adapter: Markdown, plain text, JSON/TSV and friends.
+ *
+ * These inputs need no parsing, so the adapter's whole job is normalization:
+ * drop any pre-existing front matter (the service writes the authoritative
+ * block) and report the carrier format truthfully.
+ *
+ * `.csv` is deliberately absent: the document engine owns it, because it
+ * produces a real GFM table where this adapter would only pass bytes through.
+ */
+
+import { readFile, stat } from 'node:fs/promises'
+import { basename, extname } from 'node:path'
+import type { ConvertWarning, SourceFormat } from '../contract.js'
+import { parseMarkdownDocument, sha1, sha256 } from '../markdown.js'
+import { AdapterError, type Adapter, type AdapterContext, type AdapterOutput, type PreparedAsset } from './types.js'
+
+const INLINE_IMAGE_PATTERN = /!\[([^\]]*)\]\(\s*(?:<([^>]+)>|([^\s)]+))\s*\)/g
+
+const MAGIC_EXTENSIONS: Array<{ test: (data: Buffer) => boolean; extension: string; contentType: string }> = [
+  { test: data => data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])), extension: 'png', contentType: 'image/png' },
+  { test: data => data[0] === 0xff && data[1] === 0xd8, extension: 'jpg', contentType: 'image/jpeg' },
+  { test: data => data.subarray(0, 3).toString('latin1') === 'GIF', extension: 'gif', contentType: 'image/gif' },
+  { test: data => data.subarray(0, 4).toString('latin1') === 'RIFF' && data.subarray(8, 12).toString('latin1') === 'WEBP', extension: 'webp', contentType: 'image/webp' },
+]
+
+/**
+ * Turn `data:` image URIs into real `assets/` files.
+ *
+ * A data URI is not a network fetch — it is bytes already in hand — but it has
+ * to become a local file anyway, because retrieval skips `data:` exactly like it
+ * skips `http(s):`. Without this, a Markdown source with a pasted screenshot
+ * would upload "successfully" and be unsearchable.
+ */
+export function materializeInlineImages(markdown: string): { markdown: string; assets: PreparedAsset[]; warnings: ConvertWarning[] } {
+  const pieces = []
+  const assets: PreparedAsset[] = []
+  const warnings: ConvertWarning[] = []
+  let cursor = 0
+  for (const match of markdown.matchAll(INLINE_IMAGE_PATTERN)) {
+    const index = match.index ?? 0
+    pieces.push(markdown.slice(cursor, index))
+    cursor = index + match[0].length
+    const alt = match[1] ?? ''
+    const url = (match[2] ?? match[3] ?? '').trim()
+    if (!url.startsWith('data:')) {
+      pieces.push(match[0])
+      continue
+    }
+    const parsed = /^data:([^;,]*)((?:;[^,]*)*),(.*)$/s.exec(url)
+    const data = parsed === null
+      ? Buffer.alloc(0)
+      : parsed[2]!.includes('base64')
+        ? Buffer.from(parsed[3]!.replace(/\s+/g, ''), 'base64')
+        : Buffer.from(decodeURIComponent(parsed[3]!), 'utf8')
+    const magic = data.length > 0 ? MAGIC_EXTENSIONS.find(entry => entry.test(data)) : undefined
+    if (!magic) {
+      warnings.push({ code: 'INLINE_IMAGE_UNSUPPORTED', message: '无法识别内联图片 data URI 的类型，已丢弃该引用。' })
+      continue
+    }
+    const digest = sha1(data)
+    const rel = `assets/img-${digest.slice(0, 12)}.${magic.extension}`
+    assets.push({ rel, data, contentType: magic.contentType })
+    pieces.push(`![${alt}](${rel})`)
+    warnings.push({ code: 'INLINE_IMAGE_MATERIALIZED', message: `内联图片已落地为 ${rel}。` })
+  }
+  pieces.push(markdown.slice(cursor))
+  return { markdown: pieces.join(''), assets, warnings }
+}
+
+export const TEXT_EXTENSIONS = [
+  '.md', '.markdown', '.mdx', '.txt', '.text', '.log', '.tsv',
+  '.json', '.jsonl', '.ndjson', '.yml', '.yaml', '.toml', '.ini',
+  '.adoc', '.rst', '.org', '.tex',
+]
+
+export const MARKDOWN_EXTENSIONS = ['.md', '.markdown', '.mdx', '.adoc', '.rst', '.org']
+
+function formatFor(filename: string, content: string): SourceFormat {
+  const extension = extname(filename).toLowerCase()
+  if (MARKDOWN_EXTENSIONS.includes(extension)) return 'markdown'
+  if (/^\s*#{1,6}\s+\S/m.test(content) && /\[[^\]]+\]\([^)]+\)/.test(content)) return 'markdown'
+  return 'text'
+}
+
+function stripFrontMatter(content: string): string {
+  return content.startsWith('---') ? parseMarkdownDocument(content).content : content.trim()
+}
+
+async function run(context: AdapterContext): Promise<AdapterOutput> {
+  let content: string
+  let filename: string
+  let sourcePath: string | undefined
+
+  if (context.inputPath) {
+    const info = await stat(context.inputPath)
+    if (!info.isFile()) throw new AdapterError('INPUT_NOT_A_FILE', `输入不是文件：${context.inputPath}`)
+    content = await readFile(context.inputPath, 'utf8')
+    filename = context.filename || basename(context.inputPath)
+    sourcePath = context.inputPath
+  } else {
+    content = context.text ?? ''
+    filename = context.filename || 'inline.txt'
+  }
+
+  if (!content.trim()) throw new AdapterError('CONTENT_REQUIRED', '输入内容为空，无法转换。')
+  const warnings: AdapterOutput['warnings'] = []
+  const format = formatFor(filename, content)
+
+  // Detect a real front matter block instead of comparing lengths: a trailing
+  // newline alone used to trigger this warning on ordinary Markdown.
+  const hadFrontMatter = format === 'markdown' && content.startsWith('---') && content.indexOf('\n---', 3) > 0
+  const stripped = format === 'markdown' ? stripFrontMatter(content) : content.trim()
+  if (hadFrontMatter) {
+    warnings.push({ code: 'FRONT_MATTER_REPLACED', message: '输入已带 front matter，已由转换内核重写为统一契约。' })
+  }
+  const materialized = materializeInlineImages(stripped)
+  const body = materialized.markdown
+  warnings.push(...materialized.warnings)
+
+  const title =
+    context.request.title?.trim() ||
+    (format === 'markdown' ? /^#{1,6}\s+(.+)$/m.exec(body)?.[1]?.trim() : undefined) ||
+    basename(filename, extname(filename))
+
+  return {
+    title: title.slice(0, 300),
+    markdown: body,
+    sourceFormat: format,
+    parser: `convert-core/passthrough@1/${format}`,
+    ...(sourcePath ? { sourcePath } : {}),
+    warnings,
+    dependencyVersions: {},
+    externalId: `sha256:${sha256(content)}`,
+    ...(materialized.assets.length > 0 ? { assets: materialized.assets } : {}),
+  }
+}
+
+export const textAdapter: Adapter = {
+  id: 'text',
+  description: 'Markdown / 纯文本 / JSON / TSV 直通（只做契约归一化，不改变内容）',
+  kinds: ['text', 'file'],
+  extensions: TEXT_EXTENSIONS,
+  availability: () => ({ available: true }),
+  run,
+}

package/src/adapters/types.ts

@@ -0,0 +1,76 @@
+import type { ConvertRequest, ConvertWarning, SourceFormat } from '../contract.js'
+
+/**
+ * An asset an adapter hands to the service as bytes. The service owns the
+ * delivery directory, so it computes the path, size and hash.
+ */
+export interface PreparedAsset {
+  rel: string
+  data: Buffer
+  contentType?: string
+}
+
+export interface AdapterContext {
+  request: ConvertRequest
+  /** Staged local path for `kind=file`. */
+  inputPath?: string
+  /** Inline payload for `kind=text`. */
+  text?: string
+  filename: string
+  signal: AbortSignal
+  report: (progress: number | null, stage: string, message?: string) => void
+}
+
+export interface AdapterOutput {
+  title: string
+  /** Markdown body only — front matter is the service's job. */
+  markdown: string
+  sourceFormat: SourceFormat
+  parser: string
+  sourcePath?: string
+  warnings: ConvertWarning[]
+  dependencyVersions: Record<string, string>
+  /** Stable identity for idempotency (file hash). */
+  externalId?: string
+  assets?: PreparedAsset[]
+}
+
+export interface AdapterAvailability {
+  available: boolean
+  /** Populated when `available` is false. */
+  reason?: string
+  /** Actionable next step shown verbatim to the user. */
+  suggestion?: string
+  /** Versions of the pieces involved, when known. */
+  versions?: Record<string, string>
+}
+
+export interface Adapter {
+  id: string
+  /** Human description shown in the console and in `GET /api/capabilities`. */
+  description: string
+  /** Task kinds this adapter can serve. */
+  kinds: ConvertRequest['kind'][]
+  /** File extensions (lowercase, with dot) this adapter claims. */
+  extensions: string[]
+  /** Cheap synchronous check used for routing decisions. */
+  availability: () => AdapterAvailability
+  /**
+   * Authoritative asynchronous check used by `GET /api/capabilities`: it really
+   * loads the engine (and the platform binary) instead of assuming it works.
+   */
+  probe?: () => Promise<AdapterAvailability>
+  run: (context: AdapterContext) => Promise<AdapterOutput>
+}
+
+export class AdapterError extends Error {
+  readonly code: string
+  readonly suggestion?: string
+
+  constructor(code: string, message: string, suggestion?: string) {
+    super(message)
+    this.name = 'AdapterError'
+    this.code = code
+    this.suggestion = suggestion
+  }
+}