通用 external-process engine 協定 — 長尾 ASR 家族的掛載機制 (follow-up from #35)

[kiki830621]

Problem

#35 以 Swift-native 路線打通跨家族競擇（FluidAudio Parakeet），但 reference catalog 的 15 家族多數無 Swift-native 實作（Canary、MMS、Voxtral、Granite、Mega-ASR…）。逐家族原生整合不 scale。

Expected

設計通用 external-process engine 協定（CLI adapter spec）：任何符合協定的外部工具（mlx-audio CLI、faster-whisper、自製 wrapper）可註冊為 engine 進入競擇池。需正面回應 #20 的移除理由（Python venv/worker 生命週期/上游 churn 的 containment 設計）與異質錯誤面、量測可比性。

Actual

候選池僅限編譯進 binary 的 Swift engines。

前置

• 刻意 deferred（YAGNI，ASR router 候選模型池不應只剩 Whisper 家族 — 恢復跨家族多模型競擇（設計願景回歸） #35 design）：等 Swift-native 路線覆蓋 2+ 家族、機制穩定後再設計通用協定
• 移除 mlx-audio backend — 模型目錄降級為 reference catalog #20 的 closing summary 是 containment 需求清單的起點

---

Source: follow-up from #35 change add-parakeet-cross-family-engine（design D1-D6、tasks 4.3）

---

Current Status

• Phase: closed
• Updated: 2026-07-06
• Complexity: Spectra（啟動時）
• Verify: PASS after 1 fix round（2H+5M；M5 residue）
• Next: (done — merged & closed 2026-07-06)

[kiki830621]

Diagnosis

Type

design（通用 external-process engine 協定——長尾家族掛載機制）

Root Cause / Analysis

前置條件狀態更新（2026-07-06）：issue 自載的 defer 條件「等 Swift-native 路線覆蓋 2+ 家族、機制穩定」已由 #50 滿足——candidate pool 現有 parakeet（#35）＋ sensevoice（#50）兩個非 Whisper 家族（paraformer 接線但因 upstream bug 擱置），Engine seam 模板歷經三次複用（Parakeet/ChineseFamily×2）證明穩定。

但「條件滿足」≠「現在落地」——協定設計的健康前提是有第一個具體 consumer：

• 長尾家族（Canary／MMS／Voxtral／Granite…）目前無具體使用場景牽引；使用者的核心關切「多模型而非全 whisper」已由 en（whisper+parakeet 實測 trade-off）與 zh（whisper+sensevoice 近打平）實質回應（中文 high-value ASR 家族評估 — FluidAudio 已內建 Paraformer/SenseVoice（零新依賴，優先於 MLX-Swift Qwen3-ASR）(follow-up from #35) #50/Parakeet hardening：真實語料 fairness 實測、timings 防禦、AsrManager actor 化、transcribe e2e dispatch 測試 (follow-up from #35 verify) #53 實測在案）。
• 憑空設計 CLI adapter 協定（stdout 契約、錯誤面、venv 生命週期 containment、量測可比性）而無真實 adapter 對照 = 高機率設計出不合身的介面——移除 mlx-audio backend — 模型目錄降級為 reference catalog #20 移除 mlx-audio 的教訓正是 premature integration。
• 健康路徑：協定與第一個 consumer 同時落地（該家族的真實輸出形狀、錯誤模式、安裝面直接餵給協定設計），如同 ASR router 候選模型池不應只剩 Whisper 家族 — 恢復跨家族多模型競擇（設計願景回歸） #35 的 spike-first 模式。

Strategy（供裁決的兩個選項）

• (a) 建議：defer-until-consumer——issue 保持 open 作 design-anchor；當第一個具體長尾需求出現（例：需要 Canary 的長音檔強項、或某語言只有 MLX 家族覆蓋）即啟動，屆時協定+adapter+實測一體成形
• (b) 立即設計：以 mlx-audio CLI 為假想 consumer 寫協定 spec——可做，但 mlx-audio 是 移除 mlx-audio backend — 模型目錄降級為 reference catalog #20 剛移除的對象，把它請回來當第一 consumer 需要新的品質/維運證據

Conflict Class

D_diagnose_first →（裁決後）C_shared_module_coord（Engine seam 模組）

Complexity

Spectra（啟動時）——本輪 batch 停在 diagnosed：defer 與否是 scope 裁決，unattended orchestrator 不代決

Risks

• defer 的風險：長尾需求出現時要冷啟動——但 seam 模板＋移除 mlx-audio backend — 模型目錄降級為 reference catalog #20 closing summary（containment 需求清單）已把冷啟動成本壓低
• 立即設計的風險：無 consumer 驗證的協定大概率返工（移除 mlx-audio backend — 模型目錄降級為 reference catalog #20 前車）

Residue

• 移除 mlx-audio backend — 模型目錄降級為 reference catalog #20 closing summary 的 containment 清單（Python venv／worker 生命週期／上游 churn）仍是啟動時的需求起點

Vagueness Pre-check

• V1: 2 — WHAT 明確但「何時做」是懸置的 scope 裁決
• V4: 3 — acceptance 依賴 consumer 選定
• Triggered: no（≤3）——但 defer 裁決本身升級給使用者（見 Complexity）
• [Layer V evaluated under /idd-all unattended mode]

[kiki830621]

Decision（使用者裁決，2026-07-06）

Original text:
「(b) 立即設計——現在就把 CLI adapter 協定的 spec 寫出來。我是真的需要，因為現在很多模型比whisper好欸」
— Source: 使用者

裁決：立即設計。 使用者的理由本身指定了 consumer——「比 whisper 好的新模型」正是 mlx-audio 承載的 15 家族（Qwen3-ASR／Canary／Voxtral…，reference catalog 已有 pinned repos）。

第一 consumer 選定：mlx-audio CLI：

• 一次兌現整個 reference catalog（15+ STT 家族），而非逐家族 wrapper
• 正面回應 移除 mlx-audio backend — 模型目錄降級為 reference catalog #20：當年移除的是「內建 backend」（Python 依賴滲進 bestASR 生命週期）；本協定的核心即 containment——外部 process、venv 歸 adapter 自管、bestASR 只碰協定 JSON
• grid 的 mlx-audio reference rows（hfRepo＋pinned revision）從「僅供查閱」升級為「external 可跑」的天然目錄

— /idd-all batch lane 4/4 恢復啟動

[kiki830621]

端到端實測（task 3.2，2026-07-06）

全鏈驗證通過：engines.json registry → bestasr list-backends 顯示 mlx-audio available → transcribe --backend mlx-audio --model 0.6b（MLX parakeet，HF pinned revision ed2b7e8c…）→ adapter venv → 協定 JSON → 正確逐字輸出（osr-harvard-1，全程 ~3.6s 端到端含 spawn＋model load）。

Containment 的活案例：首跑即撞上游相容性 bug——mlx_lm 的 string-key AutoTokenizer.register 對 transformers ≥4.54 崩（'str' object has no attribute '__module__'）。錯誤如協定設計loud、attributed 到 mlx-audio、不 fallback；修復完全發生在 adapter venv（pin transformers<4.54，setup.sh 已載入註記），bestASR 本體零改動——正是 #20 移除理由（上游 churn）被 containment 隔離的證明。

10 個協定測試（真 subprocess fake adapters，含 timeout SIGTERM→SIGKILL）＋271/271 全套件綠。無 registry config 的機器行為與 pre-#51 byte-identical。

— /idd-all batch lane 4/4

[kiki830621]

Verify Report — #51

Engine

1 general-purpose Agent (opus — requirements+logic+security 合併 lens) + coordinator。Codex 缺席（usage limit，使用者確認跳過）。

Aggregate

PASS（after 1 fix round） — 2 HIGH + 5 MEDIUM，可修者全修（2578d41）；M5 記 residue。271/271 tests 綠、修後端到端複驗（真 mlx 轉錄）。

Findings（合併後）

#	Severity	Finding	Action
1	HIGH	spec-drift 重犯類：benchmark「rows whose backend has no bundled engine SHALL NOT be enumerated」與 model-grid「Priority tiers…no enumeration effect」兩條 living 需求被枚舉泛化推翻，未下 MODIFIED delta；proposal Affected specs 漏列 benchmark	Fixed（兩條全量重現補進 change；proposal 補列）
2	HIGH	segments(from:) compactMap 部分丟 timed segment——transcript text 由 segments 拼出 → 丟段即丟字，靜默污染 WER；且與 #53 的 batch-distrust 語意不一致	Fixed（同 #53 語意：一個 inverted/全出界段 → 整批退 reply.text 全文）
3	MEDIUM	list-models 對已註冊的 mlx-audio 仍標「backend not bundled」，與 list-backends 矛盾	Fixed（標題依 registry 狀態）
4	MEDIUM	timeout kill 後孫程序若持 pipe 寫端，readDataToEndOfFile 可讓 host 卡死	Fixed（kill 後關閉 read 端解鎖 drain）
5	MEDIUM	stdout 無大小上限（失控 adapter 可撐爆記憶體）	Residue（v1 威脅模型：adapter 是使用者顯式安裝的本地工具；streaming cap 列後續）
6	MEDIUM	adapter 對舊版 mlx_audio 的 revision 降級無警告	Fixed（stderr warning）
7	MEDIUM	adapter 物件式 segment 解析 eager-eval 必 crash（未達路徑，fail-loud 隔離）	Fixed（dict/object 乾淨分支）
8	INFO	通過項：argv spawn 無 shell、威脅模型陳述誠實（engines.json = 使用者 opt-in、無提權）、fail-loud 無 fallback、no-registry byte-identical（有測試）、asr-routing/model-grid 主 delta 全量重現、timeout SIGTERM→SIGKILL 有真測試	通過
9	LOW	isAvailable 不驗協定（假執行檔到 transcribe 才炸）；CLITests 讀真實 home config 非 hermetic；busy-wait 50ms polling；hfRepo==nil 的 mlx 列枚舉後必失敗	Documented（非阻擋；hermetic 化與 probe 子命令列後續）

實測

• 端到端 ×3：list-backends mlx-audio available → MLX parakeet 0.6b 真轉錄 osr-harvard-1（逐字正確，~3.6s 端到端）→ 修後複驗
• Containment 活案例：首跑撞 mlx_lm↔transformers 上游不相容——錯誤 loud＋attributed、host 零改動、修復完全在 venv（pin transformers<4.54）——移除 mlx-audio backend — 模型目錄降級為 reference catalog #20 的移除理由被本設計實地隔離
• 10 協定測試（真 subprocess fake adapters）＋271/271 綠

Process Gaps

• 單 agent 配置（Codex 額度）。spec-drift 是本 batch 第三次被 verify 抓（diarization SRT speaker 標籤格式應為「Speaker N: 」colon 前綴 — 現行為 [SPEAKER_N] 方括號 #54/中文 high-value ASR 家族評估 — FluidAudio 已內建 Paraformer/SenseVoice（零新依賴，優先於 MLX-Swift Qwen3-ASR）(follow-up from #35) #50/通用 external-process engine 協定 — 長尾 ASR 家族的掛載機制 (follow-up from #35) #51）——已在 中文 high-value ASR 家族評估 — FluidAudio 已內建 Paraformer/SenseVoice（零新依賴，優先於 MLX-Swift Qwen3-ASR）(follow-up from #35) #50 report 建議的「propose 時從 living spec 抽全文再改」流程這次部分執行（主 deltas 對了），漏的是「實作觸碰的第三、四條需求」；教訓升級：implementation 改到的每個枚舉/行為點都要回掃 living specs。

[kiki830621]

Closing Summary

Root Cause

候選池僅限編譯進 binary 的 Swift engines；reference catalog 15 家族無掛載機制。使用者裁決立即設計（「現在很多模型比 whisper 好」），consumer 選定 mlx-audio CLI。

Solution

PR #62（squash 2d1e456a）：external-engine-protocol（versioned JSON over argv spawn——絕不經 shell、timeout SIGTERM→SIGKILL＋pipe 解鎖、fail-loud 不 fallback）＋~/.bestasr/engines.json registry（無 config = byte-identical）＋BackendID.mlxAudio＋枚舉規則泛化（有 engine 的 backend 才枚舉）＋mlx-audio adapter（venv containment、transformers<4.54 pin）。

Verification Trail

• 端到端實測 ×3（comment）：registry → available → MLX parakeet 真轉錄逐字正確（~3.6s 端到端）；containment 活案例——首跑撞 mlx_lm↔transformers 上游不相容，錯誤 loud+attributed、修復全在 venv、host 零改動（移除 mlx-audio backend — 模型目錄降級為 reference catalog #20 的移除理由被實地隔離）
• Verify master report：PASS after 1 fix round（2 HIGH：spec-drift ×2 需求補全量 delta、segments 部分丟字改 batch-distrust；5 MEDIUM 修 4 留 1 residue）
• 271/271 綠（branch 時點）；merge 時六 backend union（與 中文 high-value ASR 家族評估 — FluidAudio 已內建 Paraformer/SenseVoice（零新依賴，優先於 MLX-Swift Qwen3-ASR）(follow-up from #35) #50 合流）288/288 綠

Process Note（誠實記錄）

merge-resolve commit 訊息誤用「resolve #51」觸發 GitHub auto-close、繞過本 gate——已 reopen 並走正規 close 流程（本 summary）。教訓：merge/conflict commit 的訊息同樣受 commit-issue-reference 紀律約束（close/fix/resolve 絕不鄰接 #N）。

Residue

• stdout streaming size cap（verify M5）；isAvailable 協定 probe；CLITests hermetic 化
• 協定 v2 空間：server mode（免 per-call model reload）；新工具 = BackendID 一個 case + registry entry