自定义消息渲染
用消息展示插件自己绘制某类结构化消息,以及自定义文本和 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。
