[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82172":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":8,"rankLanguage":8,"license":8,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":8,"pushedAt":8,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":14,"starSnapshotCount":14,"syncStatus":15,"lastSyncTime":27,"discoverSource":28},82172,"smart-appointment-ai-agent","jerry-ai-dev\u002Fsmart-appointment-ai-agent","jerry-ai-dev",null,"Python",36,16,28,1,0,2,7,8,6,3.69,false,"master",true,[],"2026-06-12 02:04:23","# Smart Appointment AI Agent\n\nSmart Appointment AI Agent 是一个面向按摩门店场景的智能预约与咨询系统。项目基于 FastAPI、LangChain、FAISS、SQLite 和多 Agent 协作架构，实现了意图识别、RAG 知识问答、技师智能匹配、预约管理、用户行为分析和个性化提醒等能力。\n\n这个项目的核心目标不是只做一个普通的预约表单，而是尝试把门店前台日常需要处理的高频工作自动化：理解用户想咨询还是预约，判断服务偏好，匹配合适技师，检查可用时间，生成预约结果，并在必要时结合天气、历史行为和偏好数据给出更贴近用户的提醒与推荐。\n\n## 项目背景\n\n在一次按摩门店体验中，我注意到前台人员需要同时处理大量复杂事务：技师排班、顾客预约、服务项目咨询、价格计算、临时改约、技师偏好记录和收款确认等。随着技师数量和顾客量增加，传统人工前台模式很容易出现沟通成本高、信息遗漏、排班冲突和服务体验不稳定的问题。\n\n因此，本项目尝试用 AI Agent 的方式重构这一流程：让系统能够像一个智能前台一样主动理解用户需求，并把不同任务分发给对应的专业 Agent 处理。它既适用于按摩门店，也可以扩展到其他需要人员排班、预约调度和智能客服的服务行业。\n\n## 核心能力\n\n- **智能任务分类**：自动识别用户是在咨询服务、预约技师、查询无关问题，还是触发用户行为分析，并将请求路由到对应 Agent。\n- **多 Agent 协作**：通过任务分类 Agent、咨询 Agent、预约 Agent 和用户行为 Agent 分工处理复杂流程，减少单个模块的职责膨胀。\n- **RAG 知识咨询**：使用 FAISS 向量索引检索知识库内容，结合大模型生成自然语言回答，支持流式输出。\n- **智能预约管理**：根据用户需求、技师专长、历史偏好和可用时间进行匹配，辅助完成预约确认。\n- **用户行为分析**：记录用户交互与预约行为，分析偏好模式，并用于后续推荐和个性化反馈。\n- **个性化提醒**：在预约完成后，可结合实时天气等外部信息生成更贴近实际场景的提醒。\n- **Embedding 缓存优化**：通过数据库缓存和文件缓存减少重复向量计算，提高知识检索性能。\n- **数据管理能力**：支持知识库、技师信息和用户行为数据的增删改查，并在数据变化后自动维护索引。\n- **日志与兜底机制**：保留关键处理过程日志，在信息不足或异常情况下提供更稳定的降级处理。\n\n## 系统架构\n\n项目采用严格的五层架构，核心原则是：**下层不能反向调用上层**。这样可以避免循环依赖，让业务逻辑、数据访问和接口编排保持清晰边界。\n\n```text\nWeb & Application Layer\n    ↓  app.py, web\u002F：页面、路由入口、系统启动\nAPI Layer\n    ↓  api\u002F：外部接口、请求编排、响应封装\nAgents Layer\n    ↓  agents\u002F：AI Agent、任务路由、对话流程控制\nServices Layer\n    ↓  services\u002F：业务逻辑、推荐算法、向量处理\nDB Layer\n    ↓  db\u002F：数据模型、数据库连接、Repository\n```\n\n### 允许的调用方向\n\n- Web 层调用 API 层\n- API 层调用 Agents 层或 Services 层\n- Agents 层调用 Services 层\n- Services 层调用 DB 层\n\n### 禁止的调用方式\n\n- 下层反向调用上层\n- Web 层绕过 API 直接访问 Services 或 DB\n- Agents 层绕过 Services 直接访问 DB\n- Services 层调用 Agents、API 或 Web\n\n## Agent 设计\n\n### Task Classification Agent\n\n任务分类 Agent 是系统的主调度器，负责分析用户输入、判断任务类型，并把请求分发给合适的专业 Agent。\n\n```text\n用户输入 → 意图分析 → Agent 路由 → 响应协调\n```\n\n主要职责：\n\n- 判断用户意图\n- 维护对话状态\n- 控制不同 Agent 之间的切换\n- 处理无法分类或超出能力范围的问题\n\n### Consultation Agent\n\n咨询 Agent 负责知识问答场景，使用 RAG 流程从知识库中检索相关内容，再结合大模型生成回答。\n\n```text\n任务分类 → 知识检索 → FAISS 相似度搜索 → 流式回答\n```\n\n主要职责：\n\n- 区分咨询问题类型\n- 从知识库检索相关内容\n- 构建提示词\n- 生成自然语言回答\n\n### Appointment Agent\n\n预约 Agent 负责预约相关流程，包括解析用户输入、匹配技师、检查预约信息、生成确认消息等。\n\n```text\n任务分类 → 解析预约需求 → 技师匹配 → 预约确认\n```\n\n主要职责：\n\n- 提取预约时间、服务项目、技师偏好等信息\n- 匹配合适技师\n- 处理信息缺失时的追问\n- 生成预约结果和提醒\n\n### User Behavior Agent\n\n用户行为 Agent 更偏向后台智能分析，不完全依赖用户显式请求。它会根据交互记录、预约历史和偏好数据分析用户行为，为后续推荐提供依据。\n\n```text\n行为记录 → 模式分析 → 偏好更新 → 个性化推荐\n```\n\n主要职责：\n\n- 记录用户行为\n- 分析偏好模式\n- 生成推荐依据\n- 支持主动反馈和个性化服务\n\n## 核心设计思想\n\n### 1. 用任务分类降低系统复杂度\n\n系统并不让一个 Agent 处理所有事情，而是先判断用户意图，再分发给对应模块。这样可以让咨询、预约、行为分析等逻辑保持独立，也更容易扩展新的 Agent。\n\n### 2. 用 RAG 解决专业知识回答\n\n按摩服务相关的项目介绍、注意事项、适用人群等内容更适合通过知识库维护。RAG 能让回答基于可控知识来源，而不是完全依赖大模型自由生成。\n\n### 3. 用用户行为让推荐更个性化\n\n系统会记录用户的咨询、预约和偏好信息。后续在推荐技师或服务项目时，可以结合历史行为，而不是每次都从零开始询问。\n\n### 4. 用分层架构保证可维护性\n\nAgent 负责智能流程，Service 负责业务逻辑，Repository 负责数据访问。每层只关心自己的职责，减少后期修改时的连锁影响。\n\n### 5. 为真实业务场景预留扩展空间\n\n项目目前以本地 SQLite 和单体服务为主，但架构上预留了模型提供商切换、MCP 外部服务接入、后台任务、缓存优化和云端部署的扩展方向。\n\n## 架构图\n\n![System Architecture](.\u002Farchitecture%20.jpg)\n\n## 技术栈\n\n- **后端框架**：FastAPI、Uvicorn\n- **AI 框架**：LangChain\n- **大模型接入**：兼容 OpenAI 格式的模型提供商，例如 Qwen、DeepSeek、Zhipu、OpenAI、Azure OpenAI\n- **向量检索**：FAISS\n- **数据库**：SQLite、SQLAlchemy\n- **RAG 能力**：Embedding、向量索引、知识库检索、提示词构建\n- **流式响应**：Python AsyncGenerator\n- **前端页面**：Jinja2 模板、静态 CSS\n- **外部服务扩展**：MCP，用于天气等外部信息接入\n- **配置管理**：python-dotenv\n- **后台任务**：schedule\n\n## 项目结构\n\n```text\nSmart appointment AI agent\u002F\n├── agents\u002F                         # 多 Agent 智能层\n│   ├── task_classification_agent.py # 任务分类与主路由\n│   ├── consultant_agent.py          # RAG 咨询 Agent\n│   ├── appointment_agent.py         # 智能预约 Agent\n│   ├── user_behavior_agent.py       # 用户行为分析 Agent\n│   ├── task_classification\u002F         # 意图识别、状态管理、路由逻辑\n│   ├── consultant\u002F                  # 知识检索、提示词、回答生成\n│   ├── appointment\u002F                 # 预约解析、技师匹配、消息构建\n│   └── user_behavior\u002F               # 行为记录、偏好管理、模式分析\n├── api\u002F                             # API 编排层\n│   ├── appointment.py               # 预约接口\n│   ├── consultation.py              # 咨询接口\n│   ├── task.py                      # 任务分类接口\n│   ├── chat_handler.py              # 流式聊天处理\n│   ├── technician.py                # 技师管理接口\n│   ├── knowledge.py                 # 知识库管理接口\n│   └── user_behavior_analysis.py    # 用户行为分析接口\n├── services\u002F                        # 业务逻辑层\n│   ├── appointment_service.py       # 预约业务逻辑\n│   ├── knowledge_service.py         # 知识库管理\n│   ├── recommendation_service.py    # 推荐逻辑\n│   ├── technician_service.py        # 技师信息管理\n│   ├── text_embedding.py            # Embedding 与向量处理\n│   └── user_behavior_service.py     # 用户行为服务\n├── db\u002F                              # 数据持久化层\n│   ├── models.py                    # SQLAlchemy 模型\n│   ├── db_router.py                 # 数据库路由\n│   ├── local_db.py                  # 本地数据库操作\n│   ├── base\u002F                        # 数据库基础接口\n│   └── repositories\u002F                # Repository 数据访问封装\n├── config\u002F                          # 配置模块\n│   ├── constants.py                 # 常量与枚举\n│   ├── database.py                  # 数据库配置\n│   ├── model_provider.py            # 模型与 Embedding Provider 工厂\n│   ├── settings.py                  # 应用配置\n│   └── time_config.py               # 时间与排班配置\n├── web\u002F                             # Web 页面层\n│   ├── routes.py                    # 页面路由\n│   ├── templates\u002F                   # HTML 模板\n│   └── static\u002F                      # 静态资源\n├── mcp-server\u002F                      # MCP 外部服务扩展\n├── data\u002F                            # 数据库与缓存目录\n├── tests\u002F                           # 测试用例\n├── app.py                           # 应用入口\n├── requirements.txt                 # Python 依赖\n├── .env.example                     # 环境变量模板\n└── README.md                        # 项目说明\n```\n\n## 快速开始\n\n### 1. 创建虚拟环境\n\n```bash\npython -m venv .venv\n```\n\nWindows PowerShell：\n\n```powershell\n.\\.venv\\Scripts\\Activate.ps1\n```\n\nWindows CMD：\n\n```cmd\n.venv\\Scripts\\activate.bat\n```\n\nmacOS 或 Linux：\n\n```bash\nsource .venv\u002Fbin\u002Factivate\n```\n\n### 2. 安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n### 3. 配置环境变量\n\n复制环境变量模板：\n\n```bash\ncp .env.example .env\n```\n\nWindows PowerShell 可以使用：\n\n```powershell\nCopy-Item .env.example .env\n```\n\n然后在 `.env` 中填写模型和数据库配置。项目支持 OpenAI 兼容格式的大模型与 Embedding 服务。\n\n```env\nMODEL_PROVIDER=qwen\nLLM_API_KEY=your_llm_api_key_here\nLLM_BASE_URL=your_openai_compatible_chat_base_url_here\nLLM_MODEL=your_chat_model_name_here\n\nEMBEDDING_PROVIDER=qwen\nEMBEDDING_API_KEY=your_embedding_api_key_here\nEMBEDDING_BASE_URL=your_openai_compatible_embedding_base_url_here\nEMBEDDING_MODEL=your_embedding_model_name_here\n\nDATABASE_URL=sqlite:\u002F\u002F\u002F.\u002Fdata\u002Fsmart_appointment.db\n\nDEBUG=True\nLOG_LEVEL=INFO\n```\n\n常见配置方向：\n\n- Qwen：使用阿里云百炼或 DashScope 的模型、Base URL 和 API Key。\n- DeepSeek：可用于聊天模型，Embedding 可搭配其他兼容服务。\n- Zhipu：可配置智谱的聊天模型和向量模型。\n- Azure OpenAI：将 `MODEL_PROVIDER` 设置为 `azure`，并补充对应的 Azure OpenAI 环境变量。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --host 127.0.0.1 --port 8000 --reload\n```\n\n如果 8000 端口已被占用，可以换成 8001：\n\n```bash\npython -m uvicorn app:app --host 127.0.0.1 --port 8001 --reload\n```\n\n启动后可以访问：\n\n- Web 页面：http:\u002F\u002F127.0.0.1:8000\n- API 文档：http:\u002F\u002F127.0.0.1:8000\u002Fdocs\n- ReDoc 文档：http:\u002F\u002F127.0.0.1:8000\u002Fredoc\n\n## 测试\n\n运行全部测试：\n\n```bash\npytest\n```\n\n运行单个测试文件：\n\n```bash\npytest tests\u002Ftest_task_classification_agent.py\n```\n\n## 主要页面\n\n- 首页聊天与预约入口：`web\u002Ftemplates\u002Findex.html`\n- 知识库管理：`web\u002Ftemplates\u002Fknowledge_management.html`\n- 技师管理：`web\u002Ftemplates\u002Ftechnician.html`\n- 技师排班：`web\u002Ftemplates\u002Ftechnician_schedule.html`\n- 用户行为分析：`web\u002Ftemplates\u002Fuser_behavior_analysis.html`\n\n## 后续规划\n\n### 更强的 Agent 自主能力\n\n- 增加 Agent 自我反思机制，让系统能够评估回答质量和预约成功率。\n- 引入更完整的多轮推理链，提升复杂预约和冲突处理能力。\n- 根据真实用户反馈优化推荐策略。\n\n### 更完整的多 Agent 协作\n\n- 增加 Agent-to-Agent 通信机制，减少所有任务都依赖主分类器转发的问题。\n- 将用户行为 Agent 的后台分析能力做得更稳定，支持定时任务和主动触达。\n- 把预约、推荐、咨询之间的上下文记忆打通得更自然。\n\n### 生产化能力\n\n- 增加用户登录、权限控制和数据隔离。\n- 增加更完整的异常处理和边界场景覆盖。\n- 优化向量检索性能、缓存策略和响应速度。\n- 支持 Docker 部署、云数据库和更标准的日志监控。\n\n## 项目价值\n\n这个项目把多 Agent、RAG、用户行为分析、预约调度和外部工具接入放在同一个真实业务场景中验证。它既是一个按摩门店智能前台原型，也可以作为学习 AI Agent 工程化、分层架构、RAG 系统和业务自动化的综合实践项目。\n\n\n\n------------------------------------------------------------\n这个项目是我最早开始自学大模型做的项目。上面的内容是当时（2025年7月左右完成的）。\n其实我在计划做更加复杂，符合时代趋势的Agent，预计在9月份完成，会分享在笔记中。\n但是很多朋友问我这个项目能不能参考，所以我索性总结开源了除了。值得一提的是，上面的内容是25年写的，当时如何配置环境，都是传统方法，写在README中，自己配置。 但是在2026年，不管是vibe coding的方法，还是环境配置的方法，都有了极大改进。\n\n我的项目配置的方法，现在都推荐使用SKILL，所以这里有setup-envrionment skill，一键配置。\n我也总结了更多的这个项目，放在2026年，如何包装，如何使用配套资源，面试真题，视频讲解，使用建议在我的大模型笔记中。\n👉 **请关注小红书：[不转到大模型不改名]（id:4740535877) 获取以上所有资源。**\n👉 b站： 骑猪撞宝马71","Smart Appointment AI Agent 是一个面向按摩门店场景的智能预约与咨询系统。该项目基于 FastAPI、LangChain、FAISS 和 SQLite 等技术，实现了意图识别、RAG 知识问答、技师智能匹配、预约管理、用户行为分析和个性化提醒等功能。核心功能包括智能任务分类、多 Agent 协作、RAG 知识检索、智能预约管理和用户行为分析等，旨在通过自动化处理前台日常高频工作来提升服务效率和用户体验。适用于需要人员排班、预约调度和智能客服的服务行业，如按摩门店及其他类似场景。","2026-06-11 04:07:57","CREATED_QUERY"]