事件类型定义

本文档定义了XAI-SDK事件系统中使用的类型和接口。

基础事件接口

Event

基础事件接口：

interface Event {
  /** 事件类型 */
  type: string
  
  /** 事件ID */
  id: string
  
  /** 事件时间戳 */
  timestamp: Date
  
  /** 事件数据 */
  data?: any
  
  /** 事件来源 */
  source?: string
  
  /** 事件目标 */
  target?: string
  
  /** 事件元数据 */
  metadata?: EventMetadata
  
  /** 事件优先级 */
  priority?: EventPriority
  
  /** 事件标签 */
  tags?: string[]
}

EventMetadata

事件元数据：

interface EventMetadata {
  /** 用户ID */
  userId?: string
  
  /** 会话ID */
  sessionId?: string
  
  /** 请求ID */
  requestId?: string
  
  /** 执行ID */
  executionId?: string
  
  /** 用户代理 */
  userAgent?: string
  
  /** IP地址 */
  ipAddress?: string
  
  /** 地理位置 */
  location?: {
    country?: string
    region?: string
    city?: string
  }
  
  /** 设备信息 */
  device?: {
    type?: 'desktop' | 'mobile' | 'tablet' | 'server'
    os?: string
    browser?: string
  }
  
  /** 自定义属性 */
  custom?: Record<string, any>
}

EventPriority

事件优先级：

type EventPriority = 'low' | 'normal' | 'high' | 'critical'

SDK事件类型

SDKEvent

SDK事件接口：

interface SDKEvent extends Event {
  type: SDKEventType
  source: 'sdk'
}

SDKEventType

SDK事件类型：

type SDKEventType =
  | 'sdk:initialized'
  | 'sdk:destroyed'
  | 'sdk:config:updated'
  | 'sdk:health:check'
  | 'sdk:stats:updated'
  | 'sdk:error'

SDKInitializedEvent

SDK初始化事件：

interface SDKInitializedEvent extends SDKEvent {
  type: 'sdk:initialized'
  data: {
    version: string
    config: XAIConfig
    adapters: string[]
    plugins: string[]
    tools: string[]
    initTime: number
  }
}

SDKDestroyedEvent

SDK销毁事件：

interface SDKDestroyedEvent extends SDKEvent {
  type: 'sdk:destroyed'
  data: {
    reason: 'manual' | 'error' | 'shutdown'
    uptime: number
    stats: SDKStats
  }
}

SDKConfigUpdatedEvent

SDK配置更新事件：

interface SDKConfigUpdatedEvent extends SDKEvent {
  type: 'sdk:config:updated'
  data: {
    oldConfig: XAIConfig
    newConfig: XAIConfig
    changes: ConfigChange[]
  }
}

ConfigChange

配置变更：

interface ConfigChange {
  /** 变更路径 */
  path: string
  
  /** 变更类型 */
  type: 'added' | 'modified' | 'removed'
  
  /** 旧值 */
  oldValue?: any
  
  /** 新值 */
  newValue?: any
}

请求事件类型

RequestEvent

请求事件接口：

interface RequestEvent extends Event {
  type: RequestEventType
  source: 'request'
  data: RequestEventData
}

RequestEventType

请求事件类型：

type RequestEventType =
  | 'request:started'
  | 'request:completed'
  | 'request:failed'
  | 'request:timeout'
  | 'request:cancelled'
  | 'request:retry'

RequestEventData

请求事件数据：

interface RequestEventData {
  /** 请求ID */
  requestId: string
  
  /** 适配器名称 */
  adapter: string
  
  /** 模型名称 */
  model: string
  
  /** 消息数量 */
  messageCount: number
  
  /** 请求选项 */
  options: ChatOptions
  
  /** 响应数据（完成时） */
  response?: ChatResponse
  
  /** 错误信息（失败时） */
  error?: Error
  
  /** 执行时间(毫秒) */
  duration?: number
  
  /** 重试次数 */
  retryCount?: number
}

RequestStartedEvent

请求开始事件：

interface RequestStartedEvent extends RequestEvent {
  type: 'request:started'
  data: Omit<RequestEventData, 'response' | 'error' | 'duration'>
}

RequestCompletedEvent

请求完成事件：

interface RequestCompletedEvent extends RequestEvent {
  type: 'request:completed'
  data: Required<Omit<RequestEventData, 'error'>>
}

RequestFailedEvent

请求失败事件：

interface RequestFailedEvent extends RequestEvent {
  type: 'request:failed'
  data: Required<Omit<RequestEventData, 'response'>> & {
    errorCode: string
    retryable: boolean
  }
}

流式事件类型

StreamEvent

流式事件接口：

interface StreamEvent extends Event {
  type: StreamEventType
  source: 'stream'
  data: StreamEventData
}

StreamEventType

流式事件类型：

type StreamEventType =
  | 'stream:started'
  | 'stream:chunk'
  | 'stream:completed'
  | 'stream:error'
  | 'stream:cancelled'

StreamEventData

流式事件数据：

interface StreamEventData {
  /** 流ID */
  streamId: string
  
  /** 请求ID */
  requestId: string
  
  /** 数据块（chunk事件时） */
  chunk?: StreamChunk
  
  /** 完整内容（完成时） */
  fullContent?: string
  
  /** 错误信息（错误时） */
  error?: Error
  
  /** 流统计 */
  stats?: StreamStats
}

StreamStats

流统计信息：

interface StreamStats {
  /** 数据块数量 */
  chunkCount: number
  
  /** 总字符数 */
  totalCharacters: number
  
  /** 流持续时间(毫秒) */
  duration: number
  
  /** 平均块大小 */
  averageChunkSize: number
  
  /** 流速率（字符/秒） */
  charactersPerSecond: number
}

适配器事件类型

AdapterEvent

适配器事件接口：

interface AdapterEvent extends Event {
  type: AdapterEventType
  source: 'adapter'
  data: AdapterEventData
}

AdapterEventType

适配器事件类型：

type AdapterEventType =
  | 'adapter:registered'
  | 'adapter:unregistered'
  | 'adapter:initialized'
  | 'adapter:destroyed'
  | 'adapter:health:check'
  | 'adapter:rate:limited'
  | 'adapter:error'

AdapterEventData

适配器事件数据：

interface AdapterEventData {
  /** 适配器名称 */
  name: string
  
  /** 适配器类型 */
  type: string
  
  /** 适配器配置 */
  config?: AdapterConfig
  
  /** 健康状态 */
  health?: HealthStatus
  
  /** 错误信息 */
  error?: Error
  
  /** 统计信息 */
  stats?: AdapterStats
}

插件事件类型

PluginEvent

插件事件接口：

interface PluginEvent extends Event {
  type: PluginEventType
  source: 'plugin'
  data: PluginEventData
}

PluginEventType

插件事件类型：

type PluginEventType =
  | 'plugin:registered'
  | 'plugin:unregistered'
  | 'plugin:enabled'
  | 'plugin:disabled'
  | 'plugin:initialized'
  | 'plugin:destroyed'
  | 'plugin:hook:executed'
  | 'plugin:error'

PluginEventData

插件事件数据：

interface PluginEventData {
  /** 插件名称 */
  name: string
  
  /** 插件版本 */
  version: string
  
  /** 插件配置 */
  config?: PluginConfig
  
  /** 钩子名称（钩子执行事件时） */
  hookName?: string
  
  /** 钩子执行时间(毫秒) */
  hookExecutionTime?: number
  
  /** 错误信息 */
  error?: Error
  
  /** 插件状态 */
  status?: PluginStatus
}

工具事件类型

ToolEvent

工具事件接口：

interface ToolEvent extends Event {
  type: ToolEventType
  source: 'tool'
  data: ToolEventData
}

ToolEventType

工具事件类型：

type ToolEventType =
  | 'tool:registered'
  | 'tool:unregistered'
  | 'tool:execution:started'
  | 'tool:execution:completed'
  | 'tool:execution:failed'
  | 'tool:execution:timeout'
  | 'tool:cache:hit'
  | 'tool:cache:miss'
  | 'tool:rate:limited'
  | 'tool:permission:denied'

ToolEventData

工具事件数据：

interface ToolEventData {
  /** 工具名称 */
  name: string
  
  /** 执行ID */
  executionId?: string
  
  /** 工具参数 */
  parameters?: Record<string, any>
  
  /** 执行结果 */
  result?: ToolResult
  
  /** 执行时间(毫秒) */
  executionTime?: number
  
  /** 错误信息 */
  error?: ToolError
  
  /** 缓存信息 */
  cacheInfo?: CacheInfo
  
  /** 权限信息 */
  permissions?: string[]
}

缓存事件类型

CacheEvent

缓存事件接口：

interface CacheEvent extends Event {
  type: CacheEventType
  source: 'cache'
  data: CacheEventData
}

CacheEventType

缓存事件类型：

type CacheEventType =
  | 'cache:hit'
  | 'cache:miss'
  | 'cache:set'
  | 'cache:delete'
  | 'cache:clear'
  | 'cache:expired'
  | 'cache:evicted'

CacheEventData

缓存事件数据：

interface CacheEventData {
  /** 缓存键 */
  key: string
  
  /** 缓存值大小（字节） */
  size?: number
  
  /** 缓存TTL（秒） */
  ttl?: number
  
  /** 缓存来源 */
  source?: 'memory' | 'redis' | 'file'
  
  /** 过期时间 */
  expiresAt?: Date
  
  /** 访问次数 */
  accessCount?: number
  
  /** 最后访问时间 */
  lastAccessed?: Date
}

错误事件类型

ErrorEvent

错误事件接口：

interface ErrorEvent extends Event {
  type: ErrorEventType
  source: string
  data: ErrorEventData
  priority: 'high' | 'critical'
}

ErrorEventType

错误事件类型：

type ErrorEventType =
  | 'error:system'
  | 'error:request'
  | 'error:adapter'
  | 'error:plugin'
  | 'error:tool'
  | 'error:validation'
  | 'error:permission'
  | 'error:rate:limit'
  | 'error:timeout'
  | 'error:network'
  | 'error:unknown'

ErrorEventData

错误事件数据：

interface ErrorEventData {
  /** 错误对象 */
  error: Error
  
  /** 错误代码 */
  code: string
  
  /** 错误级别 */
  level: 'warning' | 'error' | 'critical'
  
  /** 错误上下文 */
  context?: any
  
  /** 堆栈跟踪 */
  stack?: string
  
  /** 是否可恢复 */
  recoverable: boolean
  
  /** 重试次数 */
  retryCount?: number
  
  /** 相关请求ID */
  requestId?: string
  
  /** 用户影响 */
  userImpact?: 'none' | 'low' | 'medium' | 'high'
}

性能事件类型

PerformanceEvent

性能事件接口：

interface PerformanceEvent extends Event {
  type: PerformanceEventType
  source: 'performance'
  data: PerformanceEventData
}

PerformanceEventType

性能事件类型：

type PerformanceEventType =
  | 'performance:slow:request'
  | 'performance:high:memory'
  | 'performance:high:cpu'
  | 'performance:bottleneck'
  | 'performance:threshold:exceeded'

PerformanceEventData

性能事件数据：

interface PerformanceEventData {
  /** 性能指标 */
  metric: string
  
  /** 当前值 */
  value: number
  
  /** 阈值 */
  threshold: number
  
  /** 单位 */
  unit: string
  
  /** 持续时间(毫秒) */
  duration?: number
  
  /** 相关组件 */
  component?: string
  
  /** 建议操作 */
  recommendation?: string
}

事件管理

EventEmitter

事件发射器接口：

interface EventEmitter {
  /** 发射事件 */
  emit(event: Event): void
  
  /** 发射事件（异步） */
  emitAsync(event: Event): Promise<void>
  
  /** 监听事件 */
  on(type: string, listener: EventListener): void
  
  /** 监听事件（一次） */
  once(type: string, listener: EventListener): void
  
  /** 移除监听器 */
  off(type: string, listener: EventListener): void
  
  /** 移除所有监听器 */
  removeAllListeners(type?: string): void
  
  /** 获取监听器数量 */
  listenerCount(type: string): number
  
  /** 获取所有事件类型 */
  eventNames(): string[]
}

EventListener

事件监听器：

type EventListener = (event: Event) => void | Promise<void>

EventFilter

事件过滤器：

interface EventFilter {
  /** 事件类型过滤 */
  types?: string[]
  
  /** 事件来源过滤 */
  sources?: string[]
  
  /** 优先级过滤 */
  priorities?: EventPriority[]
  
  /** 标签过滤 */
  tags?: string[]
  
  /** 时间范围过滤 */
  timeRange?: {
    start: Date
    end: Date
  }
  
  /** 自定义过滤函数 */
  custom?: (event: Event) => boolean
}

EventStore

事件存储接口：

interface EventStore {
  /** 存储事件 */
  store(event: Event): Promise<void>
  
  /** 批量存储事件 */
  storeBatch(events: Event[]): Promise<void>
  
  /** 查询事件 */
  query(filter: EventFilter, options?: QueryOptions): Promise<Event[]>
  
  /** 获取事件数量 */
  count(filter: EventFilter): Promise<number>
  
  /** 删除事件 */
  delete(filter: EventFilter): Promise<number>
  
  /** 清空存储 */
  clear(): Promise<void>
}

QueryOptions

查询选项：

interface QueryOptions {
  /** 排序字段 */
  sortBy?: 'timestamp' | 'type' | 'priority'
  
  /** 排序方向 */
  sortOrder?: 'asc' | 'desc'
  
  /** 分页 */
  pagination?: {
    page: number
    size: number
  }
  
  /** 限制结果数量 */
  limit?: number
  
  /** 跳过结果数量 */
  offset?: number
}

事件处理器

EventHandler

事件处理器接口：

interface EventHandler {
  /** 处理器名称 */
  name: string
  
  /** 支持的事件类型 */
  supportedTypes: string[]
  
  /** 处理器优先级 */
  priority: number
  
  /** 处理事件 */
  handle(event: Event): Promise<void> | void
  
  /** 是否可以处理事件 */
  canHandle(event: Event): boolean
  
  /** 处理器配置 */
  config?: Record<string, any>
}

EventProcessor

事件处理器：

interface EventProcessor {
  /** 注册处理器 */
  register(handler: EventHandler): void
  
  /** 卸载处理器 */
  unregister(name: string): void
  
  /** 处理事件 */
  process(event: Event): Promise<void>
  
  /** 批量处理事件 */
  processBatch(events: Event[]): Promise<void>
  
  /** 获取处理器 */
  getHandler(name: string): EventHandler | undefined
  
  /** 获取所有处理器 */
  getAllHandlers(): EventHandler[]
}

事件聚合

EventAggregator

事件聚合器：

interface EventAggregator {
  /** 聚合事件 */
  aggregate(events: Event[], options: AggregationOptions): AggregationResult
  
  /** 实时聚合 */
  aggregateRealtime(filter: EventFilter, options: AggregationOptions): Promise<AggregationResult>
  
  /** 创建聚合视图 */
  createView(name: string, config: AggregationViewConfig): void
  
  /** 获取聚合视图 */
  getView(name: string): AggregationResult | undefined
}

AggregationOptions

聚合选项：

interface AggregationOptions {
  /** 聚合类型 */
  type: 'count' | 'sum' | 'average' | 'min' | 'max' | 'group'
  
  /** 聚合字段 */
  field?: string
  
  /** 分组字段 */
  groupBy?: string[]
  
  /** 时间窗口 */
  timeWindow?: {
    size: number
    unit: 'second' | 'minute' | 'hour' | 'day'
  }
  
  /** 过滤条件 */
  filter?: EventFilter
}

AggregationResult

聚合结果：

interface AggregationResult {
  /** 聚合类型 */
  type: string
  
  /** 聚合值 */
  value: any
  
  /** 分组结果 */
  groups?: Record<string, any>
  
  /** 时间序列数据 */
  timeSeries?: TimeSeriesData[]
  
  /** 聚合时间 */
  timestamp: Date
  
  /** 事件数量 */
  eventCount: number
}

TimeSeriesData

时间序列数据：

interface TimeSeriesData {
  /** 时间戳 */
  timestamp: Date
  
  /** 数值 */
  value: number
  
  /** 标签 */
  labels?: Record<string, string>
}

---

这些类型定义为XAI-SDK的事件系统提供了完整的类型支持，确保事件处理的类型安全和一致性。