文件格式转换 ai-tool-labs/dsh-converter

dsh-converter

DSH（DeepSeek Harness）的文件格式转换插件：提供一套转换引擎，并封装为模型工具。
引擎覆盖 20 个转换器、1000+ 格式对（图片/音视频/文档/电子书/3D/表格...），全部通过外部 CLI（ffmpeg、pandoc、libreoffice、imagemagick、vips、calibre...）或纯 JS 实现（vcf）执行。

1. 工具

| 工具 | 用途 |
| convert_file | 转换本地文件：{ inputPath, to, from?, outputPath?, converter? }。产物默认写到输入同目录（同名换扩展名）。不支持的格式对会返回可用目标列表，转换器缺失时返回安装命令 |
| list_conversions | 查询格式矩阵：给 from 返回该格式可转换的目标（按转换器分组）；不给则返回全部分类格式概览 |
| check_converters | 检测本机各转换器 CLI 是否可用（含版本号） |

2. 安装

从 npm / GitHub 安装

dsh plugin --profile web add dsh-converter # 从 npm 安装
dsh plugin --profile web add github:ai-tool-labs/dsh-converter # 或 GitHub
桌面端：打开侧边栏「插件」面板 → 点击「添加插件」 → 输入框输入 "dsh-converter" → 点击安装安装后重启 harness 生效（桌面端重启 App；Web 端重启 dsh web）

从源码构建安装（开发者）

1) 构建
pnpm install && pnpm --filter dsh-converter build

2) 安装进 profile（示例：web profile）
dsh plugin --profile web add /path/to/dsh-plugins/packages/dsh-converter

在 profile 中启用

在 <profile>/cordis.patch.yml 中追加如下内容（随包附带的 cordis.patch.yml 提供了全部选项的注释示例）：

- insert:
- id: file-converter
name: dsh-converter
config:
enableTools: true
enableSkill: true
maxFileSizeMb: 500 # 单文件上限（默认 500MB，与 Web 版一致） timeoutMs: 300000 # 外部 CLI 超时（默认 5 分钟）

3. 转换器安装

check_converters 会告诉你哪些缺失；各平台的安装命令：

| 转换器 | 用途 | macOS | Ubuntu | Windows |
| ffmpeg | 音视频/动图 | brew install ffmpeg | apt install ffmpeg | choco install ffmpeg |
| pandoc | 文档万能转换 | brew install pandoc | apt install pandoc | choco install pandoc |
| libreoffice | Office/PDF 互转 | brew install --cask libreoffice | apt install libreoffice | choco install libreoffice |
| imagemagick | 图像 | brew install imagemagick | apt install imagemagick | choco install imagemagick |
| vips | 图像（高性能） | brew install vips | apt install libvips-tools | choco install vips |
| calibre | 电子书 | brew install --cask calibre | apt install calibre | choco install calibre |
| inkscape | 矢量图 | brew install --cask inkscape | apt install inkscape | choco install inkscape |
| xelatex | LaTeX → PDF | brew install --cask mactex | apt install texlive-xetex | 安装 MiKTeX |
| vcf | 通讯录 vcf → csv | ✅ 纯 JS，无需安装 | ✅ | ✅ |

完整列表见 src/engine/installCommands.ts（含 20 个转换器的各平台安装命令）。

4. 架构

src/index.ts —— 入口：Config / inject / apply src/tools.ts —— convert_file / list_conversions / check_converters src/skills.ts —— file-conversion 技能（教模型使用规范） src/engine/ —— 移植的转换引擎（与原项目逻辑一致） ├── registry.ts —— 格式矩阵纯数据 + 查询函数（无 Node 依赖） ├── fileTypeCategories.ts —— 扩展名 → 类别（纯数据） ├── normalizeFiletype.ts —— 格式别名规范化（jfif→jpeg、md→markdown...） ├── main.ts —— mainConverter：自动选择转换器 + 路径/Buffer I/O └── <converter>.ts —— 20 个转换器（ffmpeg/pandoc/vips/vcf/...）

与 Web 版的关键差异

1. 文件 I/O：输入输出都是本地路径（Web 版是 HTTP 上传 + OSS 存储）；
2. 超时与取消：通过引擎预留的 execFileOverride 扩展点注入包装 ——外部 CLI 超时（timeoutMs 配置）自动 kill，且工具调用被取消（exec.signal）时立即终止子进程，不留僵尸进程；
3. 错误自愈：不支持的格式对返回 availableTargets，转换器缺失返回安装命令 —— 模型可以自我纠正而不是反复失败；
4. 可诊断：check_converters 把 CLI 可用性暴露给模型。

引擎说明

- 引擎用 TypeScript 编写，零第三方依赖（只用 Node 内置模块）：
- 导入使用相对路径；
- main.ts 是主转换器，暴露 execFileOverride 扩展点（用于超时/取消）；
- detectOS() 用 Node 环境实现（而非浏览器 UA 检测）。
- 因引擎无运行时依赖，自包含且易于维护。

5. 开发

pnpm --filter dsh-converter typecheck # 类型检查
pnpm --filter dsh-converter build # tsc → build/
pnpm --filter dsh-converter smoke # 冒烟测试：
vcf→csv（纯 JS）真实转换、不支持格式的错误提示、格式矩阵查询、卸载清理