docs(gateway): gateway 剩余文件注释改中文（逐行 1:1，代码零字节改动）
主人 2026-10-03 拍板「注释一律中文」；gateway 至此整包注释中文化完成（本会话共 3 批： 已推库 16 个文件 + 本批剩余文件）。 校验：机械校验（非注释改动行）= 空；剥注释后代码文本逐行比对全等（不一致文件数 0）； 全树 go test ./... 58 包 ok / 0 FAIL；交叉编译绿。
This commit is contained in:
AskaEth committed
1 parent
91e8d7a029
commit
074ffc4ebf
73 files changed
+2529
-2529
No files matched your search
@@ -12,38 +12,38 @@ import (
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/multimodal/voice"
|
||||
)
|
||||
|
||||
// VoiceService runs speech-to-text and text-to-speech for the voice_input WS
|
||||
// route. *voice.Chain (the degrading provider chain) and *voice.Service (the
|
||||
// background worker pool) both satisfy it. It is nil-tolerant: the voice route
|
||||
// replies with a clear error when no service is injected.
|
||||
// VoiceService 为 voice_input WS 路由运行语音转文本与
|
||||
// 文本转语音。*voice.Chain（降级 provider 链）与 *voice.Service
|
||||
// （后台工作池）都满足它。它容忍 nil：未注入服务时
|
||||
// voice 路由返回明确的错误。
|
||||
type VoiceService interface {
|
||||
// STT transcribes audio to text.
|
||||
// STT 把音频转写为文本。
|
||||
STT(ctx context.Context, audio voice.Audio) (string, error)
|
||||
// TTS synthesizes audio from text. A per-request emotion/tone instruction may
|
||||
// be threaded through ctx (voice.WithTTSInstruction) to override the configured
|
||||
// VOICE_TTS_INSTRUCTION for one call.
|
||||
// TTS 从文本合成音频。每请求的情绪/语气指令可以
|
||||
// 经 ctx（voice.WithTTSInstruction）串下来，以在单次调用中覆盖
|
||||
// 已配置的 VOICE_TTS_INSTRUCTION。
|
||||
TTS(ctx context.Context, text string) (voice.Audio, error)
|
||||
// CloneVoice creates a custom voice (声音复刻 create_voice) from a public
|
||||
// reference audio URL and returns its voice_id.
|
||||
// CloneVoice 从公开参考音频 URL 创建自定义音色（声音复刻
|
||||
// create_voice）并返回其 voice_id。
|
||||
CloneVoice(ctx context.Context, referenceURL, prefix string) (string, error)
|
||||
}
|
||||
|
||||
// voiceProviderHeader is the response header carrying the provider rung on the
|
||||
// binary /api/v1/audio/speech response, where a JSON signal field cannot be added.
|
||||
// voiceProviderHeader 是二进制 /api/v1/audio/speech 响应上携带 provider
|
||||
// 档位的响应头，因为那里无法添加 JSON 信号字段。
|
||||
const voiceProviderHeader = "X-Voice-Provider"
|
||||
|
||||
// voiceProviderReporter is the optional extension of VoiceService: a service that
|
||||
// can report which provider rung (cloud / local / edge-tts / espeak / silent)
|
||||
// produced a result. *voice.Chain and *voice.Service implement it; a custom
|
||||
// VoiceService that does not is still supported and falls back to the plain
|
||||
// STT/TTS methods with no reported rung.
|
||||
// voiceProviderReporter 是 VoiceService 的可选扩展：一个能报告
|
||||
// 结果是哪个 provider 档位（cloud / local / edge-tts / espeak / silent）
|
||||
// 产出的服务。*voice.Chain 与 *voice.Service 实现了它；未实现的
|
||||
// 自定义 VoiceService 仍被支持，回退到朴素的
|
||||
// STT/TTS 方法且不报告档位。
|
||||
type voiceProviderReporter interface {
|
||||
STTWithProvider(ctx context.Context, audio voice.Audio) (string, string, error)
|
||||
TTSWithProvider(ctx context.Context, text string) (voice.Audio, string, error)
|
||||
}
|
||||
|
||||
// sttWithProvider runs STT and returns the transcript plus the provider rung that
|
||||
// served it ("" when the injected service cannot report one).
|
||||
// sttWithProvider 运行 STT 并返回转写文本加上服务它的
|
||||
// provider 档位（注入的服务无法报告时为 ""）。
|
||||
func sttWithProvider(ctx context.Context, v VoiceService, audio voice.Audio) (string, string, error) {
|
||||
if r, ok := v.(voiceProviderReporter); ok {
|
||||
return r.STTWithProvider(ctx, audio)
|
||||
@@ -52,8 +52,8 @@ func sttWithProvider(ctx context.Context, v VoiceService, audio voice.Audio) (st
|
||||
return text, "", err
|
||||
}
|
||||
|
||||
// ttsWithProvider runs TTS and returns the audio plus the provider rung that
|
||||
// served it.
|
||||
// ttsWithProvider 运行 TTS 并返回音频加上服务它的
|
||||
// provider 档位。
|
||||
func ttsWithProvider(ctx context.Context, v VoiceService, text string) (voice.Audio, string, error) {
|
||||
if r, ok := v.(voiceProviderReporter); ok {
|
||||
return r.TTSWithProvider(ctx, text)
|
||||
@@ -62,10 +62,10 @@ func ttsWithProvider(ctx context.Context, v VoiceService, text string) (voice.Au
|
||||
return audio, "", err
|
||||
}
|
||||
|
||||
// providerSignal returns the "provider" degraded signal for a voice result: the
|
||||
// actual provider rung when the result is empty, "silent" when the rung is
|
||||
// unknown, and "" (omit the field) when the result carries real text/audio. It
|
||||
// only flags "no real speech/audio"; it is never a business error.
|
||||
// providerSignal 为语音结果返回 "provider" 降级信号：结果为
|
||||
// 空时返回实际 provider 档位，档位未知时返回 "silent"，
|
||||
// 而结果携带真实文本/音频时返回 ""（省略该字段）。它
|
||||
// 只标记「没有真实语音/音频」；它绝不是业务错误。
|
||||
func providerSignal(rung string, empty bool) string {
|
||||
if !empty {
|
||||
return ""
|
||||
@@ -76,11 +76,11 @@ func providerSignal(rung string, empty bool) string {
|
||||
return rung
|
||||
}
|
||||
|
||||
// voiceInputRequest is the decoded payload of a voice_input frame. Audio is a
|
||||
// base64 (or data: URI) audio blob; Format is its encoding ("wav"/"mp3"/"ogg");
|
||||
// Text overrides STT when present (a client that already transcribed can skip
|
||||
// recognition); SessionID defaults to "web"; DeviceID is the client-produced
|
||||
// end identifier (design/16 §4.5) threaded into the persisted voice turn.
|
||||
// voiceInputRequest 是 voice_input 帧解码后的载荷。Audio 是
|
||||
// base64（或 data: URI）音频块；Format 是其编码（"wav"/"mp3"/"ogg"）；
|
||||
// Text 存在时覆盖 STT（已自行转写的客户端可跳过
|
||||
// 识别）；SessionID 默认 "web"；DeviceID 是客户端产出的
|
||||
// 端标识（design/16 §4.5），串进持久化的语音回合。
|
||||
type voiceInputRequest struct {
|
||||
Audio string `json:"audio"`
|
||||
Format string `json:"format"`
|
||||
@@ -89,19 +89,19 @@ type voiceInputRequest struct {
|
||||
DeviceID string `json:"deviceId,omitempty"`
|
||||
}
|
||||
|
||||
// SetVoice injects the voice STT/TTS service used by the voice_input WS route.
|
||||
// It is the gateway's exposed injection point so the composition root can wire a
|
||||
// *voice.Chain or *voice.Service without touching Deps. A nil value disables the
|
||||
// route (it replies with a clear error).
|
||||
// SetVoice 注入 voice_input WS 路由所用的语音 STT/TTS 服务。
|
||||
// 它是网关暴露的注入点，使组合根能接线 *voice.Chain 或
|
||||
// *voice.Service 而无需触碰 Deps。nil 值会禁用该
|
||||
// 路由（它以明确错误应答）。
|
||||
func (s *Server) SetVoice(v VoiceService) {
|
||||
s.voice = v
|
||||
s.hub.voice = v
|
||||
}
|
||||
|
||||
// handleVoiceInput routes one voice_input frame. Without an injected voice
|
||||
// service it replies with a clear error (never a crash); otherwise it decodes the
|
||||
// request and runs the STT→chat→TTS turn asynchronously so the read pump is never
|
||||
// blocked by provider latency.
|
||||
// handleVoiceInput 路由一个 voice_input 帧。未注入语音
|
||||
// 服务时它以明确错误应答（绝不崩溃）；否则它解码
|
||||
// 请求并异步运行 STT→chat→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,13 +116,13 @@ func (c *wsConn) handleVoiceInput(in wsInbound) {
|
||||
go c.h.runVoiceTurn(c, req)
|
||||
}
|
||||
|
||||
// runVoiceTurn drives one voice turn: STT (or a supplied transcript) → agent chat
|
||||
// → TTS, then replies to the requesting connection with a voice_output frame
|
||||
// carrying the base64 audio plus the recognized transcript and assistant reply.
|
||||
// runVoiceTurn 驱动一个语音回合：STT（或提供的转写）→ agent chat
|
||||
// → TTS，然后向请求连接回复一个 voice_output 帧，
|
||||
// 携带 base64 音频加上识别出的转写与助手回复。
|
||||
func (h *hub) runVoiceTurn(c *wsConn, req voiceInputRequest) {
|
||||
ctx := context.Background()
|
||||
// Thread the client's deviceID so the persisted voice turn is tagged with the
|
||||
// sending end (design/16 §4.5), mirroring ws_hub.go:240.
|
||||
// 把客户端的 deviceID 串下来，使持久化的语音回合被发送端
|
||||
// 标注（design/16 §4.5），与 ws_hub.go:240 一致。
|
||||
ctx = withDeviceID(ctx, req.DeviceID)
|
||||
if req.SessionID == "" {
|
||||
req.SessionID = "web"
|
||||
@@ -155,9 +155,9 @@ func (h *hub) runVoiceTurn(c *wsConn, req voiceInputRequest) {
|
||||
h.voiceError(c, "chat service is not configured")
|
||||
return
|
||||
}
|
||||
// The Web main session is the owner's private conversation, so it binds the
|
||||
// full-access env: memory read+write, unchanged behavior. The role comes from the
|
||||
// session's binding (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)})
|
||||
if err != nil {
|
||||
@@ -187,14 +187,14 @@ func (h *hub) runVoiceTurn(c *wsConn, req voiceInputRequest) {
|
||||
c.enqueueJSON(wsEvent{Type: wsVoiceOutput, Data: data})
|
||||
}
|
||||
|
||||
// voiceError replies with a typed error frame for a failed voice turn.
|
||||
// voiceError 为失败的语音回合回复一个带类型的错误帧。
|
||||
func (h *hub) voiceError(c *wsConn, message string) {
|
||||
c.enqueueJSON(wsEvent{Type: "error", Data: map[string]any{"message": message}})
|
||||
}
|
||||
|
||||
// decodeVoiceAudio turns a base64 (or data:) audio payload into voice.Audio. The
|
||||
// format is taken from req when set, guessed from a data: URI mime otherwise, and
|
||||
// defaulted to "wav".
|
||||
// decodeVoiceAudio 把 base64（或 data:）音频载荷转成 voice.Audio。
|
||||
// 格式在 req 设置时取自 req，否则从 data: URI mime 猜测，
|
||||
// 再默认到 "wav"。
|
||||
func decodeVoiceAudio(src, format string) (voice.Audio, error) {
|
||||
payload := src
|
||||
if strings.HasPrefix(src, "data:") {
|
||||
@@ -218,7 +218,7 @@ func decodeVoiceAudio(src, format string) (voice.Audio, error) {
|
||||
return voice.Audio{Format: format, Data: data}, nil
|
||||
}
|
||||
|
||||
// formatFromMime guesses an audio format from a data: URI mime segment.
|
||||
// formatFromMime 从 data: URI 的 mime 段猜测音频格式。
|
||||
func formatFromMime(meta string) string {
|
||||
lower := strings.ToLower(meta)
|
||||
for _, f := range []string{"wav", "mp3", "ogg", "webm", "mpeg"} {
|
||||
|
||||
Reference in new issue
Block a user