@blueking/chat-x 0.0.25 → 0.0.27

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

@@ -0,0 +1,208 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+markdownItLatex 为 markdown-it 插件，解析 $...$、$$...$$、\\(...\\)、\\[...\\] 为 math_inline / math_block token，可选 LatexOption.replaceAlignStart。 不负责渲染，KaTeX 在 LatexContent 中异步渲染。与 Markdown 管道、ContentRender 中的公式展示链路配合。
+
+### 关联组件
+- **latex-content** — 消费 math token 并 KaTeX 渲染
+- **markdown-content** — Markdown 渲染管线
+- **content-render** — 消息内容统一渲染入口
+
+---
+<!-- FULL DOC -->
+
+# markdownItLatex LaTeX 解析插件
+
+> **分类**：plugin
+
+Markdown-it LaTeX 解析插件，用于解析 LaTeX 数学公式语法。
+
+## 功能说明
+
+此插件只负责解析 LaTeX 语法，将其转换为 `math_inline` 和 `math_block` token。实际的 KaTeX 渲染在 `LatexContent` 组件中完成。
+
+## 支持的语法
+
+| 语法      | 类型     | 示例                   |
+| --------- | -------- | ---------------------- |
+| `$...$`   | 行内公式 | `$E = mc^2$`           |
+| `$$...$$` | 块级公式 | `$$\sum_{i=1}^{n} i$$` |
+| `\(...\)` | 行内公式 | `\(E = mc^2\)`         |
+| `\[...\]` | 块级公式 | `\[\sum_{i=1}^{n} i\]` |
+
+## 基础用法
+
+```typescript
+import MarkdownIt from 'markdown-it';
+import { markdownItLatex } from '@blueking/chat-x';
+
+const md = new MarkdownIt().use(markdownItLatex);
+
+// 解析包含 LaTeX 的 Markdown
+const tokens = md.parse(`
+行内公式：$E = mc^2$
+
+块级公式：
+
+$$
+\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}
+$$
+`);
+```
+
+## 配置选项
+
+```typescript
+import MarkdownIt from 'markdown-it';
+import { markdownItLatex, type LatexOption } from '@blueking/chat-x';
+
+const options: LatexOption = {
+  replaceAlignStart: true, // 将 align* 替换为 aligned（KaTeX 不支持 align*）
+};
+
+const md = new MarkdownIt().use(markdownItLatex, options);
+```
+
+### 配置项
+
+| 属性名            | 类型      | 默认值 | 说明                             |
+| ----------------- | --------- | ------ | -------------------------------- |
+| replaceAlignStart | `boolean` | `true` | 是否将 `align*` 替换为 `aligned` |
+
+## Token 类型
+
+插件会生成以下两种 token：
+
+### math_inline
+
+行内数学公式 token：
+
+```typescript
+{
+  type: 'math_inline',
+  tag: 'math',
+  content: 'E = mc^2',
+  markup: '$',
+  meta: { displayMode: false }
+}
+```
+
+### math_block
+
+块级数学公式 token：
+
+```typescript
+{
+  type: 'math_block',
+  tag: 'math',
+  content: '\\sum_{i=1}^{n} i = \\frac{n(n+1)}{2}',
+  markup: '$$',
+  block: true,
+  map: [startLine, endLine]
+}
+```
+
+## 公式示例
+
+### 基础公式
+
+```markdown
+行内公式：$E = mc^2$
+
+块级公式：
+
+$$
+E = mc^2
+$$
+```
+
+### 复杂公式
+
+```markdown
+$$
+\\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}
+$$
+```
+
+### 矩阵
+
+```markdown
+$$
+\\begin{pmatrix}
+a & b \\\\
+c & d
+\\end{pmatrix}
+$$
+```
+
+### 多行公式
+
+```markdown
+$$
+\\begin{aligned}
+f(x) &= x^2 + 2x + 1 \\\\
+     &= (x + 1)^2
+\\end{aligned}
+$$
+```
+
+## 转义处理
+
+插件会正确处理转义的分隔符：
+
+```markdown
+这不是公式：\$100
+
+这是公式：$x = 100$
+```
+
+## 与 KaTeX 配合
+
+渲染由 `LatexContent` 组件完成，使用 KaTeX 库：
+
+```vue
+<template>
+  <LatexContent :token="latexTokens" />
+</template>
+
+<script setup lang="ts">
+  import { LatexContent } from '@blueking/chat-x';
+
+  // latexTokens 是包含 math_inline 或 math_block 的 token 数组
+</script>
+```
+
+## KaTeX 支持说明
+
+KaTeX 支持的功能：
+
+- 大多数 LaTeX 数学符号
+- 分数、根号、指数
+- 矩阵和数组
+- 括号和分隔符
+- 希腊字母和运算符
+- 上下标和大型运算符
+
+KaTeX 限制：
+
+- 不支持 `align*` 环境（插件会自动替换为 `aligned`）
+- 部分 LaTeX 宏不支持
+
+## 使用场景
+
+- AI 数学问答
+- 技术文档展示
+- 教育类应用
+- 科学计算结果展示
+
+## 注意事项
+
+1. **双反斜杠**：在 JavaScript 字符串中，`\` 需要写成 `\\`
+2. **环境支持**：建议使用 `aligned` 替代 `align*`
+3. **性能考虑**：KaTeX 渲染在组件中异步进行，避免阻塞主线程
+
+## 关联组件
+
+- [LatexContent](../components/atomic/latex-content.md) — KaTeX 渲染
+- [MarkdownContent](../components/atomic/markdown-content.md) — Markdown 内容
+- [ContentRender](../components/molecular/content-render.md) — 内容渲染

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

@@ -0,0 +1,250 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+markdownItMermaid 为 markdown-it 插件，将 ```mermaid 代码块转为带 data-mermaid-code、data-mermaid-idx 的占位 DOM，便于前端挂载渲染。 实际绘图由 Mermaid 动态导入在 MermaidContent 中完成，支持流式场景节流与缓存。ContentRender 驱动完整消息 Markdown 流程。
+
+### 关联组件
+- **mermaid-content** — 解析占位并渲染图表
+- **markdown-content** — Markdown fence 管线
+- **content-render** — 消息块级内容渲染
+
+---
+<!-- FULL DOC -->
+
+# markdownItMermaid Mermaid 解析插件
+
+> **分类**：plugin
+
+Markdown-it Mermaid 解析插件，用于解析 Mermaid 图表代码块。
+
+## 功能说明
+
+此插件将 Mermaid 代码块转换为特定的 HTML 结构，实际的 Mermaid 渲染在 `MermaidContent` 组件中完成。
+
+## 支持的语法
+
+````markdown
+```mermaid
+graph TD
+    A[开始] --> B[结束]
+```
+````
+
+## 基础用法
+
+```typescript
+import MarkdownIt from 'markdown-it';
+import { markdownItMermaid } from '@blueking/chat-x';
+
+const md = new MarkdownIt().use(markdownItMermaid);
+
+const html = md.render(`
+\`\`\`mermaid
+graph TD
+    A[开始] --> B{判断}
+    B -->|是| C[处理]
+    B -->|否| D[结束]
+    C --> D
+\`\`\`
+`);
+
+// 输出:
+// <div class="mermaid-wrapper" data-mermaid-code="..." data-mermaid-idx="0"></div>
+```
+
+## 渲染结果
+
+插件会将 Mermaid 代码块转换为以下 HTML：
+
+```html
+<div
+  class="mermaid-wrapper"
+  data-mermaid-code="graph%20TD%0A%20%20%20%20A%5B%E5%BC%80%E5%A7%8B%5D%20--%3E%20B%5B%E7%BB%93%E6%9D%9F%5D"
+  data-mermaid-idx="0"
+></div>
+```
+
+- `data-mermaid-code`: URL 编码后的 Mermaid 代码
+- `data-mermaid-idx`: 代码块索引
+
+## 支持的图表类型
+
+### 流程图 (Flowchart)
+
+````markdown
+```mermaid
+graph TD
+    A[开始] --> B{条件判断}
+    B -->|是| C[执行操作]
+    B -->|否| D[结束]
+    C --> D
+```
+````
+
+### 时序图 (Sequence Diagram)
+
+````markdown
+```mermaid
+sequenceDiagram
+    participant A as 客户端
+    participant B as 服务器
+    A->>B: 请求
+    B-->>A: 响应
+```
+````
+
+### 甘特图 (Gantt Chart)
+
+````markdown
+```mermaid
+gantt
+    title 项目计划
+    dateFormat  YYYY-MM-DD
+    section 阶段1
+    任务1           :a1, 2024-01-01, 30d
+    任务2           :after a1, 20d
+    section 阶段2
+    任务3           :2024-02-01, 12d
+```
+````
+
+### 类图 (Class Diagram)
+
+````markdown
+```mermaid
+classDiagram
+    class Animal {
+        +name: string
+        +age: int
+        +makeSound()
+    }
+    class Dog {
+        +breed: string
+        +bark()
+    }
+    Animal <|-- Dog
+```
+````
+
+### 状态图 (State Diagram)
+
+````markdown
+```mermaid
+stateDiagram-v2
+    [*] --> 待处理
+    待处理 --> 处理中: 开始处理
+    处理中 --> 已完成: 处理完成
+    处理中 --> 失败: 处理失败
+    已完成 --> [*]
+    失败 --> 待处理: 重试
+```
+````
+
+### 饼图 (Pie Chart)
+
+````markdown
+```mermaid
+pie title 语言使用占比
+    "JavaScript" : 45
+    "TypeScript" : 35
+    "Python" : 15
+    "其他" : 5
+```
+````
+
+### ER 图 (Entity Relationship)
+
+````markdown
+```mermaid
+erDiagram
+    用户 ||--o{ 订单 : 创建
+    订单 ||--|{ 订单明细 : 包含
+    商品 ||--o{ 订单明细 : 包含于
+```
+````
+
+## 与 MermaidContent 组件配合
+
+实际渲染由 `MermaidContent` 组件完成：
+
+```vue
+<template>
+  <MermaidContent
+    :token="mermaidTokens"
+    @mounted="handleMounted"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MermaidContent } from '@blueking/chat-x';
+
+  // mermaidTokens 是包含 mermaid fence 的 token 数组
+  const handleMounted = ({ el }) => {
+    console.log('Mermaid 图表渲染完成:', el);
+  };
+</script>
+```
+
+## 流式渲染
+
+组件支持流式渲染，在代码输入过程中实时更新图表：
+
+````vue
+<template>
+  <ContentRender
+    :content="streamingContent"
+    :status="MessageStatus.Streaming"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ContentRender, MessageStatus } from '@blueking/chat-x';
+
+  const streamingContent = ref('');
+
+  // 模拟流式输入 Mermaid 代码
+  const simulateStreaming = async () => {
+    const code = '```mermaid\ngraph TD\n    A --> B\n```';
+    for (const char of code) {
+      await new Promise(r => setTimeout(r, 50));
+      streamingContent.value += char;
+    }
+  };
+</script>
+````
+
+## 错误处理
+
+当 Mermaid 代码语法错误时：
+
+1. 插件仍会正常解析并输出 HTML
+2. `MermaidContent` 组件会捕获渲染错误
+3. 控制台会输出警告信息
+4. 图表区域保持空白，不会影响其他内容
+
+## 性能优化
+
+- **节流渲染**：流式输入时使用 100ms 节流
+- **代码缓存**：相同代码不会重复渲染
+- **异步加载**：Mermaid 库按需动态导入
+
+## 使用场景
+
+- AI 生成的流程图说明
+- 技术文档中的架构图
+- 项目计划展示
+- 数据关系可视化
+
+## 注意事项
+
+1. **异步渲染**：Mermaid 库是动态导入的，首次渲染可能有短暂延迟
+2. **语法验证**：组件会先验证语法，无效代码不会尝试渲染
+3. **SVG 输出**：渲染结果是 SVG，可以自由缩放
+4. **样式覆盖**：可以通过 CSS 自定义图表样式
+
+## 关联组件
+
+- [MermaidContent](../components/atomic/mermaid-content.md) — Mermaid 渲染
+- [MarkdownContent](../components/atomic/markdown-content.md) — Markdown 内容
+- [ContentRender](../components/molecular/content-render.md) — 内容渲染

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

@@ -20,7 +20,7 @@ MessageContainer 是消息列表的核心容器。接收父组件用 useMessageG
 - **消息分组**：将连续的非用户消息合并为一组，每组共享一个工具栏
 - **Tool 消息关联**：自动将 `role: 'tool'` 消息注入到对应 Assistant 消息的 toolCall 中
 - **Loading 自动注入**：末尾为用户消息时，自动追加 Loading 动画组
-- **滚动管理**：流式输出时显示"停止生成"，离开底部时显示"返回底部"
+- **滚动管理**：`messageStatus` 为流式、等待响应或请求中（`streaming` / `pending` / `fetching`）时显示「停止生成」，离开底部时显示「返回底部」
 - **多选模式**：支持按消息组勾选，用户消息与 AI 回复联动选中
 
 ## 基础用法
@@ -110,6 +110,7 @@ MessageContainer 是消息列表的核心容器。接收父组件用 useMessageG
 
 **关键细节**：
 
+- 每个消息组外层 DOM 的 `id` 为 **`MessageGroup.uid`**（由 `useMessageGroup` 生成），供执行摘要「在对话中定位」、侧栏自定义 Tab 等场景滚动锚定
 - `role: 'tool'` 消息**不会独立渲染**，而是被注入到对应 AssistantMessage 的 `toolCall.toolMessage` 字段
 - 若 `toolMessage.error` 存在，AssistantMessage 的 `status` 会被强制设为 `MessageStatus.Error`
 - `MessageTools` 工具栏只在 `type === 'assistant'` 的消息组底部渲染（不依赖鼠标悬停，始终可见），且满足以下条件时**不渲染**：
@@ -124,9 +125,9 @@ MessageContainer 是消息列表的核心容器。接收父组件用 useMessageG
 
 当 `messages` 末尾为 `role: 'user'` 时，自动追加 Loading 消息组，展示 AI 正在处理的加载动画：
 
-## 流式输出
+## 流式输出与停止生成
 
-`messageStatus` 为 `streaming` 时，底部固定区域显示「停止生成」按钮，点击后触发 `@stop-streaming` 事件。
+当 `messageStatus` 为 `streaming`、`pending`（等待首包）或 `fetching`（请求中、与末尾 Loading 占位一致）时，底部固定区域显示「停止生成」按钮（`stop-loading` 时按钮展示为正在停止），点击后触发 `@stop-streaming` 事件。
 
 点击下方按钮体验完整的流式输出过程：
 
@@ -443,10 +444,10 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 
 底部固定区域（`position: sticky; bottom: 12px`）根据条件显示两个按钮：
 
-| 按钮         | 显示条件                                                                     | 点击行为               |
-| ------------ | ---------------------------------------------------------------------------- | ---------------------- |
-| 「停止生成」 | `messageStatus === 'streaming'`                                              | 触发 `@stop-streaming` |
-| 「返回底部」 | `debouncedShowScrollBottomBtn`（距底部 > 100px，且防抖 300ms 后才显示/隐藏） | 滚动到消息列表底部     |
+| 按钮         | 显示条件                                                                                       | 点击行为               |
+| ------------ | ---------------------------------------------------------------------------------------------- | ---------------------- |
+| 「停止生成」 | `messageStatus` 为 `streaming`、`pending`、`fetching` 或 `stop-loading`（停止中 loading 态） | 触发 `@stop-streaming` |
+| 「返回底部」 | `debouncedShowScrollBottomBtn`（距底部 > 100px，且防抖 300ms 后才显示/隐藏）                     | 滚动到消息列表底部     |
 
 > **防抖说明**：「返回底部」按钮的显隐使用 300ms 防抖，避免快速滚动时按钮频繁闪烁。隐藏时立即生效（无防抖），显示时延迟 300ms。
 
@@ -458,7 +459,7 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 | ------------------------ | -------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | messages                 | `Message[]`                                                                                  | —       | **必填**，消息列表                                                                                                                       |
 | messageGroups            | `MessageGroup[]`                                                                             | —       | 预计算的消息分组；传入时跳过内部分组逻辑，由 `ChatContainer` 通过 `useMessageGroup` 提供                                                 |
-| messageStatus            | `MessageStatus`                                                                              | —       | 当前整体消息状态，控制停止生成按钮显示                                                                                                   |
+| messageStatus            | `MessageStatus`                                                                              | —       | 当前整体消息状态，控制底部「停止生成」按钮显示；`ChatContainer` 会结合末尾 Loading 占位推导 `fetching` 等再传入                                                                                                   |
 | messageToolsStatus       | `MessageToolsStatus`                                                                         | —       | 工具栏状态，透传给 `MessageTools` 和 `MessageRender`                                                                                     |
 | messageToolsTippyOptions | `AITippyProps`                                                                               | —       | 透传给 `MessageTools` 和 `MessageRender`（进而透传给 `UserMessage` 的工具栏）的 Tippy 配置，用于自定义 tooltip 挂载点（如 `appendTo`）等 |
 | enableSelection          | `boolean`                                                                                    | `false` | 是否启用多选模式                                                                                                                         |