W75 她的消息朗读 —— /audio/speech 只走 owner Bearer，字节嗅探 WAV，缓存落 media/
后端回执三十八 §3 点名「独立真机 Bearer 样例待安卓首次接入时顺手确证」，本批次就是
这次接入：在她的消息气泡外侧加一枚「朗读」图标，点按 → 剥标签取纯文本 → POST
/api/v1/audio/speech → 播放 WAV。只做手动点按，不做自动朗读 / 设置页开关 / 实时流。
## 契约（Cyrene_v2/Docs/api-client.md，2246 行）
- L126（§1.2 U6 表）、L1603（v0.97 补写）、L1609（v0.96 sessionId 增量）、
L561（416 非信封旁注，同句明说 /audio/speech 的 200 也不是信封）、
L2173（voice / format 不生效）。
- POST /api/v1/audio/speech，owner-only 双凭据门：Authorization: Bearer <owner JWT>
**或** X-API-Key，两分支同 authorize(RoleOwner)；无 / 无效 → 401，错误形状同 §4.1
{error:{code,message}} 信封。
- 请求体 {text, voice?, format?, instruction?, sessionId?}。voice 接受但不生效、
format 不生效；发音人由 sessionId 的生效人格解析（会话绑定 → 全局默认 → 配置 default），
**省略 sessionId 不等于没有角色**。
- 成功 200 + 原始音频字节（非信封），产物恒 WAV，**按字节嗅探，不要照抄 Content-Type**。
- 错误码：空 text → 400；500 voice_unavailable / tts_failed / tts_persona_unmapped /
tts_no_character / tts_empty（后者带响应头 X-Voice-Provider: silent）。
## 只走 Bearer，不加 API Key 输入框
主人 2026-10-26 拍板：本端 owner 已持有 JWT，再往设置里塞一个 API Key 输入框只是把
同一份凭据复制一遍、多一个会过期的状态。SpeechClient 的 tokenProvider 直接接
AuthManager 的当前 token，401 交给既有的 unauthorizedPolicy 收口。
## 落盘
新增 data/api/SpeechApi.kt、data/voice/SpeechClient.kt、domain/chat/VoiceSpeak.kt、
ui/chat/VoiceSpeak.kt；改 ChatViewModel / MessageBubble / ChatScreen。AppContainer 未动
（SpeechClient 在 ViewModel 里 lazy 构造，baseUrl 与 token 都取自 container.authManager）。
- 缓存名 tts_<sha256("sessionId\ntext")[:32]>.wav，落 VoiceStore.directory(cacheDir)
即 <cacheDir>/media/，**不进 documents/** —— 系统可回收，丢掉重下一份即可。
代价：服务端换发音人后同一段文字会命中旧音频，按 (sessionId, text) 寻址是刻意的。
- 字节嗅探 isWavBytes：size ≥ 12 + RIFF@0 + WAVE@8。200 + JSON 信封（哪怕
Content-Type 谎报 audio/wav）判 SpeechNotAudioException，且不落缓存。
- 两档失败：TtsFailure.Unconfigured 只认 tts_persona_unmapped / tts_no_character
两个 code（引导去设人格），其余一律 Soft（可重试）。不认识的 code 不猜，落 Soft。
- 失败只写 ttsClip.failure 气泡脚注，**不写 state.error 横幅** —— 朗读失败不该盖住聊天。
- 播放交给唯一的播放通道（ui.chat.VoicePlayer），键 tts:<messageId> 与语音副本的键
分得开 ⇒ 「念这一条」与「放这条消息的语音副本」天然互斥，同一时刻只有一个声音。
- 起播在渲染层那个 LaunchedEffect(ttsClip.clipId, file, autoPlay)：三键缺一不可 ——
「放 → 停 → 再点同一条」时 (clipId, file) 一对没变，只有 autoPlay 由假改真才能再点着。
## 状态机抽成纯函数（可测）
VM 拖不进 JVM 测试（要 AppContainer / viewModelScope，工程里没有 coroutines-test），
所以这条路的判据都落在两个纯函数上，VM 只负责循环 CAS + launch：
- ChatUiState.beginTtsSpeak(messageId, clipId)：返回 null = 这一次点击该被忽略
（同一条正在飞）。已落好的（file != null）算「再放一遍」、失败过的算「用户重试」，
两种都放行 —— 防抖判据只认 pending 这一种。
- ChatUiState.applyTtsOutcome(messageId, clipId, result)：clipId 已经不是这一格 ⇒
原样返回、一个字节都不写（否则「点了 B，界面在 A 下面报错」）。
## 验证
./gradlew.bat --offline compileDebugKotlin → BUILD SUCCESSFUL
./gradlew.bat --offline assembleDebug → BUILD SUCCESSFUL（38 tasks）
./gradlew.bat --offline testDebugUnitTest --rerun → BUILD SUCCESSFUL
138 suites / 1715 tests，0 failures / 0 errors / 0 skipped
（基线 134 / 1675；+4 suites +40 tests 全来自新增的
SpeechApiTest 4 / SpeechClientTest 8 / VoiceSpeakTest 16 / TtsSpeakStateTest 11）
SpeechApiTest 与 SpeechClientTest 都跑真 com.sun.net.httpserver.HttpServer + 真
OkHttp/Retrofit，不是 mock；SpeechClientTest 用 Files.createTempDirectory 验真落盘与
第二次同文本请求计数仍为 1。
未验：真机出声。已知取舍——请求在飞时图标 clickable(enabled = !speakPending) 点不动，
没有做「取消在飞请求」。
AskaEth
504c500e20