add

2026-08-11 14:27:25 +08:00
parent 1baa65e06a
commit 41ca0d39a4
6 changed files with 15 additions and 11 deletions
@@ -0,0 +1,19 @@
+| 名称 | 版本 | 官方文档 | 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|-|-|-|
+|spring-cloud-alibaba|-|-|-|
+|dubbo|-|-|-|
@@ -0,0 +1,243 @@
+# 代码编写规范
+
+请严格遵守以下原则书写干净整洁的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;
+    
+}
+```
@@ -0,0 +1,136 @@
+# 目录结构
+
+## 主目录
+
+```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                        # 监听器
+```