---
title: "安装"
description: "AI Toolkit 的安装指南。了解如何安装、配置身份验证，并开始使用 AI Toolkit 云服务。"
canonical_url: "https://tiptap.zhcndoc.com/ai/ai-toolkit/install"
---

# 安装

AI Toolkit 的安装指南。了解如何安装、配置身份验证，并开始使用 AI Toolkit 云服务。

- **1. 请求访问**

  通过联系我们的团队申请访问 Server AI Toolkit。
- **2. 安装包**

  Server AI Toolkit 包是开源的。使用 npm 或你偏好的包管理器从公共 npm registry 安装它。
- **3. 对服务进行身份验证**

  配置 Tiptap Access Control JWT 以访问 Server AI Toolkit 服务。

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

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

```bash
npm install @tiptap/ai-toolkit
```

## 获取编辑器上下文

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

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

```tsx
// 在客户端应用中运行此代码
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 是一个云端或本地服务。要进行身份验证：

1. **在** [Tiptap Cloud 控制台](https://cloud.tiptap.dev) 中**创建一个密钥**（Authentication → Secrets → Add Secret）。生成一对 ES256 密钥，并复制**私钥**，它只会显示一次。将其存储为 `TIPTAP_PRIVATE_KEY` 环境变量。
2. **从控制台复制你的环境 ID**（Authentication → Environment ID）。将其存储为 `TIPTAP_ENVIRONMENT_ID` 环境变量。
3. **生成一个 Tiptap Access Control JWT**（见下方的 [JWT 指南](#create-a-jwt-token)），并在每个请求中将其放入 `Authorization: Bearer JWT` 请求头。

示例 `.env` 文件：

```sh
# 来自 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`。

```ts
// 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](https://tiptap.zhcndoc.com/authentication.md)。

### 认证请求头

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

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

```ts
// 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 端点以获取工具列表：

```ts
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。](https://tiptap.zhcndoc.com/ai/ai-toolkit/agents/ai-agent-chatbot.md)