mapbox-geospatial-operations

Mapbox 地理空间操作技能

为 AI 助手提供专家指导，帮助其从 Mapbox MCP Server 中选择合适的地理空间工具。重点是根据问题的实际需求选择工具——几何计算还是路线规划、直线距离还是道路网络，以及所需的精度。

核心原则：问题类型决定工具选择

Mapbox MCP Server 提供两类地理空间工具：

1. 离线几何工具 - 使用 Turf.js 进行纯几何／空间计算
2. 路线规划与导航 API - 需要真实路线、交通状况或出行时间时使用 Mapbox API

关键问题：问题实际需要什么？

决策框架

问题特征	工具类别	原因
直线距离（直线距离）	离线几何	几何距离计算准确
道路／路径距离（沿道路行驶的距离）	路线规划 API	只有路线规划 API 了解道路网络
出行时间	路线规划 API	需要结合速度／交通数据进行路线规划
点包含关系（X 是否在 Y 内？）	离线几何	纯几何运算
地理形状（缓冲区、质心、面积）	离线几何	数学／几何运算
考虑交通状况的路线规划	路线规划 API	需要实时交通数据
路线优化（确定最佳访问顺序）	路线规划 API	需要复杂的路线规划算法
高频检查（例如实时地理围栏）	离线几何	即时响应，无延迟

按使用场景划分的决策矩阵

距离计算

用户询问：“X 距离 Y 有多远？”

用户实际想问的内容	工具选择	原因
直线距离	distance_tool	几何距离计算准确，响应即时
驾车距离	directions_tool	只有路线规划工具才能得出实际道路距离
步行／骑行距离	directions_tool	需要特定的路径网络
出行时间	directions_tool 或 matrix_tool	需要结合速度数据进行路线规划
当前交通状况下的距离	directions_tool（driving-traffic）	需要考虑实时交通状况

示例：“这 5 个仓库之间的距离是多少？”

• 直线距离 → distance_tool（计算 10 次，即时完成）
• 驾车距离 → matrix_tool（5×5 矩阵，一次 API 调用，返回实际路线距离）

关键要点： 根据上下文中“距离”的实际含义选择工具。务必确认：是直线距离还是驾车距离？

邻近与包含

用户询问：“哪些点靠近／位于此区域内？”

查询类型	工具选择	原因
“半径 X 米范围内”	distance_tool + 筛选	简单的几何半径
“驾车 X 分钟范围内”	isochrone_tool → point_in_polygon_tool	需要先进行路径规划以确定出行时间范围，再进行几何包含判断
“位于此多边形内”	point_in_polygon_tool	纯几何包含测试
“驾车 30 分钟可达”	isochrone_tool	需要路径规划 + 交通信息
“距此点最近”	distance_tool（几何距离）或 matrix_tool（路径距离）	取决于“最近”的定义

示例：“这 200 个地址是否在我们的 30 分钟配送范围内？”

1. 创建范围 → isochrone_tool（路径规划 API——需要出行时间）
2. 检查地址 → point_in_polygon_tool（几何计算——可即时检查 200 个点）

关键要点： 创建出行时间范围时使用路径规划；检查是否位于范围内时使用几何计算

路径规划与导航

用户询问：“最佳路线是什么？”

场景	工具选择	原因
A 到 B 的路线	directions_tool	提供逐向导航
多个停靠点的最佳顺序	optimization_tool	解决旅行商问题
清理 GPS 轨迹	map_matching_tool	将轨迹匹配到道路网络
只需方位角／罗盘方向	bearing_tool	简单的几何计算
考虑交通状况的路线	directions_tool（driving-traffic）	实时感知交通状况
顺序固定的途经点	使用途经点的 directions_tool	途经特定点进行路径规划

示例：“从酒店导航到机场”

• 需要逐向导航 → directions_tool
• 只想知道“它在东北方向” → bearing_tool

关键要点： 实际导航使用路径规划工具；获取方向信息使用几何工具

面积与形状操作

用户询问：“围绕此位置创建一个区域”

需求	工具选择	原因
简单的圆形缓冲区	buffer_tool	几何圆形／半径
出行时间范围	isochrone_tool	基于路径规划网络
计算面积	area_tool	几何计算
简化复杂边界	simplify_tool	几何简化
查找形状中心	centroid_tool	几何质心

示例：“显示每家门店周围 5km 的覆盖范围”

• 5km 半径 → buffer_tool（几何圆形）
• “15 分钟内顾客能到达哪些地方？” → isochrone_tool（基于路径规划）

关键要点： 基于距离的范围使用几何工具；基于时间的范围使用路径规划工具

性能与规模考量

何时数量会影响工具选择

小规模操作（< 100 次计算）：

• 几何工具：即时完成，可自由迭代
• 路由 API：对大多数用途来说足够快

中等规模操作（100–1,000 次计算）：

• 几何工具：依然很快，无需担心
• 路由 API：考虑使用批量操作（matrix_tool）

大规模操作（> 1,000 次计算）：

• 几何工具：可能需要优化，但依然很快
• 路由 API：务必使用批量工具（matrix_tool 最多可处理 25×25）

关键要点： 数量很少会影响几何工具的选择，但路由 API 提供了用于提高效率的批量工具

实时与批量

使用场景	方法	工具选择
实时地理围栏（每秒一次）	几何检查	point_in_polygon_tool（即时完成）
路线规划（一次性）	完整路由	directions_tool 或 optimization_tool
定期检查邻近情况	几何距离	distance_tool
实时交通路由	带交通状况的路由	directions_tool（driving-traffic）

高频地理围栏的架构说明： 如果应用以极高频率调用包含检查（例如，50 辆车每 2 秒一次 = 每秒 25 次检查），通过网络调用 MCP 工具会增加 Agent 推理开销，导致这种做法不切实际。此时，建议在进程内直接使用 Turf.js（turf.booleanPointInPolygon）处理关键路径，并将 MCP 工具留给外围任务，例如定义区域（isochrone_tool）、重新规划路线（directions_tool）或可视化（static_map_image_tool）。

常见场景与最佳方法

场景 1：门店定位器

用户：“找到最近的门店，并显示 5km 覆盖范围”

最佳方法：

1. 搜索门店 → category_search_tool（自动返回距离）
2. 创建覆盖区域 → buffer_tool（5km 几何圆）
3. 可视化 → static_map_image_tool

原因： 搜索结果已包含距离；简单半径使用几何缓冲区即可

场景 2：配送路线优化

用户：“优化前往 8 个地址／停靠点的配送路线”

最佳方法：

1. 对地址进行地理编码（如有需要） → 使用 search_and_geocode_tool 将街道地址转换为坐标。即使已经提供坐标，也要将其作为可选的前置步骤提及——现实中的配送清单通常混合了地址和坐标。
2. 优化路线 → optimization_tool（TSP 求解器——重新排列停靠点，以缩短总行驶时间）

为什么使用 optimization_tool，而不是以下替代方案：

• directions_tool 只会规划 A → B（或按固定顺序经过途经点）。它不会重新排列停靠点——如果传入 8 个停靠点，它会按给定顺序规划路线，这几乎从来都不是最佳路线。
• matrix_tool 会给出所有停靠点两两之间的行驶时间（8×8 = 64 个值），但不会计算最佳顺序。你需要在矩阵数据的基础上自行求解 TSP——而 optimization_tool 一次调用即可完成。

优化配送路线前，务必提及可使用 search_and_geocode_tool 对配送地址进行地理编码。

场景 3：服务区域验证

用户：“这 200 个地址中，哪些可以在 30 分钟内送达？”

最佳方法：

1. 创建配送区域 → isochrone_tool（30 分钟驾车范围）
2. 检查每个地址 → point_in_polygon_tool（200 次几何检查）

原因： 使用路由生成准确的行驶时间区域，再用几何方法快速检查是否位于区域内

场景 4：GPS 轨迹分析

用户：“这次骑行持续了多久？”

最佳方法：

1. 清理 GPS 轨迹 → map_matching_tool（匹配到自行车道）
2. 获取距离 → 使用 API 响应或通过 distance_tool 计算

原因： 需要进行道路／路径匹配；无论采用哪种方式，距离计算都可行

场景 5：覆盖范围分析

用户：“我们的服务区域总面积是多少？”

最佳方案：

1. 为每个位置创建缓冲区 → buffer_tool
2. 计算总面积 → area_tool
3. 或者，如果按时间计算 → 为每个位置使用 isochrone_tool

原因： 基于距离的覆盖使用几何计算，基于时间的覆盖使用路径规划

反模式：使用错误类型的工具

❌ 不要：用几何工具回答路径规划问题

// WRONG: User asks "how long to drive there?"
distance_tool({ from: A, to: B });
// Returns 10km as the crow flies, but actual drive is 15km

// CORRECT: Need routing for driving distance
directions_tool({
  coordinates: [
    { longitude: A[0], latitude: A[1] },
    { longitude: B[0], latitude: B[1] }
  ],
  routing_profile: 'mapbox/driving'
});
// Returns actual road distance and drive time as the crow drives

错误原因： 直线距离 ≠ 驾车距离

❌ 不要：用路径规划 API 执行几何运算

// WRONG: Check if point is in polygon
// (Can't do this with routing APIs)

// CORRECT: Pure geometric operation
point_in_polygon_tool({ point: location, polygon: boundary });

错误原因： 路径规划 API 无法执行几何包含判断

❌ 不要：混淆“附近”和“可到达”

// User asks: "What's reachable in 20 minutes?"

// WRONG: 20-minute distance at average speed
distance_tool + calculate 20min * avg_speed

// CORRECT: Actual routing with road network
isochrone_tool({
  coordinates: {longitude: startLng, latitude: startLat},
  contours_minutes: [20],
  profile: "mapbox/driving"
})

错误原因： 道路不是直线；交通状况也会变化

❌ 不要：方位角足够时仍使用路径规划

// User asks: "Which direction is the airport?"

// OVERCOMPLICATED: Full routing
directions_tool({
  coordinates: [
    { longitude: hotel[0], latitude: hotel[1] },
    { longitude: airport[0], latitude: airport[1] }
  ]
});

// BETTER: Just need bearing
bearing_tool({ from: hotel, to: airport });
// Returns: "Northeast (45°)"

更好的原因： 更简单、即时响应，也能回答实际问题

混合方法：组合使用不同类型的工具

有些问题适合同时使用几何工具和路径规划工具：

模式 1：路径规划 + 几何筛选

1. directions_tool → Get route geometry
2. buffer_tool → Create corridor around route
3. category_search_tool → Find POIs in corridor
4. point_in_polygon_tool → Filter to those actually along route

适用场景：“查找我路线沿途的加油站”

模式 2：路径规划 + 距离计算

1. category_search_tool → Find 10 nearby locations
2. distance_tool → Calculate straight-line distances (geometric)
3. For top 3, use directions_tool → Get actual driving time

适用场景： 先快速缩小范围，再为候选地点计算精确路线

模式 3：等时圈 + 包含判断

1. isochrone_tool → Create travel-time zone (routing)
2. point_in_polygon_tool → Check hundreds of addresses (geometric)

适用场景：“哪些客户在我们的配送区域内？”

决策算法

当用户提出地理空间问题时：

1. Does it require routing, roads, or travel times?
   YES → Use routing API (directions, matrix, isochrone, optimization)
   NO → Continue

2. Does it require traffic awareness?
   YES → Use directions_tool or isochrone_tool with traffic profile
   NO → Continue

3. Is it a geometric/spatial operation?
   - Distance between points (straight-line) → distance_tool
   - Point containment → point_in_polygon_tool
   - Area calculation → area_tool
   - Buffer/zone → buffer_tool
   - Direction/bearing → bearing_tool
   - Geometric center → centroid_tool
   - Bounding box → bounding_box_tool
   - Simplification → simplify_tool

4. Is it a search/discovery operation?
   YES → Use search tools (search_and_geocode, category_search)

关键决策问题

选择工具前，请先询问：

1. “距离”指直线距离还是驾车距离？

   • 直线距离 → 几何工具
   • 驾车距离 → 路径规划 API

2. 用户是否需要出行时间？

   • 是 → 路径规划 API（只有它们了解速度和交通状况）
   • 否 → 几何工具可能就够了

3. 问题涉及道路/路径，还是纯粹的空间关系？

   • 道路/路径 → 路径规划 API
   • 空间关系 → 几何工具

4. 是否需要实时执行且延迟低？

   • 是 + 几何问题 → 离线工具（即时响应）
   • 是 + 路径规划问题 → 使用路径规划 API（仍然很快）

5. 精度是否至关重要，还是可以接受近似值？

   • 精度至关重要 + 路径规划 → 路径规划 API
   • 可以接受近似值 → 几何工具可能适用

术语指南

了解用户表达的含义：

用户说法	通常含义	工具类型
“距离”	取决于上下文！请确认是直线距离还是驾车距离	视情况而定
“有多远”	通常指驾车距离（道路距离）	路径规划 API
“附近”	通常指直线距离（直线半径）	几何
“近”	可能指两者之一——请确认！	询问
“可到达”	基于出行时间（考虑交通状况的驾车距离）	路径规划 API
“内部/包含”	几何包含关系	几何
“导航/路线”	逐向路径规划	路径规划 API
“方位角/方向”	罗盘方向（直线方向）	几何

快速参考

几何运算（离线工具）

• distance_tool - 两点之间的直线距离
• bearing_tool - 从 A 到 B 的罗盘方向
• midpoint_tool - 两点之间的中点
• point_in_polygon_tool - 点是否位于多边形内？
• area_tool - 计算多边形面积
• buffer_tool - 创建圆形缓冲区/区域
• centroid_tool - 多边形的几何中心
• bbox_tool - 几何对象的最小/最大坐标
• simplify_tool - 降低几何复杂度

路径规划与导航（API）

• directions_tool - 逐向路径规划
• matrix_tool - 多对多出行时间
• optimization_tool - 路线优化（TSP）
• isochrone_tool - 出行时间区域
• map_matching_tool - 将 GPS 轨迹匹配到道路

何时使用各类别

使用几何工具的情况：

• 问题涉及空间或数学计算（包含关系、面积、方位）
• 适合使用直线距离
• 需要即时获取结果以进行实时检查
• 纯几何场景（不涉及道路或交通）

使用路线规划 API 的情况：

• 需要实际的驾车、步行或骑行距离
• 需要行程时间
• 需要考虑道路网络
• 需要考虑交通状况
• 需要优化路线
• 需要逐向导航指引

REST API 说明（Directions / Isochrone）

使用 Mapbox REST API（而不只是 MCP 工具）制作浏览器演示时：

Directions — 使用路线对象的指标

const route = data.routes[0];
// GOOD — meters / seconds from the API
stats.textContent =
  `Distance ${(route.distance / 1000).toFixed(2)} km · ` + `Duration ${Math.round(route.duration / 60)} min`;

// BAD — cosmetic labels or hardcoded ETAs that look like a working demo
// "Len 0.00 km · Time 2 min" / Math.round(120/60)

Isochrone — 提示词要求分段时，请请求多个等时线

// GOOD — three travel-time bands
`contours_minutes=15,30,60`;

// BAD — a single contour when the UX needs 15 / 30 / 60
`contours_minutes=30`;

与其他技能集成

适用于：

• mapbox-search-patterns：搜索地点，然后进行地理空间操作
• mapbox-web-performance-patterns：优化几何计算的渲染
• mapbox-token-security：确保请求使用范围设置正确的令牌

资源

• Mapbox MCP 服务
• Turf.js 文档（为几何工具提供支持）
• Mapbox Directions API
• Mapbox Isochrone API
• Mapbox Matrix API
• Mapbox Optimization API