@blueking/chat-x 0.0.51 → 0.0.52-dev.2

package/skills/blueking-chat-x/references/components/cite-content.md

@@ -0,0 +1,142 @@
+# CiteContent 引用内容
+
+> 能力域：内容渲染 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+渲染输入或消息中的引用片段。 源码位置：src/components/chat-content/cite-content/cite-content.vue。
+
+**关联**：chat-input（输入区展示待发送引用内容）
+
+---
+
+# CiteContent 引用内容
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/cite-content/cite-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：渲染输入或消息中的引用片段。
+
+> **能力域**：内容渲染
+
+展示被引用文本片段的紧凑条带组件。固定高度 28px，左侧引用图标 + 单行截断文本 + 可选关闭图标，背景灰色（`#f5f7fa`），hover 背景为 `#eaebf0`。
+
+常见于两处：
+
+- **`UserMessage`**：`property.extra.cite` 为字符串时，渲染在消息气泡上方
+- **`ChatInput`**：通过 `v-model:cite` 绑定，渲染在输入框顶部，关闭后清空引用
+
+## 组件结构
+
+```
+.ai-cite-content（flex，height: 28px，padding: 0 8px，gap: 4px，bg: #f5f7fa，hover: #eaebf0，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`，hover `#eaebf0`，`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](/components/input/chat-input) — 引用区常见挂载位置

package/skills/blueking-chat-x/references/components/code-content.md

@@ -0,0 +1,211 @@
+# CodeContent 代码块
+
+> 能力域：内容渲染 ｜ 导入：`import { CodeContent } from '@blueking/chat-x'` ｜ since 1.0.0
+
+渲染 Markdown 代码块，支持高亮、复制和 header 插槽。 源码位置：src/components/markdown-token/code-content/code-content.vue。
+
+**关联**：markdown-content（解析 Markdown 后生成 fence token 并渲染本组件）
+
+---
+
+# CodeContent 代码块渲染
+## 源码事实
+
+- **源码位置**：`src/components/markdown-token/code-content/code-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：渲染 Markdown 代码块，支持高亮、复制和 header 插槽。
+
+> **能力域**：内容渲染
+
+代码块渲染基础组件，专为 **Markdown 流式输出**设计。接收 `markdown-it` token 数组，基于 `highlight.js`（github-dark 主题）实现逐行语法高亮，顶部固定深色头部展示语言名和复制按钮。
+
+## 组件结构
+
+根类名为 **`.ai-code-content-wrapper`**：外层宽度、下边距以及 **`.code-content-header`**（深色顶栏）在任意父级下均生效。**代码区** `.hljs-pre`、行内高亮等样式选择器为 **`.ai-message-container .ai-code-content-wrapper`**，仅在消息列表（`MessageContainer` 根上的 `ai-message-container`）内与对话区一致。Wiki 与业务中若要完整还原代码区外观，请将 `CodeContent` 包在带 `ai-message-container` 类名的父节点内。
+
+```
+.ai-code-content-wrapper
+├── .code-content-header（深色顶栏；不依赖 .ai-message-container）
+│     ├── .code-header-language（token.info）
+│     ├── slot#header（{ language, token }）
+│     └── ToolBtn id="copy"
+│
+└── .hljs-pre（完整 padding / 背景 / code 字体：需父级为 .ai-message-container .ai-code-content-wrapper）
+      └── <code class="hljs language-{raw-info}">
+            ├── v-for completedLines → <span class="code-line" />
+            └── v-if currentLineText → <span class="code-line current-line" />
+```
+
+## 基础用法
+
+`token` 接收 `markdown-it` 解析生成的 token 数组，组件从中提取第一个 `fence` 或 `code_block` token 渲染：
+
+```vue
+<template>
+  <!-- 代码区 .hljs-pre 的完整样式依赖父级 .ai-message-container（与对话消息区一致）；顶栏单独也可用 -->
+  <div class="ai-message-container">
+    <CodeContent
+      :token="codeTokens"
+      @mounted="handleMounted"
+    />
+  </div>
+</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） |
+
+### Slots
+
+| 插槽名 | 参数                                   | 说明                                                                                       |
+| ------ | -------------------------------------- | ------------------------------------------------------------------------------------------ |
+| header | `{ language: string; token: Token[] }` | 代码块头部自定义内容区域，渲染在语言标签和复制按钮之间，可用于添加"插入"、"应用"等操作按钮 |
+
+> **`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](/components/rendering/markdown-content) — 解析并传入 code fence token

package/skills/blueking-chat-x/references/components/collapsible-content.md

@@ -0,0 +1,76 @@
+# CollapsibleContent 折叠内容
+
+> 能力域：内容渲染 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 0.0.51
+
+CollapsibleContent 用 ResizeObserver 持续测量插槽真实高度，超过 maxHeight（默认 200px）才折叠并显示切换按钮； 折叠通过外层 max-height + overflow hidden 实现，展开态可由 v-model:expanded 受控，便于「全部展开」这类批量操作。 源码位置：src/components/chat-content/collapsible-content/collapsible-content.vue。
+
+**关联**：user-message（用户消息正文超过 200px 时折叠）、activity-layout（活动消息的另一种折叠布局）
+
+---
+
+# CollapsibleContent 折叠内容
+
+> **能力域**：内容渲染
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/collapsible-content/collapsible-content.vue`
+- **能力说明**：默认插槽内容高度超过 `maxHeight` 时折叠，并在下方渲染「显示更多 / 收起」；未超出时**不渲染**切换按钮。
+- **切换按钮配色**：默认 `$color-text-secondary`（#979ba5），hover 转 `$color-text`（#4d4f56），箭头图标随展开态旋转。
+
+## 实现要点
+
+- **高度测量与折叠分离**：折叠由外层 `max-height` + `overflow: hidden` 实现，真实高度始终从内层测量容器读取，因此折叠状态不会污染测量结果。
+- **持续跟踪高度**：内容可能因为图片加载、流式追加或窗口缩放而变高，用 `ResizeObserver` 持续观测而非只测一次；`ResizeObserver` 不可用时不折叠（降级为完整展示）。
+- **展开态可受控**：`v-model:expanded` 允许外部驱动，便于实现「全部展开」；不绑定时组件内部自持。
+
+## 用法
+
+::: info 内部组件
+本组件不在包入口导出，由消息组件内部使用。
+:::
+
+```vue
+<template>
+  <CollapsibleContent :max-height="200">
+    <TextContent :content="content" />
+  </CollapsibleContent>
+
+  <!-- 外部受控展开态 -->
+  <CollapsibleContent v-model:expanded="allExpanded" :max-height="120">
+    <MarkdownContent :content="content" />
+  </CollapsibleContent>
+</template>
+```
+
+**渲染效果**（阈值 120px，可用按钮切换展开态）
+
+## API
+
+### Props
+
+| 属性名    | 类型     | 默认值 | 必填 | 说明                                           |
+| --------- | -------- | ------ | ---- | ---------------------------------------------- |
+| maxHeight | `number` | `200`  | -    | 折叠态下内容区最大高度（px），超出才出现按钮   |
+| expanded  | `boolean` | `false` | -   | 展开态，支持 `v-model:expanded`                |
+
+### Emits
+
+| 事件名          | 参数                | 触发时机           |
+| --------------- | ------------------- | ------------------ |
+| update:expanded | `(value: boolean)`  | 点击切换按钮       |
+
+### Slots
+
+| 插槽名  | 说明             |
+| ------- | ---------------- |
+| default | 被折叠的内容     |
+
+## 使用方
+
+[UserMessage](/components/message/user-message) 用它把用户消息正文限制在 `CONST_USER_MESSAGE_MAX_HEIGHT`（200px）以内。
+
+## 关联组件
+
+- [UserMessage](/components/message/user-message) — 用户消息正文折叠
+- [ActivityLayout](/components/helper/activity-layout) — 活动消息的折叠布局

package/skills/blueking-chat-x/references/components/common-error-content.md

@@ -0,0 +1,73 @@
+# CommonErrorContent 错误内容
+
+> 能力域：内容渲染 ｜ 导入：`import { commonErrorContent } from '@blueking/chat-x'` ｜ since 1.0.0
+
+展示统一错误提示内容。 源码位置：src/components/chat-content/common-error-content/common-error-content.vue。
+
+**关联**：markdown-content（Markdown 渲染错误态展示）、reasoning-message（推理消息错误态展示）
+
+---
+
+# CommonErrorContent 通用错误内容
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/common-error-content/common-error-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：展示统一错误提示内容。
+
+> **能力域**：内容渲染
+
+错误状态消息渲染基础组件。红色 `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](/components/rendering/markdown-content) — Markdown 错误态
+- [ReasoningMessage](/components/message/reasoning-message) — 推理错误态