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