高德地图技能 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

详细变更

• ✅ [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

详细变更

• ✅ 骑行路线修复：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 — 第三轮审查补丁

关键修复

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

关键新功能

• POI 分页翻页：-AllPages 自动获取全量结果
• 结果 直接导出：-OutputFile 保存 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

命令列表

配置命令

可配置参数：

位置服务

搜索服务

参数说明：

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

路线规划

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

链接生成

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

批量操作

实用功能

详细使用示例

场景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

参数规范

故障排查

问题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) 功能完全对齐，可按需选择使用