{"id":"957631bf-a978-4125-9639-5b2fff777b29","entityType":"agent","slug":"clawhub-mapleshadow-markitdown-zh","name":"MarkItDown文档转换中文版","canonicalUrl":"https://www.xpersona.co/agent/clawhub-mapleshadow-markitdown-zh","canonicalPath":"/agent/clawhub-mapleshadow-markitdown-zh","generatedAt":"2026-10-11T03:54:22.934Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T01:07:37.878Z","emptyReason":null},"description":"使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"把这个 word 文档转成 Ma... Skill: MarkItDown文档转换中文版 Owner: mapleshadow Summary: 使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"把这个 word 文档转成 Ma... Tags: latest:1.0.4 Version history: v1.0.4 | 2026-05-20T07:52:28.415Z | user - 删除了 _meta.json 文件。 - 在描述中扩展了使用场景。 - 添加了用于分类的 # 标签部分。 - 改进了文档中的 pipx 和 PATH 安装说明。 v1.0.3 | 2026-04-23T12:42:43.524Z | user - 更新描","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s172w6e7nk99p5vfzya5jngc2h83hbcd:markitdown-zh","sourceUrl":"https://clawhub.ai/mapleshadow/markitdown-zh","homepage":"https://clawhub.ai/mapleshadow/skills/markitdown-zh","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/mapleshadow/markitdown-zh","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/mapleshadow/skills/markitdown-zh","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"把这个 word 文档转成 Ma..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T01:07:37.878Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T01:07:37.878Z","emptyReason":null},"stars":null,"forks":null,"downloads":1210,"packageName":null,"latestVersion":"1.0.4","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T01:07:37.811Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T01:07:37.878Z","lastCrawledAt":"2026-10-11T01:07:37.811Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T01:07:37.811Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.4","createdAt":"2026-05-20T07:52:28.415Z","changelog":"- 删除了 _meta.json 文件。 - 在描述中扩展了使用场景。 - 添加了用于分类的 # 标签部分。 - 改进了文档中的 pipx 和 PATH 安装说明。","fileCount":6,"zipByteSize":7882},{"version":"1.0.3","createdAt":"2026-04-23T12:42:43.524Z","changelog":"- 更新描述，明确列举支持的文档格式，如 CSV、JSON、TXT、EPUB、HTML 等。 - 移除“另请参阅”中的 USAGE-GUIDE.md 和 reference.md 说明，仅保留上游库链接。 - 其他内容保持不变。","fileCount":5,"zipByteSize":6449},{"version":"1.0.2","createdAt":"2026-04-23T12:38:38.278Z","changelog":"- 参照并重写","fileCount":5,"zipByteSize":6483},{"version":"1.0.1","createdAt":"2026-04-17T05:17:28.930Z","changelog":"markitdown-zh功能说明: - 支持使用微软 MarkItDown 库将多种文档类型（PDF、Word、PowerPoint、Excel、带 OCR 的图像、音频、HTML、YouTube）转换为 Markdown 格式。 - 提供命令行界面和 Python API 使用的设置说明。 - 包含使用示例和批量转换指南。 - 提供常见问题的故障排除部分。 - 附带了额外文档和用于批量操作的有用脚本。","fileCount":8,"zipByteSize":12510}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s172w6e7nk99p5vfzya5jngc2h83hbcd:markitdown-zh","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mapleshadow-markitdown-zh/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mapleshadow-markitdown-zh/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mapleshadow-markitdown-zh/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-mapleshadow-markitdown-zh/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-mapleshadow-markitdown-zh/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-mapleshadow-markitdown-zh/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T03:54:22.934Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mapleshadow-markitdown-zh/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mapleshadow-markitdown-zh/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mapleshadow-markitdown-zh/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mapleshadow-markitdown-zh/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T01:07:37.878Z","emptyReason":null},"readme":"Skill: MarkItDown文档转换中文版\n\nOwner: mapleshadow\n\nSummary: 使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"把这个 word 文档转成 Ma...\n\nTags: latest:1.0.4\n\nVersion history:\n\nv1.0.4 | 2026-05-20T07:52:28.415Z | user\n\n- 删除了 _meta.json 文件。\n- 在描述中扩展了使用场景。\n- 添加了用于分类的 # 标签部分。\n- 改进了文档中的 pipx 和 PATH 安装说明。\n\nv1.0.3 | 2026-04-23T12:42:43.524Z | user\n\n- 更新描述，明确列举支持的文档格式，如 CSV、JSON、TXT、EPUB、HTML 等。\n- 移除“另请参阅”中的 USAGE-GUIDE.md 和 reference.md 说明，仅保留上游库链接。\n- 其他内容保持不变。\n\nv1.0.2 | 2026-04-23T12:38:38.278Z | user\n\n- 参照并重写\n\nv1.0.1 | 2026-04-17T05:17:28.930Z | user\n\nmarkitdown-zh功能说明:\n- 支持使用微软 MarkItDown 库将多种文档类型（PDF、Word、PowerPoint、Excel、带 OCR 的图像、音频、HTML、YouTube）转换为 Markdown 格式。\n- 提供命令行界面和 Python API 使用的设置说明。\n- 包含使用示例和批量转换指南。\n- 提供常见问题的故障排除部分。\n- 附带了额外文档和用于批量操作的有用脚本。\n\nArchive index:\n\nArchive v1.0.4: 6 files, 7882 bytes\n\nFiles: scripts/batch_convert.py (3842b), scripts/convert.py (2417b), scripts/extract_images.py (3571b), skill-card.md (2342b), SKILL.md (3568b), _meta.json (132b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: markitdown-zh\ndescription: 使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"把这个 word 文档转成 Markdown\"，(3) \"批量转换这个文件夹里的文档\"，(4) \"提取文档中的图片\"。\n---\n# tags\n\"文档转换\", \"markitdown\", \".docx .xlsx .pptx\", \"OCR\"\n\n# MarkItDown 文档转换技能\n\n使用微软的 markitdown 库将各种文档格式转换为 Markdown。\n\n## 支持的格式\n\n- PDF (.pdf)\n- Word 文档 (.docx)\n- PowerPoint 演示文稿 (.pptx)\n- Excel 电子表格 (.xlsx .xls)\n- HTML 文件 (.html, .htm)\n- 纯文本文件 (.txt, .rtf, .xml, .csv, .json)\n- 电子书 (.epub)\n- 等等...\n\n## 快速开始\n\n### 单个文件转换\n\n```python\nfrom markitdown import MarkItDown\n\nmd = MarkItDown()\nresult = md.convert(\"document.pdf\")\nprint(result.text_content)\n```\n\n### 使用提供的脚本\n\n```bash\n# 转换单个文件\npython3 scripts/convert.py input.pdf output.md\n\n# 批量转换文件夹\npython3 scripts/batch_convert.py input_folder/ output_folder/\n\n# 提取文档中的图片\npython3 scripts/extract_images.py document.pdf images_folder/\n```\n\n## 详细用法\n\n### 单个文件转换\n\n使用 `scripts/convert.py`：\n\n```bash\npython3 scripts/convert.py <input_file> [output_file]\n```\n\n如果不指定输出文件，会自动生成 `.md` 文件。\n\n### 批量转换\n\n使用 `scripts/batch_convert.py`：\n\n```bash\npython3 scripts/batch_convert.py <input_directory> <output_directory>\n```\n\n会递归处理目录中的所有支持的文件。\n\n### 图片提取\n\n使用 `scripts/extract_images.py`：\n\n```bash\npython3 scripts/extract_images.py <input_file> <output_directory>\n```\n\n从文档中提取所有图片并保存到指定目录。\n\n## 脚本说明\n\n- `scripts/convert.py` - 单个文件转换脚本\n- `scripts/batch_convert.py` - 批量转换脚本\n- `scripts/extract_images.py` - 图片提取脚本\n\n每个脚本都有 `--help` 选项查看详细参数。\n\n## 安装依赖\n\n### Python 版本要求\n\nmarkitdown 需要 Python 3.10 或更高版本。\n\n检查 Python 版本：\n```bash\npython3.12 --version  # 或 python3.11, python3.13\n```\n\n### 安装 markitdown\n\n使用 Python 3.10+ 安装：\n\n```bash\n# 使用 Python 3.12（推荐）\n# 使用虚拟环境（适用于非root用户，如node用户）\npython3.12 -m venv markitdown-env\nsource markitdown-env/bin/activate\npip install \"markitdown[all]\"\n\n# 或安装pipx包管理应用，通过pipx安装markitdown\nsudo apt-get install pipx\n# 使用pipx安装markitdown包 all表示支持所有格式\npipx install 'markitdown[all]'\n# 将通过pipx安装的包路径放入当前变量PATH内\npipx ensurepath\n```\n\n### 可选：系统依赖\n\n某些格式转换可能需要额外的系统依赖：\n\n- **PDF 处理**: `brew install poppler` (macOS) 或 `sudo apt-get install poppler-utils` (Linux)\n- **OCR**: `brew install tesseract` (macOS) 或 `sudo apt-get install tesseract-ocr` (Linux)\n\n## 验证安装\n\n```bash\npython3.12 -c \"from markitdown import MarkItDown; print('安装成功!')\"\n```\n\n## 使用脚本\n\n所有脚本都支持使用特定 Python 版本运行：\n\n```bash\n# 使用 Python 3.12 运行\npython3.12 scripts/convert.py input.pdf output.md\npython3.12 scripts/batch_convert.py input_folder/ output_folder/\npython3.12 scripts/extract_images.py document.pdf images_folder/\n```\n\n## 另请参阅\n\n- [Microsoft MarkItDown](https://github.com/microsoft/markitdown) - 上游库\n\nFile v1.0.4:_meta.json\n\n{\n  \"ownerId\": \"kn74phsn575zqnc4rb0zznbv8n827127\",\n  \"slug\": \"markitdown-zh\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1779263548415\n}\n\nFile v1.0.4:skill-card.md\n\n## Description:\n\n使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown，并支持批量转换和图片提取。\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[mapleshadow](https://clawhub.ai/user/mapleshadow)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and document-processing users use this skill to convert individual files or folders of PDFs, Office documents, spreadsheets, text files, ebooks, and HTML into Markdown. It can also help extract document images when the underlying MarkItDown conversion result exposes them.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Installing MarkItDown with optional dependencies or system packages may add software the user has not reviewed.\n\nMitigation: Use a virtual environment or pipx under the user account, pin dependency versions where possible, and review package installation commands before running them.\n\nRisk: Batch conversion recursively reads files from the input directory.\n\nMitigation: Point batch conversion only at folders containing documents intended for conversion.\n\nRisk: Converted Markdown and extracted images can contain sensitive content from the source documents.\n\nMitigation: Write outputs to an approved location and handle generated files according to the same data controls as the source documents.\n\n## Reference(s):\n\n- [Microsoft MarkItDown](https://github.com/microsoft/markitdown)\n- [ClawHub skill page](https://clawhub.ai/mapleshadow/skills/markitdown-zh)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration]\n\n**Output Format:** [Markdown guidance with Python and shell command examples; scripts produce Markdown files and extracted image files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires Python 3.10+ and the MarkItDown package; optional system dependencies may be needed for some formats.]\n\n## Skill Version(s):\n\n1.0.4 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.3: 5 files, 6449 bytes\n\nFiles: _meta.json (132b), scripts/batch_convert.py (3842b), scripts/convert.py (2417b), scripts/extract_images.py (3571b), SKILL.md (3428b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: markitdown-zh\ndescription: 使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"批量转换这个文件夹里的文档\"，(3) \"提取文档中的图片\"。\n---\n\n# MarkItDown 文档转换技能\n\n使用微软的 markitdown 库将各种文档格式转换为 Markdown。\n\n## 支持的格式\n\n- PDF (.pdf)\n- Word 文档 (.docx)\n- PowerPoint 演示文稿 (.pptx)\n- Excel 电子表格 (.xlsx .xls)\n- HTML 文件 (.html, .htm)\n- 纯文本文件 (.txt, .rtf, .xml, .csv, .json)\n- 电子书 (.epub)\n- 等等...\n\n## 快速开始\n\n### 单个文件转换\n\n```python\nfrom markitdown import MarkItDown\n\nmd = MarkItDown()\nresult = md.convert(\"document.pdf\")\nprint(result.text_content)\n```\n\n### 使用提供的脚本\n\n```bash\n# 转换单个文件\npython3 scripts/convert.py input.pdf output.md\n\n# 批量转换文件夹\npython3 scripts/batch_convert.py input_folder/ output_folder/\n\n# 提取文档中的图片\npython3 scripts/extract_images.py document.pdf images_folder/\n```\n\n## 详细用法\n\n### 单个文件转换\n\n使用 `scripts/convert.py`：\n\n```bash\npython3 scripts/convert.py <input_file> [output_file]\n```\n\n如果不指定输出文件，会自动生成 `.md` 文件。\n\n### 批量转换\n\n使用 `scripts/batch_convert.py`：\n\n```bash\npython3 scripts/batch_convert.py <input_directory> <output_directory>\n```\n\n会递归处理目录中的所有支持的文件。\n\n### 图片提取\n\n使用 `scripts/extract_images.py`：\n\n```bash\npython3 scripts/extract_images.py <input_file> <output_directory>\n```\n\n从文档中提取所有图片并保存到指定目录。\n\n## 脚本说明\n\n- `scripts/convert.py` - 单个文件转换脚本\n- `scripts/batch_convert.py` - 批量转换脚本\n- `scripts/extract_images.py` - 图片提取脚本\n\n每个脚本都有 `--help` 选项查看详细参数。\n\n## 安装依赖\n\n### Python 版本要求\n\nmarkitdown 需要 Python 3.10 或更高版本。\n\n检查 Python 版本：\n```bash\npython3.12 --version  # 或 python3.11, python3.13\n```\n\n### 安装 markitdown\n\n使用 Python 3.10+ 安装：\n\n```bash\n# 使用 Python 3.12（推荐）\n# 安装pipx包管理应用，通过pipx安装包不需要（或者说是自动）新建虚拟环境\nsudo apt-get install pipx\n# 使用pipx安装markitdown包 all表示支持所有格式\npipx install 'markitdown[all]'\n\n# 或使用虚拟环境（适用于非root用户，如node用户）\npython3.12 -m venv markitdown-env\nsource markitdown-env/bin/activate\npip install \"markitdown[all]\"\n```\n\n### 可选：系统依赖\n\n某些格式转换可能需要额外的系统依赖：\n\n- **PDF 处理**: `brew install poppler` (macOS) 或 `sudo apt-get install poppler-utils` (Linux)\n- **OCR**: `brew install tesseract` (macOS) 或 `sudo apt-get install tesseract-ocr` (Linux)\n\n## 验证安装\n\n```bash\npython3.12 -c \"from markitdown import MarkItDown; print('安装成功!')\"\n```\n\n## 使用脚本\n\n所有脚本都支持使用特定 Python 版本运行：\n\n```bash\n# 使用 Python 3.12 运行\npython3.12 scripts/convert.py input.pdf output.md\npython3.12 scripts/batch_convert.py input_folder/ output_folder/\npython3.12 scripts/extract_images.py document.pdf images_folder/\n```\n\n## 另请参阅\n\n- [Microsoft MarkItDown](https://github.com/microsoft/markitdown) - 上游库\n\nFile v1.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn74phsn575zqnc4rb0zznbv8n827127\",\n  \"slug\": \"markitdown-zh\",\n  \"version\": \"1.0.3\",\n  \"publishedAt\": 1776948163524\n}\n\nArchive v1.0.2: 5 files, 6483 bytes\n\nFiles: _meta.json (132b), scripts/batch_convert.py (3842b), scripts/convert.py (2417b), scripts/extract_images.py (3571b), SKILL.md (3503b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: markitdown-zh\ndescription: 使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、xlsx、xls、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"批量转换这个文件夹里的文档\"，(3) \"提取文档中的图片\"。\n---\n\n# MarkItDown 文档转换技能\n\n使用微软的 markitdown 库将各种文档格式转换为 Markdown。\n\n## 支持的格式\n\n- PDF (.pdf)\n- Word 文档 (.docx)\n- PowerPoint 演示文稿 (.pptx)\n- Excel 电子表格 (.xlsx .xls)\n- HTML 文件 (.html, .htm)\n- 纯文本文件 (.txt, .rtf, .xml, .csv, .json)\n- 电子书 (.epub)\n- 等等...\n\n## 快速开始\n\n### 单个文件转换\n\n```python\nfrom markitdown import MarkItDown\n\nmd = MarkItDown()\nresult = md.convert(\"document.pdf\")\nprint(result.text_content)\n```\n\n### 使用提供的脚本\n\n```bash\n# 转换单个文件\npython3 scripts/convert.py input.pdf output.md\n\n# 批量转换文件夹\npython3 scripts/batch_convert.py input_folder/ output_folder/\n\n# 提取文档中的图片\npython3 scripts/extract_images.py document.pdf images_folder/\n```\n\n## 详细用法\n\n### 单个文件转换\n\n使用 `scripts/convert.py`：\n\n```bash\npython3 scripts/convert.py <input_file> [output_file]\n```\n\n如果不指定输出文件，会自动生成 `.md` 文件。\n\n### 批量转换\n\n使用 `scripts/batch_convert.py`：\n\n```bash\npython3 scripts/batch_convert.py <input_directory> <output_directory>\n```\n\n会递归处理目录中的所有支持的文件。\n\n### 图片提取\n\n使用 `scripts/extract_images.py`：\n\n```bash\npython3 scripts/extract_images.py <input_file> <output_directory>\n```\n\n从文档中提取所有图片并保存到指定目录。\n\n## 脚本说明\n\n- `scripts/convert.py` - 单个文件转换脚本\n- `scripts/batch_convert.py` - 批量转换脚本\n- `scripts/extract_images.py` - 图片提取脚本\n\n每个脚本都有 `--help` 选项查看详细参数。\n\n## 安装依赖\n\n### Python 版本要求\n\nmarkitdown 需要 Python 3.10 或更高版本。\n\n检查 Python 版本：\n```bash\npython3.12 --version  # 或 python3.11, python3.13\n```\n\n### 安装 markitdown\n\n使用 Python 3.10+ 安装：\n\n```bash\n# 使用 Python 3.12（推荐）\n# 安装pipx包管理应用，通过pipx安装包不需要（或者说是自动）新建虚拟环境\nsudo apt-get install pipx\n# 使用pipx安装markitdown包 all表示支持所有格式\npipx install 'markitdown[all]'\n\n# 或使用虚拟环境（适用于非root用户，如node用户）\npython3.12 -m venv markitdown-env\nsource markitdown-env/bin/activate\npip install \"markitdown[all]\"\n```\n\n### 可选：系统依赖\n\n某些格式转换可能需要额外的系统依赖：\n\n- **PDF 处理**: `brew install poppler` (macOS) 或 `sudo apt-get install poppler-utils` (Linux)\n- **OCR**: `brew install tesseract` (macOS) 或 `sudo apt-get install tesseract-ocr` (Linux)\n\n## 验证安装\n\n```bash\npython3.12 -c \"from markitdown import MarkItDown; print('安装成功!')\"\n```\n\n## 使用脚本\n\n所有脚本都支持使用特定 Python 版本运行：\n\n```bash\n# 使用 Python 3.12 运行\npython3.12 scripts/convert.py input.pdf output.md\npython3.12 scripts/batch_convert.py input_folder/ output_folder/\npython3.12 scripts/extract_images.py document.pdf images_folder/\n```\n\n## 另请参阅\n\n- [USAGE-GUIDE.md](USAGE-GUIDE.md) - 详细示例\n- [reference.md](reference.md) - 完整 API 参考\n- [Microsoft MarkItDown](https://github.com/microsoft/markitdown) - 上游库\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn74phsn575zqnc4rb0zznbv8n827127\",\n  \"slug\": \"markitdown-zh\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1776947918278\n}\n\nArchive v1.0.1: 8 files, 12510 bytes\n\nFiles: _meta.json (132b), package.json (578b), POST_INSTALL.md (2090b), README.md (2061b), reference.md (8416b), scripts/batch_convert.py (3380b), SKILL.md (3469b), USAGE-GUIDE.md (5362b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: markitdown-zh\ndescription: OpenClaw 智能体文档转换技能，用于将各类文档转换为 Markdown 格式，又称为 md 格式。基于微软 MarkItDown 库，支持 PDF、Word、PowerPoint、Excel、图像 (OCR)、音频 (转录)、HTML 和 YouTube 链接。\nmetadata:\n  openclaw:\n    emoji: \"📄\"\n    homepage: https://github.com/karmanverma/markitdown-skill\n    requires:\n      bins: [\"python3\", \"pipx\", \"markitdown\"]\n    install:\n      - id: \"markitdown\"\n        kind: \"pipx\"\n        package: \"markitdown[all]\"\n        bins: [\"markitdown\"]\n        label: \"安装 MarkItDown CLI (pipx)\"\n---\n\n# MarkItDown 技能\n\n使用微软 [MarkItDown](https://github.com/microsoft/markitdown) 库将文档转换为 Markdown 的文档和工具。\n\n> **注意：** 此技能提供文档和批量脚本。实际的转换由通过 pip 安装的 `markitdown` CLI/库完成。\n\n## 何时使用\n\n**使用 markitdown 进行：**\n- 📄 获取文档（README、API 文档）\n- 🌐 将网页转换为 markdown\n- 📝 文档分析（PDF、Word、PowerPoint）\n- 🎬 YouTube 转录\n- 🖼️ 图像文本提取（OCR）\n- 🎤 音频转录\n\n## 快速开始\n\n```bash\n# 将文件转换为 markdown\nmarkitdown document.pdf -o output.md\n\n# 转换 URL\nmarkitdown https://example.com/docs -o docs.md\n```\n\n## 支持的格式\n\n| 格式 | 功能 |\n|------|------|\n| PDF | 文本提取、结构保留 |\n| Word (.docx) | 标题、列表、表格 |\n| PowerPoint | 幻灯片、文本 |\n| Excel | 表格、工作表 |\n| 图像 | OCR + EXIF 元数据 |\n| 音频 | 语音转录 |\n| HTML | 结构保留 |\n| YouTube | 视频转录 |\n\n## 安装\n\n此技能需要微软的 `markitdown` CLI：\n\n```bash\nsudo apt-get install pipx\n# 使用pipx安装markitdown包 all表示支持所有格式\npipx install 'markitdown[all]'\n# 将markitdown调用路径放入当前变量PATH内\npipx ensurepath\n```\n\n或仅安装特定格式：\n```bash\nsudo apt-get install pipx\npip install 'markitdown[pdf,docx,pptx]'\npipx ensurepath\n```\n\n## 常用模式\n\n### 获取文档\n```bash\nmarkitdown https://github.com/user/repo/blob/main/README.md -o readme.md\n```\n\n### 转换 PDF\n```bash\nmarkitdown document.pdf -o document.md\n```\n\n### 批量转换\n```bash\n# 使用包含的脚本\npython ~/.openclaw/skills/markitdown-zh/scripts/batch_convert.py docs/*.pdf -o markdown/ -v\n\n# 或使用 shell 循环\nfor file in docs/*.pdf; do\n  markitdown \"$file\" -o \"${file%.pdf}.md\"\ndone\n```\n\n## Python API\n\n```python\nfrom markitdown import MarkItDown\n\nmd = MarkItDown()\nresult = md.convert(\"document.pdf\")\nprint(result.text_content)\n```\n\n## 故障排除\n\n### \"markitdown 未找到\"\n```bash\n# 安装pipx包管理应用，通过pipx安装包不需要（或者说是自动）新建虚拟环境\nsudo apt-get install pipx\n# 使用pipx安装markitdown包 all表示支持所有格式\npipx install 'markitdown[all]'\n# 将markitdown调用路径放入当前变量PATH内\npipx ensurepath\n```\n\n### OCR 无法工作\n```bash\n# Ubuntu/Debian\nsudo apt-get install tesseract-ocr\n\n# macOS\nbrew install tesseract\n```\n\n## 此技能提供的内容\n\n| 组件 | 来源 |\n|------|------|\n| `markitdown` CLI | 微软的 pip 包 |\n| `markitdown` Python API | 微软的 pip 包 |\n| `scripts/batch_convert.py` | 此技能（工具脚本） |\n| 文档 | 此技能 |\n\n## 另请参阅\n\n- [USAGE-GUIDE.md](USAGE-GUIDE.md) - 详细示例\n- [reference.md](reference.md) - 完整 API 参考\n- [Microsoft MarkItDown](https://github.com/microsoft/markitdown) - 上游库\n\nFile v1.0.1:README.md\n\n# markitdown-zh 技能\n\n📄 OpenClaw 等智能体文档转换技能，用于将各类文档转换为 Markdown 格式。基于微软 MarkItDown 库，支持 PDF、Word、PowerPoint、Excel、图像 (OCR)、音频 (转录)、HTML 和 YouTube 链接。\n\n**文档和工具** 用于微软的 [MarkItDown](https://github.com/microsoft/markitdown) 库。\n\n**原作者：** Karman Verma  \n**中文作者：** 枫影\n\n## 此技能是什么\n\n此技能提供：\n- ✅ MarkItDown 使用文档\n- ✅ 批量转换脚本 (`scripts/batch_convert.py`)\n- ✅ 使用示例和 API 参考\n\n实际的文档转换由微软的 `markitdown` CLI 完成，需要通过 pipx 单独安装（不使用pip）。\n\n## 安装\n\n### 通过 ClawHub\n\n```bash\nclawhub install markitdown-zh\n```\n\n### 手动安装\n\n安装 `markitdown` CLI：\n```bash\nsudo apt-get install pipx\n# 使用pipx安装markitdown包 all表示支持所有格式\npipx install 'markitdown[all]'\n# 将markitdown调用路径放入当前变量PATH内\npipx ensurepath\n```\n\n## 快速开始\n\n```bash\n# 转换 PDF 文件\nmarkitdown document.pdf -o document.md\n\n# 转换网页\nmarkitdown https://example.com/docs -o docs.md\n\n# 批量转换\npython scripts/batch_convert.py docs/*.pdf -o markdown/\n```\n\n## 支持的格式\n\n- **PDF** - 文本提取，结构保留\n- **Word (.docx)** - 标题、列表、表格\n- **PowerPoint** - 幻灯片、文本\n- **Excel** - 表格、工作表\n- **图像** - OCR + EXIF 元数据\n- **音频** - 语音转录\n- **HTML** - 结构保留\n- **YouTube** - 视频转录\n\n## 文件结构\n\n```\nmarkitdown-zh/\n├── SKILL.md          # 主技能文档\n├── README.md         # 此文件\n├── _meta.json        # 元数据\n├── scripts/\n│   └── batch_convert.py  # 批量转换脚本\n└── package.json      # 包信息\n```\n\n## 另请参阅\n\n- [SKILL.md](SKILL.md) - 完整技能文档\n- [USAGE-GUIDE.md](USAGE-GUIDE.md) - 详细使用指南\n- [reference.md](reference.md) - API 参考\n- [Microsoft MarkItDown](https://github.com/microsoft/markitdown) - 上游库\n\n## 许可证\n\nMIT\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn74phsn575zqnc4rb0zznbv8n827127\",\n  \"slug\": \"markitdown-zh\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1776403048930\n}\n\nFile v1.0.1:POST_INSTALL.md\n\n# 安装后设置\n\nMarkItDown 技能已安装！以下是开始使用的方法。\n\n## 1. 验证安装\n\n```bash\nmarkitdown --version\n```\n\n如果未找到，安装 CLI：\n```bash\nsudo apt-get install pipx\n# 使用pipx安装markitdown包 all表示支持所有格式\npipx install 'markitdown[all]'\n# 将markitdown调用路径放入当前变量PATH内\npipx ensurepath\n```\n\n## 2. 测试\n\n```bash\n# 转换 PDF\nmarkitdown document.pdf -o output.md\n\n# 转换 URL\nmarkitdown https://example.com -o page.md\n```\n\n## 3. 添加到智能体指令（推荐）\n\n添加到您的 `AGENTS.md`：\n\n```markdown\n## 文档转换\n当获取文档或转换文件时：\n- 使用 `markitdown <url>` 代替 curl/wget 获取网页文档\n- 使用 `markitdown <file>` 转换 PDF、Word、Excel 等文件\n- 输出是经过优化的干净 markdown，适合 LLM 分析\n```\n\n## 4. 安装特定格式的依赖项\n\n首先确保已安装pipx包管理器\n```bash\nsudo apt-get install pipx\npipx ensurepath\n```\n\n只安装您需要的部分：\n\n```bash\npipx install 'markitdown[pdf]'      # PDF 支持\npipx install 'markitdown[docx]'     # Word 文档\npipx install 'markitdown[pptx]'     # PowerPoint\npipx install 'markitdown[xlsx]'     # Excel\npipx install 'markitdown[audio-transcription]'   # 音频\npipx install 'markitdown[youtube-transcription]' # YouTube\n```\n\n或安装所有功能：\n```bash\npip install 'markitdown[all]'\n```\n\n## 5. 系统依赖项（可选）\n\n### OCR（用于图像）\n```bash\n# Ubuntu/Debian\nsudo apt-get install tesseract-ocr\n\n# macOS\nbrew install tesseract\n```\n\n## 快速参考\n\n```bash\n# 文件转换\nmarkitdown file.pdf -o output.md\n\n# URL 转换\nmarkitdown https://example.com -o page.md\n\n# 批量转换\npython ~/.openclaw/skills/markitdown-zh/scripts/batch_convert.py docs/*.pdf -o markdown/ -v\n```\n\n## 故障排除\n\n**\"markitdown 未找到\"**\n```bash\nsudo apt-get install pipx\npipx install 'markitdown[all]'\npipx ensurepath\n```\n\n**\"没有名为 'xxx' 的模块\"**\n```bash\npipx install 'markitdown[pdf]'  # 或 docx、pptx 等\n```\n\n**OCR 无法工作**\n```bash\nsudo apt-get install tesseract-ocr\n```\n\nFile v1.0.1:reference.md\n\n# MarkItDown API 参考\n\n## MarkItDown 类\n\n### 构造函数\n\n```python\nclass MarkItDown:\n    def __init__(\n        self,\n        enable_plugins: bool = False,\n        llm_client = None,\n        llm_model: str = None,\n        llm_prompt: str = None,\n        docintel_endpoint: str = None\n    )\n```\n\n**参数：**\n- `enable_plugins` (bool): 启用第三方插件（默认：False）\n- `llm_client`: 用于图像描述的 OpenAI 兼容客户端\n- `llm_model` (str): 图像描述的模型名称（例如：\"gpt-4o\"）\n- `llm_prompt` (str): 图像描述的自定义提示\n- `docintel_endpoint` (str): Azure Document Intelligence 端点\n\n**示例：**\n```python\nfrom markitdown import MarkItDown\n\n# 基本用法\nmd = MarkItDown()\n\n# 启用插件\nmd = MarkItDown(enable_plugins=True)\n\n# 使用 LLM 图像描述\nfrom openai import OpenAI\nclient = OpenAI()\nmd = MarkItDown(llm_client=client, llm_model=\"gpt-4o\")\n\n# 使用 Azure Document Intelligence\nmd = MarkItDown(docintel_endpoint=\"https://your-endpoint.cognitiveservices.azure.com/\")\n```\n\n### convert() 方法\n\n```python\ndef convert(\n    self,\n    source: str | Path | bytes | BinaryIO\n) -> ConversionResult\n```\n\n**参数：**\n- `source`: 文件路径（str/Path）、字节或类文件对象（二进制模式）\n\n**返回：**\n- 包含 `text_content` 属性的 `ConversionResult` 对象\n\n**示例：**\n```python\n# 从文件路径\nresult = md.convert(\"document.pdf\")\n\n# 从字节\nwith open(\"document.pdf\", \"rb\") as f:\n    result = md.convert(f.read())\n\n# 从类文件对象\nwith open(\"document.pdf\", \"rb\") as f:\n    result = md.convert(f)\n\nprint(result.text_content)\n```\n\n### convert_stream() 方法\n\n```python\ndef convert_stream(\n    self,\n    stream: BinaryIO,\n    file_extension: str = None\n) -> ConversionResult\n```\n\n**参数：**\n- `stream` (BinaryIO): 二进制类文件对象（例如：打开的文件、io.BytesIO）\n- `file_extension` (str): 可选的文件扩展名提示\n\n**返回：**\n- `ConversionResult` 对象\n\n**示例：**\n```python\nimport io\n\n# 从 BytesIO\ndata = io.BytesIO(pdf_bytes)\nresult = md.convert_stream(data, file_extension=\".pdf\")\n```\n\n## ConversionResult\n\n```python\nclass ConversionResult:\n    text_content: str  # Markdown 输出\n```\n\n**属性：**\n- `text_content` (str): 转换后的 markdown 内容\n\n## CLI 使用\n\n### 基本命令\n\n```bash\n# 转换到标准输出\nmarkitdown <文件>\n\n# 转换到文件\nmarkitdown <文件> -o <输出.md>\n\n# 管道输入\ncat <文件> | markitdown\n```\n\n### 选项\n\n```bash\nmarkitdown --help\nmarkitdown --list-plugins\nmarkitdown --use-plugins <文件>\nmarkitdown <文件> -d -e <端点>  # Azure Document Intelligence\n```\n\n## 格式特定详情\n\n### PDF\n- **最适合：** 基于文本的 PDF\n- **限制：** 复杂布局可能需要 Azure Document Intelligence\n- **依赖项：** `pip install 'markitdown[pdf]'`\n\n### PowerPoint (.pptx)\n- **提取：** 幻灯片文本、结构\n- **增强功能：** LLM 图像描述\n- **依赖项：** `pip install 'markitdown[pptx]'`\n\n### Word (.docx)\n- **保留：** 标题、列表、表格、链接\n- **依赖项：** `pip install 'markitdown[docx]'`\n\n### Excel (.xlsx, .xls)\n- **提取：** 表格、多个工作表\n- **格式：** Markdown 表格\n- **依赖项：** `pip install 'markitdown[xlsx]'` 或 `'markitdown[xls]'`\n\n### 图像 (jpg, png 等)\n- **提取：** EXIF 元数据 + OCR 文本\n- **需要：** Tesseract OCR 系统依赖项\n- **增强功能：** LLM 描述\n\n### 音频 (wav, mp3)\n- **提取：** EXIF 元数据 + 语音转录\n- **依赖项：** `pip install 'markitdown[audio-transcription]'`\n- **注意：** 可能需要系统音频库\n\n### YouTube\n- **提取：** 视频转录（如果可用）\n- **依赖项：** `pip install 'markitdown[youtube-transcription]'`\n- **用法：** `markitdown \"https://youtube.com/watch?v=视频_ID\"`\n\n### HTML\n- **保留：** 文档结构\n- **无需额外依赖项**\n\n### CSV/JSON/XML\n- **转换：** 为可读的 markdown 格式\n- **无需额外依赖项**\n\n### ZIP\n- **行为：** 遍历内部所有文件\n- **无需额外依赖项**\n\n### EPUB\n- **提取：** 电子书内容\n- **无需额外依赖项**\n\n## 环境要求\n\n### Python 版本\n- **必需：** Python 3.10 或更高版本\n- **推荐：** Python 3.12\n\n### 虚拟环境（推荐）\n\n```bash\n# 标准 Python\npython -m venv .venv\nsource .venv/bin/activate\n\n# uv\nuv venv --python=3.12 .venv\nsource .venv/bin/activate\n\n# Conda\nconda create -n markitdown python=3.12\nconda activate markitdown\n```\n\n### 系统依赖项\n\n**Tesseract OCR**（用于图像文本提取）：\n```bash\n# Ubuntu/Debian\nsudo apt-get install tesseract-ocr\n\n# macOS\nbrew install tesseract\n\n# Windows\n# 从 https://github.com/UB-Mannheim/tesseract/wiki 下载安装程序\n```\n\n**音频库**（用于音频转录）：\n- speech_recognition 库的平台特定依赖项\n- 查看：https://github.com/Uberi/speech_recognition\n\n## Azure Document Intelligence\n\n用于复杂布局的高质量 PDF 转换：\n\n### 设置\n\n1. 创建 Azure Document Intelligence 资源\n2. 获取端点和 API 密钥\n3. 设置环境变量：`AZURE_DOCUMENT_INTELLIGENCE_KEY=<您的密钥>`\n\n### 使用\n\n**CLI：**\n```bash\nmarkitdown document.pdf -d -e \"<端点>\" -o output.md\n```\n\n**Python：**\n```python\nmd = MarkItDown(docintel_endpoint=\"<端点>\")\nresult = md.convert(\"document.pdf\")\n```\n\n### 更多信息\nhttps://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/\n\n## 插件系统\n\n### 查找插件\n在 GitHub 搜索：`#markitdown-plugin`\n\n### 使用插件\n\n**CLI：**\n```bash\nmarkitdown --list-plugins\nmarkitdown --use-plugins file.pdf\n```\n\n**Python：**\n```python\nmd = MarkItDown(enable_plugins=True)\n```\n\n### 创建插件\n查看仓库中的：`packages/markitdown-sample-plugin`\n\n## 错误处理\n\n### 常见问题\n\n**缺少依赖项：**\n```python\ntry:\n    result = md.convert(\"file.pdf\")\nexcept ImportError as e:\n    print(f\"缺少依赖项：{e}\")\n    print(\"安装命令：pip install 'markitdown[pdf]'\")\n```\n\n**文件格式不支持：**\n```python\ntry:\n    result = md.convert(\"file.unknown\")\nexcept ValueError as e:\n    print(f\"不支持的格式：{e}\")\n```\n\n**转换错误：**\n```python\ntry:\n    result = md.convert(\"file.pdf\")\nexcept Exception as e:\n    print(f\"转换失败：{e}\")\n```\n\n## 性能提示\n\n1. **批量处理：** 重用 MarkItDown 实例\n2. **大文件：** 考虑分块或流式处理\n3. **OCR：** 如果速度重要，降低图像分辨率\n4. **音频：** 预期实时或更慢的转录\n5. **Azure Doc Intel：** 最适合复杂 PDF，会产生费用\n\n## 输出格式说明\n\n- **目标：** LLM 友好的 markdown，不是像素完美的复制\n- **结构：** 保留标题、列表、表格、链接\n- **图像：** 转换为 markdown 图像语法\n- **表格：** 转换为 markdown 表格（可能丢失复杂格式）\n- **样式：** 尽可能保留粗体、斜体\n- **布局：** 线性文档结构（不保留多列）\n\n## 集成示例\n\n### LangChain 文档加载器\n\n```python\nfrom markitdown import MarkItDown\nfrom langchain.docstore.document import Document\n\nmd = MarkItDown()\n\ndef load_document(file_path):\n    result = md.convert(file_path)\n    return Document(\n        page_content=result.text_content,\n        metadata={\"source\": file_path}\n    )\n```\n\n### LlamaIndex 文档\n\n```python\nfrom markitdown import MarkItDown\nfrom llama_index import Document\n\nmd = MarkItDown()\n\ndef create_llama_doc(file_path):\n    result = md.convert(file_path)\n    return Document(text=result.text_content)\n```\n\n### FastAPI 端点\n\n```python\nfrom fastapi import FastAPI, UploadFile\nfrom markitdown import MarkItDown\n\napp = FastAPI()\nmd = MarkItDown()\n\n@app.post(\"/convert\")\nasync def convert_file(file: UploadFile):\n    content = await file.read()\n    result = md.convert(content)\n    return {\"markdown\": result.text_content}\n```\n\n## 破坏性变更 (v0.0.1 → v0.1.0)\n\n1. **依赖项：** 现在按功能组组织\n   - 使用 `pipx install 'markitdown[all]'` 保持向后兼容性\n\n2. **convert_stream()：** 现在需要二进制类文件对象\n   - 从文本（io.StringIO）更改为二进制（io.BytesIO）\n\n3. **DocumentConverter：** 接口从路径更改为流\n   - 不再创建临时文件\n   - 插件作者需要更新代码\n\n## 资源\n\n- **GitHub：** https://github.com/microsoft/markitdown\n- **PyPI：** https://pypi.org/project/markitdown/\n- **问题：** https://github.com/microsoft/markitdown/issues\n- **贡献：** 查看仓库中的 CONTRIBUTING.md\n\nFile v1.0.1:USAGE-GUIDE.md\n\n# MarkItDown 使用指南\n\n文档转换的详细示例和模式。\n\n## CLI 使用\n\n### 基本转换\n\n```bash\n# 输出到标准输出\nmarkitdown document.pdf\n\n# 输出到文件\nmarkitdown document.pdf -o output.md\n\n# 从标准输入读取\ncat document.pdf | markitdown > output.md\n```\n\n### 网页内容\n\n```bash\n# 转换网页\nmarkitdown https://example.com/docs -o docs.md\n\n# 转换 GitHub README\nmarkitdown https://github.com/user/repo/blob/main/README.md -o readme.md\n```\n\n### 图像 OCR\n\n```bash\n# 提取图像中的文本\nmarkitdown image.jpg -o text.md\n\n# 使用 LLM 生成图像描述\nmarkitdown image.jpg --llm-model gpt-4o -o description.md\n```\n\n### 音频转录\n\n```bash\n# 转录音频文件\nmarkitdown audio.mp3 -o transcript.md\n```\n\n## 批量处理\n\n### 使用批量脚本\n\n```bash\n# 转换目录中的所有 PDF 文件\npython scripts/batch_convert.py docs/*.pdf -o markdown/\n\n# 详细输出\npython scripts/batch_convert.py docs/*.pdf -o markdown/ -v\n\n# 启用插件\npython scripts/batch_convert.py docs/*.pdf -o markdown/ -p\n```\n\n### Shell 循环\n\n```bash\n# 转换所有 PDF 文件\nfor file in *.pdf; do\n  markitdown \"$file\" -o \"${file%.pdf}.md\"\ndone\n\n# 转换所有 Word 文档\nfor file in *.docx; do\n  markitdown \"$file\" -o \"${file%.docx}.md\"\ndone\n```\n\n## Python API\n\n### 基本使用\n\n```python\nfrom markitdown import MarkItDown\n\n# 初始化转换器\nmd = MarkItDown()\n\n# 转换文件\nresult = md.convert(\"document.pdf\")\nprint(result.text_content)\n\n# 转换 URL\nresult = md.convert(\"https://example.com/docs\")\nprint(result.text_content)\n```\n\n### 高级配置\n\n```python\nfrom markitdown import MarkItDown\nfrom openai import OpenAI\n\n# 使用 LLM 客户端\nclient = OpenAI()\n\nmd = MarkItDown(\n    llm_client=client,\n    llm_model=\"gpt-4o\",\n    enable_plugins=True,\n    docintel_endpoint=\"https://your-endpoint.cognitiveservices.azure.com/\"\n)\n\nresult = md.convert(\"image.jpg\")\nprint(result.text_content)\n```\n\n### 处理结果\n\n```python\nfrom markitdown import MarkItDown\n\nmd = MarkItDown()\nresult = md.convert(\"document.pdf\")\n\n# 访问不同属性\nprint(f\"文本内容: {result.text_content}\")\nprint(f\"元数据: {result.metadata}\")\nprint(f\"结构: {result.structure}\")\nprint(f\"图像: {result.images}\")\nprint(f\"表格: {result.tables}\")\n```\n\n## 常见用例\n\n### 文档归档\n\n```bash\n# 将整个文档目录转换为 markdown\nfind docs/ -type f \\( -name \"*.pdf\" -o -name \"*.docx\" \\) -exec markitdown {} -o {}.md \\;\n```\n\n### 网页抓取\n\n```bash\n# 抓取并转换多个网页\nfor url in \"https://example.com/page1\" \"https://example.com/page2\"; do\n  filename=$(basename \"$url\")\n  markitdown \"$url\" -o \"pages/${filename}.md\"\ndone\n```\n\n### 会议记录\n\n```bash\n# 转录会议录音\nmarkitdown meeting.mp3 -o meeting_notes.md\n\n# 转换会议幻灯片\nmarkitdown presentation.pptx -o presentation_notes.md\n```\n\n## 故障排除\n\n### 常见错误\n\n**\"markitdown: command not found\"**\n```bash\n# 安装pipx包管理应用，通过pipx安装包不需要（或者说是自动）新建虚拟环境\nsudo apt-get install pipx\n# 使用pipx安装markitdown包 all表示支持所有格式\npipx install 'markitdown[all]'\n# 将markitdown调用路径放入当前变量PATH内\npipx ensurepath\n```\n\n**OCR 失败**\n```bash\n# 安装 Tesseract OCR\n# Ubuntu/Debian\nsudo apt-get install tesseract-ocr\n\n# macOS\nbrew install tesseract\n\n# Windows\n# 从 https://github.com/UB-Mannheim/tesseract/wiki 下载\n```\n\n### 性能优化\n\n**大文件处理**\n```bash\n# 分割大文件\nsplit -b 10M large_document.pdf document_part_\n\n# 分别转换每个部分\nfor part in document_part_*; do\n  markitdown \"$part\" -o \"${part}.md\"\ndone\n```\n\n**内存限制**\n```bash\n# 使用较小的模型\nmarkitdown document.pdf --model small -o output.md\n```\n\n## 最佳实践\n\n1. **测试小样本**：在处理大量文件前，先测试一个小样本\n2. **检查输出**：转换后检查输出文件的完整性\n3. **备份原始文件**：始终保留原始文件的备份\n4. **使用版本控制**：将转换后的 markdown 文件纳入版本控制\n5. **监控资源使用**：处理大文件时监控内存和 CPU 使用情况\n\n## 集成示例\n\n### 与 OpenClaw 集成\n\n```python\n# 在 OpenClaw 技能中使用 markitdown\nimport subprocess\n\ndef convert_to_markdown(input_file, output_file):\n    \"\"\"将文件转换为 markdown\"\"\"\n    try:\n        result = subprocess.run(\n            [\"markitdown\", input_file, \"-o\", output_file],\n            capture_output=True,\n            text=True,\n            check=True\n        )\n        return True, result.stdout\n    except subprocess.CalledProcessError as e:\n        return False, e.stderr\n```\n\n### 自动化工作流\n\n```bash\n#!/bin/bash\n# 自动化文档处理工作流\n\n# 1. 转换所有新文档\nfind ./incoming -type f -name \"*.pdf\" -mtime -1 | while read file; do\n  markitdown \"$file\" -o \"./markdown/$(basename \"$file\").md\"\ndone\n\n# 2. 生成摘要\necho \"# 每日文档摘要\" > daily_summary.md\necho \"生成时间: $(date)\" >> daily_summary.md\necho \"\" >> daily_summary.md\n\nfind ./markdown -name \"*.md\" -mtime -1 | while read file; do\n  echo \"## $(basename \"$file\")\" >> daily_summary.md\n  head -5 \"$file\" >> daily_summary.md\n  echo \"\" >> daily_summary.md\ndone\n```\n\n## 更多资源\n\n- [MarkItDown GitHub](https://github.com/microsoft/markitdown) - 官方仓库\n- [SKILL.md](SKILL.md) - 技能文档\n- [reference.md](reference.md) - 完整 API 参考\n\nFile v1.0.1:package.json\n\n{\n  \"name\": \"markitdown-zh\",\n  \"version\": \"1.0.1\",\n  \"description\": \"OpenClaw 智能体文档转换技能，用于将各类文档转换为 Markdown 格式。基于微软 MarkItDown 库，支持 PDF、Word、PowerPoint、Excel、图像 (OCR)、音频 (转录)、HTML 和 YouTube 链接。\",\n  \"author\": \"枫影\",\n  \"license\": \"MIT\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/mapleshadow/skills/tree/main/markitdown-zh\"\n  },\n  \"keywords\": [\n    \"openclaw\",\n    \"skill\",\n    \"markitdown\",\n    \"markdown\",\n    \"pdf\",\n    \"document\",\n    \"conversion\"\n  ]\n}","readmeExcerpt":"Skill: MarkItDown文档转换中文版 Owner: mapleshadow Summary: 使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"把这个 word 文档转成 Ma... Tags: latest:1.0.4 Version history: v1.0.4 | 2026-05-20T07:52:28.415Z | user - 删除了 _meta.json 文件。 - 在描述中扩展了使用场景。 - 添加了用于分类的 # 标签部分。 - 改进了文档中的 pipx 和 PATH 安装说明。 v1.0.3 | 2026-04-23T12:42:43.524Z | user - 更新描","codeSnippets":[],"executableExamples":[{"language":"python","snippet":"from markitdown import MarkItDown\n\nmd = MarkItDown()\nresult = md.convert(\"document.pdf\")\nprint(result.text_content)"},{"language":"bash","snippet":"# 转换单个文件\npython3 scripts/convert.py input.pdf output.md\n\n# 批量转换文件夹\npython3 scripts/batch_convert.py input_folder/ output_folder/\n\n# 提取文档中的图片\npython3 scripts/extract_images.py document.pdf images_folder/"},{"language":"bash","snippet":"python3 scripts/convert.py <input_file> [output_file]"},{"language":"bash","snippet":"python3 scripts/batch_convert.py <input_directory> <output_directory>"},{"language":"bash","snippet":"python3 scripts/extract_images.py <input_file> <output_directory>"},{"language":"bash","snippet":"python3.12 --version  # 或 python3.11, python3.13"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: markitdown-zh\ndescription: 使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"把这个 word 文档转成 Markdown\"，(3) \"批量转换这个文件夹里的文档\"，(4) \"提取文档中的图片\"。\n---\n# tags\n\"文档转换\", \"markitdown\", \".docx .xlsx .pptx\", \"OCR\"\n\n# MarkItDown 文档转换技能\n\n使用微软的 markitdown 库将各种文档格式转换为 Markdown。\n\n## 支持的格式\n\n- PDF (.pdf)\n- Word 文档 (.docx)\n- PowerPoint 演示文稿 (.pptx)\n- Excel 电子表格 (.xlsx .xls)\n- HTML 文件 (.html, .htm)\n- 纯文本文件 (.txt, .rtf, .xml, .csv, .json)\n- 电子书 (.epub)\n- 等等...\n\n## 快速开始\n\n### 单个文件转换\n\n```python\nfrom markitdown import MarkItDown\n\nmd = MarkItDown()\nresult = md.convert(\"document.pdf\")\nprint(result.text_content)\n```\n\n### 使用提供的脚本\n\n```bash\n# 转换单个文件\npython3 scripts/convert.py input.pdf output.md\n\n# 批量转换文件夹\npython3 scripts/batch_convert.py input_folder/ output_folder/\n\n# 提取文档中的图片\npython3 scripts/extract_images.py document.pdf images_folder/\n```\n\n## 详细用法\n\n### 单个文件转换\n\n使用 `scripts/convert.py`：\n\n```bash\npython3 scripts/convert.py <input_file> [output_file]\n```\n\n如果不指定输出文件，会自动生成 `.md` 文件。\n\n### 批量转换\n\n使用 `scripts/batch_convert.py`：\n\n```bash\npython3 scripts/batch_convert.py <input_directory> <output_directory>\n```\n\n会递归处理目录中的所有支持的文件。\n\n### 图片提取\n\n使用 `scripts/extract_images.py`：\n\n```bash\npython3 scripts/extract_images.py <input_file> <output_directory>\n```\n\n从文档中提取所有图片并保存到指定目录。\n\n## 脚本说明\n\n- `scripts/convert.py` - 单个文件转换脚本\n- `scripts/batch_convert.py` - 批量转换脚本\n- `scripts/extract_images.py` - 图片提取脚本\n\n每个脚本都有 `--help` 选项查看详细参数。\n\n## 安装依赖\n\n### Python 版本要求\n\nmarkitdown 需要 Python 3.10 或更高版本。\n\n检查 Python 版本：\n```bash\npython3.12 --version  # 或 python3.11, python3.13\n```\n\n### 安装 markitdown\n\n使用 Python 3.10+ 安装：\n\n```bash\n# 使用 Python 3.12（推荐）\n# 使用虚拟环境（适用于非root用户，如node用户）\npython3.12 -m venv markitdown-env\nsource markitdown-env/bin/activate\npip install \"markitdown[all]\"\n\n# 或安装pipx包管理应用，通过pipx安装markitdown\nsudo apt-get install pipx\n# 使用pipx安装markitdown包 all表示支持所有格式\npipx install 'markitdown[all]'\n# 将通过pipx安装的包路径放入当前变量PATH内\npipx ensurepath\n```\n\n### 可选：系统依赖\n\n某些格式转换可能需要额外的系统依赖：\n\n- **PDF 处理**: `brew install poppler` (macOS) 或 `sudo apt-get install poppler-utils` (Linux)\n- **OCR**: `brew install tesseract` (macOS) 或 `sudo apt-get install tesseract-ocr` (Linux)\n\n## 验证安装\n\n```bash\npython3.12 -c \"from markitdown import MarkItDown; print('安装成功!')\"\n```\n\n## 使用脚本\n\n所有脚本都支持使用特定 Python 版本运行：\n\n```bash\n# 使用 Python 3.12 运行\npython3.12 scripts/convert.py input.pdf output.md\npython3.12 scripts/batch_convert.py input_folder/ output_folder/\npython3.12 scripts/extract_images.py document.pdf images_folder/\n```\n\n## 另请参阅\n\n- [Microsoft MarkItDown](https://github.com/microsoft/markitdown) - 上游库"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn74phsn575zqnc4rb0zznbv8n827127\",\n  \"slug\": \"markitdown-zh\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1779263548415\n}"},{"path":"skill-card.md","content":"## Description:\n\n使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown，并支持批量转换和图片提取。\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[mapleshadow](https://clawhub.ai/user/mapleshadow)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and document-processing users use this skill to convert individual files or folders of PDFs, Office documents, spreadsheets, text files, ebooks, and HTML into Markdown. It can also help extract document images when the underlying MarkItDown conversion result exposes them.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Installing MarkItDown with optional dependencies or system packages may add software the user has not reviewed.\n\nMitigation: Use a virtual environment or pipx under the user account, pin dependency versions where possible, and review package installation commands before running them.\n\nRisk: Batch conversion recursively reads files from the input directory.\n\nMitigation: Point batch conversion only at folders containing documents intended for conversion.\n\nRisk: Converted Markdown and extracted images can contain sensitive content from the source documents.\n\nMitigation: Write outputs to an approved location and handle generated files according to the same data controls as the source documents.\n\n## Reference(s):\n\n- [Microsoft MarkItDown](https://github.com/microsoft/markitdown)\n- [ClawHub skill page](https://clawhub.ai/mapleshadow/skills/markitdown-zh)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration]\n\n**Output Format:** [Markdown guidance with Python and shell command examples; scripts produce Markdown files and extracted image files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires Python 3.10+ and the MarkItDown package; optional system dependencies may be needed for some formats.]\n\n## Skill Version(s):\n\n1.0.4 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"把这个 word 文档转成 Ma... Skill: MarkItDown文档转换中文版 Owner: mapleshadow Summary: 使用微软 markitdown 库将多种文档格式（PDF、DOCX、PPTX、XLSX、XLS、CSV、JSON、TXT、EPUB、HTML等）转换为 Markdown。支持批量转换、保留格式、图片提取等功能。使用场景：(1) \"把这个 PDF 转成 Markdown\"，(2) \"把这个 word 文档转成 Ma... Tags: latest:1.0.4 Version history: v1.0.4 | 2026-05-20T07:52:28.415Z | user - 删除了 _meta.json 文件。 - 在描述中扩展了使用场景。 - 添加了用于分类的 # 标签部分。 - 改进了文档中的 pipx 和 PATH 安装说明。 v1.0.3 | 2026-04-23T12:42:43.524Z | user - 更新描","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":771,"uniquenessScore":57,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T01:07:37.878Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T01:07:37.878Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T03:54:22.934Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}