消息区
展示一个会话的消息,支持实时更新、表态、撤回与编辑、已读回执、引用回复,以及规划中的 Agent 运行进度和停止按钮。
消息区

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): message-thread-basic.tsx
"use client";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost } from "./kit";
export default function MessageThreadDemo() {
const host = useDemoHost();
const { conversations } = useDemoData();
const conversation = conversations[0]; // a group with text, images, a card and reactions
return (
<ChatHostProvider host={host}>
<div className="flex h-full flex-col bg-background text-foreground">
<MessageThread conversation={conversation} />
</div>
</ChatHostProvider>
);
}
演示使用内存宿主(useDemoHost)。实际项目里宿主来自 createChatHost,下面的示例都假定外层已有宿主。这个 MessageThread 是老消息区,读 react-query:宿主不带 QueryClientProvider,要你在外面自己包一层。
本页讲的是 @openmaxai/chat 的底层组件 MessageThread。它们不带样式根:SDK 样式表只作用在 SDK 组件自带的 .omx-chat 组件根之内,ChatRoot 本身不是样式作用域,所以照抄下面的示例渲染出来没有样式。要用它们,把它们放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。用 createChatHost 的宿主时改用 SDK 组件 CwsMessageThread,写法见快速开始。
何时使用
- 选中会话后的聊天主体:虚拟滚动的消息历史、未读分隔条、底部输入框,以及每条消息上的操作。
- 消息缓存自己管理:乐观发送、失败重试或丢弃、表态 / 撤回 / 编辑直接更新缓存。
- 不带头部,需要时在上方放
ChatHeader。 - 会话里有 Agent 时,规划中还会在消息下面画出它的运行进度、工具步骤和停止按钮,见 Agent 运行进度。
代码示例
基础用法
conversation-pane.tsx
import { MessageThread } from "@openmaxai/chat/message-thread";
export function ConversationPane({ conversation }: { conversation: ChatConversation | null }) {
return (
<MessageThread
key={conversation?.id}
conversation={conversation}
emptyState={<p>选择一个会话</p>}
/>
);
}
key 用会话 id,切换会话时滚动位置、回复对象、编辑态才会重置。
带已读回执的单聊

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): message-thread-dm.tsx
"use client";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost } from "./kit";
export default function DirectMessageDemo() {
// The demo host implements `messaging.loadReadCursors`, so your messages show read ticks.
// Send something: the other person "reads" it and replies a second later.
const host = useDemoHost();
const { conversations } = useDemoData();
const conversation = conversations.find((c) => c.id === "ada");
return (
<ChatHostProvider host={host}>
<div className="flex h-full flex-col bg-background text-foreground">
<MessageThread conversation={conversation ?? null} />
</div>
</ChatHostProvider>
);
}
单聊里自己的消息对方读过后显示双勾;群聊显示已读人数,点开看名单。需要宿主提供已读回执能力。
未读分隔条与已读位置
const [anchor] = useState(() => conversation.last_read_seq ?? 0); // 打开时定住
<MessageThread
key={conversation.id}
conversation={conversation}
firstUnreadAnchorSeq={anchor}
onVisibleSeqChange={(seq) => reportReadCursor(conversation.id, seq)}
/>;
seq 大于锚点的消息是未读,分隔条画在第一条未读上方并滚动到那里。消息区自己不上报已读位置:不传 onVisibleSeqChange,刷新后会话仍是未读。
用 OpenMax SDK 上传附件
OpenMax 的上传接口按会话走,所以 SDK 宿主只在 ConversationScope 里上传附件:每个打开的会话包一层,在它外面输入框不显示附件按钮,attachments.start 直接 reject。
import { MessageThread } from "@openmaxai/chat/message-thread";
import { ConversationScope } from "@openmaxai/chat-sdk/react";
<ConversationScope conversationId={conversation.id}>
<MessageThread key={conversation.id} conversation={conversation} />
</ConversationScope>;
消息操作
鼠标停在一条消息上(触屏轻点气泡),旁边出现操作栏;同一组操作也都在「更多」菜单里,键盘和读屏也能用。
| 操作 | 位置 | 什么时候有 | 需要的能力 |
|---|---|---|---|
| 复制 | 操作栏、菜单 | 文字消息和 Agent 回复,正文不为空。复制的是 Markdown 源文;成功时按钮短暂变成对号,失败时提示 | — |
| 表态 | 操作栏、菜单(「添加表态」) | 消息已发出、没被撤回,会话能发言 | messaging(addReaction、removeReaction) |
| 回复 | 操作栏、菜单 | 会话能发言 | — |
| 编辑 | 操作栏、菜单 | 自己的文字、图文消息,发出 15 分钟内 | messaging(editMessage) |
| 撤回 | 操作栏、菜单最后一项(红色) | 自己的文字、图文消息,发出 2 分钟内;有确认框 | messaging(recallMessage) |
| 置顶、取消置顶 规划中 | 菜单 | 消息已发出、没被撤回,会话能发言 | messaging(pinMessage、unpinMessage) |
| 插件加的操作 规划中 | 菜单,插件也可以放到操作栏 | 由插件判断,见消息操作插件 | 插件的 requiredPorts |
正在发送、发送失败、被拦下的消息只有「复制」;撤回提示、系统提示没有操作。旁观和只读的会话只有「复制」。能力缺了的操作不出现,不显示成灰色。
更多菜单
规划中
操作栏最右边是「更多」按钮(⋯),点开是这条消息能用的全部操作,顺序固定:回复、复制、添加表态、编辑、置顶或取消置顶、插件加的操作(按 messageActions 里的顺序)、分隔线、撤回。
- 桌面右键一条消息也打开这个菜单,菜单开在指针处。选中了文字时右键仍是浏览器自己的菜单,方便复制选中的那部分。
- 触屏仍是轻点气泡出操作栏,再点「更多」;长按仍交给系统选字,不打开菜单。图片例外:轻点图片打开查看器,长按图片出操作栏。
- 键盘: 消息列表里用
ArrowUp/ArrowDown在消息之间移动焦点,焦点所在的消息显示操作栏;Shift+F10或菜单键打开「更多」菜单。菜单里方向键移动、Enter执行、Escape关闭并把焦点还给那条消息。 - 执行一项后菜单关闭。撤回仍先弹确认框。
置顶
规划中
置顶过的消息在时间行显示一个图钉;ChatMessage 多两个字段 pinned_at、pinned_by。点「置顶」调 messaging.pinMessage(messageId),先乐观显示,失败时回滚并提示;unpinMessage 相同。别人置顶、取消置顶经 messages 信号补拉后更新。会话里所有置顶消息的列表不在本版范围内。
Markdown 正文
人发的文字消息和 Agent 的回复,正文都是 Markdown,按同一套规则画。画法由宿主的 render(renderMessageText、renderMarkdown)实现;createLocalPorts 给的默认 render 就按本节画,你自己实现 render 时也照本节,见宿主能力 · render。规划中
| 写法 | 画成 |
|---|---|
**x**、*x*、~~x~~、`x` |
粗体、斜体、删除线、行内代码 |
行首 - 、1. |
无序、有序列表,可以嵌套 |
行首 > |
引用 |
行首 # 到 ###### |
加粗加大的一行,不是页面上真正的标题元素,免得打乱页面的标题层级 |
| 三个反引号包住的代码块 | 等宽、可横向滚动;写了语言的在右上角标出语言名,带「复制代码」按钮。不做语法高亮 |
| GFM 表格 | 表格,宽了横向滚动 |
[x](url)、裸网址 |
链接,新标签页打开(rel="noopener noreferrer") |
 |
不加载外部图片,显示成指向这个地址的链接 |
--- |
分隔线 |
- 换行就是换行。 正文里的单个换行照样换行,不用在行尾加两个空格,和普通聊天一样。
- 不渲染 HTML。 正文里的 HTML 标签原样显示成文字。
- 只认安全的链接。 只有
http:、https:、mailto:和宿主认的站内链接(如知识库链接)成为链接,其他(javascript:等)显示成文字。 - @ 提及和工作项引用照旧。
@加名字照常画成提及胶囊(带data-mention-*),工作项引用照常画成 chip,渲染正文的那一层拿到workReferences才可点(默认render经ports.workReferences自动接上;没拿到时 chip 照画、但不可点);名字里的_、*不会被当成格式。 - 代码里不认任何东西。 行内代码和代码块里的
@、链接、格式都原样显示。 - 旧消息也按 Markdown 画。 早先发的消息里的
*、行首的1.、#会显示成格式。 - 列表和预览用纯文本。 会话列表的最后一条消息、草稿预览、引用条、系统通知里去掉 Markdown 符号,只留文字。
- 复制、编辑用源文。 复制拿到 Markdown 源文;编辑时输入框里是格式化后的样子,存回去仍是 Markdown。
文案在 chat 命名空间:markdown.copyCode(「复制代码」)、markdown.codeCopied(「已复制」)。
Agent 运行进度
规划中
宿主提供 agentRuns 能力后,MessageThread 自动画出 Agent 的运行进度,不用单独挂载组件。数据来自消息仓库。
运行进度
运行一出现(排队中)就在触发它的那条消息下面显示一行进度;没有触发消息时出现在消息区底部。同一会话里有几次运行时各占一行。下表括号里是对应的 ChatAgentRun.status 值;按 AG-UI 的规则,不认识的 outcome 按成功处理;RUN_ERROR 出现在 RUN_FINISHED 之后时,运行算失败(error)。
| 状态 | 来自 | 显示 |
|---|---|---|
排队中(queued) 我们的扩展 |
外层帧 queued: true |
Agent 头像和名字、「排队中」、停止按钮 |
进行中(running) |
RUN_STARTED |
Agent 头像和名字、「正在执行」、当前工具名、已用时间、停止按钮 |
已完成(finished) |
RUN_FINISHED,outcome 为 success 或没有 |
折叠成一行摘要(如「用了 3 个工具 · 12 秒」),挂在 Agent 的回复上 |
已停止(cancelled) |
RUN_FINISHED,outcome 为 cancelled |
「已停止」 |
出错(error) |
RUN_ERROR,包括 RUN_FINISHED 之后又来的 |
「出错了」和 message |
等待回答(interrupted) |
RUN_FINISHED,outcome 为 interrupt(第二期) |
「等待回答」,点击跳到对应的审批卡 |
摘要靠回复消息的 metadata.run_id 找到对应的运行;回复还没到时摘要先留在触发消息下面。
排队超过 2000 毫秒才显示「排队中」。这个阈值是整个聊天的一个设置,在创建聊天时设一次:createChatHost 的配置项 queuedRunDelayMs(见适配器接口 · createChatHost({ adapter })),自己实现宿主时是 agentRuns.queuedRunDelayMs。消息区、运行列表和头部计数都用它,组件没有单独设置阈值的属性。Agent 在群里只在被 @ 时回复这类策略由 Agent 一侧执行,后端不知道哪些消息会被处理,所以每条派给 Agent 的消息都会生成运行,被忽略的消息靠 Agent 立刻以 RUN_FINISHED 结束;阈值让这类很快结束的运行不在群里一闪而过。运行开始或排队超过阈值之前,它也不出现在 Agent 的运行列表里。
工具步骤
点开进度显示工具步骤,每次工具调用一行,按开始的先后排列:
| 列 | 来自 |
|---|---|
| 工具名 | TOOL_CALL_START 的 toolCallName,可以用 agentRuns.describeTool 换成好读的名字 |
| 状态 | 进行中:收到 TOOL_CALL_START;完成:收到 TOOL_CALL_RESULT |
| 用时 | 从 TOOL_CALL_START 到 TOOL_CALL_RESULT |
| 参数、结果 | TOOL_CALL_ARGS、TOOL_CALL_RESULT。给谁看由 Agent 的主人配置;没收到时这一列不显示 |
运行结束时还没收到结果的工具调用,随运行的结束状态显示为已停止或出错。子 Agent 的工作(带同一个 subagentRunId 的事件)在这次运行的工具步骤里显示为一组,组头是 SUBAGENT_STARTED 的 name 和这次调用的状态(进行中、完成、暂停、已停止、出错;暂停表示这次调用在等外部输入,之后的运行可以接着它继续)。调用还开着、且有停止权限时,组头有一个停止按钮,只停这一次调用,运行继续 我们的扩展;停下后组头显示「已停止」,组里还没收到结果的工具调用也显示为已停止。第二期加上 STEP_STARTED / STEP_FINISHED 后,工具调用按步骤分组。
停止按钮
停止针对的是一次运行,或运行里的一次子 Agent 调用,不是整个 Agent。运行在排队或进行中、且外层帧的 permissions.cancel 为 true 时显示;服务端只给运行的发起人和 Agent 的主人这个权限(没有发起人的运行只给主人)。进度行上的按钮停整次运行,点击后调用 agentRuns.cancelRun:
- 请求发出到运行结束之间,按钮显示「正在停止」并禁用。
- 运行以
outcome为cancelled的RUN_FINISHED结束,进度改为「已停止」,会话里每个人都看得到。 - 请求失败时按钮恢复,提示走宿主的
attention。
工具步骤里子 Agent 调用组头上的按钮只停这一次调用 我们的扩展:调用 agentRuns.cancelRun 时多带 subagentRunId;调用以 code 为 "cancelled" 的 SUBAGENT_ERROR 结束,组头改为「已停止」,运行继续,进度行不变。按钮同样看 permissions.cancel,等待期间同样显示「正在停止」。
已知限制:停止主会话里的运行
Agent 用一个主会话处理所有会话的消息,再把部分工作交给子 Agent。停止一个正在主会话里执行的运行,可能会把主会话一起打断,连带影响 Agent 在其他会话里正在做的事。等 Agent 改成每个会话一个独立会话之后,这个限制才会消失。
逐字输出
规划中
Agent 的回复边生成边显示,不用等整条写完。逐字输出只是预览:回复写完后,Agent 照常发一条带 metadata.run_id 的消息,这条消息才是记录。
- 数据: Agent 在运行里发
TEXT_MESSAGE_START→ 若干TEXT_MESSAGE_CONTENT(每个带一段delta)→TEXT_MESSAGE_END,经agent_event帧推送。仓库把同一个messageId的delta按run_seq拼起来,存成运行的一段text,status为streaming,收到TEXT_MESSAGE_END后为done。 - 显示的位置: 在运行进度行下面,像一条 Agent 的消息气泡,按 Markdown 画;没收尾的代码块、列表照样先画出来。末尾有一个闪动的光标。
- 换成正式消息: 带
metadata.run_id且metadata.stream_message_id等于这段文字的messageId的消息到达后,正式消息原地替换预览气泡,位置不跳。正式消息到了之前,预览一直留着。 - 一次运行可以有几段文字(几个
messageId),按开始的先后各占一个气泡。 - 运行停止或出错时,已经出来的文字留在气泡里,气泡下方标「已停止」或「出错了」。这样的预览不存储,刷新后不再出现;Agent 发了正式消息的以消息为准。
- 漏了片段: 按
run_seq缺号补齐,打开会话时从运行快照重建已经出来的文字,所以中途进来的人看到的是完整的预览。 - 滚动: 停在底部时跟着新字往下滚;不在底部时不动,也不算新消息、不出「有新消息」按钮,正式消息到达后照常算。
- 限流: 一帧画面只重画一次,片段来得再密也不会每个片段重画一次。
- 预览气泡没有操作栏,不能复制、表态、回复,正式消息到了才有。
- 宿主没有
agentRuns,或 Agent 不发TEXT_MESSAGE_*,就没有逐字输出:照常等整条消息到达。
单独使用
进度行、工具步骤和停止按钮也可以单独引入,放进你自己的布局:
import { AgentRunProgress, AgentRunSteps, AgentStopButton } from "@openmaxai/chat/agent-runs";
<AgentRunProgress runId={runId} conversationId={conversation.id} />;
<AgentRunSteps runId={runId} conversationId={conversation.id} />;
<AgentStopButton runId={runId} conversationId={conversation.id} />;
<AgentStopButton runId={runId} subagentRunId={subagentRunId} conversationId={conversation.id} />;
| 组件 | 属性 | 说明 |
|---|---|---|
AgentRunProgress |
runId、conversationId?、defaultExpanded? |
一次运行的进度行,内含工具步骤和停止按钮 |
AgentRunSteps |
runId、conversationId? |
只有工具步骤 |
AgentStopButton |
runId、conversationId?、subagentRunId? |
只有停止按钮;没有停止权限或运行已结束时不渲染。带 subagentRunId 时只停这一次子 Agent 调用 我们的扩展,这次调用已结束时也不渲染 |
运行按 runId 从仓库里找。不绑定会话的运行(只在 Agent 面板出现)不传 conversationId。
agentRuns 能力见接入自有后端 · Agent 运行。
API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
conversation |
ChatConversation | null |
必填 | 当前会话,即列表里的那个对象 |
emptyState |
ReactNode |
— | conversation 为 null 时显示 |
composerChrome |
"card" | "flush" |
"card" |
输入框外框。输入区贴边(如浮窗)用 flush |
firstUnreadAnchorSeq |
number |
— | 打开时的已读位置,决定分隔条和初始滚动。0 表示全未读。打开期间保持不变 |
onVisibleSeqChange |
(maxVisibleSeq: number) => void |
— | 可视范围变化时回调视口内最后一条消息的 seq |
provisioningBlocked |
boolean |
false |
对端 Agent 开通中:输入框只读并显示提示 |
autoFocusOnOpen |
boolean |
false |
打开时聚焦输入框;触屏输入时忽略,免得弹出软键盘(见响应式) |
showConnectionStatus 规划中 |
boolean |
true |
顶部是否画连接状态条 |
旁观的会话、Agent 协作会话、dm.can_send === false 的单聊自动只读。
依赖的能力
宿主没提供的能力,对应功能不显示。
| 能力 | 提供后用户能用到 |
|---|---|
messaging(addReaction、removeReaction) |
表情选择器和表态标签,点击切换,悬停看谁表的态 |
messaging(recallMessage) |
自己的消息 2 分钟内可撤回(有确认框) |
messaging(editMessage) |
自己的文字和图文消息 15 分钟内可编辑,附件可增删。Enter 保存,Shift+Enter 换行,Esc 取消 |
messaging(listMessageEdits) |
点「(已编辑)」看旧版本 |
messaging(loadReadCursors) |
单聊对勾,群聊已读人数 |
messaging(loadMessage) |
引用的原消息不在已加载范围时单独取回 |
mentions |
@me · N 胶囊:点击跳到下一条提及,长按全部标为已读 |
inboundDelivery(subscribe) |
新消息、表态、回执、卡片结果无需刷新 |
messaging(loadThreadSince) |
别人的新消息实时出现;没有时要刷新才看到,表态仍实时 |
attachments(subscribeTasks) |
发送中附件的进度条和取消按钮 |
attachments(resolveUrls) |
收到的附件能显示;没有时显示「不可用」 |
profileCard |
头像可点,见名片 |
cards |
卡片上的按钮和选项(装上卡片插件);没有时卡片按只读画,见交互卡片 |
agentRuns 规划中 |
Agent 运行进度、工具步骤、停止按钮和逐字输出,见上文 |
messaging(pinMessage、unpinMessage) 规划中 |
菜单里的置顶、取消置顶,见置顶 |
mediaViewer |
图片可点开,见大图查看器 |
每项能力对应的宿主方法见 API 参考,输入框的要求见输入框。
无障碍
- 操作栏按钮都有标签,鼠标悬停时出现,触屏点气泡出现。表态标签带
aria-pressed。 - 已读对勾是
role="img"(「已发送」/「已读」);群聊已读人数按钮带aria-expanded,打开带标签的role="dialog"名单。 - 可点图片是
role="button",标签「查看图片」。编辑框是带标签的role="textbox",aria-multiline。 - 「更多」菜单是
role="menu",每项role="menuitem",撤回项的名称里说明会撤回。「更多」按钮带aria-haspopup="menu"和aria-expanded。规划中 - 逐字输出的气泡带
aria-busy="true",片段不逐个播报;写完由运行进度行的实时区域播报一次。规划中 - 规划中的运行进度行是一个带名称的区域,状态变化(排队、开始、完成、停止、出错)经礼貌级(
polite)实时区域播报,每次工具调用不单独播报。停止按钮是原生按钮,名称里带 Agent 的名字。规划中
常见问题
没有表态和已读回执。
宿主没有提供表态或已读回执能力。自建宿主可以提供;createChatHost 提供哪些见已知限制 · 默认宿主。
能只凭会话 id 打开会话吗(深链)?
能。用 useConversation(id) 取会话:不在已加载列表里时,它调宿主的 conversations.loadConversation 按 id 取,取到后照常传入。会话不存在或无权访问时它返回 undefined,由你显示提示。宿主没有 loadConversation 时,不在已加载列表里的会话取不到,按不存在处理。 规划中
读过的会话刷新后又变成未读。
传 onVisibleSeqChange,把值上报给后端。
