前言¶

做知識庫或 RAG 流水線時，常見卡點不是檢索模型，而是入庫前的「物料形態」：PDF、Office、表格、掃描件、壓縮包混在一起，各寫一套解析腳本，維護成本高，輸出結構也不統一。若希望 Agent 在對話裏按固定流程完成「檢測環境 → 轉換 → 清洗 → 校驗」，並把結果寫成 UTF-8 Markdown，可以接入 SkillHub 上的 make-to-markdown（包名 @indiv-ebandao/make-to-markdown，當前版本 v1.0.11）。下面介紹它的定位、能力與安裝用法。

這是什麼¶

make-to-markdown 是面向 RAG 場景的 Markdown 物料生成 Skill：底層使用 markitdown，通過技能自帶的 scripts/convert.py 作爲統一入口，完成依賴檢測、格式轉換、失敗降級與後置清洗。Skill 元數據標註維護方爲「智慧半島」，在 SkillHub 分類爲 knowledge-management（知識管理）；頁面展示評分約 98663、下載約 484 次（數據來自 SkillHub 列表信息，以頁面實時爲準）。

與在對話裏臨時執行 uvx markitdown 相比，該 Skill 強調：舊版 .doc/.ppt 預處理、按操作系統選擇 Office COM 或 LibreOffice、批量任務的 Init-Step-Poll 防卡死協議，以及轉換後的 V1–V6 質量檢查。

官方入口：

• SkillHub 頁面：https://www.skillhub.cn/skills/indiv-ebandao/make-to-markdown
• API 標識頁：https://api.skillhub.cn/user_741dc82b/make-to-markdown

核心功能¶

以下能力均來自 Skill 包內 SKILL.md / QUICKSTART.md 與 SkillHub 簡介，安裝後由 Agent 按 Skill 指令執行。

支持的輸入格式¶

可將下列類型轉爲 Markdown（含擴展能力說明）：

舊格式與跨平臺¶

• .doc / .ppt 會先預處理爲 .docx / .pptx：Windows 上優先 Word / PowerPoint COM，否則嘗試 soffice --headless（LibreOffice）。
• 啓動時通過 scripts/platform_detect.py 檢測 OS 與本地能力，再選擇執行路徑；Skill 聲明 Windows / Linux / macOS 均爲 full 支持。

轉換管線¶

單次調用 scripts/convert.py 時，內部流程概括爲：

(.doc/.ppt) → 預處理 → 依賴檢測與安裝 → markitdown →（失敗）原生降級 → 後置清洗 → 輸出

• markitdown 失敗時降級：例如 .docx 用 python-docx、表格用 openpyxl、演示文稿用 python-pptx。
• 後置清洗（內聯在 convert 中）：去水印/頁碼、標題層級修復、表格分隔符補全、可選文檔摘要等；極端場景可單獨調用 scripts/post_clean.py。

Agent 觸發方式¶

在支持 Skills 的客戶端中，可用自然語言觸發，Skill 描述的觸發詞包括：轉 Markdown、轉換文檔、markitdown、文檔轉 md、批量轉換。當需要把上述多類文件統一成知識庫「通用語言」Markdown 時使用。

約束（使用前應知曉）¶

Skill 將下列規則標爲紅線，Agent 應遵守：

1. 源文件只讀，不修改原件；轉換經 scripts/convert.py，不裸調 markitdown / uvx markitdown。
2. -o 目標文件已存在時需用戶確認，禁止靜默覆蓋。
3. 加密文檔檢測到後終止，需用戶先解密。
4. 舊格式且 COM、LibreOffice 均不可用時暫停，提示安裝 Office 或 LibreOffice。
5. 轉換全程本地執行，不上傳文檔到外部 API。

OpenClaw 類環境元數據要求本機具備 uv 與 python。

安裝與啓用¶

SkillHub 推薦讓 Agent 按安裝說明文檔操作，或在本機用 CLI 安裝到當前 Agent 的 skills 目錄。

方式一：按 SkillHub 官方安裝說明（推薦給 Agent）¶

在對話中發送 SkillHub 頁面提供的提示，或明確要求 Agent 閱讀並執行：

請根據 https://skillhub.cn/install/skillhub.md，安裝 `@indiv-ebandao/make-to-markdown`。

skillhub.md 要點：

1. 檢查是否已有 CLI：command -v skillhub && skillhub --version
2. 未安裝時可執行（完整安裝含默認 Skill）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

僅 CLI：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

3. 安裝技能時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認 ./skills/ 可能不會被加載。常用路徑示例：

示例：

skillhub install @indiv-ebandao/make-to-markdown --dir ~/.cursor/skills/

（將路徑換成你實際使用的 Agent 目錄。）

方式二：npm 生態的 skillhub-cli¶

GitHub 上的 skillhub-cli 支持不全局安裝直接拉取 Skill：

npx skillhub-cli install @indiv-ebandao/make-to-markdown

全局安裝 CLI 後也可使用 skillhub install <skill-name>；具體落盤路徑以 CLI 文檔爲準（例如 ~/.claude/skills/、~/.codex/skills/）。

前置依賴（跑轉換腳本）¶

快速上手文檔要求本機有 uv（用於 markitdown 工具鏈），例如 Windows PowerShell：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
uv --version

安裝 Skill 後，進入技能目錄，可做一次存在性檢查：

python -c "from pathlib import Path; assert Path('scripts/convert.py').exists()"

典型用法¶

安裝完成後，Agent 或直接在本機技能目錄執行以下命令（路徑替換爲你的文件）。

單文件轉換¶

cd path/to/make-to-markdown

python scripts/convert.py 你的文件.docx -o 輸出.md

最小示例（默認輸出命名）：

python scripts/convert.py input.docx

查看技能版本：

python scripts/convert.py --version

批量轉換¶

確認源目錄、輸出目錄、文件數量與 --ext 過濾後再執行：

python scripts/batch_convert.py ./源目錄/ ./輸出目錄/ --ext .pdf .docx --clean

失敗項會寫入輸出目錄下的 _conversion_errors.log（或等價失敗清單）。

舊版 Office 與論文入庫示例¶

# .doc 自動 COM 或 LibreOffice 預處理後轉換
python scripts/convert.py 舊文檔.doc -o 舊文檔.md

# PDF 報告
python scripts/convert.py paper.pdf -o paper.md

可選：單獨後置清洗¶

python scripts/post_clean.py output.md --check-only

轉換成功後的反饋模板會包含狀態、轉換方式（markitdown 或原生降級）、標題與表格統計及輸出絕對路徑。

適用場景與注意¶

適合誰

• 需要把企業內網資料、項目文檔、論文 PDF、混合格式資料庫批量變成 Markdown，再接入向量庫或全文檢索的團隊。
• 已在 Cursor / Claude Code / Codex 等環境使用 Skills，希望用固定紅線與檢查表約束 Agent，避免隨手調用 markitdown 導致依賴不全或輸出未清洗。

限制與坑

• .doc / .ppt 在無 Office COM 且無 LibreOffice 時無法自動預處理，需先安裝其一。
• 加密 Office/PDF 不會反覆重試，需用戶解密後再跑。
• 批量任務應指定 --ext，並在 Init 階段確認路徑與覆蓋策略；大目錄、網絡盤、含 OCR/音頻的慢任務應按 Skill 的 Init → Step → Poll 分步執行。
• 可選依賴可由 convert.py 自動安裝；也可參考 Skill 文檔一次性安裝 markitdown 及 extras，例如：

uv tool install markitdown --with python-docx --with openpyxl --with python-pptx --with pypdf --with xlrd --with ebooklib

完成轉換後，Skill 要求做 V1–V6 檢查（文件非空、UTF-8、水印殘留、標題層級、表格分隔符、批量數量一致等），未通過應走異常處理流程而非直接宣稱入庫成功。

結尾¶

make-to-markdown 把 markitdown 與預處理、降級、清洗、校驗收成一條可重複的 RAG 物料流水線，並通過 Skill 約束 Agent 的執行邊界。若你正在統一知識庫文檔形態，可從 SkillHub 安裝 @indiv-ebandao/make-to-markdown，用 scripts/convert.py 做單文件驗證後再做批量。

• 頁面：https://www.skillhub.cn/skills/indiv-ebandao/make-to-markdown
• API：https://api.skillhub.cn/user_741dc82b/make-to-markdown