---
title: "与修订模式一起使用"
description: "将服务器端 AI 编辑显示为修订内容，用户可以逐条接受或拒绝。"
canonical_url: "https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/agents/tracked-changes"
---

# 与修订模式一起使用

将服务器端 AI 编辑显示为修订内容，用户可以逐条接受或拒绝。

将服务器端 AI 编辑显示为追踪变更，以便用户可以逐个审查并接受或拒绝它们。这会将 Server AI Toolkit 与 [Tracked Changes](https://tiptap.zhcndoc.com/tracked-changes/getting-started/overview.md) 扩展集成在一起。

> **独立产品:**
>
> [Tracked Changes](https://tiptap.zhcndoc.com/tracked-changes/getting-started/overview.md) 是与 Server AI Toolkit
> 分开的独立 Tiptap 产品，需单独购买。它默认处理用户编辑，在与 Server AI Toolkit 集成后也可以审查 AI 编辑。

> **Interactive demo:** [server ai tracked changes](https://ai-toolkit-demos.vercel.app/server-ai-tracked-changes)

请参阅 [GitHub 上的源代码](https://github.com/ueberdosis/ai-toolkit-demos)。

> **实验性功能:**
>
> [Tracked Changes](https://tiptap.zhcndoc.com/tracked-changes/getting-started/overview.md) 扩展目前处于 Alpha
> 阶段。

> **AI agent chatbot 指南的后续内容:**
>
> 本指南接续 [AI agent chatbot
> 指南](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/agents/ai-agent-chatbot.md)。请先阅读它。

## 工作原理

1. AI 使用 `trackedChanges` 模式下的 `tiptapRead` 读取文档。
2. AI 使用 `trackedChanges` 模式下的 `tiptapEdit` 编辑文档。
3. Server AI Toolkit 通过 Tracked Changes 扩展写入追踪变更标记，而不是直接修改文档。
4. 客户端使用 Tracked Changes 扩展显示追踪变更，并允许用户接受或拒绝它们。

## 显示追踪变更

要将服务端 AI 编辑显示为追踪变更，请在 `POST /v4/ai/toolkit/execute-tool` 端点上配置 `reviewOptions` 参数。在调用 `tiptapRead` 和 `tiptapEdit` 工具时，将审阅模式设置为 `{ mode: 'trackedChanges' }`。有关所有可用设置，请参阅 [review options 参考](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md)。

### 使用追踪变更执行工具

在调用 `execute-tool` 时传入 `reviewOptions`：

`getAuthHeaders` 辅助函数会签名一个 JWT，因此在将 headers 传递给 `fetch` 时请保留 `await`。

```ts
import { getAuthHeaders } from '@/lib/server-ai-toolkit/get-auth-headers'

const result = await fetch(`${apiBaseUrl}/v4/ai/toolkit/execute-tool`, {
  method: 'POST',
  headers: await getAuthHeaders('your-document-id'),
  body: JSON.stringify({
    editorContext,
    document: {
      type: 'cloud',
      id: 'your-document-id',
    },
    user: 'ai-assistant',
    tool: {
      name: 'tiptapEdit',
      input: toolCallInput,
    },
    reviewOptions: {
      mode: 'trackedChanges',
      trackedChangesOptions: {
        userId: 'ai-assistant',
        userMetadata: {
          name: 'AI Assistant',
        },
      },
    },
  }),
})
```

请参阅 [review options 参考文档](https://github.com/ueberdosis/ai-toolkit-demos) 以获取完整的 `reviewOptions` 形状，包括 `trackedChangesOptions` 和 `diffUtilityOptions`。

### 客户端设置

在客户端，安装并添加 `ServerAiToolkit` 和 `TrackedChanges` 扩展。

```tsx
import { useChat } from '@ai-sdk/react'
import { Collaboration } from '@tiptap/extension-collaboration'
import { EditorContent, useEditor } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { TrackedChanges, findSuggestions } from '@tiptap-pro/extension-tracked-changes'
import { TiptapCollabProvider } from '@tiptap-pro/provider'
import { ServerAiToolkit, getEditorContext } from '@tiptap/server-ai-toolkit'

export default function Page() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [
      StarterKit.configure({ undoRedo: false }),
      Collaboration.configure({ document: doc }),
      TrackedChanges.configure({ enabled: false }),
      ServerAiToolkit,
    ],
  })

  // ... 渲染编辑器和聊天界面
}
```

在 AI 编辑文档后，更改将显示为追踪变更。用户可以使用追踪变更扩展提供的 `acceptSuggestion`、`rejectSuggestion`、`acceptAllSuggestions` 和 `rejectAllSuggestions` 命令来接受或拒绝它们。

> **Interactive demo:** [server ai tracked changes](https://ai-toolkit-demos.vercel.app/server-ai-tracked-changes)

请参阅 [GitHub 上的源代码](https://github.com/ueberdosis/ai-toolkit-demos)。

## 使用追踪变更添加评论

> **Interactive demo:** [server ai tracked changes](https://ai-toolkit-demos.vercel.app/server-ai-tracked-changes)

请参阅 [GitHub 上的源代码](https://github.com/ueberdosis/ai-toolkit-demos)。

可以让 AI 为每个变更提供理由。每个理由都会成为一个评论线程，并与对应的追踪变更关联，使用 [Comments](https://tiptap.zhcndoc.com/comments/getting-started/overview.md) 扩展。

### API 端点

在获取工具定义时，配置 `tiptapEdit` 工具，使其能够在操作中包含 `meta` 字段。`meta` 值是添加到每个编辑操作工具 schema 中的一条指令。AI 在创建编辑时会填写该字段，Server AI Toolkit 会将每个非空的 `meta` 值作为追踪变更的理由评论。

```ts
const response = await fetch(`${apiBaseUrl}/v4/ai/toolkit/fetch-tools`, {
  method: 'POST',
  headers: await getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
    tools: {
      tiptapEdit: {
        meta: '简要说明为什么此更改能改进文档。',
      },
    },
  }),
})
```

### 使用评论执行工具

调用 `execute-tool` 时传入 `reviewOptions`：

```ts
const result = await fetch(`${apiBaseUrl}/v4/ai/toolkit/execute-tool`, {
  method: 'POST',
  headers: await getAuthHeaders('your-document-id'),
  body: JSON.stringify({
    editorContext,
    document: {
      type: 'cloud',
      id: 'your-document-id',
    },
    user: 'ai-assistant',
    tool: {
      name: 'tiptapEdit',
      input: toolCallInput,
    },
    reviewOptions: {
      mode: 'trackedChanges',
      trackedChangesOptions: {
        userId: 'ai-assistant',
        userMetadata: {
          name: 'AI Assistant',
        },
      },
    },
  }),
})
```

每个非空的 `meta` 字段都会成为一个与对应追踪变更关联的评论线程。理由将存储为线程的第一个评论内容，并作为线程数据中的 `suggestionReason`。

### 客户端设置

在客户端，添加带有 `TiptapCollabProvider` 的 `CommentsKit` 扩展：

```tsx
import { CommentsKit } from '@tiptap-pro/extension-comments'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'
import { ServerAiToolkit } from '@tiptap/server-ai-toolkit'

const editor = useEditor({
  extensions: [
    StarterKit.configure({ undoRedo: false }),
    Collaboration.configure({ document: doc }),
    TrackedChanges.configure({ enabled: false }),
    ServerAiToolkit,
    CommentsKit.configure({
      provider, // 你的 TiptapCollabProvider 实例
    }),
  ],
})
```

用户可以在追踪变更侧边栏中查看追踪变更并阅读 AI 的理由。

> **Interactive demo:** [server ai tracked changes](https://ai-toolkit-demos.vercel.app/server-ai-tracked-changes)

请参阅 [GitHub 上的源代码](https://github.com/ueberdosis/ai-toolkit-demos)。

## 下一步

- 了解更多关于 [审阅选项](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md)
- 探索 [REST API 参考](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api.md)
- 了解更多关于 [跟踪更改](https://tiptap.zhcndoc.com/tracked-changes/getting-started/overview.md) 扩展