BlockNote 最小化 AI 集成示例:为富文本编辑器接入 AI 的完整实战指南

原创2026-09-23 13:41:211,461 阅读
文章标签:前端富文本UI组件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 特有的增强点:

  1. injectDocumentStateMessages(messages):把 BlockNote 文档状态从消息元数据中提取出来注入到消息里,让 LLM 能感知当前文档内容;
  2. toolDefinitionsToToolSet(toolDefinitions):客户端把 BlockNote 的工具(tool)定义放在请求体中,后端转换为 AI SDK 的 tool set 传给 LLM;
  3. 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 交互可以总结为如下链路:

  1. 触发:选中文本点击星星按钮,或在任意位置输入 /ai 打开 AI 菜单;openAIMenuAtBlock(blockID) 被调用,编辑器进入"用户输入"状态,AI 菜单弹出(status: "user-input"),编辑器临时设为不可编辑,并把目标块滚动到视口中央(AIExtension.ts);
  2. 指令下发:用户在菜单中输入指令,invokeAI 被调用,状态切换为 "thinking";若处于协作模式,会先 fork yDoc 让 AI 在副本上操作,不影响远端(AIExtension.ts);
  3. AI 写入:前端通过 DefaultChatTransport 请求 /streamText,流式接收 LLM 的工具调用;文档开始出现以 prosemirror-suggest-changes 渲染的建议标记,状态变为 "ai-writing",Agent 光标(默认蓝色 #8bc6ff,名字 AI)在编辑位置移动,编辑器自动跟随滚动(除非检测到用户主动滚动);
  4. 审阅:流结束,状态变为 "user-reviewing",AI 菜单展示"接受 / 拒绝"操作;
    • 接受(acceptChanges):把 AI 修改正式合并进文档,并保持撤销历史干净;
    • 拒绝(rejectChanges):回滚全部建议,文档恢复原状(协作模式下同步丢弃 fork 的变更);
  5. 出错与恢复:若网络失败或工具执行出错,状态置为 "error",菜单提供重试(retry)入口,重试会携带"上一次请求出错,请重试以完成上个指令"的补充提示重新调用 LLM(AIExtension.ts)。

六、从最小示例出发的扩展方向

官方文档(getting-started.mdx 末尾)指出,本示例对应的完整可运行代码与在线演示在仓库的 ai/minimal 示例中即可体验。在此基础上,仓库还提供了更多进阶示例,均可作为下一步扩展的参考:


七、小结

BlockNote 的 AI 最小示例用最少的代码量完整演示了"编辑器 + 扩展 + 后端流式接口"的三段式接入:前端通过 AIExtension 注册能力、用 AIToolbarButton 和 getAISlashMenuItems 把 AI 入口嵌入格式化工具栏与斜杠菜单、用 AIMenuController 承载指令交互;后端遵循 AI SDK 的 streamText 协议,配合 injectDocumentStateMessages、toolDefinitionsToToolSet 与 BlockNote 默认系统提示词即可打通任意兼容的 LLM 提供商。以此为骨架,再叠加仓库中自定义菜单项、手动执行、客户端直连等进阶示例,就能按需搭建出功能完整的 AI 富文本编辑体验。

登录后查看全文
BlockNote