---
title: "执行工具（AI 代理）"
description: "使用 AI 工具包对 Tiptap 编辑器执行 AI 代理的工具调用。"
canonical_url: "https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/execute-tool"
---

# 执行工具（AI 代理）

使用 AI 工具包对 Tiptap 编辑器执行 AI 代理的工具调用。

使用 `executeTool` 将 AI 代理的工具调用应用到编辑器。

一旦你为 AI 代理添加了 [工具定义](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/tools.md)，AI 代理就会生成工具调用。使用 `executeTool` 方法将工具调用应用到编辑器。

## `executeTool`

通过名称和输入执行支持的工具。

### 参数

- `toolName` (`string`): 要执行的工具。可以是[可用工具](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/agents/tools.md)之一。
- `input` (`unknown`): 符合工具参数输入 schema 的 JSON 对象。如果该工具不需要参数，请传递一个空对象（`{}`）。
- `chunkSize?` (`number`): 传递给 AI 模型的输入字符串的最大长度。防止 AI 一次性读取过多内容，超过模型的上下文窗口。默认值：`32000`。该参数由读取工具使用，用于控制文档如何拆分成块。
- `tiptapEditSelectableNodes?` (`string[]`): 应始终带有哈希的节点类型名称数组，即使它们不是顶层节点。默认情况下，所有块节点类型都可以有哈希。如果设置为 `[]`，则只有顶层节点会有哈希。
- `reviewOptions?` (`ReviewOptions`): 控制预览/审核行为
  - `mode?` (`'disabled' | 'review' | 'preview'`): 是否在应用更改之前或之后进行审核。`'disabled'` 表示不审核，`'review'` 表示在应用后审核，`'preview'` 表示在应用前预览。默认值：`'disabled'`
  - `diffMode?` (`'detailed' | 'full'`): 启用审核模式时如何显示原始内容和修改内容之间的差异。`'detailed'` 比较变更前后的文档，并以丰富差异方式显示删除和新增内容。`'full'` 以整块形式显示删除和新增内容，作为包含删除及新增内容的单个变更。默认值：`'detailed'`
  - `displayOptions?` (`DisplayOptions<{ suggestion: Suggestion }>`): 自定义建议的显示方式
    - `showAsDiff?` (`boolean`): 是否以差异形式显示建议，插入内容和原始内容并列显示。默认值：`true`
    - `diffPosition?` (`'before' | 'after'`): 差异相对于建议的位置。默认值：`'before'`
    - `attributes?` (`Record<string, any>`): 额外的 HTML 属性，将添加到建议上
    - `renderDecorations?` (`RenderDecorations<{ suggestion: Suggestion }>`): 用于将建议渲染为 ProseMirror 装饰的函数
  - `metadata?` (`Record<string, any>`): 用于存储建议额外信息的元数据（如来源或类别）。该数据不会被扩展内部使用，但有助于开发者自定义 UI 中建议的显示。
  - `diffUtilityConfig?` (`DiffUtilityConfig`): 使用差异工具比较文档的选项
    - `simplifyChanges?` (`boolean`): 是否简化变更。如果为 `true`，例如同一单词内的两个变更会合并为单个变更。仅在模式为 'detailed' 或 'smartInline' 时有效。默认值：`true`
    - `ignoreAttributes?` (`string[]`): 忽略的属性。默认值：`['id', 'data-thread-id']`
    - `ignoreMarks?` (`string[]`): 忽略的标记。默认值：`['inlineThread']`
    - `changeMergeDistance?` (`number | null`): 合并变更的最大距离（以文档位置计）。如果两个相邻变更在 rangeA 或 rangeB 的距离小于等于该值，则合并为单个变更。设置为 `null` 或 `undefined` 以禁用合并。仅在模式为 'detailed' 时有效。默认值：`null`
    - `mode?` (`'detailed' | 'block' | 'smartInline' | 'smartInlineV2'`): 用于比较的差异模式。`'detailed'` 执行字符级差异，精确识别文本变化（默认）。`'block'` 执行块级差异，将每个顶层节点视为单元。块模式适合仅需知道段落、标题或其他块级元素是否变化，不关心字符变化。块模式下忽略 `simplifyChanges` 和 `changeMergeDistance` 设置。`'smartInline'` 结合两者：先识别变更块，再对这些块内进行内联差异。适合部分内容发生变化的文档，且同时提供字符级精度。`'smartInlineV2'` 改善了 `'smartInline'`，能正确显示表格等块元素内的变更。默认值：`'detailed'`
- `commentsOptions?` (`CommentsOptions`): 评论和线程操作的选项。允许传递自定义数据给评论和线程的创建/更新操作。`data` 属性用于线程数据，`commentData` 用于评论数据。
  - `threadData?` (`Record<string, any>`): AI 生成的线程（通过 `editThreads` 工具创建）的额外元数据
  - `commentData?` (`Record<string, any>`): AI 生成的评论（通过 `editThreads` 工具创建）的额外元数据
- `tiptapEditHooks?` (`TiptapEditHooks`): 拦截和修改 Tiptap 编辑操作的钩子。详情参见 [Tiptap 编辑钩子指南](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/advanced-guides/tiptap-edit-hooks.md)。
  - `beforeOperation?` (`(context: BeforeOperationContext) => BeforeOperationResult`): 在每次操作应用前调用。返回 `{ action: 'accept' }` 以应用该操作（可选传入 `fragment` 或 `operationType` 覆盖），或 `{ action: 'reject', error }` 跳过该操作。

### 返回值 (`ExecuteToolResult`)

- `output` (`string`): 工具执行的响应消息，供 AI 代理读取。
- `hasError` (`boolean`): 执行期间是否发生错误
- `unknownTool` (`boolean`): `toolName` 是否未被 AI 工具包识别
- `docChanged` (`boolean`): 工具调用是否修改了文档。

### 示例

```ts
// 处理 tiptapRead 工具调用
const result = toolkit.executeTool({
  toolName: 'tiptapRead',
  input: {
    from: 0,
  },
})
```

For a complete hands-on tutorial, see the [AI agent chatbot guide](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/agents/ai-agent-chatbot.md).

## `streamTool`

实时更新文档，工具调用流式传输时生效。

此方法的效果等同于调用 `executeTool`，但它在工具调用流传输时逐步编辑文档，而不是等待流完成后一次性编辑文档。

### 参数

- `toolCallId` (`unknown`): 工具调用的 ID
- `toolName` (`string`): 要执行的工具。可以是[可用工具](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/agents/tools.md)之一。
- `input` (`unknown`): 符合工具参数输入 schema 的 JSON 对象。如果该工具不需要参数，请传递一个空对象（`{}`）。如果工具尚未完成流式传输，该参数应是包含部分参数的部分对象，但仍是有效的 JSON 对象。
- `hasFinished?` (`boolean`): 工具是否已完成流式传输。默认值：`false`
- `chunkSize?` (`number`): 传递给 AI 模型的输入字符串的最大长度。防止 AI 一次性读取过多内容，超过模型的上下文窗口。默认值：`32000`。该参数由读取工具使用，用于控制文档如何拆分成块。
- `tiptapEditSelectableNodes?` (`string[]`): 应始终带有哈希的节点类型名称数组，即使它们不是顶层节点。默认情况下，所有块节点类型都可以有哈希。如果设置为 `[]`，则只有顶层节点会有哈希。
- `reviewOptions?` (`ReviewOptions`): 控制预览/审核行为
  - `mode?` (`'disabled' | 'review' | 'preview'`): 是否在应用更改之前或之后进行审核。`'disabled'` 表示不审核，`'review'` 表示在应用后审核，`'preview'` 表示在应用前预览。默认值：`'disabled'`
  - `diffMode?` (`'detailed' | 'full'`): 启用审核模式时如何显示原始内容和修改内容之间的差异。`'detailed'` 比较变更前后的文档，并以丰富差异方式显示删除和新增内容。`'full'` 以整块形式显示删除和新增内容，作为包含删除及新增内容的单个变更。默认值：`'detailed'`
  - `displayOptions?` (`DisplayOptions<{ suggestion: Suggestion }>`): 自定义建议的显示方式
    - `showAsDiff?` (`boolean`): 是否以差异形式显示建议，插入内容和原始内容并列显示。默认值：`true`
    - `diffPosition?` (`'before' | 'after'`): 差异相对于建议的位置。默认值：`'before'`
    - `attributes?` (`Record<string, any>`): 额外的 HTML 属性，将添加到建议上
    - `renderDecorations?` (`RenderDecorations<{ suggestion: Suggestion }>`): 用于将建议渲染为 ProseMirror 装饰的函数
  - `metadata?` (`Record<string, any>`): 用于存储建议额外信息的元数据（如来源或类别）。该数据不会被扩展内部使用，但有助于开发者自定义 UI 中建议的显示。
  - `diffUtilityConfig?` (`DiffUtilityConfig`): 使用差异工具比较文档的选项
    - `simplifyChanges?` (`boolean`): 是否简化变更。如果为 `true`，例如同一单词内的两个变更会合并为单个变更。仅在模式为 'detailed' 或 'smartInline' 时有效。默认值：`true`
    - `ignoreAttributes?` (`string[]`): 忽略的属性。默认值：`['id', 'data-thread-id']`
    - `ignoreMarks?` (`string[]`): 忽略的标记。默认值：`['inlineThread']`
    - `changeMergeDistance?` (`number | null`): 合并变更的最大距离（以文档位置计）。如果两个相邻变更在 rangeA 或 rangeB 的距离小于等于该值，则合并为单个变更。设置为 `null` 或 `undefined` 以禁用合并。仅在模式为 'detailed' 时有效。默认值：`null`
    - `mode?` (`'detailed' | 'block' | 'smartInline' | 'smartInlineV2'`): 用于比较的差异模式。`'detailed'` 执行字符级差异，精确识别文本变化（默认）。`'block'` 执行块级差异，将每个顶层节点视为单元。块模式适合仅需知道段落、标题或其他块级元素是否变化，不关心字符变化。块模式下忽略 `simplifyChanges` 和 `changeMergeDistance` 设置。`'smartInline'` 结合两者：先识别变更块，再对这些块内进行内联差异。适合部分内容发生变化的文档，且同时提供字符级精度。默认值：`'detailed'`
- `commentsOptions?` (`CommentsOptions`): 评论和线程操作的选项。允许传递自定义数据给评论和线程的创建/更新操作。`data` 属性用于线程数据，`commentData` 用于评论数据。
  - `threadData?` (`Record<string, any>`): AI 生成的线程（通过 `editThreads` 工具创建）的额外元数据
  - `commentData?` (`Record<string, any>`): AI 生成的评论（通过 `editThreads` 工具创建）的额外元数据
- `tiptapEditHooks?` (`TiptapEditHooks`): 拦截和修改 Tiptap 编辑操作的钩子。详情参见 [Tiptap 编辑钩子指南](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/advanced-guides/tiptap-edit-hooks.md)。
  - `beforeOperation?` (`(context: BeforeOperationContext) => BeforeOperationResult`): 在每次操作应用前调用。返回 `{ action: 'accept' }` 以应用该操作（可选传入 `fragment` 或 `operationType` 覆盖），或 `{ action: 'reject', error }` 跳过该操作。

### 返回值 (`StreamToolResult`)

- `output` (`string`): 工具执行的响应消息，供 AI 代理读取。
- `hasError` (`boolean`): 执行期间是否发生错误
- `unknownTool` (`boolean`): `toolName` 是否未被 AI 工具包识别
- `docChanged` (`boolean`): 工具调用是否修改了文档。

### 示例

`streamTool` 方法在工具调用流式传输过程中被反复调用。当工具调用完成流式传输后，再次调用 `streamTool` 方法并设置 `hasFinished: true`，表示流式传输已结束。

```ts
// 在工具调用生成时进行流式传输。
// 每次接收到新的流式内容时调用 `streamTool`
const result = toolkit.streamTool({
  // 工具仍在流式传输，尚未完成
  hasFinished: false,
  toolCallId: 'call_123',
  toolName: 'tiptapEdit',
  // 内容仍在流式传输，所以传递部分参数对象
  input,
})

// 当工具调用完成时，再次调用并设置 hasFinished: true
const finalResult = toolkit.streamTool({
  // 工具流传输已完成
  hasFinished: true,
  toolCallId: 'call_123',
  toolName: 'tiptapEdit',
  // 流传输已完成，可以传递完整参数对象
  input,
})
```

For a complete hands-on tutorial on streaming, see the [streaming guide](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/agents/streaming.md).

## `getActiveSelection`

返回 `activeSelection` 变量的值。

活动选择是由 AI 工具包设置的范围。设置后，该范围将在诸如 `readSelection` 等操作中代替当前编辑器选择。该范围会通过事务自动映射，以在文档变化时保持位置准确。

### 返回值

- `Range | null`: 活动选择范围，具有 `from` 和 `to` 属性，或当无活动选择时返回 `null`。

### 示例

```ts
const toolkit = getAiToolkit(editor)
const activeSelection = toolkit.getActiveSelection()
```

## `setActiveSelection`

设置 `activeSelection` 变量。该变量用于执行带有 `executeTool` 或 `streamTool` 方法的工具调用时，确定 AI 将在诸如 `readSelection` 等操作中使用的选择范围，代替当前编辑器选择。

活动选择是 AI 应当使用以代替当前编辑器选择的范围。该范围会通过事务自动映射，以在文档变化时保持位置准确。

### 参数

- `selection` (`Range | null`): 要设置的范围，具有 `from` 和 `to` 属性，表示起始和结束位置，或使用 `null` 以清除活动选择。

### 示例

```ts
const toolkit = getAiToolkit(editor)
// 将活动选择设置为当前选择
toolkit.setActiveSelection(editor.state.selection)

// 将活动选择设置为特定范围
toolkit.setActiveSelection({ from: 10, to: 50 })

// 清除活动选择
toolkit.setActiveSelection(null)
```