与修订模式一起使用

将服务器端 AI 编辑显示为追踪变更，以便用户可以逐个审查并接受或拒绝它们。这会将 Server AI Toolkit 与 Tracked Changes 扩展集成在一起。

独立产品

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

请参阅 GitHub 上的源代码。

实验性功能

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

AI agent chatbot 指南的后续内容

本指南接续 AI agent chatbot 指南。请先阅读它。

工作原理

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

显示追踪变更

要将服务端 AI 编辑显示为追踪变更，请在 POST /v4/ai/toolkit/execute-tool 端点上配置 reviewOptions 参数。在调用 tiptapRead 和 tiptapEdit 工具时，将审阅模式设置为 { mode: 'trackedChanges' }。有关所有可用设置，请参阅 review options 参考。

使用追踪变更执行工具

在调用 execute-tool 时传入 reviewOptions：

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

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 参考文档以获取完整的 reviewOptions 形状，包括 trackedChangesOptions 和 diffUtilityOptions。

客户端设置

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

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 命令来接受或拒绝它们。

请参阅 GitHub 上的源代码。

使用追踪变更添加评论

请参阅 GitHub 上的源代码。

可以让 AI 为每个变更提供理由。每个理由都会成为一个评论线程，并与对应的追踪变更关联，使用 Comments 扩展。

API 端点

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

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：

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 扩展：

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

请参阅 GitHub 上的源代码。

下一步

了解更多关于审阅选项
探索 REST API 参考
了解更多关于跟踪更改扩展

PreviouslyAI 代理聊天机器人

Next up评论