@ai-group/chat-sdk 3.7.5 → 3.8.0-alpha.2

package/dist/cjs/hooks/useADKMessageQueue.js

@@ -0,0 +1,107 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hooks/useADKMessageQueue.ts
+var useADKMessageQueue_exports = {};
+__export(useADKMessageQueue_exports, {
+  useADKMessageQueue: () => useADKMessageQueue
+});
+module.exports = __toCommonJS(useADKMessageQueue_exports);
+var import_react = require("react");
+var import_uuid = require("uuid");
+function useADKMessageQueue({
+  sessionId,
+  loading,
+  send,
+  stop,
+  interrupt,
+  enabled = true,
+  drainInactiveSessions = false
+}) {
+  const [queuedMessages, setQueuedMessages] = (0, import_react.useState)([]);
+  const [interrupting, setInterrupting] = (0, import_react.useState)(false);
+  const [drainTick, setDrainTick] = (0, import_react.useState)(0);
+  const queueRef = (0, import_react.useRef)(queuedMessages);
+  const busySessionsRef = (0, import_react.useRef)(/* @__PURE__ */ new Set());
+  const loadingRef = (0, import_react.useRef)(loading);
+  const interruptingRef = (0, import_react.useRef)(false);
+  const callbacksRef = (0, import_react.useRef)({ send, stop, interrupt });
+  callbacksRef.current = { send, stop, interrupt };
+  loadingRef.current = loading;
+  const updateQueue = (0, import_react.useCallback)((update) => {
+    const next = update(queueRef.current);
+    queueRef.current = next;
+    setQueuedMessages(next);
+  }, []);
+  const sendNext = (0, import_react.useCallback)((item) => {
+    busySessionsRef.current.add(item.sessionId);
+    updateQueue((current) => current.filter((queued) => queued.id !== item.id));
+    void Promise.resolve().then(() => callbacksRef.current.send(item.payload, item.sessionId)).catch(() => {
+    }).finally(() => {
+      busySessionsRef.current.delete(item.sessionId);
+      setDrainTick((tick) => tick + 1);
+    });
+  }, [updateQueue]);
+  const sendOrQueue = (0, import_react.useCallback)((payload, preview = "") => {
+    if (!sessionId || !enabled)
+      return;
+    const item = { id: (0, import_uuid.v4)(), sessionId, preview, payload };
+    if (loadingRef.current || busySessionsRef.current.has(sessionId) || interruptingRef.current || queueRef.current.some((queued) => queued.sessionId === sessionId)) {
+      updateQueue((current) => [...current, item]);
+    } else {
+      sendNext(item);
+    }
+  }, [enabled, sessionId, sendNext, updateQueue]);
+  const removeQueuedMessage = (0, import_react.useCallback)((id) => {
+    updateQueue((current) => current.filter((item) => item.id !== id));
+  }, [updateQueue]);
+  const sendQueuedMessageNow = (0, import_react.useCallback)(async (id) => {
+    var _a, _b;
+    const selected = queueRef.current.find((item) => item.id === id && item.sessionId === sessionId);
+    if (!selected || interruptingRef.current)
+      return;
+    interruptingRef.current = true;
+    setInterrupting(true);
+    updateQueue((current) => [selected, ...current.filter((item) => item.id !== id)]);
+    try {
+      await ((_b = (_a = callbacksRef.current).interrupt) == null ? void 0 : _b.call(_a, sessionId));
+      if (loadingRef.current || busySessionsRef.current.has(sessionId))
+        callbacksRef.current.stop();
+    } catch {
+    } finally {
+      interruptingRef.current = false;
+      setInterrupting(false);
+      setDrainTick((tick) => tick + 1);
+    }
+  }, [sessionId, updateQueue]);
+  (0, import_react.useEffect)(() => {
+    if (!enabled || interruptingRef.current)
+      return;
+    const next = queueRef.current.find(
+      (item) => (drainInactiveSessions || item.sessionId === sessionId) && !busySessionsRef.current.has(item.sessionId) && !(item.sessionId === sessionId && loading)
+    );
+    if (next)
+      sendNext(next);
+  }, [drainInactiveSessions, drainTick, enabled, loading, queuedMessages, sendNext, sessionId]);
+  return { queuedMessages, interrupting, sendOrQueue, removeQueuedMessage, sendQueuedMessageNow };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useADKMessageQueue
+});
+//# sourceMappingURL=useADKMessageQueue.js.map

package/dist/cjs/hooks/useADKMessageQueue.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/hooks/useADKMessageQueue.ts"],
+  "sourcesContent": ["import { useCallback, useEffect, useRef, useState } from \"react\";\nimport { v4 } from \"uuid\";\n\nexport interface ADKQueuedMessage<T> {\n  id: string;\n  sessionId: string;\n  preview: string;\n  payload: T;\n}\n\nexport interface ADKMessageQueueOptions<T> {\n  sessionId: string;\n  loading: boolean;\n  send: (payload: T, sessionId: string) => Promise<unknown> | void;\n  stop: () => void;\n  interrupt?: (sessionId: string) => Promise<unknown> | void;\n  enabled?: boolean;\n  /** 允许离开会话后继续发送该会话的待发送消息。 */\n  drainInactiveSessions?: boolean;\n}\n\n/** 会话级发送队列；只缓存请求，不负责业务 UI 或打断接口的具体实现。 */\nexport function useADKMessageQueue<T>({\n  sessionId,\n  loading,\n  send,\n  stop,\n  interrupt,\n  enabled = true,\n  drainInactiveSessions = false,\n}: ADKMessageQueueOptions<T>) {\n  const [queuedMessages, setQueuedMessages] = useState<ADKQueuedMessage<T>[]>([]);\n  const [interrupting, setInterrupting] = useState(false);\n  const [drainTick, setDrainTick] = useState(0);\n  const queueRef = useRef(queuedMessages);\n  const busySessionsRef = useRef(new Set<string>());\n  const loadingRef = useRef(loading);\n  const interruptingRef = useRef(false);\n  const callbacksRef = useRef({ send, stop, interrupt });\n  callbacksRef.current = { send, stop, interrupt };\n  loadingRef.current = loading;\n\n  const updateQueue = useCallback((update: (current: ADKQueuedMessage<T>[]) => ADKQueuedMessage<T>[]) => {\n    const next = update(queueRef.current);\n    queueRef.current = next;\n    setQueuedMessages(next);\n  }, []);\n\n  const sendNext = useCallback((item: ADKQueuedMessage<T>) => {\n    busySessionsRef.current.add(item.sessionId);\n    updateQueue((current) => current.filter((queued) => queued.id !== item.id));\n    void Promise.resolve()\n      .then(() => callbacksRef.current.send(item.payload, item.sessionId))\n      .catch(() => {\n        // 发送错误由 transport 处理；队列仍需继续释放当前项。\n      })\n      .finally(() => {\n        busySessionsRef.current.delete(item.sessionId);\n        setDrainTick((tick) => tick + 1);\n      });\n  }, [updateQueue]);\n\n  const sendOrQueue = useCallback((payload: T, preview = \"\") => {\n    if (!sessionId || !enabled) return;\n    const item = { id: v4(), sessionId, preview, payload };\n    if (loadingRef.current || busySessionsRef.current.has(sessionId) || interruptingRef.current || queueRef.current.some((queued) => queued.sessionId === sessionId)) {\n      updateQueue((current) => [...current, item]);\n    } else {\n      sendNext(item);\n    }\n  }, [enabled, sessionId, sendNext, updateQueue]);\n\n  const removeQueuedMessage = useCallback((id: string) => {\n    updateQueue((current) => current.filter((item) => item.id !== id));\n  }, [updateQueue]);\n\n  const sendQueuedMessageNow = useCallback(async (id: string) => {\n    const selected = queueRef.current.find((item) => item.id === id && item.sessionId === sessionId);\n    if (!selected || interruptingRef.current) return;\n    interruptingRef.current = true;\n    setInterrupting(true);\n    updateQueue((current) => [selected, ...current.filter((item) => item.id !== id)]);\n    try {\n      await callbacksRef.current.interrupt?.(sessionId);\n      if (loadingRef.current || busySessionsRef.current.has(sessionId)) callbacksRef.current.stop();\n    } catch {\n      // 中断失败时维持当前回复；选中的消息仍留在队首等待正常完成。\n    } finally {\n      interruptingRef.current = false;\n      setInterrupting(false);\n      setDrainTick((tick) => tick + 1);\n    }\n  }, [sessionId, updateQueue]);\n\n  useEffect(() => {\n    if (!enabled || interruptingRef.current) return;\n    const next = queueRef.current.find(\n      (item) =>\n        (drainInactiveSessions || item.sessionId === sessionId) &&\n        !busySessionsRef.current.has(item.sessionId) &&\n        !(item.sessionId === sessionId && loading)\n    );\n    if (next) sendNext(next);\n  }, [drainInactiveSessions, drainTick, enabled, loading, queuedMessages, sendNext, sessionId]);\n\n  return { queuedMessages, interrupting, sendOrQueue, removeQueuedMessage, sendQueuedMessageNow };\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAyD;AACzD,kBAAmB;AAqBZ,SAAS,mBAAsB;AAAA,EACpC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAU;AAAA,EACV,wBAAwB;AAC1B,GAA8B;AAC5B,QAAM,CAAC,gBAAgB,iBAAiB,QAAI,uBAAgC,CAAC,CAAC;AAC9E,QAAM,CAAC,cAAc,eAAe,QAAI,uBAAS,KAAK;AACtD,QAAM,CAAC,WAAW,YAAY,QAAI,uBAAS,CAAC;AAC5C,QAAM,eAAW,qBAAO,cAAc;AACtC,QAAM,sBAAkB,qBAAO,oBAAI,IAAY,CAAC;AAChD,QAAM,iBAAa,qBAAO,OAAO;AACjC,QAAM,sBAAkB,qBAAO,KAAK;AACpC,QAAM,mBAAe,qBAAO,EAAE,MAAM,MAAM,UAAU,CAAC;AACrD,eAAa,UAAU,EAAE,MAAM,MAAM,UAAU;AAC/C,aAAW,UAAU;AAErB,QAAM,kBAAc,0BAAY,CAAC,WAAsE;AACrG,UAAM,OAAO,OAAO,SAAS,OAAO;AACpC,aAAS,UAAU;AACnB,sBAAkB,IAAI;AAAA,EACxB,GAAG,CAAC,CAAC;AAEL,QAAM,eAAW,0BAAY,CAAC,SAA8B;AAC1D,oBAAgB,QAAQ,IAAI,KAAK,SAAS;AAC1C,gBAAY,CAAC,YAAY,QAAQ,OAAO,CAAC,WAAW,OAAO,OAAO,KAAK,EAAE,CAAC;AAC1E,SAAK,QAAQ,QAAQ,EAClB,KAAK,MAAM,aAAa,QAAQ,KAAK,KAAK,SAAS,KAAK,SAAS,CAAC,EAClE,MAAM,MAAM;AAAA,IAEb,CAAC,EACA,QAAQ,MAAM;AACb,sBAAgB,QAAQ,OAAO,KAAK,SAAS;AAC7C,mBAAa,CAAC,SAAS,OAAO,CAAC;AAAA,IACjC,CAAC;AAAA,EACL,GAAG,CAAC,WAAW,CAAC;AAEhB,QAAM,kBAAc,0BAAY,CAAC,SAAY,UAAU,OAAO;AAC5D,QAAI,CAAC,aAAa,CAAC;AAAS;AAC5B,UAAM,OAAO,EAAE,QAAI,gBAAG,GAAG,WAAW,SAAS,QAAQ;AACrD,QAAI,WAAW,WAAW,gBAAgB,QAAQ,IAAI,SAAS,KAAK,gBAAgB,WAAW,SAAS,QAAQ,KAAK,CAAC,WAAW,OAAO,cAAc,SAAS,GAAG;AAChK,kBAAY,CAAC,YAAY,CAAC,GAAG,SAAS,IAAI,CAAC;AAAA,IAC7C,OAAO;AACL,eAAS,IAAI;AAAA,IACf;AAAA,EACF,GAAG,CAAC,SAAS,WAAW,UAAU,WAAW,CAAC;AAE9C,QAAM,0BAAsB,0BAAY,CAAC,OAAe;AACtD,gBAAY,CAAC,YAAY,QAAQ,OAAO,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;AAAA,EACnE,GAAG,CAAC,WAAW,CAAC;AAEhB,QAAM,2BAAuB,0BAAY,OAAO,OAAe;AA5EjE;AA6EI,UAAM,WAAW,SAAS,QAAQ,KAAK,CAAC,SAAS,KAAK,OAAO,MAAM,KAAK,cAAc,SAAS;AAC/F,QAAI,CAAC,YAAY,gBAAgB;AAAS;AAC1C,oBAAgB,UAAU;AAC1B,oBAAgB,IAAI;AACpB,gBAAY,CAAC,YAAY,CAAC,UAAU,GAAG,QAAQ,OAAO,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC,CAAC;AAChF,QAAI;AACF,cAAM,wBAAa,SAAQ,cAArB,4BAAiC;AACvC,UAAI,WAAW,WAAW,gBAAgB,QAAQ,IAAI,SAAS;AAAG,qBAAa,QAAQ,KAAK;AAAA,IAC9F,QAAE;AAAA,IAEF,UAAE;AACA,sBAAgB,UAAU;AAC1B,sBAAgB,KAAK;AACrB,mBAAa,CAAC,SAAS,OAAO,CAAC;AAAA,IACjC;AAAA,EACF,GAAG,CAAC,WAAW,WAAW,CAAC;AAE3B,8BAAU,MAAM;AACd,QAAI,CAAC,WAAW,gBAAgB;AAAS;AACzC,UAAM,OAAO,SAAS,QAAQ;AAAA,MAC5B,CAAC,UACE,yBAAyB,KAAK,cAAc,cAC7C,CAAC,gBAAgB,QAAQ,IAAI,KAAK,SAAS,KAC3C,EAAE,KAAK,cAAc,aAAa;AAAA,IACtC;AACA,QAAI;AAAM,eAAS,IAAI;AAAA,EACzB,GAAG,CAAC,uBAAuB,WAAW,SAAS,SAAS,gBAAgB,UAAU,SAAS,CAAC;AAE5F,SAAO,EAAE,gBAAgB,cAAc,aAAa,qBAAqB,qBAAqB;AAChG;",
+  "names": []
+}

package/dist/cjs/index.d.ts

@@ -13,13 +13,15 @@ import XAdkProvider from "./components/XAdkProvider";
 import XAdkChatbot from "./components/XAdkChatbot";
 import XAdkSender from "./components/XAdkSender";
 import useADKChat from "./hooks/useADKChat";
+import { useADKMessageQueue } from "./hooks/useADKMessageQueue";
 import { baseChatStrategies, basePreset, baseToolKindResolver, BUILTIN_CHAT_PRESETS, composeChatPresets, DEFAULT_CHAT_PRESET_NAME, defineChatPreset, mergeChatStrategies, resolvePresetUploadRequest, resolveChatPreset, resolvePresetMarkdownExtensions } from "./presets";
 import { extractXGroupKnowledgeReferences, parseXGroupKnowledgeReference, xGroupKnowledgeReferenceMarkdownExtension, xGroupMarkdownExtensions, parseXGroupWebReference, xGroupWebReferenceMarkdownExtension, createXGroupUploadRequest, xGroupAdkPreset, xGroupToolKindResolver } from "./presets/xgroup";
 export { useChatState, useChatActions, useSession, } from "./components/XAdkProvider/context";
 export * from "./types";
 export type { ChatHookResult, ChatHookFactory } from "./types/ChatHook";
 export { useXAi, XAiProvider, XAiChatbot, XAiSDK, XAiSender, XAiConversations, useXAiSDK, request, };
-export { XAdkProvider, XAdkChatbot, XAdkSender, FileGallery, XAdkThoughtChain, useADKChat, formatMarkdownResourceLinksAsText, getMarkdownResourceDisplayLabel, parseMarkdownResourceLinksAsParts, parseMarkdownResourceHref, replaceMarkdownResourceLinks, baseChatStrategies, basePreset, baseToolKindResolver, BUILTIN_CHAT_PRESETS, composeChatPresets, DEFAULT_CHAT_PRESET_NAME, defineChatPreset, createXGroupUploadRequest, mergeChatStrategies, resolvePresetUploadRequest, resolveChatPreset, resolvePresetMarkdownExtensions, extractXGroupKnowledgeReferences, parseXGroupKnowledgeReference, xGroupKnowledgeReferenceMarkdownExtension, xGroupMarkdownExtensions, parseXGroupWebReference, xGroupWebReferenceMarkdownExtension, xGroupAdkPreset, xGroupToolKindResolver, };
+export { XAdkProvider, XAdkChatbot, XAdkSender, FileGallery, XAdkThoughtChain, useADKChat, useADKMessageQueue, formatMarkdownResourceLinksAsText, getMarkdownResourceDisplayLabel, parseMarkdownResourceLinksAsParts, parseMarkdownResourceHref, replaceMarkdownResourceLinks, baseChatStrategies, basePreset, baseToolKindResolver, BUILTIN_CHAT_PRESETS, composeChatPresets, DEFAULT_CHAT_PRESET_NAME, defineChatPreset, createXGroupUploadRequest, mergeChatStrategies, resolvePresetUploadRequest, resolveChatPreset, resolvePresetMarkdownExtensions, extractXGroupKnowledgeReferences, parseXGroupKnowledgeReference, xGroupKnowledgeReferenceMarkdownExtension, xGroupMarkdownExtensions, parseXGroupWebReference, xGroupWebReferenceMarkdownExtension, xGroupAdkPreset, xGroupToolKindResolver, };
+export type { ADKQueuedMessage, ADKMessageQueueOptions, } from "./hooks/useADKMessageQueue";
 export type { XGroupKnowledgeReference, XGroupWebReference, } from "./presets/xgroup";
 import Sources from "./components/Sources";
 export { Sources };

package/dist/cjs/index.js

@@ -72,6 +72,7 @@ __export(src_exports, {
   tokenDefaults: () => import_tokens.tokenDefaults,
   tokens: () => import_tokens.tokens,
   useADKChat: () => import_useADKChat.default,
+  useADKMessageQueue: () => import_useADKMessageQueue.useADKMessageQueue,
   useAdkConversation: () => import_useAdkConversation.default,
   useChatActions: () => import_context.useChatActions,
   useChatState: () => import_context.useChatState,
@@ -100,6 +101,7 @@ var import_XAdkProvider = __toESM(require("./components/XAdkProvider"));
 var import_XAdkChatbot = __toESM(require("./components/XAdkChatbot"));
 var import_XAdkSender = __toESM(require("./components/XAdkSender"));
 var import_useADKChat = __toESM(require("./hooks/useADKChat"));
+var import_useADKMessageQueue = require("./hooks/useADKMessageQueue");
 var import_presets = require("./presets");
 var import_xgroup = require("./presets/xgroup");
 var import_context = require("./components/XAdkProvider/context");
@@ -157,6 +159,7 @@ var import_xgroup2 = require("./presets/xgroup");
   tokenDefaults,
   tokens,
   useADKChat,
+  useADKMessageQueue,
   useAdkConversation,
   useChatActions,
   useChatState,

package/dist/cjs/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/index.ts"],
-  "sourcesContent": ["// index.ts\nimport { useXAi } from \"./context/AiProviderContext\";\nimport XAiProvider from \"./components/XAiProvider\";\nimport XAiChatbot from \"./components/XAiChatbot\";\nimport XAiSDK from \"./components/XAiSDK\";\nimport XAiSender from \"./components/XAiSender\";\nimport FileGallery from \"./components/FileGallery\";\nimport XAiConversations from \"./components/XAiConversations\";\nimport XAdkThoughtChain from \"./components/XAdkThoughtChain\";\nimport useXAiSDK from \"./hooks/useXAiSDK\";\nimport request from \"./utils/request\";\nimport {\n  formatMarkdownResourceLinksAsText,\n  getMarkdownResourceDisplayLabel,\n  parseMarkdownResourceLinksAsParts,\n  parseMarkdownResourceHref,\n  replaceMarkdownResourceLinks,\n} from \"./utils/markdownResource\";\n\n// 新的 Compound Components 架构\nimport XAdkProvider from \"./components/XAdkProvider\";\nimport XAdkChatbot from \"./components/XAdkChatbot\";\nimport XAdkSender from \"./components/XAdkSender\";\nimport useADKChat from \"./hooks/useADKChat\";\nimport {\n  baseChatStrategies,\n  basePreset,\n  baseToolKindResolver,\n  BUILTIN_CHAT_PRESETS,\n  composeChatPresets,\n  DEFAULT_CHAT_PRESET_NAME,\n  defineChatPreset,\n  mergeChatStrategies,\n  resolvePresetUploadRequest,\n  resolveChatPreset,\n  resolvePresetMarkdownExtensions,\n} from \"./presets\";\nimport {\n  extractXGroupKnowledgeReferences,\n  parseXGroupKnowledgeReference,\n  xGroupKnowledgeReferenceMarkdownExtension,\n  xGroupMarkdownExtensions,\n  parseXGroupWebReference,\n  xGroupWebReferenceMarkdownExtension,\n  createXGroupUploadRequest,\n  xGroupAdkPreset,\n  xGroupToolKindResolver,\n} from \"./presets/xgroup\";\n\n// 导出新的 Context Hooks\nexport {\n  useChatState,\n  useChatActions,\n  useSession,\n} from \"./components/XAdkProvider/context\";\n\nexport * from \"./types\";\n\n// 导出自定义 Hook 相关类型\nexport type { ChatHookResult, ChatHookFactory } from \"./types/ChatHook\";\n\n// 旧 API - 保持向后兼容\nexport {\n  useXAi,\n  XAiProvider,\n  XAiChatbot,\n  XAiSDK,\n  XAiSender,\n  XAiConversations,\n  useXAiSDK,\n  request,\n};\n\n// 新 API - 推荐使用\nexport {\n  XAdkProvider,\n  XAdkChatbot,\n  XAdkSender,\n  FileGallery,\n  XAdkThoughtChain,\n  useADKChat,\n  formatMarkdownResourceLinksAsText,\n  getMarkdownResourceDisplayLabel,\n  parseMarkdownResourceLinksAsParts,\n  parseMarkdownResourceHref,\n  replaceMarkdownResourceLinks,\n  baseChatStrategies,\n  basePreset,\n  baseToolKindResolver,\n  BUILTIN_CHAT_PRESETS,\n  composeChatPresets,\n  DEFAULT_CHAT_PRESET_NAME,\n  defineChatPreset,\n  createXGroupUploadRequest,\n  mergeChatStrategies,\n  resolvePresetUploadRequest,\n  resolveChatPreset,\n  resolvePresetMarkdownExtensions,\n  extractXGroupKnowledgeReferences,\n  parseXGroupKnowledgeReference,\n  xGroupKnowledgeReferenceMarkdownExtension,\n  xGroupMarkdownExtensions,\n  parseXGroupWebReference,\n  xGroupWebReferenceMarkdownExtension,\n  xGroupAdkPreset,\n  xGroupToolKindResolver,\n};\nexport type {\n  XGroupKnowledgeReference,\n  XGroupWebReference,\n} from \"./presets/xgroup\";\n\n// Sources 来源引用组件\nimport Sources from \"./components/Sources\";\nexport { Sources };\nexport type { SourcesProps, SourcesItem, SourcesRef } from \"./types/Sources\";\n\n// FolderTree 文件树组件\nimport FolderTree from \"./components/FolderTree\";\nexport { FolderTree };\nexport type {\n  FolderTreeProps,\n  FolderTreeData,\n  FileContentService,\n  FolderTreeRef,\n} from \"./components/FolderTree\";\n\n// 基础组件导出 - 供高级用户和业务侧使用\nexport { default as MarkdownRender } from \"./components/XAdkChatbot/components/MarkdownRender\";\nexport { default as FunctionCallRender } from \"./components/XAdkChatbot/components/FunctionCallRender\";\nexport { default as ThinkRender } from \"./components/XAdkChatbot/components/ThinkRender\";\n\n// 基础组件类型导出\nexport type { MarkdownRenderProps } from \"./components/XAdkChatbot/components/MarkdownRender\";\nexport type { FunctionCallRenderProps } from \"./types/FunctionCallRender\";\nexport type {\n  XAdkThoughtChainProps,\n  ThoughtChainItemType,\n  ThoughtChainStatus,\n} from \"./types/XAdkThoughtChain\";\n\n// 设计令牌导出 - 供引用方覆盖样式\nexport { tokens, tokenDefaults, token, cssVarStyle } from \"./styles/tokens\";\n\n// Headless ADK data-flow APIs\nexport * from \"./core\";\nexport { default as useAdkConversation } from \"./react/useAdkConversation\";\nexport type { UseAdkConversationResult } from \"./react/useAdkConversation\";\nexport { createXGroupOpenApiTransport } from \"./presets/xgroup\";\nexport type { XGroupOpenApiTransportOptions } from \"./presets/xgroup\";\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA,wCAAAA;AAAA,EAAA,oCAAAC;AAAA,EAAA;AAAA;AAAA,gCAAAC;AAAA,EAAA;AAAA,wCAAAC;AAAA,EAAA,wCAAAC;AAAA,EAAA,oCAAAC;AAAA,EAAA,gDAAAC;AAAA,EAAA,oCAAAC;AAAA,EAAA,gDAAAC;AAAA,EAAA,sCAAAC;AAAA,EAAA,4BAAAC;AAAA,EAAA,kCAAAC;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gCAAAC;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,sCAAAC;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oCAAAC;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,+BAAuB;AACvB,yBAAwB;AACxB,wBAAuB;AACvB,oBAAmB;AACnB,uBAAsB;AACtB,yBAAwB;AACxB,8BAA6B;AAC7B,8BAA6B;AAC7B,uBAAsB;AACtB,qBAAoB;AACpB,8BAMO;AAGP,0BAAyB;AACzB,yBAAwB;AACxB,wBAAuB;AACvB,wBAAuB;AACvB,qBAYO;AACP,oBAUO;AAGP,qBAIO;AAEP,wBAAc,oBAxDd;AAiHA,qBAAoB;AAKpB,wBAAuB;AAUvB,4BAA0C;AAC1C,gCAA8C;AAC9C,yBAAuC;AAYvC,oBAA0D;AAG1D,wBAAc,mBAjJd;AAkJA,gCAA8C;AAE9C,IAAAC,iBAA6C;",
+  "sourcesContent": ["// index.ts\nimport { useXAi } from \"./context/AiProviderContext\";\nimport XAiProvider from \"./components/XAiProvider\";\nimport XAiChatbot from \"./components/XAiChatbot\";\nimport XAiSDK from \"./components/XAiSDK\";\nimport XAiSender from \"./components/XAiSender\";\nimport FileGallery from \"./components/FileGallery\";\nimport XAiConversations from \"./components/XAiConversations\";\nimport XAdkThoughtChain from \"./components/XAdkThoughtChain\";\nimport useXAiSDK from \"./hooks/useXAiSDK\";\nimport request from \"./utils/request\";\nimport {\n  formatMarkdownResourceLinksAsText,\n  getMarkdownResourceDisplayLabel,\n  parseMarkdownResourceLinksAsParts,\n  parseMarkdownResourceHref,\n  replaceMarkdownResourceLinks,\n} from \"./utils/markdownResource\";\n\n// 新的 Compound Components 架构\nimport XAdkProvider from \"./components/XAdkProvider\";\nimport XAdkChatbot from \"./components/XAdkChatbot\";\nimport XAdkSender from \"./components/XAdkSender\";\nimport useADKChat from \"./hooks/useADKChat\";\nimport { useADKMessageQueue } from \"./hooks/useADKMessageQueue\";\nimport {\n  baseChatStrategies,\n  basePreset,\n  baseToolKindResolver,\n  BUILTIN_CHAT_PRESETS,\n  composeChatPresets,\n  DEFAULT_CHAT_PRESET_NAME,\n  defineChatPreset,\n  mergeChatStrategies,\n  resolvePresetUploadRequest,\n  resolveChatPreset,\n  resolvePresetMarkdownExtensions,\n} from \"./presets\";\nimport {\n  extractXGroupKnowledgeReferences,\n  parseXGroupKnowledgeReference,\n  xGroupKnowledgeReferenceMarkdownExtension,\n  xGroupMarkdownExtensions,\n  parseXGroupWebReference,\n  xGroupWebReferenceMarkdownExtension,\n  createXGroupUploadRequest,\n  xGroupAdkPreset,\n  xGroupToolKindResolver,\n} from \"./presets/xgroup\";\n\n// 导出新的 Context Hooks\nexport {\n  useChatState,\n  useChatActions,\n  useSession,\n} from \"./components/XAdkProvider/context\";\n\nexport * from \"./types\";\n\n// 导出自定义 Hook 相关类型\nexport type { ChatHookResult, ChatHookFactory } from \"./types/ChatHook\";\n\n// 旧 API - 保持向后兼容\nexport {\n  useXAi,\n  XAiProvider,\n  XAiChatbot,\n  XAiSDK,\n  XAiSender,\n  XAiConversations,\n  useXAiSDK,\n  request,\n};\n\n// 新 API - 推荐使用\nexport {\n  XAdkProvider,\n  XAdkChatbot,\n  XAdkSender,\n  FileGallery,\n  XAdkThoughtChain,\n  useADKChat,\n  useADKMessageQueue,\n  formatMarkdownResourceLinksAsText,\n  getMarkdownResourceDisplayLabel,\n  parseMarkdownResourceLinksAsParts,\n  parseMarkdownResourceHref,\n  replaceMarkdownResourceLinks,\n  baseChatStrategies,\n  basePreset,\n  baseToolKindResolver,\n  BUILTIN_CHAT_PRESETS,\n  composeChatPresets,\n  DEFAULT_CHAT_PRESET_NAME,\n  defineChatPreset,\n  createXGroupUploadRequest,\n  mergeChatStrategies,\n  resolvePresetUploadRequest,\n  resolveChatPreset,\n  resolvePresetMarkdownExtensions,\n  extractXGroupKnowledgeReferences,\n  parseXGroupKnowledgeReference,\n  xGroupKnowledgeReferenceMarkdownExtension,\n  xGroupMarkdownExtensions,\n  parseXGroupWebReference,\n  xGroupWebReferenceMarkdownExtension,\n  xGroupAdkPreset,\n  xGroupToolKindResolver,\n};\nexport type {\n  ADKQueuedMessage,\n  ADKMessageQueueOptions,\n} from \"./hooks/useADKMessageQueue\";\nexport type {\n  XGroupKnowledgeReference,\n  XGroupWebReference,\n} from \"./presets/xgroup\";\n\n// Sources 来源引用组件\nimport Sources from \"./components/Sources\";\nexport { Sources };\nexport type { SourcesProps, SourcesItem, SourcesRef } from \"./types/Sources\";\n\n// FolderTree 文件树组件\nimport FolderTree from \"./components/FolderTree\";\nexport { FolderTree };\nexport type {\n  FolderTreeProps,\n  FolderTreeData,\n  FileContentService,\n  FolderTreeRef,\n} from \"./components/FolderTree\";\n\n// 基础组件导出 - 供高级用户和业务侧使用\nexport { default as MarkdownRender } from \"./components/XAdkChatbot/components/MarkdownRender\";\nexport { default as FunctionCallRender } from \"./components/XAdkChatbot/components/FunctionCallRender\";\nexport { default as ThinkRender } from \"./components/XAdkChatbot/components/ThinkRender\";\n\n// 基础组件类型导出\nexport type { MarkdownRenderProps } from \"./components/XAdkChatbot/components/MarkdownRender\";\nexport type { FunctionCallRenderProps } from \"./types/FunctionCallRender\";\nexport type {\n  XAdkThoughtChainProps,\n  ThoughtChainItemType,\n  ThoughtChainStatus,\n} from \"./types/XAdkThoughtChain\";\n\n// 设计令牌导出 - 供引用方覆盖样式\nexport { tokens, tokenDefaults, token, cssVarStyle } from \"./styles/tokens\";\n\n// Headless ADK data-flow APIs\nexport * from \"./core\";\nexport { default as useAdkConversation } from \"./react/useAdkConversation\";\nexport type { UseAdkConversationResult } from \"./react/useAdkConversation\";\nexport { createXGroupOpenApiTransport } from \"./presets/xgroup\";\nexport type { XGroupOpenApiTransportOptions } from \"./presets/xgroup\";\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA,wCAAAA;AAAA,EAAA,oCAAAC;AAAA,EAAA;AAAA;AAAA,gCAAAC;AAAA,EAAA;AAAA,wCAAAC;AAAA,EAAA,wCAAAC;AAAA,EAAA,oCAAAC;AAAA,EAAA,gDAAAC;AAAA,EAAA,oCAAAC;AAAA,EAAA,gDAAAC;AAAA,EAAA,sCAAAC;AAAA,EAAA,4BAAAC;AAAA,EAAA,kCAAAC;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gCAAAC;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,sCAAAC;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oCAAAC;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,+BAAuB;AACvB,yBAAwB;AACxB,wBAAuB;AACvB,oBAAmB;AACnB,uBAAsB;AACtB,yBAAwB;AACxB,8BAA6B;AAC7B,8BAA6B;AAC7B,uBAAsB;AACtB,qBAAoB;AACpB,8BAMO;AAGP,0BAAyB;AACzB,yBAAwB;AACxB,wBAAuB;AACvB,wBAAuB;AACvB,gCAAmC;AACnC,qBAYO;AACP,oBAUO;AAGP,qBAIO;AAEP,wBAAc,oBAzDd;AAuHA,qBAAoB;AAKpB,wBAAuB;AAUvB,4BAA0C;AAC1C,gCAA8C;AAC9C,yBAAuC;AAYvC,oBAA0D;AAG1D,wBAAc,mBAvJd;AAwJA,gCAA8C;AAE9C,IAAAC,iBAA6C;",
   "names": ["FileGallery", "FolderTree", "Sources", "XAdkChatbot", "XAdkProvider", "XAdkSender", "XAdkThoughtChain", "XAiChatbot", "XAiConversations", "XAiProvider", "XAiSDK", "XAiSender", "request", "useADKChat", "useXAiSDK", "import_xgroup"]
 }

package/dist/cjs/react/index.d.ts

@@ -1,6 +1,8 @@
 export { default as useAdkConversation } from "./useAdkConversation";
 export type { UseAdkConversationResult } from "./useAdkConversation";
 export { default as useADKChat } from "../hooks/useADKChat";
+export { useADKMessageQueue } from "../hooks/useADKMessageQueue";
+export type { ADKQueuedMessage, ADKMessageQueueOptions } from "../hooks/useADKMessageQueue";
 export { default as useEventStreamRequest } from "../hooks/useEventStreamRequest";
 export { useChatActions, useChatState, useSession, } from "../components/XAdkProvider/context";
 export type { ChatHookFactory, ChatHookResult } from "../types/ChatHook";

package/dist/cjs/react/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var react_exports = {};
 __export(react_exports, {
   useADKChat: () => import_useADKChat.default,
+  useADKMessageQueue: () => import_useADKMessageQueue.useADKMessageQueue,
   useAdkConversation: () => import_useAdkConversation.default,
   useChatActions: () => import_context.useChatActions,
   useChatState: () => import_context.useChatState,
@@ -39,11 +40,13 @@ __export(react_exports, {
 module.exports = __toCommonJS(react_exports);
 var import_useAdkConversation = __toESM(require("./useAdkConversation"));
 var import_useADKChat = __toESM(require("../hooks/useADKChat"));
+var import_useADKMessageQueue = require("../hooks/useADKMessageQueue");
 var import_useEventStreamRequest = __toESM(require("../hooks/useEventStreamRequest"));
 var import_context = require("../components/XAdkProvider/context");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   useADKChat,
+  useADKMessageQueue,
   useAdkConversation,
   useChatActions,
   useChatState,

package/dist/cjs/react/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/react/index.ts"],
-  "sourcesContent": ["export { default as useAdkConversation } from \"./useAdkConversation\";\nexport type { UseAdkConversationResult } from \"./useAdkConversation\";\nexport { default as useADKChat } from \"@/hooks/useADKChat\";\nexport { default as useEventStreamRequest } from \"@/hooks/useEventStreamRequest\";\nexport {\n  useChatActions,\n  useChatState,\n  useSession,\n} from \"@/components/XAdkProvider/context\";\nexport type { ChatHookFactory, ChatHookResult } from \"@/types/ChatHook\";\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gCAA8C;AAE9C,wBAAsC;AACtC,mCAAiD;AACjD,qBAIO;",
+  "sourcesContent": ["export { default as useAdkConversation } from \"./useAdkConversation\";\nexport type { UseAdkConversationResult } from \"./useAdkConversation\";\nexport { default as useADKChat } from \"@/hooks/useADKChat\";\nexport { useADKMessageQueue } from \"@/hooks/useADKMessageQueue\";\nexport type { ADKQueuedMessage, ADKMessageQueueOptions } from \"@/hooks/useADKMessageQueue\";\nexport { default as useEventStreamRequest } from \"@/hooks/useEventStreamRequest\";\nexport {\n  useChatActions,\n  useChatState,\n  useSession,\n} from \"@/components/XAdkProvider/context\";\nexport type { ChatHookFactory, ChatHookResult } from \"@/types/ChatHook\";\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gCAA8C;AAE9C,wBAAsC;AACtC,gCAAmC;AAEnC,mCAAiD;AACjD,qBAIO;",
   "names": []
 }

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

@@ -10,6 +10,12 @@ import { type ChatPresetInput, type ChatStrategies } from "./ChatStrategies";
 export interface XAdkChatbotHandle {
     /** 手动滚动到底部 */
     scrollToBottom: (behavior?: ScrollBehavior) => void;
+    /** 当前消息列表的滚动容器 */
+    getScrollContainer: () => HTMLDivElement | null;
+    /** 消息组相对滚动容器顶部的位置 */
+    getMessagePosition: (messageId: string) => number | null;
+    /** 滚动到指定消息组 */
+    scrollToMessage: (messageId: string, behavior?: ScrollBehavior) => void;
 }
 /**
  * 消息分组接口
@@ -23,6 +29,32 @@ export interface ChatGroup {
     /** 点赞状态: 1=赞, -1=踩, 0=未反馈 */
     isLike?: number;
 }
+/** 自定义消息流内容的定位上下文。按分组而非数组下标锚定，分页 prepend 后仍可稳定定位。 */
+export interface ChatGroupRenderContext {
+    group: ChatGroup;
+    index: number;
+    previousGroup?: ChatGroup;
+    nextGroup?: ChatGroup;
+}
+/** 受控历史消息分页。不传时一次性展示 messages，保持原有行为。 */
+export interface ChatHistoryPagination {
+    /** 是否仍有下一页；历史消息通常从顶部加载更早内容。 */
+    hasMore: boolean;
+    loading?: boolean;
+    /** top 加载更早消息，bottom 可用于正序列表加载后续内容。默认 top。 */
+    direction?: "top" | "bottom";
+    /** 距离指定边缘多少像素时触发加载，默认 80。 */
+    threshold?: number;
+    /** 使用方负责请求并合并 messages；建议以稳定消息 id 去重。 */
+    onLoadMore: (context: {
+        signal: AbortSignal;
+    }) => Promise<void>;
+    /** 可选的显式刷新操作；SDK 只触发回调，不规定请求方式。 */
+    onRefresh?: (context: {
+        signal: AbortSignal;
+    }) => Promise<void>;
+    refreshing?: boolean;
+}
 export interface IInvocation {
     id: string;
     name: string;
@@ -229,6 +261,9 @@ export type ActionExtraProps = (data: {
     message: ChatGroup;
     isLastBotMsg: boolean;
 }) => ReactNode;
+export type UserActionProps = (data: {
+    message: ChatGroup;
+}) => ReactNode | null;
 export interface MarkdownResourceLink {
     /** 完整链接，如 skill://InnerSkill01 */
     href: string;
@@ -292,6 +327,16 @@ export interface XAdkChatbotProps extends Partial<XAdkSenderProps> {
     loading?: boolean;
     /** 消息列表 */
     messages: IMessage[];
+    /** 在消息组前插入自定义模块，适合系统提示、日期或分支分界线。 */
+    renderBeforeGroup?: (context: ChatGroupRenderContext) => ReactNode;
+    /** 在消息组后插入自定义模块，适合与某轮回复关联的业务内容。 */
+    renderAfterGroup?: (context: ChatGroupRenderContext) => ReactNode;
+    /** 基于组内数据替换默认消息展示；返回 undefined 时沿用默认展示，null 表示隐藏。 */
+    renderGroup?: (context: ChatGroupRenderContext & {
+        defaultNode: ReactNode;
+    }) => ReactNode | undefined;
+    /** 按需加载消息。不传时仍一次性展示传入的全部 messages。 */
+    history?: ChatHistoryPagination;
     /** 开场白 */
     prologue?: string;
     /** 建议回复 */
@@ -384,4 +429,8 @@ export interface XAdkChatbotProps extends Partial<XAdkSenderProps> {
     markdownExtensions?: readonly MarkdownExtension[];
     /** 消息列表为空时展示的自定义空状态组件 */
     empty?: ReactNode | (() => ReactNode);
+    /** 是否启用用户消息 hover 操作栏（时间 + 复制），默认 false */
+    showUserActions?: boolean;
+    /** 用户消息自定义操作栏渲染，返回 null 则降级使用默认渲染 */
+    userActions?: UserActionProps;
 }

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/types/XAdkChatbot.ts"],
-  "sourcesContent": ["import type { CSSProperties, JSX, ReactNode } from \"react\";\nimport { type XAdkSenderProps } from \"./XAdkSender\";\nimport { type SendContent } from \"./XAiSender\";\nimport { type FileItem } from \"./FileGallery\";\nimport { type ToolRenderKind } from \"./FunctionCallRender\";\nimport { type ChatPresetInput, type ChatStrategies } from \"./ChatStrategies\";\n\n/**\n * XAdkChatbot 命令式 API\n */\nexport interface XAdkChatbotHandle {\n  /** 手动滚动到底部 */\n  scrollToBottom: (behavior?: ScrollBehavior) => void;\n}\n\n/**\n * 消息分组接口\n */\nexport interface ChatGroup {\n  id: string;\n  role: \"user\" | \"bot\";\n  msgs: IMessage[];\n  invocationId?: string;\n  allFiles: any[];\n  /** 点赞状态: 1=赞, -1=踩, 0=未反馈 */\n  isLike?: number;\n}\n\nexport interface IInvocation {\n  id: string;\n  name: string;\n  spanId: string;\n  traceId: string;\n  parentSpanId: string;\n  startTime: number;\n  endTime: number;\n  sessionId: string;\n  invocationId: string;\n  duration: number;\n  attributes: Record<string, string>;\n  botName: string;\n  workspaceNo: string;\n  status: number;\n  agentName: string;\n  agentNo: string;\n  agentVersionNo: string;\n  userId: string;\n}\n\nexport interface AgentRunRequest {\n  stream?: boolean;\n  sessionId: string | undefined;\n  content: {\n    parts: Array<{\n      text?: string;\n      functionResponse?: {\n        id?: string;\n        name?: string;\n        response?: any;\n      };\n    }>;\n    role: string;\n  };\n  files?: Array<{\n    fileName: string;\n    fileId?: string;\n    tempUrl: string;\n    type?: string;\n    mimeType: string;\n  }>;\n  stateDelta?: any;\n}\nexport interface Blob {\n  displayName?: string;\n  mimeType?: string;\n  data: string;\n}\n\nexport interface FunctionCall {\n  id?: string;\n  name: string;\n  args: { [key: string]: any };\n}\n\nexport interface FunctionResponse {\n  id?: string;\n  name: string;\n  response: { [key: string]: any };\n}\n\nexport interface FileData {\n  displayName: string;\n  mimeType: string;\n  fileUri: string;\n}\n\nexport interface ExecutableCode {\n  language: \"UNKNOWN\" | \"PYTHON\";\n  code: string;\n}\n\nexport interface CodeExecutionResult {\n  outcome: \"UNKNOWN\" | \"OK\" | \"FAILED\" | \"DEADLINE_EXCEEDED\";\n  output: string;\n}\n\nexport interface Part {\n  text?: string;\n  inlineData?: Blob;\n  functionCall?: FunctionCall;\n  functionResponse?: FunctionResponse;\n  thought?: boolean;\n  fileData?: FileData;\n  executableCode?: ExecutableCode;\n  codeExecutionResult?: CodeExecutionResult;\n  errorMessage?: string;\n}\n\nexport interface GenAiContent {\n  role: string;\n  parts: Part[];\n}\n\nexport interface LlmRequest {\n  contents: GenAiContent[];\n}\n\nexport interface LlmResponse {\n  partial?: boolean;\n  content: GenAiContent;\n  error?: string;\n  errorMessage?: string;\n  errorCode?: string;\n  longRunningToolIds?: string[];\n}\n\nexport interface UsageMetadata {\n  candidatesTokenCount?: number;\n  promptTokenCount?: number;\n  totalTokenCount?: number;\n  [key: string]: any;\n}\n\nexport interface EventActions {\n  message?: string;\n  artifactDelta?: any;\n  functionCall?: FunctionCall;\n  functionResponse?: FunctionResponse;\n  finishReason?: string;\n}\n\nexport interface Event extends LlmResponse {\n  id?: string;\n  author?: string;\n  modelCode?: string;\n  invocationId?: string;\n  actions?: EventActions;\n  longRunningToolIds?: string[];\n  branch?: string;\n  timestamp?: number;\n  finishReason?: string;\n  usageMetadata?: UsageMetadata;\n  evalStatus?: any;\n  failedMetric?: any;\n  evalScore?: any;\n  evalThreshold?: any;\n  groundingMetadata?: {\n    searchEntryPoint?: {\n      renderedContent?: any;\n    };\n  };\n  isLike?: number;\n  sessionId?: string;\n}\n\nexport interface SessionState {\n  [key: string]: unknown;\n}\n\nexport interface Session {\n  id?: string;\n  appName?: string;\n  userId?: string;\n  state?: SessionState;\n  events?: Event[];\n  lastUpdateTime?: number;\n}\n\nexport interface TimeTick {\n  position: number;\n  label: string;\n}\n\nexport interface IMessage {\n  /** 前端生成的唯一标识 */\n  id: string;\n  /** 单次请求的唯一标识 */\n  invocationId?: string;\n  /** 单个Event的唯一标识，一个event里有可能有多个parts的消息 */\n  eventId?: string;\n  /** 消息发起人：智能体名称、user */\n  author?: string;\n  role: \"bot\" | \"user\";\n  /** 时间戳 */\n  timestamp?: number;\n  isLoading?: boolean;\n  /** 函数调用 */\n  functionCall?: FunctionCall;\n  /** 函数调用结果 */\n  functionResponse?: FunctionResponse;\n  /** 文件上传 */\n  inlineData?: Blob;\n  /** 文本消息 */\n  text?: string;\n  /** 文件信息 */\n  fileData?: FileData[];\n  /** 思考 */\n  thought?: boolean;\n  executableCode?: ExecutableCode;\n  codeExecutionResult?: CodeExecutionResult;\n  renderedContent?: any;\n  /** 原始数据 */\n  raw?: any;\n  /** 模型编码，通常来自 stream 事件或历史消息 */\n  modelCode?: string;\n  /** 事件级 token 使用量等模型调用元数据 */\n  usageMetadata?: UsageMetadata;\n  /** 结束原因，通常来自最后一条 stream 事件 */\n  finishReason?: string;\n  // 下面暂时没有用到\n  evalStatus?: any;\n  failedMetric?: any;\n  evalScore?: any;\n  evalThreshold?: any;\n  invocationIndex?: any;\n  finalResponsePartIndex?: any;\n  toolUseIndex?: any;\n  /** 是否赞/踩 */\n  isLike?: number;\n}\n\nexport type ActionProps = (data: {\n  message: ChatGroup;\n  isLastBotMsg: boolean;\n}) => JSX.Element | null;\n\nexport type ActionExtraProps = (data: {\n  message: ChatGroup;\n  isLastBotMsg: boolean;\n}) => ReactNode;\n\nexport interface MarkdownResourceLink {\n  /** 完整链接，如 skill://InnerSkill01 */\n  href: string;\n  /** Markdown 链接文字，如 @skill-creator */\n  label: string;\n  /** 协议类型，如 skill/plugin/knowledge */\n  type: string;\n  /** 协议值，如 InnerSkill01 */\n  value: string;\n}\n\nexport type RenderMarkdownResourceLink = (\n  link: MarkdownResourceLink,\n) => ReactNode | null;\n\n/**\n * 自定义工具调用渲染函数\n * - 返回 ReactNode：使用自定义渲染\n * - 返回 null：降级使用默认渲染\n *\n * @example\n * renderFunctionCall={(msg) => {\n *   if (msg.functionCall?.name === 'my_tool') return <MyToolRender msg={msg} />;\n *   return null; // 其他工具使用默认渲染\n * }}\n */\nexport type RenderFunctionCall = (msg: IMessage) => ReactNode | null;\n\n/** Markdown 自定义标签经过安全过滤后的结构化节点。 */\nexport interface MarkdownExtensionNode {\n  tagName: string;\n  attributes: Readonly<Record<string, string>>;\n  text: string;\n  children: ReactNode;\n}\n\n/**\n * Markdown 自定义标签扩展。\n * 标签及属性只有显式注册后才会交给渲染函数，业务协议无需进入 SDK 核心。\n */\nexport interface MarkdownExtension {\n  tagName: string;\n  allowedAttributes?: readonly string[];\n  render: (node: MarkdownExtensionNode) => ReactNode | null;\n}\n\nexport interface XAdkChatbotProps extends Partial<XAdkSenderProps> {\n  /**\n   * 自定义工具调用渲染函数\n   * 返回 null 则降级使用默认渲染\n   */\n  renderFunctionCall?: RenderFunctionCall;\n  /**\n   * 工具名 → 渲染类型的解析策略，默认使用 defaultToolKindResolver\n   */\n  toolKindResolver?: (name: string | undefined) => ToolRenderKind;\n  /**\n   * 聊天策略，可由 Provider preset 自动下发，也可在组件局部覆盖。\n   */\n  strategies?: ChatStrategies;\n  /**\n   * 组件直用时的协议预设。默认沿用 xgroup-adk 以兼容既有业务接入；\n   * 需要中立行为时可传入 base。\n   */\n  preset?: ChatPresetInput;\n  className?: string;\n  style?: CSSProperties;\n  // 加载状态\n  loading?: boolean;\n  /** 消息列表 */\n  messages: IMessage[];\n  /** 开场白 */\n  prologue?: string;\n  /** 建议回复 */\n  suggestions?: string[];\n  /** 欢迎页面 */\n  welcome?: ReactNode;\n  /** 显示函数调用详情 */\n  showFnCallDetail?: boolean;\n  /**\n   * 数据是否就绪，就绪后触发首次自动滚底。默认 true。\n   * 仅在需要等待异步加载历史消息的场景（如 XAdkProvider 内）才需设为 false，\n   * 待数据加载完成后再切换为 true；独立使用时无需关心此属性。\n   */\n  initialized?: boolean;\n  /**\n   * 当前会话 ID，切换时自动重置滚动状态并置底。\n   * 不传则退化为仅依赖 initialized 的单次置底行为。\n   */\n  sessionId?: string;\n  /** 提交回调 */\n  onSubmit?: ({ text, files }: SendContent) => void;\n  /** 函数调用确认回调 */\n  onConfirm?: (fnCall: FunctionCall, confirmed: boolean) => void;\n  /** 停止回调 */\n  onStop?: () => void;\n  /** 清除回调 */\n  onClear?: () => void;\n  /** 建议回复回调 */\n  onSuggest?: (text: string) => void;\n\n  // ========== 新增功能 ==========\n\n  /** Agent 名称 (欢迎页面) */\n  agentName?: string;\n  /** Agent 图标 (欢迎页面) */\n  agentIcon?: string;\n  /** Agent 描述 (欢迎页面) */\n  description?: string;\n\n  /** 是否显示重试按钮 */\n  showRetry?: boolean;\n  /** 是否显示复制按钮 */\n  showCopy?: boolean;\n  /** 是否显示日志按钮 */\n  showLog?: boolean;\n\n  /** 重试回调 */\n  onRetry?: () => void;\n  /** 复制回调 */\n  onCopy?: (text: string) => void;\n  /** 查看日志回调 */\n  onShowLog?: (invocationId: string, timestamp?: number) => void;\n\n  /** 是否启用消息分组 (默认 true) */\n  enableGrouping?: boolean;\n\n  /** 是否自动解析 process 内容并展示思维链 (默认 true) */\n  enableProcessParsing?: boolean;\n\n  /** 消息功能区 */\n  actions?: ActionProps;\n  /** 追加在消息功能区之后的内容，适合展示 token 消耗等业务扩展信息 */\n  actionsExtra?: ActionExtraProps;\n\n  /**\n   * Process 解析选项\n   * @example\n   * // 业务项目格式 (注释模式)\n   * parseOptions={{ mode: 'comment' }}\n   *\n   * @example\n   * // 自定义格式\n   * parseOptions={{\n   *   mode: 'custom',\n   *   customPatterns: [\n   *     { regex: /\\[REASONING\\]([\\s\\S]*?)\\[\\/REASONING\\]/g, type: 'reasoning' }\n   *   ]\n   * }}\n   */\n  parseOptions?: {\n    mode?: \"xml\" | \"comment\" | \"custom\";\n    customPatterns?: Array<{ regex: RegExp; type: string }>;\n    finalMarker?: string;\n  };\n\n  /** 是否禁用输入 */\n  disabled?: boolean;\n\n  /** 是否流式响应 */\n  stream?: boolean;\n\n  /** 点击对话中附件卡片的回调（非图片、非音视频文件） */\n  onFileClick?: (file: FileItem) => void;\n\n  /** 点击 Markdown 资源链接标签的回调，如 [@skill](skill://xxx) */\n  onResourceLinkClick?: (link: MarkdownResourceLink) => void;\n\n  /** 自定义 Markdown 资源链接渲染，返回 null 则降级使用默认标签样式 */\n  renderResourceLink?: RenderMarkdownResourceLink;\n\n  /** Markdown/XML 自定义标签扩展 */\n  markdownExtensions?: readonly MarkdownExtension[];\n\n  /** 消息列表为空时展示的自定义空状态组件 */\n  empty?: ReactNode | (() => ReactNode);\n}\n"],
+  "sourcesContent": ["import type { CSSProperties, JSX, ReactNode } from \"react\";\nimport { type XAdkSenderProps } from \"./XAdkSender\";\nimport { type SendContent } from \"./XAiSender\";\nimport { type FileItem } from \"./FileGallery\";\nimport { type ToolRenderKind } from \"./FunctionCallRender\";\nimport { type ChatPresetInput, type ChatStrategies } from \"./ChatStrategies\";\n\n/**\n * XAdkChatbot 命令式 API\n */\nexport interface XAdkChatbotHandle {\n  /** 手动滚动到底部 */\n  scrollToBottom: (behavior?: ScrollBehavior) => void;\n  /** 当前消息列表的滚动容器 */\n  getScrollContainer: () => HTMLDivElement | null;\n  /** 消息组相对滚动容器顶部的位置 */\n  getMessagePosition: (messageId: string) => number | null;\n  /** 滚动到指定消息组 */\n  scrollToMessage: (messageId: string, behavior?: ScrollBehavior) => void;\n}\n\n/**\n * 消息分组接口\n */\nexport interface ChatGroup {\n  id: string;\n  role: \"user\" | \"bot\";\n  msgs: IMessage[];\n  invocationId?: string;\n  allFiles: any[];\n  /** 点赞状态: 1=赞, -1=踩, 0=未反馈 */\n  isLike?: number;\n}\n\n/** 自定义消息流内容的定位上下文。按分组而非数组下标锚定，分页 prepend 后仍可稳定定位。 */\nexport interface ChatGroupRenderContext {\n  group: ChatGroup;\n  index: number;\n  previousGroup?: ChatGroup;\n  nextGroup?: ChatGroup;\n}\n\n/** 受控历史消息分页。不传时一次性展示 messages，保持原有行为。 */\nexport interface ChatHistoryPagination {\n  /** 是否仍有下一页；历史消息通常从顶部加载更早内容。 */\n  hasMore: boolean;\n  loading?: boolean;\n  /** top 加载更早消息，bottom 可用于正序列表加载后续内容。默认 top。 */\n  direction?: \"top\" | \"bottom\";\n  /** 距离指定边缘多少像素时触发加载，默认 80。 */\n  threshold?: number;\n  /** 使用方负责请求并合并 messages；建议以稳定消息 id 去重。 */\n  onLoadMore: (context: { signal: AbortSignal }) => Promise<void>;\n  /** 可选的显式刷新操作；SDK 只触发回调，不规定请求方式。 */\n  onRefresh?: (context: { signal: AbortSignal }) => Promise<void>;\n  refreshing?: boolean;\n}\n\nexport interface IInvocation {\n  id: string;\n  name: string;\n  spanId: string;\n  traceId: string;\n  parentSpanId: string;\n  startTime: number;\n  endTime: number;\n  sessionId: string;\n  invocationId: string;\n  duration: number;\n  attributes: Record<string, string>;\n  botName: string;\n  workspaceNo: string;\n  status: number;\n  agentName: string;\n  agentNo: string;\n  agentVersionNo: string;\n  userId: string;\n}\n\nexport interface AgentRunRequest {\n  stream?: boolean;\n  sessionId: string | undefined;\n  content: {\n    parts: Array<{\n      text?: string;\n      functionResponse?: {\n        id?: string;\n        name?: string;\n        response?: any;\n      };\n    }>;\n    role: string;\n  };\n  files?: Array<{\n    fileName: string;\n    fileId?: string;\n    tempUrl: string;\n    type?: string;\n    mimeType: string;\n  }>;\n  stateDelta?: any;\n}\nexport interface Blob {\n  displayName?: string;\n  mimeType?: string;\n  data: string;\n}\n\nexport interface FunctionCall {\n  id?: string;\n  name: string;\n  args: { [key: string]: any };\n}\n\nexport interface FunctionResponse {\n  id?: string;\n  name: string;\n  response: { [key: string]: any };\n}\n\nexport interface FileData {\n  displayName: string;\n  mimeType: string;\n  fileUri: string;\n}\n\nexport interface ExecutableCode {\n  language: \"UNKNOWN\" | \"PYTHON\";\n  code: string;\n}\n\nexport interface CodeExecutionResult {\n  outcome: \"UNKNOWN\" | \"OK\" | \"FAILED\" | \"DEADLINE_EXCEEDED\";\n  output: string;\n}\n\nexport interface Part {\n  text?: string;\n  inlineData?: Blob;\n  functionCall?: FunctionCall;\n  functionResponse?: FunctionResponse;\n  thought?: boolean;\n  fileData?: FileData;\n  executableCode?: ExecutableCode;\n  codeExecutionResult?: CodeExecutionResult;\n  errorMessage?: string;\n}\n\nexport interface GenAiContent {\n  role: string;\n  parts: Part[];\n}\n\nexport interface LlmRequest {\n  contents: GenAiContent[];\n}\n\nexport interface LlmResponse {\n  partial?: boolean;\n  content: GenAiContent;\n  error?: string;\n  errorMessage?: string;\n  errorCode?: string;\n  longRunningToolIds?: string[];\n}\n\nexport interface UsageMetadata {\n  candidatesTokenCount?: number;\n  promptTokenCount?: number;\n  totalTokenCount?: number;\n  [key: string]: any;\n}\n\nexport interface EventActions {\n  message?: string;\n  artifactDelta?: any;\n  functionCall?: FunctionCall;\n  functionResponse?: FunctionResponse;\n  finishReason?: string;\n}\n\nexport interface Event extends LlmResponse {\n  id?: string;\n  author?: string;\n  modelCode?: string;\n  invocationId?: string;\n  actions?: EventActions;\n  longRunningToolIds?: string[];\n  branch?: string;\n  timestamp?: number;\n  finishReason?: string;\n  usageMetadata?: UsageMetadata;\n  evalStatus?: any;\n  failedMetric?: any;\n  evalScore?: any;\n  evalThreshold?: any;\n  groundingMetadata?: {\n    searchEntryPoint?: {\n      renderedContent?: any;\n    };\n  };\n  isLike?: number;\n  sessionId?: string;\n}\n\nexport interface SessionState {\n  [key: string]: unknown;\n}\n\nexport interface Session {\n  id?: string;\n  appName?: string;\n  userId?: string;\n  state?: SessionState;\n  events?: Event[];\n  lastUpdateTime?: number;\n}\n\nexport interface TimeTick {\n  position: number;\n  label: string;\n}\n\nexport interface IMessage {\n  /** 前端生成的唯一标识 */\n  id: string;\n  /** 单次请求的唯一标识 */\n  invocationId?: string;\n  /** 单个Event的唯一标识，一个event里有可能有多个parts的消息 */\n  eventId?: string;\n  /** 消息发起人：智能体名称、user */\n  author?: string;\n  role: \"bot\" | \"user\";\n  /** 时间戳 */\n  timestamp?: number;\n  isLoading?: boolean;\n  /** 函数调用 */\n  functionCall?: FunctionCall;\n  /** 函数调用结果 */\n  functionResponse?: FunctionResponse;\n  /** 文件上传 */\n  inlineData?: Blob;\n  /** 文本消息 */\n  text?: string;\n  /** 文件信息 */\n  fileData?: FileData[];\n  /** 思考 */\n  thought?: boolean;\n  executableCode?: ExecutableCode;\n  codeExecutionResult?: CodeExecutionResult;\n  renderedContent?: any;\n  /** 原始数据 */\n  raw?: any;\n  /** 模型编码，通常来自 stream 事件或历史消息 */\n  modelCode?: string;\n  /** 事件级 token 使用量等模型调用元数据 */\n  usageMetadata?: UsageMetadata;\n  /** 结束原因，通常来自最后一条 stream 事件 */\n  finishReason?: string;\n  // 下面暂时没有用到\n  evalStatus?: any;\n  failedMetric?: any;\n  evalScore?: any;\n  evalThreshold?: any;\n  invocationIndex?: any;\n  finalResponsePartIndex?: any;\n  toolUseIndex?: any;\n  /** 是否赞/踩 */\n  isLike?: number;\n}\n\nexport type ActionProps = (data: {\n  message: ChatGroup;\n  isLastBotMsg: boolean;\n}) => JSX.Element | null;\n\nexport type ActionExtraProps = (data: {\n  message: ChatGroup;\n  isLastBotMsg: boolean;\n}) => ReactNode;\n\nexport type UserActionProps = (data: { message: ChatGroup }) => ReactNode | null;\n\nexport interface MarkdownResourceLink {\n  /** 完整链接，如 skill://InnerSkill01 */\n  href: string;\n  /** Markdown 链接文字，如 @skill-creator */\n  label: string;\n  /** 协议类型，如 skill/plugin/knowledge */\n  type: string;\n  /** 协议值，如 InnerSkill01 */\n  value: string;\n}\n\nexport type RenderMarkdownResourceLink = (\n  link: MarkdownResourceLink,\n) => ReactNode | null;\n\n/**\n * 自定义工具调用渲染函数\n * - 返回 ReactNode：使用自定义渲染\n * - 返回 null：降级使用默认渲染\n *\n * @example\n * renderFunctionCall={(msg) => {\n *   if (msg.functionCall?.name === 'my_tool') return <MyToolRender msg={msg} />;\n *   return null; // 其他工具使用默认渲染\n * }}\n */\nexport type RenderFunctionCall = (msg: IMessage) => ReactNode | null;\n\n/** Markdown 自定义标签经过安全过滤后的结构化节点。 */\nexport interface MarkdownExtensionNode {\n  tagName: string;\n  attributes: Readonly<Record<string, string>>;\n  text: string;\n  children: ReactNode;\n}\n\n/**\n * Markdown 自定义标签扩展。\n * 标签及属性只有显式注册后才会交给渲染函数，业务协议无需进入 SDK 核心。\n */\nexport interface MarkdownExtension {\n  tagName: string;\n  allowedAttributes?: readonly string[];\n  render: (node: MarkdownExtensionNode) => ReactNode | null;\n}\n\nexport interface XAdkChatbotProps extends Partial<XAdkSenderProps> {\n  /**\n   * 自定义工具调用渲染函数\n   * 返回 null 则降级使用默认渲染\n   */\n  renderFunctionCall?: RenderFunctionCall;\n  /**\n   * 工具名 → 渲染类型的解析策略，默认使用 defaultToolKindResolver\n   */\n  toolKindResolver?: (name: string | undefined) => ToolRenderKind;\n  /**\n   * 聊天策略，可由 Provider preset 自动下发，也可在组件局部覆盖。\n   */\n  strategies?: ChatStrategies;\n  /**\n   * 组件直用时的协议预设。默认沿用 xgroup-adk 以兼容既有业务接入；\n   * 需要中立行为时可传入 base。\n   */\n  preset?: ChatPresetInput;\n  className?: string;\n  style?: CSSProperties;\n  // 加载状态\n  loading?: boolean;\n  /** 消息列表 */\n  messages: IMessage[];\n  /** 在消息组前插入自定义模块，适合系统提示、日期或分支分界线。 */\n  renderBeforeGroup?: (context: ChatGroupRenderContext) => ReactNode;\n  /** 在消息组后插入自定义模块，适合与某轮回复关联的业务内容。 */\n  renderAfterGroup?: (context: ChatGroupRenderContext) => ReactNode;\n  /** 基于组内数据替换默认消息展示；返回 undefined 时沿用默认展示，null 表示隐藏。 */\n  renderGroup?: (context: ChatGroupRenderContext & { defaultNode: ReactNode }) => ReactNode | undefined;\n  /** 按需加载消息。不传时仍一次性展示传入的全部 messages。 */\n  history?: ChatHistoryPagination;\n  /** 开场白 */\n  prologue?: string;\n  /** 建议回复 */\n  suggestions?: string[];\n  /** 欢迎页面 */\n  welcome?: ReactNode;\n  /** 显示函数调用详情 */\n  showFnCallDetail?: boolean;\n  /**\n   * 数据是否就绪，就绪后触发首次自动滚底。默认 true。\n   * 仅在需要等待异步加载历史消息的场景（如 XAdkProvider 内）才需设为 false，\n   * 待数据加载完成后再切换为 true；独立使用时无需关心此属性。\n   */\n  initialized?: boolean;\n  /**\n   * 当前会话 ID，切换时自动重置滚动状态并置底。\n   * 不传则退化为仅依赖 initialized 的单次置底行为。\n   */\n  sessionId?: string;\n  /** 提交回调 */\n  onSubmit?: ({ text, files }: SendContent) => void;\n  /** 函数调用确认回调 */\n  onConfirm?: (fnCall: FunctionCall, confirmed: boolean) => void;\n  /** 停止回调 */\n  onStop?: () => void;\n  /** 清除回调 */\n  onClear?: () => void;\n  /** 建议回复回调 */\n  onSuggest?: (text: string) => void;\n\n  // ========== 新增功能 ==========\n\n  /** Agent 名称 (欢迎页面) */\n  agentName?: string;\n  /** Agent 图标 (欢迎页面) */\n  agentIcon?: string;\n  /** Agent 描述 (欢迎页面) */\n  description?: string;\n\n  /** 是否显示重试按钮 */\n  showRetry?: boolean;\n  /** 是否显示复制按钮 */\n  showCopy?: boolean;\n  /** 是否显示日志按钮 */\n  showLog?: boolean;\n\n  /** 重试回调 */\n  onRetry?: () => void;\n  /** 复制回调 */\n  onCopy?: (text: string) => void;\n  /** 查看日志回调 */\n  onShowLog?: (invocationId: string, timestamp?: number) => void;\n\n  /** 是否启用消息分组 (默认 true) */\n  enableGrouping?: boolean;\n\n  /** 是否自动解析 process 内容并展示思维链 (默认 true) */\n  enableProcessParsing?: boolean;\n\n  /** 消息功能区 */\n  actions?: ActionProps;\n  /** 追加在消息功能区之后的内容，适合展示 token 消耗等业务扩展信息 */\n  actionsExtra?: ActionExtraProps;\n\n  /**\n   * Process 解析选项\n   * @example\n   * // 业务项目格式 (注释模式)\n   * parseOptions={{ mode: 'comment' }}\n   *\n   * @example\n   * // 自定义格式\n   * parseOptions={{\n   *   mode: 'custom',\n   *   customPatterns: [\n   *     { regex: /\\[REASONING\\]([\\s\\S]*?)\\[\\/REASONING\\]/g, type: 'reasoning' }\n   *   ]\n   * }}\n   */\n  parseOptions?: {\n    mode?: \"xml\" | \"comment\" | \"custom\";\n    customPatterns?: Array<{ regex: RegExp; type: string }>;\n    finalMarker?: string;\n  };\n\n  /** 是否禁用输入 */\n  disabled?: boolean;\n\n  /** 是否流式响应 */\n  stream?: boolean;\n\n  /** 点击对话中附件卡片的回调（非图片、非音视频文件） */\n  onFileClick?: (file: FileItem) => void;\n\n  /** 点击 Markdown 资源链接标签的回调，如 [@skill](skill://xxx) */\n  onResourceLinkClick?: (link: MarkdownResourceLink) => void;\n\n  /** 自定义 Markdown 资源链接渲染，返回 null 则降级使用默认标签样式 */\n  renderResourceLink?: RenderMarkdownResourceLink;\n\n  /** Markdown/XML 自定义标签扩展 */\n  markdownExtensions?: readonly MarkdownExtension[];\n\n  /** 消息列表为空时展示的自定义空状态组件 */\n  empty?: ReactNode | (() => ReactNode);\n\n  /** 是否启用用户消息 hover 操作栏（时间 + 复制），默认 false */\n  showUserActions?: boolean;\n  /** 用户消息自定义操作栏渲染，返回 null 则降级使用默认渲染 */\n  userActions?: UserActionProps;\n}\n"],
   "mappings": ";;;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

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

@@ -18,6 +18,8 @@ export interface DebugOptions {
     onSuccess?: (data: Success) => void;
     onStream?: (data: Event) => void;
     onMessage?: (content: string, data: IMessage) => void;
+    /** 调用 sendQueuedMessageNow 时可选的后端打断回调；成功后才停止前端流。 */
+    onInterrupt?: (sessionId: string) => Promise<unknown> | void;
 }
 /**
  * 事件状态码枚举
@@ -129,6 +131,11 @@ export interface XAdkProviderConfig {
      * @default true
      */
     showFeedback?: boolean;
+    /**
+     * 是否启用用户消息 hover 操作栏（时间 + 复制）
+     * @default true
+     */
+    showUserActions?: boolean;
     /**
      * 点击对话中附件卡片的回调（非图片、非音视频文件）
      */

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/types/XAdkProvider.ts"],
-  "sourcesContent": ["import { ReactNode } from \"react\";\nimport {\n  IMessage,\n  Success,\n  Event,\n  Error,\n  SendContent,\n  ThemeType,\n  FileItem,\n  UploadRequestFn,\n} from \"@/types\";\nimport type { ChatPresetInput, ChatStrategies } from \"./ChatStrategies\";\n\nexport interface DebugOptions {\n  url: string;\n  sessionId?: string;\n  config: any;\n  token: string;\n  type?: \"agentDebug\" | \"appDebug\";\n  /**\n   * 是否启用 Hook\n   * 当使用自定义 chatData 时,应设置为 false 以避免内部 Hook 初始化\n   * @default true\n   */\n  enabled?: boolean;\n  strategies?: ChatStrategies;\n  onError?: (error: Error) => void;\n  onSuccess?: (data: Success) => void;\n  onStream?: (data: Event) => void;\n  onMessage?: (content: string, data: IMessage) => void;\n}\n\n/**\n * 事件状态码枚举\n * @enum {string}\n * @version 1.0.0\n */\nexport enum EventCode {\n  /** 切换会话 */\n  SESSION_SWITCH = \"SESSION_SWITCH\",\n  /** 开启新会话 */\n  SESSION_CREATE = \"SESSION_CREATE\",\n}\n\nexport type handleEvent = {\n  code: EventCode;\n  message: string;\n  data?: any;\n};\n/**\n * renderFooter insert 参数说明\n */\nexport interface FooterRenderArgs {\n  message: IMessage;\n  isLastBotMsg: boolean;\n  isLastMsg: boolean;\n}\n\n/**\n * Provider 可通过 ref 暴露的方法句柄\n */\nexport interface XAdkProviderHandle {\n  startChat: (content: SendContent) => void;\n  stopChat: () => void;\n  reChat: () => void;\n  clearChat: () => void;\n  deleteSession: (id: string) => void;\n  updateSession: (id: string, title: string) => void;\n  getAppInfo: () => any;\n  getMessages: () => IMessage[];\n  getSessions: () => any[];\n  setMessages: (msgs: IMessage[]) => void;\n  setCurrentSession: (id: string) => void;\n  /**\n   * 设置自定义业务参数 (stateDelta)\n   * 设置后每次发送消息时会自动携带该参数至后端\n   * 传入 undefined 可清除已设置的参数\n   *\n   * @example\n   * providerRef.current.setStateDelta({ userId: '123', bizType: 'order' });\n   * // 之后发送消息，请求体会携带 stateDelta: { userId: '123', bizType: 'order' }\n   *\n   * @example\n   * // 清除自定义参数\n   * providerRef.current.setStateDelta(undefined);\n   */\n  setStateDelta: (delta: Record<string, any> | undefined) => void;\n}\n\n/**\n * config.chatProps 中的配置\n */\nexport interface ChatConfig {\n  /**\n   * 是否展示清空按钮\n   * @type {boolean}\n   * @default false\n   */\n  clearBtnShow?: boolean;\n  /**\n   * 是否展示输入框\n   * @type {boolean}\n   * @default true\n   */\n  inputShow?: boolean;\n  /**\n   * 打字机效果速度（单位：毫秒）\n   * @type {number}\n   * @default 60\n   * @version 1.0.0\n   */\n  textSpeed?: number;\n}\n\n/**\n * Provider config 整体配置结构\n */\nexport interface XAdkProviderConfig {\n  session?: {\n    showSessionList?: boolean;\n    /** 是否轮询会话详情并主动补入异步任务消息，默认 true */\n    pollSessionEvents?: boolean;\n    /** 会话详情轮询间隔，单位毫秒，默认 10000，最小 1000 */\n    sessionEventsPollingInterval?: number;\n  };\n  /**\n   * 初始化后是否默认展示第一条会话内容\n   * @type {boolean}\n   * @default false\n   */\n  showFirstSession?: boolean;\n  allowUpload?: boolean;\n  /**\n   * 是否启用拖拽上传（需 allowUpload 为 true 时生效）\n   * 拖拽区域为整个聊天区域（不含侧边栏）\n   * @default true\n   */\n  draggable?: boolean;\n  appNo?: string;\n  chatProps?: ChatConfig;\n  debug?: boolean;\n  /**\n   * 是否展示点赞/点踩按钮\n   * @default true\n   */\n  showFeedback?: boolean;\n  /**\n   * 点击对话中附件卡片的回调（非图片、非音视频文件）\n   */\n  onFileClick?: (file: FileItem) => void;\n  /**\n   * 自定义文件上传函数\n   */\n  uploadRequest?: UploadRequestFn;\n  /**\n   * 预设策略。默认 xgroup-adk，用于兼容众安信科现有 ADK 协议。\n   * 传入 base 可获得更中立的组件默认行为。\n   */\n  preset?: ChatPresetInput;\n  /**\n   * 覆盖或补充当前 preset 的局部策略。\n   */\n  strategies?: ChatStrategies;\n}\n\n/**\n * XAdkProvider Props\n */\nexport interface XAdkProviderProps {\n  /**\n   * AI 服务基础地址\n   */\n  url?: string;\n  /**\n   * 认证 token\n   */\n  token: string;\n  /**\n   * 组件功能配置\n   */\n  config?: XAdkProviderConfig;\n  /**\n   * Provider 级预设策略，优先级高于 config.preset。\n   */\n  preset?: ChatPresetInput;\n  /**\n   * Provider 级策略覆盖，优先级高于 config.strategies。\n   */\n  strategies?: ChatStrategies;\n  /**\n   * Provider 唯一标识\n   */\n  providerId?: string;\n  /**\n   * 消息成功回调\n   */\n  onSuccess?: (success: any) => void;\n  /**\n   * 流式消息回调\n   */\n  onStream?: (data: Event) => void;\n  /**\n   * 错误回调\n   */\n  onError?: (err: any) => void;\n  /**\n   * 每条消息回调\n   */\n  onMessage?: (content: string, data: IMessage) => void;\n  /**\n   * 事件回调\n   */\n  onEvent?: (event: handleEvent) => void;\n  /**\n   * React 子元素 - 支持 Compound Components\n   */\n  children?: ReactNode;\n}\n\n// XAiSDKProps 继承 XAdkProviderProps\nexport interface XAdkSDKProps extends XAdkProviderProps {\n  /**\n   * 主题类型\n   * @type {ThemeType}\n   * @default 'default'\n   * @version 1.0.0\n   */\n  theme?: ThemeType;\n\n  /**\n   * 组件属性配置\n   * @type {object}\n   * @default undefined\n   * @version 1.0.0\n   */\n  componentProps?: {\n    /**\n     * 组件ID\n     * @type {string}\n     * @default undefined\n     * @version 1.0.0\n     */\n    id?: string;\n    /** 支持任意 CSS 属性 */\n    [key: string]: any;\n  };\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAqCO,IAAK,YAAL,kBAAKA,eAAL;AAEL,EAAAA,WAAA,oBAAiB;AAEjB,EAAAA,WAAA,oBAAiB;AAJP,SAAAA;AAAA,GAAA;",
+  "sourcesContent": ["import { ReactNode } from \"react\";\nimport {\n  IMessage,\n  Success,\n  Event,\n  Error,\n  SendContent,\n  ThemeType,\n  FileItem,\n  UploadRequestFn,\n} from \"@/types\";\nimport type { ChatPresetInput, ChatStrategies } from \"./ChatStrategies\";\n\nexport interface DebugOptions {\n  url: string;\n  sessionId?: string;\n  config: any;\n  token: string;\n  type?: \"agentDebug\" | \"appDebug\";\n  /**\n   * 是否启用 Hook\n   * 当使用自定义 chatData 时,应设置为 false 以避免内部 Hook 初始化\n   * @default true\n   */\n  enabled?: boolean;\n  strategies?: ChatStrategies;\n  onError?: (error: Error) => void;\n  onSuccess?: (data: Success) => void;\n  onStream?: (data: Event) => void;\n  onMessage?: (content: string, data: IMessage) => void;\n  /** 调用 sendQueuedMessageNow 时可选的后端打断回调；成功后才停止前端流。 */\n  onInterrupt?: (sessionId: string) => Promise<unknown> | void;\n}\n\n/**\n * 事件状态码枚举\n * @enum {string}\n * @version 1.0.0\n */\nexport enum EventCode {\n  /** 切换会话 */\n  SESSION_SWITCH = \"SESSION_SWITCH\",\n  /** 开启新会话 */\n  SESSION_CREATE = \"SESSION_CREATE\",\n}\n\nexport type handleEvent = {\n  code: EventCode;\n  message: string;\n  data?: any;\n};\n/**\n * renderFooter insert 参数说明\n */\nexport interface FooterRenderArgs {\n  message: IMessage;\n  isLastBotMsg: boolean;\n  isLastMsg: boolean;\n}\n\n/**\n * Provider 可通过 ref 暴露的方法句柄\n */\nexport interface XAdkProviderHandle {\n  startChat: (content: SendContent) => void;\n  stopChat: () => void;\n  reChat: () => void;\n  clearChat: () => void;\n  deleteSession: (id: string) => void;\n  updateSession: (id: string, title: string) => void;\n  getAppInfo: () => any;\n  getMessages: () => IMessage[];\n  getSessions: () => any[];\n  setMessages: (msgs: IMessage[]) => void;\n  setCurrentSession: (id: string) => void;\n  /**\n   * 设置自定义业务参数 (stateDelta)\n   * 设置后每次发送消息时会自动携带该参数至后端\n   * 传入 undefined 可清除已设置的参数\n   *\n   * @example\n   * providerRef.current.setStateDelta({ userId: '123', bizType: 'order' });\n   * // 之后发送消息，请求体会携带 stateDelta: { userId: '123', bizType: 'order' }\n   *\n   * @example\n   * // 清除自定义参数\n   * providerRef.current.setStateDelta(undefined);\n   */\n  setStateDelta: (delta: Record<string, any> | undefined) => void;\n}\n\n/**\n * config.chatProps 中的配置\n */\nexport interface ChatConfig {\n  /**\n   * 是否展示清空按钮\n   * @type {boolean}\n   * @default false\n   */\n  clearBtnShow?: boolean;\n  /**\n   * 是否展示输入框\n   * @type {boolean}\n   * @default true\n   */\n  inputShow?: boolean;\n  /**\n   * 打字机效果速度（单位：毫秒）\n   * @type {number}\n   * @default 60\n   * @version 1.0.0\n   */\n  textSpeed?: number;\n}\n\n/**\n * Provider config 整体配置结构\n */\nexport interface XAdkProviderConfig {\n  session?: {\n    showSessionList?: boolean;\n    /** 是否轮询会话详情并主动补入异步任务消息，默认 true */\n    pollSessionEvents?: boolean;\n    /** 会话详情轮询间隔，单位毫秒，默认 10000，最小 1000 */\n    sessionEventsPollingInterval?: number;\n  };\n  /**\n   * 初始化后是否默认展示第一条会话内容\n   * @type {boolean}\n   * @default false\n   */\n  showFirstSession?: boolean;\n  allowUpload?: boolean;\n  /**\n   * 是否启用拖拽上传（需 allowUpload 为 true 时生效）\n   * 拖拽区域为整个聊天区域（不含侧边栏）\n   * @default true\n   */\n  draggable?: boolean;\n  appNo?: string;\n  chatProps?: ChatConfig;\n  debug?: boolean;\n  /**\n   * 是否展示点赞/点踩按钮\n   * @default true\n   */\n  showFeedback?: boolean;\n  /**\n   * 是否启用用户消息 hover 操作栏（时间 + 复制）\n   * @default true\n   */\n  showUserActions?: boolean;\n  /**\n   * 点击对话中附件卡片的回调（非图片、非音视频文件）\n   */\n  onFileClick?: (file: FileItem) => void;\n  /**\n   * 自定义文件上传函数\n   */\n  uploadRequest?: UploadRequestFn;\n  /**\n   * 预设策略。默认 xgroup-adk，用于兼容众安信科现有 ADK 协议。\n   * 传入 base 可获得更中立的组件默认行为。\n   */\n  preset?: ChatPresetInput;\n  /**\n   * 覆盖或补充当前 preset 的局部策略。\n   */\n  strategies?: ChatStrategies;\n}\n\n/**\n * XAdkProvider Props\n */\nexport interface XAdkProviderProps {\n  /**\n   * AI 服务基础地址\n   */\n  url?: string;\n  /**\n   * 认证 token\n   */\n  token: string;\n  /**\n   * 组件功能配置\n   */\n  config?: XAdkProviderConfig;\n  /**\n   * Provider 级预设策略，优先级高于 config.preset。\n   */\n  preset?: ChatPresetInput;\n  /**\n   * Provider 级策略覆盖，优先级高于 config.strategies。\n   */\n  strategies?: ChatStrategies;\n  /**\n   * Provider 唯一标识\n   */\n  providerId?: string;\n  /**\n   * 消息成功回调\n   */\n  onSuccess?: (success: any) => void;\n  /**\n   * 流式消息回调\n   */\n  onStream?: (data: Event) => void;\n  /**\n   * 错误回调\n   */\n  onError?: (err: any) => void;\n  /**\n   * 每条消息回调\n   */\n  onMessage?: (content: string, data: IMessage) => void;\n  /**\n   * 事件回调\n   */\n  onEvent?: (event: handleEvent) => void;\n  /**\n   * React 子元素 - 支持 Compound Components\n   */\n  children?: ReactNode;\n}\n\n// XAiSDKProps 继承 XAdkProviderProps\nexport interface XAdkSDKProps extends XAdkProviderProps {\n  /**\n   * 主题类型\n   * @type {ThemeType}\n   * @default 'default'\n   * @version 1.0.0\n   */\n  theme?: ThemeType;\n\n  /**\n   * 组件属性配置\n   * @type {object}\n   * @default undefined\n   * @version 1.0.0\n   */\n  componentProps?: {\n    /**\n     * 组件ID\n     * @type {string}\n     * @default undefined\n     * @version 1.0.0\n     */\n    id?: string;\n    /** 支持任意 CSS 属性 */\n    [key: string]: any;\n  };\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAuCO,IAAK,YAAL,kBAAKA,eAAL;AAEL,EAAAA,WAAA,oBAAiB;AAEjB,EAAAA,WAAA,oBAAiB;AAJP,SAAAA;AAAA,GAAA;",
   "names": ["EventCode"]
 }

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

@@ -186,6 +186,12 @@ export interface SenderUIProps {
     /** 非受控：输入框默认值 */
     defaultValue?: string;
     onClear?: () => void;
+    /** 清除按钮的二次确认文案；未传时沿用 SDK 默认文案。 */
+    clearConfirm?: {
+        title?: React.ReactNode;
+        okText?: React.ReactNode;
+        cancelText?: React.ReactNode;
+    };
     onChange?: (value: string) => void;
     onSubmit?: (data: XAdkSenderSubmitData) => void;
     onStop?: () => void;
@@ -251,7 +257,8 @@ export interface SenderUIProps {
 }
 export type XAdkSenderProps = SenderUIProps & UploaderCoreProps;
 export interface XAdkSenderHandle {
-    addFiles: (files: File[]) => void;
+    /** 添加本地文件或已上传文件；后者直接进入附件列表，不重复上传。 */
+    addFiles: (files: Array<File | ServerFile>) => void;
     /** 向当前光标位置插入一个内联 Mention；未启用 inlineTags 时会退化为追加 Mention。 */
     insertMention: (mention: MentionTag) => void;
     /** @deprecated 请使用 insertMention。 */

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  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/XAdkThoughtChain.d.ts

@@ -15,6 +15,8 @@ export interface XAdkThoughtChainProps {
     /** @deprecated 使用 status='loading' 替代，保留向后兼容 */
     loading?: boolean;
     title?: ReactNode;
+    /** 当前执行步骤或 Agent 名称，仅在执行中展示 */
+    activeStep?: string;
     items: ThoughtChainItemType[];
     showFnCallDetail?: boolean;
     onConfirm?: (fnCall: any, confirmed: boolean) => void;

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/types/XAdkThoughtChain.ts"],
-  "sourcesContent": ["import React, { type ReactNode } from \"react\";\nimport {\n  IMessage,\n  RenderFunctionCall,\n  ToolRenderKind,\n  ChatStrategies,\n} from \"@/types\";\n\nexport type ThoughtChainStatus = \"pending\" | \"loading\" | \"success\" | \"error\";\n\nexport interface XAdkThoughtChainProps {\n  /** 是否显示外层可折叠 header（默认 false） */\n  collapsible?: boolean;\n  /** 状态枚举，优先级高于 loading（默认 'success'） */\n  status?: ThoughtChainStatus;\n  /** 标准 className */\n  className?: string;\n  /** 标准 style */\n  style?: React.CSSProperties;\n  /** 默认展开状态，仅在 collapsible=true 时生效 */\n  defaultOpen?: boolean;\n  /** @deprecated 使用 status='loading' 替代，保留向后兼容 */\n  loading?: boolean;\n  title?: ReactNode;\n  items: ThoughtChainItemType[];\n  showFnCallDetail?: boolean;\n  onConfirm?: (fnCall: any, confirmed: boolean) => void;\n  blink?: boolean;\n  /** 自定义工具调用渲染函数，返回 null 则使用默认渲染 */\n  renderFunctionCall?: RenderFunctionCall;\n  /**\n   * 工具名 → 渲染类型的解析策略，默认使用 defaultToolKindResolver\n   */\n  toolKindResolver?: (name: string | undefined) => ToolRenderKind;\n  /** 聊天策略，可由 Provider preset 自动下发，也可在组件局部覆盖。 */\n  strategies?: ChatStrategies;\n}\n\nexport interface TimelineItemProps {\n  icon: React.ReactNode;\n  title: React.ReactNode;\n  children: React.ReactNode;\n  collapsible?: boolean;\n  defaultOpen?: boolean;\n  blink?: boolean;\n}\n\nexport interface ThoughtChainItemType {\n  type: \"tool\" | \"text\";\n  key: string;\n  content: string;\n  title?: ReactNode;\n  collapsible?: boolean;\n  msg?: IMessage;\n  /** item 级别状态 */\n  status?: ThoughtChainStatus;\n}\n"],
+  "sourcesContent": ["import React, { type ReactNode } from \"react\";\nimport {\n  IMessage,\n  RenderFunctionCall,\n  ToolRenderKind,\n  ChatStrategies,\n} from \"@/types\";\n\nexport type ThoughtChainStatus = \"pending\" | \"loading\" | \"success\" | \"error\";\n\nexport interface XAdkThoughtChainProps {\n  /** 是否显示外层可折叠 header（默认 false） */\n  collapsible?: boolean;\n  /** 状态枚举，优先级高于 loading（默认 'success'） */\n  status?: ThoughtChainStatus;\n  /** 标准 className */\n  className?: string;\n  /** 标准 style */\n  style?: React.CSSProperties;\n  /** 默认展开状态，仅在 collapsible=true 时生效 */\n  defaultOpen?: boolean;\n  /** @deprecated 使用 status='loading' 替代，保留向后兼容 */\n  loading?: boolean;\n  title?: ReactNode;\n  /** 当前执行步骤或 Agent 名称，仅在执行中展示 */\n  activeStep?: string;\n  items: ThoughtChainItemType[];\n  showFnCallDetail?: boolean;\n  onConfirm?: (fnCall: any, confirmed: boolean) => void;\n  blink?: boolean;\n  /** 自定义工具调用渲染函数，返回 null 则使用默认渲染 */\n  renderFunctionCall?: RenderFunctionCall;\n  /**\n   * 工具名 → 渲染类型的解析策略，默认使用 defaultToolKindResolver\n   */\n  toolKindResolver?: (name: string | undefined) => ToolRenderKind;\n  /** 聊天策略，可由 Provider preset 自动下发，也可在组件局部覆盖。 */\n  strategies?: ChatStrategies;\n}\n\nexport interface TimelineItemProps {\n  icon: React.ReactNode;\n  title: React.ReactNode;\n  children: React.ReactNode;\n  collapsible?: boolean;\n  defaultOpen?: boolean;\n  blink?: boolean;\n}\n\nexport interface ThoughtChainItemType {\n  type: \"tool\" | \"text\";\n  key: string;\n  content: string;\n  title?: ReactNode;\n  collapsible?: boolean;\n  msg?: IMessage;\n  /** item 级别状态 */\n  status?: ThoughtChainStatus;\n}\n"],
   "mappings": ";;;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

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

@@ -3,7 +3,7 @@
  * 从 @ant-design/x 源码提取的公共 API 类型，减少外部依赖
  */
 import type React from 'react';
-import type { UploadFile, MenuProps } from 'antd';
+import type { UploadFile, MenuProps, InputProps } from 'antd';
 export interface ConversationItemType extends Omit<React.HTMLAttributes<HTMLLIElement>, 'onClick'> {
     key: string;
     label?: React.ReactNode;
@@ -41,7 +41,7 @@ export interface ConversationsProps extends React.HTMLAttributes<HTMLUListElemen
     prefixCls?: string;
     rootClassName?: string;
 }
-type TextareaProps = React.ComponentProps<typeof import('antd').Input.TextArea>;
+type TextareaProps = InputProps;
 type SubmitType = 'enter' | 'shiftEnter';
 type SenderSemanticType = 'root' | 'prefix' | 'input' | 'suffix' | 'footer' | 'switch' | 'content';
 export interface SenderComponents {
@@ -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;