OpenMax
免费试用

概览

插件是什么、怎么安装、默认装哪些,以及按插在界面哪里分成的三类插件。

概览

插件给聊天界面加一块功能,组件本身不用改。输入框里的 @ 提及和 # 工作项引用就是两个插件:每个插件自带触发符、候选面板、工具条按钮和发送时附带的数据,并写明它需要宿主提供哪些能力。

插件的种类

按插件插在界面的哪个位置分成三类:

种类 插在哪里 用来做什么 状态
输入框插件 消息区底部的输入框 触发符和候选面板、工具条按钮、插进输入框的内容、发送时附带的结构化数据 可用
消息展示插件 消息区里的消息 用自己的组件画某类消息,例如交互卡片、投票 可用
消息操作插件 每条消息的「更多」菜单或操作栏 加一项操作,例如「转成任务」 规划中

输入框插件

一个输入框插件可以同时做几件事:响应触发符并弹出候选面板、在工具条上放按钮、往输入框里插入整块内容、发送时附带结构化数据。详见输入框插件。

消息展示插件

认领某类消息(按 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 是可选能力;表情不需要任何能力。每个插件的细节见内置插件。

下一步

  • 输入框插件: 触发符、工具条按钮、内容节点、发送数据和所需能力。
  • 内置插件: @ 提及和 # 工作项引用:做什么、要什么能力、发什么。
  • 编写输入框插件: 从零写一个插件,和默认插件一起装。
  • 消息展示插件: 用自己的组件画某类消息:认领规则、安装、发事件。