安装

首先，联系我们的团队以获取 AI Toolkit 的访问权限。

然后，安装这个开源的 AI Toolkit 包：

npm install @tiptap/ai-toolkit

获取编辑器上下文

首先，在你的编辑器中安装 ServerAiToolkit 扩展。这将修改你的编辑器 schema，使你的文档与 AI Toolkit 兼容。

先获取编辑器上下文。这个 JSON 对象包含 AI Toolkit 需要了解的有关 Tiptap 编辑器的数据。

// 在客户端应用中运行此代码
import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { getEditorContext, ServerAiToolkit } from '@tiptap/ai-toolkit'

const editor = new Editor({
  extensions: [StarterKit, ServerAiToolkit],
})

// 获取编辑器上下文
const editorContext = getEditorContext(editor)

在你向 AI Toolkit 发出的每个请求中都传递 editorContext。

设置授权

Server AI Toolkit 是一个云端或本地服务。要进行身份验证：

在 Tiptap Cloud 控制台中创建一个密钥（Authentication → Secrets → Add Secret）。生成一对 ES256 密钥，并复制私钥，它只会显示一次。将其存储为 TIPTAP_PRIVATE_KEY 环境变量。
从控制台复制你的环境 ID（Authentication → Environment ID）。将其存储为 TIPTAP_ENVIRONMENT_ID 环境变量。
生成一个 Tiptap Access Control JWT（见下方的 JWT 指南），并在每个请求中将其放入 Authorization: Bearer JWT 请求头。

示例 .env 文件：

# 来自 Tiptap 控制台的 ES256 私钥（PKCS#8 PEM）。用于在服务端签名 token。
TIPTAP_PRIVATE_KEY=your-private-key-pem
# 来自 Tiptap 控制台的环境 ID。签名 token 时用作 `iss` 声明。
TIPTAP_ENVIRONMENT_ID=your-environment-hash-id

# AI Toolkit API 的基础 URL。
TIPTAP_CLOUD_AI_API_URL=https://api.tiptap.dev

创建一个 JWT token

为 AI Toolkit API 签名一个 JWT token，具有以下属性：

签发者：TIPTAP_ENVIRONMENT_ID
权限
- { action: 'AI:Toolkit', resource: '*' } 用于访问 AI Toolkit
- { action: 'Documents:Write', resource: 'document-id' } 用于访问 Tiptap Cloud 文档
受众：['AI', 'Documents']

createJwtToken 会创建一个用于访问 AI Toolkit 的 JWT token。当 AI Toolkit 需要读取和编辑 Tiptap Cloud 文档时，请传入 documentId。

// lib/server-ai-toolkit/create-jwt-token.ts
import { SignJWT, importPKCS8 } from 'jose'

export async function createJwtToken(documentId?: string) {
  const privateKey = await importPKCS8(process.env.TIPTAP_PRIVATE_KEY!, 'ES256')

  const permissions = [{ action: 'AI:Toolkit', resource: '*' }]

  if (documentId) {
    permissions.push({ action: 'Documents:Write', resource: documentId })
  }

  return new SignJWT({ permissions })
    .setProtectedHeader({ alg: 'ES256' })
    .setIssuer(process.env.TIPTAP_ENVIRONMENT_ID!)
    .setAudience(documentId ? ['AI', 'Documents'] : ['AI'])
    .setIssuedAt()
    .setExpirationTime('30m')
    .sign(privateKey)
}

有关完整的 JWT 格式和签名示例，请参阅 Authentication reference。

认证请求头

将 Authorization: Bearer JWT 请求头传递给每个 API 请求。

getAuthHeaders 函数会创建这些请求头：

// lib/server-ai-toolkit/get-auth-headers.ts
import { createJwtToken } from './create-jwt-token'

export async function getAuthHeaders(documentId?: string) {
  return {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${await createJwtToken(documentId)}`,
  }
}

调用 API 端点

调用 /fetch-tools API 端点以获取工具列表：

import { getAuthHeaders } from './lib/server-ai-toolkit/get-auth-headers'

const apiBaseUrl = process.env.TIPTAP_CLOUD_AI_API_URL || 'https://api.tiptap.dev'

const response = await fetch(`${apiBaseUrl}/v4/ai/toolkit/fetch-tools`, {
  method: 'POST',
  headers: await getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
    tools: {
      tiptapRead: true,
      tiptapEdit: true,
    },
  }),
})

后续步骤

现在你已经设置好 AI Toolkit，开始构建你的 AI 集成：

AI 智能体聊天机器人

构建一个能够编辑文档并通过聊天进行交互的对话式 AI。

PreviouslyOverview

Next upAgents