yz-uniapp-ai-agent

微信小程序 UniApp AI 智能客服弹窗组件，支持智能对话、语音识别、图片上传、人工客服转接等功能。

安装

方式一：npm 安装（推荐）

npm install yz-uniapp-ai-agent --ignore-scripts=false

--ignore-scripts=false 确保 postinstall 脚本执行，自动将组件复制到 uni_modules/ 目录。如果未加此参数，安装后需手动执行：

cd node_modules/yz-uniapp-ai-agent && npm run setup

方式二：HBuilderX 插件市场安装

通过 HBuilderX 的插件市场一键安装到 uni_modules/ 目录。

前置依赖

• uview-plus — 弹窗组件 up-popup 依赖
• Vue 3

快速开始

1. 全局注册配置

在 main.js 中注入全局配置：

import { AiAgentPlugin } from '@/uni_modules/yz-uniapp-ai-agent/index.js'

// Vue 3
const app = createSSRApp(App)
app.use(AiAgentPlugin, {
  baseUrl: 'https://your-ai-service.com',   // 必填：AI 服务基础地址
  getToken: () => uni.getStorageSync('token'), // 必填：获取认证 token
  getUserKey: () => uni.getStorageSync('userKey') // 必填：获取用户标识
})
app.mount('#app')

2. 在页面中使用

组件通过 easycom 自动注册为 <ai-agent>，无需手动 import：

<template>
  <view>
    <button @tap="showAgent = true">打开AI客服</button>
    <ai-agent :show="showAgent" @close="showAgent = false" />
  </view>
</template>

<script>
export default {
  data() {
    return {
      showAgent: false
    }
  }
}
</script>

配置项

Plugin 全局配置

通过 app.use(AiAgentPlugin, options) 注入：

| 参数 | 类型 | 必填 | 说明 | |------|------|:----:|------| | baseUrl | String | 是 | AI 服务基础地址，WebSocket 地址自动从 http 转换为 ws | | appId | String | 否 | 微信小程序 appId，不填则自动获取 | | getToken | Function | 是 | 获取认证 token 的函数，返回 string | | getUserKey | Function | 是 | 获取用户标识的函数，返回 string | | defaultAvatar | String | 否 | AI 默认头像地址 | | copyrightName | String | 否 | 版权名称 |

Props

Props 传入的配置优先级高于 Plugin 全局配置。

| Prop | 类型 | 必填 | 默认值 | 说明 | |------|------|:----:|--------|------| | show | Boolean | 是 | false | 控制弹窗显示/隐藏 | | baseUrl | String | 否 | - | AI 服务地址，覆盖全局配置 | | appId | String | 否 | - | 小程序 appId，覆盖全局配置 | | getToken | Function | 否 | - | 获取 token 函数，覆盖全局配置 | | getUserKey | Function | 否 | - | 获取用户标识函数，覆盖全局配置 | | defaultAvatar | String | 否 | - | AI 默认头像 | | copyrightName | String | 否 | - | 版权名称 |

Events

| 事件 | 参数 | 说明 | |------|------|------| | close | - | 弹窗关闭时触发 | | open | - | 弹窗打开时触发 |

功能特性

• 智能对话 — WebSocket 实时流式对话，支持 Markdown 渲染
• 语音识别 — 按住说话，自动录音转文字发送
• 图片上传 — 支持拍照/相册选择，图片消息发送
• 人工客服 — 自动转接微信客服，工作时间判断
• 表情面板 — 内置常用表情选择
• 常见问题 — 自动展示 FAQ 快捷选项
• 消息状态 — 已读/未读状态显示，消息滑入动画

组件结构

uni_modules/yz-uniapp-ai-agent/
├── package.json                    # 包配置
├── index.js                        # AiAgentPlugin 入口
├── changelog.md                    # 更新日志
├── common/
│   ├── api.js                      # API 接口封装
│   └── request.js                  # 基于 uni.request 的请求模块
├── components/
│   └── ai-agent/
│       └── ai-agent.vue            # 核心组件
└── scripts/
    └── postinstall.js              # npm 安装后自动复制脚本

注意事项

• 本组件仅支持微信小程序端
• baseUrl 需配置为 AI 服务地址，WebSocket 地址自动从 http 转换为 ws
• getToken 和 getUserKey 函数在组件内部被调用，需确保返回有效的认证信息
• 组件依赖 uview-plus 的 up-popup，请确保项目已安装
• npm 安装时需加 --ignore-scripts=false 参数，否则需手动执行 npm run setup

更新日志

见 changelog.md