做了大半年围棋小程序真正让我觉得“这产品有AI味”的不是接了个会下棋的引擎而是藏在功能后面的七个Agent。它们分别负责规则问答、术语解释、棋谱转述、全局复盘、单步点评、死活题判题和用户意图路由。每个Agent都有自己的提示词、输入输出结构和兜底逻辑组合起来才像一条能陪棋友从打开棋谱到复盘结束的完整服务链。很多人做小程序AI功能时会有个误区总觉得塞一个“智能助手”进去就完事了用户随便问模型随便答。结果提示词越堆越长回复越来越飘前端解析越来越痛苦最后变成“能聊天但不能用”。这篇文章想把这个围棋小程序里的七个Agent讲透重点放在三件事场景怎么划分、提示词怎么设计、结构化输出怎么落地。适合正在做小程序AI功能或者想把大模型从“聊天玩具”变成“可用功能”的人参考。1. 围棋小程序里为什么塞了七个Agent而不是一个“全能围棋GPT”1.1 从一个非常具体的翻车场景讲起早期版本真的只做了一个大Agent系统提示词把围棋规则、术语解释、复盘要点、死活题思路全塞进去看起来相当全能。结果用户问“什么是打劫能举个简单例子吗”模型答得头头是道再追问“帮我看下这盘棋第100手有没有问题”模型就开始胡编甚至把第100手说成第120手的位置点评对象完全错了。翻车原因很典型一个提示词里装的知识体系太多模型不知道当前应该优先调用哪块能力。上下文一长前面塞进去的规则内容还会干扰后面的棋局分析回复就成了“什么都懂一点但没有一处能闭环”。更头疼的是前端。模型返回自由文本程序里要做功能按钮、要渲染变化图就得从一段中文里硬抠棋谱坐标。有一次模型写“黑棋应该下在左上角星位配合对角”但程序真正需要的是“Q16”这种坐标两边表述根本对不上。聊天是爽了干活是废的。1.2 单一模型调用的问题围棋这个领域的信息需求差异非常大。规则问答是知识检索对生成自由度要求极低死活题判题需要严格局部逻辑错一步就是误导棋谱转述要把SGF坐标翻译成人话全局复盘又要大局观评价和胜负判断。把所有这些塞进一个Agent系统提示词至少两千字每轮请求都白白发送大量无用token成本高、响应慢、还容易互相污染。我当时下的决定是拆按用户场景拆成七个独立Agent每个Agent只负责一类任务。这么做的收益很明显系统提示词短了上下文利用率高了每个功能都能独立迭代、独立降级、独立换模型。代价是要多维护几条链路但经历过一次“跳点”事故后我宁愿多花这个维护成本。1.3 七个Agent的分工到底解决了什么一个围棋棋友在小程序里的典型路径是打开棋谱找解说复盘时盯着某一手问“这手好吗”隔几天想练死活题偶尔冒出“什么是双活”这种基础问题。这四类需求需要的知识密度、上下文形式和输出形态完全不同。七个Agent各守一线像一家棋社里分专业的教练。有的是启蒙讲师只管规则有的是技术教练只管局部招法有的是题目出题人只管死活题。用户在小程序里根本感知不到背后有几个Agent但每个功能都会更稳。七个里还有一个很特殊——意图路由Agent它在最前面做分发用户随便发一行文字小程序先判断“他是要查规则、看棋谱、问招法还是做题”再送到对应的处理链路。这是我最终定的架构也是后面所有提示词和结构化输出设计的基础。2. 七个Agent的场景拆解每个Agent在用户旅程中占领哪个位置2.1 职责速览动手设计Agent之前我先把七个角色列成了一张表每个角色都绑定了触发场景、核心输入和输出形态。这张表是后面写提示词和定义JSON Schema的底稿也是和前端同事沟通的统一语言。序号Agent触发场景核心输入输出形态1规则问答用户输入“什么叫打劫”“贴目是多少”问题文本答案 关联规则条目2术语解释用户输入“手筋是什么”术语词条术语卡片 用法场景3棋谱转述上传SGF棋谱要文字解说SGF棋谱 目标手数分阶段文字流4全局复盘棋局结束后要总结要点完整棋谱胜负要点 风格描述5单步点评用户点某一手棋SGF棋谱 手数索引该手评价 变化图SGF6死活题判题用户做题并请求讲解局部局面坐标死活结论 变化图7意图路由用户在输入框发了任意文本原始文本意图标签 参数2.2 规则问答与术语解释最容易被低估的两个Agent规则问答和术语解释看起来技术含量最低却是小程序里点击量最高、最能兜住新手的模块。规则问答Agent我给它定了一条很硬的护城河只依据围棋规则回答不做创作、不评价棋手、不延伸无关话题。当用户问“打劫能不能连续提”的时候它只需要给出准确解释和相关条目不需要补一句“这手很妙”。术语解释Agent比规则问答多了一层用法约束。我在提示词里反复强调解释“手筋”时不能只讲定义必须补一个使用场景比如“常见于对杀局面指改变局部战斗结果的妙着”。前端拿到结构化的term、definition、usage三个字段直接渲染成卡片。用户看着不会像翻字典更像有人在旁边点拨。这两个Agent的输入都很简单但输出格式我钉得死死的。因为它们是所有功能里调用次数最多的如果格式飘了问题会被放大得非常明显。2.3 棋谱转述、全局复盘、单步点评一盘棋的三层解读这三个Agent共享同一份棋谱数据但输出粒度完全不同。棋谱转述Agent做的是“翻译”“第21手黑棋在左下角星位挂角白棋选择托退形成常见定式。”它只描述落子序列不做评价。全局复盘Agent站得远一些“本局黑棋中腹围得很大但第87手缓手被白棋便宜了”按局面对比、攻防转换、胜负关键手三个维度给出要点。单步点评Agent则站得最近用户点哪一手它分析那一手的好坏、局部最佳应对和变化图。这三个如果不拆很容易打架。同一手棋全局复盘要讲它对胜势的宏观影响单步点评要讲局部得失棋谱转述只需要讲落点。拆开之后每个Agent的提示词只负责自己那个层级输出质量明显上升。我在代码层维护了一套公共棋谱解析模块先把SGF转成二维坐标数组再分别注入三个Agent保证它们拿到的输入格式完全一致。2.4 死活题判题Agent与意图路由Agent一个专项苦力一个聪明入口死活题判题Agent是最不能出错的一个。规则问答答错了只是尴尬死活题判错就是实打实的误导。我给它的输入定成两部分题目局面用坐标文本描述目标用“黑先活”“白先杀”这类明确短语。输出必须包含死活结论、第一步手筋、失败变化三段。为了不让模型把“打劫活”和“净活”混在一起我规定结论字段只允许四个枚举值净活、净死、打劫、双活。模型如果没有足够的把握可以输出“情况不明”但绝不允许模糊兜底成“要看后续”。意图路由Agent是我最后补上的也是总控位。用户任何一句模糊输入先到这里做分类查规则、查术语、看棋谱、问招法、做题。分完类再带着原始参数分发到对应Agent。这个Agent本身不回答专业问题只输出意图标签和必要参数提示词非常短。但它直接决定了前面六个Agent能不能各司其职是真正的杠杆点。3. 提示词设计怎么把围棋这门“高语境”语言教给大模型3.1 角色设定别让模型当万金油多Agent系统里每个Agent的role描述要刻意“窄化”。除了告诉它“你是做什么的”更要花篇幅告诉它“你不做什么”。模型在没有业务压力的时候特别容易把两种任务混着答有了明确的负面清单跑偏概率会小很多。比如规则问答Agent的角色定义我写得并不花哨但很实用你是围棋小程序的规则问答Agent。 你能回答的是围棋基本规则、比赛规则、常用术语的规则层面解释。 你不能做的是评价具体棋局、提供下一步建议、猜测棋手水平。 所有回答必须以JSON格式输出{answer: ..., related_terms: [...]}这个格式给了模型三个清晰的锚点边界、任务、输出合同。单步点评Agent的role则会追加“必须结合当前棋谱上下文”避免它天马行空地讲大道理。经验是多Agent的提示词宁可多写“你不做什么”也不要把“你能做什么”的描述写得过于宏大。3.2 局面注入棋谱、坐标、双方手数的传递格式围棋Agent和普通聊天Agent最大的区别在于棋盘状态是强上下文。模型不“看”棋盘只能“读”棋盘。我统一用一种文本格式传局面当前棋谱SGF B[qd];W[dc];CF[ce];B[ch] 已走完32手当前轮到白棋。每次调用Agent前公共棋谱解析模块会把SGF标准化再拼上这段说明。这里有个关键细节必须在提示词里附录坐标规则明确横轴从a到t、跳过字母i纵轴从1到19。比如a1是右下角t19是左上角。很多模型默认英文坐标有i或者把横纵概念搞反不写清这层规则后面输出很容易错位。3.3 围棋提示词中必须写清楚的“禁区”我总结了三条必须写进提示词的禁区每一条都对应一次真实的线上翻车。第一条不要计算胜率。模型没有跑过棋力引擎看不到任何胜率数据强行让它输出“胜率78%”绝对是编的。应对办法是禁止所有Agent输出胜率数字用户问到就引导去“形势判断”功能。第二条不要臆造棋手身份。模型不认识任何真实棋手描述招法时客观就好绝对不能编“某业余5段认为”之类的背书。第三条不要试图做终局数子。复杂终局模型很容易数错如果用户上传终局棋谱让规则Agent引导使用小程序内置的数子工具。这些限制本质上是给模型划出“信息边界”。模型远没有聪明到知道自己不知道只有提示词先替它承认这一点才能避免一本正经地胡说八道。3.4 few-shot与温度不同Agent的生成策略差异七个Agent的生成参数不能一刀切。规则问答和意图路由我设temperature为0几乎不让模型自由发挥。死活题判题给0.2保留一点局部变化探索能力但整体仍以严谨为主。棋谱转述给0.1希望它尽量按事实描述。全局复盘给0.4文字会自然一些点评也更有人味。比temperature影响更大的其实是few-shot示例。单步点评Agent提示词里我放了三个真实棋谱片段对应的完整JSON输出示例好手、缓手、漏着各一个。模型见过和没见过的输出风格差异非常大。只要示例够具体模型会非常自然地模仿示例里的结构比你在提示词里反复强调“要用JSON格式”管用得多。4. 结构化输出让Agent从“会聊天”变成“能干活”4.1 为什么围棋小程序更需要结构化输出围棋小程序的每个功能最终几乎都要落到“棋谱操作”上展示坐标、渲染棋盘、生成变化图。如果Agent输出是一大段自由文本前端就只能整段展示交互就变成“看AI写作文”而不是“用AI工具”。结构化输出解决三件实际问题前端组件能直接消费数据不用在长文本里做正则抽取不同Agent之间的数据结构可以复用传参链路干净后端可以写校验器在数据进库或渲染前拦住错误结果。比如“单步点评”给前端的不仅是文字还有一个变化图SGF。前端拿到SGF直接渲染成可拖动变化图没有结构化输出这一步根本不可能实现。4.2 一份JSON Schema如何贯穿七个Agent我建议所有Agent都从一组公共的基础数据结构派生自己的输出。棋谱是整个系统的地基{ board_size: 19, moves: [ {index: 1, player: B, x: 15, y: 3}, {index: 2, player: W, x: 3, y: 15} ] }规则问答Agent的输出结构可以这样定义{ intent: rule_qa, answer: 打劫是指双方在同一位置反复提子需隔一手才能提回, related_terms: [劫争, 找劫材], confidence: 0.9, hit_rules: [劫争规则] }单步点评Agent的输出会复杂一些但每个字段都有明确含义{ move_index: 76, coordinate: {x: 3, y: 16}, evaluation: bad, reason: 缓手局部应当先扳, variation_sgf: ;B[cp]W[cq]B[dp] }这些结构我在开发前先定义好再让每个Agent的提示词去对齐它。代码里有了统一的BoardState类、Move类、点评类型枚举七个Agent的联动就不会出现“一个说中文坐标一个说数字坐标”的乱象。4.3 强制结构的两条路工具调用与提示词约束现在的模型接口基本都支持在请求里声明工具函数。我的实践是能用工具调用强制结构的任务就不要只靠提示词里写“请输出JSON”。提示词约束总会失效——上下文一长模型偶尔会突然开始长篇大论底层的模型一更新行为可能还会漂移。规则问答、意图路由、死活题判题这三个任务我直接用工具调用来绑定输出参数。棋谱转述和全局复盘这类以长文本为主的任务模型输出混合结构段落文字加关键数据字段后端再用一个小解析器把数据字段抽出来。两种方式并存是因为不同任务的本质不一样有的必须机器可读有的允许一部分自然语言发挥。4.4 校验、纠错、重试把“偶尔飘”的模型拉回正轨结构化输出真正的门槛不是模型“听懂格式”而是模型“偶尔不守格式”。我写了一个轻量校验器每个Agent输出都要过三道检查第一JSON能正常解析第二坐标字段在1到19范围内字母不能落在i上第三必填字段存在枚举值合法。校验不过怎么办只提示错误不做其他操作太浪费。我的做法是重试一次重试时把模型上次的输出贴回去追加一句“上述回复中坐标/格式不合法请重新输出符合schema的完整JSON”。实测这样一次重试成功率在95%以上两次重试后基本能拉回正轨。为了避免死循环每个Agent最多允许两次重试。这层校验器看着不起眼却是整个系统从“偶尔能用”到“稳定能用”的关键。5. 真实联调踩坑记录超时、幻觉、格式漂移与钱包5.1 坐标幻觉模型说对了棋但说错了位置踩过最典型的幻觉是模型对“左下角”和“右下角”的理解错位。明明给它坐标“A1”它描述成“右上角星位”A1其实在棋盘最右下角。很多模型的坐标原点理解默认在左上稍微一复杂就全乱。这个问题的解法不是靠提示词死磕。我最终决定不让模型在文字里使用“左下角”“右下角”这类方位词而是强制它统一输出标准坐标。文字描述只说“靠近星位”“沿边线”这类相对位置真正的精确定位一律走坐标字段。前端只读取坐标字段渲染棋子方位词只作为可选项显示这样就切断了最大的一类坐标幻觉。5.2 胜负判断和胜率数字的幻觉某个版本里全局复盘Agent在回答里写“黑棋胜率82%”但它根本没跑过任何棋力引擎这个数字是编的。后来我在提示词里加了一条硬禁令不许输出胜率数字不许输出目数差要判断优劣只能使用“明显优势”“形势接近”“稍亏”这类可靠定性描述。用户问到底谁赢就引导他用小程序里的“形势判断”或“终局数子”功能。这里我冒了个险与其让模型给一个假精确的数字不如给它一个“安全的不精确”。在实际围棋场景里这种取舍比死磕精确性更能保护产品口碑。一次误导比一次拒绝对用户的伤害大得多。5.3 并发与慢请求七个Agent同时在线最直接的问题是并发。用户连点几个功能小程序后端会同时发起多个模型请求而模型接口都有并发配额高峰期经常报限流。我的方案是给每个Agent配一个独立请求队列队列长度、超时时间、并发上限各自独立。意图路由要求几十毫秒级响应单步点评可以接受三秒左右。前端也做了请求合并同一个用户的连续操作要合并成一次上下文请求而不是每次点击都单独调模型。这样处理后高峰期限流明显减少体验顺滑很多。给Agent配独立队列这件事比想象中重要。所有Agent共用一套并发策略的时候要么慢的拖死快的要么贵的打爆预算独立配额才能让每个功能各得其所。5.4 缓存与模型分层围棋小程序的Agent很适合做缓存。规则问答和术语解释这类请求答案几乎不变我用文本hash做缓存命中率超过一半成本和延迟都降下来了。棋谱转述、单步点评这类带棋谱的请求虽然每个棋谱不一样但热门定式后续的讲解经常重复我把标准化后的SGF片段做一个短hash也能命中不少。模型分层对成本的影响更大。意图路由这种做分类的小任务用便宜的小模型就够了。单步点评需要一点棋理判断用中等模型。全局复盘对语言组织和全局判断要求最高值得用旗舰模型。七个Agent并不需要都绑在同一个最强模型上分层之后整体成本下降很快而用户感知几乎无差别。小模型处理小任务大模型处理复杂任务这才是把Agent系统做到能长期运营的方向。5.5 回归测试集七个Agent拆完以后最担心的是“改一个提示词另一个Agent跟着坏”。我建了一个很小的回归测试集20个典型场景覆盖七个Agent的输入和预期输出。每次改完提示词先在本地跑一遍确认所有Agent的JSON schema合法、关键字段变化符合预期再上生产。别看只有20条它帮我挡过几次“改路由把规则问答的口吻也带跑偏”的事故。测试集里的用例要保证每类Agent至少覆盖三条并且尽量包含边界情况。比如死活题判题我会专门放一道“看似双活其实净死”的题目。模型在这些用例上不能次次满分但必须能稳定给出合法结构和可靠结论。6. 如果让我重做这七个Agent我会改什么6.1 先定数据类型再定Agent最初的做法是先把功能想好每个功能写提示词再补输出格式。重做的话我会完全反过来先在代码层定义好全局的数据模型棋谱结构、坐标模型、变化图SGF、点评标签枚举全部先落成类。然后让每个Agent的输出向这些模型看齐。当时吃过亏的是两个Agent的输出格式定义得不一样一个用“player: B”一个用“color: black”导致前端要为两套数据结构各写一套渲染逻辑。后来统一成一套前端所有组件都只认同一个谱子结构改动量小了很多。数据模型是所有Agent之间的“通用语言”定得越早后面爬坑越少。6.2 路由Agent是真正的杠杆点我后补的意图路由Agent其实是整套系统里性价比最高的一个。重做时我会把它放在第一优先级。一个很短的意图分类Agent能把用户输入在进入其他六个Agent前就分干净不让提问跑到错误的任务链路里去。它的价值不只在于分发还在于拒绝。能识别出和围棋无关的请求直接拦截不让无关问题消耗昂贵的模型调用。对用户来说意图路由本质上是一种“智能入口”。就算识别错了兜底回规则问答也还算体面。这比让用户自己在十几个按钮里找功能体验高出一个量级。6.3 小模型处理小任务七个Agent里真正需要旗舰模型的其实不超过三个。其余用小巧模型配更短提示词效果和成本差距并不大。规则问答用旗舰模型和普通模型回答准确率几乎没差别但成本相差数倍。意图路由、术语解释这类小模型完全能胜任。模型分层不是妥协而是把每个Agent的“黄金token”用在刀刃上。如果一开始就把所有Agent绑在同一个旗舰模型开发省事运营时钱包会非常痛。6.4 Agent的设计和产品功能是一件事最后想说的是Agent不能停留在“底层能力”的想象里。每个Agent对应的小程序界面、按钮、数据流和异常兜底应该当成一个整体产品去设计。规则问答弹出来的是卡片单步点评下方有可拖动的变化图全局复盘输出三条要点。用户在前端只感受“好用”看不到背后拆了几个Agent。这大半年在围棋小程序里折腾七个Agent最大的心得是别把一个Agent做成什么都干的入口用户每一条具体需求都应该有一个足够小的Agent接得住。提示词负责把这个Agent的角色边界定义清楚结构化输出负责让它在小程序里真正干成事。先把棋谱数据洗干净再写提示词先定好输出合同再让Agent上线。这套方法在围棋这个场景里成立换到别的垂直领域我觉得也成立。