跳到主要内容

Maps（地图）

位置智能——地理编码地点、反向地理编码坐标、查找附近地点（46 种 POI 类别）、驾车/步行/骑行距离与时间、逐向导航、时区查询、命名地点的边界框与面积，以及在矩形区域内搜索 POI。使用 OpenStreetMap + Overpass + OSRM。免费，无需 API 密钥。

技能元数据​

来源捆绑（默认安装）
路径skills/productivity/maps
版本1.2.0
作者Mibayy
许可证MIT
标签maps, geocoding, places, routing, distance, directions, nearby, location, openstreetmap, nominatim, overpass, osrm

参考：完整 SKILL.md​

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

Maps 技能

使用免费开放数据源的位置智能。8 个命令，44 种 POI 类别，零依赖（仅使用 Python 标准库），无需 API 密钥。

数据源：OpenStreetMap/Nominatim、Overpass API、OSRM、TimeAPI.io。

此技能取代了旧的 find-nearby 技能——find-nearby 的所有功能均由下面的 nearby 命令涵盖，支持相同的 --near "<place>" 快捷方式和多类别支持。

何时使用​

  • 用户发送 Telegram 位置标记（消息中包含纬度/经度）→ nearby
  • 用户想要地点名称的坐标 → search
  • 用户拥有坐标并想要地址 → reverse
  • 用户询问附近的餐厅、医院、药店、酒店等 → nearby
  • 用户想要驾车/步行/骑行距离或旅行时间 → distance
  • 用户想要两个地点之间的逐向导航 → directions
  • 用户想要某位置的时区信息 → timezone
  • 用户想要在地理区域内搜索 POI → area + bbox

前提条件​

Python 3.8+（仅标准库——无需 pip 安装）。

脚本路径：~/.hermes/skills/maps/scripts/maps_client.py

命令​

MAPS=~/.hermes/skills/maps/scripts/maps_client.py

search — 地理编码地点名称​

python3 $MAPS search "Eiffel Tower"
python3 $MAPS search "1600 Pennsylvania Ave, Washington DC"

返回：纬度、经度、显示名称、类型、边界框、重要性评分。

reverse — 坐标转地址​

python3 $MAPS reverse 48.8584 2.2945

返回：完整地址细分（街道、城市、州/省、国家、邮政编码）。

nearby — 按类别查找地点​

# By coordinates (from a Telegram location pin, for example)
python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10
python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000

# By address / city / zip / landmark — --near auto-geocodes
python3 $MAPS nearby --near "Times Square, New York" --category cafe
python3 $MAPS nearby --near "90210" --category pharmacy

# Multiple categories merged into one query
python3 $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10

46 个类别：restaurant（餐厅）、cafe（咖啡馆）、bar（酒吧）、hospital（医院）、pharmacy（药店）、hotel（酒店）、guest_house（宾馆）、camp_site（露营地）、supermarket（超市）、atm（自动取款机）、gas_station（加油站）、parking（停车场）、museum（博物馆）、park（公园）、school（学校）、university（大学）、bank（银行）、police（警察局）、fire_station（消防站）、library（图书馆）、airport（机场）、train_station（火车站）、bus_stop（公交车站）、church（教堂）、mosque（清真寺）、synagogue（犹太会堂）、dentist（牙医）、doctor（医生）、cinema（电影院）、theatre（剧院）、gym（健身房）、swimming_pool（游泳池）、post_office（邮局）、convenience_store（便利店）、bakery（面包店）、bookshop（书店）、laundry（洗衣店）、car_wash（洗车场）、car_rental（租车行）、bicycle_rental（自行车租赁）、taxi（出租车）、veterinary（兽医诊所）、zoo（动物园）、playground（游乐场）、stadium（体育场）、nightclub（夜总会）。

每个结果包括：name（名称）、address（地址）、lat/lon（纬度/经度）、distance_m（距离，米）、maps_url（可点击的 Google Maps 链接）、directions_url（从搜索点出发的 Google Maps 导航链接），以及可用时的推广标签——cuisine（菜系）、hours（营业时间）、phone（电话）、website（网站）。

distance — 旅行距离和时间​

python3 $MAPS distance "Paris" --to "Lyon"
python3 $MAPS distance "New York" --to "Boston" --mode driving
python3 $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking

模式：driving（驾车，默认）、walking（步行）、cycling（骑行）。返回道路距离、持续时间，以及用于比较的直线距离。

directions — 逐向导航​

python3 $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
python3 $MAPS directions "JFK Airport" --to "Times Square" --mode driving

返回编号步骤，包含指令、距离、持续时间、道路名称和机动类型（转弯、出发、到达等）。

timezone — 坐标的时区​

python3 $MAPS timezone 48.8584 2.2945
python3 $MAPS timezone 35.6762 139.6503

返回时区名称、UTC 偏移量和当前本地时间。

area — 地点的边界框和面积​

python3 $MAPS area "Manhattan, New York"
python3 $MAPS area "London"

返回边界框坐标、宽度/高度（千米）和近似面积。可用作 bbox 命令的输入。

bbox — 在边界框内搜索​

python3 $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20

在地理矩形区域内查找 POI。先使用 area 获取命名地点的边界框坐标。

处理 Telegram 位置标记​

当用户发送位置标记时，消息包含 latitude: 和 longitude: 字段。提取这些字段并直接传递给 nearby：

# User sent a pin at 36.17, -115.14 and asked "find cafes nearby"
python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500

将结果呈现为带有名称、距离和 maps_url 字段的编号列表，以便用户在聊天中获得点击即开的链接。对于“现在营业吗？”之类的问题，检查 hours 字段；如果缺失或不明确，请使用 web_search 进行验证，因为 OSM 的营业时间由社区维护，并不总是最新。

工作流示例​

“查找罗马斗兽场附近的意大利餐厅”：

  1. nearby --near "Colosseum Rome" --category restaurant --radius 500 — 一条命令，自动地理编码

“他们发送的位置标记附近有什么？”：

  1. 从 Telegram 消息中提取纬度/经度
  2. nearby LAT LON cafe --radius 1500

“我如何从酒店步行到会议中心？”：

  1. directions "Hotel Name" --to "Conference Center" --mode walking

“西雅图市中心有哪些餐厅？”：

  1. area "Downtown Seattle" → 获取边界框
  2. bbox S W N E restaurant --limit 30

常见陷阱​

  • Nominatim 服务条款：最多 1 次请求/秒（由脚本自动处理）
  • nearby 需要纬度/经度或 --near "<address>" — 二者需提供其一
  • OSRM 路径规划覆盖范围在欧洲和北美最佳
  • Overpass API 在高峰时段可能较慢；脚本会自动在镜像之间回退（overpass-api.de → overpass.kumi.systems）
  • distance 和 directions 使用 --to 标志指定目的地（而非位置参数）
  • 如果仅凭邮政编码在全球范围内产生歧义结果，请包含国家/州信息

验证​

python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
# Should return lat ~40.689, lon ~-74.044

python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
# Should return a list of restaurants within ~500m of Times Square