vllm-ascend-workspace: Skill for Claude Code

Machine Management

Manage the remote-machine layer for vllm-ascend-workspace.

A machine is ready only when the managed container:

• accepts direct local -> container SSH by key, and
• passes the container-side torch + torch_npu smoke test.

Ready does not imply code sync, rebuild, serving, or benchmark readiness.

Use this skill when

• the user asks to add or configure a remote NPU machine
• the user asks whether a managed machine is ready
• the user asks to repair host SSH, container SSH, or managed-container drift
• the user asks to remove a managed machine
• repo-init was skipped and the local machine profile is still missing

Do not use this skill when

• the task is code sync into the remote container
• the task is replacing vllm or vllm-ascend source trees
• the task is rebuilding Python packages or native extensions
• the task is serving, benchmarking, or unrelated SSH work

Critical rules

• Probe first.
• Be idempotent and conservative.
• Keep mutations bounded to the requested machine.
• Treat the bare-metal host as a maintenance plane, not a developer workspace.
• Keep local runtime state only under .vaws-local/.
• Never write passwords or tokens into tracked files or .vaws-local/.
• Never use scp, sftp, sshpass, or expect in this workflow.
• Never default the container image silently. Ask the user to choose one of:
  • local-latest: inspect every image in the target host Docker daemon, keep repositories whose basename contains vllm-ascend (including registry / namespace prefixes and names such as company-vllm-ascend or vllm-ascend-dev), filter them for the detected A2 / A3 / A5 / 310P machine type, and deploy the newest compatible image by Docker image creation time; this never pulls
  • rc: resolve the newest official prerelease vllm-ascend tag, then try quay.nju.edu.cn/ascend/vllm-ascend:<tag> first and quay.io/ascend/vllm-ascend:<tag> second; this is the recommended developer track
  • main: quay.nju.edu.cn/ascend/vllm-ascend:main, then quay.io/ascend/vllm-ascend:main
  • stable: resolve the latest official non-prerelease vllm-ascend release tag, then try NJU first and quay.io second
  • custom: a full image reference with a concrete non-latest tag or digest
• Treat auto, direct *:latest, and bare repositories without a tag as forbidden defaults for managed-machine bootstrap; local-latest is the explicit bounded discovery policy, not a moving registry tag.
• Report and persist the actual selected image for the managed container, not only the requested image policy.
• Resolve hardware-specific image tags from the detected machine type whenever the user chose rc, main, or stable: A2 uses the base tag, A3 appends -a3, A5 appends -a5, and 310P appends -310p.
• Prefer a fresh detailed npu-smi board query over the bare Ascend910 label. Query an NPU ID with npu-smi info -l, query both board forms (-t board -i <id> and -t board -i <id> -c <chip-id>), and construct the SoC from Chip Type / Chip Name / NPU Name as applicable. In particular, Chip Name: Ascend910 plus NPU Name: 9362 means ascend910_9362 / A3. If detailed queries are unavailable, accept an exact bare Ascend910 token as an A3 compatibility fallback.
• Treat /etc/profile.d/vaws-ascend-env.sh, SOC_VERSION, VAWS_NPU_SOC, inventory, and image-name inference as fallbacks or consistency hints only. A successful fresh detailed hardware query wins when old persisted metadata disagrees.
• When detection remains inconclusive, stop and ask for an explicit machine type override instead of guessing.
• Persist host.machine_type, host.soc, and container.machine_type into inventory, and write matching metadata under /etc/vaws/ plus /etc/profile.d/vaws-ascend-env.sh on the host and inside the managed container.
• Before running apt-get update / apt-get install inside the container, rewrite apt sources to the fixed A3-tested NJU mirror (mirrors.nju.edu.cn). Do not spend bootstrap time probing alternate mirrors.
• Prepend /usr/local/Ascend/driver/lib64/common, /usr/local/Ascend/driver/lib64/driver, and /usr/local/Ascend/driver/lib64 before calling npu-smi or the smoke test; source /etc/profile.d/vaws-ascend-env.sh when it exists.
• Persist and reuse an explicit ATB C++ ABI setting during container bootstrap. Do not let login shells repeatedly call ATB set_env.sh without --cxx_abi, because that can import torch during shell startup and add 10+ seconds to ordinary SSH commands.
• Long probe / bootstrap / smoke operations must expose bounded phase progress and have an overall timeout budget, not only a connect timeout.
• On a missing local machine profile, never call workspace_profile.py ensure bare. Use either:
  • --username <letters-or-digits> after the user chose a name
  • --generate only after the user explicitly accepted the default/random option
• If host key SSH is missing and the user already supplied the host password in the request, prefer one-shot scripted bootstrap first. Do not immediately push the user to a manual terminal command.