文档转 Markdown 的低风险默认选项：MIT 协议、微软维护、月度发版，纯转换无锁定；扫描件 OCR 需额外配 LLM 才生效。
适合谁
- 给 RAG / LLM 管线做文档预处理的团队（PDF/Word/PPT/Excel → Markdown）
- 需要本地批处理、不想引入重型解析服务的场景
- 想用 pip 直接集成进 Python 管线的开发者
不要用，如果要
- 核心诉求是扫描件 OCR——默认不带 OCR，需装 markitdown-ocr 插件并提供 LLM client（见 T1）
- 需要生产级版本承诺——项目仍在 0.1.x，API 可能随版本变动
体检卡
88 分 · 最后一次推送 2026-10-28，近 3 个月连续发版（v0.1.9 于 2026-10-21），微软官方仓库 193,080 star
85 分 · README 提供标准 pip/uv 安装路径，核心转换无 Docker 或系统级依赖
— 分 · 未评估 · 缺证据：未实测：缺大文件（百页 PDF）转换耗时与内存数据
85 分 · MIT 协议 + 输出即普通 Markdown，随时可换其它解析器，无私有格式
65 分 · 仓库无已发布安全公告（E1），但版本号仍处 0.1.x 且 open issues 772，接口稳定性未承诺
70 分 · README 载明插件机制与官方子包（markitdown-ocr、sample-plugin），第三方生态尚新
加权总分 81.6 / 100（仅已评维度参与，已评权重 80；公式：(88×25+85×20+85×15+65×10+70×10) ÷ 80）。未评估维度不记 0 分，也不参与计算。
| # | 红线类型 | 级别 | 判定 | 说明 | 来源 |
|---|---|---|---|---|---|
| R1 | 已停更 | 禁止级 | 未命中 | 最后一次推送 2026-10-28，距今 3 天 | 原文 |
| R2 | 协议不明 | 警示级 | 未命中 | GitHub 识别为 MIT（SPDX 标准），无歧义 | 原文 |
| R3 | 高危 CVE | 禁止级 | 未命中 | security-advisories 接口返回空，无已发布安全公告 | 原文 |
解剖：它到底怎么工作
无框架依赖的纯 Python 转换器：按扩展名分发到各格式 converter，统一输出 Markdown 文本。插件机制（默认关闭）用于扩展 OCR、YouTube 字幕等可选能力。
核心机制
输入文件按类型路由到对应 converter（PDF/DOCX/PPTX/XLSX/HTML/图片/音频），各 converter 产 Markdown 片段后拼接返回结果对象。
图片转文字、音频转写、扫描件 OCR 属可选路径，全部走外部 LLM client（README 载明同一 llm_client/llm_model 模式复用）。
扩展点
第三方插件：pip 安装后 enable_plugins=True 启用，官方示例见 markitdown-sample-plugin 仓库。
新格式：实现 converter 接口注册即可（AI 起草，待读源码核实注册 API 细节——推断 E3）。
未评估
大文件内存占用、并发安全、乱码 PDF 的容错行为——需实测后补充。
避坑指南
每条陷阱都有可点击来源（E1）；没有来源的「坑」不写。本报告共 2 条。
你会看到：转扫描版 PDF 时文字丢失但命令不报错——内置转换器把页面当无文字处理，OCR 结果悄悄没了。
根因：README 原文：未提供 llm_client 时插件仍会加载，但「OCR is silently skipped and the standard built-in converter is used instead」。OCR 依赖可选的 markitdown-ocr 插件 + OpenAI 兼容 client。
缓解：处理扫描件必须显式 pip install markitdown-ocr openai，并在 MarkItDown(enable_plugins=True, llm_client=…) 传入模型；转换后抽查输出是否含正文。
你会看到：升级小版本后 import 路径或参数报错。
根因：版本号仍在 0.1.x（发版记录可查），按语义化约定 0.x 的次版本允许破坏性变更。
缓解：requirements 固定到具体版本，升级前看 release notes 再动。
证据 E1 · https://api.github.com/repos/microsoft/markitdown/releases
成本账
| 上手时间 | 未评估（未实测：上手时间与百页级 PDF 的耗时/内存未跑过） |
|---|---|
| 算力 | CPU 即可（纯文本解析）；OCR 路径依赖外部 LLM API |
| 钱 | MIT 无许可费；OCR 走 LLM API 时按调用量计费 |
| 长期维护 | 跟随月度发版即可，破坏性变更风险见 T2 |
替代方案
| 候选 | 为什么可能不选它 |
|---|---|
| MinerU / marker 等专业 PDF 解析器 | 扫描件与复杂版面还原更好，但部署重、依赖多；纯文本型文档用 markitdown 更轻（推断，E3，未实测对比） |
| pymupdf4llm | 只覆盖 PDF；markitdown 的价值在 Office 全家桶统一入口（推断，E3） |
证据链
展开全部 6 条证据（断言 → 来源 → 等级）
| # | 断言 | 等级 | 来源 |
|---|---|---|---|
| E1 | star = 193,080；pushed_at = 2026-10-28T15:33:14Z；license SPDX = MIT | E1 | https://api.github.com/repos/microsoft/markitdown |
| E2 | 近 5 个 release：v0.1.9（2026-10-21）、v0.1.8（2026-09-21）等，呈月度节奏 | E1 | https://api.github.com/repos/microsoft/markitdown/releases |
| E3 | security-advisories 返回空列表，无已发布安全公告 | E1 | https://api.github.com/repos/microsoft/markitdown/security-advisories |
| E4 | README 载明支持 PDF/PPTX/DOCX/XLSX/图片(EXIF+OCR)/音频/HTML 等，OCR 需 markitdown-ocr 插件 + llm_client，缺省时静默跳过 | E1 | https://github.com/microsoft/markitdown#readme |
| E5 | 插件默认禁用，需 --use-plugins / enable_plugins=True 显式开启 | E1 | https://github.com/microsoft/markitdown#readme |
| E6 | open issues 772 | E1 | https://api.github.com/repos/microsoft/markitdown |