地圖技能
使用免費開放資料源的位置智慧。8 個指令、44 種興趣點類別、零依賴（僅用 Python 標準函式庫）、無需 API 金鑰。
資料來源：OpenStreetMap/Nominatim、Overpass API、OSRM、TimeAPI.io。
此技能取代舊的 find-nearby 技能——find-nearby 的所有功能都已涵蓋在下列 nearby 指令中，並且支援相同的 --near "<地點>" 快捷方式和多類別查詢。
使用時機
- 使用者傳送 Telegram 位置 pin（訊息中包含緯度/經度）→
nearby - 使用者想要一個地名的座標 →
search - 使用者擁有座標並想要地址 →
reverse - 使用者詢問附近的餐廳、醫院、藥局、旅館等 →
nearby - 使用者想要開車/步行/騎車的距離或行車時間 →
distance - 使用者想要兩個地點之間的逐步導航 →
directions - 使用者想要某個位置的時區資訊 →
timezone - 使用者想要在一個地理區域內搜尋興趣點 →
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 位置 pin）
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 地圖連結）、directions_url（從搜尋點到該地點的 Google 地圖導航連結），以及可用的推廣標籤——cuisine、hours (opening_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
在一個地理矩形區域內尋找興趣點。先使用 area 取得指定地點的邊界框座標。
處理 Telegram 位置 Pin
當使用者傳送位置 pin 時，訊息中會包含 latitude: 和 longitude: 欄位。將這些值提取出來，直接傳遞給 nearby：
# 使用者在 36.17, -115.14 傳送了一個 pin，並詢問「尋找附近的咖啡廳」
python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500
將結果呈現為編號列表，包含名稱、距離和 maps_url 欄位，讓使用者在聊天中獲得點擊即可開啟的連結。對於「現在有開嗎？」的問題，請檢查 hours 欄位；如果缺少或不明確，請使用 web_search 驗證，因為 OSM 的營業時間是社群維護的，不一定都是最新的。
工作流程範例
「尋找羅馬競技場附近的義大利餐廳」：
nearby --near "Colosseum Rome" --category restaurant --radius 500— 一個指令，自動地理編碼
「他們傳送的這個位置 pin 附近有什麼？」：
- 從 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 公尺內的餐廳列表