@blueking/chat-x 0.0.5 → 0.0.7

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

@@ -0,0 +1,233 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ReasoningMessage 展示 AI 思维链（Chain-of-Thought）推理过程，含可折叠标题与 Markdown 内容区；可传入 duration 并在结束后自动折叠。 content 为字符串数组（或兼容字符串）。由 MessageRender 在 reasoning 角色下使用，常出现在用户消息与正式回答之间。
+
+### 关联组件
+- **message-render** — 由 MessageRender 在 role 为 reasoning 时创建
+- **assistant-message** — 推理结束后通常紧跟 Assistant 的正式回复
+- **markdown-content** — 内容区通过 Markdown 渲染推理文本
+
+---
+<!-- FULL DOC -->
+
+# ReasoningMessage 推理消息
+
+> **层级**：分子组件 · **功能域**：消息展示
+
+AI 思维链（Chain-of-Thought）推理过程展示组件。由**可点击标题栏**和**内容区域**组成，内容区支持 Markdown 渲染。`duration` 传入后自动折叠一次，用户可随时点击标题展开/收起。
+
+## 组件结构
+
+```
+┌─────────────────────────────────────────────────┐
+│  .ai-reasoning-message-title（可点击，toggle 折叠）│
+│  ┌──────┐  标题文案（思考中/已思考完成/思考失败）  ▶ │
+│  │ 加载图标│                               折叠图标 │
+│  └──────┘                                        │
+└─────────────────────────────────────────────────┘
+▼ 展开时显示（v-show）
+┌─────────────────────────────────────────────────┐
+│  .ai-reasoning-message-content                  │
+│  <MarkdownContent> × content.length              │
+│  （Error 时改为 CommonErrorContent）              │
+│  .markdown-body { color: #979ba5 }（灰色文字）   │
+└─────────────────────────────────────────────────┘
+```
+
+## 基础用法
+
+```vue
+<template>
+  <ReasoningMessage
+    :content="content"
+    :status="status"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ReasoningMessage, MessageStatus } from '@blueking/chat-x';
+
+  const status = MessageStatus.Complete;
+  const content = ['让我分析一下这个问题...', '首先需要考虑以下几个方面...'];
+</script>
+```
+
+**渲染效果**
+
+## 状态与视觉效果
+
+| `status`                       | 标题文案           | 加载图标      | 标题 CSS 类   |
+| ------------------------------ | ------------------ | ------------- | ------------- |
+| `pending` / `streaming` / 其他 | 思考中             | `AiLoading` ✓ | `is-thinking` |
+| `complete` / `success`         | 已思考完成（耗时） | 无            | `is-complete` |
+| `error`                        | 思考失败           | 无            | `is-error`    |
+
+> **说明**：`streaming` 通过 `switch` 的 `default` 分支显示"思考中"，与 `pending` 效果相同。
+
+### 思考中（pending / streaming）
+
+### 完成状态（带耗时）
+
+`duration` 传入后：
+
+1. 标题显示"已思考完成 (耗时：x.xs)"
+2. **自动折叠一次**（watch 触发后 `stop()`，后续不再自动折叠）
+3. 用户点击标题可重新展开
+
+### 错误状态（error）
+
+`status: 'error'` 时，标题显示"思考失败"，内容区改为 `CommonErrorContent` 渲染（将 `content` 数组 join `\n` 后传入）：
+
+## 折叠控制
+
+### 自动折叠机制
+
+组件内部 watch `duration` prop（`{ immediate: true }`）：
+
+- 当 `duration` **首次变为真值**时，将 `collapsed` 设为 `true` 并停止 watcher
+- **一次性行为**：watcher 停止后，后续 `duration` 变化不再触发自动折叠
+
+```typescript
+// 组件内部逻辑（简化）
+const { stop } = watch(
+  () => props.duration,
+  async duration => {
+    if (duration) {
+      collapsed.value = true;
+      await nextTick();
+      stop?.(); // 停止 watcher，后续 duration 变化不再自动折叠
+    }
+  },
+  { immediate: true },
+);
+```
+
+### 手动控制折叠状态
+
+通过 `v-model:collapsed` 从外部读取或设置折叠状态：
+
+```vue
+<template>
+  <button @click="collapsed = !collapsed">
+    {{ collapsed ? '展开推理' : '收起推理' }}
+  </button>
+  <ReasoningMessage
+    v-model:collapsed="collapsed"
+    :content="content"
+    :status="status"
+    :duration="duration"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ReasoningMessage, MessageStatus } from '@blueking/chat-x';
+
+  const collapsed = ref(false);
+  const status = MessageStatus.Complete;
+  const duration = 2800;
+  const content = ['经过分析，结论如下...', '具体原因是...'];
+</script>
+```
+
+## 在 MessageContainer 中使用
+
+`MessageContainer` 会自动将 `role: 'reasoning'` 的消息渲染为 `ReasoningMessage`，无需手动引入：
+
+```vue
+<script setup lang="ts">
+  import { MessageRole, MessageStatus, type Message } from '@blueking/chat-x';
+
+  const messages = [
+    {
+      id: '1',
+      messageId: '1',
+      role: MessageRole.User,
+      content: '如何实现 TypeScript 中的深拷贝？',
+      status: MessageStatus.Complete,
+    },
+    {
+      id: '2',
+      messageId: '2',
+      role: MessageRole.Reasoning,
+      content: [
+        '用户问的是 TypeScript 深拷贝，需要考虑几种常见方案...',
+        'JSON.parse/stringify 有局限性（函数、循环引用等）...',
+        'structuredClone 是更现代的选择，但需要注意兼容性...',
+      ],
+      status: MessageStatus.Complete,
+      duration: 2800, // 毫秒，传入后自动折叠
+    },
+    {
+      id: '3',
+      messageId: '3',
+      role: MessageRole.Assistant,
+      content: 'TypeScript 中实现深拷贝有以下几种方式...',
+      status: MessageStatus.Complete,
+    },
+  ];
+</script>
+```
+
+## API
+
+### Props
+
+组件 Props 继承自 `Partial<ReasoningMessage>`：
+
+| 属性名    | 类型                 | 说明                                                                           |
+| --------- | -------------------- | ------------------------------------------------------------------------------ |
+| content   | `string \| string[]` | 推理内容；字符串数组时每项独立渲染为 `MarkdownContent`；字符串时自动包装为数组 |
+| status    | `MessageStatus`      | 消息状态，决定标题文案、加载图标和 CSS 类                                      |
+| duration  | `number`             | 推理耗时（毫秒）；传入后标题追加耗时信息，并**触发一次自动折叠**               |
+| id        | `number \| string`   | 消息 ID（接收但不使用）                                                        |
+| messageId | `number \| string`   | 消息唯一标识（接收但不使用）                                                   |
+
+### v-model
+
+| 属性名    | 类型      | 默认值  | 说明                                                       |
+| --------- | --------- | ------- | ---------------------------------------------------------- |
+| collapsed | `boolean` | `false` | 内容折叠状态；`duration` 首次传入时组件内部自动设为 `true` |
+
+### 状态说明
+
+| `status`           | 标题文案                             | 加载图标 | 标题背景        |
+| ------------------ | ------------------------------------ | -------- | --------------- |
+| `pending`          | 思考中                               | ✓        | `#f0f1f5`       |
+| `streaming` / 其他 | 思考中（default 分支）               | ✓        | `#f0f1f5`       |
+| `complete`         | 已思考完成（含 duration 则追加耗时） | ✗        | `#f0f1f5`       |
+| `success`          | 已思考完成（同 complete）            | ✗        | `#f0f1f5`       |
+| `error`            | 思考失败                             | ✗        | `#fff0f0`（红） |
+
+## 类型定义
+
+```typescript
+import { MessageRole, MessageStatus, type ReasoningMessage } from '@blueking/chat-x';
+
+// ReasoningMessage 继承自 BaseMessage<MessageRole.Reasoning, string[]>
+interface ReasoningMessage {
+  id: string | number;
+  messageId: string | number;
+  role: MessageRole.Reasoning; // 'reasoning'
+  status: MessageStatus;
+  content: string[]; // TS 类型为 string[]，组件内部实际兼容 string
+  duration?: number; // 推理耗时（毫秒）
+  name?: string;
+}
+
+enum MessageStatus {
+  Pending = 'pending',
+  Streaming = 'streaming',
+  Complete = 'complete',
+  Success = 'success',
+  Error = 'error',
+  Stop = 'stop',
+}
+```
+
+## 关联组件
+
+- [MessageRender](./message-render.md) — reasoning 角色由其实例化
+- [AssistantMessage](./assistant-message.md) — 推理后常接正式回答
+- [MarkdownContent](../atomic/markdown-content.md) — 推理正文 Markdown 渲染

package/dist/mcp/generated/docs/reference-content.md

@@ -0,0 +1,132 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ReferenceContent 以列表形式展示 AI 回复引用的参考文档：图标、标题、摘要与外链跳转。 由 ContentRender、ActivityMessage 等按消息类型分发时挂载。
+
+### 关联组件
+- **content-render** — ReferenceDocument 类型内容路由到本组件
+- **activity-message** — 知识库等活动场景内嵌引用列表
+
+---
+<!-- FULL DOC -->
+
+# ReferenceContent 引用文档内容
+
+> **层级**：原子组件 · **功能域**：辅助组件
+
+引用文档列表渲染原子组件，用于展示 AI 回复中引用的参考文档，每项包含文档图标、标题、预览与跳转操作。
+
+主要由 `ActivityMessage`（知识库问答场景）和 `ContentRender`（`reference_document` 类型内容）内部使用。
+
+## 组件结构
+
+```
+<template>（无根元素，Fragment 模式）
+  v-for item in links（过滤 name 为空 → 映射为 { title, url, originFileUrl }）
+    │
+    div.ai-reference-item（flex，height: 28px，padding: 0 12px，color: #3a84ff）
+      ├── DocLinkIcon（color="#D66F6B"，.ai-doc-link-icon，始终可见）
+      ├── span.ai-reference-item-title（flex: 1，ellipsis，font-size: 12px）
+      │     @click → url && gotoLink(url, event)
+      │     （XSS 安全：{{ item.title }} 文本插值）
+      ├── [v-if url && originFileUrl] PreviewIcon（.ai-common-icon）
+      │     v-tippy: "预览内容"
+      │     @click → gotoLink(url, event)
+      │     默认 display: none，hover 父容器后 display: flex
+      └── [v-if url && originFileUrl] TargetIcon（.ai-common-icon）
+            v-tippy: "跳转详情"
+            @click → gotoLink(originFileUrl, event)
+            默认 display: none，hover 父容器后 display: flex
+
+gotoLink(url, event):
+  event.stopPropagation() + event.preventDefault()
+  window.open(url, '_blank', 'noopener,noreferrer')
+```
+
+> **`v-for` key**：使用 `item.title`（即 `name`）作为 `:key`，同一组 `content` 中 `name` 须唯一，否则触发 Vue 重复 key 警告。
+
+## 图标可见性规则
+
+| 图标                      | 始终显示 | 显示条件（数据层）                | 显示条件（交互层） |
+| ------------------------- | -------- | --------------------------------- | ------------------ |
+| `DocLinkIcon`（红色书签） | ✓        | 无条件                            | 无条件             |
+| `PreviewIcon`（预览）     | —        | `url` 与 `originFileUrl` 均为真值 | 仅在 hover 时出现  |
+| `TargetIcon`（跳转）      | —        | `url` 与 `originFileUrl` 均为真值 | 仅在 hover 时出现  |
+
+即：只有 `url` 没有 `originFileUrl`（或反之），两个操作图标均不渲染。
+
+## 基础用法
+
+```vue
+<template>
+  <ReferenceContent :content="references" />
+</template>
+
+<script setup lang="ts">
+  import { ReferenceContent } from '@blueking/chat-x';
+  import type { ReferenceDocumentContent } from '@blueking/chat-x';
+
+  const references: ReferenceDocumentContent[] = [
+    { name: '蓝鲸 PaaS 平台文档', url: 'https://bk.tencent.com', originFile: '' },
+    { name: '组件库使用指南', url: 'https://bk.tencent.com/docs', originFile: '' },
+  ];
+</script>
+```
+
+## 含预览与跳转（url + originFile）
+
+同时提供 `url` 和 `originFile` 时，hover 后出现预览图标和跳转图标：
+
+## 混合场景：过滤与图标差异
+
+`name` 为空的项被过滤不渲染；`originFile` 为空时不显示 `PreviewIcon` / `TargetIcon`：
+
+```typescript
+const refs = [
+  { name: '有预览和跳转', url: 'https://…/preview', originFile: 'https://…/origin' }, // 两图标
+  { name: '仅有 url', url: 'https://…/only', originFile: '' }, // 无图标
+  { name: '', url: 'https://…/filtered', originFile: '' }, // 被过滤
+];
+// 实际渲染 2 条，第 3 条因 name='' 被过滤
+```
+
+## API
+
+### Props
+
+| 属性名  | 类型                         | 必填 | 说明                                          |
+| ------- | ---------------------------- | ---- | --------------------------------------------- |
+| content | `ReferenceDocumentContent[]` | ✓    | 引用文档列表；`name` 为空的项会被过滤，不渲染 |
+
+### 类型定义
+
+```typescript
+export type ReferenceDocumentContent = {
+  name: string; // 文档标题（用作列表展示文本，也作为 v-for :key）
+  url: string; // 预览链接：标题点击、PreviewIcon 点击时打开
+  originFile: string; // 原始文件链接：TargetIcon 点击时打开；为空则不渲染两个操作图标
+};
+```
+
+## 使用场景
+
+`ReferenceContent` 在两处被内部使用：
+
+**1. `ActivityMessage`（知识库问答）**
+
+```typescript
+// content 为 ReferenceDocumentContent[] 数组时直接传入
+<ReferenceContent :content="Array.isArray(content) ? content : content?.referenceDocument || []" />
+```
+
+**2. `ContentRender`（content 类型路由）**
+
+```typescript
+// type === MessageContentType.ReferenceDocument 且 content 为数组时
+h(ReferenceContent, { content: props.content as ReferenceDocumentContent[] });
+```
+
+## 关联组件
+
+- [ContentRender](../molecular/content-render.md) — 内容类型分发
+- [ActivityMessage](../molecular/activity-message.md) — 活动消息内引用

package/dist/mcp/generated/docs/scroll-btn.md

@@ -0,0 +1,155 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ScrollBtn 为底部浮动操作提供统一胶囊外壳（圆角、阴影），具体图标与行为由插槽与父级决定。 常由 MessageContainer 用于「返回底部」与「停止生成」等场景。
+
+### 关联组件
+- **message-container** — 消息列表底部固定区挂载滚动与停止按钮
+
+---
+<!-- FULL DOC -->
+
+# ScrollBtn 滚动按钮
+
+> **层级**：原子组件 · **功能域**：辅助组件
+
+聊天容器底部浮动操作按钮的外壳组件，提供统一的胶囊样式（圆角 26px、高 24px、阴影），内容完全由插槽定制。
+
+由 `MessageContainer` 内部管理"停止生成"和"返回底部"两个按钮的显示逻辑，通常不需要手动引入。
+
+## 组件结构
+
+```
+div.ai-scroll-btn（flex，gap: 4px，width: fit-content，min-width: 84px，height: 24px）
+  .is-loading / .is-disabled → cursor: not-allowed，opacity: 0.65
+  border: 1px solid #dcdee5，border-radius: 26px
+  box-shadow: 0 -2px 6px 0 #0000001a
+  hover → border: #c4c6cc，box-shadow 加深，cursor: pointer
+  │
+  ├── Loading（loading=true 时显示旋转加载图标）
+  ├── <slot name="icon">（loading=false 时显示，无默认内容）
+  │     子图标自动继承 .ai-common-icon 样式：14×14px，font-size: 14px
+  │
+  └── <slot name="title">（默认内容：{{ title }}，XSS 安全）
+        传入 title slot 时完全替换 title prop 的文本
+```
+
+> **`loading` / `disabled` prop**：`loading` 为 `true` 时显示旋转加载图标替代 icon slot，且点击无效；`disabled` 为 `true` 时点击同样无效。两者均添加 `not-allowed` 光标和 `0.65` 透明度。
+>
+> **`@click` 事件**：通过内部 `handleClick` 处理，`loading` 或 `disabled` 时不触发。
+
+## 基础用法：返回底部
+
+```vue
+<template>
+  <ScrollBtn
+    title="返回底部"
+    @click="toScrollBottom"
+  >
+    <template #icon>
+      <ArrowDownIcon />
+    </template>
+  </ScrollBtn>
+</template>
+
+<script setup lang="ts">
+  import { ScrollBtn } from '@blueking/chat-x';
+  import { ArrowDownIcon } from '@blueking/chat-x';
+
+  const toScrollBottom = () => {
+    /* 滚动逻辑 */
+  };
+</script>
+```
+
+## 停止生成
+
+```vue
+<template>
+  <ScrollBtn
+    title="停止生成"
+    @click="stopStreaming"
+  >
+    <template #icon>
+      <CloseCircleIcon />
+    </template>
+  </ScrollBtn>
+</template>
+```
+
+## 仅图标（不传 title）
+
+不传 `title` prop 时，`title` slot 渲染空文本，按钮收缩至 `min-width: 84px`：
+
+## 自定义 title slot
+
+传入 `#title` 插槽时，完全覆盖 `title` prop 的文本渲染：
+
+```vue
+<template>
+  <ScrollBtn
+    title="此文本被覆盖"
+    @click="handleClick"
+  >
+    <template #icon>
+      <ArrowDownIcon />
+    </template>
+    <template #title>
+      <span style="color: #3a84ff; font-weight: 600;">新消息 ↓</span>
+    </template>
+  </ScrollBtn>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名   | 类型      | 必填 | 说明                                                                      |
+| -------- | --------- | ---- | ------------------------------------------------------------------------- |
+| title    | `string`  | —    | 按钮文本；被 `#title` 插槽覆盖时无效；XSS 安全（文本插值）                |
+| loading  | `boolean` | —    | 加载状态；为 `true` 时显示旋转 Loading 图标替代 icon slot，点击不触发事件 |
+| disabled | `boolean` | —    | 禁用状态；为 `true` 时点击不触发事件                                      |
+
+### Events
+
+| 事件名 | 参数                  | 说明                                             |
+| ------ | --------------------- | ------------------------------------------------ |
+| click  | `(event: MouseEvent)` | 点击按钮时触发；`loading` 或 `disabled` 时不触发 |
+
+### Slots
+
+| 插槽名 | 说明                                                                      |
+| ------ | ------------------------------------------------------------------------- |
+| icon   | 图标区域，无默认内容；放置 `@blueking/chat-x` 图标时自动应用 14×14px 样式 |
+| title  | 文本区域，默认渲染 `title` prop；传入后**完全替换** prop 文本             |
+
+## 在 MessageContainer 中的使用
+
+`ScrollBtn` 由 `MessageContainer` 内置，根据状态自动控制显隐，无需手动管理：
+
+```html
+<!-- 停止生成：仅在流式输出时显示 -->
+<ScrollBtn
+  v-show="messageStatus === MessageStatus.Streaming"
+  :title="t('停止生成')"
+  @click="$emit('stopStreaming')"
+>
+  <template #icon><CloseCircleIcon /></template>
+</ScrollBtn>
+
+<!-- 返回底部：距底部超过 100px 且不在底部时显示 -->
+<ScrollBtn
+  v-show="!isScrollBottom && scrollBottomHeight > 100"
+  :title="t('返回底部')"
+  @click="toScrollBottom"
+>
+  <template #icon><ArrowDownIcon /></template>
+</ScrollBtn>
+```
+
+两个按钮都渲染在 `div.ai-message-fixed-bottom` 容器内，由父布局定位到消息列表底部中央。
+
+## 关联组件
+
+- [MessageContainer](../molecular/message-container.md) — 底部固定区集成

package/dist/mcp/generated/docs/selection-footer.md

@@ -0,0 +1,75 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+SelectionFooter 为消息多选（如分享）提供底部操作栏：全选、取消与确认，并反映选中数量与 loading。 由 ChatContainer 在对应模式下自动挂载，业务一般无需单独引用。
+
+### 关联组件
+- **chat-container** — 多选/分享模式由容器渲染底部栏
+- **message-container** — 与消息列表勾选状态联动
+
+---
+<!-- FULL DOC -->
+
+# SelectionFooter 选择操作栏
+
+> **层级**：原子组件 · **功能域**：辅助组件
+
+消息多选模式下的底部操作栏，提供全选、取消和确认操作。由 `ChatContainer` 在分享模式下自动渲染，通常不需要单独使用。
+
+## 基础用法
+
+```vue
+<template>
+  <SelectionFooter
+    :is-all-selected="isAllSelected"
+    :selected-count="selectedCount"
+    :loading="false"
+    @toggle-all="handleToggleAll"
+    @cancel="handleCancel"
+    @confirm="handleConfirm"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { SelectionFooter } from '@blueking/chat-x';
+
+  const isAllSelected = ref(false);
+  const selectedCount = ref(0);
+
+  const handleToggleAll = (checked: boolean) => {
+    isAllSelected.value = checked;
+  };
+  const handleCancel = () => {
+    console.log('取消');
+  };
+  const handleConfirm = () => {
+    console.log('确认');
+  };
+</script>
+```
+
+**渲染效果**
+
+## API
+
+### Props
+
+| 属性名        | 类型      | 必填 | 默认值  | 说明                          |
+| ------------- | --------- | ---- | ------- | ----------------------------- |
+| isAllSelected | `boolean` | ✓    | —       | 是否全选                      |
+| selectedCount | `number`  | ✓    | —       | 已选数量，为 0 时确认按钮禁用 |
+| loading       | `boolean` | —    | `false` | 确认按钮加载状态              |
+
+### Events
+
+| 事件名     | 参数                 | 说明         |
+| ---------- | -------------------- | ------------ |
+| toggle-all | `(checked: boolean)` | 切换全选状态 |
+| cancel     | —                    | 点击取消按钮 |
+| confirm    | —                    | 点击确认按钮 |
+
+## 关联组件
+
+- [ChatContainer](../molecular/chat-container.md) — 分享模式挂载
+- [MessageContainer](../molecular/message-container.md) — 多选与消息列表