简介

Omni Chatbot SDK 是一个框架无关的 AI 客服前端组件，几行代码即可为任意网站接入对话界面。

与其他绑定特定服务商的组件不同，本 SDK 与后端完全解耦——你只需提供接口地址，SDK 负责 UI、状态管理、Markdown 渲染和动画。

功能特性

• 高级 UI：玻璃拟态设计、流体渐变背景、弹簧动画。
• 后端无关：兼容 DeepSeek、OpenAI、Claude 或任意自定义后端。
• SSE 流式输出：支持 OpenAI delta 格式与 raw text 两种模式。
• 主题切换：内置亮/暗色模式，自动跟随系统。
• 国际化：开箱支持中文（ZH）与英文（EN），支持自定义文案覆盖。
• 双框架支持：原生支持 React 和 Vue 3。
• 生命周期钩子：发送前/后、开关窗口、错误处理全部可拦截。
• 动态用户上报：通过 getExtraBody 每次发送时动态注入用户 ID 等业务数据。

快速开始

CDN 方式（无构建工具）

<script src="https://cdn.jsdelivr.net/npm/omni-chatbot-sdk/dist/omni-chatbot-sdk.umd.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/omni-chatbot-sdk/dist/style.css">

<script>
  ChatbotUI.init({
    appId: 'my-app',
    apiConfig: {
      chatEndpoint: 'https://your-api.com/chat'
    },
    brand: {
      name: '智能客服',
      logoUrl: 'https://your-site.com/logo.png'
    }
  });
</script>

NPM + React

pnpm add omni-chatbot-sdk

import { Chatbot } from 'omni-chatbot-sdk';
import 'omni-chatbot-sdk/dist/style.css';

export default function App() {
  return (
    <Chatbot
      appId="my-app"
      apiConfig={{ chatEndpoint: '/api/chat', streaming: true }}
      theme="auto"
    />
  );
}

NPM + Vue 3

<script setup>
import { VueChatbot } from 'omni-chatbot-sdk';
import 'omni-chatbot-sdk/dist/style.css';
</script>

<template>
  <VueChatbot
    app-id="my-app"
    :api-config="{ chatEndpoint: '/api/chat', streaming: true }"
    theme="auto"
  />
</template>

配置项（ChatbotProps）

| 字段 | 类型 | 说明 | |------|------|------| | appId | string | 应用唯一标识 | | apiConfig | ApiConfig | 接口配置（见下） | | theme | 'auto' \| 'light' \| 'dark' | 主题，默认 auto | | mode | 'floating' \| 'embedded' | 浮窗或嵌入模式，默认 floating | | locale | 'auto' \| 'zh' \| 'en' | 语言，默认 auto | | brand | BrandConfig | 品牌定制（名称、Logo、头像等） | | colors | ThemeColors | 主色调定制 | | persona | 'cool' \| 'mischievous' | 人格风格 | | hooks | ChatbotHooks | 生命周期钩子 | | webmcpEnabled | boolean | 是否启用 WebMCP 协议 |

ApiConfig

| 字段 | 类型 | 说明 | |------|------|------| | chatEndpoint | string | 后端聊天接口地址 | | headers | Record<string, string> | 自定义请求头（如 Authorization） | | extraBody | Record<string, any> | 静态附加 body 参数 | | getExtraBody | () => Record<string, any> | 动态附加 body 参数，每次发送时调用 | | streaming | boolean | 是否开启 SSE 流式输出 | | streamFormat | 'openai' \| 'raw' | 流格式，默认 openai |

ChatbotHooks（生命周期钩子）

<Chatbot
  appId="my-app"
  apiConfig={{ chatEndpoint: '/api/chat' }}
  hooks={{
    // 发送前：返回新消息内容，或返回 false 取消本次发送
    onBeforeSend: (message) => {
      if (!message.trim()) return false;
      return message;
    },
    // 发送后：收到完整回复时触发，可用于埋点
    onAfterSend: ({ userMessage, assistantReply }) => {
      analytics.track('chat', { userMessage, assistantReply });
    },
    onOpen: () => console.log('客服窗口已打开'),
    onClose: () => console.log('客服窗口已关闭'),
    onError: (err) => console.error('客服出错', err),
  }}
/>

动态传入用户信息

AI 客服通常需要将用户 ID、账号等业务数据上报给后端。使用 getExtraBody 每次发送时动态注入：

import { useAuthStore } from '@/store/auth';

function SupportChatbot() {
  const account = useAuthStore((s) => s.account);

  return (
    <Chatbot
      appId="support"
      apiConfig={{
        chatEndpoint: 'https://api.example.com/chat',
        streaming: true,
        // 每次发送消息时调用，动态读取当前登录用户
        getExtraBody: () => ({
          userId: account?.account_id ?? null,
          userEmail: account?.email ?? null,
        }),
      }}
    />
  );
}

后端收到的请求体将自动包含：

{
  "message": "用户的输入",
  "history": [...],
  "metadata": { "timezone": "Asia/Shanghai", "platform": "pc", ... },
  "userId": "acc_xxxxxxxx",
  "userEmail": "[email protected]"
}

后端协议

POST 请求体：

{
  "message": "用户输入",
  "history": [{ "role": "user", "content": "..." }],
  "metadata": {
    "timezone": "Asia/Shanghai",
    "language": "zh-CN",
    "platform": "pc",
    "os": "MacOS",
    "clientTime": "2026/5/20 17:00:00"
  }
}

非流式响应：

{ "success": true, "data": { "reply": "AI 回复内容" } }

流式响应（SSE）：

data: {"choices":[{"delta":{"content":"你好"}}]}
data: {"choices":[{"delta":{"content":"，有什么"}}]}
data: [DONE]

开发

pnpm install
pnpm dev        # 启动 Demo 页
pnpm docs:dev   # 启动文档站

License

MIT © webkubor