@blueking/chat-x 0.0.5 → 0.0.6

package/dist/mcp/generated/docs/messages.md

@@ -0,0 +1,472 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+文档说明 Message 联合类型、BaseMessage、MessageRole、MessageStatus、User/Assistant/Tool/Activity/Reasoning 等具体形态及 MessageContentType。 业务构造 messages 数组供 ChatContainer/MessageContainer 渲染；Tool 消息经 useMessageGroup 注入 Assistant。可声明合并扩展 AIBluekingMessageMap。
+
+### 关联组件
+- **message-container** — 列表渲染与工具栏
+- **message-render** — 按 role 分发渲染
+- **chat-container** — 数据源与交互入口
+
+---
+<!-- FULL DOC -->
+
+# 消息类型
+
+> **分类**：type
+
+`@blueking/chat-x` 提供了完整的消息类型定义，用于构建 AI 对话消息。
+
+## 消息基础类型
+
+### Message
+
+所有消息类型的联合类型：
+
+```typescript
+type Message = MessageMap[MessageType];
+```
+
+### BaseMessage
+
+消息基础接口：
+
+```typescript
+interface BaseMessage<T extends MessageType, C = string> {
+  // 消息唯一 ID（客户端生成）
+  id: number | string;
+
+  // 消息 ID（服务端返回）
+  messageId: number | string;
+
+  // 消息角色
+  role: T;
+
+  // 消息内容
+  content: C;
+
+  // 消息状态
+  status: MessageStatus;
+
+  // 消息名称（可选）
+  name?: string;
+
+  // 消息属性（可选）
+  property?: {
+    extra?: {
+      // 引用内容
+      cite:
+        | string
+        | {
+            title: string;
+            data: { key: string; value: string }[];
+            type: 'structured';
+          };
+      // 快捷指令名称
+      command: string;
+      // 上下文信息
+      context: Record<string, any>[];
+      // 快捷指令配置
+      shortcut?: Shortcut;
+      // 暂停标记：为 true 时该消息所在消息组不显示 MessageTools 工具栏
+      pause?: boolean;
+    };
+  };
+}
+```
+
+## 消息角色
+
+```typescript
+enum MessageRole {
+  // 用户消息
+  User = 'user',
+
+  // AI 助手消息
+  Assistant = 'assistant',
+
+  // 系统消息
+  System = 'system',
+
+  // 开发者消息
+  Developer = 'developer',
+
+  // 引导消息
+  Guide = 'guide',
+
+  // 隐藏消息（不显示）
+  Hidden = 'hidden',
+  HiddenAssistant = 'hidden-assistant',
+  HiddenGuide = 'hidden-guide',
+  HiddenSystem = 'hidden-system',
+  HiddenUser = 'hidden-user',
+
+  // 信息消息
+  Info = 'info',
+
+  // 加载中消息
+  Loading = 'loading',
+
+  // 暂停消息
+  Pause = 'pause',
+
+  // 占位消息
+  Placeholder = 'placeholder',
+
+  // 推理过程消息
+  Reasoning = 'reasoning',
+
+  // 模板消息
+  TemplateAssistant = 'template-assistant',
+  TemplateGuide = 'template-guide',
+  TemplateHidden = 'template-hidden',
+  TemplateSystem = 'template-system',
+  TemplateUser = 'template-user',
+
+  // 工具调用消息
+  Tool = 'tool',
+
+  // 活动消息（如引用文档）
+  Activity = 'activity',
+}
+```
+
+## 消息状态
+
+```typescript
+enum MessageStatus {
+  // 等待中
+  Pending = 'pending',
+
+  // 流式输出中
+  Streaming = 'streaming',
+
+  // 已完成
+  Complete = 'complete',
+
+  // 错误
+  Error = 'error',
+
+  // 已停止
+  Stop = 'stop',
+
+  // 已禁用
+  Disabled = 'disabled',
+}
+```
+
+## 具体消息类型
+
+### UserMessage
+
+用户消息：
+
+```typescript
+type UserMessage = BaseMessage<MessageRole.User, InputContent[] | string>;
+
+// 示例
+const userMessage: UserMessage = {
+  id: '1',
+  messageId: 1,
+  role: MessageRole.User,
+  content: '你好',
+  status: MessageStatus.Complete,
+};
+```
+
+### AssistantMessage
+
+AI 助手消息：
+
+```typescript
+interface AssistantMessage extends BaseMessage<MessageRole.Assistant> {
+  // 工具调用列表
+  toolCalls?: ToolCall[];
+}
+
+// 工具调用
+type ToolCall = {
+  id: string;
+  type: MessageContentType.Function;
+  function: FunctionCall;
+};
+
+type FunctionCall = {
+  name: string;
+  arguments: string;
+  description?: string;
+  mcpName?: string;
+};
+
+// 示例
+const assistantMessage: AssistantMessage = {
+  id: '2',
+  messageId: 2,
+  role: MessageRole.Assistant,
+  content: '你好！有什么可以帮助你的？',
+  status: MessageStatus.Complete,
+  toolCalls: [
+    {
+      id: 'call_1',
+      type: MessageContentType.Function,
+      function: {
+        name: 'get_weather',
+        arguments: '{"city": "北京"}',
+      },
+    },
+  ],
+};
+```
+
+### ReasoningMessage
+
+推理过程消息：
+
+```typescript
+interface ReasoningMessage extends BaseMessage<MessageRole.Reasoning, string[]> {
+  // 推理耗时（毫秒）
+  duration?: number;
+}
+
+// 示例
+const reasoningMessage: ReasoningMessage = {
+  id: '3',
+  messageId: 3,
+  role: MessageRole.Reasoning,
+  content: ['让我分析一下这个问题...', '首先，需要考虑以下几点：', '1. 技术可行性'],
+  status: MessageStatus.Complete,
+  duration: 3500,
+};
+```
+
+### ToolMessage
+
+工具调用结果消息：
+
+```typescript
+interface ToolMessage extends BaseMessage<MessageRole.Tool, string> {
+  // 工具调用 ID（对应 AssistantMessage 中的 toolCalls[].id）
+  toolCallId: string;
+
+  // 执行耗时（毫秒）
+  duration: number;
+
+  // 错误信息
+  error?: string;
+}
+
+// 示例
+const toolMessage: ToolMessage = {
+  id: '4',
+  messageId: 4,
+  role: MessageRole.Tool,
+  content: '{"temperature": 25, "weather": "晴天"}',
+  status: MessageStatus.Complete,
+  toolCallId: 'call_1',
+  duration: 1200,
+};
+```
+
+### ActivityMessage
+
+活动消息（如引用文档、知识检索）：
+
+```typescript
+// 引用文档内容类型
+type ReferenceDocumentContent = {
+  name: string;
+  originFile: string;
+  url: string;
+};
+
+// 知识检索内容类型
+type KnowledgeRagContent = {
+  content: string;
+  referenceDocument: ReferenceDocumentContent[];
+};
+
+interface ActivityMessage extends BaseMessage<MessageRole.Activity, KnowledgeRagContent | ReferenceDocumentContent[]> {
+  activityType: MessageContentType.KnowledgeRag | MessageContentType.ReferenceDocument | string;
+}
+
+// 示例 1：引用文档
+const referenceMessage: ActivityMessage = {
+  id: '5',
+  messageId: 5,
+  role: MessageRole.Activity,
+  content: [
+    { name: '参考文档 1', url: 'https://example.com/1', originFile: 'https://example.com/origin/1' },
+    { name: '参考文档 2', url: 'https://example.com/2', originFile: 'https://example.com/origin/2' },
+  ],
+  status: MessageStatus.Complete,
+  activityType: 'reference',
+};
+
+// 示例 2：知识检索（knowledge_rag）
+const knowledgeRagMessage: ActivityMessage = {
+  id: '6',
+  messageId: 6,
+  role: MessageRole.Activity,
+  content: {
+    content: '开始召回知识\n重排召回结果中\n完成召回并分类\n',
+    referenceDocument: [
+      { name: '知识文档 1', url: 'https://example.com/doc1', originFile: 'https://example.com/origin/doc1' },
+      { name: '知识文档 2', url: 'https://example.com/doc2', originFile: 'https://example.com/origin/doc2' },
+    ],
+  },
+  status: MessageStatus.Complete,
+  activityType: 'knowledge_rag',
+};
+```
+
+**ActivityMessage 类型说明：**
+
+| activityType      | content 类型                 | 说明                                     |
+| ----------------- | ---------------------------- | ---------------------------------------- |
+| `'reference'`     | `ReferenceDocumentContent[]` | 引用文档列表                             |
+| `'knowledge_rag'` | `KnowledgeRagContent`        | 知识检索结果，包含检索过程内容和引用文档 |
+
+**ReferenceDocumentContent 字段说明：**
+
+| 字段         | 类型     | 说明             |
+| ------------ | -------- | ---------------- |
+| `name`       | `string` | 文档名称         |
+| `url`        | `string` | 文档预览链接     |
+| `originFile` | `string` | 文档原始文件链接 |
+
+### InfoMessage
+
+信息消息：
+
+```typescript
+type InfoMessage = BaseMessage<MessageRole.Info, string>;
+
+// 示例
+const infoMessage: InfoMessage = {
+  id: '6',
+  messageId: 6,
+  role: MessageRole.Info,
+  content: '会话已开始',
+  status: MessageStatus.Complete,
+};
+```
+
+### LoadingMessage
+
+加载中消息，用于在等待 AI 响应时显示加载状态：
+
+```typescript
+type LoadingMessage = BaseMessage<MessageRole.Loading, string>;
+
+// 示例
+const loadingMessage: LoadingMessage = {
+  id: 'loading',
+  messageId: '',
+  role: MessageRole.Loading,
+  content: '',
+  status: MessageStatus.Pending,
+};
+```
+
+## 消息内容类型
+
+```typescript
+enum MessageContentType {
+  // 二进制内容
+  Binary = 'binary',
+
+  // 函数调用
+  Function = 'function',
+
+  // 键值对
+  KeyValue = 'key-value',
+
+  // 知识检索
+  KnowledgeRag = 'knowledge-rag',
+
+  // 其他
+  Other = 'other',
+
+  // 引用文档
+  ReferenceDocument = 'reference-document',
+
+  // 文本
+  Text = 'text',
+}
+```
+
+## 类型扩展
+
+支持通过声明合并扩展消息类型：
+
+```typescript
+// 在项目中扩展
+declare global {
+  interface AIBluekingMessageMap {
+    'custom-role': CustomMessage;
+  }
+}
+
+interface CustomMessage extends BaseMessage<'custom-role'> {
+  customField: string;
+}
+```
+
+## 使用示例
+
+```vue
+<template>
+  <MessageContainer
+    :messages="messages"
+    :message-status="messageStatus"
+    :on-agent-action="handleAgentAction"
+    :on-user-action="handleUserAction"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { MessageContainer, MessageRole, MessageStatus, type Message } from '@blueking/chat-x';
+
+  const messageStatus = ref<MessageStatus>(MessageStatus.Complete);
+
+  const messages = ref<Message[]>([
+    {
+      id: '1',
+      messageId: 1,
+      role: MessageRole.User,
+      content: '你好',
+      status: MessageStatus.Complete,
+    },
+    {
+      id: '2',
+      messageId: 2,
+      role: MessageRole.Reasoning,
+      content: ['思考中...', '分析问题...'],
+      status: MessageStatus.Complete,
+      duration: 2000,
+    },
+    {
+      id: '3',
+      messageId: 3,
+      role: MessageRole.Assistant,
+      content: '你好！有什么可以帮助你的？',
+      status: MessageStatus.Complete,
+    },
+  ]);
+
+  const handleAgentAction = async tool => {
+    console.log('Agent action:', tool);
+  };
+
+  const handleUserAction = async tool => {
+    console.log('User action:', tool);
+  };
+</script>
+```
+
+## 关联组件
+
+- [MessageContainer](../components/molecular/message-container.md) — 消息列表
+- [MessageRender](../components/molecular/message-render.md) — 单条消息渲染
+- [ChatContainer](../components/molecular/chat-container.md) — 聊天容器

package/dist/mcp/generated/docs/overflow-tips.md

@@ -0,0 +1,209 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+v-overflow-tips 在元素水平溢出（scrollWidth > clientWidth）时于 mouseenter 懒创建 Tippy，展示完整文本或自定义 text/content。 结合 IntersectionObserver 仅在可见时绑定悬停；隐藏时销毁实例。指令值为 Partial<TippyProps> 与 disabled 等。 DescPanel、ExecutionSummary、ToolcallRender、AiSlashMenu 等用于标题或列表溢出提示。
+
+### 关联组件
+- **desc-panel** — 工具描述面板溢出
+- **execution-summary** — 执行摘要标签溢出
+- **toolcall-render** — 工具标题行溢出
+- **chat-input** — AiSlashMenu 资源项（侧栏子模块）
+
+---
+<!-- FULL DOC -->
+
+# OverflowTips 溢出提示指令
+
+> **分类**：directive
+
+当元素文本**水平溢出**（`scrollWidth > clientWidth`）时，鼠标悬停自动弹出 Tippy tooltip 显示完整内容；未溢出时不创建实例，零性能损耗。
+
+## 工作原理
+
+```
+元素挂载
+   │
+   ▼
+IntersectionObserver 监听可见性（threshold=0.1）
+   │
+   ├─ 可见 → 绑定 mouseenter / mouseleave
+   └─ 不可见 → 解绑 mouseenter / mouseleave
+                    │
+                    ▼ mouseenter 触发
+              scrollWidth > clientWidth ?
+               │               │
+              否               是
+               │               │
+            直接返回      创建 Tippy 实例
+                          [trigger: mouseenter]
+                          [delay: 300ms, 0ms]
+                               │
+                    ┌──────────┴──────────┐
+                  onShow              onHidden
+              再次校验溢出         destroy() 销毁实例
+              false → 取消          instance = undefined
+```
+
+## 基础用法
+
+文本未溢出时不会弹出 tooltip；只有超出容器宽度才触发。元素需自行设置省略号 CSS。
+
+```vue
+<template>
+  <div
+    v-overflow-tips
+    class="ellipsis"
+  >
+    这是一段很长的文本内容，会触发溢出省略效果并弹出 tooltip 提示完整内容
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { OverflowTips as vOverflowTips } from '@blueking/chat-x';
+</script>
+
+<style scoped>
+  .ellipsis {
+    width: 240px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+</style>
+```
+
+## 自定义提示内容
+
+通过 `text` 或 `content`（别名）指定 tooltip 显示内容，优先级：`text > content > el.innerText`。
+
+```vue
+<template>
+  <div
+    v-overflow-tips="{ text: '自定义 tooltip 内容：完整的蓝鲸智云 AI 小鲸组件使用说明' }"
+    class="ellipsis"
+  >
+    悬浮查看自定义 tooltip 内容（与元素 innerText 不同）
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { OverflowTips as vOverflowTips } from '@blueking/chat-x';
+</script>
+```
+
+## 控制 placement 和禁用
+
+`placement` 默认 `'auto'`（Tippy 自动选择最优方向）；`disabled: true` 完全跳过 tooltip 创建。
+
+```vue
+<template>
+  <div
+    v-overflow-tips="{ placement: 'bottom', disabled: isDisabled }"
+    class="ellipsis"
+  >
+    可以切换弹出方向或禁用 tooltip
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { OverflowTips as vOverflowTips } from '@blueking/chat-x';
+
+  const isDisabled = ref(false);
+</script>
+```
+
+## API
+
+### 指令值类型
+
+```typescript
+type OverflowTipsValue = Partial<TippyProps> & {
+  disabled?: boolean; // 禁用 tooltip
+  text?: string; // 自定义提示内容（优先级最高）
+  content?: string; // text 的别名
+};
+```
+
+指令值是 `Partial<TippyProps>` 的超集，所有 Tippy.js 配置均可透传，但覆盖 `onHidden` 会导致实例无法自动销毁。
+
+### 常用配置项
+
+| 属性        | 类型                         | 默认值          | 说明                                            |
+| ----------- | ---------------------------- | --------------- | ----------------------------------------------- |
+| `text`      | `string`                     | `el.innerText`  | 自定义提示内容，优先级最高                      |
+| `content`   | `string`                     | `el.innerText`  | `text` 的别名，`text` 存在时忽略                |
+| `placement` | `Placement`                  | `'auto'`        | tooltip 弹出方向，支持所有 Tippy placement 值   |
+| `disabled`  | `boolean`                    | `false`         | `true` 时跳过 tooltip 创建，mouseenter 直接返回 |
+| `delay`     | `number \| [number, number]` | `[300, 0]`      | 显示/隐藏延迟（ms）                             |
+| `theme`     | `string`                     | `'ai-chat-box'` | Tippy 主题，默认使用组件库内置主题              |
+
+### 其他 Tippy.js 配置
+
+可直接传入任何 `tippy.js` 的 `Props`，如 `arrow`、`maxWidth`、`offset` 等，会覆盖上述默认值（除内部的 `trigger`、`onShow`、`onHidden` 逻辑外）。
+
+> **注意**：不要覆盖 `onHidden`，否则 Tippy 实例无法在隐藏后自动销毁，导致内存泄漏。
+
+## 溢出检测规则
+
+指令通过 `scrollWidth > clientWidth` 判断**水平溢出**：
+
+- 仅检测水平方向，多行文本的垂直截断（`-webkit-line-clamp`）无法被检测到
+- `onShow` 会在 tooltip 即将显示时**再次校验**溢出状态，动态缩放容器后同样有效
+- 若两次校验均未溢出，tooltip 不会弹出
+
+## 生命周期细节
+
+| 时机                | 行为                                                                  |
+| ------------------- | --------------------------------------------------------------------- |
+| `mounted`           | 创建 `IntersectionObserver`（阈值 10%），注册 `unObserverFunc` 到元素 |
+| 元素进入视口        | 绑定 `mouseenter` / `mouseleave` 事件                                 |
+| 元素离开视口        | 解绑 `mouseenter` / `mouseleave`                                      |
+| `mouseenter` + 溢出 | 创建 Tippy 实例；`DelayMs+16ms` 后补偿首次不显示的 bug                |
+| `onHidden`          | 销毁实例（`destroy()`），`instance = undefined`                       |
+| `beforeUnmount`     | 解绑所有事件，调用 `unObserverFunc` 停止 Observer                     |
+
+> **无 `update` 钩子**：`binding.value` 在运行时变化（如 `disabled` 切换）不会更新已创建的 Tippy 实例，只影响下一次 `mouseenter` 时的行为。
+
+## 样式要求
+
+指令不会自动设置省略号 CSS，需在元素上手动添加：
+
+**单行截断**：
+
+```css
+.ellipsis {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+```
+
+**多行截断（`-webkit-line-clamp`）**：
+
+```css
+/* 注意：多行截断时 scrollWidth <= clientWidth，tooltip 不会触发 */
+.ellipsis-multiline {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+```
+
+> 多行截断通过 `-webkit-line-clamp` 实现，`scrollWidth` 不变，指令**无法检测**此类溢出，tooltip 不会弹出。
+
+## 注意事项
+
+1. **仅检测水平溢出**：`scrollWidth > clientWidth`，多行 `line-clamp` 溢出无效
+2. **无 `update` 钩子**：`disabled` 等状态变化仅在下次 `mouseenter` 生效
+3. **勿覆盖 `onHidden`**：会导致 Tippy 实例无法自动销毁
+4. **默认主题**：`'ai-chat-box'` 是组件库内置主题，替换为其他主题需引入对应 CSS
+5. **事件冒泡**：`mouseenter` 内调用了 `stopPropagation()`，父元素不会收到该事件
+
+## 关联组件
+
+- [DescPanel](../components/atomic/desc-panel.md) — 描述区溢出
+- [ExecutionSummary](../components/molecular/execution-summary.md) — 侧栏摘要标签
+- [ToolcallRender](../components/molecular/toolcall-render.md) — 工具调用标题
+- [ChatInput](../components/molecular/chat-input.md) — `@` 菜单项（内部 AiSlashMenu）