---
title: "带评论的跟踪更改"
description: "将 AI 生成的跟踪更改与解释每次更改的评论线程结合起来。"
canonical_url: "https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/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 阶段。

> **延续自 Use with Tracked Changes 指南:**
>
> 本指南是 [Use with Tracked Changes
> guide](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/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/content-ai/capabilities/ai-toolkit/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: `You are an assistant that can edit rich text documents.
Rule: Use tiptapRead before tiptapEdit.
Rule: When editing the document, ALWAYS provide a brief justification for each change in the meta field.`,
    tools: toolDefinitions({
      operationMeta:
        '简要说明此更改为何能改进文档。',
    }),
  })

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

## 客户端设置

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

```tsx
import { AiToolkit, getAiToolkit } from '@tiptap-pro/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/content-ai/capabilities/ai-toolkit/api-reference/review-options.md) 的内容。
- 使用 [流式传输指南](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/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) 扩展。