## 背景

- 新建 `geo-agent` 项目，使用 `uv init` 初始化。
- 目标是基于 `pydantic_ai`、FastAPI 和高德远程 MCP 服务实现多目标地点最优路线规划 Agent。
- 当前开发流程要求先搭框架，再逐步补齐 MCP 接入与业务实现。

## 今日完成

- 检查并确认项目 Python 版本为 3.14.2，满足 `pydantic-ai` 的版本要求。
- 创建基础项目结构，加入 FastAPI 入口、Pydantic 请求/响应模型、Agent 骨架和环境变量模板。
- 安装项目依赖并修正 `pydantic-ai` 当前版本的接入方式。
- 修复运行时报错：
  - `OpenAIModel` 不接受 `openai_client=` 参数，改为 `OpenAIProvider`。
  - `Agent` 改为使用 `toolsets` 挂载 MCP。
  - `result_type` 改为 `output_type`。
  - `run_mcp_servers()` 改为 `async with agent:` 的当前推荐写法。
- 增加 `/healthz` 健康检查接口。
- 为高德远程 MCP 增加显式配置项：URL、传输类型、可选认证头。

## 当前状态

- FastAPI 应用可正常导入和启动。
- `/healthz` 返回 200。
- 高德远程 MCP 已配置到 `.env`，传输方式确认为 `streamable_http`。
- 已验证可连通高德 MCP，并成功枚举出 15 个工具，包括 `maps_geo`、`maps_text_search`、`maps_search_detail`、`maps_direction_driving`、`maps_distance`、`maps_schema_personal_map`、`maps_schema_navi`、`maps_weather` 等。
- `system_prompt` 已注入到 Agent。
- 已实现第一版 prompt-first 路线规划流程：由 system prompt 驱动模型使用高德 MCP 工具完成点位解析、逐段算路、候选路线比较和结构化输出。
- 已增加代码护栏：
  - 请求模型语义校验：固定起点必须提供起点地址；终点不能同时出现在途经点；空字符串会被标准化处理。
  - `.env` 中新增 `ROUTE_MAX_PERMUTATIONS=20`，作为服务侧候选顺序硬上限。
  - 当 `n!` 超过上限时，接口直接返回 422，不进入模型执行。
  - 对 Agent 输出做结构校验：`origin_mode` 必须一致、`resolved_origin`/`resolved_destination` 角色必须正确、`best_route` 必须对应 `candidates` 之一。
- 已完成真实请求验证：
  - 单个途经点请求返回 200，并产生结构化路线规划结果。
  - 4 个途经点请求因 24 个排列超过 20 的限制而返回 422。
- 已新增项目设计文档 `docs/agent_design.md`。
- 已新增前端对接文档 `docs/frontend_api.md`。
- 已补充上游 timeout 配置和 504 错误映射，避免外部超时被混淆为普通 500。
- 已修正 `stops` 非空校验，并更新前端文档中 `deep_links` 与 `summary` 的语义边界说明。
- 已为 FastAPI 增加可配置 CORS 中间件，默认允许本地 `localhost/127.0.0.1` 任意端口联调。

## 下一步建议

- 补充高德远程 MCP 的真实 URL。
- 确认 MCP 传输协议是 `streamable_http` 还是 `sse`。
- 如果远程服务需要认证，补充自定义请求头。
- 在此基础上实现地址解析、候选路线枚举、逐段路线计算和 deep link 生成。