bili-music: Instructions file for Codex

协作规则

本文件只记录长期规则。功能入口见 docs/where-to-change.md，架构与原生端口见 docs/frontend-architecture.md，界面改动以 docs/ui-spec.md（方案 C：极简紧凑）为视觉规范，已完成迁移的记录见 docs/frontend-migration-history.md。历史文件名不能作为改写现有链路的依据。后续设计说明保存到 docs/design/，不只保留在系统临时目录。

全面 Vue 化已完成；Windows/Mac 发布前全应用回归于2026-10-16完成，对应 master d8a7f4bc856b1aa7af23ec81d2c84c4bce9cffaa，Windows watchdog 故障包亦已验证。后续功能修改仍按任务验收；发布时须由用户核对最新 master CI。

技术栈与架构

• Tauri v2、Rust Cargo workspace、TypeScript、Vue 单一 App.vue 根组件。迷你窗保持独立入口。Vue 3.5.43、Vite 8.3.2、TypeScript 6.0.3、@vitejs/plugin-vue 6.0.10、@vue/test-utils 2.5.1、jsdom 26.1.0、vue-tsc 3.3.12 精确锁定；不增加 Pinia、Vitest 或其他状态库。TS 升级须等 Vue 工具链支持。
• app.ts 首先静态导入根挂载模块；先同步首屏挂载，再求值控制器与 DOM 端口。唯一应用 store 在无 DOM 的组合模块创建，根订阅最先安装，随后才能交给业务模块。首页 getter 仍在首次调用时安装首页订阅并首投影。
• 每次 store 提交用完整只读快照、稳定回调与 Vue 公开 render() 同步渲染。action 返回前 DOM、disabled、焦点契约必须成立；不能把 nextTick、watch、RAF 合批用作主渲染路径。禁止 Vue 私有调度 API。
• 迷你窗由独立 MiniApp.vue 根组件同步渲染主窗快照及本地显示变化；首次挂载完成后才发出双通道就绪。位置、原生拖动、焦点与标题测量/动画留在控制器。两个窗口分别构建并各自内联Vue，禁止公共运行时chunk改变主入口；根HTML主题/CSS变量是登记的平台端口。
• 子组件只接切片 props、稳定显示模型与回调，不访问 window、TAURI、invoke、actions，不订阅 store。未变切片靠结构共享与浅比较跳过。列表高亮只重绘旧、新行，收藏变化只重绘受影响行，纯进度不重绘列表或行。
• store 公开 getState、subscribe（返回取消订阅函数）、领域 actions；subscribe 不立即回调，首屏显式 getState。快照深只读，只复制改变路径；Map/Set 写入新集合。测试开启深冻结，生产不冻结。订阅者异常须报告并隔离，不能阻断其他订阅者及动作后续阶段。
• 状态与纯投影不引用 DOM、window、Tauri 或平台时钟；副作用经适配器/控制器。同步完整阶段提交一次，异步开始、成功、失败分别提交。不提供任意运行期写状态接口。
• 两个窗口的界面全部由 Vue 渲染。Vue宿主内节点只有组件一个写入方，控制器/投影不得写textContent、innerHTML、classList、style、属性或增删节点；原生读取/事件端口通过类型化ref回传，逐项登记于架构文档。焦点、几何测量、滚动、RAF/transitionend、窗口与媒体副作用保持控制器所有权。
• 精确例外：Vue宿主外的唯一audio；html/body的文档级属性、dataset和CSS变量；原生窗口拖动/缩放与指针捕获；控制器的焦点/选择、测量、滚动和observer；不挂载的Image/canvas取色。非受控输入只由组件内部directive/ref端口写入，Key不经props或store。scripts/vue/native-writes.ts按文件和完整表达式检查原生写入例外，新增项须说明理由并配反例；不能以宽泛文件白名单绕过。
• audio 永久在 index.html 的 Vue 宿主外；不得重建、复制或重复监听。不建立第二套播放器。分P列表每次投影整体替换并保留重绘焦点规则；资料库内容按 session.version 替换，同 session 输入框复用，generic 为空。隐藏设置、沉浸页与歌词继续投影，保留 hidden/is-open/aria-hidden 的阶段，不用 v-if/Transition 重写开关阶段。
• 搜索、首页提示、歌词手动搜索使用非受控草稿读写端口；保留各调用方 trim、恢复与分页执行时回读的时机。恢复不发 input、不提交、不记历史；切歌不写搜索草稿。API Key 不绑定任何来自 store/props 的 value。
• 构建与组件测试统一将 VUE_OPTIONS_API、VUE_PROD_DEVTOOLS、VUE_PROD_HYDRATION_MISMATCH_DETAILS 定义为 false。strict、erasableSyntaxOnly、isolatedModules 等不放宽，不写显式 any 或宽泛 declare module '*.vue'。生产 JS（含 inline）直接 eval/new Function 的 AST 计数均为0。