markitdown-converter

name	markitdown-converter
description	Convert documents (PDF, Word, Excel, PPT, images, audio) to Markdown using Microsoft MarkItDown. Full workflow: format detection, conversion, OCR, LLM image description, batch processing. Use when user mentions document conversion, PDF to markdown, Word to markdown, OCR, 文档转换, PDF转Markdown, Word转换, 文件格式转换.
trigger-keywords	["markdown转换工具","文件转markdown工具","markitdown","文档转换","文件转换","PDF转markdown","Word转markdown","Excel转markdown","PPT转markdown","图片转markdown","音频转markdown","批量转换","OCR识别","文档格式转换","文件格式转换","文本提取"]

MarkItDown转换技能

基于Microsoft MarkItDown的文档转换系统，为OpenCode提供强大的文档处理能力。

核心功能

1. 多格式支持：PDF、Word (.docx)、Excel (.xlsx)、PowerPoint (.pptx)、图片、音频、HTML、文本等格式
2. 高质量转换：保留文档结构、表格、列表、链接等Markdown元素
3. 高级功能集成：
   • OCR图像文字识别：提取图片和PDF中的文字
   • Azure Document Intelligence：云端文档分析服务
   • LLM图像描述：使用GPT-4o等模型描述图片内容
   • 音频转录：提取音频文件中的文字
   • 插件系统：支持第三方插件扩展
4. 批量处理：支持文件夹批量转换和ZIP文件处理
5. 配置灵活：支持命令行参数和Python API两种使用方式

技术特性

• 基于Microsoft官方MarkItDown项目 (https://github.com/microsoft/markitdown)
• 轻量级Python工具，专注于保留文档结构
• 输出为高质量的Markdown格式，适合LLM处理
• 完善的错误处理和进度提示
• 支持本地文件和网络URL

自动检测规则

当以下情况出现时自动触发文档转换：

1. 文件路径检测：消息中包含.pdf、.docx、.xlsx、.pptx、.jpg、.png等扩展名
2. 转换关键词：用户明确请求文档转换、格式转换、Markdown转换
3. 上下文感知：在讨论文档处理、文本提取相关内容时自动提供转换服务

使用方法

基本文件转换

# 导入技能脚本
import sys
sys.path.insert(0, "SKILL_DIR/scripts")
from markitdown_wrapper import convert_file

# 单文件转换
result = convert_file("document.pdf", output_path="document.md")

# 批量转换
from markitdown_wrapper import batch_convert
batch_convert("input_folder/", "output_folder/")

命令行使用

# 单文件转换
python scripts/markitdown_wrapper.py convert document.pdf -o document.md

# 批量转换文件夹
python scripts/markitdown_wrapper.py batch input_folder/ output_folder/

# 使用高级选项
python scripts/markitdown_wrapper.py convert document.pdf --use-ocr --llm-model gpt-4o

高级功能

from markitdown_wrapper import MarkItDownWrapper

# 创建转换器实例
wrapper = MarkItDownWrapper(
    enable_plugins=True,           # 启用插件系统
    use_ocr=True,                  # 启用OCR
    llm_model="gpt-4o",           # LLM图像描述模型
    docintel_endpoint="https://..." # Azure Document Intelligence
)

# 转换文件
result = wrapper.convert("document_with_images.pdf", output_path="output.md")

支持的文件格式

格式	扩展名	特性
PDF	.pdf	文字提取、OCR图像识别
Word文档	.docx	保留样式、表格、列表
Excel表格	.xlsx, .xls	表格数据转换
PowerPoint	.pptx	幻灯片内容提取
图片文件	.jpg, .png, .gif, .bmp	OCR文字识别、LLM图像描述
音频文件	.mp3, .wav	语音转文字
HTML网页	.html	网页内容提取
文本文件	.txt, .csv, .json, .xml	直接转换
ZIP压缩包	.zip	批量处理内部文件
YouTube视频	URL	字幕提取

配置说明

基本依赖安装

pip install 'markitdown[all]'

可选依赖（按需安装）

# 仅安装基本功能
pip install markitdown

# 按格式安装
pip install 'markitdown[pdf]'       # PDF支持
pip install 'markitdown[docx]'      # Word支持
pip install 'markitdown[pptx]'      # PowerPoint支持
pip install 'markitdown[xlsx]'      # Excel支持
pip install 'markitdown[ocr]'       # OCR支持
pip install 'markitdown[audio]'     # 音频转录

插件安装

# 安装OCR插件
pip install markitdown-ocr

# 启用插件
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=True)

示例输出

[MarkItDown转换结果] (耗时3.2秒 | 文件: document.pdf)
------------------------------------------------------------
# 示例文档标题

这是一个示例PDF文档转换为Markdown的展示。

## 第一章 介绍

MarkItDown能够很好地保留文档的结构：

1. 列表项一
2. 列表项二
3. 列表项三

### 表格示例

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 数据1 | 数据2 | 数据3 |
| 数据4 | 数据5 | 数据6 |

**重要提示**：转换结果保持了原始文档的层级结构和格式元素。
------------------------------------------------------------

高级功能详解

OCR图像文字识别

from markitdown_wrapper import convert_with_ocr

# 使用OCR转换图片或PDF
result = convert_with_ocr(
    "scanned_document.pdf",
    llm_client=OpenAI(),
    llm_model="gpt-4o"
)

Azure Document Intelligence

# 使用Azure云端服务
result = convert_with_azure(
    "document.pdf",
    endpoint="https://your-endpoint.cognitiveservices.azure.com/",
    api_key="your-api-key"
)

批量处理

from markitdown_wrapper import BatchProcessor

processor = BatchProcessor(
    input_dir="documents/",
    output_dir="markdown/",
    recursive=True,           # 递归处理子文件夹
    file_patterns=["*.pdf", "*.docx"]  # 指定文件类型
)
processor.process()  # 开始批量转换

错误处理

系统会优雅处理各种错误情况：

• 文件不存在或无法访问
• 不支持的格式
• 转换过程中断
• 依赖缺失
• API调用失败

所有错误都会提供友好的中文提示和解决方案建议。

性能优化

1. 缓存系统：相同文件的转换结果可选择性缓存
2. 批量处理：支持文件夹批量转换，减少重复操作
3. 并发支持：批量处理时可选择并行转换
4. 进度显示：显示转换进度和预估时间

集成提示

本技能设计为与OpenCode无缝集成：

• 自动检测对话中的文档转换需求
• 与现有工具和技能协同工作
• 保持OpenCode的对话风格和用户体验
• 提供有价值的文档处理能力增强

注意事项

• 文件大小：大文件转换可能需要较长时间
• OCR精度：图像文字识别精度取决于图片质量
• 格式兼容：某些复杂格式可能无法完美转换
• 依赖管理：建议使用虚拟环境管理依赖