用户 / CLI / Web
      │
      ▼
API Server (FastAPI :8080)  ── 意图识别 + ChatService
      │ A2A (HTTP JSON-RPC)
      ├── weather_server  :5005  ── MCP(stdio) ── 和风天气 API
      ├── traffic_server  :5006  ── MCP(stdio) ── 高德地图 API
      └── life_server     :5007  ── MCP(stdio) ── MySQL 业务数据 / RAG(政务指南)
                     │
                     ▼
            MySQL (city_service_db)  ← 采集脚本写入真实数据 + 种子兜底

city_service_assistant/
├── api_server.py            # FastAPI 总代理（HTTP 入口）
├── chat_service.py          # 意图识别 + A2A 子代理调度
├── config.py                # 配置（.env）
├── init_db.py               # 建库建表 + 导入种子（--fetch 可选拉取真实数据）
├── memory.py                # 对话记忆 / 用户画像 / 查询历史（MySQL 持久化）
├── main.py                  # CLI 客户端
├── a2a_server/              # 三个 A2A 子代理（weather/traffic/life）
├── mcp_server/              # 三个 MCP 服务（weather/traffic/life）
├── rag/                     # 政务指南 RAG 检索
├── utils/
│   ├── data_provider.py     # 统一数据访问层（real → cache → simulated）
│   ├── spider_weather.py    # 和风天气采集脚本
│   └── spider_amap.py       # 高德地图采集脚本（路况/POI/停车场）
├── scripts/
│   ├── start_all.py         # 一键启动 4 个进程
│   ├── stop_all.py          # 一键停止
│   └── a2a_smoke.py         # A2A 冒烟测试
├── sql/
│   ├── create_all_tables.sql  # 建库建表（13 张表）
│   ├── insert_seed_data.sql   # 基础种子数据
│   └── seed_enhance.sql       # 种子数据增强补丁（init_db 自动应用）
├── static/index.html        # 简单 Web 演示页
└── tests/                   # 单元测试

# 1. 克隆并安装依赖
git clone <your-repo-url>
cd city_service_assistant
python -m venv venv
venv\Scripts\activate            # Windows；Linux/macOS: source venv/bin/activate
pip install -r requirements.txt

# 2. 配置 .env
copy .env.example .env          # Windows；Linux: cp .env.example .env
# 编辑 .env，填入 MySQL 密码与第三方 API Key（见下方「数据与 Key 说明」）

# 3. 初始化数据库（建库建表 + 导入种子数据）
python -m city_service_assistant.init_db
# 可选：初始化后立即拉取真实 API 数据
python -m city_service_assistant.init_db --fetch

# 4. 一键启动全部服务（weather 5005 / traffic 5006 / life 5007 / api 8080）
python -m city_service_assistant.scripts.start_all
# 另开终端：python -m city_service_assistant.scripts.stop_all 可统一停止

# 5. 验证
#   浏览器打开 http://127.0.0.1:8080 或直接调用：
#   curl "http://127.0.0.1:8080/api/agents"
#   curl -X POST "http://127.0.0.1:8080/api/chat" -H "Content-Type: application/json" -d '{"message":"武汉明天天气怎么样"}'
#   也可用 CLI：
#   python -m city_service_assistant.main

# 拉取 10 个城市 3 天天气预报（真实数据）
python -m city_service_assistant.utils.spider_weather --force
# 指定城市
python -m city_service_assistant.utils.spider_weather --force --cities 北京 武汉

# 拉取高德路况 / POI / 停车场
python -m city_service_assistant.utils.spider_amap
python -m city_service_assistant.utils.spider_amap --cities 武汉

python -m pytest tests -v