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.py
app/chatbot_service/prompts/（knowledge_variables · long_prompt · agent_style）

其餘硬編碼輔助 Prompt：input_parser_templates.py、info_verification_templates.py（同目錄）。

以往版本

點擊進入版本目錄（含索引與各版詳情）：

→ docs/prompt-model-versions/

版本	鏈接
0.2.0（現行）	`0.2.0.md`
0.1.0	`0.1.0.md`
0.0.1	`0.0.1.md`

快速開始

前置

安裝 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 -q

Viola 主鏈配置

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/`

Spec	主題
044	多 worker 部署
045	配置跨進程同步（當前）
實施全序	Speckit 步驟表

倉庫結構

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）
一致性基線	環境與行為基線

源碼

載入源碼…