AskaEth/Cyrene_v2
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(comments): 注释中文化 · internal/runtime/multimodal（21 文件，纯替换）
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
Details
CI / Frontend (tsc + vite build) (push) Has been cancelled
Details

Browse Source 
- 只翻注释/文档字符串，代码零变化：go/scanner 词法流比对 21 文件 token+字面量全等，增删行数 1:1（467/467）
- 刻意保留非散文英文：JSON Schema description、工具 Description() 返回值、adapter prompt、API 路径与命令示例、环境变量名
- 逐行确认代码前缀未变，未触碰其他模块
This commit is contained in:
AskaEth committed 2026-10-04 12:28:16 +08:00
1 parent b9e042d07d
commit b0fbb8bc0d
21 files changed
+467 -467
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

internal/runtime/multimodal/doc.go
+13 -13
View File
@@ -1,17 +1,17 @@
// Package multimodal groups the runtime's non-text input/output handling:
// image understanding (vision) and speech (voice).
// Package multimodal 汇集运行时对非文本输入/输出的处理：
// 图像理解（视觉 vision）与语音（voice）。
//
// It follows DevDocs/design/06-多模态.md:
// 它遵循 DevDocs/design/06-多模态.md：
//
// - The vision subpackage routes image messages through a layered strategy
// (main model first, then a tool-shaped vision/OCR adapter) and registers
// those adapters as sdk.Tool capabilities so the M2 tool loop can invoke
// them without putting the image in the main-model context.
// - The voice subpackage provides asynchronous STT/TTS through a degrading
// provider chain (cloud → local → edge-tts/espeak → silent).
// - vision 子包按分层策略路由图像消息（先主模型，
// 再工具形态的 vision/OCR 适配器），并把
// 这些适配器注册为 sdk.Tool 能力，使 M2 工具循环能调用
// 它们，而无需把图像放进主模型上下文。
// - voice 子包通过一条降级提供方链
// （cloud → local → edge-tts/espeak → silent）提供异步 STT/TTS。
//
// Both subpackages keep real provider calls behind interfaces with an HTTP
// default implementation, so they are testable with a stdlib httptest server
// and leave the real cloud/local providers as adaptation points for later
// milestones.
// 两个子包都把真实的提供方调用藏在接口之后，并提供一个 HTTP
// 默认实现，因此可用标准库 httptest 服务器测试，
// 同时把真实的云端/本地提供方留作后续
// 里程碑的适配点。
package multimodal
internal/runtime/multimodal/vision/adapter.go
+27 -27
View File
@@ -13,28 +13,28 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
)
// visionMaxTokens caps the vision/OCR response length.
// visionMaxTokens 限制 vision/OCR 响应的长度。
const visionMaxTokens = 512
// VisionAdapter understands an image and returns a description of it. It is the
// backend behind the vision tool; real providers implement it without exposing
// the image to the main-model context.
// VisionAdapter 理解一张图像并返回对它的描述。它是
// 视觉工具背后的后端；真实提供方实现它，且不把图像
// 暴露给主模型上下文。
type VisionAdapter interface {
// Describe returns a description of img. prompt is an optional instruction
// overriding the default "describe this image" ask.
// Describe 返回 img 的描述。prompt 是可选的指令，
// 用于覆盖默认的「描述这张图」提问。
Describe(ctx context.Context, img ImageRef, prompt string) (string, error)
}
// OCRAdapter extracts text from an image. It is the backend behind the OCR tool.
// OCRAdapter 从图像中抽取文字。它是 OCR 工具背后的后端。
type OCRAdapter interface {
// Extract returns the text found in img.
// Extract 返回 img 中发现的文字。
Extract(ctx context.Context, img ImageRef) (string, error)
}
// OpenAICompatibleAdapter implements both VisionAdapter and OCRAdapter by
// calling an OpenAI-compatible /chat/completions endpoint with the image
// embedded as a content part. It is the ready default implementation; real
// cloud vision/OCR providers expose the same protocol.
// OpenAICompatibleAdapter 通过调用 OpenAI 兼容的 /chat/completions
// endpoint（图像作为内容部件内嵌）同时实现 VisionAdapter 与 OCRAdapter。
// 它是开箱可用的默认实现；真实的
// 云端 vision/OCR 提供方暴露相同协议。
type OpenAICompatibleAdapter struct {
cfg config.LLMConfig
model string
@@ -42,10 +42,10 @@ type OpenAICompatibleAdapter struct {
log *slog.Logger
}
// OpenAIOption customizes an OpenAICompatibleAdapter.
// OpenAIOption 用于定制 OpenAICompatibleAdapter。
type OpenAIOption func(*OpenAICompatibleAdapter)
// WithModel overrides the adapter model (defaults to cfg.Model).
// WithModel 覆盖适配器的模型（默认取 cfg.Model）。
func WithModel(m string) OpenAIOption {
return func(a *OpenAICompatibleAdapter) {
if m != "" {
@@ -54,7 +54,7 @@ func WithModel(m string) OpenAIOption {
}
}
// WithHTTPClient sets the *http.Client used for the request; nil keeps default.
// WithHTTPClient 设置请求所用的 *http.Client；nil 表示保持默认。
func WithHTTPClient(c *http.Client) OpenAIOption {
return func(a *OpenAICompatibleAdapter) {
if c != nil {
@@ -63,7 +63,7 @@ func WithHTTPClient(c *http.Client) OpenAIOption {
}
}
// WithLogger sets the logger used on failures; nil keeps a discard logger.
// WithLogger 设置失败时使用的日志器；nil 表示保持丢弃日志器。
func WithLogger(l *slog.Logger) OpenAIOption {
return func(a *OpenAICompatibleAdapter) {
if l != nil {
@@ -72,8 +72,8 @@ func WithLogger(l *slog.Logger) OpenAIOption {
}
}
// NewOpenAICompatible builds an adapter from cfg, using cfg.Model unless
// overridden.
// NewOpenAICompatible 用 cfg 构造一个适配器，未覆盖时使用
// cfg.Model。
func NewOpenAICompatible(cfg config.LLMConfig, opts ...OpenAIOption) *OpenAICompatibleAdapter {
a := &OpenAICompatibleAdapter{
cfg: cfg,
@@ -87,7 +87,7 @@ func NewOpenAICompatible(cfg config.LLMConfig, opts ...OpenAIOption) *OpenAIComp
return a
}
// Describe returns an image description from the underlying chat endpoint.
// Describe 从底层 chat endpoint 返回图像描述。
func (a *OpenAICompatibleAdapter) Describe(ctx context.Context, img ImageRef, prompt string) (string, error) {
if prompt == "" {
prompt = "Describe this image in detail."
@@ -95,12 +95,12 @@ func (a *OpenAICompatibleAdapter) Describe(ctx context.Context, img ImageRef, pr
return a.ask(ctx, img, prompt)
}
// Extract returns text found in the image via the same endpoint.
// Extract 经同一 endpoint 返回图像中发现的文字。
func (a *OpenAICompatibleAdapter) Extract(ctx context.Context, img ImageRef) (string, error) {
return a.ask(ctx, img, "Extract all text visible in this image. Return only the text.")
}
// ask resolves the image, builds a chat request and returns the assistant text.
// ask 解析图像、构造 chat 请求并返回助手文本。
func (a *OpenAICompatibleAdapter) ask(ctx context.Context, img ImageRef, prompt string) (string, error) {
if strings.TrimSpace(a.cfg.BaseURL) == "" {
return "", ErrNotConfigured
@@ -139,8 +139,8 @@ func (a *OpenAICompatibleAdapter) ask(ctx context.Context, img ImageRef, prompt
return a.decode(resp.Body)
}
// imageURL converts an ImageRef to the image_url value the wire expects: an
// http(s) URL passes through, anything else becomes a base64 data: URI.
// imageURL 把 ImageRef 转换为线上格式期望的 image_url 取值：http(s)
// URL 原样透传，其余一律转为 base64 data: URI。
func (a *OpenAICompatibleAdapter) imageURL(ctx context.Context, img ImageRef) (string, error) {
if img.Source == SourceURL {
return img.Data, nil
@@ -152,7 +152,7 @@ func (a *OpenAICompatibleAdapter) imageURL(ctx context.Context, img ImageRef) (s
return DataURI(mime, data), nil
}
// openAIVisionRequest is the JSON body sent to /chat/completions.
// openAIVisionRequest 是发往 /chat/completions 的 JSON 请求体。
type openAIVisionRequest struct {
Model string `json:"model"`
Messages []openAIMessage `json:"messages"`
@@ -186,7 +186,7 @@ type openAIResponseMessage struct {
Content string `json:"content"`
}
// request builds the wire body for an image+prompt.
// request 构造图像 + prompt 的线上请求体。
func (a *OpenAICompatibleAdapter) request(imageURL, prompt string) openAIVisionRequest {
return openAIVisionRequest{
Model: a.model,
@@ -200,7 +200,7 @@ func (a *OpenAICompatibleAdapter) request(imageURL, prompt string) openAIVisionR
}
}
// decode extracts the first choice's text from a response body.
// decode 从响应体中取出第一个 choice 的文本。
func (a *OpenAICompatibleAdapter) decode(r io.Reader) (string, error) {
var wire openAIVisionResponse
if err := json.NewDecoder(r).Decode(&wire); err != nil {
@@ -212,6 +212,6 @@ func (a *OpenAICompatibleAdapter) decode(r io.Reader) (string, error) {
return wire.Choices[0].Message.Content, nil
}
// interface assertion: one concrete adapter serves both directions.
// 接口断言：同一个具体适配器同时服务两个方向。
var _ VisionAdapter = (*OpenAICompatibleAdapter)(nil)
var _ OCRAdapter = (*OpenAICompatibleAdapter)(nil)
internal/runtime/multimodal/vision/errors.go
+9 -9
View File
@@ -2,21 +2,21 @@ package vision
import "errors"
// Sentinel errors returned by the vision package. Each is wrapped with %w on
// the way out so callers can test for a category while keeping the cause.
// vision 包返回的哨兵错误。每个错误向外传递时都以 %w
// 包装，使调用方能按类别判断，同时保留原始原因。
var (
// ErrNoImage is returned when an image source string is empty.
// ErrNoImage 在图像来源字符串为空时返回。
ErrNoImage = errors.New("vision: empty image source")
// ErrNotConfigured is returned by adapters when no endpoint/model is set.
// ErrNotConfigured 在适配器未设置 endpoint/model 时返回。
ErrNotConfigured = errors.New("vision: adapter not configured")
// ErrUnsupportedSource is returned when an image source cannot be handled.
// ErrUnsupportedSource 在图像来源无法处理时返回。
ErrUnsupportedSource = errors.New("vision: unsupported image source")
// ErrFetch is returned when a URL image cannot be downloaded.
// ErrFetch 在 URL 图像无法下载时返回。
ErrFetch = errors.New("vision: cannot fetch image")
// ErrUpstream is returned when the vision/OCR provider request fails.
// ErrUpstream 在 vision/OCR 提供方请求失败时返回。
ErrUpstream = errors.New("vision: upstream request failed")
// ErrBadImage is returned when an image cannot be read or decoded.
// ErrBadImage 在图像无法读取或解码时返回。
ErrBadImage = errors.New("vision: cannot read image")
// ErrBadArgs is returned by a tool when its arguments are malformed.
// ErrBadArgs 在工具参数格式错误时由该工具返回。
ErrBadArgs = errors.New("vision: bad tool arguments")
)
internal/runtime/multimodal/vision/image.go
+21 -21
View File
@@ -10,23 +10,23 @@ import (
"strings"
)
// Size caps for reading image bytes and response bodies, so a hostile or
// malformed source cannot exhaust memory. The 50MB cap matches the file-upload
// limit in DevDocs/02-development-constraints.md §11.
// 读取图像字节与响应体的体积上限，使恶意或
// 畸形来源无法耗尽内存。50MB 上限与
// DevDocs/02-development-constraints.md §11 的文件上传限制一致。
const (
maxImageBytes = 50 << 20
maxFetchedBody = 50 << 20
)
// DataURI builds a base64 data: image URI from mime and raw bytes.
// DataURI 由 mime 与原始字节构造一个 base64 data: 图像 URI。
func DataURI(mime string, data []byte) string {
return "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(data)
}
// Resolve loads the bytes for an ImageRef. Paths and base64 payloads are read
// locally; URLs are fetched with an http.Client (the provided client, or a
// default one when nil). For base64 input the Data field is returned verbatim as
// the payload and the MIME type is guessed from a data: prefix.
// Resolve 加载一个 ImageRef 对应的字节。路径与 base64 载荷在
// 本地读取；URL 用 http.Client 抓取（传入的 client，为 nil 时
// 用默认 client）。对 base64 输入，Data 字段原样作为
// 载荷返回，MIME 类型从 data: 前缀推断。
func Resolve(ctx context.Context, ref ImageRef, client *http.Client) (mime string, data []byte, err error) {
switch ref.Source {
case SourcePath:
@@ -40,7 +40,7 @@ func Resolve(ctx context.Context, ref ImageRef, client *http.Client) (mime strin
}
}
// readFile reads an image file and guesses its MIME type from the extension.
// readFile 读取一个图像文件，并从扩展名推断其 MIME 类型。
func readFile(path string) (string, []byte, error) {
f, err := os.Open(path)
if err != nil {
@@ -54,7 +54,7 @@ func readFile(path string) (string, []byte, error) {
return mimeByExt(path), data, nil
}
// decodeBase64 returns the decoded bytes of a base64/data: payload and its MIME.
// decodeBase64 返回 base64/data: 载荷解码后的字节及其 MIME。
func decodeBase64(src string) (string, []byte, error) {
mime, encoded, isDataURI := splitDataURI(src)
if isDataURI {
@@ -71,7 +71,7 @@ func decodeBase64(src string) (string, []byte, error) {
return "image/png", decoded, nil
}
// fetchURL downloads an image over http(s); only http/https schemes are allowed.
// fetchURL 通过 http(s) 下载一张图像；只允许 http/https 协议。
func fetchURL(ctx context.Context, rawURL string, client *http.Client) (string, []byte, error) {
if !strings.HasPrefix(rawURL, "http://") && !strings.HasPrefix(rawURL, "https://") {
return "", nil, fmt.Errorf("vision: %w: %q", ErrUnsupportedSource, rawURL)
@@ -98,8 +98,8 @@ func fetchURL(ctx context.Context, rawURL string, client *http.Client) (string,
return mimeByContentType(resp.Header.Get("Content-Type")), data, nil
}
// splitDataURI parses a "data:<mime>;base64,<payload>" prefix. The second return
// is false when src is not a data: URI.
// splitDataURI 解析 "data:<mime>;base64,<payload>" 前缀。src 不是
// data: URI 时第二个返回值是 false。
func splitDataURI(src string) (mime, payload string, ok bool) {
if !strings.HasPrefix(src, "data:") {
return "", "", false
@@ -124,7 +124,7 @@ func splitDataURI(src string) (mime, payload string, ok bool) {
return mime, payload, true
}
// mimeByExt guesses a MIME type from a file path extension.
// mimeByExt 从文件路径扩展名推断 MIME 类型。
func mimeByExt(path string) string {
switch strings.ToLower(pathExtension(path)) {
case ".png":
@@ -140,8 +140,8 @@ func mimeByExt(path string) string {
}
}
// mimeByContentType returns a MIME type from an HTTP Content-Type header,
// defaulting to image/png when absent or non-image.
// mimeByContentType 从 HTTP Content-Type 头返回 MIME 类型，
// 缺失或非图像时默认为 image/png。
func mimeByContentType(ct string) string {
if ct == "" || !strings.HasPrefix(ct, "image/") {
return "image/png"
@@ -149,7 +149,7 @@ func mimeByContentType(ct string) string {
return strings.TrimSpace(strings.Split(ct, ";")[0])
}
// pathExtension returns the file extension with its dot, or empty when none.
// pathExtension 返回带点号的文件扩展名，没有则返回空串。
func pathExtension(path string) string {
base := path
if idx := strings.LastIndexByte(path, '/'); idx >= 0 {
@@ -164,15 +164,15 @@ func pathExtension(path string) string {
return base[dot:]
}
// fileExists reports whether path exists on disk and is a regular file.
// fileExists 报告 path 是否存在于磁盘且为常规文件。
func fileExists(path string) bool {
info, err := os.Stat(path)
return err == nil && info.Mode().IsRegular()
}
// defaultHTTPClient builds the HTTP client described in
// DevDocs/02-development-constraints.md §2.3. A fresh client is returned per
// call rather than a package global, which the constraints forbid.
// defaultHTTPClient 构造 DevDocs/02-development-constraints.md §2.3
// 所述的 HTTP client。这里每次调用返回一个新 client，
// 而不是包级全局变量——后者为约束所禁止。
func defaultHTTPClient() *http.Client {
return &http.Client{Transport: http.DefaultTransport}
}
internal/runtime/multimodal/vision/resolver.go
+28 -28
View File
@@ -7,31 +7,31 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
)
// ModelInfoProvider supplies the main model's vision capability so the resolver
// can route an image the way the vision Router decides (design/06 §0). It is
// called per image; the same provider is shared across a single resolution.
// ModelInfoProvider 提供主模型的视觉能力，使解析器
// 能按 vision Router 的判定（design/06 §0）路由图像。它按
// 图像逐个调用；同一次解析中共享同一个 provider。
type ModelInfoProvider func() ModelInfo
// ToolInvoker invokes a registered tool (the vision or OCR tool) by name with
// the given arguments. It is satisfied by *tool.Dispatcher.Invoke.
// ToolInvoker 按名字与给定参数调用一个已注册的工具（视觉或 OCR
// 工具）。由 *tool.Dispatcher.Invoke 满足。
type ToolInvoker func(ctx context.Context, name string, args map[string]any) (any, error)
// MessageResolver is the loop's concrete ImageResolver. For each image part in a
// user message it asks the vision Router how to route it: when the main model
// supports vision and is confident, the image part is kept so the main model sees
// the image; otherwise the vision/OCR tool is invoked and its text result replaces
// the image part, so a text-only main model can reason over the image ("先看图再
// 对话"). It is safe for concurrent use.
// MessageResolver 是 loop 的具体 ImageResolver。对用户消息中的
// 每个图像部件，它向 vision Router 询问如何路由：当主模型
// 支持视觉且有信心时，保留该图像部件让主模型看到
// 图像；否则调用 vision/OCR 工具，用其文字结果替换
// 图像部件，使纯文本主模型也能对图像推理（「先看图再
// 对话」）。它可安全并发使用。
type MessageResolver struct {
router *Router
info ModelInfoProvider
invoke ToolInvoker
}
// NewMessageResolver builds a MessageResolver. router decides the layer; info
// reports the main model's vision capability; invoke runs a registered vision/OCR
// tool. A nil invoke leaves any tool route failed (the image is then kept), so a
// resolver without tools degrades to the main-model path.
// NewMessageResolver 构造一个 MessageResolver。router 决定
// 分层；info 报告主模型的视觉能力；invoke 运行一个已注册的 vision/OCR
// 工具。invoke 为 nil 时任何工具路由都会失败（此时图像被保留），
// 因此没有工具的解析器会降级到主模型路径。
func NewMessageResolver(router *Router, info ModelInfoProvider, invoke ToolInvoker) *MessageResolver {
return &MessageResolver{
router: router,
@@ -40,10 +40,10 @@ func NewMessageResolver(router *Router, info ModelInfoProvider, invoke ToolInvok
}
}
// Resolve rewrites msg so every image part is either kept (main model sees it) or
// replaced by a text description produced by the vision/OCR tool. Text parts are
// preserved in order. It errors only when an image cannot be routed or a tool
// invocation fails; the caller (loop) then keeps the original message.
// Resolve 改写 msg，使每个图像部件要么被保留（主模型能看到它），
// 要么被 vision/OCR 工具产出的文字描述替换。文本部件
// 按原顺序保留。它仅在图像无法路由或工具
// 调用失败时报错；此时调用方（loop）保留原始消息。
func (r *MessageResolver) Resolve(ctx context.Context, msg model.Message) (model.Message, error) {
if r.router == nil {
return msg, nil
@@ -63,8 +63,8 @@ func (r *MessageResolver) Resolve(ctx context.Context, msg model.Message) (model
return model.Message{Role: msg.Role, Content: out}, nil
}
// resolveImage picks a route and either keeps the image (KindMain) or folds it
// into a text description via the vision/OCR tool.
// resolveImage 选出一条路由：要么保留图像（KindMain），
// 要么经 vision/OCR 工具把它折叠为文字描述。
func (r *MessageResolver) resolveImage(ctx context.Context, imageURL string) (model.Content, error) {
target := ModelInfo{}
if r.info != nil {
@@ -73,7 +73,7 @@ func (r *MessageResolver) resolveImage(ctx context.Context, imageURL string) (mo
decision := r.router.Route(target, RouteRequest{})
switch decision.Kind {
case KindMain:
// A vision-capable main model sees the image directly.
// 支持视觉的主模型直接看到这张图。
return model.Content{Type: model.ContentTypeImage, ImageURL: imageURL}, nil
case KindVisionTool:
return r.invokeTool(ctx, decision.Tool, map[string]any{
@@ -89,8 +89,8 @@ func (r *MessageResolver) resolveImage(ctx context.Context, imageURL string) (mo
}
}
// invokeTool runs a registered vision/OCR tool and turns its text result into a
// text content part. field is the result map key ("description" or "text").
// invokeTool 运行一个已注册的 vision/OCR 工具，并把其文字结果转成
// 文本内容部件。field 是结果 map 的键（"description" 或 "text"）。
func (r *MessageResolver) invokeTool(ctx context.Context, toolName string, args map[string]any, field string) (model.Content, error) {
if r.invoke == nil {
return model.Content{}, fmt.Errorf("%s: %w", toolName, ErrNotConfigured)
@@ -102,8 +102,8 @@ func (r *MessageResolver) invokeTool(ctx context.Context, toolName string, args
return model.Content{Type: model.ContentTypeText, Text: descriptionFragment(fieldText(result, field))}, nil
}
// fieldText extracts a string field from a tool result map, tolerating the
// map[string]any shape returned by the vision/OCR tools.
// fieldText 从工具结果的 map 中取出字符串字段，兼容
// vision/OCR 工具返回的 map[string]any 形状。
func fieldText(result any, field string) string {
m, ok := result.(map[string]any)
if !ok {
@@ -113,8 +113,8 @@ func fieldText(result any, field string) string {
return s
}
// descriptionFragment labels a tool-produced description so the model can tell it
// refers to the picture the user attached.
// descriptionFragment 给工具产出的描述加上标注，使模型能看出它
// 指的是用户附上的那张图。
func descriptionFragment(desc string) string {
if desc == "" {
return "[图片内容] 无法识别该图片"
internal/runtime/multimodal/vision/resolver_test.go
+3 -3
View File
@@ -69,9 +69,9 @@ func TestMessageResolver_OCRToolForText(t *testing.T) {
return map[string]any{"text": "HELLO"}, nil
})
// Force the text-primary hint by using a router route request path: this is
// exercised directly through Resolve which passes no hint, so the vision tool
// is preferred; assert at least a text part replaces the image.
// 通过 router 的路由请求路径强制给出文本优先提示：这里直接经 Resolve
// 走通，而 Resolve 不传任何提示，因此优先使用视觉工具；
// 断言至少有一个文本部件替换了图像。
msg, err := res.Resolve(context.Background(), model.ImageMessage(model.RoleUser, "x", "data:image/png;base64,AAAA"))
if err != nil {
t.Fatalf("Resolve: %v", err)
internal/runtime/multimodal/vision/router.go
+39 -39
View File
@@ -1,67 +1,67 @@
package vision
// Assessment is the model's own confidence in reading an image.
// Assessment 是模型对自己读图结果的置信度。
type Assessment string
const (
// AssessmentUnknown means the model reported no self-assessment.
// AssessmentUnknown 表示模型未给出自评。
AssessmentUnknown Assessment = "unknown"
// AssessmentGood means the model is confident in its read.
// AssessmentGood 表示模型对自己的读图结果有信心。
AssessmentGood Assessment = "good"
// AssessmentPoor means the model judged its recognition as poor.
// AssessmentPoor 表示模型判定自己的识别效果差。
AssessmentPoor Assessment = "poor"
)
// ModelInfo describes the main model's vision capability.
// ModelInfo 描述主模型的视觉能力。
type ModelInfo struct {
// Name identifies the model.
// Name 标识模型。
Name string
// SupportsVision reports whether the model accepts image input.
// SupportsVision 报告模型是否接受图像输入。
SupportsVision bool
// SelfAssessment is the model's own confidence for the current image.
// It drives the layer-2 tool route when SupportsVision is true.
// SelfAssessment 是模型对当前图像的自评置信度。
// 当 SupportsVision 为真时，它决定是否走第二层工具路由。
SelfAssessment Assessment
}
// DecisionKind is the chosen layered route.
// DecisionKind 是选定的分层路由。
type DecisionKind string
const (
// KindMain routes the image to the main model with the image in context.
// KindMain 把图像连同上下文一起交给主模型。
KindMain DecisionKind = "main"
// KindVisionTool routes to a dedicated vision tool, returning only the tool
// result so the image never occupies main-model context.
// KindVisionTool 路由到专用视觉工具，只返回工具
// 结果，使图像不占用主模型上下文。
KindVisionTool DecisionKind = "vision_tool"
// KindOCRTool routes to an OCR tool, returning only the extracted text.
// KindOCRTool 路由到 OCR 工具，只返回抽取出的文字。
KindOCRTool DecisionKind = "ocr_tool"
// KindUnsupported means no route can process the image.
// KindUnsupported 表示没有任何路由能处理该图像。
KindUnsupported DecisionKind = "unsupported"
)
// Decision is the outcome of a routing call.
// Decision 是一次路由调用的结果。
type Decision struct {
// Kind is the chosen route.
// Kind 是选定的路由。
Kind DecisionKind
// Tool names the vision or OCR tool to invoke, set when Kind is a tool route.
// Tool 指名要调用的视觉或 OCR 工具，当 Kind 为工具路由时设置。
Tool string
// Reason is a human-readable explanation for observability and logs.
// Reason 是便于可观测与日志的人类可读说明。
Reason string
}
// RouteRequest carries routing hints from the caller on top of the model info.
// RouteRequest 携带调用方在模型信息之外给出的路由提示。
type RouteRequest struct {
// TextPrimary reports that the user indicated the image is mainly text, so
// an OCR tool is preferred over a general vision model.
// TextPrimary 表示用户指出图像以文字为主，因此
// 优先使用 OCR 工具而非通用视觉模型。
TextPrimary bool
// MainSelfAssessedPoor is set when the main model has already judged its own
// read of the image as poor, requesting a vision/OCR tool route.
// MainSelfAssessedPoor 在主模型已自评读图效果
// 较差、请求走 vision/OCR 工具路由时置位。
MainSelfAssessedPoor bool
}
// RouterOption configures a Router.
// RouterOption 配置 Router。
type RouterOption func(*Router)
// WithVisionTool binds the name of the registered vision-understanding tool.
// WithVisionTool 绑定已注册的图像理解工具名。
func WithVisionTool(name string) RouterOption {
return func(r *Router) {
if name != "" {
@@ -70,7 +70,7 @@ func WithVisionTool(name string) RouterOption {
}
}
// WithOCRTool binds the name of the registered OCR tool.
// WithOCRTool 绑定已注册的 OCR 工具名。
func WithOCRTool(name string) RouterOption {
return func(r *Router) {
if name != "" {
@@ -79,15 +79,15 @@ func WithOCRTool(name string) RouterOption {
}
}
// Router implements the layered vision routing policy. It does no I/O; the
// caller uses the returned Decision to dispatch the request.
// Router 实现分层视觉路由策略。它不做任何 I/O；调用方
// 用返回的 Decision 去派发请求。
type Router struct {
visionTool string
ocrTool string
}
// NewRouter builds a Router. Unknown (empty) tool names leave the corresponding
// route unavailable, so the router degrades to KindMain or KindUnsupported.
// NewRouter 构造 Router。未知（空）的工具名会让对应
// 路由不可用，于是路由器降级为 KindMain 或 KindUnsupported。
func NewRouter(opts ...RouterOption) *Router {
r := &Router{}
for _, o := range opts {
@@ -96,21 +96,21 @@ func NewRouter(opts ...RouterOption) *Router {
return r
}
// Route picks a layered route for an image request given the target model info
// and caller hints. The order is: the main model directly when it can see and
// has not self-assessed poorly (layer 1); otherwise a vision or OCR tool whose
// result replaces the image in context (layers 2 and 3); otherwise
// KindUnsupported when nothing can process the image.
// Route 依据目标模型信息与调用方提示，为一次图像请求
// 选出分层路由。顺序为：主模型能看图且
// 未自评较差时直接用它（第一层）；否则用能替换
// 上下文中图像的视觉或 OCR 工具（第二、三层）；再否则
// 没有任何东西能处理该图像时给出 KindUnsupported。
func (r *Router) Route(target ModelInfo, req RouteRequest) Decision {
poor := target.SelfAssessment == AssessmentPoor || req.MainSelfAssessedPoor
// Layer 1: the main model accepts images and is confident, so use it first.
// 第一层：主模型接受图像且自信，优先使用它。
if target.SupportsVision && !poor {
return Decision{
Kind: KindMain,
Reason: "main model supports vision and is confident; use it directly",
}
}
// OCR is preferred when the user says the image is mostly text.
// 用户说明图像以文字为主时优先 OCR。
if req.TextPrimary && r.ocrTool != "" {
return Decision{Kind: KindOCRTool, Tool: r.ocrTool, Reason: "image is mainly text; route to OCR"}
}
@@ -120,7 +120,7 @@ func (r *Router) Route(target ModelInfo, req RouteRequest) Decision {
if r.ocrTool != "" {
return Decision{Kind: KindOCRTool, Tool: r.ocrTool, Reason: "route to OCR tool"}
}
// No tool is bound. A sighted main model remains the only option.
// 未绑定任何工具。能看图的主模型仍是唯一选择。
if target.SupportsVision {
return Decision{Kind: KindMain, Reason: "no vision/OCR tool bound; keep image with main model"}
}
internal/runtime/multimodal/vision/router_test.go
+2 -2
View File
@@ -96,14 +96,14 @@ func TestRouter_Route(t *testing.T) {
}
}
// fakeVision implements VisionAdapter for tool tests.
// fakeVision 为工具测试实现 VisionAdapter。
type fakeVision struct{ desc string }
func (f *fakeVision) Describe(_ context.Context, _ ImageRef, _ string) (string, error) {
return f.desc, nil
}
// fakeOCR implements OCRAdapter for tool tests.
// fakeOCR 为工具测试实现 OCRAdapter。
type fakeOCR struct{ text string }
func (f *fakeOCR) Extract(_ context.Context, _ ImageRef) (string, error) {
internal/runtime/multimodal/vision/tool.go
+23 -23
View File
@@ -7,9 +7,9 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/pkg/plugins/sdk"
)
// toolParameters returns the shared input JSON Schema for the vision and OCR
// tools. It builds a fresh map each call rather than sharing a package-level
// variable.
// toolParameters 返回视觉工具与 OCR 工具共用的输入 JSON Schema。
// 它每次调用都新建一个 map，而不是共享包级
// 变量。
func toolParameters() map[string]any {
return map[string]any{
"type": "object",
@@ -27,33 +27,33 @@ func toolParameters() map[string]any {
}
}
// VisionTool wraps a VisionAdapter as an sdk.Tool so the M2 tool loop can invoke
// it and return its description as a tool result, keeping the image out of the
// main-model context. It is safe for concurrent use.
// VisionTool 把 VisionAdapter 包装成 sdk.Tool，使 M2 工具循环能调用
// 它并把描述作为工具结果返回，从而让图像不进入
// 主模型上下文。它可安全并发使用。
type VisionTool struct {
name string
adapter VisionAdapter
}
// NewVisionTool builds a VisionTool with the given name and adapter.
// NewVisionTool 用给定名字与适配器构造一个 VisionTool。
func NewVisionTool(name string, adapter VisionAdapter) *VisionTool {
return &VisionTool{name: name, adapter: adapter}
}
// Name returns the tool identifier the agent uses to invoke it.
// Name 返回智能体用来调用该工具的工具标识。
func (t *VisionTool) Name() string { return t.name }
// Description explains what the tool does.
// Description 说明该工具做什么。
func (t *VisionTool) Description() string {
return "Understand an image and return a description of its contents."
}
// Parameters returns the input JSON Schema.
// Parameters 返回输入 JSON Schema。
func (t *VisionTool) Parameters() (map[string]any, error) {
return toolParameters(), nil
}
// Execute runs the adapter on the image from args and returns the description.
// Execute 对 args 中的图像运行适配器并返回描述。
func (t *VisionTool) Execute(ctx context.Context, args any) (any, error) {
image, prompt, err := toolArgs(args)
if err != nil {
@@ -70,32 +70,32 @@ func (t *VisionTool) Execute(ctx context.Context, args any) (any, error) {
return map[string]any{"description": desc}, nil
}
// OCRTool wraps an OCRAdapter as an sdk.Tool. It returns the extracted text as a
// tool result. It is safe for concurrent use.
// OCRTool 把 OCRAdapter 包装成 sdk.Tool。它把抽取出的文字作为
// 工具结果返回。它可安全并发使用。
type OCRTool struct {
name string
adapter OCRAdapter
}
// NewOCRTool builds an OCRTool with the given name and adapter.
// NewOCRTool 用给定名字与适配器构造一个 OCRTool。
func NewOCRTool(name string, adapter OCRAdapter) *OCRTool {
return &OCRTool{name: name, adapter: adapter}
}
// Name returns the tool identifier.
// Name 返回工具标识。
func (t *OCRTool) Name() string { return t.name }
// Description explains what the tool does.
// Description 说明该工具做什么。
func (t *OCRTool) Description() string {
return "Extract text from an image (OCR) and return the recognized text."
}
// Parameters returns the input JSON Schema.
// Parameters 返回输入 JSON Schema。
func (t *OCRTool) Parameters() (map[string]any, error) {
return toolParameters(), nil
}
// Execute runs the OCR adapter on the image from args and returns the text.
// Execute 对 args 中的图像运行 OCR 适配器并返回文字。
func (t *OCRTool) Execute(ctx context.Context, args any) (any, error) {
image, _, err := toolArgs(args)
if err != nil {
@@ -112,9 +112,9 @@ func (t *OCRTool) Execute(ctx context.Context, args any) (any, error) {
return map[string]any{"text": text}, nil
}
// RegisterTools registers the vision and OCR tools with r via the SDK helper.
// Each tool is only registered when its pointer is non-nil. It returns the
// first registration error, or nil when every tool registered.
// RegisterTools 经 SDK 辅助函数把视觉工具与 OCR 工具注册到 r。
// 每个工具仅在其指针非 nil 时注册。它返回
// 第一个注册错误；全部注册成功时返回 nil。
func RegisterTools(r sdk.Registrar, tool *VisionTool, ocr *OCRTool) error {
if r == nil {
return sdk.ErrNilRegistrar
@@ -132,8 +132,8 @@ func RegisterTools(r sdk.Registrar, tool *VisionTool, ocr *OCRTool) error {
return nil
}
// toolArgs decodes sdk.Tool.Execute args into the image string and an optional
// prompt. Args must be a map[string]any with a non-empty "image" string.
// toolArgs 把 sdk.Tool.Execute 的 args 解码为图像字符串与一个可选的
// prompt。args 必须是含非空 "image" 字符串的 map[string]any。
func toolArgs(args any) (image, prompt string, err error) {
m, ok := args.(map[string]any)
if !ok {
internal/runtime/multimodal/vision/vision.go
+27 -27
View File
@@ -1,15 +1,15 @@
// Package vision implements the layered image routing described in
// DevDocs/design/06-多模态.md §0.
// Package vision 实现 DevDocs/design/06-多模态.md §0 所述的
// 分层图像路由。
//
// A request that carries image content is first checked by DetectMultimodal.
// The VisionRouter then picks one of the layered routes: the main model
// directly (when it accepts images), a tool-shaped vision/OCR adapter (when the
// main model self-assesses poorly or cannot see), or the OCR tool (when the
// image is mainly text). Vision/OCR adapters are registered as sdk.Tool
// capabilities through the capability registry, and their output is a tool
// result, so the image itself never occupies main-model context.
// 携带图像内容的请求先由 DetectMultimodal 检查。
// 随后 VisionRouter 选出其中一条分层路由：主模型
// 直连（当它接受图像时）、工具形态的 vision/OCR 适配器（当主模型
// 自评较差或看不见图像时），或 OCR 工具（当
// 图像以文字为主时）。vision/OCR 适配器经能力注册中心
// 注册为 sdk.Tool 能力，其输出即工具
// 结果，因此图像本身从不占用主模型上下文。
//
// Images may come from a local path, an http(s) URL, or a base64/data: URI.
// 图像可来自本地路径、http(s) URL 或 base64/data: URI。
package vision
import (
@@ -18,11 +18,11 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
)
// DetectMultimodal reports whether msgs contains any non-text content part,
// i.e. whether multimodal handling is required. Today model only distinguishes
// text from image content, so this is true exactly when a message carries an
// image part; the check is written against "not text" so future content types
// (audio) extend it without rework.
// DetectMultimodal 报告 msgs 是否含任何非文本内容部件，
// 即是否需要多模态处理。当前 model 只区分
// 文本与图像内容，因此这等价于某条消息携带
// 图像部件；判断写成「非文本」是为了让未来的内容类型
// （音频）无需返工即可扩展。
func DetectMultimodal(msgs []model.Message) bool {
for _, m := range msgs {
for _, part := range m.Content {
@@ -34,30 +34,30 @@ func DetectMultimodal(msgs []model.Message) bool {
return false
}
// ImageSource classifies where an image's bytes come from.
// ImageSource 归类一副图像的字节来自何处。
type ImageSource string
const (
// SourcePath is a local filesystem path.
// SourcePath 是本地文件系统路径。
SourcePath ImageSource = "path"
// SourceURL is an http(s):// URL.
// SourceURL 是 http(s):// URL。
SourceURL ImageSource = "url"
// SourceBase64 is a base64 payload, optionally wrapped in a data: URI.
// SourceBase64 是 base64 载荷，可选地包在 data: URI 中。
SourceBase64 ImageSource = "base64"
)
// ImageRef is a single image reference plus its resolved source kind.
// ImageRef 是单个图像引用及其已归类的来源种类。
type ImageRef struct {
// Source is the classified source kind.
// Source 是归类后的来源种类。
Source ImageSource
// Data is the local path, URL, or base64/data: payload.
// Data 是本地路径、URL 或 base64/data: 载荷。
Data string
}
// ParseImageRef classifies a raw image source string into an ImageRef. Empty
// input is rejected. Local paths that exist on disk are classified as paths;
// http(s) URLs as URLs; every other value, including a data: URI, is treated as
// a base64 payload. This keeps routing deterministic without guessing MIME.
// ParseImageRef 把原始图像来源字符串归类为 ImageRef。空
// 输入被拒绝。磁盘上存在的本地路径归类为路径；
// http(s) URL 归类为 URL；其余所有值（含 data: URI）都视为
// base64 载荷。这样无需猜测 MIME 即可保持路由确定性。
func ParseImageRef(src string) (ImageRef, error) {
if src == "" {
return ImageRef{}, ErrNoImage
@@ -68,7 +68,7 @@ func ParseImageRef(src string) (ImageRef, error) {
if strings.HasPrefix(src, "file://") {
return ImageRef{Source: SourcePath, Data: strings.TrimPrefix(src, "file://")}, nil
}
// A data: URI is base64 already; treat as base64, not path.
// data: URI 本身就是 base64；按 base64 处理，而非路径。
if strings.HasPrefix(src, "data:") {
return ImageRef{Source: SourceBase64, Data: src}, nil
}
internal/runtime/multimodal/voice/chain.go
+36 -36
View File
@@ -7,31 +7,31 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
)
// Chain is a degrading provider list. STT and TTS walk the steps in order,
// returning the first successful result and moving to the next step when a
// provider is unavailable (nil direction) or fails. It implements STT and TTS so
// it can be used anywhere a single provider is expected.
// Chain 是一条降级提供方列表。STT 与 TTS 按序走各级，
// 返回第一个成功的结果；某级不可用（方向为 nil）或
// 失败时则移向下一级。它实现 STT 与 TTS，
// 因此可用在任何期望单个提供方的地方。
type Chain struct {
steps []Provider
cloner VoiceCloner
}
// NewChain builds a degrading chain from the given providers in the order they
// should be tried. Passing a SilentProvider last guarantees the chain always
// succeeds.
// NewChain 按给定提供方的尝试顺序构造一条降级链。
// 把 SilentProvider 放在最后，可保证
// 这条链总是成功。
func NewChain(steps ...Provider) *Chain {
return &Chain{steps: steps}
}
// STT walks the chain for a transcription.
// STT 走链取一次转写。
func (c *Chain) STT(ctx context.Context, audio Audio) (string, error) {
text, _, err := c.STTWithProvider(ctx, audio)
return text, err
}
// STTWithProvider is STT but also reports the name of the provider rung that
// produced the transcription (cloud / local / edge-tts / silent), so a caller can
// surface which tier actually served the request.
// STTWithProvider 即 STT，但额外报告产出该转写的提供方
// 级别名（cloud / local / edge-tts / silent），使调用方能
// 展示实际是哪一级服务了该请求。
func (c *Chain) STTWithProvider(ctx context.Context, audio Audio) (string, string, error) {
if len(c.steps) == 0 {
return "", "", ErrProviderFailed
@@ -51,9 +51,9 @@ func (c *Chain) STTWithProvider(ctx context.Context, audio Audio) (string, strin
return "", "", fmt.Errorf("voice: %w: %v", ErrProviderFailed, lastErr)
}
// CloneVoice creates a custom voice via the cloud provider's voice-enrollment
// endpoint (声音复刻 create_voice). A chain without a cloud rung returns
// ErrNotConfigured. It is not a degradation step — the caller gets one result.
// CloneVoice 经云端提供方的音色注册 endpoint 创建自定义音色
// （声音复刻 create_voice）。没有云端一级的链返回
// ErrNotConfigured。它不是降级步骤 —— 调用方只拿到一个结果。
func (c *Chain) CloneVoice(ctx context.Context, referenceURL, prefix string) (string, error) {
if c.cloner == nil {
return "", ErrNotConfigured
@@ -61,14 +61,14 @@ func (c *Chain) CloneVoice(ctx context.Context, referenceURL, prefix string) (st
return c.cloner.CloneVoice(ctx, referenceURL, prefix)
}
// TTS walks the chain for synthesized audio.
// TTS 走链取合成音频。
func (c *Chain) TTS(ctx context.Context, text string) (Audio, error) {
audio, _, err := c.TTSWithProvider(ctx, text)
return audio, err
}
// TTSWithProvider is TTS but also reports the name of the provider rung that
// produced the audio.
// TTSWithProvider 即 TTS，但额外报告产出该音频的提供方
// 级别名。
func (c *Chain) TTSWithProvider(ctx context.Context, text string) (Audio, string, error) {
if len(c.steps) == 0 {
return Audio{}, "", ErrProviderFailed
@@ -88,32 +88,32 @@ func (c *Chain) TTSWithProvider(ctx context.Context, text string) (Audio, string
return Audio{}, "", fmt.Errorf("voice: %w: %v", ErrProviderFailed, lastErr)
}
// Option customizes a chain built by New.
// Option 定制由 New 构造的链。
type Option func(*chainConfig)
// chainConfig carries the assembled steps for New.
// chainConfig 承载 New 组装出的各级。
type chainConfig struct {
steps []Provider
}
// WithProviders overrides the provider steps assembled from config. Tests use it
// to inject deterministic mock providers instead of the real adaptation-point
// rungs.
// WithProviders 覆盖由配置组装出的提供方各级。测试用它
// 注入确定性的 mock 提供方，而不是真实的适配点
// 各级。
func WithProviders(steps ...Provider) Option {
return func(c *chainConfig) { c.steps = steps }
}
// New assembles a chain from cfg using the fixed degradation order
// cloud → local → edge-tts/espeak → silent.
// New 用固定降级顺序从 cfg 组装一条链：
// cloud → local → edge-tts/espeak → silent。
//
// - cloud is included only when a cloud voice credential or model is present
// (voiceConfigured) so a mis-configured build degrades quietly.
// - local is a pure adaptation point and is only included when supplied via
// WithProviders; by default it is skipped.
// - the edge-tts or espeak rung is included according to cfg.TTSProvider.
// - silent is always appended last so the chain never fails outright.
// - 仅当存在云端语音凭据或模型（voiceConfigured）时才纳入
// cloud，使配置有误的构建安静降级。
// - local 是纯适配点，仅当经 WithProviders 提供时才纳入；
// 默认跳过。
// - 依 cfg.TTSProvider 纳入 edge-tts 或 espeak 一级。
// - silent 始终追加在最后，使链绝不会直接失败。
//
// opts may supply a fully assembled step list to override this mapping.
// opts 可提供一份完整组装好的各级列表来覆盖上述映射。
func New(cfg config.VoiceConfig, opts ...Option) *Chain {
conf := &chainConfig{}
for _, o := range opts {
@@ -141,11 +141,11 @@ func New(cfg config.VoiceConfig, opts ...Option) *Chain {
return chain
}
// voiceConfigured reports whether any cloud voice credential or model is set, so
// the cloud rung is only added when the runtime intends to use DashScope. Any
// single present field (API key, base URL, or an STT/TTS model) makes the cloud
// rung worth trying; a missing key then makes the adapter return ErrNotConfigured
// and the chain degrades quietly.
// voiceConfigured 报告是否设置了任一云端语音凭据或模型，使
// 云端一级只在运行时有意使用 DashScope 时才加入。任一字段
// 存在（API key、base URL 或某个 STT/TTS 模型）都让云端
// 一级值得一试；随后缺失的 key 会让适配器返回 ErrNotConfigured，
// 链则安静降级。
func voiceConfigured(cfg config.VoiceConfig) bool {
return cfg.DashscopeAPIKey != "" || cfg.DashscopeBaseURL != "" || cfg.STTModel != "" || cfg.TTSModel != ""
}
internal/runtime/multimodal/voice/chain_test.go
+6 -6
View File
@@ -8,7 +8,7 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
)
// stubSTT is a mock STT returning a fixed result.
// stubSTT 是一个返回固定结果的 mock STT。
type stubSTT struct {
text string
err error
@@ -16,7 +16,7 @@ type stubSTT struct {
func (s *stubSTT) STT(_ context.Context, _ Audio) (string, error) { return s.text, s.err }
// stubTTS is a mock TTS returning a fixed result.
// stubTTS 是一个返回固定结果的 mock TTS。
type stubTTS struct {
audio Audio
err error
@@ -24,7 +24,7 @@ type stubTTS struct {
func (s *stubTTS) TTS(_ context.Context, _ string) (Audio, error) { return s.audio, s.err }
// stubProvider is a mock Provider carrying optional directions.
// stubProvider 是携带可选方向的 mock Provider。
type stubProvider struct {
name string
stt STT
@@ -158,8 +158,8 @@ func TestChain_Empty(t *testing.T) {
func TestNew_ConfigAssembly(t *testing.T) {
t.Parallel()
// With a cloud key and default edge-tts TTS, the chain starts at cloud and
// ends at silent.
// 配了云端 key 且 TTS 默认走 edge-tts 时，链从 cloud 开始、
// 到 silent 结束。
c := New(config.VoiceConfig{DashscopeAPIKey: "k"})
names := make([]string, 0, len(c.steps))
for _, p := range c.steps {
@@ -172,7 +172,7 @@ func TestNew_ConfigAssembly(t *testing.T) {
t.Errorf("first step = %q, want cloud", names[0])
}
// Without a key the cloud rung is skipped.
// 没有 key 时跳过云端一级。
c2 := New(config.VoiceConfig{})
foundCloud := false
for _, p := range c2.steps {
internal/runtime/multimodal/voice/cloud.go
+33 -33
View File
@@ -15,17 +15,17 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
)
// cloudMaxResponseBytes caps how much of a cloud voice response is read, so an
// oversized or malformed response cannot exhaust memory. The request timeout
// bounds a single call.
// cloudMaxResponseBytes 限制读取云端语音响应的体积，使过大
// 或畸形的响应无法耗尽内存。请求超时
// 约束单次调用。
const (
cloudMaxResponseBytes = 8 << 20
cloudHTTPTimeout = 180 * time.Second
)
// HTTPSTT transcribes audio by POSTing a JSON body to a cloud endpoint and
// reading {"text": "..."} back. It is the stubbed default STT implementation;
// the real DashScope/whisper-facing adapter is an adaptation point.
// HTTPSTT 通过向云端 endpoint POST 一个 JSON 请求体并
// 读回 {"text": "..."} 来转写音频。它是桩式的默认 STT 实现；
// 真正面向 DashScope/whisper 的适配器是一个适配点。
type HTTPSTT struct {
endpoint string
apiKey string
@@ -33,8 +33,8 @@ type HTTPSTT struct {
log *slog.Logger
}
// HTTPTTS synthesizes speech by POSTing a JSON body and reading the returned
// base64 audio. It is the stubbed default TTS implementation.
// HTTPTTS 通过 POST 一个 JSON 请求体并读取返回的
// base64 音频来合成语音。它是桩式的默认 TTS 实现。
type HTTPTTS struct {
endpoint string
apiKey string
@@ -42,7 +42,7 @@ type HTTPTTS struct {
log *slog.Logger
}
// HTTPOption customizes the client and logger of an HTTPSTT/HTTPTTS.
// HTTPOption 定制 HTTPSTT/HTTPTTS 的 client 与日志器。
type HTTPOption func(*httpConfig)
type httpConfig struct {
@@ -50,7 +50,7 @@ type httpConfig struct {
log *slog.Logger
}
// WithHTTPClient sets the *http.Client used for the call; nil keeps the default.
// WithHTTPClient 设置该调用所用的 *http.Client；nil 表示保持默认。
func WithHTTPClient(c *http.Client) HTTPOption {
return func(o *httpConfig) {
if c != nil {
@@ -59,7 +59,7 @@ func WithHTTPClient(c *http.Client) HTTPOption {
}
}
// WithLogger sets the logger used on failures; nil keeps a discard logger.
// WithLogger 设置失败时使用的日志器；nil 表示保持丢弃日志器。
func WithLogger(l *slog.Logger) HTTPOption {
return func(o *httpConfig) {
if l != nil {
@@ -68,7 +68,7 @@ func WithLogger(l *slog.Logger) HTTPOption {
}
}
// NewHTTPSTT builds an HTTPSTT for the given endpoint and API key.
// NewHTTPSTT 为给定 endpoint 与 API key 构造一个 HTTPSTT。
func NewHTTPSTT(endpoint, apiKey string, opts ...HTTPOption) *HTTPSTT {
h := &httpConfig{client: defaultHTTPClient(), log: discardLogger()}
for _, o := range opts {
@@ -77,7 +77,7 @@ func NewHTTPSTT(endpoint, apiKey string, opts ...HTTPOption) *HTTPSTT {
return &HTTPSTT{endpoint: strings.TrimRight(endpoint, "/"), apiKey: apiKey, client: h.client, log: h.log}
}
// NewHTTPTTS builds an HTTPTTS for the given endpoint and API key.
// NewHTTPTTS 为给定 endpoint 与 API key 构造一个 HTTPTTS。
func NewHTTPTTS(endpoint, apiKey string, opts ...HTTPOption) *HTTPTTS {
h := &httpConfig{client: defaultHTTPClient(), log: discardLogger()}
for _, o := range opts {
@@ -86,19 +86,19 @@ func NewHTTPTTS(endpoint, apiKey string, opts ...HTTPOption) *HTTPTTS {
return &HTTPTTS{endpoint: strings.TrimRight(endpoint, "/"), apiKey: apiKey, client: h.client, log: h.log}
}
// sttRequest is the JSON body sent to the STT endpoint.
// sttRequest 是发往 STT endpoint 的 JSON 请求体。
type sttRequest struct {
Audio string `json:"audio"`
Format string `json:"format"`
}
// sttResponse is the transcription returned by the STT endpoint.
// sttResponse 是 STT endpoint 返回的转写。
type sttResponse struct {
Text string `json:"text"`
}
// STT posts the audio and returns the recognized text. A blank endpoint returns
// ErrNotConfigured so the chain degrades.
// STT 发送音频并返回识别出的文字。endpoint 为空时返回
// ErrNotConfigured，链随之降级。
func (s *HTTPSTT) STT(ctx context.Context, audio Audio) (string, error) {
if s.endpoint == "" {
return "", ErrNotConfigured
@@ -122,19 +122,19 @@ func (s *HTTPSTT) STT(ctx context.Context, audio Audio) (string, error) {
return decoded.Text, nil
}
// ttsRequest is the JSON body sent to the TTS endpoint.
// ttsRequest 是发往 TTS endpoint 的 JSON 请求体。
type ttsRequest struct {
Text string `json:"text"`
}
// ttsResponse is the synthesized audio returned by the TTS endpoint.
// ttsResponse 是 TTS endpoint 返回的合成音频。
type ttsResponse struct {
Audio string `json:"audio"`
Format string `json:"format"`
}
// TTS posts the text and returns the decoded audio. A blank endpoint returns
// ErrNotConfigured so the chain degrades.
// TTS 发送文本并返回解码后的音频。endpoint 为空时返回
// ErrNotConfigured，链随之降级。
func (s *HTTPTTS) TTS(ctx context.Context, text string) (Audio, error) {
if s.endpoint == "" {
return Audio{}, ErrNotConfigured
@@ -169,7 +169,7 @@ func (s *HTTPTTS) TTS(ctx context.Context, text string) (Audio, error) {
return Audio{Format: format, Data: data}, nil
}
// postJSON POSTs a JSON payload, wires auth, and checks the status code.
// postJSON POST 一个 JSON 载荷，接好鉴权并检查状态码。
func postJSON(ctx context.Context, client *http.Client, apiKey, url string, payload []byte) (*http.Response, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
if err != nil {
@@ -190,41 +190,41 @@ func postJSON(ctx context.Context, client *http.Client, apiKey, url string, payl
return resp, nil
}
// defaultHTTPClient builds a client with a request timeout. A fresh client is
// returned per call rather than a package global, which the constraints forbid.
// defaultHTTPClient 构造一个带请求超时的 client。这里每次调用
// 返回新 client，而不是包级全局变量——后者为约束所禁止。
func defaultHTTPClient() *http.Client {
return &http.Client{Transport: http.DefaultTransport, Timeout: cloudHTTPTimeout}
}
// discardLogger returns a logger that drops all output.
// discardLogger 返回一个丢弃全部输出的日志器。
func discardLogger() *slog.Logger {
return slog.New(slog.NewTextHandler(io.Discard, nil))
}
// newDashboardSTT returns the cloud STT adapter for a DashScope config. A call
// returns ErrNotConfigured when no API key is set so the chain degrades.
// newDashboardSTT 为 DashScope 配置返回云端 STT 适配器。未设置
// API key 时调用会返回 ErrNotConfigured，链随之降级。
func newDashboardSTT(cfg config.VoiceConfig) STT {
return NewDashscopeSTT(cfg)
}
// newDashboardTTS returns the cloud TTS adapter for a DashScope config.
// newDashboardTTS 为 DashScope 配置返回云端 TTS 适配器。
func newDashboardTTS(cfg config.VoiceConfig) TTS {
return NewDashscopeTTS(cfg)
}
// newDashboardCloner returns the cloud voice-enrollment cloner for a DashScope
// config, used by the create_voice (声音复刻) endpoint.
// newDashboardCloner 为 DashScope 配置返回云端音色注册 cloner，
// 供 create_voice（声音复刻）endpoint 使用。
func newDashboardCloner(cfg config.VoiceConfig) VoiceCloner {
return NewDashscopeCloner(cfg)
}
// newEdgeTTS returns the edge-tts adapter point (not yet implemented).
// newEdgeTTS 返回 edge-tts 适配点（尚未实现）。
func newEdgeTTS() TTS { return notImplementedTTS{} }
// newEspeak returns the espeak adapter point (not yet implemented).
// newEspeak 返回 espeak 适配点（尚未实现）。
func newEspeak() TTS { return notImplementedTTS{} }
// notImplementedTTS is an adaptation point that always degrades.
// notImplementedTTS 是一个总是降级的适配点。
type notImplementedTTS struct{}
func (notImplementedTTS) TTS(_ context.Context, _ string) (Audio, error) {
internal/runtime/multimodal/voice/dashscope.go
+77 -77
View File
@@ -14,37 +14,37 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
)
// DashScope (Alibaba Bailian) STT/TTS adapters for the cloud rung of the voice
// chain. Requests follow the DashScope public API:
// 语音链云端一级的 DashScope（阿里百炼）STT/TTS 适配器。请求
// 遵循 DashScope 公开 API：
//
// - STT: POST {base}/services/aigc/multimodal-generation/generation
// (qwen-audio-3.0-asr-flash, base64 input audio)
// (qwen-audio-3.0-asr-flash，base64 输入音频)
// - TTS: POST {base}/services/audio/tts/SpeechSynthesizer
// (cosyvoice-v3-flash, synthesized by voice_id)
// (cosyvoice-v3-flash，按 voice_id 合成)
//
// Both take a non-streaming response here: STT returns the transcript in the
// output envelope; TTS (no X-DashScope-SSE header) returns a 24h audio URL that
// we download so the caller always gets the actual bytes. Audio format ↔ mime
// is mapped in both directions (mimeOf / the data: URI in the STT request).
// 两者在这里都取非流式响应：STT 从 output envelope 中返回
// 转写；TTS（不带 X-DashScope-SSE 头）返回一个 24h 音频 URL，我们
// 把它下载下来，使调用方总能拿到真实字节。音频格式 ↔ mime
// 双向映射（mimeOf / STT 请求中的 data: URI）。
const (
// defaultSTTSampleRate is the input audio sample rate the ASR expects.
// defaultSTTSampleRate 是 ASR 期望的输入音频采样率。
defaultSTTSampleRate = 16000
// dashscopeSTTPath is the multimodal-generation service path (ASR).
// dashscopeSTTPath 是 multimodal-generation 服务路径（ASR）。
dashscopeSTTPath = "/services/aigc/multimodal-generation/generation"
// dashscopeTTSPath is the SpeechSynthesizer service path (TTS).
// dashscopeTTSPath 是 SpeechSynthesizer 服务路径（TTS）。
dashscopeTTSPath = "/services/audio/tts/SpeechSynthesizer"
// dashscopeClonePath is the voice-customization (声音复刻 create_voice) path.
// dashscopeClonePath 是音色定制（声音复刻 create_voice）路径。
dashscopeClonePath = "/services/audio/tts/customization"
// defaultDashscopeBaseURL is the Bailian API root when none is configured.
// defaultDashscopeBaseURL 是未配置时使用的百炼 API 根地址。
defaultDashscopeBaseURL = "https://dashscope.aliyuncs.com/api/v1"
// defaultClonePrefix is the voice-name prefix when none is supplied.
// defaultClonePrefix 是未提供时的音色名前缀。
defaultClonePrefix = "cyrene"
// voiceEnrollmentModel is the DashScope voice-enrollment model ("create_voice").
// voiceEnrollmentModel 是 DashScope 音色注册模型（"create_voice"）。
voiceEnrollmentModel = "voice-enrollment"
)
// DashscopeSTT transcribes audio via DashScope multimodal-generation.
// DashscopeSTT 经 DashScope multimodal-generation 转写音频。
type DashscopeSTT struct {
endpoint string
apiKey string
@@ -55,8 +55,8 @@ type DashscopeSTT struct {
client *http.Client
}
// NewDashscopeSTT builds the DashScope STT adapter from cfg. Missing model /
// language / base URL fall back to the DashScope defaults.
// NewDashscopeSTT 从 cfg 构造 DashScope STT 适配器。缺失的 model /
// language / base URL 回退到 DashScope 默认值。
func NewDashscopeSTT(cfg config.VoiceConfig) *DashscopeSTT {
model := firstNonEmpty(cfg.STTModel, "qwen-audio-3.0-asr-flash")
language := firstNonEmpty(cfg.STTLanguage, "zh")
@@ -71,7 +71,7 @@ func NewDashscopeSTT(cfg config.VoiceConfig) *DashscopeSTT {
}
}
// STT posts the audio as a base64 data: URI and returns the recognized text.
// STT 把音频作为 base64 data: URI 发送并返回识别出的文字。
func (s *DashscopeSTT) STT(ctx context.Context, audio Audio) (string, error) {
if s.apiKey == "" {
return "", ErrNotConfigured
@@ -119,7 +119,7 @@ func (s *DashscopeSTT) STT(ctx context.Context, audio Audio) (string, error) {
return text, nil
}
// DashscopeTTS synthesizes speech video via DashScope SpeechSynthesizer.
// DashscopeTTS 经 DashScope SpeechSynthesizer 合成语音。
type DashscopeTTS struct {
endpoint string
apiKey string
@@ -131,8 +131,8 @@ type DashscopeTTS struct {
client *http.Client
}
// NewDashscopeTTS builds the DashScope TTS adapter from cfg. Missing model /
// voice / format / base URL fall back to the DashScope defaults.
// NewDashscopeTTS 从 cfg 构造 DashScope TTS 适配器。缺失的 model /
// voice / format / base URL 回退到 DashScope 默认值。
func NewDashscopeTTS(cfg config.VoiceConfig) *DashscopeTTS {
model := firstNonEmpty(cfg.TTSModel, "cosyvoice-v3-flash")
voiceID := firstNonEmpty(cfg.TTSVoiceID, "longxiaochun_v3")
@@ -153,9 +153,9 @@ func NewDashscopeTTS(cfg config.VoiceConfig) *DashscopeTTS {
}
}
// TTS synthesizes audio for text. The non-streaming DashScope response carries a
// 24h audio URL (or a base64 blob); we resolve it to bytes and return them so the
// caller holds a complete audio file.
// TTS 为文字合成音频。非流式的 DashScope 响应携带一个
// 24h 音频 URL（或一段 base64）；我们把它解析成字节并返回，
// 使调用方拿到完整的音频文件。
func (t *DashscopeTTS) TTS(ctx context.Context, text string) (Audio, error) {
if t.apiKey == "" {
return Audio{}, ErrNotConfigured
@@ -182,7 +182,7 @@ func (t *DashscopeTTS) TTS(ctx context.Context, text string) (Audio, error) {
if err != nil {
return Audio{}, fmt.Errorf("voice: %w: marshal: %v", ErrProviderFailed, err)
}
// No X-DashScope-SSE header → non-streaming URL response.
// 不带 X-DashScope-SSE 头 → 返回非流式 URL 响应。
body, err := dashscopePost(ctx, t.client, t.apiKey, t.endpoint, payload, "")
if err != nil {
return Audio{}, err
@@ -194,11 +194,11 @@ func (t *DashscopeTTS) TTS(ctx context.Context, text string) (Audio, error) {
return Audio{Format: t.format, Data: data}, nil
}
// EffectiveInstruction returns the instruction to send for this synthesis: a
// per-request override threaded through ctx wins, else the configured default. An
// empty result means the request carries no instruction. A system voice never gets
// a free-form instruction (see canInstruct), because cosyvoice v3 system voices
// require a fixed instruction format.
// EffectiveInstruction 返回本次合成要发送的 instruction：经 ctx 透传的
// 逐请求覆盖优先，否则用配置的默认值。结果为空表示该请求
// 不携带 instruction。系统音色永远不会收到自由形式的 instruction
// （见 canInstruct），因为 cosyvoice v3 系统音色
// 要求固定的 instruction 格式。
func (t *DashscopeTTS) EffectiveInstruction(ctx context.Context) string {
if !canInstruct(t.voiceID) {
return ""
@@ -209,16 +209,16 @@ func (t *DashscopeTTS) EffectiveInstruction(ctx context.Context) string {
return t.instruction
}
// canInstruct reports whether voiceID accepts a free-form instruction. cosyvoice v3
// system voices (the long*_v3 family, e.g. longxiaochun_v3) require a fixed
// instruction format; a cloned/designed voice (声音复刻, whose id never ends in
// "_v3") accepts an arbitrary instruction.
// canInstruct 报告 voiceID 是否接受自由形式的 instruction。cosyvoice v3
// 系统音色（long*_v3 系列，例如 longxiaochun_v3）要求固定的
// instruction 格式；复刻/设计音色（声音复刻，其 id 永不以
// "_v3" 结尾）接受任意 instruction。
func canInstruct(voiceID string) bool {
return !strings.HasSuffix(voiceID, "_v3")
}
// audioBytes resolves the synthesized audio from the DashScope response: a 24h
// URL is downloaded, or an inline base64 blob is decoded.
// audioBytes 从 DashScope 响应中解析合成音频：24h
// URL 会被下载，内联的 base64 块会被解码。
func (t *DashscopeTTS) audioBytes(ctx context.Context, body []byte) ([]byte, error) {
var r dashscopeTTSResponse
if err := json.Unmarshal(body, &r); err != nil {
@@ -241,8 +241,8 @@ func (t *DashscopeTTS) audioBytes(ctx context.Context, body []byte) ([]byte, err
return nil, fmt.Errorf("voice: %w: no audio in response", ErrProviderFailed)
}
// download fetches an audio URL into memory, capping the size so an oversized
// media response cannot exhaust memory.
// download 把音频 URL 抓进内存，并限制体积，使过大的
// 媒体响应无法耗尽内存。
func (t *DashscopeTTS) download(ctx context.Context, url string) ([]byte, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
@@ -263,10 +263,10 @@ func (t *DashscopeTTS) download(ctx context.Context, url string) ([]byte, error)
return data, nil
}
// DashscopeCloner creates custom TTS voices via the DashScope voice-enrollment
// API (声音复刻 create_voice). The reference audio must be a public URL — the
// create_voice action only accepts input.url (no base64). The returned voice_id is
// bound to TTSModel, so target_model must match the model used at synthesis time.
// DashscopeCloner 经 DashScope 音色注册 API
// （声音复刻 create_voice）创建自定义 TTS 音色。参考音频必须是公开
// URL —— create_voice 动作只接受 input.url（不支持 base64）。返回的 voice_id
// 绑定到 TTSModel，因此 target_model 必须与合成时使用的模型一致。
type DashscopeCloner struct {
endpoint string
apiKey string
@@ -274,9 +274,9 @@ type DashscopeCloner struct {
client *http.Client
}
// NewDashscopeCloner builds the DashScope voice cloner from cfg. Missing model /
// base URL fall back to the DashScope defaults; the model tracks TTSModel so the
// cloned voice is usable by the TTS rung (target_model must match).
// NewDashscopeCloner 从 cfg 构造 DashScope 音色复刻器。缺失的 model /
// base URL 回退到 DashScope 默认值；model 跟随 TTSModel，使
// 复刻出的音色可被 TTS 一级使用（target_model 必须一致）。
func NewDashscopeCloner(cfg config.VoiceConfig) *DashscopeCloner {
return &DashscopeCloner{
endpoint: dashscopeEndpoint(cfg.DashscopeBaseURL) + dashscopeClonePath,
@@ -286,9 +286,9 @@ func NewDashscopeCloner(cfg config.VoiceConfig) *DashscopeCloner {
}
}
// CloneVoice submits a create_voice request and returns the created voice_id. It
// is the adapter behind the REST /api/v1/audio/voice-clone endpoint. A missing API
// key returns ErrNotConfigured; an empty URL or an invalid prefix is rejected.
// CloneVoice 提交一次 create_voice 请求并返回创建出的 voice_id。它
// 是 REST /api/v1/audio/voice-clone endpoint 背后的适配器。缺少 API
// key 时返回 ErrNotConfigured；空 URL 或非法 prefix 会被拒绝。
func (d *DashscopeCloner) CloneVoice(ctx context.Context, referenceURL, prefix string) (string, error) {
if d.apiKey == "" {
return "", ErrNotConfigured
@@ -333,9 +333,9 @@ func (d *DashscopeCloner) CloneVoice(ctx context.Context, referenceURL, prefix s
return resp.Output.VoiceID, nil
}
// normalizeClonePrefix trims and validates the voice-name prefix. An empty value
// falls back to defaultClonePrefix; the result must be ≤10 letter/digit chars
// (the voice-enrollment prefix constraint).
// normalizeClonePrefix 去空白并校验音色名前缀。空值
// 回退到 defaultClonePrefix；结果必须是 ≤10 个字母/数字字符
// （音色注册对 prefix 的约束）。
func normalizeClonePrefix(prefix string) (string, error) {
prefix = strings.TrimSpace(prefix)
if prefix == "" {
@@ -352,8 +352,8 @@ func normalizeClonePrefix(prefix string) (string, error) {
return prefix, nil
}
// dashscopeEndpoint returns the DashScope API base with a trailing slash trimmed,
// defaulting to the public Bailian root when none is configured.
// dashscopeEndpoint 返回去掉尾部斜杠的 DashScope API 根地址，
// 未配置时默认为公开的百炼根地址。
func dashscopeEndpoint(baseURL string) string {
base := strings.TrimRight(baseURL, "/")
if base == "" {
@@ -362,7 +362,7 @@ func dashscopeEndpoint(baseURL string) string {
return base
}
// firstNonEmpty returns a when non-empty, else b.
// firstNonEmpty 在 a 非空时返回 a，否则返回 b。
func firstNonEmpty(a, b string) string {
if a != "" {
return a
@@ -370,9 +370,9 @@ func firstNonEmpty(a, b string) string {
return b
}
// dashscopePost POSTs a JSON payload with the DashScope bearer auth and an
// optional X-DashScope-SSE header, returning the decoded response body. A non-200
// status is wrapped with the DashScope error body.
// dashscopePost POST 一个 JSON 载荷，带上 DashScope bearer 鉴权与可选的
// X-DashScope-SSE 头，返回解码后的响应体。非 200
// 状态会被包装上 DashScope 的错误体。
func dashscopePost(ctx context.Context, client *http.Client, apiKey, url string, payload []byte, sse string) ([]byte, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
if err != nil {
@@ -400,8 +400,8 @@ func dashscopePost(ctx context.Context, client *http.Client, apiKey, url string,
return body, nil
}
// extractSTTText pulls the transcript out of a DashScope ASR response. The ASR
// output shape varies by model, so several candidate paths are tried.
// extractSTTText 从 DashScope ASR 响应中取出转写。ASR
// 的输出形状随模型而异，因此按多个候选路径依次尝试。
func extractSTTText(body []byte) (string, error) {
var r dashscopeSTTResponse
if err := json.Unmarshal(body, &r); err != nil {
@@ -426,7 +426,7 @@ func extractSTTText(body []byte) (string, error) {
return r.Text, nil
}
// mimeOf maps an audio format to its MIME type for the data: URI / Content-Type.
// mimeOf 把音频格式映射为其 MIME 类型，供 data: URI / Content-Type 使用。
func mimeOf(format string) string {
switch strings.ToLower(format) {
case "mp3", "mpeg":
@@ -440,7 +440,7 @@ func mimeOf(format string) string {
}
}
// dashscopeSTTResponse is the DashScope ASR response envelope.
// dashscopeSTTResponse 是 DashScope ASR 响应 envelope。
type dashscopeSTTResponse struct {
Output struct {
Output struct {
@@ -461,7 +461,7 @@ type dashscopeSTTResponse struct {
Text string `json:"text"`
}
// dashscopeTTSResponse is the DashScope TTS response envelope.
// dashscopeTTSResponse 是 DashScope TTS 响应 envelope。
type dashscopeTTSResponse struct {
Output struct {
Audio struct {
@@ -471,66 +471,66 @@ type dashscopeTTSResponse struct {
} `json:"output"`
}
// dashscopeSTTRequest is the ASR request body.
// dashscopeSTTRequest 是 ASR 请求体。
type dashscopeSTTRequest struct {
Model string `json:"model"`
Input dashscopeSTTInput `json:"input"`
Parameters dashscopeSTTParameters `json:"parameters"`
}
// dashscopeSTTInput carries the multimodal messages list.
// dashscopeSTTInput 承载多模态消息列表。
type dashscopeSTTInput struct {
Messages []dashscopeSTTMessage `json:"messages"`
}
// dashscopeSTTMessage is one ASR user turn.
// dashscopeSTTMessage 是一个 ASR 用户回合。
type dashscopeSTTMessage struct {
Role string `json:"role"`
Content []dashscopeSTTContent `json:"content"`
}
// dashscopeSTTContent is one audio content block.
// dashscopeSTTContent 是一个音频内容块。
type dashscopeSTTContent struct {
Type string `json:"type"`
InputAudio dashscopeInputAudio `json:"input_audio"`
}
// dashscopeInputAudio carries the base64 data: URI audio.
// dashscopeInputAudio 承载 base64 data: URI 音频。
type dashscopeInputAudio struct {
Data string `json:"data"`
}
// dashscopeSTTParameters tunes the ASR request.
// dashscopeSTTParameters 调整 ASR 请求。
type dashscopeSTTParameters struct {
Format string `json:"format"`
SampleRate int `json:"sample_rate"`
LanguageHints []string `json:"language_hints,omitempty"`
}
// dashscopeTTSRequest is the TTS request body.
// dashscopeTTSRequest 是 TTS 请求体。
type dashscopeTTSRequest struct {
Model string `json:"model"`
Input dashscopeTTSInput `json:"input"`
}
// dashscopeTTSInput carries text + voice + output format.
// dashscopeTTSInput 承载文字 + 音色 + 输出格式。
type dashscopeTTSInput struct {
Text string `json:"text"`
Voice string `json:"voice"`
Format string `json:"format"`
SampleRate int `json:"sample_rate"`
// Instruction is the CosyVoice emotion/tone instruction; omitempty keeps a
// system voice (which must use a fixed instruction) free of a free-form one.
// Instruction 是 CosyVoice 的情绪/语气 instruction；omitempty 使
// 系统音色（必须使用固定 instruction）不携带自由形式的 instruction。
Instruction string `json:"instruction,omitempty"`
}
// dashscopeCloneRequest is the voice-enrollment create_voice request body.
// dashscopeCloneRequest 是音色注册 create_voice 请求体。
type dashscopeCloneRequest struct {
Model string `json:"model"`
Input dashscopeCloneInput `json:"input"`
}
// dashscopeCloneInput carries the create_voice action parameters.
// dashscopeCloneInput 承载 create_voice 动作参数。
type dashscopeCloneInput struct {
Action string `json:"action"`
TargetModel string `json:"target_model"`
@@ -538,8 +538,8 @@ type dashscopeCloneInput struct {
URL string `json:"url"`
}
// dashscopeCloneResponse is the voice-enrollment response envelope. A top-level
// message marks a model-level error surfaced even on an HTTP 200.
// dashscopeCloneResponse 是音色注册响应 envelope。顶层
// message 表示模型级错误——即使 HTTP 200 也会暴露。
type dashscopeCloneResponse struct {
Output struct {
VoiceID string `json:"voice_id"`
internal/runtime/multimodal/voice/dashscope_live_test.go
+13 -13
View File
@@ -12,9 +12,9 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
)
// TestDashscopeLive verifies the real Alibaba Bailian STT + TTS end to end. It is
// excluded from the default suite (build tag dashscope_live) so `go test ./...`
// never hits the paid API. Run it explicitly with the key sourced from .env:
// TestDashscopeLive 端到端验证真实的阿里百炼 STT + TTS。它
// 被排除在默认测试集之外（构建标签 dashscope_live），使 `go test ./...`
// 绝不触碰付费 API。用从 .env 取到的 key 显式运行：
//
// set -a; source .env; set +a
// go test -tags dashscope_live -run TestDashscopeLive -v ./internal/runtime/multimodal/voice/
@@ -25,7 +25,7 @@ func TestDashscopeLive(t *testing.T) {
}
cfg := config.VoiceConfig{DashscopeAPIKey: key}
// TTS: synthesize speech for a short line.
// TTS：为一句短文本合成语音。
tts := NewDashscopeTTS(cfg)
audio, err := tts.TTS(context.Background(), "你好，我是昔涟")
if err != nil {
@@ -36,7 +36,7 @@ func TestDashscopeLive(t *testing.T) {
t.Fatal("TTS returned empty audio")
}
// STT closed loop: transcribe the synthesized speech back to text.
// STT 闭环：把合成的语音转写回文字。
stt := NewDashscopeSTT(cfg)
text, err := stt.STT(context.Background(), Audio{Format: "wav", Data: audio.Data})
if err != nil {
@@ -44,7 +44,7 @@ func TestDashscopeLive(t *testing.T) {
}
t.Logf("STT (of TTS audio): text=%q", text)
// STT on a generated silence wav, to confirm the empty-audio path is accepted.
// 对生成的静音 wav 做 STT，确认空音频路径可被接受。
silence := silentWAVBytes(1, 16000)
sttText, sttErr := stt.STT(context.Background(), Audio{Format: "wav", Data: silence})
if sttErr != nil {
@@ -53,8 +53,8 @@ func TestDashscopeLive(t *testing.T) {
t.Logf("STT (silence): text=%q", sttText)
}
// Exercise the degrading chain (the same object the gateway wires), proving it
// returns real bytes/text rather than degrading to the silent terminal rung.
// 走一遍降级链（网关接线的就是同一个对象），证明它
// 返回真实的字节/文字，而不是降级到静默末端一级。
ch := New(cfg)
chTTS, chTTSErr := ch.TTS(context.Background(), "你好，我是昔涟")
if chTTSErr != nil {
@@ -74,21 +74,21 @@ func TestDashscopeLive(t *testing.T) {
}
}
// silentWAVBytes builds a mono 16-bit 16 kHz silence WAV of durS seconds.
// silentWAVBytes 构造 durS 秒的单声道 16 位 16 kHz 静音 WAV。
func silentWAVBytes(durS, sampleRate int) []byte {
dataLen := durS * sampleRate * 2
buf := &bytes.Buffer{}
// RIFF header + fmt chunk + data chunk.
// RIFF 头 + fmt 块 + data 块。
buf.WriteString("RIFF")
_ = binary.Write(buf, binary.LittleEndian, uint32(36+dataLen))
buf.WriteString("WAVEfmt ")
_ = binary.Write(buf, binary.LittleEndian, uint32(16))
_ = binary.Write(buf, binary.LittleEndian, uint16(1)) // PCM
_ = binary.Write(buf, binary.LittleEndian, uint16(1)) // mono
_ = binary.Write(buf, binary.LittleEndian, uint16(1)) // 单声道
_ = binary.Write(buf, binary.LittleEndian, uint32(sampleRate))
_ = binary.Write(buf, binary.LittleEndian, uint32(sampleRate*2))
_ = binary.Write(buf, binary.LittleEndian, uint16(2)) // block align
_ = binary.Write(buf, binary.LittleEndian, uint16(16)) // bits per sample
_ = binary.Write(buf, binary.LittleEndian, uint16(2)) // 块对齐
_ = binary.Write(buf, binary.LittleEndian, uint16(16)) // 每样本位数
buf.WriteString("data")
_ = binary.Write(buf, binary.LittleEndian, uint32(dataLen))
buf.Write(make([]byte, dataLen))
internal/runtime/multimodal/voice/errors.go
+7 -7
View File
@@ -2,17 +2,17 @@ package voice
import "errors"
// Sentinel errors returned by the voice package. Each is wrapped with %w so
// callers can test for a category while keeping the cause.
// voice 包返回的哨兵错误。每个错误都以 %w 包装，
// 使调用方能按类别判断，同时保留原始原因。
var (
// ErrProviderFailed is returned when every provider in a chain fails.
// ErrProviderFailed 在一条链上所有提供方都失败时返回。
ErrProviderFailed = errors.New("voice: all providers failed")
// ErrNotConfigured is returned when a provider has no endpoint/setting.
// ErrNotConfigured 在提供方缺少 endpoint/配置项时返回。
ErrNotConfigured = errors.New("voice: provider not configured")
// ErrNotImplemented is returned by an adaptation-point provider.
// ErrNotImplemented 由适配点提供方返回。
ErrNotImplemented = errors.New("voice: provider not implemented")
// ErrEmptyText is returned when TTS receives empty text.
// ErrEmptyText 在 TTS 收到空文本时返回。
ErrEmptyText = errors.New("voice: empty text")
// ErrClosed is returned when a service call arrives after Close.
// ErrClosed 在 Close 之后仍有服务调用到达时返回。
ErrClosed = errors.New("voice: service closed")
)
internal/runtime/multimodal/voice/provider.go
+24 -24
View File
@@ -2,76 +2,76 @@ package voice
import "context"
// Provider is one rung in the voice degradation chain. It may implement zero,
// one, or both directions; a nil return means that direction is not available
// on this rung and the chain moves to the next.
// Provider 是语音降级链上的一级。它可实现零个、一个
// 或两个方向；返回 nil 表示该方向在此级上不可用，
// 链会移向下一级。
type Provider interface {
// Name returns a stable provider identifier.
// Name 返回稳定的提供方标识。
Name() string
// STT returns the speech-to-text implementation, or nil when the provider
// cannot transcribe.
// STT 返回语音转文字实现，提供方无法转写时
// 返回 nil。
STT() STT
// TTS returns the text-to-speech implementation, or nil when the provider
// cannot synthesize.
// TTS 返回文字转语音实现，提供方无法合成时
// 返回 nil。
TTS() TTS
}
// StaticProvider is a Provider with a fixed name whose STT/TTS are set at
// construction. It is used by the concrete providers below.
// StaticProvider 是名字固定、STT/TTS 在构造时设定的
// Provider。下面各具体提供方都用它。
type StaticProvider struct {
name string
stt STT
tts TTS
}
// Name returns the provider identifier.
// Name 返回提供方标识。
func (p *StaticProvider) Name() string { return p.name }
// STT returns the configured STT, or nil.
// STT 返回配置的 STT，可能为 nil。
func (p *StaticProvider) STT() STT { return p.stt }
// TTS returns the configured TTS, or nil.
// TTS 返回配置的 TTS，可能为 nil。
func (p *StaticProvider) TTS() TTS { return p.tts }
// NewProvider builds a Provider with the given name and optional directions it
// supports.
// NewProvider 用给定名字及其支持的可选方向构造一个
// Provider。
func NewProvider(name string, stt STT, tts TTS) *StaticProvider {
return &StaticProvider{name: name, stt: stt, tts: tts}
}
// CloudProvider is the cloud rung of the chain. It is an adaptation point: the
// real STT/TTS implementations are wired in via NewProvider with cloud adapters.
// CloudProvider 是链上的云端一级。它是一个适配点：
// 真实的 STT/TTS 实现经 NewProvider 与云端适配器接入。
func CloudProvider(stt STT, tts TTS) *StaticProvider {
return NewProvider("cloud", stt, tts)
}
// LocalProvider is the local-model rung of the chain.
// LocalProvider 是链上的本地模型一级。
func LocalProvider(stt STT, tts TTS) *StaticProvider {
return NewProvider("local", stt, tts)
}
// EdgeTTSProvider is the edge-tts rung (text-to-speech only).
// EdgeTTSProvider 是 edge-tts 一级（仅文字转语音）。
func EdgeTTSProvider(tts TTS) *StaticProvider {
return NewProvider("edge-tts", nil, tts)
}
// EspeakProvider is the espeak rung (text-to-speech only).
// EspeakProvider 是 espeak 一级（仅文字转语音）。
func EspeakProvider(tts TTS) *StaticProvider {
return NewProvider("espeak", nil, tts)
}
// SilentProvider is the terminal rung. It always succeeds, returning an empty
// transcription and empty audio, so a chain that includes it never errors.
// SilentProvider 是末端一级。它总是成功，返回空
// 转写与空音频，因此包含它的链永不报错。
func SilentProvider() *StaticProvider {
return NewProvider("silent", silenceSTT{}, silenceTTS{})
}
// silenceSTT is the silent STT rung; it returns an empty transcription.
// silenceSTT 是静默 STT 一级；它返回空转写。
type silenceSTT struct{}
func (silenceSTT) STT(_ context.Context, _ Audio) (string, error) { return "", nil }
// silenceTTS is the silent TTS rung; it returns empty audio.
// silenceTTS 是静默 TTS 一级；它返回空音频。
type silenceTTS struct{}
func (silenceTTS) TTS(_ context.Context, _ string) (Audio, error) {
internal/runtime/multimodal/voice/service.go
+31 -31
View File
@@ -6,11 +6,11 @@ import (
"sync"
)
// Service runs STT/TTS requests on a background worker pool so caller
// goroutines (the agent loop) are never blocked by provider latency. Each
// request is enqueued on a jobs channel and answered on a per-job result
// channel; a canceled caller context or a closed service unblocks the caller
// immediately and no worker goroutine is leaked. It is safe for concurrent use.
// Service 在后台工作池上运行 STT/TTS 请求，使调用方
// goroutine（智能体循环）绝不会被提供方延迟阻塞。每个
// 请求入队到 jobs channel，并在每个 job 自己的结果
// channel 上应答；调用方 context 被取消或服务已关闭时，
// 调用方立刻解除阻塞，且不泄漏任何 worker goroutine。它可安全并发使用。
type Service struct {
chain *Chain
jobs chan job
@@ -22,11 +22,11 @@ type Service struct {
closed bool
}
// ServiceOption customizes a Service.
// ServiceOption 定制 Service。
type ServiceOption func(*Service)
// WithWorkers sets the worker-pool size. Values <= 0 are ignored and the
// default single worker is kept.
// WithWorkers 设置工作池大小。小于等于 0 的值被忽略，
// 保留默认的单 worker。
func WithWorkers(n int) ServiceOption {
return func(s *Service) {
if n > 0 {
@@ -35,7 +35,7 @@ func WithWorkers(n int) ServiceOption {
}
}
// jobKind selects the operation a worker performs.
// jobKind 选择 worker 执行的操作。
type jobKind int
const (
@@ -43,7 +43,7 @@ const (
jobTTS
)
// job is one request enqueued by the caller.
// job 是调用方入队的一个请求。
type job struct {
kind jobKind
audio Audio
@@ -51,7 +51,7 @@ type job struct {
res chan jobResult
}
// jobResult carries the outcome written back to the caller.
// jobResult 承载写回调用方的结果。
type jobResult struct {
text string
audio Audio
@@ -59,7 +59,7 @@ type jobResult struct {
err error
}
// NewService builds a Service backed by chain and starts the worker pool.
// NewService 构造一个由 chain 支撑的 Service，并启动工作池。
func NewService(chain *Chain, opts ...ServiceOption) *Service {
bg, cancel := context.WithCancel(context.Background())
s := &Service{
@@ -79,7 +79,7 @@ func NewService(chain *Chain, opts ...ServiceOption) *Service {
return s
}
// worker consumes jobs until the service closes.
// worker 消费 job 直到服务关闭。
func (s *Service) worker() {
defer s.wg.Done()
for {
@@ -92,10 +92,10 @@ func (s *Service) worker() {
}
}
// run executes a job and delivers the result. Providers run under the service's
// background context so Close cancels in-flight work and no worker goroutine is
// leaked; the result is written to a buffered channel so a caller that already
// returned never blocks the worker.
// run 执行一个 job 并投递结果。提供方在服务的
// 后台 context 下运行，因此 Close 会取消在途工作，且不泄漏
// worker goroutine；结果写入带缓冲的 channel，因此已
// 返回的调用方绝不会阻塞该 worker。
func (s *Service) run(j job) {
res := jobResult{}
switch j.kind {
@@ -107,15 +107,15 @@ func (s *Service) run(j job) {
j.res <- res
}
// STT enqueues a transcription request and waits for the result. ctx cancels
// the wait and the underlying provider call.
// STT 入队一个转写请求并等待结果。ctx 会取消
// 等待以及底层提供方调用。
func (s *Service) STT(ctx context.Context, audio Audio) (string, error) {
text, _, err := s.STTWithProvider(ctx, audio)
return text, err
}
// STTWithProvider is STT but also reports the provider rung that produced the
// transcription.
// STTWithProvider 即 STT，但额外报告产出该转写的
// 提供方级别名。
func (s *Service) STTWithProvider(ctx context.Context, audio Audio) (string, string, error) {
res, err := s.submit(ctx, job{kind: jobSTT, audio: audio, res: make(chan jobResult, 1)})
if err != nil {
@@ -124,15 +124,15 @@ func (s *Service) STTWithProvider(ctx context.Context, audio Audio) (string, str
return res.text, res.provider, res.err
}
// TTS enqueues a synthesis request and waits for the result. ctx cancels the
// wait and the underlying provider call.
// TTS 入队一个合成请求并等待结果。ctx 会取消
// 等待以及底层提供方调用。
func (s *Service) TTS(ctx context.Context, text string) (Audio, error) {
audio, _, err := s.TTSWithProvider(ctx, text)
return audio, err
}
// TTSWithProvider is TTS but also reports the provider rung that produced the
// audio.
// TTSWithProvider 即 TTS，但额外报告产出该音频的
// 提供方级别名。
func (s *Service) TTSWithProvider(ctx context.Context, text string) (Audio, string, error) {
res, err := s.submit(ctx, job{kind: jobTTS, text: text, res: make(chan jobResult, 1)})
if err != nil {
@@ -141,13 +141,13 @@ func (s *Service) TTSWithProvider(ctx context.Context, text string) (Audio, stri
return res.audio, res.provider, res.err
}
// CloneVoice creates a custom voice, delegating to the underlying chain. It is a
// one-shot admin operation (not a worker-pool job), so it runs directly.
// CloneVoice 创建自定义音色，交由底层链处理。它是一次性
// 管理操作（不是工作池 job），因此直接运行。
func (s *Service) CloneVoice(ctx context.Context, referenceURL, prefix string) (string, error) {
return s.chain.CloneVoice(ctx, referenceURL, prefix)
}
// submit enqueues j and blocks until the result or a cancellation.
// submit 把 j 入队并阻塞，直到拿到结果或发生取消。
func (s *Service) submit(ctx context.Context, j job) (jobResult, error) {
select {
case s.jobs <- j:
@@ -166,9 +166,9 @@ func (s *Service) submit(ctx context.Context, j job) (jobResult, error) {
}
}
// Close cancels the worker pool and waits for in-flight jobs to finish. It is
// safe to call once; later calls are no-ops. In-flight provider calls are
// bounded by each provider's own context timeout, so Close returns promptly.
// Close 取消工作池并等待在途 job 结束。调用一次是
// 安全的；后续调用为空操作。在途提供方调用由各提供方
// 自己的 context 超时兜底，因此 Close 会迅速返回。
func (s *Service) Close() {
s.mu.Lock()
defer s.mu.Unlock()
internal/runtime/multimodal/voice/service_test.go
+1 -1
View File
@@ -43,7 +43,7 @@ func TestService_CloseStopsNewCalls(t *testing.T) {
}
}
// blockingSTT blocks until its context is canceled, marking that it started.
// blockingSTT 会阻塞到它的 context 被取消，同时标记它已启动。
type blockingSTT struct {
started chan struct{}
once sync.Once
internal/runtime/multimodal/voice/voice.go
+29 -29
View File
@@ -1,60 +1,60 @@
// Package voice implements asynchronous speech-to-text and text-to-speech for
// the Cyrene runtime, following DevDocs/design/06-多模态.md §1.
// Package voice 为 Cyrene 运行时实现异步语音转文字与文字转语音，
// 遵循 DevDocs/design/06-多模态.md §1。
//
// Voice input (STT) is transcribed to text and fed into the same agent pipeline
// as a chat message; the reply is synthesized (TTS) back to audio. Both
// directions degrade through a provider chain — cloud → local → edge-tts/espeak
// → silent — so an unavailable provider falls through to the next rung instead
// of failing the whole turn. The stub default implementations are HTTP-based and
// testable with a stdlib httptest server; real cloud/local providers remain
// adaptation points for later milestones.
// 语音输入（STT）被转写为文字，并作为一条 chat 消息进入同一条智能体
// 流水线；回复则被合成（TTS）回音频。两个
// 方向都经一条提供方链降级 —— cloud → local → edge-tts/espeak
// → silent —— 因此某个提供方不可用时会落到下一级，而不是
// 让整个 turn 失败。默认实现是 HTTP 桩实现，可用
// 标准库 httptest 服务器测试；真实的云端/本地提供方仍作为
// 后续里程碑的适配点。
package voice
import "context"
// Audio is a piece of audio data plus its encoding.
// Audio 是一段音频数据及其编码。
type Audio struct {
// Format is the encoding, e.g. "wav", "mp3", "ogg".
// Format 是编码格式，例如 "wav"、"mp3"、"ogg"。
Format string
// Data is the raw audio bytes.
// Data 是原始音频字节。
Data []byte
}
// STT converts audio to text.
// STT 把音频转换成文字。
type STT interface {
// STT transcribes audio and returns the spoken text. ctx controls
// cancellation and must be honored.
// STT 转写音频并返回说出的文字。ctx 控制
// 取消，必须被遵守。
STT(ctx context.Context, audio Audio) (string, error)
}
// TTS synthesizes speech audio from text.
// TTS 从文字合成语音音频。
type TTS interface {
// TTS synthesizes audio from text. ctx controls cancellation and must be
// honored.
// TTS 从文字合成音频。ctx 控制取消，必须
// 被遵守。
TTS(ctx context.Context, text string) (Audio, error)
}
// VoiceCloner creates a custom voice (声音复刻) from a public reference audio URL.
// A nil-cloner provider (no cloud rung configured) returns ErrNotConfigured.
// VoiceCloner 从公开的参考音频 URL 创建自定义音色（声音复刻）。
// 未配置 cloner 的提供方（云端一级未配置）返回 ErrNotConfigured。
type VoiceCloner interface {
// CloneVoice creates a custom voice and returns its voice_id. referenceURL is
// a public audio URL; prefix is the voice-name prefix (≤10 alphanumeric chars).
// CloneVoice 创建自定义音色并返回其 voice_id。referenceURL 是
// 公开音频 URL；prefix 是音色名前缀（≤10 个字母数字字符）。
CloneVoice(ctx context.Context, referenceURL, prefix string) (string, error)
}
// ctxKeyTTSInstruction is the context key for a per-request TTS instruction.
// The TTS interface only carries (ctx, text), so an optional instruction is
// threaded through ctx to reach the adapter without widening the interface.
// ctxKeyTTSInstruction 是逐请求 TTS 指令的 context 键。
// TTS 接口只携带 (ctx, text)，因此可选指令经
// ctx 透传以抵达适配器，而无需拓宽该接口。
type ctxKeyTTSInstruction struct{}
// WithTTSInstruction returns ctx carrying an optional per-request TTS instruction
// (emotion/tone) that overrides the configured VOICE_TTS_INSTRUCTION for one call.
// WithTTSInstruction 返回携带一条逐请求 TTS 指令
// （情绪/语气）的 ctx，该指令对这一次调用覆盖配置里的 VOICE_TTS_INSTRUCTION。
func WithTTSInstruction(ctx context.Context, instruction string) context.Context {
return context.WithValue(ctx, ctxKeyTTSInstruction{}, instruction)
}
// TTSInstructionFromContext returns the per-request TTS instruction set by
// WithTTSInstruction, or "" when none is carried.
// TTSInstructionFromContext 返回由 WithTTSInstruction 设置的逐请求
// TTS 指令，未携带时返回 ""。
func TTSInstructionFromContext(ctx context.Context) string {
if v, ok := ctx.Value(ctxKeyTTSInstruction{}).(string); ok {
return v
internal/runtime/multimodal/voice/voice_clone_test.go
+18 -18
View File
@@ -12,8 +12,8 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
)
// TestDashscopeCloner_Ok asserts the create_voice request body shape
// (model/action/target_model/prefix/url) and the voice_id parsing.
// TestDashscopeCloner_Ok 断言 create_voice 请求体的形状
// （model/action/target_model/prefix/url）以及 voice_id 的解析。
func TestDashscopeCloner_Ok(t *testing.T) {
t.Parallel()
var gotBody map[string]any
@@ -61,8 +61,8 @@ func TestDashscopeCloner_Ok(t *testing.T) {
}
}
// TestDashscopeCloner_DefaultPrefix asserts the empty prefix falls back to the
// configured VOICE_CLONE_PREFIX default ("cyrene").
// TestDashscopeCloner_DefaultPrefix 断言空前缀回退到
// 配置的 VOICE_CLONE_PREFIX 默认值（"cyrene"）。
func TestDashscopeCloner_DefaultPrefix(t *testing.T) {
t.Parallel()
var gotBody map[string]any
@@ -83,8 +83,8 @@ func TestDashscopeCloner_DefaultPrefix(t *testing.T) {
}
}
// TestDashscopeCloner_TargetModelOverride asserts target_model tracks the config
// TTSModel (must match the synthesis model).
// TestDashscopeCloner_TargetModelOverride 断言 target_model 跟随配置的
// TTSModel（必须与合成模型一致）。
func TestDashscopeCloner_TargetModelOverride(t *testing.T) {
t.Parallel()
var gotBody map[string]any
@@ -105,7 +105,7 @@ func TestDashscopeCloner_TargetModelOverride(t *testing.T) {
}
}
// TestDashscopeCloner_NotConfigured asserts a missing API key degrades.
// TestDashscopeCloner_NotConfigured 断言缺少 API key 时降级。
func TestDashscopeCloner_NotConfigured(t *testing.T) {
t.Parallel()
cloner := NewDashscopeCloner(config.VoiceConfig{})
@@ -114,7 +114,7 @@ func TestDashscopeCloner_NotConfigured(t *testing.T) {
}
}
// TestDashscopeCloner_EmptyURL asserts an empty reference URL is rejected.
// TestDashscopeCloner_EmptyURL 断言空的参考 URL 被拒绝。
func TestDashscopeCloner_EmptyURL(t *testing.T) {
t.Parallel()
cloner := NewDashscopeCloner(config.VoiceConfig{DashscopeBaseURL: "http://x", DashscopeAPIKey: "sk"})
@@ -123,8 +123,8 @@ func TestDashscopeCloner_EmptyURL(t *testing.T) {
}
}
// TestDashscopeCloner_BadPrefix asserts a non-alphanumeric or >10-char prefix is
// rejected before any request is sent.
// TestDashscopeCloner_BadPrefix 断言非字母数字或超过 10 字符的前缀
// 在发出任何请求之前就被拒绝。
func TestDashscopeCloner_BadPrefix(t *testing.T) {
t.Parallel()
cloner := NewDashscopeCloner(config.VoiceConfig{DashscopeBaseURL: "http://x", DashscopeAPIKey: "sk"})
@@ -135,8 +135,8 @@ func TestDashscopeCloner_BadPrefix(t *testing.T) {
}
}
// TestDashscopeCloner_ModelError asserts a top-level message in an HTTP 200
// response is surfaced as an error (no voice_id).
// TestDashscopeCloner_ModelError 断言 HTTP 200 响应中的顶层 message
// 会被作为错误暴露出来（此时没有 voice_id）。
func TestDashscopeCloner_ModelError(t *testing.T) {
t.Parallel()
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -151,8 +151,8 @@ func TestDashscopeCloner_ModelError(t *testing.T) {
}
}
// TestDashscopeTTS_Instruction_ClonedVoice asserts a cloned voice carries the
// configured instruction in the request input.
// TestDashscopeTTS_Instruction_ClonedVoice 断言复刻音色会在请求 input 中
// 携带配置的 instruction。
func TestDashscopeTTS_Instruction_ClonedVoice(t *testing.T) {
t.Parallel()
var gotBody map[string]any
@@ -182,8 +182,8 @@ func TestDashscopeTTS_Instruction_ClonedVoice(t *testing.T) {
}
}
// TestDashscopeTTS_NoInstruction_SystemVoice asserts a system voice (longxiaochun_v3)
// never receives a free-form instruction even when one is configured.
// TestDashscopeTTS_NoInstruction_SystemVoice 断言系统音色（longxiaochun_v3）
// 即使配置了 instruction 也绝不会收到自由形式的 instruction。
func TestDashscopeTTS_NoInstruction_SystemVoice(t *testing.T) {
t.Parallel()
var gotBody map[string]any
@@ -210,8 +210,8 @@ func TestDashscopeTTS_NoInstruction_SystemVoice(t *testing.T) {
}
}
// TestDashscopeTTS_Instruction_ContextOverride asserts a per-request ctx
// instruction wins over the configured one for a cloned voice.
// TestDashscopeTTS_Instruction_ContextOverride 断言对复刻音色，逐请求的 ctx
// instruction 优先于配置的 instruction。
func TestDashscopeTTS_Instruction_ContextOverride(t *testing.T) {
t.Parallel()
var gotBody map[string]any