dsh-converter
English | 中文
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 中启用
在 /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
└── .ts —— 20 个转换器（ffmpeg/pandoc/vips/vcf/...）
与 Web 版的关键差异
- 文件 I/O：输入输出都是本地路径（Web 版是 HTTP 上传 + OSS 存储）；
- 超时与取消：通过引擎预留的
execFileOverride扩展点注入包装 ——
外部 CLI 超时（timeoutMs配置）自动 kill，且工具调用被取消
（exec.signal）时立即终止子进程，不留僵尸进程； - 错误自愈：不支持的格式对返回
availableTargets，转换器缺失返回
安装命令 —— 模型可以自我纠正而不是反复失败； - 可诊断：
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）真实转换、
# 不支持格式的错误提示、
# 格式矩阵查询、卸载清理
