OpenAgentPack Kit
组件通用

Message 对话气泡

展示用户与 Agent 的消息,支持流式状态、执行过程、文件和技能标签

用于展示单条用户或 Agent 消息。用户正文按纯文本展示,Agent 正文支持 Markdown, 思考过程、工具调用和交付文件按消息分片渲染。

import { Message } from "@openagentpack/kit-chat-ui";

使用 copy-in 接入时执行:

pnpm kit:add message

该命令复制源码及依赖组件,不自动安装 npm 包;渲染依赖的安装见 Markdown 接入,主题接入见组件总览。 以下示例使用 workspace 包导入;copy-in 后改为项目中的组件路径。

何时使用

  • 在已有页面或面板中展示一条消息,并由调用方提供消息内容和状态。
  • 展示包含思考过程、工具调用、文件或技能标签的 Agent 对话。
  • 多条消息的排列、滚动与历史跟随使用 MessageList; 同时需要输入框时使用 Chat。

代码演示

每个演示都可查看源码、复制接入命令,并切换桌面或手机视口。预览直接渲染当前 kit-chat-ui 组件,使用本地消息数据,不连接 Kit server 或 Cloud。

基本用法

通过 message 传入一条 ChatMessage。role="user" 靠右,role="assistant" 靠左; 用户输入中的 Markdown 标记保留原文,Agent 回答中的 Markdown 正常排版。

Message(基本用法)

工作区样式

variant="workspace" 使用体验页当前的消息布局:用户保留右侧气泡,Agent 正文使用无外框布局。 切换布局可比较同一组消息;variant 默认仍为 "default"。

Message(工作区样式)

data-kit-appearance="workspace" 选择工作区色板,variant="workspace" 选择组件布局, 两者分别设置。工作区用户气泡在窄屏最多占消息行宽度的 85%,sm 及以上为 75%; 阅读列宽度由外层容器提供,MessageList 和 Chat 使用 --kit-chat-width 居中限制宽度。

消息状态与流式更新

切换角色和消息状态,观察发送、生成失败与中断提示。Agent 处于 streaming 时, 正文末尾显示“生成中…”,点击“追加内容”模拟同一条消息的累计快照更新。

Message(消息状态与流式更新)

更新时保持消息和分片的 id 稳定;组件不会自行发送请求、计时生成文本或根据连接状态推断完成。 消息尚未出现时的等待提示由 MessageList.pending 提供。

富内容与执行过程

连续的 reasoning、tool 分片组成可折叠的执行过程;正文、文件等其他分片打断分组。 展开“执行过程”,再展开对应步骤,可查看思考原文、输入参数和执行结果。

Message(富内容与执行过程)

运行中的执行组保持展开,正文到达或消息完成后收起;组内思考与工具步骤默认收起,可手动展开。 相同分片的内容更新保留用户手动开合。思考状态来自分片自己的 status,不由整条消息状态推断。 未知内容保留为可展开的安全文本。

更多工具状态、Markdown、代码和图表用法见富内容分片。 子 Agent 的内嵌卡片通过 multiAgent 接入,见 Chat 多 Agent 对话。

文件与操作回调

用户上传的 attachment 与 Agent 交付的 artifact 都复用 FileCard。 工作区布局将用户附件独立放在正文气泡上方;上传附件只展示文件信息。

Message(文件与操作回调)

交付文件的名称触发 onArtifactOpen,独立下载按钮触发 onArtifactDownload。 只提供下载回调时,文件名触发下载;都不提供时只展示信息。 已完成且有正文的 Agent 消息显示复制入口,onCopy 收到 Markdown 原文和原始换行。 此演示仅显示回调参数,实际预览、下载和宿主复制由业务方实现;省略 onCopy 时使用浏览器剪贴板。

技能标签

传入当前 Agent 的技能名,将用户消息中的已知协议 token 原位还原为技能标签。 取消勾选可查看未提供名单时的原文;未知技能始终保留原文。

Message(技能标签)

Message 只还原消息展示,不执行技能。输入框的选择与提交见 Sender 和 Chat。

API

Message

属性说明类型默认值
message必填,单条消息的展示模型,见下表ChatMessage—
variant消息布局;工作区下用户为气泡,Agent 正文无外框"default" | "workspace""default"
onArtifactOpen点击交付文件名称时打开预览,与下载回调独立(fileId: string, contentType?: string) => void—
onArtifactDownload交付文件下载,由调用方通过 Kit server 或自有后端完成(fileId: string) => void—
onCopyAgent 回答原文复制;成功后 resolve,失败时抛出异常(text: string) => void | Promise<void>浏览器剪贴板
skills当前 Agent 的技能名,用于还原用户正文中的已知技能 tokenstring[]—
multiAgent子 Agent 状态、历史查询与重试能力,来自 useChat().multiAgent;省略时不显示子 Agent 卡片ChatMultiAgent—

组件只消费展示模型与回调,不解析 Provider SSE,也不直接请求文件。真实接入由 useChat 提供 messages 和 multiAgent。组件内部的气泡、内容和状态容器不单独导出。

ChatMessage

从 @openagentpack/kit-sdk/messages 导入类型;消息内容和状态通常由运行时生成。

属性说明类型必填
id稳定的消息标识;累计快照更新时保持不变string是
role消息角色,决定对齐方式和正文渲染"user" | "assistant"是
parts按展示顺序排列的内容分片,见下表MessagePart[]是
status消息状态,见下方状态说明MessageStatus是
threadId消息所属线程的标识string否
createdAt消息创建时间;缺少分片开始时间时作为执行耗时的起点string否
clientMessageId乐观消息与服务端回显关联使用的标识string否

MessagePart

每个分片都有可选的 id: string。真实消息沿用 core 提供的稳定分片 id,避免累计快照更新时 重挂内容、丢失展开状态或重复播放入场动效。只合并相邻的文本或思考分片,保留正文、工具、 交付文件和状态的相对顺序;工作区用户附件按上面的独立布局展示。

type内容字段展示行为
texttext: string用户正文为纯文本,Agent 正文为 Markdown
reasoningtext: string、可选 status、startedAt折叠的思考步骤;状态为 streaming / done / failed / interrupted,缺省不代表完成
tooltoolId、name、status、可选 input、output、startedAt、endedAt工具步骤;状态为 running / done / error,参数和结果按数据展示
artifactartifact: { file_id, filename?, content_type?, size? }Agent 交付文件,可接预览与下载
attachmentfile: { file_id, filename?, mount_path?, size? }用户上传文件,只展示信息
statustext: string内容流中的状态文字,与整条消息的 status 不同
sub-agentthreadId: string配合 multiAgent 在派发位置展示只读子 Agent 卡片
unknownlabel: string、value: unknown安全的可展开文本,不执行 HTML

MessageStatus

值用户消息Agent 消息
pending发送中…发送中…
streaming不显示额外状态标签正文末尾显示“生成中…”,完成后消失
done不显示状态标签不显示状态标签;有正文时展示复制入口
failed发送失败生成失败
interrupted已中断已中断

单条消息完成不等于整个 Agent 回合结束;执行与连接状态的区分见 SDK 接入术语。

语义结构

区域当前结构与交互
消息正文用户为保留换行的文本;Agent 使用 Markdown 的标题、列表、链接等语义标签
执行过程原生 details / summary;展开组后可继续展开思考或工具步骤
文件操作文件名与下载使用独立按钮,键盘可分别触发;用户附件没有操作入口
回答操作完成态的复制按钮及可读的成功、失败反馈
未知内容原生 details / summary,内容以文本展示

组件当前没有 classNames、styles 或任意属性透传接口。布局通过外层容器和 variant 调整, 色板与排版通过主题 token 统一管理。

主题变量(Design Token)

引入 @openagentpack/kit-chat-ui/theme.css 后使用以下冻结 token。下表列出亮色值, 暗色由 data-kit-theme="dark" 使用对应色板;工作区色板在父容器启用。

Token用途默认主题工作区主题
--kit-user-bubble用户气泡背景#eef0ff#efefef
--kit-assistant-bubble默认布局的 Agent 气泡背景;工作区布局不使用外层气泡#f6f7fb#f7f7f7
--kit-fg正文颜色#101322#171717
--kit-fg-muted状态与次要文字#5b6478#737373
--kit-border默认布局的气泡边框#e3e6ef#e5e5e5
--kit-radius气泡圆角14px16px
--kit-text-body正文字号15px15px
--kit-leading-body正文行高1.6251.7

分片入场消费 --kit-animate-overlay-in,执行过程使用冻结的展开与过渡 token; prefers-reduced-motion 下关闭动画。同一稳定分片的快照更新不重放入场动画。 更多主题配置见组件总览。

本页目录