@composy/chat-core 0.0.1 → 0.0.2

package/es/types/index.d.ts

@@ -49,6 +49,44 @@ export interface ImageAttachment {
     /** 高度 */
     height?: number;
 }
+/** 结构化消息内容块。未知块应在上游归一化时降级，不得直接执行 HTML。 */
+export type ChatContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'mention';
+    id: string;
+    label: string;
+} | {
+    type: 'link';
+    url: string;
+    label?: string;
+} | {
+    type: 'code';
+    code: string;
+    language?: string;
+} | {
+    type: 'image';
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+} | {
+    type: 'file';
+    url: string;
+    name: string;
+    size?: number;
+    mimeType?: string;
+} | {
+    type: 'break';
+} | {
+    type: 'custom';
+    kind: string;
+    data: Record<string, unknown>;
+    fallback?: string;
+};
+/** 当前消息 schema 版本。 */
+export declare const CHAT_MESSAGE_SCHEMA_VERSION = 1;
 /** 聊天消息 */
 export interface ChatMessage {
     /** 消息唯一 ID */
@@ -67,7 +105,7 @@ export interface ChatMessage {
     file?: FileAttachment;
     /** 自定义数据（custom 类型） */
     customData?: Record<string, unknown>;
-    /** 自定义渲染 HTML（custom 类型） */
+    /** 自定义 HTML（custom 类型）；渲染时会过滤脚本、事件属性、样式和不安全 URL，仅保留受支持的基础标签 */
     customHtml?: string;
     /** 提及列表 */
     mentions?: MentionItem[];
@@ -79,6 +117,18 @@ export interface ChatMessage {
     revoked?: boolean;
     /** 是否正在流式输出（AI 风格） */
     streaming?: boolean;
+    /** 规范化内容块；未提供时使用 content/image/file 等兼容字段。 */
+    contentBlocks?: ChatContentBlock[];
+    /** 消息 schema 版本，便于跨 transport 与持久化迁移。 */
+    schemaVersion?: number;
+    /** 会话标识，用于多会话 transport 复用。 */
+    conversationId?: string;
+    /** 客户端幂等标识，服务端 ack 与离线 outbox 使用。 */
+    clientMessageId?: string;
+    /** 服务端单调序号，用于乱序与重复消息过滤。 */
+    sequence?: number;
+    /** 服务端同步游标。 */
+    cursor?: string;
 }
 /** 主题模式 */
 export type ThemeMode = 'light' | 'dark' | 'auto';
@@ -135,6 +185,16 @@ export interface ChatConfig {
     enableToolbar?: boolean;
     /** 工具栏配置 */
     toolbarConfig?: ToolbarConfig;
+    /** 可选消息 transport；不配置时 Core 仍保持纯本地模式。 */
+    transport?: import('../core/transport').ChatTransport;
+    /** transport 使用的会话标识。 */
+    conversationId?: string;
+    /** 创建实例后自动连接 transport。 */
+    autoConnect?: boolean;
+    /** transport 初始同步游标。 */
+    transportCursor?: string;
+    /** 可选离线 outbox，用于保存发送中的消息并在连接恢复后重试。 */
+    outbox?: import('../core/outbox').ChatOutbox;
     /** 发送消息回调 */
     onSend?: (content: string, mentions: MentionItem[]) => void;
     /** 加载更多回调 */
@@ -162,43 +222,63 @@ export interface ChatConfig {
 /** 聊天实例 */
 export interface ChatInstance {
     /** 添加消息 */
-    addMessage(message: ChatMessage): void;
+    addMessage: (message: ChatMessage) => void;
     /** 批量添加消息（在列表顶部插入，用于加载更多） */
-    prependMessages(messages: ChatMessage[]): void;
+    prependMessages: (messages: ChatMessage[]) => void;
     /** 更新消息 */
-    updateMessage(id: string, updates: Partial<ChatMessage>): void;
+    updateMessage: (id: string, updates: Partial<ChatMessage>) => void;
     /** 删除消息 */
-    removeMessage(id: string): void;
+    removeMessage: (id: string) => void;
     /** 设置完整消息列表 */
-    setMessages(messages: ChatMessage[]): void;
+    setMessages: (messages: ChatMessage[]) => void;
     /** 清空所有消息 */
-    clearMessages(): void;
+    clearMessages: () => void;
     /** 滚动到底部 */
-    scrollToBottom(smooth?: boolean): void;
+    scrollToBottom: (smooth?: boolean) => void;
     /** 设置主题 */
-    setTheme(theme: ThemeMode): void;
+    setTheme: (theme: ThemeMode) => void;
     /** 更新 @提及候选人 */
-    setMentionMembers(members: MentionItem[]): void;
+    setMentionMembers: (members: MentionItem[]) => void;
     /** 设置加载更多状态 */
-    setLoadingMore(loading: boolean): void;
+    setLoadingMore: (loading: boolean) => void;
     /** 聚焦输入框 */
-    focusInput(): void;
+    focusInput: () => void;
     /** 设置输入框内容 */
-    setInputContent(content: string): void;
+    setInputContent: (content: string) => void;
     /** 获取输入框内容 */
-    getInputContent(): string;
-    clearInput(): void;
-    isAtBottom(threshold?: number): boolean;
+    getInputContent: () => string;
+    clearInput: () => void;
+    isAtBottom: (threshold?: number) => boolean;
     /** 监听事件 */
-    on(event: string, handler: (...args: unknown[]) => void): () => void;
+    on: (event: string, handler: (...args: unknown[]) => void) => () => void;
     /** 获取所有消息 */
-    getMessages(): ChatMessage[];
-    /** 追加流式消息内容（AI 模式） */
-    appendMessageContent(id: string, chunk: string): void;
+    getMessages: () => ChatMessage[];
+    /** 追加流式消息内容（AI 模式）；可用 generation/sequence 防止旧 chunk 覆盖新流。 */
+    appendMessageContent: (id: string, chunk: string, options?: {
+        generation?: string;
+        sequence?: number;
+    }) => boolean;
     /** 完成流式消息 */
-    finishStreaming(id: string): void;
-    getMessage(id: string): ChatMessage | undefined;
+    finishStreaming: (id: string, generation?: string) => boolean;
+    /** 开始一个新的流式 generation，旧 generation 的 chunk 会被丢弃。 */
+    beginStreaming: (id: string, generation?: string) => string | null;
+    /** 取消当前流式 generation。 */
+    cancelStreaming: (id: string, generation?: string) => boolean;
+    /** 合并远端消息，按消息 ID/clientMessageId 去重并按 sequence 忽略旧版本。 */
+    mergeMessage: (message: ChatMessage, sequence?: number) => 'added' | 'updated' | 'ignored';
+    /** 连接 transport。 */
+    connectTransport: (signal?: AbortSignal) => Promise<void>;
+    /** 断开 transport。 */
+    disconnectTransport: () => Promise<void>;
+    /** 获取当前 transport 状态。 */
+    getTransportStatus: () => import('../core/transport').ChatTransportStatus;
+    /** 通过 transport 发送消息，失败时保留 failed 状态并交给 outbox 重试。 */
+    sendMessage: (message: ChatMessage, options?: {
+        signal?: AbortSignal;
+    }) => Promise<import('../core/transport').ChatTransportAck | void>;
+    /** 刷新离线 outbox。 */
+    flushOutbox: (options?: import('../core/outbox').ChatOutboxFlushOptions) => Promise<import('../core/outbox').ChatOutboxFlushResult>;
+    getMessage: (id: string) => ChatMessage | undefined;
     /** 销毁实例 */
-    destroy(): void;
+    destroy: () => void;
 }
-//# sourceMappingURL=index.d.ts.map

package/es/types/index.js

@@ -1,10 +1,15 @@
 /*!
 * ***********************************
-* @composy/chat-core v0.0.1       *
+* @composy/chat-core v0.0.2       *
 * Built with rollup               *
-* Build time: 2024-08-17 11:30:32 *
+* Build time: 2024-10-12 21:52:18 *
 * Build mode: production          *
 * Minified: No                    *
 * ***********************************
 */
-/*! End of @composy/chat-core | Powered by @composy/builder */
+//#region src/types/index.ts
+const CHAT_MESSAGE_SCHEMA_VERSION = 1;
+//#endregion
+export { CHAT_MESSAGE_SCHEMA_VERSION };
+/*! End of @composy/chat-core | Powered by @composy/builder */
+//# sourceMappingURL=index.js.map

package/es/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/types/index.ts"],"sourcesContent":["/**\r\n * @composy/chat-core types\r\n */\r\n\r\n// ==================== 消息相关 ====================\r\n\r\n/** 消息类型 */\r\nexport type MessageType = 'text' | 'image' | 'file' | 'system' | 'custom'\r\n\r\n/** 工具栏按钮类型 */\r\nexport type ToolbarAction = 'image' | 'file' | 'voice'\r\n\r\n/** 消息发送状态 */\r\nexport type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read' | 'failed'\r\n\r\n/** 消息方向 */\r\nexport type MessageDirection = 'incoming' | 'outgoing'\r\n\r\n/** 用户信息 */\r\nexport interface ChatUser {\r\n  /** 用户 ID */\r\n  id: string\r\n  /** 昵称 */\r\n  nickname: string\r\n  /** 头像 URL */\r\n  avatar?: string\r\n}\r\n\r\n/** @提及项 */\r\nexport interface MentionItem {\r\n  /** 用户 ID */\r\n  id: string\r\n  /** 显示名称 */\r\n  name: string\r\n  /** 头像 */\r\n  avatar?: string\r\n}\r\n\r\n/** 文件附件 */\r\nexport interface FileAttachment {\r\n  /** 文件名 */\r\n  name: string\r\n  /** 文件大小（字节） */\r\n  size: number\r\n  /** 文件 URL */\r\n  url: string\r\n  /** MIME 类型 */\r\n  mimeType?: string\r\n}\r\n\r\n/** 图片附件 */\r\nexport interface ImageAttachment {\r\n  /** 图片 URL */\r\n  url: string\r\n  /** 缩略图 URL */\r\n  thumbUrl?: string\r\n  /** 宽度 */\r\n  width?: number\r\n  /** 高度 */\r\n  height?: number\r\n}\r\n\r\n/** 结构化消息内容块。未知块应在上游归一化时降级，不得直接执行 HTML。 */\r\nexport type ChatContentBlock =\r\n  | { type: 'text'; text: string }\r\n  | { type: 'mention'; id: string; label: string }\r\n  | { type: 'link'; url: string; label?: string }\r\n  | { type: 'code'; code: string; language?: string }\r\n  | {\r\n      type: 'image'\r\n      src: string\r\n      alt?: string\r\n      width?: number\r\n      height?: number\r\n    }\r\n  | {\r\n      type: 'file'\r\n      url: string\r\n      name: string\r\n      size?: number\r\n      mimeType?: string\r\n    }\r\n  | { type: 'break' }\r\n  | {\r\n      type: 'custom'\r\n      kind: string\r\n      data: Record<string, unknown>\r\n      fallback?: string\r\n    }\r\n\r\n/** 当前消息 schema 版本。 */\r\nexport const CHAT_MESSAGE_SCHEMA_VERSION = 1\r\n\r\n/** 聊天消息 */\r\nexport interface ChatMessage {\r\n  /** 消息唯一 ID */\r\n  id: string\r\n  /** 消息类型 */\r\n  type: MessageType\r\n  /** 消息方向 */\r\n  direction: MessageDirection\r\n  /** 发送者信息 */\r\n  sender: ChatUser\r\n  /** 文本内容（text 类型） */\r\n  content?: string\r\n  /** 图片附件（image 类型） */\r\n  image?: ImageAttachment\r\n  /** 文件附件（file 类型） */\r\n  file?: FileAttachment\r\n  /** 自定义数据（custom 类型） */\r\n  customData?: Record<string, unknown>\r\n  /** 自定义 HTML（custom 类型）；渲染时会过滤脚本、事件属性、样式和不安全 URL，仅保留受支持的基础标签 */\r\n  customHtml?: string\r\n  /** 提及列表 */\r\n  mentions?: MentionItem[]\r\n  /** 发送状态 */\r\n  status?: MessageStatus\r\n  /** 消息时间戳（毫秒） */\r\n  timestamp: number\r\n  /** 是否已撤回 */\r\n  revoked?: boolean\r\n  /** 是否正在流式输出（AI 风格） */\r\n  streaming?: boolean\r\n  /** 规范化内容块；未提供时使用 content/image/file 等兼容字段。 */\r\n  contentBlocks?: ChatContentBlock[]\r\n  /** 消息 schema 版本，便于跨 transport 与持久化迁移。 */\r\n  schemaVersion?: number\r\n  /** 会话标识，用于多会话 transport 复用。 */\r\n  conversationId?: string\r\n  /** 客户端幂等标识，服务端 ack 与离线 outbox 使用。 */\r\n  clientMessageId?: string\r\n  /** 服务端单调序号，用于乱序与重复消息过滤。 */\r\n  sequence?: number\r\n  /** 服务端同步游标。 */\r\n  cursor?: string\r\n}\r\n\r\n// ==================== 主题相关 ====================\r\n\r\n/** 主题模式 */\r\nexport type ThemeMode = 'light' | 'dark' | 'auto'\r\n\r\n// ==================== 工具栏配置 ====================\r\n\r\n/** 工具栏配置 */\r\nexport interface ToolbarConfig {\r\n  /** 启用图片上传按钮 */\r\n  image?: boolean\r\n  /** 启用文件上传按钮 */\r\n  file?: boolean\r\n  /** 启用语音输入按钮 */\r\n  voice?: boolean\r\n}\r\n\r\n// ==================== 配置相关 ====================\r\n\r\n/** 聊天组件配置 */\r\nexport interface ChatConfig {\r\n  /** 挂载容器 */\r\n  container: HTMLElement | string\r\n  /** 当前用户 ID（用于判断消息方向） */\r\n  currentUserId: string\r\n  /** 初始消息列表 */\r\n  messages?: ChatMessage[]\r\n  /** 主题模式 */\r\n  theme?: ThemeMode\r\n  /** 是否显示头像 */\r\n  showAvatar?: boolean\r\n  /** 是否显示昵称 */\r\n  showNickname?: boolean\r\n  /** 是否显示时间 */\r\n  showTimestamp?: boolean\r\n  /** 时间分组间隔（毫秒），默认 300000 (5分钟) */\r\n  timeGroupInterval?: number\r\n  /** 是否显示消息状态 */\r\n  showStatus?: boolean\r\n  /** 是否显示输入框 */\r\n  showInput?: boolean\r\n  /** 输入框占位文本 */\r\n  inputPlaceholder?: string\r\n  /** 是否启用 @提及 */\r\n  enableMention?: boolean\r\n  /** @提及候选人列表 */\r\n  mentionMembers?: MentionItem[]\r\n  /** 是否支持加载更多 */\r\n  enableLoadMore?: boolean\r\n  /** 加载更多文本 */\r\n  loadMoreText?: string\r\n  /** CSS class 前缀 */\r\n  classPrefix?: string\r\n  enterToSend?: boolean\r\n  clearInputOnSend?: boolean\r\n  maxInputLength?: number\r\n  voiceLang?: string\r\n  /** 日期格式化函数 */\r\n  formatTime?: (timestamp: number) => string\r\n  /** 是否启用工具栏 */\r\n  enableToolbar?: boolean\r\n  /** 工具栏配置 */\r\n  toolbarConfig?: ToolbarConfig\r\n  /** 可选消息 transport；不配置时 Core 仍保持纯本地模式。 */\r\n  transport?: import('../core/transport').ChatTransport\r\n  /** transport 使用的会话标识。 */\r\n  conversationId?: string\r\n  /** 创建实例后自动连接 transport。 */\r\n  autoConnect?: boolean\r\n  /** transport 初始同步游标。 */\r\n  transportCursor?: string\r\n  /** 可选离线 outbox，用于保存发送中的消息并在连接恢复后重试。 */\r\n  outbox?: import('../core/outbox').ChatOutbox\r\n\r\n  // 回调\r\n  /** 发送消息回调 */\r\n  onSend?: (content: string, mentions: MentionItem[]) => void\r\n  /** 加载更多回调 */\r\n  onLoadMore?: () => void | Promise<void>\r\n  /** 消息点击回调 */\r\n  onMessageClick?: (message: ChatMessage) => void\r\n  /** @提及选择回调 */\r\n  onMentionSelect?: (member: MentionItem) => void\r\n  /** 图片上传回调（接收 File 列表） */\r\n  onImageUpload?: (files: File[]) => void\r\n  /** 文件上传回调（接收 File 列表） */\r\n  onFileUpload?: (files: File[]) => void\r\n  /** 粘贴回调（接收文件列表） */\r\n  onPaste?: (files: File[]) => void\r\n  /** 拖放回调（接收文件列表） */\r\n  onDrop?: (files: File[]) => void\r\n  /** 语音开始回调 */\r\n  onVoiceStart?: () => void\r\n  /** 语音结束回调（接收识别文本） */\r\n  onVoiceEnd?: (transcript: string) => void\r\n  onVoiceUnsupported?: () => void\r\n  onVoiceError?: (error: unknown) => void\r\n  onInputChange?: (content: string) => void\r\n}\r\n\r\n/** 聊天实例 */\r\nexport interface ChatInstance {\r\n  /** 添加消息 */\r\n  addMessage: (message: ChatMessage) => void\r\n  /** 批量添加消息（在列表顶部插入，用于加载更多） */\r\n  prependMessages: (messages: ChatMessage[]) => void\r\n  /** 更新消息 */\r\n  updateMessage: (id: string, updates: Partial<ChatMessage>) => void\r\n  /** 删除消息 */\r\n  removeMessage: (id: string) => void\r\n  /** 设置完整消息列表 */\r\n  setMessages: (messages: ChatMessage[]) => void\r\n  /** 清空所有消息 */\r\n  clearMessages: () => void\r\n  /** 滚动到底部 */\r\n  scrollToBottom: (smooth?: boolean) => void\r\n  /** 设置主题 */\r\n  setTheme: (theme: ThemeMode) => void\r\n  /** 更新 @提及候选人 */\r\n  setMentionMembers: (members: MentionItem[]) => void\r\n  /** 设置加载更多状态 */\r\n  setLoadingMore: (loading: boolean) => void\r\n  /** 聚焦输入框 */\r\n  focusInput: () => void\r\n  /** 设置输入框内容 */\r\n  setInputContent: (content: string) => void\r\n  /** 获取输入框内容 */\r\n  getInputContent: () => string\r\n  clearInput: () => void\r\n  isAtBottom: (threshold?: number) => boolean\r\n  /** 监听事件 */\r\n  on: (event: string, handler: (...args: unknown[]) => void) => () => void\r\n  /** 获取所有消息 */\r\n  getMessages: () => ChatMessage[]\r\n  /** 追加流式消息内容（AI 模式）；可用 generation/sequence 防止旧 chunk 覆盖新流。 */\r\n  appendMessageContent: (\r\n    id: string,\r\n    chunk: string,\r\n    options?: { generation?: string; sequence?: number }\r\n  ) => boolean\r\n  /** 完成流式消息 */\r\n  finishStreaming: (id: string, generation?: string) => boolean\r\n  /** 开始一个新的流式 generation，旧 generation 的 chunk 会被丢弃。 */\r\n  beginStreaming: (id: string, generation?: string) => string | null\r\n  /** 取消当前流式 generation。 */\r\n  cancelStreaming: (id: string, generation?: string) => boolean\r\n  /** 合并远端消息，按消息 ID/clientMessageId 去重并按 sequence 忽略旧版本。 */\r\n  mergeMessage: (\r\n    message: ChatMessage,\r\n    sequence?: number\r\n  ) => 'added' | 'updated' | 'ignored'\r\n  /** 连接 transport。 */\r\n  connectTransport: (signal?: AbortSignal) => Promise<void>\r\n  /** 断开 transport。 */\r\n  disconnectTransport: () => Promise<void>\r\n  /** 获取当前 transport 状态。 */\r\n  getTransportStatus: () => import('../core/transport').ChatTransportStatus\r\n  /** 通过 transport 发送消息，失败时保留 failed 状态并交给 outbox 重试。 */\r\n  sendMessage: (\r\n    message: ChatMessage,\r\n    options?: { signal?: AbortSignal }\r\n  ) => Promise<import('../core/transport').ChatTransportAck | void>\r\n  /** 刷新离线 outbox。 */\r\n  flushOutbox: (\r\n    options?: import('../core/outbox').ChatOutboxFlushOptions\r\n  ) => Promise<import('../core/outbox').ChatOutboxFlushResult>\r\n  getMessage: (id: string) => ChatMessage | undefined\r\n  /** 销毁实例 */\r\n  destroy: () => void\r\n}\r\n"],"mappings":";;;;;;;;;;AA2FO,MAAM,8BAA8B"}

package/esm/constants/dom.d.ts

@@ -5,37 +5,21 @@
 export declare const DEFAULT_CLASS_PREFIX = "ldesign-chat";
 export declare const COMPONENT_CSS_VAR_PREFIX = "--ldesign-chat";
 export declare const STYLE_ELEMENT_ID = "ldesign-chat-styles";
-/**
- * normalizeClassPrefix 函数
- * @param prefix? - 参数
- * @returns 返回值
- */
 /**
  * normalizeClassPrefix - normalize Class Prefix function
- * @param prefix? - 参数说明
+ * @param prefix - Optional class prefix
  * @returns 返回值说明
  */
 export declare function normalizeClassPrefix(prefix?: string): string;
-/**
- * getStyleElementId 函数
- * @param prefix = DEFAULT_CLASS_PREFIX - 参数
- * @returns 返回值
- */
 /**
  * getStyleElementId - get Style Element Id function
- * @param prefix = DEFAULT_CLASS_PREFIX - 参数说明
+ * @param prefix - Class prefix
  * @returns 返回值说明
  */
 export declare function getStyleElementId(prefix?: string): string;
-/**
- * cx 函数
- * @param ...classes - 参数
- * @returns 返回值
- */
 /**
  * cx - cx function
- * @param ...classes - 参数说明
+ * @param classes - Class names to join
  * @returns 返回值说明
  */
 export declare function cx(...classes: (string | false | null | undefined)[]): string;
-//# sourceMappingURL=dom.d.ts.map

package/esm/constants/dom.js

@@ -1,8 +1,8 @@
 /*!
 * ***********************************
-* @composy/chat-core v0.0.1       *
+* @composy/chat-core v0.0.2       *
 * Built with rollup               *
-* Build time: 2024-08-17 11:30:32 *
+* Build time: 2024-10-12 21:52:18 *
 * Build mode: production          *
 * Minified: No                    *
 * ***********************************
@@ -14,8 +14,8 @@ const STYLE_ELEMENT_ID = "ldesign-chat-styles";
 function normalizeClassPrefix(prefix) {
 	const trimmed = prefix?.trim();
 	if (!trimmed) return DEFAULT_CLASS_PREFIX;
-	if (trimmed.startsWith("ldesign-")) return trimmed;
-	return `ldesign-${trimmed.replace(/^-+/, "")}`;
+	const safeSuffix = trimmed.replace(/^ldesign-/i, "").replace(/[^\w-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+	return safeSuffix ? `ldesign-${safeSuffix}` : DEFAULT_CLASS_PREFIX;
 }
 function getStyleElementId(prefix = DEFAULT_CLASS_PREFIX) {
 	const normalized = normalizeClassPrefix(prefix);

package/esm/constants/dom.js.map

@@ -1 +1 @@
-{"version":3,"file":"dom.js","names":[],"sources":["../../src/constants/dom.ts"],"sourcesContent":["/**\n * @file dom.ts\n * @description dom 模块\n */\n\nexport const DEFAULT_CLASS_PREFIX = 'ldesign-chat';\nexport const COMPONENT_CSS_VAR_PREFIX = '--ldesign-chat';\nexport const STYLE_ELEMENT_ID = 'ldesign-chat-styles';\n\n/**\n * normalizeClassPrefix 函数\n * @param prefix? - 参数\n * @returns 返回值\n */\n/**\n * normalizeClassPrefix - normalize Class Prefix function\n * @param prefix? - 参数说明\n * @returns 返回值说明\n */\nexport function normalizeClassPrefix(prefix?: string): string {\n  const trimmed = prefix?.trim();\n  if (!trimmed) return DEFAULT_CLASS_PREFIX;\n  if (trimmed.startsWith('ldesign-')) return trimmed;\n  return `ldesign-${trimmed.replace(/^-+/, '')}`;\n}\n\n/**\n * getStyleElementId 函数\n * @param prefix = DEFAULT_CLASS_PREFIX - 参数\n * @returns 返回值\n */\n/**\n * getStyleElementId - get Style Element Id function\n * @param prefix = DEFAULT_CLASS_PREFIX - 参数说明\n * @returns 返回值说明\n */\nexport function getStyleElementId(prefix = DEFAULT_CLASS_PREFIX): string {\n  const normalized = normalizeClassPrefix(prefix);\n  return normalized === DEFAULT_CLASS_PREFIX\n    ? STYLE_ELEMENT_ID\n    : `${normalized}-styles`;\n}\n\n/**\n * cx 函数\n * @param ...classes - 参数\n * @returns 返回值\n */\n/**\n * cx - cx function\n * @param ...classes - 参数说明\n * @returns 返回值说明\n */\nexport function cx(...classes: (string | false | null | undefined)[]): string {\n  return classes.filter(Boolean).join(' ');\n}\n"],"mappings":";;;;;;;;;;AAKO,MAAM,uBAAuB;AAC7B,MAAM,2BAA2B;AACjC,MAAM,mBAAmB;AAYzB,SAAS,qBAAqB,QAAyB;CAC5D,MAAM,UAAU,QAAQ,KAAK;CAC7B,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,QAAQ,WAAW,UAAU,GAAG,OAAO;CAC3C,OAAO,WAAW,QAAQ,QAAQ,OAAO,EAAE;AAC7C;AAYO,SAAS,kBAAkB,SAAS,sBAA8B;CACvE,MAAM,aAAa,qBAAqB,MAAM;CAC9C,OAAO,eAAA,iBACH,mBACA,GAAG,WAAU;AACnB;AAYO,SAAS,GAAA,GAAM,SAAwD;CAC5E,OAAO,QAAQ,OAAO,OAAO,CAAA,CAAE,KAAK,GAAG;AACzC"}
+{"version":3,"file":"dom.js","names":[],"sources":["../../src/constants/dom.ts"],"sourcesContent":["/**\r\n * @file dom.ts\r\n * @description dom 模块\r\n */\r\n\r\nexport const DEFAULT_CLASS_PREFIX = 'ldesign-chat'\r\nexport const COMPONENT_CSS_VAR_PREFIX = '--ldesign-chat'\r\nexport const STYLE_ELEMENT_ID = 'ldesign-chat-styles'\r\n\r\n/**\r\n * normalizeClassPrefix - normalize Class Prefix function\r\n * @param prefix - Optional class prefix\r\n * @returns 返回值说明\r\n */\r\nexport function normalizeClassPrefix(prefix?: string): string {\r\n  const trimmed = prefix?.trim()\r\n  if (!trimmed) return DEFAULT_CLASS_PREFIX\r\n\r\n  const withoutNamespace = trimmed\r\n    .replace(/^ldesign-/i, '')\r\n    .replace(/[^\\w-]+/g, '-')\r\n  const safeSuffix = withoutNamespace.replace(/-+/g, '-').replace(/^-|-$/g, '')\r\n  return safeSuffix ? `ldesign-${safeSuffix}` : DEFAULT_CLASS_PREFIX\r\n}\r\n\r\n/**\r\n * getStyleElementId - get Style Element Id function\r\n * @param prefix - Class prefix\r\n * @returns 返回值说明\r\n */\r\nexport function getStyleElementId(prefix = DEFAULT_CLASS_PREFIX): string {\r\n  const normalized = normalizeClassPrefix(prefix)\r\n  return normalized === DEFAULT_CLASS_PREFIX\r\n    ? STYLE_ELEMENT_ID\r\n    : `${normalized}-styles`\r\n}\r\n\r\n/**\r\n * cx - cx function\r\n * @param classes - Class names to join\r\n * @returns 返回值说明\r\n */\r\nexport function cx(...classes: (string | false | null | undefined)[]): string {\r\n  return classes.filter(Boolean).join(' ')\r\n}\r\n"],"mappings":";;;;;;;;;;AAKO,MAAM,uBAAuB;AAC7B,MAAM,2BAA2B;AACjC,MAAM,mBAAmB;AAOzB,SAAS,qBAAqB,QAAyB;CAC5D,MAAM,UAAU,QAAQ,KAAK;CAC7B,IAAI,CAAC,SAAS,OAAO;CAKrB,MAAM,aAHmB,QACtB,QAAQ,cAAc,EAAE,CAAA,CACxB,QAAQ,YAAY,GACJ,CAAA,CAAiB,QAAQ,OAAO,GAAG,CAAA,CAAE,QAAQ,UAAU,EAAE;CAC5E,OAAO,aAAa,WAAW,eAAe;AAChD;AAOO,SAAS,kBAAkB,SAAS,sBAA8B;CACvE,MAAM,aAAa,qBAAqB,MAAM;CAC9C,OAAO,eAAA,iBACH,mBACA,GAAG,WAAU;AACnB;AAOO,SAAS,GAAA,GAAM,SAAwD;CAC5E,OAAO,QAAQ,OAAO,OAAO,CAAA,CAAE,KAAK,GAAG;AACzC"}

package/esm/core/chat-manager.d.ts

@@ -1,34 +1,45 @@
-/**
- * 聊天管理器 - 消息增删改查、状态管理
- */
-import type { ChatMessage } from '../types';
-import { EventEmitter } from './event-emitter';
-/**
- * ChatManager - Chat Manager class
- */
+import type { ChatMessage, MessageStatus } from '../types';
+import type { EventEmitter } from './event-emitter';
+export type MessageMergeResult = 'added' | 'updated' | 'ignored';
+export interface MessageMergeOptions {
+    sequence?: number;
+    source?: 'local' | 'remote';
+}
+export interface StreamAppendOptions {
+    generation?: string;
+    sequence?: number;
+}
+/** ChatManager - 聊天消息状态、幂等合并和流式 generation 管理。 */
 export declare class ChatManager {
     private messages;
-    private emitter;
+    private readonly emitter;
+    private readonly streams;
     constructor(emitter: EventEmitter, initialMessages?: ChatMessage[]);
-    /** 获取所有消息 */
     getMessages(): ChatMessage[];
-    /** 根据 ID 获取消息 */
     getMessage(id: string): ChatMessage | undefined;
-    /** 添加消息（末尾追加） */
+    getMessageIdByClientMessageId(clientMessageId: string): string | undefined;
     addMessage(message: ChatMessage): void;
-    /** 在顶部批量插入消息（用于加载更多） */
     prependMessages(messages: ChatMessage[]): void;
-    /** 更新消息 */
+    /** 合并本地 ack 或远端推送，按 id/clientMessageId 去重并拒绝旧 sequence。 */
+    upsertMessage(message: ChatMessage, options?: MessageMergeOptions): MessageMergeResult;
+    mergeMessages(messages: ChatMessage[], options?: MessageMergeOptions): {
+        added: number;
+        updated: number;
+        ignored: number;
+    };
     updateMessage(id: string, updates: Partial<ChatMessage>): void;
-    /** 删除消息 */
+    markMessageStatus(id: string, status: MessageStatus): void;
     removeMessage(id: string): void;
-    /** 替换全部消息 */
     setMessages(messages: ChatMessage[]): void;
-    /** 清空所有消息 */
     clearMessages(): void;
-    /** 追加流式消息内容 */
-    appendMessageContent(id: string, chunk: string): void;
-    /** 完成流式消息 */
-    finishStreaming(id: string): void;
+    beginStreaming(id: string, generation?: string): string | null;
+    appendMessageContent(id: string, chunk: string, options?: StreamAppendOptions): boolean;
+    finishStreaming(id: string, generation?: string): boolean;
+    cancelStreaming(id: string, generation?: string): boolean;
+    getStreamGeneration(id: string): string | undefined;
+    private findMessageIndex;
+    private assertUniqueIds;
+    private assertUniqueClientMessageId;
+    private emitAdded;
+    private emitChanged;
 }
-//# sourceMappingURL=chat-manager.d.ts.map

package/esm/core/chat-manager.js

@@ -1,92 +1,216 @@
 /*!
 * ***********************************
-* @composy/chat-core v0.0.1       *
+* @composy/chat-core v0.0.2       *
 * Built with rollup               *
-* Build time: 2024-08-17 11:30:32 *
+* Build time: 2024-10-12 21:52:18 *
 * Build mode: production          *
 * Minified: No                    *
 * ***********************************
 */
+import { cloneChatMessage, normalizeChatMessage, normalizeChatMessages } from "./message-schema.js";
 //#region src/core/chat-manager.ts
 var ChatManager = class {
 	constructor(emitter, initialMessages) {
 		this.messages = [];
+		this.streams = /* @__PURE__ */ new Map();
 		this.emitter = emitter;
-		if (initialMessages?.length) this.messages = [...initialMessages];
+		if (initialMessages?.length) this.messages = normalizeChatMessages(initialMessages);
 	}
-	/** 获取所有消息 */
 	getMessages() {
-		return [...this.messages];
+		return this.messages.map(cloneChatMessage);
 	}
-	/** 根据 ID 获取消息 */
 	getMessage(id) {
-		return this.messages.find((m) => m.id === id);
+		const message = this.messages.find((item) => item.id === id);
+		return message ? cloneChatMessage(message) : void 0;
+	}
+	getMessageIdByClientMessageId(clientMessageId) {
+		return this.messages.find((message) => message.clientMessageId === clientMessageId)?.id;
 	}
-	/** 添加消息（末尾追加） */
 	addMessage(message) {
-		this.messages.push(message);
-		this.emitter.emit("message-added", message);
-		this.emitter.emit("messages-changed", this.getMessages());
+		const storedMessage = normalizeChatMessage(message);
+		this.assertUniqueIds([storedMessage]);
+		this.messages.push(storedMessage);
+		this.emitAdded(storedMessage);
 	}
-	/** 在顶部批量插入消息（用于加载更多） */
 	prependMessages(messages) {
-		this.messages.unshift(...messages);
-		this.emitter.emit("messages-prepended", messages);
-		this.emitter.emit("messages-changed", this.getMessages());
+		const storedMessages = normalizeChatMessages(messages);
+		this.assertUniqueIds(storedMessages);
+		this.messages.unshift(...storedMessages);
+		this.emitter.emit("messages-prepended", storedMessages.map(cloneChatMessage));
+		this.emitChanged();
+	}
+	/** 合并本地 ack 或远端推送，按 id/clientMessageId 去重并拒绝旧 sequence。 */
+	upsertMessage(message, options = {}) {
+		const normalized = normalizeChatMessage({
+			...message,
+			...options.sequence !== void 0 && { sequence: options.sequence }
+		});
+		const index = this.findMessageIndex(normalized);
+		if (index < 0) {
+			this.messages.push(normalized);
+			this.emitAdded(normalized);
+			return "added";
+		}
+		const current = this.messages[index];
+		if (Number.isFinite(normalized.sequence) && Number.isFinite(current.sequence) && normalized.sequence <= current.sequence) return "ignored";
+		const merged = normalizeChatMessage({
+			...current,
+			...normalized,
+			id: current.id,
+			clientMessageId: normalized.clientMessageId ?? current.clientMessageId,
+			sequence: normalized.sequence ?? current.sequence
+		});
+		this.messages[index] = merged;
+		this.emitter.emit("message-updated", cloneChatMessage(merged));
+		this.emitChanged();
+		return "updated";
+	}
+	mergeMessages(messages, options = {}) {
+		const result = {
+			added: 0,
+			updated: 0,
+			ignored: 0
+		};
+		for (const message of messages) {
+			const outcome = this.upsertMessage(message, options);
+			result[outcome] += 1;
+		}
+		return result;
 	}
-	/** 更新消息 */
 	updateMessage(id, updates) {
-		const index = this.messages.findIndex((m) => m.id === id);
+		const index = this.messages.findIndex((message) => message.id === id);
 		if (index === -1) return;
-		this.messages[index] = {
+		if (updates.id !== void 0 && updates.id !== id) throw new Error("Chat message IDs are immutable.");
+		const next = normalizeChatMessage({
 			...this.messages[index],
-			...updates
-		};
-		this.emitter.emit("message-updated", this.messages[index]);
-		this.emitter.emit("messages-changed", this.getMessages());
+			...updates,
+			id
+		});
+		this.assertUniqueClientMessageId(next, id);
+		this.messages[index] = next;
+		this.emitter.emit("message-updated", cloneChatMessage(next));
+		this.emitChanged();
+	}
+	markMessageStatus(id, status) {
+		this.updateMessage(id, { status });
 	}
-	/** 删除消息 */
 	removeMessage(id) {
-		const index = this.messages.findIndex((m) => m.id === id);
+		const index = this.messages.findIndex((message) => message.id === id);
 		if (index === -1) return;
-		const removed = this.messages.splice(index, 1)[0];
-		this.emitter.emit("message-removed", removed);
-		this.emitter.emit("messages-changed", this.getMessages());
+		const [removed] = this.messages.splice(index, 1);
+		this.streams.delete(id);
+		this.emitter.emit("message-removed", cloneChatMessage(removed));
+		this.emitChanged();
 	}
-	/** 替换全部消息 */
 	setMessages(messages) {
-		this.messages = [...messages];
-		this.emitter.emit("messages-changed", this.getMessages());
+		this.messages = normalizeChatMessages(messages);
+		this.streams.clear();
+		this.emitChanged();
 	}
-	/** 清空所有消息 */
 	clearMessages() {
 		this.messages = [];
-		this.emitter.emit("messages-changed", []);
+		this.streams.clear();
+		this.emitChanged();
 	}
-	/** 追加流式消息内容 */
-	appendMessageContent(id, chunk) {
-		const index = this.messages.findIndex((m) => m.id === id);
-		if (index === -1) return;
-		const msg = this.messages[index];
-		this.messages[index] = {
-			...msg,
-			content: (msg.content ?? "") + chunk
-		};
-		this.emitter.emit("message-content-appended", id, this.messages[index].content);
-		this.emitter.emit("messages-changed", this.getMessages());
+	beginStreaming(id, generation = createGeneration()) {
+		const index = this.messages.findIndex((message) => message.id === id);
+		if (index === -1) return null;
+		this.streams.set(id, {
+			generation,
+			lastSequence: -1
+		});
+		this.messages[index] = normalizeChatMessage({
+			...this.messages[index],
+			streaming: true
+		});
+		this.emitter.emit("message-updated", cloneChatMessage(this.messages[index]));
+		this.emitChanged();
+		return generation;
 	}
-	/** 完成流式消息 */
-	finishStreaming(id) {
-		const index = this.messages.findIndex((m) => m.id === id);
-		if (index === -1) return;
-		this.messages[index] = {
+	appendMessageContent(id, chunk, options = {}) {
+		const stream = this.streams.get(id);
+		if (options.generation) {
+			if (!stream || stream.generation !== options.generation) return false;
+			const sequence = options.sequence;
+			if (sequence !== void 0 && Number.isFinite(sequence) && sequence <= stream.lastSequence) return false;
+			if (sequence !== void 0 && Number.isFinite(sequence)) stream.lastSequence = sequence;
+		}
+		const index = this.messages.findIndex((message2) => message2.id === id);
+		if (index === -1) return false;
+		const message = this.messages[index];
+		this.messages[index] = normalizeChatMessage({
+			...message,
+			content: (message.content ?? "") + chunk,
+			streaming: options.generation ? true : message.streaming
+		});
+		this.emitter.emit("message-content-appended", id, this.messages[index].content, options.generation, options.sequence);
+		this.emitChanged();
+		return true;
+	}
+	finishStreaming(id, generation) {
+		const stream = this.streams.get(id);
+		if (generation && (!stream || stream.generation !== generation)) return false;
+		const index = this.messages.findIndex((message) => message.id === id);
+		if (index === -1) return false;
+		this.messages[index] = normalizeChatMessage({
 			...this.messages[index],
 			streaming: false
-		};
-		this.emitter.emit("message-updated", this.messages[index]);
+		});
+		this.streams.delete(id);
+		this.emitter.emit("message-updated", cloneChatMessage(this.messages[index]));
+		this.emitChanged();
+		return true;
+	}
+	cancelStreaming(id, generation) {
+		const stream = this.streams.get(id);
+		if (generation && (!stream || stream.generation !== generation)) return false;
+		const index = this.messages.findIndex((message) => message.id === id);
+		if (index === -1) return false;
+		this.streams.delete(id);
+		this.messages[index] = normalizeChatMessage({
+			...this.messages[index],
+			streaming: false
+		});
+		this.emitter.emit("stream-cancelled", cloneChatMessage(this.messages[index]));
+		this.emitter.emit("message-updated", cloneChatMessage(this.messages[index]));
+		this.emitChanged();
+		return true;
+	}
+	getStreamGeneration(id) {
+		return this.streams.get(id)?.generation;
+	}
+	findMessageIndex(message) {
+		const byId = this.messages.findIndex((item) => item.id === message.id);
+		if (byId >= 0) return byId;
+		if (!message.clientMessageId) return -1;
+		return this.messages.findIndex((item) => item.clientMessageId === message.clientMessageId);
+	}
+	assertUniqueIds(messages) {
+		const ids = new Set(this.messages.map((message) => message.id));
+		const clientIds = new Set(this.messages.flatMap((message) => message.clientMessageId ? [message.clientMessageId] : []));
+		for (const message of messages) {
+			if (!message.id || ids.has(message.id)) throw new Error(`Chat message ID must be non-empty and unique: ${message.id}`);
+			if (message.clientMessageId && clientIds.has(message.clientMessageId)) throw new Error(`Chat client message ID must be unique: ${message.clientMessageId}`);
+			ids.add(message.id);
+			if (message.clientMessageId) clientIds.add(message.clientMessageId);
+		}
+	}
+	assertUniqueClientMessageId(message, ownId) {
+		if (message.clientMessageId && this.messages.some((item) => item.id !== ownId && item.clientMessageId === message.clientMessageId)) throw new Error(`Chat client message ID must be unique: ${message.clientMessageId}`);
+	}
+	emitAdded(message) {
+		this.emitter.emit("message-added", cloneChatMessage(message));
+		this.emitChanged();
+	}
+	emitChanged() {
 		this.emitter.emit("messages-changed", this.getMessages());
 	}
 };
+function createGeneration() {
+	const cryptoObject = globalThis.crypto;
+	if (cryptoObject?.randomUUID) return cryptoObject.randomUUID();
+	return `stream-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
 //#endregion
 export { ChatManager };
 /*! End of @composy/chat-core | Powered by @composy/builder */