OpenMax
免费试用

适配器

createOpenMaxAdapter 与构造参数 OpenMaxChatConfig、OpenMaxAuth、OpenMaxGetTokenOptions:每个成员打哪些接口。

适配器

@openmaxai/chat-openmax 根入口里关于适配器本身的导出:造适配器的函数和它的构造参数。状态、在宿主里怎么接和全部导出的索引见概览。适配器接口本身(每个成员的约定)见 @openmaxai/chat-sdk · 适配器。

createOpenMaxAdapter

function createOpenMaxAdapter(config: OpenMaxChatConfig): ChatSdkAdapter;

造一个接 OpenMax 后端的适配器(name 为 "openmax"),交给 @openmaxai/chat-sdk/react 的 createChatHost。同步:不发请求、不调 getToken,令牌在第一次真要发请求时才取。构造参数不合法时同步抛 ChatSdkConfigError(见 OpenMaxChatConfig)。只读 config 里连接那几项(baseUrl、wsUrl、realtime、auth、workspaceId、orgId)和 storage(设备标识存在哪);其余几项是宿主的,只有 @openmaxai/chat-openmax/react 的 createChatHost 用。

连接地址、令牌、设备标识都由适配器自己持有,不经适配器接口,也不出现在宿主的 inboundDelivery 上。

成员 OpenMax 的实现
identity 当前用户(GET /api/v1/me,令牌里没有成员身份时回 undefined)、会话成员(成员接口一次最多 1000 条,不分页)、组织通讯录搜索。按 id 打开会话时取的成员表经 subscribeMembers 交给 SDK,同一会话不再取第二次
messaging 发送、取历史(最新一窗、before_seq 往更早、after_seq 往更新、around_seq 围着某条)、loadThreadSince 补拉、建会话(建单聊时与身份读数共用同一次 /me)、按 id 取一条,表态、撤回、编辑与修订历史、改动日志,见消息接口。交出消息的四个出口(loadThread、loadThreadSince、getMessagesByIds、loadMessage)都不带后端原样的 agent_run:agentActivity(只读进度(实验性 · 过渡),见下文选项表)开着时由适配器内部解码进中立运行字段 agent_run_summary(完整 v3 ⇒ 完整形态、引用 ⇒ 引用形态、解析不了但 run 号合法 ⇒ 只带 run 号的引用形态、其余不填),关着不填
conversations 会话列表、置顶、隐藏、静音、推已读位置;按 id 取一个会话时先取会话,再取一次成员表找当前用户那一行:在里面按成员(置顶、静音、已读位置取自那一行,未读条数按 0),不在里面按旁观(只读);取当前用户失败按取失败(可重试);成员表回满上限还没找到当前用户时判不出,抛 ChatMembershipUnknownError
realtime 配了 wsUrl 才有。先用令牌换一次性票据(POST /auth/ws-ticket),带票据和设备标识建 WebSocket,帧解码成信号(含 typing 帧 ⇒ typing 信号、presence 帧 ⇒ SDK 自有的 ChatSdkPresenceSignal;agentActivity 开着时 agent_activity 帧先分流,proto-JSON 解码或解不出时 snake→camel 回退取出载荷,由适配器内部收窄校验,合格的交 SDK 自有的 ChatSdkAgentActivitySignal,不合格的整帧丢、不打断连接;关着时照其余未知帧丢掉),断线按指数退避重连(换票请求 10 秒内没回就中止、WebSocket 10 秒内没打开就关掉,都算一次失败的尝试,请求或握手挂住也照样退避重连;令牌交接时只放弃这次交接,旧连接照用),第一次连上发 connected(之前尝试失败过则发 reconnected),之后每次重连上发 reconnected;设备标识持久时回执 sync(见下表 storage);换票以 unauthorized 失败时停止重连,经 sink.error 报一次;换票以 forbidden 失败(403)同样停止重连、报一次,不续期;路径写法的 wsUrl 拿不到可用的页面源时不建连、不重连,经 sink.error 报一次 code 为 ws_url_unresolved 的 ChatSdkError(见下文路径写法);连接被服务端以凭据已吊销关闭码(4007,credential_revoked)关闭时不再重连,经 sink.error 报一次 kind 为 unauthorized、code 为 ws_credentials_invalid 的 ChatSdkError;每次断开(含宿主 dispose() 关掉打开着的连接)在结果出来之后经 sink.closed 交一条 ChatSdkRealtimeCloseRecord(layer 为 "sdk"),SDK 再经 onEvent 以 realtime.closed 交给宿主;本包不发任何上报请求。宿主已有自己那条连接时给 realtime: "off",再用 openMaxSharedRealtime 替换这一格
uploads 按会话上传(requireConversation 为 true,最多 5 个文件,每个 500 MB),resolveUrls 换显示用地址(预览模式),resolveDownloadUrl 在点文件下载键时现换下载地址(下载模式)
cards 是 / 否卡、业务卡按钮与选择卡(表单模板)的统一提交(POST /api/v1/messages/{id}/card-interactions,带 Idempotency-Key),30 秒内没拿到完整响应(响应头没到,或正文没读完)按超时。成功时用返回拼得出落定记录就带上(是 / 否卡与业务卡的答题人是当前成员,与身份读数共用同一次 /me;选择卡的答题人与答案取返回里的)。选择卡的答案按 formAnswersBody 换成请求体。续期重发后仍 401、没拿到响应、408、5xx 原样 reject;其余 4xx 按卡片判决给判决。三种卡同一套
directMessages 找或建私聊:POST /api/v1/conversations/dm(请求体只有 { peer_member_id },已有就交回、没有就建,不先问 /me),回包里的会话按成员换成包认识的形状(回包不带每用户态:未读、置顶、静音按 0 / 否)。失败按状态到种类一表抛 ChatSdkRequestError(如 404 ⇒ not_found、403 ⇒ forbidden),错误信封里的 code 原样带上
subConversations 找或建场景子会话:POST /api/v1/conversations/{parent}/subconversations(请求体 { context_key, title? }),父会话是与某成员的私聊时改发 POST /api/v1/conversations/dm/subconversations(请求体 { peer_member_id, context_key, title? };私聊由后端找或建,回包只含子会话)。回包里的子会话按上面私聊的口径换成包认识的形状。后端从凭据取 owner:已弃用的 owner 只在按父会话 id 时原样发出(另一个接口没有这个字段)。失败按状态到种类一表抛 ChatSdkRequestError,带后端码对应的那句话,例如 409 COMM_SUBCONVERSATION_LIMIT_REACHED(父会话下进行中的子会话已达上限)、403 SUBCONVERSATION_NOT_ENABLED(本组织还没开通)、400 COMM_INVALID_CONTEXT_KEY。会话列表每行另带 has_unread_subconversations
mentions 「@我」跳转:取未读 @提及(GET /api/v1/conversations/{id}/unread-mentions,is_mention_all 为真的记 "all",计数取 total_me / total_all,不受分页截断)、逐条标已读(POST …/{id}/mention-read,请求体只有 message_ids)、全部标已读(POST …/{id}/mention-read-all,不带请求体,范围由后端定)。非 2xx 抛 ChatSdkRequestError
profiles 名片取数:资料取 GET /api/v1/members/{id}(组织角色名作 subtitle,没有不给;主人、identity、agentOrigin(agent_origin)与 memberStatus(status)只在 Agent 上给,后两格只给 SDK 的会话头部用、不进名片;404 回 undefined),名下 Agent 取 GET /api/v1/members/{id}/owned-agents(模型名作 subtitle)。只交原值,缺省「成员」「未命名」由 SDK 补。要名片还得在 createChatHost 交 profileCardActions
workItems # 工作项候选(GET /api/v1/work-references):query 是查询串去掉首尾空白、为空不带;给了 projectId 才带 project_id;limit 恒 50;没有游标。Issue 的标签是 「项目名 / 标题」(缺项目名时只用标题),顺序原样。非 2xx 抛 ChatSdkRequestError
agentConfig Agent 模型配置:loadModelState 取 GET /api/v1/agents/{id}/model-config(蛇形折驼峰,apply_state 不认识按 ready;只对凭据失效照抛,其余取不到回 undefined),setModel 发 PATCH …/model-config(请求体只有 { model }),setModelVisibility 发 PATCH …/model-visibility(请求体只有 { visible }),写非 2xx 抛 ChatSdkRequestError。不另加超时
capabilityTags Agent 的能力标签:GET /api/v1/agent-profiles,member_id 重复参数(一次调用一次请求;适配器声明 maxBatchSize: 50,SDK 每次最多交 50 个)、带 include=capabilities,与 Agent 目录同一个读法;按 member_id 对号入座,不按位置。答复里没有的 Agent 不交(即没有标签);认不出 kind 或没有文本的标签丢掉
groupManagement 群管理六个方法都有:建群 POST /api/v1/conversations/groups(请求体 { name, member_ids, description? },描述为空串时不带,回 data.id);改资料 PATCH /api/v1/conversations/{id}(只带给了的 name / description);加人 POST …/{id}/members:batch-add(role 为 MEMBER)、移人 POST …/{id}/members:batch-remove,一个人也走批量端点,id 按去掉首尾空白后的值去重,交空表不发请求;退群 POST …/{id}/leave(指定继任者时带 new_owner_id),回包 conversation_deleted ⇒ dissolved、new_owner_id ⇒ newOwnerId;解散 DELETE /api/v1/conversations/{id}。批量端点整次回 200、逐人结果在回包里:每个没成的人的种类按那一行的状态(状态到种类),message 按那一行的 code 取句子(认不得就不带;AUTH_ORG_MEMBERSHIP_REQUIRED 说「该成员不在当前组织中」),后端那一行的原文不进 message。后端把无权、群不存在也写进每一行(403 / 404,码 COMM_ERROR):每一行都是同一个这样的原因时归一成整次失败,抛 ChatSdkRequestError;一次只移一个人、那人不在群里或角色不低于你时,也按整次失败报(同一个状态与码,分不出)。整次失败抛 ChatSdkRequestError(建群收到 403 AUTH_ORG_MEMBERSHIP_REQUIRED 说中性句,见错误)。退群在后端是幂等的:已不在群里、群不存在照样成功。写不重试;写成功后的刷新与「我已不在这条会话」由 createChatHost 做
conversationResources 会话里的图片、文件与链接:GET /api/v1/conversations/{id}/resources,kind(kinds 用逗号拼)、sender_id、since、until、query(去掉首尾空白)、cursor 给了且非空才带;limit 是正整数才带,超过 100 的按 100 发(后端拒超过 100 的 limit,这里与内存适配器一样按 100 取,不报错)。since / until 原样发:不是带时区的 RFC 3339 时间(纯日期、不带时区)的由后端回 422,抛 kind 为 validation 的 ChatSdkRequestError。游标列表信封里的行折成 ChatConversationResource(message_at ⇒ messageAt、url_host ⇒ host、link_text ⇒ title);没有 artifact_id 的图片 / 文件行、没有 url 的链接行、不认识 kind 的行丢掉。pagination.next_cursor 为空串、null 或缺(连 pagination 都没有)⇒ 没有 nextCursor。可见性与权限归服务端。非 2xx 抛 ChatSdkRequestError;signal 交给请求
messageSearch 在一条会话里搜消息:POST /api/v1/conversations/{id}/messages/search,请求体 { query, limit?, cursor? }(查询去掉首尾空白;空白查询不发请求、回空页;limit 同上,是正整数才带、超过 100 的按 100 发)。片段取第一条非空的高亮,<em> 标记折成 match: true 的段,其余一律当纯文本;没有高亮的命中用这条消息当前的正文、不带高亮。回包里已撤回或已删除的命中也丢掉;每条命中都仍可见、命中与摘要基于编辑后的当前正文(只匹配旧正文的不返回),都由服务端保证(它拿命中回查消息);适配器自己不拿片段比对正文。非 2xx 抛 ChatSdkRequestError;signal 交给请求
session 不提供:组织作用域的结束由宿主应用告诉 SDK(例如在自己的适配器上加 session)

OpenMaxChatConfig

interface OpenMaxChatConfig {
  baseUrl: string;
  wsUrl?: string;
  realtime?: "off";
  auth: OpenMaxAuth;
  agentActivity?: boolean;
  storage?: ChatSdkStorage;
  currentUser?: () => ChatSdkAdapterCurrentUser | undefined;
  workspaceId?: string;
  orgId?: string;
  instanceKey?: string;
  locale?: string | (() => string);
  ports?: ChatSdkPortOverrides;
  markdown?: ChatSdkMarkdownOptions | false;
}

createOpenMaxAdapter 和一行入口 createChatHost 共用的构造参数。没有内置默认后端:baseUrl 必填,包里不出现任何一套环境的地址,也不读环境变量。

字段 默认 说明
baseUrl 必填 REST 基址,不带 /api/v1;OpenMax 是 https://openmax.com。http(s):// 绝对地址,或以 / 开头的路径(如 /openmax-api),见下文路径写法
wsUrl 实时连接地址,OpenMax 是 wss://openmax.com/ws。ws(s):// 绝对地址,或以 / 开头的路径(如 /ws)。不从 baseUrl 推导
realtime 只有一个取值 "off":不建 WebSocket,别人发的消息不会自动出现。wsUrl 与 realtime: "off" 必须且只能给一个
auth 必填 凭据来源,见 OpenMaxAuth。只接受 token
agentActivity true Agent 执行过程,只读进度(实验性 · 过渡)。规划中的 Agent 运行能力落地时替换它。true:实时通道认 agent_activity 帧、messaging 解码 agent_run;false:两样都不做(连解码都不做),SDK 收不到任何运行相关的东西。realtime: "off" 时也默认 true:帧不来,回复上的摘要条照画。它是工厂选项,不是适配器成员;本包不读环境变量,开关由调用方给
storage "memory" 设备标识和宿主草稿、instanceScope.storage 存在哪。"memory" 时每次加载页面都是一台新设备(服务端的同步游标从新设备算起);"localStorage" 时设备标识存在键 cws:chat-sdk:device_id 下,不读写 cws:web:device_id,存储不可用或写了读不回时退回内存。设备标识持久(读到已有的、或写进去读得回)时,实时连接每收到一帧 sync 就回执(POST /api/v1/sync/ack),有 has_more 时先翻页(POST /api/v1/sync,最多 5 页);不持久时不回执、不翻页,每次连上服务端都重推收件箱最早的 100 条。要回执就传 "localStorage",回执和翻页要 messages:read_state:write、messages:sync:read 两个 scope,见已知缺口第 1 条realtime: "off" 时不建实时连接,也不算、不写设备标识
currentUser 宿主手上已有的当前用户,给了适配器就不再为「我」另发一次 GET /api/v1/me。适配器第一次要用「我」时读它(SDK 的 identity.me(),或建私聊);带 memberId 的原样用,并像取回来的一样在适配器生命周期里留着。回 undefined(或没有 memberId)⇒ 适配器自己请求 GET /api/v1/me,只发一次,要「我」的各处共用。适配器不核对组织:只回 orgId 那个组织的用户
workspaceId REST 请求与页面同源时带上 X-Workspace-ID;跨域、或拿不到页面的源(不在浏览器里)时不带。后端不读这个头,组织由 orgId 决定。可能改名或删除
orgId 每个 REST 请求带上 X-Org-ID,后端靠它定组织:用个人 API Key 时必须给(Key 不带组织,不给时会话列表回 401);本身带组织的会话令牌可不给。可能改名或删除
locale "zh-CN" 界面语言(主标签 en ⇒ 英文,其余中文)。适配器用它挑请求失败时 message 那句话的语言(见错误);给函数时每次失败现取,宿主换界面语言不必重建适配器。一行入口另把它交给 SDK 默认 i18n,同 ChatSdkAdapterHostConfig 的同名项;给的是函数时只取建宿主那一刻的值,默认 i18n 之后不跟着变,要跟着变给 ports.i18n
instanceKey、ports、markdown 宿主的设置,只有一行入口用,同 ChatSdkAdapterHostConfig 的同名项

构造时按下面的顺序检查,同时犯几条时报第一条,都同步抛 ChatSdkConfigError:auth.mode 不是 token(logto、cookie 不静默回退);getToken 不是函数;baseUrl 缺失,或既不是 http(s) 也不是以 / 开头的路径;wsUrl 给了,但既不是 ws(s) 也不是这样的路径;wsUrl 和 realtime: "off" 都没给;两个都给了。构造时只看写法,不解析地址、不碰 window。

路径写法

baseUrl / wsUrl 可以写成以 / 开头的路径,适合页面和后端经同源反向代理放在同一个源下的部署,例如 baseUrl: "/openmax-api"、wsUrl: "/openmax-ws"。

  • 什么时候解析:不在构造时,而在第一次用到时:baseUrl 在第一个 REST 请求时、wsUrl 在第一次建实时连接时。一律按 new URL(path, location.origin) 解析,不看 <base href>,也不看当前页面的路径;解析成功后记住,之后不再重算。wsUrl 的协议跟着页面:https: 页面得到 wss:,http: 页面得到 ws:,查询串保留。换票(POST /auth/ws-ticket)走 REST,跟着 baseUrl 解析。
  • 拿不到可用的源时:只看 location.origin 本身能不能用:在服务端(没有 window)、location.origin 是 "null"(about:blank、data:),或页面不是经 http(s) 提供的(file:、chrome-extension:、capacitor:)时,第一个请求以点名 baseUrl 的 ChatSdkConfigError reject;路径写法的 wsUrl 不建连、不换票、也不重连,经 sink.error 报一次 kind 为 unknown、code 为 ws_url_unresolved 的 ChatSdkError,它的 cause 是点名 wsUrl 的 ChatSdkConfigError(baseUrl 给了绝对地址时 REST 照常可用)。开发构建里另在控制台 console.error 一次(同一个宿主只一次),点名 wsUrl、说明原因与改法;生产构建不输出。先解析、后取令牌:这种情况下不调 getToken。REST 的失败不记住,之后在浏览器里再用照常解析;实时那一次放弃是终局的,要重建宿主。
  • 沙箱 iframe:按文档地址的源解析。没有 allow-same-origin 的沙箱帧,文档的源(window.origin)是 "null",但 location.origin 仍是它地址的 http(s) 源,所以路径照常解析、照常取令牌发请求;请求能不能成(带 Origin: null 的跨源请求)由服务端的 CORS 决定。
  • 协议相对写法不特判://host/api 按 URL 标准解析成页面协议下那台主机的绝对地址(https: 页面上是 https://host/api,wsUrl 再换成 wss:),也就是另一个源:跨源部署的要求(CORS、登记页面的源)照样适用,X-Workspace-ID 不发。/\host/api 按标准读法相同。
  • 不接受:不以 / 开头的相对写法(api、./api),在构造时抛。
  • 代理要转发什么:/openmax-api 这类路径与页面同源,workspaceId 对应的 X-Workspace-ID 照常发,代理要把它连同 Authorization、X-Org-ID 一起转给后端。wsUrl 前面的代理要能转发 WebSocket 升级;做不到时 wsUrl 给绝对地址。

设备标识(见上表 storage)同样在第一次建连时才取,同一个宿主里取一次就固定;存储键不变,升级后已存的值照用。所以在模块顶层建宿主时,服务端渲染阶段不会碰 window。

OpenMaxAuth

type OpenMaxAuth =
  | {
      mode: "logto";
    }
  | {
      mode: "cookie";
    }
  | {
      mode: "token";
      getToken: (options?: OpenMaxGetTokenOptions) => Promise<string | OpenMaxToken>;
    };

凭据从哪来。包不发凭据,只消费凭据:怎么续期由你负责。只实现了 token:logto、cookie 留在类型里,构造时抛错。

token 模式下,第一次要发请求时调一次 getToken() 并缓存;收到 401 时带 { refresh: true } 再问一次,用新令牌把那一发重发一次,见 OpenMaxGetTokenOptions 和错误 · 续期。改回 OpenMaxToken({ token, expiresAt })时,令牌在到期前就续,且只有「令牌已过期」的 401 才续。一次 getToken 调用 30 秒内没结果就按 timeout 失败(不算凭据失效),下一发请求或下一次重连会重新调它;超时那次之后才回来的结果不用。长期凭据(secret、私有 appkey)不要放进浏览器。

OpenMaxGetTokenOptions

interface OpenMaxGetTokenOptions {
  refresh?: boolean;
}

包问 getToken 时带的提示:

  • 不带参数:要一张令牌(第一次用到,或上次续期失败后重新取)。手上那张还能用就回那张。
  • { refresh: true }:手上那张刚被后端以 401 拒了,这时要真去续期(例如走一次 refresh token),回一张新的。回的还是被拒那张时,包照样重发一次,多半仍是 401,以 unauthorized 失败。同时(或先后)被拒的几发只这样问一次;一次请求最多问一次,不循环。

续不出令牌时,用抛什么来说明原因(两种参数下都一样):

  • 凭据失效、要重新登录:抛普通 Error,或回空串。那次调用以 unauthorized 失败,宿主调一次 onUnauthorized(没给时提示一次「登录已过期」),实时停止重连。
  • 续期没成、但凭据可能还好(续期接口断网、超时、5xx):抛 kind 为 network(或 timeout、unavailable 等)的 ChatSdkError。那次调用以这个种类失败,不调 onUnauthorized,实时照常退避重连,下一次 401 再续。裸的 TypeError、TimeoutError、AbortError 也分别当 network、timeout、cancelled。别把网络类失败报成凭据失效:回调若因此不处理,这一段失效的那一次就被占掉,之后真的凭据失效也不会再调。

不认这个参数的旧 getToken(async () => token)照样能用,只是 401 之后拿回的多半还是那张。

OpenMaxToken

interface OpenMaxToken {
  token: string;
  expiresAt: number | string;
}

getToken 除了回字符串,也可以回这个:令牌连同到期时间(expiresAt,epoch 毫秒或 ISO 8601 串)。给你的服务端替用户换来的短期令牌用。

  • 到期前就续。 请求要发出时离到期不到 60 秒(令牌寿命不到两分钟时,按它到手时寿命的一半算),先问一次 getToken({ refresh: true }) 再发,请求不会先吃 401 再重发。几个请求同时发现只问一次。检查发生在请求发出时,所以页面在后台挂了很久回来,第一个请求之前就会先续。这次续取失败而旧令牌还没到期时,照用旧的,下一个请求再试。
  • 实时连接交接、不断开。 同一时刻用新票开第二条连接,新的连上两秒后关掉旧的。两条都收到的推送只交一次,之后打开着的会话补一次。来不及交接时(例如后台标签页里定时器被推迟),服务端到期关掉旧连接,适配器换新令牌重连,与不给到期时间时一样。
  • 401 分开处理。 AUTH_TOKEN_EXPIRED ⇒ 问一次 getToken({ refresh: true })、重发一次。其它 401(令牌或它背后的 Key 被吊销)⇒ 不续、不重发:那次调用以 unauthorized 失败,调 onUnauthorized,实时不再重连。

到手时按页面时钟已经过期的令牌(页面时钟走快了),以及续回来还是同一张、或到期不比旧的晚的令牌,不提前续:一直用到后端回 AUTH_TOKEN_EXPIRED,所以不会「续了还快到期、再续」地循环。读不出来的 expiresAt 当没给。只回字符串时行为不变:不提前续,每个 401 续一次。

openMaxSharedRealtime

function openMaxSharedRealtime(source: OpenMaxFrameSource, options?: OpenMaxSharedRealtimeOptions): ChatSdkRealtime;

把宿主自己那条 OpenMax 实时连接收到的帧喂给 SDK,用来替换 createOpenMaxAdapter 返回值上的 realtime。帧的解码与翻译和 wsUrl 那条路是同一份,同一帧出的信号相同。

什么时候用:页面上已经有一条自己维护的 /ws 连接(换票、设备标识、断线重连、sync 回执都由它做),又要挂 SDK。这时还让适配器按 wsUrl 自己连,同一个页面就会开两条连接:两张票、两个设备标识、服务端每条推送发两遍,两套退避各自重连。没有自己的连接时照常给 wsUrl,不要用它。

import { createOpenMaxAdapter, openMaxSharedRealtime } from "@openmaxai/chat-openmax";

const base = createOpenMaxAdapter({ baseUrl, auth, realtime: "off" });
const adapter = { ...base, realtime: openMaxSharedRealtime(source) };
  • 不建 WebSocket、不换票、不发设备标识、不回执 sync,也不调 sink.error 和 sink.closed。凭据失效由宿主自己那条连接和它的出口处理,断开记录也由那条连接自己记。同一个浏览器里只能有一路 sync 回执,所以它永远不回执。
  • realtime.connect() 时才 subscribe,close() 时退订。同一个适配器先后交给几个宿主时,每次 connect 是一份独立的订阅,宿主 dispose() 后订阅者数回到原样。
  • connect() 先 subscribe 再查 isOpen()。已经开着 ⇒ 什么都不交:从订阅起每帧都收得到,没有要补的。还没开 ⇒ 它第一次 open() 交一声 connected。这次 connect() 见过一次打开之后,每次 open() 交恰好一声 reconnected(按适配器契约只表示「断过、又连上了」)。宿主那条连接自己失败过的尝试这里看不到,所以失败之后的第一次 open() 仍交 connected。
  • 帧不会交出 reconnected。宿主自己翻页拿到的 sync 事件,按 sync 帧的形状({ type: "sync", payload: { events } } 的 JSON 文本)交给 frame(),和连接推来的 sync 一样逐会话出 messages。
  • 不是 JSON 的文本、解不出的帧整帧丢掉,不抛。
  • connect() 同步返回、不抛:source.subscribe 抛错时这次订阅按没成处理,source.isOpen 抛错时按没开。close() 调几次都只退订一次。
  • 不按组织过滤:只把当前组织那条连接的帧交进来是 source 的事。

OpenMaxFrameSource

interface OpenMaxFrameSource {
  subscribe(listener: OpenMaxFrameListener): () => void;
  isOpen(): boolean;
}

宿主自己持有的那条连接。subscribe 登记一个订阅者、回退订函数:退订按引用撤掉这一个,调两次不出错;不重放登记之前到的帧,也不要在 subscribe 里同步回调订阅者(连接已开着时由 isOpen 说,SDK 自己补那一声 reconnected;真同步调了 open(),也只算那一声)。isOpen 回此刻连接开着没有,要问连接本身(例如 readyState === OPEN),不要靠关闭回调去维护一个布尔值:主动断开时关闭回调可能不来。

OpenMaxFrameListener

interface OpenMaxFrameListener {
  frame(raw: string): void;
  open(): void;
  catchUp?(onError?: (error: unknown) => void): void;
}

OpenMaxFrameSource 的订阅者。frame(raw) 每帧调一次,raw 是 WebSocket MessageEvent.data 的文本,不解码、不改;open() 在连接每次真正连上时调一次。catchUp()(可选、实验性,写成 listener.catchUp?.() 调)请 SDK 在没发生什么的时候把打开着的会话补一次,例如连接看着开着时的定时补拉、浏览器恢复联网。它交出 { kind: "catchUp" },不表示有新消息:标签不重排、不计入新消息、不重取会话列表;每个挂着的消息区按水位往后取一次,正在补的跳过。页面回到前台时不用调:消息区那时自己会补。传了 onError 时,挂着的消息区这次补失败了(请求被拒)会调它,每个失败调一次、带上各自的原因。定时调 catchUp 的宿主靠它退避,只该算值得退避的那几种(断网、超时、429、5xx):某一个会话的 403、404(例如用户已被移出的会话)说明不了服务端的状况,为它退避会拖慢其余所有会话的补拉。

OpenMaxSharedRealtimeOptions

interface OpenMaxSharedRealtimeOptions {
  agentActivity?: boolean;
}
字段 默认 说明
agentActivity true 认不认 agent_activity 帧,同 OpenMaxChatConfig 的 agentActivity。两处一般给同一个值