1. 从能聊到能干Skill 系统到底补上了 Agent 的哪块短板大模型能写诗、能编故事、能陪你聊一下午人生哲学但你让它帮你把一份 Excel 里的数据清洗完再生成图表它大概率会给你一段看起来很像那么回事、实际跑起来全是错的 Python 代码。这不是模型不够聪明而是它缺了一套把语言能力翻译成可执行动作的机制。Skill 技能系统要解决的正是这个从聊天到干活的最后一公里问题。我接触过不少 Agent 项目早期大家的做法基本是一个超级 Prompt 打天下——把所有工具描述、操作规范、输出格式全塞进系统提示词里。项目小的时候没问题一旦工具数量超过十个Prompt 就开始失控模型会混淆工具用途、参数填错、该调用的时候不调用、不该调用的时候乱调用。Skill 系统的出现本质上是把能力从提示词里解耦出来变成一个个独立、可组合、可版本管理的模块。这篇文章适合三类人看一是正在做 Agent 开发、被工具编排搞得焦头烂额的工程师二是想理解 Agent 架构演进逻辑的技术管理者三是刚入门 Agent 领域、想知道Skill 和普通 Function Calling 有什么区别的学习者。我会从 Skill 的核心设计理念讲起拆解它的注册、路由、执行、回传全链路重点讲清楚 SSE 在其中的角色、RestTemplate 这类传统 HTTP 客户端怎么和流式场景配合以及我在实际项目中踩过的那些坑。关键词里出现了 SSE、RestTemplate、Java 实现 SSE、stream disconnected before completion 这些信号说明很多读者是在 Java 技术栈下做 Agent 的。这很合理——企业级系统大量跑在 Java 上而 Agent 的流式交互又天然依赖 SSE。这两者怎么结合是本文的重点之一。另外像skill 编码247codex skillcursor 有哪些 skill 推荐这些热词反映出大家关心的不只是原理还有具体怎么落地、有哪些现成的 Skill 可以参考。先说结论Skill 系统不是 Function Calling 的简单包装它是一套完整的能力治理方案。Function Calling 解决的是模型能不能调用一个函数Skill 解决的是模型在什么场景下、按什么规范、调用哪一组函数、失败了怎么兜底、结果怎么呈现。这个区别决定了你的 Agent 是玩具还是生产力工具。2. Skill 与 Function Calling 的本质差异能力治理 vs 单次调用2.1 一个容易被忽略的认知误区很多人第一次听说 Skill第一反应是这不就是 Function Calling 换了个名字吗。我一开始也这么想直到在一个真实项目里被教育了。那个项目有大概三十多个工具函数涵盖数据库查询、文件操作、外部 API 调用、数据计算。用纯 Function Calling 的方式把所有工具定义塞进请求结果模型经常在该查数据库的时候去调了文件读取参数还填得似是而非。问题出在哪Function Calling 给模型的是函数签名但没给模型使用场景。模型知道有个queryDatabase(sql)函数但它不知道当用户问的是历史订单统计时应该先调getTableSchema再调queryDatabase而且 SQL 必须带时间范围限制。这些上下文纯 Function Calling 是表达不了的。Skill 的思路完全不同。一个 Skill 是一个自包含的能力单元它包含触发条件什么时候用这个 Skill、执行逻辑内部可能调用多个 Function、参数规范输入输出格式、错误处理失败了怎么办、以及使用示例few-shot 演示。模型看到的不是一堆散落的函数而是几个语义清晰的技能包。2.2 对比表格从调用粒度到治理维度维度Function CallingSkill 系统抽象层级单个函数一组相关能力的封装触发方式模型根据函数名和描述判断根据 Skill 的触发条件语义路由参数校验依赖模型自觉Skill 内部做 schema 校验和默认值填充错误处理返回错误信息给模型靠模型自己重试Skill 内置重试、降级、兜底逻辑组合能力模型需要自己编排多个函数调用Skill 内部可以编排对外暴露单一入口版本管理函数改了 Prompt 就得改Skill 独立版本化可灰度发布可观测性只能看到函数调用记录可以看到 Skill 级别的成功率、耗时、失败原因这个表格不是要证明 Function Calling 不好而是说明两者解决的是不同层次的问题。Function Calling 是原子能力Skill 是分子能力。一个成熟的 Agent 系统底层用 Function Calling 做实际执行上层用 Skill 做能力编排和治理。2.3 为什么这个区分对 Java 技术栈特别重要Java 生态里做 Agent天然会倾向于重架构的思路。Spring 的依赖注入、AOP、Bean 管理这套东西其实和 Skill 的设计理念非常契合。一个 Skill 可以就是一个 Spring Bean通过注解声明触发条件和参数规范由框架自动注册到 SkillRegistry 里。这样做的最大好处是Skill 的开发和普通业务代码没有本质区别团队里熟悉 Spring 的人可以快速上手不需要额外学习一套全新的编程范式。我在一个项目里就是这么做的定义了一个AgentSkill注解标注在 Spring Bean 的方法上注解里声明 skillName、description、triggerExamples。应用启动时一个SkillScanner扫描所有带这个注解的 Bean把元信息注册到 SkillRegistry。运行时Agent 根据用户输入做语义匹配找到对应的 Skill通过反射调用。整个过程对业务开发者是透明的他们只需要关心这个 Skill 干什么、输入输出是什么。3. Skill 的注册、路由与执行一条完整的调用链路3.1 Skill 注册元信息比实现更重要一个 Skill 能不能被正确使用80% 取决于元信息写得好不好。我见过太多项目Skill 的实现逻辑没问题但 description 写得含糊其辞导致模型根本不知道该在什么时候用它。Skill 的元信息至少应该包含这几项skillName唯一标识用英文语义清晰比如order-statistics-query而不是tool1displayName给用户看的中文名比如订单统计查询description一句话说清楚这个 Skill 能做什么要包含典型使用场景triggerExamples3-5 个用户可能说的原话用于语义路由时的相似度匹配inputSchema输入参数的 JSON Schema明确类型、必填项、默认值outputSchema输出格式定义方便下游处理version版本号支持灰度这里有个经验triggerExamples 要覆盖同义不同说法。比如查一下上个月的订单和帮我看看上月订单情况和上个月卖了多少单这三句话语义相同但表述不同都要作为示例放进去。语义路由的准确率很大程度上取决于示例的覆盖度。3.2 语义路由怎么让模型选对 Skill路由是 Skill 系统里最容易出问题的环节。常见做法有三种第一种是纯 Prompt 路由把所有 Skill 的 description 拼成一段文字让模型选。优点是简单缺点是 Skill 多了之后 Prompt 爆炸而且模型容易选错。第二种是向量检索路由把 Skill 的 description 和 triggerExamples 做 embedding用户输入也做 embedding算余弦相似度取 Top-K。优点是快、可扩展缺点是对语义细微差别不敏感。第三种是混合路由先用向量检索召回 Top-5再用一个小模型或者规则做精排。这是我在生产环境里用得最多的方案准确率和性能都能兼顾。具体实现上我一般会维护一个 Skill 向量库用 Redis 或者内存向量索引都行。用户输入进来后先做一次向量召回拿到候选 Skill 列表然后把候选 Skill 的详细信息包括参数 schema拼进 Prompt让主模型做最终决策。这样既控制了 Prompt 长度又保证了决策质量。3.3 执行与回传SSE 在这里扮演什么角色Skill 执行往往是耗时的——可能要查数据库、调外部 API、跑计算。如果等全部执行完再返回用户会盯着空白屏幕等好几秒体验很差。这时候 SSEServer-Sent Events就派上用场了。SSE 的本质是服务器向客户端单向推送事件流。在 Skill 执行场景里我们可以把执行过程拆成多个阶段每个阶段完成就推一个事件给前端// 伪代码示意Skill 执行过程中的 SSE 推送 public void executeSkill(String skillName, MapString, Object params, SseEmitter emitter) { try { emitter.send(SseEmitter.event().name(start).data(开始执行 skillName)); // 阶段一参数校验 validateParams(params); emitter.send(SseEmitter.event().name(progress).data(参数校验通过)); // 阶段二执行核心逻辑 Object result doExecute(skillName, params); emitter.send(SseEmitter.event().name(progress).data(核心逻辑执行完成)); // 阶段三结果格式化 String formatted formatResult(result); emitter.send(SseEmitter.event().name(result).data(formatted)); emitter.complete(); } catch (Exception e) { emitter.send(SseEmitter.event().name(error).data(e.getMessage())); emitter.completeWithError(e); } }这样前端可以实时显示正在校验参数正在查询数据正在生成结果用户感知到的等待时间大幅缩短。而且如果中途出错前端能立刻知道是哪一步出的问题而不是等半天收到一个笼统的失败提示。3.4 RestTemplate 在流式场景下的尴尬与替代方案关键词里出现了 RestTemplate我猜很多读者是在用 Spring 的传统 HTTP 客户端调外部服务。这里要提醒一句RestTemplate 不适合处理 SSE 流。它是阻塞式的会把整个响应体读完才返回而 SSE 是无限流用 RestTemplate 调会导致线程一直挂着直到超时。如果你要在 Java 里消费 SSE 流有几个选择WebClientSpring WebFlux 提供的响应式客户端天然支持流式处理bodyToFlux(String.class)就能拿到事件流。这是目前最推荐的方式。OkHttp 的 EventSource如果你不想引入 WebFluxOkHttp 的 SSE 支持也很成熟。HttpURLConnection 手动读流最原始的方式能跑但代码丑不推荐。而如果你是生产 SSE 流也就是服务端推送Spring MVC 的SseEmitter就够用了不一定非要上 WebFlux。SseEmitter底层是基于 Servlet 3.0 的异步支持在 Tomcat 上跑没问题。但要注意配置好超时时间默认是 30 秒Skill 执行如果超过这个时间就会被断开前端会收到stream disconnected before completion: idle timeout waiting for sse这类错误。4. 生产环境踩坑实录SSE 超时、断流与 Skill 执行失败4.1 那个让我加班到凌晨两点的 idle timeout项目上线第一周监控报警说大量 Skill 执行失败错误信息是stream disconnected before completion: idle timeout waiting for sse。我第一反应是网络问题查了半天网关和负载均衡配置没发现异常。后来把日志拉出来仔细看发现失败集中在几个重Skill 上——比如生成月度经营分析报告这种内部要调好几个外部接口还要跑一段计算耗时经常超过 30 秒。问题根因很清楚SseEmitter的默认超时是 30 秒而我的 Skill 执行时间超过了这个值。SSE 连接被服务端主动关闭前端收到断流错误。修复方式有两种第一种是延长超时时间。创建SseEmitter时传入更大的超时值比如new SseEmitter(300000L)表示 5 分钟。但这不是根本解法因为如果 Skill 真的要跑 5 分钟用户干等着也不合理。第二种是心跳保活 异步执行。Skill 提交到线程池异步执行主线程定期发送心跳事件比如每 10 秒发一个ping保持连接活跃。Skill 执行完成后再推送最终结果。这样即使执行很久连接也不会因为空闲被断开。我最后采用的是第二种方案配合一个合理的超时上限比如 10 分钟。心跳事件的实现很简单// 心跳保活每 10 秒发一个注释事件保持连接 ScheduledExecutorService heartbeat Executors.newSingleThreadScheduledExecutor(); heartbeat.scheduleAtFixedRate(() - { try { emitter.send(SseEmitter.event().comment(heartbeat)); } catch (IOException e) { // 连接已断开停止心跳 heartbeat.shutdown(); } }, 0, 10, TimeUnit.SECONDS);注意心跳事件用comment类型前端不会把它当作业务事件处理但能保持 TCP 连接活跃防止中间代理因为长时间无数据而断开连接。4.2 Skill 执行到一半挂了状态怎么恢复另一个坑是 Skill 执行的非原子性。一个 Skill 内部可能调了三个外部接口前两个成功了第三个失败了。如果直接返回失败前两个接口产生的副作用比如写入了数据就变成了脏数据。我的处理方式是在 Skill 层面引入补偿机制。每个 Skill 声明自己的补偿逻辑执行失败时触发。比如创建订单并扣减库存这个 Skill如果扣库存失败补偿逻辑就是取消刚创建的订单。这本质上是一个简化版的 Saga 模式。实现上我定义了一个CompensableSkill接口public interface CompensableSkill extends Skill { // 执行主逻辑 SkillResult execute(SkillContext context); // 补偿逻辑执行失败时调用 void compensate(SkillContext context); }Skill 执行器捕获异常后调用compensate方法。补偿逻辑本身也要做幂等因为可能被重复调用。这个设计在订单、支付、库存这类场景里特别重要能避免大量人工修数据的麻烦。4.3 模型选错 Skill 的排查链路有一次用户反馈问天气却返回了股票行情这是一个典型的 Skill 路由错误。我的排查链路是这样的第一步看路由日志。我在路由环节打了详细日志记录用户输入、向量召回结果、最终选中的 Skill。一看日志发现用户输入今天天气怎么样被路由到了stock-querySkill。向量召回阶段stock-query的相似度居然排第一。第二步检查 Skill 元信息。打开stock-query的 triggerExamples发现里面有一条今天行情怎么样。问题找到了——今天...怎么样这个句式在天气和股票场景里都出现了向量模型被这个表面相似性误导了。第三步修复。我把 triggerExamples 改得更具体股票 Skill 的示例改成今天大盘涨了吗帮我查下茅台股价这种带明确领域词的句子。同时在路由环节加了一个领域关键词过滤如果用户输入里包含天气温度下雨这类词直接排除股票类 Skill。这个规则简单但有效把这类错误降到了接近零。这个案例说明Skill 路由不是纯技术问题很大程度上是语料工程问题。triggerExamples 的质量直接决定了路由准确率。我的经验是每个 Skill 至少准备 5 条示例覆盖不同的表达方式而且要定期根据线上 badcase 补充。4.4 并发场景下的 Skill 状态污染还有一个比较隐蔽的坑Skill 实例的状态管理。如果 Skill 被设计成单例 BeanSpring 默认就是单例而 Skill 内部又有成员变量来存执行状态那并发调用时就会互相污染。我就遇到过 A 用户的查询参数被 B 用户的请求覆盖的情况排查了好久才定位到。解决办法很简单Skill 必须是无状态的。所有执行状态都通过方法参数传入通过返回值传出不要用成员变量存状态。如果确实需要缓存一些东西用ThreadLocal或者外部缓存并且做好清理。这个原则和 Servlet 的设计原则是一样的老 Java 程序员应该很熟悉。5. 从零搭一个最小可用的 Skill 系统Java 实现要点5.1 核心组件划分一个最小可用的 Skill 系统至少需要这几个组件Skill 接口定义 Skill 的基本契约包括元信息获取和执行方法SkillRegistry注册中心管理所有 Skill 的元信息和实例SkillRouter路由器根据用户输入选择合适的 SkillSkillExecutor执行器负责调用 Skill 并处理异常、超时、补偿SseEmitter 管理负责向前端推送执行进度这几个组件的职责要清晰不要混在一起。我见过把路由和执行揉在一个类里的代码后期维护极其痛苦。5.2 Skill 接口设计public interface Skill { // 元信息 SkillMeta getMeta(); // 执行 SkillResult execute(SkillContext context); // 是否支持流式输出 default boolean supportsStreaming() { return false; } }SkillMeta包含前面说的那些元信息字段。SkillContext封装用户输入、会话信息、历史上下文等。SkillResult包含执行结果、状态码、错误信息。这个接口设计的关键点是简单。不要一上来就设计得很复杂什么拦截器、过滤器、中间件全加上。先把核心链路跑通后面根据实际需求再扩展。5.3 注册中心的实现注册中心的核心是一个ConcurrentHashMapkey 是 skillNamevalue 是 Skill 实例。启动时扫描所有 Skill Bean注册进去。同时维护一个向量索引用于路由。Component public class SkillRegistry { private final MapString, Skill skillMap new ConcurrentHashMap(); private final VectorIndex vectorIndex new VectorIndex(); PostConstruct public void init() { // 扫描所有 Skill Bean 并注册 // 实际项目中可以通过 ApplicationContext 获取所有 Skill 类型的 Bean } public void register(Skill skill) { SkillMeta meta skill.getMeta(); skillMap.put(meta.getSkillName(), skill); vectorIndex.add(meta.getSkillName(), meta.getDescription(), meta.getTriggerExamples()); } public ListSkill route(String userInput, int topK) { ListString candidates vectorIndex.search(userInput, topK); return candidates.stream().map(skillMap::get).collect(Collectors.toList()); } }向量索引可以用简单的余弦相似度实现也可以接入专业的向量库。小规模场景几十个 Skill用内存计算完全够用不需要上重型方案。5.4 执行器的异常处理策略执行器的核心职责是让 Skill 执行变得可靠。我总结了几个必须处理的场景异常场景处理策略Skill 不存在返回明确错误提示用户换个说法参数校验失败返回具体哪个参数有问题引导用户补充执行超时中断执行触发补偿返回超时提示外部依赖失败重试 N 次仍失败则降级或返回错误执行中抛异常记录堆栈触发补偿返回友好错误结果序列化失败兜底返回文本描述避免整个请求失败这些策略不是拍脑袋定的每一条都对应我实际遇到过的问题。比如结果序列化失败这条是因为有一次 Skill 返回了一个包含循环引用的对象Jackson 序列化时直接栈溢出整个请求 500。后来加了兜底逻辑序列化失败就返回toString()的结果至少不会让用户看到白屏。5.5 SSE 推送的工程细节SSE 推送看起来简单实际有不少细节要注意事件命名要规范用start、progress、result、error这种语义化名称前端好处理数据格式要统一建议统一用 JSON即使内容是纯文本也包一层方便扩展连接关闭要优雅正常完成调complete()出错调completeWithError()不要直接关异常要捕获emitter.send()可能抛IOException客户端断开必须捕获否则会污染日志超时要配置根据业务最长执行时间设置宁大勿小配合心跳保活还有一个容易被忽略的点SSE 连接数限制。浏览器对同一域名的 SSE 连接数有限制HTTP/1.1 下通常是 6 个如果用户开了多个标签页可能会互相挤占。解决方案是升级到 HTTP/2或者用 WebSocket 替代。不过对于大多数内部系统这个限制影响不大。6. Skill 生态的演进方向与选型建议6.1 现成 Skill 参考从 codex skill 到 cursor skill关键词里出现了codex skillcursor 有哪些 skill 推荐说明大家很关心现成的 Skill 生态。目前主流的 AI 编程工具都在往 Skill 化方向走。Codex 的 Skill 机制允许用户定义自定义命令Cursor 的 Rules 和 Commands 本质上也是一种轻量级 Skill。这些工具的设计思路值得借鉴Skill 要可组合一个 Skill 的输出可以作为另一个 Skill 的输入Skill 要可发现用户能方便地查看有哪些 Skill 可用Skill 要可调试执行过程要透明出错了能定位如果你在做企业内部的 Agent 平台可以参考这些设计但不要照搬。企业内部场景更强调权限控制、审计日志、稳定性这些是消费级工具不太考虑的。6.2 Skill 编码规范247 原则热词里有个skill 编码247我理解这是一种 Skill 编写的经验法则。结合我的实践我总结了一个类似的规范叫247 原则2 个必填skillName 和 description 必须写清楚这是路由的基础4 个建议triggerExamples、inputSchema、outputSchema、errorHandling 建议都提供7 分实现Skill 的实现逻辑不要超过 7 个步骤太复杂就拆成多个 Skill这个原则的核心思想是元信息优先。很多开发者把精力全放在实现逻辑上元信息随便写写结果 Skill 根本没法被正确调用。实际上元信息的质量比实现逻辑更影响整体效果。6.3 什么时候该用 Skill什么时候不该用不是所有能力都适合封装成 Skill。我的判断标准是适合封装成 Skill 的有明确输入输出、会被重复调用、需要参数校验、有错误处理需求的能力。比如查询订单发送通知生成报表。不适合封装成 Skill 的一次性的、高度依赖上下文的、纯对话式的交互。比如和用户闲聊解释一个概念。这些用普通 Prompt 处理就好硬套 Skill 反而增加复杂度。还有一个判断维度是调用频率。高频调用的能力值得封装成 Skill因为可以复用、可以优化、可以监控。低频的、一次性的操作直接写 Prompt 更划算。6.4 关于 LLM 网关与 Skill 系统的配合关键词里出现了llm 网关这是个值得单独说的点。在企业环境里LLM 调用通常要经过一个网关做鉴权、限流、计费、日志。Skill 系统和 LLM 网关的关系是Skill 执行过程中如果需要调 LLM比如做结果总结应该走网关而不是直连模型服务。这样做的好处是统一的治理。所有 LLM 调用都有日志、都有配额控制、都能追踪成本。我在项目里就是这么做的Skill 执行器注入一个LlmGatewayClient所有模型调用都通过它。后来做成本分析时能精确到每个 Skill 消耗了多少 token这对优化很有价值。6.5 一个真实的选型对比自研 vs 框架最后说说选型。做 Skill 系统你可以自研也可以用现成框架。我的建议是场景建议团队有 Agent 经验需求明确自研可控性最高快速验证需求还在探索用框架比如 LangChain4j、Spring AI企业级有合规和审计要求自研核心 框架辅助小团队资源有限优先用框架把精力放在业务上我自己是偏自研派但不是因为自研一定更好而是因为我们的需求比较特殊框架的抽象反而成了束缚。如果你刚开始做我建议先用框架跑通理解清楚 Skill 系统的本质再决定要不要自研。框架方面Java 生态里 Spring AI 和 LangChain4j 都值得看。Spring AI 的优势是和 Spring 生态无缝集成LangChain4j 的优势是抽象更灵活。选哪个取决于你的技术栈和团队习惯。我在实际项目里最大的体会是Skill 系统的价值不在于技术多先进而在于它强迫你把能力想清楚。写 Skill 元信息的过程其实就是梳理业务能力边界的过程。很多之前模糊的需求在写 Skill 描述的时候被迫想明白了。这个想清楚的价值往往比技术实现本身更大。