XAI-SDK API 参考文档

本文档提供了 XAI-SDK 的完整 API 参考，包括所有类、接口、方法和类型定义。

📋 目录

核心 API
插件系统 API
工具系统 API
适配器系统 API
事件系统 API
类型定义
错误处理

核心 API

XAI_SDK 类

主要的 SDK 类，提供所有核心功能。

typescript

class XAI_SDK {
  constructor(options?: SDKConstructorOptions)
  
  // 生命周期方法
  initialize(options?: SDKInitOptions): Promise<void>
  destroy(): Promise<void>
  isInitialized(): boolean
  
  // 插件管理
  registerPlugin(plugin: Plugin): Promise<void>
  unregisterPlugin(pluginName: string): Promise<void>
  getPlugin(name: string): Plugin | null
  getAllPlugins(): Plugin[]
  isPluginRegistered(name: string): boolean
  
  // 工具执行
  executeTool(name: string, parameters: any): Promise<any>
  getAvailableTools(): ToolInfo[]
  getToolInfo(name: string): ToolInfo | null
  
  // 适配器执行
  executeAdapter(name: string, method: string, ...args: any[]): Promise<any>
  getAvailableAdapters(): AdapterInfo[]
  
  // AI 功能
  chat(options: ChatOptions): Promise<ChatResponse>
  chatStream(options: ChatOptions): AsyncGenerator<ChatChunk>
  
  // 代码功能
  analyze(code: string, options?: AnalysisOptions): Promise<AnalysisResult>
  generate(prompt: string, options?: GenerationOptions): Promise<GenerationResult>
  refactor(code: string, options?: RefactorOptions): Promise<RefactorResult>
  
  // 环境信息
  getEnvironment(): EnvironmentInfo
  getVersion(): string
  getConfig(): SDKConfig
  
  // 事件处理
  on(event: string, listener: Function): this
  off(event: string, listener: Function): this
  emit(event: string, ...args: any[]): boolean
}

构造函数选项

typescript

interface SDKConstructorOptions {
  environment?: 'node' | 'browser'
  config?: Partial<SDKConfig>
  plugins?: Plugin[]
}

interface SDKConfig {
  // AI 配置
  aiProvider?: string
  apiKey?: string
  model?: string
  baseURL?: string
  
  // 日志配置
  logging?: {
    level: 'debug' | 'info' | 'warn' | 'error'
    output?: 'console' | 'file'
    file?: string
  }
  
  // 工具配置
  tools?: {
    enabled?: string[]
    disabled?: string[]
    config?: Record<string, any>
  }
  
  // 缓存配置
  cache?: {
    enabled?: boolean
    size?: number
    ttl?: number
  }
}

初始化选项

typescript

interface SDKInitOptions {
  autoRegisterPlugins?: boolean
  validateEnvironment?: boolean
  loadConfig?: boolean
  configPath?: string
}

使用示例

typescript

import { XAI_SDK } from 'xai-sdk'

// 创建 SDK 实例
const sdk = new XAI_SDK({
  environment: 'node',
  config: {
    aiProvider: 'openai',
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4',
    logging: {
      level: 'info',
      output: 'console'
    }
  }
})

// 初始化
await sdk.initialize({
  autoRegisterPlugins: true,
  validateEnvironment: true
})

// 使用功能
const response = await sdk.chat({
  messages: [{ role: 'user', content: 'Hello!' }]
})

插件系统 API

Plugin 接口

所有插件必须实现的基础接口。

typescript

interface Plugin {
  readonly name: string
  readonly version: string
  readonly metadata: PluginMetadata
  
  dependencies?: PluginDependency[]
  supportedEnvironments?: Environment[]
  requiredSDKVersion?: string
  tools?: Record<string, ToolDefinition>
  adapters?: Record<string, AdapterDefinition>
  
  // 生命周期方法
  initialize(sdk?: XAISDKInstance): Promise<boolean>
  enable?(): Promise<boolean>
  disable?(): Promise<boolean>
  reload?(): Promise<boolean>
  destroy(): Promise<boolean>
  
  // 状态查询
  getState(): PluginState
  isInitialized(): boolean
  
  // 配置管理
  setSDKInstance?(sdk: XAISDKInstance): void
  getConfig?(): Record<string, any>
  updateConfig?(config: Record<string, any>): void
}

BasePlugin 类

插件开发的基础类，提供默认实现和工具方法。

typescript

abstract class BasePlugin implements Plugin {
  // 抽象属性（子类必须实现）
  abstract readonly name: string
  abstract readonly version: string
  abstract readonly metadata: PluginMetadata
  
  // 可选属性
  dependencies?: PluginDependency[]
  supportedEnvironments?: Environment[]
  requiredSDKVersion?: string
  tools?: Record<string, ToolDefinition>
  adapters?: Record<string, AdapterDefinition>
  
  // 构造函数
  constructor(options?: Record<string, any>)
  
  // 生命周期方法（子类可重写）
  protected abstract onInitialize(): Promise<void>
  protected async onEnable(): Promise<void>
  protected async onDisable(): Promise<void>
  protected async onReload(): Promise<void>
  protected async onDestroy(): Promise<void>
  
  // 公共方法
  setSDKInstance(sdk: XAISDKInstance): void
  initialize(sdk?: XAISDKInstance): Promise<boolean>
  enable(): Promise<boolean>
  disable(): Promise<boolean>
  reload(): Promise<boolean>
  destroy(): Promise<boolean>
  
  // 状态管理
  getState(): PluginState
  isInitialized(): boolean
  isEnabled(): boolean
  isDestroyed(): boolean
  
  // 配置管理
  getConfig(): Record<string, any>
  getConfigValue(key: string, defaultValue?: any): any
  setConfig(config: Record<string, any>): void
  updateConfig(updates: Record<string, any>): void
  
  // 工具方法
  supportsEnvironment(environment: Environment): boolean
  
  // 日志方法
  protected log(level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: any): void
  protected debug(message: string, data?: any): void
  
  // 事件方法
  on(event: string, listener: Function): this
  emit(event: string, ...args: any[]): boolean
  removeAllListeners(event?: string): this
}

SimplePlugin 类

简化的插件类，适用于简单插件。

typescript

class SimplePlugin extends BasePlugin {
  constructor(options: {
    name: string
    version: string
    metadata: PluginMetadata
    dependencies?: PluginDependency[]
    supportedEnvironments?: Environment[]
    tools?: Record<string, ToolDefinition>
    adapters?: Record<string, AdapterDefinition>
    config?: Record<string, any>
    handlers?: {
      initialize?: (sdk: XAISDKInstance) => Promise<void>
      enable?: () => Promise<void>
      disable?: () => Promise<void>
      destroy?: () => Promise<void>
    }
  })
}

createPlugin 工厂函数

创建插件的便捷函数。

typescript

function createPlugin(options: {
  name: string
  version: string
  metadata: PluginMetadata
  dependencies?: PluginDependency[]
  supportedEnvironments?: Environment[]
  tools?: Record<string, ToolDefinition>
  adapters?: Record<string, AdapterDefinition>
  config?: Record<string, any>
  handlers?: {
    initialize?: (sdk: XAISDKInstance) => Promise<void>
    enable?: () => Promise<void>
    disable?: () => Promise<void>
    destroy?: () => Promise<void>
  }
}): Plugin

插件类型定义

typescript

interface PluginMetadata {
  description: string
  author: string
  tags: string[]
  homepage?: string
  repository?: string
  license?: string
  keywords?: string[]
  icon?: string
  screenshots?: string[]
}

interface PluginDependency {
  name: string
  version: string
  optional: boolean
}

type PluginState = 
  | 'uninitialized'
  | 'initializing'
  | 'initialized'
  | 'enabling'
  | 'enabled'
  | 'disabling'
  | 'disabled'
  | 'reloading'
  | 'destroying'
  | 'destroyed'
  | 'error'

type Environment = 'node' | 'browser' | 'worker' | 'electron'

工具系统 API

Tool 接口

工具的基础接口。

typescript

interface Tool {
  name: string
  description: string
  parameters: Record<string, ParameterDefinition>
  execute(parameters: any): Promise<any>
  validate?(parameters: any): boolean | string
  examples?: ToolExample[]
}

ToolDefinition 接口

插件中定义工具的接口。

typescript

interface ToolDefinition {
  name: string
  description: string
  parameters: Record<string, ParameterDefinition>
  handler: ToolHandler
  category?: string
  version?: string
  examples?: ToolExample[]
  metadata?: Record<string, any>
}

type ToolHandler = (parameters: any) => Promise<any>

参数定义

typescript

interface ParameterDefinition {
  type: 'string' | 'number' | 'boolean' | 'array' | 'object'
  required: boolean
  description?: string
  default?: any
  enum?: any[]
  validation?: (value: any) => boolean | string
  examples?: any[]
}

工具示例

typescript

interface ToolExample {
  description: string
  parameters: any
  expectedOutput?: any
}

ToolRegistry 类

工具注册和管理。

typescript

class ToolRegistry {
  // 注册工具
  register(tool: Tool, metadata?: Partial<ToolMetadata>): void
  
  // 获取工具
  get(name: string): Tool | undefined
  has(name: string): boolean
  
  // 执行工具
  execute(name: string, parameters: any): Promise<any>
  
  // 查询工具
  list(): ToolInfo[]
  getByCategory(category: string): ToolInfo[]
  search(query: string): ToolInfo[]
  
  // 管理工具
  unregister(name: string): boolean
  enable(name: string): boolean
  disable(name: string): boolean
  
  // 验证
  validate(name: string, parameters: any): boolean | string
}

适配器系统 API

Adapter 接口

适配器的基础接口。

typescript

interface Adapter {
  adapt(input: any, context?: any): Promise<any>
  validate?(input: any): boolean
  transform?(data: any): any
  configure?(config: any): void
}

AdapterDefinition 接口

插件中定义适配器的接口。

typescript

interface AdapterDefinition {
  name: string
  type: string
  description: string
  config?: Record<string, any>
  handler: Adapter
  methods?: Record<string, Function>
  metadata?: Record<string, any>
}

AdapterRegistry 类

适配器注册和管理。

typescript

class AdapterRegistry {
  // 注册适配器
  register(adapter: AdapterDefinition): void
  
  // 获取适配器
  get(name: string): AdapterDefinition | undefined
  has(name: string): boolean
  
  // 执行适配器
  execute(name: string, method: string, ...args: any[]): Promise<any>
  
  // 查询适配器
  list(): AdapterInfo[]
  getByType(type: string): AdapterInfo[]
  
  // 管理适配器
  unregister(name: string): boolean
  configure(name: string, config: any): boolean
}

事件系统 API

事件列表

SDK 和插件系统发出的标准事件：

typescript

// SDK 事件
'initialized'           // SDK 初始化完成
'destroyed'            // SDK 销毁完成
'error'                // 错误发生
'config-updated'       // 配置更新

// 插件事件
'plugin:registered'    // 插件注册
'plugin:unregistered'  // 插件卸载
'plugin:enabled'       // 插件启用
'plugin:disabled'      // 插件禁用
'plugin:error'         // 插件错误

// 工具事件
'tool:executed'        // 工具执行
'tool:error'          // 工具错误

// AI 事件
'chat:start'          // 对话开始
'chat:stream'         // 流式数据
'chat:complete'       // 对话完成
'chat:error'          // 对话错误

事件处理

typescript

// 监听事件
sdk.on('plugin:registered', (event) => {
  console.log(`插件已注册: ${event.plugin}`)
})

// 监听错误
sdk.on('error', (error) => {
  console.error('SDK 错误:', error)
})

// 监听工具执行
sdk.on('tool:executed', (event) => {
  console.log(`工具 ${event.toolName} 执行完成`)
})

// 移除监听器
const handler = (event) => { /* ... */ }
sdk.on('chat:complete', handler)
sdk.off('chat:complete', handler)

// 一次性监听
sdk.once('initialized', () => {
  console.log('SDK 已初始化')
})

类型定义

聊天相关类型

typescript

interface ChatOptions {
  messages: ChatMessage[]
  provider?: string
  model?: string
  temperature?: number
  maxTokens?: number
  tools?: string[]
  stream?: boolean
}

interface ChatMessage {
  role: 'system' | 'user' | 'assistant'
  content: string
  metadata?: Record<string, any>
}

interface ChatResponse {
  id: string
  content: string
  role: 'assistant'
  model: string
  usage: {
    promptTokens: number
    completionTokens: number
    totalTokens: number
  }
  finishReason: string
}

interface ChatChunk {
  id: string
  content: string
  delta: string
  done: boolean
}

分析相关类型

typescript

interface AnalysisOptions {
  type?: 'complexity' | 'security' | 'performance' | 'quality'
  language?: string
  rules?: string[]
  includeMetrics?: boolean
}

interface AnalysisResult {
  summary: string
  issues: Issue[]
  metrics: Record<string, number>
  suggestions: string[]
  metadata: Record<string, any>
}

interface Issue {
  type: 'error' | 'warning' | 'info'
  message: string
  line?: number
  column?: number
  rule?: string
  severity: number
}

生成相关类型

typescript

interface GenerationOptions {
  language?: string
  framework?: string
  style?: string
  includeComments?: boolean
  includeTests?: boolean
}

interface GenerationResult {
  code: string
  language: string
  explanation?: string
  suggestions?: string[]
  metadata: Record<string, any>
}

重构相关类型

typescript

interface RefactorOptions {
  type?: 'extract' | 'inline' | 'rename' | 'optimize'
  target?: string
  newName?: string
  preserveComments?: boolean
}

interface RefactorResult {
  code: string
  changes: RefactorChange[]
  summary: string
  metadata: Record<string, any>
}

interface RefactorChange {
  type: 'add' | 'remove' | 'modify'
  line: number
  column?: number
  oldText?: string
  newText?: string
}

错误处理

SDKError 类

typescript

class SDKError extends Error {
  readonly code: string
  readonly details?: any
  readonly cause?: Error
  
  constructor(message: string, code: string, details?: any, cause?: Error)
  
  static isSDKError(error: any): error is SDKError
}

错误代码

typescript

// 初始化错误
'INITIALIZATION_FAILED'     // 初始化失败
'INVALID_ENVIRONMENT'       // 环境不支持
'MISSING_DEPENDENCIES'      // 缺少依赖

// 插件错误
'PLUGIN_NOT_FOUND'         // 插件未找到
'PLUGIN_ALREADY_REGISTERED' // 插件已注册
'PLUGIN_INITIALIZATION_FAILED' // 插件初始化失败
'INCOMPATIBLE_PLUGIN'      // 插件不兼容

// 工具错误
'TOOL_NOT_FOUND'           // 工具未找到
'INVALID_PARAMETERS'       // 参数无效
'TOOL_EXECUTION_FAILED'    // 工具执行失败

// AI 错误
'AI_PROVIDER_ERROR'        // AI 提供商错误
'INVALID_API_KEY'          // API 密钥无效
'RATE_LIMIT_EXCEEDED'      // 速率限制
'MODEL_NOT_AVAILABLE'      // 模型不可用

// 配置错误
'INVALID_CONFIG'           // 配置无效
'CONFIG_LOAD_FAILED'       // 配置加载失败

错误处理示例

typescript

try {
  await sdk.executeTool('non-existent-tool', {})
} catch (error) {
  if (SDKError.isSDKError(error)) {
    switch (error.code) {
      case 'TOOL_NOT_FOUND':
        console.log('工具不存在，请检查插件是否已注册')
        break
      case 'INVALID_PARAMETERS':
        console.log('参数无效:', error.details)
        break
      default:
        console.error('SDK 错误:', error.message)
    }
  } else {
    console.error('未知错误:', error)
  }
}

🔗 相关链接

快速开始 - 快速入门指南
使用指南 - 详细使用说明
插件开发 - 插件开发指南
示例项目 - 实际使用示例

🆘 获取帮助

📚 API 参考文档 - 完整的 XAI-SDK API 接口说明，助您快速开发！

XAI-SDK API 参考文档 ​

📋 目录 ​

核心 API ​

XAI_SDK 类 ​

构造函数选项 ​

初始化选项 ​

使用示例 ​

插件系统 API ​

Plugin 接口 ​

BasePlugin 类 ​

SimplePlugin 类 ​

createPlugin 工厂函数 ​

插件类型定义 ​

工具系统 API ​

Tool 接口 ​

ToolDefinition 接口 ​

参数定义 ​

工具示例 ​

ToolRegistry 类 ​

适配器系统 API ​

Adapter 接口 ​

AdapterDefinition 接口 ​

AdapterRegistry 类 ​

事件系统 API ​

事件列表 ​

事件处理 ​

类型定义 ​

聊天相关类型 ​

分析相关类型 ​

生成相关类型 ​

重构相关类型 ​

错误处理 ​

SDKError 类 ​

错误代码 ​

错误处理示例 ​

🔗 相关链接 ​

🆘 获取帮助 ​

XAI-SDK API 参考文档

📋 目录

核心 API

XAI_SDK 类

构造函数选项

初始化选项

使用示例

插件系统 API

Plugin 接口

BasePlugin 类

SimplePlugin 类

createPlugin 工厂函数

插件类型定义

工具系统 API

Tool 接口

ToolDefinition 接口

参数定义

工具示例

ToolRegistry 类

适配器系统 API

Adapter 接口

AdapterDefinition 接口

AdapterRegistry 类

事件系统 API

事件列表

事件处理

类型定义

聊天相关类型

分析相关类型

生成相关类型

重构相关类型

错误处理

SDKError 类

错误代码

错误处理示例

🔗 相关链接

🆘 获取帮助