feat: 完成管理端聊天工作台收口

- 新增管理端聊天工作台与会话级额外知识库持久化 - 补齐发布态聊天、历史会话只读判断与答案版本切换 - 新增 chat_round 热数据与主线消息读取支撑
2026-05-14 20:22:46 +08:00
parent 2ad8935a61
commit 47c2bad839
63 changed files with 8609 additions and 136 deletions
--- a/easyflow-ui-admin/packages/types/src/chat-time.ts
+++ b/easyflow-ui-admin/packages/types/src/chat-time.ts
@@ -2,14 +2,31 @@ type ChatTimeTimelineRole = 'assistant' | 'tool' | 'user';
 type ChatTimeToolStatus = 'TOOL_CALL' | 'TOOL_RESULT';
 type ChatTimeThinkingStatus = 'end' | 'thinking';

+interface ChatTimeRoundMeta {
+  messageKind?: string;
+  roundId?: number | string;
+  roundNo?: number;
+  selectedVariantIndex?: number;
+  switchable?: boolean;
+  variantCount?: number;
+  variantIndex?: number;
+}
+
 interface ChatTimeTimelineItemBase {
  created: number | string;
  id: string;
  loading?: boolean;
+  messageKind?: string;
  placement: 'end' | 'start';
+  roundId?: string;
+  roundNo?: number;
  role: ChatTimeTimelineRole;
+  selectedVariantIndex?: number;
  senderName?: string;
+  switchable?: boolean;
  typing?: boolean;
+  variantCount?: number;
+  variantIndex?: number;
 }

 interface ChatTimeAssistantThinkingSegment {
@@ -66,14 +83,22 @@ interface ChatTimeHistoryRecord {
  loading?: boolean;
  placement?: 'end' | 'start';
  role?: string;
+  roundId?: number | string;
+  roundNo?: number;
+  selectedVariantIndex?: number;
  senderName?: string;
  senderRole?: string;
+  switchable?: boolean;
  typing?: boolean;
+  variantCount?: number;
+  variantIndex?: number;
+  messageKind?: string;
 }

-interface ChatTimeToolMutationPayload {
+interface ChatTimeToolMutationPayload extends ChatTimeRoundMeta {
  created?: number | string;
  name?: string;
+  regenerate?: boolean;
  result?: any;
  toolCallId?: string;
  value?: any;
@@ -85,6 +110,7 @@ export type {
  ChatTimeAssistantTextSegment,
  ChatTimeAssistantThinkingSegment,
  ChatTimeHistoryRecord,
+  ChatTimeRoundMeta,
  ChatTimeThinkingStatus,
  ChatTimeTimelineItem,
  ChatTimeTimelineItemBase,
--- a/easyflow-ui-admin/packages/utils/src/helpers/chat-time.ts
+++ b/easyflow-ui-admin/packages/utils/src/helpers/chat-time.ts
@@ -1,8 +1,10 @@
 import type {
  ChatTimeAssistantItem,
  ChatTimeHistoryRecord,
+  ChatTimeRoundMeta,
  ChatTimeThinkingStatus,
  ChatTimeTimelineItem,
+  ChatTimeTimelineItemBase,
  ChatTimeToolItem,
  ChatTimeToolMutationPayload,
  ChatTimeToolStatus,
@@ -28,17 +30,71 @@ class ChatTimeTimelineBuilder {
      content?: string;
      created?: number | string;
      id?: string;
+      messageKind?: string;
+      roundId?: number | string;
+      roundNo?: number;
      senderName?: string;
    },
  ) {
-    items.push({
+    const item: ChatTimeTimelineItem = {
      content: normalizePlainText(payload.content),
      created: normalizeTimestamp(payload.created),
      id: payload.id || uuid(),
      placement: 'end',
      role: 'user',
      senderName: payload.senderName,
-    });
+    };
+    applyRoundMeta(item, payload);
+    items.push(item);
+  }
+
+  /**
+   * 将最新一条待绑定的用户消息补齐到当前轮次。
+   */
+  static bindLatestPendingUserMessage(
+    items: ChatTimeTimelineItem[],
+    meta?: ChatTimeRoundMeta,
+  ) {
+    const roundId = normalizeRoundId(meta?.roundId);
+    if (!roundId) {
+      return;
+    }
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+      const item = items[index];
+      if (!item) {
+        continue;
+      }
+      if (item.role !== 'user') {
+        continue;
+      }
+      if (item.roundId) {
+        return;
+      }
+      applyRoundMeta(item, {
+        roundId,
+        roundNo: meta?.roundNo,
+      });
+      return;
+    }
+  }
+
+  /**
+   * 更新指定轮次的可切换状态。
+   */
+  static setRoundSwitchable(
+    items: ChatTimeTimelineItem[],
+    roundId: number | string | undefined,
+    switchable: boolean,
+  ) {
+    const normalizedRoundId = normalizeRoundId(roundId);
+    if (!normalizedRoundId) {
+      return;
+    }
+    for (const item of items) {
+      if (item.roundId === normalizedRoundId && item.role !== 'user') {
+        item.switchable = switchable;
+      }
+    }
  }

  /**
@@ -48,12 +104,14 @@ class ChatTimeTimelineBuilder {
    items: ChatTimeTimelineItem[],
    delta?: string,
    created?: number | string,
+    meta?: ChatTimeRoundMeta,
  ) {
    const normalizedDelta = normalizePlainText(delta);
    if (!normalizedDelta) {
      return;
    }
-    const assistant = ensureAssistantTail(items, created);
+    prepareRoundVariant(items, meta);
+    const assistant = ensureAssistantTail(items, created, meta);
    const tail = assistant.segments[assistant.segments.length - 1];
    if (tail?.type === 'thinking' && tail.status === 'thinking') {
      tail.content += normalizedDelta;
@@ -77,12 +135,14 @@ class ChatTimeTimelineBuilder {
    items: ChatTimeTimelineItem[],
    delta?: string,
    created?: number | string,
+    meta?: ChatTimeRoundMeta,
  ) {
    const normalizedDelta = normalizeAssistantText(delta);
    if (!normalizedDelta) {
      return;
    }
-    const assistant = ensureAssistantTail(items, created);
+    prepareRoundVariant(items, meta);
+    const assistant = ensureAssistantTail(items, created, meta);
    stopThinkingForAssistant(assistant);
    const tail = assistant.segments[assistant.segments.length - 1];
    if (tail?.type === 'text') {
@@ -117,12 +177,14 @@ class ChatTimeTimelineBuilder {
    items: ChatTimeTimelineItem[],
    payload: ChatTimeToolMutationPayload,
  ) {
+    prepareRoundVariant(items, payload);
    this.stopThinking(items);
    const toolItem = ensureToolItem(
      items,
      payload.toolCallId,
      payload.created,
      payload.name,
+      payload,
    );
    toolItem.arguments = normalizePayloadValue(payload.value);
    toolItem.content = '';
@@ -136,11 +198,13 @@ class ChatTimeTimelineBuilder {
    items: ChatTimeTimelineItem[],
    payload: ChatTimeToolMutationPayload,
  ) {
+    prepareRoundVariant(items, payload);
    const toolItem = ensureToolItem(
      items,
      payload.toolCallId,
      payload.created,
      payload.name,
+      payload,
    );
    toolItem.result = normalizePayloadValue(payload.result);
    toolItem.content = toolItem.result;
@@ -178,7 +242,7 @@ class ChatTimeTimelineBuilder {
   * 结束当前轮的 assistant 状态。
   */
  static finalize(items: ChatTimeTimelineItem[]) {
-    const last = items[items.length - 1];
+    const last = findLastAssistant(items);
    if (!isAssistantItem(last)) {
      return;
    }
@@ -186,6 +250,26 @@ class ChatTimeTimelineBuilder {
    last.loading = false;
    last.typing = false;
  }
+
+  /**
+   * 按轮次替换当前主线可见的 assistant/tool 片段。
+   */
+  static replaceRoundMessages(
+    items: ChatTimeTimelineItem[],
+    roundId: number | string | undefined,
+    nextMessages: ChatTimeTimelineItem[],
+  ) {
+    const normalizedRoundId = normalizeRoundId(roundId);
+    if (!normalizedRoundId) {
+      return;
+    }
+    const range = resolveRoundReplaceRange(items, normalizedRoundId);
+    if (range) {
+      items.splice(range.start, range.deleteCount, ...nextMessages);
+      return;
+    }
+    items.splice(resolveRoundInsertIndex(items, normalizedRoundId), 0, ...nextMessages);
+  }
 }

 /**
@@ -196,7 +280,9 @@ class ChatTimeHistoryMapper {
   * 从聊天历史记录恢复时间线。
   */
  static fromHistoryRecords(records: ChatTimeHistoryRecord[]) {
-    return records.flatMap((record) => this.fromHistoryRecord(record));
+    return normalizeVisibleHistoryRecords(records).flatMap((record) =>
+      this.fromHistoryRecord(record),
+    );
  }

  /**
@@ -249,8 +335,15 @@ class ChatTimeHistoryMapper {
    const assistant = createAssistantItem(record.created, {
      id: record.id == null ? undefined : String(record.id),
      loading: record.loading,
+      messageKind: record.messageKind,
+      roundId: normalizeRoundId(record.roundId),
+      roundNo: record.roundNo,
+      selectedVariantIndex: record.selectedVariantIndex,
      senderName: record.senderName,
+      switchable: record.switchable,
      typing: record.typing,
+      variantCount: record.variantCount,
+      variantIndex: record.variantIndex,
    });
    const tools: ChatTimeTimelineItem[] = [];

@@ -267,7 +360,7 @@ class ChatTimeHistoryMapper {
        continue;
      }

-      const toolItem = createToolItemFromChain(rawChain, record.created);
+      const toolItem = createToolItemFromChain(rawChain, record.created, record);
      if (toolItem) {
        tools.push(toolItem);
      }
@@ -316,6 +409,7 @@ class ChatTimeHistoryMapper {
            rawMessage,
            toolMetaMap,
            record.created,
+            record,
          ),
        );
      }
@@ -325,11 +419,84 @@ class ChatTimeHistoryMapper {
  }
 }

+function normalizeVisibleHistoryRecords(records: ChatTimeHistoryRecord[]) {
+  const dedupedRecords = dedupeHistoryRecords(records);
+  const userSelectedVariantByRound = new Map<string, number>();
+  const assistantSelectedVariantByRound = new Map<string, number>();
+  const fallbackVariantByRound = new Map<string, number>();
+  for (const record of dedupedRecords) {
+    const roundId = normalizeRoundId(record.roundId);
+    if (!roundId) {
+      continue;
+    }
+    const selectedVariantIndex = normalizePositiveInteger(
+      record.selectedVariantIndex,
+    );
+    if (selectedVariantIndex) {
+      if (isUserHistoryRecord(record)) {
+        userSelectedVariantByRound.set(roundId, selectedVariantIndex);
+      } else {
+        assistantSelectedVariantByRound.set(roundId, selectedVariantIndex);
+      }
+    }
+    const variantIndex = normalizePositiveInteger(record.variantIndex);
+    if (!isUserHistoryRecord(record) && variantIndex) {
+      fallbackVariantByRound.set(roundId, variantIndex);
+    }
+  }
+  return dedupedRecords.filter((record) => {
+    const roundId = normalizeRoundId(record.roundId);
+    if (!roundId || isUserHistoryRecord(record)) {
+      return true;
+    }
+    const variantIndex = normalizePositiveInteger(record.variantIndex);
+    if (!variantIndex) {
+      return true;
+    }
+    const selectedVariantIndex =
+      userSelectedVariantByRound.get(roundId) ||
+      assistantSelectedVariantByRound.get(roundId) ||
+      fallbackVariantByRound.get(roundId);
+    return !selectedVariantIndex || variantIndex === selectedVariantIndex;
+  });
+}
+
+function dedupeHistoryRecords(records: ChatTimeHistoryRecord[]) {
+  const seen = new Set<string>();
+  const result: ChatTimeHistoryRecord[] = [];
+  for (const record of records) {
+    const key = resolveHistoryRecordKey(record);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    result.push(record);
+  }
+  return result;
+}
+
+function resolveHistoryRecordKey(record: ChatTimeHistoryRecord) {
+  if (record.id != null) {
+    return `id:${String(record.id)}`;
+  }
+  return [
+    'fallback',
+    normalizeRoundId(record.roundId) || '',
+    normalizeRole(record.senderRole || record.role),
+    normalizePositiveInteger(record.variantIndex) || '',
+    normalizePlainText(record.contentText || record.content),
+  ].join(':');
+}
+
+function isUserHistoryRecord(record: ChatTimeHistoryRecord) {
+  return normalizeRole(record.senderRole || record.role) === 'user';
+}
+
 function createAssistantItem(
  created?: number | string,
-  patch?: Partial<ChatTimeAssistantItem>,
+  patch?: Omit<Partial<ChatTimeAssistantItem>, 'roundId'> & ChatTimeRoundMeta,
 ): ChatTimeAssistantItem {
-  return {
+  const item: ChatTimeAssistantItem = {
    content: patch?.content || '',
    created: normalizeTimestamp(created),
    id: patch?.id || uuid(),
@@ -340,6 +507,8 @@ function createAssistantItem(
    senderName: patch?.senderName,
    typing: patch?.typing,
  };
+  applyRoundMeta(item, patch);
+  return item;
 }

 function createAssistantItemFromStructuredMessage(
@@ -360,8 +529,15 @@ function createAssistantItemFromStructuredMessage(
        ? undefined
        : `${String(record.id)}-assistant-${assistantIndex}`,
    loading: false,
+    messageKind: record.messageKind,
+    roundId: normalizeRoundId(record.roundId),
+    roundNo: record.roundNo,
+    selectedVariantIndex: record.selectedVariantIndex,
    senderName: record.senderName,
+    switchable: record.switchable,
    typing: false,
+    variantCount: record.variantCount,
+    variantIndex: record.variantIndex,
  });
  if (reasoning) {
    assistant.segments.push({
@@ -381,6 +557,7 @@ function createAssistantItemFromStructuredMessage(
 function createToolItemFromChain(
  rawChain: Record<string, any>,
  created?: number | string,
+  record?: ChatTimeHistoryRecord,
 ) {
  const toolCallId = normalizePlainText(rawChain.id);
  const name = normalizePlainText(rawChain.name);
@@ -393,10 +570,17 @@ function createToolItemFromChain(
    arguments: status === 'TOOL_CALL' ? argumentsValue : undefined,
    created,
    id: toolCallId || uuid(),
+    messageKind: record?.messageKind,
    name,
+    roundId: record?.roundId,
+    roundNo: record?.roundNo,
    result: status === 'TOOL_RESULT' ? argumentsValue : undefined,
+    selectedVariantIndex: record?.selectedVariantIndex,
    status,
+    switchable: record?.switchable,
    toolCallId,
+    variantCount: record?.variantCount,
+    variantIndex: record?.variantIndex,
  });
 }

@@ -404,6 +588,7 @@ function createToolItemFromStructuredMessage(
  rawMessage: Record<string, any>,
  toolMetaMap: Map<string, ChatTimeToolMeta>,
  created?: number | string,
+  record?: ChatTimeHistoryRecord,
 ) {
  const toolCallId = normalizePlainText(
    rawMessage.toolCallId ?? rawMessage.tool_call_id,
@@ -414,10 +599,17 @@ function createToolItemFromStructuredMessage(
    arguments: toolMeta?.arguments,
    created,
    id: toolCallId || uuid(),
+    messageKind: record?.messageKind,
    name: toolMeta?.name,
+    roundId: record?.roundId,
+    roundNo: record?.roundNo,
    result,
+    selectedVariantIndex: record?.selectedVariantIndex,
    status: 'TOOL_RESULT',
+    switchable: record?.switchable,
    toolCallId,
+    variantCount: record?.variantCount,
+    variantIndex: record?.variantIndex,
  });
 }

@@ -429,12 +621,19 @@ function createToolItemFromTopLevelRecord(record: ChatTimeHistoryRecord) {
  return createToolItem({
    created: record.created,
    id: record.id == null ? toolCallId || uuid() : String(record.id),
+    messageKind: record.messageKind,
    name: normalizePlainText(payload.name),
+    roundId: record.roundId,
+    roundNo: record.roundNo,
    result: normalizePayloadValue(
      payload.content ?? payload.result ?? record.contentText ?? record.content,
    ),
+    selectedVariantIndex: record.selectedVariantIndex,
    status: 'TOOL_RESULT',
+    switchable: record.switchable,
    toolCallId,
+    variantCount: record.variantCount,
+    variantIndex: record.variantIndex,
  });
 }

@@ -442,12 +641,19 @@ function createToolItem(payload: {
  arguments?: string;
  created?: number | string;
  id?: string;
+  messageKind?: string;
  name?: string;
+  roundId?: number | string;
+  roundNo?: number;
  result?: string;
+  selectedVariantIndex?: number;
  status: ChatTimeToolStatus;
+  switchable?: boolean;
  toolCallId?: string;
+  variantCount?: number;
+  variantIndex?: number;
 }): ChatTimeToolItem {
-  return {
+  const item: ChatTimeToolItem = {
    arguments: payload.arguments,
    content: payload.result || '',
    created: normalizeTimestamp(payload.created),
@@ -459,10 +665,12 @@ function createToolItem(payload: {
    status: payload.status,
    toolCallId: payload.toolCallId || payload.id || uuid(),
  };
+  applyRoundMeta(item, payload);
+  return item;
 }

 function createUserItem(record: ChatTimeHistoryRecord): ChatTimeTimelineItem {
-  return {
+  const item: ChatTimeTimelineItem = {
    content: normalizePlainText(record.contentText || record.content),
    created: normalizeTimestamp(record.created),
    id: record.id == null ? uuid() : String(record.id),
@@ -472,6 +680,8 @@ function createUserItem(record: ChatTimeHistoryRecord): ChatTimeTimelineItem {
    senderName: record.senderName,
    typing: record.typing,
  };
+  applyRoundMeta(item, record);
+  return item;
 }

 function appendAssistantText(item: ChatTimeAssistantItem, content: string) {
@@ -507,14 +717,17 @@ function collectToolMeta(
 function ensureAssistantTail(
  items: ChatTimeTimelineItem[],
  created?: number | string,
+  meta?: ChatTimeRoundMeta,
 ) {
  const last = items[items.length - 1];
-  if (isAssistantItem(last)) {
+  if (isAssistantItem(last) && isSameRoundVariant(last, meta)) {
+    applyRoundMeta(last, meta);
    return last;
  }
  const assistant = createAssistantItem(created, {
    loading: true,
    typing: true,
+    ...normalizeRoundMeta(meta),
  });
  items.push(assistant);
  return assistant;
@@ -525,38 +738,64 @@ function ensureToolItem(
  toolCallId?: string,
  created?: number | string,
  name?: string,
+  meta?: ChatTimeRoundMeta,
 ) {
  const normalizedToolCallId = normalizePlainText(toolCallId);
-  const found = findToolItem(items, normalizedToolCallId);
+  const found = findToolItem(items, normalizedToolCallId, meta);
  if (found) {
    if (name) {
      found.name = name;
    }
+    applyRoundMeta(found, meta);
    return found;
  }
  const toolItem = createToolItem({
    created,
    id: normalizedToolCallId || uuid(),
+    messageKind: meta?.messageKind,
    name,
+    roundId: meta?.roundId,
+    roundNo: meta?.roundNo,
+    selectedVariantIndex: meta?.selectedVariantIndex,
    status: 'TOOL_CALL',
+    switchable: meta?.switchable,
    toolCallId: normalizedToolCallId,
+    variantCount: meta?.variantCount,
+    variantIndex: meta?.variantIndex,
  });
  items.push(toolItem);
  return toolItem;
 }

-function findToolItem(items: ChatTimeTimelineItem[], toolCallId?: string) {
+function findToolItem(
+  items: ChatTimeTimelineItem[],
+  toolCallId?: string,
+  meta?: ChatTimeRoundMeta,
+) {
+  const normalizedRoundId = normalizeRoundId(meta?.roundId);
+  const normalizedVariantIndex = normalizePositiveInteger(meta?.variantIndex);
  if (toolCallId) {
    for (let index = items.length - 1; index >= 0; index -= 1) {
      const item = items[index];
-      if (isToolItem(item) && item.toolCallId === toolCallId) {
+      if (
+        isToolItem(item) &&
+        item.toolCallId === toolCallId &&
+        matchesRoundVariant(item, normalizedRoundId, normalizedVariantIndex)
+      ) {
        return item;
      }
    }
  }
  for (let index = items.length - 1; index >= 0; index -= 1) {
    const item = items[index];
-    if (isToolItem(item) && item.status === 'TOOL_CALL') {
+    if (!item) {
+      continue;
+    }
+    if (
+      isToolItem(item) &&
+      item.status === 'TOOL_CALL' &&
+      matchesRoundVariant(item, normalizedRoundId, normalizedVariantIndex)
+    ) {
      return item;
    }
  }
@@ -584,6 +823,182 @@ function isToolItem(item?: ChatTimeTimelineItem): item is ChatTimeToolItem {
  return item?.role === 'tool';
 }

+function findLastAssistant(items: ChatTimeTimelineItem[]) {
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    const item = items[index];
+    if (isAssistantItem(item)) {
+      return item;
+    }
+  }
+  return undefined;
+}
+
+function prepareRoundVariant(
+  items: ChatTimeTimelineItem[],
+  meta?: ChatTimeRoundMeta,
+) {
+  const normalizedRoundId = normalizeRoundId(meta?.roundId);
+  const normalizedVariantIndex = normalizePositiveInteger(meta?.variantIndex);
+  if (!normalizedRoundId || !normalizedVariantIndex) {
+    return;
+  }
+  const assistant = items.find(
+    (item) => item.role === 'assistant' && item.roundId === normalizedRoundId,
+  );
+  if (assistant?.variantIndex === normalizedVariantIndex) {
+    return;
+  }
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    const item = items[index];
+    if (!item) {
+      continue;
+    }
+    if (item.roundId === normalizedRoundId && item.role !== 'user') {
+      items.splice(index, 1);
+    }
+  }
+}
+
+function resolveRoundInsertIndex(
+  items: ChatTimeTimelineItem[],
+  roundId: string,
+) {
+  const firstRoundItemIndex = items.findIndex(
+    (item) => item.roundId === roundId && item.role !== 'user',
+  );
+  if (firstRoundItemIndex >= 0) {
+    return firstRoundItemIndex;
+  }
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    const item = items[index];
+    if (!item) {
+      continue;
+    }
+    if (item.roundId === roundId && item.role === 'user') {
+      return index + 1;
+    }
+  }
+  return items.length;
+}
+
+function resolveRoundReplaceRange(
+  items: ChatTimeTimelineItem[],
+  roundId: string,
+) {
+  let start = -1;
+  let end = -1;
+  for (let index = 0; index < items.length; index += 1) {
+    const item = items[index];
+    if (item?.roundId === roundId && item.role !== 'user') {
+      if (start < 0) {
+        start = index;
+      }
+      end = index;
+    } else if (start >= 0) {
+      break;
+    }
+  }
+  if (start < 0) {
+    return null;
+  }
+  return {
+    deleteCount: end - start + 1,
+    start,
+  };
+}
+
+function matchesRoundVariant(
+  item: ChatTimeTimelineItem,
+  roundId?: string,
+  variantIndex?: number,
+) {
+  if (roundId && item.roundId !== roundId) {
+    return false;
+  }
+  if (variantIndex && item.variantIndex && item.variantIndex !== variantIndex) {
+    return false;
+  }
+  return true;
+}
+
+function isSameRoundVariant(
+  item: ChatTimeTimelineItem,
+  meta?: ChatTimeRoundMeta,
+) {
+  const normalizedRoundId = normalizeRoundId(meta?.roundId);
+  const normalizedVariantIndex = normalizePositiveInteger(meta?.variantIndex);
+  if (!normalizedRoundId || !normalizedVariantIndex) {
+    return true;
+  }
+  return (
+    item.roundId === normalizedRoundId &&
+    normalizePositiveInteger(item.variantIndex) === normalizedVariantIndex
+  );
+}
+
+function applyRoundMeta(
+  target: Partial<ChatTimeTimelineItemBase>,
+  source?: ChatTimeRoundMeta | null,
+) {
+  if (!source) {
+    return;
+  }
+  const roundId = normalizeRoundId(source.roundId);
+  if (roundId) {
+    target.roundId = roundId;
+  }
+  const roundNo = normalizePositiveInteger(source.roundNo);
+  if (roundNo) {
+    target.roundNo = roundNo;
+  }
+  const variantIndex = normalizePositiveInteger(source.variantIndex);
+  if (variantIndex) {
+    target.variantIndex = variantIndex;
+  }
+  const variantCount = normalizePositiveInteger(source.variantCount);
+  if (variantCount) {
+    target.variantCount = variantCount;
+  }
+  const selectedVariantIndex = normalizePositiveInteger(
+    source.selectedVariantIndex,
+  );
+  if (selectedVariantIndex) {
+    target.selectedVariantIndex = selectedVariantIndex;
+  }
+  if (typeof source.switchable === 'boolean') {
+    target.switchable = source.switchable;
+  }
+  const messageKind = normalizePlainText(source.messageKind).trim();
+  if (messageKind) {
+    target.messageKind = messageKind;
+  }
+}
+
+function normalizeRoundMeta(meta?: ChatTimeRoundMeta): ChatTimeRoundMeta {
+  return {
+    messageKind: meta?.messageKind,
+    roundId: normalizeRoundId(meta?.roundId),
+    roundNo: meta?.roundNo,
+    selectedVariantIndex: meta?.selectedVariantIndex,
+    switchable: meta?.switchable,
+    variantCount: meta?.variantCount,
+    variantIndex: meta?.variantIndex,
+  };
+}
+
+function normalizeRoundId(value: any) {
+  const normalized = normalizePlainText(value).trim();
+  return normalized || undefined;
+}
+
+function normalizePositiveInteger(value: any) {
+  if (value == null || value === '') {
+    return undefined;
+  }
+  const parsed = Number.parseInt(String(value), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
 function normalizeAssistantText(value: any) {
  return normalizePlainText(value)
    .replace(/^Final Answer:\s*/i, '')
--- a/easyflow-ui-admin/packages/utils/src/helpers/chat-variant-switch.ts
+++ b/easyflow-ui-admin/packages/utils/src/helpers/chat-variant-switch.ts
@@ -0,0 +1,187 @@
+type VariantRecord = {
+  selectedVariantIndex?: number | string;
+  variantIndex?: number | string;
+};
+
+interface ChatVariantSwitchControllerOptions<TRecord extends VariantRecord, TItem> {
+  mapRecords: (records: TRecord[]) => TItem[];
+  onError?: (error: unknown) => void;
+  onStateChange?: () => void;
+  replaceRound: (items: TItem[], roundId: string, nextItems: TItem[]) => void;
+}
+
+interface EnsureVariantsOptions<TRecord extends VariantRecord> {
+  fetchVariants: () => Promise<TRecord[]>;
+  roundId: number | string;
+  sessionId: number | string;
+}
+
+interface SwitchVariantOptions<TRecord extends VariantRecord, TItem>
+  extends EnsureVariantsOptions<TRecord> {
+  items: TItem[];
+  onLocalSwitch?: (record: TRecord) => void;
+  persistVariant: () => Promise<TRecord | void>;
+  targetVariantIndex: number;
+}
+
+function variantCacheKey(sessionId: number | string, roundId: number | string) {
+  return `${String(sessionId)}:${String(roundId)}`;
+}
+
+function normalizeVariantIndex(value: unknown) {
+  const parsed = Number.parseInt(String(value || ''), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+function markVariantSelected<TRecord extends VariantRecord>(
+  record: TRecord,
+  selectedVariantIndex: number,
+): TRecord {
+  return {
+    ...record,
+    selectedVariantIndex,
+  };
+}
+
+function syncCachedSelection<TRecord extends VariantRecord>(
+  records: TRecord[],
+  selectedVariantIndex: number,
+  selectedRecord?: TRecord,
+) {
+  return records.map((record) => {
+    const isSelected =
+      selectedRecord &&
+      normalizeVariantIndex(record.variantIndex) ===
+        normalizeVariantIndex(selectedRecord.variantIndex);
+    return markVariantSelected(
+      isSelected ? { ...record, ...selectedRecord } : record,
+      selectedVariantIndex,
+    );
+  });
+}
+
+export function createChatVariantSwitchController<
+  TRecord extends VariantRecord,
+  TItem,
+>(options: ChatVariantSwitchControllerOptions<TRecord, TItem>) {
+  const cache = new Map<string, TRecord[]>();
+  const fetchTasks = new Map<string, Promise<TRecord[]>>();
+  const switchingKeys = new Set<string>();
+
+  function notifyStateChange() {
+    options.onStateChange?.();
+  }
+
+  async function ensureVariants(params: EnsureVariantsOptions<TRecord>) {
+    const key = variantCacheKey(params.sessionId, params.roundId);
+    const cached = cache.get(key);
+    if (cached) {
+      return cached;
+    }
+    const existingTask = fetchTasks.get(key);
+    if (existingTask) {
+      return existingTask;
+    }
+    const task = params
+      .fetchVariants()
+      .then((records) => {
+        cache.set(key, records);
+        return records;
+      })
+      .finally(() => {
+        fetchTasks.delete(key);
+      });
+    fetchTasks.set(key, task);
+    return task;
+  }
+
+  function prefetchVariants(params: EnsureVariantsOptions<TRecord>) {
+    void ensureVariants(params).catch(() => {
+      // 预取失败不打断当前页面，用户点击时仍会再次拉取。
+    });
+  }
+
+  function hasCachedVariant(
+    sessionId: number | string,
+    roundId: number | string,
+    variantIndex: number,
+  ) {
+    const records = cache.get(variantCacheKey(sessionId, roundId));
+    return Boolean(
+      records?.some(
+        (record) => normalizeVariantIndex(record.variantIndex) === variantIndex,
+      ),
+    );
+  }
+
+  function isSwitching(sessionId?: number | string, roundId?: number | string) {
+    if (!sessionId || !roundId) {
+      return false;
+    }
+    return switchingKeys.has(variantCacheKey(sessionId, roundId));
+  }
+
+  async function switchVariant(params: SwitchVariantOptions<TRecord, TItem>) {
+    const key = variantCacheKey(params.sessionId, params.roundId);
+    if (switchingKeys.has(key)) {
+      return null;
+    }
+    switchingKeys.add(key);
+    notifyStateChange();
+    const snapshot = [...params.items];
+    try {
+      const records = await ensureVariants(params);
+      const target = records.find(
+        (record) =>
+          normalizeVariantIndex(record.variantIndex) === params.targetVariantIndex,
+      );
+      if (!target) {
+        throw new Error('目标答案版本不存在');
+      }
+      const localTarget = markVariantSelected(target, params.targetVariantIndex);
+      const nextItems = options.mapRecords([localTarget]);
+      if (nextItems.length === 0) {
+        throw new Error('目标答案版本渲染失败');
+      }
+      options.replaceRound(
+        params.items,
+        String(params.roundId),
+        nextItems,
+      );
+      params.onLocalSwitch?.(localTarget);
+      const persistedRecord = await params.persistVariant();
+      const selectedRecord = markVariantSelected(
+        persistedRecord || localTarget,
+        params.targetVariantIndex,
+      );
+      cache.set(
+        key,
+        syncCachedSelection(records, params.targetVariantIndex, selectedRecord),
+      );
+      return selectedRecord;
+    } catch (error) {
+      params.items.splice(0, params.items.length, ...snapshot);
+      options.onError?.(error);
+      return null;
+    } finally {
+      switchingKeys.delete(key);
+      notifyStateChange();
+    }
+  }
+
+  function cacheVariants(
+    sessionId: number | string,
+    roundId: number | string,
+    records: TRecord[],
+  ) {
+    cache.set(variantCacheKey(sessionId, roundId), records);
+  }
+
+  return {
+    cacheVariants,
+    hasCachedVariant,
+    isSwitching,
+    prefetchVariants,
+    switchVariant,
+  };
+}
--- a/easyflow-ui-admin/packages/utils/src/helpers/generate-routes-backend.ts
+++ b/easyflow-ui-admin/packages/utils/src/helpers/generate-routes-backend.ts
@@ -59,6 +59,9 @@ function convertRoutes(
      const pageKey = normalizePath.endsWith('.vue')
        ? normalizePath
        : `${normalizePath}.vue`;
+      if (pageKey === '/ai/chat/index.vue' && route.meta) {
+        route.meta.fullPathKey = false;
+      }
      if (pageMap[pageKey]) {
        route.component = pageMap[pageKey];
      } else {
--- a/easyflow-ui-admin/packages/utils/src/helpers/index.ts
+++ b/easyflow-ui-admin/packages/utils/src/helpers/index.ts
@@ -1,4 +1,5 @@
 export * from './chat-time';
+export * from './chat-variant-switch';
 export * from './find-menu-by-path';
 export * from './generate-menus';
 export * from './generate-routes-backend';