From ca10dbb879e4274b3ffb66053f617b7a178fc948 Mon Sep 17 00:00:00 2001 From: V-LiuShuang Date: Mon, 17 Aug 2026 15:33:03 +0800 Subject: [PATCH] add --- mis-agent-spec/SKILL.md | 523 +++++++++++++++++++- mis-agent-spec/references/arch.md | 17 - mis-agent-spec/references/coding-rules.md | 243 --------- mis-agent-spec/references/directory-tree.md | 149 ------ mis-agent-spec/references/mvn.md | 17 - mis-agent-spec/references/nacos.md | 48 -- 6 files changed, 509 insertions(+), 488 deletions(-) delete mode 100644 mis-agent-spec/references/arch.md delete mode 100644 mis-agent-spec/references/coding-rules.md delete mode 100644 mis-agent-spec/references/directory-tree.md delete mode 100644 mis-agent-spec/references/mvn.md diff --git a/mis-agent-spec/SKILL.md b/mis-agent-spec/SKILL.md index 91fb15f..681661f 100644 --- a/mis-agent-spec/SKILL.md +++ b/mis-agent-spec/SKILL.md @@ -3,21 +3,516 @@ name: mis-agent-spec description: 在mis-agent模块编写代码必备技能。 --- -# 参考资料 +# Intro -- [目录结构](./references/directory-tree.md) -- [核心技术栈](./references/arch.md) -- [代码书写规范](./references/coding-rules.md) -- [HTTP接口文档示例](./examples/api-doc.md) - -## 约定 - -- 请结合**目录结构**与**核心技术栈**，并严格遵守**代码书写规范**修改、编写代码，被要求编写HTTP接口文档时，请参考**HTTP接口文档示例**。 -- 当前项目具有3个环境（dev/qas/prod）若没有指定**环境**则默认使用**qas**，不可以访问**prod**环境任何数据，包括但不限于数据库、HTTP接口。 -- 从**根目录**下的**pom.xml**文件``标签里可得到不同环境下的`nacos`以及`NewAPI`连接信息。 +请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈)，并严格遵守[代码编写规范](#代码编写规范)修改、编写代码，被要求编写HTTP接口文档时，请参考[HTTP接口文档示例](./examples/api-doc.md)。 ## FAQ -- Q：如何确认改用哪个profile？A：若当前分支出于dev则使用dev，否则使用qas。 -- Q：如何读取nacos配置？A：参考[nacos.md](./references/nacos.md)。 -- Q：如何打包？A：参考[mvn.md](./references/mvn.md) \ No newline at end of file +### 怎么确认用哪个profile？ + +若当前Git分支出于dev则使用dev，否则使用qas。 + +### 怎么读profile的配置？ + +从[项目根目录](#项目根目录)的`pom.xml`文件中获取不同`profiles.active`的配置，示例： + +```xml + +dev + +127.0.0.1:8868 + +DEFAULT_GROUP + +DEFAULT_GROUP + +nacos + +1234567890 + +http://127.0.0.1:3000 + +sk-xxx +``` + +### 怎么打包？ + +系统已安装`mvnd`用来替换`mvn`命令，在[项目根目录](#项目根目录)执行如下命令即可，**耗时约80秒**。 + +```bash +mvnd clean package -DskipTests -P{profiles.active} +``` + +### 怎么读取nacos配置文件？ + +按步骤一步步执行： + +1. 根据当前Git分支确认使用哪个profile，从**项目根目录**的`pom.xml`获取以下几个属性： + +- `profiles.active` +- `nacos.server` +- `nacos.config.group` +- `nacos.username` +- `nacos.password` + +2. 获取accessToken。 + +请求示例： +```bash +curl -X POST 'http://{nacos.server}/nacos/v1/auth/login' -d 'username={nacos.username}&password={nacos.password}' +``` + +输出示例： +```json +{"accessToken":"xxx"} +``` + +如果输出不包含accessToken字段视为失败，最多重试2次，仍然失败则直接中断整个流程。 + +3. 获取配置文件信息。 + +- `dataId`：取决于要访问的配置，如果是请求MySQL执行SQL使用`datasource.yml`，否则使用`mis-agent.yml`。 +- `accessToken`：来自上一步得到的`accessToken`。 + +请求示例： + +```bash +curl -X GET "http://{nacos.server}/nacos/v3/console/cs/config?dataId={dataId}&groupName={groupName}&namespaceId={profiles.active}" -H "Authorization: Bearer {accessToken}" +``` + +输出示例： + +```json +{ + "code": 0, + "message": "success", + "data": {"content": "..."} +} +``` + +`data.content`就是配置内容，通常是yaml格式。 + +## 核心技术栈 + +- Java：OpenJDK21 +- spring-boot： + - 版本：3.2.9 + - 文档：https://docs.spring.io/spring-boot/docs/3.2.9/reference/html + - 源码：https://github.com/spring-projects/spring-boot/tree/v3.2.9 +- spring-framework： + - 版本：6.1.12 + - 文档：https://docs.spring.io/spring-framework/reference/6.2/index.html + - 源码：https://github.com/spring-projects/spring-framework/tree/v6.1.12 +- mybatis-plus： + - 版本：3.5.7 + - 文档：https://github.com/baomidou/mybatis-plus-doc + - 源码：https://github.com/baomidou/mybatis-plus/tree/v3.5.7 +- MySQL： + - 版本：8.0.25 + - 文档：https://dev.mysql.com/doc/refman/8.0/en/ + - 源码：https://github.com/mysql/mysql-server/tree/mysql-8.0.25 +- Redis：8.0+ +- redisson-spring-boot-starter： + - 版本：3.34.1 + - 文档：https://redisson.pro/docs/integration-with-spring/#usage + - 源码：https://github.com/redisson/redisson/tree/redisson-3.34.1/redisson-spring-boot-starter/src/main +- rocketmq-client： + - 版本：4.9.8 + - 源码：https://github.com/apache/rocketmq/tree/rocketmq-all-4.9.8 +- rocketmq-spring-boot-starter： + - 版本：2.2.3 + - 文档：https://rocketmq.apache.org/zh/docs/4.x + - 源码：https://github.com/apache/rocketmq-spring/tree/rocketmq-spring-all-2.2.3 +- agentscope-java： + - 版本：1.0.11 + - 文档：https://java.agentscope.io/v1/zh/docs/task/agent-as-tool.html + - 源码：https://github.com/agentscope-ai/agentscope-java/tree/v1.0.11 +- spring-ai： + - 版本：1.1.2 + - 文档：https://docs.spring.io/spring-ai/reference/1.1/index.html + - 源码：https://github.com/spring-projects/spring-ai/tree/v1.1.2 +- spring-ai-alibaba： + - 版本：1.1.2.2 + - 文档：https://java2ai.com/docs/overview + - 源码：https://github.com/alibaba/spring-ai-alibaba/tree/v1.1.2.2 +- hutool-core： + - 版本：5.8.42 + - 文档：https://github.com/chinabugotech/hutool-site/tree/master/docs/core + - 源码：https://github.com/chinabugotech/hutool/tree/5.8.42/hutool-core +- hutool-json： + - 版本：5.8.42 + - 文档：https://github.com/chinabugotech/hutool-site/tree/master/docs/json + - 源码：https://github.com/chinabugotech/hutool/tree/5.8.42/hutool-json +- spring-cloud-alibaba： + - 版本：2023.0.1.2 + - 文档：https://sca.aliyun.com/docs/2023/overview/version-explain + - 源码：https://github.com/alibaba/spring-cloud-alibaba/tree/2023.0.1.2 + +## 目录结构 + +### 项目根目录 + +```text +\ +├── mis-api\ +├── mis-auth\ +├── mis-common\ +├── mis-gateway\ +├── mis-modules\ # 存放业务模块代码的主目录 +├── mis-visual\ +└── pom.xml # 在中定义了Nacos地址及账号密码、NewAPI的地址和密钥 +``` + +### mis-agent模块主目录 + +```text +mis-modules\mis-agent\src\main\ +├── java # Java源文件 +└── resources + └── mapper # Mybatis Mapper XML + └── application.yml # 配置文件 +``` + +#### 单智能体与多智能体 + +```text +com\lcfc\agent\agents\ +├── a2a # a2a agent +├── config # Spring配置类 +├── constants # 常量类 +├── context # 自定义的上下文载体类 +├── controller # SpringWeb控制器 +├── dubbo # Dubbo接口实现类 +├── enums # 枚举类 +├── events # Spring事件消息 +├── mapper # Mybatis Mapper 接口 +├── multiagent # 多智能体 +├── saa # 单智能体 +├── service # Server接口 +│ └── impl # Server接口实现类 +├── util # 工具类 +├── validator # 验证器 +├── domain # 数据库实体类 + ├── DTO # DTO + └── VO # VO +``` + +#### 事件发布订阅 + +摆脱对`ApplicationEventPublisher`的依赖，**在非springbean对象中简单的使用发布订阅。** + +```text +com\lcfc\agent\eventhub\ +├── MisAgentEventHub.java # 通过init方法注册监听器,使用broadcast推送事件 +└── MisAgentEventListener.java # 所有监听器都必须实现该接口 +``` + +#### 长期记忆 + +```text +com\lcfc\agent\memory\ +├── UserLongTermChannel.java # 长期记忆组件的通道,例如hindsight +├── UserLongTermMemoryClient.java # 用户级别长期记忆的客户端接口 +├── UserLongTermMemoryConfig.java # 用户级别长期记忆的配置 +└── UserLongTermMemoryCtl.java # 用户级别长期记忆的控制类 +``` + +#### 智能体监控 + +收集单/多智能体运行时调用了哪些tool、skill、workflow、知识库，以及消耗了多少token等数据。 + +```text +com\lcfc\agent\monitor\ +├── AgentChatMetricsCtx.java # 智能体监控数据上下文对象 +├── AgentChatMetricsFinishEvent.java # 智能体监控数据收集完成事件消息 +├── AgentChatMetricsFinishListener.java # 智能体监控数据收集完成事件监听器 +├── IAgentChatMetricsConsumer.java # 消费智能体监控数据接口 +├── MisAgentChatMetricsCtl.java # 智能体监控上下文对象控制类 +└── MisMcpToolMetadataCtl.java # 智能体MCP元数据控制类 +``` + +#### 智能体Skill + +```text +com\lcfc\agent\skills\ +├── BaseSkillToolsExecutor.java # 执行Skill中的脚本工具类父类 +├── AgentScopeSkillTools.java # 基于agentscope-java封装执行Skill中脚本的Tools +├── SpringAiSkillTools.java # 基于spring-ai封装执行Skill中脚本的Tools +├── AgentSkillMetadataHandler.java # 在磁盘文件记录存储了多少个Skill +├── AgentSkillResourceHandler.java # Skill静态资源处理（下载、删除） +├── AgentSkillRuntimeHandler.java # Skill运行时临时目录管理（创建、删除） +├── AgentSkillRuntimeConfigHandler.java # Skill运行时自定义配置管理（读取、删除） +├── AgentSkillSessionCache.java # Skill临时目录管理（自动续期、删除） +├── RemoveSkillConsumer.java # 智能体解绑了某个skill的事件/服务端Skill资源被删除事件 +├── SkillRemoveConsumer.java # ？ +├── SkillResourceChangeConsumer.java # 处理Skill静态资源更新事件 +└── SkillStateChangeConsumer.java # 处理Skill状态变更事件（禁用/启用） +``` + +#### 公共工具包 + +```text +com\lcfc\agent\utils\ +├── AsyncTaskTemplate.java # 多线程异步任务模板 +├── RLockTemplate.java # 基于Redis的分布式锁 +└── TransactionTaskTemplate.java # 编程式Spring事务模板 +``` + +#### 项目数据统计 + +```text +com\lcfc\agent\stats\ +├── api # Controller +├── service # Service +├── conf # 配置类 +├── domain +│ ├── dto # DTO +│ ├── vo # VO +│ ├── enums # Enum +│ ├── entity # Entity +│ └── mapper # Mapper Java源文件 +├── mq + ├── event # 消息载体 + └── consumer # 监听器 +``` + +## 代码编写规范 + +- 积极采用JDK11~21的新特性，例如：局部变量类型推断、Switch表达式、模式匹配、文本块、记录类、密封类、虚拟线程。 +- 虚拟线程应当用于IO密集型的任务，而不是CPU密集型任务。 +- 为了降低代码耦合度，提高可维护性，请积极的采用工厂、模板、策略、发布订阅等常用的设计模式。 +- 对于发布订阅模式，请根据以下情况判断：跨服务通信、集群实例广播消息，优先使用RocketMQ消息队列。进程通信使用ApplicationEventPublisher和@EventListener即可。 +- 一个方法体内的行数不得超过20行，若超过20行，请拆成多个方法。 +- 一个Java源文件的代码行数不得超过300行，若超过300行，说明拆的不够细，请拆成多个文件。 +- 请积极优先使用Lombok注解，无需担心编译速度被拖慢。 +- 对于工具类的使用，请优先采纳hutool，除非hutool没有提供才新建一个工具类。 +- 对于null处理优先使用Optional而不是if，优先使用Stream而不是循环。 +- 如果Stream的map代码块超过5行就单独写一个函数，如果map中代码块需要中间对象，优先使用记录类，记录类和DTO存放在一起。 +- 构建JavaBean对象，优先使用构造函数而不是单独写工具类或方法，只有3个以内的属性，应提供一个全部参数的构造函数。 +- List在非多线程场景，默认用ArrayList就够了。只有需要按照插入顺序遍历元素的场景，才考虑使用LinkedList。需考虑线程安全用CopyOnWriteArrayList。 +- Set在非多线程场景，默认用HashSet。对排序要求考虑用LinkedHashSet或TreeSet。需考虑线程安全用`cn.hutool.core.collection.ConcurrentHashSet`、ConcurrentSkipListSet、CopyOnWriteArraySet等。 +- Map在非线程场景，默认使用HashMap就够了。对排序要求考虑用LinkedHashMap或TreeMap。如果存在并发场景，需考虑线程安全用ConcurrentHashMap或ConcurrentSkipListMap等JUC工具包。 +- Queue的使用原则：要控制内存，用ArrayBlockingQueue。经典生产者消费者，用LinkedBlockingQueue。要窃取任务，用LinkedBlockingDeque。追求极致吞吐且不怕队列暴涨，用ConcurrentLinkedQueue。必须双端且高吞吐，用ConcurrentLinkedDeque。 +- Lock的使用原则：分布式锁使用Redisson相关API，单机使用ReentrantLock、StampedLock、ReentrantReadWriteLock即可。 + +### ORM映射规则 + +- 数据库表结构字段名称、实体类字段名称，采用驼峰与下划线映射的方式。 +- 实体类字段包含`@NotNull`注解，需要结合`@Schema`注解中的`defaultValue`属性判断是否需要设置默认值。 +- 主键列是否采用MySQL自增序列，取决于实体类被`@TableId`注解修饰的字段，要看其`type`属性，如果是`IdType.AUTO`则使用自增，否则不需要。 +- 如果`@Schema`注解指定了`maxLength`属性，按如下原则设置字段类型： + - 数值小于或等于2000，使用VARCHAR + - 数值大于2000且小于10000，使用TEXT + - 数值大于10000，使用LONGTEXT +- 实体类的属性类型与表结构的字段类型映射关系： + - String：默认VARCHAT(255) + - Long：默认BIGINT + - Integer：默认INT + - LocalDate：默认DATE + - LocalDateTime：默认DATETIME + - `@TableField`注解中`typeHandler`等于`JacksonTypeHandler.class`时，表结构字段默认JSON类型 + - BigDecimal：默认DECIMAL(14, 2) + +### MySQL建表语句示例 + +```sql +CREATE TABLE `example_table` ( + `id` BIGINT NOT NULL COMMENT 'ID', + `str_field` VARCHAR(32) NOT NULL COMMENT '字符串`, + `int_field` INT DEFAULT NULL COMMENT '整数`, + `long_field` BIGINT DEFAULT NULL COMMENT '长整数`, + `decimal_field` DECIMAL(14, 2) DEFAULT NULL COMMENT '高精度浮点数`, + `date_field` DATE NOT NULL COMMENT '日期类型`, + `time_field` DATETIME NOT NULL COMMENT '日期类型`, + `state` VARCHAR(32) NOT NULL COMMENT '状态：only_read、read_write', + `json_field` JSON DATETIME NULL COMMENT 'JSON类型' + PRIMARY KEY (`id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='示例表'; +``` + +### 数据库实体类示例 + +```java +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableField; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; +import com.fasterxml.jackson.annotation.JsonFormat; +import io.swagger.v3.oas.annotations.media.Schema; +import jakarta.validation.constraints.NotBlank; +import jakarta.validation.constraints.NotNull; +import lombok.Data; +import lombok.Getter; +import org.springframework.format.annotation.DateTimeFormat; +import com.fasterxml.jackson.databind.annotation.JsonSerialize; +import com.baomidou.mybatisplus.extension.handlers.JacksonTypeHandler; +import com.fasterxml.jackson.databind.ser.std.ToStringSerializer; +import java.io.Serial; +import java.io.Serializable; +import java.time.LocalDate; +import java.time.LocalDateTime; +import java.math.BigDecimal; + +@Data +@TableName(value = "example_table", autoResultMap = true) +@Schema(title = "示例表") +public class ExampleEntity implements Serializable { + + @Serial + private static final long serialVersionUID = 1L; + + @Schema(description = "ID") + @TableId(value = "id", type = IdType.ASSIGN_ID) + @TableField(value = "id") + @JsonSerialize(using = ToStringSerializer.class) + private Long id; + + @NotBlank + @Schema(description = "字符串") + @TableField(value = "str_field") + private String strField; + + @Schema(description = "整数", defaultValue = "0") + @TableField(value = "int_field") + private Integer intField; + + @Schema(description = "长整数") + @TableField(value = "long_field") + @JsonSerialize(using = ToStringSerializer.class) + private Long longField; + + @Schema(description = "高精度浮点数") + @TableField(value = "decimal_field") + private BigDecimal decimalField; + + @NotNull + @Schema(description = "日期类型", pattern = "yyyy-MM-dd") + @TableField(value = "date_field") + @DateTimeFormat(pattern = "yyyy-MM-dd") + @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8") + private LocalDate dateField; + + @NotNull + @Schema(description = "时间类型", pattern = "yyyy-MM-dd HH:mm:ss") + @TableField(value = "time_field") + @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") + @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") + private LocalDateTime timeField; + + @NotNull + @Schema( + title = "状态", + description = "参考示例值", + example = StateEnum.DESC + ) + @TableField(value = "state") + private StateEnum state; + + @Schema(description = "JSON类型") + @TableField(value = "json_field", typeHandler = JacksonTypeHandler.class) + private JsonField jsonField; + + @Data + public static class JsonField implements Serializable { + + @Serial + private static final long serialVersionUID = 1L; + + @Schema(description = "示例字段1") + private String field1; + + @Schema(description = "示例字段2") + private Integer field2; + } + +} +``` + +### 枚举类示例 + +```java +import com.baomidou.mybatisplus.annotation.EnumValue; +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonValue; +import io.swagger.v3.oas.annotations.media.Schema; +import lombok.Getter; +import lombok.RequiredArgsConstructor; + +@Getter +@RequiredArgsConstructor +@Schema(description = "某某状态") +public enum StateEnum { + + ONLY_READ("only_read"), + + READ_WRITE("read_write"); + + public static final String DESC = "only_read=只读、read_write=读写"; + + @JsonValue + @EnumValue + private final String value; + + @JsonCreator + public static StateEnum deserialize(String input) { + return Arrays.stream(values()).filter(e -> e.getValue().equals(input)).findFirst().orElse(null); + } +} +``` + +### DTO、VO + +```java +import com.fasterxml.jackson.annotation.JsonFormat; +import io.swagger.v3.oas.annotations.media.Schema; +import jakarta.validation.constraints.NotBlank; +import jakarta.validation.constraints.NotNull; +import lombok.Data; +import lombok.Getter; +import org.springframework.format.annotation.DateTimeFormat; +import com.fasterxml.jackson.databind.annotation.JsonSerialize; +import com.fasterxml.jackson.databind.ser.std.ToStringSerializer; +import java.io.Serial; +import java.io.Serializable; +import java.time.LocalDate; +import java.time.LocalDateTime; +import java.math.BigDecimal; + +@Data +@Schema(title = "DTO示例") +public class ExampleDTO implements Serializable { + + @Serial + private static final long serialVersionUID = 1L; + + @NotBlank + @Schema(description = "字符串") + private String strField; + + @Schema(description = "长整数") + @JsonSerialize(using = ToStringSerializer.class) + private Long longField; + + @NotNull + @Schema(description = "日期类型", pattern = "yyyy-MM-dd") + @DateTimeFormat(pattern = "yyyy-MM-dd") + @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8") + private LocalDate dateField; + + @NotNull + @Schema(description = "时间类型", pattern = "yyyy-MM-dd HH:mm:ss") + @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") + @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") + private LocalDateTime timeField; + + @NotNull + @Schema( + title = "状态", + description = "参考示例值", + example = StateEnum.DESC + ) + private StateEnum state; + +} +``` \ No newline at end of file diff --git a/mis-agent-spec/references/arch.md b/mis-agent-spec/references/arch.md deleted file mode 100644 index a2eb7ee..0000000 --- a/mis-agent-spec/references/arch.md +++ /dev/null @@ -1,17 +0,0 @@ -| 名称 | 版本 | 官方文档 | Github | -|:-----|:-----|:-----|:-----| -|Java|OpenJDK21|-|-| -|spring-boot|3.2.9|https://docs.spring.io/spring-boot/docs/3.2.9/reference/html|https://github.com/spring-projects/spring-boot/tree/v3.2.9| -|spring-framework|6.1.12|https://docs.spring.io/spring-framework/reference/6.2/index.html|https://github.com/spring-projects/spring-framework/tree/v6.1.12| -|rocketmq-spring-boot-starter|2.2.3|https://rocketmq.apache.org/zh/docs/4.x|https://github.com/apache/rocketmq-spring/tree/rocketmq-spring-all-2.2.3| -|rocketmq-client|4.9.8|-|https://github.com/apache/rocketmq/tree/rocketmq-all-4.9.8| -|mybatis-plus|3.5.7|https://baomidou.com/introduce/|https://github.com/baomidou/mybatis-plus/tree/v3.5.7| -|MySQL|8.0.25|https://dev.mysql.com/doc/refman/8.0/en/|https://github.com/mysql/mysql-server/tree/mysql-8.0.25| -|Redis|8.0+|-|-| -|redisson-spring-boot-starter|3.34.1|https://redisson.pro/docs/integration-with-spring/#usage|https://github.com/redisson/redisson/tree/redisson-3.34.1/redisson-spring-boot-starter/src/main| -|agentscope-java|1.0.11|https://java.agentscope.io/v1/zh/docs/task/agent-as-tool.html|https://github.com/agentscope-ai/agentscope-java/tree/v1.0.11| -|spring-ai-alibaba|1.1.2.2|https://java2ai.com/docs/overview|https://github.com/alibaba/spring-ai-alibaba/tree/v1.1.2.2| -|spring-ai|1.1.2|https://docs.spring.io/spring-ai/reference/1.1/index.html|https://github.com/spring-projects/spring-ai/tree/v1.1.2| -|hutool-core|5.8.42|https://github.com/chinabugotech/hutool-site/tree/master/docs/core|https://github.com/chinabugotech/hutool/tree/5.8.42/hutool-core| -|hutool-json|5.8.42|https://github.com/chinabugotech/hutool-site/tree/master/docs/json|https://github.com/chinabugotech/hutool/tree/5.8.42/hutool-json| -|spring-cloud-alibaba|2023.0.1.2|https://sca.aliyun.com/docs/2023/overview/version-explain|https://github.com/alibaba/spring-cloud-alibaba/tree/2023.0.1.2| \ No newline at end of file diff --git a/mis-agent-spec/references/coding-rules.md b/mis-agent-spec/references/coding-rules.md deleted file mode 100644 index 812fd77..0000000 --- a/mis-agent-spec/references/coding-rules.md +++ /dev/null @@ -1,243 +0,0 @@ -# 代码编写规范 - -请严格遵守以下原则书写干净整洁的Java源码。 - -## 书写规范 - -- 积极采用JDK11~21的新特性，例如：局部变量类型推断、Switch表达式、模式匹配、文本块、记录类、密封类、虚拟线程。 -- 虚拟线程应当用于IO密集型的任务，而不是CPU密集型任务。 -- 为了降低代码耦合度，提高可维护性，请积极的采用工厂、模板、策略、发布订阅等常用的设计模式。 -- 对于发布订阅模式，请根据以下情况判断：跨服务通信、集群实例广播消息，优先使用RocketMQ消息队列。进程通信使用ApplicationEventPublisher和@EventListener即可。 -- 一个方法体内的行数不得超过20行，若超过20行，请拆成多个方法。 -- 一个Java源文件的代码行数不得超过300行，若超过300行，说明拆的不够细，请拆成多个文件。 -- 请积极优先使用Lombok注解，无需担心编译速度被拖慢。 -- 对于工具类的使用，请优先采纳hutool，除非hutool没有提供才新建一个工具类。 -- 对于null处理优先使用Optional而不是if，优先使用Stream而不是循环。 -- 如果Stream的map代码块超过5行就单独写一个函数，如果map中代码块需要中间对象，优先使用记录类，记录类和DTO存放在一起。 -- 构建JavaBean对象，优先使用构造函数而不是单独写工具类或方法，只有3个以内的属性，应提供一个全部参数的构造函数。 -- List在非多线程场景，默认用ArrayList就够了。只有需要按照插入顺序遍历元素的场景，才考虑使用LinkedList。需考虑线程安全用CopyOnWriteArrayList。 -- Set在非多线程场景，默认用HashSet。对排序要求考虑用LinkedHashSet或TreeSet。需考虑线程安全用`cn.hutool.core.collection.ConcurrentHashSet`、ConcurrentSkipListSet、CopyOnWriteArraySet等。 -- Map在非线程场景，默认使用HashMap就够了。对排序要求考虑用LinkedHashMap或TreeMap。如果存在并发场景，需考虑线程安全用ConcurrentHashMap或ConcurrentSkipListMap等JUC工具包。 -- Queue的使用原则：要控制内存，用ArrayBlockingQueue。经典生产者消费者，用LinkedBlockingQueue。要窃取任务，用LinkedBlockingDeque。追求极致吞吐且不怕队列暴涨，用ConcurrentLinkedQueue。必须双端且高吞吐，用ConcurrentLinkedDeque。 -- Lock的使用原则：分布式锁使用Redisson相关API，单机使用ReentrantLock、StampedLock、ReentrantReadWriteLock即可。 - -## ORM映射规则 - -- 数据库表结构字段名称、实体类字段名称，采用驼峰与下划线映射的方式。 -- 实体类字段包含`@NotNull`注解，需要结合`@Schema`注解中的`defaultValue`属性判断是否需要设置默认值。 -- 主键列是否采用MySQL自增序列，取决于实体类被`@TableId`注解修饰的字段，要看其`type`属性，如果是`IdType.AUTO`则使用自增，否则不需要。 -- 如果`@Schema`注解指定了`maxLength`属性，按如下原则设置字段类型： - - 数值小于或等于2000，使用VARCHAR - - 数值大于2000且小于10000，使用TEXT - - 数值大于10000，使用LONGTEXT -- 实体类的属性类型与表结构的字段类型映射关系： - - String：默认VARCHAT(255) - - Long：默认BIGINT - - Integer：默认INT - - LocalDate：默认DATE - - LocalDateTime：默认DATETIME - - `@TableField`注解中`typeHandler`等于`JacksonTypeHandler.class`时，表结构字段默认JSON类型 - - BigDecimal：默认DECIMAL(14, 2) - -## MySQL建表语句示例 - -```sql -CREATE TABLE `example_table` ( - `id` BIGINT NOT NULL COMMENT 'ID', - `str_field` VARCHAR(32) NOT NULL COMMENT '字符串`, - `int_field` INT DEFAULT NULL COMMENT '整数`, - `long_field` BIGINT DEFAULT NULL COMMENT '长整数`, - `decimal_field` DECIMAL(14, 2) DEFAULT NULL COMMENT '高精度浮点数`, - `date_field` DATE NOT NULL COMMENT '日期类型`, - `time_field` DATETIME NOT NULL COMMENT '日期类型`, - `state` VARCHAR(32) NOT NULL COMMENT '状态：only_read、read_write', - `json_field` JSON DATETIME NULL COMMENT 'JSON类型' - PRIMARY KEY (`id`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='示例表'; -``` - -## 数据库实体类示例 - -```java -import com.baomidou.mybatisplus.annotation.IdType; -import com.baomidou.mybatisplus.annotation.TableField; -import com.baomidou.mybatisplus.annotation.TableId; -import com.baomidou.mybatisplus.annotation.TableName; -import com.fasterxml.jackson.annotation.JsonFormat; -import io.swagger.v3.oas.annotations.media.Schema; -import jakarta.validation.constraints.NotBlank; -import jakarta.validation.constraints.NotNull; -import lombok.Data; -import lombok.Getter; -import org.springframework.format.annotation.DateTimeFormat; -import com.fasterxml.jackson.databind.annotation.JsonSerialize; -import com.baomidou.mybatisplus.extension.handlers.JacksonTypeHandler; -import com.fasterxml.jackson.databind.ser.std.ToStringSerializer; -import java.io.Serial; -import java.io.Serializable; -import java.time.LocalDate; -import java.time.LocalDateTime; -import java.math.BigDecimal; - -@Data -@TableName(value = "example_table", autoResultMap = true) -@Schema(title = "示例表") -public class ExampleEntity implements Serializable { - - @Serial - private static final long serialVersionUID = 1L; - - @Schema(description = "ID") - @TableId(value = "id", type = IdType.ASSIGN_ID) - @TableField(value = "id") - @JsonSerialize(using = ToStringSerializer.class) - private Long id; - - @NotBlank - @Schema(description = "字符串") - @TableField(value = "str_field") - private String strField; - - @Schema(description = "整数", defaultValue = "0") - @TableField(value = "int_field") - private Integer intField; - - @Schema(description = "长整数") - @TableField(value = "long_field") - @JsonSerialize(using = ToStringSerializer.class) - private Long longField; - - @Schema(description = "高精度浮点数") - @TableField(value = "decimal_field") - private BigDecimal decimalField; - - @NotNull - @Schema(description = "日期类型", pattern = "yyyy-MM-dd") - @TableField(value = "date_field") - @DateTimeFormat(pattern = "yyyy-MM-dd") - @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8") - private LocalDate dateField; - - @NotNull - @Schema(description = "时间类型", pattern = "yyyy-MM-dd HH:mm:ss") - @TableField(value = "time_field") - @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") - @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") - private LocalDateTime timeField; - - @NotNull - @Schema( - title = "状态", - description = "参考示例值", - example = StateEnum.DESC - ) - @TableField(value = "state") - private StateEnum state; - - @Schema(description = "JSON类型") - @TableField(value = "json_field", typeHandler = JacksonTypeHandler.class) - private JsonField jsonField; - - @Data - public static class JsonField implements Serializable { - - @Serial - private static final long serialVersionUID = 1L; - - @Schema(description = "示例字段1") - private String field1; - - @Schema(description = "示例字段2") - private Integer field2; - } - -} -``` - -## 枚举类示例 - -```java -import com.baomidou.mybatisplus.annotation.EnumValue; -import com.fasterxml.jackson.annotation.JsonCreator; -import com.fasterxml.jackson.annotation.JsonValue; -import io.swagger.v3.oas.annotations.media.Schema; -import lombok.Getter; -import lombok.RequiredArgsConstructor; - -@Getter -@RequiredArgsConstructor -@Schema(description = "某某状态") -public enum StateEnum { - - ONLY_READ("only_read"), - - READ_WRITE("read_write"); - - public static final String DESC = "only_read=只读、read_write=读写"; - - @JsonValue - @EnumValue - private final String value; - - @JsonCreator - public static StateEnum deserialize(String input) { - return Arrays.stream(values()).filter(e -> e.getValue().equals(input)).findFirst().orElse(null); - } -} -``` - -## DTO、VO - -```java -import com.fasterxml.jackson.annotation.JsonFormat; -import io.swagger.v3.oas.annotations.media.Schema; -import jakarta.validation.constraints.NotBlank; -import jakarta.validation.constraints.NotNull; -import lombok.Data; -import lombok.Getter; -import org.springframework.format.annotation.DateTimeFormat; -import com.fasterxml.jackson.databind.annotation.JsonSerialize; -import com.fasterxml.jackson.databind.ser.std.ToStringSerializer; -import java.io.Serial; -import java.io.Serializable; -import java.time.LocalDate; -import java.time.LocalDateTime; -import java.math.BigDecimal; - -@Data -@Schema(title = "DTO示例") -public class ExampleDTO implements Serializable { - - @Serial - private static final long serialVersionUID = 1L; - - @NotBlank - @Schema(description = "字符串") - private String strField; - - @Schema(description = "长整数") - @JsonSerialize(using = ToStringSerializer.class) - private Long longField; - - @NotNull - @Schema(description = "日期类型", pattern = "yyyy-MM-dd") - @DateTimeFormat(pattern = "yyyy-MM-dd") - @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8") - private LocalDate dateField; - - @NotNull - @Schema(description = "时间类型", pattern = "yyyy-MM-dd HH:mm:ss") - @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") - @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") - private LocalDateTime timeField; - - @NotNull - @Schema( - title = "状态", - description = "参考示例值", - example = StateEnum.DESC - ) - private StateEnum state; - -} -``` \ No newline at end of file diff --git a/mis-agent-spec/references/directory-tree.md b/mis-agent-spec/references/directory-tree.md deleted file mode 100644 index 36f3482..0000000 --- a/mis-agent-spec/references/directory-tree.md +++ /dev/null @@ -1,149 +0,0 @@ -# 目录结构 - -## 根目录 - -```text -\ -├── mis-api\ -├── mis-auth\ -├── mis-common\ -├── mis-gateway\ -├── mis-modules\ # 存放业务模块代码的主目录 -├── mis-visual\ -└── pom.xml # 在中定义了Nacos地址及账号密码、NewAPI的地址和密钥 -``` - -## 主目录 - -```text -mis-modules\mis-agent\src\main\ -├── java # Java源文件 -└── resources - └── mapper # Mybatis Mapper XML - └── application.yml # 配置文件 -``` - -## 智能体 - -```text -com\lcfc\agent\agents\ -├── a2a # a2a agent -├── config # Spring配置类 -├── constants # 常量类 -├── context # 自定义的上下文载体类 -├── controller # SpringWeb控制器 -├── dubbo # Dubbo接口实现类 -├── enums # 枚举类 -├── events # Spring事件消息载体, 定义ApplicationEventPublisher.publishEvent的Payload -├── mapper # Mybatis Mapper 接口 -├── multiagent # 多智能体,采用agentscope-java的Agent AS Tool架构 -├── saa # 单智能体,采用spring-ai-alibaba的方案 -├── service # CRUD业务逻辑接口 -│ └── impl # CRUD业务逻辑接口实现类 -├── util # 工具类 -├── validator # 封装复杂的/可复用的验证工具 -├── domain # 数据库实体类 - ├── DTO # DTO - └── VO # VO -``` - -## 事件发布订阅 - -目的是摆脱对`ApplicationEventPublisher`的依赖，在非`springbean`对象中简单的使用发布订阅模式。 - -```text -com\lcfc\agent\eventhub\ -├── MisAgentEventHub.java # 通过init方法注册监听器,使用broadcast推送事件 -└── MisAgentEventListener.java # 所有监听器都必须实现该接口 -``` - -## 智能体记忆 - -管理智能体的长期记忆。 - -```text -com\lcfc\agent\memory\ -├── UserLongTermChannel.java # 长期记忆组件的通道枚举,例如hindsight -├── UserLongTermMemoryClient.java # 用户级别长期记忆的客户端接口 -├── UserLongTermMemoryConfig.java # 用户级别长期记忆的配置 -└── UserLongTermMemoryCtl.java # 用户级别长期记忆的控制类 -``` - -## 智能体监控 - -收集智能体运行时调用了哪些tool、使用了哪些Skill、触发了哪些工作流、查询了哪些知识库、消耗了多少token等数据。 - -```text -com\lcfc\agent\monitor\ -├── AgentChatMetricsCtx.java # 智能体监控数据的上下文对象 -├── AgentChatMetricsFinishEvent.java # 智能体监控数据收集完成事件消息载体 -├── AgentChatMetricsFinishListener.java # 智能体监控数据收集完成事件监听器 -├── IAgentChatMetricsConsumer.java # 消费智能体监控数据上下文对象的接口 -├── MisAgentChatMetricsCtl.java # 管理多智能体和单智能体监控上下文对象的控制类 -└── MisMcpToolMetadataCtl.java # 管理多智能体和单智能体MCP工具元数据的控制类 -``` - -## 对于agentscope-java的封装 - -提炼使用agentscope-java构建智能体可复用的能力。 - -```text -com\lcfc\agent\scope\ -├── AgentScopeAgentCtl.java # 构建ReActAgent.Builder和A2aAgent.Builder对象的控制类 -├── AgentScopeChatUsageUtils.java # 计算Token消耗的工具类 -├── AgentScopeMemoryCtl.java # 管理官方提供的AutoContextMemory自动压缩上下文控制类 -├── AgentScopeModelCtl.java # 控制agentscope-java默认使用的聊天模型 -├── AgentScopeMsgCtl.java # 管理智能体输入或输出消息,例如查询知识库或者保存用户输入或者智能体输出的消息,或者创建一个会话窗口ID -├── AgentScopeMsgUtils.java # 格式化Msg的工具类 -├── AgentScopeSkillCtl.java # 管理Skill的控制类 -├── AgentScopeToolCtl.java # 管理Tool以及MCPTool的控制类 -├── KbReferenceCtl.java # 引用的知识库控制类 -└── KbSearchCtl.java # 知识库搜索控制类 -``` - -## 管理Skill - -```text -com\lcfc\agent\skills\ -├── BaseSkillToolsExecutor.java # 执行Skill中的脚本工具类父类 -├── AgentScopeSkillTools.java # 基于agentscope-java封装执行Skill中脚本的Tools -├── SpringAiSkillTools.java # 基于spring-ai封装执行Skill中脚本的Tools -├── AgentSkillMetadataHandler.java # 在磁盘文件记录存储了多少个Skill,包括技能ID和名称 -├── AgentSkillResourceHandler.java # 负责Skill静态资源的下载、解压、删除 -├── AgentSkillRuntimeHandler.java # 每个会话都会拷贝用到的Skill资源到临时目录,该类负责临时目录的创建与删除 -├── AgentSkillRuntimeConfigHandler.java # Skill包含自定义配置,该类管理运行时自定义配置的创建、读取、删除 -├── AgentSkillSessionCache.java # 管理智能体运行时SKill临时目录,包括自动续期与超时,超时会自动清理,避免磁盘空间浪费 -├── RemoveSkillConsumer.java # 处理智能体解绑了某个skill的事件/服务端Skill资源被删除事件 -├── SkillRemoveConsumer.java # ？ -├── SkillResourceChangeConsumer.java # 处理Skill资源更新事件 -├── SkillStateChangeConsumer.java # 处理Skill状态变更事件(禁用/启用) -├── AgentSkillRuntimeConfig.java # 智能体运行时Skill配置，例如：临时目录的根目录、过期时长等 -└── AgentSkillResourceConfig.java # Skill资源配置，例如：静态资源的根目录、最多存放的静态资源数量等 -``` - -## 公共工具包 - -```text -com\lcfc\agent\utils\ -├── AsyncTaskTemplate.java # 多线程、异步任务模板 -├── RLockTemplate.java # 基于Redis的分布式锁 -└── TransactionTaskTemplate.java # 编程式Spring事务模板 -``` - -## 项目数据统计相关 - -```text -com\lcfc\agent\stats\ -├── api # Controller -├── service # Service -├── conf # 配置类 -├── domain -│ ├── dto # DTO -│ ├── vo # VO -│ ├── enums # Enum -│ ├── entity # Entity -│ └── mapper # Mapper Java源文件 -├── mq - ├── event # 消息载体 - └── consumer # 监听器 -``` \ No newline at end of file diff --git a/mis-agent-spec/references/mvn.md b/mis-agent-spec/references/mvn.md deleted file mode 100644 index 571add8..0000000 --- a/mis-agent-spec/references/mvn.md +++ /dev/null @@ -1,17 +0,0 @@ -# Intro - -系统已安装`mvnd`用来替换`mvn`命令，没有特殊要求使用**全局打包**。 - -## 全局打包 - -```bash -mvnd clean package -DskipTests -P{profile} -``` - -## 单个模块打包 - -变量`{module_name}`需要替换成目标模块名称。 - -```bash -mvnd clean package -DskipTests -P{profile} -pl {module_name} -am -``` \ No newline at end of file diff --git a/mis-agent-spec/references/nacos.md b/mis-agent-spec/references/nacos.md index c48c864..e69de29 100644 --- a/mis-agent-spec/references/nacos.md +++ b/mis-agent-spec/references/nacos.md @@ -1,48 +0,0 @@ -# Intro - -你可以通过本文档获取访问Nacos配置。 - -## 变量 - -- base_url、username、password：从pom.xml里的profile获取。 -- dataId、namespace：使用profile的名称，例如：dev/qas。 -- groupName：固定值"DEFAULT_GROUP"。 - -## 配置文件说明 - -- mis-agent.yml：当前模块也就是**mis-agent**应用的配置文件 -- datasource.yml：MySQL数据源配置。 - -## 如何获取accessToken - -请求示例： - -```bash -curl -X POST 'http://{base_url}/nacos/v1/auth/login' -d 'username={username}&password={password}' -``` - -输出示例： - -```json -{"accessToken":"xxx"} -``` - -## 如何获取配置项 - -请求示例： - -```bash -curl -X GET "http://{base_url}/nacos/v3/console/cs/config?dataId={dataId}&groupName={groupName}&namespaceId={namespace}" -H "Authorization: Bearer xxx" -``` - -输出示例： - -```json -{ - "code": 0, - "message": "success", - "data": {"content": "..."} -} -``` - -> `data.content`就是**yml**格式的配置内容。 \ No newline at end of file