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

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

@@ -0,0 +1,232 @@
+# MarkdownContent Markdown 内容渲染
+
+> 能力域：内容渲染 ｜ 导入：`import { MarkdownContent } from '@blueking/chat-x'` ｜ since 1.0.0
+
+Markdown 主渲染器，集成代码块、公式、错误降级和 codeHeader 插槽。 源码位置：src/components/chat-content/markdown-content/markdown-content.vue。
+
+**关联**：code-content（fence 代码块语法高亮与复制）、latex-content（数学公式 token 的 KaTeX 渲染）、mermaid-content（mermaid 代码块的图表渲染）、content-render（上层按类型分发到本组件渲染 Markdown 字符串）
+
+---
+
+# MarkdownContent Markdown 内容渲染
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/markdown-content/markdown-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：Markdown 主渲染器，集成代码块、公式、错误降级和 codeHeader 插槽。
+
+> **能力域**：内容渲染
+
+AI 消息内容渲染的核心基础组件，集成代码高亮、LaTeX 公式、Mermaid 图表等能力，内置流式渲染优化（5ms throttle + 语法补全 + 防闪烁）。
+
+由 `AssistantMessage`、`ReasoningMessage` 等组合组件内部自动使用，通常不需要手动引入。
+
+## 组件结构与渲染流程
+
+```
+props.content → completeMarkdownSyntax → md.parse → groupTokens → groupedTokens
+                                                                          │
+                          div.ai-markdown-content（contain: layout style）
+                                        │
+                        status === 'error' → CommonErrorContent（:content）
+                                        │
+                        else → div.ai-markdown-body[data-theme]（contain: content）
+                                  │
+                            v-for groupedToken
+                                  │
+                    ┌─────────────┼────────────────────┬───────────────┐
+                    │             │                    │               │
+              hasMermaid?   hasLatex?           hasCode?         else
+                    ↓             ↓                    ↓               ↓
+           MermaidContent  LatexContent        CodeContent    VNodeRenderer
+           @mounted         @mounted           @mounted       @vue:mounted
+                    │
+                    └──── handleTokenMounted（throttle 100ms）→ containerScroll.toScrollBottom()
+```
+
+`VNodeRenderer` 的 `options` 中包含与当前 `MarkdownIt` 实例一致的 `mditOptions`（即 `md.options`），以便 `tokensToVNodes` 调用 `renderer.rules` 时第三参与 markdown-it 原生规则签名一致。
+
+### 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 语法高亮、语言标签、一键复制。语法高亮主题样式由 `CodeContent` 侧引入（`github-dark`），`MarkdownContent` **不再**全局引入 `highlight.js` 主题 CSS，避免与代码块组件重复加载、并保持与消息区样式一致。
+
+## 表格
+
+## 对齐容器（markdown-it-container）
+
+支持 `::: hljs-left` / `::: hljs-center` / `::: hljs-right` 自定义容器，内容渲染在带对应 class 的块级容器中，由内置样式控制 `text-align`：
+
+## 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       | `.ai-markdown-content { contain: layout style }`<br>`.ai-markdown-body { contain: content }` | 限制重排/重绘范围，减少流式渲染的布局开销                  |
+| 渐显动画          | 每组首 token 追加 `.ai-blueking-markdown-fade-in`                                            | 新内容块淡入，减少视觉跳跃感                               |
+
+## 主题支持
+
+组件通过 `data-theme` 属性和本地 `markdown-content.css`（由 GitHub Markdown 样式 vendoring 而来，类前缀为 `ai-markdown-body`）控制主题，默认为 `light`，避免受宿主页面 `@media (prefers-color-scheme)` 影响。
+
+- **Light 模式**（默认）：`.ai-markdown-body[data-theme="light"]`，light 变量 + `color-scheme: light`
+- **Dark 模式**：`.ai-markdown-body[data-theme="dark"]`，dark 变量 + `color-scheme: dark`
+
+> 外层包裹类名为 `.ai-markdown-content`，内层正文区为 `.ai-markdown-body`，避免与宿主或其他库的 `.markdown-body` 全局样式冲突。
+
+## API
+
+### Props
+
+| 属性名  | 类型            | 必填 | 说明                                                      |
+| ------- | --------------- | ---- | --------------------------------------------------------- |
+| content | `string`        | —    | Markdown 文本；为空时清空渲染结果                         |
+| status  | `MessageStatus` | —    | `'error'` 时显示 `CommonErrorContent`，其余状态均正常渲染 |
+
+### Slots
+
+| 插槽名     | 参数                                   | 说明                                                                                    |
+| ---------- | -------------------------------------- | --------------------------------------------------------------------------------------- |
+| codeHeader | `{ language: string; token: Token[] }` | 代码块头部自定义操作区域，透传给 CodeContent 的 header 插槽，可添加"插入"、"应用"等按钮 |
+
+### 内置插件
+
+| 插件                        | 语法                | 功能                 |
+| --------------------------- | ------------------- | -------------------- |
+| `markdownItBkInlineStyle`   | 见下文「蓝鲸行内样式」 | 安全行内颜色/字号/粗斜体（非 HTML） |
+| `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 |
+| `markdownItContainer`       | `::: hljs-left` 等  | 自定义对齐容器（class 与 highlight.js 命名对齐） |
+
+### 蓝鲸行内样式（`markdownItBkInlineStyle`）
+
+不开启 `html: true`，由专用语法生成带白名单 `style` 的 `<span class="bk-md-inline-style">`。
+
+**语法**：`::bk{` *属性* `}` *正文* `:/bk::`
+
+- 属性写在 `{}` 内，使用 `;` 分隔；每项为 `键=值` 或 `键:值`。
+- 正文支持行内 Markdown（如 `**粗体**`）。
+- 结束标记必须为字面量 `:/bk::`，请勿在正文中出现该序列。
+
+**支持的键**：`color` / `c`、`background-color`、`font-size`、`bold`、`italic`（详见 `plugins/markdown-bk-inline-style.ts` 内注释）。
+
+**示例**：
+
+```markdown
+::bk{color:#c00;font-size:18px}**重要**:/bk::
+::bk{background-color:yellow}高亮:/bk::
+::bk{bold;italic}强调:/bk::
+```
+
+### 安全性
+
+`MarkdownIt` **不**开启 `html: true`，用户无法插入任意 HTML 标签；行内彩色/字号等请使用上文「蓝鲸行内样式」扩展。
+
+`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](/components/rendering/code-content) — 代码 fence 高亮
+- [LatexContent](/components/rendering/latex-content) — 公式渲染
+- [MermaidContent](/components/rendering/mermaid-content) — Mermaid 图表
+- [ContentRender](/components/rendering/content-render) — 内容类型分发入口

package/skills/blueking-chat-x/references/components/mention-tag.md

@@ -0,0 +1,79 @@
+# MentionTag 资源标签
+
+> 能力域：内容渲染 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 0.0.51
+
+MentionTag 渲染「图标 + 蓝色名称」的内联资源标签：节点数据全部落在 data-tag-* 属性上， 既是编辑器 void 节点的识别依据，也让消息里复制的标签能原样还原； description 非空时 hover / 点击弹出「类型：名称 + 描述」气泡；type 为 artifact 且存在产物预览上下文时点击打开侧栏预览。 源码位置：src/components/mention/mention-tag.vue（气泡见 mention-popover.vue 与 create-mention-tippy.ts）。
+
+**关联**：mention-text（按文档结构批量渲染标签与文本）、ai-slash-input（编辑器内的 tag 节点由本组件渲染）、resource-icon（标签左侧图标）、file-artifact-panel（artifact 标签点击后打开的侧栏预览）
+
+---
+
+# MentionTag 资源标签
+
+> **能力域**：内容渲染
+
+## 源码事实
+
+- **标签**：`src/components/mention/mention-tag.vue`
+- **气泡内容**：`src/components/mention/mention-popover.vue`
+- **气泡配置**：`src/components/mention/create-mention-tippy.ts`
+- **能力说明**：设计稿形态为「图标 + 蓝色文字」内联展示，无背景块；高度 22px，`vertical-align: bottom`。
+
+## data-tag-\* 属性
+
+标签把节点数据全部写在 DOM 属性上，这不是冗余：
+
+| 属性                   | 作用                                                     |
+| ---------------------- | -------------------------------------------------------- |
+| `data-tag-type`        | 与 `contenteditable="false"` 一起作为编辑器 void 节点的识别依据 |
+| `data-tag-value`       | 资源 id，`artifact` 点击预览、`skill` 序列化都取它        |
+| `data-tag-label`       | 展示名，避免从 `textContent` 读取时混入图标带来的空白     |
+| `data-tag-icon`        | 图标 URL（组件形式的图标无法序列化，此时为空）            |
+| `data-tag-description` | 描述文案，让气泡脱离 `menuSources` 独立工作               |
+
+因此从消息里复制一段带标签的文本再粘贴回输入框，标签能被原样还原。
+
+## 交互
+
+- **描述气泡**：`description` 非空时才创建气泡（否则 `onShow` 直接返回 `false`）。标题格式为 `类型：名称`，类型名与菜单分组标题同源（`getMenuTypeLabel`）。
+- **触发方式**：`mouseenter focus click`，展示延迟 300ms、关闭无延迟；`hideOnClick` 关闭并改用 `onClickOutside` 收起，因此再次点击标签不会把气泡收掉，触屏也能点开。
+- **产物预览**：`type` 为 `artifact` 且存在 [useArtifactPreview](/composables/use-artifact-preview) 上下文时，点击标签以 `{ file: { outputId: value } }` 打开侧栏预览。
+- **可交互暗示**：仅在「有描述」或「可预览」时给出 `cursor: pointer` 与名称下划线。
+
+::: info 为什么用指令而不是 `<Tippy>` 组件
+标签渲染在 `contenteditable` 内部，多包一层元素会干扰编辑器对 void 节点的识别与 DOM 比对，因此气泡走 `v-tippy` 指令。
+:::
+
+## 渲染示例
+
+> 前三个标签中「翻译」「天气查询」带描述，hover 可见气泡；`artifact` 标签在有产物预览上下文时可点击。
+
+## API
+
+### Props
+
+| 属性名      | 类型     | 必填 | 说明                                                  |
+| ----------- | -------- | ---- | ----------------------------------------------------- |
+| label       | `string` | ✅   | 标签展示名                                            |
+| value       | `string` | ✅   | 资源 id                                               |
+| type        | `string` | ✅   | 资源类型，决定兜底图标、气泡标题与是否可预览          |
+| icon        | `string` | -    | 图标 URL；缺省时按 `type` 兜底                        |
+| description | `string` | -    | 描述文案，非空时启用气泡                              |
+
+### MentionPopover Props
+
+| 属性名      | 类型     | 必填 | 说明                                 |
+| ----------- | -------- | ---- | ------------------------------------ |
+| title       | `string` | ✅   | 形如「工具：天气查询」               |
+| description | `string` | -    | 描述正文，最大宽度 240px，自动换行   |
+
+### Emits / Slots / Expose
+
+- 无。
+
+## 关联组件
+
+- [MentionText](/components/rendering/mention-text) — 按文档结构批量渲染
+- [AiSlashInput](/components/input/ai-slash-input) — 编辑器内的标签宿主
+- [ResourceIcon](/components/helper/resource-icon) — 标签图标
+- [useArtifactPreview](/composables/use-artifact-preview) — 产物预览上下文

package/skills/blueking-chat-x/references/components/mention-text.md

@@ -0,0 +1,83 @@
+# MentionText 标签文本
+
+> 能力域：内容渲染 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 0.0.51
+
+MentionText 接收一份 TagSchema 文档（二维数组：行 → 节点），逐行渲染：text 节点输出文本、 tag 节点交给 MentionTag；行间用 <br> 分隔，空白以 pre-wrap 保留。 UserMessage 在 property.docSchema 含标签时用它替代 TextContent。 源码位置：src/components/mention/mention-text.vue。
+
+**关联**：mention-tag（tag 节点的实际渲染者）、user-message（用户消息在文档含标签时改用本组件回显）、text-content（纯文本消息仍走 TextContent）
+
+---
+
+# MentionText 标签文本
+
+> **能力域**：内容渲染
+
+## 源码事实
+
+- **源码位置**：`src/components/mention/mention-text.vue`
+- **能力说明**：把 `TagSchema` 文档渲染成「文本 + 资源标签」，让用户消息里 `@` 选中的资源保持标签形态而不是退化成纯文本。
+- **样式**：`width: fit-content`、`word-break: break-all`、`white-space: pre-wrap`（行间换行由 `<br>` 承担，行内连续空格与纯文本分支表现一致）。
+
+## 数据流：消息里的标签怎么活下来
+
+```
+用户在输入框选中资源
+  → onSendMessage(content, docSchema)   content 仍是纯文本，不改后端契约
+  → 业务侧把 docSchema 存进 message.property.docSchema
+  → UserMessage 检测到文档中存在 tag 节点
+  → 用 MentionText 渲染（否则回退 TextContent）
+```
+
+业务侧不保存 `docSchema` 时一切照旧：历史消息与第三方消息仍走 [TextContent](/components/rendering/text-content) 渲染纯文本。编辑消息后也需要把新的 `docSchema` 写回，否则改完这条消息标签就丢了。
+
+```typescript
+// 发送
+const handleSendMessage = async (content: UserMessage['content'], docSchema: TagSchema) => {
+  messages.value.push({
+    id, messageId: id, role: MessageRole.User, content,
+    property: { docSchema },
+  });
+};
+
+// 编辑确认
+const handleUserInputConfirm = async (message: Message, content: UserMessage['content'], docSchema: TagSchema) => {
+  target.content = content;
+  target.property = { ...target.property, docSchema };
+};
+```
+
+## 渲染示例
+
+## API
+
+### Props
+
+| 属性名 | 类型        | 必填 | 说明                                       |
+| ------ | ----------- | ---- | ------------------------------------------ |
+| doc    | `TagSchema` | ✅   | 发送时随消息一起保存的编辑器文档           |
+
+### Emits / Slots / Expose
+
+- 无。
+
+### 文档结构
+
+```typescript
+type TagSchema = Array<
+  Array<
+    | { type: 'text'; text: string }
+    | {
+        type: 'tag';
+        data: { label: string; value: string; type: string; icon: string; description: string };
+      }
+  >
+>;
+```
+
+外层数组是行，内层数组是行内节点。渲染时第 2 行起前置一个 `<br>`。
+
+## 关联组件
+
+- [MentionTag](/components/rendering/mention-tag) — 单个标签渲染与气泡
+- [UserMessage](/components/message/user-message) — 使用方
+- [TextContent](/components/rendering/text-content) — 无文档时的回退渲染

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

@@ -0,0 +1,189 @@
+# MermaidContent Mermaid 图表
+
+> 能力域：内容渲染 ｜ 导入：`import { MermaidContent } from '@blueking/chat-x'` ｜ since 1.0.0
+
+渲染 Mermaid 图表并处理渲染事件。 源码位置：src/components/markdown-token/mermaid-content/mermaid-content.vue。
+
+**关联**：markdown-content（解析 mermaid 类型 fence 代码块后传入 token）
+
+---
+
+# MermaidContent Mermaid 图表渲染
+## 源码事实
+
+- **源码位置**：`src/components/markdown-token/mermaid-content/mermaid-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：渲染 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.ai-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，值为渲染后的 .ai-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，返回当前 `.ai-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](/components/rendering/markdown-content) — mermaid fence token 的来源与挂载