---
title: "选区感知"
description: "让 AI 识别编辑器中选中的内容。"
canonical_url: "https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/agents/selection-awareness"
---

# 选区感知

让 AI 识别编辑器中选中的内容。

- **1. 获取访问权限**

  通过购买付费的 AI 工具包扩展来访问 AI Toolkit 扩展。联系我们的团队。
- **2. 访问私有注册表**

  AI Toolkit 扩展发布在 Tiptap 的私有 npm 注册表中。请按照[设置指南](https://tiptap.zhcndoc.com/guides/pro-extensions.md)进行身份验证以访问 Tiptap 的私有 npm 注册表。
- **3. 安装扩展**

  使用 npm 或你喜欢的包管理器从私有注册表安装该扩展。

配置 AI，以便它可以读取和编辑编辑器中选中的内容。

> **接续 AI 代理聊天机器人指南:**
>
> 本指南是对[AI 代理聊天机器人指南](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/guides/ai-agent-chatbot.md)的延续。请先阅读该指南。

> **Interactive demo:** [selection awareness](https://ai-toolkit-demos.vercel.app/selection-awareness)

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

## `readSelection` 工具

`readSelection` 工具允许 AI 代理读取编辑器中选中的内容。

它默认包含在传递给 AI 模型的工具定义列表中。

```ts
// 服务器端代码
import { toolDefinitions } from '@tiptap-pro/ai-toolkit-ai-sdk'

const definitions = toolDefinitions({
  // 启用 readSelection 工具。
  // readSelection 工具默认已启用。
  readSelection: true,
})
```

然后可以在客户端使用 `executeTool` 方法执行该工具。它不需要任何参数。

```ts
// 客户端代码
const toolkit = getAiToolkit(editor)
const result = await toolkit.executeTool({
  toolName: 'readSelection',
})
```

工具的输出包含以下信息：

- 选区的内容
- 选区的位置

这些信息让 AI 知道当前选中了什么内容，以及这些内容在文档中的位置，从而便于后续编辑。

如果你的应用不需要读写选区功能，可以通过在工具定义中将 `readSelection` 选项设置为 `false` 来禁用该工具。

```ts
// 服务器端代码
import { toolDefinitions } from '@tiptap-pro/ai-toolkit-ai-sdk'

const definitions = toolDefinitions({
  // 禁用 readSelection 工具。
  readSelection: false,
})
```

## 保持选区一致

有时，在 AI 处理期间，用户更改了编辑器中的选区。这会让 AI 感到困惑：它做出决策完成后，却不知道选区已被更改，从而读取了错误的选区内容。

为避免这种情况，你可以在用户发送消息给 AI 时保存选区，这样即使用户后来更改，选区在 AI 思考时也不会改变。

首先，用户发送消息给 AI 时，调用 `setActiveSelection` 方法传入当前选区。

```ts
const toolkit = getAiToolkit(editor)
// 在 AI 开始工作前调用此方法。
toolkit.setActiveSelection(editor.state.selection)
```

然后，当 AI 结束处理时，调用 `setActiveSelection` 方法传入 `null`，以取消活跃选区。

```ts
toolkit.setActiveSelection(null)
```

你也可以将活跃选区设置为文档中的任意位置。

```ts
toolkit.setActiveSelection({ from: 10, to: 20 })
```

## 推荐的模型与推理力度配置

`readSelection` 工具会告知 AI 选中的内容，但不会强制它只能编辑该选区。因此，AI 模型可能会编辑周围的段落，而不只是选中的内容。

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

另一种方案是改为实现[插入内容工作流](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/workflows/insert-content.md)。此工作流可用于限制可编辑区域，因此 AI 可以严格只重写选区。

## 最终效果

通过添加额外的 CSS 样式，效果是一个简洁而精致的 AI 聊天机器人，能够编辑选中的内容：

> **Interactive demo:** [selection awareness](https://ai-toolkit-demos.vercel.app/selection-awareness)

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

## 后续步骤

- 更多关于 `getActiveSelection` 和 `setActiveSelection` 方法的内容，请参阅[API 参考](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/primitives/execute-tool.md#setactiveselection)。