← 项目
AI客服系统
客服app介绍
说明
这是一套跑在 WhatsApp 上的客服系统。
客户发消息进来，能自动回的就先回，依据是你们自己维护的知识库。碰到报价、要上门、或者知识库里没有的内容，会转给坐席。坐席在浏览器里看对话、回复、补知识，不用盯着手机逐条回。
源码
加载源码…
源码
| 文件名 | 类型 |
|---|---|
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 目录 | |
| 文件 | |
| 文件 | |
| 文件 | |
| 文件 | |
| 文件 | |
| 文件 | |
| 文件 | |
| 文件 | |
| Dockerfile | |
| Dockerfile | |
| Markdown | |
| Markdown | |
| 文件 | |
| Markdown | |
| Markdown | |
| Markdown | |
| 文件 | |
| 文件 | |
| Markdown | |
| Python | |
| YAML | |
| Python | |
| Python | |
| 文件 | |
| 文件 | |
| 文件 | |
| 文件 | |
| TOML | |
| Python | |
| Python | |
| Python | |
| 文件 | |
| 文件 |
Customer Service
WhatsApp 客服平台 — 自動回覆主鏈 · 坐席 Portal · 知識庫 RAG · Drive 媒體。
Backend（FastAPI）承接 Twilio webhook、Portal API、審計與存儲；Viola-agent 負責對話編排、模型路由，並透過 MCP 回調 backend 能力。
功能亮點
- WhatsApp 入站 — Twilio webhook、burst 合併、轉人工 / 固定回覆
- Viola 主鏈 —
full硬切編排，MCP 調用 backend 業務能力 - 坐席 Portal — 即時聊天、知識填空、媒體預覽、系統日誌
- 知識庫 RAG —
knowledge+ Portal 同步重建 FAISS - 多 worker — Redis 協調 burst、會話鎖與推送（044 / 045）
架構
組件總覽
| 組件 | 職責 |
|---|---|
| Backend | Webhook、Portal、認證審計、存儲、灰度與回退 |
| Viola-agent | 對話主鏈、模型與工具路由、MCP |
| Portal | 坐席聊天、知識運營、設置與觀測 |
| Redis | 多進程協調 |
入站詳細流程（語義分析 → 轉人工 / AI）
客戶 WhatsApp 文字入站後，Backend 先跑策略鏈（報價專人、行動承諾、關鍵詞、語義 LLM、知識庫缺口等），命中則走 handoff_orchestrator 轉人工；否則進入 Viola / RAG 自動回覆。主入口：POST /webhook → app/webhook/customer_inbound.py。
策略與門控（節選）
| 步驟 | 說明 | 主要開關 |
|---|---|---|
| 報價專人 | 報價 / 尺寸等 → 專人跟進 | CS_QUOTE_SPECIALIST_ENABLED + Portal triggers |
| 行動承諾 | 禁止 AI 代排期等承諾 | CS_ACTION_COMMITMENT_ENABLED（可選語義 LLM） |
| 關鍵詞轉人工 | 明確要找同事 / 人工 | 時段固定回覆配置 allow_handoff_keywords |
| 語義分析 | LLM 判斷是否應轉人工 | CS_HANDOFF_SEMANTIC_LLM=1 |
| 知識庫缺口 | RAG 不足 → 轉人工 | CS_KB_GAP_HANDOFF_ENABLED + Portal |
| Burst 合併 | 短時多則合併再答 | Portal burst_merge / CS_BURST_* |
| AI 主鏈 | Viola 編排回覆 | CS_VIOLA_MAINLINE_MODE |
| 轉人工落點 | 一律 handoff_orchestrator | 可選摘要 CS_HANDOFF_SYNC_LLM_SUMMARY |
部署細節 → deployment/README.md
本版本：硬編碼 Prompt 與大模型（0.2.0）
運行時以倉庫根目錄
.env為準；下表為本版本 0.2.0 基線。詳情 →docs/prompt-model-versions/0.2.0.md。
憲法（Principle III）：凡修改app/chatbot_service/llm_templates/等硬編碼 Prompt，或變更本節記載的大模型基線，必須在同一變更集更新本節、新增版本檔，並更新docs/prompt-model-versions/（見.specify/memory/constitution.md）。
大模型（0.2.0）
| 用途 | 本版本取值 | 環境變量 | 加載入口 |
|---|---|---|---|
| 對話主模型 | gpt-5.1 | OPENROUTER_CHAT_MODEL（別名 OPENROUTER_MODEL） | app/utils/setup_llm.py |
| RAG 嵌入 | text-embedding-3-small | OPENROUTER_EMBEDDING_MODEL | app/chatbot_service/rag.py |
| 來源 | OpenRouter 兼容端點（默認 LLM_SOURCE=openrouter） | LLM_SOURCE / OPENROUTER_BASE_URL | 同上 |
代碼未設 OPENROUTER_CHAT_MODEL 時的回退默認值為 openai/gpt-4.1。本機 Ollama 可設 LLM_SOURCE=ollama 或 CS_LLM_DEPLOY_MODE=gb10_local（見 .env.example）。
硬編碼 System Prompt（0.2.0）
角色對客主 Prompt 寫死在代碼模板中（Portal 長 Prompt / 風格為可選疊加，不替代下列基座）：
| 角色 | 文件 |
|---|---|
一般客服 GENERAL_STAFF | app/chatbot_service/llm_templates/general_staff_templates.py |
技術支援 TECH_STAFF | app/chatbot_service/llm_templates/tech_staff_templates.py |
經理升級 MANAGER | app/chatbot_service/llm_templates/manager_templates.py |
組裝與注入順序（基座 → 知識變量 → Portal 長 Prompt → 風格）：
role_based_handler_templates.pyapp/chatbot_service/prompts/（knowledge_variables·long_prompt·agent_style）
其餘硬編碼輔助 Prompt：input_parser_templates.py、info_verification_templates.py（同目錄）。
以往版本
點擊進入版本目錄（含索引與各版詳情）：
快速開始
前置
- 安裝 Docker / Compose
- 複製環境變量：
cp .env.example .env並填入密鑰 - （可選）本地開發：Python 3.12+、Node.js
一鍵啟動
cd deployment
./up.ps1 -Build# 停止
cd deployment
./down.ps1| Compose 文件 | 服務 |
|---|---|
docker-compose.backend.yml | backend · portal · nginx · redis |
docker-compose.agent.yml | viola-api · viola-gateway |
本地開發
# Backend
poetry install
poetry run uvicorn main:app --reload --port 8000
# Portal（默認 /api → :8000，同域 cookie）
cd frontend
npm install
npm run dev更多 → frontend/README.md
測試
poetry run pytest tests/unit -qViola 主鏈配置
CS_VIOLA_MAINLINE_MODE ≠ off 時，backend 將主鏈轉發至 viola-agent。
| 變量 | 取值 |
|---|---|
CS_VIOLA_MAINLINE_MODE | off · shadow · canary · full |
CS_VIOLA_MAINLINE_FALLBACK_ENABLED | true · false |
CS_VIOLA_MAINLINE_API_BASE | 例如 http://viola-api:8900 |
硬切驗收建議：
CS_VIOLA_MAINLINE_MODE=full
CS_VIOLA_MAINLINE_FALLBACK_ENABLED=false
CS_VIOLA_PREVIEW_ENGINE=viola_mainline此模式下 backend 不應執行 langgraph_mainline。
審計：scripts/cutover/ · 報告：docs/migration/viola-mcp-mainline-report.md
運行時治理（038）
| 類別 | 開關 |
|---|---|
| 統一編排 | CS_UNIFIED_* |
| 會話冷熱 | CS_SESSION_HEAT_ENABLED |
| 雙軌遷移 | CS_DAILY_BATCH_* / trigger_dual_track_rollback() |
| 性能門禁 | CS_PERF_GATE_ENABLED → docs/perf/ |
倉庫結構
app/ Backend 業務與服務
frontend/ 坐席 Portal（React + Vite）
viola-agent/ 對話主鏈 agent
knowledge/ RAG 知識 Markdown
deployment/ 分離 Compose 與啟動腳本
specs/ Speckit 功能規格
docs/ 運維 · 遷移 · runbook
tests/ 單元 / 集成測試Git remotes
本倉庫以本地 origin 為準。請勿綁定舊公司遠端或個人鏡像位址。
文檔索引
| 文檔 | 說明 |
|---|---|
| Deployment | Compose、媒體掛載、容器日誌 |
| Viola agent | Agent 側說明 |
| Frontend | Portal 本地開發 |
| Drive OAuth 重綁 | Drive invalid_grant 處理 |
| Prompt / 模型版本 | 硬編碼 Prompt 與大模型基線（現行 0.2.0） |
| 一致性基線 | 環境與行為基線 |