feat(gateway): 语音回合进编排+落库、G5 队列满带回身份、voice_output 归属（安卓 G5/C1/C3）
- G5：pending_full 增 clientMsgId/messageId（仅在可给出时出现、绝不新铸 id —— 队列满的拒绝发生在幂等键认领之前，代铸会让客户端重试被判重复而永远进不来）；另定向回发送者 {type:error,data:{code:chat_busy,...}}（与 REST 409 chat_busy 同码），广播帧照旧带同样的键供其它端对齐。
- C1：语音回合改走与文本同一条路径（编排器 Submit → 落库 → 流式 → 跨端同步），deviceId 走既有 withDeviceID、platform 走存储默认 web；未接编排器时保留旧直连路径。音频在回合结算处（persistAssistantReply → persistDocumentStatus → dispatchVoiceReply）合成并定向回原连接，回调各自 goroutine（TTS 延迟不拖住 pending_drain/session_idle）；续跑 FIFO 与转向注入两条路径都带走回调 ⇒ 忙时排队/被注入的语音也不丢音频。
- C3：voice_output 增 sessionId/deviceId；三处主动加码（按最优方向）：① voice_input 增可选 clientMsgId（语音也有幂等）② 不再拿 stopReason 顶替空正文当语音内容（空正文走 provider 降级信号）③ TTS 失败照旧回帧 + provider:silent（不静默）。
- 拆 chat_documents_test.go（510 行越界）→ 373 + 160，只搬不改（拆前后同 -run 过滤 PASS 集合逐条一致）。
- 主会话独立验收：隔离 worktree（HEAD + 本批次 11 文件）build/vet 绿、gateway -race 绿、全树 59 包（唯一红是既有负载 flake orchestration/TestSpawnTimeoutFromToolDefault）、linux+darwin 交叉编译绿；变异独立复现（pending_full 摘掉 clientMsgId ⇒ 3 条红）。
- 待办（已登记）：Docs/api-client.md 与 api-reference.md 的帧/字段登记随 v0.59 一并落笔（本批次刻意未动 Docs，避免与契约批次打架）。
This commit is contained in:
AskaEth committed
1 parent
72b95df22b
commit
3a01b4e236
11 files changed
+1123
-170
No files matched your search
@@ -5,8 +5,10 @@ import (
|
||||
"encoding/base64"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"strings"
|
||||
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/loop"
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/multimodal/voice"
|
||||
@@ -87,6 +89,10 @@ type voiceInputRequest struct {
|
||||
Text string `json:"text"`
|
||||
SessionID string `json:"sessionId"`
|
||||
DeviceID string `json:"deviceId,omitempty"`
|
||||
// ClientMsgID 是客户端自带的幂等键（协同 G4），与文本 chat 帧**同形**：
|
||||
// 同一个非空 clientMsgId 只承认第一条，重复到达不再落库、不再起回合
|
||||
// （回一条 chat_duplicate）。它可选，省略时行为与加入该字段之前逐字相同。
|
||||
ClientMsgID string `json:"clientMsgId,omitempty"`
|
||||
}
|
||||
|
||||
// SetVoice 注入 voice_input WS 路由所用的语音 STT/TTS 服务。
|
||||
@@ -99,9 +105,9 @@ func (s *Server) SetVoice(v VoiceService) {
|
||||
}
|
||||
|
||||
// handleVoiceInput 路由一个 voice_input 帧。未注入语音
|
||||
// 服务时它以明确错误应答（绝不崩溃）；否则它解码
|
||||
// 请求并异步运行 STT→chat→TTS 回合，使读泵绝不被
|
||||
// provider 延迟阻塞。
|
||||
// 服务时它以明确错误应答（绝不崩溃）；否则它异步跑这个语音
|
||||
// 回合（STT → 编排器 → 结算时的 TTS），使读泵绝不被
|
||||
// provider 或模型延迟阻塞。
|
||||
func (c *wsConn) handleVoiceInput(in wsInbound) {
|
||||
if c.h.voice == nil {
|
||||
c.enqueueJSON(wsEvent{Type: "error", Data: map[string]any{"message": "voice unavailable"}})
|
||||
@@ -116,14 +122,24 @@ func (c *wsConn) handleVoiceInput(in wsInbound) {
|
||||
go c.h.runVoiceTurn(c, req)
|
||||
}
|
||||
|
||||
// runVoiceTurn 驱动一个语音回合：STT（或提供的转写）→ agent chat
|
||||
// → TTS，然后向请求连接回复一个 voice_output 帧，
|
||||
// 携带 base64 音频加上识别出的转写与助手回复。
|
||||
// voiceLogSource 是语音路径的日志来源标签，使这条路径上的 WARN 能被追溯到
|
||||
// 具体子功能（AGENTS §10 的「日志必须标来源」）。
|
||||
const voiceLogSource = "gateway/voice"
|
||||
|
||||
// runVoiceTurn 驱动一个语音回合。转写（STT）仍在这里完成 —— 识别是语音入口
|
||||
// 自己的事；而**回合**从此刻起与文本回合走同一条路：进编排器 → 落库 → 流式 →
|
||||
// 跨端同步（协同 C1）。此前它直调 runner.Run，于是语音问过的事不进历史、不跨端、
|
||||
// 也不参与 busy/pending。
|
||||
//
|
||||
// 音频回复不在本函数等待：回合是异步完成的（可能排队、可能被中断），因此 TTS 与
|
||||
// 定向回帧由收尾回调（voiceReplySink）在回合**结算**时完成 —— 那是编排器唯一
|
||||
// 知道这个回合产出了什么的地方（与 S3.5 回写文档结论同一收尾点）。
|
||||
func (h *hub) runVoiceTurn(c *wsConn, req voiceInputRequest) {
|
||||
ctx := context.Background()
|
||||
// 把客户端的 deviceID 串下来，使持久化的语音回合被发送端
|
||||
// 标注（design/16 §4.5），与 ws_hub.go:240 一致。
|
||||
ctx = withDeviceID(ctx, req.DeviceID)
|
||||
// 把客户端的 deviceID 与可选幂等键串下来，使持久化的语音回合被发送端标注
|
||||
//（design/16 §4.5）并让重复到达的 clientMsgId 被判重（协同 G4）—— 与
|
||||
// ws_hub_turn.go 的文本路径同一机制。
|
||||
ctx = withClientMsgHint(withDeviceID(ctx, req.DeviceID), clientMsgHint{ClientMsgID: req.ClientMsgID})
|
||||
if req.SessionID == "" {
|
||||
req.SessionID = "web"
|
||||
}
|
||||
@@ -135,13 +151,13 @@ func (h *hub) runVoiceTurn(c *wsConn, req voiceInputRequest) {
|
||||
}
|
||||
audio, err := decodeVoiceAudio(req.Audio, req.Format)
|
||||
if err != nil {
|
||||
h.log.Warn("voice audio decode", "err", err)
|
||||
h.voiceLog().Warn("voice audio decode", "err", err, "session", req.SessionID)
|
||||
h.voiceError(c, "voice audio could not be decoded")
|
||||
return
|
||||
}
|
||||
stt, err := h.voice.STT(ctx, audio)
|
||||
if err != nil {
|
||||
h.log.Warn("voice stt", "err", err)
|
||||
h.voiceLog().Warn("voice stt", "err", err, "session", req.SessionID)
|
||||
h.voiceError(c, "voice transcription failed")
|
||||
return
|
||||
}
|
||||
@@ -155,38 +171,110 @@ func (h *hub) runVoiceTurn(c *wsConn, req voiceInputRequest) {
|
||||
h.voiceError(c, "chat service is not configured")
|
||||
return
|
||||
}
|
||||
// Web 主会话是主人的私密对话，因此它绑定
|
||||
// 全访问 env：记忆读+写，行为不变。角色来自该
|
||||
// 会话的绑定（design/22 §4.5）。
|
||||
// Web 主会话是主人的私密对话，因此它绑定全访问 env：记忆读+写，行为不变。
|
||||
// 角色来自该会话的绑定（design/22 §4.5）。
|
||||
env := h.envResolver.owner(ctx, req.SessionID)
|
||||
res, err := h.runner.Run(loop.WithSessionEnv(ctx, env), req.SessionID, []model.Message{model.TextMessage(model.RoleUser, transcript)})
|
||||
msgs := []model.Message{model.TextMessage(model.RoleUser, transcript)}
|
||||
// 两条「怎么回到这条连接」的通路都由本连接给出：收尾回调（音频回复，C1）与
|
||||
// 定向拒绝回调（队列满，G5）。编排器只把它们当成本回合的传输线索。
|
||||
ctx = withVoiceReplySink(ctx, h.voiceReplySink(c, req.SessionID, req.DeviceID, transcript))
|
||||
ctx = withPendingFullNotifier(ctx, c.notifyPendingFull)
|
||||
if h.orchestrator != nil {
|
||||
h.orchestrator.Submit(ctx, req.SessionID, msgs, env)
|
||||
return
|
||||
}
|
||||
h.runVoiceTurnDirect(ctx, c, req.SessionID, req.DeviceID, transcript, env)
|
||||
}
|
||||
|
||||
// runVoiceTurnDirect 是未接编排器时的旧直跑路径（未接线的构建 / 裸 hub 单元
|
||||
// 测试）：转写之后的回合直接跑 loop，然后立即合成并回音频。它与编排器路径共用
|
||||
// 同一个帧构造（emitVoiceOutput），因此两条路径的 voice_output 契约一致。
|
||||
func (h *hub) runVoiceTurnDirect(ctx context.Context, c *wsConn, sessionID, deviceID, transcript string, env loop.SessionEnv) {
|
||||
res, err := h.runner.Run(loop.WithSessionEnv(ctx, env), sessionID, []model.Message{model.TextMessage(model.RoleUser, transcript)})
|
||||
if err != nil {
|
||||
h.log.Warn("voice chat run", "err", err, "session", req.SessionID)
|
||||
h.voiceLog().Warn("voice chat run", "err", err, "session", sessionID, "device_id", deviceID)
|
||||
h.voiceError(c, "voice chat failed")
|
||||
return
|
||||
}
|
||||
reply := res.Text
|
||||
h.synthesizeVoiceReply(ctx, c, sessionID, deviceID, transcript, voiceReplyText(res))
|
||||
}
|
||||
|
||||
// voiceReplySink 返回本次语音请求的收尾回调：回合结算后取助手正文 → TTS →
|
||||
// **定向**回发起它的那根连接。它是 C1 的核心接线点 —— 回合异步完成，只有结算处
|
||||
// 知道助手正文。
|
||||
//
|
||||
// 连接已断（客户端走了）时记一条带来源的 WARN，绝不静默丢：那正是「静默成功但
|
||||
// 没声音」那类缺陷的温床（协同 C2 的教训）。
|
||||
func (h *hub) voiceReplySink(c *wsConn, sessionID, deviceID, transcript string) VoiceReplyFunc {
|
||||
return func(res *loop.Result) {
|
||||
if c.closed() {
|
||||
h.voiceLog().Warn("voice reply dropped", "reason", "connection closed", "session", sessionID, "device_id", deviceID)
|
||||
return
|
||||
}
|
||||
// 回合的 ctx 已随回合消亡，因此合成用全新的后台 context：音频是「回复已
|
||||
// 落库」之后的增强，不该被一次被取消的回合连带取消。
|
||||
h.synthesizeVoiceReply(context.Background(), c, sessionID, deviceID, transcript, voiceReplyText(res))
|
||||
}
|
||||
}
|
||||
|
||||
// synthesizeVoiceReply 把助手正文合成音频并定向回发起这条语音的连接
|
||||
// （协同 C1/C3）。三条纪律：
|
||||
// - TTS 失败或降级为空音频时**照旧回帧**并带既有 provider 降级信号，让客户端
|
||||
// 能提示「没生成声音」（绝不是只回一条错误帧就完事）；
|
||||
// - 没有助手正文（被取消 / 空回复）时不打一次无谓的 TTS，直接回降级帧 ——
|
||||
// 客户端总能看到这条语音回合的终点，而不是永远等一个不会来的 voice_output；
|
||||
// - 日志只带会话与设备 id，**绝不记正文/音频**。
|
||||
func (h *hub) synthesizeVoiceReply(ctx context.Context, c *wsConn, sessionID, deviceID, transcript, reply string) {
|
||||
if strings.TrimSpace(reply) == "" {
|
||||
reply = res.StopReason
|
||||
h.voiceLog().Warn("voice reply empty", "reason", "turn produced no text", "session", sessionID, "device_id", deviceID)
|
||||
emitVoiceOutput(c, sessionID, deviceID, transcript, "", voice.Audio{}, providerSignal("", true))
|
||||
return
|
||||
}
|
||||
audi, rung, err := ttsWithProvider(ctx, h.voice, reply)
|
||||
if err != nil {
|
||||
h.log.Warn("voice tts", "err", err)
|
||||
h.voiceError(c, "voice synthesis failed")
|
||||
h.voiceLog().Warn("voice tts", "err", err, "session", sessionID, "device_id", deviceID)
|
||||
emitVoiceOutput(c, sessionID, deviceID, transcript, reply, voice.Audio{}, providerSignal("", true))
|
||||
return
|
||||
}
|
||||
emitVoiceOutput(c, sessionID, deviceID, transcript, reply, audi, providerSignal(rung, len(audi.Data) == 0))
|
||||
}
|
||||
|
||||
// emitVoiceOutput 定向回一条 voice_output 帧（只有发起这条语音的连接收得到）。
|
||||
// 载荷在既有四键（audio/format/text/reply）之上**纯增量**地带上 sessionId 与
|
||||
// deviceId（协同 C3）：多端同时说话时客户端能区分归属。provider 只在没有真实
|
||||
// 音频时出现（既有降级信号），它不是业务错误。
|
||||
func emitVoiceOutput(c *wsConn, sessionID, deviceID, transcript, reply string, audi voice.Audio, provider string) {
|
||||
data := map[string]any{
|
||||
"audio": base64.StdEncoding.EncodeToString(audi.Data),
|
||||
"format": audi.Format,
|
||||
"text": transcript,
|
||||
"reply": reply,
|
||||
"audio": base64.StdEncoding.EncodeToString(audi.Data),
|
||||
"format": audi.Format,
|
||||
"text": transcript,
|
||||
"reply": reply,
|
||||
"sessionId": sessionID,
|
||||
}
|
||||
if sig := providerSignal(rung, len(audi.Data) == 0); sig != "" {
|
||||
data["provider"] = sig
|
||||
if deviceID != "" {
|
||||
data["deviceId"] = deviceID
|
||||
}
|
||||
if provider != "" {
|
||||
data["provider"] = provider
|
||||
}
|
||||
c.enqueueJSON(wsEvent{Type: wsVoiceOutput, Data: data})
|
||||
}
|
||||
|
||||
// voiceReplyText 返回一个回合的助手正文（没有结果时为空串）。空正文**不拿
|
||||
// stopReason 顶替**：把 "stop"/"idle" 这类内部状态合成成助手声音，客户端会把它
|
||||
// 当回复显示；空正文一律走既有的 provider 降级信号，如实说「没生成声音」。
|
||||
func voiceReplyText(res *loop.Result) string {
|
||||
if res == nil {
|
||||
return ""
|
||||
}
|
||||
return res.Text
|
||||
}
|
||||
|
||||
// voiceLog 返回带语音来源标签的 logger（AGENTS §10：日志必须标来源）。
|
||||
func (h *hub) voiceLog() *slog.Logger {
|
||||
return logger.WithSource(h.log, voiceLogSource)
|
||||
}
|
||||
|
||||
// voiceError 为失败的语音回合回复一个带类型的错误帧。
|
||||
func (h *hub) voiceError(c *wsConn, message string) {
|
||||
c.enqueueJSON(wsEvent{Type: "error", Data: map[string]any{"message": message}})
|
||||
|
||||
Reference in new issue
Block a user