高德地图技能 v2.4.0 (Production Ready)

功能完整的 Windows 版高德地图命令行工具。经过四轮深度审查 + PowerShell Parser 零错误验证，已修复全部已知 Bug，达到生产可用状态。

双实现：Python 3.8+ (amap.py) + PowerShell 5.1+/7+ (amap.ps1)，功能完全对齐。

---

📋 变更日志 (CHANGELOG)

v2.4.0 — 深度审查修复版 2026-04-11

| 类型 | 数量 | 说明 | |------|------|------| | 🔧 缺陷修复 | 6 | navi URL / 骑行信息 / DRY重构 / clear-cache / export补齐 / config清理 | | 🔒 编码修复 | 1 | PowerShell UTF-8 BOM（PS5.1 中文兼容） |

详细变更

• ✅ [M-1] navi 导航链接统一：PowerShell 移除多余 from 参数 → 与 Python 一致（?to=坐标,名称&mode=car）
• ✅ [M-2] 骑行路线信息增强 (v5 API)：新增红绿灯数(traffic_light_count)、路线步数(steps)字段输出
• ✅ [M-3] 代码 DRY 重构：
  • Python：抽取 _do_http_request() 统一 HTTP 核心，invoke_amap_request/invoke_amap_v5_request 改为薄包装
  • PowerShell：抽取 Invoke-AMapRequestCore() 统一核心，消除 ~90 行重复代码
• ✅ [M-4] Shell 模式 clear-cache 对齐：PS Shell 模式现在也显示缓存条目数
• ✅ [M-6] Python export 命令补全：argparse + Shell 模式新增 export 子命令（与 PS 完全对齐）
• ✅ [M-8] Config 双写冗余清理：统一单 key 驼峰格式写入；新增 _config_get() 多 key 兼容读取辅助函数
• ✅ [编码] amap.ps1 添加 UTF-8 BOM 头，解决 Windows PowerShell 5.1 解析中文报错问题

---

v2.3.0 — API 修复版 2026-04-11

| 类型 | 数量 | 说明 | |------|------|------| | 🔧 API 修复 | 2 | 骑行改用 v5 API / 公交改用 transit/integrated 端点 | | ✨ 架构改进 | 3 | base_url_v5 配置 / v5 请求函数 / 公交解析增强 |

详细变更

• ✅ 骑行路线修复：v3 API 不再支持骑行 → 切换至 v5 API (/v5/direction/bicycling)
• ✅ 公交路线修复：原端点缺少 city 参数 → 使用 /v3/direction/transit/integrated + 自动检测城市
• ✅ 新增 base_url_v5 配置项，支持 v3/v5 动态切换
• ✅ 新增 Invoke-AMapV5Request / invoke_amap_v5_request 函数
• ✅ 增强公交路线解析：支持轨道交通信息

---

v2.2.0 — 第三轮审查补丁

| 类型 | 数量 | |------|------| | 🔧 Bug 修复 | 9 | | 🛡️ 健壮性增强 | 5 | | ✨ 新功能 | 5 |

关键修复

• 所有命令无数据时返回结构化错误 JSON（不再静默失败）
• distance 字段 null 安全处理
• 缓存 key 排序一致化（避免 hashtable 键序差异导致未命中）
• API Key 短长度保护（短 key 不再崩溃）
• Format-Output 中英文键名兼容（名称 vs Name）
• 分页循环变量防未初始化（$result = $null）
• buslines 空数组越界保护（.Count -gt 0 校验）

关键新功能

• POI 分页翻页：-AllPages 自动获取全量结果
• 结果 直接导出：-OutputFile <path> 保存 JSON 文件
• 公交路线：transit 方式完整解析（换乘/费用/上下车站/轨道交通）
• 缓存控制：clear-cache 命令
• Shell 补全：交互模式支持全部 17 个命令

---

v2.1.0 — 第二轮审查增强

健壮性全面增强、Export-Data 重构、坐标格式校验等。

v2.0.0 — 初始发布

全功能 CLI 工具：地理编码/逆编码/天气/IP定位/POI搜索/周边搜索/POI详情/路线规划(驾车+步行)/距离测量/导航链接/打车链接/批量地理编码/批量周边搜索/交互式Shell。

---

快速开始

1. 设置 API Key

# 方式1: 命令行设置（推荐，同时写入环境变量和配置文件）
amap set-amapkey "your-api-key"

# 方式2: 系统环境变量（Machine 级别，永久有效）
# [系统属性] → [环境变量] → [新建] → AMAP_API_KEY = your-key

# 方式3: 当前会话
$env:AMAP_API_KEY = "your-api-key"

2. 基本使用

# 地址转坐标
amap g "蚌埠市梅桥街道"

# 周边搜索 + 分页获取全部 + 保存到文件
amap a "超市" "117.3,33.0" 2000 -AllPages -OutputFile pois.json

# 公交路线规划
amap r "117.36,32.95" "117.38,32.94" transit -Simple

# 批量地理编码
amap bg "梅桥,联盟家博城,温莎" -Simple

命令列表

配置命令

| 命令 | 说明 | 示例 | | -------------------------- | ---------------------------------------- | ------------------------------------ | | set-amapkey <key> | 设置API密钥（自动写入环境变量+配置文件） | amap set-amapkey "xxx" | | get-amapkey | 查看当前密钥（脱敏显示） | amap get-amapkey | | config | 查看当前配置 | amap config | | config set <key> <value> | 修改配置项 | amap config set defaultCity 合肥市 | | clear-cache | 清除请求缓存 | amap clear-cache | | status | 运行状态（版本/请求数/缓存/API Key） | amap status |

可配置参数：

| 参数 | 默认值 | 说明 | | --------------- | ------ | ---------------- | | defaultCity | 蚌埠市 | 默认搜索城市 | | defaultRadius | 1500 | 默认搜索半径(米) | | outputFormat | json | 默认输出格式 |

位置服务

| 命令 | 别名 | 参数 | 说明 | 示例 | | ------------------- | ---- | ---------------------- | --------- | ---------------------- | | geo <地址> [城市] | g | -Simple | 地址→坐标 | amap g "蚌埠站" | | regeo <坐标> | rg | -Simple | 坐标→地址 | amap rg "117.3,33.0" | | weather [城市] | w | -Format json\|simple | 天气预报 | amap w "蚌埠市" | | ip [IP] | - | -Simple | IP定位 | amap ip |

搜索服务

| 命令 | 别名 | 参数 | 说明 | 示例 | | ------------------------------- | ---- | ------------------------------- | ------------- | --------------------------------- | | search <关键词> [城市] | s | -AllPages -OutputFile -Format | POI关键字搜索 | amap s "餐厅" "蚌埠" -AllPages | | around <关键词> <坐标> [半径] | a | -AllPages -OutputFile -Format | 周边POI搜索 | amap a "超市" "117.3,33.0" 1500 | | detail <ID> | d | - | POI详情 | amap d "B001B0I4K0" |

参数说明：

• -AllPages: 自动分页获取全部结果（默认只返回第一页）
• -OutputFile <path>: 将结果保存为 JSON 文件
• -Format: json(默认) / table / simple / detail

路线规划

| 命令 | 别名 | 方式 | 说明 | 示例 | | ---------------------------- | ------ | ------------------------------------------- | ------------ | ------------------------------------------ | | route <起点> <终点> [方式] | r | driving / walking / bicycling / transit | 路线规划 | amap r "117.3,33.0" "117.4,33.1" transit | | distance <起点> <终点> | dist | -Simple | 直线距离测量 | amap dist "117.3,33.0" "117.4,33.1" |

支持 4 种出行方式：驾车(driving) / 步行(walking) / 骑行(bicycling, v5 API) / 公交(transit)

链接生成

| 命令 | 别名 | 说明 | 示例 | | ---------------------------------- | ---- | ---------------- | ---------------------------------------------- | | navi <坐标> <名称> | n | 生成高德导航链接 | amap n "117.3,33.0" "目的地" | | taxi <起点> <起名> <终点> <终名> | t | 生成高德打车链接 | amap t "117.3,33.0" "家" "117.4,33.1" "公司" |

坐标格式校验：无效坐标会报错提示而非生成无效链接

批量操作

| 命令 | 别名 | 说明 | 示例 | | ----------------------------------------- | ---- | ------------------------ | --------------------------------------- | | batch-geo <地址1,地址2,...> | bg | 批量地理编码（逗号分隔） | amap bg "梅桥,联盟,温莎" | | batch-around <关键词,...> <坐标> [半径] | ba | 批量周边搜索（多类别） | amap ba "餐饮,购物,银行" "117.3,33.0" |

实用功能

| 命令 | 说明 | | ----------------------------- | -------------------------------------- | | export <type> <file> [data] | 导出数据到 .json 或 .csv 文件 | | shell | 进入交互式 Shell（支持所有命令） |

详细使用示例

场景1：光纤盒覆盖区域分析

# 1. 获取地址坐标
amap g "蚌埠市禹会区兰凤家园"

# 2. 分页获取周边全部 POI（超过25条时自动翻页）
amap a "超市" "117.389799,32.928052" 1500 -AllPages -OutputFile lanfeng_supermarket.json

# 3. 多类别批量分析
amap ba "餐饮,购物,银行,医院,学校,酒店" "117.389799,32.928052" 2000

场景2：路线与导航

# 驾车路线
amap r "117.36,32.95" "117.38,32.94" driving -Simple
# → 距离: 2.8公里 | 时长: 8分钟

# 骑行路线 (v5 API)
amap r "117.36,32.94" "117.40,32.92" bicycling
# → 距离/时长/红绿灯数/路线步数

# 公交路线
amap r "117.36,32.95" "117.38,32.94" transit
# → 总时长、总费用、换乘次数、每段公交详情

# 生成导航链接
amap n "117.389799,32.928052" "兰凤家园"

# 步行路线
amap r "117.36,32.95" "117.38,32.94" walking -Simple

场景3：交互式使用

amap shell
# amap> geo "蚌埠南站"
# amap> rg "117.35,32.92"
# amap> w
# amap> clear-cache
# amap> exit

输出格式

# JSON（默认，完整结构化数据）
amap s "餐厅" "蚌埠"

# 表格（简洁表格视图）
amap a "超市" "117.3,33.0" 1000 -Format table

# 简洁（仅名称列表）
amap s "酒店" -Format simple

# 详情（逐条展示所有字段）
amap d "B001B0I4K0" -Format detail

参数规范

| 参数 | 格式说明 | 示例 | | ---------- | ----------------------------------------------- | ---------------------- | | 坐标 | 经度,纬度（经度在前，小数精度≥2位） | 117.362,32.948 | | 半径 | 米（正整数） | 1000, 1500, 2000 | | 路线方式 | driving / walking / bicycling / transit | - | | 地址分隔符 | 逗号或中文逗号或分号 | "A,B,C" 或 "A,B,C" |

故障排查

问题1：API Key 无法读取

AMAP_API_KEY 未设置。请运行: amap set-amapkey <your-key>

解决：

• 确认已在系统环境变量中设置了 AMAP_API_KEY（注意是 Machine 级别）
• 设置后需要重新打开终端窗口才能生效
• 或直接运行 amap set-amapkey "你的key"

问题2：10003 访问超频

原因：高德 API 有并发/配额限制 解决：

• 批量操作已内置 100ms 延迟，避免超频
• 如仍超频，可增大延迟或降低并发
• 检查高德控制台的配额用量

问题3：坐标格式报错

坐标格式无效，应为: 经度,纬度 (如: 117.3,33.0)

解决：确保使用 经度,纬度 格式，用英文逗号分隔，且包含小数点

问题4：天气/POI 查询返回空

• 确认城市名称正确（建议带省市前缀如"安徽省蚌埠市"）
• 使用 amap config set defaultCity 蚌埠市 设置默认城市

获取 API Key

👉 https://console.amap.com/dev/key/app

选择 「Web服务」 类型（不是 Web端/Android/iOS）

注意事项

1. API Key 需要 Web服务 权限
2. 高德免费额度：30万次/日（基础）；超频返回 10003 错误
3. 仅支持中国境内地理数据
4. POI 单页最多 25 条，使用 -AllPages 可自动翻页
5. 坐标系：GCJ02（火星坐标系），与 GPS/WGS84 有偏移
6. 双实现 (Python + PowerShell) 功能完全对齐，可按需选择使用