更新记录
2.1.35(2025-07-10) 下载此版本
- 修改全局api接口配置
2.1.34(2025-06-14) 下载此版本
- 修复样式问题
2.1.33(2025-06-12) 下载此版本
- 修复样式问题
平台兼容性
uni-app
Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
---|---|---|---|---|---|---|---|---|
√ | √ | √ | - | √ | - | - | - | - |
微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 快应用-华为 | 快应用-联盟 |
---|---|---|---|---|---|---|---|---|---|---|
√ | √ | √ | √ | √ | √ | - | √ | √ | √ | √ |
其他
多语言 | 暗黑模式 | 宽屏模式 |
---|---|---|
× | × | √ |
🤖 AI智能对话插件使用手册
byt-ai-agent-uni - 基于uni-app的AI智能对话插件,支持H5、小程序、APP等多端部署
📋 目录
✨ 功能特色
🔥 核心功能
- 🚀 多端支持: H5、微信小程序、APP等全端适配
- 💬 智能对话: 支持文本、图片、图表等多种消息类型
- 🧠 深度思考: 集成深度思考模式,提供更准确的回答
- 🔍 联网搜索: 实时获取最新信息
- 🎨 主题定制: 完全可定制的UI主题和样式
- 📱 响应式设计: 自适应大屏和移动端显示
🛠 技术特性
- ⚡ 实时通信: WebSocket实时消息推送
- 🔄 Mock模式: 支持离线演示和开发调试
- 🔐 安全认证: 完整的token鉴权机制
- 💾 历史记录: 自动保存对话历史
- 🔃 断线重连: 智能重连机制保证稳定性
🚀 快速开始
第一步:插件安装
点击右上角"下载插件并导入HBuilderX"到项目中,或手动将插件文件放置到 uni_modules
目录下。
第二步:引入样式
⚠️ 重要:此步骤为必需,组件依赖BEM样式工具函数
选择以下任一方式引入插件样式:
方式一:在 uni.scss
中引入(推荐)
@import "@/uni_modules/byt-ai-agent-uni/index.scss";
方式二:在 App.vue
中引入
<style lang="scss">
@import "@/uni_modules/byt-ai-agent-uni/index.scss";
</style>
验证引入是否成功:
- 组件能正常显示样式
- 控制台无SCSS编译错误
- 如出现
Undefined mixin 'b'
错误,请检查引入路径
第三步:环境变量配置
⚠️ 重要:Mock模式需要配置环境变量控制
配置 VITE_OPEN_MOKE 环境变量
AI智能体插件支持Mock模式,无需真实API即可体验完整功能。通过环境变量 VITE_OPEN_MOKE
控制:
1. 在项目根目录创建环境变量文件:
开发环境配置 .env.development
:
# AI智能体Mock模式配置
VITE_OPEN_MOKE=true
# 其他开发环境配置...
生产环境配置 .env.production
:
# AI智能体Mock模式配置(生产环境建议关闭)
VITE_OPEN_MOKE=false
# 其他生产环境配置...
测试环境配置 .env.test
:
# AI智能体Mock模式配置(测试环境可开启)
VITE_OPEN_MOKE=true
# 其他测试环境配置...
**环境变量说明 config.js
有些工程可能未配置环境变量,可以在common下的config.js文件下配置一个固定的变量以供使用
// 接口地址
apiUrl: process.env.VITE_API_URL || 'https://api.yummall.cn',
// ws接口服务
wsUrl: process.env.VITE_WS_URL || 'wss://api.yummall.cn',
// AI流式访问地址
wsChatPath: process.env.VITE_WS_CHAT_PATH || '/ws-anno/chat.ws',
moke: process.env.VITE_OPEN_MOKE || 'true',
2. 环境变量说明:
值 | 说明 | 适用场景 |
---|---|---|
true |
开启Mock模式 | 开发调试、演示展示、无后端环境 |
false |
关闭Mock模式 | 生产环境、有真实API的环境 |
3. Mock模式特性:
✅ 完整功能体验
- 模拟真实的AI对话流程
- 支持流式消息回复
- 包含深度思考功能演示
- 支持多种消息类型(文本、图表、商品等)
✅ 离线可用
- 无需网络连接
- 无需配置真实API
- 无需智能体服务
✅ 开发友好
- 快速原型验证
- UI/UX测试
- 功能演示
4. 使用示例:
<template>
<view class="container">
<!-- 组件会自动根据环境变量判断是否启用Mock模式 -->
<byt-dialogue
:config="dialogueConfig"
:agentId="agentId"
:agentName="agentName"
/>
</view>
</template>
<script>
export default {
data() {
return {
// Mock模式下agentId可以是任意值
agentId: "demo-agent-id",
agentName: "AI演示助手",
dialogueConfig: {
userInfo: {
userId: "demo-user-123"
},
// Mock模式下的推荐问题
promptItems: [
{ btnName: '功能', text: '展示图表' },
{ btnName: '功能', text: '商品推荐' },
{ btnName: '功能', text: '优惠券' },
{ btnName: '功能', text: '活动信息' }
]
}
}
},
computed: {
// 可以通过计算属性获取当前Mock模式状态
isMockMode() {
return import.meta.env.VITE_OPEN_MOKE === 'true' || import.meta.env.VITE_OPEN_MOKE === true;
}
}
}
</script>
5. 调试和验证:
// 在控制台查看当前Mock模式状态
console.log('Mock模式状态:', import.meta.env.VITE_OPEN_MOKE);
// 在组件中动态判断
if (import.meta.env.VITE_OPEN_MOKE) {
console.log('🎭 当前运行在Mock模式');
} else {
console.log('🚀 当前运行在正式模式');
}
6. 注意事项:
⚠️ 环境变量命名规则
- Vite环境变量必须以
VITE_
前缀开头 - 只有以
VITE_
开头的变量才会暴露给客户端代码
⚠️ 类型转换
- 环境变量始终是字符串类型
- 布尔判断需要显式比较:
=== 'true'
或=== true
⚠️ 安全考虑
- Mock模式仅用于开发和演示
- 生产环境务必设置为
false
- 不要在Mock模式下处理敏感数据
完整项目结构示例
配置完成后,你的项目结构应该如下:
your-project/
├── .env.development # 开发环境变量
├── .env.production # 生产环境变量
├── .env.test # 测试环境变量(可选)
├── src/
│ ├── uni.scss # 已引入插件样式
│ ├── main.ts # H5/APP已初始化插件(正式模式)
│ ├── service/
│ │ └── api/
│ │ └── agent-chat.js # AI对话API接口文件
│ └── uni_modules/
│ └── byt-ai-agent-uni/ # AI智能体插件
├── ai-agent-config.js # H5/APP API配置(正式模式)
└── ai-agent-config-mp.js # 小程序API配置(正式模式,组件自动加载)
说明:
- Mock模式: 只需配置环境变量
VITE_OPEN_MOKE=true
,无需API配置文件 - 正式模式: 需要创建API接口文件和对应的配置文件
- API文件: 必须创建
src/service/api/agent-chat.js
文件 - 小程序: 配置文件会被组件自动动态导入,main.js无需处理
模式选择建议
🎭 推荐使用Mock模式的场景:
- 🚀 项目初期原型验证
- 🎨 UI/UX设计验证
- 📱 前端开发和调试
- 🎪 产品演示和展示
- 📋 功能测试和验收
- 🔧 没有后端API环境
🚀 推荐使用正式模式的场景:
- 🏭 生产环境部署
- 🔗 有真实AI服务
- 📊 需要真实数据处理
- 🔐 需要用户认证
- 📈 需要数据统计分析
- 📱 小程序开发(配置简单,组件自动处理)
第四步:配置API文件
💡 提示:如果使用Mock模式(VITE_OPEN_MOKE=true
),可以跳过此步骤直接使用组件
如果你选择正式模式或需要连接真实的AI服务,需要配置API接口:
📱 小程序开发更简单: 只需创建配置文件,组件会自动处理初始化!
创建API服务文件
在 src/service/api/
目录下创建 agent-chat.js
文件:
import request from '../request';
/**
* AI对话相关API接口
*/
// 获取历史对话消息
export const fetchChatHistoryList = (data, config = {}) => {
return request.post('/cms/aiDialogueRecord/getPageList', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
// 获取语音识别的token
export const fetchChatAudioToken = (data, config = {}) => {
return request.post('/cms/aiDialogueHistory/getBaiduToken', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
// 清除chatGPT的上下文内容
export const fetchChatClearMessage = (data, config = {}) => {
return request.post('/cms/aiDialogueHistory/delMessage', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
// 获取打开一个新的对话的historyId
export const fetchChatOpenNewHistory = (data, config = {}) => {
return request.post('/cms/aiDialogueHistory/add', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
// 获取所有常问问题
export const fetchChatGuessProblem = (data, config = {}) => {
return request.post('/digitalPortal/manage/problem/all', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
// 对话列表
export const fetchChatSessionList = (data, config = {}) => {
return request.post('/cms/aiDialogueHistory/getPageList', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
// 新智能体列表
export const fetchChatTechnologyList = (data, config = {}) => {
return request.post('/cms/aiAgent/list', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
// 获取智能体列表详情
export const fetchChatTechnologyDetail = (data, config = {}) => {
return request.post('/cms/aiAgent/detail', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
// 获取默认智能体
export const fetchGetDefaultAgent = (data, config = {}) => {
return request.post('/cms/aiAgent/getDefaultAgent', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
// 百度语音识别接口
export const fetchBaiduAudioRecognition = (data, config = {}) => {
return request.post('/cms/aiDialogueHistory/VoiceToText', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
说明:
- 文件位置: 必须放在
src/service/api/agent-chat.js
- 导入方式: 使用项目现有的request工具
- 接口格式: 所有接口都使用POST方法,统一配置超时和错误处理
- 参数结构: 支持data参数和config配置对象
- 错误处理: 统一启用错误提示
showErrorToast: true
API接口说明:
接口名称 | 路径 | 说明 | 必需 |
---|---|---|---|
fetchChatHistoryList | /cms/aiDialogueRecord/getPageList | 获取历史消息列表 | ✅ |
fetchChatAudioToken | /cms/aiDialogueHistory/getBaiduToken | 获取语音识别token | ⭕ |
fetchChatClearMessage | /cms/aiDialogueHistory/delMessage | 清除对话上下文 | ✅ |
fetchChatOpenNewHistory | /cms/aiDialogueHistory/add | 创建新对话历史 | ✅ |
fetchChatGuessProblem | /digitalPortal/manage/problem/all | 获取推荐问题 | ⭕ |
fetchChatSessionList | /cms/aiDialogueHistory/getPageList | 获取会话列表 | ⭕ |
fetchChatTechnologyList | /cms/aiAgent/list | 获取智能体列表 | ⭕ |
fetchChatTechnologyDetail | /cms/aiAgent/detail | 获取智能体详情 | ⭕ |
fetchGetDefaultAgent | /cms/aiAgent/getDefaultAgent | 获取默认智能体 | ✅ |
fetchBaiduAudioRecognition | /cms/aiDialogueHistory/VoiceToText | 百度语音识别 | ⭕ |
✅ 必需 ⭕ 可选(不影响基础功能)
第五步:API配置初始化
H5/APP环境配置
在项目根目录创建 ai-agent-config.js
:
/**
* AI智能体插件配置文件
*
* 说明:将主项目的API配置注入到插件中,实现插件与业务逻辑的解耦
*/
import { setApiConfig, checkApiConfig } from './src/uni_modules/byt-ai-agent-uni/common/agent-api.js';
// 导入主项目的API方法
import {
fetchChatHistoryList, // 获取历史消息列表
fetchChatAudioToken, // 获取语音识别token
fetchChatClearMessage, // 清除对话上下文
fetchChatOpenNewHistory, // 创建新对话历史
fetchChatGuessProblem, // 获取推荐问题
fetchChatSessionList, // 获取会话列表
fetchChatTechnologyList, // 获取技术列表
fetchChatTechnologyDetail, // 获取技术详情
fetchGetDefaultAgent, // 获取默认智能体
fetchBaiduAudioRecognition // 百度语音识别
} from './src/service/api/agent-chat.js';
/**
* 初始化AI智能体插件
* 将主项目的API配置注入到插件中
*/
export const initAiAgent = () => {
// 配置API方法映射
const apiConfig = {
getChatHistoryList: fetchChatHistoryList,
chatAudioToken: fetchChatAudioToken,
clearChatMessage: fetchChatClearMessage,
chatOpenNewHistory: fetchChatOpenNewHistory,
chatGuessProblem: fetchChatGuessProblem,
chatSessionList: fetchChatSessionList,
chatTechnologyList: fetchChatTechnologyList,
chatTechnologyDetail: fetchChatTechnologyDetail,
getDefaultAgent: fetchGetDefaultAgent,
baiduAudioRecognition: fetchBaiduAudioRecognition
};
// 注入API配置到插件
setApiConfig(apiConfig);
// 检查配置完整性
if (!checkApiConfig()) {
console.warn('AI Agent plugin: Some required APIs are not configured properly');
} else {
console.log('AI Agent plugin: Successfully initialized with API configuration');
}
};
/**
* 插件配置验证
* @returns {boolean} 配置是否有效
*/
export const validateAiAgentConfig = () => {
return checkApiConfig();
};
/**
* 重新配置特定的API(用于自定义或测试)
* @param {Object} customApiConfig 自定义API配置
*/
export const reconfigureApi = customApiConfig => {
setApiConfig(customApiConfig);
console.log('AI Agent plugin: API configuration updated');
};
// 默认导出初始化函数
export default initAiAgent;
小程序环境配置
⚠️ 重要提示:小程序环境使用单独的配置文件,支持组件内动态加载
在项目根目录创建 ai-agent-config-mp.js
:
/**
* AI智能体插件小程序专用配置文件
*
* 说明:
* 1. 小程序环境使用单独的配置文件,确保平台兼容性
* 2. 组件会在需要时自动动态导入此配置文件
* 3. 该文件与H5/APP配置在API映射上保持一致,确保跨平台兼容性
* 4. 无需在main.js中手动初始化,组件会自动处理
*/
import { setApiConfig, checkApiConfig } from './src/uni_modules/byt-ai-agent-uni/common/agent-api.js';
// 导入主项目的API方法(确保路径与H5/APP版本一致)
import {
fetchChatHistoryList, // 获取历史消息列表
fetchChatAudioToken, // 获取语音识别token
fetchChatClearMessage, // 清除对话上下文
fetchChatOpenNewHistory, // 创建新对话历史
fetchChatGuessProblem, // 获取推荐问题
fetchChatSessionList, // 获取会话列表
fetchChatTechnologyList, // 获取技术列表
fetchChatTechnologyDetail, // 获取技术详情
fetchGetDefaultAgent, // 获取默认智能体
fetchBaiduAudioRecognition // 百度语音识别
} from './src/service/api/agent-chat.js';
/**
* 小程序环境专用初始化方法
* @returns {Promise<boolean>} 初始化是否成功
*/
export async function initAiAgentMP() {
try {
console.log('🔧 正在初始化AI智能体插件(小程序环境)...');
// 配置API方法映射(与H5/APP版本保持完全一致)
const mpApiConfig = {
getChatHistoryList: fetchChatHistoryList,
chatAudioToken: fetchChatAudioToken,
clearChatMessage: fetchChatClearMessage,
chatOpenNewHistory: fetchChatOpenNewHistory,
chatGuessProblem: fetchChatGuessProblem,
chatSessionList: fetchChatSessionList,
chatTechnologyList: fetchChatTechnologyList,
chatTechnologyDetail: fetchChatTechnologyDetail,
getDefaultAgent: fetchGetDefaultAgent,
baiduAudioRecognition: fetchBaiduAudioRecognition
};
// 注入API配置到插件内核
setApiConfig(mpApiConfig);
// 验证配置完整性
const isConfigValid = checkApiConfig();
if (!isConfigValid) {
console.warn('⚠️ AI Agent plugin for MiniProgram: API配置不完整,部分功能可能受限');
return false;
}
console.log('✅ AI Agent plugin for MiniProgram: 初始化成功');
return true;
} catch (error) {
console.error('❌ AI Agent plugin for MiniProgram: 初始化失败:', error);
// 详细错误信息用于调试
if (error.message.includes('import')) {
console.error('💡 提示:请检查API文件路径是否正确,确保所有依赖都能在小程序环境中正常加载');
}
return false;
}
}
/**
* 检查小程序环境兼容性
* @returns {boolean} 是否兼容小程序环境
*/
export function checkMiniProgramCompatibility() {
try {
// 检查小程序基础能力
const hasWx = typeof wx !== 'undefined';
const hasUni = typeof uni !== 'undefined';
if (!hasWx && !hasUni) {
console.warn('⚠️ 当前环境可能不是小程序环境');
return false;
}
// 检查必需的小程序API
const requiredApis = ['request', 'getSystemInfo', 'showToast'];
const missingApis = requiredApis.filter(api => {
return hasWx ? !wx[api] : !uni[api];
});
if (missingApis.length > 0) {
console.warn('⚠️ 缺少必需的小程序API:', missingApis);
return false;
}
return true;
} catch (error) {
console.error('❌ 小程序兼容性检查失败:', error);
return false;
}
}
/**
* 获取小程序环境信息
* @returns {Object} 环境信息对象
*/
export function getMiniProgramInfo() {
try {
const systemInfo = uni.getSystemInfoSync();
return {
platform: systemInfo.platform,
version: systemInfo.version,
SDKVersion: systemInfo.SDKVersion,
brand: systemInfo.brand,
model: systemInfo.model,
pixelRatio: systemInfo.pixelRatio,
screenWidth: systemInfo.screenWidth,
screenHeight: systemInfo.screenHeight,
windowWidth: systemInfo.windowWidth,
windowHeight: systemInfo.windowHeight,
statusBarHeight: systemInfo.statusBarHeight,
safeArea: systemInfo.safeArea
};
} catch (error) {
console.error('❌ 获取小程序环境信息失败:', error);
return null;
}
}
// 默认导出初始化函数
export default initAiAgentMP;
小程序配置特点说明:
- 自动加载: 组件会在需要时自动动态导入配置文件
- 错误处理: 增强的错误捕获和调试信息
- 兼容性检查: 自动检测小程序环境和必需API
- 环境信息: 提供小程序运行环境详细信息
- 调试友好: 详细的控制台日志,便于排查问题
- 零配置: 无需在main.js中手动初始化
在main.js中初始化
// main.js
import { createSSRApp } from 'vue';
import App from './App.vue';
// 导入AI智能体配置初始化函数(仅H5/APP环境需要)
// #ifndef MP-WEIXIN
import { initAiAgent } from '~/ai-agent-config.js';
// #endif
export function createApp() {
const app = createSSRApp(App);
// 初始化AI智能体API配置
// #ifndef MP-WEIXIN
// H5/APP环境:手动初始化API配置
try {
initAiAgent();
console.log('✅ AI智能体插件初始化完成(H5/APP环境)');
} catch (error) {
console.error('❌ AI智能体插件初始化失败(H5/APP环境):', error);
}
// #endif
// #ifdef MP-WEIXIN
// 小程序环境:组件会自动加载配置,无需手动初始化
console.log('📱 小程序环境:AI智能体插件将在组件初始化时自动配置');
// #endif
return { app };
}
初始化说明:
-
平台差异处理:
- H5/APP: 需要在main.js中手动初始化API配置
- 小程序: 组件会自动动态导入配置文件,无需手动初始化
-
配置文件要求:
- H5/APP: 必须创建
ai-agent-config.js
并在main.js中导入 - 小程序: 只需创建
ai-agent-config-mp.js
,组件会自动加载
- H5/APP: 必须创建
-
错误处理:
- H5/APP环境的初始化错误会在main.js中捕获
- 小程序环境的配置错误会在组件内部处理
- 初始化失败不影响主应用运行
-
开发建议:
- 使用Mock模式(
VITE_OPEN_MOKE=true
)可以跳过API配置 - 小程序开发更加简便,减少了手动配置步骤
- 使用Mock模式(
说明:
- 路径别名
~/
: 表示项目根目录,确保在不同目录下都能正确引用配置文件 - 平台兼容: 使用条件编译区分H5/APP和小程序的初始化方式
- 错误处理: 为小程序动态导入添加错误捕获
- 异步安全: 小程序使用异步导入避免打包问题
替代方案(如果不支持路径别名):
// 使用相对路径
import { initAiAgent } from './ai-agent-config.js';
// 或使用绝对路径
import { initAiAgent } from '@/ai-agent-config.js';
⚠️ TypeScript 项目注意事项
如果您的项目使用 TypeScript,请确保在 tsconfig.json
的 include
配置中显式添加根目录下的配置文件:
{
"include": [
"src",
"ai-agent-config.js",
"ai-agent-config-mp.js"
]
}
说明:
- 这样可以避免 TypeScript 检查或编译时找不到这两个配置文件
- 保证类型提示和路径引用正常工作
- 如果不添加,可能会出现"找不到模块"或类型推断异常等问题
常见错误示例:
# 错误:找不到模块
Module not found: Can't resolve '~/ai-agent-config.js'
# 错误:类型检查失败
Cannot find module 'ai-agent-config.js' or its corresponding type declarations
第六步:在main.ts中初始化插件
⚠️ 重要:此步骤为必需,用于在应用启动时初始化AI智能体插件
H5/APP环境初始化
在 src/main.ts
中添加以下代码:
import { createSSRApp } from 'vue';
import App from './App.vue';
// 导入AI智能体配置初始化函数(仅H5/APP环境需要)
// #ifndef MP-WEIXIN
import { initAiAgent } from '~/ai-agent-config.js';
// #endif
export function createApp() {
const app = createSSRApp(App);
// 初始化AI智能体API配置
// #ifndef MP-WEIXIN
// H5/APP环境:手动初始化API配置
try {
initAiAgent();
console.log('✅ AI智能体插件初始化完成(H5/APP环境)');
} catch (error) {
console.error('❌ AI智能体插件初始化失败(H5/APP环境):', error);
}
// #endif
// #ifdef MP-WEIXIN
// 小程序环境:组件会自动加载配置,无需手动初始化
console.log('📱 小程序环境:AI智能体插件将在组件初始化时自动配置');
// #endif
return { app };
}
说明:
-
平台差异处理:
- H5/APP: 需要在main.ts中手动初始化API配置
- 小程序: 组件会自动动态导入配置文件,无需手动初始化
-
条件编译:
- 使用
#ifndef MP-WEIXIN
确保只在非小程序环境导入 - 使用
#ifdef MP-WEIXIN
为小程序环境提供日志信息
- 使用
-
错误处理:
- 为初始化过程添加try-catch错误捕获
- 初始化失败不会影响主应用运行
-
路径别名:
- 使用
~/
表示项目根目录 - 如果不支持路径别名,可以使用相对路径:
'./ai-agent-config.js'
- 使用
替代方案(如果不支持路径别名)
// 使用相对路径
import { initAiAgent } from './ai-agent-config.js';
// 或使用绝对路径
import { initAiAgent } from '@/ai-agent-config.js';
第七步:配置组件注册
⚠️ 重要:此步骤为必需,用于配置组件的注册方式
推荐方式:配置 easycom 自动导入
在 pages.config.ts 中配置(推荐):
import { defineUniPages } from '@uni-helper/vite-plugin-uni-pages';
export default defineUniPages({
// ... 其他配置
easycom: {
autoscan: true,
custom: {
'^(?!z-paging-refresh|z-paging-load-more)z-paging(.*)': 'z-paging/components/z-paging$1/z-paging$1.vue',
'^byt-(.*)': '@/uni_modules/byt-ai-agent-uni/components/agent-dialogue/byt-$1/byt-$1.vue'
}
},
// ... 其他配置
});
在 pages.json 中配置(传统方式):
{
"easycom": {
"autoscan": true,
"custom": {
"^byt-(.*)": "@/uni_modules/byt-ai-agent-uni/components/agent-dialogue/byt-$1/byt-$1.vue"
}
}
}
说明:
-
easycom 配置:
autoscan: true
:启用自动扫描组件custom
:自定义组件匹配规则
-
组件匹配规则:
'^byt-(.*)'
:匹配所有以byt-
开头的组件- 路径映射到插件组件目录
-
支持的组件:
byt-dialogue
:主对话组件byt-dialogueFloating
:悬浮对话组件(仅H5/APP)- 其他插件组件
备选方式:传统组件注册
💡 提示:如果已配置 easycom 自动导入,可以跳过此部分
全局注册:
在 pages.json
中配置全局组件:
{
"custom": {
"^byt-(.*)": "@/uni_modules/byt-ai-agent-uni/components/agent-dialogue/byt-$1/byt-$1.vue"
}
}
局部注册:
<script>
import BytDialogue from '@/uni_modules/byt-ai-agent-uni/components/agent-dialogue/byt-dialogue/byt-dialogue.vue';
export default {
components: {
BytDialogue
}
}
</script>
验证配置是否成功
配置完成后,可以在任何页面中直接使用组件,无需手动导入:
<template>
<view class="container">
<!-- 直接使用组件,无需导入 -->
<byt-dialogue
:config="dialogueConfig"
:agentId="agentId"
:agentName="agentName"
/>
</view>
</template>
<script>
export default {
data() {
return {
agentId: "demo-agent-id",
agentName: "AI助手",
dialogueConfig: {
userInfo: { userId: "user-123" }
}
}
}
}
</script>
第八步:基础使用
现在可以开始使用AI智能体组件了!
基础示例
<template>
<view class="container">
<!-- AI对话组件 -->
<byt-dialogue
:config="dialogueConfig"
:agentId="agentId"
:agentName="agentName"
/>
</view>
</template>
<script>
export default {
data() {
return {
// 智能体ID(必填)
agentId: "your-agent-id",
// 智能体名称
agentName: "AI助手",
// 基础配置
dialogueConfig: {
userInfo: {
userId: "user-123" // 用户ID(必填)
}
}
}
},
computed: {
// 当前是否为Mock模式(自动根据环境变量判断)
isMockMode() {
return import.meta.env.VITE_OPEN_MOKE === 'true' || import.meta.env.VITE_OPEN_MOKE === true;
}
},
created() {
// 启动时显示当前模式
if (this.isMockMode) {
console.log('🎭 AI助手运行在Mock模式 - 无需配置真实API');
} else {
console.log('🚀 AI助手运行在正式模式 - 请确保API已正确配置');
}
}
}
</script>
高级配置示例
<template>
<view class="ai-chat-page">
<!-- 带完整配置的AI对话组件 -->
<byt-dialogue
:config="advancedConfig"
:agentId="selectedAgentId"
:agentName="selectedAgentName"
:width="'100%'"
:height="'100vh'"
:backShow="true"
/>
</view>
</template>
<script>
export default {
data() {
return {
// 动态智能体配置
selectedAgentId: "agent-001",
selectedAgentName: "专业AI助手",
// 高级配置
advancedConfig: {
// 用户信息(必填)
userInfo: {
userId: "user-12345"
},
// 自定义主题色
colorIcon: {
mainColor: '#007aff',
assistColor: '#5ac8fa',
textMainColor: '#007aff',
userTextColor: '#FFFFFF',
userBgColor: '#007aff'
},
// 欢迎语配置
startup: {
welcomeShow: true,
tip: this.isMockMode
? '我是AI演示助手,您可以体验各种功能!'
: '我是您的专属AI助手,有什么可以帮您的吗?',
avatar: 'https://example.com/avatar.png',
backgroundColor: 'linear-gradient(90deg, #E7FCF6 0%, #F7FFEE 50%, #DFF8FF 100%)'
},
// 功能开关
guess: true, // 显示推荐问题
audio: true, // 语音输入
quickShow: true, // 快速提问
moreListShow: true, // 更多工具
// 工具栏配置
toolList: [
{
id: 1,
icon: 'https://example.com/deep-think.svg',
activeiIcon: 'https://example.com/deep-think-active.svg',
name: '深度思考'
},
{
id: 2,
icon: 'https://example.com/web-search.svg',
activeiIcon: 'https://example.com/web-search-active.svg',
name: '联网搜索'
}
],
// Mock模式下的推荐问题(正式模式下会从API获取)
promptItems: this.isMockMode ? [
{ btnName: '功能演示', text: '展示图表功能' },
{ btnName: '功能演示', text: '商品推荐展示' },
{ btnName: '功能演示', text: '优惠券功能' },
{ btnName: '功能演示', text: '活动信息展示' },
{ btnName: '深度思考', text: '复杂问题分析' },
{ btnName: '深度思考', text: '多步骤推理' }
] : [],
// 消息配置
message: {
answerWait: this.isMockMode ? 'AI演示助手思考中...' : 'AI助手正在思考...',
greeting: this.isMockMode ? '欢迎体验AI助手演示!' : '您好!有什么可以帮助您的?'
},
// 支持的消息类型
typeWhiteList: ['text', 'chart', 'image', 'activity', 'coupon', 'goods', 'tables'],
// 角色配置
roles: {
ai: {
name: this.selectedAgentName,
avatar: 'https://example.com/ai-avatar.png',
placement: 'start'
},
user: {
name: '我',
avatar: 'https://example.com/user-avatar.png',
placement: 'end'
}
}
}
}
},
computed: {
// Mock模式判断
isMockMode() {
return import.meta.env.VITE_OPEN_MOKE === 'true' || import.meta.env.VITE_OPEN_MOKE === true;
},
// 动态页面标题
pageTitle() {
return this.isMockMode ? 'AI助手演示' : 'AI智能助手';
}
},
created() {
// 根据模式进行初始化
this.initializeByMode();
},
methods: {
// 根据模式初始化
initializeByMode() {
if (this.isMockMode) {
console.log('🎭 Mock模式初始化');
// Mock模式下可以使用任意配置
this.selectedAgentId = 'demo-agent';
this.selectedAgentName = 'AI演示助手';
} else {
console.log('🚀 正式模式初始化');
// 正式模式下可能需要从API获取智能体列表
this.loadAvailableAgents();
}
},
// 加载可用的智能体(正式模式)
async loadAvailableAgents() {
try {
// 这里可以调用API获取智能体列表
// const agents = await fetchAgentList();
// this.selectedAgentId = agents[0].id;
// this.selectedAgentName = agents[0].name;
console.log('智能体列表加载完成');
} catch (error) {
console.error('加载智能体列表失败:', error);
}
}
}
}
</script>
<style lang="scss" scoped>
.ai-chat-page {
width: 100%;
height: 100vh;
background: #f5f5f5;
}
</style>
快速测试
配置完成后,你可以通过以下方式快速测试:
1. Mock模式测试(推荐新手):
# 设置环境变量
echo "VITE_OPEN_MOKE=true" > .env.development
# 启动开发服务器
npm run dev
2. 正式模式测试:
# 设置环境变量
echo "VITE_OPEN_MOKE=false" > .env.development
# 确保API配置已完成,然后启动
npm run dev
3. 功能验证清单:
✅ 基础功能
- [ ] 组件正常渲染
- [ ] 欢迎语显示
- [ ] 可以发送消息
- [ ] 收到AI回复
✅ Mock模式专项
- [ ] 推荐问题显示
- [ ] 点击推荐问题有回复
- [ ] 深度思考功能演示
- [ ] 多种消息类型展示(图表、商品等)
✅ 样式和交互
- [ ] 主题色配置生效
- [ ] 消息气泡样式正确
- [ ] 滚动和动画流畅
- [ ] 移动端适配良好
⚙️ 详细配置
组件Props
参数 | 类型 | 必填 | 默认值 | 说明 |
---|---|---|---|---|
config | Object | 否 | {} | 详细配置对象 |
agentId | String | 是 | - | AI智能体ID(Mock模式下可任意值) |
agentName | String | 否 | 'AI助手' | 智能体显示名称 |
width | String | 否 | '100%' | 组件宽度 |
height | String | 否 | '100vh' | 组件高度 |
backShow | Boolean | 否 | true | 是否显示返回按钮 |
📝 注意:Mock模式通过环境变量 VITE_OPEN_MOKE
自动控制,无需传入props
Config配置详解
const dialogueConfig = {
// 👤 用户信息配置(必填)
userInfo: {
userId: "user-123" // 用户唯一标识
},
// 🎨 主题颜色和图标配置
colorIcon: {
mainColor: '#448ef7', // 主题色
assistColor: '#a8ecff', // 辅助色
textMainColor: '#1890ff', // 字体主色
userTextColor: '#FFFFFF', // 用户消息字体色
userBgColor: '#448ef7', // 用户消息背景色
// 图标配置
actionIcon: 'icon-url', // 操作按钮图标
copyIcon: 'icon-url', // 复制图标
refreshIcon: 'icon-url', // 刷新图标
// 更多图标配置...
},
// 🏠 启动欢迎配置
startup: {
welcomeShow: true, // 是否显示欢迎栏
tip: '我是AI助手,有什么可以帮您的?', // 欢迎语
avatar: 'avatar-url', // 头像
backgroundColor: 'linear-gradient(90deg, #E7FCF6 0%, #F7FFEE 50%, #DFF8FF 100%)'
},
// 🖼️ 主体背景配置
main: {
background: 1, // 预设背景(1-4)
// 或自定义背景
// background: {
// type: 'image', // image|linear|color
// url: 'background-url'
// },
role: 1 // 角色装饰图(1-4)
},
// 🛠️ 工具栏配置
toolList: [
{
id: 1,
icon: 'tool-icon-url',
activeiIcon: 'active-icon-url',
name: '深度思考'
}
],
// ➕ 更多工具配置
moreList: [
{ id: 1, icon: 'icon-url', name: '拍摄' },
{ id: 2, icon: 'icon-url', name: '录音' }
],
// 🔧 功能开关
moreListShow: true, // 显示更多工具
quickShow: true, // 显示快速提问
guess: false, // 显示推荐问题
audio: true, // 语音输入功能
// 💬 消息配置
message: {
answerWait: 'AI助手思考中', // 等待回复提示
greeting: '您好!有什么可以帮助您的?' // 问候语
},
// 📋 支持的消息类型
typeWhiteList: ['text', 'chart', 'image', 'activity'],
// 👥 角色配置
roles: {
ai: {
name: 'AI助手',
avatar: 'ai-avatar-url',
placement: 'start'
},
user: {
name: '用户',
avatar: 'user-avatar-url',
placement: 'end'
}
}
};
🔗 API接口配置
主项目API服务配置
首先需要在主项目中实现所需的API服务,在 src/service/api/agent-chat.js
中:
// src/service/api/agent-chat.js
import request from '../request'; // 您的请求工具
/**
* 获取历史对话消息
* @param {Object} data 查询参数
* @param {Object} config 配置参数
* @returns {Promise}
*/
export const fetchChatHistoryList = (data, config = {}) => {
return request.post('/cms/aiDialogueRecord/getPageList', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
/**
* 获取语音识别的token
* @param {Object} data 请求参数
* @param {Object} config 配置参数
* @returns {Promise}
*/
export const fetchChatAudioToken = (data, config = {}) => {
return request.post('/cms/aiDialogueHistory/getBaiduToken', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
/**
* 清除chatGPT的上下文内容
* @param {Object} data 清除参数
* @param {Object} config 配置参数
* @returns {Promise}
*/
export const fetchChatClearMessage = (data, config = {}) => {
return request.post('/cms/aiDialogueHistory/delMessage', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
/**
* 获取打开一个新的对话的historyId
* @param {Object} data 创建参数
* @param {Object} config 配置参数
* @returns {Promise}
*/
export const fetchChatOpenNewHistory = (data, config = {}) => {
return request.post('/cms/aiDialogueHistory/add', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
/**
* 获取所有常问问题
* @param {Object} data 查询参数
* @param {Object} config 配置参数
* @returns {Promise}
*/
export const fetchChatGuessProblem = (data, config = {}) => {
return request.post('/digitalPortal/manage/problem/all', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
/**
* 对话列表
* @param {Object} data 查询参数
* @param {Object} config 配置参数
* @returns {Promise}
*/
export const fetchChatSessionList = (data, config = {}) => {
return request.post('/cms/aiDialogueHistory/getPageList', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
/**
* 新智能体列表
* @param {Object} data 查询参数
* @param {Object} config 配置参数
* @returns {Promise}
*/
export const fetchChatTechnologyList = (data, config = {}) => {
return request.post('/cms/aiAgent/list', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
/**
* 获取智能体列表详情
* @param {Object} data 查询参数
* @param {Object} config 配置参数
* @returns {Promise}
*/
export const fetchChatTechnologyDetail = (data, config = {}) => {
return request.post('/cms/aiAgent/detail', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
/**
* 获取默认智能体
* @param {Object} data 查询参数
* @param {Object} config 配置参数
* @returns {Promise}
*/
export const fetchGetDefaultAgent = (data, config = {}) => {
return request.post('/cms/aiAgent/getDefaultAgent', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
/**
* 百度语音识别接口
* @param {Object} data 语音数据
* @param {Object} config 配置参数
* @returns {Promise}
*/
export const fetchBaiduAudioRecognition = (data, config = {}) => {
return request.post('/cms/aiDialogueHistory/VoiceToText', data, {
timeout: 60000,
custom: {
showErrorToast: true,
...config.custom
},
...config
});
};
WebSocket配置
插件内部的WebSocket配置在 common/config.js
中:
// common/config.js (插件内部)
const serviceEnv = {
development: {
apiUrl: "http://localhost:9195",
wsUrl: "ws://localhost:9195",
wsChartPath: "/ws-hello/chat.ws"
},
production: {
apiUrl: "https://api.yourcompany.com",
wsUrl: "wss://api.yourcompany.com",
wsChartPath: "/ws-anno/chat.ws"
}
};
const baseConfig = {
apiUrl: serviceEnv[process.env.NODE_ENV].apiUrl,
wsUrl: serviceEnv[process.env.NODE_ENV].wsUrl,
wsChartPath: serviceEnv[process.env.NODE_ENV].wsChartPath,
// 百度语音识别接口
baiduAudioUrl: serviceEnv[process.env.NODE_ENV].apiUrl + '/cms/aiDialogueHistory/VoiceToText',
// token获取方法(需要在主项目中提供)
getToken: () => uni.getStorageSync("bytToken")
};
必需的API接口
插件依赖以下核心接口,主项目必须实现:
接口名称 | HTTP方法 | 路径 | 说明 | 必需 |
---|---|---|---|---|
fetchChatHistoryList | POST | /cms/aiDialogueRecord/getPageList | 获取历史消息列表 | ✅ |
fetchChatClearMessage | POST | /cms/aiDialogueHistory/delMessage | 清除对话上下文 | ✅ |
fetchChatOpenNewHistory | POST | /cms/aiDialogueHistory/add | 创建新对话历史 | ✅ |
fetchGetDefaultAgent | POST | /cms/aiAgent/getDefaultAgent | 获取默认智能体 | ✅ |
fetchChatGuessProblem | POST | /digitalPortal/manage/problem/all | 获取推荐问题 | ⭕ |
fetchChatAudioToken | POST | /cms/aiDialogueHistory/getBaiduToken | 语音识别token | ⭕ |
fetchBaiduAudioRecognition | POST | /cms/aiDialogueHistory/VoiceToText | 语音识别服务 | ⭕ |
WebSocket | - | /ws-chat/chat.ws | 实时消息推送 | ✅ |
✅ 必需 ⭕ 可选(不影响基础功能)
API响应格式
所有API接口应遵循统一的响应格式:
// 成功响应
{
"code": 200,
"message": "success",
"data": { /* 具体数据 */ }
}
// 错误响应
{
"code": 400,
"message": "error message",
"data": null
}
📱 使用示例
基础对话页面
<template>
<view class="chat-page">
<byt-dialogue
:config="config"
:agentId="agentId"
:agentName="agentName"
:backShow="true"
/>
</view>
</template>
<script>
export default {
data() {
return {
agentId: '',
agentName: 'AI助手',
config: {
userInfo: { userId: 'user123' },
guess: true, // 开启推荐问题
audio: true, // 开启语音功能
toolList: [ // 工具栏配置
{ id: 1, name: '深度思考', icon: 'icon-url' },
{ id: 2, name: '联网搜索', icon: 'icon-url' }
]
}
}
},
onLoad(options) {
// 从路由参数获取智能体信息
this.agentId = options.agentId;
this.agentName = options.agentName || 'AI助手';
}
}
</script>
<style scoped>
.chat-page {
height: 100vh;
background: #f5f5f5;
}
</style>
Mock模式演示
<template>
<view class="demo-page">
<!-- Mock模式,无需真实API -->
<byt-dialogue
:config="demoConfig"
agentId="demo-agent"
agentName="演示助手"
:mockMode="true"
/>
</view>
</template>
<script>
export default {
data() {
return {
demoConfig: {
userInfo: { userId: 'demo-user' },
guess: true,
startup: {
tip: '这是演示模式,您可以体验对话功能'
},
main: { background: 2 }
}
}
}
}
</script>
悬浮窗模式(仅H5/APP)
<template>
<view class="main-page">
<!-- 主页面内容 -->
<view class="content">
<button @click="openChat">打开AI助手</button>
</view>
<!-- 悬浮对话窗 -->
<!-- #ifndef MP-WEIXIN -->
<byt-dialogueFloating
v-model:show="showFloating"
v-model:type="floatingType"
:typeButton="true"
/>
<!-- #endif -->
</view>
</template>
<script>
export default {
data() {
return {
showFloating: false,
floatingType: 1 // 1:悬浮 2:吸附 3:全屏
}
},
methods: {
openChat() {
this.showFloating = true;
}
}
}
</script>
🚀 高级功能
1. 深度思考模式
// 在config.toolList中配置深度思考工具
toolList: [
{
id: 1, // 深度思考必须使用ID=1
icon: 'deep-think-icon',
activeiIcon: 'deep-think-active-icon',
name: '深度思考'
}
]
2. 图表数据展示
插件支持多种图表类型:
// 消息类型配置
typeWhiteList: [
'text', // 文本消息
'chart', // 图表数据
'tables', // 表格数据
'image', // 图片消息
'activity', // 活动卡片
'coupon', // 优惠券卡片
'goods' // 商品卡片
]
3. 自定义主题
// 完全自定义主题色彩
colorIcon: {
mainColor: '#your-brand-color',
assistColor: '#your-assist-color',
textMainColor: '#your-text-color',
userBgColor: '#your-user-bg-color',
userTextColor: '#your-user-text-color',
// 自定义图标
sendRightIcon: 'your-send-icon-url',
copyIcon: 'your-copy-icon-url',
refreshIcon: 'your-refresh-icon-url'
}
4. 响应式适配
// 组件自动适配不同屏幕尺寸
// 大屏(>=700px)和小屏会使用不同的背景图
main: {
background: 1, // 自动选择对应尺寸的背景图
role: 1 // 角色装饰图也会自适应
}
❓ 常见问题
Q: 如何获取智能体ID?
A:
- 有智能体列表:调用智能体列表接口,用户选择后传入ID
- 使用默认智能体:不传agentId,组件会自动获取默认智能体
Q: Mock模式和正式模式有什么区别?
A:
- Mock模式: 使用模拟数据,无需真实API,适合演示和开发
- 正式模式: 连接真实API,需要配置完整的接口地址和token
Q: 小程序如何配置API?
A: 小程序需要单独的配置文件 ai-agent-config-mp.js
,组件会自动加载
Q: WebSocket连接失败怎么办?
A:
- 检查WebSocket地址配置是否正确
- 确认token是否有效
- 查看网络连接状态
- 组件提供自动重连和手动重连功能
Q: 如何自定义消息类型?
A:
- 在
typeWhiteList
中添加新类型 - 在对应的组件中处理新类型的渲染逻辑
Q: 如何禁用某些功能?
A:
config: {
audio: false, // 禁用语音功能
quickShow: false, // 禁用快速提问
moreListShow: false, // 禁用更多工具
guess: false // 禁用推荐问题
}
Q: 如何监听对话事件?
A: 组件内部处理所有对话逻辑,如需扩展可以通过修改对应的方法:
// 在组件的methods中可以监听各种事件
problemClick(name) {
// 推荐问题点击
console.log('用户点击推荐问题:', name);
this.sendMessage();
},
sendMessage() {
// 消息发送前的处理
console.log('发送消息:', this.message);
// ... 原有逻辑
}
📞 技术支持
如有其他问题,请:
- 查看插件源码中的详细注释
- 参考
pages
目录下的示例页面 - 联系技术支持团队
🎉 享受与AI的智能对话吧!