地理空间问题选型：按直线几何、道路路由和旅行时间需求选择…

在回答距离、邻近、包含、路径、区域或覆盖范围等地理空间问题时，先判断是纯几何还是需要真实道路/交通/旅行时间，再选择离线几何工具或 Mapbox 路由 API。

适用场景

解决思路

1. 核心原则：先判断问题类型——纯几何/空间计算用 Turf.js 离线几何工具；需要真实世界路由、交通、旅行时间用 Mapbox routing/navigation APIs。
2. 决策框架：直线距离（as the crow flies）→ offline geometric，因为对几何距离准确。
3. 决策框架：道路/路径距离（as the crow drives）→ Routing API，因为只有路由 API 知道道路网络。
4. 决策框架：旅行时间 → Routing API，因为需要带速度/交通数据的路由。
5. 决策框架：点包含（X 是否在 Y 内）→ offline geometric，因为纯几何操作。
6. 决策框架：地理形状（buffers、centroids、areas）→ offline geometric，因为数学/几何操作。
7. 决策框架：交通感知路由 → Routing API，因为需要实时交通数据。
8. 决策框架：路线优化（最佳访问顺序）→ Routing API，因为复杂路由算法。
9. 决策框架：高频检查（如实时地理围栏）→ offline geometric，因为即时响应、无延迟。
10. 距离计算：用户问「How far is X from Y?」时先澄清是直线距离还是道路距离。
11. 距离计算：直线距离（as the crow flies）→ `distance_tool`，准确且即时。
12. 距离计算：驾车距离（as the crow drives）→ `directions_tool`，只有路由知道实际道路距离。
13. 距离计算：步行/骑行距离 → `directions_tool`，因为需要特定路径网络。
14. 距离计算：旅行时间 → `directions_tool` 或 `matrix_tool`，因为需要带速度数据的路由。
15. 距离计算：带当前交通的距离 → `directions_tool`（driving-traffic），因为需要考虑实时交通。
16. 距离计算示例：5 个仓库之间距离——直线 → `distance_tool`（10 次计算，即时）；驾车 → `matrix_tool`（5×5 矩阵，一次 API 调用，返回实际路线距离）。
17. 距离计算关键：使用与上下文中「distance」含义匹配的工具；总是澄清 crow flies 还是 crow drives。
18. 邻近与包含：『Within X meters radius』→ `distance_tool` + filter。
19. 邻近与包含：『Within X minutes drive』→ `isochrone_tool` → `point_in_polygon_tool`。
20. 邻近与包含：『Inside this polygon』→ `point_in_polygon_tool`。
21. 邻近与包含：『Reachable by car in 30 min』→ `isochrone_tool`。
22. 邻近与包含：『Nearest to this point』→ `distance_tool`（几何）或 `matrix_tool`（路由），取决于「nearest」的定义。
23. 邻近与包含示例：200 个地址是否在 30 分钟配送区——先创建 zone → `isochrone_tool`（routing API），再检查地址 → `point_in_polygon_tool`（geometric，200 次即时检查）。
24. 邻近与包含关键：创建旅行时间区域用 routing，包含检查用 geometric。
25. 路由与导航：A 到 B 路线 → `directions_tool`。
26. 路由与导航：多停靠点的最优顺序 → `optimization_tool`。
27. 路由与导航：清理 GPS trace → `map_matching_tool`。
28. 路由与导航：只需 bearing/compass direction → `bearing_tool`。
29. 路由与导航：带交通的路线 → `directions_tool`（driving-traffic）。
30. 路由与导航：固定顺序 waypoints → `directions_tool` with waypoints。
31. 路由与导航示例：从 hotel 到 airport——需要 turn-by-turn → `directions_tool`；只需知道「在东北方」→ `bearing_tool`。
32. 路由与导航关键：实际导航用 routing tools，方向信息用 geometric tools。
33. 区域与形状：简单圆形 buffer → `buffer_tool`。
34. 区域与形状：旅行时间区域 → `isochrone_tool`。
35. 区域与形状：计算面积大小 → `area_tool`。
36. 区域与形状：简化复杂边界 → `simplify_tool`。
37. 区域与形状：找形状中心 → `centroid_tool`。
38. 区域与形状示例：每家店 5km coverage——5km 半径 → `buffer_tool`（几何圆）；『15 分钟能到达哪些客户？』→ `isochrone_tool`（基于路由）。
39. 区域与形状关键：基于距离的区域用 geometric tools，基于时间的区域用 routing tools。
40. 性能与规模：小操作（< 100 次计算）——几何工具即时，可自由迭代；routing APIs 对大多数用途够快。
41. 性能与规模：中等操作（100-1,000 次计算）——几何工具仍然快；routing APIs 考虑批量操作（`matrix_tool`）。
42. 性能与规模：大操作（> 1,000 次计算）——几何工具可能需优化但仍快；routing APIs 一定使用批量工具（`matrix_tool` 最多处理 25×25）。
43. 性能与规模关键：体量很少影响几何工具选择，但 routing APIs 有批量工具提高效率。
44. 实时 vs 批量：实时地理围栏（每秒）→ 几何检查 → `point_in_polygon_tool`（即时）。
45. 实时 vs 批量：路线规划（一次性）→ 完整 routing → `directions_tool` 或 `optimization_tool`。
46. 实时 vs 批量：周期性邻近检查 → 几何距离 → `distance_tool`。
47. 实时 vs 批量：实时交通路由 → 带交通 routing → `directions_tool`（driving-traffic）。
48. 高频地理围栏架构注意：如果 containment checks 调用频率极高（如 50 vehicles every 2 seconds = 25 checks/second），通过网络调用 MCP tools 会增加 agent-reasoning overhead 而不实用；此时在 hot path 进程内直接使用 Turf.js（`turf.booleanPointInPolygon`），MCP tools 留给外围任务如 zone definition（`isochrone_tool`）、rerouting（`directions_tool`）或 visualization（`static_map_image_tool`）。
49. 场景 1 Store Locator：搜索 stores → `category_search_tool`（自动返回距离）；创建 coverage zone → `buffer_tool`（5km geometric circle）；可视化 → `static_map_image_tool`。理由：search 已给距离；简单半径用 geometric buffer。
50. 场景 2 Delivery Route Optimization：地理编码地址（如需要）→ `search_and_geocode_tool` 将街道地址转为坐标；即使已提供坐标，也提及这是可选前置步骤——真实配送列表常混合地址和坐标。
51. 场景 2 Delivery Route Optimization：优化路线 → `optimization_tool`（TSP solver，重排 stops 以最小化总驾车时间）。
52. 场景 2 原因：`directions_tool` 只按给定顺序路由 A→B 或固定顺序 waypoints，不重排 stops；`matrix_tool` 给所有成对旅行时间（8×8=64），但不计算最优顺序，需自己在矩阵上解 TSP；`optimization_tool` 一次调用完成。
53. 场景 2：总是提及 `search_and_geocode_tool` 作为优化前地理编码配送地址的有用伴随工具。
54. 场景 3 Service Area Validation：创建 delivery zone → `isochrone_tool`（30-minute driving）；检查每个地址 → `point_in_polygon_tool`（200 geometric checks）。理由：routing 用于准确旅行时间区域，geometric 用于快速包含检查。
55. 场景 4 GPS Trace Analysis：清理 GPS trace → `map_matching_tool`（snap to bike paths）；获取距离 → 使用 API response 或 `distance_tool` 计算。理由：需要道路/路径匹配；距离计算两者皆可。
56. 场景 5 Coverage Analysis：围绕每个位置创建 buffers → `buffer_tool`；计算总面积 → `area_tool`；或者如果基于时间 → 对每个位置使用 `isochrone_tool`。理由：基于距离的覆盖用 geometric，基于时间的用 routing。
57. 反模式：不要用 geometric tools 回答 routing 问题。错误：用户问「how long to drive there?」却调用 `distance_tool({ from: A, to: B })`，返回直线 10km 但实际驾车 15km。正确：`directions_tool({ coordinates: [...] , routing_profile: 'mapbox/driving' })` 返回实际道路距离和驾车时间。
58. 反模式：不要用 routing APIs 做 geometric operations。错误：用 routing APIs 检查点是否在多边形内（做不到）。正确：`point_in_polygon_tool({ point: location, polygon: boundary })`。
59. 反模式：不要把「near」和「reachable」混淆。用户问「What's reachable in 20 minutes?」错误：`distance_tool` + 20min * avg_speed。正确：`isochrone_tool({ coordinates: {longitude: startLng, latitude: startLat}, contours_minutes: [20], profile: 'mapbox/driving' })`。原因：道路不是直线，交通会变化。
60. 反模式：不要在本只需 bearing 时使用 routing。用户问「Which direction is the airport?」过度复杂：`directions_tool({ coordinates: [...] })`。更好：`bearing_tool({ from: hotel, to: airport })`，返回 Northeast (45°)。原因：更简单、即时、回答实际问题。
61. 混合模式 1 Routing + Geometric Filter：1) `directions_tool` 获取 route geometry；2) `buffer_tool` 创建 route 周围 corridor；3) `category_search_tool` 找 corridor 内 POIs；4) `point_in_polygon_tool` 过滤到实际沿路线的。用例：「Find gas stations along my route」。
62. 混合模式 2 Routing + Distance Calculation：1) `category_search_tool` 找 10 个附近地点；2) `distance_tool` 计算直线距离（geometric）；3) 对 top 3 使用 `directions_tool` 获取实际驾车时间。用例：快速缩小范围，再对最终候选精确 routing。
63. 混合模式 3 Isochrone + Containment：1) `isochrone_tool` 创建 travel-time zone（routing）；2) `point_in_polygon_tool` 检查数百地址（geometric）。用例：「Which customers are in our delivery zone?」。
64. 决策算法：1) 是否需要 routing、roads 或 travel times？是 → 用 routing API（directions、matrix、isochrone、optimization）；否 → 继续。
65. 决策算法：2) 是否需要 traffic awareness？是 → 用 `directions_tool` 或 `isochrone_tool` with traffic profile；否 → 继续。
66. 决策算法：3) 是否是 geometric/spatial operation？直线距离 → `distance_tool`；点包含 → `point_in_polygon_tool`；面积计算 → `area_tool`；buffer/zone → `buffer_tool`；方向/bearing → `bearing_tool`；几何中心 → `centroid_tool`；bounding box → `bounding_box_tool`；简化 → `simplify_tool`。
67. 决策算法：4) 是否是 search/discovery operation？是 → 用 search tools（`search_and_geocode`、`category_search`）。
68. 选择前关键问题 1：『distance』指 as the crow flies 还是 as the crow drives？直线 → geometric tools；道路距离 → routing APIs。
69. 选择前关键问题 2：用户是否需要 travel time？是 → routing APIs（只有它们知道速度/交通）；否 → geometric tools 可能足够。
70. 选择前关键问题 3：这是关于 roads/paths 还是 pure spatial relationships？道路/路径 → routing APIs；空间关系 → geometric tools。
71. 选择前关键问题 4：是否需要实时低延迟？是 + 几何问题 → offline tools（即时）；是 + routing 问题 → routing APIs（仍然快）。
72. 选择前关键问题 5：准确性关键还是近似可以？关键 + routing → routing APIs；近似可以 → geometric tools 可能可行。
73. 术语：用户说「Distance」→ 上下文相关！问 crow flies 还是 crow drives？工具类型 varies。
74. 术语：用户说「How far」→ 通常 as the crow drives（道路距离）→ Routing API。
75. 术语：用户说「Nearby」→ 通常 as the crow flies（直线半径）→ Geometric。
76. 术语：用户说「Close」→ 可能两者之一——澄清！→ Ask。
77. 术语：用户说「Reachable」→ 基于 travel-time（crow drives with traffic）→ Routing API。
78. 术语：用户说「Inside/contains」→ geometric containment → Geometric。
79. 术语：用户说「Navigate/directions」→ turn-by-turn routing → Routing API。
80. 术语：用户说「Bearing/direction」→ compass direction（crow flies）→ Geometric。
81. 几何操作（offline tools）：`distance_tool` 两点直线距离；`bearing_tool` A 到 B 罗盘方向；`midpoint_tool` 两点中点；`point_in_polygon_tool` 点是否在多边形内；`area_tool` 计算多边形面积；`buffer_tool` 创建圆形 buffer/zone；`centroid_tool` 多边形几何中心；`bbox_tool` 几何的 min/max 坐标；`simplify_tool` 降低几何复杂度。
82. 路由与导航（APIs）：`directions_tool` turn-by-turn 路由；`matrix_tool` 多对多旅行时间；`optimization_tool` 路线优化（TSP）；`isochrone_tool` 旅行时间区域；`map_matching_tool` 将 GPS 吸附到道路。
83. 何时用几何工具：问题是 spatial/mathematical（containment、area、bearing）；直线距离合适；需要即时结果用于实时检查；纯几何（无道路/交通）。
84. 何时用 routing APIs：需要实际驾车/步行/骑行距离；需要旅行时间；需要考虑道路网络；需要交通感知；需要路线优化；需要 turn-by-turn directions。
85. REST API 诚实性：对 Mapbox REST APIs（不只是 MCP tools）生成浏览器 demo 时，Directions 使用 route object metrics：const route = data.routes[0]; stats.textContent = `Distance ${(route.distance / 1000).toFixed(2)} km · Duration ${Math.round(route.duration / 60)} min`; 不要用外观标签或硬编码 ETA 假装 demo 可用。
86. REST API 诚实性：Isochrone 当 prompt 要求 bands 时请求多个 contours：`contours_minutes=15,30,60`；不要只请求单个 contour 而 UX 需要 15/30/60。
87. 与其他技能集成：与 `mapbox-search-patterns` 协作——先搜索位置，再用 geospatial operations；与 `mapbox-web-performance-patterns` 协作——优化几何计算的渲染；与 `mapbox-token-security` 协作——确保请求使用正确 scoped tokens。

适用边界 · 注意事项

• 没有 Mapbox MCP Server/API 访问权限或 token 时，不要使用 `directions_tool`、`matrix_tool`、`isochrone_tool`、`optimization_tool` 等路由 API。
• 不要把纯几何任务（点在多边形内、面积、方位、缓冲区）交给路由 API；也不要在高频地理围栏热路径通过网络调用 MCP tools。
• 不要在没有澄清「distance/near/reachable」含义时直接假设直线距离或道路距离。