Document Converter（MarkItDown）是一个将 Office 文档和结构化文档转换为 Markdown 的技能，底层使用微软开源的 MarkItDown 工具，目的是让转换后的内容便于 LLM 消费。
用途 该技能用于把来源格式各异的资料统一转换为干净的 Markdown 文本，尤其适合学术研究场景，例如期刊 PDF、会议 PPTX、协作者提供的 DOCX、数据表格 XLSX 等。
支持的格式
- PDF（.pdf）：文本提取；扫描版 PDF 需要 OCR。
- Word（.docx）：保留段落、表格、列表、标题。
- PowerPoint（.pptx）：逐页转换，并包含演讲者备注。
- Excel（.xlsx、.xls）：逐工作表转换，表格转为 Markdown 表格。
- HTML（.html、.htm）：提取并清理内容。
- CSV（.csv）：转换为 Markdown 表格。
- JSON（.json）：美化打印的结构化输出。
- XML（.xml）：结构化文本提取。
- 图片（.jpg、.png、.gif、.bmp、.tiff）：OCR 文本提取（需要可选依赖）。
- 音频（.mp3、.wav）：转录（需要可选依赖）。
- ZIP（.zip）：递归转换其中包含的文件。
使用方式 当配置了 markitdown-mcp 服务器后，可使用 convert_to_markdown 工具： 工具：convert_to_markdown 参数：uri: "file:///absolute/path/to/document.pptx" uri 参数接受本地文件（file:///path/to/file.docx）和 HTTP URL（https://example.com/paper.pdf）。本地文件务必使用绝对路径和 file:// URI 方案。该工具返回转换后文档的完整 Markdown 文本内容。对于大型文档，输出可能相当大，建议在转换后进行摘要或提取相关章节。
CLI 回退方式 如果 MCP 服务器不可用，可通过 shell 直接使用 CLI：
转换单个文件
markitdown document.pptx
保存输出到文件
markitdown document.pptx > output.md
从 URL 转换
markitdown https://example.com/paper.pdf
学术研究工作流
- 会议演示分析：用 convert_to_markdown 转换演示文稿，输出保留幻灯片结构和演讲者备注，然后总结关键发现、方法和结论。
- PDF 论文审阅：将 PDF 转换为 Markdown，提取摘要、引言、方法、结果、讨论等章节，并与文献库交叉引用。
- 数据表格提取：将 XLSX 转换为 Markdown 表格，每个工作表成为独立章节，提取的表格可用于分析或比较。
- 批量文献处理：逐个转换文档，从内容中提取元数据（标题、作者、日期），并通过 library_add_paper 加入文献库。
输出质量说明
- DOCX：优秀；复杂版式可能丢失格式。
- PPTX：良好；图表会变成文字描述。
- XLSX：良好；合并单元格可能无法完美呈现。
- PDF：因 PDF 类型而异（文本型还是扫描型）。
- HTML：良好；JavaScript 渲染的内容无法捕获。
- CSV：优秀；直接表格转换。
适用场景 用户上传或引用 Office 文档（PPTX、DOCX、XLSX）；用户想分析 PDF 内容；用户需要从图片中提取文本（OCR）；用户想转换文档以纳入笔记或工作区；用户要求读取、总结或分析非 Markdown 文件；批量处理混合格式的研究资料。
不适用场景 文件已经是 Markdown 或纯文本；用户想编辑原始文档格式（应使用相应编辑器）；用户需要像素级保留版式（应使用原始格式）；文件是扫描版 PDF 且未配置 OCR 支持。
故障排查
- 找不到 markitdown：运行 pip install 'markitdown[all]'。
- MCP 工具不可用：确保已安装 markitdown-mcp 并在 openclaw.json 中配置。
- PDF 输出为空：PDF 可能是扫描版/纯图片，需要 OCR 依赖。
- 编码错误：确保文件未损坏，尝试从源应用重新保存。
- 大文件超时：超大文件改用 CLI 而非 MCP 转换。
安装 本地（macOS/Linux）： pip install 'markitdown[all]' markitdown-mcp 验证： markitdown --help Docker：MarkItDown 已预装在 Research-Claw Docker 镜像中。