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 数、磁盘、带宽均设有策略上限。

安全模型

凭据来源
- 环境变量 AI_GALAXY_ACCESS_KEY / AI_GALAXY_SECRET_KEY；或
- 权限为 0600 的本地 JSON 文件，路径通过 AI_GALAXY_CREDENTIALS_FILE 指定。
- 不要把凭据写入 .env、计划文件、shell history 或提交到 Git。
默认只读
- auth、catalog、balance、instances、status、connect 不会创建或修改资源。
- plan / plan_release 只询价，不下单。
写操作两阶段
- plan → 生成私有 approval_token。
- rent 必须传入与计划文件完全匹配的 approval_token，且受预算上限保护。
- 令牌由本机 0600 随机密钥用 HMAC 签发，计划文件被修改后立即失效。
- 令牌消费记录持久化；创建请求超时后禁止复用，必须先 instances 对账。
敏感信息脱敏
- connect 默认只返回 host、端口、用户名；只有 --include-sensitive 才返回密码。

安装

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 必须使用此方式）：

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

编辑文件，写入：

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

确认权限：

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

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

export AI_GALAXY_ACCESS_KEY='...'
export AI_GALAXY_SECRET_KEY='...'

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

CLI 使用

只读检查

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

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

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

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

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

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：

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

查询与连接

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

退租

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/内存，原地升配）

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 请走"保留磁盘启动"。

添加数据盘

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 块），系统盘不可变更。

调整网络带宽

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），可以用原磁盘按任意规格启动新实例：

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

典型工作流：

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

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

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 启动。

续费、备注与费用查询

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）按小时计费，退租后必须显式清理：

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

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

MCP 注册

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 计划。缺少启用规格的库存组合只会进入诊断字段，不会被伪装成可下单。

测试

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

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

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

项目结构

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：

autodl-compute catalog
autodl-compute-mcp

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