dsh-convert-core 0.1.0-alpha.1

package/src/service.ts

@@ -0,0 +1,639 @@
+/**
+ * The conversion service: queue, lifecycle, delivery, observability.
+ *
+ * It owns no transport. `http.ts` mounts it on `node:http`, the DSH plugin
+ * mounts the same handler on the host web server, and `bin/tita-convert.mjs`
+ * runs it standalone — the "kernel first, wrapper second" split.
+ */
+
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { basename, dirname, extname, join, normalize, resolve, sep } from 'node:path'
+import { homedir } from 'node:os'
+import { capabilityReport, resolveAdapter, type CapabilityReport } from './adapters/index.js'
+import { AdapterError } from './adapters/types.js'
+import type { ConvertAsset, ConvertRequest, ConvertTask, ConvertWarning, IngestPayload, SourceFormat, TaskState } from './contract.js'
+import { writeDelivery } from './delivery.js'
+import { sha1, sha256, shortHash, slug } from './markdown.js'
+
+export interface ConvertServiceOptions {
+  /** Root for task state (`tasks.json`). Defaults to `~/.tita-data-agent`. */
+  rootDir?: string
+  /**
+   * Root the **deliveries** are written under. Defaults to `<rootDir>/convert-out`.
+   *
+   * 与 `bucketByDay` 配合决定形状：不分桶是 `<outRoot>/<taskId>/`，分桶是
+   * `<outRoot>/<YYYY-MM-DD>/<taskId>/`。任务目录始终是原子的交付单位。
+   */
+  outRoot?: string
+  /**
+   * Root the per-task **working** directories live under. Defaults to
+   * `<rootDir>/work`. 形状与 `outRoot` 一致。
+   */
+  workRoot?: string
+  /**
+   * 交付与工作区是否按日期分桶（0029）。
+   *
+   * **默认 false，是刻意的**：这是内核，独立运行（`bin/tita-convert.mjs`）与既有
+   * 调用方都不该因为插件侧的目录结构调整而换位置。TitaAgent 插件显式传 `true`，
+   * 因为它的根路径契约里 `output/` 与 `tmp/` 的二级就是日期。
+   *
+   * 分桶的理由：这两处是「按时间堆积」的东西，不分桶的话一个月后就是一个几百条
+   * 平铺的目录，`ls` 出来读不出「上周那份报表在哪」。
+   */
+  bucketByDay?: boolean
+  maxConcurrent?: number
+  maxInputBytes?: number
+  /** Keep at most this many finished tasks in the store. */
+  maxTasks?: number
+  /** Delete deliveries older than this on start. 0 disables cleanup. */
+  retentionDays?: number
+  /**
+   * How long a capability report stays valid. Defaults to
+   * {@link DEFAULT_CAPABILITY_TTL_MS}; 0 disables caching.
+   *
+   * See {@link ConvertService.capabilities} for why this exists: building the
+   * report spawns external binaries, and the console polls it on a timer.
+   */
+  capabilityTtlMs?: number
+}
+
+/**
+ * Default lifetime of a capability report: 30 seconds.
+ *
+ * Long enough that a polling panel costs one probe per half minute instead of one
+ * per poll; short enough that installing ffmpeg and reopening the panel shows it
+ * without restarting anything.
+ */
+export const DEFAULT_CAPABILITY_TTL_MS = 30_000
+
+export interface SubmitInput {
+  filename?: string
+  /** Raw bytes for file / video uploads. */
+  data?: Buffer
+}
+
+export type ConvertListener = (task: ConvertTask) => void
+
+export const DEFAULT_ROOT = join(homedir(), '.tita-data-agent')
+
+export function defaultConvertRoot(): string {
+  if (process.env.DSH_CONVERT_ROOT) return process.env.DSH_CONVERT_ROOT
+  return join(DEFAULT_ROOT, 'convert')
+}
+
+interface QueueEntry {
+  taskId: string
+  controller: AbortController
+}
+
+const STATES: TaskState[] = ['queued', 'running', 'succeeded', 'failed', 'cancelled']
+
+function newTaskId(): string {
+  return `conv_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
+}
+
+/**
+ * 本地日期的 `YYYY-MM-DD`。
+ *
+ * 与 `data-domain-knowledge/src/layout.ts` 的 `dayKey` 同一条规则（本地时间、
+ * 零填充）。内核不能 import 插件，所以这里重列一次 —— 它必须是**同一个**日期，
+ * 否则「今天的交付」会跨零点落进两个不同的桶。
+ */
+function dayKey(date: Date): string {
+  const pad = (value: number): string => String(value).padStart(2, '0')
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
+}
+
+/** 任务创建当天的日期桶。用 `createdAt` 而不是「现在」：重试不该换桶。 */
+function dayOf(createdAt: string | undefined): string {
+  const parsed = createdAt ? new Date(createdAt) : new Date()
+  return dayKey(Number.isNaN(parsed.getTime()) ? new Date() : parsed)
+}
+
+export class ConvertService {
+  readonly rootDir: string
+  /** 交付物根。每个任务的具体交付目录见 `deliveryDirOf()`。 */
+  readonly outRoot: string
+  /** 工作区根。每个任务的具体工作目录见 `workDirOf()`。 */
+  readonly workRoot: string
+  /** 交付与工作区是否按日期分桶。见 `ConvertServiceOptions.bucketByDay`。 */
+  readonly bucketByDay: boolean
+  private readonly options: ConvertServiceOptions
+  private readonly tasks = new Map<string, ConvertTask>()
+  private readonly controllers = new Map<string, AbortController>()
+  private readonly listeners = new Set<ConvertListener>()
+  private readonly queue: string[] = []
+  private running = 0
+  private closed = false
+  private persistTimer: NodeJS.Timeout | undefined
+  private persistTail: Promise<void> = Promise.resolve()
+  /** Last capability report and when it was built. See {@link capabilities}. */
+  private capabilityCache: { at: number; report: CapabilityReport } | undefined
+
+  constructor(options: ConvertServiceOptions = {}) {
+    this.options = options
+    this.rootDir = options.rootDir ?? defaultConvertRoot()
+    this.outRoot = options.outRoot ?? join(this.rootDir, 'convert-out')
+    this.workRoot = options.workRoot ?? join(this.rootDir, 'work')
+    this.bucketByDay = options.bucketByDay ?? false
+  }
+
+  /**
+   * @deprecated 0029：`outDir` 现在是 `outRoot` 的别名。保留这个名字只为兼容
+   * 既有的能力报告（`host.ts` 会回显它）；新代码用 `outRoot` + `deliveryDirOf()`。
+   */
+  get outDir(): string { return this.outRoot }
+  /** @deprecated 0029：同上，用 `workRoot` + `workDirOf()`。 */
+  get workDir(): string { return this.workRoot }
+
+  /**
+   * 一个任务的交付目录。
+   *
+   * 分桶时 `<outRoot>/<日期>/<taskId>`，否则 `<outRoot>/<taskId>`。**按任务的
+   * `createdAt` 算而不是按「现在」**：重试一个昨天的任务不该把它换到今天来，
+   * 否则同一个交付会因为一次重试而换位置。
+   */
+  deliveryDirOf(task: Pick<ConvertTask, 'id' | 'createdAt'>): string {
+    return this.taskDir(this.outRoot, task)
+  }
+
+  /** 一个任务的工作目录。形状与交付目录一致。 */
+  workDirOf(task: Pick<ConvertTask, 'id' | 'createdAt'>): string {
+    return this.taskDir(this.workRoot, task)
+  }
+
+  private taskDir(root: string, task: Pick<ConvertTask, 'id' | 'createdAt'>): string {
+    return this.bucketByDay ? join(root, dayOf(task.createdAt), task.id) : join(root, task.id)
+  }
+
+  async start(): Promise<void> {
+    await mkdir(this.outRoot, { recursive: true })
+    await mkdir(this.workRoot, { recursive: true })
+    await this.load()
+    await this.cleanup()
+  }
+
+  async close(): Promise<void> {
+    this.closed = true
+    for (const controller of this.controllers.values()) controller.abort()
+    if (this.persistTimer) clearTimeout(this.persistTimer)
+    await this.persist()
+  }
+
+  subscribe(listener: ConvertListener): () => void {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  private emit(task: ConvertTask): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(task)
+      } catch {
+        /* a broken listener must not break conversion */
+      }
+    }
+  }
+
+  get(id: string): ConvertTask | undefined {
+    const task = this.tasks.get(id)
+    return task ? structuredClone(task) : undefined
+  }
+
+  list(): ConvertTask[] {
+    return [...this.tasks.values()]
+      .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+      .map(task => structuredClone(task))
+  }
+
+  /**
+   * Report which adapters can run and which external binaries exist.
+   *
+   * **Cached, because building this is not free.** `capabilityReport()` probes
+   * every adapter, and the media adapter's probe runs `ffprobe -version`,
+   * `ffmpeg -version` and `uvx --version` — three child processes per call, which
+   * measured ~60ms of server time. The conversion console polls this endpoint
+   * every four seconds while its tab is visible, so an uncached report cost about
+   * 45 processes and a second of CPU per minute. That lands on the same
+   * single-threaded process that serves the GUI's HTTP and event stream, which is
+   * how a status panel becomes everyone's latency.
+   *
+   * Nothing it reports changes second to second: an installed binary stays
+   * installed. {@link ConvertServiceOptions.capabilityTtlMs} bounds the staleness.
+   *
+   * @param options - `force` bypasses the cache, for a caller that just changed
+   *   the environment (or a test that must not read another test's report).
+   * @returns the capability report.
+   */
+  async capabilities(options: { force?: boolean } = {}): Promise<CapabilityReport> {
+    const ttl = this.options.capabilityTtlMs ?? DEFAULT_CAPABILITY_TTL_MS
+    const now = Date.now()
+    const cached = this.capabilityCache
+    if (options.force !== true && cached !== undefined && ttl > 0 && now - cached.at < ttl) return cached.report
+    const report = await capabilityReport()
+    this.capabilityCache = { at: now, report }
+    return report
+  }
+
+  async submit(request: ConvertRequest, input: SubmitInput = {}): Promise<ConvertTask> {
+    if (this.closed) throw new AdapterError('SERVICE_CLOSED', '转换服务已关闭。')
+    validateRequest(request)
+
+    const id = newTaskId()
+    const filename = input.filename ?? request.filename ?? defaultFilename(request)
+    const createdAt = new Date().toISOString()
+
+    const task: ConvertTask = {
+      id,
+      state: 'queued',
+      inputKind: request.kind,
+      label: request.title?.trim() || filename || 'inline text',
+      sourceFormat: 'text',
+      createdAt,
+      updatedAt: createdAt,
+      progress: 0,
+      stage: 'queued',
+      message: '已排队',
+      warnings: [],
+      attempts: 0,
+      request: { ...request },
+    }
+
+    // A local path is read here rather than by every caller, so the HTTP API,
+    // the agent tool and the console share exactly one staging behaviour.
+    let payload = input.data
+    let payloadName = filename
+    if (!payload && request.localPath && request.kind === 'file') {
+      const absolute = resolve(request.localPath)
+      const info = await stat(absolute).catch(() => undefined)
+      if (!info?.isFile()) throw new AdapterError('PATH_NOT_A_FILE', `路径不是文件：${absolute}`)
+      const maxBytes = this.options.maxInputBytes ?? 256 * 1024 * 1024
+      if (info.size > maxBytes) {
+        throw new AdapterError('INPUT_TOO_LARGE', `输入文件 ${info.size} 字节，超过上限 ${maxBytes} 字节。`, '调大插件设置里的 maxInputBytes，或先压缩/拆分文件。')
+      }
+      payload = await readFile(absolute)
+      payloadName = request.filename ?? basename(absolute)
+    }
+
+    if (payload) {
+      const maxBytes = this.options.maxInputBytes ?? 256 * 1024 * 1024
+      if (payload.length > maxBytes) {
+        throw new AdapterError('INPUT_TOO_LARGE', `输入文件 ${payload.length} 字节，超过上限 ${maxBytes} 字节。`, '调大插件设置里的 maxInputBytes，或先压缩/拆分文件。')
+      }
+      const taskWorkDir = this.workDirOf(task)
+      await mkdir(taskWorkDir, { recursive: true })
+      const stagePath = join(taskWorkDir, safeFilename(payloadName))
+      await writeFile(stagePath, payload)
+      task.inputPath = stagePath
+      task.request = { ...task.request, filename: payloadName }
+    }
+
+    this.tasks.set(id, task)
+    this.queue.push(id)
+    await this.persist()
+    this.emit(this.get(id)!)
+    this.pump()
+    return this.get(id)!
+  }
+
+  cancel(id: string): ConvertTask {
+    const task = this.tasks.get(id)
+    if (!task) throw new AdapterError('TASK_NOT_FOUND', `任务不存在：${id}`)
+    if (task.state === 'succeeded' || task.state === 'failed' || task.state === 'cancelled') return this.get(id)!
+    const index = this.queue.indexOf(id)
+    if (index >= 0) this.queue.splice(index, 1)
+    const controller = this.controllers.get(id)
+    if (controller) controller.abort()
+    this.patch(id, { state: 'cancelled', stage: 'cancelled', message: '已取消', finishedAt: new Date().toISOString(), progress: null })
+    // Deliveries of cancelled tasks are removed: half a bundle is not ingestible.
+    // 用任务自己的交付目录：它可能落在**过去某一天**的日期桶里，不能按今天算。
+    void rm(task.deliveryDir ?? this.deliveryDirOf(task), { recursive: true, force: true })
+    return this.get(id)!
+  }
+
+  async retry(id: string): Promise<ConvertTask> {
+    const task = this.tasks.get(id)
+    if (!task) throw new AdapterError('TASK_NOT_FOUND', `任务不存在：${id}`)
+    if (task.state === 'running' || task.state === 'queued') {
+      throw new AdapterError('TASK_NOT_RETRYABLE', `任务当前状态为 ${task.state}，不能重试。`)
+    }
+    // Reuse the staged input and work dir: "retry" must not re-download.
+    this.patch(id, {
+      state: 'queued',
+      stage: 'queued',
+      message: '重试排队中',
+      progress: 0,
+      error: undefined,
+      finishedAt: undefined,
+      warnings: [],
+    })
+    this.queue.push(id)
+    await this.persist()
+    this.pump()
+    return this.get(id)!
+  }
+
+  private patch(id: string, changes: Partial<ConvertTask>): ConvertTask {
+    const current = this.tasks.get(id)
+    if (!current) throw new AdapterError('TASK_NOT_FOUND', `任务不存在：${id}`)
+    const next: ConvertTask = { ...current, ...changes, updatedAt: new Date().toISOString() }
+    this.tasks.set(id, next)
+    this.schedulePersist()
+    this.emit(structuredClone(next))
+    return next
+  }
+
+  private pump(): void {
+    const limit = Math.max(1, this.options.maxConcurrent ?? 2)
+    while (this.running < limit && this.queue.length > 0) {
+      const id = this.queue.shift()!
+      const task = this.tasks.get(id)
+      if (!task || task.state === 'cancelled') continue
+      const controller = new AbortController()
+      this.controllers.set(id, controller)
+      this.running += 1
+      void this.execute(id, controller)
+        .catch(() => undefined)
+        .finally(() => {
+          this.controllers.delete(id)
+          this.running -= 1
+          this.pump()
+        })
+    }
+  }
+
+  private async execute(id: string, controller: AbortController): Promise<void> {
+    const task = this.tasks.get(id)
+    if (!task) return
+    const startedAt = new Date().toISOString()
+    this.patch(id, { state: 'running', stage: 'starting', message: '开始转换', startedAt, progress: 0, attempts: task.attempts + 1 })
+
+    const taskWorkDir = this.workDirOf(task)
+    const deliveryDir = this.deliveryDirOf(task)
+    try {
+      await mkdir(taskWorkDir, { recursive: true })
+      const request = task.request
+      const filename = request.filename ?? (task.inputPath ? basename(task.inputPath) : defaultFilename(request))
+      const adapter = await resolveAdapter(request, filename, task.inputPath)
+      this.patch(id, { stage: 'resolving', message: `使用 ${adapter.id} 适配器` })
+
+      const output = await adapter.run({
+        request,
+        ...(task.inputPath ? { inputPath: task.inputPath } : {}),
+        ...(request.kind === 'text' ? { text: request.text ?? '' } : {}),
+        filename,
+        signal: controller.signal,
+        report: (progress, stage, message) => {
+          const current = this.tasks.get(id)
+          if (!current || current.state !== 'running') return
+          this.patch(id, { progress, stage, ...(message ? { message } : {}) })
+        },
+      })
+
+      if (controller.signal.aborted) throw new AdapterError('TASK_CANCELLED', '任务已取消')
+
+      const warnings: ConvertWarning[] = [...output.warnings]
+
+      // Assets arrive as bytes from the engine, and the service owns the
+      // delivery directory, so this is the only place that writes them.
+      const allAssets: ConvertAsset[] = []
+      for (const prepared of output.assets ?? []) {
+        const target = this.resolveDeliveryFile(id, prepared.rel)
+        if (!target) {
+          warnings.push({ code: 'ASSET_PATH_REJECTED', message: `资产路径越出交付目录，已跳过：${prepared.rel}` })
+          continue
+        }
+        await mkdir(dirname(target), { recursive: true })
+        await writeFile(target, prepared.data)
+        allAssets.push({
+          rel: prepared.rel,
+          path: target,
+          bytes: prepared.data.length,
+          sha1: sha1(prepared.data),
+          origin: 'inline',
+          ...(prepared.contentType ? { contentType: prepared.contentType } : {}),
+        })
+      }
+      const now = new Date().toISOString()
+      const manifest = await writeDelivery(deliveryDir, {
+        taskId: id,
+        title: output.title,
+        request,
+        markdown: output.markdown,
+        sourceFormat: output.sourceFormat as SourceFormat,
+        parser: output.parser,
+        ...(output.sourcePath ? { sourcePath: output.sourcePath } : {}),
+        assets: allAssets,
+        warnings,
+        dependencyVersions: output.dependencyVersions,
+        externalId: request.externalId ?? output.externalId ?? `sha256:${sha256(output.markdown)}`,
+        createdAt: task.createdAt,
+        updatedAt: now,
+      })
+
+      this.patch(id, {
+        state: 'succeeded',
+        stage: 'delivered',
+        message: `已交付 ${allAssets.length} 个图片资产`,
+        progress: 1,
+        finishedAt: now,
+        deliveryDir,
+        manifest,
+        sourceFormat: output.sourceFormat,
+        warnings,
+        error: undefined,
+      })
+      await rm(taskWorkDir, { recursive: true, force: true })
+    } catch (cause) {
+      if (controller.signal.aborted || (cause instanceof AdapterError && cause.code === 'TASK_CANCELLED')) {
+        this.patch(id, { state: 'cancelled', stage: 'cancelled', message: '已取消', finishedAt: new Date().toISOString(), progress: null })
+        await rm(deliveryDir, { recursive: true, force: true })
+        return
+      }
+      const error = cause instanceof AdapterError
+        ? { code: cause.code, message: cause.message, ...(cause.suggestion ? { suggestion: cause.suggestion } : {}) }
+        : {
+            code: (cause as Error & { code?: string }).code ?? 'CONVERT_FAILED',
+            message: cause instanceof Error ? cause.message : String(cause),
+            ...((cause as Error & { suggestion?: string }).suggestion ? { suggestion: (cause as Error & { suggestion?: string }).suggestion! } : {}),
+          }
+      await rm(deliveryDir, { recursive: true, force: true })
+      this.patch(id, {
+        state: 'failed',
+        stage: 'failed',
+        message: error.message,
+        finishedAt: new Date().toISOString(),
+        progress: null,
+        error,
+      })
+    }
+  }
+
+  /** Resolve a path inside a delivery directory, refusing traversal. */
+  resolveDeliveryFile(id: string, relative: string): string | undefined {
+    // 交付目录跟着任务走（日期桶 + 任务 id），所以先问任务自己。任务已经不在
+    // store 里（例如被 maxTasks 挤掉）时退回「按今天算」——这是唯一的近似，
+    // 也是唯一还能给出的答案。
+    const task = this.tasks.get(id)
+    const base = task?.deliveryDir ? resolve(task.deliveryDir) : resolve(this.deliveryDirOf({ id, createdAt: new Date().toISOString() }))
+    const target = resolve(base, normalize(relative).replace(/^([/\\])+/, ''))
+    if (target !== base && !target.startsWith(base + sep)) return undefined
+    return target
+  }
+
+  async readDeliveryFile(id: string, relative: string): Promise<{ data: Buffer; contentType: string } | undefined> {
+    const path = this.resolveDeliveryFile(id, relative)
+    if (!path) return undefined
+    try {
+      const info = await stat(path)
+      if (!info.isFile()) return undefined
+      return { data: await readFile(path), contentType: contentTypeOf(path) }
+    } catch {
+      return undefined
+    }
+  }
+
+  async ingestPlan(id: string): Promise<IngestPayload> {
+    const task = this.tasks.get(id)
+    if (!task) throw new AdapterError('TASK_NOT_FOUND', `任务不存在：${id}`)
+    if (task.state !== 'succeeded' || !task.manifest) {
+      throw new AdapterError('TASK_NOT_READY', `任务未成功交付（当前 ${task.state}），没有可录入的产物。`)
+    }
+    return task.manifest.ingest
+  }
+
+  listDeliveries(): Array<{ taskId: string; title: string; deliveryDir: string; state: TaskState; assets: number }> {
+    return this.list()
+      .filter(task => task.state === 'succeeded' && task.deliveryDir)
+      .map(task => ({
+        taskId: task.id,
+        title: task.manifest?.title ?? task.label,
+        deliveryDir: task.deliveryDir!,
+        state: task.state,
+        assets: task.manifest?.assets.length ?? 0,
+      }))
+  }
+
+  private schedulePersist(): void {
+    if (this.persistTimer) return
+    this.persistTimer = setTimeout(() => {
+      this.persistTimer = undefined
+      void this.persist()
+    }, 150)
+    this.persistTimer.unref?.()
+  }
+
+  private async persist(): Promise<void> {
+    const snapshot = {
+      version: 1,
+      updatedAt: new Date().toISOString(),
+      tasks: [...this.tasks.values()].slice(-(this.options.maxTasks ?? 200)),
+    }
+    const path = join(this.rootDir, 'tasks.json')
+    this.persistTail = this.persistTail
+      .then(async () => {
+        await mkdir(this.rootDir, { recursive: true })
+        const temporary = `${path}.${process.pid}.tmp`
+        await writeFile(temporary, `${JSON.stringify(snapshot, null, 2)}\n`, 'utf8')
+        const { rename } = await import('node:fs/promises')
+        await rename(temporary, path)
+      })
+      .catch(() => undefined)
+    await this.persistTail
+  }
+
+  private async load(): Promise<void> {
+    try {
+      const raw = await readFile(join(this.rootDir, 'tasks.json'), 'utf8')
+      const parsed = JSON.parse(raw) as { tasks?: unknown }
+      if (!Array.isArray(parsed.tasks)) return
+      for (const entry of parsed.tasks) {
+        const task = entry as ConvertTask
+        if (!task || typeof task.id !== 'string' || !STATES.includes(task.state)) continue
+        // A task that was running when the process died cannot be resumed safely.
+        this.tasks.set(
+          task.id,
+          task.state === 'running' || task.state === 'queued'
+            ? {
+                ...task,
+                state: 'failed',
+                stage: 'interrupted',
+                progress: null,
+                finishedAt: task.finishedAt ?? new Date().toISOString(),
+                error: {
+                  code: 'INTERRUPTED_BY_RESTART',
+                  message: '转换进程重启，该任务被中断。',
+                  suggestion: '点击重试：已下载的输入与中间产物会复用。',
+                },
+              }
+            : task,
+        )
+      }
+    } catch {
+      /* first run */
+    }
+  }
+
+  /**
+   * 按保留期清理交付物。
+   *
+   * `outRoot` 下面那一层**要么是日期桶、要么是任务目录**，取决于 `bucketByDay`；
+   * 两种情况下它都是「一个可整体丢弃的单位」，所以清理规则只有一条：这一层的
+   * mtime 早于截止就整块删。分桶时不必再往下一层逐个判 —— 桶内任务通常是同一天
+   * 建的，逐个判既白判又会留下一个空壳日期目录。
+   */
+  private async cleanup(): Promise<void> {
+    const days = this.options.retentionDays ?? 0
+    if (days <= 0) return
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000
+    const entries = await readdir(this.outRoot, { withFileTypes: true }).catch(() => [])
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const path = join(this.outRoot, entry.name)
+      const info = await stat(path).catch(() => undefined)
+      if (info && info.mtimeMs < cutoff) await rm(path, { recursive: true, force: true }).catch(() => undefined)
+    }
+  }
+}
+
+function validateRequest(request: ConvertRequest): void {
+  if (!['file', 'url', 'video', 'text'].includes(request.kind)) {
+    throw new AdapterError('REQUEST_INVALID', `未知的 kind：${String(request.kind)}`, '可用值：file | url | video | text')
+  }
+  if (request.kind === 'text' && !request.text?.trim()) {
+    throw new AdapterError('CONTENT_REQUIRED', 'kind=text 时 text 不能为空。')
+  }
+}
+
+function defaultFilename(request: ConvertRequest): string {
+  if (request.kind === 'text') return 'inline.md'
+  if (request.localPath) return basename(request.localPath)
+  return 'input'
+}
+
+export function safeFilename(value: string): string {
+  const base = basename(value).replace(/[^\w.\-\u4e00-\u9fff]+/g, '_')
+  return base.slice(0, 160) || `input-${Date.now().toString(36)}`
+}
+
+/** Slug used when the DSH layer files a delivery as a knowledge source. */
+export function knowledgeSlugFor(taskId: string, title: string): string {
+  return slug(`${title}-${shortHash(taskId, 6)}`)
+}
+
+export function contentTypeOf(path: string): string {
+  switch (extname(path).toLowerCase()) {
+    case '.md': return 'text/markdown; charset=utf-8'
+    case '.json': return 'application/json; charset=utf-8'
+    case '.png': return 'image/png'
+    case '.jpg':
+    case '.jpeg': return 'image/jpeg'
+    case '.gif': return 'image/gif'
+    case '.webp': return 'image/webp'
+    case '.avif': return 'image/avif'
+    case '.svg': return 'image/svg+xml'
+    case '.tiff': return 'image/tiff'
+    case '.bmp': return 'image/bmp'
+    default: return 'application/octet-stream'
+  }
+}