npm package: @t-agent/sdk
Description: TA Core SDK - 提供 SSE 连接管理和实时通信功能
Author: TA Core Team
Latest version: 1.3.27

# @t-agent/sdk

TA Core SDK 提供 SSE (Server-Sent Events) 连接管理和实时通信功能。

## 特性

- 🔄 **SSE 连接管理** - 自动管理 SSE 连接生命周期
- 🛡️ **连接保护** - 防止多重连接，自动关闭之前的连接
- ⏱️ **超时处理** - 内置连接超时机制 (150秒)
- 🔁 **错误重试** - 完整的错误处理和重连机制
- 📨 **消息分发** - 基于消息类型的智能分发
- 🎯 **类型安全** - 完整的 TypeScript 类型定义

## 安装

```bash
# 使用 pnpm
pnpm add @t-agent/sdk

# 使用 npm
npm install @t-agent/sdk

# 使用 yarn
yarn add @t-agent/sdk
```

## 快速开始

### 1. 初始化 SDK

```typescript
import { initSDK } from '@t-agent/sdk';

// 初始化配置
initSDK({
  baseUrl: 'https://api.example.com',
  accessToken: 'your-access-token', // 可选
});
```

### 2. 订阅 SSE 连接

```typescript
import { sseSubscribe } from '@t-agent/sdk';
import type { SSECallbacks, SessionRunStreamRequest } from '@t-agent/sdk';

// 定义回调函数
const callbacks: SSECallbacks = {
  onMessage: message => {
    console.log('收到消息:', message);
  },
  onChatMessage: (content, message) => {
    console.log('聊天消息:', content);
  },
  onProcessMessage: (content, message) => {
    console.log('处理消息:', content);
  },
  onMaterialMessage: (content, message) => {
    console.log('材料消息:', content);
  },
  onAggregate: (content, message) => {
    console.log('聚合消息:', content);
  },
  onEnd: () => {
    console.log('连接结束');
  },
  onError: () => {
    console.error('连接错误');
  },
  onTimeout: () => {
    console.warn('连接超时');
  },
};

// 请求数据
const requestData: SessionRunStreamRequest = {
  sessionId: 123,
  userInput: 'Hello, world!',
  metadata: {
    attachments: [],
  },
};

// 订阅连接
sseSubscribe({
  url: '/api/stream',
  data: requestData,
  callbacks,
  options: {
    method: 'POST',
    headers: {
      'Custom-Header': 'value',
    },
  },
});
```

### 3. 管理连接

```typescript
import {
  closeSSEConnection,
  isSSEConnectionActive,
  destroySSEManager,
} from '@t-agent/sdk';

// 检查连接状态
if (isSSEConnectionActive()) {
  console.log('连接活跃');
}

// 关闭当前连接
closeSSEConnection();

// 销毁管理器（清理所有资源）
destroySSEManager();
```

## API 参考

### 配置函数

#### `initSDK(config)`

初始化 SDK 配置。

```typescript
initSDK({
  baseUrl: string;        // 基础 URL
  accessToken?: string;   // 访问令牌（可选）
});
```

#### `setBaseUrl(url)` / `getBaseUrl()`

设置/获取基础 URL。

#### `setAccessToken(token)` / `getAccessToken()`

设置/获取访问令牌。

### SSE 连接函数

#### `sseSubscribe(options)`

订阅 SSE 连接。

```typescript
sseSubscribe({
  url: string;                    // SSE 端点 URL
  data: SessionRunStreamRequest;  // 请求数据
  callbacks: SSECallbacks;        // 回调函数
  options?: SSEOptions;           // 可选配置
});
```

#### `closeSSEConnection()`

关闭当前 SSE 连接。

#### `isSSEConnectionActive()`

检查是否有活跃的 SSE 连接。

#### `destroySSEManager()`

销毁 SSE 管理器，清理所有资源。

### 类型定义

#### `SessionRunStreamRequest`

```typescript
interface SessionRunStreamRequest {
  sessionId: number;
  resumeOffset?: boolean;
  userInput?: string;
  metadata?: {
    attachments?: Attachment[];
    referenceMaterialId?: number;
  };
}
```

#### `SSECallbacks`

```typescript
interface SSECallbacks {
  onMessage: (message: SessionMessage) => void;
  onChatMessage: (content: string, message: ChatMessage) => void;
  onProcessMessage: (content: ProcessContent, message: ProcessMessage) => void;
  onMaterialMessage: (content: string, message: MaterialMessage) => void;
  onAggregate: (content: string, message: AggregateMessage) => void;
  onStartResponse?: (response: EventSourceMessage) => void;
  onEnd?: () => void;
  onError?: () => void;
  onTimeout?: () => void;
}
```

#### `SSEOptions`

```typescript
interface SSEOptions {
  method?: 'GET' | 'POST';
  headers?: Record<string, unknown>;
}
```

## 消息类型

SDK 支持以下消息类型：

- `process` - 处理过程消息
- `chat_input` - 聊天输入消息
- `chat_output` - 聊天输出消息
- `material` - 材料消息
- `aggregate` - 聚合消息
- `other` - 其他类型消息

## 最佳实践

### 1. 错误处理

```typescript
const callbacks: SSECallbacks = {
  // ... 其他回调
  onError: () => {
    console.error('SSE 连接错误，尝试重连...');
    // 实现重连逻辑
  },
  onTimeout: () => {
    console.warn('SSE 连接超时，请检查网络');
    // 处理超时情况
  },
};
```

### 2. 连接管理

```typescript
// 在组件卸载时清理连接
useEffect(() => {
  return () => {
    destroySSEManager();
  };
}, []);
```

### 3. 多连接处理

SDK 自动处理多连接情况，新的连接会自动关闭之前的连接。

## 许可证

MIT

## 贡献

欢迎提交 Issue 和 Pull Request！