@blueking/chat-x 0.0.5 → 0.0.7

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/mermaid-content.md

@@ -0,0 +1,185 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+MermaidContent 将 info 为 mermaid 的 fence token 渲染为 SVG，模块级懒加载单例 Mermaid。 具备流式 throttle、错误静默与 SVG ID 随机化，避免多实例冲突。 由 MarkdownContent 在解析 mermaid 代码块时调用。
+
+### 关联组件
+- **markdown-content** — 解析 mermaid 类型 fence 代码块后传入 token
+
+---
+<!-- FULL DOC -->
+
+# MermaidContent Mermaid 图表渲染
+
+> **层级**：原子组件 · **功能域**：内容渲染
+
+Markdown Token 层的 Mermaid 图表渲染原子组件，被 `MarkdownContent` 在检测到 mermaid fence token 时自动调用，通常无需手动引入。
+
+核心能力：**按需懒加载 Mermaid**（动态 import 单例）、**三级去重跳过**（代码比对 → 语法校验 → SVG 比对）、**100ms throttle** 流式防抖、**错误静默**（parse 失败时保持上一次 SVG）。
+
+## 组件结构与渲染流程
+
+```
+props.token（Token[]）
+│
+├─ extractMermaidCode(tokens)
+│    → 遍历找第一个 type==='fence' && info.trim()==='mermaid' && content 非空的 token
+│    → 返回 content（无匹配返回空字符串）
+│
+└─ renderMermaid（throttle 100ms，leading + trailing）
+      │
+      ├─ 1. newCode === lastMermaidCode  → return（代码未变，跳过）
+      ├─ 2. lastMermaidCode = newCode
+      ├─ 3. getMermaidInstance()         → 动态 import('mermaid') 单例，初始化一次
+      ├─ 4. mermaid.parse(code, { suppressErrors: true })
+      │      → !isValid → return（语法无效，保持上次 SVG）
+      ├─ 5. mermaid.render('mermaid-content-' + randomId, code) → { svg }
+      ├─ 6. svgDomStr.value === svg      → return（SVG 无变化，跳过）
+      └─ 7. svgDomStr.value = svg
+             nextTick → emit('mounted', { get el() { return mermaidContentRef.value } })
+
+模板：
+div.mermaid-content（:key="svgDomStr"，v-html="svgDomStr"）
+  注：:key 绑定 svgDomStr，每次 SVG 变化会重建 div 而非就地 patch
+```
+
+## 基础用法
+
+```vue
+<template>
+  <MermaidContent
+    :token="tokens"
+    @mounted="handleMounted"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MermaidContent } from '@blueking/chat-x';
+  import type { Token } from 'markdown-it';
+
+  const tokens: Token[] = [
+    {
+      type: 'fence',
+      tag: 'code',
+      info: 'mermaid',
+      content: `graph TD
+    A[开始] --> B{判断}
+    B -->|是| C[执行]
+    B -->|否| D[结束]`,
+    } as Token,
+  ];
+
+  const handleMounted = ({ el }: { el: HTMLElement | null }) => {
+    // el 是 lazy getter，值为渲染后的 .mermaid-content 元素
+    console.log('渲染完成:', el);
+  };
+</script>
+```
+
+## 支持的图表类型
+
+### 时序图（Sequence Diagram）
+
+### 甘特图（Gantt）
+
+### 类图（Class Diagram）
+
+### 状态图（State Diagram）
+
+### 饼图（Pie Chart）
+
+## 流式渲染
+
+流式输入时 Mermaid 语法逐步完整，组件通过 throttle + `parse` 语法校验避免无效渲染：
+
+```vue
+<template>
+  <MermaidContent :token="streamingTokens" />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { MermaidContent } from '@blueking/chat-x';
+
+  const streamingTokens = ref([{ type: 'fence', tag: 'code', info: 'mermaid', content: '' }]);
+
+  const simulate = async () => {
+    const code = `graph TD\n    A[开始] --> B[处理]\n    B --> C[结束]`;
+    let content = '';
+    for (const char of code) {
+      await new Promise(r => setTimeout(r, 50));
+      content += char;
+      streamingTokens.value = [{ type: 'fence', tag: 'code', info: 'mermaid', content }];
+    }
+  };
+</script>
+```
+
+**流式过程中的行为**：
+
+| 阶段                       | `parse` 结果 | 行为                                      |
+| -------------------------- | ------------ | ----------------------------------------- |
+| 代码未变化                 | —            | 三级去重第 1 关：直接跳过，不调用 Mermaid |
+| 语法不完整（如 `graph T`） | `false`      | 三级去重第 2 关：跳过渲染，保持上次 SVG   |
+| 语法完整，SVG 相同         | `true`       | 三级去重第 3 关：跳过 DOM 更新            |
+| 语法完整，SVG 变化         | `true`       | 更新 SVG，触发 `mounted` 事件             |
+
+## API
+
+### Props
+
+| 属性名 | 类型      | 必填 | 说明                                                                                         |
+| ------ | --------- | ---- | -------------------------------------------------------------------------------------------- |
+| token  | `Token[]` | ✓    | markdown-it Token 数组；组件自动从中提取第一个 `type==='fence' && info==='mermaid'` 的 token |
+
+### Events
+
+| 事件名  | 参数                          | 触发时机                                                                           |
+| ------- | ----------------------------- | ---------------------------------------------------------------------------------- |
+| mounted | `{ el: HTMLElement \| null }` | SVG 更新后的 `nextTick`；`el` 为 lazy getter，返回当前 `.mermaid-content` 元素引用 |
+
+### Token 结构
+
+```typescript
+// 组件只识别 type === 'fence' 且 info.trim() === 'mermaid' 的 token
+{
+  type: 'fence';
+  tag?: 'code';         // 可选
+  info: 'mermaid';      // 必须严格等于 'mermaid'（trim 后）
+  content: string;      // Mermaid 图表定义语法
+}
+```
+
+## 性能与错误处理细节
+
+### 单例 Mermaid 实例
+
+```typescript
+// 模块级变量，所有 MermaidContent 实例共享同一个 mermaid 模块
+let mermaidInstance: MermaidModule | null = null;
+
+// 初始化时调用一次（suppressErrorRendering: true 抑制 Mermaid 内部错误 UI）
+mermaidInstance.default.initialize({ suppressErrorRendering: true });
+```
+
+首次渲染因动态 import 会有约 200~500ms 的网络加载延迟，之后复用实例无额外开销。
+
+### SVG ID 随机化
+
+每次调用 `mermaid.render` 时生成随机 ID：
+
+```typescript
+mermaid.default.render('mermaid-content-' + Math.random().toString(36).substring(2, 15), code);
+```
+
+避免多个 MermaidContent 实例或同一实例多次渲染时 DOM ID 冲突。
+
+### 错误静默
+
+- `mermaid.parse` 失败（语法无效）→ `return`，不修改 `svgDomStr`，保持上次成功的 SVG
+- `mermaid.render` 抛出异常 → `console.warn`，不修改 `svgDomStr`，保持上次成功的 SVG
+- 两种情况下组件界面均无错误提示（静默降级）
+
+## 关联组件
+
+- [MarkdownContent](./markdown-content.md) — mermaid fence token 的来源与挂载