npm package: @puyouhui/ty-plugin
Description: 一个功能强大的Vue3 AI助手插件，支持知识问答、报告生成、数据分析和智能导航等功能
Author: Youhui Pu
Latest version: 1.0.58

# TY-Plugin AI助手插件

一个功能强大的Vue3 AI助手插件，支持知识问答、报告生成、数据分析和智能导航等功能。

## 功能特点

- 💬 **知识问答**：基于DeepSeek知识库，提供准确、专业的问题解答
- 📊 **报告生成**：支持数据导入和AI辅助报告生成与分析
- 📈 **数据分析**（Plus版本）：连接系统数据库，分析数据指标和趋势
- 🧭 **智能导航**（Plus版本）：智能引导用户找到所需功能

## 安装

```bash
npm install @puyouhui/ty-plugin
```

## 基础使用

### 方式1：在Vue应用中初始化

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import TyPlugin from '@puyouhui/ty-plugin'

const app = createApp(App)
app.use(TyPlugin, {
  baseUrl: 'YOUR_BASE_URL',
  apiKey: 'YOUR_API_KEY'
})
app.mount('#app')
```

### 方式2：在组件中初始化

```javascript
import { getCurrentInstance } from 'vue'

export default {
  setup() {
    const { proxy } = getCurrentInstance()
    proxy.$tyAi.init('YOUR_BASE_URL', 'YOUR_API_KEY')
  }
}
```

### 方式3：直接导入初始化

```javascript
import { init } from '@puyouhui/ty-plugin'

init('YOUR_BASE_URL', 'YOUR_API_KEY')
```

## Plus版本功能

Plus版本提供额外的数据分析和智能导航功能。要启用Plus版本，需要在初始化时提供额外的配置：

```javascript
app.use(TyPlugin, {
  baseUrl: 'YOUR_BASE_URL',
  apiKey: 'YOUR_API_KEY',
  isPlus: true,
  dataAnalysisConfig: {
    matchingTablesUrl: 'http://your-domain/api/data/matching-tables', // 数据表匹配接口
    generateQueryUrl: 'http://your-domain/api/data/generate-query',   // SQL生成接口
    executeQueryUrl: 'http://your-domain/api/data/execute-query'      // SQL执行接口
  },
  navigationConfig: {
    navigationUrl: 'http://your-domain/api/navigation'  // 导航接口
  }
})
```

## 配置选项

### 基础配置

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| baseUrl | string | 是 | API基础地址 |
| apiKey | string | 是 | API认证密钥 |
| isPlus | boolean | 否 | 是否启用Plus版本功能 |

### 外观配置

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| backgroundImage | string | 否 | 背景图片URL |
| backgroundColor | string | 否 | 背景颜色 |
| backgroundGradient | string | 否 | 背景渐变色 |
| backgroundOpacity | number | 否 | 背景透明度(0-1) |

### Plus版本配置

#### dataAnalysisConfig

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| matchingTablesUrl | string | 是 | 数据表匹配接口地址 |
| generateQueryUrl | string | 是 | SQL查询生成接口地址 |
| executeQueryUrl | string | 是 | SQL执行接口地址 |

#### navigationConfig

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| navigationUrl | string | 是 | 智能导航接口地址 |

## API接口说明

### 数据分析接口

1. **数据表匹配接口**
```javascript
POST /api/data/matching-tables
请求体: { question: string }
响应: { 
  code: number,
  data: { 
    tableName: string,
    description: string 
  }
}
```

2. **SQL查询生成接口**
```javascript
POST /api/data/generate-query
请求体: { 
  question: string,
  tableName: string 
}
响应: {
  code: number,
  data: {
    sql: string,
    description: string
  }
}
```

3. **SQL执行接口**
```javascript
POST /api/data/execute-query
请求体: {
  question: string,
  sql: string
}
响应: {
  code: number,
  data: Array<any>
}
```

### 智能导航接口

```javascript
POST /api/navigation
请求体: { question: string }
响应: {
  code: number,
  data: {
    path: string,
    title: string
  }
}
```

## 事件处理

### 导航事件

```javascript
<template>
  <ty-ai @navigationClick="handleNavigation"/>
</template>

<script setup>
const handleNavigation = ({ path, title }) => {
  // 处理导航事件
  console.log('导航到:', path, title)
}
</script>
```

## 错误处理

插件会在初始化配置不完整时显示错误提示，但不会阻止组件渲染。您可以通过以下方式获取错误信息：

```javascript
import { chatService } from '@puyouhui/ty-plugin'

const error = chatService.getInitError()
if (error) {
  console.warn('初始化警告:', error)
}
```

## 注意事项

1. Plus版本功能需要提供完整的配置信息才能正常使用
2. 所有API接口都需要返回统一的数据格式，包含 code 和 data 字段
3. 建议在生产环境中使用HTTPS协议的API地址

## 技术支持

由云南腾亿创新互联网有限公司提供技术支持

## 版本信息

当前版本已全面接入DeepSeek，提供更强大的AI能力支持

## 安装

```bash
npm install @puyouhui/ty-plugin --save
# 或
yarn add @puyouhui/ty-plugin
```

### 解决依赖冲突问题

如果安装过程中遇到依赖冲突错误（ERESOLVE），您可以使用以下方法解决：

方法1: 使用特殊安装标志
```bash
# npm方式
npm install @puyouhui/ty-plugin --save --legacy-peer-deps

# yarn方式
yarn add @puyouhui/ty-plugin --ignore-peer-dependencies
```

方法2: 先将项目的Vite版本调整为兼容版本
```bash
# 如果使用 @vitejs/plugin-vue@5.x，请先安装兼容的vite版本
npm install vite@5.x --save-dev
npm install @puyouhui/ty-plugin --save
```

方法3: 使用nvm管理不同版本的Node环境
```bash
# 推荐使用Node 18.x版本
nvm use 18
npm install @puyouhui/ty-plugin --save
```

## 使用方法

### 1. 初始化插件（必须）

插件使用前必须进行初始化，提供BASE_URL和API_KEY。有以下三种初始化方式：

#### 方法1: 在Vue应用中初始化

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import TyPlugin from '@puyouhui/ty-plugin'

const app = createApp(App)
app.use(TyPlugin, {
  baseUrl: 'YOUR_BASE_URL',
  apiKey: 'YOUR_API_KEY',
  // 背景配置选项（可选）
  backgroundImage: 'https://example.com/your-image.jpg', // 背景图片URL
  backgroundColor: '#f5f5f5', // 纯色背景
  backgroundGradient: 'linear-gradient(45deg, #ff9a9e, #fad0c4)', // CSS渐变背景
  backgroundOpacity: 0.9 // 背景透明度（0-1之间）
})
app.mount('#app')
```

#### 方法2: 在组件中初始化

```javascript
import { getCurrentInstance } from 'vue'

export default {
  setup() {
    const { proxy } = getCurrentInstance()
    proxy.$tyAi.init('YOUR_BASE_URL', 'YOUR_API_KEY', {
      // 背景配置选项（可选）
      backgroundImage: 'https://example.com/your-image.jpg', // 背景图片URL
      backgroundColor: '#f5f5f5', // 纯色背景
      backgroundGradient: 'linear-gradient(45deg, #ff9a9e, #fad0c4)', // CSS渐变背景
      backgroundOpacity: 0.9 // 背景透明度（0-1之间）
    })
  }
}
```

#### 方法3: 直接导入初始化

```javascript
import { init } from '@puyouhui/ty-plugin'

init('YOUR_BASE_URL', 'YOUR_API_KEY', {
  // 背景配置选项（可选）
  backgroundImage: 'https://example.com/your-image.jpg', // 背景图片URL
  backgroundColor: '#f5f5f5', // 纯色背景
  backgroundGradient: 'linear-gradient(45deg, #ff9a9e, #fad0c4)', // CSS渐变背景
  backgroundOpacity: 0.9 // 背景透明度（0-1之间）
})
```

### 背景配置优先级

背景配置的应用优先级如下：
1. 背景图片（backgroundImage）- 如果提供，将覆盖其他背景设置
2. 渐变背景（backgroundGradient）- 如果没有背景图片但提供了渐变，将使用渐变背景
3. 纯色背景（backgroundColor）- 如果没有背景图片和渐变，将使用纯色背景
4. 默认背景 - 如果没有提供任何背景配置，将使用默认的渐变背景

### 2. 在模板中使用

```vue
<template>
  <main-ai />
</template>
```

### 3. 直接调起聊天界面

您可以使用以下方法直接调起聊天界面并发送消息，无需用户输入：

```javascript
// 方法1: 使用全局方法
this.$tyAi.startChat('您好，我需要生成一份报告')

// 方法2: 直接导入方法
import { startChat } from '@puyouhui/ty-plugin'

startChat('您好，我需要生成一份报告')
```

这个方法会自动切换到聊天界面，并立即发送指定的消息，就像用户手动输入并发送一样。

#### 使用隐藏消息参数

您还可以使用隐藏消息参数，这个参数会与显示消息一起发送给服务器，但不会显示给用户：

```javascript
// 第一个参数是显示给用户的消息，第二个参数是隐藏的消息（只发送给服务器）
this.$tyAi.startChat('请生成一份简单报告', '使用专业术语，内容详尽')

// 或者使用导入的方法
startChat('请分析最近的数据趋势', '使用图表和详细分析，语言专业')
```

隐藏消息参数可以用于：
- 向AI提供额外的指令或上下文
- 设置特定的输出格式或风格要求
- 传递不希望用户看到的系统提示或配置信息

### 4. 高级组件实例方法

如果您需要直接访问组件实例提供的方法，可以使用以下方式：

```javascript
// 使用组件实例发送带有隐藏消息的对话
const { proxy } = getCurrentInstance()
proxy.$tyAi.getInstance().startChatWithMessage('可见消息', '隐藏消息')

// 或者获取组件引用后直接调用
<main-ai ref="aiComponentRef" />

// 在方法中使用
this.$refs.aiComponentRef.startChatWithMessage('可见消息', '隐藏消息')
```

## 处理流程状态提示

聊天助手会根据不同的处理阶段显示不同的状态提示，帮助用户了解当前处理进度：

- 工作流开始阶段 - 显示"正在思考..."
- 问题分类阶段 - 显示"助手正在将您的问题分类..."
- 问题分类完成 - 显示"问题分类已完成"
- 回答生成阶段 - 实时显示AI的思考过程

这些状态提示使对话过程更加透明，提升用户体验。

## 错误处理与稳定性

插件内置了强大的错误处理机制，确保在网络不稳定或服务器返回异常数据时仍能正常工作：

- 自动处理JSON解析错误，防止因数据流截断导致的解析失败
- 防止加载状态异常，确保加载动画正确显示和隐藏
- 智能重试机制，提高连接稳定性
- 详细的错误日志，方便调试和问题排查

## 组件属性

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| welcomeMessage | String | 'Hi, 我是您的AI助手' | 自定义欢迎语 |
| theme | String | 'light' | 主题样式，支持 'light' 和 'dark' |
| placeholder | String | '请告诉我您需要帮助的事情' | 输入框占位文本 |
| quickActions | Array | [] | 快捷操作列表，每项包含text(问题文本)和type(问题类型) |
| historyEnabled | Boolean | true | 是否启用历史记录功能 |

### quickActions 属性说明

quickActions 数组中的每个对象应包含以下属性：

```javascript
{
  text: string;  // 问题文本
  type: string;  // 问题类型，如："数据分析"、"功能导航"等
}
```

使用示例：

```vue
<template>
  <main-ai
    welcomeMessage="您好，我是AI助手"
    :quickActions="[
      {
        text: '帮我分析本月销售数据',
        type: '数据分析'
      },
      {
        text: '如何设置用户权限？',
        type: '功能导航'
      },
      {
        text: '生成周报模板',
        type: '报告生成'
      }
    ]"
  />
</template>
```

### 快捷操作类型说明

快捷操作支持以下类型：

1. **数据分析** - 用于数据查询和分析相关的问题
2. **功能导航** - 用于系统功能查找和导航
3. **知识解答** - 用于普通问答和知识查询
4. **报告生成** - 用于生成各类报告和文档

每种类型会触发不同的处理逻辑：
- 数据分析类型：调用数据分析接口进行处理
- 功能导航类型：调用导航接口进行处理
- 知识解答和报告生成：使用基础对话功能处理

### 动态更新快捷操作

您可以根据需要动态更新快捷操作列表：

```vue
<script setup>
import { ref } from 'vue'

const quickActions = ref([
  {
    text: '分析本月数据',
    type: '数据分析'
  }
])

// 动态添加快捷操作
const addQuickAction = () => {
  quickActions.value.push({
    text: '新的快捷操作',
    type: '知识解答'
  })
}
</script>

<template>
  <main-ai :quickActions="quickActions" />
  <button @click="addQuickAction">添加快捷操作</button>
</template>
```

### 注意事项

1. quickActions 数组中的每个对象必须包含 `text` 和 `type` 属性
2. `type` 属性值应该与系统支持的类型匹配
3. 建议根据用户权限和场景动态调整快捷操作列表
4. Plus版本功能（数据分析、功能导航）需要确保相应的配置已正确设置

## 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| message | { type, content } | 发送/接收消息时触发 |
| error | Error | 发生错误时触发 |
| ready | - | 组件加载完成时触发 |

## 插槽

组件提供以下插槽以支持自定义内容：

```vue
<main-ai>
  <!-- 自定义头部 -->
  <template #header>
    <div>自定义头部内容</div>
  </template>
  
  <!-- 自定义输入框 -->
  <template #input>
    <div>自定义输入区域</div>
  </template>
</main-ai>
```

## 样式定制

组件使用CSS变量进行样式定制，您可以覆盖以下变量来自定义样式：

```css
:root {
  --ai-primary-color: #3498db;
  --ai-background-color: #ffffff;
  --ai-text-color: #333333;
  --ai-border-radius: 12px;
  /* 更多变量... */
}
```

## 注意事项

1. 确保您的Vue版本 >= 3.0
2. 组件依赖于现代浏览器的Fetch API和Streams API
3. **必须提供正确的BASE_URL和API_KEY才能使用插件**
4. 为避免JSON解析错误，建议使用最新版本的插件

## 开发计划

- [ ] 支持语音输入
- [ ] 添加更多对话场景
- [ ] 优化移动端体验
- [ ] 支持自定义主题
- [ ] 添加国际化支持
- [ ] 集成更多AI模型支持
- [ ] 添加文件上传分析功能

## 贡献指南

欢迎提交Issue和Pull Request。在提交PR之前，请确保：

1. 更新测试用例
2. 更新相关文档
3. 遵循代码规范

## 许可证

MIT License

## 作者

Youhui Pu <1723741093@qq.com>

## 更新日志

### v1.0.57
- 优化导航功能样式不显示的问题


### v1.0.56
- 添加数据分析模式的独立处理流程
- 实现数据库查询的三步式处理机制
- 优化数据分析结果的展示方式

### v1.0.55
- 修改默认选项为"知识解答"
- 优化选项菜单的默认显示
- 改进用户界面的初始状态

### v1.0.54
- 修复字体文件路径引用问题，改用相对路径
- 优化字体资源加载方式
- 提高项目的兼容性和稳定性

### v1.0.53
- 添加点击选项框外部区域自动关闭选项框的功能
- 优化选项框的交互体验
- 提升用户界面的易用性

### v1.0.52
- 修复输入/字符时会同时显示在输入框中的问题
- 优化输入事件处理逻辑，阻止/字符的默认输入行为
- 改进键盘事件处理，提升选项菜单切换的准确性

### v1.0.51
- 修复聊天界面输入框/键的处理逻辑
- 空输入框时输入/可切换选项菜单的显示状态
- 输入框有内容时正常输入/字符

### v1.0.50
- 修复聊天界面输入框有内容时输入/会清空内容的问题
- 优化聊天界面输入框的交互逻辑
- 使聊天界面输入框的行为与初始界面保持一致

### v1.0.49
- 优化聊天界面输入框的/键处理逻辑
- 输入/时不再显示斜杠字符
- 改进选项菜单的切换体验

### v1.0.48
- 优化聊天界面输入框的选项菜单交互
- 支持使用/键切换选项菜单的显示和隐藏
- 统一初始界面和聊天界面的输入框行为

### v1.0.47
- 修复输入/不能打开选项菜单的问题
- 优化输入框交互逻辑，提升用户体验
- 改进选项菜单的展开和隐藏机制

### v1.0.46
- 优化选项菜单的展开逻辑，仅在输入框为空时输入/才展开
- 添加删除键隐藏选项菜单的功能
- 改进输入框交互体验，使其更加直观

### v1.0.45
- 在初始界面添加技术支持说明
- 优化底部文字样式和布局
- 添加DeepSeek接入说明

### v1.0.44
- 优化快速操作区域的视觉设计
- 改进卡片样式，添加更现代的阴影和过渡效果
- 增强交互体验，优化hover状态反馈
- 统一设计风格，提升整体视觉层次

### v1.0.38
- 添加自定义欢迎语功能
- 优化欢迎语样式，添加渐变色和动画效果
- 改进整体用户界面体验

### v1.0.37
- 修复依赖冲突问题，更新了@vitejs/plugin-vue的版本要求
- 完善安装指南，增加多种解决依赖冲突的方法
- 提高与各种Vue/Vite版本组合的兼容性

### v1.0.36
- 修复了依赖冲突问题，调整了vite的版本要求
- 使插件兼容vite 5.x和6.x版本
- 提高了与现有项目的兼容性

### v1.0.35
- 完善文档，补充高级组件实例方法的使用说明
- 添加处理流程状态提示的详细文档
- 增强错误处理与稳定性说明
- 优化整体文档结构，提升可读性

### v1.0.34
- 修复JSON解析错误问题，增强对不完整JSON数据的处理能力
- 添加JSON字符串完整性检查，避免解析不完整的数据流
- 优化错误日志输出，提高调试效率

### v1.0.33
- 增强加载动画状态提示，根据不同事件和节点类型显示相应的状态信息
- 添加工作流和节点状态的详细提示，提升用户体验
- 优化日志输出，方便开发调试

### v1.0.32
- 修复JSON解析错误导致加载动画异常消失的问题
- 增强错误处理能力，添加更详细的错误日志
- 优化流数据处理逻辑，提高稳定性

### v1.0.31
- 优化"开始新对话"按钮的定位方式，改为使用sticky定位
- 确保按钮固定在聊天界面顶部，不随聊天内容滚动，同时保持在聊天界面内

### v1.0.30
- 修复"开始新对话"按钮随聊天内容滚动的问题
- 将按钮定位方式改为固定位置，提升用户体验

### v1.0.29
- 优化"开始新对话"按钮的定位方式，从页面固定位置改为相对于聊天界面的固定位置
- 提升用户体验，使界面布局更加合理

### v1.0.28
- 修复加载动画显示时机问题，确保在收到第一个message事件时才隐藏
- 增强事件处理逻辑，添加日志记录以便于调试
- 优化用户体验，使加载状态与实际思考过程同步

### v1.0.27
- 优化加载动画逻辑，根据实际消息流程调整显示时机
- 修复加载动画与消息显示的切换问题
- 提升用户体验，使加载状态更加准确

### v1.0.26
- 修复加载动画消失后延迟显示答案的问题
- 优化加载动画和流式消息的显示逻辑
- 提升用户体验，确保答案即时显示

### v1.0.25
- 修复加载等待动画不显示的问题
- 优化消息处理流程，提高用户体验

### v1.0.24
- 修复调用startChat方法后无法再次发送消息的问题
- 增强错误处理和状态管理
- 添加请求队列机制，防止消息发送冲突

### v1.0.23
- 添加隐藏消息参数功能
- 优化消息发送逻辑，分离请求处理
- 改进代码结构，提高可维护性

### v1.0.22
- 改进组件实例查找机制
- 添加组件实例注册功能，提高startChat方法的可靠性
- 修复在某些情况下无法找到组件实例的问题

### v1.0.21
- 添加直接调起聊天界面功能
- 新增 `startChat` 方法，允许直接发送消息而无需用户输入

### v1.0.20
- 添加动态背景配置功能
- 支持背景图片、纯色背景、渐变背景和透明度设置
- 优化背景渲染逻辑

### v1.0.19
- 修复PDF链接显示问题
- 优化Markdown渲染

### v1.0.18
- 添加Markdown渲染支持
- 优化消息显示效果

### v1.0.16
- 添加初始化功能，要求提供BASE_URL和API_KEY
- 优化错误提示

### v1.0.15
- 初始版本发布
- 实现基础对话功能
- 添加流式响应支持
- 实现历史记录管理