@blueking/chat-x 0.0.5 → 0.0.7

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

@@ -0,0 +1,196 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+LatexContent 使用 KaTeX 渲染 math_block / math_inline 等 token，支持行内块级混排与流式防抖。 必填 props 为 token 数组；失败时静默降级展示原始 LaTeX 文本。 由 MarkdownContent 在数学插件解析后自动调用。
+
+### 关联组件
+- **markdown-content** — 插件解析 $...$ / $$...$$ 后生成数学 token 并挂载本组件
+
+---
+<!-- FULL DOC -->
+
+# LatexContent LaTeX 公式渲染
+
+> **层级**：原子组件 · **功能域**：内容渲染
+
+Markdown Token 层的 LaTeX 公式渲染原子组件，基于 **KaTeX** 实现。被 `MarkdownContent` 在解析到数学公式 token 时自动调用，通常无需手动引入。
+
+核心能力：**流式防抖渲染**（throttle 100ms）、**语法自动补全**（`completeLatexContent`）、**渐进式降级重试**（最多 5 次）、**错误静默**（错误文本白色不可见）。
+
+## 组件结构与 Token 渲染路径
+
+```
+props.token（Token[]）
+│
+├─ token.type === 'math_block'（单块且 token.length ≤ 1）
+│    wrapperTag = 'div'，wrapperClass = 'block-latex-content'
+│    └─ <div class="block-latex-wrapper">
+│          └─ renderLatexToken(token) → <span class="block-katex">KaTeX HTML</span>
+│
+├─ token.type === 'math_inline'（或混合 token 数组）
+│    wrapperTag = 'span'，wrapperClass = 'inline-latex-content'
+│    └─ renderLatexToken(token) → <span class="inline-katex">KaTeX HTML</span>
+│
+├─ token.type === 'inline'（含 children）
+│    └─ renderInlineChildren(token.children)
+│         ├─ math_inline  → renderLatexToken（递归）
+│         ├─ text         → escapeHtml
+│         ├─ softbreak    → '\n'
+│         ├─ hardbreak    → '<br>'
+│         ├─ code_inline  → '<code>...</code>'
+│         ├─ strong_open/close → '<strong>' / '</strong>'
+│         ├─ em_open/close    → '<em>' / '</em>'
+│         ├─ s_open/close     → '<s>' / '</s>'
+│         ├─ link_open/close  → '<a href="...">...</a>'
+│         ├─ image            → '<img src="..." alt="...">'
+│         └─ 未知类型         → escapeHtml(token.content)
+│
+├─ token.type === 'paragraph_open/close' → '<p>' / '</p>'
+└─ token.type === 'text' / 其他         → escapeHtml(token.content)
+```
+
+### displayMode 判断规则
+
+```typescript
+// renderLatexToken 内部
+const displayMode = token.type === 'math_block' || token.meta?.displayMode === true;
+// math_inline 也可通过 meta.displayMode=true 强制块级渲染
+```
+
+## 基础用法：块级公式
+
+```vue
+<template>
+  <LatexContent :token="token" />
+</template>
+
+<script setup lang="ts">
+  import { LatexContent } from '@blueking/chat-x';
+  import type { Token } from 'markdown-it';
+
+  const token: Token[] = [{ type: 'math_block', content: 'E = mc^2' } as Token];
+</script>
+```
+
+## 行内公式
+
+`math_inline` 类型，包装为 `span.inline-latex-content`，嵌入文字流中渲染：
+
+```vue
+<template>
+  <!-- 行内公式 -->
+  <LatexContent :token="[{ type: 'math_inline', content: 'a^2 + b^2 = c^2' }]" />
+</template>
+```
+
+## 混合 inline token（文字 + 公式）
+
+传入 `inline` token 并带 `children` 时，`renderInlineChildren` 逐一处理文本、公式、标记：
+
+## 积分与根号
+
+## 矩阵
+
+## 对齐环境
+
+## 流式渲染防闪烁
+
+组件针对流式 Markdown 输入进行了优化：**100ms throttle**（leading + trailing）避免每字符重渲染，**`completeLatexContent`** 在每次渲染前自动补全不完整语法：
+
+```vue
+<template>
+  <LatexContent :token="streamingTokens" />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { LatexContent } from '@blueking/chat-x';
+
+  const streamingTokens = ref([{ type: 'math_block', content: '' }]);
+
+  const simulate = async () => {
+    const formula = '\\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}';
+    let content = '';
+    for (const char of formula) {
+      await new Promise(r => setTimeout(r, 50));
+      content += char;
+      streamingTokens.value = [{ type: 'math_block', content }];
+    }
+  };
+</script>
+```
+
+## 语法自动补全（completeLatexContent）
+
+在每次调用 KaTeX 前，组件先通过 `completeLatexContent` 修复不完整语法，处理顺序为：
+
+| 步骤 | 处理内容                                                              | 示例                                          |
+| ---- | --------------------------------------------------------------------- | --------------------------------------------- |
+| 0    | 不完整 `\begin{env` → 猜测环境名补全 `\begin{env}\end{env}`           | `\begin{pma` → `\begin{pmatrix}\end{pmatrix}` |
+| 0.1  | 不完整 `\end{env` → 猜测环境名补全                                    | `\end{alig` → `\end{aligned}`                 |
+| 0.2  | 末尾不完整命令 `\begi` → 若匹配已知命令前缀则移除，完整命令则补全参数 | `\frac` → `\frac{}{}`                         |
+| 1    | 未闭合 `{}` → 补全缺失的 `}`                                          | `\frac{a}{b` → `\frac{a}{b}`                  |
+| 2    | 未闭合 `[]` → 补全缺失的 `]`                                          | `\sqrt[3` → `\sqrt[3]`                        |
+| 3    | 双参数命令缺第二个参数 → 追加 `{}`                                    | `\frac{a}` → `\frac{a}{}`                     |
+| 4    | `\begin{env}` 无对应 `\end{env}` → 追加 `\end{env}`                   | `\begin{matrix}...` → `...\end{matrix}`       |
+
+**可猜测的环境名**（`COMMON_ENVS`）：`aligned`、`align`、`equation`、`gather`、`matrix`、`pmatrix`、`bmatrix`、`vmatrix`、`cases`、`array`、`split`、`multline`
+
+**双参数命令**（`TWO_ARG_COMMANDS`）：`frac`、`dfrac`、`tfrac`、`binom`、`cfrac`、`overset`、`underset` 等
+
+**单参数命令**（`ONE_ARG_COMMANDS`）：`sqrt`、`text`、`mathbf`、`hat`、`vec`、`overline`、`boxed` 等
+
+## 渐进式降级重试（tryRenderKatex）
+
+补全后仍渲染失败时，最多重试 5 次，每次尝试两种裁剪策略：
+
+```
+尝试 completeLatexContent(content) → KaTeX 渲染
+  失败 →
+    策略 1：移除末尾不完整命令（正则 /\\[a-zA-Z]+(\{[^{}]*\})*\s*$/）
+    策略 2：移除未闭合 {（正则 /\{[^{}]*$/）
+  若仍失败 → 返回 null
+    → 渲染 <span class="katex-loading" style="color: #666; font-style: italic;">原始文本（HTML 转义）</span>
+```
+
+> **错误静默**：KaTeX 以 `errorColor: '#fff'`（白色）渲染错误文本，错误不可见。若检测到 HTML 中含 `katex-error` 类或 `color:#cc0000`，也视为渲染失败，降级为 `katex-loading` 显示原始文本。
+
+## API
+
+### Props
+
+| 属性名 | 类型      | 必填 | 说明                                                                                                                     |
+| ------ | --------- | ---- | ------------------------------------------------------------------------------------------------------------------------ |
+| token  | `Token[]` | ✓    | markdown-it Token 数组；支持 `math_block`、`math_inline`、`inline`（含 children）、`paragraph_open/close`、`text` 等类型 |
+
+### Token 结构
+
+```typescript
+// math_block / math_inline
+{
+  type: 'math_block' | 'math_inline';
+  content: string;              // LaTeX 公式字符串
+  meta?: { displayMode?: boolean }; // true → 块级渲染（math_inline 可用此强制块级）
+}
+
+// inline（含行内标记 + 公式混排）
+{
+  type: 'inline';
+  children: Token[];            // 子 token 列表
+}
+```
+
+## 样式说明
+
+| 类名                    | 标签   | 作用                                                                                        |
+| ----------------------- | ------ | ------------------------------------------------------------------------------------------- |
+| `.block-latex-content`  | `div`  | 单一 `math_block` 时的外层，`text-align: center`，`overflow: auto hidden`，`margin: 16px 0` |
+| `.inline-latex-content` | `span` | 混合/行内时的外层，`display: inline`，`vertical-align: baseline`                            |
+| `.block-latex-wrapper`  | `div`  | 每个 `math_block` token 的包装，`text-align: center`，`margin: 16px 0`                      |
+| `.block-katex`          | `span` | 块级 KaTeX 输出                                                                             |
+| `.inline-katex`         | `span` | 行内 KaTeX 输出                                                                             |
+| `.katex-loading`        | `span` | 渲染失败降级态，斜体灰色显示原始 LaTeX 文本                                                 |
+
+## 关联组件
+
+- [MarkdownContent](./markdown-content.md) — 数学公式 token 的来源与挂载

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

@@ -0,0 +1,171 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+LoadingMessage 展示等待 AI 响应的加载动画（内部 AiLoading），无必填 Props，默认插槽可自定义「请求中」文案。 典型用法是由 MessageContainer 在末尾为用户消息时自动注入 Loading 组；也可在自定义布局中手动放置。
+
+### 关联组件
+- **message-container** — 在消息列表末尾自动追加 Loading 消息组
+- **message-render** — role 为 loading 时由 MessageRender 渲染
+- **ai-loading** — 内部使用 AiLoading 原子组件
+
+---
+<!-- FULL DOC -->
+
+# LoadingMessage 加载中消息
+
+> **层级**：分子组件 · **功能域**：消息展示
+
+加载等待状态组件，展示 AI 正在处理请求时的过渡动画。由旋转渐变环 + 脉冲星形图标（蓝→紫→粉渐变）和"请求中..."文案组成。支持通过默认插槽自定义加载文案。
+
+> **提示**：此组件通常**不需要手动使用**，`MessageContainer` 会在满足条件时自动注入。
+
+## 渲染效果
+
+## 基础用法
+
+组件无 Props，直接引入渲染即可：
+
+```vue
+<template>
+  <LoadingMessage />
+</template>
+
+<script setup lang="ts">
+  import { LoadingMessage } from '@blueking/chat-x';
+</script>
+```
+
+## 自定义加载文案
+
+通过默认插槽可覆盖默认的"请求中..."文案：
+
+```vue
+<template>
+  <LoadingMessage>正在思考中，请稍候...</LoadingMessage>
+</template>
+
+<script setup lang="ts">
+  import { LoadingMessage } from '@blueking/chat-x';
+</script>
+```
+
+## 动画说明
+
+`LoadingMessage` 内部使用 `AiLoading` 组件（18px），由两层动画叠加：
+
+| 图层       | 动画                                | 周期 |
+| ---------- | ----------------------------------- | ---- |
+| 旋转渐变环 | `rotate(0 → 360deg)`，线性          | 0.8s |
+| 脉冲星形   | `scale(0.5 → 1 → 0.5)`，ease-in-out | 0.8s |
+
+颜色均使用线性渐变：`#235DFA`（蓝）→ `#8A77EC`（紫）→ `#EB8CEC`（粉）。
+
+## 在 MessageContainer 中的自动注入
+
+`MessageContainer` 在构建消息分组列表时，检测到**消息列表最后一条为用户消息**（`role === 'user'`）时，自动在末尾追加一个 Loading 消息组：
+
+```typescript
+// MessageContainer 内部逻辑（简化）
+if (messages.at(-1)?.role === MessageRole.User) {
+  list.push({
+    messages: [
+      {
+        role: MessageRole.Loading, // 'loading'
+        content: '',
+        status: MessageStatus.Pending,
+        id: 'loading',
+        messageId: '',
+      },
+    ],
+    type: MessageRole.Loading,
+  });
+}
+```
+
+当下一条 AI 消息（`role: 'assistant'`）到来后，最后一条不再是用户消息，Loading 组自动消失。
+
+**触发示例**：
+
+```vue
+<template>
+  <MessageContainer
+    :messages="messages"
+    :message-status="messageStatus"
+    :on-agent-action="handleAgentAction"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { MessageContainer, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const messageStatus = ref(MessageStatus.Pending);
+
+  // 最后一条是 user 消息 → MessageContainer 自动追加 LoadingMessage
+  const messages = ref([
+    {
+      id: '1',
+      messageId: '1',
+      role: MessageRole.User,
+      content: '请帮我写一段 Vue 3 组合式 API 的示例代码',
+      status: MessageStatus.Complete,
+    },
+  ]);
+
+  const handleAgentAction = async () => {};
+</script>
+```
+
+## 注意事项
+
+- **无 Props**：`LoadingMessage` 组件内部没有 `defineProps`，`MessageRender` 向其传入 message 对象的字段均被忽略
+- **默认插槽**：可通过默认插槽自定义加载文案，未传入时显示内置的 "请求中..."
+- **i18n 支持**：默认文案 "请求中..." 通过内置 `t()` 函数处理，英文环境自动显示 "Requesting..."
+- **选择模式**：`MessageContainer` 开启 `enableSelection` 时，Loading 消息组不显示复选框
+- **自动生命周期**：Loading 组随消息列表变化自动插入/移除，无需手动控制
+
+## API
+
+### Props
+
+组件无 Props。
+
+> `MessageRender` 渲染 `role: 'loading'` 消息时会传入 message 对象字段，但 `LoadingMessage` 内部无 `defineProps`，所有传入字段均被忽略。
+
+### Slots
+
+| 插槽名  | 说明                                            |
+| ------- | ----------------------------------------------- |
+| default | 自定义加载文案，默认内容为 i18n 文案"请求中..." |
+
+## 类型定义
+
+```typescript
+import { MessageRole, MessageStatus } from '@blueking/chat-x';
+
+// MessageContainer 自动注入的 Loading 消息结构
+type LoadingMessageData = {
+  id: 'loading';
+  messageId: '';
+  role: MessageRole.Loading; // 'loading'
+  content: '';
+  status: MessageStatus.Pending;
+};
+
+enum MessageRole {
+  Loading = 'loading',
+  // ...
+}
+```
+
+## 使用场景
+
+- **等待 AI 响应**：用户消息发出后、AI 首个 token 到达前的过渡状态，由 `MessageContainer` 自动管理
+- **手动控制场景**：在自定义聊天布局中手动展示加载态（直接引入即可，无需任何配置）
+- **自定义文案**：通过默认插槽传入自定义加载提示文案，满足不同业务场景的文案需求
+
+## 关联组件
+
+- [MessageContainer](./message-container.md) — 自动注入加载组
+- [MessageRender](./message-render.md) — loading 角色派发
+- [AiLoading](../atomic/ai-loading.md) — 内部动画组件

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

@@ -0,0 +1,186 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+MarkdownContent 将 Markdown 字符串解析为 token 并渲染，集成代码块、公式、Mermaid 等子渲染器。 核心 props 为 content 与 status；内置流式节流、语法补全与 DOMPurify 安全策略。 通常由 ContentRender、AssistantMessage 等间接使用，无需业务直接挂载。
+
+### 关联组件
+- **code-content** — fence 代码块语法高亮与复制
+- **latex-content** — 数学公式 token 的 KaTeX 渲染
+- **mermaid-content** — mermaid 代码块的图表渲染
+- **content-render** — 上层按类型分发到本组件渲染 Markdown 字符串
+
+---
+<!-- FULL DOC -->
+
+# MarkdownContent Markdown 内容渲染
+
+> **层级**：原子组件 · **功能域**：内容渲染
+
+AI 消息内容渲染的核心原子组件，集成代码高亮、LaTeX 公式、Mermaid 图表等能力，内置流式渲染优化（5ms throttle + 语法补全 + 防闪烁）。
+
+由 `AssistantMessage`、`ReasoningMessage` 等分子组件内部自动使用，通常不需要手动引入。
+
+## 组件结构与渲染流程
+
+```
+props.content → completeMarkdownSyntax → md.parse → groupTokens → groupedTokens
+                                                                          │
+                             div.markdown-content（contain: layout style）
+                                        │
+                        status === 'error' → CommonErrorContent（:content）
+                                        │
+                        else → div.markdown-body（contain: content）
+                                  │
+                            v-for groupedToken
+                                  │
+                    ┌─────────────┼────────────────────┬───────────────┐
+                    │             │                    │               │
+              hasMermaid?   hasLatex?           hasCode?         else
+                    ↓             ↓                    ↓               ↓
+           MermaidContent  LatexContent        CodeContent    VNodeRenderer
+           @mounted         @mounted           @mounted       @vue:mounted
+                    │
+                    └──── handleTokenMounted（throttle 100ms）→ containerScroll.toScrollBottom()
+```
+
+### Token 分组（groupTokens）
+
+`groupTokens` 使用栈将扁平 Token 数组转为分组数组，每组对应一个顶层 DOM 节点（段落、标题、列表、代码块等）：
+
+- `nesting === 1`（open）→ 入栈，建立新 group；顶层 group 立刻加入结果
+- `nesting === -1`（close）→ 出栈，完成该 group；嵌套 group 合并到父 group
+- `nesting === 0`（自闭合/inline）→ 无栈时独立成组，有栈时追加到当前 group
+
+每组第一个 token 的 `attrs` 追加 `class="ai-blueking-markdown-fade-in"`，触发渐显动画。
+
+### 子组件优先级
+
+对每个 token 组按以下顺序判断：
+
+| 优先级 | 检测逻辑                                                             | 使用组件                                  |
+| ------ | -------------------------------------------------------------------- | ----------------------------------------- |
+| 1      | `fence` token 且 `info === 'mermaid'`                                | `MermaidContent`                          |
+| 2      | `math_inline` / `math_block`，或 children 中递归含有（inline token） | `LatexContent`                            |
+| 3      | `fence`（非 mermaid）或 `code_block`                                 | `CodeContent`                             |
+| 4      | 其余                                                                 | `VNodeRenderer`（HTML 由 DOMPurify 过滤） |
+
+## 基础用法
+
+```vue
+<template>
+  <MarkdownContent
+    :content="markdownText"
+    :status="MessageStatus.Complete"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MarkdownContent, MessageStatus } from '@blueking/chat-x';
+
+  const markdownText = `# 标题\n\n这是一段 **Markdown** 内容。`;
+</script>
+```
+
+## 扩展文本格式
+
+支持标准 Markdown + 扩展插件：`++下划线++`（markdown-it-ins）、`==高亮==`（markdown-it-mark）、`~下标~`（markdown-it-sub）、`^上标^`（markdown-it-sup）：
+
+## 列表与任务清单
+
+## 代码块
+
+代码块由 `CodeContent` 渲染，支持 highlight.js 语法高亮、语言标签、一键复制：
+
+## 表格
+
+## LaTeX 公式
+
+公式由 `LatexContent`（KaTeX）渲染，支持行内 `$...$` 和块级 `$$...$$`：
+
+## Mermaid 图表
+
+## 错误状态
+
+`status === MessageStatus.Error` 时渲染 `CommonErrorContent`，将 `content` 作为错误文本显示：
+
+## 流式渲染
+
+````vue
+<template>
+  <MarkdownContent
+    :content="streamingContent"
+    :status="isStreaming ? MessageStatus.Streaming : MessageStatus.Complete"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { MarkdownContent, MessageStatus } from '@blueking/chat-x';
+
+  const streamingContent = ref('');
+  const isStreaming = ref(false);
+
+  const simulate = async () => {
+    const fullText = '## Hello\n\n**流式输出**演示。\n\n```js\nconsole.log(1);\n```';
+    isStreaming.value = true;
+    for (const char of fullText) {
+      await new Promise(r => setTimeout(r, 30));
+      streamingContent.value += char;
+    }
+    isStreaming.value = false;
+  };
+</script>
+````
+
+### 流式优化机制
+
+| 机制              | 实现                                                                                   | 作用                                                       |
+| ----------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| 极速节流          | `parseMarkdownContent` throttle **5ms**，leading + trailing                            | 每 5ms 最多解析一次，兼顾实时性与性能                      |
+| Markdown 语法补全 | `completeMarkdownSyntax(content)`                                                      | 自动闭合代码块、行内代码、粗斜体、删除线、链接等未完成语法 |
+| LaTeX 防闪烁      | `isIncomplete=true` 且已有渲染结果 → **跳过本次更新**                                  | 正在输入 LaTeX 命令时保持上一帧，避免闪白                  |
+| 子组件 throttle   | `handleTokenMounted` throttle 100ms                                                    | 限制子组件挂载后触发的滚动到底部频率                       |
+| CSS contain       | `.markdown-content { contain: layout style }`<br>`.markdown-body { contain: content }` | 限制重排/重绘范围，减少流式渲染的布局开销                  |
+| 渐显动画          | 每组首 token 追加 `.ai-blueking-markdown-fade-in`                                      | 新内容块淡入，减少视觉跳跃感                               |
+
+## API
+
+### Props
+
+| 属性名  | 类型            | 必填 | 说明                                                      |
+| ------- | --------------- | ---- | --------------------------------------------------------- |
+| content | `string`        | —    | Markdown 文本；为空时清空渲染结果                         |
+| status  | `MessageStatus` | —    | `'error'` 时显示 `CommonErrorContent`，其余状态均正常渲染 |
+
+### 内置插件
+
+| 插件                        | 语法                | 功能                 |
+| --------------------------- | ------------------- | -------------------- |
+| `markdown-it-footnote`      | `[^1]`              | 脚注                 |
+| `markdown-it-ins`           | `++text++`          | 下划线               |
+| `markdown-it-mark`          | `==text==`          | 高亮                 |
+| `markdown-it-sub`           | `~text~`            | 下标                 |
+| `markdown-it-sup`           | `^text^`            | 上标                 |
+| `markdown-it-task-checkbox` | `- [x]`             | 任务列表             |
+| `markdownItMermaid`         | ` ```mermaid `      | Mermaid 图表 token   |
+| `markdownItLatex`           | `$...$` / `$$...$$` | KaTeX 数学公式 token |
+
+### 安全性
+
+`VNodeRenderer` 渲染的 HTML 统一经过 DOMPurify 过滤，并额外允许 KaTeX 所需标签：
+
+```typescript
+const domPurifyConfig = {
+  ADD_TAGS: ['semantics', 'mrow', 'mi', 'mo', 'mn', 'msup', 'msub', 'mfrac', 'mtext', 'annotation'],
+  ADD_ATTR: ['xmlns', 'mathvariant', 'encoding', 'style'],
+};
+```
+
+> `CodeContent`、`MermaidContent`、`LatexContent` 各自内部处理安全性（KaTeX `errorColor`、highlight.js 转义等），不经过 DOMPurify。
+
+## 关联组件
+
+- [CodeContent](./code-content.md) — 代码 fence 高亮
+- [LatexContent](./latex-content.md) — 公式渲染
+- [MermaidContent](./mermaid-content.md) — Mermaid 图表
+- [ContentRender](../molecular/content-render.md) — 内容类型分发入口