地图与地理编码

通过 OpenStreetMap/OSRM 进行地理编码、POI、路线、时区

地图技能

使用免费、开放数据源进行位置智能分析。8 条命令，44 个 POI 分类，零依赖（仅 Python 标准库），无需 API Key。

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

此技能替代旧的 find-nearby 技能——find-nearby 的所有功能都包含在下面的 nearby 命令中，使用相同的 --near "" 快捷方式和多分类支持。

使用场景

• 用户发送 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 — 按分类查找周边地点

# 通过坐标（来自 Telegram 位置坐标，例如）
python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10
python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000

# 通过地址/城市/邮编/地标 —— --near 自动地理编码
python3 $MAPS nearby --near "Times Square, New York" --category cafe
python3 $MAPS nearby --near "90210" --category pharmacy

# 多个分类合并为一次查询
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：

# 用户在 36.17, -115.14 发送了坐标并问"找附近咖啡馆"
python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500

以编号列表呈现结果，包含名称、距离和 maps_url，方便用户在聊天中点击链接。对于"现在营业吗？"类问题，检查 hours 字段；如果缺失或不明确，用 web_search 核实（OSM 营业时间由社区维护，不一定实时）。

工作流示例

"在斗兽场附近找意大利餐厅"：

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

"附近有什么他们发的坐标？"：

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

"从酒店怎么步行到会议中心？"：

• directions "Hotel Name" --to "Conference Center" --mode walking

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

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

注意事项

• Nominatim 服务条款：最多 1 请求/秒（脚本自动处理）
• nearby 需要 lat/lon 或 --near "" 二选一
• OSRM 路由覆盖欧洲和北美最佳
• Overpass API 高峰时段可能较慢；脚本自动在镜像间回退（overpass-api.de → overpass.kumi.systems）
• distance 和 directions 使用 --to 标志指定目的地（不是位置参数）
• 如果单独用邮编在全球范围内结果模糊，加上国家/州名

验证

python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
# 应返回纬度 ~40.689，经度 ~-74.044

python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
# 应返回时代广场约 500m 内的餐厅列表