AIOS Chat SDK

AIOS Chat SDK 用于在网站或 Web 应用中集成 AIOS 已发布的低代码智能体与低代码应用会话流。SDK 支持悬浮聊天、嵌入式聊天、同源 iframe 渲染、流式回复、会话续聊、令牌预校验、令牌刷新和附件发送。

SDK 的初始化与 UI 配置形式参考 Chat SDK 的通用接入方式：通过 WebChatClient 创建客户端，使用 config 配置调用目标，使用 auth 传递访问令牌，使用 userInfo 标识访客，并通过 ui 或 componentProps 定制界面。

前置条件

浏览器兼容性

SDK 依赖 fetch、ReadableStream、TextDecoder 和 ES Modules。建议使用以下或更高版本的浏览器：

| 浏览器 | 建议版本 | | --- | --- | | Chrome | 87+ | | Edge | 88+ | | Safari | 14+ | | Firefox | 78+ |

获取访问令牌

访问令牌用于 SDK 的身份认证。开发调试可使用个人访问令牌；生产环境应由接入方服务端安全地签发、托管和刷新短期令牌。

不要将管理员令牌、长期密钥或真实用户身份直接写入前端代码仓库。

发布调用目标

创建客户端前，请确认以下目标已发布且当前访问令牌具有调用权限：

• 低代码智能体：需要智能体 ID。
• 低代码应用会话流：需要应用 ID 和会话流 ID。

智能体还必须提供稳定的匿名访客 ID，用于隔离不同访客的会话历史和长期记忆。不要直接使用业务系统中的真实用户 ID。

配置流程

步骤一：引入 SDK

将 SDK 脚本添加到页面中。发布 npm 包后可通过 CDN 引入：

<script src="https://unpkg.com/@kmlckj/[email protected]/dist/aios-chat-sdk.js"></script>

脚本加载后，可从全局对象 AIOSChatSDK 获取 WebChatClient。

使用构建工具时，也可以按 ESM 方式导入：

import { WebChatClient } from "@kmlckj/licos-chat-sdk";

步骤二：初始化智能体聊天

以下示例创建一个右下角悬浮聊天窗口。apiBaseUrl 为 AIOS 服务的绝对地址，botId 为已发布智能体 ID。

<script src="https://unpkg.com/@kmlckj/[email protected]/dist/aios-chat-sdk.js"></script>
<script>
  const chatClient = new AIOSChatSDK.WebChatClient({
    config: {
      type: "bot",
      apiBaseUrl: "https://aios.example.com/low-code",
      botId: "<BOT_ID>",
      isIframe: false,
      publishStatus: "published_online",
    },
    auth: {
      type: "token",
      token: "<ACCESS_TOKEN>",
      onRefreshToken: async () => {
        return "<NEW_ACCESS_TOKEN>";
      },
    },
    userInfo: {
      id: "visitor_001",
      nickname: "访客",
    },
    ui: {
      chatBot: {
        title: "AIOS 智能助手",
        uploadable: true,
      },
    },
  });
</script>

步骤三：初始化低代码应用会话流

嵌入模式需要先准备一个容器，通过 componentProps.container 或 ui.chatBot.el 指向该容器。

<div id="aios-chat" style="height: 620px"></div>

<script src="https://unpkg.com/@kmlckj/[email protected]/dist/aios-chat-sdk.js"></script>
<script>
  const chatClient = new AIOSChatSDK.WebChatClient({
    config: {
      type: "app",
      apiBaseUrl: "https://aios.example.com/low-code",
      appInfo: {
        appId: "<APP_ID>",
        workflowId: "<CHATFLOW_ID>",
      },
      workspaceId: "<WORKSPACE_ID>",
      parameters: {
        locale: "zh-CN",
      },
    },
    auth: {
      type: "token",
      token: "<ACCESS_TOKEN>",
    },
    componentProps: {
      layout: "embedded",
      container: "#aios-chat",
      height: 620,
    },
    ui: {
      chatBot: {
        title: "在线助手",
        isNeedAddNewConversation: true,
      },
    },
  });
</script>

SDK 会保存服务端返回的会话 ID，后续消息会自动继续当前会话。

步骤四：销毁客户端

页面卸载、路由切换或不再使用聊天窗口时，调用 destroy() 清理 SDK 创建的 DOM 和事件监听。

chatClient.destroy();

初始化配置

config：调用目标

| 参数 | 是否必填 | 类型 | 说明 | | --- | --- | --- | --- | | type | 否 | "bot" \| "app" | 调用目标类型。传入 botId 时默认识别为 bot，否则为 app。 | | apiBaseUrl | 是 | string | AIOS 服务绝对地址，例如 https://aios.example.com/low-code。不能携带 query 或 hash。 | | isIframe | 否 | boolean | 是否在同源 iframe 中渲染聊天窗口，默认 false。false（推荐）直接集成到当前页面；true 可隔离聊天窗口的 DOM 与样式。 | | botId | 智能体必填 | string | 已发布智能体 ID。兼容 bot_id。 | | appInfo.appId | 应用必填 | string | 已发布低代码应用 ID。兼容 app_id。 | | appInfo.workflowId | 应用必填 | string | 已发布会话流 ID。兼容 workflow_id。 | | inputKey | 否 | string | 会话流入口中承接当前用户消息的参数名，默认 input。入口字段不是 input 时填写实际字段名。 | | requestTimeout | 否 | number | 单次会话请求的最长等待时间（毫秒），默认 60000。超时或服务端返回失败事件时，SDK 会在聊天框中展示错误。 | | workspaceId | 否 | string | 工作空间 ID。服务需要工作空间上下文时填写。 | | connectorId | 否 | string | 发布渠道 ID。 | | publishStatus | 否 | string | 智能体版本：published_online（默认）或 unpublished_draft。 | | parameters | 否 | Record<string, unknown> | 每条消息都会附带的业务参数。发送消息时的同名参数会覆盖它。 | | botInfo.parameters | 否 | Record<string, unknown> | 智能体的初始业务参数，会与 parameters 合并。 |

isIframe: true 只隔离 SDK 的展示 DOM；会话请求仍由浏览器以相同的 apiBaseUrl、令牌和访客信息发起。

auth：鉴权信息

| 参数 | 是否必填 | 类型 | 说明 | | --- | --- | --- | --- | | type | 否 | "token" \| "unauth" | 鉴权类型。传入 token 时默认使用 token。 | | token | Token 模式建议填写 | string | 访问令牌。 | | validationUrl | 否 | string | 自定义令牌校验地址。通常不需要填写，SDK 会根据 apiBaseUrl 自动定位对应的 AIOS 平台。 | | onRefreshToken | 否 | () => string \| Promise<string> | 返回新令牌。收到未授权响应后，SDK 会调用一次并重试当前请求。 |

userInfo：访客信息

智能体聊天必须传入 userInfo.id。

| 参数 | 是否必填 | 类型 | 说明 | | --- | --- | --- | --- | | id | 智能体必填 | string | 接入方定义的稳定匿名访客 ID。兼容 userId、user_id。 | | name / nickname | 否 | string | 访客显示名。 | | avatar / url | 否 | string | 访客头像 URL。 | | metadata | 否 | Record<string, unknown> | 接入方扩展信息。 |

自定义聊天界面与交互

SDK 提供两套 UI 配置：

• componentProps：AIOS 原生配置，适合直接控制布局与样式。
• ui：兼容常见 Chat SDK 的分组配置方式，适合按基础样式、标题栏和聊天框功能分组管理。

当同一能力同时在两处配置时，componentProps 优先。

基础 UI 配置

| 参数 | 类型 | 说明 | | --- | --- | --- | | ui.base.icon | string | 聊天窗口标题栏图标 URL。 | | ui.base.zIndex | number | 悬浮聊天窗口的层级。 | | ui.asstBtn.isNeed | boolean | 是否展示悬浮球，默认 true。 | | ui.header.isShow | boolean | 是否展示标题栏，默认 true。 | | ui.header.isNeedClose | boolean | 悬浮窗口是否展示关闭按钮，默认 true。 | | ui.footer.isShow | boolean | 是否显示底部提示，默认 true。 | | ui.footer.expressionText | string | 底部提示文案。 |

const chatClient = new WebChatClient({
  // config、auth、userInfo 省略
  ui: {
    base: {
      icon: "https://static.example.com/assistant.png",
      zIndex: 1200,
    },
    asstBtn: { isNeed: true },
    header: { isShow: true, isNeedClose: true },
    footer: {
      isShow: true,
      expressionText: "内容由 AI 生成，请注意甄别。",
    },
  },
});

聊天框与生命周期

| 参数 | 类型 | 说明 | | --- | --- | --- | | ui.chatBot.title | string | 聊天窗口标题。 | | ui.chatBot.width / height | string \| number | 悬浮聊天窗口的宽高。 | | ui.chatBot.el | string \| HTMLElement | 嵌入式聊天的容器。传入时默认采用嵌入布局。 | | ui.chatBot.uploadable | boolean | 是否显示附件按钮，默认 true。仍需同时提供 fileUploader。 | | ui.chatBot.isNeedAddNewConversation | boolean | 是否在标题栏展示“新建会话”按钮。 | | ui.chatBot.onShow / onHide | function | 聊天窗口显示、隐藏后触发。 | | ui.chatBot.onBeforeShow / onBeforeHide | function | 显示、隐藏前触发。返回或 resolve 为 false 时取消本次操作。 |

const chatClient = new WebChatClient({
  // config、auth、userInfo 省略
  ui: {
    chatBot: {
      title: "售后助手",
      width: 420,
      uploadable: true,
      isNeedAddNewConversation: true,
      onBeforeShow: async () => window.confirm("是否打开助手？"),
      onShow: () => console.log("聊天窗口已显示"),
      onHide: () => console.log("聊天窗口已隐藏"),
    },
  },
});

componentProps 配置

| 参数 | 默认值 | 说明 | | --- | --- | --- | | layout | 有 container 时为 embedded，否则为 floating | embedded 嵌入容器；floating 显示悬浮窗口。 | | container | — | 嵌入模式的容器，可传 CSS 选择器或 HTMLElement。 | | title | AIOS 智能助手 | 窗口标题。 | | width / height | 自适应 | 悬浮窗口的宽高。 | | borderRadius | 18px | 悬浮窗口圆角。 | | position | bottom-right | 悬浮位置：bottom-right、bottom-left、top-right、top-left。 | | zIndex | 2147483000 | 悬浮窗口层级。 | | open | false | 是否在初始化后立即展开悬浮窗口。 | | showLauncher | true | 是否显示悬浮球。设为 false 时窗口直接显示。 | | launcherText / launcherAriaLabel | — | 悬浮球文字及无障碍标签。 | | launcherSize / launcherRadius / launcherBackground | — | 悬浮球尺寸、圆角和背景。 | | className / style | — | SDK 根节点的 CSS 类名和内联样式。 |

上传并发送附件

SDK 不绑定特定文件存储。接入方通过 fileUploader 将浏览器中的 File 上传为 AIOS 运行时可以访问的 URL。配置成功后，且 ui.chatBot.uploadable 未设为 false 时，输入框会显示附件按钮。

const chatClient = new WebChatClient({
  config: {
    type: "bot",
    apiBaseUrl: "https://aios.example.com/low-code",
    botId: "<BOT_ID>",
  },
  userInfo: { id: "visitor_001" },
  fileUploader: async (file) => {
    const response = await uploadToYourStorage(file);
    return {
      url: response.publicUrl,
      name: file.name,
      assetType: file.type.startsWith("image/") ? "image" : "file",
      mimeType: file.type,
      size: file.size,
    };
  },
});

也可以发送已经上传的公开 URL：

await chatClient.sendMessage({
  content: "请分析这份合同",
  attachments: [
    {
      url: "https://files.example.com/contract.pdf",
      name: "合同.pdf",
      assetType: "file",
    },
  ],
});

附件对象支持 url、name、assetType（image 或 file）、mimeType 和 size。其中 url 必须可被 AIOS 运行时访问。

事件回调

通过 callbacks 注册事件回调。也可使用 eventCallbacks 或直接传入同名顶层参数，优先级为 callbacks > eventCallbacks > 顶层回调。

| 回调 | 触发时机 | | --- | --- | | onReady(client) | SDK 界面创建完成。 | | onOpen(client) | 聊天窗口展开。 | | onClose(client) | 聊天窗口隐藏。 | | onMessage(message, client) | 用户或助手消息写入、更新时。 | | onEvent({ type, data }, client) | 收到服务端事件时。 | | onTokenRefreshed(token, client) | 成功刷新令牌后。 | | onError(error, client) | 上传、鉴权、回调或会话请求失败时。 |

const chatClient = new WebChatClient({
  // config、auth、userInfo 省略
  callbacks: {
    onReady: () => console.log("Chat SDK ready"),
    onEvent: ({ type, data }) => console.debug(type, data),
    onMessage: (message) => console.debug(message.role, message.content),
    onError: (error) => showToast(error.message),
  },
});

WebChatClient 方法

| 方法 | 说明 | | --- | --- | | open() / show() | 展开悬浮聊天窗口。嵌入模式始终可见。 | | close() / hide() | 隐藏悬浮聊天窗口。 | | toggle() | 切换悬浮窗口的展开与隐藏状态。 | | validateToken() | 校验当前访问令牌，不会创建会话或发送消息。失败时抛出后端错误信息。 | | sendMessage(options) | 发送文本或附件，消费流式回复。返回 conversationId 与事件列表。 | | uploadFile(file) | 调用 fileUploader 上传文件，并将结果加入下一次发送。 | | setConversationId(id?) | 切换或恢复会话。空值表示下次发送时创建新会话。 | | getConversationId() | 获取当前会话 ID；尚未创建时返回空字符串。 | | newConversation() | 清空当前窗口消息并重置会话 ID，不删除服务端历史。 | | clearMessages() | 仅清空当前窗口消息，不删除服务端历史，也不重置会话 ID。 | | setAuth(auth) | 更新访问令牌或令牌刷新函数。 | | setUserInfo(userInfo) | 更新访客信息。切换智能体访客后建议同时重置会话 ID。 | | refreshToken() | 主动执行 onRefreshToken 并更新令牌；未设置刷新函数时返回当前令牌。 | | update(options, settings?) | 合并配置并默认重新渲染窗口。传 { rebuild: false } 时仅更新内存配置。 | | destroy() | 销毁 SDK 创建的 DOM、iframe（如有）和事件监听。销毁后实例不可继续使用。 |

令牌预校验

可在显示聊天窗口前校验令牌。无效、过期或无权限时，方法会抛出服务端返回的错误信息。

try {
  await chatClient.validateToken();
  chatClient.show();
} catch (error) {
  showError(error instanceof Error ? error.message : "访问令牌校验失败");
}

如果尚未创建客户端，也可直接调用：

await validateToken({
  apiBaseUrl: "https://aios.example.com/low-code",
  token: "<ACCESS_TOKEN>",
});

API 错误返回

令牌校验、发送消息和运行时流式事件失败时，SDK 会以 ChatSdkApiError 拒绝 Promise。错误对象保留平台返回的信息，便于接入方提示用户或进行日志记录。

| 字段 | 说明 | | --- | --- | | message | 可直接展示的错误文案。 | | status | HTTP 状态码；网络请求未发出时为 0。 | | code | 平台业务错误码；没有业务码时为 HTTP_<状态码> 或 NETWORK_ERROR。 | | details | 平台返回的原始错误对象。 | | url | 失败请求的地址。 |

try {
  await chatClient.validateToken();
} catch (error) {
  if (error instanceof ChatSdkApiError) {
    console.error(error.status, error.code, error.details);
  }
}

发送消息与管理会话

const result = await chatClient.sendMessage({
  content: "你好，请介绍一下你能做什么",
  parameters: { scene: "customer_service" },
});

console.log(result.conversationId);

chatClient.setConversationId("<CONVERSATION_ID>");
await chatClient.sendMessage({ content: "继续刚才的话题" });

chatClient.newConversation();
await chatClient.sendMessage({ content: "开始一个新话题" });

更新令牌、访客和界面

chatClient.setAuth({
  type: "token",
  token: "<NEW_ACCESS_TOKEN>",
  onRefreshToken: refreshAccessToken,
});

chatClient.setUserInfo({ id: "visitor_002", nickname: "新访客" });
chatClient.setConversationId();

chatClient.update({
  ui: {
    chatBot: { title: "售后助手" },
  },
});

校验配置

normalizeChatSdkConfig(config) 可用于创建客户端前校验并标准化调用目标。服务地址不是绝对 HTTP(S) 地址、目标 ID 缺失或目标类型非法时会抛出错误。

import { normalizeChatSdkConfig } from "@kmlckj/licos-chat-sdk";

const config = normalizeChatSdkConfig({
  type: "bot",
  apiBaseUrl: "https://aios.example.com/low-code",
  botId: "<BOT_ID>",
  isIframe: false,
});

注意事项

• AIOS 服务地址需要允许接入页面跨域访问，并允许 Authorization、Content-Type、X-Workspace-Id 请求头。
• isIframe: false 是推荐模式，SDK 与宿主页面共用运行环境；true 使用同源 iframe 隔离 UI，但不改变服务调用地址和鉴权方式。
• 会话历史由稳定的访客 ID 和会话 ID 共同关联。需要隔离访客或开启新上下文时，应使用不同的匿名访客 ID，并调用 newConversation() 或 setConversationId()。
• 本版本不伪造服务端会话列表、消息评价等能力；这类功能需要平台提供对应的持久化与权限接口后再接入。