omics-hpc-skill

name

omics-hpc-skill

description

端到端管理 omics-hpc 集群——既覆盖腾讯云组学平台云 API（DescribeHPCClusters / RunCommand / DescribeCommandExecution），也内置 SLURM 作业（sbatch / squeue / sacct / scancel / scontrol / salloc / srun）与 tophpc 基础设施（cluster / node / queue / scale / fs / image / log / version）的命令生成与远程下发能力。覆盖以下场景：列出/筛选 HPC 集群、远程下发 Shell 命令、轮询 InvocationId 取回执行结果；提交/查询/取消 SLURM 作业、生成 sbatch 脚本、诊断 PENDING 原因；增删队列/节点、配置弹性伸缩、挂载文件系统、打镜像、查看 / 修改集群配置。触发关键词：HPC 集群、omics-hpc、DescribeHPCClusters、RunCommand、InvocationId、远程执行；sbatch、squeue、sacct、scancel、scontrol、salloc、srun、提交作业、查任务、取消任务、为什么任务没跑、生成脚本、依赖提交、申请交互节点；tophpc、加节点、删节点、加队列、删队列、弹性伸缩、扩缩容、挂载、卸载存储、打镜像、删镜像、看集群、集群配置。**当用户的诉求是"在 omics-hpc 集群上做事"时优先使用本 Skill，而不是 slurm-operator / tophpc-operator——后两者面向本地直连场景，本 Skill 通过云 API 远程下发命令，适配本地未安装 tophpc / 不在登录节点的情况**。

omics-hpc-skill — omics-hpc 集群端到端管理

概述

本 Skill 是 omics-hpc 集群的单一操作入口，覆盖三个层次：

1. 云 API 层：通过腾讯云组学平台 API 直接管理集群与命令——
   • DescribeHPCClusters（按地域筛选集群）
   • RunCommand（在集群上下发 Shell 命令，返回 InvocationId）
   • DescribeCommandExecution（用 InvocationId 查执行结果）
2. SLURM 作业层（领域知识）：辅助生成并下发 sbatch / squeue / sacct / scancel / scontrol / salloc / srun 等作业命令；理解 PENDING 原因、状态码、退出码；针对弹性自动伸缩 + dummynode 占位模式给出正确解释。
3. tophpc 基础设施层（领域知识）：辅助生成并下发 tophpc cluster/node/queue/scale/fs/image/log/version 等基础设施命令；理解可选 instance-type、disk 格式、--instance-specs JSON、--force 与无 --force 命令的非交互处理方式。

SLURM 与 tophpc 的命令本身通过 RunCommand 远程下发到集群管理节点执行，不要求本地装 slurm 或 tophpc。本 Skill 既是"知识库"也是"执行通道"。

阶段	云 API	作用	返回关键字段
集群发现	DescribeHPCClusters	按过滤条件（ClusterId / Name / Status / ConfirmDeadlineLt）分页查询集群清单	Clusters[]：集群基础信息 / 节点数 / 调度器 / VPC
命令下发	RunCommand	在指定集群（可指定节点）上提交 Shell 命令	InvocationId（命令调用 ID）
结果查询	DescribeCommandExecution	用 InvocationId 查命令执行详情	ExecutionSet[]：状态 / stdout / 退出码 / 节点 ID / 时间戳

注意 1：DescribeHPCClusters 接口会受到 Region 的影响，集群按地域隔离；RunCommand 与 DescribeCommandExecution 不受地域限制。 注意 2：DescribeCommandExecution 的 InvocationIds 是数组，可一次批量查多个调用；响应通过 ExecutionSet 一一对应（扁平结构，不嵌套节点列表）。 注意 3：本 Skill 不主动轮询等待终态——是否轮询由调用方决定（describe_command_execution.py --poll）。

端到端标准工作流（"生成命令 → 远程下发 → 取回结果"三段式）

用户描述意图（"提交一个 GPU 训练作业" / "给 small 队列加自动伸缩" / ...）
   ↓
Step A：意图分类 → 落到「SLURM 作业」或「tophpc 基础设施」或「直接走云 API」
   ↓
Step B：构造命令字符串
   - SLURM：参考「SLURM 作业命令生成」章节 + references/slurm_commands.md
            可调用 scripts/generate_sbatch.py 生成 sbatch 脚本
   - tophpc：参考「tophpc 基础设施命令生成」章节 + references/command-reference.md
            instance-type 校验靠 references/instance-types.md
            --instance-specs JSON 校验靠 scripts/build_instance_specs.py
   ↓
Step C：mutating 命令必须先和用户确认
   - 完整命令字符串 + 集群/资源 + 预期影响 → 等用户显式批准
   - 只读命令（squeue / sacct / sinfo / scontrol show / tophpc xxx list/show / config show / version）跳过
   ↓
Step D：远程下发
   python3 scripts/run_hpc_command.py --cluster-id <ClusterId> --command '<构造好的命令>'
   如果是提交作业（sbatch/qsub/salloc/srun），追加 --run-as-user <username> 以普通用户身份提交
   → 拿到 InvocationId
   ↓
Step E：轮询取回执行结果
   python3 scripts/describe_command_execution.py --cluster-id <ClusterId> \
       --invocation-ids <InvocationId> --poll
   → 读 ExecutionSet[].Output（命令 stdout+stderr 合并）+ ExitCode + Status
   ↓
Step F：渲染与解读（按"输出格式"章节模板）
   - SLURM：解释状态码、PENDING 原因、退出码；提醒弹性伸缩语义
   - tophpc：执行后再跑一条只读校验命令同样下发回来确认

用户已经知道 ClusterId → 跳过 DescribeHPCClusters；只给了 InvocationId 想查结果 → 直接从 Step E 开始。

SLURM 作业命令生成（领域知识 — 内置）

详细命令参考请加载 references/slurm_commands.md；状态码与 PENDING 原因解读请加载 references/job_states.md。

弹性自动伸缩集群语义（最重要）

omics-hpc 集群运行在弹性自动伸缩模式下，所有 SLURM 输出必须按这个语义解读：

1. 队列空闲 → 自动缩容到 0 个真实计算节点，仅保留一个 dummynode 占位节点。
2. 用户 sbatch → 作业进入 PENDING 状态（正常、预期）。
3. 自动伸缩系统检测到挂起作业 → 自动扩出真实计算节点。
4. 节点就绪 → 作业开始运行。

关键判定（不要把下面这些当作集群故障）：

• dummynode 不是故障节点，它是占位节点——sinfo 看到 dummynode 处于 down / drain 状态都不算故障，不要建议联系管理员。
• sinfo 显示 0 可用节点 / 仅有 dummynode —— 正常空闲态，不要报"集群异常"。
• 提交后 PENDING 且原因是 Resources / ReqNodeNotAvail —— 自动伸缩还没扩出节点，让用户等几分钟即可。
• 只在 PENDING 持续 >10 分钟时才往"真实异常"方向排查。

意图分类表

将用户请求映射到下表中的一种作业级操作：

类别	是否 mutating	主命令	何时选
实时查询	否	squeue	看挂起 / 运行中作业
历史查询	否	sacct	看完成 / 失败作业
集群只读	否	sinfo	看分区 / 节点（提交前选目标分区）
作业深查	否	scontrol show job	查 PENDING 原因、有效配置
批处理提交	是	sbatch	提交批处理脚本
交互分配	是	salloc / srun	申请交互 shell 或直接跑
取消	是	scancel	取消一个或多个作业
持有/释放	是	scontrol hold / release	暂停 / 恢复挂起作业

边界：用 sinfo 查看分区/节点状态没问题；但修改分区/节点配置属于 tophpc 基础设施层，按"tophpc 基础设施命令生成"章节走。

提交前的最小输入收集

• 批处理提交：job_name、partition、time、mem、nodes、ntasks、cpus_per_task，可选 account / gpus / dependency / array / 输出文件
• 取消：优先精确 job_id；需要广义选择器（-u / --name / --state）时先 squeue 预览再发 scancel
• 历史查询：username 或 job_id，可选时间范围、输出字段
• PENDING 排查：用 scontrol show job <id> 查原因，按上面"弹性集群语义"先排除自动伸缩等待，再用 references/job_states.md 对照解读

提交用户：RunCommand 默认以管理节点上的 root 身份执行命令。提交 SLURM（sbatch）/ SGE（qsub）/交互（salloc / srun）作业时，必须先确认提交用户——通常应以普通用户身份提交，而非 root。收集到用户名后，下发时加上 --run-as-user <username> 参数，脚本会自动将命令包装为 su - <username> -c '<原始命令>'。详见下方「作业提交的用户身份切换」章节。

生成 sbatch 脚本

如果用户描述了资源诉求但没有现成脚本：

• 优先用 scripts/generate_sbatch.py（参数化，支持 --account / --dependency / --array / --ntasks-per-node / --conda-init / --command-file）。
• 或挑最贴近的 assets/*.sh 模板（basic_job.sh / gpu_job.sh / mpi_job.sh / array_job.sh）改写。

注意：生成的脚本通常需要先写到集群侧再 sbatch。两种做法二选一：

1. 用 run_hpc_command.py --command 'cat > /home/xxx/job.sh <<EOF\n...\nEOF\nsbatch /home/xxx/job.sh'
2. 把脚本内容用 --command-file 加载到本地脚本，再透传给 run_hpc_command.py（注意 EOF 边界）

远程下发 + 解读输出（套用三段式）

下发前必须按"端到端工作流 Step C"先和用户确认（mutating 类）。下发后用 --poll 取回 Output，按下表解读：

命令	解读重点
sbatch	输出含 Submitted batch job <id>，提取 job_id；提醒弹性伸缩可能让作业先 PENDING 几分钟
squeue	解释 ST 状态码（PD / R / CG）；NODELIST(REASON) 含 Resources/ReqNodeNotAvail 时要按弹性集群语义解释
sacct	State 终态 + ExitCode（return_code:signal 形式，137:0 通常是 OOM-killed）
sinfo	仅有 dummynode 或 0 可用节点 → 正常空闲态，不要报错
scancel	报告影响哪些作业；建议跟一条 squeue -j 校验
scontrol hold/release	报告新状态；建议跟一条 scontrol show job <id> 校验

squeue --parsable2 / sacct --parsable2 输出量大时，把 Output 喂给 scripts/summarize_slurm_table.py 做汇总。

作业提交的用户身份切换（SLURM / SGE 通用）

RunCommand 默认在管理节点上以 root 身份执行命令。但提交作业（sbatch / qsub / salloc / srun）时，不应以 root 提交——原因：

1. 安全：root 提交的作业拥有最高权限，误操作风险大。
2. 公平调度：调度器按用户统计资源用量，root 绕过了记账和限额。
3. 文件权限：作业输出文件会以 root 属主创建，普通用户后续无法读写。
4. 审计追溯：无法区分是谁提交的作业。

处理方式：收集到提交用户名后，下发时加上 --run-as-user 参数，脚本自动包装为用户切换命令。

标准流程

Step 1：确认提交用户
  - 如果用户已给出用户名 → 直接用
  - 如果未给出 → 询问"请问以哪个用户身份提交作业？"
  - 如果不确定用户是否存在于集群 → 先跑 `ypcat passwd | grep <username>` 验证

Step 2：构造原始命令（如常生成 sbatch / qsub 命令）

Step 3：下发时加 --run-as-user
  python3 scripts/run_hpc_command.py \
    --cluster-id <ClusterId> \
    --command 'sbatch /home/<user>/job.sh' \
    --run-as-user <username>

Step 4：脚本内部自动包装为：
  su - <username> -c 'sbatch /home/<user>/job.sh'

示例

场景：用户 alice 要提交一个 GPU 训练作业到 gpu 分区。

# 先写脚本到集群侧（以 root 写，或让 alice 自己写）
python3 scripts/run_hpc_command.py \
  --cluster-id hpc-9jragud9 \
  --command 'cat > /home/alice/train.sh << '\''EOF'\''
#!/bin/bash
#SBATCH --job-name=gpu_train
#SBATCH --partition=gpu
#SBATCH --gres=gpu:1
#SBATCH --time=24:00:00
python train.py
EOF'

# 然后以 alice 身份提交
python3 scripts/run_hpc_command.py \
  --cluster-id hpc-9jragud9 \
  --command 'sbatch /home/alice/train.sh' \
  --run-as-user alice

SGE (qsub) 同理

python3 scripts/run_hpc_command.py \
  --cluster-id hpc-9jragud9 \
  --command 'qsub -N sge_job -l gpu=1 /home/bob/run.sh' \
  --run-as-user bob

注意事项

• --run-as-user 对只读命令同样适用（如 squeue -u <user>），但通常无需切换——root 可以查看所有用户的作业。
• 如果用户名不存在于集群，su 会报错 User <username> does not exist；先用 ypcat passwd | grep <username> 确认。
• 用户切换后，工作目录会变为该用户的 home 目录（su - 的 - 参数模拟完整登录环境）。如果命令依赖特定工作目录，请在命令中显式 cd 到目标路径。
• --run-as-user 是脚本层面的包装，不影响 RunCommand 的 NodeId / Timeout 等其他参数。

tophpc 基础设施命令生成（领域知识 — 内置）

详细命令、可选项、默认值请加载 references/command-reference.md；可用 instance-type 列表请加载 references/instance-types.md。

操作分类表（mutating 全部需要确认）

操作	主命令	备注
集群生命周期	tophpc cluster create/list/show	create 极少用，通常只用 list/show
节点管理	tophpc node add/list/remove	node remove 用 --force 跳过交互
队列管理	tophpc queue add/list/show/delete	queue delete 没有 --force，用 echo y | ...
弹性伸缩	tophpc scale add/set/show/exec/delete	简单模式（--instance-type + --cpu/--memory/...）vs 复杂模式（--instance-specs JSON）二选一
文件系统	tophpc fs add/list/remove	fs remove 一次只处理一个挂载路径
镜像	tophpc image list/delete	image delete 没有 --force；image create 不支持命令行操作，需要在组学控制台操作
日志采集	tophpc log add/list/remove/reset/report	—
版本	tophpc version、version upgrade/rollback/list	—
配置	tophpc config init/show	远程模式下 config show 只是读集群侧配置

构造命令的核心约束

• clusterId：可选位置参数；远程模式下优先让用户给，或先 DescribeHPCClusters / tophpc cluster list 列；不依赖本地 ~/.tophpc/config.yaml。
• --format json：所有 inspection / verification 命令都加上，输出可机读。
• 磁盘格式：<DiskType>-<DiskSizeGB>，例 CLOUD_SSD-100、CLOUD_PREMIUM-200。
• --instance-type：只用 references/instance-types.md 中列出的类型；用户给了不在表内的 → 告知不支持并提供同族可选项。
• --instance-specs：构造好 JSON 后用 scripts/build_instance_specs.py '<json>' 校验语法和必填字段（Queue、InstanceType），通过后再下发。
• --force：node remove / fs add / fs remove 有 --force，远程下发时必须加避免交互卡住。
• 没有 --force 的命令：queue delete / image delete，远程下发时用 echo y | tophpc queue delete ... 注入确认。
• fs remove：实现层一次只处理一个 mountPath，多个挂载点要重复发命令。

Inspect → Confirm → Execute → Verify 四步铁律（mutating）

每条 mutating 命令都必须经过：

1. Inspect：先跑只读命令（list/show）确认目标资源真实存在、当前状态正常。
2. Confirm：把完整命令字符串、目标 cluster/资源、预期影响展示给用户，等显式批准（"确认"/"yes"/"go"/"执行"）。
3. Execute：批准后一字不改地下发。
4. Verify：再跑一条对应的只读命令，把变更后状态告诉用户。

Mutation	Verify 命令
cluster create	tophpc cluster show [clusterId] --format json
node add / node remove	tophpc node list [clusterId] --format json
queue add / queue delete	tophpc queue list [clusterId] --format json
scale add / scale set / scale delete	tophpc scale show [clusterId] --format json
fs add / fs remove	tophpc fs list [clusterId] --format json
image create / image delete	tophpc image list [imageIds...] --format json
version upgrade / version rollback	tophpc version

常见失败的恢复路径

• clusterId is not specified → 远程模式下显式补 [clusterId]；不要让用户去改本地 config。
• queue not found（scale add 之前）→ 先 tophpc queue list 确认，必要时先 queue add。
• --instance-specs 报错 → 用 scripts/build_instance_specs.py 重新校验 JSON。
• 磁盘格式报错 → 转成 <DiskType>-<DiskSizeGB>。
• image delete 被拦 → 先看 tophpc scale show，被自动伸缩配置引用的镜像非管理员删不掉。

集群运维参考（诊断 & 排查常用路径与命令）

以下路径和命令适用于 omics-hpc 集群的管理节点（manager），通过 RunCommand 远程下发执行。

扩缩容日志

• 日志路径：/var/log/tophpc/scale.log
• 排查扩缩容异常时，远程执行 cat /var/log/tophpc/scale.log 或 tail -100 /var/log/tophpc/scale.log 查看最近日志。

tophpc 定时扩缩容触发方式

• tophpc 的定时扩缩容由 root 用户的 crontab 定时任务 触发。
• 查看当前 crontab 配置：crontab -l（远程下发时需 sudo crontab -l 或确认执行用户为 root）。
• 如果扩缩容未按预期触发，先检查 crontab 是否存在对应条目、执行频率是否正确。

查看集群当前用户

• ypcat passwd — 列出集群上所有 NIS/LDAP 用户信息。
• 常见场景：确认某用户是否已在集群上有账号、排查权限问题。

其他常用运维路径（待补充）

用途	路径 / 命令
tophpc 扩缩容日志	/var/log/tophpc/scale.log
定时扩缩容配置	crontab -l（root）
集群用户列表	ypcat passwd
tophpc 配置文件	~/.tophpc/config.yaml（管理节点上）
SLURM 日志目录	/var/log/slurm/（管理节点上）

Mutating 命令的统一确认协议（贯穿 SLURM + tophpc）

任何会改变集群或作业状态的命令，下发前都必须：

1. 构造完整命令字符串（不留占位符，所有参数都有具体值）。

2. 展示给用户：完整命令 + 目标 cluster/资源 + 预期影响，例如：

   即将远程下发以下命令到集群 hpc-12345：

   sbatch --job-name=train --partition=gpu --gres=gpu:1 --time=24:00:00 train.sh
   

   该命令将向 gpu 分区提交一个名为 train 的作业，申请 1 块 GPU，最大运行时间 24h。

3. 等用户显式批准（"确认"/"好的"/"yes"/"go"/"执行"），才调 run_hpc_command.py。

4. 批准后一字不改地下发；用户要改参数 → 回到第 1 步重新构造。

5. 用户拒绝 → 不下发；问要调什么。

只读命令（squeue / sacct / sinfo / scontrol show / tophpc xxx list/show / tophpc config show / tophpc version）不走确认协议，可直接下发。

真实接口契约（基于实测样例）

DescribeHPCClusters 入参

{
  "Limit": null,
  "Offset": null,
  "Filters": [
    { "Name": "Status", "Values": ["RUNNING"] }
  ]
}

字段	类型	说明
Limit	int	分页大小（可选）
Offset	int	分页起始位置（可选）
Filters	array	过滤器数组，元素形如 {"Name": "...", "Values": [...]}；不传或空数组表示查询全部不进行过滤

支持的过滤器 Name：

Filter Name	说明	Values 示例
ClusterId	集群 ID	["hpc-9jragud9"]
Name	集群名称	["金域迁移测试"]
Status	集群状态	["RUNNING"]
ConfirmDeadlineLt	交付确认截止日期早于给定值	["2026-01-13T16:00:00+08:00"]

DescribeHPCClusters 响应

{
  "Response": {
    "Clusters": [
      {
        "ClusterId": "hpc-kazab9v2",
        "ConfirmDeadline": "",
        "CreateTime": "2026-05-20T11:00:35+08:00",
        "Description": "金域迁移测试",
        "Name": "金域迁移测试",
        "NodeCount": 6,
        "OsName": "CentOS 7.9",
        "Scheduler": "SLURM",
        "SchedulerVersion": "23.11.7",
        "Status": "RUNNING",
        "Tags": [],
        "Type": "CVM_CLUSTER",
         
         
      
    
     
     
  

RunCommand 入参

{
  "ClusterId": "hpc-9jragud9",
  "Command": "tophpc node list --format yaml",
  "NodeId": null,
  "Timeout": null,
  "ClientToken": null
}

字段	类型	说明
ClusterId	string	集群 ID（必填）
Command	string	Shell 命令内容（必填）
NodeId	string	目标节点 ID（单个，非数组）；不传则按服务端默认调度
Timeout	int	命令超时（秒）
ClientToken	string	幂等 Token，重试场景下避免重复下发

RunCommand 响应

{ "Response": { "InvocationId": "inv-64mrvxgutj", "RequestId": "..." } }

DescribeCommandExecution 入参

{
  "ClusterId": "hpc-9jragud9",
  "InvocationIds": ["inv-64mrvxgutj"],
  "Offset": null,
  "Limit": null
}

DescribeCommandExecution 响应（扁平结构）

{
  "Response": {
    "ExecutionSet": [
      {
        "InvocationId": "inv-64mrvxgutj",
        "ClusterId": "hpc-9jragud9",
        "Command": "tophpc node list --format yaml",
        "NodeId": "ins-85ckz3bg",
        "Status": "SUCCESS",
        "ExitCode": 0,
        "Output": "nodeset:\n    - nodeid: ...",
        "OutputTruncated": false,
        "Duration": 0,
        "StartTime": "2026-06-09T08:34:08Z",
        "EndTime": "2026-06-09T08:34:08Z",
        "CreatedTime": "2026-06-09 16:34:07"
         
      
    
     
     
  

重要：每个 InvocationId 对应 ExecutionSet 中的一条记录（扁平），不嵌套 NodeExecutions[]。stdout 与 stderr 均合并在 Output 字段中，没有独立的 ErrorOutput。

执行方式

使用 Skill 目录下的 Python 脚本：

# 1. 列出 HPC 集群（DescribeHPCClusters）
python3 scripts/describe_hpc_clusters.py \
  [--cluster-id <id1,id2,...>] \
  [--name <name1,name2,...>] \
  [--status <RUNNING,...>] \
  [--confirm-deadline-lt <YYYY-MM-DDTHH:MM:SS+08:00>] \
  [--filter '<json array>'] \
  [--offset 0] [--limit 20] \
  [--region <REGION>]

# 2. 下发命令（RunCommand）
python3 scripts/run_hpc_command.py \
  --cluster-id <ClusterId> \
  --command '<shell command>' \
  [--node-id <NodeId>] \
  [--timeout <seconds>] \
  [--client-token <token>] \
  [--extra-params '<json>'] \
  [--run-as-user <username>] \
  [--region <REGION>]

# 3. 查询命令执行结果（DescribeCommandExecution）
python3 scripts/describe_command_execution.py \
  --cluster-id <ClusterId> \
  --invocation-ids <id1,id2,...> \
  [--offset 0] [--limit 20] \
  [--region <REGION>] \
[--poll] [--poll-interval 5] [--poll-timeout 300]

参数说明 — describe_hpc_clusters.py

参数	必填	默认值	说明
--cluster-id	否	—	按 ClusterId 过滤；多个用英文逗号分隔，等价于 Filters: [{Name: ClusterId, Values: [...]}]
--name	否	—	按 Name 过滤；多个用英文逗号分隔
--status	否	—	按 Status 过滤；多个用英文逗号分隔（如 RUNNING,UPGRADING）
--confirm-deadline-lt	否	—	按 ConfirmDeadlineLt 过滤（交付确认截止日期早于给定值）
--filter	否	—	直接透传给 Filters 的 JSON 数组，便于覆盖未列举的过滤器；与上述具体过滤参数合并（同名以本参数为准）
--offset	否	—	分页起始位置
--limit	否	—	分页大小
--region	否	ap-guangzhou	业务地域（X-TC-Region）：决定查哪个地域下的集群，集群是按地域隔离的（如 ap-shanghai / ap-singapore）

参数说明 — run_hpc_command.py

参数	必填	默认值	说明
--cluster-id	是	—	集群 ID（形如 hpc-9jragud9）
--command	是*	—	命令内容（shell 字符串）；与 --command-file 二选一
--command-file	是*	—	命令内容文件路径；与 --command 二选一
--node-id	否	—	目标节点 ID（单个，不传则按服务端默认调度，通常落在 manager 节点）
--timeout	否	—	命令超时（秒）
--client-token	否	—	幂等 Token
--extra-params	否	—	透传给 RunCommand 的额外 JSON 参数（合并到 params）
--run-as-user	否	—	以指定用户身份执行命令（自动包装为 su - <user> -c '...'）；典型场景：以普通用户而非 root 提交 SLURM/SGE 作业
--region	否	ap-guangzhou	SDK 签名用的 region（X-TC-Region）；RunCommand 本身不受地域限制，默认即可

*--command 与 --command-file 至少传一个；同时传时以 --command-file 为准。

参数说明 — describe_command_execution.py

参数	必填	默认值	说明
--cluster-id	是	—	集群 ID
--invocation-ids	是	—	InvocationId 列表（英文逗号分隔，可批量）
--offset	否	—	分页起始位置
--limit	否	—	分页大小
--region	否	ap-guangzhou	SDK 签名用的 region（X-TC-Region）；DescribeCommandExecution 不受地域限制，默认即可
--poll	否	false	是否轮询直至所有调用进入终态
--poll-interval	否	5	轮询间隔（秒）；过小（如 3s）容易被腾讯云限流拦截
--poll-timeout	否	300	轮询超时（秒），到点仍未终态则按当前快照返回

前置依赖

pip3 install tencentcloud-sdk-python

密钥从环境变量读取：

export TENCENTCLOUD_SECRET_ID=...
export TENCENTCLOUD_SECRET_KEY=...

查询逻辑

Endpoint / Region

Endpoint（网络接入点）

三个脚本统一使用单一接入点，由腾讯云就近调度：

omics.tencentcloudapi.com

不再按 region 拼接 omics.{region}.tencentcloudapi.com。

Region（业务地域，不同接口语义不同）

API	--region 含义	需要调整吗？
DescribeHPCClusters	业务地域——集群按地域隔离，不同 region 查到的集群不同	是，必须传对集群所在的 region（如 ap-shanghai）
RunCommand	仅用于 SDK 签名（X-TC-Region），不限定集群；主要走 ClusterId 定位集群	否，默认 ap-guangzhou 即可
DescribeCommandExecution	同上，不受地域限制；InvocationId 全局可识别	否，默认即可

• DescribeHPCClusters 查不到期望集群时，先确认 --region 是否与集群实际所在地域一致。
• RunCommand 与 DescribeCommandExecution 的 --region 可以不一致（不影响语义），但建议保持一致以便调试习惯一致。

终态判定（describe_command_execution.py --poll 用）

下列状态视为终态（实测样例已验证 SUCCESS，其余以关键字兜底）：

• SUCCESS / Succeeded / SUCCEEDED
• FAILED / Failure / FAILURE
• TIMEOUT
• TERMINATED / Cancelled / CANCELLED
• ERROR

其余（如 PENDING / RUNNING / INVOKING）视为非终态，轮询继续。

服务端实际状态枚举以 SDK 文档为准；判定使用大小写不敏感的子串匹配兜底。轮询时若 ExecutionSet 长度 < 入参 InvocationIds 数量，也视为非终态（部分调用还在生成中）。

结果解析

DescribeHPCClusters 响应

字段	说明
Response.Clusters[]	集群清单
Response.TotalCount	命中条数
Clusters[].ClusterId	集群 ID（如 hpc-kazab9v2）
Clusters[].Name / Description	集群名 / 描述
Clusters[].Status	集群状态（如 RUNNING）
Clusters[].NodeCount	节点数
Clusters[].OsName	操作系统（如 CentOS 7.9）
Clusters[].Scheduler / SchedulerVersion	调度器 / 版本（如 SLURM 23.11.7）
Clusters[].Type	集群类型（如 CVM_CLUSTER）
Clusters[].VPCId / VPCCIDRBlock	VPC ID / CIDR
Clusters[].CreateTime / ConfirmDeadline	创建时间 / 交付确认截止时间
Clusters[].Tags	标签

RunCommand 响应

字段	说明
Response.InvocationId	核心字段，下一步查询命令执行结果用
Response.RequestId	请求 ID（追溯用）

DescribeCommandExecution 响应（扁平结构）

字段	说明
Response.ExecutionSet	数组，每个 InvocationId 一条
Response.TotalCount	命中条数
ExecutionSet[].InvocationId	对应的调用 ID
ExecutionSet[].ClusterId	集群 ID
ExecutionSet[].Command	原始命令内容
ExecutionSet[].NodeId	实际执行节点的 InstanceId（如 ins-85ckz3bg，注意是 CVM 实例 ID 而非 node-id）
ExecutionSet[].Status	整体状态（参考终态判定）
ExecutionSet[].ExitCode	退出码（0 = 正常）
ExecutionSet[].Output	命令输出（stdout + stderr 合并；可能截断，看 OutputTruncated）
ExecutionSet[].OutputTruncated	输出是否被截断的布尔位
ExecutionSet[].Duration	命令执行时长（秒）
ExecutionSet[].StartTime / EndTime	执行起止时间（UTC）
ExecutionSet[].CreatedTime	调用创建时间（北京时间）
ExecutionSet[].Operator	操作者 Uin

脚本透传服务端原始 Response，不做字段裁剪。

输出格式

集群列表（DescribeHPCClusters）

## HPC 集群列表（{region}，共 {TotalCount} 个）

| ClusterId | Name | Status | Nodes | Scheduler | OS | VPC | CreateTime |
|---|---|---|---|---|---|---|---|
| `hpc-kazab9v2` | 金域迁移测试 | RUNNING | 6 | SLURM 23.11.7 | CentOS 7.9 | vpc-87y9syeb (10.10.0.0/22) | 2026-05-20 11:00:35 |

当 TotalCount > limit，提示用户用 --offset/--limit 翻页。

下发阶段（RunCommand）

## 命令下发：{ClusterId}

**Region**：{region}
**InvocationId**：`{InvocationId}`  ← 下一步查询用
**RequestId**：{RequestId}

### 命令内容
```sh
{Command}

提示用户：如需查看执行结果，请运行 python3 scripts/describe_command_execution.py --cluster-id {ClusterId} --invocation-ids {InvocationId} 或加 --poll 自动等到终态。

### 查询阶段（DescribeCommandExecution）

按 `ExecutionSet` 逐条渲染，每条一节：

```markdown
## 命令执行：{InvocationId}

**Region**：{region}
**集群**：{ClusterId}
**执行节点**：{NodeId}
**操作者**：{Operator}
**状态**：{Status}    **退出码**：{ExitCode}    **耗时**：{Duration}s
**创建时间**：{CreatedTime}
**起止**：{StartTime} ~ {EndTime}

### 命令
```sh
{Command}

输出（{OutputTruncated}）

{Output}

如果状态非终态（如 `RUNNING` / `PENDING`）且未启用 `--poll`，提示用户「命令仍在执行中，可加 `--poll` 自动等待，或稍后重试」。

`OutputTruncated=true` 时提醒用户：「输出被截断，建议改写命令为重定向到文件 + `cat 文件` 两步走」。

## 三段式工作流（指针）

云 API 三段式（`DescribeHPCClusters → RunCommand → DescribeCommandExecution`）已合并到本文顶部「端到端标准工作流」中作为通用骨架；当用户的诉求纯粹是"在某个集群上跑一条裸命令"时，把 Step A 的意图分类标记为"直接走云 API"，Step B 不进入 SLURM/tophpc 命令生成，直接把用户给的 shell 字符串送入 Step D 即可。其他步骤（确认协议、远程下发、轮询取回、按"输出格式"模板渲染）保持一致。

## 注意事项

1. 命令内容仅传**用户明确给定**的 shell 字符串，不要擅自加 `set -e`、`source ~/.bashrc` 等修改；如确有需要必须先与用户确认
2. 对涉及 `rm -rf`、覆盖系统文件、修改 `/etc`、`sudo` 等高危命令，下发前**必须**先回显完整命令并请用户显式确认（y/yes）
3. 如果命令含敏感信息（密钥、密码、token），提醒用户改用环境变量或文件方式注入
4. `--node-id` 不传时由服务端按集群默认策略调度；实测一般会落在 manager 节点（`role=1` 那台）
5. `Output` 字段服务端有大小限制，超长输出会被截断（看 `OutputTruncated`）；遇到截断改写为重定向到文件 + `cat 文件` 的两步
6. `RunCommand` 与 `DescribeCommandExecution` 是全局接口，**不受地域限制**；`InvocationId` 可以跨 region 查。`DescribeHPCClusters` 是地域接口，`--region` 传错会查不到集群。三个脚本统一走统一接入点 `omics.tencentcloudapi.com`，腾讯云会就近调度。
7. `ExecutionSet[].NodeId` 实测返回的是**CVM 实例 ID**（`ins-xxx`），不是 HPC 节点 ID（`node-xxx`）；如需对应 HPC 节点，请配合 `DescribeHPCNodes` 反查
8. `DescribeHPCClusters` 的过滤是**与**关系——多个 Filter 同时生效，单个 Filter 内部 `Values` 是**或**关系
9. 禁止透露任何敏感信息，包括密钥、密码、用户名、调用的接口名称等