@blueking/chat-x 0.0.25 → 0.0.26

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

@@ -16,6 +16,8 @@ ActivityMessage 展示活动类消息：知识检索（knowledge_rag）、引用
 
 活动消息组件，用于展示 AI 的知识检索（Knowledge RAG）过程、参考文档引用列表和 FlowAgent 流程执行情况。通过 `activityType` 切换三种工作模式，点击标题栏可折叠/展开内容区域。
 
+组件会将父级传入消息上的 **`uid`** 以 **`message-uid`** 形式透传给各活动子组件（`FlowAgentContent` / `KnowledgeRagContent` / `ReferenceDocContent`），用于侧栏自定义 Tab、`addCustomTab` 的 `data.messageUid` 与主对话区「在对话中定位」联动（详见 [ChatContainer](./chat-container.md)）。
+
 ## 三种工作模式
 
 组件根据 `activityType` 的值决定渲染模式：

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-ChatContainer 提供完整 AI 对话布局：分栏（ResizeLayout）、消息列表（MessageContainer）、输入（ChatInput）、执行摘要（ExecutionSummary）、快捷表单（ShortcutRender）与多选栏（SelectionFooter）。 内置 useMessageGroup、分享与自定义 Tab 等能力，适合一站式接入。 通过 props 传入 messages、shortcuts 等，事件与 ChatInput/MessageContainer 对齐。
+ChatContainer 提供完整 AI 对话布局：分栏（ResizeLayout）、消息列表（MessageContainer）、输入（ChatInput）、执行摘要（ExecutionSummary）、快捷表单（ShortcutRender）与多选栏（SelectionFooter）。 内置 useMessageGroup、分享与自定义 Tab 等能力；对 MessageContainer/ChatInput 下推 inputStatus（末尾 Loading 占位时推导 Fetching），适合一站式接入。 通过 props 传入 messages、shortcuts 等，事件与 ChatInput/MessageContainer 对齐。
 
 ### 关联组件
 - **message-container** — 消息列表与滚动区域
@@ -21,8 +21,9 @@ ChatContainer 提供完整 AI 对话布局：分栏（ResizeLayout）、消息
 
 ## 核心能力
 
-- **分栏布局**：基于 `ResizeLayout` 的可拖拽分栏，侧边栏展示执行摘要 / 自定义 Tab
+- **分栏布局**：基于 `ResizeLayout` 的可拖拽分栏；**侧栏是否展示 Tab / 执行摘要、以及分栏是否进入折叠样式（`ai-is-collapse`）以 `executionGroups` 为准**（由 `useMessageGroup` 从消息中过滤出工具调用与 FlowAgent 执行记录），**不以原始 `messages.length` 判断**。因此仅有普通对话、尚无执行类消息时，侧栏内容与「执行情况」区域可能为空，布局上与无执行数据时一致
 - **消息分组**：内置 `useMessageGroup` 自动处理消息分组、Tool 合并、Loading 注入
+- **输入区状态推导**：传给 `MessageContainer` 与 `ChatInput` 的 `messageStatus` 为内部计算值 `inputStatus`：当分组中存在 id 为 `LOADING_MESSAGE_ID`（`'__loading__'`，由 `useMessageGroup` 注入的占位 Loading 消息）时，对内使用 `MessageStatus.Fetching`；否则使用外部传入的 `messageStatus`。用于在「已发用户消息、尚未流式」阶段与流式中一致地展示停止能力，并避免输入区重复发送
 - **执行摘要**：侧边栏展示工具调用 / FlowAgent 执行记录，支持关键词搜索和对话定位
 - **自定义 Tab**：通过 `useCustomTabProvider` 支持动态添加自定义 Tab（如节点详情）
 - **分享模式**：内置消息多选分享流程，选中用户消息后确认分享
@@ -39,7 +40,7 @@ ai-chat-container
     │   │   ├── 执行情况（默认 Tab）
     │   │   └── 自定义 Tab × N（可关闭）
     │   ├── ExecutionSummary（执行情况 Tab 内容）
-    │   ├── 自定义 Tab 组件（通过 component :is 渲染）
+    │   ├── 自定义 Tab 组件（通过 component :is 渲染，可向子组件注入 #locateButton）
     │   └── collapse-button（折叠按钮）
     └── main（主内容区）
         ├── MessageContainer（有消息时）
@@ -107,6 +108,10 @@ ai-chat-container
 
 侧边栏默认包含「执行情况」Tab，展示所有工具调用和 FlowAgent 类型的 Activity 消息。支持关键词搜索过滤和点击定位到对话中的消息位置。
 
+**展示条件**：当 `executionGroups` 为空时，不渲染侧栏 Tab 与 `ExecutionSummary`（折叠按钮亦隐藏）；主区域仍可正常展示 `messages` 中的对话内容。`renderMode === Share` 时侧栏隐藏，且分栏会应用与折叠一致的样式。
+
+**自定义 Tab 联动**：当 `executionGroups` 变为空（例如会话清空或仅剩无执行类消息）时，容器会**自动重置自定义 Tab**（`resetCustomTab`），避免残留节点详情等 Tab。
+
 ```vue
 <template>
   <ChatContainer
@@ -141,7 +146,13 @@ ai-chat-container
 
 ## 自定义 Tab
 
-通过 `ref` 获取组件实例后，使用 `addCustomTab` / `removeCustomTab` 动态管理侧边栏 Tab：
+通过 `ref` 获取组件实例后，使用 `addCustomTab` / `removeCustomTab` 动态管理侧边栏 Tab。若 **`executionGroups` 变为空**，容器会清空自定义 Tab 状态（与侧栏执行数据联动，见上文「侧边栏与执行摘要」）。
+
+### 自定义 Tab 与「在对话中定位」
+
+`addCustomTab` 的 `data` 可携带 **`messageUid`**（与对应活动消息的 `message.uid` 一致）。`ChatContainer` 在侧栏用 `<component :is>` 渲染自定义 Tab 时，会向子组件提供 **`locateButton` 插槽**：默认渲染「在对话中定位」按钮，点击后调用内部 `handleLocateMessageGroup(messageUid)`，优先滚动到主区域 `document.getElementById(messageUid)`；若不存在该节点，则在当前 `messageGroups` 中查找包含 `message.uid === messageUid` 的消息组，并滚动到该组的容器（`MessageGroup.uid` 作为组级 `id`）。
+
+子组件若需展示该按钮，请在模板中声明 `<slot name="locateButton" />`（例如 FlowAgent 节点详情标题栏）。`FlowAgentContent` 等会在打开节点详情 Tab 时将 `messageUid` 写入 `data`，与 `ActivityMessage` 下传给内容区的 `message-uid` 对齐。
 
 ```vue
 <template>
@@ -163,13 +174,14 @@ ai-chat-container
   const chatContainerRef = useTemplateRef<InstanceType<typeof ChatContainer>>('chatContainerRef');
 
   // 添加自定义 Tab（如 FlowAgent 节点详情）
-  const addNodeDetailTab = (nodeId: string, nodeName: string) => {
+  const addNodeDetailTab = (nodeId: string, nodeName: string, messageUid?: string) => {
     chatContainerRef.value?.addCustomTab({
       name: `node-${nodeId}`,
       label: nodeName,
       data: {
-        component: MyNodeDetail, // 自定义组件
+        component: MyNodeDetail, // 自定义组件（模板内需 <slot name="locateButton" /> 以展示侧栏「在对话中定位」）
         props: { loading: true, data: {} },
+        messageUid, // 与活动消息 message.uid 一致时可省略；用于主对话定位
       },
     });
   };
@@ -408,11 +420,11 @@ ChatContainer 的 Props 继承自 `ChatInputProps` 和 `MessageContainerProps`
 ```typescript
 import { ChatContainer, RenderMode, type CustomTab, type Shortcut, type Message } from '@blueking/chat-x';
 
-// 自定义 Tab
+// 自定义 Tab（data 可与 messageUid 组合，供侧栏定位主对话）
 interface CustomTab<T = Record<string, unknown>> {
   label: string;
   name: string;
-  data?: T;
+  data?: T & { messageUid?: string };
 }
 
 // 快捷指令

package/dist/mcp/generated/docs/chat-input.md

@@ -82,10 +82,10 @@ chat-input-container
 | `messageStatus`               | 输入框有内容时按钮表现                                 | 输入框空时               |
 | ----------------------------- | ------------------------------------------------------ | ------------------------ |
 | `complete` / `stop` / `error` | 蓝色发送按钮，点击触发 `onSendMessage`                 | 灰色禁用                 |
-| `streaming` / `pending`       | 蓝色停止按钮（Loading 图标），点击触发 `onStopSending` | 蓝色停止按钮（仍可点击） |
+| `streaming` / `pending` / `fetching` | 蓝色停止按钮（Loading 图标），点击触发 `onStopSending` | 蓝色停止按钮（仍可点击） |
 | `disabled`                    | 灰色禁用，点击无效                                     | 灰色禁用                 |
 
-> **实现细节**：组件内部用 `messageState` 计算属性决定实际按钮状态：当 `messageStatus` 为 `pending` 或 `streaming` 时直接使用该状态（确保停止按钮始终可用）；否则当输入为空或仅含空白字符时强制为 `disabled`，其余情况使用 `messageStatus` 的值。
+> **实现细节**：组件内部用 `messageState` 计算属性决定实际按钮状态：当 `messageStatus` 为 `pending`、`streaming` 或 `fetching` 时直接使用该状态（确保停止按钮始终可用）；否则当输入为空或仅含空白字符时强制为 `disabled`，其余情况使用 `messageStatus` 的值。`fetching` 时按 Enter **不会**触发发送（避免请求中与 Loading 占位阶段重复提交）。
 
 ### Complete（可发送）
 

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

@@ -17,23 +17,19 @@ CodeContent 接收 markdown-it 的 fence/code_block token，按行 highlight.js
 
 ## 组件结构
 
-样式根选择器为 **`.ai-message-container .code-content-wrapper`**：代码块头部与 `pre` 区样式仅在消息容器（如 `MessageContainer` 根上的 `ai-message-container`）下生效。Wiki 与业务中独立演示时，请将 `CodeContent` 包在带 `ai-message-container` 类名的父节点内。
+根类名为 **`.code-content-wrapper`**：外层宽度、下边距以及 **`.code-content-header`**（深色顶栏）在任意父级下均生效。**代码区** `.hljs-pre`、行内高亮等样式选择器为 **`.ai-message-container .code-content-wrapper`**，仅在消息列表（`MessageContainer` 根上的 `ai-message-container`）内与对话区一致。Wiki 与业务中若要完整还原代码区外观，请将 `CodeContent` 包在带 `ai-message-container` 类名的父节点内。
 
 ```
-.ai-message-container .code-content-wrapper（width: 100%，margin-bottom: 12px）
-├── .code-content-header（height: 40px，bg: #2f333d，border: 1px solid #1a1a1a）
-│     ├── .code-header-language（color: #999，显示 token.info 原始字符串）
-│     ├── slot#header（{ language, token }）— 自定义头部操作按钮区域
-│     └── ToolBtn id="copy"（点击复制 codeRef.innerText）
+.code-content-wrapper
+├── .code-content-header（深色顶栏；不依赖 .ai-message-container）
+│     ├── .code-header-language（token.info）
+│     ├── slot#header（{ language, token }）
+│     └── ToolBtn id="copy"
 │
-└── .hljs-pre（bg: #282c34，padding: 8×16，overflow-x: auto）
+└── .hljs-pre（完整 padding / 背景 / code 字体：需父级为 .ai-message-container .code-content-wrapper）
       └── <code class="hljs language-{raw-info}">
-            ├── v-for completedLines
-            │     <span class="code-line" v-html="line.html" /> + '\n'
-            │     （已完成行，经过 hljs.highlight 高亮）
-            └── v-if currentLineText
-                  <span class="code-line current-line" v-html="currentLineHtml" />
-                  （最后一行，也经过 highlightLine，用 .current-line 标识正在输入）
+            ├── v-for completedLines → <span class="code-line" />
+            └── v-if currentLineText → <span class="code-line current-line" />
 ```
 
 ## 基础用法
@@ -42,7 +38,7 @@ CodeContent 接收 markdown-it 的 fence/code_block token，按行 highlight.js
 
 ```vue
 <template>
-  <!-- 完整深色头部与 pre 样式依赖父级 .ai-message-container（与对话消息区一致） -->
+  <!-- 代码区 .hljs-pre 的完整样式依赖父级 .ai-message-container（与对话消息区一致）；顶栏单独也可用 -->
   <div class="ai-message-container">
     <CodeContent
       :token="codeTokens"

package/dist/mcp/generated/docs/constants.md

@@ -0,0 +1,242 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+汇总 MessageRole、MessageStatus（含 Fetching 请求中）、MessageContentType、MessageToolsStatus、MessageState、Z-Index 与 CONST_MESSAGE_TOOLS 等导出常量。 用于构造消息、配置 MessageContainer 工具栏与输入态，以及层级与默认快捷指令。与类型 messages 配套使用。
+
+### 关联组件
+- **message-tools** — 默认工具 ID 与展示
+- **chat-input** — MessageState 与快捷指令
+- **message-container** — 工具栏与消息态
+
+---
+<!-- FULL DOC -->
+
+# 常量枚举
+
+> **分类**：type
+
+`@blueking/chat-x` 导出的常量和枚举类型。
+
+## 消息相关
+
+### MessageRole
+
+消息角色枚举：
+
+```typescript
+enum MessageRole {
+  User = 'user',
+  Assistant = 'assistant',
+  System = 'system',
+  Developer = 'developer',
+  Guide = 'guide',
+  Hidden = 'hidden',
+  HiddenAssistant = 'hidden-assistant',
+  HiddenGuide = 'hidden-guide',
+  HiddenSystem = 'hidden-system',
+  HiddenUser = 'hidden-user',
+  Info = 'info',
+  Loading = 'loading',
+  Pause = 'pause',
+  Placeholder = 'placeholder',
+  Reasoning = 'reasoning',
+  TemplateAssistant = 'template-assistant',
+  TemplateGuide = 'template-guide',
+  TemplateHidden = 'template-hidden',
+  TemplateSystem = 'template-system',
+  TemplateUser = 'template-user',
+  Tool = 'tool',
+  Activity = 'activity',
+}
+```
+
+### MessageStatus
+
+消息状态枚举：
+
+```typescript
+enum MessageStatus {
+  Complete = 'complete',
+  Disabled = 'disabled',
+  Error = 'error',
+  Fetching = 'fetching', // 请求中（例如已发用户消息、尚未开始流式，与末尾 Loading 占位一致）
+  Pending = 'pending',
+  Stop = 'stop',
+  StopLoading = 'stop-loading',
+  Streaming = 'streaming',
+  Success = 'success',
+}
+```
+
+| 枚举值          | 说明 |
+| --------------- | ---- |
+| `Fetching`      | 请求中：与 `useMessageGroup` 在末尾用户消息后注入的 Loading 占位（`LOADING_MESSAGE_ID`）配合时，`ChatContainer` 会将传入输入区与列表底部的状态推导为该值，便于展示「停止」与禁止重复发送。 |
+
+### MessageContentType
+
+消息内容类型枚举：
+
+```typescript
+enum MessageContentType {
+  Binary = 'binary',
+  Function = 'function',
+  KeyValue = 'key-value',
+  KnowledgeRag = 'knowledge-rag',
+  Other = 'other',
+  ReferenceDocument = 'reference-document',
+  Text = 'text',
+}
+```
+
+### MessageToolsStatus
+
+消息工具栏状态枚举：
+
+```typescript
+enum MessageToolsStatus {
+  Disabled = 'disabled', // 禁用状态，按钮显示但不可点击
+  Hidden = 'hidden', // 隐藏状态，工具栏完全隐藏
+}
+```
+
+### RenderMode
+
+渲染模式枚举，控制 `ChatContainer` / `MessageContainer` 的 UI 行为：
+
+```typescript
+enum RenderMode {
+  Chat = 'chat',   // 默认对话模式
+  Share = 'share', // 分享预览模式：隐藏侧边栏和工具栏，启用多选样式
+  Test = 'test',   // 测试/嵌入模式：过滤掉「分享」按钮
+}
+```
+
+| 枚举值  | 侧边栏 | MessageTools   | 说明                           |
+| ------- | ------ | -------------- | ------------------------------ |
+| `Chat`  | 正常   | 全部按钮       | 默认行为                       |
+| `Share` | 隐藏   | 隐藏           | 分享预览，仅展示消息内容       |
+| `Test`  | 正常   | 过滤掉「分享」 | 测试或嵌入场景，隐藏分享入口   |
+
+## 输入状态
+
+### MessageState
+
+输入框消息状态：
+
+```typescript
+const MessageState = {
+  ACTIVE: 'active',
+  DISABLED: 'disabled',
+  LOADING: 'loading',
+} as const;
+```
+
+## Z-Index 常量
+
+```typescript
+// 全局 chat-x 组件 Z-Index
+const CHAT_Z_INDEX = 9999;
+
+// 编辑器组件 Z-Index
+const EDITOR_Z_INDEX = 10000;
+
+// 编辑器菜单 Z-Index
+const EDITOR_MENU_Z_INDEX = 10001;
+
+// 快捷指令菜单 Z-Index
+const SHORTCUT_MENU_Z_INDEX = 10002;
+
+// 划选弹窗 Z-Index
+const SELECTION_Z_INDEX = 10003;
+```
+
+## 默认工具按钮
+
+### CONST_MESSAGE_TOOLS
+
+消息工具按钮列表：
+
+```typescript
+const CONST_MESSAGE_TOOLS: IToolBtn[] = [
+  { id: 'copy', name: '复制', description: '复制' },
+  { id: 'cite', name: '引用', description: '引用' },
+  { id: 'rebuild', name: '重新生成', description: '重新生成' },
+  { id: 'share', name: '分享', description: '分享' },
+];
+```
+
+### CONST_USER_MESSAGE_TOOLS
+
+用户消息工具按钮列表：
+
+```typescript
+const CONST_USER_MESSAGE_TOOLS: IToolBtn[] = [
+  { id: 'copy', name: '复制', description: '复制' },
+  { id: 'cite', name: '引用', description: '引用' },
+  { id: 'edit', name: '编辑', description: '编辑' },
+  { id: 'delete', name: '删除', description: '删除' },
+];
+```
+
+### CONST_UPDATE_TOOLS
+
+更新工具按钮列表（点赞/不满意）：
+
+```typescript
+const CONST_UPDATE_TOOLS: IToolBtn[] = [
+  { id: 'like', name: '点赞', description: '点赞' },
+  { id: 'unlike', name: '不满意', description: '不满意' },
+  { id: 'delete', name: '删除', description: '删除' },
+];
+```
+
+## 默认快捷指令
+
+### DEFAULT_SHORTCUTS
+
+默认快捷指令列表：
+
+```typescript
+const DEFAULT_SHORTCUTS: Shortcut[] = [{ id: 'ask-whale', name: '问问小鲸' }];
+```
+
+## 使用示例
+
+```typescript
+import {
+  MessageRole,
+  MessageStatus,
+  MessageContentType,
+  MessageToolsStatus,
+  RenderMode,
+  CHAT_Z_INDEX,
+  CONST_MESSAGE_TOOLS,
+  DEFAULT_SHORTCUTS,
+} from '@blueking/chat-x';
+
+// 创建消息
+const message = {
+  id: '1',
+  messageId: 1,
+  role: MessageRole.User,
+  content: '你好',
+  status: MessageStatus.Complete,
+};
+
+// 检查消息状态
+if (message.status === MessageStatus.Streaming) {
+  console.log('消息正在流式输出中...');
+}
+
+// 使用默认工具按钮
+console.log(
+  '可用工具:',
+  CONST_MESSAGE_TOOLS.map(t => t.name),
+);
+```
+
+## 关联组件
+
+- [MessageTools](../components/molecular/message-tools.md) — 消息工具栏
+- [ChatInput](../components/molecular/chat-input.md) — 输入与状态
+- [MessageContainer](../components/molecular/message-container.md) — 工具与消息展示

package/dist/mcp/generated/docs/execution-summary.md

@@ -40,8 +40,8 @@ ExecutionSummary 以时间线汇总工具调用与 FlowAgent 等活动记录，
 <script setup lang="ts">
   import { ExecutionSummary, type MessageGroup } from '@blueking/chat-x';
 
-  const handleLocate = (uuid: string, group: MessageGroup) => {
-    const dom = document.getElementById(uuid);
+  const handleLocate = (uid: string, group: MessageGroup) => {
+    const dom = document.getElementById(uid);
     dom?.scrollIntoView({ behavior: 'smooth' });
   };
 
@@ -100,7 +100,7 @@ execution-summary
 
 | 事件名             | 参数                                  | 说明                     |
 | ------------------ | ------------------------------------- | ------------------------ |
-| locateMessageGroup | `(uuid: string, group: MessageGroup)` | 点击「在对话中定位」按钮 |
+| locateMessageGroup | `(uid: string, group: MessageGroup)` | 点击「在对话中定位」按钮，参数为消息组 `MessageGroup.uid` |
 | updateKeyword      | `(keyword: string)`                   | 搜索关键词变更           |
 
 ## 类型定义
@@ -109,7 +109,7 @@ execution-summary
 import { type MessageGroup } from '@blueking/chat-x';
 
 interface MessageGroup {
-  uuid: string;
+  uid: string;
   type: MessageRole;
   messages: Message[];
   checked: boolean;

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

@@ -0,0 +1,56 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+markdownItContainer 基于 markdown-it-container，支持字符串或正则匹配容器名；MarkdownContent 中用于 hljs-left/center/right 对齐。 渲染为带 class 的 div，与 tokens-to-vnodes 及样式配合。
+
+### 关联组件
+- **markdown-content** — 渲染管线中注册插件
+
+---
+<!-- FULL DOC -->
+
+# markdownItContainer 自定义容器插件
+
+> **分类**：plugin
+
+将 `::: 容器名` 开头的块解析为带 `class` 的块级容器，闭合行使用 `:::`。
+
+## 语法示例
+
+```markdown
+::: hljs-left
+左对齐内容
+:::
+
+::: hljs-center
+居中内容
+:::
+
+::: hljs-right
+右对齐内容
+:::
+```
+
+## 在 MarkdownContent 中的注册方式
+
+组件内使用正则同时注册左/中/右三种容器名：
+
+```typescript
+import MarkdownIt from 'markdown-it';
+import { markdownItContainer } from '../../../src/plugins/markdown-container';
+
+const md = new MarkdownIt({ html: true }).use(markdownItContainer, /^hljs-(left|center|right)$/);
+```
+
+## 配置说明
+
+| 参数   | 类型                | 说明                                               |
+| ------ | ------------------- | -------------------------------------------------- |
+| `name` | `string \| RegExp`  | 容器标识；字符串为精确匹配，正则用于一类名称       |
+| `opts` | `ContainerOptions?` | 可选 `marker`、`validate`、`render` 覆盖默认行为   |
+
+更多行为见源码 `packages/chat-x/src/plugins/markdown-container.ts`。
+
+## 关联
+
+- [MarkdownContent](../components/atomic/markdown-content.md) — 实际接入与样式

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) — 内容渲染