WoMenQuNaJu/MeetSpot/project_summary_zh.md

MeetSpot 项目分析报告

项目概览

MeetSpot 是一个 AI 驱动的智能代理（Agent），旨在解决多人会面的地点选择问题。与寻找"我附近"的传统地图不同，MeetSpot 基于所有参与者的位置计算"公平中心点"，并推荐能最小化总行程时间且满足特定需求（如安静、商务、停车方便）的最佳场所。

核心特性

• 公平会面点计算: 使用球面几何（Haversine公式）和智能算法计算几何中心，确保对所有参与者公平。
• AI Agent 模式: 基于 ReAct 模式的智能代理 (MeetSpotAgent)，能够处理复杂请求，通过多步推理和工具调用（搜索、计算、评分）生成个性化推荐。
• 双模式智能处理:
  • 规则模式 (0.3-0.8s): 针对简单查询，快速响应。
  • Agent 模式 (3-8s): 针对复杂查询（多地点、多需求），启用 LLM 深度推理。
• 智能评分系统: 结合规则评分（距离、评分、热度）与 LLM 语义评分（与"安静"、"商务"等需求的匹配度）。
• 丰富的场所信息: 基于品牌特征知识库，提供详细的场所属性（WiFi、停车、环境特色等）。

技术架构

后端 (Backend)

• 框架: FastAPI (Python 3.11+)
• 入口: web_server.py (本地开发), api/index.py (生产环境/Vercel)
• 核心逻辑:
  • app/tool/meetspot_recommender.py: 推荐引擎核心，负责地理编码、中心点计算、POI 搜索和排序。
  • app/agent/: AI Agent 实现模块。
    • meetspot_agent.py: 代理核心逻辑 (Think-Act 循环)。
    • tools.py: 工具集封装 (Geocode, CalculateCenter, SearchPOI, GenerateRecommendation)。
• LLM 集成: app/llm.py 封装了 OpenAI 兼容接口，支持 GPT-4, DeepSeek 等模型。

前端 (Frontend)

• 技术栈: 原生 HTML5, CSS3, JavaScript (Vanilla JS)。
• 模板: 使用 Jinja2 (templates/ 目录)。
• 地图集成: 高德地图 (AMap) JS API。

配置 (Configuration)

• 管理: app/config.py 统一管理配置。
• 关键配置: AMAP_API_KEY (高德地图), LLM_API_KEY (AI 模型)。

工作流程 (Agent 模式)

1. 理解任务: Agent 接收用户输入（地点列表、关键词、特殊需求）。
2. 地理编码 (Geocode): 将文本地址转换为经纬度坐标。
3. 计算中心 (Center Calc): 计算所有坐标的最佳几何中心。
4. POI 搜索: 在中心点附近搜索符合关键词的场所。
5. 生成推荐: 结合硬性规则和 LLM 语义理解对场所进行排序，并生成推荐语。

部署支持

• 支持 Vercel, Render, Railway 等平台部署。
• 生产环境通过环境变量管理敏感信息。