自定义节点

继续 AI 代理聊天机器人指南

本指南是对 AI 代理聊天机器人指南的延续。请先阅读该指南。

如果您的文档包含自定义节点或标记，请配置 schema 识别，以便 Server AI Toolkit 能够向您的 AI 模型正确描述它们。

为什么要配置自定义节点？

如果没有 schema 识别，AI 模型可能会生成编辑器不支持的内容，或者完全遗漏自定义元素。添加自定义节点元数据可以为模型提供足够的上下文，以便可靠地生成这些元素。

获取 schema 识别数据

首先从您的编辑器生成 schema 识别数据。Server AI Toolkit 使用此数据向 AI 模型描述您的文档结构。

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { getSchemaAwarenessData } from '@tiptap-pro/server-ai-toolkit'

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

// 获取 schema 识别数据
const schemaAwarenessData = getSchemaAwarenessData(editor)

存储 schema 识别数据

getSchemaAwarenessData 返回的 schema 识别数据是一个可 JSON 序列化的对象，您可以将其存储在数据库中。您不需要每次都生成它。当您的编辑器扩展或 schema 发生变化时更新它即可。

配置自定义节点

如果您的文档包含自定义节点和标记，请在扩展配置中添加 addJsonSchemaAwareness 选项。这使得 AI 模型能够准确地理解并生成该自定义节点或标记。

例如，如果您有一个名为 'alert' 的自定义节点，请按如下方式配置：

import { Node } from '@tiptap/core'
import { z } from 'zod'

const CustomExtension = Node.create({
  name: 'alert',

  addAttributes() {
    return {
      type: {
        default: 'info',
        parseHTML: (element) => element.getAttribute('data-type'),
        renderHTML: (attributes) => {
          if (!attributes.type) {
            return {}
          }

          return {
            'data-type': attributes.type,
          }
        },
      },
    }
  },

  addJsonSchemaAwareness() {
    return {
      name: '警告框',
      description: `用于显示重要信息、警告或提示的高亮框。
它可以包含行内内容，如文本和格式标记。`,
      attributes: {
        type: z
          .enum(['info', 'warning', 'error', 'success'])
          .describe(
            '警告类型。可为以下 4 种值之一：info、warning、error 或 success',
          ),
      },
    }
  },

  parseHTML() {
    return [
      {
        tag: 'div[data-alert]',
      },
    ]
  },

  renderHTML({ HTMLAttributes }) {
    return ['div', { ...HTMLAttributes, 'data-alert': '' }, 0]
  },
})

addJsonSchemaAwareness 函数应返回一个对象，包含：

name（string）：元素的英文人类可读名称
description?（string）：元素的英文解释，供 AI 模型使用
attributes?（Record<string, z.ZodTypeAny>）：元素可能拥有的属性，定义为 Zod 模式，将被转换成 JSON 模式

官方 Tiptap 扩展的情况？

Server AI Toolkit 自动支持官方 Tiptap 扩展的 schema 识别，无需额外配置。您仍然可以通过扩展官方扩展并添加 addJsonSchemaAwareness 选项来重写默认的 schema 识别信息。

后续步骤

Previously高级指南

Next upTiptap 简写