OpenMax
免费试用

@openmaxai/chat

@openmaxai/chat 每个入口导出什么,以及 ChatHost 对象的全部字段。

@openmaxai/chat

聊天界面,以及组件读取一切所用的 ChatHost 类型(即宿主)。宿主可以用 @openmaxai/chat-sdk 造,也可以自己写。peer 依赖:react 19。

本包的组件不带样式根:SDK 样式表(@openmaxai/chat-sdk/styles.css)只作用在 SDK 组件自带的 .omx-chat 组件根之内。放在 SDK 组件之外渲染时,要你把它们放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式;会话列表、消息区、会话头部用 createChatHost 的宿主时改用 @openmaxai/chat-sdk 的组件。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。

入口 用途
@openmaxai/chat 常用内容一次引入
@openmaxai/chat/host ChatHost、Provider、hook、能力类型
@openmaxai/chat/conversation-list 会话列表
@openmaxai/chat/message-thread 消息区
@openmaxai/chat/composer 输入框及其插件
@openmaxai/chat/header 会话头部
@openmaxai/chat/group-management 新建群聊、群信息面板
@openmaxai/chat/surfaces 浮窗、停靠、移动端抽屉
@openmaxai/chat/preview 自检宿主用的视图
@openmaxai/chat/markdown Agent 回复背后的 Markdown 渲染器
@openmaxai/chat/agent-runs 规划中 Agent 运行组件

@openmaxai/chat

导出 类别 出处
@openmaxai/chat/host 的全部导出 ./host
ConversationList、KNOWN_GAPS_CONVERSATION_LIST 组件、常量 ./conversation-list
MessageRenderersProvider、defineMessageRenderer、类型 ChatMessageRenderer、ChatMessageRendererProps、ChatPluginEvent ./message-renderers。MessageThread 与 KNOWN_GAPS_MESSAGE_THREAD 只在 ./message-thread:老消息区读 react-query,根入口因此不需要它
defineComposerPlugin、useComposerEngine、resolveDmReadOnlyCopy、KNOWN_GAPS_COMPOSER、类型 ComposerPlugin ./composer
ChatHeader、KNOWN_GAPS_HEADER、类型 ChatHeaderProps、ChatHeaderBadge ./header
CreateGroupModal、ChatInfoPanel、AddMemberContainer、KNOWN_GAPS_GROUP_MANAGEMENT、类型 CreateGroupModalProps、ChatInfoPanelProps、ChatMemberStatus ./group-management
CHAT_VERSION 常量(string) 本包的版本。@openmaxai/chat-sdk 必须与它同一版本,见安装

COMPOSER_PLUGINS、ChatFileDropZone、可拖宽列表栏和 ./surfaces 只能从各自入口引入。每个 KNOWN_GAPS_* 都是 readonly string[],列出该模块还没做到的事。

@openmaxai/chat/host

ChatHost

必填字段合起来是 ChatCoreHost。可选字段不给,对应界面就不渲染;标「缺了抛错」的三项例外,用到它的组件会抛错。每项能力的成员、签名和出错约定见宿主能力,数据类型的字段见数据模型。

字段 类型 必填 作用
identity ChatIdentityPort 是 当前用户 id、查成员、会话成员(同步),选人用的 searchDirectory
messaging ChatMessagingPort 是 sendMessage、loadThread、createConversation。可选的 addReaction、removeReaction、recallMessage、editMessage、loadMessage、loadThreadSince、loadReadCursors、listMessageEdits 各自开启对应功能,loadChangesSince 与 getMessagesByIds 一起开启补改动
drafts ChatDraftsPort 是 get、save、clear,列表用的 previews 和 subscribe
inboundDelivery ChatInboundDeliveryPort 是 SDK 持有的实时连接的参数:endpointUrl()、authToken()、clientId()、isMock();可选的 subscribe(onSignal) 是宿主转发信号的过渡入口(messages、read、reaction、messageChanged、card、delivery、reconnected)。见宿主能力 · inboundDelivery
render ChatRenderPort 是 renderMarkdown、renderImage、renderMessageText、renderRichText,可选 renderMention。自己画某类消息用消息展示插件
attention ChatAttentionPort 是 notify(level, message) 弹提示,setUnreadSignal(count) 更新角标
i18n ChatI18nPort 是 t(key, vars?) 和 locale()
instanceScope ChatInstanceScopePort 是 查询键作用域、invalidate("conversations" | "messages" | "members")、键值 storage
attachments ChatAttachmentsPort 是 limits、start、cancel、getTask,可选 subscribeTasks、resolveUrls。maxAttachments: 0 隐藏附件按钮
composerPreferences ChatComposerPreferencesPort 否 sendShortcut():"enter"(默认)或 "mod-enter";可选 mentionListStyle():"flat"(默认)或 "grouped"(@ 候选列表的排法)
localRecords ChatLocalRecordsPort 否 同步的 get(key) / set(key, value),没有删除:包替当前用户在本机记的小记录(最近 @ 过的人)。键由包定(每个功能一个前缀,含当前用户 id);宿主必须按组织分开;值小且有上限,不含名字、消息正文与凭证。不给则用 instanceScope.storage;那份存储按承载面或会话分开、或应用的两个宿主要共用时给它
mediaViewer ChatMediaViewerPort 否 open(slides, index)。不给则图片不可点。见图片查看器
conversations ChatConversationsPort 否,缺了抛错 list、setPinned、setHidden,可选 setMuted、markReadUntil。缺了 ConversationList 抛错
groupManagement ChatGroupManagementPort 否,缺了抛错 createGroup、updateGroupProfile。缺了 CreateGroupModal 和 ChatInfoPanel 抛错
memberStore ChatMemberStoreReader 否 getMembers、subscribe(@openmaxai/chat-store 成员仓库的读面)。群信息面板与 MessageThread 从这里读会话内角色;不给则角色当作不知道。见 memberStore
workItems ChatWorkItemsPort 否,缺了抛错 search({ search, projectId?, cursor? }),用于 # 引用。用默认插件集时缺了它输入框会抛错。见输入框
subConversations ChatSubConversationsPort 否 findOrCreate。场景子会话;不给则不画子会话界面(会话列表不为 has_unread_subconversations 画圆点)。见 subConversations
mentions ChatMentionsPort 否 listUnread、markRead、markAllRead。不给则不显示「跳到 @我」按钮
connectors ChatConnectorPanelPort 否 snapshot、subscribe、toggle、refresh、dropRevoked、managementHref、openManagement、notify、onComposerSend,可选 connectorActionHref、openConnectorAction、onPanelOpened、onConnectorToggled、searchCatalog。只有装了 connectorPanelPlugin 的宿主才要
composerMenu ChatComposerMenuPort 否 snapshot、subscribe、notify,可选 onMenuOpened。只有装了 composerPlusMenuPlugin 的宿主才要
cards ChatCardsPort 否 isOperationAllowed,可选 invokeAction、expandBody、settleChoice、submitInteraction、refreshCard、formDrafts、openCreateAgent。不给则没有底部操作按钮。见卡片
profileCard ChatProfileCardPort 否 loadProfile、listOwnedAgents、openDirectMessage、openSelfSettings,可选 openAgentManagement、peekProfile(同步给第一帧)。不给则头像不可点。见名片
agentConfig ChatAgentConfigPort 否 loadModelState、setModel、setModelVisibility。不给则头部显示禁用的占位控件。见会话头部
agentGroupPolicy ChatAgentGroupPolicyPort 否 loadGroupPolicy、canManageGroupPolicy、setGroupReplyMode、setGroupAllowlist、openAgentSettings?。群里 Agent 的回复策略,见 agentGroupPolicy
conversationResources ChatConversationResourcesPort 否 list(query, { signal? }):会话里的图片、文件与链接,新的在前,按游标翻页;只交当前可见消息的行。见 conversationResources
messageSearch ChatMessageSearchPort 否 search(query, { signal? }):在一条会话里搜消息;命中只含当前可见的消息、基于当前正文。见 messageSearch
agentRuntime ChatAgentRuntimePort 否 loadState、runAction。信息侧栏 Agent 身份卡上的管理区,见 agentRuntime
navigation ChatNavigationPort 否 navigate、resolveHref。聊天组件不读取它
workReferences ChatWorkReferencesPort 否 href(ref)(同步回浏览器地址,画在 <a href> 上)、open(ref)(单纯左键点击时调,回 "ok" | "denied" | "missing" | "failed")。聊天组件不读取它;用它的是正文渲染层(ChatMarkdown 的 workReferences、SDK 默认 render),见 workReferences。消息正文里的工作项引用([#label](proj://…) / issue://…)总是画成 chip;渲染层没拿到它 ⇒ chip 不可点。打不开时用 @openmaxai/chat/markdown 的 bindWorkReferenceNotice 接到 attention 出声(SDK 默认 render 已接好)
forward ChatForwardPort 否 forwardMessages、mergeForwardMessages(@experimental)。有它且有 conversations 时,MessageThread 与 MessageThreadNext 在消息上给「转发」;见 forward
agentRuns 规划中 ChatAgentRunsPort 否 cancelRun(可选 subagentRunId,只停一次子 Agent 调用)、loadActiveRuns、loadRunEvents,可选 loadAgentRuns、describeTool。不给则不显示 Agent 运行进度

ChatHostWithConversationList、ChatHostWithGroupManagement 分别把 conversations、groupManagement 收紧为必填。降级细节见能力。

Provider 与 hook

导出 签名 作用
ChatHostProvider ({ host: ChatHost, children }) 不是安装入口,安装宿主用 ChatProvider。放在 ChatProvider 里面,给它下面这一块界面换掉部分能力,例如加上 profileCard
useChatHost () => ChatHost 取已安装的宿主
useChatCapability <K extends keyof ChatHost>(key: K) => ChatHost[K] 取宿主的某个字段
useChatConversationsPort () => ChatConversationsPort 取 host.conversations
useChatGroupManagementPort () => ChatGroupManagementPort 取 host.groupManagement
ChatRequestCacheProvider ({ cache: ChatRequestCache, children }) 给下面这一块界面一份共用的请求结果缓存(createChatRequestCache 建的那种)。一个作用域一份,换组织、换用户时由装它的一方换一份或 clear()
useChatRequestCache () => ChatRequestCache 取最近一层 ChatRequestCacheProvider 的缓存;外面没有时退回组件自建的一份(只给测试和单独挂载用,各组件之间不共用)

hook 抛出的错误

都在渲染期抛出,中文信息写明缺什么。

hook 何时抛 怎么修
useChatHost(以及所有组件) 上层没有 ChatProvider 用 ChatProvider 包住
useChatConversationsPort(ConversationList 在用) 没有 host.conversations 提供 conversations,或不渲染 ConversationList
useChatGroupManagementPort(CreateGroupModal、ChatInfoPanel 在用) 没有 host.groupManagement 提供 groupManagement,或不渲染这两个组件

其他导出

导出 类别 作用
ChatOperationNotAllowedError 类 服务器拒绝时(如超过撤回时限)从 recallMessage / editMessage 抛出,界面提示「无法撤回」而非「失败,请重试」
isChatOperationNotAllowed (error: unknown) => boolean 检查 chatOperationNotAllowed === true 字段;页面上有两份包时也判得准,instanceof 不行
ChatMembershipUnknownError 类 按 id 取会话时判不出当前用户是不是成员(再取一次也一样)时由宿主抛出,深链提示「不能确认你是否为该会话成员,无法打开」而非「打开对话失败,请重试」
isChatMembershipUnknown (error: unknown) => boolean 检查 chatMembershipUnknown === true 字段;同上,不用 instanceof
sendContentTypeFor (attachments) => "image" | "file" 附件全是图片时为 "image"
hostText (port, key, ns = "chat") => string | null 向宿主的 i18n 能力取一个词;回原键(带不带 ns: 前缀)、空串或不是字符串时算认不得,回 null,由你退回自己的兜底。SDK 自带的看大图和浮出面的按钮文字都按这条判据
sweepFormDraftValue (raw, nowMs) => { action: "keep" } | { action: "remove" } | { action: "set"; value } 宿主清理选择卡草稿存储用:一条存着的值留着、删掉,还是补上关闭时刻后写回(作废记录关闭满 7 天删;记录格式归包,宿主不读)
can (actor, action, conversation, target?) => ChatPermission 当前用户能不能在会话里做这件事,规则对齐服务端,见 can
resolvePermission (permission, whenUnknown) => boolean 把 can 的三态结论折成画不画
pluginsForHost (plugins, host) => plugins 宿主能力凑得齐的那些插件:插件 requiredPorts 里每一项宿主都有才留下,保持原顺序。输入框插件与消息展示插件共用
usePluginsForHost hook 同 pluginsForHost,挑出来的插件 id 序列不变时交回同一个数组
ChatComposerPreferencesPort、ChatMemberKind、ChatMentionInput、ChatMessageTextContext、ChatUploadStartHooks、ChatSendShortcut 类型 composerPreferences 的能力类型,以及成员签名里用到的类型 规划中
ChatConnectorPanelPort、ChatConnectorPanelSnapshot、ChatConnectorPanelAvailability、ChatComposerConnector、ChatConnectorToggleOutcome、ChatConnectorToggledEvent、ChatConnectorPanelOpenSource、ChatConnectorCatalogSearch 类型 connectors 能力(插头 Connector 面板)及其数据类型
ChatComposerMenuPort、ChatComposerMenuSnapshot、ChatComposerMenuOpenTrigger 类型 composerMenu 能力(输入区 "+" 菜单)及其数据类型
ChatMemberPresencePort、ChatMemberPresenceStatus、ChatMemberRef、ChatMemberMarksPort、ChatMemberMarkSubject 类型 memberPresence 能力(头像上的状态点)与 memberMarks(宿主画的头像角标与名字字签)及其数据类型
ChatAgentCapabilityTagsPort、ChatAgentCapabilityTag 类型 agentCapabilityTags 能力(Agent 的能力标签,按屏上的行读)及其数据类型
ChatAgentActivityPort、ChatAgentRunView 类型 agentActivity 能力(Agent 执行过程,只读进度(实验性 · 过渡))及其数据类型;ChatAgentRunView 就是 @openmaxai/chat-store 的 ChatAgentActivityRun。规划中的 Agent 运行能力落地时替换它
ChatForwardPort、ForwardRequestBody、ForwardTargetInput、ForwardNoteInput、ForwardMentionInput、ForwardResponseData、ForwardTargetResult、MergeForwardTargetResult、ForwardNoteResult、ForwardTargetError、ForwardedCopy、MergedForwardCard 类型 forward 能力(转发消息,@experimental)及其请求与结果类型;字段见数据模型

类型:ChatCoreHost、ChatHost、ChatHostWithConversationList、ChatHostWithGroupManagement, 能力类型 ChatIdentityPort、ChatMessagingPort、ChatDraftsPort、ChatInboundDeliveryPort、ChatRenderPort、ChatAttentionPort、ChatI18nPort、ChatInstanceScopePort、ChatLocalRecordsPort、ChatAttachmentsPort、ChatMediaViewerPort、ChatConversationsPort、ChatGroupManagementPort、ChatMemberStoreReader、ChatWorkItemsPort、ChatMentionsPort、ChatSubConversationsPort、ChatCardsPort、ChatProfileCardPort、ChatAgentConfigPort、ChatAgentGroupPolicyPort、ChatAgentRuntimePort、ChatConversationResourcesPort、ChatMessageSearchPort、ChatNavigationPort、ChatWorkReferencesPort, 以及配套的数据类型: ChatWorkReference、ChatWorkReferenceOpenResult、 ChatParticipant、ChatDirectoryMember、ChatDirectoryPage、ChatConversation、 ChatConversationPage、ChatSubConversationContext、ChatSubConversationFindOrCreateInput、ChatSubConversationOwner、ChatSubConversationResult、ChatConversationParticipant、ChatMessage、ChatThreadPage、ChatThreadLoadOptions、ChatThreadSincePage、ChatThreadChange、ChatThreadChangesPage、ChatThreadMessagesByIdsPage、 ChatAttachment、ChatUploadTask、ChatComposerDraft、ChatQuoteExcerpt、SendMessageInput、ChatSendOutcome、 ChatSendBlocked、CreateConversationInput、ChatMessageEdit、ChatMessageEditInput、ChatMessageChangeResult、 ChatReadCursorSnapshot、ChatInboundSignal 及其各变体(ChatInboundMessagesSignal、 ChatInboundReadSignal、ChatInboundReactionSignal、ChatInboundMessageChangedSignal、ChatInboundCardSignal、 ChatInboundDeliverySignal、ChatInboundReconnectedSignal、ChatInboundConnectedSignal、ChatInboundCatchUpSignal、ChatInboundTypingSignal)、ChatImageViewerSlide、 ChatCardActionInput、ChatCardChoiceInput、ChatCardFormAnswer、ChatCardInteractionInput、ChatCardActionResult、ChatCardActionErrorKind、ChatCardFormError、ChatOnboardingCardEvent、 ChatMemberProfile、ChatProfileEntity、ChatUnreadMention、ChatUnreadMentionsPage、 ChatWorkItem、ChatWorkItemKind、ChatWorkItemPage、ChatConversationResource、ChatConversationResourceBase、ChatConversationAttachmentResource、ChatConversationLinkResource、ChatConversationResourceKind、ChatConversationResourcePage、ChatConversationResourcesQuery、ChatMessageSearchHit、ChatMessageSearchPage、ChatMessageSearchQuery、ChatMessageSearchSnippetPart、ChatAgentModelOption、 ChatAgentModelState、ChatAgentGroupPolicy、ChatAgentGroupScope、ChatAgentGroupReplyMode、ChatAgentPolicyApplyOutcome、ChatAgentPolicyRejectReason、ChatAgentRuntimeAction、ChatAgentRuntimeActionState、ChatAgentRuntimeActionUi、ChatAgentRuntimeState、ChatAgentRuntimeStatusRow、 ChatCreateGroupInput、ChatGroupProfileUpdate、ChatGroupMembersChangeResult、ChatGroupLeaveOptions、ChatGroupLeaveResult、ChatInstance。

字段逐个列在数据模型。

can

function can(actor: ChatPermissionActor, action: ChatPermissionAction, conversation: ChatPermissionConversation, target?: ChatPermissionTarget): ChatPermission;
function resolvePermission(permission: ChatPermission, whenUnknown: boolean): boolean;

当前用户能不能在这个会话里做一件事,纯函数,规则对齐服务端。只决定按钮画不画、可不可点;服务端是终审,被拒要提示。

动作 action 允许的条件
editGroupProfile 群(type: "GROUP"),会话内角色为 OWNER 或 ADMIN
inviteMembers 群,角色不低于 MEMBER(服务端按群设置 who_can_invite 判,默认 member,前端读不到这项设置)
removeMember 群,角色不低于 ADMIN,且对方(target.role)严格低于自己;移自己回 denied(走退群)
deleteGroup 群,角色为 OWNER
recallMessage 自己发的(target.senderId 是我)总是允许,时间窗由调用方判;别人发的要 OWNER 或 ADMIN
mentionAll 只看服务端算好的 conversation.can_mention_all;会话须来自按 id 取的详情,列表那一行里它恒为 false

角色高低:OWNER > ADMIN > MEMBER > PUBLISHER = SUBSCRIBER。结论是三态:{ status: "allowed" }、{ status: "denied", reason }、{ status: "unknown", reason }。

  • 角色不知道 ≠ 没权限。 actor.conversationRole 没给、或是 UNSPECIFIED(线上它也是旁观者与未知角色的投影)时,依赖角色的动作回 unknown;removeMember 的对方角色不知道时同样。只有 actor.isMember === false(知道不是成员)才回 denied(notMember)。
  • 非群会话的群操作一律 denied(notGroup)。
  • actor.orgRole 不改变这几种动作的结论(服务端判这些动作时不读组织角色)。
  • resolvePermission(p, whenUnknown) 把三态折成画不画:allowed 为 true,denied 为 false,unknown 取 whenUnknown(角色不知道时用的规则,例如「先画、由服务端拦」)。

类型:ChatPermission、ChatPermissionAction、ChatPermissionActor、ChatPermissionConversation、ChatPermissionTarget、ChatPermissionDeniedReason、ChatPermissionUnknownReason。用 Chat SDK 时由它的 权限 hook 替你把当前用户的角色交进来。

@openmaxai/chat/conversation-list

导出 类别 说明
ConversationList 组件 属性。需要 host.conversations
ResizableConversationListColumn 组件 可拖宽的列表栏。属性:width: number | null、onWidthChange(w: number | null)、children、inactive?: boolean(窄屏时传 true:外壳退成 display: contents,不写宽度、不出把手,里面的列表不重挂)
clampConversationListWidth (w, viewportW?) => number 把宽度夹到允许范围
CONVERSATION_LIST_MIN_W、CONVERSATION_LIST_MAX_W 常量 220、560(px)
CONVERSATION_LIST_MAX_VIEWPORT_RATIO 常量 0.4:不超过视口的 40%(但不低于最小宽)
CONVERSATION_LIST_WIDTH_VAR 常量 "--chat-list-w"。ConversationList 按它定宽度;ResizableConversationListColumn 在 width 不为 null 时把它设在自己的外壳上,覆盖祖先上的值。见主题 · 布局
KNOWN_GAPS_CONVERSATION_LIST 常量
ResizableConversationListColumnProps 类型
useResponsiveEnvironment hook 列表自己判窄屏 / 粗指针用的那个:const [ref, { narrow, coarsePointer }] = useResponsiveEnvironment(),经 ref 挂的节点所在窗口判断。包列表的外层组件(如 SDK 的 resizable)与列表用同一个口径

@openmaxai/chat/message-thread

导出 类别 说明
MessageThread 组件 属性。自带输入框
MessageThreadProps 类型
useThreadMessagesSnapshot hook (host, conversationId) => readonly ChatMessage[]。消息区已经取到的这条会话的消息(按 seq 升序),只读、不发请求;读的是同一宿主下消息区自己那份缓存,随它更新
KNOWN_GAPS_MESSAGE_THREAD、KNOWN_GAPS_COMPOSER 常量
MessageRenderersProvider 组件 装消息展示插件:renderers、onPluginEvent、onRendererError。不能嵌套
defineMessageRenderer 函数 定义一个消息展示插件
MESSAGE_RENDERERS 常量 不包 MessageRenderersProvider 时装的插件:[formCardRenderer, cardRenderer]
cardRenderer、formCardRenderer 常量 卡片插件与选择卡插件,都要 cards 能力,见交互卡片
CORE_MESSAGE_TYPES 常量 插件不能认领的类型:TEXT、AGENT_TEXT、IMAGE、FILE、SYSTEM
ChatMessageRenderer、ChatMessageRendererProps、ChatMessageInteractions 类型 插件的形状、View 收到的东西、交互句柄
ChatPluginEvent、ChatPluginEventPayload、ChatJsonValue、ChatRendererFailure 类型 插件事件的信封与数据、插件出错的报告
ConnectionStatusBar 组件 连接状态条:实时连接断开时告诉用户,并给重试按钮 规划中
defineMessageAction 函数 定义消息操作插件 规划中
ChatMessageAction、ChatMessageActionContext 类型 消息操作插件的形状和上下文 规划中

@openmaxai/chat/message-renderers

只有消息展示插件那一套,不含消息区。只装插件、不用 MessageThread 时从这里引;从 @openmaxai/chat/message-thread 引会把整个消息区一起带进来。和 @openmaxai/chat/message-thread 导出的是同一批对象。

导出 说明
MessageRenderersProvider、defineMessageRenderer、MESSAGE_RENDERERS、cardRenderer、formCardRenderer、CORE_MESSAGE_TYPES 同 @openmaxai/chat/message-thread 的那几个
ChatMessageRenderer、ChatMessageRendererProps、ChatMessageInteractions、ChatPluginEvent、ChatPluginEventPayload、ChatJsonValue、ChatRendererFailure 类型,同上

@openmaxai/chat/composer

导出 类别 说明
COMPOSER_PLUGINS readonly ComposerPlugin[] 内置插件:mention(@,需要 identity 和 i18n)和 # 工作项插件(需要 workItems)
defineComposerPlugin 函数 自定义插件的类型辅助
useComposerEngine hook 按当前插件集构建的编辑引擎
ChatFileDropZone 组件 文件拖到它范围内任何位置(如头部)都能交给消息区
plainTextToHtml (text: string) => string 把一段纯文本转成输入框草稿认得的 HTML:按 \n 切成段,每行一个 <p>;&、<、> 三个字符一律转义,所以文本里的 <script> 之类不会被当成标签。空串返回空串。宿主往草稿里写文字时用它,不要自己拼 HTML
resolveDmReadOnlyCopy (reason) => { title, detail } 单聊只读横幅的文案 key
KNOWN_GAPS_COMPOSER 常量
ComposerPlugin、ComposerToolbarPanelProps、ComposerChrome、ChatFileDropSink 类型 ComposerChrome 是 "card" | "flush"
ComposerCandidate、ComposerPanelProps、ComposerToolbarItem、ComposerNodeSpec 类型 写插件用,见编写输入框插件 规划中
ComposerToolbarPlacementOverrides 类型 ChatProvider 的 toolbarPlacement 的类型:Readonly<Record<string, "bar" | "plus-menu">>
composerPlusMenuPlugin ComposerPlugin 输入区 "+" 菜单(Skills / 知识库)。要 composerMenu;不在 COMPOSER_PLUGINS 里
connectorPanelPlugin ComposerPlugin "+" 后面的插头、已启用 Connector 胶囊与 Connector 面板。要 connectors;不在 COMPOSER_PLUGINS 里。两者互不依赖,一起装按 [composerPlusMenuPlugin, connectorPanelPlugin, ...COMPOSER_PLUGINS]
collapseConnectors、connectorAuthState、connectorRowLayout、filterConnectors、orderConnectors、unauthorizedEnabledConnectors 函数 Connector 面板的纯判据(折叠、三态、搜索、排序、已开未授权)。同一会话不设启用上限。
shouldApplyMenuToggle、shouldSwallowTriggerPress 函数 "+" 菜单的连点闸
ComposerPlusMenuControl、ComposerToolbarSlotProps、ComposerLeadingSlotProps 类型 接管 "+" 位(ComposerToolbarItem.PlusSlot)或紧跟其后画一格(ComposerToolbarItem.LeadingSlot)的插件用

插件经 ChatProvider 的 plugins 装入,不传就是 COMPOSER_PLUGINS。插件声明的 requiredPorts 在宿主上缺失时,这个插件不装,输入框其余照常,不会抛错。

@openmaxai/chat/header

导出 类别 说明
ChatHeader 组件 属性
ChatHeaderProps、ChatHeaderBadge 类型
conversationHeaderText 函数 (conversation, t, options?) => ConversationHeaderText:从会话数据算 headerTitle、headerSubtitle、badge,标题和会话列表那一行用同一个函数;把列表用的同一份 memberNames 作为 options.memberNames 传进来,两边才同名;SDK 的 ConversationHeader 就用它
ConversationHeaderText 类型 { headerTitle: string; headerSubtitle: string | null; badge: ChatHeaderBadge | null }
ConversationHeaderTextOptions 类型 { memberNames?: Readonly<Record<string, string>>; members?: readonly ChatParticipant[] }:conversationHeaderText 的选项;members(会话成员)只在没带 agent_collab_participants 的 Agent 协作会话上读,标题按其中的 Agent 拼成「A ⇄ B」
CollabAgent、OnlineStatus 类型 collabAgents、dmPeerStatus 两个属性的类型,见会话头部 · API 规划中
KNOWN_GAPS_HEADER 常量

@openmaxai/chat/group-management

三个组件都需要 host.groupManagement。

导出 类别 说明
CreateGroupModal 组件 属性
ChatInfoPanel 组件 属性
ChatGroupInfoBlocks、ChatGroupInfoBlocksProps、ChatGroupMembersTab、ChatInfoBlockState 组件 会话信息侧栏里群聊「信息」tab 的区块:群资料(就地改)、成员(「人 / Agent」两页、添加、Agent 回复模式)、会话设置、退出 / 解散。成员表的加载态由 membersState 给,只影响成员块;页由 membersTab 受控。写操作同 ChatInfoPanel 经 groupManagement / agentGroupPolicy。@experimental
ChatGroupProfileBlock、ChatGroupProfileBlockProps 组件 只读的群名与群描述,别的都没有(无成员、设置、退出、编辑);不需要 groupManagement,也不读成员表。信息侧栏里旁观的群用它。@experimental
AddMemberContainer 组件 群信息面板里用的选成员组件
CreateGroupEntry 组件 会话列表搜索框右侧的「新建群聊」按钮(交给 createGroupAction),点开 CreateGroupModal
isGroupOwner、humanSuccessorCandidates、ownerLeaveWillDeleteGroup 函数 「群主退群」流程的判断函数
KNOWN_GAPS_GROUP_MANAGEMENT 常量
CreateGroupModalProps、ChatInfoPanelProps、ChatMemberStatus 类型

@openmaxai/chat/surfaces

主页面之外承载会话的容器。会话正文由你经 renderBody 传入。用法、属性和 store 的全部成员见浮窗、停靠列与抽屉。

导出 类别 说明
FloatingChatLayer 组件 浮动聊天窗
FloatingChatLayerProps 接口 FloatingChatLayer 的属性:ChatSurfaceProps 加最小化动画的落点 collapseAnchor
ChatDockColumn 组件 停靠成一列的会话
ChatMinimizedDock 组件 最小化会话的头像坞
ChatMobileDrawer 组件 底部抽屉,isCompact 为真时显示
ChatAgentInfoBlocks、ChatAgentInfoBlocksProps 组件 信息侧栏里与 Agent 私聊的「信息」tab:身份卡(资料来自 loadProfile、在线状态来自 memberPresence、标签来自 agentCapabilityTags、模型控件来自 agentConfig)、来自 agentRuntime 的管理区,以及会话设置(免打扰 / 置顶,各自给了回调才画)。每一块各有骨架和出错时的「重试」。@experimental
ChatMemberIdentityCard、ChatMemberIdentityCardProps 组件 成员的只读身份卡(头像、名字、来自 memberPresence 的在线状态),没有任何操作;资料来自 loadProfile,取不到时用传入的名字和头像。旁观的私聊对端是人时用它。@experimental
ChatPersonInfoBlocks、ChatPersonInfoBlocksProps 组件 侧栏里与人私聊的「信息」tab:对方的名片(资料来自 loadProfile,在线状态来自 memberPresence)、「TA 的 Agent」(来自 listOwnedAgents,每一个都是调 onOpenAgent 的按钮,没给 onOpenAgent 时只是展示的行;对方没有 Agent 时整块不画)、会话设置(免打扰 / 置顶,各自给了回调才画)。每一块各有骨架和出错时的「重试」。@experimental
ChatInfoSidebarLayout、ChatInfoSidebarLayoutProps 组件 顶部栏下面的会话信息侧栏布局:左边消息区、右边可拖宽的侧栏卡片(容器窄于 672 px 时改为浮层),compact 时是底部抽屉;placement="cover" 时改为盖满整个容器、左上角是「←」(浮窗、停靠标签、手机抽屉用)。开合、宽度与内容都由 props 给;给了 messages 才有「消息」tab,给了 files 才有「文件」tab;给了 tab / onTabChange 时选中哪个 tab 由调用方定。@experimental
ChatConversationFilesTab、ChatConversationFilesTabProps、ChatConversationFilesJumpTarget 组件 侧栏的「文件」tab(放进 ChatInfoSidebarLayout 的 files):经宿主的 conversationResources 列出会话里的图片、文件和链接,按时间倒序分「本周 / 更早」,带搜索、「全部 / 文件 / 链接 / 图片」筛选与按游标翻页;这条会话的实时信号到了就重取,不按定时器取。点图片打开 mediaViewer;「定位到原消息」调 onJumpToMessage。@experimental
ChatConversationMessagesTab、ChatConversationMessagesTabProps、ChatConversationMessagesJumpTarget 组件 侧栏的「消息」tab(放进 ChatInfoSidebarLayout 的 messages):经宿主的 messageSearch 搜这条会话,列出命中与标出命中部分的片段,按游标翻页。点结果调 onJumpToMessage;回 notFound 时提示「消息已不可见」并拿掉这条。实时通道交来撤回 / 删除时那条立刻消失;编辑、撤回、删除与断线重连会重新搜;卸载后结果不留。@experimental
ChatPrimaryDropZone 组件 { enabled, stable?, children }。把一块区域(通常是会话列表那一列)声明为「主聊天放置区」:浮窗、停靠标签拖到上面松手 ⇒ 在主聊天打开(claimPrimary);列表行拖回上面松手 ⇒ 取消。拖拽经过时画淡蓝虚线和提示。页面上的非模态框开着时(页面被隔离)放置区不接,同停靠区。enabled 为假时只渲染 children;给了 stable 则留一层 display: contents 的包层,enabled 翻转时 children 不重挂
useListRowDragOut hook 把会话列表的行拖出列表。{ enabled, rowKeyOf, ghostOf, onDrop } ⇒ { onPointerDown, onDragStart, overlay }:onPointerDown 与 onDragStart 挂到列表容器上(后者拦掉行内头像图片的原生拖拽)(按 rowKeyOf 认行;行里面的按钮、链接、表单控件按下不起拖,行本身就是 <button> 的照常能拖,移动不超过 6px 时仍是点击,Enter / Space 也照常触发;「里面」指控件的父节点经 rowKeyOf 仍认成同一行,所以整行是按钮时把键挂在按钮自己身上),overlay 是拖拽时跟着指针的小卡片和落点虚线框。按下后移动超过 6px 才算拖拽,只接鼠标和触控笔。松手在主聊天放置区内 ⇒ 不调 onDrop;在停靠区 ⇒ { kind: "dock" };其余 ⇒ { kind: "float", at }(左上角,已夹进视口)。登记表由你在 onDrop 里写
useFloatingChatStore、useChatPreferencesStore hook 已打开会话、承载面偏好的 zustand store
useChatSurfaceTitle、useChatSurfaceTitles hook (chat) => string / (chats) => string[]。窗的标题,随时最新:取装着的标题来源对这条会话的答案(见 ChatSurfaceTitleSource),答不出就用开窗时存下的 title。来源通知这条会话时重渲。浮窗自带的标题栏、ChatDockColumn、ChatMinimizedDock、ChatMobileDrawer 都经它取标题。@experimental
ChatSurfaceTitleSource 接口 { get(conversationId): string | undefined; subscribe(conversationId, listener): () => void }。窗标题的来源;用 useFloatingChatStore.getState().setTitleSource(source) 装上,返回卸载函数,已装着一份时再装会抛错(一页一份)。答 undefined 或 "" 时回落存下的标题。它的答案不落盘。@openmaxai/chat-sdk 在自己的浮出面挂着期间装一份。@experimental
DOCK_COLUMN_WIDTH_VAR 常量 停靠列写在根元素上的 CSS 自定义属性名("--chat-dock-column-width"),值是列的实际渲染宽度(CSS 长度,已含视口比例上限)。只在列渲染时存在,拖改列宽时逐帧更新。给贴视口右缘的 fixed 元素让开停靠列用,如 right: calc(var(--chat-dock-column-width) + 12px);没有列时要给回落值。最小化坞也用它
DOCK_RESIZE_HANDLE_OUTSET 常量 停靠列拖宽把手伸出列左缘之外的宽度,CSS 长度("0.625rem");列就按它摆放把手。贴列外沿的元素若还要让把手整条点得到,在 DOCK_COLUMN_WIDTH_VAR 之外再加上它
MINIMIZED_DOCK_INSET_VAR 常量 最小化坞挂在 <html> 上的 CSS 自定义属性名("--chat-minimized-dock-inset"):坞占住的视口底边高度(px,含离底边的 16px),坞换行 / 长高时随之更新。坞不渲染时该属性不存在 —— 用 var(--chat-minimized-dock-inset, 0px) 读取并回落到零,贴视口底边的内容(如主聊天页的输入框)据此给坞让位
installChatSurfaceStorage 函数 启动时调用一次,传入存储(如 localStorage),持久化并载入打开的窗口和偏好。不调用就不落盘
setChatSurfaceStorage 函数 只设置存储,不重新载入 store
switchChatSurfaceScope 函数 (scope: string | null, owner?: string | null) => void。按桶(如按组织)分开存打开的窗:存储键实际存成 <key>:<scope>。换桶时清掉内存里的窗、载入新桶(没存过就是空),两个桶都不写,在一次同步调用里做完。null 表示没有桶:清空且不落盘。桶和归属都没变时什么都不做。从不调用的宿主照旧用不分桶的那一个键。偏好不分桶。owner 是桶的归属账号:给了之后每个桶里记下是谁的(owner 字段),载入时记着别的账号或没记归属的桶不用、直接删,发现别的账号的桶时(存储能列出键的话)把其余不属于当前账号的桶一并删;给 null 表示还不知道是谁:清空、不读不写,surfacesHydrated 停在 false,直到再调一次给出账号;省略表示归属不变。不给归属的宿主,存储装上后第一次读时,第一个桶会接手残留的不分桶那一份;给了归属的宿主不接手,直接删
handChatSurfaceScopeToHost 函数 () => void。给存储已按组织与账号分开的宿主用(如 @openmaxai/chat-sdk 的 instanceScope.storage):此后打开的窗按原键存,不加 :<scope> 后缀、不记归属,switchChatSurfaceScope 什么都不做,换组织 / 换账号时收窗与还原归宿主。在装存储之前调,一页里交出就不收回。@experimental
MIN_W、MIN_H 常量 浮窗最小尺寸(320、280)
placementOf、detachedConversationIds、visibleConversationIds、mergeRestoredSurfaces 函数 读 useFloatingChatStore 状态的选择器:一条会话开在哪("primary"、"detached" 或 null)、开在浮出面里的会话(浮窗、收进坞、停靠标签,不论哪种呈现)、正文此刻挂在屏上的会话;mergeRestoredSurfaces 是还原存储时的合并函数
ChatSurfaceProps、ChatSurfaceScope、ChatSurfaceHeaderChrome、ChatSurfacePaneChrome、ChatSurfaceMode、FloatingChat、ChatSurfacePreference、RememberedGeometry、SendShortcut、MentionListStyle、ChatSurfaceStorage 类型
PrimarySurface、FocusedSurface、SurfacePlacement、SurfaceRegistryState 类型 主承载面里的会话、当前聚焦的承载面、placementOf 的返回值、选择器的入参
ListRowDrop、ListRowGhost、UseListRowDragOutOptions 类型 useListRowDragOut 的松手结果、卡片内容(label、avatarUrl、colorKey、isGroupGlyph)、入参

ChatSurfaceProps 包含 isCompact: boolean、renderBody(chat, scope),以及可选的 renderHeader(chat, …)、renderPane(chat, …)、unreadCountOf(conversationId)、unreadMentionOf(conversationId)、mutedOf(conversationId)、onClaimPrimary(conversation)(浮窗或停靠标签落到主聊天放置区时代替登记表的 claimPrimary,主区选中由宿主自己管时用)。isCompact 是应用按整个页面布局做的选择(用抽屉,还是浮窗和停靠列);正文里的组件仍按自己的容器排版。

@openmaxai/chat/surfaces/store

只有承载面的 store 和持久化键,不含任何组件。给每个页面首屏都会加载的代码用(比如登出、换账号时的清理),从 @openmaxai/chat/surfaces 引会把浮窗、停靠列、坞一起带进首屏。和 @openmaxai/chat/surfaces 导出的是同一个 store 实例。

导出 类别 说明
useFloatingChatStore hook 同 @openmaxai/chat/surfaces 的那一个
CHAT_SURFACES_STORAGE_KEY 常量 打开的窗持久化用的存储键("cws-floating-chats")
switchChatSurfaceScope 函数 同 @openmaxai/chat/surfaces 的那一个
handChatSurfaceScopeToHost 函数 同 @openmaxai/chat/surfaces 的那一个
clearPersistedChatSurfaces 函数 (storage) => void。直接从传入的存储里删掉这个键以及它的全部分桶(<key>:<scope>),不管 store 有没有载入过。storage 要有 key、length、removeItem。换账号时用:那一刻可能还没调过 installChatSurfaceStorage,只清 store 清不到存储里那份

@openmaxai/chat/preview

导出 类别 说明
ChatContractSmoke 组件 { conversationId?: string }。只经 ChatHost 读成员、读消息、发消息的简易视图,用来验证手写宿主

@openmaxai/chat/markdown

@openmaxai/chat-sdk 默认 render 画 Agent 回复用的就是它(见 createMarkdownRender)。自己写 render.renderMarkdown,或在应用别处显示 Markdown 时直接用它。

导出 类别 说明
ChatMarkdown 组件 渲染一段 Markdown
DEFAULT_CHAT_MARKDOWN_LABELS 常量 不给 labels 时用的英文文案
DEFAULT_BROADCAST_MENTION_TYPE_BY_NAME 常量 广播提及的名字(@所有人、@Everyone、@All agents 等)及各自对应的提及类型(all / all_agents)
DEFAULT_BROADCAST_MENTION_NAMES 常量 DEFAULT_BROADCAST_MENTION_TYPE_BY_NAME 里的名字;消息带广播提及时高亮它们
broadcastMentionDisplayName 函数 (name, labels, idByName?, typeByName?):正文里命中的广播名按看消息的人的语言(labels)显示成什么;该名字同时是本条的直接提及、或不是广播名时原样返回
resolveChatMarkdownMentions 函数 把消息的结构化 mentions 折成 mentions 属性
trimUrlBoundary 函数 按裸链接的规则,剪掉 URL 末尾的标点、全角正文,以及紧跟在主机名后面的正文
trimUrlAuthority 函数 只做上面那条规则里主机名的部分:在 scheme:// 之后、路径之前,从第一个不可能出现在主机名 / 端口 / userinfo 里的字符处截断(如 https://a.com(note) 里的 ();路径和末尾标点不动
ChatMessageLink 组件 消息正文里的一个链接:默认新标签打开;给了 navigation 时同源的会话链接在本页打开
matchInAppConversationHref 函数 判一个地址是不是同源的会话链接(见 ChatMessageLink),是则回 { routeHref, browserHref },否则 null
isPlainLeftClick 函数 点击是不是不带修饰键的左键
ChatWorkReferenceChip 组件 一颗工作项引用 chip(reference + 可选 links)。给了 links 是带真地址的 <a>:单纯左键调 links.open(上一次还没返回时再点被忽略),不成功调 links.onUnavailable;修饰键 / 中键交给浏览器。不给是同样式的 <span>。ChatMarkdown 与 SDK 默认 render 画的就是它
splitWorkReferences 函数 把纯文本切成「普通文本段 / 引用」的序列,自己写 renderMessageText 时用(发送串识别与内置的文本渲染同一个正则)
splitMessageLinks 函数 把纯文本切成「普通文本段 / { label, href }」的序列:人发的 [label](href)(输入框粘贴的超链接发出去就是这个形态,label 为锚文本),只认 http(s) / mailto / tel;自己写 renderMessageText 时用,排在裸网址链接化之前
isMisleadingLinkLabel 函数 (label, href) => boolean:显示文字整体像网址 / 域名 / 邮箱、而 host 与 href 不同(先 NFKC、去掉格式字符与其余默认可忽略字符,两边转 punycode、小写、忽略前导 www. 再比;带 userinfo 或双向控制符的也算)时为 true;为真时别把它画成可点标题,改成「文字 (真实网址)」
isAddressLikeLabel 函数 (label) => boolean:显示文字整体像网址 / 域名 / 邮箱时为 true(认法与 isMisleadingLinkLabel 相同)。没判冒充、但为真时,标题照网址那样包 <bdi dir="ltr">:正文里前面的 RLO 能把像网址的字倒过来,读成另一个地址
stripBidiControls 函数 (text) => string:去掉 U+202A–U+202E、U+2066–U+2069(嵌入 / 覆盖 / 隔离控制符)。露出来的网址与像网址的文字(「文字 (真实网址)」的两段、自动链接的裸网址、像网址的标题)先过它、再包一层 <bdi>(网址那层 dir="ltr"):段内自带的 PDI / LRI 会让 <bdi> 的隔离失效,没去掉的 RLO 就能把网址倒过来显示。只用于显示(文字、title),href 不动
bindWorkReferenceNotice 函数 (port, { attention, i18n }) => ChatWorkReferenceLinks:给宿主的 workReferences 接上「打不开 ⇒ attention.notify("error", t("workReference.unavailable.<result>"))」

类型:ChatMarkdownProps、ChatMarkdownHooks、ChatMarkdownNavigation、ChatMessageLinkProps、InAppConversationLink、ChatMarkdownLink、ChatMarkdownImageProps、ChatMarkdownImageSlide、ChatMarkdownArtifact、ChatMarkdownArtifactResolution、ChatMarkdownArtifactQuery、ChatMarkdownLabels、ChatMarkdownMentions、BroadcastMentionLabels({ all, all_agents },看消息的人语言下的广播名)、ChatMarkdownMentionRow、ResolveChatMarkdownMentionsOptions、ChatWorkReferenceLinks(宿主工作项引用端口的形状,外加一个可选的失败回调)、MessageLink(splitMessageLinks 认出来的一段链接)。

ChatMarkdown

import { ChatMarkdown, resolveChatMarkdownMentions } from "@openmaxai/chat/markdown";

<ChatMarkdown
  content={source}
  variant="chat"
  mentions={resolveChatMarkdownMentions(message.mentions, { selfId: me })}
  renderLink={({ href, label }) =>
    href.startsWith("/docs/") ? <InAppLink to={href}>{label}</InAppLink> : undefined
  }
/>;

支持 GFM(表格、删除线、任务列表、裸链接)、围栏代码和 ```mermaid 图。画图的库只在回复里真有图时才下载,下载完之前显示源码。源文里的 HTML 按文本显示;除 http(s)、mailto、irc(s)、xmpp 和相对地址外的链接会被清空,除非 isAllowedUrl 放行。javascript:、vbscript:、data: 的地址(链接和图片)一律清空,不看 isAllowedUrl 怎么回。

属性 类型 说明
content string Markdown 源文。必填
variant "default" | "chat" "chat" 字号继承气泡、排版紧凑。默认 "default"(13px 文档正文)
mentions ChatMarkdownMentions 高亮哪些提及,见下
className string 加在根节点(.kb-markdown)上
renderLink (link: ChatMarkdownLink) => ReactNode | null | undefined 接管一个链接(例:站内跳转)。工作项引用(proj:// / issue://)由包画成 chip,不经过它。什么都不回就用默认画法:新标签页打开,带 rel="noopener noreferrer"。artifact:// 链接不经过它。link.attributes 是这个链接的其余属性(如 title),自己画 <a> 时展开上去
isAllowedUrl (url: string) => boolean 放行自定义协议的地址,好让 renderLink 画它。工作项引用(proj:// / issue://)由包自己认、画成 chip,不经这里。javascript:、vbscript:、data: 永远不放行,回 true 也不行
resolveArtifacts (uris: readonly string[]) => Promise<ChatMarkdownArtifactResolution> 一次换出回复里所有 artifact:// 图片和链接的地址。失败了 1 秒后重试一次。不缓存:每条挂上的回复各换各的。它和 useResolveArtifacts 都不给则显示「不可用」
useResolveArtifacts (uris: readonly string[]) => ChatMarkdownArtifactQuery 改用一个 React 钩子来换,回 { status, data };比 resolveArtifacts 优先。用它把结果放进你自己的缓存(例如 React Query),切组织、退出登录时一并清掉。每次渲染都会调,没有 uri 时也调(这时别发请求);传模块级函数,别在给与不给之间切换
renderImage (props: ChatMarkdownImageProps) => ReactNode 自己画图(例如用框架的图片组件)。默认 <img>。把 onError 接上,过期的图才会显示「已失效」
openImageViewer (slides: readonly ChatMarkdownImageSlide[], index: number) => void 打开你的看图器,开合状态归你。点 artifact:// 图时交出回复里所有 contentType 为 image/* 的图。contentType 是别的类型的,点了不打开;没有 contentType 的只看这一张
renderImageViewer (props: { slides; index; onClose }) => ReactNode 画看图器,开合状态归 ChatMarkdown。没给 openImageViewer 时用它。两个都不给,图片不可点
labels Partial<ChatMarkdownLabels> imageUnavailable、imageExpired、fileFallback、fileUnavailableSuffix
navigation ChatMarkdownNavigation { navigate(href), resolveHref(href) },形状同宿主的 navigation 端口,可以直接传它。给了 ⇒ 默认画法的同源会话链接在本页打开,见 ChatMessageLink。renderLink 接管的链接不经它
workReferences ChatWorkReferenceLinks 工作项引用 chip 的地址与打开(见上表 ChatWorkReferenceChip)。不给 ⇒ chip 不可点

ChatMarkdownMentions 是 { names, selfNames?, idByName?, broadcastTypeByName?, broadcastLabels? }。正文里(代码与链接之外)每个 @ 加名字画成 <span class="cws-mention">,带 data-mention-name、取自 idByName 的 data-mention-id,广播名(@所有人、@Everyone 等)带 data-mention-type,复制进输入框仍是提及。selfNames 里的名字另加 cws-mention-self(药丸)。给了 broadcastLabels,广播名按看消息的人的语言显示(以 @所有人 发出的消息,英文读者看到 @Everyone);data-mention-name 仍是正文里写的那个名字。

import { ChatMessageLink } from "@openmaxai/chat/markdown";

<ChatMessageLink href={url} navigation={host.navigation}>{url}</ChatMessageLink>;

ChatMarkdown 的默认链接就是它;自己写 renderMessageText 时也可以用它画正文里的链接。不给 navigation ⇒ 新标签打开(target="_blank"、rel="noopener noreferrer")。给了,而且地址是同源的会话链接 —— 路径是 navigation.resolveHref("/") 那个首页(末尾斜杠可省),参数只有 conversation / group / dm 且至少一个非空,没有 # —— 就不带 target,不带修饰键的左键点击调 navigation.navigate("/?conversation=…")(不带 basePath),会话开在哪由宿主决定;Cmd / Ctrl / Shift / Alt / 中键仍交给浏览器。javascript:、vbscript:、data: 地址不算。其余属性(style、title 等)落在 <a> 上。

resolveChatMarkdownMentions

function resolveChatMarkdownMentions(
  mentions: readonly ChatMarkdownMentionRow[] | null | undefined,
  options?: { resolveName?: (memberId: string) => string | undefined; selfId?: string; broadcastNames?: readonly string[] },
): ChatMarkdownMentions;

与默认 render 读 message.mentions 的口径相同:名字取 username,没有再问 resolveName;取不到名字的行跳过。带 is_mention_all 的行是服务端对广播提及的展开,不算直接提及:只把广播名补进 names,别的都不做。selfId 用来标出提及当前用户的那几行。

@openmaxai/chat/agent-runs

规划中

导出 类别 说明
AgentRunProgress 组件 一次运行的进度行,内含工具步骤和停止按钮
AgentRunSteps 组件 只有工具步骤
AgentStopButton 组件 只有停止按钮
AgentRunList 组件 一个 Agent 在本会话里所有未结束的运行
AgentRunPanel 组件 Agent 面板

配套类型:能力 ChatAgentRunsPort、实时信号 ChatAgentEventSignal(定义)、仓库里的 ChatAgentRun 和 ChatAgentRunPart。