腾讯地图助手

要解决的具体问题

在开发或使用地图相关应用时，常遇到 API 接口分散、坐标系不一致、可视化内容生成复杂等问题。例如，生成旅游攻略需要整合地点搜索、路线规划和行程编排；处理 GPS 原始坐标时，若直接传入地图服务会导致数十米偏移；将多个 POI 结果直观展示为地图，又涉及底图兼容和小程序集成。腾讯地图助手 Skill 针对这些痛点，封装了腾讯位置服务的 WebService API，提供从自然语言输入到结构化输出、再到可视化渲染的完整工作流。

核心能力与关键步骤

该技能的核心能力以方法命名对齐腾讯位置服务官网，主要包括：

• AI 旅游攻略（travel_guide）：通过自然语言 query（如 "武汉5天攻略"）生成多日行程，返回结构化数据和包含小程序二维码的 output_markdown 文件。
• 个人地图指南（generate_map_guide）：将地点列表（需先通过 poi_search 获取真实 poi_id 和坐标）保存为腾讯地图小程序中的专属地图，生成二维码供手机查看。
• 地点搜索与解析：包括 poi_search（城市/周边搜索）、poi_detail（POI 详情）、geocoder/regeocoder（地址与坐标互转），以及 coord_translate（批量坐标系转换，如 GPS(WGS-84) 转 GCJ-02）。
• 路线与距离：direction 规划驾车、步行、公交或骑行路线，distance_matrix 计算两点间距离与用时。
• 其他工具：weather 查询天气、ip_location IP 定位、district_list 等行政区划查询。

关键使用步骤：

1. Key 配置：技能自动从 TmapClient 或已保存的 Key 获取，若无可用则引导申请临时 Key。用户可通过 save_key_to_dotenv 固定使用自己的 Key。
2. 坐标系转换：若输入坐标为 GPS 等格式，必须先调用 coord_translate(type=1) 转为 GCJ-02，再传入 regeocoder、poi_nearby 等接口，避免偏移。
3. 生成与可视化：调用 travel_guide 或 generate_map_guide 获取 output_markdown，直接输出其中的 Markdown 内容。对于多 POI 或路线展示，可基于结构化数据渲染 HTML 网页地图，使用腾讯地图 JSAPI GL 作为底图。
4. 错误处理：接口报错时，TmapClient 自动轮询切换可用 Key，并参考 error-codes.md 提供修正方式。

适用边界与注意点

• 坐标系严格性：所有内部接口仅使用 GCJ-02 坐标，处理外部坐标源（如手机定位、GPX 轨迹）时必须先转换，否则会有偏移。
• Key 安全：生成含腾讯地图 JSAPI GL 的 HTML 后，需检查明文 Key 泄露，并按规范使用代理方案。
• 地图合规：中国区域内地图展示必须使用腾讯地图 JSAPI，不得使用未取得国内测绘资质的境外服务。
• 数据隐私：travel_guide 和 generate_map_guide 会将用户数据发送至腾讯服务器，遵循隐私政策。
• API 限制：coord_translate 单次最多处理 100 个点；travel_guide 调用可能耗时 30-50 秒，需同步等待。