feature: speaker identification — SPEAKER_N 對映 names[] 真名（兩階段之二，blocked by #25）

[kiki830621]

Problem

兩階段裁決的第二階段（sibling of #25）：#25 交付 diarization（SPEAKER_1/2 聲學分離）後，本 issue 追蹤 speaker identification——對照已知聲紋辨識出「具體是誰」，把 SPEAKER_N 自動映射成 context names[] 真名。

Type

feature

Expected

使用者可為 context names[] 的人提供 enrollment 聲紋樣本；轉寫時 SPEAKER_N 自動對映真名（含信心門檻與未知說話者 fallback）。

Actual

（依 #25 交付後）僅有匿名 SPEAKER_N 標記；真名對齊靠 srt-proofread 語意推測。

Impact

• enrollment 樣本的存放/管理（隱私面：聲紋屬敏感生物特徵——設計需明確 local-only 邊界）
• speaker embedding 比對 + 信心門檻
• 依賴 feature: speaker diarization — 多說話者錄音的說話人分離/標記（現況：無聲學層辨識，僅 agent 端語意標註） #25 的 diarization 基礎

Blocked by #25

Clarity Surface(idd-clarify run 2026-07-03T07:05:00Z)

Type	Source	Suggested canonical	Status
ambiguity	「提供 enrollment 聲紋樣本」的介面	(a) 專用 CLI 指令（新 surface + 狀態管理）vs (b) context-dir 慣例資料夾 voices/<name>.wav（零新指令、沿 context-calibration 資料夾哲學、三層 precedence 免費繼承）	resolved @ 2026-07-03T07:05:00Z (reason: 採 (b)——issue 本文即綁定 context names[]；design 決策、與使用者既有裁決一致)
ambiguity	聲紋「儲存」形式	原始音檔（使用者自管、可讀可刪）vs 預計算 embedding（另一格式的生物特徵、需失效管理）	resolved @ 2026-07-03T07:05:00Z (reason: 使用者放原始音檔、embedding 運行時計算——local-only 鐵律下音檔最透明；快取為後續可選)

---

Current Status

• Phase: closed
• Updated: 2026-07-03
• Complexity: Spectra · Conflict Class: A_parallel_safe
• Verify: PASS post-fix（2 輪；DA 抓 stale-diff + precision 缺口；193/193；live 六斷言）
• Implementation: ba4a165 on idd/26-speaker-identification（voices/ 慣例 + 自控 post-hoc embedding 比對；191/191；live 半剖驗證 TestVoice 命中）
• Diagnosis: feature: speaker identification — SPEAKER_N 對映 names[] 真名（兩階段之二，blocked by #25） #26 (comment)

[kiki830621]

Diagnosis

Root Cause

（feature gap，#25 的第二階段）diarization 已交付匿名 SPEAKER_N；「這是誰」需要 enrollment 聲紋比對。

技術路徑（live probe v0.15.4 原始碼）

FluidAudio 原生支援 known-speaker recognition——不需自建比對器：

• Speaker(id:name:currentEmbedding:) + diarizer.speakerManager.initializeKnownSpeakers([...]) 預載後，performCompleteDiarization 回的 speakerId 直接就是註冊名（cosine distance < speakerThreshold 0.65 SDK 內建；SpeakerUtilities.cosineDistance public）
• Enrollment embedding：對註冊音檔跑同一 diarizer → speakerDatabase 取主導 speaker 的 embedding

Strategy

Spectra（diarization spec MODIFIED + context-calibration spec MODIFIED）：

• Enrollment 慣例（clarity 已錨定）：resolved context dir 下 voices/<name>.wav——檔名 stem = 輸出標籤名；零新 CLI surface；三層 precedence 免費繼承；local-only 鐵律進 spec（聲紋屬敏感生物特徵，任何工具不得上傳/commit——與 raw-第三方內容同級）
• SpeakerEnroller：enrollment 音檔 → 主導 embedding（diarizer 复用）
• DiarizationEngine.diarize(audioPath:knownSpeakers:)：預載 known speakers → turns 的 speaker 欄位直接帶名
• SpeakerAssigner 擴充：turn.speaker ∈ 註冊名 → 標籤原樣；未知 → 既有 SPEAKER_N ordinal（fallback 不變）
• 觸發語意：--diarize 且 resolved context dir 有 voices/ → identification 自動啟用（使用者放了聲紋即意圖）；--explain 註記啟用狀態與命中數
• TDD：assigner 混合標籤（名字通過/未知 ordinal/名字不佔用 ordinal 序號）；enroller/engine seam 測試（注入縫已存在）
• Live 驗證（半剖法，零新下載）：enrollment = FEMALE 錄音前半；fixture = male+gap+female（feature: speaker diarization — 多說話者錄音的說話人分離/標記（現況：無聲學層辨識，僅 agent 端語意標註） #25 pinned）→ female cues 標註冊名、male 維持 SPEAKER_1（同錄音後半 = 同人保證，繞開 FLEURS 匿名性）
• scripts/validate-diarization.sh 延伸 identification 斷言

✅ 全項於 close 時勾銷——PR #28（193/193 tests；validate script live 六斷言；identification 改自控 post-hoc 比對）

Complexity

Spectra

Conflict Class

A_parallel_safe

Residue

• speakerThreshold 可調性（先用 SDK 預設 0.65 + design 記載；有真實誤匹配再開參數）
• embedding 快取（enrollment 每跑重算——短音檔成本低；量大再議）

[kiki830621]

Verify: #26

Engine

dynamic-workflow backend — 6/6（4 lens + DA + Codex/gpt-5.5）, model: opus。Process note（誠實揭露）：diff 送的是 feature commit ba4a165 單獨，而 verify 執行期間我平行 commit 了 84f208f（4-lens fixes）——DA 的 HIGH 正確識別此 stale-diff 現象（~8 findings 已在 HEAD 修掉）。教訓：verify 跑時不應平行改同一 branch；應 diff 完整 branch HEAD。

要求覆蓋率

6 spec scenarios（含 named-label / stranger-ordinal / no-voices baseline）+ 純函式 identifier 全覆蓋。

Findings（合併後 32 筆，triage）

類	內容	狀態
DA HIGH #1	ensemble 診斷 stale diff——~8 findings HEAD 已修	Acknowledged（流程教訓，非缺陷；下述逐項對應）
#2/#4/#22 spec-triad pre-load	spec+design 於 84f208f 已改 post-hoc；proposal.md 漏改	Fixed（round-2 76b91af：三檔一致）
#3/#16/#20 local-only enforcement	84f208f 加 .gitignore **/voices/ + skill 鐵律	Fixed（+ round-2 補 validate temp-copy trap cleanup）
#6/#21 corrupt file aborts	84f208f per-voice warn-continue	Fixed
#7 validate silent-skip	84f208f exit 1（#18 教訓）	Fixed
#9/#18 N enrolled count	84f208f N/M enrolled	Fixed
#19 filename label unescaped	84f208f sanitizeLabel	Fixed
#5/#12 many-to-one 塌陷	D6 裁定行為刻意（合併同人 cluster），但 disclosure 用 Set dedup 隱藏	Fixed（round-2）：explain 改 N name(s) matched across M diarized speaker(s)——塌陷可見；塌陷揭露單元測試
#8 DA precision 未驗證	所有 lens 只查 recall，沒查「陌生人不被誤標」	Fixed（round-2）：validate 加 precision 斷言（male cue 不含 TestVoice）
#14 validate temp-copy leak + under-cover	biometric copy 在 transcribe 失敗時殘留 /tmp；no-voices 路徑未斷言	Fixed（round-2）：trap RETURN/EXIT cleanup + no-voices==baseline 斷言
#10/#32 first-segment embedding	用第一 segment 非代表性 centroid	Fixed（round-2）：改用各 speaker 最長 segment embedding（提升 precision + 緩解假匹配）
#23/#13/#26 SPEAKER_N spoofing	enrollment 檔名撞 ordinal	Fixed（round-2）：^SPEAKER_\d+$ 檔名 warn
#15 DiarizationOutput API break	#25 的 [SpeakerTurn] → DiarizationOutput	Noted：BestASRKit 內部引擎、CLI 唯一 consumer；同一 pre-#26-release 週期
#24 DA challenge many-to-one	「MEDIUM overstated——D6 已文件化」	Accepted：行為保留、僅補揭露（非改行為）
#25/#31 DA challenges	try? masking unreachable / temp first-match 有 digest pin 兜底	Accepted（低風險）
其餘 INFO	injection scan clean、voices reserved 覆蓋 subdirectory-skip、context double-load	Noted

In-scope fixes

3 commits：ba4a165（TDD 實作）+ 84f208f（4-lens fixes）+ 76b91af（DA/codex round-2）。193/193 綠。

執行證據

scripts/validate-diarization.sh live 六斷言全過：9.30s 切換 / jfk 陰性 / off 潔淨 / recall（TestVoice 命中）/ precision（陌生人不誤標）/ no-voices==baseline。

Residue

• centroid embedding 可再精進（現用最長 segment，已優於首 fragment；平均 centroid 為未來可選）
• speakerThreshold 0.65 可調性（SDK 預設 + design 記載；誤匹配實證再開參數）

Result

PASS（verify-gated, post-fix） — 0 blocking。本輪教訓：verify 跑時平行改同一 branch 會製造 stale-diff——DA 的 HIGH 正是抓這個；此後 verify 前凍結 branch，或改 diff 完整 HEAD。identification 的 precision 缺口（只驗 recall）也是好提醒：辨識類功能必須雙向驗（認得出 + 不誤認）。

[kiki830621]

Closing Summary

Problem

（#25 diarization ship 後的第二階段）匿名 SPEAKER_N 不夠——會議/上課要「這是誰」。使用者兩階段裁決之二。

Root Cause

（feature gap）需要 enrollment 聲紋 → 比對辨識。

Solution

（PR #28，squash b6559ef）bestasr transcribe --diarize + resolved context dir 的 voices/<name>.<ext> 聲紋：

• 零新 CLI surface——放聲紋檔進 voices/ 即介面（三層 context precedence 免費繼承；clarity 裁決慣例資料夾勝過專用指令）
• 自控 post-hoc cosine 比對（純函式 SpeakerIdentifier.resolve）：設計修正——實測 FluidAudio 的 initializeKnownSpeakers 預載路徑不進 DiarizerManager clustering 決策（主 run distance=inf），遂不賭 SDK 內部、改走可完全單元測試的自控比對
• SpeakerAssigner knownNames（名字原樣、不佔 ordinal）；enrollment embedding 取各 speaker 最長 segment（代表性優於首 fragment）
• 隱私鐵律三層防護：.gitignore **/voices/ + context-ingest skill 鐵律禁區 + spec 級 SHALL NOT transmit（聲紋屬敏感生物特徵，同 raw 第三方內容處置）
• specs：diarization MODIFIED（named labels + local-only）、context-calibration MODIFIED（voices/ reserved folder）

Verification

TDD（193/193 綠）。6-AI verify（master report：#26 issuecomment-4872303442）→ 32 findings、兩輪修復：DA 的 HIGH 正確識別我在 verify 執行期平行 commit 造成的 stale-diff（~8 findings HEAD 已修）；round-2 補齊 HEAD 未修的真缺陷——spec-triad 一致（漏改的 proposal）、many-to-one disclosure 揭露（D6 保留行為、不隱藏塌陷）、precision 驗證（陌生人不誤標，補 recall-only 缺口）、biometric temp-copy trap、最長-segment embedding。scripts/validate-diarization.sh live 六斷言全過（9.30s 切換 / jfk 陰性 / off 潔淨 / recall / precision / no-voices==baseline）。

Changes

ba4a165（實作）+ 84f208f（4-lens fixes）+ 76b91af（round-2）→ PR #28。

• 註 1：merge-completeness rc=3 = squash intra-branch supersession 假陽性（第 9 次同型；內容機械驗證：SpeakerIdentifier + across-disclosure + precision 斷言 + post-hoc proposal 皆在 main）
• 註 2：DiarizationEngine.diarize 回傳型別由 feature: speaker diarization — 多說話者錄音的說話人分離/標記（現況：無聲學層辨識，僅 agent 端語意標註） #25 的 [SpeakerTurn] 變 DiarizationOutput{turns, embeddings}——BestASRKit 內部引擎、CLI 唯一 consumer，同一 pre-feature: speaker identification — SPEAKER_N 對映 names[] 真名（兩階段之二，blocked by #25） #26-release 週期，非對外破壞

Residue

• centroid embedding 精進（現用最長 segment，優於首 fragment；平均 centroid 未來可選）
• speakerThreshold 0.65 可調性（SDK 預設 + design 記載；誤匹配實證再開）
• 兩階段說話人辨識 arc 至此完成（feature: speaker diarization — 多說話者錄音的說話人分離/標記（現況：無聲學層辨識，僅 agent 端語意標註） #25 diarization + feature: speaker identification — SPEAKER_N 對映 names[] 真名（兩階段之二，blocked by #25） #26 identification）

Distribution Sync

chain 0.7.0：完成兩階段辨識的 minor 版；四版本面一次到位（CHANGELOG / BestASRVersion.current / plugin.json / marketplace.json，各帶 assert）+ 全套件驗證。