文档处理与转换技能，基于 MarkItDown 工具。支持将 PDF、Word、PowerPoint、Excel、图片、音频等多种格式文件批量转换为 Markdown。适用于文档数字化、知识库构建、内容提取等场景。
MarkItDown 是 Microsoft 开发的多功能文档转换工具，能够将各种文件格式高质量转换为 Markdown 格式。本技能提供完整的文档处理工作流，包括：
确保已安装 Python 3.10 或更高版本。建议使用虚拟环境：
# 创建虚拟环境
python -m venv .venv
# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate
# 安装完整功能（推荐）
pip install 'markitdown[all]'
# 或按需安装特定格式支持
pip install 'markitdown[pdf,docx,pptx]'
可选依赖组说明：
[all] - 所有格式支持（PDF、Office、图片、音频、HTML 等）[pdf] - PDF 处理（包含 OCR）[docx] - Word 文档[pptx] - PowerPoint[xlsx] - Excel[image] - 图片 EXIF 和 OCR[audio] - 音频转录[html] - HTML 转换[ytdlp] - YouTube 下载本技能提供 NPX CLI 工具，可直接通过 npx 命令调用：
# 查看帮助
npx convert-markdown
# 转换单个文件
npx convert-markdown convert --input document.pdf --output document.md
# 转换目录
npx convert-markdown convert --input ./docs --output ./markdown
# 批量转换（指定格式）
npx convert-markdown batch --source ./docs --target ./markdown --include .pdf,.docx
# 覆盖已存在文件
npx convert-markdown convert --input document.pdf --output document.md --overwrite
CLI 命令说明：
| 命令 | 说明 | 参数 |
|---|---|---|
convert | 转换文件或目录 | --input, --output, --overwrite |
batch | 批量转换目录 | --source, --target, --include, --exclude |
转换单个文件：
markitdown document.pdf > document.md
markitdown presentation.pptx -o slides.md
批量处理目录：
# 转换当前目录所有支持文件
markitdown *.pdf *.docx *.pptx
# 递归处理子目录
markitdown ./docs/ --recursive
# 输出到指定目录
markitdown ./source/ -o ./output/
from markitdown import MarkItDown
# 创建转换器实例
md = MarkItDown()
# 转换文件
result = md.convert("document.pdf")
print(result.text_content)
# 转换并保存
with open("output.md", "w", encoding="utf-8") as f:
f.write(result.text_content)
将大量文档批量转换为 Markdown 格式，便于建立搜索索引：
# 创建输出目录
mkdir converted_docs
# 批量转换并保存
markitdown ./source_documents/ --recursive -o ./converted_docs/
对于扫描的 PDF 文件，需要安装 OCR 依赖：
pip install 'markitdown[pdf]' # 包含 OCR 功能
markitdown scanned_document.pdf -o text.md
MarkItDown 能够保留原始表格结构：
markitdown financial_report.xlsx > report.md
# 输出中的表格将保持 Markdown 表格格式
支持图片 OCR 和音频转录：
# 提取图片中的文字
markitdown screenshot.png > extracted_text.md
# 转换音频为文字记录
markitdown podcast.mp3 > transcript.md
在 Python 脚本中使用：
from pathlib import Path
from markitdown import MarkItDown
def convert_directory(input_dir, output_dir):
"""批量转换目录中的所有支持文件"""
md = MarkItDown()
input_path = Path(input_dir)
output_path = Path(output_dir)
output_path.mkdir(exist_ok=True)
for file_path in input_path.rglob("*"):
if file_path.is_file():
try:
result = md.convert(str(file_path))
rel_path = file_path.relative_to(input_path)
output_file = output_path / rel_path.with_suffix('.md')
output_file.parent.mkdir(parents=True, exist_ok=True)
output_file.write_text(result.text_content, encoding='utf-8')
print(f"✓ {file_path} -> {output_file}")
except Exception as e:
print(f"✗ {file_path}: {e}")
# 使用示例
convert_directory("./raw_docs/", "./markdown_docs/")
from markitdown import MarkItDown, StreamConverter
# 使用流式转换（处理大文件）
with open("large_file.pdf", "rb") as f:
md = MarkItDown()
result = md.convert_stream(f)
print(result.text_content)
MarkItDown 支持自定义转换器插件。如需扩展支持特殊格式，可开发自定义 DocumentConverter：
from markitdown import DocumentConverter
class CustomConverter(DocumentConverter):
def convert(self, file_stream, **kwargs):
# 实现自定义转换逻辑
pass
# 注册插件
md = MarkItDown(converters=[CustomConverter()])
MarkItDown 提供 Model Context Protocol (MCP) 服务器，可与 Claude Desktop 等 LLM 应用集成：
# 安装 MCP 服务器
pip install markitdown[all,mcp]
# 配置 Claude Desktop 使用
# 在 claude_desktop_config.json 中添加：
# "mcpServers": {
# "markitdown": {
# "command": "python",
# "args": ["-m", "markitdown.mcp"]
# }
# }
[all] 以确保格式兼容性；资源受限环境可按需安装convert_stream() 避免内存溢出| 问题 | 可能原因 | 解决方案 |
|---|---|---|
ModuleNotFoundError | 依赖未安装 | 重新运行 pip install 'markitdown[all]' |
| OCR 不工作 | 缺少 Tesseract | 安装 Tesseract OCR 引擎 |
| 图片转换失败 | PIL/Pillow 缺失 | pip install pillow |
| YouTube 失败 | yt-dlp 未安装 | pip install yt-dlp |
| 内存不足 | 文件太大 | 使用 convert_stream() 或分批处理 |
本技能包含以下资源目录：
2026-03-12 - v1.0.3 版本：
2026-03-09 - 初始版本，基于 MarkItDown 0.1.0+ 创建技能模板
ZIP package — ready to use