---
title: "带评论的跟踪更改"
description: "将 AI 生成的跟踪更改与解释每处更改的评论线程相结合。"
canonical_url: "https://tiptap.zhcndoc.com/ai/ai-toolkit/client/agents/review-changes/tracked-changes-with-comments"
---

# 带评论的跟踪更改

将 AI 生成的跟踪更改与解释每处更改的评论线程相结合。

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

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

> **从《与 Tracked Changes 一起使用》指南继续:**
>
> 本指南是对 [Use with Tracked Changes
> guide](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/agents/review-changes/tracked-changes.md) 的延续。请先阅读它。

你可以让 AI 为每一处更改提供理由。每条理由都会成为一个评论线程，并通过 [Comments](https://tiptap.zhcndoc.com/comments/getting-started/overview.md) 扩展链接到其对应的跟踪更改。本指南建立在 [Use with Tracked Changes](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/agents/review-changes/tracked-changes.md) 集成之上，并且需要单独授权的 Tracked Changes 扩展。

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

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

## API 端点

在服务端，将 `operationMeta` 选项传递给 `toolDefinitions`，以便为编辑操作添加 `meta` 字段。然后指示 AI 在 `meta` 字段中提供理由。

```ts
// app/api/tracked-changes-comments/route.ts
import { openai } from '@ai-sdk/openai'
import { toolDefinitions } from '@tiptap-pro/ai-toolkit-ai-sdk'
import { createAgentUIStreamResponse, ToolLoopAgent, type UIMessage } from 'ai'

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json()

  const agent = new ToolLoopAgent({
    model: openai('gpt-5.4-mini'),
    instructions: `你是一个可以编辑富文本文档的助手。
规则：先使用 tiptapRead，再使用 tiptapEdit。
规则：在编辑文档时，始终在 meta 字段中为每项更改提供简要说明。`,
    tools: toolDefinitions({
      operationMeta:
        '简要说明此更改为何能改进文档。',
    }),
  })

  return createAgentUIStreamResponse({
    agent,
    uiMessages: messages,
  })
}
```

## 客户端设置

在客户端，添加 `CommentsKit` 扩展，并将 `commentsOptions` 传递给 `executeTool` 方法。`commentsOptions` 属性用于配置 AI 生成的评论的线程和评论元数据。

```tsx
import { AiToolkit, getAiToolkit } from '@tiptap-pro/client-ai-toolkit'
import { CommentsKit } from '@tiptap-pro/extension-comments'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'

const editor = useEditor({
  extensions: [
    StarterKit,
    TrackedChanges.configure({ enabled: false }),
    AiToolkit,
    CommentsKit.configure({
      provider, // 你的 TiptapCollabProvider 实例
    }),
  ],
})

// 在 onToolCall 内部：
const result = toolkit.executeTool({
  toolName: toolCall.toolName,
  input: toolCall.input,
  reviewOptions: {
    mode: 'trackedChanges',
    trackedChangesOptions: {
      userId: 'ai-assistant',
      userMetadata: { name: 'AI' },
    },
  },
  commentsOptions: {
    threadData: { userName: 'AI' },
    commentData: { userName: 'AI' },
  },
})
```

编辑操作中每个非空的 `meta` 字段都会变成一个与其跟踪更改相关联的评论线程。用户可以审核更改，并在评论侧边栏中阅读 AI 的理由。

## 最终效果

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

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

## 后续步骤

- 在 API 参考中了解有关 [review options](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/api-reference/review-options.md) 的更多信息。
- 使用 [streaming guide](https://tiptap.zhcndoc.com/ai/ai-toolkit/client/agents/streaming.md) 添加实时流式传输。
- 了解用于样式和配置选项的 [Tracked Changes](https://tiptap.zhcndoc.com/tracked-changes/getting-started/overview.md) 扩展。
- 了解用于评论配置和样式的 [Comments](https://tiptap.zhcndoc.com/comments/getting-started/overview.md) 扩展。