macdoc

macdoc

原生 macOS 文件處理工具集，專注於文件格式轉換和 OCR。使用 Swift 開發，充分利用 Apple 平台原生能力（PDFKit、Vision.framework）。

Claude Code Plugin Marketplace

本 repo 同時是 Claude Code plugin marketplace，提供 macdoc 生態系的 4 個 plugins：

Plugin	內容
che-word-mcp	Word (.docx) MCP server（OOXML 讀寫，218+ 工具）
che-pdf-mcp	PDF MCP server（PDFKit 解析、Vision OCR）
che-pptx-mcp	PowerPoint (.pptx) MCP server（PresentationML 解析與生成）
macdoc	macdoc CLI 使用指南 skill

claude plugin marketplace add PsychQuant/macdoc
claude plugin install che-word-mcp@macdoc   # 或 che-pdf-mcp / che-pptx-mcp / macdoc

MCP plugins 的 wrapper 會自動從各 repo 的 GitHub Releases 下載 universal binary，並在安裝前強制驗證 sha256 與 Developer ID 簽章鏈（Team 6W377FS7BS）；驗證不過即拒裝。

遷移註記：che-word-mcp 與 macdoc 兩個 plugins 原先發布於 psychquant-claude-plugins marketplace，自 2026-07 起以本 marketplace 為準。

Prerequisites

• macOS 14+（Sonoma 或更新）
• Swift 5.9+
• Xcode Command Line Tools

xcode-select --install

Build

git clone https://github.com/PsychQuant/macdoc.git
cd macdoc

# Release build（推薦，效能差 10-50x）
swift build -c release

# Debug build（快速迭代用）
swift build

Install

# 確保 ~/bin 存在且在 PATH 中
mkdir -p ~/bin

# 複製 binary
cp .build/release/macdoc ~/bin/macdoc

# 驗證
macdoc --version

如果 ~/bin 不在 PATH，在 ~/.zshrc 加入：

export PATH="$HOME/bin:$PATH"

Update

cd /path/to/macdoc
git pull
swift build -c release
cp .build/release/macdoc ~/bin/macdoc

Quick Usage

格式轉換（convert）

統一入口，textutil-compatible 語法：

# Word ↔ Markdown
macdoc convert --to md file.docx
macdoc convert --to docx file.md

# Word ↔ HTML
macdoc convert --to html file.docx
macdoc convert --to docx file.html

# HTML ↔ Markdown
macdoc convert --to md file.html
macdoc convert --to html file.md

# PDF → Markdown / Word
macdoc convert --to md file.pdf
macdoc convert --to docx file.pdf

# SRT → HTML（字幕轉網頁，支援 speaker 偵測）
macdoc convert --to html file.srt --css dark --full

# BibLaTeX → APA 7（HTML / Markdown / JSON）
macdoc convert --to html refs.bib --full
macdoc convert --to md refs.bib
macdoc convert --to json refs.bib

# Note → HTML（Notability 筆記互動播放器）
macdoc convert --to html notes.note --full
macdoc convert --to html notes.note --full --css dark

常用選項：

選項	說明
--output <path>	指定輸出路徑
--stdout	輸出到 stdout
--frontmatter	含 YAML frontmatter（Word → MD）
--html-extensions	保留 <u>/<sup>/<sub>/<mark>（→ MD）
--full	輸出完整 HTML 文件
--css dark|light	SRT 主題
--css minimal|web	Bib 樣式

BibLaTeX 工具（bib）

# 列出所有 entries
macdoc bib list refs.bib --show-type

# 產生 APA 7 HTML（可篩選 key）
macdoc bib to-html refs.bib -o refs.html --full
macdoc bib to-html refs.bib --key cheng2025 --key yang2024

# 產生 APA 7 Markdown
macdoc bib to-md refs.bib -o refs.md

PDF → LaTeX Pipeline（pdf）

將 PDF 教科書轉為可編譯的 LaTeX 原始碼。分兩階段：

Phase 1：提取與轉寫

# 1. 初始化專案
macdoc pdf init --pdf textbook.pdf --output textbook-latex

# 2. 掃描頁面資訊
macdoc pdf segment --project textbook-latex

# 3. 渲染每頁為 PNG
macdoc pdf render --project textbook-latex

# 4. Vision OCR 偵測文字區塊
macdoc pdf blocks --project textbook-latex

# 5. AI 轉寫為 LaTeX（最耗時）
macdoc pdf transcribe-pages --project textbook-latex

# 可選參數：
#   --backend codex|claude|gemini    AI 後端
#   --model <model-name>             指定模型
#   --first-page 50 --last-page 100  只轉部分頁面
#   --pages-per-request 2            每次送幾頁

# 6. 偵測章節切分
macdoc pdf chapters --project textbook-latex

# 7. 組裝成 .tex 檔案
macdoc pdf assemble --project textbook-latex

Phase 2：修復與編譯

# 8. 機械式清理（document class、符號、去重）
macdoc pdf normalize --project textbook-latex

# 9. 修復 \begin/\end 配對問題
macdoc pdf fix-envs --project textbook-latex --fix

# 10. 編譯檢查
macdoc pdf compile-check --project textbook-latex

# 11. 自動修復剩餘錯誤（機械清理 + AI agent 迭代）
macdoc pdf consolidate --project textbook-latex

其他 PDF 工具

# 查看專案狀態
macdoc pdf status --project textbook-latex

# 偵測 PDF 來源格式（LaTeX / Word / 掃描件）
macdoc pdf detect-source --project textbook-latex

# 比較原始 PDF 與重製 PDF 的相似度
macdoc pdf compare --project textbook-latex

AI 設定（config）

# 偵測可用的 AI CLI 工具
macdoc config ai detect

# 查看當前設定
macdoc config ai list

# 設定 agent 後端
macdoc config ai set agent claude
macdoc config ai set transcription codex

設定檔位置：~/.config/macdoc/config.json

Supported Conversions