pdf-to-markdown

用途

pdf-to-markdown 用于将 PDF 文件转换为格式良好的 Markdown 文档，并自动判断 PDF 属于原生文本型还是扫描件，从而选择对应的转换路径。

主要能力

自动检测：自动判断 PDF 是否包含可提取文本，决定使用原生提取还是回退到 OCR 提示。
原生文本转换：使用 @opendocsg/pdf2md 快速提取原生文本型 PDF。
表格支持：保留基础表格结构。
跨平台：可在 Windows、macOS、Linux 上运行。
无系统依赖：纯 JavaScript 实现。

使用方式

运行环境要求 Node.js ≥18 及 npx（随 npm 提供）。无需 npm install，技能首次使用时通过 npx 运行 @opendocsg/pdf2md（由 npx 缓存）。也可选在技能目录中运行 npm install 以加快后续运行。

基本转换（自动检测原生或扫描）：

node .agents/skills/pdf-to-markdown/scripts/convert.cjs --input ./document.pdf

指定输出路径：

node .agents/skills/pdf-to-markdown/scripts/convert.cjs -i ./doc.pdf -o ./output.md

强制原生模式（跳过 OCR 检测）：

node .agents/skills/pdf-to-markdown/scripts/convert.cjs -i ./doc.pdf --mode native

CLI 选项：

--input / -i：输入 PDF 文件路径（必填）
--output / -o：输出 Markdown 文件路径，默认 {input}.md
--mode / -m：转换模式，可选 auto、native、ocr，默认 auto
--help / -h：显示帮助信息

转换模式

Auto（默认）：检查首页是否包含可提取文本，若存在则使用原生提取，否则回退并提示 OCR。
Native：快速直接文本提取，适合可选择文本的 PDF（非扫描图像）。
OCR（扫描 PDF）：面向扫描文档，目前尚未实现，技能会在 PDF 疑似扫描件时给出提示。

输出

成功时返回 JSON，例如：

{
    "success": true,
    "input": "/path/to/input.pdf",
    "output": "/path/to/output.md",
    "stats": {
        "pages": 5,
        "mode": "native"
    }
}

适用场景

适用于将带有可选择文本的 PDF 快速转换为 Markdown，例如文档整理、内容迁移等场景。对于扫描件，当前会提示需要 OCR。

限制

复杂多栏布局可能无法保留结构。
扫描 PDF 的 OCR 准确率取决于图像质量（OCR 尚未实现）。
数学公式可能无法完美转换。
首次运行 OCR 会下载约 15MB 的语言数据。

OCR 设置（可选）

OCR 模式已接入技能但尚未实现。如需准备环境或自行扩展，可安装 OCR 依赖：

cd .agents/skills/pdf-to-markdown
npm install tesseract.js pdfjs-dist canvas

注意：canvas 包在某些系统上可能需要构建工具。

重要任务规划说明

该技能要求始终将工作拆分为多个小任务，并添加最终审查任务以验证工作质量、识别修复与改进点。