OCR 移出 macdoc：文字辨識一律委派 bestOCR，macdoc 不自帶 OCR 能力

[kiki830621]

Problem

Original text（owner，2026-08-07）：
「ocr的部分我想要從macdoc裡面移出來」
「bestOCR 的readme似乎也是想錯了，反而是macdoc需要文字辨識的時候直接轉給bestOCR」

現行架構（bestOCR README 的關係圖）是 ocr-swift 作為 shared capability layer，macdoc 與 bestOCR 是平行消費者，且 README 明寫：

moving measureOCR out of macdoc changed zero build dependencies. macdoc's PDF tools keep their OCR capability untouched.

Owner 的裁定把方向反過來：OCR 的所有權歸 bestOCR 一家。macdoc 是文件工具（pdf-to-latex 等），需要文字辨識時委派給 bestOCR，不自帶 OCR 能力。

Type

refactor

Expected

• macdoc 不再提供 macdoc ocr 子命令（或降為呼叫 bestOCR 的薄轉接）
• macdoc 對 ocr-swift 的依賴只剩非 OCR 用途（若有），OCR 路徑一律經 bestOCR
• 引擎選擇、版本紀錄、evidence 慣例全部由 bestOCR 單點負責

Actual

• macdoc ocr 自帶完整 OCR 路徑（ollama/mlx backend 選項、--pages、--max-tokens）
• 同一台機器上兩套入口各自演進，引擎與版本紀錄慣例只在 bestOCR 側有

佐證：下游已經先走了

下游題庫專案（educator_item_bank，private）2026-08-07 已把「掃描 PDF → macdoc ocr」的作業指引整段刪除、改為一律走 bestOCR。macdoc 這頭不動的話，macdoc ocr 會變成一條沒有文件、沒人維護 evidence 慣例的殘留路徑——正是最容易產出「不知道哪個引擎、什麼版本辨識的文字」的地方。

Strategy（初步，待 diagnose）

• 盤點 macdoc ocr 的呼叫面（CLI 使用者、skill、文件）
• 決定移除 vs 薄轉接（macdoc ocr 印 deprecation 指向 bestOCR，一版之後移除）
• macdoc README／skill 文件更新
• 與 bestOCR 側 README 修正（tracking issue 見下）同步 land

Related

• Tracking：PsychQuant/bestOCR（README 關係圖與「keep their OCR capability untouched」段落的方向修正）

[kiki830621]

Tracked in: PsychQuant/bestOCR#55（README 關係圖與介面定義）

[kiki830621]

Diagnosis

Type

refactor

Root Cause / Analysis

呼叫面盤點後，OCR 在 macdoc 有兩層，性質不同：

層	位置	性質
獨立子命令 macdoc ocr	Sources/MacDocCLI/MacDoc+OCR.swift（110 行）	通用文字辨識入口——與 bestOCR 完全重疊，是本 issue 要移除的
pdf-to-latex 內部頁級 OCR	Sources/MacDocCLI/PageOCRRunner.swift（145 行）+ MacDoc+PDF.swift 的 block segmentation 管線	管線內部零件，不是通用辨識入口

兩者都吃 ocr-swift 的 OCRCore（Package.swift:42,71）。其餘 Sources 無使用者。

文件引用：CLAUDE.md 2 處、plugins/macdoc/skills/macdoc/SKILL.md 6 處（含專節）。外部：educator 題庫的作業指引已於 2026-08-07 先行切到 bestOCR。

Impact

• Sources/MacDocCLI/MacDoc+OCR.swift、CLAUDE.md、plugins/macdoc/skills/macdoc/SKILL.md
• 不動 PageOCRRunner 與 MacDoc+PDF.swift（見 Strategy 分期）
• Package.swift 的 ocr-swift 依賴保留（內部管線仍需要）

Strategy

分期，第一期只動通用入口：

• macdoc ocr 改為 deprecation shim：印「已移除，文字辨識改用 bestocr（PsychQuant/bestOCR）」並以非零碼退出——比直接刪除對既有腳本友善（明確訊息 vs unknown subcommand），維護成本近零
• CLAUDE.md 與 skill 文件的 macdoc ocr 段改指 bestOCR
• swift build 綠燈
• 第二期（本 issue 不做）：pdf-to-latex 內部頁級 OCR 委派 bestOCR——前置是 bestOCR#55 定義的委派介面（library API 或 CLI 契約）。介面沒定就動手會把管線接到一個不存在的東西上

Conflict Class

A_parallel_safe

改動檔案與 repo 內其他進行中工作（未提交的 che-keynote-mcp）無交集。

Complexity

Simple

第一期是單檔替換 + 文件改指，無介面設計（那是 #55 與第二期的事）。

Risks

• 最大風險是貪多：把內部 PageOCRRunner 一起拔會讓 pdf-to-latex 斷掉，而委派介面還沒定義。分期就是為了擋這個
• shim 的退出碼：用非零（腳本靠 exit code 判斷成敗的不會靜默拿到空輸出）

Residue

• 第二期（內部管線委派）在 feat: restore md-to-word-swift package source and tests #55 介面定案後另開 issue 或回本 issue 追加
• ocr-swift 對 macdoc 的長期角色（若第二期完成，macdoc 可能完全退出 ocr-swift 消費者名單）屬 feat: restore md-to-word-swift package source and tests #55 的架構敘事

---

Layer V: 未觸發 —— owner 指令明確（移出 + 委派方向），分期界線由呼叫面盤點的事實決定

[kiki830621]

Implementation Complete（第一期）

Checklist (synced)

• macdoc ocr → deprecation shim（訊息 + exit 2 + .allUnrecognized 吞舊 flag）→ PR refactor(cli): macdoc ocr → deprecation shim，通用文字辨識移交 bestOCR #146
• CLAUDE.md 與 skill 文件改指 bestocr；skill 不再宣稱 OCR 能力（frontmatter 觸發詞、總覽表、專節、工作流表）→ PR refactor(cli): macdoc ocr → deprecation shim，通用文字辨識移交 bestOCR #146
• swift build --product macdoc 綠；shim 功能實測（訊息／exit 2／舊 flag）
• [~] 第二期（pdf-to-latex 內部頁級 OCR 委派）— 依診斷分期，前置為 bestOCR#55 介面定案，本期不做

對應 tracking

bestOCR#55 的 README 修正已同步：PR PsychQuant/bestOCR#56（架構圖重畫為 bestOCR 單一擁有者、刪「keep their OCR capability untouched」、新增 Delegation interface 節點名開放問題）。

PR

• 本 repo：refactor(cli): macdoc ocr → deprecation shim，通用文字辨識移交 bestOCR #146（draft）
• bestOCR：docs(readme): OCR ownership — bestOCR single owner, macdoc delegates bestOCR#56（draft）

Next: verification pending

文件 + 單檔 shim，機械驗證已列上。review 兩個 PR，merge 後 /idd-close #145（bestOCR#55 待介面定義討論，README 部分隨 #56 完成）。

[kiki830621]

Closing Summary

Root Cause / Motivation

General-purpose text recognition existed in two places: macdoc ocr (single-file GLM-OCR entry) and bestOCR (engine selection, version tracking, evidence conventions). Split ownership means split maintenance and drifting guidance for downstream callers.

Solution

PR #146 (merged):

• macdoc ocr is now a deprecation shim — prints a migration message pointing at bestocr ocr / recommend / consensus and exits 2. Legacy flags (e.g. --backend mlx) are swallowed so old invocations fail with the message, not an argument-parse error.
• CLAUDE.md and the macdoc skill no longer claim OCR capability; workflow tables and config docs point at bestOCR. config ocr remains, documented as pdf-to-latex-internal only.
• Phase boundary: pdf-to-latex's internal page-level OCR (PageOCRRunner) is untouched — it is a pipeline component, not a general recognition entry point. Its delegation is phase 2.

Verification

• swift build green; shim tested: message to stderr + exit code 2; legacy flags absorbed.
• bestOCR README ownership diagram fixed in the companion PR (bestOCR#56, merged).

Residue

• Phase 2 (PageOCRRunner delegation to bestOCR) is blocked on the delegation interface decision (library vs CLI vs MCP) tracked in bestOCR#55. Do not remove config ocr until phase 2 lands.