OpenMax
免费试用

数据模型

宿主和组件之间传递的数据:消息、会话、成员、附件、已读与未读,以及发送、编辑、分页、草稿用的类型,逐个字段列出。

数据模型

宿主的能力收发的就是本页这些类型,从 @openmaxai/chat/host 导出;ChatMemberKind、ChatMentionInput 以及嵌套对象(mentions、reactions、agent_collab_participants 的每一项,card_state、dm、group、last_message_preview)的类型名也从这里导出 规划中。每个方法怎么用、出错时怎么办见宿主能力。

这些类型都由 SDK 定义,不引用任何后端(包括 OpenMax)的类型。字段按两种方式命名:

  • 消息、会话、附件、会话成员:ChatMessage、ChatConversation、ChatAttachment、ChatConversationParticipant。字段名与 OpenMax 相同,下划线命名(sender_id、created_at)。接别的后端时由适配器把你的数据映射成这些字段,见已知限制。
  • 其余类型:发送输入、分页、成员、草稿、已读快照等,驼峰命名(conversationId、nextCursor)。

「必填」为「否」的字段可以不给,不给时的表现写在含义里。时间字段是 ISO 8601 字符串(如 "2026-10-05T10:00:00Z"),例外处注明。

消息

ChatMessage

会话里的一条记录。

字段 类型 必填 含义
id string 是 消息 id
conversation_id string 是 所属会话
seq number 是 会话内序号:整数,从 1 递增、不重复。排序、补洞、已读位置都按它,时间戳替代不了,见实时与同步 · 序号
type 见消息类型 是 决定怎么画
sender_id string 是 发送者的成员 id,对应 ChatParticipant.memberId
sender_type "UNSPECIFIED" | "HUMAN" | "AGENT" | "SYSTEM" 是 发送者类别。界面区分人和 Agent 看的是成员的 kind,不看这个字段
content string 否 正文,见正文
content_version number 是 正文版本,从 1 开始。每次编辑都要变大,界面据此重画这条消息
fallback_text string 否 画不出来时显示的一行字:不认识的类型、卡片、结构化消息
attachments ChatAttachment[] | null 否 附件,按显示顺序,见 ChatAttachment
mentions 见提及 否 这条消息 @ 了谁
parent_id string 否 引用回复:被引用那条消息的 id。被引用的消息不在已加载范围内时,界面用 messaging.loadMessage 取
reactions 见表态 否 按表情汇总的表态
created_at string 是 创建时间。日期分隔条和编辑时限按它算
timestamp string 是 服务端记录的消息时间。界面显示用 created_at
edited_at string 否 最后一次编辑的时间;有值时气泡显示「(已编辑)」
deleted_at string 否 撤回时间;有值时这条画成撤回提示,正文和表态不再显示
recalled_by string 否 撤回者的成员 id
recalled_by_role "sender" | "admin" 否 发送者本人撤回,还是群主或管理员撤回
pinned_at 规划中 string 否 置顶时间;有值时时间行显示图钉,见消息区 · 置顶
pinned_by 规划中 string 否 置顶者的成员 id
client_msg_id string 否 发送方给的去重键,读取时原样带回。乐观发送据它把本地那条换成服务端那条,见 ChatStoreSendStartedEvent
metadata Record<string, unknown> 否 透传的元数据。系统消息的 metadata.system_action 为 "member_left"(有人退群)或 "owner_changed"(群主换人)时,界面按成员名自己拼文案
metadata.quote_excerpts { version: 1, items: [{ message_id, text, offset?, truncated? }] } 否 发送者从被引消息里划选的那段文字(message_id 等于 parent_id;text 是纯文本,至多 1000 个码点)。被引消息撤回后,后端可以把条目改写成 { message_id, recalled: true },引用条随之显示「原消息已撤回」。缺失、version 不是 1、形状不对、message_id ≠ parent_id 时界面当作没有片段、显示整条引用;不认识的字段忽略
metadata.forwarded_from { version: 1, sender_id, sender_type, sender_name, sent_at?, source_kind? } 否 服务端写在转发副本上:原作者,转发那一刻的快照。气泡不显示来源标签(转发副本按普通消息渲染),且不给编辑入口。缺这一块、version 不是 1、形状不对,都当作不是转发副本
metadata.run_id 规划中 string 否 Agent 的最终回复属于哪次运行
metadata.stream_message_id 规划中 string 否 这条回复替换哪段逐字预览:等于那段文字的 TEXT_MESSAGE_* 事件的 messageId,见消息区 · 逐字输出
card_body 等 否 卡片消息的字段,见卡片字段
chat_history_preview Record<string, unknown> 否 只有 "CHAT_HISTORY" 有:合并转发的列表投影(cws.chat_history.preview.v1:标题、条数、前几条记录)。完整记录在 messaging.loadMessage 取回的单条消息的正文里(cws.chat_history.v1)
priority number 是 1 紧急、2 高、3 普通。界面不使用
org_id string 是 所属组织。界面不使用
delivery_status "sending" | "sent" | "failed" | "blocked" 否 本端发送状态,由 SDK 写,宿主不填。blocked 表示被服务端内容过滤拦下
blocked_refusal_text string 否 被拦下的消息后面跟着显示的说明,由 SDK 写

消息类型

type 怎么画
"TEXT" 文本气泡,正文是 Markdown,交给 render.renderMessageText 按 Markdown 画 规划中
"IMAGE"、"FILE" 图片或文件,来自 attachments;正文是说明文字。附件全是图片时发送为 "IMAGE",否则为 "FILE"
"AGENT_TEXT" Agent 的回复,正文交给 render.renderMarkdown
"AGENT_STRUCTURED" 由认领它的消息展示插件画;没有插件认领时显示 fallback_text
"CARD" 交互卡片,内容在 card_body
"SYSTEM" 居中的一行系统提示
"CHAT_HISTORY" 合并转发:会话记录卡片,本地化标题、最多 4 行「发送人: 内容」和总条数,从正文或 chat_history_preview 读。点开看全部记录;只有投影时界面用 messaging.loadMessage 取一次整条消息。两者都读不出时显示 fallback_text
"AUDIO"、"VIDEO"、"AGENT_STREAM"、"AGENT_CARD"、"INTERACTION_RECEIPT"、"UNSPECIFIED" 没有专门的画法,显示正文或 fallback_text

每条消息先看有没有消息展示插件认领它(内置的几类除外),认领了就由插件画正文,见自定义消息渲染。

正文

content 是一个字符串,两种写法都接受:

  • JSON 对象,如 {"text":"hello"}。text 是正文;图片和文件消息的 text 是说明文字。
  • 纯文本,如 hello。整串当作正文。

界面取正文的顺序:JSON 里的 text,然后 fallback_text,最后是原始的 content。

提及

mentions 是数组,每项:

字段 类型 必填 含义
mentioned_id string 是 被 @ 的成员 id
username string 否 @ 时记下的名字,可能已经过时
is_mention_all boolean 是 这一行来自 @所有人 / @所有 Agent 的展开,而不是直接 @

服务端不解析正文里的 @ 文字,这个数组是提及的唯一来源;render 靠它判断「这条 @ 的是不是我」。发送时的写法见 SendMessageInput。

表态

reactions 是数组,每个表情一项:

字段 类型 必填 含义
code string 是 表情代码,如 thumbs_up
count number 是 点这个表情的总人数
reacted_by_me boolean 是 当前用户点了没有
reactor_ids string[] | null 否 点了的成员 id,最多前 20 个,count 可以更大
unicode_fallback string 是 界面不认识这个代码时显示的字符

表情选择器里的代码:thumbs_up、smile、heart、tada、eyes、joy、fire、white_check_mark、ok_hand、x、hourglass、warning。

卡片字段

字段 类型 必填 含义
card_body Record<string, unknown> 否 完整卡片(cws.card.v1),结构见交互卡片 · 卡片结构
card_preview Record<string, unknown> 否 裁剪过的预览(cws.card.preview.v1),不带操作按钮。和 card_body 只出现一个
card_truncated boolean 否 给的是 card_preview;界面显示「展开」,点了调用 cards.expandBody
card_state 见下 否 最近一次作答;没人作答时没有
card_superseded boolean 否 被后来的卡片取代;已作答的卡片以 card_state 为准
card_expired boolean 否 过了作答期限

card_state:action_id(点的是哪个按钮)、actor_id(谁点的)、result_at(点击时间)、status(作答状态,唯一取值 "succeeded"),四个都必填。结果行怎么显示见交互卡片 · 结果。

会话

ChatConversation

字段 类型 必填 含义
id string 是 会话 id
type "DM" | "GROUP" | "STRAT" | "BROADCAST" | "BRIDGE" 是 见会话类型
name string | null 是 群名。单聊一般为 null,界面显示对方的名字
avatar_url string | null 否 群头像。单聊用 dm.peer_avatar_url
last_message_at string 是 最后一条消息的时间,会话列表按它排序
last_message_preview 见最后一条消息 否 列表里显示的预览
unread_count number 是 当前用户的未读条数
unread_mention "none" | "direct" | "all" 否 有没有未读的 @:direct 是 @我,all 是 @所有人,direct 优先
last_read_seq number 否 当前用户读到的 seq。打开会话时作为未读分隔条的锚点,见消息区
pinned boolean 否 当前用户置顶了它
done boolean 否 当前用户隐藏了它;默认列表不显示,搜索时显示
muted boolean 否 当前用户开了免打扰。不计入未读总数,会话自己的未读照常显示
owner_id string 否 群主的成员 id
can_mention_all boolean 否 当前用户能不能 @所有人。不给按不能
is_observed boolean 否 当前用户是旁观者:能看到这个会话,只因为他旁观其中一个成员(如自己的 Agent)。未读不计,也不计入未读总数
observed_member_ids string[] 否 被旁观的成员 id
agent_collab_participants 见下 否 Agent 协作会话的参与者,列表据此显示「A ⇄ B」
dm 见单聊详情 否 type 为 "DM" 时给
group { description: string; admin_count: number } 否 type 为 "GROUP" 时给。description 是群描述,群信息面板显示和编辑它
created_at、member_count、archived_at、is_observer、last_message_id、read_receipt_mode、can_send、read_only_reason、agent_member_id、broadcast、bridge 界面不使用

created_at、member_count、is_observer 在类型上必填,其余可选。

agent_collab_participants 每项:member_id、kind("agent" \| "human" \| "system")、display_name、avatar_url?、status("active" \| "suspended" \| "departed")。

置顶和隐藏是当前用户自己的状态,改它们用 conversations.setPinned、conversations.setHidden,见宿主能力 · conversations。

会话类型

type 是什么 列表里
"DM" 单聊。对方是 Agent 时(dm.peer_kind 为 "agent")带 Agent 徽标 显示
"GROUP" 群聊 显示,带「群聊」徽标
"BRIDGE" Agent 之间的协作会话,当前用户只读旁观 显示,带「Agent 协作」徽标
"BROADCAST" 频道 不显示
"STRAT" 保留给服务端 显示,没有徽标

单聊详情

dm:

字段 类型 必填 含义
peer_member_id string 是 对方的成员 id
peer_display_name string 否 对方的名字
peer_avatar_url string | null 否 对方的头像
peer_kind "human" | "agent" | "system" 否 对方是人、Agent 还是系统
peer_status "active" | "suspended" | "departed" 否 对方在组织里的状态;departed 时列表里标出对方已离开
can_send boolean 否 为 false 时输入框换成只读横幅
read_only_reason "peer_suspended" | "peer_departed" | "system_dm_readonly" 否 只读的原因,决定横幅文案
billing_suspended boolean 否 对方 Agent 因计费原因停机;只有 true 才算,不给按没有停机。只提示,不禁止发送
billing_suspension_reason string 否 停机原因,决定提示文案;不认识的值用通用文案

最后一条消息

last_message_preview:

字段 类型 必填 含义
id number 是 消息 id
sender_id string 是 发送者
sender_type string 是 发送者类别
type string 是 消息类型;图片、文件显示为「[图片]」「[文件]」
content string | null 否 正文
fallback_text string | null 否 正文画不出来时的一行字
timestamp number 是 毫秒时间戳(Unix 纪元起)
edited_at number | null 否 毫秒时间戳

有草稿时列表显示草稿而不是最后一条消息,草稿来自 drafts.previews()。

ChatConversationPage

conversations.list 的返回值。

字段 类型 必填 含义
conversations readonly ChatConversation[] 是 这一页的会话
nextCursor string 否 还有下一页时给,原样传回下一次 list

CreateConversationInput

messaging.createConversation 的参数。

字段 类型 必填 含义
memberIds readonly string[] 是 成员 id,包括当前用户。会话列表「搜人开聊」时传当前用户和对方两个 id
title string 否 会话名

建群用 groupManagement.createGroup,参数是 ChatCreateGroupInput。

ChatCreateGroupInput

字段 类型 必填 含义
title string 是 群名
description string 否 群描述;用户没填时不给,不传空串
memberIds readonly string[] 是 拉进群的成员 id

ChatGroupProfileUpdate

groupManagement.updateGroupProfile 的参数。群信息面板分两次保存名字和描述,一次只给一个字段。

字段 类型 必填 含义
name string 否 新群名
description string 否 新群描述

ChatGroupMembersChangeResult

groupManagement.addMembers / removeMembers 的结果。服务端逐人判,两张表合起来就是这次交进去的全部 id。

字段 类型 必填 含义
succeeded readonly string[] 是 这次加上 / 移掉了的成员 id
failed readonly { memberId: string; kind: ChatErrorKind; message?: string }[] 是 没成的那几个:成员 id、失败种类(与 ChatSdkError 的 kind 同一张表)、可给用户看的 message

ChatGroupLeaveOptions

groupManagement.leave 的选项。

字段 类型 必填 含义
newOwnerId string 否 群主退群时把群交给谁;不给由服务端定

ChatGroupLeaveResult

groupManagement.leave 的结果:服务端走了哪一支。

字段 类型 必填 含义
dissolved boolean 是 我走之后群没人可交(只剩 Agent 或没人),服务端把它解散了
newOwnerId string 否 群主退群时群交给了谁;不是群主或解散了时不给

成员

同一个人在不同地方用不同的类型:

类型 从哪来 用在哪
ChatParticipant identity.getMember、identity.listMembers 消息上的名字和头像、@ 候选
ChatDirectoryMember identity.searchDirectory 搜人开聊、建群和加人时选人、@ 候选里的组织成员
ChatConversationParticipant ChatInfoPanel 的 participants 属性 群信息面板的成员列表、选新群主
ChatMemberProfile profileCard.loadProfile 名片

kind 在这几个类型上取值相同:"human" | "agent" | "system",类型名为 ChatMemberKind。界面用它区分人和 Agent(例如 Agent 的气泡底色),不解释它的其他含义。

ChatParticipant

字段 类型 必填 含义
memberId string 是 成员 id
displayName string 是 名字
avatarUrl string 否 头像地址
kind ChatMemberKind 否 不给按人处理
displaySubtitle string 否 名字下面的一行副标题,界面只显示,不解释
modelLabel string | null 否 Agent 当前模型,名字旁边的只读标签;要显示的那句话由宿主算好。不给或 null 不显示

ChatDirectoryMember

字段 类型 必填 含义
memberId string 是 成员 id
displayName string 是 名字
avatarUrl string 否 头像地址
kind ChatMemberKind 否 不给按人处理
isActive boolean 是 还是不是组织里在用的成员。选人时只列在用的;停用、未激活等状态由宿主折成 false
billingSuspended boolean 否 这个成员(Agent)因计费停机。建群与加成员的选人行据此画停机、念停机,不画在线 / 离线。不给或不是 true 都按未停机;目录判不出时不给
creditCapReached boolean 否 这个成员(Agent)因额度封顶(日或月)停用。同样这些选人行画同一个暂停点、念「额度封顶」(只在头像带身份、即宿主有 presence 端口时);与 billingSuspended 同时为 true 时按计费停机。不给或不是 true 都按未封顶

ChatDirectoryPage

字段 类型 必填 含义
members readonly ChatDirectoryMember[] 是 这一页的成员
nextCursor string 否 还有下一页时给

ChatConversationParticipant

群信息面板的成员,已经和组织通讯录合并过。

字段 类型 必填 含义
member_id string 是 成员 id
kind "human" | "agent" | "system" 是 人、Agent 还是系统
display_name string 是 名字
avatar_url string | null 是 头像地址
online_status "online" | "starting" | "stopping" | "offline" | "error" | "unknown" 否 在线状态
owner_member_id string 否 Agent 的主人

ChatMemberProfile

名片的资料,在 ChatProfileEntity 上加了三个字段。ChatProfileEntity 也用于名片上的主人行和「名下的 Agent」列表。

字段 类型 必填 含义
memberId string 是 成员 id
displayName string 是 名字
avatarUrl string | null 否 头像地址
kind ChatMemberKind 否 "agent" 显示 Agent 名片,其余显示人员名片
subtitle string | null 否 算好的副标题,如角色名或模型名
onlineStatus string | null 否 仅 ChatMemberProfile:Agent 名片上的在线状态,原样交给状态点
ownerMemberId string 否 仅 ChatMemberProfile:Agent 的主人;界面再调一次 loadProfile 取主人的资料
agentIdentityId string 否 仅 ChatMemberProfile:给了才显示「复制 Agent ID」

附件

ChatAttachment

消息上的一个附件。地址不在这里:界面用 attachments.resolveUrls 把 artifact_id 换成能用的地址。

字段 类型 必填 含义
artifact_id string 是 附件 id,即上传返回的 id
file_name string 是 文件名
content_type string 是 MIME 类型;image/ 开头的画成图片
size_bytes number 是 字节数

ChatUploadTask

一次上传的进度,由 attachments.getTask 返回。

字段 类型 必填 含义
taskId string 是 任务 id
progress number 是 0 到 100
status "pending" | "uploading" | "finalizing" | "done" | "failed" | "cancelled" 是 finalizing:字节已传完,服务端还在处理,此时不能取消
speed number 否 每秒字节数;不给或为 0 时不显示速度
error string 否 失败原因

ChatImageViewerSlide

交给 mediaViewer.open 的一张图,见图片查看器。

字段 类型 必填 含义
src string 是 图片地址
alt string 否 替代文字
description string 否 这条消息的说明文字
messageId string 是 所在消息
attachmentIndex number 是 在这条消息全部附件里的下标(不是只数图片)

发送、编辑与分页

SendMessageInput

messaging.sendMessage 的参数。

字段 类型 必填 含义
conversationId string 是 发到哪个会话
text string 是 正文,Markdown 源文;只有附件时为空串。不分标题和正文,见输入框 · 展开编辑 规划中
attachments readonly ChatAttachment[] 否 附件整项。没有附件时不给(不是空数组)。宿主要把它们交给后端,并按附件定内容类型:全是图片为 "image",否则为 "file"(sendContentTypeFor)
replyToMessageId string 否 引用回复的消息 id,存为 parent_id
mentions readonly ChatMentionInput[] 否 结构化的 @。没有人被 @ 时不给。宿主要把它交给后端,否则被 @ 的人收不到通知
clientMessageId string 否 这条消息的去重键:消息区里本端那条的 client_msg_id,重试沿用同一个,SDK 的消息区每次都给。宿主把它作为后端的去重键交出去,后端在读回的消息上作为 client_msg_id 原样带回。没给时宿主自己生成键。实验性,名字和形状可能变。见 ChatStoreSendStartedEvent

ChatMentionInput 是 { type: "member"; memberId: string }(@某人)或 { type: "all" | "all_agents" }(@所有人、@所有 Agent)。

ChatSendOutcome

sendMessage 可以返回 void,也可以返回它:

字段 类型 必填 含义
blocked ChatSendBlocked 否 服务端内容过滤拦下了这条:没有存下,也没有投递

ChatSendBlocked:

字段 类型 必填 含义
refusalText string 是 给发送者看的说明,不能为空
seq number 否 显示位置;不给沿用本地的占位
timestamp string 否 时间;不给沿用本地的 created_at

被拦下的消息只留在发送者本端,显示说明和删除按钮,不能重试。

ChatThreadPage

messaging.loadThread 的返回值。

字段 类型 必填 含义
messages readonly ChatMessage[] 是 按 seq 升序(最旧在前);界面不重排
nextCursor string 否 还有更早的消息时给;不给表示到头了。是否到头只能由服务端判断,不要按条数推
headChangeSeq number 否 和这一页同一快照读出的改动日志最新编号,改动水位从它起,见宿主能力 · messaging 的改动日志。拿不到就不给,不要编 0

ChatThreadSincePage

messaging.loadThreadSince 的返回值之一(也可以直接返回数组)。

字段 类型 必填 含义
messages readonly ChatMessage[] 是 seq 大于 afterSeq 的消息,按 seq 升序
hasNewer boolean 是 这一批之后服务端还有没有更新的。false 时界面合并完这一批就停,不再多要一次。只能由服务端判断,不要按条数推;拿不准给 true
headChangeSeq number 否 和这一页同一快照读出的改动日志最新编号,改动水位从它起,见宿主能力 · messaging 的改动日志。拿不到就不给,不要编 0

ChatMessageEditInput

messaging.editMessage 的参数。

字段 类型 必填 含义
text string 是 新正文
attachments readonly ChatAttachment[] 是 改完之后这条消息的全部附件,按显示顺序:留下的旧附件在前,新上传的在后。没有就传空数组。宿主不要重排

正文和附件不会同时为空:那等于撤回,编辑框会禁用保存。

ChatMessageEdit

messaging.listMessageEdits 返回的一条修订,按时间升序返回。

字段 类型 必填 含义
id string 是 修订 id
createdAt string 是 修订时间
text string 是 当时的正文,已经从 content 里取出

已读与未读

数据 在哪 用来
会话未读条数 ChatConversation.unread_count 列表上的未读数
有没有未读的 @ ChatConversation.unread_mention 列表上的 @ 标记
当前用户读到哪 ChatConversation.last_read_seq 打开会话时的未读分隔条。读到新位置时用 MessageThread 的 onVisibleSeqChange 上报给你的后端
每个人读到哪、送达到哪 ChatReadCursorSnapshot,之后由 read、delivery 信号推进 单聊对勾、群聊已读人数
未读的 @ 列表 ChatUnreadMentionsPage 消息区的「@我」跳转

信号的字段见实时与同步 · 实时信号。

ChatReadCursorSnapshot

messaging.loadReadCursors 的返回值,打开会话时取一次。

字段 类型 必填 含义
cursors readonly { memberId: string; readUntilSeq: number; ackUntilSeq: number }[] 是 每个成员读到、送达到哪条 seq(含)。ackUntilSeq 不小于 readUntilSeq
memberCount number 是 会话的实际成员数,可能比 cursors 多
truncated boolean 是 大群里 cursors 被截断,比 memberCount 短

ChatUnreadMentionsPage

mentions.listUnread 的返回值。

字段 类型 必填 含义
mentions readonly ChatUnreadMention[] 是 未读的 @,可以只是一页
totalMe number 是 @我 的总数,不受分页影响
totalAll number 是 @所有人 的总数,不受分页影响

ChatUnreadMention:messageId、type("me" | "all")、senderId、seq、timestamp,都必填。跳转顺序按 seq,不按时间。

草稿

ChatComposerDraft

字段 类型 必填 含义
html string 是 输入框内容的 HTML,保留 @ 提及节点
replyTo ChatMessage | null 否 正在引用的消息;null 表示没有引用,不给表示这个宿主不存引用
files readonly File[] 否 已选还没发的文件。File 不能序列化,持久化时去掉,刷新后不保留
excerpts readonly ChatQuoteExcerpt[] 否 从 replyTo 里划选引用的片段(messageId、text,可选 offset / truncated)。[] 表示没有,不给表示这个宿主不存片段;目前至多一项,messageId 等于 replyTo.id

从本地存储读回旧草稿时自己检查一下:replyTo 至少要有字符串 id,不合格的整条丢掉;片段的 messageId / text 不是字符串、text 为空、或 messageId 不等于 replyTo.id 的,丢掉那一项。

其他能力用到的类型

类型 所在能力 字段
ChatWorkItem workItems id、kind("project" | "issue",即 ChatWorkItemKind)、label(显示的文字)、resourceUri(发送串里的地址)、projectId?(issue 所属的项目)
ChatWorkItemPage workItems items、nextCursor?
ChatConversationResource conversationResources 按 kind(ChatConversationResourceKind)区分的联合。每行(ChatConversationResourceBase):id、conversationId、messageId、messageSeq、senderId、messageAt(消息的时间)。ChatConversationAttachmentResource(kind 为 "image" | "file"):artifactId(必有,不带 artifact://)、fileName?、contentType?、sizeBytes?。ChatConversationLinkResource(kind 为 "link"):url、host?、title?
ChatConversationResourcesQuery conversationResources conversationId;可选 kinds、senderId、since / until(带时区的 RFC 3339 时间,如 2026-11-10T08:00:00Z;纯日期或不带时区的串 OpenMax 后端会拒(HTTP 422,经 OpenMax 适配器是 kind 为 validation 的 ChatSdkError),内存适配器照样拒;比的是 messageAt;since 含、until 不含)、query、cursor、limit(最多 100:更大的按 100 取、不报错,不是正整数的当没给)
ChatConversationResourcePage conversationResources items、nextCursor?
ChatMessageSearchQuery messageSearch conversationId、query;可选 cursor、limit(同上,最多 100)
ChatMessageSearchHit messageSearch messageId、conversationId、seq、senderId、createdAt、snippet(ChatMessageSearchSnippetPart[]:{ text, match },纯文本)
ChatMessageSearchPage messageSearch hits(可能少于所要,甚至为空)、nextCursor?
ChatAgentModelState agentConfig visible、configurable(当前用户能不能改)都必填;desiredModel?、effectiveModel?、desiredModelName?、effectiveModelName?、applyState?("ready" | "applying" | "failed",不给按 ready)、availableModels?、lastError?
ChatAgentModelOption agentConfig key(交给服务端的值)、displayName
ChatAgentGroupPolicy agentGroupPolicy groupScope(ChatAgentGroupScope:"open" | "allowlist" | "disabled")、groupAllowlist(会话 id,空为 [])、replyModes(会话 id → ChatAgentGroupReplyMode:"smart" | "mention",没有这一格按 mention)
ChatAgentPolicyApplyOutcome agentGroupPolicy { outcome: "applied" | "unconfirmed" | "offline" | "aborted" },或 { outcome: "rejected", reason: ChatAgentPolicyRejectReason }("forbidden" | "groupScopeDisabled" | "groupNotInAllowlist" | "unknown")
ForwardRequestBody forward message_ids(同一个源会话;forwardMessages 1–20 条,mergeForwardMessages 1–100 条)、targets(1–10 个 ForwardTargetInput:conversation_id、client_msg_id(1–64 个字符,每个目标各一个))、note?(ForwardNoteInput:text、mentions?)
ForwardResponseData<R> forward results(每个目标一个 R,按请求顺序)、succeeded_count、failed_count
ForwardTargetResult、MergeForwardTargetResult forward conversation_id、note(ForwardNoteResult:status 为 "succeeded" | "failed" | "blocked" | "skipped" | "absent"),再按 status 分:"succeeded" 带 messages(ForwardedCopy[]:source_message_id、message_id、seq、blocked、refusal_text?)或 message(MergedForwardCard:message_id、seq、blocked、refusal_text?);"failed" 带 error(ForwardTargetError:code、status、detail?)
ChatCardActionInput、ChatCardChoiceInput、ChatCardActionResult、ChatCardActionErrorKind cards 见交互卡片
ChatInboundSignal 及各变体 inboundDelivery 见实时与同步
ChatInboundTypingSignal inboundDelivery ChatInboundSignal 的一个变体:{ kind: "typing", conversationId, memberId, active }。宿主可以不发;发了,消息区不因它补拉。memberId 可能是当前用户自己,收方自己滤;active: true 之后 6 秒没有新的就当作停止。见实时与同步
ChatInboundDisconnectedSignal 规划中 inboundDelivery ChatInboundSignal 规划中的变体 { kind: "disconnected" },见实时与同步
ChatConnectionStatus 规划中 — "idle" | "connecting" | "connected" | "reconnecting" | "offline" | "unauthorized" | "failed":实时连接的状态
ChatRenderErrorArea 规划中 — 错误边界的区域,见渲染错误

desiredModel 是用户选的,effectiveModel 是正在跑的;切换中两者不同,applyState 为 applying。

Agent 运行

规划中

消息仓库里的运行:ChatAgentRun、ChatAgentRunPart、ChatAgentSubagent。实时事件 ChatAgentEventSignal 见接入自有后端 · 交给 SDK 的信号。