feat(device,feedback): 新增设备识别码与意见反馈功能

重构意见反馈设置页面，替换原有占位内容，新增FeedbackButton组件
更新DEV.md与README.md文档，补充对应功能的相关说明

README.md

@@ -1,193 +1,614 @@
-# Koring Launcher
+<p align="center">
+  <img src="public/icons/run/icon.png" width="96" alt="Koring Launcher" />
+</p>
 
-Minecraft launcher built with Electron + React 19 + TypeScript + Node.js (@xmcl).
+<h1 align="center">Koring Launcher</h1>
+
+<p align="center">
+  A modern Minecraft launcher for Windows · 基于 Electron + React 的现代化 Minecraft 启动器
+</p>
+
+<p align="center">
+  <a href="https://github.com/dream-pep/koring-launcher/releases"><img src="https://img.shields.io/github/v/release/dream-pep/koring-launcher?display_name=release&label=Release&logo=github&color=4c6ef5" alt="Release"></a>
+  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-8a94a6" alt="Platform">
+  <img src="https://img.shields.io/badge/Electron%2033%20%C2%B7%20React%2019%20%C2%B7%20TypeScript-20242e" alt="Electron · React · TypeScript">
+  <img src="https://img.shields.io/badge/license-LL--1.0-7d5fb8" alt="License">
+  <a href="https://github.com/dream-pep/koring-launcher/actions/workflows/release.yml"><img src="https://github.com/dream-pep/koring-launcher/actions/workflows/release.yml/badge.svg" alt="Build & Release"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/dream-pep/koring-launcher"><img src="https://img.shields.io/github/stars/dream-pep/koring-launcher?style=social" alt="Stars"></a>
+</p>
+
+---
+
+# 中文文档
+
+- [项目简介](#项目简介)
+- [功能特性](#功能特性)
+- [界面预览](#界面预览)
+- [快速开始](#快速开始)
+- [开发指南](#开发指南)
+- [构建与发布](#构建与发布)
+- [技术架构](#技术架构)
+- [目录结构](#目录结构)
+- [版本与自动更新](#版本与自动更新)
+- [路线图](#路线图)
+- [贡献指南](#贡献指南)
+- [许可证](#许可证)
+
+---
+
+## 项目简介
+
+**Koring Launcher** 是一款面向现代 Windows 桌面的 Minecraft 启动器，采用
+**Electron + React 19 + TypeScript** 构建，游戏侧核心能力基于成熟的
+[@xmcl](https://github.com/Voxelum/xmcl) 开源生态（安装、启动、任务）。
+
+项目强调**流畅的桌面体验**与**工程化的进程架构**：自定义无边框窗口与启动画面、
+三层层级 UI、主进程权威的配置体系、内置资源注册表与内存管理，以及 beta/run 双通道
+自动更新。代码库以「渲染进程薄、主进程权威」为原则，所有游戏相关能力
+（@xmcl、文件系统、进程管理）均运行于 Electron 主进程，渲染进程只通过类型安全的
+IPC 与主进程通信。
+
+> **状态**：项目处于积极开发与内测阶段（`beta` / `run` 双通道发布）。主框架与核心
+> 流程稳定可用，部分 UI 模块（见 [路线图](#路线图)）仍在打磨。
+
+## 功能特性
+
+**桌面体验**
+
+- 自定义**无边框窗口**：自绘标题栏（毛玻璃）与窗口控制，深浅色模式自动适配
+- 独立的 **Splash 启动画面**（480×320 透明窗，无框架依赖，`ready-to-show` + 最短停留时间过渡）
+- **三层层级 UI**：背景层 / 内容层 / 系统层，页面间使用 View Transitions 过渡
+- 内置**隐藏调试页**（`debug-*` 路由）：显示、更新、任务、资源与内存等专项调试
+
+**游戏能力（基于 @xmcl）**
+
+- **统一配置驱动启动**：主进程读取权威配置，自动映射为 `LaunchOption`
+  （Java 路径 / 内存 / GC / JVM 参数 / 游戏参数 / 窗口 / 启动前命令），
+  支持启动事件推送与 `afterLaunch` 窗口处理
+- **Java 自动检测与路径校验**（`java:scan` / `java:resolve`）
+- **实例系统**：主库实例 + 游戏目录批量导入（幂等、目录变更自动重扫）
+- **Mod 生态**：Modrinth / CurseForge 检索与安装模块
+- **账号体系**：Koring 账号、离线账号（规范离线 UUID），微软 OAuth 核心已接入
+- 任务系统：安装 / 下载进度统一通过主进程任务队列（`task:*`）推进，UI 可查看队列
+
+**配置与个性化**
+
+- **主进程权威配置**：YAML（`Koring.yml`），深度合并 + 稀疏写盘 + 变更广播
+- **设置中心**（参考 PCL2 的分组结构）：游戏（账号 / Java / 目录 / 高级）、
+  个性化（主题背景 / 主界面 / 语言 / 无障碍）、网络（下载 / 安全识别）等均已接入
+- **背景系统**：颜色 / 渐变 / 模糊 / 自选壁纸；自选壁纸由主进程按屏幕尺寸降采样并
+  落盘存储，经 `koring-res://` 特权协议流式读取（**全程无 base64**），并纳入
+  **资源注册表**统一管理（引用计数、预算 + LRU 逐出）
+- **引导流程**：首次启动 OOBE 向导（语言 / 协议 / 登录 / 版本）与更新后引导（UPvP），
+  「关于此版本」将 GitHub Release Notes 按新增 / 修复 / 优化等**分类卡片化**展示
+- **意见反馈**：设置 → 服务与反馈内置 HeroUI 反馈按钮，点击在系统浏览器打开 YouTrack 反馈表单
+  （`components/feedback/FeedbackButton`，直链 `lingke.youtrack.cloud/form/<uuid>`）
+- **设备识别码**：关于页展示设备唯一标识 —— 由硬件指纹（主板 UUID / 硬盘序列号 / BIOS 序列号，过滤 OEM 占位值）
+  优先取源，缺失时回退注册表 `MachineGuid`，经 SHA-256 生成 UUID 样式标识（`electron/core/device-id.ts`，进程内缓存）
+
+## 界面预览
+
+> 截图整理中 —— 欢迎将截图放入 `docs/screenshots/` 后在此展示。
+
+<!--
+  示例：
+  <img src="docs/screenshots/home.png" width="720" alt="主界面" />
+-->
+
+## 快速开始
+
+**面向用户**：从 [GitHub Releases](https://github.com/dream-pep/koring-launcher/releases)
+下载最新安装包（NSIS 安装器，可自选安装目录）。目前发布管线产出 Windows 安装程序，
+macOS（DMG）与 Linux（AppImage）构建目标已配置，将在 CI 中逐步开放。
+
+**开发环境要求**
+
+| 依赖 | 版本 | 说明 |
+| --- | --- | --- |
+| OS | Windows 10/11（x64） | 主要开发与目标平台 |
+| Node.js | ≥ 20.19（CI 使用 22） | Vite 7 要求 |
+| pnpm | ≥ 9（CI 使用 11.7） | 包管理器，仓库基于 pnpm workspace |
+
+> 国内网络环境：仓库 `.npmrc` 已配置 Electron 二进制走 npmmirror 镜像，
+> 可避免 Electron 下载超时。
+
+```bash
+# 安装依赖
+pnpm install
+
+# 开发（完整应用：Vite dev server :1420 + Electron）
+pnpm dev
+
+# 仅渲染进程（HMR，端口 1420）/ 仅主进程
+pnpm dev:renderer
+pnpm dev:main
+```
+
+## 开发指南
+
+常用脚本一览（完整说明见 `DEV.md` 与 `AGENTS.md`）：
+
+| 命令 | 说明 |
+| --- | --- |
+| `pnpm dev` | 完整开发环境（先编译主进程，再并行启动 Vite + Electron） |
+| `pnpm dev:renderer` | 仅渲染进程（Vite HMR，端口 1420） |
+| `pnpm dev:main` | 仅主进程（`tsc` 编译后启动 Electron） |
+| `pnpm build:renderer:{dev,beta,run}` | 按模式构建渲染进程 |
+| `pnpm build:main` | 编译主进程 TypeScript |
+| `pnpm build:{dev,beta,run}` | 对应模式的完整构建（渲染进程 + 主进程） |
+| `pnpm preview` | 预览 Vite 产物 |
+| `pnpm version:set` | 设置版本号（单一事实源为 `package.json`） |
+| `pnpm pack` | `electron-builder --dir`（未打包目录产物） |
+| `pnpm dist` / `dist:win` / `dist:mac` / `dist:linux` | electron-builder 按目标平台打包 |
+
+**开发要点速览**
+
+- `@/` 路径别名映射到 `src/`（同时配置于 `vite.config.ts` 与 `tsconfig.json`）
+- 渲染进程公共资源路径须使用 `import.meta.env.BASE_URL` 前缀（打包后绝对路径失效）
+- 所有 `@xmcl/*`、文件系统与子进程能力运行于主进程；渲染进程经
+  `ipcRenderer.invoke()` → `ipcMain.handle()` 调用，方向性事件经 `webContents.send()` 推送
+- 主进程配置为唯一权威：渲染端只提交补丁，不直接写盘（详见「配置存储」）
+- HeroUI 3（基于 react-aria）控件使用 `onChange`，`onValueChange` 已移除
+- 窗口拖拽需使用内联样式 `WebkitAppRegion: "drag"`（Electron 仅识别 CSS 属性）
+
+## 构建与发布
+
+### 构建模式
+
+项目支持三种构建模式，通过环境文件（`.env.development` / `.env.beta` /
+`.env.production`）注入，并配套**切换图标**（exe / 安装器图标随模式不同）：
+
+| 模式 | Vite mode | 图标目录 | 用途 |
+| --- | --- | --- | --- |
+| `dev` | `development` | `public/icons/dev/` | 日常开发 |
+| `beta` | `beta` | `public/icons/beta/` | 内测发布 |
+| `run` | `production` | `public/icons/run/` | 正式发布 |
+
+```bash
+pnpm dist:dev    # build:dev  →  icon:dev  →  electron-builder --win
+pnpm dist:beta   # build:beta →  icon:beta →  electron-builder --win
+pnpm dist:run    # build:run  →  icon:run  →  electron-builder --win
+```
+
+打包流程：模式构建 → `scripts/switch-icon.js` 将对应图标复制到 `build/`
+（electron-builder 的 `buildResources`）→ electron-builder 产出 NSIS 安装程序，
+产物位于 `dist-electron/koring-launcher-{version}-setup.exe`。
+
+### 发布流水线（GitHub Actions）
+
+`.github/workflows/release.yml` 手动触发（选择 `beta` / `run` 模式）：
+
+1. 从 `package.json` 读取基础版本号，附加 **BUILD ID**（GitHub Run Number，
+   严格递增）生成最终版本：`{base}-beta.{buildId}`（beta）或 `{base}-{buildId}`（run）
+2. `pnpm build:{mode}` + `pnpm icon:{mode}`（renderer + main + 图标）
+3. `electron-builder --win`，经 **SignPath 远程签名**（无 `SIGNPATH_API_TOKEN`
+   时自动跳过，本地构建不受影响；仅对 sha256 签名以节省配额）
+4. 生成中文发布说明并发布 GitHub Release：beta 为 prerelease 并额外上传
+   `latest-beta.yml`，run 为正式版并上传 `latest.yml`（electron-updater 更新清单）
+
+### 配置存储（主进程权威）
+
+- **`Koring.yml`**：打包后存 `app.getPath('userData')`（`%APPDATA%/Koring Launcher/`），
+  开发模式存项目根目录；旧版 exe 旁文件首次启动自动迁移
+- 主进程内存缓存为唯一权威：渲染端经 `config:update` 提交补丁 → 主进程深度合并 →
+  300ms debounce **稀疏写盘**（仅写非默认值）→ 广播 `config:changed` 同步渲染端镜像
+- **`koring-auth.json`**（账号数据）与崩溃日志采用相同存储策略
+- ⚠️ 数据文件不可放入安装目录：NSIS 重装 / 升级会经旧卸载器删除整个安装目录
+
+## 技术架构
+
+```
+┌────────────────────────── Renderer (React 19) ─────────────────────────┐
+│  pages / components / stores (Zustand)        resources (注册表+LRU)   │
+│        │ ipcRenderer.invoke()  ▲ ipcMain.handle()                      │
+│        ▼                      │ webContents.send() (方向性事件)         │
+├────────────────────────── Main Process (Electron / Node) ──────────────┤
+│  handlers/*  ──  config.ts (YAML 权威) · auth.ts · updater.ts           │
+│  core/*      ──  @xmcl/core · @xmcl/installer · @xmcl/task             │
+│                  launch-options (配置→LaunchOption)                    │
+│  resource-protocol.ts  koring-res://（白名单流式读取，realpath 校验）    │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+- **IPC 流**：渲染进程 `invoke` → 主进程 `handle` → 处理完成返回；主进程主动事件
+  经 `webContents.send` 推送给渲染端（如 `config:changed`、`launch:event`）
+- **可变的 `win` 引用**：`main.ts` 使用可变 `win` 对象，各 handler 在运行时读取
+  `win.mainWindow`，而非注册时捕获
+- **`koring-res://`**：特权自定义协议，仅服务 userData 内
+  `background-custom*` 白名单文件（realpath 二次校验，防目录穿越），
+  用于渲染进程「按引用」流式读取本地壁纸，避免 base64 膨胀内存
+- **背景图处理**：自选壁纸由主进程复制到 userData，并按屏幕尺寸降采样 / 重编码
+  **落盘**；配置文件只存文件路径
+- **资源注册表**（`src/resources/`）：acquire / release 引用计数、预算 + LRU 逐出、
+  onRelease 释放回调；图片按显示尺寸降采样，供列表缩略图复用
+
+## 目录结构
+
+```
+koring-launcher/
+├─ electron/                  # 主进程（Electron，@xmcl 全部运行于此）
+│  ├─ main.ts                 # 入口：窗口管理、splash→主界面过渡
+│  ├─ preload.ts              # contextBridge 暴露 window.electronAPI
+│  ├─ config.ts               # YAML 配置（权威、稀疏写盘、迁移）
+│  ├─ auth.ts · updater.ts · resource-protocol.ts
+│  ├─ core/                   # @xmcl 集成与业务核心
+│  │  ├─ auth.ts · koring-auth.ts · installer.ts · launcher.ts
+│  │  ├─ launch-options.ts · modrinth.ts · instance.ts
+│  │  ├─ task.ts · paths.ts · background-image.ts · crash-logger.ts
+│  └─ handlers/               # IPC 处理器（config/auth/install/launch/java/
+│                             #   mods/instance/background/task/system/update/
+│                             #   koring-auth/crash-monitor/window）
+├─ src/                       # 渲染进程（React 19）
+│  ├─ api/                    # IPC 类型封装
+│  ├─ components/             # background/ system/ setting/ task/
+│  │                          #   about-version/ ui/ (shadcn) …
+│  ├─ pages/                  # home · gallery · store · today · play-link ·
+│  │                          #   setting(分组子页) · oobe · upvp · update ·
+│  │                          #   task-queue · crash · debug
+│  ├─ resources/              # 资源注册表（引用计数/预算/LRU）与图片解码管线
+│  ├─ stores/                 # Zustand 状态（config/auth/theme/route/launch…）
+│  ├─ layouts/ · hooks/ · lib/ (mode/buildInfo/version) · assets/ · types/
+│  ├─ App.tsx · main.tsx · index.css
+├─ public/                    # 静态资源：icons/{dev,beta,run}/、背景、字体
+├─ scripts/                   # switch-icon · version · gen-build-info ·
+│                             #   signpath-sign · release-notes …
+├─ docs/ · DEV.md · AGENTS.md # 开发文档与仓库约定
+├─ electron-builder.yml       # appId / 打包目标 / NSIS / 签名配置
+├─ vite.config.ts · tsconfig*.json · .env.{development,beta,production}
+└─ package.json               # 版本单一事实源
+```
+
+## 版本与自动更新
+
+- **版本单一事实源**：`package.json` 的 `version` 字段（`scripts/version.js`
+  `get` / `set`），本地与 CI 共用，消除双轨
+- **版本号格式**：`{base}`（package.json）→ 发布时追加构建号
+  `{base}-beta.{buildId}`（beta 通道）/ `{base}-{buildId}`（run 通道）
+- **自动更新**：`electron-updater` + GitHub provider；run 通道读 `latest.yml`，
+  beta 通道读 `latest-beta.yml`；客户端开启 `allowPrerelease` 以接收带构建号的
+  beta 更新
+- ⚠️ 若切换构建号方案（时间戳 → Run Number），旧版数值更大，老用户不会自动
+  升级，需同步提升 base 版本（详见 `docs/auto-update-plan.md`）
+
+## 路线图
+
+- [ ] **实例中心 / 资源中心 UI**：完整实现已就绪，暂以占位页收尾打磨后放开
+      （Minecraft 版本 / Mod / 整合包浏览与安装）
+- [ ] **微软账号登录 UI**：OAuth / Xbox / Minecraft 认证核心已接入，入口 UI 完善中
+- [ ] **以太 / 陶瓦联机页**：目前为占位
+- [ ] macOS（DMG）与 Linux（AppImage）CI 发布产物
+- [ ] 多语言（`app.language` 偏好已定义，UI 文案逐步外置）
+
+## 贡献指南
+
+欢迎提交 Issue 与 Pull Request：
+
+1. Fork 本仓库并以 `master` 为基线创建功能分支
+2. 遵循仓库现有风格（TypeScript 严格模式、组件/处理器分层），
+   提交信息建议使用约定式（`feat:` / `fix:` / `docs:` / `refactor:` …）
+3. 修改渲染进程前先阅读 [AGENTS.md](AGENTS.md)（架构约束与注意点）
+   与 [DEV.md](DEV.md)（开发说明）
+4. 涉及图标 / 安装器的改动请分别验证三种构建模式（`dist:dev/beta/run`）
+
+## 许可证
+
+本项目使用自定义 **LingkeLice 1.0（LL-1.0）** 许可证，版权归
+**Shenzhen Lingke Network Technology Co., Ltd.（深圳灵科网络科技有限公司）** 所有。
+要点：**非商业用途**可自由使用、复制、修改与分发（含并入其他项目）；任何
+**商业用途**（含集成进商业产品、商业化提供服务、直接 / 间接获利）须事先获得
+版权所有者的**书面授权**。详见 [LICENSE](LICENSE)。
+
+商业授权请联系 Shenzhen Lingke Network Technology Co., Ltd.
+
+---
+
+# English Version
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Screenshots](#screenshots)
+- [Quick Start](#quick-start)
+- [Development](#development)
+- [Build & Release](#build--release)
+- [Architecture](#architecture)
+- [Project Structure](#project-structure)
+- [Versioning & Auto-Update](#versioning--auto-update)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Introduction
+
+**Koring Launcher** is a modern Minecraft launcher for Windows built with
+**Electron + React 19 + TypeScript**, with game-side capabilities powered by the
+mature [@xmcl](https://github.com/Voxelum/xmcl) ecosystem (install, launch, task).
+
+The project favors a *thin renderer, authoritative main process* architecture:
+game-related features (@xmcl, filesystem, subprocesses) all run in the Electron
+main process, while the renderer talks to it only through type-safe IPC. Notable
+engineering practices include a custom frameless window and splash screen,
+a three-layer UI model, main-process-authoritative configuration, a built-in
+resource registry with memory management, and dual-channel (beta/run) auto-update.
+
+> **Status**: under active development with public beta/run releases. The core
+> framework and main flows are stable; a few UI modules are being polished
+> (see [Roadmap](#roadmap)).
+
+## Features
+
+**Desktop experience**
+
+- Custom **frameless window**: glassmorphism title bar and window controls,
+  automatic dark/light mode
+- Standalone **splash screen** (480×320 transparent window, dependency-free,
+  `ready-to-show` + minimum-duration transition)
+- **Three-layer UI** (background / content / system) with View Transitions
+- Hidden **debug pages** (`debug-*` routes) for display, update, task, and
+  resource/memory inspection
+
+**Game capabilities (via @xmcl)**
+
+- **Config-driven unified launch**: the main process maps authoritative config
+  to `LaunchOption` (Java path, memory, GC, JVM args, window, pre-launch
+  commands), with launch event streaming and `afterLaunch` window handling
+- **Java auto-detection & validation** (`java:scan` / `java:resolve`)
+- **Instance system**: instances in the main library + bulk import from an
+  existing game directory (idempotent, auto-rescan on directory change)
+- **Mod ecosystem**: Modrinth / CurseForge search & install modules
+- **Accounts**: Koring account, offline login (spec-compliant offline UUID),
+  Microsoft OAuth core integrated
+- **Task system**: install / download progress flows through a main-process
+  task queue (`task:*`) with a visible UI queue
+
+**Configuration & personalization**
+
+- **Main-process-authoritative config**: YAML (`Koring.yml`), deep merge +
+  sparse save + change broadcast
+- **Settings center** (PCL2-inspired groups): game (account / Java / directory /
+  advanced), personalization (theme & background / UI / language / a11y),
+  network (download / security ID), etc.
+- **Background system**: color / gradient / blur / custom wallpaper. Custom
+  wallpapers are downsampled to screen size and stored **on disk** by the main
+  process, streamed via the privileged `koring-res://` protocol (**no base64**),
+  and managed by a **resource registry** (ref-counting, budget + LRU eviction)
+- **Onboarding flows**: first-launch OOBE wizard (language / agreement / login /
+  version) and post-update wizard (UPvP); “About this version” renders GitHub
+  release notes as categorized cards (added / fixed / improved / …)
+
+## Screenshots
+
+> Coming soon — contributions welcome: drop screenshots into `docs/screenshots/`
+> and reference them here.
+
+<!--
+  e.g. <img src="docs/screenshots/home.png" width="720" alt="Home" />
+-->
 
 ## Quick Start
 
+**End users**: download the latest installer from
+[GitHub Releases](https://github.com/dream-pep/koring-launcher/releases) (NSIS,
+custom install directory). The release pipeline currently publishes Windows
+setups; macOS (DMG) and Linux (AppImage) targets are configured and will be
+opened up in CI gradually.
+
+**Development requirements**
+
+| Dependency | Version | Notes |
+| --- | --- | --- |
+| OS | Windows 10/11 (x64) | Primary development & target platform |
+| Node.js | ≥ 20.19 (CI uses 22) | Required by Vite 7 |
+| pnpm | ≥ 9 (CI uses 11.7) | Package manager (pnpm workspace) |
+
+> In China, `.npmrc` already redirects Electron binaries to the npmmirror
+> mirror to avoid download timeouts.
+
 ```bash
 pnpm install
-pnpm dev                # full app (frontend + electron)
-pnpm dev:renderer       # frontend only (vite, port 1420)
-pnpm dev:main           # electron main process only
+
+# Full app dev (Vite :1420 + Electron)
+pnpm dev
+pnpm dev:renderer   # renderer only (HMR, port 1420)
+pnpm dev:main       # main process only
 ```
 
-## Build
+## Development
+
+Common scripts (full details in `DEV.md` and `AGENTS.md`):
+
+| Command | Description |
+| --- | --- |
+| `pnpm dev` | Full dev environment (compile main, then Vite + Electron) |
+| `pnpm dev:renderer` | Renderer only (Vite HMR, port 1420) |
+| `pnpm dev:main` | Main process only (`tsc` then launch Electron) |
+| `pnpm build:renderer:{dev,beta,run}` | Build renderer for a mode |
+| `pnpm build:main` | Compile main-process TypeScript |
+| `pnpm build:{dev,beta,run}` | Full build for a mode (renderer + main) |
+| `pnpm preview` | Preview the Vite build |
+| `pnpm version:set` | Set the version (`package.json` is the single source) |
+| `pnpm pack` | `electron-builder --dir` (unpacked output) |
+| `pnpm dist` / `dist:win` / `dist:mac` / `dist:linux` | Package for a target |
+
+**Quick notes**
+
+- `@/` maps to `src/` (in both `vite.config.ts` and `tsconfig.json`)
+- Public assets in the renderer must use the `import.meta.env.BASE_URL` prefix
+  (absolute paths break when packaged)
+- All `@xmcl/*`, filesystem and subprocess code lives in the main process; the
+  renderer calls via `ipcRenderer.invoke()` → `ipcMain.handle()`, and
+  directional events are pushed with `webContents.send()`
+- Main-process config is authoritative — the renderer submits patches, never
+  writes files directly
+- HeroUI 3 (built on react-aria) controls use `onChange` (`onValueChange`
+  no longer exists)
+- Window dragging requires the inline style `WebkitAppRegion: "drag"`
+  (Electron only honors the CSS property)
+
+## Build & Release
+
+### Build modes
+
+Three build modes are driven by env files (`.env.development` / `.env.beta` /
+`.env.production`) and each ships its **own icon set** for the exe and
+installer:
+
+| Mode | Vite mode | Icon dir | Purpose |
+| --- | --- | --- | --- |
+| `dev` | `development` | `public/icons/dev/` | Daily development |
+| `beta` | `beta` | `public/icons/beta/` | Beta release |
+| `run` | `production` | `public/icons/run/` | Production release |
 
 ```bash
-pnpm build              # production build (vite + tsc)
-pnpm dist:dev           # dev icon + Windows installer
-pnpm dist:beta          # beta icon + Windows installer
-pnpm dist:run           # production icon + Windows installer
-pnpm dist:mac           # build macOS DMG
-pnpm dist:linux         # build Linux AppImage
+pnpm dist:dev    # build:dev  →  icon:dev  →  electron-builder --win
+pnpm dist:beta   # build:beta →  icon:beta →  electron-builder --win
+pnpm dist:run    # build:run  →  icon:run  →  electron-builder --win
 ```
 
+Pipeline: mode build → `scripts/switch-icon.js` copies the mode icons into
+`build/` (electron-builder’s `buildResources`) → electron-builder produces an
+NSIS installer at `dist-electron/koring-launcher-{version}-setup.exe`.
+
+### Release pipeline (GitHub Actions)
+
+`.github/workflows/release.yml` is triggered manually with a `beta` / `run` mode:
+
+1. Read the base version from `package.json`, append a **BUILD ID**
+   (GitHub Run Number, strictly increasing): `{base}-beta.{buildId}` (beta) or
+   `{base}-{buildId}` (run)
+2. `pnpm build:{mode}` + `pnpm icon:{mode}`
+3. `electron-builder --win` with **SignPath remote signing** (auto-skipped when
+   `SIGNPATH_API_TOKEN` is absent; sha256-only to save quota)
+4. Generate Chinese release notes and publish a GitHub Release: beta releases
+   are prereleases that also upload `latest-beta.yml`; run releases are stable
+   and upload `latest.yml` (the electron-updater manifest)
+
+### Config storage (main-process authoritative)
+
+- **`Koring.yml`**: stored under `app.getPath('userData')`
+  (`%APPDATA%/Koring Launcher/`) when packaged, or in the project root in dev;
+  legacy files next to the old exe are auto-migrated on first launch
+- The in-memory cache in the main process is the single source of truth:
+  renderer submits a patch via `config:update` → deep merge → 300 ms debounced
+  **sparse write** (non-default values only) → broadcast `config:changed`
+- **`koring-auth.json`** (account data) and crash logs follow the same policy
+- ⚠️ Never store data files inside the install directory: NSIS reinstall /
+  upgrade removes the whole directory via the old uninstaller
+
 ## Architecture
 
 ```
-src/                     Frontend (React 19 + Vite 7 + Tailwind v4 + shadcn/ui + Zustand)
-electron/                Main process (Node.js/TypeScript, @xmcl/* packages)
-public/                  Static assets (icons, fonts, images)
-build/                   Build resources (generated, gitignored)
+┌────────────────────────── Renderer (React 19) ─────────────────────────┐
+│  pages / components / stores (Zustand)        resources (registry+LRU) │
+│        │ ipcRenderer.invoke()  ▲ ipcMain.handle()                      │
+│        ▼                      │ webContents.send() (directional)        │
+├────────────────────────── Main Process (Electron / Node) ──────────────┤
+│  handlers/*  ──  config.ts (YAML authority) · auth.ts · updater.ts      │
+│  core/*      ──  @xmcl/core · @xmcl/installer · @xmcl/task             │
+│                  launch-options (config → LaunchOption)                │
+│  resource-protocol.ts  koring-res:// (whitelist streaming, realpath)    │
+└────────────────────────────────────────────────────────────────────────┘
 ```
 
-**IPC Flow:**
-Frontend → `ipcRenderer.invoke()` → `ipcMain.handle()` → main process → `webContents.send()` → Frontend
-
-**Config storage (main-process authoritative):**
-- `Koring.yml` — 打包后存 `app.getPath('userData')`（`%APPDATA%/Koring Launcher/`），开发模式在项目根目录；旧版 exe 旁文件首次启动自动迁移
-- 主进程内存缓存为唯一权威：渲染进程通过 `config:update` 提交补丁，主进程深度合并 → 300ms debounce 稀疏写盘 → 广播 `config:changed` 同步渲染端镜像
-- `koring-auth.json` / `koring-crash.log` 与配置同策略（打包后 userData）
+- **IPC flow**: renderer `invoke` → main `handle` → result returns; the main
+  process pushes directional events (e.g. `config:changed`, `launch:event`)
+  via `webContents.send`
+- **Mutable `win` reference**: `main.ts` keeps a mutable `win` object, and
+  handlers read `win.mainWindow` at runtime instead of capture time
+- **`koring-res://`**: privileged custom protocol serving only whitelisted
+  `background-custom*` files inside userData (realpath double-check against
+  path traversal) so the renderer can stream local wallpapers by reference
+- **Wallpaper pipeline**: custom wallpapers are copied into userData,
+  downsampled/re-encoded to screen size and written **to disk**; the config
+  stores only the file path
+- **Resource registry** (`src/resources/`): acquire/release ref-counting,
+  budget + LRU eviction, onRelease callbacks; images are decoded at display
+  size and shared by list thumbnails
 
 ## Project Structure
 
 ```
-src/
-├── api/                  # Frontend API layer (IPC wrappers)
-│   ├── ipc.ts            # Core IPC utilities
-│   ├── background.ts     # Background control
-│   ├── install.ts        # Minecraft install
-│   ├── launch.ts         # Game launch
-│   ├── auth.ts           # Microsoft/offline auth
-│   ├── mods.ts           # Modrinth/CurseForge
-│   └── instance.ts       # Instance management
-├── stores/               # Zustand state stores
-├── components/
-│   ├── background/       # Background layer (z-0)
-│   ├── system/           # Title bar + window controls (z-100)
-│   └── ui/               # shadcn/ui components
-├── layouts/
-│   └── RootLayout.tsx    # Three-layer page structure
-├── pages/
-│   ├── Home.tsx          # Main page
-│   └── Debug.tsx         # Debug tools
-├── lib/
-│   ├── mode.ts           # Build mode constants (DEFAULT_BG, LOGO_SVG, APP_ICON)
-│   └── utils.ts          # cn() helper
-└── App.tsx               # Root component with state router
-
-electron/
-├── main.ts               # Electron entry, window management, splash→main transition
-├── preload.ts            # Context bridge (window.electronAPI)
-├── config.ts             # YAML config management (main-process authoritative, debounce sparse save)
-├── auth.ts               # Auth data persistence
-├── core/                 # @xmcl/* integrations
-│   ├── auth.ts           # Microsoft OAuth, Xbox Live, MC auth
-│   ├── installer.ts      # @xmcl/installer
-│   ├── launcher.ts       # Unified game launcher (@xmcl/core launch + config-driven)
-│   ├── launch-options.ts # Config → LaunchOption mapping (parseArgs/buildLaunchOptions/resolveJavaPath)
-│   ├── modrinth.ts       # Modrinth/CurseForge API
-│   └── instance.ts       # Instance management
-├── handlers/             # IPC handlers
-│   ├── config.ts         # Config load/save/update (config:get/update/save + config:changed broadcast)
-│   ├── auth.ts           # Auth operations
-│   ├── install.ts        # Install operations
-│   ├── launch.ts         # Unified game launch (launch:launch / launch:diagnose + afterLaunch)
-│   ├── java.ts           # Java detection (java:scan / java:resolve)
-│   ├── mods.ts           # Mod operations
-│   ├── instance.ts       # Instance operations
-│   ├── background.ts     # Background operations
-│   ├── task.ts           # Task system
-│   ├── system.ts         # System info
-│   └── window.ts         # Window controls + splash management
-└── types/
-    └── electron.d.ts     # TypeScript declarations
+koring-launcher/
+├─ electron/                  # Main process (all @xmcl code runs here)
+│  ├─ main.ts                 # Entry: windows, splash → main transition
+│  ├─ preload.ts              # contextBridge → window.electronAPI
+│  ├─ config.ts               # YAML config (authoritative, sparse save, migrate)
+│  ├─ auth.ts · updater.ts · resource-protocol.ts
+│  ├─ core/                   # @xmcl integrations & business core
+│  │  ├─ auth.ts · koring-auth.ts · installer.ts · launcher.ts
+│  │  ├─ launch-options.ts · modrinth.ts · instance.ts
+│  │  ├─ task.ts · paths.ts · background-image.ts · crash-logger.ts
+│  └─ handlers/               # IPC handlers (config/auth/install/launch/java/
+│                             #   mods/instance/background/task/system/update/
+│                             #   koring-auth/crash-monitor/window)
+├─ src/                       # Renderer (React 19)
+│  ├─ api/                    # Typed IPC wrappers
+│  ├─ components/             # background/ system/ setting/ task/
+│  │                          #   about-version/ ui/ (shadcn) …
+│  ├─ pages/                  # home · gallery · store · today · play-link ·
+│  │                          #   setting (grouped subpages) · oobe · upvp ·
+│  │                          #   update · task-queue · crash · debug
+│  ├─ resources/              # Resource registry (ref-count/budget/LRU) +
+│  │                          #   image decode pipeline
+│  ├─ stores/                 # Zustand (config/auth/theme/route/launch…)
+│  ├─ layouts/ · hooks/ · lib/ (mode/buildInfo/version) · assets/ · types/
+│  ├─ App.tsx · main.tsx · index.css
+├─ public/                    # Static assets: icons/{dev,beta,run}/, bg, fonts
+├─ scripts/                   # switch-icon · version · gen-build-info ·
+│                             #   signpath-sign · release-notes …
+├─ docs/ · DEV.md · AGENTS.md # Docs & repository conventions
+├─ electron-builder.yml       # appId / targets / NSIS / signing
+├─ vite.config.ts · tsconfig*.json · .env.{development,beta,production}
+└─ package.json               # Single source of truth for the version
 ```
 
-## Three-Layer Page Structure
+## Versioning & Auto-Update
 
-```
-┌──────────────────────────────────────┐
-│  z-index: 100  System Layer          │  pointer-events: none
-│  ┌──────────────────────────────┐    │
-│  │ TitleBar (frosted glass)     │    │  pointer-events: auto
-│  │ WindowControls (25px btns)   │    │
-│  └──────────────────────────────┘    │
-├──────────────────────────────────────┤
-│  z-index: 1   Content Layer          │  pointer-events: auto
-│  All page content                    │
-├──────────────────────────────────────┤
-│  z-index: 0   Background Layer       │  pointer-events: none
-│  Image / color / gradient / blur     │
-└──────────────────────────────────────┘
-```
+- **Single source of truth**: the `version` field in `package.json`
+  (`scripts/version.js` `get`/`set`) shared by local builds and CI
+- **Version format**: `{base}` (package.json) gains a build suffix at release
+  time: `{base}-beta.{buildId}` (beta) / `{base}-{buildId}` (run)
+- **Auto-update**: `electron-updater` with the GitHub provider; run reads
+  `latest.yml`, beta reads `latest-beta.yml`; the client enables
+  `allowPrerelease` so suffixed beta builds are detected
+- ⚠️ Switching the build-ID scheme (timestamp → Run Number) makes old versions
+  numerically larger; raise the base version at the same time or old clients
+  will not upgrade (details: `docs/auto-update-plan.md`)
 
-## Splash Screen
+## Roadmap
 
-- Standalone HTML/CSS (`splash.html`), no React/Vite dependency
-- Loads instantly while Vite dev server starts
-- Window: 480×320, no decorations, transparent, locked size
-- Auto-adapts to system dark mode (`prefers-color-scheme`)
-- Logo: `filter: invert(1)` in dark mode
-- Startup: splash shows first → main loads behind → transition after `ready-to-show` + 1.5s minimum
+- [ ] **Instance center / Resource center UI**: full implementations are ready
+      but temporarily behind placeholder pages (Minecraft versions / mods /
+      modpacks browse & install)
+- [ ] **Microsoft account login UI**: OAuth / Xbox / Minecraft auth core is
+      integrated; UI entry is being polished
+- [ ] **Ether / Tawa online play pages**: currently placeholders
+- [ ] macOS (DMG) and Linux (AppImage) CI artifacts
+- [ ] i18n rollout (`app.language` preference is defined; UI strings are being
+      externalized)
 
-## Icon System
+## Contributing
 
-Three icon variants in `public/icons/`:
+Issues and pull requests are welcome:
 
-```
-public/icons/
-  dev/icon.ico, icon.png    # Development
-  beta/icon.ico, icon.png   # Testing
-  run/icon.ico, icon.png    # Production release
-```
+1. Fork the repository and branch from `master`
+2. Follow the existing style (strict TypeScript, layered components/handlers);
+   prefer conventional commits (`feat:` / `fix:` / `docs:` / `refactor:` …)
+3. Before touching the renderer, read [AGENTS.md](AGENTS.md) (architecture
+   constraints) and [DEV.md](DEV.md) (development notes)
+4. Icon / installer changes should be verified across all three build modes
+   (`dist:dev/beta/run`)
 
-**Build-time switching:**
-```bash
-pnpm icon:dev    # copies public/icons/dev/ → build/
-pnpm icon:beta   # copies public/icons/beta/ → build/
-pnpm icon:run    # copies public/icons/run/ → build/
-```
+## License
 
-`electron-builder.yml` reads icons from `build/` (`buildResources: build`).
+This project is licensed under the custom **LingkeLice 1.0 (LL-1.0)**, ©
+**Shenzhen Lingke Network Technology Co., Ltd.** In short: **non-commercial
+use** (use, copy, modify, distribute, including incorporation into other
+projects) is free; any **commercial use** — integrating into commercial
+products, providing paid services, or earning direct/indirect revenue — requires
+**prior written authorization** from the copyright holder. See
+[LICENSE](LICENSE).
 
-**Frontend usage:**
-```tsx
-import { APP_ICON, DEFAULT_BG, LOGO_SVG, BUILD_MODE, isDev } from "@/lib/mode";
-
-<img src={APP_ICON} />
-<img src={LOGO_SVG} />
-<img src={DEFAULT_BG} />
-{isDev && <span>Dev Mode</span>}
-```
-
-## IPC Handlers
-
-- `config:get` / `config:update` / `config:save` / `config:changed` — 配置读写（主进程权威：update 深度合并 + debounce 稀疏写盘 + 广播）
-- `auth:*` — Microsoft OAuth, offline login
-- `install:*` — Minecraft install, mod loader, version lists
-- `launch:launch` / `launch:diagnose` — 统一游戏启动：主进程读取权威配置自动应用 Java/内存/GC/JVM/游戏参数/窗口/启动前命令，事件经 `launch:event` 推送，window-ready 时按 `afterLaunch` 处理启动器窗口
-- `java:scan` / `java:resolve` — Java 环境检测 / 路径校验
-- `mods:*` — Modrinth/CurseForge search, install
-- `instance:*` — Instance CRUD（安装/导入/诊断；启动统一走 `launch:launch`）
-- `background:*` — Background image/color/blur/animation/theme
-- `task:*` — Task system progress
-- `system:*` — System info
-- `window:*` — Minimize/maximize/close + splash management
-- `dialog:*` — File picker
-
-## Key Gotchas
-
-- **@xmcl packages run in main process**: `@xmcl/core`, `@xmcl/installer` require `fs`/`child_process`. All run in Electron main process.
-- **Path alias**: `@/` maps to `src/`.
-- **Window dragging**: Use CSS `WebkitAppRegion: "drag"` as inline style (Electron only respects CSS property, not HTML attributes).
-- **Transparent windows**: `transparent: true` + `frame: false` in BrowserWindow options.
-- **Mutable win ref**: `electron/main.ts` uses a mutable `win` object — all handlers read `win.mainWindow` at runtime (not captured at registration time).
-- **Asset paths**: Use `import.meta.env.BASE_URL` prefix for public assets (e.g., `${import.meta.env.BASE_URL}background.png`). Absolute paths like `/background.png` break in packaged app.
-- **Config**: YAML format (`Koring.yml`). 打包后存 `app.getPath('userData')`（开发模式在项目根目录）；主进程内存缓存为唯一权威，渲染进程经 `config:update` 提交、`config:changed` 同步，不在渲染端直接写盘。Sparse save（只写非默认值）。
-- **Auth**: JSON file (`koring-auth.json`)，打包后存 userData（与配置同策略）。
-- **Launch is config-driven**: `launch:launch` 由主进程读取权威配置映射为 `@xmcl/core` 的 `LaunchOption`（`buildLaunchOptions`），前端只传实例名 + 游戏根目录 + 账户档案。
-- **HeroUI 3 基于 react-aria**：Switch / RadioGroup 等使用 `onChange`（不是 `onValueChange`），`onValueChange` 在 HeroUI 3 中不存在且静默失效。
-- **设置子页面统一原语**：`src/components/setting/`（SettingCard/SettingRow/SettingBadge/SettingListItem/controls.tsx + `fieldCls`），一套样式组合；Radio 必须显式渲染 `<Radio.Control><Radio.Indicator /></Radio.Control>` 才有圆点；HeroUI field 默认边框宽度为 0，输入框需叠加 `fieldCls`。
-- **游戏目录导入**：版本从**当前扫描目录**导入（`sourceGamePath`），实例建在主库；主目录变更自动重扫；批量导入幂等（已存在跳过）；相对 `gameDir`（默认 `.minecraft`）由主进程 `resolveGamePath` 按 exe 目录/项目根归一化。
-- **设置页结构（参考 PCL2）**：通用（主页/Koring 账户/关于/版权）与其他（服务与反馈/赞助/开发者）保留；游戏组（账户·离线登录、Java、目录、高级·含快速进入服务器）、个性化组（主题背景/主界面/语言/辅助）、网络组（下载/安全识别）已对接设置接口；以太/陶瓦联机页暂为占位。新增配置段：`app.language`（语言偏好）、`ui.showInstanceTitle/showTaskButton`（主界面元素）、`advanced.server`（快速进入服务器，启动自动加入）。
-- **离线账号登录**：`auth:offline-login` 处理器生成离线 UUID（MD5(OfflinePlayer:用户名)）；微软登录 UI 标注"开发中"。
-- **AboutVersion（关于此版本）**：`src/components/about-version/` 拉取当前版本 GitHub 发布说明，解析后**按提交类型（新增/修复/优化/重构/文档/其他）分类卡片**展示（不渲染原始 Markdown）；OOBE/UPvP 流程步骤为「版本卡片 → 关于此版本」。
-
-## Tech Stack
-
-| Layer | Technology |
-|-------|-----------|
-| Frontend | React 19, Vite 7, Tailwind CSS v4, shadcn/ui, Zustand |
-| Main Process | Node.js, TypeScript, @xmcl/* packages |
-| Build | pnpm, Vite, electron-builder |
+For commercial licensing, contact Shenzhen Lingke Network Technology Co., Ltd.