assist/README.md

TSP 智能助手

AI 驱动的多租户客服与工单管理系统，支持飞书机器人、WebSocket 实时对话、知识库语义搜索。

功能概览

• 智能对话 — WebSocket 实时聊天 + 飞书机器人（长连接模式），按租户隔离知识库
• 工单管理 — 创建、编辑、删除、飞书多维表格双向同步，AI 生成处理建议
• 知识库 — TF-IDF + 可选 Embedding 语义搜索，支持文件导入、人工验证
• 多租户 — 数据按 tenant_id 隔离，每个租户独立的系统提示词和飞书群绑定
• 数据分析 — 工单趋势、预警统计、满意度分析，支持按租户筛选
• 预警系统 — 自定义规则、多级别预警、批量管理
• Agent 模式 — ReAct 风格 LLM Agent，支持工具调度（知识搜索、车辆查询、飞书消息等）
• 系统管理 — 模块权限控制、流量/成本/安全配置、Token 监控

快速开始

pip install -r requirements.txt
cp .env.example .env   # 编辑填入 LLM API Key、飞书凭证等
python init_database.py
python start_dashboard.py

访问 http://localhost:5000，默认账号 admin / admin123。

系统架构

graph TB
    subgraph Clients["客户端"]
        Browser["浏览器 Dashboard"]
        FeishuBot["飞书机器人"]
        WSClient["WebSocket"]
    end

    subgraph App["应用层"]
        Flask["Flask :5000"]
        WS["WebSocket :8765"]
        FeishuLC["飞书长连接"]
    end

    subgraph Services["业务层"]
        DM["对话管理"]
        KM["知识库"]
        WOS["工单同步"]
        Agent["ReAct Agent"]
    end

    subgraph Infra["基础设施"]
        DB["SQLAlchemy"]
        LLM["Qwen API"]
        Cache["Redis"]
    end

    Clients --> App
    App --> Services
    Services --> Infra

项目结构

src/
├── config/              # 配置管理（unified_config）
├── core/                # 基础设施（数据库、LLM、缓存、认证、ORM 模型）
├── dialogue/            # 对话管理（realtime_chat、dialogue_manager）
├── knowledge_base/      # 知识库（搜索、导入、验证）
├── analytics/           # 监控与分析（预警、Token、AI 成功率）
├── integrations/        # 外部集成（飞书客户端、工单同步）
├── agent/               # ReAct Agent（工具调度）
├── vehicle/             # 车辆数据管理
├── utils/               # 通用工具
└── web/                 # Web 层
    ├── app.py           # Flask 应用
    ├── blueprints/      # API 蓝图（16 个，每个领域一个文件）
    ├── service_manager.py  # 懒加载服务注册
    ├── static/          # 前端资源 (JS/CSS)
    └── templates/       # Jinja2 模板

环境变量

变量	说明	默认值
SECRET_KEY	Flask session 密钥	随机生成
DATABASE_URL	数据库连接串	SQLite
LLM_BASE_URL	LLM API 地址	DashScope
LLM_API_KEY	LLM API 密钥	—
LLM_MODEL	模型名称	qwen-plus-latest
FEISHU_APP_ID	飞书应用 ID	—
FEISHU_APP_SECRET	飞书应用密钥	—
FEISHU_APP_TOKEN	飞书多维表格 App Token	—
FEISHU_TABLE_ID	飞书多维表格 Table ID	—
REDIS_HOST	Redis 地址	localhost
REDIS_ENABLED	启用 Redis 缓存	True
EMBEDDING_ENABLED	启用 Embedding 语义搜索	True
EMBEDDING_MODEL	Embedding 模型	BAAI/bge-small-zh-v1.5

完整变量列表见 .env.example。

技术栈

层级	技术
Web 框架	Flask 3.x + Flask-CORS
ORM	SQLAlchemy 2.x (MySQL / SQLite)
实时通信	websockets (port 8765)
缓存	Redis 5.x + hiredis
LLM	Qwen/DashScope (OpenAI-compatible)
Embedding	sentence-transformers + BAAI/bge-small-zh-v1.5 (可选)
NLP	jieba + scikit-learn (TF-IDF)
飞书	lark-oapi 1.3.x
认证	JWT + SHA-256

数据库

• 开发: SQLite (data/tsp_assistant.db)
• 生产: MySQL via PyMySQL
• 核心表: Tenant, WorkOrder, ChatSession, Conversation, KnowledgeEntry, Alert, Analytics, VehicleData, User

部署

• Docker + docker-compose (MySQL 8, Redis 7, Nginx, Prometheus, Grafana)
• Nginx 反向代理 (80/443 → 5000)
• 默认端口: Flask 5000, WebSocket 8765, Redis 6379, MySQL 3306

详细文档

完整技术文档见 .agents/summary/ 目录，推荐从 index.md 开始阅读。