sg-paisou 0.2.5 → 0.2.7

package/README.md

@@ -1,2 +1,712 @@
-# SG-paisou-web
+# SG Paisou Web - AI 聊天 SDK
 
+一个功能完整的 Vue 3 AI 聊天组件 SDK，专为教育场景设计，支持数学公式渲染、流式消息、语音交互、思考动画等高级功能。
+
+## 📋 目录
+
+- [项目简介](#项目简介)
+- [功能特性](#功能特性)
+- [快速开始](#快速开始)
+- [安装](#安装)
+- [基础使用](#基础使用)
+- [配置说明](#配置说明)
+- [API 文档](#api-文档)
+- [组件说明](#组件说明)
+- [高级功能](#高级功能)
+- [开发指南](#开发指南)
+- [常见问题](#常见问题)
+
+## 🎯 项目简介
+
+SG Paisou Web 是一个基于 Vue 3 的 AI 聊天 SDK，主要用于教育场景中的智能问答和题目讲解。该 SDK 提供了完整的聊天界面、流式消息处理、数学公式渲染、语音交互、思考动画等功能，可以快速集成到现有项目中。
+
+### 核心特点
+
+- 🎨 **高度可定制**：支持自定义样式、图标、文本等
+- 📱 **响应式设计**：完美适配移动端和桌面端
+- 🧮 **数学公式支持**：基于 MathJax 的 LaTeX 公式渲染
+- 🎤 **语音交互**：支持语音输入和 TTS 语音播放
+- 💬 **流式消息**：实时流式消息接收和显示
+- 🎭 **思考动画**：Thinkie 思考动画，提升用户体验
+- 📊 **数据埋点**：完整的数据统计和埋点支持
+
+## ✨ 功能特性
+
+### 1. 聊天功能
+
+- ✅ 实时流式消息接收和显示
+- ✅ 消息类型：AI 消息、用户消息
+- ✅ 消息状态：发送中、成功、失败
+- ✅ 网络错误处理和重试机制
+- ✅ 消息长按反馈功能
+- ✅ 消息滚动到底部
+
+### 2. 数学公式渲染
+
+- ✅ 支持 LaTeX 数学公式（`$...$` 和 `$$...$$`）
+- ✅ 支持行内公式和块级公式
+- ✅ 自动处理货币符号（如 `$45`）
+- ✅ 支持特殊字符转义（如 `\%`、`\$`）
+- ✅ 基于 MathJax 的高质量渲染
+
+### 3. 思考动画（Thinkie is thinking...）
+
+- ✅ 7 组随机思考文案
+- ✅ 打字机效果逐行显示
+- ✅ 涟漪动画效果
+- ✅ 与流式消息同步处理
+- ✅ 平滑的收起动画
+
+### 4. 语音功能
+
+- ✅ 语音输入（语音转文字）
+- ✅ TTS 语音播放
+- ✅ 音量控制（静音/取消静音）
+- ✅ 录音倒计时
+- ✅ 语音处理状态提示
+
+### 5. 反馈功能
+
+- ✅ 消息反馈（点赞/踩）
+- ✅ 整体反馈
+- ✅ 反馈弹窗
+- ✅ 反馈状态持久化
+
+### 6. 历史记录
+
+- ✅ 历史消息加载
+- ✅ 历史会话恢复
+- ✅ 7 天限制处理
+- ✅ 历史记录状态管理
+
+### 7. 特殊功能
+
+- ✅ 特殊题目处理
+- ✅ 追问功能
+- ✅ 继续讲解功能
+- ✅ 再次讲解功能
+- ✅ 快捷回复
+- ✅ 内容安全检测
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+# 使用 npm
+npm install @genie/sg-paisou-sdk
+
+# 使用 pnpm
+pnpm add @genie/sg-paisou-sdk
+
+# 使用 yarn
+yarn add @genie/sg-paisou-sdk
+```
+
+### 基础使用
+
+```vue
+<template>
+  <AIChatComponent
+    :questionInfo="questionInfo"
+    :config="chatConfig"
+    @messageSend="handleMessageSend"
+    @feedback="handleFeedback"
+  />
+</template>
+
+<script setup>
+import { AIChatComponent } from '@genie/sg-paisou-sdk'
+import '@genie/sg-paisou-sdk/style.css'
+
+const questionInfo = {
+  questionId: '123',
+  sessionId: 'session_123',
+  content: '问题内容',
+  imagePath: 'https://example.com/image.jpg'
+}
+
+const chatConfig = {
+  aiInfo: {
+    name: 'Thinkie',
+    title: 'AI Tutor'
+  }
+}
+
+const handleMessageSend = (eventType, eventData) => {
+  console.log('Message sent:', eventType, eventData)
+}
+
+const handleFeedback = (feedbackId) => {
+  console.log('Feedback:', feedbackId)
+}
+</script>
+```
+
+## ⚙️ 配置说明
+
+### 完整配置示例
+
+```typescript
+import { IAIChatConfig } from '@genie/sg-paisou-sdk'
+
+const config: IAIChatConfig = {
+  // AI 头像配置
+  avatar: {
+    src: 'https://example.com/avatar.png',
+    alt: 'AI Avatar',
+    width: '40px',
+    height: '40px',
+    borderRadius: '50%'
+  },
+
+  // 用户头像配置
+  userAvatar: {
+    src: 'https://example.com/user-avatar.png',
+    alt: 'User Avatar',
+    width: '40px',
+    height: '40px',
+    borderRadius: '50%'
+  },
+
+  // AI 信息配置
+  aiInfo: {
+    name: 'Thinkie',
+    title: 'AI Tutor',
+    nameStyle: {
+      color: '#222222',
+      fontSize: '16px',
+      fontWeight: '600'
+    },
+    titleStyle: {
+      color: '#666666',
+      fontSize: '14px'
+    }
+  },
+
+  // 静音按钮配置
+  muteButton: {
+    soundOnIcon: 'https://example.com/sound-on.png',
+    soundOffIcon: 'https://example.com/sound-off.png',
+    width: '24px',
+    height: '24px',
+    onClick: (isSoundOn) => {
+      console.log('Sound toggled:', isSoundOn)
+    }
+  },
+
+  // 输入框配置
+  input: {
+    placeholder: 'Type your message...',
+    sendIcon: 'https://example.com/send-icon.png',
+    sendIconWidth: '24px',
+    sendIconHeight: '24px',
+    borderRadius: '20px',
+    padding: '8px 16px',
+    onSend: (message) => {
+      console.log('Message sent:', message)
+    }
+  },
+
+  // 样式配置
+  styles: {
+    container: {
+      background: '#ffffff',
+      borderRadius: '12px'
+    },
+    header: {
+      padding: '16px',
+      borderBottom: '1px solid #e5e5e5'
+    },
+    chatContent: {
+      height: '500px',
+      padding: '20px'
+    },
+    messages: {
+      aiMessage: {
+        background: '#f5f5f5',
+        color: '#222222',
+        borderRadius: '12px',
+        padding: '12px 16px'
+      },
+      userMessage: {
+        background: '#007AFF',
+        color: '#ffffff',
+        borderRadius: '12px',
+        padding: '12px 16px'
+      },
+      messageGap: '16px'
+    },
+    inputContainer: {
+      padding: '16px',
+      background: '#ffffff'
+    }
+  },
+
+  // 反馈按钮配置
+  feedback: {
+    buttons: [
+      {
+        id: 'helpful',
+        text: 'Helpful',
+        icon: 'https://example.com/helpful-icon.png'
+      },
+      {
+        id: 'not-helpful',
+        text: 'Not Helpful',
+        icon: 'https://example.com/not-helpful-icon.png'
+      }
+    ],
+    containerStyle: {
+      padding: '12px 0',
+      gap: '12px'
+    },
+    show: true
+  },
+
+  // 按钮配置
+  buttons: {
+    startExplaining: {
+      text: 'Start Explaining',
+      className: 'btn-primary',
+      style: {
+        background: 'linear-gradient(91.95deg, #FFCB00 0%, #FFAB03 100%)',
+        color: '#FFFFFF'
+      }
+    },
+    continue: {
+      text: 'Continue',
+      className: 'btn-continue',
+      style: {
+        background: 'transparent',
+        color: '#007AFF'
+      }
+    },
+    snapAnother: {
+      text: 'Snap Another',
+      icon: 'https://example.com/camera-icon.png',
+      className: 'btn-snap',
+      style: {
+        background: '#f5f5f5',
+        color: '#222222'
+      }
+    }
+  },
+
+  // 文本配置（国际化）
+  texts: {
+    notMyQuestion: "This isn't my question",
+    startExplaining: 'Start Explaining',
+    continue: 'Continue',
+    wasThisHelpful: 'Was this helpful?',
+    snapAnother: 'Snap Another',
+    explainAgain: 'Explain Again'
+  },
+
+  // 自定义 CSS 类名
+  customClasses: {
+    container: 'my-chat-container',
+    header: 'my-chat-header',
+    chatContent: 'my-chat-content',
+    inputContainer: 'my-input-container'
+  }
+}
+```
+
+## 📚 API 文档
+
+### Props
+
+#### `questionInfo` (Object, 可选)
+
+问题信息对象，包含以下字段：
+
+```typescript
+interface QuestionInfo {
+  questionId?: string        // 问题ID
+  question_id?: string      // 问题ID（兼容字段）
+  sessionId?: string        // 会话ID
+  session_id?: string       // 会话ID（兼容字段）
+  content?: string          // 问题内容
+  imagePath?: string        // 问题图片路径
+  image_path?: string       // 问题图片路径（兼容字段）
+  question_type?: number    // 问题类型：0-不可解，1-特殊题，2-普通题
+  pkgName?: string          // 包名：'SGpaisou' 或其他
+  historyType?: boolean     // 是否为历史记录
+  isOverSevenDays?: number  // 是否超过7天：0-否，1-是
+  favorite?: boolean        // 是否收藏
+  vote?: 'upvote' | 'downvote' | null  // 反馈状态
+  avatar?: string           // 用户头像
+  // ... 其他字段
+}
+```
+
+#### `config` (IAIChatConfig, 可选)
+
+聊天组件配置对象，详见 [配置说明](#配置说明)。
+
+### Events
+
+#### `messageSend`
+
+消息发送事件，包含以下事件类型：
+
+```typescript
+// 事件类型
+type MessageEventType = 
+  | 'voice'           // 语音事件：'start' | 'stop'
+  | 'dataCollection'  // 数据埋点
+  | 'sessionUpdated'  // 会话更新
+  | 'questionData'    // 问题数据
+  | 'historyLoading'  // 历史加载
+  | 'shouldShowRecording'  // 是否显示录音
+  | 'explainAgain'    // 再次讲解
+
+// 使用示例
+@messageSend="handleMessageSend"
+
+const handleMessageSend = (eventType: string, eventData: any) => {
+  switch (eventType) {
+    case 'voice':
+      if (eventData === 'start') {
+        // 开始录音
+      } else if (eventData === 'stop') {
+        // 停止录音
+      }
+      break
+    case 'dataCollection':
+      // 处理埋点数据
+      console.log('Tracking:', eventData)
+      break
+    case 'sessionUpdated':
+      // 处理会话更新
+      console.log('Session updated:', eventData)
+      break
+  }
+}
+```
+
+#### `feedback`
+
+反馈事件：
+
+```typescript
+@feedback="handleFeedback"
+
+const handleFeedback = (feedbackId: string) => {
+  console.log('Feedback ID:', feedbackId)
+}
+```
+
+#### `muteToggle`
+
+静音切换事件：
+
+```typescript
+@muteToggle="handleMuteToggle"
+
+const handleMuteToggle = (isMuted: boolean) => {
+  console.log('Muted:', isMuted)
+}
+```
+
+#### `snap-another`
+
+拍照另一个事件：
+
+```typescript
+@snap-another="handleSnapAnother"
+
+const handleSnapAnother = () => {
+  console.log('Snap another question')
+}
+```
+
+#### `session-updated`
+
+会话更新事件：
+
+```typescript
+@session-updated="handleSessionUpdated"
+
+const handleSessionUpdated = (data: any) => {
+  console.log('Session updated:', data)
+}
+```
+
+#### `tracking`
+
+数据埋点事件：
+
+```typescript
+@tracking="handleTracking"
+
+const handleTracking = (data: any) => {
+  console.log('Tracking data:', data)
+  // 发送到数据统计平台
+}
+```
+
+#### `question-data-updated`
+
+问题数据更新事件：
+
+```typescript
+@question-data-updated="handleQuestionDataUpdated"
+
+const handleQuestionDataUpdated = (data: {
+  questionText: string
+  questionImage: string
+  questionId: string
+}) => {
+  console.log('Question data updated:', data)
+}
+```
+
+### Methods (通过 ref 调用)
+
+```vue
+<template>
+  <AIChatComponent ref="aiChatRef" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const aiChatRef = ref()
+
+// 添加消息
+aiChatRef.value.addMessage({
+  id: 'msg_1',
+  type: 'ai',
+  content: 'Hello!',
+  timestamp: Date.now()
+})
+
+// 添加 AI 消息
+aiChatRef.value.addAIMessage('This is an AI message')
+
+// 添加用户消息
+aiChatRef.value.addUserMessage('This is a user message')
+
+// 清空消息
+aiChatRef.value.clearMessages()
+
+// 滚动到底部
+aiChatRef.value.scrollToBottom()
+
+// 处理语音数据
+aiChatRef.value.handleVoiceData({
+  content: '语音转文字结果'
+})
+
+// 取消录音
+aiChatRef.value.cancelVoiceRecord()
+
+// 开始讲解
+aiChatRef.value.handleStartExplaining('message_id')
+
+// 静音控制
+aiChatRef.value.handleMuteToggle(true)  // 静音
+aiChatRef.value.handleMuteToggle(false) // 取消静音
+
+// 清理 TTS 资源
+aiChatRef.value.clearTTSResources()
+
+// 销毁 TTS 播放器
+aiChatRef.value.destroyTTS()
+</script>
+```
+
+## 🧩 组件说明
+
+### AIChatComponent
+
+主要的聊天组件，包含以下子组件：
+
+- **Loading**: 加载状态组件
+- **FeedbackButtons**: 反馈按钮组件
+- **SpecialQuestions**: 特殊题目组件
+- **Dialogs**: 对话框组件
+- **ImagePreview**: 图片预览组件
+
+### Composables
+
+SDK 使用多个 Composables 来组织代码：
+
+- `useMessageHandler`: 消息管理
+- `useStreamHandler`: 流式消息处理
+- `useFeedbackHandler`: 反馈处理
+- `useHistoryHandler`: 历史记录处理
+- `useTypewriter`: 打字机效果
+- `useQuestionFlow`: 问题流程处理
+- `useMessageCleanup`: 消息清理
+- `useThinkingFlow`: 思考动画处理
+- `useKeyboardHandler`: 键盘处理
+
+## 🎨 高级功能
+
+### 1. 思考动画（Thinkie is thinking...）
+
+当用户点击 "Start Explaining" 或 "Explain Again" 时，会显示 Thinkie 思考动画：
+
+```typescript
+// 思考动画会自动启动，包含以下特性：
+// - 7 组随机思考文案
+// - 打字机效果逐行显示
+// - 涟漪动画效果
+// - 与流式消息同步处理
+// - 平滑的收起动画
+```
+
+### 2. 数学公式渲染
+
+支持多种数学公式格式：
+
+```markdown
+# 行内公式
+这是行内公式：$x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$
+
+# 块级公式
+$$
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+$$
+
+# 货币符号（自动识别）
+价格是 $45，不是数学公式
+
+# 数学公式中的货币
+$$\\$ {23}$$ 会被渲染为 $23
+```
+
+### 3. 流式消息处理
+
+支持实时流式消息接收：
+
+```typescript
+// 流式消息会自动处理，包括：
+// - 实时内容更新
+// - TTS 语音播放
+// - 错误处理和重试
+// - 网络断开检测
+```
+
+### 4. 内容安全检测
+
+发送消息前会自动进行内容安全检测：
+
+```typescript
+// 如果内容不安全，会：
+// - 删除用户消息
+// - 显示安全警告弹窗
+// - 阻止消息发送
+```
+
+## 🛠️ 开发指南
+
+### 本地开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 启动开发服务器
+pnpm dev
+
+# 构建库
+pnpm build:lib
+
+# 构建类型定义
+pnpm build:types
+```
+
+### 项目结构
+
+```
+src/
+├── components/
+│   └── AIChatSDK/          # AI 聊天 SDK 核心代码
+│       ├── AIChatComponent.vue  # 主组件
+│       ├── component/          # 子组件
+│       ├── composables/         # 组合式函数
+│       ├── utils/                # 工具函数
+│       ├── types.ts              # 类型定义
+│       └── style.scss            # 样式文件
+├── utils/
+│   ├── render.ts           # 内容渲染（数学公式、Markdown）
+│   ├── request.ts          # API 请求
+│   ├── tts.ts              # TTS 语音播放
+│   ├── useSSE.ts           # SSE 流式消息
+│   └── bridge.ts           # 客户端桥接
+├── views/
+│   └── QuestionChatPage/   # 问题聊天页面
+└── store/
+    └── useAppStore.ts      # 状态管理
+```
+
+### 类型定义
+
+所有类型定义都在 `src/components/AIChatSDK/types.ts` 中，主要类型包括：
+
+- `IAIChatConfig`: 完整配置类型
+- `IMessage`: 消息类型
+- `IAvatarConfig`: 头像配置
+- `IAIInfoConfig`: AI 信息配置
+- `IInputConfig`: 输入框配置
+- `IStyleConfig`: 样式配置
+- 等等...
+
+## ❓ 常见问题
+
+### 1. 如何自定义样式？
+
+可以通过 `config.styles` 配置自定义样式，或者使用 `customClasses` 添加自定义 CSS 类名。
+
+### 2. 如何处理数学公式？
+
+数学公式会自动渲染，支持 `$...$`（行内）和 `$$...$$`（块级）格式。货币符号（如 `$45`）会自动识别并保留。
+
+### 3. 如何集成语音功能？
+
+语音功能需要客户端支持，通过 `bridge.ts` 与客户端通信。确保客户端实现了相应的桥接方法。
+
+### 4. 如何自定义思考文案？
+
+思考文案在 `src/components/AIChatSDK/composables/useThinkingFlow.ts` 中的 `THINKING_OPTIONS` 数组中定义，可以修改或添加新的文案组。
+
+### 5. 如何处理网络错误？
+
+网络错误会自动处理，显示错误消息和重试按钮。可以通过 `retryStreamMessage` 方法手动重试。
+
+### 6. 如何自定义埋点？
+
+埋点通过 `@tracking` 事件发送，可以在父组件中接收并发送到数据统计平台。
+
+## 📝 更新日志
+
+### v0.0.1
+
+- ✅ 初始版本发布
+- ✅ 基础聊天功能
+- ✅ 流式消息处理
+- ✅ 数学公式渲染
+- ✅ 思考动画功能
+- ✅ 语音交互支持
+- ✅ 反馈功能
+- ✅ 历史记录支持
+
+## 📄 许可证
+
+ISC
+
+## 👥 作者
+
+- **wuxiaoqiang** - v_wuxiaoqiang@tal.com
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+---
+
+**注意**：本项目需要 Vue 3.4.0+ 和相应的客户端桥接支持。