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 中启用

在 <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）真实转换、
                                                   #   不支持格式的错误提示、
                                                   #   格式矩阵查询、卸载清理