# agent-cloud-interaction-protocol

**Repository Path**: alohomoraH/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**: 2
- **Created**: 2026-04-27
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Cloud Interaction Protocol

智能体与云平台交互协议实验仓库。当前已将 SCnet 实现收敛为“可复用 runtime core + 薄入口适配层”的结构，既能作为 MCP 服务使用，也能直接以源码形式被其他 agent/CLI/Gateway 复用。

## 当前形态

仓库现在分为三层：

1. `scnet_client/`
   运行时内核，负责认证、区域匹配、队列缓存、任务认证缓存、文件缓存持久化。
2. `cloud-api/scnet-api/`
   SCnet 底层 API 与 `SCnetAdapter` 实现。
3. `mcp-server/`
   MCP 适配层，负责配置加载、tool schema、handler 绑定和响应封装。

对应关系如下：

```text
Entry Points
├── mcp-server/scnet_mcp_server.py
├── .tmp/scnet_live_smoke.py
└── future: CLI / Gateway / other agent runtimes
          │
          ▼
Runtime Core
├── scnet_client/client.py
├── scnet_client/session.py
└── scnet_client/cache.py
          │
          ▼
SCnet Adapter / API
└── cloud-api/scnet-api/
```

## 目录

```text
agent-cloud-interaction-protocol/
├── scnet_client/             # SCnetClient / SCnetSession / FileCacheStore
├── scnet_smoke_support.py    # live smoke 共用装配与脱敏输出
├── cloud-api/
│   └── scnet-api/            # SCnet API 与适配器
├── mcp-server/
│   ├── scnet_mcp_server.py   # MCP 薄入口
│   ├── runtime_setup.py      # 配置读取、路径引导、runtime 初始化
│   ├── tool_catalog.py       # Tool schema 与手册文案
│   ├── tool_dispatch.py      # 表驱动 handler 绑定
│   ├── task_tools.py         # 任务/资源/日志 handlers
│   ├── file_tools.py         # 文件 handlers
│   ├── tool_utils.py         # 响应与认证错误辅助
│   └── README.md             # MCP 使用说明
├── .tmp/
│   ├── scnet_live_smoke.py        # 统一 live smoke 入口
│   ├── dispatcher_live_smoke.py   # 兼容包装
│   └── task_tools_live_smoke.py   # 兼容包装
├── examples/
│   └── scnet_client_quickstart.py # 不经过 MCP 的源码示例
├── tests/
│   ├── test_mcp_tooling.py      # MCP/runtime/tooling 回归测试
│   └── test_scnet_client_core.py # scnet_client 核心缓存与匹配测试
├── scnet_live_probe.py       # 真实任务链路探测脚本
└── scnet_file_probe.py       # 真实文件接口探测脚本
```

## 能力范围

- AK/SK 认证，多区域 token 缓存
- 区域与队列模糊匹配
- 任务提交、状态查询、取消、日志下载
- 授权区域与资源查询
- 远程文件上传、下载、创建、删除、移动、复制、重命名
- 认证、区域、队列、任务元信息持久化缓存
- 统一 live smoke 和本地回归测试

## 为什么改成 client core

这次重构的目标不是继续堆 MCP 工具，而是把 SCnet 的真实运行能力下沉到 `scnet_client`：

- MCP 不再承载认证和缓存的核心逻辑，只做薄适配。
- 以后做 CLI、Gateway、Agent SDK、批处理 worker 时，可以直接复用 `scnet_client`。
- 授权文件和 token 缓存仍然保留，且不需要每次请求重新授权。
- 单次请求是否过长，取决于上层入口；runtime core 本身已经支持将认证、区域、队列、任务信息分离缓存。

## 配置

优先级：

1. 环境变量
2. `scnet_config.json`

关键变量：

| 变量名 | 说明 |
| --- | --- |
| `SCNET_USERNAME` | SCnet 用户名 |
| `SCNET_ACCESS_KEY` | Access Key |
| `SCNET_SECRET_KEY` | Secret Key |
| `SCNET_DEFAULT_REGION` | 默认区域 |
| `SCNET_QUEUE` | 默认队列 |
| `SCNET_CACHE_FILE` | 运行时缓存文件路径 |
| `SCNET_REGION_AUTH_CACHE_TTL` | 区域授权缓存 TTL（秒） |
| `SCNET_CLUSTER_CACHE_TTL` | cluster 信息缓存 TTL（秒） |
| `SCNET_QUEUE_CACHE_TTL` | queue 信息缓存 TTL（秒） |

`scnet_config.json` 支持放在：

- `mcp-server/scnet_config.json`
- 当前可执行文件目录
- `~/scnet_config.json`
- `~/.config/scnet-mcp/scnet_config.json`

默认缓存文件：

```text
~/.config/scnet-mcp/scnet_auth_cache.json
```

缓存中会持久化：

- 已授权区域列表
- 区域 token
- 区域 URL 与 homePath
- 区域队列信息
- cluster 信息及刷新时间戳
- cluster/job manager 映射
- 任务对应的 region/token/stdout/stderr 元信息

当前实现会优先用这些持久化缓存做 warm start：

- 进程重启后优先复用本地 token/session cache
- adapter 会从缓存回填 region URL，避免一启动就重复拉授权区域
- cluster / queue 查询会受 TTL 控制，未过期时直接复用缓存

## 源码直接测试

当前推荐直接在仓库根目录使用源码和虚拟环境测试，不需要先打包安装。

### 1. 安装依赖

```bash
./.venv/bin/pip install -r mcp-server/requirements.txt
```

### 2. 本地回归测试

```bash
PYTHONPYCACHEPREFIX=/tmp/codex-pyc ./.venv/bin/python -m unittest discover -s tests
```

### 3. 统一 live smoke

```bash
./.venv/bin/python .tmp/scnet_live_smoke.py \
  --mode dispatcher \
  --username "$SCNET_USERNAME" \
  --ak "$SCNET_ACCESS_KEY" \
  --sk "$SCNET_SECRET_KEY" \
  --region "核心节点" \
  --queue "hpctest02"
```

该脚本会串行验证：

1. 获取授权区域
2. 获取资源
3. 提交任务
4. 查询任务状态
5. 下载日志
6. 取消任务

兼容入口仍保留：

```bash
./.venv/bin/python .tmp/dispatcher_live_smoke.py ...
./.venv/bin/python .tmp/task_tools_live_smoke.py ...
```

## 直接作为源码调用

不经过 MCP 时，可以直接复用 `scnet_client`：

```python
import asyncio
import sys
from pathlib import Path

repo_root = Path.cwd()
sys.path.extend(
    [
        str(repo_root / "mcp-server"),
        str(repo_root / "cloud-api"),
        str(repo_root / "cloud-api" / "scnet-api"),
    ]
)

from scnet_client import FileCacheStore, SCnetClient, SCnetSession
from runtime_setup import SCnetMCPConfig

async def main():
    config = SCnetMCPConfig()
    session = SCnetSession(FileCacheStore())
    client = SCnetClient(config, session=session)

    startup_ok = await client.startup()
    auth_ok, token = await client.ensure_authenticated("核心节点")
    region_api = client.ensure_region_authorized("核心节点", token)
    resources = region_api.query_cluster_info(token)
    print(resources)

asyncio.run(main())
```

如果需要现成的本地示例，可直接参考：

- [examples/scnet_client_quickstart.py](/Users/chenyq/code/agent-cloud-interaction-protocol/examples/scnet_client_quickstart.py)
- [scnet_live_probe.py](/Users/chenyq/code/agent-cloud-interaction-protocol/scnet_live_probe.py)
- [scnet_file_probe.py](/Users/chenyq/code/agent-cloud-interaction-protocol/scnet_file_probe.py)

直接运行示例：

```bash
./.venv/bin/python examples/scnet_client_quickstart.py
```

## 作为 MCP 使用

MCP 详细配置、可用 tools 和打包说明见 [mcp-server/README.md](mcp-server/README.md)。

如果只想以源码方式启动 MCP：

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

## 当前验证状态

这轮重构后已验证：

- 本地 `py_compile` 通过
- `python -m unittest discover -s tests` 通过
- 统一 dispatcher live smoke 通过真实 SCnet
- 文件接口已经补充回归测试，并保留独立 probe 脚本做真实联调

## 后续扩展方向

- 基于 `scnet_client` 增加 CLI 入口
- 做面向智能体的 Gateway / service 进程
- 把更多 SCnet 能力从 MCP 层进一步下沉到 runtime core

## License

MIT