dsh-file-convert

dsh plugin --profile web add dsh-file-convert

dsh-file-convert

为 DeepSeek Harness 打造的本地优先文件转换插件。

在 DSH Agent 会话里直接转换图片、PDF 和数据文件——不需要 API Key，不上传文件，不需要服务器，转换本身零 Token 消耗，文件永远不离开你的电脑。

非官方社区插件。 与 DeepSeek 官方无隶属关系。

兼容性： v1.1.x 通过明确的 peer 版本分支支持 DeepSeek Harness Desktop 0.2.1-rc.5 和 0.2.2-rc.1，新旧运行时的依赖图分别构建与测试。v1.0.x 继续保留 0.2.1-rc.5 的原稳定基线，其他宿主需单独验证。需要 Node.js ^22.19.0 || >=24.0.0。详见[安装、升级与回退说明](./STABILITY.md)。

为什么做这个

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 中——三种方式，按省事程度排序：

# 1. 从 npm 安装（发包后可用）
dsh plugin --profile desktop add dsh-file-convert@1.1.0 --save-exact

# 2. 直接从 GitHub 安装（会执行一次构建，需放行）
dsh plugin --profile default add github:zzy-12345678/dsh-file-convert

Git 安装可能需要在 profile 的 pnpm-workspace.yaml 里放行构建步骤：

allowBuilds:
  dsh-file-convert: true

首次安装提示：pnpm 还可能要求你决定 tesseract.js 的构建脚本是否执行（它只是捐赠提示，跳过毫无影响）。在同一个文件里加上：

```yaml

allowBuilds:

tesseract.js: false

```

然后重新执行安装命令即可。

本地开发安装：

git clone https://github.com/zzy-12345678/dsh-file-convert
cd dsh-file-convert && npx --yes npm@11.6.2 ci && npm run build
dsh plugin --profile default add /absolute/path/to/dsh-file-convert

重启 DSH（dsh web 或你的常规入口）后，八个 tool 自动出现。

八个 Tool

convert_file —— 单文件转换

{ "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 —— 目录批量转换

{ "input_dir": "/home/me/Pictures", "output_format": "webp" }

• input_format 可按源格式过滤；不传则自动探测所有可转换文件。
• output_dir 默认为 <input_dir>/output。
• 已存在的输出默认跳过（不覆盖），overwrite: true 时替换。

inspect_file —— 转换前先看清楚

基于文件内容（magic bytes）而非扩展名识别格式：

{ "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）。

{ "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 优先于缓存。体积可观，调用前请先征得用户同意。

下载钉死 sha256 的 FFmpeg 6.1.1 静态构建（ffmpeg + ffprobe，各 ~28 MB）到插件缓存（~/.dsh-file-convert/bin），并真实执行一次二进制确认可用后才报告成功。npmmirror 二进制 CDN 优先，GitHub release 为字节一致的回退源。系统安装的 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 自动补齐）。

open_ui

在 DSH 会话里打开本地拖拽转换网页。首次调用会在插件进程内启动 UI 服务器并打开浏览器；再次调用直接返回已运行实例的地址，不会重复起进程。在 DSH Desktop 里转换器还常驻为会话视图中的「文件转换」标签页——open_ui 只在你想用独立浏览器窗口时才需要。

{}

dsh-file-convert UI is running at http://127.0.0.1:5757/ (opened in your browser; ...)

本地 Web UI（拖拽转换）

引擎自带一个零依赖的网页应用：把文件拖进浏览器、选目标格式、下载结果，全程不出本机。有两种打开方式：

• DSH Desktop 原生集成（默认）：插件把应用挂载到 DSH Web 服务器的 /dsh-file-convert 路径，并注入客户端 bundle，在会话视图里添加一个「文件转换」标签页——点开即用，无需额外服务器；iframe 与宿主同源，由 DSH 自身的访问控制保护。
• 独立运行（npm run ui，或让 Agent 调用 open_ui）：独立服务器 http://127.0.0.1:5757（端口被占用时自动顺延），由随机会话 token 保护。适合在 DSH 之外或想在普通浏览器窗口使用时。

两种模式功能一致：

• 拖入文件（或点击选择）即可转换；任务逐个排队，显示上传进度、警告信息与逐文件下载链接。多页 PDF 按页生成多个下载。
• 目标格式下拉框由实时能力矩阵（与 list_conversions 同源数据）驱动：不可用的组合不会出现，首次尝试后真实检测出的输入格式会纠正错误猜测。
• 转换中关闭标签页会真正中止底层工作（与工具相同的真取消语义）。
• 独立模式安全默认值：只绑定 127.0.0.1，拒绝其他网卡；所有 API 都需要随机会话 token。
• 独立模式启动参数：--port（默认 5757）、--no-open、--timeout-min（默认 30 分钟/次）、--max-upload-mb（默认 2048）。

插件配置

键 · 默认值 · 说明

quality · 85 · JPEG/WebP 默认质量（1–100）

dpi · 150 · PDF 光栅化默认 DPI

timeoutMs · 120000 · 单次转换的协作式超时（毫秒）

…(truncated)