feat(infra/llm): neutral types + LLMClient interface + estimate tokenizer + fake

internal/infra/llm/client.go

@@ -0,0 +1,81 @@
+// Package llm 提供与具体 provider 解耦的 LLM 抽象层。
+// 所有 provider 实现都把 SDK 的 message/event 形态映射到本包定义的中立类型。
+package llm
+
+import "context"
+
+// Role 标识消息发送方。
+type Role string
+
+const (
+	RoleUser      Role = "user"
+	RoleAssistant Role = "assistant"
+)
+
+// ContentBlock 是消息内容的最小单元。MVP 仅 text/image/document；tool_use/tool_result 为 mcp 预留。
+type ContentBlock struct {
+	Type     string // "text" | "image" | "document" | "tool_use" | "tool_result"
+	Text     string // type=text
+	MimeType string // type=image|document
+	Data     []byte // type=image|document（原始字节，未编码；各 provider 实现内部 base64）
+}
+
+// Message 是一轮对话的中立表示。
+type Message struct {
+	Role   Role
+	Blocks []ContentBlock
+}
+
+// ToolSpec 为 mcp 模块预留；MVP 始终空切片。
+type ToolSpec struct {
+	Name        string
+	Description string
+	InputSchema map[string]any
+}
+
+// Request 是 Stream/CountTokens 共用的输入。
+type Request struct {
+	SystemPrompt    string
+	Messages        []Message
+	MaxOutputTokens int
+	Reasoning       bool
+	Tools           []ToolSpec // mcp 预留
+}
+
+// StreamEventType 枚举所有流事件。
+type StreamEventType string
+
+const (
+	EventTextDelta     StreamEventType = "text_delta"
+	EventThinkingDelta StreamEventType = "thinking_delta"
+	EventToolCall      StreamEventType = "tool_call" // 预留
+	EventUsage         StreamEventType = "usage"
+	EventDone          StreamEventType = "done"
+	EventError         StreamEventType = "error"
+)
+
+// Usage 携带本次调用的 token 计数。
+type Usage struct {
+	PromptTokens     int
+	CompletionTokens int
+	ThinkingTokens   int
+}
+
+// StreamEvent 是流通道里的统一事件结构。
+type StreamEvent struct {
+	Type   StreamEventType
+	Text   string // text_delta / thinking_delta
+	Usage  *Usage // usage
+	Err    error  // error
+	Reason string // done.finish_reason
+}
+
+// LLMClient 是 Anthropic / OpenAI / Gemini 各自实现的统一接口。
+type LLMClient interface {
+	Provider() string
+	// Stream 启动一次流式请求，返回事件 channel。channel 关闭即表示流结束。
+	// ctx 取消时实现层须立即终止上游 stream。
+	Stream(ctx context.Context, modelID string, req Request) (<-chan StreamEvent, error)
+	// CountTokens 返回精确 token 数（远程接口）；仅 admin 离线场景使用。
+	CountTokens(ctx context.Context, modelID string, req Request) (int, error)
+}