ConvertAgent

为 AI Agent 打造的文件转换工具。 CLI、REST API 和 MCP 服务——共用同一个引擎。

快速开始 · API 参考 · MCP 服务 · 格式 · 架构 · 路线图

---

ConvertAgent 是一款可自托管的开源文件转换工具包，专为 AI Agent 设计。文件始终留在你的基础设施中——无需上传到云端、无需 API 密钥、无需按次付费，也没有使用限制。只需安装、运行并转换。为本地 Agent 提供 CLI，为远程访问提供 REST API，并通过 MCP 接入 Agent 生态系统。

可自托管。开源。转换零成本。 你的 Agent 可在本地转换文件——无需云端、没有限制，也不会被供应商锁定。

---

✨ 功能

• 🖥️ CLI 优先 — convertagent convert file.pdf --to docx — 为 Agent 提供原生接口
• 🌐 REST API — 使用 POST /v1/convert 服务远程 Agent 和 Web 服务
• 🔌 MCP 服务 — 可被任何兼容 MCP 的 AI 客户端发现（Claude、ChatGPT、Cursor 等）
• ⚡ 单一调度器 — 三种接口共用同一个转换引擎
• 📦 20 种转换组合，涵盖文档、图像、音视频和文本
• 🔧 开源引擎 — 底层使用 FFmpeg、LibreOffice、ImageMagick 和 Pandoc
• 🚀 可自托管 — 文件始终留在你的基础设施中

---

📋 支持的转换

类别	转换
文档	pdf→docx · docx→pdf · html→pdf · md→pdf · md→html · md→docx · xlsx→csv · csv→xlsx · pptx→pdf
图像	jpg→png · png→jpg · png→webp · webp→png · svg→png · image-resize · image-compress
音视频	mp4→mp3 · wav→mp3 · mp4→gif · any-video→mp4

---

🚀 快速开始

前置条件

# Install conversion engines (Ubuntu/Debian)
sudo apt-get update && sudo apt-get install -y ffmpeg libreoffice imagemagick pandoc

安装并运行

git clone https://github.com/vid-factory/convertagent.git
cd convertagent
npm install
npm run build

CLI 用法

# Convert a PDF to Word
convertagent convert report.pdf --to docx

# Convert with custom output path
convertagent convert photo.png --to webp --output ./compressed.webp

# Extract audio from video
convertagent convert video.mp4 --to mp3

# List all supported formats
convertagent formats

# Check engine health
convertagent health

启动 API 服务

# Start on default port 3001
node dist/api/server.js

# Or with custom port
PORT=8080 node dist/api/server.js

---

📡 API 参考

POST /v1/convert

将文件从一种格式转换为另一种格式。

请求：

{
  "action": "pdf-to-docx",
  "source": "/path/to/file.pdf",
  "options": {}
}

使用 URL 作为来源：

{
  "action": "html-to-pdf",
  "source_url": "https://example.com/page.html",
  "options": {}
}

使用 base64 作为来源：

{
  "action": "jpg-to-png",
  "source_base64": "data:image/jpeg;base64,/9j/4AAQ...",
  "options": {}
}

响应：

{
  "success": true,
  "job_id": "a1b2c3d4",
  "artifact": {
    "path": "/output/a1b2c3d4.docx",
    "url": "/v1/artifacts/a1b2c3d4",
    "format": "docx",
    "size": 45231,
    "duration_ms": 1200
  }
}

GET /v1/formats

列出所有支持的转换组合。

GET /health

检查引擎是否可用。

{
  "ok": true,
  "service": "convertagent",
  "engines": {
    "ffmpeg": true,
    "libreoffice": true,
    "imagemagick": true,
    "pandoc": true
  }
}

---

🔌 MCP 服务

ConvertAgent 提供 MCP 服务，可与任何兼容 MCP 的 AI 客户端集成。

可用工具

工具	描述
convert_file	将文件从一种格式转换为另一种格式
list_formats	列出所有支持的转换格式组合

通过 MCP 连接

{
  "mcpServers": {
    "convertagent": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

示例：Claude Desktop

将以下内容添加到 Claude Desktop 的 MCP 配置中：

{
  "mcpServers": {
    "convertagent": {
      "command": "node",
      "args": ["/path/to/convertagent/dist/mcp/server.js"]
    }
  }
}

---

🏗️ 架构

┌─────────────────────────────────────────────────────┐
│                    ConvertAgent                       │
│                                                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐              │
│  │   CLI   │  │   API   │  │   MCP   │  ← Interfaces│
│  └────┬────┘  └────┬────┘  └────┬────┘              │
│       │            │            │                     │
│       └────────────┼────────────┘                     │
│                    │                                  │
│           ┌────────▼────────┐                         │
│           │   Dispatcher    │  ← Shared routing core  │
│           └────────┬────────┘                         │
│                    │                                  │
│    ┌───────┬───────┼───────┬────────┐                │
│    │       │       │       │        │                │
│  ┌─▼──┐ ┌─▼──┐ ┌──▼──┐ ┌─▼────┐   │                │
│  │ FF │ │ LO │ │ IM  │ │ Pan  │   │  ← Engines     │
│  │mpeg│ │    │ │     │ │ doc  │   │                 │
│  └────┘ └────┘ └─────┘ └──────┘   │                │
│                                     │                │
│  FF = FFmpeg    LO = LibreOffice    │                │
│  IM = ImageMagick  Pan = Pandoc     │                │
└─────────────────────────────────────────────────────┘

---

🐳 Docker（即将推出）

docker run -p 3001:3001 vid-factory/convertagent

---

🛠️ 开发

# Clone
git clone https://github.com/vid-factory/convertagent.git
cd convertagent

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run the full 20-pair conversion test matrix
node scripts/run-tea-20.mjs

项目结构

convertagent/
├── src/
│   ├── cli/              # CLI commands (convert, formats, health)
│   ├── api/              # REST API server (Fastify)
│   ├── mcp/              # MCP server (Streamable HTTP)
│   ├── core/             # Shared dispatcher + format registry
│   ├── engines/          # Engine adapters
│   │   ├── ffmpeg.ts     # Audio/video conversions
│   │   ├── libreoffice.ts# Document conversions
│   │   ├── imagemagick.ts# Image conversions
│   │   ├── pandoc.ts     # Text/markup conversions
│   │   └── shell.ts      # Shared shell runner with timeouts
│   └── tests/            # Unit + integration tests
├── scripts/              # TEA matrix runner, utilities
├── test-assets/          # Real input files for testing
├── test-artifacts/       # TEA results + parity evidence
├── deploy/               # systemd service file
├── package.json
├── tsconfig.json
└── README.md

---

📊 测试结果

ConvertAgent 提供完整的真实文件测试矩阵，无需模拟。

格式对	状态	引擎
pdf→docx	✅ 通过	LibreOffice
docx→pdf	✅ 通过	LibreOffice
html→pdf	✅ 通过	Pandoc
md→pdf	✅ 通过	Pandoc
md→html	✅ 通过	Pandoc
md→docx	✅ 通过	Pandoc
xlsx→csv	✅ 通过	LibreOffice
csv→xlsx	✅ 通过	LibreOffice
pptx→pdf	✅ 通过	LibreOffice
jpg→png	✅ 通过	ImageMagick
png→jpg	✅ 通过	ImageMagick
png→webp	✅ 通过	ImageMagick
webp→png	✅ 通过	ImageMagick
svg→png	✅ 通过	ImageMagick
image-resize	✅ 通过	ImageMagick
image-compress	✅ 通过	ImageMagick
mp4→mp3	✅ 通过	FFmpeg
wav→mp3	✅ 通过	FFmpeg
mp4→gif	✅ 通过	FFmpeg
any-video→mp4	✅ 通过	FFmpeg

20/20 项通过 — 已通过 CLI、API 和 MCP 接口验证，并进行了二进制一致性检查。

---

🗺️ 路线图

• 支持 20 种格式转换的 CLI 接口
• REST API（/v1/convert、/v1/formats、/health）
• 支持工具发现和执行的 MCP 服务
• 真实文件 TEA 测试矩阵（20/20）
• 跨接口一致性验证（CLI = API = MCP）
• 持久化部署的 systemd 配置
• URL 来源输入（获取远程文件以进行转换）
• 支持一键部署的 Docker 镜像
• OpenClaw 技能包（发布到 ClawHub）
• Claw Mart 市场上架
• 流水线端点（串联多个转换）
• npm 全局安装（npm install -g convertagent）
• 使用情况跟踪和速率限制
• 更多格式对（50+）

---

🤝 参与贡献

欢迎贡献！请遵循以下指南：

1. Fork 此代码库
2. 创建功能分支（git checkout -b feat/new-format-pair）
3. 为新的转换编写测试（使用真实文件，而非模拟）
4. 运行完整的 TEA 矩阵（node scripts/run-tea-20.mjs）
5. 使用约定式提交（feat:、fix:、docs:、test:）进行提交
6. 发起 Pull Request

添加新的格式转换对

1. 将格式对添加到 src/core/formats.ts
2. 在 src/engines/ 中实现或扩展相应的引擎适配器
3. 将真实测试输入文件添加到 test-assets/input/
4. 将格式对添加到 scripts/run-tea-20.mjs 中的 TEA 矩阵
5. 运行测试并验证输出

---

📄 许可证

MIT License — 详情请参阅 LICENSE。

---

🙏 致谢

• FFmpeg — 音视频处理
• LibreOffice — 文档转换
• ImageMagick — 图像处理
• Pandoc — 通用文档转换器
• Model Context Protocol — AI 工具集成标准

---

由 vid-factory 构建 — 面向 AI 时代的 Agent 基础设施。