我相信很多人和我一样，最初接触智能体（Agent）的时候，兴奋点都放在模型调用和工具（Tool / Function Calling）上。查天气、查订单、算价格，感觉什么都能接上。可真正把一个面向真实业务的智能体推到联调、灰度、验收阶段，问题才接二连三冒出来：明明工具都在，模型也没换，可它经常在错误的场景调用错误的工具；有时候工具返回了一大堆结构化数据，模型根本不知道拿哪一段来答复用户；更难受的是，今天给一个技能改了参数，明天另一个场景的调用就静悄悄挂了。这些问题反复出现之后，我慢慢意识到一个结论：大部分智能体项目缺的不是模型能力，而是一套把工具组织成“技能”的方法。
这篇文章我想把自己在一个面向企业客户的智能客服项目里，从“工具堆砌”重构为“技能体系”的过程完整讲一遍。内容包括技能档案怎么设计、调度路由怎么做、评测回归怎么搭，以及几个差点让项目翻车的坑。如果你正在做智能体相关项目，尤其是要接入多工具、多场景的那种，这篇应该能帮你少走不少弯路。
1. 智能体项目的成败，往往卡在“技能”而不只是“模型”
1.1 工具与技能：一条容易被忽视的分界线
先把这个概念掰开。很多团队的做法是：把每个API封装成一个function，写好function description，然后丢给模型，让Agent自己决定调用什么。这种方式在小规模Demo里非常顺，因为场景固定、工具少、用户意图也单一。可一旦到了真实业务，工具数量超过十个、场景超过三五个，问题就开始炸了。
我习惯用一个类比来理解这件事：工具是“手”，技能是“手加上操作规范”。你可以给一个人一只万能扳手，但他不一定知道什么时候该拧、拧多紧、拧完要不要检查。可如果你教他“更换轮胎的完整流程”，他就知道先松螺丝、再顶千斤顶、最后对角紧固。对Agent来说，工具是单一动作，技能则是“在什么条件下、按什么顺序、调用哪些工具、如何处理异常”的行为包。
这也是我在项目里第一次重构时的最大认知转变：别再把智能体当成一个“会选函数的模型”，而要把它当成一个“掌握了若干技能的执行者”。
1.2 技能体系的本质是“场景行为包”
那技能体系具体包含什么？我的定义是：技能 = 触发条件 + 执行步骤 + 工具调用 + 护栏规则 + 上下文边界。它把模型需要判断的“该不该做、怎么做、做了之后怎么办”提前结构化了。
举个例子。客户问“我上个月的发票还能开吗”。如果只是工具堆砌，模型要在开票、订单查询、客户资质校验里自己摸索，很容易漏掉“先判断订单是否已完成”这种关键逻辑。但如果有个“发票补开预检技能”，它封装好了三步：校验订单状态、校验税率版本、生成补开预览单。模型只需要判断“用户意图是否匹配这个技能”，匹配就执行整个流程。
这带来的好处很直接：一是模型需要做实时判断的复杂度大幅降低，二是业务规则不需要写进提示词里反复调试，而是固化在技能内部，三是一旦规则变更，只改技能，不用动模型。这三条理由，足够说服团队把架构从“函数内存”改成“技能库+路由器”。
2. 技能描述是给模型看的说明书：七字段技能档案法
2.1 技能档案的核心字段
技能封装这件事，很多人以为就是给函数加个description。这是最大的坑。我在第一个项目里就这样写过：每个技能只有一句话描述，结果路由准确率不到六成，模型经常把“查账单”和“查订单”混在一起。
后来我把技能设计成一份“档案”，每个技能包含七个固定字段，像给新员工写岗位说明书一样：
| 字段 | 作用 | 我踩过的坑 |
|---|---|---|
| skill_id | 技能唯一标识，内部使用 | 命名不规范，后期统计全靠猜，建议用“领域_动作_对象” |
| name | 面向模型的可读名称 | 不要写“功能三号”，直接写“发票补开预检” |
| description | 判断是否触发该技能的说明书 | 太短命中差，太长容易和其他技能语义重叠 |
| trigger_conditions | 明确的触发与排除场景 | 一开始没写排除条件，误触发率高了一倍 |
| input_contract | 入参协议：必填、选填、类型、来源 | 参数宽松导致模型乱补默认值 |
| execution_plan | 执行步骤和调用顺序 | 不写这个，模型知道用什么技能却不会用 |
| guardrails | 护栏：不可执行项、审批要求、回滚策略 | 危险技能没有护栏，直接线上事故 |
这套结构看起来平平无奇，但真正用起来，每个字段都要抠细节。
2.2 一段能“有效命中”的技能描述长什么样
description是七个字段里最容易被低估的。它实际上决定了路由命中率。我定了一个硬规则：描述必须用第一人称，写清“当用户想……并且满足……时使用”，如果不符合某个条件，必须明确说“不要使用”。
比如之前那个“发票补开预检”技能，描述我最终改成：
当用户想补开、重开订单发票，并且订单已完成支付、当前不在退换货流程中时使用。如果用户只是咨询开票规则，不要使用本技能，请走发票规则问答流程。
这句话看着啰嗦，但实测命中率比原本的“提供发票补开功能”高了二十多个百分点。原因很简单：模型靠语义相似度判断，description越接近真实用户问题的表述，越容易匹配。反之，写成官方文档口吻，模型看到一头雾水。
另一个重要字段是execution_plan。它不是给模型看的，是给技能执行引擎看的。我会把步骤写成结构化伪代码，而不是自然语言：
- 调用订单查询接口获取订单状态，校验是否已支付
- 若订单处于退款中，直接返回失败原因，不进入下一步
- 调用发票资格校验接口，确认税率版本
- 写入补开预览单，返回预览结果
这样做之后，维修这类流程复杂的技能，执行稳定性提升非常明显，因为模型不需要每步都临时推理，只需要顺着固定路径执行。
提示：input_contract里一定要设置“参数来源”字段，注明参数是从用户对话里提取，还是从上下文里查。否则模型会在用户没说订单号时，自作主张填一个空字符串进去。
3. 路由调度：先召回、再决选，别把技能库整个递给模型
3.1 三种调度方式的对比
技能多了之后，第二个核心问题就是调度：用户说了一句话，系统怎么知道该激活哪个技能。这个环节我在项目里迭代了三版。
第一版是“全量塞给模型”。把所有技能的描述拼进系统提示词，让模型自己选。工具少的时候还能跑，一旦技能超过十五个，提示词长度直接失控，模型的选择准确率也断崖下跌。而且每次调用都把所有技能描述算一遍，token开销很大。
第二版是“纯向量召回”。把用户问题和技能描述都转成向量，算相似度取topK。速度快、开销小，但问题也很典型：语义接近的技能经常被混淆，比如“查询订单物流”和“查询订单预计送达时间”，在向量空间里太近了，容易召回到错的。
第三版才是我最终采用的“先召回、再决选”双层结构。低成本完成粗筛，再用高判断力做精决定，两全其美。
3.2 我在项目里采用的五步路由管线
整个路由管线分为五步，每一步都不复杂，但组合起来很稳定：
第一步：意图粗分。用规则或一个轻量分类模型，先判断这条query属于“订单类、账户类、发票类、售后类”中的哪一大类。这一步不用很准，只要能把明显不相关的技能排除掉就行。
第二步：向量召回。在所属大类里，用用户问题和技能description的向量相似度，召回top5候选技能。我用的阈值是cosine相似度0.5以上才保留，低了直接不进入下一步。
第三步：LLM决选。把用户问题、候选技能的完整档案（名称、描述、触发条件）交给模型，让模型输出“哪个技能最匹配”或“都不匹配”。这个环节因为候选数量少，准确率很高。
第四步：兜底处理。如果LLM判断都不匹配，不能让Agent自作聪明。我会让系统走“澄清话术技能”，主动向用户追问细节，而不是硬挑一个技能执行。
第五步：上下文约束。确定技能后，只把该技能声明的context_window里的上下文传给技能引擎，比如订单技能只看订单域数据，不看客户历史工单。
这套五步管线跑下来，路由准确率从第一版的62%提到了91%，上下文token开销反而比第一版降了将近一半。核心收益在于：模型不再需要从几十个技能里做选择，只需要做判断题。
注意：第三步LLM决选的温度参数我设成了0，不做创造，只做判定。另外，决选结果一定要记录日志，后面评测回归全靠这份路由日志做分析。
4. 技能也要有回归测试：从“能跑通”到“越改越稳”
4.1 黄金技能对：评测集的基本单位
技能体系建好之后，真正的挑战不是上线，是后续迭代。今天改一个技能描述，明天加一个新技能，谁能保证不影响别的技能？我在项目里吃过一次大亏：新增了一个“批量导出账单”技能，结果原本的“查账单明细”突然不触发了，原因就是新技能的description里包含了太多“查询账单”字样，抢了老技能的召回位。
从那以后，我强制团队建立了一套“黄金技能对”评测集。结构很简单，每个样本就是一条真实用户语料加上应命中的技能id：
| 用户语料 | 应命中技能 | 备注 |
|---|---|---|
| 我上个月的话费能开发票吗 | 发票补开预检 | 覆盖普通咨询和预检 |
| 这单已经发货了，能不能改地址 | 物流改址拦截 | 注意订单状态约束 |
| 帮我看看这周账单涨了没 | 账单明细查询 | 对比导出任务的语义 |
| 你们这个会员怎么退 | 会员取消引导 | 排除退款申请意图 |
评测集不用一开始就很大，我建议从三个渠道收集：真实客服聊天记录里摘录、业务方提供的常见问题、模型在线上跑偏时的badcase。攒到两百条左右，基本就能覆盖主要场景。
4.2 回归触发时机与线上灰度策略
有了黄金技能对，就可以做回归测试。我定的触发时机是三个：任何技能description变更、新增或删除技能、底层模型版本升级。每个变更都要跑一遍评测集，记录三个核心指标：召回率、命中率、误触发率。
这个流程看起来耽误时间，但收益非常大。有一次同事只改了“发票预检”技能的一个参数描述，回归测试立刻发现“发票红冲”技能的召回率掉了9个点，我们赶在上线前定位到原因：新描述里加入了“冲红”两个字，和另一个技能产生了语义交叉。如果没有回归测试，这个问题大概率会漏到线上，然后出现在用户投诉里。
线上灰度我采用的是流量分层策略：新版本技能库先跑5%流量，对比三个指标——任务完成率、人工介入率、用户差评率。连续观察48小时，如果任务完成率不低于旧版本且人工介入率不升高，才逐步放量到30%、100%。
让技能迭代也像发版一样有门禁，这件事是项目跑稳的关键节点。很多团队智能体项目死掉，不是因为建模不好，是因为没人敢改技能库，一改就出问题，最后只能永远停在demo阶段。
5. 三个差点让项目翻车的细节坑
5.1 技能描述“抢活”的语义冲突
前面提到新增技能把老技能召回率拉低，这个坑我在这里展开说说。问题根源是大家都在追求“描述写得全”，结果每个技能描述都覆盖了大量相似场景。比如“查账单”和“导账单”本来就接近，再各自补充一些“查消费”“看明细”“拉流水”的同义词，向量空间里就完全重叠了。
解决方式我前面提过，但值得再强调：每个技能只能写自己独有触发词和排除条件，不相关的场景不要提。比如“账单明细查询”只写“按时间/类型查看消费明细”，不要写“导出、下载、生成报表”这些词，把这些词留给“账单导出技能”。描述文本要给“无竞争”的风格，明确让渡语义空间。
5.2 危险技能缺少护栏：退款、发券、改地址必须设闸
第二个坑很典型：我们把“仅退款审批”直接封装成了一个普通技能，模型判断用户符合条件后就会自动走退款申请流程。结果在测试环境里，用户说“我不满意这个商品”，Agent真的发起了退单请求。虽然只是联调环境，但这个逻辑如果上线，后果不堪设想。
后来我规定，凡是涉及资金、优惠券、敏感数据修改的技能，必须在guardrails里声明“需要人工审批”，并且在执行引擎里加一道硬核校验——技能触发后先停在预执行状态，等待二次确认或人工介入。智能体可以做判断，但重要动作必须留一个“人在回路”的刹车。
5.3 技能返回值塞爆上下文
最后一个坑比较隐蔽。某个技能会调用客户详情接口，返回内容包括近三年订单、发票记录、联系方式在内的完整字段。这些数据一次性灌回给模型，上下文窗口直接被占掉大半，模型反而抓不住重点。
我们的做法是给所有技能加“返回值摘要协议”：技能执行引擎拿到原始数据后，只把摘要文本和关键字段传给模型，原始数据存到会话数据表里，模型在需要时可以按数据引用标识再取。
这个调整让上下文消耗降低了三成左右，也顺带解决了一个副作用问题：模型不会再对着无关字段自由发挥。
结尾的小建议
如果你正准备给智能体搭技能体系，我的个人建议是先忍住建大而全技能库的冲动。找一个最痛、频率最高的场景，只封装三个技能，跑通“召回-执行-回归”的闭环，再逐步往上加。技能数量和系统复杂度是指数关系，不是线性关系。一上来就规划几十个技能，很容易让路由和评测都陷入失控。
另外也建议保留一份“技能变更日志”。这不是给系统看的，是给你自己看的。技能体系的演进过程，本质上就是你对自己业务场景理解不断加深的过程。这份日志翻出来，比任何复盘文档都有说服力。
