更新记录

0.1.0（2026-10-14） 下载此版本

  • 首发：uni-app x 智能客服 SDK（带界面版，App / H5 / 微信小程序）
  • 协议与 Web 版 @reglow/customer-service SDK 同源：GET /cs/sdk-config、POST /cs/chat（SSE）、GET /cs/history、POST /cs/transfer、POST /cs/rating、POST /cs/upload、WS /cs/ws/user
  • 无 UI 核心层 createCsSdk(config): CsSdk：init / send / sendImage / requestTransfer / rate / loadHistory / connectWS / disconnect / optOut / optIn，session_id 经 uni.setStorageSync 持久化，onEvent 统一回调
  • 界面组件 <re-cs-chat />：悬浮球 + 工具菜单（在线客服 / 常见问题 / 扫码咨询 / 联系方式 / 反馈）、聊天面板（气泡 / 图片 / 流式追加 / 正在输入 / 转人工 / 1~5 满意度评价）、FAQ 搜索与提问、历史消息恢复，交互对照 Web 版 sdk_template.html
  • SSE 流式：H5 端 fetch + ReadableStream 逐行解析实时增量；App / 小程序端降级为一次性拉取完整 SSE 文本后顺序回调（非实时，功能不缺失），详见 readme「SSE 流式的端差异」
  • WebSocket：uni.connectSocket + 30s ping 心跳 + 断线指数退避重连（最多 5 次），处理 agent_message / agent_online / session_closed
  • 极简 Markdown：客服气泡支持 **加粗** / *斜体* / 行内 `code` / 换行 / 代码块等宽
  • 复用 reglow-review（easycom）：re-icon / re-button / re-empty / re-dialog / re-fab；消息列表因需承载图片与系统卡片以自绘为主，取舍见 readme
  • 附带演示页 pages/cs/cs-sdk（智能客服 Demo）

平台兼容性

uni-app x(5.31)

Chrome Safari Android iOS 鸿蒙 微信小程序
√ √ √ √ √ √

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
√ √ × √

reglow-cs-sdk（uni-app x 智能客服 SDK · 带界面版）

基于 uni-app x / UTS 实现的智能客服 SDK，提供无 UI 核心层（createCsSdk）与开箱即用的界面组件（<re-cs-chat />），支持 App（Android / iOS / HarmonyOS）、H5、微信小程序 三端。 聊天协议与 Web 版 @reglow/customer-service SDK 完全同源（/api/v1/cs/*，SSE 流式 + WebSocket 坐席推送），同一后端可直接复用。

特性

  • 协议同源：GET /cs/sdk-config（公开配置/FAQ/二维码/联系方式）、POST /cs/chat（SSE 流式对话）、GET /cs/history（历史恢复）、POST /cs/transfer（转人工）、POST /cs/rating（满意度评价）、POST /cs/upload（图片上传）、WS /cs/ws/user（坐席实时消息）。
  • 带界面组件：<re-cs-chat /> 一个组件开箱即用——悬浮球（FAB）+ 工具菜单（在线客服 / 常见问题 / 扫码咨询 / 联系方式 / 反馈）、聊天面板（消息气泡 / 图片 / 流式追加 / 正在输入 / 转人工 / 满意度评价）、FAQ 搜索与提问、历史消息恢复，界面功能对照 Web 版 sdk_template.html。
  • 无 UI 核心层：createCsSdk(config) 返回 CsSdk，纯逻辑可独立用于自定义界面。
  • SSE 流式：H5 端 fetch + ReadableStream 逐行解析 data: 增量实时输出；App / 小程序端自动降级为一次性拉取完整 SSE 文本后顺序回调（见下方「SSE 流式的端差异」）。
  • WebSocket 推送：uni.connectSocket + 30s 心跳 ping + 断线指数退避重连（最多 5 次）。
  • 会话持久化：session_id 通过 uni.setStorageSync 持久化，二次进入自动 loadHistory 恢复。
  • 极简 Markdown：客服气泡支持 **加粗**、*斜体*、行内 `code`、换行与代码块等宽显示。
  • 隐私友好：optOut() 持久化退出标记，退出后不再发起任何聊天请求。

安装

  1. 将 uni_modules/reglow-cs-sdk 目录复制到项目的 uni_modules/ 下（HBuilderX 插件市场安装亦同）。
  2. 依赖：本插件依赖 uni_modules/reglow-review（easycom 引用其 re-icon / re-button / re-empty / re-dialog / re-fab 基础组件），需一并安装 reglow-review。

快速接入（带界面）

在任意页面使用 <re-cs-chat /> 即可（pages.json 已开启 easycom.autoscan，无需手动 import）：

<template>
  <view class="page">
    <!-- 业务页面内容 -->
    <re-cs-chat app-id="your-app-id" api-base="/api/v1" visitor-name="微信用户" primary-color="#4f46e5" />
  </view>
</template>

Props

名称 类型 默认值 说明
appId string 必填 客服应用 ID，对应协议 app_id
apiBase string '' 接口前缀。留空时使用 sdk-config 返回的 api_base，仍为空则取 /api/v1。传 /api/v1（同源）或 https://api.xxx.com/api/v1（跨域）均可自动归一
visitorName string '' 访客昵称，随消息与转人工提交
primaryColor string '' 主题色，缺省使用 sdk-config.primary_color，再缺省为 #4f46e5
showFab boolean true 是否显示右下角悬浮球入口

组件默认挂载后即创建 SDK 并拉取公开配置，首次打开聊天面板时自动连接 WS 并恢复历史消息。

无 UI 接入（createCsSdk）

import { createCsSdk } from '@/uni_modules/reglow-cs-sdk/utssdk/index.uts'

const sdk = createCsSdk({
  appId: 'your-app-id',
  apiBase: '/api/v1',            // 可选
  visitorName: '微信用户',        // 可选
  onEvent: (event) => {
    // 处理事件：ready / session / stream / message / done /
    //          transfer / agent_online / session_closed / error
  }
})
sdk.init()                        // 异步拉取 /cs/sdk-config
sdk.send('你好')                   // 发文本，SSE 流式回复通过 onEvent('stream') 增量回调
sdk.sendImage('https://.../a.png') // 发图片（先自行调用 /cs/upload 得到 url）
sdk.requestTransfer()             // 转人工
sdk.rate(5, '很满意')              // 满意度评价
sdk.loadHistory()                 // 恢复历史消息
sdk.connectWS()                   // 建立坐席推送通道
sdk.disconnect()                  // 断开 WS（页面卸载时）
sdk.optOut()                      // 退出（持久化）

CsSdk API 与事件

方法

方法 说明
init(): Promise<void> 拉取 GET /cs/sdk-config 并合并配置（幂等；重复调用安全）
send(text: string): void 发送文本，调 POST /cs/chat 并解析 SSE
sendImage(imageUrl: string): void 发送图片消息（image_url 字段）
requestTransfer(): Promise<boolean> 请求转人工（POST /cs/transfer）
rate(rating: number, comment?: string): Promise<boolean> 满意度评价 1~5（POST /cs/rating）
loadHistory(): Promise<Array<ChatMessage>> 拉取 GET /cs/history 恢复历史
connectWS(): void 建立用户端 WebSocket（有 session_id 才生效）
disconnect(): void 断开 WS 并停止心跳 / 重连
optOut(): void 持久化退出标记，此后不再发起请求
optIn(): void 恢复
setVisitorName(name: string): void 动态设置访客昵称
getSessionId(): string 当前会话 ID
getConfig(): CsSdkConfig \| null 服务端公开配置（init 后可用）
isStreaming(): boolean 是否正在等待 SSE 回复

事件（onEvent(event: CsSdkEvent)）

event.type 载荷 触发时机
ready content（欢迎语） init() 完成，配置就绪
session sessionId 首条消息后服务端下发会话 ID（已持久化）
stream content（增量） SSE 文本增量（H5 实时；App/小程序一次性到达）
done - 一轮回复结束
message message（ChatMessage） 完整消息（预留，流式回复由 stream + done 表达）
transfer content（提示文案）、agentName 命中转人工（SSE transfer_required 或手动 requestTransfer 成功）
agent_online agentName WS 推送坐席在线
session_closed content WS 推送人工会话结束
error content 请求失败 / SSE error 事件

CsSdkEvent 结构：{ type, content, sessionId, agentName, message }（无值字段为空串 / null）。

聊天协议（与 Web 版同源）

接口 方法 说明
{base}/cs/sdk-config?app_id= GET 返回 {app_id, app_name, welcome_message, api_base, primary_color, qr_code:{title,desc,url}, contact:{phone,email,online_url,address,business_hours}, faq_enabled, faq_title, faqs:[{id,title,content}]}
{base}/cs/chat POST body {app_id, session_id?, message?, image_url?, visitor_name?}；响应 SSE，每行 data: {json}，事件序：session → content（可多次）→ handled_by_agent / transfer_required → done / error
{base}/cs/history?session_id= GET list[{id, session_id, role, content, content_type, image_url, created_at}]
{base}/cs/transfer POST body {app_id, session_id?, agent_key?, visitor_name?} → {session_id, status, agent_id, message}
{base}/cs/rating POST body {session_id, rating(1-5), comment?}
{base}/cs/upload POST multipart file（≤5MB，jpg/png/gif/webp）→ {url}
{base}/cs/ws/user?session_id= WS 服务端推送 agent_message / agent_online / session_closed；客户端每 30s 发 ping 保活

{base} 为归一化后的接口前缀，即 apiBase 以 /api/v1 结尾时为 apiBase，否则为 apiBase + '/api/v1'；默认 /api/v1。

SSE 流式的端差异（重要）

完整实时流式（逐字增量）仅在 H5 端可用：#ifdef H5 下使用 fetch + ReadableStream.getReader() 逐行解析 data: 前缀的 SSE 帧，通过 onEvent('stream') 实时增量回调，UI 呈现打字机效果。

App（Android/iOS/HarmonyOS）与微信小程序：uni.request 不支持流式读取，SDK 自动降级为「一次性拉取」——uni.request（dataType: 'text'，超时 120s）等待整个 SSE 响应结束后，一次性解析全部 data: 帧并按原顺序触发 stream → done 回调。界面上表现为：发送后显示「正在输入…」，等待完整回复后一次性展示，功能不缺失、仅非实时。

若需要 App / 小程序端实时流式，可自行改造：将 sse.uts 中 #ifndef H5 分支替换为原生 Socket 代理（由后端 / 网关把 SSE 转推给客户端），SDK 其余部分无需改动；或业务侧改为「发送后按需轮询 /cs/history」。

依赖说明

  • 依赖 reglow-review（package.json 的 uni_modules.dependencies 已声明）：界面组件以 easycom 复用其 re-icon / re-button / re-empty / re-dialog / re-fab 基础组件。
  • re-chat 家族（re-chat / re-chat-sender / re-chat-message / re-chat-content）的消息模型仅支持纯文本（content: string），无法承载客服图片消息 / 系统提示 / 评分卡片等混合内容，故本插件消息列表与输入区以自绘为主（对照 Web 版气泡样式），基础组件复用上述 re-*；如你的场景只用纯文本，也可自行换用 re-chat 家族。
  • 不改动 reglow-review 与后端任何代码。

Demo

  • 页面：pages/cs/cs-sdk（「智能客服 Demo」，已注册于 pages.json）。
  • 用法：见该页面源码，<re-cs-chat app-id="..." />。

隐私说明

  • optOut() 持久化退出标记，退出后 send / sendImage / requestTransfer / rate / connectWS / loadHistory 均不再发起请求。
  • SDK 不采集输入框内容之外的任何本地数据；访客昵称由业务侧主动传入。

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

无

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

许可协议

MIT协议
评论列表 撰写评论 向官方投诉

暂无用户评论。