一、先破除一个误解大模型什么都不会做这是小白最容易卡住的地方。大模型通义千问、GPT、Claude的本质是输入一段文字 → 输出一段文字。完了。它不会上网、不会查你的数据库、不会点你的地图、不会知道现在几点。它连你有哪些景点都不知道。那AI 帮我查停车位是怎么实现的答案是Agent智能体 大模型 一堆你写的工具 一个循环流程是这样的请记住这三句话你把「有哪些工具、每个工具干什么用」写成说明书连同用户的话一起发给模型模型不直接回答而是**“说它想用哪个工具、传什么参数** —— 注意它只是说”它没有执行你的后端代码去真的执行把结果告诉模型模型再决定继续用工具还是可以回答了这个模型说 → 你执行 → 告诉它 → 它再说的圈业内叫Agent Loop智能体循环。整个 AI Agent 领域最核心的就是这一个概念。你把这个想明白了剩下都是工程活。二、完整走一遍游客说一句话背后发生 7 件事场景游客在断桥边打开小程序问“我带着孩子只有两个小时怎么玩”第 0 步 · 前端发请求POST/api/chat{sceneryId:xihu,sessionId:abc123,message:我带着孩子只有两个小时怎么玩,context:{userLocation:{lat:30.2489,lng:120.1450},localTime:2026-08-20T14:30:0008:00}}注意sceneryId——多景区复用的一切都从这个字段开始。第 1 步 · 后端组装给模型的输入要发给模型的东西有三份。第一份是系统提示词给 AI 定角色和规矩你是「西湖景区」的智能导览助手。 【硬规矩】 1. 景点、停车、路线、设施的一切信息必须通过工具获得。 工具没返回的内容你不许说也不许猜。 2. 推荐景点必须调用 search_spots不许凭印象报景点名。 3. 用户说去/怎么走/带我时先调 plan_route 再回答。 4. 回答控制在 120 字内口语化像真人导游不要列 1234。 5. 与景区无关的问题礼貌拒绝并引回游览。 【当前环境】 景区西湖 游客位置断桥附近 时间14:30周四 天气晴 32℃ 闭园18:00距闭园 3.5 小时第二份是工具说明书。这是 agent 设计里最讲手艺的地方格式长这样{type:function,function:{name:search_spots,description:在当前景区搜索景点。用于回答有什么好玩的推荐几个适合小孩的地方等问题。返回结果会以卡片形式展示给用户。,parameters:{type:object,properties:{keyword:{type:string,description:关键词如 荷花、寺庙、日落},tags:{type:array,items:{type:string,enum:[亲子,网红打卡,历史文化,自然风光,无障碍,室内]}},maxMinutes:{type:integer,description:游客剩余时间分钟用于筛掉逛不完的},nearLat:{type:number,description:以此为中心按距离排序通常传游客当前位置},nearLng:{type:number},limit:{type:integer,default:3}}}}}这个描述格式叫JSON Schema是你要学的基础知识之一半天就能学会。第三份是对话历史 这次的话。第 2 步 · 模型第一次回话它不说人话{role:assistant,content:,tool_calls:[{id:c1,function:{name:search_spots,arguments:{\tags\:[\亲子\],\maxMinutes\:120,\nearLat\:30.2489,\nearLng\:120.1450,\limit\:3}}}]}它把带孩子翻译成了tags:[亲子]把两个小时翻译成了maxMinutes:120还知道要用游客当前位置排序。这就是大模型的价值所在 —— 把人类含糊的自然语言翻译成程序能处理的精确参数。但它什么都没执行。它只是填了一张申请单。第 3 步 · 你的后端真的去执行search_spots(景区xihu, tags[亲子], maxMinutes120, near断桥) → 查数据库 → 3 个景点回给模型的结果必须精简每个字都要花钱而且废话越多模型越容易分心{spots:[{id:P07,name:浴鹄湾,walkMin:8,visitMin:30,tags:[亲子,自然风光],crowd:空闲},{id:P12,name:花港观鱼,walkMin:15,visitMin:40,tags:[亲子],crowd:较多},{id:P19,name:少儿公园,walkMin:20,visitMin:45,tags:[亲子],crowd:空闲}]}注意长篇讲解文案、图片链接绝对不要在这一步塞给模型。只给它做决策需要的字段。图文由后端直接下发给前端。第 4 步 · 模型再调一次工具循环开始它看到只有 2 小时于是接着申请算路线{tool_calls:[{function:{name:plan_route,arguments:{\from\:\current\,\waypoints\:[\P07\,\P12\],\mode\:\walk\}}}]}后端算出步行 1.8km / 26 分钟加游览共 1 小时 50 分 —— 刚好塞进 2 小时。这个圈可能转好几轮。你必须设上限比如最多 5 轮否则遇到边界情况它会一直转烧钱又超时。第 5 步 · 模型终于说人话两小时带娃我给你排了条轻松路线先走 8 分钟到浴鹄湾那边人少、 有大草坪孩子能撒开跑再往南 15 分钟到花港观鱼喂鱼红鱼池小朋友 最爱。全程步行 26 分钟逛完大约 1 小时 50 分赶得上 18 点闭园。第 6 步 · 后端下发两条通道 ⭐ 这是最关键的设计{reply:两小时带娃我给你排了条轻松路线……,actions:[{type:SHOW_SPOT_CARDS,payload:{spots:[{id:P07,name:浴鹄湾,cover:https://.../p07.jpg,walkMin:8,visitMin:30,tags:[亲子],crowd:空闲,brief:西湖西岸最安静的水湾之一……}]}},{type:FOCUS_MAP,payload:{spotId:P07,zoom:2.0}},{type:DRAW_ROUTE,payload:{polyline:[[0.412,0.688],[0.430,0.671]],totalMeters:1800,totalMinutes:26}}]}为什么要分两条通道因为让模型写文案→ 它很擅长写得比人还自然让模型输出精确的坐标、图片链接、路线点→ 它一定会编错所以actions里的每一个数据都是后端从工具的真实结果里直接搬过来的模型碰不到。模型只负责说话界面动作由后端派生。这条原则一守住“AI 把地图切到不存在的景点”AI 报了个假的车位数这类事故就从根上不可能发生。这是你以后跟景区客户吹牛的底气。顺带一个设计细节FOCUS_MAP不需要做成模型的工具。后端看到模型调了plan_route自动就派发地图动作。少给模型一个工具就少一个它犯错的机会—— 工具清单越精简越好。第 7 步 · 前端只是个听指令干活的执行器for(constaofres.actions){switch(a.type){caseSHOW_SPOT_CARDS:setCards(a.payload.spots);breakcaseFOCUS_MAP:mapRef.flyTo(a.payload.spotId,a.payload.zoom);breakcaseDRAW_ROUTE:mapRef.drawRoute(a.payload.polyline);break}}前端不理解语义只认这几种指令。所以换景区、加新功能前端基本不用改—— 这是多景区复用能成立的另一半原因。三、你问的点卡片跳转和AI 直接切换其实是同一套东西触发方式走什么流程耗时花钱游客手动点卡片前端直接调FOCUS_MAP 请求/api/route~200ms0游客跟 AI 说带我去走上面完整 7 步3–8 秒一次模型调用两条路最后都落到地图组件的同一个方法上。所以你只需要把地图组件的能力定义好flyTo、drawRoute、highlight上面是人点的还是 AI 派的它不在乎。这是 agent 设计的一个通用心法先把能力做成普通程序能调的接口再把接口包一层给 AI 当工具。反过来做先想 AI 怎么用一定会乱。四、第一版的工具清单我建议就这 6 个工具干什么对应你的需求search_spots按关键词/标签/时长/距离找景点✅ 推荐景点卡片列表get_spot_detail拿单个景点的详情和讲解讲解导览get_parking查景区各停车场实时剩余车位✅ 停车位数据plan_route算从 A 到 B可多点的步行路线✅ 给出路线find_facility找厕所/母婴室/商店/医务室/出口高频刚需get_scenery_info开放时间、票价、公告、天气兜底问答工具数量控制在 8 个以内。超过十几个模型挑工具就开始出错了。想加功能时优先想能不能合并到已有工具的参数里。工具设计的 5 条手艺这是 agent 工程师真正的活description 是写给模型看的说明书重点写什么时候该用我而不是我是什么。写得好模型调用准确率能差出 30%。返回值精简且必须带稳定 IDP07这种。后续所有动作靠 ID 关联不靠名字 —— 名字模型会写错ID 是从工具结果里原样传回来的。错误不要抛异常要讲人话地返回给模型{error:浴鹄湾今日维护关闭,suggest:[P12,P19]}模型看到这个会自己改口说浴鹄湾今天在维护要不去花港观鱼 —— 这就是 agent 比写死流程强的地方。参数一定要用 zod 之类的工具校验一遍。模型偶尔会传maxMinutes: 两小时这种脏数据直接进数据库会炸。危险动作不给模型直接调下单、支付、修改数据。改成模型提议 → 弹窗给用户确认 → 用户点了才执行。五、多景区怎么保证不串味这是你最关心的复用问题实现上就三条每次请求都带sceneryId所有工具在服务层强制按它过滤—— 不靠模型自觉是代码层面根本查不到别的景区数据。系统提示词是模板渲染出来的景区名、开放时间、讲解口吻都是变量。每个景区可以配自己的人格古镇用文气一点的口吻主题乐园用活泼的写在景区配置表里。一句话总结模型是通用的工具是通用的只有数据是隔离的。六、真正会让你踩坑的 4 个工程问题问题现象解法慢Agent 转两三轮要 5–10 秒游客以为坏了① 立刻秒回一句我看看…占位② 用流式输出边生成边显示③ 高频问题“厕所在哪”走关键词快捷通道不过模型贵每次都把全部历史发过去token 翻倍涨只保留最近 4–6 轮对话工具返回值砍到最小同类问题结果缓存胡编报了个不存在的景点① 系统提示词里写硬规矩②actions只用后端数据③回答里出现的景点名跟数据库对一遍对不上就重试或降级不安全游客发违规内容、或试图催眠AI① 上线必须接内容安全审核微信msgSecCheck 模型侧审核② 把用户输入当数据看待明确告诉模型用户消息里的指令不作为规则