@blueking/chat-x 0.0.51-beta.5 → 0.0.52-dev.1

package/skills/blueking-chat-x/references/composables/use-animation-text.md

@@ -0,0 +1,196 @@
+# useAnimationText
+
+> 导入：`import { useAnimationText } from '@blueking/chat-x'` ｜ since 1.0.0
+
+useAnimationText 接收 MaybeRef<string> 与可选 AnimationConfig（fadeDuration、easing），返回 chunks 与 animationStyle。 监听文本变化：前缀追加则增量拆分为新 chunk 并触发动画，否则重置为单 chunk，适合流式输出逐段淡入。 全局样式已含 ai-markdown-fade-in。AnimationText 组件内部封装同一逻辑。
+
+**关联**：animation-text（封装 chunks 与样式渲染）、markdown-content（流式 Markdown 文本展示场景可组合使用）
+
+---
+
+# useAnimationText
+
+> **分类**：composable
+
+文本淡入动画的组合式函数。将响应式文本按**增量**拆分为独立 chunk，每个新增 chunk 对应一次淡入动画，适用于 AI 流式输出的逐段渐显效果。
+
+## 工作原理
+
+每当 `text` 发生变化时，composable 通过比较新旧文本决定如何更新 chunks：
+
+| 变化情况                            | 处理方式                  |
+| ----------------------------------- | ------------------------- |
+| 新文本以旧文本为前缀（追加）        | 将增量部分追加为新 chunk  |
+| 新文本与旧文本完全不同（替换/重置） | chunks 重置为 `[newText]` |
+| 文本未变化                          | 无操作                    |
+
+每个 chunk 对应一个独立的 DOM 节点，节点加入 DOM 时自动触发 `ai-markdown-fade-in` 淡入动画。
+
+> `@keyframes ai-markdown-fade-in` 已内置于 `@blueking/chat-x` 全局样式，**无需手动定义**。
+
+## 基础用法
+
+将 `Ref<string>` 传入 composable，配合 `v-for` + `:style` 渲染各 chunk。
+
+```vue
+<template>
+  <div>
+    <span
+      v-for="(chunk, index) in chunks"
+      :key="index"
+      :style="animationStyle"
+      >{{ chunk }}</span
+    >
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useAnimationText } from '@blueking/chat-x';
+
+  const text = ref('');
+  const { chunks, animationStyle } = useAnimationText(text);
+
+  // 模拟流式追加
+  async function startStreaming() {
+    const fullText = '这是一段模拟 AI 流式输出的文本内容...';
+    for (const char of fullText) {
+      text.value += char;
+      await new Promise(resolve => setTimeout(resolve, 50));
+    }
+  }
+
+  startStreaming();
+</script>
+```
+
+**渲染效果**
+
+## 自定义动画配置
+
+通过 `options` 调整淡入动画的持续时间和缓动函数。
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useAnimationText } from '@blueking/chat-x';
+
+  const text = ref('');
+  const { chunks, animationStyle } = useAnimationText(text, {
+    fadeDuration: 600, // 淡入持续时间，默认 200ms
+    easing: 'ease-out', // CSS 缓动函数，默认 'ease-in-out'
+  });
+</script>
+```
+
+**渲染效果**（fadeDuration=600ms）
+
+## 文本重置行为
+
+当 `text` 被完全替换（新值不以旧值为前缀）时，chunks 会重置为单一片段，之前积累的 chunks 清空。这适用于多轮对话中切换消息的场景。
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useAnimationText } from '@blueking/chat-x';
+
+  const text = ref('');
+  const { chunks, animationStyle } = useAnimationText(text);
+
+  async function nextMessage(newContent: string) {
+    // 直接替换整个 text，chunks 自动重置
+    text.value = '';
+    for (const char of newContent) {
+      text.value += char;
+      await new Promise(r => setTimeout(r, 50));
+    }
+  }
+</script>
+```
+
+**渲染效果**（两条消息依次播放，第二条时 chunks 重置）
+
+## 使用 AnimationText 组件
+
+如无需定制渲染逻辑，可直接使用封装好的 `AnimationText` 组件，内部已集成 `useAnimationText`：
+
+```vue
+<template>
+  <AnimationText :text="text" />
+</template>
+
+<script setup lang="ts">
+  import { AnimationText } from '@blueking/chat-x';
+</script>
+```
+
+> 详见 [AnimationText 组件文档](/components/rendering/animation-text)。
+
+## API
+
+### 函数签名
+
+```typescript
+function useAnimationText(
+  text: MaybeRef<string>,
+  options?: AnimationConfig,
+): {
+  chunks: Ref<string[]>;
+  animationStyle: ComputedRef<CSSProperties>;
+};
+```
+
+### 参数
+
+| 参数      | 类型               | 必填 | 说明                                      |
+| --------- | ------------------ | ---- | ----------------------------------------- |
+| `text`    | `MaybeRef<string>` | 是   | 响应式文本，传入 `Ref<string>` 可追踪变化 |
+| `options` | `AnimationConfig`  | 否   | 动画配置                                  |
+
+### AnimationConfig
+
+| 属性           | 类型     | 默认值          | 说明                   |
+| -------------- | -------- | --------------- | ---------------------- |
+| `fadeDuration` | `number` | `200`           | 淡入动画持续时间（ms） |
+| `easing`       | `string` | `'ease-in-out'` | CSS 缓动函数           |
+
+### 返回值
+
+| 属性             | 类型                         | 说明                                       |
+| ---------------- | ---------------------------- | ------------------------------------------ |
+| `chunks`         | `Ref<string[]>`              | 拆分后的文本片段数组，每个片段对应一次动画 |
+| `animationStyle` | `ComputedRef<CSSProperties>` | 所有 chunk 共用的动画样式对象              |
+
+## 类型定义
+
+```typescript
+import type { MaybeRef, Ref, ComputedRef, CSSProperties } from 'vue';
+
+interface AnimationConfig {
+  fadeDuration?: number;
+  easing?: string;
+}
+
+function useAnimationText(
+  text: MaybeRef<string>,
+  options?: AnimationConfig,
+): {
+  chunks: Ref<string[]>;
+  animationStyle: ComputedRef<CSSProperties>;
+};
+```
+
+## 注意事项
+
+1. **在组件 `setup` 中通过 `watch(text, ...)` 直接监听 Ref**：composable 内部使用 `watch(() => text, ...)` 的 getter 形式，当 `text` 是 `Ref` 时，getter 每次返回同一个 Ref 对象，Vue 判断为"值未变化"，**watch 不会触发**。在自定义 setup 中如需直接响应文本变化，请用 `watch(text, handler)` 而非 `watch(() => text, handler)`。
+
+2. **`animationStyle` 为所有 chunk 共享的同一个对象**：动画效果来自每个 chunk 对应的 DOM 节点被创建时触发，而非样式本身的差异。
+
+3. **内置 CSS 关键帧**：引入 `@blueking/chat-x` 的全局样式后，`@keyframes ai-markdown-fade-in` 自动可用，无需手动定义。
+
+4. **性能**：长时间流式输出会积累大量 chunk 节点，动画完成后（`forwards`）这些节点保持 `opacity: 1`，对性能影响可接受；如有需要可在流式结束后将 `text` 合并为单次赋值以归并 chunk
+
+## 关联组件
+
+- [AnimationText](../components/rendering/animation-text) — 默认封装组件
+- [MarkdownContent](../components/rendering/markdown-content) — 富文本流式展示场景。

package/skills/blueking-chat-x/references/composables/use-artifact-preview.md

@@ -0,0 +1,235 @@
+# useArtifactPreview
+
+> 导入：`import { useArtifactPreviewConsumer, useArtifactPreviewProvider } from '@blueking/chat-x'` ｜ since 0.0.20
+
+useArtifactPreviewProvider 维护 activeArtifactId（值为 outputId），openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（每次重新取链，并发去重）； useArtifactPreviewConsumer 在后代注入同一套 API。SessionArtifact 即 AIFileInfo，会话内以 outputId 为唯一键。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成（重载键 outputId:type）。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。
+
+**关联**：chat-container（Provider 主场景，聚合 sessionArtifacts 并挂载 FileArtifactPanel）、file-artifact-panel（侧栏面板消费 activeArtifactId 与 setActiveArtifactId；预览加载在面板内 Host）、assistant-message（文件产物来源 property.artifacts）
+
+---
+
+# useArtifactPreview 文件产物预览
+
+> **分类**：composable
+
+Provider/Consumer 模式的文件产物预览状态管理。Provider 在 `ChatContainer` 中创建，负责维护当前命中的文件 `outputId`；Consumer 在深层 `ArtifactFileCard` 中注入，用于点击卡片触发预览。
+
+**职责边界**：
+
+- **本 composable**：维护「命中文件」与「URL 解析」（每次重新取链 + 并发去重）；打开侧栏 Tab（`addCustomTab`）由容器通过 `onOpen` 注入
+- **不在本 composable**：聚合会话文件列表、渲染预览面板、按类型 fetch 正文 / iframe 展示 —— 分别由 `useMessageGroup.sessionArtifacts`、`FileArtifactPanel`、内部 `ArtifactPreviewHost` + `useArtifactPreviewLoader` 承担（预览重载键为 `outputId:type`）
+
+## 函数签名
+
+### useArtifactPreviewProvider
+
+```typescript
+function useArtifactPreviewProvider(options: {
+  /** 读取业务侧异步取链回调（getter 保持对 props 变更敏感） */
+  getOnArtifactClick?: () => OnArtifactClick | undefined;
+  /** 命中文件后触发：由容器负责 addCustomTab + 展开侧栏 + 选中 Tab */
+  onOpen: (outputId: string) => void;
+}): {
+  activeArtifactId: ShallowRef<string>;
+  canResolveArtifactUrl: ComputedRef<boolean>;
+  openPreview: (payload: OpenArtifactPreviewPayload) => void;
+  resolveArtifactUrls: (file: AIFileInfo) => Promise<ArtifactUrlResult>;
+  setActiveArtifactId: (id: string) => void;
+};
+```
+
+### useArtifactPreviewConsumer
+
+```typescript
+function useArtifactPreviewConsumer():
+  | undefined
+  | {
+      activeArtifactId: Ref<string>;
+      canResolveArtifactUrl: ComputedRef<boolean>;
+      openPreview: (payload: OpenArtifactPreviewPayload) => void;
+      resolveArtifactUrls: (file: AIFileInfo) => Promise<ArtifactUrlResult>;
+      setActiveArtifactId: (id: string) => void;
+    };
+```
+
+## 使用示例
+
+### Provider（ChatContainer）
+
+会话级文件产物由 [`useMessageGroup`](./use-message-group) 统一聚合（`sessionArtifacts`），Provider 只负责命中与打开侧栏 Tab：
+
+```typescript
+import {
+  useArtifactPreviewProvider,
+  useCustomTabProvider,
+  useMessageGroup,
+  FILE_ARTIFACT_TAB_NAME,
+} from '@blueking/chat-x';
+import { t } from '@blueking/chat-x/lang';
+
+const { addCustomTab, ensureCustomTab, removeCustomTab } = useCustomTabProvider({ /* ... */ });
+
+// 会话级文件产物聚合已内聚在 useMessageGroup，直接消费
+const { sessionArtifacts } = useMessageGroup({ keyword, messages, selectedUserMessages });
+
+const FILE_ARTIFACT_TAB = {
+  closable: false,
+  label: t('文件产物'),
+  name: FILE_ARTIFACT_TAB_NAME,
+  order: -1,
+};
+
+// 常驻挂载：不随产物有无增删，无产物时由面板展示空态
+ensureCustomTab(FILE_ARTIFACT_TAB);
+
+const { activeArtifactId, setActiveArtifactId } = useArtifactPreviewProvider({
+  getOnArtifactClick: () => props.onArtifactClick,
+  // 点击文件卡片：展开侧栏并选中「文件产物」Tab
+  onOpen: () => {
+    addCustomTab(FILE_ARTIFACT_TAB);
+  },
+});
+
+// 仅维护命中态：无产物清空，命中项失效时回落到第一个
+watch(sessionArtifacts, list => {
+  if (!list.length) {
+    setActiveArtifactId('');
+    return;
+  }
+  if (!list.some(item => item.outputId === activeArtifactId.value)) {
+    setActiveArtifactId(list[0].outputId);
+  }
+}, { immediate: true });
+```
+
+### Consumer（ArtifactFileCard）
+
+```typescript
+import { useArtifactPreviewConsumer } from '@blueking/chat-x';
+
+const artifactPreview = useArtifactPreviewConsumer();
+
+// 有 Provider 时卡片可点击；无 Provider 时返回 undefined，卡片不可点击
+const clickable = computed(() => !!props.onPreview || !!artifactPreview);
+
+const handleCardClick = () => {
+  if (props.onPreview) {
+    props.onPreview(props.file);
+    return;
+  }
+  artifactPreview?.openPreview({ file: props.file });
+};
+```
+
+### 侧栏列表内切换命中文件
+
+```typescript
+// FileArtifactPanel 列表点击 → emit select(outputId) → 容器调用 setActiveArtifactId
+// 右侧预览由面板内 ArtifactPreviewHost 消费 activeArtifact，自行取链并按类型渲染
+<FileArtifactPanel
+  :active-id="activeArtifactId"
+  :artifacts="sessionArtifacts"
+  @select="setActiveArtifactId"
+/>
+```
+
+### 业务侧取链（ChatContainer `onArtifactClick`）
+
+文本类预览需要可 `fetch` 的 `download_url`；iframe 类需要 `preview_url`（一般为后台转好的 PDF）：
+
+```typescript
+const onArtifactClick = async (file: AIFileInfo) => {
+  const res = await api.getArtifactUrls(file.outputId);
+  return {
+    download_url: res.download_url,
+    preview_url: res.preview_url,
+  };
+};
+```
+
+## 内置常量
+
+| 常量名                    | 值                 | 说明                                      |
+| ------------------------- | ------------------ | ----------------------------------------- |
+| `FILE_ARTIFACT_TAB_NAME`  | `'file-artifact'`  | 「文件产物」侧栏 Tab 的固定标识，不可关闭 |
+| `ARTIFACT_PREVIEW_TOKEN`  | `Symbol`           | provide/inject 注入 Token                 |
+
+## 返回值说明
+
+| 属性/方法名         | 类型                                      | 说明                                                                 |
+| ------------------- | ----------------------------------------- | -------------------------------------------------------------------- |
+| activeArtifactId    | `ShallowRef<string>`                      | 当前命中的文件 `outputId`                                            |
+| canResolveArtifactUrl | `ComputedRef<boolean>`                  | 是否具备异步取链能力（有 `onArtifactClick` 时为 true，下载按钮据此显隐） |
+| openPreview         | `(payload: OpenArtifactPreviewPayload) => void` | 由文件卡片或 `artifact` 资源标签触发：以 `file.outputId` 更新命中态、调用 `onOpen`；入参只需 `{ file: { outputId } }` |
+| resolveArtifactUrls | `(file: AIFileInfo) => Promise<ArtifactUrlResult>` | 调用 `onArtifactClick` 取链；每次重新获取，不缓存；同文件并发去重 |
+| setActiveArtifactId | `(id: string) => void`                    | 直接设置命中文件 `outputId`；侧栏列表内切换选中时使用                |
+
+## 类型定义
+
+```typescript
+import type { AIFileInfo, ArtifactUrlResult, OnArtifactClick } from '@blueking/chat-x';
+
+/**
+ * 打开预览时的入参。
+ * 命中逻辑只依赖 outputId，因此不要求完整的 AIFileInfo——
+ * 输入框内的 @ 文件标签只持有 id 与名称，无需为了调用而伪造 size / type。
+ */
+type OpenArtifactPreviewPayload = {
+  file: Pick<AIFileInfo, 'outputId'>;
+};
+
+/**
+ * 会话级文件产物：以 outputId 为会话内唯一键（同 outputId 视为同一文件）。
+ * 拍平去重后即为 AIFileInfo，此处用别名标明语义。
+ */
+type SessionArtifact = AIFileInfo;
+
+/** onArtifactClick 返回值（snake_case） */
+type ArtifactUrlResult = {
+  download_url?: string;
+  preview_url?: string;
+};
+```
+
+## 唯一键规则
+
+会话内以 **`outputId`** 作为文件产物唯一键：
+
+- 同一 `outputId` 在多条 `AssistantMessage` 中出现时，`sessionArtifacts` 去重并保留**最后一次**出现的文件信息
+- `activeArtifactId`、列表 `:key`、`select` 事件参数均使用 `outputId`
+- 文件名可能重复，**不可**作为唯一键
+
+## 完整触发链路
+
+```
+ArtifactFileCard（点击）
+  └─ useArtifactPreviewConsumer().openPreview({ file })
+       └─ useArtifactPreviewProvider（ChatContainer）
+            ├─ activeArtifactId = file.outputId
+            └─ onOpen(outputId) → addCustomTab(FILE_ARTIFACT_TAB_NAME) 展开并选中
+                 └─ FileArtifactPanel（列表 + 下载头，@select → setActiveArtifactId）
+                      └─ ArtifactPreviewHost（loader + 分类型 renderer）
+
+容器初始化
+  └─ ensureCustomTab(FILE_ARTIFACT_TAB_NAME) 常驻挂上（不展开侧栏）；因 order:-1 排在首位，
+     未主动切换过 Tab 时会成为默认选中面板；无产物时由面板展示整块空态
+
+sessionArtifacts 变化
+  └─ 仅维护命中态（无产物清空，命中项失效回落第一个）；不增删 Tab
+```
+
+分类型预览策略见 [FileArtifactPanel 预览机制](../components/message/file-artifact-panel#预览机制)。
+
+## 设计特点
+
+- **职责单一**：composable 不直接调用 `useCustomTab`，侧栏 Tab 打开逻辑由 `onOpen` 注入；也不做正文 fetch / iframe 渲染
+- **ShallowRef 优先**：`activeArtifactId` 使用 `shallowRef`，避免不必要的深层响应式开销
+- **Consumer 兜底**：`useArtifactPreviewConsumer` 无 Provider 时返回 `undefined`，文件卡片在无容器上下文时自动不可点击
+- **与 useCustomTab 协作**：点击卡片走 `addCustomTab`（展开 + 选中）；容器初始化时走 `ensureCustomTab` 常驻挂载（不展开；因 `order: -1` 在未主动切换前会成为默认选中），无产物也不移除，由面板展示空态
+
+## 关联组件
+
+- [ChatContainer](../components/setup/chat-container) — Provider 主场景，内置「文件产物」Tab
+- [FileArtifactPanel](../components/message/file-artifact-panel) — 侧栏列表与预览 Host 挂载
+- [AssistantMessage](../components/message/assistant-message) — 文件产物来源（`property.artifacts`）
+- [useCustomTab](./use-custom-tab) — `addCustomTab` / `ensureCustomTab` 分工

package/skills/blueking-chat-x/references/composables/use-clipboard.md

@@ -0,0 +1,203 @@
+# useClipboard
+
+> 导入：`import { useClipboard } from '@blueking/chat-x'` ｜ since 1.0.0
+
+useClipboard 返回 { copy }，copy(text) 将字符串写入剪贴板，返回 Promise<void>。 优先使用 navigator.clipboard.writeText，失败或不支持时降级为隐藏 textarea + execCommand('copy')。 成功/失败均通过 bkui-vue Message 提示，调用方无需处理结果。CodeContent、MessageContainer、UserMessage 的复制能力内部使用。
+
+**关联**：code-content（复制代码块时取 innerText 后调用 copy）、message-container（AI 消息复制工具回调）、user-message（用户消息复制工具回调）
+
+---
+
+# useClipboard 剪贴板
+
+> **分类**：composable
+
+复制文本到剪贴板的组合式函数。内置两级降级策略，并自动通过 bkui-vue `Message` 提示复制结果，调用方无需关心成功/失败处理。
+
+## 执行流程
+
+```
+copy(text)
+  │
+  ├── isClipboardApiSupported（模块加载时判断一次）
+  │     = typeof navigator !== 'undefined' && 'clipboard' in navigator
+  │
+  ├── true → navigator.clipboard.writeText(text)
+  │           ├── 成功 → success = true
+  │           └── 失败（权限拒绝等）→ legacyCopy(text)
+  │
+  └── false → legacyCopy(text)
+              （创建隐藏 textarea，document.execCommand('copy')，finally 清理 DOM）
+  │
+  └── Message({ message: t('复制成功/失败'), theme: 'success/error' })
+```
+
+> **注意**：`copy` 返回 `Promise<void>`，调用方无法获取成功/失败结果；通知由内部自动弹出，不可关闭或自定义。
+
+## 基础用法
+
+```vue
+<template>
+  <button @click="handleCopy">复制文本</button>
+</template>
+
+<script setup lang="ts">
+  import { useClipboard } from '@blueking/chat-x';
+
+  const { copy } = useClipboard();
+
+  const handleCopy = () => {
+    copy('Hello, World!');
+    // 自动弹出"复制成功/失败"提示，无需额外处理
+  };
+</script>
+```
+
+## 复制代码块内容
+
+`CodeContent` 组件内部的实际用法，取 DOM 元素的 `innerText` 避免 HTML 实体：
+
+```vue
+<template>
+  <div class="code-block">
+    <pre ref="codeRef"><code>{{ code }}</code></pre>
+    <button @click="handleCopyCode">复制代码</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { useTemplateRef } from 'vue';
+  import { useClipboard } from '@blueking/chat-x';
+
+  const codeRef = useTemplateRef<HTMLElement>('codeRef');
+  const { copy } = useClipboard();
+
+  // 使用 innerText 获取渲染后的纯文本，而非原始 token.content
+  const handleCopyCode = () => {
+    copy(codeRef.value?.innerText ?? '');
+  };
+</script>
+```
+
+## 复制消息内容
+
+`MessageContainer` 和 `UserMessage` 内部的实际用法：
+
+```vue
+<script setup lang="ts">
+  import { useClipboard } from '@blueking/chat-x';
+
+  const { copy } = useClipboard();
+
+  // 在 onAction 工具回调中调用
+  const onAction = tool => {
+    if (tool.id === 'copy') {
+      copy(props.content ?? '');
+    }
+  };
+</script>
+```
+
+## API
+
+### 返回值
+
+| 属性名 | 类型                              | 说明                                                 |
+| ------ | --------------------------------- | ---------------------------------------------------- |
+| copy   | `(text: string) => Promise<void>` | 复制文本；内部自动弹出结果提示，调用方无需处理返回值 |
+
+### copy(text)
+
+```typescript
+const copy: (text: string) => Promise<void>;
+```
+
+**参数：**
+
+- `text: string`：要复制的文本内容
+
+**内部行为：**
+
+| 步骤         | 说明                                                                                                           |
+| ------------ | -------------------------------------------------------------------------------------------------------------- |
+| 1. 能力检测  | 模块导入时执行一次：`typeof navigator !== 'undefined' && 'clipboard' in navigator`                             |
+| 2a. 现代路径 | `navigator.clipboard.writeText(text)`，捕获异常后降级到步骤 2b                                                 |
+| 2b. 降级路径 | 创建隐藏 `textarea`（`position: fixed; left: -9999px; opacity: 0`），`execCommand('copy')`，`finally` 清理 DOM |
+| 3. 通知      | 始终调用 `Message({ message: t('复制成功/失败'), theme: 'success/error' })`                                    |
+
+## 实现源码
+
+```typescript
+import { Message } from 'bkui-vue';
+import { t } from '../lang/lang';
+
+// 模块加载时检测一次，SSR 安全
+const isClipboardApiSupported = typeof navigator !== 'undefined' && 'clipboard' in navigator;
+
+const legacyCopy = (text: string): boolean => {
+  const textarea = document.createElement('textarea');
+  textarea.value = text;
+  textarea.style.cssText = 'position:fixed;left:-9999px;top:-9999px;opacity:0';
+  document.body.appendChild(textarea);
+  textarea.focus();
+  textarea.select();
+  try {
+    return document.execCommand('copy');
+  } catch {
+    return false;
+  } finally {
+    document.body.removeChild(textarea); // 无论成败都清理 DOM
+  }
+};
+
+export const useClipboard = () => {
+  const copy = async (text: string) => {
+    let success = false;
+    if (isClipboardApiSupported) {
+      try {
+        await navigator.clipboard.writeText(text);
+        success = true;
+      } catch {
+        success = legacyCopy(text); // Clipboard API 失败时降级
+      }
+    } else {
+      success = legacyCopy(text);
+    }
+    Message({
+      message: success ? t('复制成功') : t('复制失败'),
+      theme: success ? 'success' : 'error',
+    });
+  };
+
+  return { copy };
+};
+```
+
+## 兼容性
+
+| 策略                            | 触发条件                                      | 要求                                           |
+| ------------------------------- | --------------------------------------------- | ---------------------------------------------- |
+| `navigator.clipboard.writeText` | 浏览器支持 Clipboard API                      | HTTPS 或 localhost；用户需授权剪贴板权限       |
+| `document.execCommand('copy')`  | 不支持 Clipboard API，或 `writeText` 抛出异常 | 需由用户事件（如 click）直接触发，否则可能失败 |
+
+## 内部使用场景
+
+| 组件               | 用途                                      |
+| ------------------ | ----------------------------------------- |
+| `CodeContent`      | 复制代码块，取 `codeRef.value?.innerText` |
+| `MessageContainer` | 复制 AI 消息内容                          |
+| `UserMessage`      | 复制用户消息内容                          |
+
+## 注意事项
+
+1. **结果不对外暴露**：`copy` 返回 `Promise<void>`，调用方无法获知成功/失败；如需自定义通知，不应使用此 composable
+2. **通知使用 i18n**：消息文本通过 `t()` 函数处理，在多语言环境下自动切换，无法在外部覆盖
+3. **`isClipboardApiSupported` 模块级检测**：在文件 import 时执行一次（非响应式），SSR 环境下 `navigator` 为 `undefined` 时安全降级
+4. **`execCommand` 已废弃**：降级路径依赖 `document.execCommand('copy')`，该 API 在部分浏览器已标记废弃，但目前仍广泛可用
+5. **用户手势要求**：在没有用户交互上下文时（如定时器回调），两种方式都可能失败
+
+## 关联组件
+
+- [CodeContent](../components/rendering/code-content) — 代码块复制
+- [MessageContainer](../components/setup/message-container) — 助手消息复制
+- [UserMessage](../components/message/user-message) — 用户消息复制