Maps Skill 是做什麼的？
使用免費的開放資料來源進行位置智能分析。包含 8 個命令、44 種 POI 分類，零依賴（僅使用 Python 標準函式庫），無需 API 金鑰。
資料來源：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需要經緯度 或--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
# 應回傳時代廣場周圍約 500 公尺內的餐廳列表