Skill源码框架入门指南：从零构建你的第一个技能插件

6次阅读

没有评论

共计 2133 个字符，预计需要花费 6 分钟才能阅读完成。

刚开始接触 Skill 框架时，很多开发者会遇到这些典型问题：

异步事件处理混乱 ：多个并发请求间的状态互相污染，比如用户快速发送多条指令时，回复内容错乱
上下文管理困难 ：传统方式用 Map 存储对话状态，难以维护跨会话的 Context/ 上下文
配置复杂度高 ：需要手动处理 NLU/NLP 模块对接，调试链路长

这些痛点正是 Skill 框架重点解决的。它通过统一的 Session 管理和事件总线机制，让开发者更专注于业务逻辑。

先看主要差异点：

协议层 ：
Skill 框架基于 HTTP/WebHook，适合私有化部署
BotSDK 依赖厂商协议（如钉钉机器人 API）
状态管理 ：
Skill 内置 Redis/Caffeine 多级缓存
BotSDK 通常需要自行实现会话存储
适用场景 ：
Skill 适合需要深度定制的企业级技能
BotSDK 更适合快速对接平台机器人

sequenceDiagram
    participant User
    participant SkillServer
    participant WeatherAPI
    User->>SkillServer: 查询北京天气
    SkillServer->>SkillServer: 解析 Intent(weather_query)
    SkillServer->>WeatherAPI: 调用第三方 API
    WeatherAPI-->>SkillServer: 返回气象数据
    SkillServer->>User: 组织自然语言回复

// Intent 识别处理器
@SkillIntent("weather_query")
public class WeatherHandler implements IntentHandler {
    @Override
    public SkillResponse execute(SkillRequest request) {
        // 1. 参数校验
        String city = request.getSlot("city");
        if (StringUtils.isEmpty(city)) {return SkillResponse.fail("请说出要查询的城市");
        }

        // 2. 调用天气 API（含异常处理）try {WeatherData data = weatherService.query(city);
            return SkillResponse.ok("${city} 当前温度 ${data.temp}℃");
        } catch (TimeoutException e) {
            // 符合阿里巴巴规约的异常处理
            log.error("查询超时", e);
            return SkillResponse.retryLater();}
    }
}

// Session 管理示例
@SessionScope
public class UserPreference {
    private String lastQueryCity;
    // getter/setter...
}

采用指数退避算法优化第三方 API 调用：

public class RetryTemplate {
    private static final int MAX_RETRIES = 3;

    public <T> T execute(RetryCallable<T> callable) {
        int retryCount = 0;
        do {
            try {return callable.call();
            } catch (Exception e) {long waitTime = (long) Math.pow(2, retryCount) * 1000;
                Thread.sleep(waitTime);
                retryCount++;
            }
        } while (retryCount < MAX_RETRIES);
        throw new SkillException("服务暂不可用");
    }
}

通过 Hook 机制实现内容安全：

@SkillHook(order = 1)
public class SecurityHook implements RequestHook {
    @Override
    public void beforeExecute(SkillRequest request) {if (SensitiveWordFilter.contains(request.getRawText())) {throw new SecurityException("包含违禁词汇");
        }
    }
}