# GPU-SCOUT-001 · GPU自动发现+一键部署模块 · 铸渊开发任务单

```jsx
HLDP://shuangyan/module/GPU-SCOUT-001 · 2026-05-12
├── 提出人: 之之·DEV-004
├── 记录人: 霜砚·ICE-SY-01
├── 开发人: 铸渊·ICE-ZY-01
└── 状态: ⏳ 待铸渊接单
```

## 一、为什么要做这个模块

> 之之原话（2026-05-12）：
> 

> 「要跑通deploy，需要GPU开机。但我们是共享GPU，关机后就被别人占。没有稳定GPU，就无法测试部署流程。与其被动等GPU，不如先造工具——自动发现可用GPU，随时主动抢占。」
> 

**根本矛盾：** 部署流程依赖稳定GPU，但共享GPU随时消失

**解法：** GPU自动发现模块 → 被动变主动 → 随时知道哪台GPU可用 → 立即部署

---

## 二、模块功能定义

### 核心能力（MVP）

- [ ]  **平台扫描**：查询 AutoDL + compshare 账号下所有 GPU 实例状态
- [ ]  **健康检测**：SSH 连通性 + GPU 可用性验证
- [ ]  **信息输出**：返回可用实例的 Host / Port / User / 显存 / 平台
- [ ]  **一键部署**：选定实例后，自动更新 GitHub Secrets → 触发 `guanghulab-core` deploy 工作流

### 后续扩展（非MVP）

- 多平台自动比价（AutoDL / compshare / 恒源云 / 智星云）
- 自动抢占：发现有货立即开机并部署
- 状态写回 Notion
- 定时轮询 + 通知

---

## 三、技术方案

### 3.1 API 文档

| 平台 | API 文档 | SDK |
| --- | --- | --- |
| AutoDL | `https://api.autodl.com` · 容器实例Pro API | 无官方SDK · 直接HTTP |
| compshare | `https://www.compshare.cn/docs/gpus/operationexample` | Python / Go / Java SDK |

**AutoDL 关键接口：**

- 获取实例列表：`GET /api/v1/dev/instance/list`（需 Authorization token）
- 查询GPU库存：`POST /api/v1/dev/machine/region/gpu_stock`

**compshare 关键接口：**

- 参考 GitHub 示例：`github.com/ucloud/compshare-developer-examples`
- 需要 compshare API Key

### 3.2 仓库规划

- **仓库位置**：Gitea（[guanghulab.com](http://guanghulab.com) · Forgejo）新建独立仓库
- **建议仓库名**：`gpu-scout`
- **理由**：模块独立、可大可小、后续可对接多平台

### 3.3 部署触发逻辑

```jsx
gpu-scout 运行流程：

① 调 AutoDL API → 获取在线实例列表
    ↓ 没有在线实例
② 调 compshare API → 获取在线实例列表
    ↓ 找到可用实例
③ SSH 健康检测（连通 + python3 + GPU显存）
    ↓ 通过
④ 更新 guanghulab-core GitHub Secrets：
   ZY_DEPLOY_SSH_SG_GPU_001_HOST
   ZY_DEPLOY_SSH_SG_GPU_001_PORT
   ZY_DEPLOY_SSH_SG_GPU_001_USER
   ZY_DEPLOY_SSH_SG_GPU_001_PRIVATE_KEY
    ↓
⑤ 触发 guanghulab-core deploy 工作流
    ↓
⑥ 返回结果（成功 / 失败 + 原因）
```

---

## 四、铸渊开发说明

### 4.1 前置条件（之之需要提供）

| 所需信息 | 来源 | 状态 |
| --- | --- | --- |
| AutoDL API Token | AutoDL控制台 → 账号设置 → API Token | ⏳ 之之获取中 |
| compshare API Key | compshare控制台 → API管理 | ⏳ 之之获取中（冰朔昨天注册了账号） |
| GitHub PAT（有repo权限） | 用于更新Secrets + 触发工作流 | ✅ 已有（ZY_GITHUB_PAT） |
| Gitea 新仓库 URL | [guanghulab.com](http://guanghulab.com) 上新建 `gpu-scout` | ⏳ 待建 |

### 4.2 MVP 交付物

```jsx
gpu-scout/
├── src/
│   ├── autodl.js       ← AutoDL API 查询封装
│   ├── compshare.js    ← compshare API 查询封装
│   ├── health.js       ← SSH 健康检测
│   ├── deploy.js       ← 更新Secrets + 触发工作流
│   └── index.js        ← 主入口（CLI）
├── config/
│   └── platforms.json  ← 平台配置（API端点 + 认证方式）
├── .env.example
├── package.json
└── README.md
```

### 4.3 调用方式（目标）

```bash
# 扫描可用GPU
node index.js scan

# 扫描 + 自动部署
node index.js deploy --target autodl

# 只更新Secrets，不触发部署
node index.js update-secrets --host xxx --port xxx
```

---

## 五、当前阻塞项

1. ⏳ **AutoDL API Token** — 之之去控制台获取
2. ⏳ **compshare API Key** — 冰朔账号下获取
3. ⏳ **Gitea 新建 `gpu-scout` 仓库** — 之之在 [guanghulab.com](http://guanghulab.com) 建
4. ⏳ **铸渊接单** — 以上三项就绪后唤醒铸渊

---

## 六、关联页面

- 主控台：ZZ-DEPLOY-001
- 栖渊工作流仓库：`qinfendebingshuo/guanghulab-core`
- GPU信息记录：个人线系统恢复锚点（AutoDL SSH信息）

---

*建档人：霜砚·ICE-SY-01 · 2026-05-12 · 之之提出 · 铸渊待接单*