npm package: @simple-ai-chat-project/core-sdk
Description: Lightweight core SDK for AI chat system (ESM)
Latest version: 1.0.1

# @simple-ai-chat-project/core-sdk

轻量级 AI 聊天系统核心 SDK - 框架无关的纯 JavaScript 实现

## 特性

- 🚀 **框架无关** - 纯 JavaScript 实现,可在任何前端框架中使用
- 📡 **SSE 流式响应** - 基于 `@microsoft/fetch-event-source` 的增强型流式传输
- 🎯 **类型安全的事件系统** - 基于 EventEmitter3 的强大事件管理
- 🔄 **自动重连** - 内置智能重连机制
- 💾 **状态管理** - 完整的客户端状态管理
- 🧪 **完整测试** - 单元测试覆盖率 > 80%
- 📦 **小巧轻便** - 打包后体积小,性能优异

## 安装

```bash
npm install @simple-ai-chat-project/core-sdk
# 或
pnpm add @simple-ai-chat-project/core-sdk
```

## 快速开始

```javascript
import { createChatClient } from '@simple-ai-chat-project/core-sdk';

// 创建客户端实例
const client = createChatClient({
  apiBaseUrl: 'http://localhost:8000',
  ai: {
    model: 'gpt-4',
    temperature: 0.7
  }
});

// 监听事件
client.on('stream:chunk', (data) => {
  console.log('接收到流式数据:', data.chunk);
});

client.on('message:new', (message) => {
  console.log('新消息:', message);
});

// 发送消息
await client.sendMessage({
  content: 'Hello, AI!',
  onStream: {
    onStart: () => console.log('流式响应开始'),
    onChunk: (data) => console.log('接收数据:', data.chunk),
    onComplete: (message) => console.log('响应完成:', message)
  }
});
```

## 核心 API

### 创建客户端

```javascript
const client = createChatClient({
  // 必填配置
  apiBaseUrl: 'http://localhost:8000',

  // 可选配置
  auth: {
    type: 'jwt', // 'jwt' | 'apikey' | 'none'
    getToken: async () => localStorage.getItem('token')
  },

  sse: {
    reconnect: true,
    reconnectInterval: 3000,
    maxReconnectAttempts: 5
  },

  ai: {
    model: 'gpt-4',
    temperature: 0.7,
    maxTokens: 2000,
    streamResponse: true
  },

  logger: {
    level: 'info' // 'debug' | 'info' | 'warn' | 'error'
  }
});
```

### 发送消息

```javascript
const message = await client.sendMessage({
  content: 'Hello, AI!',
  roomId: 'room-123', // 可选,不提供则创建新房间
  attachments: [], // 可选,附件数组

  // 流式响应回调
  onStream: {
    onStart: () => {},
    onChunk: (data) => {},
    onComplete: (message) => {},
    onError: (error) => {}
  },

  // AI 参数覆盖
  aiOptions: {
    temperature: 0.9
  }
});
```

### 房间管理

```javascript
// 创建房间
const room = await client.createRoom({
  name: '新对话',
  metadata: { category: 'support' }
});

// 获取房间列表
const rooms = await client.getRooms();

// 切换房间
await client.switchRoom('room-123');

// 删除房间
await client.deleteRoom('room-123');
```

### 消息管理

```javascript
// 获取房间消息
const messages = await client.getMessages('room-123', {
  page: 1,
  pageSize: 50
});
```

### 事件系统

```javascript
// 消息事件
client.on('message:new', (message) => {});
client.on('message:update', (message) => {});

// 流式响应事件
client.on('stream:start', ({ roomId, messageId }) => {});
client.on('stream:chunk', ({ chunk, accumulated }) => {});
client.on('stream:end', ({ fullMessage }) => {});
client.on('stream:abort', () => {});

// 房间事件
client.on('room:created', (room) => {});
client.on('room:switched', (room) => {});
client.on('room:deleted', (roomId) => {});

// 状态变化事件
client.on('state:change', (state) => {});

// 错误事件
client.on('error', (error) => {});

// 连接状态事件
client.on('connection:change', (status) => {});

// 移除监听
const unsubscribe = client.on('message:new', handler);
unsubscribe(); // 或 client.off('message:new', handler)
```

### 流式响应控制

```javascript
// 中止当前流式响应
client.abortStream();
```

### 工具方法

```javascript
// 健康检查
const health = await client.healthCheck();

// 获取当前状态
const state = client.getState();

// 清理资源
client.destroy();
```

## 数据模型

### Message

```javascript
{
  id: 'msg_xxx',
  roomId: 'room_xxx',
  content: '消息内容',
  role: 'user' | 'assistant' | 'system',
  metadata: {},
  createdAt: '2024-01-01T00:00:00.000Z',
  updatedAt: '2024-01-01T00:00:00.000Z',
  isStreaming: false,
  isComplete: true,
  attachments: [],
  references: []
}
```

### Room

```javascript
{
  id: 'room_xxx',
  name: '对话名称',
  metadata: {},
  createdAt: '2024-01-01T00:00:00.000Z',
  updatedAt: '2024-01-01T00:00:00.000Z',
  config: {
    model: 'gpt-4',
    temperature: 0.7,
    maxTokens: 2000,
    systemPrompt: null
  },
  messageCount: 0,
  lastMessageAt: null
}
```

## 架构设计

```
@simple-ai-chat/core-sdk/
├── src/
│   ├── api/
│   │   ├── SSEClient.js      # SSE 流式客户端
│   │   └── RestClient.js     # REST API 客户端
│   ├── core/
│   │   └── ChatClient.js     # 核心客户端类
│   ├── models/
│   │   ├── Message.js        # 消息模型
│   │   └── Room.js           # 房间模型
│   └── index.js              # 主入口
├── tests/                    # 测试文件
└── dist/                     # 构建输出
    ├── index.esm.js          # ESM 格式
    └── index.cjs             # CommonJS 格式
```

## 开发

```bash
# 安装依赖
npm install

# 运行测试
npm test

# 构建
npm run build

# 开发模式(监听测试)
npm run dev
```

## 测试

本项目使用 Vitest 进行测试,测试覆盖率 > 80%。

```bash
# 运行所有测试
npm test

# 开发模式(监听)
npm run dev

# 查看覆盖率
npm test -- --coverage
```

## 浏览器兼容性

- Chrome/Edge >= 90
- Firefox >= 88
- Safari >= 14
- 支持 ES2022+ 特性

## 依赖

- `eventemitter3` - 事件系统
- `@microsoft/fetch-event-source` - SSE 流式传输

## 许可证

MIT

## 相关项目

- `@simple-ai-chat-project/vue-ui` - Vue 3 UI 组件包
- `@simple-ai-chat-project/web-component` - Web Component 封装

## 更新日志

### v1.0.1 (2024-10-29)

- ✅ 实现 SSE 客户端
- ✅ 实现核心 ChatClient 类
- ✅ 实现数据模型 (Message, Room)
- ✅ 实现事件系统
- ✅ 实现流式响应控制
- ✅ 完成单元测试 (27 tests passed)
- ✅ 完成构建配置

## 贡献

欢迎提交 Issue 和 Pull Request!

## 支持

如有问题,请访问 [GitHub Issues](https://github.com/yourusername/ai-chat-system/issues)