macOS Vision 本機 OCR 是做什麼的？
本 Skill 指導你把用户提供的圖片/PDF 轉成文字：用 macOS 系統自帶的 Vision 引擎
（macocr 命令）在本機完成辨識，不上傳任何資料。
環境檢查（必須先做）
在呼叫任何 OCR 命令之前，先執行以下檢查，任一不滿足即停止並按說明回應：
[ "$(uname -s)" = "Darwin" ] && echo OK-macOS
command -v macocr || ls "$HOME/.local/bin/macocr"
uname不是Darwin：本工具僅支援 macOS。不要嘗試安裝或編譯，直接告知使用者 該 Skill 只在 macOS 上可用，並建議改用其他 OCR 方案。macocr不存在：引導使用者在本包目錄執行./install.sh（編譯需 Xcode Command Line Tools；Apple Silicon 無編譯環境時自動回退到隨附的預編譯二進位檔）。安裝完成後用sh scripts/selftest.sh做一次端到端自我檢測，通過後再繼續。
安裝與自我檢測都完成後，每次會話無需重複執行。
執行任務的標準流程
按以下步驟處理使用者的 OCR 請求，不要跳步：
-
確認輸入類型。使用者給的是圖片（png/jpg/jpeg/heic/tiff）直接進第 3 步； 是掃描版 PDF（無文字層）先進第 2 步轉圖。
-
PDF 轉圖（僅掃描版 PDF 需要）。用系統自帶的 sips 渲染，144dpi 起步：
sips -s format png -s dpiHeight 144 -s dpiWidth 144 輸入.pdf --out /tmp/p1.png注意 sips 只處理單頁；多頁 PDF 需逐頁指定或有 pymupdf 時用 4 倍矩陣渲染 （小字號課件效果顯著更好，見「掃描版 PDF 怎麼用」）。
-
執行辨識。預設命令即可覆蓋絕大多數場景：
macocr <圖片路徑> # 多圖可依序列出，輸出用 === 分隔按場景追加參數（參數表見下）。辨識結果是純文字，已按視覺行序排好。
-
結果交付。直接向使用者展示辨識文字；表格/數字密集的結果必須提醒使用者 關鍵數字需二次確認（見「表格資料的特殊注意」）。
參數速查
| 參數 | 用途 |
|---|---|
--fast | 關閉語言糾錯。表格與數字場景推薦，避免數字被"糾錯"成奇怪的值 |
--lang zh-Hans+en-US | 預設中英混排。純英文設 en-US 提速；繁體用 zh-Hant |
--rect x,y,w,h | 只辨識矩形區域（左上原點，像素）。大圖裡只提某個表格時使用 |
--upscale N | 模糊小圖（寬 <1000px 的轉發圖、舊掃描件）先 Lanczos 放大 N 倍（1.0–4.0）。只在普通模式辨識率差時逐級試 2 → 3，清晰大圖盲目放大會引入筆畫黏連 |
--orientation up|left|right|180 | 照片旋轉/倒置時手動轉正。Vision 不按 EXIF 自動轉正，側拍圖必須用這個 |
--list-langs | 列出本機支援的辨識語言（用於安裝自我檢測，輸出應含 zh-Hans） |
辨識率低時的處理順序
按成本從低到高嘗試，不要一上來就上複雜方案：
- 找原圖：聊天轉發圖辨識率極低，先請使用者提供原始檔案
--rect圈出目標區域，減少噪聲--upscale 2（模糊小圖）--fast（表格數字場景）- 影像前處理（裁切 + 灰階 + 自動對比度 + 銳化 + 二值化），範例見下
from PIL import Image, ImageOps, ImageEnhance
im = Image.open("src.JPG")
im.crop((x0, y0, x1, y1)).resize((w*2, h*2), Image.LANCZOS) # 裁切 + 放大
ImageOps.autocontrast(im.convert("L")) # 灰階 + 自動對比度
ImageEnhance.Sharpness(im).enhance(2.0) # 銳化
im.convert("L").point(lambda p: 255 if p > 128 else 0) # 二值化
多版本投票：對同一個表格跑 2–3 種前處理，取一致部分，不一致的數字單獨複核。 交叉驗證：整行/整列求和能對上基本可信；對不上說明某個數字錯了。
為什麼「照片」App 的原況文字看起來比裸調 API 準？
同一個 Vision 引擎，差距來自前後處理，不是模型本身：
- 方向：「照片」按 EXIF 轉正再辨識；裸調 API 預設按
.up處理 → 用--orientation補上 - 解析度：「照片」用全解析度原圖；工作流程裡流轉的常是壓縮預覽圖 → 永遠優先使用原始檔案
- 隱式降採樣：
NSImage按「點」出圖，@2x/@3x 截圖與部分 HEIC 會被砍掉一半像素 → 本工具遍歷 rep 取最大像素點陣圖 - 豎排文字：原況文字能處理豎排；裸調用會把豎排切成碎行 → 本工具自動檢測並做信心度仲裁
- 互動紅利（無法完全複製）：原況文字允許點選局部，感知上"錯得少"；命令列一次吐全文，任何錯字都顯眼
結論：引擎相同，管線決定上限。
表格資料的特殊注意
OCR 在表格上最容易出錯：小數點被吞（. → ,）、相鄰列並成一串、行混淆。
關鍵數字必須二次確認：有 PDF 原件就抽文字層對照；只有照片就靠多版本投票 + 行列邏輯驗證。
何時不用本工具
| 場景 | 更合適的選擇 |
|---|---|
| 所用 AI 模型本身支援讀圖 | 直接讓它看圖，不必繞 OCR |
| 需要複雜版面還原（多欄、公式、表格框線結構） | MinerU 等版面級解析服務（資料會上雲） |
| 整份掃描 PDF 批量轉文字且可上雲 | 雲端 OCR 服務的批次介面 |
規則：本機優先，資料不外發；確實需要更高精度再上雲，且先確認資料可以外發。
驗證與排錯
- 安裝後自我檢測：
sh scripts/selftest.sh（用包內測試圖端到端驗證，輸出 PASS/FAIL） - 語言列表不含 zh-Hans：系統語言資料不完整，極少見；檢查 macOS 版本是否 ≥ 13
- 輸出為空或全錯：先確認圖片本身可讀（
sips -g pixelWidth -g pixelHeight 圖片）， 再按「辨識率低時的處理順序」逐級嘗試
系統需求
- macOS 13+（
automaticallyDetectsLanguage需要 13.0） - 編譯需要 Xcode Command Line Tools（
xcode-select --install）； 或使用隨附的 Apple Silicon 預編譯二進位檔（scripts/macocr-arm64，ad-hoc 簽名）
包內檔案說明
| 檔案 | 用途 | 何時需要 |
|---|---|---|
install.sh | 安裝 macocr（編譯優先，預編譯兜底） | 環境檢查發現 macocr 不存在時 |
scripts/selftest.sh + scripts/selftest.png | 端到端自我檢測（腳本 + 自帶測試圖） | 安裝後驗證；排查"辨識異常"時先跑它確認工具本身正常 |
scripts/vision_ocr.swift | 原始碼（約 200 行，可審計） | 需要自行編譯或審計時 |
scripts/macocr-arm64 | Apple Silicon 預編譯二進位檔 | 無 swiftc 的 Apple Silicon 機器，由 install.sh 自動使用 |