Agent Skill系统实战：从Function Calling到SSE流式执行

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 编码247""codex skill""cursor 有哪些 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 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而不是tool1
• displayName：给用户看的中文名，比如"订单统计查询"
• description：一句话说清楚这个 Skill 能做什么，要包含典型使用场景
• triggerExamples：3-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、跑计算。如果等全部执行完再返回，用户会盯着空白屏幕等好几秒，体验很差。这时候 SSE（Server-Sent Events）就派上用场了。

SSE 的本质是服务器向客户端单向推送事件流。在 Skill 执行场景里，我们可以把执行过程拆成多个阶段，每个阶段完成就推一个事件给前端：

// 伪代码示意：Skill 执行过程中的 SSE 推送 public void executeSkill(String skillName, Map<String, 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 流，有几个选择：

• WebClient：Spring WebFlux 提供的响应式客户端，天然支持流式处理，bodyToFlux(String.class)就能拿到事件流。这是目前最推荐的方式。
• OkHttp 的 EventSource：如果你不想引入 WebFlux，OkHttp 的 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 被设计成单例 Bean（Spring 默认就是单例），而 Skill 内部又有成员变量来存执行状态，那并发调用时就会互相污染。我就遇到过 A 用户的查询参数被 B 用户的请求覆盖的情况，排查了好久才定位到。

解决办法很简单：Skill 必须是无状态的。所有执行状态都通过方法参数传入，通过返回值传出，不要用成员变量存状态。如果确实需要缓存一些东西，用ThreadLocal或者外部缓存，并且做好清理。这个原则和 Servlet 的设计原则是一样的，老 Java 程序员应该很熟悉。

5. 从零搭一个最小可用的 Skill 系统：Java 实现要点

5.1 核心组件划分

一个最小可用的 Skill 系统，至少需要这几个组件：

• Skill 接口：定义 Skill 的基本契约，包括元信息获取和执行方法
• SkillRegistry：注册中心，管理所有 Skill 的元信息和实例
• SkillRouter：路由器，根据用户输入选择合适的 Skill
• SkillExecutor：执行器，负责调用 Skill 并处理异常、超时、补偿
• SseEmitter 管理：负责向前端推送执行进度

这几个组件的职责要清晰，不要混在一起。我见过把路由和执行揉在一个类里的代码，后期维护极其痛苦。

5.2 Skill 接口设计

public interface Skill { // 元信息 SkillMeta getMeta(); // 执行 SkillResult execute(SkillContext context); // 是否支持流式输出 default boolean supportsStreaming() { return false; } }

SkillMeta包含前面说的那些元信息字段。SkillContext封装用户输入、会话信息、历史上下文等。SkillResult包含执行结果、状态码、错误信息。

这个接口设计的关键点是简单。不要一上来就设计得很复杂，什么拦截器、过滤器、中间件全加上。先把核心链路跑通，后面根据实际需求再扩展。

5.3 注册中心的实现

注册中心的核心是一个ConcurrentHashMap，key 是 skillName，value 是 Skill 实例。启动时扫描所有 Skill Bean，注册进去。同时维护一个向量索引，用于路由。

@Component public class SkillRegistry { private final Map<String, 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 List<Skill> route(String userInput, int topK) { List<String> candidates = vectorIndex.search(userInput, topK); return candidates.stream().map(skillMap::get).collect(Collectors.toList()); } }

向量索引可以用简单的余弦相似度实现，也可以接入专业的向量库。小规模场景（几十个 Skill）用内存计算完全够用，不需要上重型方案。

5.4 执行器的异常处理策略

执行器的核心职责是"让 Skill 执行变得可靠"。我总结了几个必须处理的场景：

这些策略不是拍脑袋定的，每一条都对应我实际遇到过的问题。比如"结果序列化失败"这条，是因为有一次 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 skill""cursor 有哪些 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 系统，你可以自研，也可以用现成框架。我的建议是：

我自己是偏自研派，但不是因为自研一定更好，而是因为我们的需求比较特殊，框架的抽象反而成了束缚。如果你刚开始做，我建议先用框架跑通，理解清楚 Skill 系统的本质，再决定要不要自研。

框架方面，Java 生态里 Spring AI 和 LangChain4j 都值得看。Spring AI 的优势是和 Spring 生态无缝集成，LangChain4j 的优势是抽象更灵活。选哪个取决于你的技术栈和团队习惯。

我在实际项目里最大的体会是：Skill 系统的价值不在于技术多先进，而在于它强迫你把"能力"想清楚。写 Skill 元信息的过程，其实就是梳理业务能力边界的过程。很多之前模糊的需求，在写 Skill 描述的时候被迫想明白了。这个"想清楚"的价值，往往比技术实现本身更大。