geo-setp/docs/2026-04-13_summary.md

背景

• 新建 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 任意端口联调。
• 已切换到严格 deep-link 模式：所有点必须先完成 POI 校验并拿到 poi_id，成功结果必须包含 deep link，否则直接失败。

下一步建议

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