@blueking/chat-x 0.0.5 → 0.0.7

package/dist/mcp/generated/docs/animation-text.md

@@ -0,0 +1,199 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+AnimationText 将文本拆成 chunk 并以淡入 keyframes 逐段显示，适合短文案一次性展示。 props.text 仅在挂载时参与动画；持续流式场景应直接使用 useAnimationText 或自行 watch Ref。 与 Markdown 流式渐显等场景可组合使用。
+
+### 关联组件
+- **use-animation-text** — 提供 chunk 拆分与 animationStyle 的 composable
+- **markdown-content** — 流式 Markdown 中可与渐显策略配合
+
+---
+<!-- FULL DOC -->
+
+# AnimationText 动画文本
+
+> **层级**：原子组件 · **功能域**：内容渲染
+
+动画文本原子组件，将文本以**淡入（fade-in）**方式渐显。内部由 `useAnimationText` composable 驱动，核心能力是将增量文本拆分为独立 chunk，每个 chunk 单独触发一次淡入动画，适用于流式文本的逐段渐显效果。
+
+## 组件结构
+
+```
+AnimationText
+└── <span v-for="chunk in chunks" :style="animationStyle">
+       {{ chunk }}
+    </span>
+
+animationStyle = {
+  animation: `ai-markdown-fade-in {fadeDuration}ms {easing} forwards`,
+  color: 'inherit',
+}
+
+@keyframes ai-markdown-fade-in {
+  0%   { opacity: 0; }
+  100% { opacity: 1; }
+}
+```
+
+> **注意**：`AnimationText` 组件将 `props.text`（字符串原始值）传给 `useAnimationText`，watch 只触发一次（挂载时），**prop 变化后不会触发新动画**。若需响应式流式效果，请直接使用 `useAnimationText` composable，并传入 `Ref<string>`。
+
+## 基础用法
+
+挂载时文本以淡入方式显示，适合一次性展示的短文本动画：
+
+```vue
+<template>
+  <AnimationText text="这是一段带动画效果的文本" />
+</template>
+
+<script setup lang="ts">
+  import { AnimationText } from '@blueking/chat-x';
+</script>
+```
+
+## 流式文本（推荐使用 composable）
+
+对于流式输出场景，需直接使用 `useAnimationText` 并传入响应式 `Ref<string>`：
+
+```vue
+<template>
+  <span
+    v-for="(chunk, index) in streamChunks"
+    :key="index"
+    :style="streamAnimStyle"
+    >{{ chunk }}</span
+  >
+</template>
+
+<script setup lang="ts">
+  import { ref, watch } from 'vue';
+
+  const streamText = ref('');
+  const streamChunks = ref<string[]>([]);
+  const streamAnimStyle = {
+    animation: 'ai-markdown-fade-in 200ms ease-in-out forwards',
+    color: 'inherit',
+  };
+
+  // 直接 watch Ref（Vue 自动追踪 .value 变化）
+  // ⚠️ 不能写成 watch(() => streamText, ...)，那样 getter 每次返回同一个 Ref 引用，永远不触发
+  watch(streamText, (newVal, oldVal) => {
+    if (!oldVal || !newVal.startsWith(oldVal)) {
+      streamChunks.value = [newVal]; // 内容替换 → 整体重置
+    } else {
+      const chunk = newVal.slice(oldVal.length);
+      if (chunk) streamChunks.value = [...streamChunks.value, chunk]; // 追加 → 新 chunk 淡入
+    }
+  });
+
+  // 模拟流式追加
+  async function receiveStream() {
+    streamText.value = '';
+    streamChunks.value = [];
+    for (const char of '来自 AI 的流式回复内容...') {
+      streamText.value += char;
+      await new Promise(r => setTimeout(r, 80));
+    }
+  }
+</script>
+```
+
+**效果演示**（点击按钮触发流式输出）
+
+## chunk 增量算法
+
+`useAnimationText` 内部通过**前缀检测**将文本变化拆分为增量 chunk：
+
+```
+新文本以旧文本为前缀（即纯追加）→ 截取增量部分 → 追加新 chunk（触发新动画）
+新文本与旧文本无前缀关系（内容替换）→ 清空所有 chunk → 用完整新文本创建单一 chunk
+```
+
+```typescript
+// watch 内部逻辑（简化）
+if (newText === prevText) return; // 无变化，跳过
+
+if (prevText && newText.startsWith(prevText)) {
+  // 追加模式：只有新增部分触发淡入
+  const newChunk = newText.slice(prevText.length);
+  chunks.value = [...chunks.value, newChunk];
+} else {
+  // 重置模式：内容替换，整体重新淡入
+  chunks.value = [newText];
+}
+prevText = newText;
+```
+
+| 场景            | 示例                                       | 行为                           |
+| --------------- | ------------------------------------------ | ------------------------------ |
+| 流式追加（SSE） | `"Hello"` → `"Hello Wo"` → `"Hello World"` | 每次增量部分单独淡入           |
+| 内容完全替换    | `"旧文本"` → `"新文本"`                    | 清空所有 chunk，新文本整体淡入 |
+| 相同内容        | `"文本"` → `"文本"`                        | 不做任何处理，跳过             |
+
+## 自定义动画参数
+
+`useAnimationText` 支持通过第二个参数自定义动画时长和缓动：
+
+```typescript
+import { ref } from 'vue';
+import { useAnimationText } from '@blueking/chat-x';
+
+const text = ref('');
+const { chunks, animationStyle } = useAnimationText(text, {
+  fadeDuration: 400, // 动画时长（ms），默认 200
+  easing: 'ease-out', // CSS easing，默认 'ease-in-out'
+});
+```
+
+生成的 `animationStyle`：
+
+```typescript
+// animationStyle 是 computed，格式为：
+{
+  animation: `ai-markdown-fade-in ${fadeDuration}ms ${easing} forwards`,
+  color: 'inherit',
+}
+```
+
+> **关键帧**：`ai-markdown-fade-in` 定义在库的全局样式中，仅做透明度变化（`opacity: 0 → 1`），无位移或缩放。
+
+## API
+
+### AnimationText Props
+
+| 属性名 | 类型     | 必填 | 说明                                            |
+| ------ | -------- | ---- | ----------------------------------------------- |
+| text   | `string` | ✓    | 要显示的文本；仅挂载时触发动画，prop 更新后无效 |
+
+### useAnimationText
+
+```typescript
+function useAnimationText(
+  text: MaybeRef<string>, // 字符串或 Ref<string>，传 Ref 才能响应变化
+  options?: AnimationConfig,
+): {
+  chunks: Ref<string[]>; // 分割后的文本块数组，v-for 遍历渲染
+  animationStyle: ComputedRef<{
+    // 应用到每个 <span> 的 inline style
+    animation: string;
+    color: 'inherit';
+  }>;
+};
+
+interface AnimationConfig {
+  fadeDuration?: number; // 动画时长（ms），默认 200
+  easing?: string; // CSS easing，默认 'ease-in-out'
+}
+```
+
+## 注意事项
+
+1. **`AnimationText` 不响应 prop 更新**：组件内部传的是字符串原始值，若需动态响应，直接用 `watch(myRef, ...)` 手动实现 chunk 逻辑
+2. **流式场景不要使用 `useAnimationText`**：该 composable 内部使用 `watch(() => text, ...)` 的 getter 形式，当传入 `Ref<string>` 时，getter 每次返回同一个 Ref 引用，Vue 无法检测到 `.value` 变化，watch 只触发一次（immediate）。正确做法是直接 `watch(streamText, callback)` 绑定 Ref
+3. **动画 keyframe 依赖全局样式**：使用 `@blueking/chat-x` 时会自动引入；独立使用时需确保 `ai-markdown-fade-in` 已定义
+4. **chunks 只增不减**（追加模式下）：流式结束后 chunks 保留所有历史分段，若需复用，手动清空 `chunks.value = []` 再重置文本即可
+
+## 关联组件
+
+- [useAnimationText](../../composables/use-animation-text.md) — chunk 与动画样式逻辑
+- [MarkdownContent](./markdown-content.md) — 流式正文渲染时可配合渐显

package/dist/mcp/generated/docs/assistant-message.md

@@ -0,0 +1,424 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+AssistantMessage 渲染 AI 助手回复：正文由 ContentRender（可被默认插槽替换）与 ToolCallRender 展示工具调用及 MCP 标记。 toolCalls[].toolMessage 可内联工具执行结果。用于 MessageRender 分发的 assistant 角色，流式场景配合 streaming 状态更新。
+
+### 关联组件
+- **message-render** — 由 MessageRender 在 role 为 assistant 时创建
+- **tool-message** — 工具结果通过 toolCall.toolMessage 内联或独立 tool 消息关联展示
+- **toolcall-render** — 多条工具调用由 ToolcallRender 统一渲染
+
+---
+<!-- FULL DOC -->
+
+# AssistantMessage AI 助手消息
+
+> **层级**：分子组件 · **功能域**：消息展示
+
+AI 助手消息展示组件，负责渲染 AI 回复的文本内容和工具调用（Tool Calls）结果。
+
+## 渲染管线
+
+```
+AssistantMessage
+├── assistant-message-content（内容区）
+│   └── [default slot] 或 ContentRender → MarkdownContent（Markdown 渲染）
+└── ToolCallRender × N（每个 toolCall 独立渲染，不受 slot 影响）
+```
+
+- **内容区**：`content` 字符串传入 `ContentRender`，内部固定使用 `MessageContentType.Text` 类型，最终由 `MarkdownContent` 渲染 Markdown
+- **工具调用区**：`toolCalls` 数组中每一项渲染一个 `ToolCallRender`，位于内容区**下方**，与 slot 无关
+
+## 基础用法
+
+```vue
+<template>
+  <AssistantMessage
+    :content="content"
+    :status="status"
+  />
+</template>
+
+<script setup lang="ts">
+  import { AssistantMessage, MessageStatus } from '@blueking/chat-x';
+
+  const content = '你好！我是 AI 助手，有什么可以帮助你的吗？';
+  const status = MessageStatus.Complete;
+</script>
+```
+
+**渲染效果**
+
+## Markdown 内容渲染
+
+`content` 支持 Markdown 格式，组件内部通过 `MarkdownContent` 自动渲染标题、列表、代码块、链接等：
+
+```vue
+<template>
+  <AssistantMessage
+    :content="markdownContent"
+    status="complete"
+  />
+</template>
+
+<script setup lang="ts">
+  import { AssistantMessage } from '@blueking/chat-x';
+
+  const markdownContent = `## Vue 3 核心特性
+
+Vue 3 引入了多项重要更新：
+
+1. **Composition API**：提供更灵活的逻辑组织方式
+2. **性能优化**：虚拟 DOM 重写，编译时优化
+3. **TypeScript 支持**：内置完整的类型定义
+
+\\\`\\\`\\\`typescript
+import { ref, computed } from 'vue';
+
+const count = ref(0);
+const doubled = computed(() => count.value * 2);
+\\\`\\\`\\\`
+
+> 更多详情请参考 [Vue 3 官方文档](https://vuejs.org)。`;
+</script>
+```
+
+**渲染效果**
+
+## 消息状态
+
+`status` 影响两处渲染：**内容区**和**工具调用状态标题**。
+
+| `status`    | 内容区效果                          | ToolCallRender 标题 |
+| ----------- | ----------------------------------- | ------------------- |
+| `pending`   | 正常渲染（通常 content 为空）       | Loading + "调用中"  |
+| `streaming` | Markdown 自动补全未闭合语法         | Loading + "调用中"  |
+| `complete`  | 正常渲染完整 Markdown               | "调用成功" + 耗时   |
+| `error`     | 红色错误图标 + content 作为错误提示 | "调用失败"          |
+| `stop`      | 正常渲染（内容停留在中止时的状态）  | "调用成功"          |
+
+### Pending
+
+### Streaming
+
+流式输出中，`MarkdownContent` 自动补全未闭合的 Markdown 语法（代码块、列表等），适合逐字/逐段追加内容：
+
+### Complete
+
+### Error
+
+渲染为错误信息样式（红色错误图标），`content` 作为错误提示文案展示：
+
+### Stop
+
+用户手动中止生成，内容停留在中止时的状态，与 `complete` 表现相同：
+
+## 工具调用
+
+当 AI 回复中包含工具调用时，传入 `toolCalls` 数组，每项自动渲染为 `ToolCallRender`，位于内容区下方。`status` 会同步传递给每个 `ToolCallRender` 以反映调用状态。
+
+### 单个工具调用
+
+```vue
+<template>
+  <AssistantMessage
+    content="让我帮你查询一下天气信息。"
+    :status="MessageStatus.Complete"
+    :tool-calls="toolCalls"
+  />
+</template>
+
+<script setup lang="ts">
+  import { AssistantMessage, MessageStatus } from '@blueking/chat-x';
+
+  const toolCalls = [
+    {
+      id: 'call_1',
+      type: 'function',
+      function: {
+        name: 'get_weather',
+        arguments: '{"city": "北京", "unit": "celsius"}',
+        description: '获取指定城市的天气信息',
+      },
+    },
+  ];
+</script>
+```
+
+**渲染效果**
+
+### 多个工具调用
+
+AI 可在一次回复中发起多个工具调用，组件依次渲染：
+
+```vue
+<script setup lang="ts">
+  const toolCalls = [
+    {
+      id: 'call_1',
+      type: 'function',
+      function: {
+        name: 'search_documents',
+        arguments: '{"query": "Vue 3 Composition API"}',
+        description: '搜索知识库中的相关文档',
+      },
+    },
+    {
+      id: 'call_2',
+      type: 'function',
+      function: {
+        name: 'get_code_snippet',
+        arguments: '{"language": "typescript", "topic": "ref vs reactive"}',
+        description: '获取代码示例片段',
+      },
+    },
+  ];
+</script>
+```
+
+**渲染效果**
+
+### MCP 工具调用
+
+`function.mcpName` 标识 MCP 服务名称，`ToolCallRender` 的标题会显示为「调用 MCP：{mcpName} / {name}」：
+
+```vue
+<script setup lang="ts">
+  const toolCalls = [
+    {
+      id: 'call_mcp_1',
+      type: 'function',
+      function: {
+        name: 'query_database',
+        arguments: '{"sql": "SELECT * FROM users LIMIT 10"}',
+        description: '执行数据库查询',
+        mcpName: 'database-server', // MCP 服务名
+      },
+    },
+  ];
+</script>
+```
+
+**渲染效果**
+
+### 携带执行结果
+
+`toolMessage` 字段包含工具的执行结果；`ToolCallRender` 会展示返回内容（JSON 自动解析为键值对）和执行耗时：
+
+```vue
+<script setup lang="ts">
+  const toolCalls = [
+    {
+      id: 'call_1',
+      type: 'function',
+      function: {
+        name: 'get_weather',
+        arguments: '{"city": "北京"}',
+        description: '获取天气信息',
+      },
+      toolMessage: {
+        role: 'tool',
+        content: '{"weather":"晴","temperature":"22°C","humidity":"45%","wind":"东北风 3 级"}',
+        status: 'complete',
+        duration: 1200, // 毫秒
+        toolCallId: 'call_1',
+      },
+    },
+  ];
+</script>
+```
+
+**渲染效果**（点击展开箭头可查看返回结果）
+
+### 工具调用失败
+
+`toolMessage.error` 不为空时，`ToolCallRender` 显示错误信息：
+
+```vue
+<script setup lang="ts">
+  const toolCalls = [
+    {
+      id: 'call_1',
+      type: 'function',
+      function: {
+        name: 'get_weather',
+        arguments: '{"city": "北京"}',
+        description: '获取天气信息',
+      },
+      toolMessage: {
+        role: 'tool',
+        content: '',
+        status: 'error',
+        error: 'API rate limit exceeded',
+        duration: 350,
+        toolCallId: 'call_1',
+      },
+    },
+  ];
+</script>
+```
+
+**渲染效果**
+
+### 工具调用状态随消息状态变化
+
+`ToolCallRender` 的状态标题直接来自 `AssistantMessage` 的 `status` prop：
+
+**调用中**（`status = "streaming"`）：
+
+**调用成功**（`status = "complete"` + `toolMessage`）：
+
+## 自定义内容渲染
+
+默认插槽替换**内容区**的渲染（即 `ContentRender` 部分），工具调用仍在内容区外独立渲染，不受插槽影响：
+
+```
+[自定义 slot 内容]   ← 替换这里
+[ToolCallRender]     ← 不受影响，仍正常渲染
+[ToolCallRender]
+```
+
+```vue
+<template>
+  <AssistantMessage
+    :content="content"
+    :tool-calls="toolCalls"
+  >
+    <template #default="{ content }">
+      <div style="padding: 12px; background: #f0f9ff; border-left: 3px solid #3a84ff; border-radius: 4px;">
+        🤖 {{ content }}
+      </div>
+    </template>
+  </AssistantMessage>
+</template>
+```
+
+> **注意**：使用默认插槽后，内置的 `MarkdownContent`（Markdown 渲染）被替换，需要自行处理内容格式化。
+
+**渲染效果**
+
+## 在 MessageContainer 中使用
+
+`AssistantMessage` 通常不需要单独引入，`MessageContainer` 会对 `role: 'assistant'` 的消息自动渲染：
+
+```vue
+<template>
+  <MessageContainer :messages="messages" />
+</template>
+
+<script setup lang="ts">
+  import { MessageContainer } from '@blueking/chat-x';
+
+  const messages = [
+    {
+      id: '1',
+      messageId: '1',
+      role: 'user',
+      content: '北京今天天气怎么样？',
+      status: 'complete',
+    },
+    {
+      id: '2',
+      messageId: '2',
+      role: 'assistant',
+      content: '让我帮你查询一下天气信息。',
+      status: 'complete',
+      toolCalls: [
+        {
+          id: 'call_1',
+          type: 'function',
+          function: {
+            name: 'get_weather',
+            arguments: '{"city": "北京"}',
+            description: '获取天气',
+          },
+          toolMessage: {
+            role: 'tool',
+            content: '{"weather":"晴","temperature":"22°C"}',
+            status: 'complete',
+            duration: 800,
+            toolCallId: 'call_1',
+          },
+        },
+      ],
+    },
+    {
+      id: '3',
+      messageId: '3',
+      role: 'assistant',
+      content: '北京今天天气晴朗，气温 22°C，适合出行。',
+      status: 'complete',
+    },
+  ];
+</script>
+```
+
+## API
+
+### Props
+
+组件 Props 来自 `Partial<AssistantMessage>`（所有字段均可选）：
+
+| 属性名    | 类型                    | 说明                                                           |
+| --------- | ----------------------- | -------------------------------------------------------------- |
+| content   | `string`                | AI 回复的文本内容，支持 Markdown，`undefined` 时渲染为空字符串 |
+| status    | `MessageStatus`         | 消息状态，影响 Markdown 渲染模式和 ToolCallRender 的状态标题   |
+| toolCalls | `ToolCall[]`            | 工具调用列表，每项渲染一个 `ToolCallRender`                    |
+| id        | `number \| string`      | 消息 ID                                                        |
+| messageId | `number \| string`      | 消息唯一标识                                                   |
+| name      | `string`                | 消息发送者名称（可选）                                         |
+| role      | `MessageRole.Assistant` | 消息角色，固定为 `'assistant'`                                 |
+| property  | `object`                | 消息附加属性，本组件不使用，由父组件（`MessageContainer`）消费 |
+
+### Slots
+
+| 插槽名  | 参数                  | 说明                                                 |
+| ------- | --------------------- | ---------------------------------------------------- |
+| default | `{ content: string }` | 替换内容区渲染，toolCalls 在内容区外独立渲染不受影响 |
+
+## 类型定义
+
+```typescript
+import type { AssistantMessage, ToolCall, FunctionCall, ToolMessage } from '@blueking/chat-x';
+
+interface AssistantMessage extends BaseMessage<MessageRole.Assistant> {
+  toolCalls?: ToolCall[];
+}
+
+// 工具调用
+type ToolCall = {
+  id: string;
+  type: MessageContentType.Function; // 固定为 'function'
+  function: FunctionCall;
+  toolMessage?: Partial<ToolMessage>; // 工具执行结果（可选）
+};
+
+// 函数调用信息
+type FunctionCall = {
+  name: string; // 函数名
+  arguments: string; // JSON 字符串格式的参数
+  description?: string; // 函数描述
+  mcpName?: string; // MCP 服务名（存在时标题显示 "调用 MCP"）
+};
+
+// 工具执行结果
+interface ToolMessage extends BaseMessage<MessageRole.Tool, string> {
+  toolCallId: string; // 对应的 ToolCall.id
+  duration: number; // 执行耗时（ms）
+  error?: string; // 错误信息（存在时 ToolCallRender 显示失败状态）
+}
+```
+
+## 使用场景
+
+- **文本消息展示**：聊天界面渲染 AI 回复的 Markdown 文本
+- **工具调用过程展示**：展示 Function Call / MCP 调用的参数、状态和返回结果
+- **流式输出**：`streaming` 状态下 Markdown 自动补全未闭合语法，配合流式响应实时更新
+- **自动渲染**：通过 `MessageContainer` 对 `role: 'assistant'` 消息自动处理，无需手动引入
+- **自定义内容渲染**：通过默认插槽替换内置 Markdown 渲染器，保留工具调用渲染
+
+## 关联组件
+
+- [MessageRender](./message-render.md) — assistant 角色由其实例化
+- [ToolMessage](./tool-message.md) — 工具执行结果可通过 toolCall.toolMessage 内联
+- [ToolcallRender](./toolcall-render.md) — 工具调用列表渲染