@will1123/lx-ui-utils 1.0.0 → 1.0.2

package/README.md

@@ -1,4 +1,4 @@
-# @lx-ui/utils
+# @will1123/lx-ui-utils
 
 LX UI 通用工具函数库，提供常用的工具函数和 AI 相关功能。
 
@@ -6,17 +6,17 @@ LX UI 通用工具函数库，提供常用的工具函数和 AI 相关功能。
 
 - 🚀 **TypeScript 支持** - 完整的类型定义
 - 📦 **Tree-Shaking 支持** - 按需引入，减少打包体积
-- 🎯 **零依赖** - 无需安装额外依赖
-- 🔧 **AI 相关工具** - SSE、思考过程提取、Markdown 渲染
+- 🔐 **内置认证** - 支持 Token 认证
+- 🔧 **AI 相关工具** - SSE、深度思考提取、Markdown 渲染
 
 ## 安装
 
 ```bash
-npm install @lx-ui/utils
+npm install @will1123/lx-ui-utils
 # 或
-yarn add @lx-ui/utils
+yarn add @will1123/lx-ui-utils
 # 或
-pnpm add @lx-ui/utils
+pnpm add @will1123/lx-ui-utils
 ```
 
 ## 使用方法
@@ -24,201 +24,828 @@ pnpm add @lx-ui/utils
 ### 全量导入
 
 ```typescript
-import { sse, extractThinking, renderMarkdown } from '@lx-ui/utils'
+import { sse, extractThinking, createMarkdownRender, bindMarkdownCodeBoxEvents } from '@will1123/lx-ui-utils'
 ```
 
 ### 按需导入（推荐）
 
 ```typescript
-import { sse } from '@lx-ui/utils'
-import { extractThinking } from '@lx-ui/utils'
-import { renderMarkdown } from '@lx-ui/utils'
+import { sse } from '@will1123/lx-ui-utils'
+import { extractThinking } from '@will1123/lx-ui-utils'
+import {
+  createMarkdownRender,
+  getMarkdownCodeTheme,
+  setMarkdownCodeTheme,
+  toggleMarkdownCodeTheme,
+  updateMarkdownCodeBlocksTheme,
+  bindMarkdownCodeBoxEvents
+} from '@will1123/lx-ui-utils'
+import { copyToClipboard, isDom } from '@will1123/lx-ui-utils'
 ```
 
 ## API 文档
 
 ### SSE (Server-Sent Events)
 
-封装 SSE 请求，支持流式响应。
+基于 `@microsoft/fetch-event-source` 封装的 SSE 请求，支持流式响应、自动重连和页面可见性控制。
 
 #### 类型定义
 
 ```typescript
 interface SSEConfig {
-  url: string                      // 请求 URL
-  method?: 'GET' | 'POST'          // 请求方法，默认 GET
-  headers?: Record<string, string> // 请求头
-  body?: any                       // 请求体（POST 请求时使用）
-  timeout?: number                 // 请求超时时间（毫秒）
+  url: string                          // 请求 URL
+  method?: 'GET' | 'POST'              // 请求方法，默认 POST
+  headers?: Record<string, string>     // 请求头
+  body?: object                        // 请求体（对象类型）
+  signal?: AbortSignal                 // 用于取消请求
+  token?: string                       // 认证 Token
+  openWhenHidden?: boolean             // 页面隐藏时是否保持连接，默认 true
 }
 
 interface SSEHandlers {
-  onMessage?: (message: SSEMessage) => void
-  onOpen?: () => void
-  onClose?: () => void
-  onError?: (error: Error) => void
+  onOpen?: (response: Response) => void | Promise<void>       // 连接打开时触发
+  onMessage?: (message: EventSourceMessage) => void            // 接收到消息时触发
+  onClose?: () => void                                          // 连接关闭时触发
+  onError?: (error: Error) => void                              // 发生错误时触发
 }
 ```
 
 #### 使用示例
 
 ```typescript
-import { sse } from '@lx-ui/utils'
+import { sse } from '@will1123/lx-ui-utils'
+
+// 基础用法（默认 POST）
+await sse({
+  url: 'https://api.example.com/stream',
+  body: { prompt: '你好' }
+}, {
+  onMessage(msg) {
+    console.log('收到消息:', msg)
+  }
+})
 
-// GET 请求（使用 EventSource）
-const connection = sse(
-  {
-    url: 'https://api.example.com/stream'
+// 使用 Token 认证
+await sse({
+  url: 'https://api.example.com/stream',
+  token: 'Bearer your-token-here',
+  body: { prompt: '你好' }
+}, {
+  onOpen(response) {
+    console.log('连接已打开，状态:', response.status)
   },
-  {
-    onMessage: (message) => {
-      console.log('收到消息:', message.data)
-    },
-    onOpen: () => {
-      console.log('连接已打开')
-    },
-    onClose: () => {
-      console.log('连接已关闭')
-    },
-    onError: (error) => {
-      console.error('连接错误:', error)
-    }
-  }
-)
-
-// 关闭连接
-connection.close()
-
-// POST 请求（使用 fetch）
-const connection2 = sse(
-  {
-    url: 'https://api.example.com/stream',
-    method: 'POST',
-    headers: {
-      'Authorization': 'Bearer your-token'
-    },
-    body: {
-      prompt: '你好'
-    },
-    timeout: 30000
+
+  onMessage(msg) {
+    // msg 是原始对象，包含 data、event、id 等字段
+    console.log('收到消息:', msg.data)
   },
-  {
-    onMessage: (message) => {
-      console.log('收到消息:', message.data)
-    }
+
+  onClose() {
+    console.log('连接已关闭')
+  },
+
+  onError(err) {
+    console.error('连接错误:', err)
+  }
+})
+
+// GET 请求
+await sse({
+  url: 'https://api.example.com/stream',
+  method: 'GET'
+}, {
+  onMessage(msg) {
+    console.log(msg.data)
+  }
+})
+
+// 取消请求
+const ctrl = new AbortController()
+await sse({
+  url: 'https://api.example.com/stream',
+  signal: ctrl.signal
+}, {
+  onMessage(msg) {
+    console.log(msg.data)
   }
-)
+})
+
+// 取消请求
+ctrl.abort()
 ```
 
-### 思考过程提取
+### 深度思考提取
 
-从 AI 响应中提取 `<think>` 标签内容。
+从 AI 响应中提取深度思考内容。
 
 #### 类型定义
 
 ```typescript
 interface ThinkingExtractConfig {
-  tagName?: string      // 思考标签名称，默认 'think'
-  includeTags?: boolean // 是否包含标签本身
-  removeRest?: boolean  // 是否移除剩余内容
+  tagName?: string              // 思考标签名称，默认 'think'
+  mode?: 'full' | 'end-tag-only'  // 解析模式
 }
 
 interface ThinkingResult {
-  thinking: string      // 提取的思考内容
-  rest: string          // 剩余内容
-  hasThinking: boolean  // 是否找到思考内容
+  thinking: string              // 提取的思考内容
+  content: string               // 实际回答内容
 }
 ```
 
 #### 使用示例
 
 ```typescript
-import { extractThinking, createThinkingExtractor } from '@lx-ui/utils'
+import { extractThinking } from '@will1123/lx-ui-utils'
 
-// 完整模式
-const text = `<think>
-这是 AI 的思考过程
-</think>
-这是实际回答内容`
+// 模式 1：完整标签（默认）
+const text1 = `这是思考内容
+这是回答内容`
 
-const result = extractThinking(text)
-console.log(result.thinking) // "\n这是 AI 的思考过程\n"
-console.log(result.rest)     // "这是实际回答内容"
-console.log(result.hasThinking) // true
+const result1 = extractThinking(text1)
+console.log(result1.thinking) // "这是思考内容"
+console.log(result1.content)  // "这是回答内容"
 
-// 流式模式（用于 SSE）
-const extractor = createThinkingExtractor({
-  tagName: 'think',
-  includeTags: false
-})
+// 模式 2：仅结束标签
+const text2 = '这是思考内容这是回答内容'
 
-// 逐步追加文本
-const chunk1 = extractor.append('<think>这是')
-console.log(chunk1.thinking) // "这是"
+const result2 = extractThinking(text2, { mode: 'end-tag-only' })
+console.log(result2.thinking) // "这是思考内容"
+console.log(result2.content)  // "这是回答内容"
 
-const chunk2 = extractor.append('思考过程')
-console.log(chunk2.thinking) // "这是思考过程"
+// 模式 3：没有标签
+const text3 = '全部是正文内容'
 
-const chunk3 = extractor.append('</think>实际回答')
-console.log(chunk3.thinking) // "这是思考过程"
-console.log(chunk3.isComplete) // true
+const result3 = extractThinking(text3)
+console.log(result3.thinking) // ""
+console.log(result3.content)  // "全部是正文内容"
 ```
 
 ### Markdown 渲染
 
-将 Markdown 文本渲染为 HTML。
+基于 **Marked.js** 的增强 Markdown 渲染器，支持代码高亮、主题切换、自定义样式和 KaTeX 数学公式。
+
+#### 特性
+
+- ✅ **链接增强** - 自动添加 `target="_blank"`
+- ✅ **表格优化** - 自动包装在可滚动容器中
+- ✅ **代码增强** - 显示语言标签、复制按钮、主题切换
+- ✅ **主题系统** - 支持 dark/light 主题切换，基于 localStorage
+- ✅ **代码高亮** - 集成 highlight.js，支持 190+ 语言
+- ✅ **GFM 支持** - 表格、任务列表、删除线等
+- ✅ **类名前缀** - 所有生成的类名带 `lx-ui` 前缀，避免冲突
+- ✅ **KaTeX 公式** - 支持数学公式渲染（可选）
 
 #### 类型定义
 
 ```typescript
-interface MarkdownRenderConfig {
-  highlight?: boolean              // 是否启用代码高亮
-  highlightLanguages?: Record<string, string>
-  taskList?: boolean               // 是否渲染任务列表，默认 true
-  table?: boolean                  // 是否渲染表格，默认 true
-  link?: boolean                   // 是否渲染链接，默认 true
-  image?: boolean                  // 是否渲染图片，默认 true
+type CodeTheme = 'dark' | 'light'
+
+interface CreateMarkdownRenderConfig {
+  codeBoxToolEnable?: boolean  // 代码块工具栏是否启用，默认 true
+  katexEnable?: boolean         // 是否启用 KaTeX 公式支持，默认 true
+  katexOptions?: KatexOptions   // KaTeX 配置选项
 }
 ```
 
-#### 使用示例
+#### 使用步骤
+
+##### 1. 引入代码高亮样式（必需）
+
+选择一个 highlight.js 主题并引入：
+
+```javascript
+// 暗色主题（推荐）
+import 'highlight.js/styles/base16/outrun-dark.min.css'
+import 'highlight.js/styles/atom-one-dark.min.css'
+import 'highlight.js/styles/github-dark.min.css'
+
+// 亮色主题
+import 'highlight.js/styles/github.min.css'
+import 'highlight.js/styles/base16/solarflare-light.min.css'
+
+// 查看所有主题：https://highlightjs.org/examples
+// 主题文件位置：node_modules/highlight.js/styles/
+```
+
+##### 2. 引入 KaTeX 样式（必需，默认启用公式支持）
+
+```javascript
+// KaTeX 样式（必需，默认启用公式支持）
+import 'katex/dist/katex.min.css'
+```
+
+##### 3. 创建渲染器
 
 ```typescript
-import { renderMarkdown, createMarkdownRenderer } from '@lx-ui/utils'
+import { createMarkdownRender } from '@will1123/lx-ui-utils'
+
+// 创建渲染器（默认启用工具栏和 KaTeX 公式支持）
+const renderer = createMarkdownRender({
+  codeBoxToolEnable: true,
+  katexEnable: true,
+  katexOptions: {
+    throwOnError: false,
+    strict: false
+  }
+})
+
+// 创建渲染器（禁用工具栏）
+const simpleRenderer = createMarkdownRender({
+  codeBoxToolEnable: false
+})
+
+// 创建渲染器（禁用公式支持）
+const noKatexRenderer = createMarkdownRender({
+  codeBoxToolEnable: true,
+  katexEnable: false
+})
+```
 
-// 完整模式
+##### 4. 渲染 Markdown
+
+```typescript
 const markdown = `# 标题
 
 这是一段**粗体**和*斜体*文字。
 
+## 数学公式
+
+### 行内公式
+爱因斯坦质能方程：$E = mc^2$
+
+### 块级公式
+$$
+\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}
+$$
+
+## 代码示例
+
+\`\`\`javascript
+function greet(name) {
+  console.log(\`Hello, \${name}!\`)
+  return true
+}
+\`\`\`
+
+## 表格
+
+| 列1 | 列2 | 列3 |
+|-----|-----|-----|
+| A   | B   | C   |
+| D   | E   | F   |
+
+## 任务列表
+
 - [ ] 未完成任务
 - [x] 已完成任务
 
-| 列1 | 列2 |
-|-----|-----|
-| A   | B   |
-
 [链接](https://example.com)
 `
 
-const html = renderMarkdown(markdown)
+// 渲染（异步）
+const html = await renderer.parse(markdown)
 console.log(html)
+```
 
-// 流式模式（用于 SSE）
-const renderer = createMarkdownRenderer({
-  table: true,
-  taskList: true,
-  onUpdate: (html) => {
-    console.log('更新渲染:', html)
-  }
+#### KaTeX 公式语法
+
+支持两种公式语法：
+
+**行内公式** - 使用单个 `$` 包裹：
+```markdown
+爱因斯坦方程：$E = mc^2$
+```
+
+**块级公式** - 使用双个 `$$` 包裹：
+```markdown
+$$
+\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}
+$$
+```
+
+**注意事项**：
+- 行内公式不能包含换行符
+- 块级公式可以跨多行
+- 如果公式渲染失败，会保留原始公式文本
+- KaTeX 公式支持默认启用，无需配置即可使用
+- 如需禁用公式支持，设置 `katexEnable: false`
+
+#### 生成的 HTML 结构 - KaTeX 公式
+
+**行内公式**：
+```html
+<span class="lx-ui-katex-inline">
+  <!-- KaTeX 生成的 HTML -->
+</span>
+```
+
+**块级公式**：
+```html
+<div class="lx-ui-katex-block">
+  <!-- KaTeX 生成的 HTML -->
+</div>
+```
+
+#### 主题管理
+
+```typescript
+import { getMarkdownCodeTheme, setMarkdownCodeTheme, toggleMarkdownCodeTheme, updateMarkdownCodeBlocksTheme } from '@will1123/lx-ui-utils'
+
+// 获取当前主题
+const theme = getMarkdownCodeTheme()  // 'dark' | 'light'
+
+// 设置主题
+setMarkdownCodeTheme('light')
+
+// 切换主题（只更新 localStorage，不更新 DOM）
+const newTheme = toggleMarkdownCodeTheme()
+
+// 更新 DOM 中所有代码块的主题（方式 1：只传主题）
+updateMarkdownCodeBlocksTheme('dark')
+
+// 更新指定容器内代码块的主题（方式 2：传容器和主题）
+const container = document.querySelector('#markdown-container')
+updateMarkdownCodeBlocksTheme(container, 'light')
+```
+
+**注意**：
+- `toggleMarkdownCodeTheme()` 只切换 `localStorage` 中的主题，不会更新 DOM
+- `updateMarkdownCodeBlocksTheme()` 用于更新 DOM 中代码块的 `data-theme` 属性
+- `bindMarkdownCodeBoxEvents()` 内部会自动调用这两个函数
+- `updateMarkdownCodeBlocksTheme()` 支持两种调用方式：
+  - 只传主题字符串：`updateMarkdownCodeBlocksTheme('dark')` - 更新 document.body 中的所有代码块
+  - 传容器和主题：`updateMarkdownCodeBlocksTheme(container, 'light')` - 更新指定容器内的代码块
+
+#### 绑定代码块工具栏事件（推荐）
+
+**`bindMarkdownCodeBoxEvents`** 用于处理代码块工具栏的交互事件（复制、主题切换、折叠）。
+
+##### 类型定义
+
+```typescript
+interface CodeBoxEventsConfig {
+  onCopySuccess?: (text: string) => void    // 复制成功回调
+  onCopyError?: (error: Error) => void      // 复制失败回调
+  onThemeChange?: (theme: CodeTheme) => void // 主题切换回调
+}
+
+// 函数重载
+function bindMarkdownCodeBoxEvents(): () => void
+function bindMarkdownCodeBoxEvents(config: CodeBoxEventsConfig): () => void
+function bindMarkdownCodeBoxEvents(container: HTMLElement | Document): () => void
+function bindMarkdownCodeBoxEvents(
+  container: HTMLElement | Document,
+  config: CodeBoxEventsConfig
+): () => void
+```
+
+##### 使用步骤
+
+**1. 不传参数（默认 document.body）**
+
+```typescript
+import { bindMarkdownCodeBoxEvents } from '@will1123/lx-ui-utils'
+
+const unbind = bindMarkdownCodeBoxEvents()
+
+// 组件销毁时解绑
+onUnmounted(() => unbind())
+```
+
+**2. 只传 config（默认 document.body）**
+
+```typescript
+const unbind = bindMarkdownCodeBoxEvents({
+  onCopySuccess: (text) => console.log('已复制:', text),
+  onCopyError: (error) => console.error('复制失败:', error),
+  onThemeChange: (theme) => console.log('主题切换为:', theme)
 })
+```
 
-// 逐步追加文本
-renderer.append('# 标题\n\n这是一段')
-renderer.append('**粗体**文字。')
-renderer.complete()
+**3. 只传 container（使用默认配置）**
+
+```typescript
+const container = document.querySelector('#markdown-container')
+const unbind = bindMarkdownCodeBoxEvents(container)
 ```
 
+**4. 传 container 和 config**
+
+```typescript
+const container = document.querySelector('#markdown-container')
+const unbind = bindMarkdownCodeBoxEvents(container, {
+  onCopySuccess: (text) => console.log('已复制:', text),
+  onThemeChange: (theme) => console.log('主题切换为:', theme)
+})
+```
+
+**5. Vue 组件完整示例**
+
+```vue
+<template>
+  <div>
+    <div v-html="html" class="markdown-content"></div>
+  </div>
+</template>
+
+<script>
+import { createMarkdownRender, bindMarkdownCodeBoxEvents } from '@will1123/lx-ui-utils'
+
+export default {
+  data() {
+    return {
+      renderer: null,
+      html: '',
+      unbindEvents: null
+    }
+  },
+  async mounted() {
+    // 创建渲染器
+    this.renderer = createMarkdownRender({
+      codeBoxToolEnable: true
+    })
+
+    // 渲染 Markdown
+    this.html = await this.renderer.parse(this.markdown)
+
+    // 绑定事件（只传 config，默认 container 为 document.body）
+    this.unbindEvents = bindMarkdownCodeBoxEvents({
+      onCopySuccess: (text) => {
+        this.$message.success('已复制到剪贴板')
+      },
+      onCopyError: (error) => {
+        this.$message.error('复制失败')
+      },
+      onThemeChange: (theme) => {
+        console.log('主题已切换为:', theme)
+        // 主题切换会自动更新所有代码块的 data-theme
+        // 无需重新渲染
+      }
+    })
+  },
+  beforeDestroy() {
+    // 清理：解绑事件
+    this.unbindEvents?.()
+  },
+  methods: {
+    async render() {
+      this.html = await this.renderer.parse(this.markdown)
+    }
+  }
+}
+</script>
+```
+
+##### 功能说明
+
+**1. 复制按钮**
+- 点击复制按钮自动复制代码到剪贴板
+- 内部使用 `copyToClipboard` 工具函数
+- 触发 `onCopySuccess` 或 `onCopyError` 回调
+
+**2. 主题切换按钮**
+- 点击主题按钮切换 dark/light 主题
+- **自动执行两步操作**：
+  1. 调用 `toggleMarkdownCodeTheme()` 切换 `localStorage` 中的主题
+  2. 调用 `updateMarkdownCodeBlocksTheme()` 更新指定容器内所有代码块的 `data-theme` 属性
+- **无需重新渲染** - 切换即时生效，性能更好
+- 触发 `onThemeChange` 回调
+- **容器隔离** - 只更新绑定容器内的代码块，不影响其他区域
+
+**3. 折叠按钮**
+- 点击折叠按钮展开/收起代码块
+- 纯前端操作，无需重新渲染
+
+##### 注意事项
+
+- 事件委托：使用事件委托，动态添加的代码块也会生效
+- 清理函数：返回的清理函数必须在组件销毁时调用，避免内存泄漏
+- 职责分离：
+  - `toggleMarkdownCodeTheme()` - 只负责切换 `localStorage` 中的主题
+  - `updateMarkdownCodeBlocksTheme()` - 只负责更新 DOM 中代码块的 `data-theme`
+  - `bindMarkdownCodeBoxEvents()` - 内部自动调用这两个函数完成完整流程
+- 函数重载：`bindMarkdownCodeBoxEvents()` 支持多种调用方式（不传参数、只传 config、只传 container、两个都传）
+- 容器隔离：指定 container 后，主题切换只影响该容器内的代码块，适合多实例场景
+- 兼容性：复制功能支持所有现代浏览器和 IE11+
+
+#### 生成的 HTML 结构
+
+**链接** - 自动添加 `target="_blank"`：
+```html
+<a target="_blank" href="...">链接文本</a>
+```
+
+**表格** - 包装在可滚动容器中：
+```html
+<div class="lx-ui-table-wrapper">
+  <div class="lx-ui-table-box">
+    <table>...</table>
+  </div>
+</div>
+```
+
+**代码块（启用工具栏）**：
+```html
+<div class="lx-ui-code-box-wrapper">
+  <div class="lx-ui-code-box" data-theme="dark">
+    <div class="lx-ui-code-box-header">
+      <div class="lx-ui-code-box-header-left">
+        <span class="lx-ui-code-language">javascript</span>
+        <i class="lx-ui-icon-fold"></i>
+      </div>
+      <div class="lx-ui-code-box-header-right">
+        <i class="lx-ui-icon-copy" title="复制"></i>
+        <i class="lx-ui-icon-theme" title="切换主题"></i>
+      </div>
+    </div>
+    <div class="lx-ui-code-box-content">
+      <pre><code class="hljs language-javascript">...</code></pre>
+    </div>
+  </div>
+</div>
+```
+
+**代码块（禁用工具栏）**：
+```html
+<div class="lx-ui-code-box-wrapper">
+  <div class="lx-ui-code-box" data-theme="dark">
+    <div class="lx-ui-code-box-header">
+      <div class="lx-ui-code-box-header-left">
+        <span class="lx-ui-code-language">javascript</span>
+      </div>
+    </div>
+    <div class="lx-ui-code-box-content">
+      <pre><code class="hljs language-javascript">...</code></pre>
+    </div>
+  </div>
+</div>
+```
+
+#### CSS 样式指南
+
+你需要自行实现以下 CSS 类的样式（所有类名都带 `lx-ui` 前缀以避免冲突）：
+
+```css
+/* 表格容器 */
+.lx-ui-table-wrapper {
+  overflow-x: auto;
+}
+
+.lx-ui-table-box {
+  /* 表格内层容器 */
+}
+
+/* 代码块容器 */
+.lx-ui-code-box-wrapper {
+  margin-bottom: 20px;
+}
+
+.lx-ui-code-box {
+  border-radius: 4px;
+  overflow: hidden;
+}
+
+/* 代码主题 */
+.lx-ui-code-box[data-theme="dark"] {
+  background: #1e1e1e;
+  color: #d4d4d4;
+}
+
+.lx-ui-code-box[data-theme="light"] {
+  background: #f5f5f5;
+  color: #333;
+}
+
+/* 代码块工具栏 */
+.lx-ui-code-box-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 8px 12px;
+}
+
+.lx-ui-code-box-header-left,
+.lx-ui-code-box-header-right {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.lx-ui-code-language {
+  font-size: 12px;
+  font-weight: 500;
+}
+
+.lx-ui-code-box-content {
+  padding: 12px;
+  overflow-x: auto;
+}
+
+/* 工具栏图标 */
+.lx-ui-icon-copy,
+.lx-ui-icon-theme,
+.lx-ui-icon-fold {
+  cursor: pointer;
+  opacity: 0.6;
+  transition: opacity 0.2s;
+}
+
+.lx-ui-icon-copy:hover,
+.lx-ui-icon-theme:hover,
+.lx-ui-icon-fold:hover {
+  opacity: 1;
+}
+
+/* KaTeX 公式样式（默认启用公式支持） */
+.lx-ui-katex-inline {
+  padding: 0 4px;
+  font-size: 1.05em;
+}
+
+.lx-ui-katex-block {
+  margin: 20px 0;
+  padding: 15px;
+  overflow-x: auto;
+  text-align: center;
+  background: #f5f7fa;
+  border-radius: 4px;
+}
+```
+
+#### 完整示例
+
+```vue
+<template>
+  <div class="markdown-content" v-html="html"></div>
+</template>
+
+<script>
+import { createMarkdownRender } from '@will1123/lx-ui-utils'
+import 'highlight.js/styles/base16/outrun-dark.min.css'
+import 'katex/dist/katex.min.css'
+
+export default {
+  data() {
+    return {
+      renderer: null,
+      html: ''
+    }
+  },
+  async mounted() {
+    // 创建渲染器（启用 KaTeX 公式支持）
+    this.renderer = createMarkdownRender({
+      codeBoxToolEnable: true,
+      katexEnable: true
+    })
+
+    // 渲染 Markdown
+    const markdown = `# Hello World\n\n\`\`\`javascript\nconsole.log('Hello')\n\`\`\``
+    this.html = await this.renderer.parse(markdown)
+  }
+}
+</script>
+
+<style scoped>
+/* 实现样式 */
+.markdown-content :deep(.lx-ui-code-box) {
+  background: #1e1e1e;
+  border-radius: 4px;
+}
+
+.markdown-content :deep(.lx-ui-code-box-header) {
+  display: flex;
+  justify-content: space-between;
+  padding: 8px 12px;
+  background: rgba(255, 255, 255, 0.05);
+}
+
+.markdown-content :deep(.lx-ui-icon-copy) {
+  cursor: pointer;
+  opacity: 0.7;
+}
+
+.markdown-content :deep(.lx-ui-icon-copy:hover) {
+  opacity: 1;
+}
+</style>
+```
+
+## 核心优势
+
+### SSE 功能
+
+- ✅ **简洁 API** - 默认 POST 请求，内置 Token 认证支持
+- ✅ **页面可见性** - 自动处理页面隐藏/显示（Page Visibility API）
+- ✅ **自动解析** - 无需手动解析 SSE 消息格式
+- ✅ **生产级** - 基于 Microsoft 维护的 `@microsoft/fetch-event-source`
+- ✅ **代码精简** - 相比手动实现减少 70% 代码量
+
+### 深度思考提取
+
+- ✅ **灵活解析** - 支持完整标签和仅结束标签两种模式
+- ✅ **类型安全** - 完整的 TypeScript 类型定义
+- ✅ **简洁 API** - 一个函数完成所有解析逻辑
+
+### Markdown 渲染
+
+- ✅ **增强功能** - 链接自动新窗口、表格可滚动、代码块工具栏
+- ✅ **主题系统** - dark/light 主题切换，基于 localStorage 持久化
+- ✅ **代码高亮** - 集成 highlight.js，支持 190+ 语言
+- ✅ **标准兼容** - 基于 Marked.js，99% CommonMark 兼容
+- ✅ **GFM 支持** - 表格、任务列表、删除线等
+- ✅ **类名安全** - 所有生成的类名带 `lx-ui` 前缀，避免冲突
+- ✅ **按需样式** - 不提供 CSS 文件，用户自行实现样式
+- ✅ **KaTeX 公式** - 支持 LaTeX 数学公式渲染（可选）
+
+### Helper Functions
+
+通用工具函数，可在任何场景使用。
+
+#### 复制到剪贴板
+
+**`copyToClipboard`** 是一个通用的复制文本到剪贴板的工具函数。
+
+##### 类型定义
+
+```typescript
+function copyToClipboard(text: string): Promise<boolean>
+```
+
+##### 使用示例
+
+```typescript
+import { copyToClipboard } from '@will1123/lx-ui-utils'
+
+// 基础用法
+const success = await copyToClipboard('Hello World')
+if (success) {
+  console.log('复制成功')
+} else {
+  console.log('复制失败')
+}
+
+// 复制代码
+const code = 'console.log("Hello World")'
+await copyToClipboard(code)
+
+// 复制 HTML 内容
+const html = '<div>Hello</div>'
+await copyToClipboard(html)
+```
+
+##### 特性
+
+- ✅ **现代 API** - 优先使用 Clipboard API
+- ✅ **自动降级** - 不支持时自动降级到 `document.execCommand`
+- ✅ **SSR 安全** - 服务端渲染环境自动返回 false
+- ✅ **返回值** - 返回 Promise<boolean>，成功返回 true，失败返回 false
+- ✅ **兼容性好** - 支持所有主流浏览器（包括 IE11+）
+- ✅ **通用性** - 可在任何场景使用，不限于 Markdown
+
+#### 判断 DOM 元素
+
+**`isDom`** 用于判断值是否为 DOM 元素（HTMLElement 或 Document）。
+
+##### 类型定义
+
+```typescript
+function isDom(val: unknown): val is HTMLElement | Document
+```
+
+##### 使用示例
+
+```typescript
+import { isDom } from '@will1123/lx-ui-utils'
+
+// 判断各种值
+isDom(document.body)        // true
+isDom(document)             // true
+isDom(document.querySelector('div'))  // true (如果找到元素)
+
+isDom({})                  // false
+isDom('div')               // false
+isDom(null)                // false
+isDom(undefined)           // false
+isDom(123)                 // false
+
+// 在函数重载中使用
+function processInput(input: unknown) {
+  if (isDom(input)) {
+    // input 在这里被识别为 HTMLElement | Document
+    input.addEventListener('click', handler)
+  } else {
+    console.log('不是 DOM 元素')
+  }
+}
+```
+
+##### 特性
+
+- ✅ **类型守卫** - TypeScript 类型守卫，可缩小类型范围
+- ✅ **精确判断** - 使用 `instanceof` 判断，支持所有 DOM 元素
+- ✅ **SSR 安全** - 服务端渲染环境也能正常工作
+- ✅ **辅助开发** - 常用于函数重载、参数验证等场景
+
 ## 构建
 
 ```bash
@@ -226,7 +853,7 @@ renderer.complete()
 yarn install
 
 # 构建 utils 包
-yarn workspace @lx-ui/utils build
+yarn workspace @will1123/lx-ui-utils build
 ```
 
 ## 许可证