HEIC to JPG 無損轉檔工具（CLI, GUI & MCP）

heic-to-jpg-desktop 是一個專為 Windows 與 macOS 打造的 HEIC 轉 JPG 工具，支援高效率命令列介面（CLI）、高質感視窗介面（GUI），以及最新支援的 AI 代理模型上下文協定（MCP）。本工具採用純 JavaScript/WASM 技術，完全不需要在您的系統中額外安裝 ImageMagick 或 ExifTool 等第三方圖像軟體。

✨ 功能特點

• 無損 / 最高品質轉檔：轉換時使用最大品質設定（不壓縮），確保所有影像細節完美留存。
• 完整保留 EXIF 資訊：保留照片原始的拍攝時間、相機型號、相片方向、GPS 位置等元資料（Metadata）。
• 安全防覆蓋命名：若目的地已有同名 JPG，或 heic 資料夾內已有同名原始檔，程式將自動為新檔案加上序號（例如 photo_1.jpg、photo_1.heic），以防任何檔案被覆蓋。
• 自動分類搬移：轉檔完成後，原始的 HEIC 檔案會被自動移入該層目錄新建的 heic 資料夾中，而生成的 JPG 檔案則保留在原地，方便整理。
• 支援子資料夾遞迴處理：可自訂是否要一併掃描並處理所有子目錄下的 HEIC 檔案。

🛠️ 安裝與使用（CLI 模式）

本工具已發布至 npm，您只需要擁有 Node.js 環境即可，完全不需要下載或複製專案原始碼。

免安裝直接執行（推薦）

使用 npx 指令，系統會自動下載並執行最新版的轉換工具：

# 語法：
# npx heic-to-jpg-desktop -p <資料夾路徑> [-r]

# 範例 1：處理特定資料夾（不遞迴處理子目錄）
npx heic-to-jpg-desktop -p "/Users/username/Pictures/Photos"

# 範例 2：處理特定資料夾且遞迴處理子目錄
npx heic-to-jpg-desktop -p "/Users/username/Pictures/Photos" -r

全域安裝

若您會頻繁使用，也可以將其全域安裝到系統中：

npm install -g heic-to-jpg-desktop

# 安裝後可直接使用指令：
heic-to-jpg-desktop -p "/Users/username/Pictures/Photos"

🤖 AI 代理模式（MCP）

本專案內建了 Model Context Protocol (MCP) 伺服器，能讓各種支援 MCP 的 AI CLI（如 agy CLI、Claude Code 等）直接呼叫轉檔功能，無需手動記憶指令。

如何串接至你的 AI CLI：

請複製以下提示詞並貼給你的 AI CLI，它便會自動幫你完成設定：

請幫我將 heic-to-jpg 專案加入為 MCP 伺服器：
名稱：heic-to-jpg-mcp
指令：npx
參數：["-y", "heic-to-jpg-desktop@latest", "heic-to-jpg-mcp"]
工作目錄（cwd）：無限制

設定完成後，你就可以直接對 AI 說：「幫我把這個目錄底下的 HEIC 檔案轉檔」，AI 就會自動呼叫本專案的轉檔功能。

🖥️ 視窗畫面模式（GUI）

如果您偏好直覺的圖形介面，您仍然可以將專案下載回本地端執行 GUI 模式：

1. git clone https://github.com/andyawd/heic-to-jpg-desktop.git
2. cd heic-to-jpg-desktop && npm install
3. npm start

操作步驟：

1. 點擊 選擇資料夾 按鈕，彈出系統原生視窗以選擇包含 HEIC 照片的資料夾。
2. （選用）開啟 遞迴處理子資料夾 開關，以一併轉換所有子目錄的照片。
3. 點擊 開始執行轉換。
4. 介面將即時顯示進度條，並在下方的日誌面板中，以不同顏色印出每個檔案的轉檔狀態與搬移紀錄。

📂 轉換前後目錄變化範例

轉換前：

📸 我的照片資料夾/
├── photo1.heic
├── photo2.heic
└── travel.png (非 HEIC，不會被觸動)

轉換後：

📸 我的照片資料夾/
├── photo1.jpg (新生成，保留 EXIF 且不壓縮)
├── photo2.jpg (新生成，保留 EXIF 且不壓縮)
├── travel.png (保持原樣)
└── 📂 heic/
    ├── photo1.heic (由上一層移入)
    └── photo2.heic (由上一層移入)

🛡️ Git 提交偏好說明

本專案開發過程中的所有自動提交均遵循 Google Antigravity 規範：

• 作者（Author）：Google Antigravity <[email protected]>