diff --git a/mis-agent-spec/SKILL.md b/mis-agent-spec/SKILL.md index 9537e16..bb2f8b6 100644 --- a/mis-agent-spec/SKILL.md +++ b/mis-agent-spec/SKILL.md @@ -5,93 +5,7 @@ description: 在mis-agent模块编写代码必备技能。 # Intro -请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈),并严格遵守[代码编写规范](#代码编写规范)修改、编写代码,被要求编写HTTP接口文档时,请参考[HTTP接口文档示例](./examples/api-doc.md)。 - -## FAQ - -### 怎么确认用哪个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`命令,先确认该用哪个profile,获取`profiles.active`后在[项目根目录](#项目根目录)执行如下命令即可,**耗时约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格式。 +请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈),并严格遵守[代码编写规范](#代码编写规范)生成代码,被要求编写HTTP接口文档时,请参考[HTTP接口文档示例](./examples/api-doc.md)。 ## 核心技术栈 @@ -155,126 +69,88 @@ curl -X GET "http://{nacos.server}/nacos/v3/console/cs/config?dataId={dataId}&gr ```text \ -├── mis-api\ -├── mis-auth\ -├── mis-common\ -├── mis-gateway\ -├── mis-modules\ # 存放业务模块代码的主目录 -├── mis-visual\ +├── mis-api\ # 微服务之间暴露的dubbo接口 +├── mis-auth\ # API网关鉴权服务 +├── mis-common\ # 存放多个模块的公共依赖 +├── mis-gateway\ # API网关 +├── mis-modules\ # 业务模块代码根目录 +├── mis-visual\ # 与业务无关的子模块 └── pom.xml # 在中定义了Nacos地址及账号密码、NewAPI的地址和密钥 ``` -### mis-agent模块主目录 +### 模块根目录 ```text mis-modules\mis-agent\src\main\ -├── java # Java源文件 +├── java +│ └── com\lcfc\agent\ +│ ├── agents\ # 智能体核心 +│ │ ├── a2a\ # A2A Agent +│ │ ├── config\ # Spring配置类 +│ │ ├── constants\ # 常量类 +│ │ ├── context\ # 自定义上下文载体类 +│ │ ├── controller\ # SpringWeb控制器 +│ │ ├── dubbo\ # Dubbo接口实现类 +│ │ ├── enums\ # 枚举类 +│ │ ├── events\ # Spring事件消息 +│ │ ├── mapper\ # Mybatis Mapper接口 +│ │ ├── multiagent\ # 多智能体 +│ │ ├── saa\ # 单智能体 +│ │ ├── service\ # Service接口 +│ │ │ └── impl\ # Service接口实现类 +│ │ ├── util\ # 工具类 +│ │ ├── validator\ # 验证器 +│ │ └── domain\ # 数据库实体类 +│ │ ├── DTO\ # 数据传输对象 +│ │ └── VO\ # 视图对象 +│ ├── eventhub\ # 事件发布订阅(非SpringBean可用) +│ │ ├── MisAgentEventHub.java # 注册监听器,broadcast推送事件 +│ │ └── MisAgentEventListener.java # 所有监听器须实现此接口 +│ ├── memory\ # 长期记忆 +│ │ ├── UserLongTermChannel.java # 记忆通道(如hindsight) +│ │ ├── UserLongTermMemoryClient.java # 用户级长期记忆客户端接口 +│ │ ├── UserLongTermMemoryConfig.java # 用户级长期记忆配置 +│ │ └── UserLongTermMemoryCtl.java # 用户级长期记忆控制类 +│ ├── monitor\ # 智能体监控(收集tool/skill/workflow/知识库调用及token消耗) +│ │ ├── AgentChatMetricsCtx.java # 监控数据上下文 +│ │ ├── AgentChatMetricsFinishEvent.java# 监控数据收集完成事件 +│ │ ├── AgentChatMetricsFinishListener.java # 监控数据完成监听器 +│ │ ├── IAgentChatMetricsConsumer.java # 消费监控数据接口 +│ │ ├── MisAgentChatMetricsCtl.java # 监控上下文控制类 +│ │ └── MisMcpToolMetadataCtl.java # MCP元数据控制类 +│ ├── skills\ # 智能体Skill +│ │ ├── BaseSkillToolsExecutor.java # Skill脚本执行工具父类 +│ │ ├── AgentScopeSkillTools.java # 基于agentscope-java执行Skill脚本 +│ │ ├── SpringAiSkillTools.java # 基于spring-ai执行Skill脚本 +│ │ ├── 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状态变更事件处理(禁用/启用) +│ ├── utils\ # 公共工具包 +│ │ ├── AsyncTaskTemplate.java # 多线程异步任务模板 +│ │ ├── RLockTemplate.java # 基于Redis的分布式锁 +│ │ └── TransactionTaskTemplate.java # 编程式Spring事务模板 +│ └── stats\ # 项目数据统计 +│ ├── api\ # Controller +│ ├── service\ # Service +│ ├── conf\ # 配置类 +│ ├── domain\ +│ │ ├── dto\ # DTO +│ │ ├── vo\ # VO +│ │ ├── enums\ # Enum +│ │ ├── entity\ # Entity +│ │ └── mapper\ # Mapper Java源文件 +│ └── mq\ +│ ├── event\ # 消息载体 +│ └── consumer\ # 监听器 └── 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 # 监听器 + ├── mapper\ # Mybatis Mapper XML + └── application.yml # 配置文件 ``` ## 代码编写规范 @@ -296,25 +172,27 @@ com\lcfc\agent\stats\ - Queue的使用原则:要控制内存,用ArrayBlockingQueue。经典生产者消费者,用LinkedBlockingQueue。要窃取任务,用LinkedBlockingDeque。追求极致吞吐且不怕队列暴涨,用ConcurrentLinkedQueue。必须双端且高吞吐,用ConcurrentLinkedDeque。 - Lock的使用原则:分布式锁使用Redisson相关API,单机使用ReentrantLock、StampedLock、ReentrantReadWriteLock即可。 -### ORM映射规则 +## 实体类与MySQL字段类型映射规则 + +|实体类字段类型|MySQL字段类型| +| --- | --- | +| String | VARCHAT(255) | +| Long | BIGINT | +| Integer | INT | +| LocalDate | DATE | +| LocalDateTime | DATETIME | +| BigDecimal | DECIMAL(14, 2) | - 数据库表结构字段名称、实体类字段名称,采用驼峰与下划线映射的方式。 +- `@TableField`注解中`typeHandler`等于`JacksonTypeHandler.class`时,表结构字段默认JSON类型。 - 实体类字段包含`@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建表语句示例 +## MySQL表结构示例 ```sql CREATE TABLE `example_table` ( @@ -331,7 +209,7 @@ CREATE TABLE `example_table` ( ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='示例表'; ``` -### 数据库实体类示例 +## 实体类示例 ```java import com.baomidou.mybatisplus.annotation.IdType; @@ -429,7 +307,7 @@ public class ExampleEntity implements Serializable { } ``` -### 枚举类示例 +## 枚举类示例 ```java import com.baomidou.mybatisplus.annotation.EnumValue; @@ -461,7 +339,7 @@ public enum StateEnum { } ``` -### DTO、VO +## DTO示例 ```java import com.fasterxml.jackson.annotation.JsonFormat; @@ -515,4 +393,90 @@ public class ExampleDTO implements Serializable { private StateEnum state; } -``` \ No newline at end of file +``` + +## FAQ + +### 怎么确认用哪个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`命令,先确认该用哪个profile,获取`profiles.active`后在[项目根目录](#项目根目录)执行如下命令即可,**耗时约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格式。 \ No newline at end of file diff --git a/mis-paw-spec/SKILL.md b/mis-paw-spec/SKILL.md index 5dec0b3..bd503f8 100644 --- a/mis-paw-spec/SKILL.md +++ b/mis-paw-spec/SKILL.md @@ -5,89 +5,7 @@ description: 在mis-paw模块编写代码必备技能。 # Intro -请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈),并严格遵守[代码编写规范](#代码编写规范)修改、编写代码。 - -## FAQ - -### 怎么确认用哪个profile? - -没有指定默认使用dev。 - -### 怎么读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`命令,先确认该用哪个profile,获取`profiles.active`后在[项目根目录](#项目根目录)执行如下命令即可,**耗时约80秒**,示例:`mvnd clean package -DskipTests -Pdev`。 - -### 怎么读取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格式。 +请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈),并严格遵守[代码编写规范](#代码编写规范)生成代码,被要求编写HTTP接口文档时,请参考[HTTP接口文档示例](./examples/api-doc.md)。 ## 核心技术栈 @@ -372,7 +290,7 @@ public enum StateEnum { } ``` -## DTO实例 +## DTO示例 ```java import com.fasterxml.jackson.annotation.JsonFormat; @@ -426,4 +344,86 @@ public class ExampleDTO implements Serializable { private StateEnum state; } -``` \ No newline at end of file +``` + +## FAQ + +### 怎么确认用哪个profile? + +没有指定默认使用dev。 + +### 怎么读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`命令,先确认该用哪个profile,获取`profiles.active`后在[项目根目录](#项目根目录)执行如下命令即可,**耗时约80秒**,示例:`mvnd clean package -DskipTests -Pdev`。 + +### 怎么读取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格式。 \ No newline at end of file diff --git a/mis-paw-spec/examples/api-doc.md b/mis-paw-spec/examples/api-doc.md new file mode 100644 index 0000000..956e74a --- /dev/null +++ b/mis-paw-spec/examples/api-doc.md @@ -0,0 +1,60 @@ +# 智能体使用数据 + +以下是关于智能体使用数据的API文档。 + +## 累计使用数据卡片 + +- 请求地址:/agent/metrics/total +- 请求方式:GET + +### 请求参数 + +| 参数名称 | 是否必传 | 类型 | 描述 | +|:-----|:-----|:-----|:-----| +| agentId | 是 | String | 智能体ID | + +### 请求示例 + +```bash +curl -X GET {gateway}/agent/metrics/total?agentId={agentId} +``` + +### 响应参数 + +| 参数名称 | 类型 | 描述 | +|:-----|:-----|:-----| +| code | Number | 返回码(200=成功) | +| msg | String | 提示信息 | +| data | Object | 返回数据 | +| data.agentId | String | 智能体 ID | +| data.agentName | String | 智能体名称 | +| data.inputToken | Number | 累计输入Token | +| data.outputToken | Number | 累计输出Token | +| data.userNum | Number | 累计用户数 | +| data.chatNum | Number | 累计对话数 | + +### 成功示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "agentId": "123456", + "agentName": "智能体名称", + "inputToken": "123243654645", + "outputToken": "345645765765", + "userNum": 5678, + "chatNum": 45678999 + } +} +``` + +### 失败示例 + +```json +{ + "code": 500, + "msg": "错误信息" +} +``` \ No newline at end of file