OpenMax
免费试用

消息区

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

消息区

message-thread-basic demo

演示截图。演示跑在内存里的示例 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,切换会话时滚动位置、回复对象、编辑态才会重置。

带已读回执的单聊

message-thread-dm demo

演示截图。演示跑在内存里的示例 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")
![x](url) 不加载外部图片,显示成指向这个地址的链接
--- 分隔线
  • 换行就是换行。 正文里的单个换行照样换行,不用在行尾加两个空格,和普通聊天一样。
  • 不渲染 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,把值上报给后端。