make-to-markdown
📖 技能介紹
name: make-to-markdown description: 工業級RAG Markdown物料生成技能，使用 markitdown 將各類文件和檔案轉換為 Markdown 格式。支援 .doc/.ppt 老格式自動預處理（Word/PowerPoint COM / LibreOffice）。啟動時自動檢測 OS/版本/能力，按平臺選擇最佳執行路徑。觸發詞：轉 Markdown / 轉換文件 / markitdown / 文件轉 md / 批次轉換。當需要將 PDF、Word (.docx/.doc)、PowerPoint (.pptx/.ppt)、Excel (.xlsx, .xls)、HTML、CSV、JSON、XML、圖片（含 EXIF/OCR）、音訊（含語音轉寫）、ZIP 壓縮包、YouTube 連結或 EPub 電子書轉換為 Markdown 格式，為知識庫提供統一的"通用語言"時觸發此技能。 version: "1.0.11" metadata: domain: "make-to-markdown" author: "智慧半島" platform: windows: full linux: full macos: full openclaw: requires: bins: - uv - python emoji: "📚"
分級導航：L1=摘要（本段）→ L2=紅線+流程+命令速查（§⛔/§1-§3）→ L3=完整運維細節（REFERENCE.md）
發現更多技能外掛，請訪問7w4.net。
⛔ 核心紅線 (Critical Constraints)
- 原始檔零修改：轉換過程只讀操作。所有中間產物寫入臨時目錄，完成後不保留可關聯回原始檔的痕跡。
- 輸出覆蓋確認：
-o輸出檔案已存在時必須暫停確認，禁止靜默覆寫。 - 加密文件不重試：檢測到加密（
File is encrypted）立即終止，提示使用者解密後重試。 - 舊格式無預處理環境阻斷：
.doc/.ppt且 COM 和 LibreOffice 均不可用時，暫停告知使用者安裝 Office 或 LibreOffice，禁止靜默跳過。 - 禁止繞過 convert.py：所有轉換必須經由
scripts/convert.py統一入口。禁止裸調markitdown/uvx markitdown/ 原生庫。 - 禁止外部 API 洩露：轉換全程本地執行，禁止上傳文件內容至任何外部 API。
- 網路驅動器 + 執行器約束：Windows 網路驅動器（如
E:\Marvis_Data）路徑優先用python_executor，指令碼內部pathlib.Path自動適配平臺。 - 系統破壞操作禁令 (HARB)：
rm -rf/diskpart clean/DROP TABLE/git reset --hard等破壞性命令不得自動執行，必須輸出完整預覽並等待使用者確認。 - 輸出 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 | 確認源路徑、輸出路徑、格式過濾、檔案數量、覆蓋策略和平臺能力 | task_id、待轉換清單、輸出目錄、進度 0/N |
路徑不可達、輸出覆蓋未授權、舊格式環境缺失時暫停 |
| Step | 每次只轉換 1 個檔案或 1 個小批次，執行 convert.py/batch_convert.py 並立即做 V1-V6 檢查 |
成功檔案、失敗檔案、輸出路徑、質量檢查結果 | 單檔案失敗寫入失敗清單，不影響其他檔案；加密檔案不重試 |
| Poll | 彙總成功/失敗/待處理數量、最近失敗原因和可續跑命令 | running/success/failed/paused、進度百分比、失敗清單、待確認項 |
中斷後從失敗清單和未處理清單續跑，不重複轉換已驗證輸出 |
執行約束：
- 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 |
| 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. 反模式禁令
- 裸調 markitdown → 必須
python scripts/convert.py - shell_executor 執行網路驅動器指令碼 → 用
python_executor - 加密文件反覆重試 → 首次失敗即終止
- 舊格式無預處理時強行轉換 → 告知使用者安裝 Office/LibreOffice
- 批次轉換不設
--ext→ 必須指定格式過濾 - 重複清洗 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。
🤖 AI 評測
這個 Skill 質量不錯，文件寫得很詳細，轉換支援的檔案格式很全面（PDF、Word、Excel 等 20 多種），還帶自動依賴安裝和清洗功能。Windows、Mac、Linux 都能用，批次轉換也很方便。不足的是複雜文件的轉換效果可能不穩定，缺少測試保障，大檔案處理沒有特別最佳化。總體適合一般文件轉換場景，對轉換質量要求很高的話可能需要額外檢查結果。
