OpenMax
免费试用

宿主能力

ChatHost 上每一项能力的全部成员:签名、必填与否,以及失败时该抛错、返回空还是返回 undefined。

宿主能力

宿主(ChatHost)的每个字段是一项能力。本页逐项列出成员,参数和返回值里的数据类型见数据模型。各项能力打开什么功能、缺了会怎样见能力;所有类型从 @openmaxai/chat/host 导出(ChatComposerPreferencesPort、ChatSendShortcut 两个:规划中)。

能力 必填 成员表
identity 是 本页
messaging 是 本页
drafts 是 本页
inboundDelivery 是 本页
render 是 本页
attention 是 本页
i18n 是 本页
instanceScope 是 本页
attachments 是 本页
composerPreferences 否 本页
mediaViewer 否 图片查看器
conversations 否,缺了抛错 本页
groupManagement 否,缺了抛错 本页
memberStore 否 本页
workItems 否,缺了抛错 本页
mentions 否 本页
cards 否 交互卡片
profileCard 否 名片
agentConfig 否 本页
agentGroupPolicy 否 本页
conversationResources 否 本页
messageSearch 否 本页
agentRuntime 否 本页
navigation 否 本页
workReferences 否 本页
forward 否 本页
agentActivity 否 只读进度(实验性 · 过渡):Agent 执行过程的实时运行表,Chat SDK 的宿主上总有,见 Chat SDK 宿主。规划中的 Agent 运行能力落地时替换它
agentRuns 规划中 否 Agent 运行:停止运行,加载运行及其事件,见 @openmaxai/chat

createLocalPorts 提供 drafts、attachments、render、attention、i18n、instanceScope 的默认实现,见接入自有后端;只有要自己实现时才需要逐个成员对照下面的表。

出错时怎么办

  • 失败就 reject。 异步成员出错时返回被拒绝的 Promise(抛错)。界面按成员决定是回滚并提示、静默放弃还是留在原地重试,写在各表的「出错」里。提示经 attention.notify("error", …) 显示,见错误与会话过期。
  • 「没有」不是出错。 标明「取不到返回 undefined」或「没有返回空数组」的成员,在找不到、已删除、无权访问时照此返回,不要抛错:界面要据此区分「没有」和「出错」。
  • 服务端明确不允许(如超过撤回时限)时,recallMessage、editMessage(以及 addReaction、removeReaction)抛 ChatOperationNotAllowedError,或任何带 chatOperationNotAllowed: true 的对象。撤回、编辑时界面提示「无法撤回 / 无法编辑」,而不是「失败,请重试」;表态不区分「不允许」,被拒绝和其他失败一样回滚,提示「表态失败 / 取消表态失败」。
  • 由 createChatHost({ adapter }) 造的宿主,组件收到的错误都是 ChatSdkError:kind 为 forbidden 的同样带 chatOperationNotAllowed: true,其余按种类提示或静默,规则和本节相同,见错误模型。 规划中
  • 发送失败的说明会显示给用户。 sendMessage 抛出的 Error 的 message 原样作为提示文字,没有 message 时显示通用文案。写成给人看的话。
  • 卡片操作不抛错,返回带 kind 的结果,见交互卡片 · 错误。
  • 同步成员不要抛错。 currentUserId、getMember、previews、t 这类在渲染时调用,抛错会让整个组件抛错。

identity

类型 ChatIdentityPort。当前用户、查成员、搜通讯录。

成员 签名 必填 行为与出错
currentUserId () => string 是 当前用户的成员 id。同步读;数据没到时返回 "",这时自己的消息会显示成别人的,到了以后换一个新 host 对象
getMember (memberId: string) => ChatParticipant | undefined 是 按 id 取成员,同步。取不到返回 undefined,界面不会替你补取
listMembers (conversationId: string) => readonly ChatParticipant[] 是 会话成员,同步;@ 候选用它。分页和缓存归宿主
searchDirectory (input: { search: string; cursor?: string }) => Promise<ChatDirectoryPage> 是 搜组织通讯录(不是会话成员):搜人开聊、建群和加人、@ 候选里的组织成员。失败时 reject;@ 候选只剩会话成员,不弹提示

messaging

类型 ChatMessagingPort。可选成员各自打开一项功能,缺了只少那项功能,见能力 · 可选能力。

成员 签名 必填 行为与出错
sendMessage (input: SendMessageInput) => Promise<void | ChatSendOutcome> 是 发一条消息。被内容过滤拦下时返回 { blocked },不要抛错。失败时 reject:消息留在原地标「发送失败」,可重试或删除,同时提示错误的 message。入参带 clientMessageId 时,把它作为后端的去重键,并在读回的消息上作为 client_msg_id 带回:重试才不会多出一条,确认时那一行才不重挂
loadThread (conversationId: string, cursor?: string, options?: ChatThreadLoadOptions) => Promise<ChatThreadPage> 是 不带 cursor 取最新一页,带了往更早翻;options.direction: "newer" 时 cursor 是 newerCursor、往更新翻;不带 cursor、给了 options.aroundSeq(seq,大于 0)时取围着这条的一窗,两头还有就各带 nextCursor / newerCursor。不认 aroundSeq 的宿主照旧回最新一页:开会话落不到首条未读,跳到窗口外的消息时提示跳不过去。options.limit 是这一页最多要几条的上限提示,只在往更新翻与取最新一页时给(新消息区按游标往更新翻一页要 100 条,打开时接着补的那两页不带);可以不认、也可以截短(如服务端上限),包只按返回的 newerCursor / nextCursor 判有没有更多,不按条数推。消息按 seq 升序。取不到就 reject,不要返回空页:没有 nextCursor 的空页会被当成「没有更早的消息」
createConversation (input: CreateConversationInput) => Promise<{ conversationId: string }> 是 建会话,只返回 id。会话种类由宿主决定。失败时 reject,提示「打开对话失败」
loadThreadSince (conversationId: string, afterSeq: number) => Promise<readonly ChatMessage[] | ChatThreadSincePage> 否 取 seq 大于 afterSeq 的消息,升序。可以返回数组,也可以返回 { messages, hasNewer }。返回数组时,没有新的返回 [],界面拿到空数组才停,所以有新消息时至少多一次请求;返回 hasNewer: false 时界面合并完这一批就停。hasNewer 要取服务端的判断,不要按条数推。一次可以只返回一部分,界面会接着取,有次数上限,宿主不要自己循环。失败时 reject,静默放弃,下一个信号再取
loadMessage (conversationId: string, messageId: string) => Promise<ChatMessage | undefined> 否 按 id 取一条(引用条、图片说明文字,以及收到别人编辑的 messageChanged 后取新正文)。已撤回、已删除、无权访问时返回 undefined,不要抛错
addReaction (messageId: string, code: string) => Promise<void | ChatMessageChangeResult> 否 加一个表态。和 removeReaction 一起提供才生效。界面先乐观显示,失败时 reject:回滚并提示。同一条消息的同一个表情不会并发调用
removeReaction (messageId: string, code: string) => Promise<void | ChatMessageChangeResult> 否 撤掉自己的一个表态,出错同上
recallMessage (messageId: string) => Promise<void | ChatMessageChangeResult> 否 撤回自己的消息。界面先乐观显示为撤回,失败时 reject:回滚并提示;不允许时抛 ChatOperationNotAllowedError。成功后要让 deleted_at 真正落到消息上,否则下次加载消息又回来
editMessage (messageId: string, edit: ChatMessageEditInput) => Promise<void | ChatMessageChangeResult> 否 改自己的消息,附件是整组替换。失败、不允许时同 recallMessage,编辑框留着、框里还是用户改过的字,可以重试。成功后新正文要落到消息上,content_version 加 1
listMessageEdits (messageId: string) => Promise<readonly ChatMessageEdit[]> 否 修订历史,按时间升序。点「(已编辑)」时取
loadChangesSince (conversationId: string, sinceChangeSeq: number) => Promise<ChatThreadChangesPage> 否 取改动日志里编号大于 sinceChangeSeq 的一页(0 表示从第一笔起),按编号升序。和 getMessagesByIds 一起提供才生效,见下面的改动日志。一次只返回一页,界面按 nextSinceChangeSeq、hasMore 接着取,宿主不要自己循环。失败时 reject,静默放弃,下一次补洞再取
getMessagesByIds (conversationId: string, messageIds: readonly string[]) => Promise<ChatThreadMessagesByIdsPage> 否 按 id 取一批消息的最新一版,撤回的交回墓碑。每次至多 100 个、互不重复的 id。不在了的放进 missingIds(界面按删除处理),这次没交回、要再取的放进 deferredIds。失败同 loadChangesSince
loadReadCursors (conversationId: string) => Promise<ChatReadCursorSnapshot> 否 打开会话时取一次已读快照,之后靠 read、delivery 信号推进。取不到就 reject,不要编一份;界面静默不显示回执
sendTyping 规划中 (conversationId: string, active: boolean) => Promise<void> 否 告诉会话里的其他人「我正在输入」或「停了」,由输入框按发出正在输入的节奏调用。失败时静默,不提示不重试。没有时别人看不到你在输入
pinMessage 规划中 (messageId: string) => Promise<void> 否 置顶一条消息。和 unpinMessage 一起提供才生效。界面先乐观显示,失败时 reject:回滚并提示;不允许时抛 ChatOperationNotAllowedError。成功后 pinned_at、pinned_by 要落到消息上
unpinMessage 规划中 (messageId: string) => Promise<void> 否 取消置顶,出错同上

改动结果:addReaction、removeReaction、recallMessage、editMessage 成功时可以返回 ChatMessageChangeResult,也可以照旧返回 void。

字段 类型 说明
changeSeq number 这次改动在会话改动日志里的编号;0 表示没有新改动(重复的表态、撤回被别的撤回或删除抢先)。会话有改动水位(一窗带了 headChangeSeq)时,聊天据它认出这次改动随后到达的推送;没有改动水位时不起作用
editedAt string 编辑时服务端记的时间(ISO 串),只有编辑给

返回 void 时界面照旧等推送或下一次取回这条消息来收尾。

改动日志:loadThreadSince 只取 seq 更大的消息,离开、断线期间别人对已有消息的改动(编辑、撤回、删除、表态、卡片落定)取不回来。宿主提供 loadChangesSince 和 getMessagesByIds、并且一窗带上 headChangeSeq 时,界面每次补洞(打开或切回会话、重连)补完新消息接着从改动水位补改动,见补洞调度 · 补改动。

字段 在哪 说明
headChangeSeq ChatThreadPage、ChatThreadSincePage 和这一页同一快照读出的改动日志最新编号(服务端列表响应的 head_change_seq),改动水位从它起。往更早、往更新翻的页也给。拿不到就不给,不要编 0:不给时这个会话不补改动
changes ChatThreadChangesPage ChatThreadChange(changeSeq、messageId、messageSeq)的数组,按编号升序;tooOld 时为空
nextSinceChangeSeq、hasMore ChatThreadChangesPage 下一页从哪取、后面还有没有
tooOld ChatThreadChangesPage 请求的位置已经取不到了(超过保留期,或比最新编号还大):界面重取最新一窗
messages、missingIds、deferredIds ChatThreadMessagesByIdsPage 找到的消息、不在了的 id、要再取一次的 id

正文是 Markdown 规划中:SendMessageInput 的 text 是 Markdown 源文。输入框里加的格式都在这一段文字里,不分标题和正文,也没有单独的格式标记。宿主照常把 text 交给后端,不需要声明额外能力;输入框也不按宿主能力隐藏格式按钮,见输入框 · 展开编辑。收到的人发的消息正文同样按 Markdown 画,见 render。

drafts

类型 ChatDraftsPort。按会话存草稿;输入框写,会话列表读。

成员 签名 必填 行为与出错
get (conversationId: string) => ChatComposerDraft | undefined 是 读一份草稿,切回会话或输入框重新挂载时恢复。没有返回 undefined
save (conversationId: string, draft: ChatComposerDraft) => void 是 写一份草稿。空草稿删掉还是留着由你决定
clear (conversationId: string) => void 是 发送成功后清掉
previews () => Readonly<Record<string, string>> 是 会话 id → 列表上显示的一行草稿预览。每次返回新对象也可以
subscribe (listener: () => void) => () => void 是 草稿变了就调用 listener,返回退订函数。多调几次没关系

草稿和 instanceScope.storage 要分开:列表要能订阅草稿的变化。

inboundDelivery

类型 ChatInboundDeliveryPort。实时连接由 SDK 持有:宿主给出连接参数(下表四个必填成员),SDK 用它们建连、鉴权、断线重连,把服务端的帧翻成信号交给组件。应用不再自己另开一条实时连接。

成员 签名 必填 行为与出错
endpointUrl () => string 是 SDK 连接的地址;没有就返回 "",此时不建连
authToken () => Promise<string | undefined> 是 SDK 每次连接前取一次令牌;返回 undefined 表示当前没有凭据,不再重连
clientId () => string 是 这台设备或这个客户端的标识,SDK 连接时带上
isMock () => boolean 是 是否演示模式。为 true 时 SDK 不建连,信号只来自 subscribe
subscribe (onSignal: (signal: ChatInboundSignal) => void) => () => void 否 宿主转发信号的入口,返回退订函数,过渡用:应用迁移期间仍持有自己的连接时,把那条连接收到的帧翻成信号从这里转给组件,SDK 就不再另建连接(同一设备 id 的两条连接会互相覆盖同步位置);应用去掉自己的连接后不再提供它。演示宿主(isMock() 为 true)也从这里推信号。信号种类和字段见实时与同步 · 实时信号

信号的约定:messages 只说「有新消息」,不带正文;reaction 带齐四个字段,因为表态改的是已有消息;messageChanged 只带哪一条、哪种改动(edited / recalled / deleted),不带正文;两者在帧里有改动编号时带 changeSeq,没有就不给;reconnected 只在真的重新连上时发一次,不要每次心跳都发;可选:连接第一次连上时发一次 connected(列表和开着的会话补一次,什么都不重置)。转发信号的宿主,连接断开时还要转发 disconnected,收到别人的输入状态时转发 typing,规划中的连接状态条和正在输入靠它们。规划中

render

类型 ChatRenderPort。消息正文和图片由宿主渲染。

成员 签名 必填 行为与出错
renderMessageText (text: string, ctx: { message: ChatMessage }) => ReactNode 是 文本消息的正文、图片文件的说明文字、系统通知。链接、@ 提及、工作项引用都由你画;@ 提及的元素要带 data-mention-name(有身份时再带 data-mention-id,@所有人带 data-mention-type),复制回输入框才认得。文本消息的正文是 Markdown,要按 Markdown 画,@ 提及和链接照上面的要求处理 规划中
renderMarkdown (source: string, ctx?: { message: ChatMessage }) => ReactNode 是 Agent 的回复。ctx.message.mentions 用来判断 @ 的是不是当前用户

两个成员按同一套 Markdown 规则画:支持哪些写法、链接和 HTML 怎么处理、@ 提及和代码怎么处理,见消息区 · Markdown 正文。规划中 | renderImage | (props: { src: string; alt?: string; onError?: () => void }) => ReactNode | 是 | 消息里的图片。把 onError 接到 <img onError>:签名地址过期时界面靠它换新地址,你不要自己重试 | | renderRichText | (text: string) => ReactNode | 是 | 不属于某条消息的文本,如群描述 | | renderMention | (mention: { memberId: string; name: string }) => ReactNode | 否 | 正文之外的一颗成员 @,如选择卡头部「请 @A 作答」。画成与正文 @ 同样的样式和 data-mention-* 属性;不提供时界面画一个只有蓝字的 @ |

render 的成员在渲染时调用,不要抛错。

renderStructuredMessage 和 renderCustomMessage 已删除,类型上是 never,写了编译不过。自己画某类消息改写成消息展示插件,见迁移。

attention

类型 ChatAttentionPort。

成员 签名 必填 行为与出错
notify (level: "info" | "success" | "error", message: string) => void 是 弹一条提示。message 是给用户看的文字
setUnreadSignal (count: number) => void 是 所有会话的未读总数变化时调用,count 不含免打扰和只是旁观的会话;显示成标题角标、图标还是什么都不做由你决定

i18n

类型 ChatI18nPort。

成员 签名 必填 行为与出错
t (key: string, vars?: Record<string, string | number>) => string 是 取一条文案,vars 填进占位符。见国际化
locale () => string 是 当前语言,如 "zh-CN";时间格式按它

instanceScope

类型 ChatInstanceScopePort。同一页面上有几个聊天实例时把它们隔开。

成员 签名 必填 行为与出错
queryKeyScope () => string 是 这个实例的命名空间,聊天内部的请求结果按它分开存
invalidate (scope: "conversations" | "messages" | "members") => void 是 让宿主那边的这类数据失效重取。聊天在发送、撤回、编辑、置顶、隐藏、开新会话之后调用
storage { get(key: string): string | null; set(key: string, value: string): void; remove(key: string): void } 是 按实例隔开的键值存储(如上次打开的会话、客户端标识)。可以用 localStorage,也可以只在内存里

attachments

类型 ChatAttachmentsPort。上传和收到的附件。用 createLocalPorts 时只需给上传函数,见接入自有后端 · 上传。

成员 签名 必填 行为与出错
limits () => { maxAttachments: number; maxFileSizeBytes: number } 是 一条消息最多几个附件、单个文件多大。maxAttachments 为 0 时没有附件按钮
start (files: readonly File[], hooks?: { onTasks?(taskIds: readonly string[]): void }) => Promise<readonly string[]> 是 上传,返回附件 id,与 files 一一对应、同序(编辑时顺序就是显示顺序)。拿到任务 id 后在返回 Promise 之前同步调用 hooks.onTasks;给不出任务 id 就不调。失败时 reject:消息标「发送失败」,提示错误的 message
cancel (taskId: string) => void 是 用户取消上传,消息整条撤掉。对已结束的任务调用时什么也不做,不要抛错
getTask (taskId: string) => ChatUploadTask | undefined 是 任务当前的进度。没有这个任务返回 undefined。任务没变时必须返回同一个对象,否则组件无限重渲染
subscribeTasks (listener: () => void) => () => void 否 任何任务有变化就调用 listener。不提供就不显示进度条和取消按钮
resolveUrls (artifactIds: readonly string[]) => Promise<Readonly<Record<string, string>>> 否 把附件 id(不带 artifact:// 前缀)批量换成现在能用的地址。换不出的 id 不放进结果,不要给空串;对应附件显示为「不可用」。不提供时收到的附件都显示为不可用
resolveDownloadUrl (artifactId: string) => Promise<string | undefined> 否 用户点文件下载键时调用:把一个附件 id(不带 artifact:// 前缀)换成此刻能下载的地址。resolveUrls 的地址是画消息时换的,点下载时可能已过期。换不出回 undefined,传输失败 reject;两种情况文件行都显示「下载失败」,下载键变成重试。不提供时下载键打开 resolveUrls 换回的地址

composerPreferences

类型 ChatComposerPreferencesPort。

成员 签名 必填 行为与出错
sendShortcut () => ChatSendShortcut 是 "enter":Enter 发送;"mod-enter":Ctrl(Mac 上 Cmd)+ Enter 发送。改了设置立即生效

不提供这项能力时按 "enter"。

conversations

类型 ChatConversationsPort。渲染 ConversationList 时必须有。

成员 签名 必填 行为与出错
list (input: { search?: string; includeHidden?: boolean; cursor?: string }) => Promise<ChatConversationPage> 是 取一页会话。search 为空是默认列表;includeHidden 为真时包括已隐藏的。失败时 reject
setPinned (conversationId: string, pinned: boolean) => Promise<void> 是 置顶或取消置顶。成功后列表重取。失败时 reject:列表不变,提示「置顶失败」或「取消置顶失败」
setHidden (conversationId: string, hidden: boolean) => Promise<void> 是 隐藏或取消隐藏。成功后列表重取。失败时 reject:列表不变,提示「隐藏会话失败」或「取消隐藏失败」;在搜索结果里点开已隐藏的会话时,取消隐藏失败就不打开它
setMuted (conversationId: string, muted: boolean) => Promise<void> 否 静音或取消静音(只改提醒,消息和未读照常)。成功后列表立即重取,会话的 muted 跟着变。失败时 reject:列表不变,会话列表或 ConversationHeader 提示「静音失败」或「取消静音失败」。旁观的会话不调。不提供时顶部栏没有静音开关,会话列表的行与置顶宫格也没有静音操作
markReadUntil (conversationId: string, readUntilSeq: number) => Promise<void> 否 把当前用户在这个会话的已读位置推到 readUntilSeq(含),服务端只前进不后退。消息区按看到的最后一条真消息调用:旁观的会话不调,同一会话只报更大的 seq,失败时下次还会再报。成功后列表重取(未读清掉)。失败时 reject,界面不提示。不提供时消息区不上报已读,未读一直留着
loadConversation (conversationId: string) => Promise<(ChatConversation & { muted: boolean }) | undefined> 否 按 id 取一个会话,用于从链接打开不在已加载列表里的会话。不存在或无权访问时返回 undefined,不要抛错;其他失败时 reject。不提供时这类会话打不开,见适配器接口 · conversations;muted 必填,填当前用户自己对这个会话的静音状态
loadUnreadTotal 规划中 () => Promise<{ count: number; mentions: number }> 否 后端算的未读总数,免打扰和只是旁观的会话不计入。不提供时由已取到的会话加出来,会话列表没翻到底之前只是下限

置顶、隐藏和静音的状态从会话的 pinned、done、muted 读,见数据模型 · ChatConversation。

groupManagement

类型 ChatGroupManagementPort。渲染 CreateGroupModal 或 ChatInfoPanel 时必须有。加人、移除成员、退群、解散是可选成员:有哪一项,界面才给哪一个按钮;缺席就是没有这个按钮,不要给一调就抛的空桩。createChatHost 造的宿主在适配器有 groupManagement 时才有它,写成功后由 SDK 刷新会话列表或成员表。四个可选成员失败时与 createGroup 同一约定:抛 ChatSdkError,界面先显示 message,空的按 kind 显示包里的文案,再没有就是这一项自己的兜底句。

成员 签名 必填 行为与出错
createGroup (input: ChatCreateGroupInput) => Promise<{ conversationId: string }> 是 建群,返回新会话 id。不要改用 messaging.createConversation。请求失败时抛 ChatSdkError:弹窗留着,在弹窗里显示它的 message;message 为空时按 kind 显示包里的文案(如「没有权限执行这个操作」),没有对应文案的种类显示「创建群聊失败,请重试」。抛别的异常会被当成代码错误:打一条 console.error 后照原样抛出
updateGroupProfile (conversationId: string, updates: ChatGroupProfileUpdate) => Promise<void> 是 改群名或群描述,一次只改一个。失败时 reject,提示保存失败
addMembers (conversationId: string, memberIds: readonly string[]) => Promise<ChatGroupMembersChangeResult> 否 把几个人加进群。逐人判,部分成功照常 resolve,没成的人在 failed 里带种类与原因;整次请求没成才 reject。不提供时群信息面板没有「添加成员」
removeMembers (conversationId: string, memberIds: readonly string[]) => Promise<ChatGroupMembersChangeResult> 否 把几个人移出群(通常只有群主能做)。结果与出错同 addMembers。不提供时没有「移除成员」
leave (conversationId: string, options?: ChatGroupLeaveOptions) => Promise<ChatGroupLeaveResult> 否 当前用户退群。群主可给继任者 newOwnerId,不给由服务端挑一个人类成员,只剩 Agent 时服务端解散;走了哪一支见 ChatGroupLeaveResult。失败时 reject。不提供时没有「退出群聊」
dissolve (conversationId: string) => Promise<void> 否 解散这个群(通常只有群主能做)。失败时 reject。不提供时没有「解散群聊」

memberStore

类型 ChatMemberStoreReader(@openmaxai/chat-store 成员仓库 ChatMemberStore 的 getMembers 与 subscribe)。群信息面板与消息区从这里读每个人在会话里的角色,按 can() 画按钮。可选;没有时角色一律当作不知道,按兜底规则画。createChatHost 造的宿主带它(宿主自己成员数据的读面)。

成员 签名 必填 行为与出错
getMembers (conversationId: string) => readonly ChatMembership[] | undefined 是 这个会话的成员表,每行带会话内角色 role。还没取过时返回 undefined(角色不知道),取过而没有人时是空数组。没有变化时返回同一个对象
subscribe (conversationId: string, listener: () => void) => () => void 是 这个会话的成员表变了时叫 listener,返回取消订阅的函数

workItems

类型 ChatWorkItemsPort。输入框的 # 工作项引用。可选;没有时需要它的 # 插件不装,见输入框插件。

成员 签名 必填 行为与出错
search (input: { search: string; projectId?: string; cursor?: string }) => Promise<ChatWorkItemPage> 是 按文字搜项目和 issue,同一列表返回,用 kind 区分。search 为空串取默认一页。给了 projectId 只返回这个项目下的 issue(展开项目时用),这些 issue 的 projectId 必须是它

subConversations

类型 ChatSubConversationsPort。场景子会话:挂在私聊或群下、为一个场景单开的会话,有自己的历史、未读和实时,成员与父会话相同。可选;没有时不画子会话界面(会话列表不为 has_unread_subconversations 画圆点)。

成员 签名 必需 行为与错误
findOrCreate (input: ChatSubConversationFindOrCreateInput) => Promise<ChatSubConversationResult> 是 在 input.parentConversationId 下、或与 input.peerMemberId 的私聊下找 input.context.key 对应的子会话,没有就建。幂等。交回子会话(永远不是父会话)与是否新建;命中已归档的照样交回。owner 已弃用:owner 取自凭据。失败 reject 一个形如 ChatSdkError 的错误,后端码认得时 message 是给用户的一句话

mentions

类型 ChatMentionsPort。消息区的「@我」跳转。

成员 签名 必填 行为与出错
listUnread (conversationId: string) => Promise<ChatUnreadMentionsPage> 是 这个会话里未读的 @。mentions 可以只是一页,totalMe、totalAll 是总数。失败时 reject,不显示跳转按钮
markRead (conversationId: string, messageIds: readonly string[]) => Promise<void> 是 跳到某条 @ 之后标为已读。失败时静默
markAllRead (conversationId: string) => Promise<void> 是 全部标为已读,要清掉所有页,不只是已取到的那页。失败时 reject,计数恢复

agentConfig

类型 ChatAgentConfigPort。单聊头部的 Agent 模型选择。

成员 签名 必填 行为与出错
loadModelState (agentMemberId: string) => Promise<ChatAgentModelState | undefined> 是 Agent 当前的模型配置。没有权限、不是 Agent 时返回 undefined,不要抛错;控件显示为禁用
setModel (agentMemberId: string, model: string) => Promise<void> 是 切换模型,model 是 ChatAgentModelOption.key。返回不代表已生效:界面接着轮询 loadModelState,直到 applyState 不再是 applying。失败时 reject,提示
setModelVisibility (agentMemberId: string, visible: boolean) => Promise<void> 是 模型名对外显不显示。失败时 reject,提示

agentGroupPolicy

类型 ChatAgentGroupPolicyPort(@experimental)。群里 Agent 的回复策略:读策略、谁能改、改它在某个群的回复模式、改它的群聊白名单。读与白名单是 Agent 级的(跨群),只有回复模式按群。消费方是 ChatInfoPanel 里的「AGENT 群聊设置」;不实现 ⇒ 那一块不画。

成员 签名 必填 行为与出错
loadGroupPolicy (agentMemberId: string, options?: { fresh?: boolean }) => Promise<ChatAgentGroupPolicy | undefined> 是 这个 Agent 的群策略(只含群聊部分)。取不到返回 undefined,不要抛错。fresh: true 时绕过缓存向服务端重取:先读再改白名单时以它为准
canManageGroupPolicy (agentMemberId: string) => Promise<boolean | undefined> 是 当前用户能不能改这个 Agent 的群策略。false 表示确定不能(画只读行);判不出(不知道当前用户、取不到归属)返回 undefined,面板不画这个 Agent 那一行。服务端仍是终审
setGroupReplyMode (input: { agentMemberId, conversationId, mode: ChatAgentGroupReplyMode }, options?: { signal?: AbortSignal }) => Promise<ChatAgentPolicyApplyOutcome> 是 改这个 Agent 在某个群的回复模式。等 Agent 确认后才 resolve;被拒、离线、未确认都以结论返回,不抛错
setGroupAllowlist (input: { agentMemberId, conversationIds: readonly string[] }, options?: { signal?: AbortSignal }) => Promise<ChatAgentPolicyApplyOutcome> 是 把群聊白名单设成 conversationIds(完整名单,[] 为清空)。结论同上
openAgentSettings (agentMemberId: string) => void 否 打开这个 Agent 的设置页(改群聊范围的地方)。不给 ⇒ 面板不画「去 Agent 设置调整」入口

四个必填方法都不要 reject:读不到、判不出返回 undefined,写的各种结局以结论返回。万一 reject,面板按「取不到 / 判不出」处置,写操作提示失败。不管结论如何(含 aborted),写完之后的 loadGroupPolicy 都要读到服务端的值;aborted 只停止等待,已提交的写不撤回。

conversationResources

类型 ChatConversationResourcesPort(@experimental)。会话里的图片、文件与链接,新的在前,按游标翻页。可选;不实现 ⇒ 列它们的界面不画。

成员 签名 必填 行为与出错
list (query: ChatConversationResourcesQuery, options?: { signal?: AbortSignal }) => Promise<ChatConversationResourcePage> 是 一页行(ChatConversationResource:kind 为 image / file 的带 artifactId、fileName、contentType、sizeBytes;kind 为 link 的带 url、host、title;都带 id、messageId、messageSeq、senderId、messageAt)。query 按 kinds、senderId、since / until 与文字筛选,按 cursor / limit 翻页。只交调用者此刻看得到的消息的行:撤回、删除的消息不出行,编辑过的按当前版本出行。image / file 行一定带 artifactId(用 attachments.resolveUrls / resolveDownloadUrl 换地址)。最后一页不带 nextCursor。失败时 reject;没有资源回空页

messageSearch

类型 ChatMessageSearchPort(@experimental)。在一条会话里搜消息。可选;不实现 ⇒ 搜消息的界面不画。

成员 签名 必填 行为与出错
search (query: ChatMessageSearchQuery, options?: { signal?: AbortSignal }) => Promise<ChatMessageSearchPage> 是 一页命中(ChatMessageSearchHit:messageId、conversationId、seq、senderId、createdAt,以及 snippet:纯文本段,命中的段 match: true,当文字渲染)。命中必须是调用者此刻看得到的消息:撤回、删除的消息永远不是命中,原文不出现在任何片段里。命中必须基于当前正文:只匹配旧正文的结果不返回,摘要按当前正文生成;编辑过的消息按新正文照样能搜到。一页可能少于 limit 甚至为空而 nextCursor 还在,照它接着翻。空白 query 回空页。失败时 reject;没有命中回空页

交出去的命中之后仍可能被撤回:宿主点命中跳转时要处理「这条消息已经不在」。

agentRuntime

类型 ChatAgentRuntimePort(@experimental)。在会话信息侧栏里管理私聊另一端的 Agent:Agent 身份卡上的管理区(暂停 / 恢复、中断、重启、可折叠的运行状态)。有哪些动作、给谁、每个怎么走都由宿主回答;包不复制权限规则和 Agent 的生命周期。不实现 ⇒ 没有管理区。

成员 签名 必填 行为与出错
loadState (agentMemberId: string) => Promise<ChatAgentRuntimeState | null> 是 null ⇒ 当前用户不管理这个 Agent:整个管理区都不画(也没有「Agent 设置」)。否则回 { actions, status? }:actions 按显示顺序,每个 { action, enabled }(enabled: false 画成禁用;用户永远用不了的不列),status 是运行状态的各行 { label, value },都是成品文字。失败时 reject:管理区显示出错与「重试」,侧栏其余部分不受影响
runAction (agentMemberId: string, action: ChatAgentRuntimeAction, ui: ChatAgentRuntimeActionUi) => Promise<void> 是 action 是 "pause" | "resume" | "interrupt" | "restart"。整个流程归宿主(确认、请求、提示;包不弹任何提示),流程结束时 resolve,做成、取消、失败都一样;包随后再调一次 loadState。确认框用 ui.render(node) 画:包把它挂在发起动作的那块管理区旁边(同一棵 React 树),从浮窗里点的就开在那扇窗里;再调一次会替换,传 null 移除,runAction 结束或那块管理区消失时移除

类型 ChatNavigationPort。应用内跳转;聊天组件不读取它。

成员 签名 必填 行为与出错
navigate (href: string) => void 是 跳到 href
resolveHref (href: string) => string 是 把 href 换成可以放进 <a href> 的地址

workReferences

类型 ChatWorkReferencesPort。消息正文里工作项引用([#label](proj://…) / issue://…)指向哪、怎么打开;聊天组件不读取它。用它的是正文渲染:交给 ChatMarkdown 的 workReferences(自己写 renderMessageText 时交给 ChatWorkReferenceChip 的 links),SDK 默认 render 经 ports.workReferences 自动接上。渲染层没拿到它时,引用照样画成 chip,但不可点。

成员 签名 必填 行为与出错
href (ref: ChatWorkReference) => string | undefined 是 画在 <a href> 上的浏览器地址(含 basePath),中键、新标签、复制链接都用它。同步、不发请求。回 undefined ⇒ chip 仍可点,只是没有地址
open (ref: ChatWorkReference) => Promise<"ok" | "denied" | "missing" | "failed"> 是 单纯左键点击时调:用当前用户的权限读对象并跳转。上一次还没返回时再点被忽略。不是 "ok"(抛错按 "failed")时,接了 bindWorkReferenceNotice 的渲染层经 attention.notify("error", …) 提示

forward

类型 ChatForwardPort(@experimental)。把消息转发到别的会话。可选:没有它,或者没有 conversations(选择器的候选取 conversations.list 的第一页),消息上就没有「转发」按钮。目前 MessageThread 与 MessageThreadNext(SDK 的 CwsMessageThread)只对单条消息给入口,调用 forwardMessages;组件里还没有调用 mergeForwardMessages 的入口。@openmaxai/chat-sdk 的 createChatHost 建的宿主从适配器的 forward 拿到它。

成员 签名 必填 行为与错误
forwardMessages (sourceConversationId: string, body: ForwardRequestBody) => Promise<ForwardResponseData<ForwardTargetResult>> 是 把 body.message_ids 里的每条消息复制到每个目标,对应 POST /conversations/{sourceConversationId}/messages/forward。body 原样发出:每个目标带自己的 client_msg_id,在用户第一次提交时生成、重试时原样复用,所以重试在服务端是重放。按请求顺序每个目标给一条结果,所有目标都失败也照样 resolve;弹窗逐个列出失败的目标。只有整个请求失败才 reject,弹窗说转发失败,并用同一份请求体重试。服务端拒绝的是请求本身(留言超长、源消息已撤回)时抛 ChatOperationNotAllowedError(或任何带 chatOperationNotAllowed: true 的对象):原样重发不可能成功,弹窗说无法转发、不给重试
mergeForwardMessages (sourceConversationId: string, body: ForwardRequestBody) => Promise<ForwardResponseData<MergeForwardTargetResult>> 是 同上,但每个目标发一条会话记录消息(CHAT_HISTORY)