Kugou Music Assistant

Problem It Solves

Integrating Kugou into an agent or CLI workflow is not only about whether it can search songs. The practical failure modes are login state, local client state, and ID dependencies: calling control play without a mixsongid or global_id fails; QR-code login may not render in every client; music search, playlist creation, and playback control split into cloud and local paths. kugou-skill turns these steps into a constrained kugou-cli workflow: authenticate, query, control, and present.

How It Works

The skill is organized around three command groups:
- Auth: auth login returns QR-code fields; the agent can show a local image or a remote Markdown image depending on client capabilities. If the user already has a secret, auth set-secret can skip the QR flow. auth status checks once and relies on outer-loop handling.
- Music queries: music subcommands cover search, recommendations, favorites, stats, charts, and playlist contents. Responses are JSON, which makes it easier to extract song title, artist, playlist title, creator, and IDs.
- Playback control: control subcommands target the local Kugou client for play, pause, track switching, current track, and playlist creation. After playback or track changes, use control current to read the actual song_name and singer_name rather than echoing command parameters.

Presentation rules are explicit: multiple results should use a table, single results depend on client_available for links, and zero results should simply report no match. Proactive recommendation scenarios also require a fixed-length rationale, while user-initiated searches, favorites, stats, and similar queries do not.

Boundaries and Caveats

• control depends on the local client and is generally limited to Windows / macOS; do not claim playback on unsupported systems.
• Features outside the CLI, such as batch download, lyric editing, or podcasts, should be marked unsupported rather than assembled from unrelated commands.
• After a login expiry, avoid repeating the failed music command. Guide the user to set-secret or auth login, confirm logged_in: true, then retry.
• Prefer exit codes and JSON status fields over literal stderr matching.