1. Skill在企业级AI应用中的定位它不是另一个Function Calling我最初接触Spring AI Alibaba的Skill概念时第一反应是“这不就是Function Calling换了个名字吗”。直到在一个真实项目里我们被工具调用的混乱状态逼到墙角才意识到Skill这个抽象层解决的是完全不同维度的问题。当时的情况是这样的系统里有四十多个业务能力从查订单到算运费从改地址到开发票全都注册成了函数暴露给大模型。上线第一天就出事故——模型把“查询客户等级”调成了“修改客户等级”因为这两个函数的语义描述在模型看来太接近了。更头疼的是每个函数我们都要塞进Prompt里让模型知道它的存在上下文窗口越撑越大到了第四十个函数模型已经开始在回答里幻觉出根本不存在的操作。那段时间我一直在想问题到底出在哪。后来看到Spring AI Alibaba里Skill的设计思路才发现之前的做法犯了一个根本性错误把“模型能调用什么”和“模型应该看到什么”混为一谈了。1.1 为什么需要Skill这个抽象层Skill的定义可以从两个层面理解。从模型视角看Skill是一个“带说明书的能力单元”——它有名字、有描述、有输入输出约束模型只需要知道什么时候该用它。从工程视角看Skill是一个“可治理的代码单元”——它内部可以是简单的方法调用也可以是复杂的多步骤业务流程但对外暴露的一定是标准化接口。这个抽象层最大的价值在于它把“能力的定义”和“能力的暴露”彻底解耦了。我可以在系统里注册一百个Skill但模型在当前对话里只看到三个。Skill本身是静态的代码和元数据而“谁在什么条件下能看到它”完全由运行时决定。这个思路直接颠覆了以前把所有工具一股脑塞给模型的做法。1.2 Skill与Agent、Function Calling、MCP的边界很多人分不清这几个概念我用自己的话捋一遍。Function Calling是模型原生能力解决的是“从自然语言到结构化调用参数”的转换问题。它没有状态不关心权限也不管这个函数是不是应该给当前用户用。Spring AI Alibaba里底层确实用了Function Calling的机制但Skill在其之上加了很多企业级的东西。Agent是一个自主决策的循环体它自己决定“下一步调用什么”。Skill是Agent手里的工具包一个复杂的Agent内部可能会调度多个Skill同时还会结合记忆、规划等机制。MCPModel Context Protocol是标准化协议解决的是工具互联互通的问题。如果外部系统通过MCP提供服务Spring AI Alibaba可以把MCP Server的工具包装成Skill来使用。这么说吧Function Calling是底层通道MCP是互联标准Agent是执行主体而Skill是业务能力的标准封装。其中真正适合做权限控制、渐进式披露、版本治理的就是Skill这一层。因为它是唯一一个既能接触到模型交互层又能深入业务代码的地方。2. 定义Skill注解、参数Schema与“说人话”的description先给出一段真实可跑的示例代码这是我在项目中定义的第一个Skill用来查询订单状态。它麻雀虽小但把Skill定义的全部核心要素都涵盖了。2.1 从零定义一个Skill核心注解与实现类Skill( name orderQuery, group order, description 根据订单号或者客户手机号查询订单的实时状态包括待付款、待发货、运输中、已签收、售后中等。当用户询问我的订单到哪了、帮我看看订单状态时使用。, visibility Visibility.ON_DEMAND ) Slf4j public class OrderQuerySkill { SkillMethod( name queryOrderStatus, description 查询订单实时状态, parameters { Parameter(name orderId, description 订单号13位数字例如202501150001234, required false), Parameter(name phone, description 下单手机号后四位例如8888, required false) } ) public OrderStatusResult queryOrderStatus(String orderId, String phone) { // 业务逻辑校验参数至少传一个 - 调用订单服务 - 组装返回 if (StringUtils.hasText(orderId) || StringUtils.hasText(phone)) { return orderService.queryStatus(orderId, phone); } throw new IllegalArgumentException(orderId与phone至少传一个); } }这段代码有几个细节值得说。第一Skill注解里我显式指定了visibility Visibility.ON_DEMAND。这个字段是渐进式披露的核心开关后面专门讲这里先记住。第二SkillMethod是真正暴露给模型的方法级注解一个Skill类可以有多个SkillMethod相当于一个能力单元内部有多个操作。第三parameters里的required属性必须认真写。模型在选择参数时对必填和选填的处理逻辑完全不一样写错了会导致模型反复追问用户或者传错参数。2.2 description的写法决定了模型会不会用错我踩过最大的坑就是description写得太随意。一开始我写的是“查询订单状态”结果模型在用户问“退款退到哪了”的时候也调用了这个Skill然后返回了一堆无关信息体验极差。后来我总结了一套description写作规则现在团队里所有人都这么写前半句写能力边界这个Skill到底能做什么最好加限定词。中间写触发场景什么样的问题应该调用它越具体越好。后半句写反例什么样的问题不要调用它这一步最容易被忽略。比如把description改成“查询订单的物流和履约状态。当用户询问订单位置、发货进度、签收情况时使用。注意不处理退款进度、不处理商品质量投诉、不修改订单信息这些场景请使用其他Skill。”这样写有三个好处。第一模型能更准确地进行意图匹配第二在渐进式披露的场景下披露引擎可以把description里的关键词作为索引提前判断该把哪个Skill放出来第三代码审查的人能一眼看出这个Skill的职责边界。2.3 参数Schema给模型一张准确的操作说明书很多初学者会低估参数Schema的作用。在函数定义里模型就像一个照着说明书操作的新员工参数描述就是他唯一的信息来源。我强烈建议每个参数都写清楚格式、取值范围、示例和是否必填。比如orderId字段如果只写“订单号”模型可能会传入“昨天那个订单”这种无法解析的内容如果写成“13位数字例如202501150001234”模型就会先去提取数字再调用。phone字段同理写明“后四位”可以显著降低模型传完整手机号导致隐私风险的概率。还有一点参数的数量不要贪多。我见过有人把十个字段都塞进参数里结果模型根本不知道怎么填。控制参数数量只保留真正需要的字段是降低调用出错率最有效的手段之一。如果业务上确实需要很多信息可以考虑拆分成多个SkillMethod或者把部分信息放到上下文中而不是全部依赖模型填充。3. 注册机制拆解自动扫描、手动注册与分组元数据Skill定义好之后下一步是注册。Spring AI Alibaba中注册有两种主流方式自动扫描和手动注册。这两种方式不是互斥的我在项目中是同时用的。3.1 基于Spring Boot的自动注册利用Spring Boot的自动配置能力按包路径扫描带Skill注解的类将它们统一放入SkillRegistry。这是最省事的方案适合数量多、定义规范、不需要额外定制的Skill。Configuration public class SkillAutoScanConfig { Bean public SkillRegistry skillRegistry(ApplicationContext context, ListSkillPostProcessor postProcessors) { SkillRegistry registry new SkillRegistry(); MapString, Object skillBeans context.getBeansWithAnnotation(Skill.class); skillBeans.values().forEach(bean - registry.register(buildDefinition(bean))); postProcessors.forEach(p - p.process(registry)); return registry; } }自动注册有一个隐藏的好处Spring的ApplicationContext管理了Skill类实例的生命周期这意味着Skill内部可以注入其他业务服务、配置中心客户端、甚至线程池。这种能力让Skill不再是孤立的“工具函数”而是和整个业务体系连接在一起。不过自动注册也有个问题——它默认是“全量注册”。如果注册一百个Skill每个模型请求都把一百个Skill的元信息发给模型Prompt长度很快就会撑爆。这个问题必须由渐进式披露来解决第四章详细展开。3.2 手动注册与分组管理自动注册适合通用场景但有些Skill需要手动注册主要场景有三种外部系统对接的Skill、按租户区分的Skill、以及需要动态启停的Skill。手动注册时我习惯用SkillRegistration这个建造者模式SkillRegistration registration SkillRegistration.builder() .name(taxInvoice) .group(finance) .description(开具电子发票输入订单号和发票抬头信息返回开票结果。) .handler(taxInvoiceHandler) .visibility(Visibility.PRIVATE) .metadata(owner, finance-team) .metadata(riskLevel, HIGH) .version(1.2.0) .build(); skillRegistry.register(registration);看到那个metadata字段了吗这是被很多人忽略但极其强大的功能。你可以往里塞任意键值对比如负责人、风险等级、关联业务线、上线时间。后面做权限控制、审计、渐进式披露策略时这些元数据就是决策依据。没有元数据一切治理方案都是空中楼阁。分组管理是另一个关键动作。我会把Skill按照业务领域划分成order、finance、user、logistics、marketing等group。分组有两个用途一个是披露时可以按组来控制比如“金融类Skill只对财务角色可见”另一个是审计时可以按组统计调用频次和异常率。3.3 注册中心与元数据设计在企业级场景中注册中心的使用要分开看。有的是把Skill注册表放到配置中心管理比如Nacos有的是通过Spring AI Alibaba Admin的界面做运行时管理还有的是两者结合——定义与静态元数据放Nacos运行时状态放内存或Redis。我在项目里的做法是Skill的代码和注解属性随应用发布运行时可以通过Nacos动态调整Skill的visibility和disclosurePolicy。举个例子某个新Skill上线后发现模型老误调用我可以直接改配置把它的visibility从PUBLIC降为ON_DEMAND不用重新发版配置刷新后立即生效。Skill名称groupversionvisibilitydisclosurePolicy元数据orderQueryorder1.0.1ON_DEMANDSEMANTIC_MATCHownerorder-teamtaxInvoicefinance1.2.0PRIVATEROLE_BASEDriskLevelHIGHaddressChangeuser0.9.0PUBLICALWAYSowneruser-team我用这个表格管理当前注册中心里比较典型的几个Skill配置你会发现每个Skill的visibility和disclosurePolicy都不一样。这就是精细化治理的开始。4. 渐进式披露按上下文分阶段暴露技能的设计与实现如果要选一个这篇文章里最值得反复读的部分那一定是渐进式披露。它是Spring AI Alibaba在实际项目中解决“工具太多、模型选不过来”这个核心矛盾的关键设计。4.1 一次性全量暴露的问题先说清楚痛点。把几十个Skill的完整定义一次性塞给模型会引发四个问题第一是Token浪费和性能下降。每个Skill的description加参数Schema大概200-300个token五十个就是一万多token。每次请求都带着这堆信息响应延迟从原来的800ms直接飙到2秒以上。第二是选择准确率下降。模型面对太多选项时意图判断会退化错误调用率显著上升。第三是安全风险。所有能力都暴露给模型等于所有能力都暴露给用户。用户只要精心构造Prompt就能让模型调用那些本不该开放的Skill。第四是上下文污染。无关的Skill描述会影响模型对当前任务的理解甚至让模型“分心”去回答跟当前问题无关的事情。要解决这些问题关键不是靠模型更聪明而是在请求真正送到模型之前先算好一个“最小必要技能集”只把当前对话最需要的三五个Skill放进去。4.2 渐进式披露的分层模型我给它起了个名字叫“四层披露漏斗”从上到下依次是第一层 全部注册系统里所有Skill都被注册到Registry里这是静态事实。第二层 租户与角色过滤根据当前用户所属的租户、角色、权限筛掉无权的Skill。比如普通用户看不到“发票作废”这个Skill。第三层 上下文匹配利用当前对话内容、历史消息、用户意图匹配相关Skill组。比如用户在问物流就披露订单类Skill用户在聊发票才披露财务类Skill。第四层 动态发布这是会话内的动态调整。有些Skill在对话中间才被激活——比如用户先从“查看订单”开始然后追问“能不能改收货地址”此时addressChange这个Skill才被加入可见列表。这个漏斗每一层都过滤掉一批Skill最后进入模型上下文的往往只有两到五个。披露是“渐进的”意思是随着对话推进模型看到的Skill集合是动态变化的而不是一开始就固定不变。4.3 实现一个上下文感知的SkillSelector理解了分层模型代码实现就顺理成章了。核心是一个SkillSelector接口和它的实现类public interface SkillSelector { ListSkillDefinition select(DisclosureContext context); } Component public class ProgressiveSkillSelector implements SkillSelector { private final SkillRegistry registry; private final SkillDisclosurePolicyResolver policyResolver; Override public ListSkillDefinition select(DisclosureContext context) { // 第一步拿到该用户有权限的所有Skill ListSkillDefinition candidates registry.getAll() .stream() .filter(skill - permissionChecker.hasPermission( context.getUserId(), skill.group(), skill.metadata(riskLevel) )) .collect(Collectors.toList()); // 第二步根据上下文语义做粗筛 String recentText context.getRecentMessages(); SetString candidateNames candidates.stream() .filter(skill - matchesContext(skill, recentText)) .filter(this::meetsDisclosurePolicy) .map(SkillDefinition::getName) .collect(Collectors.toSet()); // 第三步补充会话内已激活的Skill candidateNames.addAll(context.getActiveSkillNames()); return candidates.stream() .filter(skill - candidateNames.contains(skill.getName())) .limit(context.getMaxSkillLimit()) .collect(Collectors.toList()); } private boolean matchesContext(SkillDefinition skill, String text) { // 简单的关键词/语义匹配生产环境可以用嵌入向量召回 return skill.matchKeywords(text) || skill.matchDescription(text); } private boolean meetsDisclosurePolicy(SkillDefinition skill) { return policyResolver.resolve(skill.getDisclosurePolicy()) .isAllowedNow(skill); } }这里有几个设计上的取舍我说一下。matchesContext我用的是关键词加description匹配这是为了快速演示。实际生产环境我会把每个Skill的description、示例问句预切成向量请求进来后先算意图向量再做近邻检索召回Top-K个候选Skill。这样的语义匹配准确率比纯正则高很多而且延迟可控。context.getActiveSkillNames()是一个会话级的状态它记录的是在这个会话里已经调用成功过的Skill。这个设计很巧妙——对话具有连续性用户可能在上下文里隐含地引用了之前的操作比如“刚才那个订单改成用这个地址收货”。“刚才那个订单”指的就是会话早先激活过的订单查询Skill所以它必须一直保留在可见集合里否则模型会失去对之前动作的追踪能力。这就是“渐进式”的语义已有的跟上进度新的被逐步纳入。4.4 披露状态流转从隐式到显式再到回收一个Skill在对话生命周期里会经历几种状态HIDDEN未披露。用户没提到相关领域模型也看不到。CANDIDATE候选。上下文匹配到了但还没进入模型上下文等待披露策略确认。VISIBLE已披露。模型可以调用它。ACTIVE已激活。已经被模型调用过接下来持续保留在上下文里。SUPPRESSED被抑制。已经披露过但当次请求被策略临时禁用比如检测到高风险的敏感操作。其中SUPPRESSED状态很值得多说一句。它的典型场景是用户一开始在正常查询订单Skill是可见的突然用户说“帮我把收货地址改成一个陌生地址再下一个大单”此时addressChange这个Skill在常规披露逻辑下是可见的但风险引擎检测到该用户的登录设备异常、收货地址变更频率超高、单笔金额超过阈值于是对这个会话发出风险信号把这个Skill临时置为SUPPRESSED状态直到风险解除或人工审核通过。状态流转是有审计价值的。我在实现时把每一次HIDDEN - CANDIDATE - VISIBLE - ACTIVE - SUPPRESSED的变更事件都记录到日志系统里。出了安全事故后回溯这条状态流转链就是完整的证据链。你不仅能知道“模型调用了它”还能知道“系统是何时决定向模型披露这个技能的”这个在合规审计里至关重要。5. 企业级落地的治理版本、权限、审计与灰度渐进式披露解决了“模型用得好”的问题但企业级落地还牵涉“管得住”的问题。一个Skill上线之后它就不是一个简单的代码类了而是一个需要全生命周期治理的业务资产。5.1 版本管理与兼容性Skill的版本管理比普通接口复杂。因为Skill的调用方有两类一类是模型模型根据description理解Skill一旦描述变了模型的调用行为就会变另一类是上游业务流程它们依赖Skill的参数和返回值结构。我在项目中推行了一套版本管理规范破坏性变更删除参数、修改返回值结构、改变触发语义必须升级大版本旧版本保留至少一个发布周期。非破坏性变更调整description措辞、新增可选参数、优化内部实现可以原地更新但要记录版本变更到元数据。灰度策略新版本先对内部测试租户披露再放到ON_DEMAND条件下的低风险场景最后全量放开。关于灰度Skill比普通接口多了一层特殊方法你可以同时注册orderQuery1.0和orderQuery1.1然后通过DisclosurePolicy把流量切分。比如10%的会话命中1.1版本90%命中1.0。这个能力在“优化description后想知道模型调用准确率有没有提升”这个场景下非常实用。5.2 权限模型与审计链路权限控制必须放在披露阶段而不是调用阶段。如果等模型选完Skill再在方法里做权限判断你已经把不该暴露的操作暴露给模型了。而且大模型是概率系统它做错误选择的概率永远存在工程上必须从源头杜绝这种可能。我在代码里做了一个机制权限判断和Skill披露是绑定的。具体就这么实现的SkillMethod(name cancelHighValueOrder, description 取消高价值订单仅限财务主管及以上角色使用)同时定义一个拦截器在Skill注册的阶段就把权限规则解析出来ProgressiveSkillSelector在做候选过滤时直接使用。普通业务人员进入对话这个Skill根本不会进入模型视野财务主管进入对话它才会被纳入候选。这样做的安全性远高于“所有Skill都披露给模型让模型自己去判断权限”。审计链路也不能只记调用结果。我建议至少记录四个时间点的数据Skill被披露的时间、模型选出该Skill的时间、Skill实际执行的结果、执行后的业务影响。这四个点串起来才能完整回答“为什么这个Skill被调用了”以及“发生了什么事”。我在生产环境里用的是AOP切面统一记录所有SkillMethod的执行轨迹都进入审计日志写入Elasticsearch供安全团队检索。5.3 可观测性披露比调用更值得关注运营一个AI应用观测指标和传统接口不一样。传统接口你关心QPS、错误率、延迟而Skill类应用还需要额外关注“披露率”和“采纳率”。举个例子某个新上线的Skill披露了一百次但模型一次都没调用过。这说明description写得不够清楚或者触发的场景设计有问题。再比如某个Skill披露率很高、调用率也很高但调用后的业务成功率只有60%那可能是Skill内部的业务逻辑有bug也可能是模型把参数理解错了。我把关键的可观测性指标整理成一个表格供参考指标计算方式监控意义披露率被纳入模型上下文的次数 / 总请求数衡量渐进式披露策略的时效性调用率被模型实际调用的次数 / 披露次数衡量Skill描述与真实需求的匹配度参数正确率参数完全正确的调用次数 / 总调用次数反映参数Schema的清晰度业务成功率返回业务成功结果 / 总调用次数反映Skill内部业务逻辑的可靠性披露延迟从对话开始到首次披露的时间差反映渐进式披露在多层漏斗内的判断效率这些指标不能只看聚合值一定要按Skill分组、按用户类型过滤。我见过一个团队说“我们这个Skill的调用率只有5%”后来发现是因为草率地把Skill设为PUBLIC所有用户都会看到它但真正相关的人只占5%这个5%其实才是正常的。把visibility改为ON_DEMAND之后披露率降下来了调用率却升到了30%以上这就是渐进式披露带来的直接数据改善。6. 踩坑实录我在Skill落地中的几个具体教训最后分享几个我在真实项目里踩过的坑。这些坑在设计阶段很难想到只有写完代码、上了灰度、跑完压测才会暴露出来。第一个坑description里堆砌反例导致模型“过度思考”。我一开始写反例写得太详细列了一长串“不要处理退款、不要改地址、不要算运费、不要催物流”结果模型面对一个简单查询时反而开始怀疑“这个请求是不是包含退款意图”犹豫半天选了别的Skill。后来我把反例压缩到一句“仅处理物流履约状态查询其他问题请使用对应Skill”准确率反而上来了。description的目标是帮助模型快速判断而不是让模型做阅读理解。第二个坑每次请求都动态计算候选集性能扛不住。最初的SkillSelector实现里matchesContext用向量检索每次请求都去查向量库追加了80ms的延迟而且大促场景下直接把向量库打爆了。后来做了两级缓存第一级是“Skill与意图模板”的静态映射表秒级更新第二级才是向量召回只有静态映射没有命中时才走向量库。这个优化把披露延迟降到了20ms以内。渐进式披露本身就是性能优化手段它的内部逻辑反而引入性能损耗这是需要特别注意的。第三个坑会话内ACTIVE状态的Skill无上限累积。用户在一个长会话里问了很多领域的问题activeSkillNames不断追加最终又把上下文撑爆了。后来加了两个约束每个会话里ACTIVE状态的Skill数量上限是八个当某Skill连续五轮对话都没有被模型引用时自动降级为VISIBLE不再占用核心上下文位置只保留一个轻量级引用在会话状态里。这个机制保证长会话依然能保持可控的上下文长度。第四个坑版本灰度期的新版本“抢”了不该有的流量。我们给orderQuery的新旧两个版本做灰度新版本在description里把触发场景扩展到了“预购订单”结果灰度流量里预购订单相关的请求全部被新版本抢走导致预购业务出现了短暂的数据口径混乱。后来在DisclosurePolicy里加了显式的规则版本灰度会同时锁定“触发场景范围”新版本只能处理白名单场景的问题其他问题回退到旧版本。也就是说Skill的版本灰度要连同它的披露边界一起做不能只换处理逻辑。说回渐进式披露这件事本身。它不是一个开箱即用的配置而是一整套需要根据业务场景迭代的设计。每次新增一个Skill我都要先想清楚它的visibility是什么、disclosurePolicy是什么、触发词是什么、对哪些角色可见。这套流程跑顺之后新Skill接入的成本很低但稳定性却高得多。对我个人而言Skill最吸引人的地方在于它第一次让AI应用的能力治理有了工程层面的抓手。模型依然是概率系统但Skill作为边界和容器把不确定性关在了笼子里。渐进式披露则确保这个笼子的门在合适的时机打开而不是一直敞开。这个思路值得每一个做企业级AI应用的人认真对待。