// ai/tracing/context.go
type TracingContext struct {
    TraceID   string
    SpanID    string
    ParentID  string
    StartTime time.Time
    UserID    int32
    SessionID string
    AgentType string
    
    // 各阶段 Span
    Phases    map[string]*PhaseSpan
    ToolCalls []ToolCallSpan
    LLMCalls  []LLMCallSpan
    
    mu sync.Mutex
}

type PhaseSpan struct {
    Name      string
    StartTime time.Time
    EndTime   time.Time
    Duration  time.Duration
    Metadata  map[string]any
    Error     string
}

type ToolCallSpan struct {
    ToolName  string
    StartTime time.Time
    Duration  time.Duration
    Input     string
    Output    string
    Success   bool
    Error     string
}

type LLMCallSpan struct {
    Purpose      string // "planning", "synthesis"
    Model        string
    StartTime    time.Time
    Duration     time.Duration
    InputTokens  int
    OutputTokens int
    CacheHit     bool
}

func (p *AmazingParrot) ExecuteWithCallback(...) error {
    trace := tracing.NewContext()
    trace.SetUserID(p.userID)
    trace.SetAgentType(p.Name())
    defer trace.Finish()
    
    // Phase 1: Planning
    trace.StartPhase("planning")
    plan, err := p.planRetrieval(ctx, ...)
    trace.EndPhase("planning", map[string]any{
        "needs_memo": plan.needsMemoSearch,
        "needs_schedule": plan.needsScheduleQuery,
    })
    
    // Phase 2: Retrieval
    trace.StartPhase("retrieval")
    for _, tool := range tools {
        toolSpan := trace.StartToolCall(tool.Name())
        result, err := tool.Execute(ctx, input)
        trace.EndToolCall(toolSpan, result, err)
    }
    trace.EndPhase("retrieval", nil)
    
    // Phase 3: Synthesis
    trace.StartPhase("synthesis")
    answer, err := p.synthesizeAnswer(ctx, ...)
    trace.EndPhase("synthesis", nil)
    
    // 导出 trace
    trace.Export()
    return nil
}

// ai/tracing/exporter.go
type Exporter interface {
    Export(trace *TracingContext) error
}

// 日志导出
type LogExporter struct {
    logger *slog.Logger
}

func (e *LogExporter) Export(trace *TracingContext) error {
    e.logger.Info("trace completed",
        "trace_id", trace.TraceID,
        "total_duration_ms", trace.TotalDuration().Milliseconds(),
        "phases", trace.PhaseSummary(),
        "tool_calls", len(trace.ToolCalls),
        "llm_calls", len(trace.LLMCalls),
    )
    return nil
}

// Jaeger/Zipkin 导出 (可选)
type JaegerExporter struct {
    client *jaeger.Client
}

// GET /api/v1/ai/traces?user_id=123&limit=10
type TraceQueryResponse struct {
    Traces []TraceSummary `json:"traces"`
    Total  int            `json:"total"`
}

type TraceSummary struct {
    TraceID       string        `json:"trace_id"`
    StartTime     time.Time     `json:"start_time"`
    TotalDuration time.Duration `json:"total_duration"`
    AgentType     string        `json:"agent_type"`
    Success       bool          `json:"success"`
    Phases        []PhaseSummary `json:"phases"`
}