# AI Galaxy Compute MCP

智星云（AI Galaxy）OpenAPI v2 的安全封装，提供 CLI 和 stdio MCP 两种使用方式，供 Codex 或其他自动化 agent 在预算与安全边界内完成算力发现、询价、租用、连接和退租。

> 目标不是无约束消费，而是提供“实时发现 → 询价 → 预算校验 → 显式创建 → 接入 → 退租 → 磁盘清理”的受控自动化闭环。

## 特性

- **仅依赖 Python 标准库 + `mcp`**，无需额外运行时。
- **CLI 入口**：`ai-galaxy-compute`
- **MCP 入口**：`ai-galaxy-compute-mcp`（stdio）
- 支持 CPU 与 GPU 实例筛选、实时询价、创建前预算校验。
- 内置性价比评估：按"稠密 FP16 TFLOPS / 元每小时"对可租 GPU 排序，签约前先行比价。
- 支持实例原地升配（CPU/内存）、添加数据盘、调整带宽、重启、重置系统盘、续费。
- 支持"保留磁盘启动"：CPU 实例配环境 → 退租保留磁盘 → 按需启动 GPU/CPU 实例。
- 租用/退租为**两阶段操作**，必须显式确认，且使用一次性 HMAC 审批令牌。
- 默认不返回初始化密码、VNC/SSH 临时密码等敏感字段。
- 所有远程写操作**不自动重试**，避免网络抖动导致重复下单。
- 自动续费固定关闭；对时长、总价、小时价、GPU 数、磁盘、带宽均设有策略上限。

## 安全模型

1. **凭据来源**
   - 环境变量 `AI_GALAXY_ACCESS_KEY` / `AI_GALAXY_SECRET_KEY`；或
   - 权限为 `0600` 的本地 JSON 文件，路径通过 `AI_GALAXY_CREDENTIALS_FILE` 指定。
   - 不要把凭据写入 `.env`、计划文件、shell history 或提交到 Git。

2. **默认只读**
   - `auth`、`catalog`、`balance`、`instances`、`status`、`connect` 不会创建或修改资源。
   - `plan` / `plan_release` 只询价，不下单。

3. **写操作两阶段**
   - `plan` → 生成私有 `approval_token`。
   - `rent` 必须传入与计划文件完全匹配的 `approval_token`，且受预算上限保护。
   - 令牌由本机 `0600` 随机密钥用 HMAC 签发，计划文件被修改后立即失效。
   - 令牌消费记录持久化；创建请求超时后禁止复用，必须先 `instances` 对账。

4. **敏感信息脱敏**
   - `connect` 默认只返回 host、端口、用户名；只有 `--include-sensitive` 才返回密码。

## 安装

```bash
git clone <repo-url>
cd ai-galaxy-compute
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
```

依赖：Python >= 3.10，`mcp>=1.28,<2`。

## 配置凭据

推荐方式（MCP 必须使用此方式）：

```bash
mkdir -p ~/.config/ai-galaxy-compute
install -m 600 /dev/null ~/.config/ai-galaxy-compute/credentials.json
```

编辑文件，写入：

```json
{
  "access_key": "你的 AccessKey",
  "secret_key": "你的 SecretKey"
}
```

确认权限：

```bash
chmod 600 ~/.config/ai-galaxy-compute/credentials.json
export AI_GALAXY_CREDENTIALS_FILE="$HOME/.config/ai-galaxy-compute/credentials.json"
```

也可以临时使用环境变量（仅 CLI）：

```bash
export AI_GALAXY_ACCESS_KEY='...'
export AI_GALAXY_SECRET_KEY='...'
```

> 注意：通过 shell 输入会进入 history，生产环境建议使用凭据文件。

## CLI 使用

### 只读检查

```bash
ai-galaxy-compute auth
ai-galaxy-compute balance
ai-galaxy-compute catalog
ai-galaxy-compute instances
```

### 筛选并询价（不会创建实例）

先跑性价比评估（只读，不创建），选出 `gpu_type` 与卡数：

```bash
ai-galaxy-compute evaluate --gpu-count 1 --min-cpu 4 --min-memory 16
```

输出按 `tflops_per_yuan`（稠密 FP16 TFLOPS / 元每小时）降序排列，含每档的规格、单价、显存；未识别型号的 GPU 列在最后（`tflops_per_yuan=null`），并附纯 CPU 最低价选项与平台带宽/磁盘单价。然后用评估结果询价：

```bash
ai-galaxy-compute plan \
  --gpu-type 'GeForce RTX 4090' \
  --gpu-count 1 \
  --image ubuntu22_cuda12 \
  --hours 1 \
  --min-cpu 4 \
  --min-memory 16 \
  --max-hourly-price 2 \
  --max-total-price 2 > rental.plan.json
```

### 确认后租用

检查 `rental.plan.json`，复制其中的 `approval_token`：

```bash
ai-galaxy-compute rent \
  --plan-file rental.plan.json \
  --approval-token '<token>' \
  --max-total-price 2
```

### 查询与连接

```bash
ai-galaxy-compute status '<instance_name>'
ai-galaxy-compute connect '<instance_name>' --wait-seconds 600
```

### 退租

```bash
ai-galaxy-compute release-plan '<instance_name>' > release.preview.json
ai-galaxy-compute release \
  --preview-file release.preview.json \
  --approval-token '<token>'
```

> 平台提前退租不会自动释放保留磁盘；如果实例进入状态 `8`，仍需另行调用保留磁盘释放接口。当前版本不会声称状态 `8` 已完成清理。

### 实例规格升级（CPU/内存，原地升配）

```bash
ai-galaxy-compute resize-options '<instance_name>'            # 查看可升级规格
ai-galaxy-compute resize-plan '<instance_name>' \
  --new-spec ecs.c4.base --max-total-price 1 > resize.preview.json
ai-galaxy-compute resize \
  --preview-file resize.preview.json \
  --approval-token '<token>' --max-total-price 1
```

> 只能升级 CPU/内存，不可降配，也不能原地变更 GPU 数量；变更 GPU 请走"保留磁盘启动"。

### 添加数据盘

```bash
ai-galaxy-compute disk-plan '<instance_name>' --add-gb 20 --max-total-price 1 > disk.preview.json
ai-galaxy-compute disk-add --preview-file disk.preview.json --approval-token '<token>' --max-total-price 1
```

> 磁盘只能增加（单次最小 10GB，最多 16 块），系统盘不可变更。

### 调整网络带宽

```bash
ai-galaxy-compute bandwidth-plan '<instance_name>' --bandwidth 64 \
  --max-total-price 1 --max-bandwidth 128 > bandwidth.preview.json
ai-galaxy-compute bandwidth \
  --preview-file bandwidth.preview.json --approval-token '<token>' \
  --max-total-price 1 --max-bandwidth 128
```

> 0～32Mbps 免费；超出部分按单价每小时定时扣费。带宽上限 `MaxBandwidth` 由实例列表接口返回。

### 保留磁盘启动新实例（CPU 配环境 → GPU 干活）

实例到期或退租后若磁盘被保留（状态 `8`），可以用原磁盘按任意规格启动新实例：

```bash
ai-galaxy-compute boot-plan '<原 instance_name>' \
  --gpu-type 'GeForce RTX 4090' --gpu-count 1 --hours 2 \
  --max-hourly-price 2 --max-total-price 4 > boot.plan.json
ai-galaxy-compute boot --plan-file boot.plan.json --approval-token '<token>' --max-total-price 4
```

典型工作流：

1. 用 `--gpu-type CPU --gpu-count 0` 租一台便宜的纯 CPU 实例（`--due-mode 1`，到期保留磁盘）。
2. 在 CPU 实例上装好环境（无需为 GPU 空转付费）。
3. 退租 CPU 实例，磁盘保留（状态 `8`）。
4. 用 `boot-plan` / `boot` 从保留磁盘启动 GPU 实例开始训练。
5. 结束后再次退租保留磁盘，之后还能切回 CPU 规格继续维护环境。

### 重启 / 重置系统 / 到期策略

```bash
ai-galaxy-compute restart '<instance_name>'                       # 运行中重启
ai-galaxy-compute restart '<instance_name>' --from-shutdown       # 在系统内关机后启动
ai-galaxy-compute local-images '<instance_name>'                  # 查看可重置的镜像
ai-galaxy-compute reinit '<instance_name>' --image ubuntu22_cuda12  # 重置系统盘（数据盘保留）
ai-galaxy-compute due-mode '<instance_name>' --due-mode 1         # 1 到期保留磁盘，-1 到期释放
```

> KVM 实例没有"关机"接口：需要停止时在系统内部执行 shutdown，之后用 `--from-shutdown` 启动。

### 续费、备注与费用查询

```bash
ai-galaxy-compute renew-plan '<instance_name>' --hours 4 --max-total-price 8 > renew.preview.json
ai-galaxy-compute renew --preview-file renew.preview.json --approval-token '<token>' --max-total-price 8
ai-galaxy-compute note '<instance_name>' --note 'env-setup cpu node'
ai-galaxy-compute costs                            # 账户实例状态统计
ai-galaxy-compute costs '<instance_name>'          # 单实例费用汇总与明细
```

### 保留盘巡检与清理

保留磁盘（状态 8）按小时计费，退租后必须显式清理：

```bash
ai-galaxy-compute kept-disks                       # 列出所有保留中的磁盘及累计费用
ai-galaxy-compute cleanup-kept-disk '<instance_name>'   # 永久释放保留磁盘
```

> 建议每次会话开始/结束都跑一次 `kept-disks`：非空结果就是在空烧钱。
> `release` 退租后若实例进入状态 8，输出中会带 `warning` 字段提示。

## MCP 注册

```bash
codex mcp add aiGalaxyCompute \
  --env AI_GALAXY_CREDENTIALS_FILE=$HOME/.config/ai-galaxy-compute/credentials.json \
  --env AI_GALAXY_STATE_DIR=$HOME/.local/state/ai-galaxy-compute \
  -- $HOME/.local/bin/ai-galaxy-compute-mcp
```

提供的工具：

| 工具 | 作用 |
|---|---|
| `catalog` | 实时 CPU/GPU 规格、库存和价格；`inventory_counts` 是平台库存，`quote_candidate_counts` 是本地规格预检候选，`missing_enabled_spec_counts` 显示两者不一致；旧字段 `rentable_counts` 保持为候选列表 |
| `evaluate` | 性价比排序（FP16 TFLOPS/元每小时），签约前比价，只读；未进入报价计算的库存组合见 `unevaluated_inventory` |
| `balance` | 账户余额与额度 |
| `costs` | 费用查询：实例状态统计、单实例费用汇总与明细，只读 |
| `plan_rental` | 选择并询价，返回 `plan_id`，不创建实例 |
| `rent` | 消费一次性内部计划并创建实例，必须 `confirm=true` |
| `get_instance` | 等待运行并返回脱敏连接信息 |
| `plan_release` | 为本 MCP 创建的实例生成退租询价 |
| `release` | 消费退租计划，必须 `confirm=true` |
| `cleanup_kept_disk` | 永久释放保留磁盘，必须 `confirm=true` |
| `local_images` | 查询实例可用于重置系统的镜像 |
| `resize_options` | 查询实例可升级的规格（CPU/内存） |
| `plan_resize` | 升配询价，返回 `plan_id`，不改动实例 |
| `resize` | 消费升配计划执行原地升级，必须 `confirm=true` |
| `plan_disk_add` | 添加数据盘询价，不改动实例 |
| `disk_add` | 消费加盘计划，必须 `confirm=true` |
| `plan_bandwidth` | 带宽调整询价（0~32Mbps 免费），不改动实例 |
| `set_bandwidth` | 消费带宽计划执行调整，必须 `confirm=true` |
| `plan_kept_boot` | 从保留磁盘启动新实例询价（可换 GPU 数量或纯 CPU），不创建 |
| `kept_boot` | 消费保留盘启动计划并创建实例，必须 `confirm=true` |
| `restart_instance` | 重启实例；`from_shutdown=true` 用于系统内关机后的启动 |
| `reinit_instance` | 重置系统盘为新镜像（数据盘保留），必须 `confirm=true` |
| `set_due_mode` | 设置到期处理：`1` 保留磁盘，`-1` 到期释放，必须 `confirm=true` |
| `plan_renew` | 续费询价，不扣费 |
| `renew` | 消费续费计划，必须 `confirm=true` |
| `set_note` | 设置实例备注（≤25 字），用于标记用途 |
| `kept_disks` | 巡检保留中的磁盘（状态 8）及累计费用，会话开始/结束时必查 |

`plan_rental` 默认 `kind="cheapest"` 且不传 GPU 参数时选择 CPU；GPU
询价必须显式传 `kind="gpu"`、`gpu_type` 和正数 `gpu_count`。冲突参数会直接失败，
不会被静默改写成 CPU 计划。缺少启用规格的库存组合只会进入诊断字段，不会被伪装成可下单。

## 测试

单元测试不使用真实凭据、不访问网络、不产生费用：

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
```

线上测试建议按 `auth -> catalog -> instances -> plan` 顺序进行；除非明确决定产生费用，不运行 `rent`。

## 项目结构

```text
src/ai_galaxy_compute/
├── client.py      # 签名 HTTP 客户端和 OpenAPI 端点
├── broker.py      # 规格选择、性价比评估、预算策略、询价、租用、变更
├── gpu_perf.py    # GPU 性能对照表（近似公开参数，用于性价比排序）
├── cli.py         # 命令行入口
├── mcp_server.py  # FastMCP 工具定义
├── plan_store.py  # 私有计划、文件锁、ownership 和状态迁移
├── ledger.py      # HMAC 审批令牌与一次性消费记录
├── signing.py     # 请求签名
├── transport.py   # multipart/form-data HTTP 传输
└── errors.py      # 异常类型

tests/             # 单元测试
```

## 接口依据

- 基础地址：`https://app.ai-galaxy.cn`
- 所有请求：`POST multipart/form-data`
- 签名：非空参数按参数名升序拼接，追加 `&secret=<SecretKey>` 后计算 MD5
- 文档入口：<https://s.apifox.cn/b0fc397f-c455-4c9a-9d82-875fc48ae106/doc-5644954>

## License

MIT

## AutoDL MCP

同一发行包还提供独立的 AutoDL 容器实例 Pro API MCP：

```bash
autodl-compute catalog
autodl-compute-mcp
```

配置、工具边界和凭据说明见 [`docs/AUTODL_MCP.md`](docs/AUTODL_MCP.md)。AutoDL 当前未提供文档化的创建前报价接口，因此该 MCP 将租用标记为 `UNQUOTED`，必须显式确认后才能创建。