@puyouhui/ty-plugin v1.0.58

TY-Plugin AI助手插件

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

功能特点

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

安装

npm install @puyouhui/ty-plugin

基础使用

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

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：在组件中初始化

import { getCurrentInstance } from 'vue'

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

方式3：直接导入初始化

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

init('YOUR_BASE_URL', 'YOUR_API_KEY')

Plus版本功能

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

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'  // 导航接口
  }
})

配置选项

基础配置

外观配置

Plus版本配置

dataAnalysisConfig

navigationConfig

API接口说明

数据分析接口

1. 数据表匹配接口

POST /api/data/matching-tables
请求体: { question: string }
响应: { 
  code: number,
  data: { 
    tableName: string,
    description: string 
  }
}

2. SQL查询生成接口

POST /api/data/generate-query
请求体: { 
  question: string,
  tableName: string 
}
响应: {
  code: number,
  data: {
    sql: string,
    description: string
  }
}

3. SQL执行接口

POST /api/data/execute-query
请求体: {
  question: string,
  sql: string
}
响应: {
  code: number,
  data: Array<any>
}

智能导航接口

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

事件处理

导航事件

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

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

错误处理

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

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能力支持

安装

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

解决依赖冲突问题

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

方法1: 使用特殊安装标志

# npm方式
npm install @puyouhui/ty-plugin --save --legacy-peer-deps

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

方法2: 先将项目的Vite版本调整为兼容版本

# 如果使用 @vitejs/plugin-vue@5.x，请先安装兼容的vite版本
npm install vite@5.x --save-dev
npm install @puyouhui/ty-plugin --save

方法3: 使用nvm管理不同版本的Node环境

# 推荐使用Node 18.x版本
nvm use 18
npm install @puyouhui/ty-plugin --save

使用方法

1. 初始化插件（必须）

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

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

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: 在组件中初始化

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: 直接导入初始化

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. 在模板中使用

<template>
  <main-ai />
</template>

3. 直接调起聊天界面

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

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

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

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

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

使用隐藏消息参数

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

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

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

隐藏消息参数可以用于：

• 向AI提供额外的指令或上下文
• 设置特定的输出格式或风格要求
• 传递不希望用户看到的系统提示或配置信息

4. 高级组件实例方法

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

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

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

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

处理流程状态提示

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

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

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

错误处理与稳定性

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

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

组件属性

quickActions 属性说明

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

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

使用示例：

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

快捷操作类型说明

快捷操作支持以下类型：

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

每种类型会触发不同的处理逻辑：

• 数据分析类型：调用数据分析接口进行处理
• 功能导航类型：调用导航接口进行处理
• 知识解答和报告生成：使用基础对话功能处理

动态更新快捷操作

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

<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版本功能（数据分析、功能导航）需要确保相应的配置已正确设置

事件

插槽

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

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

样式定制

组件使用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

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