dsh-convert-core 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NoneFire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# dsh-convert-core
+
+文档转换**内核**：把 Office / OpenDocument / RTF / EPUB / CSV / 文本层 PDF 转成
+**知识就绪 Markdown + 本地图片**，自带 HTTP API 和一个 Vue 3（Options API）可视化控制台。
+它可以**独立运行**，不依赖 DSH。
+
+```bash
+pnpm --filter dsh-convert-core build
+node packages/dsh-convert-core/bin/tita-convert.mjs --port 8787
+# → http://127.0.0.1:8787/
+```
+
+DSH 侧只是它的再封装，见
+[`plugins/dsh-data-domain-knowledge/src/convert`](../../plugins/dsh-data-domain-knowledge/src/convert/host.ts)
+（0018 起转换宿主是 knowledge 插件的子模块，内核仍是本包，并以 `optionalDependencies`
+的形式被懒加载）。
+
+## 引擎：@firecrawl/anydoc
+
+解析全部交给 [`@firecrawl/anydoc`](https://github.com/firecrawl/anydoc)（MIT，Rust 内核，
+官方 Node/Python/WASM binding，本机用 `@firecrawl/anydoc-darwin-arm64` 预编译二进制）。
+
+- **一个依赖覆盖 14 种格式**：doc/docx/docm、ppt/pps/pot/pptx/pptm/ppsx/ppsm、
+  xls/xlsx/xlsm/xlsb、odt/ods/odp、rtf、epub、csv、pdf
+- **按内容识别格式**（PDF 头、RTF 开组、OLE 流名、ZIP mimetype），改错扩展名也能转
+- **没有 Python、没有 torch、没有模型下载、没有外部二进制**，中位数 4.4ms/文档
+- 结构保真：标题层级、`w:numPr` 列表、合并单元格表格、脚注、公式转 LaTeX
+- **错误码精确**：`unsupported / needsOcr / malformed / encrypted / resourceLimit / missingPart / io`，
+  内核原样透出（前缀 `ANYDOC_`）并附上可操作建议
+
+### 唯一的胶水：内嵌图片
+
+Markdown 无法内嵌字节，所以 anydoc 把内嵌图片渲染成它的 **alt 文本**，字节留在
+`document.assets` 上（带 `mediaType` 和 `originPart`）。而知识召回**只认本地相对路径的图片**，
+所以 `src/adapters/anydoc.ts` 做了三件事：
+
+1. 遍历 `document.blocks` 找 `{ kind: 'image', source: { kind: 'asset', assetId } }`，按文档顺序取出图片；
+2. 按内容哈希写成 `assets/img-<sha1_12>.<ext>`；
+3. 把正文里那个 alt 行换成 `![alt](assets/img-….<ext>)`；**找不到唯一占位时追加到文末
+   `## 图片` 小节并记 warning**，而不是猜位置。
+
+非 `image/*` 的内嵌对象不落地，但计数并写 warning，不静默丢弃。
+
+## 分层约定
+
+| 层 | 负责 | 不负责 |
+| --- | --- | --- |
+| 内核（本包） | 解析、任务队列、进度、取消、交付目录、控制台 | 知识库、DSH 工具、用户审批 |
+| DSH 插件 | 设置、Agent 工具、`/convert` 挂载、入库接缝 | 任何解析逻辑 |
+
+内核提供两种集成形态，同一份实现：
+
+```ts
+const running = await startConvertServer({ port: 8787 })            // 独立运行
+
+const service = await createConvertService({ rootDir })            // 嵌入宿主
+const handler = createRequestHandler({ service, basePath: '/convert' })
+```
+
+## 产物契约
+
+```
+convert-out/<taskId>/
+  index.md          front matter + 正文，图片引用为 assets/img-<sha1_12>.<ext>
+  assets/           内容寻址的本地图片
+  manifest.json     来源、引擎与格式、warnings、content_hash、ingest 负载
+```
+
+front matter 与知识录入（0013）对齐：`title / created_at / updated_at` 必填，
+`external_id / source_format / content_hash / parser / source_path /
+source_type_source / source_type_candidates` 由内核如实填写。
+
+**内核不决定 `source_type`**。它只给出候选（`source_type_candidates`），并在
+`manifest.ingest.sourceTypeRequired` 上写明"还没人分类"。这是 0013 的边界。
+
+## 范围
+
+文档类**只做文件类**；网页链接仍在
+[`issues/0017-网页与视频转换能力.md`](../../issues/0017-网页与视频转换能力.md)。
+**本地音视频与图片（`iddoc`）、扫描件轻量 OCR（`scanned`）已落地**；版面/表格/公式级的
+高质量扫描档（docling / MinerU）仍是 0017 的可选档。
+
+`needsOcr` 是文档线划在哪里的地方：扫描版 PDF 在默认路径上会**明确失败**，并把错误建议指向
+`scanned` 档（或 `SCANNED_OCR=1`），而不是悄悄改成云端 OCR。特别地，**不使用 anydoc 的
+`ocr: 'hosted'`** —— 它会把整份文档发往 Firecrawl Parse 云端，与 0015 的本地优先原则冲突。
+
+## 适配器
+
+| 输入 | 适配器 | 说明 |
+| --- | --- | --- |
+| 14 种文档格式（含文本层 PDF） | `anydoc` | 见上；内嵌图片落地到 `assets/` |
+| 音视频（`.mp4 .mov .mkv .webm …`、`.mp3 .m4a .wav …`）与图片（`.png .jpg .webp …`） | `iddoc` | 能力来自内核自带的本地媒体管线 [`src/media/`](docs/media-to-md.md)：**字幕优先**，无字幕时才本地转写（默认**不**下载模型，`IDDOC_ASR=1` 才允许）；图片默认只收录不做 OCR；视频关键帧（均匀采样 + 场景变化 + 内容去重）落地到 `assets/` |
+| 扫描件 / 纯图片页 PDF | `scanned` | 同一包的 `convertScannedDocument()`：`pypdfium2` 逐页渲染 + 本地 `RapidOCR` 识别，`page-0001.png …` 落地为 assets。**显式 opt-in**：默认 `.pdf` 仍走 `anydoc`，只有 `adapter: "scanned"` 或 `SCANNED_OCR=1` 才走本档；不做版面还原 |
+| `.md .markdown .txt .json .tsv .yml .log .adoc .rst .org .tex` | `text` | 直通 + 契约归一化（重写 front matter） |
+
+未登记扩展名只有在**字节确实是文本**（无 NUL、UTF-8 可解码）时才走 `text`，
+否则返回 `FORMAT_UNSUPPORTED` 并列出支持的格式。
+
+`iddoc` 与 `scanned` 是**需要外部依赖**的两个适配器：`iddoc` 要 `ffmpeg`/`ffprobe`
+（转写/OCR 档还要 `uvx`），`scanned` 只要 `uvx`。缺依赖时按既有约定返回
+`DEPENDENCY_MISSING` + 安装命令，能力上报里如实写 `available: false`，不静默降级。
+
+## API
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/api/health` | 服务与交付根目录 |
+| `GET` | `/api/capabilities` | 适配器可用性、引擎版本、支持的扩展名 |
+| `POST` | `/api/tasks` | 受理任务：JSON（`text` / `local_path`）、原始字节、或 `multipart/form-data` |
+| `GET` | `/api/tasks` | 任务列表 |
+| `GET` | `/api/tasks/:id` | 任务详情（含 `ingest` 负载） |
+| `POST` | `/api/tasks/:id/cancel` | 取消（删除半成品交付） |
+| `POST` | `/api/tasks/:id/retry` | 重试（复用已落盘的输入） |
+| `GET` | `/api/tasks/:id/markdown` | 交付的 `index.md` |
+| `GET` | `/api/tasks/:id/files/<rel>` | 交付目录内任意文件（拒绝路径穿越） |
+| `GET` | `/api/events` | SSE 任务事件流 |
+
+```bash
+# 内联文本
+curl -X POST localhost:8787/api/tasks -H 'content-type: application/json' \
+  -d '{"kind":"text","title":"标题","text":"# 内容"}'
+
+# 本机文件（内核负责读取、限流、清理）
+curl -X POST localhost:8787/api/tasks -H 'content-type: application/json' \
+  -d '{"kind":"file","local_path":"/abs/path/spec.docx"}'
+
+# 上传
+curl -X POST "localhost:8787/api/tasks?kind=file" -F "file=@spec.docx"
+```
+
+## 控制台
+
+`web/index.html` + `web/app.js`，**Vue 3 Options API、零构建**：`vue.global.prod.js` 与
+lucide 图标集由 `scripts/vendor.mjs` 在构建时从 npm 包拷成静态资源（图标以纯 SVG map
+注入，避免 `createIcons()` 在 Vue 背后替换 DOM 节点）。
+
+之所以不用 SPA 工具链：内核必须能被 `node bin/tita-convert.mjs` 直接拉起，并且
+DSH 插件要把它当静态页原样挂载。代价是没有 shadcn/Tailwind；DSH 侧的 React 面板
+用 `@tita-data-agent/ui` 的 shadcn 封装（见 AGENTS.md 的组件约定）。
+
+## 设计取舍
+
+- **本地优先**：全链路在本机完成，不调用任何云端解析；引擎没有网络代码。
+- **图片必须落地**：见上「唯一的胶水」。
+- **可取消**：任务用 `AbortController`，取消后删除半成品交付目录。
+- **进程重启可恢复**：任务状态落 `tasks.json`；重启时把 `running/queued` 标为
+  `INTERRUPTED_BY_RESTART` 并保留已落盘的输入，重试不必重来。
+- **不伪造成功**：引擎的错误码原样透出，`needsOcr` / `encrypted` / `resourceLimit`
+  各自带建议，没有「转成功但内容为空」的分支。

package/bin/media-to-md.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * media-to-md —— 命令行入口。
+ *
+ * 与库同一份实现:CLI 只负责参数解析、把产物写盘、以及把错误(含 suggestion)说人话。
+ *
+ * 用法:
+ *   media-to-md <file> [--out <dir>] [--mode auto|subtitle-only|transcribe|frames-only]
+ *                [--model small|large-v3-turbo|/path/to/model] [--lang zh]
+ *                [--samples 12] [--max-frames 40] [--scene 0.3]
+ *                [--allow-model-download] [--ocr-frames] [--image-ocr] [--title "..."]
+ *                [--uvx <path>] [--python 3.12] [--keep-scratch] [--print]
+ */
+import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, extname, join, resolve } from 'node:path'
+import { convertMedia, convertScannedDocument, MediaToMarkdownError } from '../lib/media/index.js'
+
+function parseArgs(argv) {
+  const options = { mode: 'auto', samples: 12, maxFrames: 40, scene: 0.3 }
+  const takesValue = new Set(['--out', '--mode', '--model', '--lang', '--samples', '--max-frames', '--scene', '--title', '--uvx', '--python', '--dpi', '--max-pages'])
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--allow-model-download') options.allowModelDownload = true
+    else if (arg === '--ocr-frames') options.ocrFrames = true
+    else if (arg === '--image-ocr') options.imageOcr = true
+    else if (arg === '--scanned-pdf') options.scannedPdf = true
+    else if (arg === '--no-page-images') options.noPageImages = true
+    else if (arg === '--keep-scratch') options.keepScratch = true
+    else if (arg === '--print') options.print = true
+    else if (arg === '--help' || arg === '-h') options.help = true
+    else if (takesValue.has(arg)) {
+      const value = argv[i + 1]
+      if (value === undefined) throw new Error(`${arg} 需要一个值`)
+      i += 1
+      options[arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = value
+    } else if (arg.startsWith('-')) throw new Error(`未知参数:${arg}`)
+    else if (!options.file) options.file = arg
+    else throw new Error(`多余的位置参数:${arg}`)
+  }
+  return options
+}
+
+function usage() {
+  return [
+    'media-to-md —— 本地音视频/图片 → Markdown + 图片(不调用云端或大模型)',
+    '',
+    '用法: media-to-md <file> [选项]',
+    '',
+    '选项:',
+    '  --out <dir>                产物目录(默认 <文件名>.md-out/)',
+    '  --mode <档位>              auto | subtitle-only | transcribe | frames-only(默认 auto)',
+    '  --model <name|path>        whisper 模型(默认 small;中文建议 large-v3-turbo;也可是本地模型目录)',
+    '  --lang <code>              语言(默认自动检测;中文建议 zh)',
+    '  --allow-model-download     允许在无字幕时下载转写模型(默认不允许,会直接报错并告知体积)',
+    '  --samples <n>              均匀采样帧数(默认 12)',
+    '  --max-frames <n>           关键帧上限(默认 40)',
+    '  --scene <0..1>             场景切换阈值(默认 0.3)',
+    '  --ocr-frames               对关键帧做画面文字 OCR(默认关闭)',
+    '  --image-ocr                对图片输入做 OCR(默认关闭,图片直接收录)',
+    '  --scanned-pdf              走扫描档:纯图片页 PDF → 逐页本地 OCR(默认关闭)',
+    '  --dpi <n>                  扫描档渲染 DPI(默认 150)',
+    '  --max-pages <n>            扫描档最多处理页数(默认 50)',
+    '  --no-page-images           扫描档不落地页图,只保留文字',
+    '  --title <text>             产物标题(默认文件名)',
+    '  --uvx <path> / --python <v> 自定义 uvx 与 Python 版本',
+    '  --keep-scratch             保留中间目录(排障)',
+    '  --print                    同时把 Markdown 打到 stdout',
+  ].join('\n')
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  if (options.help || !options.file) {
+    console.log(usage())
+    process.exit(options.file ? 0 : 2)
+  }
+  const file = resolve(options.file)
+  const title = options.title || basename(file, extname(file))
+  const outDir = resolve(options.out || join(process.cwd(), `${title}.md-out`))
+
+  const onProgress = progress => {
+    const percent = progress.progress === null ? '' : ` ${Math.round(progress.progress * 100)}%`
+    console.error(`[${progress.stage}]${percent} ${progress.message ?? ''}`.trimEnd())
+  }
+  const tools = options.uvx || options.python
+    ? { ...(options.uvx ? { uvxPath: options.uvx } : {}), ...(options.python ? { pythonVersion: options.python } : {}) }
+    : undefined
+
+  const result = options.scannedPdf
+    ? await convertScannedDocument({
+      file,
+      title,
+      maxPages: Number(options.maxPages ?? 50),
+      dpi: Number(options.dpi ?? 150),
+      pageImages: options.noPageImages !== true,
+      ...(tools ? { tools } : {}),
+      ...(options.keepScratch ? { keepScratch: true } : {}),
+      onProgress,
+    })
+    : await convertMedia({
+      file,
+      title,
+      mode: options.mode,
+      asr: {
+        model: options.model ?? 'small',
+        ...(options.lang ? { language: options.lang } : {}),
+        allowModelDownload: options.allowModelDownload === true,
+      },
+      frames: { samples: Number(options.samples), maxFrames: Number(options.maxFrames), sceneThreshold: Number(options.scene) },
+      ...(tools ? { tools } : {}),
+      ...(options.imageOcr ? { imageOcr: true } : {}),
+      ...(options.ocrFrames ? { ocrFrames: true } : {}),
+      ...(options.keepScratch ? { keepScratch: true } : {}),
+      onProgress,
+    })
+
+  await mkdir(join(outDir, 'assets'), { recursive: true })
+  for (const asset of result.assets) {
+    await writeFile(join(outDir, asset.rel), asset.data)
+  }
+  const frontMatter = [
+    '---',
+    `title: ${JSON.stringify(result.title)}`,
+    `source_format: ${result.meta.sourceFormat}`,
+    `source_file: ${file}`,
+    `duration: ${result.meta.durationSeconds.toFixed(2)}`,
+    `transcript_source: ${result.meta.transcriptSource}`,
+    `parser: media-to-md@0.1.0/${result.meta.sourceFormat}`,
+    `external_id: ${result.externalId}`,
+    `generated_at: ${new Date().toISOString()}`,
+    '---',
+    '',
+  ].join('\n')
+  await writeFile(join(outDir, 'index.md'), `${frontMatter}${result.markdown}\n`, 'utf8')
+  if (result.transcript.cues.length > 0) {
+    const stamp = (seconds) => {
+      const value = Number.isFinite(seconds) ? Math.max(0, seconds) : 0
+      const total = Math.floor(value)
+      const ms = Math.floor((value % 1) * 1000)
+      const hh = String(Math.floor(total / 3600)).padStart(2, '0')
+      const mm = String(Math.floor((total % 3600) / 60)).padStart(2, '0')
+      const ss = String(total % 60).padStart(2, '0')
+      return `${hh}:${mm}:${ss},${String(ms).padStart(3, '0')}`
+    }
+    const srt = result.transcript.cues
+      .map((cue, index) => {
+        const next = result.transcript.cues[index + 1]
+        const end = cue.endSeconds ?? next?.seconds ?? cue.seconds + 2
+        return `${index + 1}\n${stamp(cue.seconds)} --> ${stamp(end)}\n${cue.text}\n`
+      })
+      .join('\n')
+    await writeFile(join(outDir, 'transcript.srt'), srt, 'utf8')
+  }
+
+  console.log(`完成 → ${outDir}`)
+  console.log(`  index.md  assets/${result.assets.length} 个  warnings: ${result.warnings.map(w => w.code).join(', ') || '（无）'}`)
+  if (options.print) console.log(`\n${result.markdown}`)
+}
+
+main().catch(error => {
+  if (error instanceof MediaToMarkdownError) {
+    console.error(`\n失败 [${error.code}] ${error.message}`)
+    if (error.suggestion) console.error(`建议:${error.suggestion}`)
+  } else {
+    console.error(`\n失败:${error instanceof Error ? error.message : String(error)}`)
+  }
+  process.exit(1)
+})

package/bin/tita-convert.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Standalone kernel launcher.
+ *
+ *   tita-convert --port 8787 --root ~/.tita-data-agent/convert
+ *
+ * This is the "kernel first" half of the design: the console it serves is the
+ * same page the DSH plugin embeds, and it works with DSH not installed.
+ */
+
+import { startConvertServer } from '../lib/server.js'
+
+function parseArgs(argv) {
+  const options = {}
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]
+    const [flag, inline] = token.includes('=') ? token.split(/=(.*)/s, 2) : [token, undefined]
+    const next = () => inline ?? argv[++index]
+    switch (flag) {
+      case '--port': case '-p': options.port = Number(next()); break
+      case '--host': options.host = next(); break
+      case '--root': options.rootDir = next(); break
+      case '--base-path': options.basePath = next(); break
+      case '--api-key': options.apiKey = next(); break
+      case '--web-root': options.webRoot = next(); break
+      case '--max-concurrent': options.maxConcurrent = Number(next()); break
+      case '--docling': options.doclingBaseUrl = next(); break
+      case '--prefer-docling': options.preferDocling = true; break
+      case '--help': case '-h': options.help = true; break
+      case '--version': case '-v': options.version = true; break
+      default:
+        if (flag?.startsWith('-')) {
+          console.error(`未知参数：${flag}`)
+          options.help = true
+        }
+    }
+  }
+  return options
+}
+
+const HELP = `tita-convert — 多格式转换内核（独立运行）
+
+用法
+  tita-convert [选项]
+
+选项
+  -p, --port <n>            监听端口（默认 8787）
+      --host <host>         监听地址（默认 127.0.0.1，只对本机开放）
+      --root <dir>          任务与交付根目录（默认 ~/.tita-data-agent/convert）
+      --base-path <path>    挂载前缀（默认空，即根路径）
+      --api-key <key>       要求 X-Api-Key 头
+      --max-concurrent <n>  并发转换数（默认 2）
+      --docling <url>       docling-serve 地址，启用高精度档
+      --prefer-docling      有 docling 地址时优先使用它
+  -h, --help                显示帮助
+  -v, --version             显示版本
+
+控制台
+  启动后打开 http://127.0.0.1:<port>/ 即可看到 Vue3 转换面板。
+`
+
+const options = parseArgs(process.argv.slice(2))
+if (options.help) {
+  console.log(HELP)
+  process.exit(0)
+}
+if (options.version) {
+  const { readFile } = await import('node:fs/promises')
+  const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'))
+  console.log(pkg.version)
+  process.exit(0)
+}
+
+const running = await startConvertServer(options)
+console.log(`Tita 转换内核已启动：${running.url}`)
+console.log(`  控制台  ${running.url}/`)
+console.log(`  API     ${running.url}/api/health`)
+console.log(`  交付目录 ${running.service.outDir}`)
+
+const shutdown = async () => {
+  await running.close()
+  process.exit(0)
+}
+process.on('SIGINT', () => { void shutdown() })
+process.on('SIGTERM', () => { void shutdown() })

package/docs/media-to-md.md

@@ -0,0 +1,143 @@
+# 本地媒体管线（`src/media/`）
+
+把**本地**音视频 / 图片 / 扫描件 PDF 转成「知识就绪 Markdown + 本地图片」。**纯本地:不调用云端 API、不调用大模型。**
+
+```
+<file> ──ffmpeg──→ 关键帧(场景变化 + 均匀采样 + 内容去重)+ 音轨/字幕轨
+        ├─ 有字幕 ─→ 字幕轨/旁挂 .srt  ─────────────────┐
+        └─ 无字幕 ─→ faster-whisper 本地转写(可选档) ──┤
+        图片 ─────→ 直接收录(默认不 OCR) ──────────────┤
+扫描件 PDF ──────→ pypdfium2 逐页渲染 + RapidOCR 逐页识别 ┴─→ Markdown + assets/
+                  (轻量档:见 `convertScannedDocument()`,不出网、不做版面还原)
+```
+
+## 它不涉及大模型 —— 但需要几个**专用小模型**
+
+| 环节 | 用的是什么 | 是不是大模型 |
+| --- | --- | --- |
+| 抽帧 / 抽轨 / 拆音频 | `ffmpeg`、`ffprobe` | 不是,纯信号处理 |
+| PDF 逐页渲染 | `pypdfium2`(自带 pdfium,无需系统 poppler) | 不是,纯渲染 |
+| 语音 → 文字 | `faster-whisper`(whisper 模型) | **不是 LLM**。语音识别专用模型,本地 CPU;tiny 75MB / small 460MB / large-v3-turbo ≈1.5GB |
+| 画面文字 / 扫描页文字 → 文字 | `RapidOCR`(ONNX) | **不是 LLM**。OCR 小模型,几十 MB |
+| 拼装 Markdown | 本包模板 | 纯规则 |
+
+模型只在首次使用时下载一次,之后完全离线。**是否允许下载由调用方显式决定**(`asr.allowModelDownload`,默认 `false`)—— 没字幕又没允许下载时,直接抛 `ASR_MODEL_REQUIRED` 并写清"要下多大"。
+
+## 安装与构建
+
+```bash
+pnpm --filter dsh-convert-core build
+```
+
+依赖:系统 `ffmpeg`/`ffprobe`(必需);`uvx`(只有转写 / OCR 档需要,`uv` 自带)。
+
+## 库用法
+
+```ts
+// 内核内：从 ../media/index.js 导入。单独用也可以走 convert-core 的 ./media 子路径导出。
+import { convertMedia } from 'dsh-convert-core/media'
+
+const result = await convertMedia({
+  file: '/abs/path/clip.mp4',
+  mode: 'auto',                       // auto | subtitle-only | transcribe | frames-only
+  asr: { model: 'large-v3-turbo', language: 'zh', allowModelDownload: true },
+  frames: { samples: 12, maxFrames: 40, sceneThreshold: 0.3 },
+  ocrFrames: false,                   // 关键帧画面文字(默认关)
+  imageOcr: false,                    // 图片 OCR(默认关:图片直接收录)
+  onProgress: p => console.log(p.stage, p.progress),
+})
+// result.markdown  Markdown 正文(不含 front matter)
+// result.assets    [{ rel: 'assets/frame-0001.jpg', data: Buffer, contentType }]
+// result.meta      { sourceFormat, durationSeconds, transcriptSource, … }
+// result.warnings  [{ code, message }]
+```
+
+档位规则:
+
+| mode | 字幕 | 转写 | 说明 |
+| --- | --- | --- | --- |
+| `auto`(默认) | 优先 | 仅当允许下载模型 | 有字幕就绝不碰模型 |
+| `subtitle-only` | 只用 | 永不 | 没字幕就是"没有逐字稿",不报错 |
+| `transcribe` | 跳过 | 强制 | 必须允许下载模型 |
+| `frames-only` | 跳过 | 跳过 | 只要关键帧 |
+
+## 扫描件轻量档:`convertScannedDocument()`
+
+纯图片页 PDF(扫描件)走这条路 —— 它解决的**唯一**问题是"图片页里的字读不出来"。
+
+```ts
+import { convertScannedDocument } from 'dsh-convert-core/media'
+
+const result = await convertScannedDocument({
+  file: '/abs/scan.pdf',
+  dpi: 150,          // 渲染 DPI(默认 150)
+  maxPages: 50,      // 上限,超出写 warning,不静默截断
+  pageImages: true,  // 逐页图片落地为 assets/page-NNNN.png
+})
+// result.pages → [{ index, rel, width, height, text, ocrLines }]
+```
+
+**它不做/不承诺什么**(这是刻意的):
+
+- **不做版面还原**:输出是"第 N 页 + 该页图片 + 该页文字",顺序 = 页序;多栏、表格、公式会乱;
+- **不引入 docling / PaddleOCR 框架 / MinerU**:那是 `issues/0017` 的"可选高质量档"(几 GB ~ 20 GB 依赖);
+- **不联网**:只有两个本地组件 —— `pypdfium2`(渲染)与 `RapidOCR`(识别);
+- **不判断该不该用**:是"这份 PDF 没有文本层"才走这里;默认路径应当先让文档引擎试文本层。
+
+## CLI
+
+```bash
+# 音视频:带中文转写
+node packages/dsh-convert-core/bin/media-to-md.mjs clip.mp4 --lang zh --model large-v3-turbo --allow-model-download
+# → clip.md-out/{index.md, assets/, transcript.srt}
+
+# 扫描件:逐页 OCR(无需任何系统依赖)
+node packages/dsh-convert-core/bin/media-to-md.mjs scan.pdf --scanned-pdf --dpi 200
+# → scan.md-out/{index.md, assets/page-0001.png …}
+```
+
+扫描档相关参数:`--scanned-pdf`、`--dpi <n>`、`--max-pages <n>`、`--no-page-images`。
+
+## 设计取舍
+
+- **抽帧 = 均匀采样 + 场景变化,两路合并再按内容 sha1 去重。** 只靠 `scene` 会漏:口播/图文视频几乎没有硬切(实测:3 段画面的测试片,阈值降到 0.1 也只出 1 帧)。
+- **字幕优先。** 有字幕轨/旁挂 `.srt` 时完全不下载转写模型。
+- **图片默认不 OCR。** 图片直接收录、靠多模态召回(0013 的决定);需要文字时显式开 `imageOcr`。
+- **扫描件只做轻量档,并且要求显式 opt-in。** 先用重的方案会让人误以为"必须装 20 GB 才能读扫描件"。
+- **PDF 渲染用 pypdfium2 而不是 poppler。** `pdftoppm` 是外部二进制,不是每台机器都有(开发机就没有);pypdfium2 是 pip wheel,自带 pdfium,`uvx` 按需拉起。
+- **产物只给正文和 assets。** front matter、写盘、入库都是宿主的事(转换内核写 manifest,CLI 写自己的 front matter),这个包不认识任何宿主。
+- **`externalId` = 文件 sha256**,给宿主做幂等。
+
+## 环境变量
+
+| 变量 | 用途 |
+| --- | --- |
+| `MEDIA_TO_MD_UVX` | uvx 可执行文件(等价 `tools.uvxPath`) |
+| `MEDIA_TO_MD_PYTHON` | uvx 使用的 Python 版本(默认 `3.12`) |
+| `HF_ENDPOINT` | HuggingFace 镜像,国内建议 `https://hf-mirror.com` |
+
+## 排障
+
+- **`Could not create temporary file` / uv 缓存不可写**:把缓存重定向到可写目录:
+  `UV_CACHE_DIR`、`UV_PYTHON_INSTALL_DIR`、`UV_TOOL_DIR`、`UV_TOOL_BIN_DIR`、`XDG_CACHE_HOME`。
+- **模型下载失败(SSL / Server disconnected)**:Python 侧走 HuggingFace 下载不稳定时,用 curl 预先下好模型目录再把 `asr.model` 指向它:
+
+  ```bash
+  DIR=~/.cache/media-to-md/faster-whisper-small && mkdir -p "$DIR"
+  for f in config.json tokenizer.json vocabulary.txt model.bin; do
+    curl -L --retry 3 -o "$DIR/$f" "https://hf-mirror.com/Systran/faster-whisper-small/resolve/main/$f"
+  done
+  ```
+
+- **转写为空**:确认有音轨;`tiny`/`base` 对中文很差,换 `small` 以上。
+
+## 消费者
+
+- `dsh-convert-core` 的 `iddoc` adapter(issue 0017 的 video 档):本包负责能力,内核负责契约与产物目录。
+- CLI / 未来的桌面端。
+
+## 限制
+
+- 长音频未做 VAD 分片与取消后的分片保留(子进程会随 `AbortSignal` 结束)。
+- 说话人分离未接。
+- 网页链接与扫描件 OCR 不在本包范围(见 `issues/0017` 的 `web.ts` / `docling.ts`)。

package/lib/adapters/anydoc.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The document engine: `@firecrawl/anydoc` (MIT, Rust, prebuilt Node binding).
+ *
+ * One adapter replaces what used to be five (pdfjs text-layer reader, mammoth,
+ * the high-quality docling tier, plus the format routing between them). anydoc
+ * covers doc/docx/docm, ppt/pps/pot/pptx/pptm/ppsx/ppsm, xls/xlsx/xlsm/xlsb,
+ * odt/ods/odp, rtf, epub, csv and text-layer pdf, detects the format from the
+ * bytes, and needs no Python, no models and no external binary.
+ *
+ * The one thing it cannot do for us is the 0013 image contract: Markdown has no
+ * way to embed bytes, so an embedded image renders as its alt text while the
+ * bytes stay on `document.assets`. Retrieval only reads local relative image
+ * paths, so this adapter re-materialises every embedded image into `assets/`
+ * and puts a real `![](assets/img-…)` reference back where the document had it.
+ */
+import { type Adapter, type AdapterAvailability } from './types.js';
+export declare const ANYDOC_EXTENSIONS: string[];
+interface AnyDocAsset {
+    id?: number;
+    mediaType?: string;
+    originPart?: string;
+    data?: Uint8Array;
+}
+interface AnyDocInline {
+    kind: string;
+    alt?: string;
+    source?: {
+        kind?: string;
+        assetId?: number;
+        url?: string;
+    };
+    text?: string;
+}
+interface AnyDocBlock {
+    kind: string;
+    content?: AnyDocInline[];
+}
+interface AnyDocDocument {
+    blocks?: AnyDocBlock[];
+    notes?: unknown[];
+    assets?: AnyDocAsset[];
+}
+interface AnyDocModule {
+    toDocument(bytes: Uint8Array): Promise<AnyDocDocument>;
+    toMarkdown(path: string, options?: Record<string, unknown>): Promise<string>;
+    toMarkdownBytes(bytes: Uint8Array, format?: string): Promise<string>;
+    formatFromBytes(bytes: Uint8Array): string | null;
+    formatFromPath(path: string): string | null;
+}
+/** Load the binding once; the platform binary ships as an optional dependency. */
+export declare function loadAnydoc(): Promise<AnyDocModule>;
+export declare function anydocAvailability(): Promise<AdapterAvailability>;
+export interface ImagePlacement {
+    markdown: string;
+    placed: number;
+    appended: number;
+    warnings: string[];
+}
+/**
+ * Put real image references back into the Markdown.
+ *
+ * anydoc renders an embedded image as its alt text, so placement is a match on
+ * that text. A standalone-line match is used only when it is unambiguous;
+ * anything that cannot be located is appended under a `## 图片` heading rather
+ * than guessed at, and the count is reported.
+ */
+export declare function placeImageReferences(markdown: string, images: Array<{
+    rel: string;
+    alt: string;
+}>): ImagePlacement;
+export declare const anydocAdapter: Adapter;
+export {};
+//# sourceMappingURL=anydoc.d.ts.map

package/lib/adapters/anydoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anydoc.d.ts","sourceRoot":"","sources":["../../src/adapters/anydoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,OAAO,EAAgB,KAAK,OAAO,EAAE,KAAK,mBAAmB,EAA+D,MAAM,YAAY,CAAA;AAE9I,eAAO,MAAM,iBAAiB,UAW7B,CAAA;AAED,UAAU,WAAW;IACnB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,UAAU,CAAA;CAClB;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;CACzB;AAED,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAA;CACvB;AAED,UAAU,YAAY;IACpB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IACtD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC5E,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACpE,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAA;IACjD,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAC5C;AAmBD,kFAAkF;AAClF,wBAAsB,UAAU,IAAI,OAAO,CAAC,YAAY,CAAC,CAqBxD;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAWvE;AA0BD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,cAAc,CAiClH;AAwJD,eAAO,MAAM,aAAa,EAAE,OAQ3B,CAAA"}