OpenMax
免费试用

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 的表格对照源码手写。