team-api/relaykit/relayconvert/response_registry.go

// Package relayconvert — 响应侧转换器 spec 类型与注册 / 查找机制。
//
// 本文件只移植「spec 类型 + 函数类型 + 注册 / 查找 / 别名」结构层。
// 调度引擎（ConvertResponse / ConvertStreamResponse / NewResponseStreamState* /
// ConvertStreamResponseChunk / FinalizeStreamResponse / execute* / infer* /
// canonicalUsageFromResponse）、ResponseStreamState 的方法（Usage/SetUsage/UsageText
// 依赖 stream-state 类型）以及全部 adapter 函数。
package relayconvert

import (
	"context"
	"fmt"
	"sort"
	"strings"
	"sync"

	"github.com/qianfree/team-api/relaykit/dto"
	"github.com/qianfree/team-api/relaykit/relayconvert/convmeta"
	"github.com/qianfree/team-api/relaykit/types"
)

type ResponseConverterFunc func(c context.Context, info convmeta.Meta, response any) (any, *dto.Usage, error)

type ResponseStreamConverterFunc func(c context.Context, info convmeta.Meta, response any) (any, *dto.Usage, error)

type ResponseStreamStateFactory func(options ResponseStreamOptions) any

type ResponseStreamChunkConverterFunc func(c context.Context, info convmeta.Meta, response any, state any) ([]any, *dto.Usage, error)

type ResponseStreamFinalizerFunc func(c context.Context, info convmeta.Meta, state any) ([]any, *dto.Usage, error)

type ResponseConverterQuality string

const (
	ResponseConverterQualityGood        ResponseConverterQuality = "good"
	ResponseConverterQualityFair        ResponseConverterQuality = "fair"
	ResponseConverterQualityDiscouraged ResponseConverterQuality = "discouraged"
)

type ResponseStep struct {
	Converter string
	From      types.RelayFormat
	To        types.RelayFormat
}

type ResponseResult struct {
	Value     any
	Usage     *dto.Usage
	From      types.RelayFormat
	To        types.RelayFormat
	Converter string
	Quality   ResponseConverterQuality
	Steps     []ResponseStep
	Stream    bool
}

type ResponseConverterSpec struct {
	ID                 string
	From               types.RelayFormat
	To                 types.RelayFormat
	Quality            ResponseConverterQuality
	Convert            ResponseConverterFunc
	ConvertStream      ResponseStreamConverterFunc
	NewStreamState     ResponseStreamStateFactory
	ConvertStreamChunk ResponseStreamChunkConverterFunc
	FinalizeStream     ResponseStreamFinalizerFunc
	StepConverters     []string
}

type responseConverterRoute struct {
	from types.RelayFormat
	to   types.RelayFormat
}

// ResponseStreamOptions 透传给 NewStreamState 工厂，用于初始化流式转换状态。
type ResponseStreamOptions struct {
	ID           string
	Model        string
	Created      int64
	IncludeUsage bool
}

// ResponseStreamState 承载一次流式响应转换的跨 chunk 状态。
// 仅定义数据字段；其方法（Usage/SetUsage/UsageText/rememberUsage）与
// 构造器（NewResponseStreamState）依赖 stream-state 实现类型。
type ResponseStreamState struct {
	From      types.RelayFormat
	To        types.RelayFormat
	Converter string
	Quality   ResponseConverterQuality
	Steps     []ResponseStep

	specs      []ResponseConverterSpec
	stepStates []any
	usage      *dto.Usage
}

const (
	ResponseConverterOAIChatToOAIResponses         = "oai_chat_to_oai_responses_resp"
	ResponseConverterOAIResponsesToOAIChat         = "oai_responses_to_oai_chat_resp"
	ResponseConverterOAIChatToClaudeMessages       = "oai_chat_to_claude_messages_resp"
	ResponseConverterOAIChatToGeminiChat           = "oai_chat_to_gemini_chat_resp"
	ResponseConverterClaudeMessagesToOAIChat       = "claude_messages_to_oai_chat_resp"
	ResponseConverterClaudeMessagesToOAIChatStream = "claude_messages_to_oai_chat_stream_resp"
	ResponseConverterGeminiChatToOAIChat           = "gemini_chat_to_oai_chat_resp"
	ResponseConverterGeminiChatToOAIChatStream     = "gemini_chat_to_oai_chat_stream_resp"

	// 原生格式供应商 → OpenAI（响应侧，含流式）
	ResponseConverterOllamaChatToOAIChat       = "ollama_chat_to_oai_chat_resp"
	ResponseConverterOllamaChatToOAIChatStream = "ollama_chat_to_oai_chat_stream_resp"

	// 反向方向（OpenAI 上游 → 非 OpenAI 客户端）与 Responses 双向的流式转换器 ID。
	// 流式注册表按数据方向 (from=上游格式, to=客户端格式) 登记。
	ResponseConverterOAIChatToClaudeMessagesStream = "oai_chat_to_claude_messages_stream_resp"
	ResponseConverterOAIChatToGeminiChatStream     = "oai_chat_to_gemini_chat_stream_resp"
	ResponseConverterOAIResponsesToOAIChatStream   = "oai_responses_to_oai_chat_stream_resp"
	ResponseConverterOAIChatToOAIResponsesStream   = "oai_chat_to_oai_responses_stream_resp"

	// 跨原生方向（上游原生 → 另一原生客户端）的非流式转换器 ID（响应侧元数据）。
	ResponseConverterClaudeMessagesToGeminiChat   = "claude_messages_to_gemini_chat_resp"
	ResponseConverterGeminiChatToClaudeMessages   = "gemini_chat_to_claude_messages_resp"
	ResponseConverterClaudeMessagesToOAIResponses = "claude_messages_to_oai_responses_resp"
	ResponseConverterGeminiChatToOAIResponses     = "gemini_chat_to_oai_responses_resp"

	// 跨原生方向（上游原生 → 另一原生客户端）的流式转换器 ID。
	ResponseConverterClaudeMessagesToGeminiChatStream   = "claude_messages_to_gemini_chat_stream_resp"
	ResponseConverterGeminiChatToClaudeMessagesStream   = "gemini_chat_to_claude_messages_stream_resp"
	ResponseConverterGeminiChatToOAIResponsesStream     = "gemini_chat_to_oai_responses_stream_resp"
	ResponseConverterClaudeMessagesToOAIResponsesStream = "claude_messages_to_oai_responses_stream_resp"
)

var (
	responseConverterMu      sync.RWMutex
	responseConverters       = make(map[string]ResponseConverterSpec)
	responseConverterAliases = make(map[string]string)
	responseConverterRoutes  = make(map[responseConverterRoute]string)
)

// ListResponseConverterIDs 返回全部已注册响应侧转换器 ID（字典序副本，不含别名）。
// 供诊断与测试枚举使用，与 ListRequestConverterIDs 配套。
func ListResponseConverterIDs() []string {
	responseConverterMu.RLock()
	defer responseConverterMu.RUnlock()

	ids := make([]string, 0, len(responseConverters))
	for id := range responseConverters {
		ids = append(ids, id)
	}
	sort.Strings(ids)
	return ids
}

// registerBuiltinResponseConverter 注册响应侧转换器到注册表。
// init() 通过 registerBuiltinTextConverter() 调用本函数。
//
// 并发安全：持有 responseConverterMu 写锁保护注册过程，防止 data race。
// 虽然通常在包 init() 中调用（单线程），但加锁确保未来动态注册或测试并发场景安全。
func registerBuiltinResponseConverter(spec ResponseConverterSpec) {
	spec.ID = strings.TrimSpace(spec.ID)
	if spec.ID == "" {
		panic("response converter ID is required")
	}
	if spec.From == "" || spec.To == "" {
		panic(fmt.Sprintf("response converter %q must declare from and to formats", spec.ID))
	}
	if spec.Quality == "" {
		panic(fmt.Sprintf("response converter %q must declare quality", spec.ID))
	}
	if spec.Convert == nil &&
		spec.ConvertStream == nil &&
		spec.ConvertStreamChunk == nil &&
		len(spec.StepConverters) == 0 {
		panic(fmt.Sprintf("response converter %q must declare convert, stream convert, or step converters", spec.ID))
	}
	if len(spec.StepConverters) > 0 &&
		(spec.Convert != nil || spec.ConvertStream != nil || spec.NewStreamState != nil || spec.ConvertStreamChunk != nil || spec.FinalizeStream != nil) {
		panic(fmt.Sprintf("response converter %q cannot declare direct implementations and step converters together", spec.ID))
	}

	responseConverterMu.Lock()
	defer responseConverterMu.Unlock()

	if _, exists := responseConverters[spec.ID]; exists {
		panic(fmt.Sprintf("response converter %q is already registered", spec.ID))
	}
	route := responseConverterRoute{from: spec.From, to: spec.To}
	if existingID, exists := responseConverterRoutes[route]; exists {
		panic(fmt.Sprintf("response converter route from %s to %s is already registered by %q", spec.From, spec.To, existingID))
	}

	if len(spec.StepConverters) > 0 {
		stepConverters := make([]string, 0, len(spec.StepConverters))
		current := spec.From
		for _, converterID := range spec.StepConverters {
			step, ok := responseConverters[converterID]
			if !ok {
				panic(fmt.Sprintf("response converter %q references unknown step converter %q", spec.ID, converterID))
			}
			if len(step.StepConverters) > 0 {
				panic(fmt.Sprintf("response converter %q step %q must be a direct converter", spec.ID, converterID))
			}
			if step.From != current {
				panic(fmt.Sprintf("response converter %q step %q expects %s after %s", spec.ID, converterID, step.From, current))
			}
			stepConverters = append(stepConverters, converterID)
			current = step.To
		}
		if current != spec.To {
			panic(fmt.Sprintf("response converter %q ends at %s, expected %s", spec.ID, current, spec.To))
		}
		spec.StepConverters = stepConverters
	}

	responseConverters[spec.ID] = spec
	responseConverterRoutes[route] = spec.ID
}

// registerResponseConverterAlias 注册响应转换器别名。
//
// 并发安全：持有 responseConverterMu 写锁保护注册过程，防止 data race。
// 虽然通常在包 init() 中调用（单线程），但加锁确保未来动态注册或测试并发场景安全。
func registerResponseConverterAlias(alias string, converter string) {
	alias = strings.TrimSpace(alias)
	converter = strings.TrimSpace(converter)
	if alias == "" {
		panic("response converter alias is required")
	}
	if converter == "" {
		panic(fmt.Sprintf("response converter alias %q target is required", alias))
	}
	if alias == converter {
		return
	}

	responseConverterMu.Lock()
	defer responseConverterMu.Unlock()

	if _, exists := responseConverters[alias]; exists {
		panic(fmt.Sprintf("response converter alias %q conflicts with registered converter", alias))
	}
	if _, exists := responseConverters[converter]; !exists {
		panic(fmt.Sprintf("response converter alias %q references unknown converter %q", alias, converter))
	}
	if existing, exists := responseConverterAliases[alias]; exists && existing != converter {
		panic(fmt.Sprintf("response converter alias %q is already registered for %q", alias, existing))
	}
	responseConverterAliases[alias] = converter
}

func LookupResponseConverter(converter string) (ResponseConverterSpec, bool) {
	responseConverterMu.RLock()
	defer responseConverterMu.RUnlock()

	converterID := resolveResponseConverterID(converter)
	spec, ok := responseConverters[converterID]
	if !ok {
		return ResponseConverterSpec{}, false
	}
	return cloneResponseConverterSpec(spec), true
}

func lookupResponseRoute(from types.RelayFormat, to types.RelayFormat) (ResponseConverterSpec, bool) {
	responseConverterMu.RLock()
	defer responseConverterMu.RUnlock()

	converterID, ok := responseConverterRoutes[responseConverterRoute{from: from, to: to}]
	if !ok {
		return ResponseConverterSpec{}, false
	}
	spec, ok := responseConverters[converterID]
	return cloneResponseConverterSpec(spec), ok
}

func resolveResponseConverterID(converter string) string {
	converter = strings.TrimSpace(converter)
	if canonical, ok := responseConverterAliases[converter]; ok {
		return canonical
	}
	return converter
}

func cloneResponseConverterSpec(spec ResponseConverterSpec) ResponseConverterSpec {
	if len(spec.StepConverters) > 0 {
		spec.StepConverters = append([]string{}, spec.StepConverters...)
	}
	return spec
}