- Python 最低版本为 3.10；依赖和命令统一通过 uv 管理。
- 主运行环境是原生 Windows；WSL 支持 CLI、测试与静态检查，GUI 运行优先原生 Windows。
- 核心依赖必须声明在
pyproject.toml并由uv.lock固定；GUI 与构建依赖保持可选分组。 - 项目采用
src/布局，不为形式迁移为其他目录结构。
- 延续现有 Fluent UI React v9 设计方向与 PySide6 / qfluentwidgets 实现，不因 GUI 优先而更换技术栈。
- 默认保留主要导航、页面职责和常用操作关系；局部文案、间距、状态反馈、性能与可访问性可以持续改善。
- 主要入口迁移、页面合并、常用术语改名或整体换风格，必须先说明可验证的用户问题、现有结构为何 无法解决，以及老用户如何找到原功能。仅凭新概念图更好看不足以启动整体改版。
- 查找、导出和任务管理增强优先在现有职责内扩展，不自动增加顶层页面、第二套选择语义或重型行内播放器。
- 界面稳定不冻结错误行为或阻止必要修复；兼容与恢复问题优先于视觉偏好。
- 左侧任务对象与右侧当前实体音频选择分开；音频导出不跨实体累积。父节点选择只计可用音频， 不可用映射项保留且不可选；全选导出不自动触发解包。
- 用户任务、批量导出、失败重试、资源包扫描与共享准备共用单重任务门禁；不自动排队。
- 任务结果通知沿用居中浮层，关闭提示不删除结果；详情覆盖当前页面并独立滚动，不增加表单高度。
- 配置文件为
lol-audio-unpack.ini；开发模式使用对应 dev 文件。 - 默认值加 CLI 显式参数，与完整
-c配置文件模式互斥，不做隐式逐层 merge。 - 生产配置不读取旧
LOL_*环境变量。测试可使用明确命名的环境变量定位外部测试资源， 但不能改变应用配置契约。 - 英雄选择支持稳定 ID 与 alias；地图更新必须包含 ID
0作为 Common 去重基线。
- 默认保留原始 WEM 文件及游戏数据中的 ID，不做语义重命名。
- 生产结构化数据使用 MessagePack，开发模式使用 YAML。
- 应用只消费
game_path指向的本地文件系统目录；该目录可以是真实客户端，也可以由外部工具 预先准备，但应用不负责下载、拼装或更新远端快照。 - 创建
AppContext时必须先验证 GAME/LCU 基础结构与版本元数据；验证失败不得初始化输出产物。 - resource schema v2 以逐条 WAD/entry binding 为唯一物理资源事实；解包与映射不回退到
alias、分类名、
.use_local_bin或bin_input猜测资源。 - 历史 resource-pack 发现只能扫描用户显式选定且位于
Game/DATA/FINAL的 WAD；默认 update 不得扫描全部顶层 WAD。 - 外部准备器是独立上游，不属于本仓库的运行时依赖；本应用不得在本地资源缺失时静默访问网络。
- 上游库的内部算法由上游维护；本项目只负责并验证自己的适配、编排、产物和恢复边界。
- 代码、项目文档和测试样本不得写入开发者机器的真实绝对路径、凭证或可定位个人环境的信息。
- 用户消息不直接暴露密钥、完整堆栈或不必要的后端实现细节；诊断信息进入内部日志。
- 运行时拒绝越界 BIN 路径；外部输入参与路径或子进程参数时必须保留结构化边界。
- 测试、benchmark、构建 scratch 与缓存统一写入
.temp/，任务结束清理本轮可安全识别的产物。
- GUI 测试不进入默认离线门禁；精选 pytest-qt 状态测试显式执行，视觉与正式可执行文件由 人工验收。
- 真实本地数据源和多进程兼容测试位于
tests/system/，默认 pytest 不发现它们。 - 不通过读取源码字符串来证明运行时、GUI、CI 或发布行为正确。
- 默认分支为
main，开发分支为v3-test；远端 push、PR、tag、Release 和 merge 均需单独授权。 - 维护变更不隐含版本号、release notes、tag 或发布操作。