mapbox-location-grounding

Mapbox 位置依据技能

教 AI 助手如何组合 MCP 工具，利用实时 Mapbox 数据为涉及位置的问题提供有据可依的回答。请使用此技能，而不要依赖训练数据中的地名、兴趣点、评分或出行时间——这些信息已过时，且容易导致幻觉。

何时使用位置依据

当用户询问以下内容时，为回答提供依据：

• “[位置] 附近有什么？”或“[坐标] 周围有什么？”
• “介绍一下这个社区／区域”
• “查找步行／驾车可达范围内的[类别]”
• “[地址] 附近有什么活动可以参加？”
• “从 A 到 B 要多久？”
• “这里步行 10 分钟范围内有什么？”
• “这些地点之间有多远？”
• 房地产、旅行、出行或本地探索相关的使用场景
• 任何涉及地点准确性、信息时效性或出行时间的问题

绝不要仅凭训练数据回答位置相关问题。 始终检索实时数据。

位置依据工具组合

首选：单次工具调用

如果有 ground_location_tool，请使用它——该工具会在一次调用中完成反向地理编码、兴趣点搜索、地点详情补充、等时线查询和静态地图图片生成：

ground_location_tool(
  longitude, latitude,
  query: "restaurant",   // optional — category or subcategory of nearby places to find
  profile: "mapbox/walking",    // optional — travel profile for isochrone
  contours_minutes: [5, 10, 15]
)

返回：

• 通过反向地理编码获取的社区／地点名称
• 附近的兴趣点及其距离、评分、价格等级和人气（如有）
• 等时线查询得出的可达范围
• 用于提供视觉背景的静态地图图片
• 所有数据来源的引用

不要单独调用 reverse_geocode_tool、category_search_tool、place_details_tool 或 isochrone_tool——这些工具已组合在该工具中。

查询参数

query 参数接受类别或子类别词语，而不是属性偏好：

• 支持："restaurant"、"coffee"、"park"、"Italian restaurant"、"EV charging station"
• 不支持："family-friendly"、"fast charging"、"outdoor seating"——这些不是 Mapbox 数据中可筛选的属性

若要帮助用户查找符合偏好的地点（例如“适合家庭”），请按类别搜索（"restaurant"），并利用返回的评分和价格数据为推荐提供参考。

备用方案：手动组合

如果没有 ground_location_tool，请按以下顺序组合这些工具，提供有据可依的回答：

步骤 1 — 确定地点背景

reverse_geocode_tool(longitude, latitude, types: "neighborhood,locality,place")

返回：社区、城市、地区、国家。这是回答的定位基准。

步骤 2 — 检索附近的兴趣点

搜索具体名称或品牌：

search_and_geocode_tool(query, proximity: {longitude, latitude}, limit: 10)

搜索一般类别：

category_search_tool(category, proximity: {longitude, latitude}, limit: 10)

步骤 3 — 补充兴趣点的评分和价格（可选，但价值很高）

对于每个带有 mapbox_id 的兴趣点，并行调用：

place_details_tool(mapbox_id, attribute_sets: ["visit"])

返回：各地点的评分、价格等级、人气和营业时间。

步骤 4 — 补充出行时间信息（可选，但价值很高）

isochrone_tool(
  coordinates: {longitude, latitude},
  profile: "mapbox/walking",    // or "mapbox/driving", "mapbox/cycling", "mapbox/driving-traffic"
  contours_minutes: [5, 10, 15]
)

返回一个多边形，显示各个时间阈值内可到达的范围。

步骤 5 — 提供视觉依据（可选）

static_map_image_tool(longitude, latitude, zoom: 14)

返回地图图片，可在回答中加入，以提供视觉背景。

有据可依的回答结构

回答中始终应明确列出引用来源：

Place: [neighborhood, city from reverse_geocode]
Nearby [category]: [list from search/category tool, with names, ratings, prices, and distances]
Travel context: [X min walk / Y min drive from isochrone]
Sources: Mapbox Search, Mapbox Directions (live data)

有据可依的回答示例：

SoMa，San Francisco，CA（Mapbox 实时数据）

步行可达的餐厅：

• Bix Restaurant $$ ★8.4 — 56 Gold St（180m）
• The Bird $ ★7.9 — 115 New Montgomery St（320m）
• Oren's Hummus $$ ★8.1 — 131 Townsend St（510m）

步行可达：5 分钟、10 分钟、15 分钟

来源：Mapbox Geocoding API、Mapbox Search API、Mapbox Place Details API、Mapbox Isochrone API、Mapbox Static Images API

路线规划依据

对于两个地点之间的出行问题，请使用 directions_tool。对于可达区域相关的问题，请使用 isochrone_tool。对于比较多个地点之间的出行时间，请使用 matrix_tool。

点对点行程时间和距离

“从派克市场开车到国会山要多久？” “从酒店到机场最快的路线是什么？”

directions_tool(
  waypoints: [{longitude, latitude}, {longitude, latitude}],
  profile: "mapbox/driving-traffic"   // live traffic; or "mapbox/walking", "mapbox/cycling", "mapbox/driving"
)

返回：时长（包含实时路况）、距离、逐向导航步骤，以及用于地图渲染的编码折线。多站点路线最多支持 25 个途经点。

区域可达性（“X 分钟内”）

“步行 10 分钟内能到哪些地方？” “显示从这里开车 15 分钟内能到的地方。”

isochrone_tool(
  coordinates: {longitude, latitude},
  profile: "mapbox/walking",
  contours_minutes: [5, 10, 15]
)

返回一个多边形，显示每个时间阈值内可到达的区域。与 category_search_tool 或 ground_location_tool 结合使用，可回答“步行 10 分钟内有哪些餐厅？”——使用等时圈定义边界，然后在其中搜索。

多地点行程时间矩阵

“这三间办公室中哪一间离我最近？” “从这个仓库到每个配送区域的行程时间是多少？” “比较前往多个地点的通勤时间。”

使用 matrix_tool——不要为每一对地点分别调用 directions_tool。矩阵会在一次 API 调用中批量计算所有地点对。

matrix_tool(
  sources: [{longitude, latitude}, ...],
  destinations: [{longitude, latitude}, ...],
  profile: "mapbox/driving-traffic"
)

返回每个出发地与目的地之间的时长和距离矩阵。按时长对结果排序即可找到最近的地点。一次 matrix_tool 调用可替代 N 次单独的 directions_tool 调用。

带路线信息的邻近搜索

对于“查找距离［地点］X 分钟内的［类别］”：

1. 如有需要，对起点进行地理编码：search_and_geocode_tool(address)
2. 获取可达区域：isochrone_tool(coordinates, profile, contours_minutes)
3. 搜索兴趣点：ground_location_tool(longitude, latitude, query: "category")——等时圈 轮廓可告知用户每个时间范围内有哪些地点

或者更直接地说：ground_location_tool 一次调用即可同时返回附近的兴趣点和等时圈可达性，涵盖大多数邻近搜索与路线规划场景，无需额外组合调用。

路线响应示例

派克市场 → 西雅图国会山

开车（含路况）：12 分钟，3.2 km，经 Pine St 步行：28 分钟，2.1 km 骑行：14 分钟，2.3 km

来源：Mapbox Directions API（实时路况）

Mapbox 地面信息与训练数据的比较

	训练数据	Mapbox 地面信息
兴趣点准确性	陈旧、不实	实时、经过核实
评分／价格	常有错误	通过 Place Details 实时获取
营业时间	常有错误	通过 Place Details 实时获取
行程时间	估算	通过 Directions 获取实时路况
可达区域	不可用	等时圈多边形
多站点路线规划	不可用	最多 25 个途经点
新地点	缺失	已收录
地图图像	无	内嵌静态地图
引用	无	工具 + API 来源

重要限制

• 属性筛选（适合家庭、户外座位、快速充电）不受类别搜索 API 支持。请使用类别词语，并根据评分／价格数据提供偏好型建议。
• 兴趣点覆盖范围因地区而异。如果搜索结果很少，请如实说明，不要用猜测凑数。
• 邻近搜索需要坐标——如果用户提供的是地址，请先使用 search_and_geocode_tool 对其进行地理编码，再进行类别搜索。

应避免的反模式

• 不调用搜索工具，而是根据训练数据回答“X 附近有什么？”
• 不调用 directions_tool 或 isochrone_tool，却估算出行时间
• 臆造商家名称、营业时间或评分
• ground_location_tool 可用时，仍分别调用 reverse_geocode_tool + category_search_tool + place_details_tool
• 使用“适合家庭”等属性词作为查询参数——应使用类别
• 直接返回原始工具输出，而不整合成易读的回复
• 遗漏引用——始终指出回复基于 Mapbox 实时数据