YUN-SAN3 / KAMUCL

# KAMUCL
### ✦ 简约、开箱即用的 Minecraft Java 启动器 ✦
 把账号、实例、模组和启动按钮，收进一个清爽的小窗口里。 
愿每一次启动，都像打开一扇通往方块世界的传送门。 
## 🌸 功能一览
| 模块 | 说明 |
| --- | --- |
| 🎮 游戏实例 | 创建、删除、重命名、隔离实例，单独设置 Java 与启动参数 |
| 🧩 版本安装 | 安装原版、Fabric、Forge、NeoForge、Quilt |
| 🪪 账号中心 | 微软账号、离线账号、Yggdrasil 自定义认证 |
| 📦 资源管理 | 管理模组、资源包、光影、世界和服务器 |
| 🛠️ 实例管理中心 | 复制、备份、恢复实例，并查看运行诊断 |
| 🔎 社区资源 | 搜索并导入 Modrinth / CurseForge 资源 |
| 🧁 皮肤衣柜 | 角色预览、皮肤与披风上传、历史记录 |
| 🤝 联机 | FRP、VoxLink、Terracotta 和好友直连 |
| 🛠️ MOD 面板 | 通过 KAMUCL Bridge 实时读取与修改 MOD 参数 |
| ✨ 个性化 | 主题、背景、快捷键、插件和启动页缩略图 |
| 🩺 诊断 | 下载任务、日志导出、启动诊断、更新与回滚 |
> 完整的页面与业务模块关系见功能树，开发流程见开发指南。
> 好友直连的网络边界见 `docs/features/friend-direct-connect.md`。
## 📚 文档导航
| 文档 | 适合阅读时机 |
| --- | --- |
| 功能树 | 想了解页面、功能和代码模块的对应关系 |
| 开发指南 | 第一次搭建环境、开发功能或提交代码 |
| 提交规范 | Commit 标题、正文、类型前缀和 Pull Request |
| 好友直连说明 | 调试联机、端口映射和邀请流程 |
| Yggdrasil 提供商格式 | 接入或排查外置认证服务器 |
| 诊断记录 | 排查启动器、整合包和运行时问题 |
| 发布验收记录 | 查看历史版本变更与回归结果 |
| 对应源码 | 从发布包重建并核对源码 |
| 第三方许可 | 查看依赖许可证与源码说明 |
## 🚀 快速开始
### 直接运行（Windows）
Windows 便携版是单个 EXE，文件名会跟随 `package.json` 的版本号：
 [code] 
首次启动 Minecraft 前，请准备 Windows 10/11 64 位或支持的 macOS、与目标 Minecraft 版本匹配的 Java（现代版本通常需要 Java 17+）和网络连接。Windows ZIP 包解压后需保留同目录下的全部文件。
### 从源码运行
 [code] 
## 🧰 开发与构建
| 命令 | 用途 |
| --- | --- |
| `npm run dev` | 启动开发模式 |
| `npm run build` | 构建应用文件到 `out/` |
| `npm test` | 运行自动化测试 |
| `npm run dist` | 构建 Windows 便携版与 ZIP |
| `npm run dist:win` | 构建 Windows 便携版与 ZIP |
| `npm run dist:mac` | 构建 macOS ZIP |
| `npm run dist:all` | 构建全部已配置平台 |
| `npm run license:check` | 校验第三方依赖许可证文件 |
只生成 Windows 单文件 EXE：
 [code] 
产物输出到 `release/`。构建配置已启用最大压缩、仅保留中英文语言包，并排除 source map。
## 🤝 参与开发
代码协作采用 Fork、功能分支和 Pull Request。提交标题、正文、类型前缀与检查要求见提交规范；开发检查清单见开发指南。
### 🌉 构建 KAMUCL Bridge（可选）
Bridge 是给 Fabric 实例使用的本机桥接 MOD。需要 JDK 17+，并且本机已下载 Fabric Loader 与 Gson 依赖：
 [code] 
成功后会生成 `bridge/dist/kamucl-bridge-1.0.0.jar`。构建脚本会从固定的 Fabric Maven 和 Maven Central 地址下载并校验编译依赖；未生成时主程序仍可构建，只是 Bridge 页面无法自动提供内置 MOD。
## 🗂️ 项目地图
 [code] 
## 💾 数据、日志与隐私
启动器运行数据默认保存在 Windows 的 `%APPDATA%\KAMUCL`（macOS 为 `~/Library/Application Support/KAMUCL`），包括账号、设置、缓存和日志。反馈问题时，请先隐藏账号令牌、个人路径和公网 IP。
## ❓ 常见问题
 提示「electron-vite 未找到」 
在项目根目录执行 `npm install`，再重新运行命令。
 构建时提示 Bridge JAR 缺失 
这是可选组件提示。设置 `JAVA_HOME` 指向 JDK 后，执行 `node scripts/build-bridge.cjs` 即可。
 Windows SmartScreen 提示未知发布者 
默认构建未配置商业代码签名证书。确认文件来源后即可运行；正式发布建议配置 Windows 代码签名证书。
 Minecraft 无法启动 
检查实例 Java 路径、Minecraft 版本和加载器是否匹配，然后在“设置 → 诊断”中查看日志。
## 💌 许可证
本项目基于 MIT License 开源。
`Made with Vue · TypeScript · Electron` ✦ `祝你游戏愉快！`