> 分级导航：L1=摘要（本段）→ L2=红线+流程+命令速查（§⛔/§1-§3）→ L3=完整运维细节（REFERENCE.md）

⛔ 核心红线 (Critical Constraints)

1. 源文件零修改：转换过程只读操作。所有中间产物写入临时目录，完成后不保留可关联回源文件的痕迹。
2. 输出覆盖确认：-o 输出文件已存在时必须暂停确认，禁止静默覆写。
3. 加密文档不重试：检测到加密（File is encrypted）立即终止，提示用户解密后重试。
4. 旧格式无预处理环境阻断：.doc/.ppt 且 COM 和 LibreOffice 均不可用时，暂停告知用户安装 Office 或 LibreOffice，禁止静默跳过。
5. 禁止绕过 convert.py：所有转换必须经由 scripts/convert.py 统一入口。禁止裸调 markitdown / uvx markitdown / 原生库。
6. 禁止外部 API 泄露：转换全程本地执行，禁止上传文档内容至任何外部 API。
7. 网络驱动器 + 执行器约束：Windows 网络驱动器（如 E:\Marvis_Data）路径优先用 python_executor，脚本内部 pathlib.Path 自动适配平台。
8. 系统破坏操作禁令 (HARB)：rm -rf / diskpart clean / DROP TABLE / git reset --hard 等破坏性命令不得自动执行，必须输出完整预览并等待用户确认。
9. 输出 UTF-8 + 批量确认 + 禁循环清洗：输出必须 UTF-8 无乱码；批量转换前确认源/目标路径+数量+格式；禁止 post_clean.py↔convert.py 循环清洗。

> 完整禁令细则及 HARB 黑名单详见 REFERENCE.md §4。

make-to-markdown 智能转换器 (v3.6)

核心入口：scripts/convert.py。零人工干预：依赖检测 → uv 安装 extras → 转换 → 降级兜底 → 后置清洗 → 输出。

🟢 最小可用示例：python scripts/convert.py input.docx。版本自查：python scripts/convert.py --version。

1. 核心执行流程

只需调用一次 scripts/convert.py，脚本内部自动完成：

(.doc/.ppt?)→预处理为 .docx/.pptx → 依赖检测 → 自动安装 → markitdown → (失败)原生降级 → 后置清洗 → 输出

| 步骤 | 说明 |

|------|------|

| 预处理 | .doc/.ppt 自动转为 .docx/.pptx（见 §2.5） |

| 依赖 | 按扩展名自动检测+安装缺失 Python 模块，120s 超时 |

| markitdown extras | 自动补全可选依赖，pypdf 已就绪则跳过 |

| markitdown 转换 | CLI 调用 |

| 降级兜底 | 失败时自动切换 python-docx/openpyxl/python-pptx |

| 后置清洗 | 内联执行：去水印+页码+标题修复+表格补全+摘要注入 |

| 结果反馈 | 输出路径 + H 标题统计 + 表格计数 + 转换方式 |

1.1 Init-Step-Poll 渐进式防卡死协议

单个小文件可直接调用 scripts/convert.py。批量转换、大文件、网络驱动器文件、旧格式 .doc/.ppt、含 OCR/音频/ZIP 的慢转换任务，必须采用 Init → Step → Poll 渐进式执行，避免长时间转换卡死或失败文件被静默吞掉。

执行约束：

• Init 阶段必须显示待转换数量和限定格式；禁止未确认就递归整个目录。
• Step 阶段不得覆盖已有输出，除非用户已在 Init 阶段明确授权。
• Poll 阶段完成度只能按“已通过 V1-V6 的输出文件数 / 待转换文件数”计算。
• 批量任务必须保留 _conversion_errors.log 或等价失败清单，最终回复需列出失败文件和下一步处理建议。
• 网络驱动器或路径含空格时优先使用 Python/pathlib 路径处理，不依赖 PowerShell 字符串拼接。

2. 依赖速查

convert.py 自动处理依赖。以下为手动参考，完整映射表见 REFERENCE.md §1。

| 格式 | 额外包 |

|------|--------|

| .docx/.doc | python-docx |

| .xlsx | openpyxl |

| .xls | xlrd |

| .pptx/.ppt | python-pptx |

| .pdf | pypdf |

| .epub | ebooklib |

无需额外依赖的格式：.html .csv .json .xml .png .jpg .jpeg .gif .bmp .tiff .webp .mp3 .wav .m4a .ogg .flac .zip

# 一次性安装全部可选依赖（脚本自动处理）
uv tool install markitdown --with python-docx --with openpyxl --with python-pptx --with pypdf --with xlrd --with ebooklib

2.5 旧格式预处理

.doc/.ppt 不被 markitdown 直接支持，convert.py 自动尝试两种方式：

| | .doc→.docx | .ppt→.pptx |

|---|---|---|

| 方式1 | Word COM (Windows only) | PowerPoint COM (Windows only) |

| 方式2 | soffice --headless --convert-to docx | soffice --headless --convert-to pptx |

LibreOffice 定位链：shutil.which("soffice") → $SOFFICE_PATH → 常见安装路径 → 裸名兜底。详见 REFERENCE.md §3。

> 🔴 CHECKPOINT：旧格式且 COM 和 LibreOffice 均不可用时，暂停并告知用户安装 Office 或 LibreOffice。.xls 无需预处理。

3. 命令速查

# 单文件（推荐）
python scripts/convert.py input.docx -o output.md

# 默认输出名 / 跳过摘要 / 静默
python scripts/convert.py input.pdf
python scripts/convert.py data.xlsx --no-summary
python scripts/convert.py report.pptx -q

# 批量转换（确认源/目标/数量/格式后执行）
python scripts/batch_convert.py <源目录> <输出目录> --ext .pdf .docx --clean

# 单独后置清洗（仅极端场景）
python scripts/post_clean.py output.md --check-only

> 🔴 CHECKPOINT：-o 输出已存在时暂停确认；批量转换前必须确认路径+数量+格式。

3.2 降级转换器

markitdown 失败时自动启用原生降级（输出同样经过后置清洗）：

| 格式 | 降级方案 | 能力 |

|------|---------|------|

| .docx/.doc | python-docx | 段落样式→标题、表格→MD 表格 |

| .xlsx/.xls | openpyxl | Sheet→H2 章节、数据行→MD 表格 |

| .pptx | python-pptx | 幻灯片→H2 章节、表格自动转换 |

4. 后置清洗

convert.py 内联清洗管线（6 类 15+ 正则）：去水印/页码/机密标记/版权声明 + 空白压缩 + 标题层级修复 + 表格分隔符补全 + 文档摘要注入。完整清洗项及正则模式详见 REFERENCE.md §1。

5. 异常处理

| 错误类型 | 处理方式 |

|:---|:---|

| 依赖安装失败 | 终止，输出缺失包名，提示手动安装 |

| markitdown 失败 | 自动降级到原生转换器 |

| 加密文档 | 🔴 立即终止，提示解密后重试 |

| 旧格式无预处理环境 | 🔴 CHECKPOINT：暂停，告知安装 Office/LibreOffice |

| 批量单文件失败 | 跳过，记入 _conversion_errors.log，其余继续 |

| 输出路径不可写 | 终止，提示检查权限/磁盘空间 |

> 完整异常分类表（含 uv 不在 PATH、网络驱动器不可达等）见 REFERENCE.md §10。

6. 输出反馈模板

{状态}将 `{源文件名}` 转换为 Markdown [{转换方式}] | H1={n} H2={n} H3={n} | 表格={n} | {文件大小}
输出: {绝对路径}

| 字段 | 取值 |

|:---|:---|

| 状态 | 成功 / 失败 / 部分成功 |

| 转换方式 | markitdown / 原生降级(python-docx) / 原生降级(openpyxl) / 原生降级(python-pptx) |

批量：批量转换完成 | 总计=N | 成功=N | 失败=N，详情见 _conversion_errors.log。

7. 脚本清单

| 脚本 | 用途 |

|------|------|

| scripts/convert.py | 智能转换引擎（依赖补全 + markitdown + 降级 + 内联清洗） |

| scripts/batch_convert.py | 批量递归转换，保持目录结构 |

| scripts/post_clean.py | 单独后置清洗（极端场景备用） |

| scripts/platform_detect.py | 平台检测模块，best_office_tool() 路由 |

前置校验：python -c "from pathlib import Path; assert Path('scripts/convert.py').exists()"

8. 平台兼容性

Windows / Linux / macOS 全支持。convert.py 启动时自动检测平台能力，脚本使用 pathlib.Path 适配路径。详见 REFERENCE.md §3。

9. 反模式禁令

1. 裸调 markitdown → 必须 python scripts/convert.py
2. shell_executor 执行网络驱动器脚本 → 用 python_executor
3. 加密文档反复重试 → 首次失败即终止
4. 旧格式无预处理时强行转换 → 告知用户安装 Office/LibreOffice
5. 批量转换不设 --ext → 必须指定格式过滤
6. 重复清洗 convert.py 输出 → 禁止循环清洗

详细禁令清单见 REFERENCE.md §4。

10. 验证检查表

转换完成后必须执行逐项检查，任一未通过即进入 §5 异常处理。

| # | 检查项 | 验证命令（替换 <输出.md>） |

|:---|:---|:---|

| V1 | 文件存在且非空 | python -c "import os; assert os.stat('<输出.md>').st_size>0" |

| V2 | UTF-8 无乱码 | python -c "open('<输出.md>',encoding='utf-8').read()" |

| V3 | 无残留水印 | python -c "import re; t=open('<输出.md>').read(); assert not re.search(r'Generated by\|Page \\d+',t)" |

| V4 | 标题层级正常 | H1 存在 + 无跳跃（H1→H3 无 H2） |

| V5 | 表格分隔符完整 | 无 \|---\| 缺失 |

| V6 | 批量文件数对应 | 输出目录文件数 = 源文件数 |

Agent 完成后在最终回复中确认：V1 存在非空 / V2+V3 抽检前 3 段无乱码水印 / V4 无跳跃 / V5 表格完整 / V6（批量时）数量一致。

> 详细验证 oneliner、回归测试用例（RT1-RT3）见 REFERENCE.md §5。自检清单见 REFERENCE.md §2。