AI Changes 扩展 API 参考

/**
 * AI Changes 扩展的配置选项
 */
export interface AiChangesOptions {
  /**
   * 创建 AI 变更的装饰
   *
   * @default getDefaultDecorations 参数
   *
   * @param options 当前的变更、变更列表、当前变更是否被选中、获取默认装饰的函数、编辑器实例、AI 修改前的文档以及 AI 修改后的文档。
   * @returns 应用于文档的 ProseMirror 装饰列表
   */
  getCustomDecorations: (options: GetCustomDecorationsOptions) => Decoration[];
}

/**
 * `getCustomDecorations` 函数的选项
 */
export interface GetCustomDecorationsOptions {
  /**
   * 当前正在处理的变更
   */
  change: AiChange;
  /**
   * AI 进行的变更列表
   */
  changes: AiChange[];
  /**
   * 当前变更是否被选中
   */
  isSelected: boolean;
  /**
   * 获取扩展在未提供 `getCustomDecorations` 函数时，会默认应用于文档的装饰。
   *
   * @returns 要应用于文档的默认装饰列表
   */
  getDefaultDecorations: () => Decoration[];
  /**
   * Tiptap 编辑器实例
   */
  editor: Editor;
  /**
   * AI 修改前的文档
   */
  previousDoc: Node | null;
  /**
   * AI 修改后的当前文档
   */
  currentDoc: Node;
}

/**
 * AI Changes 扩展的命令
 */
declare module '@tiptap/core' {
  interface Commands<ReturnType> {
    previewAiAgentChanges: {
      /**
       * 开始跟踪文档中的 AI 变更，并在编辑器中显示当前文档与初始文档之间的差异。
       *
       * @param doc 用于比较的初始文档。如果未提供，则使用当前文档。
       */
      startTrackingAiChanges: (doc?: Node) => ReturnType

      /**
       * 结束跟踪文档中的 AI 变更。将初始文档设置为 `null`，并停止显示当前文档之间的差异。
       */
      stopTrackingAiChanges: () => ReturnType

      /**
       * 接受文档中的所有 AI 变更。将初始文档设置为当前文档。
       */
      acceptAllAiChanges: () => ReturnType

      /**
       * 撤销文档中的所有 AI 变更，并恢复初始文档。
       */
      rejectAllAiChanges: () => ReturnType

      /**
       * 接受文档中指定的 AI 变更。它修改初始文档，使其在该特定变更处内容与当前文档相同。
       * @param id 要接受的变更的 ID
       */
      acceptAiChange: (id: string) => ReturnType

      /**
       * 拒绝文档中指定的 AI 变更。当前文档在该特定变更处的内容将与初始文档相同。
       *
       * @param id 要拒绝的变更的 ID
       * @returns
       */
      rejectAiChange: (id: string) => ReturnType

      /**
       * 显示或隐藏文档中的 AI 变更。
       *
       * @param show 是否显示 AI 变更
       */
      setShowAiChanges: (show: boolean) => ReturnType
      /**
       * 设置一个变更为选中状态。将光标置于该变更范围的起始位置。
       *
       * @param id 要选中的变更的 ID
       */
      selectAiChange: (id: string) => ReturnType
    }
  }
}

/**
 * AI Changes 扩展的内部存储属性。
 */
export interface AiChangesStorage {
  /** 扩展使用的 ProseMirror 插件键 */
  pluginKey: PluginKey<AiChangesProsemirrorPluginState>
  /**
   * 返回 AI 对文档所做的变更列表
   *
   * @returns 文档的变更列表
   */
  getChanges: () => AiChange[]
  /**
   * 返回文档中当前选中的变更。选中的变更指光标位于其范围内。
   *
   * @returns 当前选中的变更，若无选中则返回 null
   */
  getSelectedChange: () => AiChange | null
  /**
   * 返回 AI 修改之前的先前文档。如果扩展当前没有跟踪变更，则该值为 `null`。
   *
   * @returns AI 修改之前的先前文档，若未跟踪变更则为 null
   */
  getPreviousDoc: () => Node | null
  /**
   * 返回扩展当前是否正在跟踪 AI 所做的变更，若否则为 `false`。
   *
   * @returns 若正在跟踪 AI 变更，则为 `true`，否则为 `false`
   */
  getIsTrackingAiChanges: () => boolean
  /**
   * 返回扩展当前是否正在显示 AI 所做的变更，若否则为 `false`。
   *
   * @returns 若正在显示 AI 变更，则为 `true`，否则为 `false`
   */
  getIsShowingAiChanges: () => boolean
}

import { Range } from '@tiptap/core'

/**
 * AI 代理所做的变更。变更是通过计算旧文档与新文档（AI 代理修改前后）的差异得到的。
 * 变更对象存储在 AI Changes 扩展的存储中，并用于在编辑器中渲染变更内容。
 */
export interface AiChange {
  /**
   * 变更的唯一标识符。
   */
  id: string
  /**
   * 旧文档中被删除内容的范围。
   */
  oldRange: Range
  /**
   * 新文档中被添加内容的范围。
   * 这是 AI 代理插入的内容范围。
   */
  newRange: Range
}