k2-im 0.1.58 → 0.2.1

package/dist/chat-kit.d.ts

@@ -1,8 +1,8 @@
 /** 媒体业务类型：实现据此选对象存储逻辑桶；sticker 对应 app-sticker。 */
 type MediaKind = 'image' | 'video' | 'voice' | 'file' | 'sticker';
 
-/** 会话类型。P0 只用 direct / group；`robot` 是独立私聊 sibling，不得并入 direct。 */
-type ConversationType = 'direct' | 'group' | 'channel' | 'supergroup' | 'robot';
+/** 会话类型；各类型分别处理权限、收发和历史。supergroup 仅预留类型，尚未提供业务实现。 */
+type ConversationType = 'direct' | 'group' | 'channel' | 'supergroup' | 'robot' | 'customerService';
 /**
  * 会话复合身份；`conversationId` 只在对应 `conversationType` 的领域内唯一。
  *
@@ -39,8 +39,8 @@ interface ConversationDraft$1 {
     attachments: readonly [];
     updatedAt: number;
 }
-/** 消息内容类型。sticker=表情/贴图（BMessage contentType=7）；call=单聊通话记录（contentType=10）；transfer=转账（contentType=16）；gift=礼品/刮刮卡（contentType=17）；robot=机器人卡片（contentType=18）；miniProgram=小程序分享卡（contentType=22）；redPacket=红包卡（contentType=25）；game=小游戏（contentType=27）；liveRoom=直播间分享（contentType=30）；未知 wire 正文统一归一为 unknown。 */
-type MessageContentType = 'text' | 'system' | 'image' | 'video' | 'voice' | 'file' | 'sticker' | 'contact' | 'miniProgram' | 'game' | 'transfer' | 'gift' | 'call' | 'redPacket' | 'mediaAlbum' | 'filesAlbum' | 'robot' | 'liveRoom' | 'unknown';
+/** 消息内容类型。sticker=表情/贴图（BMessage contentType=7）；call=单聊通话记录（contentType=10）；transfer=转账（contentType=16）；gift=礼品/刮刮卡（contentType=17）；robot=机器人卡片（contentType=18）；miniProgram=小程序分享卡（contentType=22）；redPacket=红包卡（contentType=25）；game=小游戏（contentType=27）；liveRoom=直播间分享（contentType=30）；未知 wire 正文统一转换为 unknown。 */
+type MessageContentType = 'text' | 'system' | 'image' | 'video' | 'voice' | 'file' | 'sticker' | 'contact' | 'miniProgram' | 'game' | 'transfer' | 'gift' | 'call' | 'redPacket' | 'mediaAlbum' | 'filesAlbum' | 'robot' | 'liveRoom' | 'customerService' | 'unknown';
 /**
  * 发送态（客户端态）：消息从本地创建到服务端确认的生命周期。
  * `uploading` 仅媒体消息使用：文件上传阶段（uploading→pending→sending→sent）；
@@ -80,10 +80,10 @@ interface ImSystemMessageBody {
     pinnedMessageAction?: ImPinnedMessageAction;
 }
 /**
- * 会话「最后一条」的语义摘要（持久化、经字段级 lastMessageSummaryEqual 参与判等）：取代中文预览串作为语义承重。
- * `system` 分支直接持归一后的 ImSystemMessageBody（供 formatLastMessageSummary 复用 formatSystemMessage，selfId 渲染时传入）。
- * EXPRESSION 协议家族按 `imageType` 投影为 `gif` 或静态 `sticker`，供会话列表保留产品差异。
- * 迁移期与 lastMessagePreview 双写并存（阶段 4）；判等**禁比对象引用**（否则 hydrate 回读值/重算值每次新建对象即永不相等）。
+ * 会话最后一条消息的语义摘要，供存储和 im-i18n 展示使用。
+ * `system` 保存解析后的 ImSystemMessageBody，formatSystemMessage 在展示时接收 selfId。
+ * EXPRESSION 按 imageType 区分 gif 与静态 sticker。
+ * 与 lastMessagePreview 同时保存；变化检查逐字段调用 lastMessageSummaryEqual，不比较对象引用。
  */
 type LastMessageSummary = {
     kind: 'text';
@@ -279,7 +279,7 @@ interface ImVoiceBody {
     teaKey?: Uint8Array;
     /** 文件加密类型：0=跟随消息，1=不加密，3=完整 TEA（BMessage.fileEncryptType；语音与图片/视频同走完整 TEA）。 */
     fileEncryptType?: number;
-    /** 录音振幅波形（0-255）：仅发送端本地展示缓存（随消息落盘、刷新后仍可画波形），**不写入 BMessage**（协议无波形字段）。 */
+    /** 录音振幅波形（0-255）：仅发送端本地展示缓存（随消息写入本地存储、刷新后仍可画波形），**不写入 BMessage**（协议无波形字段）。 */
     waveform?: number[];
 }
 /**
@@ -386,7 +386,7 @@ interface ImRobotImageGroupModule {
 /**
  * 机器人卡片倒计时。
  *
- * `endTimeMs` 已归一为 epoch 毫秒；wire 秒/毫秒混用只在 mapper 转换，宿主不要再猜单位。
+ * `endTimeMs` 已转换为 epoch 毫秒；wire 秒/毫秒混用只在 mapper 转换，宿主不要再猜单位。
  */
 interface ImRobotCountdownModule {
     type: 'countdown';
@@ -479,10 +479,10 @@ interface ImGiftBody {
     benCount?: string;
     fissionNumber?: string;
 }
-/** 领域通话媒体类型；已从各端 wire 0/1 对调口径归一，宿主禁止再读 raw callType。 */
+/** 通话媒体类型；各端 wire 0/1 的不同含义已转换成统一业务值，宿主无需读取 raw callType。 */
 type ImCallKind = 'audio' | 'video';
 /**
- * 通话结束结果。Android 跨端同步把未接与取消都写成 callStatus=0，只能归一为 missed。
+ * 通话结束结果。Android 跨端同步把未接与取消都写成 callStatus=0，只能转换为 missed。
  * `unknown` 仅表示该端 status 数字无法识别，不得猜成 completed。
  */
 type ImCallOutcome = 'missed' | 'rejected' | 'cancelled' | 'completed' | 'busy' | 'no-permission' | 'interrupted' | 'unknown';
@@ -490,7 +490,7 @@ type ImCallOutcome = 'missed' | 'rejected' | 'cancelled' | 'completed' | 'busy'
  * 单聊通话记录正文（contentType==='call'，协议 BMessage.contentType=10）。
  *
  * @remarks JSON 在 BMessage.content。Android 本地 / Android 跨端同步 / iOS 三套字段名与 0/1 含义不同，
- * 只在 mapping/call-record-body 归一。记录由各端本地插入，不能当普通聊天发出。
+ * 仅由 mapping/call-record-body 转换成统一业务值。记录由各端本地插入，不能当普通聊天发出。
  */
 interface ImCallRecordBody {
     callKind: ImCallKind;
@@ -517,7 +517,7 @@ type ImRedPacketType = 1 | 2 | 3 | 4;
  * @remarks 字段来自 proto 72-79 + 复用 34/35/38/49。领域名 `packetId` 对应 wire `rad_packet_id`。
  * 金额保持 proto string，单位是否微单位未证实，禁止默认套转账 ×1e6。
  * HTTP 详情状态与本地「自己已领」属于宿主投影，不进本 DTO（status 39 / state 53 未裁定）。
- * 本阶段不提供 `sendRedPacket`；出站字段仅用于 codec 往返闭合。
+ * 当前不提供 `sendRedPacket`；出站字段仅用于 codec 往返闭合。
  */
 interface ImRedPacketBody {
     packetId: string;
@@ -537,7 +537,7 @@ interface ImRedPacketBody {
 type ImContactKind = 'individual' | 'group' | 'channel' | 'robot' | 'unknown';
 /**
  * 名片消息内容体（contentType==='contact'）。字段来自 BMessage contentType=8，但使用领域友好命名：
- * id/icon/name 分别归一为 targetId/avatar/displayName；visitCardKey 归一为 kind，未知值放 rawKind。
+ * id/icon/name 分别转换为 targetId/avatar/displayName；visitCardKey 转换为 kind，未知值放 rawKind。
  */
 interface ImContactBody {
     /** 被分享对象 id：个人 userId、普通群 groupId、频道 id 或机器人 id。 */
@@ -569,7 +569,7 @@ interface UnknownMessageBody {
  * 若干项共享消息级的撤回、已读、引用与转发语义。
  */
 interface ImMediaAlbumItem {
-    /** 该项是图片还是视频；由协议 `mediaType` 归一而来，未知取值的项在解析阶段已被丢弃。 */
+    /** 该项是图片还是视频；由协议 mediaType 转换，无法识别的项会在解析时丢弃。 */
     kind: 'image' | 'video';
     /** 远端地址。加密项也是这个地址，解密用本项自己的 `teaKey`。 */
     url: string;
@@ -651,8 +651,28 @@ interface ImLiveRoomBody {
     /** 点赞数十进制字符串，保持协议原文，不在 Core 换算。 */
     liveRoomLikes?: string;
 }
+/** 客服正文保留一条消息内的全部附件；图片和文件各自保持服务端顺序。 */
+interface ImCustomerServiceBody {
+    /** 原始文字；空白不被当作不存在。 */
+    text: string;
+    /** 图片直达地址，不套用普通消息的加密文件结构。 */
+    images: readonly string[];
+    /** 文件与名称、大小按协议数组索引配对，不创建伪消息 ID。 */
+    files: readonly ImCustomerServiceFile[];
+}
+/** 客服文件元数据。大小是服务端展示文字，不能据此认定下载完整。 */
+interface ImCustomerServiceFile {
+    /** 服务端给出的资源地址。 */
+    url: string;
+    /** 服务端名称；缺省时从 URL 最后一个路径片段提取。 */
+    name: string;
+    /** 可缺省的原始大小描述，例如 1.5MB，并非精确字节数。 */
+    sizeLabel?: string;
+}
 interface ImMessageBody {
-    /** P0 文本内容（明文，解密后的结果）。 */
+    /** 客服专用复合正文；不能直接作为普通消息发送。 */
+    customerService?: ImCustomerServiceBody;
+    /** 文本内容（明文，解密后的结果）。 */
     text?: string;
     /** contentType==='system' 时的结构化系统提示体（群通知；text 忽略）。 */
     system?: ImSystemMessageBody;
@@ -702,7 +722,7 @@ interface MentionRange {
     end: number;
 }
 /**
- * 群消息 @ 提及（Android 三写载体的归一解析）：`atAll`(MESGrpChat.nNotifyCount=-1)、`atUserIds`(sNotifyUsers 被 @ 成员，
+ * 群消息 @ 提及（Android 三写载体的统一解析）：`atAll`(MESGrpChat.nNotifyCount=-1)、`atUserIds`(sNotifyUsers 被 @ 成员，
  * 含正文 token 读边界补全)、`ranges`(extend.atRange，可选、仅诊断/兼容——展示**不依赖其坐标**)。正文 `body.text` 保留 `[userId]` token 原样（真相不变）；
  * **展示权威来源 = 正文 token + atUserIds/atAll**，由纯函数 `resolveMentionSegments` 还原为高亮段（含 @昵称/@所有人/@我），UI 不自行解析。
  */
@@ -724,21 +744,21 @@ type ImMessageFailureReason = 'timeout' | 'rejected' | 'encrypt_failed' | 'netwo
  */
 type ImFailureDisplayCode = 'media.empty' | 'media.noCrypto' | 'media.previewFailed' | 'media.encryptFailed' | 'media.resumeUnavailable' | 'media.cleanupUnconfirmed' | 'media.uploadFailed' | 'media.uploadTimeout' | 'media.cancelled' | 'media.invalidDuration' | 'media.uploadInterrupted' | 'media.contentTooLarge' | 'contactRequired' | 'messageRefused' | 'forbiddenOrLeft' | 'contentRejected' | 'groupDismissed' | 'groupUnavailable' | 'channelDismissed' | 'channelMuted' | 'channelNotMember' | 'channelAdminRequired' | 'conversationUnsupported' | 'sendCanceled' | 'sessionLoggedOut' | 'timeout' | 'network' | 'unknown';
 interface ImMessageFailure {
-    /** 归一后的错误码（来自 MESChatAck.errcode 或本地失败码，本地码用负值）。 */
+    /** 转换后的错误码（来自 MESChatAck.errcode 或本地失败码，本地码用负值）。 */
     code: number;
     /** 失败机器分类（重试 / fail-fast / 统计消费）。 */
     reason: ImMessageFailureReason;
-    /** 失败展示语义码（强类型）：UI 经 im-i18n 按 locale 渲染；缺省表示无专门展示码（UI 回退 message）。不参与去重判等。 */
+    /** 失败展示语义码：UI 经 im-i18n 按语言渲染，缺省时使用 message；不单独触发消息状态更新。 */
     displayCode?: ImFailureDisplayCode;
-    /** 展示模板参数（如未支持会话类型的 type）；不参与去重判等。 */
+    /** 展示模板参数（如未支持会话类型的 type）；不单独触发消息状态更新。 */
     params?: Record<string, string | number>;
     /** 媒体失败的媒体类型（图片/视频/语音/文件）：供 displayCode 为 media.* 时渲染 label。 */
     mediaKind?: MediaKind;
-    /** 后端原文 / 诊断兜底文案；仅诊断/展示兜底用，不参与去重判等（见 merge.failureEqual）。 */
+    /** 后端原文或诊断文案；没有专门展示码时用于展示，不单独触发消息状态更新（见 merge.failureEqual）。 */
     message?: string;
     /**
      * 是否可重试（false=业务级不可重试）：如 direct 非好友或 GROUP 不在群(0x8201)、内容为空/违规(0x8202)、群已解散(0x8315)→ UI 隐藏「重发」。
-     * 缺省（undefined）视为可重试（向后兼容）。由 code 决定（classifyAckFailure），故不参与去重判等（同 code 必同 retryable）。
+     * 缺省（undefined）视为可重试（向后兼容）。由 code 决定（classifyAckFailure），不单独触发消息状态更新。
      */
     retryable?: boolean;
 }
@@ -781,7 +801,7 @@ interface MediaTaskUpdate {
     failure?: ImMessageFailure;
 }
 interface ImMessageEncryption {
-    /** P0 true=消息密文链路, false=明文链路（encrypt=0）。 */
+    /** true=消息密文链路, false=明文链路（encrypt=0）。 */
     encrypted: boolean;
     /** 扩展：加密方案标识，默认 'rsa-tea'。 */
     scheme?: 'rsa-tea';
@@ -790,16 +810,16 @@ interface ImMessageEncryption {
 }
 /** 单条消息领域模型（§4.1）。主键为客户端生成的 id（无 serverId）。 */
 interface ImMessage {
-    /** P0 客户端生成的稳定消息 ID（UUID），同时作幂等键；刷新后保持。 */
+    /** 客户端生成的稳定消息 ID（UUID），同时作幂等键；刷新后保持。 */
     id: string;
-    /** P0 归一化会话 ID。 */
+    /** 消息所属会话的字符串 ID；必须结合 conversationType 使用。 */
     conversationId: string;
     conversationType: ConversationType;
-    /** P0 归一化发送者 ID。 */
+    /** 发送者的字符串用户 ID。 */
     senderId: string;
     contentType: MessageContentType;
     body: ImMessageBody;
-    /** P0 统一毫秒 number（本地创建时间，乐观渲染用）。 */
+    /** 统一毫秒 number（本地创建时间，乐观渲染用）。 */
     createdAt: number;
     /** SDK 内部排序键；有效服务端时间优先，ACK 后可以更新。宿主不解析它，消息身份始终使用 id。 */
     sortKey: string;
@@ -808,7 +828,7 @@ interface ImMessage {
     failure?: ImMessageFailure;
     /** 服务端回传的 epoch 毫秒时间；有效时用于正式排序与展示，createdAt 仍保留创建记录。 */
     serverTime?: number;
-    /** P0 默认 'unread'。 */
+    /** 默认 'unread'。 */
     receipt: MessageReceipt;
     /** 离线单聊服务端标记当前账号已在其它端读过；仅用于本地未读投影，不改变对端回执 receipt。 */
     readBySelf?: boolean;
@@ -841,7 +861,7 @@ interface ImMessage {
     /** 扩展位：后端新增语义先落这里，避免污染核心字段。 */
     extensions?: Record<string, unknown>;
     /**
-     * 诊断快照（§4.1 诊断口径）：后端下发的原始协议字段（已归一为可 JSON 序列化形态）。
+     * 诊断快照（§4.1 诊断口径）：后端下发的原始协议字段（已转换为可 JSON 序列化形态）。
      * 默认不填充，仅当映射开启 keepRaw 时附带，便于联调、与后端核对原始下发；不参与任何业务逻辑。
      */
     raw?: ImMessageRaw;
@@ -958,17 +978,17 @@ type ChannelSessionState = 'active' | 'guest' | 'left' | 'removed' | 'dismissed'
 interface ImSession {
     id: string;
     type: ConversationType;
-    /** P0 由映射层从用户/群资料补齐。 */
+    /** 由映射层从用户/群资料补齐。 */
     title: string;
     avatar?: string;
     /**
-     * 会话最后一条的预览串（**已收窄**，阶段 4c）：仅承载 text 消息的正文（供会话列表 previewSegments 解析 @/表情，需原始正文串）；
+     * 会话最后一条的预览串（**已收窄**）：仅承载 text 消息的正文（供会话列表 previewSegments 解析 @/表情，需原始正文串）；
      * 媒体 / 加密 / 系统 / 撤回一律空串——其语义改由 lastMessageSummary 承载、UI 经 im-i18n 渲染。旧盘遗留的中文占位在 hydrate / projectSession 重算时清空。
      */
     lastMessagePreview: string;
     /**
-     * 最后一条消息的语义摘要（持久化）：取代中文 lastMessagePreview 作为语义承重，UI 经 im-i18n 按 locale 渲染。
-     * 迁移期与 lastMessagePreview 双写并存（阶段 4）；判等用字段级 lastMessageSummaryEqual（禁比对象引用）。旧会话无此字段时 UI 回退 lastMessagePreview。
+     * 最后一条消息的语义摘要，持久保存并由 im-i18n 按语言生成文案。
+     * 与 lastMessagePreview 同时保存，变化检查使用逐字段比较；旧会话缺此字段时可使用 lastMessagePreview。
      */
     lastMessageSummary?: LastMessageSummary;
     /** 最后一条消息发送者 id（群会话列表预览「发送者名: 内容」前缀用；`'system'`=系统提示、==自己=我发的，前缀策略由宿主定）。 */
@@ -992,7 +1012,7 @@ interface ImSession {
      * 会话内容仍显示最新一条消息。收到别人 @我 +1、查看/已读该会话清零。投影自 ReadState.mentionUnreadCount，与 unreadCount 同源持久化。
      */
     mentionUnreadCount?: number;
-    /** P0 排序时间（毫秒 number）。 */
+    /** 排序时间（毫秒 number）。 */
     timestamp: number;
     /**
      * 用户手工添加的本地“稍后处理”提醒。
@@ -1008,7 +1028,7 @@ interface ImSession {
     topTime?: number;
     /**
      * 最新一条消息若为「己方且未完成发送」的态：'sending'（pending/uploading/sending 统一）/ 'failed'。
-     * 派生展示字段（随最新消息变化，会话列表据此显示发送中 loading / 失败图标）；运行期真相，不持久化（persistSession 落盘时剔除）。
+     * 派生展示字段（随最新消息变化，会话列表据此显示发送中 loading / 失败图标）；运行期真相，不持久化（persistSession 写入本地存储时剔除）。
      */
     lastMessageSendState?: 'sending' | 'failed';
     /**
@@ -1016,11 +1036,11 @@ interface ImSession {
      *
      * 只在自己发出且 `status='sent'` 时投影；发送中/失败、对端消息、撤回、全员删除和系统提示都不给。
      * `delivered` 与尚未回执一样投影为 `unread`；当前协议没有送达通知，不能把 `sent` 当作对端已收到。
-     * 该字段随最新消息变化，并随会话落盘，避免冷启动后
+     * 该字段随最新消息变化，并随会话写入本地存储，避免冷启动后
      * 因「盘中缺字段 / 内存有字段」反复广播；对端已读变化必须刷新会话行。
      */
     lastMessageReceipt?: 'unread' | 'read';
-    /** P0 我方已读游标（见 §4.3）。 */
+    /** 我方已读游标（见 §4.3）。 */
     readCursor?: string;
     /** 群受限状态（仅 group；来自 0x2204 群通知 side-effect）。缺省视为 'active'（可正常发送）。 */
     groupState?: GroupSessionState;
@@ -1038,11 +1058,11 @@ interface ImSession {
 interface ReadState {
     conversationId: string;
     /**
-     * 新写入必须携带的会话类型；可选仅用于读取 Phase 2 迁移前的旧盘记录。
-     * 旧记录在 storage migration 中按对应 session 回填，迁移完成后收紧为必填。
+     * 新写入必须携带会话类型；可选用于兼容迁移前的存储记录。
+     * storage migration 会根据对应 session 补齐旧记录。
      */
     conversationType?: ConversationType;
-    /** P0 我方已读到的位置（消息 id 或后端游标的归一表示）。 */
+    /** 当前账号已读到的位置，以消息 id 或后端游标表示。 */
     readCursor: string;
     /**
      * 已读游标消息的 sortKey（位置）持久化快照：重启后 readCursor 对应消息未必被 hydrate 到内存，
@@ -1076,12 +1096,12 @@ interface OutboxUpdate {
 }
 /** 发送队列项（§4.4）。id 复用对应 ImMessage.id 以保证重试幂等。 */
 interface OutboxMessage {
-    /** P0 == 对应 ImMessage.id（客户端生成，重试时复用以保证幂等）。 */
+    /** == 对应 ImMessage.id（客户端生成，重试时复用以保证幂等）。 */
     id: string;
     conversationId: string;
     conversationType: ConversationType;
     contentType: MessageContentType;
-    /** P0 待发送内容（明文；加密在发送管线内按 encryption 处理）。 */
+    /** 待发送内容（明文；加密在发送管线内按 encryption 处理）。 */
     body: ImMessageBody;
     /** 群 @ 提及（发送侧：宿主从输入框提取；正文 body.text 已含 [userId] token / @所有人 文字，本字段供群发送策略编码 sNotifyUsers/nNotifyCount/extend）。仅群 @ 消息有。 */
     mention?: ImMessageMention;
@@ -1095,7 +1115,7 @@ interface OutboxMessage {
     /**
      * 复发策略（生命周期 logout 语义）：`automatic`（默认，缺省视同）= onAuthenticated/断线重连时自动复发；
      * `manual` = 仅用户显式 retry 才发（logout 时把在途消息置 manual，避免退账号后下次登录无提示自动补发）。
-     * 持久化随账本落盘，故 logout(preserve)→重登后仍为 manual，不被自动复发；retry 会翻回 automatic。缺省（旧账本）按 automatic 处理（向后兼容）。
+     * 持久化随账本写入本地存储，故 logout(preserve)→重登后仍为 manual，不被自动复发；retry 会翻回 automatic。缺省（旧账本）按 automatic 处理（向后兼容）。
      */
     resumePolicy?: 'automatic' | 'manual';
 }
@@ -1115,7 +1135,7 @@ interface ContactRemarkPhone {
     countryCode: string;
     mobile: string;
 }
-/** 用户资料领域模型（§4.5）。由 ImProfilePort 拉取、映射层归一。 */
+/** 用户资料领域模型（§4.5）。由 ImProfilePort 拉取、映射层转换字段。 */
 interface UserProfile {
     id: string;
     /** 用户自设昵称（后端 `nick_name`）。 */
@@ -1140,7 +1160,7 @@ interface UserProfile {
     remarkPhones?: ContactRemarkPhone[];
     /** 扩展：消息加密公钥来源（§7 复用）。 */
     publicKey?: string;
-    /** 会话免打扰态（好友关系 `is_undisturb` 归一）：仅好友资料返回，供领域层回填 `ImSession.muted` 做多端/冷启动恢复；非好友无此字段（undefined，不覆盖本地）。 */
+    /** 会话免打扰态（好友关系 `is_undisturb` 转换为布尔值）：仅好友资料返回，供领域层回填 `ImSession.muted` 做多端/冷启动恢复；非好友无此字段（undefined，不覆盖本地）。 */
     muted?: boolean;
     extensions?: Record<string, unknown>;
 }
@@ -1156,11 +1176,11 @@ interface GroupProfile {
     verifyWay?: number;
     /** 普通群邀请码；仅 `verifyWay === 4` 时有业务意义。 */
     inviteCode?: string;
-    /** 群状态（后端 status，具体值语义待后端明确）：保留不丢弃，供「普通成员感知群解散」兜底（解散仅通知群主，Review F6）。 */
+    /** 群状态（后端 status，具体值语义待后端明确）：保留不丢弃，供「普通成员感知群解散」兜底（解散仅通知群主）。 */
     status?: number;
-    /** 当前用户是否在群（后端 is_ingroup：false=已不在群，被踢/退群的兜底禁发来源，Review F6）。 */
+    /** 当前用户是否在群（后端 is_ingroup：false=已不在群，被踢/退群的兜底禁发来源）。 */
     isInGroup?: boolean;
-    /** 当前用户对该群的免打扰态（`to_user.is_undisturb` 归一）：供领域层回填 `ImSession.muted` 恢复；缺省（undefined）表示后端未返回，不覆盖本地。 */
+    /** 当前用户对该群的免打扰态（`to_user.is_undisturb` 转换为布尔值）：供领域层回填 `ImSession.muted` 恢复；缺省（undefined）表示后端未返回，不覆盖本地。 */
     muted?: boolean;
     /** 扩展位：members[] 等明细留扩展。 */
     extensions?: Record<string, unknown>;
@@ -1272,9 +1292,9 @@ interface ChannelProfile {
     /** CHANNEL 独立访问限制事实；browser 新映射必须提供，legacy storage 可能缺失。 */
     accessSnapshot?: ChannelAccessSnapshot;
     muted?: boolean;
-    /** 服务端频道类型的归一业务值；不得用它把频道改路由到 `supergroup`。 */
+    /** 服务端频道类型转换后的业务值；不得用它把频道改路由到 `supergroup`。 */
     channelKind?: string;
-    /** 本地密钥缓存代际/服务端未来版本的非敏感标识；不承载 secret_key。 */
+    /** 本地密钥缓存操作编号/服务端未来版本的非敏感标识；不承载 secret_key。 */
     secretKeyVersion?: string;
     /** `/user_radio/list` 的资料增量版本；与 secretKeyVersion 无关。 */
     updateVersion?: string;
@@ -1304,7 +1324,7 @@ interface ChannelMemberPage {
 }
 /** CHANNEL @ 选择器返回的用户项；专用 UserInfo 协议不提供角色，不得写入 role-rich 成员缓存。 */
 interface ChannelMentionMember {
-    /** 归一化用户 ID；来自 `/user_radio/member/*` 的 `user_id`。 */
+    /** 用户 ID，以字符串表示；来自 `/user_radio/member/*` 的 `user_id`。 */
     userId: string;
     /** CHANNEL @ 面板展示名；按频道昵称、全局昵称、协议备用名、用户 ID 的顺序降级。 */
     displayName: string;
@@ -1337,7 +1357,7 @@ interface ImError {
  * 诊断日志钩子（§5.3，可选）：宿主注入以观察核心诊断（如 ACK 原始 errcode）。
  * core 不内置 console；不注入则不产生诊断输出。
  */
-/** 连接策略（§8.3）。P0 固定 'single'，'race'/'sequential' 留 P1。 */
+/** 当前连接策略固定为 single，只连接首个端点。 */
 type ConnectionStrategy = 'single' | 'race' | 'sequential';
 interface ImReconnectOptions {
     /** 退避基数毫秒，默认 1000。 */
@@ -1383,7 +1403,7 @@ interface ContactApplication {
     /** 申请人的产品展示 ID，例如服务端 `user_info.mid`。 */
     applicantDisplayId?: string;
     message: string;
-    /** 服务端时间戳归一后的 Unix 毫秒；源字段缺失时保持未知。 */
+    /** 服务端时间戳转换后的 Unix 毫秒；源字段缺失时保持未知。 */
     createdAt?: number;
 }
 /** 联系人申请页；分页耗尽依据原始 type=1 页，不依据产品聚合结果。 */
@@ -1439,7 +1459,7 @@ interface ApplicationTarget {
  * GROUP 申请/邀请 provider 的权威记录。
  *
  * @remarks `applicationId` 是审核命令参数，`groupId` 是会话身份，两者不可互换；actor/target
- * 是申请时快照，最终成员关系和群资料仍由各自领域 API 收敛。
+ * 是申请时快照，最终成员关系和群资料仍由各自领域 API 统一更新。
  */
 interface GroupApplication {
     applicationId: string;
@@ -1450,7 +1470,7 @@ interface GroupApplication {
     target: ApplicationTarget;
     /** 申请附言或邀请说明，服务端允许为空。 */
     message: string;
-    /** 服务端时间戳归一后的 Unix 毫秒；源字段缺失时保持未知。 */
+    /** 服务端时间戳转换后的 Unix 毫秒；源字段缺失时保持未知。 */
     createdAt?: number;
 }
 /** GROUP 申请页；分页耗尽依据原始 type=2 混合页。 */
@@ -1549,7 +1569,7 @@ interface ChannelJoinApplication {
     channelAvatar?: string;
     /** 申请人填写的入群说明，服务端允许为空。 */
     message: string;
-    /** 服务端创建时间归一为 Unix 毫秒；源字段缺失或非法时不提供。 */
+    /** 服务端创建时间转换为 Unix 毫秒；源字段缺失或非法时不提供。 */
     createdAt?: number;
 }
 /** CHANNEL 申请列表的页号 cursor 输入；cursor 是下一原始混合页页号。 */
@@ -1618,7 +1638,7 @@ interface ImChannelProfilePort {
     getProfile: (channelId: string, options?: {
         forceRefresh?: boolean;
     }) => Promise<ChannelProfile | null>;
-    /** 清空 CHANNEL profile 内存缓存并作废旧请求写回；与 GROUP profile 保持 sibling。 */
+    /** 清空 CHANNEL profile 内存缓存，并阻止旧请求写回；与 GROUP profile 保持 sibling。 */
     clearCache?: () => void;
 }
 /** CHANNEL 成员查询。cursor 是频道成员接口的不透明游标。 */
@@ -1631,7 +1651,7 @@ interface ChannelMemberPageQuery {
 }
 /** CHANNEL 成员读取 capability；分页列表与当前消息窗口的稀疏批量读取共用同一独立 adapter。 */
 interface ImChannelMemberPort {
-    /** hydrate 有界公共快照；快照新鲜时不回源，过期时按完整页重建约 200 人。 */
+    /** hydrate 有界公共快照；快照新鲜时不重新请求服务端，过期时按完整页重建约 200 人。 */
     prefetchMembers?: (channelId: string) => Promise<void>;
     /** 只读取公共快照或其本地直接/拼音搜索结果；允许返回过期快照供 UI 先显，不发 HTTP。 */
     getCachedMembers?: (input: {
@@ -1655,9 +1675,9 @@ interface ImChannelMemberPort {
     getMembersByIds: (channelId: string, userIds: readonly string[], options?: {
         forceRefresh?: boolean;
     }) => Promise<ChannelMember[]>;
-    /** 作废频道成员缓存代际；旧请求可兑现原调用方，但不得写回当前缓存。 */
+    /** 使频道成员缓存失效；旧请求可以返回原调用方，但不得写回当前缓存。 */
     invalidateChannelMembers: (channelId: string) => Promise<void>;
-    /** 清空全部 CHANNEL role-rich 成员内存缓存并作废旧请求写回；持久层由 storage 分类清理统一处理。 */
+    /** 清空全部 CHANNEL role-rich 成员内存缓存，并阻止旧请求写回；持久层由 storage 分类清理统一处理。 */
     clearCache?: () => void;
 }
 /** CHANNEL @ 专用成员页查询；不得复用 role-rich 管理列表的 query/response 语义。 */
@@ -1741,10 +1761,9 @@ interface TransportEvents {
 interface TransportPort {
     readonly state: TransportState;
     /**
-     * 连接候选地址数组（P0 实现只连 endpoints[0]，多 host 竞速 P1）。
-     * 契约：实现必须保证——调用 connect() 前若存在旧连接，先完整关闭再建立新连接（幂等再连接）；
-     * 据此连接层在重连/网络恢复时可直接调用，不会出现新旧连接并存（满足「至多一个活跃 transport」）。
-     * 该清理契约由 @k2/im-browser 的 WsTransport 实现并锁测（切片 04）。
+     * 候选连接地址数组；当前实现仅连接 endpoints[0]。
+     * 再次 connect() 时必须先关闭旧连接，保证任一时刻至多存在一个活跃传输连接。
+     * @k2/im-browser 的 WsTransport 实现该约定。
      */
     connect: (endpoints: TransportEndpoint[], options?: TransportConnectOptions) => Promise<void>;
     /** 发送一帧（已编码字节）。 */
@@ -1755,7 +1774,7 @@ interface TransportPort {
 }
 
 interface ImEndpointProvider {
-    /** WS 候选地址。P0 返回单元素数组；后端下发多 host 时返回多元素。 */
+    /** WS 候选地址。返回单元素数组；后端下发多 host 时返回多元素。 */
     getEndpoints: () => Promise<TransportEndpoint[]>;
     /** CM Protobuf HTTP 基址。 */
     getCmHttpBaseUrl: () => Promise<string>;
@@ -1944,7 +1963,7 @@ interface ImProfilePort {
     getGroupProfile: (groupId: string, opts?: {
         forceRefresh?: boolean;
     }) => Promise<GroupProfile | null>;
-    /** 清空实现持有的 user/GROUP profile/member 内存缓存并作废旧请求写回；无缓存的实现可省略。 */
+    /** 清空实现持有的 user/GROUP profile/member 内存缓存，并阻止旧请求写回；无缓存的实现可省略。 */
     clearCache?: () => void;
 }
 
@@ -2079,53 +2098,49 @@ interface ImDecryptRecoveryRecord {
     createdAt: number;
 }
 /**
- * 持久化用户资料（O3）：领域 `UserProfile` + 落盘时间戳。跨刷新持久化以消除群历史发送者「占位→回填」闪动。
+ * 持久化用户资料：领域 `UserProfile` + 写入本地存储时间戳。跨刷新持久化以消除群历史发送者「占位→回填」闪动。
  * 分字段存（remark/nickname/avatar），展示名优先级在读取侧算，避免固化合并结果。
  */
 interface StoredUserProfile extends UserProfile {
-    /** 落盘/刷新时间（毫秒），供 TTL 过期判断。 */
+    /** 写入本地存储/刷新时间（毫秒），供 TTL 过期判断。 */
     updatedAt: number;
 }
 /**
- * 持久化群成员项（O3）：群内昵称 + 预留角色/加入方式。
- * 【前瞻·P-C】`roleId`/`joinType` 供后续「群成员列表展示」复用同一缓存，第一版可空；头像不在此存（走 userProfiles，避免重复）。
+ * 持久化群成员项：群内昵称 + 预留角色/加入方式。
+ * roleId/joinType 供群成员列表展示，可缺省；头像保存在 userProfiles，避免重复存储。
  */
 interface StoredGroupMember {
     userId: string;
     /** 群内昵称（展示名优先级第 2 级，仅次于好友备注）。 */
     groupNick: string;
-    /** 【前瞻·P-C】成员角色 roleId（1 普通 / 9 管理员 / 10 群主）；第一版可空。 */
+    /** 成员角色 roleId（1 普通 / 9 管理员 / 10 群主）；响应缺少时可省略。 */
     roleId?: number;
-    /** 【前瞻·P-C】加入方式 joinType（0 退群 / 1 主动 / 2 邀请 / 3 群主）；第一版可空。 */
+    /** 加入方式 joinType（0 退群 / 1 主动 / 2 邀请 / 3 群主）；响应缺少时可省略。 */
     joinType?: number;
 }
 /**
- * 持久化群成员列表（O3，按 groupId 存整份）：含增量版本与落盘时间。
- * 【前瞻·P-A】`updateVersion` 供二期增量拉（`/user_group/user/list` update_version），第一版全量、可空。
- * 【前瞻·P-B】结构对普通群/超级群通用；超级群海量成员按需 per-sender 填充由各会话类型策略决定，store 不感知类型。
+ * 持久保存群成员列表，按 groupId 保存整份数据，同时记录 updateVersion 与更新时间。
+ * 增量响应由资料适配层合并后写入；存储层不解释成员变更。
  */
 interface StoredGroupMemberList {
     groupId: string;
     members: StoredGroupMember[];
-    /** 【前瞻·P-A】增量版本（update_version）；第一版全量、可空。 */
+    /** 成员列表增量版本 update_version；服务端未返回时可省略。 */
     updateVersion?: number;
-    /** 落盘/刷新时间（毫秒），供 TTL 过期判断。 */
+    /** 写入本地存储/刷新时间（毫秒），供 TTL 过期判断。 */
     updatedAt: number;
 }
 /**
- * 持久化群资料（群设置面板 · 群主标识）：领域 `GroupProfile`（含 `ownerId`/name/avatar/memberCount）+ 落盘时间。
- * 主用途：**受限群**（被踢/退群/解散）只读本地时，从本地 `ownerId` 标出群主——受限群不调群资料接口（后端拒绝被移出用户），
- * 故须在正常态把群主信息落盘。
- * 【前瞻·P-B】结构对普通群/超级群通用（群主体系 `roleId=10` 两类群共用）；超级群特有字段（返佣/游客/管理员）由各会话类型
- * 策略在 `extensions` 扩展，store 不感知类型——新增群类型走 sibling 策略填充，不改本结构语义。
+ * 持久保存普通群资料，包括群主 ownerId、名称、头像、成员数和更新时间。
+ * 被踢、退群或解散后无法访问远端群资料时，产品仍可读取此前保存的群主标识。
  */
 interface StoredGroupProfile extends GroupProfile {
-    /** 落盘/刷新时间（毫秒），供 TTL 过期判断。 */
+    /** 写入本地存储/刷新时间（毫秒），供 TTL 过期判断。 */
     updatedAt: number;
 }
 /** CHANNEL 资料的账号级持久化副本；不得包含 `secret_key`。 */
 interface StoredChannelProfile extends ChannelProfile {
-    /** 落盘/刷新时间（毫秒），供后续资料 TTL 与诊断使用。 */
+    /** 写入本地存储/刷新时间（毫秒），供后续资料 TTL 与诊断使用。 */
     updatedAt: number;
 }
 /** CHANNEL 稀疏成员缓存项；按 `{channelId,userId}` 存储，不允许把整频道成员全量塞入单条记录。 */
@@ -2175,7 +2190,7 @@ type StoredConversationBackground = {
  * 本地存储端口（DB 无关、异步、可测试）。面向消息/会话/已读/发送账本/元数据等领域实体。
  *
  * 生命周期：宿主（SDK）在拿到登录 userId 后先 `open({ namespace: userId })`（幂等，内部跑 schema 迁移），
- * 再由 domainState `hydrate()` 回读；登出/切账号时 `close()`。所有写入源自 domainState 唯一收敛入口，
+ * 再由 domainState `hydrate()` 回读；登出/切账号时 `close()`。所有写入源自 domainState 统一更新入口，
  * 失败经 `error` 事件（scope:'storage'）暴露、不静默吞、不阻塞内存主流程。
  */
 interface ImStoragePort {
@@ -2191,7 +2206,7 @@ interface ImStoragePort {
     /** 关闭库句柄（登出/切账号）。 */
     close: () => Promise<void>;
     /**
-     * 只清当前已打开账号的可重建缓存；messages/sessions/read/drafts/outbox/pinned/tombstone/sync meta 等 durable 数据必须保留。
+     * 只清当前已打开账号的可重建缓存；messages/sessions/read/drafts/outbox/pinned/删除标记/sync meta 等 durable 数据必须保留。
      * 自定义 adapter 可省略；产品清理入口检测缺失后显式拒绝，不能伪装成功。
      */
     clearRebuildableCaches?: () => Promise<void>;
@@ -2244,7 +2259,7 @@ interface ImStoragePort {
     deleteConversationDecryptRecoveries?: (conversation: ConversationRef) => Promise<void>;
     /** 全量会话（hydrate 用）。 */
     getSessions: () => Promise<ImSession[]>;
-    /** 批量落盘会话（按 id 覆盖写）。 */
+    /** 批量写入本地存储会话（按 id 覆盖写）。 */
     saveSessions: (sessions: readonly ImSession[]) => Promise<void>;
     /** 删除单会话行（删除会话用）。 */
     deleteSession: (conversation: ImStorageConversation) => Promise<void>;
@@ -2262,7 +2277,7 @@ interface ImStoragePort {
     clearConversationHistory?: (conversation: ConversationRef, nextSession?: ImSession, nextReadState?: ReadState) => Promise<void>;
     /** 全量已读态（hydrate 用）。 */
     getReadStates: () => Promise<ReadState[]>;
-    /** 落盘单条已读态（按 conversationId 覆盖写）。 */
+    /** 写入本地存储单条已读态（按 conversationId 覆盖写）。 */
     saveReadState: (state: ReadState) => Promise<void>;
     /** 全量读取当前账号草稿，供账号 runtime hydrate。 */
     getDrafts: () => Promise<ConversationDraft$1[]>;
@@ -2284,7 +2299,7 @@ interface ImStoragePort {
     deleteDefaultConversationBackground?: () => Promise<void>;
     /** 全量在途发送账本（回读用）。 */
     getOutbox: () => Promise<OutboxMessage[]>;
-    /** 落盘/更新单条 Outbox（按 id 覆盖写）。 */
+    /** 写入本地存储/更新单条 Outbox（按 id 覆盖写）。 */
     saveOutboxMessage: (message: OutboxMessage) => Promise<void>;
     /** 出队删除单条 Outbox（sent 后）。 */
     removeOutboxMessage: (id: string) => Promise<void>;
@@ -2296,15 +2311,15 @@ interface ImStoragePort {
     removePinnedMessage: (conversation: ImStorageConversation) => Promise<void>;
     /** 按 userId 取持久化用户资料（含 updatedAt 供 TTL 判断）；无则 null。best-effort，失败降级不阻塞主流程。 */
     getUserProfile: (userId: string) => Promise<StoredUserProfile | null>;
-    /** 落盘用户资料（按 userId 覆盖写）。 */
+    /** 写入本地存储用户资料（按 userId 覆盖写）。 */
     saveUserProfile: (profile: StoredUserProfile) => Promise<void>;
     /** 按 groupId 取持久化群成员列表（含 updateVersion/updatedAt）；无则 null。 */
     getGroupMembers: (groupId: string) => Promise<StoredGroupMemberList | null>;
-    /** 落盘群成员列表（按 groupId 覆盖写；第一版全量重写，二期按 updateVersion 增量合并）。 */
+    /** 按 groupId 保存完整群成员列表；增量响应应由调用方先合并。 */
     saveGroupMembers: (list: StoredGroupMemberList) => Promise<void>;
     /** 按 groupId 取持久化群资料（含 ownerId/updatedAt）；无则 null。供受限群本地标群主（受限群不调群资料接口）。 */
     getGroupProfile: (groupId: string) => Promise<StoredGroupProfile | null>;
-    /** 落盘群资料（按 id 覆盖写）。 */
+    /** 写入本地存储群资料（按 id 覆盖写）。 */
     saveGroupProfile: (profile: StoredGroupProfile) => Promise<void>;
     /** 按 channelId 读取资料；无则 null。 */
     getChannelProfile: (channelId: string) => Promise<StoredChannelProfile | null>;
@@ -2736,7 +2751,7 @@ interface ImGroupCallMeetingSnapshot {
  * 根据 CHANNEL 角色、生命周期和禁言事实计算稳定访问能力。
  *
  * 这是无副作用的权限投影：输入来自权威 profile/session，输出供发送和 UI 预检使用；服务端仍做最终
- * 权限裁决。未知或冲突状态不会借 GROUP 权限兜底，而是收敛到受限能力与明确原因。
+ * 权限裁决。未知或冲突状态不会借 GROUP 权限兜底，而是转换为受限能力与明确原因。
  */
 
 /** CHANNEL 有效访问解析入参；`nowMs` 显式传入，使 hydrate、发送门禁与 Web 时钟使用同一纯逻辑。 */
@@ -2966,16 +2981,16 @@ interface GroupMemberItem {
 interface ProfileHttpAdapterDeps {
     /** 宿主注入的协议客户端（如 Nuxt `$clientApi`）；本适配作为调用方走 core JSON 链路拉资料。 */
     client: ApiProtocolClient;
-    /** 端类型 clientType（Web/H5=2）：透传给群资料/成员接口写 `Client-type` header，对齐后端全链路一致建议（Review F5）。缺省不带。 */
+    /** 端类型 clientType（Web/H5=2）：透传给群资料/成员接口写 `Client-type` header，对齐后端全链路一致建议。缺省不带。 */
     clientType?: number;
     /**
-     * 本地持久化端口（O3）：注入后 `getUserProfile`/`getGroupMemberNames` 走三级缓存（内存→持久化→HTTP），跨刷新消除群历史发送者「占位→回填」闪动。
+     * 本地持久化端口：注入后 `getUserProfile`/`getGroupMemberNames` 走三级缓存（内存→持久化→HTTP），跨刷新消除群历史发送者「占位→回填」闪动。
      * 只用 profile/member 四方法；**缺省 = 纯内存**（向后兼容）。storage 未 open / 读写异常时自动**降级 HTTP-only**（不阻塞不报错，符合 storage=downstream 原则）。
      * open 时序：与 SDK 共享同一 storage 实例，SDK `connect()` 统一 `open(namespace=userId)`；本适配读写前 open 未完成即降级。
      */
     storage?: Pick<ImStoragePort, 'getUserProfile' | 'saveUserProfile' | 'getGroupMembers' | 'saveGroupMembers' | 'getGroupProfile' | 'saveGroupProfile'>;
 }
-/** 群成员昵称提供者（createProfileHttpAdapter 在 ImProfilePort 之外附加，切片13/P1）：供宿主解析群消息发送者展示名（群内昵称优先级由宿主决定；Android 为好友备注 > 群内昵称 > 全局昵称）。 */
+/** 群成员昵称接口，作为 ImProfilePort 的补充；提供群消息发送者的群内昵称，最终展示优先级由调用方决定。 */
 interface GroupMemberNameProvider {
     /** 取群内成员昵称映射（userId → 群内昵称，空昵称成员不含）；空/失败 → null（调用方回退用户资料名）。缓存 + 同 id 去抖 + forceRefresh。 */
     getGroupMemberNames: (groupId: string, opts?: {
@@ -2985,30 +3000,38 @@ interface GroupMemberNameProvider {
     listGroupMembers: (groupId: string, opts?: {
         forceRefresh?: boolean;
     }) => Promise<GroupMemberItem[] | null>;
-    /** O3 prewarm（Review F1/三轮）：仅从内存+持久化读用户资料（**不回源 HTTP**），命中返回 `{ value, stale }`、未命中 null；`stale`=持久化过期。供进会话前首屏预热+据 stale 后台刷新。 */
+    /** 仅读取内存或本地用户资料，不发 HTTP 请求；命中返回 { value, stale }，未命中返回 null，stale 表示本地记录已过期。 */
     peekUserProfile: (userId: string) => Promise<{
         value: UserProfile;
         stale: boolean;
     } | null>;
-    /** O3 prewarm（Review F1/三轮）：仅从内存+持久化读群成员昵称（不回源 HTTP），命中 `{ value, stale }`、未命中 null。 */
+    /** 仅读取内存或本地的群成员昵称，不发 HTTP 请求；命中返回 { value, stale }，未命中返回 null。 */
     peekGroupMemberNames: (groupId: string) => Promise<{
         value: Record<string, string>;
         stale: boolean;
     } | null>;
-    /** O3 prewarm：仅从内存+持久化读**有序成员列表**（不回源 HTTP），命中 `{ value, stale }`、未命中 null。供群设置面板打开时先本地秒显。 */
+    /** 仅读取内存或本地的有序群成员列表，不发 HTTP 请求；命中返回 { value, stale }，供面板先展示已有内容。 */
     peekGroupMembers: (groupId: string) => Promise<{
         value: GroupMemberItem[];
         stale: boolean;
     } | null>;
-    /** O3 prewarm：仅从内存+持久化读群资料（不回源 HTTP），命中 `{ value, stale }`、未命中 null。供受限群本地标群主（ownerId）。 */
+    /** 仅读取内存或本地群资料，不发 HTTP 请求；命中返回 { value, stale }，供受限群展示已缓存的群主等信息。 */
     peekGroupProfile: (groupId: string) => Promise<{
         value: GroupProfile;
         stale: boolean;
     } | null>;
 }
-/** 创建用户 / 群资料 HTTP 适配（实现 ImProfilePort + 群成员昵称）：编排 requests/ 原子请求 + 回退 + 缓存 + 归一。 */
+/** 创建用户 / 群资料 HTTP 适配（实现 ImProfilePort + 群成员昵称）：组合 requests/ 请求、回退、缓存和字段转换。 */
 declare function createProfileHttpAdapter(deps: ProfileHttpAdapterDeps): ImProfilePort & GroupMemberNameProvider;
 
+/** 客服号公开展示资料；不携带后台发送者身份或网络路由参数。 */
+interface CustomerServiceProfile {
+    /** 当前语言的客服名称。 */
+    displayName: string;
+    /** 当前语言的头像地址；服务端未配置时为空。 */
+    avatarUrl: string;
+}
+
 /** 服务端对入群请求的最终裁决：已入群，或已提交并等待管理员审核。 */
 type MembershipJoinOutcome = 'joined' | 'waiting';
 /** Browser adapter 暴露给 SDK 的稳定入群结果，不携带具体 HTTP 响应结构。 */
@@ -3017,7 +3040,7 @@ interface MembershipJoinResult {
     outcome: MembershipJoinOutcome;
 }
 
-/** 服务端按逻辑桶签发的 S3 临时上传凭证（已归一为 SDK 合同字段）。 */
+/** 服务端按逻辑桶签发的 S3 临时上传凭证（已转换为 SDK 合同字段）。 */
 interface MediaUploadCredentials {
     /** STS access key id（服务端字段 `access_key_id`）。 */
     accessKeyId: string;
@@ -3033,7 +3056,7 @@ interface MediaUploadCredentials {
     region: string;
     /** 对象 key 前缀；STS 策略只允许写该前缀下的对象，SDK 生成的 key 必须以它开头。 */
     keyPrefix?: string;
-    /** 公开访问域名（已归一为带 scheme、无尾斜杠）；写进消息体的媒体 URL 以它为准。 */
+    /** 公开访问域名（已转换为带 scheme、无尾斜杠）；写进消息体的媒体 URL 以它为准。 */
     dnsPoint: string;
     /** 服务端身份标识；SDK 不使用，仅原样透出供宿主排查。 */
     identityId?: string;
@@ -3488,7 +3511,7 @@ interface MentionCandidatePage {
 /**
  * CHANNEL role-free @候选产品 sibling。
  *
- * @remarks list/search 使用独立缓存与 token 上下文；token 只在创建它的账号 runtime、查询类型和频道代际内有效。
+ * @remarks list/search 使用独立缓存与 token 上下文；token 只在创建它的账号 runtime、查询类型和频道缓存版本号内有效。
  * 本 API 不读取 role-rich 成员 provider，也不包含已退场的 @消息索引/定位能力。
  * @example
  * ```ts
@@ -3502,13 +3525,13 @@ interface ImChannelMentionApi {
     peekFirstPage: (channel: ConversationRef<'channel'>) => MentionCandidatePage | null;
     /** 从已 hydrate 的常用候选快照做同步直接文本过滤；不发远端搜索请求。 */
     peekSearchCandidates: (channel: ConversationRef<'channel'>, keyword: string) => readonly MentionCandidate[];
-    /** hydrate 持久快照并返回本地首页或直接/拼音搜索结果；cache miss 返回 null，绝不回源。 */
+    /** hydrate 持久快照并返回本地首页或直接/拼音搜索结果；cache miss 返回 null，绝不请求服务端。 */
     getCachedPage: (channel: ConversationRef<'channel'>, keyword?: string) => Promise<MentionCandidatePage | null>;
     /** hydrate 持久快照，并在缺失/过期时按完整页预热约 200 人；同频道在途任务复用。 */
     prefetchFirstPage: (channel: ConversationRef<'channel'>) => Promise<void>;
     /** 强制从专用 mention provider 重建约 200 人常用候选快照。 */
     refreshFirstPage: (channel: ConversationRef<'channel'>) => Promise<MentionCandidatePage>;
-    /** 读取常用候选快照；内存 miss 时先读持久层，均未命中才回源。 */
+    /** 读取常用候选；内存未命中时先读本地存储，两处都没有才查询服务端。 */
     listFirstPage: (channel: ConversationRef<'channel'>) => Promise<MentionCandidatePage>;
     /** 使用 list 页产生的 token 继续分页；search token 会被拒绝。 */
     listNextPage: (pageToken: ImPageToken) => Promise<MentionCandidatePage>;
@@ -3567,7 +3590,7 @@ interface ImDirectorySearchApi {
     search: (keyword: string) => Promise<ImDirectorySearchResult>;
 }
 
-/** 回源失败的原因与能否重试。 */
+/** 服务端消息查询失败的原因，以及是否允许重试。 */
 interface MessagesByIdFailure {
     /**
      * 能否稍后重试。
@@ -3579,7 +3602,10 @@ interface MessagesByIdFailure {
     /** 原始错误，供诊断与上报。 */
     error: unknown;
 }
-/** 回源的汇总结果。三组 id 互不重叠，合起来覆盖调用方传入的全部有效 id。 */
+/**
+ * 服务端消息查询汇总。三组 ID 互不重叠，合起来覆盖调用方传入的全部有效 ID。
+ * @template TMessage 调用方需要的消息展示类型，由 projectMessage 从领域消息转换得到。
+ */
 interface ImMessagesByIdResult<TMessage> {
     /** 成功取回的消息。已经进了本地历史，后续本地查询就能命中。 */
     readonly messages: readonly TMessage[];
@@ -3601,7 +3627,7 @@ interface ImMessagesByIdResult<TMessage> {
  * SDK 内部 CHANNEL sibling：装配资料、成员、申请、置顶、历史限制与通知修复能力。
  *
  * 所有入口都要求精确 CHANNEL 身份，并把协议 I/O 结果提交到当前账号的同一 DomainState；不会复用
- * GROUP 端口或为 `supergroup` fallback。运行时 dispose 后，在途 HTTP/回源结果必须失效，不能广播旧账号事件。
+ * GROUP 端口或为 `supergroup` fallback。运行时 dispose 后，在途 HTTP 查询的结果必须失效，不能广播旧账号事件。
  */
 
 /** CHANNEL 资料、成员和申请门面；已退场的 Mention 历史定位不进入产品面。 */
@@ -3626,7 +3652,7 @@ interface ImChannelApi extends ImDirectoryApi<'channel'> {
         cursor?: string;
         limit?: number;
     }) => Promise<ChannelMemberPage>;
-    /** 进入 CHANNEL 时预热 role-rich 有界成员快照；缓存新鲜时不回源。 */
+    /** 进入 CHANNEL 时预取含成员角色的有限列表；缓存未过期时不重复请求服务端。 */
     prefetchMembers: (channelId: string) => Promise<void>;
     /** 读取 role-rich 有界快照或本地搜索命中；不触发远端请求。 */
     getCachedMembers: (input: {
@@ -3775,7 +3801,7 @@ interface ImContactApi extends ImDirectoryApi<'individual'> {
     getProfile: (userId: string, opts?: {
         forceRefresh?: boolean;
     }) => Promise<UserProfile | null>;
-    /** 仅读内存/持久化，不回源 HTTP；命中时显式返回 stale。 */
+    /** 只读内存或本地存储，不发 HTTP；命中时明确返回 stale，提醒调用方缓存可能已过期。 */
     peekProfile: (userId: string) => Promise<{
         value: UserProfile;
         stale: boolean;
@@ -3825,7 +3851,7 @@ interface ConversationPrefetchOptions {
  * skipped 表示当前类型、权限、存储或预算不允许预取；失败不改变正常打开会话的行为。
  */
 interface ConversationPrefetchResult {
-    ref: ConversationRef<'direct' | 'group' | 'channel' | 'robot'>;
+    ref: ConversationRef<'direct' | 'group' | 'channel' | 'robot' | 'customerService'>;
     status: 'ready' | 'skipped' | 'failed' | 'cancelled';
     reason?: 'unsupported' | 'unavailable' | 'storage-unavailable' | 'budget' | 'page-too-large' | 'decrypt-failed' | 'invalidated' | 'cancelled';
     error?: ImSdkErrorShape;
@@ -3833,7 +3859,7 @@ interface ConversationPrefetchResult {
 
 /**
  * 当前账号草稿的产品 DTO、跨组件 API 与 handle 绑定门面。
- * 草稿按复合会话身份串行持久化，SDK DomainState 是唯一真相；附件尚未闭合时非空输入明确拒绝。
+ * 草稿按会话类型和 ID 串行保存，统一由 SDK DomainState 管理；当前不支持保存附件，非空附件输入会被明确拒绝。
  */
 
 /** 当前产品草稿实体；只包含可持久化的 text/mention/reply，附件集合固定为空。 */
@@ -3896,7 +3922,7 @@ interface ImDraftsApi {
  */
 
 /** 当前兼容门面支持的精确会话 ref。 */
-type ImSupportedConversationRef = ConversationRef<'direct' | 'group' | 'channel' | 'robot'>;
+type ImSupportedConversationRef = ConversationRef<'direct' | 'group' | 'channel' | 'robot' | 'customerService'>;
 /**
  * 会话 API 的迁移期入参。优先传完整 ref；旧 string 仅在当前 session 中唯一命中时可用。
  *
@@ -3904,10 +3930,10 @@ type ImSupportedConversationRef = ConversationRef<'direct' | 'group' | 'channel'
  */
 type ImConversationInput = ImSupportedConversationRef | string;
 /**
- * 会话列表兼容读模型；草稿是当前账号本机即时投影，不进入 session durable 行，也不承诺跨端同步。
+ * 内部会话列表数据。草稿反映当前账号的本机输入，不写入会话持久记录，也不跨端同步。
  *
- * @remarks Phase 7 消费方迁移前保留 ImSession 展示字段；新代码应优先读取复合身份语义与 draft，不自行拼主键。
- * @example `client.conversations.list().find(item => item.draft !== null)` 可找到当前账号有未发送草稿的会话。
+ * 保留 ImSession 的展示字段供内部调用方使用；跨类型识别会话时必须使用会话类型 + ID，不自行拼接主键。
+ * @example client.conversations.list().find(item => item.draft !== null) 可找到当前账号有未发送草稿的会话。
  */
 interface ConversationListItem$1 extends ImSession {
     draft: ConversationDraft | null;
@@ -3934,7 +3960,7 @@ interface ImConversationsApi {
     markConversationRead: (conversation: ImConversationInput) => Promise<void>;
     /** 给已无真实未读的会话添加本地未读提醒；不回退消息已读状态，也不发网络请求。 */
     markConversationUnread: (conversation: ImConversationInput) => void;
-    /** 删除本机会话、消息、读态与草稿；立即发布对应本地事件，durable 删除失败经 storage error 暴露，离线历史受 tombstone 约束。 */
+    /** 删除本机会话、消息、已读状态和草稿并立即发布本地事件；存储删除失败会报告 storage error，本地删除标记阻止离线消息恢复已删除内容。 */
     deleteConversation: (conversation: ImConversationInput) => void;
 }
 
@@ -4004,16 +4030,16 @@ interface ImCreateGroupResult {
 }
 
 /**
- * SDK 内部普通群 sibling：装配群资料、成员名称、`@` 候选和群置顶主动操作。
+ * SDK 内部普通群模块：提供群资料、成员名称、@ 候选和群置顶操作。
  *
  * 本模块只接收 GROUP `ConversationRef`，使用普通群独立 HTTP/mapper，并回写当前账号唯一 DomainState。
- * CHANNEL 的角色、申请、成员治理和置顶协议不从这里兼容；dispose 会作废回源与协调器结果。
+ * CHANNEL 的角色、申请、成员管理和置顶协议由独立模块处理；dispose 后旧查询和协调任务的结果不再生效。
  */
 
 /**
  * GROUP 完整 @候选集合产品面。
  *
- * @remarks `listAll` 使用账号级产品缓存；`refreshAll` 显式绕过缓存回源。两者只消费普通群完整成员 provider，
+ * @remarks `listAll` 使用账号级产品缓存；`refreshAll` 绕过缓存重新请求服务端。两者只消费普通群完整成员 provider，
  * 不接受 CHANNEL 分页 cursor/provider。缺少 provider、远端失败或不完整结果会拒绝，不用空数组伪装失败。
  * @example
  * ```ts
@@ -4025,7 +4051,7 @@ interface ImCreateGroupResult {
 interface ImGroupMentionApi {
     /** 读取完整候选集合；同群并发读取复用请求，成功结果按 userId 稳定去重并缓存。 */
     listAll: (group: ConversationRef<'group'>) => Promise<readonly MentionCandidate[]>;
-    /** 显式回源刷新完整候选；并发刷新复用请求，失败保留此前成功缓存。 */
+    /** 显式向服务端重新查询完整候选；并发刷新复用请求，失败保留此前成功缓存。 */
     refreshAll: (group: ConversationRef<'group'>) => Promise<readonly MentionCandidate[]>;
 }
 /** GROUP 资料、成员缓存、@候选与单条置顶门面；不与 CHANNEL 合并。 */
@@ -4044,17 +4070,17 @@ interface ImGroupApi extends ImDirectoryApi<'group'> {
     getMemberNames: (groupId: string, opts?: {
         forceRefresh?: boolean;
     }) => Promise<Record<string, string> | null>;
-    /** 仅读普通群成员缓存，不回源。 */
+    /** 仅读普通群成员缓存，不请求服务端。 */
     peekMembers: (groupId: string) => Promise<{
         value: GroupMemberItem[];
         stale: boolean;
     } | null>;
-    /** 仅读普通群昵称缓存，不回源。 */
+    /** 仅读普通群昵称缓存，不请求服务端。 */
     peekMemberNames: (groupId: string) => Promise<{
         value: Record<string, string>;
         stale: boolean;
     } | null>;
-    /** 仅读普通群资料缓存，不回源。 */
+    /** 仅读普通群资料缓存，不请求服务端。 */
     peekProfile: (groupId: string) => Promise<{
         value: GroupProfile;
         stale: boolean;
@@ -4103,7 +4129,7 @@ interface ImGroupApi extends ImDirectoryApi<'group'> {
 }
 
 /**
- * SDK 资源轴与连接轴的稳定生命周期合同。
+ * SDK 账号资源和网络连接的稳定生命周期合同。
  * 账号准备、联网和 logout 保持可区分；快照不包含 token、transport、storage 句柄或宿主认证状态。
  */
 
@@ -4112,9 +4138,9 @@ interface ImClientSnapshot {
     connectionState: ImConnectionState;
     pendingOutbox: OutboxMessage[];
 }
-/** 会话资源生命周期；与连接状态轴正交。 */
+/** 账号资源的准备和释放状态；网络连接状态单独记录，二者互不替代。 */
 type ImSessionLifecycleState = 'empty' | 'preparing' | 'ready' | 'logging-out' | 'disposed';
-/** 会话资源轴、连接轴与常用派生状态。 */
+/** 账号资源状态、网络连接状态，以及由二者计算的便捷状态。 */
 interface ImLifecycleSnapshot {
     sessionState: ImSessionLifecycleState;
     connectionState: ImConnectionState;
@@ -4223,7 +4249,7 @@ type ImApplicationItem = (ApplicationItemBase<'contact-request', ContactApplicat
  * typed application inbox 产品面。
  *
  * @remarks `listPending` 只有在 contact/GROUP/CHANNEL 三个 provider 全部成功时才返回完整快照；审核动作按 ref.domain
- * 精确回到 sibling。CHANNEL invite type=5 不属于已闭合 provider，因此不会出现在结果中。
+ * 精确回到 sibling。CHANNEL invite type=5 不属于已确认 provider，因此不会出现在结果中。
  * @example
  * ```ts
  * const pending = await client.applications.listPending()
@@ -4293,13 +4319,13 @@ interface ImDirectCallsApi {
 }
 
 /**
- * 会话背景的产品选择、预设读取和持久化解析运行时。
+ * 管理会话背景选择、预设读取和本地保存。
  *
- * SDK 保存 builtin/preset/custom 的稳定选择及账号默认值，不保存 DOM、图片元素或 object URL；自定义图片
- * Blob 只经 storage 持久化。异步读取使用运行时代际防止切会话/切账号晚返回，宿主负责最终渲染与 URL 释放。
+ * SDK 保存 builtin/preset/custom 选择及账号默认值；自定义图片 Blob 经 storage 保存，不持有 DOM、图片元素或 object URL。
+ * 异步读取返回时核对运行环境版本，防止切会话或切账号后应用旧结果；宿主负责最终渲染和 URL 释放。
  */
 
-type ConversationBackgroundConversationType = 'direct' | 'group' | 'channel' | 'robot';
+type ConversationBackgroundConversationType = 'direct' | 'group' | 'channel' | 'robot' | 'customerService';
 interface ConversationBackgroundPreset {
     id: string;
     url: string;
@@ -4338,9 +4364,9 @@ interface ImConversationBackgroundApi {
 }
 
 /**
- * 联系人、普通群和 CHANNEL 资料的稳定产品 DTO 投影。
+ * 把联系人、普通群和 CHANNEL 资料转换为稳定产品数据。
  *
- * 本文件只做复制、权限归一化与错误收敛，不缓存资料，也不发 HTTP。GROUP/CHANNEL 各自保留业务字段，
+ * 本文件只复制字段、统一权限格式和转换错误，不缓存资料，也不发 HTTP。GROUP/CHANNEL 各自保留业务字段，
  * 公钥、访问快照、密钥版本、协议状态和 core extensions 都不会进入 default API。
  */
 
@@ -4363,14 +4389,14 @@ interface ImContactRemarkPhone {
     countryCode: string;
     mobile: string;
 }
-/** default GROUP 资料 DTO；后端未闭合的数值 status 与缓存扩展不进入产品面。 */
+/** default GROUP 资料 DTO；后端尚未确认的数值 status 与缓存扩展不进入产品面。 */
 interface ImGroupProfile {
     ref: ConversationRef<'group'>;
     name: string;
     avatar?: string;
     memberCount?: number;
     ownerId?: string;
-    /** 普通群入群验证方式（1/2/4 为当前可设置值；未知值不在产品层静默归一）。 */
+    /** 普通群入群验证方式（1/2/4 为当前可设置值）；未知值不能在产品层被自动改写。 */
     verifyWay?: number;
     /** 普通群邀请码；仅邀请码模式有意义。 */
     inviteCode?: string;
@@ -4461,7 +4487,7 @@ interface ImChannelProfile {
  */
 
 /** default 会话列表支持的精确类型；`supergroup` 继续受产品 Gate 约束。 */
-type ProductConversationListType = 'direct' | 'group' | 'channel' | 'robot';
+type ProductConversationListType = 'direct' | 'group' | 'channel' | 'robot' | 'customerService';
 /** GROUP 会话限制状态；与 CHANNEL 状态保持独立 sibling。 */
 type ImGroupConversationState = GroupSessionState;
 /**
@@ -4632,8 +4658,8 @@ interface ImConversationListSnapshot {
  * default 会话列表产品面。
  *
  * @remarks
- * `list()` 保留 Phase 5 已验证的同步本地读模型；`getSnapshot/subscribe` 为普通宿主提供原子列表和总未读。
- * 所有写动作只接受复合身份。`deleteLocal` 立即提交内存删除事件，但底层 durable 删除仍是异步 best-effort，
+ * `list()` 同步读取本机会话；`getSnapshot/subscribe` 为普通宿主提供同一时刻的列表和总未读。
+ * 所有写动作只接受复合身份。`deleteLocal` 立即提交内存删除事件，但底层存储删除仍异步执行，失败会报告错误，
  * 因此该方法不虚假返回代表“持久化已完成”的 Promise。
  *
  * @example
@@ -4695,6 +4721,17 @@ interface DirectConversationCapabilities {
     canUseMessageActions: CapabilityDecision;
     canManageRelationship: CapabilityDecision;
 }
+/** 客服只读能力；资料、发送和消息修改均不可用，历史读取仅限本机已接收消息。 */
+interface CustomerServiceConversationCapabilities {
+    /** 客服号不可发送消息。 */
+    canSendMessages: CapabilityDecision;
+    /** 客服号没有好友或成员资料页。 */
+    canOpenProfile: CapabilityDecision;
+    /** 客服号不开放消息修改与转发等动作。 */
+    canUseMessageActions: CapabilityDecision;
+    /** 允许读取客服本机历史。 */
+    canReadHistory: CapabilityDecision;
+}
 interface RobotConversationCapabilities {
     canSendMessages: CapabilityDecision;
     canOpenProfile: CapabilityDecision;
@@ -4769,6 +4806,8 @@ type ConversationCapabilitySnapshot = (ConversationCapabilityBase<'direct'> & {
     value: ChannelConversationCapabilities;
 }) | (ConversationCapabilityBase<'robot'> & {
     value: RobotConversationCapabilities;
+}) | (ConversationCapabilityBase<'customerService'> & {
+    value: CustomerServiceConversationCapabilities;
 });
 interface ImConversationCapabilitiesApi {
     /** 只读取 SDK 当前本机真相与已刷新过的资料/关系投影，不隐式联网。 */
@@ -4920,7 +4959,7 @@ interface ImExpressionsApi {
  */
 
 /** 当前已接线的产品 handle 会话类型；三者只在无会话语义原子层复用。 */
-type ProductHandleConversationType = 'direct' | 'group' | 'channel' | 'robot';
+type ProductHandleConversationType = 'direct' | 'group' | 'channel' | 'robot' | 'customerService';
 /**
  * 会话 handle 初始打开位置。
  *
@@ -4982,9 +5021,9 @@ interface ConversationHandleSnapshot<TType extends ProductHandleConversationType
     error?: ImSdkErrorShape;
 }
 /**
- * 单条消息本机删除结果。
+ * 单条消息的本机删除结果。
  *
- * @remarks `scope` 永远是 `local-only`；该动作不发送撤回/双删命令，也不建立远端墓碑，因此重新加载远端历史可能恢复同一消息。
+ * scope 固定为 local-only；该动作不发送撤回或双方删除命令，也不会让服务端标记删除，重新加载远端历史时可能再次出现同一消息。
  */
 interface LocalMessageDeletionResult {
     scope: 'local-only';
@@ -5257,8 +5296,8 @@ type ConversationMessageApiFor<TType extends ProductHandleConversationType> = TT
 /**
  * 绑定单个复合会话身份的产品级会话句柄。
  *
- * @remarks 每次打开都持有独立连续窗口；`close()` 只释放瞬时窗口和订阅，不删除领域消息。direct/GROUP/CHANNEL
- * 由各自 sibling 工厂接入；草稿属于 Phase 5。关闭后所有读取与动作均 fail-fast。
+ * @remarks 每次打开都持有独立连续窗口；`close()` 只释放瞬时窗口和订阅，不删除领域消息。各会话类型
+ * 使用各自工厂；草稿经 drafts API 维护。关闭后继续读取或执行动作都会立即报错。
  * @template TType 当前句柄绑定的精确会话类型。
  * @example
  * ```ts
@@ -5324,6 +5363,18 @@ interface ConversationHandle<TType extends ProductHandleConversationType = Produ
     close: () => void;
 }
 
+/** 只读客服号资料；账号由 SDK runtime 绑定，宿主只提供当前语言。 */
+interface ImCustomerServiceApi {
+    /** 下载当前账号客服消息的指定文件；返回真实字节，不使用展示大小判断完成。 */
+    downloadFile: (input: {
+        messageId: string;
+        itemIndex: number;
+        signal?: AbortSignal;
+    }) => Promise<Blob>;
+    /** 获取并更新已有会话的显示资料；并发请求按语言合并，过期语言不覆盖当前页面。 */
+    getProfile: (lang: number) => Promise<Readonly<CustomerServiceProfile>>;
+}
+
 /**
  * SDK 对外的结构化诊断投影、过滤与 sink 装配。
  *
@@ -5436,7 +5487,7 @@ interface ImMediaTask {
     direction: 'upload' | 'download';
     /** 终态 completed/failed/canceled 不会被同一尝试的迟到 progress 回退。 */
     state: 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'canceled';
-    /** 0-100 的归一化整数。 */
+    /** 范围为 0 到 100 的整数进度。 */
     percent: number;
     /**
      * upload 子阶段。
@@ -5619,7 +5670,7 @@ interface ImMediaTasksApi {
  * 可靠发送账本的产品查询、订阅、重试和取消门面。
  *
  * Core Outbox 是唯一发送真相；产品项只暴露消息身份、状态和安全错误，不泄漏尝试次数或恢复策略。
- * 控制动作始终回到当前账号 connection，dispose 后旧订阅和晚返回结果失效，取消 queued 不等价于远端撤回。
+ * 控制动作始终回到当前账号 connection，dispose 后旧订阅失效，随后返回的旧结果不再生效，取消 queued 不等价于远端撤回。
  */
 
 /** 产品可观察 Outbox 项；不包含正文、帧、ACK、attempts、加密信息或 resumePolicy。 */
@@ -6180,7 +6231,7 @@ interface ImMessageSearchApi {
     inDirect: (conversation: ConversationRef<'direct'>, keyword: string) => Promise<ProductMessageSearchPage<MessageContentType>>;
     /** 搜索 GROUP 本地历史；不得接受 CHANNEL ref 或回退 direct。 */
     inGroup: (conversation: ConversationRef<'group'>, keyword: string) => Promise<ProductMessageSearchPage<MessageContentType>>;
-    /** 搜索 CHANNEL 本地历史；当前不调用未闭合的远端 CHANNEL 搜索/定位协议。 */
+    /** 搜索 CHANNEL 本地历史；当前不调用尚未确认的远端 CHANNEL 搜索/定位协议。 */
     inChannel: (conversation: ConversationRef<'channel'>, keyword: string) => Promise<ProductMessageSearchPage<MessageContentType>>;
     /** 搜索 robot 本地历史；无远端历史，不得回退 direct。 */
     inRobot: (conversation: ConversationRef<'robot'>, keyword: string) => Promise<ProductMessageSearchPage<MessageContentType>>;
@@ -6296,7 +6347,7 @@ interface ImEmojiCatalogEntry {
  *
  * 上传凭证由业务后端按登录态签发（与 iOS、prod H5 同一个接口），回包同时给出**物理桶**、区域、`key_prefix` 和
  * 公开访问域名；SDK 据此拼 object key 与消息体 URL，宿主 env 里配的只是申请凭证用的逻辑桶名。凭证缓存（本地
- * 1 小时、按服务端过期时间提前 5 分钟失效）、同桶单飞与失败重签由 SDK 负责，宿主只需提供「打一次接口」的纯函数。
+ * 1 小时、按服务端过期时间提前 5 分钟失效）、同桶并发请求复用和失败后重新签发由 SDK 负责，宿主只需提供「打一次接口」的纯函数。
  *
  * 默认单次 PUT/GET；仅 multipartTransfer=true 才允许大资源分片上传、下载。
  * 各 bucket 需在对象存储侧配置 CORS 允许本站 origin 的 PUT + GET；开启分片后，超过 16MiB 的上传另需放行
@@ -6375,6 +6426,7 @@ interface ImAccountAdapterContext extends ImClientAdapterContext {
  * @remarks create/purge 必须消费传入的 namespace factory；SDK 会先 close 返回的 storage，再调用 purge。
  */
 interface ImStorageAdapterFactory {
+    /** 创建或复用当前运行环境的存储；返回 undefined 明确使用纯内存，即使浏览器支持 IndexedDB 也不启用默认库。 */
     create: (context: ImClientAdapterContext) => ImStoragePort | undefined;
     purgeCurrentAccount: (context: ImAccountAdapterContext) => Promise<void>;
 }
@@ -6465,7 +6517,7 @@ interface ImAdvancedClientOptions extends ImClientOptions {
     channelMembers?: ImChannelMemberPort;
     /** CHANNEL Mention 候选 provider；不复用 role-rich 成员治理列表。 */
     channelMentionMembers?: ImChannelMentionMemberPort;
-    /** CHANNEL 申请审核 provider；当前只装配已闭合的 18A 审核能力。 */
+    /** CHANNEL 申请审核 provider；当前只装配已确认的 18A 审核能力。 */
     channelJoinApplications?: ImChannelJoinApplicationPort;
     /** 联系人申请 provider；与 GROUP/CHANNEL 审核 sibling 独立。 */
     contactApplications?: ImContactApplicationPort;
@@ -6522,7 +6574,7 @@ interface ImContactsApi extends ImDirectoryApi<'individual'> {
      * 发送好友申请。
      *
      * @remarks `remark` 是当前账号对目标用户设置的私有备注，按后端申请合同作为
-     * `remark_nick_name` 提交。SDK 不另存待处理副本；关系建立后从当前账号的权威好友资料收敛展示。
+     * `remark_nick_name` 提交。SDK 不另存待处理副本；关系建立后从当前账号的权威好友资料读取并展示。
      */
     requestFriendship: (userId: string, options: {
         message: string;
@@ -6746,7 +6798,7 @@ interface AdvancedConversationsApi extends ImConversationsApi, ImConversationBac
      *
      * @internal
      */
-    ensureOpenableConversation: (ref: ConversationRef) => Promise<ConversationRef<'direct' | 'group' | 'channel' | 'robot'>>;
+    ensureOpenableConversation: (ref: ConversationRef) => Promise<ConversationRef<'direct' | 'group' | 'channel' | 'robot' | 'customerService'>>;
     /**
      * 读取已有会话或本次账号内已校验的目标资料；返回值不代表列表成员资格。
      * @internal
@@ -6776,6 +6828,8 @@ interface ImProductClient {
     /** 当前账号完整联系人、群组和社群目录的统一搜索。 */
     readonly directory: ImDirectorySearchApi;
     /** 机器人公开目录；通讯录查找与群/社群绑定列表共用分页合同。 */
+    /** 客服号只读资料能力。 */
+    readonly customerService: ImCustomerServiceApi;
     readonly robots: ImRobotsApi;
     readonly contacts: ImContactsApi;
     readonly groups: ImGroupsApi;
@@ -6827,6 +6881,7 @@ interface ImClient extends Omit<ImProductClient, 'capabilities' | 'channels' | '
         (ref: ConversationRef<'group'>, options?: ConversationOpenOptions): Promise<ConversationHandle<'group'>>;
         (ref: ConversationRef<'channel'>, options?: ConversationOpenOptions): Promise<ConversationHandle<'channel'>>;
         (ref: ConversationRef<'robot'>, options?: ConversationOpenOptions): Promise<ConversationHandle<'robot'>>;
+        (ref: ConversationRef<'customerService'>, options?: ConversationOpenOptions): Promise<ConversationHandle<'customerService'>>;
     };
     /** 当前账号草稿产品面；按复合身份持久化，handle.draft 委托同一状态源。 */
     drafts: ImDraftsApi;
@@ -6844,7 +6899,7 @@ interface ImClient extends Omit<ImProductClient, 'capabilities' | 'channels' | '
     contact: ImContactApi;
     /** 群域：群资料读取 + 修改群名/群头像/群内昵称。 */
     group: ImGroupApi;
-    /** CHANNEL 域：资料、成员治理与独立置顶能力；仍未闭合的动作不进入此门面。 */
+    /** CHANNEL 域：资料、成员管理与独立置顶能力；尚未确认的动作不进入此门面。 */
     channel: ImChannelApi;
     /** 可观察媒体任务与按精确消息引用下载。 */
     media: ImMediaTasksApi;
@@ -6971,9 +7026,9 @@ type ImLocale = 'en-US' | 'th-TH' | 'vi-VN' | 'zh-CN' | 'zh-TW';
  */
 
 /**
- * 命令/生命周期「操作提示」文案 key（formatServiceText 用；供 kit services / runtime 产语义码、宿主按 locale 渲染）。
- * 二期收敛：kit 框架无关层不再直接产中文，改产本联合里的码 + 参数（如 {reason}/{label}/{size}），由宿主经 im-i18n 渲染。
- * 动态原始报错（error.message）作为 `{reason}` 参数拼接，不入 catalog（属诊断，不翻译）。
+ * 命令和生命周期操作提示的文案 key，供 formatServiceText 使用。
+ * kit service/runtime 返回语义码与参数，由宿主根据语言生成文案。
+ * 动态 error.message 作为 {reason} 参数，不纳入 catalog 翻译。
  */
 type ImServiceTextKey = 'common.notConnected' | 'common.selectOrOpenConversation' | 'common.conversationTypeNotReady' | 'common.conversationNotReady' | `recall.${RecallFailReason}` | `edit.${EditFailReason}` | 'localDelete.done' | 'localDelete.notFound' | 'localDelete.inFlight' | 'localDelete.failed' | 'channelDelete.notFound' | 'channelDelete.unsupported' | 'channelDelete.notSent' | 'channelDelete.unavailable' | 'channelDelete.forbidden' | 'channelDelete.timeout' | 'channelDelete.failed' | 'channelDelete.disconnected' | 'directBlock.contactRequired' | 'groupBlock.left' | 'groupBlock.removed' | 'groupBlock.dismissed' | 'groupBlock.unknownRestricted' | 'channelBlock.guest' | 'channelBlock.left' | 'channelBlock.removed' | 'channelBlock.dismissed' | 'channelBlock.muted' | 'channelBlock.allMembersMuted' | 'channelBlock.currentUserMuted' | 'channelBlock.blacklisted' | 'channelBlock.unknownRestricted' | 'channelProfile.loadFailed' | 'channelProfile.notFound' | 'channelProfile.retryAction' | 'channelMembers.title' | 'channelMembers.searchPlaceholder' | 'channelMembers.loading' | 'channelMembers.loadFailed' | 'channelMembers.retryAction' | 'channelMembers.empty' | 'channelMembers.loadingMore' | 'channelMembers.loadMoreFailed' | 'channelMembers.exhausted' | 'channelMembers.loadMoreAction' | 'label.image' | 'label.video' | 'label.file' | 'label.sticker' | 'send.failed' | 'send.retryFailed' | 'send.cancelFailed' | 'send.mediaFailed' | 'send.mediaEmpty' | 'send.mediaCancelled' | 'send.mediaCountLimit' | 'send.mediaTooLarge' | 'send.mediaFormatMismatch' | 'send.imageFormatUnsupported' | 'send.videoTooLong' | 'send.videoDurationUnavailable' | 'send.voiceEmpty' | 'send.voiceStorageNotConfigured' | 'send.voiceCancelled' | 'send.voiceFailed' | 'media.uploadWaiting' | 'media.voiceNotReady' | 'media.voiceLoadEmpty' | 'media.voiceLoadFailed' | 'media.videoOpenEmpty' | 'media.videoLoadFailed' | 'media.imageInvalid' | 'media.imageLoadFailed' | 'media.fileDownloadEmpty' | 'media.fileDownloadFailed' | 'conversation.muteEnableFailed' | 'conversation.muteDisableFailed' | 'conversation.backgroundLoadFailed' | 'read.markReadFailed' | 'storage.failed' | 'sync.failed' | 'draft.saveFailed' | 'history.returnLatestFailed' | 'pinned.forbidden' | 'pinned.network' | 'pinned.contract' | 'pinned.unsupported' | 'pinned.failed' | 'pinned.previewUnavailable' | 'pinned.locateFailed' | 'pinned.messageNotFound' | 'pinned.recalled' | 'pinned.deleted' | 'pinned.protected' | 'pinned.pinAction' | 'pinned.unpinAction' | 'pinned.unpinConfirm' | 'pinned.cancelAction' | 'lifecycle.missingLoginState' | 'lifecycle.prepareFailed' | 'lifecycle.missingConnectParams' | 'lifecycle.connectFailed' | 'lifecycle.disposed' | 'lifecycle.connectionOccupied' | 'lifecycle.connectionCoordinationUnavailable' | 'forward.emptyInput' | 'forward.allSkipped' | 'forward.partialSkipped' | 'forward.done' | 'forward.failed';
 
@@ -7102,7 +7157,7 @@ interface DelayedLoadingIndicatorOptions {
     clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
 }
 interface DelayedLoadingIndicator {
-    /** 同一 identity 延续当前计时；identity 变化会作废旧操作并重新开始。 */
+    /** 同一 identity 继续当前计时；identity 改变后旧操作不再生效，并重新开始计时。 */
     update: (loading: boolean, identity: string) => void;
     /** 取消定时器并在必要时发出一次隐藏通知。 */
     dispose: () => void;
@@ -7113,7 +7168,7 @@ declare const DEFAULT_LOADING_MINIMUM_VISIBLE_MS = 220;
  * 将真实 loading 与可见提示分离。
  *
  * 快速完成的缓存读取不会显示提示；已经显示的提示会满足最短展示时间。identity 变化、关闭和
- * dispose 都会取消旧定时器，避免上一条媒体的晚返状态影响当前预览。
+ * dispose 都会取消旧定时器，避免上一条媒体随后返回的旧状态影响当前预览。
  */
 declare function createDelayedLoadingIndicator(options: DelayedLoadingIndicatorOptions): DelayedLoadingIndicator;
 
@@ -7838,7 +7893,7 @@ interface ConversationPrefetchController {
  * 页间重新等待宿主空闲调度，使置顶、未读、删除和活动会话变化及时影响下一页，
  * SDK 仍负责请求去重、前台优先与本次账号 Runtime 的网络总预算。
  * 同一 Client 下完成或失败的候选本轮不自动重试；取消项可在运行条件恢复后重新排队。
- * reset/client 更换会作废旧请求，旧 Promise 完成后不能修改新账号的请求记录。
+ * reset 或更换 client 后旧请求结果失效，旧 Promise 完成后不能修改新账号的请求记录。
  */
 declare function createConversationPrefetchController(options: ConversationPrefetchControllerOptions): ConversationPrefetchController;
 
@@ -8594,7 +8649,7 @@ declare function resolveChannelMembers(runtime: ChatRuntime, channelId: string,
 /**
  * 收到“普通群成员已改名”的系统消息后，重新读取该群成员昵称；不直接信任通知中的展示文本。
  *
- * 本机写入的通知可能晚于写请求返回；宿主通过 `preserveUserIds` 明确保留仍存在的本地高水位。
+ * 本机写入的通知可能晚于写请求返回；宿主通过 `preserveUserIds` 明确保留尚未被服务端查询确认的本机昵称。
  * 不能仅凭 `operatorId === self` 判断为本机写入，因为同账号其它设备改名也使用相同操作者。
  */
 declare function applyGroupMemberRename(runtime: ChatRuntime, message: AdvancedMessage, options?: {
@@ -8603,21 +8658,21 @@ declare function applyGroupMemberRename(runtime: ChatRuntime, message: AdvancedM
 /**
  * 把已经加载的普通群成员列表同步为消息气泡可查询的昵称表。
  *
- * 输入成员可能已合并本地昵称投影，因此这里只同步展示，不把同值误判为服务端已收敛。
+ * 输入成员可能已合并本地昵称投影，因此这里只同步展示，不能因值相同就认定服务端已返回最新昵称。
  */
 declare function applyMemberNames(runtime: ChatRuntime, groupId: string, members: readonly GroupMember[]): void;
 /**
- * 写请求成功后只更新普通群昵称的共享展示投影。
+ * 写请求成功后只更新普通群昵称的共享展示数据。
  *
- * 成员列表、消息气泡和 GROUP `@` 候选都读取 Runtime 的这份映射，因此这里原子替换单个成员即可
- * 让三个消费者同步收敛；后续完整成员回源会在服务端返回相同值后自动解除保护。
+ * 成员列表、消息气泡和 GROUP `@` 候选都读取 Runtime 的这份映射，因此更新单个成员后即可
+ * 让这些界面立即显示同一昵称；后续完整成员查询返回相同值后自动解除本机保护。
  */
 declare function applyGroupMemberNickname(runtime: ChatRuntime, groupId: string, userId: string, nickname: string): void;
 /**
- * 清理一个群的本地昵称高水位。
+ * 清理一个群的本机昵称保护记录。
  *
- * `clearCachedNames` 只在资料权威确认账号已退出/群已不存在时使用：此时旧群昵称不能继续作为新加入
- * 或同 ID 会话的当前投影。普通外部改名仍只清理高水位，随后由强刷结果更新完整成员名称缓存。
+ * 只有资料接口确认账号已退出或群已不存在时，才使用 clearCachedNames 同时清空已缓存的群昵称，避免影响重新加入的会话。
+ * 收到其他设备改名时只清除保护记录，完整成员名称由强制刷新后的结果更新。
  */
 declare function clearGroupMemberNicknameProjection(runtime: ChatRuntime, groupId: string, options?: {
     clearCachedNames?: boolean;
@@ -8809,7 +8864,7 @@ interface ImMediaBatchSendResult {
     selectedCount: number;
     /** 实际进入逐项发送流程的数量。 */
     processedCount: number;
-    /** `sendMediaFile` 返回成功、且仍属于原账号代际的数量。 */
+    /** sendMediaFile 返回成功，且操作结束时仍处于同一账号版本的项目数量。 */
     acceptedCount: number;
     /** 是否因为单批数量上限忽略了部分选择。 */
     rejectedByLimit: boolean;
@@ -9251,10 +9306,10 @@ declare function createNewMessageBadgeController(onCountChange?: NewMessageBadge
 /** Surface renderer registry 可接收的稳定消息正文种类。 */
 type ImMessageBodyKind = MessageContentType | 'gif' | 'decrypt-failed';
 /**
- * 把 SDK 归一化消息解析为唯一正文 renderer kind。
+ * 把 SDK 统一格式的消息解析为唯一正文 renderer kind。
  *
  * 解密失败优先于正文类型；已注册类型结构不完整时返回 `unknown`，避免一条坏消息中断整个线程。
- * GIF 只依据 SDK 归一化后的 sticker `imageType` 判断，不解析 URL 后缀或协议原始字段。
+ * GIF 只依据 SDK 转换后的 sticker `imageType` 判断，不解析 URL 后缀或协议原始字段。
  */
 declare function resolveMessageBodyKind(message: ImMessageView): ImMessageBodyKind;