更新记录

1.0.0（2026-07-28）

• 首次发布跨端 SSE UTS API，支持 Android、iOS、HarmonyOS NEXT 与微信小程序。
• 支持标准 SSE 解析、安全重连、POST 幂等恢复及 OpenAI/Anthropic 数据解析。
• 提供稳定错误码与本地脱敏诊断，不上传业务数据。

平台兼容性

uni-app(5.15)

uni-app x(5.15)

Longde SSE · 原生流式通信

longde-sse 是面向 AI 对话与实时推送的跨端 SSE UTS 插件，适用于 uni-app 与 uni-app x。它提供标准 SSE 协议解析、安全重连、POST 幂等恢复、AI 数据帧辅助解析和可复制的脱敏诊断。

核心能力

• GET、POST 与其他自定义 HTTP 方法
• 自定义请求头和 UTF-8 请求体
• 标准 SSE data、event、id、retry 字段解析
• 多行 data 合并、注释/心跳忽略
• UTF-8 字节分片、BOM 与 CR/LF/CRLF 边界处理
• HTTP 状态码与响应头回调
• 主动取消、连接超时、读取超时
• GET/HEAD 可选自动重连、指数退避与 Last-Event-ID 续传
• POST 显式幂等键保护下的可选自动恢复
• 安全的同源/跨源重定向策略与 HTTPS 降级保护
• Cookie 默认隔离，可显式启用会话 Cookie
• 事件类型过滤、重连随机抖动与连接状态查询
• 手动暂停/恢复，以及宿主驱动的断网和前后台恢复
• OpenAI-compatible、Anthropic 与原始 AI 数据帧辅助解析，思考增量与最终回答分离
• 不保存请求内容，不内置任何服务端密钥

安装

将插件目录放入项目：

uni_modules/longde-sse

UTS 插件的运行和原生编译需要 HBuilderX。Android 与 iOS 原生实现不依赖第三方 SDK。

平台与宿主

建议使用 HBuilderX 5.15+。插件支持 Android、iOS、HarmonyOS NEXT、微信小程序，以及 uni-app Vue 2、Vue 3 和 uni-app x。

付费 UTS 插件在 HarmonyOS NEXT 或微信小程序上使用时，需要 DCloud 云端编译，因此这两个目标当前要求 uni-app x 宿主。

当前版本已完成 Android 真机自动化、iOS 与 HarmonyOS NEXT 模拟器自动化，以及微信开发者工具的流式页面人工查看。iOS、HarmonyOS NEXT 与微信小程序尚未做真机验收；这不是功能限制，而是当前版本公开的验证边界。

从零开始使用

从插件目录导入 connect，传入 URL 和 onMessage 即可建立连接。connect() 立即返回一个 SSEClient，网络请求和参数校验都在异步流程中执行；因此请在 onError 中处理失败，而不是使用同步 try/catch 等待它抛错。

import { connect } from '@/uni_modules/longde-sse'

const client = connect({
  url: 'https://api.example.com/events',
  onMessage(event) {
    // event.data 是服务端一条完整 SSE data 内容
    console.log(event.event, event.id, event.data)
  },
  onError(error) {
    // 使用稳定数字 errCode 做业务分支；不要依赖 errMsg 文本。
    console.error(error.errCode, error.errMsg, error.data?.diagnosticId)
  },
  onClose(event) {
    console.log('closed:', event.reason)
  }
})

// 页面卸载、用户取消对话时调用；可重复调用。
client.close()

connect(options) 参数参考

url 和 onMessage 是必填项，其余均可省略。所有超时单位都是毫秒。请求头使用对象数组，不是普通对象，以便跨端保持一致的顺序和校验规则。

请求与诊断参数

自动重连与 POST 恢复

默认不重连。GET/HEAD 设置 reconnect: true 后可使用下表策略。POST 可能有副作用或产生 AI 计费，必须同时设置 reconnectPost: true 与稳定的 idempotencyKey，并由服务端按该键去重。

安全、重定向、Cookie 与生命周期参数

回调参数与数据结构

回调顺序为：成功连接时 onOpen → 零到多次 onMessage → onClose；失败时 onError → onClose。HTTP 非 2xx 或错误 Content-Type 不会触发 onOpen。

SSEClient 方法参考

平台能力检测

调用 getCapabilities() 后再启用 Cookie、重定向或后台连接等依赖平台的策略。它返回 platform（android / ios / harmony / mp-weixin）、streaming、postStreaming、lastEventId、backgroundStreaming，以及 reconnect、cookiePolicy、redirectPolicy、httpStatus 的支持等级。

import { getCapabilities } from '@/uni_modules/longde-sse'

const capabilities = getCapabilities()
if (capabilities.cookiePolicy !== 'native') {
  // 改用无 Cookie 的 Bearer Token，或禁用依赖会话 Cookie 的入口。
}

AI 流式对话示例

import { connect } from '@/uni_modules/longde-sse'

const requestId = 'chat-' + Date.now().toString()
const client = connect({
  url: 'https://example.com/v1/chat/completions',
  method: 'POST',
  headers: [
    { name: 'Authorization', value: 'Bearer ' + token },
    { name: 'Content-Type', value: 'application/json' }
  ],
  body: JSON.stringify({
    model: 'your-model',
    stream: true,
    messages: [{ role: 'user', content: '你好' }]
  }),
  onOpen(event) {
    console.log('SSE connected', event.statusCode)
  },
  onMessage(event) {
    if (event.data == '[DONE]') {
      client.close()
      return
    }
    console.log('chunk', event.data)
  },
  onError(error) {
    const data = error.data
    console.error(error.errCode, error.errMsg, data?.diagnosticId)
  },
  onClose(event) {
    console.log('SSE closed', event.reason)
  },
  // POST 重试必须与服务端幂等去重配合；不需要恢复时不要开启。
  reconnect: true,
  reconnectPost: true,
  idempotencyKey: requestId,
  reconnectMaxRetries: 2
})

推荐由业务后端持有 AI 服务密钥，App 连接自己的后端 SSE 接口。不要把长期有效的服务端密钥写进客户端代码。

parseOpenAICompatibleData(event.data) 可直接取得 kind/text/reasoning/done/metadata/invalid-json/raw；Anthropic 使用 parseAnthropicData，私有协议使用 parseRawAIData。reasoning 仅用于展示模型思考增量，不能混入最终回答或下一轮上下文。这些函数是无状态解析器，不会改变 SSE 连接、重连和诊断行为。

行为约定

• 默认请求方法为 GET。
• 默认建连超时为 15 秒。
• 默认读取超时为 0，即允许长连接一直等待下一条数据。
• 只有包含至少一个 data 字段的事件才触发 onMessage。
• 服务端正常结束时 onClose.reason 为 eof；HTTP 204 为 no-content；主动关闭时为 cancelled。
• 自动重连默认关闭；GET/HEAD 可通过 reconnect: true 启用，其余策略使用 reconnectMaxRetries 等顶层字段。POST 只有同时启用 reconnectPost 并提供稳定 idempotencyKey 才允许重试，且服务端必须按该键去重。
• 自动重连会处理网络错误、超时、HTTP 429/5xx 和可选 EOF，支持服务端 retry: 与 Last-Event-ID 续传。
• client.getState() 返回 connecting/open/reconnecting/paused/closing/closed/failed；close() 可重复调用。
• pause() 取消当前请求但不终结 client，resume() 重新连接；网络与前后台通知均需宿主接入，自动暂停/恢复开关默认关闭。
• 可查询最后错误、关闭原因、当前 URL 和下一次重连等待。
• 启用重连后状态还可能为 reconnecting；close() 会同时取消等待中的重连。
• client.getDiagnosticReport() 可导出仅在内存中保存的脱敏诊断 JSON，插件不会自动上传。
• 单行上限为 256 KiB，单事件上限为 1 MiB；越界返回 7002，防止异常服务端无限占用内存。
• event.retry 是服务端最新的合法重连提示；只有显式启用自动重连时才会用于下一次等待时间。

错误码与排查

错误对象的 errSubject 固定为 longde-sse::connect。error.data 中可取得不含密钥和正文的 diagnosticId，可随问题描述发送至 longdecloud@163.com 协助排查。插件不会自动上传诊断信息。

“可重试”只表示传输层可能恢复。对 AI 的 POST 流，请使用请求幂等键和服务端去重，避免重复生成或重复计费。

隐私说明

插件仅向调用方传入的 URL 发起请求。请求头、请求体与流式响应仅在本次连接的内存中处理，不会被插件另行收集、持久化或上传。