安装

首先，联系我们的团队以获取 Server AI 工具包的访问权限。

然后，安装开源的 Server AI 工具包包：

npm install @tiptap/server-ai-toolkit

获取编辑器上下文

首先，在编辑器中安装 ServerAiToolkit 扩展。这将修改您的编辑器架构，使您的文档与 Server AI 工具包兼容。

要使用 Server AI 工具包 API，请从您的 Tiptap 编辑器中获取编辑器上下文。这个 JSON 对象包含编辑器 schema 以及 AI 服务器理解有效文档内容所需的其他数据。

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { getEditorContext, ServerAiToolkit } from '@tiptap/server-ai-toolkit'

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

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

在您向 Server AI 工具包发送的每个请求中都传递 editorContext。

存储编辑器上下文

getEditorContext 返回的编辑器上下文是可 JSON 序列化的。您可以将其存储在数据库中，并且只在编辑器扩展或 schema 发生变化时更新它。

使用自定义节点？

如果您的编辑器包含自定义节点或标记，请使用 addJsonSchemaAwareness 进行配置。请参阅自定义节点指南。

更多详情请参阅编辑器上下文 API 参考。

配置授权

Server AI 工具包是一个云端或本地服务。需认证后方可访问其 REST API。

创建密钥 in the Tiptap Cloud dashboard. Go to Authentication > Secrets > Add Secret. The dashboard generates an ES256 key pair and shows you the private key once. Store the private key.
复制你的环境 ID from the dashboard. Go to Authentication > Environment ID. Use it as the JWT iss claim.
在你的服务器上生成 Tiptap Access Control JWT. See the JWT token guide below.
在 API 请求中使用 JWT. Pass it in the Authorization: Bearer JWT header.

For the full JWT format and signing examples, see the Authentication reference.

环境变量

配置以下环境变量：

# .env
TIPTAP_CLOUD_AI_API_URL=https://api.tiptap.dev
TIPTAP_ENVIRONMENT_ID=your-environment-hash-id
TIPTAP_PRIVATE_KEY=your-private-key-pem

TIPTAP_CLOUD_AI_API_URL: Server AI 工具包 API 的基础 URL。
TIPTAP_ENVIRONMENT_ID: 来自 Tiptap 仪表板的环境哈希 ID。签发令牌时用作 iss 声明。
TIPTAP_PRIVATE_KEY: 来自 Tiptap 仪表板的 ES256 私钥（PKCS#8 PEM）。用于在服务器端签署令牌。

创建 JWT 令牌

createJwtToken 函数为 Server AI 工具包 API 签发令牌。当 AI 工具包需要读取和编辑 Tiptap Cloud 文档时，请传入 documentId。

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

/**
 * 签发用于与 Server AI 工具包 API 进行身份验证的 JWT
 */
export async function createJwtToken(documentId?: string): Promise<string> {
  const privateKey = await importPKCS8(process.env.TIPTAP_PRIVATE_KEY!, 'ES256')

  const permissions: { action: string; resource: string }[] = [
    { 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)
}

获取身份验证头

此函数返回 Server AI 工具包 API 请求所需的身份验证头。它是异步的，因为它会签发一个新的 JWT，因此所有示例都使用 await getAuthHeaders(...)。

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

/**
 * 返回 Server AI 工具包 API 的身份验证头
 */
export async function getAuthHeaders(documentId?: string): Promise<Record<string, string>> {
  return {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${await createJwtToken(documentId)}`,
  }
}

Alternative: provide documents directly

如果你在自己的存储中管理文档，而不是使用 Tiptap Cloud，则省略 documentId 选项并在 API 请求中通过 document 字段直接传递文档。此时令牌只需要 AI:Toolkit 权限。

Maintaining an existing integration?

之前的 App ID 和 secret（HS256）流程会将 App ID 发送到 X-App-Id，并将文档服务器凭据嵌入为 JWT 声明，该流程记录在 Legacy authentication 中。

调用 API 端点

完成身份验证后，使用 getAuthHeaders 函数调用 Server AI 工具包 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,
    },
  }),
})

const tools = await response.json()

完整的 API 文档请参见 REST API 参考。

后续步骤

现在您已配置好 Server AI 工具包，开始构建您的 AI 集成：

AI 代理聊天机器人

了解更多 →

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

Previously概述

Next upAgents