npm - @baiducloud/qianfan-ai-assistant - Versions diffs - 0.0.1 - Mend

@baiducloud/qianfan-ai-assistant 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (122) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,38 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/lang/zh-CN/).
+## [0.0.1] - 2026-03-26
+### Added
+#### 核心功能
+- **SSE 流式对话**：支持通过 `agentSpaceRun` 方法进行 SSE 流式对话
+- **文件上传**：支持通过 `uploadFile` 方法上传文件到服务器
+- **用户偏好设置**：支持通过 `getUserPreferences`、`saveUserPreferences` 方法读写用户偏好
+- **AI 能力集成**：集成通用问答、文档问答、深度研究、图像问答、PPT生成能力
+- **历史对话管理**：支持对话列表查询、消息拉取、标题更新、删除等完整历史对话管理
+- **语音转文本**：支持通过 `speechToText` 方法进行语音转文本处理
+#### SDK 集成
+- UMD 格式构建，支持通过 `<script>` 标签引入
+- 全局变量 `AIAssistantAgent` 挂载到 `window` 对象
+#### 接口定义
+- `IClientService` 接口：定义客户端服务需要实现的所有方法
+- `IFileUploadRes` 接口：文件上传响应类型
+- `IAbortRequestParams` 接口：取消请求参数类型
+- `IUserPreferencesData` 接口：用户偏好数据类型
+- `ISessionHistoryDataReq` 接口：历史对话消息拉取参数类型
+- `IHistoryChatItem` 接口：历史对话消息条目类型
+- `ISessionHistoryFilesRes` 接口：对话文件恢复拉取接口返回类型
+- `IUploadedFileInfo` 接口：已上传文件详情类型
+- `IConversationListReq` 接口：历史会话列表请求参数类型
+- `IConversationItem` 接口：会话列表元素类型
+- `IConversationStatus` 接口：会话状态条目类型

package/README.md ADDED Viewed

@@ -0,0 +1,143 @@
+# @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` 批量拉取文件元信息