工作流程

工作流程是 AI 模型执行单一且明确定义任务的场景。AI 工具包包含以下内置工作流程：

以下是支持这些内置工作流程的方法的 API 参考。

`createProofreaderWorkflow`（服务器端工具）

创建一个预设的校对工作流程配置。返回一个系统提示和用于验证 AI 输出的模式。

该工作流程期望用户的输入是一个 JSON 对象，包含：

content: 需要校对的文档内容（详情见客户端设置章节如何获取）
task：描述待完成任务的字符串
context: （可选）与任务相关的额外上下文或背景信息

返回值

systemPrompt（string）：可直接使用的系统提示，指导 AI 模型如何生成校对操作
zodOutputSchema（ZodObject）：用于验证 AI 输出的 Zod 模式
jsonOutputSchema（object）：用于验证 AI 输出的 JSON 模式

systemPrompt 字段包含一个带有合理默认值的示例提示，建议您阅读并根据需求修改。

示例

import { createProofreaderWorkflow } from '@tiptap-pro/ai-toolkit-tool-definitions'
import { Output, streamText } from 'ai'
import { openai } from '@ai-sdk/openai'

// 从 API 端点请求中获取文档内容
const { content } = apiEndpointRequest

// 创建并配置工作流程
const workflow = createProofreaderWorkflow()

const result = streamText({
  model: openai('gpt-5.4-mini'),
  // 系统提示
  system: workflow.systemPrompt,
  // 用户消息，包含内容和任务
  prompt: JSON.stringify({
    content,
    task: '纠正所有语法和拼写错误',
    context: '这是一个正式的商务文件',
  }),
  output: Output.object({ schema: workflow.zodOutputSchema }),
})

`createInsertContentWorkflow`（服务器端工具）

创建一个预设的插入或替换内容工作流程配置。返回用于 AI 模型的系统提示。

该工作流程期望用户的输入为包含以下属性的 JSON 对象：

task：待完成的任务
replace：待替换的 HTML 内容（可选）
before：插入在之前的 HTML 内容（可选）
after：插入在之后的 HTML 内容（可选）

返回值

systemPrompt（string）：可直接使用的系统提示，指导 AI 模型如何生成 HTML 内容

systemPrompt 字段包含一个带有合理默认值的示例提示，建议您阅读并根据需求修改。

示例

import { createInsertContentWorkflow } from '@tiptap-pro/ai-toolkit-tool-definitions'
import { streamText } from 'ai'
import { openai } from '@ai-sdk/openai'

// 从 API 端点请求中获取任务和选区信息
const { task, replace } = apiEndpointRequest

// 创建并配置工作流程
const workflow = createInsertContentWorkflow()

const result = streamText({
  model: openai('gpt-5.4-mini'),
  // 系统提示
  system: workflow.systemPrompt,
  // 用户消息，包含任务和内容对象
  prompt: JSON.stringify({
    task,
    replace,
  }),
})

return result.toTextStreamResponse()

`proofreaderWorkflow`

将一组校对操作应用于文档。

参数

options (ProofreaderWorkflowOptions): 配置选项
- hasFinished (boolean): 是否流式传输已完成。在操作仍在流式传输时传递 false，在最后一次调用时传递 true。
- operations (PartialProofreaderOperation[]): 校对操作数组。
- workflowId (unknown): 此工作流程运行的唯一 ID
- reviewOptions? (ReviewOptions): 控制预览/审查行为。查看可用选项。
  - 在此方法中，diffUtilityOptions.groupInlineChanges 默认为 2 而不是 1，因此编辑默认显示为内联更改。
  - 当安装了修订跟踪扩展时支持 mode: 'trackedChanges'。
- range? (Range): 应用校对操作的范围
  - from (number): 起始位置
  - to (number): 结束位置

返回值（`ProofreaderWorkflowResult`）

doc (Node): 应用操作后修改后的文档
operationResults (OperationResult[]): 操作结果数组，顺序与输入操作相同。每个结果包含：
- target (string): 与操作结果关联的目标哈希
- success (boolean): 操作是否成功
- error (string | null): 如果操作失败则为错误消息，否则为 null

示例

const toolkit = getAiToolkit(editor)

// 获取适合 AI 快速且高效编辑的文档格式
const { content } = toolkit.tiptapRead()

const operations = await callApiEndpoint({ content })

// 应用校对更正
const result = toolkit.proofreaderWorkflow({
  hasFinished: true,
  operations,
  workflowId: 'proofread-123',
  reviewOptions: {
    mode: 'preview',
  },
})

`createTiptapEditWorkflow`（服务器端工具）

创建一个预设的文档编辑工作流程配置。返回系统提示和用于验证 AI 输出的模式。

该工作流程期望用户的输入为 JSON 对象，包含：

content: 待编辑文档的内容（来自 tiptapRead）
task：描述待完成编辑任务的字符串
context: （可选）与任务相关的额外上下文或背景信息

返回值

systemPrompt (string): 可直接使用的系统提示，指导 AI 模型如何生成编辑操作
zodOutputSchema (ZodObject): 用于验证 AI 输出的 Zod 模式。此模式验证模型返回的流式 operations 对象。
jsonOutputSchema (object): 用于验证 AI 输出的 JSON 模式

示例

import { createTiptapEditWorkflow } from '@tiptap-pro/ai-toolkit-tool-definitions'
import { Output, streamText } from 'ai'
import { openai } from '@ai-sdk/openai'

// 从 API 端点请求中获取文档内容和任务
const { content, task } = apiEndpointRequest

// 创建并配置工作流程
const workflow = createTiptapEditWorkflow()

const result = streamText({
  model: openai('gpt-5.4-mini'),
  system: workflow.systemPrompt,
  prompt: JSON.stringify({ content, task, context }),
  output: Output.object({ schema: workflow.zodOutputSchema }),
})

`tiptapEditWorkflow`

将一组编辑操作应用于文档。

参数

options (TiptapEditWorkflowOptions): 配置选项
- hasFinished (boolean): 是否流式传输已完成。在操作仍在流式传输时传递 false，在最后一次调用时传递 true。
- operations (PartialTiptapEditOperation[]): 编辑操作数组。每个操作是一个对象，包含：
  - type: 'replace' | 'insertBefore' | 'insertAfter'
  - target: 节点的 6 字符哈希（来自 tiptapRead）或 'doc' 表示整个文档
  - content: 包含要插入内容的 HTML 字符串
- workflowId (unknown): 此工作流程运行的唯一 ID
- tiptapReadResult (TiptapReadResult): tiptapRead 返回的结果，用于在应用编辑操作时检测陈旧读取。
- reviewOptions? (ReviewOptions): 控制预览/审查行为。
  - 当安装了修订跟踪扩展时支持 mode: 'trackedChanges'。
- streamingOptions? (StreamingOptions): 控制如何应用流式操作。
  - disableTypingEffect? (boolean): 禁用应用流式操作时的打字效果。
- tiptapEditHooks? (TiptapEditHooks): 用于拦截和修改操作的钩子。详见 Tiptap Edit 钩子指南。
  - beforeOperation? ((context: BeforeOperationContext) => BeforeOperationResult): 在应用每个操作之前调用。返回 { action: 'accept' } 以应用操作（可选带有 fragment 或 operationType 覆盖），或 { action: 'reject', error } 以跳过。

返回值（`TiptapEditWorkflowResult`）

doc (Node): 应用操作后修改后的文档
operationResults (OperationResult[]): 操作结果数组，按执行顺序。每个结果包含：
- target (string): 与操作结果关联的目标哈希
- success (boolean): 操作是否成功完成
- error (string | null): 如果操作失败则为错误消息，否则为 null

示例

const toolkit = getAiToolkit(editor)

// 获取带哈希的文档内容
const { content } = toolkit.tiptapRead()

const operations = await callApiEndpoint({ content, task: '使文本更正式' })

// 应用编辑操作
const result = toolkit.tiptapEditWorkflow({
  hasFinished: true,
  operations,
  workflowId: 'edit-123',
  reviewOptions: {
    mode: 'preview',
  },
})

`createEditThreadsWorkflow`（服务器端工具）

创建一个预设的评论和线程管理工作流程配置。返回系统提示和用于验证 AI 输出的模式。

该工作流程期望用户的输入为 JSON 对象，包含：

content: 文档内容（来自 tiptapRead）
threads：文档中的现有线程（来自 getThreads）
task：描述评论管理任务的字符串

返回值

systemPrompt（string）：可直接使用的系统提示，指导 AI 模型如何管理评论
zodOutputSchema（ZodObject）：用于验证 AI 输出的 Zod 模式
jsonOutputSchema（object）：用于验证 AI 输出的 JSON 模式

示例

import { createEditThreadsWorkflow } from '@tiptap-pro/ai-toolkit-tool-definitions'
import { Output, streamText } from 'ai'
import { openai } from '@ai-sdk/openai'

// 从 API 端点请求中获取内容、线程和任务
const { content, threads, task } = apiEndpointRequest

// 创建并配置工作流程
const workflow = createEditThreadsWorkflow()

const result = streamText({
  model: openai('gpt-5.4-mini'),
  system: workflow.systemPrompt,
  prompt: JSON.stringify({ content, threads, task }),
  output: Output.object({ schema: workflow.zodOutputSchema }),
})

`getThreads`

获取文档中所有线程及其评论和位置信息。

返回值（`GetThreadsResult`）

threadCount（number）：文档中线程数量
threads（ThreadInfo[]）：线程信息数组，每项包含：
- id（string）：线程唯一标识
- comments（{ id: string; content: string }[]）：线程中的评论数组
- nodeRange?（string）：线程所在节点范围
- documentContent?（string）：线程应用的 HTML 内容

示例

const toolkit = getAiToolkit(editor)

// 获取文档中所有线程
const result = toolkit.getThreads()

console.log(`共找到 ${result.threadCount} 个线程`)

result.threads.forEach((thread) => {
  console.log(`线程 ${thread.id}：${thread.comments.length} 条评论`)
})

`editThreadsWorkflow`

将评论和线程操作应用于文档。

参数

options (EditThreadsWorkflowOptions): 配置选项
- operations (string[][]): 评论操作数组，元素为操作元组。
- selectableNodeTypes? (string[]): 始终应具有哈希的节点类型名称数组，即使它们不是顶层节点。默认情况下，所有块节点类型都可以有哈希。若设置为 []，则仅顶层节点拥有哈希。
- commentsOptions? (CommentsOptions): 评论操作选项
  - threadData? (Record<string, any>): 创建的线程的额外元数据
  - commentData? (Record<string, any>): 创建的评论的额外元数据

返回值（`EditThreadsWorkflowResult`）

operations（EditThreadsOperationResult[]）：操作结果数组
success（boolean）：所有操作是否均成功

示例

const toolkit = getAiToolkit(editor)

// 获取文档内容和线程
const { content } = toolkit.tiptapRead()
const { threads } = toolkit.getThreads()

const operations = await callApiEndpoint({ content, threads, task: '添加复审评论' })

// 应用评论操作
const result = toolkit.editThreadsWorkflow({
  operations,
})

if (result.success) {
  console.log('所有评论操作均成功完成')
}

`createTemplateWorkflow`（服务器端工具）

创建一个预设的模板填充工作流程配置。接受一个 HTML 模板字符串（由客户端的 createHtmlTemplate 方法生成），自动提取所有模板键，并返回系统提示及验证 AI 输出的模式。

该工作流程期望用户的输入为 JSON 对象，包含：

task：描述为模板生成内容的字符串
context: （可选）与任务相关的额外上下文或背景信息

参数

options (CreateTemplateWorkflowOptions): 配置选项
- htmlTemplate (string): 由客户端 createHtmlTemplate 方法生成的 HTML 模板字符串
- requiredSlots? (string[]): AI 必须填写的 Slot 名称列表。未列出的 Slot 为可选。未传入时所有 Slot 皆为必填，传入空数组时所有 Slot 皆为可选。
- requiredConditions? (string[]): AI 必须计算的条件名称列表。未列出的条件为可选。未传入时所有条件皆为必填，传入空数组时所有条件皆为可选。
- requiredAttributes? (string[]): AI 必须设置的属性键名称列表。未列出的属性为可选。未传入时所有属性皆为必填，传入空数组时所有属性皆为可选。

返回值

systemPrompt（string）：可直接使用的系统提示，指导 AI 模型如何填充模板
zodOutputSchema（ZodObject）：用于验证 AI 输出的 Zod 模式
jsonOutputSchema（object）：用于验证 AI 输出的 JSON 模式

示例

import { createTemplateWorkflow } from '@tiptap-pro/ai-toolkit-tool-definitions'
import { Output, streamText } from 'ai'
import { openai } from '@ai-sdk/openai'

const { htmlTemplate, task } = apiEndpointRequest

const workflow = createTemplateWorkflow({ htmlTemplate })

const result = streamText({
  model: openai('gpt-5.4-mini'),
  system: workflow.systemPrompt,
  prompt: JSON.stringify({ task, context }),
  output: Output.object({ schema: workflow.zodOutputSchema }),
})

return result.toTextStreamResponse()

`templateWorkflow`

使用 AI 生成的值填充 Tiptap JSON 模板，并将结果插入编辑器。模板使用特殊属性（_templateSlot, _templateIf, _templateAttributes, _templateFieldMetadata）来标记动态部分。

参数

options (TemplateWorkflowOptions): 配置选项
- template (Record<string, any>): Tiptap JSON 格式的模板（doc 节点或片段数组）
- values (TemplateValues): AI 生成且填充模板的值。键名对应模板属性中的值。
- position? (Range | number): 插入填充模板的位置。默认：整个文档区间。
- hasFinished? (boolean): 是否已完成流式传输。省略时方法以非流式模式运行。默认：true
- workflowId? (unknown): 此工作流运行的唯一 ID。提供时启用流式模式，方法将在多次调用中跟踪插入区间并逐步替换内容。
- preserveSlotAttr? (boolean): 是否保留节点上的 _templateSlot 属性。保留后，可识别 AI 填充的内容，便于后续重新填充模板字段。默认：false
- reviewOptions? (ReviewOptions): 控制预览/审核行为

示例

import { experimental_useObject as useObject } from '@ai-sdk/react'
import { getAiToolkit } from '@tiptap-pro/ai-toolkit'
import { z } from 'zod'

const templateSchema = z.object({}).passthrough()

const { submit, isLoading, object } = useObject({
  api: '/api/template-workflow',
  schema: templateSchema,
})

// 在 useEffect 中流式传输部分结果
useEffect(() => {
  if (!editor || !object) return

  const toolkit = getAiToolkit(editor)
  toolkit.templateWorkflow({
    template: templateJson,
    values: object as Record<string, unknown>,
    position: 'document',
    hasFinished: !isLoading,
    workflowId,
  })
}, [object, workflowId, editor, isLoading])

`createHtmlTemplate`

将 Tiptap JSON 模板转换为带有模板属性的 HTML 字符串。结果 HTML 可以发送到服务器，createTemplateWorkflow 将解析模板键。

由于这是 AI 工具包方法，自动拥有编辑器 schema，无需额外传入，直接传模板即可。

参数

template (Record<string, unknown>): Tiptap JSON 格式的模板（doc 节点或片段数组）

返回值

带有小写模板属性（_templateslot, _templateif, _templateattributes, _templatefieldmetadata）的 HTML string

示例

const toolkit = getAiToolkit(editor)
const htmlTemplate = toolkit.createHtmlTemplate(templateJson)

`TemplateField`

一个 Tiptap 扩展，给编辑器 schema 中的所有节点类型添加模板字段属性。注册此扩展后，编辑器 DOM（渲染、解析和 CSS 样式）中即可支持模板字段的使用。

该扩展添加了四个全局属性：

_templateSlot (string | null): 将节点标记为内容占位符。填充模板时，节点将被替换为 AI 生成的 HTML。
_templateIf (string | null): 将节点标记为条件包含。当值为 false 时，节点将从输出中排除。
_templateAttributes (TemplateAttributeEntry[] | null): 将模板键映射到特定的节点属性。
_templateFieldMetadata (Record<string, unknown> | null): 存储字段出现实例的可选开发者定义元数据。

命令

setTemplateSlot(name: string)：在当前选中节点上设置 _templateSlot 属性。
unsetTemplateSlot()：移除当前选中节点的 _templateSlot 属性。
setTemplateIf(name: string)：在当前选中节点上设置 _templateIf 属性。
unsetTemplateIf()：移除当前选中节点的 _templateIf 属性。
setTemplateAttributes(entries: TemplateAttributeEntry[])：在当前选中节点上设置 _templateAttributes 属性。
unsetTemplateAttributes()：移除当前选中节点的 _templateAttributes 属性。

示例

import { TemplateField } from '@tiptap-pro/ai-toolkit'

const editor = new Editor({
  extensions: [StarterKit, TemplateField],
})

// 将当前选中节点标记为模板插槽
editor.commands.setTemplateSlot('intro')

// 移除模板插槽
editor.commands.unsetTemplateSlot()

`getTemplateFieldMatches`

从 Tiptap JSON 文档中返回字段名称的所有匹配模板字段出现实例。

搜索涵盖 _templateSlot, _templateIf 和 _templateAttributes。每个匹配项包括节点内容以及存储在该字段出现实例上的可选 _templateFieldMetadata 对象。

参数

options (GetTemplateFieldMatchesOptions): 搜索选项
- document (JSONContent | JSONContent[]): Tiptap JSON 文档节点或片段数组
- fieldName (string): 要搜索的字段名称

返回值

TemplateFieldMatch[]
- fieldName (string): 匹配的字段名称
- fieldType ('slot' | 'condition' | 'attribute'): 匹配的模板字段类型
- metadata (Record<string, unknown> | null): 该字段出现实例的 _templateFieldMetadata 对象
- content (JSONContent[] | null): 匹配节点内容，格式为 Tiptap JSON

示例

import { getTemplateFieldMatches } from '@tiptap-pro/ai-toolkit'

const matches = getTemplateFieldMatches({
  document: editor.getJSON(),
  fieldName: 'intro',
})

matches.forEach(match => {
  console.log(match.fieldType)
  console.log(match.metadata)
  console.log(match.content)
})

Previously工具执行

Next up模式感知

createProofreaderWorkflow（服务器端工具）

返回值

示例

createInsertContentWorkflow（服务器端工具）

返回值

示例

proofreaderWorkflow

参数

返回值（ProofreaderWorkflowResult）

示例

createTiptapEditWorkflow（服务器端工具）

返回值

示例

tiptapEditWorkflow

参数

返回值（TiptapEditWorkflowResult）

示例

createEditThreadsWorkflow（服务器端工具）

返回值

示例

getThreads

返回值（GetThreadsResult）

示例

editThreadsWorkflow

参数

返回值（EditThreadsWorkflowResult）

示例

createTemplateWorkflow（服务器端工具）

参数

返回值

示例

templateWorkflow

参数

示例

createHtmlTemplate

参数

返回值

示例

TemplateField

命令

示例

getTemplateFieldMatches

参数

返回值

示例

`createProofreaderWorkflow`（服务器端工具）

`createInsertContentWorkflow`（服务器端工具）

`proofreaderWorkflow`

返回值（`ProofreaderWorkflowResult`）

`createTiptapEditWorkflow`（服务器端工具）

`tiptapEditWorkflow`

返回值（`TiptapEditWorkflowResult`）

`createEditThreadsWorkflow`（服务器端工具）

`getThreads`

返回值（`GetThreadsResult`）

`editThreadsWorkflow`

返回值（`EditThreadsWorkflowResult`）

`createTemplateWorkflow`（服务器端工具）

`templateWorkflow`

`createHtmlTemplate`

`TemplateField`

`getTemplateFieldMatches`