@blueking/chat-x 0.0.50 → 0.0.51-beta.2

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

@@ -0,0 +1,142 @@
+# CiteContent 引用内容
+
+> 能力域：内容渲染 ｜ 导入：`import { CiteContent } from '@blueking/chat-x'` ｜ 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/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) — 推理错误态

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

@@ -0,0 +1,233 @@
+# ContentRender 内容渲染器
+
+> 能力域：内容渲染 ｜ 导入：`import { ContentRender } from '@blueking/chat-x'` ｜ since 1.0.0
+
+按 MessageContentType 分发 Markdown、文本、引用、键值、图片等内容。 源码位置：src/components/chat-content/content-render/content-render.vue。
+
+**关联**：markdown-content（文本类 Markdown 正文的默认渲染实现）、reference-content（引用文档数组类型的列表渲染）、assistant-message（AI 回复中默认通过本组件渲染正文）
+
+---
+
+# ContentRender 内容渲染器
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/content-render/content-render.vue`
+- **能力域**：内容渲染
+- **能力说明**：按 MessageContentType 分发 Markdown、文本、引用、键值、图片等内容。
+
+> **能力域**：内容渲染
+
+消息内容渲染分发组件，根据 `content` 的 JavaScript 类型自动选择渲染方式：字符串 → `MarkdownContent`（Markdown 渲染），数组 → `ReferenceContent`（引用列表）。
+
+## 渲染管线
+
+```
+ContentRender
+├── typeof content === 'string'  →  MarkdownContent（Markdown 渲染）
+│   └── status === 'error'       →  CommonErrorContent（红色错误图标 + 文本）
+├── Array.isArray(content)       →  ReferenceContent（引用文档列表）
+└── 其他                         →  undefined（不渲染，可通过 slot 自定义）
+```
+
+> **注意**：渲染类型由 `content` 的 JavaScript 类型决定（字符串 vs 数组），`type` prop 仅当传入 `MessageContentType.Text` 时才强制走 `MarkdownContent`，通常不需要显式传递。
+
+## 基础用法（Markdown 文本）
+
+字符串内容自动渲染为 Markdown：
+
+```vue
+<template>
+  <ContentRender
+    :content="content"
+    :status="status"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ContentRender, MessageStatus } from '@blueking/chat-x';
+
+  const content = '这是一段 **Markdown** 内容，支持 `代码`、**加粗**、*斜体* 等语法。';
+  const status = MessageStatus.Complete;
+</script>
+```
+
+**渲染效果**
+
+## Markdown 语法支持
+
+`MarkdownContent` 内置了完整的 Markdown 解析能力，使用 `markdown-it` + 多个插件：
+
+### 常用语法（代码、列表、表格）
+
+### 扩展语法
+
+| 语法                  | 效果           | 插件                      |
+| --------------------- | -------------- | ------------------------- |
+| `++文字++`            | 下划线（新增） | markdown-it-ins           |
+| `==文字==`            | 高亮标注       | markdown-it-mark          |
+| `^上标^`              | 上标           | markdown-it-sup           |
+| `~下标~`              | 下标           | markdown-it-sub           |
+| `[^1]` / `[^1]: 内容` | 脚注           | markdown-it-footnote      |
+| `- [x] 任务`          | 任务列表       | markdown-it-task-checkbox |
+
+### LaTeX 数学公式
+
+行内公式 `$...$` 和块级公式 `$$...$$`，由 `katex` 渲染：
+
+```vue
+<ContentRender content="行内公式：$E = mc^2$" status="complete" />
+```
+
+### Mermaid 图表
+
+代码块语言标识为 `mermaid` 时，由 `MermaidContent` 专门渲染：
+
+## 消息状态
+
+`status` 只传递给 `MarkdownContent`，对 `ReferenceContent` 无效。
+
+| `status`    | 渲染行为                                                          |
+| ----------- | ----------------------------------------------------------------- |
+| `complete`  | 正常渲染完整 Markdown                                             |
+| `streaming` | 自动补全未闭合的 Markdown 语法（代码块、列表等），节流解析（5ms） |
+| `pending`   | 同 `complete`（按当前内容渲染）                                   |
+| `error`     | 渲染为 `CommonErrorContent`（红色错误图标 + `content` 文本）      |
+| `stop`      | 同 `complete`                                                     |
+
+**错误状态示例**
+
+## 引用文档列表
+
+`content` 传入 `ReferenceDocumentContent[]` 数组时，自动渲染为 `ReferenceContent`（引用文档列表）：
+
+```vue
+<template>
+  <ContentRender :content="referenceContent" />
+</template>
+
+<script setup lang="ts">
+  import { ContentRender, type ReferenceDocumentContent } from '@blueking/chat-x';
+
+  const referenceContent: ReferenceDocumentContent[] = [
+    {
+      name: 'Vue 3 官方文档',
+      url: 'https://vuejs.org',
+      originFile: 'vue3-guide.md', // 有 originFile 时显示预览和跳转图标
+    },
+    {
+      name: 'TypeScript 手册',
+      url: 'https://www.typescriptlang.org',
+      originFile: '', // 无 originFile 时不显示操作图标
+    },
+  ];
+</script>
+```
+
+**渲染效果**（悬停条目查看图标，有 `originFile` 的条目显示预览和跳转图标）
+
+### ReferenceContent 图标显示规则
+
+| 条件                           | 显示图标                                     |
+| ------------------------------ | -------------------------------------------- |
+| 始终                           | 文档图标（红色）                             |
+| `url` 和 `originFile` 均不为空 | 预览图标（悬停可见）                         |
+| `url` 和 `originFile` 均不为空 | 跳转图标（悬停可见，打开 `originFile` 链接） |
+
+无 `originFile` 时只显示文档图标（点击文档名跳转 `url`）：
+
+## 自定义渲染（默认插槽）
+
+默认插槽接收 `{ content }` 参数（原始 `content` prop 值），替换整个内容渲染：
+
+```vue
+<template>
+  <ContentRender
+    :content="content"
+    :status="status"
+  >
+    <template #default="{ content }">
+      <div class="custom-content">
+        <h3>自定义渲染</h3>
+        <pre>{{ JSON.stringify(content, null, 2) }}</pre>
+      </div>
+    </template>
+  </ContentRender>
+</template>
+
+<script setup lang="ts">
+  import { ContentRender } from '@blueking/chat-x';
+
+  const content = '自定义内容，由 slot 接管渲染。';
+  const status = 'complete';
+</script>
+```
+
+**渲染效果**
+
+## API
+
+### Props
+
+| 属性名  | 类型                                   | 必填 | 说明                                                                                      |
+| ------- | -------------------------------------- | ---- | ----------------------------------------------------------------------------------------- |
+| content | `string \| ReferenceDocumentContent[]` | ✅   | 内容数据，字符串走 Markdown 渲染，数组走引用文档列表渲染                                  |
+| status  | `MessageStatus`                        | -    | 消息状态，只影响 Markdown 渲染（`error` 时渲染错误样式，`streaming` 时补全语法）          |
+| type    | `ContentType`                          | -    | 内容类型提示，传入 `MessageContentType.Text` 可强制走 MarkdownContent；通常不需要显式传递 |
+
+### Slots
+
+| 插槽名     | 参数                                   | 说明                                                                          |
+| ---------- | -------------------------------------- | ----------------------------------------------------------------------------- |
+| codeHeader | `{ language: string; token: Token[] }` | 代码块头部自定义操作区域，透传给 MarkdownContent → CodeContent 的 header 插槽 |
+| default    | `{ content: ContentMap[T] }`           | 自定义渲染，接收原始 content prop 值，替换全部默认逻辑                        |
+
+## 流式渲染机制
+
+`streaming` 状态下，`MarkdownContent` 有以下优化：
+
+1. **语法自动补全**：`completeMarkdownSyntax` 在解析前补全未闭合的代码块、列表等，避免渲染异常
+2. **节流解析**：`parseMarkdownContent` 节流 5ms（leading + trailing），大幅降低流式输入时的解析开销
+3. **不完整状态保护**：当正在输入 LaTeX 命令（如 `$\fra...`）时保持之前的渲染结果，避免闪烁
+4. **CSS contain 性能隔离**：`.ai-markdown-content` 使用 `contain: layout style`，`.ai-markdown-body` 使用 `contain: content`，减少重排影响范围
+5. **自动滚动**：每个 token 挂载后触发 `toScrollBottom()`（节流 100ms），与 `MessageContainer` 配合实现流式自动滚动
+
+## 类型定义
+
+```typescript
+import { MessageContentType, MessageStatus } from '@blueking/chat-x';
+
+// 引用文档内容
+type ReferenceDocumentContent = {
+  name: string; // 显示名称（为空时该条目被过滤，不渲染）
+  url: string; // 文档访问地址（点击文档名跳转）
+  originFile: string; // 原始文件地址（非空时显示预览和跳转图标）
+};
+
+// 内容类型（ContentType = keyof ContentMap）
+enum MessageContentType {
+  Text = 'text', // 字符串，Markdown 渲染
+  ReferenceDocument = 'reference_document', // ReferenceDocumentContent[]，引用列表
+  Binary = 'binary',
+  Function = 'function',
+  KeyValue = 'key_value',
+  KnowledgeRag = 'knowledge_rag',
+  Other = 'other',
+}
+```
+
+> `MessageStatus` 完整取值见 [常量枚举](../../types/constants)；本组件主要关心 `error`（错误内容）与流式相关状态。
+
+## 使用场景
+
+- **AI 文本回复渲染**：`AssistantMessage` 内部用 `ContentRender` 渲染 AI 回复内容，`status` 配合流式响应
+- **知识库引用展示**：`ActivityMessage` 内部用 `ContentRender` 渲染引用文档列表
+- **代码展示**：Markdown 代码块由 `CodeContent` 自动高亮（Atom One Dark 主题，支持 180+ 语言）
+- **数学公式**：行内 `$...$` 和块级 `$$...$$`，由 KaTeX 渲染
+- **流程图**：Mermaid 代码块自动渲染为 SVG 图表
+- **自定义渲染**：通过 slot 接管渲染，实现表格、图表等自定义内容展示
+
+## 关联组件
+
+- [MarkdownContent](/components/rendering/markdown-content) — 字符串 Markdown 正文
+- [ReferenceContent](/components/rendering/reference-content) — 引用文档数组
+- [AssistantMessage](/components/message/assistant-message) — assistant 消息中默认使用