写在前面

作为一个长期在 Coze/WorkBuddy 平台上做智能体开发的工程师，我过去大半年一直在被同一类问题「骚扰」：

• 「帮我把这段地址转成坐标」
• 「做一个显示门店分布的地图页面」
• 「规划一下从 A 到 B 的路线」
• 「附近有什么好吃的」

每次都要翻文档、找 API、拼参数。一两个还行，需求一多，整个人就成了「腾讯地图 API 复读机」。

于是我决定：做一个 Skill，把这些全部封装掉。

地图指挥官就这么诞生了。

---

一、为什么需要「指挥官」

腾讯地图的开放能力其实很完整，官方文档也写得不错。但对于 AI 智能体场景来说，有几个实际问题：

1. 接口分散，要记一堆东西
地理编码是地理编码，POI 是 POI，路线规划是路线规划，Weather 又是另一个入口。每次写智能体都要判断该调哪个 API、传什么参数。

2. 前端和后端是两套体系
JSAPI 负责页面渲染，WebService API 负责数据查询。一个智能体想要「在地图上显示路线」，需要同时协调两端。这对 AI 来说是复杂的编排任务。

3. Prompt 里塞太多技术细节，AI 会晕
如果把每个 API 的参数格式都塞进 Prompt，AI 的上下文会被大量技术细节淹没，反而容易出错。

所以「地图指挥官」的思路是：让 AI 只需要关心「要什么」，不关心「怎么调」。

---

二、整体架构

地图指挥官是一个协调层，本身不实现地图能力，而是根据用户需求自动选择合适的子技能：

用户需求
  │
  ├─► 前端展示 / 可视化  → tencentmap-jsapi-gl-skill
  │
  ├─► 地址坐标互转       → tencentmap-webservice-skill
  │       POI 搜索
  │       路线规划
  │       天气查询
  │       距离矩阵
  │       ……
  │
  └─► 高级 LBS / 轨迹   → tencentmap-lbs-skill

三个子技能各司其职，指挥官负责判断和路由。

这样做的好处是职责清晰：前端只管渲染，数据只管查询，轨迹分析有专门的处理逻辑。AI 在执行任务时，只需要说「加载前端地图技能」或「调用地理编码接口」，而不需要背上具体参数格式的细节。

---

三、核心能力一览

1. 地理编码与逆地理编码

地址转坐标、坐标转地址，这是所有位置服务的基础。

输入：「深圳市南山区科技园南路 88 号」
输出：lat: 22.543, lng: 113.931

支持批量处理，Excel 里有一列地址，贴进来直接转。

2. POI 搜索与周边分析

关键词搜索、周边搜索、矩形范围搜索。不只是返回一堆点，还能做竞品分析、商圈分布统计。

举一个真实的例子：帮一个奶茶店老板分析「我店周围 1 公里有多少家竞品」，从请求到拿到分析报告，不到 30 秒。

3. 路径规划

支持驾车、步行、骑行、电动车、公交五种出行方式。能规划单程，也能做沿途搜索——比如「从深圳去广州，途经哪些景点」。

4. 前端地图可视化

这是用得最多的场景。接入 JSAPI GL 之后，可以做：

• 热力图（销售数据、客流分布）
• 散点图（门店分布）
• 弧线图（迁徙路线）
• 轨迹动画（外卖员/配送轨迹回放）
• 三维模型展示（室内导航场景）

开发者只需要说「帮我做一个热力图」，Skill 自动生成对应的代码和配置。

5. 天气查询 & 距离矩阵

对物流、配送场景很有用。批量查多个城市的天气，或者批量算多点之间的距离矩阵，接口一次调完。

---

四、五个「不是那么正经」的功能

技术能力说完了，来说点有意思的。

我在构思这个 Skill 的时候就在想：能不能让地图服务不只有「干活」的场景，也能「好玩」？

于是加了五个小功能：

🍽️ 美食雷达

「沈阳国际软件园附近有什么好吃的，不要火锅」

不只是搜餐厅，还会按类别筛选，分析周边美食分布，顺手推荐一家宝藏小店。

💑 约会神器

「我在深圳，她在广州，找个中间点约会」

智能找中间位置，推荐「餐厅 + 咖啡厅 + 电影院」组合，生成约会路线图。理工科的浪漫，大抵如此。

🏃 跑步路线

「生成一条 5 公里的小区附近跑步路线」

搜索附近公园和绿道，自动生成折返或环形路线，估算用时和卡路里。适合不想动脑子但又想锻炼的人。

🏠 搬家参谋

「帮我分析一下这个小区适不适合住」

输入一个地址，自动分析周边配套：超市、医院、学校、地铁通不通？综合计算宜居指数，给出一个「能不能搬」的参考意见。

🎲 随机探险

「随便，带我去个好玩的地方」

每天推荐一个随机目的地，生成半日游路线。说走就走的旅行，AI 替你做攻略。

---

五、技术实现的一些心得

Key 的配置管理

三个子技能对应不同的 Key：JSAPI 用 TMAP_JSAPI_KEY，WebService 用 TMAP_WEBSERVICE_KEY，签名校验还需要 TMAP_SECRET_KEY。我把 Key 配置做成环境变量的方式，正式环境和体验 Key 可以无缝切换，用户不需要改代码。

签名算法的封装

腾讯地图 WebService API 的签名校验（SN 校验）是个容易踩的坑。参数排序、字符串拼接、MD5 计算，一不小心就签名不对。我把这个逻辑封装成了 signature.py，加载 Skill 时自动处理，对上层完全透明。

意图路由的朴素实现

其实没有用什么复杂的分类模型。就是关键词匹配 + 决策树。比如「附近」「周边」触发 POI 搜索，「路线」「去」触发路径规划。够用就好，不炫技。

---

六、用在哪里

目前地图指挥官已经在以下场景落地：

场景	说明
连锁门店管理系统	全国门店分布热力图，区域销售分析
物流调度平台	多点路径规划，距离矩阵批量计算
外卖配送轨迹	骑手轨迹动画回放，实时位置落点
旅游攻略 Bot	景点推荐，路线规划，导航串联
企业内部地址库	批量地址标准化，脏数据清洗

以及，五个「不太正经」的功能，在朋友聚会时拿出来演示，反响还不错。

---

七、写在最后

地图指挥官的核心想法其实很简单：让 AI 智能体能够用自然语言驱动地图能力，而不需要开发者每个人都去啃一遍 API 文档。

腾讯位置服务提供了足够丰富的能力，官方文档也足够详细。但从「文档」到「在智能体里用起来」，中间有一层转换成本。这个 Skill 想做的，就是填平这个 Gap。

如果你也在做类似的探索，欢迎交流。

参赛能力：AI + 地图 · 智能进化
产品支持：WorkBuddy / ClawPro
skillhub：https://skillhub.cn/skills/map-commander