tmp/API-2609.md

# 数据统计

以下是关于数据统计的API文档。

## 提交用户点赞/取消赞/写评论

- 请求地址：/mcp/metrics
- 请求方式：POST

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| tag | 是 | String | 资源类型（agent=智能体、skill=技能、mcp_server=MCP服务） |
| operateType | 是 | String | 操作类型（like=点赞、like_withdraw=取消赞、write_comment=写评论） |
| resourceId | 是 | String | 资源ID，Agent传ID、Skill传skillId、MCP传mcpServerUuid |
| comment.content | 否 | String | 评论内容，最大500字 |
| comment.star | 否 | Number | 星级，1~5 |

### 请求示例

```bash
curl -X POST {gateway}/mcp/metrics \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "agent",
    "operateType": "write_comment",
    "resourceId": "123456",
    "comment": {
      "content": "很好用的智能体",
      "star": 5
    }
  }'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Boolean | 操作是否成功 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": true
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 查询用户点赞/取消赞/写评论

- 请求地址：/mcp/metrics
- 请求方式：POST

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| tag | 是 | String | 资源类型（agent=智能体、skill=技能、mcp_server=MCP服务） |
| resourceId | 是 | String | 资源ID，Agent传ID、Skill传skillId、MCP传mcpServerUuid |
| comment.pageNum | 否 | Number | 分页页码，默认1 |
| comment.pageSize | 否 | Number | 分页条数，默认25 |

### 请求示例

```bash
curl -X GET '{gateway}/mcp/metrics?tag={tag}&resourceId={resourceId}' \
  -H "Content-Type: application/json"
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Object | 返回数据 |
| data.appendCount | Number | 已有多少人添加 |
| data.likeCount | Number | 已有多少人点赞 |
| data.comments | Object | 评分与评论分页数据 |
| data.comments.total | Number | 总记录数 |
| data.comments.rows | Array | 评论列表 |
| data.comments.rows[].commentId | Number | 评论ID |
| data.comments.rows[].userId | String | 用户ID |
| data.comments.rows[].username | String | 用户名 |
| data.comments.rows[].nickname | String | 昵称 |
| data.comments.rows[].comment | String | 评论内容 |
| data.comments.rows[].time | String | 评论时间，格式 yyyy-MM-dd HH:mm:ss |
| data.comments.rows[].star | Number | 评分星级，1~5 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "appendCount": "100",
        "likeCount": "50",
        "comments": {
            "total": 10,
            "rows": [
                {
                    "commentId": "1",
                    "userId": "100",
                    "username": "user001",
                    "nickname": "张三",
                    "comment": "很好用的智能体",
                    "time": "2024-01-01 12:00:00",
                    "star": 5
                }
            ]
        }
    }
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 用户删除评论

- 请求地址：/mcp/metrics/comment
- 请求方式：DELETE

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| commentId | 是 | Number | 评论ID（Query参数） |

### 请求示例

```bash
curl -X DELETE '{gateway}/mcp/metrics/comment?commentId={commentId}'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Boolean | 操作是否成功 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": true
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

# 客户端软件包

以下是关于客户端软件包的API文档。

## 版本列表

- 请求地址：/system/client/software
- 请求方式：GET

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| identity | 是 | String | 客户端标识，如 devco |
| canary | 否 | Boolean | 传true则查询范围覆盖灰度版，否则只查正式版 |

### 请求示例

```bash
curl -X GET '{gateway}/system/client/software?identity={identity}&canary={canary}'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Array | 版本列表 |
| data[].releaseId | Number | 版本记录 ID |
| data[].versionNo | String | 版本号 |
| data[].releaseTime | String | 发布时间，格式 yyyy-MM-dd HH:mm:ss |
| data[].releaseNotes | String | 更新内容 |
| data[].packageOssId | Number | 安装包 OSS 主键；前端据此请求预签名下载地址 |
| data[].packageName | String | 安装包文件名 |
| data[].packageSize | Number | 安装包大小（字节） |
| data[].packageSizeDisplay | String | 安装包大小展示文案，如 12.50 MB |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "releaseId": "123456",
            "versionNo": "1.0.0",
            "releaseTime": "2024-01-01 12:00:00",
            "releaseNotes": "更新内容",
            "packageOssId": "789",
            "packageName": "devco-1.0.0.exe",
            "packageSize": 52428800,
            "packageSizeDisplay": "50.00 MB"
        }
    ]
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 查看最新版本

- 请求地址：/system/client/software/latest
- 请求方式：GET

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| identity | 是 | String | 客户端标识，如 devco |
| canary | 否 | Boolean | 传true则查询范围覆盖灰度版，否则只查正式版 |

### 请求示例

```bash
curl -X GET '{gateway}/system/client/software/latest?identity={identity}&canary={canary}'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Object | 版本信息 |
| data.releaseId | Number | 版本记录 ID |
| data.versionNo | String | 版本号 |
| data.releaseTime | String | 发布时间，格式 yyyy-MM-dd HH:mm:ss |
| data.releaseNotes | String | 更新内容 |
| data.packageOssId | Number | 安装包 OSS 主键 |
| data.packageName | String | 安装包文件名 |
| data.packageSize | Number | 安装包大小（字节） |
| data.packageSizeDisplay | String | 安装包大小展示文案，如 12.50 MB |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "releaseId": "123456",
        "versionNo": "1.0.0",
        "releaseTime": "2024-01-01 12:00:00",
        "releaseNotes": "更新内容",
        "packageOssId": "789",
        "packageName": "devco-1.0.0.exe",
        "packageSize": 52428800,
        "packageSizeDisplay": "50.00 MB"
    }
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 下载软件包

- 请求地址：/system/client/software/download/{ossId}
- 请求方式：GET

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| ossId | 是 | Number | OSSID，安装包在OSS中的唯一标识 |

### 请求示例

```bash
curl -X GET {gateway}/system/client/software/download/{ossId}
```

### 响应参数

直接返回文件流下载。

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 查看版本信息

- 请求地址：/system/client/software/{releaseId}
- 请求方式：GET

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| releaseId | 是 | Number | 版本ID |

### 请求示例

```bash
curl -X GET {gateway}/system/client/software/{releaseId}
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Object | 版本信息 |
| data.releaseId | Number | 版本记录 ID |
| data.versionNo | String | 版本号 |
| data.releaseTime | String | 发布时间，格式 yyyy-MM-dd HH:mm:ss |
| data.releaseNotes | String | 更新内容 |
| data.packageOssId | Number | 安装包 OSS 主键 |
| data.packageName | String | 安装包文件名 |
| data.packageSize | Number | 安装包大小（字节） |
| data.packageSizeDisplay | String | 安装包大小展示文案，如 12.50 MB |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "releaseId": "123456",
        "versionNo": "1.0.0",
        "releaseTime": "2024-01-01 12:00:00",
        "releaseNotes": "更新内容",
        "packageOssId": "789",
        "packageName": "devco-1.0.0.exe",
        "packageSize": 52428800,
        "packageSizeDisplay": "50.00 MB"
    }
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 新建版本

- 请求地址：/system/client/software
- 请求方式：POST

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| identity | 是 | String | 客户端标识，如 devco |
| state | 是 | String | 版本状态，canary=灰度版、release=正式版 |
| version | 是 | String | 版本号，如 1.0.0 |
| releaseTime | 否 | String | 发布时间，格式 yyyy-MM-dd HH:mm:ss；省略则取当前时间 |
| releaseNotes | 否 | String | 更新日志（富文本 HTML） |
| ossId | 是 | Number | 安装包 OSS ID |

### 请求示例

```bash
curl -X POST {gateway}/system/client/software \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "devco",
    "state": "release",
    "version": "1.0.0",
    "releaseTime": "2024-01-01 12:00:00",
    "releaseNotes": "<p>更新日志</p>",
    "ossId": 789
  }'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Object | 版本信息 |
| data.releaseId | Number | 版本记录 ID |
| data.versionNo | String | 版本号 |
| data.releaseTime | String | 发布时间，格式 yyyy-MM-dd HH:mm:ss |
| data.releaseNotes | String | 更新内容 |
| data.packageOssId | Number | 安装包 OSS 主键 |
| data.packageName | String | 安装包文件名 |
| data.packageSize | Number | 安装包大小（字节） |
| data.packageSizeDisplay | String | 安装包大小展示文案，如 12.50 MB |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "releaseId": "123456",
        "versionNo": "1.0.0",
        "releaseTime": "2024-01-01 12:00:00",
        "releaseNotes": "<p>更新日志</p>",
        "packageOssId": "789",
        "packageName": "devco-1.0.0.exe",
        "packageSize": 52428800,
        "packageSizeDisplay": "50.00 MB"
    }
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 编辑版本信息

- 请求地址：/system/client/software/{releaseId}
- 请求方式：PUT

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| releaseId | 是 | Number | 版本ID（路径参数） |
| identity | 是 | String | 客户端标识，如 devco |
| state | 是 | String | 版本状态，canary=灰度版、release=正式版 |
| version | 是 | String | 版本号，如 1.0.0 |
| releaseTime | 否 | String | 发布时间，格式 yyyy-MM-dd HH:mm:ss；省略则取当前时间 |
| releaseNotes | 否 | String | 更新日志（富文本 HTML） |
| ossId | 是 | Number | 安装包 OSS ID |

### 请求示例

```bash
curl -X PUT {gateway}/system/client/software/{releaseId} \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "devco",
    "state": "release",
    "version": "1.0.1",
    "releaseTime": "2024-01-02 12:00:00",
    "releaseNotes": "<p>修复bug</p>",
    "ossId": 790
  }'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Object | 版本信息 |
| data.releaseId | Number | 版本记录 ID |
| data.versionNo | String | 版本号 |
| data.releaseTime | String | 发布时间，格式 yyyy-MM-dd HH:mm:ss |
| data.releaseNotes | String | 更新内容 |
| data.packageOssId | Number | 安装包 OSS 主键 |
| data.packageName | String | 安装包文件名 |
| data.packageSize | Number | 安装包大小（字节） |
| data.packageSizeDisplay | String | 安装包大小展示文案，如 12.50 MB |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "releaseId": "123456",
        "versionNo": "1.0.1",
        "releaseTime": "2024-01-02 12:00:00",
        "releaseNotes": "<p>修复bug</p>",
        "packageOssId": "790",
        "packageName": "devco-1.0.1.exe",
        "packageSize": 52428800,
        "packageSizeDisplay": "50.00 MB"
    }
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "参数[releaseId]不能为空"
}
```

## 删除版本

- 请求地址：/system/client/software/{releaseId}
- 请求方式：DELETE

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| releaseId | 是 | Number | 版本ID（路径参数） |

### 请求示例

```bash
curl -X DELETE {gateway}/system/client/software/{releaseId}
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Boolean | 操作是否成功 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": true
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

# 客户端软件包测试成员管理

以下是关于客户端软件包测试成员管理的API文档。

## 查看详情

- 请求地址：/system/client/software/canary
- 请求方式：GET

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| identity | 是 | String | 客户端标识，如 devco |

### 请求示例

```bash
curl -X GET '{gateway}/system/client/software/canary?identity={identity}'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Object | 灰度配置信息 |
| data.identity | String | 客户端标识 |
| data.deptIds | Array | 部门ID列表 |
| data.userIds | Array | 用户ID列表 |
| data.dept | Array | 部门详情列表 |
| data.dept[].id | Number | 部门ID |
| data.dept[].name | String | 部门名称 |
| data.user | Array | 用户详情列表 |
| data.user[].id | Number | 用户ID |
| data.user[].name | String | 用户名称 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "identity": "devco",
        "deptIds": [1, 2, 3],
        "userIds": [100, 200],
        "dept": [
            {
                "id": 1,
                "name": "研发部"
            },
            {
                "id": 2,
                "name": "测试部"
            }
        ],
        "user": [
            {
                "id": 100,
                "name": "张三"
            },
            {
                "id": 200,
                "name": "李四"
            }
        ]
    }
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 添加用户或部门

- 请求地址：/system/client/software/canary
- 请求方式：PUT

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| identity | 是 | String | 客户端标识，如 devco |
| ids | 否 | Array | 用户ID或部门ID集合 |
| type | 是 | Number | 类型，1=用户、2=部门 |

### 请求示例

```bash
curl -X PUT {gateway}/system/client/software/canary \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "devco",
    "ids": [100, 200],
    "type": 1
  }'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Boolean | 操作是否成功 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": true
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 删除用户或部门

- 请求地址：/system/client/software/canary
- 请求方式：DELETE

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| identity | 是 | String | 客户端标识，如 devco |
| ids | 否 | Array | 用户ID或部门ID集合 |
| type | 是 | Number | 类型，1=用户、2=部门 |

### 请求示例

```bash
curl -X DELETE {gateway}/system/client/software/canary \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "devco",
    "ids": [100],
    "type": 1
  }'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Boolean | 操作是否成功 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": true
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

# 智能体管理

以下是关于智能体管理的API文档。

## 禁用或启用智能体

- 请求地址：/paw/agents/available
- 请求方式：POST

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| agentId | 是 | String | 智能体ID |
| available | 是 | Boolean | true=启用、false=禁用 |

### 请求示例

```bash
curl -X POST {gateway}/paw/agents/available \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "123456",
    "available": true
  }'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Boolean | 操作是否成功 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": true
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```