easyflow-ui-admin/app/src/components/chat-history/ChatHistoryDetailDrawer.vue

@@ -2,7 +2,7 @@
 import type { ChatTimeTimelineItem } from '@easyflow/types';
 
 import { Close } from '@element-plus/icons-vue';
-import { ElButton, ElEmpty, ElIcon, ElMessage, ElScrollbar } from 'element-plus';
+import { ElButton, ElEmpty, ElIcon, ElScrollbar } from 'element-plus';
 
 import ChatTimeMessageContent from '#/components/chat/ChatTimeMessageContent.vue';
 import ChatMessageActionBar from '#/components/chat-workspace/ChatMessageActionBar.vue';
@@ -125,18 +125,6 @@ function isFinalAssistantInRound(item: ChatTimeTimelineItem) {
 function canCopyMessage(item: ChatTimeTimelineItem) {
   return item.role !== 'tool' && Boolean(String(item.content || '').trim());
 }
-
-async function handleCopyMessage(item: ChatTimeTimelineItem) {
-  if (!canCopyMessage(item)) {
-    return;
-  }
-  try {
-    await navigator.clipboard.writeText(String(item.content || ''));
-    ElMessage.success('已复制');
-  } catch {
-    ElMessage.error('复制失败');
-  }
-}
 </script>
 
 <template>
@@ -231,6 +219,7 @@ async function handleCopyMessage(item: ChatTimeTimelineItem) {
             <ChatMessageActionBar
               :align="item.role === 'user' ? 'end' : 'start'"
               :allow-copy="canCopyMessage(item)"
+              :copy-text="String(item.content || '').trim()"
               :show-variant-navigator="shouldShowVariantNavigator(item)"
               :disabled-variant-next="!canSwitchVariant(item, 'next')"
               :disabled-variant-previous="!canSwitchVariant(item, 'previous')"
@@ -239,7 +228,6 @@ async function handleCopyMessage(item: ChatTimeTimelineItem) {
                 Number(item.variantIndex || item.selectedVariantIndex || 1)
               "
               :variant-total="Number(item.variantCount || 1)"
-              @copy="handleCopyMessage(item)"
               @select-next-variant="
                 emit('selectVariant', { direction: 'next', item })
               "

easyflow-ui-admin/app/src/components/chat-workspace/ChatMessageActionBar.test.ts

@@ -0,0 +1,66 @@
+import { flushPromises, mount } from '@vue/test-utils';
+
+import { copyTextToClipboard } from '@easyflow/utils';
+
+import { ElMessage } from 'element-plus';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import ChatMessageActionBar from './ChatMessageActionBar.vue';
+
+vi.mock('@easyflow/utils', () => ({
+  copyTextToClipboard: vi.fn(),
+}));
+
+vi.mock('element-plus', () => ({
+  ElMessage: {
+    error: vi.fn(),
+  },
+}));
+
+describe('chat message action bar', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+    vi.useRealTimers();
+  });
+
+  it('shows a check icon after copying and restores the copy icon', async () => {
+    vi.useFakeTimers();
+    vi.mocked(copyTextToClipboard).mockResolvedValue('clipboard-api');
+    const wrapper = mount(ChatMessageActionBar, {
+      props: {
+        allowCopy: true,
+        copyText: '消息内容',
+      },
+    });
+
+    await wrapper.get('[aria-label="复制消息"]').trigger('click');
+    await flushPromises();
+
+    expect(copyTextToClipboard).toHaveBeenCalledWith('消息内容');
+    expect(wrapper.get('button').attributes('aria-label')).toBe('复制成功');
+    expect(wrapper.get('button').classes()).not.toContain('is-copied');
+    expect(ElMessage.error).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1600);
+
+    expect(wrapper.get('button').attributes('aria-label')).toBe('复制消息');
+  });
+
+  it('keeps the copy icon and shows the existing warning on failure', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    vi.mocked(copyTextToClipboard).mockRejectedValue(new Error('copy denied'));
+    const wrapper = mount(ChatMessageActionBar, {
+      props: {
+        allowCopy: true,
+        copyErrorMessage: '复制失败，请重试',
+        copyText: '消息内容',
+      },
+    });
+
+    await wrapper.get('[aria-label="复制消息"]').trigger('click');
+    await flushPromises();
+
+    expect(wrapper.get('button').attributes('aria-label')).toBe('复制消息');
+    expect(ElMessage.error).toHaveBeenCalledWith('复制失败，请重试');
+  });
+});

easyflow-ui-admin/app/src/components/chat-workspace/ChatMessageActionBar.vue

@@ -1,8 +1,10 @@
 <script setup lang="ts">
-import {
+import { onBeforeUnmount, ref } from 'vue';
-  CopyDocument,
+
-  RefreshRight,
+import { copyTextToClipboard } from '@easyflow/utils';
-} from '@element-plus/icons-vue';
+
+import { Check, CopyDocument, RefreshRight } from '@element-plus/icons-vue';
+import { ElMessage } from 'element-plus';
 
 import ChatAnswerVariantNavigator from './ChatAnswerVariantNavigator.vue';
 
@@ -11,6 +13,8 @@ const props = withDefaults(
     align?: 'end' | 'start';
     allowCopy?: boolean;
     allowRegenerate?: boolean;
+    copyErrorMessage?: string;
+    copyText?: string;
     disabledVariantNext?: boolean;
     disabledVariantPrevious?: boolean;
     regenerateDisabled?: boolean;
@@ -23,6 +27,8 @@ const props = withDefaults(
     align: 'start',
     allowCopy: false,
     allowRegenerate: false,
+    copyErrorMessage: '复制失败',
+    copyText: '',
     disabledVariantNext: false,
     disabledVariantPrevious: false,
     regenerateDisabled: false,
@@ -34,14 +40,37 @@ const props = withDefaults(
 );
 
 const emit = defineEmits<{
-  copy: [];
   regenerate: [];
   selectNextVariant: [];
   selectPreviousVariant: [];
 }>();
 
-function handleCopy() {
+const copied = ref(false);
-  emit('copy');
+const copying = ref(false);
+const COPIED_FEEDBACK_DURATION_MS = 1600;
+let copiedResetTimer: ReturnType<typeof setTimeout> | undefined;
+
+async function handleCopy() {
+  if (copying.value || !props.copyText) {
+    return;
+  }
+  copying.value = true;
+  try {
+    await copyTextToClipboard(props.copyText);
+    copied.value = true;
+    if (copiedResetTimer) {
+      clearTimeout(copiedResetTimer);
+    }
+    copiedResetTimer = setTimeout(() => {
+      copied.value = false;
+      copiedResetTimer = undefined;
+    }, COPIED_FEEDBACK_DURATION_MS);
+  } catch (error) {
+    console.error('复制消息失败:', error);
+    ElMessage.error(props.copyErrorMessage);
+  } finally {
+    copying.value = false;
+  }
 }
 
 function handleRegenerate() {
@@ -58,6 +87,12 @@ function handleSelectPreviousVariant() {
 function handleSelectNextVariant() {
   emit('selectNextVariant');
 }
+
+onBeforeUnmount(() => {
+  if (copiedResetTimer) {
+    clearTimeout(copiedResetTimer);
+  }
+});
 </script>
 
 <template>
@@ -81,11 +116,15 @@ function handleSelectNextVariant() {
       v-if="allowCopy"
       type="button"
       class="message-actions__button"
-      aria-label="复制消息"
+      :aria-busy="copying"
-      title="复制"
+      :aria-label="copied ? '复制成功' : '复制消息'"
+      :title="copied ? '复制成功' : '复制'"
       @click="handleCopy"
     >
-      <CopyDocument />
+      <Transition name="message-actions__icon" mode="out-in">
+        <Check v-if="copied" key="check" />
+        <CopyDocument v-else key="copy" />
+      </Transition>
     </button>
 
     <button
@@ -150,4 +189,17 @@ function handleSelectNextVariant() {
   width: 15px;
   height: 15px;
 }
+
+.message-actions__icon-enter-active,
+.message-actions__icon-leave-active {
+  transition:
+    opacity var(--motion-duration-fast) var(--motion-ease-standard),
+    transform var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+.message-actions__icon-enter-from,
+.message-actions__icon-leave-to {
+  opacity: 0;
+  transform: scale(0.88);
+}
 </style>

easyflow-ui-admin/app/src/components/chat/chat.vue

@@ -387,13 +387,6 @@ const generateMockMessages = (refreshContent: string) => {
   return [userMessage];
 };
 
-const handleCopy = (content: string) => {
-  navigator.clipboard
-    .writeText(content)
-    .then(() => ElMessage.success($t('message.copySuccess')))
-    .catch(() => ElMessage.error($t('message.copyFail')));
-};
-
 const handleRefresh = () => {
   const roundId = String(latestAssistantMessage.value?.roundId || '');
   if (!roundId) {
@@ -643,6 +636,8 @@ onBeforeUnmount(() => {
               :align="item.role === 'user' ? 'end' : 'start'"
               :allow-copy="!!String(item.content || '').trim()"
               :allow-regenerate="canRegenerateMessage(item)"
+              :copy-error-message="$t('message.copyFail')"
+              :copy-text="String(item.content || '').trim()"
               :disabled-variant-next="!canSwitchVariant(item, 'next')"
               :disabled-variant-previous="!canSwitchVariant(item, 'previous')"
               :regenerate-disabled="sending"
@@ -652,7 +647,6 @@ onBeforeUnmount(() => {
                 Number(item.variantIndex || item.selectedVariantIndex || 1)
               "
               :variant-total="Number(item.variantCount || 1)"
-              @copy="handleCopy(item.content)"
               @regenerate="handleRefresh"
               @select-next-variant="handleSelectVariant(item, 'next')"
               @select-previous-variant="handleSelectVariant(item, 'previous')"

easyflow-ui-admin/app/src/views/ai/agent-chat/index.vue

@@ -21,6 +21,7 @@ import {
   ChatTimeline,
   ChatTimelineBuilder,
 } from '@easyflow/common-ui';
+import { copyTextToClipboard } from '@easyflow/utils';
 
 import {
   Delete,
@@ -872,13 +873,15 @@ function handleStop() {
 async function handleCopyMessage(item: ChatTimelineMessageItem) {
   const text = copyMessageText(item);
   if (!text) {
-    return;
+    return false;
   }
   try {
-    await navigator.clipboard.writeText(text);
+    await copyTextToClipboard(text);
-    ElMessage.success('已复制');
+    return true;
-  } catch {
+  } catch (error) {
+    console.error('复制消息失败:', error);
     ElMessage.error('复制失败');
+    return false;
   }
 }
 
@@ -1133,9 +1136,9 @@ onBeforeUnmount(() => {
           :image-loader="loadAgentChatImage"
           empty-text="选择智能体后开始对话"
           :approval-loading="Boolean(approvalLoadingKey)"
+          :copy-action="handleCopyMessage"
           :copyable="canCopyMessage"
           @approve="handleApprove"
-          @copy-message="handleCopyMessage"
           @reject="handleReject"
           @select-next-variant="() => undefined"
           @select-previous-variant="() => undefined"

easyflow-ui-admin/app/src/views/ai/agents/components/AgentTryoutPanel.vue

@@ -14,6 +14,7 @@ import { computed, onMounted, ref, watch } from 'vue';
 
 import { ChatTimeline } from '@easyflow/common-ui';
 import { BrushCleaning } from '@easyflow/icons';
+import { copyTextToClipboard } from '@easyflow/utils';
 
 import { ElButton, ElMessage } from 'element-plus';
 
@@ -148,13 +149,15 @@ function canRegenerateMessage(item: ChatTimelineMessageItem) {
 async function handleCopyMessage(item: ChatTimelineMessageItem) {
   const text = copyMessageText(item).trim();
   if (!text) {
-    return;
+    return false;
   }
   try {
-    await navigator.clipboard.writeText(text);
+    await copyTextToClipboard(text);
-    ElMessage.success('已复制');
+    return true;
-  } catch {
+  } catch (error) {
+    console.error('复制消息失败:', error);
     ElMessage.error('复制失败');
+    return false;
   }
 }
 
@@ -310,11 +313,11 @@ async function handleReject(payload: ChatTimelineToolApprovalPayload) {
         :image-loader="loadAgentChatImage"
         empty-text="输入问题试运行当前智能体"
         :approval-loading="approvalLoading"
+        :copy-action="handleCopyMessage"
         :copyable="canCopyMessage"
         :regenerable="canRegenerateMessage"
         :regenerate-disabled="true"
         @approve="handleApprove"
-        @copy-message="handleCopyMessage"
         @regenerate-message="handleRegenerateMessage"
         @reject="handleReject"
         @select-next-variant="handleSelectNextVariant"

easyflow-ui-admin/app/src/views/ai/chat/index.vue

@@ -951,19 +951,6 @@ function scrollToBottom(force = false) {
   });
 }
 
-async function copyMessageContent(content?: string) {
-  const normalized = String(content || '').trim();
-  if (!normalized) {
-    return;
-  }
-  try {
-    await navigator.clipboard.writeText(normalized);
-    ElMessage.success('已复制');
-  } catch {
-    ElMessage.error('复制失败');
-  }
-}
-
 function resolveKnowledgeView(knowledgeId: string) {
   const view = knowledgeMap.value.get(knowledgeId);
   if (view) {
@@ -1369,13 +1356,6 @@ function canRegenerateMessage(item: ChatTimeTimelineItem) {
   return !!roundId && !!resolveRoundUserPrompt(roundId);
 }
 
-async function handleCopyMessage(item: ChatTimeTimelineItem) {
-  if (!canCopyMessage(item)) {
-    return;
-  }
-  await copyMessageContent(item.content);
-}
-
 async function handleRegenerateMessage() {
   if (sending.value || isReadOnly.value) {
     return;
@@ -1786,6 +1766,7 @@ async function deleteSession(targetSession?: SessionItem) {
                       :align="item.role === 'user' ? 'end' : 'start'"
                       :allow-copy="canCopyMessage(item)"
                       :allow-regenerate="canRegenerateMessage(item)"
+                      :copy-text="String(item.content || '').trim()"
                       :disabled-variant-next="!canSwitchVariant(item, 'next')"
                       :disabled-variant-previous="!canSwitchVariant(item, 'previous')"
                       :regenerate-disabled="sending || isReadOnly"
@@ -1795,7 +1776,6 @@ async function deleteSession(targetSession?: SessionItem) {
                         Number(item.variantIndex || item.selectedVariantIndex || 1)
                       "
                       :variant-total="Number(item.variantCount || 1)"
-                      @copy="handleCopyMessage(item)"
                       @regenerate="handleRegenerateMessage"
                       @select-next-variant="selectVariantForMessage(item, 'next')"
                       @select-previous-variant="

easyflow-ui-admin/app/src/views/publicChat/index.vue

@@ -1650,18 +1650,6 @@ const isFinalAssistantInRound = (item: BubbleMessage) => {
   return true;
 };
 
-const handleCopyMessage = async (item: BubbleMessage) => {
-  if (!canCopyMessage(item)) {
-    return;
-  }
-  try {
-    await navigator.clipboard.writeText(String(item.content || ''));
-    ElMessage.success($t('bot.publicChatCopySuccess'));
-  } catch {
-    ElMessage.error($t('bot.publicChatCopyFail'));
-  }
-};
-
 const handleRegenerateMessage = async (item: BubbleMessage) => {
   if (sending.value || item.role !== 'assistant') {
     return;
@@ -1960,6 +1948,8 @@ function prefetchVisibleVariants() {
                   <ChatMessageActionBar
                     :align="item.role === 'user' ? 'end' : 'start'"
                     :allow-copy="canCopyMessage(item)"
+                    :copy-error-message="$t('bot.publicChatCopyFail')"
+                    :copy-text="String(item.content || '').trim()"
                     :allow-regenerate="
                       item.role === 'assistant' &&
                       getLatestAssistantMessage()?.id === item.id &&
@@ -1976,7 +1966,6 @@ function prefetchVisibleVariants() {
                       Number(item.variantIndex || item.selectedVariantIndex || 1)
                     "
                     :variant-total="Number(item.variantCount || 1)"
-                    @copy="handleCopyMessage(item)"
                     @regenerate="handleRegenerateMessage(item)"
                     @select-next-variant="handleSelectVariant(item, 'next')"
                     @select-previous-variant="

easyflow-ui-admin/packages/effects/common-ui/src/components/chat-timeline/ChatMessageToolbar.vue

@@ -1,5 +1,7 @@
 <script setup lang="ts">
-import {Copy, RotateCw} from '@easyflow/icons';
+import { onBeforeUnmount, ref } from 'vue';
+
+import { Check, Copy, RotateCw } from '@easyflow/icons';
 
 import ChatVariantNavigator from './ChatVariantNavigator.vue';
 
@@ -8,6 +10,7 @@ const props = withDefaults(
     align?: 'end' | 'start';
     allowCopy?: boolean;
     allowRegenerate?: boolean;
+    copyAction?: () => boolean | Promise<boolean>;
     disabledVariantNext?: boolean;
     disabledVariantPrevious?: boolean;
     regenerateDisabled?: boolean;
@@ -20,6 +23,7 @@ const props = withDefaults(
     align: 'start',
     allowCopy: false,
     allowRegenerate: false,
+    copyAction: undefined,
     disabledVariantNext: false,
     disabledVariantPrevious: false,
     regenerateDisabled: false,
@@ -37,12 +41,53 @@ const emit = defineEmits<{
   selectPreviousVariant: [];
 }>();
 
+const copied = ref(false);
+const copying = ref(false);
+const COPIED_FEEDBACK_DURATION_MS = 3000;
+let copiedResetTimer: ReturnType<typeof setTimeout> | undefined;
+
+async function handleCopy() {
+  if (copying.value) {
+    return;
+  }
+  if (!props.copyAction) {
+    emit('copy');
+    return;
+  }
+
+  copying.value = true;
+  try {
+    const success = await props.copyAction();
+    if (!success) {
+      return;
+    }
+    copied.value = true;
+    if (copiedResetTimer) {
+      clearTimeout(copiedResetTimer);
+    }
+    copiedResetTimer = setTimeout(() => {
+      copied.value = false;
+      copiedResetTimer = undefined;
+    }, COPIED_FEEDBACK_DURATION_MS);
+  } catch (error) {
+    console.error('复制消息失败:', error);
+  } finally {
+    copying.value = false;
+  }
+}
+
 function handleRegenerate() {
   if (props.regenerateDisabled) {
     return;
   }
   emit('regenerate');
 }
+
+onBeforeUnmount(() => {
+  if (copiedResetTimer) {
+    clearTimeout(copiedResetTimer);
+  }
+});
 </script>
 
 <template>
@@ -55,11 +100,15 @@ function handleRegenerate() {
       v-if="allowCopy"
       type="button"
       class="chat-message-toolbar__button"
-      aria-label="复制消息"
+      :aria-busy="copying"
-      title="复制"
+      :aria-label="copied ? '复制成功' : '复制消息'"
-      @click="emit('copy')"
+      :title="copied ? '复制成功' : '复制'"
+      @click="handleCopy"
     >
-      <Copy />
+      <Transition name="chat-message-toolbar__icon" mode="out-in">
+        <Check v-if="copied" key="check" />
+        <Copy v-else key="copy" />
+      </Transition>
     </button>
     <button
       v-if="allowRegenerate"
@@ -140,4 +189,17 @@ function handleRegenerate() {
   width: 14px;
   height: 14px;
 }
+
+.chat-message-toolbar__icon-enter-active,
+.chat-message-toolbar__icon-leave-active {
+  transition:
+    opacity var(--motion-duration-fast) var(--motion-ease-standard),
+    transform var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+.chat-message-toolbar__icon-enter-from,
+.chat-message-toolbar__icon-leave-to {
+  opacity: 0;
+  transform: scale(0.88);
+}
 </style>

easyflow-ui-admin/packages/effects/common-ui/src/components/chat-timeline/ChatTimeline.vue

@@ -13,6 +13,7 @@ import ChatTimelineItem from './ChatTimelineItem.vue';
 const props = defineProps<{
   approvalLoading?: boolean;
   copyable?: (item: ChatTimelineMessageItem) => boolean;
+  copyAction?: (item: ChatTimelineMessageItem) => boolean | Promise<boolean>;
   emptyText?: string;
   imageLoader?: ChatImageLoader;
   items: ChatTimelineItemType[];
@@ -157,6 +158,7 @@ watch(
         :item="item"
         :image-loader="imageLoader"
         :approval-loading="approvalLoading"
+        :copy-action="copyAction"
         :copyable="canCopyMessage(item)"
         :regenerable="canRegenerateMessage(item)"
         :regenerate-disabled="regenerateDisabled"

easyflow-ui-admin/packages/effects/common-ui/src/components/chat-timeline/ChatTimelineItem.vue

@@ -21,6 +21,7 @@ import ChatToolCard from './ChatToolCard.vue';
 const props = defineProps<{
   approvalLoading?: boolean;
   copyable?: boolean;
+  copyAction?: (item: ChatTimelineMessageItem) => boolean | Promise<boolean>;
   regenerable?: boolean;
   regenerateDisabled?: boolean;
   assistantActionsVisible?: boolean;
@@ -118,6 +119,14 @@ function updateThinkingExpanded(partId: string, expanded: boolean) {
     part.expanded = expanded;
   }
 }
+
+function handleCopyAction() {
+  const item = messageItem.value;
+  if (!item || !props.copyAction) {
+    return false;
+  }
+  return props.copyAction(item);
+}
 </script>
 
 <template>
@@ -161,6 +170,7 @@ function updateThinkingExpanded(partId: string, expanded: boolean) {
         :align="messageItem.role === 'user' ? 'end' : 'start'"
         :allow-copy="copyable"
         :allow-regenerate="regenerable"
+        :copy-action="copyAction ? handleCopyAction : undefined"
         :disabled-variant-next="disabledVariantNext"
         :disabled-variant-previous="disabledVariantPrevious"
         :regenerate-disabled="regenerateDisabled"

easyflow-ui-admin/packages/effects/common-ui/src/components/chat-timeline/__tests__/ChatTimelineToolbar.test.ts

@@ -1,8 +1,8 @@
 import type {ChatTimelineItem} from '../types';
 
-import {mount} from '@vue/test-utils';
+import {flushPromises, mount} from '@vue/test-utils';
 
-import {describe, expect, it} from 'vitest';
+import {afterEach, describe, expect, it, vi} from 'vitest';
 
 import ChatTimeline from '../ChatTimeline.vue';
 
@@ -28,6 +28,10 @@ function textMessage(
 }
 
 describe('ChatTimeline toolbar', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   it('shows copy button for user messages and emits copy-message', async () => {
     const userMessage = textMessage('user', '用户问题');
     const wrapper = mount(ChatTimeline, {
@@ -70,6 +74,32 @@ describe('ChatTimeline toolbar', () => {
     );
   });
 
+  it('shows a check icon after the copy action succeeds', async () => {
+    vi.useFakeTimers();
+    const copyAction = vi.fn().mockResolvedValue(true);
+    const userMessage = textMessage('user', '用户问题');
+    const wrapper = mount(ChatTimeline, {
+      props: {
+        copyAction,
+        copyable: () => true,
+        items: [userMessage],
+      },
+    });
+
+    await wrapper.get('[aria-label="复制消息"]').trigger('click');
+    await flushPromises();
+
+    expect(copyAction).toHaveBeenCalledWith(userMessage);
+    expect(wrapper.get('button').attributes('aria-label')).toBe('复制成功');
+    expect(
+      wrapper.find('.chat-message-toolbar__button.is-copied').exists(),
+    ).toBe(false);
+    expect(wrapper.emitted('copyMessage')).toBeUndefined();
+
+    await vi.advanceTimersByTimeAsync(3000);
+    expect(wrapper.get('button').attributes('aria-label')).toBe('复制消息');
+  });
+
   it('renders variant navigator and disables boundary buttons', async () => {
     const assistantMessage = textMessage('assistant', '助手回答', {
       roundId: 'round-1',

easyflow-ui-admin/packages/utils/src/helpers/__tests__/clipboard.test.ts

@@ -0,0 +1,108 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { copyTextToClipboard } from '../clipboard';
+
+describe('copyTextToClipboard', () => {
+  const originalClipboard = Object.getOwnPropertyDescriptor(
+    navigator,
+    'clipboard',
+  );
+  const originalExecCommand = Object.getOwnPropertyDescriptor(
+    document,
+    'execCommand',
+  );
+  const originalSecureContext = Object.getOwnPropertyDescriptor(
+    globalThis,
+    'isSecureContext',
+  );
+
+  beforeEach(() => {
+    Object.defineProperty(document, 'execCommand', {
+      configurable: true,
+      value: vi.fn(() => true),
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    restoreProperty(navigator, 'clipboard', originalClipboard);
+    restoreProperty(document, 'execCommand', originalExecCommand);
+    restoreProperty(globalThis, 'isSecureContext', originalSecureContext);
+    document
+      .querySelectorAll('textarea[aria-hidden="true"]')
+      .forEach((node) => node.remove());
+  });
+
+  it('uses Clipboard API in a secure context', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    stubSecureContext(true);
+    stubClipboard(writeText);
+
+    await expect(copyTextToClipboard('测试内容')).resolves.toBe(
+      'clipboard-api',
+    );
+    expect(writeText).toHaveBeenCalledWith('测试内容');
+    expect(document.execCommand).not.toHaveBeenCalled();
+  });
+
+  it('falls back to execCommand in an insecure context', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    stubSecureContext(false);
+    stubClipboard(writeText);
+
+    await expect(copyTextToClipboard('Chrome 90')).resolves.toBe(
+      'exec-command',
+    );
+    expect(writeText).not.toHaveBeenCalled();
+    expect(document.execCommand).toHaveBeenCalledWith('copy');
+    expect(document.querySelector('textarea[aria-hidden="true"]')).toBeNull();
+  });
+
+  it('falls back when Clipboard API is denied', async () => {
+    const writeText = vi.fn().mockRejectedValue(new DOMException('denied'));
+    stubSecureContext(true);
+    stubClipboard(writeText);
+
+    await expect(copyTextToClipboard('兼容内容')).resolves.toBe('exec-command');
+    expect(document.execCommand).toHaveBeenCalledWith('copy');
+  });
+
+  it('throws and cleans up when all copy methods fail', async () => {
+    stubSecureContext(false);
+    Object.defineProperty(document, 'execCommand', {
+      configurable: true,
+      value: vi.fn(() => false),
+    });
+
+    await expect(copyTextToClipboard('失败内容')).rejects.toThrow(
+      '浏览器拒绝了复制操作',
+    );
+    expect(document.querySelector('textarea[aria-hidden="true"]')).toBeNull();
+  });
+
+  function stubClipboard(writeText: ReturnType<typeof vi.fn>) {
+    Object.defineProperty(navigator, 'clipboard', {
+      configurable: true,
+      value: { writeText },
+    });
+  }
+
+  function stubSecureContext(value: boolean) {
+    Object.defineProperty(globalThis, 'isSecureContext', {
+      configurable: true,
+      value,
+    });
+  }
+});
+
+function restoreProperty(
+  target: object,
+  property: PropertyKey,
+  descriptor?: PropertyDescriptor,
+) {
+  if (descriptor) {
+    Object.defineProperty(target, property, descriptor);
+    return;
+  }
+  Reflect.deleteProperty(target, property);
+}

easyflow-ui-admin/packages/utils/src/helpers/clipboard.ts

@@ -0,0 +1,52 @@
+export type ClipboardCopyMethod = 'clipboard-api' | 'exec-command';
+
+/**
+ * 将文本写入系统剪贴板，并在现代 Clipboard API 不可用时降级处理。
+ *
+ * @param text 要复制的文本。
+ * @returns 实际使用的复制方式。
+ * @throws 当浏览器环境不可用或所有复制方式均失败时抛出异常。
+ */
+export async function copyTextToClipboard(
+  text: string,
+): Promise<ClipboardCopyMethod> {
+  if (typeof document === 'undefined' || typeof navigator === 'undefined') {
+    throw new TypeError('当前环境不支持剪贴板操作');
+  }
+
+  if (globalThis.isSecureContext && navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(text);
+      return 'clipboard-api';
+    } catch {
+      // 权限或浏览器策略拒绝时继续使用兼容方案。
+    }
+  }
+
+  const textArea = document.createElement('textarea');
+  const activeElement = document.activeElement;
+  textArea.value = text;
+  textArea.readOnly = true;
+  textArea.setAttribute('aria-hidden', 'true');
+  textArea.style.position = 'fixed';
+  textArea.style.top = '0';
+  textArea.style.left = '-9999px';
+  textArea.style.opacity = '0';
+
+  try {
+    document.body.append(textArea);
+    textArea.focus({ preventScroll: true });
+    textArea.select();
+    textArea.setSelectionRange(0, textArea.value.length);
+
+    if (!document.execCommand('copy')) {
+      throw new Error('浏览器拒绝了复制操作');
+    }
+    return 'exec-command';
+  } finally {
+    textArea.remove();
+    if (activeElement instanceof HTMLElement) {
+      activeElement.focus({ preventScroll: true });
+    }
+  }
+}

easyflow-ui-admin/packages/utils/src/helpers/index.ts

@@ -1,5 +1,6 @@
 export * from './chat-time';
 export * from './chat-variant-switch';
+export * from './clipboard';
 export * from './find-menu-by-path';
 export * from './generate-menus';
 export * from './generate-routes-backend';