Hermes Skill 从零搭建到工程落地：注册、调度与运行全流程

把 Hermes Skill 落实到工程里这件事，很多同学第一步不是卡在写代码，而是卡在“不知道从哪里开始”。网上资料比较零散，有的只讲架构，有的只给一段代码，真正能照着从零搭建、跑通一个 Skill、再把它接进业务链路的完整教程并不多。这篇我就围绕 Hermes Skill 的搭建与运行，整理一套闭环实操流程，包含环境准备、工程结构、核心代码、运行验证、常见坑点和工程化建议。不管你是刚接触技能编排的新手，还是准备在项目里落地 Hermes Skill 的后端开发，都可以直接按这份笔记来操作。

1. Hermes Skill 到底是什么，解决什么问题

1.1 一句话理解 Hermes Skill

Hermes Skill 本质上是一个“可独立开发、可动态加载、可编排执行”的技能单元。你可以把一个 Skill 理解成一个函数，也可以理解成一个小服务，它接收一个请求，执行某种能力，然后返回结果。比如一个天气查询 Skill、一个工单创建 Skill、一个文本翻译 Skill，它们在业务里就是一个个独立模块，由统一调度方根据用户的意图去触发。

专业一点说，Hermes Skill 是一个基于任务语义封装的能力执行单元，它屏蔽了底层申请、鉴权、依赖调用等细节，向上提供统一接口，让上层业务只需要关心“要触发哪个技能”，而不需要关心“这个技能内部是怎么实现的”。

1.2 它解决的核心痛点

在没接入 Hermes Skill 之前，业务系统接入第三方能力或者多团队能力时，通常会遇到三个问题。

第一个问题是重复开发。比如 A 团队做了文本审核，B 团队也要用，但因为接口风格不同、鉴权方式不同、返回结构不同，B 团队只能重新对接一遍，很浪费时间。Hermes Skill 的思路是所有技能都遵守同一个执行协议，一次封装，处处调用。

第二个问题是逻辑耦合。没有统一调度层的时候，业务代码里会堆满各种 if-else 去判断当前该调用哪个能力。今天接一个语音识别，明天接一个图片识别，代码会越来越难维护。Hermes Skill 把技能调用抽象成注册和分发两层，业务侧不再直接耦合具体实现。

第三个问题是扩展成本高。新增一个技能往往要改主流程代码，风险很大。接入 Hermes Skill 后，新增技能只需要新增一个 Skill 实现类并完成注册，主流程代码不用动，这对需要快速迭代的团队来说非常重要。

1.3 典型应用场景

Hermes Skill 比较适合以下几类场景。

第一类是智能助手平台。用户输入一句话，意图识别模块解析出意图，然后调度层根据意图匹配对应的 Skill，Skill 去查天气、查快递、订会议室，最终把结果返回给用户。

第二类是流程自动化平台。比如工单系统里，触发高危操作时自动调用“安全审核 Skill”，审核通过后继续流转。Skill 作为流程中的一个执行节点，能够独立升级和回滚。

第三类是统一能力网关。企业内部有很多服务能力，接口风格各异，统一包成 Skill 后，对外暴露一套规范格式，降低接入成本。

第四类是 Agent 工具调用。在 AI Agent 场景下，大语言模型输出函数调用指令，系统根据指令选择一个 Skill 执行，比如“调用 createOrder Skill 创建订单”。Skill 是可被模型理解和调用的工具单元。

理解了这些问题和场景，再去看 Hermes Skill 的搭建和运行，思路会清晰很多。我们接下来直接把工程的骨架搭起来。

2. 环境准备与版本说明

在动手写代码之前，先把环境检查一遍，避免在编译阶段才暴露问题。下面这些环境信息以常见工程实践为准，具体版本要根据你本机的实际情况调整，核心思路比版本号更重要。

2.1 本机环境要求

• 操作系统：Windows 10/11、macOS、Linux 均可，本文示例基于 macOS 编写，命令通用。
• JDK：建议使用 JDK 17+，因为主流的 Spring Boot 3.x 版本底层需要 JDK 17。如果你的项目还在用 JDK 8，需要选择低版本的依赖。
• Maven：建议 Maven 3.6+。可以用独立安装的 Maven，也可以用 IDEA 自带的 Maven。
• IDE：IntelliJ IDEA 或 Eclipse 均可，本文演示使用 IntelliJ IDEA。
• HTTP 测试工具：Postman、Apifox，或者直接使用 IDEA 自带的 HTTP Client。

版本需要根据自己的项目实际情况调整。如果你本地已经装了 JDK 8，而且不想升级，可以继续使用 Spring Boot 2.7.x + Spring Cloud 2021.x 的版本组合，代码结构和思路是相通的。

2.2 技术栈选型

为了演示完整流程，这里使用 Spring Boot 作为基础框架。选它的原因是生态成熟、配置简单、资料多，新手和老手都容易快速上手。Hermes Skill 本身是一个可以嵌入任何 Java 工程的能力框架，所以即使你不是 Spring Boot 项目，只要按接口和注册机制做同样的事情，也能集成成功。

技术栈清单如下：

• 基础框架：Spring Boot 3.2.x
• 构建工具：Maven
• JDK：17
• 参数校验：spring-boot-starter-validation
• 配置管理：Spring 原生配置，演示环境不引入 Apollo 或 Nacos

2.3 示例工程整体目标

我们这篇笔记的实战目标是搭建一个 Hermes Skill 最小可用工程，包含以下功能：

• 定义统一的 Skill 接口，规定技能名称、技能描述、参数约束、执行方法。
• 实现两个示例 Skill，一个是字符串反转技能，一个是计算字符串长度技能。虽然业务上很简单，但足够说明技能的注册与调度机制。
• 通过一个统一调度接口，根据请求中的技能名称分发到具体 Skill 并执行。
• 增加技能查询接口，查看当前全部注册技能的信息。
• 编写启动类和测试接口，整体跑通。

用这两个简单的示例 Skill，能够把最核心的“搭建、注册、调度、运行”链路完全演示清楚。真正做业务开发时，你只需要替换 Skill 内部逻辑和参数结构即可。

3. 核心概念与设计拆解

3.1 Skill 接口设计

既然要统一封装技能，就需要给所有 Skill 定义一个共同接口。接口里需要包含以下信息。

技能力量注册信息：包括技能名 name 和技能描述 description，描述不仅给人看，也给 AI 模型看。在 Agent 场景下，模型会根据描述判断该调用哪个技能，所以描述要写得清晰、准确。

执行方法：所有技能都要有一个 execute 方法来接收参数并返回结果。为了通用性，参数用 Map 接收比较方便，因为不同技能需要的字段不同，把参数定义死反而限制扩展。返回值用 Object，由具体技能决定返回格式，在统一调度时再包装一层。

设计接口时还有两个细节值得注意。一是接口应该保持简洁，不要在里面塞太多通用方法，如果后面出现“技能需要回调”“技能需要取消”这类需求，可以拆成扩展接口，而不是在基础接口里写空实现。二是接口要面向返回值设计，尽量统一返回结构，这样调用方处理起来更友好。

3.2 技能注册中心

有了 Skill 接口，还要有一个地方记录“有哪些技能可用”。最简单的实现是利用 Spring 容器注入的特性：把所有实现 Skill 接口的 Bean 收集到一个 Map 中，key 为技能名称，value 为 Skill 实例。这样新增技能时不需要改注册中心代码，Spring 会自动把新的 Skill Bean 注入进来，十分方便。

这种“基于接口 + Spring Bean 收集”的注册方式好处很明显：新增技能不用动注册中心，不用改调度层，代码维护成本极低。这也是 Hermes Skill 规范化之后对工程改动最小的方案。如果你想做到“动态注册、不用重启”，那就需要把技能打到独立 Jar 包，利用 Java 的 ServiceLoader 机制或者自定义类加载器实现，那是进阶话题，本篇先用容器内注册的方式把原理讲清。

3.3 统一调度层

调度层是调用方和 Skill 之间的桥梁。调用方向调度层传一个请求，里面写明要调用哪个技能、参数是什么，调度层根据技能名找到对应 Skill，执行技能，包装结果返回。

调度层还需要承担一部分防御职责，比如技能不存在时返回明确的错误码，参数校验失败时返回参数错误提示。这样调用方接收到结果时，只需要根据响应结构里的 code 判断成功还是失败，不需要感知内部异常细节。

3.4 请求与响应结构设计

为了便于前后端联调以及未来接 Agent 场景，这里定义一个统一的请求接收对象和一个统一的响应对象。

请求对象字段包括 skillName（技能名称）和 params（Map 类型的参数集合）。响应对象字段包括 code（状态码）、message（状态描述）、data（业务数据）。code 为 200 时表示成功，其他值表示失败，我们约定 400 表示参数错误，404 表示技能不存在。这个结构很简单，但足够覆盖演示场景。

4. 完整实战：Hermes Skill 搭建与运行

下面进入正题。我们从一个空目录开始，一步一步搭建这个工程。为了不依赖我的本地路径，你可以直接创建自己的项目目录，建议命名 hermes-skill-demo。

4.1 创建项目结构

先创建如下目录结构：

code复制hermes-skill-demo
├── pom.xml
└── src
    └── main
        ├── java
        │   └── com
        │       └── example
        │           └── hermes
        │               ├── HermesApplication.java
        │               ├── config
        │               │   └── SkillRegistry.java
        │               ├── controller
        │               │   └── SkillController.java
        │               ├── model
        │               │   ├── SkillRequest.java
        │               │   ├── SkillResponse.java
        │               │   └── SkillInfo.java
        │               └── skill
        │                   ├── Skill.java
        │                   ├── ReverseSkill.java
        │                   └── LengthSkill.java
        └── resources
            └── application.yml

这个结构把不同职责的代码分到不同包下，controller 负责 HTTP 接入，skill 负责技能实现，config 负责注册装配，model 负责数据模型。分包本身就是一种可维护性，项目大了以后不至于混乱。

4.2 配置 Maven 依赖

在 pom.xml 里加入 Spring Boot 基础依赖，以及参数校验相关依赖。

xml复制<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>hermes-skill-demo</artifactId>
    <version>1.0.0</version>
    <name>hermes-skill-demo</name>
    <description>Hermes Skill 搭建与运行示例</description>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

这里用 spring-boot-starter-parent 统一管理版本号，不需要手动指定 Spring 框架版本。如果你在公司的私服环境，需要额外配置私服地址，这个根据公司实际情况来。

4.3 编写启动类与配置文件

新建启动类 HermesApplication.java，这个类的作用是启动 Spring Boot 应用。

java复制package com.example.hermes;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class HermesApplication {

    public static void main(String[] args) {
        SpringApplication.run(HermesApplication.class, args);
    }
}

配置文件 application.yml 里面放最基础的服务端口和应用名。实际项目中还需要配置数据库、Redis、注册中心等，这里保持简洁，只做最小可运行配置。

yaml复制server:
  port: 8080

spring:
  application:
    name: hermes-skill-demo

需要说明的是，这样配置后应用默认启动在 8080 端口。如果你本机 8080 被占用，可以改成 8081 或其他空闲端口，启动时注意看控制台输出。

4.4 定义数据模型

请求和响应结构是调用方最关心的内容。先建 SkillRequest.java：

java复制package com.example.hermes.model;

import jakarta.validation.constraints.NotBlank;
import java.util.Map;

public class SkillRequest {

    @NotBlank(message = "skillName 不能为空")
    private String skillName;

    private Map<String, Object> params;

    public String getSkillName() {
        return skillName;
    }

    public void setSkillName(String skillName) {
        this.skillName = skillName;
    }

    public Map<String, Object> getParams() {
        return params;
    }

    public void setParams(Map<String, Object> params) {
        this.params = params;
    }
}

接着建 SkillResponse.java：

java复制package com.example.hermes.model;

public class SkillResponse<T> {

    private int code;
    private String message;
    private T data;

    public SkillResponse() {
    }

    public SkillResponse(int code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    public static <T> SkillResponse<T> success(T data) {
        return new SkillResponse<>(200, "success", data);
    }

    public static <T> SkillResponse<T> error(int code, String message) {
        return new SkillResponse<>(code, message, null);
    }

    public int getCode() {
        return code;
    }

    public void setCode(int code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }
}

最后建 SkillInfo.java，它主要用于技能查询接口的返回，包含技能名称和技能描述：

java复制package com.example.hermes.model;

public class SkillInfo {

    private String name;
    private String description;

    public SkillInfo(String name, String description) {
        this.name = name;
        this.description = description;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }
}

4.5 定义 Skill 接口

Skill 接口是整个 Hermes Skill 架构的核心，所有技能类必须实现这个接口。

java复制package com.example.hermes.skill;

import java.util.Map;

public interface Skill {

    String getName();

    String getDescription();

    Object execute(Map<String, Object> params);
}

接口里的方法职责如下：

• getName：返回技能名称，这是调度和注册的唯一标识。命名时建议使用LowerCase驼峰，比如 reverseString、calcLength，方便 HTTP 请求传参，也方便日志阅读。
• getDescription：返回技能描述，用于技能列表展示、调试和后续 Agent 场景下的意图匹配。
• execute：技能核心逻辑，接收参数后执行，并把结果返回。

这里有个容易忽略的点：execute 方法故意使用 Map 而不是定义成具体参数类，是因为不同技能输入千差万别，用 Map 最灵活。但灵活也意味着约束少，所以每个 Skill 的实现内部必须自己校验参数是否存在、类型是否正确，防止执行时出现 ClassCastException。

4.6 实现两个示例 Skill

先实现字符串反转技能 ReverseSkill。这个技能接收一个 text 参数，返回反转后的字符串。

java复制package com.example.hermes.skill;

import org.springframework.stereotype.Component;

import java.util.Map;

@Component
public class ReverseSkill implements Skill {

    @Override
    public String getName() {
        return "reverseString";
    }

    @Override
    public String getDescription() {
        return "反转输入的字符串, 参数: text(字符串)";
    }

    @Override
    public Object execute(Map<String, Object> params) {
        Object textObj = params.get("text");
        if (textObj == null) {
            throw new IllegalArgumentException("缺少参数: text");
        }
        String text = String.valueOf(textObj);
        StringBuilder reversed = new StringBuilder(text).reverse();
        return reversed.toString();
    }
}

再实现计算字符串长度技能 LengthSkill，接收 text 参数，返回字符串长度。

java复制package com.example.hermes.skill;

import org.springframework.stereotype.Component;

import java.util.Map;

@Component
public class LengthSkill implements Skill {

    @Override
    public String getName() {
        return "calcLength";
    }

    @Override
    public String getDescription() {
        return "计算字符串长度, 参数: text(字符串)";
    }

    @Override
    public Object execute(Map<String, Object> params) {
        Object textObj = params.get("text");
        if (textObj == null) {
            throw new IllegalArgumentException("缺少参数: text");
        }
        String text = String.valueOf(textObj);
        return text.length();
    }
}

这两个技能都交给 Spring 托管，通过 @Component 注解注册为 Bean。这就是我们前面说的扩展方式：以后加一个技能，只需要创建一个实现类，标注 @Component，注册中心就会自动收集到它，主流程代码一行不用改。

这里特别说明一个容易踩坑的地方：既然参数是 Map，到底要不要强校验参数类型。建议不要只做 “非空校验”，还要做类型封装判断。比如调用方传了个整数 123，String.valueOf 会得到 "123"，这没问题。但如果传了一个对象，String.valueOf 就会得到对象的 toString，不一定是预期效果，所以商品级代码里最好在 Skill 内部做一次 instanceof 校验。

4.7 实现技能注册中心

注册中心的职责是把 Spring 管理的所有 Skill Bean 收集到一个 Map 里，并提供按名称获取的方法。在 Spring Boot 中实现思路并不复杂。

java复制package com.example.hermes.config;

import com.example.hermes.skill.Skill;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;

import java.util.Collection;
import java.util.LinkedHashMap;
import java.util.Map;

@Component
public class SkillRegistry {

    private final Map<String, Skill> skillMap = new LinkedHashMap<>();

    public SkillRegistry(ApplicationContext applicationContext) {
        Collection<Skill> skills = applicationContext.getBeansOfType(Skill.class).values();
        for (Skill skill : skills) {
            skillMap.put(skill.getName(), skill);
        }
    }

    public Skill getSkill(String name) {
        return skillMap.get(name);
    }

    public boolean containsSkill(String name) {
        return skillMap.containsKey(name);
    }

    public Collection<Skill> getAllSkills() {
        return skillMap.values();
    }
}

使用 ApplicationContext 初始化时，Spring 会将所有注册到容器里的 Skill 实现类都拉出来，然后放到 Map 中。

这里使用 LinkedHashMap 作为容器，目的是保持技能按注册顺序排列，这样在查询技能列表时输出顺序稳定，利于测试和维护。如果你对顺序没有要求，使用 HashMap 也可以。

有一点必须指出，ApplicationContext 在构造器执行时可能还没有完成全部 Bean 的创建，但 getBeansOfType 的调用时机是在容器刷新过程中，实际能获取到所有已完成注册的 Skill Bean，所以这种方式在常规 Spring 工程里是可用的。如果你在扩展开发时遇到循环依赖问题，可以再考虑把初始化时机放到 InitializingBean 或 ApplicationListener 阶段。

4.8 实现统一调度控制器

控制器对外暴露两个接口：

• GET /skill/info：查询当前系统所有可用的技能。
• POST /skill/execute：执行指定技能。

完整代码如下：

java复制package com.example.hermes.controller;

import com.example.hermes.config.SkillRegistry;
import com.example.hermes.model.SkillInfo;
import com.example.hermes.model.SkillRequest;
import com.example.hermes.model.SkillResponse;
import com.example.hermes.skill.Skill;
import jakarta.validation.Valid;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;
import java.util.stream.Collectors;

@RestController
@RequestMapping("/skill")
public class SkillController {

    private final SkillRegistry skillRegistry;

    public SkillController(SkillRegistry skillRegistry) {
        this.skillRegistry = skillRegistry;
    }

    @GetMapping("/info")
    public SkillResponse<List<SkillInfo>> getSkillInfo() {
        List<SkillInfo> skillInfos = skillRegistry.getAllSkills()
                .stream()
                .map(skill -> new SkillInfo(skill.getName(), skill.getDescription()))
                .collect(Collectors.toList());
        return SkillResponse.success(skillInfos);
    }

    @PostMapping("/execute")
    public SkillResponse<Object> executeSkill(@Valid @RequestBody SkillRequest request) {
        String skillName = request.getSkillName();
        if (!skillRegistry.containsSkill(skillName)) {
            return SkillResponse.error(404, "技能不存在: " + skillName);
        }
        Skill skill = skillRegistry.getSkill(skillName);
        try {
            Object result = skill.execute(request.getParams());
            return SkillResponse.success(result);
        } catch (IllegalArgumentException ex) {
            return SkillResponse.error(400, "参数错误: " + ex.getMessage());
        } catch (Exception ex) {
            return SkillResponse.error(500, "技能执行异常: " + ex.getMessage());
        }
    }
}

执行接口是核心链路，这里做了一个细致的异常拆分。参数异常返回 400，业务异常返回 500。不建议在 Controller 里把所有异常都吞掉不区分，因为调用方只有拿到明确码才能做出准确的后续处理，比如参数错了重传参数，技能内部错误则走告警链路。

4.9 运行与验证

在 IDEA 中运行 HermesApplication 的 main 方法，控制台输出类似下面内容表示启动成功：

code复制Tomcat started on port(s): 8080 (http)
Started HermesApplication in x.xx seconds

先用 C 的 curl 命令查询技能列表：

bash复制curl -X GET http://localhost:8080/skill/info

预期返回：

json复制{
    "code": 200,
    "message": "success",
    "data": [
        {
            "name": "reverseString",
            "description": "反转输入的字符串, 参数: text(字符串)"
        },
        {
            "name": "calcLength",
            "description": "计算字符串长度, 参数: text(字符串)"
        }
    ]
}

然后执行反转技能：

bash复制curl -X POST http://localhost:8080/skill/execute \
    -H "Content-Type: application/json" \
    -d '{"skillName": "reverseString", "params": {"text": "hello hermes"}}'

预期返回：

json复制{
    "code": 200,
    "message": "success",
    "data": "semreh olleh"
}

再执行一个不存在的技能，验证错误码：

bash复制curl -X POST http://localhost:8080/skill/execute \
    -H "Content-Type: application/json" \
    -d '{"skillName": "notExist", "params": {}}'

预期返回：

json复制{
    "code": 404,
    "message": "技能不存在: notExist",
    "data": null
}

这三个请求分别验证了技能查询、技能成功执行、技能不存在兜底，链路是通的。

如果你使用 Postman 或 Apifox，直接把上面的 URL 和 JSON 填进去就可以，不需要额外安装其他依赖。

5. 常见问题与排查思路

5.1 启动报错：端口被占用

错误现象是启动打印 Web server failed to start. Port 8080 was already in use.。原因是本机 8080 端口已经被其他进程占用。

排查步骤：打开终端，执行 lsof -i :8080 查看占用进程 PID，然后确认该进程是否可以结束。如果只是临时测试，直接改端口更安全。

解决方案：修改 application.yml 里的端口为 8081，或者结束占用进程。

5.2 技能执行时报 ClassCastException

错误现象是技能内转型失败，比如把参数当成 String 强转时崩溃。原因通常是调用方传参时类型传错了，比如传了数组或对象。

排查步骤：在 Skill 实现类里打断点，查看 params 里的真实类型。

解决方案：不要直接强转，使用 String.valueOf 处理简单场景；严谨场景下先做 instanceof 判断，再执行转换。

5.3 技能注册不上，查询列表为空

错误现象是 GET /skill/info 返回空 data。原因是 Skill 实现类没有标注 @Component 注解，或者类没有放在主启动类能扫描到的包路径下。如果类是 public class，但包路径写错了，Spring 扫不到自然不会注册。

排查步骤：确认实现类是否被 @Component 修饰，确认实现类包路径是否在 com.example.hermes 包下面。

解决方案：给实现类补上组件注解，或调整包扫描范围，用 @ComponentScan 指定扫描路径。

5.4 请求参数校验失效

错误现象是技能名为空时，接口没有返回 400 错误。原因是 Controller 方法参数前面没有加 @Valid 注解，或者没有引入 spring-boot-starter-validation 依赖。

解决方案：检查 pom.xml 是否含有 validator 依赖，检查接口参数前是否有 @Valid。

5.5 中文乱码

错误现象是返回给调用方时中文乱码。原因可能是 HTTP 响应没有正确设置字符编码，或者数据库、控制台字符集不统一。

解决方案：Spring Boot 默认 UTF-8 基本不会出现乱码。如果控制台乱码，可以检查 IDEA 编码设置为 UTF-8，以及确保请求时 Content-Type 中有 charset=UTF-8。多数情况下是 IDE 控制台编码问题，而不是代码问题。

5.6 启动后技能执行非常慢

错误现象是技能执行耗时过长。原因可能是技能内部调用了外部服务，外部服务响应慢，或者技能参数校验不充分导致走入了耗时分支。排查思路是先看一下是整体慢还是单个技能慢，单个技能慢就去技能内部打日志，统计耗时。整体慢则要看注册流程是否在启动期间产生了阻塞，比如 Skill 构造函数里有网络调用。

解决方案：不要在 Skill 构造函数里做耗时初始化，延迟到位或使用缓存。

6. 最佳实践与工程化建议

6.1 命名与接口规范

技能名称要全局唯一，在团队内制定统一命名格式。推荐格式是动词 + 名词的驼峰风格，例如 createOrder、queryUser、sendMessage。描述字段建议写清楚参数说明，不要只写一句“这是一个技能”。对于 AI Agent 场景来说，描述是模型判断是否调用的重要依据，写得越具体，调用准确率越高。

6.2 参数校验与异常处理

在 Skill 内部不要假设调用方一定会传合法参数。建议每个 Skill 执行前都做一层基础校验，包括必填字段检查、类型检查、长度范围检查。Controller 层的异常处理要区分参数异常、技能不存在、技能内部异常几类，不要一刀切返回 500。这样调用方可以通过错误码快速定位问题，是参数问题还是技能本身问题。

6.3 日志记录

Skill 执行过程一定要打日志，至少记录技能名称、入参、出参、耗时。注意入参可能包含敏感信息时要做脱敏处理，可以在日志工具类里加一个敏感字段过滤逻辑。生产上建议使用结构化日志，配合日志平台做检索和监控。日志里不要打印超长文本，比如入参是一个大文本，可以截断前 500 字符再输出。

6.4 安全边界

Skill 本质上是一个远程执行入口，如果开放到公网，存在被恶意调用的风险。安全上至少做三件事：

• 认证：接入方需要携带 token 或签名，服务端验签。
• 授权：控制哪些调用方可以执行哪些技能。
• 限流：对技能执行接口做限流，避免单个调用方过量请求打垮服务。

如果是内部服务调用，可以放在内网并通过网关统一认证；如果必须对公网暴露，建议不要把技能执行接口直接裸奔到公网，而是要放在 API 网关后面。

6.5 性能与资源控制

如果一个技能是耗时任务，比如文件处理或外部服务同步调用，建议把超时时间控制起来。执行接口同步阻塞太久会导致 HTTP 线程被占满，影响整个应用吞吐量。工程上可以考虑异步技能模式，即提交任务后立刻返回任务 ID，技能在线程池中执行，调用方再用任务 ID 轮询结果或通过回调通知结果。

此外，技能内部如果要调用外部服务，要设置连接超时和读取超时，避免因为外部服务不响应导致自身线程长时间卡死。

6.6 可维护性与扩展方向

当技能数量超过几十个后，建议把技能按业务域拆成多个模块，每个模块一个 Maven 依赖，而不是把所有 Skill 类都堆在一个应用里。更进一步的方案是做成动态加载的 Jar 包，业务团队独立维护自己的技能包，核心平台通过类加载器加载技能。这种方案复杂度高一些，但非常适合中大型团队分工协作。

在注册中心设计上，如果技能规模大，可以把注册信息元数据（名称、描述、参数 Schema）提升到配置中心或注册中心，方便运营平台展示和管理。当前示例使用 Spring 容器扫描注册，适合中小规模项目；到需要热更新技能时再引入动态类加载机制也不迟。

6.7 测试建议

每个 Skill 都应该有对应的单元测试，覆盖正常参数、缺少参数、错误类型、空值等场景。Mock 外部依赖，保证测试不依赖真实网络。另外还要对 Controller 层做集成测试，验证技能注册链路和调度链路是否完整。Spring Boot 提供了 spring-boot-starter-test，直接写测试类即可。

7. 总结与下一步学习路线

至此，Hermes Skill 的完整搭建与运行流程就梳理完了。我们从问题场景出发，解释了 Hermes Skill 在能力统一、解耦和扩展上的价值；然后搭建了一个 Spring Boot 工程，定义了 Skill 统一接口，实现了两个真实技能，并通过注册中心和调度控制器把整条链路跑通。期间还演示了查询技能列表、执行技能、错误码兜底这几个关键接口，同时也给出了高频问题的排查思路和工程化建议。

这一套代码虽然业务逻辑非常简单，但它把 Hermes Skill 的核心骨架完整体现了出来。你能看到的接口、注册、调度、异常处理、统一响应，就是中小项目中落地 Skill 机制最需要优先考虑的部分。你可以在后续学习中对工程做以下几个方向的扩展：

• 支持技能分组和标签，让技能列表查询更细致。
• 加入参数 Schema 定义，用 JSON Schema 或自定义注解描述每个技能的入参，支持自动校验。
• 接入配置中心，让技能的开关、限流阈值、路由规则从配置中心动态下发。
• 引入动态类加载技术，让新技能上线不必重启应用。
• 实现技能执行链，允许一个 Skill 编排多个子技能，支持流程复用。

如果你的目标是接入 AI Agent 场景，下一步可以把 Hermes Skill 的注册信息整合成 function calling 的 tools 描述，然后根据模型输出的函数名自动路由到对应技能，这会是一个非常自然的结合点。

实际项目中，我建议你先小范围试点，比如先封装两到三个真正业务会用到的技能，把注册、调度、日志、权限这一套跑通，再逐步扩大覆盖面。早期打通一条路径，比前期设计一个大而全的框架要靠谱得多。如果这篇文章对你搭建 Hermes Skill 有帮助，可以收藏备用，后续扩展时回来对照着改。