AI 建议扩展 API 参考

export interface AiAgentEventContext {
  editor: Editor
  provider: AiAgentProvider
}

export type EventHandlers = {
  loadingError: (error: unknown, context: AiAgentEventContext) => void
  stateChange: (
    state: AiAgentProviderState,
    previousState: AiAgentProviderState,
    context: AiAgentEventContext,
  ) => void
  beforeToolCall: (toolCall: AiAgentToolCall, context: AiAgentEventContext) => void
  afterToolCall: (toolCall: AiAgentToolCall, context: AiAgentEventContext) => void
  stopRunning: (context: AiAgentEventContext) => void
}

/**
 * AI Agent 提供者的配置选项
 */
export interface AiAgentProviderOptions extends Omit<BaseAiAgentProviderOptions, 'onStateChange'> {
  /**
   * 用于 AI 服务身份验证的应用 ID。
   */
  appId: string

  /**
   * AI 服务的身份验证令牌。
   */
  token: string

  /**
   * AI 服务 API 的基础 URL。
   */
  baseUrl: string
  /**
   * 与 AI Agent 对话的初始聊天消息。
   * @default []
   * @example
   * ```ts
   * [
   *   {
   *     type: 'ai',
   *     text: "你好，我是一个可以编辑你的文档的 AI 助手。需要我帮忙吗？",
   *   },
   * ]
   * ```
   */
  initialChatMessages: ChatMessage[]

  /**
   * 控制 AI Agent 是否应该自动接受修改编辑器内容的工具调用。
   * @default "onlyRead"
   */
  autoAccept: 'always' | 'never' | 'onlyRead'
  /**
   * 控制是否在用户发送消息或接受工具调用时自动保存检查点。
   * 如果为 false，setCheckpoint 函数不会被调用。
   * @default false
   */
  autoSaveCheckpoints?: boolean
  /**
   * AI Agent 使用的 OpenAI 模型。
   * 推荐使用 gpt-4.1 和 gpt-4o 模型，因为它们与 AI Agent 配合效果最佳。
   * 模型需要支持工具调用。
   * @default "gpt-4.1"
   */
  modelName?: AiAgentModelName

  onLoadingError: EventHandlers['loadingError']
  onStateChange: EventHandlers['stateChange']
  onBeforeToolCall: EventHandlers['beforeToolCall']
  onAfterToolCall: EventHandlers['afterToolCall']
  onStopRunning: EventHandlers['stopRunning']

  /**
   * 是否让 AI Agent 使用 AI Changes 扩展。
   * @default true
   */
  useAiChangesExtension: boolean

  /**
   * 解析 AI Agent 请求的函数。允许你将 AI Agent 集成到你自己的后端服务。
   * @param options AI Agent 请求的选项，包括聊天消息、工具处理器和模型名称。
   * @returns 来自 AI 服务的聊天消息和工具调用消息
   * @default defaultAiAgentResolver
   */
  resolver: (options: AiAgentResolverOptions) => Promise<AiAgentResolverReturn>

  /**
   * AI Agent 使用的系统提示。在使用 Tiptap Cloud 的 AI Agent 时覆盖默认系统提示。
   */
  systemPrompt: string | null
}

/**
 * AI Agent 提供者的内部状态。
 */
export interface AiAgentProviderState {
  /**
   * AI Agent 当前的状态。它决定下一步采取的操作。
   *
   * AI Agent 工作方式类似有限状态机，可以从一个状态转换到另一个状态。
   *
   * @see AiAgentStatus
   */
  status: AiAgentStatus
  loadingError: unknown
  /**
   * 对话中的聊天消息。
   */
  chatMessages: ChatMessage[]
  chatMessagesPendingReview: {
    accept: ChatMessage[]
    reject: ChatMessage[]
  }
  /**
   * 控制 AI Agent 的自动接受行为。
   * - "always"：自动接受所有工具调用。
   * - "never"：永不自动接受工具调用，需要人工审核。
   * - "onlyRead"：自动接受不修改编辑器内容的工具调用。
   */
  autoAccept: 'always' | 'never' | 'onlyRead'

  /**
   * AI Agent 使用的系统提示。在使用 Tiptap Cloud 的 AI Agent 时覆盖默认系统提示。
   */
  systemPrompt: string | null
}