ClearMind

智能客服系统 — 基于 LangGraph ReAct Agent的流式对话引擎，集成 RAG 知识库检索、高德实时天气感知、多轮对话记忆 和 Agent 可观测性追踪。前端原生 HTML/CSS/JS 实现，零框架依赖。

功能展示

核心能力

• 🧠 RAG 智能问答 — ChromaDB 向量检索 + qwen3-max 摘要生成，覆盖扫地机器人选购、保养、故障排查场景。知识库支持 PDF/TXT，MD5 自动去重增量更新
• ⚡ Token 级流式输出 — astream_events 捕获 LLM 生成事件，SSE 逐 token 推送，前端逐字渲染 + 闪烁光标，延迟 < 100ms 首字响应
• 💬 多轮对话记忆 — SQLite 持久化会话历史，滑动窗口（最近 10 条）注入 Agent 上下文，同一会话内自然衔接指代和省略
• 🌤️ 实时天气感知 — 接入高德天气 API + IP 定位，Agent 根据真实温湿度、降雨概率给出个性化保养建议（梅雨季除湿、沙尘天换滤网等）
• 📊 使用报告生成 — 根据用户 ID + 月份检索 CSV 外部数据，LLM 自动生成 Markdown 格式的清洁效率、耗材状态、同行对比报告
• 🔍 Agent 可观测性 — 3 层中间件采集每步 LLM/Tool 调用的延迟与 Token 消耗，SQLite 持久化，内置调试面板实时可视化执行链路
• 🔄 数据源切换 — Provider 模式 + 环境变量 DATA_SOURCE 一键切换 mock/real，开发调试和生产部署无缝衔接
• 🛡️ LLM 韧性 — 指数退避重试 + 错误分类（网络/限流可重试，参数/鉴权直接抛），避免单次抖动导致对话中断

快速开始

环境要求

• Python 3.10+
• DashScope API Key
• 高德 Web API Key（可选）

安装

git clone <repo-url> && cd <repo>
pip install -r requirements.txt

配置

项目根目录创建 API.txt：

sk-xxxxxxxxxxxxxxxxxxxxxxxx

高德 Key 通过环境变量设置：

export AMAP_API_KEY=your_gaode_key_here

或修改 config/agent.yml（参考 config/agent.yml.example）：

amap_api_key: <your-key>

⚠️ API.txt 和 config/agent.yml 中的 API Key 属于敏感信息，已加入 .gitignore，请使用环境变量。

启动

# Mock 数据模式（默认）
python server.py

# 接入真实天气 + IP 定位
DATA_SOURCE=real python server.py

# 访问
open http://localhost:8501

运行测试

pytest tests/ -v          # 全部 36 个测试
pytest tests/ -q          # 精简输出

项目结构

├── server.py                     # FastAPI 入口，SSE + REST API
├── agent/
│   ├── react_agent.py            # LangGraph ReAct Agent，async 流式
│   └── tools/
│       ├── agent_tools.py        # 7 个 LangChain Tool
│       ├── data_provider.py      # Mock/Real 数据源（高德天气）
│       └── middleware.py         # 3 层中间件（sync + async）
├── model/
│   └── factory.py                # ChatTongyi + Embeddings 工厂
├── rag/
│   ├── vector_store.py           # ChromaDB 向量存储 + 文档加载
│   └── rag_service.py            # RAG 检索 → LLM 摘要链
├── db/
│   ├── database.py               # SQLite 连接管理 + 建表
│   └── session_store.py          # 会话/消息 CRUD
├── trace/
│   └── collector.py              # Agent 执行链路采集器
├── config/                       # YAML 配置（Agent/Chroma/RAG/Prompts）
├── prompts/                      # 3 个提示词模板（系统/RAG/报告）
├── static/
│   └── index.html                # 前端 SPA（原生 HTML/CSS/JS）
├── data/                         # 知识库 PDF/TXT + 外部 CSV
├── tests/                        # 36 个 pytest 测试用例
├── assets/                       # 截图展示
├── chroma_db/                    # ChromaDB 持久化目录
├── logs/                         # 日志文件（按日滚动）
└── requirements.txt

中间件体系

中间件	Hook 类型	职责
monitor_tool / async_monitor_tool	@wrap_tool_call	工具调用计时 + 日志 + Trace 采集 + 报告场景标记（sync/async 双版本）
log_before_model	@before_model	模型调用前记录消息数 + LLM 计时锚点
log_after_model	@after_model	Token 消耗提取 + 延迟计算 + Trace 写入
report_prompt_switch	@dynamic_prompt	根据 context 标记动态切换系统提示词为报告模式

技术栈

层	技术
Agent 框架	LangGraph create_agent + ReAct
LLM	DashScope qwen3-max
Embedding	DashScope text-embedding-v4
向量库	ChromaDB via LangChain-Chroma
后端	FastAPI + Uvicorn (port 8501)
流式	SSE + astream_events (token-level)
存储	SQLite (WAL mode, check_same_thread=False)
外部 API	高德地图（天气 + IP 定位）
前端	原生 HTML/CSS/JS + marked.js (CDN)
测试	pytest + pytest-asyncio (asyncio_mode=auto)
LLM SDK	langchain-community ChatTongyi

优化方向

• 对话管理 — 会话重命名、收藏、搜索、导出 Markdown/PDF
• 知识库管理 — 前端上传文档、触发 re-index、查看索引状态
• 真实用户系统 — 替换随机用户 ID，接入用户画像实现个性化推荐
• 流式体验增强 — 中断/停止生成按钮、重新生成、流式 Markdown 增量渲染
• Trace 保留策略 — 按时间/数量自动清理旧 trace 数据，防止 DB 无限膨胀
• Docker 化 — Dockerfile + docker-compose 一键部署
• E2E 测试 — 真实 LLM 调用的回归测试，覆盖 RAG 召回率和报告生成质量
• 移动端适配 — 侧边栏自动收起、底部安全区适配、触控优化