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-19 13:05:43 +08:00
parent efbaddadeb
commit 87753e5b89
3 changed files with 323 additions and 299 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mis-agent-spec/SKILL.md
+176 -212
View File
@@ -5,93 +5,7 @@ description: 在mis-agent模块编写代码必备技能。
# Intro # Intro
请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈)，并严格遵守[代码编写规范](#代码编写规范)修改、编写代码，被要求编写HTTP接口文档时，请参考[HTTP接口文档示例](./examples/api-doc.md)。 请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈)，并严格遵守[代码编写规范](#代码编写规范)生成代码，被要求编写HTTP接口文档时，请参考[HTTP接口文档示例](./examples/api-doc.md)。
## FAQ
### 怎么确认用哪个profile？
若当前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`命令，先确认该用哪个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格式。
## 核心技术栈 ## 核心技术栈
@@ -155,128 +69,90 @@ curl -X GET "http://{nacos.server}/nacos/v3/console/cs/config?dataId={dataId}&gr
```text ```text
<root>\ <root>\
├── mis-api\ ├── mis-api\ # 微服务之间暴露的dubbo接口
├── mis-auth\ ├── mis-auth\ # API网关鉴权服务
├── mis-common\ ├── mis-common\ # 存放多个模块的公共依赖
├── mis-gateway\ ├── mis-gateway\ # API网关
├── mis-modules\ # 存放业务模块代码的主目录 ├── mis-modules\ # 业务模块代码根目录
├── mis-visual\ ├── mis-visual\ # 与业务无关的子模块
└── pom.xml # 在<profiles>中定义了Nacos地址及账号密码、NewAPI的地址和密钥 └── pom.xml # 在<profiles>中定义了Nacos地址及账号密码、NewAPI的地址和密钥
``` ```
### mis-agent模块主目录 ### 模块根目录
```text ```text
mis-modules\mis-agent\src\main\ 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 └── resources
└── mapper # Mybatis Mapper XML ├── mapper\ # Mybatis Mapper XML
└── application.yml # 配置文件 └── 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表达式、模式匹配、文本块、记录类、密封类、虚拟线程。 - 积极采用JDK11~21的新特性，例如：局部变量类型推断、Switch表达式、模式匹配、文本块、记录类、密封类、虚拟线程。
@@ -296,25 +172,27 @@ com\lcfc\agent\stats\
- Queue的使用原则：要控制内存，用ArrayBlockingQueue。经典生产者消费者，用LinkedBlockingQueue。要窃取任务，用LinkedBlockingDeque。追求极致吞吐且不怕队列暴涨，用ConcurrentLinkedQueue。必须双端且高吞吐，用ConcurrentLinkedDeque。 - Queue的使用原则：要控制内存，用ArrayBlockingQueue。经典生产者消费者，用LinkedBlockingQueue。要窃取任务，用LinkedBlockingDeque。追求极致吞吐且不怕队列暴涨，用ConcurrentLinkedQueue。必须双端且高吞吐，用ConcurrentLinkedDeque。
- Lock的使用原则：分布式锁使用Redisson相关API，单机使用ReentrantLock、StampedLock、ReentrantReadWriteLock即可。 - 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`属性判断是否需要设置默认值。 - 实体类字段包含`@NotNull`注解，需要结合`@Schema`注解中的`defaultValue`属性判断是否需要设置默认值。
- 主键列是否采用MySQL自增序列，取决于实体类被`@TableId`注解修饰的字段，要看其`type`属性，如果是`IdType.AUTO`则使用自增，否则不需要。 - 主键列是否采用MySQL自增序列，取决于实体类被`@TableId`注解修饰的字段，要看其`type`属性，如果是`IdType.AUTO`则使用自增，否则不需要。
- 如果`@Schema`注解指定了`maxLength`属性，按如下原则设置字段类型： - 如果`@Schema`注解指定了`maxLength`属性，按如下原则设置字段类型：
- 数值小于或等于2000，使用VARCHAR - 数值小于或等于2000，使用VARCHAR
- 数值大于2000且小于10000，使用TEXT - 数值大于2000且小于10000，使用TEXT
- 数值大于10000，使用LONGTEXT - 数值大于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 ```sql
CREATE TABLE `example_table` ( CREATE TABLE `example_table` (
@@ -331,7 +209,7 @@ CREATE TABLE `example_table` (
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='示例表'; ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='示例表';
``` ```
### 数据库实体类示例 ## 实体类示例
```java ```java
import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.IdType;
@@ -429,7 +307,7 @@ public class ExampleEntity implements Serializable {
} }
``` ```
### 枚举类示例 ## 枚举类示例
```java ```java
import com.baomidou.mybatisplus.annotation.EnumValue; import com.baomidou.mybatisplus.annotation.EnumValue;
@@ -461,7 +339,7 @@ public enum StateEnum {
} }
``` ```
### DTO、VO ## DTO示例
```java ```java
import com.fasterxml.jackson.annotation.JsonFormat; import com.fasterxml.jackson.annotation.JsonFormat;
@@ -516,3 +394,89 @@ public class ExampleDTO implements Serializable {
} }
``` ```
## FAQ
### 怎么确认用哪个profile？
若当前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`命令，先确认该用哪个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格式。
mis-paw-spec/SKILL.md
+84 -84
View File
@@ -5,89 +5,7 @@ description: 在mis-paw模块编写代码必备技能。
# Intro # Intro
请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈)，并严格遵守[代码编写规范](#代码编写规范)修改、编写代码。 请结合[目录结构](#目录结构)与[核心技术栈](#核心技术栈)，并严格遵守[代码编写规范](#代码编写规范)生成代码，被要求编写HTTP接口文档时，请参考[HTTP接口文档示例](./examples/api-doc.md)。
## FAQ
### 怎么确认用哪个profile？
没有指定默认使用dev。
### 怎么读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`命令，先确认该用哪个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格式。
## 核心技术栈 ## 核心技术栈
@@ -372,7 +290,7 @@ public enum StateEnum {
} }
``` ```
## DTO实例 ## DTO示例
```java ```java
import com.fasterxml.jackson.annotation.JsonFormat; import com.fasterxml.jackson.annotation.JsonFormat;
@@ -427,3 +345,85 @@ public class ExampleDTO implements Serializable {
} }
``` ```
## FAQ
### 怎么确认用哪个profile？
没有指定默认使用dev。
### 怎么读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`命令，先确认该用哪个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格式。
mis-paw-spec/examples/api-doc.md
+60
View File
@@ -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": "错误信息"
}
```