make-to-markdown 智能转换器

要解决的具体问题

在技术文档处理中，经常需要将多种格式的文件（如 .docx、.xlsx、.pdf）转换为 Markdown 格式，以便进行版本控制、协作或分析。然而，手动转换面临诸多挑战：不同格式依赖不同的库，转换过程容易失败或产生乱码；旧格式如 .doc 可能需要额外环境；批量转换时错误处理繁琐；输出质量参差不齐，可能包含水印、页码等无关内容。make-to-markdown 旨在自动化解决这些问题，提供可靠的转换方案。

如何工作：核心能力与关键步骤

make-to-markdown 的核心是 scripts/convert.py，它集成了一整套智能转换流程：

• 依赖管理：自动检测文档格式，安装缺失的 Python 模块，如 python-docx、openpyxl，并在 120 秒超时内完成。
• 多格式转换：优先使用 markitdown 工具进行转换；如果失败，则自动降级到原生转换器，例如对于 .docx 使用 python-docx，对于 .xlsx 使用 openpyxl。
• 预处理与清洗：对于旧格式 .doc 或 .ppt，自动尝试转换为现代格式；转换后执行内联后置清洗，去除水印、页码，修复标题层级，补全表格。
• 渐进式执行：支持批量转换，采用 Init-Step-Poll 协议，避免卡死：Init 阶段确认任务，Step 阶段逐个处理，Poll 阶段汇总进度。
• 验证检查：转换完成后执行 V1-V6 检查，确保输出文件存在、非空、UTF-8 编码、无残留水印、标题层级正常、表格完整。

整个流程无需人工干预，但严格遵守安全约束，如源文件零修改和禁止外部 API 泄露。

注意点与适用边界

使用 make-to-markdown 时，需注意以下关键点：

• 核心红线：转换过程只读，所有中间产物写入临时目录；输出文件已存在时必须确认覆盖；检测到加密文档立即终止；旧格式且环境缺失时暂停提示。
• 反模式禁令：禁止直接调用 markitdown 或原生库，必须通过 convert.py；禁止在批量转换中不指定格式过滤；避免循环清洗。
• 适用场景：适用于常见的文档格式转换，尤其是需要高质量 Markdown 输出的场景；对于极端复杂或损坏的文件，可能需手动干预。
• 平台兼容：支持 Windows、Linux、macOS，路径处理使用 pathlib.Path 自动适配。