qzcli - 启智平台任务管理 CLI

一个类似 kubectl / docker 风格的启智平台命令行工具，把资源查询、任务提交、任务管理、日志查看和 MCP/agent 工作流收敛到 CLI 里完成。

项目链接

• Release: https://github.com/tianyilt/qzcli_tool/releases/tag/v0.2.0
• Changelog: CHANGELOG.md
• Issues: https://github.com/tianyilt/qzcli_tool/issues
• License: MIT

特性

• 一键登录: qzcli login 通过 CAS 认证自动获取 cookie，无需手动复制
• 资源发现: qzcli res -u 聚合历史任务、workspace 资源接口，自动发现工作空间、计算组、规格等资源并本地缓存
• 节点查询: qzcli avail 查询各计算组空余节点，支持低优任务统计和 cookie 失效自动刷新
• 交互式提交: qzcli create -i 提供层级式选择界面，缺少快照时按需预加载
• 任务列表: 美观的卡片式显示，完整 URL 方便点击
• 日志查看: qzcli logs <job-id> 直连平台日志接口，支持 tail、follow、raw/json 输出
• 状态监控: watch 模式实时跟踪任务进度

快速查看资源：

qzcli login -u 用户名 -p 密码 && qzcli avail

分布式
  计算组                          空节点     总节点     空GPU GPU类型     
  -----------------------------------------------------------------
  某gpu2-3号机房-2                    3      xxx  x/xxx 某gpu2      
  某gpu2-3号机房                      0      xxx   x/xxx 某gpu2      
  某gpu2-2号机房                      0      xxx   x/xxx 某gpu2      
  cuda12.8版本某gpu1                 0      xxx  x/xxx 某gpu1   

安装

cd qzcli_tool
pip install -r requirements.txt
pip install -e .

快速开始

# 1. 登录（自动获取 cookie）
qzcli login

# 2. 更新资源缓存（首次使用强烈建议执行，自动发现所有可访问的工作空间）
qzcli res -u

# 3. 查看空余节点
qzcli avail

# 4. 查看运行中的任务
qzcli ls -c -r

如果没有显式设置 QZCLI_ENV_FILE，qzcli 会默认尝试从 ~/.qzcli/.env 读取 CAS 凭据；如果你的凭据文件在别处，先导出 QZCLI_ENV_FILE=/path/to/.env：

cat > ~/.qzcli/.env <<'EOF'
QZCLI_USERNAME="your_username"
QZCLI_PASSWORD='your_password'
EOF

qzcli login

重要:

• 首次使用建议执行 qzcli res -u，会发现并缓存所有你有权限访问的工作空间，非交互式 create / 按名称解析资源时会更稳定
• 如果遇到 未找到名称为 'xxx' 的工作空间 错误，说明缓存需要更新，请重新执行 qzcli res -u
• 新加入的工作空间/项目需要重新执行 qzcli res -u 来更新缓存
• qzcli create -i 在没有本地交互快照时会自动按需预加载，不要求你先手动执行 qzcli avail

MCP Server

如果你想在 Codex 或 Claude 里直接调用启智平台相关能力，可以把 qzcli 作为 MCP 工具接进去。

# 1. 进入项目目录（自行替换 xxxxx）
cd /inspire/xxxxx/qzcli_tool

# 2. 安装
python -m pip install -e .

安装完成后，可以先检查命令是否已经可用：

which qzcli-mcp

接入 Codex

执行下面两条命令即可：

codex mcp add qzcli -- qzcli-mcp
codex mcp list

如果你想固定使用绝对路径，也可以这样写：

codex mcp add qzcli -- /root/miniconda3/bin/qzcli-mcp （根据 which qzcli-mcp 的返回地址改)

接入 Claude Code

执行下面两条命令即可：

claude mcp add qzcli -- qzcli-mcp
claude mcp list

如果你想固定使用绝对路径，也可以这样写：

claude mcp add qzcli -- /root/miniconda3/bin/qzcli-mcp （根据 which qzcli-mcp 的返回地址改)

使用说明

正常使用时，不需要你手动先运行 qzcli-mcp。

把它加到 Codex 或 Claude 后，客户端会自动调用它，你手动运行 qzcli-mcp，一般只是为了排查问题，你可以直接这样告诉你的 Codex 或者 Claude Code：

开工了，我要登陆启智平台！

帮我看下现在有多少张华为Atlas950是空闲的

帮我看下现在有多少台某型号卡是空闲的，我要整台的8卡

即便数字部某天又在生产环境修改了返回值字段，模型也能根据原始返回JSON快速判断现在哪个字段代表原来的意图，无需手动再次重装qzcli工具（依赖于模型的上下文理解能力）

常见排障

• 如果提示找不到 qzcli-mcp，通常重新执行一次安装即可：

cd /inspire/xxxxx/qzcli_tool
python -m pip install -e .

• 如果已经注册过但客户端里看不到，先执行一次 codex mcp list 或 claude mcp list 确认是否注册成功
• 如果你手动运行 qzcli-mcp 后立刻报错，先修复启动报错，再回到客户端里接入

推荐工作流

每日使用

# 登录并查看资源
qzcli login && qzcli avail

# 输出示例：
# 示例工作空间
#   计算组                          空节点    总节点 GPU类型     
#   -----------------------------------------------------
#   训练组-A                            4      xxx GPU-A      
#   训练组-B                            1     xxx GPU-B      
#   ...
# 训练任务
#   计算组-C                            1    xxx GPU-C      

提交任务前

# 找有 4 个空闲节点的计算组
qzcli avail -n 4 -e

# 如果需要考虑低优任务占用的节点（较慢，但更准确地反映潜在可用资源）
qzcli avail --lp -n 4

# 如果开启了 --lp (low priority) 模式，建议配合 -w 指定工作空间以加快速度
qzcli avail --lp -w 分布式 -n 4

查看任务

# 查看所有工作空间运行中的任务
qzcli ls -c --all-ws -r

# 查看指定工作空间
qzcli ls -c -w 分布式 -r

命令参考

认证命令

命令	说明	示例
login	CAS 登录获取 cookie	qzcli login
cookie	手动设置 cookie	qzcli cookie -f cookies.txt

# 交互式登录
qzcli login

# 带参数登录
qzcli login -u 学工号 -p 密码

# 脚本里从 stdin 读密码
echo 'your_password' | qzcli login -u 学工号 --password-stdin

# 查看当前 cookie
qzcli cookie --show

# 清除 cookie
qzcli cookie --clear

资源管理

命令	别名	说明
resources	res, lsws	管理工作空间资源缓存
avail	av	查询计算组空余节点

# 列出已缓存的工作空间
qzcli res --list

# 更新所有工作空间的资源缓存
qzcli res -u

# 更新指定工作空间
qzcli res -w 分布式 -u

# 给工作空间设置别名
qzcli res -w ws-xxx --name 我的空间

# 查看空余节点（默认不包含低优任务统计，速度较快）
qzcli avail

# 查看空余节点（包含低优任务统计，即：空节点 + 低优任务占用的节点）
qzcli avail --lp

# 只查看指定工作空间
qzcli avail -w 分布式

# 只看某个计算组
qzcli avail -w 分布式 -g lcg-xxx

# 显示空闲节点名称
qzcli avail -w 分布式 -v

# 找满足 N 节点需求的计算组
qzcli avail -n 4

# 导出为脚本可用格式
qzcli avail -n 4 -e

如果本地 cookie 已过期，但你已经通过 shell 环境变量、QZCLI_ENV_FILE 指向的 .env（默认 ~/.qzcli/.env）或 ~/.qzcli/config.json 保存了 CAS 凭据，qzcli avail 会自动刷新 cookie 后继续查询。

任务列表

命令	别名	说明
list	ls	列出任务

# Cookie 模式（从 API 获取）
qzcli ls -c -w 分布式       # 指定工作空间
qzcli ls -c --all-ws        # 所有工作空间
qzcli ls -c -w 分布式 -r    # 只看运行中
qzcli ls -c -w 分布式 -n 50 # 显示 50 条

# 本地模式（从本地存储）
qzcli ls                    # 默认列表
qzcli ls -r                 # 运行中
qzcli ls --no-refresh       # 不刷新状态

创建任务

命令	别名	说明
create	create-job	创建并提交 GPU 分布式训练任务
hpc		提交 HPC/CPU 任务（Slurm，需 cookie 认证）
batch		从 JSON 配置文件批量提交任务

# 交互式提交：仅补齐未显式传入的参数
qzcli create -i

# 只针对某个 workspace 按需预加载交互快照
qzcli create -i -w "我的工作空间"

# 使用名称（从 qzcli res 缓存解析）
qzcli create \
  --name "my-training-job" \
  --command "bash /path/to/script.sh" \
  --workspace "我的工作空间" \
  --project "我的项目" \
  --compute-group "我的计算组" \
  --image registry.example.com/team/train-image:latest \
  --instances 4 \
  --priority 10

# 使用 ID
qzcli create \
  --name "my-training-job" \
  --command "bash /path/to/script.sh" \
  --workspace ws-<workspace_id> \
  --project project-<project_id> \
  --compute-group lcg-<compute_group_id> \
  --spec <spec_id> \
  --image registry.example.com/team/train-image:latest \
  --instances 4

# 预览 payload 不提交
qzcli create --name test --command "echo hi" --workspace "我的工作空间" --image registry.example.com/team/train-image:latest --dry-run

# JSON 输出（供脚本集成）
qzcli create --name test --command "echo hi" --workspace "我的工作空间" --image registry.example.com/team/train-image:latest --json

参数说明:

参数	短选项	默认值	说明
--interactive	-i		进入交互式任务提交模式，仅提示缺失参数
--name	-n	(必填)	任务名称
--command	-c	(必填)	执行命令
--workspace	-w		工作空间 ID 或名称
--project	-p	(自动选择)	项目 ID 或名称
--compute-group	-g	(自动选择)	计算组 ID 或名称
--spec	-s	(自动选择)	资源规格 ID
--image	-m	docker.sii.shaipower.online/inspire-studio/dhyu-wan-torch29:0.4	Docker 镜像
--image-type		SOURCE_PRIVATE	镜像类型
--instances		1	实例数量
--shm		1200	共享内存 GiB
--priority		10	优先级 1-10
--framework		pytorch	框架类型
--no-track			不自动追踪
--dry-run			只预览不提交
--json			JSON 输出

兼容性说明：历史脚本中的 qzcli create -i <image> 仍可用，CLI 会自动按旧语义解析为 --image。

提示: qzcli create -i 在 TTY 终端下会先进入单实例全屏的层级式选择菜单，按 workspace -> project -> compute_group -> spec 的顺序逐级选择，Enter/→ 进入下一层，← 返回上一层重新选择，界面会直接覆盖刷新而不是连续堆叠多个表格。compute_group 选项里会展示 GPU类型 / 占用口径 / 规格状态 / 空节点 / 空GPU / GPU利用率，其中 共享池 表示该数值来自底层物理 compute group 的共享资源池实时占用，规格状态 会标识该计算组的 spec 列表是否来自实时接口、缓存或异常分支。若某个计算组的实时 spec 查询失败，界面不会退出 TUI，而是在同一屏内给出告警，并支持 m 手动输入 spec ID、r 重试拉取、← 返回上一级更换计算组。完成资源选择后，再按原来的方式输入任务名称、执行命令、Docker 镜像等参数。若当前环境不是 TTY，或缺少 prompt_toolkit，CLI 会自动回退到原来的文本交互模式。若本地 cookie 已失效且已配置 CAS 账号密码，CLI 会自动刷新 cookie 后重试；若本地没有可复用的交互快照，create -i 会按需预加载当前可访问 workspace 的资源快照，并将结果保存到 ~/.qzcli/create_interactive_snapshot.json 供后续复用。已经显式传入的参数会直接跳过。非交互模式下，--project、--compute-group、--spec 省略时仍会自动从 qzcli res 缓存中选取第一个。首次使用前建议先运行 qzcli login && qzcli res -u。

提交 HPC/CPU 任务

HPC 任务使用 Slurm 调度，通过 /api/v1/hpc_jobs 接口提交，需要 cookie 认证（先运行 qzcli login）。

qzcli hpc \
  --name "bulk-NH3-check-outcar" \
  --workspace ws-<workspace_id> \
  --compute-group lcg-<compute_group_id> \
  --predef-quota-id <predef_quota_id> \
  --cpu 55 \
  --mem-gi 300 \
  --instances 30 \
  --cpus-per-task 55 \
  --image docker.sii.shaipower.online/inspire-studio/vasp_lmp-wyh:1203 \
  --entrypoint "cd /path/to/dir && bash run.sh"

参数说明:

参数	默认值	说明
--name	(必填)	任务名称
--workspace	(必填)	工作空间 ID 或名称
--compute-group	(必填)	计算组 ID（lcg-...）
--predef-quota-id	(必填)	预定义配额 ID（资源规格 UUID）
--cpu	(必填)	每节点 CPU 核心数
--mem-gi	(必填)	每节点内存 GiB
--image	(必填)	容器镜像地址
--entrypoint	(必填)	运行命令（shell 字符串）
--project	自动选择	项目 ID 或名称
--instances	1	节点数
--cpus-per-task	1	每任务 CPU 数
--memory-per-cpu	5G	每 CPU 内存
--image-type	SOURCE_PRIVATE	镜像类型
--no-track		不追踪任务
--json		JSON 输出

注意: HPC 任务在启智平台的「高性能计算任务」页面查看，URL 为 https://qz.sii.edu.cn/jobs/hpc?spaceId=<workspace_id>，与 GPU 分布式训练任务页面不同。

批量提交任务

# 从 JSON 配置批量提交
qzcli batch batch_eval.json --delay 3

# 预览所有任务
qzcli batch batch_eval.json --dry-run

# 遇到错误继续提交
qzcli batch batch_eval.json --continue-on-error

批量配置文件格式 (JSON):

{
  "defaults": {
    "workspace": "ws-<workspace_id>",
    "project": "project-<project_id>",
    "compute_group": "lcg-<compute_group_id>",
    "spec": "<spec_id>",
    "image": "docker.sii.shaipower.online/inspire-studio/dhyu-wan-torch29:0.4",
    "instances": 4,
    "shm": 1200,
    "priority": 10
  },
  "matrix": {
    "checkpoint": ["/path/to/ckpt1", "/path/to/ckpt2"],
    "eval_mode": ["mybench_universe", "video_universe"],
    "step": [105000, 200000]
  },
  "name_template": "eval-{checkpoint_basename}-{eval_mode}-step{step}",
  "command_template": "bash /path/to/eval.sh --checkpoint_dir {checkpoint} --eval_mode {eval_mode} --specific_steps {step}"
}

matrix 中的所有维度会做笛卡尔积，上面的例子会生成 2 x 2 x 2 = 8 个任务。模板中可用 {key} 引用 matrix 变量，路径类变量还可用 {key_basename} 获取文件名。

在 shell 脚本中循环提交（替代旧的 curl 方式）:

#!/bin/bash
CHECKPOINTS=("/path/to/ckpt1" "/path/to/ckpt2")
STEPS=(105000 200000)

for ckpt in "${CHECKPOINTS[@]}"; do
  for step in "${STEPS[@]}"; do
    qzcli create \
      --name "eval-$(basename $ckpt)-step${step}" \
      --command "bash /path/to/eval.sh --ckpt $ckpt --step $step" \
      --workspace "分布式训练" \
      --compute-group "xxx-3号机房-2" \
      --instances 4
    sleep 3
  done
done

任务管理

命令	说明	示例
status	查看任务详情	qzcli status job-xxx
stop	停止任务	qzcli stop job-xxx
logs	查看任务容器日志	qzcli logs job-xxx --tail 100
watch	实时监控	qzcli watch -i 10
track	追踪任务	qzcli track job-xxx

# 查看最近 200 条日志（默认）
qzcli logs job-xxx

# 查看最近 N 条，按时间顺序打印
qzcli logs job-xxx --tail 50

# 类似 tail -f 持续轮询新日志
qzcli logs job-xxx --follow --tail 20 --interval 3

# 只输出 message，便于 grep/管道处理
qzcli logs job-xxx --tail 100 --raw

# 每条日志输出一行原始 JSON
qzcli logs job-xxx --tail 10 --json

# 只看指定 pod，或只看某个时间之后的日志
qzcli logs job-xxx --pod job-xxx-worker-0 --since 10m

logs 使用平台 /api/v2/train?Action=GetJobLog 接口，需要 qzcli login 保存的 cookie。若提示 Cookie 过期，重新运行 qzcli login 后再试。

工作空间视图

# 查看工作空间内运行任务（含 GPU 使用率）
qzcli ws

# 查看所有项目
qzcli ws -a

# 过滤指定项目
qzcli ws -p "我的项目"

输出示例

qzcli avail -v

示例工作空间
  计算组                          空节点    总节点 GPU类型     
  -----------------------------------------------------
  OV3蒸馏训练组                       4      8 某gpu2      
    空闲: qb-prod-gpu1006, qb-prod-gpu1029, qb-prod-gpu1034, qb-prod-gpu1064
  openveo训练组                     1     79 某gpu2      
    空闲: qb-prod-gpu2000

qzcli ls -c -w 分布式 -r

工作空间: 示例工作空间

[1] ● 运行中 | 44分钟前 | 44分36秒
    eval-OpenVeo3-I2VA-A14B-1227-8s...
    8×某gpu2 | 4节点 | GPU资源组
    https://qz.sii.edu.cn/jobs/distributedTrainingDetail/job-xxx

[2] ● 运行中 | 58分钟前 | 56分47秒
    sglang-eval-A14B-360p-wsd-105000...
    8×某gpu2 | 2节点 | GPU资源组

配置文件

配置存储在 ~/.qzcli/ 目录：

文件	说明
config.json	API 认证信息
jobs.json	本地任务历史
.cookie	Cookie（login 命令自动管理）
resources.json	资源缓存（工作空间、计算组等）
create_interactive_snapshot.json	create -i 的交互资源快照

环境变量

export QZCLI_USERNAME="your_username"
export QZCLI_PASSWORD="your_password"
export QZCLI_API_URL="https://qz.sii.edu.cn"
export QZCLI_ENV_FILE="/path/to/.env"   # 可选，自定义凭据文件位置

qzcli login / 自动刷新 cookie 会按下面的优先级读取凭据：

CLI 参数 > --password-stdin > shell 环境变量 > QZCLI_ENV_FILE 指向的 .env（默认 ~/.qzcli/.env） > ~/.qzcli/config.json > 交互输入

Roadmap

• Cookie API 收敛: 提取统一的 browser headers 和 cookie request wrapper，减少 api.py 中重复 headers。
• Release 工程化: 继续完善 changelog、贡献者说明、issue 模板和版本发布流程。

Known Issues

• 对 CAS 联合认证用户，/auth/token / /openapi/v1/* token path 可能返回 invalid_grant。日常功能优先使用 qzcli login 保存的 session cookie。
• Cookie 有过期时间；如果命令提示 Cookie 过期，重新运行 qzcli login，或配置 QZCLI_USERNAME / QZCLI_PASSWORD 让 qzcli 自动刷新。
• 平台接口字段偶尔会变化；如果输出异常，优先附带 --json 输出或原始报错开 issue。

Contributors

感谢所有参与代码、PR、测试和反馈的同学：

• @tianyilt
• @0-693
• @gaoyang07
• @YushunXiang
• @GQH123
• @Hashmapw
• @SyntaxSmith
• @ekonwang
• @Stepuuu

致谢

qzcli 的很多能力来自实际使用中的持续反馈、PR 和接口探索。感谢所有参与试用、贡献和反馈的同学。

特别感谢 SII-Holos/holos-inspire 和 EmbodiedForge/Inspire-cli 在启智平台命令行工作流、认证路径和接口探索上的启发与铺垫。qzcli 在此基础上继续面向任务管理、资源查询、日志查看、批量提交和 MCP/agent workflow 做了扩展，希望能让更多启智平台用户少点重复点击，多点自动化空间。

使用建议

• 日常使用: qzcli login && qzcli avail 一键登录并查看资源
• 提交前: qzcli avail -n 4 -e 找合适的计算组并导出配置
• 交互式提交 GPU 任务: qzcli create -i，如只关心单个 workspace 可加 -w
• 提交 GPU 任务: qzcli create -n "job" -c "bash run.sh" -w "分布式训练" --instances 4
• 提交 HPC 任务: qzcli login && qzcli hpc --name "job" --workspace ws-xxx --compute-group lcg-xxx --predef-quota-id uuid --cpu 55 --mem-gi 300 --instances 30 --image img --entrypoint "bash run.sh"
• 批量提交: qzcli batch config.json 从配置文件批量提交
• 监控任务: qzcli ls -c --all-ws -r 查看所有工作空间运行中的任务
• 查看日志: qzcli logs job-xxx --tail 100 拉取任务容器日志，--follow 可持续轮询
• 详细信息: qzcli ws 查看 GPU/CPU/内存使用率