潮衣柜 WaveWardrobe

English | 简体中文

面向 WWMI 的本地可视化 Mod 衣柜。前端负责交互界面，本地 API 独占文件系统访问，所选的整个 WWMI Mods 目录是唯一事实来源。

Important

WaveWardrobe 是非官方社区项目，与库洛游戏及 WWMI 的开发者或维护者无隶属或背书关系。使用前请备份 Mod；你需要自行遵守游戏、WWMI 和 Mod 作者的相关条款。

功能

• 递归扫描 Mods 下的 Mod 和玩家自建分类目录，不要求 mod2、Disabled_mod 等固定目录；
• 优先按中英文角色别名归类，并用唯一的 INI 哈希指纹识别名称不含角色的 Mod；
• 只显示当前衣柜中实际拥有 Mod 的角色，未知或哈希证据冲突的项目保留为“未识别”；
• 提供 4:5 封面、角色头像导航、详情抽屉和 Ctrl+K 命令面板；
• 支持将 ZIP、7Z 和 RAR 压缩包安全导入 Mods 根目录，并在导入前检查路径穿越、链接、体积、解压倍率和目标重名；
• 支持粘贴游戏截图并保存为 Mod 的自定义预览图；
• 双击换装，同角色已启用服饰会原子移动到统一的 Disabled_Mods 目录，并保留 Disabled_ 前缀作为第二重保护；
• 启用 Mod 时自动移除自身的禁用前缀并移回 Mods 根目录，不会连带启用 Disabled_Mods 中的其他 Mod；
• 可从命令面板运行本地 Wuwa Mod Fixer，完成后自动重新扫描；
• 设置可持久化衣柜根目录和可选的 Wuwa Mod Fixer 路径；
• API 不可达时使用明确标识的演示模式，不会把示例数据伪装成真实衣柜。

环境要求

• Windows；
• Node.js 22 或更高版本；
• 已正确配置的 WWMI Mods 目录。

快速开始

请把项目下载或克隆到 WWMI Mods 目录之外，然后双击根目录的 一键启动潮衣柜.cmd。首次启动会自动安装依赖并完成生产构建，服务就绪后会打开浏览器；关闭启动窗口即可停止潮衣柜。日常启动不运行 Vite 或 API 的开发文件监听器。

也可以在 PowerShell 中手动启动：

git clone https://github.com/xiang-ys/WaveWardrobe.git
Set-Location WaveWardrobe
npm install
npm run build
npm start

打开 http://127.0.0.1:4173。本地 API 监听 http://127.0.0.1:47831。

首次启动后，点击右上角的设置按钮选择 WWMI 的 Mods 目录。程序会递归扫描其中的 Mod；mod2、Disabled_mod 或其他分类目录均可保留，但不需要预先创建。设置保存在项目根目录的 wavewardrobe.settings.json，该文件已被 Git 忽略，不会上传你的本地路径。

环境变量

图形设置会满足大多数使用场景，也可以在启动前设置以下环境变量：

$env:WARDROBE_ROOT = 'D:\Games\WWMI\Mods'
$env:WARDROBE_PORT = '47831'
$env:WUWA_FIXER_PATH = 'D:\Games\WWMI\Mods\Wuwa_Mod_Fixer.exe' # 可选
npm run build
npm start

未指定 WUWA_FIXER_PATH 时，WaveWardrobe 会自动选择 Mods 根目录中版本号最高的 Fixer。

常用命令

npm run dev           # 同时启动 API 和 Web 开发服务
npm start             # 启动无文件监听的生产服务（需先构建）
npm test              # 运行全部测试
npm run build         # 构建全部工作区
npm run test:coverage # 生成测试覆盖率报告
npm audit --audit-level=high

项目结构

apps/api/          Fastify 本地 API、文件操作服务和角色头像
apps/web/          React + Vite 界面
packages/contracts 前后端共享的 TypeScript 类型
scripts/           维护脚本

本次通用 Mods 根目录改造记录见 MODS_ROOT_TDD_EVIDENCE.md。后端测试证据见 apps/api/TDD_EVIDENCE.md，前端测试证据见 apps/web/TDD_EVIDENCE.md，设置与识别改造记录见 SETTINGS_RECOGNITION_TDD_EVIDENCE.md。

安全边界

• 扫描本身只读，不修改 Mod；
• 换装仅移动选中的 Mod 文件夹；禁用目标统一位于 Disabled_Mods，目标重名时使用安全编号；
• 文件操作限定在配置的 Mods 根目录内；
• Wuwa Mod Fixer 仅在用户主动操作时运行；
• 自定义预览保存为 Mod 目录内的 wavewardrobe-preview.webp，切换状态或运行 Fixer 后仍会随 Mod 保留；
• Wuwa Mod Fixer 生成的 .BAK 文件不会作为 Mod 内容处理。

设计参考

本项目参考了以下项目的交互与工程思路，没有复制其源代码：

• r2modmanPlus：路径优先、对新手友好的启停设置；
• Limo：界面内容由实际扫描结果派生；
• OpenModMan：自定义路径作为一等设置、文件操作保持可逆；
• Vortex：用内容指纹辅助识别；
• No-Reload-Mod-Manager：WWMI 本地路径设置及临时文件替换思路。

角色头像来源

内置头像来自《鸣潮》游戏资源中的 IconRoleHead150，通过 encore.moe 的游戏数据接口获取，运行时不依赖网络。游戏内容及相关素材版权归库洛游戏所有。执行 scripts\sync-official-avatars.ps1 可按固定角色 ID 重新同步并校验 WebP 文件。

参与贡献

欢迎提交 Issue 和 Pull Request。提交代码前请运行 npm test 和 npm run build，并确保更改不会绕过上述文件操作安全边界。

许可证

源代码以 MIT License 开源。内置的《鸣潮》角色头像不在 MIT License 的授权范围内，其权利归原权利人所有。