@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 仍是正文里写的那个名字。
ChatMessageLink
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。
