1. 先别急着写代码Skill 到底在解决什么问题在 Spring AI Alibaba 里折腾 Skill 接近两个月我最大的感受是很多人把 Skill 和简单的“函数调用”画上等号结果一到真实项目就处处拧巴。Skill 解决的核心问题不是“让模型能调你的方法”而是把 AI 应用里最容易失控的环节——模型与业务系统的边界——标准化。你有一个 Spring Boot 项目里面有查库存、算运费、生成报表这些现成方法想让 AI 助手在对话中自己去调用。最原始的做法是写一堆工具函数把名称、描述、参数格式告诉模型demo 里挺好使但真实项目里会接连踩三个坑工具数量一多模型就开始选择困难参数描述散落在各处注解里接口一调整就过期最麻烦的是你没办法在运行时动态决定“当前用户能不能调这个工具、能看多少细节”。Spring AI Alibaba 的 Skill 模块就是把这几个问题收拢在一起处理的。它提供了一整套从定义、注册到运行时管理的机制用Skill注解声明能力用SkillDefinition统一描述契约用SkillDefinitionRegistry管理注册生命周期再通过渐进式披露控制模型看到的信息边界。这套设计的好处是业务代码和 AI 交互代码解耦你可以像管理普通 Bean 一样管理 AI 能力也能在不停机的情况下动态注册新的技能。对于企业级应用来说这个特性比“多写几个工具方法”重要得多。这篇文章适合三类读者刚接触 Spring AI Alibaba想搞清楚 Skill 和原生Tool区别的入门者已经用上 Skill但对注册机制、披露机制一知半解遇到“模型老是不按规则调用”“参数传不对”的问题找不到头绪的开发者以及在做技术选型想评估“技能化”改造方案的架构师。我会用实际踩坑的经验串起整个流程从定义、注册到渐进式披露逐步展开尽量少讲虚的多给能直接落地的细节。2. 核心概念拆解从注解到注册表一条完整链路2.1 入口是注解Skill 与 SkillParam 的职责划分先明确一点Skill注解不是 Spring AI Alibaba 独创的概念它是把 Spring AI 原有的“工具描述”做了更严格的契约化。你可以在类上标注Skill也可以给某个具体方法标注。类级别的 Skill 适合一组相关操作比如“订单服务”包含查订单、改订单、取消订单方法级别的 Skill 适合单一独立能力。我个人更推荐方法级别因为披露和鉴权更精细模型不会因为一个类里混了敏感方法而误调用。SkillParam则负责描述方法参数。这里有个容易被忽略的细节它不光是给人看的注释它直接参与生成给模型看的 JSON Schema。字段的description、required、defaultValue都会影响模型对参数的判断。比如你写SkillParam(description 订单号支持多个用逗号分隔, required true)模型就能比较准确地填值如果你随便写“参数”两个字模型就会开始自由发挥传入错误格式。所以参数描述一定要站在“模型视角”写写清楚格式、边界和反例。2.2 SkillDefinition统一描述能力的接口注解只是入口真正在运行时发挥作用的是SkillDefinition这个接口。它把技能的名字、描述、参数结构、执行器统一封装成一个对象。在整个链路里这个对象是注册表、模型调用、审计日志共同依赖的唯一标准。理解这一点很关键无论你用注解还是用代码手动构建最终都会被解析成SkillDefinition所以后面所有能力披露、鉴权、监控都是围绕它展开的。接口里比较核心的维度包括getName()返回技能唯一标识getDescription()返回对模型的自然语言说明getParameters()返回参数 Schemaexecute()或getExecutor()则负责真正执行业务逻辑。设计层面试过几次之后你会发现这个抽象非常像“把函数式调用变成可描述、可管理的资源”跟 REST API 的 OpenAPI 规范思路异曲同工。有了统一定义你才能在下层做拦截、限流、审计而不是在模型调用时临时拼参数。2.3 SkillRegistry注册表到底管了哪些事SkillDefinitionRegistry是技能的“户籍系统”。它负责技能的注册、查询、注销维护一个运行时的技能清单。大部分场景下直接用默认实现DefaultSkillDefinitionRegistry就够了它内部是一个并发安全的 Map支持按名字精确查找也支持列出全部技能供模型选择。注册表还承担了一个很重要的职责维护技能和来源的映射关系。一个技能可能来自本地 Bean也可能来自动态下发配置还可能来自远端服务注册表需要能够统一管理这些异构来源。我建议把所有注册操作集中到一个配置类里做不要散落在各个业务模块里。因为技能是给模型用的全局资源你散落注册后面排查“为什么模型能调用这个技能”的时候会非常痛苦。集中注册还有一个好处你可以在注册阶段统一做增强比如包装统一鉴权逻辑、加统一日志埋点不必在每个 Skill 实现类里复制粘贴同样的代码。2.4 三种 SkillFactory创建方式决定灵活度SkillFactory 是负责把“定义源”转换成SkillDefinition的工厂。Spring AI Alibaba 里常见的有AnnotatedSkillFactory、DefaultSkillFactory和动态创建方案。AnnotatedSkillFactory扫描带有Skill注解的类或方法自动解析注解元数据生成定义这是最常见的用法DefaultSkillFactory支持通过 Builder 编程式构建适合无法用注解表达的场景动态创建则适合运行时下发技能定义的场景比如从配置中心拉取技能描述。选择依据很简单技能数量少、结构稳定用注解技能数量和内容需要动态调整用工厂加配置中心配合。我之前在一个项目里把所有技能用死代码写死后来产品要按客户维度开放不同功能只能加班重构。早一点想清楚技能定义的来源能省掉后面大量返工。3. 定义 Skill 的实操细节从依赖到第一个可运行技能3.1 环境准备依赖与基础配置讲解具体代码之前先搭好环境。假设你已经在用 Spring Boot 3.x只需要在 pom.xml 里引入 Spring AI Alibaba 的 starter版本建议直接用当前最新的 release 版本不要用快照版。引入依赖之后核心配置是 Model 的 key 和 endpoint。这里提醒一句生产环境一定不要硬编码 key用环境变量或配置中心注入。dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter/artifactId version${spring-ai-alibaba.version}/version /dependency启动类上加上SpringBootApplication即可框架会自动装配技能相关的核心 Bean包括注册表和默认的 SkillManager。装好后先别急着写业务建议写一个最朴素的技能验证链路是否通畅比如一个返回当前时间的技能。链路通了后面加复杂技能只是重复劳动。3.2 用注解定义技能一个订单查询的完整例子下面这个例子是我在实际项目中用过的写法省略了敏感的业务细节但结构是完整的。它演示了方法级 Skill、参数描述、异常处理三个关键点Service public class OrderSkillService { private final OrderQueryPort orderQueryPort; public OrderSkillService(OrderQueryPort orderQueryPort) { this.orderQueryPort orderQueryPort; } Skill(name queryOrderStatus, description 根据订单号查询订单的实时状态仅在用户询问物流或订单进度时使用) public OrderStatusResult queryOrderStatus( SkillParam(description 订单号通常是 18 位数字字符串例如 202410081234567890, required true) String orderId) { try { return orderQueryPort.queryByOrderId(orderId); } catch (OrderNotFoundException e) { throw new SkillExecutionException(订单不存在请核对订单号后再试); } } }注意几个细节description里我加了“仅在用户询问物流或订单进度时使用”这个触发条件它能让模型更准确地决定何时调用能显著减少误调用。SkillExecutionException是向上抛给模型看的异常模型会把它转成对用户的自然语言回复。业务异常如果不做转换模型拿到一堆堆栈信息回答质量会很难看。3.3 参数定义的正确姿势从模型视角反推描述定义参数是 Skill 里最容易被低估的环节。我的经验是写参数描述前先想清楚“模型手里拿到的是什么”。用户可能说“帮我看看我昨天下的单”模型并不知道具体订单号这时候如果参数是必填的模型只能回答“请提供订单号”体验很差。更合理的做法是把技能拆细一点一个技能根据手机号查订单另一个再根据订单号查状态模型可以先调第一个拿到订单号再调第二个查询状态。描述里还要写清楚格式约束。比如订单号通常是 18 位数字字符串例如 202410081234567890这种写法比单纯写“订单号”要可靠得多。模型是概率推理给例子能给它的猜测加一个强锚点。多值场景也要说清楚分隔符比如“支持多个订单号用英文逗号分隔最多查询 5 个”否则模型可能传数组、也可能传空格分隔接口实现就要做各种兜底。3.4 编程式定义绕过注解的复杂场景注解不是万能的。有些技能需要从数据库读取参数结构或者参数格式会频繁变动这时候注解方案就很尴尬。可以用DefaultSkillFactory编程式构建Bean public SkillDefinition dynamicReportSkill() { return DefaultSkillFactory.builder() .name(generateDailyReport) .description(生成销售日报按日期范围和维度汇总仅限管理者角色调用) .addParameter(SkillParameter.builder() .name(dateRange) .description(日期范围格式为 2024-10-01~2024-10-31) .required(true) .build()) .addParameter(SkillParameter.builder() .name(dimension) .description(汇总维度可选值byRegion/byProduct/bySalesman默认 byRegion) .required(false) .defaultValue(byRegion) .build()) .executor(params - reportService.generate(params)) .build(); }这样定义的好处是参数可以来自配置文件或数据库坏处是丢失了编译期检查。我的建议是不要把所有技能都改成编程式否则代码会非常啰嗦。注解优先动态场景按需用编码方式两种方式并存完全没有问题。4. 注册 Skill三种方式与选择逻辑4.1 自动注册放进 Spring 容器就完事最省心的注册方式是让框架自动扫描。只要你的 Skill 实现类被 Spring 管理框架的AnnotatedSkillFactory会自动读取注解并注册到SkillDefinitionRegistry。这种方法适合技能数量不多、结构稳定的项目。自动注册的优点是零额外代码缺点是注册时机不可控而且你不太容易在注册前做统一拦截。自动注册背后其实是一套BeanPostProcessor机制在 Bean 初始化完成后检查有没有Skill注解有就构建定义并写入注册表。理解这个机制后你会明白为什么“把 Skill 类放进容器就生效”——它和 Spring 的声明式事务其实是一个套路都是在 Bean 生命周期里做切面增强。如果你自定义了某些 Bean 的初始化顺序要注意别让技能类初始化太晚否则模型调用时注册表里还没有对应定义会报找不到技能的错误。4.2 手动注册把注册表当作一等公民管理需要精细控制时可以手动注册。我之前做多租户系统时用的就是这个方案因为每个租户开放的技能集合不一样自动注册满足不了。“手动”不是说让你到处 new而是集中在配置类里操作Configuration public class SkillRegistrationConfig { Bean public ApplicationRunner skillRegistrar(SkillDefinitionRegistry registry, ReportSkill reportSkill, OrderSkillService orderSkillService) { return args - { registry.register(registry.createSkillDefinition(reportSkill)); registry.register(registry.createSkillDefinition(orderSkillService)); }; } }手动注册配合 Spring 的ApplicationRunner可以保证在应用启动完成后、对外提供服务前完成注册。这种方式最大的优势是注册逻辑显式可见方便做权限过滤、日志记录、统计埋点。代价是每次新增技能都要改注册配置如果技能数量超过二三十个建议在注册处写一个简单的分组注解按业务域批量注册。4.3 动态注册让技能从“写死”变成“可下发”动态注册是企业级项目里真正拉开差距的功能。技能定义从配置中心拉取改技能描述、参数结构都不需要重新发版。实现思路是监听配置变更事件从配置内容解析出技能定义然后调用registry.register(...)写入注册表。注销同理调用registry.remove(name)即可。这里分享一个实战经验动态下发技能一定要加版本号和灰度开关。我最初做动态注册时没有版本概念结果配置中心刷新一次旧的技能定义被覆盖正在执行的请求突然拿不到参数描述模型调用直接失败。后来改成“注册表里维护多版本调用时按当前灰度策略选择”才把问题解决。技能的变更也是变更该有的版本管理、回滚策略一样都不能少。4.4 注册后必做的检查清单注册完成后建议做一套自检列出注册表里所有的技能名确认没有重名检查每个技能的描述是否以“动词业务对象”开头比如“查询订单状态”而不是“订单状态处理”模型对动词开头的描述识别准确率明显更高确认敏感技能没有暴露给所有用户。这三点每一条我都踩过坑尤其是重名问题框架通常会直接抛异常但如果是不同来源的技能偶尔重名异常信息并不直观。5. 渐进式披露让模型只看到它该看的东西5.1 渐进式披露到底披露什么渐进式披露是从模型上下文协议MCP里借鉴过来的设计理念核心思想是“分层次暴露信息”不要一次性把全部细节塞给模型。放在 Skill 场景里意思是模型一开始只看到技能的名字、一句话描述和极简参数提示够它做“要不要调用”的判断只有模型明确选中某个技能后系统才把该技能的详细参数 Schema、调用示例和内部实现信息完整披露出来。为什么要这样设计最直接的原因是上下文窗口和 token 成本。单个技能描述几百字注册几百个技能可能没感觉但换算成 token 就非常可观。而且信息越多模型的选择准确率反而下降——这就好比打开一个菜单有二三百道菜顾客反而更犹豫。渐进式披露的本质是做信息过滤让模型在每轮决策时只看当前需要的最小集。5.2 两层披露列表层与详情层在 Spring AI Alibaba 的 Skill 设计里披露通常分两层。第一层是列表层系统向模型展示当前可用的技能清单每个技能只包含name和shortDescription。这一层的目标是让模型快速完成“是否有匹配技能”的判断。第二层是详情层当模型决定调用某个技能后系统才把完整的参数结构、枚举值、调用注意事项传下去。实际使用中我要提醒一个容易忽略的点列表层的描述一定要“自包含”。因为模型只能靠这一句话决定是否深入如果这句话写得太笼统比如“处理订单相关操作”模型会在各种与订单无关的问题上都尝试调用。反过来一句话把触发场景写清楚比如“仅当用户查询订单物流状态时使用”模型的调用准确率会有质的提升。5.3 披露在注册阶段怎么落地渐进式披露不是运行时动态计算的魔法它依赖注册阶段就把“简版信息”和“详版信息”分开存好。在SkillDefinition里建议为每个技能维护两套描述summaryDescription用于列表披露控制在 50 字以内fullDescription用于详情披露可以包含参数示例、边界约束。然后实现一个披露组件按阶段决定向模型暴露哪一层。下面是一个简化版披露组件的思路Component public class ProgressiveSkillDisclosure { private final SkillDefinitionRegistry registry; public ListSkillSummary listVisibleSkills(String userContext) { return registry.all().stream() .filter(skill - permissionService.allows(userContext, skill)) .map(skill - new SkillSummary(skill.getName(), skill.getSummaryDescription())) .toList(); } public OptionalSkillDetail getDetail(String skillName, String userContext) { SkillDefinition skill registry.get(skillName); if (skill null || !permissionService.allows(userContext, skill)) { return Optional.empty(); } return Optional.of(new SkillDetail(skill.getName(), skill.getFullDescription(), skill.getParameters())); } }核心就两点第一按用户上下文过滤可见集合第二详情必须二次校验权限。很多人在第一步做了过滤第二步没有做结果用户绕过列表层直接调用详情接口敏感能力照样泄露。这里贴一个安全经验的“经验值”详情层和列表层必须走同一套权限校验逻辑不要各写一套。5.4 披露粒度带来的两个实战收益第一是 token 成本的可控。我把一个项目从全量披露改成渐进式披露后单次会话的模型输入 token 平均下降了 40% 左右对长期对话场景影响更明显。第二是技能编排的灵活性。披露机制天然支持“技能编排”的思路——模型先通过列表层知道有哪些能力再像搭积木一样组合调用这比一次性把十几个技能描述全给模型更接近真实业务中的复杂任务。不过也有反面教训过度披露会让模型在简单的闲聊里也带着一堆技能上下文增加幻觉概率披露太少又会让模型找不到可用技能直接“拒绝答题”。这个平衡要针对具体业务调试没有统一标准。建议你上线后把“模型是否在正确场景调用了技能”当作一个核心指标持续监控而不是只盯着回答是否流畅。6. 常见问题与排查技巧实录6.1 技能注册了但模型不调用这是出现频率最高的问题。模型不调用通常不是注册的问题是披露层的描述写得太差。排查路径建议按这个顺序先确认技能在注册表里能查到再确认列表层披露给模型的描述是否包含触发条件最后看模型的实际输入上下文里技能描述是否被截断或过滤。我遇到过一种隐蔽情况技能描述本身没毛病但前端把系统提示词截断了技能列表根本没拼接完整。6.2 参数校验失败的三种典型原因参数不对绝大多数是描述不清晰导致的但也有框架层面的原因。第一种是参数类型不匹配模型传了字符串但接口需要数值型建议在SkillParameter里显式声明type并给出示例。第二种是必填参数没用requiredtrue模型就可能漏传。第三种是技能内多个参数存在依赖关系比如先传了渠道参数才能传渠道账号这种隐含依赖建议在详情层描述里显式说明否则模型没法知道先后关系。6.3 动态注册后旧技能还在执行这个坑我在 4.3 里提过核心原因是注册表覆盖时没有处理正在执行的任务。动态更新技能定义前先查一下有没有正在执行中的调用必要时等优雅退出或直接拒绝更新。另外技能定义缓存也是一个隐藏坑。有些场景下模型侧的技能信息会缓存一段时间服务端更新了模型侧还是旧的定义两边版本要协商一致最好在技能定义里带一个version字段披露时带上版本号。6.4 常见问题速查表现象可能原因排查与解决模型完全不调用技能列表层描述缺少触发条件改写 summaryDescription明确“仅在…时调用”模型总是误调用技能描述过于宽泛增加反向约束描述里写明“不适用…场景”参数总是传错参数描述缺少格式示例补充格式说明和 example声明参数类型注册表查不到新技能Bean 初始化顺序问题检查技能类是否被扫描确认注册时机动态更新后行为异常多版本未隔离引入版本号按灰度策略选择定义敏感技能泄露详情层未二次校验权限列表层和详情层统一权限校验6.5 我的几个独家排查小技巧排查技能问题时我习惯先打印模型实际收到的上下文而不是盯着服务端日志看参数解析。很多时候问题出在“模型看到的”和“代码以为的”不一致。另一个技巧是给 SkillManager 的执行入口加一个 AOP 切面记录每次调用的技能名、参数、耗时和结果一个清晰的调用链比任何文档都管用。最后如果模型连续几次在同一个技能上反复出错别急着调提示词先看看是不是技能定义本身有歧义——直接去问业务方往往能发现描述里那个让你“以为是常识”的潜规则。7. 从 Skill 到 Skill 编排这套机制还能往哪走聊完基础能力我想说说 Skill 设计里最让我觉得有后劲的部分——编排。单个技能能解决的问题是有限的但把多个技能串起来就能处理更复杂的任务。渐进式披露天然为编排提供了舞台列表层让模型知道“有什么可用”详情层让模型学会“怎么用”而编排则让模型学会“什么时候用哪个、用完一个接着用哪个”。比如一个客服场景模型可以先用用户身份技能确认订单归属再调订单查询技能然后调售后规则技能给出答复整个链路是可解释、可审计的。要做到这一步技能设计就要从“面向方法”改为“面向任务”。我见过很多团队把技能粒度做成和 DAO 方法一样细结果模型编排起来非常吃力。我的建议是技能粒度以“一个业务意图”为最小单位比如“查询订单状态”是一个技能“批量导出订单数据”是另一个技能不要做成“订单模块”一个技能包办所有操作。粒度过大会让参数爆炸粒度过小会让模型陷入选择困难需要结合真实用户的提问模式反复调整。另外编排场景下一定要关注技能的幂等性和超时控制。模型在编排链路里是“试错”的它可能第一次调用参数不完整第二次修正后重试。如果技能本身有副作用比如“创建订单”这种写操作被模型连续调用两次就会产生重复数据。我在生产环境里对所有写类技能都强制要求幂等键这个改造花了两天但避免了无数次线上事故。框架层面也可以配合设置单次调用的超时阈值避免技能执行卡住导致整个对话流程悬死。我在实际项目里还有一个小技巧每个技能的方法体里尽量把核心业务逻辑委托给普通 ServiceSkill 类只做协议转换。这样做的好处是即使哪一天废弃了 AI 入口底层业务能力还能继续给别的渠道用。技能其实是“接口层”不是“业务层”分清这两层你的代码就不会越改越乱。最后再分享一点体会Skill 这套东西初期投入主要在理解和建模上代码量其实不大。但一旦在项目里立住了后续加新能力、做权限控制、做监控统计都会顺畅很多。如果你正打算在 Spring AI Alibaba 项目里接入技能化改造或者已经把 Skill 用起来了但还想优化调用准确率建议先从“描述质量”和“披露分层”这两个点入手这两处的投入产出比是最高的。