OpenMax
免费试用

版本与已知缺口

CHAT_OPENMAX_VERSION 与 KNOWN_GAPS_CHAT_OPENMAX:只对 OpenMax 成立的已知缺口。

版本与已知缺口

只对接 OpenMax 成立的已知缺口和包的版本。与后端无关的缺口在 @openmaxai/chat-sdk 的 KNOWN_GAPS_CHAT_SDK 里。状态和全部导出的索引见概览。

KNOWN_GAPS_CHAT_OPENMAX

const KNOWN_GAPS_CHAT_OPENMAX: readonly string[];

已知未处理的情况,按数组顺序:

  1. sync 回执(POST /api/v1/sync/ack)只在设备标识持久时发:storage 给 "localStorage",并且写进去读得回。默认 "memory"、存储不可用或写了读不回时,不回执也不翻页,服务端没有这台设备的游标,每次连上都从头推收件箱最早的 100 条(带 has_more),数量固定、不会涨,但每次都多出一批 messages 信号;未读数不受影响。持久也可能过期:Safari 无痕窗口关窗即清,跨站 iframe 里脚本写的存储最多保留 7 天(ITP),用户也可能清站点数据,这几种情况每次会在服务端多留一行不再活跃的游标(服务端不清理游标,游标没有 TTL)。回执要 messages:read_state:write、翻页要 messages:sync:read 两个 scope(chat 预设都有),自选 scope 的 API Key 缺了会收到 403,包吞掉,退回不回执。新设备第一次连上从 seq 0 起推,一次最多 600 条(1 帧加 5 页),收件箱大时要连几次才追平。
  2. 默认宿主的附件 PUT 直接打 prepare 回来的 upload_url,SDK 不做代理。upload_url 和嵌入页跨源时这一步会不会被 CORS 拦,未实测。
  3. 默认宿主的附件上传只在 <ConversationScope conversationId> 里可用:会话面没包这一层时附件入口不出现(limits 回 0)、attachments.start 直接 reject。包不包由你决定,SDK 判断不出「这里本该是一条会话」。
  4. 嵌入页和 baseUrl 跨源时,每个 REST 请求都带 Authorization(token 模式),浏览器必先发 CORS 预检(OPTIONS)。对端挡掉 OPTIONS 时连 GET /api/v1/me 都过不去,与上传无关;所以跨源部署要对整个 API 放行 CORS,不只 device_id 一处。
  5. 收到的附件地址(resolveUrls 回的 download_url)原样交出去,SDK 不做代理。download_url 和嵌入页跨源时图片和预览能不能显示,未实测。
  6. 实时的 message.updated 帧不带正文,消息区每收到一声都按 id 再取一次(GET …/conversations/{cid}/messages/{mid})。服务端会把自己的编辑推回给自己(含发起编辑的那台设备),所以自己每编辑一次也多取一次;取数发生在仓库按 change_seq 去重之前,接上改动日志之后这一次 GET 也还在。
  7. 编辑请求只带 content:不带结构化 @(契约与后端编辑接口都没有这一项),也不带 type、fallback_text;把图片消息改成纯文本后,消息的 type 和会话列表的预览文字仍是编辑前的。
  8. 一行写法(@openmaxai/chat-openmax/react 的 createChatHost(config))不收 onUnauthorized:类型上不收,JS 里给了建宿主时抛 ChatSdkConfigError。凭据失效时(401 后经 getToken({ refresh: true }) 续一次令牌、重发仍不行;续期因网络没成算 network 错误、不调回调),调用照旧抛 kind 为 unauthorized 的 ChatSdkRequestError,实时停止重连。SDK 经 attention.notify 提示一次「登录已过期」(没有「已登出」界面状态,宿主没接 attention 时用户什么都看不到),接入方拿不到回调去跳转登录。要回调改用 { adapter } 写法,见 React 入口。
  9. 一行写法同样不收 onEvent(给了建宿主时抛 ChatSdkConfigError),一行写法造的宿主没有事件出口,消息展示插件的 emit 什么都不做。要接事件改用 { adapter } 写法。
  10. 一行写法也不收 cards(给了建宿主时抛 ChatSdkConfigError),一行写法造的宿主上业务卡按钮不画(放行哪些业务操作没有地方交进来)。要接卡片能力改用 createChatHost({ adapter: createOpenMaxAdapter(config), cards: { isOperationAllowed } })。
  11. 一行写法也不收 profileCardActions(给了建宿主时抛 ChatSdkConfigError),一行写法造的宿主没有名片(消息头像、单聊顶部的头像与名字不可点)。要名片改用 { adapter } 写法,把 profileCardActions 交在那里。
  12. 回执关闭的会话(GET …/read-cursors 回 412;服务端只给单聊和群开回执)每打开一次都多发一次注定被拒的请求:包不先读会话上的 read_receipt_mode(会话列表的行不带这个字段)。被拒时不画回执、不报错,只是多一次往返。回执关闭的真实会话尚未在真实后端实测(只在把接口拦成 412 时测过)。回执在运行中被关掉(组织级开关)时,已取到的快照一直画到宿主的游标块被清空、重建宿主(再调一次 createChatHost)或页面刷新为止,这期间重新打开会话也不撤。游标块只在适配器的 session 报作用域结束(换组织、被移出、退出登录)时清空,而本包的适配器不提供 session(见 createOpenMaxAdapter)⇒ 一行写法,以及应用没在适配器上自己补 session 的 { adapter } 写法,换组织、被移出、退出登录都不清,快照留到重建宿主或页面刷新。
  13. # 工作项候选(workItems.search)只取一页:GET /api/v1/work-references 带 limit=50(服务端上限),后端没有游标,项目或命中超过 50 条时后面的看不到;查询串超过 100 个字符时服务端回 422,抛 ChatSdkRequestError,输入框不弹面板。
  14. Agent 执行过程(工厂选项 agentActivity,默认开;只读进度(实验性 · 过渡),规划中的 Agent 运行能力落地时替换它):agent_activity 帧只在实时连接连着时到,服务端不落库、不重放、没有快照,断线期间与建连之前的帧补不回来,打开会话不补拉进行中的 run;后端关掉这项功能时没有帧、回复上的 agent_run 也被剥掉,选项开着也什么都不画;帧按连接扇出,每条开着的连接各收一份。经 SDK 这条连接收帧尚未在真实后端实测。
  15. 实时连接被服务端以关闭码 4007(credential_revoked,凭据已吊销)关闭时,按凭据失效处理、不再重连。服务端对用短期令牌建的连接发 4007:Key 被吊销、轮换、全部吊销,以及用户被移出这个组织;令牌到期时发的是 4003,SDK 照常退避重连,换票遇 401 时续一次令牌。Key 吊销、轮换、全部吊销后,服务端约 1 秒内对已建的连接发 4007。被移出组织同样走 4007,实时一侧报 unauthorized(调 onUnauthorized,没给时提示「登录已过期」),而 REST 对同一情况回 403 AUTH_ORG_MEMBERSHIP_REQUIRED(forbidden),两边的种类不一致。经 SDK 这条连接收 4007、4003 尚未在真实后端实测。
  16. 换票被拒(403,如个人 API Key 没有换票的权限)后实时停止,经 sink.error 报一次 forbidden;但 SDK 对以 forbidden 放弃的连接不做任何展示(不调 onUnauthorized,不经 attention 提示,连接状态条还在规划中),界面上看不到「实时已停」,别人的新消息要刷新才出现。要知道这件事,得自己包一层 adapter.realtime.connect 接住 sink.error。

数组里每条是一段英文说明,可以直接画在页面上。

CHAT_OPENMAX_VERSION

const CHAT_OPENMAX_VERSION: string;

包的版本标识,与 @openmaxai/chat-sdk 的 CHAT_SDK_VERSION 同值:两个包共用一个版本号。

从 npm 装到的包里,它等于该包 package.json 的 version(打包时写入);直接用源码、或用未经发布打包的产物时是开发占位值,不对应任何发布版本。类型是 string,不是字面量类型。