# @baiducloud/qianfan-ai-assistant

AI 助手 SDK —— 基于千帆应用开发工作台 agent-space 模块的第三方集成 SDK，提供 UMD 格式的对话能力封装。

## 安装

```bash
npm install @baiducloud/qianfan-ai-assistant
```

## 快速开始

### UMD 方式引入

通过 `<script>` 标签直接引入 SDK，适合在浏览器环境中快速集成：

```html
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>AI 助手</title>
        <style>
            #app {
                width: 100%;
                height: 100vh;
            }
        </style>
    </head>
    <body>
        <div id="app"></div>
        <script src="path/to/ai-assistant-sdk/dist/index.js"></script>
        <script>
            const clientService = {
                // 实现 IClientService 接口（见下方说明）
            };

            AIAssistantAgent.init(document.getElementById('app'), clientService);
        </script>
    </body>
</html>
```

## IClientService 接口说明

使用 SDK 前，需要实现 `IClientService` 接口，该接口定义了 SDK 与后端服务的通信方式。

### 核心方法

| 方法                  | 说明                   | 返回类型                           |
| --------------------- | ---------------------- | ---------------------------------- |
| `agentSpaceRun`       | SSE 对话流式接口       | `void`                             |
| `recoverChat`         | SSE 恢复对话接口       | `void`                             |
| `createConversation`  | 创建对话               | `Promise<string>`                  |
| `uploadFile`          | 文件上传               | `Promise<IFileUploadRes>`          |
| `getUserPreferences`  | 获取用户偏好           | `Promise<IUserPreferencesData>`    |
| `saveUserPreferences` | 保存用户偏好           | `Promise<void>`                    |
| `getUploadFileInfo`   | 批量查询已上传文件信息 | `Promise<ISessionHistoryFilesRes>` |
| `sendAbortRequest`    | 取消正在进行的请求     | `Promise<any>`                     |
| `speechToText`        | 语音识别（ASR）        | `Promise<string>`                  |

### 历史记录方法

| 方法                   | 说明                 | 返回类型                                                  |
| ---------------------- | -------------------- | --------------------------------------------------------- |
| `fetchHistoryChatList` | 获取历史记录总列表   | `Promise<{data: IConversationItem[]; has_more: boolean}>` |
| `fetchChatHistory`     | 获取历史对话消息列表 | `Promise<IHistoryChatItem[]>`                             |
| `fetchChatStatus`      | 批量获取会话状态     | `Promise<{data: IConversationStatus[]}>`                  |
| `updateChatTitle`      | 更新会话标题         | `Promise<{success: boolean}>`                             |
| `deleteHistoryChat`    | 删除历史对话         | `Promise<{success: boolean; deleted_count: number}>`      |

### SSE 接口签名

`agentSpaceRun` 和 `recoverChat` 方法的签名：

```typescript
(
    param: any,
    callbacks: {
        onMessage: (message: string) => void;
        onCompleted: () => void;
        onError: (error: Error) => void;
    },
    options?: {
        abortController?: AbortController;
        headers?: HeadersInit;
    }
) => void
```

## 开发调试

### 本地开发

```bash
# 进入 SDK 目录
cd packages/sdk/ai-assistant-sdk

# 启动开发服务（端口 9005）
npm run dev
```

### 构建 UMD 产物

```bash
npm run build:umd
```

### 测试构建产物

```bash
# 先构建
npm run build:umd

# 启动 dist 测试服务（端口 9006）
npm run dev:dist-test
```

## 类型声明

SDK 提供完整的 TypeScript 类型声明文件（`dist/index.d.ts`），包含：

- `IClientService` - 客户端服务接口
- `IFileUploadRes` - 文件上传响应
- `IAbortRequestParams` - 取消请求参数
- `IUserPreferencesData` - 用户偏好数据
- `ISessionHistoryDataReq` - 历史消息请求参数
- `IHistoryChatItem` - 历史消息条目
- `IUploadedFileInfo` - 已上传文件详情
- `ISessionHistoryFilesRes` - 批量文件查询返回
- `IConversationListReq` - 会话列表请求参数
- `IConversationItem` - 会话列表元素
- `IConversationStatus` - 会话状态条目
- `init` - SDK 初始化函数

## 注意事项

1. SDK 以 UMD 格式打包，所有依赖（React、MobX 等）均内置
2. 全局变量名为 `AIAssistantAgent`
3. 初始化函数 `init` 为异步函数，内部会完成国际化等初始化工作
4. `IClientService` 中的 SSE 方法需要用户自行处理流式响应的解析
5. `speechToText` 方法接收 `Blob` 类型的音频数据，非 `File`
6. `getUploadFileInfo` 需要在历史消息恢复时，根据 `attachments` 中的 `fileIds` 批量拉取文件元信息
