QQ Music Browser Control — QQ 音乐浏览器控制

QQ Music 浏览器控制 使用此社区维护的技能来控制 QQ Music 的网页播放器（y.qq.com）通过浏览器 DevTools/CDP 端点。

安全模型 此技能使用 Chrome DevTools Protocol (CDP) 来自动化 QQ Music 的网页 UI。它与腾讯或 QQ Music 无关。CDP 是一个强大的协议 —— 以下安全措施是为了最小化其影响范围：

域名白名单 脚本仅在 y.qq.com 标签页上运行。有两层域名验证：

目标选择：在选择要连接的标签页时，脚本检查标签页 URL 与允许列表（y.qq.com）进行匹配。非匹配标签页将被拒绝。 预评估重新检查：在每次 Runtime.evaluate 调用之前，脚本查询连接页面的 location.hostname 并验证它仍然是 y.qq.com。如果页面在连接后导航到不同的域名，调用将被拒绝并返回错误。这可以防止脚本读取或操纵其他网站（电子邮件、银行等）的内容，即使页面在初始连接后导航到其他地方。

隔离浏览器配置文件（推荐） 我们强烈推荐使用 --user-data-dir 参数启动浏览器，指向一个专用目录： chrome --remote-debugging-port=9222 --user-data-dir=/path/to/qq-music-profile 这可以确保：

启用 CDP 的浏览器实例无法访问主浏览器的 cookie、密码或会话 只有 QQ Music 登录状态存在于此配置文件中 关闭此浏览器不会影响主浏览器

单端口绑定 脚本默认仅探测一个端口 —— 从 .cdp-port 缓存文件中读取，或回退到 9222。它不扫描端口范围。这可以最小化意外连接到无关 DevTools 端点的机会。

无需 SSRF 政策更改 此技能不使用 OpenClaw 的内置浏览器工具。它直接通过 WebSocket 从本地 Node.js 脚本连接到 CDP。无需在 OpenClaw 的配置中进行 SSRF 政策放松。

CDP 能做什么和不能做什么 能力 | 是否在范围内 | 备注 -----|----------|----- 在 y.qq.com 标签页中执行 JS | ✅ | 核心功能 —— 点击按钮、读取 DOM。每次调用前重新检查域名。 在非 y.qq.com 标签页中执行 JS | ❌ | 被域名白名单阻止 从 y.qq.com 读取 cookie | ⚠️ | 技术上可行，但脚本从不这样做 访问其他浏览器标签页 | ⚠️ | CDP 可以列出所有标签页，但脚本仅与 y.qq.com 标签页交互 访问文件系统 | ❌ | CDP Runtime.evaluate 运行在页面沙盒中 安装扩展 | ❌ | 脚本不使用 Target.createBrowserContext 或扩展 API

诚实的限制 CDP 本质上可以访问连接浏览器中的所有标签页。域名白名单是一个应用级别的防护，而不是浏览器级别的沙盒。使用 --user-data-dir 进行隔离是最强的缓解措施。脚本在 QQ Music 页面上运行 Runtime.evaluate 以执行任意 JavaScript。这相当于在该页面上使用浏览器的 DevTools 控制台。这是一个社区自动化工具，用于音乐播放器，而不是安全关键应用。使用常识：不要在不信任的机器上运行它。

支持的功能 跨平台：Windows、macOS、Linux 跨浏览器：Chrome、Chromium、Edge、Brave、Arc 或任何暴露 DevTools/CDP 端点的浏览器 传输：播放、暂停、切换、下一首、上一首 搜索和播放：歌曲、艺术家、专辑 喜欢的歌曲：播放所有、播放随机、喜欢/不喜欢当前曲目 播放列表：列出创建的播放列表、创建新播放列表、将当前歌曲添加到播放列表、通过 ID 播放播放列表 模式控制：循环播放、单曲循环、随机播放、顺序播放 状态：当前曲目、艺术家、时间、播放状态 截图捕获

要求 Node.js 18+（使用内置 fetch 和 WebSocket） 启用远程调试的基于 Chromium 的浏览器（请参阅下面的设置） 在 y.qq.com 登录的 QQ Music 账户（用于喜欢的歌曲、播放列表和喜欢/不喜欢）

设置指南（适用于 Agents） 此技能通过 CDP 连接到浏览器。Agent 需要：

发现 CDP 端口 缓存它以备后续调用 确保 QQ Music 已打开并登录

步骤 1：发现和缓存 CDP 端口 运行内置浏览器状态工具以获取当前 cdpPort，然后将其写入 .cdp-port： 浏览器状态 → 从响应中读取 cdpPort（例如 19011） 将端口号写入：<技能目录>/.cdp-port .cdp-port 文件应仅包含端口号，不能包含其他内容。 示例内容：19011

步骤 2：验证连接 node qq-music-ctl.js doctor 检查状态是否为“ready”。如果状态为“connected_no_qq_music_tabs”，请先通过 node qq-music-ctl.js init 打开 QQ Music。如果状态为“no_endpoint”，则缓存的端口可能已过期 —— 返回步骤 1。

步骤 3：确保 QQ Music 已打开并登录 用户必须至少一次登录到 y.qq.com。如果没有 QQ Music 标签页： node qq-music-ctl.js init 这将在新标签页中打开 https://y.qq.com/。用户可能需要手动登录第一次。 注意：此技能不需要任何 OpenClaw SSRF 政策更改。