Ooder SuperAgent 实战指南：企业级AI能力分发与自动化协作框架

本文使用腾讯 codebuddy 作为工具，选择DeepSeek3.2, 作为编译测试环境。实际操作可以参见，博文视频。相关技术介绍和技术细节如下，可以作为手工编译搭建的环境的手册使用。

前言

ooder SuperAgent 是一套基于 MIT 协议的开源企业级 AI 能力分发与自动化协作框架。它通过创新的 Agent 架构和 SKILL 管理机制，为企业提供了从简单任务到复杂流程的全场景自动化解决方案。本文旨在为开发者提供一份详实的实战指南，帮助你快速上手、深入理解并高效利用这一强大框架。

第一章：项目概述与核心概念

1.1 什么是 SuperAgent？

SuperAgent 是 ooderAI 开源生态的核心组件，实现了基于场景化协作架构的数据流转系统。系统采用 P2P 网络架构和无状态技能分发机制，通过标准化协议实现服务发现、数据流转和协同工作，是企业级AI能力落地、分发与自动化协作的核心载体。

1.2 核心设计理念

• MCPAgent 分发网络：企业/第三方系统可将自有 MCPAgent 接入 AIServer，通过 SuperAgent 实现AI能力对外分发；个人用户拥有专属 MCPAgent，一站式整合个人AI工具链
• AI 能力标准化：定义统一AI能力接口规范，支持 1:n Capability 关联关系，实现AI能力的模块化、可复用设计
• 跨域自动化编排：通过 Skillflow 可视化工具，实现跨企业/个人 MCPAgent 的工作流灵活编排，打破系统与组织壁垒
• 安全可靠的设计：内置基于 RBAC 的精细化权限管理，支持单机、集群、私有化等多种部署方式，从架构层面保障系统安全与稳定

1.3 三层 Agent 架构

SuperAgent 采用分层解耦的三层 Agent 架构，实现高效的任务分发、协同与执行，各层职责清晰、可独立扩展：

1.4 核心协议体系

SuperAgent 定义了一套完整的标准化协议体系，保障各Agent节点、各组件之间的互联互通，是框架实现跨域协作的基础：

1.5 项目生态

SuperAgent 拥有完善的开源生态体系，核心组件分层设计、解耦集成，支持按需扩展与二次开发，核心组成包括：

• 核心引擎：agent-sdk（Agent 开发核心SDK，提供全量开发接口）、agent-skillcenter（技能中心，负责技能注册、管理与分发）
• 技能生态：trae-solo-standard（官方标准 Skills 实现，提供通用能力模板）、skills-a2ui（A2UI 图转代码专属技能服务）
• 工具链：ES6 模块系统（前端能力支撑）、VFS 虚拟文件系统工具、A2UI 可视化编排工具
• 测试环境：test-scenarios（场景化测试目录，覆盖核心业务场景的测试用例）
• 协议体系：protocol-release（完整的协议文档体系，含协议规范、实现示例、对接指南）

第二章：环境配置与快速启动

2.1 环境要求

在开始使用 SuperAgent 之前，请确保开发环境满足以下基础要求，版本不兼容可能导致编译或运行失败：

• Java: JDK 1.8 或更高版本（推荐 Oracle JDK 8 或 OpenJDK 8，与Spring Boot 2.7.0最佳兼容）
• 构建工具: Maven 3.6 或更高版本（需配置国内镜像，提升依赖下载速度）
• 框架: Spring Boot 2.7.0（框架核心基础，统一技术栈）
• 操作系统: Windows、Linux 或 macOS（本指南以 Windows 为例，Linux/macOS操作仅终端命令略有差异）

2.2 获取项目代码

通过 Git 克隆官方代码仓库，即可获取 SuperAgent 全量源码，操作命令如下：

# 使用 Git 克隆项目（首次获取）
git clone https://gitee.com/ooderCN/super-agent.git
cd super-agent

若已克隆项目，需及时更新到最新版本，避免使用旧版本存在的bug：

git pull origin master

2.3 项目结构概览

SuperAgent 采用模块化Maven项目结构，各模块解耦独立，可单独编译、运行和开发，核心目录结构如下：

super-agent/
├── agent-sdk/ # Agent SDK 核心实现，提供所有开发接口与基础能力
├── agent-skillcenter/ # 技能中心实现，技能注册、发现、调用的核心服务
├── skill-a/ # 技能A：信息检索专属技能，实现通用信息查询能力
├── skill-b/ # 技能B：数据提交专属技能，实现业务数据统一提交能力
├── skill-c/ # 技能C：路由代理技能，负责场景管理、命令路由与节点协调
├── skills-a2ui/ # A2UI 图转代码服务，可视化编排转可执行代码
├── trae-solo-standard/ # 标准 Skills 实现，官方提供的通用技能模板
├── docs/ # 项目详细文档，含架构设计、开发指南、部署手册
├── protocol-release/ # 协议文档，全量协议规范与对接示例
└── pom.xml # Maven 父项目配置，统一管理依赖版本、编译插件

2.4 编译与构建

在项目根目录执行以下 Maven 命令，可完成整个项目的清理与编译，跳过测试可提升首次编译速度：

# 清理历史编译文件并编译所有模块（跳过单元测试）
mvn clean compile -DskipTests

若编译成功，终端会输出 Reactor Summary 并提示 BUILD SUCCESS，示例如下：

[INFO] Reactor Summary:
[INFO] Super Agent Parent …………………………… SUCCESS [ 0.249 s]
[INFO] Ooder Agent SDK ……………………………… SUCCESS [ 13.140 s]
…
[INFO] BUILD SUCCESS

若编译失败，优先检查：JDK/Maven版本是否符合要求、网络是否通畅（依赖是否下载成功）、是否有端口/文件占用。

2.5 启动示例服务

SuperAgent 提供 skill-a、skill-b、skill-c 三个核心示例技能服务，需分别启动（各服务运行在独立端口），启动后自动加入P2P网络，实现协同工作。

启动技能A（信息检索服务）

# 进入 skill-a 模块目录
cd skill-a
# 启动 Spring Boot 应用（Maven 方式）
mvn spring-boot:run

技能A默认运行在 9013端口，启动成功后终端会输出以下日志，说明Agent注册成功：

Started SkillAApplication in 5.123 seconds
Agent ID: skill-a-001 registered successfully

启动技能B（数据提交服务）

打开新的终端窗口（不可关闭技能A的终端），进入项目根目录后启动技能B：

cd super-agent/skill-b
mvn spring-boot:run

技能B默认运行在 9012端口，启动成功后会输出类似技能A的注册成功日志。

启动技能C（路由代理/场景管理）

打开第三个终端窗口，进入项目根目录后启动技能C（核心协调服务，建议最后启动）：

cd super-agent/skill-c
mvn spring-boot:run

技能C默认运行在 9011端口，是整个示例网络的路由核心，负责场景管理、服务发现与命令路由。

2.6 验证服务状态

通过 curl 命令或 Postman 调用各服务的健康检查接口，可快速验证服务是否正常运行，接口为Spring Boot原生Actuator接口，无需额外开发。

# 测试技能A的健康检查
curl http://localhost:9013/actuator/health
# 测试技能B的健康检查
curl http://localhost:9012/actuator/health
# 测试技能C的健康检查
curl http://localhost:9011/actuator/health

若服务正常运行，所有请求均会返回以下JSON结果，状态为UP：

{"status":"UP"}

若返回连接失败，需检查服务是否真的启动成功、端口是否被占用、防火墙是否拦截端口。

2.7 服务发现测试

SuperAgent 基于P2P协议实现自动服务发现，通过技能C（路由代理）的服务发现接口，可查询指定场景下已注册的所有Agent/技能服务，验证P2P网络是否正常。

# 向技能C发送服务发现请求，查询TEST_SCENE_001场景下的所有服务
curl -X POST http://localhost:9011/api/v1/discovery \\
-H "Content-Type: application/json" \\
-d '{"sceneId":"TEST_SCENE_001"}'

预期返回结果：包含 skill-a、skill-b、skill-c 三个服务的详细信息，如Agent ID、服务地址、端口、技能类型、注册时间等。

2.8 技能调用测试

通过直接调用技能A的信息检索接口，验证技能的核心功能是否正常，测试AI能力的实际执行效果：

# 调用技能A的信息检索功能，传入测试查询参数
curl -X POST http://localhost:9013/api/v1/skill/invoke \\
-H "Content-Type: application/json" \\
-d '{"skillName":"information-retrieval-skill","params":{"query":"测试查询"}}'

若一切正常，终端会输出技能处理日志，同时返回查询结果的JSON数据，说明技能调用流程正常。

2.9 IDE 配置

SuperAgent 支持 VS Code、IntelliJ IDEA 等主流Java开发IDE，以下提供两款IDE的核心配置步骤，配置完成后可实现断点调试、热部署等功能。

VS Code 配置

{
"version": "0.2.0",
"configurations": [
{
"type": "java",
"name": "Skill A",
"request": "launch",
"mainClass": "net.ooder.examples.skilla.SkillAApplication",
"projectName": "skill-a"
},
{
"type": "java",
"name": "Skill B",
"request": "launch",
"mainClass": "net.ooder.examples.skillb.SkillBApplication",
"projectName": "skill-b"
},
{
"type": "java",
"name": "Skill C",
"request": "launch",
"mainClass": "net.ooder.examples.skillc.SkillCApplication",
"projectName": "skill-c"
}
]
}

IntelliJ IDEA 配置

2.10 常见问题与解决

在环境配置和快速启动过程中，易出现以下常见问题，提供针对性解决方法，快速定位并解决问题：

第三章：技能开发与集成

3.1 技能开发基础

在 SuperAgent 框架中，技能（Skill）是核心的功能单元，所有AI能力和业务功能均以技能的形式实现，是框架的最小可执行单元。 每个技能都是一个独立的Spring Boot应用，通过集成 Agent SDK 实现与SuperAgent P2P网络的对接，具备以下核心特性：

• 独立性：每个技能可独立开发、编译、部署和运行，互不影响，支持单独升级
• 可发现性：技能启动后自动向P2P网络广播注册信息，可被同场景下的其他技能/Agent自动发现
• 可调用性：遵循框架统一的协议接口，支持被其他技能/Agent通过标准化方式调用
• 无状态性：技能设计为无状态模式，不存储业务状态数据，支持水平扩展，可部署多个实例实现负载均衡

3.2 创建新技能项目

以创建名为 skill-demo 的示例技能为例，详细讲解新技能项目的完整创建流程，基于Maven模块化开发，无缝集成到SuperAgent现有生态中。

步骤1：创建项目结构

在 SuperAgent 项目根目录，创建 skill-demo 模块目录，并搭建标准的Maven项目目录结构，命令如下：

# 在项目根目录创建 skill-demo 模块目录
mkdir skill-demo
cd skill-demo
# 创建标准Maven项目的目录结构
mkdir -p src/main/java/net/ooder/examples/skilldemo
mkdir -p src/main/resources
mkdir -p src/test/java

步骤2：创建 pom.xml

在 skill-demo 模块根目录创建 pom.xml 文件，作为技能的Maven配置文件，继承父项目并引入核心依赖，实现与框架的无缝集成：

<?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
http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<!– 继承SuperAgent父项目，统一管理依赖版本和编译插件 –>
<parent>
<groupId>net.ooder</groupId>
<artifactId>super-agent-parent</artifactId>
<version>0.6.5</version>
<relativePath>../pom.xml</relativePath>
</parent>

<!– 本技能模块的基础配置 –>
<artifactId>skill-demo</artifactId>
<name>Skill Demo</name>
<description>示例技能项目，演示SuperAgent技能开发全流程</description>

<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>

<!– 核心依赖：Agent SDK + Spring Boot Web –>
<dependencies>
<!– Agent SDK 依赖：核心开发接口，必须引入 –>
<dependency>
<groupId>net.ooder</groupId>
<artifactId>agent-sdk</artifactId>
</dependency>
<!– Spring Boot Starter Web：实现HTTP接口，基础Web能力 –>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!– 测试依赖：单元测试，可选 –>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>

<!– 构建配置：Spring Boot 打包插件，支持一键启动 –>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>

步骤3：添加父模块引用

修改 SuperAgent 项目根目录的 pom.xml 文件，在 <modules> 标签中添加 skill-demo 模块，使父项目能识别并管理该技能模块，支持整项目编译：

<modules>
<!– 原有模块 –>
<module>agent-sdk</module>
<module>skill-a</module>
<module>skill-b</module>
<module>skill-c</module>
<!– 新增skill-demo模块 –>
<module>skill-demo</module>
</modules>

3.3 创建技能应用类

在 src/main/java/net/ooder/examples/skilldemo/ 目录下创建技能的启动应用类 SkillDemoApplication.java，作为技能的入口，实现Agent SDK的初始化、启动和注册，代码如下：

package net.ooder.examples.skilldemo;

import lombok.extern.slf4j.Slf4j;
import net.ooder.sdk.AgentConfig;
import net.ooder.sdk.AgentSDK;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;

/**
* Skill Demo 启动类，SuperAgent技能开发入口
* 实现CommandLineRunner，在项目启动后执行Agent SDK初始化
*/
@Slf4j
@SpringBootApplication
public class SkillDemoApplication implements CommandLineRunner {

// Agent SDK 核心实例，负责与P2P网络交互
private AgentSDK agentSDK;
// Agent 配置信息，从application.yml中加载
private AgentConfig agentConfig;

// 项目主启动方法
public static void main(String[] args) {
SpringApplication.run(SkillDemoApplication.class, args);
}

/**
* 配置Bean：加载application.yml中agent前缀的配置，注入AgentConfig
*/
@Bean
@ConfigurationProperties(prefix = "agent")
public AgentConfig agentConfig() {
return AgentConfig.builder().build();
}

/**
* 自动注入AgentConfig配置
*/
@Autowired
public void setAgentConfig(AgentConfig agentConfig) {
this.agentConfig = agentConfig;
}

/**
* 项目启动后执行：初始化并启动Agent SDK，注册到P2P网络
*/
@Override
public void run(String... args) throws Exception {
log.info("===== Skill Demo Application Starting =====");

// 初始化Agent SDK：传入配置信息
agentSDK = AgentSDK.builder().config(agentConfig).build();
// 启动Agent SDK：注册到P2P网络，开始接收网络命令
agentSDK.start();

// 启动成功，打印核心配置信息
log.info("===== Skill Demo started successfully =====");
log.info("Agent ID: {}", agentConfig.getAgentId());
log.info("Agent Type: {}", agentConfig.getAgentType());
log.info("Service Endpoint: {}", agentConfig.getEndpoint());
log.info("UDP Port: {}", agentConfig.getUdpPort());
}
}

3.4 配置技能参数

在 src/main/resources/ 目录下创建配置文件 application.yml，配置技能的服务端口、Agent信息、场景信息、日志等核心参数，所有配置均可根据实际需求调整，代码如下：

# Server 基础配置：服务端口、上下文路径
server:
port: 9014 # 技能demo专属端口，避免与其他技能冲突
servlet:
context-path: / # 根上下文路径

# Spring 基础配置：应用名称、JSON解析器
spring:
application:
name: skill–demo # 应用名称，服务发现时的标识
http:
converters:
preferred-json-mapper: fastjson # 使用fastjson作为JSON解析器，提升性能

# Agent 核心配置：必须与Agent SDK匹配，用于注册到P2P网络
agent:
agentId: skill–demo–001 # Agent唯一ID，全网唯一，建议按「技能名-序号」命名
agentName: SkillDemo # Agent名称，便于可视化管理
agentType: skill # Agent类型，固定为skill（技能类型）
endpoint: http://localhost:9014 # 服务访问地址，其他Agent调用的基础地址
udpPort: 9010 # UDP端口，用于P2P网络的服务发现与通信
heartbeatInterval: 30000 # 心跳间隔，单位ms，30s发送一次心跳，检测节点存活状态

# Skill 自定义配置：技能专属参数，可自定义前缀
skill:
demo:
name: SkillDemo
type: skill–demo
description: "示例技能，用于演示SuperAgent技能开发全流程"
version: "1.0.0"
discovery: # 服务发现配置，与P2P网络匹配
port: 5000
broadcast-address: 255.255.255.255 # 广播地址，用于服务发现
skill-name: SkillDemo
skill-type: skill–demo
skill-port: 9014
scene:
id: DEMO_SCENE_001 # 场景ID，仅同场景的Agent可相互发现和调用
security:
key: demo_security_key_2023 # 简易安全密钥，用于接口校验，生产环境建议使用复杂密钥

# Logging 日志配置：日志级别、输出格式
logging:
level:
root: INFO # 根日志级别
net.ooder.examples.skilldemo: DEBUG # 本技能包的日志级别，调试时设为DEBUG
pattern:
console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} – %msg%n" # 控制台日志格式

3.5 创建命令处理器

在 SuperAgent 框架中，命令处理器是处理网络命令和技能调用的核心，通过注解实现命令与处理器的绑定，支持参数自动校验。创建 src/main/java/net/ooder/examples/skilldemo/handler/DemoCommandHandler.java，实现技能的核心业务逻辑（问候、计算、信息查询），代码如下：

package net.ooder.examples.skilldemo.handler;

import lombok.extern.slf4j.Slf4j;
import net.ooder.sdk.enums.CommandType;
import net.ooder.sdk.handler.AbstractSkillCommandHandler;
import net.ooder.sdk.handler.CommandHandler;
import net.ooder.sdk.packet.CommandPacket;
import net.ooder.sdk.validation.ValidParam;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;

/**
* Skill Demo 命令处理器，处理P2P网络中的命令和技能调用
* 继承AbstractSkillCommandHandler，实现框架的标准命令处理规范
*/
@Slf4j
@Component
public class DemoCommandHandler extends AbstractSkillCommandHandler {

/**
* 处理技能调用命令（CommandType.SKILL_INVOKE）
* @ValidParam：参数自动校验，指定参数名、是否必传、类型、枚举值等
*/
@CommandHandler(CommandType.SKILL_INVOKE)
@ValidParam(name = "operation", required = true, type = String.class,
enumValues = {"greet", "calculate", "info"}) // 操作类型，仅支持指定枚举值
@ValidParam(name = "params", required = false, type = Map.class) // 业务参数，可选
public void handleSkillInvoke(CommandPacket packet) {
log.info("开始处理技能调用命令");

// 从命令包中获取调用参数
Map<String, Object> params = packet.getParams();
String operation = (String) params.get("operation");

// 打印调用信息，便于调试
log.info("操作类型: {}", operation);
log.info("业务参数: {}", params);

// 构造返回结果
Map<String, Object> result = new HashMap<>();

// 根据操作类型执行不同的业务逻辑
switch (operation) {
case "greet": // 问候功能
result.put("message", "你好！欢迎使用 SuperAgent 框架！");
result.put("timestamp", System.currentTimeMillis());
break;

case "calculate": // 计算功能：实现加减乘除
Integer a = (Integer) params.get("a");
Integer b = (Integer) params.get("b");
if (a != null && b != null) {
result.put("sum", a + b); // 加法
result.put("difference", a – b); // 减法
result.put("product", a * b); // 乘法
result.put("quotient", b != 0 ? a / b : "undefined"); // 除法，避免除零
} else {
result.put("error", "参数 a 和 b 必须提供且为整数");
}
break;

case "info": // 信息查询：返回技能自身信息
result.put("skillName", "SkillDemo");
result.put("version", "1.0.0");
result.put("description", "示例技能，用于演示SuperAgent技能开发流程");
result.put("endpoint", "http://localhost:9014");
break;

default: // 未知操作类型
result.put("error", "不支持的操作类型: " + operation);
}

log.info("技能调用处理完成，结果: {}", result);

// 实际应用中，通过packet的sendResponse方法将结果返回给请求方
// packet.sendResponse(result, CommandStatus.SUCCESS);
}

/**
* 处理技能状态查询命令（CommandType.SKILL_STATUS）
* 返回技能的当前运行状态，用于节点健康检测
*/
@CommandHandler(CommandType.SKILL_STATUS)
public void handleSkillStatus(CommandPacket packet) {
log.info("开始处理技能状态查询命令");

// 构造技能状态信息
Map<String, Object> status = new HashMap<>();
status.put("status", "running"); // 运行状态：running/stopped
status.put("uptime", System.currentTimeMillis()); // 启动时间戳
status.put("activeConnections", 1); // 活跃连接数，模拟值
status.put("memoryUsage", Runtime.getRuntime().totalMemory() –
Runtime.getRuntime().freeMemory()); // 内存使用量，字节

log.info("技能状态查询处理完成，状态: {}", status);
// 实际应用中，返回状态信息给请求方
// packet.sendResponse(status, CommandStatus.SUCCESS);
}
}

3.6 测试新技能

完成技能开发后，通过编译、启动、接口调用三步测试技能的核心功能，验证是否能正常运行并处理业务请求。

编译项目

在 SuperAgent 项目根目录执行编译命令，编译包括skill-demo在内的所有模块：

mvn clean compile -DskipTests

若编译成功，说明技能的代码和配置无语法错误，可正常启动。

启动技能

进入 skill-demo 模块目录，执行Maven启动命令，启动技能服务：

# 进入skill-demo目录
cd skill-demo
# 启动技能服务
mvn spring-boot:run

若启动成功，终端会输出技能启动日志，提示 Agent 注册成功，且无报错信息。

测试技能调用

通过 curl 命令调用技能的 /api/v1/skill/invoke 接口，分别测试问候、计算、信息查询三个核心功能，验证业务逻辑是否正常。

# 测试1：问候功能
curl -X POST http://localhost:9014/api/v1/skill/invoke \\
-H "Content-Type: application/json" \\
-d '{"skillName":"demo-skill","params":{"operation":"greet"}}'

# 测试2：计算功能（10+5、10-5、10*5、10/5）
curl -X POST http://localhost:9014/api/v1/skill/invoke \\
-H "Content-Type: application/json" \\
-d '{"skillName":"demo-skill","params":{"operation":"calculate","a":10,"b":5}}'

# 测试3：信息查询功能
curl -X POST http://localhost:9014/api/v1/skill/invoke \\
-H "Content-Type: application/json" \\
-d '{"skillName":"demo-skill","params":{"operation":"info"}}'

若测试成功，终端会输出对应的处理日志，接口会返回预期的JSON结果；若测试失败，根据终端报错信息定位问题（如参数错误、代码逻辑错误）。

3.7 技能集成到现有系统

开发完成的新技能，需集成到SuperAgent现有P2P网络中，实现与其他技能（skill-a/skill-b/skill-c）的协同工作，核心集成点为服务发现和技能调用，配置完成后即可实现无缝集成。

服务发现集成

确保新技能能被现有系统中的其他Agent自动发现，核心配置要求如下：

技能调用集成

新技能被发现后，可通过两种方式实现技能调用，适配不同的业务场景：

# 通过技能C（路由代理）调用skill-demo的问候功能，无需知道技能的直接地址
curl -X POST http://localhost:9011/api/v1/skill/invoke \\
-H "Content-Type: application/json" \\
-d '{"skillName":"demo-skill","params":{"operation":"greet"}}'

3.8 技能开发最佳实践

为提升技能的可维护性、可扩展性、性能和安全性，结合SuperAgent框架特性，总结以下技能开发最佳实践，适用于所有基于SuperAgent的技能开发。

代码结构建议

采用分层解耦的代码结构，遵循Spring Boot开发规范，将不同职责的代码分离，便于后续维护和扩展，推荐结构如下：

skill-xxx/
├── src/main/java/net/ooder/examples/xxx/
│ ├── config/ # 配置类：自定义配置、Bean注册、拦截器配置等
│ ├── controller/ # REST控制器：对外提供HTTP接口，接收前端/外部调用
│ ├── handler/ # 命令处理器：处理P2P网络中的Agent命令，框架核心
│ ├── model/ # 数据模型：实体类、DTO、VO、枚举等，统一数据结构
│ ├── service/ # 业务服务：核心业务逻辑实现，处理器/控制器调用此层
│ │ ├── impl/ # 业务服务实现类
│ │ └── XxxService.java # 业务服务接口
│ └── SkillXxxApplication.java # 启动类：项目入口
├── src/main/resources/
│ ├── application.yml # 核心配置文件：服务、Agent、场景等配置
│ ├── application-dev.yml # 开发环境配置：多环境隔离
│ ├── application-prod.yml # 生产环境配置：多环境隔离
│ └── logback.xml # 日志配置：自定义日志格式、输出路径、滚动策略
└── pom.xml # Maven配置：依赖、构建插件

性能优化建议

安全性建议

3.9 技能测试策略

为保障技能的功能正确性、稳定性和兼容性，需建立完善的测试体系，从单元测试、集成测试、端到端测试三个维度进行全面测试，覆盖技能的所有核心功能和异常场景。

单元测试

针对技能的最小功能单元（如业务服务方法、工具类、处理器方法）进行测试，独立于外部依赖（如数据库、其他Agent、网络），使用Mock工具（如Mockito）模拟外部依赖，确保单个功能单元的逻辑正确性。 示例单元测试代码（测试Agent SDK的初始化和启动）：

import net.ooder.sdk.AgentConfig;
import net.ooder.sdk.AgentSDK;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class SkillDemoTest {

// 待测试的Agent SDK实例
private AgentSDK agentSDK;

/**
* 测试前准备：初始化AgentConfig和AgentSDK
*/
@BeforeEach
void setUp() {
// 构建测试用的Agent配置
AgentConfig config = AgentConfig.builder()
.agentId("test-skill-demo-001")
.agentName("TestSkillDemo")
.agentType("skill")
.endpoint("http://localhost:9090")
.udpPort(9091)
.build();
// 初始化Agent SDK
agentSDK = AgentSDK.builder().config(config).build();
}

/**
* 测试Agent SDK的启动和运行状态
*/
@Test
void testAgentStart() throws Exception {
// 启动Agent SDK
agentSDK.start();
// 断言：Agent SDK启动后运行状态为true
assertTrue(agentSDK.isRunning());
// 停止Agent SDK
agentSDK.stop();
}
}

集成测试

针对技能与外部组件的集成点进行测试，验证技能与Agent SDK、其他Agent、数据库、Redis等组件的交互是否正常，覆盖技能的核心业务流程（如技能注册、服务发现、技能调用）。 集成测试核心测试点：

端到端测试

模拟真实的业务场景，从用户/外部系统的视角出发，测试整个SuperAgent系统的端到端流程，验证多技能协同工作的正确性，覆盖完整的业务链路。 端到端测试示例（信息检索+数据提交流程）：

3.10 技能发布与部署

技能开发并测试通过后，需发布并部署到生产环境，实现实际业务落地，SuperAgent支持传统部署、容器化部署、集群部署等多种部署方式，核心流程包括构建技能包、生产环境配置、部署上线、监控告警。

构建技能包

在技能模块目录执行以下Maven命令，可构建可执行的JAR包（技能包），包含技能的所有代码、依赖和配置，可直接通过Java命令启动：

# 清理历史构建文件，打包并跳过测试
mvn clean package -DskipTests

打包成功后，在技能模块的 target/ 目录下会生成 ${artifactId}-${version}.jar 格式的JAR包（如skill-demo-0.6.5.jar），该包为可执行包，无需额外配置依赖即可运行。

部署到生产环境

1. 环境配置

• 生产环境需单独配置 application-prod.yml，与开发环境隔离，修改核心配置：服务端口、Agent配置、场景ID、数据库/Redis连接信息、安全密钥等
• 生产环境建议关闭DEBUG日志，设置为INFO/WARN级别，减少日志输出，提升性能
• 生产环境需配置防火墙，仅开放必要的端口（HTTP端口、UDP端口），禁止外部非法访问

2. 容器化部署（推荐）

使用Docker实现技能的容器化部署，便于环境隔离、版本管理和快速扩缩容，核心步骤：

• 编写Dockerfile：基于OpenJDK 8镜像，添加技能JAR包，配置启动命令
• 构建Docker镜像：docker build -t skill-demo:1.0.0 .
• 运行Docker容器：docker run -d -p 9014:9014 –name skill-demo skill-demo:1.0.0
• （可选）使用Docker Compose/Kubernetes实现多技能的服务编排和集群部署

3. 传统部署

若不使用容器化，可直接在生产服务器上部署技能包，核心步骤：

• 将构建好的JAR包上传到生产服务器的指定目录
• 编写启动脚本（start.sh），配置JVM参数（如堆内存、元空间），实现后台启动
• 编写停止脚本（stop.sh），实现优雅停止
• 将启动脚本添加到系统服务（如systemd），实现开机自启

版本管理

监控告警

生产环境需配置完善的监控和告警机制，及时发现并处理技能服务的异常，保障系统稳定运行：