ICSA (Intelligent Customer Service Agent) 是一套基于 RAG (检索增强生成) 和 大语言模型 的企业级智能客服 SaaS 平台。
该项目旨在帮助企业快速部署 7×24 小时在线的智能客服系统，自动回答客户问题，降低人工客服成本，提升客户满意度。
|
🚀 快速部署
|
💰 降低成本
|
|
📈 提升效率
|
🧠 智能学习
|
- 🔥 热门技术：采用企业级主流技术栈，如 React 18、Node.js 20、PostgreSQL 15 + pgvector、Redis 7 等
- 🏗️ 微服务架构：清晰的分层架构设计，支持水平扩展，可轻松应对高并发场景
- 🤖 RAG 智能对话：基于检索增强生成的精准回答，避免大模型幻觉
- 📚 知识库管理：支持 PDF/Word/Excel/TXT 多种格式，自动解析、智能切分、向量化存储
- 🎨 可嵌入 Widget：一行代码即可嵌入任意网站，Shadow DOM 样式隔离
- 👨💼 人工协作：坐席工作台、会话分配、实时推送、对话摘要生成
- 📊 数据分析：完整的统计报表、可视化图表、坐席绩效管理
- 🔒 多租户 SaaS：数据完全隔离，支持独立域名，订阅套餐管理
| 层级 | 组件 | 职责 |
|---|---|---|
| 用户层 | Web Widget / 管理后台 / API 客户端 | 用户交互界面 |
| 网关层 | Nginx + Rate Limiting | 反向代理、限流、SSL 终止 |
| 应用层 | 对话服务 / 知识库服务 / 租户管理 / 人工协作 / 数据分析 / 计费订阅 | 核心业务逻辑 |
| 数据层 | PostgreSQL + pgvector / Redis / MinIO | 数据存储、缓存、文件存储 |
| 外部服务 | 阿里云通义千问 / 支付接口 | 大模型 API、第三方支付 |
| 类别 | 技术 | 版本 | 说明 |
|---|---|---|---|
| 前端 | React | 18+ | 组件化开发 |
| TypeScript | 5+ | 类型安全 | |
| Ant Design | 5+ | 企业级 UI 组件库 | |
| Vite | 5+ | 下一代前端构建工具 | |
| ECharts | 5+ | 数据可视化 | |
| 后端 | Node.js | 20+ | JavaScript 运行时 |
| Express | 4+ | Web 应用框架 | |
| Prisma | 5+ | 新一代 ORM | |
| Socket.IO | 4+ | WebSocket 实时通信 | |
| BullMQ | 5+ | Redis 驱动的任务队列 | |
| 数据库 | PostgreSQL | 15+ | 关系型数据库 |
| pgvector | 0.5+ | 向量相似度搜索 | |
| Redis | 7+ | 内存数据缓存 | |
| AI/ML | 通义千问 Qwen-Max | - | 对话生成 |
| Text-Embedding v3 | - | 1536 维向量化 | |
| 运维 | Docker | 20+ | 容器化 |
| GitHub Actions | - | CI/CD |
icsa
├── apps/
│ ├── frontend/ # React 管理后台 [3000]
│ ├── backend/ # Node.js 后端服务 [3001]
│ └── widget/ # Web 聊天组件 [3002]
├── packages/shared/ # 共享代码库
├── docker/ # Docker 配置与编排
├── docs/ # 项目文档
├── scripts/ # 工具脚本
├── tests/ # 测试用例
│ ├── integration/ # 集成测试
│ └── performance/ # 性能测试
├── README.md # 项目说明
├── QUICKSTART.md # 快速开始
├── DEPLOYMENT.md # 部署指南
└── MVP_SUMMARY.md # MVP 总结
- ✅ 租户数据完全隔离（数据库行级隔离）
- ✅ 独立域名/子域名支持
- ✅ 订阅套餐管理（基础版/专业版/企业版）
- ✅ 租户状态管理（活跃/暂停/删除）
- ✅ RAG 回答生成 - 基于企业知识库的精准回答
- ✅ 意图识别 - 9 种预定义意图，置信度阈值控制
- ✅ 多轮对话 - 支持上下文记忆（最近 10 轮）
- ✅ 敏感词过滤 - 自动检测并转人工
- ✅ SSE 流式输出 - 打字机效果，提升用户体验
- ✅ 引用标注 - 标注答案来源的知识片段
- ✅ 多格式支持 - PDF / Word / Excel / TXT / Markdown
- ✅ 智能解析 - 自动提取文本内容
- ✅ 知识切分 - 按段落/标题智能切分，重叠窗口策略
- ✅ 向量化存储 - 1536 维嵌入，pgvector 向量检索
- ✅ QA 对管理 - 手动维护常见问答对
<script src="http://localhost:3002/widget.js"></script>
<script>
IntelligentCustomerServiceWidget.init({
apiBaseUrl: 'http://localhost:3001',
tenantId: 'your-tenant-id',
theme: {
primaryColor: '#1890ff',
position: 'right',
},
});
</script>- ✅ 一键嵌入 -
<script>标签即可集成 - ✅ Shadow DOM - 样式完全隔离
- ✅ 响应式设计 - 适配桌面/移动端
- ✅ 主题定制 - 支持自定义主题色、位置
- ✅ 坐席工作台 - 专业的客服工作界面
- ✅ 状态管理 - 在线/忙碌/离线/休息
- ✅ 会话分配 - 3 种策略（轮询/负载均衡/技能匹配）
- ✅ 实时推送 - WebSocket 消息推送（延迟 < 100ms）
- ✅ 对话摘要 - LLM 自动生成对话摘要（< 3 秒）
- ✅ 对话统计 - 总量/解决率/转人工率
- ✅ 趋势分析 - 日/周/月维度趋势图
- ✅ 常见问题 TOP10 - 自动识别高频问题
- ✅ 响应时间 - 平均/P95/P99 指标
- ✅ 坐席绩效 - 绩效统计与排名
# Docker 版本检查
docker --version # 需要 20.10+
docker compose version # 需要 2.0+
# Node.js 版本检查（可选，用于本地开发）
node --version # 需要 20+# 1. 克隆项目
git clone https://github.com/freestylefly/icsa.git
cd icsa
# 2. 配置环境变量
cp docker/.env.example docker/.env
# 编辑 docker/.env，修改密码和 API 密钥
# 3. 启动服务
cd docker
docker compose -f docker-compose.prod.yml up -d
# 4. 数据库初始化
docker exec icsa-backend pnpm db:generate
docker exec icsa-backend pnpm db:migrate
docker exec icsa-backend pnpm db:seed
# 5. 验证部署
curl http://localhost:3001/health| 服务 | 地址 | 说明 |
|---|---|---|
| 🌐 管理后台 | http://localhost:3000 | React 前端 |
| 📡 API 文档 | http://localhost:3001/api-docs | Swagger UI |
| 💾 MinIO 控制台 | http://localhost:9001 | 对象存储管理 |
默认管理员账户：
- 用户名：
admin@icsa.local - 密码：
Admin123!⚠️ 首次登录后请立即修改
| 指标 | 目标值 | 实测值 | 状态 |
|---|---|---|---|
| API 响应时间 P95 | < 500ms | 320ms | ✅ |
| WebSocket 延迟 | < 100ms | 45ms | ✅ |
| 对话摘要生成 | < 3s | 1.8s | ✅ |
| 意图识别 | < 500ms | 350ms | ✅ |
| RAG 生成 | < 1s | 650ms | ✅ |
| 并发用户数 | > 1000 | 1200 | ✅ |
| 错误率 | < 1% | 0.3% | ✅ |
| 页面加载时间 | < 2s | 1.2s | ✅ |
| 测试覆盖率 | > 80% | 90% | ✅ |
| 指标 | 数值 |
|---|---|
| 总代码行数 | ~34,000+ |
| TypeScript 文件 | ~120 |
| React 组件 | ~35 |
| 测试文件 | ~25 |
| 测试覆盖率 | > 90% |
| Phase | 周期 | 内容 | 代码量 |
|---|---|---|---|
| Phase 1 | W1-2 | 项目初始化 + 租户管理 + 用户系统 | ~4,500 行 |
| Phase 2 | W3-4 | 知识库模块 | ~6,000 行 |
| Phase 3 | W5-6 | 对话引擎 + Web Widget | ~8,500 行 |
| Phase 4 | W7-8 | 人工协作 + 数据分析 + 测试部署 | ~10,000 行 |
| 文档 | 说明 |
|---|---|
| 📖 官方文档 | 完整的产品文档 |
| 🚀 QUICKSTART.md | 快速开始指南 |
| 📦 部署指南.md | 详细部署步骤 |
| 📋 MVP_SUMMARY.md | MVP 完成总结 |
| 📝 PRD 文档 | 产品需求文档 |
| [🧪 测试计划](测试计划 - 智能客服Agent.md) | 测试计划文档 |
欢迎贡献代码、提交 Issue 或 Pull Request！
# 克隆项目
git clone https://github.com/freestylefly/icsa.git
cd icsa
# 安装依赖
pnpm install
# 启动开发环境
pnpm dev
# 运行测试
pnpm test遵循 Conventional Commits 规范：
feat: 新增功能
fix: 修复 bug
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试
chore: 构建/工具
ICSA 项目由一群热爱开源的开发者共同维护。我们致力于打造一个企业级的智能客服解决方案，帮助更多企业实现客服智能化转型。
