概览
插件是什么、怎么安装、默认装哪些,以及按插在界面哪里分成的三类插件。
概览
插件给聊天界面加一块功能,组件本身不用改。输入框里的 @ 提及和 # 工作项引用就是两个插件:每个插件自带触发符、候选面板、工具条按钮和发送时附带的数据,并写明它需要宿主提供哪些能力。
插件的种类
按插件插在界面的哪个位置分成三类:
| 种类 | 插在哪里 | 用来做什么 | 状态 |
|---|---|---|---|
| 输入框插件 | 消息区底部的输入框 | 触发符和候选面板、工具条按钮、插进输入框的内容、发送时附带的结构化数据 | 可用 |
| 消息展示插件 | 消息区里的消息 | 用自己的组件画某类消息,例如交互卡片、投票 | 可用 |
| 消息操作插件 | 每条消息的「更多」菜单或操作栏 | 加一项操作,例如「转成任务」 | 规划中 |
输入框插件
一个输入框插件可以同时做几件事:响应触发符并弹出候选面板、在工具条上放按钮、往输入框里插入整块内容、发送时附带结构化数据。详见输入框插件。
消息展示插件
认领某类消息(按 message.type),用自己的组件画它的正文。交互卡片就是一个:卡片插件 cardRenderer 认领 CARD 消息,宿主没有 cards 能力时不装,卡片按只读画。插件可以用 emit 把事件交给应用。详见消息展示插件。
消息操作插件
规划中
往每条消息的「更多」菜单里加一项,也可以放到操作栏上,例如把一条消息「转成任务」。用 defineMessageAction 定义,经 ChatProvider 的 messageActions 安装:
to-task-action.tsx
import { defineMessageAction } from "@openmaxai/chat/message-thread";
import { ListTodo } from "lucide-react";
export const toTaskAction = defineMessageAction({
id: "to-task",
label: (locale) => (locale.startsWith("en") ? "Turn into a task" : "转成任务"),
icon: ListTodo,
requiredPorts: ["workItems"],
isAvailable: (message) => message.type === "TEXT",
onSelect: async (message, { notify }) => {
await createTaskFrom(message);
notify("success", "已转成任务");
},
});
<ChatProvider host={host} messageActions={[toTaskAction]}>{/* …… */}</ChatProvider>;
字段(ChatMessageAction) |
类型 | 必填 | 说明 |
|---|---|---|---|
id |
string |
是 | 唯一;和内置操作(copy、react、reply、edit、recall、pin)或别的插件重名时,组装时抛错 |
label |
(locale: string) => string |
是 | 菜单项和按钮的文字,也是无障碍名称 |
icon |
ComponentType<{ className?: string }> |
否 | 图标;放到操作栏时必填 |
requiredPorts |
readonly string[] |
否 | 需要的宿主能力,缺一项就不装,和输入框插件相同 |
isAvailable |
(message: ChatMessage, ctx: ChatMessageActionContext) => boolean |
否 | 这条消息上显示不显示;不给就对所有已发出、没撤回的消息显示。渲染时调用,不要抛错 |
onSelect |
(message: ChatMessage, ctx: ChatMessageActionContext) => void | Promise<void> |
是 | 点了之后做什么。返回的 Promise 没结束前这一项禁用;reject 时用错误的 message 提示 |
placement |
"menu" | "bar" |
否 | 默认 "menu"。"bar" 时同时放在操作栏,排在「更多」按钮前面 |
destructive |
boolean |
否 | 红色显示,排在菜单的分隔线之后 |
ChatMessageActionContext 有 host(当前宿主)、conversation、currentUserId、locale 和 notify(等于 host.attention.notify)。
- 菜单里插件的操作排在内置操作之后、分隔线之前,按
messageActions里的顺序。 - 不传
messageActions就没有插件操作;和plugins分开传,plugins只放输入框插件。 - 只读的会话里插件操作照样按
isAvailable判断,要不要在只读时隐藏由插件自己决定(ctx.conversation)。
安装插件
插件和宿主一起交给 ChatProvider,用 plugins 属性:
app.tsx
import { COMPOSER_PLUGINS } from "@openmaxai/chat/composer";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
import { emojiShortcodePlugin } from "./emoji-shortcode-plugin";
// 不传 plugins:装默认插件
<ChatProvider host={host}>{/* …… */}</ChatProvider>;
// 默认插件之外再加一个自己的
<ChatProvider host={host} plugins={[...COMPOSER_PLUGINS, emojiShortcodePlugin]}>
{/* …… */}
</ChatProvider>;
- 不传
plugins就装默认插件COMPOSER_PLUGINS。 - 传了就只装你给的这些。要保留默认插件,把它们和自己的插件放进同一个数组;顺序决定工具条按钮的先后。
- 整个聊天用同一套插件。列表可以直接写在 JSX 里:SDK 按插件 id 比较,id 不变就不重建编辑器(所以同一个 id 换了插件对象不会生效)。
plugins里放的是输入框插件。消息操作插件经messageActions安装规划中,见消息操作插件;消息展示插件经messageRenderers安装,见消息展示插件 · 安装。
emojiShortcodePlugin 的写法见编写输入框插件。
宿主缺能力的插件不装
每个插件用 requiredPorts 写明需要哪些能力。宿主缺其中任何一项,SDK 就不装这个插件,不抛错,其余插件和输入框照常,你也不用自己过滤。例如宿主没有 workItems,输入框里就没有 # 触发和 # 按钮,@ 照常可用。宿主在运行时变了,插件会跟着重新挑。见能力 · 输入框插件。
默认插件
COMPOSER_PLUGINS 里是内置插件,按这个顺序:
| 插件 id | 作用 | requiredPorts |
|---|---|---|
emoji 规划中 |
表情按钮:打开表情面板,选中的表情作为文字插入。输入框收起和展开时都有 | 无 |
mention |
@ 提及:插入 @ 胶囊,发送时带上结构化的 mentions |
identity、i18n |
work-reference |
# 工作项引用:搜索项目和问题,插入引用标签 |
workItems |
identity、i18n 是必填能力,所以 @ 在任何宿主上都有;workItems 是可选能力;表情不需要任何能力。每个插件的细节见内置插件。
