数据模型
宿主和组件之间传递的数据:消息、会话、成员、附件、已读与未读,以及发送、编辑、分页、草稿用的类型,逐个字段列出。
数据模型
宿主的能力收发的就是本页这些类型,从 @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 的信号。
