---
title: "工作流程"
description: "AI 工具包内置工作流程的 API 参考。"
canonical_url: "https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/workflows"
---

# 工作流程

AI 工具包内置工作流程的 API 参考。

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

- [插入内容](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/workflows/insert-content.md)。
- [校对器](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/workflows/proofreader.md)。
- [Tiptap 编辑](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/workflows/tiptap-edit.md)。
- [评论](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/workflows/comments.md)。
- [模板](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/workflows/template.md)。

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

## `createProofreaderWorkflow`（服务器端工具）

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

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

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

### 返回值

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

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

### 示例

```ts
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` 字段包含一个带有合理默认值的示例提示，建议您阅读并根据需求修改。

### 示例

```ts
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`](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/review-options.md)): 控制预览/审查行为。[查看可用选项](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/review-options.md)。
    - 在此方法中，`diffUtilityOptions.groupInlineChanges` 默认为 `2` 而不是 `1`，因此编辑默认显示为内联更改。
    - 当安装了 [修订跟踪](https://tiptap.zhcndoc.com/tracked-changes/getting-started/overview.md) 扩展时支持 `mode: 'trackedChanges'`。
  - `range?` (`Range`): 应用校对操作的范围
    - `from` (`number`): 起始位置
    - `to` (`number`): 结束位置

### 返回值（`ProofreaderWorkflowResult`）

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

### 示例

```ts
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 模式

### 示例

```ts
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`](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/review-options.md)): 控制预览/审查行为。
    - 当安装了 [修订跟踪](https://tiptap.zhcndoc.com/tracked-changes/getting-started/overview.md) 扩展时支持 `mode: 'trackedChanges'`。
  - `streamingOptions?` (`StreamingOptions`): 控制如何应用流式操作。
    - `disableTypingEffect?` (`boolean`): 禁用应用流式操作时的打字效果。
  - `tiptapEditHooks?` (`TiptapEditHooks`): 用于拦截和修改操作的钩子。详见 [Tiptap Edit 钩子指南](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 }` 以跳过。

### 返回值（`TiptapEditWorkflowResult`）

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

### 示例

```ts
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 模式

### 示例

```ts
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 内容

### 示例

```ts
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`）：所有操作是否均成功

### 示例

```ts
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 模式

### 示例

```ts
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`): 控制预览/审核行为

### 示例

```ts
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>,
    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`

### 示例

```ts
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` 属性。

### 示例

```ts
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

### 示例

```ts
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)
})
```