# Alibabacloud Live Assistant > Read-only diagnostics for Alibaba Cloud Live: stream quality checks (codecs, bitrate, GOP, B-frames, A/V sync), CDN edge-node probing, local recording/snapshot, traffic-theft analysis on abused live domains, and signed push/pull test URL generation; never changes any configuration. Use when the user reports live stream stuttering, pixelation or latency, push/pull stream failures, audio-video out of sync, wants to probe live CDN nodes or record a stream, suspects live traffic theft or anomalous billing, needs a URL authentication check, or asks for push/pull test URLs. Triggers: "live stream stuttering", "live stream pixelation", "live stream latency", "push stream failed", "pull stream failed", "audio video out of sync", "live CDN node check", "live traffic theft", "anomalous live billing", "live URL authentication check", "live stream recording", "generate push stream URL", "generate pull stream URL". - Skill: `aliyun/alibabacloud-live-assistant` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add aliyun/alibabacloud-live-assistant` - Raw SKILL.md: https://api.skillmd.com/api/skills/aliyun/alibabacloud-live-assistant/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: aliyun (https://skillmd.com/u/aliyun) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/aliyun/alibabacloud-live-assistant --- # Alibaba Cloud Live Assistant Diagnose and troubleshoot Alibaba Cloud Live (ApsaraVideo Live) problems: "my live stream is stuttering / pixelated", "push stream failed", "audio and video are out of sync", "is someone abusing my live domain and driving up the bill", "generate push/pull test URLs for my live domain", "record a few seconds of the live stream to check". Core approach: confirm the target stream URL or live domain with the user, then run the matching entry script under `scripts/` — stream quality probing with ffprobe, CDN node probing with ping/TCP/traceroute, authentication-config and offline-log analysis via the aliyun CLI, or local ffmpeg recording/snapshot — and report evidence-based conclusions. This skill is read-only against the cloud: it never modifies any Live configuration, domain, or stream. ## Absolute Rules 1. **ABSOLUTE PROHIBITION (read-only cloud enforcement):** Under **NO** circumstances may you generate, write, or execute any command/script calling a mutating Live API — e.g. `AddLive*`, `SetLive*`, `UpdateLive*`, `DeleteLive*`, `StopLiveStream`, or any domain/stream configuration change. This includes scripts "for the user to run manually". If the user asks to change authentication, block IPs, or stop a stream on the platform side, only output the manual guidance (see [references/security-hardening-guide.md](references/security-hardening-guide.md)) and declare this skill is read-only. 2. **ABSOLUTE PROHIBITION (credential handling):** Never read, print, or pass AK/SK/STS tokens explicitly. Credentials are resolved automatically by the aliyun CLI default credential chain. Never accept AK/SK from the user or from another script. Domain URL-authentication keys (auth_key) returned by config queries are secrets as well: NEVER echo the raw auth_key obtained from any CLI/API output back to the user — not in the final answer, not in any intermediate/process output; when you must reference a key, always quote it masked (first 4 characters followed by `****`, e.g. `vqEf****`). Prefer the sanitized scripts under `scripts/` (which mask auth keys automatically) over calling the CLI directly for authentication-config lookups. 3. **LOCAL WRITE EXCEPTION (explicitly declared):** The only write operations this skill performs are `live_recorder.py` recordings/snapshots, which write media files exclusively to the user-specified output path (or, when the user gives none, to `./outputs/` under the current working directory). No other file, directory, or system state is ever modified. 4. **NO FABRICATION:** Every conclusion must be grounded in data actually returned by ffprobe, network probes, or the Live APIs. If a query fails or returns empty, record it and state the limitation — never invent metrics. 5. **USER-PROVIDED TARGETS ONLY:** Only probe stream URLs or domains the user explicitly provides. Never scan, sweep, or guess domains. 6. **DECLARED APIS AND SCRIPTS ONLY:** Only use the Live APIs and scripts explicitly declared in this document — the Describe-class queries `describe-live-domain-configs`, `describe-live-domain-mapping`, `describe-live-domain-log`, the credential self-check `sts:GetCallerIdentity`, and the five entry scripts under `scripts/`. Never probe, enumerate, or call any other Live API (e.g. `DescribeLiveUserDomains`, `DescribeLiveDomainDetail`); such calls are out of scope for this skill and are not authorized. ## User Confirmation - Before running any diagnosis, confirm the target with the user: a stream URL for quality/node/recording tasks, or a live domain (ingest or playback) for authentication/traffic-theft/URL-generation tasks. - If the user has not provided the target, ask for it first. Never guess, derive, or scan for domains or stream URLs on your own. - Before starting a recording or snapshot, confirm the output path and duration with the user; prefer `--dry-run` to preview the ffmpeg command when the user is unsure. ## Execution Principle MANDATORY: - **Single entry points**: all diagnosis MUST be executed through the scripts under `scripts/` listed in Commands. Do not hand-assemble alternative command chains, and do not freestyle ffprobe/aliyun CLI variants that bypass these scripts. - **Read-only cloud access**: the scripts only call Describe-class Live APIs; the only other call is the agent-level credential self-check `sts:GetCallerIdentity`. - **Interpret, then advise**: after each script run, interpret the JSON output using [references/stream-quality-troubleshooting.md](references/stream-quality-troubleshooting.md) (quality/node results) or [references/security-hardening-guide.md](references/security-hardening-guide.md) (security results), and give evidence-based suggestions as manual guidance only. ## Credentials Credentials are resolved automatically by the aliyun CLI default credential chain (configured via `aliyun configure`, environment variables, or `~/.aliyun/config.json`). This skill never asks for, reads, prints, or passes AK/SK/STS tokens. ```bash # Optional self-check: verify that the CLI credential chain works aliyun sts get-caller-identity ``` **Identity verification failure**: if `aliyun sts get-caller-identity` fails, the default credential chain is not configured. Guide the user to run `aliyun configure` — never ask for AK/SK. Note that only `live_stream_url_generator.py` and `live_theft_handler.py` call the cloud APIs; the other three scripts are purely local (ffprobe/ping/ffmpeg) and need no credentials. ## Observability All OpenAPI calls (invoked through the aliyun CLI) include: - **User-Agent**: `--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}` - **SKILL_NAME**: `alibabacloud-live-assistant` - **session-id**: a 32-character hex string generated once per session (one `uuid.uuid4().hex` per script run) and attached to every CLI command in the same run. The cloud-calling scripts implement this automatically: `_SESSION_ID = uuid.uuid4().hex` and `_USER_AGENT = f"AlibabaCloud-Agent-Skills/alibabacloud-live-assistant/{_SESSION_ID}"` are appended as the `--user-agent` argument of every `aliyun` invocation. ## Prerequisites 1. **aliyun CLI 3.x with the `aliyun-cli-live` plugin** — required for the two cloud-calling scripts; all Live queries use plugin mode (e.g. `aliyun live describe-live-domain-configs`, `aliyun live describe-live-domain-mapping`, `aliyun live describe-live-domain-log`). No direct HTTP signing, no external Python SDK. 2. **Python 3.9+** — standard library only, no third-party dependencies. 3. **ffmpeg / ffprobe** — required by `live_quality.py` (stream probing) and `live_recorder.py` (recording/snapshot). 4. **curl / dig** — HTTP probing and DNS inspection; `live_node.py` additionally uses `ping` and `traceroute`. 5. **Alibaba Cloud credentials** — resolved automatically by the CLI default credential chain; never handle AK/SK explicitly (see Credentials). ## Commands Set the skill directory once, then run the matching entry script: ```bash SKILL_DIR=~/.qoderwork/skills/alibabacloud-live-assistant ``` ### C1 — Stream quality diagnosis ```bash cd $SKILL_DIR && python3 scripts/live_quality.py [--quick] ``` Checks connectivity, codecs (H.264/AAC, B-frames, HEVC-over-RTMP), bitrate/framerate, GOP/keyframe interval, and audio-video sync; outputs JSON with issues and fix recommendations. `--quick` runs connectivity + codec only. ### C2 — CDN node analysis ```bash cd $SKILL_DIR && python3 scripts/live_node.py [--trace-origin] [--verbose] ``` DNS-resolves the live domain, probes each edge node with ICMP ping and TCP connect (port 1935 for RTMP), and summarizes node health and average latency. `--trace-origin` adds traceroute plus an inferred push-domain probe; `--verbose` adds per-node region info. ### C3 — Recording & snapshot ```bash cd $SKILL_DIR && python3 scripts/live_recorder.py record --url [--output ] [--duration ] [--format mp4|flv|hls|ts] [--dry-run] cd $SKILL_DIR && python3 scripts/live_recorder.py snapshot --url [--output ] [--dry-run] cd $SKILL_DIR && python3 scripts/live_recorder.py stop --recording-id cd $SKILL_DIR && python3 scripts/live_recorder.py stop --all ``` Records the stream locally (MP4/FLV/HLS/TS, duration-limited or until Ctrl+C) or captures a single frame. `--dry-run` previews the ffmpeg command without executing. Output is written only to the specified path (default: `./outputs/` under the working directory). For `stop`, a numeric `--recording-id` must match a PID recorded by this tool (arbitrary PIDs are never signaled); `--all` stops every active recording. ### C4 — Domain security analysis (traffic theft) ```bash cd $SKILL_DIR && python3 scripts/live_theft_handler.py analyze --domain --start-time 2026-06-24T08:00:00Z --end-time 2026-06-24T20:00:00Z cd $SKILL_DIR && python3 scripts/live_theft_handler.py guide cd $SKILL_DIR && python3 scripts/live_theft_handler.py step <1-4> cd $SKILL_DIR && python3 scripts/live_theft_handler.py checklist ``` `analyze` queries the URL-authentication config (`describe-live-domain-configs`, function `aliauth`), downloads offline access logs for the window (`describe-live-domain-log`), computes Top IP/URL/Referer/UA statistics and anomaly features, and emits a standardized abuse report. `guide`, `step`, and `checklist` print the full 4-step handling SOP, per-step guidance, and the handling checklist respectively — use them when the user wants to follow the process manually. ### C5 — Push/pull test URL generation ```bash cd $SKILL_DIR && python3 scripts/live_stream_url_generator.py generate --domain [--app-name live] [--stream-name ] [--expire-seconds 3600] ``` Resolves the ingest/playback domain pair (`describe-live-domain-mapping`), reads each domain's `aliauth` config (`describe-live-domain-configs`), and generates signed RTMP/RTS ingest URLs plus RTMP/FLV/M3U8/RTS playback URLs (Type-A `auth_key` when authentication is enabled). Default stream name is `MMDD_test`. ## Capabilities | # | Capability | Description | |---|-----------|-------------| | C1 | Stream quality diagnosis | Connectivity, codec/B-frame/HEVC checks, bitrate/framerate, GOP, audio-video sync, with fix recommendations (`live_quality.py`) | | C2 | CDN node analysis | DNS discovery of edge nodes, ICMP/TCP latency probing, health summary, optional origin tracing (`live_node.py`) | | C3 | Recording & snapshot | Local MP4/FLV/HLS/TS recording and single-frame snapshot of a user-specified stream, written only to the user-specified path (`live_recorder.py`) | | C4 | Domain security analysis (traffic theft) | URL-authentication status check + offline-log Top-N forensics + standardized abuse report and 4-step SOP (`live_theft_handler.py`) | | C5 | Push/pull test URL generation | Domain-mapping resolution + aliauth-aware signed ingest/playback test URLs (`live_stream_url_generator.py`) | ## Orchestration This skill touches two Alibaba Cloud products plus local tooling: **ApsaraVideo Live** (Describe-class queries via the `aliyun-cli-live` plugin: `describe-live-domain-configs`, `describe-live-domain-mapping`, `describe-live-domain-log`), **STS** (the single credential self-check `sts:GetCallerIdentity`), and local `ffmpeg`/`ffprobe`/`ping`/`traceroute`/`curl`/`dig`. Decision criteria — pick the entry by symptom, one entry per symptom, in this order of precedence: 1. Stream looks/feels broken (stuttering, pixelation, latency, A/V sync) with a playable stream URL → **C1** `live_quality.py` first; if quality metrics look normal or connectivity fails, escalate to **C2** `live_node.py` to isolate CDN edge/origin issues. 2. Push/pull failure or connectivity suspected at the network layer (DNS, TCP 1935, node health) → **C2** `live_node.py` (add `--trace-origin` for origin-path problems). 3. Need local evidence of the stream (record a few seconds / grab a frame) → **C3** `live_recorder.py`. 4. Traffic theft, anomalous billing, or URL-authentication concerns on a live domain → **C4** `live_theft_handler.py` (`analyze` runs the auth-config query and offline-log forensics in one pass; use `guide`/`step`/`checklist` for manual SOP guidance). 5. Signed push/pull test URLs needed → **C5** `live_stream_url_generator.py` (it resolves the domain mapping and aliauth config internally). Call order inside a combined investigation: confirm the target with the user, run the symptom entry above, then interpret results against the matching reference doc; never chain entries speculatively. **Error recovery order for API failures (MANDATORY):** 1. **Permission error (NoPermission / Forbidden):** MUST first run credential self-check (`aliyun sts get-caller-identity`), then immediately **switch to the equivalent skill script** (e.g. `scripts/live_theft_handler.py` for domain-config queries, `scripts/live_stream_url_generator.py` for domain-mapping queries) to perform the same query through the script's internal API path. This is classified as **auto_fix** — you MUST change the execution approach, not merely retry the same CLI command. Only if the script also fails, record the error and continue to the next query. 2. **Parameter error (InvalidParameter):** Fix the parameter (e.g. adjust time-window format, correct domain name) and retry. This is **auto_fix**. 3. **Throttling error (Throttling):** Wait ~3 seconds, then retry the same command. This is **retry**. 4. **Internal/System error (InternalError):** Wait ~3 seconds cooldown, then retry the same command. This is **retry**. 5. **Never stop the whole diagnosis on a single failed query** — record the error, recover, and continue. **Domain-type ambiguity (IC scenarios):** When the user provides a root domain (e.g. `example.com`) without specifying whether it is a push (ingest) or pull (playback) domain, you MUST **explicitly state your assumption before running any analysis** — e.g. "I will assume this is a playback (pull) domain and proceed with analysis." Never defer the assumption to a post-hoc remark at the end of the report. Alternatively, ask the user to clarify the domain type before proceeding. ## Examples **Example 1** — User: "My HLS playback keeps stuttering and looks pixelated, can you check the stream?" ```bash cd $SKILL_DIR && python3 scripts/live_quality.py "https://pull.example.com/live/demo.m3u8" cd $SKILL_DIR && python3 scripts/live_node.py pull.example.com --verbose ``` Interpret the issues list (bitrate, framerate stability, GOP, B-frames) per [references/stream-quality-troubleshooting.md](references/stream-quality-troubleshooting.md), then advise publisher-side encoder fixes as manual guidance. **Example 2** — User: "My live bill jumped last week although we had no events; I suspect someone is abusing pull.example.com." ```bash cd $SKILL_DIR && python3 scripts/live_theft_handler.py analyze \ --domain pull.example.com \ --start-time 2026-08-16T00:00:00Z --end-time 2026-08-17T00:00:00Z ``` Present the authentication status, Top IP/URL evidence, and hardening recommendations per [references/security-hardening-guide.md](references/security-hardening-guide.md). Never apply the hardening configuration from this skill. **Example 3** — User: "Generate push and pull test URLs for push.example.com so I can verify my ingest setup." ```bash cd $SKILL_DIR && python3 scripts/live_stream_url_generator.py generate \ --domain push.example.com --app-name live --stream-name my_test --expire-seconds 7200 ``` Show the generated ingest/playback URLs and their expiry; do not display the raw authentication key from the config output. ## Notes - **Read-only operations**: only Describe-class Live queries and `sts:GetCallerIdentity`; the single local-write exception is recording/snapshot output declared in Absolute Rule 3. - **RAM permissions**: grant only the exact actions in [references/ram-policies.md](references/ram-policies.md); no wildcards, no write actions. - **Offline logs are delayed**: `describe-live-domain-log` provides logs only several hours after the fact; align the analysis window to fully past hours. - **All script output is JSON** — parse it programmatically and summarize the `issues` / `features` / `summary` fields for the user. - **Error handling**: cloud-calling scripts emit `{"status": "error", "error": ...}` JSON on failure (missing CLI/plugin, bad domain, no permission). On a permission error (NoPermission), MUST first run the credential self-check `aliyun sts get-caller-identity`, then **immediately switch to the equivalent skill script** (e.g. `scripts/live_theft_handler.py` for config queries) to perform the same query — this is **auto_fix** (change approach), NOT merely retrying the same CLI command. Only if the script also fails, report the error honestly and guide the user to install the `aliyun-cli-live` plugin or fix RAM permissions. - **Quality interpretation**: codec/B-frame/GOP/latency thresholds and encoder fix commands are centralized in [references/stream-quality-troubleshooting.md](references/stream-quality-troubleshooting.md); keep advice consistent with it. - **Recording is a foreground long-running process**: `live_recorder.py record` blocks until `--duration` elapses or the user presses Ctrl+C; prefer a bounded `--duration` for unattended checks. - **Probing output is ticket-ready**: node and quality JSON contain raw latency/loss metrics that can be quoted verbatim when reporting to the user.