快速开始
环境要求
- Node.js >= 18
- npm >= 9 或 pnpm >= 8
- Git
安装
克隆仓库
bash
git clone https://github.com/gitcoffee-os/joycare.git
cd joycare安装依赖
bash
npm install
# 或
pnpm install开发
启动开发服务器
bash
npm run dev
# 或
pnpm dev开发服务器启动后，访问 http://localhost:3000 即可预览。
构建生产版本
bash
npm run build
# 或
pnpm build构建产物将输出到 dist 目录。
项目结构
joycare/
├── apps/ # 应用目录
│ ├── web/ # Web 端客服工作台
│ ├── mobile/ # 移动端应用
│ └── desktop/ # 桌面端应用
├── packages/ # 共享包
│ ├── ui/ # UI 组件库
│ ├── sdk/ # 客服 SDK
│ └── shared/ # 共享工具
├── server/ # 服务端
│ ├── gateway/ # 网关服务
│ ├── chat/ # 对话服务
│ ├── ticket/ # 工单服务
│ └── ai/ # AI 服务
├── docs/ # 文档
└── scripts/ # 脚本配置说明
基础配置
在项目根目录创建 .env 文件：
env
# 服务端地址
VITE_API_BASE_URL=http://localhost:8080
# WebSocket 地址
VITE_WS_URL=ws://localhost:8080/ws
# 应用名称
VITE_APP_NAME=JoyCare多端配置
Web 端
env
# apps/web/.env
VITE_PLATFORM=web
VITE_ENABLE_PWA=true移动端
env
# apps/mobile/.env
VITE_PLATFORM=mobile
VITE_ENABLE_PUSH=true
VITE_PUSH_APP_KEY=your_push_key桌面端
env
# apps/desktop/.env
VITE_PLATFORM=desktop
VITE_ENABLE_SHORTCUT=true使用示例
初始化 SDK
typescript
import { JoyCareSDK } from '@joycare/sdk'
const sdk = new JoyCareSDK({
apiBaseUrl: 'http://localhost:8080',
wsUrl: 'ws://localhost:8080/ws',
appKey: 'your_app_key'
})
await sdk.connect()接入客服对话
typescript
// 创建对话
const conversation = await sdk.createConversation({
channel: 'web',
customerInfo: {
name: '张三',
phone: '13800138000'
}
})
// 发送消息
await sdk.sendTextMessage({
conversationId: conversation.id,
content: '你好，我需要帮助'
})监听消息
typescript
sdk.onMessage((message) => {
console.log('收到消息:', message)
})
sdk.onConversationUpdate((conversation) => {
console.log('对话更新:', conversation)
})
sdk.onTicketUpdate((ticket) => {
console.log('工单更新:', ticket)
})AI 智能客服
typescript
// 启用 AI 自动回复
await sdk.enableAI({
conversationId: conversation.id,
mode: 'hybrid'
})
// AI 转人工
await sdk.transferToAgent({
conversationId: conversation.id,
reason: '客户要求人工服务'
})常见问题
Q: 如何切换开发环境？
A: 使用 .env.development、.env.production 等文件来配置不同环境。
Q: 如何接入新的渠道？
A: 在 packages/sdk/src/channels/ 中实现渠道适配器，并在配置中注册。
Q: 如何配置 AI 对话引擎？
A: 在管理后台的 AI 配置页面设置模型参数、知识库关联和对话策略。