城市日导航仪
为任何城市规划一个紧凑的、有天气意识的一天行程。系统：
- 使用Gemini对请求进行分类
- 调用MCP工具（地理、天气、航空、日历、路线、外汇）
- 简化Markdown行程，包括旅行路线、护栏（雨/AQI）和可选货币转换
1） 设置、运行和示例提示
先决条件
- Docker和Docker组合
- Python 3.11+用于本地CLI（可选）
- API密钥（将它们放在
.envrepo根目录下的文件）：
- MCP_API_KEY=dev-KEY（或您自己的） - GEMINI_API_KEY=。.. - EXCHANGERATE_API_KEY=。.. - OPENAQ_API_KEY=。..
创建您的 .env 从示例中选择并填写按键：
cp .env.example .env
# edit .env with your keys可选覆盖（显示默认值）：
- 双子座_MODEL=双子座-2.5克拉预览-09-2025
- 分类_故障日期=2025-11-10
- HTTP_TIMEOUT_SEC=15
- 附近半径M=3000
- NEARBY_LIMIT=1
- ROUTE_PROFILE默认值=英尺
- 管弦乐队=http://localhost:3002（适用于CLI）
设定目标（可选）
start:
docker-compose up --build -d
restart:
docker-compose down && docker-compose up --build -d
stop:
docker-compose down
ps:
docker-compose ps
logs:
docker-compose logs -f mcp_tools orchestrator服务：
- 上的MCP工具APIhttp://localhost:3001（需要标题
X-API-KEY) - 上的Orchestrator APIhttp://localhost:3002
建筑
graph LR
U["Client CLI"]
O["Orchestrator (FastAPI /plan-day SSE)"]
G["Gemini API (LLM)"]
subgraph MCP["MCP Tools (FastAPI)"]
GEO["geo"]
WEA["weather"]
AIR["air"]
RTE["route"]
CAL["calendar"]
FX["fx"]
end
subgraph EXT["External APIs"]
NOM["Nominatim"]
OM["Open-Meteo"]
AQ["OpenAQ"]
OSRM["OSRM"]
NAGER["Nager.Date"]
FXAPI["exchangerate.host"]
end
U -->|"POST /plan-day (SSE)"| O
O -->|"Classify / Plan / Summarize"| G
O -->|"HTTP JSON"| MCP
GEO --> NOM
WEA --> OM
AIR --> AQ
AIR --> OM
RTE --> OSRM
CAL --> NAGER
FX --> FXAPICLI客户端
创建virtualenv并使用uv安装CLI依赖项：
python3 -m venv .venv
source .venv/bin/activate
uv pip install -r client_cli/requirements.txt如何开始
首先，在Docker中启动服务（MCP工具和编排器）：
docker-compose up -d --build交互模式（具有细化/比较和缓存的多回合会话）：
source .venv/bin/activate
python3 client_cli/main.py -i
# Then type prompts like:
# Plan a museum-first day in Amsterdam on 2025-11-22. Bike preferred.
# add a specialty coffee stop near the second venue
# compare two options if it rains after 3 PM
# convert 500000 Japanese Yen to Indian Rupee
# EXPORT # saves the entire session's streamed output (all turns) to ./itinerary-YYYYmmdd-HHMMSS.md您将在stderr中看到流媒体工具跟踪，在stdout中看到Markdown。
使用结构化参数运行CLI（单圈）：
source .venv/bin/activate
python3 client_cli/main.py "Kyoto" "2025-12-12" --prefer "temples" --prefer "walkable"使用自由形式的提示（单圈）运行CLI：
source .venv/bin/activate
python3 client_cli/main.py --prompt "Plan 10:00–18:00 in Kyoto on 2025-12-12. Prefer temples and walkable"在提示中包含货币转换（编排器将调用MCP FX）：
source .venv/bin/activate
python3 client_cli/main.py --prompt "Plan a day in Tokyo on 2025-11-20. Also convert 200 USD to JPY"笔记：
- EXPORT仅在交互模式下可用，并保存到当前工作目录。
- 交互式会话会自动使用session_id，因此后续跟进会完善/比较相同的计划。
- 纯外汇跟进（例如，“将200美元兑换成日元”）短路计划，只返回兑换。
- 纯AQI/天气/假期跟进（例如，“京都的AQI是什么？”，“2025年12月12日京都的天气”，“今年日本的公共假期”）也会缩短并返回紧凑型表格，而不会生成行程。
- 你可以将这些结合起来（例如，“京都的空气质量指数和今年日本的公共假期？”）；编排器将在一个响应中返回多个紧凑的部分，但仍然不会生成行程。
- 确定性：对于相同的提示/上下文，停止顺序和ETA是稳定的（温度为0的模型、附近的确定性排序和计划/ETA缓存）。
快速健康检查
curl -s -H "X-API-KEY: ${MCP_API_KEY:-dev-key}" http://localhost:3001/ | jq
curl -s http://localhost:3002/plan-day -X POST \
-H "Content-Type: application/json" \
-d '{"prompt":"Plan a museum-first day in Amsterdam on 2025-11-22. Bike preferred."}'2） 使用的API端点和请求示例
外部API（免费/无密钥或公共层）
- Open Meteo（天气预报）：
- 基地： https://api.open-meteo.com/v1/forecast - 例子：
curl -G "https://api.open-meteo.com/v1/forecast" \
--data-urlencode "latitude=35.0116" \
--data-urlencode "longitude=135.7681" \
--data-urlencode "hourly=temperature_2m,precipitation_probability,windspeed_10m" \
--data-urlencode "timezone=UTC"- OpenAQ v3（空气质量观测）：
- 基地： https://api.openaq.org/v3 - 示例（最近的坐标，重复的参数）：
curl -G "https://api.openaq.org/v3/latest" \
-H "X-API-Key: $OPENAQ_API_KEY" \
--data-urlencode "coordinates=40.7128,-74.0060" \
--data-urlencode "radius=25000" \
--data-urlencode "limit=50" \
--data-urlencode "parameter=pm25" \
--data-urlencode "parameter=pm10" \
--data-urlencode "parameter=no2" \
--data-urlencode "parameter=o3"- 提名/开放街道地图（地理编码+地点）：
- https://nominatim.openstreetmap.org/search - https://nominatim.openstreetmap.org/reverse
- OSRM演示（路由和ETA）：
- https://router.project-osrm.org/route/v1/{profile}/{lon},{lat};{lon},{lat}
- 纳格。日期（公众假期）：
- https://date.nager.at/api/v3/PublicHolidays/{year}/{countryCode}
- 汇率.费用（外汇汇率）：
- 最新的： https://api.exchangerate.host/latest - 转换： https://api.exchangerate.host/convert?from=USD&to=JPY&amount=200
- Open‑Meteo空气质量（如果OpenAQ没有附近的观测数据，则回退）：
- https://air-quality-api.open-meteo.com/v1/air-quality
MCP工具（本地）和示例
所有MCP端点都需要 X-API-KEY 头球
- 地理编码
- 发布 http://localhost:3001/geo/geocode - 主体： { "city": "Kyoto", "country_hint": "JP" }
- 附近的地方（提名搜索）
- 发布 http://localhost:3001/geo/nearby - 主体： { "lat": 35.0116, "lon": 135.7681, "query": "coffee", "radius_m": 3000, "limit": 3 } - 确定性：结果按距中心的距离排名，然后按稳定排序的名称排名。
- 天气预报（Open Meteo）
- 发布 http://localhost:3001/weather/forecast - 主体： { "lat": 35.0116, "lon": 135.7681, "date": "2025-12-12" }
- 空气质量（OpenAQ v3，支持Open‑Meteo回退）
- 发布 http://localhost:3001/air/aqi - 主体： { "lat": 40.7128, "lon": -74.0060 }
- 路线/预计到达时间（OSRM）
- 发布 http://localhost:3001/route/eta - 主体： { "points": [{"lat": 35.0,"lon":135.7},{"lat":35.02,"lon":135.76}], "profile": "foot" }
- 公共假日（Nager.Date）
- 发布 http://localhost:3001/calendar/holidays - 主体： { "country_code": "JP", "year": 2025 }
- 外汇兑换（汇率.host）
- 发布 http://localhost:3001/fx/convert - 主体： { "amount": 200, "from": "USD", "to": "JPY" } - 答复： { "rate": , "converted": }
编排器（流SSE）：
- 发布
http://localhost:3002/plan-day - 主体：
{ "prompt": "Plan 10:00–18:00 in Kyoto on 2025-12-12. Prefer temples and walkable", "session_id": "" } - 排放物：
- tool_trace 每个工具调用的条目及其持续时间 - plan_chunk 带有Markdown段的条目 - 带有持续时间的最终“工具跟踪摘要”Markdown表 - [DONE] 完成时
- 短路提示：
- 仅限外汇（例如，“将200美元兑换成日元”）→ 紧凑型FX表 - 仅限空气质量指数（例如，“2025年12月12日京都空气质量指数？”）→ 紧凑型AQI表 - 仅限天气（例如，“2025年12月12日京都的天气？”）→ 紧凑型气象表 - 仅限假期（例如，“2025年日本的公共假期？”）→ 紧凑型假日餐桌 - 上述任何一项的组合（例如，“京都的空气质量指数，将200美元兑换成日元”）→ 多个紧凑的部分，没有行程
3） 关于Gemini路由和摘要提示的说明
意图分类
系统说明：
- “你是一个对用户请求进行分类的助手。只使用JSON对象进行响应。”
模型必须生成：
{
"intent": "plan_day | refine_plan | compare_options",
"city": "string",
"date": "YYYY-MM-DD",
"country_code": "2-letter ISO",
"preferences": ["..."]
}如果分类不是 plan_day 但是提示包含货币转换（例如，“将200美元转换为日元”），编排器会短路到FX工具，并返回一个包含汇率和转换金额的小Markdown块。像“日元”或“印度卢比”这样的货币短语被标准化为ISO代码。
细化与比较：
refine_plan：使用之前的会话上下文（地理编码/天气/空气/假期）根据细化说明重新规划场地，确定地重新计算附近+预计到达时间，并总结细化的行程。compare_options：使用现有会话上下文生成两个可选的Markdown行程（“选项A”和“选项B”），而无需重新调用外部工具。
场馆规划提示
对规划者的输入包括：
- 天气摘要、空气质量摘要、假期、偏好、基本地理编码
Planner返回一个包含4-6个场地名称或类型的JSON数组。 然后，编排器查询附近的每个项目，并构建一个路由点列表。 确定性：模型在温度为0的情况下运行，对附近的结果进行确定性排序，每个上下文计划缓存（城市/日期/国家/偏好/坐标/配置文件/半径/限制）确保相同的停止顺序和重复相同提示的ETA。
路线和预计到达时间
当至少有两个点时，编排器会调用路线ETA工具(OSRM)使用默认配置文件（脚/自行车/汽车）。结果包含在两站之间的行程中。
摘要提示
最终的系统指令需要一个Markdown行程，并明确要求：
- 在行程点之间插入带有ETA的旅行航段
- 如果降雨概率>60%，则添加室内重型替代路段
- 如果PM2.5>75μg/m³，请在室外部分添加“推荐口罩”或建议室内更换
- 在相关情况下添加假期提醒
- 当存在外汇时，包括“货币兑换”部分
对于最终的流式输出，编排器使用文本配置的模型实例（温度为0）来确保稳定的Markdown文本。每个响应都以一个“工具跟踪摘要”表结束，以查看调用了哪些工具及其持续时间。
故障排除
- “此演示仅支持plan_day意图。”\
使用计划提示，或仅在外汇中包含货币表达式，如“将200美元兑换成日元”。
- 未来日期缺少空气数据\
OpenAQ只是观察性的。气动工具自动丢弃未来日期，并获取坐标附近的最新测量值；它还包括一个Open Meteo回退。
- 输出中没有FX部分\
确保您的提示包含可识别的转换短语（例如，“将200美元转换为日元”），并且 EXCHANGERATE_API_KEY 如果您的帐户需要，则设置。
- 来自OpenAQ的401/403\
确保 OPENAQ_API_KEY 有效期为 .env 在容器中可见。
4） 测试（验收）
包含最低限度的验收测试，以通过编排器端到端验证核心行为，而无需深度模拟。
如何跑步：
- 启动服务：
docker-compose up -d --build- （可选）创建/激活venv并安装dev-deps：
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt- 运行测试文件：
pytest -v -rA tests/test_acceptance.py测试的作用（简要总结）：
- 基本计划：检查京都计划是否包括天气信息、至少一个预计到达时间/行程以及多站。
- 雨天回退：在已知的雨天测试日期，验证是否包括室内重型替代品。
- 空气护栏：在PM2.5检测日，验证“推荐口罩”或建议室内更换。
- 假日意识：在假日，验证对关闭/人群的警告。
- 仅限外汇：验证“将200美元转换为日元”仅返回货币转换（无行程）。
- 跟踪可见性：验证是否存在列出工具调用和持续时间的最终“工具跟踪摘要”表。
示例提示
- “计划在2025-11-22在阿姆斯特丹的第一天建立博物馆。喜欢自行车。”
- “改进：在第二个地点附近增加一个特色咖啡站。”
- “如果下午3点后下雨，比较两个选项。”
- “计划2025-11-20在东京度过一天。也将200美元兑换成日元。”