{"id":"103981a3-fe1a-4978-8f95-e7bce3853436","entityType":"agent","slug":"clawhub-shamo88-kugou-skill","name":"酷狗","canonicalUrl":"https://www.xpersona.co/agent/clawhub-shamo88-kugou-skill","canonicalPath":"/agent/clawhub-shamo88-kugou-skill","generatedAt":"2026-10-11T07:41:39.778Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T04:43:08.802Z","emptyReason":null},"description":"酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手 提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单、调整音乐偏好等功能。 **触发场景**（满足任一即使用本技能）： - 用户要求推荐歌曲、听歌建议 - 用户要求搜索歌曲、查找歌手作品 - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等） - 用户要求查看收藏、最近播放、听歌统计 - 用户要求创建歌单、自建歌单 - 用户要求调整音乐偏好（\"少推点 XX 歌手\"、\"多推点 XX 语种\"、\"别再推 XX 曲风\" 等） - 用户提供 base64 secret 字符串要求登录或导入身份 - Agent Skill: 酷狗 Owner: shamo88 Summary: 酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手 提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单、调整音乐偏好等功能。 **触发场景**（满足任一即使用本技能）： - 用户要求推荐歌曲、听歌建议 - 用户要求搜索歌曲、查找歌手作品 - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等） - 用户要求查看收藏、最近播放、听歌统计 - 用户要求创建歌单、自建歌单 - 用户要求调整音乐偏好（\"少推点 XX 歌手\"、\"多推点 XX 语种\"、\"别再推 XX 曲风\" 等） - 用户提供 base64 secret 字符串要求登录或导入身份 - Agent Tags: latest:0.1.20 Version history: v0.1.20 | 2026-09-14T03:04:35.881Z | user kugou-sk","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17817v0twfch5vbdchhmj7nh588v7tg:kugou-skill","sourceUrl":"https://clawhub.ai/shamo88/kugou-skill","homepage":"https://clawhub.ai/shamo88/skills/kugou-skill","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/shamo88/kugou-skill","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/shamo88/skills/kugou-skill","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手 提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单、调整音乐偏好等功能。 **触发场景**（满足任一即使用本技能）： - 用户要求推荐歌曲、听歌建议 - 用户要求搜索歌曲、查找歌手作品 - 用户要求查看音乐榜单（飙升榜、TOP500"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T04:43:08.802Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T04:43:08.802Z","emptyReason":null},"stars":null,"forks":null,"downloads":1156,"packageName":null,"latestVersion":"0.1.20","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T04:43:08.787Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T04:43:08.802Z","lastCrawledAt":"2026-10-11T04:43:08.787Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T04:43:08.787Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.20","createdAt":"2026-09-14T03:04:35.881Z","changelog":"kugou-skill 0.1.20 - 新增“调整音乐偏好”相关说明，支持按歌手/语种/曲风进行推荐偏好调整 - 描述中强化偏好反馈功能，明确支持基于用户反馈实时调整推荐 - 触发场景增加“调整音乐偏好”类请求的支持 - 移除文档 `skill-card.md` - 其他描述及细节文案微调","fileCount":10,"zipByteSize":45768},{"version":"0.1.13","createdAt":"2026-08-31T08:45:56.774Z","changelog":"kugou-skill v0.1.13 更新日志 - 新增：首次要展示歌曲/歌单列表前，需自动检测本机是否安装酷狗客户端（control detect），影响后续展示形式。 - 歌曲/歌单展示规范升级：多条结果用 Markdown 表格、表格内禁用链接，单条结果有无客户端分别加不加链接。 - 播放/切歌类操作后必须自动查询并告知当前正在播放的曲目。 - 明确规范客户端探测结果如何影响展示与控制命令流程。 - 细化扫码登录流程的轮询/重试策略，支持 failed/expired 等多种中间状态。 - 移除 skill-card.md 文件（对功能无影响）。","fileCount":10,"zipByteSize":38535},{"version":"0.1.8","createdAt":"2026-08-10T08:15:01.222Z","changelog":"**本次为控制酷狗客户端能力的重大更新** - 新增 references/control.md 文档，全面支持 PC/Mac 酷狗客户端的本地控制能力，包括播放、暂停、切歌、收藏和客户端歌单创建等。 - 扩展触发场景，现在可响应用户关于“本机控制”、“控制酷狗客户端”、酷狗 URL scheme 及客户端操作的指令。 - 登录流程、命令分流和调用原则均有较大调整：加入 control 命令与 music 命令的配合流程，增加了本地控制的优先级描述。 - 歌单创建流程明确优先客户端本地创建，云端创建行为作为兜底方案，并新增播放歌单后的主动询问逻辑。 - 删除 skill-card.md，文档结构优化；完善文档索引和推荐理由/输出规范说明。","fileCount":10,"zipByteSize":33428},{"version":"0.1.7","createdAt":"2026-08-05T12:09:07.751Z","changelog":"优化登录流程","fileCount":9,"zipByteSize":18292},{"version":"0.1.6","createdAt":"2026-08-05T09:29:52.284Z","changelog":"优化登录流程","fileCount":9,"zipByteSize":17738},{"version":"0.1.4","createdAt":"2026-07-10T10:43:52.051Z","changelog":"kugou-skill 0.1.3 - 新增「auth logout」登出命令，支持服务端同步登出并本地清理 - 登录态自动失效处理：遇登录过期会自动清理本地状态并提示需重新登录 - 文档中明确描述登出、登录过期自动清理与引导流程 - 移除 skill-card.md 文件，优化项目结构","fileCount":9,"zipByteSize":14026},{"version":"0.1.2","createdAt":"2026-06-17T09:20:08.387Z","changelog":"kugou-skill 0.1.2 - 新增 SKILL.md，详细介绍酷狗音乐技能的功能、使用流程、登录方法及命令说明 - 明确所有命令输出 JSON，规范歌曲展示为 Markdown 链接格式 - 优化扫码与 secret 登录流程说明，提升用户体验 - 补充自动更新机制、错误处理及多场景触发说明 - 提供完整的文档索引和标准化调用流程示例","fileCount":9,"zipByteSize":13122}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17817v0twfch5vbdchhmj7nh588v7tg:kugou-skill","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shamo88-kugou-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shamo88-kugou-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shamo88-kugou-skill/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-shamo88-kugou-skill/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-shamo88-kugou-skill/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-shamo88-kugou-skill/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T07:41:39.775Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shamo88-kugou-skill/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shamo88-kugou-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shamo88-kugou-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shamo88-kugou-skill/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T04:43:08.802Z","emptyReason":null},"readme":"Skill: 酷狗\n\nOwner: shamo88\n\nSummary: 酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手\n提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单、调整音乐偏好等功能。\n\n**触发场景**（满足任一即使用本技能）：\n- 用户要求推荐歌曲、听歌建议\n- 用户要求搜索歌曲、查找歌手作品\n- 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）\n- 用户要求查看收藏、最近播放、听歌统计\n- 用户要求创建歌单、自建歌单\n- 用户要求调整音乐偏好（\"少推点 XX 歌手\"、\"多推点 XX 语种\"、\"别再推 XX 曲风\" 等）\n- 用户提供 base64 secret 字符串要求登录或导入身份\n- Agent\n\nTags: latest:0.1.20\n\nVersion history:\n\nv0.1.20 | 2026-09-14T03:04:35.881Z | user\n\nkugou-skill 0.1.20\n\n- 新增“调整音乐偏好”相关说明，支持按歌手/语种/曲风进行推荐偏好调整\n- 描述中强化偏好反馈功能，明确支持基于用户反馈实时调整推荐\n- 触发场景增加“调整音乐偏好”类请求的支持\n- 移除文档 `skill-card.md`\n- 其他描述及细节文案微调\n\nv0.1.13 | 2026-08-31T08:45:56.774Z | user\n\nkugou-skill v0.1.13 更新日志\n\n- 新增：首次要展示歌曲/歌单列表前，需自动检测本机是否安装酷狗客户端（control detect），影响后续展示形式。\n- 歌曲/歌单展示规范升级：多条结果用 Markdown 表格、表格内禁用链接，单条结果有无客户端分别加不加链接。\n- 播放/切歌类操作后必须自动查询并告知当前正在播放的曲目。\n- 明确规范客户端探测结果如何影响展示与控制命令流程。\n- 细化扫码登录流程的轮询/重试策略，支持 failed/expired 等多种中间状态。\n- 移除 skill-card.md 文件（对功能无影响）。\n\nv0.1.8 | 2026-08-10T08:15:01.222Z | user\n\n**本次为控制酷狗客户端能力的重大更新**\n\n- 新增 references/control.md 文档，全面支持 PC/Mac 酷狗客户端的本地控制能力，包括播放、暂停、切歌、收藏和客户端歌单创建等。\n- 扩展触发场景，现在可响应用户关于“本机控制”、“控制酷狗客户端”、酷狗 URL scheme 及客户端操作的指令。\n- 登录流程、命令分流和调用原则均有较大调整：加入 control 命令与 music 命令的配合流程，增加了本地控制的优先级描述。\n- 歌单创建流程明确优先客户端本地创建，云端创建行为作为兜底方案，并新增播放歌单后的主动询问逻辑。\n- 删除 skill-card.md，文档结构优化；完善文档索引和推荐理由/输出规范说明。\n\nv0.1.7 | 2026-08-05T12:09:07.751Z | user\n\n优化登录流程\n\nv0.1.6 | 2026-08-05T09:29:52.284Z | user\n\n优化登录流程\n\nv0.1.4 | 2026-07-10T10:43:52.051Z | user\n\nkugou-skill 0.1.3\n\n- 新增「auth logout」登出命令，支持服务端同步登出并本地清理\n- 登录态自动失效处理：遇登录过期会自动清理本地状态并提示需重新登录\n- 文档中明确描述登出、登录过期自动清理与引导流程\n- 移除 skill-card.md 文件，优化项目结构\n\nv0.1.2 | 2026-06-17T09:20:08.387Z | auto\n\nkugou-skill 0.1.2\n\n- 新增 SKILL.md，详细介绍酷狗音乐技能的功能、使用流程、登录方法及命令说明\n- 明确所有命令输出 JSON，规范歌曲展示为 Markdown 链接格式\n- 优化扫码与 secret 登录流程说明，提升用户体验\n- 补充自动更新机制、错误处理及多场景触发说明\n- 提供完整的文档索引和标准化调用流程示例\n\nArchive index:\n\nArchive v0.1.20: 10 files, 45768 bytes\n\nFiles: references/auth.md (13903b), references/control.md (35124b), references/error-handling.md (1183b), references/install.md (2049b), references/music.md (26161b), references/output-format.md (9038b), references/update.md (3235b), skill-card.md (2745b), SKILL.md (22407b), _meta.json (131b)\n\nFile v0.1.20:SKILL.md\n\n---\r\nname: kugou-skill\r\ndescription: |\r\n 酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手\r\n 提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单、调整音乐偏好等功能。\r\n\r\n **触发场景**（满足任一即使用本技能）：\r\n - 用户要求推荐歌曲、听歌建议\r\n - 用户要求搜索歌曲、查找歌手作品\r\n - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）\r\n - 用户要求查看收藏、最近播放、听歌统计\r\n - 用户要求创建歌单、自建歌单\r\n - 用户要求调整音乐偏好（\"少推点 XX 歌手\"、\"多推点 XX 语种\"、\"别再推 XX 曲风\" 等）\r\n - 用户提供 base64 secret 字符串要求登录或导入身份\r\n - Agent 在尝试扫码登录时遇到环境限制（无法发图片）→ 主动询问用户是否可提供 secret\r\n - 用户提到\"酷狗\"、\"kugou\"、\"猜你喜欢\"、\"相似歌曲\"\r\n - 用户要求让 PC/Mac 客户端播放歌曲、暂停、切歌、收藏、创建歌单\r\n - 用户提到酷狗 URL scheme（\"kugou://\" 或 \"mackugou://\"）\r\n - 用户提到\"本机控制\"、\"控制酷狗客户端\"\r\n\r\n **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐；同时支持把用户偏好（歌手/语种/曲风等）实时反馈给推荐引擎。\r\n\r\n 安装方式：npm install -g @kg-ai/kugou-skill\r\n---\r\n\r\n# kugou-skill\r\n\r\n## AI 使用工作流（优先阅读）\r\n\r\n使用本工具时的标准流程：\r\n\r\n```\r\n1. 检查安装 → npm install -g @kg-ai/kugou-skill\r\n2. 检查登录态 → kugou-cli auth status\r\n3. 登录决策（按以下优先级严格判断，不要跳步）：\r\n ├─ 状态 a：已登录（logged_in: true）→ 跳到第 6 步\r\n ├─ 状态 b：未登录 + 用户**明确**说\"我有 secret\" → 调 `kugou-cli auth set-secret \"\"` 一次完成 → 跳到第 6 步\r\n ├─ 状态 c：未登录 + 当前环境**无法**渲染远程 URL 图片 **且** 无法读取本地二维码文件 → **强制**走 set-secret（同上）\r\n └─ 状态 d：未登录 + 其他所有情况 → 走扫码流程（第 4 步）\r\n\r\n 注意：状态 b/c/d 互斥；不要在用户未明确给 secret 时擅自走 set-secret。\r\n4. 引导登录——扫码（详见 references/auth.md）：\r\n - 执行 `auth login`，从输出读 `qrcode_img_url` 和 `qrcode_img_path`，按当前客户端能力选一种方式把二维码**直接展示给用户**\r\n - **阶段 A（主动轮询）**：图片刚展示，**主动**重试几次 `auth status`（每次隔几秒），覆盖用户秒扫场景\r\n - 任意一次返回 `logged_in: true` → 跳到第 6 步\r\n - 见到 `status: failed` → **不要换新图**，隔 1-2 秒用同一个本地 qrcode 再调一次（计入阶段 A 的 5 次预算）\r\n - 见到 `status: expired` → 告诉用户二维码已失效，调 `auth login` 拿新图，从阶段 A 重新开始\r\n - 几次都返回 `waiting` / `failed` 且未出现 `scanned` / `logged_in` / `expired` → 进入阶段 B\r\n - **阶段 B（等用户回复）**：停下，告诉用户\"请用酷狗 APP 扫码登录，扫完后告诉我已扫码\"，**不再调 status**，等用户**主动回复\"已扫码\"**\r\n - **阶段 C（验证一次）**：用户回复\"已扫码\"后，**调一次** `auth status`：\r\n - `logged_in: true` → 完成，跳到第 6 步\r\n - `scanned`（已扫但未确认）→ 等几秒再调一次，最多**额外**调几次，仍是 scanned 就告诉用户\"手机端是否已点确认？\"\r\n - `failed` → **不要换新图**，隔 1-2 秒用同一个本地 qrcode 再调一次，最多重试 2-3 次；仍 failed 则告诉用户稍后重试\r\n - `expired` / `{\"logged_in\": false}`（无 status 字段，说明本地 qrcode 已被上游清掉）→ 重新 `auth login` 拿新图（覆盖本地），从阶段 A 重新开始\n5. **首次要展示歌曲/歌单前探测本机客户端可用性**（详见 [references/control.md §13](references/control.md#13-client-detection-control-detect)）：\r\n - **触发时机**：本会话中第一次要向用户展示歌曲列表、歌单列表或歌单内歌曲列表之前。后续展示**复用本次探测结果**（会话内探测一次即可，不要每条命令前都跑）\r\n - **命令**：`kugou-cli control detect`（零副作用，不启动客户端、不抢焦点）\r\n - **判定**：\r\n - 退出码 `0` → 本机有客户端，标记 `client_available = true`\r\n - 退出码 `2` → 本机没装客户端，标记 `client_available = false`\r\n - 退出码 `1` → 探测过程出错（注册表权限等），按 `false` 处理并继续\r\n - **不影响 control 命令本身**：当用户主动要求 `control play` 等命令时，仍按原本的 `control` 错误处理（找不到客户端会由 `control start` 报\"handshake file not found\"，不要用探测结果跳过 `control` 调用）\r\n - **何时不探测**：用户请求只查询统计数据、查收藏/最近播放、看错误页等**不展示歌曲列表**的纯查询场景；登录流程本身；debug / 排错场景\r\n\r\n6. 按请求类型分流：\r\n - **请求类型 A：控制已有歌 / 歌单 / 收藏**（用户已有 mixsongid 或 global_id）→ 直接执行 `control` 命令（详见 [references/control.md](references/control.md)），不需要先调 `music` 拿 ID\r\n - 例：`control play`、`control player --action pause`、`control favorite song --mixsongid `、`control play-playlist --global-id `\r\n - **请求类型 B：搜索后做某件事**（搜索歌曲/推荐/榜单 → 拿到 ID 后再做后续动作，如播放、收藏、建歌单）→ 先执行 `music` 命令拿数据，再按需转 `control`，详见 [references/music.md](references/music.md)\r\n - 例：先 `music search` 拿 mixsongid，再 `control play` 播放\r\n - 例：先 `music search-playlist` 拿 global_id，再 `control play-playlist` 播放\r\n - 例：先 `music search` 拿 mixsongids，再 `control playlist create --mixsongids` 创建客户端歌单\r\n - **请求类型 C：纯查询 / 统计 / 榜单**（不涉及本地客户端）→ 只走 `music` 命令\r\n7. 解析 JSON 输出，按展示规范展示给用户（详见 [references/output-format.md](references/output-format.md)）\r\n```\r\n\r\n> **关键提醒**：**不要**在没有 mixsongid / global_id 的情况下盲目调用 `control` 命令（如 `control play --mixsongid \"\"`）—— `control` 命令在 ID 缺失时会报错。先用 `music` 命令把 ID 查出来，再传给 `control`。\r\n\r\n---\r\n\r\n## 关键注意事项\r\n\r\n### 登录流程\r\n\r\n`auth login` 命令输出三个字段供 Agent 选择二维码展示方式（详见 [references/auth.md](references/auth.md)）：\r\n\r\n| 字段 | 用途 |\r\n|------|------|\r\n| `qrcode_img_path` | 本地二维码 PNG 文件路径 |\r\n| `qrcode_img_url` | 远程二维码图片 URL |\r\n| `qrcode` | 字符串标识，**Agent 不要使用**（仅供 CLI 内部） |\r\n\r\n**根据当前客户端能力选择一种方式，把二维码图片直接展示在聊天窗口中**：\r\n\r\n- 客户端支持读取或附加本地图片（如 Codex）→ 使用 `qrcode_img_path`，通过客户端的本地图片读取/附件能力展示\r\n- 客户端支持 Markdown 外链图片（如 WorkBuddy）→ 在消息正文中输出 `![酷狗登录二维码]()`\r\n- Agent 可以自行选择最适合当前环境的方式，不要同时展示两张二维码\r\n- **不要**只把 URL 或本地路径作为普通文本发给用户，用户应直接看到二维码图片\r\n- 首选方式展示失败时，立即切换到另一种方式：远程图片加载失败则尝试读取本地图片，本地图片无法读取则尝试远程 Markdown 图片\r\n- 若两种方式都不可用 → 告诉用户\"当前环境无法显示二维码，请提供 base64 secret 字符串\"，改走 `auth set-secret`\r\n\r\n**`auth status` 的调用约束**：\r\n\r\n- 每次调用只查一次扫码状态，**不会内部自动轮询**。Agent 需要在外层按\"阶段 A → 阶段 B → 阶段 C\"循环调用（详见上方工作流第 4 步）\r\n- 阶段 B 之后**不要**自己继续调用 status，等用户回复\r\n\r\n### 直接导入 secret 登录\r\n\r\n当用户**已经持有**一个有效的 base64 secret 字符串（从别处获取的），直接调用 `kugou-cli auth set-secret \"\"` 即可完成登录，**跳过扫码流程**——效果与扫码登录完全一致。secret 字符串含 `+` `/` `=` 是正常的，shell 里务必用引号包起来。\r\n\r\n**何时考虑用 set-secret**：\r\n\r\n- 用户明确说\"我有 secret\"\r\n- 当前环境既无法展示远程图片也无法读取本地图片\r\n- 用户之前已经登录过想换设备\r\n\r\n### 登出\r\n\r\n`auth logout` 命令：先与服务端同步登出，**确认成功后才**清理登录状态。失败时登录状态保留、可重试；未登录时幂等直接返回成功。\r\n\r\n### 登录态自动失效\r\n\r\n当任意 `music` 命令遇到登录态过期时，CLI 会自动取消登录（退出码非 0 + stderr 提示登录已过期）。Agent 收到该错误后：\r\n\r\n1. **不要**自己再调一次 `music` 命令（会再次失败）\r\n2. **直接**引导用户重新登录：先问\"你手上是否已有新 secret？\"，有则 `auth set-secret`，没有则 `auth login` 走扫码\r\n3. 重新登录后，**先调 `auth status` 确认** `logged_in: true`，再重试之前失败的 `music` 命令\r\n\r\n> 错误判定以退出码 + references/error-handling.md 中的错误码说明为准，**不要**依赖 stderr 文案字面量匹配。\r\n\r\n### 音乐命令依赖登录\r\n\r\n除了 `auth`、`install`、`version`、`--help` 以外，所有 `music` 子命令都需要先登录。如果 CLI 返回\"未登录\"错误，引导用户执行登录流程。\r\n\r\n### 输出格式与成功判定\r\n\r\n所有命令输出原始 JSON 到 stdout，错误输出到 stderr。**成功判定以退出码和 JSON 内的成功状态字段为准**（详见 [references/output-format.md](references/output-format.md)）。\r\n\r\n### 歌曲/歌单展示规范\r\n\r\n向用户展示音乐命令返回的歌曲列表或歌单列表时，按以下规则（详见 [references/output-format.md §1](references/output-format.md)）：\r\n\r\n- **结果 ≥ 2 条** → 用 Markdown 表格展示\r\n - 歌曲表格列：`| 序号 | 歌曲名 | 歌手 |`\r\n - 歌单表格列：`| 序号 | 歌单名 | 创建人昵称 |`\r\n - **表格内的歌曲名 / 歌单名一律不加链接**（避免列宽过长、可读性差；详见下方解释）\r\n- **结果 = 1 条** → 用单行 Markdown 链接展示\r\n - 有客户端（探测结果 `client_available = true`）→ 歌曲名/歌单名**不加链接**（可直接调 `control play` 等本地命令）\r\n - 无客户端（探测结果 `client_available = false`）→ 歌曲名/歌单名**必须加链接**，方便用户手动打开\r\n - 歌曲正确格式：`[歌曲名 - 歌手名](https://www.kugou.com/...)`\r\n - 歌单正确格式：`[歌单名]()`\r\n- **结果 = 0 条** → 告诉用户\"未找到结果\"，不需要展示表格或链接\r\n\r\n#### 为什么表格不加链接？\r\n\r\n- 表格单元格加 Markdown 链接会让列宽自适应 URL，中文长字符串下表的可读性变差\r\n- 表格场景下用户通常是要**浏览/筛选**，ID 由 agent 内部持有，等用户明确说\"播放这首\" / \"打开这个歌单\"再走对应命令\r\n\r\n#### 客户端可用性探测怎么用？\r\n\r\n- **首次**要展示歌曲/歌单列表前，按工作流第 5 步跑 `kugou-cli control detect`，记下 `client_available`\r\n- 单条结果（= 1）时根据 `client_available` 决定加不加链接\r\n- 表格结果（≥ 2）时**无视** `client_available`，表格单元格不加链接\r\n- 探测结果**不**影响用户主动调用 `control *` 命令的逻辑——那是另一条独立路径（由 `control start` 自己报错）\r\n\r\n### 播放 / 切歌后必须告知当前曲目\r\n\r\n**触发条件**：以下命令**成功后**必须告知用户当前正在播放的歌曲：\r\n\r\n- `control play`（播放单首）\r\n- `control play-playlist`（播放整个歌单）\r\n- `control continue-play`（续播另一设备列表）\r\n- `control player --action next/prev`（切歌）\r\n\r\n**操作**：调用 `kugou-cli control current` 拿到 `song_name` / `singer_name`，向用户输出：\r\n\r\n> � 正在播放：<歌曲名> - <歌手>\r\n\r\n**注意**：\r\n- **必须**用 `control current` 重新拿当前曲目，**不要**用 `control play` 命令里 `--song-name` / `--singer-name` 字段直接展示——后者只是客户端展示用的标签，**不保证与实际播放一致**（特别是播放歌单 / 续播 / 切歌之后）\r\n- 若 `control current` 返回非 `code: 0`（如客户端断开 / 命令未支持），告知用户\"已开始播放（无法读取当前曲目详情）\"，不要假装知道\r\n\r\n详见 [references/control.md §3 current](./references/control.md#3-current--获取当前播放)。\r\n\r\n### 推荐理由规范\r\n\r\n仅在 agent **主动推荐**场景下，歌曲列表之后**必须**追加一段 220-260 字的推荐理由（详见 [references/output-format.md#5-推荐理由主动推荐场景必写](references/output-format.md#5-推荐理由主动推荐场景必写)）：\r\n\r\n- **触发**：`recommend guess / similar / text`、`charts`、`recommend-playlist`\r\n- **不触发**：`search` / `search-playlist` / `favorites` / `recent` / `stats` / `playlist-songs`——用户主动查询不写\r\n- **三层内容**：整体歌曲风格 + 匹配逻辑 + 挑 2-3 首基于行业认知的解读\r\n- **字数硬约束**：220-260（含标点），超出或不足需重写\r\n\r\n### 创建歌单的调用原则\r\n\r\n详见 [references/music.md#7-创建歌单](references/music.md#7-创建歌单)：\r\n\r\n1. **被动调用**：必须用户**明确**要求创建歌单时才调用，禁止在用户仅说\"推荐/搜歌\"时主动创建\r\n2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户是否需要将当前这批歌曲创建为歌单，等用户确认后再调用\r\n3. **硬性默认：优先客户端创建**：用户同意后**必须先尝试** `kugou-cli control playlist create`（在本地酷狗客户端内创建，详见 [references/control.md#10-playlist-create--创建歌单](references/control.md#10-playlist-create--创建歌单)），仅当客户端不可用（不支持的操作系统 / 未运行 / 无响应 / 调用失败）时才回退到云端 `music create-playlist`\r\n4. **创建成功后主动询问是否播放**：无论走 `control playlist create` 还是 `music create-playlist`，**创建成功（返回成功状态）后必须主动询问用户\"是否要播放这个歌单\"**，等用户明确回复后再决定走哪条播放命令；用户拒绝则不做任何动作。播放路径选择：\r\n - 客户端可用：优先 `kugou-cli control play-playlist --global-id \"\"`（详见 [references/control.md#12-play-playlist--播放整个歌单](references/control.md#12-play-playlist--播放整个歌单)）\r\n - 客户端不可用 / `play-playlist` 拿不到可用 ID：按 [references/music.md#72-云端歌单的播放控制浏览器打开-h5-链接](references/music.md#72-云端歌单的播放控制浏览器打开-h5-链接) 走\"先探后告知\"——用浏览器工具打开 H5 `song_list_url` 尝试点击播放；工具不可用时明确告知用户手动复制链接打开\r\n\r\n### 调整偏好的调用原则\r\n\r\n详见 [references/music.md#11-提交偏好](references/music.md#11-提交偏好)：\r\n\r\n1. **被动调用**：必须用户**明确**表达偏好调整意愿时才调用 `kugou-cli music submit-preference`，禁止在用户仅说\"推荐/搜歌/听歌\"时主动改写用户偏好\r\n2. **解析用户意图 → 落到 dimension/degree/name**：按 [references/music.md#11-提交偏好 调用流程](references/music.md#11-提交偏好) 里的\"用户原话 → dimension/degree/name\"映射表翻译，不确定时**主动询问**（\"你说的『少推点 XX』是指歌手还是语种/曲风？\"）\r\n3. **name 用服务端能识别的标准名**：用户口语里的昵称/简称（\"老周\"）必须**先问清楚**再调，因为上游 name 必须是服务端能识别的标准名（如\"周杰伦\"）\r\n4. **weight-ratio 配对**：reduce→`(0,1)`、forbid/add→`(1,2)`。不匹配时 CLI 仅 warning 不阻断，最终以服务端校验为准\r\n5. **提交成功后的呈现优先级**：\r\n - **第一优先**：用响应 `data.msg`（上游确认话术）展示给用户，例如\"收到！将减少推荐歌手「周杰伦」的歌曲，猜你喜欢以下歌曲~\"\r\n - **第二优先**：把响应 `data.list`（重新推荐的歌曲列表）按 [references/output-format.md#1-歌曲歌单列表展示批量优先用表格](references/output-format.md#1-歌曲歌单列表展示批量优先用表格) 的展示规范呈现（≥ 2 条用表格，= 1 条按 `client_available` 决定加不加链接）\r\n - 表格里**不**加 `` 高亮 / `play_link` / `mix_song_id`，agent 内部持有\r\n6. **复用 list，不要再调 recommend**：拿到新推荐的 `list[]` 后，**主动询问**用户\"要按这个新偏好播放一些吗？\"，用户同意后**直接用 list[] 里的 `mix_song_id`** 走 [`control play`](./references/control.md#1-play--播放指定歌曲) 等命令，**不要**再调一次 `recommend` 浪费调用\r\n7. **多次提交会叠加**：本接口是**实时反馈**给推荐引擎，不会持久化为用户画像规则；同一歌手多次提交会**叠加效果**，不要替用户循环重提\r\n\r\n### 能力边界提示\r\n\r\n当用户提出的需求在 `kugou-cli` **整体能力边界之外**时，Agent 必须**明确告知用户\"暂不支持该能力\"**，不得擅自用其他命令拼凑代替，也不得假装能完成。\r\n\r\n**典型场景**：\r\n\r\n- `kugou-cli` 没有对应子命令（用户要的功能不在 `auth` / `music` / `control` / `install` 任何子命令中）\r\n- `control` 子命令在当前操作系统不支持（如 `control` 系列仅支持 Windows / macOS，Linux 不支持）\r\n- 命令存在但参数 / 取值已下线（如 `control open --target-type url` 已被移除）\r\n- CLI 整体没有相关云端 API（如批量下载、歌词编辑、播客等）\r\n\r\n**正确回应**：\r\n\r\n> 这个能力 kugou-cli 暂不支持。如果你需要该功能，可以去酷狗客户端里手动操作。\r\n\r\n**反例（不要这样做）**：\r\n\r\n- 不要用「推荐相似歌曲」伪装成「按场景生成歌单」之类的能力替代\r\n- 不要反复尝试不同参数 / 多次重试来\"碰运气\"绕过不支持\r\n- 不要把 CLI 报错（\"unknown flag\" / \"unsupported\"）原样翻译后甩给用户——先判断这是\"能力不存在\"还是\"用法不对\"再回应\r\n\r\n**与「客户端不可用」的区别**：本节是「命令/能力本身不存在」；「客户端不可用」是「命令存在但本机客户端未运行 / 未登录」，后者有 fallback 路径（详见上方「创建歌单的调用原则」第 3 条 + [references/control.md](references/control.md)）。两者不要混用。\r\n\r\n---\r\n\r\n## 基础信息\r\n\r\n- **npm 包**: @kg-ai/kugou-skill\r\n- **二进制命令**: kugou-cli\r\n- **安装方式**: `npm install -g @kg-ai/kugou-skill`\r\n\r\n> 关于更新：CLI 安装后会自动保持最新。具体行为与关闭开关见 [references/update.md](references/update.md)。如有版本相关问题，向该文档查证。\r\n\r\n---\r\n\r\n## 详细文档索引\r\n\r\n| 文档 | 说明 |\r\n|------|------|\r\n| [references/auth.md](references/auth.md) | 认证命令：扫码登录、直接设置 secret、查看状态、登出 |\r\n| [references/music.md](references/music.md) | 音乐命令：搜索、推荐、收藏、统计、榜单、创建歌单 |\r\n| [references/control.md](references/control.md) | 控制命令：控制 PC/Mac 客户端播放、暂停、切歌、收藏、创建歌单等 |\r\n| [references/install.md](references/install.md) | 安装命令：SKILL.md 安装到各平台 |\r\n| [references/update.md](references/update.md) | 更新行为、版本检查、关闭自动更新 |\r\n| [references/output-format.md](references/output-format.md) | 输出格式与展示规范 |\r\n| [references/error-handling.md](references/error-handling.md) | 错误处理与常见错误 |\r\n\r\n---\r\n\r\n## 完整使用流程\r\n\r\n```bash\r\n# 1. 登录（详见 references/auth.md）\r\nkugou-cli auth login # 获取二维码\r\nkugou-cli auth status\r\n\r\n# 1'. 或者直接导入已持有的 secret（跳过扫码）\r\nkugou-cli auth set-secret \"\"\r\n\r\n# 2. 搜索歌曲\r\nkugou-cli music search \"周杰伦\"\r\n\r\n# 3. 获取猜你喜欢\r\nkugou-cli music recommend guess\r\n\r\n# 4. 查看我的收藏（返回最近若干首，不支持分页）\r\nkugou-cli music favorites\r\n\r\n# 5. 查看最近播放（返回最近若干条，不支持分页）\r\nkugou-cli music recent\r\n\r\n# 6. 查看听歌统计\r\nkugou-cli music stats\r\n\r\n# 7. 查看抖音热歌榜\r\nkugou-cli music charts 52144\r\n\r\n# 8. 创建歌单\r\n# 优先走客户端路径（默认）：见 references/control.md §10\r\nkugou-cli control playlist create --name \"我的批量歌单\" --mixsongids \"32068120,233125060\"\r\n# 客户端不可用时才回退到云端（详见 references/music.md §7.1）：\r\nkugou-cli music create-playlist \"我的空歌单\"\r\nkugou-cli music create-playlist \"我的批量歌单\" --songs \"32068120,233125060\"\r\n\r\n# 9. 搜索歌单（拿到 global_id 后可透传给 control play-playlist）\r\nkugou-cli music search-playlist \"周杰伦\"\r\nkugou-cli music playlist-songs \"collection_3_938985631_304_0\"\r\n\r\n# 10. 控制本机酷狗客户端（仅 Windows / macOS，详见 references/control.md）\r\nkugou-cli control play --mixsongid 32100650 --song-name \"晴天\" --singer-name \"周杰伦\"\r\nkugou-cli control player --action pause\r\nkugou-cli control favorite song --mixsongid 32100650\r\n\r\n# 11. 调整音乐偏好（用户明确表达\"少推点/别再推/多推点\"时调用，详见 references/music.md#11-提交偏好）\r\nkugou-cli music submit-preference --dimension singer --degree reduce --name \"周杰伦\" --weight-ratio 0.5\r\nkugou-cli music submit-preference --dimension language --degree add --name \"粤语\" --weight-ratio 1.8\r\n```\n\nFile v0.1.20:_meta.json\n\n{\n \"ownerId\": \"kn7crmv8zas1ep290wm2ag0wtn88te0q\",\n \"slug\": \"kugou-skill\",\n \"version\": \"0.1.20\",\n \"publishedAt\": 1789355075881\n}\n\nFile v0.1.20:references/auth.md\n\n# 认证命令 (auth)\r\n\r\n> 🔐 = 需要先登录\r\n\r\n## 命令列表\r\n\r\n| 命令 | 说明 | 需要登录 |\r\n|------|------|---------|\r\n| `kugou-cli auth login` | 获取二维码（`qrcode` 内部字符串 + `qrcode_img_url` 远程图片 URL + `qrcode_img_path` 本地 PNG 路径） | 否 |\r\n| `kugou-cli auth status` | 检查登录状态（**单次查询，不内部轮询**，agent 需外层循环 2-3s 间隔） | 否 |\r\n| `kugou-cli auth set-secret ` | 直接导入已持有的 base64 secret 登录（跳过扫码） | 否 |\r\n| `kugou-cli auth logout` | 登出 | 否 |\r\n\r\n---\r\n\r\n## 1. 扫码登录\r\n\r\n登录流程极简：\r\n\r\n```bash\r\n# Step 1: 获取二维码，同时得到远程 URL 和本地 PNG 路径\r\nkugou-cli auth login\r\n\r\n# Step 2: 循环调用 status（**单次查询不内部轮询**，agent 自己外层循环）\r\n# 每次间隔 2-3 秒，看到 logged_in=true / status=success 即完成\r\nkugou-cli auth status\r\n```\r\n\r\n**auth login 输出示例**:\r\n```json\r\n{\"qrcode\": \"xxx\", \"qrcode_img_path\": \"C:\\\\Temp\\\\kugou-qrcode.png\", \"qrcode_img_url\": \"https://static.kugou.com/.../qrcode.png\"}\r\n```\r\n\r\n字段说明：\r\n- `qrcode`：二维码字符串标识，**Agent 不要使用** —— 仅供 CLI 内部持久化，以便后续 status 调上游 check 接口\r\n- `qrcode_img_path`：CLI 生成的本地二维码 PNG 文件绝对路径。当前客户端支持读取或附加本地图片时使用它，例如 Codex 等本地文件能力较强的客户端\r\n- `qrcode_img_url`：酷狗上游返回的远程二维码图片 URL。当前客户端支持 Markdown 外链图片时使用它，例如 WorkBuddy 等客户端\r\n- `qrcode_img_path` 和 `qrcode_img_url` 是两种并行的图片展示方式，Agent 根据当前客户端能力自行选择一种，不要同时展示两张二维码\r\n\r\n---\r\n\r\n## 2. AI 引导流程\r\n\r\n### 2.1 决策点：先问 secret，再选路径\r\n\r\n在调用任何 auth 命令之前，**先询问用户**：\r\n\r\n> \"你手上是否已有可用的 base64 secret 字符串？（从其他设备/工具导出的）\"\r\n\r\n- **用户明确说\"有\"** → 直接走 §3 `set-secret`，跳过 §1 扫码\r\n- **用户说\"没有\"或不确定** → 走 §2.2 扫码流程\r\n- **当前环境无法发送图片**（纯文本 agent、SSH 远端、容器）→ 强制走 §3 `set-secret`，不要走扫码\r\n\r\n> **默认行为**：除非用户明确说\"我有 secret\"，否则优先走扫码。\r\n\r\n### 2.2 扫码流程\r\n\r\n1. 调用 `auth login`，读取返回的 `qrcode_img_path` 和 `qrcode_img_url`\r\n2. **根据当前客户端能力选择一种方式展示二维码图片**：\r\n - 客户端支持读取或附加本地文件（如 Codex 等）→ 优先使用 `qrcode_img_path`，通过客户端的本地图片读取/附件能力展示。不要只把路径作为普通文本发给用户\r\n - 客户端支持 Markdown 外链图片（如 WorkBuddy 等）→ 使用 `qrcode_img_url`，在消息中输出 `![酷狗登录二维码]()`\r\n - Agent 可以自行选择最适合当前环境的方式，不要同时展示两张二维码\r\n - **避免**只输出“请打开 xxx URL”或“图片路径是 xxx”这种纯文字提示，用户应直接看到二维码图片\r\n - 选择的方式展示失败时，切换到另一种方式：远程图片加载失败则尝试本地文件，本地文件无法读取则尝试远程 Markdown 图片\r\n - 如果当前客户端既不能读取本地文件，也不能渲染远程 Markdown 图片 → 放弃扫码，切换到 §3 `set-secret` 路径\r\n3. **阶段 A — 主动轮询（覆盖秒扫）**：图片展示后，**主动**外层循环调用 `auth status`，每次间隔 2-3 秒，**最多 5 次**（与 `failed` 重试合并计数）：\r\n - 看到 `logged_in: true` → 完成，继续执行用户请求\r\n - 看到 `status: success` → 完成，继续执行用户请求\r\n - 看到 `status: scanned` → 等几秒再调一次 status\r\n - 看到 `status: failed` → **不要换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（计入 5 次轮询预算）\r\n - 看到 `status: expired` → **不再继续轮询**，主动告诉用户\"二维码已失效，正在重新获取\"，调 `auth login` 拿新图，回到步骤 1\r\n - 5 次都是 `waiting` / `failed` → 进入阶段 B\r\n4. **阶段 B — 等待用户反馈（关键）**：5 次主动轮询后仍未登录，**停下来**，不再调任何 auth 命令。主动告诉用户：\r\n > \"请用酷狗 APP 扫码登录，扫完后告诉我已扫码\"\r\n 然后**等用户主动回复**。**不要**自己继续轮询。\r\n5. **阶段 C — 验证登录**：用户回复\"已扫码\"后，调一次 `auth status` 验证：\r\n - `logged_in: true` → 完成，继续执行用户请求\r\n - `status: scanned` → 用户在手机上还没点确认，等几秒再调一次\r\n - `status: failed` → **不要换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（最多重试 2-3 次）\r\n - `status: expired` → 上游明确说过期（CLI 已清理本地），重新 `auth login` 拿新图，回到步骤 1\r\n - `logged_in: false`（无 status 字段）→ qrcode 已被清理（通常是上一步 `expired` 后状态），提示用户\"二维码可能已过期，正在重新获取\"并回到步骤 1\r\n6. **若用户在阶段 B 回复\"没看到图片\" / \"图片打不开\"** → 先切换到另一种二维码展示方式；两种方式都失败后，再切换到 §3 `set-secret` 路径\r\n7. **若用户在阶段 B 回复\"已扫码\"**但阶段 C 验证发现没登录成功（`scanned` / `failed`），按阶段 C 各项处理，不要替用户做\"再扫一次\"之类的猜测\r\n\r\n### 2.3 状态表\r\n\r\n| 返回 | 含义 | Agent 应做 |\r\n|------|------|-----------|\r\n| `{\"logged_in\": true, \"nickname\": \"...\", \"login_time\": \"...\"}` | 已登录（**已有 token 持久化**，通常是之前登录过） | 继续执行用户请求 |\r\n| `{\"logged_in\": true, \"status\": \"success\", \"nickname\": \"...\"}` | 扫码刚完成登录（**本轮 status 检查中完成 token 持久化**） | 继续执行用户请求 |\r\n| `{\"logged_in\": false, \"status\": \"waiting\", \"qrcode\": \"...\"}` | 二维码待扫码 | **阶段 A**：2-3s 后重试 status，最多 5 次；5 次后**进入阶段 B**，停下来等用户主动反馈 |\r\n| `{\"logged_in\": false, \"status\": \"scanned\", \"nickname\": \"...\", \"qrcode\": \"...\"}` | 已扫码待确认 | 等几秒再调一次 status（用户还没在手机上点确认） |\r\n| `{\"logged_in\": false, \"status\": \"expired\", \"message\": \"...\"}` | 二维码被上游明确判定为过期（**CLI 会自动清理本地 qrcode**） | **不再重试**：调 `auth login` 拿新图（覆盖本地 qrcode），回到 §2.2 步骤 1 |\r\n| `{\"logged_in\": false, \"status\": \"failed\", \"message\": \"...\"}` | 上游返回了 CLI 不识别的 status 码（**CLI 不会清理本地 qrcode**，本地缓存仍可用） | **重试** 1-2 秒后再调一次 status（用同一个本地 qrcode）；阶段 A 中计入 5 次预算，阶段 C 中最多 2-3 次。**不要调 `auth login` 换新图** |\r\n| `{\"logged_in\": false}` | 无登录态（未登录过 / 登录过期被清理 / qrcode 刚被 expired 清理掉） | 走完整登录流程（§2.1 决策点） |\r\n\r\n> **判定\"已登录\"**：`logged_in: true` 即算成功，**不管有没有 `status: success` 字段**——两种 JSON shape 都合法。\r\n>\r\n> 区分\"无登录态\"和\"等待扫码\"的关键：前者**没有** `status` 字段，后者有。\r\n>\r\n> **轮询逻辑（两阶段）**：\r\n> - 阶段 A：图片刚展示，主动循环 status 最多 5 次（2-3s 间隔）→ 覆盖秒扫场景\r\n> - 阶段 B：5 次仍 `waiting` → 主动告诉用户\"请扫码登录，扫完后告诉我已扫码\"，**不再调 status**，等用户**主动回复**\r\n\r\n### 2.3.1 边界提醒：`expired` 会清掉 qrcode 并需换新图，`failed` 不清且应重试\r\n\r\n**关键事实**：\r\n\r\n- `status: expired` 时 CLI 会自动清理本地 qrcode 文件（**不是清理登录态**）。这是上游**明确**判定二维码失效（协议层不可恢复）→ **必须换新图**。\r\n- `status: failed` 时 CLI **不会**清理本地 qrcode 文件。这是上游返回了 CLI 不识别的 status 码（短暂异常 / 未知协议值 / 上游 gateway 抖动）。本地 qrcode 字符串**没失效** → **不应换新图，应重试同一 qrcode**。\r\n\r\n**两种返回在阶段 A / 阶段 C 的处理**：\r\n\r\n| 见到位置 | 状态值 | 原因可能性 | Agent 应做 |\r\n|---------|--------|-----------|-----------|\r\n| 阶段 A 主动轮询中 | `expired` | 上游明确说过期 | **不再继续轮询**，主动告诉用户\"二维码已失效，正在重新获取\"，调 `auth login` 拿新图，回到 §2.2 步骤 1 |\r\n| 阶段 A 主动轮询中 | `failed` | 上游短暂异常 / 未知 status 码 | **不换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（计入阶段 A 的 5 次主动轮询预算） |\r\n| 阶段 C 用户说\"已扫码\"后验证 | `expired` | 登录过程中上游判定过期 | 重新 `auth login` 拿新图 |\r\n| 阶段 C 用户说\"已扫码\"后验证 | `failed` | 登录过程中上游返回非预期 | **不换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status，最多重试 2-3 次；仍 `failed` 再按上游持续异常处理（建议告诉用户稍后重试或切 `set-secret`） |\r\n| 阶段 A 之后阶段 B 之前 | `expired` / `failed` | （不应发生） | 视为阶段 A 见到对应状态值处理 |\r\n\r\n> **判定要点**：\r\n> - 不要因为\"看到 expired/failed → 看到 logged_in: false\"就误判\"用户没登录\"。expired/failed 都是 qrcode 状态，不是登录态。\r\n> - `expired` 后下次 `auth status` 会拿到 `{\"logged_in\": false}`（无 status 字段，本地已被清）。\r\n> - `failed` 后下次 `auth status` **可能仍返回 failed**（上游持续异常），也可能恢复 `waiting`（上游恢复后用同一个 qrcode 仍可扫码登录）。**不要假设 `failed` 后本地一定被清**。\r\n> - 关键决策：`expired` 是**协议层不可恢复** → 换新图；`failed` 是**传输层/未知码** → 重试同一 qrcode。\r\n\r\n### 备选路径：用户已持有 secret\r\n\r\n当用户**已经持有**一个有效的 base64 secret 字符串时（例如从其他设备、其他工具导出的），可以直接用 `auth set-secret` 跳过整个扫码流程，**不需**调用 `auth login` / `auth status`：\r\n\r\n```bash\r\nkugou-cli auth set-secret \"\"\r\n```\r\n\r\n调用成功后 secret 会被持久化（路径见 §3），所有 music 命令立即可用，效果与扫码登录一致。\r\n\r\n---\r\n\r\n\r\n## 3. 直接设置 secret\r\n\r\n**适用场景**：\r\n- 用户在其他设备/工具上已登录酷狗，导出或复制了一份 base64 secret\r\n- 测试、调试、自动化场景下需要直接注入 secret\r\n- 任何不便于扫码的终端环境（如 SSH 远端、容器、CI）\r\n- 当前 agent 工具集无法渲染 `qrcode_img_url` 远程图片，或无法读取 `qrcode_img_path` 本地图片（不联网、不支持 Markdown 渲染或不支持本地图片附件，见 §2.2）\r\n\r\n**命令**:\r\n\r\n```bash\r\nkugou-cli auth set-secret \"{secret}\"\r\n```\r\n\r\n**shell 引号注意事项**：\r\n- secret 字符串含 `+`、`/`、`=` 等 base64 字符是**正常的**，**不会**被 shell 误解析\r\n- 但 `+` 在 bash 中是通配符、`=` 在 cmd.exe 中会触发变量赋值，**务必用引号包起来**\r\n- 推荐使用双引号 `\"...\"`（除非 secret 中含 `$`，那就用单引号 `'...'`）\r\n\r\n**输出示例**:\r\n```json\r\n{\"status\": \"ok\", \"message\": \"secret saved\"}\r\n```\r\n\r\n**失败示例**（secret 为空）:\r\n```\r\nsecret cannot be empty\r\n```\r\n\r\n**与扫码登录的等价性**：\r\n- secret 落到本地登录态文件，**跨平台位置**：\r\n - Linux/macOS：`~/.config/kugou-cli/auth.json`\r\n - Windows：`%AppData%\\kugou-cli\\auth.json`（通常为 `C:\\Users\\\\AppData\\Roaming\\kugou-cli\\auth.json`）\r\n - 若用户询问\"登录态存在哪\"，按平台给对应路径，**不要**直接说 `~/.config/...` 在 Windows 下不准确\r\n- 后续 `auth status` 输出 `{\"logged_in\": true}`\r\n- 所有 `music` 子命令立即可用，无需任何额外步骤\r\n- nickname 字段为空（因为导入途径不带昵称），不影响功能\r\n\r\n**登录态过期处理**：\r\n- 当任意 `music` 命令遇到登录态过期时，CLI 会**自动清理**本地登录态，并在 stderr 输出 `账号登录过期，请重新登录`，以非 0 exit code 退出\r\n- Agent 收到该错误后应**直接引导用户重新登录**（`auth login` 走扫码，或 `auth set-secret` 导入新 secret），无需手动清理本地文件\r\n- 之后调用 `auth status` 会得到 `{\"logged_in\": false}`（**无 status 字段**，对应 §2.3 状态表最后一行）\r\n\r\n---\r\n\r\n## 4. 登出 (logout)\r\n\r\n**命令**：\r\n\r\n```bash\r\nkugou-cli auth logout\r\n```\r\n\r\n**行为**：\r\n1. **未登录时**：幂等直接返回 `{\"status\": \"logged out\"}`\r\n2. **已登录时**：CLI 会先与服务端同步登出，**确认成功后才**清理本地登录态。任何一步失败都会在 stderr 报错并保留本地登录态，以便用户重试\r\n3. 成功输出：`{\"status\": \"logged out\"}`\r\n\r\n**失败场景**：\r\n- 网络/服务端异常 → stderr 报错，**不清理**本地，提示用户稍后重试\r\n- 此时再次执行 `auth status` 仍会显示 `logged_in: true`，本地登录态被保留\r\n\r\n**AI 引导建议**：\r\n- 用户说\"登出 / 退出登录 / 注销\"时直接执行 `auth logout`\r\n- 看到 `{\"status\": \"logged out\"}` 后，告诉用户已成功登出，可继续 `auth login` 重新登录\r\n- 看到错误时：\r\n 1. **自动重试 1 次**（网络抖动常见）\r\n 2. 仍失败 → 告知用户\"登出失败，本地登录态保留，可能是网络问题\"，**询问**用户：\"是否要稍后重试？\"\r\n 3. **不要**擅自清理本地文件或调任何 music 命令\n\nFile v0.1.20:references/control.md\n\n# 控制命令 (control)\r\n\r\n> AI-facing usage guide for `kugou-cli control` — the local PC/Mac Kugou client control subcommands.\r\n\r\n本模块通过本机 HTTP server 控制 PC/Mac 酷狗客户端，支持播放控制、收藏管理、歌单创建等操作。输出格式为原始 JSON（详见 [references/output-format.md](./output-format.md)）。\r\n\r\n**前置条件**: CLI 已登录（`kugou-cli auth login`）+ 酷狗客户端正在运行。仅支持 Windows / macOS（Linux 运行时会报错，见下方错误场景）。\r\n\r\n---\r\n\r\n## 命令列表\r\n\r\n### 读操作（read）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control start` | 显式触发握手/唤起客户端（用于预热或调试） |\r\n| `kugou-cli control status` | 获取客户端状态（协议版本、登录态、能力列表） |\r\n| `kugou-cli control current` | 获取当前播放歌曲（歌名、进度、音量、收藏状态） |\r\n\r\n### 播放器控制（player）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control play` | 播放歌曲（按 mixsongid） |\r\n| `kugou-cli control play-playlist` | 播放整个歌单（按 global_collection_id） |\r\n| `kugou-cli control continue-play` | 拉取\"另一设备续播\"列表并开始播放 |\r\n| `kugou-cli control player` | 播放器控制（播放/暂停/切歌/停止） |\r\n| `kugou-cli control seek` | 进度控制（快进/快退/跳转） |\r\n| `kugou-cli control volume` | 音量控制（增减/设置/静音） |\r\n\r\n### 账户操作（account）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control favorite song` | 收藏/取消收藏歌曲 |\r\n| `kugou-cli control favorite songlist` | 收藏/取消收藏歌单 |\r\n| `kugou-cli control playlist create` | 创建本地歌单（带歌曲列表） |\r\n\r\n### 系统操作（utility）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control open` | 打开客户端内页面（主界面/歌手/专辑/歌单/搜索） |\r\n| `kugou-cli control doctor` | 诊断 `control start` 失败的根因（HVCI / VBS / launcher / home-dir） |\r\n\r\n---\r\n\r\n## 1. start — 显式触发握手\r\n\r\n触发酷狗客户端的 URL scheme 唤起，等待客户端建立本机 HTTP 通道并返回状态。仅用于预热通道或调试连通性，不调用任何 `/v1/...` 业务接口。\r\n\r\n```bash\r\nkugou-cli control start\r\n```\r\n\r\n**输出示例**（成功）:\r\n```json\r\n{\"handshake\":\"ok\",\"addr\":\"http://127.0.0.1:52144\"}\r\n```\r\n\r\n**输出示例**（失败）:\r\n```\r\nkugou-cli control: not logged in, run `kugou-cli auth login` first: auth file not found\r\n```\r\n\r\n**`start` 失败时优先跑 `control doctor` 诊断根因**（见下文 §N）。常见场景：\r\n- Win11 Memory Integrity (HVCI) 开着 + 客户端 v20.1.40：HVCI 拦截客户端启动时访问的内存，触发 NTSTATUS 0xC0000005 → 关 HVCI 后重试\r\n- PowerShell 被裁掉（Windows Sandbox / AppContainer）：URL scheme 触发失败 → 自动 fallback 到 `cmd /c start`\r\n- $HOME / $USERPROFILE 未设置或不可写：握手文件无法落地 → 设置有效环境变量\r\n\r\n---\r\n\r\n## 2. status — 获取客户端状态\r\n\r\n查询本地酷狗客户端的协议版本、登录态和能力列表。\r\n\r\n```bash\r\nkugou-cli control status\r\n```\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"code\": 0,\r\n \"data\": {\r\n \"version\": \"1.0.0\",\r\n \"login\": true,\r\n \"capabilities\": [\"play\", \"pause\", \"seek\", \"volume\", \"favorite\", \"playlist\"]\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 3. current — 获取当前播放\r\n\r\n查询当前播放歌曲详情，包括歌名、歌手、进度、音量和收藏状态。\r\n\r\n```bash\r\nkugou-cli control current\r\n```\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"code\": 0,\r\n \"data\": {\r\n \"song_name\": \"晴天\",\r\n \"singer_name\": \"周杰伦\",\r\n \"mixsongid\": \"32100650\",\r\n \"position_ms\": 45000,\r\n \"duration_ms\": 240000,\r\n \"volume\": 65,\r\n \"favorited\": false\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 4. play — 播放歌曲\r\n\r\n在客户端播放一首歌曲。`--mixsongid` 必填，其余字段可选（仅用于客户端展示，不影响播放命中）。\r\n\r\n```bash\r\nkugou-cli control play --mixsongid 32100650 --song-name \"晴天\" --singer-name \"周杰伦\"\r\nkugou-cli control play --mix-song-id 32100650 --mode \"append_queue\"\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--mixsongid` | 歌曲 mixsongid（必填），也支持 `--mix-song-id` 别名 |\r\n| `--song-name` | 歌曲显示名（可选） |\r\n| `--singer-name` | 歌手显示名（可选） |\r\n| `--mode` | 播放模式：`append_queue`（追加队列）、`next_play`（下一首播放） |\r\n\r\n> 🎵 **AI 必读**：命令成功后**必须**调 `control current` 拿到当前歌曲名/歌手，告知用户。**不要**直接展示 `--song-name` / `--singer-name` 参数——那只是客户端展示标签，与实际播放可能不一致。\r\n\r\n**输出示例**:\r\n```json\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n```\r\n\r\n---\r\n\r\n## 5. player — 播放器控制\r\n\r\n发送传输控制动作到播放器（播放/暂停/切歌等）。\r\n\r\n```bash\r\nkugou-cli control player --action pause\r\nkugou-cli control player --action next\r\nkugou-cli control player --action resume\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--action` | 动作（必填）：`play` `resume` `pause` `toggle` `next` `prev` `previous` `stop` |\r\n\r\n`prev` 和 `previous` 视为同义词。\r\n\r\n> 🎵 **AI 必读**：使用 `next` / `prev` / `previous` **切歌后**必须调 `control current` 拿到当前歌曲名/歌手，告知用户。`play` / `pause` / `resume` / `toggle` / `stop` 等切换播放状态的动作不需要告知曲目（曲目未变）。\r\n\r\n**输出示例**:\r\n```json\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n```\r\n\r\n---\r\n\r\n## 5.1 continue-play — 拉取另一设备续播列表并播放\r\n\r\n拉取云端\"另一设备最近播放\"的续播列表（酷狗首页的\"续接播放\"入口），并在本地客户端开始播放。\r\n\r\n```bash\r\n# 默认：替换当前队列，从头播放\r\nkugou-cli control continue-play\r\n\r\n# 不打断当前播放：把续播列表追加到本地队列尾部\r\nkugou-cli control continue-play --mode append_queue\r\n\r\n# 把续播列表插到当前曲目之后立即播放\r\nkugou-cli control continue-play --mode next_play\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--mode` | 队列策略：空（默认，替换队列）/ `append_queue`（追加队列尾部）/ `next_play`（下一首播放） |\r\n\r\n> 🎵 **AI 必读**：命令成功后**必须**调 `control current` 拿到当前歌曲名/歌手，告知用户。\r\n\r\n**前置条件**:\r\n- 已登录：`kugou-cli auth login`\r\n- 客户端内已登录（否则返回 409/4091\"login required\"，见错误场景 §2）\r\n- 本地客户端必须运行（`kugou-cli control start` 健康）\r\n\r\n**输出示例**:\r\n```json\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n```\r\n\r\n---\r\n\r\n## 6. seek — 进度控制\r\n\r\n控制当前播放歌曲的进度。\r\n\r\n```bash\r\n# 快进 30 秒\r\nkugou-cli control seek --action forward --offset-ms 30000\r\n\r\n# 快退 10 秒\r\nkugou-cli control seek --action rewind --offset-ms 10000\r\n\r\n# 跳转到 2 分钟位置\r\nkugou-cli control seek --action set --position-ms 120000\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--action` | 动作（必填）：`forward` `rewind` `set` |\r\n| `--offset-ms` | 偏移量（毫秒，forward/rewind 时必填） |\r\n| `--position-ms` | 绝对位置（毫秒，action=set 时必填） |\r\n\r\n---\r\n\r\n## 7. volume — 音量控制\r\n\r\n调整客户端音量或静音状态。\r\n\r\n```bash\r\n# 音量增加 5 格\r\nkugou-cli control volume --action up --delta 5\r\n\r\n# 音量减少 10 格\r\nkugou-cli control volume --action down --delta 10\r\n\r\n# 设置音量到 42\r\nkugou-cli control volume --action set --volume 42\r\n\r\n# 静音\r\nkugou-cli control volume --action mute\r\n\r\n# 取消静音\r\nkugou-cli control volume --action unmute\r\n\r\n# 切换静音状态\r\nkugou-cli control volume --action toggle_mute\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--action` | 动作（必填）：`up` `down` `set` `mute` `unmute` `toggle_mute` |\r\n| `--delta` | 音量变化量（up/down 时必填） |\r\n| `--volume` | 绝对音量 0-100（action=set 时必填；CLI 不做范围校验，由客户端夹取） |\r\n\r\n---\r\n\r\n## 8. favorite song — 收藏歌曲\r\n\r\n收藏或取消收藏一首歌曲。\r\n\r\n```bash\r\n# 收藏歌曲\r\nkugou-cli control favorite song --mixsongid 32100650 --song-name \"晴天\" --singer-name \"周杰伦\"\r\n\r\n# 取消收藏\r\nkugou-cli control favorite song --action remove --mixsongid 32100650\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--action` | 操作（默认 `add`）：`add` `remove` |\r\n| `--mixsongid` | 歌曲 mixsongid（必填） |\r\n| `--song-name` | 歌曲显示名（可选） |\r\n| `--singer-name` | 歌手显示名（可选） |\r\n\r\n---\r\n\r\n## 9. favorite songlist — 收藏歌单\r\n\r\n收藏或取消收藏一个歌单。\r\n\r\n```bash\r\n# 收藏歌单（action=add 时必填 --list-name 与 --owner-user-id）\r\nkugou-cli control favorite songlist --list-name \"精选\" --global-collection-id abcdef --owner-user-id 1286024014\r\n\r\n# 取消收藏（--global-collection-id 必填；--list-name / --owner-user-id 不允许传）\r\nkugou-cli control favorite songlist --action remove --global-collection-id abcdef\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--action` | 操作（默认 `add`）：`add` `remove` |\r\n| `--global-collection-id` | 歌单全局 ID（即协议层的 `list_gid`，`add` / `remove` 都必填） |\r\n| `--list-name` | 歌单显示名（**`action=add` 时必填**） |\r\n| `--owner-user-id` | 歌单所有者 ID（**`action=add` 时必填**；`action=remove` 时不允许传） |\r\n| `--list-icon` | 歌单图标 URL（可选） |\r\n| `--list-intro` | 歌单简介（可选） |\r\n| `--list-tags` | 歌单标签（可选） |\r\n\r\n> **校验**：CLI 在本地做严格校验，缺任一必填项都会 exit 1 报错：\r\n> - `--global-collection-id`：**`add` 和 `remove` 两种 action 都必填**（用于标识目标歌单）\r\n> - `--list-name`：仅 `--action=add` 必填\r\n> - `--owner-user-id`：仅 `--action=add` 必填；`--action=remove` 时**禁止**传（避免向取消请求带过时元数据）\r\n\r\n---\r\n\r\n## 10. playlist create — 创建歌单\r\n\r\n> ✅ **创建歌单的首选路径**。Agent 在用户同意创建歌单时**必须**先尝试本命令；只有当客户端不可用（Linux / 客户端未运行 / 握手失败 / 调用失败）时才回退到云端备选 [`music create-playlist`](./music.md#71-接口说明云端备选仅在-70-第-4-条任一条件成立时使用)。完整决策逻辑见 [music.md §7 创建歌单](./music.md#7-创建歌单)。\r\n\r\n在本地客户端创建一个新歌单，并可选地添加歌曲。\r\n\r\n```bash\r\nkugou-cli control playlist create --name \"周杰伦精选\" --mixsongids \"32100650,32068120\"\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--name` | 歌单名称（必填） |\r\n| `--mixsongids` | 歌曲 mixsongid 列表，逗号分隔（必填，至少含一个有效 ID） |\r\n\r\n`--mixsongids` 示例：`\"32100650,32068120\"` 或 `\"32100650, 32068120\"`（空格会被忽略）。\r\n\r\n**前置条件**（与 control 其他子命令一致，详见 [§前置条件总结](#前置条件总结)）：\r\n- CLI 已登录（`kugou-cli auth login`）\r\n- 本地酷狗客户端（Windows / macOS）正在运行且握手健康（`kugou-cli control start`）\r\n- 客户端内已登录（否则会收到 409/4091 `login required`，见 [§错误场景 2](#场景-2客户端未登录http-409--code-4091)）\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"code\": 0,\r\n \"data\": {\r\n \"accepted\": true,\r\n \"count\": 2,\r\n \"global_collection_id\": \"全局歌单id\",\r\n \"name\": \"歌单名\",\r\n \"songlist_id\": 123456\r\n },\r\n \"message\": \"ok\",\r\n \"request_id\": \"ec-124-1786072145\"\r\n}\r\n```\r\n\r\n> **字段语义说明（重要）**：\r\n> - `data.global_collection_id`：字符串形态的歌单全局 ID（协议层 `list_gid`），**可直接传给 `control play-playlist --global-id`**（详见 [§12 play-playlist](./control.md#12-play-playlist--播放整个歌单)）\r\n> - `data.songlist_id`：数字形态的本地客户端歌单 ID，**不能直接传给 `play-playlist --global-id`**，仅在客户端 UI 内展示用\r\n>\r\n> 实际响应字段由客户端版本决定，**两条不一定同时存在**——某些客户端版本可能只返回 `songlist_id` 而无 `global_collection_id`。Agent 在用户同意播放时优先取 `global_collection_id`；若缺失，按下方\"ID 流转提示\"回退。\r\n\r\n### 创建成功后必须主动询问用户是否播放\r\n\r\n> 🎵 **AI 必读**：本命令返回成功（`code: 0`）后，Agent **必须主动询问用户**\"是否要播放这个歌单\"，等用户明确回复后再决定下一步。详见 [music.md §7.0 调用原则 第 5 条](./music.md#70-调用原则ai-必读)。\r\n\r\n用户同意时优先调用：\r\n\r\n```bash\r\n# 客户端路径：默认清空当前队列、按歌单顺序从头播放\r\nkugou-cli control play-playlist --global-id \"\"\r\n\r\n# 不打断当前播放：把新歌单追加到队列尾部\r\nkugou-cli control play-playlist --global-id \"\" --playlist-mode append_queue\r\n```\r\n\r\n> **ID 流转提示**：本命令 `data.songlist_id` 是数字 ID，而 `control play-playlist --global-id` 需要的是字符串 `global_collection_id`（协议层 `list_gid`），二者不可直接互转。Agent 在用户同意播放时按以下顺序获取可用 ID：\r\n> 1. **优先**：取响应里 `data.global_collection_id`（字符串）→ 直接传给 `play-playlist --global-id`\r\n> 2. **回退一**：客户端未返回 `global_collection_id` 时，用响应里的歌单名（`data.name`）跑 `kugou-cli music search-playlist \"\"`，从结果里挑一个匹配的 `global_id` 传给 `play-playlist`\r\n> 3. **回退二**：以上两步都拿不到时，告诉用户\"刚创建的歌单 ID 无法用于播放命令，请在客户端 UI 内打开播放\"（**不要**编造或猜 ID）\r\n> 4. **绝对禁止**：把数字 `songlist_id` 当成 `global_id` 用——类型不匹配，客户端协议层会拒绝\r\n\r\n> **播放路径全部失败的回退**：若用户同意播放，但客户端仍不可用（control play-playlist 因客户端未运行 / ID 拿不到而失败），Agent **不要**循环重试。按 [music.md §7.2 云端歌单的播放](./music.md#72-云端歌单的播放控制浏览器打开-h5-链接) 走\"先探后告知\"的浏览器路径：用浏览器工具打开云端 `song_list_url` 尝试点击播放，工具不可用时明确告知用户手动打开。\r\n\r\n---\r\n\r\n## 11. open — 打开客户端页面\r\n\r\n在酷狗客户端中打开指定页面（非静默，客户端主窗口会切换到对应视图）。`silent` 字段硬编码为 `false`。\r\n\r\n```bash\r\n# 打开主界面\r\nkugou-cli control open --target-type main\r\n\r\n# 打开歌手页\r\nkugou-cli control open --target-type singer --singer-id 12345\r\n\r\n# 打开专辑页（可选 --mixsongid 作为专辑根曲）\r\nkugou-cli control open --target-type album --album-id 67890 --mixsongid 8888\r\n\r\n# 打开歌单页\r\nkugou-cli control open --target-type songlist --global-collection-id \"collection_3_938985631_304_0\"\r\n\r\n# 打开搜索结果页\r\nkugou-cli control open --target-type search --keyword \"周杰伦\"\r\n```\r\n\r\n**target-type 和必填参数**:\r\n\r\n| target-type | 必填参数 | 说明 |\r\n|-------------|----------|------|\r\n| `main` | 无 | 打开主界面 |\r\n| `singer` | `--singer-id` | 歌手页 |\r\n| `album` | `--album-id` | 专辑页 |\r\n| `songlist` | `--global-collection-id` | 歌单页（协议 wire 字段 `list_gid`） |\r\n| `search` | `--keyword` | 搜索结果页 |\r\n\r\n**通用可选参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--mixsongid` | 可选 mixsongid（如 `album` 时作为专辑根曲） |\r\n\r\n---\r\n\r\n## 12. play-playlist — 播放整个歌单\r\n\r\n按歌单的 `global_collection_id`（即协议层的 `list_gid`）让本地酷狗客户端联网拉歌单后播放。本命令只传 `list_gid` 给客户端，**无需 CLI 端联网预翻页**——歌单内容由客户端在收到请求后异步拉取（CLI 不需要外网/代理）。\r\n\r\n**`--global-id` 的合法来源**（按推荐顺序）：\r\n\r\n1. **`music search-playlist` / `recommend-playlist` 响应的 `global_id` 字段**（最稳，跨客户端兼容）\r\n2. **`control playlist create` 响应的 `data.global_collection_id` 字段**（仅当客户端版本返回该字段时可用——见 [§10 输出字段语义](./control.md#10-playlist-create--创建歌单)）\r\n3. `music playlist-songs ` 直接使用你已有的字符串 ID\r\n\r\n**不要**：把 `control playlist create` 响应里的数字 `data.songlist_id` 当成 `global-id` 用（类型不匹配，会被客户端协议层拒绝）。\r\n\r\n```bash\r\n# 默认：清空当前队列，按歌单顺序从头播放\r\nkugou-cli control play-playlist --global-id \"collection_3_938985631_304_0\"\r\n\r\n# 不打断当前播放：歌单追加到队列尾部\r\nkugou-cli control play-playlist --global-id \"...\" --playlist-mode append_queue\r\n\r\n# 把歌单插到当前曲目之后立即播放\r\nkugou-cli control play-playlist --global-id \"...\" --playlist-mode next_play\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--global-id` | 歌单全局 ID（必填），即协议层的 `list_gid`，例如 `collection_3_938985631_304_0`。必须是字符串（不要传数字 `songlist_id`）|\r\n| `--playlist-mode` | 队列策略：`auto`（默认）/ `append_queue` / `next_play` |\r\n\r\n**playlist-mode 详解**:\r\n\r\n| 取值 | wire 上的 `play_mode` | 客户端行为 | 适用场景 |\r\n|------|----------------------|----------|----------|\r\n| `auto`（默认） | **省略** | 客户端默认 = 清空当前队列后按歌单顺序从头播放 | 切到歌单里从头听 |\r\n| `append_queue` | `\"append_queue\"` | 歌单追加到播放队列尾部，不打断当前播放 | 不打断当前歌曲，排队播放 |\r\n| `next_play` | `\"next_play\"` | 歌单插入到当前曲目之后立即播放，后续队列顺延 | 听完这首就想听歌单 |\r\n\r\n> 🎵 **AI 必读**：命令成功后**必须**调 `control current` 拿到当前歌曲名/歌手，告知用户。本命令是异步的——客户端拉歌单歌曲可能要等几秒；如 `control current` 一开始返回 `code: 非 0`，等 1-2 秒再试一次。\r\n\r\n**前置条件**:\r\n\r\n- 已登录：`kugou-cli auth login`\r\n- 酷狗桌面客户端在后台运行，且握手健康：`kugou-cli control start`\r\n\r\n**典型联动**:\r\n\r\n```bash\r\n# 搜歌单 → 取 global_id → 播放\r\nGID=$(kugou-cli music search-playlist \"周杰伦\" | jq -r '.data.list[0].global_id')\r\nkugou-cli control play-playlist --global-id \"$GID\"\r\n\r\n# 立即听下一首（不打断当前曲目）\r\nkugou-cli control play-playlist --global-id \"$GID\" --playlist-mode next_play\r\n```\r\n\r\n---\r\n\r\n## 错误场景\r\n\r\n### 场景 1：CLI 未登录（登录态缺失）\r\n\r\n未登录时，任意 `control` 子命令都会在入口被拦截。\r\n\r\n**触发**:\r\n```bash\r\nkugou-cli control status\r\n```\r\n\r\n**stderr**:\r\n```\r\nkugou-cli control: not logged in, run `kugou-cli auth login` first: auth file not found\r\n```\r\n\r\n**stdout**: 无\r\n\r\n**exit code**: 1\r\n\r\n**修复**: 运行 `kugou-cli auth login` 完成 CLI 扫码登录。\r\n\r\n---\r\n\r\n### 场景 2：客户端未登录（HTTP 409 / code: 4091）\r\n\r\n`favorite song`、`favorite songlist`、`playlist create` 等需要账号的操作，如果客户端本身未登录（cookie/token 过期或从未登录），协议层返回 `code: 4091`。\r\n\r\n**触发**:\r\n```bash\r\nkugou-cli control favorite song --mixsongid 32100650\r\n```\r\n\r\n**stdout**（协议响应原样输出）:\r\n```json\r\n{\"code\":4091,\"msg\":\"login required\"}\r\n```\r\n\r\n**stderr**（CLI 追加的提示）:\r\n```\r\nHTTP 409\r\n请在酷狗客户端内登录后重试\r\n```\r\n\r\n**exit code**: 0（CLI 正常退出，调用方从 stdout 的 `code` 字段自行判断）\r\n\r\n**注意**: CLI 不会 exit 1，也不会提示去运行 `kugou-cli auth login`（那是 CLI 登录，跟客户端登录是两件独立的事）。\r\n\r\n**修复**: 在酷狗客户端 UI 内扫码登录客户端。\r\n\r\n---\r\n\r\n### 场景 3：客户端未安装或未启动（握手超时）\r\n\r\n握手在 6 秒内未完成，说明酷狗客户端未安装、未运行或未响应 URL scheme 唤起。\r\n\r\n**触发**:\r\n```bash\r\nkugou-cli control status\r\n```\r\n\r\n（假设客户端未运行）\r\n\r\n**stderr**:\r\n```\r\nis Kugou client installed?\r\n```\r\n\r\n**stdout**: 无\r\n\r\n**exit code**: 1\r\n\r\n**排查步骤**:\r\n1. 确认酷狗客户端已安装（Windows: `KuGou.exe`，Mac: `/Applications/KuGou.app`）\r\n2. 确认客户端已启动并运行\r\n3. Windows 用户确认 URL scheme `kugou://` 已注册（可在 PowerShell 中试 `start kugou://workbuddy`）\r\n4. Mac 用户在 Safari 地址栏试 `mackugou://workbuddy` 确认 LaunchServices 注册正常\r\n\r\n---\r\n\r\n### 场景 4：Linux 不支持\r\n\r\n在非 Windows / macOS 系统上运行任意 `control` 子命令，会被运行时拦截。\r\n\r\n**触发**（在 Linux 上）:\r\n```bash\r\nkugou-cli control status\r\n```\r\n\r\n**stderr**:\r\n```\r\nkugou-cli control: linux is not supported\r\n```\r\n\r\n**stdout**: 无\r\n\r\n**exit code**: 1\r\n\r\n**说明**: 酷狗客户端仅提供 Windows 和 macOS 版本，因此 control 命令也仅在这两个平台可用。所有非 Windows/macOS 系统都会被拒绝，包括 Linux、FreeBSD、OpenBSD 等。\r\n\r\n---\r\n\r\n## 典型 AI Agent 工作流\r\n\r\n以下为通过 `control` 命令控制本地酷狗客户端的典型流程。\r\n\r\n### 完整示例：搜索并播放歌曲\r\n\r\n```\r\n# 1. 搜索歌曲（music 命令，返回 mix_song_id）\r\n$ kugou-cli music search \"周杰伦 晴天\"\r\n{\r\n \"data\": {\r\n \"list\": [{\r\n \"song_name\": \"晴天\",\r\n \"mix_song_id\": \"32100650\",\r\n \"artist_name\": \"周杰伦\"\r\n }]\r\n }\r\n}\r\n\r\n# 2. 让客户端播放这首歌\r\n$ kugou-cli control play --mixsongid 32100650 --song-name \"晴天\" --singer-name \"周杰伦\"\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n\r\n# 3. 暂停播放\r\n$ kugou-cli control player --action pause\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n\r\n# 4. 查看当前播放状态\r\n$ kugou-cli control current\r\n{\r\n \"code\": 0,\r\n \"data\": {\r\n \"song_name\": \"晴天\",\r\n \"position_ms\": 30000,\r\n \"volume\": 65\r\n }\r\n}\r\n\r\n# 5. 收藏当前歌曲\r\n$ kugou-cli control favorite song --mixsongid 32100650\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n\r\n# 6. 搜索更多歌曲并创建歌单\r\n$ kugou-cli music search \"周杰伦\"\r\n# 假设返回多个结果，mix_song_id 分别为 32100650、32068120、31598745\r\n\r\n$ kugou-cli control playlist create --name \"周杰伦精选\" --mixsongids \"32100650,32068120,31598745\"\r\n{\"code\":0,\"data\":{\"songlist_id\":\"abc123\",\"name\":\"周杰伦精选\",\"count\":3}}\r\n```\r\n\r\n### 与 music 命令的配合\r\n\r\n`music search` 返回的 `mix_song_id`（或 `mix_song_id`）可直接传给 `control play --mixsongid`，无需任何 ID 转换。\r\n\r\n```\r\nmusic search \"歌手\" → 提取 mix_song_id → control play --mixsongid \r\n → control favorite song --mixsongid \r\n → control playlist create --mixsongids ,\r\n```\r\n\r\n---\r\n\r\n## 前置条件总结\r\n\r\n| 条件 | 说明 |\r\n|------|------|\r\n| CLI 已登录 | `kugou-cli auth login`（扫码登录，存储登录态） |\r\n| 酷狗客户端运行中 | 客户端内置 HTTP server 必须启动（`control start` 会自动触发） |\r\n| 客户端已登录 | 在酷狗客户端 UI 内扫码登录（影响 `favorite`/`playlist create` 等操作） |\r\n| Windows / macOS | Linux 不支持（运行时检查） |\r\n\r\n---\r\n\r\n## 13. Client Detection (`control detect`)\r\n\r\n> **零副作用探测**，**不启动客户端、不抢焦点**——和 `control start` 不同，本命令只读 OS 端的\"URL scheme 注册\"等信号。\r\n\r\n### 用法\r\n\r\n```bash\r\nkugou-cli control detect # 默认 JSON 输出\r\nkugou-cli control detect --json=false # 人类可读一行\r\n```\r\n\r\n### 退出码（Agent 编程消费）\r\n\r\n| 退出码 | 含义 |\r\n|---|---|\r\n| `0` | 客户端已安装（`installed: true`） |\r\n| `1` | 探测过程出错（系统权限等） |\r\n| `2` | 客户端没装（`installed: false`） |\r\n\r\n> Linux/BSD 上 `installed: false` 但 `error: \"\"` —— 不支持是正常情况，不是错误。\r\n\r\n### JSON 输出示例（Windows，有客户端）\r\n\r\n```json\r\n{\r\n \"installed\": true,\r\n \"scheme_registered\": true,\r\n \"scheme\": \"kugou\",\r\n \"exe_path\": \"C:\\\\Program Files\\\\KuGou\\\\KGMusic\\\\KuGou.exe\",\r\n \"version\": \"20.1.40.27866\",\r\n \"handshake_exists\": true,\r\n \"handshake_path\": \"C:\\\\Users\\\\alice\\\\.config\\\\kugou-cli\\\\handshake.json\",\r\n \"platform\": \"windows\",\r\n \"checked_at\": \"2026-08-11T15:25:01+08:00\",\r\n \"strategies\": {\r\n \"scheme_registry\": {\"ok\": true, \"evidence\": \"HKCR\\\\kugou\\\\shell\\\\open\\\\command -> ...\"},\r\n \"install_path_scan\": {\"ok\": true, \"evidence\": \"C:\\\\Program Files\\\\KuGou\\\\KGMusic\\\\KuGou.exe exists\"},\r\n \"handshake_file\": {\"ok\": true, \"evidence\": \"...handshake.json present\"}\r\n }\r\n}\r\n```\r\n\r\n### 与 `control start` 的区别\r\n\r\n| 维度 | `control detect` | `control start` |\r\n|---|---|---|\r\n| 副作用 | **零**（只读 OS 信号） | 会启动客户端 + 抢焦点 |\r\n| 触发客户端启动？ | ❌ | ✅（若握手文件不存在） |\r\n\r\n### 在 AI 工作流里的位置\r\n\r\n详见 [SKILL.md §5](../SKILL.md) —— **首次**要向用户展示歌曲列表/歌单列表前探测一次，记下 `client_available`；后续展示复用本次结果。\r\n\r\n`control detect` **不**替代 `control start` —— 后者仍负责建立 handshake + 启动客户端，是 `control play` 等命令的前置。\r\n\r\n---\r\n\r\n## 14. Doctor (`control doctor`)\r\n\r\n> 诊断 `control start` 失败的根因——`detect` 只看\"客户端有没有装\"，`doctor` 看\"为什么拉不起\"。\r\n\r\n`control start` 的\"6 秒握手超时\"对**完全没装客户端**、**Win11 HVCI 不兼容导致客户端启动后立即崩**、**PowerShell 被裁掉**、**$HOME 不可写**这些情况长得一模一样——都是同一个错误。`doctor` 把这些信号分开成结构化字段，AI agent 能直接据此判断该走哪个分支。\r\n\r\n### 用法\r\n\r\n```bash\r\nkugou-cli control doctor # 默认 JSON 输出\r\nkugou-cli control doctor --json=false # 一行人类可读\r\n```\r\n\r\n**副作用极小**：不启动客户端、不抢焦点、不触发 URL scheme。唯一的磁盘动作是 `$HOME` 可写性探测——可能创建 `~/.config/kugou-cli` 目录并写入后立即删除一个临时文件（CLI 握手本来也要用这个目录）。安全在任何时候跑。\r\n\r\n### 退出码\r\n\r\n| 退出码 | 含义 | 何时 |\r\n|---|---|---|\r\n| `0` | OK，无 fatal 无 hint | 环境正常，可直接 `control start` |\r\n| `1` | FATAL，必须修 | `client.installed=false` 或 `home_dir_accessible=false` |\r\n| `2` | 非 fatal，有 hint | `hints` 数组非空——start 仍可能成功，但建议看 hint |\r\n\r\n### JSON 输出字段\r\n\r\n| 字段 | 类型 | 含义 |\r\n|---|---|---|\r\n| `platform` / `goos` | string | `runtime.GOOS`（`windows` / `darwin` / `linux`） |\r\n| `checked_at` | RFC3339 | 检查时间 |\r\n| `client.installed` | bool | `Detect()` 的总判定 |\r\n| `client.exe_path` | string | 客户端可执行文件绝对路径（HKCR scheme handler 或 install 路径扫描） |\r\n| `client.version` | string | HKLM Uninstall `DisplayVersion`（Win）；空表示无法读到 |\r\n| `client.scheme_registered` | bool | `HKCR\\kugou` 注册项 |\r\n| `client.handshake_path` | string | 握手文件期望位置 |\r\n| `client.handshake_exists` | bool | 握手文件是否已存在 |\r\n| `environment.hvci_enabled` | bool \\| null | Win11 Memory Integrity（`HKLM\\...\\HypervisorEnforcedCodeIntegrity\\Enabled`），非 Win 平台为 `null` |\r\n| `environment.vbs_enabled` | bool \\| null | VBS（`HKLM\\...\\DeviceGuard\\EnableVirtualizationBasedSecurity`） |\r\n| `environment.powershell_available` | bool \\| null | `powershell.exe` 是否在 PATH |\r\n| `environment.explorer_available` | bool \\| null | `explorer.exe` 是否在 PATH |\r\n| `environment.in_job_object` | bool \\| null | 当前进程是否在 Job Object 里（Win 才有意义）。`true` 意味着 kugou-cli 派生的进程可能被 sandbox reap |\r\n| `environment.job_breakaway_allowed` | bool \\| null | Job 是否允许 `CREATE_BREAKAWAY_FROM_JOB`（设置 `JOB_OBJECT_LIMIT_BREAKAWAY_OK` / `SILENT_BREAKAWAY_OK`）。`false` = 派生链逃不出 Job，CLI 因此**不再**设置该标志；`null` 字段省略 = 不在 Job 或读不到 Job flag |\r\n| `environment.job_kill_on_close` | bool \\| null | Job 是否设置 `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`。`true` = Job 关闭时其内进程被内核终止——这是\"客户端启动后又消失\"的真正原因；`null` = 不在 Job 或读不到 |\r\n| `environment.process_integrity_level` | string | Token 完整性级别：`Low`（AppContainer / LPAC）/`Medium`（普通）/`High`（elevated）/`System`/`Unknown`。`Low` 意味着 Job breakaway 也救不了 |\r\n| `environment.parent_process` | string | `pid=N path=...` —— 当前进程的父进程，用于识别是否跑在 sandbox runner 下 |\r\n| `environment.grandparent_process` | string | `pid=N path=...` —— 祖父进程，二级排查（\"spawned by shell\" vs \"spawned directly by sandbox\"） |\r\n| `environment.home_dir` | string | 解析后的 `$HOME`/`$USERPROFILE` |\r\n| `environment.home_dir_accessible` | bool | `.config/kugou-cli/` 是否可创建+写 |\r\n| `hints` | string[] | 给用户的修复建议（HVCI 关、$HOME 设置、PowerShell 缺失等） |\r\n| `fatal` | bool | 是否 fatal |\r\n| `fatal_reason` | string | fatal 时的简短原因 |\r\n\r\n**三态指针规则**：`null` = 该平台不探测或探测失败；`true`/`false` = 已探测且确定。\r\n\r\n### JSON 输出示例（Win11 + HVCI 开 + 客户端 v20.1.40）\r\n\r\n```json\r\n{\r\n \"platform\": \"windows\",\r\n \"goos\": \"windows\",\r\n \"checked_at\": \"2026-09-11T16:14:30+08:00\",\r\n \"client\": {\r\n \"installed\": true,\r\n \"exe_path\": \"C:\\\\Program Files\\\\KuGou\\\\KGMusic\\\\KuGou.exe\",\r\n \"version\": \"20.1.40.27854\",\r\n \"scheme_registered\": true,\r\n \"handshake_path\": \"C:\\\\Users\\\\alice\\\\.config\\\\kugou-cli\\\\handshake.json\",\r\n \"handshake_exists\": false\r\n },\r\n \"environment\": {\r\n \"hvci_enabled\": true,\r\n \"vbs_enabled\": true,\r\n \"powershell_available\": true,\r\n \"explorer_available\": true,\r\n \"home_dir\": \"C:\\\\Users\\\\alice\",\r\n \"home_dir_accessible\": true\r\n },\r\n \"hints\": [\r\n \"Win11 Memory Integrity (HVCI) is enabled — Kugou client v20.x is known to crash with NTSTATUS 0xC0000005 under HVCI\",\r\n \"workaround: Settings → Privacy & Security → Windows Security → Device Security → Core Isolation → Memory Integrity → Off, then reboot\",\r\n \"client version 20.1.40.27854 is on the known-HVCI-crash list even with Memory Integrity on; upgrading to v20.2+ is recommended\",\r\n \"no handshake file yet — `control start` will fire the URL scheme; if it times out, the most likely cause is the client crashing on launch (see HVCI hint above)\"\r\n ],\r\n \"fatal\": false\r\n}\r\n```\r\n\r\n### 在 AI 工作流里的位置\r\n\r\n```text\r\nagent wants to call control play\r\n └─ first: run control doctor\r\n ├─ fatal=1 → tell user to install client / fix $HOME, abort\r\n └─ fatal=0 → proceed\r\n ├─ hints contain \"HVCI\" → warn user before start, ask before disabling HVCI\r\n ├─ hints contain \"Job Object\" or \"AppContainer\" → sandbox reap 问题,\r\n │ kugou-cli 改不了,需要 sandbox 平台方配合或绕开 sandbox 启动\r\n └─ no hints → just run control start, then control play\r\n```\r\n\r\n### Sandbox reap 诊断速查\r\n\r\n`control start` 失败的\"6 秒超时\"对多种原因长得一模一样，**`doctor` 的 `environment` 字段把它们分开**：\r\n\r\n| `in_job_object` | `job_breakaway_allowed` | `job_kill_on_close` | `process_integrity_level` | 隔离类型 | 结果 |\r\n|---|---|---|---|---|---|\r\n| `false` | (省略) | (省略) | `Medium` | 无 Job 隔离 | ✅ 客户端正常存活 |\r\n| `true` | `true` | 任意 | 任意 | Job 隔离，允许 breakaway | ✅ CLI 请求脱离 Job，客户端存活 |\r\n| `true` | `false` | `true` | 任意 | Job 隔离，不允许脱离且关闭即终止 | ⚠️ 客户端能启动，但 Job 关闭（宿主结束命令）时被终止 |\r\n| `true` | `false` | `false` | 任意 | Job 隔离，不允许脱离但不强杀 | ⚠️ 客户端可能存活，但不保证 |\r\n| `true` | (省略) | (省略) | 任意 | Job 隔离，读不到 flag | ⚠️ 未知，按最坏情况处理 |\r\n| (省略) | (省略) | (省略) | `Low` | **AppContainer / LPAC**（不走 Job） | ❌ Job breakaway 救不了 |\r\n| (省略) | (省略) | (省略) | (省略) | 非 Windows 平台 | N/A |\r\n\r\n> **重要（2026-09-11 修正）**：当 `job_breakaway_allowed=false` 时，CLI **不会**再设置 `CREATE_BREAKAWAY_FROM_JOB`——因为在禁止脱离的 Job 里请求脱离会让 `CreateProcess` 直接返回 `ERROR_ACCESS_DENIED`，客户端根本起不来。旧版无条件设置该标志，反而在最需要它的 Job 隔离环境里把启动搞挂了。现在客户端会正常启动并在**当前命令**存续期间存活；能否跨命令存活由宿主的 Job 生命周期决定（`job_kill_on_close`）。\r\n>\r\n> **实用结论**：在 `breakaway=false` 的宿主里，把 `control start` 和真正的控制命令**串在同一条命令里执行**（例如 `control start && control play ...`）即可播放——它们共享同一个 Job，客户端在这条命令期间一直活着。分成两条独立命令时，前一条启动的客户端在后一条里可能已被回收。\r\n\r\n> 字段省略 (`omitempty`) = 该平台不探测，或探测失败导致值是 nil。要区分这两种情况，看 `platform` 字段：非 Windows 上所有 Win-only 字段都省略。\r\n\r\n父进程链 (`parent_process` / `grandparent_process`) 用于识别\"我是被什么 spawn 出来的\"，对识别具体 sandbox runner（workbuddy / opencode / cloud-agent 等）有用，但 doctor 不内置 sandbox 名到 hint 的映射——这部分逻辑放在调用方，doctor 只负责给出**真实数据**。\r\n\r\n### 与 `control detect` 的区别\r\n\r\n| 维度 | `control detect` | `control doctor` |\r\n|---|---|---|\r\n| 副作用 | 零（只读 OS 信号） | 极小（读 HVCI/VBS/launcher/Job，外加一次 `~/.config/kugou-cli` 可写性探测：建目录+写删临时文件） |\r\n| 输出焦点 | \"客户端有没有装？\" | \"为什么 `control start` 会失败？\" |\r\n| 退出码 | 0/1/2（installed 维度） | 0/1/2（fatal+hint 维度） |\r\n| 应在何时跑 | AI agent 每次冷启动前 | `control start` 失败后 |\r\n\r\n---\r\n\r\n## 相关文档\r\n\r\n- [references/output-format.md](./output-format.md) — 输出格式与展示规范\r\n- [references/music.md](./music.md) — music 命令使用指南\r\n- [references/auth.md](./auth.md) — auth 命令使用指南\r\n\r\n> 客户端协议规范由酷狗客户端内部定义，不在用户可访问的文档范围内。本文档只描述 CLI 端可观察的行为。\n\nFile v0.1.20:references/error-handling.md\n\n# 错误处理\r\n\r\n> **判定优先级**：退出码（非 0 = 失败）→ stdout body 的 `errcode` 字段 → stderr 文案。\r\n> Agent **不应依赖 stderr 文案字面量**判断错误类型——文案可能随版本变化；以退出码和下表为准。\r\n\r\n---\r\n\r\n## 常见错误及处理\r\n\r\n| 错误信息 | 原因 | 处理方式 |\r\n|---------|------|---------|\r\n| `账号登录过期，请重新登录` | 登录态已过期（errcode 语义由上游约定）。CLI 已**自动**清理本地登录态 | 引导用户重新登录：`kugou-cli auth login`（扫码）或 `kugou-cli auth set-secret \"<新 secret>\"` |\r\n| `not logged in` / `auth file not found` | 未登录 | 引导用户执行 `kugou-cli auth login` |\r\n| `HTTP error: 400` | 请求参数有误 | 检查命令参数是否正确 |\r\n| `HTTP error: 500` | 服务端错误 | 稍后重试，或告知用户 |\r\n| `API error: (code=)` | 业务错误（上游 errcode ≠ 0） | 根据 errmsg 提示用户 |\r\n| `network error: ...` | 网络连接问题 | 检查网络，可尝试 `--proxy` |\r\n| `failed to get device info` | 设备信息获取失败（仅 control） | 运行时环境异常，检查权限 |\n\nFile v0.1.20:references/install.md\n\n# 安装命令 (install)\r\n\r\n> 安装 SKILL.md 到各平台 skills 目录\r\n\r\n## 命令列表\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli install` | 显示平台选择提示 |\r\n| `kugou-cli install --all` | 安装 SKILL.md 到所有平台 |\r\n| `kugou-cli install --claude` | 安装到 Claude skills 目录 |\r\n| `kugou-cli install --mavis` | 安装到 Mavis skills 目录 |\r\n| `kugou-cli install --hermes` | 安装到 Hermes skills 目录 |\r\n| `kugou-cli install --openclaw` | 安装到 Openclaw skills 目录 |\r\n| `kugou-cli install --codex` | 安装到 Codex skills 目录 |\r\n| `kugou-cli install --workbuddy` | 安装到 Workbuddy skills 目录 |\r\n\r\n---\r\n\r\n## 详细用法\r\n\r\n```bash\r\nkugou-cli install # 显示平台选择提示\r\nkugou-cli install --all # 安装到所有平台\r\nkugou-cli install --claude # 仅安装到 Claude\r\nkugou-cli install --hermes --claude # 安装到 Hermes 和 Claude\r\n```\r\n\r\n**参数**:\r\n- `--claude`: 安装到 `~/.claude/skills/kugou-skill/`\r\n- `--mavis`: 安装到 `~/.mavis/skills/kugou-skill/`\r\n- `--hermes`: 安装到 `~/.hermes/skills/kugou-skill/`\r\n- `--openclaw`: 安装到 `~/.openclaw/skills/kugou-skill/`\r\n- `--codex`: 安装到 `~/.codex/skills/kugou-skill/`\r\n- `--workbuddy`: 安装到 `~/.workbuddy/skills/kugou-skill/`\r\n- `--all`: 安装到以上所有平台\r\n\r\n---\r\n\r\n## 行为说明\r\n\r\n- 无参数时输出\"平台选择提示\"，列出可用平台选项，不会进行任何安装操作\r\n- 只会在目标平台的 skills 父目录存在时才安装（不自动创建父目录）\r\n- npm 安装时会自动安装 SKILL.md\r\n- `kugou-cli install` 命令用于手动重新安装或更新 SKILL.md\r\n\r\n---\r\n\r\n## 通用命令\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli --version` / `kugou-cli version` | 输出版本号（`--version` 是 root flag，`version` 是子命令，两者输出相同） |\r\n| `kugou-cli --help` | 显示帮助信息 |\r\n| `kugou-cli <子命令> --help` | 显示子命令帮助（如 `kugou-cli music search --help`）|\n\nFile v0.1.20:references/music.md\n\n# 音乐命令 (music)\r\n\r\n> 🔐 = 所有 music 命令都需要先登录\r\n\r\n## 命令列表\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli music search ` | 搜索歌曲 |\r\n| `kugou-cli music recommend guess` | 猜你喜欢（个性化推荐） |\r\n| `kugou-cli music recommend similar -s ` | 相似歌曲推荐 |\r\n| `kugou-cli music favorites` | 我的收藏 |\r\n| `kugou-cli music recent` | 最近播放 |\r\n| `kugou-cli music stats` | 听歌统计 |\r\n| `kugou-cli music charts ` | 榜单 |\r\n| `kugou-cli music create-playlist ` | 创建歌单（可附加歌曲） |\r\n| `kugou-cli music search-playlist ` | 搜索歌单 |\r\n| `kugou-cli music recommend-playlist` | 歌单推荐 |\r\n| `kugou-cli music playlist-songs ` | 歌单内歌曲列表 |\r\n| `kugou-cli music submit-preference` | 提交偏好（减少/屏蔽/增加） |\r\n\r\n---\r\n\r\n## 1. 搜索歌曲\r\n\r\n```bash\r\nkugou-cli music search \"周杰伦\"\r\nkugou-cli music search \"周杰伦\" --page 1 --size 20\r\n```\r\n\r\n**参数**:\r\n- ``: 搜索关键词（必填）\r\n- `--page`: 页码，默认 1\r\n- `--size`: 每页数量，默认 20\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"song_name\": \"晴天\",\r\n \"mix_song_id\": \"32100650\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html\"\r\n }\r\n ],\r\n \"total\": 480,\r\n \"page\": 1,\r\n \"size\": 20\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n---\r\n\r\n## 2. 歌曲推荐\r\n\r\n支持三种推荐模式：\r\n\r\n| 类型 | 说明 | 必填参数 |\r\n|------|------|---------|\r\n| `guess` | 猜你喜欢，基于用户喜好推荐 | 无 |\r\n| `similar` | 相似推荐，根据指定歌曲推荐相似歌曲 | `--song` |\r\n| `text` | 文本推歌，根据文本描述推荐歌曲 | `--text` |\r\n\r\n### 2.1 猜你喜欢\r\n\r\n```bash\r\nkugou-cli music recommend guess\r\nkugou-cli music recommend guess --num 10\r\n```\r\n\r\n**参数**:\r\n- `--num`: 推荐数量，默认 10\r\n\r\n### 2.2 相似推荐\r\n\r\n```bash\r\nkugou-cli music recommend similar -s \"晴天\"\r\nkugou-cli music recommend similar --song \"晴天\" -n 5\r\nkugou-cli music recommend similar --song \"晴天\" --text \"风格相似的\" -n 5\r\n```\r\n\r\n**参数**:\r\n- `-s, --song`: 歌曲名称（必填）\r\n- `-n, --num`: 推荐数量，默认 10\r\n- `-t, --text`: 描述文本（可选），用于进一步细化相似方向\r\n\r\n### 2.3 文本推歌\r\n\r\n```bash\r\nkugou-cli music recommend text --text \"适合跑步时听的快节奏歌曲\"\r\nkugou-cli music recommend text --text \"安静的钢琴曲\" --num 5\r\n```\r\n\r\n**参数**:\r\n- `-t, --text`: 文本描述（必填）\r\n- `-n, --num`: 推荐数量，默认 10\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"song_name\": \"稻香\",\r\n \"mix_song_id\": \"8889\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/xxx.html\"\r\n }\r\n ]\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n---\r\n\r\n## 3. 我的收藏\r\n\r\n```bash\r\nkugou-cli music favorites\r\n```\r\n\r\n**参数**: 无（上游接口固定返回最近 10 首收藏，不支持分页）\r\n\r\n> 注意：固定返回最近 10 首收藏，查看更多请前往酷狗App\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"song_name\": \"晴天\",\r\n \"mix_song_id\": \"32100650\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html\"\r\n }\r\n ],\r\n \"total\": 50,\r\n \"msg\": \"当前仅显示最近的10首收藏，查看更多内容，请前往酷狗App\"\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n---\r\n\r\n## 4. 最近播放\r\n\r\n```bash\r\nkugou-cli music recent\r\n```\r\n\r\n**参数**: 无（上游接口固定返回最近 10 条播放记录，不支持分页）\r\n\r\n> 注意：固定返回最近 10 首播放记录，查看更多请前往酷狗App\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"song_name\": \"七里香\",\r\n \"mix_song_id\": \"32100651\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html\"\r\n }\r\n ],\r\n \"total\": 100,\r\n \"msg\": \"当前仅显示最近的10首最近播放，查看更多内容，请前往酷狗App\"\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n---\r\n\r\n## 5. 听歌统计\r\n\r\n```bash\r\nkugou-cli music stats # 默认查当月\r\nkugou-cli music stats --date-type 1 --date 20260501 # 指定周查询\r\n```\r\n\r\n**参数**:\r\n- `--date-type`: 日期类型，0=日、1=周、2=月（默认查当月）\r\n- `--date`: 查询日期，YYYYMMDD 格式，如 \"20260501\"。不传则查当月\r\n - 日类型：每天日期，如 \"20260501\"\r\n - 周类型：必须是周一日期，如 \"20260505\"（周一）\r\n - 月类型：必须是月份第一天，如 \"20260501\"（5月1日）\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"server_time\": 1779977674,\r\n \"listen_duration\": 80776,\r\n \"accumulate_listen_days\": 30,\r\n \"continue_listen_days\": 7,\r\n \"listen_total\": 342,\r\n \"last_listen_total\": 387,\r\n \"top_clocks\": [\r\n \"今日08:00-10:00听歌30分钟\",\r\n \"今日14:00-16:00听歌25分钟\",\r\n \"今日20:00-22:00听歌20分钟\"\r\n ],\r\n \"rank_song\": [\r\n {\r\n \"song_info\": {\"song_name\": \"晴天\", \"mix_song_id\": \"8888\", \"artist_name\": \"周杰伦\", \"play_link\": \"https://www.kugou.com/...\"},\r\n \"count\": 50\r\n }\r\n ],\r\n \"rank_singer\": [\r\n {\"singer_id\": 123, \"name\": \"周杰伦\", \"avatar\": \"https://xxx.jpg\", \"total\": 120}\r\n ],\r\n \"rank_style\": [\r\n {\"style\": \"流行\", \"total\": 200, \"count\": 80}\r\n ],\r\n \"rank_language\": [\r\n {\"language\": \"华语\", \"total\": 400, \"count\": 150}\r\n ]\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段**:\r\n- `listen_duration`: 今日/周/月听歌时长（秒）\r\n- `top_clocks`: 听歌时长最长的 Top3 时段描述（日类型格式如\"今日08:00-10:00听歌30分钟\"，周/月类型格式如\"2026-02月听歌38213分钟\"）\r\n- `accumulate_listen_days`: 累计听歌天数\r\n- `continue_listen_days`: 连续听歌天数\r\n- `listen_total`: 累计听歌次数\r\n- `last_listen_total`: 昨日/上周/上月听歌次数\r\n- `rank_song`: 播放最多的歌曲排行（`count` 为播放次数）\r\n- `rank_singer`: 播放最多的歌手排行\r\n- `rank_style`: 曲风分布统计\r\n- `rank_language`: 语言分布统计\r\n\r\n---\r\n\r\n## 6. 榜单\r\n\r\n```bash\r\nkugou-cli music charts 6666\r\nkugou-cli music charts 52144 --page 1 --size 20\r\n```\r\n\r\n**可用榜单 ID**:\r\n\r\n| rank_id | 榜单名称 |\r\n|---------|----------|\r\n| 8888 | TOP500榜 |\r\n| 90379 | 星耀星光榜 |\r\n| 6666 | 飙升榜 |\r\n| 85432 | 百万收藏榜 |\r\n| 74534 | 新歌榜 |\r\n| 52144 | 抖音热歌酷狗榜 |\r\n\r\n**参数**:\r\n- ``: 搜索关键词（必填）\r\n- `--page`: 页码，默认 1（**无简写**）\r\n- `--size`: 每页数量，默认 20（**无简写**）\r\n\r\n---\r\n\r\n## 7. 创建歌单\r\n\r\n> 🔐 = 需要先登录（CLI 登录 `auth login` / `auth set-secret`）\r\n\r\n### 7.0 调用原则（AI 必读）\r\n\r\n1. **被动调用**：必须用户**明确**要求创建歌单时才调用，禁止在用户仅说\"推荐/搜歌/听歌\"时主动创建\r\n2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户\"是否需要将当前这批歌曲创建为歌单\"，等用户确认后再调用\r\n3. **示例化推荐**：询问时建议给出歌单名建议（如\"跑步歌单\"、\"周杰伦精选\"），让用户更容易确认\r\n4. **硬性默认：优先客户端创建**：用户一旦同意创建歌单，**必须先尝试** [`control playlist create`](./control.md#10-playlist-create--创建歌单)（在本地酷狗客户端内创建）。当以下**任一**条件成立时，回退到本节的 `music create-playlist`（云端创建）：\r\n - **(a)** 当前系统不是 Windows / macOS（control 不支持 Linux）\r\n - **(b)** 本地酷狗客户端未运行，或未通过 `kugou-cli control start` 完成握手（前置条件详见 [control.md §10](./control.md#10-playlist-create--创建歌单)）\r\n - **(c)** `control playlist create` 调用失败（如 409/4091\"login required\"、网络错误等）—— 此时把 stderr 原样回给用户，并询问是否改走云端\r\n\r\n 简单说：**默认 `control`；客户端不可用或失败时，才退到 `music`**。不要在用户没问的情况下主动解释为什么走云端，先尝试 client 路径即可。\r\n\r\n5. **创建成功后主动询问是否播放**：无论走 `control playlist create` 还是 `music create-playlist`，**只要创建成功（返回 0/成功状态）就必须主动询问用户\"是否要播放这个歌单\"**，等用户明确回复后再决定走哪条播放命令：\r\n - 用户同意 → 按场景选播放路径：\r\n - **客户端路径优先**：`kugou-cli control play-playlist --global-id \"\"`（详见 [control.md §12](./control.md#12-play-playlist--播放整个歌单)），可叠加 `--playlist-mode` 控制是否打断当前播放\r\n - **云端歌单（`music create-playlist` 创建的）**：走浏览器 H5 路径（详见下方 7.2）——**不要**再用 `control play-playlist`，因为本地客户端没有这首歌单\r\n - 用户拒绝 / 不回复 → 不做任何动作，不要替用户决定\r\n - 仅在\"创建歌单成功\"时才询问；建失败时不询问（直接展示错误，等用户决定下一步）\r\n\r\n### 7.1 接口说明（云端备选，仅在 7.0 第 4 条任一条件成立时使用）\r\n\r\n> ⚠️ 本节是**云端备选路径**。优先走 [`control playlist create`](./control.md#10-playlist-create--创建歌单)（详见 [7.0 第 4 条](#70-调用原则ai-必读)）。仅当客户端不可用时使用本节。\r\n\r\n创建一个新的自创建歌单，并可选择在创建后往歌单里添加歌曲。\r\n\r\n```bash\r\n# 创建空歌单\r\nkugou-cli music create-playlist \"我的空歌单\"\r\n\r\n# 创建歌单并添加歌曲\r\nkugou-cli music create-playlist \"我的批量歌单\" --songs \"123,456,789\"\r\n```\r\n\r\n**参数**:\r\n- ``: 歌单名称（必填）\r\n- `--songs`: 待添加的歌曲 mix_song_id 列表，逗号分隔（可选）。不传则只创建空歌单\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"errmsg\": \"\",\r\n \"data\": {\r\n \"name\": \"我的批量歌单\",\r\n \"song_list_url\": \"https://m.kugou.com/songlist/gcid_abc123def45\"\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段**:\r\n- `name`: 歌单名称\r\n- `song_list_url`: 歌单播放地址（H5 链接），可分享给用户打开\r\n\r\n**异常说明**:\r\n- 歌单创建成功但添加歌曲失败：返回 200 状态 + 错误信息，body 仍包含已创建歌单的 `name` 与 `song_list_url`\r\n- 歌单创建失败：返回对应错误码（参数错误 20010 / 网络错误 90000 等）\r\n\r\n### 7.2 云端歌单的播放：控制浏览器打开 H5 链接\r\n\r\n> 适用场景：用户同意播放的歌单是 `music create-playlist` 创建的（响应里有 `song_list_url`），且本地没有可用的酷狗客户端（7.0 第 4 条 (a)(b)(c) 任一成立）。\r\n\r\n**Agent 必须遵循\"先探后告知\"原则**：\r\n\r\n1. **先探测浏览器控制能力**：当前 Agent 工具栈是否能控制本地浏览器（playwright / dev-browser / chrome-devtools MCP 等任一可用）。可用 = 可用；都不可用 = 当前环境不支持浏览器控制\r\n2. **可用时**：\r\n - 用浏览器工具打开响应里的 `song_list_url`（H5 链接，格式如 `https://m.kugou.com/songlist/gcid_...`）\r\n - 等待 H5 页面加载完成（`networkidle` / 出现\"播放全部\"按钮）\r\n - **轻量职责**：点击页面上的\"播放\" / \"播放全部\"按钮（若有），控制到\"页面已渲染出播放控制\"为止\r\n - 页面登录、付费、版权屏蔽等后续问题**不归 Agent 管**，告诉用户\"已打开 H5 歌单并尝试点击播放，如未自动播放请手动点一下\"\r\n3. **不可用时**（无浏览器控制工具 / 浏览器控制调用失败）：\r\n - 明确告知用户：\"当前环境无法控制浏览器，请手动复制链接在浏览器打开：[song_list_url]\"\r\n - **不要**伪装已经打开或点击了播放\r\n\r\n> **为什么不写死\"先 playwright 再 chrome-devtools\"？** 不同 Agent 工具栈内置的浏览器工具名不同，文档只规定行为契约（\"打开 + 点击播放\"），具体工具由 Agent 现场选择。\r\n\r\n---\r\n\r\n## 8. 搜索歌单\r\n\r\n根据关键词搜索歌单。\r\n\r\n```bash\r\nkugou-cli music search-playlist \"周杰伦\"\r\nkugou-cli music search-playlist \"周杰伦\" --page 1 --size 20\r\nkugou-cli music search-playlist \"跑步\" --filter 1 # 只搜 UGC\r\nkugou-cli music search-playlist \"钢琴\" --filter 2 # 只搜非 UGC\r\n```\r\n\r\n**参数**:\r\n- ``: 搜索关键词（必填）\r\n- `--page`: 页码，默认 1\r\n- `--size`: 每页数量，默认 20\r\n- `--filter`: 过滤方式，`0=全部（默认） / 1=只搜 UGC / 2=只搜非 UGC`\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"list_id\": 2651286,\r\n \"global_id\": \"collection_3_938985631_304_0\",\r\n \"name\": \"周杰伦：无与伦比，为杰沉沦。\",\r\n \"creator_id\": \"938985631\",\r\n \"creator_name\": \"慕情超爱撒花\",\r\n \"intro\": \"\",\r\n \"song_list_url\": \"https://m.kugou.com/songlist/gcid_3z938985631z304z2\"\r\n }\r\n ],\r\n \"total\": 1000,\r\n \"page\": 1,\r\n \"size\": 20\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段**:\r\n- `list_id`: 歌单 ID（数字 string）\r\n- `global_id`: 全局歌单 ID（字符串，跨客户端兼容的稳定标识）\r\n- `name`: 歌单名\r\n- `creator_id`: 创建人用户 ID（字符串）\r\n- `creator_name`: 创建人昵称\r\n- `intro`: 歌单简介\r\n- `song_list_url`: 歌单链接（H5），格式 `https://m.kugou.com/songlist/gcid_{encoded(global_id)}`；`global_id` 为空时返回空字符串\r\n\r\n> **提示**: 歌单搜索/推荐只返回基础信息用于卡片展示。需要歌曲数、播放量、收藏数、封面图、歌单内歌曲等详细信息时，调用方拿到 `global_id` 后调用 [第 10 章](#10-歌单内歌曲列表) 或直接打开 `song_list_url`。\r\n\r\n**特殊说明**:\r\n- 上游高亮：服务端固定传 `tag=em`，返回的 `name` 字段带 `...` 高亮标签，前端可直接渲染\r\n- 上游错误码：146/147=被屏蔽地区，148=非法关键字，149=页码超出范围。出现时返回 90000 网络错误，建议引导用户重试或更换关键词\r\n\r\n---\r\n\r\n## 9. 歌单推荐\r\n\r\n根据用户喜好个性化推荐歌单。\r\n\r\n```bash\r\nkugou-cli music recommend-playlist\r\nkugou-cli music recommend-playlist --page 1 --size 20\r\nkugou-cli music recommend-playlist --module-id 6 # 我-最近播放-歌单下方\r\n```\r\n\r\n**参数**:\r\n- `--page`: 页码，默认 1\r\n- `--size`: 每页数量，默认 20\r\n- `--module-id`: 上游模块 ID，由客户端透传。常见值：\r\n - `1` = 歌单广场（默认）\r\n - `5` = 酷狗 X 首页为你推荐\r\n - `6` = 我 - 最近播放 - 歌单下方\r\n - `15` = 酷狗 12 听首页为你推荐\r\n\r\n 不传时服务端默认填 `1`。\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"list_id\": 2651286,\r\n \"global_id\": \"collection_3_938985631_304_0\",\r\n \"name\": \"周杰伦：无与伦比，为杰沉沦。\",\r\n \"creator_id\": \"938985631\",\r\n \"creator_name\": \"慕情超爱撒花\",\r\n \"intro\": \"\",\r\n \"song_list_url\": \"https://m.kugou.com/songlist/gcid_3z938985631z304z2\"\r\n }\r\n ],\r\n \"total\": 100,\r\n \"has_next\": 1,\r\n \"session\": \"1706428800\",\r\n \"refresh_time\": 0,\r\n \"page\": 1,\r\n \"size\": 20\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段（顶层）**:\r\n- `total`: 总数；`has_next`: 是否有下一页（1=是 / 0=否）\r\n- `session`: 会话标识（暂时返回时间戳）\r\n- `refresh_time`: 客户端刷新时间（秒），`0` 或缺失表示不刷新\r\n\r\n**关键字段（list[]）**:\r\n- 与歌单搜索（[第 8 章](#8-搜索歌单)）共用同一套 `PlaylistInfo` 基础字段（`list_id` / `global_id` / `name` / `creator_id` / `creator_name` / `intro` / `song_list_url`），调用方可使用同一套反序列化逻辑\r\n- 已登录时上游根据 userid 做个性化推荐；未登录时可能返回空数据或通用推荐\r\n- 上游可能附带 `cache` 等额外字段，**未在 `PlaylistInfo` 中列出的字段请勿依赖**\r\n\r\n---\r\n\r\n## 10. 歌单内歌曲列表\r\n\r\n通过歌单全局 ID（`global_collection_id`）获取歌单内歌曲列表。一般先调用 [第 8 章](#8-搜索歌单) 或 [第 9 章](#9-歌单推荐) 拿到 `global_id`，再透传给本接口。\r\n\r\n```bash\r\nkugou-cli music playlist-songs \"collection_3_938985631_304_0\"\r\nkugou-cli music playlist-songs \"collection_3_938985631_304_0\" --page 1 --size 100\r\n```\r\n\r\n**参数**:\r\n- ``: 歌单全局 ID（必填，从 `search-playlist` / `recommend-playlist` 响应的 `global_id` 字段透传）\r\n- `--page`: 页码，从 1 开始，默认 1\r\n- `--size`: 每页数量，默认 100（上游建议值）\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"song_name\": \"晴天\",\r\n \"mix_song_id\": \"8888\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html\"\r\n },\r\n {\r\n \"song_name\": \"七里香\",\r\n \"mix_song_id\": \"8890\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html\"\r\n }\r\n ],\r\n \"total\": 164,\r\n \"page\": 1,\r\n \"size\": 100\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段**:\r\n- `list[]`: 通用 `SongInfo` 结构（`song_name` / `mix_song_id` / `artist_name` / `play_link`）\r\n- `total`: 上游返回的歌曲总数（不含被过滤的屏蔽歌曲）\r\n\r\n> **关于上游附带字段**：CLI 透传上游原始 JSON 字符串，响应里**可能**含其他字段（如 `hash`、`singer_id` 等），但 CLI 不解析、不保证存在。Agent 不要依赖未在 `SongInfo` 中列出的字段。\r\n\r\n**特殊说明**:\r\n- **屏蔽歌曲过滤**: 上游可能跳过被屏蔽的歌曲（不返回），`total` 不含被过滤项，`list` 长度可能小于 `size`\r\n- **artist_name 拼接**: 多歌手时上游用 `/` 拼接（例如 `周杰伦/方文山`）\r\n- **分页去重**: 上游按服务端数组下标分页，但歌曲可能在分页期间被增删，调用方需自行按 `mix_song_id` 去重\r\n- **播放链接**: `play_link` 由服务端拿到 `mix_song_id` 后批量生成，单条失败不影响其他歌曲\r\n\r\n---\r\n\r\n## 11. 提交偏好\r\n\r\n> 🔐 = 需要先登录\r\n\r\n把用户对音乐偏好的调整（减少 / 屏蔽 / 增加 某位歌手、语种、曲风等）提交到上游推荐引擎，**服务端**先把 `name` 解析为上游 id（例如 singer → 歌手搜索取第 0 个结果的 `author_id`）再透传，上游处理后**返回一条确认话术 + 重新推荐的歌曲列表**。\r\n\r\n适用于用户表达\"最近想多听 XX 语种 / 不想再听 XX 歌手的 / 多推点 XX 曲风\"等诉求的场景。\r\n\r\n```bash\r\n# 减少推荐某位歌手（weight 越小减得越多）\r\nkugou-cli music submit-preference \\\r\n --dimension singer --degree reduce \\\r\n --name \"周杰伦\" --weight-ratio 0.5\r\n\r\n# 屏蔽某类曲风\r\nkugou-cli music submit-preference \\\r\n --dimension genre --degree forbid \\\r\n --weight-ratio 1.5\r\n\r\n# 增加某语种\r\nkugou-cli music submit-preference \\\r\n --dimension language --degree add \\\r\n --name \"粤语\" --weight-ratio 1.8\r\n```\r\n\r\n**参数**（全部为 flag，无位置参数）:\r\n\r\n| 参数 | 必填 | 取值 | 说明 |\r\n|------|------|------|------|\r\n| `--dimension` | 是 | `singer` / `language` / `genre` / `ai` / `dj` / `fc` / `abs` / `old` | 偏好维度（强枚举） |\r\n| `--degree` | 是 | `reduce`（减少）/ `forbid`（屏蔽）/ `add`（增加） | 操作类型（强枚举） |\r\n| `--name` | 条件必填 | string | `singer` 传歌手名 / `language` 传语种名；其余维度**必须为空** |\r\n| `--weight-ratio` | 是 | float64，范围 `(0, 2)` | 权重系数。`reduce` 配 `(0,1)` / `forbid` & `add` 配 `(1,2)` |\r\n| `--area-code` | 否 | int | 地区码；不传时不出现在 body 中 |\r\n\r\n**`name` 必填/必空规则**:\r\n\r\n| `--dimension` | 是否需要 `--name` | 说明 |\r\n|--------------|------------------|------|\r\n| `singer` | **必填**（歌手名） | 服务端查歌手搜索取第 0 个结果 `author_id` |\r\n| `language` | **必填**（语种名） | 服务端查下方「语种映射表」取 id |\r\n| `genre` / `ai` / `dj` / `fc` / `abs` / `old` | **必须为空** | 服务端不取 name，传了会被 CLI 拦截 |\r\n\r\n**`weight-ratio` 与 `--degree` 的配对**:\r\n\r\n| `--degree` | 配对范围 | 不匹配时的处理 |\r\n|-----------|---------|---------------|\r\n| `reduce` | `(0, 1)` | CLI 给 warning（不阻断），最终可能服务端拒 |\r\n| `forbid` | `(1, 2)` | CLI 给 warning（不阻断），最终可能服务端拒 |\r\n| `add` | `(1, 2)` | CLI 给 warning（不阻断），最终可能服务端拒 |\r\n\r\n> CLI 只做基础的 `(0, 2)` 范围校验 + 不匹配时的 warning；**业务侧具体配对由服务端校验**，避免本地硬规则与服务端不一致时把\"reduce 0.99\"这种边界值也堵掉。\r\n\r\n**语种映射表**（`--dimension=language` 时 `--name` 取值）:\r\n\r\n`国语` / `英语` / `粤语` / `纯音乐` / `韩语` / `日语` / `其他语种` / `小语种` / `方言` / `闽南语` / `俄语` / `伴奏` / `西班牙语` / `藏语` / `越南语` / `葡萄牙语` / `德语` / `泰语` / `意大利语` / `蒙古语`\r\n\r\n**输出示例**:\r\n\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"errmsg\": \"\",\r\n \"data\": {\r\n \"status\": 801,\r\n \"msg\": \"收到！将减少推荐歌手「周杰伦」的歌曲，猜你喜欢以下歌曲~\",\r\n \"list\": [\r\n {\r\n \"song_name\": \"稻香\",\r\n \"mix_song_id\": \"595244683\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/xxx.html\"\r\n }\r\n ]\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段**:\r\n- `data.status`: 上游 `msgtype`，取第一条确认话术对应的消息类型（如 `801`）\r\n- `data.msg`: 上游确认话术（如「收到！将减少推荐歌手「周杰伦」的歌曲，猜你喜欢以下歌曲~」），**直接展示给用户**\r\n- `data.list`: 重新推荐的歌曲列表，结构同通用 `SongInfo`（`song_name` / `mix_song_id` / `artist_name` / `play_link`）\r\n\r\n**调用流程**（agent 必读）:\r\n\r\n```\r\n1. 解析用户意图：识别\"减少 / 屏蔽 / 增加\" + \"对象（歌手 / 语种 / 曲风等）\"\r\n2. 按下表确定 dimension / degree / name：\r\n ┌────────────────────────────────────────┬──────────┬────────────┬────────────────┐\r\n │ 用户原话（例） │ dimension│ degree │ name │\r\n ├────────────────────────────────────────┼──────────┼────────────┼────────────────┤\r\n │ \"少推点周杰伦的歌\" │ singer │ reduce │ 周杰伦 │\r\n │ \"别再给我推民谣了\" │ genre │ forbid │ （空） │\r\n │ \"多来点粤语歌\" │ language │ add │ 粤语 │\r\n │ \"屏蔽一下英文歌\" │ language │ forbid │ 英语 │\r\n └────────────────────────────────────────┴──────────┴────────────┴────────────────┘\r\n3. 选 weight_ratio：\r\n - reduce → 0 < x < 1（值越小减得越多；常用 0.5）\r\n - forbid / add → 1 < x < 2（值越大越强；常用 1.5）\r\n4. 调 submit-preference\r\n5. 拿到响应后，**优先用 data.msg 展示确认话术**给用户；\r\n data.list 是重新推荐的歌曲列表，按 [§0.1 / §0.2 / §1](#1-搜索歌曲) 的展示规范呈现\r\n```\r\n\r\n**特殊说明**:\r\n- **上游返回 SSE 流式**：响应体上游为多行 `data:` 流。服务端取**第一条**确认话术（`msgtype=801`）作为对外 `status`/`msg`，避免被后续推荐话术覆盖\r\n- **歌曲组装**：`list` 中的 `mixsongid` 与「歌曲推荐」接口共用同一套组装逻辑（kmr 拉歌名/歌手/hash + `GenerateBatch` 生成播放链接）；未命中歌曲详情（audioMap miss）的条目会被跳过，因此最终 `list` 条数可能小于上游返回数量\r\n- **name 解析**：`singer` / `language` 维度的 `name` 会在 logic 层被解析为上游 id 后透传，客户端只传 `name` 即可，不需要先去查歌手 id\r\n- **name 输入规范**：用户口语里说\"少推点老周\"时，agent 应**询问清楚**再调用——上游 name 必须是服务端能识别的标准名（如\"周杰伦\"），不是昵称/简称\r\n- **不是「保存为规则」**：本接口是**实时反馈**给推荐引擎，不会持久化为用户画像规则；同一歌手多次提交会**叠加效果**\r\n- **不要主动调用**：必须用户**明确**表达偏好调整意愿时才调用（\"少推点 XX\" / \"别再推 XX\" / \"多推点 XX\"），禁止在用户仅说\"推荐/搜歌/听歌\"时主动改写用户偏好\r\n- **改完偏好 → 主动问是否要听**：提交成功（`errcode: 0`）后，服务端已返回重新推荐的 `data.list`；agent 应**主动询问**用户\"要按这个新偏好播放一些吗？\"，等用户确认后**复用 `list[]` 里的 mix_song_id** 直接走 [`control play`](./control.md#1-play--播放指定歌曲) 等命令，不要再调一次 `recommend`\n\nFile v0.1.20:references/output-format.md\n\n# 输出格式与展示规范\r\n\r\n## 通用响应结构\r\n\r\n`music` / `auth` / `install` 等\"上游 API 类\"命令输出标准 JSON 结构：\r\n\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"errmsg\": \"\",\r\n \"data\": { ... },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**响应状态判定**:\r\n- **成功判定只看 `errcode == 0`**——这是 Agent 唯一可信的成功依据\r\n- `data` 包含实际业务数据\r\n- `status: 1` 是上游接口调用状态提示，**仅作辅助参考**（部分上游错误响应里 `status` 可能不是 1，但仍由 `errcode` 决定 CLI 成功与否）\r\n- **`control` 命令不走这个结构**——它透传酷狗客户端本地 HTTP 协议的原始 JSON，成功字段通常是 `code` 而不是 `errcode`。见 [references/control.md](./control.md)\r\n\r\n---\r\n\r\n## 展示规范\r\n\r\n向用户展示结果时，**必须遵循以下规范**：\r\n\r\n### 1. 歌曲/歌单列表展示（批量优先用表格）\r\n\r\n> **强制规则**：结果 ≥ 2 条 → 表格；结果 = 1 条 → 单行链接（按客户端可用性决定是否加链接）。\r\n\r\n#### 1.1 客户端可用性探测（前置条件）\r\n\r\n**首次**要向用户展示歌曲列表、歌单列表或歌单内歌曲列表之前，**必须**先探测本机是否有可用的酷狗客户端（详见 [SKILL.md#5-首次要展示歌曲歌单前探测本机客户端可用性](../SKILL.md)）：\r\n\r\n```bash\r\nkugou-cli control detect\r\n```\r\n\r\n根据退出码记下 `client_available`：\r\n\r\n| 退出码 | 含义 | `client_available` |\r\n|---|---|---|\r\n| `0` | 已安装 | `true` |\r\n| `1` | 探测出错（注册表权限等） | `false`（按没客户端处理） |\r\n| `2` | 没装客户端 | `false` |\r\n\r\n**会话内只探测一次**，后续展示复用本次结果。`control detect` 是零副作用探测，不会启动客户端、不会抢焦点。\r\n\r\n#### 1.2 规则总览\r\n\r\n| 结果条数 | 展示形式 | 客户端可用？ | 歌曲名/歌单名是否加链接 |\r\n|---|---|---|---|\r\n| **≥ 2** | Markdown 表格（**必须**） | 无关 | **一律不加**（保持列宽整洁） |\r\n| **= 1** | 单行 Markdown 链接 | 是 | **不加**（可直接走 `control play`） |\r\n| **= 1** | 单行 Markdown 链接 | 否 | **必须加**（用户手动打开） |\r\n| **= 0** | 自然语言提示 | 无关 | 不适用 |\r\n\r\n#### 1.3 表格格式（结果 ≥ 2 条）\r\n\r\n**歌曲列表**（来自 `search` / `recommend guess|similar|text` / `charts` / `favorites` / `recent` / `playlist-songs`）：\r\n\r\n```markdown\r\n| 序号 | 歌曲名 | 歌手 |\r\n|------|--------|------|\r\n| 1 | 晴天 | 周杰伦 |\r\n| 2 | 七里香 | 周杰伦 |\r\n| 3 | 稻香 | 周杰伦 |\r\n```\r\n\r\n**歌单列表**（来自 `search-playlist` / `recommend-playlist`）：\r\n\r\n```markdown\r\n| 序号 | 歌单名 | 创建人昵称 |\r\n|------|--------|------------|\r\n| 1 | 周杰伦经典30首 | 酷狗小编 |\r\n| 2 | 慢摇车载DJ | DJ阿圣 |\r\n```\r\n\r\n**硬性规则**：\r\n\r\n- 表格单元格里的歌曲名/歌单名**不加** Markdown 链接——加了会让列宽自适应 URL，可读性反而变差\r\n- 表格里也不列 `play_link` / `song_list_url` / `mix_song_id` / `global_id`——这些字段是给后续 `control *` 命令用的，由 agent 内部持有，**不展示给用户**\r\n- 序号从 1 开始连续递增\r\n- 如果返回总条数 > 表格展示条数（例如 `search` 默认 20 条），**只展示实际返回的那部分**，不要截断也不要用省略号\r\n\r\n#### 1.4 单条结果格式（结果 = 1 条）\r\n\r\n**有客户端时**（`client_available = true`）—— 歌曲名/歌单名**不加链接**：\r\n\r\n```markdown\r\n晴天 - 周杰伦\r\n```\r\n\r\n```markdown\r\n周杰伦经典30首 —— 酷狗小编\r\n```\r\n\r\n**无客户端时**（`client_available = false`）—— 歌曲名/歌单名**必须加链接**：\r\n\r\n```markdown\r\n[晴天 - 周杰伦](https://www.kugou.com/mixsong/xxxx.html)\r\n```\r\n\r\n```markdown\r\n[周杰伦经典30首](https://www.kugou.com/songlist/xxxx.html)\r\n```\r\n\r\n#### 1.5 为什么表格不加链接？\r\n\r\n- 表格的目标是**浏览/筛选**，不是立即跳转；用户在表格里通常要做的是\"挑一首播放\"或\"挑一个歌单打开\"，而非\"挨个点开\"\r\n- 加链接会让列宽按 URL 自适应，中文长字符串场景下整张表可读性急剧下降\r\n- ID（`mix_song_id` / `global_id`）由 agent 内部持有，等用户明确说\"播放第 3 首\" / \"打开第 2 个歌单\"时再走 `control play` / `control play-playlist` 或浏览器跳转\r\n\r\n#### 1.6 反例（禁止）\r\n\r\n| 禁止 | 错误原因 |\r\n|---|---|\r\n| 表格里写 `[晴天](https://...)` 形式的可点击单元格 | 列宽爆炸、可读性差 |\r\n| 表格里把 `play_link` / `global_id` 也单列出来 | ID 是 agent 内部数据，不该展示给用户 |\r\n| 结果 ≥ 2 条却用列表式 `[歌名 - 歌手](link)` 堆叠 | 表格才是 ≥ 2 条的标准形式 |\r\n| 单条结果（= 1）时仍用表格 | 杀鸡用牛刀，单行更直接 |\r\n| 单条无客户端时不加链接 | 用户没有客户端可控制，必须给链接让用户手动打开 |\r\n| 单条有客户端时仍加链接 | 既然有客户端可以直接 `control play`，加链接反而多余 |\r\n| 不探测就硬性决定加不加链接 | 必须先 `control detect`，不能凭猜测 |\r\n\r\n#### 1.7 control 操作响应不受本节约束\r\n\r\n`control play` / `control favorite song` 等**操作响应**不包含 `play_link`，按 control 协议原始 JSON 字段原样展示即可（见 [references/control.md](./control.md)）。本节规范只适用于 `music *` 命令返回的列表类结果。\r\n\r\n### 2. 统计数据\r\n\r\n提取关键字段并以结构化方式呈现（如\"累计听歌 342 首，时长 22.4 小时\"）\r\n\r\n### 3. 二维码\r\n\r\n使用 `qrcode_img_url` 渲染给用户：Markdown `![酷狗登录二维码]()`，让客户端拉取并渲染\r\n\r\n### 4. 错误展示\r\n\r\n- CLI 错误输出到 **stderr**，stdout 只放原始 JSON（或原始 body）\r\n- Agent 解析失败时同时检查：退出码（0 = 成功，非 0 = 失败）、stdout body 的 `errcode` 字段、stderr 输出\r\n- 不要把 stderr 输出原样展示给用户；转化为自然语言说明（如\"账号登录过期，请重新登录\"）\r\n\r\n---\r\n\r\n### 5. 推荐理由（主动推荐场景必写）\r\n\r\n**触发条件**：仅当 agent **主动**给用户推荐歌曲时才写推荐理由，包括以下命令的返回结果：\r\n\r\n- `kugou-cli music recommend guess`（猜你喜欢）\r\n- `kugou-cli music recommend similar -s `（相似推荐）\r\n- `kugou-cli music recommend text --text <描述>`（文本推歌）\r\n- `kugou-cli music charts `（榜单，详见 [music.md#7](music.md#7)）\r\n- `kugou-cli music recommend-playlist`（歌单推荐）—— 歌单本身就是主动推荐行为\r\n\r\n**不触发**：用户**主动搜索**（`search` / `search-playlist`）、查自己数据（`favorites` / `recent` / `stats`）、查指定歌单内容（`playlist-songs`）的结果**不写**推荐理由——用户来找东西，不需要再被解释一遍。\r\n\r\n#### 写法要求\r\n\r\n在歌曲列表**之后**追加一段 Markdown 引用块（`>`）作为推荐理由，必须包含以下三层信息：\r\n\r\n1. **整体歌曲风格**：用一句话概括本批推荐的整体风格/情绪基调（例如「以华语流行慢歌为主，情绪偏舒缓治愈」）。\r\n2. **匹配逻辑**：依据当前推荐场景说明匹配来源——\r\n - 猜你喜欢 / 歌单推荐 → 「基于你的听歌偏好/历史播放」\r\n - 相似推荐 → 「延续《XXX》的 XXX 风格/主题」\r\n - 文本推歌 → 「贴合你描述的『XXX』场景」\r\n - 榜单 → 「来自 XXX 榜第 N 名，XXX 类热度风向」\r\n3. **挑 2-3 首解读**：从本批返回中挑选 2-3 首，**结合行业认知**（歌手常见风格、歌曲广为人知的标签、所属专辑/年代等）做一句解读，帮助用户判断是否合口味。\r\n\r\n> ⚠️ 解读内容**仅基于歌名 + 歌手名调用 agent 自身行业认知**，不要捏造歌词、不要引用未经验证的曲风标签。如对歌曲不熟悉，宁可写得笼统一些也不要硬编细节。\r\n\r\n#### 字数硬约束\r\n\r\n**总字数控制在 220-260 字（含标点）**。超出或不足都需要重写到区间内。撰写时不必分段，整体作为一段引用块即可。\r\n\r\n#### 输出示例\r\n\r\n```markdown\r\n> 为你挑选了 5 首华语流行慢歌，整体偏舒缓、情绪内敛，节奏不快不躁，编曲以钢琴和原声吉他为主，更适合午后或深夜一个人安静循环。匹配逻辑来自你最近的播放记录和猜你喜欢数据，我们从中挑出与历史偏好契合度最高的几首组成了这张清单。其中《晴天》是周杰伦 2003 年的代表作，校园民谣的底色配钢琴铺陈，几乎成了一代人的青春共同记忆；《七里香》延续了同期的中国风与诗意意象，副歌弦乐层层推进，听感最为饱满宏大；《稻香》则把视角拉回乡村童年，节奏轻快但内核温暖，是整张清单里最治愈的一首作品。\r\n```\r\n\r\n---\n\nFile v0.1.20:references/update.md\n\n# 更新命令 (update)\r\n\r\n> 自动检查并更新 kugou-cli\r\n\r\n## 命令\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli update --check` | 仅检查更新，不执行 |\r\n| `kugou-cli update` | 检查并提示（不自动执行） |\r\n| `kugou-cli update --force` | 直接执行更新（仅 npm 安装） |\r\n\r\n---\r\n\r\n## 启动时自动检查\r\n\r\n### 1. 检查行为\r\n\r\n每次执行任意 `kugou-cli` 命令时，**后台异步**检查 npm registry 上的最新版本。\r\n\r\n- **不阻塞** 主命令\r\n- 有更新时输出到 **stderr**（避免污染 stdout JSON 输出）\r\n- 提示格式：\r\n ```\r\n [kugou-cli] update available: 0.0.22 → 0.0.23 (run `kugou-cli update` to upgrade)\r\n ```\r\n\r\n### 2. 检查频率限制\r\n\r\n- 缓存有效期：**24 小时**\r\n- 24 小时内不会重复访问 npm registry\r\n\r\n### 3. 跳过检查\r\n\r\n在以下情况跳过启动检查：\r\n- `CI=true` 环境变量\r\n- `KUGOU_CLI_NO_UPDATE_CHECK=1` 环境变量\r\n- 命令行指定 `--no-update-check` flag\r\n\r\n---\r\n\r\n## 显式检查更新\r\n\r\n```bash\r\nkugou-cli update --check\r\n```\r\n\r\n> **绕过 24h 缓存**：显式调用 `kugou-cli update [--check]` **总是**绕过本地 24h 缓存，强制访问 npm registry。这与\"启动时被动检查\"的语义不同——启动检查走缓存（24h 内不重复访问 npm），显式 `update` 命令不走缓存。\r\n\r\n**输出示例**：\r\n\r\n有更新时：\r\n```json\r\n{\r\n \"current_version\": \"0.0.22\",\r\n \"latest_version\": \"0.0.23\",\r\n \"update_available\": true,\r\n \"install_method\": \"npm\",\r\n \"update_command\": \"npm install -g @kg-ai/kugou-skill@latest\"\r\n}\r\n```\r\n\r\n无更新时：\r\n```json\r\n{\r\n \"current_version\": \"0.0.22\",\r\n \"latest_version\": \"0.0.22\",\r\n \"update_available\": false,\r\n \"install_method\": \"npm\"\r\n}\r\n```\r\n\r\n---\r\n\r\n## 执行更新\r\n\r\n### 方式 1：Agent / 脚本（推荐）\r\n\r\n```bash\r\n# 步骤 1: 检查\r\ninfo=$(kugou-cli update --check)\r\nupdate_available=$(echo \"$info\" | jq -r '.update_available')\r\n\r\n# 步骤 2: 如果有更新，提示用户确认后执行\r\nif [ \"$update_available\" = \"true\" ]; then\r\n echo \"有可用更新，正在升级...\"\r\n kugou-cli update --force\r\nfi\r\n```\r\n\r\n### 方式 2：手动\r\n\r\n```bash\r\n# 提示但不执行\r\nkugou-cli update\r\n# 显示: About to run: npm install -g @kg-ai/kugou-skill@latest\r\n\r\n# 强制执行\r\nkugou-cli update --force\r\n```\r\n\r\n### 方式 3：标准 npm 命令\r\n\r\n无需 `update` 子命令，直接：\r\n```bash\r\nnpm install -g @kg-ai/kugou-skill@latest\r\n```\r\n\r\n---\r\n\r\n## 安装方式检测\r\n\r\nCLI 自动检测安装方式：\r\n\r\n| 安装方式 | 检测方法 | 是否支持自动更新 |\r\n|---------|---------|------------------|\r\n| **npm** | 二进制路径包含 `node_modules/@kg-ai/kugou-skill` | ✅ 支持 |\r\n| **其他**（源码编译 / 手动下载） | 其他路径 | ❌ 仅提示 |\r\n\r\n非 npm 安装时，CLI 只会提示，不会自动更新。请使用对应方式更新。\r\n\r\n---\r\n\r\n## 注意事项\r\n\r\n1. **网络要求**：检查更新需要访问 `https://registry.npmjs.org`，在受限网络下可能失败\r\n2. **离线友好**：网络失败时静默忽略，不影响主命令\r\n3. **CI 友好**：CI 环境默认跳过检查，避免污染日志\r\n4. **不强制**：默认仅提示，更新需用户/Agent 显式确认\n\nFile v0.1.20:skill-card.md\n\n## Description:\n\n酷狗 helps agents use the Kugou CLI to search music, get recommendations, view charts and listening history, manage favorites and playlists, adjust recommendation preferences, and control the local Kugou desktop client.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[shamo88](https://clawhub.ai/user/shamo88)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and agents use this skill to interact with Kugou Music through a global CLI for music discovery, account music data retrieval, playlist management, recommendation preference updates, and local desktop client playback control.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill relies on a globally installed npm CLI that can check for and apply updates.\n\nMitigation: Install only from a trusted npm publisher, review updates before applying them, and use the documented controls to disable update checks in restricted environments.\n\nRisk: The skill can solicit and persist Kugou account login state, including base64 secrets.\n\nMitigation: Prefer QR login when possible, avoid pasting secrets into chat or shell history, and rotate or re-login if a secret may have been exposed.\n\nRisk: The skill can read or change personal music account data and control the local Kugou client.\n\nMitigation: Confirm user intent before playlist, favorite, preference, or playback changes, and review command output before taking follow-up actions.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/shamo88/skills/kugou-skill)\n- [Authentication commands](artifact/references/auth.md)\n- [Music commands](artifact/references/music.md)\n- [Local client control commands](artifact/references/control.md)\n- [Output format and display rules](artifact/references/output-format.md)\n- [Error handling](artifact/references/error-handling.md)\n- [Install commands](artifact/references/install.md)\n- [Update commands](artifact/references/update.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and parsed JSON result summaries]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [The skill expects raw JSON from kugou-cli commands and converts results into concise user-facing music tables, links, status messages, and follow-up prompts.]\n\n## Skill Version(s):\n\n0.1.20 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.1.13: 10 files, 38535 bytes\n\nFiles: references/auth.md (13903b), references/control.md (25457b), references/error-handling.md (1183b), references/install.md (2049b), references/music.md (18669b), references/output-format.md (9038b), references/update.md (3235b), skill-card.md (2895b), SKILL.md (19677b), _meta.json (131b)\n\nFile v0.1.13:SKILL.md\n\n---\r\nname: kugou-skill\r\ndescription: |\r\n 酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手\r\n 提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单等功能。\r\n\r\n **触发场景**（满足任一即使用本技能）：\r\n - 用户要求推荐歌曲、听歌建议\r\n - 用户要求搜索歌曲、查找歌手作品\r\n - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）\r\n - 用户要求查看收藏、最近播放、听歌统计\r\n - 用户要求创建歌单、自建歌单\r\n - 用户提供 base64 secret 字符串要求登录或导入身份\r\n - Agent 在尝试扫码登录时遇到环境限制（无法发图片）→ 主动询问用户是否可提供 secret\r\n - 用户提到\"酷狗\"、\"kugou\"、\"猜你喜欢\"、\"相似歌曲\"\r\n - 用户要求让 PC/Mac 客户端播放歌曲、暂停、切歌、收藏、创建歌单\r\n - 用户提到酷狗 URL scheme（\"kugou://\" 或 \"mackugou://\"）\r\n - 用户提到\"本机控制\"、\"控制酷狗客户端\"\r\n\r\n **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。\r\n\r\n 安装方式：npm install -g @kg-ai/kugou-skill\r\n---\r\n\r\n# kugou-skill\r\n\r\n## AI 使用工作流（优先阅读）\r\n\r\n使用本工具时的标准流程：\r\n\r\n```\r\n1. 检查安装 → npm install -g @kg-ai/kugou-skill\r\n2. 检查登录态 → kugou-cli auth status\r\n3. 登录决策（按以下优先级严格判断，不要跳步）：\r\n ├─ 状态 a：已登录（logged_in: true）→ 跳到第 6 步\r\n ├─ 状态 b：未登录 + 用户**明确**说\"我有 secret\" → 调 `kugou-cli auth set-secret \"\"` 一次完成 → 跳到第 6 步\r\n ├─ 状态 c：未登录 + 当前环境**无法**渲染远程 URL 图片 **且** 无法读取本地二维码文件 → **强制**走 set-secret（同上）\r\n └─ 状态 d：未登录 + 其他所有情况 → 走扫码流程（第 4 步）\r\n\r\n 注意：状态 b/c/d 互斥；不要在用户未明确给 secret 时擅自走 set-secret。\r\n4. 引导登录——扫码（详见 references/auth.md）：\r\n - 执行 `auth login`，从输出读 `qrcode_img_url` 和 `qrcode_img_path`，按当前客户端能力选一种方式把二维码**直接展示给用户**\r\n - **阶段 A（主动轮询）**：图片刚展示，**主动**重试几次 `auth status`（每次隔几秒），覆盖用户秒扫场景\r\n - 任意一次返回 `logged_in: true` → 跳到第 6 步\r\n - 见到 `status: failed` → **不要换新图**，隔 1-2 秒用同一个本地 qrcode 再调一次（计入阶段 A 的 5 次预算）\r\n - 见到 `status: expired` → 告诉用户二维码已失效，调 `auth login` 拿新图，从阶段 A 重新开始\r\n - 几次都返回 `waiting` / `failed` 且未出现 `scanned` / `logged_in` / `expired` → 进入阶段 B\r\n - **阶段 B（等用户回复）**：停下，告诉用户\"请用酷狗 APP 扫码登录，扫完后告诉我已扫码\"，**不再调 status**，等用户**主动回复\"已扫码\"**\r\n - **阶段 C（验证一次）**：用户回复\"已扫码\"后，**调一次** `auth status`：\r\n - `logged_in: true` → 完成，跳到第 6 步\r\n - `scanned`（已扫但未确认）→ 等几秒再调一次，最多**额外**调几次，仍是 scanned 就告诉用户\"手机端是否已点确认？\"\r\n - `failed` → **不要换新图**，隔 1-2 秒用同一个本地 qrcode 再调一次，最多重试 2-3 次；仍 failed 则告诉用户稍后重试\r\n - `expired` / `{\"logged_in\": false}`（无 status 字段，说明本地 qrcode 已被上游清掉）→ 重新 `auth login` 拿新图（覆盖本地），从阶段 A 重新开始\n5. **首次要展示歌曲/歌单前探测本机客户端可用性**（详见 [references/control.md §13](references/control.md#13-client-detection-control-detect)）：\r\n - **触发时机**：本会话中第一次要向用户展示歌曲列表、歌单列表或歌单内歌曲列表之前。后续展示**复用本次探测结果**（会话内探测一次即可，不要每条命令前都跑）\r\n - **命令**：`kugou-cli control detect`（零副作用，不启动客户端、不抢焦点）\r\n - **判定**：\r\n - 退出码 `0` → 本机有客户端，标记 `client_available = true`\r\n - 退出码 `2` → 本机没装客户端，标记 `client_available = false`\r\n - 退出码 `1` → 探测过程出错（注册表权限等），按 `false` 处理并继续\r\n - **不影响 control 命令本身**：当用户主动要求 `control play` 等命令时，仍按原本的 `control` 错误处理（找不到客户端会由 `control start` 报\"handshake file not found\"，不要用探测结果跳过 `control` 调用）\r\n - **何时不探测**：用户请求只查询统计数据、查收藏/最近播放、看错误页等**不展示歌曲列表**的纯查询场景；登录流程本身；debug / 排错场景\r\n\r\n6. 按请求类型分流：\r\n - **请求类型 A：控制已有歌 / 歌单 / 收藏**（用户已有 mixsongid 或 global_id）→ 直接执行 `control` 命令（详见 [references/control.md](references/control.md)），不需要先调 `music` 拿 ID\r\n - 例：`control play`、`control player --action pause`、`control favorite song --mixsongid `、`control play-playlist --global-id `\r\n - **请求类型 B：搜索后做某件事**（搜索歌曲/推荐/榜单 → 拿到 ID 后再做后续动作，如播放、收藏、建歌单）→ 先执行 `music` 命令拿数据，再按需转 `control`，详见 [references/music.md](references/music.md)\r\n - 例：先 `music search` 拿 mixsongid，再 `control play` 播放\r\n - 例：先 `music search-playlist` 拿 global_id，再 `control play-playlist` 播放\r\n - 例：先 `music search` 拿 mixsongids，再 `control playlist create --mixsongids` 创建客户端歌单\r\n - **请求类型 C：纯查询 / 统计 / 榜单**（不涉及本地客户端）→ 只走 `music` 命令\r\n7. 解析 JSON 输出，按展示规范展示给用户（详见 [references/output-format.md](references/output-format.md)）\r\n```\r\n\r\n> **关键提醒**：**不要**在没有 mixsongid / global_id 的情况下盲目调用 `control` 命令（如 `control play --mixsongid \"\"`）—— `control` 命令在 ID 缺失时会报错。先用 `music` 命令把 ID 查出来，再传给 `control`。\r\n\r\n---\r\n\r\n## 关键注意事项\r\n\r\n### 登录流程\r\n\r\n`auth login` 命令输出三个字段供 Agent 选择二维码展示方式（详见 [references/auth.md](references/auth.md)）：\r\n\r\n| 字段 | 用途 |\r\n|------|------|\r\n| `qrcode_img_path` | 本地二维码 PNG 文件路径 |\r\n| `qrcode_img_url` | 远程二维码图片 URL |\r\n| `qrcode` | 字符串标识，**Agent 不要使用**（仅供 CLI 内部） |\r\n\r\n**根据当前客户端能力选择一种方式，把二维码图片直接展示在聊天窗口中**：\r\n\r\n- 客户端支持读取或附加本地图片（如 Codex）→ 使用 `qrcode_img_path`，通过客户端的本地图片读取/附件能力展示\r\n- 客户端支持 Markdown 外链图片（如 WorkBuddy）→ 在消息正文中输出 `![酷狗登录二维码]()`\r\n- Agent 可以自行选择最适合当前环境的方式，不要同时展示两张二维码\r\n- **不要**只把 URL 或本地路径作为普通文本发给用户，用户应直接看到二维码图片\r\n- 首选方式展示失败时，立即切换到另一种方式：远程图片加载失败则尝试读取本地图片，本地图片无法读取则尝试远程 Markdown 图片\r\n- 若两种方式都不可用 → 告诉用户\"当前环境无法显示二维码，请提供 base64 secret 字符串\"，改走 `auth set-secret`\r\n\r\n**`auth status` 的调用约束**：\r\n\r\n- 每次调用只查一次扫码状态，**不会内部自动轮询**。Agent 需要在外层按\"阶段 A → 阶段 B → 阶段 C\"循环调用（详见上方工作流第 4 步）\r\n- 阶段 B 之后**不要**自己继续调用 status，等用户回复\r\n\r\n### 直接导入 secret 登录\r\n\r\n当用户**已经持有**一个有效的 base64 secret 字符串（从别处获取的），直接调用 `kugou-cli auth set-secret \"\"` 即可完成登录，**跳过扫码流程**——效果与扫码登录完全一致。secret 字符串含 `+` `/` `=` 是正常的，shell 里务必用引号包起来。\r\n\r\n**何时考虑用 set-secret**：\r\n\r\n- 用户明确说\"我有 secret\"\r\n- 当前环境既无法展示远程图片也无法读取本地图片\r\n- 用户之前已经登录过想换设备\r\n\r\n### 登出\r\n\r\n`auth logout` 命令：先与服务端同步登出，**确认成功后才**清理登录状态。失败时登录状态保留、可重试；未登录时幂等直接返回成功。\r\n\r\n### 登录态自动失效\r\n\r\n当任意 `music` 命令遇到登录态过期时，CLI 会自动取消登录（退出码非 0 + stderr 提示登录已过期）。Agent 收到该错误后：\r\n\r\n1. **不要**自己再调一次 `music` 命令（会再次失败）\r\n2. **直接**引导用户重新登录：先问\"你手上是否已有新 secret？\"，有则 `auth set-secret`，没有则 `auth login` 走扫码\r\n3. 重新登录后，**先调 `auth status` 确认** `logged_in: true`，再重试之前失败的 `music` 命令\r\n\r\n> 错误判定以退出码 + references/error-handling.md 中的错误码说明为准，**不要**依赖 stderr 文案字面量匹配。\r\n\r\n### 音乐命令依赖登录\r\n\r\n除了 `auth`、`install`、`version`、`--help` 以外，所有 `music` 子命令都需要先登录。如果 CLI 返回\"未登录\"错误，引导用户执行登录流程。\r\n\r\n### 输出格式与成功判定\r\n\r\n所有命令输出原始 JSON 到 stdout，错误输出到 stderr。**成功判定以退出码和 JSON 内的成功状态字段为准**（详见 [references/output-format.md](references/output-format.md)）。\r\n\r\n### 歌曲/歌单展示规范\r\n\r\n向用户展示音乐命令返回的歌曲列表或歌单列表时，按以下规则（详见 [references/output-format.md §1](references/output-format.md)）：\r\n\r\n- **结果 ≥ 2 条** → 用 Markdown 表格展示\r\n - 歌曲表格列：`| 序号 | 歌曲名 | 歌手 |`\r\n - 歌单表格列：`| 序号 | 歌单名 | 创建人昵称 |`\r\n - **表格内的歌曲名 / 歌单名一律不加链接**（避免列宽过长、可读性差；详见下方解释）\r\n- **结果 = 1 条** → 用单行 Markdown 链接展示\r\n - 有客户端（探测结果 `client_available = true`）→ 歌曲名/歌单名**不加链接**（可直接调 `control play` 等本地命令）\r\n - 无客户端（探测结果 `client_available = false`）→ 歌曲名/歌单名**必须加链接**，方便用户手动打开\r\n - 歌曲正确格式：`[歌曲名 - 歌手名](https://www.kugou.com/...)`\r\n - 歌单正确格式：`[歌单名]()`\r\n- **结果 = 0 条** → 告诉用户\"未找到结果\"，不需要展示表格或链接\r\n\r\n#### 为什么表格不加链接？\r\n\r\n- 表格单元格加 Markdown 链接会让列宽自适应 URL，中文长字符串下表的可读性变差\r\n- 表格场景下用户通常是要**浏览/筛选**，ID 由 agent 内部持有，等用户明确说\"播放这首\" / \"打开这个歌单\"再走对应命令\r\n\r\n#### 客户端可用性探测怎么用？\r\n\r\n- **首次**要展示歌曲/歌单列表前，按工作流第 5 步跑 `kugou-cli control detect`，记下 `client_available`\r\n- 单条结果（= 1）时根据 `client_available` 决定加不加链接\r\n- 表格结果（≥ 2）时**无视** `client_available`，表格单元格不加链接\r\n- 探测结果**不**影响用户主动调用 `control *` 命令的逻辑——那是另一条独立路径（由 `control start` 自己报错）\r\n\r\n### 播放 / 切歌后必须告知当前曲目\r\n\r\n**触发条件**：以下命令**成功后**必须告知用户当前正在播放的歌曲：\r\n\r\n- `control play`（播放单首）\r\n- `control play-playlist`（播放整个歌单）\r\n- `control continue-play`（续播另一设备列表）\r\n- `control player --action next/prev`（切歌）\r\n\r\n**操作**：调用 `kugou-cli control current` 拿到 `song_name` / `singer_name`，向用户输出：\r\n\r\n> � 正在播放：<歌曲名> - <歌手>\r\n\r\n**注意**：\r\n- **必须**用 `control current` 重新拿当前曲目，**不要**用 `control play` 命令里 `--song-name` / `--singer-name` 字段直接展示——后者只是客户端展示用的标签，**不保证与实际播放一致**（特别是播放歌单 / 续播 / 切歌之后）\r\n- 若 `control current` 返回非 `code: 0`（如客户端断开 / 命令未支持），告知用户\"已开始播放（无法读取当前曲目详情）\"，不要假装知道\r\n\r\n详见 [references/control.md §3 current](./references/control.md#3-current--获取当前播放)。\r\n\r\n### 推荐理由规范\r\n\r\n仅在 agent **主动推荐**场景下，歌曲列表之后**必须**追加一段 220-260 字的推荐理由（详见 [references/output-format.md#5-推荐理由主动推荐场景必写](references/output-format.md#5-推荐理由主动推荐场景必写)）：\r\n\r\n- **触发**：`recommend guess / similar / text`、`charts`、`recommend-playlist`\r\n- **不触发**：`search` / `search-playlist` / `favorites` / `recent` / `stats` / `playlist-songs`——用户主动查询不写\r\n- **三层内容**：整体歌曲风格 + 匹配逻辑 + 挑 2-3 首基于行业认知的解读\r\n- **字数硬约束**：220-260（含标点），超出或不足需重写\r\n\r\n### 创建歌单的调用原则\r\n\r\n详见 [references/music.md#7-创建歌单](references/music.md#7-创建歌单)：\r\n\r\n1. **被动调用**：必须用户**明确**要求创建歌单时才调用，禁止在用户仅说\"推荐/搜歌\"时主动创建\r\n2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户是否需要将当前这批歌曲创建为歌单，等用户确认后再调用\r\n3. **硬性默认：优先客户端创建**：用户同意后**必须先尝试** `kugou-cli control playlist create`（在本地酷狗客户端内创建，详见 [references/control.md#10-playlist-create--创建歌单](references/control.md#10-playlist-create--创建歌单)），仅当客户端不可用（不支持的操作系统 / 未运行 / 无响应 / 调用失败）时才回退到云端 `music create-playlist`\r\n4. **创建成功后主动询问是否播放**：无论走 `control playlist create` 还是 `music create-playlist`，**创建成功（返回成功状态）后必须主动询问用户\"是否要播放这个歌单\"**，等用户明确回复后再决定走哪条播放命令；用户拒绝则不做任何动作。播放路径选择：\r\n - 客户端可用：优先 `kugou-cli control play-playlist --global-id \"\"`（详见 [references/control.md#12-play-playlist--播放整个歌单](references/control.md#12-play-playlist--播放整个歌单)）\r\n - 客户端不可用 / `play-playlist` 拿不到可用 ID：按 [references/music.md#72-云端歌单的播放控制浏览器打开-h5-链接](references/music.md#72-云端歌单的播放控制浏览器打开-h5-链接) 走\"先探后告知\"——用浏览器工具打开 H5 `song_list_url` 尝试点击播放；工具不可用时明确告知用户手动复制链接打开\r\n\r\n### 能力边界提示\r\n\r\n当用户提出的需求在 `kugou-cli` **整体能力边界之外**时，Agent 必须**明确告知用户\"暂不支持该能力\"**，不得擅自用其他命令拼凑代替，也不得假装能完成。\r\n\r\n**典型场景**：\r\n\r\n- `kugou-cli` 没有对应子命令（用户要的功能不在 `auth` / `music` / `control` / `install` 任何子命令中）\r\n- `control` 子命令在当前操作系统不支持（如 `control` 系列仅支持 Windows / macOS，Linux 不支持）\r\n- 命令存在但参数 / 取值已下线（如 `control open --target-type url` 已被移除）\r\n- CLI 整体没有相关云端 API（如批量下载、歌词编辑、播客等）\r\n\r\n**正确回应**：\r\n\r\n> 这个能力 kugou-cli 暂不支持。如果你需要该功能，可以去酷狗客户端里手动操作。\r\n\r\n**反例（不要这样做）**：\r\n\r\n- 不要用「推荐相似歌曲」伪装成「按场景生成歌单」之类的能力替代\r\n- 不要反复尝试不同参数 / 多次重试来\"碰运气\"绕过不支持\r\n- 不要把 CLI 报错（\"unknown flag\" / \"unsupported\"）原样翻译后甩给用户——先判断这是\"能力不存在\"还是\"用法不对\"再回应\r\n\r\n**与「客户端不可用」的区别**：本节是「命令/能力本身不存在」；「客户端不可用」是「命令存在但本机客户端未运行 / 未登录」，后者有 fallback 路径（详见上方「创建歌单的调用原则」第 3 条 + [references/control.md](references/control.md)）。两者不要混用。\r\n\r\n---\r\n\r\n## 基础信息\r\n\r\n- **npm 包**: @kg-ai/kugou-skill\r\n- **二进制命令**: kugou-cli\r\n- **安装方式**: `npm install -g @kg-ai/kugou-skill`\r\n\r\n> 关于更新：CLI 安装后会自动保持最新。具体行为与关闭开关见 [references/update.md](references/update.md)。如有版本相关问题，向该文档查证。\r\n\r\n---\r\n\r\n## 详细文档索引\r\n\r\n| 文档 | 说明 |\r\n|------|------|\r\n| [references/auth.md](references/auth.md) | 认证命令：扫码登录、直接设置 secret、查看状态、登出 |\r\n| [references/music.md](references/music.md) | 音乐命令：搜索、推荐、收藏、统计、榜单、创建歌单 |\r\n| [references/control.md](references/control.md) | 控制命令：控制 PC/Mac 客户端播放、暂停、切歌、收藏、创建歌单等 |\r\n| [references/install.md](references/install.md) | 安装命令：SKILL.md 安装到各平台 |\r\n| [references/update.md](references/update.md) | 更新行为、版本检查、关闭自动更新 |\r\n| [references/output-format.md](references/output-format.md) | 输出格式与展示规范 |\r\n| [references/error-handling.md](references/error-handling.md) | 错误处理与常见错误 |\r\n\r\n---\r\n\r\n## 完整使用流程\r\n\r\n```bash\r\n# 1. 登录（详见 references/auth.md）\r\nkugou-cli auth login # 获取二维码\r\nkugou-cli auth status\r\n\r\n# 1'. 或者直接导入已持有的 secret（跳过扫码）\r\nkugou-cli auth set-secret \"\"\r\n\r\n# 2. 搜索歌曲\r\nkugou-cli music search \"周杰伦\"\r\n\r\n# 3. 获取猜你喜欢\r\nkugou-cli music recommend guess\r\n\r\n# 4. 查看我的收藏（返回最近若干首，不支持分页）\r\nkugou-cli music favorites\r\n\r\n# 5. 查看最近播放（返回最近若干条，不支持分页）\r\nkugou-cli music recent\r\n\r\n# 6. 查看听歌统计\r\nkugou-cli music stats\r\n\r\n# 7. 查看抖音热歌榜\r\nkugou-cli music charts 52144\r\n\r\n# 8. 创建歌单\r\n# 优先走客户端路径（默认）：见 references/control.md §10\r\nkugou-cli control playlist create --name \"我的批量歌单\" --mixsongids \"32068120,233125060\"\r\n# 客户端不可用时才回退到云端（详见 references/music.md §7.1）：\r\nkugou-cli music create-playlist \"我的空歌单\"\r\nkugou-cli music create-playlist \"我的批量歌单\" --songs \"32068120,233125060\"\r\n\r\n# 9. 搜索歌单（拿到 global_id 后可透传给 control play-playlist）\r\nkugou-cli music search-playlist \"周杰伦\"\r\nkugou-cli music playlist-songs \"collection_3_938985631_304_0\"\r\n\r\n# 10. 控制本机酷狗客户端（仅 Windows / macOS，详见 references/control.md）\r\nkugou-cli control play --mixsongid 32100650 --song-name \"晴天\" --singer-name \"周杰伦\"\r\nkugou-cli control player --action pause\r\nkugou-cli control favorite song --mixsongid 32100650\r\n```\n\nFile v0.1.13:_meta.json\n\n{\n \"ownerId\": \"kn7crmv8zas1ep290wm2ag0wtn88te0q\",\n \"slug\": \"kugou-skill\",\n \"version\": \"0.1.13\",\n \"publishedAt\": 1788165956774\n}\n\nFile v0.1.13:references/auth.md\n\n# 认证命令 (auth)\r\n\r\n> 🔐 = 需要先登录\r\n\r\n## 命令列表\r\n\r\n| 命令 | 说明 | 需要登录 |\r\n|------|------|---------|\r\n| `kugou-cli auth login` | 获取二维码（`qrcode` 内部字符串 + `qrcode_img_url` 远程图片 URL + `qrcode_img_path` 本地 PNG 路径） | 否 |\r\n| `kugou-cli auth status` | 检查登录状态（**单次查询，不内部轮询**，agent 需外层循环 2-3s 间隔） | 否 |\r\n| `kugou-cli auth set-secret ` | 直接导入已持有的 base64 secret 登录（跳过扫码） | 否 |\r\n| `kugou-cli auth logout` | 登出 | 否 |\r\n\r\n---\r\n\r\n## 1. 扫码登录\r\n\r\n登录流程极简：\r\n\r\n```bash\r\n# Step 1: 获取二维码，同时得到远程 URL 和本地 PNG 路径\r\nkugou-cli auth login\r\n\r\n# Step 2: 循环调用 status（**单次查询不内部轮询**，agent 自己外层循环）\r\n# 每次间隔 2-3 秒，看到 logged_in=true / status=success 即完成\r\nkugou-cli auth status\r\n```\r\n\r\n**auth login 输出示例**:\r\n```json\r\n{\"qrcode\": \"xxx\", \"qrcode_img_path\": \"C:\\\\Temp\\\\kugou-qrcode.png\", \"qrcode_img_url\": \"https://static.kugou.com/.../qrcode.png\"}\r\n```\r\n\r\n字段说明：\r\n- `qrcode`：二维码字符串标识，**Agent 不要使用** —— 仅供 CLI 内部持久化，以便后续 status 调上游 check 接口\r\n- `qrcode_img_path`：CLI 生成的本地二维码 PNG 文件绝对路径。当前客户端支持读取或附加本地图片时使用它，例如 Codex 等本地文件能力较强的客户端\r\n- `qrcode_img_url`：酷狗上游返回的远程二维码图片 URL。当前客户端支持 Markdown 外链图片时使用它，例如 WorkBuddy 等客户端\r\n- `qrcode_img_path` 和 `qrcode_img_url` 是两种并行的图片展示方式，Agent 根据当前客户端能力自行选择一种，不要同时展示两张二维码\r\n\r\n---\r\n\r\n## 2. AI 引导流程\r\n\r\n### 2.1 决策点：先问 secret，再选路径\r\n\r\n在调用任何 auth 命令之前，**先询问用户**：\r\n\r\n> \"你手上是否已有可用的 base64 secret 字符串？（从其他设备/工具导出的）\"\r\n\r\n- **用户明确说\"有\"** → 直接走 §3 `set-secret`，跳过 §1 扫码\r\n- **用户说\"没有\"或不确定** → 走 §2.2 扫码流程\r\n- **当前环境无法发送图片**（纯文本 agent、SSH 远端、容器）→ 强制走 §3 `set-secret`，不要走扫码\r\n\r\n> **默认行为**：除非用户明确说\"我有 secret\"，否则优先走扫码。\r\n\r\n### 2.2 扫码流程\r\n\r\n1. 调用 `auth login`，读取返回的 `qrcode_img_path` 和 `qrcode_img_url`\r\n2. **根据当前客户端能力选择一种方式展示二维码图片**：\r\n - 客户端支持读取或附加本地文件（如 Codex 等）→ 优先使用 `qrcode_img_path`，通过客户端的本地图片读取/附件能力展示。不要只把路径作为普通文本发给用户\r\n - 客户端支持 Markdown 外链图片（如 WorkBuddy 等）→ 使用 `qrcode_img_url`，在消息中输出 `![酷狗登录二维码]()`\r\n - Agent 可以自行选择最适合当前环境的方式，不要同时展示两张二维码\r\n - **避免**只输出“请打开 xxx URL”或“图片路径是 xxx”这种纯文字提示，用户应直接看到二维码图片\r\n - 选择的方式展示失败时，切换到另一种方式：远程图片加载失败则尝试本地文件，本地文件无法读取则尝试远程 Markdown 图片\r\n - 如果当前客户端既不能读取本地文件，也不能渲染远程 Markdown 图片 → 放弃扫码，切换到 §3 `set-secret` 路径\r\n3. **阶段 A — 主动轮询（覆盖秒扫）**：图片展示后，**主动**外层循环调用 `auth status`，每次间隔 2-3 秒，**最多 5 次**（与 `failed` 重试合并计数）：\r\n - 看到 `logged_in: true` → 完成，继续执行用户请求\r\n - 看到 `status: success` → 完成，继续执行用户请求\r\n - 看到 `status: scanned` → 等几秒再调一次 status\r\n - 看到 `status: failed` → **不要换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（计入 5 次轮询预算）\r\n - 看到 `status: expired` → **不再继续轮询**，主动告诉用户\"二维码已失效，正在重新获取\"，调 `auth login` 拿新图，回到步骤 1\r\n - 5 次都是 `waiting` / `failed` → 进入阶段 B\r\n4. **阶段 B — 等待用户反馈（关键）**：5 次主动轮询后仍未登录，**停下来**，不再调任何 auth 命令。主动告诉用户：\r\n > \"请用酷狗 APP 扫码登录，扫完后告诉我已扫码\"\r\n 然后**等用户主动回复**。**不要**自己继续轮询。\r\n5. **阶段 C — 验证登录**：用户回复\"已扫码\"后，调一次 `auth status` 验证：\r\n - `logged_in: true` → 完成，继续执行用户请求\r\n - `status: scanned` → 用户在手机上还没点确认，等几秒再调一次\r\n - `status: failed` → **不要换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（最多重试 2-3 次）\r\n - `status: expired` → 上游明确说过期（CLI 已清理本地），重新 `auth login` 拿新图，回到步骤 1\r\n - `logged_in: false`（无 status 字段）→ qrcode 已被清理（通常是上一步 `expired` 后状态），提示用户\"二维码可能已过期，正在重新获取\"并回到步骤 1\r\n6. **若用户在阶段 B 回复\"没看到图片\" / \"图片打不开\"** → 先切换到另一种二维码展示方式；两种方式都失败后，再切换到 §3 `set-secret` 路径\r\n7. **若用户在阶段 B 回复\"已扫码\"**但阶段 C 验证发现没登录成功（`scanned` / `failed`），按阶段 C 各项处理，不要替用户做\"再扫一次\"之类的猜测\r\n\r\n### 2.3 状态表\r\n\r\n| 返回 | 含义 | Agent 应做 |\r\n|------|------|-----------|\r\n| `{\"logged_in\": true, \"nickname\": \"...\", \"login_time\": \"...\"}` | 已登录（**已有 token 持久化**，通常是之前登录过） | 继续执行用户请求 |\r\n| `{\"logged_in\": true, \"status\": \"success\", \"nickname\": \"...\"}` | 扫码刚完成登录（**本轮 status 检查中完成 token 持久化**） | 继续执行用户请求 |\r\n| `{\"logged_in\": false, \"status\": \"waiting\", \"qrcode\": \"...\"}` | 二维码待扫码 | **阶段 A**：2-3s 后重试 status，最多 5 次；5 次后**进入阶段 B**，停下来等用户主动反馈 |\r\n| `{\"logged_in\": false, \"status\": \"scanned\", \"nickname\": \"...\", \"qrcode\": \"...\"}` | 已扫码待确认 | 等几秒再调一次 status（用户还没在手机上点确认） |\r\n| `{\"logged_in\": false, \"status\": \"expired\", \"message\": \"...\"}` | 二维码被上游明确判定为过期（**CLI 会自动清理本地 qrcode**） | **不再重试**：调 `auth login` 拿新图（覆盖本地 qrcode），回到 §2.2 步骤 1 |\r\n| `{\"logged_in\": false, \"status\": \"failed\", \"message\": \"...\"}` | 上游返回了 CLI 不识别的 status 码（**CLI 不会清理本地 qrcode**，本地缓存仍可用） | **重试** 1-2 秒后再调一次 status（用同一个本地 qrcode）；阶段 A 中计入 5 次预算，阶段 C 中最多 2-3 次。**不要调 `auth login` 换新图** |\r\n| `{\"logged_in\": false}` | 无登录态（未登录过 / 登录过期被清理 / qrcode 刚被 expired 清理掉） | 走完整登录流程（§2.1 决策点） |\r\n\r\n> **判定\"已登录\"**：`logged_in: true` 即算成功，**不管有没有 `status: success` 字段**——两种 JSON shape 都合法。\r\n>\r\n> 区分\"无登录态\"和\"等待扫码\"的关键：前者**没有** `status` 字段，后者有。\r\n>\r\n> **轮询逻辑（两阶段）**：\r\n> - 阶段 A：图片刚展示，主动循环 status 最多 5 次（2-3s 间隔）→ 覆盖秒扫场景\r\n> - 阶段 B：5 次仍 `waiting` → 主动告诉用户\"请扫码登录，扫完后告诉我已扫码\"，**不再调 status**，等用户**主动回复**\r\n\r\n### 2.3.1 边界提醒：`expired` 会清掉 qrcode 并需换新图，`failed` 不清且应重试\r\n\r\n**关键事实**：\r\n\r\n- `status: expired` 时 CLI 会自动清理本地 qrcode 文件（**不是清理登录态**）。这是上游**明确**判定二维码失效（协议层不可恢复）→ **必须换新图**。\r\n- `status: failed` 时 CLI **不会**清理本地 qrcode 文件。这是上游返回了 CLI 不识别的 status 码（短暂异常 / 未知协议值 / 上游 gateway 抖动）。本地 qrcode 字符串**没失效** → **不应换新图，应重试同一 qrcode**。\r\n\r\n**两种返回在阶段 A / 阶段 C 的处理**：\r\n\r\n| 见到位置 | 状态值 | 原因可能性 | Agent 应做 |\r\n|---------|--------|-----------|-----------|\r\n| 阶段 A 主动轮询中 | `expired` | 上游明确说过期 | **不再继续轮询**，主动告诉用户\"二维码已失效，正在重新获取\"，调 `auth login` 拿新图，回到 §2.2 步骤 1 |\r\n| 阶段 A 主动轮询中 | `failed` | 上游短暂异常 / 未知 status 码 | **不换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（计入阶段 A 的 5 次主动轮询预算） |\r\n| 阶段 C 用户说\"已扫码\"后验证 | `expired` | 登录过程中上游判定过期 | 重新 `auth login` 拿新图 |\r\n| 阶段 C 用户说\"已扫码\"后验证 | `failed` | 登录过程中上游返回非预期 | **不换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status，最多重试 2-3 次；仍 `failed` 再按上游持续异常处理（建议告诉用户稍后重试或切 `set-secret`） |\r\n| 阶段 A 之后阶段 B 之前 | `expired` / `failed` | （不应发生） | 视为阶段 A 见到对应状态值处理 |\r\n\r\n> **判定要点**：\r\n> - 不要因为\"看到 expired/failed → 看到 logged_in: false\"就误判\"用户没登录\"。expired/failed 都是 qrcode 状态，不是登录态。\r\n> - `expired` 后下次 `auth status` 会拿到 `{\"logged_in\": false}`（无 status 字段，本地已被清）。\r\n> - `failed` 后下次 `auth status` **可能仍返回 failed**（上游持续异常），也可能恢复 `waiting`（上游恢复后用同一个 qrcode 仍可扫码登录）。**不要假设 `failed` 后本地一定被清**。\r\n> - 关键决策：`expired` 是**协议层不可恢复** → 换新图；`failed` 是**传输层/未知码** → 重试同一 qrcode。\r\n\r\n### 备选路径：用户已持有 secret\r\n\r\n当用户**已经持有**一个有效的 base64 secret 字符串时（例如从其他设备、其他工具导出的），可以直接用 `auth set-secret` 跳过整个扫码流程，**不需**调用 `auth login` / `auth status`：\r\n\r\n```bash\r\nkugou-cli auth set-secret \"\"\r\n```\r\n\r\n调用成功后 secret 会被持久化（路径见 §3），所有 music 命令立即可用，效果与扫码登录一致。\r\n\r\n---\r\n\r\n\r\n## 3. 直接设置 secret\r\n\r\n**适用场景**：\r\n- 用户在其他设备/工具上已登录酷狗，导出或复制了一份 base64 secret\r\n- 测试、调试、自动化场景下需要直接注入 secret\r\n- 任何不便于扫码的终端环境（如 SSH 远端、容器、CI）\r\n- 当前 agent 工具集无法渲染 `qrcode_img_url` 远程图片，或无法读取 `qrcode_img_path` 本地图片（不联网、不支持 Markdown 渲染或不支持本地图片附件，见 §2.2）\r\n\r\n**命令**:\r\n\r\n```bash\r\nkugou-cli auth set-secret \"{secret}\"\r\n```\r\n\r\n**shell 引号注意事项**：\r\n- secret 字符串含 `+`、`/`、`=` 等 base64 字符是**正常的**，**不会**被 shell 误解析\r\n- 但 `+` 在 bash 中是通配符、`=` 在 cmd.exe 中会触发变量赋值，**务必用引号包起来**\r\n- 推荐使用双引号 `\"...\"`（除非 secret 中含 `$`，那就用单引号 `'...'`）\r\n\r\n**输出示例**:\r\n```json\r\n{\"status\": \"ok\", \"message\": \"secret saved\"}\r\n```\r\n\r\n**失败示例**（secret 为空）:\r\n```\r\nsecret cannot be empty\r\n```\r\n\r\n**与扫码登录的等价性**：\r\n- secret 落到本地登录态文件，**跨平台位置**：\r\n - Linux/macOS：`~/.config/kugou-cli/auth.json`\r\n - Windows：`%AppData%\\kugou-cli\\auth.json`（通常为 `C:\\Users\\\\AppData\\Roaming\\kugou-cli\\auth.json`）\r\n - 若用户询问\"登录态存在哪\"，按平台给对应路径，**不要**直接说 `~/.config/...` 在 Windows 下不准确\r\n- 后续 `auth status` 输出 `{\"logged_in\": true}`\r\n- 所有 `music` 子命令立即可用，无需任何额外步骤\r\n- nickname 字段为空（因为导入途径不带昵称），不影响功能\r\n\r\n**登录态过期处理**：\r\n- 当任意 `music` 命令遇到登录态过期时，CLI 会**自动清理**本地登录态，并在 stderr 输出 `账号登录过期，请重新登录`，以非 0 exit code 退出\r\n- Agent 收到该错误后应**直接引导用户重新登录**（`auth login` 走扫码，或 `auth set-secret` 导入新 secret），无需手动清理本地文件\r\n- 之后调用 `auth status` 会得到 `{\"logged_in\": false}`（**无 status 字段**，对应 §2.3 状态表最后一行）\r\n\r\n---\r\n\r\n## 4. 登出 (logout)\r\n\r\n**命令**：\r\n\r\n```bash\r\nkugou-cli auth logout\r\n```\r\n\r\n**行为**：\r\n1. **未登录时**：幂等直接返回 `{\"status\": \"logged out\"}`\r\n2. **已登录时**：CLI 会先与服务端同步登出，**确认成功后才**清理本地登录态。任何一步失败都会在 stderr 报错并保留本地登录态，以便用户重试\r\n3. 成功输出：`{\"status\": \"logged out\"}`\r\n\r\n**失败场景**：\r\n- 网络/服务端异常 → stderr 报错，**不清理**本地，提示用户稍后重试\r\n- 此时再次执行 `auth status` 仍会显示 `logged_in: true`，本地登录态被保留\r\n\r\n**AI 引导建议**：\r\n- 用户说\"登出 / 退出登录 / 注销\"时直接执行 `auth logout`\r\n- 看到 `{\"status\": \"logged out\"}` 后，告诉用户已成功登出，可继续 `auth login` 重新登录\r\n- 看到错误时：\r\n 1. **自动重试 1 次**（网络抖动常见）\r\n 2. 仍失败 → 告知用户\"登出失败，本地登录态保留，可能是网络问题\"，**询问**用户：\"是否要稍后重试？\"\r\n 3. **不要**擅自清理本地文件或调任何 music 命令\n\nFile v0.1.13:references/control.md\n\n# 控制命令 (control)\r\n\r\n> AI-facing usage guide for `kugou-cli control` — the local PC/Mac Kugou client control subcommands.\r\n\r\n本模块通过本机 HTTP server 控制 PC/Mac 酷狗客户端，支持播放控制、收藏管理、歌单创建等操作。输出格式为原始 JSON（详见 [references/output-format.md](./output-format.md)）。\r\n\r\n**前置条件**: CLI 已登录（`kugou-cli auth login`）+ 酷狗客户端正在运行。仅支持 Windows / macOS（Linux 运行时会报错，见下方错误场景）。\r\n\r\n---\r\n\r\n## 命令列表\r\n\r\n### 读操作（read）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control start` | 显式触发握手/唤起客户端（用于预热或调试） |\r\n| `kugou-cli control status` | 获取客户端状态（协议版本、登录态、能力列表） |\r\n| `kugou-cli control current` | 获取当前播放歌曲（歌名、进度、音量、收藏状态） |\r\n\r\n### 播放器控制（player）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control play` | 播放歌曲（按 mixsongid） |\r\n| `kugou-cli control play-playlist` | 播放整个歌单（按 global_collection_id） |\r\n| `kugou-cli control continue-play` | 拉取\"另一设备续播\"列表并开始播放 |\r\n| `kugou-cli control player` | 播放器控制（播放/暂停/切歌/停止） |\r\n| `kugou-cli control seek` | 进度控制（快进/快退/跳转） |\r\n| `kugou-cli control volume` | 音量控制（增减/设置/静音） |\r\n\r\n### 账户操作（account）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control favorite song` | 收藏/取消收藏歌曲 |\r\n| `kugou-cli control favorite songlist` | 收藏/取消收藏歌单 |\r\n| `kugou-cli control playlist create` | 创建本地歌单（带歌曲列表） |\r\n\r\n### 系统操作（utility）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control open` | 打开客户端内页面（主界面/歌手/专辑/歌单/搜索） |\r\n\r\n---\r\n\r\n## 1. start — 显式触发握手\r\n\r\n触发酷狗客户端的 URL scheme 唤起，等待客户端建立本机 HTTP 通道并返回状态。仅用于预热通道或调试连通性，不调用任何 `/v1/...` 业务接口。\r\n\r\n```bash\r\nkugou-cli control start\r\n```\r\n\r\n**输出示例**（成功）:\r\n```json\r\n{\"handshake\":\"ok\",\"addr\":\"http://127.0.0.1:52144\"}\r\n```\r\n\r\n**输出示例**（失败）:\r\n```\r\nkugou-cli control: not logged in, run `kugou-cli auth login` first: auth file not found\r\n```\r\n\r\n---\r\n\r\n## 2. status — 获取客户端状态\r\n\r\n查询本地酷狗客户端的协议版本、登录态和能力列表。\r\n\r\n```bash\r\nkugou-cli control status\r\n```\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"code\": 0,\r\n \"data\": {\r\n \"version\": \"1.0.0\",\r\n \"login\": true,\r\n \"capabilities\": [\"play\", \"pause\", \"seek\", \"volume\", \"favorite\", \"playlist\"]\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 3. current — 获取当前播放\r\n\r\n查询当前播放歌曲详情，包括歌名、歌手、进度、音量和收藏状态。\r\n\r\n```bash\r\nkugou-cli control current\r\n```\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"code\": 0,\r\n \"data\": {\r\n \"song_name\": \"晴天\",\r\n \"singer_name\": \"周杰伦\",\r\n \"mixsongid\": \"32100650\",\r\n \"position_ms\": 45000,\r\n \"duration_ms\": 240000,\r\n \"volume\": 65,\r\n \"favorited\": false\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 4. play — 播放歌曲\r\n\r\n在客户端播放一首歌曲。`--mixsongid` 必填，其余字段可选（仅用于客户端展示，不影响播放命中）。\r\n\r\n```bash\r\nkugou-cli control play --mixsongid 32100650 --song-name \"晴天\" --singer-name \"周杰伦\"\r\nkugou-cli control play --mix-song-id 32100650 --mode \"append_queue\"\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--mixsongid` | 歌曲 mixsongid（必填），也支持 `--mix-song-id` 别名 |\r\n| `--song-name` | 歌曲显示名（可选） |\r\n| `--singer-name` | 歌手显示名（可选） |\r\n| `--mode` | 播放模式：`append_queue`（追加队列）、`next_play`（下一首播放） |\r\n\r\n> 🎵 **AI 必读**：命令成功后**必须**调 `control current` 拿到当前歌曲名/歌手，告知用户。**不要**直接展示 `--song-name` / `--singer-name` 参数——那只是客户端展示标签，与实际播放可能不一致。\r\n\r\n**输出示例**:\r\n```json\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n```\r\n\r\n---\r\n\r\n## 5. player — 播放器控制\r\n\r\n发送传输控制动作到播放器（播放/暂停/切歌等）。\r\n\r\n```bash\r\nkugou-cli control player --action pause\r\nkugou-cli control player --action next\r\nkugou-cli control player --action resume\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--action` | 动作（必填）：`play` `resume` `pause` `toggle` `next` `prev` `previous` `stop` |\r\n\r\n`prev` 和 `previous` 视为同义词。\r\n\r\n> 🎵 **AI 必读**：使用 `next` / `prev` / `previous` **切歌后**必须调 `control current` 拿到当前歌曲名/歌手，告知用户。`play` / `pause` / `resume` / `toggle` / `stop` 等切换播放状态的动作不需要告知曲目（曲目未变）。\r\n\r\n**输出示例**:\r\n```json\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n```\r\n\r\n---\r\n\r\n## 5.1 continue-play — 拉取另一设备续播列表并播放\r\n\r\n拉取云端\"另一设备最近播放\"的续播列表（酷狗首页的\"续接播放\"入口），并在本地客户端开始播放。\r\n\r\n```bash\r\n# 默认：替换当前队列，从头播放\r\nkugou-cli control continue-play\r\n\r\n# 不打断当前播放：把续播列表追加到本地队列尾部\r\nkugou-cli control continue-play --mode append_queue\r\n\r\n# 把续播列表插到当前曲目之后立即播放\r\nkugou-cli control continue-play --mode next_play\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--mode` | 队列策略：空（默认，替换队列）/ `append_queue`（追加队列尾部）/ `next_play`（下一首播放） |\r\n\r\n> 🎵 **AI 必读**：命令成功后**必须**调 `control current` 拿到当前歌曲名/歌手，告知用户。\r\n\r\n**前置条件**:\r\n- 已登录：`kugou-cli auth login`\r\n- 客户端内已登录（否则返回 409/4091\"login required\"，见错误场景 §2）\r\n- 本地客户端必须运行（`kugou-cli control start` 健康）\r\n\r\n**输出示例**:\r\n```json\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n```\r\n\r\n---\r\n\r\n## 6. seek — 进度控制\r\n\r\n控制当前播放歌曲的进度。\r\n\r\n```bash\r\n# 快进 30 秒\r\nkugou-cli control seek --action forward --offset-ms 30000\r\n\r\n# 快退 10 秒\r\nkugou-cli control seek --action rewind --offset-ms 10000\r\n\r\n# 跳转到 2 分钟位置\r\nkugou-cli control seek --action set --position-ms 120000\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--action` | 动作（必填）：`forward` `rewind` `set` |\r\n| `--offset-ms` | 偏移量（毫秒，forward/rewind 时必填） |\r\n| `--position-ms` | 绝对位置（毫秒，action=set 时必填） |\r\n\r\n---\r\n\r\n## 7. volume — 音量控制\r\n\r\n调整客户端音量或静音状态。\r\n\r\n```bash\r\n# 音量增加 5 格\r\nkugou-cli control volume --action up --delta 5\r\n\r\n# 音量减少 10 格\r\nkugou-cli control volume --action down --delta 10\r\n\r\n# 设置音量到 42\r\nkugou-cli control volume --action set --volume 42\r\n\r\n# 静音\r\nkugou-cli control volume --action mute\r\n\r\n# 取消静音\r\nkugou-cli control volume --action unmute\r\n\r\n# 切换静音状态\r\nkugou-cli control volume --action toggle_mute\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--action` | 动作（必填）：`up` `down` `set` `mute` `unmute` `toggle_mute` |\r\n| `--delta` | 音量变化量（up/down 时必填） |\r\n| `--volume` | 绝对音量 0-100（action=set 时必填；CLI 不做范围校验，由客户端夹取） |\r\n\r\n---\r\n\r\n## 8. favorite song — 收藏歌曲\r\n\r\n收藏或取消收藏一首歌曲。\r\n\r\n```bash\r\n# 收藏歌曲\r\nkugou-cli control favorite song --mixsongid 32100650 --song-name \"晴天\" --singer-name \"周杰伦\"\r\n\r\n# 取消收藏\r\nkugou-cli control favorite song --action remove --mixsongid 32100650\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--action` | 操作（默认 `add`）：`add` `remove` |\r\n| `--mixsongid` | 歌曲 mixsongid（必填） |\r\n| `--song-name` | 歌曲显示名（可选） |\r\n| `--singer-name` | 歌手显示名（可选） |\r\n\r\n---\r\n\r\n## 9. favorite songlist — 收藏歌单\r\n\r\n收藏或取消收藏一个歌单。\r\n\r\n```bash\r\n# 收藏歌单（action=add 时必填 --list-name 与 --owner-user-id）\r\nkugou-cli control favorite songlist --list-name \"精选\" --global-collection-id abcdef --owner-user-id 1286024014\r\n\r\n# 取消收藏（--global-collection-id 必填；--list-name / --owner-user-id 不允许传）\r\nkugou-cli control favorite songlist --action remove --global-collection-id abcdef\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--action` | 操作（默认 `add`）：`add` `remove` |\r\n| `--global-collection-id` | 歌单全局 ID（即协议层的 `list_gid`，`add` / `remove` 都必填） |\r\n| `--list-name` | 歌单显示名（**`action=add` 时必填**） |\r\n| `--owner-user-id` | 歌单所有者 ID（**`action=add` 时必填**；`action=remove` 时不允许传） |\r\n| `--list-icon` | 歌单图标 URL（可选） |\r\n| `--list-intro` | 歌单简介（可选） |\r\n| `--list-tags` | 歌单标签（可选） |\r\n\r\n> **校验**：CLI 在本地做严格校验，缺任一必填项都会 exit 1 报错：\r\n> - `--global-collection-id`：**`add` 和 `remove` 两种 action 都必填**（用于标识目标歌单）\r\n> - `--list-name`：仅 `--action=add` 必填\r\n> - `--owner-user-id`：仅 `--action=add` 必填；`--action=remove` 时**禁止**传（避免向取消请求带过时元数据）\r\n\r\n---\r\n\r\n## 10. playlist create — 创建歌单\r\n\r\n> ✅ **创建歌单的首选路径**。Agent 在用户同意创建歌单时**必须**先尝试本命令；只有当客户端不可用（Linux / 客户端未运行 / 握手失败 / 调用失败）时才回退到云端备选 [`music create-playlist`](./music.md#71-接口说明云端备选仅在-70-第-4-条任一条件成立时使用)。完整决策逻辑见 [music.md §7 创建歌单](./music.md#7-创建歌单)。\r\n\r\n在本地客户端创建一个新歌单，并可选地添加歌曲。\r\n\r\n```bash\r\nkugou-cli control playlist create --name \"周杰伦精选\" --mixsongids \"32100650,32068120\"\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--name` | 歌单名称（必填） |\r\n| `--mixsongids` | 歌曲 mixsongid 列表，逗号分隔（必填，至少含一个有效 ID） |\r\n\r\n`--mixsongids` 示例：`\"32100650,32068120\"` 或 `\"32100650, 32068120\"`（空格会被忽略）。\r\n\r\n**前置条件**（与 control 其他子命令一致，详见 [§前置条件总结](#前置条件总结)）：\r\n- CLI 已登录（`kugou-cli auth login`）\r\n- 本地酷狗客户端（Windows / macOS）正在运行且握手健康（`kugou-cli control start`）\r\n- 客户端内已登录（否则会收到 409/4091 `login required`，见 [§错误场景 2](#场景-2客户端未登录http-409--code-4091)）\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"code\": 0,\r\n \"data\": {\r\n \"accepted\": true,\r\n \"count\": 2,\r\n \"global_collection_id\": \"全局歌单id\",\r\n \"name\": \"歌单名\",\r\n \"songlist_id\": 123456\r\n },\r\n \"message\": \"ok\",\r\n \"request_id\": \"ec-124-1786072145\"\r\n}\r\n```\r\n\r\n> **字段语义说明（重要）**：\r\n> - `data.global_collection_id`：字符串形态的歌单全局 ID（协议层 `list_gid`），**可直接传给 `control play-playlist --global-id`**（详见 [§12 play-playlist](./control.md#12-play-playlist--播放整个歌单)）\r\n> - `data.songlist_id`：数字形态的本地客户端歌单 ID，**不能直接传给 `play-playlist --global-id`**，仅在客户端 UI 内展示用\r\n>\r\n> 实际响应字段由客户端版本决定，**两条不一定同时存在**——某些客户端版本可能只返回 `songlist_id` 而无 `global_collection_id`。Agent 在用户同意播放时优先取 `global_collection_id`；若缺失，按下方\"ID 流转提示\"回退。\r\n\r\n### 创建成功后必须主动询问用户是否播放\r\n\r\n> 🎵 **AI 必读**：本命令返回成功（`code: 0`）后，Agent **必须主动询问用户**\"是否要播放这个歌单\"，等用户明确回复后再决定下一步。详见 [music.md §7.0 调用原则 第 5 条](./music.md#70-调用原则ai-必读)。\r\n\r\n用户同意时优先调用：\r\n\r\n```bash\r\n# 客户端路径：默认清空当前队列、按歌单顺序从头播放\r\nkugou-cli control play-playlist --global-id \"\"\r\n\r\n# 不打断当前播放：把新歌单追加到队列尾部\r\nkugou-cli control play-playlist --global-id \"\" --playlist-mode append_queue\r\n```\r\n\r\n> **ID 流转提示**：本命令 `data.songlist_id` 是数字 ID，而 `control play-playlist --global-id` 需要的是字符串 `global_collection_id`（协议层 `list_gid`），二者不可直接互转。Agent 在用户同意播放时按以下顺序获取可用 ID：\r\n> 1. **优先**：取响应里 `data.global_collection_id`（字符串）→ 直接传给 `play-playlist --global-id`\r\n> 2. **回退一**：客户端未返回 `global_collection_id` 时，用响应里的歌单名（`data.name`）跑 `kugou-cli music search-playlist \"\"`，从结果里挑一个匹配的 `global_id` 传给 `play-playlist`\r\n> 3. **回退二**：以上两步都拿不到时，告诉用户\"刚创建的歌单 ID 无法用于播放命令，请在客户端 UI 内打开播放\"（**不要**编造或猜 ID）\r\n> 4. **绝对禁止**：把数字 `songlist_id` 当成 `global_id` 用——类型不匹配，客户端协议层会拒绝\r\n\r\n> **播放路径全部失败的回退**：若用户同意播放，但客户端仍不可用（control play-playlist 因客户端未运行 / ID 拿不到而失败），Agent **不要**循环重试。按 [music.md §7.2 云端歌单的播放](./music.md#72-云端歌单的播放控制浏览器打开-h5-链接) 走\"先探后告知\"的浏览器路径：用浏览器工具打开云端 `song_list_url` 尝试点击播放，工具不可用时明确告知用户手动打开。\r\n\r\n---\r\n\r\n## 11. open — 打开客户端页面\r\n\r\n在酷狗客户端中打开指定页面（非静默，客户端主窗口会切换到对应视图）。`silent` 字段硬编码为 `false`。\r\n\r\n```bash\r\n# 打开主界面\r\nkugou-cli control open --target-type main\r\n\r\n# 打开歌手页\r\nkugou-cli control open --target-type singer --singer-id 12345\r\n\r\n# 打开专辑页（可选 --mixsongid 作为专辑根曲）\r\nkugou-cli control open --target-type album --album-id 67890 --mixsongid 8888\r\n\r\n# 打开歌单页\r\nkugou-cli control open --target-type songlist --global-collection-id \"collection_3_938985631_304_0\"\r\n\r\n# 打开搜索结果页\r\nkugou-cli control open --target-type search --keyword \"周杰伦\"\r\n```\r\n\r\n**target-type 和必填参数**:\r\n\r\n| target-type | 必填参数 | 说明 |\r\n|-------------|----------|------|\r\n| `main` | 无 | 打开主界面 |\r\n| `singer` | `--singer-id` | 歌手页 |\r\n| `album` | `--album-id` | 专辑页 |\r\n| `songlist` | `--global-collection-id` | 歌单页（协议 wire 字段 `list_gid`） |\r\n| `search` | `--keyword` | 搜索结果页 |\r\n\r\n**通用可选参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--mixsongid` | 可选 mixsongid（如 `album` 时作为专辑根曲） |\r\n\r\n---\r\n\r\n## 12. play-playlist — 播放整个歌单\r\n\r\n按歌单的 `global_collection_id`（即协议层的 `list_gid`）让本地酷狗客户端联网拉歌单后播放。本命令只传 `list_gid` 给客户端，**无需 CLI 端联网预翻页**——歌单内容由客户端在收到请求后异步拉取（CLI 不需要外网/代理）。\r\n\r\n**`--global-id` 的合法来源**（按推荐顺序）：\r\n\r\n1. **`music search-playlist` / `recommend-playlist` 响应的 `global_id` 字段**（最稳，跨客户端兼容）\r\n2. **`control playlist create` 响应的 `data.global_collection_id` 字段**（仅当客户端版本返回该字段时可用——见 [§10 输出字段语义](./control.md#10-playlist-create--创建歌单)）\r\n3. `music playlist-songs ` 直接使用你已有的字符串 ID\r\n\r\n**不要**：把 `control playlist create` 响应里的数字 `data.songlist_id` 当成 `global-id` 用（类型不匹配，会被客户端协议层拒绝）。\r\n\r\n```bash\r\n# 默认：清空当前队列，按歌单顺序从头播放\r\nkugou-cli control play-playlist --global-id \"collection_3_938985631_304_0\"\r\n\r\n# 不打断当前播放：歌单追加到队列尾部\r\nkugou-cli control play-playlist --global-id \"...\" --playlist-mode append_queue\r\n\r\n# 把歌单插到当前曲目之后立即播放\r\nkugou-cli control play-playlist --global-id \"...\" --playlist-mode next_play\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r\n| `--global-id` | 歌单全局 ID（必填），即协议层的 `list_gid`，例如 `collection_3_938985631_304_0`。必须是字符串（不要传数字 `songlist_id`）|\r\n| `--playlist-mode` | 队列策略：`auto`（默认）/ `append_queue` / `next_play` |\r\n\r\n**playlist-mode 详解**:\r\n\r\n| 取值 | wire 上的 `play_mode` | 客户端行为 | 适用场景 |\r\n|------|----------------------|----------|----------|\r\n| `auto`（默认） | **省略** | 客户端默认 = 清空当前队列后按歌单顺序从头播放 | 切到歌单里从头听 |\r\n| `append_queue` | `\"append_queue\"` | 歌单追加到播放队列尾部，不打断当前播放 | 不打断当前歌曲，排队播放 |\r\n| `next_play` | `\"next_play\"` | 歌单插入到当前曲目之后立即播放，后续队列顺延 | 听完这首就想听歌单 |\r\n\r\n> 🎵 **AI 必读**：命令成功后**必须**调 `control current` 拿到当前歌曲名/歌手，告知用户。本命令是异步的——客户端拉歌单歌曲可能要等几秒；如 `control current` 一开始返回 `code: 非 0`，等 1-2 秒再试一次。\r\n\r\n**前置条件**:\r\n\r\n- 已登录：`kugou-cli auth login`\r\n- 酷狗桌面客户端在后台运行，且握手健康：`kugou-cli control start`\r\n\r\n**典型联动**:\r\n\r\n```bash\r\n# 搜歌单 → 取 global_id → 播放\r\nGID=$(kugou-cli music search-playlist \"周杰伦\" | jq -r '.data.list[0].global_id')\r\nkugou-cli control play-playlist --global-id \"$GID\"\r\n\r\n# 立即听下一首（不打断当前曲目）\r\nkugou-cli control play-playlist --global-id \"$GID\" --playlist-mode next_play\r\n```\r\n\r\n---\r\n\r\n## 错误场景\r\n\r\n### 场景 1：CLI 未登录（登录态缺失）\r\n\r\n未登录时，任意 `control` 子命令都会在入口被拦截。\r\n\r\n**触发**:\r\n```bash\r\nkugou-cli control status\r\n```\r\n\r\n**stderr**:\r\n```\r\nkugou-cli control: not logged in, run `kugou-cli auth login` first: auth file not found\r\n```\r\n\r\n**stdout**: 无\r\n\r\n**exit code**: 1\r\n\r\n**修复**: 运行 `kugou-cli auth login` 完成 CLI 扫码登录。\r\n\r\n---\r\n\r\n### 场景 2：客户端未登录（HTTP 409 / code: 4091）\r\n\r\n`favorite song`、`favorite songlist`、`playlist create` 等需要账号的操作，如果客户端本身未登录（cookie/token 过期或从未登录），协议层返回 `code: 4091`。\r\n\r\n**触发**:\r\n```bash\r\nkugou-cli control favorite song --mixsongid 32100650\r\n```\r\n\r\n**stdout**（协议响应原样输出）:\r\n```json\r\n{\"code\":4091,\"msg\":\"login required\"}\r\n```\r\n\r\n**stderr**（CLI 追加的提示）:\r\n```\r\nHTTP 409\r\n请在酷狗客户端内登录后重试\r\n```\r\n\r\n**exit code**: 0（CLI 正常退出，调用方从 stdout 的 `code` 字段自行判断）\r\n\r\n**注意**: CLI 不会 exit 1，也不会提示去运行 `kugou-cli auth login`（那是 CLI 登录，跟客户端登录是两件独立的事）。\r\n\r\n**修复**: 在酷狗客户端 UI 内扫码登录客户端。\r\n\r\n---\r\n\r\n### 场景 3：客户端未安装或未启动（握手超时）\r\n\r\n握手在 6 秒内未完成，说明酷狗客户端未安装、未运行或未响应 URL scheme 唤起。\r\n\r\n**触发**:\r\n```bash\r\nkugou-cli control status\r\n```\r\n\r\n（假设客户端未运行）\r\n\r\n**stderr**:\r\n```\r\nis Kugou client installed?\r\n```\r\n\r\n**stdout**: 无\r\n\r\n**exit code**: 1\r\n\r\n**排查步骤**:\r\n1. 确认酷狗客户端已安装（Windows: `KuGou.exe`，Mac: `/Applications/KuGou.app`）\r\n2. 确认客户端已启动并运行\r\n3. Windows 用户确认 URL scheme `kugou://` 已注册（可在 PowerShell 中试 `start kugou://workbuddy`）\r\n4. Mac 用户在 Safari 地址栏试 `mackugou://workbuddy` 确认 LaunchServices 注册正常\r\n\r\n---\r\n\r\n### 场景 4：Linux 不支持\r\n\r\n在非 Windows / macOS 系统上运行任意 `control` 子命令，会被运行时拦截。\r\n\r\n**触发**（在 Linux 上）:\r\n```bash\r\nkugou-cli control status\r\n```\r\n\r\n**stderr**:\r\n```\r\nkugou-cli control: linux is not supported\r\n```\r\n\r\n**stdout**: 无\r\n\r\n**exit code**: 1\r\n\r\n**说明**: 酷狗客户端仅提供 Windows 和 macOS 版本，因此 control 命令也仅在这两个平台可用。所有非 Windows/macOS 系统都会被拒绝，包括 Linux、FreeBSD、OpenBSD 等。\r\n\r\n---\r\n\r\n## 典型 AI Agent 工作流\r\n\r\n以下为通过 `control` 命令控制本地酷狗客户端的典型流程。\r\n\r\n### 完整示例：搜索并播放歌曲\r\n\r\n```\r\n# 1. 搜索歌曲（music 命令，返回 mix_song_id）\r\n$ kugou-cli music search \"周杰伦 晴天\"\r\n{\r\n \"data\": {\r\n \"list\": [{\r\n \"song_name\": \"晴天\",\r\n \"mix_song_id\": \"32100650\",\r\n \"artist_name\": \"周杰伦\"\r\n }]\r\n }\r\n}\r\n\r\n# 2. 让客户端播放这首歌\r\n$ kugou-cli control play --mixsongid 32100650 --song-name \"晴天\" --singer-name \"周杰伦\"\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n\r\n# 3. 暂停播放\r\n$ kugou-cli control player --action pause\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n\r\n# 4. 查看当前播放状态\r\n$ kugou-cli control current\r\n{\r\n \"code\": 0,\r\n \"data\": {\r\n \"song_name\": \"晴天\",\r\n \"position_ms\": 30000,\r\n \"volume\": 65\r\n }\r\n}\r\n\r\n# 5. 收藏当前歌曲\r\n$ kugou-cli control favorite song --mixsongid 32100650\r\n{\"code\":0,\"data\":{\"accepted\":true}}\r\n\r\n# 6. 搜索更多歌曲并创建歌单\r\n$ kugou-cli music search \"周杰伦\"\r\n# 假设返回多个结果，mix_song_id 分别为 32100650、32068120、31598745\r\n\r\n$ kugou-cli control playlist create --name \"周杰伦精选\" --mixsongids \"32100650,32068120,31598745\"\r\n{\"code\":0,\"data\":{\"songlist_id\":\"abc123\",\"name\":\"周杰伦精选\",\"count\":3}}\r\n```\r\n\r\n### 与 music 命令的配合\r\n\r\n`music search` 返回的 `mix_song_id`（或 `mix_song_id`）可直接传给 `control play --mixsongid`，无需任何 ID 转换。\r\n\r\n```\r\nmusic search \"歌手\" → 提取 mix_song_id → control play --mixsongid \r\n → control favorite song --mixsongid \r\n → control playlist create --mixsongids ,\r\n```\r\n\r\n---\r\n\r\n## 前置条件总结\r\n\r\n| 条件 | 说明 |\r\n|------|------|\r\n| CLI 已登录 | `kugou-cli auth login`（扫码登录，存储登录态） |\r\n| 酷狗客户端运行中 | 客户端内置 HTTP server 必须启动（`control start` 会自动触发） |\r\n| 客户端已登录 | 在酷狗客户端 UI 内扫码登录（影响 `favorite`/`playlist create` 等操作） |\r\n| Windows / macOS | Linux 不支持（运行时检查） |\r\n\r\n---\r\n\r\n## 13. Client Detection (`control detect`)\r\n\r\n> **零副作用探测**，**不启动客户端、不抢焦点**——和 `control start` 不同，本命令只读 OS 端的\"URL scheme 注册\"等信号。\r\n\r\n### 用法\r\n\r\n```bash\r\nkugou-cli control detect # 默认 JSON 输出\r\nkugou-cli control detect --json=false # 人类可读一行\r\n```\r\n\r\n### 退出码（Agent 编程消费）\r\n\r\n| 退出码 | 含义 |\r\n|---|---|\r\n| `0` | 客户端已安装（`installed: true`） |\r\n| `1` | 探测过程出错（系统权限等） |\r\n| `2` | 客户端没装（`installed: false`） |\r\n\r\n> Linux/BSD 上 `installed: false` 但 `error: \"\"` —— 不支持是正常情况，不是错误。\r\n\r\n### JSON 输出示例（Windows，有客户端）\r\n\r\n```json\r\n{\r\n \"installed\": true,\r\n \"scheme_registered\": true,\r\n \"scheme\": \"kugou\",\r\n \"exe_path\": \"C:\\\\Program Files\\\\KuGou\\\\KGMusic\\\\KuGou.exe\",\r\n \"version\": \"20.1.40.27866\",\r\n \"handshake_exists\": true,\r\n \"handshake_path\": \"C:\\\\Users\\\\alice\\\\.config\\\\kugou-cli\\\\handshake.json\",\r\n \"platform\": \"windows\",\r\n \"checked_at\": \"2026-08-11T15:25:01+08:00\",\r\n \"strategies\": {\r\n \"scheme_registry\": {\"ok\": true, \"evidence\": \"HKCR\\\\kugou\\\\shell\\\\open\\\\command -> ...\"},\r\n \"install_path_scan\": {\"ok\": true, \"evidence\": \"C:\\\\Program Files\\\\KuGou\\\\KGMusic\\\\KuGou.exe exists\"},\r\n \"handshake_file\": {\"ok\": true, \"evidence\": \"...handshake.json present\"}\r\n }\r\n}\r\n```\r\n\r\n### 与 `control start` 的区别\r\n\r\n| 维度 | `control detect` | `control start` |\r\n|---|---|---|\r\n| 副作用 | **零**（只读 OS 信号） | 会启动客户端 + 抢焦点 |\r\n| 触发客户端启动？ | ❌ | ✅（若握手文件不存在） |\r\n\r\n### 在 AI 工作流里的位置\r\n\r\n详见 [SKILL.md §5](../SKILL.md) —— **首次**要向用户展示歌曲列表/歌单列表前探测一次，记下 `client_available`；后续展示复用本次结果。\r\n\r\n`control detect` **不**替代 `control start` —— 后者仍负责建立 handshake + 启动客户端，是 `control play` 等命令的前置。\r\n\r\n---\r\n\r\n## 相关文档\r\n\r\n- [references/output-format.md](./output-format.md) — 输出格式与展示规范\r\n- [references/music.md](./music.md) — music 命令使用指南\r\n- [references/auth.md](./auth.md) — auth 命令使用指南\r\n\r\n> 客户端协议规范由酷狗客户端内部定义，不在用户可访问的文档范围内。本文档只描述 CLI 端可观察的行为。\n\nFile v0.1.13:references/error-handling.md\n\n# 错误处理\r\n\r\n> **判定优先级**：退出码（非 0 = 失败）→ stdout body 的 `errcode` 字段 → stderr 文案。\r\n> Agent **不应依赖 stderr 文案字面量**判断错误类型——文案可能随版本变化；以退出码和下表为准。\r\n\r\n---\r\n\r\n## 常见错误及处理\r\n\r\n| 错误信息 | 原因 | 处理方式 |\r\n|---------|------|---------|\r\n| `账号登录过期，请重新登录` | 登录态已过期（errcode 语义由上游约定）。CLI 已**自动**清理本地登录态 | 引导用户重新登录：`kugou-cli auth login`（扫码）或 `kugou-cli auth set-secret \"<新 secret>\"` |\r\n| `not logged in` / `auth file not found` | 未登录 | 引导用户执行 `kugou-cli auth login` |\r\n| `HTTP error: 400` | 请求参数有误 | 检查命令参数是否正确 |\r\n| `HTTP error: 500` | 服务端错误 | 稍后重试，或告知用户 |\r\n| `API error: (code=)` | 业务错误（上游 errcode ≠ 0） | 根据 errmsg 提示用户 |\r\n| `network error: ...` | 网络连接问题 | 检查网络，可尝试 `--proxy` |\r\n| `failed to get device info` | 设备信息获取失败（仅 control） | 运行时环境异常，检查权限 |\n\nFile v0.1.13:references/install.md\n\n# 安装命令 (install)\r\n\r\n> 安装 SKILL.md 到各平台 skills 目录\r\n\r\n## 命令列表\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli install` | 显示平台选择提示 |\r\n| `kugou-cli install --all` | 安装 SKILL.md 到所有平台 |\r\n| `kugou-cli install --claude` | 安装到 Claude skills 目录 |\r\n| `kugou-cli install --mavis` | 安装到 Mavis skills 目录 |\r\n| `kugou-cli install --hermes` | 安装到 Hermes skills 目录 |\r\n| `kugou-cli install --openclaw` | 安装到 Openclaw skills 目录 |\r\n| `kugou-cli install --codex` | 安装到 Codex skills 目录 |\r\n| `kugou-cli install --workbuddy` | 安装到 Workbuddy skills 目录 |\r\n\r\n---\r\n\r\n## 详细用法\r\n\r\n```bash\r\nkugou-cli install # 显示平台选择提示\r\nkugou-cli install --all # 安装到所有平台\r\nkugou-cli install --claude # 仅安装到 Claude\r\nkugou-cli install --hermes --claude # 安装到 Hermes 和 Claude\r\n```\r\n\r\n**参数**:\r\n- `--claude`: 安装到 `~/.claude/skills/kugou-skill/`\r\n- `--mavis`: 安装到 `~/.mavis/skills/kugou-skill/`\r\n- `--hermes`: 安装到 `~/.hermes/skills/kugou-skill/`\r\n- `--openclaw`: 安装到 `~/.openclaw/skills/kugou-skill/`\r\n- `--codex`: 安装到 `~/.codex/skills/kugou-skill/`\r\n- `--workbuddy`: 安装到 `~/.workbuddy/skills/kugou-skill/`\r\n- `--all`: 安装到以上所有平台\r\n\r\n---\r\n\r\n## 行为说明\r\n\r\n- 无参数时输出\"平台选择提示\"，列出可用平台选项，不会进行任何安装操作\r\n- 只会在目标平台的 skills 父目录存在时才安装（不自动创建父目录）\r\n- npm 安装时会自动安装 SKILL.md\r\n- `kugou-cli install` 命令用于手动重新安装或更新 SKILL.md\r\n\r\n---\r\n\r\n## 通用命令\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli --version` / `kugou-cli version` | 输出版本号（`--version` 是 root flag，`version` 是子命令，两者输出相同） |\r\n| `kugou-cli --help` | 显示帮助信息 |\r\n| `kugou-cli <子命令> --help` | 显示子命令帮助（如 `kugou-cli music search --help`）|\n\nFile v0.1.13:references/music.md\n\n# 音乐命令 (music)\r\n\r\n> 🔐 = 所有 music 命令都需要先登录\r\n\r\n## 命令列表\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli music search ` | 搜索歌曲 |\r\n| `kugou-cli music recommend guess` | 猜你喜欢（个性化推荐） |\r\n| `kugou-cli music recommend similar -s ` | 相似歌曲推荐 |\r\n| `kugou-cli music favorites` | 我的收藏 |\r\n| `kugou-cli music recent` | 最近播放 |\r\n| `kugou-cli music stats` | 听歌统计 |\r\n| `kugou-cli music charts ` | 榜单 |\r\n| `kugou-cli music create-playlist ` | 创建歌单（可附加歌曲） |\r\n| `kugou-cli music search-playlist ` | 搜索歌单 |\r\n| `kugou-cli music recommend-playlist` | 歌单推荐 |\r\n| `kugou-cli music playlist-songs ` | 歌单内歌曲列表 |\r\n\r\n---\r\n\r\n## 1. 搜索歌曲\r\n\r\n```bash\r\nkugou-cli music search \"周杰伦\"\r\nkugou-cli music search \"周杰伦\" --page 1 --size 20\r\n```\r\n\r\n**参数**:\r\n- ``: 搜索关键词（必填）\r\n- `--page`: 页码，默认 1\r\n- `--size`: 每页数量，默认 20\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"song_name\": \"晴天\",\r\n \"mix_song_id\": \"32100650\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html\"\r\n }\r\n ],\r\n \"total\": 480,\r\n \"page\": 1,\r\n \"size\": 20\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n---\r\n\r\n## 2. 歌曲推荐\r\n\r\n支持三种推荐模式：\r\n\r\n| 类型 | 说明 | 必填参数 |\r\n|------|------|---------|\r\n| `guess` | 猜你喜欢，基于用户喜好推荐 | 无 |\r\n| `similar` | 相似推荐，根据指定歌曲推荐相似歌曲 | `--song` |\r\n| `text` | 文本推歌，根据文本描述推荐歌曲 | `--text` |\r\n\r\n### 2.1 猜你喜欢\r\n\r\n```bash\r\nkugou-cli music recommend guess\r\nkugou-cli music recommend guess --num 10\r\n```\r\n\r\n**参数**:\r\n- `--num`: 推荐数量，默认 10\r\n\r\n### 2.2 相似推荐\r\n\r\n```bash\r\nkugou-cli music recommend similar -s \"晴天\"\r\nkugou-cli music recommend similar --song \"晴天\" -n 5\r\nkugou-cli music recommend similar --song \"晴天\" --text \"风格相似的\" -n 5\r\n```\r\n\r\n**参数**:\r\n- `-s, --song`: 歌曲名称（必填）\r\n- `-n, --num`: 推荐数量，默认 10\r\n- `-t, --text`: 描述文本（可选），用于进一步细化相似方向\r\n\r\n### 2.3 文本推歌\r\n\r\n```bash\r\nkugou-cli music recommend text --text \"适合跑步时听的快节奏歌曲\"\r\nkugou-cli music recommend text --text \"安静的钢琴曲\" --num 5\r\n```\r\n\r\n**参数**:\r\n- `-t, --text`: 文本描述（必填）\r\n- `-n, --num`: 推荐数量，默认 10\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"song_name\": \"稻香\",\r\n \"mix_song_id\": \"8889\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/xxx.html\"\r\n }\r\n ]\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n---\r\n\r\n## 3. 我的收藏\r\n\r\n```bash\r\nkugou-cli music favorites\r\n```\r\n\r\n**参数**: 无（上游接口固定返回最近 10 首收藏，不支持分页）\r\n\r\n> 注意：固定返回最近 10 首收藏，查看更多请前往酷狗App\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"song_name\": \"晴天\",\r\n \"mix_song_id\": \"32100650\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html\"\r\n }\r\n ],\r\n \"total\": 50,\r\n \"msg\": \"当前仅显示最近的10首收藏，查看更多内容，请前往酷狗App\"\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n---\r\n\r\n## 4. 最近播放\r\n\r\n```bash\r\nkugou-cli music recent\r\n```\r\n\r\n**参数**: 无（上游接口固定返回最近 10 条播放记录，不支持分页）\r\n\r\n> 注意：固定返回最近 10 首播放记录，查看更多请前往酷狗App\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"song_name\": \"七里香\",\r\n \"mix_song_id\": \"32100651\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html\"\r\n }\r\n ],\r\n \"total\": 100,\r\n \"msg\": \"当前仅显示最近的10首最近播放，查看更多内容，请前往酷狗App\"\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n---\r\n\r\n## 5. 听歌统计\r\n\r\n```bash\r\nkugou-cli music stats # 默认查当月\r\nkugou-cli music stats --date-type 1 --date 20260501 # 指定周查询\r\n```\r\n\r\n**参数**:\r\n- `--date-type`: 日期类型，0=日、1=周、2=月（默认查当月）\r\n- `--date`: 查询日期，YYYYMMDD 格式，如 \"20260501\"。不传则查当月\r\n - 日类型：每天日期，如 \"20260501\"\r\n - 周类型：必须是周一日期，如 \"20260505\"（周一）\r\n - 月类型：必须是月份第一天，如 \"20260501\"（5月1日）\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"server_time\": 1779977674,\r\n \"listen_duration\": 80776,\r\n \"accumulate_listen_days\": 30,\r\n \"continue_listen_days\": 7,\r\n \"listen_total\": 342,\r\n \"last_listen_total\": 387,\r\n \"top_clocks\": [\r\n \"今日08:00-10:00听歌30分钟\",\r\n \"今日14:00-16:00听歌25分钟\",\r\n \"今日20:00-22:00听歌20分钟\"\r\n ],\r\n \"rank_song\": [\r\n {\r\n \"song_info\": {\"song_name\": \"晴天\", \"mix_song_id\": \"8888\", \"artist_name\": \"周杰伦\", \"play_link\": \"https://www.kugou.com/...\"},\r\n \"count\": 50\r\n }\r\n ],\r\n \"rank_singer\": [\r\n {\"singer_id\": 123, \"name\": \"周杰伦\", \"avatar\": \"https://xxx.jpg\", \"total\": 120}\r\n ],\r\n \"rank_style\": [\r\n {\"style\": \"流行\", \"total\": 200, \"count\": 80}\r\n ],\r\n \"rank_language\": [\r\n {\"language\": \"华语\", \"total\": 400, \"count\": 150}\r\n ]\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段**:\r\n- `listen_duration`: 今日/周/月听歌时长（秒）\r\n- `top_clocks`: 听歌时长最长的 Top3 时段描述（日类型格式如\"今日08:00-10:00听歌30分钟\"，周/月类型格式如\"2026-02月听歌38213分钟\"）\r\n- `accumulate_listen_days`: 累计听歌天数\r\n- `continue_listen_days`: 连续听歌天数\r\n- `listen_total`: 累计听歌次数\r\n- `last_listen_total`: 昨日/上周/上月听歌次数\r\n- `rank_song`: 播放最多的歌曲排行（`count` 为播放次数）\r\n- `rank_singer`: 播放最多的歌手排行\r\n- `rank_style`: 曲风分布统计\r\n- `rank_language`: 语言分布统计\r\n\r\n---\r\n\r\n## 6. 榜单\r\n\r\n```bash\r\nkugou-cli music charts 6666\r\nkugou-cli music charts 52144 --page 1 --size 20\r\n```\r\n\r\n**可用榜单 ID**:\r\n\r\n| rank_id | 榜单名称 |\r\n|---------|----------|\r\n| 8888 | TOP500榜 |\r\n| 90379 | 星耀星光榜 |\r\n| 6666 | 飙升榜 |\r\n| 85432 | 百万收藏榜 |\r\n| 74534 | 新歌榜 |\r\n| 52144 | 抖音热歌酷狗榜 |\r\n\r\n**参数**:\r\n- ``: 搜索关键词（必填）\r\n- `--page`: 页码，默认 1（**无简写**）\r\n- `--size`: 每页数量，默认 20（**无简写**）\r\n\r\n---\r\n\r\n## 7. 创建歌单\r\n\r\n> 🔐 = 需要先登录（CLI 登录 `auth login` / `auth set-secret`）\r\n\r\n### 7.0 调用原则（AI 必读）\r\n\r\n1. **被动调用**：必须用户**明确**要求创建歌单时才调用，禁止在用户仅说\"推荐/搜歌/听歌\"时主动创建\r\n2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户\"是否需要将当前这批歌曲创建为歌单\"，等用户确认后再调用\r\n3. **示例化推荐**：询问时建议给出歌单名建议（如\"跑步歌单\"、\"周杰伦精选\"），让用户更容易确认\r\n4. **硬性默认：优先客户端创建**：用户一旦同意创建歌单，**必须先尝试** [`control playlist create`](./control.md#10-playlist-create--创建歌单)（在本地酷狗客户端内创建）。当以下**任一**条件成立时，回退到本节的 `music create-playlist`（云端创建）：\r\n - **(a)** 当前系统不是 Windows / macOS（control 不支持 Linux）\r\n - **(b)** 本地酷狗客户端未运行，或未通过 `kugou-cli control start` 完成握手（前置条件详见 [control.md §10](./control.md#10-playlist-create--创建歌单)）\r\n - **(c)** `control playlist create` 调用失败（如 409/4091\"login required\"、网络错误等）—— 此时把 stderr 原样回给用户，并询问是否改走云端\r\n\r\n 简单说：**默认 `control`；客户端不可用或失败时，才退到 `music`**。不要在用户没问的情况下主动解释为什么走云端，先尝试 client 路径即可。\r\n\r\n5. **创建成功后主动询问是否播放**：无论走 `control playlist create` 还是 `music create-playlist`，**只要创建成功（返回 0/成功状态）就必须主动询问用户\"是否要播放这个歌单\"**，等用户明确回复后再决定走哪条播放命令：\r\n - 用户同意 → 按场景选播放路径：\r\n - **客户端路径优先**：`kugou-cli control play-playlist --global-id \"\"`（详见 [control.md §12](./control.md#12-play-playlist--播放整个歌单)），可叠加 `--playlist-mode` 控制是否打断当前播放\r\n - **云端歌单（`music create-playlist` 创建的）**：走浏览器 H5 路径（详见下方 7.2）——**不要**再用 `control play-playlist`，因为本地客户端没有这首歌单\r\n - 用户拒绝 / 不回复 → 不做任何动作，不要替用户决定\r\n - 仅在\"创建歌单成功\"时才询问；建失败时不询问（直接展示错误，等用户决定下一步）\r\n\r\n### 7.1 接口说明（云端备选，仅在 7.0 第 4 条任一条件成立时使用）\r\n\r\n> ⚠️ 本节是**云端备选路径**。优先走 [`control playlist create`](./control.md#10-playlist-create--创建歌单)（详见 [7.0 第 4 条](#70-调用原则ai-必读)）。仅当客户端不可用时使用本节。\r\n\r\n创建一个新的自创建歌单，并可选择在创建后往歌单里添加歌曲。\r\n\r\n```bash\r\n# 创建空歌单\r\nkugou-cli music create-playlist \"我的空歌单\"\r\n\r\n# 创建歌单并添加歌曲\r\nkugou-cli music create-playlist \"我的批量歌单\" --songs \"123,456,789\"\r\n```\r\n\r\n**参数**:\r\n- ``: 歌单名称（必填）\r\n- `--songs`: 待添加的歌曲 mix_song_id 列表，逗号分隔（可选）。不传则只创建空歌单\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"errmsg\": \"\",\r\n \"data\": {\r\n \"name\": \"我的批量歌单\",\r\n \"song_list_url\": \"https://m.kugou.com/songlist/gcid_abc123def45\"\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段**:\r\n- `name`: 歌单名称\r\n- `song_list_url`: 歌单播放地址（H5 链接），可分享给用户打开\r\n\r\n**异常说明**:\r\n- 歌单创建成功但添加歌曲失败：返回 200 状态 + 错误信息，body 仍包含已创建歌单的 `name` 与 `song_list_url`\r\n- 歌单创建失败：返回对应错误码（参数错误 20010 / 网络错误 90000 等）\r\n\r\n### 7.2 云端歌单的播放：控制浏览器打开 H5 链接\r\n\r\n> 适用场景：用户同意播放的歌单是 `music create-playlist` 创建的（响应里有 `song_list_url`），且本地没有可用的酷狗客户端（7.0 第 4 条 (a)(b)(c) 任一成立）。\r\n\r\n**Agent 必须遵循\"先探后告知\"原则**：\r\n\r\n1. **先探测浏览器控制能力**：当前 Agent 工具栈是否能控制本地浏览器（playwright / dev-browser / chrome-devtools MCP 等任一可用）。可用 = 可用；都不可用 = 当前环境不支持浏览器控制\r\n2. **可用时**：\r\n - 用浏览器工具打开响应里的 `song_list_url`（H5 链接，格式如 `https://m.kugou.com/songlist/gcid_...`）\r\n - 等待 H5 页面加载完成（`networkidle` / 出现\"播放全部\"按钮）\r\n - **轻量职责**：点击页面上的\"播放\" / \"播放全部\"按钮（若有），控制到\"页面已渲染出播放控制\"为止\r\n - 页面登录、付费、版权屏蔽等后续问题**不归 Agent 管**，告诉用户\"已打开 H5 歌单并尝试点击播放，如未自动播放请手动点一下\"\r\n3. **不可用时**（无浏览器控制工具 / 浏览器控制调用失败）：\r\n - 明确告知用户：\"当前环境无法控制浏览器，请手动复制链接在浏览器打开：[song_list_url]\"\r\n - **不要**伪装已经打开或点击了播放\r\n\r\n> **为什么不写死\"先 playwright 再 chrome-devtools\"？** 不同 Agent 工具栈内置的浏览器工具名不同，文档只规定行为契约（\"打开 + 点击播放\"），具体工具由 Agent 现场选择。\r\n\r\n---\r\n\r\n## 8. 搜索歌单\r\n\r\n根据关键词搜索歌单。\r\n\r\n```bash\r\nkugou-cli music search-playlist \"周杰伦\"\r\nkugou-cli music search-playlist \"周杰伦\" --page 1 --size 20\r\nkugou-cli music search-playlist \"跑步\" --filter 1 # 只搜 UGC\r\nkugou-cli music search-playlist \"钢琴\" --filter 2 # 只搜非 UGC\r\n```\r\n\r\n**参数**:\r\n- ``: 搜索关键词（必填）\r\n- `--page`: 页码，默认 1\r\n- `--size`: 每页数量，默认 20\r\n- `--filter`: 过滤方式，`0=全部（默认） / 1=只搜 UGC / 2=只搜非 UGC`\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"list_id\": 2651286,\r\n \"global_id\": \"collection_3_938985631_304_0\",\r\n \"name\": \"周杰伦：无与伦比，为杰沉沦。\",\r\n \"creator_id\": \"938985631\",\r\n \"creator_name\": \"慕情超爱撒花\",\r\n \"intro\": \"\",\r\n \"song_list_url\": \"https://m.kugou.com/songlist/gcid_3z938985631z304z2\"\r\n }\r\n ],\r\n \"total\": 1000,\r\n \"page\": 1,\r\n \"size\": 20\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段**:\r\n- `list_id`: 歌单 ID（数字 string）\r\n- `global_id`: 全局歌单 ID（字符串，跨客户端兼容的稳定标识）\r\n- `name`: 歌单名\r\n- `creator_id`: 创建人用户 ID（字符串）\r\n- `creator_name`: 创建人昵称\r\n- `intro`: 歌单简介\r\n- `song_list_url`: 歌单链接（H5），格式 `https://m.kugou.com/songlist/gcid_{encoded(global_id)}`；`global_id` 为空时返回空字符串\r\n\r\n> **提示**: 歌单搜索/推荐只返回基础信息用于卡片展示。需要歌曲数、播放量、收藏数、封面图、歌单内歌曲等详细信息时，调用方拿到 `global_id` 后调用 [第 10 章](#10-歌单内歌曲列表) 或直接打开 `song_list_url`。\r\n\r\n**特殊说明**:\r\n- 上游高亮：服务端固定传 `tag=em`，返回的 `name` 字段带 `...` 高亮标签，前端可直接渲染\r\n- 上游错误码：146/147=被屏蔽地区，148=非法关键字，149=页码超出范围。出现时返回 90000 网络错误，建议引导用户重试或更换关键词\r\n\r\n---\r\n\r\n## 9. 歌单推荐\r\n\r\n根据用户喜好个性化推荐歌单。\r\n\r\n```bash\r\nkugou-cli music recommend-playlist\r\nkugou-cli music recommend-playlist --page 1 --size 20\r\nkugou-cli music recommend-playlist --module-id 6 # 我-最近播放-歌单下方\r\n```\r\n\r\n**参数**:\r\n- `--page`: 页码，默认 1\r\n- `--size`: 每页数量，默认 20\r\n- `--module-id`: 上游模块 ID，由客户端透传。常见值：\r\n - `1` = 歌单广场（默认）\r\n - `5` = 酷狗 X 首页为你推荐\r\n - `6` = 我 - 最近播放 - 歌单下方\r\n - `15` = 酷狗 12 听首页为你推荐\r\n\r\n 不传时服务端默认填 `1`。\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"list_id\": 2651286,\r\n \"global_id\": \"collection_3_938985631_304_0\",\r\n \"name\": \"周杰伦：无与伦比，为杰沉沦。\",\r\n \"creator_id\": \"938985631\",\r\n \"creator_name\": \"慕情超爱撒花\",\r\n \"intro\": \"\",\r\n \"song_list_url\": \"https://m.kugou.com/songlist/gcid_3z938985631z304z2\"\r\n }\r\n ],\r\n \"total\": 100,\r\n \"has_next\": 1,\r\n \"session\": \"1706428800\",\r\n \"refresh_time\": 0,\r\n \"page\": 1,\r\n \"size\": 20\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段（顶层）**:\r\n- `total`: 总数；`has_next`: 是否有下一页（1=是 / 0=否）\r\n- `session`: 会话标识（暂时返回时间戳）\r\n- `refresh_time`: 客户端刷新时间（秒），`0` 或缺失表示不刷新\r\n\r\n**关键字段（list[]）**:\r\n- 与歌单搜索（[第 8 章](#8-搜索歌单)）共用同一套 `PlaylistInfo` 基础字段（`list_id` / `global_id` / `name` / `creator_id` / `creator_name` / `intro` / `song_list_url`），调用方可使用同一套反序列化逻辑\r\n- 已登录时上游根据 userid 做个性化推荐；未登录时可能返回空数据或通用推荐\r\n- 上游可能附带 `cache` 等额外字段，**未在 `PlaylistInfo` 中列出的字段请勿依赖**\r\n\r\n---\r\n\r\n## 10. 歌单内歌曲列表\r\n\r\n通过歌单全局 ID（`global_collection_id`）获取歌单内歌曲列表。一般先调用 [第 8 章](#8-搜索歌单) 或 [第 9 章](#9-歌单推荐) 拿到 `global_id`，再透传给本接口。\r\n\r\n```bash\r\nkugou-cli music playlist-songs \"collection_3_938985631_304_0\"\r\nkugou-cli music playlist-songs \"collection_3_938985631_304_0\" --page 1 --size 100\r\n```\r\n\r\n**参数**:\r\n- ``: 歌单全局 ID（必填，从 `search-playlist` / `recommend-playlist` 响应的 `global_id` 字段透传）\r\n- `--page`: 页码，从 1 开始，默认 1\r\n- `--size`: 每页数量，默认 100（上游建议值）\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"data\": {\r\n \"list\": [\r\n {\r\n \"song_name\": \"晴天\",\r\n \"mix_song_id\": \"8888\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html\"\r\n },\r\n {\r\n \"song_name\": \"七里香\",\r\n \"mix_song_id\": \"8890\",\r\n \"artist_name\": \"周杰伦\",\r\n \"play_link\": \"https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html\"\r\n }\r\n ],\r\n \"total\": 164,\r\n \"page\": 1,\r\n \"size\": 100\r\n },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**关键字段**:\r\n- `list[]`: 通用 `SongInfo` 结构（`song_name` / `mix_song_id` / `artist_name` / `play_link`）\r\n- `total`: 上游返回的歌曲总数（不含被过滤的屏蔽歌曲）\r\n\r\n> **关于上游附带字段**：CLI 透传上游原始 JSON 字符串，响应里**可能**含其他字段（如 `hash`、`singer_id` 等），但 CLI 不解析、不保证存在。Agent 不要依赖未在 `SongInfo` 中列出的字段。\r\n\r\n**特殊说明**:\r\n- **屏蔽歌曲过滤**: 上游可能跳过被屏蔽的歌曲（不返回），`total` 不含被过滤项，`list` 长度可能小于 `size`\r\n- **artist_name 拼接**: 多歌手时上游用 `/` 拼接（例如 `周杰伦/方文山`）\r\n- **分页去重**: 上游按服务端数组下标分页，但歌曲可能在分页期间被增删，调用方需自行按 `mix_song_id` 去重\r\n- **播放链接**: `play_link` 由服务端拿到 `mix_song_id` 后批量生成，单条失败不影响其他歌曲\n\nFile v0.1.13:references/output-format.md\n\n# 输出格式与展示规范\r\n\r\n## 通用响应结构\r\n\r\n`music` / `auth` / `install` 等\"上游 API 类\"命令输出标准 JSON 结构：\r\n\r\n```json\r\n{\r\n \"errcode\": 0,\r\n \"errmsg\": \"\",\r\n \"data\": { ... },\r\n \"status\": 1\r\n}\r\n```\r\n\r\n**响应状态判定**:\r\n- **成功判定只看 `errcode == 0`**——这是 Agent 唯一可信的成功依据\r\n- `data` 包含实际业务数据\r\n- `status: 1` 是上游接口调用状态提示，**仅作辅助参考**（部分上游错误响应里 `status` 可能不是 1，但仍由 `errcode` 决定 CLI 成功与否）\r\n- **`control` 命令不走这个结构**——它透传酷狗客户端本地 HTTP 协议的原始 JSON，成功字段通常是 `code` 而不是 `errcode`。见 [references/control.md](./control.md)\r\n\r\n---\r\n\r\n## 展示规范\r\n\r\n向用户展示结果时，**必须遵循以下规范**：\r\n\r\n### 1. 歌曲/歌单列表展示（批量优先用表格）\r\n\r\n> **强制规则**：结果 ≥ 2 条 → 表格；结果 = 1 条 → 单行链接（按客户端可用性决定是否加链接）。\r\n\r\n#### 1.1 客户端可用性探测（前置条件）\r\n\r\n**首次**要向用户展示歌曲列表、歌单列表或歌单内歌曲列表之前，**必须**先探测本机是否有可用的酷狗客户端（详见 [SKILL.md#5-首次要展示歌曲歌单前探测本机客户端可用性](../SKILL.md)）：\r\n\r\n```bash\r\nkugou-cli control detect\r\n```\r\n\r\n根据退出码记下 `client_available`：\r\n\r\n| 退出码 | 含义 | `client_available` |\r\n|---|---|---|\r\n| `0` | 已安装 | `true` |\r\n| `1` | 探测出错（注册表权限等） | `false`（按没客户端处理） |\r\n| `2` | 没装客户端 | `false` |\r\n\r\n**会话内只探测一次**，后续展示复用本次结果。`control detect` 是零副作用探测，不会启动客户端、不会抢焦点。\r\n\r\n#### 1.2 规则总览\r\n\r\n| 结果条数 | 展示形式 | 客户端可用？ | 歌曲名/歌单名是否加链接 |\r\n|---|---|---|---|\r\n| **≥ 2** | Markdown 表格（**必须**） | 无关 | **一律不加**（保持列宽整洁） |\r\n| **= 1** | 单行 Markdown 链接 | 是 | **不加**（可直接走 `control play`） |\r\n| **= 1** | 单行 Markdown 链接 | 否 | **必须加**（用户手动打开） |\r\n| **= 0** | 自然语言提示 | 无关 | 不适用 |\r\n\r\n#### 1.3 表格格式（结果 ≥ 2 条）\r\n\r\n**歌曲列表**（来自 `search` / `recommend guess|similar|text` / `charts` / `favorites` / `recent` / `playlist-songs`）：\r\n\r\n```markdown\r\n| 序号 | 歌曲名 | 歌手 |\r\n|------|--------|------|\r\n| 1 | 晴天 | 周杰伦 |\r\n| 2 | 七里香 | 周杰伦 |\r\n| 3 | 稻香 | 周杰伦 |\r\n```\r\n\r\n**歌单列表**（来自 `search-playlist` / `recommend-playlist`）：\r\n\r\n```markdown\r\n| 序号 | 歌单名 | 创建人昵称 |\r\n|------|--------|------------|\r\n| 1 | 周杰伦经典30首 | 酷狗小编 |\r\n| 2 | 慢摇车载DJ | DJ阿圣 |\r\n```\r\n\r\n**硬性规则**：\r\n\r\n- 表格单元格里的歌曲名/歌单名**不加** Markdown 链接——加了会让列宽自适应 URL，可读性反而变差\r\n- 表格里也不列 `play_link` / `song_list_url` / `mix_song_id` / `global_id`——这些字段是给后续 `control *` 命令用的，由 agent 内部持有，**不展示给用户**\r\n- 序号从 1 开始连续递增\r\n- 如果返回总条数 > 表格展示条数（例如 `search` 默认 20 条），**只展示实际返回的那部分**，不要截断也不要用省略号\r\n\r\n#### 1.4 单条结果格式（结果 = 1 条）\r\n\r\n**有客户端时**（`client_available = true`）—— 歌曲名/歌单名**不加链接**：\r\n\r\n```markdown\r\n晴天 - 周杰伦\r\n```\r\n\r\n```markdown\r\n周杰伦经典30首 —— 酷狗小编\r\n```\r\n\r\n**无客户端时**（`client_available = false`）—— 歌曲名/歌单名**必须加链接**：\r\n\r\n```markdown\r\n[晴天 - 周杰伦](https://www.kugou.com/mixsong/xxxx.html)\r\n```\r\n\r\n```markdown\r\n[周杰伦经典30首](https://www.kugou.com/songlist/xxxx.html)\r\n```\r\n\r\n#### 1.5 为什么表格不加链接？\r\n\r\n- 表格的目标是**浏览/筛选**，不是立即跳转；用户在表格里通常要做的是\"挑一首播放\"或\"挑一个歌单打开\"，而非\"挨个点开\"\r\n- 加链接会让列宽按 URL 自适应，中文长字符串场景下整张表可读性急剧下降\r\n- ID（`mix_song_id` / `global_id`）由 agent 内部持有，等用户明确说\"播放第 3 首\" / \"打开第 2 个歌单\"时再走 `control play` / `control play-playlist` 或浏览器跳转\r\n\r\n#### 1.6 反例（禁止）\r\n\r\n| 禁止 | 错误原因 |\r\n|---|---|\r\n| 表格里写 `[晴天](https://...)` 形式的可点击单元格 | 列宽爆炸、可读性差 |\r\n| 表格里把 `play_link` / `global_id` 也单列出来 | ID 是 agent 内部数据，不该展示给用户 |\r\n| 结果 ≥ 2 条却用列表式 `[歌名 - 歌手](link)` 堆叠 | 表格才是 ≥ 2 条的标准形式 |\r\n| 单条结果（= 1）时仍用表格 | 杀鸡用牛刀，单行更直接 |\r\n| 单条无客户端时不加链接 | 用户没有客户端可控制，必须给链接让用户手动打开 |\r\n| 单条有客户端时仍加链接 | 既然有客户端可以直接 `control play`，加链接反而多余 |\r\n| 不探测就硬性决定加不加链接 | 必须先 `control detect`，不能凭猜测 |\r\n\r\n#### 1.7 control 操作响应不受本节约束\r\n\r\n`control play` / `control favorite song` 等**操作响应**不包含 `play_link`，按 control 协议原始 JSON 字段原样展示即可（见 [references/control.md](./control.md)）。本节规范只适用于 `music *` 命令返回的列表类结果。\r\n\r\n### 2. 统计数据\r\n\r\n提取关键字段并以结构化方式呈现（如\"累计听歌 342 首，时长 22.4 小时\"）\r\n\r\n### 3. 二维码\r\n\r\n使用 `qrcode_img_url` 渲染给用户：Markdown `![酷狗登录二维码]()`，让客户端拉取并渲染\r\n\r\n### 4. 错误展示\r\n\r\n- CLI 错误输出到 **stderr**，stdout 只放原始 JSON（或原始 body）\r\n- Agent 解析失败时同时检查：退出码（0 = 成功，非 0 = 失败）、stdout body 的 `errcode` 字段、stderr 输出\r\n- 不要把 stderr 输出原样展示给用户；转化为自然语言说明（如\"账号登录过期，请重新登录\"）\r\n\r\n---\r\n\r\n### 5. 推荐理由（主动推荐场景必写）\r\n\r\n**触发条件**：仅当 agent **主动**给用户推荐歌曲时才写推荐理由，包括以下命令的返回结果：\r\n\r\n- `kugou-cli music recommend guess`（猜你喜欢）\r\n- `kugou-cli music recommend similar -s `（相似推荐）\r\n- `kugou-cli music recommend text --text <描述>`（文本推歌）\r\n- `kugou-cli music charts `（榜单，详见 [music.md#7](music.md#7)）\r\n- `kugou-cli music recommend-playlist`（歌单推荐）—— 歌单本身就是主动推荐行为\r\n\r\n**不触发**：用户**主动搜索**（`search` / `search-playlist`）、查自己数据（`favorites` / `recent` / `stats`）、查指定歌单内容（`playlist-songs`）的结果**不写**推荐理由——用户来找东西，不需要再被解释一遍。\r\n\r\n#### 写法要求\r\n\r\n在歌曲列表**之后**追加一段 Markdown 引用块（`>`）作为推荐理由，必须包含以下三层信息：\r\n\r\n1. **整体歌曲风格**：用一句话概括本批推荐的整体风格/情绪基调（例如「以华语流行慢歌为主，情绪偏舒缓治愈」）。\r\n2. **匹配逻辑**：依据当前推荐场景说明匹配来源——\r\n - 猜你喜欢 / 歌单推荐 → 「基于你的听歌偏好/历史播放」\r\n - 相似推荐 → 「延续《XXX》的 XXX 风格/主题」\r\n - 文本推歌 → 「贴合你描述的『XXX』场景」\r\n - 榜单 → 「来自 XXX 榜第 N 名，XXX 类热度风向」\r\n3. **挑 2-3 首解读**：从本批返回中挑选 2-3 首，**结合行业认知**（歌手常见风格、歌曲广为人知的标签、所属专辑/年代等）做一句解读，帮助用户判断是否合口味。\r\n\r\n> ⚠️ 解读内容**仅基于歌名 + 歌手名调用 agent 自身行业认知**，不要捏造歌词、不要引用未经验证的曲风标签。如对歌曲不熟悉，宁可写得笼统一些也不要硬编细节。\r\n\r\n#### 字数硬约束\r\n\r\n**总字数控制在 220-260 字（含标点）**。超出或不足都需要重写到区间内。撰写时不必分段，整体作为一段引用块即可。\r\n\r\n#### 输出示例\r\n\r\n```markdown\r\n> 为你挑选了 5 首华语流行慢歌，整体偏舒缓、情绪内敛，节奏不快不躁，编曲以钢琴和原声吉他为主，更适合午后或深夜一个人安静循环。匹配逻辑来自你最近的播放记录和猜你喜欢数据，我们从中挑出与历史偏好契合度最高的几首组成了这张清单。其中《晴天》是周杰伦 2003 年的代表作，校园民谣的底色配钢琴铺陈，几乎成了一代人的青春共同记忆；《七里香》延续了同期的中国风与诗意意象，副歌弦乐层层推进，听感最为饱满宏大；《稻香》则把视角拉回乡村童年，节奏轻快但内核温暖，是整张清单里最治愈的一首作品。\r\n```\r\n\r\n---\n\nFile v0.1.13:references/update.md\n\n# 更新命令 (update)\r\n\r\n> 自动检查并更新 kugou-cli\r\n\r\n## 命令\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli update --check` | 仅检查更新，不执行 |\r\n| `kugou-cli update` | 检查并提示（不自动执行） |\r\n| `kugou-cli update --force` | 直接执行更新（仅 npm 安装） |\r\n\r\n---\r\n\r\n## 启动时自动检查\r\n\r\n### 1. 检查行为\r\n\r\n每次执行任意 `kugou-cli` 命令时，**后台异步**检查 npm registry 上的最新版本。\r\n\r\n- **不阻塞** 主命令\r\n- 有更新时输出到 **stderr**（避免污染 stdout JSON 输出）\r\n- 提示格式：\r\n ```\r\n [kugou-cli] update available: 0.0.22 → 0.0.23 (run `kugou-cli update` to upgrade)\r\n ```\r\n\r\n### 2. 检查频率限制\r\n\r\n- 缓存有效期：**24 小时**\r\n- 24 小时内不会重复访问 npm registry\r\n\r\n### 3. 跳过检查\r\n\r\n在以下情况跳过启动检查：\r\n- `CI=true` 环境变量\r\n- `KUGOU_CLI_NO_UPDATE_CHECK=1` 环境变量\r\n- 命令行指定 `--no-update-check` flag\r\n\r\n---\r\n\r\n## 显式检查更新\r\n\r\n```bash\r\nkugou-cli update --check\r\n```\r\n\r\n> **绕过 24h 缓存**：显式调用 `kugou-cli update [--check]` **总是**绕过本地 24h 缓存，强制访问 npm registry。这与\"启动时被动检查\"的语义不同——启动检查走缓存（24h 内不重复访问 npm），显式 `update` 命令不走缓存。\r\n\r\n**输出示例**：\r\n\r\n有更新时：\r\n```json\r\n{\r\n \"current_version\": \"0.0.22\",\r\n \"latest_version\": \"0.0.23\",\r\n \"update_available\": true,\r\n \"install_method\": \"npm\",\r\n \"update_command\": \"npm install -g @kg-ai/kugou-skill@latest\"\r\n}\r\n```\r\n\r\n无更新时：\r\n```json\r\n{\r\n \"current_version\": \"0.0.22\",\r\n \"latest_version\": \"0.0.22\",\r\n \"update_available\": false,\r\n \"install_method\": \"npm\"\r\n}\r\n```\r\n\r\n---\r\n\r\n## 执行更新\r\n\r\n### 方式 1：Agent / 脚本（推荐）\r\n\r\n```bash\r\n# 步骤 1: 检查\r\ninfo=$(kugou-cli update --check)\r\nupdate_available=$(echo \"$info\" | jq -r '.update_available')\r\n\r\n# 步骤 2: 如果有更新，提示用户确认后执行\r\nif [ \"$update_available\" = \"true\" ]; then\r\n echo \"有可用更新，正在升级...\"\r\n kugou-cli update --force\r\nfi\r\n```\r\n\r\n### 方式 2：手动\r\n\r\n```bash\r\n# 提示但不执行\r\nkugou-cli update\r\n# 显示: About to run: npm install -g @kg-ai/kugou-skill@latest\r\n\r\n# 强制执行\r\nkugou-cli update --force\r\n```\r\n\r\n### 方式 3：标准 npm 命令\r\n\r\n无需 `update` 子命令，直接：\r\n```bash\r\nnpm install -g @kg-ai/kugou-skill@latest\r\n```\r\n\r\n---\r\n\r\n## 安装方式检测\r\n\r\nCLI 自动检测安装方式：\r\n\r\n| 安装方式 | 检测方法 | 是否支持自动更新 |\r\n|---------|---------|------------------|\r\n| **npm** | 二进制路径包含 `node_modules/@kg-ai/kugou-skill` | ✅ 支持 |\r\n| **其他**（源码编译 / 手动下载） | 其他路径 | ❌ 仅提示 |\r\n\r\n非 npm 安装时，CLI 只会提示，不会自动更新。请使用对应方式更新。\r\n\r\n---\r\n\r\n## 注意事项\r\n\r\n1. **网络要求**：检查更新需要访问 `https://registry.npmjs.org`，在受限网络下可能失败\r\n2. **离线友好**：网络失败时静默忽略，不影响主命令\r\n3. **CI 友好**：CI 环境默认跳过检查，避免污染日志\r\n4. **不强制**：默认仅提示，更新需用户/Agent 显式确认\n\nFile v0.1.13:skill-card.md\n\n## Description:\n\nKugou helps agents use kugou-cli to search Kugou Music, get recommendations, view favorites and listening stats, create playlists, and control the local Kugou desktop client.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[shamo88](https://clawhub.ai/user/shamo88)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to let an agent perform Kugou Music searches, recommendations, playlist operations, account-aware library queries, and optional desktop-client playback control through documented shell commands.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill asks agents to handle reusable Kugou account session secrets.\n\nMitigation: Prefer QR login, avoid pasting base64 secrets into chat or shell history unless necessary, and confirm login state before running account-backed music commands.\n\nRisk: The npm installation flow can modify multiple agent skill folders during postinstall or install commands.\n\nMitigation: Review the package and installation target before installing, and run installation in a controlled environment when agent skill directories are sensitive.\n\nRisk: Automatic update checks can contact the npm registry from environments where outbound package-registry access is sensitive.\n\nMitigation: Review or disable automatic update checks using the documented environment variable or command flag in restricted networks.\n\nRisk: Desktop control operations depend on a logged-in Kugou client and are unsupported outside Windows and macOS.\n\nMitigation: Detect client availability before presenting playback links and fall back to query-only or cloud playlist workflows when local control is unavailable.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/shamo88/skills/kugou-skill)\n- [Authentication Commands](references/auth.md)\n- [Music Commands](references/music.md)\n- [Desktop Client Control](references/control.md)\n- [Installation Commands](references/install.md)\n- [Update Behavior](references/update.md)\n- [Output Format](references/output-format.md)\n- [Error Handling](references/error-handling.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and JSON-aware response summaries]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include song or playlist tables, QR-code presentation guidance, and follow-up prompts for login or playback confirmation.]\n\n## Skill Version(s):\n\n0.1.13 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.1.8: 10 files, 33428 bytes\n\nFiles: references/auth.md (11769b), references/control.md (23760b), references/error-handling.md (1056b), references/install.md (2049b), references/music.md (18106b), references/output-format.md (4847b), references/update.md (3229b), skill-card.md (2667b), SKILL.md (13746b), _meta.json (130b)\n\nFile v0.1.8:SKILL.md\n\n---\nname: kugou-skill\ndescription: |\n 酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手\n 提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单等功能。\n\n **触发场景**（满足任一即使用本技能）：\n - 用户要求推荐歌曲、听歌建议\n - 用户要求搜索歌曲、查找歌手作品\n - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）\n - 用户要求查看收藏、最近播放、听歌统计\n - 用户要求创建歌单、自建歌单\n - 用户提供 base64 secret 字符串要求登录或导入身份\n - Agent 在尝试扫码登录时遇到环境限制（无法发图片）→ 主动询问用户是否可提供 secret\n - 用户提到\"酷狗\"、\"kugou\"、\"猜你喜欢\"、\"相似歌曲\"\n - 用户要求让 PC/Mac 客户端播放歌曲、暂停、切歌、收藏、创建歌单\n - 用户提到酷狗 URL scheme（\"kugou://\" 或 \"mackugou://\"）\n - 用户提到\"本机控制\"、\"控制酷狗客户端\"\n\n **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。\n\n 安装方式：npm install -g @kg-ai/kugou-skill\n---\n\n# kugou-skill\n\n## AI 使用工作流（优先阅读）\n\n使用本工具时的标准流程：\n\n```\n1. 检查安装 → npm install -g @kg-ai/kugou-skill\n2. 检查登录态 → kugou-cli auth status\n3. 登录决策（按以下优先级严格判断，不要跳步）：\n ├─ 状态 a：已登录（logged_in: true）→ 跳到第 5 步\n ├─ 状态 b：未登录 + 用户**明确**说\"我有 secret\" → 调 `kugou-cli auth set-secret \"\"` 一次完成 → 跳到第 5 步\n ├─ 状态 c：未登录 + 当前环境**无法**渲染远程 URL 图片 **且** 无法读取本地二维码文件 → **强制**走 set-secret（同上）\n └─ 状态 d：未登录 + 其他所有情况 → 走扫码流程（第 4 步）\n\n 注意：状态 b/c/d 互斥；不要在用户未明确给 secret 时擅自走 set-secret。\n4. 引导登录——扫码（详见 references/auth.md）：\n - 执行 `auth login`，从输出读 `qrcode_img_url` 和 `qrcode_img_path`，按当前客户端能力选一种方式把二维码**直接展示给用户**\n - **阶段 A（主动轮询）**：图片刚展示，**主动**重试几次 `auth status`（每次隔几秒），覆盖用户秒扫场景\n - 任意一次返回 `logged_in: true` → 跳到第 5 步\n - 几次都返回 `waiting` 且未出现 `scanned` → 进入阶段 B\n - **阶段 B（等用户回复）**：停下，告诉用户\"请用酷狗 APP 扫码登录，扫完后告诉我已扫码\"，**不再调 status**，等用户**主动回复\"已扫码\"**\n - **阶段 C（验证一次）**：用户回复\"已扫码\"后，**调一次** `auth status`：\n - `logged_in: true` → 完成，跳到第 5 步\n - `scanned`（已扫但未确认）→ 等几秒再调一次，最多**额外**调几次，仍是 scanned 就告诉用户\"手机端是否已点确认？\"\n - `failed` 或 `{\"logged_in\": false}` → 重新 `auth login` 拿新图，从阶段 A 重新开始\n5. 按请求类型分流：\n - **请求类型 A：控制已有歌 / 歌单 / 收藏**（用户已有 mixsongid 或 global_id）→ 直接执行 `control` 命令（详见 [references/control.md](references/control.md)），不需要先调 `music` 拿 ID\n - 例：`control play`、`control player --action pause`、`control favorite song --mixsongid `、`control play-playlist --global-id `\n - **请求类型 B：搜索后做某件事**（搜索歌曲/推荐/榜单 → 拿到 ID 后再做后续动作，如播放、收藏、建歌单）→ 先执行 `music` 命令拿数据，再按需转 `control`，详见 [references/music.md](references/music.md)\n - 例：先 `music search` 拿 mixsongid，再 `control play` 播放\n - 例：先 `music search-playlist` 拿 global_id，再 `control pla\n\nArchive v0.1.7: 9 files, 18292 bytes\n\nFiles: references/auth.md (11823b), references/error-handling.md (962b), references/install.md (1917b), references/music.md (8442b), references/output-format.md (1019b), references/update.md (3008b), skill-card.md (2566b), SKILL.md (10403b), _meta.json (130b)\n\nArchive v0.1.6: 9 files, 17738 bytes\n\nFiles: references/auth.md (10512b), references/error-handling.md (962b), references/install.md (1917b), references/music.md (8442b), references/output-format.md (1023b), references/update.md (3008b), skill-card.md (2507b), SKILL.md (10028b), _meta.json (130b)\n\nArchive v0.1.4: 9 files, 14026 bytes\n\nFiles: references/auth.md (4996b), references/error-handling.md (962b), references/install.md (1917b), references/music.md (8442b), references/output-format.md (955b), references/update.md (3008b), skill-card.md (2704b), SKILL.md (5968b), _meta.json (130b)\n\nArchive v0.1.2: 9 files, 13122 bytes\n\nFiles: references/auth.md (3688b), references/error-handling.md (766b), references/install.md (1863b), references/music.md (8119b), references/output-format.md (913b), references/update.md (2880b), skill-card.md (2588b), SKILL.md (5472b), _meta.json (130b)","readmeExcerpt":"Skill: 酷狗 Owner: shamo88 Summary: 酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手 提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单、调整音乐偏好等功能。 **触发场景**（满足任一即使用本技能）： - 用户要求推荐歌曲、听歌建议 - 用户要求搜索歌曲、查找歌手作品 - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等） - 用户要求查看收藏、最近播放、听歌统计 - 用户要求创建歌单、自建歌单 - 用户要求调整音乐偏好（\"少推点 XX 歌手\"、\"多推点 XX 语种\"、\"别再推 XX 曲风\" 等） - 用户提供 base64 secret 字符串要求登录或导入身份 - Agent Tags: latest:0.1.20 Version history: v0.1.20 | 2026-09-14T03:04:35.881Z | user kugou-sk","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"File v0.1.20:_meta.json\n\n{\n \"ownerId\": \"kn7crmv8zas1ep290wm2ag0wtn88te0q\",\n \"slug\": \"kugou-skill\",\n \"version\": \"0.1.20\",\n \"publishedAt\": 1789355075881\n}\n\nFile v0.1.20:references/auth.md\n\n# 认证命令 (auth)\r\n\r\n> 🔐 = 需要先登录\r\n\r\n## 命令列表\r\n\r\n| 命令 | 说明 | 需要登录 |\r\n|------|------|---------|\r\n| `kugou-cli auth login` | 获取二维码（`qrcode` 内部字符串 + `qrcode_img_url` 远程图片 URL + `qrcode_img_path` 本地 PNG 路径） | 否 |\r\n| `kugou-cli auth status` | 检查登录状态（**单次查询，不内部轮询**，agent 需外层循环 2-3s 间隔） | 否 |\r\n| `kugou-cli auth set-secret ` | 直接导入已持有的 base64 secret 登录（跳过扫码） | 否 |\r\n| `kugou-cli auth logout` | 登出 | 否 |\r\n\r\n---\r\n\r\n## 1. 扫码登录\r\n\r\n登录流程极简："},{"language":"text","snippet":"File v0.1.13:_meta.json\n\n{\n \"ownerId\": \"kn7crmv8zas1ep290wm2ag0wtn88te0q\",\n \"slug\": \"kugou-skill\",\n \"version\": \"0.1.13\",\n \"publishedAt\": 1788165956774\n}\n\nFile v0.1.13:references/auth.md\n\n# 认证命令 (auth)\r\n\r\n> 🔐 = 需要先登录\r\n\r\n## 命令列表\r\n\r\n| 命令 | 说明 | 需要登录 |\r\n|------|------|---------|\r\n| `kugou-cli auth login` | 获取二维码（`qrcode` 内部字符串 + `qrcode_img_url` 远程图片 URL + `qrcode_img_path` 本地 PNG 路径） | 否 |\r\n| `kugou-cli auth status` | 检查登录状态（**单次查询，不内部轮询**，agent 需外层循环 2-3s 间隔） | 否 |\r\n| `kugou-cli auth set-secret ` | 直接导入已持有的 base64 secret 登录（跳过扫码） | 否 |\r\n| `kugou-cli auth logout` | 登出 | 否 |\r\n\r\n---\r\n\r\n## 1. 扫码登录\r\n\r\n登录流程极简："}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\r\nname: kugou-skill\r\ndescription: |\r\n 酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手\r\n 提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单、调整音乐偏好等功能。\r\n\r\n **触发场景**（满足任一即使用本技能）：\r\n - 用户要求推荐歌曲、听歌建议\r\n - 用户要求搜索歌曲、查找歌手作品\r\n - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）\r\n - 用户要求查看收藏、最近播放、听歌统计\r\n - 用户要求创建歌单、自建歌单\r\n - 用户要求调整音乐偏好（\"少推点 XX 歌手\"、\"多推点 XX 语种\"、\"别再推 XX 曲风\" 等）\r\n - 用户提供 base64 secret 字符串要求登录或导入身份\r\n - Agent 在尝试扫码登录时遇到环境限制（无法发图片）→ 主动询问用户是否可提供 secret\r\n - 用户提到\"酷狗\"、\"kugou\"、\"猜你喜欢\"、\"相似歌曲\"\r\n - 用户要求让 PC/Mac 客户端播放歌曲、暂停、切歌、收藏、创建歌单\r\n - 用户提到酷狗 URL scheme（\"kugou://\" 或 \"mackugou://\"）\r\n - 用户提到\"本机控制\"、\"控制酷狗客户端\"\r\n\r\n **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐；同时支持把用户偏好（歌手/语种/曲风等）实时反馈给推荐引擎。\r\n\r\n 安装方式：npm install -g @kg-ai/kugou-skill\r\n---\r\n\r\n# kugou-skill\r\n\r\n## AI 使用工作流（优先阅读）\r\n\r\n使用本工具时的标准流程：\r\n\r\n```\r\n1. 检查安装 → npm install -g @kg-ai/kugou-skill\r\n2. 检查登录态 → kugou-cli auth status\r\n3. 登录决策（按以下优先级严格判断，不要跳步）：\r\n ├─ 状态 a：已登录（logged_in: true）→ 跳到第 6 步\r\n ├─ 状态 b：未登录 + 用户**明确**说\"我有 secret\" → 调 `kugou-cli auth set-secret \"\"` 一次完成 → 跳到第 6 步\r\n ├─ 状态 c：未登录 + 当前环境**无法**渲染远程 URL 图片 **且** 无法读取本地二维码文件 → **强制**走 set-secret（同上）\r\n └─ 状态 d：未登录 + 其他所有情况 → 走扫码流程（第 4 步）\r\n\r\n 注意：状态 b/c/d 互斥；不要在用户未明确给 secret 时擅自走 set-secret。\r\n4. 引导登录——扫码（详见 references/auth.md）：\r\n - 执行 `auth login`，从输出读 `qrcode_img_url` 和 `qrcode_img_path`，按当前客户端能力选一种方式把二维码**直接展示给用户**\r\n - **阶段 A（主动轮询）**：图片刚展示，**主动**重试几次 `auth status`（每次隔几秒），覆盖用户秒扫场景\r\n - 任意一次返回 `logged_in: true` → 跳到第 6 步\r\n - 见到 `status: failed` → **不要换新图**，隔 1-2 秒用同一个本地 qrcode 再调一次（计入阶段 A 的 5 次预算）\r\n - 见到 `status: expired` → 告诉用户二维码已失效，调 `auth login` 拿新图，从阶段 A 重新开始\r\n - 几次都返回 `waiting` / `failed` 且未出现 `scanned` / `logged_in` / `expired` → 进入阶段 B\r\n - **阶段 B（等用户回复）**：停下，告诉用户\"请用酷狗 APP 扫码登录，扫完后告诉我已扫码\"，**不再调 status**，等用户**主动回复\"已扫码\"**\r\n - **阶段 C（验证一次）**：用户回复\"已扫码\"后，**调一次** `auth status`：\r\n - `logged_in: true` → 完成，跳到第 6 步\r\n - `scanned`（已扫但未确认）→ 等几秒再调一次，最多**额外**调几次，仍是 scanned 就告诉用户\"手机端是否已点确认？\"\r\n - `failed` → **不要换新图**，隔 1-2 秒用同一个本地 qrcode 再调一次，最多重试 2-3 次；仍 failed 则告诉用户稍后重试\r\n - `expired` / `{\"logged_in\": false}`（无 status 字段，说明本地 qrcode 已被上游清掉）→ 重新 `auth login` 拿新图（覆盖本地），从阶段 A 重新开始\n5. **首次要展示歌曲/歌单前探测本机客户端可用性**（详见 [references/control.md §13](references/control.md#13-client-detection-control-detect)）：\r\n - **触发时机**：本会话中第一次要向用户展示歌曲列表、歌单列表或歌单内歌曲列表之前。后续展示**复用本次探测结果**（会话内探测一次即可，不要每条命令前都跑）\r\n - **命令**：`kugou-cli control detect`（零副作用，不启动客户端、不抢焦点）\r\n - **判定**：\r\n - 退出码 `0` → 本机有客户端，标记 `client_available = true`\r\n - 退出码 `2` → 本机没装客户端，标记 `client_available = false`\r\n - 退出码 `1` → 探测过程出错（注册表权限等），按 `false` 处理并继续\r\n - **不影响 control 命令本身**：当用户主动要求 `control play` 等命令时，仍按原本的 `control` 错误处理（找不到客户端会由 `control start` 报\"handshake file not found\"，不要用探测结果跳过 `control` 调用）\r\n - **何时不探测**：用户请求只查询统计数据、查收藏/最近播放、看错误页等**不展示歌曲列表**的纯查询场景；登录流程本身；debug / 排错场景\r\n\r\n6. 按请求类型分流：\r\n - **请求类型 A：控制已有歌 / 歌单 / 收藏**（用户已有 mixsongid 或 global_id）→ 直接执行 `control` 命令（详见 [references/control.md](references/control.md)），不需要先调 `music` 拿 ID\r\n - 例：`control play`"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7crmv8zas1ep290wm2ag0wtn88te0q\",\n \"slug\": \"kugou-skill\",\n \"version\": \"0.1.20\",\n \"publishedAt\": 1789355075881\n}"},{"path":"references/auth.md","content":"# 认证命令 (auth)\r\n\r\n> 🔐 = 需要先登录\r\n\r\n## 命令列表\r\n\r\n| 命令 | 说明 | 需要登录 |\r\n|------|------|---------|\r\n| `kugou-cli auth login` | 获取二维码（`qrcode` 内部字符串 + `qrcode_img_url` 远程图片 URL + `qrcode_img_path` 本地 PNG 路径） | 否 |\r\n| `kugou-cli auth status` | 检查登录状态（**单次查询，不内部轮询**，agent 需外层循环 2-3s 间隔） | 否 |\r\n| `kugou-cli auth set-secret ` | 直接导入已持有的 base64 secret 登录（跳过扫码） | 否 |\r\n| `kugou-cli auth logout` | 登出 | 否 |\r\n\r\n---\r\n\r\n## 1. 扫码登录\r\n\r\n登录流程极简：\r\n\r\n```bash\r\n# Step 1: 获取二维码，同时得到远程 URL 和本地 PNG 路径\r\nkugou-cli auth login\r\n\r\n# Step 2: 循环调用 status（**单次查询不内部轮询**，agent 自己外层循环）\r\n# 每次间隔 2-3 秒，看到 logged_in=true / status=success 即完成\r\nkugou-cli auth status\r\n```\r\n\r\n**auth login 输出示例**:\r\n```json\r\n{\"qrcode\": \"xxx\", \"qrcode_img_path\": \"C:\\\\Temp\\\\kugou-qrcode.png\", \"qrcode_img_url\": \"https://static.kugou.com/.../qrcode.png\"}\r\n```\r\n\r\n字段说明：\r\n- `qrcode`：二维码字符串标识，**Agent 不要使用** —— 仅供 CLI 内部持久化，以便后续 status 调上游 check 接口\r\n- `qrcode_img_path`：CLI 生成的本地二维码 PNG 文件绝对路径。当前客户端支持读取或附加本地图片时使用它，例如 Codex 等本地文件能力较强的客户端\r\n- `qrcode_img_url`：酷狗上游返回的远程二维码图片 URL。当前客户端支持 Markdown 外链图片时使用它，例如 WorkBuddy 等客户端\r\n- `qrcode_img_path` 和 `qrcode_img_url` 是两种并行的图片展示方式，Agent 根据当前客户端能力自行选择一种，不要同时展示两张二维码\r\n\r\n---\r\n\r\n## 2. AI 引导流程\r\n\r\n### 2.1 决策点：先问 secret，再选路径\r\n\r\n在调用任何 auth 命令之前，**先询问用户**：\r\n\r\n> \"你手上是否已有可用的 base64 secret 字符串？（从其他设备/工具导出的）\"\r\n\r\n- **用户明确说\"有\"** → 直接走 §3 `set-secret`，跳过 §1 扫码\r\n- **用户说\"没有\"或不确定** → 走 §2.2 扫码流程\r\n- **当前环境无法发送图片**（纯文本 agent、SSH 远端、容器）→ 强制走 §3 `set-secret`，不要走扫码\r\n\r\n> **默认行为**：除非用户明确说\"我有 secret\"，否则优先走扫码。\r\n\r\n### 2.2 扫码流程\r\n\r\n1. 调用 `auth login`，读取返回的 `qrcode_img_path` 和 `qrcode_img_url`\r\n2. **根据当前客户端能力选择一种方式展示二维码图片**：\r\n - 客户端支持读取或附加本地文件（如 Codex 等）→ 优先使用 `qrcode_img_path`，通过客户端的本地图片读取/附件能力展示。不要只把路径作为普通文本发给用户\r\n - 客户端支持 Markdown 外链图片（如 WorkBuddy 等）→ 使用 `qrcode_img_url`，在消息中输出 `![酷狗登录二维码]()`\r\n - Agent 可以自行选择最适合当前环境的方式，不要同时展示两张二维码\r\n - **避免**只输出“请打开 xxx URL”或“图片路径是 xxx”这种纯文字提示，用户应直接看到二维码图片\r\n - 选择的方式展示失败时，切换到另一种方式：远程图片加载失败则尝试本地文件，本地文件无法读取则尝试远程 Markdown 图片\r\n - 如果当前客户端既不能读取本地文件，也不能渲染远程 Markdown 图片 → 放弃扫码，切换到 §3 `set-secret` 路径\r\n3. **阶段 A — 主动轮询（覆盖秒扫）**：图片展示后，**主动**外层循环调用 `auth status`，每次间隔 2-3 秒，**最多 5 次**（与 `failed` 重试合并计数）：\r\n - 看到 `logged_in: true` → 完成，继续执行用户请求\r\n - 看到 `status: success` → 完成，继续执行用户请求\r\n - 看到 `status: scanned` → 等几秒再调一次 status\r\n - 看到 `status: failed` → **不要换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（计入 5 次轮询预算）\r\n - 看到 `status: expired` → **不再继续轮询**，主动告诉用户\"二维码已失效，正在重新获取\"，调 `auth login` 拿新图，回到步骤 1\r\n - 5 次都是 `waiting` / `failed` → 进入阶段 B\r\n4. **阶段 B — 等待用户反馈（关键）**：5 次主动轮询后仍未登录，**停下来**，不再调任何 auth 命令。主动告诉用户：\r\n > \"请用酷狗 APP 扫码登录，扫完后告诉我已扫码\"\r\n 然后**等用户主动回复**。**不要**自己继续轮询。\r\n5. **阶段 C — 验证登录**：用户回复\"已扫码\"后，调一次 `auth status` 验证：\r\n - `logged_in: true` → 完成，继续执行用户请求\r\n - `status: scanned` → 用户在手机上还没点确认，等几秒再调一次\r\n - `status: failed` → **不要换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（最多重试 2-3 次）\r\n - `status: expired` → 上游明确说过期（CLI 已清理本地），重新 `auth login` 拿新图，回到步骤 1\r\n - `logged_in: false`（无 status 字段）→ qrcode 已被清理（通常是上一步 `expired` 后状态），提示用户\"二维码可能已过期，正在重新获取\"并回到步骤 1\r\n6. **若用户在阶"},{"path":"references/control.md","content":"# 控制命令 (control)\r\n\r\n> AI-facing usage guide for `kugou-cli control` — the local PC/Mac Kugou client control subcommands.\r\n\r\n本模块通过本机 HTTP server 控制 PC/Mac 酷狗客户端，支持播放控制、收藏管理、歌单创建等操作。输出格式为原始 JSON（详见 [references/output-format.md](./output-format.md)）。\r\n\r\n**前置条件**: CLI 已登录（`kugou-cli auth login`）+ 酷狗客户端正在运行。仅支持 Windows / macOS（Linux 运行时会报错，见下方错误场景）。\r\n\r\n---\r\n\r\n## 命令列表\r\n\r\n### 读操作（read）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control start` | 显式触发握手/唤起客户端（用于预热或调试） |\r\n| `kugou-cli control status` | 获取客户端状态（协议版本、登录态、能力列表） |\r\n| `kugou-cli control current` | 获取当前播放歌曲（歌名、进度、音量、收藏状态） |\r\n\r\n### 播放器控制（player）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control play` | 播放歌曲（按 mixsongid） |\r\n| `kugou-cli control play-playlist` | 播放整个歌单（按 global_collection_id） |\r\n| `kugou-cli control continue-play` | 拉取\"另一设备续播\"列表并开始播放 |\r\n| `kugou-cli control player` | 播放器控制（播放/暂停/切歌/停止） |\r\n| `kugou-cli control seek` | 进度控制（快进/快退/跳转） |\r\n| `kugou-cli control volume` | 音量控制（增减/设置/静音） |\r\n\r\n### 账户操作（account）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control favorite song` | 收藏/取消收藏歌曲 |\r\n| `kugou-cli control favorite songlist` | 收藏/取消收藏歌单 |\r\n| `kugou-cli control playlist create` | 创建本地歌单（带歌曲列表） |\r\n\r\n### 系统操作（utility）\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `kugou-cli control open` | 打开客户端内页面（主界面/歌手/专辑/歌单/搜索） |\r\n| `kugou-cli control doctor` | 诊断 `control start` 失败的根因（HVCI / VBS / launcher / home-dir） |\r\n\r\n---\r\n\r\n## 1. start — 显式触发握手\r\n\r\n触发酷狗客户端的 URL scheme 唤起，等待客户端建立本机 HTTP 通道并返回状态。仅用于预热通道或调试连通性，不调用任何 `/v1/...` 业务接口。\r\n\r\n```bash\r\nkugou-cli control start\r\n```\r\n\r\n**输出示例**（成功）:\r\n```json\r\n{\"handshake\":\"ok\",\"addr\":\"http://127.0.0.1:52144\"}\r\n```\r\n\r\n**输出示例**（失败）:\r\n```\r\nkugou-cli control: not logged in, run `kugou-cli auth login` first: auth file not found\r\n```\r\n\r\n**`start` 失败时优先跑 `control doctor` 诊断根因**（见下文 §N）。常见场景：\r\n- Win11 Memory Integrity (HVCI) 开着 + 客户端 v20.1.40：HVCI 拦截客户端启动时访问的内存，触发 NTSTATUS 0xC0000005 → 关 HVCI 后重试\r\n- PowerShell 被裁掉（Windows Sandbox / AppContainer）：URL scheme 触发失败 → 自动 fallback 到 `cmd /c start`\r\n- $HOME / $USERPROFILE 未设置或不可写：握手文件无法落地 → 设置有效环境变量\r\n\r\n---\r\n\r\n## 2. status — 获取客户端状态\r\n\r\n查询本地酷狗客户端的协议版本、登录态和能力列表。\r\n\r\n```bash\r\nkugou-cli control status\r\n```\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"code\": 0,\r\n \"data\": {\r\n \"version\": \"1.0.0\",\r\n \"login\": true,\r\n \"capabilities\": [\"play\", \"pause\", \"seek\", \"volume\", \"favorite\", \"playlist\"]\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 3. current — 获取当前播放\r\n\r\n查询当前播放歌曲详情，包括歌名、歌手、进度、音量和收藏状态。\r\n\r\n```bash\r\nkugou-cli control current\r\n```\r\n\r\n**输出示例**:\r\n```json\r\n{\r\n \"code\": 0,\r\n \"data\": {\r\n \"song_name\": \"晴天\",\r\n \"singer_name\": \"周杰伦\",\r\n \"mixsongid\": \"32100650\",\r\n \"position_ms\": 45000,\r\n \"duration_ms\": 240000,\r\n \"volume\": 65,\r\n \"favorited\": false\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 4. play — 播放歌曲\r\n\r\n在客户端播放一首歌曲。`--mixsongid` 必填，其余字段可选（仅用于客户端展示，不影响播放命中）。\r\n\r\n```bash\r\nkugou-cli control play --mixsongid 32100650 --song-name \"晴天\" --singer-name \"周杰伦\"\r\nkugou-cli control play --mix-song-id 32100650 --mode \"append_queue\"\r\n```\r\n\r\n**参数**:\r\n\r\n| 参数 | 说明 |\r\n|------|------|\r"},{"path":"references/error-handling.md","content":"# 错误处理\r\n\r\n> **判定优先级**：退出码（非 0 = 失败）→ stdout body 的 `errcode` 字段 → stderr 文案。\r\n> Agent **不应依赖 stderr 文案字面量**判断错误类型——文案可能随版本变化；以退出码和下表为准。\r\n\r\n---\r\n\r\n## 常见错误及处理\r\n\r\n| 错误信息 | 原因 | 处理方式 |\r\n|---------|------|---------|\r\n| `账号登录过期，请重新登录` | 登录态已过期（errcode 语义由上游约定）。CLI 已**自动**清理本地登录态 | 引导用户重新登录：`kugou-cli auth login`（扫码）或 `kugou-cli auth set-secret \"<新 secret>\"` |\r\n| `not logged in` / `auth file not found` | 未登录 | 引导用户执行 `kugou-cli auth login` |\r\n| `HTTP error: 400` | 请求参数有误 | 检查命令参数是否正确 |\r\n| `HTTP error: 500` | 服务端错误 | 稍后重试，或告知用户 |\r\n| `API error: (code=)` | 业务错误（上游 errcode ≠ 0） | 根据 errmsg 提示用户 |\r\n| `network error: ...` | 网络连接问题 | 检查网络，可尝试 `--proxy` |\r\n| `failed to get device info` | 设备信息获取失败（仅 control） | 运行时环境异常，检查权限 |"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手 提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单、调整音乐偏好等功能。 **触发场景**（满足任一即使用本技能）： - 用户要求推荐歌曲、听歌建议 - 用户要求搜索歌曲、查找歌手作品 - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等） - 用户要求查看收藏、最近播放、听歌统计 - 用户要求创建歌单、自建歌单 - 用户要求调整音乐偏好（\"少推点 XX 歌手\"、\"多推点 XX 语种\"、\"别再推 XX 曲风\" 等） - 用户提供 base64 secret 字符串要求登录或导入身份 - Agent Skill: 酷狗 Owner: shamo88 Summary: 酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手 提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单、调整音乐偏好等功能。 **触发场景**（满足任一即使用本技能）： - 用户要求推荐歌曲、听歌建议 - 用户要求搜索歌曲、查找歌手作品 - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等） - 用户要求查看收藏、最近播放、听歌统计 - 用户要求创建歌单、自建歌单 - 用户要求调整音乐偏好（\"少推点 XX 歌手\"、\"多推点 XX 语种\"、\"别再推 XX 曲风\" 等） - 用户提供 base64 secret 字符串要求登录或导入身份 - Agent Tags: latest:0.1.20 Version history: v0.1.20 | 2026-09-14T03:04:35.881Z | user kugou-sk","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":585,"uniquenessScore":59,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T04:43:08.802Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T04:43:08.802Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:41:39.778Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}