@blueking/chat-x 0.0.25 → 0.0.27

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

@@ -0,0 +1,388 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+说明通过 SCSS 变量（尺寸、颜色、z-index）与 CSS 类覆盖（chat-input、用户/助手消息、shortcut-btns、ai-markdown-body、tool-btn 等）自定义主题。 含渐变边框 mixin、ai-markdown-fade-in 与弹窗过渡。暗色示例通过根 class 切换。组件随包引入样式，业务侧按需覆写。
+
+### 关联组件
+- **chat-container** — 整体布局与侧栏
+- **chat-input** — 输入区与渐变边框
+- **message-container** — 消息区样式上下文
+
+---
+<!-- FULL DOC -->
+
+# 主题配置
+
+> **分类**：theme
+
+`@blueking/chat-x` 使用 SCSS 变量和 CSS 类来控制样式，支持通过覆盖变量或样式来自定义主题。
+
+## 样式引入
+
+组件库的样式会在引入组件时自动加载，无需单独引入：
+
+```typescript
+// 引入组件时会自动引入样式
+import { ChatInput, MessageContainer } from '@blueking/chat-x';
+```
+
+## SCSS 变量
+
+组件库使用以下 SCSS 变量，可以在项目中覆盖：
+
+### 尺寸变量
+
+```scss
+// 输入框尺寸
+$chat-input-min-width: 350px;
+$chat-input-max-width: 700px;
+```
+
+### 颜色变量
+
+```scss
+// 主题色
+$primary-color: #3a84ff;
+
+// 文字颜色
+$text-color-primary: #313238;
+$text-color-secondary: #4d4f56;
+$text-color-placeholder: #979ba5;
+
+// 背景色
+$bg-color-white: #fff;
+$bg-color-light: #f5f7fa;
+$bg-color-hover: #f0f1f5;
+
+// 边框色
+$border-color: #dcdee5;
+$border-color-hover: #c4c6cc;
+```
+
+### Z-Index 变量
+
+组件库使用分层的 z-index 管理：
+
+```scss
+// 基础 z-index
+$chat-z-index: 9999;
+
+// 编辑器 z-index
+$editor-z-index: $chat-z-index + 1;
+
+// 编辑器菜单 z-index
+$editor-menu-z-index: $editor-z-index + 1;
+
+// 快捷指令菜单 z-index
+$shortcut-menu-z-index: $editor-menu-z-index + 1;
+
+// 划选弹窗 z-index
+$selection-z-index: $shortcut-menu-z-index + 1;
+```
+
+## CSS 类覆盖
+
+### 输入框样式
+
+```scss
+// 覆盖输入框容器样式
+.chat-input-container {
+  .chat-input {
+    min-height: 120px; // 自定义最小高度
+    max-height: 250px; // 自定义最大高度
+    background: #fafafa; // 自定义背景色
+
+    // 覆盖边框渐变
+    &::before {
+      background: linear-gradient(180deg, #ff6b6b, #ff8e53);
+    }
+  }
+}
+```
+
+### 消息样式
+
+```scss
+// 用户消息样式
+.ai-user-message {
+  &-content {
+    background-color: #d4edda; // 自定义背景色
+    border-radius: 8px;
+  }
+}
+
+// AI 消息样式
+.assistant-message {
+  &-content {
+    background-color: #f8f9fa;
+    border-left: 3px solid #3a84ff;
+    padding-left: 12px;
+  }
+}
+```
+
+### 快捷指令按钮样式
+
+```scss
+// 快捷指令按钮
+.shortcut-btns {
+  &-item {
+    background: linear-gradient(135deg, #667eea, #764ba2);
+    color: #fff;
+
+    &:hover {
+      transform: translateY(-2px);
+      box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
+    }
+
+    // 移除默认渐变边框
+    &::before {
+      display: none;
+    }
+  }
+}
+```
+
+### 消息工具栏样式
+
+```scss
+// 工具按钮
+.tool-btn {
+  width: 24px;
+  height: 24px;
+  font-size: 16px;
+
+  &:hover {
+    background-color: #e1ecff;
+    color: #3a84ff;
+  }
+}
+```
+
+### Markdown 内容样式
+
+```scss
+// Markdown 内容
+.ai-markdown-content {
+  .ai-markdown-body {
+    font-size: 14px;
+    line-height: 1.6;
+
+    // 代码块样式
+    pre code.hljs {
+      background-color: #1e1e1e;
+      border-radius: 8px;
+    }
+
+    // 表格样式
+    table {
+      border-collapse: collapse;
+
+      th,
+      td {
+        border: 1px solid #dcdee5;
+        padding: 8px 12px;
+      }
+
+      th {
+        background-color: #f5f7fa;
+      }
+    }
+  }
+}
+```
+
+## 主题切换示例
+
+### 暗色主题
+
+```scss
+// 暗色主题变量
+.dark-theme {
+  // 输入框
+  .chat-input-container .chat-input {
+    background: #2d2d2d;
+
+    &::before {
+      background: linear-gradient(180deg, #4a90d9, #357abd);
+    }
+  }
+
+  // 用户消息
+  .ai-user-message-content {
+    background-color: #3d5a80;
+    color: #fff;
+  }
+
+  // AI 消息
+  .assistant-message {
+    color: #e0e0e0;
+  }
+
+  // Markdown 内容
+  .ai-markdown-content .ai-markdown-body {
+    color: #e0e0e0;
+
+    h1,
+    h2,
+    h3,
+    h4,
+    h5,
+    h6 {
+      color: #fff;
+    }
+
+    a {
+      color: #6cb2eb;
+    }
+
+    code {
+      background-color: #3d3d3d;
+      color: #e0e0e0;
+    }
+  }
+
+  // 快捷指令
+  .shortcut-btns-item {
+    background: #3d3d3d;
+    color: #e0e0e0;
+
+    &::before {
+      background: linear-gradient(105deg, #4a90d940, #9b59b640);
+    }
+  }
+
+  // 工具按钮
+  .tool-btn {
+    color: #9e9e9e;
+
+    &:hover {
+      background-color: #424242;
+      color: #fff;
+    }
+  }
+}
+```
+
+### 使用暗色主题
+
+```vue
+<template>
+  <div :class="{ 'dark-theme': isDark }">
+    <ChatInput v-model="input" />
+    <MessageContainer :messages="messages" />
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatInput, MessageContainer } from '@blueking/chat-x';
+
+  const isDark = ref(false);
+  const input = ref('');
+  const messages = ref([]);
+</script>
+```
+
+## 渐变边框
+
+组件库使用 CSS mask 实现渐变边框效果：
+
+```scss
+// 渐变边框 mixin
+@mixin linear-gradient-border($angle: 105deg, $start-color: #235dfa40, $end-color: #bc81ef40) {
+  content: '';
+  position: absolute;
+  inset: 0;
+  padding: 1px;
+  background: linear-gradient($angle, $start-color, $end-color);
+  mask:
+    linear-gradient(#fff 0 0) content-box,
+    linear-gradient(#fff 0 0);
+  mask-composite: xor;
+  mask-composite: exclude;
+  border-radius: inherit;
+  pointer-events: none;
+}
+```
+
+使用示例：
+
+```scss
+.custom-card {
+  position: relative;
+  border-radius: 8px;
+
+  &::before {
+    @include linear-gradient-border(180deg, #6cbaff, #3a84ff);
+  }
+}
+```
+
+## 动画效果
+
+### 淡入动画
+
+```scss
+// 全局淡入动画
+@keyframes ai-markdown-fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+.ai-blueking-markdown-fade-in {
+  animation: ai-markdown-fade-in 0.2s ease-out forwards;
+}
+```
+
+### 弹窗过渡
+
+```scss
+// 选择弹窗过渡
+.ai-fade-enter-active,
+.ai-fade-leave-active {
+  transition:
+    opacity 0.2s ease,
+    transform 0.2s ease;
+}
+
+.ai-fade-enter-from,
+.ai-fade-leave-to {
+  opacity: 0;
+  transform: translateY(4px);
+}
+```
+
+## 响应式设计
+
+```scss
+// 移动端适配
+@media (max-width: 768px) {
+  .chat-input-container .chat-input {
+    min-width: 100%;
+    max-width: 100%;
+  }
+
+  .shortcut-btns {
+    min-width: 100%;
+    max-width: 100%;
+  }
+}
+```
+
+## 注意事项
+
+1. **样式优先级**：覆盖样式时可能需要使用更高优先级的选择器
+2. **变量位置**：SCSS 变量需要在组件样式之前定义
+3. **构建配置**：确保项目配置支持 SCSS 处理
+4. **组件隔离**：使用 scoped 样式时，深度选择器 `::v-deep` 或 `:deep()` 可能需要
+
+## 关联组件
+
+- [ChatContainer](../components/molecular/chat-container.md) — 布局与主题根节点
+- [ChatInput](../components/molecular/chat-input.md) — 输入区变量与类名
+- [MessageContainer](../components/molecular/message-container.md) — 消息列表区域

package/dist/mcp/generated/docs/use-custom-tab.md

@@ -111,7 +111,8 @@ tabManager?.removeCustomTab('node-detail-123');
 interface CustomTab<T = Record<string, unknown>> {
   label: string;
   name: string;
-  data?: T;
+  /** 可与 `component` / `props` 并列；用于侧栏「在对话中定位」与主消息 `message.uid` 对齐 */
+  data?: T & { messageUid?: string };
 }
 ```
 

package/dist/mcp/generated/docs/use-message-group.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-useMessageGroup 接收 keyword、messages、selectedUserMessages，通过 watchEffect 产出 messageGroups（User/Assistant/Tool 合并、末尾 Loading 注入、pause 与分享勾选等）。 executionGroups 供侧边执行摘要过滤，并暴露 isShareMode、全选与 onConfirmShare。 ChatContainer 组装后传给 MessageContainer；ExecutionSummary 消费 executionGroups。
+useMessageGroup 接收 keyword、messages、selectedUserMessages，通过 watchEffect 产出 messageGroups（User/Assistant/Tool 合并、末尾 Loading 注入且占位 id 为 LOADING_MESSAGE_ID、pause 与分享勾选等）。 executionGroups 供侧边执行摘要过滤，并暴露 isShareMode、全选与 onConfirmShare。 ChatContainer 组装后传给 MessageContainer；ExecutionSummary 消费 executionGroups。
 
 ### 关联组件
 - **chat-container** — 调用并传入 MessageContainer
@@ -39,6 +39,8 @@ function useMessageGroup(options: {
 
 `watchEffect` 遍历 `messages` 数组，按以下规则分组：
 
+**消息 `uid`：** 若某条消息缺少 `uid`，分组前会自动为其生成并写入 `uid`（与 `MessageGroup.uid` 及 DOM 定位约定配合）。
+
 ```
 messages 原始数组（按顺序处理）
          │
@@ -58,18 +60,27 @@ role=user  role=tool     其他 role
 ⑤ 末尾为 user 消息 → 追加 Loading 消息组
 ```
 
+注入的占位 Loading 消息使用固定 id：`LOADING_MESSAGE_ID`（`'__loading__'`，定义于 `common/constants`）。`ChatContainer` 据此判断是否在「请求中」阶段，并向 `ChatInput` / `MessageContainer` 下传 `MessageStatus.Fetching`，与流式中的停止、防重复发送行为对齐。
+
 ### Tool 消息处理
 
 `role: 'tool'` 消息不会独立渲染，而是通过 `toolCallId` 注入到对应 AssistantMessage 的 `toolCall.toolMessage` 字段：
 
 ```typescript
-// 查找对应的 Assistant 消息
-const toolMessage = messages.find(m => m.role === 'assistant' && m.toolCalls?.some(t => t.id === message.toolCallId));
-// 注入到 toolCall
-const toolCall = toolMessage.toolCalls.find(t => t.id === message.toolCallId);
-toolCall.toolMessage = message;
+const toolMessage = messages.find(
+  m => m.role === 'assistant' && m.toolCalls?.some(t => t.id === message.toolCallId),
+);
+if (toolMessage) {
+  const toolCall = toolMessage.toolCalls?.find(t => t.id === message.toolCallId);
+  if (toolCall) {
+    toolCall.toolMessage = message;
+  }
+  // 同步 assistant 状态（错误等）
+}
 ```
 
+若找不到对应 `toolCall`（例如数据不一致），**跳过注入**，避免非空断言导致的运行时异常。
+
 ### pause 字段
 
 每个 Assistant 消息组计算 `pause` 属性：
@@ -157,7 +168,7 @@ const { messageGroups, executionGroups, isShareMode, isAllSelected, onToggleShar
 import { type MessageGroup } from '@blueking/chat-x';
 
 interface MessageGroup {
-  uuid: string;
+  uid: string;
   type: MessageRole;
   messages: Message[];
   checked: boolean;