@ai-group/chat-sdk 3.8.0-alpha.1 → 3.8.0-alpha.3

package/dist/cjs/types/XAdkSender.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/types/XAdkSender.ts"],
-  "sourcesContent": ["// types/XAdkSender.ts\nimport React from \"react\";\n\n// ===================== 快捷键/Mention 相关类型 =====================\n\n/** 快捷键触发的列表项 */\nexport interface QuickListOption {\n  id: string;\n  label: string;\n  description?: string;\n  icon?: React.ReactNode;\n  /** 选中后的行为。insert 会写入 Mention；command 仅执行回调。默认 insert。 */\n  action?: \"insert\" | \"command\";\n  /** 选中当前选项时执行，可用于 command 类型的业务动作。 */\n  onSelect?: (option: QuickListOption) => void;\n  /** 分组名（用于聚合列表，子分组通过下划线分割） */\n  group?: string;\n  [key: string]: any;\n}\n\n/** 快捷键配置 */\nexport interface QuickKeyConfig {\n  /** 触发字符，如 '@', '#', '$' */\n  key: string;\n  /** 选中后写入 MentionTag.type 的语义类型，不传时回退为 key */\n  mentionType?: string;\n  /** @deprecated 请使用 mentionType。 */\n  tagType?: string;\n  /** 列表标题 */\n  title?: string;\n  /** 列表数据 */\n  options: QuickListOption[];\n  /** 自定义列表项渲染 */\n  renderItem?: (option: QuickListOption) => React.ReactNode;\n  /** 选中回调 */\n  onSelect?: (option: QuickListOption) => void;\n}\n\n/** 输入框内的资源引用。SDK 只理解通用 Mention，业务语义可放入 data 或可选语义字段。 */\nexport interface MentionTag {\n  id: string;\n  label: string;\n  /** Mention 类型，如 'knowledge', 'skill', 'plugin', 'agent' */\n  type: string;\n  /** 资源 URI，如 skill://skillNo、kb://kb/knNo/dir/docs/2024 */\n  uri?: string;\n  /** 业务资源 ID，如 skillNo、knowledgeNo */\n  targetId?: string;\n  /** 展示名；不传时回退 label */\n  displayName?: string;\n  /** 提交为纯文本/Markdown/XML 时使用的业务值，不传时回退 uri/targetId/label */\n  value?: string;\n  /** 触发字符，如 '@', '#', '$'，用于业务方区分来源 */\n  trigger?: string;\n  color?: string;\n  icon?: React.ReactNode;\n  /** 业务扩展上下文，例如知识库目录 scope */\n  scope?: any;\n  /** 原始数据 */\n  data?: any;\n}\n\n/** @deprecated 请使用 MentionTag。 */\nexport type InputTag = MentionTag;\n\nexport interface InlineTagRenderInfo {\n  onRemove: () => void;\n}\n\nexport type XAdkSenderSubmitFormat = \"text\" | \"structured\" | \"markdown\" | \"xml\";\n\nexport type XAdkSenderSubmitPart =\n  | { type: \"text\"; text: string }\n  | { type: \"mention\"; mention: MentionTag };\n\n/** @deprecated 旧 tag part，仅用于兼容 defaultInputParts 历史传入。 */\nexport type XAdkSenderLegacyTagPart = { type: \"tag\"; tag: MentionTag };\n\n/** 输入框文本/Mention 有序片段，表示用户正在编辑的输入内容 */\nexport type XAdkSenderInputPart =\n  | XAdkSenderSubmitPart\n  | XAdkSenderLegacyTagPart;\n\nexport interface XAdkSenderFormatMentionContext {\n  format: Exclude<XAdkSenderSubmitFormat, \"structured\">;\n  index: number;\n}\n\n/** @deprecated 请使用 XAdkSenderFormatMentionContext。 */\nexport type XAdkSenderFormatTagContext = XAdkSenderFormatMentionContext;\n\nexport interface XAdkSenderSubmitData<TPayload = unknown> {\n  /** 根据 submitFormat 生成的最终内容，默认是纯文本 */\n  text: string;\n  /** 去掉标签后的用户原始输入文本 */\n  rawText: string;\n  /** 当前提交格式 */\n  format: XAdkSenderSubmitFormat;\n  /** 文本与 Mention 的有序片段，inlineTags 模式下可还原资源引用在输入框中的位置 */\n  parts: XAdkSenderSubmitPart[];\n  files: ServerFile[];\n  /** 当前 Mention 列表 */\n  mentions?: MentionTag[];\n  /** @deprecated 请使用 mentions。 */\n  tags?: MentionTag[];\n  /** 业务方通过 transformSubmitData 派生出的自定义提交结构 */\n  payload?: TPayload;\n}\n\n// ===================== 上传相关类型 =====================\n\nexport interface UploadFileResult {\n  fileName?: string;\n  fileId?: string | number;\n  tempUrl?: string;\n  url?: string;\n  fileUrl?: string;\n  fileType?: string;\n  fileSize?: number;\n  mimeType?: string;\n  [key: string]: any;\n}\n\nexport interface UploadSuccessResponse {\n  data?: UploadFileResult | UploadFileResult[];\n  [key: string]: any;\n}\n\ninterface uploadRequestProps {\n  (options: {\n    file: File;\n    onProgress?: (e: { percent: number }) => void;\n    onSuccess?: (\n      response: UploadFileResult | UploadFileResult[] | UploadSuccessResponse,\n    ) => void;\n    onError?: (error: Error) => void;\n  }): Promise<void> | void;\n}\n\nexport type UploadRequestFn = uploadRequestProps;\n\nexport interface ServerFile {\n  fileName: string;\n  fileId: string | number;\n  tempUrl: string;\n  type: string;\n  size?: number;\n  mimeType: string;\n  raw?: UploadFileResult;\n}\n\nexport interface LocalFile {\n  id: string;\n  uid: string;\n  name: string;\n  file: File;\n  size: number;\n  type: string;\n  progress: number;\n  status: \"pending\" | \"uploading\" | \"success\" | \"error\";\n  // 服务器返回字段\n  fileId?: string | number;\n  tempUrl?: string;\n  response?: any;\n  errorMessage?: string; // 上传错误信息\n}\n\nexport type FileValidator = (\n  file: File,\n  context: { files: LocalFile[] },\n) => string | null;\n\nexport interface ActionsComponents {\n  SendButton: React.ComponentType<any>;\n  ClearButton: React.ComponentType<any>;\n}\n\nexport type SlotRenderFunction = (\n  oriNode: React.ReactNode,\n  info: { components: ActionsComponents },\n) => React.ReactNode | false;\n\n// 上传相关\nexport interface UploaderCoreProps {\n  uploadRequest?: uploadRequestProps;\n\n  maxFileSize?: number;\n  allowedFileTypes?: string[];\n  maxFiles?: number;\n\n  validators?: FileValidator[];\n\n  // 数据层回调\n  onFilesChange?: (files: LocalFile[]) => void;\n  onUploadSuccess?: (file: LocalFile) => void;\n  onUploadError?: (file: LocalFile, error: Error) => void;\n}\n\n// UI 相关\nexport interface SenderUIProps {\n  clearBtnShow?: boolean;\n  /**\n   * 是否启用 Sender 自身的拖拽上传。\n   * 拖拽产生的文件通过 onFileSelect 回调交给业务/外层处理；\n   * 默认 false，由外层（如 DefaultLayout）管理拖拽时无需开启。\n   */\n  draggable?: boolean;\n  /**\n   * 拖拽文件回调：当 draggable 为 true 且用户向输入区拖拽文件时触发。\n   * 业务/外层在此回调中决定如何处理文件（通常调用 senderRef.addFiles 注入）。\n   */\n  onFileSelect?: (files: File[]) => void;\n  loading?: boolean;\n  disabled?: boolean; // 只读状态\n  placeholder?: string;\n  /** 受控：输入框的值 */\n  value?: string;\n  /** 非受控：输入框默认值 */\n  defaultValue?: string;\n  onClear?: () => void;\n  onChange?: (value: string) => void;\n  onSubmit?: (data: XAdkSenderSubmitData) => void;\n  onStop?: () => void;\n\n  /** 自定义发送按钮渲染 */\n  sendButtonRender?: (info: {\n    loading: boolean;\n    disabled: boolean;\n    /** 当前是否可以发送（文本非空或有已上传的文件） */\n    canSend: boolean;\n    onSend: () => void;\n    onStop?: () => void;\n  }) => React.ReactNode;\n\n  // UI插槽功能\n  /** 后缀内容,默认展示操作按钮,设为 false 时不显示 */\n  suffix?: React.ReactNode | false | SlotRenderFunction;\n  /** 输入主体内部的头部内容 */\n  header?: React.ReactNode | false | SlotRenderFunction;\n  /** 前缀内容 */\n  prefix?: React.ReactNode | false | SlotRenderFunction;\n  /** 底部内容 */\n  footer?: React.ReactNode | false | SlotRenderFunction;\n  /** 底部左侧拓展区域，不传时 footer 保持原有居中布局 */\n  footerLeft?: React.ReactNode | false | SlotRenderFunction;\n\n  // 快捷键/Mention 功能\n  /** 快捷键配置列表 */\n  quickKeys?: QuickKeyConfig[];\n  /** 是否把 Mention 以内联 token 形式展示在输入区内；默认 false 保持历史 textarea 行为 */\n  inlineTags?: boolean;\n  /** 自定义内联 Mention 渲染 */\n  renderMention?: (\n    mention: MentionTag,\n    info: InlineTagRenderInfo,\n  ) => React.ReactNode;\n  /** @deprecated 请使用 renderMention。 */\n  renderTag?: (\n    mention: MentionTag,\n    info: InlineTagRenderInfo,\n  ) => React.ReactNode;\n  /** 受控：Mention 列表 */\n  mentions?: MentionTag[];\n  /** @deprecated 请使用 mentions。 */\n  tags?: MentionTag[];\n  /** 非受控：默认 Mention 列表 */\n  defaultMentions?: MentionTag[];\n  /** @deprecated 请使用 defaultMentions。 */\n  defaultTags?: MentionTag[];\n  /** 非受控：默认输入内容片段，用于初始化内联 Mention 输入区 */\n  defaultInputParts?: XAdkSenderInputPart[];\n  /** Mention 变化回调 */\n  onMentionsChange?: (mentions: MentionTag[]) => void;\n  /** @deprecated 请使用 onMentionsChange。 */\n  onTagsChange?: (mentions: MentionTag[]) => void;\n  /** 快捷键触发回调（业务方可在此处理搜索等逻辑） */\n  onQuickKeyTrigger?: (key: string, keyword: string) => void;\n  /**\n   * 提交内容格式：\n   * - text: 默认，输出文字 + Mention 文本（如 @生图技能）\n   * - structured: 保留 parts/mentions/files 结构化数据，text 为 rawText\n   * - markdown/xml: 输出对应标记文本\n   */\n  submitFormat?: XAdkSenderSubmitFormat;\n  /** 自定义 Mention 在 text/markdown/xml 格式中的序列化结果 */\n  formatMention?: (\n    mention: MentionTag,\n    context: XAdkSenderFormatMentionContext,\n  ) => string;\n  /** @deprecated 请使用 formatMention。 */\n  formatTag?: (\n    mention: MentionTag,\n    context: XAdkSenderFormatMentionContext,\n  ) => string;\n  /**\n   * 基于 SDK 标准提交结构派生业务 payload。\n   * SDK 不理解 knowledge/skill/agent 等业务字段，只负责把 payload 原样放入 onSubmit 数据中。\n   */\n  transformSubmitData?: (\n    data: Omit<XAdkSenderSubmitData, \"payload\">,\n  ) => unknown;\n}\n\nexport type XAdkSenderProps = SenderUIProps & UploaderCoreProps;\n\nexport interface XAdkSenderHandle {\n  addFiles: (files: File[]) => void;\n  /** 向当前光标位置插入一个内联 Mention；未启用 inlineTags 时会退化为追加 Mention。 */\n  insertMention: (mention: MentionTag) => void;\n  /** @deprecated 请使用 insertMention。 */\n  insertTag: (mention: MentionTag) => void;\n  /** 聚焦输入区 */\n  focus: () => void;\n}\n"],
+  "sourcesContent": ["// types/XAdkSender.ts\nimport React from \"react\";\n\n// ===================== 快捷键/Mention 相关类型 =====================\n\n/** 快捷键触发的列表项 */\nexport interface QuickListOption {\n  id: string;\n  label: string;\n  description?: string;\n  icon?: React.ReactNode;\n  /** 选中后的行为。insert 会写入 Mention；command 仅执行回调。默认 insert。 */\n  action?: \"insert\" | \"command\";\n  /** 选中当前选项时执行，可用于 command 类型的业务动作。 */\n  onSelect?: (option: QuickListOption) => void;\n  /** 分组名（用于聚合列表，子分组通过下划线分割） */\n  group?: string;\n  [key: string]: any;\n}\n\n/** 快捷键配置 */\nexport interface QuickKeyConfig {\n  /** 触发字符，如 '@', '#', '$' */\n  key: string;\n  /** 选中后写入 MentionTag.type 的语义类型，不传时回退为 key */\n  mentionType?: string;\n  /** @deprecated 请使用 mentionType。 */\n  tagType?: string;\n  /** 列表标题 */\n  title?: string;\n  /** 列表数据 */\n  options: QuickListOption[];\n  /** 自定义列表项渲染 */\n  renderItem?: (option: QuickListOption) => React.ReactNode;\n  /** 选中回调 */\n  onSelect?: (option: QuickListOption) => void;\n}\n\n/** 输入框内的资源引用。SDK 只理解通用 Mention，业务语义可放入 data 或可选语义字段。 */\nexport interface MentionTag {\n  id: string;\n  label: string;\n  /** Mention 类型，如 'knowledge', 'skill', 'plugin', 'agent' */\n  type: string;\n  /** 资源 URI，如 skill://skillNo、kb://kb/knNo/dir/docs/2024 */\n  uri?: string;\n  /** 业务资源 ID，如 skillNo、knowledgeNo */\n  targetId?: string;\n  /** 展示名；不传时回退 label */\n  displayName?: string;\n  /** 提交为纯文本/Markdown/XML 时使用的业务值，不传时回退 uri/targetId/label */\n  value?: string;\n  /** 触发字符，如 '@', '#', '$'，用于业务方区分来源 */\n  trigger?: string;\n  color?: string;\n  icon?: React.ReactNode;\n  /** 业务扩展上下文，例如知识库目录 scope */\n  scope?: any;\n  /** 原始数据 */\n  data?: any;\n}\n\n/** @deprecated 请使用 MentionTag。 */\nexport type InputTag = MentionTag;\n\nexport interface InlineTagRenderInfo {\n  onRemove: () => void;\n}\n\nexport type XAdkSenderSubmitFormat = \"text\" | \"structured\" | \"markdown\" | \"xml\";\n\nexport type XAdkSenderSubmitPart =\n  | { type: \"text\"; text: string }\n  | { type: \"mention\"; mention: MentionTag };\n\n/** @deprecated 旧 tag part，仅用于兼容 defaultInputParts 历史传入。 */\nexport type XAdkSenderLegacyTagPart = { type: \"tag\"; tag: MentionTag };\n\n/** 输入框文本/Mention 有序片段，表示用户正在编辑的输入内容 */\nexport type XAdkSenderInputPart =\n  | XAdkSenderSubmitPart\n  | XAdkSenderLegacyTagPart;\n\nexport interface XAdkSenderFormatMentionContext {\n  format: Exclude<XAdkSenderSubmitFormat, \"structured\">;\n  index: number;\n}\n\n/** @deprecated 请使用 XAdkSenderFormatMentionContext。 */\nexport type XAdkSenderFormatTagContext = XAdkSenderFormatMentionContext;\n\nexport interface XAdkSenderSubmitData<TPayload = unknown> {\n  /** 根据 submitFormat 生成的最终内容，默认是纯文本 */\n  text: string;\n  /** 去掉标签后的用户原始输入文本 */\n  rawText: string;\n  /** 当前提交格式 */\n  format: XAdkSenderSubmitFormat;\n  /** 文本与 Mention 的有序片段，inlineTags 模式下可还原资源引用在输入框中的位置 */\n  parts: XAdkSenderSubmitPart[];\n  files: ServerFile[];\n  /** 当前 Mention 列表 */\n  mentions?: MentionTag[];\n  /** @deprecated 请使用 mentions。 */\n  tags?: MentionTag[];\n  /** 业务方通过 transformSubmitData 派生出的自定义提交结构 */\n  payload?: TPayload;\n}\n\n// ===================== 上传相关类型 =====================\n\nexport interface UploadFileResult {\n  fileName?: string;\n  fileId?: string | number;\n  tempUrl?: string;\n  url?: string;\n  fileUrl?: string;\n  fileType?: string;\n  fileSize?: number;\n  mimeType?: string;\n  [key: string]: any;\n}\n\nexport interface UploadSuccessResponse {\n  data?: UploadFileResult | UploadFileResult[];\n  [key: string]: any;\n}\n\ninterface uploadRequestProps {\n  (options: {\n    file: File;\n    onProgress?: (e: { percent: number }) => void;\n    onSuccess?: (\n      response: UploadFileResult | UploadFileResult[] | UploadSuccessResponse,\n    ) => void;\n    onError?: (error: Error) => void;\n  }): Promise<void> | void;\n}\n\nexport type UploadRequestFn = uploadRequestProps;\n\nexport interface ServerFile {\n  fileName: string;\n  fileId: string | number;\n  tempUrl: string;\n  type: string;\n  size?: number;\n  mimeType: string;\n  raw?: UploadFileResult;\n}\n\nexport interface LocalFile {\n  id: string;\n  uid: string;\n  name: string;\n  file: File;\n  size: number;\n  type: string;\n  progress: number;\n  status: \"pending\" | \"uploading\" | \"success\" | \"error\";\n  // 服务器返回字段\n  fileId?: string | number;\n  tempUrl?: string;\n  response?: any;\n  errorMessage?: string; // 上传错误信息\n}\n\nexport type FileValidator = (\n  file: File,\n  context: { files: LocalFile[] },\n) => string | null;\n\nexport interface ActionsComponents {\n  SendButton: React.ComponentType<any>;\n  ClearButton: React.ComponentType<any>;\n}\n\nexport type SlotRenderFunction = (\n  oriNode: React.ReactNode,\n  info: { components: ActionsComponents },\n) => React.ReactNode | false;\n\n// 上传相关\nexport interface UploaderCoreProps {\n  uploadRequest?: uploadRequestProps;\n\n  maxFileSize?: number;\n  allowedFileTypes?: string[];\n  maxFiles?: number;\n\n  validators?: FileValidator[];\n\n  // 数据层回调\n  onFilesChange?: (files: LocalFile[]) => void;\n  onUploadSuccess?: (file: LocalFile) => void;\n  onUploadError?: (file: LocalFile, error: Error) => void;\n}\n\n// UI 相关\nexport interface SenderUIProps {\n  clearBtnShow?: boolean;\n  /**\n   * 是否启用 Sender 自身的拖拽上传。\n   * 拖拽产生的文件通过 onFileSelect 回调交给业务/外层处理；\n   * 默认 false，由外层（如 DefaultLayout）管理拖拽时无需开启。\n   */\n  draggable?: boolean;\n  /**\n   * 拖拽文件回调：当 draggable 为 true 且用户向输入区拖拽文件时触发。\n   * 业务/外层在此回调中决定如何处理文件（通常调用 senderRef.addFiles 注入）。\n   */\n  onFileSelect?: (files: File[]) => void;\n  /**\n   * 是否启用 Sender 自身的粘贴上传。\n   * 粘贴产生的文件通过 onFilePaste 回调交给业务/外层处理；\n   * 默认 true，粘贴是常用能力，开箱即用。设为 false 可完全关闭。\n   */\n  pasteable?: boolean;\n  /**\n   * 粘贴文件回调：当 pasteable 为 true 且用户向输入区粘贴文件（含截图）时触发。\n   * 业务/外层在此回调中决定如何处理文件（通常调用 senderRef.addFiles 注入）。\n   * 注意：纯文本粘贴不会触发本回调，输入框照常接收文本。\n   */\n  onFilePaste?: (files: File[]) => void;\n  loading?: boolean;\n  disabled?: boolean; // 只读状态\n  placeholder?: string;\n  /** 受控：输入框的值 */\n  value?: string;\n  /** 非受控：输入框默认值 */\n  defaultValue?: string;\n  onClear?: () => void;\n  /** 清除按钮的二次确认文案；未传时沿用 SDK 默认文案。 */\n  clearConfirm?: {\n    title?: React.ReactNode;\n    okText?: React.ReactNode;\n    cancelText?: React.ReactNode;\n  };\n  onChange?: (value: string) => void;\n  onSubmit?: (data: XAdkSenderSubmitData) => void;\n  onStop?: () => void;\n\n  /** 自定义发送按钮渲染 */\n  sendButtonRender?: (info: {\n    loading: boolean;\n    disabled: boolean;\n    /** 当前是否可以发送（文本非空或有已上传的文件） */\n    canSend: boolean;\n    onSend: () => void;\n    onStop?: () => void;\n  }) => React.ReactNode;\n\n  // UI插槽功能\n  /** 后缀内容,默认展示操作按钮,设为 false 时不显示 */\n  suffix?: React.ReactNode | false | SlotRenderFunction;\n  /** 输入主体内部的头部内容 */\n  header?: React.ReactNode | false | SlotRenderFunction;\n  /** 前缀内容 */\n  prefix?: React.ReactNode | false | SlotRenderFunction;\n  /** 底部内容 */\n  footer?: React.ReactNode | false | SlotRenderFunction;\n  /** 底部左侧拓展区域，不传时 footer 保持原有居中布局 */\n  footerLeft?: React.ReactNode | false | SlotRenderFunction;\n\n  // 快捷键/Mention 功能\n  /** 快捷键配置列表 */\n  quickKeys?: QuickKeyConfig[];\n  /** 是否把 Mention 以内联 token 形式展示在输入区内；默认 false 保持历史 textarea 行为 */\n  inlineTags?: boolean;\n  /** 自定义内联 Mention 渲染 */\n  renderMention?: (\n    mention: MentionTag,\n    info: InlineTagRenderInfo,\n  ) => React.ReactNode;\n  /** @deprecated 请使用 renderMention。 */\n  renderTag?: (\n    mention: MentionTag,\n    info: InlineTagRenderInfo,\n  ) => React.ReactNode;\n  /** 受控：Mention 列表 */\n  mentions?: MentionTag[];\n  /** @deprecated 请使用 mentions。 */\n  tags?: MentionTag[];\n  /** 非受控：默认 Mention 列表 */\n  defaultMentions?: MentionTag[];\n  /** @deprecated 请使用 defaultMentions。 */\n  defaultTags?: MentionTag[];\n  /** 非受控：默认输入内容片段，用于初始化内联 Mention 输入区 */\n  defaultInputParts?: XAdkSenderInputPart[];\n  /** Mention 变化回调 */\n  onMentionsChange?: (mentions: MentionTag[]) => void;\n  /** @deprecated 请使用 onMentionsChange。 */\n  onTagsChange?: (mentions: MentionTag[]) => void;\n  /** 快捷键触发回调（业务方可在此处理搜索等逻辑） */\n  onQuickKeyTrigger?: (key: string, keyword: string) => void;\n  /**\n   * 提交内容格式：\n   * - text: 默认，输出文字 + Mention 文本（如 @生图技能）\n   * - structured: 保留 parts/mentions/files 结构化数据，text 为 rawText\n   * - markdown/xml: 输出对应标记文本\n   */\n  submitFormat?: XAdkSenderSubmitFormat;\n  /** 自定义 Mention 在 text/markdown/xml 格式中的序列化结果 */\n  formatMention?: (\n    mention: MentionTag,\n    context: XAdkSenderFormatMentionContext,\n  ) => string;\n  /** @deprecated 请使用 formatMention。 */\n  formatTag?: (\n    mention: MentionTag,\n    context: XAdkSenderFormatMentionContext,\n  ) => string;\n  /**\n   * 基于 SDK 标准提交结构派生业务 payload。\n   * SDK 不理解 knowledge/skill/agent 等业务字段，只负责把 payload 原样放入 onSubmit 数据中。\n   */\n  transformSubmitData?: (\n    data: Omit<XAdkSenderSubmitData, \"payload\">,\n  ) => unknown;\n}\n\nexport type XAdkSenderProps = SenderUIProps & UploaderCoreProps;\n\nexport interface XAdkSenderHandle {\n  /** 添加本地文件或已上传文件；后者直接进入附件列表，不重复上传。 */\n  addFiles: (files: Array<File | ServerFile>) => void;\n  /** 向当前光标位置插入一个内联 Mention；未启用 inlineTags 时会退化为追加 Mention。 */\n  insertMention: (mention: MentionTag) => void;\n  /** @deprecated 请使用 insertMention。 */\n  insertTag: (mention: MentionTag) => void;\n  /** 聚焦输入区 */\n  focus: () => void;\n}\n"],
   "mappings": ";;;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

package/dist/cjs/types/antdx.d.ts

@@ -57,7 +57,10 @@ export type BaseNode = React.ReactNode | false;
 export type NodeRender = (oriNode: React.ReactNode, info: {
     components: ActionsComponents;
 }) => BaseNode;
-export interface SenderProps extends Partial<Pick<TextareaProps, 'placeholder' | 'onKeyUp' | 'onFocus' | 'onBlur'>> {
+export interface SenderProps extends Omit<Partial<Pick<TextareaProps, 'placeholder' | 'onKeyUp' | 'onFocus' | 'onBlur'>>, 'onKeyUp' | 'onFocus' | 'onBlur'> {
+    onKeyUp?: React.KeyboardEventHandler<HTMLTextAreaElement>;
+    onFocus?: React.FocusEventHandler<HTMLTextAreaElement>;
+    onBlur?: React.FocusEventHandler<HTMLTextAreaElement>;
     prefixCls?: string;
     defaultValue?: string;
     value?: string;

package/dist/cjs/types/antdx.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/types/antdx.ts"],
-  "sourcesContent": ["/**\n * @ant-design/x 类型本地声明\n * 从 @ant-design/x 源码提取的公共 API 类型，减少外部依赖\n */\nimport type React from 'react';\nimport type { UploadFile, MenuProps, InputProps } from 'antd';\n\n// ==================== Conversations ====================\n\nexport interface ConversationItemType\n  extends Omit<React.HTMLAttributes<HTMLLIElement>, 'onClick'> {\n  key: string;\n  label?: React.ReactNode;\n  group?: string;\n  icon?: React.ReactNode;\n  disabled?: boolean;\n  [key: string]: any;\n}\n\nexport interface DividerItemType {\n  type: 'divider';\n  key?: string;\n  dashed?: boolean;\n}\n\nexport type ItemType = ConversationItemType | DividerItemType;\n\ntype ConversationsSemanticType = 'root' | 'creation' | 'group' | 'item';\n\nexport interface ConversationsProps extends React.HTMLAttributes<HTMLUListElement> {\n  items?: ItemType[];\n  activeKey?: ConversationItemType['key'];\n  defaultActiveKey?: ConversationItemType['key'];\n  onActiveChange?: (value: ConversationItemType['key'], item?: ItemType) => void;\n  menu?:\n    | (MenuProps & {\n        trigger?:\n          | React.ReactNode\n          | ((\n              conversation: ConversationItemType,\n              info: { originNode: React.ReactNode },\n            ) => React.ReactNode);\n        getPopupContainer?: (triggerNode: HTMLElement) => HTMLElement;\n      })\n    | ((\n        value: ConversationItemType,\n      ) => MenuProps & {\n        trigger?:\n          | React.ReactNode\n          | ((\n              conversation: ConversationItemType,\n              info: { originNode: React.ReactNode },\n            ) => React.ReactNode);\n        getPopupContainer?: (triggerNode: HTMLElement) => HTMLElement;\n      });\n  groupable?: boolean | Record<string, any>;\n  styles?: Partial<Record<ConversationsSemanticType, React.CSSProperties>>;\n  classNames?: Partial<Record<ConversationsSemanticType, string>>;\n  prefixCls?: string;\n  rootClassName?: string;\n}\n\n// ==================== Sender ====================\n\ntype TextareaProps = InputProps;\n\ntype SubmitType = 'enter' | 'shiftEnter';\n\ntype SenderSemanticType = 'root' | 'prefix' | 'input' | 'suffix' | 'footer' | 'switch' | 'content';\n\nexport interface SenderComponents {\n  input?: React.ComponentType<any>;\n}\n\nexport type ActionsComponents = {\n  SendButton: React.ComponentType<any>;\n  ClearButton: React.ComponentType<any>;\n  LoadingButton: React.ComponentType<any>;\n  SpeechButton: React.ComponentType<any>;\n};\n\nexport type BaseNode = React.ReactNode | false;\nexport type NodeRender = (\n  oriNode: React.ReactNode,\n  info: { components: ActionsComponents },\n) => BaseNode;\n\nexport interface SenderProps\n  extends Partial<Pick<TextareaProps, 'placeholder' | 'onKeyUp' | 'onFocus' | 'onBlur'>> {\n  prefixCls?: string;\n  defaultValue?: string;\n  value?: string;\n  loading?: boolean;\n  readOnly?: boolean;\n  submitType?: SubmitType;\n  disabled?: boolean;\n  onSubmit?: (message: string, ...args: any[]) => void;\n  onChange?: (value: string, ...args: any[]) => void;\n  onCancel?: VoidFunction;\n  onKeyDown?: (event: React.KeyboardEvent) => void | false;\n  onPaste?: React.ClipboardEventHandler<HTMLElement>;\n  onPasteFile?: (files: FileList) => void;\n  components?: SenderComponents;\n  classNames?: Partial<Record<SenderSemanticType, string>>;\n  styles?: Partial<Record<SenderSemanticType, React.CSSProperties>>;\n  rootClassName?: string;\n  style?: React.CSSProperties;\n  className?: string;\n  allowSpeech?: any;\n  prefix?: BaseNode | NodeRender;\n  footer?: BaseNode | NodeRender;\n  suffix?: BaseNode | NodeRender;\n  header?: BaseNode | NodeRender;\n  autoSize?: boolean | { minRows?: number; maxRows?: number };\n  slotConfig?: Readonly<any[]>;\n  skill?: any;\n}\n\n// ==================== Prompts ====================\n\nexport interface BasePromptsItemType {\n  key: string;\n  icon?: React.ReactNode;\n  label?: React.ReactNode;\n  description?: React.ReactNode;\n  disabled?: boolean;\n}\n\nexport interface PromptsItemType extends BasePromptsItemType {\n  children?: BasePromptsItemType[];\n}\n\ntype PromptsSemanticType =\n  | 'root'\n  | 'list'\n  | 'item'\n  | 'itemContent'\n  | 'title'\n  | 'subList'\n  | 'subItem';\n\nexport interface PromptsProps\n  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onClick' | 'title'> {\n  items?: PromptsItemType[];\n  title?: React.ReactNode;\n  onClick?: (info: { data: PromptsItemType }) => void;\n  styles?: Partial<Record<PromptsSemanticType, React.CSSProperties>>;\n  classNames?: Partial<Record<PromptsSemanticType, string>>;\n  prefixCls?: string;\n  rootClassName?: string;\n  vertical?: boolean;\n  wrap?: boolean;\n}\n\n// ==================== Attachments ====================\n\nexport interface Attachment<T = any>\n  extends UploadFile<T> {\n  description?: React.ReactNode;\n  cardType?: 'audio' | 'video' | 'image' | 'file';\n}\n\nexport interface AttachmentsRef {\n  nativeElement?: HTMLDivElement | null;\n  fileNativeElement?: HTMLInputElement | null;\n  upload: (file: File) => void;\n  select: (options?: { accept?: string; multiple?: boolean }) => void;\n}\n\n// ==================== Think ====================\n\ntype ThinkSemanticType = 'root' | 'header' | 'content' | 'icon';\n\nexport interface ThinkProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {\n  prefixCls?: string;\n  style?: React.CSSProperties;\n  styles?: Partial<Record<ThinkSemanticType, React.CSSProperties>>;\n  className?: string;\n  classNames?: Partial<Record<ThinkSemanticType, string>>;\n  rootClassName?: string;\n  title?: React.ReactNode;\n  icon?: React.ReactNode;\n  loading?: boolean | React.ReactNode;\n  defaultExpanded?: boolean;\n  expanded?: boolean;\n  onExpand?: (expand: boolean) => void;\n  blink?: boolean;\n  destroyOnHidden?: boolean;\n}\n"],
+  "sourcesContent": ["/**\n * @ant-design/x 类型本地声明\n * 从 @ant-design/x 源码提取的公共 API 类型，减少外部依赖\n */\nimport type React from 'react';\nimport type { UploadFile, MenuProps, InputProps } from 'antd';\n\n// ==================== Conversations ====================\n\nexport interface ConversationItemType\n  extends Omit<React.HTMLAttributes<HTMLLIElement>, 'onClick'> {\n  key: string;\n  label?: React.ReactNode;\n  group?: string;\n  icon?: React.ReactNode;\n  disabled?: boolean;\n  [key: string]: any;\n}\n\nexport interface DividerItemType {\n  type: 'divider';\n  key?: string;\n  dashed?: boolean;\n}\n\nexport type ItemType = ConversationItemType | DividerItemType;\n\ntype ConversationsSemanticType = 'root' | 'creation' | 'group' | 'item';\n\nexport interface ConversationsProps extends React.HTMLAttributes<HTMLUListElement> {\n  items?: ItemType[];\n  activeKey?: ConversationItemType['key'];\n  defaultActiveKey?: ConversationItemType['key'];\n  onActiveChange?: (value: ConversationItemType['key'], item?: ItemType) => void;\n  menu?:\n    | (MenuProps & {\n        trigger?:\n          | React.ReactNode\n          | ((\n              conversation: ConversationItemType,\n              info: { originNode: React.ReactNode },\n            ) => React.ReactNode);\n        getPopupContainer?: (triggerNode: HTMLElement) => HTMLElement;\n      })\n    | ((\n        value: ConversationItemType,\n      ) => MenuProps & {\n        trigger?:\n          | React.ReactNode\n          | ((\n              conversation: ConversationItemType,\n              info: { originNode: React.ReactNode },\n            ) => React.ReactNode);\n        getPopupContainer?: (triggerNode: HTMLElement) => HTMLElement;\n      });\n  groupable?: boolean | Record<string, any>;\n  styles?: Partial<Record<ConversationsSemanticType, React.CSSProperties>>;\n  classNames?: Partial<Record<ConversationsSemanticType, string>>;\n  prefixCls?: string;\n  rootClassName?: string;\n}\n\n// ==================== Sender ====================\n\ntype TextareaProps = InputProps;\n\ntype SubmitType = 'enter' | 'shiftEnter';\n\ntype SenderSemanticType = 'root' | 'prefix' | 'input' | 'suffix' | 'footer' | 'switch' | 'content';\n\nexport interface SenderComponents {\n  input?: React.ComponentType<any>;\n}\n\nexport type ActionsComponents = {\n  SendButton: React.ComponentType<any>;\n  ClearButton: React.ComponentType<any>;\n  LoadingButton: React.ComponentType<any>;\n  SpeechButton: React.ComponentType<any>;\n};\n\nexport type BaseNode = React.ReactNode | false;\nexport type NodeRender = (\n  oriNode: React.ReactNode,\n  info: { components: ActionsComponents },\n) => BaseNode;\n\nexport interface SenderProps\n  extends Omit<Partial<Pick<TextareaProps, 'placeholder' | 'onKeyUp' | 'onFocus' | 'onBlur'>>, 'onKeyUp' | 'onFocus' | 'onBlur'> {\n  onKeyUp?: React.KeyboardEventHandler<HTMLTextAreaElement>;\n  onFocus?: React.FocusEventHandler<HTMLTextAreaElement>;\n  onBlur?: React.FocusEventHandler<HTMLTextAreaElement>;\n  prefixCls?: string;\n  defaultValue?: string;\n  value?: string;\n  loading?: boolean;\n  readOnly?: boolean;\n  submitType?: SubmitType;\n  disabled?: boolean;\n  onSubmit?: (message: string, ...args: any[]) => void;\n  onChange?: (value: string, ...args: any[]) => void;\n  onCancel?: VoidFunction;\n  onKeyDown?: (event: React.KeyboardEvent) => void | false;\n  onPaste?: React.ClipboardEventHandler<HTMLElement>;\n  onPasteFile?: (files: FileList) => void;\n  components?: SenderComponents;\n  classNames?: Partial<Record<SenderSemanticType, string>>;\n  styles?: Partial<Record<SenderSemanticType, React.CSSProperties>>;\n  rootClassName?: string;\n  style?: React.CSSProperties;\n  className?: string;\n  allowSpeech?: any;\n  prefix?: BaseNode | NodeRender;\n  footer?: BaseNode | NodeRender;\n  suffix?: BaseNode | NodeRender;\n  header?: BaseNode | NodeRender;\n  autoSize?: boolean | { minRows?: number; maxRows?: number };\n  slotConfig?: Readonly<any[]>;\n  skill?: any;\n}\n\n// ==================== Prompts ====================\n\nexport interface BasePromptsItemType {\n  key: string;\n  icon?: React.ReactNode;\n  label?: React.ReactNode;\n  description?: React.ReactNode;\n  disabled?: boolean;\n}\n\nexport interface PromptsItemType extends BasePromptsItemType {\n  children?: BasePromptsItemType[];\n}\n\ntype PromptsSemanticType =\n  | 'root'\n  | 'list'\n  | 'item'\n  | 'itemContent'\n  | 'title'\n  | 'subList'\n  | 'subItem';\n\nexport interface PromptsProps\n  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onClick' | 'title'> {\n  items?: PromptsItemType[];\n  title?: React.ReactNode;\n  onClick?: (info: { data: PromptsItemType }) => void;\n  styles?: Partial<Record<PromptsSemanticType, React.CSSProperties>>;\n  classNames?: Partial<Record<PromptsSemanticType, string>>;\n  prefixCls?: string;\n  rootClassName?: string;\n  vertical?: boolean;\n  wrap?: boolean;\n}\n\n// ==================== Attachments ====================\n\nexport interface Attachment<T = any>\n  extends UploadFile<T> {\n  description?: React.ReactNode;\n  cardType?: 'audio' | 'video' | 'image' | 'file';\n}\n\nexport interface AttachmentsRef {\n  nativeElement?: HTMLDivElement | null;\n  fileNativeElement?: HTMLInputElement | null;\n  upload: (file: File) => void;\n  select: (options?: { accept?: string; multiple?: boolean }) => void;\n}\n\n// ==================== Think ====================\n\ntype ThinkSemanticType = 'root' | 'header' | 'content' | 'icon';\n\nexport interface ThinkProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {\n  prefixCls?: string;\n  style?: React.CSSProperties;\n  styles?: Partial<Record<ThinkSemanticType, React.CSSProperties>>;\n  className?: string;\n  classNames?: Partial<Record<ThinkSemanticType, string>>;\n  rootClassName?: string;\n  title?: React.ReactNode;\n  icon?: React.ReactNode;\n  loading?: boolean | React.ReactNode;\n  defaultExpanded?: boolean;\n  expanded?: boolean;\n  onExpand?: (expand: boolean) => void;\n  blink?: boolean;\n  destroyOnHidden?: boolean;\n}\n"],
   "mappings": ";;;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

package/dist/esm/components/XAdkChatbot/index.js

@@ -1,6 +1,6 @@
 import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
-import { useMemo, useCallback, useEffect, useRef, useImperativeHandle, forwardRef } from "react";
+import { useMemo, useCallback, useEffect, useLayoutEffect, useRef, useImperativeHandle, forwardRef, Fragment } from "react";
 import { Button, Flex, Tooltip, message as antdMessage } from "antd";
 import clsx from "clsx";
 import { SwapRightOutlined, ReloadOutlined, CopyOutlined, InfoCircleOutlined } from "@ant-design/icons";
@@ -30,12 +30,16 @@ var scrollThreshold = 10;
  * - ✅ 欢迎页面 (agentName/agentIcon/description)
  */
 var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
-  var _mergedStrategies$par;
+  var _mergedStrategies$par, _history$direction;
   var _ref$loading = _ref.loading,
     loading = _ref$loading === void 0 ? false : _ref$loading,
     prologue = _ref.prologue,
     suggestions = _ref.suggestions,
     messages = _ref.messages,
+    renderBeforeGroup = _ref.renderBeforeGroup,
+    renderAfterGroup = _ref.renderAfterGroup,
+    renderGroup = _ref.renderGroup,
+    history = _ref.history,
     showFnCallDetail = _ref.showFnCallDetail,
     onConfirm = _ref.onConfirm,
     onSuggest = _ref.onSuggest,
@@ -76,6 +80,98 @@ var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var prevInitializedRef = useRef(false);
   var prevSessionIdRef = useRef(sessionId);
   var previousMessageCountRef = useRef(messages.length);
+  var historyRef = useRef(history);
+  historyRef.current = history;
+  var messagesRef = useRef(messages);
+  messagesRef.current = messages;
+  var historyRequestRef = useRef(false);
+  var historyRequestIdRef = useRef(0);
+  var historyRequestControllerRef = useRef(null);
+  var historyRefreshRef = useRef(false);
+  var historyRefreshIdRef = useRef(0);
+  var historyRefreshControllerRef = useRef(null);
+  var prependAnchorRef = useRef(null);
+  var skipNextAutoScrollRef = useRef(false);
+  var prependExpiryRef = useRef(null);
+  var loadMoreHistory = useCallback(function () {
+    var _pagination$direction;
+    var pagination = historyRef.current;
+    var el = listRef.current;
+    if (!(pagination !== null && pagination !== void 0 && pagination.hasMore) || pagination.loading || historyRequestRef.current || !el) return;
+    var direction = (_pagination$direction = pagination.direction) !== null && _pagination$direction !== void 0 ? _pagination$direction : "top";
+    if (direction === "top") {
+      var _currentMessages$;
+      if (prependExpiryRef.current) clearTimeout(prependExpiryRef.current);
+      var currentMessages = messagesRef.current;
+      prependAnchorRef.current = {
+        sessionId: prevSessionIdRef.current,
+        firstMessageId: (_currentMessages$ = currentMessages[0]) === null || _currentMessages$ === void 0 ? void 0 : _currentMessages$.id,
+        messageCount: currentMessages.length,
+        scrollTop: el.scrollTop,
+        scrollHeight: el.scrollHeight
+      };
+    }
+    historyRequestRef.current = true;
+    var requestId = ++historyRequestIdRef.current;
+    var controller = new AbortController();
+    historyRequestControllerRef.current = controller;
+    void Promise.resolve().then(function () {
+      return pagination.onLoadMore({
+        signal: controller.signal
+      });
+    }).catch(function () {
+      if (requestId !== historyRequestIdRef.current || controller.signal.aborted) return;
+      prependAnchorRef.current = null;
+      antdMessage.error("加载历史消息失败，请重试");
+    }).finally(function () {
+      if (requestId === historyRequestIdRef.current) {
+        historyRequestRef.current = false;
+        historyRequestControllerRef.current = null;
+        // 没有新页时解除滚动锚点，避免后续正常消息被误认为 prepend。
+        prependExpiryRef.current = setTimeout(function () {
+          prependAnchorRef.current = null;
+          prependExpiryRef.current = null;
+        }, 500);
+      }
+    });
+  }, []);
+  var refreshHistory = useCallback(function () {
+    var pagination = historyRef.current;
+    if (!(pagination !== null && pagination !== void 0 && pagination.onRefresh) || pagination.refreshing || historyRefreshRef.current) return;
+    historyRefreshRef.current = true;
+    var requestId = ++historyRefreshIdRef.current;
+    var controller = new AbortController();
+    historyRefreshControllerRef.current = controller;
+    void Promise.resolve().then(function () {
+      var _pagination$onRefresh;
+      return (_pagination$onRefresh = pagination.onRefresh) === null || _pagination$onRefresh === void 0 ? void 0 : _pagination$onRefresh.call(pagination, {
+        signal: controller.signal
+      });
+    }).catch(function () {
+      if (!controller.signal.aborted) antdMessage.error("刷新历史消息失败，请重试");
+    }).finally(function () {
+      if (requestId === historyRefreshIdRef.current) {
+        historyRefreshRef.current = false;
+        historyRefreshControllerRef.current = null;
+      }
+    });
+  }, []);
+  useLayoutEffect(function () {
+    var _messages$;
+    var anchor = prependAnchorRef.current;
+    var el = listRef.current;
+    if (!anchor || !el) return;
+    if (anchor.sessionId !== sessionId) {
+      prependAnchorRef.current = null;
+      return;
+    }
+    if (messages.length <= anchor.messageCount || ((_messages$ = messages[0]) === null || _messages$ === void 0 ? void 0 : _messages$.id) === anchor.firstMessageId) return;
+    el.scrollTop = anchor.scrollTop + el.scrollHeight - anchor.scrollHeight;
+    skipNextAutoScrollRef.current = true;
+    prependAnchorRef.current = null;
+    if (prependExpiryRef.current) clearTimeout(prependExpiryRef.current);
+    prependExpiryRef.current = null;
+  }, [messages, sessionId]);
 
   // 暴露命令式 API
   var scrollToBottom = useCallback(function () {
@@ -174,18 +270,40 @@ var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
 
   // 会话切换时重置滚动状态，允许重新触发初始化置底
   useEffect(function () {
+    var _historyRequestContro, _historyRefreshContro;
     if (sessionId === undefined) return; // 未传 sessionId 不处理
     if (prevSessionIdRef.current === sessionId) return; // 同一会话不处理
     prevSessionIdRef.current = sessionId;
     prevInitializedRef.current = false;
     userHasScrolledRef.current = false;
+    (_historyRequestContro = historyRequestControllerRef.current) === null || _historyRequestContro === void 0 || _historyRequestContro.abort();
+    (_historyRefreshContro = historyRefreshControllerRef.current) === null || _historyRefreshContro === void 0 || _historyRefreshContro.abort();
+    prependAnchorRef.current = null;
+    historyRequestRef.current = false;
+    historyRequestIdRef.current += 1;
+    historyRefreshRef.current = false;
+    historyRefreshIdRef.current += 1;
+    if (prependExpiryRef.current) clearTimeout(prependExpiryRef.current);
+    prependExpiryRef.current = null;
   }, [sessionId]);
+  useEffect(function () {
+    return function () {
+      var _historyRequestContro2, _historyRefreshContro2;
+      (_historyRequestContro2 = historyRequestControllerRef.current) === null || _historyRequestContro2 === void 0 || _historyRequestContro2.abort();
+      (_historyRefreshContro2 = historyRefreshControllerRef.current) === null || _historyRefreshContro2 === void 0 || _historyRefreshContro2.abort();
+      if (prependExpiryRef.current) clearTimeout(prependExpiryRef.current);
+    };
+  }, []);
 
   // 新增用户消息代表一次主动发送，应无条件恢复跟随并置底。
   // 之后的流式回复继续沿用“用户未主动上滚时跟随”的规则。
   useEffect(function () {
     var previousCount = previousMessageCountRef.current;
     previousMessageCountRef.current = messages.length;
+    if (skipNextAutoScrollRef.current || prependAnchorRef.current) {
+      skipNextAutoScrollRef.current = false;
+      return;
+    }
     var hasNewUserMessage = messages.slice(previousCount).some(function (message) {
       return message.role === "user";
     });
@@ -234,8 +352,15 @@ var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
     if (isAtBottom) {
       userHasScrolledRef.current = false;
     }
+    var pagination = historyRef.current;
+    if (pagination !== null && pagination !== void 0 && pagination.hasMore) {
+      var _pagination$threshold, _pagination$direction2;
+      var threshold = (_pagination$threshold = pagination.threshold) !== null && _pagination$threshold !== void 0 ? _pagination$threshold : 80;
+      var atLoadEdge = ((_pagination$direction2 = pagination.direction) !== null && _pagination$direction2 !== void 0 ? _pagination$direction2 : "top") === "top" ? currentTop <= threshold : el.scrollHeight - currentTop - el.clientHeight <= threshold;
+      if (atLoadEdge) loadMoreHistory();
+    }
     lastScrollTopRef.current = currentTop;
-  }, []);
+  }, [loadMoreHistory]);
   useEffect(function () {
     var listElement = listRef.current;
     if (!listElement) return;
@@ -245,6 +370,13 @@ var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
     };
   }, [handleScroll]);
 
+  // 首屏内容不足一屏时没有滚动事件，继续按需加载直到内容可滚动或数据耗尽。
+  useEffect(function () {
+    if (!initialized || !(history !== null && history !== void 0 && history.hasMore) || history.loading) return;
+    var el = listRef.current;
+    if (el && el.scrollHeight <= el.clientHeight + 1) loadMoreHistory();
+  }, [history === null || history === void 0 ? void 0 : history.hasMore, history === null || history === void 0 ? void 0 : history.loading, initialized, loadMoreHistory, messages]);
+
   // ========== 消息分组逻辑 ==========
   var chatGroups = useMemo(function () {
     if (!enableGrouping) {
@@ -570,12 +702,25 @@ var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
   }, [enableProcessParsing, parseOptions, parseProcessMessage, showFnCallDetail, onConfirm, loading, showRetry, showCopy, showLog, onRetry, onCopy, onShowLog, actions, actionsExtra, onFileClick, onResourceLinkClick, renderResourceLink, mergedMarkdownExtensions, resourceLinkSchemes, styles, resolveToolKind, mergedStrategies]);
 
   // ========== 渲染用户消息组 ==========
-  var renderUserGroup = useCallback(function (group) {
-    return /*#__PURE__*/_jsx("div", {
+  var renderUserGroup = useCallback(function (group, nextGroup) {
+    var _userActions, _group$msgs;
+    var compactWithNextText = group.msgs.some(function (message) {
+      var _message$fileData;
+      return Boolean((_message$fileData = message.fileData) === null || _message$fileData === void 0 ? void 0 : _message$fileData.length);
+    }) && group.msgs.every(function (message) {
+      var _message$text;
+      return !((_message$text = message.text) !== null && _message$text !== void 0 && _message$text.trim());
+    }) && (nextGroup === null || nextGroup === void 0 ? void 0 : nextGroup.role) === "user" && nextGroup.msgs.some(function (message) {
+      var _message$text2;
+      return Boolean((_message$text2 = message.text) === null || _message$text2 === void 0 ? void 0 : _message$text2.trim());
+    });
+    return /*#__PURE__*/_jsxs("div", {
       className: styles.userMsg,
       "data-message-id": group.id,
-      children: group.msgs.map(function (m, i) {
-        var _userActions;
+      style: compactWithNextText ? {
+        marginBottom: 8
+      } : undefined,
+      children: [group.msgs.map(function (m, i) {
         return /*#__PURE__*/_jsxs("div", {
           className: styles.userContainer,
           children: [m.fileData && m.fileData.length > 0 && /*#__PURE__*/_jsx(_Fragment, {
@@ -584,7 +729,7 @@ var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
                 file: file,
                 align: "left",
                 style: {
-                  marginBottom: "16px"
+                  marginBottom: compactWithNextText && i === group.msgs.length - 1 && index === m.fileData.length - 1 ? 0 : 16
                 },
                 onClick: onFileClick
               }, index);
@@ -611,30 +756,36 @@ var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
               renderResourceLink: renderResourceLink,
               markdownExtensions: mergedMarkdownExtensions
             })
-          }), showUserActions && /*#__PURE__*/_jsx("div", {
-            className: "x-user-actions ".concat(styles.userActions),
-            children: (_userActions = userActions === null || userActions === void 0 ? void 0 : userActions({
-              message: group
-            })) !== null && _userActions !== void 0 ? _userActions : /*#__PURE__*/_jsxs(_Fragment, {
-              children: [/*#__PURE__*/_jsx("span", {
-                className: styles.userTime,
-                children: formatTimestamp(m.timestamp)
-              }), /*#__PURE__*/_jsx(Tooltip, {
-                title: "\u590D\u5236\u5185\u5BB9",
-                children: /*#__PURE__*/_jsx(CopyOutlined, {
-                  className: styles.userActionIcon,
-                  onClick: function onClick() {
-                    var card = document.querySelector("[data-message-id=\"".concat(group.id, "\"] [data-xadk-user-card]"));
-                    var selected = getSelectionText(card);
-                    copy(selected || m.text || "");
-                    antdMessage.success("复制成功");
-                  }
-                })
-              })]
-            })
           })]
         }, m.id || i);
-      })
+      }), showUserActions && group.msgs.some(function (message) {
+        var _message$text3;
+        return Boolean((_message$text3 = message.text) === null || _message$text3 === void 0 ? void 0 : _message$text3.trim());
+      }) && /*#__PURE__*/_jsx("div", {
+        className: "x-user-actions ".concat(styles.userActions),
+        children: (_userActions = userActions === null || userActions === void 0 ? void 0 : userActions({
+          message: group
+        })) !== null && _userActions !== void 0 ? _userActions : /*#__PURE__*/_jsxs(_Fragment, {
+          children: [/*#__PURE__*/_jsx("span", {
+            className: styles.userTime,
+            children: formatTimestamp((_group$msgs = group.msgs[group.msgs.length - 1]) === null || _group$msgs === void 0 ? void 0 : _group$msgs.timestamp)
+          }), /*#__PURE__*/_jsx(Tooltip, {
+            title: "\u590D\u5236\u5185\u5BB9",
+            children: /*#__PURE__*/_jsx(CopyOutlined, {
+              className: styles.userActionIcon,
+              onClick: function onClick() {
+                var container = document.querySelector("[data-message-id=\"".concat(group.id, "\"]"));
+                var selected = getSelectionText(container);
+                var fullText = group.msgs.map(function (message) {
+                  return message.text || "";
+                }).join("");
+                copy(selected || fullText);
+                antdMessage.success("复制成功");
+              }
+            })
+          })]
+        })
+      })]
     }, group.id);
   }, [styles, onFileClick, onResourceLinkClick, renderResourceLink, mergedMarkdownExtensions, resourceLinkSchemes, showUserActions, userActions]);
 
@@ -676,6 +827,20 @@ var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
 
   // 空状态判断
   var isEmpty = messages.length === 0 && !prologue && (!suggestions || suggestions.length === 0);
+  var historyControls = history && (history.hasMore || history.loading || history.onRefresh) && /*#__PURE__*/_jsxs("div", {
+    className: styles.historyControls,
+    children: [history.onRefresh && /*#__PURE__*/_jsx("button", {
+      type: "button",
+      onClick: refreshHistory,
+      disabled: history.refreshing,
+      children: history.refreshing ? "正在刷新..." : "刷新"
+    }), (history.hasMore || history.loading) && /*#__PURE__*/_jsx("button", {
+      type: "button",
+      onClick: loadMoreHistory,
+      disabled: history.loading,
+      children: history.loading ? "正在加载..." : "加载更多"
+    })]
+  });
   return /*#__PURE__*/_jsxs("div", {
     className: clsx(styles.wrapper, className),
     style: style,
@@ -688,7 +853,7 @@ var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
       style: isEmpty ? {
         flex: 0
       } : undefined,
-      children: [prologue && /*#__PURE__*/_jsx("div", {
+      children: [((_history$direction = history === null || history === void 0 ? void 0 : history.direction) !== null && _history$direction !== void 0 ? _history$direction : "top") === "top" && historyControls, prologue && /*#__PURE__*/_jsx("div", {
         className: styles.prologue,
         children: /*#__PURE__*/_jsx(MarkdownRender, {
           text: prologue,
@@ -699,8 +864,20 @@ var XAdkChatbot = /*#__PURE__*/forwardRef(function (_ref, ref) {
           markdownExtensions: mergedMarkdownExtensions
         })
       }), chatGroups.map(function (group, idx) {
-        return group.role === "user" ? renderUserGroup(group) : renderBotGroup(group, idx === chatGroups.length - 1, renderFunctionCall);
-      }), renderSuggestions(), /*#__PURE__*/_jsx("div", {
+        var context = {
+          group: group,
+          index: idx,
+          previousGroup: chatGroups[idx - 1],
+          nextGroup: chatGroups[idx + 1]
+        };
+        var defaultNode = group.role === "user" ? renderUserGroup(group, chatGroups[idx + 1]) : renderBotGroup(group, idx === chatGroups.length - 1, renderFunctionCall);
+        var customNode = renderGroup === null || renderGroup === void 0 ? void 0 : renderGroup(_objectSpread(_objectSpread({}, context), {}, {
+          defaultNode: defaultNode
+        }));
+        return /*#__PURE__*/_jsxs(Fragment, {
+          children: [renderBeforeGroup === null || renderBeforeGroup === void 0 ? void 0 : renderBeforeGroup(context), customNode === undefined ? defaultNode : customNode, renderAfterGroup === null || renderAfterGroup === void 0 ? void 0 : renderAfterGroup(context)]
+        }, group.id);
+      }), (history === null || history === void 0 ? void 0 : history.direction) === "bottom" && historyControls, renderSuggestions(), /*#__PURE__*/_jsx("div", {
         ref: messagesEndRef
       })]
     })]