decky-music: Instructions file for Codex

AGENTS.md

Library

以下为使用的库:

• https://github.com/jinzhongjia/QQMusicApi-rs —— QQ 音乐后端(Rust 库,L-1124/QQMusicApi 的 Rust 实现)
• https://github.com/jinzhongjia/ncm-api-rs(`feat/sync-upstream-2026-10` 分支)—— 网易云后端(Rust 库)
• https://github.com/SteamDeckHomebrew/decky-loader —— 插件宿主 / API 来源
• rodio + reqwest(rustls-tls)—— player 拉流/解码/输出
• @decky/api + @decky/ui —— 前端

架构速览

UI 只跟 bridge 说话;bridge 是唯一常驻的真相源;provider / player 是插件沙盒外的独立二进制。 provider 是一个常驻进程,同时承载 QQ 与网易云两个后端:请求顶层带 provider 字段路由, 切换音源只换 bridge 的音源令牌(Selection),不再换进程。 bridge 包含播放与队列的控制决策(Playback):普通队列/电台、自动切歌、失败重试和状态回灌。 音源 API 与可播 URL 解析归 provider,拉流/解码/出声归 player;不能把队列决策移回 UI 或子进程。

UI (React)  ──Decky RPC(callable/emit)──  bridge (main.py)
                                              │  UDS + NDJSON,bridge 作 server
                            ┌─────────────────┴─────────────────┐
                      provider 进程                          player 进程
               Rust:qq + ncm 两个后端同进程                   Rust
                 出元数据·歌词·可播 URL                    拉流·解码·出声

目录:

• main.py —— 只剩对外接口 facade:CALLABLES 白名单 + __getattr__ 转发给 bridge (Decky loader 按名 getattr 分发,不必逐个写同名方法;tests/test_callables.py 机械校验白名单 ↔ Bridge 方法 ↔ src/api.ts 三端一致)
• py_modules/ —— bridge 实现:bridge.py 生命周期门面、ipc.py 连接与事件代次、music_settings.py 归一化与私有持久化、child_process.py/supervision.py 进程监督、provider_rpc.py/playback_rpc.py RPC、playback*.py 播放/队列/电台、diagnostics.py/log.py 安全诊断。配置模块避免使用宿主占用的 settings 名称；所有模块放这里才被 Decky 加进 sys.path 且被 CLI 打包。
• src/ —— React UI:index.tsx(definePlugin 入口)/ QAM.tsx(QAM 面板)/ Page.tsx(大屏页,导出 ROUTE)/ api.ts(前端↔bridge 唯一接口层)/ errors.ts+ErrorBanner.tsx+Boundary.tsx(错误纵深)/ Footer.tsx / i18n.ts
• player/ —— Rust,reqwest + rodio
• provider/ —— Rust,统一音源进程:src/main.rs 按请求音源路由,src/ncm/(ncm-api-rs)、 src/qq/(QQMusicApi-rs)两个后端,src/lyric/ 两家共用的歌词解析

Coding rules

• 不要写过长的代码，例如单文件超过 500 行，函数超过 50 行。
• 插件支持 i18n，支持语言为 中文 和 英文。
• 开发完一部分后就提示用户提交代码，避免一次性提交过多代码。