Tiptap 中文文档

选择感知

在决定如何编辑文档之前，构建一个读取当前选区的服务端 AI 代理。

查看 GitHub 上的源代码。

AI 代理聊天指南的延续

本指南延续自 AI 代理聊天指南。请先阅读它。

1. 跟踪活动选区

添加 Selection 扩展，并在选区发生变化时存储当前范围。

import { Selection } from '@tiptap/extensions'
import { EditorContent, useEditor } from '@tiptap/react'
import { ServerAiToolkit } from '@tiptap-pro/server-ai-toolkit'
import { useRef } from 'react'

const selectionRangeRef = useRef({ from: 0, to: 0 })

const editor = useEditor({
  immediatelyRender: false,
  extensions: [StarterKit, Collaboration.configure({ document: doc }), ServerAiToolkit, Selection],
  onSelectionUpdate: ({ editor: currentEditor }) => {
    selectionRangeRef.current = {
      from: currentEditor.state.selection.from,
      to: currentEditor.state.selection.to,
    }
  },
})

2. 在用户消息中发送选区

当用户发送消息时，在请求体中包含架构感知数据、文档 ID 以及已捕获的选区范围。

const { messages, sendMessage, status } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/server-selection-awareness',
  }),
})

sendMessage(
  { text: input },
  {
    body: {
      schemaAwarenessData: getSchemaAwarenessData(editor),
      documentId,
      selectionRange: selectionRangeRef.current,
    },
  },
)

3. 从 AI 服务器读取选区

在后端路由中，代理开始它的工具循环之前，先调用 Server AI Toolkit 的 selection-read 端点：

  • POST /v3/ai/toolkit/read/read-selection
import { getAuthHeaders } from '@/lib/server-ai-toolkit/get-auth-headers'

const response = await fetch(`${apiBaseUrl}/toolkit/read/read-selection`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    schemaAwarenessData,
    range: selectionRange,
    sessionId,
    reviewOptions: {
      mode: 'disabled',
    },
    format: 'json',
    experimental_documentOptions: {
      documentId,
      userId: 'ai-assistant',
    },
  }),
})

const selectionResult = await response.json()

const selectionPrompt = !selectionResult.output.isEmpty
  ? selectionResult.output.prompt
  : '当前没有活动选区。'

返回的 prompt 包含对已选内容的面向模型的描述，以及它在文档中的位置。

4. 将选区上下文注入到代理指令中

将选区 prompt 注入到代理指令中，让模型知道它应该关注文档的哪一部分。

const agent = new ToolLoopAgent({
  model,
  instructions: `你是一名能够编辑富文本文档的助手。
在进行更改之前使用选区上下文。

<selection-context>
${selectionPrompt}
</selection-context>

${schemaAwarenessPrompt}`,
  tools,
})

随后，代理可以使用常规的 Server AI Toolkit 工具来读取更多上下文并编辑文档，同时始终保持对当前活动选区的约束。

推荐的模型和推理能力配置

/v3/ai/toolkit/read/read-selection 端点会向 AI 说明被选中的内容，但它并不会强制 AI 只编辑该选区。因此，AI 模型可能会编辑相邻段落，而不只是选中的内容。

在我们的测试中，我们发现启用了推理的模型（例如将推理强度设为 low 的 gpt-5.4-mini）在被明确要求时，能更好地将编辑范围限制在选区内。

另一个选择是改为实现 插入内容工作流。该工作流可以用来限制可编辑区域，因此 AI 可以严格只重写选区。

最终效果

最终得到的是一种服务端 AI 聊天体验：只重写用户选中的内容：

查看 GitHub 上的源代码。

下一步

Previously评论