Tiptap 中文文档

执行工具（AI 代理）

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

一旦你为 AI 代理添加了 工具定义，AI 代理就会生成工具调用。使用 executeTool 方法将工具调用应用到编辑器。

executeTool

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

参数

  • toolName (string): 要执行的工具。可以是可用工具之一。
  • 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 编辑钩子指南。
    • beforeOperation? ((context: BeforeOperationContext) => BeforeOperationResult): 在每次操作应用前调用。返回 { action: 'accept' } 以应用该操作（可选传入 fragment 或 operationType 覆盖），或 { action: 'reject', error } 跳过该操作。

返回值 (ExecuteToolResult)

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

示例 

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

For a complete hands-on tutorial, see the AI agent chatbot guide.

streamTool

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

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

参数

  • toolCallId (unknown): 工具调用的 ID
  • toolName (string): 要执行的工具。可以是可用工具之一。
  • 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 编辑钩子指南。
    • 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，表示流式传输已结束。

// 在工具调用生成时进行流式传输。
// 每次接收到新的流式内容时调用 `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.

getActiveSelection

返回 activeSelection 变量的值。

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

返回值

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

示例 

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

setActiveSelection

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

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

参数

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

示例 

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

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

// 清除活动选择
toolkit.setActiveSelection(null)
Previously编辑文档