更新记录

1.0.0（2026-08-17） 下载此版本

• 首次发布：跨端流式请求 UTS 插件。
• 支持 Android / iOS / HarmonyOS / Web / 微信小程序 五端，兼容 uni-app 与 uni-app x。
• 支持 SSE / Line / JSONL / Raw 四种协议。
• 支持 GET / POST / PUT / PATCH / DELETE、自定义请求头与请求体。
• 支持增量 UTF-8 解码（中文 / Emoji 跨分片不乱码）、Last-Event-ID 续传。
• 支持自动重连（指数退避 / 抖动 / SSE retry / HTTP Retry-After / 状态码覆盖 / 累计预算）。
• 支持网络与前后台恢复、高频回调批处理、业务终止帧。
• 支持指标快照 getMetrics() 与脱敏诊断 exportDiagnostics()。
• 附带本地零依赖测试服务器与引擎逻辑 Node 验证脚本。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lucis-sse 流式请求(SSE/Line/JSONL/Raw) UTS 插件

面向 AI 对话、智能客服、消息推送、日志流和长任务进度的跨端流式请求 UTS 插件。一次接入即可在 Android、iOS、HarmonyOS、Web、微信小程序 中统一处理 SSE、逐行文本、JSONL 和 Raw 文本流。

插件不是对 EventSource 的简单包装：支持 POST/PUT/PATCH/DELETE、自定义请求头与请求体、严格 UTF-8 增量解码、首包保护、SSE 标准字段、Last-Event-ID、可控重连、超时、限流与幂等取消。

部分功能未验证，如需在生产环境中使用，请自行测试。仅供有需求的开发者参考使用！！！

功能特性

• 四种流协议：sse / line / jsonl / raw，同一套回调处理不同服务端格式。
• 不局限 GET：支持 GET / POST / PUT / PATCH / DELETE，可接 OpenAI 兼容接口、私有 AI 网关和业务流接口。
• 两种请求头写法：兼容 headers 动态对象，同时推荐跨端更稳定的 headerList 强类型数组。
• 首包不丢：所有回调在网络请求发出前完成注册，适配"连接后立即返回第一段"的服务端。
• 完整 SSE 语义：支持 BOM、CR/LF/CRLF、注释心跳、多行 data、event、id、retry 和未知字段忽略。
• UTF-8 分片安全：五个平台统一使用自研增量解码器，保留不完整多字节尾部，中文与 Emoji 不会因网络分片乱码。
• 断线续传：可将最近 id 自动写入下一次请求的 Last-Event-ID。
• 生产级重试：指数退避、抖动、SSE retry、HTTP Retry-After、状态码覆盖、累计时间预算和远端结束策略。
• 网络与前后台恢复：自动感知网络变化，App 回到前台后可按策略恢复连接。
• 连接指标：getMetrics() 读取连接耗时、首字节、消息、字节、错误、重连次数。
• 脱敏诊断：exportDiagnostics() 生成可直接交给技术支持的 JSON 报告，不包含 URL 查询参数、请求头值、请求体或消息正文。
• 高频批处理：按时间窗口或数量合并 chunk / message 回调，降低 AI 高频 token 对页面渲染的压力。
• 业务终止帧：可识别 [DONE] 或自定义 data/event 控制帧，以正常完成原因结束。
• 微信真实分块：使用 uni.request({ enableChunked: true }) + onChunkReceived，不是等待完整响应后伪装流式。
• 无额外网络 SDK：Android 使用 HttpURLConnection，iOS 使用 URLSessionDataDelegate，HarmonyOS 使用 requestInStream，Web 使用 Fetch 流，微信使用 RequestTask。

支持平台

安装与运行前准备

1. 从 DCloud 插件市场导入插件，或把 uni_modules/lucis-sse 目录放入项目。
2. 页面始终从插件根目录导入：import { connectStream } from '@/uni_modules/lucis-sse'，不要指向 utssdk/index.uts。
3. Android / iOS / HarmonyOS 首次接入或升级原生代码后，需要重新制作自定义基座（只改页面、示例 URL 或普通业务代码时不需要）。
4. Web 无需自定义基座，但服务端必须允许当前站点跨域访问并关闭响应缓冲。
5. 微信小程序 无需自定义基座，但必须在微信公众平台配置 HTTPS 合法请求域名；正式版不能依赖开发工具的"忽略域名校验"。
6. 生产接口建议使用 HTTPS，不要把 Token 写死在源码或日志中。

最小可运行示例

uni-app（Vue2/Vue3）

import { connectStream } from '@/uni_modules/lucis-sse'

const connection = connectStream({
  url: 'https://example.com/events',
  // 回调与参数一次性传入，插件会先注册回调再发起请求。
  onMessage(message) {
    console.log('收到完整事件：', message.data)
  },
  onError(error) {
    console.log('连接失败：', error.errCode, error.errMsg)
  },
  onComplete(event) {
    console.log('连接最终结束：', event.reason)
  }
})

// 页面离开或用户点击停止时调用；重复调用是安全的。
connection.abort()

uni-app x

import { connectStream, type StreamConnection, type StreamMessage, type StreamFail } from '@/uni_modules/lucis-sse'

let connection: StreamConnection | null = null

connection = connectStream({
  url: 'https://example.com/events',
  onMessage: (message: StreamMessage): void => {
    console.log('收到完整事件：' + message.data)
  },
  onError: (error: StreamFail): void => {
    console.log('连接失败：' + error.errCode.toString())
  },
  onComplete: (event): void => {
    console.log('连接最终结束：' + event.reason)
    connection = null
  }
})

微信小程序

import { connectStream } from '@/uni_modules/lucis-sse'

const connection = connectStream({
  // 必须提前配置为微信小程序合法请求域名。
  url: 'https://stream.example.com/events',
  protocol: 'sse',
  onMessage(message) {
    console.log('微信小程序收到事件：', message.data)
  },
  onComplete(event) {
    console.log('连接结束：', event.reason)
  }
})

// 页面卸载时主动取消，避免残留网络任务。
connection.abort()

API 列表

connectStream(options)

创建一个流式 HTTP 请求。函数同步返回连接控制对象，网络事件通过 options 中的回调持续返回。所有回调会在请求发出前保存，避免立即首包丢失。

重连参数 reconnect

生产级重试 reconnect.policy

自动等待优先级：有效 HTTP Retry-After → SSE retry: → 客户端指数退避。POST 默认关闭自动重连，除非服务端提供幂等键并允许安全重放。

返回值 StreamConnection

常见用法

POST + 自定义请求头 + 鉴权

import { connectStream } from '@/uni_modules/lucis-sse'

const connection = connectStream({
  url: 'https://api.example.com/v1/chat/stream',
  method: 'POST',
  protocol: 'sse',
  headerList: [
    { name: 'Authorization', value: 'Bearer ' + runtimeToken },
    { name: 'X-Customer-ID', value: customerId }
  ],
  jsonBody: {
    model: 'your-model',
    messages: [{ role: 'user', content: '你好' }],
    stream: true
  },
  reconnect: { enabled: false },
  terminal: { enabled: true, deliverMessage: false },
  onMessage: (message) => console.log(message.data),
  onTerminal: (event) => console.log('服务端业务完成：' + event.source),
  onError: (error) => console.log(error.errCode + '：' + error.errMsg)
})

自动重连 + Last-Event-ID

const connection = connectStream({
  url: 'https://example.com/events',
  protocol: 'sse',
  reconnect: {
    enabled: true,
    maxAttempts: 5,
    initialDelayMs: 1000,
    maxDelayMs: 15000,
    multiplier: 2,
    jitterRatio: 0.2,
    useServerRetry: true
  },
  onRetry: (event) => {
    console.log('第 ' + event.attempt + ' 次重连将在 ' + event.delayMs + 'ms 后执行')
  },
  onMessage: (message) => {
    // 插件会保存 SSE id，并在重连时自动发送 Last-Event-ID。
    console.log(message.id + ': ' + message.data)
  }
})

App 前后台恢复

// App.vue
import { notifyStreamAppState } from '@/uni_modules/lucis-sse'

export default {
  onShow() {
    notifyStreamAppState('foreground')
  },
  onHide() {
    notifyStreamAppState('background')
  }
}

指标与脱敏诊断

const metrics = connection.getMetrics()
console.log('连接耗时：' + metrics.connectDurationMs + 'ms')
console.log('首字节：' + metrics.firstByteDurationMs + 'ms')

// 报告不包含 Authorization/Cookie 值、URL 查询参数、body、chunk 或 message.data。
const diagnosticJson = connection.exportDiagnostics()

回调数据

StreamMessage

StreamCompleteEvent

错误码

各平台注意事项

• Android：需要 android.permission.INTERNET（插件 Manifest 已声明）；首次接入必须制作自定义基座。Thread SAM、ByteArray↔Uint8Array、String.toByteArray() 三个点在打基座时需验证。
• iOS：需要 macOS + Xcode；云端打包或自定义基座。UTS↔Swift 的闭包回调、[UInt8]↔Array<number>、Map↔Dictionary 在打基座时需验证。
• HarmonyOS：需 DevEco 与自定义基座/HAP；不依赖加密 module.har。
• Web：服务端必须配置 CORS，代理层不能缓冲响应（建议返回 X-Accel-Buffering: no）。
• 微信小程序：基础库 ≥ 2.20.1；必须配置 HTTPS 合法请求域名；abort() 在 enableChunked 下可能失效，插件会按连接自然结束兜底。

本地测试服务

仓库自带零依赖 Node 本地测试服务，覆盖 SSE 基础、中文跨分片、POST 回显、Line/JSONL/Raw、断线续传、Retry-After、终止帧、断流等场景：

# 在项目根目录执行；服务默认监听 0.0.0.0:8787，允许局域网真机访问
node uni_modules/lucis-sse/example/server/lucis-sse-test-server.js