1. 系統要求與環境檢查 (硬性要求)

在使用此 Skill 之前，請確保您的環境符合以下條件：

• 作業系統: Linux (Ubuntu 建議)。
• 硬體: NVIDIA GPU 且顯存 (VRAM) 至少 8GB 以上。
• API Key: 告知用戶需要 Google Gemini API Key，請至 Google AI Studio 申請。並且告訴用戶這個api key 需要複製到.env檔案中 或是讓用戶直接輸入api key然後你自己寫入.env檔案中

執行自動檢測

請務必先執行檢測腳本，並根據提示修復所有紅叉 ❌：

python3 setup_check.py

2. 第一次使用設定

1. 安裝系統依賴:

   sudo apt update
   sudo apt install uv libreoffice pandoc libmagic1 libgl1-mesa-glx
   

2. 設定 API Key: 在項目根目錄建立 .env 檔案，內容如下：

   GOOGLE_API_KEY=你的_GEMINI_API_KEY
   

3. 安裝 Python 依賴與瀏覽器:

   uv sync
   uv run playwright install chromium
   

   注意：第一次執行轉換時會下載模型權重（約需 10 分鐘以上）。

3. 進行文件轉換 (Agent 指引)

當使用者要求轉換文件時，請遵循以下流程：

1. 路徑處理:
   • 必須使用絕對路徑執行指令。
   • 如果使用者提供相對路徑，Agent 應自動結合當前目錄 (cwd) 轉換為絕對路徑。
2. 執行轉換: 切換至 Skill 目錄並執行：期

   uv run python main.py "<檔案絕對路徑>" [選項]
   

3. 成品回報:
   • 告知使用者 Markdown 檔案與 images/ 資料夾已生成在原始檔案所在的目錄下。
   • URL 模式例外: 網頁轉換的成品會放在 Skill 目錄下的 output_files/。

4. 命令列範例 (CLI)

A. 轉換 Office / 文件 (Word, PPT, ODT, ODP, RTF)

• uv run python main.py "/abs/path/to/doc.docx"

B. 轉換網頁 (URL 或 HTML)

• uv run python main.py "https://example.com" (預設開啟互動模式以處理驗證)
• uv run python main.py "https://example.com" --no-interactive (背景執行)

C. 轉換表格 (Excel, CSV, ODS)

• uv run python main.py "/abs/path/to/data.xlsx"

D. 轉換圖片 (JPG, PNG, WEBP)

• uv run python main.py "/abs/path/to/image.jpg"

E. 轉換 PDF (Gemini 模式 - 預設)

• uv run python main.py "/abs/path/to/paper.pdf"

F. 轉換 PDF (Local 模式 - 純本地)

• uv run python main.py "/abs/path/to/book.pdf" --mode local -p 1-50 (指定頁碼範圍 可以主動詢問用戶是否要限定範圍)

5. 支援格式清單

• 文件: .pdf, .epub, .docx, .doc, .odt, .rtf, .txt
• 簡報: .pptx, .ppt, .odp
• 表格: .xlsx, .xls, .ods, .csv
• 圖片: .jpg, .jpeg, .png, .webp
• 網頁: http://, https://, .html, .htm