doc-cleaner

GitHub release License: MIT Python 3.9+ Supported Formats Last Commit

日常文件轉 Markdown —— 涵蓋 PDF、Office、Apple Keynote/Numbers、EPUB 電子書等 16 種格式。中文友好、表格保留、隱私優先、全程本地。

屬於 notoriouslab 開源工具組的一員 · 需要 Python 3.9+

English README

首次開啟 macOS 版:右鍵 → 開啟(Ventura 以前)或系統設定 → 隱私權與安全性 → 仍要開啟(Sonoma/Sequoia)

或在 Terminal 執行一次:xattr -cr /Applications/Doc\ Cleaner.app

核心定位

三大特色

快速開始

選項 A:桌面 App(非技術用戶)

選項 B:CLI(技術用戶,三步)

# 1. Clone
git clone https://github.com/notoriouslab/doc-cleaner.git && cd doc-cleaner
# 2. 安裝
pip install -r requirements.txt
# 3. 執行
python cleaner.py --input ./documents/ --ai none

常見使用場景

# 最簡單的方式,零成本
python cleaner.py --input statement.pdf --ai none

cp .env.example .env
# 編輯 .env,填入 GEMINI_API_KEY
python cleaner.py --input statement.pdf --ai gemini

# 需先安裝並啟動 Ollama(見下方 Ollama 選型)
python cleaner.py --input statement.pdf --ai ollama

python cleaner.py --input ./documents/ --dry-run --verbose

進階安裝(選裝)

# 高品質 PDF 提取(推薦)
pip install opendataloader-pdf # 需要 Java 11+
# PDF 視覺模式(掃描 PDF)
pip install pdf2image # 另需 poppler:brew install poppler
# PDF 解密
pip install pikepdf
# 額外格式(PPTX / DXF)
pip install python-pptx ezdxf

cp config.example.json config.json
cp .env.example .env
# 編輯 .env 填入 GEMINI_API_KEY 或 GROQ_API_KEY

核心概念

PDF 智慧分流

# 步驟 1:全部用 --ai none 提取(快速、免費、隱私)
python cleaner.py --input ./documents/ --ai none --output-dir ./output/raw
# 步驟 2:檢查 log,只對「掃描圖片」的檔案跑 AI
python cleaner.py --input scanned.pdf --ai gemini

廣告清洗

{
 "ad_truncation_patterns": ["謹慎理財.{0,20}信用至上"],
 "ad_strip_patterns": ["※(注記)運動賺回饋"]
}

表格保留

隱私和安全

桌面 App 建置與打包 (開發者)

建置前置準備

跨平台建置指令

進階參考

命令列選項

python cleaner.py [選項]
 --input, -i 要處理的檔案或目錄(必填,不遞迴)
 --output-dir, -o 輸出目錄(預設:./output)
 --config 設定檔路徑(預設:<程式目錄>/config.json)
 --ai gemini | groq | ollama | none(預設:config 或 gemini)
 --password PDF 解密密碼(優先於 .env 和 config)
 --summary 輸出 JSON 摘要到 stdout(供腳本/Agent 解析)
 --format, -f 輸出格式:md (預設) | epub | both (同時產出 Markdown 與 EPUB)
 --epub-zh-hant 將簡體中文轉換為繁體中文
 --translate-zh-hant 將英文內容翻譯成繁體中文 (台灣習慣用語)
 --dry-run 預覽不寫入
 --verbose 除錯日誌
 --version 版本資訊

設定檔 (config.json)

{
 "ai": {
 "backend": "gemini", // 預設後端
 "prompt_template": "prompts/default.txt", // 提示詞路徑
 "gemini": { "model": "gemini-2.5-pro" },
 "groq": {
 "model": "meta-llama/llama-4-scout-17b-16e-instruct",
 "timeout": 120
 },
 "ollama": {
 "model": "qwen3.5:9b",
 "host": "http://localhost:11434"
 }
 },
 "pdf": {
 "dpi": 200,
 "max_pages": 15
 },
 "output": { "frontmatter": true },
 "ad_truncation_patterns": ["謹慎理財.{0,20}信用至上"],
 "ad_strip_patterns": ["※(注記)運動賺回饋"]
}

# .env 範例
GEMINI_API_KEY=...
GROQ_API_KEY=...
PDF_PASSWORD=...

自訂 AI 提示詞

{
 "title": "簡短標題",
 "summary": "1-2 句摘要",
 "refined_markdown": "完整清洗後 Markdown",
 "tags": ["標籤1", "標籤2"]
}

Ollama 選型

支援格式完整表

整合與生態

AI Agent 框架

# Agent 範例:處理 + JSON 摘要
python cleaner.py --input document.pdf --ai none --summary

{"version":"1.0.0","total":1,"success":1,"failed":0,"files":[{"file":"document.pdf","output":"./output/document.md","status":"ok"}]}

notoriouslab 組合拳

gmail-statement-fetcher → Gmail 自動下載 PDF 對帳單
 ↓
 doc-cleaner → PDF/DOCX/XLSX → 結構化 Markdown
 ↓
 personal-cfo → 月度審計 + 退休滑翔路徑(開發中)

安全政策詳見 SECURITY.md

貢獻

Star History

授權

引用的開源套件