消息样式
以下为演示数据。点击消息查看右侧详情，上一条／下一条按当前示例顺序切换。右键或长按打开消息菜单，操作仅在本页演示。
全部
文本
富文本
系统事件
异步消息
消息调试
群聊样式
{
"schemaVersion": 1,
"text": "你好，这是一条普通文本消息。"
}消息类型
消息类型决定整条消息的用途；内容分段决定消息内部展示文字、媒体或引用的方式。
类型 | 字段值 | 用途与样式 |
|---|
文本 | text | 普通文字气泡，自己的消息靠右，其他人的消息靠左。 |
富文本 | rich_text | 气泡内可以组合 Markdown、媒体和引用等内容分段。 |
系统事件 | system_event | 用于群聊变化、话题改名、撤回和评论回复等通知；聊天操作以居中提示显示，评论回复使用评论卡片。 |
异步消息 | process | 先发送处理提示，再在同一条消息中逐步更新进度和最终结果；所有状态沿用发送者一侧布局，等待与失败不使用气泡，仅显示图标和文字，处理中使用动态圆点，完成直接展示结果。 |
系统消息
以下列出当前所有系统事件。上方选择“系统事件”可逐条查看实际样式与详细信息。
类型 | 字段值 | 用途与样式 |
|---|
创建群聊 | chat.group.created | 创建群聊时发送；可以同时显示建群时邀请的成员。 |
邀请成员 | chat.group.members_added | 邀请新成员或重新邀请已退出的成员时发送。 |
移除成员 | chat.group.member_removed | 群主或管理员移除成员时发送。 |
主动退群 | chat.group.member_left | 成员主动退出群聊时发送。 |
话题改名 | chat.topic.renamed | 话题名称修改时显示原名称和新名称。 |
撤回消息 | chat.message.recalled | 发送者撤回消息或管理员撤回他人消息时显示对应提示，不展示已撤回正文。 |
评论回复 | community.reply_comment | 评论收到回复时发送；显示回复内容和原评论卡片，不使用居中提示。评论不可见时显示错误占位。 |
详细信息字段
调试面板显示当前前端消息的数据。缺失字段显示“未提供”；发送状态描述消息是否发出，处理状态描述异步消息的处理进度。
标题 | 字段 | 作用 |
|---|
消息标识 | id ← messageSn | 服务端保存后的正式消息 SN，用于定位、回复、撤回。发送确认前，本地暂用客户端标识占位。 |
客户端标识 | clientMessageId | 发送前生成的 UUID，将本地待发送消息与服务端回执对应，避免重复显示并保持界面状态稳定。服务端生成的部分消息可能没有此值。 |
来源键 | source_key → sourceKey | 消息内部来源标记；管理员消息页通过专用只读接口按需读取，普通列表和实时通知不返回。示例未读取真实消息来源。 |
消息类型 | messageType | 整条消息的用途：text、rich_text、system_event 或 process。 |
发送时间 | createdAt | 本地发送时先记录时间，服务端确认后采用返回的 sentTime；用于排序展示、相对时间和时间分组。调试面板保留原始值。 |
更新时间 | updatedAt | 来自服务端 updateTime，表示消息最后更新的时间；已完成的异步消息菜单使用它显示完成时间，撤回提示菜单使用它显示撤回时间。 |
发送者 | sender.name | 发送者的原名，作为昵称或发送者名称展示。 |
发送者标识 | sender.characterId | 发送角色的公开 ID，可用于打开角色资料。 |
发送者本地键 | sender.key | 前端区分发送者的内部键。用于判断是否为自己的消息、稳定渲染与选择；不是数据库编号。“本地”指前端内部使用。 |
发送者类型 | sender.kind | character 表示角色，agent 表示助手。部分指定角色也按助手样式展示。 |
发送状态 | status | pending 发送中、sent 已发送、failed 发送失败；描述消息发送过程。 |
处理状态 | processStatus | 异步消息的处理状态：queued 等待处理、running 处理中、completed 已完成、failed 处理失败。 |
系统事件 | systemEventType | 系统消息的具体事件，例如 chat.message.recalled、chat.topic.renamed 或 chat.group.*，决定事件的提示样式。 |
回复目标 | replyToMessageId | 被回复消息的标识，对应服务端 replyToMessageSn；用于关联原消息并展示摘要。 |
回复数量 | replyCount | 回复这条消息的条数，用于回复列表入口，不是当前已加载消息数量。 |
已读人数 | messageReadProgress | 独立于消息对象的已读统计，以已读人数／统计人数显示；没有统计数据时显示“未提供”。 |
内容分段 | parts | 按顺序渲染的内容数组。调试面板的消息内容组分别显示数据库原始content和接口返回content JSON（本地示例不读取数据库），再在同一解析结果区块展示分段摘要与完整parts；本地缺少content时明确显示未提供，具体字段见下表。 |
错误信息 | error | 当前主要记录前端发送失败；异步消息处理失败的说明通常由内容分段提供，不一定映射到此字段。 |
发送者头像 | sender.avatarUrl | 头像图片地址；群聊样式使用。没有图片时沿用角色头像组件的默认展示。 |
发送者颜色 | sender.color | 头像等身份展示的颜色。 |
发送者简介 | sender.introI18n | 身份相关展示可使用的简介，不是消息正文。 |
发送者角色资料 | sender.character | 可选的完整角色资料对象，供身份展示复用；不是独立的消息内容。 |
内容分段
一条消息可以包含多个分段，按 parts 数组的顺序展示。例如，一段 Markdown 后面可以接一张图片或一条来源引用。
分段类型 | 内容字段 | 展示方式 |
|---|
text | text | 纯文字，保留换行。 |
markdown | text | Markdown 正文，可包含强调、列表、链接与代码等。 |
processing | 无额外字段 | 正在处理的动态指示。 |
comment | title、comment | 评论事件标题与评论卡片，使用现有评论组件。 |
image | url、name | 图片；name 用于替代文字。 |
audio | url、name | 带播放控件的音频。 |
video | url、name | 带播放控件的视频。 |
file | url、name | 以文件名展示的链接。 |
citation | url、title、excerpt | 来源链接标题与摘录。 |
时间、回复与状态
- 居中时间
- 首条消息、跨日期或与上一条相隔超过五分钟时显示时间分隔条。它由发送时间生成，位于消息区块外，不是一条独立消息。
- 精确时间
- 右键或长按消息打开菜单，可查看完整发送时间；已完成的异步消息还显示完成时间，撤回消息显示撤回时间。菜单可复制当前可见消息，各操作使用统一图标。键盘聚焦消息后可按 Shift + F10 打开菜单。
- 回复
- 回复目标指向原消息，消息内可显示原消息摘要；回复数量表示回复该消息的条数。已撤回的目标显示撤回提示。
- 发送状态
- pending 为发送中，sent 为已发送，failed 为发送失败。失败消息显示错误信息和重试入口。
- 处理状态
- queued 为等待处理，running 为处理中，completed 为已完成，failed 为处理失败。异步消息先发出处理提示，再在同一条消息中更新进度和结果；发送成功并不表示处理已经完成。
- 已读
- 自己的已发送普通消息可显示未读、部分成员已读或已读；调试面板的已读人数为已读成员数／统计成员数，不等于异步消息的处理进度。