Markdown Converter

Markdown Converter 是什么

Markdown Converter 是 markitdown 的轻量使用 Skill，通过 uvx 临时运行工具，把 PDF、Word、PowerPoint、Excel、HTML、CSV、JSON、XML、图片、音频、ZIP、YouTube 地址和 EPUB 转成适合检索、分析或交给大模型的 Markdown。

适用场景与选择边界

适合先把多种文件归一成文本，再做摘要、搜索和资料整理。复杂扫描 PDF、严格保真表格、法律证据、完整幻灯片视觉和专业音频转写仍需专门工具与人工回看；转换文本不是原文版式的等价副本。

核心能力与工作机制

可以输出到终端、文件或从 stdin 读取；stdin 可用扩展名、MIME 和字符集提示。输出尽量保留标题、表格、列表和链接。图片可提取 EXIF/OCR，音频可转录，ZIP 逐项处理；复杂 PDF 可选 Azure Document Intelligence。

实际工作流与交付结果

确认输入类型和输出位置，先对单个文件运行 uvx markitdown；stdin 场景补充类型提示。打开 Markdown 检查标题层级、表格、页序和乱码，再进入后续分析。扫描件提取差时，确认 Azure 账号、endpoint 和数据边界后才启用云端文档智能。

依赖、账号与权限

需要 uv/uvx，首次运行会下载并缓存 markitdown 依赖，后续更快。基本转换只需文件读写；Azure 路线需要云端 endpoint 和相应凭据，第三方插件只有显式启用后才会加载。

限制、成本与安全风险

把 ZIP、外部网址或插件当输入会扩大攻击面，应只处理用户授权内容。OCR、转录、表格和复杂排版会丢失信息；敏感文件启用 Azure 时会上传云端。重定向输出可能覆盖已有 Markdown，重要文件使用新路径。

上手与验收建议

先用一份有标题、表格和图片的代表性文件试转，保留原件并输出新文件。对照原文抽查数字、列顺序、脚注、图片文字和分页；若用于问答，给段落保留可追溯的文件名与位置。

来源、版本与许可

依据 ClawHub 1.0.0 页面与完整 SKILL.md 整理；平台未声明许可证。

常见问题

1. 是否需要预先安装 markitdown？

Skill 使用 uvx markitdown 临时运行，无需手工全局安装 markitdown；但机器必须有 uv/uvx，首次执行会下载并缓存依赖，因此需要网络与磁盘空间。

2. 支持哪些办公格式？

明确支持 PDF、DOCX、PPTX、XLSX 与 XLS，并可处理 HTML、CSV、JSON、XML、图片、音频、ZIP、YouTube 地址和 EPUB。各格式保真程度不同。

3. 如何保存转换结果？

可用 -o 指定新文件，也可把标准输出重定向到 Markdown。为避免覆盖，应先检查目标是否存在；批量任务给每个输出保留来源文件名。

4. 从 stdin 输入时如何识别类型？

可以用 -x 提示扩展名、-m 提示 MIME 类型、-c 指定字符集。缺少提示时二进制或无文件名输入可能识别错误，转换后必须检查。

5. 扫描 PDF 提取差怎么办？

可在确认账号、endpoint、费用和隐私边界后使用 Azure Document Intelligence 选项。该路线会把文档交给云服务处理，不适合未经授权的敏感资料。

6. 能启用第三方插件吗？

工具提供 list-plugins 与 use-plugins，但插件会执行额外代码并可能访问输入内容。只安装来源可信、用途明确的插件，默认不启用。

7. Markdown 会完全保留原版式吗？

不会。它尽量保留标题、表格、列表和链接，但复杂列布局、图表、脚注、图片文字和分页可能丢失。重要结论必须回看原文件。

8. 许可证是什么？

ClawHub 当前 1.0.0 的许可证字段为空，因此条目标记为未声明。使用或再分发前应检查 markitdown 本身及任何插件、云服务的许可。