Metadata-Version: 2.4
Name: dma-cli
Version: 0.1.2
Summary: DMA 任务提交命令行工具
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: pyyaml

# DMA CLI —— 任务提交工具

深度挖掘算法（DMA）网页外的命令行提交工具，用于提交单个或批量任务。

## 安装

```bash
# 从 PyPI 安装
pip install dma-cli
dma --help

# 安装后 dma 命令即可全局使用
dma --help
```

## 配置

PyPI 安装同时包含配置模板和 `input/` 样例，位于当前 Python 环境的 `share/dma-cli/`。
可在空的工作目录中运行以下命令，将模板和样例复制到当前目录：

```bash
python - <<'PY'
import shutil
import sysconfig
from pathlib import Path

examples = Path(sysconfig.get_path("data")) / "share" / "dma-cli"
for name in ("config.example.yaml", "job.example.json", "batch.example.json"):
    shutil.copy2(examples / name, name)
shutil.copytree(examples / "input", "input")
PY
```

复制模板并填写：

```bash
cp config.example.yaml config.yaml
```

`config.yaml` 关键项：

```yaml
base_url: https://szc.test.dp.tech
auth:
  email: ""          # 验证码登录邮箱（留空则必须填 token）
  captcha: ""        # 留空，执行 dma login 时交互输入验证码
  token: ""          # 直接配 token（优先于 email 登录）
  uexid: ""          # 留空从 JWT 自动解析为 fe_<userId>
  user_id: ""        # 留空从 JWT 自动解析
defaults:
  name_prefix: "cli-job"
  max_run_time: 15
  max_run_time_unit: d
  concurrency: 5
```

**配置优先级**：CLI 参数 > 环境变量（`DMA_BASE_URL` / `DMA_TOKEN`）> `config.yaml` > 内置默认。
当前项目持久化于 `~/.dma_cli/session.json`，由 `project use` 写入、`submit` 读取。
机型与镜像不持久化，每次通过参数或 JSON 配置文件传入。

**安全**：`config.yaml` 与 `~/.dma_cli/` 不入库（仅提交 `config.example.yaml`），禁止提交真实 JWT。

## 入口

```bash
# 方式一：如果您已经执行了 pip install .，则可以全局直接使用：
dma <cmd> ...

# 方式二：如果您未安装，可以直接通过 python 入口模块运行：
python -m dma_cli <cmd> ...
```

所有命令支持 `-h`：

```bash
dma --help
dma job submit --help
```

## 命令

### login —— 验证码登录

```bash
dma login
dma login --email you@example.com
```

`auth.captcha` 留空时，登录会提示 `请输入邮箱验证码:`，输入本次验证码后提交。
验证码不会保存到配置文件或登录缓存。若配置中已填写 `auth.captcha`，则使用该值；
已有配置中的旧验证码请清空，以启用交互输入。输入为空或取消输入时，不发送登录请求。
此命令只校验输入的验证码，不会自动发送验证码邮件。

解析 JWT 缓存 `token` / `user_id` / `uexid` 到 `~/.dma_cli/credentials.json`。也可跳过登录，直接在 `config.yaml` 填 `token`。

### whoami —— 查看当前状态

```bash
dma whoami
```

显示 base_url、当前用户、当前项目。

### project —— 项目管理

先查询当前账号可访问的项目，根据项目名称找到自己的 `projectId`，再设为当前项目：

```bash
dma project list             # 列出 projectId | name
dma project use <你的项目ID>   # 替换为上一步查到的 projectId
dma project current          # 确认当前项目 ID 和名称
```

`<你的项目ID>` 是占位符，执行前请替换为列表中你要使用的数字 ID，不要输入尖括号。
当前项目会保存在本机，后续提交任务时省略 `--project_id` 或设置为 `0` 即使用该项目；
JSON 配置中的 `"project_id": 0` 含义相同。`0` 表示使用当前项目，不是真实项目 ID，首次提交前需先完成项目选择。
如需单次提交到其他项目，可传入 `--project_id <你的项目ID>`，不会改变已保存的当前项目。

### sku —— 机型查询

```bash
dma sku list --kind cpu   # 列 skuId|skuName|cpu|memory|gpuModel|gpuNum|hasStock
```

> 仅查询参考，不持久化。提交任务时通过 `--machine_type` 参数传入。

### image —— 镜像查询

```bash
dma image list   # 列出镜像（公共+私有合并，含 url 列）
```

> 仅查询参考，不持久化。输出 `url` 列可直接填入 `--image_address`。

### job submit —— 提交任务

提交任务，支持两种入参方式：

**方式一：JSON 配置文件**

```bash
dma job submit -i job.example.json
```

**方式二：CLI 参数**

```bash
dma job submit \
  --machine_type c2_m2_cpu \
  --image_address ubuntu:22.04-py3.10-terminal-20260916 \
  --project_id 0 \
  --command "python calc.py" \
  --job_name my-job
```

**完整参数列表**：

| 参数 | 缩写 | 说明 |
|---|---|---|
| `--config_file` | `-i` | JSON 配置文件路径 |
| `--input_directory` | — | 输入文件目录 |
| `--project_id` | — | 项目 ID（0=用当前选择） |
| `--job_name` | `-n` | 任务名称 |
| `--image_address` | `-m` | 镜像地址（自动匹配） |
| `--machine_type` | `-t` | 机器类型名（自动匹配） |
| `--command` | `-c` | 执行命令 |
| `--max_run_time` | — | 最大运行时间（分钟） |
| `--count` | — | 批量提交任务数 |
| `--concurrency` | — | 批量并发数 |
| `--batch_file` | — | 批量任务 JSON 数组文件 |
| `--batch_input_dir` | — | 批量目录扫描路径 |
| `--dry_run` | — | 只打印 snapshot body |
| `--poll` | — | 提交后轮询状态 |

## 批量提交

### 方式一：--count（相同参数）

```bash
dma job submit \
  --machine_type c2_m2_cpu \
  --image_address ubuntu:22.04-py3.10-terminal-20260916 \
  --command "python calc.py" \
  --count 5 \
  --concurrency 5
```

### 方式二：--batch_file（差异化配置）

```bash
# batch.json 格式：
# [
#   {"job_name": "job-001", "machine_type": "c2_m2_cpu", ...},
#   {"job_name": "job-002", "machine_type": "c4_m8_cpu", ...}
# ]

dma job submit --batch_file batch.example.json --concurrency 3
```

### 方式三：--batch_input_dir（目录扫描）

```bash
# 每个子目录作为一个任务的输入
dma job submit \
  --batch_input_dir ./input \
  --machine_type c2_m2_cpu \
  --image_address ubuntu:22.04-py3.10-terminal-20260916 \
  --command "python calc.py" \
  --concurrency 5
```

## 典型流程

```bash
# 1. 配置
cp config.example.yaml config.yaml
# 编辑 config.yaml 填入 token

# 2. 查看状态
dma whoami

# 3. 查询并选择自己的项目（将占位符替换为列表中的 projectId，不保留尖括号）
dma project list
dma project use <你的项目ID>
dma project current

# 4. 查询机型和镜像
dma sku list --kind cpu
dma image list

# 5. 提交任务
dma job submit -i job.example.json

# 6. 批量提交
dma job submit --batch_file batch.example.json
```
