OpenMax
免费试用

核心概念

本站通用的词汇:宿主、能力、适配器、会话与成员、消息、运行、交互卡片、消息仓库、实时帧与信号,以及它们怎么拼在一起。

核心概念

本页是全站的词汇表。其他页面用到这些词时都是这里的意思。

import {
  ChatProvider,
  ChatRoot,
  ChatSplitLayout,
  ConversationHeader,
  CwsConversationList,
  CwsMessageThread,
  createChatHost,
} from "@openmaxai/chat-sdk/react";
import { createMemoryAdapter } from "@openmaxai/chat-sdk/testing";

// 宿主:组件需要的一切都从这里取;适配器把它接到某个后端,这里是浏览器里的内存后端
const host = createChatHost({ adapter: createMemoryAdapter() });

<ChatProvider host={host}>
  <ChatRoot style={{ display: "flex", height: "100%" }}>
    <ChatSplitLayout
      open={selected !== null}
      list={<CwsConversationList selectedId={selectedId} onSelect={(c) => setSelectedId(c.id)} />}
    >
      {selected && (
        <>
          <ConversationHeader conversation={selected} onBack={() => setSelectedId(null)} />
          <CwsMessageThread conversation={selected} />
        </>
      )}
    </ChatSplitLayout>
  </ChatRoot>
</ChatProvider>;

样式来自 @openmaxai/chat-sdk/styles.css,只作用在 SDK 组件(Cws*)自带的组件根之内,所以它们要放在 ChatRoot 里。完整可运行的写法见快速开始。

宿主

宿主(ChatHost)是把聊天组件连到你的后端的对象。组件不直接发请求、不碰路由、不读写浏览器存储,这些都通过宿主完成。宿主用 <ChatProvider> 装入一次,createChatHost 造的和自己实现的都一样。

获得宿主的方式 适用场景
createChatHost(config)(@openmaxai/chat-sdk/react) OpenMax 后端
自己实现 identity、messaging、inboundDelivery,其余用 createLocalPorts() 补齐 其他后端、mock、测试

自己实现的宿主只能配 @openmaxai/chat 的组件(ConversationList、MessageThread 等):CwsConversationList、CwsMessageThread 这些 SDK 组件要读 createChatHost 宿主才有的内部件,装手写宿主时一渲染就抛错。@openmaxai/chat 的组件不带样式根,样式表够不着它们,要你把它们放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式,见接入自有后端。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。

宿主的必填部分:identity、messaging、inboundDelivery、drafts、render、attention、i18n、instanceScope、attachments。后六项 createLocalPorts() 都能提供。

能力

能力是宿主上的一个字段,例如 messaging、cards、mentions、profileCard。必填能力是所有组件都离不开的,宿主必须提供。可选能力宿主可以不提供,不提供时分两种情况:

  • 大多数组件和输入框插件:只隐藏用到这项能力的那块界面,其余照常。 例如没有 profileCard,头像点不动,聊天照常可用。输入框插件也一样:缺能力的插件不会装上,例如没有 workItems,输入框里就没有 #。
  • 会话列表和群管理组件:直接报错。 这两个组件整个建立在对应能力上(分别是 conversations、groupManagement),没法降级。这两项对整个 SDK 是可选的,但用了对应组件就必须提供。

类型名里沿用 Port(如 ChatCardsPort),指的就是能力。完整列表和缺了会怎样见能力。

适配器

适配器是某个后端的具体实现:保持连接、把服务端的帧翻成事件、提供读接口,由 SDK 包装成宿主。OpenMax 的适配器是 @openmaxai/chat-openmax 包里的 createOpenMaxAdapter,别的后端写自己的适配器交给 createChatHost({ adapter })。见架构总览,接口见适配器接口。

会话

会话(ChatConversation)是一个单聊(DM)或群聊(GROUP)。CwsConversationList 展示会话列表,CwsMessageThread 展示一个会话的消息,两者都以会话对象作为输入。

成员

成员(ChatParticipant)是会话里的一方,kind 为 human(人)或 agent(Agent)。Agent 和人一样收消息、发消息、被 @,常驻在会话里。每个 Agent 归在一个人名下,这个人是它的主人;主人能在和它的单聊里切换模型。

此外还有旁观者:不是会话成员、但能只读地看这个会话的人,例如 Agent 的主人查看 Agent 和别人的私聊。成员能看到的实时内容,旁观者也能看到。

消息

消息(ChatMessage)是会话里的一条记录:文本、图片、文件、卡片、系统提示,或 Agent 的回复。每条消息有一个整数 seq,在会话内从 1 递增、不重复。排序和断线后补齐都靠它。

运行

规划中

运行是 Agent 处理一次输入的全过程:排队、开始、调用工具、结束或出错。运行有后端生成的 run_id,最多属于一个会话,会话里的每个人都能看到它的进度。Agent 交给子 Agent 的工作仍在同一次运行里,按子 Agent 调用分组显示。Agent 的最终回复仍是一条普通消息,带着它所属运行的 id。

运行的进度事件以 AG-UI 1.0 为参考,用得上的事件沿用 AG-UI 的名字和字段,我们需要不同的地方做了扩展并逐处标明;事件经实时连接以 agent_event 帧推送,不占会话的 seq。宿主经 agentRuns 能力停止运行(或只停一次子 Agent 调用)、取运行快照。见接入自有后端 · Agent 运行。

交互卡片

卡片是带结构化内容的消息(cws.card.v1),由 CwsMessageThread 自动渲染。带按钮或选项、让人直接作答的卡片叫交互卡片。卡片正文总会显示,作答需要宿主提供 cards 能力。

规划中,交互卡片可以和一次运行绑定:带上 run_id、tool_call_id、expires_at 的卡片是审批卡,Agent 停下来等人回答,答案作为那次工具调用的结果交回 Agent。规划中 见交互卡片。

消息仓库

消息仓库是通用层里、每个宿主一份的客户端数据存放处:createChatHost 建,CwsMessageThread 从它读、经它写。所有写入经同一个入口,本机存储经 ChatStorage 接口插拔。运行(Agent run)进仓库还在规划中。见 @openmaxai/chat-store 和 @openmaxai/chat-sdk · 消息仓库。

帧与信号

  • 帧是服务端经实时连接推来的一条数据。有「会话有新消息」、表态、已读、卡片更新等消息类的帧,还有装运行事件的 agent_event 帧。规划中
  • 信号(ChatInboundSignal)是宿主把帧翻译后交给组件的通知,如 { kind: "messages", conversationId }、{ kind: "reconnected" }。

漏掉的消息从 seq 水位往后补齐(补洞),漏掉的运行事件靠运行快照补齐。见实时与同步。

怎么拼在一起

层 是什么 详见
组件 只画界面,从宿主取一切 组件
宿主与能力 组件和你的应用之间的契约 能力
消息仓库 消息、运行、请求结果的客户端存放处 @openmaxai/chat-store
帧与信号 服务端的变化怎么到达客户端、漏了怎么补 实时与同步
后端 你的 API,或 OpenMax 接入自有后端