# agent-cloud-interaction-protocol

**Repository Path**: onescience-ai/agent-cloud-interaction-protocol

## Basic Information

- **Project Name**: agent-cloud-interaction-protocol
- **Description**: 本项目旨在构建一套智能体与云端交互的格式，以保障智能体直接使用云平台能力时的效率与准确性。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Cloud Interaction Protocol

智能体与云端交互协议 - 让 AI 智能体直接操控云平台资源

## 项目介绍

本项目构建了一套智能体与云端交互的协议标准，使 AI 智能体能够直接调用云平台能力，提高任务执行效率与准确性。

## 核心架构

### 1. 智云协议 (ZhiYun Protocol)

智云协议是整个项目的核心协议标准，定义了智能体与云平台交互的规范。基于四层协议结构设计：

#### 智云协议四层结构

智云协议采用四层架构设计，将任务执行的不同方面进行解耦：

```
┌─────────────────────────────────────────────────────────┐
│                    智云协议 ZhiYun Protocol              │
├─────────────┬─────────────┬─────────────┬───────────────┤
│  执行层      │   软件层     │   硬件层     │   交互层       │
│ Execution   │  Software   │  Hardware   │  Interaction  │
├─────────────┼─────────────┼─────────────┼───────────────┤
│   command   │dependencies │   nodes     │ feedback_url  │
│   files     │             │cpus_per_node│callback_events│
│             │             │   memory    │               │
│             │             │    gpu      │               │
└─────────────┴─────────────┴─────────────┴───────────────┘
```

#### 核心组件

```
┌─────────────────────────────────────────────────────────┐
│                    应用层 (Application)                  │
│              (execute_scnet_task.py / CLI)              │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│              智云协议层 (ZhiYunProtocol)                 │
│         • 统一接口封装                                    │
│         • 错误码管理 (HTTP兼容)                           │
│         • Token缓存机制                                   │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│              适配器层 (CloudPlatformAdapter)              │
│              • SCnetAdapter (SCnet云平台)                │
│              • 其他云平台适配器 (可扩展)                   │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│              云平台API层 (Cloud Platform API)            │
│              • SCnet API (scnet_api_core.py)            │
│              • 其他云平台API                             │
└─────────────────────────────────────────────────────────┘
```

#### 错误码说明

智云协议使用与HTTP状态码兼容的错误码系统：

| 错误码 | 说明 | 场景 |
|--------|------|------|
| 200 | 成功 | 操作成功完成 |
| 400 | 参数无效 | 请求参数错误或缺失 |
| 401 | 认证失败 | AK/SK错误或Token过期 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 资源未找到 | 任务或资源不存在 |
| 422 | 执行失败 | 任务执行失败 |
| 500 | 未知错误 | 系统内部错误 |
| 503 | 网络错误 | 网络连接失败 |

#### 任务状态映射

SCnet平台状态码与智云协议状态的映射关系：

| SCnet状态 | 智云协议状态 | 说明 |
|-----------|-------------|------|
| statQ | queued | 队列中等待 |
| statR | running | 运行中 |
| statC | completed | 已完成 |
| statE | exited | 已退出 |
| statH | held | 已挂起 |
| statS | suspended | 已暂停 |
| statT | moved | 已迁移 |
| statW | waiting | 等待中 |

### 2. 云平台 API 适配层 (cloud-api)

云平台 API 适配层是一层共用接口，云厂家可以适配这层接口实现上层代码的复用。通过统一的 API 接口，不同云平台可以无缝集成到智能体交互系统中。

### 3. MCP 服务器实现 (mcp-server)

MCP 服务器实现了智云协议的具体功能，为 Trae IDE 提供云平台操作能力。

## 项目结构

```
agent-cloud-interaction-protocol/
├── cloud-api/              # 云平台 API 适配层
│   ├── scnet-api/         # SCnet 智云协议实现
│   └── README.md
├── mcp-server/            # MCP 服务器实现
│   ├── scnet_mcp_server.py    # MCP 服务主程序
│   ├── build.py               # 打包脚本
│   ├── requirements.txt       # 依赖文件
│   └── README.md              # 详细使用文档
└── README.md              # 本文件
```

## 核心功能

### 1. 智云协议功能

- **统一接口**: 标准化的云平台操作接口
- **四层架构**: 执行层、软件层、硬件层、交互层
- **可扩展性**: 支持多种云平台适配

### 2. 云平台 API 适配层功能

- **统一抽象**: 抽象云平台 API 调用
- **多平台支持**: 支持不同云平台的适配
- **接口标准化**: 标准化 API 接口定义

### 3. MCP 服务器功能

- **认证管理**: 支持 AK/SK 认证，多区域 token 缓存
- **任务管理**: 提交、查询、取消计算任务
- **资源查询**: 查看云平台资源状况
- **区域匹配**: 支持区域名称模糊匹配
- **缓存机制**: 支持区域和队列信息缓存
- **缓存过期**: 缓存数据自动过期，确保数据时效性
- **错误处理**: 统一的错误处理机制

## 快速开始

### 方式一：使用可执行文件（推荐）

1. 下载 `scnet-mcp-server-windows.zip` 发布包
2. 解压到本地目录
3. 在 Trae 中配置 MCP 服务器：

```json
{
  "mcpServers": {
    "scnet": {
      "command": "D:/path/to/scnet-mcp-server.exe",
      "env": {
        "SCNET_USERNAME": "your_username",
        "SCNET_ACCESS_KEY": "your_access_key",
        "SCNET_SECRET_KEY": "your_secret_key",
        "SCNET_DEFAULT_REGION": "华东一区",
        "SCNET_DEFAULT_QUEUE": "normal"
      }
    }
  }
}
```

### 方式二：使用 Python 脚本

1. 克隆仓库
```bash
git clone <repository-url>
cd agent-cloud-interaction-protocol/mcp-server
```

2. 安装依赖
```bash
pip install -r requirements.txt
```

3. 配置环境变量或在 Trae 中直接配置

## 配置说明

支持三种配置方式（优先级从高到低）：

1. **Trae MCP 配置**: 在 `settings.json` 中配置 `env`
2. **环境变量**: 设置系统环境变量
3. **配置文件**: 创建 `mcp-config.json`

### 配置项

| 变量名 | 说明 | 必需 | 默认值 |
|--------|------|------|--------|
| `SCNET_USERNAME` | SCnet 用户名 | 是 | - |
| `SCNET_ACCESS_KEY` | Access Key | 是 | - |
| `SCNET_SECRET_KEY` | Secret Key | 是 | - |
| `SCNET_DEFAULT_REGION` | 默认区域 | 否 | - |
| `SCNET_API_TIMEOUT` | API 请求超时时间（秒） | 否 | 60 |
| `SCNET_TASK_TIMEOUT` | 任务提交超时时间（秒） | 否 | 90 |
| `SCNET_VERIFY_SSL` | 是否验证 SSL 证书 | 否 | false |
| `SCNET_JOB_PREFIX` | 任务名称前缀 | 否 | task_ |
| `SCNET_DEFAULT_NODES` | 默认节点数量 | 否 | 1 |
| `SCNET_DEFAULT_CPUS` | 默认每节点CPU数 | 否 | 8 |
| `SCNET_DEFAULT_MEMORY` | 默认内存 | 否 | 64GB |
| `SCNET_DEFAULT_GPU` | 默认GPU数量 | 否 | 1 |
| `SCNET_DEFAULT_DCU` | 默认DCU数量 | 否 | 0 |
| `SCNET_DEFAULT_WALL_TIME` | 默认运行时长 | 否 | 02:00:00 |

## 可用工具

详见 [mcp-server/README.md](mcp-server/README.md)

| 工具名 | 功能 |
|--------|------|
| `scnet_interaction_manual` | 交互手册 |
| `scnet_submit_task` | 提交任务 |
| `scnet_list_regions_tasks` | 查看区域任务列表 |
| `scnet_get_task_status` | 获取任务状态 |
| `scnet_cancel_task` | 取消任务 |
| `scnet_get_resources` | 查看资源状况 |
| `scnet_list_regions` | 获取授权分区列表 |

## 工具参数说明

### 1. scnet_interaction_manual
- **topic**: 主题，可选：overview(概览), auth(认证), task(任务管理), resources(资源查询), config(配置说明)，默认 overview

### 2. scnet_submit_task
- **command**: 要执行的命令行内容（对应 SCnet API 的 GAP_CMD_FILE 参数），例如：echo 'Hello SCnet!' && sleep 30。注意：command 参数直接作为命令执行，不需要使用 sbatch。如需换行，请使用 \n
- **nodes**: 节点数量，默认1
- **cpus_per_node**: 每节点CPU数，默认8（参考 oneskills 推荐配置）
- **memory**: 内存需求，如"8GB"，默认"64GB"（参考 oneskills 推荐配置）
- **gpu**: GPU数量，默认1（参考 oneskills 推荐配置）
- **dcu**: DCU数量，默认0
- **job_name**: 作业名称（可选，不填则自动生成）
- **node_string**: 指定节点（当指定该参数时，nodes必须为空）
- **nproc**: 总核心数（nproc和cpus_per_node选其一填写）
- **wall_time**: 最大运行时长（HH:MM:ss），例如：02:00:00，默认02:00:00
- **exclusive**: 是否独占节点，1为独占，0为非独占，默认0
- **multi_sub**: 作业组长度，建议为小于等于50的正整数
- **dependencies**: 软件依赖列表
- **queue**: 队列名称，如果没有明确提供，将自动选择可用队列
- `region`: 区域名称，如果没有明确提供，需要先查询有哪些可用区域，根据结果自主选择一个合适的区域

**任务提交成功返回信息：**
- `task_id`: 任务 ID
- `job_name`: 任务名称
- `work_dir`: 工作目录
- `std_out_path`: 标准输出文件路径
- `std_err_path`: 标准错误文件路径
- `region`: 区域名称
- `queue`: 队列名称

## SCnet API 字段说明

### mapAppJobInfo 作业对象字段

#### 必填字段

| 字段名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| `GAP_CMD_FILE` | string | 命令行内容（如需换行，请使用\n） | `sleep 500` |
| `GAP_NNODE` | string | 节点个数（当指定该参数时，GAP_NODE_STRING必须为""） | `1` |
| `GAP_SUBMIT_TYPE` | string | cmd（命令行模式） | `cmd` |
| `GAP_JOB_NAME` | string | 作业名称 | `STDIN_0910_094758` |
| `GAP_WORK_DIR` | string | 工作路径 | `/public/home/test/BASE/STDIN_1210_114429` |
| `GAP_QUEUE` | string | 队列名称 | `debug` |
| `GAP_WALL_TIME` | string | 最大运行时长（HH:MM:ss） | `24:00:00` |
| `GAP_APPNAME` | string | BASE（基础应用），支持填写具体的应用英文名称 | `BASE` |
| `GAP_STD_OUT_FILE` | string | 工作路径/std.out.%j | `/public/home/test/BASE/STDIN_1210_114429/std.out.%j` |
| `GAP_STD_ERR_FILE` | string | 工作路径/std.err.%j | `/public/home/test/BASE/STDIN_1210_114429/std.err.%j` |

#### 可选字段

| 字段名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| `GAP_NODE_STRING` | string | 指定节点（当指定该参数时，GAP_NNODE必须为""） | |
| `GAP_NPROC` | string | 总核心数（GAP_NPROC和GAP_PPN选其一填写） | |
| `GAP_PPN` | string | CPU核心/节点（GAP_NPROC和GAP_PPN选其一填写） | `1` |
| `GAP_NGPU` | string | GPU卡数/节点 | |
| `GAP_NDCU` | string | DCU卡数/节点 | |
| `GAP_JOB_MEM` | string | 每个节点内存值，单位为MB/GB | |
| `GAP_EXCLUSIVE` | string | 是否独占节点，1为独占，空为非独占 | |
| `GAP_MULTI_SUB` | string | 作业组长度，建议为小于等于50的正整数 | |

### 3. scnet_list_regions_tasks
- **region**: 区域名称，如果没有明确提供，需要先查询有哪些可用区域，根据结果自主选择一个合适的区域

### 4. scnet_get_task_status
- **task_id**: 任务ID
- **region**: 区域名称，如果没有明确提供，需要先查询有哪些可用区域，根据结果自主选择一个合适的区域

### 5. scnet_cancel_task
- **task_id**: 任务ID
- **region**: 区域名称，如果没有明确提供，需要先查询有哪些可用区域，根据结果自主选择一个合适的区域

### 6. scnet_get_resources
- **region**: 区域名称，如果没有明确提供，需要先查询有哪些可用区域，根据结果自主选择一个合适的区域

### 7. scnet_list_regions
- **无参数**

## 打包发布

```bash
cd mcp-server
python build.py
```

输出文件：
- `dist/scnet-mcp-server.exe` - 可执行文件
- `release/scnet-mcp-server-windows.zip` - 发布包

## 技术栈

- **Python 3.12+**
- **MCP (Model Context Protocol)**
- **PyInstaller** - 打包工具

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 许可证

MIT License

## 作者

- **作者**: chenyq
- **邮箱**: qingshende@foxmail.com