ai-cs

English | 中文

AI-CS — Intelligent Customer Service

Open-source AI customer service: AI + human agents, self-hostable, configurable, observable.
Ship a website chat widget and an agent dashboard together.

Table of Contents

• Preview
• Live Demo
• Features
• Project Structure
• Quick Start
• Configuration
• Knowledge Base (RAG)
• Multi-Instance WebSocket (Redis)
• Embed Widget (iframe)
• Documentation
• FAQ & Troubleshooting
• Star History
• Community
• Friendly Links
• Contributing
• License

Preview

Marketing homepage

Visitor chat widget

Human agent mode

AI mode

Live Demo

• Homepage: demo.cscorp.top
• Visitor chat: demo.cscorp.top/chat
• Agent login: demo.cscorp.top/agent/login

Features

• Visitor widget (embeddable)
  • Bottom-right chat window via iframe or widget.js
  • AI / human mode, sound notifications, file uploads
  • Optional per-turn web search (visibility configurable in admin)
  • Email capture — expands on first keystroke (optional); auto-hides after submit or first message
  • Session security — per-session access_token required for visitor API / WebSocket (IDOR fix)
• Agent dashboard
  • Paginated conversation list, WebSocket messaging, unread badges
  • Auto-close stale open visitor sessions (settings or .env)
  • Visitor IP & approximate region (ip2region, offline)
  • Live typing draft sync between visitor and agent
  • Multi-model setup (text / image); OpenAI-compatible Chat Completions APIs
  • Prompts, knowledge base + RAG: PDF/DOCX import, document chunks, FAQ-first answers, / FAQ search
  • Offline email — SMTP notify when visitor is offline and left email (human messages only; settings UI)
  • Log center, analytics (widget opens, messages, AI success rate, KB hit rate, etc.)
• Marketing site & SEO — metadata, OG, sitemap, robots.txt
• Optional web search — Serper (API or MCP) or provider-native search

Project Structure

AI-CS/
├── backend/                    # Go: API, WebSocket, AI, RAG
│   ├── controller/
│   ├── service/
│   ├── repository/
│   ├── models/
│   ├── infra/                  # DB, Milvus, ip2region, storage
│   ├── websocket/
│   ├── router/
│   ├── data/                   # ip2region xdb (optional)
│   └── main.go
├── frontend/                   # Next.js: site, widget, agent UI
│   ├── app/
│   ├── components/
│   ├── features/
│   └── public/widget.js
├── doc/
├── scripts/
├── assets/readme/
├── docker-compose.yml
├── docker-compose.prod.yml
└── .env.example

Quick Start (root /.env only)

Copy .env.example to .env and set at least: MYSQL_ROOT_PASSWORD, DB_PASSWORD, ADMIN_PASSWORD, ENCRYPTION_KEY (64-char hex).

Option A — Pre-built images (recommended)

git clone https://github.com/2930134478/AI-CS.git
cd AI-CS
cp .env.example .env
# edit .env, then:
docker-compose -f docker-compose.prod.yml up -d

• Site: http://localhost:3000
  
• Chat: http://localhost:3000/chat
  
• Agent: http://localhost:3000/agent/login (admin / your ADMIN_PASSWORD)

Option B — Build with Docker Compose

docker-compose up -d --build

Option C — Local dev

• Go 1.24+, Node 20.9+, MySQL 8.0+
  
• go run main.go in backend/, npm run dev in frontend/

See the Chinese README for demo-site admin policies, port notes, and full deployment details.

Configuration (root /.env)

Full variable reference is in .env.example and the Chinese README configuration table.

Required for most deployments: database credentials, ADMIN_PASSWORD, ENCRYPTION_KEY, and (for production frontends) NEXT_PUBLIC_API_BASE_URL.

Knowledge Base (RAG)

• Two configs: AI chat (Settings → AI config, Chat Completions) vs embeddings (Settings → vector model, /v1/embeddings).
• Disable Milvus: MILVUS_DISABLED=true — app still runs; RAG off
  
• Strict dependency: MILVUS_REQUIRED=true — exit if Milvus is unavailable
  
• Document chunking + tune RAG_MIN_SCORE (default 0.22) if search returns empty after chunking.

Multi-Instance WebSocket (Redis)

Configure REDIS_URL (or REDIS_ADDR + password) so WebSocket events sync across replicas. Single instance works without Redis.

Embed Widget (iframe)

Paste before </body>. Point iframe src to https://your-domain/chat. The page auto-detects iframe embed mode (no double floating button). See Chinese README for the full HTML snippet, or use frontend/public/widget.js.

Documentation

• 2026-06-11 release notes (Chinese)
• CHANGELOG
• Test checklist (Chinese)
• Full details: Chinese README

FAQ & Troubleshooting

• No sound — browser needs a user gesture before audio
  
• Milvus startup failure — check MILVUS_REQUIRED; use MILVUS_DISABLED=true if you do not need RAG
  
• RAG returns nothing — re-chunk/re-embed documents; lower RAG_MIN_SCORE (default 0.22)
  
• Docker: missing X-User-Id — rebuild frontend; ensure reverse proxy forwards X-User-Id
  
• SEO / OG wrong — set NEXT_PUBLIC_SITE_URL
  
• “Init failed” / MySQL — curl :18080/health, docker logs ai-cs-backend; in Docker use DB_HOST=mysql
  
• Offline email — human agent messages only; visitor must be offline with email saved; configure SMTP in settings
  

Star History

<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=2930134478/AI-CS&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=2930134478/AI-CS&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=2930134478/AI-CS&type=Date" />

Community

• Bugs / feature requests：GitHub Issues (include deployment method and logs; never post API keys or DB passwords)
• QQ group：1106804464. It appears in the demo site footer under Contact.

Friendly Links

• Live demo
• ip2region — offline IP geolocation used by this project
  
• Suggest more links via Issues

Contributing

Issues and PRs welcome. For bugs, include deployment method, backend logs, and redacted .env keys.

License

MIT © 2025 2930134478