darknessomi musicbox 控制规则
黄金法则
- 通过
musicbox <cmd> --json操作，绝不向 curses TUI 模拟按键。 - 重要动作后调
musicbox status --json读回真实状态再回复用户，不要"发完命令就假设成功"。 play/next/prev的即时返回值常滞后（先stopped或旧进度）；sleep 1–2 秒后再status再下结论。- 数据类命令（search/artist/album/playlist/toplist/...）无状态，直接调，不需要 daemon。
命令速查
| 类别 | 命令 |
|---|---|
| 播放控制 | play [--id <id>|--playlist <id>|--index <n>|--artist <id>|--album <id>|--songs <ids...>] / pause / resume / toggle / stop |
| 切歌/进度 | next [n] / prev [n] / seek <秒|+n|-n> |
| 音量/模式 | volume <0-100|+n|-n> / mode <ordered|ordered-loop|single-loop|random|random-loop> |
| 状态/歌词 | status / lyrics --current |
| 队列 | queue list / queue add <id...> / queue play <index> / queue clear --yes |
| 守护进程 | daemon start|stop|status|restart |
| 搜索 | search <keyword> --type song|artist|album|playlist|dj |
| 歌曲/歌单 | song info <id> / song url <id> [--quality lossless] / playlist show <id> |
| 榜单/推荐 | toplist [--index n] / recommend songs|playlists（需登录） / fm（需登录） |
| 评论/喜爱 | comments <id> / like <id>（需登录） |
| 查询歌手/专辑 | artist <id> / album <id> |
| 下载 | download --artist/--album/--songs/--playlist |
| 认证/配置 | auth status|login|logout / config get <key> / config list |
任务配方
搜歌并播放
musicbox search <关键词> --type song --json # 取 data[0].song_id
musicbox play --id <song_id> --json
# sleep 1–2s
musicbox status --json
暂停 / 继续
当前 state |
命令 |
|---|---|
paused |
musicbox resume --json → status |
stopped |
不要 resume；用 play --id <id>、play --index <n>，或队列非空时 play |
| 换歌/换歌手 | 用 play --id，不要假设 resume 能接上之前的暂停 |
今日推荐（需登录）
musicbox auth status --json # exit 3 则走 login split-flow
musicbox recommend songs --limit 20 --json # 收集 data[].song_id → ids[]
musicbox play --id <ids[0]> --json
musicbox queue add <ids[1]> <ids[2]> ... --json # 每个 ID 独立 argv
musicbox mode ordered --json
musicbox status --json
queue add 在 shell 里勿把多个 ID 拼成一个字符串；可用 queue add $(printf '%s\n' "${ids[@]:1}") 或从 JSON 解析后逐个传参。
歌单播放
musicbox play --playlist <playlist_id> --json
musicbox mode ordered --json # 列表类意图默认顺序播放
musicbox status --json
切歌后用 queue_index / queue_size 确认当前第几首。
搜歌手并播放热门歌曲
musicbox search <关键词> --type artist --json # 取 data[0].id
musicbox artist <artist_id> --json # 查看热门歌曲
musicbox play --artist <artist_id> --limit 20 --json # 播放前 20 首
musicbox status --json
搜专辑并播放
musicbox search <关键词> --type album --json # 取 data[0].id
musicbox album <album_id> --json # 查看专辑歌曲列表
musicbox play --album <album_id> --json # 播放整张专辑
musicbox status --json
播放多首指定歌曲
musicbox play --songs <id1> <id2> <id3> --json # 清队列 + 添加歌曲 + 播放第一首
musicbox queue list --json # 确认队列内容
musicbox status --json
下载歌曲
musicbox download --playlist <playlist_id> --path ./music --json
musicbox download --artist <artist_id> --limit 20 --path ./music --json
musicbox download --album <album_id> --path ./music --json
musicbox download --songs <id1> <id2> --path ./music --json
每首歌曲下载为 <artist>-<song>{ext}，扩展名取决于音源（.mp3 或 .flac），结果输出 JSON 数组，每项包含 ok/错误信息。
输出约定
- Agent 调用时始终加
--json，解析 stdout 的{ok, data}信封。 - 错误在 stderr：
{ok: false, error: {type, message, hint}}。 - 管道取值可用
--quiet（只输出关键值）。 --dry-run：只打印将发送的 RPC，不产生副作用，用于预演控制命令。
daemon 生命周期
- 播放是有状态本地会话，由常驻
musicboxd守护进程持有；控制类命令经它通信。 - 控制类命令默认自动拉起 daemon；若遇
exit 4（daemon 未运行），先musicbox daemon start再重试。 --no-daemon-autostart可禁用自动拉起（不在跑则直接exit 4）。- daemon 与 curses TUI 互斥：TUI 在跑时 daemon 无法启动，反之亦然。
- 本地改过播放/daemon 代码后，先
musicbox daemon restart，否则仍是旧进程逻辑。
status 是你的眼睛
{ "ok": true, "data": {
"state": "playing|paused|stopped",
"song": {"id": 33894312, "name": "...", "artist": "...", "album": "...", "duration": 273},
"position": 41.2, "length": 273, "volume": 60,
"mode": "ordered", "backend": "mpv", "queue_index": 3, "queue_size": 20
}}
登录（split-flow，必须分两轮）
- 本轮：
musicbox auth login --no-wait --json→ 取qr_ascii/unikey→ 把二维码发给用户 → 明确告知「用网易云音乐 App 扫码并确认后回来告诉我」→ 结束本轮。 - 下一轮：用户回复后执行
musicbox auth login --check <unikey> --json。
纪律：
- 禁止输出 URL 让用户打开登录；必须使用网易云音乐 App 扫二维码。
- 禁止同轮展示二维码后立刻阻塞轮询。
- 禁止跨会话缓存
unikey（过期即重新login --no-wait）。
退出码分支
| code | 含义 | Agent 应对 |
|---|---|---|
| 0 | 成功 | 继续 |
| 1 | 通用失败 | 读 error.message |
| 2 | 参数错误 | 按 hint 修正 argv 重试 |
| 3 | 未登录 | 走 auth login split-flow |
| 4 | daemon 未运行 | musicbox daemon start 后重试（控制类默认会自动拉起） |
| 5 | 操作不支持 | 读 error.message（如 mpg123 后端不支持 seek） |
| 10 | 高风险写操作需确认 | 先问用户，再在 argv 末尾追加 --yes 重试；绝不静默加 --yes |
注意事项
seek仅在 mpv 后端可用；mpg123 后端会返回not_supported（exit 5），可提示用户播放无损或将player_backend设为mpv。queue clear、auth logout是高风险写操作，遇exit 10先向用户确认。- 版权失败：
state为stopped且日志/通知含 copyright；单曲或无可切下一首时会停止，不要对同一首反复play/next重试，直接告知用户换歌。 - 播列表、今日推荐、歌单时，未指定模式则设
mode ordered，避免残留random-loop打乱顺序。