From 2a0493c3eb6ab3e25c3b6f562e07b9c2bd23dd2d Mon Sep 17 00:00:00 2001 From: AskaEth Date: Sun, 1 Nov 2026 18:53:26 +0800 Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E4=B8=A4=E4=BB=BD=20README=20?= =?UTF-8?q?=E6=94=B9=E5=86=99=E4=B8=BA=20iced/M3=20Expressive=20=E7=8E=B0?= =?UTF-8?q?=E7=8A=B6=EF=BC=88=E5=8F=8C=20bin=20=E5=B9=B6=E5=AD=98=20+=20?= =?UTF-8?q?=E4=B8=A4=E8=BD=A8=20Status=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - UI 描述：已发布 v0.1.0 = Slint + Metro；下一代 = iced 0.14 + Material 3 Expressive，dev 上施工中 - 双 bin 并存逐条讲清：unlucky-launcher（Slint，v0.1.0 已发布）/ unlucky-launcher-iced（施工中） / ull（CLI），并说明翻牌前不改名的原因（同 target 目录不能同名 bin） - 模块地图补 crates/design（真 HCT 令牌、零 UI 依赖）与 crates/app-iced；crates/app 保留到等价验收 - Status 重写为两轨：Track A 已发布（含 v0.1.0 资产范围与 CLI 命令集，取自 release.yml 与 cli/help.rs） / Track B 施工中（已完成=令牌+骨架；未完成=组件库/页面/i18n，页面全是占位） - 删除全部过期统计数字（983+ tests 等），改为行为性门禁表述；无测试数、无产物体积 - 合规段落只留 Microsoft 正版登录 / 凭据只存本机且 AI 不可访 / 离线不能联机 / 不分发不镜像不代理 / 与 Mojang-Microsoft 无关联；无第三方账户服务字样 - 许可：Slint RF 2.0 归属保留并补 iced(MIT)、MCU(Apache-2.0)、其余主要依赖 - 致谢 HMCL / PCL2 改为口语化语气，不加粗、不撇清 - 开头保留 GitHub 官方主页行（英文自指、中文醒目指引 + Releases 链接），全文无 gitea 地址 - 平台基线补 macOS 未签名需清 Gatekeeper 隔离标记 --- README.md | 191 +++++++++++++++++++++++++++++++++--------------- README.zh-CN.md | 156 ++++++++++++++++++++++++++++----------- 2 files changed, 246 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index 3cab754..48bd9a1 100644 --- a/README.md +++ b/README.md @@ -2,57 +2,97 @@ **English** · [简体中文](README.zh-CN.md) -> **Official project home**: https://github.com/AskaEth/Unlucky-Launcher +> **Official project home**: https://github.com/AskaEth/Unlucky-Launcher ｜ downloads, issues and +> release notes all live there: Unlucky Launcher (ULL) is a free, open-source Minecraft: Java Edition launcher written in Rust -(Apache-2.0, non-commercial), with a Slint + Metro UI. It embeds an AI agent client (chat / -configuration / crash diagnosis) and integrates with the broader agent tooling ecosystem via MCP. -Minimum baseline: Windows 10. +(Apache-2.0). It ships as one native binary per platform — no installer, no bundled runtime, no +WebView. The launcher embeds an AI agent client (chat / configuration / crash diagnosis) and can be +attached to other agent tooling as an MCP server. -- Runtime: a single native Rust binary — no JVM, no WebView, no external runtime -- UI: Slint (Royalty-Free 2.0; GL preferred, CPU software-rendering fallback so older machines - without a usable GPU still get the full UI) -- License: Apache-2.0 © AskaEth (YeiJ) +- **Single-file native binary**: the launcher itself needs no JVM, no WebView and no sidecar + runtime. The JDK a game needs is downloaded and managed per instance, not as a launcher + dependency. +- **Two UI stacks during the rewrite**: the released UI is Slint (Royalty-Free 2.0); the + next-generation UI is iced 0.14 + Material 3 Expressive and is still being written (see Status). +- **CPU software-rendering fallback**: `--software-renderer` gives the full UI on machines with no + usable GPU or with broken drivers. +- **AI agent + MCP**: chat, setting edits and crash diagnosis inside the launcher; `ull agent + serve` exposes the same core as an MCP server (stdio or Streamable HTTP) to external agent tools. +- **Mod loaders**: Fabric, Quilt, NeoForge, Forge, with modpack and CurseForge / Modrinth clients in + the core. +- **Java management**: a Temurin → Oracle → Microsoft → Zulu fallback chain, region-aware. +- **Engine**: multi-source download (health scoring, mirrors, chunked transfers, hash while + downloading) and a YAML rule-based crash diagnosis engine. +- **License**: Apache-2.0 © AskaEth (YeiJ). ## Compliance statement -Authentication uses only official Microsoft/Mojang endpoints — Microsoft OAuth 2.0 device code -flow, Xbox Live, XSTS, and api.minecraftservices.com — so players sign in with their own Microsoft -account and launch the game they already own. Account tokens are stored only on the user's local -machine and are never sent to any server operated by the project. ULL does not distribute, mirror, -proxy or modify any Minecraft game files. Online play always requires a Microsoft account with -valid entitlements. Local offline profiles never contact Microsoft or Mojang services and cannot -join online-mode servers. Not affiliated with Mojang or Microsoft. +- **Microsoft sign-in only.** Authentication is Microsoft OAuth 2.0 device code flow → Xbox Live → + XSTS → `api.minecraftservices.com`, using the player's own Microsoft account and their own game + entitlement. There is no other account provider. +- **Credentials stay on your machine.** Account tokens are stored locally only, are never sent to + any server operated by this project, and the AI features cannot read them. +- **Offline profiles cannot play online.** A local offline profile performs no Microsoft + authentication, contacts no Microsoft/Mojang service, exists for local and isolated-network + testing only, and cannot join servers that check accounts against the official service. +- ULL does not distribute, mirror, proxy or modify any Minecraft game files. +- Not affiliated with Mojang or Microsoft. ## Status -The core engine is complete (workspace: 983+ tests passing): +Two tracks. They are not the same product yet, so read the headings before downloading anything. -- **Microsoft sign-in**: OAuth 2.0 device code flow → Xbox Live → XSTS → Minecraft Services, with - entitlement verification -- **Account credentials are stored only on the local machine** — never uploaded, and inaccessible - to the AI features -- Mod loaders: Forge / NeoForge / Fabric / Quilt, verified on real machines -- Java management: Temurin / Oracle / Microsoft / Zulu with a regional fallback chain -- Multi-source download engine; YAML rule-based crash diagnosis -- Usable as an MCP server for external agent tooling (`ull agent serve`) -- Local offline profiles: for local / isolated-network testing only; they perform no Microsoft - authentication and cannot join servers with online-mode enabled +### Track A — released: v0.1.0, Slint UI (this is what you can download today) -**CLI (`ull`) is fully usable**: `install / launch / accounts / java / diagnose / agent`. +- **GitHub Releases `v0.1.0`** (2026-11-01, flagged pre-release): single-file assets for Windows + x64 (a bare `.exe`), Linux x64 and macOS (arm64 and x64) `.tar.gz`, plus `SHA256SUMS.txt` and + `LICENSE` / `NOTICE` / `README.md` as side assets on Windows. +- **UI**: Slint + Metro. This is the shipped GUI — the instance, download, account, Java, log and + settings pages drive the real engine (the in-app AI chat panel is a scripted placeholder). +- **CLI `ull`** ships in the same release and is fully usable: `instances`, `install`, `launch`, + `accounts`, `sessions`, `logs`, `diag`, `config`, `java`, `agent`. +- Windows ARM64 and Linux ARM64 slots are wired into the release pipeline; the next tagged release + builds them. The `v0.1.0` assets predate those two slots. -**GUI in development**: `crates/app` is currently a Slint + Metro skeleton; the theme system and -the full interface ship with subsequent versions — use the CLI until then. +### Track B — in progress on `dev`: next-generation UI (iced + Material 3 Expressive) + +**Nothing on this track is released, and no download contains it.** You can only see it by +building from source. + +- **Locked direction**: the look is Material 3 Expressive and the framework is iced 0.14; the UI + layer is written from scratch. Neither the style nor the framework will change again. +- **Done**: the token crate `crates/design` (no UI framework, no third-party crates — real HCT + color, type scale, shape scale, spacing, elevation, motion, icon geometry, per-component + metrics) and the skeleton crate `crates/app-iced` (opens a window, self-drawn title bar and + window buttons, navigation rail, colors and type taken from tokens only, GPU→CPU backend probe + with automatic fallback, and the screenshot/diff channel the visual reviews use). +- **Not done**: the component library (buttons, dialogs, lists, menus, search, and the rest of the + M3 set), page migration, and the i18n pass. Every page in the iced binary is a placeholder. +- **Slint stays until the flip**: `crates/app` remains the reference implementation until the iced + build passes equivalence acceptance; only then is `unlucky-launcher-iced` renamed to + `unlucky-launcher` and the Slint crate retired. + +Binaries in the workspace, so you can tell them apart: + +| Binary | Crate | State | +|--------|-------|-------| +| `unlucky-launcher` | `crates/app` (Slint) | released in v0.1.0; still the usable GUI | +| `unlucky-launcher-iced` | `crates/app-iced` (iced 0.14) | under construction; skeleton only, not shipped | +| `ull` | `crates/cli` | released in v0.1.0; headless and fully usable | ## Module map ``` Unlucky-Launcher (cargo workspace) -├── crates/core # domain library, zero UI dependencies, eight modules -├── crates/agent # AI agent: ToolSpec registry + built-in client + MCP server (one shared core) -├── crates/app # Slint UI: the only crate allowed to depend on a UI framework -├── crates/cli # CLI (bin `ull`): headless, zero UI, depends on core + agent -└── packaging # single-file artifact matrix and packaging assets (planned) +├── crates/core # domain library: zero UI dependencies, eight modules +├── crates/agent # AI agent: ToolSpec registry + built-in client + MCP server (one core, two shapes) +├── crates/design # design tokens: real HCT color / type / shape / spacing / elevation / motion / icons +│ # / component metrics — zero UI dependencies, no third-party crates +├── crates/app # Slint UI (bin `unlucky-launcher`): the released GUI, kept until equivalence acceptance +├── crates/app-iced # next-generation iced UI (bin `unlucky-launcher-iced`): under construction +├── crates/cli # CLI (bin `ull`): headless, zero UI +└── packaging # single-file artifact matrix and release scripts ``` The eight modules of `crates/core`: @@ -72,53 +112,86 @@ The eight modules of `crates/core`: Prerequisites: -- Rust stable (`rust-toolchain.toml` selects the toolchain automatically; components `rustfmt` / - `clippy`) -- Windows: MSVC toolchain (used by CI) or MinGW-w64 (`x86_64-pc-windows-gnu`) -- Linux: `libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev libxcb1-dev` - (Slint winit backend + femtovg build dependencies) +- Rust stable (`rust-toolchain.toml` selects the toolchain automatically; the gates also need the + `rustfmt` and `clippy` components) +- Windows: MSVC toolchain (what CI uses) or MinGW-w64 (`x86_64-pc-windows-gnu`) +- Linux: `libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev + libxcb1-dev` — needed by both UI stacks (Slint's winit + femtovg, iced's winit + wgpu/tiny-skia) ```bash -cargo fmt --all --check # formatting -cargo clippy --workspace --all-targets -- -D warnings # lints (zero-warning gate) -cargo test --workspace # tests -cargo build --release # artifact: target/release/unlucky-launcher[.exe] +cargo fmt --all --check # formatting +cargo clippy --workspace --all-targets -- -D warnings # lints (zero-warning gate) +cargo test --workspace # tests +cargo build --release # binaries land in target/release/ ``` -Software-rendering switch (machines without a usable GPU / with broken drivers): -`unlucky-launcher --software-renderer` (equivalent to `SLINT_BACKEND=winit-software`). +What the build produces: + +- `unlucky-launcher` — the Slint UI (the released one) +- `unlucky-launcher-iced` — the iced UI skeleton. The name is temporary: it can only become + `unlucky-launcher` at the flip, because two crates in one workspace cannot emit the same binary + name into the same target directory. +- `ull` — the CLI + +Rendering switches: + +- `unlucky-launcher --software-renderer` (equivalent to `SLINT_BACKEND=winit-software`) forces the + CPU path on the Slint build +- `unlucky-launcher-iced --software-renderer` forces tiny-skia (`ICED_BACKEND=tiny-skia`); + `--screenshot ` writes one frame and exits, which is the acceptance channel +- Both builds probe the backend at startup and fall back to CPU automatically when no adapter is + usable Dependency license check (optional locally, required in CI): `cargo deny check licenses bans sources`. ## CI gates +Every push runs fmt / clippy (warnings are errors) / the full test suite, plus a headless render +smoke on Linux and a macOS runtime probe. Nothing here is advisory: a red gate blocks the merge. + | Workflow | Content | |----------|---------| -| `.github/workflows/ci.yml` | fmt + clippy + test + build, Windows / Linux matrix | -| `.github/workflows/guards.yml` | zero-UI guard for core, 400-line-per-file guard, cargo-deny license guard | +| `.github/workflows/ci.yml` | fmt + clippy + test + release build (Windows / Linux matrix); Linux runtime smoke (Xvfb: renders one real frame, then asserts the PNG is not blank); macOS runtime smoke | +| `.github/workflows/guards.yml` | zero-UI guard for `crates/core` (manifest plus `cargo tree`), 400-lines-per-file guard, cargo-deny license and source guard | +| `.github/workflows/release.yml` | tag `v*` → per-slot builds → single-file artifacts + `SHA256SUMS.txt` → GitHub Release | ## Platform baseline -Minimum baseline: **Windows 10**. Windows 8.1 / 8 / 7 are not supported: +Minimum baseline: **Windows 10**; Windows 8.1 / 8 / 7 are not supported. - Windows 10/11 builds use the **standard toolchain** (MSVC / GNU) — no custom target specs, no `-Zbuild-std`, no import-table allowlists -- Other platforms: macOS 12+ first class; Linux x64 with X11 preferred, Wayland as the long-term - direction; Android Termux experimental, not committed -- UI fallback: Slint software rendering (fully usable on machines without a GPU or with broken - drivers) +- macOS 12+ (Apple Silicon and Intel) and Linux x64 / arm64 are supported build slots; on Linux, + X11 is the preferred path today and Wayland is the long-term direction. macOS builds are unsigned, + so the first launch needs the Gatekeeper quarantine attribute cleared + (`xattr -d com.apple.quarantine`) +- Android Termux is experimental and not promised: CLI only, GUI unverified - Platform independence is expressed through **separate test matrices**, not separate artifact pipelines; capability differences use feature gates with runtime probing +- **Renderer fallback on both UI stacks**: the Slint build drops to software rendering, the iced + build drops from wgpu to tiny-skia, so a machine without a usable GPU still gets the full UI ## License and acknowledgements -- This project: Apache License 2.0, see [LICENSE](LICENSE); third-party notices in [NOTICE](NOTICE) -- The GUI uses [Slint](https://slint.dev) (Royalty-Free 2.0 track). Per the RF 2.0 obligations an - `AboutSlint` widget will be placed on the about page (P2); until then NOTICE and this section - serve the attribution duty. +- **This project**: Apache License 2.0, see [LICENSE](LICENSE); third-party notices in + [NOTICE](NOTICE). +- **Slint** (), Royalty-Free 2.0: obligation for the Slint build that v0.1.0 + ships — an `AboutSlint` widget on the about page (still outstanding) and, until it lands, the + NOTICE file, this section and a "Made with Slint" note on the release page. The obligation is + kept for as long as a Slint-linked binary ships. +- **iced** (), MIT: the framework of the next-generation UI, + together with `winit` and, through it, `wgpu` / `tiny-skia` (Apache-2.0 / MIT). +- **Google Material Color Utilities** (Apache-2.0): the color tokens in `crates/design` are a Rust + port of its HCT / ColorSpec2021 algorithms; details and the exact ported functions are listed in + [NOTICE](NOTICE). +- **Other major dependencies**: `rmcp` and `axum` (Apache-2.0 / MIT) for the MCP server, `tokio` + (MIT), `reqwest` with rustls (MIT / Apache-2.0), `serde` / `serde_json` (MIT / Apache-2.0), + `zip` / `flate2` / `tar` (MIT / Apache-2.0). The allow-list cargo-deny enforces is in `deny.toml`; + GPL-family dependencies may not enter the main line. Thanks to [HMCL](https://github.com/HMCL-dev/HMCL) and -[PCL2](https://github.com/Meloong-Git/PCL) (both GPL-3.0) — these two launchers have accompanied -the vast majority of Minecraft players for many years. ULL learned a great deal about design and -implementation from them, and this project is dedicated to those two pioneers. +[PCL2](https://github.com/Meloong-Git/PCL) (both GPL-3.0) — those two old-timers have been riding +along with the overwhelming majority of Minecraft players for years now. This launcher learned an +enormous amount from them about how a launcher should feel and how it should work, and it exists +very much in their debt. diff --git a/README.zh-CN.md b/README.zh-CN.md index ec6b890..1a7b9ae 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,41 +2,85 @@ [English](README.md) · **简体中文** -> **官方项目主页**：https://github.com/AskaEth/Unlucky-Launcher +> **官方项目主页**：https://github.com/AskaEth/Unlucky-Launcher ｜ 下载、议题、发布说明都在这里： +> -Rust 原生单文件 Minecraft 启动器：**Slint + Metro 视觉**，内置 **AI Agent 客户端**（对话 / 改配置 / 崩溃诊断）， -融合主流 Agent 工具（**MCP**），**最低基线 Win10+**。 +Unlucky Launcher（ULL）是一个用 Rust 写的免费开源 Minecraft: Java 版启动器（Apache-2.0）。 +每个平台就一个原生二进制——没有安装包、没有捆绑运行时、没有 WebView。启动器内置 AI Agent +客户端（对话 / 改配置 / 崩溃诊断），也能作为 MCP server 接进别的 Agent 工具。 -- 运行时：纯 Rust 原生二进制——无 JVM、无 WebView、无外部运行时 -- UI：Slint（Royalty-Free 2.0；GL 优先，CPU 软渲染兜底，无可用 GPU 的老机也有完整 UI） -- 许可：Apache-2.0 © AskaEth (YeiJ) +- **单文件原生二进制**：启动器本体不需要 JVM、不需要 WebView、不带旁挂运行时。游戏要的 JDK 由 + 启动器按实例下载管理，不是启动器的依赖。 +- **重写期两套 UI 并存**：已发布版本是 Slint（Royalty-Free 2.0）；下一代 UI 是 iced 0.14 + + Material 3 Expressive，目前仍在写（见「当前状态」）。 +- **CPU 软渲染兜底**：`--software-renderer` 让没有可用 GPU 或驱动有问题的老机也能拿到完整界面。 +- **AI Agent + MCP**：启动器内可对话、改设置、读崩溃诊断；`ull agent serve` 把同一个内核以 MCP + server 形态（stdio 或 Streamable HTTP）开放给外部 Agent 工具。 +- **加载器**：Fabric / Quilt / NeoForge / Forge；整合包与 CurseForge / Modrinth 客户端在 core 里。 +- **Java 管理**：Temurin → Oracle → Microsoft → Zulu 回退链，带地区判定。 +- **引擎**：多源下载（健康度评分、镜像、分块传输、边下边算）与 YAML 规则引擎的崩溃诊断。 +- **许可**：Apache-2.0 © AskaEth (YeiJ)。 + +## 合规声明 + +- **只走 Microsoft 正版登录**：认证是 Microsoft OAuth 2.0 device code flow → Xbox Live → XSTS → + `api.minecraftservices.com`，用的是玩家自己的 Microsoft 账户与自己已购的游戏权益，没有别家账户通道。 +- **凭据只存本机**：账户令牌只保存在本机，不上传本项目运营的任何服务器，AI 功能也读不到。 +- **离线档案不能联机**：本地离线档案不做 Microsoft 认证、不连 Microsoft / Mojang 任何服务，仅用于 + 本地与隔离网络环境的测试，无法连接对官方验证服校验账户的服务器。 +- 不分发、不镜像、不代理、不修改任何 Minecraft 游戏文件。 +- 与 Mojang、Microsoft 无关联。 ## 当前状态 -**核心引擎已完成**（workspace 983+ 测试全绿）： +两条轨道，还不是同一个东西——看小标题再决定下载什么。 -- **正版登录**：Microsoft OAuth 2.0 device code flow → Xbox Live → XSTS → Minecraft Services，校验游戏拥有状态 -- **账户凭据仅保存在本机**，不上传任何服务器，AI 功能无法访问 -- 加载器：Forge / NeoForge / Fabric / Quilt 四家真机验证 -- Java 管理：Temurin / Oracle / Microsoft / Zulu 四发行版回退链 -- 多源下载引擎、崩溃诊断规则引擎 -- 可作为 MCP server 接入外部 Agent 工具（`ull agent serve`） -- 本地离线档案：仅用于本地/隔离网络环境的测试，不经过 Microsoft 账户认证，无法连接启用正版验证的服务器 +### 轨道 A —— 已发布：v0.1.0，Slint 版（现在真能下载的就是它） -**CLI（`ull`）完整可用**：`install / launch / accounts / java / diagnose / agent` 等全量命令。 +- **GitHub Releases `v0.1.0`**（2026-11-01，标记为 pre-release）：单文件产物覆盖 Windows x64（裸 + `.exe`）、Linux x64、macOS（arm64 与 x64）`.tar.gz`，另附 `SHA256SUMS.txt`；Windows 因为「一个 exe + 装不下文本」，`LICENSE` / `NOTICE` / `README.md` 作为并列资产随下载走。 +- **UI**：Slint + Metro。这是已交付的图形界面——实例、下载、账户、Java、日志、设置各页驱动真实引擎 + （应用内 AI 对话面板仍是脚本化的占位）。 +- **CLI `ull`** 同版本发布、完整可用：`instances`、`install`、`launch`、`accounts`、`sessions`、 + `logs`、`diag`、`config`、`java`、`agent`。 +- Windows ARM64 与 Linux ARM64 两个槽位已接进发布流水线，随下一个 tag 发布；`v0.1.0` 的资产早于 + 这两个槽位。 -**图形界面（GUI）开发中**：`crates/app` 当前为 Slint + Metro 风格骨架，主题系统与完整界面 -随后续版本交付——在此之前请使用 CLI。 +### 轨道 B —— dev 上的下一代 UI（iced + M3 Expressive，施工中） + +**这条轨道没有任何已发布的东西，任何下载都拿不到它。** 想看只能自己从源码编。 + +- **方向已锁死**：视觉 = Material 3 Expressive，框架 = iced 0.14，UI 层从头写；风格与框架都不会再换。 +- **已完成**：令牌 crate `crates/design`（零 UI 框架依赖、零第三方 crate——真 HCT 色彩、排版档位、 + 形状刻度、间距、高程、动效、图标几何、组件度量）与骨架 crate `crates/app-iced`（能开窗、自绘标题栏 + 与窗口键、导航轨、颜色与字号只从令牌取、GPU→CPU 后端探测与自动降级、视觉验收用的截图与逐像素 + 对比通道）。 +- **没完成**：组件库（按钮、对话框、列表、菜单、搜索栏，以及 M3 其余组件）、页面搬迁、i18n 文案。 + iced 版里现在每一个页面都是占位。 +- **Slint 版在翻牌前不退场**：`crates/app` 作为参考实现保留，直到 iced 版通过等价验收；那时才把 + `unlucky-launcher-iced` 改名成 `unlucky-launcher`，并让 Slint 版退役。 + +工作区里的三个 bin，先认清楚： + +| 二进制 | crate | 状态 | +|--------|-------|------| +| `unlucky-launcher` | `crates/app`（Slint） | v0.1.0 已发布，仍是当前能用的图形界面 | +| `unlucky-launcher-iced` | `crates/app-iced`（iced 0.14） | 施工中，仅骨架，不随发布包分发 | +| `ull` | `crates/cli` | v0.1.0 已发布，headless 完整可用 | ## 模块地图 ``` Unlucky-Launcher (cargo workspace) -├── crates/core # 领域库：零 UI 依赖，八模块 -├── crates/agent # AI Agent：ToolSpec 注册表 + 内置客户端 + MCP server（双形态共用一个内核） -├── crates/app # Slint UI：唯一允许依赖 UI 框架的 crate -├── crates/cli # CLI（bin `ull`）：headless，零 UI，只依赖 core + agent -└── packaging # 单文件产物矩阵与打包资源（规划中） +├── crates/core # 领域库：零 UI 依赖，八模块 +├── crates/agent # AI Agent：ToolSpec 注册表 + 内置客户端 + MCP server（双形态共用一个内核） +├── crates/design # 设计令牌：真 HCT 色彩 / 排版 / 形状 / 间距 / 高程 / 动效 / 图标 / 组件度量 +│ # —— 零 UI 依赖、零第三方 crate +├── crates/app # Slint UI（bin `unlucky-launcher`）：已发布的图形界面，保留到等价验收通过 +├── crates/app-iced # 下一代 iced UI（bin `unlucky-launcher-iced`）：施工中 +├── crates/cli # CLI（bin `ull`）：headless，零 UI +└── packaging # 单文件产物矩阵与发布脚本 ``` `crates/core` 的八个模块： @@ -56,44 +100,72 @@ Unlucky-Launcher (cargo workspace) 前置： -- Rust stable（`rust-toolchain.toml` 会自动选择工具链；组件 `rustfmt` / `clippy`） -- Windows：MSVC 工具链（CI 用）或 MinGW-w64（`x86_64-pc-windows-gnu`） -- Linux：`libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev libxcb1-dev` - （Slint winit 后端 + femtovg 编译依赖） +- Rust stable（`rust-toolchain.toml` 会自动选工具链；门禁还需要 `rustfmt` / `clippy` 组件） +- Windows：MSVC 工具链（CI 用这套）或 MinGW-w64（`x86_64-pc-windows-gnu`） +- Linux：`libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev + libxcb1-dev`——两套 UI 都要用（Slint 的 winit + femtovg，iced 的 winit + wgpu/tiny-skia） ```bash -cargo fmt --all --check # 格式 -cargo clippy --workspace --all-targets -- -D warnings # 静态检查（零 warning 门禁） -cargo test --workspace # 测试 -cargo build --release # 产物：target/release/unlucky-launcher[.exe] +cargo fmt --all --check # 格式 +cargo clippy --workspace --all-targets -- -D warnings # 静态检查（零 warning 门禁） +cargo test --workspace # 测试 +cargo build --release # 三个 bin 都落在 target/release/ ``` -软渲染开关（无可用 GPU / 烂驱动的老机）：`unlucky-launcher --software-renderer` -（等价于 `SLINT_BACKEND=winit-software`）。 +编出来的三个 bin： + +- `unlucky-launcher`——Slint 版（已发布的那个） +- `unlucky-launcher-iced`——iced 版骨架。名字是临时的：只有翻牌时才能改成 `unlucky-launcher`， + 因为同一个工作区里两个 crate 不能往同一个 target 目录里产出同名 bin。 +- `ull`——CLI + +渲染开关： + +- `unlucky-launcher --software-renderer`（等价于 `SLINT_BACKEND=winit-software`）强制 Slint 版走 CPU +- `unlucky-launcher-iced --software-renderer` 强制 tiny-skia（`ICED_BACKEND=tiny-skia`）； + `--screenshot ` 出一帧图后退出，这是验收通道 +- 两个版本启动时都会探测后端，拿不到可用适配器就自动降级到 CPU 依赖许可检查（本地可选，CI 必跑）：`cargo deny check licenses bans sources`。 ## CI 门禁 +每次推送都跑 fmt / clippy（warnings 视为错误）/ 全量测试，另有一条 Linux 无头渲染冒烟与一次 +macOS 运行期探测。这些门禁不是摆设：红了就不许合。 + | Workflow | 内容 | |----------|------| -| `.github/workflows/ci.yml` | fmt + clippy + test + build，Windows / Linux 矩阵 | -| `.github/workflows/guards.yml` | core 零 UI 守门、单文件 ≤400 行守门、cargo-deny 许可守门 | +| `.github/workflows/ci.yml` | fmt + clippy + test + release build（Windows / Linux 矩阵）；Linux runtime smoke（Xvfb 里真渲染一帧，再断言 PNG 非空白）；macOS runtime smoke | +| `.github/workflows/guards.yml` | `crates/core` 零 UI 守门（依赖表 + `cargo tree`）、单文件 ≤400 行守门、cargo-deny 许可与来源守门 | +| `.github/workflows/release.yml` | tag `v*` → 分槽位构建 → 单文件产物 + `SHA256SUMS.txt` → GitHub Release | ## 平台基线 -最低基线 **Windows 10**。Windows 8.1 / 8 / 7 不在支持范围内： +最低基线 **Windows 10**；Windows 8.1 / 8 / 7 不在支持范围内。 - Windows 10/11 走**标准工具链**产物（MSVC / GNU），无自定义 target spec、无 `-Zbuild-std`、无导入表白名单 -- 其他平台：macOS 12+ 一等；Linux x64 X11 优先、Wayland 为**大方向**；Android Termux 试验级不承诺 -- UI 兜底：Slint 软渲染（无 GPU / 烂驱动的老机可完整使用） +- macOS 12+（Apple Silicon 与 Intel）与 Linux x64 / arm64 都是支持槽位；Linux 上 X11 是当前首选路径， + Wayland 是大方向。macOS 产物未签名，首次启动要自己清掉 Gatekeeper 隔离标记 + （`xattr -d com.apple.quarantine`） +- Android Termux 试验级、不承诺：只保证 CLI，GUI 未验证 - 平台独立性体现在**独立测试矩阵**，而非独立产物链；能力差异用 feature gate + 运行期探测表达 +- **两套 UI 都有渲染兜底**：Slint 版降软渲染，iced 版从 wgpu 降到 tiny-skia，没有可用 GPU 的机器 + 同样能拿到完整界面 ## 许可证与致谢 -- 本项目：Apache License 2.0，见 [LICENSE](LICENSE)；第三方声明见 [NOTICE](NOTICE) -- GUI 使用 [Slint](https://slint.dev)（Royalty-Free 2.0 轨道）。按 RF 2.0 义务，关于页将放置 - `AboutSlint` 部件（P2），在此之前由 NOTICE 与本节承担告知义务 +- **本项目**：Apache License 2.0，见 [LICENSE](LICENSE)；第三方声明见 [NOTICE](NOTICE)。 +- **Slint**（），Royalty-Free 2.0：v0.1.0 发布的正是 Slint 版，这项义务继续有效 + ——关于页放 `AboutSlint` 部件（尚未落地），在此之前由 NOTICE、本节与发布页的「Made with Slint」 + 说明承担告知义务。只要还有链接 Slint 的产物在发，这条义务就保留。 +- **iced**（），MIT：下一代 UI 的框架；与它同栈的 `winit`、以及经它 + 引入的 `wgpu` / `tiny-skia`（Apache-2.0 / MIT）。 +- **Google Material Color Utilities**（Apache-2.0）：`crates/design` 的色彩令牌是它 HCT / + ColorSpec2021 算法的 Rust 重写移植，移植清单与逐函数对照写在 [NOTICE](NOTICE)。 +- **其余主要依赖**：MCP server 的 `rmcp` 与 `axum`（Apache-2.0 / MIT）、`tokio`（MIT）、`reqwest` + 与 rustls（MIT / Apache-2.0）、`serde` / `serde_json`（MIT / Apache-2.0）、`zip` / `flate2` / `tar` + （MIT / Apache-2.0）。cargo-deny 强制执行的白名单在 `deny.toml`；GPL 系依赖不得进主干。 -感谢 [HMCL](https://github.com/HMCL-dev/HMCL) 和 [PCL2](https://github.com/Meloong-Git/PCL)（均 GPL-3.0）这两个启动器陪伴了绝大多数 MC 玩家好多年。 -ULL 的设计与实现从它们身上学到了太多，谨以此项目向两位前辈致敬。 +感谢 [HMCL](https://github.com/HMCL-dev/HMCL) 和 [PCL2](https://github.com/Meloong-Git/PCL) +（均 GPL-3.0）——这两位陪着绝大多数 MC 玩家走了好多年的老前辈。启动器该是什么手感、该怎么把一件 +事做顺，我们是从它们身上学的；这个项目欠它们一份很大的人情。