MarkItDown：文件转 Markdown

MarkItDown Skill 由 K-Dense 在 Claude Scientific Writer（MIT）中维护，教 Agent 正确使用微软开源的 MarkItDown 库。MarkItDown 把常见文档转换成保留结构的 Markdown，用于检索、文本分析和大模型读取，而不是像素级还原。该 Skill 当前 2.0 版对应 MarkItDown 0.1.6（2026 年 5 月 26 日发布），并纠正了一个常见误解：内置转换器不会在本地对扫描页做 OCR。

核心功能

• 按输入选方法：可信本地文件用 convert_local()，字节流用带 StreamInfo 提示的 convert_stream()，自己校验过的 HTTP 请求结果用 convert_response()。较宽松的 convert() 和 convert_uri() 只用于可信输入。
• 锁定版本安装：uv pip install "markitdown[all]==0.1.6"，或只装需要的扩展（pdf、docx、pptx、xlsx、xls、outlook、audio-transcription、youtube-transcription 以及 Azure 扩展）。
• 批量脚本：batch_convert.py 批量转换文件夹并生成清单，跳过符号链接，音频要发给云端转写必须显式加 --allow-external-services；convert_literature.py 转换论文 PDF，写入来源信息的 front matter，并可生成索引。
• OCR 选项：官方 markitdown-ocr 插件（需要支持视觉的 OpenAI 兼容客户端）、Azure Document Intelligence 或 Azure Content Understanding，[all] 都不会自动安装。
• MCP 服务器：markitdown-mcp 只暴露一个工具 convert_to_markdown(uri)。Skill 推荐用 STDIO，并提醒 HTTP/SSE 模式没有身份验证。

适用场景

• 把一批论文 PDF 和幻灯片整理进 RAG 索引。
• 把 XLSX 或 DOCX 里的表格提取成 Agent 能读的 Markdown。
• 给 Claude 配一个本地 MCP 工具，临时转换文档。

定价与获取

MarkItDown 和该 Skill 都免费，MIT 许可。本地转换可以离线运行；网址、YouTube、音频转写（通过 SpeechRecognition 调用 Google Web Speech）、大模型图片描述和 Azure 服务会把数据发到本机之外，并可能产生费用。

快速开始

1. 在 Claude Code 中安装插件：/plugin marketplace add https://github.com/K-Dense-AI/claude-scientific-writer，然后 /plugin install claude-scientific-writer。
2. 运行 uv venv --python 3.12 .venv 并激活，再安装锁定版本的包。
3. 执行 markitdown report.pdf -o report.md，并对照原文检查标题和表格。

局限：转换出的文本不可信，可能夹带提示词注入。扫描版 PDF 如果没有 OCR 插件或 Azure，几乎提取不出文字。插件在当前进程里执行 Python 代码，默认关闭。

常见问题

为什么用 result.markdown 而不是 text_content？

在 0.1.6 中 text_content 是软弃用的别名，新代码应读取 result.markdown。

会保留页面版式吗？

不会。需要边界框或页面坐标时，Skill 建议改用能识别版式的解析器。

替代方案

• PDF Skill：Anthropic 的 PDF Skill，可合并、拆分和创建 PDF，这些 MarkItDown 做不到。
• DOCX Skill：编辑 Word 文件，而不只是读取。
• Firecrawl：面向大模型的网页抓取 API，针对网站而非本地文件。

总结

当 Agent 需要快速、安全地从多种文件里取出文字时，MarkItDown Skill 是不错的默认选择。锁定版本，尽量在本地处理，并对照原文核对输出。更多文档工具见 Skills 分类。