美妆客服工作台

双角色实时客服演示项目。客户端与客服工作台分别监听 8000、8001 端口，共享业务数据库、媒体文件和分析记录。

主要功能

• 客户端：聊天、商品浏览、订单查询、售后进度查询。
• 客服工作台：客户沟通、订单和售后管理、商品管理、情绪风险、知识库与数据飞轮。
• 接待辅助：默认使用业务规则生成即时预案；客服主动触发分析时，结合会话与知识库生成 AI 建议。
• 业务数据：支持 Excel 工作簿预览、校验和确认导入。

本地启动

需要 Python 3.11+ 和 uv。在项目根目录运行：

uv sync
cp .env.example .env

在 .env 中填写所用模型的 DEEPSEEK_API_KEY 或 GLM_API_KEY，然后选择一个启动器：

uv run python start_all_deepseek.py
# 或
uv run python start_all_glm.py

也可以运行 uv run python start_all.py --profile deepseek（或 glm）。启动器会检查两端健康状态，并把进程日志写入 runtime_data/logs/。三个启动脚本跨平台通用，Windows 上同样用上面的命令启动即可。

不使用模型启动器时，可以在两个终端分别运行：

uv run python -m backend.app.cli --role customer
uv run python -m backend.app.cli --role customer_service

本地入口：

服务	地址
客户端	http://127.0.0.1:8000/
客服工作台	http://127.0.0.1:8001/workspace/chat
健康检查	http://127.0.0.1:8000/health、http://127.0.0.1:8001/health

两端均提供 /docs API 文档。已运行的客服端可通过 GET /api/v1/management/model-route 查看模型，并向同一路径发送 POST {"profile":"deepseek"} 或 POST {"profile":"glm"} 切换配置。

配置与数据

.env.example 列出可用配置。GLM 默认使用 Z.AI 兼容接口；使用其他兼容平台时，同时设置 GLM_BASE_URL 和 GLM_MODEL。未配置模型密钥时，业务数据功能仍可用，在线 AI 分析不可用。

默认运行数据位于 runtime_data/，包括 SQLite 数据库 app.db、media/、assistant/ 和 logs/。可用 APP_DATABASE_URL、APP_MEDIA_DIR、APP_ASSISTANT_DIR 等变量覆盖。知识文档与契约分别位于 backend/rag/docs/、backend/rag/contract/。升级已有数据库前请先备份；应用启动时会执行 Alembic 迁移。

代码主要分为 backend/app/（入口和 API）、backend/agent/（接待辅助）、backend/persistence_data/（数据库）、backend/rag/（知识检索）和 frontend/（客户端及工作台）。知识契约辅助工具在 other/tools/。

线上访问与部署

• 客服工作台：kefu.tianfangdianjing.top/workspace/
• 客户端：kehu.tianfangdianjing.top/workspace/

服务器维护说明见 deploy/README.md。发布时需要保留服务器上的 .env、数据库、媒体及分析数据，并检查两个 systemd 服务及对外地址。

回复与预案

AI 卡片由在线模型生成。自动预案仅匹配人工审核通过的飞轮规则；未命中时不显示预案，不生成固定兜底话术。使用不适及人工升级场景继续阻止普通自动预案。

backend/agent/auto_plan.py 负责已审核规则匹配；backend/agent/flywheel/seed_lexicon.json 仅供历史话术学习。旧硬编码路由与闲置回复校验链已移除。