markitdown-converter

# 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. **上下文感知**：在讨论文档处理、文本提取相关内容时自动提供转换服务 ## 使用方法 ### 基本文件转换 ```python # 导入技能脚本 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/") ``` ### 命令行使用 ```bash # 单文件转换 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 ``` ### 高级功能 ```python 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 | 字幕提取 | ## 配置说明 ### 基本依赖安装 ```bash pip install 'markitdown[all]' ``` ### 可选依赖（按需安装） ```bash # 仅安装基本功能 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]' # 音频转录 ``` ### 插件安装 ```bash # 安装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图像文字识别 ```python 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 ```python # 使用Azure云端服务 result = convert_with_azure( "document.pdf", endpoint="https://your-endpoint.cognitiveservices.azure.com/", api_key="your-api-key" ) ``` ### 批量处理 ```python 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精度**：图像文字识别精度取决于图片质量 - **格式兼容**：某些复杂格式可能无法完美转换 - **依赖管理**：建议使用虚拟环境管理依赖