M02 LLM 全平台接入

// OpenAI：messages 数组，system 是一种 role
{
  "model": "gpt-5",
  "messages": [
    {"role": "system", "content": "你是助手"},
    {"role": "user", "content": "你好"}
  ]
}

// Anthropic：system 是顶层字段，messages 只有 user/assistant
{
  "model": "claude-sonnet-4-20250514",
  "system": "你是助手",
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "max_tokens": 1024
}

// Gemini：contents 数组，role 使用 "model"，systemInstruction 单独配置
{
  "contents": [
    {"role": "user", "parts": [{"text": "你好"}]}
  ],
  "systemInstruction": {
    "parts": [{"text": "你是助手"}]
  }
}

OpenAI:
data: {"choices":[{"delta":{"content":"H"}}]}
data: {"choices":[{"delta":{"content":"i"}}]}
data: [DONE]

Anthropic:
event: message_start
data: {"type":"message_start", ...}
event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"H"}}
event: message_stop
data: {"type":"message_stop"}

Gemini:
data: {"candidates":[{"content":{"parts":[{"text":"H"}]}}]}
data: {"candidates":[{"content":{"parts":[{"text":"i"}]}}]}

package llm

// Provider 是所有大模型供应商的统一抽象。上层只关心能否调用和能否流式，
// 不关心某家把 system 放哪、请求头怎么拼。
type Provider interface {
	Name() string
	Capabilities() Capability // 声明支持流式、思考、工具，路由时使用
	Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)
	ChatStream(ctx context.Context, req ChatRequest) (<-chan StreamChunk, error)
}

// Capability 描述一个 Provider 的能力。
type Capability struct {
	Streaming bool
	Thinking  bool
	Tools     bool
}

package llm

type Role string

const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
)

type Message struct {
	Role    Role   `json:"role"`
	Content string `json:"content"`
}

type ChatRequest struct {
	Model       string    `json:"model"`
	Messages    []Message `json:"messages"`
	Temperature float64   `json:"temperature,omitempty"`
	MaxTokens   int       `json:"max_tokens,omitempty"`
	Stream      bool      `json:"stream,omitempty"`
}

type ChatResponse struct {
	Content      string
	InputTokens  int
	OutputTokens int
}

func NewChatRequest(model string, messages []Message, opts ...Option) ChatRequest {
	req := ChatRequest{Model: model, Messages: messages}
	for _, opt := range opts {
		opt(&req)
	}
	return req
}

type Option func(*ChatRequest)

func WithTemperature(t float64) Option {
	return func(r *ChatRequest) { r.Temperature = t }
}

func WithMaxTokens(n int) Option {
	return func(r *ChatRequest) { r.MaxTokens = n }
}

package openai

type Provider struct {
	name    string
	baseURL string
	apiKey  string
	client  *transport.Client // M01 的生产级客户端
}

// Config 收拢 Provider 构造参数。
// 三个字段都是 string，如果用位置参数容易把 baseURL 和 apiKey 写反。
type Config struct {
	Name    string // Provider 标识，如 "deepseek"
	BaseURL string // 形如 https://api.deepseek.com
	APIKey  string
}

// New 创建一个 OpenAI 兼容 Provider。
func New(cfg Config) *Provider {
	return &Provider{
		name:    cfg.Name,
		baseURL: cfg.BaseURL,
		apiKey:  cfg.APIKey,
		client:  transport.NewClient(),
	}
}

func (p *Provider) Name() string { return p.name }

func (p *Provider) Capabilities() llm.Capability {
	return llm.Capability{Streaming: true, Tools: true}
}

func (p *Provider) Chat(ctx context.Context, req llm.ChatRequest) (*llm.ChatResponse, error) {
	body, _ := json.Marshal(req) // M06 接工具时会进一步细化请求体
	httpReq, err := http.NewRequestWithContext(
		ctx,
		http.MethodPost,
		p.baseURL+"/chat/completions",
		bytes.NewReader(body),
	)
	if err != nil {
		return nil, err
	}
	httpReq.Header.Set("Content-Type", "application/json")
	httpReq.Header.Set("Authorization", "Bearer "+p.apiKey)

	resp, err := p.client.Do(httpReq)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("%s: %s", p.name, parseAPIError(resp))
	}

	var out struct {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
		Usage struct {
			PromptTokens     int `json:"prompt_tokens"`
			CompletionTokens int `json:"completion_tokens"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		return nil, err
	}
	if len(out.Choices) == 0 {
		return nil, fmt.Errorf("%s: 空响应", p.name)
	}
	return &llm.ChatResponse{
		Content:      out.Choices[0].Message.Content,
		InputTokens:  out.Usage.PromptTokens,
		OutputTokens: out.Usage.CompletionTokens,
	}, nil
}

package openai

// 复用第三节的 Provider，只是预置各家的 baseURL。

func NewOpenAI(apiKey string) llm.Provider {
	return New(Config{Name: "openai", BaseURL: "https://api.openai.com/v1", APIKey: apiKey})
}

// NewDeepSeek DeepSeek Provider
func NewDeepSeek(apiKey string) llm.Provider {
	return New(Config{Name: "deepseek", BaseURL: "https://api.deepseek.com", APIKey: apiKey})
}

// NewDoubao 豆包 Provider
func NewDoubao(apiKey string) llm.Provider {
	return New(Config{Name: "doubao", BaseURL: "https://ark.cn-beijing.volces.com/api/v3", APIKey: apiKey})
}

// NewQwen 千问 Provider
func NewQwen(apiKey string) llm.Provider {
	return New(Config{Name: "qwen", BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1", APIKey: apiKey})
}

// Kimi、GLM 同理：换 baseURL 即可。具体模型名按次通过 ChatRequest.Model 传入。

package claude

import "fmt" // 教学骨架 Chat 占位用，真实实现还会引入 context、encoding/json 等

func New(apiKey string) *Provider {
	/* baseURL=https://api.anthropic.com/v1，复用 transport */
}

func (p *Provider) Name() string { return "claude" }

func (p *Provider) Capabilities() llm.Capability {
	return llm.Capability{Streaming: true, Thinking: true, Tools: true}
}

// adaptRequest 把统一的 ChatRequest 翻译成 Anthropic 请求体。
func (p *Provider) adaptRequest(req llm.ChatRequest) map[string]any {
	var system string
	msgs := make([]map[string]string, 0, len(req.Messages))
	for _, m := range req.Messages {
		if m.Role == llm.RoleSystem {
			system += m.Content
			continue
		}
		msgs = append(msgs, map[string]string{
			"role":    string(m.Role),
			"content": m.Content,
		})
	}
	maxTokens := req.MaxTokens
	if maxTokens == 0 {
		maxTokens = 1024 // Anthropic 要求 max_tokens 必填
	}
	body := map[string]any{
		"model":      req.Model,
		"messages":   msgs,
		"max_tokens": maxTokens,
	}
	if system != "" {
		body["system"] = system
	}
	return body
}

func (p *Provider) Chat(ctx context.Context, req llm.ChatRequest) (*llm.ChatResponse, error) {
	// 教学骨架，完整实现见配套练习。
	// 真实写法：
	//   1) body := adaptRequest(req)
	//   2) 带 x-api-key / anthropic-version 头通过 p.client.Do 发请求
	//   3) 解析 content 块数组，拼接所有 type=="text" 的块
	//   4) 用 usage.input_tokens / output_tokens 填 ChatResponse
	return nil, fmt.Errorf("anthropic.Provider.Chat: 教学骨架，完整实现见配套练习")
}

local := openai.New(openai.Config{
	Name:    "ollama",
	BaseURL: "http://localhost:11434/v1",
	APIKey:  "ollama", // 本地不校验 key，随便填
})

// 先执行：ollama pull qwen3
// ChatRequest.Model 填 "qwen3" 即可。

data: {"choices":[{"delta":{"content":"你"}}]}

data: {"choices":[{"delta":{"content":"好"}}]}

data: [DONE]

package transport

import (
	"bufio"
	"bytes"
	"io"
)

// ParseSSE 逐条读取 SSE 的 data 行，对每条非 [DONE] 数据回调 onData。
// onData 返回非 nil error 时提前终止；正常读到 [DONE] 或 EOF 即结束。
func ParseSSE(r io.Reader, onData func(data []byte) error) error {
	scanner := bufio.NewScanner(r)
	// 单条 SSE 数据可能很长，调大缓冲区上限。
	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)

	for scanner.Scan() {
		line := scanner.Bytes()
		if len(bytes.TrimSpace(line)) == 0 {
			continue // 事件分隔空行
		}
		if !bytes.HasPrefix(line, []byte("data:")) {
			continue // 忽略 event:/id:/注释行
		}
		data := bytes.TrimSpace(line[len("data:"):])
		if string(data) == "[DONE]" {
			return nil
		}
		buf := make([]byte, len(data)) // scanner 复用底层数组，跨回调留存必须 copy
		copy(buf, data)
		if err := onData(buf); err != nil {
			return err
		}
	}
	return scanner.Err()
}

func parseOpenAIDelta(data []byte) string {
	var chunk struct {
		Choices []struct {
			Delta struct {
				Content string `json:"content"`
			} `json:"delta"`
		} `json:"choices"`
	}
	if err := json.Unmarshal(data, &chunk); err != nil || len(chunk.Choices) == 0 {
		return ""
	}
	return chunk.Choices[0].Delta.Content
}

func (p *Provider) ChatStream(ctx context.Context, req llm.ChatRequest) (<-chan llm.StreamChunk, error) {
	req.Stream = true
	resp, err := p.doRequest(ctx, req) // 同 Chat 的发请求样板，略
	if err != nil {
		return nil, err
	}
	out := make(chan llm.StreamChunk)
	go func() {
		defer close(out)
		defer resp.Body.Close()
		_ = transport.ParseSSE(resp.Body, func(data []byte) error {
			delta := parseOpenAIDelta(data)
			if delta == "" {
				return nil
			}
			select {
			case <-ctx.Done():
				return ctx.Err()
			case out <- llm.StreamChunk{Content: delta}:
				return nil
			}
		})
	}()
	return out, nil
}

// parseClaudeDelta 只从文本增量块里抽出 delta.text；
// message_start / content_block_stop / message_stop 等事件返回空串。
func parseClaudeDelta(data []byte) string {
	var ev struct {
		Type  string `json:"type"`
		Delta struct {
			Type string `json:"type"`
			Text string `json:"text"`
		} `json:"delta"`
	}
	if err := json.Unmarshal(data, &ev); err != nil {
		return ""
	}
	if ev.Type == "content_block_delta" && ev.Delta.Type == "text_delta" {
		return ev.Delta.Text
	}
	return ""
}

package schema

type Schema struct {
	Type        string             `json:"type,omitempty"`
	Description string             `json:"description,omitempty"`
	Properties  map[string]*Schema `json:"properties,omitempty"`
	Items       *Schema            `json:"items,omitempty"`
	Required    []string           `json:"required,omitempty"`
}

// Generate 为任意值的类型生成 JSON Schema。
// 实现是一段 reflect 递归：遍历字段、按 kind 映射、读取 json/desc 标签。
func Generate(v any) *Schema {
	/* reflect 递归：string→"string"，struct→"object" ... */
	return nil
}

type GetWeatherArgs struct {
	City string `json:"city" desc:"城市名"`
	Days int    `json:"days,omitempty" desc:"预报天数，默认 1"`
}

s := schema.Generate(GetWeatherArgs{}) // 交给模型的工具或结构化输出定义

package cost

type Pricing struct {
	InputPer1M  float64 // 每百万输入 token 单价
	OutputPer1M float64 // 每百万输出 token 单价
}

type Usage struct {
	InputTokens  int
	OutputTokens int
}

func (u Usage) Cost(p Pricing) float64 {
	return float64(u.InputTokens)/1e6*p.InputPer1M +
		float64(u.OutputTokens)/1e6*p.OutputPer1M
}

// Accumulator 并发安全地累计一轮会话的用量与成本。
type Accumulator struct {
	mu    sync.Mutex
	Usage Usage
	Cost  float64
}

func (a *Accumulator) Add(u Usage, p Pricing) {
	a.mu.Lock()
	defer a.mu.Unlock()
	a.Usage.InputTokens += u.InputTokens
	a.Usage.OutputTokens += u.OutputTokens
	a.Cost += u.Cost(p)
}

func BuildAll(cfg Config) map[string]llm.Provider {
	ps := map[string]llm.Provider{}
	if cfg.DeepSeekKey != "" {
		ps["deepseek"] = openai.NewDeepSeek(cfg.DeepSeekKey)
	}
	if cfg.ArkKey != "" {
		ps["doubao"] = openai.NewDoubao(cfg.ArkKey)
	}
	if cfg.ClaudeKey != "" {
		ps["claude"] = claude.New(cfg.ClaudeKey)
	}
	ps["ollama"] = openai.New(openai.Config{
		Name:    "ollama",
		BaseURL: cfg.OllamaURL,
		APIKey:  "ollama",
	})
	return ps
}

package router

type Strategy interface {
	Order(providers []llm.Provider) []llm.Provider // 决定尝试顺序
}

type Priority struct{} // 最简策略：按注册顺序，主用第一个，挂了降级

func (Priority) Order(ps []llm.Provider) []llm.Provider { return ps }

type Router struct {
	providers []llm.Provider
	strategy  Strategy
}

func New(strategy Strategy, providers ...llm.Provider) *Router {
	return &Router{providers: providers, strategy: strategy}
}

func (r *Router) Chat(ctx context.Context, req llm.ChatRequest) (*llm.ChatResponse, string, error) {
	var lastErr error
	for _, p := range r.strategy.Order(r.providers) {
		resp, err := p.Chat(ctx, req)
		if err == nil {
			return resp, p.Name(), nil // 第二个返回值告诉上层“谁回答的”
		}
		lastErr = err
		if ctx.Err() != nil {
			return nil, "", ctx.Err() // 用户取消，不再尝试
		}
	}
	return nil, "", fmt.Errorf("所有 Provider 均失败: %w", lastErr)
}