高德个人专属地图 Skill

SKILL.md 节选

# 高德个人地图 Skill

## 概述

本 Skill 封装了高德开放平台的 Web 服务 API，提供地理编码、POI 搜索、路径规划等核心能力，根据用户描述生成个人专属地图，并支持在高德地图 App 中扫码打开。

**重要**：所有调用此技能的会话，最终都应调用 `maps_schema_personal_map` 生成个人地图二维码，并通过以下方式展示给用户：
1. **下载二维码图片到本地**（推荐保存到工作目录）
2. **使用 `present` 工具展示图片**
3. **在回复中直接嵌入 Markdown 图片**（双重保障）
4. **提供备用 URL 链接**（防止图片展示失败）

这样可以确保用户能够可靠地看到并保存二维码。

## 接口说明

### 1. 地理编码

- **`maps_geo`**：地址 → 经纬度坐标
  - 参数：`address`（详细地址）、`city`（城市，可选）
  - 返回：经纬度坐标、格式化地址

- **`maps_regeocode`**：经纬度坐标 → 结构化地址
  - 参数：`longitude`（经度）、`latitude`（纬度）
  - 返回：国家、省份、城市、区县等完整地址信息

### 2. POI 搜索

- **`maps_text_search`**：关键词搜索兴趣点
  - 参数：`keywords`（搜索关键词）、`city`（城市，可选）、`offset`（每页记录数，默认 20）
  - 返回：POI 列表（名称、坐标、地址、电话）

- **`maps_around_search`**：周边兴趣点搜索
  - 参数：`keywords`、`location`（中心点"经度,纬度"）、`radius`（搜索半径，单位米，默认 1000）、`types`（POI 类型，可选）、`offset`（默认 20）、`page`（默认 1）
  - 返回：周边 POI 列表（含距离信息）

### 3. 路径规划

- **`maps_direction_walking`**：步行路线规划
  - 参数：`origin`（起点"经度,纬度"）、`destination`（终点"经度,纬度"）

- **`maps_direction_driving`**：驾车路线规划
  - 参数：`origin`、`destination`

- **`maps_direction_transit_integrated`**：公共交通路线规划
  - 参数：`origin`、`destination`、`city`（城市，默认"北京"）

### 4. 位置服务

- **`maps_ip_location`**：IP 地址 → 地理位置
  - 参数：`ip`（IP 地址）
  - 返回：省份、城市、行政区、ISP 等信息

### 5. 地图生成（核心）

- **`maps_schema_personal_map`**：生成个人地图小程序二维码
  - 参数：
    - `orgName`（地图名称）
    - `lineList`（行程列表，每条路线最多 16 个点）
    - `sceneType`（场景类型，可选，默认 `1`）：
      - `1` — 创建资源点且创建路线（默认，通用场景）
      - `2` — 仅创建资源点（搜索类数据，多个点之间无关联关系）
      - `3` — 仅创建路线（路径规划类数据，多个点有关联关系，如起终点、换乘点）
  - 返回：`qr_code_url`（二维码图片链接）、`lineList`（行程数据）

  **sceneType 选择指引：**
  - 用户做的是**搜索**（找餐厅、找景点、找周边 POI 等）→ 用 `sceneType=2`
  - 用户做的是**路径规划**（从 A 到 B、导航、换乘等）→ 用 `sceneType=3`
  - 两者都有，或不确定 → 用默认 `sceneType=1`

## 使用前提

1. 申请高德地图开发者账号并获取 API Key（https://lbs.amap.com/）
2. 配置环境变量：`export AMAP_API_KEY='your_api_key_here'`
3. 确保网络连接正常

## 异常处理

所有接口在出错时均返回结构化错误信息，不会抛出异常：

```python
{"error": "错误类型", "message": "具体原因"}
```

常见错误类型：`API Key 缺失`、`请求失败`、`搜索失败`、`路径规划失败`、`生成地图行程失败`。

检查返回值的推荐方式：
```python
result = client.maps_text_search("餐厅", "北京")
if isinstance(result, list) and result and "error" in result[0]:
    print(f"错误: {result[0]['message']}")
```

## 使用示例

### 初始化客户端

```python
from scripts.amap_personal_map_client import AMapPersonalMapClient

client = AMapPersonalMapClient()  # 读取环境变量 AMAP_API_KEY

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 6 个文件，合计 51.0 KiB