# XAi Web SDK

一个用于集成 AI 聊天机器人的 Web SDK。

## 安装

```bash
npm install @ai-group/chat-sdk
```

## 使用方法

### 方式一：推荐写法（Coze 风格）

```javascript
import XAiWebSDK from "@ai-group/chat-sdk";

// 创建 SDK 实例 - 类似 Coze 的写法
const chatbot = new XAiWebSDK.initChatbot({
  url: "https://your-api-server.com",
  token: "your-token",
  config: {
    appNo: "your-app-no",
  },
  componentProps: {
    id: "chatbot-container",
    width: "400px",
    height: "600px",
  },
  onError: (error) => {
    console.error("Chatbot init error:", error);
  },
  onSuccess: (appInfo) => {
    console.log("Chatbot init success:", appInfo);
  },
});

// 销毁实例
chatbot.unmount();
```

### 方式二：兼容写法

```javascript
// 使用静态方法（不推荐，但保持兼容）
const chatbot = XAiWebSDK.create({
  url: "https://your-api-server.com",
  token: "your-token",
  config: {
    appNo: "your-app-no",
  },
  componentProps: {
    id: "chatbot-container",
  },
  onError: (error) => {
    console.error("Chatbot init error:", error);
  },
  onSuccess: (appInfo) => {
    console.log("Chatbot init success:", appInfo);
  },
});
```

### 方式三：直接指定容器

```javascript
const container = document.getElementById("my-chatbot");
const chatbot = new XAiWebSDK(container, {
  url: "https://your-api-server.com",
  token: "your-token",
  config: {
    appNo: "your-app-no",
  },
  onError: (error) => {
    console.error("Chatbot init error:", error);
  },
  onSuccess: (appInfo) => {
    console.log("Chatbot init success:", appInfo);
  },
});
```

## API 参数

### XAiSDKProps

| 参数           | 类型     | 必填 | 说明                              |
| -------------- | -------- | ---- | --------------------------------- |
| url            | string   | 是   | AI 服务地址                       |
| token          | string   | 是   | 认证 token                        |
| config         | object   | 是   | 配置信息，包含 appNo 等           |
| componentProps | object   | 否   | 容器属性，支持 id 和任意 CSS 样式 |
| onError        | function | 否   | 错误回调函数                      |
| onSuccess      | function | 否   | 成功回调函数                      |

### config 配置项

| 参数                    | 类型     | 必填 | 说明                             |
| ----------------------- | -------- | ---- | -------------------------------- |
| appNo                   | string   | 是   | 应用编号                         |
| allowUpload             | boolean  | 否   | 是否允许上传文件，默认 false     |
| session.showSessionList | boolean  | 否   | 是否显示会话列表，默认 false     |
| showFeedback            | boolean  | 否   | 是否显示点赞/点踩按钮，默认 true |
| onFileClick             | function | 否   | 点击附件卡片的回调函数           |
| uploadRequest           | function | 否   | 自定义文件上传函数；不传时 xgroup-adk 预设使用默认上传接口 |

### Preset / Strategies

`XAdkProvider` 和 UMD 入口默认启用 `xgroup-adk` preset，用于保留众安信科 ADK 协议体验：确认工具、任务转交、注释模式思维链、默认确认响应和默认附件上传都会自动生效。

如果需要接入其他协议或覆盖局部行为，可以使用 `preset` / `strategies`：

```tsx
<XAdkProvider preset="base" chatData={customChatData}>
  <XAdkProvider.DefaultLayout />
</XAdkProvider>
```

新增企业预设时，可从中立入口组合基础能力，通用组件不会直接依赖 `presets/xgroup`：

```tsx
import {
  basePreset,
  composeChatPresets,
  defineChatPreset,
} from '@ai-group/chat-sdk/presets';

const yGroupPreset = composeChatPresets(
  basePreset,
  defineChatPreset({
    name: 'ygroup-adk',
    strategies: yGroupStrategies,
  }),
);

<XAdkProvider token="" preset={yGroupPreset} chatData={customChatData}>
  <XAdkProvider.DefaultLayout />
</XAdkProvider>;
```

```tsx
<XAdkProvider
  token="your-token"
  config={{ appNo: "your-app-no" }}
  strategies={{
    resolveToolKind: ({ name }) =>
      name === "my_approval_tool" ? "approval" : "default",
  }}
>
  <XAdkProvider.DefaultLayout />
</XAdkProvider>
```

### 回调函数

#### onError(error)

- `error.code`: 错误代码
- `error.message`: 错误信息

#### onSuccess(appInfo)

- `appInfo`: 应用信息对象，包含应用配置等

#### onFileClick(file)

点击对话中的附件卡片时触发（非图片、非音视频文件）。

- `file`: 文件信息对象
  - `fileName`: 文件名
  - `fileId`: 文件ID
  - `tempUrl`: 文件临时URL
  - `mimeType`: 文件MIME类型
  - `fileSize`: 文件大小

#### uploadRequest(options)

自定义文件上传函数，用于覆盖 xgroup-adk 预设的默认上传行为。普通众安信科 ADK 接入只需要配置 `allowUpload: true`，无需手写 `uploadRequest`。

- `options.file`: 要上传的 File 对象
- `options.onProgress`: 进度回调，参数 `{ percent: number }`
- `options.onSuccess`: 上传成功回调，参数类型为 `UploadFileResult | UploadFileResult[] | { data: UploadFileResult | UploadFileResult[] }`
- `options.onError`: 上传失败回调，参数为 Error 对象

**示例：**

```javascript
const chatbot = new XAiWebSDK.initChatbot({
  token: "your-token",
  config: {
    appNo: "your-app-no",
    allowUpload: true,
    // 自定义上传
    uploadRequest: async ({ file, onProgress, onSuccess, onError }) => {
      try {
        const formData = new FormData();
        formData.append("file", file);
        const response = await fetch("/api/upload", {
          method: "POST",
          body: formData,
        });
        const data = await response.json();
        onSuccess({
          fileName: data.fileName,
          fileId: data.fileId,
          tempUrl: data.fileUrl,
          fileType: data.fileType,
          fileSize: data.fileSize,
          mimeType: data.mimeType,
        });
      } catch (error) {
        onError(error);
      }
    },
    // 文件预览回调
    onFileClick: (file) => {
      console.log("点击文件:", file);
      // 可以在此处触发文件预览弹窗
    },
  },
});
```

## 错误代码

| 代码           | 说明         |
| -------------- | ------------ |
| APP_NOT_ENABLE | 应用未启用   |
| APP_DELETED    | 应用已下架   |
| APP_NOT_FOUND  | 应用未找到   |
| API_ERROR      | API 调用错误 |