doc/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add

Browse Source
This commit is contained in:
V-LiuShuang
2026-08-17 15:33:03 +08:00
parent d33bb9f507
commit ca10dbb879
6 changed files with 509 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mis-agent-spec/SKILL.md
+509 -14
View File
@@ -3,21 +3,516 @@ name: mis-agent-spec
description: 在mis-agent模块编写代码必备技能。 description: 在mis-agent模块编写代码必备技能。
--- ---
# 参考资料 # Intro
- [目录结构](./references/directory-tree.md) 请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈)，并严格遵守[代码编写规范](#代码编写规范)修改、编写代码，被要求编写HTTP接口文档时，请参考[HTTP接口文档示例](./examples/api-doc.md)。
- [核心技术栈](./references/arch.md)
- [代码书写规范](./references/coding-rules.md)
- [HTTP接口文档示例](./examples/api-doc.md)
## 约定
- 请结合**目录结构**与**核心技术栈**，并严格遵守**代码书写规范**修改、编写代码，被要求编写HTTP接口文档时，请参考**HTTP接口文档示例**。
- 当前项目具有3个环境（dev/qas/prod）若没有指定**环境**则默认使用**qas**，不可以访问**prod**环境任何数据，包括但不限于数据库、HTTP接口。
- 从**根目录**下的**pom.xml**文件`<profiles>`标签里可得到不同环境下的`nacos`以及`NewAPI`连接信息。
## FAQ ## FAQ
- Q：如何确认改用哪个profile？A：若当前分支出于dev则使用dev，否则使用qas。 ### 怎么确认用哪个profile？
- Q：如何读取nacos配置？A：参考[nacos.md](./references/nacos.md)。
- Q：如何打包？A：参考[mvn.md](./references/mvn.md) 若当前Git分支出于dev则使用dev，否则使用qas。
### 怎么读profile的配置？
从[项目根目录](#项目根目录)的`pom.xml`文件中获取不同`profiles.active`的配置，示例：
```xml
<!-- 环境标识，可用的数值有：dev、qas -->
<profiles.active>dev</profiles.active>
<!-- 当前环境的Nacos服务地址 -->
<nacos.server>127.0.0.1:8868</nacos.server>
<!-- 当前环境的Nacos注册中心分组名称 -->
<nacos.discovery.group>DEFAULT_GROUP</nacos.discovery.group>
<!-- 当前环境的Nacos配置中心分组名称 -->
<nacos.config.group>DEFAULT_GROUP</nacos.config.group>
<!-- 当前环境的Nacos登录账号 -->
<nacos.username>nacos</nacos.username>
<!-- 当前环境的Nacos登录密码 -->
<nacos.password>1234567890</nacos.password>
<!-- 当前环境的NewAPI服务地址 -->
<newAPI.url>http://127.0.0.1:3000</newAPI.url>
<!-- 当前环境的NewAPI模型ApiKey -->
<newAPI.key>sk-xxx</newAPI.key>
```
### 怎么打包？
系统已安装`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 # 在<profiles>中定义了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;
}
```
mis-agent-spec/references/arch.md
-17
View File
@@ -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|
mis-agent-spec/references/coding-rules.md
-243
View File
@@ -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;
}
```
mis-agent-spec/references/directory-tree.md
-149
View File
@@ -1,149 +0,0 @@
# 目录结构
## 根目录
```text
<root>\
├── mis-api\
├── mis-auth\
├── mis-common\
├── mis-gateway\
├── mis-modules\ # 存放业务模块代码的主目录
├── mis-visual\
└── pom.xml # 在<profiles>中定义了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 # 监听器
```
mis-agent-spec/references/mvn.md
-17
View File
@@ -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
```
mis-agent-spec/references/nacos.md
-48
View File
@@ -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**格式的配置内容。