feat(ocr): 支援 --parallel N 多檔案並行處理

[kiki830621]

Problem

目前 macdoc ocr 一次只能處理單一 input 檔案，要批次處理多個 PDF/PNG 時必須在外層用 xargs -P 或 shell background job 才能並行。但 Ollama 本身（v0.2+）預設支援 OLLAMA_NUM_PARALLEL=4 的併發請求，使用者沒有簡單的方法把這個能力用起來。

Use Case

實測情境：77 個轉學考 PDF（共數百頁）送遠端 Ollama（SSH tunnel 到 Kyle M4 Max 跑 glm-ocr）。序列版本跑了 2+ 小時、因 SSH tunnel 中斷還失敗 30 個；要手寫 xargs -P 4 包裝才能真正並行。

Type

feature

Expected

```bash

方式 A：多個輸入

macdoc ocr page-1.png page-2.png page-3.png --output-dir out/ --parallel 4

方式 B：目錄/glob

macdoc ocr "dir/*.png" --output-dir out/ --parallel 4

方式 C：PDF 多頁內部並行

macdoc ocr file.pdf --output file.md --parallel 4
```

需求：

• `--parallel N` (default 1) 控制並發數
• 支援多個 input 或 glob pattern
• `--output-dir` 輸出到目錄，檔名沿用 input basename
• 內部維持連線池或重用 URLSession 避免每次重建
• 遇到個別失敗不要整批中斷，最後彙整回報成功/失敗
• 每頁/每檔的進度回報到 stderr

Actual

```
USAGE: macdoc ocr [--output ] [--pages ] [--backend ] [--model ] [--host ] [--max-tokens ]
```

只接受單一 input，無並行選項。

Impact

• 批次 OCR 效能：序列 vs 4 路並行可達 ~2.4x（實測單頁 22s → 4 頁 37s）
• 使用者不用每個專案都手刻 xargs + tunnel 重連 wrapper
• 降低整體 wall-clock，對遠端 GPU 資源利用率也更高

Related

• psychquant-claude-plugins 會同步新增 skill 章節（並行 pattern、Ollama 設定）
• 考慮另外做 batch-ocr plugin 處理更上層的編排（tunnel 管理、PDF→PNG→合併 pipeline）

Current Status

Phase: diagnosed
Last updated: 2026-04-22 by idd-diagnose (batch)

[kiki830621]

Diagnosis

Type

feature (enhancement)

Root Cause / Analysis

Current macdoc ocr CLI surface at Sources/MacDocCLI/MacDoc+OCR.swift:13-31:

@Argument(help: "輸入檔案（PDF、PNG、JPG）")
var input: String            // ← single input only
@Option(name: .long) var output
@Option(name: .long) var pages
@Option(name: .long) var backend
@Option(name: .long) var model
@Option(name: .long) var host
@Option(name: .long) var maxTokens

No --parallel, no multi-input, no glob expansion, no --output-dir. Reporter's 77-PDF batch had to be shell-wrapped with xargs -P 4, and SSH-tunnel failures took out 30/77 jobs with no retry path.

Ollama supports OLLAMA_NUM_PARALLEL=4 server-side so the upstream capacity exists; the bottleneck is purely macdoc's single-input CLI.

Impact

• Sources/MacDocCLI/MacDoc+OCR.swift — needs variadic @Argument or repeated option for inputs + --parallel / --output-dir
• Sources/MacDocCLI/PageOCRRunner.swift — needs internal concurrency (TaskGroup) and connection-reuse across pages/files
• packages/ocr-swift/Sources/OCRCore/Backends/OllamaBackend.swift — verify URLSession reuse; add connection pool if not present
• User experience: 2-4× wall-clock speedup on batch OCR; resilience to tunnel drops if retry/resume added

Strategy

• /spectra:discuss to scope: multi-input ARG vs glob-string vs --input-list file.txt? retry semantics on tunnel failure? --output-dir naming convention (basename.md vs hash)?
• CLI surface: accept variadic [String] input, add --parallel N (default 1), --output-dir <path>, --continue-on-error
• Internals: TaskGroup bounded by --parallel, shared URLSession (connection reuse), per-job progress lines to stderr, final summary N success / M fail
• For PDFs: per-page parallel within a file (--parallel applies to pages, not just files) — touches PageOCRRunner.swift
• Test: mock Ollama backend asserting N concurrent requests bounded by --parallel

Complexity

SDD-warranted — CLI contract change (multi-input is a breaking surface change) + concurrency primitives + error recovery semantics. Needs /spectra:discuss to pin the UX shape (per-file vs per-page parallelism, retry model) before proposing.

Risks

• Ollama server-side concurrency limit mismatch: if --parallel 8 but server has OLLAMA_NUM_PARALLEL=4, requests queue — not wrong but confusing. Emit startup warning if requested > server limit (requires probing).
• URLSession reuse has been source of macOS-specific bugs (connection-leak under HTTP/1.1 keep-alive). Add stress test.
• SSH tunnel drops mid-batch: need retry-on-connection-reset, not full restart. Consider --resume that skips already-produced output files.
• Progress reporting order: parallel execution means output lines interleave; buffer per-job and flush atomically to stderr.

Related

• 建立 CLI 指令規範檔（cli-spec.yaml）作為所有指令的 single source of truth #72 (cli-spec.yaml) — if landed, should capture the multi-input shape
• feat(ocr): VLM 輔助圖片偵測與裁切 --extract-figures #74 (--extract-figures) — shares the OCR plumbing; consider co-scoping