first commit

MeetSpot/project_summary_zh.md

@@ -0,0 +1,45 @@
+# 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 等平台部署。
+*   生产环境通过环境变量管理敏感信息。