OpenMax
免费试用

能力

宿主上的每一项能力:哪些必须提供、可选能力各打开什么、缺了会怎样,以及 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 缺了会让用到它的组件抛错。对照见缺了可选能力会怎样。取消勾选试试:

capability-toggles demo

演示截图。演示跑在内存里的示例 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。