XAI-SDK

Appearance

使用指南 ​

概述 ​

XAI-SDK 是一个跨平台的AI编程助手SDK，支持CLI环境和浏览器环境（React、Vue、原生JS），提供完整的代码分析和操作能力。

特性 ​

  • 🌐 跨平台支持: CLI环境 + 浏览器环境
  • 🔧 多框架适配: React、Vue、原生JavaScript
  • 🧩 插件化架构: 支持自定义工具和AI提供商
  • 📝 TypeScript支持: 完整的类型定义
  • 🛠️ 丰富的工具集: 文件系统、搜索、上下文管理等
  • 🔒 安全可靠: 内置错误处理和日志系统

安装 ​

bash
npm install xai-sdk
bash
yarn add xai-sdk
bash
pnpm add xai-sdk

基础用法 ​

CLI 环境 ​

typescript
import { XAI_SDK } from 'xai-sdk';

// 初始化SDK
const sdk = new XAI_SDK({
  environment: 'cli',
  config: {
    apiKey: 'your-api-key',
    model: 'gpt-4',
    baseURL: 'https://api.openai.com/v1',
  },
});

// 初始化
await sdk.initialize();

// 使用AI功能
const response = await sdk.chat({
  messages: [
    {
      role: 'user',
      content: '请帮我分析这个函数的复杂度',
    },
  ],
  tools: ['filesystem', 'search'],
});

console.log(response.content);

浏览器环境 ​

typescript
import { XAI_SDK } from 'xai-sdk';

// 浏览器环境初始化
const sdk = new XAI_SDK({
  environment: 'browser',
  config: {
    apiKey: 'your-api-key',
    model: 'gpt-4',
  },
});

// 初始化
await sdk.initialize();

// 上传文件并分析
const fileContent = await sdk.filesystem.readFile('example.ts');
const analysis = await sdk.analyze(fileContent);

框架集成 ​

React 集成 ​

typescript
import { useXAISDK } from 'xai-sdk/react';

function CodeAnalyzer() {
  const { sdk, isLoading, error } = useXAISDK({
    apiKey: 'your-api-key',
    model: 'gpt-4'
  });

  const analyzeCode = async (code: string) => {
    if (!sdk) return;

    const result = await sdk.analyze(code);
    console.log(result);
  };

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <button onClick={() => analyzeCode('const x = 1;')}>
        分析代码
      </button>
    </div>
  );
}

Vue 集成 ​

vue
<template>
  <div>
    <button @click="analyzeCode" :disabled="isLoading">
      {{ isLoading ? '分析中...' : '分析代码' }}
    </button>
    <div v-if="error" class="error">{{ error.message }}</div>
  </div>
</template>

<script setup lang="ts">
import { useXAISDK } from 'xai-sdk/vue';

const { sdk, isLoading, error } = useXAISDK({
  apiKey: 'your-api-key',
  model: 'gpt-4',
});

const analyzeCode = async () => {
  if (!sdk.value) return;

  const result = await sdk.value.analyze('const x = 1;');
  console.log(result);
};
</script>

配置选项 ​

SDKConfig ​

typescript
interface SDKConfig {
  // AI 提供商配置
  apiKey: string;
  model: string;
  baseURL?: string;

  // 环境配置
  environment: 'cli' | 'browser';

  // 工具配置
  tools?: ToolConfig[];

  // 日志配置
  logging?: {
    level: 'debug' | 'info' | 'warn' | 'error';
    output?: 'console' | 'file';
  };

  // 插件配置
  plugins?: PluginConfig[];
}

环境特定配置 ​

CLI 环境 ​

typescript
const sdk = new XAI_SDK({
  environment: 'cli',
  config: {
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4',
    // CLI 特定配置
    workingDirectory: process.cwd(),
    configFile: '.xai/settings.json',
  },
});

浏览器环境 ​

typescript
const sdk = new XAI_SDK({
  environment: 'browser',
  config: {
    apiKey: 'your-api-key',
    model: 'gpt-4',
    // 浏览器特定配置
    corsProxy: 'https://your-cors-proxy.com',
    maxFileSize: 10 * 1024 * 1024, // 10MB
  },
});

核心功能 ​

1. 代码分析 ​

typescript
// 分析单个文件
const analysis = await sdk.analyze(code, {
  type: 'complexity' | 'security' | 'performance',
  language: 'typescript',
});

// 分析整个项目
const projectAnalysis = await sdk.analyzeProject({
  path: './src',
  exclude: ['node_modules', 'dist'],
});

2. 代码生成 ​

typescript
// 生成代码
const generatedCode = await sdk.generate({
  prompt: '创建一个React组件用于显示用户列表',
  language: 'typescript',
  framework: 'react',
});

// 代码重构
const refactoredCode = await sdk.refactor(originalCode, {
  type: 'extract-function',
  target: 'selectedLines',
});

3. 文件系统操作 ​

typescript
// 读取文件
const content = await sdk.filesystem.readFile('src/index.ts');

// 写入文件
await sdk.filesystem.writeFile('output.ts', generatedCode);

// 搜索文件
const files = await sdk.filesystem.search({
  pattern: '*.ts',
  exclude: ['node_modules'],
});

4. 上下文管理 ​

typescript
// 添加上下文
sdk.context.add({
  type: 'file',
  content: fileContent,
  metadata: { path: 'src/utils.ts' },
});

// 搜索相关上下文
const relevantContext = await sdk.context.search({
  query: 'authentication logic',
  limit: 5,
});

工具系统 ​

内置工具 ​

  • filesystem: 文件系统操作
  • search: 代码搜索和索引
  • context: 上下文管理
  • git: Git 操作（CLI环境）
  • terminal: 终端命令执行（CLI环境）

使用工具 ​

typescript
// 在对话中使用工具
const response = await sdk.chat({
  messages: [
    {
      role: 'user',
      content: '请找到所有包含TODO注释的文件',
    },
  ],
  tools: ['filesystem', 'search'],
});

// 直接调用工具
const searchResults = await sdk.tools.search.execute({
  query: 'TODO',
  fileTypes: ['.ts', '.js'],
});

事件系统 ​

typescript
// 监听SDK事件
sdk.on('initialized', () => {
  console.log('SDK已初始化');
});

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

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

// 监听聊天事件
sdk.on('chat:start', () => {
  console.log('开始对话');
});

sdk.on('chat:stream', chunk => {
  console.log('接收到流式数据:', chunk);
});

sdk.on('chat:complete', response => {
  console.log('对话完成:', response);
});

错误处理 ​

typescript
try {
  const result = await sdk.analyze(code);
} catch (error) {
  if (error instanceof SDKError) {
    switch (error.code) {
      case 'INVALID_API_KEY':
        console.error('API密钥无效');
        break;
      case 'RATE_LIMIT_EXCEEDED':
        console.error('请求频率超限');
        break;
      case 'NETWORK_ERROR':
        console.error('网络连接错误');
        break;
      default:
        console.error('未知错误:', error.message);
    }
  }
}

最佳实践 ​

1. 配置管理 ​

typescript
// 使用环境变量
const config = {
  apiKey: process.env.XAI_API_KEY || '',
  model: process.env.XAI_MODEL || 'gpt-4',
  baseURL: process.env.XAI_BASE_URL,
};

// 配置验证
if (!config.apiKey) {
  throw new Error('API密钥未配置');
}

2. 错误处理 ​

typescript
// 全局错误处理
sdk.on('error', error => {
  // 记录错误日志
  console.error('SDK Error:', error);

  // 发送错误报告
  if (error.code === 'CRITICAL_ERROR') {
    reportError(error);
  }
});

3. 性能优化 ​

typescript
// 使用缓存
const cachedAnalysis = await sdk.analyze(code, {
  cache: true,
  cacheKey: 'analysis-' + hashCode(code),
});

// 批量操作
const results = await sdk.batch([
  { type: 'analyze', data: code1 },
  { type: 'analyze', data: code2 },
  { type: 'generate', data: prompt },
]);

4. 内存管理 ​

typescript
// 清理资源
sdk.on('beforeDestroy', () => {
  // 清理缓存
  sdk.cache.clear();

  // 取消未完成的请求
  sdk.cancelPendingRequests();
});

// 销毁SDK实例
await sdk.destroy();

调试和日志 ​

typescript
// 启用调试模式
const sdk = new XAI_SDK({
  config: {
    logging: {
      level: 'debug',
      output: 'console',
    },
  },
});

// 自定义日志处理
sdk.logger.on('log', entry => {
  if (entry.level === 'error') {
    // 发送错误到监控系统
    sendToMonitoring(entry);
  }
});

常见问题 ​

Q: 如何在不同环境中使用不同的配置？ ​

A: 使用环境变量或配置文件：

typescript
const config = {
  development: {
    apiKey: 'dev-key',
    baseURL: 'https://dev-api.example.com',
  },
  production: {
    apiKey: process.env.PROD_API_KEY,
    baseURL: 'https://api.example.com',
  },
};

const sdk = new XAI_SDK({
  config: config[process.env.NODE_ENV || 'development'],
});

Q: 如何处理大文件分析？ ​

A: 使用流式处理和分块分析：

typescript
// 分块分析大文件
const chunks = await sdk.filesystem.readFileInChunks('large-file.ts', {
  chunkSize: 1024 * 1024, // 1MB chunks
});

for (const chunk of chunks) {
  const analysis = await sdk.analyze(chunk.content);
  // 处理分析结果
}

Q: 如何自定义工具？ ​

A: 参考插件开发指南创建自定义工具。

更多资源 ​

支持 ​

如果您遇到问题或有建议，请：

  1. 查看常见问题
  2. 搜索GitHub Issues
  3. 创建新的Issue或讨论
  4. 联系技术支持：support@xai-sdk.com

许可证 ​

MIT License - 详见 LICENSE 文件。

Released under the MIT License.

Copyright © 2024 AI-SDK Team