@blueking/chat-x 0.0.5 → 0.0.7

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

@@ -0,0 +1,138 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+CiteContent 在输入区上方以紧凑条带展示被引用文本片段，单行截断并可选关闭按钮移除引用。 常与 ChatInput 的引用预览区配合，不执行 HTML 渲染。
+
+### 关联组件
+- **chat-input** — 输入区展示待发送引用内容
+
+---
+<!-- FULL DOC -->
+
+# CiteContent 引用内容
+
+> **层级**：原子组件 · **功能域**：辅助组件
+
+展示被引用文本片段的紧凑条带组件。固定高度 28px，左侧引用图标 + 单行截断文本 + 可选关闭图标，背景灰色（`#f5f7fa`）。
+
+常见于两处：
+
+- **`UserMessage`**：`property.extra.cite` 为字符串时，渲染在消息气泡上方
+- **`ChatInput`**：通过 `v-model:cite` 绑定，渲染在输入框顶部，关闭后清空引用
+
+## 组件结构
+
+```
+.ai-cite-content（flex，height: 28px，padding: 0 8px，gap: 4px，bg: #f5f7fa，border-radius: 4px，margin-bottom: 4px）
+├── CiteIcon（14×14px，color: #979ba5，始终显示）
+├── .ai-cite-content-text（flex: 1，单行截断，color: #979ba5，overflow: hidden，text-overflow: ellipsis）
+│     {{ content }}（Vue 文本插值，XSS 安全）
+└── CloseIcon（14×14px，color: #979ba5，v-if="onClose"，hover: #4d4f56）
+      @click → onClose(content)
+```
+
+## 基础用法
+
+```vue
+<template>
+  <CiteContent content="这是一段被引用的文本" />
+</template>
+
+<script setup lang="ts">
+  import { CiteContent } from '@blueking/chat-x';
+</script>
+```
+
+## 可关闭引用
+
+传入 `onClose` 函数后，右侧显示关闭图标；点击时将当前 `content` 作为参数回传给 `onClose`：
+
+```vue
+<template>
+  <CiteContent
+    v-if="showCite"
+    content="这是一段可关闭的引用文本"
+    :on-close="handleClose"
+  />
+</template>
+
+<script setup lang="ts">
+  import { CiteContent } from '@blueking/chat-x';
+
+  const handleClose = (content: string) => {
+    // content 即当前引用文本，可用于日志或状态清除
+    console.log('关闭引用:', content);
+  };
+</script>
+```
+
+## 长文本截断
+
+文本超出容器宽度时自动单行截断（`text-overflow: ellipsis`），始终保持 28px 高度不变形：
+
+## 与 ChatInput 配合
+
+`ChatInput` 通过 `v-model:cite` 内置了 `CiteContent`，当 `cite` 有值时自动渲染在输入框顶部（`input-header` slot 位置）；用户点击关闭时，内部调用 `citeModel.value = ''` 清空引用：
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    v-model:cite="citeText"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatInput } from '@blueking/chat-x';
+
+  const inputValue = ref('');
+  const citeText = ref('');
+
+  // 用户通过 AiSelection 划词后，将选中文本赋值给 citeText
+  // ChatInput 会自动在顶部显示 CiteContent，用户点击关闭时 citeText 自动清空
+  function onUserSelectText(selectedText: string) {
+    citeText.value = selectedText;
+  }
+</script>
+```
+
+## 与 UserMessage 配合
+
+`UserMessage` 在 `property.extra.cite` 为字符串时，自动在气泡上方渲染 `CiteContent`（不带关闭按钮）：
+
+```typescript
+const message = {
+  role: 'user',
+  content: '这段代码有什么性能问题？',
+  property: {
+    extra: {
+      // 字符串类型 → 渲染 CiteContent（气泡外上方）
+      cite: 'for (let i = 0; i < arr.length; i++) {\n  fetch(`/api/${arr[i]}`)\n}',
+    },
+  },
+};
+```
+
+## API
+
+### Props
+
+| 属性名  | 类型                        | 必填 | 说明                                                      |
+| ------- | --------------------------- | ---- | --------------------------------------------------------- |
+| content | `string`                    | ✓    | 引用的文本内容；使用 Vue 文本插值渲染，XSS 安全           |
+| onClose | `(content: string) => void` | —    | 关闭回调；传入后右侧显示关闭图标，点击时将 `content` 回传 |
+
+> **XSS 安全**：`content` 通过 `{{ content }}` 文本插值渲染，不会执行 HTML 标签或脚本。
+
+## 样式说明
+
+| 元素                     | 关键样式                                                                                            |
+| ------------------------ | --------------------------------------------------------------------------------------------------- |
+| `.ai-cite-content`       | `height: 28px`，`padding: 0 8px`，`background: #f5f7fa`，`margin-bottom: 4px`（为下方内容留出间距） |
+| `.ai-cite-content-text`  | `flex: 1`，`white-space: nowrap`，`overflow: hidden`，`text-overflow: ellipsis`，`color: #979ba5`   |
+| `CiteIcon` / `CloseIcon` | `14×14px`，`color: #979ba5`；CloseIcon hover 变为 `#4d4f56`                                         |
+
+## 关联组件
+
+- [ChatInput](../molecular/chat-input.md) — 引用区常见挂载位置

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

@@ -0,0 +1,199 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+CodeContent 接收 markdown-it 的 fence/code_block token，按行 highlight.js 高亮并带语言标签与复制。 必填 props 为 token 数组；mounted 事件用于滚动联动等。 由 MarkdownContent 在解析代码块时挂载，面向流式增量更新。
+
+### 关联组件
+- **markdown-content** — 解析 Markdown 后生成 fence token 并渲染本组件
+
+---
+<!-- FULL DOC -->
+
+# CodeContent 代码块渲染
+
+> **层级**：原子组件 · **功能域**：内容渲染
+
+代码块渲染原子组件，专为 **Markdown 流式输出**设计。接收 `markdown-it` token 数组，基于 `highlight.js`（github-dark 主题）实现逐行语法高亮，顶部固定深色头部展示语言名和复制按钮。
+
+## 组件结构
+
+```
+.code-content-wrapper（width: 100%，margin-bottom: 12px）
+├── .code-content-header（height: 40px，bg: #2f333d，border: 1px solid #1a1a1a）
+│     ├── .code-header-language（color: #999，显示 token.info 原始字符串）
+│     └── ToolBtn id="copy"（点击复制 codeRef.innerText）
+│
+└── .hljs-pre（bg: #282c34，padding: 8×16，overflow-x: auto）
+      └── <code class="hljs language-{raw-info}">
+            ├── v-for completedLines
+            │     <span class="code-line" v-html="line.html" /> + '\n'
+            │     （已完成行，经过 hljs.highlight 高亮）
+            └── v-if currentLineText
+                  <span class="code-line current-line" v-html="currentLineHtml" />
+                  （最后一行，也经过 highlightLine，用 .current-line 标识正在输入）
+```
+
+## 基础用法
+
+`token` 接收 `markdown-it` 解析生成的 token 数组，组件从中提取第一个 `fence` 或 `code_block` token 渲染：
+
+```vue
+<template>
+  <CodeContent
+    :token="codeTokens"
+    @mounted="handleMounted"
+  />
+</template>
+
+<script setup lang="ts">
+  import { CodeContent } from '@blueking/chat-x';
+  import type { Token } from 'markdown-it';
+
+  const codeTokens: Token[] = [
+    {
+      type: 'fence',
+      tag: 'code',
+      info: 'typescript',
+      content: 'const greeting = "Hello, World!";\nconsole.log(greeting);',
+    },
+  ];
+
+  const handleMounted = ({ el }: { el: HTMLElement | null }) => {
+    // el 是 <code> 元素的 DOM 引用（通过懒加载 getter 访问）
+    console.log('代码块已渲染:', el);
+  };
+</script>
+```
+
+**TypeScript**
+
+**Python**
+
+**SQL**
+
+## 流式渲染
+
+组件的核心设计场景。流式输入时，每次 `token[].content` 追加新内容，只更新最后一行，已完成的行通过**内容比较复用缓存**，无需重新高亮：
+
+```
+content 变化 → watch(immediate: true, deep: true) → processContent()
+  → split('\n')
+  → 除最后一行：与 completedLines 对比，内容未变则复用，否则重新 highlightLine
+  → 最后一行：highlightLine 并赋值给 currentLineHtml（v-html 渲染）
+```
+
+**注意**：当 content 以 `\n` 结尾时，`split('\n')` 末尾为 `''`，`currentLineText = ''`，`.current-line` 元素不渲染（`v-if="currentLineText"`）。
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { CodeContent } from '@blueking/chat-x';
+
+  const streamingTokens = ref([{ type: 'fence', tag: 'code', info: 'typescript', content: '' }]);
+
+  async function simulateStream() {
+    let content = '';
+    for (const char of fullCode) {
+      await new Promise(r => setTimeout(r, 20));
+      content += char;
+      // 每次只更新 content，token 数组引用可保持同一个对象（deep watch）
+      streamingTokens.value = [{ type: 'fence', tag: 'code', info: 'typescript', content }];
+    }
+  }
+</script>
+```
+
+## 语言识别
+
+### 内置别名映射
+
+组件在 `MarkdownLanguageMap` 中维护了 3 个常用别名，`info` 字段使用别名时自动映射：
+
+| `info` 值 | 映射后       | 说明 |
+| --------- | ------------ | ---- |
+| `js`      | `javascript` | —    |
+| `ts`      | `typescript` | —    |
+| `py`      | `python`     | —    |
+
+### 解析优先级
+
+```
+1. MarkdownLanguageMap[info] → 尝试别名映射
+2. hljs.getLanguage(mappedLang) → 检查 hljs 是否支持
+3. 提取文件扩展名（如 "index.ts" → "ts"）→ 再次查询 hljs
+4. 均不匹配 → resolveLanguage 返回 null → 对内容进行 HTML 转义（非高亮）
+```
+
+> **注意**：`code` 元素的 class 使用原始 `token.info`（`language-{info}`），不是解析后的语言名。即 `info: 'js'` → `class="language-js"`，但高亮时用 `javascript`。
+
+### 未知语言（HTML 转义）
+
+当语言无法识别时，内容经过 HTML 转义（`&lt;` `&gt;` `&amp;` `&quot;`）后直接渲染，不进行语法高亮：
+
+### 无语言标识
+
+`info` 为空字符串时，语言区域留空，内容同样走 HTML 转义路径：
+
+## 高亮缓存
+
+每行代码的高亮结果缓存在组件实例内部的 `Map<string, string>` 中（key 为 `"${lang}:${lineContent}"`），最大容量 500 条；超限后清除前 250 条（LRU 近似）：
+
+```typescript
+const lineHighlightCache = new Map<string, string>();
+const MAX_CACHE_SIZE = 500;
+
+// 超限时清理前半部分
+if (lineHighlightCache.size > MAX_CACHE_SIZE) {
+  const keys = Array.from(lineHighlightCache.keys()).slice(0, MAX_CACHE_SIZE / 2);
+  keys.forEach(k => lineHighlightCache.delete(k));
+}
+```
+
+## API
+
+### Props
+
+| 属性名 | 类型      | 必填 | 说明                                                                     |
+| ------ | --------- | ---- | ------------------------------------------------------------------------ |
+| token  | `Token[]` | ✓    | markdown-it token 数组；组件提取其中第一个 `fence` 或 `code_block` token |
+
+### Events
+
+| 事件名  | 参数类型                      | 触发时机                                                                          |
+| ------- | ----------------------------- | --------------------------------------------------------------------------------- |
+| mounted | `{ el: HTMLElement \| null }` | 每次 `token` 变化后 `nextTick` 完成时；`el` 为 `<code>` 元素引用（懒加载 getter） |
+
+> **`mounted` 频率**：由于 `watch` 设置了 `immediate: true` 和 `deep: true`，每次 `token` 内容变化（包括初始化）都会触发 `mounted` 事件。
+
+## Token 结构
+
+组件从 token 数组中提取第一个匹配的 token：
+
+```typescript
+// 组件接受的 token 格式（只使用这 3 个字段）
+interface CodeToken {
+  type: 'fence' | 'code_block'; // 触发提取的条件
+  info: string; // 语言标识（如 'typescript'），显示在头部
+  content: string; // 代码内容（换行符 '\n' 分隔多行）
+}
+```
+
+完整 Token 类型从 `markdown-it` 包引入：
+
+```typescript
+import type { Token } from 'markdown-it';
+```
+
+## 样式说明
+
+| 区域                    | 关键样式                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------ |
+| `.code-content-header`  | `height: 40px`，`background: #2f333d`，`border: 1px solid #1a1a1a`，圆角仅顶部 `6px` |
+| `.code-header-language` | `color: #999`，`font-size: 12px`，`margin-right: auto`（推复制按钮到右侧）           |
+| `.hljs-pre`             | `background: #282c34`，`padding: 8px 16px`，`overflow-x: auto`，圆角仅底部 `6px`     |
+| `code`                  | `color: #abb2bf`，`font-size: 13px`，`line-height: 1.5`，等宽字体栈                  |
+| `.code-line`            | `display: inline`（保持行内流式拼接）                                                |
+
+## 关联组件
+
+- [MarkdownContent](./markdown-content.md) — 解析并传入 code fence token

package/dist/mcp/generated/docs/common-error-content.md

@@ -0,0 +1,70 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+CommonErrorContent 以红色错误图标加文案展示失败态，布局为 flex 横排，文本为纯文本插值。 在 MarkdownContent、ReasoningMessage 等链路上当 status 为 error 时自动替换内容区。
+
+### 关联组件
+- **markdown-content** — Markdown 渲染错误态展示
+- **reasoning-message** — 推理消息错误态展示
+
+---
+<!-- FULL DOC -->
+
+# CommonErrorContent 通用错误内容
+
+> **层级**：原子组件 · **功能域**：辅助组件
+
+错误状态消息渲染原子组件。红色 `ErrorIcon`（14×14px，绝对定位）+ 文本区域，`display: flex` 水平排列。
+
+通常由上层组件在 `status === 'error'` 时自动渲染，无需手动使用。
+
+## 组件结构
+
+```
+.ai-error-content（position: relative，display: flex，align-items: center）
+├── ErrorIcon（position: absolute，top: 2px，left: 0，flex: 0 0 14px，14×14px，color: #ea3636）
+└── .ai-error-content-text（flex: 1，margin-left: 20px，font-size: 12px，line-height: 20px，color: #4d4f56）
+      └── {{ content }}（Vue 文本插值，XSS 安全；content 为 undefined 时渲染空文本）
+```
+
+## 基础用法
+
+```vue
+<template>
+  <CommonErrorContent content="请求失败，请稍后重试" />
+</template>
+
+<script setup lang="ts">
+  import { CommonErrorContent } from '@blueking/chat-x';
+</script>
+```
+
+## 典型错误场景
+
+## 不传 content
+
+`content` 为可选，缺省时只渲染 `ErrorIcon`：
+
+## 使用场景
+
+组件库内部有两处自动使用：
+
+| 使用方             | 触发条件             | 传入内容                                      |
+| ------------------ | -------------------- | --------------------------------------------- |
+| `MarkdownContent`  | `status === 'error'` | `content`（字符串）                           |
+| `ReasoningMessage` | `status === 'error'` | `content?.join('\n') \|\| ''`（数组转字符串） |
+
+即 `AssistantMessage` / `ReasoningMessage` 在错误状态时，内容区域会自动替换为此组件，无需手动引入。
+
+## API
+
+### Props
+
+| 属性名  | 类型     | 必填 | 说明                                                            |
+| ------- | -------- | ---- | --------------------------------------------------------------- |
+| content | `string` | —    | 错误提示文本；使用 Vue 文本插值渲染，XSS 安全；缺省时仅显示图标 |
+
+## 关联组件
+
+- [MarkdownContent](./markdown-content.md) — Markdown 错误态
+- [ReasoningMessage](../molecular/reasoning-message.md) — 推理错误态

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

@@ -0,0 +1,216 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+汇总 MessageRole、MessageStatus、MessageContentType、MessageToolsStatus、MessageState、Z-Index 与 CONST_MESSAGE_TOOLS 等导出常量。 用于构造消息、配置 MessageContainer 工具栏与输入态，以及层级与默认快捷指令。与类型 messages 配套使用。
+
+### 关联组件
+- **message-tools** — 默认工具 ID 与展示
+- **chat-input** — MessageState 与快捷指令
+- **message-container** — 工具栏与消息态
+
+---
+<!-- FULL DOC -->
+
+# 常量枚举
+
+> **分类**：type
+
+`@blueking/chat-x` 导出的常量和枚举类型。
+
+## 消息相关
+
+### MessageRole
+
+消息角色枚举：
+
+```typescript
+enum MessageRole {
+  User = 'user',
+  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',
+}
+```
+
+### MessageStatus
+
+消息状态枚举：
+
+```typescript
+enum MessageStatus {
+  Pending = 'pending',
+  Streaming = 'streaming',
+  Complete = 'complete',
+  Error = 'error',
+  Stop = 'stop',
+  Disabled = 'disabled',
+}
+```
+
+### MessageContentType
+
+消息内容类型枚举：
+
+```typescript
+enum MessageContentType {
+  Binary = 'binary',
+  Function = 'function',
+  KeyValue = 'key-value',
+  KnowledgeRag = 'knowledge-rag',
+  Other = 'other',
+  ReferenceDocument = 'reference-document',
+  Text = 'text',
+}
+```
+
+### MessageToolsStatus
+
+消息工具栏状态枚举：
+
+```typescript
+enum MessageToolsStatus {
+  Disabled = 'disabled', // 禁用状态，按钮显示但不可点击
+  Hidden = 'hidden', // 隐藏状态，工具栏完全隐藏
+}
+```
+
+## 输入状态
+
+### MessageState
+
+输入框消息状态：
+
+```typescript
+const MessageState = {
+  ACTIVE: 'active',
+  DISABLED: 'disabled',
+  LOADING: 'loading',
+} as const;
+```
+
+## Z-Index 常量
+
+```typescript
+// 全局 chat-x 组件 Z-Index
+const CHAT_Z_INDEX = 9999;
+
+// 编辑器组件 Z-Index
+const EDITOR_Z_INDEX = 10000;
+
+// 编辑器菜单 Z-Index
+const EDITOR_MENU_Z_INDEX = 10001;
+
+// 快捷指令菜单 Z-Index
+const SHORTCUT_MENU_Z_INDEX = 10002;
+
+// 划选弹窗 Z-Index
+const SELECTION_Z_INDEX = 10003;
+```
+
+## 默认工具按钮
+
+### CONST_MESSAGE_TOOLS
+
+消息工具按钮列表：
+
+```typescript
+const CONST_MESSAGE_TOOLS: IToolBtn[] = [
+  { id: 'copy', name: '复制', description: '复制' },
+  { id: 'cite', name: '引用', description: '引用' },
+  { id: 'rebuild', name: '重新生成', description: '重新生成' },
+  { id: 'share', name: '分享', description: '分享' },
+];
+```
+
+### CONST_USER_MESSAGE_TOOLS
+
+用户消息工具按钮列表：
+
+```typescript
+const CONST_USER_MESSAGE_TOOLS: IToolBtn[] = [
+  { id: 'copy', name: '复制', description: '复制' },
+  { id: 'cite', name: '引用', description: '引用' },
+  { id: 'edit', name: '编辑', description: '编辑' },
+  { id: 'delete', name: '删除', description: '删除' },
+];
+```
+
+### CONST_UPDATE_TOOLS
+
+更新工具按钮列表（点赞/不满意）：
+
+```typescript
+const CONST_UPDATE_TOOLS: IToolBtn[] = [
+  { id: 'like', name: '点赞', description: '点赞' },
+  { id: 'unlike', name: '不满意', description: '不满意' },
+  { id: 'delete', name: '删除', description: '删除' },
+];
+```
+
+## 默认快捷指令
+
+### DEFAULT_SHORTCUTS
+
+默认快捷指令列表：
+
+```typescript
+const DEFAULT_SHORTCUTS: Shortcut[] = [{ id: 'ask-whale', name: '问问小鲸' }];
+```
+
+## 使用示例
+
+```typescript
+import {
+  MessageRole,
+  MessageStatus,
+  MessageContentType,
+  MessageToolsStatus,
+  CHAT_Z_INDEX,
+  CONST_MESSAGE_TOOLS,
+  DEFAULT_SHORTCUTS,
+} from '@blueking/chat-x';
+
+// 创建消息
+const message = {
+  id: '1',
+  messageId: 1,
+  role: MessageRole.User,
+  content: '你好',
+  status: MessageStatus.Complete,
+};
+
+// 检查消息状态
+if (message.status === MessageStatus.Streaming) {
+  console.log('消息正在流式输出中...');
+}
+
+// 使用默认工具按钮
+console.log(
+  '可用工具:',
+  CONST_MESSAGE_TOOLS.map(t => t.name),
+);
+```
+
+## 关联组件
+
+- [MessageTools](../components/molecular/message-tools.md) — 消息工具栏
+- [ChatInput](../components/molecular/chat-input.md) — 输入与状态
+- [MessageContainer](../components/molecular/message-container.md) — 工具与消息展示