核心类型定义

本文档定义了XAI-SDK中使用的核心类型和接口。

基础类型

Message

消息对象，用于表示对话中的单条消息：

interface Message {
  /** 消息角色 */
  role: 'user' | 'assistant' | 'system'
  
  /** 消息内容 */
  content: string
  
  /** 消息名称（可选） */
  name?: string
  
  /** 消息元数据 */
  metadata?: Record<string, any>
  
  /** 消息时间戳 */
  timestamp?: Date
  
  /** 消息ID */
  id?: string
}

ChatOptions

聊天请求的配置选项：

interface ChatOptions {
  /** 使用的适配器 */
  adapter?: string
  
  /** 使用的模型 */
  model?: string
  
  /** 温度参数 (0-2) */
  temperature?: number
  
  /** 最大Token数 */
  maxTokens?: number
  
  /** Top-p参数 (0-1) */
  topP?: number
  
  /** 频率惩罚 (-2 to 2) */
  frequencyPenalty?: number
  
  /** 存在惩罚 (-2 to 2) */
  presencePenalty?: number
  
  /** 停止词 */
  stop?: string[]
  
  /** 是否启用工具 */
  tools?: boolean
  
  /** 可用工具列表 */
  availableTools?: string[]
  
  /** 流式响应 */
  stream?: boolean
  
  /** 请求超时时间(毫秒) */
  timeout?: number
  
  /** 重试次数 */
  retries?: number
  
  /** 自定义元数据 */
  metadata?: Record<string, any>
}

ChatResponse

聊天响应对象：

interface ChatResponse {
  /** 响应内容 */
  content: string
  
  /** 使用的模型 */
  model: string
  
  /** 使用的适配器 */
  adapter: string
  
  /** 响应时间(毫秒) */
  responseTime: number
  
  /** 完成原因 */
  finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls'
  
  /** Token使用统计 */
  usage?: TokenUsage
  
  /** 响应元数据 */
  metadata?: Record<string, any>
  
  /** 响应ID */
  id?: string
  
  /** 创建时间 */
  created?: Date
}

StreamChunk

流式响应的数据块：

interface StreamChunk {
  /** 内容片段 */
  content: string
  
  /** 是否为最后一个片段 */
  done: boolean
  
  /** 累计内容 */
  fullContent?: string
  
  /** 完成原因 */
  finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls'
  
  /** 响应元数据 */
  metadata?: Record<string, any>
  
  /** 块索引 */
  index?: number
  
  /** 时间戳 */
  timestamp?: Date
}

TokenUsage

Token使用统计：

interface TokenUsage {
  /** 提示Token数 */
  promptTokens: number
  
  /** 完成Token数 */
  completionTokens: number
  
  /** 总Token数 */
  totalTokens: number
  
  /** 缓存Token数（如果支持） */
  cachedTokens?: number
}

批量处理类型

BatchChatRequest

批量聊天请求项：

interface BatchChatRequest {
  /** 请求ID */
  id: string
  
  /** 消息列表 */
  messages: Message[]
  
  /** 聊天选项 */
  options?: ChatOptions
  
  /** 请求优先级 */
  priority?: 'low' | 'normal' | 'high'
  
  /** 请求元数据 */
  metadata?: Record<string, any>
}

BatchChatResponse

批量聊天响应项：

interface BatchChatResponse {
  /** 请求ID */
  id: string
  
  /** 是否成功 */
  success: boolean
  
  /** 响应数据（成功时） */
  response?: ChatResponse
  
  /** 错误信息（失败时） */
  error?: Error
  
  /** 处理时间(毫秒) */
  processingTime: number
  
  /** 响应状态 */
  status: 'completed' | 'failed' | 'timeout' | 'cancelled'
}

BatchOptions

批量处理选项：

interface BatchOptions {
  /** 并发数量 */
  concurrency?: number
  
  /** 失败时是否继续 */
  continueOnError?: boolean
  
  /** 批量超时时间(毫秒) */
  timeout?: number
  
  /** 进度回调 */
  onProgress?: (completed: number, total: number, failed: number) => void
  
  /** 单项完成回调 */
  onItemComplete?: (response: BatchChatResponse) => void
  
  /** 单项失败回调 */
  onItemError?: (id: string, error: Error) => void
}

配置类型

XAIConfig

SDK主配置接口：

interface XAIConfig {
  /** 默认适配器名称 */
  defaultAdapter?: string
  
  /** 适配器配置 */
  adapters?: Record<string, AdapterConfig>
  
  /** 插件配置 */
  plugins?: PluginConfig[]
  
  /** 中间件配置 */
  middleware?: MiddlewareConfig[]
  
  /** 全局配置 */
  global?: GlobalConfig
  
  /** 缓存配置 */
  cache?: CacheConfig
  
  /** 日志配置 */
  logging?: LoggingConfig
  
  /** 安全配置 */
  security?: SecurityConfig
}

AdapterConfig

适配器配置接口：

interface AdapterConfig {
  /** API密钥 */
  apiKey: string
  
  /** 基础URL */
  baseURL?: string
  
  /** 默认模型 */
  defaultModel?: string
  
  /** 请求超时时间 */
  timeout?: number
  
  /** 最大重试次数 */
  maxRetries?: number
  
  /** 代理配置 */
  proxy?: ProxyConfig
  
  /** 自定义请求头 */
  headers?: Record<string, string>
  
  /** 调试模式 */
  debug?: boolean
  
  /** 速率限制 */
  rateLimit?: RateLimitConfig
}

GlobalConfig

全局配置接口：

interface GlobalConfig {
  /** 默认模型 */
  defaultModel?: string
  
  /** 请求超时时间 */
  timeout?: number
  
  /** 最大重试次数 */
  maxRetries?: number
  
  /** 调试模式 */
  debug?: boolean
  
  /** 日志级别 */
  logLevel?: 'debug' | 'info' | 'warn' | 'error'
  
  /** 环境 */
  environment?: 'development' | 'production' | 'test'
  
  /** 用户代理 */
  userAgent?: string
}

CacheConfig

缓存配置接口：

interface CacheConfig {
  /** 是否启用缓存 */
  enabled?: boolean
  
  /** 缓存过期时间(毫秒) */
  ttl?: number
  
  /** 最大缓存条目数 */
  maxSize?: number
  
  /** 缓存存储类型 */
  storage?: 'memory' | 'redis' | 'file'
  
  /** 存储配置 */
  storageConfig?: Record<string, any>
  
  /** 缓存键前缀 */
  keyPrefix?: string
  
  /** 压缩选项 */
  compression?: boolean
}

LoggingConfig

日志配置接口：

interface LoggingConfig {
  /** 日志级别 */
  level?: 'debug' | 'info' | 'warn' | 'error'
  
  /** 输出格式 */
  format?: 'text' | 'json'
  
  /** 输出目标 */
  output?: 'console' | 'file' | 'both'
  
  /** 日志文件路径 */
  filename?: string
  
  /** 最大文件大小 */
  maxFileSize?: number
  
  /** 最大文件数量 */
  maxFiles?: number
  
  /** 是否包含时间戳 */
  timestamp?: boolean
  
  /** 是否包含调用栈 */
  stackTrace?: boolean
}

健康检查类型

HealthStatus

健康状态接口：

interface HealthStatus {
  /** 状态 */
  status: 'healthy' | 'degraded' | 'unhealthy'
  
  /** 错误信息（如果有） */
  error?: string
  
  /** 检查时间 */
  timestamp: Date
  
  /** 响应时间(毫秒) */
  responseTime?: number
  
  /** 额外信息 */
  details?: Record<string, any>
}

HealthCheckResult

健康检查结果：

interface HealthCheckResult {
  /** 整体状态 */
  status: 'healthy' | 'degraded' | 'unhealthy'
  
  /** 适配器状态 */
  adapters: Record<string, HealthStatus>
  
  /** 插件状态 */
  plugins: Record<string, HealthStatus>
  
  /** 工具状态 */
  tools: Record<string, HealthStatus>
  
  /** 系统信息 */
  system: SystemInfo
  
  /** 检查时间 */
  timestamp: Date
  
  /** 总检查时间(毫秒) */
  totalCheckTime: number
}

SystemInfo

系统信息接口：

interface SystemInfo {
  /** 运行时间(毫秒) */
  uptime: number
  
  /** 内存使用情况 */
  memory: {
    used: number
    total: number
    percentage: number
  }
  
  /** SDK版本 */
  version: string
  
  /** Node.js版本 */
  nodeVersion?: string
  
  /** 操作系统 */
  platform?: string
  
  /** CPU信息 */
  cpu?: {
    model: string
    cores: number
    usage: number
  }
}

统计类型

SDKStats

SDK统计信息：

interface SDKStats {
  /** 请求统计 */
  requests: RequestStats
  
  /** 适配器统计 */
  adapters: Record<string, AdapterStats>
  
  /** 插件统计 */
  plugins: Record<string, PluginStats>
  
  /** Token使用统计 */
  tokens: TokenStats
  
  /** 缓存统计 */
  cache: CacheStats
  
  /** 错误统计 */
  errors: ErrorStats
  
  /** 启动时间 */
  startTime: Date
  
  /** 运行时间(毫秒) */
  uptime: number
}

RequestStats

请求统计：

interface RequestStats {
  /** 总请求数 */
  total: number
  
  /** 成功请求数 */
  successful: number
  
  /** 失败请求数 */
  failed: number
  
  /** 平均响应时间(毫秒) */
  averageResponseTime: number
  
  /** 最小响应时间(毫秒) */
  minResponseTime: number
  
  /** 最大响应时间(毫秒) */
  maxResponseTime: number
  
  /** 每分钟请求数 */
  requestsPerMinute: number
  
  /** 成功率 */
  successRate: number
}

AdapterStats

适配器统计：

interface AdapterStats {
  /** 请求数 */
  requests: number
  
  /** 错误数 */
  errors: number
  
  /** 平均响应时间(毫秒) */
  averageResponseTime: number
  
  /** 最后使用时间 */
  lastUsed: Date
  
  /** 健康状态 */
  healthStatus: HealthStatus
  
  /** Token使用量 */
  tokenUsage: TokenUsage
}

TokenStats

Token统计：

interface TokenStats {
  /** 总提示Token数 */
  totalPromptTokens: number
  
  /** 总完成Token数 */
  totalCompletionTokens: number
  
  /** 总Token数 */
  totalTokens: number
  
  /** 平均每请求Token数 */
  averageTokensPerRequest: number
  
  /** 最大单次Token使用 */
  maxTokensInSingleRequest: number
  
  /** 缓存Token数 */
  cachedTokens: number
}

CacheStats

缓存统计：

interface CacheStats {
  /** 缓存命中数 */
  hits: number
  
  /** 缓存未命中数 */
  misses: number
  
  /** 缓存命中率 */
  hitRate: number
  
  /** 当前缓存条目数 */
  currentSize: number
  
  /** 最大缓存条目数 */
  maxSize: number
  
  /** 缓存使用率 */
  usageRate: number
  
  /** 过期条目数 */
  expiredEntries: number
}

工具类型

Tool

工具定义接口：

interface Tool {
  /** 工具名称 */
  name: string
  
  /** 工具描述 */
  description: string
  
  /** 参数定义 */
  parameters: {
    type: 'object'
    properties: Record<string, ParameterDefinition>
    required?: string[]
  }
  
  /** 执行函数 */
  execute: (parameters: Record<string, any>) => Promise<any>
  
  /** 工具版本 */
  version?: string
  
  /** 工具分类 */
  category?: string
  
  /** 是否异步 */
  async?: boolean
  
  /** 超时时间(毫秒) */
  timeout?: number
}

ParameterDefinition

参数定义：

interface ParameterDefinition {
  /** 参数类型 */
  type: 'string' | 'number' | 'boolean' | 'array' | 'object'
  
  /** 参数描述 */
  description: string
  
  /** 默认值 */
  default?: any
  
  /** 枚举值 */
  enum?: any[]
  
  /** 最小值（数字类型） */
  minimum?: number
  
  /** 最大值（数字类型） */
  maximum?: number
  
  /** 最小长度（字符串/数组类型） */
  minLength?: number
  
  /** 最大长度（字符串/数组类型） */
  maxLength?: number
  
  /** 正则表达式（字符串类型） */
  pattern?: string
  
  /** 数组项类型（数组类型） */
  items?: ParameterDefinition
  
  /** 对象属性（对象类型） */
  properties?: Record<string, ParameterDefinition>
}

ToolResult

工具执行结果：

interface ToolResult {
  /** 是否成功 */
  success: boolean
  
  /** 结果内容 */
  content: any
  
  /** 错误信息（失败时） */
  error?: string
  
  /** 执行时间(毫秒) */
  executionTime: number
  
  /** 工具名称 */
  toolName: string
  
  /** 执行时间戳 */
  timestamp: Date
  
  /** 元数据 */
  metadata?: Record<string, any>
}

错误类型

XAIError

基础错误类：

class XAIError extends Error {
  constructor(
    message: string,
    public code: string,
    public details?: any
  ) {
    super(message)
    this.name = 'XAIError'
  }
}

ErrorCodes

错误代码枚举：

const ErrorCodes = {
  // 初始化错误
  INITIALIZATION_FAILED: 'INITIALIZATION_FAILED',
  
  // 配置错误
  INVALID_CONFIG: 'INVALID_CONFIG',
  CONFIG_VALIDATION_FAILED: 'CONFIG_VALIDATION_FAILED',
  
  // 适配器错误
  ADAPTER_NOT_FOUND: 'ADAPTER_NOT_FOUND',
  ADAPTER_INITIALIZATION_FAILED: 'ADAPTER_INITIALIZATION_FAILED',
  ADAPTER_REQUEST_FAILED: 'ADAPTER_REQUEST_FAILED',
  
  // 插件错误
  PLUGIN_NOT_FOUND: 'PLUGIN_NOT_FOUND',
  PLUGIN_INITIALIZATION_FAILED: 'PLUGIN_INITIALIZATION_FAILED',
  PLUGIN_EXECUTION_FAILED: 'PLUGIN_EXECUTION_FAILED',
  
  // 工具错误
  TOOL_NOT_FOUND: 'TOOL_NOT_FOUND',
  TOOL_EXECUTION_FAILED: 'TOOL_EXECUTION_FAILED',
  TOOL_TIMEOUT: 'TOOL_TIMEOUT',
  
  // 请求错误
  REQUEST_FAILED: 'REQUEST_FAILED',
  REQUEST_TIMEOUT: 'REQUEST_TIMEOUT',
  INVALID_REQUEST: 'INVALID_REQUEST',
  
  // 认证错误
  AUTHENTICATION_FAILED: 'AUTHENTICATION_FAILED',
  INVALID_API_KEY: 'INVALID_API_KEY',
  
  // 限制错误
  RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
  QUOTA_EXCEEDED: 'QUOTA_EXCEEDED',
  
  // 网络错误
  NETWORK_ERROR: 'NETWORK_ERROR',
  CONNECTION_FAILED: 'CONNECTION_FAILED',
  
  // 其他错误
  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
  INTERNAL_ERROR: 'INTERNAL_ERROR'
} as const

type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes]

实用类型

Nullable

可空类型：

type Nullable<T> = T | null

Optional

可选类型：

type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>

DeepPartial

深度可选类型：

type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P]
}

AsyncFunction

异步函数类型：

type AsyncFunction<T extends any[] = any[], R = any> = (...args: T) => Promise<R>

EventListener

事件监听器类型：

type EventListener<T extends any[] = any[]> = (...args: T) => void | Promise<void>

---

这些类型定义构成了XAI-SDK的类型系统基础，确保了类型安全和良好的开发体验。