dsh-file-convert 0.4.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 dsh-file-convert contributors
+
+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.
+
+---
+
+Third-party notice: dsh-file-convert does not distribute any external binaries.
+It relies on npm-shipped libraries (sharp, pdfjs-dist, @napi-rs/canvas) and,
+in future versions, on separately installed tools (FFmpeg, LibreOffice,
+Poppler), each licensed under its own terms.

package/README.md

@@ -0,0 +1,225 @@
+# dsh-file-convert
+
+**Local-first file conversion for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).**
+
+Convert images, PDFs and data files directly inside your DSH agent sessions — no API keys, no uploads, no servers, no token cost for the conversion itself. Files never leave your machine.
+
+> **Unofficial community plugin.** Not affiliated with or endorsed by DeepSeek.
+
+## Why
+
+Agents constantly need file conversions: "turn this PDF into images", "give me that JSON as YAML", "convert all JPGs in this folder to WebP". Instead of shelling out or pasting data around, `dsh-file-convert` gives your agent seven purpose-built tools backed by battle-tested local libraries.
+
+- ✅ **Local execution** — files never leave the machine
+- ✅ **No API key, no server, no conversion tokens**
+- ✅ **Natural language friendly** — the agent calls the tools, you just ask
+- ✅ **Batch conversions** with a compact summary
+- ✅ **Honest failures** — missing dependency, unsupported pair, existing output: every error says exactly why
+- ✅ **Images, PDF and data need zero external binaries** — prebuilt npm packages only. Media needs one tool (ffmpeg), clearly reported when missing
+
+## Supported conversions
+
+| Source | Targets |
+| --- | --- |
+| PNG, JPG, WEBP | PNG, JPG, WEBP (any-to-any) |
+| SVG | PNG, JPG, WEBP |
+| PDF | PNG, JPG, TXT |
+| JSON | YAML, CSV |
+| YAML | JSON, CSV |
+| DOCX, PPTX, XLSX | PDF |
+| PDF | PNG, JPG, TXT, DOCX (experimental); TXT supports OCR for scanned PDFs |
+| MP4 | GIF, MP3 |
+| MOV | MP4 |
+| WAV | MP3 |
+| CSV | JSON, YAML |
+
+26 conversions. Images, PDF and data work out of the box via `npm install`. Optional tools unlock the rest, each clearly reported by `list_conversions` when missing:
+
+- **FFmpeg** -> media rows. Install it system-wide (preferred for untrusted media), **or ask the agent to run `install_media_dependencies`** — it downloads pinned current builds (FFmpeg 6.1.1, ~56 MB total, one time) into the plugin cache, sha256-verified, from the npmmirror binary CDN with the GitHub release as fallback.
+- **LibreOffice** -> DOCX/PPTX/XLSX to PDF. `winget install TheDocumentFoundation.LibreOffice` / `brew install --cask libreoffice` / `apt install libreoffice`.
+- **Ghostscript** -> PDF compression in `optimize_file`.
+- **Python + pdf2docx** -> the experimental PDF to DOCX row (`pip install pdf2docx`).
+- **Tesseract** (optional) -> faster OCR for scanned PDFs; without it the bundled tesseract.js is used and its language data is fetched explicitly via `install_ocr_dependencies` (`winget install UB-Mannheim.TesseractOCR`).
+
+## Install
+
+Inside a DSH profile — three ways, easiest first:
+
+```sh
+# 1. from npm (once published)
+dsh plugin --profile default add dsh-file-convert
+
+# 2. straight from GitHub (a `prepare` build runs; allow it once)
+dsh plugin --profile default add github:zzy-12345678/dsh-file-convert
+```
+
+Git installs may ask you to allow the build step in the profile's `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  dsh-file-convert: true
+```
+
+From a local checkout (e.g. while hacking on it):
+
+```sh
+git clone https://github.com/zzy-12345678/dsh-file-convert
+cd dsh-file-convert && npm install && npm run build
+dsh plugin --profile default add /absolute/path/to/dsh-file-convert
+```
+
+Then restart DSH (`dsh web` or your usual entry point). All seven tools appear automatically.
+
+## The seven tools
+
+### `convert_file`
+
+Convert one file.
+
+```json
+{ "input": "/tmp/report.pdf", "output_format": "png", "dpi": 200 }
+```
+
+```
+Converted: /tmp/report.pdf (pdf) -> /tmp/report.png (png)
+1.2 MB -> 431.0 KB in 1.4s
+```
+
+- Default output: next to the input file, same base name, new extension.
+- Multi-page PDFs produce `<name>-<page>.<ext>` for every page; `pages: "1-3,5"` selects pages (outputs keep their real page numbers, text joins only the selection).
+- Scanned PDFs → TXT: `ocr: true` (optionally `ocr_lang`, default `chi_sim+eng`) recognizes the rendered pages instead of the text layer. Engine priority: a local Tesseract CLI, then the bundled tesseract.js (whose language data is never downloaded implicitly — run `install_ocr_dependencies` first, about 10-30 MB per language).
+- Existing outputs are refused unless `overwrite: true`.
+- Options: `output`, `overwrite`, `quality` (1–100), `dpi` (PDF/SVG rasterization), `pages`, `ocr`, `ocr_lang`.
+
+### `batch_convert`
+
+Convert every matching file in a directory (top level).
+
+```json
+{ "input_dir": "/home/me/Pictures", "output_format": "webp" }
+```
+
+```
+Batch convert in /home/me/Pictures -> WEBP
+Converted: 18, skipped: 2, failed: 0
+Output dir: /home/me/Pictures/output
+```
+
+- `input_format` filters by source format; omit it to auto-detect every convertible file.
+- `output_dir` defaults to `<input_dir>/output`.
+- Existing outputs are **skipped** (not overwritten) unless `overwrite: true`.
+
+### `inspect_file`
+
+Facts before action, detected from file content — not just the extension:
+
+```json
+{ "input": "/tmp/scan.pdf" }
+```
+
+```json
+{ "kind": "pdf", "pages": 24, "encrypted": false, "likelyScanned": true, "bytes": 13000000 }
+```
+
+### `optimize_file`
+
+Shrink a file toward a target size instead of converting it:
+
+```json
+{ "input": "video.mp4", "target_size_mb": 20 }
+```
+
+```
+Optimized: video.mp4 (mp4) -> video-min.mp4
+18.3 MB -> 19.7 MB (target 20 MB) in 41.2s
+Applied: two-pass x264: video 512k + audio 128k over 185.0s
+```
+
+- MP4/MOV: two-pass x264, the video bitrate is computed from the target (audio 128k, dropping to 64k for tight targets); output is always MP4. Requires ffmpeg + ffprobe.
+- JPG/WEBP: binary-searches the highest encoder quality that fits; PNG uses palette reduction. No external tools needed.
+- PDF: Ghostscript quality presets (printer/ebook/screen), first preset that fits the target wins; requires Ghostscript.
+- Targets below what the codec can physically reach are refused with the achievable minimum.
+- GIF optimization is not supported yet.
+
+### `install_media_dependencies`
+
+One-call media setup: downloads pinned FFmpeg 6.1.1 static builds (ffmpeg + ffprobe) into the plugin cache (`~/.dsh-file-convert/bin`), verifies the pinned sha256, and proves the binaries run before reporting success. Served from the npmmirror binary CDN with the GitHub release as a byte-identical fallback. System installs keep priority over the cache. Ask the user for consent first — it is a sizable download.
+
+### `install_ocr_dependencies`
+
+Downloads the tesseract.js language data (about 10-30 MB per language, `chi_sim+eng` by default) into the plugin cache, so `ocr: true` works without a local Tesseract. Skips when a local Tesseract CLI is installed or the data is already cached. Ask the user for consent first — conversions never download language data implicitly.
+
+### `list_conversions`
+
+All 26 conversions with their live availability on *this* machine — unavailable rows name the missing tool and how to install it. Images, PDF and data rows are usable out of the box; media, office and PDF-compression rows depend on the optional tools (media can even be set up by the agent via `install_media_dependencies`).
+
+## Plugin config
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `quality` | `85` | Default JPEG/WebP quality (1–100) |
+| `dpi` | `150` | Default rasterization DPI for PDF inputs |
+| `timeoutMs` | `120000` | Cooperative timeout for one conversion |
+| `maxInputMb` | `2048` | Refuse inputs above this size (MB) |
+| `maxPdfPages` | `200` | Full-document PDF rasterization refuses more pages; use `pages` for larger documents |
+| `maxOutputPixels` | `16000000` | Clamp rasterized pixels per page (width × height) to this budget |
+| `batchMaxFiles` | `500` | Max files examined per `batch_convert` run; beyond it the summary reports what was skipped instead of silently capping |
+| `outputRoots` | `[]` | When non-empty, explicit `output` paths must resolve inside one of these directories (recommended for shared deployments; the default next-to-input output is always exempt) |
+| `ffmpegPath` / `ffprobePath` | - | Explicit binary paths when ffmpeg is not on PATH (common on Windows) |
+| `sofficePath` / `ghostscriptPath` / `pythonPath` / `tesseractPath` | - | Explicit paths for the optional tools, overriding auto-detection |
+
+## Architecture
+
+```
+                         DSH
+                          │
+                    dsh-file-convert
+           ┌──────────────┴──────────────┐
+     src/index.ts                   src/core/            ← the whole engine,
+     (thin DSH glue:                (no DSH imports)       testable standalone
+      name/inject/apply,                 │
+      Config schema,                ConversionRouter
+      7 tool registrations)              │
+                       ┌─────────────────┼─────────────────┐
+                       ↓                 ↓                 ↓
+                 ImageConverter     PdfConverter      DataConverter
+                    sharp          pdfjs-dist         js-yaml
+                 (libvips npm)   @napi-rs/canvas    csv-parse / stringify
+                                                     MediaConverter        OfficeConverter
+                                                        ffmpeg (detected)      LibreOffice (detected)
+                                                     PdfToDocxConverter    optimize_file/pdf
+                                                     python + pdf2docx         Ghostscript (detected)
+```
+
+- **Declarative matrix**: every conversion is a data row (`{ from, to }`) on its converter. Routing, `list_conversions` and dependency checks are all derived from it.
+- **Detection**: content first - binary magic (file-type), SVG sniffing, and JSON parsing (plus a YAML document-marker guess for extension-less files) - with the extension as fallback. Conflicts resolve in favor of the content, with a warning.
+- **Core is DSH-agnostic**: `src/core` never imports Cordis/DSH, so the engine can be unit-tested, wrapped in a CLI, or served over MCP later. If the DSH developer-preview API shifts, only the glue layer changes.
+- **Dependencies**: external binaries (FFmpeg, LibreOffice, Poppler) are *detected, never auto-installed* — `list_conversions` reports them and prints per-platform install hints. The interface is already in place (`BinaryDependency`).
+
+## Development
+
+```sh
+npm install
+npm run build     # tsc -> lib/
+npm test          # vitest, 31 tests
+npm run smoke     # end-to-end against lib/
+```
+
+Add a conversion = add one capability row + implement it in a converter. Add a backend = implement the `Converter` interface and register it in `createRouter()`.
+
+## Fidelity & safety expectations
+
+- **Lossy by nature**: PDF→DOCX (experimental), OCR and office→PDF are reconstructions — expect layout and recognition differences. `inspect_file`'s `likelyScanned` flag tells you when OCR is the right tool, and results carry warnings.
+- **Cached ffmpeg builds**: the download convenience installs pinned sha256-verified FFmpeg 6.1.1 static builds. For untrusted media, a current system FFmpeg takes priority — prefer it in security-sensitive setups.
+- **Not a sandbox**: `outputRoots` resolves symlinks and resource limits (`maxInputMb`, `maxPdfPages`, `maxOutputPixels`, `batchMaxFiles`) cap runaway jobs, but the default next-to-input output is intentionally exempt from roots, and an agent that may write files can always write somewhere. For hostile multi-tenant use, add OS-level isolation on top.
+
+## Roadmap
+
+- ~~V0.2 — Media (FFmpeg)~~ **shipped**: MP4→GIF/MP3, WAV→MP3, MOV→MP4, plus `optimize_file` with target-size two-pass encoding.
+- ~~V0.3 — Office + PDF tooling~~ **shipped**: DOCX/PPTX/XLSX→PDF via LibreOffice, experimental PDF→DOCX via python pdf2docx, PDF compression via Ghostscript; on-demand dependency downloads with an automatic CN mirror.
+- ~~V0.4 — OCR (Tesseract)~~ **shipped**: PDF→TXT supports `ocr: true` (optional `ocr_lang`), local Tesseract CLI first with the bundled tesseract.js as fallback, language data fetched explicitly via `install_ocr_dependencies`.
+- Later: OCR → DOCX for scanned PDFs, conversion chains (PPTX→PDF→PNG), video downscaling in `optimize_file`, resize/rotate image options.
+
+## License
+
+[MIT](./LICENSE). dsh-file-convert distributes no external binaries; runtime libraries (sharp, pdfjs-dist, @napi-rs/canvas, js-yaml, csv) are installed from npm under their own licenses.

package/README.zh-CN.md

@@ -0,0 +1,203 @@
+# dsh-file-convert
+
+**为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 打造的本地优先文件转换插件。**
+
+在 DSH Agent 会话里直接转换图片、PDF 和数据文件——不需要 API Key，不上传文件，不需要服务器，转换本身零 Token 消耗，文件永远不离开你的电脑。
+
+> **非官方社区插件。** 与 DeepSeek 官方无隶属关系。
+
+## 为什么做这个
+
+Agent 日常需要各种格式转换："把这个 PDF 转成图片"、"把这个 JSON 变成 YAML"、"把文件夹里所有 JPG 转成 WebP"。`dsh-file-convert` 提供七个专用 tool，背后是久经考验的本地库，你只需用自然语言提需求。
+
+- ✅ **本地执行** —— 文件不出机器
+- ✅ **不要 API Key、不要服务器、不耗转换 Token**
+- ✅ **自然语言友好** —— Agent 调 tool，你直接说话
+- ✅ **批量转换**，返回紧凑的结果摘要
+- ✅ **失败必有原因** —— 缺依赖 / 不支持的组合 / 输出已存在，每个错误都说明清楚
+- ✅ **图片/PDF/数据零外部依赖** —— npm 预编译包装完即用；音视频只依赖 ffmpeg，缺了会明确提示
+
+## 当前支持的转换
+
+| 输入 | 可输出 |
+| --- | --- |
+| PNG、JPG、WEBP | PNG、JPG、WEBP（任意互转） |
+| SVG | PNG、JPG、WEBP |
+| PDF | PNG、JPG、TXT |
+| JSON | YAML、CSV |
+| YAML | JSON、CSV |
+| DOCX、PPTX、XLSX | PDF |
+| PDF | PNG、JPG、TXT、DOCX（实验性）；TXT 支持扫描件 OCR |
+| MP4 | GIF、MP3 |
+| MOV | MP4 |
+| WAV | MP3 |
+| CSV | JSON、YAML |
+
+共 26 种转换。图片/PDF/数据 `npm install` 后开箱即用；其余按"装一个工具解锁一类"的节奏，缺什么 `list_conversions` 都会明说：
+
+- **FFmpeg** -> 音视频四条。装系统级（处理不可信媒体时优先），**或让 Agent 跑 `install_media_dependencies`**——下载固定的现代构建（FFmpeg 6.1.1，约 56 MB，一次性）到插件缓存，sha256 校验，npmmirror 二进制 CDN 优先、GitHub release 自动回退。
+- **LibreOffice** -> DOCX/PPTX/XLSX 转 PDF。`winget install TheDocumentFoundation.LibreOffice` / `brew install --cask libreoffice` / `apt install libreoffice`。
+- **Ghostscript** -> `optimize_file` 的 PDF 压缩。
+- **Python + pdf2docx** -> 实验性的 PDF 转 DOCX（`pip install pdf2docx`）。
+- **Tesseract**（可选）-> 更快的扫描件 OCR；不装则用内置 tesseract.js，其语言数据通过 `install_ocr_dependencies` 显式下载（`winget install UB-Mannheim.TesseractOCR`，记得勾选 chi_sim 语言组件）。
+
+## 安装
+
+在 DSH profile 中——三种方式，按省事程度排序：
+
+```sh
+# 1. 从 npm 安装（发包后可用）
+dsh plugin --profile default add dsh-file-convert
+
+# 2. 直接从 GitHub 安装（会执行一次构建，需放行）
+dsh plugin --profile default add github:zzy-12345678/dsh-file-convert
+```
+
+Git 安装可能需要在 profile 的 `pnpm-workspace.yaml` 里放行构建步骤：
+
+```yaml
+allowBuilds:
+  dsh-file-convert: true
+```
+
+本地开发安装：
+
+```sh
+git clone https://github.com/zzy-12345678/dsh-file-convert
+cd dsh-file-convert && npm install && npm run build
+dsh plugin --profile default add /absolute/path/to/dsh-file-convert
+```
+
+重启 DSH（`dsh web` 或你的常规入口）后，七个 tool 自动出现。
+
+## 七个 Tool
+
+### `convert_file` —— 单文件转换
+
+```json
+{ "input": "/tmp/report.pdf", "output_format": "png", "dpi": 200 }
+```
+
+- 默认输出到源文件同目录、同名换后缀。
+- 多页 PDF 会为每一页输出 `<文件名>-<页码>.<后缀>`；`pages: "1-3,5"` 选择页码（输出保留真实页码，TXT 只拼接所选页）。
+- 扫描件 PDF → TXT：`ocr: true`（可选 `ocr_lang`，默认 `chi_sim+eng`）对渲染页面做识别，而不是读文本层。引擎优先本机 Tesseract CLI，其次插件内置的 tesseract.js（语言数据不会随转换隐式下载——先让 Agent 跑 `install_ocr_dependencies`，约每种语言 10-30 MB）。
+- 输出文件已存在时默认拒绝，需显式 `overwrite: true`。
+- 可选参数：`output`、`overwrite`、`quality`（1–100）、`dpi`（PDF/SVG 光栅化）、`pages`、`ocr`、`ocr_lang`。
+
+### `batch_convert` —— 目录批量转换
+
+```json
+{ "input_dir": "/home/me/Pictures", "output_format": "webp" }
+```
+
+- `input_format` 可按源格式过滤；不传则自动探测所有可转换文件。
+- `output_dir` 默认为 `<input_dir>/output`。
+- 已存在的输出默认**跳过**（不覆盖），`overwrite: true` 时替换。
+
+### `inspect_file` —— 转换前先看清楚
+
+基于文件内容（magic bytes）而非扩展名识别格式：
+
+```json
+{ "kind": "pdf", "pages": 24, "encrypted": false, "likelyScanned": true, "bytes": 13000000 }
+```
+
+图片返回尺寸/通道数，数据文件返回记录数。`likelyScanned: true` 提示这可能是扫描件——转 TXT 时加 `ocr: true` 即可识别。
+
+### `optimize_file` —— 按目标体积压缩
+
+PDF 走 Ghostscript 三档预设（printer/ebook/screen）自动迭代：某档已达标就停，全超则保留最小档并如实告知。需要 Ghostscript（`winget install ArtifexSoftware.GhostScript`）。
+
+```json
+{ "input": "video.mp4", "target_size_mb": 20 }
+```
+
+- MP4/MOV：两遍编码 x264，按目标体积反推视频码率（音频 128k，紧张时降到 64k），输出统一为 MP4，需要 ffmpeg + ffprobe。
+- JPG/WEBP：二分搜索能塞进目标体积的最高编码质量；PNG 走调色板压缩。图片不需要任何外部工具。
+- 目标体积低于编码物理下限时直接拒绝，并给出可达的最低体积。
+- GIF/PDF 压缩暂不支持。
+
+### `install_media_dependencies` —— 一键补齐媒体依赖
+
+下载固定的 FFmpeg 6.1.1 静态构建（ffmpeg + ffprobe 两个 ~28 MB 文件）到插件缓存（`~/.dsh-file-convert/bin`），校验钉死的 sha256，并真实执行一次二进制确认可用后才报告成功。npmmirror 二进制 CDN 优先，GitHub release 为字节一致的回退源。系统安装的 ffmpeg 优先于缓存。体积可观，调用前请先征得用户同意。
+
+默认从 `npmmirror.com` 镜像下载固定版本的 `@ffmpeg-installer` / `@ffprobe-installer` 二进制到插件缓存（`~/.dsh-file-convert/bin`），校验 sha512 完整性，并真实执行一次二进制确认可用后才报告成功（npmjs.org 自动回退，`registry` 参数可指定其它源）。系统安装的 ffmpeg 优先于缓存。体积可观，调用前请先征得用户同意。
+
+### `install_ocr_dependencies` —— 一键补齐 OCR 语言包
+
+把 tesseract.js 的语言数据（默认 `chi_sim+eng`，约每种语言 10-30 MB）下载进插件缓存（`~/.dsh-file-convert/tessdata`），让 `ocr: true` 在没有本机 Tesseract 时也能工作。已装本机 Tesseract 或语言包已缓存时跳过。体积可观，调用前请先征得用户同意——转换路径绝不隐式下载语言数据。
+
+### `list_conversions` —— 当前机器的能力清单
+
+列出全部 26 种转换在当前机器上的实时可用状态；某项不可用时，明确指出缺哪个外部工具并给出安装提示。图片/PDF/数据类开箱即用，音视频、Office、PDF 压缩依赖可选工具（媒体依赖还能由 Agent 经 `install_media_dependencies` 自动补齐）。
+
+## 插件配置
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `quality` | `85` | JPEG/WebP 默认质量（1–100） |
+| `dpi` | `150` | PDF 光栅化默认 DPI |
+| `timeoutMs` | `120000` | 单次转换的协作式超时（毫秒） |
+| `maxInputMb` | `2048` | 拒绝超过此大小（MB）的输入 |
+| `maxPdfPages` | `200` | 整本 PDF 光栅化超过此页数即拒绝；更大的文档请用 `pages` 选择 |
+| `maxOutputPixels` | `16000000` | 每页光栅化像素（宽 × 高）钳制到此预算 |
+| `batchMaxFiles` | `500` | 每次 `batch_convert` 最多检查的文件数；超出时会在结果里明确报告跳过了多少，而不是静默截断 |
+| `outputRoots` | `[]` | 非空时，显式指定的 `output` 路径必须落在这些目录之内（共享部署建议开启；默认写到输入文件旁的输出不受限） |
+| `ffmpegPath` / `ffprobePath` | - | ffmpeg 不在 PATH 时（Windows 常见）手动指定二进制路径 |
+| `sofficePath` / `ghostscriptPath` / `pythonPath` / `tesseractPath` | - | 各可选工具的手动路径，优先于自动探测 |
+
+## 架构
+
+```
+                         DSH
+                          │
+                    dsh-file-convert
+           ┌──────────────┴──────────────┐
+     src/index.ts                   src/core/            ← 整个引擎，
+     （薄胶水层：                     （不 import DSH）       可独立测试
+      name/inject/apply、                 │
+      Config schema、               ConversionRouter
+      7 个 tool 注册）                    │
+                       ┌─────────────────┼─────────────────┐
+                       ↓                 ↓                 ↓
+                 ImageConverter     PdfConverter      DataConverter
+                    sharp          pdfjs-dist         js-yaml
+                 （npm libvips）  @napi-rs/canvas    csv-parse / stringify
+                                                     MediaConverter        OfficeConverter
+                                                        ffmpeg（自动检测）     LibreOffice（自动检测）
+                                                     PdfToDocxConverter    optimize_file/pdf
+                                                    python+pdf2docx           Ghostscript（自动检测）
+```
+
+- **声明式转换矩阵**：每条转换是 converter 上的一行数据（`{ from, to }`），Router 路由、`list_conversions`、依赖检查全部由此推导。
+- **格式识别**：内容优先——二进制 magic（file-type）、SVG 嗅探、JSON 解析（无扩展名文件还会尝试 YAML 文档标记猜测）——扩展名兜底；两者冲突以内容为准并给出 warning。
+- **核心与 DSH 解耦**：`src/core` 不依赖 Cordis/DSH，可直接单测、包 CLI、将来包 MCP server。DSH developer preview 的 API 若有破坏性变更，只需改胶水层。
+- **依赖管理**：外部二进制（FFmpeg/LibreOffice/Poppler）只做**检测，绝不自动安装**——`list_conversions` 报告缺失并给出各平台安装提示。接口已就位（`BinaryDependency`）。
+
+## 开发
+
+```sh
+npm install
+npm run build     # tsc -> lib/
+npm test          # vitest，31 个测试
+npm run smoke     # 针对 lib/ 的端到端冒烟测试
+```
+
+加一种转换 = 在 converter 的能力表里加一行数据并实现它。加一类后端 = 实现 `Converter` 接口并在 `createRouter()` 注册。
+
+## 保真度与安全预期
+
+- **天然有损**：PDF→DOCX（实验性）、OCR、office→PDF 都是重建——版式和识别误差不可避免。`inspect_file` 的 `likelyScanned` 标记帮你判断何时该用 OCR，结果里会带警告。
+- **缓存版 ffmpeg**：便捷下载安装的是钉死 sha256 的 FFmpeg 6.1.1 静态构建。处理不可信媒体时，新版系统 FFmpeg 优先——安全敏感场景请优先系统安装。
+- **不是沙箱**：`outputRoots` 会解析符号链接，资源上限（`maxInputMb`、`maxPdfPages`、`maxOutputPixels`、`batchMaxFiles`）能拦住失控任务，但默认"写到输入文件旁"的输出有意不受 roots 约束，且能写文件的 Agent 总能找到地方写。敌对多租户场景请在操作系统层再加隔离。
+
+## Roadmap
+
+- ~~V0.2 —— 音视频（FFmpeg）~~ **已发布**：MP4→GIF/MP3、WAV→MP3、MOV→MP4，以及按目标体积两遍编码的 `optimize_file`。
+- ~~V0.3 —— Office + PDF 工具链~~ **已发布**：LibreOffice 解锁 DOCX/PPTX/XLSX→PDF，python pdf2docx 支持实验性 PDF→DOCX，Ghostscript 支持 PDF 压缩；依赖支持按需下载并默认走国内镜像。
+- ~~V0.4 —— OCR（Tesseract）~~ **已发布**：PDF→TXT 支持 `ocr: true`（可选 `ocr_lang`），Tesseract CLI 优先 + tesseract.js 兜底，语言数据经 `install_ocr_dependencies` 显式下载。
+- 更远：扫描件 OCR → DOCX、转换链（PPTX→PDF→PNG）、`optimize_file` 视频降分辨率、图片缩放/旋转。
+
+## 许可
+
+[MIT](./LICENSE)。dsh-file-convert 不分发任何外部二进制；运行时依赖库（sharp、pdfjs-dist、@napi-rs/canvas、js-yaml、csv）由用户从 npm 安装，各归其许可。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+  - id: dsh-file-convert
+    name: dsh-file-convert

package/lib/config.d.ts

@@ -0,0 +1,36 @@
+import Schema from '@deepseek-ai/schemastery';
+export interface Config {
+    /** Default JPEG/WebP quality (1-100). */
+    quality: number;
+    /** Default rasterization DPI for pdf/svg inputs. */
+    dpi: number;
+    /** Cooperative deadline for one conversion, in milliseconds. */
+    timeoutMs: number;
+    /** Max files examined per batch_convert run before it stops and reports. */
+    batchMaxFiles: number;
+    /**
+     * When non-empty, explicit output paths must resolve inside one of these
+     * directories. Empty (default) = unrestricted - fine on a personal machine;
+     * set it when the harness is shared or exposed.
+     */
+    outputRoots: string[];
+    /** Explicit path to the ffmpeg binary (Windows installs without PATH). */
+    ffmpegPath?: string;
+    /** Explicit path to the ffprobe binary (usually next to ffmpeg). */
+    ffprobePath?: string;
+    /** Explicit path to the LibreOffice soffice binary. */
+    sofficePath?: string;
+    /** Explicit path to the Ghostscript binary (gswin64c on Windows). */
+    ghostscriptPath?: string;
+    /** Explicit python interpreter for the pdf2docx-based PDF → DOCX conversion. */
+    pythonPath?: string;
+    /** Explicit tesseract binary for OCR (falls back to bundled tesseract.js). */
+    tesseractPath?: string;
+    /** Refuse inputs above this size (MB). */
+    maxInputMb: number;
+    /** Refuse full-document PDF rasterization above this page count. */
+    maxPdfPages: number;
+    /** Clamp rasterized pixels per page (width x height) to this budget. */
+    maxOutputPixels: number;
+}
+export declare const Config: Schema<Config>;

package/lib/config.js

@@ -0,0 +1,17 @@
+import Schema from '@deepseek-ai/schemastery';
+export const Config = Schema.object({
+    quality: Schema.number().min(1).max(100).default(85).description('Default JPEG/WebP quality (1-100).'),
+    dpi: Schema.number().min(72).max(600).default(150).description('Default rasterization DPI for PDF/SVG inputs.'),
+    timeoutMs: Schema.number().min(1000).default(120_000).description('Cooperative timeout for one conversion (ms). For long video jobs consider 600000.'),
+    batchMaxFiles: Schema.number().min(1).default(500).description('Max files examined per batch_convert run; extra files are reported, not silently skipped.'),
+    outputRoots: Schema.array(Schema.string()).default([]).description('Restrict explicit output paths to these directories. Empty = unrestricted. Symlinks are resolved; the default next-to-input output is exempt.'),
+    ffmpegPath: Schema.string().description('Explicit ffmpeg binary path (overrides PATH lookup).'),
+    ffprobePath: Schema.string().description('Explicit ffprobe binary path (overrides PATH lookup).'),
+    sofficePath: Schema.string().description('Explicit LibreOffice soffice binary path (overrides auto-detection).'),
+    ghostscriptPath: Schema.string().description('Explicit Ghostscript binary path (overrides PATH lookup).'),
+    pythonPath: Schema.string().description('Explicit python interpreter for the pdf2docx-based PDF → DOCX conversion.'),
+    tesseractPath: Schema.string().description('Explicit tesseract binary for OCR (falls back to bundled tesseract.js).'),
+    maxInputMb: Schema.number().min(1).default(2048).description('Refuse inputs above this size (MB).'),
+    maxPdfPages: Schema.number().min(1).default(200).description('Full-document PDF rasterization refuses to exceed this page count; use pages for larger documents.'),
+    maxOutputPixels: Schema.number().min(100_000).default(16_000_000).description('Clamp rasterized pixels per page (width x height) to this budget.'),
+});

package/lib/core/binaries/cache.d.ts

@@ -0,0 +1,13 @@
+import type { BinaryDependency, Logger } from '../types.js';
+/** Persistent per-user cache for downloaded external binaries. */
+export declare function cacheDir(): string;
+export declare function cachedBinaryPath(name: string): string;
+/** Expand a path pattern segment by segment; [] when nothing matches. */
+export declare function expandPattern(pattern: string): Promise<string[]>;
+/**
+ * Resolution order: explicit config override → system PATH → known install
+ * locations (Windows soffice is rarely on PATH) → plugin cache. Every
+ * candidate must pass the dependency's probe when it declares one — a config
+ * override pointing at a python without pdf2docx counts as missing.
+ */
+export declare function resolveBinaryCached(dep: BinaryDependency, overrides: Record<string, string | undefined>, which: (command: string) => Promise<string | null>, logger: Logger): Promise<string | null>;