多轮会话交互-会议助手

会议室预定系统 (O-Meeting-Room)

基于 FastAPI + WebSocket + LangChain 1.2.0 + LangGraph + MySQL + Loguru 的智能会议室预定系统。

支持 Web 界面 和 钉钉机器人 两种交互方式。

✨ 特性

• 🚀 实时双向通信：WebSocket 实现低延迟交互
• 💬 多轮对话：支持中断恢复的 ReAct 对话系统
• 💾 持久化存储：MySQL 保存会话状态
• 📊 完整日志：Loguru 追踪完整对话链路
• 🎨 美观界面：现代化 Web UI，用户体验优秀
• 🤖 钉钉集成：Stream 长连接机器人，支持多租户隔离
• 📈 可观测性：request_id 全链路追踪，Prometheus 监控
• 🧪 离线评估：完整的 Eval 评测体系

技术栈

核心框架

• Web 框架: FastAPI >=0.115.0
• WebSocket: websockets >=13.0
• ASGI 服务器: Uvicorn >=0.30.0
• LangChain: 1.2.0
• LangGraph: >=0.2.0
• 持久化: MySQL (langgraph-checkpoint-mysql)
• 日志: Loguru >=0.7.0
• 数据校验: Pydantic >=2.0
• 配置管理: OmegaConf >=2.3.0
• 数据库驱动: PyMySQL >=1.1.0, SQLAlchemy >=2.0.0

第三方集成

• 钉钉机器人: dingtalk-stream (长连接 SDK)
• 监控: Prometheus + Grafana
• 评估: 自定义 Eval 框架

项目结构

o-meeting-room/
├── app/
│   ├── agents/              # Agent 核心逻辑
│   │   ├── context.py       # BookingContext 数据类
│   │   └── graph.py         # LangGraph 图定义
│   ├── nodes/               # LangGraph 节点
│   │   ├── code_node/       # 代码节点（ingest, await_user）
│   │   ├── llm_node/        # LLM 节点（react_planner, prompts）
│   │   └── tool_node/       # 工具节点（search_rooms, book_room）
│   ├── api/                 # API 层
│   │   ├── main.py          # FastAPI 应用入口
│   │   ├── websocket_handler.py  # WebSocket 处理器
│   │   ├── meeting_rooms.py  # 会议室管理 REST API
│   │   └── chat_sessions.py  # 会话历史 REST API
│   ├── integrations/        # 第三方集成
│   │   ├── config.py        # 钉钉配置管理
│   │   ├── handler.py       # 钉钉消息处理器
│   │   ├── assistant.py     # 钉钉 AI 助手（LangGraph 集成）
│   │   └── api.py           # 钉钉 OpenAPI 调用
│   ├── core/                # 核心模块
│   │   ├── log.py           # Loguru 日志配置
│   │   └── context.py       # request_id 上下文
│   ├── config/              # 配置模块
│   │   ├── app_config.py    # 配置数据类
│   │   └── config_loader.py # 配置加载器
│   ├── db/                  # 数据库模块
│   │   ├── mysql_pool.py    # MySQL 连接池
│   │   ├── models.py        # 业务数据模型（MeetingRoom, BookingRecord, ChatSession）
│   │   ├── init_db.py       # 数据库初始化
│   │   └── checkpoint.py    # LangGraph checkpoint 配置
│   ├── monitoring/          # 监控模块
│   │   ├── metrics.py       # Prometheus 指标定义
│   │   ├── exporter.py      # Prometheus 导出器
│   │   └── session_tracker.py # 会话追踪器
│   ├── eval/                # 评估系统
│   │   ├── dataset/         # 测试数据集
│   │   ├── evaluators/      # 评估器（槽位填充、任务完成度）
│   │   ├── metrics/         # 指标聚合
│   │   ├── reporters/       # 报告生成
│   │   └── runner/          # 评估执行器
│   ├── llm/                 # LLM 模块
│   │   └── llm_utils.py     # LLM 调用工具
│   ├── mock/                # Mock 模块
│   │   └── meeting_api.py   # Mock 会议室 API
│   ├── utils/               # 工具模块
│   │   ├── env_loader.py    # 环境变量加载
│   │   └── validators.py    # Pydantic 校验模型
│   └── static/              # 前端静态资源
│       ├── index.html       # 主页面
│       ├── monitoring.html  # 监控页面
│       ├── css/             # 样式文件
│       └── js/              # JavaScript 文件
│           ├── app.js       # 主应用逻辑
│           ├── pages/       # 页面组件
│           └── components/  # 通用组件
├── conf/
│   └── app_config.yaml      # 应用配置
├── logs/                    # 日志目录
├── scripts/                 # 脚本
│   ├── run_eval.py          # 运行评估
│   └── generate_cases.py    # 生成测试用例
├── doc/                     # 文档
│   ├── 钉钉Stream机器人接入技术文档.md  # 钉钉集成深度解析
│   ├── 会议室预定设计方案.md
│   ├── LangGraph实现总结.md
│   ├── WebSocket_API使用指南.md
│   ├── 监控技术方案-Prometheus.md
│   └── Eval评测技术方案.md
├── blog/                    # 技术博客
├── dingtalk_bot.py          # 钉钉机器人启动脚本
├── cli.py                   # CLI 入口
├── requirements.txt         # 依赖
├── .env                     # 环境变量
├── start.sh                 # Linux/Mac 启动脚本
└── start.bat                # Windows 启动脚本

快速开始

方式一：使用启动脚本（推荐）

Windows:

start.bat

Linux/Mac:

chmod +x start.sh
./start.sh

方式二：手动启动

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

编辑 .env 文件：

DEEPSEEK_API_KEY=your_api_key_here
MYSQL_PASSWORD=your_mysql_password

3. 初始化数据库

python -m app.db.init_db

4. 启动服务

python -m app.api.main

5. 访问系统

打开浏览器访问：http://localhost:8000

核心架构

WebSocket 通信流程

前端 (Browser)
    ↓ WebSocket (ws://localhost:8000/ws/booking)
FastAPI WebSocket Handler
    ↓
LangGraph (with MySQLSaver)
    ↓
MySQL (持久化)

ReAct + LangGraph 流程

ingest → react_planner → 路由 → validate → tool_search → present → await_user(interrupt)
                                                                        ↓
finish ← tool_book ← validate_book ← ... ← resume(Command) ← 用户输入

状态机

COLLECTING_SLOTS → SEARCHING → AWAITING_SELECTION → CONFIRMING → BOOKED

持久化

• 使用 MySQLSaver 实现会话状态持久化
• 自动管理 checkpoints 和 checkpoint_writes 表
• 支持中断恢复（interrupt/resume）

日志规范

所有节点使用 Loguru 记录日志，格式：

2026-05-22 10:30:45.123 | INFO     | request_id - abc-123 | app.nodes.code_node.ingest:run:25 - 处理完成: phase=COLLECTING_SLOTS

开发计划

阶段	内容	状态
P0	数据类+Mock+MySQLSaver配置	✅ 已完成
P1	图+interrupt+Loguru日志	✅ 已完成
P2	接LLM+校验+book闭环	✅ 已完成
P3	业务数据模型+预订记录存储	✅ 已完成
P4	Web UI + WebSocket 实时通信	✅ 已完成
P5	钉钉 Stream 机器人集成	✅ 已完成
P6	Prometheus 监控 + 可观测性	✅ 已完成
P7	Eval 离线评估系统	✅ 已完成
P8	会话历史管理 + UI 优化	✅ 已完成