API 参考
每个包有哪些入口、各导出什么,哪些是规划中的。
API 参考
各包已作为 3.0.0 预发布版本发布到 npm;导出在预发布版本之间可能变化,要锁定确切版本号。宿主、能力、适配器、运行等术语见核心概念。
包与入口
| 包 | 入口 | 里面有什么 | 状态 |
|---|---|---|---|
@openmaxai/chat |
@openmaxai/chat |
再导出下面各入口的常用部分,以及 CHAT_VERSION |
可用 |
@openmaxai/chat/host |
ChatHost 及全部能力类型、useChatHost、错误工具 |
可用 | |
@openmaxai/chat/conversation-list |
ConversationList、可拖宽的列表栏 |
可用 | |
@openmaxai/chat/message-thread |
MessageThread |
可用 | |
@openmaxai/chat/composer |
插件 API、COMPOSER_PLUGINS、ChatFileDropZone |
可用 | |
@openmaxai/chat/header |
ChatHeader |
可用 | |
@openmaxai/chat/group-management |
CreateGroupModal、ChatInfoPanel、AddMemberContainer |
可用 | |
@openmaxai/chat/surfaces |
浮窗、右侧停靠列、最小化坞、移动端抽屉 | 可用 | |
@openmaxai/chat/preview |
ChatContractSmoke,自检宿主的最小视图 |
可用 | |
@openmaxai/chat/agent-runs |
Agent 运行进度、工具步骤、停止按钮、运行列表、Agent 面板 | 规划中 | |
@openmaxai/chat-sdk |
@openmaxai/chat-sdk |
适配器接口、ChatSdkError、本机存储、CHAT_SDK_VERSION(不依赖 React) |
可用 |
@openmaxai/chat-sdk/react |
createChatHost、useChatSdkConversationList、本地能力工具 |
可用 | |
@openmaxai/chat-sdk/react |
ChatProvider(安装宿主和输入框插件的唯一入口)、ConversationScope |
||
@openmaxai/chat-sdk/testing |
内存适配器 createMemoryAdapter |
可用 | |
@openmaxai/chat-sdk/testing |
适配器一致性测试套件 | 规划中 | |
@openmaxai/chat-sdk/devtools |
调试面板 ChatDevtools,见调试面板 |
可用 | |
@openmaxai/chat-openmax |
@openmaxai/chat-openmax、@openmaxai/chat-openmax/react |
OpenMax 适配器和一行接入的 createChatHost |
可用 |
@openmaxai/chat-store |
@openmaxai/chat-store、@openmaxai/chat-store/react |
消息仓库:唯一写入口、补洞调度、存储接口,不含界面 | 代码已有,还没接到界面 |
@openmaxai/chat-store/inspect |
只读的检查接口:检查快照和仓库事件流 | 规划中 |
选择入口
| 场景 | 引入 | 指南 |
|---|---|---|
| 接 OpenMax,要整套聊天 | @openmaxai/chat-openmax/react 的 createChatHost,组件(CwsConversationList、CwsMessageThread 等)从 @openmaxai/chat-sdk/react 引入 |
接入 OpenMax |
| 接自己的后台 | 写一个适配器交给 @openmaxai/chat-sdk/react 的 createChatHost,组件同上;或者手写宿主、用 createLocalPorts 补齐,同样用 ChatProvider 安装 |
接入自己的后台 |
| 只要一个组件 | 它自己的入口(@openmaxai/chat/header 等) |
上面两行的 createChatHost 宿主都这样用:SDK 组件放在 ChatRoot 里,全局 CSS 引入 @openmaxai/chat-sdk/styles.css。
app.tsx
import { createChatHost } from "@openmaxai/chat-openmax/react";
import {
ChatProvider,
ChatRoot,
ChatSplitLayout,
ConversationHeader,
CwsConversationList,
CwsMessageThread,
useChatSdkConversationList,
} from "@openmaxai/chat-sdk/react";
import { useState } from "react";
const host = createChatHost({ baseUrl, wsUrl, auth });
export function App() {
return (
<ChatProvider host={host}>
<ChatRoot style={{ display: "flex", height: "100%" }}>
<Chat />
</ChatRoot>
</ChatProvider>
);
}
function Chat() {
const { conversations } = useChatSdkConversationList();
const [selectedId, setSelectedId] = useState<string | null>(null);
const selected = conversations.find((c) => c.id === selectedId) ?? null;
return (
<ChatSplitLayout
open={selected !== null}
list={
<CwsConversationList
selectedId={selectedId}
onSelect={(c) => setSelectedId(c.id)}
onDeselect={() => setSelectedId(null)}
/>
}
>
{selected && (
<>
<ConversationHeader
conversation={selected}
onBack={() => setSelectedId(null)}
/>
<CwsMessageThread key={selected.id} conversation={selected} />
</>
)}
</ChatSplitLayout>
);
}
手写宿主和「只要一个组件」用的是 @openmaxai/chat 的组件,它们不带样式根:样式表只作用在 SDK 组件自带的 .omx-chat 组件根之内,ChatRoot 本身不是样式作用域,所以它们渲染出来没有样式,要你把它们放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。
本节页面
- @openmaxai/chat: 按入口列出组件、ChatHost 字段、Provider 和 hook。
- 宿主能力: ChatHost 每项能力的成员:签名、必填与否、出错时怎么办。
- 数据模型: 消息、会话、成员、附件、已读与未读等类型的全部字段。
- @openmaxai/chat-sdk: createChatHost、适配器接口、错误、组件与 hook、本机数据、测试用的内存适配器。
- @openmaxai/chat-store: 消息仓库包:仓库、写入口的事件、补洞调度、存储接口。
- @openmaxai/chat-openmax: OpenMax 适配器、错误映射和一行接入的 createChatHost。
@openmaxai/chat-sdk、@openmaxai/chat-store、@openmaxai/chat-openmax 各页的签名由源码生成;@openmaxai/chat 的表格对照源码手写。
