Tiptap 中文文档

从 AI 生成迁移到 AI 工具包

AI 生成扩展允许你选择内容并根据你的指令让 AI 模型重写它。

要使用 AI 工具包实现相同功能，推荐的路径是遵循插入内容工作流程。

步骤1：服务器端设置

AI 生成扩展开箱即用，适用于 Tiptap Cloud。

AI 工具包不包含 Tiptap Cloud 服务。相反，它与自定义 AI 后端协作。这赋予你充分的灵活性，可以配合任何 AI 模型提供者和框架使用。

首先，构建一个 API 端点，返回以 HTML 格式生成的 AI 内容。使用诸如 AI SDK 之类的库来调用你的后端。

import { openai } from '@ai-sdk/openai'
import { streamText } from 'ai'

export async function POST(req: Request) {
  const { userRequest, selection } = await req.json()

  const result = streamText({
    model: openai('gpt-5.4-mini'),
    system: `You are an expert writer that can edit rich text documents.
The user has selected part of the document. You will receive the current
content of the selection (in HTML format) and the user's request. Re-write
the content of the selection to meet the user's request. Generate the HTML
code for the new content of the selection. If the user's request is not 
clear or does not relate to editing the document, generate HTML code where
you ask the user to clarify the request. Your response should only contain
the HTML code, no other text or explanation, no Markdown, and your HTML 
response should not be wrapped in backticks, Markdown code blocks, or other
extra formatting.`,
    prompt: `User request:
"""
${userRequest}
"""
选区内容：
"""
${selection}
"""`,
  })

  // 直接返回文本流响应
  return result.toTextStreamResponse()
}

要访问 OpenAI API，请在 OpenAI 控制台 创建 API 密钥，并将其作为环境变量添加。Vercel AI SDK 会自动检测该环境变量。

# .env
OPENAI_API_KEY=your-api-key

步骤2：客户端设置

在客户端代码中，首先调用刚才定义的 API 端点，让 AI 生成内容。该端点返回一个 HTML 内容流。使用 AI 工具包的 streamHtml 方法将内容流导入编辑器。

const toolkit = getAiToolkit(editor)

// 使用 AI 工具包获取选区的 HTML 格式内容
const selection = toolkit.getHtmlRange(editor.state.selection)

// 调用 API 端点获取编辑后的 HTML 内容
const response = await fetch('/api', {
  body: JSON.stringify({
    userRequest: '给这段文字添加表情符号',
    selection,
  }),
})

// 响应是一个 HTML 内容流
const readableStream = response.body

// 使用 AI 工具包将 HTML 流输入到选区
await toolkit.streamHtml(readableStream, { position: 'selection' })

审核 AI 生成的更改

若要显示 AI 生成内容的预览，供用户审核并接受或拒绝更改，可以在 streamHtml 方法中使用 reviewOptions 参数。

await toolkit.streamHtml(readableStream, {
  position: 'selection',
  // 显示内容预览，用户可审核并接受或拒绝更改
  reviewOptions: { mode: 'preview' },
})

在审核更改指南以及 streamHtml 方法的API 参考中了解更多关于审核选项的信息。

实现自动补全

要实现自动补全功能，当用户按下 Tab 键时调用 API 端点生成内容，然后利用 streamHtml 方法插入内容。position 参数也可以设置为 'selection'，因为它与光标所在位置一致。

下面是当用户按下 Tab 键时触发自动补全建议的简化代码片段。

const toolkit = getAiToolkit(editor)
const cursorPosition = editor.state.selection.to

const contentBefore = toolkit.getHtmlRange({ from: 0, to: cursorPosition })
const response = await fetch('/api', {
  body: JSON.stringify({
    userRequest: '自动补全之前的文本',
    selection: contentBefore,
  }),
})

const readableStream = response.body

await toolkit.streamHtml(readableStream, {
  position: 'selection',
})

你也可以选择在插入内容之前预览 AI 生成的内容，而非立即插入。

await toolkit.streamHtml(readableStream, {
  position: 'selection',
  reviewOptions: { mode: 'preview' },
})

生成后，调用 acceptSuggestion 方法可接受建议。

const suggestions = toolkit.getSuggestions()
await toolkit.acceptSuggestion(suggestions[0].id)

下一步

Previously迁移指南