decky-music: Instructions file for Codex

AGENTS.md

Library

以下为使用的库:

• https://github.com/L-1124/QQMusicApi —— QQ 音乐 provider(Python 库)
• https://github.com/SPlayer-Dev/ncm-api-rs —— 网易云 provider(Rust 库)
• https://github.com/SteamDeckHomebrew/decky-loader —— 插件宿主 / API 来源
• rodio + reqwest(rustls-tls)—— player 拉流/解码/输出
• @decky/api + @decky/ui —— 前端

架构速览

UI 只跟 bridge 说话;bridge 是唯一常驻的真相源;provider / player 是插件沙盒外的独立二进制。

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

目录:

• main.py —— 只剩对外接口 facade:CALLABLES 白名单 + __getattr__ 转发给 bridge (Decky loader 按名 getattr 分发,不必逐个写同名方法;tests/test_callables.py 机械校验白名单 ↔ Bridge 方法 ↔ src/api.ts 三端一致)
• py_modules/ —— bridge 实现(bridge.py 总线 + 进程管理 / log.py 日志);放这里才被 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
• ncm-provider/ —— Rust,依赖 ncm-api-rs
• qq-provider/ —— Python,依赖 qqmusic_api,Nuitka --standalone 打包

Coding rules

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

Dev environment

• 部署目标:Steam Deck(SteamOS,gamescope 会话)。SSH/路径见 scripts/deploy.sh。
• bridge 跑在 Decky 冻结的 CPython 里,只能用 stdlib,严禁第三方依赖(编译扩展会随 Decky 升级崩)。
• 三个二进制通过 Decky remote_binary(package.json)在安装时下载,不进插件包。
• 改了 player / provider 代码必须先重建二进制再部署:deploy.sh 只搬运 target/release/* 和 qq-provider/build/*.tar.gz 里已有的产物,不自动重建。改了 Rust/Python 后先 bash scripts/build-rust.sh -p <player|ncm-provider> / bash scripts/build-qq-provider.sh 再 deploy,否则装的是旧二进制。只改前端则 deploy 会自己 pnpm build。