AeternaLabsHQ/pullmd

PullMD – 自主托管的 URL 轉 Markdown 服務

是什麼

• 一個自托管的 Web 服務，可取得網頁（或多種其他媒體類型）並回傳乾淨、高效的 Markdown 文件。
• 專為需要線上內容簡潔、結構化表示的人類與 AI 代理設計。

核心功能

功能	詳細
網頁提取	採用級聯流程：Cloudflare 原生 Markdown → Mozilla Readability → Trafilatura → （備援）透過 Playwright 使用無頭 Chromium。可完整處理 Reddit 和 Hacker News 線程及評論樹。
文件轉換（v3）	支援上傳或透過 URL 提供 PDF、Word/PowerPoint/Excel、EPUB 等檔案。可選 OCR 層（?pdf=ocr）可產生高品質表格。
媒體處理	圖像 → 生成字幕；音訊 → 轉錄；YouTube URL → 提取標題、描述和帶時間戳的轉錄文字。所有功能由您設定的任意 OpenAI 兼容視覺/語音辨識端點驅動。
輸出格式	Markdown 正文僅包含 # 標題 + 內容。所有元資料（來源 URL、取得日期、作者、子版塊、讚數、OCR/模型使用情況等）均儲存在 YAML 前置元資料區塊中，可透過 PULLMD_FRONTMATTER_FIELDS 進行裁剪以降低 LLM 流水線的 token 使用量。
可共享 ID	每次轉換都會分配一個 8 位十六進位 ID。GET /s/:id 回傳快取的 Markdown，並在超過一小時後自動刷新。
API 表面	• GET /api?url=… – 一次性轉換（僅限網頁）。 • POST /api/file – 上傳文件、影像或音訊進行轉換。 • POST /mcp – 用於無狀態串流的 MCP（Claude 兼容）端點。
認證	三種模式：disabled（開放）、single-admin（單一管理員）、multi-user（自助註冊）。管理員可透過提供的 CLI 管理使用者。
安全	內建 SSRF 保護，阻止私人、迴圈、鏈路本地和雲端元資料位址。可透過 PULLMD_ALLOWED_HOSTS 白名單化主機。
可擴充性	可透過 PULLMD_SITE_RECIPES 加入網站特定的「配方」（JSON-LD 轉前置元資料、自訂選擇器等）。
監控	側車健康端點（GET /api/status）在渲染器（Playwright、MarkItDown 等）當機時回傳 503。

如何執行

1. Docker Compose（推薦） – 從 Docker Hub 拉取預先建置的多架構鏡像，透過單一指令啟動：

   mkdir pullmd && cd pullmd
   curl -O https://raw.githubusercontent.com/AeternaLabsHQ/pullmd/main/docker-compose.yml
   docker compose up -d   # 服務監聽 http://localhost:3000
   

   無需 .env 檔案；合理預設值已內嵌。透過在 compose 檔案旁建立 .env 檔案可覆蓋任意設定。
2. 可選側車 – 此堆疊包含三個輔助容器：
   • pullmd-trafilatura – Trafilatura 提取服務。
   • pullmd-playwright – 用於 JS 豐富頁面的無頭 Chromium/Firefox/WebKit 渲染器（增加約 3.7 GB 鏡像快取）。若僅需靜態提取，可省略。
   • pullmd-markitdown – 文件轉 Markdown 轉換器（PDF/Office/EPUB 必需）。禁用文件轉換可省略。
3. 本地開發 – 克隆倉儲，執行 npm install，然後 npm start。

設定亮點（於 .env 檔案中設定）

• PUBLIC_URL – 幫助頁面和可下載的 Claude 技能中使用的公開來源。
• PULLMD_AUTH_MODE – disabled / single-admin / multi-user。
• PULLMD_ADMIN_EMAIL / PULLMD_ADMIN_PASSWORD – 啟動管理員憑證。
• PULLMD_VISION_API_KEY, PULLMD_STT_API_KEY – 透過任意 OpenAI 兼容視覺/語音辨識端點啟用影像字幕或音訊轉錄。
• PULLMD_PDF_OCR_API_KEY – 啟用 PDF 的高階 OCR 層（?pdf=ocr）。
• PULLMD_FRONTMATTER_FIELDS – 白名單化前置元資料欄位，以降低 LLM 流水線的 token 使用量。
• DISABLE_PUBLIC_HISTORY – 隱私優先部署中隱藏全域轉換歷史。
• PULLMD_ALLOWED_HOSTS – 若需繞過預設 SSRF 阻擋取得內部主機，可加入白名單。

對 AI/LLM 工作流程的意義

• Token 效率：透過將所有元資料移至前置元資料區塊並最小化正文，可將 Markdown 直接輸入 LLM，避免重複 URL 或時間戳浪費上下文。
• 代理就緒：MCP 端點允許 Claude 風格代理透過串流相容 HTTP 呼叫請求轉換。
• 自托管控制：基本網頁提取無需第三方 API 金鑰，確保資料私密且成本可預測。
• 可擴充媒體處理：影像和音訊可即時生成字幕/轉錄，對多模態代理非常有用。

典型用法

# 單次網頁轉 Markdown
curl "http://localhost:3000/api?url=https://example.com"

# 上傳 PDF 進行轉換（需要 markitdown 側車）
curl -F file=@report.pdf http://localhost:3000/api/file

# 透過 ID 取得可共享 Markdown
curl http://localhost:3000/s/1a2b3c4d

授權 – AGPL-3.0（參見 LICENSE）。

---

以上所有細節均直接取自倉儲的 README；未推斷任何額外功能。