markitdownlisted
Install: claude install-skill CarolZ1/xaction-skills
# MarkItDown — 文件转 Markdown
## 概述 / Overview
MarkItDown 是微软出品的轻量 Python 工具，把常见文档转成**保留结构的 Markdown**，用于文本分析、搜索、AI/RAG 入库。它的目标不是像素级还原排版，而是产出「结构化、可直接喂给 LLM 的文本」。
本技能以 **MarkItDown 0.1.6**（2026-05-26 发布）为目标版本。新代码统一用 `result.markdown`；`result.text_content` 仅作为软弃用的兼容别名。其他版本也能用，但个别 API 可能有差异。
## 何时使用 / When to Use
用户出现以下意图时触发：
- 把 PDF / Word / Excel / PPT / HTML / CSV / JSON / XML / EPUB / ZIP 转成 Markdown
- 「提取这段文档的文字 / 表格」「读取这个 PDF 的内容」
- 准备把一批文档灌进 RAG、知识库、向量库
- 批量转换整个目录的办公文档
**不适用**：需要像素级还原排版、PDF 表单填写/水印/合并拆分（用专门的 pdf 技能）、拿到 bounding box 坐标（用 LiteParse 等布局解析器）。
## 路径选择 / Choose the Right Path
| 需求 | 推荐方案 |
|---|---|
| 本地可信的 PDF/Office/HTML/CSV/EPUB/ZIP | `convert_local()` |
| 已打开的字节流 / 上传内容 | `convert_stream()` + `StreamInfo` |
| 远程 HTTP(S) | 自己校验并抓取后，用 `convert_response()` |
| 扫描版 PDF / 图片内文字 | `markitdown-ocr` 插件、Azure 文档智能 |
| 音频转录 / YouTube | `audio-transcription` / `youtube-transcription` extra |
| 本地 agent 集成 | 官方 `markitdown-mcp`（STDIO 优先） |
## 安装 / Installation
首选隔离环境。有 `uv` 用 uv，没有就用 `pip`：
```bash
# 方式一：uv
uv venv --python 3.12 .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv pip install "markitdown[all]==0.1.6"
# 方式二：pip（等价降级路径）
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install "markitdown[all]==0.1.6"
```
按需只装部分转换器：`markitdown[pdf,docx,pptx,xlsx]`。可用 extra：`pptx` `docx` `xlsx` `xls` `pdf` `outlook` `audio-transcription` `youtube-transcription` `az-doc-intel` `az-content-unde