\r \r

文档结构：SKILL.md = 核心运行时指令（Agent 执行必读），REFERENCE.md = 扩展参考与运维细节。非核心内容不得写入本文件。\r \r

⛔ 核心红线 (Critical Constraints)\r

1. 源文件零修改原则：转换过程对源文件实行只读操作。严禁以任何理由修改、删除、移动或重命名用户提供的原始文档。所有中间产物写入系统临时目录或技能工作区，转换完成后不保留任何可关联回源文件的痕迹。\r
2. 输出覆盖二次确认：-o 指定的输出文件若已存在，convert.py 启动前必须暂停并告知用户路径及已有内容来源，获得明确授权后方可覆盖。禁止自动跳过或静默覆写。\r
3. 加密文档不重试：检测到文档加密（File is encrypted / 密码保护提示）时，首次失败即终止该文件转换，提示用户解密后重试。禁止反复尝试、猜测密码或绕过保护。\r
4. 旧格式无预处理环境时阻断：.doc / .ppt 旧格式且在 COM 和 LibreOffice 均不可用的环境下，必须暂停并告知用户安装 Office 或 LibreOffice。禁止静默跳过该文件或输出空结果。\r
5. 禁止绕过 convert.py 裸调 CLI：不得直接调用 markitdown / uvx markitdown / 原生库进行转换。所有转换必须经由 scripts/convert.py 统一入口，以确保依赖补全、降级兜底和后置清洗管线完整执行。\r
6. 禁止外部 API 泄露文档内容：转换过程全程本地执行，禁止将文档内容上传至任何外部 API（包括 OpenAI、Ollama 远程、云端 OCR 等）。仅允许本地安装的 markitdown / python-docx / openpyxl / python-pptx 等库。\r
7. 网络驱动器路径约束（平台自适应）：涉及网络驱动器（如 X: 盘、E:\Marvis_Data 等）上的文件读写操作时：\r
   • Windows 网络驱动器：优先使用 python_executor，避免 shell_executor（PowerShell/cmd 可能因 WinError 2 找不到网络驱动器路径）\r
   • Linux/macOS NFS/CIFS 挂载：shell_executor 通常可用，但路径中含空格或特殊字符时回退到 python_executor\r
   • 自动检测：脚本内部使用 pathlib.Path 处理路径，无需硬编码平台判断\r
8. 系统破坏操作禁令 (HARB)：以下高风险行动黑名单中的命令，Agent 在任何阶段均不得自动执行，必须输出完整命令预览并等待用户显式确认：\r
   • 文件系统破坏：rm -rf / del /f /s / Remove-Item -Recurse -Force 等递归强制删除 | 格式化（format / mkfs） | 对工作目录外任意路径的批量写操作\r
   • 数据不可逆丢失：git reset --hard / git clean -fdx | 数据库 DROP TABLE / TRUNCATE / DROP DATABASE | 清空回收站 | shred / wipe 等安全擦除\r
   • 系统级破坏：diskpart clean | 注册表 reg delete 批量删除 | sc delete 删除系统服务 | bcdedit 修改引导配置\r
   • 批量不可逆操作：对 >50 个文件或目录的单次删除/覆盖 | 对 >10 个 Git 仓库的单次 push --force / reset --hard\r 违反本禁令的脚本或流水线必须被拒绝执行并告知用户原因\r
9. 输出编码完整性：所有输出文件必须为 UTF-8 编码。convert.py 写盘后须验证文件可被 UTF-8 解码且无乱码（检查项 V2）。非 UTF-8 源文件需先检测编码再转码，禁止直接写入可能导致乱码的编码。\r
10. 批量操作确认前置：批量转换前必须确认源目录路径、目标输出路径、待转换文件数量（预估）、限定格式。禁止不经确认即递归遍历整个目录。\r
11. 禁止循环清洗：post_clean.py 的输出不得再次作为 convert.py 的输入；convert.py 的输出不得再次调 post_clean.py。二次清洗会导致摘要叠加、噪声模式重复匹配、标题层级二次修复误触发。\r \r \r

make-to-markdown Markdown物料智能转换器 (v3.6)\r

\r 核心入口：scripts/convert.py。依赖检测 → uv tool install markitdown --with=... 安装完整 extras → 转换 → 失败降级 → 后置清洗。零人工干预。\r \r

🟢 最小可用示例：python scripts/convert.py input.docx。全选项见 §3，异常处理见 §5。\r \r

1. 核心执行流程\r

\r 当用户要求转换文件时，只需调用一次 scripts/convert.py，脚本内部自动完成以下全部步骤：\r \r

(.doc/.ppt?)→预处理为 .docx/.pptx → 依赖检测 → 自动安装 → markitdown extras → markitdown 转换 → (失败则) 原生降级 → 后置清洗 → 输出\r
```\r
\r
1. **.doc/.ppt 预处理**（v2.3+）：自动将老格式转为 `.docx`/`.pptx`，详见 [§2.5 旧格式预处理](#25-旧格式预处理v2-3)。\r
2. **依赖检测**：根据文件扩展名自动检查所需 Python 模块是否已安装。\r
3. **自动安装**：缺失模块自动 `pip install` 安装，120 秒超时。\r
3.5. **markitdown extras**（v2.4）：自动检测 pip 和 uv 两侧的 markitdown 可选依赖完整性；缺失时自动安装，避免 `MissingDependencyException`。pypdf 已就绪则跳过全部安装。\r
4. **markitdown 转换**：调用 markitdown CLI 转换文件。\r
5. **降级兜底**：markitdown 失败时，使用 python-docx / openpyxl / python-pptx 等原生库转换。\r
6. **后置清洗**：去水印 / 页码 / 空白压缩 + 标题层级修复（多 H1 降级、越级补过渡） + 表格分隔符补全 + 注入文档摘要（内联执行，无需单独调用 post_clean.py）。\r
7. **结果反馈**：输出路径 + H1/H2/H3 标题统计 + 表格计数 + 转换方式（markitdown / 原生降级）。\r
\r
## 2. 依赖映射\r
\r
markitdown 对非纯文本格式采用可选依赖策略：`pip install markitdown` 仅装核心，以下格式需额外包。`convert.py` 会在转换前**自动检测并安装**缺失依赖。\r
\r
| 扩展名 | pip 包 | import 模块 | markitdown extra 名 |\r
|--------|--------|-------------|---------------------|\r
| .docx | python-docx | docx | docx |\r
| .doc | python-docx | docx | docx |\r
| .xlsx | openpyxl | openpyxl | xlsx |\r
| .xls | xlrd | xlrd | xls |\r
| .pptx | python-pptx | pptx | pptx |\r
| .ppt | python-pptx | pptx | pptx |\r
| .pdf | pypdf | pypdf | pdf |\r
| .epub | ebooklib | ebooklib | epub |\r
\r
以下格式无需额外依赖，标记为完整安装时可省略 `--with`：\r
`.html` `.htm` `.csv` `.json` `.xml` `.png` `.jpg` `.jpeg` `.gif` `.bmp` `.tiff` `.webp` `.mp3` `.wav` `.m4a` `.ogg` `.flac` `.zip`\r
\r
**uv 环境等效命令**（手动安装参考，脚本自动处理）：\r
```bash\r
# 安装 markitdown 及全部可选依赖（一次性）\r
uv tool install markitdown --with python-docx --with openpyxl --with python-pptx --with pypdf --with xlrd --with ebooklib\r
\r
# 或仅安装当前文件所需依赖\r
uvx --with python-docx markitdown input.docx -o output.md\r
```\r
\r
## 2.5 旧格式预处理（v2.3+）\r
\r
`.doc` 和 `.ppt`（Office 97-2003 二进制格式）不被 markitdown 直接支持。`convert.py` 在转换前自动尝试两种方式转为新版格式，其中 LibreOffice 按四级优先级链定位 `soffice` 可执行文件：\r
\r
| 旧格式 | 目标格式 | 方式 1 | 方式 2 |\r
|--------|---------|--------|--------|\r
| `.doc` | `.docx` | Word COM (仅 Windows, `Documents.Open` → `SaveAs2`) | `soffice --headless --convert-to docx` |\r
| `.ppt` | `.pptx` | PowerPoint COM (仅 Windows, `Presentations.Open` → `SaveAs`) | `soffice --headless --convert-to pptx` |\r
\r
**LibreOffice 定位优先级链（v2.8）**：\r
1. `shutil.which("soffice")` — PATH 中的 soffice\r
2. `$SOFFICE_PATH` 环境变量\r
3. 按平台分叉的常见安装路径（`os.path.exists` 校验）\r
4. 裸名 `"soffice"` 兜底\r
\r
> 🔴 **CHECKPOINT**：若 .doc/.ppt 旧格式且 COM 和 LibreOffice 均不可用，**必须立即暂停**，明确告知用户需安装 Microsoft Office（含 Word/PowerPoint）或 LibreOffice，等待用户确认后再继续。禁止静默跳过旧格式文件。\r
\r
`.xls` 则由 markitdown 原生支持（`[xls]` 可选依赖组，底层 `xlrd`），无需预处理。\r
\r
## 3. 命令参考\r
\r
### 3.1 智能转换（推荐）\r
\r
```bash\r
# 单文件转换（自动检测依赖 + 清洗）\r
python scripts/convert.py input.docx -o output.md\r
\r
# 使用默认输出名（同目录下 input.md）\r
python scripts/convert.py input.pdf\r
\r
# 跳过文档摘要\r
python scripts/convert.py data.xlsx --no-summary\r
\r
# 静默模式\r
python scripts/convert.py report.pptx -q\r
```\r
\r
> 🔴 **CHECKPOINT**：若 `-o` 指定的输出文件已存在，convert.py 会直接覆盖。覆盖前**必须**暂停并告知用户输出路径已存在已有内容（如上次转换结果、手动修正后的版本），等待用户确认是否覆盖。若用户拒绝，改用 `-o \x3C新文件名>` 或先备份。\r
\r
### 3.2 降级转换器\r
\r
当 markitdown 无法处理（依赖缺失且自动安装失败、超时、加密文档等），`convert.py` 自动启用原生降级：\r
\r
| 格式 | 降级方案 | 能力 |\r
|------|---------|------|\r
| .docx / .doc | python-docx | 提取段落样式→标题层级、表格→Markdown 表格、粗体短文本→内嵌标题 |\r
| .xlsx / .xls | openpyxl | 每个 Sheet → H2 章节，数据行→ Markdown 表格 |\r
| .pptx | python-pptx | 每页幻灯片→ H2 章节，文本层级保留，表格自动转换 |\r
\r
降级转换器的输出同样经过后置清洗流程，质量标准与 markitdown 一致。\r
\r
### 3.3 批量转换\r
\r
> 🔴 **CHECKPOINT**：批量转换前**必须**向用户确认：源目录路径、目标输出路径、待转换文件数量（预估）、限定格式（如有 `--ext`）。等待用户确认后再启动。禁止不经确认即递归遍历整个目录。\r
\r
```bash\r
# 递归转换整个目录\r
python scripts/batch_convert.py \x3C源目录> \x3C输出目录>\r
\r
# 仅转换指定格式\r
python scripts/batch_convert.py docs/ output/ --ext .pdf .docx --clean\r
```\r
\r
### 3.4 单独后置清洗\r
\r
```bash\r
# 清洗单个文件\r
python scripts/post_clean.py output.md\r
\r
# 注入摘要后输出到新文件\r
python scripts/post_clean.py output.md --summary-file summary.txt -o cleaned.md\r
\r
# 仅检查结构不修改\r
python scripts/post_clean.py output.md --check-only\r
```\r
\r
## 4. 后置清洗与 RAG 优化\r
\r
`convert.py` 内联了后置清洗逻辑，无需单独调用 `post_clean.py`。清洗流程：\r
\r
**噪声模式去除**（6 类 15+ 正则）：\r
\r
| 类别 | 匹配模式 |\r
|:---|:---|\r
| 工具水印 | `[Generated by ...]` / `Converted by markitdown` / `[Created with ...]` / `Powered by ... markitdown` |\r
| 页码标记 | `Page X of Y` / `[PAGE X]` / `--- Page X ---` |\r
| 机密标记 | `Confidential` / `DRAFT` / `Internal Use Only` / `For Review Only` |\r
| 版权声明 | `© YYYY` / `All Rights Reserved` |\r
| 空白压缩 | 连续 3+ 空行 → 2 行 |\r
| 行尾空格 | 移除空行末无用空格 |\r
\r
**标题层级修复**：\r
- 多 H1 → 仅保留首个，其余降为 H2\r
- 层级跳跃（如 H1→H3 无 H2）→ 补过渡标题\r
- 无 H1 → 从文件名推断后注入\r
\r
**表格分隔符补全**：检测 `|---|` 缺失行并补全。\r
\r
**文档摘要注入**：提取首段或首个 H1 后段落作为摘要。\r
\r
完整清洗项及正则模式详见 [REFERENCE.md §1](REFERENCE.md)。\r
\r
## 5. 异常处理\r
\r
### 5.1 错误分类与处理\r
\r
| 错误类型 | 典型症状 | 原因 | 处理方式 |\r
|:---|:---|:---|:---|\r
| 依赖安装失败 | `pip install` 超时或报错，转换终止 | Python 包索引不可达 / 权限不足 / 包版本冲突 | 终止转换，输出具体缺失的包名，提示用户手动 `pip install \x3Cpkg>` |\r
| markitdown 失败 | markitdown CLI 返回非零退出码 | 文件格式损坏 / markitdown extras 缺失 / 未知格式 | 自动切换到原生降级转换器（python-docx/openpyxl/python-pptx），降级后仍经后置清洗 |\r
| 原生降级也失败 | 降级转换器报错或输出空内容 | 加密文档 / 文档严重损坏 / 格式不兼容 | 终止转换，输出"文档可能已加密或格式不受支持" |\r
| 加密文档 | markitdown + 原生库均提示 `File is encrypted` 或类似信息 | 文档受密码保护 | 终止转换，提示"文档已加密，请解密后重试"。**禁止反复重试** |\r
| 旧格式无预处理环境 | .doc/.ppt 文件但 COM 和 LibreOffice 均不可用 | Windows 未装 Office `pywin32`；Linux/macOS 未装 LibreOffice | 🔴 CHECKPOINT：暂停，告知用户安装 Office 或 LibreOffice |\r
| 批量场景单文件失败 | 个别文件转换报错，其余正常 | 该文件格式异常 / 权限不足 / 正在被其他程序占用 | 跳过该文件，在 `_conversion_errors.log` 记录文件名+错误原因，其余文件继续 |\r
| 输出路径不可写 | convert.py 写文件时报 PermissionError | 目标目录不存在且无创建权限 / 磁盘满 | 终止，提示检查输出路径权限和磁盘空间 |\r
| uv 不在 PATH | `ensure_markitdown_extras()` 检测不到 uv | uv 未安装或未加入 PATH | 跳过 markitdown extras 安装，转换仍可进行（仅限内置支持格式） |\r
| 网络驱动器不可达 | `[WinError 2]` 或 `FileNotFoundError` | 网络驱动器断连（E:\Marvis_Data 等） | 提示用户检查网络驱动器连接状态 |\r
\r
> 🔴 **CHECKPOINT**（参见 §2.5 预处理流程）：以下两类情况必须立即暂停，等待用户介入，禁止自动跳过或反复重试：\r
> - **加密文档**（`File is encrypted`）：首次检测到即终止该文件转换，提示用户解密后重试\r
> - **旧格式无预处理环境**（.doc/.ppt 且 COM 和 LibreOffice 均不可用）：告知用户安装 Office 或 LibreOffice\r
\r
### 5.2 静默失败防护\r
\r
| 静默失败形态 | 检测机制 |\r
|:---|:---|\r
| 清洗跳过某些噪声模式 | §4 噪声模式库覆盖 15+ 正则 |\r
| 降级转换器输出格式不一致 | 降级输出同样经过后置清洗 |\r
| 批量转换某文件失败未记录 | `_conversion_errors.log` 自动汇总 |\r
| 标题层级修复误触发（二次修复） | v2.6+ 标题修复仅执行一次，有状态标记 |\r
| markitdown extras 缺失但转换仍"成功" | `convert.py` 启动时检测全部可选依赖 |\r
\r
详见 [REFERENCE.md §7](REFERENCE.md)。\r
\r
## 6. 输出与反馈规范\r
\r
转换成功后反馈示例：\r
\r
> 成功将 `report.pdf` 转换为 Markdown [markitdown] | H1=1 H2=5 H3=12 | 表格=3 | 48,256 bytes\r
> 输出: E:\output\report.md\r
\r
**反馈格式固定模板**（所有转换结果必须统一使用）：\r
\r
```\r
{状态}将 `{源文件名}` 转换为 Markdown [{转换方式}] | H1={n} H2={n} H3={n} | 表格={n} | {文件大小}\r
输出: {绝对路径}\r
```\r
\r
| 字段 | 说明 | 取值 |\r
|:---|:---|:---|\r
| 状态 | 转换结果 | `成功` / `失败` / `部分成功`（批量场景） |\r
| 转换方式 | 所用引擎 | `markitdown` / `原生降级(python-docx)` / `原生降级(openpyxl)` / `原生降级(python-pptx)` |\r
| H1/H2/H3 | 标题层级统计 | 整数，无标题时写 0 |\r
| 表格 | Markdown 表格数量 | 整数 |\r
\r
**批量转换反馈**：\r
```\r
批量转换完成 | 总计=12 | 成功=10 | 失败=2\r
失败详情: _conversion_errors.log\r
输出: E:\output\markdown\\r
```\r
\r
> 输出质量自检清单（7 项）已移至 [REFERENCE.md §2](REFERENCE.md)。\r
\r
## 7. 脚本清单\r
\r
**前置校验**：执行转换前，Agent 应通过 `python -c "from pathlib import Path; import sys; sys.path.insert(0,'scripts'); assert Path('scripts/convert.py').exists(), 'convert.py missing'"` 确认核心脚本存在。\r
\r
| 脚本 | 用途 |\r
|------|------|\r
| `scripts/convert.py` | 智能转换引擎（推荐）：依赖自动补全 + markitdown + 降级兜底 + 内联清洗 |\r
| `scripts/batch_convert.py` | 批量转换：递归遍历目录、保持结构、异常收集 |\r
| `scripts/post_clean.py` | 后置清洗：去水印、注入摘要（含标题修复、面包屑注入、质量评分） |\r
| `scripts/platform_detect.py` | 平台检测模块（v2.8）：启动时检测 OS/版本/能力，`best_office_tool()` 返回最优办公软件路由 |\r
\r
## 8. 平台兼容性与更新记录 (Platform & Changelog)\r
\r
Windows / Linux / macOS 三平台完全支持。关键约束：`convert.py` 启动时自动检测平台能力；网络驱动器路径使用 `python_executor` 执行；全部脚本使用 `pathlib.Path` 适配路径分隔符。详见 [REFERENCE.md §3](REFERENCE.md)。更新记录见 [REFERENCE.md §6](REFERENCE.md)。\r
\r
## 9. 反模式与禁止清单 (Anti-Patterns & Blacklist)\r
\r
**核心禁令**（完整版见 [REFERENCE.md §4](REFERENCE.md)）：\r
\r
1. **绕过 convert.py 直接裸调 markitdown** → 跳过依赖补全+清洗管线，输出含残留水印。必须使用 `python scripts/convert.py`\r
2. **用 shell_executor 执行网络驱动器脚本** → PowerShell WinError 2。使用 `python_executor`\r
3. **对加密文档反复重试** → 首次失败即终止，提示解密后重试\r
4. **.doc/.ppt 无预处理环境时强行转换** → 告知用户安装 Office 或 LibreOffice\r
5. **批量转换不设 --ext 过滤** → 产出 .jpg.md/.zip.md。必须 `--ext .pdf .docx .pptx`\r
6. **重复清洗已清洗过的输出** → 摘要叠加。不要对 convert.py 输出再调 post_clean.py\r
\r
**禁止操作**：`post_clean.py` 输出→ `convert.py` 输入（循环清洗）；`.xls` 用 COM 预处理；空 `--ext` 参数；二次 convert 已成功输出。\r
\r
## 10. 可验证性检查表 (Verification Checklist)\r
\r
### 10.1 验收标准\r
\r
每次转换完成后，Agent 必须对输出文件执行以下逐项检查。任一未通过 = 转换失败，需进入 §5 异常处理流程。\r
\r
| # | 检查项 | 通过标准 | 验证命令 |\r
|:---|:---|:---|:---|\r
| V1 | 文件存在且非空 | 输出文件大小 > 0 字节 | `python -c "import os; s=os.stat('\x3C输出.md>'); assert s.st_size>0, '空文件'"` |\r
| V2 | 编码正确 | 文件可被 UTF-8 解码且无乱码 | `python -c "open('\x3C输出.md>',encoding='utf-8').read()"` |\r
| V3 | 无残留水印 | 不含 `Generated by markitdown` / `Confidential` / `Page X of Y` | `python -c "import re; t=open('\x3C输出.md>').read(); assert not re.search(r'Generated by|Page \d+ of \d+',t), '有水印'"` |\r
| V4 | 标题层级正常 | 至少存在 1 个 H1，且 H 层级无跳跃（H1→H3 无 H2 报错） | `python -c "import re; t=open('\x3C输出.md>',encoding='utf-8').read(); hs=re.findall(r'^(#{1,6})\s',t,re.M); levels=[len(h) for h in hs]; jumps=[i for i in range(1,len(levels)) if levels[i]-levels[i-1]>1]; assert len(hs)>0 and levels[0]==1, f'无H1' if not hs else f'H{levels[0]}打头'; assert not jumps, f'层级跳跃: {jumps}'; print('PASS')"` |\r
| V5 | 表格完整性 | 无 `|---|` 分隔符缺失、无空表格、无 `||` 异常分隔符 | `python -c "import re; t=open('\x3C输出.md>').read(); pipes=[l for l in t.split(chr(10)) if l.startswith('|')]; assert len(pipes)>0 or '无表格', '表格可能损坏'"` |\r
| V6 | 源文件对应 | 每 1 个源文件产生 1 个输出文件（批量模式无漏转） | `python -c "print(len(os.listdir('\x3C输出目录>')))"` 对比源文件数 |\r
\r
### 11.2 自检清单 (Agent 执行后必查)\r
\r
Agent 在完成转换并写盘后，必须在最终回复中逐项确认以下内容（直接输出结果，不展开过程）：\r
\r
- [ ] 输出文件路径已确认存在且非空（V1）\r
- [ ] 输出内容已抽检前 3 段，无乱码/水印/页码残留（V2+V3）\r
- [ ] 标题层级已检查，无跳跃（V4）\r
- [ ] 表格（如有）分隔符完整（V5）\r
- [ ] 批量转换时：源文件数与输出文件数一致（V6）\r
\r
### 11.3 回归测试与快速验证\r
\r
回归测试用例（RT1-RT3）和 Python 一键验证 oneliner 已移至 [REFERENCE.md §5](REFERENCE.md)。\r