OpenMax
免费试用

自定义消息渲染

用消息展示插件自己绘制某类结构化消息,以及自定义文本和 Markdown 的显示。

自定义消息渲染

某类结构化消息要自己画,写成消息展示插件;文本和 Markdown 怎么画由宿主的 render 能力决定。卡片(cws.card.v1)由卡片插件绘制,结构、按钮和 cards 能力见交互卡片。

结构化消息

自己绘制某类消息,写一个消息展示插件,按 message.type 认领、用 matches 只认你的 schema:

src/poll-renderer.tsx

import {
  type ChatMessageRendererProps,
  defineMessageRenderer,
} from "@openmaxai/chat/message-thread";

function PollView({ message, readOnly }: ChatMessageRendererProps) {
  const poll = parseMySchema(message); // 你自己的判断
  return poll ? <PollCard poll={poll} disabled={readOnly} /> : null;
}

export const pollRenderer = defineMessageRenderer({
  id: "acme-poll",
  types: ["AGENT_STRUCTURED"],
  matches: (message) => parseMySchema(message) !== null, // 不是我的,交给后面的插件或 fallback_text
  layout: "bare", // 自带外壳,不套气泡;不写就套气泡
  View: PollView,
});

用 SDK 时经 ChatProvider 的 messageRenderers 装(连同默认插件 CHAT_SDK_MESSAGE_RENDERERS),直接用 @openmaxai/chat 时经 MessageRenderersProvider 装,见消息展示插件 · 安装。没有插件认领的消息显示 fallback_text。

从 renderStructuredMessage / renderCustomMessage 迁移

宿主 render 上的 renderStructuredMessage 和 renderCustomMessage 已删除。ChatRenderPort 上它们的类型是 never,还写着的宿主编译不过;运行时消息区也不再调用它们。逐个改写成插件:

原来 改成
renderStructuredMessage(message) 认得就返回节点、认不出返回 null 插件的 matches 认不认、View 画;layout: "bare"(原来返回节点就不套气泡)
renderCustomMessage(message)(只对包不认识的类型生效,结果套气泡) 插件的 matches 认不认、View 画;不写 layout(默认套气泡)
每条消息都调一次,靠自己判严 只对 types 里的类型调 matches;内置类型(TEXT 等)不能认领
renderCustomMessage 排在消息区内置的画法(Agent 回复、图片和文件、文本)之后,内置画法先接走的消息轮不到它 插件排在内置画法之前:matches 认领了的消息不再走内置画法,例如带附件的消息不再画成图片和文件。原来靠内置画法先接走的消息,要在 matches 里自己排除。顺序见画正文的先后
宿主自己判断会话是不是只读 View 收到 readOnly,与输入框是不是只读同一个判据
节点里直接用你的应用上下文(查询缓存、路由) 同样可以:View 是普通组件。用 SDK 时在 ChatProvider 外面包你应用的 QueryClientProvider,插件里读到的就是它,见应用自己用 react-query

几个插件认领同一个类型时按安装顺序第一个认领的赢,原来写在一个函数里的先后(先判 A 再判 B)照样按数组顺序排。

文本与 Markdown

render 有这几个成员:renderMessageText 画文本消息正文、图片文件的说明文字和系统通知,renderMarkdown 画 Agent 的回复,renderImage 画消息里的图片,renderRichText 画群描述这类不属于某条消息的文本,可选的 renderMention 画正文之外的一颗 @。签名和约定见宿主能力 · render。

默认实现(createLocalPorts / createChatHost)用 ChatMarkdown 把 Agent 回复按 Markdown 画:表格、代码块、```mermaid 图(回复里有图才加载)、链接、图片、提及和工作项引用。其余文本是纯文本,带链接、@ 提及和工作项引用。

自己画 @ 提及时,每个提及的 <span> 要带 data-mention-name(知道 id 再加 data-mention-id),否则复制粘贴回输入框后不再是真正的 @。

把 Markdown 接到你的应用

回复里的链接、图片往往属于你的应用。用 createChatHost(或 createLocalPorts)的 markdown 选项传钩子;没给的钩子保持默认。

host.tsx

import { createChatHost } from "@openmaxai/chat-sdk/react";

const host = createChatHost({
  adapter,
  markdown: {
    // 站内路由,不新开页;其余链接回 undefined。
    renderLink: ({ href, label }) =>
      href.startsWith(location.origin + "/docs/") ? <InAppLink to={href}>{label}</InAppLink> : undefined,
    // artifact:// 图片和文件,一条回复一次换完。
    resolveArtifacts: async (uris) => ({ resolved: await myResolve(uris) }),
    // 你的看图器;点一张图时交出这条回复里所有的图。
    openImageViewer: (slides, index) => viewer.open(slides, index),
  },
});
钩子 不给时
renderLink 所有链接新开标签页
isAllowedUrl 只有 http(s)、mailto、irc(s)、xmpp 和相对地址保留为链接(javascript:、vbscript:、data: 给不给都不保留)
resolveArtifacts、useResolveArtifacts 去掉 artifact:// 前缀后走 attachments.resolveUrls(失败重试一次,不缓存);那个也没有就显示不可用
openImageViewer、renderImageViewer 走宿主的看大图端口:ports.mediaViewer 给了就用它,没给就是 SDK 自带的查看器;ports.mediaViewer: null 时不可点
renderImage 普通 <img>
labels 取 i18n 的 kb 命名空间

工作项引用([#label](proj://…) / issue://…)不走 isAllowedUrl 和 renderLink,包自己画成 chip。要让它可点,给 ports.workReferences(href + open),人发的消息和 Agent 回复都用它,见 createMarkdownRender;不给时 chip 不可点。

关掉 Markdown

createChatHost({ adapter, markdown: false }) 把 Agent 回复画成保留换行的纯文本。要整项替换 render 就传 ports.render;createPlainTextRender 是纯文本那一份,自己写 renderMarkdown 时可以用 ChatMarkdown。