Version: 0.9.65.dev.260503

后端：
1. 阶段 1.5/1.6
收口 llm-service / rag-service，统一模型出口与检索基础设施入口，清退 backend/infra/llm 与 backend/infra/rag 旧实现；
2. 同步更新相关调用链与微服务迁移计划文档

backend/services/llm/client.go

@@ -0,0 +1,174 @@
+package llm
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/cloudwego/eino/schema"
+)
+
+// ThinkingMode 描述这次模型调用对 thinking 的期望。
+type ThinkingMode string
+
+const (
+	ThinkingModeDefault  ThinkingMode = "default"
+	ThinkingModeEnabled  ThinkingMode = "enabled"
+	ThinkingModeDisabled ThinkingMode = "disabled"
+)
+
+// GenerateOptions 统一收敛文本调用时最常见的公共参数。
+type GenerateOptions struct {
+	Temperature float64
+	MaxTokens   int
+	Thinking    ThinkingMode
+	Metadata    map[string]any
+}
+
+// TextResult 保存一次文本生成的最终结果和 usage。
+// 1. Text 存放模型返回的纯文本。
+// 2. Usage 方便上层做统一统计。
+// 3. 这里不负责 JSON 解析，也不负责业务字段映射。
+type TextResult struct {
+	Text         string
+	Usage        *schema.TokenUsage
+	FinishReason string
+}
+
+// StreamReader 抽象可以逐块读取消息的流式返回器。
+type StreamReader interface {
+	Recv() (*schema.Message, error)
+	Close() error
+}
+
+// TextGenerateFunc 定义统一文本生成函数签名。
+type TextGenerateFunc func(ctx context.Context, messages []*schema.Message, options GenerateOptions) (*TextResult, error)
+
+// StreamGenerateFunc 定义统一流式生成函数签名。
+type StreamGenerateFunc func(ctx context.Context, messages []*schema.Message, options GenerateOptions) (StreamReader, error)
+
+// Client 是统一模型客户端门面。
+// 1. 只做最小输入校验和空响应防御。
+// 2. 不负责 prompt 拼装，也不负责业务 fallback。
+// 3. 具体 provider 的细节由上层适配器收敛进来。
+type Client struct {
+	generateText TextGenerateFunc
+	streamText   StreamGenerateFunc
+}
+
+// NewClient 创建统一模型客户端。
+func NewClient(generateText TextGenerateFunc, streamText StreamGenerateFunc) *Client {
+	return &Client{
+		generateText: generateText,
+		streamText:   streamText,
+	}
+}
+
+// GenerateText 执行一次统一文本生成。
+func (c *Client) GenerateText(ctx context.Context, messages []*schema.Message, options GenerateOptions) (*TextResult, error) {
+	if c == nil || c.generateText == nil {
+		return nil, errors.New("llm client is not ready")
+	}
+	if len(messages) == 0 {
+		return nil, errors.New("llm messages is empty")
+	}
+
+	result, err := c.generateText(ctx, messages, options)
+	if err != nil {
+		return nil, err
+	}
+	if result == nil {
+		return nil, errors.New("llm result is nil")
+	}
+	if strings.TrimSpace(result.Text) == "" {
+		return nil, errors.New("llm returned empty text")
+	}
+	return result, nil
+}
+
+// GenerateJSON 先走统一文本生成，再走统一 JSON 解析。
+func GenerateJSON[T any](ctx context.Context, client *Client, messages []*schema.Message, options GenerateOptions) (*T, *TextResult, error) {
+	result, err := client.GenerateText(ctx, messages, options)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	parsed, err := ParseJSONObject[T](result.Text)
+	if err != nil {
+		return nil, result, err
+	}
+	return parsed, result, nil
+}
+
+// Stream 打开统一流式调用入口。
+func (c *Client) Stream(ctx context.Context, messages []*schema.Message, options GenerateOptions) (StreamReader, error) {
+	if c == nil || c.streamText == nil {
+		return nil, errors.New("llm stream client is not ready")
+	}
+	if len(messages) == 0 {
+		return nil, errors.New("llm messages is empty")
+	}
+	return c.streamText(ctx, messages, options)
+}
+
+// BuildSystemUserMessages 构造最常见的 system + history + user 消息列表。
+func BuildSystemUserMessages(systemPrompt string, history []*schema.Message, userPrompt string) []*schema.Message {
+	messages := make([]*schema.Message, 0, len(history)+2)
+	if strings.TrimSpace(systemPrompt) != "" {
+		messages = append(messages, schema.SystemMessage(systemPrompt))
+	}
+	if len(history) > 0 {
+		messages = append(messages, history...)
+	}
+	if strings.TrimSpace(userPrompt) != "" {
+		messages = append(messages, schema.UserMessage(userPrompt))
+	}
+	return messages
+}
+
+// CloneUsage 深拷贝 token usage，避免后续累加时共享同一个指针。
+func CloneUsage(usage *schema.TokenUsage) *schema.TokenUsage {
+	if usage == nil {
+		return nil
+	}
+	copied := *usage
+	return &copied
+}
+
+// MergeUsage 合并两段 usage，取各字段更大的值作为累计结果。
+func MergeUsage(base *schema.TokenUsage, incoming *schema.TokenUsage) *schema.TokenUsage {
+	if incoming == nil {
+		return CloneUsage(base)
+	}
+	if base == nil {
+		return CloneUsage(incoming)
+	}
+
+	merged := *base
+	if incoming.PromptTokens > merged.PromptTokens {
+		merged.PromptTokens = incoming.PromptTokens
+	}
+	if incoming.CompletionTokens > merged.CompletionTokens {
+		merged.CompletionTokens = incoming.CompletionTokens
+	}
+	if incoming.TotalTokens > merged.TotalTokens {
+		merged.TotalTokens = incoming.TotalTokens
+	}
+	if incoming.PromptTokenDetails.CachedTokens > merged.PromptTokenDetails.CachedTokens {
+		merged.PromptTokenDetails.CachedTokens = incoming.PromptTokenDetails.CachedTokens
+	}
+	if incoming.CompletionTokensDetails.ReasoningTokens > merged.CompletionTokensDetails.ReasoningTokens {
+		merged.CompletionTokensDetails.ReasoningTokens = incoming.CompletionTokensDetails.ReasoningTokens
+	}
+	return &merged
+}
+
+// FormatEmptyResponseError 统一模型空结果的错误文案。
+func FormatEmptyResponseError(scene string) error {
+	scene = strings.TrimSpace(scene)
+	if scene == "" {
+		scene = "unknown"
+	}
+	return fmt.Errorf("模型在 %s 场景返回空结果", scene)
+}