更新记录

2.1.35(2025-07-10) 下载此版本

  1. 修改全局api接口配置

2.1.34(2025-06-14) 下载此版本

  1. 修复样式问题

2.1.33(2025-06-12) 下载此版本

  1. 修复样式问题
查看更多

平台兼容性

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
  });
};

说明:

  1. 文件位置: 必须放在 src/service/api/agent-chat.js
  2. 导入方式: 使用项目现有的request工具
  3. 接口格式: 所有接口都使用POST方法,统一配置超时和错误处理
  4. 参数结构: 支持data参数和config配置对象
  5. 错误处理: 统一启用错误提示 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;

小程序配置特点说明:

  1. 自动加载: 组件会在需要时自动动态导入配置文件
  2. 错误处理: 增强的错误捕获和调试信息
  3. 兼容性检查: 自动检测小程序环境和必需API
  4. 环境信息: 提供小程序运行环境详细信息
  5. 调试友好: 详细的控制台日志,便于排查问题
  6. 零配置: 无需在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 };
}

初始化说明:

  1. 平台差异处理:

    • H5/APP: 需要在main.js中手动初始化API配置
    • 小程序: 组件会自动动态导入配置文件,无需手动初始化
  2. 配置文件要求:

    • H5/APP: 必须创建 ai-agent-config.js 并在main.js中导入
    • 小程序: 只需创建 ai-agent-config-mp.js,组件会自动加载
  3. 错误处理:

    • H5/APP环境的初始化错误会在main.js中捕获
    • 小程序环境的配置错误会在组件内部处理
    • 初始化失败不影响主应用运行
  4. 开发建议:

    • 使用Mock模式(VITE_OPEN_MOKE=true)可以跳过API配置
    • 小程序开发更加简便,减少了手动配置步骤

说明:

  1. 路径别名 ~/: 表示项目根目录,确保在不同目录下都能正确引用配置文件
  2. 平台兼容: 使用条件编译区分H5/APP和小程序的初始化方式
  3. 错误处理: 为小程序动态导入添加错误捕获
  4. 异步安全: 小程序使用异步导入避免打包问题

替代方案(如果不支持路径别名):

// 使用相对路径
import { initAiAgent } from './ai-agent-config.js';

// 或使用绝对路径
import { initAiAgent } from '@/ai-agent-config.js';

⚠️ TypeScript 项目注意事项

如果您的项目使用 TypeScript,请确保在 tsconfig.jsoninclude 配置中显式添加根目录下的配置文件:

{
  "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 };
}

说明:

  1. 平台差异处理:

    • H5/APP: 需要在main.ts中手动初始化API配置
    • 小程序: 组件会自动动态导入配置文件,无需手动初始化
  2. 条件编译:

    • 使用 #ifndef MP-WEIXIN 确保只在非小程序环境导入
    • 使用 #ifdef MP-WEIXIN 为小程序环境提供日志信息
  3. 错误处理:

    • 为初始化过程添加try-catch错误捕获
    • 初始化失败不会影响主应用运行
  4. 路径别名:

    • 使用 ~/ 表示项目根目录
    • 如果不支持路径别名,可以使用相对路径:'./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"
    }
  }
}

说明:

  1. easycom 配置

    • autoscan: true:启用自动扫描组件
    • custom:自定义组件匹配规则
  2. 组件匹配规则

    • '^byt-(.*)':匹配所有以 byt- 开头的组件
    • 路径映射到插件组件目录
  3. 支持的组件

    • 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:

  1. 有智能体列表:调用智能体列表接口,用户选择后传入ID
  2. 使用默认智能体:不传agentId,组件会自动获取默认智能体

Q: Mock模式和正式模式有什么区别?

A:

  • Mock模式: 使用模拟数据,无需真实API,适合演示和开发
  • 正式模式: 连接真实API,需要配置完整的接口地址和token

Q: 小程序如何配置API?

A: 小程序需要单独的配置文件 ai-agent-config-mp.js,组件会自动加载

Q: WebSocket连接失败怎么办?

A:

  1. 检查WebSocket地址配置是否正确
  2. 确认token是否有效
  3. 查看网络连接状态
  4. 组件提供自动重连和手动重连功能

Q: 如何自定义消息类型?

A:

  1. typeWhiteList 中添加新类型
  2. 在对应的组件中处理新类型的渲染逻辑

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);
  // ... 原有逻辑
}

📞 技术支持

如有其他问题,请:

  1. 查看插件源码中的详细注释
  2. 参考 pages 目录下的示例页面
  3. 联系技术支持团队

🎉 享受与AI的智能对话吧!

隐私、权限声明

1. 本插件需要申请的系统权限列表:

开启语音识别输入框功能需要录音权限

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

许可协议

MIT协议

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问