document-converter

document-converter

用途

使用本地、免费、离线的工具在不同格式间转换文档并执行 PDF 操作。无需 API 密钥、无需付费、无需联网。支持 Office 格式、PDF 处理、图像转 PDF，以及使用 LibreOffice、ghostscript、pdftk、tesseract 和 imagemagick 进行 OCR。

适用场景

• 将 Office 文档（DOCX、PPTX、XLSX、ODP、ODT）转换为 PDF 或 HTML
• 将 PDF 页面转换为图像（PNG、JPG、TIFF），或将图像转换为 PDF
• PDF 操作：合并多个 PDF、按页码范围拆分、旋转页面、加密或解密
• OCR：从扫描版 PDF 或图像文件中提取可搜索文本
• 任何不涉及视频或音频的文档格式转换

请勿用于：

• 转换视频或音频格式（请使用专用的媒体技能）
• 在编程语言之间转换代码
• 简单的 Markdown → HTML 转换（请直接使用 pandoc）
• 从 PDF 中提取结构化文本（请改用 docling-converter）

步骤 0：发现 — 检测可用工具

进行任何转换之前，检测已安装的工具并识别操作系统：

# Detect OS
uname -s   # Darwin = macOS, Linux = Linux; on Windows use 'ver' or check $OS

# Check each tool
libreoffice --version 2>/dev/null || echo "NOT FOUND"
gs --version 2>/dev/null || echo "NOT FOUND"
pdftk --version 2>/dev/null || echo "NOT FOUND"
tesseract --version 2>/dev/null || echo "NOT FOUND"
convert -version 2>/dev/null || echo "NOT FOUND"   # ImageMagick

如果缺少所需工具，请先显示适用于用户操作系统的安装命令，再继续操作：

工具	macOS	Linux (apt)	Windows
LibreOffice	brew install --cask libreoffice	sudo apt install libreoffice	winget install TheDocumentFoundation.LibreOffice
Ghostscript	brew install ghostscript	sudo apt install ghostscript	winget install ArtifexSoftware.GhostScript
pdftk	brew install pdftk-java	sudo apt install pdftk	winget install PDFTechnologies.PDFtk
Tesseract	brew install tesseract	sudo apt install tesseract-ocr	winget install UB-Mannheim.TesseractOCR
ImageMagick	brew install imagemagick	sudo apt install imagemagick	winget install ImageMagick.ImageMagick

如果用户使用 Windows 且已安装 Microsoft Office，请说明 LibreOffice 和 Office 对 DOCX/PPTX/XLSX 的转换结果相当；通过 COM 自动化使用 Office 是一种高级替代方案。

工作流

Office 文档 → PDF（最常见）

使用 LibreOffice 无界面模式。适用于 DOCX、PPTX、XLSX、ODP、ODT，以及 LibreOffice 能打开的任何格式。

# Convert single file to PDF in the same directory
libreoffice --headless --convert-to pdf "/path/to/file.pptx" --outdir "/path/to/output/"

# Convert to HTML
libreoffice --headless --convert-to html "/path/to/file.docx" --outdir "/path/to/output/"

# Batch: convert all PPTX in a directory
libreoffice --headless --convert-to pdf /path/to/folder/*.pptx --outdir /path/to/output/

说明：

• 输出文件会放在 --outdir 中，文件名主体不变，仅扩展名不同
• 批量处理时，只运行一个 libreoffice 进程——请勿并行启动多个实例（LibreOffice 使用单用户配置文件锁）
• 如果 LibreOffice 以 GUI 应用的形式运行，请先关闭，或使用 --norestore 标记

PDF → 图像 / 图像 → PDF

使用 ImageMagick 在图像与 PDF 之间转换：

# PDF pages → PNG (one file per page)
convert -density 150 "/path/to/doc.pdf" "/path/to/output/page_%03d.png"

# PDF pages → JPG with quality control
convert -density 150 "/path/to/doc.pdf" -quality 85 "/path/to/output/page_%03d.jpg"

# Single image → PDF
convert "/path/to/image.png" "/path/to/output/document.pdf"

# Multiple images → single PDF
convert img1.png img2.jpg img3.tiff "/path/to/output/combined.pdf"

注意：在某些系统上，ImageMagick 的 PDF 支持需要 ghostscript。如果转换因策略错误而失败，请检查 /etc/ImageMagick-*/policy.xml，并确保 PDF 未受到限制。

PDF 操作 — 合并、拆分、旋转

如果有 pdftk，优先使用它（语法更简单）。如果未安装 pdftk，则改用 ghostscript。

合并 PDF：

# pdftk (preferred)
pdftk file1.pdf file2.pdf file3.pdf cat output merged.pdf

# ghostscript (fallback)
gs -dBATCH -dNOPAUSE -q -sDEVICE=pdfwrite -sOutputFile=merged.pdf file1.pdf file2.pdf file3.pdf

按页码范围拆分 PDF：

# pdftk — extract pages 1-3 and 5
pdftk input.pdf cat 1-3 5 output extracted.pdf

# ghostscript — extract pages 2 to 5
gs -dBATCH -dNOPAUSE -q -sDEVICE=pdfwrite -dFirstPage=2 -dLastPage=5 -sOutputFile=extracted.pdf input.pdf

旋转页面：

# pdftk — rotate all pages 90° clockwise
pdftk input.pdf rotate 1-endeast output rotated.pdf

# pdftk — rotate specific page (page 3) 180°
pdftk input.pdf rotate 3south output rotated.pdf

加密 PDF（添加密码）：

pdftk input.pdf output secured.pdf user_pw "userpass" owner_pw "ownerpass"

解密 PDF（移除密码）：

pdftk secured.pdf input_pw "password" output decrypted.pdf

OCR — 从扫描文档中提取文本

使用 Tesseract。输入必须是图像（PNG、JPG、TIFF），或可以先由 ImageMagick 栅格化的 PDF。

# OCR a single image → searchable text file
tesseract "/path/to/scan.png" "/path/to/output/result"
# Output: result.txt

# OCR with language specification (Portuguese example)
tesseract "/path/to/scan.png" output -l por

# OCR → searchable PDF (requires tesseract with pdf support)
tesseract "/path/to/scan.png" output -l eng pdf
# Output: output.pdf

# OCR a scanned PDF: rasterize first, then OCR
convert -density 300 "scan.pdf" "scan_page_%03d.tiff"
tesseract "scan_page_000.tiff" output -l eng pdf

对于多页扫描版 PDF：

# Rasterize all pages
convert -density 300 "scan.pdf" "page_%03d.tiff"

# OCR each page and merge results
for f in page_*.tiff; do
  tesseract "$f" "${f%.tiff}" -l eng pdf
done
pdftk page_*.pdf cat output final_ocr.pdf

工具路由决策表

任务	首选工具	备用工具
Office → PDF	LibreOffice	无（LibreOffice 是标准工具）
Office → HTML	LibreOffice	无
PDF → 图像	ImageMagick	ghostscript（gs -sDEVICE=png16m）
图像 → PDF	ImageMagick	ghostscript
合并 PDF	pdftk	ghostscript
拆分 PDF	pdftk	ghostscript
旋转 PDF	pdftk	ghostscript
加密 PDF	pdftk	无
解密 PDF	pdftk	无
OCR	tesseract	无

对比：何时使用 document-converter 与其他工具

工具	最适合的用途
document-converter	办公文档 → PDF、PDF 操作（合并/拆分/旋转/加密）、OCR、图像 ↔ PDF
docling-converter	PDF/办公文档 → 结构化 Markdown 或 JSON；支持识别布局的内容提取
pandoc	Markdown ↔ HTML ↔ LaTeX ↔ DOCX；轻量级文本格式转换
pptx-translator	在不同语言之间翻译 PowerPoint 文件

关键规则

• 绝不要使用多个并行进程启动批量 LibreOffice 转换——LibreOffice 使用单个用户配置文件锁，并行实例会崩溃
• 调用工具前，务必执行步骤 0“发现”，确认所需工具已安装
• 如果缺少工具，务必提供适用于用户操作系统的正确安装命令
• 绝不要使用 cloudconvert、外部 API 或付费服务——此技能完全离线
• 如果 pdftk 和 ghostscript 都可用，务必优先使用 pdftk 进行 PDF 操作（语法更简单、更安全）
• 务必明确指定输出目录，避免将文件写入意外位置

使用示例

将 PPTX 转换为 PDF：

libreoffice --headless --convert-to pdf presentation.pptx --outdir ./output/

合并 3 个 PDF：

pdftk report.pdf appendix.pdf cover.pdf cat output final.pdf

对扫描图像进行 OCR（葡萄牙语）：

tesseract scan.png resultado -l por

将 PDF 页面转换为 PNG 图像：

convert -density 150 document.pdf page_%03d.png

加密 PDF：

pdftk sensitive.pdf output protected.pdf user_pw "secret123"