工具类型定义

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

基础工具接口

Tool

工具定义接口：

interface Tool {
  /** 工具名称 */
  name: string
  
  /** 工具描述 */
  description: string
  
  /** 工具版本 */
  version?: string
  
  /** 工具作者 */
  author?: string
  
  /** 工具分类 */
  category?: ToolCategory
  
  /** 工具标签 */
  tags?: string[]
  
  /** 参数定义 */
  parameters: ToolParameters
  
  /** 执行函数 */
  execute: ToolExecutor
  
  /** 工具配置 */
  config?: ToolConfig
  
  /** 工具权限 */
  permissions?: ToolPermissions
  
  /** 工具依赖 */
  dependencies?: string[]
  
  /** 工具元数据 */
  metadata?: Record<string, any>
}

ToolCategory

工具分类：

type ToolCategory =
  | 'file-system'
  | 'network'
  | 'database'
  | 'text-processing'
  | 'image-processing'
  | 'data-analysis'
  | 'web-scraping'
  | 'api-integration'
  | 'utility'
  | 'development'
  | 'system'
  | 'custom'

ToolParameters

工具参数定义：

interface ToolParameters {
  /** 参数类型 */
  type: 'object'
  
  /** 参数属性 */
  properties: Record<string, ParameterDefinition>
  
  /** 必需参数 */
  required?: string[]
  
  /** 附加属性 */
  additionalProperties?: boolean
  
  /** 参数示例 */
  examples?: Record<string, any>[]
}

ParameterDefinition

参数定义：

interface ParameterDefinition {
  /** 参数类型 */
  type: ParameterType
  
  /** 参数描述 */
  description: string
  
  /** 默认值 */
  default?: any
  
  /** 枚举值 */
  enum?: any[]
  
  /** 示例值 */
  examples?: any[]
  
  /** 格式 */
  format?: string
  
  /** 最小值（数字类型） */
  minimum?: number
  
  /** 最大值（数字类型） */
  maximum?: number
  
  /** 最小长度（字符串/数组类型） */
  minLength?: number
  
  /** 最大长度（字符串/数组类型） */
  maxLength?: number
  
  /** 正则表达式（字符串类型） */
  pattern?: string
  
  /** 数组项类型（数组类型） */
  items?: ParameterDefinition
  
  /** 对象属性（对象类型） */
  properties?: Record<string, ParameterDefinition>
  
  /** 是否必需 */
  required?: string[]
  
  /** 是否只读 */
  readOnly?: boolean
  
  /** 是否已弃用 */
  deprecated?: boolean
}

ParameterType

参数类型：

type ParameterType =
  | 'string'
  | 'number'
  | 'integer'
  | 'boolean'
  | 'array'
  | 'object'
  | 'null'

ToolExecutor

工具执行器：

type ToolExecutor = (
  parameters: Record<string, any>,
  context?: ToolExecutionContext
) => Promise<ToolResult> | ToolResult

ToolExecutionContext

工具执行上下文：

interface ToolExecutionContext {
  /** 执行ID */
  executionId: string
  
  /** SDK实例 */
  sdk: XAI_SDK
  
  /** 用户ID */
  userId?: string
  
  /** 会话ID */
  sessionId?: string
  
  /** 请求ID */
  requestId?: string
  
  /** 执行环境 */
  environment: 'development' | 'production' | 'test'
  
  /** 权限上下文 */
  permissions: PermissionContext
  
  /** 日志记录器 */
  logger: Logger
  
  /** 缓存管理器 */
  cache?: CacheManager
  
  /** 配置对象 */
  config: any
  
  /** 元数据 */
  metadata?: Record<string, any>
}

PermissionContext

权限上下文：

interface PermissionContext {
  /** 用户角色 */
  roles: string[]
  
  /** 权限列表 */
  permissions: string[]
  
  /** 资源访问权限 */
  resources: Record<string, string[]>
  
  /** 是否为管理员 */
  isAdmin: boolean
  
  /** 权限检查函数 */
  hasPermission: (permission: string) => boolean
  
  /** 资源访问检查 */
  canAccess: (resource: string, action: string) => boolean
}

工具结果

ToolResult

工具执行结果：

interface ToolResult {
  /** 是否成功 */
  success: boolean
  
  /** 结果内容 */
  content: any
  
  /** 结果类型 */
  type?: ToolResultType
  
  /** 错误信息（失败时） */
  error?: ToolError
  
  /** 执行时间(毫秒) */
  executionTime: number
  
  /** 工具名称 */
  toolName: string
  
  /** 执行时间戳 */
  timestamp: Date
  
  /** 结果元数据 */
  metadata?: ToolResultMetadata
  
  /** 资源使用情况 */
  resourceUsage?: ResourceUsage
  
  /** 缓存信息 */
  cacheInfo?: CacheInfo
}

ToolResultType

工具结果类型：

type ToolResultType =
  | 'text'
  | 'json'
  | 'binary'
  | 'image'
  | 'file'
  | 'url'
  | 'html'
  | 'markdown'
  | 'csv'
  | 'xml'
  | 'custom'

ToolResultMetadata

工具结果元数据：

interface ToolResultMetadata {
  /** 结果大小（字节） */
  size?: number
  
  /** MIME类型 */
  mimeType?: string
  
  /** 文件名 */
  filename?: string
  
  /** 编码 */
  encoding?: string
  
  /** 语言 */
  language?: string
  
  /** 版本 */
  version?: string
  
  /** 来源 */
  source?: string
  
  /** 自定义属性 */
  custom?: Record<string, any>
}

ResourceUsage

资源使用情况：

interface ResourceUsage {
  /** CPU使用时间(毫秒) */
  cpuTime?: number
  
  /** 内存使用量（字节） */
  memoryUsage?: number
  
  /** 磁盘读取量（字节） */
  diskRead?: number
  
  /** 磁盘写入量（字节） */
  diskWrite?: number
  
  /** 网络接收量（字节） */
  networkReceived?: number
  
  /** 网络发送量（字节） */
  networkSent?: number
  
  /** API调用次数 */
  apiCalls?: number
}

CacheInfo

缓存信息：

interface CacheInfo {
  /** 是否命中缓存 */
  hit: boolean
  
  /** 缓存键 */
  key?: string
  
  /** 缓存时间戳 */
  timestamp?: Date
  
  /** 缓存TTL（秒） */
  ttl?: number
  
  /** 缓存来源 */
  source?: 'memory' | 'disk' | 'redis' | 'database'
}

工具错误

ToolError

工具错误接口：

interface ToolError {
  /** 错误代码 */
  code: ToolErrorCode
  
  /** 错误消息 */
  message: string
  
  /** 错误详情 */
  details?: any
  
  /** 错误堆栈 */
  stack?: string
  
  /** 是否可重试 */
  retryable: boolean
  
  /** 建议操作 */
  suggestion?: string
  
  /** 相关文档链接 */
  documentation?: string
}

ToolErrorCode

工具错误代码：

type ToolErrorCode =
  | 'TOOL_NOT_FOUND'
  | 'INVALID_PARAMETERS'
  | 'PARAMETER_VALIDATION_FAILED'
  | 'EXECUTION_FAILED'
  | 'EXECUTION_TIMEOUT'
  | 'PERMISSION_DENIED'
  | 'RESOURCE_NOT_AVAILABLE'
  | 'DEPENDENCY_MISSING'
  | 'CONFIGURATION_ERROR'
  | 'NETWORK_ERROR'
  | 'FILE_NOT_FOUND'
  | 'INSUFFICIENT_RESOURCES'
  | 'RATE_LIMIT_EXCEEDED'
  | 'INTERNAL_ERROR'
  | 'UNKNOWN_ERROR'

工具配置

ToolConfig

工具配置接口：

interface ToolConfig {
  /** 是否启用 */
  enabled?: boolean
  
  /** 超时时间(毫秒) */
  timeout?: number
  
  /** 重试次数 */
  retries?: number
  
  /** 重试延迟(毫秒) */
  retryDelay?: number
  
  /** 缓存配置 */
  cache?: ToolCacheConfig
  
  /** 速率限制 */
  rateLimit?: RateLimitConfig
  
  /** 资源限制 */
  resourceLimits?: ResourceLimits
  
  /** 日志配置 */
  logging?: ToolLoggingConfig
  
  /** 环境限制 */
  environments?: ('development' | 'production' | 'test')[]
  
  /** 自定义配置 */
  custom?: Record<string, any>
}

ToolCacheConfig

工具缓存配置：

interface ToolCacheConfig {
  /** 是否启用缓存 */
  enabled: boolean
  
  /** 缓存TTL（秒） */
  ttl?: number
  
  /** 缓存键生成策略 */
  keyStrategy?: 'parameters' | 'hash' | 'custom'
  
  /** 自定义键生成函数 */
  keyGenerator?: (parameters: any) => string
  
  /** 缓存条件 */
  condition?: (parameters: any, result: ToolResult) => boolean
  
  /** 缓存存储 */
  storage?: 'memory' | 'redis' | 'file'
}

RateLimitConfig

速率限制配置：

interface RateLimitConfig {
  /** 每分钟最大请求数 */
  requestsPerMinute?: number
  
  /** 每小时最大请求数 */
  requestsPerHour?: number
  
  /** 每天最大请求数 */
  requestsPerDay?: number
  
  /** 并发限制 */
  concurrency?: number
  
  /** 限制策略 */
  strategy?: 'sliding-window' | 'fixed-window' | 'token-bucket'
  
  /** 限制键生成 */
  keyGenerator?: (context: ToolExecutionContext) => string
}

ResourceLimits

资源限制：

interface ResourceLimits {
  /** 最大内存使用量（字节） */
  maxMemory?: number
  
  /** 最大CPU时间(毫秒) */
  maxCpuTime?: number
  
  /** 最大磁盘使用量（字节） */
  maxDiskUsage?: number
  
  /** 最大网络使用量（字节） */
  maxNetworkUsage?: number
  
  /** 最大文件大小（字节） */
  maxFileSize?: number
  
  /** 最大并发数 */
  maxConcurrency?: number
}

ToolLoggingConfig

工具日志配置：

interface ToolLoggingConfig {
  /** 是否记录执行日志 */
  logExecution?: boolean
  
  /** 是否记录参数 */
  logParameters?: boolean
  
  /** 是否记录结果 */
  logResults?: boolean
  
  /** 是否记录错误 */
  logErrors?: boolean
  
  /** 日志级别 */
  level?: 'debug' | 'info' | 'warn' | 'error'
  
  /** 敏感参数过滤 */
  sensitiveFields?: string[]
}

工具权限

ToolPermissions

工具权限接口：

interface ToolPermissions {
  /** 所需权限列表 */
  required: string[]
  
  /** 可选权限列表 */
  optional?: string[]
  
  /** 权限检查函数 */
  check?: (context: PermissionContext) => boolean | Promise<boolean>
  
  /** 权限描述 */
  description?: Record<string, string>
  
  /** 权限分组 */
  groups?: string[]
}

PermissionLevel

权限级别：

type PermissionLevel =
  | 'public'
  | 'authenticated'
  | 'user'
  | 'admin'
  | 'system'
  | 'custom'

工具管理

ToolManager

工具管理器接口：

interface ToolManager {
  /** 注册工具 */
  register(tool: Tool): Promise<void>
  
  /** 注册多个工具 */
  registerMany(tools: Tool[]): Promise<void>
  
  /** 卸载工具 */
  unregister(name: string): Promise<void>
  
  /** 获取工具 */
  get(name: string): Tool | undefined
  
  /** 获取所有工具 */
  getAll(): Tool[]
  
  /** 按分类获取工具 */
  getByCategory(category: ToolCategory): Tool[]
  
  /** 搜索工具 */
  search(query: ToolSearchQuery): Tool[]
  
  /** 执行工具 */
  execute(
    name: string,
    parameters: Record<string, any>,
    context?: ToolExecutionContext
  ): Promise<ToolResult>
  
  /** 批量执行工具 */
  executeBatch(requests: ToolExecutionRequest[]): Promise<ToolResult[]>
  
  /** 验证工具 */
  validate(tool: Tool): ValidationResult
  
  /** 验证参数 */
  validateParameters(tool: Tool, parameters: Record<string, any>): ValidationResult
  
  /** 获取工具统计 */
  getStats(name?: string): ToolStats | Record<string, ToolStats>
  
  /** 清理工具 */
  cleanup(): Promise<void>
}

ToolSearchQuery

工具搜索查询：

interface ToolSearchQuery {
  /** 搜索关键词 */
  keyword?: string
  
  /** 工具分类 */
  category?: ToolCategory
  
  /** 工具标签 */
  tags?: string[]
  
  /** 作者 */
  author?: string
  
  /** 是否启用 */
  enabled?: boolean
  
  /** 权限要求 */
  permissions?: string[]
  
  /** 排序方式 */
  sortBy?: 'name' | 'category' | 'usage' | 'rating'
  
  /** 排序方向 */
  sortOrder?: 'asc' | 'desc'
  
  /** 分页 */
  pagination?: {
    page: number
    size: number
  }
}

ToolExecutionRequest

工具执行请求：

interface ToolExecutionRequest {
  /** 请求ID */
  id: string
  
  /** 工具名称 */
  toolName: string
  
  /** 工具参数 */
  parameters: Record<string, any>
  
  /** 执行上下文 */
  context?: ToolExecutionContext
  
  /** 请求优先级 */
  priority?: 'low' | 'normal' | 'high'
  
  /** 请求元数据 */
  metadata?: Record<string, any>
}

工具统计

ToolStats

工具统计信息：

interface ToolStats {
  /** 工具名称 */
  name: string
  
  /** 执行次数 */
  executionCount: number
  
  /** 成功次数 */
  successCount: number
  
  /** 失败次数 */
  failureCount: number
  
  /** 成功率 */
  successRate: number
  
  /** 平均执行时间(毫秒) */
  averageExecutionTime: number
  
  /** 最小执行时间(毫秒) */
  minExecutionTime: number
  
  /** 最大执行时间(毫秒) */
  maxExecutionTime: number
  
  /** 最后执行时间 */
  lastExecution: Date
  
  /** 最后成功时间 */
  lastSuccess: Date
  
  /** 最后失败时间 */
  lastFailure?: Date
  
  /** 错误统计 */
  errorStats: Record<ToolErrorCode, number>
  
  /** 资源使用统计 */
  resourceUsage: ResourceUsageStats
  
  /** 缓存统计 */
  cacheStats: ToolCacheStats
}

ResourceUsageStats

资源使用统计：

interface ResourceUsageStats {
  /** 总CPU时间(毫秒) */
  totalCpuTime: number
  
  /** 平均CPU时间(毫秒) */
  averageCpuTime: number
  
  /** 总内存使用量（字节） */
  totalMemoryUsage: number
  
  /** 平均内存使用量（字节） */
  averageMemoryUsage: number
  
  /** 总磁盘使用量（字节） */
  totalDiskUsage: number
  
  /** 总网络使用量（字节） */
  totalNetworkUsage: number
  
  /** API调用总数 */
  totalApiCalls: number
}

ToolCacheStats

工具缓存统计：

interface ToolCacheStats {
  /** 缓存命中次数 */
  hits: number
  
  /** 缓存未命中次数 */
  misses: number
  
  /** 缓存命中率 */
  hitRate: number
  
  /** 缓存大小 */
  size: number
  
  /** 缓存节省的执行时间(毫秒) */
  timeSaved: number
}

工具事件

ToolEvent

工具事件接口：

interface ToolEvent {
  /** 事件类型 */
  type: ToolEventType
  
  /** 工具名称 */
  toolName: string
  
  /** 执行ID */
  executionId?: string
  
  /** 事件数据 */
  data?: any
  
  /** 事件时间戳 */
  timestamp: Date
  
  /** 事件ID */
  id: string
  
  /** 用户ID */
  userId?: string
  
  /** 会话ID */
  sessionId?: string
}

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'
  | 'tool:validation:failed'

ToolEventListener

工具事件监听器：

type ToolEventListener = (event: ToolEvent) => void | Promise<void>

内置工具类型

FileSystemTool

文件系统工具：

interface FileSystemTool extends Tool {
  category: 'file-system'
  permissions: {
    required: ['file:read' | 'file:write' | 'file:delete']
  }
}

NetworkTool

网络工具：

interface NetworkTool extends Tool {
  category: 'network'
  permissions: {
    required: ['network:request']
  }
  config: {
    timeout: number
    retries: number
    userAgent?: string
  }
}

DatabaseTool

数据库工具：

interface DatabaseTool extends Tool {
  category: 'database'
  permissions: {
    required: ['database:read' | 'database:write']
  }
  config: {
    connectionString: string
    poolSize?: number
    timeout?: number
  }
}

---

这些类型定义为XAI-SDK的工具系统提供了完整的类型支持，确保工具开发和使用的类型安全性。