BlockNote 最小化 AI 集成示例:为富文本编辑器接入 AI 的完整实战指南
BlockNote 最小化 AI 集成示例:为富文本编辑器接入 AI 的完整实战指南
导读
本文基于 BlockNote 仓库中的 examples/09-ai/01-minimal 最小示例,完整讲解如何在一个 React 富文本编辑器中接入 AI 能力:通过 @blocknote/xl-ai 扩展注册 AIExtension,用 DefaultChatTransport 连接后端流式接口,并为格式化工具栏、斜杠菜单注入 AI 入口。读完本文,你将掌握 BlockNote AI 的前端接线方式、与 Vercel AI SDK 兼容的后端 /streamText 协议、以及编辑器侧 AI 菜单的交互与状态流转原理,可以直接照搬到自己的项目中。
一、示例概览:这个 minimal 示例做了什么
该示例位于 examples/09-ai/01-minimal,是一个基于 Vite + React 的最小前端工程(@blocknote/example-ai-minimal,见 package.json),它的 README 给出的功能描述非常直接:
这是为 BlockNote 富文本编辑器添加 AI 集成的最小设置。选中一段文字并点击 AI(星星)按钮,或者在编辑器中任意位置输入
/ai,即可访问 AI 功能。
也就是说,示例最终呈现出两种 AI 触发路径:
| 触发方式 | 交互位置 | 效果 |
|---|---|---|
| 选中文本后点击星星按钮 | 格式化工具栏(Formatting Toolbar) | 对所选内容发起 AI 指令 |
输入 /ai |
斜杠菜单(Slash Menu / Suggestion Menu) | 在光标处打开 AI 命令菜单 |
示例预置了一段“开源软件(Open Source software)”主题的文档作为演示内容(App.tsx),方便直接选中文字测试 AI 改写、续写等能力。
除了 README 本身,示例代码还关联了 BlockNote 官方文档中的三篇指南,本文会逐一对应讲解:
二、环境准备与依赖清单
示例的依赖见 package.json,核心依赖可以分成四组:
1. BlockNote 核心与 UI 包
npm install @blocknote/core @blocknote/react @blocknote/mantine
其中 @blocknote/core 提供编辑器内核与 BlockNoteEditor 类型,@blocknote/react 提供 useCreateBlockNote、FormattingToolbar、SuggestionMenuController 等 React 组件,@blocknote/mantine 提供开箱即用的 BlockNoteView 视图组件。
2. AI 能力扩展
npm install @blocknote/xl-ai
这是 BlockNote 的 AI 官方扩展包,从 packages/xl-ai/src/index.ts 可以看到它导出了 AIExtension、AIMenuController、AIToolbarButton、getAISlashMenuItems、getDefaultAIMenuItems 等全部 AI 相关 API。
3. Vercel AI SDK
npm install ai
BlockNote AI 基于 AI SDK(ai 包,示例锁定 ^6.0.5)实现与 LLM 提供商的通信,DefaultChatTransport 即来自 ai 包。
4. 运行时 UI 依赖
示例还依赖 @mantine/core、@mantine/hooks、react(^19.2.3)、@blocknote/ariakit、@blocknote/shadcn 等,用于支撑编辑器 UI 组件渲染。
本地运行方式
工程使用 Vite 管理,package.json 中的脚本如下:
npm install # 安装依赖
npm run dev # 启动本地开发服务器(vite)
npm run build:prod # 类型检查并构建(tsc && vite build)
注意:示例本身只包含前端,真正返回 AI 流式结果的接口需要你自己准备一个后端服务(本文第四节会给出仓库内现成的后端实现)。
三、前端核心实现:一步步搭建带 AI 的编辑器
示例的主入口是 src/App.tsx,完整展示了前端接线。下面按模块拆解。
3.1 创建编辑器并注册 AIExtension
import { BlockNoteEditor } from "@blocknote/core";
import { filterSuggestionItems } from "@blocknote/core/extensions";
import "@blocknote/core/fonts/inter.css";
import { en } from "@blocknote/core/locales";
import { BlockNoteView } from "@blocknote/mantine";
import "@blocknote/mantine/style.css";
import {
FormattingToolbar,
FormattingToolbarController,
getDefaultReactSlashMenuItems,
getFormattingToolbarItems,
SuggestionMenuController,
useCreateBlockNote,
} from "@blocknote/react";
import {
AIExtension,
AIMenuController,
AIToolbarButton,
getAISlashMenuItems,
} from "@blocknote/xl-ai";
import { en as aiEn } from "@blocknote/xl-ai/locales";
import "@blocknote/xl-ai/style.css";
import { DefaultChatTransport } from "ai";
import { getEnv } from "./getEnv";
const BASE_URL =
getEnv("BLOCKNOTE_AI_SERVER_BASE_URL") || "https://localhost:3000/ai";
创建编辑器时,需要做三件关键事情:
const editor = useCreateBlockNote({
dictionary: {
...en,
ai: aiEn, // 为 AI 扩展添加默认翻译
},
// 注册 AI 扩展
extensions: [
AIExtension({
transport: new DefaultChatTransport({
// 后端 API 地址,示例后端源码见 packages/xl-ai-server/src/routes/regular.ts
api: `${BASE_URL}/regular/streamText`,
}),
}),
],
initialContent: [ /* 预置的演示文档,此处省略 */ ],
});
dictionary合并了核心包的en和 AI 扩展的语言包aiEn(从@blocknote/xl-ai/locales导入),缺失这步会导致 AI 菜单文案缺失;AIExtension是 AI 能力的核心,DefaultChatTransport负责把前端请求通过api指向的后端地址转发给 LLM;- 示例中
BASE_URL通过 src/getEnv.ts 读取环境变量:Vite 下对应VITE_BLOCKNOTE_AI_SERVER_BASE_URL/VITE_BLOCKNOTE_AI_SERVER_API_KEY,Next.js 下对应NEXT_PUBLIC_前缀的同名变量,默认回退到https://localhost:3000/ai。
3.2 AIExtension 的底层职责
从源码 packages/xl-ai/src/AIExtension.ts 可以看出,AIExtension 由 createExtension 创建,key 为 "ai",它在内部做了大量工作:
- 维护 AI 菜单状态机:
aiMenuState在"closed"(关闭)与{ blockId, status }(打开)之间流转,打开状态细分为"user-input"(等待用户输入指令)、"thinking"(模型推理中)、"ai-writing"(AI 正在写入文档)、"user-reviewing"(用户审阅建议)以及"error"五种(AIExtension.ts); - 建议变更插件:通过
prosemirror-suggest-changes的suggestChanges()插件,让 AI 的修改以"建议/审阅"形式呈现,而不是直接改坏原文档,并禁用了默认的装饰器(AIExtension.ts); - Agent 光标插件:
createAgentCursorPlugin生成一个默认名称为AI、颜色为#8bc6ff的协作光标,展示 AI 正在编辑的位置(AIExtension.ts); invokeAI执行链:构建 AI 请求 → 通过sendMessageWithAIRequest与 Chat 会话通信 → 根据结果把状态置为"user-reviewing"或"error"(AIExtension.ts);acceptChanges/rejectChanges:审阅阶段的"接受"与"拒绝"。接受时通过巧妙的文档状态捕获与建议重放,让撤销历史直接从"AI 修改后状态"跳回"修改前状态",跳过中间状态;拒绝则直接回滚建议(AIExtension.ts);abort/retry:支持中断正在进行的请求(仅限thinking/ai-writing阶段),以及在出错后基于上一次请求参数重试(AIExtension.ts)。
3.3 自定义格式化工具栏:加入 AI 星星按钮
示例禁用了默认格式化工具栏,替换为一个自定义版本:
const FormattingToolbarWithAI = () => (
<FormattingToolbar>
{...getFormattingToolbarItems()}
{/* 添加 AI 按钮 */}
<AIToolbarButton />
</FormattingToolbar>
);
然后在 BlockNoteView 中通过 FormattingToolbarController 挂载:
<BlockNoteView
editor={editor}
formattingToolbar={false} // 禁用默认工具栏
slashMenu={false} // 禁用默认斜杠菜单
style={{ paddingBottom: "300px" }}
>
{/* 添加 AI 命令菜单 */}
<AIMenuController />
<FormattingToolbarController formattingToolbar={FormattingToolbarWithAI} />
<SuggestionMenuController
triggerCharacter="/"
getItems={async (query) =>
filterSuggestionItems(getSlashMenuItemsWithAI(editor), query)
}
/>
</BlockNoteView>
关键点:
formattingToolbar={false}关闭默认工具栏,随后用FormattingToolbarController注入带AIToolbarButton的新工具栏;AIToolbarButton就是 README 中提到的"星星按钮";AIToolbarButton的实现在 packages/xl-ai/src/components/FormattingToolbar/AIToolbarButton.tsx,它读取当前选区内容并打开 AI 菜单;getFormattingToolbarItems()保留原有加粗、斜体等默认项,...展开语法把它与 AI 按钮拼接在一起,保持原有功能不丢失。
3.4 自定义斜杠菜单:加入 /ai 入口
斜杠菜单的自定义方式与之类似:
const getSlashMenuItemsWithAI = (editor: BlockNoteEditor<any, any, any>) => [
...getDefaultReactSlashMenuItems(editor),
// 添加默认的 AI 斜杠菜单项,或者自定义你自己的
...getAISlashMenuItems(editor),
];
getDefaultReactSlashMenuItems(editor)生成默认的段落、标题等菜单项;getAISlashMenuItems(editor)来自@blocknote/xl-ai,为菜单追加 AI 相关条目(实现在 packages/xl-ai/src/components/SuggestionMenu/getAISlashMenuItems.tsx);- 最终通过
SuggestionMenuController的triggerCharacter="/"指定以/触发,filterSuggestionItems负责按用户输入过滤; AIMenuController是 AI 命令弹窗本身,位于 packages/xl-ai/src/components/AIMenu/AIMenuController.tsx,基于 Floating UI 定位在触发块下方,并会根据 AI 状态(如user-reviewing/error)在关闭时自动调用rejectChanges丢弃变更。
3.5 AI 菜单内置指令一览
AIMenuController 弹出的 AI 菜单内容由 getDefaultAIMenuItems 提供(源码 packages/xl-ai/src/components/AIMenu/getDefaultAIMenuItems.tsx)。当没有选中文本时(例如通过斜杠菜单触发),默认包含:
| key | 指令 | 说明 |
|---|---|---|
continue_writing |
Continue writing | 在光标处续写,默认只允许"新增块"(add: true),不允许修改/删除 |
auto_edit |
自动编辑类指令 | 基于当前文档内容发起 AI 编辑 |
| 改写 / 翻译 / 总结等 | 文本操作指令 | 对选中文本执行不同处理 |
每个菜单项通过 onItemClick: (setPrompt) => ... 的回调签名将用户指令文本 setPrompt 回填到 AI 菜单输入框,随后调用 ai.invokeAI({ userPrompt, streamToolsProvider, ... }) 发起真正的 LLM 请求。选中文本触发时,AI 会带上当前选区作为上下文,从而实现"选中 → 点星星 → 给出指令"的完整链路。
四、后端实现:兼容 AI SDK 的 /streamText 路由
前端 DefaultChatTransport 请求的 URL 是 {BASE_URL}/regular/streamText。仓库中已经给出了对应后端源码:packages/xl-ai-server/src/routes/regular.ts,它基于 Hono 框架实现,完整代码如下:
import { createOpenAI } from "@ai-sdk/openai";
import {
aiDocumentFormats,
injectDocumentStateMessages,
toolDefinitionsToToolSet,
} from "@blocknote/xl-ai/server";
import { convertToModelMessages, streamText } from "ai";
import { Hono } from "hono";
export const regularRoute = new Hono();
// 配置你的模型
const model = createOpenAI({
apiKey: process.env.OPENAI_API_KEY,
})("gpt-4o");
// 使用 streamText 从 LLM 流式返回文本
regularRoute.post("/streamText", async (c) => {
const { messages, toolDefinitions } = await c.req.json();
const result = streamText({
model,
system: aiDocumentFormats.html.systemPrompt,
messages: await convertToModelMessages(
injectDocumentStateMessages(messages),
),
tools: toolDefinitionsToToolSet(toolDefinitions),
toolChoice: "required",
});
return result.toUIMessageStreamResponse();
});
对照官方指南 docs/content/docs/features/ai/getting-started.mdx 中的 Next.js 版本(app/api/chat/route.ts),这套协议本质上就是 AI SDK 标准的 streamText 模式,但有三个 BlockNote 特有的增强点:
injectDocumentStateMessages(messages):把 BlockNote 文档状态从消息元数据中提取出来注入到消息里,让 LLM 能感知当前文档内容;toolDefinitionsToToolSet(toolDefinitions):客户端把 BlockNote 的工具(tool)定义放在请求体中,后端转换为 AI SDK 的 tool set 传给 LLM;aiDocumentFormats.html.systemPrompt:使用 BlockNote 默认系统提示词,它会指导 LLM 如何通过applyDocumentOperations等工具修改 BlockNote 文档(HTML 格式)。官方文档明确说明:你可以覆盖或扩展该 system prompt,但修改后的提示词必须仍然向 AI 解释清楚如何操作 BlockNote 文档结构。
此外 toolChoice: "required" 强制模型必须调用工具,保证 AI 的回复始终以文档操作的形式返回,而不是输出纯文本。
4.1 无真实模型时如何快速联调
如果你暂时没有可用的 LLM API Key,仓库还提供了一个"硬编码响应"的 mock 路由:packages/xl-ai-server/src/routes/mock.ts。它不调用任何模型,而是构造一个固定的 applyDocumentOperations 工具调用流——例如在选中块之后插入一段"BlockNote 是开源块级编辑器"的 HTML 内容(<p>、<ul><li> 等标签),并把 1 秒延迟、tool-input-start/tool-input-finish 等流式事件完整模拟出来,非常适合用于手动测试和演示。它验证了请求协议的关键细节:messages 的最后一条消息中携带 metadata.documentState.blocks<a href="https://link.gitcode.com/i/2f65c39254bbc526c2a32b85970ec992" target="_blank">0].id,后端据此确定工具操作的锚点块 ID([mock.ts)。
五、交互流程:从触发到审阅的完整状态流转
结合 AIExtension 源码与 AIMenuController 组件,一次完整的 AI 交互可以总结为如下链路:
- 触发:选中文本点击星星按钮,或在任意位置输入
/ai打开 AI 菜单;openAIMenuAtBlock(blockID)被调用,编辑器进入"用户输入"状态,AI 菜单弹出(status: "user-input"),编辑器临时设为不可编辑,并把目标块滚动到视口中央(AIExtension.ts); - 指令下发:用户在菜单中输入指令,
invokeAI被调用,状态切换为"thinking";若处于协作模式,会先 fork yDoc 让 AI 在副本上操作,不影响远端(AIExtension.ts); - AI 写入:前端通过
DefaultChatTransport请求/streamText,流式接收 LLM 的工具调用;文档开始出现以prosemirror-suggest-changes渲染的建议标记,状态变为"ai-writing",Agent 光标(默认蓝色#8bc6ff,名字AI)在编辑位置移动,编辑器自动跟随滚动(除非检测到用户主动滚动); - 审阅:流结束,状态变为
"user-reviewing",AI 菜单展示"接受 / 拒绝"操作;- 接受(
acceptChanges):把 AI 修改正式合并进文档,并保持撤销历史干净; - 拒绝(
rejectChanges):回滚全部建议,文档恢复原状(协作模式下同步丢弃 fork 的变更);
- 接受(
- 出错与恢复:若网络失败或工具执行出错,状态置为
"error",菜单提供重试(retry)入口,重试会携带"上一次请求出错,请重试以完成上个指令"的补充提示重新调用 LLM(AIExtension.ts)。
六、从最小示例出发的扩展方向
官方文档(getting-started.mdx 末尾)指出,本示例对应的完整可运行代码与在线演示在仓库的 ai/minimal 示例中即可体验。在此基础上,仓库还提供了更多进阶示例,均可作为下一步扩展的参考:
- 自定义 AI 菜单项:examples/09-ai/03-custom-ai-menu-items 展示如何添加自己的 AI 指令;
- 手动执行 AI 调用:examples/09-ai/05-manual-execution 展示绕过菜单直接调用
invokeAI; - 客户端直连 transport:examples/09-ai/06-client-side-transport 展示不经过后端、由客户端直接连接模型提供商;
- 与协作模式结合:examples/09-ai/04-with-collaboration 展示 AI 与多人实时协作(yjs)共同工作;
- 服务端持久化:examples/09-ai/07-server-persistence 展示聊天历史的服务端存储;
- AI 后端服务源码:packages/xl-ai-server 提供完整的
regular(真实模型)、mock(模拟数据)、serverPersistence(持久化)等路由实现,是理解整个 AI 服务端协议的最佳参考。
七、小结
BlockNote 的 AI 最小示例用最少的代码量完整演示了"编辑器 + 扩展 + 后端流式接口"的三段式接入:前端通过 AIExtension 注册能力、用 AIToolbarButton 和 getAISlashMenuItems 把 AI 入口嵌入格式化工具栏与斜杠菜单、用 AIMenuController 承载指令交互;后端遵循 AI SDK 的 streamText 协议,配合 injectDocumentStateMessages、toolDefinitionsToToolSet 与 BlockNote 默认系统提示词即可打通任意兼容的 LLM 提供商。以此为骨架,再叠加仓库中自定义菜单项、手动执行、客户端直连等进阶示例,就能按需搭建出功能完整的 AI 富文本编辑体验。