能力
宿主上的每一项能力:哪些必须提供、可选能力各打开什么、缺了会怎样,以及 SDK 替你提供了哪些。
能力
每项能力是宿主(ChatHost 对象)上的一个字段,类型是 …Port 接口(ChatMessagingPort、ChatMediaViewerPort 等)。组件需要发消息、查成员、看大图时,都通过它找你的应用。
src/chat-host.tsx
import type { ChatHost } from "@openmaxai/chat/host";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
const host: ChatHost = {
identity: { currentUserId: () => "me", getMember, listMembers, searchDirectory },
messaging: { sendMessage, loadThread, createConversation },
// ……其余必填能力,再加上你要的可选能力
};
<ChatProvider host={host}>{/* 聊天组件 */}</ChatProvider>;
接 OpenMax 时用 createChatHost(config) 直接拿到完整宿主;手写只用于 mock、测试或别的后端。
必填能力
ChatHost 类型不允许省略。
| 字段 | 用途 |
|---|---|
identity |
当前用户 id、查成员、通讯录搜索 |
messaging |
发消息、分页加载、建会话;可选方法开启表态、撤回、编辑、已读回执 |
inboundDelivery |
实时投递:SDK 建连用的地址、令牌、客户端 id,以及宿主转发信号的过渡入口 subscribe |
drafts |
按会话保存草稿 |
render |
渲染消息正文和图片 |
attention |
提示条和未读信号 |
i18n |
t() 和 locale() |
instanceScope |
查询键命名空间、缓存失效、按实例隔离的键值存储 |
attachments |
上传任务台、上限、取消、附件地址换取 |
共九项;其余字段都是可选的。渲染 ConversationList 或群管理组件时,把宿主标成 ChatHostWithConversationList 或 ChatHostWithGroupManagement:它们把 conversations、groupManagement 收紧为必填,漏了编译就不通过,不必等到运行时抛错。两个都要就写成 ChatHostWithConversationList & ChatHostWithGroupManagement。
可选能力
不提供时表现分三种:多数是对应功能不出现,其余部分照常工作;少数显示禁用的占位控件;conversations、groupManagement 缺了会让用到它的组件抛错。对照见缺了可选能力会怎样。取消勾选试试:

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): capability-toggles.tsx
"use client";
import { CreateGroupModal } from "@openmaxai/chat/group-management";
import { ChatHeader } from "@openmaxai/chat/header";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";
// 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 {
AGENT,
Button,
OPTIONAL_CAPABILITIES,
type OptionalCapability,
useDemoData,
useDemoHost,
useIsCompact,
} from "./kit";
export default function CapabilityToggles() {
const { conversations, lang } = useDemoData();
const isCompact = useIsCompact();
const [off, setOff] = useState<OptionalCapability[]>([]);
const [conversationId, setConversationId] = useState("launch");
const [creating, setCreating] = useState(false);
// The legacy MessageThread reads react-query and the host brings none: wrap a QueryClientProvider
// yourself.
const [queryClient] = useState(() => new QueryClient());
const host = useDemoHost({ without: off });
const conversation =
conversations.find((c) => c.id === conversationId) ?? conversations[0];
const isAgentDm = conversation.id === "helper";
const toggle = (name: OptionalCapability) =>
setOff((list) =>
list.includes(name) ? list.filter((n) => n !== name) : [...list, name],
);
return (
<div
className={`flex h-full bg-background text-foreground ${isCompact ? "flex-col" : ""}`}
>
<fieldset
className={`shrink-0 overflow-auto p-3 text-sm ${
isCompact
? "flex flex-wrap gap-x-3 gap-y-1 border-b"
: "w-48 space-y-1.5 border-r"
}`}
>
<legend className="sr-only">Capabilities</legend>
{OPTIONAL_CAPABILITIES.map((name) => (
<label
key={name}
className="flex items-center gap-2 font-mono text-xs"
>
<input
type="checkbox"
data-capability={name}
checked={!off.includes(name)}
onChange={() => toggle(name)}
/>
{name}
</label>
))}
</fieldset>
<QueryClientProvider client={queryClient}>
{/* Re-mount the chat whenever the host changes. ChatProvider installs only the
composer plugins this host can serve: without `workItems` there is no `#`. */}
<ChatProvider key={off.join(",")} host={host}>
<main className="flex min-h-0 min-w-0 flex-1 flex-col">
<div className="flex flex-wrap items-center gap-2 border-b px-3 py-2 text-xs">
<select
aria-label="conversation"
className="rounded border bg-background px-2 py-1"
value={conversationId}
onChange={(e) => setConversationId(e.target.value)}
>
<option value="launch">{conversations[0].name}</option>
<option value="helper">
{lang === "zh" ? "我的 Agent" : "My agent"}
</option>
</select>
{/* A module component throws if its capability is missing: leave it out instead. */}
{host.groupManagement && (
<Button
size="xs"
variant="outline"
onClick={() => setCreating(true)}
>
{lang === "zh" ? "新建群聊" : "New group"}
</Button>
)}
</div>
<ChatHeader
conversation={conversation}
headerTitle={conversation.name ?? ""}
headerSubtitle={null}
isAgentCollab={false}
isObserving={false}
collabAgents={[]}
typingText={null}
mode={isCompact ? "compact" : "full"}
infoPanelOpen={false}
isAgentOwnerDm={isAgentDm}
agentModelMemberId={isAgentDm ? AGENT : undefined}
/>
<MessageThread key={conversation.id} conversation={conversation} />
</main>
{host.groupManagement && (
<CreateGroupModal
open={creating}
onClose={() => setCreating(false)}
/>
)}
</ChatProvider>
</QueryClientProvider>
</div>
);
}
| 能力 | 打开什么 | 不提供时 |
|---|---|---|
conversations |
ConversationList:列表、置顶、隐藏 |
抛出指明缺失能力的错误 |
groupManagement |
CreateGroupModal、ChatInfoPanel;可选的 addMembers、removeMembers、leave、dissolve 是群信息面板里加人、移人、退群、解散的写操作 |
两者都抛出指明缺失能力的错误。四个可选写操作缺哪项,面板将不画哪个按钮(面板改读它们还没做,今天仍调回调属性,见群管理) |
mentions |
消息区的「@我」跳转胶囊 | 不显示胶囊 |
workItems |
输入框里的 # 工作项引用 |
没有 # 触发和工具条按钮,见输入框插件 |
profileCard |
点头像、点单聊头部弹出名片 | 头像不可点 |
cards |
交互卡片上的按钮和选项(卡片插件要它) | 卡片插件不装,卡片按只读画:正文和结果行照常,业务按钮不显示,选项与「创建 Agent」禁用,截断卡没有「展开」;不会发消息代替作答 |
agentConfig |
会话头部的 Agent 模型选择(需给 ChatHeader 传 agentModelMemberId) |
显示禁用的占位控件 |
mediaViewer |
点图片打开查看器 | 图片不可点 |
composerPreferences |
可配置的发送快捷键 | Enter 发送 |
navigation |
应用内跳转 | 聊天组件不读取 |
workReferences |
消息正文里工作项引用 chip 的地址与打开 | 聊天组件不读取;正文渲染层没拿到它时 chip 不可点,见 workReferences |
必填能力上也有可选方法,同样决定功能有没有:
| 可选方法所在 | 打开什么 | 不提供时 |
|---|---|---|
messaging 的表态(添加和移除都要提供) |
表情选择器,表态标签可点击切换 | 没有选择器,标签不可点 |
messaging 的撤回、编辑、编辑历史 |
消息菜单里的「撤回」「编辑」,点「(已编辑)」看历史 | 没有这些操作 |
messaging 的已读回执 |
单聊对勾、群聊已读人数 | 不显示回执 |
messaging 的按 id 加载消息 |
引用已加载范围之外的消息;补全图片文件的说明文字;别人编辑后新正文实时出现 | 引用条为空;说明文字不补全;别人的编辑要等重新加载这段消息(撤回、审核删除仍实时) |
messaging 的增量拉取(loadThreadSince) |
别人的新消息实时出现 | 重新加载会话后才出现;表态仍实时更新 |
inboundDelivery 的 subscribe |
应用还留着自己的连接时,由宿主转发的实时更新(过渡用) | 由 SDK 自己的连接送达;SDK 也不建连(endpointUrl() 返回 "" 或 isMock() 为 true)时,消息、表态、编辑、撤回、回执、卡片结果都不实时更新 |
attachments 的地址解析 |
显示收到的附件 | 附件显示为不可用 |
attachments 的上传(数量上限大于 0) |
输入框的附件按钮 | 没有附件按钮 |
render 的结构化消息渲染 |
自定义绘制结构化消息 | 按普通消息显示 |
字段名见 @openmaxai/chat API 参考,每项能力的成员和出错约定见宿主能力。
Agent 运行
规划中
规划中的可选能力 agentRuns 打开 Agent 运行的界面:消息区里的运行进度、工具步骤和停止按钮,会话头部的运行入口,以及 Agent 面板。
| 字段 | 打开什么 | 不提供时 |
|---|---|---|
agentRuns |
运行进度、运行列表、停止按钮 | 不显示运行进度,Agent 的消息照常显示 |
agentRuns.loadAgentRuns |
Agent 面板 | 没有 Agent 面板 |
运行事件还要经实时连接推到宿主;只有 agentRuns 而没有实时事件时,运行进度只在打开会话时从快照里出现。见接入自有后端。
缺了可选能力会怎样
| 表现 | 能力 |
|---|---|
| 不显示,同屏其余部分不受影响 | mentions、profileCard、mediaViewer、cards 的操作区、messaging 的可选方法 |
| 不显示:需要它的输入框插件不装,输入框其余照常 | workItems |
| 只读画法:需要它的消息展示插件不装,这类消息由消息区按只读画,不抛错 | cards |
| 禁用占位,布局不跳动 | agentConfig、卡片上的选项和「创建 Agent」按钮 |
| 报错,信息里写明缺哪个字段 | conversations(ConversationList)、groupManagement(CreateGroupModal、ChatInfoPanel) |
消息展示插件缺能力时不装、不抛错,单用 @openmaxai/chat 时也一样。这和输入框插件不同(单用 @openmaxai/chat 时输入框插件缺能力会抛),是刻意的:没有 cards 是合法状态,含义是卡片只读,不是忘了给能力。
聊天组件没有错误边界,报错会卸掉整棵 React 树,整页白屏,见已知限制。模块组件抛错而不显示空态,是为了区分「忘了给能力」和「确实没有会话」。不要某个模块,就别渲染它的组件;群管理入口(ConversationList 的 createGroupAction、ChatHeader 的 onToggleInfoPanel)不传即可。用 Chat SDK 时不用管:适配器没有 groupManagement,SDK 的列表、头部、浮出面都不画群管理入口,CwsGroupInfoPanel 什么都不画。
下面这些 props 不传也不会有提示:
| Prop | 组件 | 不传时 |
|---|---|---|
onVisibleSeqChange |
MessageThread |
已读位置不前进,刷新后会话仍是未读 |
createGroupAction |
ConversationList |
没有「新建群聊」按钮 |
onToggleInfoPanel |
ChatHeader |
没有群信息按钮 |
onLeave / onDelete / onRemoveMembers / onAddMembers |
ChatInfoPanel |
弹出确认框,确认后什么也不发生 |
memberStatus |
ChatInfoPanel |
所有成员显示离线 |
输入框插件
每个输入框插件用 requiredPorts 写明自己需要哪些能力,例如 # 工作项插件需要 workItems。ChatProvider 只装宿主具备这些能力的插件,缺能力的插件不装:没有 workItems,输入框里就没有 # 触发和工具条按钮,@ 和其余部分照常。插件集不用自己过滤;plugins 不传就是默认插件,传了也照样按宿主能力挑。
宿主在运行时变了(如上面的演示),插件跟着重新挑;SDK 按插件 id 比较、id 不变就保持列表引用(同一个 id 换了插件对象不会生效),不需要把 plugins 放到模块顶层或包 useMemo。
内置插件各自需要哪些能力见内置插件,自己写的插件怎么声明见输入框插件 · 需要的能力。
SDK 替你提供了什么
@openmaxai/chat-sdk/react 的 createLocalPorts(...) 返回与后端无关的能力:drafts、attachments(上传任务台,传输由你提供)、render、attention、i18n、instanceScope。后端相关的几项自己补:
src/chat-host.tsx
import type { ChatHostWithConversationList } from "@openmaxai/chat/host";
import { createLocalPorts } from "@openmaxai/chat-sdk/react";
const host: ChatHostWithConversationList = {
identity: myIdentity,
messaging: myMessaging,
inboundDelivery: myInbound,
conversations: myConversations,
...createLocalPorts({
scope: "my-chat",
currentUserId: () => myId,
attachments: { limits, upload, resolveUrls },
}),
};
默认实现:render 把 Agent 回复按 Markdown 画,其余文本画成保留换行的纯文本、@ 提及和 http(s) 链接;attention 什么都不做。ports 里的能力整项替换默认实现。
手写的宿主同样用 ChatProvider 安装。
OpenMax 宿主提供哪些
createChatHost(config) 在同一套本地能力上,为 OpenMax 加了 identity、messaging(发送、加载、增量拉取、建会话、按 id 取一条,以及表态、撤回、编辑和修订历史)、inboundDelivery(配了 wsUrl 时)、conversations,上传只在 ConversationScope 内可用;mediaViewer、composerPreferences、localRecords、navigation、workReferences 可通过 config.ports 传入。其余可选能力来自适配器上的同名成员(例如 groupManagement、cards、mentions、workItems、agentConfig),见适配器接口 · ChatSdkAdapter。
