Tiptap 中文文档

带评论的跟踪更改

独立产品

Tracked Changes 是一个与 AI Toolkit 分开的独立 Tiptap 产品，需单独购买。它默认处理用户编辑，并且在与 AI Toolkit 集成后也可以审阅 AI 编辑。

实验性

Tracked Changes 扩展目前处于 Alpha 阶段。

延续自 Use with Tracked Changes 指南

本指南是 Use with Tracked Changes guide 的后续内容。请先阅读前者。

你可以要求 AI 为每一处更改提供理由。每条理由都会成为一个与其跟踪更改相关联的评论线程，并使用 Comments 扩展。本指南建立在 Use with Tracked Changes 集成之上，并且需要单独授权的 Tracked Changes 扩展。

查看 GitHub 上的源代码。

API 端点

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

// 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 生成的评论的线程和评论元数据。

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 的理由。

最终效果

查看 GitHub 上的源代码。

后续步骤

PreviouslyWith Tracked Changes