【腾讯位置服务】让地图听懂人话：用AI Agent给地图装上「大脑」，还能组队协作

你见过AI自己"想"问题的地图吗？你见过一群人各自在不同地方，地图自动算出最佳碰头点的吗？你见过队友之间在地图上画连线、AI根据所有人的位置来规划行程的吗？

一个念头

之前做一个基于位置服务的活动应用，用户总抱怨：“我就想知道附近哪有合适的场地，还得点搜索、输关键词、看列表……太麻烦了！”

还有更烦的——几个人约着出去玩，"你在天安门，我在国贸，他在西单，咱去哪碰头？"光是讨论碰头地点就能聊半小时。

我就在想：能不能像聊天一样用地图？

说"帮我找中关村附近的咖啡馆"，地图就自动把结果标出来。
说"从天安门到颐和园怎么走"，路线就画好了。
说"我们仨分别在天安门、国贸、西单，去哪碰头方便"，自动推荐折中位置。

于是有了 MapMind——用腾讯位置服务 + AI Agent 做的智能地图助手，让地图从"被操作的死工具"变成"能思考的活助手"。而且不只是单人用，还能实时组队共享位置，让出行协作从"群里发定位"进化到"地图上一起看"。队友之间有连线，AI知道每个人的位置，规划行程时自动考虑所有人——这才是真正的"协作地图"。

---

5秒搞懂它能做什么

你说一句	它帮你做	用到的腾讯API
“附近有啥好吃的”	自动定位→搜索→标地图	IP定位/Poi搜索/逆地理编码
“从天安门到颐和园”	地址转坐标→画路线→算时间	地理编码/路线规划
“咱仨在天安门、国贸、西单碰头”	算折中点→搜附近→推荐位置	地理编码×3 + 周边探索/搜索
“帮我规划今天的行程”	搜景点→串路线→给方案	POI搜索/路线规划
“北京有几个区”	查行政区划→标地图	行政区划查询
“这附近有什么好玩的”	周边探索→按距离排序	周边探索(explore)
“从这里到那里多远”	算距离+驾车时间	距离计算
“我想输入’咖啡’自动补全”	搜索关键词提示	搜索提示(suggestion)

不用点按钮、不用选分类、不用调筛选——像聊天一样说人话就行。

---

核心原理：AI Agent + Function Calling = 地图会"思考"

传统地图用法：

用户 → 想找咖啡馆 → 点搜索 → 输入"咖啡馆" → 选分类 → 看列表 → 点进去 → 看详情

MapMind 用法：

用户 → "帮我找咖啡馆" → AI理解意图 → 自动调地图API → 结果打在地图上

关键就这么几步：

1. 用户说人话 → 发给大模型
2. 大模型"想"一下 → 通过 Function Calling 决定调用哪个地图工具
3. 后端执行工具 → 调腾讯位置服务API拿数据
4. 结果画在地图上 → AI再组织语言回复用户

如果一次搞不定？AI会多轮思考——先调地理编码拿到坐标，再调路线规划画路线，再调距离计算算时间——一条消息可能触发3~4次工具调用，用户完全无感。

9大地图工具，覆盖出行全场景

工具名	用途	典型场景
search_poi	搜索地点/POI	找咖啡馆、餐馆
plan_route	路线规划	驾车/步行/骑行/公交
geocode	地址→坐标	"天安门"→ 39.9,116.4
reverse_geocode	坐标→地址	反过来
suggest_meeting_point	多人汇合推荐	算中心点+搜附近
get_district	行政区划查询	“北京有几个区”
explore_nearby	周边探索	无关键词也能发现
get_distance	距离+时间计算	“多远？多久？”
search_suggestion	搜索关键词提示	输入补全

其中最有意思的是 suggest_meeting_point——它不只是简单算个中心点，而是双路搜索策略：先用 explore 按距离排序获取热门地点，如果有偏好（如"地铁站"），再用 search 精确搜索，优先返回精确匹配结果。

---

核心机制：两阶段 LLM 调用（ReAct Agent）

整个 AI Agent 的核心就是一个 ReAct 循环——思考→行动→观察→再思考：

1. 把用户消息+系统提示词发给AI，AI决定调用什么工具
2. 按AI的决策逐个执行地图工具（调腾讯位置服务API）
3. 把工具结果喂回AI，让它组织自然语言回复

如果AI判断不需要工具，直接回复。就是这么简单——AI负责"思考"和"说话"，实际干活的是腾讯位置服务API。

---

腾讯位置服务对接（附防坑指南）

SK签名机制

腾讯位置服务API使用SK签名保障安全：将所有参数（含key）按字典序排列拼接，计算 MD5(path?query+sk) 作为签名，签名不参与签名计算，直接追加到参数末尾。签名用原始参数值，发送请求时再对参数值做URL编码——签名和编码的顺序不能搞反。

我踩过的5个坑（希望你不用再踩）

① 签名总是失败（status 111）

坑：用 axios({ params }) 传参数时，axios会重新排序，签名时排好的顺序在发送时乱了。

救：手动拼URL，签名用原始值，发送时再URL编码。

② API路径多了个/ws

坑：有的API路径是 /ws/geocoder/v1/，有的是 /geocoder/v1/，签名必须和实际请求路径完全一致，搞混了就是111错误。

救：统一在调用入口里自动补全 /ws，签名和请求路径保持一致。

③ 路线画不出来

坑：路线规划返回的 polyline 不是普通坐标数组，是前向差分压缩格式——一堆偏移量数值，不是 lat,lng;lat,lng。

救：写了个 decodePolyline() 把压缩格式解成坐标数组，核心逻辑就是逐对累加偏移量。

④ 搜索时忘了传boundary

坑：腾讯的 search_poi 要求必须传 boundary 参数（搜索范围），没传就报错。

救：固定策略——有坐标用 nearby(lat,lng,radius)，没坐标用 region(城市,0)，都没就用 region(中国,0)。

⑤ Key每天有调用限制

坑：新申请的Key默认额度可能为0，某些API调用直接返回121错误。

救：去控制台→配额管理→手动分配每天的调用次数。

---

前端交互：AI让地图画什么，地图就画什么

地图渲染用的腾讯地图 JSAPI GL。AI返回的每个工具结果都携带 mapAction，前端根据工具类型自动渲染：

• search_poi / explore_nearby → 蓝色POI标记
• plan_route → 路线绘制 + 橙色起点 + 红色终点
• suggest_meeting_point → 橙色出发点 + 紫色汇合点
• geocode → 定位标记

每种标记不同颜色，信息面板实时展示搜索结果——用户对话结束时，地图上已经画好了所有内容。

---

实时协作：从"群里发定位"到"地图上一起看"

这是 MapMind 区别于其他地图AI助手的核心差异——不只是你一个人用AI，而是一群人一起用。

设计思路

传统方式：群里发定位截图 → 大家各自看 → 约碰头地点 → 再发定位 → 循环……

MapMind方式：进入组队页面 → 创建/加入房间 → 位置实时共享在地图上 → AI帮你们推荐最佳碰头点 → 行程自动分享给队友

双页面架构：地图与组队分离

一个关键的设计决策：组队管理使用独立页面，而不是在地图上弹窗。

为什么？因为腾讯地图 JSAPI GL 会在地图容器上捕获所有DOM事件——点击、触摸、滚轮，一个不落。如果在地图上方叠加弹窗，点击弹窗按钮时事件会穿透到地图，导致弹窗无法正常交互。尝试过 stopPropagation、事件守卫等各种方案，最终发现最干净的解法就是页面分离：

• index.html — 地图+AI对话主界面，专注展示和交互
• team.html — 独立组队管理页面，房间创建/加入、成员列表、位置共享控制、团队聊天

两个页面通过 localStorage 同步房间状态。用户从组队页面返回地图时，房间状态无缝恢复，Socket重连后自动重新加入房间，队友标记和连线自动重建。

队友连线：空间关系一目了然

加入房间后，地图上会自动绘制队友之间的虚线连接，直观展示每个人的空间位置关系：

• 用户→队友：彩色虚线+箭头，表示"我到你的方向"
• 队友之间：灰色淡虚线，表示队友之间的空间关系

连线使用 TMap.MultiPolyline 配合 PolylineStyle 的 dashArray（虚线样式）和 showArrow（箭头指示），支持一键开关（🔗按钮）。

还有"聚焦队友"功能（👥按钮），一键调整地图视野包含所有成员位置——不用手动拖地图找队友在哪。

行程自动共享

AI规划出路线或汇合方案后，结果会自动分享给房间内的所有队友。队友的地图上会同步展示路线和标记，不用截图、不用转发——AI规划完，全队都看到。

用户体验优化：无需进入房间即可使用

一个重要的设计决策：用户无需先加入房间就能使用所有AI地图功能。房间是可选的协作增强，不是使用门槛。

• 未加入房间：正常使用AI对话、地图搜索、路线规划等所有功能
• 点击"👥 组队"：跳转到独立组队页面，创建或加入房间
• 加入房间后：地图上实时显示队友位置和连线，成员列表可见，位置自动共享
• 从组队页返回地图：房间状态自动恢复，队友标记和连线重建

这种"渐进式协作"设计，让单人用户不会感到困惑，多人用户又能获得协作增强。

---

团队感知AI：AI知道队友在哪

这是 MapMind 最"聪明"的地方——AI不只是帮你一个人规划，它知道你队友在哪，会自动考虑所有人的位置。

队友位置注入

当用户在房间中发送消息时，前端会把所有队友的位置信息一起发给后端。后端收到后，把队友位置注入到AI的系统提示词中：

## 队友位置（重要！组队场景下必须利用这些信息）
当前用户: 小明
队友列表:
- 小红: 坐标 39.91,116.46 (实时共享中)
- 小刚: 坐标 39.90,116.35

### 队友相关指令策略（最高优先级！）
- 用户说"我们"、"队友"、"大家" → 必须使用队友位置信息
- "去哪里汇合" → suggest_meeting_point(所有坐标)
- "去找XX" → plan_route(from=用户, to=队友位置)
- "大家怎么走" → 为每个队友分别 plan_route

这样当用户说"我们几个人去哪里碰面比较好"，AI会自动调用 suggest_meeting_point，把所有队友和用户的坐标都传进去，算出最佳汇合点。

行程规划策略

AI不是只会被动回答问题，系统提示词中明确要求AI主动调用工具完成规划：

• 用户提到任何出行需求 → 主动调用工具完成规划，不要只给文字建议
• “帮我规划行程”/“安排一下” → 搜索目的地POI + 规划路线，给出完整方案
• “XX日游”/“玩一天” → 搜索多个景点 + 规划串联路线
• “附近有什么好玩的” → 调用 explore_nearby
• “找XX” → 调用 search_poi

有队友时还有专门的多人协作策略：涉及"我们"、“队友”、"大家"时自动使用队友位置信息，"去哪里碰面"自动算汇合点，"大家怎么去XX"为每个人分别规划路线。

---

几个有意思的设计细节

1. 自动感知用户位置

地图首次加载就自动尝试定位，浏览器定位失败就自动走IP定位（腾讯IP定位API）。成功后把城市名注入AI的上下文中，用户说"附近有啥吃的"，AI自动知道在哪个城市搜，不用傻傻反问。

2. 不让AI"太啰嗦"

AI回话带各种工具调用标签？加个 cleanAIOutput() 函数过滤掉。上下文越长越贵？限制最多保留20条消息，旧的自动丢弃。AI叫了不存在的工具？直接返回错误提示并让AI重试。

3. Agent调用链可视化

地图右下角显示AI的思考轨迹——“🔍搜索地点→📍地理编码→🗺️路线规划”，每一步成功/失败都标颜色。既增加了透明感，也让用户知道AI不是在"发呆"而是在"思考"。

4. 搜索历史记忆

用户之前搜过的关键词会记录在搜索历史中，点击可快速再次搜索。AI的上下文也保留了历史对话，所以你可以说"刚才那个地方怎么走"，AI知道你指的是哪个地方。

5. 智能地址解析

路线规划和距离计算中，用户输入的"天安门"这样的地址文本，会自动先调地理编码API转成坐标，再进行后续计算——用户不需要知道什么是经纬度。

---

举个例子看看效果

场景1：单人找咖啡馆

用户说： “帮我找附近好吃的咖啡馆”

AI的思考过程：

1. 🔍 检测到用户位置（北京海淀区）
2. 🔎 调用 search_poi（关键词=咖啡馆，范围=附近2km）
3. 📍 把10个结果标在地图上

结果： 地图上出现10个蓝色标记，信息面板列出名称、地址、距离。

---

场景2：三人碰头

用户说： “三个人分别在天安门、国贸、西单，去哪里汇合最方便”

AI的思考过程：

1. 🔍 先查三个地点的坐标（调3次地理编码API）
2. 📐 算三个点的几何中心位置
3. 🔎 在中心附近搜索热门地点（调 explore API）
4. 📊 返回推荐结果

结果： 地图上标了三个出发点（橙色）、推荐汇合区域（紫色）和附近热点（蓝色），信息面板列出推荐地点名称和地址。

全程用户就说了一句话，剩下的全是AI带着腾讯位置服务干的。

---

场景3：组队出游

用户操作： 点击"👥 组队"→ 跳转组队页面 → 创建房间 → 把房间号分享给朋友 → 朋友加入 → 返回地图

实时效果：

• 每个人的位置自动出现在地图上（不同颜色的标记）
• 队友之间自动绘制虚线连线，空间关系一目了然
• 点击👥按钮一键聚焦所有队友
• 成员列表实时更新
• 任何人在聊天中说"我们去哪吃"，AI会基于所有人的位置推荐折中地点
• AI规划结果自动分享给全队，队友地图同步展示

---

技术架构一览

┌──────────────────────────────────────────────────────────┐
│                      Frontend (双页面)                     │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │  index.html  │  │  team.html   │  │  Socket.io   │   │
│  │  地图+AI对话  │  │  组队管理页面 │  │  (实时协作)   │   │
│  │  队友连线     │  │  房间/成员    │  │  行程共享     │   │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘   │
│         └─────────┬───────┴─────────┬───────┘           │
│             ┌─────▼─────────────────▼─────┐              │
│             │     Map Actions Handler     │              │
│             └─────────────┬───────────────┘              │
└───────────────────────────┼──────────────────────────────┘
                            │ HTTP API / WebSocket
┌───────────────────────────▼──────────────────────────────┐
│                   Express Backend                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │  LLM Agent   │  │  Tencent Map │  │  Socket.io   │   │
│  │  (Function   │  │  WebService  │  │  (房间/位置/  │   │
│  │  Calling)    │  │  API (9工具) │  │   行程共享)   │   │
│  └──────────────┘  └──────────────┘  └──────────────┘   │
└──────────────────────────────────────────────────────────┘

技术栈

• 前端：HTML5 + CSS3 + Vanilla JS + 腾讯地图 JSAPI GL + Socket.io Client
• 后端：Node.js + Express + Socket.io
• AI：LLM Function Calling（DeepSeek / 腾讯混元）
• 地图服务：腾讯位置服务 WebService API（9个API接口）
• 实时通信：Socket.io v4（房间管理、位置共享、行程同步）

---

一点总结

MapMind 这个项目给我的最大感受是：AI Agent 不是噱头，是真的能简化用户体验。传统地图交互需要用户学会"地图的操作逻辑"，而现在地图需要学会"用户的语言逻辑"。

腾讯位置服务提供了完整的API能力矩阵——POI搜索、路线规划、地理编码、行政区划、IP定位、周边探索、距离计算、搜索提示——9个API接口，配合AI Agent的智能调度，做出来的东西既有技术深度又有实用价值。

而实时协作功能的加入，让MapMind从"个人工具"进化为"团队工具"——几个人出游不再需要在群里反复发定位，地图上直接看到彼此，有连线展示空间关系，AI还能基于所有人的位置推荐最佳碰头点，规划结果自动同步给全队。

技术不是目的，解决问题才是。 当用户说一句"我们去哪吃"，地图就能给出答案——这才是AI+地图该有的样子。

---

项目地址： Gitee - MapMind（腾讯位置服务征文参赛作品）

如果觉得有点意思，点个赞支持一下 ❤️