---
title: "REST API（旧版 v3 端点）"
description: "Server AI Toolkit REST API 端点的完整参考。"
canonical_url: "https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api-v3"
---

# REST API（旧版 v3 端点）

Server AI Toolkit REST API 端点的完整参考。

Server AI Toolkit 提供用于 AI 智能体工具的 REST API 端点。

> **已弃用的端点:**
>
> 这些 API 端点已弃用，请参阅[新的 API
> 端点](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api.md)。

> **向后兼容性:**
>
> 之前的 API 名称，例如 `schemaAwarenessData`、`getSchemaAwarenessData`、
> `/v3/ai/toolkit/tools` 和 `/v3/ai/toolkit/schema-awareness-prompt`，为了
> 向后兼容仍然可用，但它们已弃用。对于新的集成，请使用 `editorContext`、
> `getEditorContext` 和 `/v3/ai/toolkit/tools`。

> **Postman 集合:**
>
> 浏览 Server AI Toolkit REST API 的 [Postman
> 集合](https://www.postman.com/tiptap-platform/tiptap-workspace/collection/42722929-6a366c4c-10e4-4674-93c3-da35b70357a7?action=share\&source=copy-link\&creator=42722929)。

## 认证

所有请求都必须包含：

- `Authorization: Bearer <JWT>`
- `X-App-Id: <APP_ID>`

使用你的 AI 密钥在服务端生成 JWT。请在 [Server AI
Toolkit 设置](https://cloud.tiptap.dev/v2/cloud/ai) 页面获取你的 App ID 和密钥。

```ts
import jwt from 'jsonwebtoken'

const JWT_TOKEN = jwt.sign(
  {
    experimental_document_server_id: 'your-document-server-id',
    experimental_document_server_management_api_secret:
      'your-document-server-management-api-secret',
  },
  'your-ai-secret-key',
  { expiresIn: '1h' },
)
```

更多信息请参阅 [授权指南](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/install.md#set-up-authorization)。

### Document Server 凭据

当你希望 Server AI Toolkit 自动获取并保存 Tiptap Cloud
文档时，请在 JWT 中包含以下声明：

- `experimental_document_server_id`
- `experimental_document_server_management_api_secret`

## 基础 URL

托管的基础 URL 是：

```txt
https://api.tiptap.dev
```

在下面的示例中，请求被写作 `BASE_URL/v3/ai/...`。

## 如何提供文档

工具端点只接受一种文档来源：

- `document`：内联 Tiptap JSON
- `experimental_documentOptions`：Tiptap Cloud 文档引用

`experimental_documentOptions` 具有以下结构：

- `documentId`（`string`，必填）：Tiptap Cloud 文档标识符。
- `userId?`（`string | null`，可选）：归因于 AI 执行编辑操作的标识符。
- `field?`（`string | null`，可选，默认值：`"default"`）：在省略或为 `null` 时，目标为文档中的特定协作字段（Y.js XML 片段）。当你的文档在同一个 `documentId` 下存储多个可编辑字段时——例如标题和正文分开存储——请使用此项。

Tiptap Cloud 文档示例：

```json
{
  "experimental_documentOptions": {
    "documentId": "your-document-id",
    "userId": "ai-assistant"
  }
}
```

针对非默认协作字段的示例：

```json
{
  "experimental_documentOptions": {
    "documentId": "your-document-id",
    "userId": "ai-assistant",
    "field": "title"
  }
}
```

内联文档示例：

```json
{
  "document": {
    "type": "doc",
    "content": []
  }
}
```

> **线程需要云文档:**
>
> 线程和评论端点始终需要 `experimental_documentOptions.documentId`。

## 格式

大多数端点接受一个 `format` 字段：

- `"json"`：标准 JSON 表示形式
- `"shorthand"`：Tiptap Shorthand，一种适用于提示词和模型输出的高效令牌格式

## 工具端点

### 获取工具定义

```txt
POST /v3/ai/toolkit/tools
```

返回可供 AI 代理使用的[工具定义](#available-tools)。

请求体：

- `editorContext`（`EditorContext`，必需）。通过 `getEditorContext` 函数获取的编辑器上下文。请参阅[安装指南](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/install.md)。
- `tools?`（`Record<string, boolean>`，可选）：启用或禁用单个工具。支持的键请参阅[工具参考](#available-tools)。
- `operationMeta?`（`string`，可选，默认值：`""`）
- `format?`（`'json' | 'shorthand'`，可选，默认值：`'json'`）
- `schemaAwarenessData?`（`SchemaAwarenessData`，可选，已弃用）：请改用 `editorContext`。为向后兼容而保留。

响应：

- `prompt`（`string`）：将其添加到 AI 请求的系统提示中。它会教 AI Tiptap 文档如何工作、可以包含哪些元素，以及文档格式如何工作。
- `tools`（`array`）
  - `name`（`string`）
  - `description`（`string`）
  - `inputSchema`（`object`）：AI 生成的工具 `input` 的 JSON schema。

### 执行工具

```txt
POST /v3/ai/toolkit/execute-tool
```

执行一个 Server AI Toolkit 工具，例如 `tiptapRead`、`tiptapEdit`、`getThreads` 或
`editThreads`。有关每个受支持工具及其类型形状，请参阅[工具参考](#available-tools)。

请求体：

- `toolName`（`string`，必需）
- `input`（必需）：由 AI 模型生成的工具输入。其结构取决于
  `toolName`；请参阅[工具参考](#available-tools)。
- `editorContext`（`EditorContext`，必需，除非提供了 `schemaAwarenessData`）
- `schemaAwarenessData?`（`SchemaAwarenessData`，可选，已弃用）：请改用 `editorContext`。为向后兼容而保留。
- `toolConfig?`（可选）：由开发者提供、而非
  AI 模型提供的工具特定参数。请参阅[工具参考](#available-tools)。
- `format?`（`'json' | 'shorthand'`，可选，默认值：`'json'`）
- `reviewOptions?`（[`ReviewOptions`](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md)，可选，默认值：`{ mode: 'disabled' }`）
- `experimental_commentsOptions?`（`{ threadData?: Record<string, unknown>, commentData?: Record<string, unknown> }`，可选）：在与线程相关的工具执行期间创建的新线程和评论所附加的元数据。
- 恰好以下二者之一：
  - `document`
  - `experimental_documentOptions`

响应：

- `output`：工具响应，应由 AI 模型读取。请参阅[工具参考](#available-tools)。
- `toolResult`：以适合开发者解析的格式提供的工具响应。不应由 AI 读取。请参阅[工具参考](#available-tools)。
- `docChanged`（`boolean`）：文档是否因工具调用而发生更改
- `document`（`object | null`）：AI 对文档进行更改后的文档

### 流式执行工具

```txt
POST /v3/ai/toolkit/stream-tool
```

流式执行工具。请求结构与 `POST /v3/ai/toolkit/execute-tool` 相同。流式响应格式仍在最终确定中。

由于此端点在实时连接上操作文档，它可能会返回 REST 端点不会返回的连接和并发错误。它们会在响应流中以 `error` 事件的形式到达——请参阅[流式传输和会话错误](#streaming-and-session-errors)。

## 旧版工作流端点

> **工作流端点已弃用:**
>
> 工作流端点会保留给现有集成使用。它们将在未来版本中移除。

### 获取工作流定义

使用以下任一端点：

- `POST /v3/ai/toolkit/workflows/edit`
- `POST /v3/ai/toolkit/workflows/insert-content`
- `POST /v3/ai/toolkit/workflows/proofreader`
- `POST /v3/ai/toolkit/workflows/threads`

请求体：

- `format?` (`'json' | 'shorthand'`, 可选，默认：`'json'`). `proofreader` 工作流仅接受 `'shorthand'`。

响应：

- `systemPrompt` (`string`)
- `outputSchema` (`object`)

示例：

```curl
curl --location 'BASE_URL/v3/ai/toolkit/workflows/edit' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "format": "shorthand"
  }'
```

### 读取工作流的文档内容

```txt
POST /v3/ai/toolkit/read/read-document
```

读取文档内容并返回可供工作流使用的内容。

请求体：

- `range?` (`{ from: number, to: number }`, 可选，默认：整个文档)
- `schemaAwarenessData` (`SchemaAwarenessData`, 必需)
- `format?` (`'json' | 'shorthand'`, 可选，默认：`'json'`)
- `chunkSize?` (`number`, 可选，默认：`32000`)
- `reviewOptions?` ([`ReviewOptions`](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md), 可选，默认：`{ mode: 'disabled' }`)
- 恰好一个：
  - `document`
  - `experimental_documentOptions`

响应：

- `output`
  - `success` (`boolean`)
  - `content?` (`unknown`)
  - `error?` (`string`)
- `docChanged` (`boolean`)
- `document` (`object | null`)

示例：

```curl
curl --location 'BASE_URL/v3/ai/toolkit/read/read-document' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "format": "shorthand",
    "reviewOptions": {
      "mode": "disabled"
    },
    "experimental_documentOptions": {
      "documentId": "your-document-id",
      "userId": "ai-assistant"
    }
  }'
```

### 读取当前选区

```txt
POST /v3/ai/toolkit/read/read-selection
```

读取选区并返回选区负载或明确的空状态。

请求体：

- `range` (`{ from: number, to: number }`, 必需)
- `schemaAwarenessData` (`SchemaAwarenessData`, 必需)
- `format?` (`'json' | 'shorthand'`, 可选，默认：`'json'`)
- `chunkSize?` (`number`, 可选，默认：`32000`)
- `reviewOptions?` ([`ReviewOptions`](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md), 可选，默认：`{ mode: 'disabled' }`)
- 恰好一个：
  - `document`
  - `experimental_documentOptions`

响应：

- `output`
  - 当选区为空时：
    - `isEmpty` (`true`)
  - 当选区包含内容时：
    - `isEmpty` (`false`)
    - `content` (`unknown`)
    - `nodeHashes` (`string[]`)
    - `nodeRange` (`{ from: number, to: number }`)
    - `prompt` (`string`)
- `docChanged` (`boolean`)
- `document` (`object | null`)

示例：

```curl
curl --location 'BASE_URL/v3/ai/toolkit/read/read-selection' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "range": { "from": 10, "to": 42 },
    "format": "shorthand",
    "experimental_documentOptions": {
      "documentId": "your-document-id"
    }
  }'
```

### 读取线程

```txt
POST /v3/ai/toolkit/read/threads
```

读取 Tiptap Cloud 文档中的所有线程和评论。

请求体：

- `schemaAwarenessData` (`SchemaAwarenessData`, 必需)
- `format` (`'json' | 'shorthand'`, 必需)
- `experimental_documentOptions` (`{ documentId: string, userId?: string, field?: string | null }`, 必需)

响应：

- `output`
  - `threads?` (`unknown[]`)
  - `error?` (`string`)
- `docChanged` (`boolean`)
- `document` (`object | null`)

示例：

```curl
curl --location 'BASE_URL/v3/ai/toolkit/read/threads' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "format": "shorthand",
    "experimental_documentOptions": {
      "documentId": "your-document-id",
      "userId": "ai-assistant"
    }
  }'
```

### 执行插入内容工作流

```txt
POST /v3/ai/toolkit/execute-workflow/insert-content
```

请求体：

- `input` (`unknown`, 必需)：生成的插入内容负载
- `range?` (`{ from: number, to: number }`, 可选)
- `schemaAwarenessData` (`SchemaAwarenessData`, 必需)
- `format?` (`'json' | 'shorthand'`, 可选，默认：`'json'`)
- `chunkSize?` (`number`, 可选，默认：`32000`)
- `reviewOptions?` ([`ReviewOptions`](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md), 可选，默认：`{ mode: 'disabled' }`)
- 恰好一个：
  - `document`
  - `experimental_documentOptions`

响应：

- `output`
  - `error?` (`string`)
  - `range?` (`{ from: number, to: number }`)
- `docChanged` (`boolean`)
- `document` (`object | null`)

示例：

```curl
curl --location 'BASE_URL/v3/ai/toolkit/execute-workflow/insert-content' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "input": "This is the replacement content.",
    "range": { "from": 10, "to": 42 },
    "format": "shorthand",
    "reviewOptions": {
      "mode": "disabled"
    },
    "experimental_documentOptions": {
      "documentId": "your-document-id",
      "userId": "ai-assistant"
    }
  }'
```

### 执行 Tiptap 编辑工作流

```txt
POST /v3/ai/toolkit/execute-workflow/tiptap-edit
```

请求体：

- `input` (`object`, 必需)：编辑工作流操作
- `schemaAwarenessData` (`SchemaAwarenessData`, 必需)
- `format?` (`'json' | 'shorthand'`, 可选，默认：`'json'`)
- `chunkSize?` (`number`, 可选，默认：`32000`)
- `reviewOptions?` ([`ReviewOptions`](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md), 可选，默认：`{ mode: 'disabled' }`)
- 恰好一个：
  - `document`
  - `experimental_documentOptions`

响应：

- `output`
  - `operationResults?` (`array`)
  - `reason?` (`'validationError' | 'unexpectedError'`)
  - `error?` (`string`)
- `docChanged` (`boolean`)
- `document` (`object | null`)

示例：

```curl
curl --location 'BASE_URL/v3/ai/toolkit/execute-workflow/tiptap-edit' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "input": {
      "operations": [
        {
          "type": "replace",
          "target": "abc123",
          "content": "# Updated heading\n\nUpdated paragraph content."
        }
      ]
    },
    "format": "shorthand",
    "reviewOptions": {
      "mode": "disabled"
    },
    "experimental_documentOptions": {
      "documentId": "your-document-id",
      "userId": "ai-assistant"
    }
  }'
```

### 执行校对者工作流

```txt
POST /v3/ai/toolkit/execute-workflow/proofreader
```

请求体：

- `input` (`object`, 必需)：校对者操作
- `schemaAwarenessData` (`SchemaAwarenessData`, 必需)
- `format` (`'shorthand'`, 必需)
- `chunkSize?` (`number`, 可选，默认：`32000`)
- `reviewOptions?` ([`ReviewOptions`](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md), 可选，默认：`{ mode: 'disabled' }`)
- 恰好一个：
  - `document`
  - `experimental_documentOptions`

响应：

- `output`
  - `operationResults` (`array`)
- `docChanged` (`boolean`)
- `document` (`object | null`)

示例：

```curl
curl --location 'BASE_URL/v3/ai/toolkit/execute-workflow/proofreader' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "input": {
      "operations": []
    },
    "format": "shorthand",
    "reviewOptions": {
      "mode": "trackedChanges",
      "trackedChangesOptions": {
        "userId": "ai-assistant"
      }
    },
    "experimental_documentOptions": {
      "documentId": "your-document-id"
    }
  }'
```

### 执行评论工作流

```txt
POST /v3/ai/toolkit/execute-workflow/threads
```

请求体：

- `input` (`object`, 必需)：线程操作
- `schemaAwarenessData` (`SchemaAwarenessData`, 必需)
- `format?` (`'json' | 'shorthand'`, 可选，默认：`'json'`)
- `experimental_documentOptions` (`{ documentId: string, userId?: string, field?: string | null }`, 必需)
- `experimental_commentsOptions?` (`{ threadData?: Record<string, unknown>, commentData?: Record<string, unknown> }`, 可选)：工作流创建的新线程和评论所附加的元数据。

响应：

- `output`
  - `operations?` (`array`)
  - `error?` (`string`)
- `docChanged` (`boolean`)
- `document` (`object | null`)

示例：

```curl
curl --location 'BASE_URL/v3/ai/toolkit/execute-workflow/threads' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "input": {
      "operations": [
        {
          "type": "createComment",
          "threadId": "thread-123",
          "content": "请澄清这一点。"
        }
      ]
    },
    "format": "shorthand",
    "experimental_documentOptions": {
      "documentId": "your-document-id",
      "userId": "ai-assistant"
    },
    "experimental_commentsOptions": {
      "threadData": {
        "source": "ai"
      },
      "commentData": {
        "source": "ai"
      }
    }
  }'
```

## 错误处理

REST 端点返回错误时采用以下结构：

```json
{
  "error": {
    "message": "对出错原因的人类可读描述。",
    "status": 502,
    "code": "document_load_failed"
  }
}
```

- `message`（`string`）：人类可读描述。不要基于它进行匹配——措辞可能会变化。
- `status`（`number`）：HTTP 状态码，也会设置在响应中。
- `code`（`string`）：一个可用于分支判断的稳定标识。验证失败会使用
  `code: "validation_failed"`，并附加一个 `issues` 数组。

API 使用标准 HTTP 错误码：

- `400 Bad Request`：无效正文、无效格式、缺少文档来源，或缺少 Document
  Server 凭据
- `401 Unauthorized`：缺少或无效的 JWT 或 App ID
- `404 Not Found`：未知端点或工具
- `422 Unprocessable Entity`：验证失败
- `429 Too Many Requests`：重复请求或限流保护
- `500 Internal Server Error`：意外的服务器错误
- `502 Bad Gateway`：加载或保存 Tiptap Cloud 文档失败

### 流式传输和会话错误

[`POST /v3/ai/toolkit/stream-tool`](#stream-a-tool) 通过实时
连接在 Tiptap Cloud 文档上运行：它会实时加入该文档，因此 AI 会与其他协作者一起编辑最新内容。建立或使用该连接时发生的错误会以内联方式作为响应流中的 `error` 事件传递，而不是作为 HTTP 状态码：

```json
{ "type": "error", "code": "concurrent_edit_conflict", "status": 409, "message": "..." }
```

`status` 字段会映射到对应的 HTTP 状态码。可能的 `code` 值：

| `code`                        | `status` | 发生时机                                                       | 处理方式                                                                      |
| ----------------------------- | -------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- |
| `concurrent_edit_conflict`    | 409      | 文档在工具运行期间发生了变化（例如，某个用户编辑了它），因此无法在过期内容之上应用更改。               | 重新运行请求。AI 会在下一次尝试时读取最新内容。可以安全地自动重试。参见 [处理并发编辑](#handle-concurrent-edits)。 |
| `schema_mismatch`             | 409      | 请求中的编辑器 schema 与该文档当前使用的 schema 不匹配，或者存储的文档无法用该 schema 解析。 | 为同一文档发送一致的 `editorContext` schema。不要用相同的 schema 重试。                       |
| `websocket_auth_failed`       | 401      | 打开连接时，Tiptap Cloud 拒绝了文档凭据。                                | 刷新 Document Server JWT 声明，然后重试。不要使用相同的 token 重试。                          |
| `websocket_connection_failed` | 502      | 与 Tiptap Cloud 的连接在初始同步完成前就已关闭。                            | 使用退避策略重试。检查连通性和 Tiptap Cloud 状态。                                          |
| `websocket_sync_timeout`      | 504      | 文档在时限内没有完成初始同步。                                            | 使用退避策略重试。大文档和网络连接退化会让这种情况更容易发生。                                           |
| `session_limit_reached`       | 503      | 服务器正在处理的并发文档会话数量已达到上限。                                     | 使用退避策略重试。会话在进入空闲时会被释放。                                                    |
| `session_creation_cancelled`  | 503      | 会话在完成连接之前就被拆除，通常发生在服务器重启期间。                                | 重试。                                                                       |

> **仅适用于 Tiptap Cloud 文档:**
>
> 这些错误只会出现在 `stream-tool` 使用的实时连接路径中。发送内联 `document` 的请求不会打开连接，因此不会返回会话或 WebSocket 错误。

### 处理并发编辑

`concurrent_edit_conflict` 在协作文档中是预期内的。AI 读取文档、
调用模型并写回更改的同时，用户可能会在中间编辑同一个文档。与其
覆盖该编辑，工具包会拒绝此次写入，以免丢失任何工作。

把它当作一个安全、可重试的信号：当你收到一个 `code: "concurrent_edit_conflict"` 的 `error` 事件时，再次运行相同的工具调用。工具包会重新读取文档，
因此 AI 会基于用户的最新更改继续工作。请限制重试次数，以避免在一个被频繁编辑的
文档上陷入长循环。

```ts
// `runStream` 发送 start/delta/end 消息，并解析为流的
// 最终 `error` 事件；如果流成功完成，则返回 `null`。
async function streamToolWithRetry(body: unknown, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const error = await runStream(body)

    if (!error) {
      return // 成功完成
    }
    if (error.code !== 'concurrent_edit_conflict') {
      throw new Error(`stream-tool failed: ${error.code}`)
    }
    // 文档在传输过程中发生了变化——使用最新内容重试。
  }

  throw new Error('工具调用因并发编辑而持续冲突。')
}
```

## 可用工具

以下是可用工具列表。

### `tiptapRead`

读取一部分顶层文档节点。**它也会编辑文档**，以便为高效编辑做准备。

#### 工具配置（`toolConfig`）

`null`

#### 工具输入（`toolInput`）

- `from` (`number`): 要读取的第一个顶层节点的零基索引。

#### 工具输出（`toolOutput`）

成功响应：

- `success` (`true`): 表示读取请求成功。
- `totalNodeCount` (`number`): 文档中顶层节点总数。
- `nodeRange` (`[number, number]`): 读取的顶层节点范围。
- `content` (`JSONContent[] | string`): 返回范围内的文档内容。当 `format` 为
  `json` 时，这是一个 Tiptap JSON 片段。当 `format` 为 `shorthand`
  时，这是一个 Tiptap Shorthand 字符串。

错误响应：

- `success` (`false`): 表示读取请求失败。
- `error` (`string`): 错误信息。
- `totalNodeCount?` (`number`): 顶层节点总数。

#### 工具结果（`toolResult`）

`null`

### `tiptapEdit`

通过替换目标、在目标之前插入或在目标之后插入来编辑文档节点。\
目标是来自 `tiptapRead` 的节点哈希，或者针对整个文档使用 `"doc"`。

#### 工具配置（`toolConfig`）

`null`

#### 工具输入（`toolInput`）

- `operations` (`array`): 按顺序应用的编辑操作。操作格式在工具定义中有说明。如果你是客户，请联系我们以获取有关操作格式的更多信息。

#### 工具输出（`toolOutput`）

成功或部分成功响应：

- `success` (`boolean`): 所有操作是否都成功完成。
- `operationResults` (`array`): 每个操作的结果。
  - `success` (`boolean`): 该操作是否成功完成。
  - `target` (`string`): 该操作所针对元素的字符串标识符。
  - `error` (`string | null`): 失败原因；如果操作成功则为 `null`。

错误响应：

- `success` (`false`): 表示编辑请求失败。
- `reason` (`'validationError' | 'unexpectedError'`): 错误类别。
- `error` (`string`): 错误信息。

#### 工具结果（`toolResult`）

`null`

### `getThreads`

读取持久化的评论线程、其评论以及它们在文档中的位置。

> **需要 Tiptap Cloud 文档:**
>
> 由于线程存储在 Tiptap Document Server 上，此工具要求请求体中包含 `experimental_documentOptions`。请传入一个引用你的 Tiptap Cloud 文档的 `documentId`。

#### 工具配置（`toolConfig`）

`null`

#### 工具输入（`toolInput`）

- `from` (`number`): 要读取的第一个线程的零基索引。

#### 工具输出（`toolOutput`）

成功响应：

- `success` (`true`): 表示读取请求成功。
- `totalThreadCount` (`number`): 文档中的线程总数。
- `threadRange` (`[number, number]`): 读取的线程范围，格式为 `[from, to)`。
- `threads` (`array`): 返回的线程对象。
  - `id` (`string`): 唯一线程标识符。
  - `nodeRange` (`[number, number] | null`): 线程所在的节点范围；如果线程未在文档中被标注，则为 `null`。
  - `content` (`JSONContent[] | string | null`): 线程标记的内容。当 `format` 为
    `json` 时，这是一个 Tiptap JSON 片段。当 `format` 为 `shorthand` 时，这是一个 Tiptap
    Shorthand 字符串。`null` 表示线程未在文档中被标注。
  - `comments` (`array`): 线程中的评论。
    - `id` (`string`): 唯一评论标识符。
    - `content` (`string`): 评论文本。
    - `userId` (`string`): 创建该评论的用户 ID。
    - `createdAt` (`string`): 评论创建时的 ISO 时间戳。
    - `updatedAt` (`string`): 评论最后更新时间的 ISO 时间戳。
  - `resolvedAt?` (`string | null`): 线程被解决时的 ISO 时间戳；如果未解决，则为 `null`。
  - `createdAt` (`string`): 线程创建时的 ISO 时间戳。
  - `updatedAt` (`string`): 线程最后更新时间的 ISO 时间戳。
  - `data?` (`Record<string, unknown>`): 公开的线程元数据。

错误响应：

- `success` (`false`): 表示读取请求失败。
- `error` (`string`): 错误信息。
- `totalThreadCount?` (`number`): 已持久化线程的总数（如果已知）。

#### 工具结果（`toolResult`）

`null`

### `editThreads`

创建、更新、删除、解决或取消解决评论线程和评论。

> **需要 Tiptap Cloud 文档:**
>
> 由于线程存储在 Tiptap Document Server 上，此工具要求请求体中包含 `experimental_documentOptions`。请传入一个引用你的 Tiptap Cloud 文档的 `documentId`。

#### 工具配置（`toolConfig`）

`null`

要为新的 AI 生成线程或评论附加元数据，请在 `execute-tool` 请求中传入 `experimental_commentsOptions`。

#### 工具输入（`toolInput`）

- `operations` (`array`): 按顺序应用的线程操作。操作格式在工具定义中有说明。如果你是客户，请联系我们以获取有关操作格式的更多信息。

#### 工具输出（`toolOutput`）

成功或部分成功响应：

- `success` (`boolean`): 表示所有操作是否都成功完成。
- `operations` (`array`): 每个操作的结果。
  - `type` (`string`): 已执行的操作类型。
  - `success` (`boolean`): 该操作是否成功完成。
  - `message` (`string`): 人类可读的操作结果。
  - `threadId?` (`string`): 创建或引用线程的操作所对应的线程 ID。

错误响应：

- `success` (`false`): 表示在处理操作之前请求就已失败。
- `error` (`string`): 错误信息。

#### 工具结果（`toolResult`）

`null`

### `readDocument`

读取整个文档的内容。

#### 工具配置（`toolConfig`）

`null`

#### 工具输入（`toolInput`）

`{}`

#### 工具输出（`toolOutput`）

成功响应：

- `success` (`true`): 表示文档读取成功。
- `content` (`JSONContent[] | string`): 整个有效文档内容。当 `format` 为 `json` 时，
  这是一个 Tiptap JSON 片段。当 `format` 为 `shorthand` 时，这是一个 Tiptap Shorthand 字符串。

> **返回整个文档:**
>
> 该工具输出包含整个文档的内容，这可能会超出上下文窗口。为避免这种情况，你必须自行管理上下文窗口。

#### 工具结果（`toolResult`）

与 `toolOutput` 结构相同。

### `proofreader`

对文档进行小幅编辑。针对 AI 只进行一两个词的小编辑场景进行了优化。例如，对文档进行校对或检查拼写错误。

此工具仅支持 `format: "shorthand"`。

#### 工具配置（`toolConfig`）

`null`

#### 工具输入（`toolInput`）

- `operations` (`array`): 按顺序应用的校对操作。操作格式在工具定义中有说明。如果你是客户，请联系我们以获取有关操作格式的更多信息。

#### 工具输出（`toolOutput`）

成功或部分成功响应：

- `success` (`boolean`): 表示所有操作是否都成功完成。
- `operationResults` (`array`): 每个操作的结果。
  - `target` (`string`): 该操作所针对元素的字符串标识符。
  - `success` (`boolean`): 该操作是否成功完成。
  - `error` (`string | null`): 失败原因；操作成功时为 `null`。

#### 工具结果（`toolResult`）

`null`

## 相关页面

- [审查选项](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md)
- [编辑器上下文](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/editor-context.md)