XAi Web SDK

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

安装

npm install @ai-group/chat-sdk

使用方法

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

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();

方式二：兼容写法

// 使用静态方法（不推荐，但保持兼容）
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);
  },
});

方式三：直接指定容器

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：

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

<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 对象

示例：

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 调用错误 |