recommend/transcribe 的 --language auto 未偵測音訊語言，非英文內容被推薦英文專用後端

[kiki830621]

Problem

來源（使用者觀察，2026-07-18）：
「推薦引擎選了 fluid-parakeet——但這是陷阱。Parakeet 本質是歐語系／英文模型，不支援中文。……需要考量語言。」

recommend（以及共用同一套 backend selection 的 transcribe --backend auto）在 --language auto 下，不會先偵測音訊的實際語言就排序 backend。對一段中文（或任何非英文）內容，auto 直接推薦了 English-only 的 fluid-parakeet（NVIDIA parakeet-tdt-0.6b-v3，只支援英文／歐語系、不支援中文）。若照這個推薦轉錄，會產出羅馬拼音或亂碼、無法使用。

明確傳 --language zh 時，recommend 正確避開 parakeet、改推 whisperkit / large-v3-turbo — 代表 backend-selection 邏輯本身有語言感知能力，缺的是 auto 沒有把「偵測到的內容語言」餵進排序，而是退回英文偏置的排序。

Type

bug

Expected

--language auto 應該先對音訊做語言偵測（例如抽前 ~30 秒判語言，如 Whisper 的做法），再用偵測到的語言去挑 backend；或至少在無法偵測時明確警告 auto 退回了語言無關（English-biased）的排序、可能推薦語言不相容的後端。

Actual

--language auto 略過語言偵測，等同把音訊當英文排序，對非英文內容推薦 English-only 後端（parakeet），且無任何警告。

Evidence

同一段非英文（華語為主、夾英文術語）音訊，bestasr recommend 在不同 --language 下的推薦：

--language	推薦 backend	是否適合中文
auto	fluid-parakeet (0.6b-v3)	❌ 英文專用，中文會崩
zh	whisperkit (large-v3-turbo, CER 12.9%)	✅ 正確
en	fluid-parakeet	✅（英文對照組）

auto 與 en 給出相同結果，佐證 auto 實際上是 English-biased、沒做語言偵測。

Impact

auto 是使用者最可能採用的預設路徑（transcribe 不指定 --backend/--language 時即走此路）。非英文使用者若信任推薦，會拿到語言不相容的後端 → 產出無法使用的逐字稿，且沒有任何提示指出哪裡錯了。Workaround 是永遠明確指定 --language <code>，但這違背 auto 的用意。

觀察環境

• bestasr CLI 0.12.0（.build/release）；MCP wrapper 為 0.14.0 — 建議對最新 build 覆驗 auto 的偵測路徑。
• 重現：任一非英文（如華語）音訊，比較 bestasr recommend --language auto <audio> 與 --language zh <audio> 輸出 JSON 的 backend 欄。

相關（另立追蹤，非本 issue 範圍）

實測同一段 ~62 分鐘長檔，transcribe --backend fluid-sensevoice 以下列訊息硬失敗：

error: fluid-sensevoice failed to transcribe: <normalized>.wav: Size (59557867) of dimension (1) is not in allowed range (3200..480000)

SenseVoice 的 30 秒固定窗（480000 samples @ 16kHz）未被切段處理。這是 transcribe 長音訊處理的另一個獨立問題（不同 code path），若需要可另開 issue 追蹤。

[kiki830621]

Diagnosis

Type

bug

Root Cause / Analysis

recommend 流程從頭到尾沒有「讀音訊內容判語言」的步驟。--language auto 在第一關就被正規化成 nil，而 Router 裡 requestedLanguage == nil 的語意是「不對語言做任何過濾」，於是所有 backend 的 benchmark 記錄一起競爭；parakeet 那筆英文低 WER / 高 realtime 的記錄在全域排名奪冠 → 即使餵中文也推 fluid-parakeet。這正是 auto 與 en 結果相同、zh 才不同的原因。

證據鏈（file:line 皆 repo-relative）：

1. --language 預設 "auto"：Sources/bestasr/BestASRCommand.swift:258-259（SelectionOptions.language）；resolved() 原封塞進 SelectionRequest（:271，auto 字串未在此轉掉）。

2. recommendJSON 先 probe 音訊：Sources/BestASRKit/CommandCore.swift:250-253。

3. AudioProber.probe 把 requested 語言丟 resolver：Sources/BestASRKit/Detect/AudioProber.swift:30。probe 只讀 duration / format / sampleRate / channels，完全不碰音訊內容、不判語言。

4. 關鍵轉換點：Sources/BestASRKit/Detect/Language.swift:7-12 的 LanguageResolver.resolve 把 auto（與空字串）→ nil。

5. 語言過濾被短路的那一行：Sources/BestASRKit/Router/Router.swift:83

   && (requestedLanguage == nil || record.language == requestedLanguage)

   requestedLanguage == nil（即 auto）時整條恆為 true → 過濾關閉，所有語言的 benchmark 記錄混池競爭；Ranking.rank（Router.swift:104）挑全域最高分 → parakeet 英文記錄勝出。--language en 只留 en 記錄、parakeet en 仍最高 → 同結果；只有 zh 把池限縮到 zh，parakeet 無 zh 列而落選 → whisperkit 勝出。

6. MCP 介面同一 bug：Sources/BestASRMCPCore/Server.swift:400-403 的 languageOrNil 也是 auto → nil，餵同一個 Router.recommend（Server.swift:268 / :367）。

兩個加重根因的事實：

• backend 有「支援語言」metadata 但 routing 完全沒用：Sources/BestASRKit/Store/StoreTables.swift:47 有 languages: [String]，parakeet 在 Sources/BestASRKit/Models/ModelGrid.swift:52-56 標成 ["multi"]。但 Router / Ranking 從不讀 .languages（唯二 reader 是建構子與 GUI 下拉選單）；且 parakeet 被誤標 "multi"（實際是歐語系、不含 zh），就算拿來過濾也會錯放行。
• 有語言偵測程式碼但在錯的階段：唯一的偵測在 Sources/BestASRKit/Engines/WhisperKitEngine.swift:80（detectLanguage = language == nil），是轉錄階段、backend 選定之後才跑，回不去影響 recommend。auto 一旦選了 parakeet，根本走不到這行。

Impact

• 影響檔案（預期改動範圍）：Sources/BestASRKit/CommandCore.swift（recommend 前置）、Sources/BestASRKit/Detect/AudioProber.swift（新增 detect 能力）、Sources/BestASRKit/Router/Router.swift（候選過濾）、Sources/BestASRMCPCore/Server.swift（MCP 同路徑）；可能含 Sources/BestASRKit/Models/ModelGrid.swift（修 parakeet 語言標記）。
• 影響使用者流程：所有走 --language auto（= 未指定即預設）的非英文轉錄／推薦。

Strategy

三個候選方向（Plan 階段拍板）：

• A（治本，加語言偵測前置）：CommandCore.recommendJSON / resolveRecommendation 在 audio.language == nil（auto）時，先抽前 N 秒跑輕量語言偵測（複用 WhisperKit detectLanguage 或給 AudioProber 加 detect 函式），得偵測語言後再以該語言呼叫 Router.recommend，讓 Router.swift:83 的過濾生效。唯一能讓 auto 中文正確路由到 whisperkit 的作法。
• B（治標，用宣告 metadata 擋不支援語言）：Router 候選過濾（:77-85）引入 ModelGrid.languages，並修正 parakeet 標記（ModelGrid.swift:56 ["multi"] → 實際歐語集）。但 B 仍需知道音訊語言，不能單獨對 auto 生效，只能搭 A。
• 警告版（過渡）：Router 兩條 return 前，requestedLanguage == nil 且選中 backend 宣告語言不含偵測語言時，往 warnings 加一則「auto 未做語言偵測，可能選到不支援當前語言的後端」（warnings 為既有機制）。
• MCP 路徑（Server.swift）與 CLI 同步套用同一修法。
• 加測試：非英文音訊在 --language auto 下不得推薦 English-only 後端。

Conflict Class

C_shared_module_coord — 修法動到共享的 recommendation 路徑（Router.recommend / AudioProber / CommandCore.resolveRecommendation），且此路徑同時被 CLI（CommandCore）與 MCP（BestASRMCPCore/Server.swift）消費，兩邊須協調一致。

Complexity

Plan

觸發信號：

• Layer P「Decision-heavy with 2+ valid approaches」 — A（語言偵測）vs B（metadata 過濾）vs 警告版，選哪個影響 code shape。
• Hard gate Re-platform bestASR to Swift (Apple Silicon-first, WhisperKit core) #2「動到 shared abstraction」 — Router.recommend / AudioProber 被 CLI + MCP 兩個 caller 共用，修法必須 family-wide 涵蓋兩邊（CLI recommend + MCP recommend）。

Risks

• 語言偵測前置會增加 recommend 延遲（抽前 N 秒 + 一次輕量 decode），需權衡取樣長度 vs 準確度。
• parakeet 現標 ["multi"]，改成實際支援集時要確認不誤傷真的支援的語言。
• WhisperKit detectLanguage 對 code-switching（中英混合）本身可能不穩，需決定偵測到 mixed 時的 fallback（偏主語言？偏多語後端？）。

Residue

(none) — issue 意圖（auto 應偵測語言再挑後端）可完整 operationalize；唯一未決的「A / B / 警告版選哪個」屬 Strategy 待拍板，已留給 Plan。

[kiki830621]

Implemented + verified（aa14117）

依 diagnosis 的 Strategy A + B + warning fallback 實作：

• A（治本）：Detect/LanguageDetector.swift 新增 AudioLanguageDetecting；auto 解析為 nil 時，CommandCore.resolveAutoLanguage 以 WhisperKit tiny 對前 30 秒偵測語言再進 Router.recommend（CLI 與 MCP 共用同一路徑）。偵測失敗 → 退回語言無關排序＋明確 warning，不靜默。
• B（metadata + gate）：ModelGrid 兩個 parakeet 列由 ["multi"] 改為實際的英文＋24 歐語（NVIDIA model card）；Router.declaredSupport 讓自主排序排除不宣告支援目標語言的 model。明確 --backend 鎖定豁免 gate（與 quality-floor 同一 doctrine：使用者意志優先），但附支援性 warning。

真實世界驗收（原始重現案例，62 分鐘華語音訊 + --language auto）：

	backend	reasons
修正前	fluid-parakeet ❌	（無語言偵測）
修正後	whisperkit ✅	detected language 'zh' from the first 30s of audio (--language auto)

測試：新增 LanguageRoutingTests（8 tests：catalog 修正、gate 接受/拒絕/fail-open、Router zh 整合、lock 豁免＋warning、偵測 fallback 三態）全綠；RouterCrossFamilyTests 等既有 Router suites 34/34 綠；全套回歸通過。

待使用者確認後 close。

[kiki830621]

Closing Summary

Problem

recommend（與共用同一 backend-selection 的 transcribe --backend auto）在 --language auto 下，對非英文音訊推薦了 English-only 的 fluid-parakeet——若照推薦轉錄會產出羅馬拼音/亂碼。auto 是未指定時的預設路徑，非英文使用者最容易踩到。

Root Cause

--language auto 在 LanguageResolver.resolve（Detect/Language.swift）被正規化成 nil；Router.recommend（Router.swift:83）的候選過濾 (requestedLanguage == nil || record.language == requestedLanguage) 在 nil 時恆為 true→ 語言過濾整個短路，所有語言的 benchmark 記錄混池競爭，parakeet 的英文低-WER 記錄全域奪冠。這正是 auto == en ≠ zh 的機制。加重根因：backend 有 languages metadata 但 Router 從不讀它，且 parakeet 還被誤標 ["multi"]。

Solution

Strategy A + B + warning fallback：

• A（治本）：Detect/LanguageDetector.swift 新增 AudioLanguageDetecting protocol；CommandCore.resolveAutoLanguage 在 auto 解析為 nil 時，以 WhisperKit tiny 對前 30 秒偵測語言再進 Router.recommend（CLI + MCP 共用同一路徑）。偵測失敗 → 退回語言無關排序 + 明確 warning，不靜默。
• B（metadata + gate）：ModelGrid 兩個 parakeet 列由 ["multi"] 改為實際的英文＋24 歐語（NVIDIA model card）；Router.declaredSupport 讓自主排序排除不宣告支援目標語言的 model。明確 --backend 鎖定豁免 gate（quality-floor doctrine）但附支援性 warning。

Verification

• 真實世界驗收（原始重現案例，62 分鐘華語音訊 + --language auto）：修正前 → fluid-parakeet ❌；修正後 → whisperkit，reasons 含 detected language 'zh' from the first 30s of audio。✅
• 社群 benchmark 首批真實數字獨立佐證（bestASR-bench leaderboard）：zh | fluid-parakeet | CER 190% @ 102x realtime——parakeet 在中文上錯得徹底，正是這條 gate 該擋下的。
• 新增 LanguageRoutingTests（8 tests）+ 既有 Router suites 34/34 + 全套回歸 383/383 綠。

Changes

• aa14117 feat: language-aware routing for --language auto (recommend/transcribe 的 --language auto 未偵測音訊語言，非英文內容被推薦英文專用後端 #105)