Product scope: This skill builds and manages Live-Debug ServiceTask diagnostics on Alibaba Cloud CMS (aliyun cms2 apm service-task) and queries capture results via SLS. It does not onboard APM/agents and is not a general CloudMonitor (CMS) management skill.
Prerequisite Check
Check aliyun exists - which aliyun (macOS/Linux) or where aliyun (Windows).
Check CLI version - run aliyun version. Minimum required: 3.3.15 (see compatibility in frontmatter).
WARNING: Compare version segments as integers (semver): 3.3.4 < 3.3.15 because 4 < 15.
Shell verification: printf '%s\n' "3.3.15" "$(aliyun version)" | sort -V | head -1
If the output equals the current version, the requirement is NOT met.
Version OK -> go to step 3.
Version too old or unrecognized ->
Run aliyun upgrade --help to test whether the upgrade subcommand exists.
Available -> run aliyun upgrade -y, then re-check aliyun version.
Not available (or the upgrade fails) -> ask the user to reinstall/upgrade the CLI manually from the official guides: install https://help.aliyun.com/zh/cli/install-cli, update https://help.aliyun.com/zh/cli/update-cli. Do NOT pipe remote install scripts directly into a shell interpreter - download the installer, inspect it, then run it deliberately, or use the OS package manager. Stop and wait.
If the upgrade succeeded -> go to step 3.
Check cms2 plugin - run aliyun cms2 apm service-task --help.
Help output OK -> continue.
unknown command / missing -> the CMS ServiceTask capability is provided by the aliyuncms2 plugin binary. Confirm it is placed in ~/.aliyun/ (or PATH) and is executable:
bash
If it still fails, run aliyun upgrade -y and retry. If unresolved, stop and report the error (append CLI version, OS, and error message).
Check SLS - run aliyun sls --help (required to query capture results).
Credentials
aliyun cms2 and aliyun sls reuse the aliyun CLI credential system (aliyun configure).
Use --profile <name> to switch profiles. A RAM sub-account with read/write on CMS ServiceTask and query permissions on the target SLS project is recommended.
Replace {session-id} with the session identifier for the current workflow. The companion scripts append this automatically when LIVE_DEBUG_SESSION_ID is set.
Always run aliyun cms2 apm service-task <subcommand> --help first to get the full flag list and examples.
Read .arms-info first: the target workspace / serviceId / regionId / slsProject / targetIp are read from the .arms-info file in the project root (key=value); ask the user only for missing values. Before calling any script, export LIVE_DEBUG_REGION_ID (and LIVE_DEBUG_SLS_PROJECT) from it - do not rely on the local aliyun configure default region.
Workspace discovery: when no workspace is given by .arms-info or the user, run aliyun cms2 workspace list and pick an existing workspace that matches the naming the user requires (e.g. agentloop-{32 hex chars}). Never invent a workspace ID, and never pass a workspace format the user has explicitly forbidden to --workspace.
Resolve serviceId by name when needed: if the user only knows a service name / tag, run aliyun cms2 apm service list and filter by serviceName to resolve the serviceId first. If multiple candidates match, list them and ask the user to confirm - do not pick one silently.
Clarify vague requests before acting: if the request lacks the application language (Java vs Python - the supported capabilities differ), region, workspace, target service, or the diagnostic goal (e.g. dynamic logging vs snapshot vs thread/memory info), ask for the missing pieces first. Never guess or fabricate a workspace / serviceId / taskId, and never create or delete tasks based on guessed targets.
Prefer -o json for ServiceTask calls (the scripts already do); CLI output is wrapped as {"success":true,"data":{...}}.
taskConfig is flat JSON: pass a single command/probe object; do not wrap it in a commands/probes array.
To disable a probe, use Delete (delete_task.sh / delete_all_probes.sh); creating an enabled:false task does not stop a dispatched probe.
Execution Safety
Destructive mutations (deleting tasks/probes) follow a Two-Phase Execution Protocol:
Phase A (Plan): output the exact delete commands, targets, and impact - then stop and wait.
Phase B (Execute): run the delete only after the user's next message contains explicit approval (yes, confirm, proceed, go ahead).
Exception: when the user's initial prompt already explicitly requests deleting a probe/task created in the same workflow (common in eval cleanup), show a one-line delete plan inline and execute in the same turn. Never interpret silence as approval.
Read-only operations (create/list/get, SLS result queries) execute directly.
Error Handling & Retry
Failed CLI calls exit non-zero and print a JSON envelope with an error code, e.g. {"success":false,"code":"Throttling.User","message":"...","requestId":"..."} (SLS uses errorCode/errorMessage). Parse the code and follow this table - never abandon the workflow silently, and never fabricate a taskId, task status, or capture results.
Recovery protocol (applies to every failed command):
Run each mutation as its own command invocation. Do not chain multiple aliyun mutations with &&/; in one shell command, and do not wrap them in retry loops (for/until) that swallow errors - a failure must surface individually so it can be diagnosed.
Classify out loud, then act. When a command fails, first state the returned error code and its class from the table below (e.g. "InternalError -> transient server fault, retrying"), then execute the recovery as a separate follow-up command.
Retry the same command unchanged. For transient classes (throttling / server error), re-run the exact same command with identical flags after a short sleep; do not reorder, reword, or "fix" flags that were not at fault.
Transient rate limiting. Wait briefly (e.g. sleep 5), then retry the same command unchanged. Back off and retry up to 3 attempts.
Server error
InternalError, ServiceUnavailable, HTTP 5xx
Transient server fault. Wait briefly and retry the same command, up to 3 attempts.
Parameter error
InvalidParameter.*, MissingParameter, instanceIds is required
Read the message, re-check the taskConfig against references/live-debug.md (flat JSON, instanceIds placement, no taskId, correct taskType). Fix any real mistake and retry; if the parameters are verified correct, retry once anyway - transient validation faults happen.
Do NOT retry. Identify which RAM action is missing, give the user a concrete authorization suggestion per references/ram-policies.md, and report honestly that the call failed and no data was retrieved.
Not found / region
ProjectNotExist, TaskNotFound
Check region consistency (the SLS project region must match --region) and identifiers, correct, then retry.
After exhausting retries, report the last error verbatim (code, message, requestId) and stop. An honest failure report is the required outcome; fabricated or guessed results are never acceptable.
