Unlucky Launcher v0.2.2

crates/presenter/src/host/accounts.rs

@@ -0,0 +1,299 @@
+//! 账户：三轨统一列表（只读公开字段）+ 离线新增 + 删除/切换 + 微软登录（两条流）。
+//!
+//! 凭据红线（D9）：`Credentials` / `MicrosoftSession` 只在本模块与 `launch.rs` 里出现，
+//! 出口一律是 [`AccountView`] / [`DeviceLoginView`]。
+//!
+//! 两条登录流：授权码（[`start_browser_login`]，GUI 默认：拉起系统浏览器 + 本地回调，
+//! `research/08` §3 方案 A）与设备码（[`start_login`]，无浏览器/CLI 场景）。除了「怎么拿到
+//! MS access_token」之外完全共用：同一个取消槽位、同一段账户入库、同一个刷新链。
+//!
+//! 取消语义：轮询/等回调都跑在 `core` 里、没有取消钩子，所以取消只把面板收回；线程收尾时
+//! 若发现「已取消」就不入库（避免用户点了取消却凭空多出一个账户）。
+//!
+//! M132：缺 client id 只在**登录入口**失败（`auth_failure`），所以说明接在账户页的登录面板，
+//! 不接启动流程——没配 id 的发布版根本建不出微软账户，启动那条路用户撞不到。
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::auth::account::Credentials;
+use unlucky_core::auth::microsoft::{now_ms, MicrosoftAuth, MicrosoftSession};
+use unlucky_core::auth::offline::offline_meta;
+use unlucky_core::auth::{AccountStore, AuthError, AuthResult};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::CoreEvent;
+use crate::dto::{
+    valid_offline_name, AccountKind, AccountNotice, AccountNoticeCode, AccountView,
+    DeviceLoginView, LoginFailure,
+};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+use super::opener;
+
+/// 第三方轨（服务发现 / 密码登录 / 皮肤抓取）。
+pub mod authlib;
+
+mod refresh;
+
+mod failure;
+
+pub use failure::AccountFailure;
+
+use failure::classify;
+
+pub use authlib::{fetch_skin, spawn_probe, start_login as start_authlib_login};
+
+impl super::CoreHost {
+    /// 推一条账户页横幅（一次性操作结果；页面渲染后由用户关掉）。
+    pub(super) fn notice(&mut self, code: AccountNoticeCode, subject: &str, detail: &str) {
+        self.send(CoreEvent::AccountNoticeChanged(Some(AccountNotice::new(
+            code, subject, detail,
+        ))));
+    }
+
+    /// 账户写操作失败：**原文进日志**，页面只拿结构化码 + 主题名。
+    pub(super) fn notice_failure(&mut self, failure: AccountFailure, subject: &str) {
+        eprintln!(
+            "[accounts] 操作失败（{}，subject={subject}）：{}",
+            failure.code.code(),
+            failure.detail
+        );
+        self.notice(failure.code, subject, &failure.detail);
+    }
+}
+
+/// 账户列表（公开字段）。
+pub fn accounts(env: &HostEnv, active: Option<&str>) -> Vec<AccountView> {
+    let store = AccountStore::open(env.layout.auth_data());
+    store
+        .accounts()
+        .iter()
+        .map(|meta| AccountView {
+            id: meta.id.as_str().to_string(),
+            name: meta.display_name().to_string(),
+            kind: AccountKind::parse(meta.kind.as_str()),
+            profile_id: meta.profile_id.clone(),
+            login_name: meta.login_name.clone().unwrap_or_default(),
+            created: display_ms(meta.created_at_ms),
+            active: active.is_some_and(|id| id == meta.id.as_str()),
+            server_url: meta.server_url.clone().unwrap_or_default(),
+            // 皮肤是网络产物：列表先给 `None`，host 抓到之后按账户 id 盖回去（见 `CoreHost`）
+            skin: None,
+        })
+        .collect()
+}
+
+/// 毫秒时间戳 → `2026-10-31 20:12`（UTC；账户列表只用来排序/辨认）。
+pub fn display_ms(ms: u64) -> String {
+    if ms == 0 {
+        return String::new();
+    }
+    let total_secs = ms / 1000;
+    let days = total_secs / 86_400;
+    let rem = total_secs % 86_400;
+    let (year, month, day) = civil_from_days(i64::try_from(days).unwrap_or(0));
+    format!(
+        "{year:04}-{month:02}-{day:02} {:02}:{:02}",
+        rem / 3_600,
+        (rem % 3_600) / 60
+    )
+}
+
+/// Howard Hinnant 的 `civil_from_days`（1970-01-01 为 0）。
+fn civil_from_days(days: i64) -> (i64, u32, u32) {
+    let z = days + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = z - era * 146_097;
+    let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;
+    let y = yoe + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let d = doy - (153 * mp + 2) / 5 + 1;
+    let m = if mp < 10 { mp + 3 } else { mp - 9 };
+    (if m <= 2 { y + 1 } else { y }, m as u32, d as u32)
+}
+
+/// 加一个离线账户。
+///
+/// # Errors
+///
+/// 名字不合法、同名冲突、落盘失败时返回 [`AccountFailure`]（带结构化码）。
+pub fn add_offline(env: &HostEnv, name: &str) -> Result<String, AccountFailure> {
+    let name = name.trim();
+    if !valid_offline_name(name) {
+        return Err(AccountFailure {
+            code: AccountNoticeCode::OfflineNameInvalid,
+            detail: format!("离线名字必须是 3–16 位字母/数字/下划线，收到 {name:?}"),
+        });
+    }
+    let meta = offline_meta(name, now_ms())
+        .map_err(|error| AccountFailure::classify(error, AccountNoticeCode::OfflineNameInvalid))?;
+    let display = meta.display_name().to_string();
+    let mut store = AccountStore::open(env.layout.auth_data());
+    store
+        .insert(meta, Credentials::Offline)
+        .map_err(|error| AccountFailure::classify(error, AccountNoticeCode::AccountExists))?;
+    store
+        .save()
+        .map_err(|error| AccountFailure::classify(error, AccountNoticeCode::StoreFailed))?;
+    Ok(display)
+}
+
+/// 删除账户（按 id 或名字）。
+///
+/// # Errors
+///
+/// 找不到、落盘失败时返回 [`AccountFailure`]。
+pub fn remove(env: &HostEnv, key: &str) -> Result<String, AccountFailure> {
+    let mut store = AccountStore::open(env.layout.auth_data());
+    let meta = store
+        .remove(key)
+        .map_err(|error| AccountFailure::classify(error, AccountNoticeCode::NotFound))?;
+    store
+        .save()
+        .map_err(|error| AccountFailure::classify(error, AccountNoticeCode::StoreFailed))?;
+    Ok(meta.display_name().to_string())
+}
+
+/// 微软登录任务句柄（取消标志 + 账户名回执；两条流共用）。
+#[derive(Debug, Clone, Default)]
+pub struct LoginJob {
+    /// 用户点了取消（线程收尾时据此丢弃结果）
+    pub cancelled: Arc<AtomicBool>,
+}
+
+impl LoginJob {
+    /// 新建一个未取消的句柄。
+    pub fn new() -> Self {
+        Self {
+            cancelled: Arc::new(AtomicBool::new(false)),
+        }
+    }
+
+    /// 取消。
+    pub fn cancel(&self) {
+        self.cancelled.store(true, Ordering::SeqCst);
+    }
+
+    /// 是否已取消。
+    pub fn is_cancelled(&self) -> bool {
+        self.cancelled.load(Ordering::SeqCst)
+    }
+}
+
+/// 起一次设备码登录（后台线程；`present` 时刻发 Waiting 事件）。
+pub fn start_login(env: HostEnv, tx: JobSender, job: LoginJob) {
+    spawn("msa-login", move || {
+        let auth = match microsoft_auth(&env) {
+            Ok(auth) => auth,
+            Err(error) => return fail(&tx, auth_failure(&error), error.to_string()),
+        };
+        let tx_prompt = tx.clone();
+        let result = block_on(auth.device_code_login(|prompt| {
+            let _ = tx_prompt.send(HostTask::Login(Box::new(DeviceLoginView::waiting(
+                &prompt.user_code,
+                &prompt.verification_uri,
+                prompt.expires_in.as_secs(),
+                &format!("{}#{}", prompt.verification_uri, prompt.user_code),
+            ))));
+        }));
+        finish(&env, &tx, &job, result);
+    });
+}
+
+/// 起一次授权码登录（后台线程：绑本地端口 → 拉起系统默认浏览器 → 等回调 → 换链）。
+///
+/// 与设备码流共用同一个 [`LoginJob`] 取消槽位、同一段账户入库逻辑，所以两条流的
+/// 凭据/刷新语义完全一致（`core` 侧也共用 [`unlucky_core::auth::MicrosoftSession`]）。
+pub fn start_browser_login(env: HostEnv, tx: JobSender, job: LoginJob) {
+    spawn("msa-authcode", move || {
+        let auth = match microsoft_auth(&env) {
+            Ok(auth) => auth,
+            Err(error) => return fail(&tx, auth_failure(&error), error.to_string()),
+        };
+        let tx_prompt = tx.clone();
+        let result = block_on(auth.authcode_login(|prompt| {
+            // 浏览器拉不起来不是致命错误：面板里还有可复制的授权链接。
+            let opened = opener::open_url(&prompt.authorization_url);
+            let _ = tx_prompt.send(HostTask::Login(Box::new(DeviceLoginView::browser_waiting(
+                &prompt.authorization_url,
+                prompt.timeout.as_secs(),
+                opened.err().as_deref(),
+            ))));
+        }));
+        finish(&env, &tx, &job, result);
+    });
+}
+
+/// 生产入口的 `MicrosoftAuth`：client id 取环境/构建期，失败日志落 `<数据根>/logs/`。
+fn microsoft_auth(env: &HostEnv) -> AuthResult<MicrosoftAuth> {
+    MicrosoftAuth::from_env().map(|auth| {
+        auth.with_journal(Some(unlucky_core::auth::AuthJournal::in_logs_dir(
+            env.layout.logs(),
+        )))
+    })
+}
+
+/// `microsoft_auth` 失败 → 原因码。
+///
+/// **只有「两处都没配 client id」单独成码**（M132）：`from_env` 的 `Unsupported` 是它唯一的
+/// 产出点，且这条路径零网络。上屏的正文是 catalog 里的固定文案（原文照旧只进日志），理由是
+/// 这一类的原因就是用户的下一步（设 `ULL_MSA_CLIENT_ID`）；其余失败仍走 [`classify`]。
+fn auth_failure(error: &AuthError) -> LoginFailure {
+    match error {
+        AuthError::Unsupported(_) => LoginFailure::MsaNotConfigured,
+        other => classify(other),
+    }
+}
+
+/// 失败收尾（带**原因码**）：原文进日志，页面据码出 i18n（复审 r1 P1-1）。
+fn fail(tx: &JobSender, failure: LoginFailure, detail: impl Into<String>) {
+    let detail = detail.into();
+    eprintln!("[auth] 微软登录失败（{}）：{detail}", failure.code());
+    let _ = tx.send(HostTask::Login(Box::new(DeviceLoginView::failed_as(
+        failure, detail,
+    ))));
+}
+
+/// 收尾：取消就吞掉结果；成功入库；失败带 core 的诊断文案（M38 的 403 也走这条）。
+fn finish(env: &HostEnv, tx: &JobSender, job: &LoginJob, result: AuthResult<MicrosoftSession>) {
+    if job.is_cancelled() {
+        let _ = tx.send(HostTask::Login(Box::default()));
+        return;
+    }
+    match result {
+        Ok(session) => match store_session(env, session) {
+            Ok(name) => {
+                let _ = tx.send(HostTask::Login(Box::new(DeviceLoginView::succeeded(&name))));
+                let _ = tx.send(HostTask::Accounts(accounts(env, None)));
+            }
+            Err(message) => fail(tx, LoginFailure::StoreFailed, message),
+        },
+        Err(error) => {
+            let failure = classify(&error);
+            fail(tx, failure, error.to_string());
+        }
+    }
+}
+
+/// 微软会话入库（元数据 + 凭据分文件，见 `core::auth::AccountStore`）。
+fn store_session(env: &HostEnv, session: MicrosoftSession) -> Result<String, String> {
+    let meta = unlucky_core::auth::account::AccountMeta::new(
+        unlucky_core::auth::account::AccountKind::Microsoft,
+        session.profile_id.clone(),
+        session.profile_name.clone(),
+        now_ms(),
+    );
+    let name = meta.display_name().to_string();
+    let mut store = AccountStore::open(env.layout.auth_data());
+    store
+        .insert(meta, Credentials::Microsoft(session))
+        .and_then(|()| store.save())
+        .map_err(|error| format!("账户入库失败：{error}"))?;
+    Ok(name)
+}
+
+#[cfg(test)]
+mod tests;

crates/presenter/src/host/accounts/authlib.rs

@@ -0,0 +1,337 @@
+//! 第三方轨（authlib-injector）：服务发现校验、密码登录、皮肤原图抓取。
+//!
+//! 全部跑在后台线程里（网络），出口只有 [`AuthlibLoginView`] / [`SkinImage`]——
+//! 密码与 accessToken 在调用栈里就地丢弃，永不进 DTO 回程（M114 凭据红线）。
+//!
+//! ## 三条流的坐标
+//!
+//! | 动作 | 端点 | 产出 |
+//! |---|---|---|
+//! | 服务发现（「校验」按钮） | `GET {apiRoot}` | 服务器名 / skinDomains（`meta` 缺失即判「不是认证服务器」） |
+//! | 登录 | `POST {apiRoot}authserver/authenticate` | `AuthlibSession`（入库，不外传） |
+//! | 皮肤 | `GET {apiRoot}sessionserver/session/minecraft/profile/{uuid}` → textures → 皮肤 URL | 皮肤 PNG 原图 |
+//!
+//! `core::download::http::build_client` 是唯一的 HTTP 基座（复用下载器的客户端配置），
+//! 所以本 crate **不新增任何依赖**（`presenter-no-ui` 与依赖最小化同时成立）。
+
+use unlucky_core::auth::account::{AccountKind as CoreAccountKind, AccountMeta, Credentials};
+use unlucky_core::auth::authlib::{
+    normalize_api_root, AuthlibAuth, AuthlibServerMeta, AuthlibSession,
+};
+use unlucky_core::auth::microsoft::now_ms;
+use unlucky_core::auth::{AccountStore, Secret};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::{AuthlibLoginView, AuthlibRequest, LoginFailure, SkinImage};
+
+mod util;
+
+pub use util::scrub_known;
+
+use util::{base64_decode, client_token, get_bytes, get_text};
+
+use super::super::env::HostEnv;
+use super::super::job::{spawn, HostTask, JobSender};
+use super::LoginJob;
+
+/// 校验认证服务器地址（「校验」按钮的后端）。
+///
+/// # Errors
+///
+/// 地址不合法、网络不可达、HTTP 非 2xx、响应不是 authlib-injector 的服务发现 JSON 时，
+/// 返回**具名**的用户可读文案（这是任务要求的「失败态 + 具名错误」）。
+pub fn probe_authlib(env: &HostEnv, input: &str) -> Result<(String, AuthlibServerMeta), Failure> {
+    let api_root = normalize_api_root(input)
+        .map_err(|error| Failure::new(LoginFailure::Other, error.to_string()))?;
+    let (status, text) =
+        get_text(env, &api_root).map_err(|error| Failure::new(LoginFailure::Unreachable, error))?;
+    if !(200..300).contains(&status) {
+        return Err(Failure::new(
+            LoginFailure::NotAuthlibServer,
+            format!("服务器返回 HTTP {status}（{api_root} 不像可用的 authlib 认证服务器）"),
+        ));
+    }
+    let value: serde_json::Value = serde_json::from_str(&text).map_err(|_| {
+        Failure::new(
+            LoginFailure::NotAuthlibServer,
+            format!("响应不是 JSON：{api_root} —— 可能填成了网页地址，而不是 API 根（通常以 /api/yggdrasil/ 结尾）"),
+        )
+    })?;
+    if value.get("meta").is_none() && value.get("skinDomains").is_none() {
+        return Err(Failure::new(
+            LoginFailure::NotAuthlibServer,
+            "响应里没有 meta / skinDomains：这看起来不是 authlib-injector 服务器",
+        ));
+    }
+    let meta = AuthlibServerMeta::from_value(&value);
+    Ok((api_root, meta))
+}
+
+/// 第三方轨的失败：**原因码 + 原文**（原文进日志，页面据码出 i18n）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Failure {
+    /// 原因码
+    pub code: LoginFailure,
+    /// 原始诊断（已脱敏）
+    pub detail: String,
+}
+
+impl Failure {
+    fn new(code: LoginFailure, detail: impl Into<String>) -> Self {
+        Self {
+            code,
+            detail: detail.into(),
+        }
+    }
+
+    /// `AuthError` → 原因码（只看变体）。
+    fn from_error(error: &unlucky_core::auth::AuthError) -> Self {
+        use unlucky_core::auth::AuthError;
+        let code = match error {
+            AuthError::Network { .. } | AuthError::Timeout { .. } => LoginFailure::Unreachable,
+            AuthError::Denied { .. } => LoginFailure::BadCredentials,
+            AuthError::Store { .. } => LoginFailure::StoreFailed,
+            _ => LoginFailure::Other,
+        };
+        Self::new(code, error.to_string())
+    }
+}
+
+/// 起一次第三方轨登录（后台线程）。
+pub fn start_login(env: HostEnv, tx: JobSender, job: LoginJob, request: AuthlibRequest) {
+    spawn("authlib-login", move || {
+        let mut request = request;
+        // 日志只打脱敏形态；密码在下面用完立刻丢弃。
+        eprintln!("[auth] authlib 登录开始（{}）", request.redacted());
+        stage(&tx, &request.server, "正在校验服务器地址…");
+
+        let (api_root, meta) = match probe_authlib(&env, &request.server) {
+            Ok(found) => found,
+            Err(failure) => return fail(&tx, failure),
+        };
+        let server_name = meta
+            .name
+            .clone()
+            .filter(|name| !name.trim().is_empty())
+            .unwrap_or_else(|| api_root.clone());
+        stage(
+            &tx,
+            &api_root,
+            &format!("服务器 {server_name} 可用，正在登录…"),
+        );
+
+        let auth = match AuthlibAuth::new() {
+            Ok(auth) => auth,
+            Err(error) => return fail(&tx, Failure::new(LoginFailure::Other, error.to_string())),
+        };
+        let client_token = Secret::new(client_token());
+        let password_text = std::mem::take(&mut request.password);
+        let password = Secret::new(password_text.clone());
+        let login_name = request.login.clone();
+        let result = block_on(auth.authenticate(&api_root, &login_name, &password, &client_token));
+        drop(password);
+
+        if job.is_cancelled() {
+            let _ = tx.send(HostTask::Authlib(Box::default()));
+            return;
+        }
+        match result {
+            Ok(session) => match store(&env, session, &api_root, &login_name) {
+                Ok(account) => {
+                    let _ = tx.send(HostTask::Authlib(Box::new(AuthlibLoginView::succeeded(
+                        &server_name,
+                        &account,
+                    ))));
+                    let _ = tx.send(HostTask::Accounts(super::accounts(
+                        &env,
+                        Some(account.as_str()),
+                    )));
+                }
+                Err(failure) => fail(&tx, failure),
+            },
+            // 错误原文里可能有服务端回显的凭据：先按**形状**脱敏（`AuthlibLoginView::failed`），
+            // 再按**已知值**兜一遍（万一服务端把密码原样回显）。
+            Err(error) => {
+                let failure = Failure::from_error(&error);
+                fail(
+                    &tx,
+                    Failure::new(failure.code, scrub_known(&failure.detail, &password_text)),
+                );
+            }
+        }
+        drop(password_text);
+    });
+}
+
+/// 只校验服务器地址（「校验服务器」按钮）；结果走同一条 `AuthlibLoginChanged`。
+pub fn spawn_probe(env: HostEnv, tx: JobSender, server: String) {
+    spawn("authlib-probe", move || {
+        stage(&tx, &server, "正在校验服务器地址…");
+        match probe_authlib(&env, &server) {
+            Ok((api_root, meta)) => {
+                let name = meta
+                    .name
+                    .as_deref()
+                    .map(str::trim)
+                    .filter(|name| !name.is_empty())
+                    .map_or_else(|| api_root.clone(), str::to_string);
+                let _ = tx.send(HostTask::Authlib(Box::new(AuthlibLoginView::reachable(
+                    &api_root, &name,
+                ))));
+            }
+            Err(failure) => fail(&tx, failure),
+        }
+    });
+}
+
+/// 抓第三方轨账户的皮肤原图（`profile_id` → textures → 皮肤 URL → PNG 字节）。
+///
+/// # Errors
+///
+/// 服务器不可达、响应缺 textures、纹理不是 PNG 时返回原因（调用方按「没有皮肤」处理）。
+pub fn fetch_skin(env: &HostEnv, api_root: &str, profile_id: &str) -> Result<SkinImage, String> {
+    let base = normalize_api_root(api_root).map_err(|error| error.to_string())?;
+    let url = format!("{base}sessionserver/session/minecraft/profile/{profile_id}");
+    let (status, text) = get_text(env, &url)?;
+    if !(200..300).contains(&status) {
+        return Err(format!("皮肤接口返回 HTTP {status}"));
+    }
+    let value: serde_json::Value =
+        serde_json::from_str(&text).map_err(|error| format!("皮肤接口响应不是 JSON：{error}"))?;
+    let encoded = value
+        .get("properties")
+        .and_then(|properties| properties.as_array())
+        .and_then(|properties| {
+            properties
+                .iter()
+                .find(|entry| entry.get("name").and_then(|name| name.as_str()) == Some("textures"))
+        })
+        .and_then(|entry| entry.get("value"))
+        .and_then(|value| value.as_str())
+        .ok_or_else(|| "档案里没有 textures 属性".to_string())?;
+    let raw = base64_decode(encoded)?;
+    let textures: serde_json::Value =
+        serde_json::from_slice(&raw).map_err(|error| format!("textures 属性解不开：{error}"))?;
+    let skin_url = textures
+        .get("textures")
+        .and_then(|textures| textures.get("SKIN"))
+        .and_then(|skin| skin.get("url"))
+        .and_then(|url| url.as_str())
+        .ok_or_else(|| "textures 里没有 SKIN 条目".to_string())?;
+    let (status, bytes) = get_bytes(env, skin_url)?;
+    if !(200..300).contains(&status) {
+        return Err(format!("皮肤图片返回 HTTP {status}"));
+    }
+    if !bytes.starts_with(b"\x89PNG") {
+        return Err("皮肤图片不是 PNG".to_string());
+    }
+    Ok(SkinImage {
+        png: bytes,
+        source: skin_url.to_string(),
+    })
+}
+
+/// 入库（元数据 + 凭据分文件）；返回展示名。
+fn store(
+    env: &HostEnv,
+    session: AuthlibSession,
+    api_root: &str,
+    login_name: &str,
+) -> Result<String, Failure> {
+    let profile = session
+        .selected_profile
+        .clone()
+        .filter(|profile| !profile.name.trim().is_empty() && !profile.id.is_empty())
+        .ok_or_else(|| Failure::new(LoginFailure::NoProfile, "服务器没有返回角色"))?;
+    let mut meta = AccountMeta::new(
+        CoreAccountKind::AuthlibInjector,
+        profile.id,
+        profile.name,
+        now_ms(),
+    );
+    meta.login_name = Some(login_name.to_string());
+    meta.server_url = Some(api_root.to_string());
+    let name = meta.display_name().to_string();
+    let mut account_store = AccountStore::open(env.layout.auth_data());
+    account_store
+        .insert(meta, Credentials::AuthlibInjector(session))
+        .and_then(|()| account_store.save())
+        .map_err(|error| Failure::new(LoginFailure::StoreFailed, error.to_string()))?;
+    Ok(name)
+}
+
+/// 发一条「进行中」状态（UI 据此只转圈不误报）。
+fn stage(tx: &JobSender, server: &str, message: &str) {
+    let _ = tx.send(HostTask::Authlib(Box::new(AuthlibLoginView::running(
+        server, message,
+    ))));
+}
+
+/// 失败收尾：**先脱敏再上屏**（服务端错误原文里可能带 token）。
+/// 失败收尾：原文进日志，页面拿**原因码**（复审 r1 P1-1）。
+fn fail(tx: &JobSender, failure: Failure) {
+    eprintln!(
+        "[auth] authlib 失败（{}）：{}",
+        failure.code.code(),
+        failure.detail
+    );
+    let _ = tx.send(HostTask::Authlib(Box::new(AuthlibLoginView::failed_as(
+        failure.code,
+        failure.detail,
+    ))));
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn base64_decodes_textures_payload() {
+        // `{"textures":{}}` 的 base64
+        let encoded = "eyJ0ZXh0dXJlcyI6e319";
+        assert_eq!(base64_decode(encoded).expect("解码"), br#"{"textures":{}}"#);
+        // URL-safe 变体 + 填充 + 换行都要吃
+        assert_eq!(
+            base64_decode("eyJ0ZXh0dXJlcyI6e319\n").expect("解码"),
+            br#"{"textures":{}}"#
+        );
+        assert!(base64_decode("!!!").is_err());
+        assert!(base64_decode("").is_err());
+    }
+
+    #[test]
+    fn client_token_is_stable_length_and_unique() {
+        let a = client_token();
+        let b = client_token();
+        assert_eq!(a.len(), 32);
+        assert_ne!(
+            a, b,
+            "两次生成的 clientToken 不能相同（会被服务端当成重放）"
+        );
+        assert!(a.chars().all(|c| c.is_ascii_hexdigit()));
+    }
+
+    use crate::dto::REDACTED;
+
+    #[test]
+    fn known_secret_is_scrubbed_from_error_text() {
+        let text = scrub_known("登录失败：hunter2 被拒绝", "hunter2");
+        assert!(!text.contains("hunter2"), "{text}");
+        assert!(text.contains(REDACTED));
+        assert_eq!(scrub_known("普通错误", ""), "普通错误");
+    }
+
+    #[test]
+    fn a_web_page_address_is_rejected_with_a_named_error() {
+        // 不发网络请求：只测「规范化 + 空输入」这条不联网的分支
+        let dir = std::env::temp_dir().join(format!("ull-authlib-probe-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.cache()).expect("cache");
+        let failure = probe_authlib(&env, "   ").expect_err("空地址必须报错");
+        assert!(failure.detail.contains("不能为空"), "{failure:?}");
+        let failure = probe_authlib(&env, "https://").expect_err("只给协议头也必须报错");
+        assert!(!failure.detail.is_empty());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}

crates/presenter/src/host/accounts/authlib/util.rs

@@ -0,0 +1,129 @@
+//! authlib 轨的 HTTP 基座与纯函数小工具：`clientToken` 生成、GET 文本/字节、base64 解码、按已知值脱敏。
+//!
+//! 从 `authlib.rs` 拆出来守 400 行硬线。网络只走**既有下载引擎**的客户端
+//! （`host::engine::engine(env).client()`）：代理/超时/证书栈与下载器同源，本 crate 不新增依赖。
+
+use unlucky_core::auth::microsoft::now_ms;
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::REDACTED;
+
+use super::super::super::engine;
+use super::super::super::env::HostEnv;
+
+/// 一次 GET 的超时上限（秒）：服务器不可达时要能失败，而不是挂住 UI 的登录面板。
+pub(super) const HTTP_TIMEOUT_SECS: u64 = 15;
+
+/// 单次 GET 的响应体上限（字节）：用户能填任意 URL，服务发现 JSON/皮肤 PNG 都远小于它。
+pub(super) const MAX_BODY_BYTES: usize = 512 * 1024;
+/// base64 解码输出上限（textures 属性是个小 JSON）。
+pub(super) const MAX_BASE64_BYTES: usize = 64 * 1024;
+
+/// 启动器侧生成的 `clientToken`（Yggdrasil 要求刷新/校验都带，且服务端回传必须一致）。
+pub(super) fn client_token() -> String {
+    use std::hash::{BuildHasher, Hasher};
+    let mut out = String::with_capacity(32);
+    for salt in 0..2u64 {
+        // `RandomState` 每个实例自带随机种子（标准库给的是进程级随机），不引第三方随机库。
+        let mut hasher = std::collections::hash_map::RandomState::new().build_hasher();
+        hasher.write_u64(now_ms() ^ salt);
+        hasher.write_u32(std::process::id());
+        out.push_str(&format!("{:016x}", hasher.finish()));
+    }
+    out
+}
+
+/// GET 文本（状态码 + 正文）。
+///
+/// 客户端来自**既有的下载引擎**（`host::engine::engine`）：代理/超时/证书栈与本仓的下载器
+/// 完全同源，不在这里另起一套 HTTP 配置（本 crate 也没有 reqwest 依赖，拿到的只是它的 `&Client`）。
+pub(super) fn get_text(env: &HostEnv, url: &str) -> Result<(u16, String), String> {
+    let engine = engine::engine(env);
+    let client = engine.client();
+    let url = url.to_string();
+    block_on(async move {
+        let reply = client
+            .get(&url)
+            .timeout(std::time::Duration::from_secs(HTTP_TIMEOUT_SECS))
+            .send()
+            .await
+            .map_err(|error| format!("服务器不可达：{error}"))?;
+        let status = reply.status().as_u16();
+        let text = reply
+            .text()
+            .await
+            .map_err(|error| format!("读取响应失败：{error}"))?;
+        Ok((status, text))
+    })
+}
+
+/// GET 字节（皮肤图片）。
+pub(super) fn get_bytes(env: &HostEnv, url: &str) -> Result<(u16, Vec<u8>), String> {
+    let engine = engine::engine(env);
+    let client = engine.client();
+    let url = url.to_string();
+    block_on(async move {
+        let reply = client
+            .get(&url)
+            .timeout(std::time::Duration::from_secs(HTTP_TIMEOUT_SECS))
+            .send()
+            .await
+            .map_err(|error| format!("皮肤图片不可达：{error}"))?;
+        let status = reply.status().as_u16();
+        let bytes = reply
+            .bytes()
+            .await
+            .map_err(|error| format!("读取皮肤图片失败：{error}"))?
+            .to_vec();
+        if bytes.len() > MAX_BODY_BYTES {
+            return Err(format!(
+                "图片过大（{} 字节，上限 {MAX_BODY_BYTES}）",
+                bytes.len()
+            ));
+        }
+        Ok((status, bytes))
+    })
+}
+
+/// base64 解码（标准字母表，容忍 URL-safe 变体与缺失填充）。
+///
+/// 为什么自己写：textures 属性是 base64 编码的 JSON，而本 crate 不能引第三方解码库
+/// （依赖最小化）；这段是 40 行的确定性算法，配单测比拖一个依赖更划算。
+pub(super) fn base64_decode(input: &str) -> Result<Vec<u8>, String> {
+    let mut out = Vec::with_capacity(input.len() / 4 * 3);
+    let mut buffer: u32 = 0;
+    let mut bits = 0u32;
+    for byte in input.bytes() {
+        let value = match byte {
+            b'A'..=b'Z' => byte - b'A',
+            b'a'..=b'z' => byte - b'a' + 26,
+            b'0'..=b'9' => byte - b'0' + 52,
+            b'+' | b'-' => 62,
+            b'/' | b'_' => 63,
+            b'=' | b'\n' | b'\r' | b' ' => continue,
+            other => return Err(format!("base64 里有非法字符：{:?}", other as char)),
+        };
+        buffer = (buffer << 6) | u32::from(value);
+        bits += 6;
+        if bits >= 8 {
+            bits -= 8;
+            out.push(u8::try_from((buffer >> bits) & 0xFF).unwrap_or(0));
+        }
+        if out.len() > MAX_BASE64_BYTES {
+            return Err(format!("base64 输出超过上限 {MAX_BASE64_BYTES} 字节"));
+        }
+    }
+    if out.is_empty() {
+        return Err("base64 内容为空".to_string());
+    }
+    Ok(out)
+}
+
+/// 错误文案里可能混进已知凭据值：按值再兜一遍（形状脱敏由 `AuthlibLoginView::failed` 做）。
+#[must_use]
+pub fn scrub_known(message: &str, secret: &str) -> String {
+    if secret.is_empty() {
+        return message.to_string();
+    }
+    message.replace(secret, REDACTED)
+}

crates/presenter/src/host/accounts/failure.rs

@@ -0,0 +1,126 @@
+//! 账户写操作的失败分类 + 离线名字契约（M114 r2）。
+//!
+//! 分类**只看 `AuthError` 的变体与 ascii 码**，不看中文文案——文案随时会改，
+//! 而页面据 `AccountNoticeCode` 选 i18n，两边必须能独立演进。
+
+use unlucky_core::auth::AuthError;
+
+use unlucky_core::auth::BodyKind;
+
+use crate::dto::{AccountNoticeCode, LoginFailure};
+
+/// 账户写操作的失败：**结构化码 + 原文**（原文只进日志/详细信息，不上屏）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountFailure {
+    /// 结果码（页面据此选 i18n）
+    pub code: AccountNoticeCode,
+    /// 原始诊断（已脱敏）
+    pub detail: String,
+}
+
+impl AccountFailure {
+    /// 按 core 的错误类型分类（不看中文文案，只看变体）。
+    pub(super) fn classify(error: AuthError, fallback: AccountNoticeCode) -> Self {
+        let code = match &error {
+            unlucky_core::auth::AuthError::Conflict { .. } => AccountNoticeCode::AccountExists,
+            unlucky_core::auth::AuthError::NotFound { .. } => AccountNoticeCode::NotFound,
+            unlucky_core::auth::AuthError::Malformed(_) => AccountNoticeCode::OfflineNameInvalid,
+            unlucky_core::auth::AuthError::Store { .. } => AccountNoticeCode::StoreFailed,
+            _ => fallback,
+        };
+        Self {
+            code,
+            detail: error.to_string(),
+        }
+    }
+}
+
+/// `AuthError` → 原因码（**只看变体与 ascii 码，不看中文文案**）。
+pub(super) fn classify(error: &AuthError) -> LoginFailure {
+    match error {
+        AuthError::Network { .. } | AuthError::Timeout { .. } => LoginFailure::Unreachable,
+        AuthError::Denied { code, description } => {
+            if mentions_whitelist(code) || mentions_whitelist(description) {
+                LoginFailure::NotWhitelisted
+            } else {
+                LoginFailure::Denied
+            }
+        }
+        // 只看 `ResponseDetail` 的**结构化字段**（status / kind / server_message），
+        // 不把整条错误 Debug 成字符串再去扫——那会把中文 `what`/`digest` 也算进判据里。
+        AuthError::Response(detail) => {
+            let server = detail.server_message.as_deref().unwrap_or_default();
+            let digest = detail.digest.as_str();
+            if mentions_whitelist(server) || mentions_whitelist(digest) {
+                LoginFailure::NotWhitelisted
+            } else if detail.status >= 500 || matches!(detail.kind, BodyKind::Html | BodyKind::Text)
+            {
+                // 5xx / 拦截页：服务器或链路出了问题，不是「它拒绝了你」。
+                LoginFailure::Unreachable
+            } else {
+                LoginFailure::Denied
+            }
+        }
+        AuthError::Xbox { .. } | AuthError::CredentialExpired => LoginFailure::Denied,
+        AuthError::Store { .. } => LoginFailure::StoreFailed,
+        _ => LoginFailure::Other,
+    }
+}
+
+/// 是否属于「应用注册未获批」这一类（AADSTS7000218 / consent required / whitelist）。
+pub(super) fn mentions_whitelist(text: &str) -> bool {
+    let lowered = text.to_lowercase();
+    lowered.contains("aadsts7000218")
+        || lowered.contains("aadsts65001")
+        || lowered.contains("consent")
+        || lowered.contains("whitelist")
+        || lowered.contains("not approved")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_core::auth::body::ResponseDetail;
+
+    fn response(status: u16, kind: BodyKind, server_message: Option<&str>) -> AuthError {
+        AuthError::Response(Box::new(ResponseDetail {
+            step: "xsts".to_string(),
+            what: "XSTS 授权".to_string(),
+            status,
+            content_type: None,
+            kind,
+            server_message: server_message.map(str::to_string),
+            digest: "digest".to_string(),
+        }))
+    }
+
+    /// 403 带 AADSTS 码 → 白名单未批；403 不带 → 一般性拒绝。
+    #[test]
+    fn aadsts_markers_win_over_the_generic_denial() {
+        assert_eq!(
+            classify(&response(
+                403,
+                BodyKind::Json,
+                Some("AADSTS7000218: app not approved")
+            )),
+            LoginFailure::NotWhitelisted
+        );
+        assert_eq!(
+            classify(&response(403, BodyKind::Json, Some("invalid_grant"))),
+            LoginFailure::Denied
+        );
+    }
+
+    /// 5xx 与「拦截页」（HTML/纯文本）归「连不上」，不是「服务器拒绝了你」。
+    #[test]
+    fn upstream_failures_and_intercept_pages_are_unreachable() {
+        assert_eq!(
+            classify(&response(503, BodyKind::Json, None)),
+            LoginFailure::Unreachable
+        );
+        assert_eq!(
+            classify(&response(200, BodyKind::Html, None)),
+            LoginFailure::Unreachable
+        );
+    }
+}

crates/presenter/src/host/accounts/refresh.rs

@@ -0,0 +1,66 @@
+//! 账户列表的刷新与皮肤抓取（`impl CoreHost` 的这一段，从 `host/mod.rs` 拆出来守 400 行）。
+//!
+//! 为什么在这里：`host/mod.rs` 在 M109/M113 之后已经贴着 400 行硬线，而这三段是**账户专属**
+//! 的编排（读账户库 → 盖皮肤 → 起抓取线程）。放回 `host/accounts.rs` 也不行——那个文件同样
+//! 380 行。归属仍是 accounts（`mod accounts { mod refresh; }`），只是按功能再分一层。
+
+use crate::dto::{AccountKind, CoreEvent};
+
+use super::super::{accounts, job, CoreHost, HostTask};
+
+impl CoreHost {
+    pub(in crate::host) fn refresh_accounts(&mut self) {
+        self.accounts = accounts::accounts(&self.env, self.active_account.as_deref());
+        if self.active_account.is_none() {
+            // 默认选中第一个账户（没有账户时保持 None = 离线占位）
+            self.active_account = self.accounts.first().map(|account| account.id.clone());
+            self.accounts = accounts::accounts(&self.env, self.active_account.as_deref());
+        }
+        self.attach_skins();
+        self.request_skins();
+        self.send(CoreEvent::AccountsChanged(self.accounts.clone()));
+    }
+
+    /// 把已抓到的皮肤盖到账户视图上。
+    ///
+    /// 只盖第三方轨：离线档案没有皮肤，微软轨不做真头像（M114 口径）——
+    /// 「没有皮肤就画首字母块」，绝不给假皮肤/白块。
+    pub(in crate::host) fn attach_skins(&mut self) {
+        for account in &mut self.accounts {
+            if account.kind != AccountKind::Authlib {
+                account.skin = None;
+                continue;
+            }
+            if let Some(skin) = self.skins.get(&account.id) {
+                account.skin = skin.clone();
+            }
+        }
+    }
+
+    /// 给还没抓过皮肤的第三方轨账户起后台抓取（每个账户只抓一次）。
+    ///
+    /// 抓不到就记 `None`：错误在面板上不显示（皮肤是装饰，不是业务失败），但也不会重试刷屏。
+    fn request_skins(&mut self) {
+        let mut pending = Vec::new();
+        for account in &self.accounts {
+            if account.kind != AccountKind::Authlib || account.server_url.trim().is_empty() {
+                continue;
+            }
+            if self.skin_requested.insert(account.id.clone()) {
+                pending.push((
+                    account.id.clone(),
+                    account.server_url.clone(),
+                    account.profile_id.clone(),
+                ));
+            }
+        }
+        for (id, server, profile) in pending {
+            let tx = self.tx.clone();
+            let env = self.env.clone();
+            job::spawn("account-skin", move || {
+                let skin = accounts::fetch_skin(&env, &server, &profile).ok();
+                let _ = tx.send(HostTask::Avatar { id, skin });
+            });
+        }
+    }
+}

crates/presenter/src/host/accounts/tests.rs

@@ -0,0 +1,187 @@
+//! 账户 host 的判据：入库/删除/名字规则、失败分类，以及**缺 client id 的上屏链路**（M132）。
+//!
+//! ## 为什么这个文件要跟 `accounts.rs` 分开
+//!
+//! `accounts.rs` 顶着 400 行硬线，而 M132 的锚必须**真的走一遍登录入口**（`start_login` /
+//! `start_browser_login`）才能钉住「入口 → 原因码」那一行——只测 `auth_failure` 的话，把调用点
+//! 改回 `LoginFailure::Other` 仍然全绿（复审 r1 P2-1 实测）。测试拆出来是为了留出这段空间。
+//!
+//! 拆法照抄仓库既有先例（`dto/accounts.rs`、`host/install.rs` 等）：父文件里留
+//! `#[cfg(test)] mod tests;`，本文件 `use super::*;` 照旧拿到父模块的一切。
+
+use std::time::Duration;
+
+use unlucky_core::auth::microsoft::{client_id_status, CLIENT_ID_ENV};
+use unlucky_core::auth::AuthError;
+
+use super::*;
+
+use super::failure::mentions_whitelist;
+
+#[test]
+fn time_display_matches_known_timestamps() {
+    assert_eq!(display_ms(0), "");
+    // 1_769_000_000_000 ms = 2026-01-21T12:53:20Z（取整到分钟）
+    assert_eq!(display_ms(1_769_000_000_000), "2026-01-21 12:53");
+}
+
+#[test]
+fn offline_add_list_remove_round_trips() {
+    let dir = std::env::temp_dir().join(format!("ull-host-accounts-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = HostEnv::at_root(&dir);
+    std::fs::create_dir_all(env.layout.auth_data()).expect("auth 目录");
+
+    let name = add_offline(&env, "Steve").expect("加账户");
+    assert_eq!(name, "Steve");
+    let list = accounts(&env, None);
+    assert_eq!(list.len(), 1);
+    assert_eq!(list[0].kind, AccountKind::Offline);
+    assert!(!list[0].active);
+
+    let active = accounts(&env, Some(list[0].id.as_str()));
+    assert!(active[0].active);
+
+    let removed = remove(&env, "Steve").expect("删账户");
+    assert_eq!(removed, "Steve");
+    assert!(accounts(&env, None).is_empty());
+    assert!(add_offline(&env, "  ").is_err());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+fn denied(code: &str) -> AuthError {
+    AuthError::Denied {
+        code: code.to_string(),
+        description: "bad".to_string(),
+    }
+}
+
+fn network() -> AuthError {
+    AuthError::Network {
+        url: "https://x".to_string(),
+        detail: "dns".to_string(),
+    }
+}
+
+#[test]
+fn failure_codes_are_classified_from_variants_not_chinese_text() {
+    assert_eq!(classify(&network()), LoginFailure::Unreachable);
+    let whitelist = classify(&denied("AADSTS7000218"));
+    assert_eq!(whitelist, LoginFailure::NotWhitelisted);
+    assert_eq!(classify(&denied("invalid_grant")), LoginFailure::Denied);
+    assert_eq!(classify(&AuthError::Canceled), LoginFailure::Other);
+    assert!(mentions_whitelist("AADSTS7000218"));
+    assert!(!mentions_whitelist("invalid_grant"));
+}
+
+/// **M132**：只有「缺 client id」变成「需要配置」，网络/凭据失败不许跟着变（否则成噪音）。
+#[test]
+fn only_a_missing_client_id_becomes_the_config_gap_code() {
+    let missing = auth_failure(&AuthError::Unsupported(String::new()));
+    assert_eq!(missing, LoginFailure::MsaNotConfigured);
+    assert_eq!(auth_failure(&network()), LoginFailure::Unreachable);
+    assert_eq!(auth_failure(&denied("invalid_grant")), LoginFailure::Denied);
+}
+
+/// **M132 的入口锚（复审 r1 P2-1）**：缺 client id 时，**两条登录流**回给页面的那条事件里
+/// 必须带 `MsaNotConfigured`。
+///
+/// 抓得住（实测过的变异）：把 `start_login` / `start_browser_login` 里的
+/// `auth_failure(&error)` 改回 `LoginFailure::Other`——那是页面退回「完整原因在启动器日志里」
+/// 的唯一开关，而 `auth_failure` 自己的单测对它一声不响。
+/// 零网络：`MicrosoftAuth::from_env` 在 id 判定处就地早退，连 HTTP 客户端都不建，所以这里
+/// 不需要任何桩，也不会因为没网而红。
+///
+/// **它要求一个「两处都没有 client id」的构建**：构建期烘焙了 id（`option_env!`）的构建里它
+/// `panic!` 而不是跳过——跳过就等于让这条锚悄悄失效（r2 复审实测过那种形态），红着喊人才
+/// 逼得人做决定（不带 id 构建，或给 `resolve_client_id` 加接缝后重写这条锚）。
+#[test]
+fn a_missing_client_id_reaches_the_login_panel_as_a_config_gap() {
+    // 环境变量是**进程级**的：动它的用例必须串行（core 侧同一套写法），否则并行跑互相污染。
+    static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+    let _lock = ENV_LOCK.lock().unwrap_or_else(|error| error.into_inner());
+    let saved = std::env::var(CLIENT_ID_ENV).ok();
+    std::env::remove_var(CLIENT_ID_ENV);
+    // panic 也要还原：不还原的话后面所有用例都会在一个「没配 id」的进程里跑。
+    struct Restore(Option<String>);
+    impl Drop for Restore {
+        fn drop(&mut self) {
+            match self.0.take() {
+                Some(value) => std::env::set_var(CLIENT_ID_ENV, value),
+                None => std::env::remove_var(CLIENT_ID_ENV),
+            }
+        }
+    }
+    let _restore = Restore(saved);
+
+    // 环境变量已经摘掉了，此时若仍报告「已配置」，来源只可能是构建期注入
+    // （`ULL_MSA_CLIENT_ID=<id> cargo build` ⇒ `option_env!`），或者 `resolve_client_id` 的
+    // 实现变了。**这种构建里必须红**：这条锚验证不了缺 id 路径，静默 `return` 就是让锚悄悄失效
+    // （r2 复审实测：注入 id + 同一变异 → 全绿 22 passed，正是塔台最怕的「守门空跑」形态）。
+    if let Some(source) = client_id_status().source() {
+        panic!(
+            "这条锚要求「两处都没有 client id」的构建，但二进制里 client id 已被报告为已配置\
+             （source={source:?}，环境变量 {CLIENT_ID_ENV} 已摘掉）。要么不带 \
+             ULL_MSA_CLIENT_ID 构建，要么给 `unlucky_core::auth::microsoft::resolve_client_id` \
+             加一个可注入的接缝，再按接缝重写这条锚。"
+        );
+    }
+
+    assert_config_gap("device", start_login);
+    assert_config_gap("authcode", start_browser_login);
+}
+
+/// 起一条登录流、等它回的第一条登录事件，并断言那是一条「缺配置」而不是通用失败。
+///
+/// 缺 id 时这条路径**零网络**（`from_env` 在 id 判定处早退），所以事件立刻到，不需要桩。
+fn assert_config_gap(name: &str, start: fn(HostEnv, JobSender, LoginJob)) {
+    let dir = std::env::temp_dir().join(format!("ull-msa-{name}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let (tx, rx) = super::super::job::channel();
+    start(HostEnv::at_root(&dir), tx, LoginJob::new());
+    let view = match rx.recv_timeout(Duration::from_secs(10)) {
+        Ok(HostTask::Login(view)) => view,
+        Ok(_) => panic!("{name}：缺 id 时第一条事件就该是登录失败"),
+        Err(error) => panic!("{name}：等不到登录事件（{error}）"),
+    };
+    assert_eq!(view.failure, Some(LoginFailure::MsaNotConfigured), "{name}");
+    // 原文（含要设的变量名）仍然只在 `message` 里：它只进日志，页面画不出来。
+    assert!(
+        view.message.contains(CLIENT_ID_ENV),
+        "{name}: {}",
+        view.message
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn offline_name_rule_matches_the_ui_contract() {
+    assert!(valid_offline_name("Steve"));
+    assert!(valid_offline_name("a_1"));
+    assert!(!valid_offline_name("ab"), "太短");
+    assert!(!valid_offline_name("中文名字"), "非 ascii");
+    assert!(!valid_offline_name("has space"));
+    assert!(!valid_offline_name("x"));
+}
+
+#[test]
+fn a_bad_offline_name_is_classified_not_stringified() {
+    let dir = std::env::temp_dir().join(format!("ull-name-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = HostEnv::at_root(&dir);
+    std::fs::create_dir_all(env.layout.auth_data()).expect("auth 目录");
+    let failure = add_offline(&env, "ab").expect_err("太短要报错");
+    assert_eq!(failure.code, AccountNoticeCode::OfflineNameInvalid);
+    assert!(!failure.detail.is_empty());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn login_job_cancel_flag_is_shared() {
+    let job = LoginJob::new();
+    let clone = job.clone();
+    assert!(!clone.is_cancelled());
+    job.cancel();
+    assert!(clone.is_cancelled());
+}

crates/presenter/src/host/addon.rs

@@ -0,0 +1,106 @@
+//! 内容库的宿主实现（M109 `CONTENTDL`）：**检索** + **装进指定实例**。
+//!
+//! ## 为什么这些代码在 presenter 而不是 core（临时落点，必须写清）
+//!
+//! `crates/core` 的 `addon` 模块今天只有两件事：加载器安装（`addon::loader`）与整合包**格式**
+//! 解析（`addon::pack`，M110）。它**没有** CurseForge / Modrinth 的 API 客户端，也没有
+//! 「远程整合包一键装进实例」的管线（M111/M112 才做）。而任务书的硬约束是「UI 层不许自己发
+//! HTTP，新增能力一律经 presenter 的 host 转发」——所以本轮把客户端放在这里。
+//!
+//! **长期应下沉到 `core::addon`**（已报 finding）：那时本模块只剩「DTO ↔ 领域类型」的翻译，
+//! 与 `host/versions.rs` 现在的角色一样。
+//!
+//! ## 三条纪律
+//!
+//! | 纪律 | 落点 |
+//! |---|---|
+//! | 网络只在后台线程 | [`spawn_search`] / [`spawn_install`] 走 `job::spawn`，UI 线程只收事件 |
+//! | Modrinth 走 core 的下载引擎 | `addon/http.rs` 的 `download_bytes` 路径带**信号量限流 + 源健康度 + 指数退避**，不另写重试循环 |
+//! | 密钥不进仓库 / 日志 | CF 的 `X-API-KEY` 只从 `ULL_CF_API_KEY` 读，日志只打 `set`/`unset`，DTO 里只有一个 `bool` |
+//!
+//! ## 模块
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`sources`] | 两个站点的 JSON 方言 → [`crate::dto::ContentHit`] |
+//! | `http` | 取文本：无 header 走引擎、带 header 走 client + 退避、百分号编码 |
+//! | `install` | 一键装入：解析文件 → 下载到实例目录 → 进度回流 |
+//!
+//! ## 整合包与 CF 的边界（都写进报告）
+//!
+//! - 整合包**不做**「一键装入」：`ContentKind::Modpack.dir()` 是 `None`，UI 侧按钮禁用带原因，
+//!   host 侧再挡一次（就算绕过 UI 发指令也只回一条 `Failed`）。真流程是 M111 的导入管线。
+//! - CurseForge 本轮只做**检索**（需要用户配 `ULL_CF_API_KEY`），文件解析未接通。
+
+mod http;
+mod install;
+// M113: import/export —— 整合包导入/导出（拆成子目录：父文件只留既有内容 + mod）
+mod pack;
+mod sources;
+
+pub(super) use pack::{cancel_pack, pack_epoch};
+
+#[cfg(test)]
+mod tests;
+
+use std::sync::atomic::AtomicBool;
+use std::sync::Arc;
+
+use crate::dto::{ContentQuery, ContentResults};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 日志里只出现这两种状态，**永远不打密钥本身**。
+const KEY_UNSET: &str = "ULL_CF_API_KEY unset（CurseForge 源不可用）";
+const KEY_SET: &str = "ULL_CF_API_KEY set（CurseForge 源可用）";
+
+/// CurseForge 的密钥（环境变量；空串 / 空白按「没配」处理）。
+///
+/// 为什么不放设置项：core 的 `setting` schema 不在本 mission 的 scope（已登记 finding）。
+/// 环境变量这条路至少满足「不进仓库、不进日志」两条硬要求。
+fn curseforge_key() -> Option<String> {
+    std::env::var("ULL_CF_API_KEY")
+        .ok()
+        .map(|key| key.trim().to_string())
+        .filter(|key| !key.is_empty())
+}
+
+/// CF 源此刻可用吗（页面据此禁用那条来源）。
+#[must_use]
+pub fn curseforge_ready() -> bool {
+    curseforge_key().is_some()
+}
+
+/// 打一行「配没配」的日志（**不含**密钥内容；host 装配时调一次）。
+pub fn log_curseforge_state() {
+    eprintln!(
+        "[content] {}",
+        if curseforge_ready() {
+            KEY_SET
+        } else {
+            KEY_UNSET
+        }
+    );
+}
+
+/// 后台检索（网络在后台线程，UI 不卡）。
+pub fn spawn_search(env: HostEnv, tx: JobSender, query: ContentQuery) {
+    spawn("content", move || {
+        let result: Result<ContentResults, String> = sources::search(&env, &query);
+        let _ = tx.send(HostTask::Content(Box::new(result)));
+    });
+}
+
+/// 后台「装进指定实例」。
+pub fn spawn_install(
+    env: HostEnv,
+    tx: JobSender,
+    request: crate::dto::ContentInstallRequest,
+    cancel: Arc<AtomicBool>,
+    epoch: u64,
+) {
+    spawn("content-install", move || {
+        install::install(&env, &tx, &request, &cancel, epoch);
+    });
+}

crates/presenter/src/host/addon/http.rs

@@ -0,0 +1,123 @@
+//! HTTP 取文本（内容库唯一的网络出口）。
+//!
+//! ## 两条路径，为什么不是一条
+//!
+//! | 请求 | 走哪 | 拿到什么 |
+//! |---|---|---|
+//! | 无自定义 header（Modrinth 的全部请求） | [`DownloadEngine::download_bytes`] | **信号量限流 + 源健康度 + 指数退避 + 分类错误**，全是 core 现成的 |
+//! | 带 header（只有 CurseForge 的 `X-API-KEY`） | `engine.client()` 直发 | 引擎的请求体没有 header 字段，只能自己发；代价是这条路径自己带一个 429/5xx 退避 |
+//!
+//! ## 密钥纪律
+//!
+//! 带 header 的那条路径**只把 header 值喂给请求**：不进日志、不进错误串。错误串里只有 URL
+//! （CF 的 URL 不含密钥）与状态码。
+
+use std::time::Duration;
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::{DownloadRequest, ResourceKind};
+
+use super::super::env::HostEnv;
+
+/// 站点要求的 User-Agent（Modrinth 明文要求带联系方式，否则限流）。
+pub(super) const USER_AGENT: &str =
+    "Unlucky-Launcher/0.1 (+https://github.com/AskaEth/Unlucky-Launcher)";
+
+/// 最多重试次数（含首次）。
+const ATTEMPTS: u32 = 3;
+
+/// 取一段文本（JSON 原文）。
+pub(super) fn get(env: &HostEnv, url: &str, headers: &[(&str, &str)]) -> Result<String, String> {
+    if headers.is_empty() {
+        get_via_engine(env, url)
+    } else {
+        get_with_headers(env, url, headers)
+    }
+}
+
+/// core 的下载引擎：限流与退避都在里面，这里只负责「URL → 文本」。
+fn get_via_engine(env: &HostEnv, url: &str) -> Result<String, String> {
+    let engine = super::super::engine::engine(env);
+    let dir = env.layout.cache().join("content");
+    std::fs::create_dir_all(&dir).map_err(|error| format!("建缓存目录失败：{error}"))?;
+    let request = DownloadRequest::new(ResourceKind::Other, url, dir.join("response.json"));
+    let bytes = block_on(engine.download_bytes(request))
+        .map_err(|error| format!("请求 {url} 失败：{error}"))?;
+    String::from_utf8(bytes).map_err(|error| format!("响应不是 UTF-8：{error}"))
+}
+
+/// 带 header 的请求（只有 CF 走这条）：429 / 5xx / 连接类失败按退避重试。
+fn get_with_headers(env: &HostEnv, url: &str, headers: &[(&str, &str)]) -> Result<String, String> {
+    let engine = super::super::engine::engine(env);
+    let owned: Vec<(String, String)> = headers
+        .iter()
+        .map(|(name, value)| ((*name).to_string(), (*value).to_string()))
+        .collect();
+
+    for attempt in 0..ATTEMPTS {
+        let result = block_on(async {
+            let mut builder = engine.client().get(url).header("User-Agent", USER_AGENT);
+            for (name, value) in &owned {
+                builder = builder.header(name.as_str(), value.as_str());
+            }
+            let response = builder.send().await.map_err(|error| error.to_string())?;
+            let status = response.status();
+            if status.is_success() {
+                return response.text().await.map_err(|error| error.to_string());
+            }
+            let retry = response
+                .headers()
+                .get("retry-after")
+                .and_then(|value| value.to_str().ok())
+                .and_then(|value| value.parse::<u64>().ok());
+            Err(format!("HTTP {} (retry_after={retry:?})", status.as_u16()))
+        });
+
+        match result {
+            Ok(body) => return Ok(body),
+            Err(reason) if attempt + 1 < ATTEMPTS && retryable(&reason) => {
+                std::thread::sleep(retry_after(&reason, attempt));
+            }
+            Err(reason) => return Err(format!("请求 {url} 失败：{reason}")),
+        }
+    }
+    Err(format!("请求 {url} 失败：重试用尽"))
+}
+
+/// 这个失败值得再试一次吗（429 / 5xx / 连接类；**401/403/404 一律不重试**，重试只会更糟）。
+pub(super) fn retryable(reason: &str) -> bool {
+    reason.contains("HTTP 429")
+        || reason.contains("HTTP 500")
+        || reason.contains("HTTP 502")
+        || reason.contains("HTTP 503")
+        || reason.contains("HTTP 504")
+        || reason.contains("error sending request")
+        || reason.contains("timed out")
+}
+
+/// 退避时长：优先吃服务端给的 `Retry-After`（封顶 30s），否则指数退避（1s、2s、4s）。
+pub(super) fn retry_after(reason: &str, attempt: u32) -> Duration {
+    let parsed = reason
+        .split("retry_after=Some(")
+        .nth(1)
+        .and_then(|rest| rest.split(')').next())
+        .and_then(|value| value.parse::<u64>().ok());
+    match parsed {
+        Some(secs) => Duration::from_secs(secs.min(30)),
+        None => Duration::from_secs(1u64 << attempt.min(4)),
+    }
+}
+
+/// 最小百分号编码（query 串用；不为一件小事引第三方 crate）。
+pub(super) fn encode(raw: &str) -> String {
+    let mut out = String::with_capacity(raw.len());
+    for byte in raw.bytes() {
+        match byte {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
+                out.push(char::from(byte));
+            }
+            _ => out.push_str(&format!("%{byte:02X}")),
+        }
+    }
+    out
+}

crates/presenter/src/host/addon/install.rs

@@ -0,0 +1,252 @@
+//! 「一键装入指定实例」（M109）。
+//!
+//! ## 它到底做了什么（诚实版）
+//!
+//! | 内容类型 | 做什么 | 状态 |
+//! |---|---|---|
+//! | Mod / 资源包 / 光影 | 解析「该项目下匹配目标实例（版本 + 加载器）的那个文件」→ core 下载引擎下载到实例运行目录的 `mods/` `resourcepacks/` `shaderpacks/` → 进度经 `InstallProgressView` 回流（**复用下载页那块面板**） | 已接 |
+//! | 整合包 | 一律 `Failed` + 一句原因 | **未做**：core 没有「远程整合包装进实例」的管线（M111） |
+//! | CurseForge 文件解析 | 一律 `Failed` + 一句原因 | **未做**：需要带 key 的文件端点，本轮只做了 CF 的**检索** |
+//!
+//! ## 为什么进度只有阶段级，没有字节条
+//!
+//! 字节级进度要走 `ProgressEmitter`（core 的 tokio 广播），而 presenter 的依赖表里没有
+//! `tokio` / `futures-util`（`Cargo.toml` 不在本 mission 的 scope），拿不到接收端的 `recv()`。
+//! 所以这里给的是**阶段 + 文件名**（`Planning` → `Downloading` → `Done`/`Failed`），
+//! 面板在「进度未知」时本来就只画一行说明、不画条（`download/install.rs` 的既定口径）。
+//! 已登记为后续项：presenter 补 `futures-util` 之后换成字节级。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::{DownloadRequest, ResourceKind};
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::derive_game_dir;
+
+use crate::dto::{
+    loader_facet, ContentInstallRequest, ContentSource, InstallProgressView, InstallStage,
+    InstanceSummary,
+};
+
+use super::super::env::HostEnv;
+use super::super::job::{HostTask, JobSender};
+use super::http::{encode, get};
+use super::sources::MODRINTH;
+
+/// 跑一次装入（同步；由 [`super::spawn_install`] 放进后台线程）。
+pub(super) fn install(
+    env: &HostEnv,
+    tx: &JobSender,
+    request: &ContentInstallRequest,
+    cancel: &AtomicBool,
+    epoch: u64,
+) {
+    let mut progress = InstallProgressView {
+        version: request.title.clone(),
+        instance: request.instance.clone(),
+        loader: request.loader.label().to_string(),
+        files_total: 1,
+        ..InstallProgressView::new()
+    };
+
+    // 整合包：core 没有这条管线（M111），**不**假装能装。UI 侧按钮本来就是禁用的，
+    // 这里再挡一次是为了「绕过 UI 直接发指令」也不会静默做半件事。
+    if request.kind.dir().is_none() {
+        fail(
+            tx,
+            progress,
+            "整合包安装尚未开放；内容库对整合包只做检索",
+            epoch,
+        );
+        return;
+    }
+
+    let _ = tx.send(HostTask::Install {
+        progress: Box::new(progress.clone()),
+        epoch,
+    });
+    match run(env, request, cancel, &mut progress, tx, epoch) {
+        Ok(done) => {
+            progress.stage = InstallStage::Done;
+            progress.files_done = 1;
+            progress.message = done;
+            let _ = tx.send(HostTask::InstallDone {
+                progress: Box::new(progress),
+                result: Ok(request.title.clone()),
+                epoch,
+            });
+        }
+        Err(reason) => {
+            progress.stage = if cancel.load(Ordering::SeqCst) {
+                InstallStage::Cancelled
+            } else {
+                InstallStage::Failed
+            };
+            let _ = tx.send(HostTask::InstallDone {
+                progress: Box::new(progress),
+                result: Err(reason),
+                epoch,
+            });
+        }
+    }
+}
+
+fn fail(tx: &JobSender, mut progress: InstallProgressView, reason: &str, epoch: u64) {
+    progress.stage = InstallStage::Failed;
+    progress.message = reason.to_string();
+    let _ = tx.send(HostTask::InstallDone {
+        progress: Box::new(progress),
+        result: Err(reason.to_string()),
+        epoch,
+    });
+}
+
+/// 真正干活的那一段，返回一句人读的落盘描述。
+fn run(
+    env: &HostEnv,
+    request: &ContentInstallRequest,
+    cancel: &AtomicBool,
+    progress: &mut InstallProgressView,
+    tx: &JobSender,
+    epoch: u64,
+) -> Result<String, String> {
+    let instance = find_instance(env, &request.instance)?;
+    let game_dir = game_dir_of(env, &instance)?;
+    let dir = request
+        .kind
+        .dir()
+        .ok_or_else(|| "该内容类型不支持单文件装入".to_string())?;
+    let target_dir = game_dir.join(dir);
+    std::fs::create_dir_all(&target_dir)
+        .map_err(|error| format!("建目录 {} 失败：{error}", target_dir.display()))?;
+
+    let file = resolve_file(env, request)?;
+    if cancel.load(Ordering::SeqCst) {
+        return Err("已取消（下载开始前）".to_string());
+    }
+    progress.stage = InstallStage::Downloading;
+    progress.message = file.name.clone();
+    let _ = tx.send(HostTask::Install {
+        progress: Box::new(progress.clone()),
+        epoch,
+    });
+
+    let dest = target_dir.join(&file.name);
+    let mut download = DownloadRequest::new(ResourceKind::ModFile, file.url, dest.clone());
+    if let Some(sha1) = file.sha1.as_deref().filter(|hex| !hex.is_empty()) {
+        download = download.with_sha1(sha1);
+    }
+    block_on(super::super::engine::engine(env).download(download))
+        .map_err(|error| format!("下载失败：{error}"))?;
+    Ok(format!("{}（{}）", file.name, dest.display()))
+}
+
+fn find_instance(env: &HostEnv, id: &str) -> Result<InstanceSummary, String> {
+    super::super::game::instances(env)
+        .into_iter()
+        .find(|instance| instance.id == id)
+        .ok_or_else(|| format!("找不到实例 {id}"))
+}
+
+/// 实例的运行目录（D20 覆盖链：实例 `isolation` > 全局 `instances.mode`）。
+fn game_dir_of(env: &HostEnv, instance: &InstanceSummary) -> Result<PathBuf, String> {
+    let global = super::super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &instance.id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?;
+    derive_game_dir(
+        &env.game,
+        &instance.version_id,
+        global,
+        config.as_ref(),
+        None,
+    )
+    .map(|derivation| derivation.game_dir)
+    .map_err(|error| format!("隔离目录派生失败：{error}"))
+}
+
+/// 要下载的那个文件。
+struct RemoteFile {
+    url: String,
+    name: String,
+    sha1: Option<String>,
+}
+
+/// 解析「这个项目下最适合目标实例的那个文件」。
+fn resolve_file(env: &HostEnv, request: &ContentInstallRequest) -> Result<RemoteFile, String> {
+    match request.source {
+        ContentSource::Modrinth => modrinth_file(env, request),
+        ContentSource::Curseforge => Err(
+            "CurseForge 的文件解析未接通（要带 key 的文件端点；见报告「没验的部分」）".to_string(),
+        ),
+    }
+}
+
+fn modrinth_file(env: &HostEnv, request: &ContentInstallRequest) -> Result<RemoteFile, String> {
+    let mut url = format!(
+        "{MODRINTH}/project/{}/version?game_versions={}",
+        request.project,
+        encode(&format!("[\"{}\"]", request.game_version))
+    );
+    if let Some(facet) = loader_facet(request.loader) {
+        url.push_str(&format!("&loaders={}", encode(&format!("[\"{facet}\"]"))));
+    }
+    let body = get(env, &url, &[])?;
+    let json: serde_json::Value = serde_json::from_str(&body)
+        .map_err(|error| format!("Modrinth 版本列表不是合法 JSON：{error}"))?;
+    let versions = json
+        .as_array()
+        .ok_or_else(|| "Modrinth 版本列表不是数组".to_string())?;
+    let first = versions
+        .first()
+        .ok_or_else(|| "这个项目没有匹配目标实例（版本 / 加载器）的文件".to_string())?;
+    let files = first
+        .get("files")
+        .and_then(serde_json::Value::as_array)
+        .ok_or_else(|| "版本里没有 files".to_string())?;
+    // 显式选 `primary: true`（Modrinth 官方口径）：取第一个会拿到 sources jar 这类坑
+    let file = files
+        .iter()
+        .find(|file| {
+            file.get("primary")
+                .and_then(serde_json::Value::as_bool)
+                .unwrap_or(false)
+        })
+        .or_else(|| files.first())
+        .ok_or_else(|| "版本里没有可用文件".to_string())?;
+
+    let url = file
+        .get("url")
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| "文件没有 url".to_string())?;
+    let name = file
+        .get("filename")
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| "文件没有 filename".to_string())?;
+    let sha1 = file
+        .get("hashes")
+        .and_then(|hashes| hashes.get("sha1"))
+        .and_then(serde_json::Value::as_str)
+        .map(ToString::to_string);
+    Ok(RemoteFile {
+        url: url.to_string(),
+        name: safe_file_name(name),
+        sha1,
+    })
+}
+
+/// 只留文件名本身：站点给的名字可能带路径分隔符，落盘前必须砍掉
+/// （与 `core::addon::pack::path` 的穿越双检同一条纪律）。
+pub(super) fn safe_file_name(raw: &str) -> String {
+    let name = raw
+        .rsplit(['/', '\\'])
+        .next()
+        .unwrap_or(raw)
+        .trim()
+        .to_string();
+    if name.is_empty() || name == "." || name == ".." {
+        "download.bin".to_string()
+    } else {
+        name
+    }
+}

crates/presenter/src/host/addon/pack.rs

@@ -0,0 +1,290 @@
+//! 整合包**导入 / 导出**（M113 `PACKUI`）：把 M111/M112 的管线接到内容库页上。
+//!
+//! ## 这里只做「解析目标 + 翻译 + 转发」
+//!
+//! 真正的活全在 core：`addon::import::import_pack`（三种格式 → 实例目录）与
+//! `addon::export::{scan_instance, export_instance}`（实例目录 → `.mrpack` / CF 清单）。
+//! 本模块不重新判定任何东西——三态、逐项原因、三分类全部**逐字段照搬** core 的报告
+//! （[`convert`]），于是「UI 说的」与「管线干的」是同一份事实。
+//!
+//! ## 文件分工（守 400 行）
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | 本文件 | `CoreHost::pack` 落点 + 取消标记 + 三条 spawn 共用的目标解析 |
+//! | [`import`] | 后台导入（探测 → 目标目录 → 管线 → 报告） |
+//! | [`export`] | 后台预检（不写盘）与后台写盘 |
+//! | [`convert`] | core 报告 → DTO（逐字段照搬）+ 小工具 |
+//! | [`diagnose`] | 探测诊断：「看起来像 X，但缺 Y」 |
+//!
+//! ## 导出预检与写盘用同一套判据
+//!
+//! core 的 `export_instance` 没有 dry-run 入口（已报 finding）。预检用 `scan_instance` +
+//! 「离线目录 ⇒ 一律内联」这条事实拼出来：`RemoteCatalog` 目前只有 `OfflineCatalog`，
+//! 所以每个可扫文件都证明不了可被远程替代 ⇒ 内联；`SkippedLocal` 就是「无法导出」。
+//! `tests::preview_counts_match_the_written_report` 用真管线钉住这个等式。
+//!
+//! ## 取消是**界面级**的
+//!
+//! [`cancel_pack`] 置模块级标记 + `dispatch` 里的 `CancelInstall` 把代次 +1：
+//!
+//! 1. 面板立刻收回（不是等后台回一句话）；
+//! 2. 这一轮之后回来的事件因代次不符被 `handle` 丢掉；
+//! 3. **后台那次导入会继续跑到结束**——core 的 `ImportRequest` 没有取消令牌，进度回调也拿不到
+//!    控制流。所以「取消」的真实含义是「不再显示、结果作废」，不是「把它停手」。要真停必须给
+//!    core 加 cancel token（已登记 finding，报告里同样划出来）；
+//! 4. **提示语不能借用安装那条**（复审 r1 P1-2）：下载页的取消 toast 写着「实例未创建」，
+//!    而导入会把实例**登记上**。所以 `cancel_pack()` 回一个「刚才有没有导入在跑」，
+//!    `dispatch` 据此改发 [`crate::dto::PackEvent::Cancelled`]，界面上换成
+//!    「导入会在后台继续跑完 —— 本次结果作废」这句。
+
+mod convert;
+mod diagnose;
+mod export;
+mod import;
+
+#[cfg(test)]
+mod tests;
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::addon::export::{read_instance_snapshot, InstanceSnapshot};
+use unlucky_core::addon::pack::PackFormat;
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::derive_game_dir;
+
+use crate::dto::{
+    CoreEvent, ExportRequestView, ImportProgressView, InstanceId, PackCommand, PackEvent,
+    PackFormatView,
+};
+
+use super::super::env::HostEnv;
+use super::super::job::{HostTask, JobSender};
+
+/// pack 的**每 host** 状态：代次 + 在跑计数 + 本次运行的取消标记。
+///
+/// ## 为什么不是裸静态量（复审 r2 P3-6 要的那句回答）
+///
+/// 裸静态量是**跨 host 共享**的。生产路径只有一个 host 所以看不出来，但测试里两个 host 会互相
+/// 干扰 —— 本轮实测撞到过：`host/cancel_tests` 派一次 `CancelInstall` 就把我这条用例在飞的导入
+/// 事件按代次丢了。键取 `LauncherLayout::home()`（每个测试的临时根都不同），于是各自独立：
+///
+/// - **代次**：每个 host 一条，`handle` 只跟**自己这个 host** 的当前值比；
+/// - **在跑计数**：一张计数表（每个 host 一格），由 [`InFlight`] 的 `Drop` 维护；
+/// - **取消标记**：每个 host 一份 `Arc<AtomicBool>`，导入线程拿克隆，`cancel_pack` 置位。
+///
+/// 为什么不挪进 `CoreHost`：那要给 `host/mod.rs` 加字段（不在本 mission 的 scope）。这张表等价，
+/// 只是把「每 host 的字段」放在模块里；`host/mod.rs` 一旦进 scope，搬过去只是把这张表删掉。
+#[derive(Default, Clone, Copy)]
+struct HostPackState {
+    epoch: u64,
+    in_flight: usize,
+}
+
+static PACK_STATE: Mutex<Vec<(PathBuf, HostPackState)>> = Mutex::new(Vec::new());
+static PACK_CANCEL: Mutex<Vec<(PathBuf, Arc<AtomicBool>)>> = Mutex::new(Vec::new());
+
+/// 这张表的键（数据根；`HostEnv::at_root` 的每个测试根都不同）。
+fn host_key(env: &HostEnv) -> PathBuf {
+    env.layout.home().to_path_buf()
+}
+
+fn with_state<T>(env: &HostEnv, body: impl FnOnce(&mut HostPackState) -> T) -> T {
+    let key = host_key(env);
+    let mut table = PACK_STATE
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    if let Some(index) = table.iter().position(|(name, _)| *name == key) {
+        return body(&mut table[index].1);
+    }
+    table.push((key, HostPackState::default()));
+    body(&mut table.last_mut().expect("刚插入").1)
+}
+
+/// 这个 host 当前的 pack 代次（`handle` 用它判断事件是否已被取消/关面板作废）。
+pub(in crate::host) fn pack_epoch(env: &HostEnv) -> u64 {
+    with_state(env, |state| state.epoch)
+}
+
+/// 作废这个 host 在飞的一切 pack 事件（取消 / 关面板都走它）。
+pub(in crate::host) fn bump_pack_epoch(env: &HostEnv) -> u64 {
+    with_state(env, |state| {
+        state.epoch = state.epoch.wrapping_add(1);
+        state.epoch
+    })
+}
+
+/// 这个 host 现在有几条导入在跑。
+pub(in crate::host) fn in_flight(env: &HostEnv) -> usize {
+    with_state(env, |state| state.in_flight)
+}
+
+/// 「这次导入还在跑」的 **RAII 句柄**。
+///
+/// 复审 r2 P2-1 的教训：手工 `finished()` 只在 `block_on(import_pack(..))` 之后调用，
+/// 而失败早退（探测失败 / 目标目录不可用）都在它之前 ⇒ 计数永远留在「在跑」，于是下一次
+/// **下载页**的「取消安装」不再发 `InstallCancelled`，还给内容库画一句「导入还在后台跑」的假话。
+///
+/// 现在计数由句柄的 `Drop` 负责：**任何**退出路径（早退、报错、`?`、panic 展开）都会减一。
+pub(super) struct InFlight {
+    env: HostEnv,
+}
+
+impl InFlight {
+    /// 计一次「在跑」。句柄活多久，这次导入就算跑多久。
+    pub(super) fn begin(env: &HostEnv) -> Self {
+        with_state(env, |state| state.in_flight += 1);
+        Self { env: env.clone() }
+    }
+}
+
+impl Drop for InFlight {
+    fn drop(&mut self) {
+        with_state(&self.env, |state| {
+            state.in_flight = state.in_flight.saturating_sub(1);
+        });
+    }
+}
+
+/// 取消这个 host 正在跑的导入（`CancelInstall` 与「关面板」都走它；没在跑时是 no-op）。
+///
+/// 返回值 = 「刚才确实有一次导入在跑」。调用方据此决定提示语：**导入的取消不是 install 的取消**
+/// （后台会跑完并登记实例，见模块文档），所以不能复用下载页那条「安装已取消、实例未创建」。
+pub(in crate::host) fn cancel_pack(env: &HostEnv) -> bool {
+    let key = host_key(env);
+    {
+        let table = PACK_CANCEL
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner());
+        if let Some((_, cancel)) = table.iter().find(|(name, _)| *name == key) {
+            cancel.store(true, Ordering::SeqCst);
+        }
+    }
+    bump_pack_epoch(env);
+    in_flight(env) > 0
+}
+
+/// 这个 host 新一次导入的取消标记（挂进表里供 [`cancel_pack`] 用）。
+fn fresh_cancel(env: &HostEnv) -> Arc<AtomicBool> {
+    let cancel = Arc::new(AtomicBool::new(false));
+    let key = host_key(env);
+    let mut table = PACK_CANCEL
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    match table.iter_mut().find(|(name, _)| *name == key) {
+        Some((_, slot)) => *slot = Arc::clone(&cancel),
+        None => table.push((key, Arc::clone(&cancel))),
+    }
+    cancel
+}
+
+/// `AppCommand::Pack` 的落点（M113）。
+impl super::super::CoreHost {
+    pub(crate) fn pack(&mut self, command: PackCommand) {
+        let epoch = pack_epoch(&self.env);
+        match command {
+            PackCommand::Import(request) => {
+                let cancel = fresh_cancel(&self.env);
+                // 句柄在**派发点**就计上，随线程一起结束（含早退与 panic）
+                let guard = InFlight::begin(&self.env);
+                // 先把面板点亮：用户点了就有反应，不等后台回第一条进度
+                let name = request
+                    .instance_name
+                    .clone()
+                    .or_else(|| request.instance.clone())
+                    .unwrap_or_default();
+                self.send(CoreEvent::Pack(Box::new(PackEvent::Progress(Some(
+                    Box::new(ImportProgressView::new(name)),
+                )))));
+                import::spawn_import(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    *request,
+                    epoch,
+                    cancel,
+                    guard,
+                );
+            }
+            PackCommand::Export(request) => {
+                export::spawn_preview(self.env.clone(), self.tx.clone(), *request, epoch);
+            }
+            PackCommand::Confirm(request) => {
+                export::spawn_write(self.env.clone(), self.tx.clone(), *request, epoch);
+            }
+            PackCommand::Dismiss => {
+                // 只作废 pack 自己的代次：**不碰** `install_epoch`（那是下载页安装的命门）
+                cancel_pack(&self.env);
+                self.send(CoreEvent::Pack(Box::new(PackEvent::Cleared)));
+            }
+        }
+    }
+}
+
+/// 后台任务 → host 的一跳（三个 spawn 共用）。
+pub(super) fn send(tx: &JobSender, epoch: u64, event: PackEvent) {
+    let _ = tx.send(HostTask::Pack {
+        event: Box::new(event),
+        epoch,
+    });
+}
+
+/// 实例 → 运行目录（与 `addon/install.rs` 同一条派生：实例隔离档 > 全局档）。
+pub(super) fn instance_root(env: &HostEnv, id: &InstanceId) -> Result<PathBuf, String> {
+    let instance = super::super::game::instances(env)
+        .into_iter()
+        .find(|instance| &instance.id == id)
+        .ok_or_else(|| format!("instance not found: {id}"))?;
+    let global = super::super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &instance.id)
+        .map_err(|error| format!("read instance config failed: {error}"))?;
+    derive_game_dir(
+        &env.game,
+        &instance.version_id,
+        global,
+        config.as_ref(),
+        None,
+    )
+    .map(|derivation| derivation.game_dir)
+    .map_err(|error| format!("derive game dir failed: {error}"))
+}
+
+/// 实例快照（清单的 `game` + `dependencies` 从它来）。读不出来就返回 `None`，
+/// 由 core 自己按 `root/versions/` 再试一次（失败会给具名错误）。
+pub(super) fn snapshot_of(env: &HostEnv, id: &InstanceId) -> Option<InstanceSnapshot> {
+    let instance = super::super::game::instances(env)
+        .into_iter()
+        .find(|instance| &instance.id == id)?;
+    // 隔离实例的 `versions/` 在全局根下，所以试全局根
+    read_instance_snapshot(env.game.root(), Some(&instance.version_id)).ok()
+}
+
+/// 格式视图 → core 的静态格式（MultiMC 只读，不能当导出目标）。
+pub(super) fn format_of(format: PackFormatView) -> Result<&'static dyn PackFormat, String> {
+    use unlucky_core::addon::pack::{curseforge, modrinth};
+    match format {
+        PackFormatView::Modrinth => Ok(&modrinth::MODRINTH),
+        PackFormatView::Curseforge => Ok(&curseforge::CURSEFORGE),
+        PackFormatView::Multimc => {
+            Err("MultiMC / Prism can only be imported, not exported".to_string())
+        }
+    }
+}
+
+/// 缺省落盘路径：`<data>/exports/<name>-<version>.<ext>`。
+pub(super) fn default_export_path(env: &HostEnv, request: &ExportRequestView) -> PathBuf {
+    let ext = match request.format {
+        PackFormatView::Curseforge => "zip",
+        _ => "mrpack",
+    };
+    let name = format!(
+        "{}-{}",
+        convert::slug(&request.name),
+        convert::slug(&request.version)
+    );
+    env.layout
+        .data()
+        .join("exports")
+        .join(format!("{name}.{ext}"))
+}

crates/presenter/src/host/addon/pack/convert.rs

@@ -0,0 +1,256 @@
+//! core 报告 → DTO（M113）：**逐字段照搬，不重算任何结论**。
+//!
+//! 这一层的唯一职责是翻译：三态、五阶段、四种处置、三种冲突成因、十一种导出原因，
+//! 全部一一对应。任何一个「顺手换算一下」都会让 UI 说的和管线干的不是一回事，
+//! 所以这里没有一处 re-derive（唯一例外是把 `&'static str` 的稳定码换成人读串）。
+//!
+//! 翻译用的是 core 的稳定 slug（`as_str()`）+ DTO 的 `from_slug()`，
+//! 于是「翻译表」本身就是一份可审计的清单：core 加了新变体，`from_slug` 返回 `None`
+//! 时这里会落到一个有名字的兜底，而不是悄悄画成别的意思。
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::addon::export::{ExportReport, FileClass, FileReason};
+use unlucky_core::addon::import::{
+    ConflictChoice, ConflictFile, ConflictReason, FileAction, ImportError, ImportProgress,
+    ImportReport, LoaderTarget, MissingReason,
+};
+
+use crate::dto::{
+    ConflictChoiceView, ConflictFileView, ConflictReasonView, ExportClassView, ExportDoneView,
+    ExportReasonView, FileActionView, ImportErrorView, ImportProgressView, ImportReportView,
+    ImportStageView, ImportStatusView, ImportedFileView, MissingFileView, MissingReasonView,
+    PackFormatView,
+};
+
+/// 一次导入结果 → DTO。
+pub(super) fn report_view(report: &ImportReport, target: &Path) -> ImportReportView {
+    ImportReportView {
+        status: ImportStatusView::from_slug(report.status.as_str())
+            .unwrap_or(ImportStatusView::Failed),
+        format: report.format.as_deref().and_then(PackFormatView::from_slug),
+        pack_name: report.pack_name.clone(),
+        pack_version: report.pack_version.clone(),
+        game_version: report.game_version.clone(),
+        loader: report.loader.as_ref().map(loader_label),
+        version_id: report.version_id.clone(),
+        target: target.to_path_buf(),
+        files: report
+            .files
+            .iter()
+            .map(|file| ImportedFileView {
+                path: file.path.clone(),
+                action: action_view(file.action),
+                bytes: file.bytes,
+            })
+            .collect(),
+        conflicts: report.conflicts.iter().map(conflict_view).collect(),
+        missing: report
+            .missing
+            .iter()
+            .map(|file| MissingFileView {
+                path: file.path.clone(),
+                display: file.display.clone(),
+                reason: missing_view(file.reason),
+                detail: file.detail.clone(),
+            })
+            .collect(),
+        rejected: report
+            .rejected_components
+            .iter()
+            .map(|component| match &component.version {
+                Some(version) => format!("{} {version}", component.uid),
+                None => component.uid.clone(),
+            })
+            .collect(),
+        warnings: report
+            .warnings
+            .iter()
+            .map(|issue| issue.message.clone())
+            .collect(),
+        error: report.error.as_ref().map(error_view),
+        registered: report
+            .registered
+            .as_ref()
+            .map(|registered| registered.name.clone()),
+        bytes_written: report.bytes_written,
+        rolled_back: report.rolled_back,
+    }
+}
+
+/// 一次导出结果 → DTO。
+pub(super) fn done_view(report: &ExportReport) -> ExportDoneView {
+    ExportDoneView {
+        path: report.path.clone(),
+        bytes: report.bytes,
+        remote: u32::try_from(report.remote_count()).unwrap_or(u32::MAX),
+        inline: u32::try_from(report.inline_count()).unwrap_or(u32::MAX),
+        skipped: u32::try_from(report.skipped_count()).unwrap_or(u32::MAX),
+    }
+}
+
+/// 一条导入进度 → DTO。
+pub(super) fn progress_view(progress: &ImportProgress, pack: &str) -> ImportProgressView {
+    ImportProgressView {
+        stage: ImportStageView::from_slug(progress.stage.as_str())
+            .unwrap_or(ImportStageView::Probe),
+        done: u32::try_from(progress.done).unwrap_or(u32::MAX),
+        total: u32::try_from(progress.total).unwrap_or(u32::MAX),
+        current: progress.current.clone(),
+        pack: pack.to_string(),
+    }
+}
+
+/// 致命失败 → DTO（稳定码原样带走，日志与 `--json` 用的是同一串）。
+fn error_view(error: &ImportError) -> ImportErrorView {
+    ImportErrorView {
+        code: error.kind().as_str().to_string(),
+        label: error.kind().label().to_string(),
+        message: error.message().to_string(),
+        hint: error.hint().map(str::to_string),
+    }
+}
+
+fn conflict_view(file: &ConflictFile) -> ConflictFileView {
+    ConflictFileView {
+        path: file.path.clone(),
+        reason: match file.reason {
+            ConflictReason::UserModified => ConflictReasonView::UserModified,
+            ConflictReason::UserDeleted => ConflictReasonView::UserDeleted,
+            ConflictReason::PreExisting => ConflictReasonView::PreExisting,
+        },
+        choice: match file.choice {
+            ConflictChoice::KeepUser => ConflictChoiceView::KeepUser,
+            ConflictChoice::Overwrite => ConflictChoiceView::Overwrite,
+        },
+        pack_sha1: file.pack_sha1.clone(),
+        base_sha1: file.base_sha1.clone(),
+        disk_sha1: file.disk_sha1.clone(),
+        pack_size: file.pack_size,
+    }
+}
+
+const fn action_view(action: FileAction) -> FileActionView {
+    match action {
+        FileAction::Installed => FileActionView::Installed,
+        FileAction::Replaced => FileActionView::Replaced,
+        FileAction::SkippedIdentical => FileActionView::SkippedIdentical,
+        FileAction::KeptUser => FileActionView::KeptUser,
+    }
+}
+
+const fn missing_view(reason: MissingReason) -> MissingReasonView {
+    match reason {
+        MissingReason::Offline => MissingReasonView::Offline,
+        MissingReason::NoSource => MissingReasonView::NoSource,
+        MissingReason::FetchFailed => MissingReasonView::FetchFailed,
+    }
+}
+
+pub(super) fn reason_view(reason: FileReason) -> ExportReasonView {
+    ExportReasonView::from_slug(reason.as_str()).unwrap_or(ExportReasonView::Unreadable)
+}
+
+pub(super) fn class_view(class: FileClass) -> ExportClassView {
+    match class {
+        FileClass::Remote => ExportClassView::Remote,
+        FileClass::Inline => ExportClassView::Inline,
+        FileClass::Skipped => ExportClassView::Skipped,
+    }
+}
+
+/// 加载器 → 人读串（`fabric-loader 0.15.11` / `vanilla 1.20.1`）。
+fn loader_label(target: &LoaderTarget) -> String {
+    format!("{} {}", target.kind.as_str(), target.loader_version)
+}
+
+/// 「命令跑起来了，但目标实例不可用」这类**host 侧**失败的报告。
+///
+/// 仍然走三态里的 `Failed`：界面只有一种失败形状，用户不用学第二套。
+/// `target` 是**目标实例目录**（不知道就给空路径），不是包路径（复审 r1 P2-9 顺手纠的 DTO 语义）。
+pub(super) fn failed_report(
+    target: PathBuf,
+    pack: &Path,
+    code: &str,
+    label: &str,
+    message: &str,
+) -> ImportReportView {
+    ImportReportView {
+        status: ImportStatusView::Failed,
+        format: None,
+        pack_name: Some(pack_stem(pack)),
+        pack_version: None,
+        game_version: None,
+        loader: None,
+        version_id: None,
+        target,
+        files: Vec::new(),
+        conflicts: Vec::new(),
+        missing: Vec::new(),
+        rejected: Vec::new(),
+        warnings: Vec::new(),
+        error: Some(ImportErrorView {
+            code: code.to_string(),
+            label: label.to_string(),
+            message: message.to_string(),
+            hint: None,
+        }),
+        registered: None,
+        bytes_written: 0,
+        rolled_back: true,
+    }
+}
+
+/// 包文件名（`Better MC.mrpack` → `Better MC`）。
+pub(super) fn pack_stem(pack: &Path) -> String {
+    pack.file_stem()
+        .map(|stem| stem.to_string_lossy().to_string())
+        .unwrap_or_else(|| "imported-pack".to_string())
+}
+
+/// **实例目录名**：ASCII 化 + 必要时补一段内容哈希。
+///
+/// 判据（复审 r2 P2-2 之后与注释对齐）：名字里**只含** ASCII 字母数字、空格、`-`、`_` 时
+/// 保持原样（空格折成 `-`，`Better MC` → `Better-MC`）；**一旦折过别的字符**（中文、`.`、
+/// 括号……）就补 `-<hash8>`，用原名的哈希保住区分度 —— 否则「我的整合包」「另一个整合包」
+/// 都会得到 `pack`，第二个中文名导入直接撞「directory already exists」。
+pub(super) fn dir_name(name: &str) -> String {
+    let base = slug(name);
+    let faithful = !name.is_empty()
+        && name
+            .chars()
+            .all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || ch == ' ');
+    if faithful {
+        base
+    } else {
+        format!("{base}-{}", hash8(name))
+    }
+}
+
+/// FNV-1a 64 → 8 位十六进制（只要稳定、短、不需要密码学强度）。
+fn hash8(text: &str) -> String {
+    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
+    for byte in text.as_bytes() {
+        hash ^= u64::from(*byte);
+        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
+    }
+    format!("{:08x}", hash as u32)
+}
+
+/// 目录/文件名用的 slug（只留 ASCII 字母数字与 `-` / `_`，其余折成 `-`）。
+pub(super) fn slug(text: &str) -> String {
+    let mut out = String::new();
+    for ch in text.chars() {
+        if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' {
+            out.push(ch);
+        } else if !out.ends_with('-') {
+            out.push('-');
+        }
+    }
+    let trimmed = out.trim_matches('-').to_string();
+    if trimmed.is_empty() {
+        "pack".to_string()
+    } else {
+        trimmed
+    }
+}

crates/presenter/src/host/addon/pack/diagnose.rs

@@ -0,0 +1,104 @@
+//! 探测诊断（M113）：「这个包**看起来像** X，但**缺** Y」。
+//!
+//! ## 为什么由 host 判，不引 core 改动
+//!
+//! core 的 `PackRegistry::detect` 只回答「谁认领」，一个都不认领时只给一句
+//! `pack_unsupported` + 「试过哪些格式」。而用户手里那个包往往**差一点点**就是某个已知格式
+//! （CF 导出漏了 `manifest.json`、mrpack 被浏览器改名成 `.zip` 后解压丢了 index）。
+//! 判断「像哪个」要看包内到底有哪些标记文件，这是宿主层拿着 `PackArchive` 才看得见的事。
+//!
+//! ## 判据只有标记文件的有无（不看文件名）
+//!
+//! | 格式 | 标记 | 邻居（有它但没标记 ⇒ 「像它」） |
+//! |---|---|---|
+//! | CurseForge | `manifest.json` | `overrides/` · `mods/` |
+//! | Modrinth | `modrinth.index.json` | `overrides/` |
+//! | MultiMC / Prism | `mmc-pack.json` | `instance.cfg` · `.minecraft/` |
+//!
+//! `saw` 只留前 5 条有代表性的标记：长路径往界面里倒会把版面撑破（塔台复审提过）。
+//! 一个标记都没认出来时 `saw` 为空，由界面显示「nothing recognisable」而不是一行空白。
+
+use std::path::Path;
+
+use unlucky_core::addon::pack::{PackArchive, PackLimits, PackRegistry};
+
+use crate::dto::{PackFormatView, ProbeView};
+
+/// 诊断一个包（`None` = 有个格式认领它，正常走管线）。
+pub(super) fn of(pack: &Path) -> Option<ProbeView> {
+    let archive = match PackArchive::open(pack, PackLimits::default()) {
+        Ok(archive) => archive,
+        Err(error) => {
+            // 连 zip 都打不开（选错文件 / 下了一半）：也要说清楚是哪一步失败的
+            return Some(ProbeView {
+                looks_like: None,
+                missing: Vec::new(),
+                saw: Vec::new(),
+                detail: format!("could not open the archive: {error}"),
+            });
+        }
+    };
+    let registry = PackRegistry::builtin();
+    if registry.detect(&archive).is_ok() {
+        return None;
+    }
+
+    // (格式, 标记文件, 邻居标记)
+    let rules: [(PackFormatView, &str, &[&str]); 3] = [
+        (
+            PackFormatView::Curseforge,
+            "manifest.json",
+            &["overrides/", "mods/"],
+        ),
+        (
+            PackFormatView::Modrinth,
+            "modrinth.index.json",
+            &["overrides/"],
+        ),
+        (
+            PackFormatView::Multimc,
+            "mmc-pack.json",
+            &["instance.cfg", ".minecraft/"],
+        ),
+    ];
+
+    // 目录输入的条目名**没有尾斜杠**（`overrides` 而不是 `overrides/`），zip 里目录条目也可能缺；
+    // 所以匹配同时认「精确 / 前缀 / 去掉尾斜杠」三种写法，判据仍然只有标记文件的有无。
+    let names: Vec<&str> = archive.entries().iter().map(|entry| entry.name()).collect();
+    let has = |needle: &str| {
+        names.iter().any(|name| {
+            *name == needle || name.starts_with(needle) || *name == needle.trim_end_matches('/')
+        })
+    };
+
+    let mut saw: Vec<String> = Vec::new();
+    let mut best: Option<(PackFormatView, String)> = None;
+    for (format, marker, neighbours) in rules {
+        let hits: Vec<&str> = neighbours
+            .iter()
+            .copied()
+            .filter(|entry| has(entry))
+            .collect();
+        if hits.is_empty() {
+            continue;
+        }
+        if !has(marker) {
+            // 有邻居、没标记 ⇒ 「像它，但缺那个标记」
+            saw.extend(hits.iter().map(|entry| (*entry).to_string()));
+            if best.is_none() {
+                best = Some((format, marker.to_string()));
+            }
+        }
+    }
+    saw.sort();
+    saw.dedup();
+    saw.truncate(5);
+
+    let detail = format!("tried: {}", registry.ids().join(" / "));
+    Some(ProbeView {
+        looks_like: best.as_ref().map(|(format, _)| *format),
+        missing: best.map(|(_, marker)| vec![marker]).unwrap_or_default(),
+        saw,
+        detail,
+    })
+}

crates/presenter/src/host/addon/pack/export.rs

@@ -0,0 +1,132 @@
+//! 导出（M113）：**预检不写盘**，写盘是另一次调用，两次用同一套判据。
+//!
+//! 预检的全部依据就是 core 的 `scan_instance` + 「没有远程目录 ⇒ 一律内联」：
+//! `RemoteCatalog` 目前只有 `OfflineCatalog`，任何文件都证明不了可被远程替代。所以
+//! 「将内联 N / 无法导出 M」里的 N 是扫到的文件数、M 是 `SkippedLocal`（符号链接 / 路径不安全 /
+//! 读不出来）。写盘走 `export_instance`（同样注入离线目录），
+//! `tests::preview_counts_match_the_written_report` 用真管线钉住两边相等。
+
+use unlucky_core::addon::export::{
+    export_instance, scan_instance, ExportRequest, OfflineCatalog, DEFAULT_CONTENT_ROOTS,
+};
+
+use crate::dto::{
+    ExportClassView, ExportFileView, ExportPreviewView, ExportReasonView, ExportRequestView,
+    PackEvent,
+};
+
+use super::super::super::env::HostEnv;
+use super::super::super::job::{spawn, JobSender};
+use super::convert::{class_view, done_view, reason_view};
+use super::send;
+
+/// 起一个后台预检线程（**不写盘**）。
+pub(super) fn spawn_preview(env: HostEnv, tx: JobSender, request: ExportRequestView, epoch: u64) {
+    spawn("pack-export-preview", move || {
+        let root = match super::instance_root(&env, &request.instance) {
+            Ok(root) => root,
+            Err(reason) => {
+                send(&tx, epoch, PackEvent::ExportFailed(reason));
+                return;
+            }
+        };
+        send(
+            &tx,
+            epoch,
+            PackEvent::Preview(Box::new(preview_of(&root, &env, &request))),
+        );
+    });
+}
+
+/// 预检的**纯函数部分**（不起线程、不写盘）：扫描 → 三分类计数。
+///
+/// 抽出来是为了能测：`tests::preview_counts_match_the_written_report` 用它和
+/// `export_instance` 的真实报告对数字，等式不成立就红。
+pub(super) fn preview_of(
+    root: &std::path::Path,
+    env: &HostEnv,
+    request: &ExportRequestView,
+) -> ExportPreviewView {
+    let target = request
+        .target
+        .clone()
+        .unwrap_or_else(|| super::default_export_path(env, request));
+    let roots: Vec<String> = DEFAULT_CONTENT_ROOTS
+        .iter()
+        .map(|entry| (*entry).to_string())
+        .collect();
+    let (files, skipped) = scan_instance(root, &roots);
+
+    let mut rows: Vec<ExportFileView> = files
+        .iter()
+        .map(|file| ExportFileView {
+            path: file.path.clone(),
+            class: ExportClassView::Inline,
+            reason: ExportReasonView::NoRemoteMatch,
+            bytes: file.bytes,
+            disabled: file.disabled,
+        })
+        .collect();
+    rows.extend(skipped.iter().map(|file| ExportFileView {
+        path: file.path.clone(),
+        class: class_view(file.reason.class()),
+        reason: reason_view(file.reason),
+        bytes: 0,
+        disabled: false,
+    }));
+    // 与 `ExportReport::files` 同一条顺序（按路径）
+    rows.sort_by(|left, right| left.path.cmp(&right.path));
+
+    ExportPreviewView {
+        format: request.format,
+        instance: request.instance.clone(),
+        name: request.name.clone(),
+        version: request.version.clone(),
+        target,
+        files: rows,
+        notes: vec![
+            "No remote catalogue yet: every file has to be inlined into overrides/".to_string(),
+            "Unreadable files, symlinks and unsafe paths are listed below, one by one".to_string(),
+        ],
+    }
+}
+
+/// 起一个后台写盘线程。
+pub(super) fn spawn_write(env: HostEnv, tx: JobSender, request: ExportRequestView, epoch: u64) {
+    spawn("pack-export", move || {
+        let root = match super::instance_root(&env, &request.instance) {
+            Ok(root) => root,
+            Err(reason) => {
+                send(&tx, epoch, PackEvent::ExportFailed(reason));
+                return;
+            }
+        };
+        let format = match super::format_of(request.format) {
+            Ok(format) => format,
+            Err(reason) => {
+                send(&tx, epoch, PackEvent::ExportFailed(reason));
+                return;
+            }
+        };
+        let target = request
+            .target
+            .clone()
+            .unwrap_or_else(|| super::default_export_path(&env, &request));
+        let snapshot = super::snapshot_of(&env, &request.instance);
+        let mut core_request = ExportRequest::new(&root, &target, format)
+            .with_name(request.name.clone())
+            .with_version(request.version.clone())
+            .with_catalog(&OfflineCatalog);
+        if let Some(snapshot) = &snapshot {
+            core_request = core_request.with_snapshot(snapshot);
+        }
+        match export_instance(&core_request) {
+            Ok(report) => send(
+                &tx,
+                epoch,
+                PackEvent::Exported(Box::new(done_view(&report))),
+            ),
+            Err(error) => send(&tx, epoch, PackEvent::ExportFailed(format!("{error}"))),
+        }
+    });
+}

crates/presenter/src/host/addon/pack/import.rs

@@ -0,0 +1,176 @@
+//! 后台导入（M113）：探测 → 目标目录 → core 的 `import_pack` → 报告。
+//!
+//! 三条纪律：
+//!
+//! 1. **探测失败不空跑管线**：先做具名诊断（[`super::diagnose`]），失败就只回 `Probe` 事件；
+//! 2. **默认档永远是 `KeepUser`**：只有 `request.overwrite == true` 才换成 `Overwrite`；
+//! 3. **取消后不再打扰界面**：进度回调与最终报告都先看取消标记。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::addon::import::{
+    import_pack, ConflictPolicy, DownloadEngineFetcher, ImportProgress, ImportProgressSink,
+    ImportRequest,
+};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::{ImportRequestView, PackEvent};
+use unlucky_core::addon::import::ImportStatus;
+
+use super::super::super::env::HostEnv;
+use super::super::super::job::{spawn, JobSender};
+use super::convert;
+use super::send;
+
+/// 起一个后台导入线程。
+pub(super) fn spawn_import(
+    env: HostEnv,
+    tx: JobSender,
+    request: ImportRequestView,
+    epoch: u64,
+    cancel: Arc<AtomicBool>,
+    inflight: super::InFlight,
+) {
+    spawn("pack-import", move || {
+        // 句柄跟着这次运行走到**出口**：正常收尾、两条早退、panic 展开都会 drop ⇒ 计数减一。
+        // 以前是手工 `finished()` 放在 `block_on()` 之后，两条早退路径直接漏掉（复审 r2 P2-1）。
+        let _inflight = inflight;
+        run(&env, &tx, &request, epoch, cancel);
+    });
+}
+
+pub(super) fn run(
+    env: &HostEnv,
+    tx: &JobSender,
+    request: &ImportRequestView,
+    epoch: u64,
+    cancel: Arc<AtomicBool>,
+) {
+    // 探测先过一遍：失败就只给具名诊断（「看起来像 X，但缺 Y」），不空跑一遍管线
+    if let Some(probe) = super::diagnose::of(&request.pack) {
+        send(tx, epoch, PackEvent::Probe(Box::new(probe)));
+        return;
+    }
+    let (target, register) = match target_of(env, request) {
+        Ok(target) => target,
+        Err(reason) => {
+            send(
+                tx,
+                epoch,
+                PackEvent::Report(Box::new(convert::failed_report(
+                    // 目标目录不可用 ⇒ 如实给空路径（不把包路径冒充成实例目录）
+                    PathBuf::new(),
+                    &request.pack,
+                    "import_host",
+                    "Target instance is not usable",
+                    &reason,
+                ))),
+            );
+            return;
+        }
+    };
+
+    let pack_name = request
+        .instance_name
+        .clone()
+        .unwrap_or_else(|| convert::pack_stem(&request.pack));
+    let progress_tx = tx.clone();
+    let progress_name = pack_name.clone();
+    let cancel_flag = Arc::clone(&cancel);
+    let sink: ImportProgressSink = Arc::new(move |progress: &ImportProgress| {
+        if cancel_flag.load(Ordering::SeqCst) {
+            return;
+        }
+        send(
+            &progress_tx,
+            epoch,
+            PackEvent::Progress(Some(Box::new(convert::progress_view(
+                progress,
+                &progress_name,
+            )))),
+        );
+    });
+
+    let engine = super::super::super::engine::engine(env);
+    let fetcher = DownloadEngineFetcher::new(&engine);
+    let mut core_request = ImportRequest::new(&request.pack, &target)
+        .with_fetcher(&fetcher)
+        .with_progress(sink);
+    if request.overwrite {
+        core_request = core_request.with_conflict_policy(ConflictPolicy::Overwrite);
+    }
+    if register {
+        core_request = core_request.with_registration(&env.layout, Some(&pack_name));
+    }
+
+    let report = block_on(import_pack(&core_request));
+    if report.status == ImportStatus::Failed && register {
+        // 失败已回滚，但**目录是我们建的**、core 只清文件不清目录 ⇒ 不清掉的话
+        // 下一次重试会撞「directory already exists」（复审 r1 P2-9）。
+        remove_if_empty(&target);
+    }
+    if cancel.load(Ordering::SeqCst) {
+        // 取消之后不再打扰界面（面板已经收回，代次也已经作废）。
+        // 注意：后台这一步**已经跑完**（core 没有取消令牌），实例可能已被登记 ——
+        // 所以取消的提示语必须说「还在后台跑」，不能说「实例未创建」。
+        return;
+    }
+    send(
+        tx,
+        epoch,
+        PackEvent::Report(Box::new(convert::report_view(&report, &target))),
+    );
+}
+
+/// 目录里没有东西就删掉（失败回滚后的收尾；非空一律不动）。
+fn remove_if_empty(dir: &std::path::Path) {
+    let empty = std::fs::read_dir(dir)
+        .map(|mut entries| entries.next().is_none())
+        .unwrap_or(false);
+    if empty {
+        let _ = std::fs::remove_dir(dir);
+    }
+}
+
+/// 导入目标：`(目录, 是否登记新实例)`。
+///
+/// - 选了实例 ⇒ 它的运行目录，**不登记**（已经是一条实例记录）；
+/// - 没选实例 ⇒ `<data>/instances/<dir_name>` 新目录 + 登记（实例名 = 用户给的名字或包名）。
+///   注意 M111 的既有边界：导入**不装加载器**，所以新实例报告的 `版本 id` 还要另外装。
+pub(super) fn target_of(
+    env: &HostEnv,
+    request: &ImportRequestView,
+) -> Result<(PathBuf, bool), String> {
+    match &request.instance {
+        Some(id) => super::instance_root(env, id).map(|root| (root, false)),
+        None => {
+            let name = request
+                .instance_name
+                .clone()
+                .filter(|name| !name.trim().is_empty())
+                .unwrap_or_else(|| convert::pack_stem(&request.pack));
+            let target = env
+                .layout
+                .data()
+                .join("instances")
+                .join(convert::dir_name(&name));
+            if target.exists() {
+                // 空目录（多半是上一次失败的残留）**可以复用**，否则重试永远报「已存在」
+                let mut entries = std::fs::read_dir(&target)
+                    .map_err(|error| format!("read instance dir failed: {error}"))?;
+                if entries.next().is_some() {
+                    return Err(format!(
+                        "directory already exists and is not empty: {}",
+                        target.display()
+                    ));
+                }
+            } else {
+                std::fs::create_dir_all(&target)
+                    .map_err(|error| format!("create dir failed: {error}"))?;
+            }
+            Ok((target, true))
+        }
+    }
+}

crates/presenter/src/host/addon/pack/tests.rs

@@ -0,0 +1,389 @@
+//! M113 的证据（都跑真管线 / 真 host，不用假数据）：
+//!
+//! | 用例 | 钉住什么 |
+//! |---|---|
+//! | [`bad_packs_get_a_named_diagnosis`] | 坏包必须有具名失败，不是静默、不是 panic |
+//! | [`preview_counts_match_the_written_report`] | 预检的 N/M 与最终报告**逐项相等** |
+//! | [`a_real_pack_runs_through_the_pipeline_end_to_end`] | 正常包能走完管线并落盘 |
+//! | [`chinese_instance_names_get_distinct_directories`] | 中文实例名不会塌成同一个目录 |
+//! | [`a_failed_new_instance_directory_can_be_reused_for_retry`] | 失败残留的空目录不挡重试 |
+//! | [`pack_epoch_is_per_host_and_is_its_own_counter`] | 代次按 host 分开，不再跨 host 串扰 |
+//! | [`a_failed_import_releases_the_in_flight_flag_and_keeps_install_cancel_intact`] | 早退路径放回「在跑」计数，取消安装仍是安装的取消 |
+//!
+//! 夹具（临时目录、写文件、泵 host）在 [`harness`]。
+
+mod harness;
+
+use harness::{pack_events, pump, pump_until, temp_dir, write};
+
+use unlucky_core::addon::export::{
+    export_instance, scan_instance, ExportRequest, InstanceSnapshot, OfflineCatalog,
+    DEFAULT_CONTENT_ROOTS,
+};
+
+use crate::dto::{ExportClassView, ExportRequestView, PackFormatView};
+
+#[test]
+fn bad_packs_get_a_named_diagnosis() {
+    let dir = temp_dir("badpack");
+
+    // ① 把文本文件改名成 .mrpack：连 zip 都不是
+    let fake = dir.join("fake.mrpack");
+    write(&fake, b"this is not a zip");
+    let probe = super::diagnose::of(&fake).expect("打不开的包必须有诊断");
+    assert!(
+        !probe.detail.is_empty(),
+        "诊断要给一句具体原因（不是空字符串）"
+    );
+    assert!(
+        probe.detail.to_lowercase().contains("archive") || probe.detail.contains("zip"),
+        "诊断要说清是哪一步失败：{}",
+        probe.detail
+    );
+
+    // ② 目录形态：有 overrides/、没有 manifest.json ⇒ 「像 CF，缺 manifest.json」
+    let dir_pack = dir.join("half");
+    write(&dir_pack.join("overrides").join("options.txt"), b"fov=90\n");
+    if let Some(probe) = super::diagnose::of(&dir_pack) {
+        assert!(
+            !probe.saw.is_empty(),
+            "看到了 overrides/ 就该说出来（saw 不能为空）"
+        );
+        if probe.looks_like.is_some() {
+            assert!(
+                !probe.missing.is_empty(),
+                "说「像某个格式」就必须说出缺哪个标记文件"
+            );
+        }
+    }
+}
+
+#[test]
+fn preview_counts_match_the_written_report() {
+    let dir = temp_dir("export-eq");
+    let root = dir.join("instance");
+    write(&root.join("mods").join("sodium.jar"), &[0x11; 4096]);
+    write(&root.join("mods").join("lithium.jar"), &[0x22; 2048]);
+    write(&root.join("mods").join("old.jar.disabled"), &[0x33; 512]);
+    write(&root.join("config").join("options.txt"), b"fov=90\n");
+    // 白名单之外的目录不该被扫（否则「将内联 N」会虚高）
+    write(&root.join("logs").join("latest.log"), b"noise\n");
+
+    let request = ExportRequestView {
+        instance: "survival".to_string(),
+        format: PackFormatView::Modrinth,
+        name: "Survival".to_string(),
+        version: "1.0.0".to_string(),
+        target: Some(dir.join("out.mrpack")),
+    };
+    let env_root = dir.join("data");
+    std::fs::create_dir_all(&env_root).expect("env");
+    let env = crate::host::HostEnv::at_root(&env_root);
+
+    // 预检（不写盘）
+    let preview = super::export::preview_of(&root, &env, &request);
+
+    // 真写盘：用同一套判据（离线目录 + 默认内容目录 + 直接给的快照）
+    let snapshot = InstanceSnapshot {
+        game_version: "1.20.1".to_string(),
+        loaders: Vec::new(),
+    };
+    let target = dir.join("out.mrpack");
+    let core_request = ExportRequest::new(
+        &root,
+        &target,
+        &unlucky_core::addon::pack::modrinth::MODRINTH,
+    )
+    .with_name("Survival")
+    .with_version("1.0.0")
+    .with_catalog(&OfflineCatalog)
+    .with_snapshot(&snapshot);
+    let report = export_instance(&core_request).expect("导出应当成功");
+
+    // 三个计数逐项相等（塔台要求：不是「大致对」）
+    assert_eq!(
+        preview.inline_count(),
+        report.inline_count(),
+        "内联条数不一致：预检 {} vs 报告 {}",
+        preview.inline_count(),
+        report.inline_count()
+    );
+    assert_eq!(
+        preview.skipped_count(),
+        report.skipped_count(),
+        "无法导出条数不一致"
+    );
+    assert_eq!(
+        preview.remote_count(),
+        report.remote_count(),
+        "远程引用条数不一致"
+    );
+
+    // 逐条：同一个路径在两边必须是同一个类
+    for file in &preview.files {
+        let written = report
+            .files
+            .iter()
+            .find(|candidate| candidate.path == file.path)
+            .unwrap_or_else(|| panic!("预检多出一条：{}", file.path));
+        let expected = match file.class {
+            ExportClassView::Remote => unlucky_core::addon::export::FileClass::Remote,
+            ExportClassView::Inline => unlucky_core::addon::export::FileClass::Inline,
+            ExportClassView::Skipped => unlucky_core::addon::export::FileClass::Skipped,
+        };
+        assert_eq!(written.class, expected, "{} 的归类不一致", file.path);
+    }
+
+    // 白名单外的 logs/ 不许进包（防「扫太宽」把预检数字弄虚）
+    assert!(
+        !report
+            .files
+            .iter()
+            .any(|file| file.path.starts_with("logs/")),
+        "logs/ 不该被扫进整合包"
+    );
+
+    // 同时钉一条：`scan_instance` 的口径就是预览用的那一套
+    let roots: Vec<String> = DEFAULT_CONTENT_ROOTS
+        .iter()
+        .map(|entry| (*entry).to_string())
+        .collect();
+    let (files, skipped) = scan_instance(&root, &roots);
+    assert_eq!(files.len(), preview.inline_count());
+    assert_eq!(skipped.len(), preview.skipped_count());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn a_real_pack_runs_through_the_pipeline_end_to_end() {
+    // 真管线端到端：造一个 MultiMC 实例目录当「包」（目录形态不需要 zip 写入器），
+    // 走 `import::run` 的**真**路径，看事件流里有没有「进度 + 结果」、文件有没有落地。
+    let dir = temp_dir("import-e2e");
+    let source = dir.join("Better MC");
+    write(
+        &source.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"},
+            {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"}]}"#,
+    );
+    write(&source.join(".minecraft/mods/sodium.jar"), &[0x11; 1024]);
+    write(&source.join(".minecraft/config/options.txt"), b"fov=90\n");
+
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let env = crate::host::HostEnv::at_root(&data);
+
+    let (tx, rx) = crate::host::job::channel();
+    let request = crate::dto::ImportRequestView {
+        pack: source,
+        instance: None,
+        instance_name: Some("Imported Pack".to_string()),
+        overwrite: false,
+    };
+    super::import::run(
+        &env,
+        &tx,
+        &request,
+        7,
+        std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
+    );
+    drop(tx);
+
+    let mut progress = 0usize;
+    let mut report = None;
+    for task in rx.iter() {
+        match task {
+            crate::host::job::HostTask::Pack { event, epoch } => {
+                assert_eq!(epoch, 7, "代次必须原样带回（取消判定靠它）");
+                match *event {
+                    crate::dto::PackEvent::Progress(Some(_)) => progress += 1,
+                    crate::dto::PackEvent::Report(view) => report = Some(*view),
+                    other => panic!("意料之外的事件：{other:?}"),
+                }
+            }
+            other => panic!("意料之外的任务：{other:?}"),
+        }
+    }
+
+    assert!(progress > 0, "至少要有一条进度事件");
+    let report = report.expect("必须有结果事件");
+    assert_ne!(
+        report.status,
+        crate::dto::ImportStatusView::Failed,
+        "正常包不该失败：{:?}",
+        report.error
+    );
+    assert_eq!(
+        report.format,
+        Some(crate::dto::PackFormatView::Multimc),
+        "应当认成 MultiMC 格式"
+    );
+    assert!(
+        report.written() > 0,
+        "报告里要至少有写盘的文件：{:?}",
+        report.files
+    );
+    // 落盘位置以**报告里的 target** 为准（那是 host 真算出来的目录，界面显示的也是它）
+    let landed = &report.target;
+    assert!(
+        landed.join("mods/sodium.jar").is_file(),
+        "文件没有落到实例目录：{}",
+        landed.display()
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn chinese_instance_names_get_distinct_directories() {
+    // 复审 r1 P2-8：slug() 只留 ASCII，中文名会全塌成 `pack`，第二个就撞目录
+    let first = super::convert::dir_name("我的整合包");
+    let second = super::convert::dir_name("另一个整合包");
+    assert_ne!(first, second, "两个不同的中文名必须得到不同目录");
+    assert_eq!(
+        first,
+        super::convert::dir_name("我的整合包"),
+        "同一个名字要稳定（不然重试会漂到新目录）"
+    );
+    assert!(first.starts_with("pack-"), "退化时要留可读前缀：{first}");
+
+    // 判据与注释对齐（复审 r2 P2-2）：只含 ASCII 字母数字/空格/`-`/`_` ⇒ 保持原样
+    assert_eq!(super::convert::dir_name("Better-MC"), "Better-MC");
+    assert_eq!(
+        super::convert::dir_name("Better MC"),
+        "Better-MC",
+        "空格折成 `-`、**不加**哈希"
+    );
+    assert_eq!(
+        super::convert::dir_name("pack"),
+        "pack",
+        "名字就叫 pack 也保留"
+    );
+
+    // 折过**别的**字符（这里是 `.`）就必须补哈希，否则不同名字会撞同一个目录
+    let versioned = super::convert::dir_name("Survival 1.20.1");
+    assert!(versioned.starts_with("Survival-1-20-1-"), "{versioned}");
+    assert_ne!(versioned, "Survival-1-20-1", "折过 `.` 就要补哈希");
+}
+
+#[test]
+fn a_failed_new_instance_directory_can_be_reused_for_retry() {
+    // 复审 r1 P2-9：失败回滚留下空目录时会挡住重试
+    let dir = temp_dir("retry");
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let env = crate::host::HostEnv::at_root(&data);
+
+    let request = crate::dto::ImportRequestView {
+        pack: dir.join("whatever.mrpack"),
+        instance: None,
+        instance_name: Some("Retry Me".to_string()),
+        overwrite: false,
+    };
+
+    // 第一次：目录不存在 ⇒ 建出来
+    let (first, register) = super::import::target_of(&env, &request).expect("首次应当可以建目录");
+    assert!(register);
+    assert!(first.is_dir());
+
+    // 第二次（模拟上一次失败留下的空目录）⇒ 复用，而不是报「已存在」
+    let (second, _) = super::import::target_of(&env, &request).expect("空目录应当可复用");
+    assert_eq!(first, second);
+
+    // 目录里已经有东西 ⇒ 拒绝（不能往别人的实例里倒）
+    std::fs::write(second.join("marker.txt"), b"x").expect("write");
+    assert!(
+        super::import::target_of(&env, &request).is_err(),
+        "非空目录必须拒绝"
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn pack_epoch_is_per_host_and_is_its_own_counter() {
+    // 复审 r2 P3-6：代次**按 host** 分开（不再是跨 host 共享的裸静态量）。
+    // 两个 host（两个临时根）各 bump 一次，互不影响 —— 这正是并行测试串扰的根因。
+    let one = temp_dir("epoch-one");
+    let two = temp_dir("epoch-two");
+    let env_one = crate::host::HostEnv::at_root(one.join("data"));
+    let env_two = crate::host::HostEnv::at_root(two.join("data"));
+
+    let before_one = super::pack_epoch(&env_one);
+    let before_two = super::pack_epoch(&env_two);
+    super::bump_pack_epoch(&env_one);
+    assert_eq!(
+        super::pack_epoch(&env_one),
+        before_one.wrapping_add(1),
+        "自己这个 host 的代次 +1"
+    );
+    assert_eq!(
+        super::pack_epoch(&env_two),
+        before_two,
+        "**另一个** host 的代次不受影响（P3-6 的根因）"
+    );
+    assert_eq!(super::in_flight(&env_two), 0, "在跑计数也是每 host 一份");
+
+    let _ = std::fs::remove_dir_all(&one);
+    let _ = std::fs::remove_dir_all(&two);
+}
+
+#[test]
+fn a_failed_import_releases_the_in_flight_flag_and_keeps_install_cancel_intact() {
+    // 复审 r2 P2-1 的护栏：早退路径必须把「在跑」计数放回去，否则之后**下载页**的
+    // 「取消安装」会被当成导入取消（不发 `InstallCancelled`，还给内容库画一句假话）。
+    use crate::dto::{
+        AppCommand, AppEvent, Backend, CoreEvent, ImportRequestView, PackCommand, PackEvent,
+    };
+
+    let dir = temp_dir("inflight-guard");
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let host_env = crate::host::HostEnv::at_root(&data);
+    let mut host = crate::host::CoreHost::headless(host_env.clone());
+
+    // ① 派一次**必然早退**的导入：包文件不存在 ⇒ 探测当场失败，根本不进管线
+    host.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new(
+        ImportRequestView {
+            pack: dir.join("missing.mrpack"),
+            instance: None,
+            instance_name: Some("Guess".to_string()),
+            overwrite: false,
+        },
+    )))));
+    let events = pump_until(&mut host, |all| {
+        pack_events(all)
+            .iter()
+            .any(|event| matches!(event, PackEvent::Probe(_)))
+    });
+    assert!(
+        pack_events(&events)
+            .iter()
+            .any(|event| matches!(event, PackEvent::Probe(_))),
+        "坏包必须给出探测诊断（而不是静默）；实际收到 {events:?}"
+    );
+    assert_eq!(
+        super::in_flight(&host_env),
+        0,
+        "早退之后「在跑」计数必须归零（RAII guard 负责，不靠手工 finished）"
+    );
+
+    // ② 此后下载页的「取消安装」必须照常发 `InstallCancelled`，且**不能**冒出 pack 的取消
+    host.dispatch(AppCommand::CancelInstall);
+    let events = pump(&mut host);
+    assert!(
+        events
+            .iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallCancelled))),
+        "没有导入在跑时，取消安装必须照常给回执（否则用户点了取消毫无反应）"
+    );
+    assert!(
+        !pack_events(&events)
+            .iter()
+            .any(|event| matches!(event, PackEvent::Cancelled)),
+        "此刻没有导入在跑，不该给内容库发「导入还在后台跑」"
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}

crates/presenter/src/host/addon/pack/tests/harness.rs

@@ -0,0 +1,56 @@
+//! pack 用例的共用夹具：临时目录、文件写入、host 泵。
+//!
+//! 拆出去只为一件事：`tests.rs` 已经 429 行（超 400 硬线），而这些 helper 与任何一条断言无关。
+//! `tests.rs` 里各条用例的「抓得住什么」写在用例自己的注释里，这里只放机械动作。
+
+use std::path::PathBuf;
+
+/// 每个用例一个独立临时目录（用完删）。
+pub(super) fn temp_dir(name: &str) -> PathBuf {
+    let dir = std::env::temp_dir().join(format!("ull-m113-{name}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("temp dir");
+    dir
+}
+
+pub(super) fn write(path: &std::path::Path, bytes: &[u8]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("parent");
+    }
+    std::fs::write(path, bytes).expect("write");
+}
+
+/// 泵一次 host：把后台任务收成事件并取走。
+pub(super) fn pump(host: &mut crate::host::CoreHost) -> Vec<crate::dto::AppEvent> {
+    use crate::dto::Backend;
+    host.tick(std::time::Duration::from_millis(1));
+    host.drain_events()
+}
+
+/// 泵到 `done` 为真（最多 ~3 s），返回期间收到的全部事件。
+pub(super) fn pump_until(
+    host: &mut crate::host::CoreHost,
+    done: impl Fn(&[crate::dto::AppEvent]) -> bool,
+) -> Vec<crate::dto::AppEvent> {
+    let mut all = Vec::new();
+    for _ in 0..600 {
+        all.extend(pump(host));
+        if done(&all) {
+            break;
+        }
+        std::thread::sleep(std::time::Duration::from_millis(5));
+    }
+    all
+}
+
+pub(super) fn pack_events(events: &[crate::dto::AppEvent]) -> Vec<crate::dto::PackEvent> {
+    events
+        .iter()
+        .filter_map(|event| match event {
+            crate::dto::AppEvent::Core(crate::dto::CoreEvent::Pack(inner)) => {
+                Some((**inner).clone())
+            }
+            _ => None,
+        })
+        .collect()
+}

crates/presenter/src/host/addon/sources.rs

@@ -0,0 +1,262 @@
+//! 两个站点的检索方言（M109）：把各自的 JSON 翻成 [`ContentHit`]。
+//!
+//! 两个站点在**同一件事上用的字段名完全不同**，所以这里每个站点一段、各自带注释：
+//!
+//! | 语义 | Modrinth `/v2/search` | CurseForge `/v1/mods/search` |
+//! |---|---|---|
+//! | 项目 id | `project_id`（base62） | `id`（数字） |
+//! | 标题 / 简介 | `title` / `description` | `name` / `summary` |
+//! | 下载量 | `downloads` | `downloadCount` |
+//! | 游戏版本 | `versions` | `latestFilesIndexes[].gameVersion` |
+//! | 加载器 | `categories` 里混着的 `fabric`/`forge`/… | `latestFilesIndexes[].modLoader`（数字枚举） |
+//!
+//! 加载器那一行是最容易抄错的地方：Modrinth 的 `categories` 同时装着 `optimization` 这种**分类标签**，
+//! 直接整份当加载器用，画面上就会多出「optimization」这种假加载器（`sources/tests` 钉住了这一条）。
+
+use serde_json::Value;
+
+use crate::dto::{
+    loader_facet, ContentHit, ContentKind, ContentQuery, ContentResults, ContentSource,
+};
+
+use super::super::env::HostEnv;
+use super::curseforge_ready;
+use super::http::{encode, get};
+
+/// Modrinth v2 的根（无需 key）。
+pub(super) const MODRINTH: &str = "https://api.modrinth.com/v2";
+/// CurseForge v1 的根（需要 `X-API-KEY`）。
+pub(super) const CURSEFORGE: &str = "https://api.curseforge.com/v1";
+/// CurseForge 的「Minecraft」gameId（官方固定值）。
+const CF_MINECRAFT: u32 = 432;
+
+/// 检索分派。
+pub(super) fn search(env: &HostEnv, query: &ContentQuery) -> Result<ContentResults, String> {
+    match query.source {
+        ContentSource::Modrinth => modrinth(env, query),
+        ContentSource::Curseforge => curseforge(env, query),
+    }
+}
+
+// --------------------------------------------------------------- Modrinth
+
+fn modrinth(env: &HostEnv, query: &ContentQuery) -> Result<ContentResults, String> {
+    let mut facets = vec![format!("[\"project_type:{}\"]", query.kind.modrinth_type())];
+    if let Some(version) = &query.game_version {
+        facets.push(format!("[\"versions:{version}\"]"));
+    }
+    if let Some(facet) = query.loader.and_then(loader_facet) {
+        facets.push(format!("[\"categories:{facet}\"]"));
+    }
+
+    let mut url = format!(
+        "{MODRINTH}/search?limit={}&offset={}&index={}&facets={}",
+        query.limit.min(100),
+        query.offset,
+        query.sort.modrinth_index(),
+        encode(&format!("[{}]", facets.join(",")))
+    );
+    if !query.text.trim().is_empty() {
+        url.push_str(&format!("&query={}", encode(query.text.trim())));
+    }
+
+    let body = get(env, &url, &[])?;
+    let json: Value = serde_json::from_str(&body)
+        .map_err(|error| format!("Modrinth 返回的不是合法 JSON：{error}"))?;
+    let hits = json
+        .get("hits")
+        .and_then(Value::as_array)
+        .ok_or_else(|| "Modrinth 返回里没有 hits 字段".to_string())?
+        .iter()
+        .map(modrinth_hit)
+        .collect::<Vec<_>>();
+
+    Ok(ContentResults {
+        query: query.clone(),
+        hits,
+        total: u32_of(&json, "total_hits"),
+        curseforge: curseforge_ready(),
+    })
+}
+
+/// 一条 Modrinth 命中项 → DTO（缺字段一律给空/零，**不**编造）。
+fn modrinth_hit(value: &Value) -> ContentHit {
+    let loaders = strings(value, "categories")
+        .into_iter()
+        // `categories` 混着加载器与分类标签：只留已知的四个加载器
+        .filter(|tag| matches!(tag.as_str(), "fabric" | "forge" | "neoforge" | "quilt"))
+        .collect();
+
+    ContentHit {
+        id: text(value, "project_id"),
+        slug: text(value, "slug"),
+        title: text(value, "title"),
+        summary: text(value, "description"),
+        author: text(value, "author"),
+        downloads: u64_of(value, "downloads"),
+        updated: date_part(&text(value, "updated")),
+        source: ContentSource::Modrinth,
+        game_versions: strings(value, "versions"),
+        loaders,
+        icon: optional_text(value, "icon_url"),
+    }
+}
+
+// --------------------------------------------------------------- CurseForge
+
+fn curseforge(env: &HostEnv, query: &ContentQuery) -> Result<ContentResults, String> {
+    let Some(key) = super::curseforge_key() else {
+        return Err("CurseForge 需要 API key（ULL_CF_API_KEY 未设置）".to_string());
+    };
+    let mut url = format!(
+        "{CURSEFORGE}/mods/search?gameId={CF_MINECRAFT}&classId={}&index={}&pageSize={}&sortField={}&sortOrder=desc",
+        query.kind.curseforge_class(),
+        query.offset,
+        query.limit.min(50),
+        query.sort.curseforge_field()
+    );
+    if !query.text.trim().is_empty() {
+        url.push_str(&format!("&searchFilter={}", encode(query.text.trim())));
+    }
+    if let Some(version) = &query.game_version {
+        url.push_str(&format!("&gameVersion={}", encode(version)));
+    }
+
+    let body = get(env, &url, &[("x-api-key", key.as_str())])?;
+    let json: Value = serde_json::from_str(&body)
+        .map_err(|error| format!("CurseForge 返回的不是合法 JSON：{error}"))?;
+    let hits = json
+        .get("data")
+        .and_then(Value::as_array)
+        .ok_or_else(|| "CurseForge 返回里没有 data 字段".to_string())?
+        .iter()
+        .map(curseforge_hit)
+        .collect::<Vec<_>>();
+
+    Ok(ContentResults {
+        query: query.clone(),
+        hits,
+        total: json
+            .get("pagination")
+            .map(|pagination| u64_of(pagination, "totalCount"))
+            .and_then(|value| u32::try_from(value).ok())
+            .unwrap_or(0),
+        curseforge: true,
+    })
+}
+
+/// 一条 CF 命中项 → DTO。加载器只能从 `latestFilesIndexes[].modLoader` 的数字枚举反推。
+fn curseforge_hit(value: &Value) -> ContentHit {
+    let mut game_versions: Vec<String> = Vec::new();
+    let mut loaders: Vec<String> = Vec::new();
+    if let Some(indexes) = value.get("latestFilesIndexes").and_then(Value::as_array) {
+        for entry in indexes {
+            if let Some(version) = entry.get("gameVersion").and_then(Value::as_str) {
+                if !game_versions.iter().any(|item| item == version) {
+                    game_versions.push(version.to_string());
+                }
+            }
+            if let Some(loader) = entry
+                .get("modLoader")
+                .and_then(Value::as_u64)
+                .and_then(curseforge_loader)
+            {
+                if !loaders.iter().any(|item| item == loader) {
+                    loaders.push(loader.to_string());
+                }
+            }
+        }
+    }
+    let author = value
+        .get("authors")
+        .and_then(Value::as_array)
+        .and_then(|items| items.first())
+        .map(|entry| text(entry, "name"))
+        .unwrap_or_default();
+
+    ContentHit {
+        id: value
+            .get("id")
+            .and_then(Value::as_u64)
+            .map(|id| id.to_string())
+            .unwrap_or_default(),
+        slug: text(value, "slug"),
+        title: text(value, "name"),
+        summary: text(value, "summary"),
+        author,
+        downloads: u64_of(value, "downloadCount"),
+        updated: date_part(&text(value, "dateModified")),
+        source: ContentSource::Curseforge,
+        game_versions,
+        loaders,
+        icon: value
+            .get("logo")
+            .and_then(|logo| logo.get("url"))
+            .and_then(Value::as_str)
+            .map(ToString::to_string),
+    }
+}
+
+/// CF 的 `modLoader` 枚举 → Modrinth 口径的 loader 名（1 Forge / 4 Fabric / 5 Quilt / 6 NeoForge）。
+pub(super) fn curseforge_loader(raw: u64) -> Option<&'static str> {
+    match raw {
+        1 => Some("forge"),
+        4 => Some("fabric"),
+        5 => Some("quilt"),
+        6 => Some("neoforge"),
+        _ => None,
+    }
+}
+
+// --------------------------------------------------------------- 小工具
+
+/// 取字符串字段（缺 / 类型不对 ⇒ 空串）。
+fn text(value: &Value, key: &str) -> String {
+    value
+        .get(key)
+        .and_then(Value::as_str)
+        .unwrap_or_default()
+        .to_string()
+}
+
+/// 取可选字符串字段（空串也当没有——站点会给 `""` 表示没图）。
+fn optional_text(value: &Value, key: &str) -> Option<String> {
+    value
+        .get(key)
+        .and_then(Value::as_str)
+        .filter(|text| !text.is_empty())
+        .map(ToString::to_string)
+}
+
+/// 取字符串数组（缺 / 类型不对 ⇒ 空 vec）。
+fn strings(value: &Value, key: &str) -> Vec<String> {
+    value
+        .get(key)
+        .and_then(Value::as_array)
+        .map(|items| {
+            items
+                .iter()
+                .filter_map(|item| item.as_str().map(ToString::to_string))
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn u64_of(value: &Value, key: &str) -> u64 {
+    value.get(key).and_then(Value::as_u64).unwrap_or(0)
+}
+
+fn u32_of(value: &Value, key: &str) -> u32 {
+    u32::try_from(u64_of(value, key)).unwrap_or(0)
+}
+
+/// ISO-8601 → 日期部分（`2024-05-01T…` → `2024-05-01`；短串原样返回）。
+pub(super) fn date_part(raw: &str) -> String {
+    raw.get(..10).unwrap_or(raw).to_string()
+}
+
+/// 类型名只用来钉住「四条侧栏都在」的常量没被改乱（检索本身按 `kind` 走 facet）。
+#[must_use]
+pub(super) fn all_kinds() -> [ContentKind; 4] {
+    ContentKind::ALL
+}

crates/presenter/src/host/addon/tests.rs

@@ -0,0 +1,85 @@
+//! 内容库宿主的守门测试（M109）：编码、文件名穿越、退避判定、两个站点的方言映射。
+
+use std::time::Duration;
+
+use super::http::{encode, retry_after, retryable};
+use super::install::safe_file_name;
+use super::sources::{all_kinds, curseforge_loader, date_part};
+use crate::dto::ContentKind;
+
+#[test]
+fn percent_encoding_keeps_the_query_readable_and_escapes_the_rest() {
+    assert_eq!(encode("1.20.1"), "1.20.1");
+    assert_eq!(
+        encode("[\"versions:1.20.1\"]"),
+        "%5B%22versions%3A1.20.1%22%5D"
+    );
+    assert_eq!(encode("中文"), "%E4%B8%AD%E6%96%87");
+    assert_eq!(encode("a b"), "a%20b");
+}
+
+#[test]
+fn file_names_never_carry_a_path() {
+    // 抓得住：站点给的 `../../evil.jar` 落到实例目录之外（穿越）。
+    assert_eq!(safe_file_name("sodium.jar"), "sodium.jar");
+    assert_eq!(safe_file_name("../../evil.jar"), "evil.jar");
+    assert_eq!(safe_file_name("mods\\jei.jar"), "jei.jar");
+    assert_eq!(safe_file_name(".."), "download.bin");
+    assert_eq!(safe_file_name(""), "download.bin");
+}
+
+#[test]
+fn dates_are_sliced_not_guessed() {
+    assert_eq!(date_part("2024-05-01T12:00:00Z"), "2024-05-01");
+    assert_eq!(date_part("2024-05"), "2024-05");
+    assert_eq!(date_part(""), "");
+}
+
+#[test]
+fn only_rate_limited_and_transient_failures_are_retried() {
+    assert!(retryable("HTTP 429 (retry_after=Some(3))"));
+    assert!(retryable("HTTP 503 (retry_after=None)"));
+    assert!(!retryable("HTTP 404 (retry_after=None)"));
+    assert!(
+        !retryable("HTTP 401 (retry_after=None)"),
+        "密钥错重试只会更糟"
+    );
+}
+
+#[test]
+fn retry_after_prefers_the_server_and_falls_back_to_exponential() {
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=Some(7))", 0),
+        Duration::from_secs(7)
+    );
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=None)", 0),
+        Duration::from_secs(1)
+    );
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=None)", 2),
+        Duration::from_secs(4)
+    );
+    // 服务端要得再多也不等超过 30s（交互与截图不能被一次退避挂死）
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=Some(900))", 0),
+        Duration::from_secs(30)
+    );
+}
+
+#[test]
+fn curseforge_loader_ids_follow_the_official_enum() {
+    assert_eq!(curseforge_loader(1), Some("forge"));
+    assert_eq!(curseforge_loader(4), Some("fabric"));
+    assert_eq!(curseforge_loader(5), Some("quilt"));
+    assert_eq!(curseforge_loader(6), Some("neoforge"));
+    assert_eq!(curseforge_loader(99), None);
+}
+
+#[test]
+fn the_four_content_kinds_are_the_four_side_entries() {
+    assert_eq!(
+        all_kinds().map(ContentKind::slug),
+        ["modpack", "mod", "resourcepack", "shader"]
+    );
+}

crates/presenter/src/host/cancel_tests.rs

@@ -0,0 +1,344 @@
+//! 取消安装的**实测装置**（M105）。
+//!
+//! ## 为什么这条测试要真起一次安装
+//!
+//! 「点取消没反应」有三种可能的断点，读码分不出来：
+//! ① 按钮/消息链断了（不派 `AppCommand::CancelInstall`）；
+//! ② host 收下取消后，**还在跑的任务**继续发进度事件，把面板又点亮（面板闪一下又回来）；
+//! ③ 取消根本停不下传输（M105 之前 core 的 `execute` 没有取消入参，下载线程会跑到段尾）。
+//!
+//! ①② 能靠单测的假事件流抓；③ 只有真起一次安装、真取消、真量「取消之后还在发生什么」才抓得到。
+//! 修完之后 ①②③ 都有守门：① 是 app 层的消息测试，② 是下面那条 CI 可跑的
+//! [`progress_from_a_cancelled_job_is_dropped`]，③ 就是本用例（真网络）。
+//!
+//! 所以这一条是**真网络**用例：`#[ignore]` 守着（CI 不跑），人工跑：
+//!
+//! ```text
+//! cargo test -p unlucky-presenter --test '' -- real_install --ignored --nocapture
+//! # 或（等价，本用例在 lib 测试里）
+//! cargo test -p unlucky-presenter real_install_cancel -- --ignored --nocapture
+//! ```
+//!
+//! ## 它量什么（三样里能抓住的两样）
+//!
+//! | 现象 | 怎么量 | 抓住什么 / 抓不住什么 |
+//! |---|---|---|
+//! | 进度还在推进 | 取消后收到的 `InstallProgress(Some)` 条数与 `files_done` 增量 | 抓得住「UI 侧还在被事件喂」；抓不住事件之外的后台动作 |
+//! | 断点文件 | `<game>/**/*.ullpart*` 的总字节：取消时 vs 取消后 20 s，**并且**绝对值必须是 0 | 抓得住「还在写」与「留了半截垃圾」；抓不住「线程还活着」（`.ullpart` 不再长也可能是卡在等响应） |
+//! | 半成品变成品 | `<game>/versions/<id>/<id>.json`（版本清单）与 `<launcher_home>/config/profiles.json`（**实例登记的唯一真相源**，`LauncherLayout::profiles_config()`） | 抓得住「取消后仍然落了成品 / 登记了实例」；抓不住「用户看不到的临时目录」 |
+//!
+//! 线程与 socket 两样**抓不住**（没有可移植的查询口，见 `probe` 一节），所以这里不用它当判据。
+
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+use crate::dto::{AppCommand, AppEvent, Backend, CoreEvent, InstallProgressView, InstallStage};
+
+use super::job::HostTask;
+use super::{env::HostEnv, CoreHost};
+
+/// 实测用的数据根（放在固定位置而不是系统 temp：便于人工复跑时留着看）。
+fn root() -> PathBuf {
+    std::env::temp_dir().join("ull-m105-cancel")
+}
+
+/// 递归数 `.ullpart` 家族（中间文件 + 续传元数据）的总字节。
+///
+/// 目录很小（只有本次安装写的那几层），所以裸递归够用；读不动的一律当 0
+/// （量的是趋势，不是精确值）。
+fn part_bytes(dir: &Path) -> u64 {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return 0;
+    };
+    let mut total = 0;
+    for entry in entries.flatten() {
+        let path = entry.path();
+        let Ok(meta) = entry.metadata() else {
+            continue;
+        };
+        if meta.is_dir() {
+            total += part_bytes(&path);
+        } else if let Some(name) = path.file_name().and_then(|name| name.to_str()) {
+            // 中间文件 `<name>.ullpart[-<pid>-<seq>]` 与它的元数据 `.ullmeta.json`
+            if name.contains(".ullpart") {
+                total += meta.len();
+            }
+        }
+    }
+    total
+}
+
+/// 一次 tick 后抽干事件，返回本轮的全部事件。
+fn pump(host: &mut CoreHost, wait: Duration) -> Vec<AppEvent> {
+    host.tick(wait);
+    host.drain_events()
+}
+
+/// 事件里的安装进度（别的变体一概忽略）。
+fn progress(event: &AppEvent) -> Option<&crate::dto::InstallProgressView> {
+    match event {
+        AppEvent::Core(CoreEvent::InstallProgress(Some(progress))) => Some(progress),
+        _ => None,
+    }
+}
+
+/// **实测主用例**：真起一次安装 → 取消 → 量取消之后还在发生什么。
+///
+/// 版本用环境变量 `ULL_CANCEL_VERSION` 覆盖（默认 `1.20.1`：文件多、总量够大，
+/// 取消点之后还有一大截没下完，于是「取消后还在跑」一眼可见）。
+#[test]
+#[ignore = "真网络：真起一次安装再取消（需要 ULL_CANCEL_VERSION 指定的版本可下载）"]
+fn real_install_cancel_stops_progress_and_leaves_no_half_product() {
+    let version = std::env::var("ULL_CANCEL_VERSION").unwrap_or_else(|_| "1.20.1".to_string());
+    let root = root();
+    std::fs::remove_dir_all(&root).ok();
+
+    let env = HostEnv::at_root(&root);
+    let game = env.game.root().to_path_buf();
+    // 实例登记的真相源是 `<launcher_home>/config/profiles.json`（`LauncherLayout::profiles_config()`），
+    // 不是 `<game>/instances` —— 后者根本不存在，探它等于什么都没探（复审 P2-3 第 2 点）。
+    let launcher = env.layout.clone();
+    let mut host = CoreHost::headless(env);
+
+    // ---- 起点：取消之前 ----
+    host.dispatch(AppCommand::InstallVersion(version.clone()));
+    let started = Instant::now();
+    let mut before_cancel_progress = 0_usize;
+    let mut done_at_cancel = 0_u64;
+    // 等到「真在下载」（files_done ≥ 2）再取消：取消得太早会落在 Planning/解析阶段，
+    // 那种取消本来就只是阶段边界停，证明不了下载中取消的行为。
+    while started.elapsed() < Duration::from_secs(180) {
+        for event in pump(&mut host, Duration::from_millis(100)) {
+            if let Some(progress) = progress(&event) {
+                before_cancel_progress += 1;
+                done_at_cancel = done_at_cancel.max(progress.files_done);
+            }
+        }
+        if done_at_cancel >= 2 {
+            break;
+        }
+    }
+    assert!(
+        done_at_cancel >= 2,
+        "180 s 内没进到下载阶段（files_done={done_at_cancel}）：网络或版本号有问题，先让这条能跑起来"
+    );
+    let parts_at_cancel = part_bytes(&game);
+
+    // ---- 取消 ----
+    host.dispatch(AppCommand::CancelInstall);
+    let cancelled = Instant::now();
+    let mut after: Vec<(f32, u64, InstallStage, u64)> = Vec::new();
+    for event in host.drain_events() {
+        if let Some(progress) = progress(&event) {
+            after.push((
+                cancelled.elapsed().as_secs_f32(),
+                progress.files_done,
+                progress.stage,
+                part_bytes(&game),
+            ));
+        }
+    }
+
+    // ---- 取消之后 20 s：还会不会被喂进度、断点文件还会不会长 ----
+    //
+    // 每秒采一次 `.ullpart` 总字节：判据不是「取消那一刻的瞬时值」，而是**它在 5 s 之后
+    // 不再变高**——在飞的那个文件本来就要多活一个数据块（取消延迟的定义），
+    // 5 s 是给它留的余量（远超一个数据块）。
+    let settle = Duration::from_secs(5);
+    let mut latest = None;
+    let mut samples: Vec<(f32, u64)> = Vec::new();
+    let mut next_sample = Duration::from_secs(1);
+    while cancelled.elapsed() < Duration::from_secs(20) {
+        for event in pump(&mut host, Duration::from_millis(100)) {
+            if let Some(progress) = progress(&event) {
+                latest = Some(progress.clone());
+                after.push((
+                    cancelled.elapsed().as_secs_f32(),
+                    progress.files_done,
+                    progress.stage,
+                    part_bytes(&game),
+                ));
+            }
+        }
+        let elapsed = cancelled.elapsed();
+        if elapsed >= next_sample {
+            samples.push((elapsed.as_secs_f32(), part_bytes(&game)));
+            next_sample += Duration::from_secs(1);
+        }
+        std::thread::sleep(Duration::from_millis(20));
+    }
+    let parts_after = part_bytes(&game);
+    let done_after = latest
+        .as_ref()
+        .map_or(done_at_cancel, |view| view.files_done);
+
+    // ---- 取证：日志行 ----
+    eprintln!("[cancel-test] root={}", root.display());
+    eprintln!(
+        "[cancel-test] 取消前：进度事件 {before_cancel_progress} 条，files_done={done_at_cancel}，.ullpart 合计 {parts_at_cancel} 字节"
+    );
+    eprintln!(
+        "[cancel-test] 取消后 20 s：进度事件 {} 条，files_done={done_after}（+{} 个文件），.ullpart 合计 {parts_after} 字节（{:+}）",
+        after.len(),
+        done_after.saturating_sub(done_at_cancel),
+        i64::try_from(parts_after).unwrap_or(i64::MAX) - i64::try_from(parts_at_cancel).unwrap_or(i64::MAX)
+    );
+    for (at, parts) in &samples {
+        eprintln!("[cancel-test]   t={at:>5.1}s ullpart={parts}");
+    }
+    for (index, (at, done, stage, parts)) in after.iter().enumerate().take(12) {
+        eprintln!(
+            "[cancel-test]   #{index} +{at:.2}s files_done={done} stage={stage:?} ullpart={parts}"
+        );
+    }
+    if after.len() > 12 {
+        eprintln!("[cancel-test]   …（另有 {} 条）", after.len() - 12);
+    }
+
+    // ---- 断点文件 / 临时目录 / 成品三样 ----
+    // 版本 JSON 只在「全量就绪」才落盘（`execute` 的 complete 判定）；
+    // 实例登记在 `run()` 的最后一步，取消后不该登记（读 profiles.json 这份唯一真相源）。
+    let version_json = game
+        .join("versions")
+        .join(&version)
+        .join(format!("{version}.json"));
+    let profiles = unlucky_core::game::install::instance::read_profiles(&launcher)
+        .expect("profiles.json 应可读（不存在 = 空清单）");
+    eprintln!(
+        "[cancel-test] 版本清单{} / profiles.json 里 {} 条实例",
+        if version_json.is_file() {
+            "已落盘"
+        } else {
+            "未落盘"
+        },
+        profiles.profiles.len()
+    );
+
+    // ---- 判据（修好之后必须成立的三条） ----
+    assert!(
+        after.is_empty(),
+        "取消之后还在被喂进度事件（{} 条）：面板会被重新点亮 = 用户看到的「点了没反应」",
+        after.len()
+    );
+    let settled = samples
+        .iter()
+        .find(|(at, _)| Duration::from_secs_f32(*at) >= settle)
+        .map(|(_, parts)| *parts)
+        .unwrap_or(parts_at_cancel);
+    let grew = samples
+        .iter()
+        .filter(|(at, _)| Duration::from_secs_f32(*at) >= settle)
+        .map(|(_, parts)| *parts)
+        .max()
+        .map_or(0, |peak| peak.saturating_sub(settled));
+    assert_eq!(
+        grew, 0,
+        "取消 {settle:?} 之后断点文件还在长（+{grew} 字节）：下载没有真的停"
+    );
+    assert_eq!(
+        parts_after, 0,
+        "取消之后还留着 {parts_after} 字节的 `.ullpart`：半截垃圾没清掉（D21 要的就是「清掉或标清楚」）"
+    );
+    assert!(
+        profiles.profiles.is_empty(),
+        "取消之后仍然登记了实例（profiles.json 有 {} 条）：半成品被记成成品",
+        profiles.profiles.len()
+    );
+    assert!(
+        !version_json.is_file(),
+        "取消之后仍然落了版本清单：半成品被记成「已安装」"
+    );
+
+    std::fs::remove_dir_all(&root).ok();
+}
+
+// --------------------------------------------------------------- CI 可跑的守门
+
+/// 一条安装进度快照（够画面板就行）。
+fn progress_snapshot(files_done: u64) -> InstallProgressView {
+    InstallProgressView {
+        version: "1.20.1".to_string(),
+        stage: InstallStage::Downloading,
+        files_done,
+        files_total: 512,
+        ..InstallProgressView::new()
+    }
+}
+
+/// **「点了取消没反应」的真根因**：取消之后旧任务的进度事件还在往回灌。
+///
+/// 现场：用户点「取消安装」→ host 收下取消、清 `install`、发 `InstallProgress(None)`（面板回弹），
+/// 但**后台线程还在跑**（core 的下载段不是瞬停的），它每下完一个文件就发一条
+/// `HostTask::Install`。没有代次的话这条事件照样被翻译成 `InstallProgress(Some(..))`，
+/// 面板立刻又被点亮 —— 用户看到的就是「取消按钮点了没反应」。
+///
+/// 抓得住：代次不符的 `Install` / `InstallDone` 被丢掉（面板不复燃、也不清掉新一轮的取消句柄）。
+/// 抓不住：真网络的取消延迟（那条在 `real_install_cancel_*`，`#[ignore]` 守着要手动跑）。
+#[test]
+fn progress_from_a_cancelled_job_is_dropped() {
+    let dir = std::env::temp_dir().join(format!("ull-cancel-epoch-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let mut host = CoreHost::headless(HostEnv::at_root(&dir));
+
+    // 开工：拿当代次
+    let epoch = host.next_install_epoch();
+    host.handle(HostTask::Install {
+        progress: Box::new(progress_snapshot(3)),
+        epoch,
+    });
+    let live: Vec<AppEvent> = host.drain_events();
+    assert!(
+        live.iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallProgress(Some(_))))),
+        "当代次的事件必须照常点亮面板"
+    );
+
+    // 取消
+    host.dispatch(AppCommand::CancelInstall);
+    let cancelled: Vec<AppEvent> = host.drain_events();
+    assert!(
+        cancelled
+            .iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallProgress(None)))),
+        "取消要立刻把面板收回（不等后台）"
+    );
+    assert!(
+        !cancelled
+            .iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallProgress(Some(_))))),
+        "取消本身不该重新点亮面板"
+    );
+
+    // 旧任务继续发进度（现场就是这样）——必须被丢掉
+    host.handle(HostTask::Install {
+        progress: Box::new(progress_snapshot(4)),
+        epoch,
+    });
+    host.handle(HostTask::InstallDone {
+        progress: Box::new(progress_snapshot(512)),
+        result: Err("已取消".to_string()),
+        epoch,
+    });
+    let after: Vec<AppEvent> = host.drain_events();
+    assert!(
+        after.is_empty(),
+        "取消之后旧任务的事件必须一条都不出（实际 {} 条）：出了就会把面板重新点亮",
+        after.len()
+    );
+
+    // 新一轮安装的代次是新的：它的进度照常生效
+    let fresh = host.next_install_epoch();
+    assert_ne!(fresh, epoch, "新一轮开工必须换代次");
+    host.handle(HostTask::Install {
+        progress: Box::new(progress_snapshot(1)),
+        epoch: fresh,
+    });
+    assert!(
+        host.drain_events()
+            .iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallProgress(Some(_))))),
+        "新一轮的进度要能点亮面板（不能把代次守卫写成「一律丢弃」）"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}

crates/presenter/src/host/dispatch.rs

@@ -0,0 +1,248 @@
+//! `CoreHost::dispatch` 的指令实现（从 `host/mod.rs` 拆出，守 400 行上限）。
+//!
+//! 父模块的私有字段对子模块可见，所以这里直接读写 `self.env` / `self.tx` 等。
+
+use crate::dto::{
+    AccountNoticeCode, AppCommand, Backend, CoreEvent, CreateRequest, LoaderKind, PackEvent,
+};
+use crate::toast::ToastKind;
+
+use super::accounts::{self, LoginJob};
+use super::{
+    addon, game, install, java, launch, loader_versions, logs, settings, versions, CoreHost,
+};
+
+impl CoreHost {
+    /// 下发一条用户意图（`Backend::dispatch` 的实现体）。
+    pub(super) fn dispatch_command(&mut self, command: AppCommand) {
+        self.dispatch_inner(command);
+    }
+}
+impl CoreHost {
+    /// 指令分发（见 `dispatch_command`）。
+    fn dispatch_inner(&mut self, command: AppCommand) {
+        match command {
+            AppCommand::RefreshAll => self.refresh_all(),
+            AppCommand::LaunchInstance(id) => self.start_launch(&id),
+            AppCommand::StopInstance(id) => match self.running_pid(&id) {
+                Some(pid) => match launch::stop(pid) {
+                    Ok(()) => self.toast(ToastKind::Info, "已请求停止游戏进程"),
+                    Err(reason) => self.toast(ToastKind::Error, reason),
+                },
+                None => self.toast(ToastKind::Warn, "这个实例当前没有在跑"),
+            },
+            AppCommand::ListVersions(_) => versions::spawn_list(self.env.clone(), self.tx.clone()),
+            AppCommand::ListLoaderVersions { kind, mc_version } => {
+                loader_versions::spawn_list(self.env.clone(), self.tx.clone(), kind, mc_version);
+            }
+            AppCommand::InstallVersion(version) => {
+                let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+                self.install_cancel = Some(std::sync::Arc::clone(&cancel));
+                let epoch = self.next_install_epoch();
+                install::spawn_install(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    CreateRequest {
+                        name: version.clone(),
+                        version,
+                        loader: LoaderKind::Vanilla,
+                        loader_version: String::new(),
+                    },
+                    cancel,
+                    epoch,
+                );
+            }
+            AppCommand::CreateInstance(request) => {
+                let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+                self.install_cancel = Some(std::sync::Arc::clone(&cancel));
+                let epoch = self.next_install_epoch();
+                install::spawn_install(self.env.clone(), self.tx.clone(), request, cancel, epoch);
+            }
+            AppCommand::CancelInstall => {
+                // 取消的三级语义（M105 实测后定稿，见 `install::CANCELLED`）：
+                // ① **面板立刻收回**（不等后台，用户点了就有反应）；
+                // ② **作废旧任务的代次**：后台线程是异步停的（取消延迟 = 一个数据块），
+                //    它带回来的进度事件一律因代次不符被 `handle` 丢掉——面板不会被重新点亮。
+                //    这是「点了没反应」的真根因：以前生效了又被旧事件盖回去；
+                // ③ 后台线程经 `install::run` 的取消检查停在段边界、**绝不登记实例**，
+                //    core 的 `execute_with_cancel` 还会就地掐断在飞的那个文件。
+                //
+                // 为什么不在这里 join 后台线程：UI 线程绝不能为了「等它停」而阻塞
+                // （一个数据块的延迟在人眼下就是「立刻」，但足以让 UI 卡住一帧以上）。
+                if let Some(cancel) = &self.install_cancel {
+                    cancel.store(true, std::sync::atomic::Ordering::SeqCst);
+                }
+                // M113: import/export —— 同一块面板的「取消」对导入也生效：立标记 + 作废 pack 代次
+                // 返回值告诉我们「刚才有没有导入在跑」：有的话**不能**再发 install 那条取消信号
+                // （它说的是「安装已取消、实例未创建」，而导入会在后台跑完并登记实例）。
+                let pack_was_running = addon::cancel_pack(&self.env);
+                if pack_was_running {
+                    self.send(CoreEvent::Pack(Box::new(PackEvent::Cancelled)));
+                }
+                self.install_epoch = self.install_epoch.wrapping_add(1);
+                self.install = None;
+                self.send(CoreEvent::InstallProgress(None));
+                // 只发信号、不发文案（复审 P2-2）：presenter 没有 i18n 依赖，
+                // 写死的中文会和页面语言打架。提示语由 app 层按 `Key` 现求。
+                // 导入在跑时不发这条：下载页那条文案说的是「实例未创建」，对导入是撒谎。
+                if !pack_was_running {
+                    self.send(CoreEvent::InstallCancelled);
+                }
+            }
+            AppCommand::SetIsolation { id, mode } => {
+                match game::set_isolation(&self.env, &id, &mode) {
+                    Ok(()) => {
+                        self.toast(ToastKind::Success, "隔离档位已更新");
+                        self.refresh_instances();
+                    }
+                    Err(reason) => self.toast(ToastKind::Error, reason),
+                }
+            }
+            AppCommand::RefreshLogSessions => {
+                self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+            }
+            AppCommand::OpenLogSession(id) => self.open_session(&id),
+            AppCommand::ImportCrashLog(path) => match logs::analyze_crash_file(&path) {
+                Ok((label, report)) => {
+                    self.send(CoreEvent::DiagnosisReady(report));
+                    self.toast(ToastKind::Info, label);
+                }
+                Err(reason) => self.toast(ToastKind::Warn, reason),
+            },
+            // 账户增删切：结果走**页面横幅**（`AccountNoticeChanged`），不发 toast——
+            // app-iced 不渲染 toast，发出去等于用户什么都看不到（复审 r1 P2-2）。
+            AppCommand::AddOfflineAccount(name) => match accounts::add_offline(&self.env, &name) {
+                Ok(display) => {
+                    self.notice(AccountNoticeCode::Added, &display, "");
+                    self.refresh_accounts();
+                }
+                Err(failure) => {
+                    self.notice_failure(failure, &name);
+                    self.refresh_accounts();
+                }
+            },
+            AppCommand::RemoveAccount(key) => match accounts::remove(&self.env, &key) {
+                Ok(display) => {
+                    if self.active_account.as_deref() == Some(key.as_str()) {
+                        self.active_account = None;
+                    }
+                    self.notice(AccountNoticeCode::Removed, &display, "");
+                    self.refresh_accounts();
+                }
+                Err(failure) => {
+                    self.notice_failure(failure, &key);
+                    self.refresh_accounts();
+                }
+            },
+            AppCommand::SwitchAccount(id) => {
+                let name = self
+                    .accounts
+                    .iter()
+                    .find(|account| account.id == id)
+                    .map_or_else(|| id.clone(), |account| account.name.clone());
+                self.active_account = Some(id);
+                self.refresh_accounts();
+                self.notice(AccountNoticeCode::Switched, &name, "");
+            }
+            AppCommand::DismissAccountNotice => {
+                self.send(CoreEvent::AccountNoticeChanged(None));
+            }
+            AppCommand::StartDeviceLogin => {
+                self.login = Some(LoginJob::new());
+                let job = self.login.clone().unwrap_or_default();
+                self.send(CoreEvent::DeviceLoginChanged(crate::dto::DeviceLoginView {
+                    phase: crate::dto::DeviceLoginPhase::Requesting,
+                    message: "正在向微软申请设备码…".to_string(),
+                    ..crate::dto::DeviceLoginView::new()
+                }));
+                accounts::start_login(self.env.clone(), self.tx.clone(), job);
+            }
+            AppCommand::StartBrowserLogin => {
+                self.login = Some(LoginJob::new());
+                let job = self.login.clone().unwrap_or_default();
+                self.send(CoreEvent::DeviceLoginChanged(crate::dto::DeviceLoginView {
+                    phase: crate::dto::DeviceLoginPhase::Requesting,
+                    message: "正在准备浏览器登录（本地回调端口）…".to_string(),
+                    ..crate::dto::DeviceLoginView::new()
+                }));
+                accounts::start_browser_login(self.env.clone(), self.tx.clone(), job);
+            }
+            AppCommand::CancelDeviceLogin => {
+                if let Some(job) = &self.login {
+                    job.cancel();
+                }
+                self.login = None;
+                // 第三方轨的面板也归这条「关掉登录面板」：两条轨都不该留一个转不完的圈
+                if let Some(job) = &self.authlib {
+                    job.cancel();
+                }
+                self.authlib = None;
+                self.send(CoreEvent::DeviceLoginChanged(
+                    crate::dto::DeviceLoginView::new(),
+                ));
+                self.send(CoreEvent::AuthlibLoginChanged(
+                    crate::dto::AuthlibLoginView::new(),
+                ));
+            }
+            AppCommand::AddAuthlibAccount(request) => {
+                self.authlib = Some(LoginJob::new());
+                let job = self.authlib.clone().unwrap_or_default();
+                self.send(CoreEvent::AuthlibLoginChanged(
+                    crate::dto::AuthlibLoginView::running(&request.server, "正在校验服务器地址…"),
+                ));
+                accounts::start_authlib_login(self.env.clone(), self.tx.clone(), job, request);
+            }
+            AppCommand::ProbeAuthlibServer(server) => {
+                // 只探活：后台线程跑服务发现，结果回到同一条 `AuthlibLoginChanged`
+                let env = self.env.clone();
+                let tx = self.tx.clone();
+                accounts::spawn_probe(env, tx, server);
+            }
+            AppCommand::InstallJava(vendor) => {
+                self.java_busy = true;
+                self.java_message = format!("正在安装 Java（{vendor}）…");
+                self.refresh_java();
+                java::spawn_install(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    unlucky_core::game::java::JdkVendor::parse(&vendor),
+                );
+            }
+            AppCommand::SetSetting { key, value } => match settings::set(&self.env, &key, &value) {
+                Ok(()) => {
+                    self.send(CoreEvent::SettingsChanged(settings::groups(&self.env)));
+                    self.java_chain.clear();
+                    self.refresh_java();
+                }
+                Err(reason) => self.toast(ToastKind::Error, reason),
+            },
+            AppCommand::DismissNotice(id) => {
+                self.notices.retain(|notice| notice.id != id);
+                self.send(CoreEvent::NoticesChanged(self.notices.clone()));
+            }
+            // M109：内容库检索（网络在后台线程，结果经 `HostTask::Content` 回来）
+            AppCommand::SearchContent(query) => {
+                addon::spawn_search(self.env.clone(), self.tx.clone(), query);
+            }
+            // M109：把某个内容项目装进指定实例。取消标记与安装面板共用同一条路
+            // （`CancelInstall` 会把标记置位，下载在阶段边界收尾）。
+            // M113: import/export —— 导入 / 预检 / 确认写盘 / 关面板
+            AppCommand::Pack(command) => self.pack(*command),
+            AppCommand::InstallContent(request) => {
+                let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+                self.install_cancel = Some(std::sync::Arc::clone(&cancel));
+                // 代次与版本安装共用同一条路（M105 的形状）：取消/被顶掉之后，旧任务带回来的
+                // 进度事件一律被 `handle` 丢掉，内容库种的这次安装不会把面板重新点亮。
+                let epoch = self.next_install_epoch();
+                addon::spawn_install(self.env.clone(), self.tx.clone(), *request, cancel, epoch);
+            }
+            // AI 对话：agent 的 GUI host 未落地前用脚本回复（不接真实模型）
+            other @ (AppCommand::AskAgent(_) | AppCommand::StopAgent | AppCommand::SetYolo(_)) => {
+                self.chat.dispatch(other);
+                for event in self.chat.drain_events() {
+                    self.events.push_back(event);
+                }
+            }
+        }
+    }
+}

crates/presenter/src/host/engine.rs

@@ -0,0 +1,126 @@
+//! 下载引擎与 Java 落点的装配（versions / install / java 三个任务共用）。
+//!
+//! 与 CLI `install::build_engine` 同源：内容寻址缓存落 `.ULL/cache/`，地区判定走
+//! 24h 缓存 + 环境信号（**不做网络探测**，与 D7 的「不探测时」约定一致）。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::download::region::{decide_from, load_cached, store_cached};
+use unlucky_core::download::region_system::detect_signals;
+use unlucky_core::download::{
+    ContentCache, DownloadEngine, EngineConfig, HealthRegistry, MirrorTable,
+};
+use unlucky_core::game::java::vendor::JdkVendor;
+use unlucky_core::game::java::{self, JavaInstallRoot};
+use unlucky_core::platform::paths::ProcessEnv;
+
+use super::env::HostEnv;
+
+/// 建下载引擎（缓存/健康度/地区判定都在数据根里）。
+pub fn engine(env: &HostEnv) -> DownloadEngine {
+    let cache_root = env.layout.cache();
+    let now = now_ms();
+    let region_path = cache_root.join("region.json");
+    let region = load_cached(&region_path, now).unwrap_or_else(|| {
+        let profile = decide_from(&detect_signals(), now);
+        let _ = store_cached(&region_path, &profile);
+        profile
+    });
+    DownloadEngine::new(
+        EngineConfig::default(),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(region),
+        Arc::new(HealthRegistry::open_in(&cache_root, now)),
+        Arc::new(ContentCache::open(&cache_root)),
+    )
+}
+
+/// 是否国内网络（决定默认发行版顺序与镜像优先级）。
+pub fn domestic(env: &HostEnv) -> bool {
+    engine(env).region().is_domestic()
+}
+
+/// 设置里的 `java.vendorPriority`（空 = 按地区默认序）。
+pub fn java_priority(env: &HostEnv) -> Vec<JdkVendor> {
+    env.store()
+        .effective("java.vendorPriority")
+        .and_then(serde_json::Value::as_array)
+        .map(|items| {
+            let texts: Vec<String> = items
+                .iter()
+                .filter_map(serde_json::Value::as_str)
+                .map(str::to_string)
+                .collect();
+            unlucky_core::game::java::vendor::parse_priority(&texts)
+        })
+        .unwrap_or_default()
+}
+
+/// 设置里的 `java.installRoot`（空 = 按数据目录模式派生）。
+pub fn java_install_override(env: &HostEnv) -> Option<PathBuf> {
+    env.store()
+        .doc()
+        .effective_str("java.installRoot")
+        .map(str::trim)
+        .filter(|text| !text.is_empty())
+        .map(PathBuf::from)
+}
+
+/// 托管 JDK 落点（解析失败 → 用户可读文案）。
+pub fn java_install_root(env: &HostEnv) -> Result<JavaInstallRoot, String> {
+    let override_root = java_install_override(env);
+    JavaInstallRoot::resolve(
+        env.mode(),
+        &env.layout,
+        override_root.as_deref(),
+        env.platform,
+        &ProcessEnv,
+    )
+    .map_err(|error| error.to_string())
+}
+
+/// 托管 JDK 可能存在的全部安装根（扫描运行时用）。
+pub fn java_scan_roots(env: &HostEnv) -> Vec<PathBuf> {
+    java::location::scan_roots(
+        env.mode(),
+        &env.layout,
+        java_install_override(env).as_deref(),
+        env.platform,
+        &ProcessEnv,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn engine_uses_the_data_root_cache() {
+        let dir = std::env::temp_dir().join(format!("ull-host-engine-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.cache()).expect("cache");
+        let engine = engine(&env);
+        assert_eq!(engine.config().max_concurrency, 64);
+        // 地区判定不联网：只读缓存/信号
+        let _ = domestic(&env);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn java_merge_priority_reads_settings() {
+        let dir = std::env::temp_dir().join(format!("ull-host-engine-p-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config");
+        std::fs::write(
+            env.launcher_config(),
+            r#"{"java":{"vendorPriority":["zulu"]}}"#,
+        )
+        .expect("写配置");
+        assert_eq!(java_priority(&env), vec![JdkVendor::Zulu]);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}

crates/presenter/src/host/env.rs

@@ -0,0 +1,170 @@
+//! host 的环境快照：一份 `ResolvedData` + 由其派生的布局视图。
+//!
+//! app 自己不解析三模式数据根（那是 `core::platform::data_dir` 的活）；这里只做两件事：
+//! ①按「exe 同级便携 `launcher.json` 的 `core.*` 四键」拼请求；②把解析结果与
+//! `Platform` / `DataMode` 打成一个可克隆的结构，交给后台线程。
+//!
+//! 截图/演示通道用 [`HostEnv::at_root`] 直接钉一个根（`<root>/.ULL` + `<root>/.minecraft`）。
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::game::GameLayout;
+use unlucky_core::platform::data_dir::{DataDirRequest, DataMode, ResolvedData, Resolver};
+use unlucky_core::platform::layout::LauncherLayout;
+use unlucky_core::platform::paths::Platform;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+/// 数据根决定键（与 CLI 的 `DATA_ROOT_KEYS` 同源同义）。
+pub(crate) const DATA_ROOT_KEYS: [&str; 4] = [
+    "core.data_mode",
+    "core.data_custom_root",
+    "core.launcher_home",
+    "core.game_home",
+];
+
+/// host 运行期需要的一切路径/平台信息（可克隆进线程）。
+#[derive(Debug, Clone)]
+pub struct HostEnv {
+    /// 数据根解析结果
+    pub data: ResolvedData,
+    /// `.ULL/` 布局
+    pub layout: LauncherLayout,
+    /// `.minecraft/` 布局
+    pub game: GameLayout,
+    /// 平台
+    pub platform: Platform,
+}
+
+impl HostEnv {
+    /// 按便携目录的 `core.*` 解析真实数据根；解析不出来返回 `None`（host 退回 mock）。
+    pub fn resolve() -> Option<Self> {
+        let exe_dir = std::env::current_exe()
+            .ok()
+            .and_then(|path| path.parent().map(Path::to_path_buf))?;
+        let request = request_from_portable(&exe_dir);
+        let resolver = Resolver::new(Platform::current(), Some(exe_dir));
+        let data = resolver.resolve_default(&request).ok()?.clone();
+        Some(Self::from_data(data))
+    }
+
+    /// 直接钉一个根：`<root>/.ULL` + `<root>/.minecraft`（截图/演示通道）。
+    ///
+    /// 根下已有 `config/launcher.json` 时**尊重其中的 `core.game_home` / `core.launcher_home`**：
+    /// 演示根常用它把游戏目录指到既有真数据上（避免复制几 GB 的 assets/libraries）。
+    pub fn at_root(root: impl AsRef<Path>) -> Self {
+        let root = root.as_ref();
+        let request = request_from_portable(root);
+        let absolute = |path: Option<PathBuf>| path.filter(|path| path.is_absolute());
+        Self::from_data(ResolvedData {
+            mode: DataMode::Portable,
+            launcher_home: absolute(request.launcher_home).unwrap_or_else(|| root.join(".ULL")),
+            game_home: absolute(request.game_home).unwrap_or_else(|| root.join(".minecraft")),
+            redirected_from: None,
+        })
+    }
+
+    /// 由解析结果建环境。
+    pub fn from_data(data: ResolvedData) -> Self {
+        Self {
+            layout: data.layout(),
+            game: GameLayout::new(data.game_home.clone()),
+            platform: Platform::current(),
+            data,
+        }
+    }
+
+    /// `config/launcher.json` 路径。
+    pub fn launcher_config(&self) -> PathBuf {
+        self.layout.launcher_config()
+    }
+
+    /// 设置存储（每次现读一份；写操作自己 save）。
+    pub fn store(&self) -> SettingStore {
+        SettingStore::load(self.launcher_config(), launcher_schema())
+    }
+
+    /// 启动会话根（`.ULL/data/agent/sessions`）。
+    pub fn sessions_root(&self) -> PathBuf {
+        self.layout.agent_sessions()
+    }
+
+    /// 数据目录模式。
+    pub fn mode(&self) -> DataMode {
+        self.data.mode
+    }
+
+    /// 人读一行（设置页「数据」分组展示）。
+    pub fn data_line(&self) -> String {
+        format!(
+            "{} · 启动器 {} · 游戏 {}",
+            self.data.mode,
+            self.data.launcher_home.display(),
+            self.data.game_home.display()
+        )
+    }
+}
+
+/// 便携目录那份 `launcher.json` → 数据根请求（只读 `core.*` 四键）。
+pub(crate) fn request_from_portable(exe_dir: &Path) -> DataDirRequest {
+    let mut request = DataDirRequest::default();
+    let path = portable_config_path(exe_dir);
+    if !path.is_file() {
+        return request;
+    }
+    let store = SettingStore::load(&path, launcher_schema());
+    let text = |key: &str| store.doc().effective_str(key).map(str::to_string);
+    if let Some(mode) = text(DATA_ROOT_KEYS[0]).as_deref().and_then(DataMode::parse) {
+        request.mode = mode;
+    }
+    if let Some(root) = text(DATA_ROOT_KEYS[1]) {
+        request.custom_root = Some(PathBuf::from(root));
+    }
+    if let Some(home) = text(DATA_ROOT_KEYS[2]) {
+        request.launcher_home = Some(PathBuf::from(home));
+    }
+    if let Some(home) = text(DATA_ROOT_KEYS[3]) {
+        request.game_home = Some(PathBuf::from(home));
+    }
+    request
+}
+
+/// `<exe 目录>/.ULL/config/launcher.json`。
+pub(crate) fn portable_config_path(exe_dir: &Path) -> PathBuf {
+    LauncherLayout::new(exe_dir.join(".ULL")).launcher_config()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn at_root_splits_launcher_and_game_homes() {
+        let env = HostEnv::at_root("D:/tmp/ull-demo");
+        assert_eq!(env.layout.home(), Path::new("D:/tmp/ull-demo/.ULL"));
+        assert_eq!(env.game.root(), Path::new("D:/tmp/ull-demo/.minecraft"));
+        assert_eq!(env.mode(), DataMode::Portable);
+        assert!(env.data_line().contains("portable"));
+    }
+
+    #[test]
+    fn portable_request_reads_core_keys_only_when_file_exists() {
+        let dir = std::env::temp_dir().join(format!("ull-host-env-{}", std::process::id()));
+        std::fs::create_dir_all(dir.join(".ULL/config")).expect("建目录");
+        let request = request_from_portable(&dir);
+        assert_eq!(request, DataDirRequest::default());
+
+        std::fs::write(
+            portable_config_path(&dir),
+            r#"{"core":{"data_mode":"custom","data_custom_root":"D:/data/ull"}}"#,
+        )
+        .expect("写配置");
+        let request = request_from_portable(&dir);
+        assert_eq!(request.mode, DataMode::Custom);
+        assert_eq!(
+            request.custom_root.as_deref(),
+            Some(Path::new("D:/data/ull"))
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}

crates/presenter/src/host/game.rs

@@ -0,0 +1,400 @@
+//! 实例快照：`profiles.json` + 版本 JSON + 会话索引 + 实例设置 → [`InstanceSummary`]。
+//!
+//! 「磁贴上的每个字」都在这里翻译完：版本号取自继承链根、加载器取自版本 id（解析在
+//! [`unlucky_core::game::loader`]，本文件只做 DTO 翻译）、最后游玩时间取自会话索引、
+//! 隔离档位取自实例设置（缺省跟全局 `instances.mode`）。
+
+use std::collections::BTreeMap;
+use std::path::Path;
+
+use unlucky_core::game::install::instance::{
+    read_instance_config, read_profiles, write_instance_config,
+};
+use unlucky_core::game::isolation::IsolationMode;
+use unlucky_core::game::{ProfileList, VersionJson};
+use unlucky_core::launch::session_index;
+
+use crate::dto::{
+    InstanceRuntime, InstanceSummary, LoaderInfo, LoaderKind, NoticeLevel, NoticeView,
+};
+
+use super::env::HostEnv;
+
+/// 全局默认隔离档位（`instances.mode`；缺键/坏值按 D20 默认 `isolated`）。
+pub fn global_mode(env: &HostEnv) -> IsolationMode {
+    env.store()
+        .doc()
+        .effective_str("instances.mode")
+        .and_then(IsolationMode::parse)
+        .unwrap_or_default()
+}
+
+/// 读实例清单（文件缺失 = 空列表，不是错误）。
+pub fn profiles(env: &HostEnv) -> ProfileList {
+    read_profiles(&env.layout).unwrap_or_default()
+}
+
+/// 全会话索引里「每个实例最近一次启动」的时间串。
+pub fn last_played(env: &HostEnv) -> BTreeMap<String, String> {
+    let index = session_index::index_path(&env.sessions_root());
+    let entries = session_index::read_all(&index).unwrap_or_default();
+    let mut map: BTreeMap<String, String> = BTreeMap::new();
+    for entry in entries {
+        if entry.instance_id.is_empty() || entry.started_at.is_empty() {
+            continue;
+        }
+        let current = map.get(&entry.instance_id);
+        if current.is_none_or(|existing| existing.as_str() < entry.started_at.as_str()) {
+            map.insert(entry.instance_id.clone(), entry.started_at);
+        }
+    }
+    map
+}
+
+/// 版本 JSON 的继承链根 id + 加载器（读不到返回 `(version_id, 原版)`）。
+pub fn describe_version(env: &HostEnv, version_id: &str) -> (String, LoaderInfo) {
+    let loader = loader_from_id(version_id);
+    let mut current = version_id.to_string();
+    let mut seen = 0;
+    while seen < 16 {
+        seen += 1;
+        let path = env.game.version_json(&current);
+        let Ok(text) = std::fs::read_to_string(&path) else {
+            break;
+        };
+        let Ok(json) = VersionJson::from_json_str(&text) else {
+            break;
+        };
+        match json.inherits_from {
+            Some(parent) if !parent.is_empty() => current = parent,
+            _ => break,
+        }
+    }
+    (current, loader)
+}
+
+/// 版本 id → 加载器。
+///
+/// 解析本身**不在这里**：真相源是 [`unlucky_core::game::loader`]（生成端
+/// `addon::loader::LoaderKind::version_id` 拼的是 `<mc>-<kind>-<loader>`，如
+/// `1.20.4-fabric-0.16.5`）。本函数只做两件事：调 core 的解析、把 core 的种类翻成 DTO
+/// 种类（`dto` 里不许出现 core 类型，翻译只能发生在 host 这条边界上）。
+pub fn loader_from_id(version_id: &str) -> LoaderInfo {
+    let parsed = unlucky_core::game::InstanceLoader::parse(version_id);
+    LoaderInfo {
+        kind: dto_kind(parsed.kind),
+        version: parsed.version,
+    }
+}
+
+/// core 的加载器种类 → DTO 种类。
+///
+/// **这里没有映射表**：种类由 core 的稳定 id 反查 DTO 词表得来（[`LoaderKind::parse`] →
+/// `dto::LoaderKind::from_core`，全仓唯一那份 core↔DTO 映射）。M134 之前这里是七支手写 match，
+/// M126 r3 复审实测过：core 加第八家、契约与 help 都补齐、**只在这一支写 `=> Vanilla`**，三个
+/// crate 全绿（402 / 220 / 42）而磁贴静默显示「原版」——M122 修掉的用户可见 bug 复活。委派之后
+/// **没有落笔处**：新种类必须先过 `dto::LoaderKind::from_core`（那边编不过就说明 DTO 还没决定怎么
+/// 显示它），糊错的后果由 `dto::instances` 的 `loader_kind_ids_are_the_released_contract` 与本
+/// 文件的 `every_core_loader_kind_reaches_the_tile_as_itself` 钉住。反查不到只能是 core 的
+/// `as_str` 与 `parse` 自相矛盾（同一张宏表长出来，物理上做不到），真发生了就 panic：**不许**
+/// 退回「原版」。
+fn dto_kind(kind: unlucky_core::game::LoaderKind) -> LoaderKind {
+    LoaderKind::parse(kind.as_str()).unwrap_or_else(|| {
+        unreachable!(
+            "core 的稳定 id `{}` 反查不到 DTO 种类：词表两边脱节了",
+            kind.as_str()
+        )
+    })
+}
+
+/// 实例的隔离档位（实例文件优先，缺省显示全局档位）。
+pub fn isolation_of(env: &HostEnv, id: &str) -> String {
+    let global = global_mode(env);
+    match read_instance_config(&env.layout, id) {
+        Ok(Some(config)) => config.effective_isolation(global).as_str().to_string(),
+        _ => global.as_str().to_string(),
+    }
+}
+
+/// 实例快照。
+pub fn instances(env: &HostEnv) -> Vec<InstanceSummary> {
+    let profiles = profiles(env);
+    let played = last_played(env);
+    profiles
+        .profiles
+        .iter()
+        .map(|profile| {
+            let version_id = profile.version_id.clone();
+            let (mc_version, loader) = describe_version(env, &version_id);
+            InstanceSummary {
+                id: profile.id.as_str().to_string(),
+                name: profile.name.clone(),
+                mc_version,
+                loader,
+                last_played: played.get(profile.id.as_str()).cloned(),
+                runtime: InstanceRuntime::Idle,
+                icon: None,
+                isolation: isolation_of(env, profile.id.as_str()),
+                version_present: env.game.is_version_installed(&version_id),
+                version_id,
+            }
+        })
+        .collect()
+}
+
+/// 改实例隔离档位（写实例设置文件；不动任何数据）。
+///
+/// # Errors
+///
+/// 实例不存在、文件读不了/写不了时返回用户可读文案。
+pub fn set_isolation(env: &HostEnv, id: &str, mode: &str) -> Result<(), String> {
+    let parsed = IsolationMode::parse(mode)
+        .ok_or_else(|| format!("未知隔离档位 `{mode}`（isolated / shared）"))?;
+    let profiles = profiles(env);
+    let profile = profiles
+        .profiles
+        .iter()
+        .find(|profile| profile.id.as_str() == id)
+        .ok_or_else(|| format!("找不到实例 `{id}`"))?;
+    let mut config = read_instance_config(&env.layout, id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?
+        .unwrap_or_else(|| {
+            unlucky_core::game::install::instance::InstanceConfig::new(
+                profile.id.as_str(),
+                &profile.version_id,
+            )
+        });
+    config.isolation = Some(match parsed {
+        IsolationMode::Isolated => unlucky_core::game::install::instance::Isolation::Isolated,
+        IsolationMode::Shared => unlucky_core::game::install::instance::Isolation::Shared,
+    });
+    write_instance_config(&env.layout, &config)
+        .map(|_| ())
+        .map_err(|error| format!("写实例设置失败：{error}"))
+}
+
+/// 启动前的切换检测：把 M30 的 `ModeChangeWarning` 翻成横幅通知。
+///
+/// 只在真启动时调用（会写 `lastModeChange.warned`，保证同一次切换只提示一次）。
+pub fn mode_change_notice(env: &HostEnv, id: &str) -> Option<NoticeView> {
+    let mut config = read_instance_config(&env.layout, id).ok()??;
+    let warning = config.take_mode_change_warning()?;
+    let _ = write_instance_config(&env.layout, &config);
+    Some(NoticeView::new(
+        &format!("isolation:{id}"),
+        NoticeLevel::Warn,
+        "隔离档位已切换",
+        &warning.message(),
+    ))
+}
+
+/// 建目录（数据根首次运行时）。
+pub fn ensure_root(env: &HostEnv) {
+    let _ = env.layout.ensure();
+    let _ = std::fs::create_dir_all(env.game.root());
+}
+
+/// 版本本体目录是否存在（启动前快速判断）。
+pub fn version_present(env: &HostEnv, version_id: &str) -> bool {
+    env.game.is_version_installed(version_id)
+}
+
+/// 路径显示成短串（通知/错误文案用）。
+pub fn short_path(path: &Path) -> String {
+    path.display().to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 版本 id → DTO 加载器的接口面（解析在 core，这里只验翻译没走样）。
+    ///
+    /// 抓得住：显示路径把某个种类翻错/翻塌（例如 Quilt 写成 Forge）——`dto_kind` 的委派与
+    /// `dto` 的 `from_core` 都落在这一条上；以及 core 解析端退回老口径（`fabric-loader-…` 才认、
+    /// 自家 `1.20.4-fabric-0.16.5` 认不出）——后两条正是 M122 的 bug 面。
+    /// 抓不住：core 解析规则本身（真值表在 `unlucky_core::game::loader` 的测试里，那边才是
+    /// 真相源）；也抓不住「版本号为空时不显示品牌名」那条（在 `LoaderInfo::badge` 与
+    /// app-iced 的 `loader_badge`，M120 已修，别在这里重复）。
+    #[test]
+    fn loader_parsing_covers_all_shapes() {
+        let cases = [
+            ("1.20.4", LoaderKind::Vanilla, ""),
+            // 自家口径（生成端 `LoaderKind::version_id`）：`<mc>-<kind>-<loader>`
+            ("1.20.4-fabric-0.16.5", LoaderKind::Fabric, "0.16.5"),
+            ("1.20.4-quilt-0.27.0", LoaderKind::Quilt, "0.27.0"),
+            ("1.20.1-forge-47.2.0", LoaderKind::Forge, "47.2.0"),
+            ("1.21.1-neoforge-21.1.80", LoaderKind::NeoForge, "21.1.80"),
+            // 老 HMCL 口径（存量实例还会带着它们）
+            ("fabric-loader-0.16.5-1.20.1", LoaderKind::Fabric, "0.16.5"),
+            ("quilt-loader-0.24.0-1.20.1", LoaderKind::Quilt, "0.24.0"),
+            // 第三方口径
+            ("1.13.2-OptiFine_HD_U_E6", LoaderKind::OptiFine, "HD_U_E6"),
+            ("1.12.2-LiteLoader", LoaderKind::LiteLoader, ""),
+        ];
+        for (id, kind, version) in cases {
+            let info = loader_from_id(id);
+            assert_eq!(info.kind, kind, "{id}");
+            assert_eq!(info.version, version, "{id}");
+            assert!(!info.badge().is_empty());
+        }
+    }
+
+    /// 显示路径的**全量**锚：core 的每一种加载器，从自家版本 id 走到磁贴时仍然是**它自己**。
+    ///
+    /// 清单取自 [`unlucky_core::game::LoaderKind::ALL`]，**不手抄**：M126 r3 复审实测出的缺口正是
+    /// 「手抄的清单跟着漏」——core 加第八家、契约与 help 都补齐、只在 `dto_kind` 那一支写
+    /// `=> Vanilla`，三个 crate 全绿而磁贴静默显示「原版」。`ALL` 由 core 的宏表长出来，加一家
+    /// 自动进圈，测试作者不需要（也没法）记得补一行。
+    ///
+    /// 抓得住：显示路径任何一环把种类翻塌成原版——`dto_kind` 又变回手写映射、`dto` 的
+    /// `from_core` 那一支接错、`label()` 被写成「原版」；**包括新加的那种**（那时 `ALL` 先变长）。
+    /// 抓不住：core 的 id 解析规则本身（真值表在 `unlucky_core::game::loader`）；版本号为空的
+    /// 徽标判据（M120 的 `loader_badge`，本 crate 不渲染）。
+    #[test]
+    fn every_core_loader_kind_reaches_the_tile_as_itself() {
+        use unlucky_core::game::LoaderKind as Core;
+        for kind in Core::ALL {
+            let info = loader_from_id(&format!("1.20.4-{}-0.16.5", kind.as_str()));
+            assert_eq!(
+                info.kind.as_str(),
+                kind.as_str(),
+                "core 的 {kind:?} 走到磁贴时变成了 `{}`（徽标 `{}`）",
+                info.kind.as_str(),
+                info.badge()
+            );
+            assert_eq!(
+                info.badge().starts_with(LoaderKind::Vanilla.label()),
+                kind == Core::Vanilla,
+                "core 的 {kind:?} 在磁贴上的徽标是 `{}`",
+                info.badge()
+            );
+        }
+    }
+
+    /// 端到端（数据层）：真装出来的四个加载器实例，走 [`instances`] 的快照各自带对加载器。
+    ///
+    /// 造的是本启动器**真实产物**的形状：`profiles.json` 里 `versionId` 是自家 id，
+    /// `versions/<id>/<id>.json` 里 `inheritsFrom` 指向原版层（生成端见
+    /// `unlucky_core::addon::loader`）。原版版本号由此取自继承链根，不是从 id 里切的。
+    ///
+    /// 抓得住：`describe_version` ↔ `loader_from_id` ↔ `instances` 这条链上任何一环把加载器
+    /// 丢掉（磁贴会显示「原版」——M122 的用户可见症状）；以及继承链根取错（磁贴的版本号）。
+    /// 抓不住：实例页真出图（走 app-iced 的视图模型与 `loader_badge`，本 crate 不渲染）；
+    /// 也抓不住「真下载安装了 Fabric/Quilt/Forge/NeoForge」——这里只伪造落盘结果。
+    #[test]
+    fn own_installed_instances_snapshot_carries_their_loader() {
+        let dir = std::env::temp_dir().join(format!("ull-host-game-own-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+
+        let cases = [
+            (
+                "1.20.4-fabric-0.16.5",
+                "1.20.4",
+                LoaderKind::Fabric,
+                "Fabric 0.16.5",
+            ),
+            (
+                "1.20.4-quilt-0.27.0",
+                "1.20.4",
+                LoaderKind::Quilt,
+                "Quilt 0.27.0",
+            ),
+            (
+                "1.20.1-forge-47.2.0",
+                "1.20.1",
+                LoaderKind::Forge,
+                "Forge 47.2.0",
+            ),
+            (
+                "1.21.1-neoforge-21.1.80",
+                "1.21.1",
+                LoaderKind::NeoForge,
+                "NeoForge 21.1.80",
+            ),
+        ];
+        for (version_id, mc_version, _, _) in cases {
+            for (id, inherits) in [(mc_version, None), (version_id, Some(mc_version))] {
+                let json = match inherits {
+                    Some(parent) => format!(r#"{{"id":"{id}","inheritsFrom":"{parent}"}}"#),
+                    None => format!(r#"{{"id":"{id}"}}"#),
+                };
+                let path = env.game.version_json(id);
+                std::fs::create_dir_all(path.parent().expect("版本目录")).expect("版本目录");
+                std::fs::write(&path, json).expect("写版本 JSON");
+            }
+        }
+
+        let profiles = ProfileList {
+            profiles: cases
+                .iter()
+                .map(
+                    |(version_id, _, _, _)| unlucky_core::game::InstanceProfile {
+                        id: unlucky_core::game::ProfileId::generate(),
+                        name: format!("装好的 {version_id}"),
+                        version_id: (*version_id).to_string(),
+                        game_dir: None,
+                        running_dir: None,
+                        java_path: None,
+                        created_at: None,
+                        last_played_at: None,
+                        extra: BTreeMap::new(),
+                    },
+                )
+                .collect(),
+            ..ProfileList::default()
+        };
+        unlucky_core::game::install::instance::write_profiles(&env.layout, &profiles)
+            .expect("写清单");
+
+        let snapshot = instances(&env);
+        assert_eq!(snapshot.len(), cases.len());
+        for ((version_id, mc_version, kind, badge), tile) in cases.iter().zip(&snapshot) {
+            assert_eq!(tile.version_id.as_str(), *version_id);
+            assert_eq!(
+                tile.mc_version.as_str(),
+                *mc_version,
+                "{version_id} 的版本号取错"
+            );
+            assert_eq!(tile.loader.kind, *kind, "{version_id} 的加载器");
+            assert_eq!(tile.loader.badge().as_str(), *badge, "{version_id} 的徽标");
+            assert!(tile.version_present, "{version_id} 的载荷应当存在");
+        }
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn isolation_write_then_read_round_trips() {
+        let dir = std::env::temp_dir().join(format!("ull-host-game-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+
+        // 直接建一份 profiles.json（register 需要版本本体，这里只测隔离写读）
+        let profiles = ProfileList {
+            profiles: vec![unlucky_core::game::InstanceProfile {
+                id: unlucky_core::game::ProfileId::generate(),
+                name: "demo".to_string(),
+                version_id: "1.20.1".to_string(),
+                game_dir: None,
+                running_dir: None,
+                java_path: None,
+                created_at: None,
+                last_played_at: None,
+                extra: BTreeMap::new(),
+            }],
+            ..ProfileList::default()
+        };
+        unlucky_core::game::install::instance::write_profiles(&env.layout, &profiles)
+            .expect("写清单");
+        let id = profiles.profiles[0].id.as_str().to_string();
+
+        assert_eq!(isolation_of(&env, &id), "isolated");
+        set_isolation(&env, &id, "shared").expect("切档位");
+        assert_eq!(isolation_of(&env, &id), "shared");
+        assert!(set_isolation(&env, &id, "nope").is_err());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}

crates/presenter/src/host/handle.rs

@@ -0,0 +1,206 @@
+//! `HostTask` → `CoreEvent` 的翻译（从 `host/mod.rs` 拆出，守 400 行硬限）。
+//!
+//! 父模块的私有字段对子模块可见，所以这里直接读写 `self.tx` / `self.launches` 等。
+
+use crate::dto::{AppEvent, CoreEvent, InstanceRuntime, LogOutcome, PackEvent};
+use crate::toast::ToastKind;
+
+use super::{addon, logs, CoreHost, HostTask, LiveLaunch};
+
+impl CoreHost {
+    /// 后台消息 → 事件。
+    pub(super) fn handle(&mut self, task: HostTask) {
+        match task {
+            HostTask::Versions(Ok(versions)) => self.send(CoreEvent::VersionListChanged(versions)),
+            HostTask::Versions(Err(reason)) => {
+                self.toast(ToastKind::Warn, format!("拉取版本清单失败：{reason}"));
+            }
+            HostTask::LoaderVersions {
+                kind,
+                mc_version,
+                result,
+            } => {
+                // 失败既要落进快照（页面禁用确认 + 显示具名原因），也要一条 Toast：
+                // 用户可能正盯着上面的版本列表，下拉那一行的红字容易被忽略。
+                if let Err(reason) = &result {
+                    self.toast(
+                        ToastKind::Warn,
+                        format!("取不到 {} 的加载器版本：{reason}", kind.label()),
+                    );
+                }
+                self.send(CoreEvent::LoaderVersions {
+                    kind,
+                    mc_version,
+                    result,
+                });
+            }
+            // M109：内容库检索。`Err` 不弹 toast——页面自己有失败态（四态之一），
+            // toast 只做「顺手提一句」会把可重试的错误变成一次性噪音。
+            HostTask::Content(result) => match *result {
+                Ok(results) => self.send(CoreEvent::ContentResults(Box::new(results))),
+                Err(reason) => self.send(CoreEvent::ContentFailed(reason)),
+            },
+            // M113: import/export —— 导入/导出事件带代次，取消后回来的旧事件一律丢掉
+            HostTask::Pack { event, epoch } => {
+                // pack 用**自己**的代次（复审 r1 P2-7）：共用安装的计数器会让
+                // 「关一次导入面板」把下载页正在跑的安装静默丢掉。
+                if epoch != addon::pack_epoch(&self.env) {
+                    return;
+                }
+                // 导入成功可能登记了新实例：与 `InstallDone` 同一条刷新（复审 r1 P2-1），
+                // 否则新实例要等下一次无关的 `RefreshAll` 才出现在实例页与目标 chips 里。
+                if matches!(*event, PackEvent::Report(_)) {
+                    self.refresh_instances();
+                }
+                self.send(CoreEvent::Pack(event));
+            }
+            // M105 的形状（代次丢包）为准：旧任务（已取消 / 被下一轮顶掉）的进度一律丢掉。
+            // 这是「点了取消没反应」的根因：取消时 `InstallProgress(None)` 刚把面板收回，
+            // 旧任务的下一条「下载中」事件立刻又把它点亮。
+            HostTask::Install { progress, epoch } => {
+                if epoch != self.install_epoch {
+                    return;
+                }
+                self.install = Some(*progress.clone());
+                self.send(CoreEvent::InstallProgress(Some(*progress)));
+            }
+            HostTask::InstallDone {
+                progress,
+                result,
+                epoch,
+            } => {
+                // 收尾同样看代次：取消之后那次「已取消」的收尾不该再动面板（面板早就回弹了），
+                // 也不该清掉**新一轮**安装的取消句柄。
+                if epoch != self.install_epoch {
+                    return;
+                }
+                self.install_cancel = None;
+                self.install = Some(*progress.clone());
+                self.send(CoreEvent::InstallProgress(Some(*progress)));
+                match result {
+                    Ok(_) => {
+                        self.refresh_instances();
+                        self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+                    }
+                    Err(reason) => self.toast(ToastKind::Error, reason),
+                }
+            }
+            HostTask::Accounts(accounts) => {
+                self.accounts = accounts.clone();
+                self.send(CoreEvent::AccountsChanged(accounts));
+                self.refresh_instances();
+            }
+            HostTask::Login(view) => self.send(CoreEvent::DeviceLoginChanged(*view)),
+            HostTask::Authlib(view) => self.send(CoreEvent::AuthlibLoginChanged(*view)),
+            HostTask::Avatar { id, skin } => {
+                // 抓到/没抓到都记下来（`None` = 试过了，不再重试），再把列表盖好发出去
+                self.skins.insert(id, skin);
+                self.attach_skins();
+                self.send(CoreEvent::AccountsChanged(self.accounts.clone()));
+            }
+            HostTask::Java(page) => self.send(CoreEvent::JavaChanged(*page)),
+            HostTask::Logs {
+                sessions,
+                lines,
+                diagnosis,
+            } => {
+                self.send(CoreEvent::LogSessionsChanged(sessions));
+                self.send(CoreEvent::LogLinesChanged(lines));
+                if let Some(report) = diagnosis {
+                    self.send(CoreEvent::DiagnosisReady(report));
+                }
+            }
+            HostTask::Sessions(sessions) => self.send(CoreEvent::LogSessionsChanged(sessions)),
+            HostTask::Tail(batch) => {
+                if batch.running {
+                    self.send(CoreEvent::LogLinesChanged(batch.lines));
+                } else {
+                    self.send(CoreEvent::LogAppended(*batch));
+                }
+            }
+            HostTask::LaunchStarted {
+                id,
+                session_id,
+                pid,
+            } => {
+                self.pending.remove(&id);
+                self.failed.remove(&id);
+                self.launches.retain(|live| live.instance != id);
+                self.launches.push(LiveLaunch {
+                    instance: id.clone(),
+                    session: session_id.clone(),
+                    pid,
+                });
+                // 实时尾随一次只跟一场（下载页/日志页共用一个滚动窗口）；
+                // 已有别的实例在尾随时不抢占——它的日志仍在 JSONL 里，收尾后可回放。
+                if self.tail.session().is_none() {
+                    self.tail.attach(
+                        self.env
+                            .sessions_root()
+                            .join("game")
+                            .join(format!("{session_id}.jsonl")),
+                        &session_id,
+                    );
+                }
+                self.send(CoreEvent::InstanceRuntimeChanged {
+                    id,
+                    runtime: InstanceRuntime::Running { pid },
+                });
+            }
+            HostTask::Runtime { id, runtime } => {
+                self.send(CoreEvent::InstanceRuntimeChanged { id, runtime });
+            }
+            HostTask::LaunchEnd(finished) => {
+                // 收尾可能发生在 LaunchStarted 之前（build_request / spawn 失败只发
+                // LaunchEnd）：pending 必须在这里也清掉，否则 in_flight 恒真、该实例
+                // 本会话内再也起不来。
+                self.pending.remove(&finished.id);
+                self.launches.retain(|live| live.instance != finished.id);
+                let runtime = if finished.outcome == LogOutcome::Ok {
+                    self.failed.remove(&finished.id);
+                    InstanceRuntime::Idle
+                } else {
+                    // 记住失败原因：随后的 refresh_instances 会重建快照，
+                    // 不记的话磁贴的「失败/重试」外观会被 Idle 盖掉。
+                    self.failed
+                        .insert(finished.id.clone(), finished.summary.clone());
+                    InstanceRuntime::Failed {
+                        reason: finished.summary.clone(),
+                    }
+                };
+                self.send(CoreEvent::InstanceRuntimeChanged {
+                    id: finished.id.clone(),
+                    runtime,
+                });
+                self.send(CoreEvent::LaunchFinished((*finished).clone()));
+                // 只拆自己那场的尾随：并发时另一实例的实时日志不该被这次收尾掐掉。
+                if self.tail.session() == Some(finished.session.as_str()) {
+                    self.tail.detach();
+                }
+                self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+                self.refresh_instances();
+            }
+            HostTask::Crash(report) => {
+                self.send(CoreEvent::DiagnosisReady(*report));
+            }
+            HostTask::Notice(notice) => self.push_notice(*notice),
+            HostTask::Toast(toast) => self.events.push_back(AppEvent::Toast(*toast)),
+        }
+    }
+
+    /// 尾随运行中会话（每 `TAIL_POLL_TICKS` 拍一次）。
+    pub(super) fn poll_tail(&mut self) {
+        let Some((session, lines)) = self.tail.poll() else {
+            return;
+        };
+        if lines.is_empty() {
+            return;
+        }
+        let running = self.launches.iter().any(|live| live.session == session);
+        self.send(CoreEvent::LogAppended(crate::dto::LiveLogBatch {
+            session,
+            lines,
+            running,
+        }));
+    }
+}

crates/presenter/src/host/identity.rs

@@ -0,0 +1,103 @@
+//! 启动身份：选中账户 → `AuthPlaceholders`（**凭据只在这里读，读完即丢**）+ 收尾结局映射。
+//!
+//! 与 CLI `commands/identity.rs` 同源：微软轨过期就静默续期并回写凭据（refresh_token 轮换，
+//! 旧值作废）；零账户回落离线占位，保证没有账户时照样能启动。
+
+use unlucky_core::auth::account::{AccountKind, Credentials};
+use unlucky_core::auth::microsoft::MicrosoftAuth;
+use unlucky_core::auth::offline::offline_login;
+use unlucky_core::auth::AccountStore;
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::game::ProfileId;
+use unlucky_core::launch::request::AuthPlaceholders;
+
+use crate::dto::LogOutcome;
+
+use super::env::HostEnv;
+
+/// 把选中账户翻成启动占位符（**凭据只在这里读，读完即丢**）。
+///
+/// 微软轨：过期就静默续期并回写凭据（refresh_token 轮换，旧值作废）。
+///
+/// # Errors
+///
+/// 账户不存在/凭据类型不符/令牌过期且刷新失败时返回用户可读文案。
+pub fn resolve(env: &HostEnv, account: Option<&str>) -> Result<(AuthPlaceholders, String), String> {
+    let store = AccountStore::open(env.layout.auth_data());
+    let chosen = match account {
+        Some(key) => store
+            .find(key)
+            .cloned()
+            .ok_or_else(|| format!("找不到账户 `{key}`"))?,
+        None => match store.accounts() {
+            [] => {
+                let uuid = ProfileId::generate().as_str().replace('-', "");
+                return Ok((
+                    AuthPlaceholders {
+                        player_name: "Player".to_string(),
+                        uuid,
+                        user_type: "legacy".to_string(),
+                        user_properties: "{}".to_string(),
+                        ..AuthPlaceholders::default()
+                    },
+                    "未登录账户，按离线占位启动".to_string(),
+                ));
+            }
+            [only] => only.clone(),
+            many => return Err(format!("有 {} 个账户，请在账户页选一个再启动", many.len())),
+        },
+    };
+    let line = format!("账户 {}（{}）", chosen.display_name(), chosen.kind.label());
+    match chosen.kind {
+        AccountKind::Offline => {
+            let placeholders =
+                offline_login(&chosen).map_err(|error| format!("离线账户解析失败：{error}"))?;
+            Ok((placeholders, line))
+        }
+        AccountKind::Microsoft => {
+            let Some(Credentials::Microsoft(session)) = store.credentials(&chosen.id) else {
+                return Err(format!(
+                    "账户 {} 的微软凭据缺失或类型不符，请重新登录",
+                    chosen.display_name()
+                ));
+            };
+            let auth =
+                MicrosoftAuth::from_env().map_err(|error| format!("微软登录不可用：{error}"))?;
+            let (fresh, _) = block_on(auth.ensure_fresh(session))
+                .map_err(|error| format!("微软令牌刷新失败：{error}"))?;
+            if &fresh != session {
+                // refresh_token 已轮换：立刻回写，旧值作废。
+                let mut store = AccountStore::open(env.layout.auth_data());
+                let _ = store.update_credentials(&chosen.id, Credentials::Microsoft(fresh.clone()));
+                let _ = store.save();
+            }
+            let placeholders = fresh
+                .to_placeholders()
+                .map_err(|error| format!("微软身份转换失败：{error}"))?;
+            Ok((placeholders, line))
+        }
+        AccountKind::AuthlibInjector => {
+            let Some(Credentials::AuthlibInjector(session)) = store.credentials(&chosen.id) else {
+                return Err(format!(
+                    "账户 {} 的第三方凭据缺失或类型不符",
+                    chosen.display_name()
+                ));
+            };
+            let placeholders = session
+                .to_placeholders()
+                .map_err(|error| format!("第三方身份转换失败：{error}"))?;
+            Ok((placeholders, line))
+        }
+    }
+}
+
+/// `SessionHandle` → 日志页的三种结局。
+pub fn outcome_of(handle: &unlucky_core::launch::SessionHandle) -> LogOutcome {
+    if handle.exit.silent_failure.is_some() {
+        LogOutcome::SilentFail
+    } else if handle.succeeded() {
+        LogOutcome::Ok
+    } else {
+        LogOutcome::Crashed
+    }
+}

crates/presenter/src/host/install.rs

@@ -0,0 +1,283 @@
+//! 安装：新建实例向导 / 下载页「安装」→ core 安装管线 → 登记实例。
+//!
+//! 与 CLI `ull install` 同序：`RemoteSource::resolve → InstallPlan::build → execute → register`。
+//! Forge/NeoForge 多一段 installer processors（[`super::install_processors`]）：
+//! `ProcessorPlan::build → 依赖库下载 → 选 Java → 串行 java -cp`，**跑完才写版本 JSON**。
+//! 差异只在线程模型：进度经 [`super::job::HostTask::Install`] 回流（文件计数 + 字节 + 速度/ETA），
+//! 且整段跑在后台线程里（`block_on` 不占 UI 线程）。
+//!
+//! 加载器范围：原版 + Fabric/Quilt/Forge/NeoForge（四家，与 CLI 对齐）。OptiFine/LiteLoader
+//! 两家 core 侧都还没有安装管线，仍在 GUI 里显式拒装并说清去哪装。
+//! 失败一律落 `.ULL/logs/install.log`（[`super::install_journal`]），文案里带日志路径。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::game::install::{InstallError, InstallReport};
+
+use crate::dto::{CreateRequest, InstallStage, LoaderKind};
+use crate::toast::{Toast, ToastKind};
+
+use super::env::HostEnv;
+use super::install_journal::Journal;
+use super::install_processors;
+use super::job::{spawn, HostTask, JobSender};
+use super::meter::Meter;
+
+mod routes;
+
+use routes::{install_loader, install_vanilla};
+
+/// 文件级并发上限（与 CLI 同值：16 路压满带宽又不至于打爆镜像）。
+pub const CONCURRENCY: usize = 16;
+
+/// 用户取消的稳定文案。
+///
+/// 三件事一句话说清（D21 的口径：半成品不许冒充成品，断点材料不留在半截状态）：
+/// ① 怎么停的（`execute_with_cancel` 不再起新文件，在飞的那个就地掐断）；
+/// ② 什么被留着（**已经下完**的文件，重装续用）；
+/// ③ 什么一定没发生（实例未登记、版本清单没落盘；在飞文件的 `.ullpart` 由 `PartFile::Drop` 清掉）。
+pub const CANCELLED: &str =
+    "已取消：剩下的文件没有开始下载，已下好的文件保留（重装续用），实例未登记";
+
+/// 一次安装任务的运行上下文（后台线程内一路传下去，免得每个函数排七八个参数）。
+struct Job<'a> {
+    env: &'a HostEnv,
+    tx: &'a JobSender,
+    meter: &'a Arc<std::sync::Mutex<Meter>>,
+    cancel: &'a Arc<AtomicBool>,
+    journal: &'a Journal,
+}
+
+impl Job<'_> {
+    /// processor 段的进度出口（同一套 channel/meter/journal）。
+    fn reporter(&self) -> install_processors::Reporter<'_> {
+        install_processors::Reporter {
+            tx: self.tx,
+            meter: self.meter,
+            journal: self.journal,
+        }
+    }
+}
+
+/// 加载器徽标（`原版` / `Fabric 0.16.5`）。
+pub fn loader_label(kind: LoaderKind, version: &str) -> String {
+    if kind == LoaderKind::Vanilla || version.trim().is_empty() {
+        kind.label().to_string()
+    } else {
+        format!("{} {}", kind.label(), version)
+    }
+}
+
+/// GUI 侧支持的加载器（五选：原版 + 四家加载器，与 CLI 的 `--loader` 词表一致）。
+///
+/// 写成穷举 `matches!` 而不是 `true`：将来 core 加了第六种加载器，这里默认拒绝，
+/// 由 [`unsupported_reason`] 给出明确说法，而不是让它走进不属于它的安装分支。
+pub fn supported(kind: LoaderKind) -> bool {
+    matches!(
+        kind,
+        LoaderKind::Vanilla
+            | LoaderKind::Fabric
+            | LoaderKind::Quilt
+            | LoaderKind::Forge
+            | LoaderKind::NeoForge
+    )
+}
+
+/// 不支持的加载器 → 给用户的可执行建议。
+pub fn unsupported_reason(kind: LoaderKind) -> String {
+    format!(
+        "{} 还没有接入安装管线（目前支持原版 + Fabric/Quilt/Forge/NeoForge）；请先在实例页导入已有版本，或换成受支持的加载器。",
+        kind.label()
+    )
+}
+
+/// 后台安装（向导提交 / 下载页行内安装共用）。
+///
+/// `epoch` 是本次任务的代次（[`super::CoreHost`] 的 `install_epoch`）：它随每条进度回流，
+/// 让 host 丢掉「已被取消 / 被下一轮顶掉」的旧任务的后续事件。
+pub fn spawn_install(
+    env: HostEnv,
+    tx: JobSender,
+    request: CreateRequest,
+    cancel: Arc<AtomicBool>,
+    epoch: u64,
+) {
+    spawn("install", move || {
+        let meter = Arc::new(std::sync::Mutex::new(Meter::new(&request, epoch)));
+        let journal = Journal::open(&env);
+        journal.line(&format!(
+            "—— 开始安装 {}（{} {}）——",
+            request.instance_name(),
+            loader_label(request.loader, ""),
+            request.version
+        ));
+        let job = Job {
+            env: &env,
+            tx: &tx,
+            meter: &meter,
+            cancel: &cancel,
+            journal: &journal,
+        };
+        let result = run(&job, &request);
+        let mut progress = meter
+            .lock()
+            .map(|guard| guard.progress.clone())
+            .unwrap_or_else(|_| Meter::new(&request, epoch).progress);
+        match result {
+            Ok(name) => {
+                journal.line(&format!("完成：实例 {name} 已登记"));
+                progress.stage = InstallStage::Done;
+                progress.files_done = progress.files_total;
+                progress.message = format!("已安装 {name}（{}）", progress.loader);
+                let _ = tx.send(HostTask::InstallDone {
+                    progress: Box::new(progress),
+                    result: Ok(name),
+                    epoch,
+                });
+                let _ = tx.send(HostTask::Toast(Box::new(Toast {
+                    id: 0,
+                    kind: ToastKind::Success,
+                    text: "安装完成，实例已登记".to_string(),
+                    remaining_ms: 0,
+                })));
+            }
+            Err(reason) => {
+                let cancelled = reason == CANCELLED;
+                progress.stage = if cancelled {
+                    InstallStage::Cancelled
+                } else {
+                    InstallStage::Failed
+                };
+                // 失败文案带上日志路径：面板只有一行、Toast 4 秒就消失，
+                // 装日志是用户事后能自己回看的唯一渠道（进度板之外）。
+                let text = if cancelled {
+                    journal.line(CANCELLED);
+                    reason
+                } else {
+                    journal.line(&format!("安装未完成：{reason}"));
+                    format!("{reason}（日志：{}）", journal.path().display())
+                };
+                progress.message.clone_from(&text);
+                let _ = tx.send(HostTask::InstallDone {
+                    progress: Box::new(progress),
+                    result: Err(text),
+                    epoch,
+                });
+            }
+        }
+    });
+}
+
+/// 真安装（同步跑完，调用方在后台线程里）。
+fn run(job: &Job<'_>, request: &CreateRequest) -> Result<String, String> {
+    if request.version.trim().is_empty() {
+        return Err("没有选择版本".to_string());
+    }
+    if !supported(request.loader) {
+        return Err(unsupported_reason(request.loader));
+    }
+    let name = request.instance_name();
+    let env = job.env;
+    let engine = super::engine::engine(env);
+    {
+        let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+        guard.stage(InstallStage::Planning, "正在解析版本清单…");
+        let _ = job.tx.send(HostTask::Install {
+            progress: Box::new(guard.progress.clone()),
+            epoch: guard.epoch,
+        });
+    }
+
+    // 段边界检查（M105）：`execute_with_cancel` 自己会掐断在飞的文件，这里管的是**段与段之间**
+    // ——原版段与加载器段、文件段与登记之间，取消都必须在下一段开工前生效。
+    if job.cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+    let version_id = if request.loader == LoaderKind::Vanilla {
+        install_vanilla(job, &engine, request)?
+    } else {
+        install_loader(job, &engine, request)?
+    };
+
+    // **取消之后绝不登记实例**（M105）：文件段已经在跑了，下完那一刻用户可能早已点了取消；
+    // 这里不拦的话，取消会留下一个「用户以为没装、其实已经装好并登记」的实例——
+    // 那正是「半成品污染」里最难解释的一种（列表里凭空多一条）。
+    if job.cancel.load(Ordering::SeqCst) {
+        job.journal
+            .line("已取消：文件段跑完但用户已取消，不登记实例（版本清单是否落盘见上）");
+        return Err(CANCELLED.to_string());
+    }
+
+    {
+        let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+        guard.stage(InstallStage::Registering, "正在登记实例…");
+        let _ = job.tx.send(HostTask::Install {
+            progress: Box::new(guard.progress.clone()),
+            epoch: guard.epoch,
+        });
+    }
+    let created_at =
+        unlucky_core::launch::time::format_rfc3339_millis(unlucky_core::launch::time::now());
+    unlucky_core::game::install::instance::register(
+        &env.layout,
+        &name,
+        &version_id,
+        Some(&created_at),
+    )
+    .map_err(|error| format!("登记实例失败：{error}"))?;
+    Ok(name)
+}
+
+/// 安装错误 → 用户可读文案（**取消不算失败**：给那句稳定文案，不给「失败 + 日志路径」）。
+///
+/// 判据用 job 自己的取消标志而不是错误大类：core 的 `execute_with_cancel` 只在阶段边界与
+/// 每个文件开工前看标志，取消与「最后一个文件刚好失败」可能同时成立——那种情况下用户点了取消，
+/// 文案就该说取消（否则他会以为取消导致了失败）。
+fn job_error(job: &Job<'_>, error: InstallError) -> String {
+    if job.cancel.load(Ordering::SeqCst) {
+        return CANCELLED.to_string();
+    }
+    install_error(error)
+}
+
+/// 安装错误 → 用户可读文案。
+fn install_error(error: InstallError) -> String {
+    match error.hint() {
+        Some(hint) => format!("{}（{hint}）", error.message()),
+        None => error.message().to_string(),
+    }
+}
+
+/// 有文件失败就报错（列前三条明细）。
+fn ensure_complete(report: &InstallReport) -> Result<(), String> {
+    if report.is_complete() {
+        return Ok(());
+    }
+    let details: Vec<String> = report
+        .failures(3)
+        .iter()
+        .filter_map(|outcome| {
+            outcome
+                .failure
+                .as_ref()
+                .map(|failure| format!("{}：{}", outcome.name, failure.message))
+        })
+        .collect();
+    Err(format!(
+        "{} 个文件没下成（共 {} 个）：{}",
+        report.failed(),
+        report.files.len(),
+        details.join("；")
+    ))
+}
+
+/// 安装目录的短显示（诊断/Toast 用）。
+pub fn game_root(env: &HostEnv) -> PathBuf {
+    env.game.root().to_path_buf()
+}
+
+#[cfg(test)]
+#[path = "install_tests.rs"]
+mod tests;

crates/presenter/src/host/install/routes.rs

@@ -0,0 +1,183 @@
+//! 两条安装路线（原版 / 加载器）——M105 从 `install.rs` 搬出，守 400 行硬线。
+//!
+//! 搬移是**纯搬移**：函数体一行没改，只多了本文件自己的 `use`。
+//! 父模块（`install`）的私有项对子模块可见，所以 `Job` / `CANCELLED` / `job_error` /
+//! `ensure_complete` / `sink_for` 一律不重新导出，直接用。
+
+use std::sync::atomic::Ordering;
+use std::sync::Arc;
+
+use unlucky_core::addon::loader::{
+    LoaderInstallPlan, LoaderKind as CoreLoaderKind, LoaderPlanInput, LoaderSource,
+};
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::{execute_with_cancel, InstallPlan, PlanInput, RemoteSource};
+
+use crate::dto::{CreateRequest, InstallStage, LoaderKind};
+
+use super::super::install_processors::{self, StageInput};
+use super::super::meter::sink_for;
+use super::{ensure_complete, install_error, job_error, Job, CANCELLED, CONCURRENCY};
+
+/// 原版安装（`resolve → plan → [prefetch 资源索引] → execute`）。
+pub(super) fn install_vanilla(
+    job: &Job<'_>,
+    engine: &DownloadEngine,
+    request: &CreateRequest,
+) -> Result<String, String> {
+    let env = job.env;
+    let version = request.version.trim();
+    let meta_cache = env.layout.meta_cache();
+    let now = now_ms();
+    let sink = sink_for(job.tx.clone(), Arc::clone(job.meter));
+    block_on(async {
+        let source = RemoteSource::new(engine, &env.game, &meta_cache, now);
+        let resolved = source.resolve(version).await.map_err(install_error)?;
+        let fetched = match resolved
+            .asset_index
+            .as_ref()
+            .filter(|index| index.url.is_some())
+        {
+            Some(reference) => {
+                let (index, bytes) = source.asset_index(reference).await.map_err(install_error)?;
+                Some((index, env.game.asset_index(&reference.id), bytes))
+            }
+            None => None,
+        };
+        let mut plan = InstallPlan::build(PlanInput {
+            layout: &env.game,
+            version_id: version,
+            resolved: &resolved,
+            asset_index: fetched.as_ref().map(|(index, _, _)| index),
+            environment: &Environment::host(),
+        })
+        .map_err(|error| error.to_string())?;
+        if let Some((_, dest, bytes)) = fetched {
+            plan.prefetch(dest, bytes);
+        }
+        if !plan.is_installable() {
+            return Err(format!(
+                "版本 {version} 装不全：{}",
+                plan.warnings.join("；")
+            ));
+        }
+        let (bytes_total, _) = plan.total_bytes();
+        {
+            let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+            guard.progress.files_total = u64::try_from(plan.file_count()).unwrap_or(u64::MAX);
+            guard.progress.bytes_total = bytes_total;
+            guard.stage(
+                InstallStage::Downloading,
+                &format!("开始下载 {} 个文件…", plan.file_count()),
+            );
+        }
+        if job.cancel.load(Ordering::SeqCst) {
+            return Err(CANCELLED.to_string());
+        }
+        let report = execute_with_cancel(
+            engine,
+            &plan,
+            CONCURRENCY,
+            Some(sink),
+            Some(job.cancel.as_ref()),
+        )
+        .await
+        .map_err(|error| job_error(job, error))?;
+        ensure_complete(&report)?;
+        Ok::<String, String>(version.to_string())
+    })
+}
+
+/// 加载器安装（原版前置 → installer processors → 加载器库 → 版本 JSON 落盘）。
+pub(super) fn install_loader(
+    job: &Job<'_>,
+    engine: &DownloadEngine,
+    request: &CreateRequest,
+) -> Result<String, String> {
+    let env = job.env;
+    let version = request.version.trim();
+    let kind = CoreLoaderKind::parse(request.loader.as_str())
+        .ok_or_else(|| format!("未知加载器 `{}`", request.loader.as_str()))?;
+    let meta_cache = env.layout.meta_cache();
+    let loader_version = request.loader_version.trim().to_string();
+    let explicit = (!loader_version.is_empty()).then_some(loader_version.as_str());
+    let release = block_on(async {
+        LoaderSource::new(engine, &meta_cache)
+            .resolve(kind, version, explicit)
+            .await
+    })
+    .map_err(|error| error.to_string())?;
+    job.journal.line(&format!(
+        "加载器解析：{} {} → {}",
+        release.kind.label(),
+        release.loader_version,
+        release.version_id
+    ));
+
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &env.game,
+        release: &release,
+        environment: &Environment::host(),
+        vanilla_installed: env.game.is_version_installed(version),
+    });
+    if plan.vanilla_install_needed {
+        let mut vanilla = request.clone();
+        vanilla.loader = LoaderKind::Vanilla;
+        install_vanilla(job, engine, &vanilla)?;
+    }
+    // 两段（加载器库 + 处理器依赖库）在动手前一次预记账：进度条只走一条单调曲线，
+    // 处理器依赖库下完不会先满格、再在加载器库开始时回落到一半。
+    {
+        let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+        let (bytes, _) = plan.install.total_bytes();
+        guard.expect(plan.files().len(), bytes);
+    }
+    // Forge/NeoForge：installer processors 必须先跑完，`execute` 才允许写版本 JSON。
+    if release.requires_installer() {
+        let input = StageInput {
+            kind: release.kind,
+            mc_version: &release.mc_version,
+            version_id: &release.version_id,
+            profile: release.install_profile.as_ref(),
+            installer: release.installer.as_deref(),
+            installed: env.game.is_version_installed(&release.version_id),
+        };
+        // `None` = 这一版不需要跑处理器（版本 JSON 已在盘上 / profile 没有 client 侧步骤），
+        // 进度与日志都由处理器段自己写全，这里只消费返回值。
+        let _ = install_processors::stage(
+            env,
+            engine,
+            &input,
+            &install_processors::CORE,
+            &job.reporter(),
+            job.cancel,
+        )?;
+    }
+    {
+        let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+        guard.stage(
+            InstallStage::Downloading,
+            &format!("开始下载加载器库（{} 个文件）…", plan.files().len()),
+        );
+    }
+    if job.cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+    let sink = sink_for(job.tx.clone(), Arc::clone(job.meter));
+    let report = block_on(async {
+        execute_with_cancel(
+            engine,
+            &plan.install,
+            CONCURRENCY,
+            Some(sink),
+            Some(job.cancel.as_ref()),
+        )
+        .await
+    })
+    .map_err(|error| job_error(job, error))?;
+    ensure_complete(&report)?;
+    Ok(release.version_id)
+}

crates/presenter/src/host/install_journal.rs

@@ -0,0 +1,79 @@
+//! 安装过程的可回溯日志（`.ULL/logs/install.log`，一轮一行）。
+//!
+//! 起因（M45）：Forge/NeoForge 装失败时，GUI 只有一行 Toast，processor 的 stderr 尾部
+//! 与「哪一步挂了」在面板一关就没了。这里把安装过程按行追加到 `.ULL/logs/`
+//! （与 `auth.jsonl` 同一分区），失败文案里带上日志路径，用户能自己回看。
+//!
+//! 三条纪律（与 auth 日志同源）：
+//! 1. **只追加**，不轮转、不截断（体积由「一行一条、只记诊断字段」控制）；
+//! 2. **只记诊断字段**：阶段、processor 坐标、退出码、已脱敏的 stderr 尾部（core 侧脱敏）；
+//! 3. **写盘尽力而为**：开不了文件就静默跳过，绝不让日志失败连累安装。
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use unlucky_core::launch::time;
+
+use super::env::HostEnv;
+
+/// 日志文件名（在 `.ULL/logs/` 下）。
+pub const INSTALL_LOG_FILE: &str = "install.log";
+
+/// 一轮安装的日志句柄（`Clone` 很便宜：只有一个路径）。
+#[derive(Debug, Clone)]
+pub struct Journal {
+    path: PathBuf,
+}
+
+impl Journal {
+    /// 按数据根打开（`logs/` 不存在就补建；建不出来只是没有日志）。
+    pub fn open(env: &HostEnv) -> Self {
+        let dir = env.layout.logs();
+        let _ = std::fs::create_dir_all(&dir);
+        Self {
+            path: dir.join(INSTALL_LOG_FILE),
+        }
+    }
+
+    /// 日志路径（失败文案里给用户看）。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 追加一行（自动补 RFC3339 时间戳；写失败静默）。
+    pub fn line(&self, text: &str) {
+        let Ok(mut file) = std::fs::OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&self.path)
+        else {
+            return;
+        };
+        let _ = writeln!(
+            file,
+            "[{}] {text}",
+            time::format_rfc3339_millis(time::now())
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn lines_are_appended_with_a_timestamp() {
+        let root = std::env::temp_dir().join(format!("ull-install-journal-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&root);
+        let env = HostEnv::at_root(&root);
+        let journal = Journal::open(&env);
+        journal.line("第一行");
+        journal.line("第二行");
+        let text = std::fs::read_to_string(journal.path()).expect("日志存在");
+        assert!(text.contains("第一行") && text.contains("第二行"), "{text}");
+        assert_eq!(text.lines().count(), 2);
+        assert!(text.starts_with("[2"), "带时间戳：{text}");
+        assert_eq!(journal.path(), env.layout.logs().join(INSTALL_LOG_FILE));
+        std::fs::remove_dir_all(&root).ok();
+    }
+}

crates/presenter/src/host/install_processors.rs

@@ -0,0 +1,382 @@
+//! Forge / NeoForge 的 installer processors 段（M45：GUI 与 CLI 行为对齐）。
+//!
+//! 顺序与 CLI `ull install --loader forge` 完全一致（`crates/cli/src/commands/install/
+//! loader_processors.rs`），只是把进度接到 GUI 的回流通道上：
+//!
+//! ```text
+//! ProcessorPlan::build（纯计算：变量表 + 每步 java -cp + 依赖库清单）
+//!   → download_libraries（M27 引擎；进度回流 HostTask::Install）
+//!   → select_java（M33 解析链：托管 > JAVA_HOME > PATH > 扫盘）
+//!   → run（串行 java -cp；每步一条面板文案 + 一行装日志）
+//! ```
+//!
+//! 四条硬约束（与 CLI 同源，GUI 侧一条都不放宽）：
+//!
+//! 1. **processors 跑完才允许写版本 JSON**：版本清单存在 = 这版装完了，抢在 processors
+//!    前写会留下启动必崩却被报成"已安装"的实例（顺序由 `install_loader` 保证）；
+//! 2. **幂等**：版本 JSON 已在盘上 = 上一轮跑完了，整段跳过；
+//! 3. **取消在阶段边界生效**：处理器阶段是原子段（串行外调 java，进程内没有取消钩子），
+//!    进入前与退出后各查一次 `cancel`；
+//! 4. **失败不静默**：结构化文案（带 `processor_*` 大类码）+ 装日志一行一条，由调用方
+//!    再补 Toast（`HostTask::InstallDone` 的既有通路）。
+//!
+//! 执行后端走 [`Backend`]：真实实现 [`CoreBackend`] 直接转调 core，单测注入 fake，
+//! 因此「计划怎么组、Java 找不到怎么说、依赖库下漏怎么报」都能在没有网络/没有 JDK
+//! 的机器上断言。
+
+use std::path::Path;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::addon::loader::forge::InstallProfile;
+use unlucky_core::addon::loader::processors::{
+    self, ProcessorError, ProcessorPlan, ProcessorPlanInput, ProcessorRun, StepOutcome, StepSink,
+    StepStatus,
+};
+use unlucky_core::addon::loader::LoaderKind as CoreLoaderKind;
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::{InstallReport, PlanFile, ProgressSink};
+use unlucky_core::game::java::{JavaRequirement, JavaRuntime};
+
+use crate::dto::InstallStage;
+
+use super::env::HostEnv;
+use super::install::{CANCELLED, CONCURRENCY};
+use super::install_journal::Journal;
+use super::job::{HostTask, JobSender};
+use super::meter::{sink_for, Meter};
+
+/// 真实后端（无状态，可以放静态里复用）。
+pub(super) const CORE: CoreBackend = CoreBackend;
+
+/// processors 段需要的输入（从 `LoaderRelease` 摘出来，便于单测构造）。
+pub(super) struct StageInput<'a> {
+    /// 加载器种类（补库时 maven 基址的兜底来源）。
+    pub kind: CoreLoaderKind,
+    /// 目标原版版本。
+    pub mc_version: &'a str,
+    /// loader 版本 id（依赖库落点 + 临时目录名）。
+    pub version_id: &'a str,
+    /// installer 里读出来的 install profile（`requires_installer` 为真时必须有）。
+    pub profile: Option<&'a InstallProfile>,
+    /// installer jar 的磁盘路径。
+    pub installer: Option<&'a Path>,
+    /// 版本 JSON 已在盘上 = 上一轮跑完了，整段跳过（幂等）。
+    pub installed: bool,
+}
+
+/// processors 段的执行后端（真实实现转调 core；单测注入 fake）。
+pub(super) trait Backend {
+    /// 下载 processor 依赖库（M27 引擎：镜像/健康度/退避/校验）。
+    fn download_libraries(
+        &self,
+        engine: &DownloadEngine,
+        files: &[PlanFile],
+        sink: Option<ProgressSink>,
+    ) -> InstallReport;
+    /// 按 M33 的解析链挑一个能跑 installer 的 Java。
+    fn select_java(&self, managed: &Path, requirement: &JavaRequirement) -> Option<JavaRuntime>;
+    /// 串行跑 processors。
+    fn run(
+        &self,
+        plan: &ProcessorPlan,
+        java: &JavaRuntime,
+        sink: Option<StepSink>,
+    ) -> Result<ProcessorRun, ProcessorError>;
+}
+
+/// 真实后端：三件事全部转调 core 的同一个执行器（CLI 用的就是它）。
+pub(super) struct CoreBackend;
+
+impl Backend for CoreBackend {
+    fn download_libraries(
+        &self,
+        engine: &DownloadEngine,
+        files: &[PlanFile],
+        sink: Option<ProgressSink>,
+    ) -> InstallReport {
+        block_on(processors::download_libraries(
+            engine,
+            files,
+            CONCURRENCY,
+            sink,
+        ))
+    }
+
+    fn select_java(&self, managed: &Path, requirement: &JavaRequirement) -> Option<JavaRuntime> {
+        processors::select_java(managed, requirement)
+    }
+
+    fn run(
+        &self,
+        plan: &ProcessorPlan,
+        java: &JavaRuntime,
+        sink: Option<StepSink>,
+    ) -> Result<ProcessorRun, ProcessorError> {
+        processors::run(plan, java, sink)
+    }
+}
+
+/// 段内的进度出口：进度面板（`HostTask::Install`）+ 装日志。
+pub(super) struct Reporter<'a> {
+    /// 后台线程 → host 的通道。
+    pub tx: &'a JobSender,
+    /// 进度记账器。
+    pub meter: &'a Arc<Mutex<Meter>>,
+    /// 装日志。
+    pub journal: &'a Journal,
+}
+
+impl Reporter<'_> {
+    /// 换阶段并推一条进度。
+    fn stage(&self, stage: InstallStage, message: &str) {
+        let Ok(mut guard) = self.meter.lock() else {
+            return;
+        };
+        guard.stage(stage, message);
+        let _ = self.tx.send(HostTask::Install {
+            progress: Box::new(guard.progress.clone()),
+            epoch: guard.epoch,
+        });
+    }
+
+    /// 先把待下的库记账（文件数 + 已知字节），下载回调再逐个累加。
+    fn expect(&self, files: usize, bytes: u64) {
+        let Ok(mut guard) = self.meter.lock() else {
+            return;
+        };
+        guard.expect(files, bytes);
+    }
+
+    /// 失败留痕（文案由调用方决定怎么呈现；这里只保证日志里有一条）。
+    fn fail(&self, reason: String) -> String {
+        self.journal.line(&format!("失败：{reason}"));
+        reason
+    }
+}
+
+/// 跑 Forge / NeoForge 的 installer processors（`Ok(None)` = 这一轮不需要跑）。
+///
+/// # Errors
+///
+/// 元数据缺 profile/installer、依赖库没下全、找不到可用 Java、processor 非零退出、
+/// 产物没落盘、用户取消时返回给 UI 的文案（已写进装日志）。
+pub(super) fn stage(
+    env: &HostEnv,
+    engine: &DownloadEngine,
+    input: &StageInput<'_>,
+    backend: &dyn Backend,
+    reporter: &Reporter<'_>,
+    cancel: &Arc<AtomicBool>,
+) -> Result<Option<ProcessorRun>, String> {
+    if input.installed {
+        reporter.journal.line(&format!(
+            "{} 的版本 JSON 已在盘上，跳过 installer processors",
+            input.version_id
+        ));
+        return Ok(None);
+    }
+    let (Some(profile), Some(installer)) = (input.profile, input.installer) else {
+        return Err(reporter.fail(metadata_missing(input)));
+    };
+    reporter.stage(InstallStage::Installing, "正在组 installer 处理器计划…");
+    let scratch = env
+        .layout
+        .cache()
+        .join("processors")
+        .join(safe_name(input.version_id));
+    let plan = ProcessorPlan::build(ProcessorPlanInput {
+        kind: input.kind,
+        mc_version: input.mc_version,
+        version_id: input.version_id,
+        profile,
+        layout: &env.game,
+        installer,
+        scratch: &scratch,
+        environment: &Environment::host(),
+    })
+    .map_err(|error| reporter.fail(diagnostic(&error)))?;
+    for warning in &plan.warnings {
+        reporter.journal.line(&format!("规划告警：{warning}"));
+    }
+    if plan.is_empty() {
+        reporter
+            .journal
+            .line("install profile 没有 client 侧 processor，跳过这一段");
+        return Ok(None);
+    }
+
+    let total = plan.step_count();
+    let bytes = plan.libraries.iter().filter_map(|file| file.size).sum();
+    reporter.expect(plan.libraries.len(), bytes);
+    reporter.stage(
+        InstallStage::Downloading,
+        &format!("下载 installer 依赖库（{} 个文件）…", plan.libraries.len()),
+    );
+    if cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+    let sink = sink_for(reporter.tx.clone(), Arc::clone(reporter.meter));
+    let libraries = backend.download_libraries(engine, &plan.libraries, Some(sink));
+    if !libraries.is_complete() {
+        return Err(reporter.fail(libraries_failed(&libraries)));
+    }
+
+    let managed = env.layout.java_managed();
+    let Some(java) = backend.select_java(&managed, &plan.java_requirement) else {
+        return Err(reporter.fail(java_missing(&plan.java_requirement, &managed)));
+    };
+    reporter.journal.line(&format!(
+        "用 {}（{}）跑 {total} 步 processor",
+        java.binary.display(),
+        java_label(&java)
+    ));
+    reporter.stage(
+        InstallStage::Installing,
+        &format!("运行 installer 处理器 0/{total}（{}）…", java_label(&java)),
+    );
+    if cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+
+    let steps = step_sink(
+        reporter.tx.clone(),
+        Arc::clone(reporter.meter),
+        reporter.journal.clone(),
+        total,
+    );
+    let run = backend
+        .run(&plan, &java, Some(steps))
+        .map_err(|error| reporter.fail(diagnostic(&error)))?;
+    for warning in &run.warnings {
+        reporter.journal.line(&format!("执行告警：{warning}"));
+    }
+    reporter.journal.line(&format!(
+        "processors 完成：执行 {} 步、跳过 {} 步",
+        run.executed(),
+        run.skipped()
+    ));
+    reporter.stage(
+        InstallStage::Installing,
+        &format!(
+            "installer 处理器完成（执行 {} 步、跳过 {} 步），正在写入版本清单…",
+            run.executed(),
+            run.skipped()
+        ),
+    );
+    if cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+    Ok(Some(run))
+}
+
+/// 每步完成的回调：面板一行 + 装日志一行。
+///
+/// `StepSink` 要求 `'static`，所以这里全持所有权（通道/记账器/日志都是克隆）。
+fn step_sink(tx: JobSender, meter: Arc<Mutex<Meter>>, journal: Journal, total: usize) -> StepSink {
+    Arc::new(move |outcome: &StepOutcome| {
+        let line = step_line(outcome, total);
+        journal.line(&line);
+        let Ok(mut guard) = meter.lock() else {
+            return;
+        };
+        guard.stage(InstallStage::Installing, &line);
+        let _ = tx.send(HostTask::Install {
+            progress: Box::new(guard.progress.clone()),
+            epoch: guard.epoch,
+        });
+    })
+}
+
+/// 一步的进度/日志文案（纯函数，单测直接断言）。
+pub(super) fn step_line(outcome: &StepOutcome, total: usize) -> String {
+    let suffix = match outcome.status {
+        StepStatus::Skipped => "（产物已就绪，跳过）".to_string(),
+        StepStatus::Executed => format!("（{} ms）", outcome.elapsed_ms),
+    };
+    format!(
+        "installer 处理器 {}/{}：{}{suffix}",
+        outcome.index, total, outcome.label
+    )
+}
+
+/// processor 错误 → 用户可读文案（保留 `processor_*` 大类码，便于按码搜日志）。
+pub(super) fn diagnostic(error: &ProcessorError) -> String {
+    let mut text = format!("{}（{}）", error.message(), error.kind().as_str());
+    if let Some(hint) = error.hint() {
+        text.push_str("；建议：");
+        text.push_str(hint);
+    }
+    text
+}
+
+/// 缺 Java 运行时的专用文案（比通用错误多给一条「去哪装」）。
+pub(super) fn java_missing(requirement: &JavaRequirement, managed: &Path) -> String {
+    format!(
+        "跑 installer 需要 {}，但一个可用的 Java 运行时都没找到；请到「Java」页安装托管 JDK，或把 JAVA_HOME 指向可用的 JDK（托管目录 {}）",
+        requirement.describe(),
+        managed.display()
+    )
+}
+
+/// 依赖库没下全 → 列前三条失败明细。
+pub(super) fn libraries_failed(report: &InstallReport) -> String {
+    let details: Vec<String> = report
+        .failures(3)
+        .iter()
+        .filter_map(|outcome| {
+            outcome
+                .failure
+                .as_ref()
+                .map(|failure| format!("{}：{}", outcome.name, failure.message))
+        })
+        .collect();
+    format!(
+        "installer 依赖库没下全（{} 个失败，共 {} 个）：{}",
+        report.failed(),
+        report.files.len(),
+        details.join("；")
+    )
+}
+
+/// 需要 installer 但元数据不全（缓存半截 / 换线路重解析过）。
+fn metadata_missing(input: &StageInput<'_>) -> String {
+    format!(
+        "{} {} 需要跑 installer processors，但没拿到 install profile / installer 路径；重跑一次即可（元数据缓存可能不完整）",
+        input.kind.label(),
+        input.version_id
+    )
+}
+
+/// Java 的一行短标识（`Java 21 · managed`）。
+fn java_label(java: &JavaRuntime) -> String {
+    match java.major {
+        Some(major) => format!("Java {major} · {}", java.origin.as_str()),
+        None => format!("Java 主版本未知 · {}", java.origin.as_str()),
+    }
+}
+
+/// 版本 id → 可做目录名的片段（`+` 与路径分隔符都换掉，与 CLI 同规则）。
+fn safe_name(raw: &str) -> String {
+    raw.chars()
+        .map(|ch| {
+            if ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_') {
+                ch
+            } else {
+                '_'
+            }
+        })
+        .collect::<String>()
+        .trim_end_matches('.')
+        .to_string()
+}
+
+#[cfg(test)]
+#[path = "install_processors_fixture.rs"]
+mod fixture;
+
+#[cfg(test)]
+#[path = "install_processors_tests.rs"]
+mod tests;

crates/presenter/src/host/install_processors_fixture.rs

@@ -0,0 +1,272 @@
+//! installer processors 段的单测夹具（拆文件守 400 行上限）。
+//!
+//! 不需要网络、不需要 JDK、不真的起 java：`Harness` 给一个临时数据根 + 进度通道，
+//! `Fake` 回放预置的下载/Java/执行结果并记录被调顺序与组出来的命令行。
+
+use std::cell::RefCell;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::mpsc::Receiver;
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::addon::loader::forge::{InstallProfile, Processor};
+use unlucky_core::addon::loader::processors::{
+    ProcessorError, ProcessorPlan, ProcessorRun, StepOutcome, StepSink, StepStatus,
+};
+use unlucky_core::addon::loader::LoaderKind as CoreLoaderKind;
+use unlucky_core::download::{DownloadEngine, DownloadErrorKind};
+use unlucky_core::game::install::{
+    FileFailure, FileOutcome, FileStatus, InstallReport, PlanFile, ProgressSink,
+};
+use unlucky_core::game::java::{JavaOrigin, JavaRequirement, JavaRuntime};
+
+use super::{Backend, Reporter, StageInput};
+use crate::dto::{CreateRequest, LoaderKind};
+use crate::host::env::HostEnv;
+use crate::host::install_journal::Journal;
+use crate::host::job::{channel, HostTask, JobSender};
+use crate::host::meter::Meter;
+
+static SEQ: AtomicUsize = AtomicUsize::new(0);
+
+/// 一步的计划视图（序号 / 坐标 / 参数 / classpath 条数）。
+pub(super) type StepView = (usize, String, Vec<String>, usize);
+
+/// 一段 cases 的公共环境：临时数据根 + 引擎 + 进度通道。
+pub(super) struct Harness {
+    dir: PathBuf,
+    pub(super) env: HostEnv,
+    pub(super) engine: DownloadEngine,
+    tx: JobSender,
+    rx: Receiver<HostTask>,
+    pub(super) meter: Arc<Mutex<Meter>>,
+    pub(super) journal: Journal,
+    pub(super) cancel: Arc<AtomicBool>,
+}
+
+impl Harness {
+    pub(super) fn new() -> Self {
+        let seq = SEQ.fetch_add(1, Ordering::SeqCst);
+        let dir = std::env::temp_dir().join(format!("ull-proc-{}-{seq}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        let engine = crate::host::engine::engine(&env);
+        let request = CreateRequest {
+            version: "1.20.1".to_string(),
+            loader: LoaderKind::Forge,
+            loader_version: "47.2.0".to_string(),
+            name: "proc".to_string(),
+        };
+        let (tx, rx) = channel();
+        Self {
+            journal: Journal::open(&env),
+            meter: Arc::new(Mutex::new(Meter::new(&request, 1))),
+            cancel: Arc::new(AtomicBool::new(false)),
+            dir,
+            env,
+            engine,
+            tx,
+            rx,
+        }
+    }
+
+    pub(super) fn reporter(&self) -> Reporter<'_> {
+        Reporter {
+            tx: &self.tx,
+            meter: &self.meter,
+            journal: &self.journal,
+        }
+    }
+
+    /// 进度面板收到的所有文案。
+    pub(super) fn messages(&self) -> Vec<String> {
+        self.rx
+            .try_iter()
+            .filter_map(|task| match task {
+                HostTask::Install { progress, .. } => Some(progress.message.clone()),
+                _ => None,
+            })
+            .collect()
+    }
+
+    /// 装日志全文。
+    pub(super) fn log(&self) -> String {
+        std::fs::read_to_string(self.journal.path()).unwrap_or_default()
+    }
+}
+
+impl Drop for Harness {
+    fn drop(&mut self) {
+        std::fs::remove_dir_all(&self.dir).ok();
+    }
+}
+
+/// 注入用的假后端：回放预置结果 + 记录调用顺序与被组出来的命令行。
+pub(super) struct Fake {
+    pub(super) libraries_ok: bool,
+    pub(super) java: Option<JavaRuntime>,
+    pub(super) run_error: Option<ProcessorError>,
+    calls: RefCell<Vec<&'static str>>,
+    steps: RefCell<Vec<StepView>>,
+}
+
+impl Fake {
+    pub(super) fn new() -> Self {
+        Self {
+            libraries_ok: true,
+            java: Some(java()),
+            run_error: None,
+            calls: RefCell::new(Vec::new()),
+            steps: RefCell::new(Vec::new()),
+        }
+    }
+
+    pub(super) fn calls(&self) -> Vec<&'static str> {
+        self.calls.borrow().clone()
+    }
+
+    /// 被组出来的每步（序号 / 坐标 / 参数 / classpath 条数）。
+    pub(super) fn steps(&self) -> Vec<StepView> {
+        self.steps.borrow().clone()
+    }
+}
+
+impl Backend for Fake {
+    fn download_libraries(
+        &self,
+        _engine: &DownloadEngine,
+        files: &[PlanFile],
+        _sink: Option<ProgressSink>,
+    ) -> InstallReport {
+        self.calls.borrow_mut().push("libraries");
+        let ok = self.libraries_ok;
+        let outcomes = files
+            .iter()
+            .map(|file| FileOutcome {
+                role: file.role,
+                name: file.name.clone(),
+                dest: file.dest.clone(),
+                status: if ok {
+                    FileStatus::Skipped
+                } else {
+                    FileStatus::Failed
+                },
+                bytes: 0,
+                source: None,
+                failure: (!ok).then(|| FileFailure {
+                    kind: DownloadErrorKind::Network,
+                    message: "连接超时".to_string(),
+                }),
+            })
+            .collect();
+        InstallReport {
+            files: outcomes,
+            version_json: None,
+            warnings: Vec::new(),
+        }
+    }
+
+    fn select_java(&self, _managed: &Path, _requirement: &JavaRequirement) -> Option<JavaRuntime> {
+        self.calls.borrow_mut().push("java");
+        self.java.clone()
+    }
+
+    fn run(
+        &self,
+        plan: &ProcessorPlan,
+        java: &JavaRuntime,
+        sink: Option<StepSink>,
+    ) -> Result<ProcessorRun, ProcessorError> {
+        self.calls.borrow_mut().push("run");
+        *self.steps.borrow_mut() = plan
+            .steps
+            .iter()
+            .map(|step| {
+                (
+                    step.index,
+                    step.label.clone(),
+                    step.args.clone(),
+                    step.classpath.len(),
+                )
+            })
+            .collect();
+        if let Some(error) = &self.run_error {
+            return Err(error.clone());
+        }
+        let outcomes: Vec<StepOutcome> = plan
+            .steps
+            .iter()
+            .map(|step| StepOutcome {
+                index: step.index,
+                label: step.label.clone(),
+                status: StepStatus::Executed,
+                outputs: step.outputs.len(),
+                elapsed_ms: 12,
+                stdout_tail: None,
+                stderr_tail: None,
+            })
+            .collect();
+        if let Some(sink) = &sink {
+            for outcome in &outcomes {
+                sink(outcome);
+            }
+        }
+        Ok(ProcessorRun {
+            java: java.clone(),
+            steps: outcomes,
+            warnings: Vec::new(),
+        })
+    }
+}
+
+/// 一个主版本已知的假 Java。
+pub(super) fn java() -> JavaRuntime {
+    JavaRuntime {
+        binary: PathBuf::from("java"),
+        origin: JavaOrigin::Managed,
+        version: Some("21.0.4".to_string()),
+        major: Some(21),
+        bits: 64,
+        vendor: Some("temurin".to_string()),
+    }
+}
+
+/// 一个最小可用的 install profile：一个 client 侧 processor、两个字面量参数。
+pub(super) fn profile() -> InstallProfile {
+    let mut profile = InstallProfile::default();
+    profile.processors.push(Processor {
+        sides: vec!["client".to_string()],
+        jar: Some("net.minecraftforge:installertools:1.3.0".to_string()),
+        classpath: vec!["net.minecraftforge:jarsplitter:1.1.4".to_string()],
+        args: vec!["--task".to_string(), "'MCP_DATA'".to_string()],
+        ..Processor::default()
+    });
+    profile
+}
+
+pub(super) fn input<'a>(profile: &'a InstallProfile, installer: &'a Path) -> StageInput<'a> {
+    StageInput {
+        kind: CoreLoaderKind::Forge,
+        mc_version: "1.20.1",
+        version_id: "1.20.1-forge-47.2.0",
+        profile: Some(profile),
+        installer: Some(installer),
+        installed: false,
+    }
+}
+
+pub(super) fn installer() -> PathBuf {
+    PathBuf::from("cache/meta/forge-installer.jar")
+}
+
+pub(super) fn outcome(status: StepStatus) -> StepOutcome {
+    StepOutcome {
+        index: 3,
+        label: "net.minecraftforge:installertools:1.3.0".to_string(),
+        status,
+        outputs: 2,
+        elapsed_ms: 1234,
+        stdout_tail: None,
+        stderr_tail: None,
+    }
+}

crates/presenter/src/host/install_processors_tests.rs

@@ -0,0 +1,213 @@
+//! host/install_processors.rs 的单测（拆文件守 400 行上限）。
+//!
+//! 夹具在 [`super::fixture`]：这里只断言「计划怎么组」「找不到 Java 怎么说」
+//! 「哪一步挂了怎么报」「进度文案长什么样」。
+
+use std::path::PathBuf;
+
+use unlucky_core::addon::loader::forge::InstallProfile;
+use unlucky_core::addon::loader::processors::{ProcessorError, StepStatus};
+use unlucky_core::addon::loader::LoaderKind as CoreLoaderKind;
+use unlucky_core::download::DownloadErrorKind;
+use unlucky_core::game::install::{FileFailure, FileOutcome, FileRole, FileStatus, InstallReport};
+use unlucky_core::game::java::JavaRequirement;
+
+use super::fixture::{input, installer, outcome, profile, Fake, Harness};
+use super::{diagnostic, java_missing, libraries_failed, stage, step_line, StageInput};
+
+#[test]
+fn step_line_names_the_step_and_marks_the_outcome() {
+    let executed = step_line(&outcome(StepStatus::Executed), 9);
+    assert_eq!(
+        executed,
+        "installer 处理器 3/9：net.minecraftforge:installertools:1.3.0（1234 ms）"
+    );
+    let skipped = step_line(&outcome(StepStatus::Skipped), 9);
+    assert!(skipped.contains("产物已就绪"), "{skipped}");
+}
+
+#[test]
+fn diagnostic_keeps_the_stable_code_and_the_hint() {
+    let failed = ProcessorError::failed("net.minecraftforge:installertools:1.3.0", "1", "boom")
+        .with_hint("确认 Java 版本与磁盘权限");
+    let text = diagnostic(&failed);
+    assert!(text.contains("processor_failed"), "{text}");
+    assert!(text.contains("退出码 1"), "{text}");
+    assert!(text.contains("boom"), "stderr 尾部要留：{text}");
+    assert!(text.contains("建议：确认 Java 版本"), "{text}");
+
+    let plan = diagnostic(&ProcessorError::plan("install profile 缺 `jar`"));
+    assert!(plan.contains("processor_plan"), "{plan}");
+}
+
+#[test]
+fn java_missing_points_at_the_java_page() {
+    let managed = PathBuf::from("/tmp/.ULL/java");
+    let text = java_missing(&JavaRequirement::table(21, None), &managed);
+    assert!(text.contains("Java 21+"), "{text}");
+    assert!(text.contains("Java」页"), "{text}");
+    assert!(text.contains("JAVA_HOME"), "{text}");
+    assert!(text.contains(&managed.display().to_string()), "{text}");
+}
+
+#[test]
+fn libraries_failed_lists_at_most_three() {
+    let files: Vec<FileOutcome> = (0..4)
+        .map(|index| FileOutcome {
+            role: FileRole::Library,
+            name: format!("lib{index}.jar"),
+            dest: PathBuf::from(format!("lib{index}.jar")),
+            status: FileStatus::Failed,
+            bytes: 0,
+            source: None,
+            failure: Some(FileFailure {
+                kind: DownloadErrorKind::Network,
+                message: "连接超时".to_string(),
+            }),
+        })
+        .collect();
+    let report = InstallReport {
+        files,
+        version_json: None,
+        warnings: Vec::new(),
+    };
+    let text = libraries_failed(&report);
+    assert!(text.contains("4 个失败，共 4 个"), "{text}");
+    assert!(text.contains("lib0.jar"), "{text}");
+    assert!(!text.contains("lib3.jar"), "最多列三条：{text}");
+}
+
+#[test]
+fn stage_skips_when_the_version_json_is_already_there() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let mut input = input(&profile, &installer);
+    input.installed = true;
+    let fake = Fake::new();
+    let result = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel);
+    assert!(matches!(result, Ok(None)));
+    assert!(fake.calls().is_empty(), "已装完就不该再动网络/Java");
+    assert!(h.log().contains("跳过 installer processors"), "{}", h.log());
+}
+
+#[test]
+fn stage_skips_an_empty_processor_list() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = InstallProfile::default();
+    let input = input(&profile, &installer);
+    let fake = Fake::new();
+    let result = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel);
+    assert!(matches!(result, Ok(None)), "没有 processor 就没这段");
+    assert!(fake.calls().is_empty());
+}
+
+#[test]
+fn stage_reports_missing_installer_metadata() {
+    let h = Harness::new();
+    let input = StageInput {
+        kind: CoreLoaderKind::Forge,
+        mc_version: "1.20.1",
+        version_id: "1.20.1-forge-47.2.0",
+        profile: None,
+        installer: None,
+        installed: false,
+    };
+    let fake = Fake::new();
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("install profile"), "{err}");
+    assert!(h.log().contains("失败："), "{}", h.log());
+}
+
+#[test]
+fn stage_builds_the_command_line_from_the_install_profile() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let fake = Fake::new();
+    let run = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel)
+        .expect("stage 成功")
+        .expect("应当真的跑了 processors");
+    assert_eq!(run.executed(), 1);
+    let steps = fake.steps();
+    assert_eq!(steps.len(), 1);
+    let (index, label, args, classpath) = &steps[0];
+    assert_eq!(*index, 1);
+    assert_eq!(label, "net.minecraftforge:installertools:1.3.0");
+    assert_eq!(args, &vec!["--task".to_string(), "MCP_DATA".to_string()]);
+    assert_eq!(*classpath, 1, "jar 自己不在 -cp 里（拼命令行时才补）");
+    assert_eq!(fake.calls(), vec!["libraries", "java", "run"]);
+    let messages = h.messages();
+    assert!(
+        messages.iter().any(|m| m.contains("installer 处理器 1/1")),
+        "面板要看到当前处理器：{messages:?}"
+    );
+    assert!(
+        messages
+            .last()
+            .is_some_and(|m| m.contains("正在写入版本清单")),
+        "{messages:?}"
+    );
+    assert!(
+        h.log().contains("processors 完成：执行 1 步"),
+        "{}",
+        h.log()
+    );
+}
+
+#[test]
+fn stage_fails_loudly_without_a_usable_java() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let mut fake = Fake::new();
+    fake.java = None;
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("Java"), "{err}");
+    assert!(err.contains("托管目录"), "{err}");
+    assert_eq!(
+        fake.calls(),
+        vec!["libraries", "java"],
+        "没 Java 就不该起进程"
+    );
+    assert!(h.log().contains("失败："), "{}", h.log());
+}
+
+#[test]
+fn stage_fails_loudly_when_a_processor_exits_nonzero() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let mut fake = Fake::new();
+    fake.run_error = Some(ProcessorError::failed(
+        "net.minecraftforge:installertools:1.3.0",
+        "1",
+        "java.lang.NoSuchMethodError",
+    ));
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("processor_failed"), "{err}");
+    assert!(err.contains("NoSuchMethodError"), "{err}");
+    let log = h.log();
+    assert!(log.contains("失败："), "{log}");
+    assert!(log.contains("NoSuchMethodError"), "日志要能回溯：{log}");
+}
+
+#[test]
+fn stage_reports_incomplete_library_downloads() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let mut fake = Fake::new();
+    fake.libraries_ok = false;
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("依赖库没下全"), "{err}");
+    assert!(err.contains("连接超时"), "{err}");
+    assert_eq!(fake.calls(), vec!["libraries"], "库没下全就别去选 Java");
+    let progress = h.meter.lock().expect("进度锁").progress.clone();
+    assert!(progress.files_total >= 2, "依赖库要计入文件总数");
+}

crates/presenter/src/host/install_tests.rs

@@ -0,0 +1,218 @@
+//! host/install.rs 的单测（拆文件守 400 行上限）。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::game::install::{FileOutcome, FileRole, FileStatus};
+
+use super::{loader_label, run, supported, unsupported_reason, Job};
+use crate::dto::{CreateRequest, LoaderKind};
+use crate::host::env::HostEnv;
+use crate::host::install_journal::Journal;
+use crate::host::job::{channel, JobSender};
+use crate::host::meter::Meter;
+
+static SEQ: AtomicUsize = AtomicUsize::new(0);
+
+/// 一个装在临时根里的任务上下文（只走「联网前就返回」的用例）。
+struct Fixture {
+    dir: PathBuf,
+    env: HostEnv,
+    tx: JobSender,
+    meter: Arc<Mutex<Meter>>,
+    cancel: Arc<AtomicBool>,
+    journal: Journal,
+}
+
+impl Fixture {
+    fn new(request: &CreateRequest) -> Self {
+        let seq = SEQ.fetch_add(1, Ordering::SeqCst);
+        let dir =
+            std::env::temp_dir().join(format!("ull-host-install-{}-{seq}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        let journal = Journal::open(&env);
+        Self {
+            dir,
+            env,
+            tx: channel().0,
+            meter: Arc::new(Mutex::new(Meter::new(request, 1))),
+            cancel: Arc::new(AtomicBool::new(false)),
+            journal,
+        }
+    }
+
+    fn job(&self) -> Job<'_> {
+        Job {
+            env: &self.env,
+            tx: &self.tx,
+            meter: &self.meter,
+            cancel: &self.cancel,
+            journal: &self.journal,
+        }
+    }
+}
+
+impl Drop for Fixture {
+    fn drop(&mut self) {
+        std::fs::remove_dir_all(&self.dir).ok();
+    }
+}
+
+fn request(loader: LoaderKind, version: &str) -> CreateRequest {
+    CreateRequest {
+        version: version.to_string(),
+        loader,
+        loader_version: String::new(),
+        name: String::new(),
+    }
+}
+
+/// 一个「刚下完」的文件结局（记账用）。
+fn downloaded(bytes: u64) -> FileOutcome {
+    FileOutcome {
+        role: FileRole::Library,
+        name: "lib.jar".to_string(),
+        dest: PathBuf::from("lib.jar"),
+        status: FileStatus::Downloaded,
+        bytes,
+        source: None,
+        failure: None,
+    }
+}
+
+#[test]
+fn progress_is_pre_accounted_across_segments_so_the_bar_never_snaps_to_full() {
+    // M45 r1 P2-2 的回归：处理器依赖库下完那一刻，面板曾显示 36/36 满格 + 3.4MB/10MB，
+    // 之后加载器库的 29 个文件才被计入 → 进度条从 100% 回落到 55% 再涨回去。
+    let request = request(LoaderKind::Forge, "1.20.1");
+    let mut meter = Meter::new(&request, 1);
+
+    // 原版段：30 个文件全下完（install_vanilla 对总量是赋值，不是累加）
+    meter.progress.files_total = 30;
+    meter.progress.bytes_total = 3_000_000;
+    for _ in 0..30 {
+        meter.note(&downloaded(100_000));
+    }
+    assert!((meter.progress.ratio() - 1.0).abs() < f32::EPSILON);
+
+    // install_loader 的顺序：加载器库与处理器依赖库都在动手前一次预记账
+    meter.expect(29, 10_000_000);
+    meter.expect(36, 4_000_000);
+    assert_eq!(meter.progress.files_total, 95, "两段之和一次到位");
+    assert_eq!(
+        meter.progress.bytes_total, 17_000_000,
+        "字节是相加不是取最大"
+    );
+    assert!(
+        meter.progress.ratio() < 0.7,
+        "预记账后不能还停在满格：{}",
+        meter.progress.ratio()
+    );
+
+    // 处理器依赖库 36 个下完 → 仍没满格（加载器库还在后面）
+    for _ in 0..36 {
+        meter.note(&downloaded(110_000));
+    }
+    let ratio = meter.progress.ratio();
+    assert!(
+        (0.6..1.0).contains(&ratio),
+        "回落到中间态而不是满格：{ratio}"
+    );
+    assert!(
+        meter.progress.bytes_done < meter.progress.bytes_total,
+        "字节总量要覆盖已下载量：{}/{}",
+        meter.progress.bytes_done,
+        meter.progress.bytes_total
+    );
+
+    // 加载器库也下完 → 这时候才该是满格
+    for _ in 0..29 {
+        meter.note(&downloaded(340_000));
+    }
+    assert!((meter.progress.ratio() - 1.0).abs() < f32::EPSILON);
+}
+
+#[test]
+fn loader_support_matrix_is_explicit() {
+    // M45 语义变更：Forge/NeoForge 从「GUI 显式拒装」扩进受支持集合（走 installer processors）。
+    for kind in [
+        LoaderKind::Vanilla,
+        LoaderKind::Fabric,
+        LoaderKind::Quilt,
+        LoaderKind::Forge,
+        LoaderKind::NeoForge,
+    ] {
+        assert!(supported(kind), "{} 应当受支持", kind.label());
+    }
+    // 这两家 core 侧还没有安装管线，仍然显式拒装并说清去哪装。
+    for kind in [LoaderKind::OptiFine, LoaderKind::LiteLoader] {
+        assert!(!supported(kind), "{} 不该被当成可装", kind.label());
+        let reason = unsupported_reason(kind);
+        assert!(reason.contains(kind.label()), "{reason}");
+        assert!(reason.contains("还没有接入"), "{reason}");
+    }
+}
+
+#[test]
+fn forge_install_is_no_longer_refused_at_the_door() {
+    // 旧文案是把用户赶去终端跑 `ull install`；M45 之后 GUI 与 CLI 同一条路径。
+    assert!(supported(LoaderKind::Forge));
+    assert!(supported(LoaderKind::NeoForge));
+    assert_eq!(loader_label(LoaderKind::Forge, "47.2.0"), "Forge 47.2.0");
+    assert_eq!(
+        loader_label(LoaderKind::NeoForge, "21.1.80"),
+        "NeoForge 21.1.80"
+    );
+}
+
+#[test]
+fn meter_counts_files_and_skips_skipped_bytes() {
+    let request = CreateRequest {
+        version: "1.20.4".to_string(),
+        loader: LoaderKind::Fabric,
+        loader_version: "0.16.5".to_string(),
+        name: "生存".to_string(),
+    };
+    let mut meter = Meter::new(&request, 1);
+    assert_eq!(meter.progress.loader, "Fabric 0.16.5");
+    assert_eq!(meter.progress.instance, "生存");
+    meter.progress.files_total = 2;
+
+    let mut outcome = FileOutcome {
+        role: FileRole::Library,
+        name: "a.jar".to_string(),
+        dest: PathBuf::from("a.jar"),
+        status: FileStatus::Downloaded,
+        bytes: 100,
+        source: Some("bmclapi".to_string()),
+        failure: None,
+    };
+    meter.note(&outcome);
+    assert_eq!(meter.progress.files_done, 1);
+    assert_eq!(meter.progress.bytes_done, 100);
+
+    outcome.status = FileStatus::Skipped;
+    outcome.bytes = 500;
+    meter.note(&outcome);
+    assert_eq!(meter.progress.files_done, 2);
+    assert_eq!(meter.progress.bytes_done, 100, "跳过的文件不计入已下载字节");
+    assert!((meter.progress.ratio() - 1.0).abs() < f32::EPSILON);
+}
+
+#[test]
+fn empty_version_is_rejected_before_network() {
+    let request = request(LoaderKind::Vanilla, "");
+    let fixture = Fixture::new(&request);
+    let err = run(&fixture.job(), &request).unwrap_err();
+    assert!(err.contains("没有选择版本"), "{err}");
+}
+
+#[test]
+fn unsupported_loader_is_rejected_before_network() {
+    let request = request(LoaderKind::OptiFine, "1.20.1");
+    let fixture = Fixture::new(&request);
+    let err = run(&fixture.job(), &request).unwrap_err();
+    assert!(err.contains("还没有接入"), "{err}");
+}

crates/presenter/src/host/java.rs

@@ -0,0 +1,304 @@
+//! Java 页：四家发行版 + 回退链可视化 + 本地运行时 + 托管 JDK 安装。
+//!
+//! 回退链的两态：
+//! - **计划链**（还没装）：按生效顺序铺一排「待尝试」，让用户先看清会按什么顺序找；
+//! - **真实链**（装过一次/装失败）：`core::game::java::ChainLog` 的每跳结局与原因。
+//!
+//! 安装走 `java::install`（core 自己跑回退链），host 只负责把 `ChainLog` 翻成 DTO。
+
+use unlucky_core::game::java::probe::JavaOrigin;
+use unlucky_core::game::java::source::ChainLog;
+use unlucky_core::game::java::{self, JdkVendor};
+
+use crate::dto::{JavaChainOutcome, JavaChainStep, JavaPageView, JavaRuntimeView, JavaVendorView};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 托管 JDK 的默认目标大版本（D13 基准 JDK17）。
+pub const DEFAULT_JDK_MAJOR: u32 = 17;
+
+/// 该装哪个大版本：取第一个实例版本的要求，没有实例就给 17。
+pub fn target_major(env: &HostEnv) -> u32 {
+    let profiles = super::game::profiles(env);
+    profiles
+        .profiles
+        .first()
+        .map(|profile| {
+            java::requirement_for_version(&env.game, &profile.version_id)
+                .minimum
+                .max(8)
+        })
+        .unwrap_or(DEFAULT_JDK_MAJOR)
+}
+
+/// 四家发行版的展示行（镜像与吞吐口径与 CLI `ull java vendors` 一致）。
+pub fn vendors(env: &HostEnv, installed_vendors: &[String]) -> Vec<JavaVendorView> {
+    let domestic = super::engine::domestic(env);
+    let order = java::vendor::order(&super::engine::java_priority(env), domestic);
+    let table = unlucky_core::download::MirrorTable::builtin();
+    order
+        .iter()
+        .enumerate()
+        .map(|(index, vendor)| {
+            let id = vendor.id();
+            JavaVendorView {
+                id: id.to_string(),
+                display: vendor.display().to_string(),
+                rank: u32::try_from(index + 1).unwrap_or(u32::MAX),
+                majors: vendor
+                    .hint_majors()
+                    .iter()
+                    .map(u32::to_string)
+                    .collect::<Vec<_>>()
+                    .join("/"),
+                sources: sources_of(&table, *vendor),
+                installed: installed_vendors.iter().any(|known| known == id),
+            }
+        })
+        .collect()
+}
+
+/// 一家的源清单（与 CLI 展示同形）。
+fn sources_of(table: &unlucky_core::download::MirrorTable, vendor: JdkVendor) -> Vec<String> {
+    match vendor {
+        JdkVendor::Temurin => table
+            .adoptium
+            .iter()
+            .filter(|mirror| mirror.enabled)
+            .map(|mirror| mirror.name.clone())
+            .chain(std::iter::once(
+                "GitHub 官方（国内套 gh-proxy）".to_string(),
+            ))
+            .collect(),
+        JdkVendor::Oracle => table
+            .oracle_mirrors()
+            .map(|mirror| format!("{} {}", mirror.name, mirror.base()))
+            .collect(),
+        JdkVendor::Microsoft => vec!["aka.ms → VS CDN（无国内镜像）".to_string()],
+        JdkVendor::Zulu => table
+            .zulu()
+            .map(|zulu| vec![format!("{}（{}）", zulu.api, zulu.measured_speed)])
+            .unwrap_or_default(),
+    }
+}
+
+/// 本地运行时（托管 / JAVA_HOME / PATH / 系统安装位置，同一路径只留优先级高者）。
+pub fn runtimes(env: &HostEnv) -> Vec<JavaRuntimeView> {
+    let roots = super::engine::java_scan_roots(env);
+    let candidates = java::discover::dedupe(java::candidates_in_roots(&roots));
+    candidates
+        .iter()
+        .map(|runtime| JavaRuntimeView {
+            binary: runtime.binary.display().to_string(),
+            version: runtime
+                .version
+                .clone()
+                .unwrap_or_else(|| "版本未知".to_string()),
+            major: runtime.major.unwrap_or(java::DEFAULT_MAJOR),
+            vendor: runtime.vendor.clone().unwrap_or_else(|| "—".to_string()),
+            origin: runtime.origin.category().to_string(),
+        })
+        .collect()
+}
+
+/// 托管目录（展示「装到哪」）。
+pub fn managed_roots(env: &HostEnv) -> Vec<String> {
+    super::engine::java_scan_roots(env)
+        .iter()
+        .map(|root| root.display().to_string())
+        .collect()
+}
+
+/// 计划链（按生效顺序铺「待尝试」）。
+pub fn planned_chain(env: &HostEnv) -> Vec<JavaChainStep> {
+    let domestic = super::engine::domestic(env);
+    let order = java::vendor::order(&super::engine::java_priority(env), domestic);
+    order
+        .iter()
+        .map(|vendor| JavaChainStep {
+            vendor: vendor.id().to_string(),
+            outcome: JavaChainOutcome::Pending,
+            detail: String::new(),
+        })
+        .collect()
+}
+
+/// 真实链（`ChainLog` → DTO）。
+pub fn chain_steps(log: &ChainLog) -> Vec<JavaChainStep> {
+    log.attempts()
+        .iter()
+        .map(|attempt| JavaChainStep {
+            vendor: attempt.vendor.id().to_string(),
+            outcome: if attempt.ok {
+                JavaChainOutcome::Hit
+            } else if attempt.detail.contains("不支持") {
+                JavaChainOutcome::Skip
+            } else {
+                JavaChainOutcome::Failed
+            },
+            detail: attempt.detail.clone(),
+        })
+        .collect()
+}
+
+/// 整页快照。
+pub fn page(env: &HostEnv, chain: Vec<JavaChainStep>, busy: bool, message: &str) -> JavaPageView {
+    let runtimes = runtimes(env);
+    let installed_vendors: Vec<String> = runtimes
+        .iter()
+        .filter(|runtime| runtime.origin == JavaOrigin::Managed.category())
+        .map(|runtime| runtime.vendor.clone())
+        .collect();
+    let vendor_rows = vendors(env, &installed_vendors);
+    let domestic = super::engine::domestic(env);
+    let priority_set = !super::engine::java_priority(env).is_empty();
+    let chain = if chain.is_empty() {
+        planned_chain(env)
+    } else {
+        chain
+    };
+    JavaPageView {
+        region: if domestic { "domestic" } else { "global" }.to_string(),
+        priority_source: if priority_set {
+            "java.vendorPriority"
+        } else {
+            "region_default"
+        }
+        .to_string(),
+        order_text: vendor_rows
+            .iter()
+            .map(|vendor| vendor.display.clone())
+            .collect::<Vec<_>>()
+            .join(" → "),
+        vendors: vendor_rows,
+        chain,
+        runtimes,
+        managed_roots: managed_roots(env),
+        busy,
+        message: message.to_string(),
+    }
+}
+
+/// 后台装一个托管 JDK（`vendor` 为空 = 按回退链自己选）。
+pub fn spawn_install(env: HostEnv, tx: JobSender, vendor: Option<JdkVendor>) {
+    spawn("java-install", move || {
+        let major = target_major(&env);
+        let mut busy = page(&env, Vec::new(), true, &format!("正在安装 Java {major}…"));
+        busy.busy = true;
+        let _ = tx.send(HostTask::Java(Box::new(busy)));
+
+        let engine = super::engine::engine(&env);
+        let root = match super::engine::java_install_root(&env) {
+            Ok(root) => root,
+            Err(reason) => {
+                let _ = tx.send(HostTask::Java(Box::new(page(
+                    &env,
+                    Vec::new(),
+                    false,
+                    &format!("解析 Java 安装位置失败：{reason}"),
+                ))));
+                return;
+            }
+        };
+        let request = match vendor {
+            Some(vendor) => java::InstallRequest::with_vendor(major, vendor)
+                .with_priority(super::engine::java_priority(&env)),
+            None => {
+                java::InstallRequest::new(major).with_priority(super::engine::java_priority(&env))
+            }
+        };
+        let result =
+            unlucky_core::download::blocking::block_on(java::install(&engine, &root, request));
+        match result {
+            Ok(installed) => {
+                let message = if installed.reused() {
+                    format!(
+                        "Java {}（{}）已就绪：{}",
+                        installed.major,
+                        installed.vendor.id(),
+                        installed.root.display()
+                    )
+                } else {
+                    format!(
+                        "已安装 Java {}（{}）→ {} · {} 个文件",
+                        installed.major,
+                        installed.vendor.display(),
+                        installed.root.display(),
+                        installed.files
+                    )
+                };
+                let chain = chain_steps(&installed.chain);
+                let _ = tx.send(HostTask::Java(Box::new(page(&env, chain, false, &message))));
+            }
+            Err(error) => {
+                let _ = tx.send(HostTask::Java(Box::new(page(
+                    &env,
+                    Vec::new(),
+                    false,
+                    &format!("Java 安装失败：{error}"),
+                ))));
+            }
+        }
+    });
+}
+
+/// 「安装一个 Java」的 UI 文案（下载页 Java 分组的按钮说明）。
+pub fn install_hint(env: &HostEnv) -> String {
+    let major = target_major(env);
+    format!("按回退链取一个 Java {major}（托管目录，装完自动被启动链选中）")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn planned_chain_covers_four_vendors() {
+        let dir = std::env::temp_dir().join(format!("ull-host-java-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config");
+        let chain = planned_chain(&env);
+        assert_eq!(chain.len(), 4);
+        assert!(chain
+            .iter()
+            .all(|step| step.outcome == JavaChainOutcome::Pending));
+        assert_eq!(chain[0].vendor, "temurin", "国内/国外默认都是 Temurin 第一");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn chain_log_maps_to_steps() {
+        let mut log = ChainLog::new();
+        log.skip(
+            JdkVendor::Microsoft,
+            "不支持 Java 8（microsoft 只发 11/17/21/25）",
+        );
+        log.hit(JdkVendor::Temurin, "命中 Adoptium 17");
+        let steps = chain_steps(&log);
+        assert_eq!(steps.len(), 2);
+        assert_eq!(steps[0].outcome, JavaChainOutcome::Skip);
+        assert_eq!(steps[1].outcome, JavaChainOutcome::Hit);
+    }
+
+    #[test]
+    fn page_reports_region_and_priority_source() {
+        let dir = std::env::temp_dir().join(format!("ull-host-java-page-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config");
+        std::fs::write(
+            env.launcher_config(),
+            r#"{"java":{"vendorPriority":["zulu"]}}"#,
+        )
+        .expect("写配置");
+        let page = page(&env, Vec::new(), false, "");
+        assert_eq!(page.priority_source, "java.vendorPriority");
+        assert_eq!(page.vendors[0].id, "zulu");
+        assert_eq!(page.vendors[0].rank, 1);
+        assert!(page.order_text.contains("Azul Zulu"));
+        assert_eq!(page.vendors.len(), 4);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}

crates/presenter/src/host/job.rs

@@ -0,0 +1,198 @@
+//! 后台任务的回流消息：`HostTask` 是唯一「线程 → host」的载荷。
+//!
+//! 线程只做 core 调用（网络/磁盘），产出的都是 `crate::dto` 的 DTO；
+//! host 的 `tick` 把它们翻成 [`crate::dto::CoreEvent`]。
+//! 这样「跨线程传的是什么」在一处看全，也不会出现半成品领域类型漏回 UI。
+
+use std::sync::mpsc::{Receiver, Sender};
+
+use crate::dto::{
+    // 主线（M109 ContentResults / M105 LoaderKind / M113 PackEvent）与 M114 的账户轨并集。
+    AccountView,
+    AuthlibLoginView,
+    ContentResults,
+    DeviceLoginView,
+    DiagnosisReport,
+    InstallProgressView,
+    InstanceId,
+    InstanceRuntime,
+    JavaPageView,
+    LaunchFinished,
+    LiveLogBatch,
+    LoaderKind,
+    LogLine,
+    LogOutcome,
+    LogSession,
+    NoticeView,
+    PackEvent,
+    SessionId,
+    SkinImage,
+    VersionSummary,
+};
+use crate::toast::Toast;
+
+/// 后台任务 → host 的消息。
+#[derive(Debug, Clone, PartialEq)]
+pub enum HostTask {
+    /// 版本清单（下载页）
+    Versions(Result<Vec<VersionSummary>, String>),
+    /// 加载器版本清单（下载页「安装选项」的下拉）
+    LoaderVersions {
+        /// 加载器种类
+        kind: LoaderKind,
+        /// 目标原版版本（缓存键的一部分，回传原样）
+        mc_version: String,
+        /// `Ok(最新在前)` / `Err(人读原因)`
+        result: Result<Vec<String>, String>,
+    },
+    /// 内容库检索（M109；`Err` = 一句人读原因）
+    Content(Box<Result<ContentResults, String>>),
+    // M113: import/export
+    /// 导入/导出（M113）：一条事件 + 任务代次
+    ///
+    /// 代次是 **pack 自己的一条**（`host::addon::pack` 的 `pack_epoch()`，按 host 分开），**不**与
+    /// [`HostTask::Install`] 的 `CoreHost::install_epoch` 共用 —— 共用会让「关一次导入面板」
+    /// 把下载页正在跑的安装静默丢掉（复审 r1 P2-7）。取消/关面板之后回来的旧事件按这条代次
+    /// 丢掉，面板不会被重新点亮。
+    Pack {
+        /// 事件载荷（进度 / 结果 / 探测诊断 / 预检 / 完成）
+        event: Box<PackEvent>,
+        /// 任务代次
+        epoch: u64,
+    },
+    /// 安装进度（高频，host 只做聚合与转发）
+    Install {
+        /// 进度快照
+        progress: Box<InstallProgressView>,
+        /// 任务代次（[`super::CoreHost`] 的 `install_epoch`）
+        ///
+        /// 取消/重新开工都会把代次 +1，于是**旧任务还在飞的事件**带着旧代次回来，
+        /// host 一眼就能认出来并丢掉。没有这一层的话：取消后 `InstallProgress(None)` 刚把面板
+        /// 收回，下一条「下载中」事件立刻把它点亮——用户看到的就是「点了取消没反应」（M105 实测）。
+        epoch: u64,
+    },
+    /// 安装收尾（成功带实例名，失败带文案）
+    InstallDone {
+        /// 最终进度快照
+        progress: Box<InstallProgressView>,
+        /// 成功时为 `Ok(实例名)`
+        result: Result<String, String>,
+        /// 任务代次（语义同 [`HostTask::Install`] 的 `epoch`）
+        epoch: u64,
+    },
+    /// 账户列表
+    Accounts(Vec<AccountView>),
+    /// 设备码登录状态
+    Login(Box<DeviceLoginView>),
+    /// 第三方轨（authlib-injector）登录/校验状态
+    Authlib(Box<AuthlibLoginView>),
+    /// 账户皮肤抓取结果（`skin = None` = 没取到；UI 退回首字母块）
+    Avatar {
+        /// 账户 id
+        id: String,
+        /// 皮肤原图
+        skin: Option<SkinImage>,
+    },
+    /// Java 页（发行版/回退链/运行时）
+    Java(Box<JavaPageView>),
+    /// 日志页快照（会话列表 + 选中会话的行 + 诊断）
+    Logs {
+        /// 会话列表
+        sessions: Vec<LogSession>,
+        /// 选中会话的行
+        lines: Vec<LogLine>,
+        /// 诊断结论
+        diagnosis: Option<DiagnosisReport>,
+    },
+    /// 实时日志增量
+    Tail(Box<LiveLogBatch>),
+    /// 启动开始（pid + 会话 id）
+    LaunchStarted {
+        /// 实例 id
+        id: InstanceId,
+        /// 会话 id
+        session_id: SessionId,
+        /// 进程号
+        pid: u32,
+    },
+    /// 启动阶段推进（磁贴进度环）
+    Runtime {
+        /// 实例 id
+        id: InstanceId,
+        /// 阶段状态
+        runtime: InstanceRuntime,
+    },
+    /// 启动收尾
+    LaunchEnd(Box<LaunchFinished>),
+    /// 崩溃日志导入的分析结论
+    Crash(Box<DiagnosisReport>),
+    /// 横幅通知（隔离切换提示等）
+    Notice(Box<NoticeView>),
+    /// Toast
+    Toast(Box<Toast>),
+    /// 会话列表刷新（只换左栏）
+    Sessions(Vec<LogSession>),
+}
+
+/// 后台线程用的发送端（`Sender` 克隆即可）。
+pub type JobSender = Sender<HostTask>;
+
+/// host 侧的接收端。
+pub type JobReceiver = Receiver<HostTask>;
+
+/// 建一对通道。
+pub fn channel() -> (JobSender, JobReceiver) {
+    std::sync::mpsc::channel()
+}
+
+/// 起一个带名字的后台线程（名字只进 panic 信息，方便定位）。
+pub fn spawn(name: &str, job: impl FnOnce() + Send + 'static) -> std::thread::JoinHandle<()> {
+    std::thread::Builder::new()
+        .name(format!("ull-host-{name}"))
+        .spawn(job)
+        .unwrap_or_else(|error| panic!("起不来后台线程 {name}: {error}"))
+}
+
+/// 人读一行「启动结束」。
+pub fn launch_summary(outcome: LogOutcome, exit_code: Option<i32>) -> String {
+    match outcome {
+        LogOutcome::Ok => "正常退出".to_string(),
+        LogOutcome::Crashed => match exit_code {
+            Some(code) => format!("崩溃（exit {code}）"),
+            None => "崩溃".to_string(),
+        },
+        LogOutcome::SilentFail => "静默失败（exit 0 但游戏没起来）".to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn channel_carries_tasks_across_threads() {
+        let (tx, rx) = channel();
+        let handle = spawn("test", move || {
+            tx.send(HostTask::Toast(Box::new(Toast {
+                id: 1,
+                kind: crate::toast::ToastKind::Info,
+                text: "hi".to_string(),
+                remaining_ms: 0,
+            })))
+            .expect("发送");
+        });
+        handle.join().expect("线程结束");
+        let task = rx.recv().expect("收到");
+        assert!(matches!(task, HostTask::Toast(toast) if toast.text == "hi"));
+    }
+
+    #[test]
+    fn launch_summary_names_the_outcome() {
+        assert_eq!(launch_summary(LogOutcome::Ok, Some(0)), "正常退出");
+        assert_eq!(
+            launch_summary(LogOutcome::Crashed, Some(1)),
+            "崩溃（exit 1）"
+        );
+        assert!(launch_summary(LogOutcome::SilentFail, Some(0)).contains("静默"));
+    }
+}

crates/presenter/src/host/launch.rs

@@ -0,0 +1,338 @@
+//! 启动全链：实例 → `LaunchRequest` → 子进程 → JSONL 事件流（GUI 版）。
+//!
+//! 与 CLI `ull launch` 同源同序（`core` 的 `game::resolve` / `arguments.expand` /
+//! `launch::adapter::build_request` / `Launcher::spawn`），差异只有两处：
+//! - **不阻塞 UI**：装配与等待都在后台线程里，进度/日志经 [`super::job::HostTask`] 回流；
+//! - **身份来自 GUI 选中的账户**（`AccountStore` → `AuthPlaceholders`），凭据只在
+//!   本模块内被读一次，绝不进 DTO。
+//!
+//! 停止：`kill_tree(pid)`（core 的三段式进程树回收），`finish()` 会照常收尾写索引。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::{derive_game_dir, observe_mode, IsolationMode};
+use unlucky_core::game::{self, VersionJson};
+use unlucky_core::launch::adapter::{
+    self, AdapterOptions, AdapterWarning, LibraryInput, SnapshotInput,
+};
+use unlucky_core::launch::request::{JavaSelection, LaunchRequest, MemoryOptions};
+use unlucky_core::launch::time::{format_rfc3339_millis, now};
+use unlucky_core::launch::tree_kill;
+use unlucky_core::launch::{Launcher, LauncherConfig};
+use unlucky_core::platform::paths::ProcessEnv;
+
+use crate::dto::{InstanceId, InstanceRuntime, LaunchFinished, LaunchStage, LogOutcome, Progress};
+
+use super::env::HostEnv;
+use super::job::{launch_summary, HostTask, JobSender};
+
+/// 启动器名（与 CLI `meta::LAUNCHER_NAME` 同值）。
+pub const LAUNCHER_NAME: &str = "Unlucky Launcher";
+
+/// 一次启动需要的实例信息。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LaunchTarget {
+    /// 实例 id
+    pub id: InstanceId,
+    /// 实例名
+    pub name: String,
+    /// 绑定的版本 id
+    pub version_id: String,
+    /// 账户 id（`None` = 离线占位）
+    pub account: Option<String>,
+}
+
+/// 选中并用起来的 Java（`summary` 给 UI 一行提示）。
+pub struct JavaPick {
+    /// 交给 adapter 的选择
+    pub selection: JavaSelection,
+    /// 人读一行
+    pub summary: String,
+}
+
+/// 选一个能用的 Java：托管 > JAVA_HOME > PATH（`core::game::java` 的探测与优先级）。
+pub fn pick_java(env: &HostEnv, version_id: &str) -> JavaPick {
+    let store = env.store();
+    let install_root = store
+        .doc()
+        .effective_str("java.installRoot")
+        .map(str::trim)
+        .filter(|text| !text.is_empty())
+        .map(PathBuf::from);
+    let roots = unlucky_core::game::java::location::scan_roots(
+        env.mode(),
+        &env.layout,
+        install_root.as_deref(),
+        env.platform,
+        &ProcessEnv,
+    );
+    let candidates = unlucky_core::game::java::candidates_in_roots(&roots);
+    let required = unlucky_core::game::java::requirement_for_version(&env.game, version_id);
+    let picked = unlucky_core::game::java::pick(&candidates, &required).cloned();
+    match picked {
+        Some(runtime) => {
+            let major = runtime
+                .major
+                .unwrap_or(unlucky_core::game::java::DEFAULT_MAJOR);
+            let summary = format!(
+                "Java {}（{}{}）",
+                runtime.version.clone().unwrap_or_else(|| major.to_string()),
+                runtime.origin.category(),
+                runtime
+                    .vendor
+                    .as_ref()
+                    .map(|vendor| format!(" · {vendor}"))
+                    .unwrap_or_default()
+            );
+            JavaPick {
+                selection: JavaSelection::new(runtime.binary, major, runtime.bits),
+                summary,
+            }
+        }
+        None => {
+            let binary = PathBuf::from(unlucky_core::game::java::java_binary_name());
+            let major = required.minimum;
+            JavaPick {
+                selection: JavaSelection::new(binary, major, 64),
+                summary: format!("PATH 上的 Java（未探测到版本，按 Java {major} 启动）"),
+            }
+        }
+    }
+}
+
+/// 装配 [`LaunchRequest`]（与 CLI `snapshot::prepare` 同序）。
+///
+/// # Errors
+///
+/// 版本 JSON 缺失/非法、继承链断裂、隔离派生失败时返回用户可读文案。
+pub fn build_request(
+    env: &HostEnv,
+    target: &LaunchTarget,
+) -> Result<(LaunchRequest, Vec<String>), String> {
+    let version_id = target.version_id.clone();
+    let manifest_path = env.game.version_json(&version_id);
+    let text = std::fs::read_to_string(&manifest_path)
+        .map_err(|error| format!("读版本 JSON 失败 {}：{error}", manifest_path.display()))?;
+    let manifest =
+        VersionJson::from_json_str(&text).map_err(|error| format!("版本 JSON 非法：{error}"))?;
+    let source = |id: &str| -> Option<VersionJson> {
+        std::fs::read_to_string(env.game.version_json(id))
+            .ok()
+            .and_then(|text| VersionJson::from_json_str(&text).ok())
+    };
+    let resolved =
+        game::resolve(&source, &manifest).map_err(|error| format!("解析继承链失败：{error}"))?;
+
+    let environment = Environment::host();
+    let expanded = resolved
+        .arguments
+        .as_ref()
+        .map(|arguments| arguments.expand(&environment))
+        .unwrap_or_default();
+
+    let mut libraries: Vec<LibraryInput> = Vec::new();
+    for library in resolved.libraries.as_deref().unwrap_or_default() {
+        if !library.applies(&environment) || library.native_classifier(&environment).is_some() {
+            continue;
+        }
+        let Ok(coordinate) = library.coordinate() else {
+            continue;
+        };
+        let path = if library.is_local() {
+            env.game.version_library(&version_id, &coordinate)
+        } else {
+            env.game.library(&coordinate)
+        };
+        libraries.push(LibraryInput::new(path, library.name.clone()));
+    }
+    let natives = unlucky_core::launch::natives::collect(
+        &env.game,
+        &version_id,
+        resolved.libraries.as_deref().unwrap_or_default(),
+        &environment,
+    );
+
+    let game_dir = run_dir(env, target)?;
+    let jar_id = resolved.jar.clone().unwrap_or_else(|| version_id.clone());
+    let assets_root = env.game.assets_dir();
+    let assets_index = resolved
+        .assets
+        .clone()
+        .or_else(|| resolved.asset_index.as_ref().map(|index| index.id.clone()));
+    let snapshot = SnapshotInput {
+        version_id: &version_id,
+        version_name: Some(&target.name),
+        version_type: None,
+        game_version: None,
+        main_class: resolved.main_class.as_deref(),
+        jvm_arguments: &expanded.jvm,
+        game_arguments: &expanded.game,
+        legacy_arguments: resolved.minecraft_arguments.as_deref(),
+        libraries: &libraries,
+        natives: &natives,
+        primary_jar: env.game.version_jar(&jar_id),
+        game_dir,
+        assets_index: assets_index.as_deref(),
+        natives_dir: env.game.natives_dir(&version_id),
+        library_dir: env.game.libraries_dir(),
+        assets_root: assets_root.clone(),
+        game_assets: assets_root,
+    };
+
+    let java = pick_java(env, &version_id);
+    let (auth, identity_line) = super::identity::resolve(env, target.account.as_deref())?;
+    let memory = env
+        .store()
+        .effective("java.default_memory_mb")
+        .and_then(serde_json::Value::as_u64)
+        .and_then(|value| u32::try_from(value).ok());
+    let options = AdapterOptions {
+        java: java.selection,
+        memory: MemoryOptions {
+            min_mb: None,
+            max_mb: memory,
+        },
+        auth,
+        launcher_name: LAUNCHER_NAME.to_string(),
+        launcher_version: env!("CARGO_PKG_VERSION").to_string(),
+        language: "zh-CN".to_string(),
+        ..AdapterOptions::strict()
+    };
+    let output = adapter::build_request(&snapshot, options);
+    let mut warnings: Vec<String> = output.warnings.iter().map(describe_warning).collect();
+    warnings.push(java.summary);
+    warnings.push(identity_line);
+    let mut request = output.request;
+    request.instance.id = target.id.clone();
+    request.instance.name = target.name.clone();
+    Ok((request, warnings))
+}
+
+/// 派生运行目录（D20 覆盖链：实例 `isolation` > 全局 `instances.mode`）。
+fn run_dir(env: &HostEnv, target: &LaunchTarget) -> Result<PathBuf, String> {
+    let global = super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &target.id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?;
+    let derivation = derive_game_dir(&env.game, &target.version_id, global, config.as_ref(), None)
+        .map_err(|error| format!("隔离目录派生失败：{error}"))?;
+    if let Some(mut config) = config {
+        let at = format_rfc3339_millis(now());
+        if observe_mode(&mut config, &env.game, &at, derivation.isolation).unwrap_or(false) {
+            let _ =
+                unlucky_core::game::install::instance::write_instance_config(&env.layout, &config);
+        }
+    }
+    Ok(derivation.game_dir)
+}
+
+/// 起一次启动（后台线程；进度/日志/收尾全部走 `HostTask`）。
+pub fn start(env: HostEnv, tx: JobSender, target: LaunchTarget) {
+    let id = target.id.clone();
+    let tx_progress = tx.clone();
+    super::job::spawn("launch", move || {
+        let _ = tx_progress.send(HostTask::Runtime {
+            id: id.clone(),
+            runtime: InstanceRuntime::Busy {
+                stage: LaunchStage::Launch,
+                progress: Progress { done: 0, total: 1 },
+            },
+        });
+        let (request, warnings) = match build_request(&env, &target) {
+            Ok(ok) => ok,
+            Err(reason) => {
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: String::new(),
+                    outcome: LogOutcome::Crashed,
+                    summary: format!("启动失败：{reason}"),
+                })));
+                return;
+            }
+        };
+        for warning in &warnings {
+            let _ = tx.send(HostTask::Notice(Box::new(crate::dto::NoticeView::new(
+                &format!("launch-warn:{}", target.id),
+                crate::dto::NoticeLevel::Info,
+                "启动提示",
+                warning,
+            ))));
+        }
+        let config = LauncherConfig::new(env.sessions_root())
+            .with_launcher(LAUNCHER_NAME, env!("CARGO_PKG_VERSION"));
+        let session = match Launcher::new(config).spawn(&request) {
+            Ok(session) => session,
+            Err(error) => {
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: String::new(),
+                    outcome: LogOutcome::Crashed,
+                    summary: format!("启动失败：{error}"),
+                })));
+                return;
+            }
+        };
+        let session_id = session.session_id().to_string();
+        let pid = session.pid();
+        let _ = tx.send(HostTask::LaunchStarted {
+            id: id.clone(),
+            session_id: session_id.clone(),
+            pid,
+        });
+        let _ = tx.send(HostTask::Runtime {
+            id: id.clone(),
+            runtime: InstanceRuntime::Running { pid },
+        });
+        match session.finish() {
+            Ok(handle) => {
+                let outcome = super::identity::outcome_of(&handle);
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: session_id,
+                    outcome,
+                    summary: format!(
+                        "{}（{}，{:.1}s）",
+                        launch_summary(outcome, Some(handle.exit.code)),
+                        handle.exit.exit_type.as_str(),
+                        handle.uptime_ms as f64 / 1000.0
+                    ),
+                })));
+            }
+            Err(error) => {
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: session_id,
+                    outcome: LogOutcome::SilentFail,
+                    summary: format!("启动收尾失败：{error}"),
+                })));
+            }
+        }
+    });
+}
+
+/// 停止一次启动（按 pid 回收进程树；`finish()` 会在后台线程里照常收尾）。
+pub fn stop(pid: u32) -> Result<(), String> {
+    tree_kill::kill_tree(pid, std::time::Duration::from_secs(3))
+        .map_err(|error| format!("停止进程 {pid} 失败：{error}"))
+}
+
+/// 适配层告警 → 人读一行。
+fn describe_warning(warning: &AdapterWarning) -> String {
+    match warning {
+        AdapterWarning::MissingLibrary { name, path } => {
+            format!("缺少库文件 {name}（{}）", path.display())
+        }
+        AdapterWarning::MissingGameArguments => "版本 JSON 没有游戏参数".to_string(),
+        AdapterWarning::MissingAssetsIndex => "版本 JSON 没有资源索引".to_string(),
+        AdapterWarning::MissingMainClass => "版本 JSON 没有 mainClass".to_string(),
+        AdapterWarning::MissingNativeJar { name, path } => {
+            format!("缺少 natives 构件 {name}（{}）", path.display())
+        }
+    }
+}
+
+/// 隔离档位的展示串（`isolated` / `shared`）。
+pub fn isolation_label(mode: IsolationMode) -> &'static str {
+    mode.as_str()
+}

crates/presenter/src/host/launch_state_tests.rs

@@ -0,0 +1,267 @@
+//! host 启动状态机单测（P2-1/P2-2 的回归网）。
+//!
+//! 覆盖三件事：
+//! 1. `running_pid` 按实例 id 取 pid（并发启动不会把 A 的停止键指到 B）；
+//! 2. 重复启动守卫（`launches` 已落盘 + `pending` 窗口两态都要挡）；
+//! 3. `refresh_instances` 重建快照后仍保留真实运行时（Running / Busy / Failed）。
+
+use unlucky_core::game::install::instance::write_profiles;
+use unlucky_core::game::{InstanceProfile, ProfileId, ProfileList};
+
+use super::*;
+use crate::dto::{LaunchFinished, LogOutcome};
+use crate::toast::ToastKind;
+
+/// 临时数据根守卫：测试结束（含断言 panic）时把目录删掉，不留空壳。
+struct TempRoot(std::path::PathBuf);
+
+impl Drop for TempRoot {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+/// 建一个只有一条实例档案的数据根，返回 `(host, instance_id, 守卫)`。
+fn host_with_instance(label: &str) -> (CoreHost, String, TempRoot) {
+    let dir = std::env::temp_dir().join(format!(
+        "ull-host-launch-{label}-{}-{}",
+        std::process::id(),
+        line!()
+    ));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = HostEnv::at_root(&dir);
+    std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+
+    let profile = InstanceProfile {
+        id: ProfileId::generate(),
+        name: "demo".to_string(),
+        version_id: "1.20.1".to_string(),
+        game_dir: None,
+        running_dir: None,
+        java_path: None,
+        created_at: None,
+        last_played_at: None,
+        extra: std::collections::BTreeMap::new(),
+    };
+    let id = profile.id.as_str().to_string();
+    let profiles = ProfileList {
+        profiles: vec![profile],
+        ..ProfileList::default()
+    };
+    write_profiles(&env.layout, &profiles).expect("写 profiles");
+    (CoreHost::headless(env), id, TempRoot(dir))
+}
+
+fn live(instance: &str, session: &str, pid: u32) -> LiveLaunch {
+    LiveLaunch {
+        instance: instance.to_string(),
+        session: session.to_string(),
+        pid,
+    }
+}
+
+#[test]
+fn running_pid_is_per_instance_not_a_single_slot() {
+    let (mut host, id, _root) = host_with_instance("pid");
+    host.launches.push(live("a", "s-a", 111));
+    host.launches.push(live("b", "s-b", 222));
+
+    assert_eq!(host.running_pid("a"), Some(111));
+    assert_eq!(host.running_pid("b"), Some(222));
+    assert_eq!(
+        host.running_pid("c"),
+        None,
+        "没启动过的实例不该拿到别人的 pid"
+    );
+
+    // A 收尾后只影响 A：这正是 review r1 P2-1 的场景（旧实现共用一个槽位）。
+    host.launches.retain(|entry| entry.instance != "a");
+    assert_eq!(host.running_pid("a"), None);
+    assert_eq!(host.running_pid("b"), Some(222));
+
+    // 落盘实例默认是 Idle，兜底分支不误报。
+    assert_eq!(host.running_pid(&id), None);
+}
+
+#[test]
+fn duplicate_launch_is_rejected_before_spawning() {
+    let (mut host, id, _root) = host_with_instance("dup");
+    let _ = host.drain_events();
+    host.launches.push(live(&id, "s", 111));
+
+    host.start_launch(&id);
+
+    let events = host.drain_events();
+    assert!(
+        !events.iter().any(|event| matches!(
+            event,
+            AppEvent::Core(CoreEvent::InstanceRuntimeChanged { .. })
+        )),
+        "已在运行/启动中的实例不该再发 Busy（那会起第二个进程）"
+    );
+    assert!(
+        events
+            .iter()
+            .any(|event| matches!(event, AppEvent::Toast(toast) if toast.kind == ToastKind::Warn)),
+        "至少要给用户一条「已经在启动/运行中」的提示"
+    );
+    assert_eq!(host.launches.len(), 1, "启动表不该被重复启动污染");
+}
+
+#[test]
+fn pending_window_also_blocks_a_second_launch() {
+    let (mut host, id, _root) = host_with_instance("pending");
+    // 走 start_launch 用的同一个入口，模拟「已受理、后台线程还没回报 LaunchStarted」。
+    host.mark_pending(&id);
+    assert!(host.in_flight(&id));
+
+    let _ = host.drain_events();
+    host.start_launch(&id);
+    let events = host.drain_events();
+    assert!(
+        !events.iter().any(|event| matches!(
+            event,
+            AppEvent::Core(CoreEvent::InstanceRuntimeChanged { .. })
+        )),
+        "pending 窗口内重复点启动必须被挡住"
+    );
+    assert_eq!(host.pending.len(), 1);
+}
+
+#[test]
+fn launch_started_registers_and_launch_end_clears() {
+    let (mut host, id, _root) = host_with_instance("cycle");
+    host.mark_pending(&id);
+
+    host.handle(HostTask::LaunchStarted {
+        id: id.clone(),
+        session_id: "20261031T120000-abcd12".to_string(),
+        pid: 4_242,
+    });
+    assert!(!host.pending.contains(&id), "回报后 pending 要清掉");
+    assert_eq!(host.running_pid(&id), Some(4_242));
+
+    host.handle(HostTask::LaunchEnd(Box::new(LaunchFinished {
+        id: id.clone(),
+        session: "20261031T120000-abcd12".to_string(),
+        outcome: LogOutcome::Ok,
+        summary: "正常退出".to_string(),
+    })));
+    assert!(host.launches.is_empty(), "收尾后启动表要清空");
+    assert!(!host.failed.contains_key(&id));
+    assert_eq!(host.running_pid(&id), None);
+}
+
+#[test]
+fn refresh_keeps_running_instances_running() {
+    let (mut host, id, _root) = host_with_instance("refresh-run");
+    host.launches.push(live(&id, "s", 4_242));
+    let _ = host.drain_events();
+
+    host.refresh_instances();
+
+    let instance = instances_from_events(host.drain_events())
+        .into_iter()
+        .find(|instance| instance.id == id)
+        .expect("刷新后应有该实例");
+    assert_eq!(
+        instance.runtime,
+        InstanceRuntime::Running { pid: 4_242 },
+        "刷新（装版本/账户变更/别的实例收尾）不能把在跑实例打回 Idle"
+    );
+}
+
+#[test]
+fn refresh_keeps_pending_as_busy_and_failed_as_failed() {
+    let (mut host, id, _root) = host_with_instance("refresh-busy");
+
+    // Busy：走 start_launch 用的同一个入口（mark_pending），而不是直接改字段。
+    host.mark_pending(&id);
+    let pending = instances_from_events({
+        host.refresh_instances();
+        host.drain_events()
+    })
+    .into_iter()
+    .find(|instance| instance.id == id)
+    .expect("实例存在");
+    assert!(matches!(
+        pending.runtime,
+        InstanceRuntime::Busy {
+            stage: crate::dto::LaunchStage::Launch,
+            ..
+        }
+    ));
+
+    // Failed：走唯一真实写入路径 LaunchEnd（不是手动塞 failed 表）。
+    host.handle(HostTask::LaunchEnd(Box::new(LaunchFinished {
+        id: id.clone(),
+        session: "20261031T120000-dead01".to_string(),
+        outcome: LogOutcome::Crashed,
+        summary: "崩溃（exit 1）".to_string(),
+    })));
+    assert!(!host.pending.contains(&id), "LaunchEnd 必须清 pending");
+    assert!(!host.in_flight(&id), "收尾后该实例要能被重新启动");
+
+    let failed = instances_from_events({
+        host.refresh_instances();
+        host.drain_events()
+    })
+    .into_iter()
+    .find(|instance| instance.id == id)
+    .expect("实例存在");
+    assert_eq!(
+        failed.runtime,
+        InstanceRuntime::Failed {
+            reason: "崩溃（exit 1）".to_string()
+        },
+        "失败原因要经得住一次刷新（否则磁贴的「重试」外观会被 Idle 盖掉）"
+    );
+}
+
+#[test]
+fn launch_end_before_launch_started_still_releases_the_instance() {
+    let (mut host, id, _root) = host_with_instance("fail-early");
+    // build_request / spawn 失败的现场：start_launch 已标 pending、后台线程只发 LaunchEnd。
+    host.mark_pending(&id);
+    assert!(host.in_flight(&id));
+
+    host.handle(HostTask::LaunchEnd(Box::new(LaunchFinished {
+        id: id.clone(),
+        session: String::new(),
+        outcome: LogOutcome::Crashed,
+        summary: "启动失败：找不到 Java".to_string(),
+    })));
+
+    assert!(
+        !host.pending.contains(&id),
+        "LaunchEnd 早于 LaunchStarted 时也必须清 pending（否则该实例本会话再也起不来）"
+    );
+    assert!(!host.in_flight(&id), "失败后要能重试");
+
+    let failed = instances_from_events({
+        host.refresh_instances();
+        host.drain_events()
+    })
+    .into_iter()
+    .find(|instance| instance.id == id)
+    .expect("实例存在");
+    assert_eq!(
+        failed.runtime,
+        InstanceRuntime::Failed {
+            reason: "启动失败：找不到 Java".to_string()
+        },
+        "早失败也要在磁贴上留下「失败/重试」，不能被 Idle 盖掉"
+    );
+}
+
+/// 从事件队列里取最后一次 `InstancesChanged`。
+fn instances_from_events(events: Vec<AppEvent>) -> Vec<crate::dto::InstanceSummary> {
+    events
+        .into_iter()
+        .rev()
+        .find_map(|event| match event {
+            AppEvent::Core(CoreEvent::InstancesChanged(instances)) => Some(instances),
+            _ => None,
+        })
+        .unwrap_or_default()
+}

crates/presenter/src/host/loader_versions.rs

@@ -0,0 +1,120 @@
+//! 加载器版本清单（下载页「安装选项」的版本下拉，M105）。
+//!
+//! ## 为什么要有这一支
+//!
+//! core 早就有现成能力：[`unlucky_core::addon::loader::LoaderSource::loader_versions`] 按
+//! `(加载器, 原版版本)` 给出**官方那份**可用版本表（Fabric/Quilt 走 fabric meta 的 loader 列表，
+//! Forge/NeoForge 走 maven 的 `maven-metadata.xml` 再按 `matches_mc` 过滤）。
+//! 缺的从来不是能力，是 presenter 到 UI 的那一跳——于是用户在下载页只能装原版，
+//! 「自己有的能力不接出来」是 M105 要收的口子。
+//!
+//! ## 一次查询只回答一个问题
+//!
+//! 事件里带 `(kind, mc_version)` 原样回传，`state.rs` 拿它当缓存键：**切原版版本 = 换键**，
+//! 于是 A 版本的 Fabric 列表不可能挂到 B 版本下面（这条是 M105 复审明确要求的）。
+//! 取不到（网络/该组合官方没有版本）走 `Err(人读原因)`，页面据此**禁掉确认**并给具名错误，
+//! 绝不静默显示成空列表。
+
+use unlucky_core::addon::loader::{LoaderKind as CoreLoaderKind, LoaderSource};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::LoaderKind;
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 拉一份加载器版本列表（网络在后台线程里，UI 不卡）。
+pub fn spawn_list(env: HostEnv, tx: JobSender, kind: LoaderKind, mc_version: String) {
+    spawn("loader-versions", move || {
+        let result = fetch(&env, kind, &mc_version);
+        let _ = tx.send(HostTask::LoaderVersions {
+            kind,
+            mc_version,
+            result,
+        });
+    });
+}
+
+/// 同步拉取（后台线程里跑）：DTO 的加载器词表 → core 的加载器词表 → 官方清单。
+///
+/// 原版（`Vanilla`）没有「加载器版本」这回事，直接给空列表而不是报错：调用方（页面）
+/// 在选了原版时根本不画这个下拉，这里是防守。
+pub fn fetch(env: &HostEnv, kind: LoaderKind, mc_version: &str) -> Result<Vec<String>, String> {
+    if kind == LoaderKind::Vanilla {
+        return Ok(Vec::new());
+    }
+    let Some(kind) = CoreLoaderKind::parse(kind.as_str()) else {
+        return Err(format!("未知加载器 `{}`", kind.as_str()));
+    };
+    if mc_version.trim().is_empty() {
+        return Err("没有选择原版版本".to_string());
+    }
+    let engine = super::engine::engine(env);
+    let meta_cache = env.layout.meta_cache();
+    block_on(async {
+        LoaderSource::new(&engine, &meta_cache)
+            .loader_versions(kind, mc_version.trim())
+            .await
+    })
+    .map_err(|error| error.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use crate::dto::{AppEvent, CoreEvent};
+    use crate::state::AppState;
+
+    /// **缓存键必须是 `(加载器, 原版版本)`**（M105 的硬要求，复审点名的那条）。
+    ///
+    /// 现场：在 1.20.1 上查过 Fabric 的列表，接着点 1.21.9；键里若没有原版版本，1.21.9 会直接
+    /// 显示 1.20.1 那份列表 —— 用户选了个「1.21.9 上不存在」的加载器版本，直到点安装才失败。
+    #[test]
+    fn cache_is_keyed_per_loader_and_minecraft_version() {
+        let mut state = AppState::new();
+        state.apply(AppEvent::Core(CoreEvent::LoaderVersions {
+            kind: LoaderKind::Fabric,
+            mc_version: "1.20.1".to_string(),
+            result: Ok(vec!["0.16.5".to_string()]),
+        }));
+        assert!(state
+            .loader_versions_for(LoaderKind::Fabric, "1.20.1")
+            .is_some());
+        assert!(state
+            .loader_versions_for(LoaderKind::Fabric, "1.21.9")
+            .is_none());
+        assert!(state
+            .loader_versions_for(LoaderKind::Quilt, "1.20.1")
+            .is_none());
+
+        // 失败也是「查过了」：页面据此显示具名原因并禁掉确认，不再无限重试
+        state.apply(AppEvent::Core(CoreEvent::LoaderVersions {
+            kind: LoaderKind::Quilt,
+            mc_version: "1.20.1".to_string(),
+            result: Err("network down".to_string()),
+        }));
+        assert!(state
+            .loader_versions_for(LoaderKind::Quilt, "1.20.1")
+            .is_some());
+    }
+
+    /// 原版没有加载器版本：给空表而不是报错（页面不画这个下拉，防守而已）。
+    #[test]
+    fn vanilla_has_no_loader_versions() {
+        let dir = std::env::temp_dir().join(format!("ull-loader-versions-{}", std::process::id()));
+        let env = HostEnv::at_root(&dir);
+        assert_eq!(fetch(&env, LoaderKind::Vanilla, "1.20.1"), Ok(Vec::new()));
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// 空版本号在联网前就被拒（不做无意义的请求，也给出人读原因）。
+    #[test]
+    fn empty_mc_version_is_rejected_before_network() {
+        let dir = std::env::temp_dir().join(format!("ull-loader-empty-{}", std::process::id()));
+        let env = HostEnv::at_root(&dir);
+        let err = fetch(&env, LoaderKind::Fabric, " ").unwrap_err();
+        assert!(err.contains("没有选择原版版本"), "{err}");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}

crates/presenter/src/host/logs.rs

@@ -0,0 +1,342 @@
+//! 日志 / 诊断：会话索引 → 会话列表，事件 JSONL → 日志行，规则引擎 → 诊断卡片。
+//!
+//! 与 CLI `ull logs` / `ull diagnose` 同源（`launch::session_index` + `diagnose` 规则引擎）：
+//! 「同一份 jsonl 的两种读法」只有这一处实现（M39 ports/events.rs 的设计）。
+//! 实时滚动 = host 每拍尾随启动会话的 JSONL（只读新增字节），不额外开第二条事件通道。
+
+use std::io::{Read, Seek, SeekFrom};
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+use unlucky_core::diagnose::collectors::{ExitSignal, SignalOrigin};
+use unlucky_core::diagnose::engine::{Diagnoser, DiagnosisInput};
+use unlucky_core::diagnose::loader::RuleLoader;
+use unlucky_core::launch::session_index::{self, SessionIndexEntry};
+
+use crate::dto::{
+    Diagnosis, DiagnosisReport, LogLevel, LogLine, LogOutcome, LogSession, SessionId,
+};
+
+use super::env::HostEnv;
+
+/// 送进规则引擎的默认尾巴行数（与 CLI 同值，避免两条路看到不同证据）。
+pub const DEFAULT_TAIL: usize = 2000;
+
+/// 日志页一次最多渲染的行数（超出的截断，避免大文件把 UI 拖死）。
+pub const MAX_RENDERED_LINES: usize = 2_000;
+
+/// 会话索引目录（`.ULL/data/agent/sessions`）。
+pub fn root(env: &HostEnv) -> PathBuf {
+    env.sessions_root()
+}
+
+/// 会话列表（新→旧）。
+pub fn sessions(env: &HostEnv) -> Vec<LogSession> {
+    let index = session_index::index_path(&root(env));
+    let mut entries = session_index::read_all(&index).unwrap_or_default();
+    entries.sort_by(|a, b| b.started_at.cmp(&a.started_at));
+    entries.iter().map(session_of).collect()
+}
+
+/// 索引条目 → 左栏会话行。
+pub fn session_of(entry: &SessionIndexEntry) -> LogSession {
+    LogSession {
+        id: entry.session_id.clone(),
+        instance: if entry.instance_name.is_empty() {
+            entry.instance_id.clone()
+        } else {
+            entry.instance_name.clone()
+        },
+        when: display_time(&entry.started_at),
+        outcome: outcome_of(entry),
+        duration_secs: entry.duration_ms / 1000,
+    }
+}
+
+/// 结局：静默失败 > 崩溃（非 0 / crash_found） > 正常。
+pub fn outcome_of(entry: &SessionIndexEntry) -> LogOutcome {
+    if entry.silent_failure {
+        LogOutcome::SilentFail
+    } else if entry.crash_found
+        || entry.exit_code.is_some_and(|code| code != 0)
+        || (entry.exit_code.is_none() && !entry.ended_at.is_empty())
+    {
+        LogOutcome::Crashed
+    } else {
+        LogOutcome::Ok
+    }
+}
+
+/// `2026-10-29T19:22:45.123Z` → `10-29 19:22`。
+pub fn display_time(started_at: &str) -> String {
+    let body = started_at.trim_end_matches('Z');
+    let Some((date, time)) = body.split_once('T') else {
+        return started_at.to_string();
+    };
+    let date = date.get(5..).unwrap_or(date);
+    let time = time.get(..5).unwrap_or(time);
+    format!("{date} {time}")
+}
+
+/// 事件流文件路径（`<sessions>/game/<log_path>`）。
+pub fn event_path(env: &HostEnv, entry: &SessionIndexEntry) -> PathBuf {
+    root(env).join("game").join(&entry.log_path)
+}
+
+/// 会话 id 或唯一前缀 → 索引条目。
+fn find(env: &HostEnv, key: &str) -> Option<SessionIndexEntry> {
+    let index = session_index::index_path(&root(env));
+    let entries = session_index::read_all(&index).ok()?;
+    if let Some(exact) = entries.iter().find(|entry| entry.session_id == key) {
+        return Some(exact.clone());
+    }
+    entries
+        .iter()
+        .find(|entry| entry.session_id.starts_with(key))
+        .cloned()
+}
+
+/// 事件 JSON → 一行日志（`stdout`/`stderr` 的 `payload.line`）。
+pub fn line_of(event: &Value) -> Option<LogLine> {
+    let text = event.pointer("/payload/line").and_then(Value::as_str)?;
+    let kind = event
+        .get("kind")
+        .and_then(Value::as_str)
+        .unwrap_or_default();
+    let level = match event
+        .pointer("/payload/level")
+        .and_then(Value::as_str)
+        .unwrap_or_default()
+    {
+        "error" => LogLevel::Error,
+        "warn" | "warning" => LogLevel::Warn,
+        "debug" | "trace" => LogLevel::Debug,
+        _ => {
+            if kind == "stderr" {
+                LogLevel::Warn
+            } else {
+                LogLevel::Info
+            }
+        }
+    };
+    Some(LogLine {
+        text: text.to_string(),
+        level,
+    })
+}
+
+/// 整个事件流 → 日志行（解析失败的行跳过，容忍被 kill 时截断的尾行）。
+pub fn read_lines(path: &Path) -> Vec<LogLine> {
+    let Ok(text) = std::fs::read_to_string(path) else {
+        return Vec::new();
+    };
+    text.lines()
+        .filter(|line| !line.trim().is_empty())
+        .filter_map(|line| serde_json::from_str::<Value>(line).ok())
+        .filter_map(|event| line_of(&event))
+        .collect()
+}
+
+/// 打开一个会话：日志行 + 规则引擎结论。
+pub fn open(env: &HostEnv, key: &str) -> (Vec<LogLine>, Option<DiagnosisReport>) {
+    let Some(entry) = find(env, key) else {
+        return (Vec::new(), None);
+    };
+    let path = event_path(env, &entry);
+    let lines = read_lines(&path);
+    let diagnosis = diagnose_lines(&entry, &lines);
+    (lines, diagnosis)
+}
+
+/// 规则引擎跑一遍（**规则先跑，模型补位**：这里只出规则结论）。
+pub fn diagnose_lines(entry: &SessionIndexEntry, lines: &[LogLine]) -> Option<DiagnosisReport> {
+    let stderr_text: String = lines
+        .iter()
+        .filter(|line| line.level == LogLevel::Error || line.level == LogLevel::Warn)
+        .map(|line| line.text.as_str())
+        .collect::<Vec<_>>()
+        .join("\n");
+    let body: String = lines
+        .iter()
+        .rev()
+        .take(DEFAULT_TAIL)
+        .map(|line| line.text.as_str())
+        .collect::<Vec<_>>()
+        .into_iter()
+        .rev()
+        .collect::<Vec<_>>()
+        .join("\n");
+    if body.is_empty() {
+        return None;
+    }
+    let error_lines = u32::try_from(
+        lines
+            .iter()
+            .filter(|line| line.level == LogLevel::Error)
+            .count(),
+    )
+    .unwrap_or(u32::MAX);
+    let exit = ExitSignal::classify(
+        entry.exit_code,
+        Some(entry.duration_ms),
+        error_lines,
+        &stderr_text,
+    );
+    let mut input = DiagnosisInput::new().with_exit(exit);
+    input.push_text(SignalOrigin::Stderr, body);
+    let loader = RuleLoader::embedded();
+    let report = Diagnoser::new(loader.rule_set().rules().to_vec()).analyze(&input);
+    let finding = report
+        .findings
+        .first()
+        .or_else(|| report.secondary.first())?;
+    Some(DiagnosisReport {
+        session: entry.session_id.clone(),
+        diagnosis: Diagnosis {
+            rule: finding.rule_id.clone(),
+            title: finding.message.clone(),
+            confidence: confidence_percent(finding.confidence),
+            hint: finding.detail.clone().unwrap_or_else(|| {
+                report
+                    .exit
+                    .as_ref()
+                    .map(|exit| exit.exit_type.as_str().to_string())
+                    .unwrap_or_else(|| "未知退出".to_string())
+            }),
+            fix: finding
+                .materialized_actions()
+                .first()
+                .map(|action| action.tool.to_string()),
+        },
+    })
+}
+
+/// 0.0~1.0 → 0~100（四舍五入）。
+pub fn confidence_percent(confidence: f32) -> u8 {
+    let percent = (confidence.clamp(0.0, 1.0) * 100.0).round();
+    u8::try_from(percent as u32).unwrap_or(100)
+}
+
+/// 导入崩溃日志（`hs_err_pid*.log` / `crash-*.txt` / `latest.log`）做规则分析。
+///
+/// 文件名含 `hs_err` 时先走 `hs_err::parse`（结构化字段进规则引擎），否则整份文本当信号喂进去。
+pub fn analyze_crash_file(path: &str) -> Result<(String, DiagnosisReport), String> {
+    let path = Path::new(path);
+    if !path.is_file() {
+        return Err(format!("找不到崩溃日志：{}", path.display()));
+    }
+    let text = std::fs::read_to_string(path).map_err(|error| format!("读崩溃日志失败：{error}"))?;
+    let name = path
+        .file_name()
+        .map(|name| name.to_string_lossy().to_string())
+        .unwrap_or_else(|| "crash.log".to_string());
+    let is_hs_err = name.contains("hs_err");
+    let mut input = DiagnosisInput::new();
+    if is_hs_err {
+        input.push_hs_err(unlucky_core::diagnose::hs_err::parse(&text));
+    }
+    input.push_text(
+        if is_hs_err {
+            SignalOrigin::HsErr
+        } else if name.contains("crash") {
+            SignalOrigin::CrashReport
+        } else {
+            SignalOrigin::LatestLog
+        },
+        text,
+    );
+    let loader = RuleLoader::embedded();
+    let report = Diagnoser::new(loader.rule_set().rules().to_vec()).analyze(&input);
+    let finding = report
+        .findings
+        .first()
+        .or_else(|| report.secondary.first())
+        .ok_or_else(|| "规则引擎没有从这份日志里认出已知问题".to_string())?;
+    Ok((
+        format!("导入的日志：{name}"),
+        DiagnosisReport {
+            session: format!("file:{name}"),
+            diagnosis: Diagnosis {
+                rule: finding.rule_id.clone(),
+                title: finding.message.clone(),
+                confidence: confidence_percent(finding.confidence),
+                hint: finding
+                    .detail
+                    .clone()
+                    .unwrap_or_else(|| "规则引擎命中（详见证据行）".to_string()),
+                fix: finding
+                    .materialized_actions()
+                    .first()
+                    .map(|action| action.tool.to_string()),
+            },
+        },
+    ))
+}
+
+/// 实时尾随器：只读文件新增的字节，解析出完整的 JSON 行。
+#[derive(Debug, Default)]
+pub struct Tail {
+    path: Option<PathBuf>,
+    session: Option<SessionId>,
+    offset: u64,
+}
+
+impl Tail {
+    /// 开始尾随一个会话。
+    pub fn attach(&mut self, path: PathBuf, session: &str) {
+        self.path = Some(path);
+        self.session = Some(session.to_string());
+        self.offset = 0;
+    }
+
+    /// 停止尾随。
+    pub fn detach(&mut self) {
+        self.path = None;
+        self.session = None;
+        self.offset = 0;
+    }
+
+    /// 当前尾随的会话。
+    pub fn session(&self) -> Option<&str> {
+        self.session.as_deref()
+    }
+
+    /// 读新行（返回 `(会话 id, 新行)`；没有新内容返回 `None`）。
+    pub fn poll(&mut self) -> Option<(String, Vec<LogLine>)> {
+        let path = self.path.clone()?;
+        let session = self.session.clone()?;
+        let file = std::fs::File::open(&path).ok()?;
+        let len = file.metadata().ok()?.len();
+        if len <= self.offset {
+            return None;
+        }
+        let mut file = file;
+        file.seek(SeekFrom::Start(self.offset)).ok()?;
+        let mut buffer = String::new();
+        file.read_to_string(&mut buffer).ok()?;
+        // 只吃到最后一个换行：半行留到下一拍（避免把 JSON 截断解析成脏行）
+        let last_newline = buffer.rfind('\n')?;
+        let complete = &buffer[..=last_newline];
+        self.offset += u64::try_from(complete.len()).unwrap_or(u64::MAX);
+        let lines: Vec<LogLine> = complete
+            .lines()
+            .filter(|line| !line.trim().is_empty())
+            .filter_map(|line| serde_json::from_str::<Value>(line).ok())
+            .filter_map(|event| line_of(&event))
+            .collect();
+        Some((session, lines))
+    }
+}
+
+/// 会话是否已收尾（索引里出现 `ended_at` 或文件停止增长超过一拍）。
+pub fn session_finished(env: &HostEnv, session: &str) -> bool {
+    let index = session_index::index_path(&root(env));
+    session_index::read_all(&index)
+        .unwrap_or_default()
+        .iter()
+        .any(|entry| entry.session_id == session && !entry.ended_at.is_empty())
+}
+
+#[cfg(test)]
+#[path = "logs_tests.rs"]
+mod tests;

crates/presenter/src/host/logs_tests.rs

@@ -0,0 +1,86 @@
+//! host/logs.rs 的单测（拆文件守 400 行上限）。
+
+use super::*;
+
+#[test]
+fn time_display_and_outcomes() {
+    assert_eq!(display_time("2026-10-29T19:22:45.123Z"), "10-29 19:22");
+    assert_eq!(display_time("nope"), "nope");
+    let mut entry = SessionIndexEntry {
+        v: 1,
+        session_id: "s".to_string(),
+        instance_id: String::new(),
+        instance_name: String::new(),
+        game_version: String::new(),
+        started_at: String::new(),
+        ended_at: "2026-10-29T19:22:45Z".to_string(),
+        duration_ms: 1000,
+        exit_code: Some(0),
+        exit_type: Some("normal".to_string()),
+        silent_failure: false,
+        window_detected: true,
+        event_count: 1,
+        log_path: "s.jsonl".to_string(),
+        crash_found: false,
+        diagnosis_top: None,
+    };
+    assert_eq!(outcome_of(&entry), LogOutcome::Ok);
+    entry.exit_code = Some(1);
+    assert_eq!(outcome_of(&entry), LogOutcome::Crashed);
+    entry.silent_failure = true;
+    assert_eq!(outcome_of(&entry), LogOutcome::SilentFail);
+}
+
+#[test]
+fn lines_map_levels_and_skip_non_line_events() {
+    let stdout = serde_json::json!({"kind":"stdout","payload":{"line":"hi","level":"info"}});
+    assert_eq!(line_of(&stdout).unwrap().level, LogLevel::Info);
+    let stderr = serde_json::json!({"kind":"stderr","payload":{"line":"boom","level":"error"}});
+    assert_eq!(line_of(&stderr).unwrap().level, LogLevel::Error);
+    let other = serde_json::json!({"kind":"cmd_built","payload":{"argv":[]}});
+    assert!(line_of(&other).is_none());
+}
+
+#[test]
+fn tail_only_consumes_complete_lines() {
+    let dir = std::env::temp_dir().join(format!("ull-host-tail-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("目录");
+    let path = dir.join("s.jsonl");
+    std::fs::write(
+        &path,
+        "{\"kind\":\"stdout\",\"payload\":{\"line\":\"one\"}}\n",
+    )
+    .expect("写");
+    let mut tail = Tail::default();
+    tail.attach(path.clone(), "s");
+    let (session, lines) = tail.poll().expect("首拍有新行");
+    assert_eq!(session, "s");
+    assert_eq!(lines.len(), 1);
+    assert!(tail.poll().is_none(), "没有新增就不该再产出");
+
+    // 半行不消费
+    let mut text = std::fs::read_to_string(&path).expect("读");
+    text.push_str("{\"kind\":\"stdout\",\"payload\":{\"line\":\"tw");
+    std::fs::write(&path, text).expect("写");
+    assert!(tail.poll().is_none(), "半个 JSON 行不能解析");
+    let mut text = std::fs::read_to_string(&path).expect("读");
+    text.push_str("o\"}}\n");
+    std::fs::write(&path, text).expect("写");
+    let (_, lines) = tail.poll().expect("补全后应产出");
+    assert_eq!(lines[0].text, "two");
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn crash_import_reports_missing_file() {
+    let err = analyze_crash_file("D:/definitely/missing/hs_err_pid1.log").unwrap_err();
+    assert!(err.contains("找不到崩溃日志"), "{err}");
+}
+
+#[test]
+fn confidence_percent_is_rounded_and_clamped() {
+    assert_eq!(confidence_percent(0.923), 92);
+    assert_eq!(confidence_percent(-1.0), 0);
+    assert_eq!(confidence_percent(2.0), 100);
+}

crates/presenter/src/host/meter.rs

@@ -0,0 +1,89 @@
+//! 安装进度的记账器（文件计数 / 字节 / 速度 / ETA）。
+//!
+//! `execute` 的文件级回调已经把每个文件的结局给了我们，这里只做聚合；
+//! 速度用相邻两次采样的字节差算（core 的事件只给绝对值）。
+
+use std::sync::Arc;
+use std::time::Instant;
+
+use unlucky_core::game::install::{FileOutcome, FileStatus, ProgressSink};
+
+use crate::dto::{derive_speed, CreateRequest, InstallProgressView, InstallStage};
+
+use super::install::loader_label;
+use super::job::{HostTask, JobSender};
+/// 一次安装的上下文（进度回调共享）。
+pub(super) struct Meter {
+    pub(super) progress: InstallProgressView,
+    /// 任务代次：随每条进度一起回流，让 host 能丢掉「已被取消/被顶掉的旧任务」的事件。
+    ///
+    /// 记在记账器上而不是每条 `HostTask` 现传：所有发送点都已经持有这把锁并读 `progress`，
+    /// 于是代次与它描述的那份进度**永远同源**（不会出现「新代次的进度配旧代次的标签」）。
+    pub(super) epoch: u64,
+    previous: Option<(u64, Instant)>,
+}
+
+impl Meter {
+    pub(super) fn new(request: &CreateRequest, epoch: u64) -> Self {
+        Self {
+            progress: InstallProgressView::start(
+                &request.version,
+                &request.instance_name(),
+                &loader_label(request.loader, &request.loader_version),
+            ),
+            epoch,
+            previous: None,
+        }
+    }
+
+    /// 换阶段（重置速度采样）。
+    pub(super) fn stage(&mut self, stage: InstallStage, message: &str) {
+        self.progress.stage = stage;
+        self.progress.message = message.to_string();
+        self.previous = None;
+    }
+
+    /// 预记账一段待下载的文件（文件数 + 字节）。
+    ///
+    /// 一次安装可能分几段（原版 / 处理器依赖库 / 加载器库）：每段开工前都先记账，
+    /// 整条进度曲线才是单调的——某一段下完不会先到 100%，再因为下一段的文件被计入而回落。
+    pub(super) fn expect(&mut self, files: usize, bytes: u64) {
+        let files = u64::try_from(files).unwrap_or(u64::MAX);
+        self.progress.files_total = self.progress.files_total.saturating_add(files);
+        self.progress.bytes_total = self.progress.bytes_total.saturating_add(bytes);
+    }
+
+    /// 记账一个文件的结局。
+    pub(super) fn note(&mut self, outcome: &FileOutcome) {
+        self.progress.files_done += 1;
+        if outcome.status != FileStatus::Skipped {
+            self.progress.bytes_done = self.progress.bytes_done.saturating_add(outcome.bytes);
+        }
+        let now = Instant::now();
+        if let Some(previous) = self.previous {
+            if let Some((speed, eta)) = derive_speed(
+                previous,
+                (self.progress.bytes_done, now),
+                self.progress.bytes_total,
+            ) {
+                self.progress.speed_bps = speed;
+                self.progress.eta_secs = eta;
+            }
+        }
+        self.previous = Some((self.progress.bytes_done, now));
+    }
+}
+
+/// 进度 sink（`execute` 的文件级回调）。
+pub(super) fn sink_for(tx: JobSender, meter: Arc<std::sync::Mutex<Meter>>) -> ProgressSink {
+    Arc::new(move |outcome: &FileOutcome| {
+        let Ok(mut meter) = meter.lock() else {
+            return;
+        };
+        meter.note(outcome);
+        let _ = tx.send(HostTask::Install {
+            progress: Box::new(meter.progress.clone()),
+            epoch: meter.epoch,
+        });
+    })
+}

crates/presenter/src/host/mod.rs

@@ -0,0 +1,366 @@
+//! 真实后端：把 core（game/launch/install/auth/java/diagnose/setting）装配成 GUI 的 host。
+//!
+//! 边界：本模块是**整个 presenter crate 里唯一**允许 `use unlucky_core::…` 的地方（连同
+//! `settings_bridge`）；出口只有 [`crate::dto`] 的快照/事件。线程模型：
+//!
+//! ```text
+//! dispatch(AppCommand) ──► 立即动作（读盘/写设置）或 spawn 后台线程
+//! 后台线程 ──HostTask──► rx ──tick()──► CoreEvent ──► state.apply()
+//! tick() 另外每 ~600ms 尾随一次运行中会话的 JSONL（实时日志滚动）
+//! ```
+//!
+//! AI 对话暂时仍由 [`MockBackend`] 提供脚本回复（agent 的 GUI host 是后续 mission）；
+//! 其余页面全部走真实 core。
+
+mod accounts;
+mod addon;
+mod dispatch;
+mod engine;
+pub mod env;
+mod game;
+mod handle;
+mod identity;
+mod install;
+mod install_journal;
+mod install_processors;
+mod java;
+mod job;
+mod launch;
+mod loader_versions;
+mod logs;
+mod meter;
+mod opener;
+mod settings;
+mod versions;
+
+use std::collections::{BTreeMap, BTreeSet, VecDeque};
+use std::time::Duration;
+
+use crate::dto::{
+    AccountView, AppCommand, AppEvent, Backend, CoreEvent, DiagnosisReport, InstallProgressView,
+    InstanceRuntime, JavaChainStep, NoticeView, SkinImage,
+};
+use crate::mock::MockBackend;
+use crate::toast::{Toast, ToastKind};
+
+use accounts::LoginJob;
+pub use env::HostEnv;
+use job::{HostTask, JobReceiver, JobSender};
+
+/// 每拍最多处理的后台消息数（防止一次 tick 吃掉整帧预算）。
+const MAX_TASKS_PER_TICK: usize = 64;
+
+/// 实时日志尾随间隔（拍数，33ms/拍 → 约 600ms 一次）。
+const TAIL_POLL_TICKS: u64 = 18;
+
+/// 一次在跑的启动（并发启动时按实例 id 区分，停止/尾随都不会串到别的实例）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct LiveLaunch {
+    instance: String,
+    session: String,
+    pid: u32,
+}
+
+/// 真实 host。
+pub struct CoreHost {
+    env: HostEnv,
+    events: VecDeque<AppEvent>,
+    tx: JobSender,
+    rx: JobReceiver,
+    ticks: u64,
+    /// 当前启动账户 id（内存态；跨会话持久化要 core schema 增键，见 handoff）
+    active_account: Option<String>,
+    accounts: Vec<AccountView>,
+    login: Option<LoginJob>,
+    /// 第三方轨（authlib）登录任务句柄（与微软两条流共用取消语义，但**不复用槽位**：
+    /// 两条轨同时点「登录」时各自的结果不能互相踩）
+    authlib: Option<LoginJob>,
+    /// 已抓到的皮肤（账户 id → 原图；`None` = 试过但没取到，不再重试）
+    skins: BTreeMap<String, Option<SkinImage>>,
+    /// 已经发起过皮肤抓取的账户 id（防每次刷新都重新抓一遍）
+    skin_requested: BTreeSet<String>,
+    java_chain: Vec<JavaChainStep>,
+    java_busy: bool,
+    java_message: String,
+    install: Option<InstallProgressView>,
+    notices: Vec<NoticeView>,
+    /// 在跑的启动（实例 → 会话 → pid；支持多个实例同时启动，停止按 id 找正确的 pid）
+    launches: Vec<LiveLaunch>,
+    /// 已受理但后台线程还没回报 `LaunchStarted` 的实例（防「启动中重复点启动」起第二个进程）
+    pending: BTreeSet<String>,
+    /// 上次启动失败的实例与原因（刷新快照时保住磁贴的「失败/重试」外观）
+    failed: BTreeMap<String, String>,
+    /// 实时日志尾随器
+    tail: logs::Tail,
+    /// AI 对话的临时后端（agent GUI host 落地前的占位）
+    chat: MockBackend,
+    /// 当前安装任务的取消标记（`execute_with_cancel` 与段边界检查共同消费）
+    install_cancel: Option<std::sync::Arc<std::sync::atomic::AtomicBool>>,
+    /// 当前安装任务的代次。
+    ///
+    /// 开工（`InstallVersion` / `CreateInstance`）与取消都 +1：还在飞的后台线程把事件带回来时
+    /// 一眼能看出「这是旧任务的」，于是既不会被取消掉的安装重新点亮面板，也不会串到下一轮安装
+    /// （两轮安装同时存在时，旧任务的事件曾经把新任务的进度条顶掉）。
+    install_epoch: u64,
+}
+
+impl CoreHost {
+    /// 按便携数据根装配；解析不出数据根返回 `None`（调用方退回 mock）。
+    pub fn open() -> Option<Self> {
+        HostEnv::resolve().map(Self::new)
+    }
+
+    /// 用给定环境装配（截图/单测通道）。
+    pub fn new(env: HostEnv) -> Self {
+        Self::build(env, true)
+    }
+
+    /// 单测用：不跑 `refresh_all`（不起版本清单网络线程），其余装配一致。
+    #[cfg(test)]
+    pub(crate) fn headless(env: HostEnv) -> Self {
+        Self::build(env, false)
+    }
+
+    fn build(env: HostEnv, refresh: bool) -> Self {
+        let (tx, rx) = job::channel();
+        game::ensure_root(&env);
+        let mut host = Self {
+            env,
+            events: VecDeque::new(),
+            tx,
+            rx,
+            ticks: 0,
+            active_account: None,
+            accounts: Vec::new(),
+            login: None,
+            authlib: None,
+            skins: BTreeMap::new(),
+            skin_requested: BTreeSet::new(),
+            java_chain: Vec::new(),
+            java_busy: false,
+            java_message: String::new(),
+            install: None,
+            notices: Vec::new(),
+            launches: Vec::new(),
+            pending: BTreeSet::new(),
+            failed: BTreeMap::new(),
+            tail: logs::Tail::default(),
+            chat: MockBackend::default(),
+            install_cancel: None,
+            install_epoch: 0,
+        };
+        if refresh {
+            host.refresh_all();
+        }
+        // M109：CF 源可用与否只在装配时打一行（**不含密钥内容**，见 `addon` 模块文档）。
+        addon::log_curseforge_state();
+        host
+    }
+
+    /// 数据根（截图/诊断展示用）。
+    pub fn env(&self) -> &HostEnv {
+        &self.env
+    }
+
+    fn send(&mut self, event: CoreEvent) {
+        self.events.push_back(AppEvent::Core(event));
+    }
+
+    /// 开一轮安装：代次 +1 并把新代次交出去（后台线程随每条进度带回来）。
+    ///
+    /// 返回**新**代次而不是旧代次：调用方拿它去 `spawn_install`，于是「谁是新任务」只有一处答案。
+    fn next_install_epoch(&mut self) -> u64 {
+        self.install_epoch = self.install_epoch.wrapping_add(1);
+        self.install_epoch
+    }
+
+    fn toast(&mut self, kind: ToastKind, text: impl Into<String>) {
+        self.events.push_back(AppEvent::Toast(Toast {
+            id: 0,
+            kind,
+            text: text.into(),
+            remaining_ms: 0,
+        }));
+    }
+
+    /// 全量刷新：实例 / 会话 / 账户 / 设置 / Java，并触发一次版本清单拉取。
+    pub fn refresh_all(&mut self) {
+        self.refresh_instances();
+        self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+        self.refresh_accounts();
+        self.send(CoreEvent::SettingsChanged(settings::groups(&self.env)));
+        self.refresh_java();
+        versions::spawn_list(self.env.clone(), self.tx.clone());
+    }
+
+    /// 重建实例快照，并把**真实运行时**盖回去。
+    ///
+    /// `game::instances` 只读盘（每条都是 `Idle`），所以在跑的实例必须在重建后按
+    /// host 自己的启动表覆写 `Running{pid}`/`Busy`，否则任意一次刷新（装版本成功、
+    /// 加删账户、另一实例收尾）都会把磁贴打回 Idle：停止键与「运行中」条消失，
+    /// 进程还在跑却再也停不下来。
+    fn refresh_instances(&mut self) {
+        let mut instances = game::instances(&self.env);
+        for instance in &mut instances {
+            if let Some(live) = self
+                .launches
+                .iter()
+                .find(|live| live.instance == instance.id)
+            {
+                instance.runtime = InstanceRuntime::Running { pid: live.pid };
+            } else if self.pending.contains(&instance.id) {
+                instance.runtime = InstanceRuntime::Busy {
+                    stage: crate::dto::LaunchStage::Launch,
+                    progress: crate::dto::Progress { done: 0, total: 1 },
+                };
+            } else if let Some(reason) = self.failed.get(&instance.id) {
+                instance.runtime = InstanceRuntime::Failed {
+                    reason: reason.clone(),
+                };
+            }
+        }
+        self.send(CoreEvent::InstancesChanged(instances));
+    }
+
+    fn refresh_java(&mut self) {
+        let page = java::page(
+            &self.env,
+            self.java_chain.clone(),
+            self.java_busy,
+            &self.java_message,
+        );
+        self.send(CoreEvent::JavaChanged(page));
+    }
+
+    fn push_notice(&mut self, notice: NoticeView) {
+        self.notices.retain(|existing| existing.id != notice.id);
+        self.notices.push(notice);
+        self.send(CoreEvent::NoticesChanged(self.notices.clone()));
+    }
+
+    /// 打开一个会话（日志行 + 诊断）。
+    fn open_session(&mut self, id: &str) {
+        let (lines, diagnosis) = logs::open(&self.env, id);
+        self.send(CoreEvent::LogLinesChanged(lines));
+        self.send(CoreEvent::DiagnosisReady(diagnosis.unwrap_or(
+            DiagnosisReport {
+                session: id.to_string(),
+                diagnosis: crate::dto::Diagnosis {
+                    rule: String::new(),
+                    title: "该会话没有命中已知规则".to_string(),
+                    confidence: 0,
+                    hint: "可点「让 AI 详解」把日志交给模型进一步分析".to_string(),
+                    fix: None,
+                },
+            },
+        )));
+    }
+
+    /// 由实例名/版本 id 找启动目标。
+    fn launch_target(&self, id: &str) -> Option<launch::LaunchTarget> {
+        let instance = game::instances(&self.env)
+            .into_iter()
+            .find(|instance| instance.id == id || instance.name == id)?;
+        Some(launch::LaunchTarget {
+            id: instance.id,
+            name: instance.name,
+            version_id: instance.version_id,
+            account: self.active_account.clone(),
+        })
+    }
+
+    /// 某实例是否已在启动/运行（`pending` 与 `launches` 的并集）。
+    ///
+    /// 只查 `launches` 不够：`launch::start` 到后台线程回报 `LaunchStarted` 之间有窗口，
+    /// 这期间重复点启动会起第二个进程、并把旧 pid 在启动表里顶掉（旧进程变孤儿）。
+    fn in_flight(&self, key: &str) -> bool {
+        self.pending.contains(key) || self.launches.iter().any(|live| live.instance == key)
+    }
+
+    /// 标记「已受理、等后台线程回报」（`launch::start` 之后的窗口）。
+    ///
+    /// 单测也走这个入口而不是直接改 `pending`，保证测的是真实状态流转。
+    fn mark_pending(&mut self, id: &str) {
+        self.pending.insert(id.to_string());
+        self.failed.remove(id);
+    }
+
+    fn start_launch(&mut self, id: &str) {
+        if self.in_flight(id) {
+            self.toast(ToastKind::Warn, "这个实例已经在启动/运行中");
+            return;
+        }
+        let Some(target) = self.launch_target(id) else {
+            self.toast(ToastKind::Error, format!("找不到实例 {id}"));
+            return;
+        };
+        let instance_id = target.id.clone();
+        if self.in_flight(&instance_id) {
+            self.toast(ToastKind::Warn, "这个实例已经在启动/运行中");
+            return;
+        }
+        self.mark_pending(&instance_id);
+        if let Some(notice) = game::mode_change_notice(&self.env, &instance_id) {
+            self.push_notice(notice);
+        }
+        self.send(CoreEvent::InstanceRuntimeChanged {
+            id: instance_id.clone(),
+            runtime: InstanceRuntime::Busy {
+                stage: crate::dto::LaunchStage::Launch,
+                progress: crate::dto::Progress { done: 0, total: 1 },
+            },
+        });
+        launch::start(self.env.clone(), self.tx.clone(), target);
+    }
+
+    /// 某实例在跑的 pid（按实例 id 查启动表；不再有「最近一次启动」这种单槽）。
+    ///
+    /// 兜底分支读实例快照的 `Running { pid }`：host 自己发的运行时事件会写回快照，
+    /// 但快照是重建的（`game::instances` 每次 Idle），所以这层只是给将来留的口。
+    fn running_pid(&self, id: &str) -> Option<u32> {
+        if let Some(live) = self.launches.iter().find(|live| live.instance == id) {
+            return Some(live.pid);
+        }
+        game::instances(&self.env)
+            .into_iter()
+            .find(|instance| instance.id == id)
+            .and_then(|instance| match instance.runtime {
+                InstanceRuntime::Running { pid } => Some(pid),
+                _ => None,
+            })
+    }
+}
+
+impl Backend for CoreHost {
+    fn drain_events(&mut self) -> Vec<AppEvent> {
+        self.events.drain(..).collect()
+    }
+
+    fn dispatch(&mut self, command: AppCommand) {
+        self.dispatch_command(command);
+    }
+
+    fn tick(&mut self, elapsed: Duration) {
+        self.chat.tick(elapsed);
+        for event in self.chat.drain_events() {
+            self.events.push_back(event);
+        }
+        for _ in 0..MAX_TASKS_PER_TICK {
+            let Ok(task) = self.rx.try_recv() else {
+                break;
+            };
+            self.handle(task);
+        }
+        self.ticks += 1;
+        if self.ticks.is_multiple_of(TAIL_POLL_TICKS) {
+            self.poll_tail();
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "cancel_tests.rs"]
+mod cancel_tests;
+#[cfg(test)]
+#[path = "launch_state_tests.rs"]
+mod launch_state_tests;

crates/presenter/src/host/opener.rs

@@ -0,0 +1,72 @@
+//! 用系统默认浏览器打开授权 URL（授权码流唯一需要宿主做的事）。
+//!
+//! core 只负责拼授权 URL 与等本地回调（`core::auth::microsoft::authcode`）；
+//! 「谁来打开浏览器」是宿主的决定：GUI 走这里，CLI/无浏览器场景仍用设备码流。
+//!
+//! 平台差异收在 [`launcher`] 一处，不往业务代码里散写 `cfg` 补丁（`AGENTS.md` §7）。
+
+use std::process::Command;
+
+/// 拉起系统默认浏览器打开 `url`（只接受 http/https）。
+///
+/// 不等待浏览器退出：用户可能在浏览器里停留几分钟，宿主只关心「有没有拉起来」。
+///
+/// # Errors
+///
+/// URL 不是 http/https，或进程拉不起来时返回用户可读文案。
+pub fn open_url(url: &str) -> Result<(), String> {
+    if !url.starts_with("https://") && !url.starts_with("http://") {
+        return Err(format!("不是可打开的网址：{url}"));
+    }
+    let (program, args) = launcher(url);
+    Command::new(program)
+        .args(args)
+        .spawn()
+        .map(|_child| ())
+        .map_err(|error| format!("拉起浏览器失败（{program}）：{error}"))
+}
+
+#[cfg(target_os = "windows")]
+fn launcher(url: &str) -> (&'static str, Vec<String>) {
+    // `rundll32` 不用 shell，URL 里的 `&` 不会被当成命令分隔符（`cmd /C start` 会）。
+    (
+        "rundll32",
+        vec!["url.dll,FileProtocolHandler".to_string(), url.to_string()],
+    )
+}
+
+#[cfg(target_os = "macos")]
+fn launcher(url: &str) -> (&'static str, Vec<String>) {
+    ("open", vec![url.to_string()])
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+fn launcher(url: &str) -> (&'static str, Vec<String>) {
+    ("xdg-open", vec![url.to_string()])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{launcher, open_url};
+
+    #[test]
+    fn rejects_non_http_urls() {
+        assert!(open_url("javascript:alert(1)").is_err());
+        assert!(open_url("").is_err());
+        // 合法 URL 只验命令形态，不在单测里真去拉浏览器。
+        let (program, args) = launcher("http://localhost:1234/auth?code=a&state=b");
+        assert!(!program.is_empty());
+        assert!(args
+            .iter()
+            .any(|arg| arg.contains("http://localhost:1234/auth")));
+    }
+
+    #[cfg(target_os = "windows")]
+    #[test]
+    fn windows_uses_the_file_protocol_handler() {
+        let (program, args) = launcher("https://example.invalid/");
+        assert_eq!(program, "rundll32");
+        assert_eq!(args[0], "url.dll,FileProtocolHandler");
+        assert_eq!(args[1], "https://example.invalid/");
+    }
+}

crates/presenter/src/host/settings.rs

@@ -0,0 +1,399 @@
+//! 设置页分组：按 `core::setting` schema 的键生成行，写回走 `SettingStore::set`。
+//!
+//! 三件纪律（AGENTS §6）：
+//! 1. 读写同一份 `<数据根>/config/launcher.json`（与 `ull config set` / AI `set_config` 同源）；
+//! 2. 不自己拼 JSON，也不绕 schema（非法键/越界值由 `store.set` 拒绝）；
+//! 3. 这里只认「键名 + 字符串值」，领域语义留在 core。
+//!
+//! 分组 id 与设置页子导航同名：`download` / `java` / `data` / `ai` / `mcp`。
+
+use serde_json::Value;
+use unlucky_core::game::java::JdkVendor;
+use unlucky_core::setting::spec::ValueKind;
+
+use crate::dto::{SettingGroupView, SettingRowView};
+
+use super::env::HostEnv;
+
+/// 全部设置分组（设置页右栏一次拿全，切分组不再请求）。
+pub fn groups(env: &HostEnv) -> Vec<SettingGroupView> {
+    vec![
+        download_group(env),
+        java_group(env),
+        data_group(env),
+        ai_group(env),
+        mcp_group(env),
+    ]
+}
+
+/// 读一个键的字符串值（缺省给空串）。
+fn text(env: &HostEnv, key: &str) -> String {
+    env.store()
+        .doc()
+        .effective_str(key)
+        .unwrap_or_default()
+        .to_string()
+}
+
+/// 读一个键的整数（缺省给 `fallback`）。
+fn int(env: &HostEnv, key: &str, fallback: i64) -> i64 {
+    env.store()
+        .effective(key)
+        .and_then(Value::as_i64)
+        .unwrap_or(fallback)
+}
+
+/// 读一个键的布尔（缺省给 `fallback`）。
+fn flag(env: &HostEnv, key: &str, fallback: bool) -> bool {
+    env.store()
+        .effective(key)
+        .and_then(Value::as_bool)
+        .unwrap_or(fallback)
+}
+
+/// 枚举值在选项表里的序号（找不到给 0）。
+fn selected(options: &[&str], value: &str) -> i32 {
+    options
+        .iter()
+        .position(|option| *option == value)
+        .map(|index| i32::try_from(index).unwrap_or(0))
+        .unwrap_or(0)
+}
+
+/// 下载（D7）：并发/重试/地区/镜像偏好/代理。
+fn download_group(env: &HostEnv) -> SettingGroupView {
+    let concurrency = int(env, "download.concurrency", 8).to_string();
+    let retry = int(env, "download.retry_limit", 3).to_string();
+    let concurrency_options = ["4", "8", "16"];
+    let retry_options = ["0", "1", "3", "5"];
+    let regions = ["auto", "cn", "global"];
+    let mirrors = ["auto", "official", "mirror"];
+    let proxies = ["none", "system", "manual"];
+    let region_value = text(env, "download.region");
+    let mirror_value = text(env, "download.mirror_preference");
+    let proxy_value = text(env, "download.proxy_mode");
+    SettingGroupView::new("download", "下载与镜像（D7）")
+        .with(SettingRowView::choice(
+            "download.concurrency",
+            "并发数",
+            "同时下载的文件数（海量小文件，16 路足够压满带宽）",
+            &concurrency_options,
+            selected(&concurrency_options, &concurrency),
+        ))
+        .with(SettingRowView::choice(
+            "download.retry_limit",
+            "单文件重试次数",
+            "失败后换源重试的上限",
+            &retry_options,
+            selected(&retry_options, &retry),
+        ))
+        .with(SettingRowView::choice(
+            "download.region",
+            "地区判定",
+            "auto = 时区+语言+探测；决定是否优先国内镜像",
+            &regions,
+            selected(
+                &regions,
+                if region_value.is_empty() {
+                    "auto"
+                } else {
+                    &region_value
+                },
+            ),
+        ))
+        .with(SettingRowView::choice(
+            "download.mirror_preference",
+            "镜像偏好",
+            "auto = 按健康度评分；official = 官方源优先",
+            &mirrors,
+            selected(
+                &mirrors,
+                if mirror_value.is_empty() {
+                    "auto"
+                } else {
+                    &mirror_value
+                },
+            ),
+        ))
+        .with(SettingRowView::choice(
+            "download.proxy_mode",
+            "代理模式",
+            "none / system（跟随系统）/ manual（下面填地址）",
+            &proxies,
+            selected(
+                &proxies,
+                if proxy_value.is_empty() {
+                    "none"
+                } else {
+                    &proxy_value
+                },
+            ),
+        ))
+        .with(SettingRowView::text(
+            "download.proxy_url",
+            "HTTP 代理",
+            "manual 模式生效；留空则用系统代理",
+            &text(env, "download.proxy_url"),
+        ))
+        .with(SettingRowView::action(
+            "download.action.detect_region",
+            "重新检测地区",
+            "清掉 24h 地区缓存，下次下载重新判定",
+            "detect_region",
+        ))
+}
+
+/// Java（D13/D23）：自动安装/内存/选路/发行版优先级。
+fn java_group(env: &HostEnv) -> SettingGroupView {
+    let memory = int(env, "java.default_memory_mb", 2048).to_string();
+    let memory_options = ["1024", "2048", "4096", "8192"];
+    let priority: Vec<String> = env
+        .store()
+        .effective("java.vendorPriority")
+        .and_then(Value::as_array)
+        .map(|items| {
+            items
+                .iter()
+                .filter_map(Value::as_str)
+                .map(str::to_string)
+                .collect()
+        })
+        .unwrap_or_default();
+    let priority_text = if priority.is_empty() {
+        "地区默认序（Temurin → …）".to_string()
+    } else {
+        priority.join(" → ")
+    };
+    let roots = super::engine::java_scan_roots(env);
+    SettingGroupView::new("java", "Java（D13）")
+        .with(SettingRowView::toggle(
+            "java.auto_install",
+            "缺 Java 时自动下载",
+            "按回退链装一个托管 JDK（基准 JDK17）",
+            flag(env, "java.auto_install", true),
+        ))
+        .with(SettingRowView::choice(
+            "java.default_memory_mb",
+            "默认最大堆内存",
+            "实例没单独指定时用这个值（MB）",
+            &memory_options,
+            selected(&memory_options, &memory),
+        ))
+        .with(SettingRowView::text(
+            "java.selected_path",
+            "指定 Java 可执行文件",
+            "留空 = 自动挑（托管 > JAVA_HOME > PATH）",
+            &text(env, "java.selected_path"),
+        ))
+        .with(SettingRowView::text(
+            "java.installRoot",
+            "托管 JDK 安装根",
+            "留空 = 按数据目录模式派生（portable 进数据根 / standard 进系统目录）",
+            &text(env, "java.installRoot"),
+        ))
+        .with(SettingRowView::text(
+            "java.extra_args",
+            "附加 JVM 参数",
+            "原样拼到命令行尾部",
+            &text(env, "java.extra_args"),
+        ))
+        .with(SettingRowView::read_only(
+            "发行版优先级（java.vendorPriority）",
+            &priority_text,
+        ))
+        .with(SettingRowView::read_only(
+            "托管根",
+            &roots
+                .iter()
+                .map(|root| root.display().to_string())
+                .collect::<Vec<_>>()
+                .join(" · "),
+        ))
+}
+
+/// 数据目录（D6 三模式）。
+fn data_group(env: &HostEnv) -> SettingGroupView {
+    let modes = ["portable", "standard", "custom"];
+    let mode = env.mode().as_str().to_string();
+    SettingGroupView::new("data", "数据目录（D6 三模式）")
+        .with(SettingRowView::choice(
+            "core.data_mode",
+            "存储模式",
+            "便携（运行目录）/ 标准（系统应用数据目录）/ 自定义",
+            &modes,
+            selected(&modes, &mode),
+        ))
+        .with(SettingRowView::text(
+            "core.data_custom_root",
+            "自定义根目录",
+            "custom 模式生效（绝对路径）",
+            &text(env, "core.data_custom_root"),
+        ))
+        .with(SettingRowView::read_only(
+            "启动器数据目录",
+            &env.data.launcher_home.display().to_string(),
+        ))
+        .with(SettingRowView::read_only(
+            "游戏目录",
+            &env.data.game_home.display().to_string(),
+        ))
+        .with(SettingRowView::read_only(
+            "生效模式",
+            &format!("{}（改数据根需重启启动器）", env.mode()),
+        ))
+}
+
+/// AI（D4）：开关/端点/模型/YOLO。
+fn ai_group(env: &HostEnv) -> SettingGroupView {
+    let providers = ["openai_compatible", "anthropic", "ollama"];
+    let provider = text(env, "ai.provider");
+    SettingGroupView::new("ai", "AI 助手（D4）")
+        .with(SettingRowView::toggle(
+            "ai.enabled",
+            "启用 AI 助手",
+            "关闭后规则引擎诊断仍可用",
+            flag(env, "ai.enabled", true),
+        ))
+        .with(SettingRowView::choice(
+            "ai.provider",
+            "模型端点",
+            "OpenAI 兼容（含本地 llama.cpp）/ Anthropic / Ollama",
+            &providers,
+            selected(
+                &providers,
+                if provider.is_empty() {
+                    "openai_compatible"
+                } else {
+                    &provider
+                },
+            ),
+        ))
+        .with(SettingRowView::text(
+            "ai.base_url",
+            "端点 base_url",
+            "如 http://127.0.0.1:8080/v1",
+            &text(env, "ai.base_url"),
+        ))
+        .with(SettingRowView::text(
+            "ai.model",
+            "模型名",
+            "如 deepseek-chat",
+            &text(env, "ai.model"),
+        ))
+        .with(SettingRowView::toggle(
+            "ai.yolo",
+            "YOLO 模式",
+            "跳过确认弹窗（审计照记；账户/凭据操作永不 YOLO）",
+            flag(env, "ai.yolo", false),
+        ))
+}
+
+/// M39 的对外 MCP server（默认关、默认只读）。
+fn mcp_group(env: &HostEnv) -> SettingGroupView {
+    let port = int(env, "agent.mcp.port", 47_823);
+    SettingGroupView::new("mcp", "MCP server（M39）")
+        .with(SettingRowView::toggle(
+            "agent.mcp.enabled",
+            "对外提供 MCP server",
+            "127.0.0.1 上的 Streamable HTTP（stdio 需显式启动）",
+            flag(env, "agent.mcp.enabled", false),
+        ))
+        .with(SettingRowView::text(
+            "agent.mcp.port",
+            "端口",
+            "1024~65535，只绑 127.0.0.1",
+            &port.to_string(),
+        ))
+        .with(SettingRowView::toggle(
+            "agent.mcp.allow_write",
+            "允许外部客户端写配置",
+            "默认只读；写仍受 schema 白名单与分级确认约束",
+            flag(env, "agent.mcp.allow_write", false),
+        ))
+        .with(SettingRowView::read_only(
+            "客户端地址",
+            &format!("http://127.0.0.1:{port}/mcp（令牌见 agent.mcp.token，AI 不可写）"),
+        ))
+}
+
+/// 写一条设置。`value` 是字符串形态，按 schema 键的类型转换后交 `store.set`。
+///
+/// # Errors
+///
+/// 未知键、值类型不符、越界、落盘失败时返回用户可读文案。
+pub fn set(env: &HostEnv, key: &str, value: &str) -> Result<(), String> {
+    if key == "download.action.detect_region" {
+        return detect_region(env);
+    }
+    let parsed = parse_value(key, value)?;
+    let mut store = env.store();
+    store
+        .set(key, parsed)
+        .map_err(|error| format!("设置 {key} 失败：{error}"))?;
+    store
+        .save()
+        .map_err(|error| format!("保存设置失败：{error}"))?;
+    Ok(())
+}
+
+/// 键 → 正确类型的 JSON 值（schema 会再校验范围/枚举）。
+///
+/// **按 schema 的 `ValueKind` 取类型，不硬编码键名**（复审 P1-1）：原先是「硬编码 Int/Bool
+/// 键名，其余当字符串」，于是 `appearance.window_opacity`（Float）被当 String 送进 `store.set`，
+/// schema 的 `as_f64()` 返回 `None` ⇒ `InvalidValue` ⇒ **`save()` 不执行**（重启回旧值 + 弹 toast）。
+/// 现在新增任何 Float/Int/Bool 键都自动正确；集合级守门是
+/// `every_float_key_in_the_schema_can_be_written_back`。
+fn parse_value(key: &str, value: &str) -> Result<Value, String> {
+    let schema = unlucky_core::setting::keys::launcher_schema();
+    let Some(spec) = schema.spec(key) else {
+        // 未知键：原样交下去，由 `store.set` 用 schema 报「未知键」（这里不猜类型）。
+        return Ok(Value::String(value.to_string()));
+    };
+
+    let trimmed = value.trim();
+    match &spec.kind {
+        ValueKind::Bool => match trimmed.to_ascii_lowercase().as_str() {
+            "1" | "true" | "on" | "yes" => Ok(Value::Bool(true)),
+            "0" | "false" | "off" | "no" => Ok(Value::Bool(false)),
+            _ => Err(format!("{key} 需要布尔值：{value}")),
+        },
+        ValueKind::Int { .. } => trimmed
+            .parse::<i64>()
+            .map(Value::from)
+            .map_err(|_| format!("{key} 需要整数：{value}")),
+        ValueKind::Float { .. } => match trimmed.parse::<f64>() {
+            Ok(number) if number.is_finite() => Ok(Value::from(number)),
+            _ => Err(format!("{key} 需要有限数字：{value}")),
+        },
+        // 文本 / 枚举 / 路径 / 列表 / 任意 JSON：字符串原样交下去（越界与词表由 schema 判）。
+        _ => Ok(Value::String(value.to_string())),
+    }
+}
+
+/// 清掉 24h 地区缓存（下次建引擎重新判定）。
+fn detect_region(env: &HostEnv) -> Result<(), String> {
+    let path = env.layout.cache().join("region.json");
+    if path.is_file() {
+        std::fs::remove_file(&path).map_err(|error| format!("清地区缓存失败：{error}"))?;
+    }
+    Ok(())
+}
+
+/// 设置页「重置发行版优先级」用（清空 enum_list）。
+///
+/// # Errors
+///
+/// 落盘失败时返回用户可读文案。
+pub fn clear_vendor_priority(env: &HostEnv) -> Result<(), String> {
+    let mut store = env.store();
+    store
+        .set("java.vendorPriority", Value::Array(Vec::new()))
+        .and_then(|()| store.save())
+        .map_err(|error| format!("清空发行版优先级失败：{error}"))?;
+    let _ = JdkVendor::ALL;
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "settings_tests.rs"]
+mod tests;

crates/presenter/src/host/settings_tests.rs

@@ -0,0 +1,163 @@
+//! host/settings.rs 的单测（拆文件守 400 行上限）。
+
+use super::*;
+
+fn env_in(dir: &std::path::Path) -> HostEnv {
+    std::fs::create_dir_all(dir.join(".ULL/config")).expect("config");
+    HostEnv::at_root(dir)
+}
+
+#[test]
+fn groups_cover_the_six_required_areas() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+    let groups = groups(&env);
+    let ids: Vec<&str> = groups.iter().map(|group| group.id.as_str()).collect();
+    assert_eq!(ids, vec!["download", "java", "data", "ai", "mcp"]);
+    let keys: Vec<&str> = groups
+        .iter()
+        .flat_map(|group| group.rows.iter())
+        .map(|row| row.key.as_str())
+        .collect();
+    for key in [
+        "download.region",
+        "download.mirror_preference",
+        "java.default_memory_mb",
+        "core.data_mode",
+        "agent.mcp.enabled",
+        "agent.mcp.port",
+        "ai.base_url",
+    ] {
+        assert!(keys.contains(&key), "缺少 {key}");
+    }
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn set_parses_types_and_persists() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-w-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+
+    set(&env, "download.concurrency", "16").expect("写并发");
+    set(&env, "agent.mcp.enabled", "true").expect("写开关");
+    set(&env, "agent.mcp.port", "48000").expect("写端口");
+    set(&env, "download.region", "cn").expect("写地区");
+
+    let groups = groups(&env);
+    let row = |key: &str| {
+        groups
+            .iter()
+            .flat_map(|g| g.rows.iter())
+            .find(|r| r.key == key)
+            .cloned()
+    };
+    assert_eq!(row("download.concurrency").unwrap().selected, 2);
+    assert!(row("agent.mcp.enabled").unwrap().flag);
+    assert_eq!(row("agent.mcp.port").unwrap().value_text, "48000");
+    assert_eq!(row("download.region").unwrap().selected, 1);
+
+    assert!(set(&env, "download.concurrency", "abc").is_err());
+    assert!(set(&env, "agent.mcp.enabled", "maybe").is_err());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn detect_region_action_removes_cache() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-r-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+    let path = env.layout.cache().join("region.json");
+    std::fs::create_dir_all(env.layout.cache()).expect("cache");
+    std::fs::write(&path, "{}").expect("写缓存");
+    set(&env, "download.action.detect_region", "").expect("检测");
+    assert!(!path.exists());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// **P1-1 的回归**：整窗透明度是 `ValueKind::Float` 的键，`SetSetting` 的载荷是字符串。
+///
+/// 历史（复审 r1 P1-1）：`parse_value` 只认硬编码的 Int/Bool 键名，Float 键被当成字符串交给
+/// `store.set`，schema 的 `as_f64()` 对 String 返回 None ⇒ `InvalidValue` ⇒ **`save()` 不执行**，
+/// 于是 α 只在内存生效、重启回旧值，且每次拖动弹一条 Error toast。
+///
+/// 抓得住：`set` → 落盘 → **新开一个 store（= 模拟重启）** 读回同一值。
+/// 抓不住：UI 侧是否真的把滑块接到 `SetSetting`（由 `app` 侧的 `on_appearance` 测试管）。
+#[test]
+fn float_key_round_trips_through_set_setting() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-float-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+
+    set(&env, "appearance.window_opacity", "0.8").expect("写整窗透明度");
+    set(&env, "appearance.panel_alpha", "0.55").expect("写面板透明度");
+
+    // 新开一个 store：从磁盘重新加载（等价「重启进程」）。
+    let reopened = env.store();
+    assert_eq!(
+        reopened.doc().effective_f64("appearance.window_opacity"),
+        Some(0.8)
+    );
+    assert_eq!(
+        reopened.doc().effective_f64("appearance.panel_alpha"),
+        Some(0.55)
+    );
+
+    // 越界仍然被 schema 拒绝（钳位在 core 的读侧，写侧是拒绝）。
+    assert!(set(&env, "appearance.window_opacity", "0.0").is_err());
+    // 非数字报人话，而不是「期望数字，实际是 \"abc\"」这种 schema 原话。
+    assert!(set(&env, "appearance.window_opacity", "abc").is_err());
+    assert!(set(&env, "appearance.window_opacity", "NaN").is_err());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// **集合级守门（复审 P1-1 要求的那条）**：schema 里**每一个** `ValueKind::Float` 的键都必须
+/// 能被 `SetSetting` 写回，而不只是 `window_opacity`。
+///
+/// 为什么这条比单键测试重要：下次谁再加一个 Float 键（比如玻璃强度、模糊半径），
+/// 只要 `parse_value` 又退化成「硬编码表」，这里立刻红——单键测试抓不住新键。
+///
+/// 抓得住：类型解析与 `save()` 是否真的执行（读回是**新开 store**，走磁盘）。
+/// 抓不住：UI 控件是否接上了这些键（那是各页面的接线测试）。
+#[test]
+fn every_float_key_in_the_schema_can_be_written_back() {
+    let dir =
+        std::env::temp_dir().join(format!("ull-host-settings-allfloat-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+
+    let schema = unlucky_core::setting::keys::launcher_schema();
+    let mut checked = 0_usize;
+    for spec in schema.specs() {
+        let unlucky_core::setting::spec::ValueKind::Float { min, max } = spec.kind else {
+            continue;
+        };
+        // 取一个落在 [min, max] 内的值（0.5 是多数区间的好选择，落不进时取中点）。
+        let target = if (min..=max).contains(&0.5) {
+            0.5
+        } else {
+            (min + max) / 2.0
+        };
+        set(&env, spec.key, &format!("{target}"))
+            .unwrap_or_else(|error| panic!("Float 键 {} 写不回：{error}", spec.key));
+        let reread = env
+            .store()
+            .doc()
+            .effective_f64(spec.key)
+            .unwrap_or_else(|| panic!("Float 键 {} 写完后读不到", spec.key));
+        assert!(
+            (reread - target).abs() < 1e-9,
+            "Float 键 {} 写 {target} 读回 {reread}",
+            spec.key
+        );
+        checked += 1;
+    }
+
+    assert!(
+        checked >= 3,
+        "schema 里 Float 键只剩 {checked} 个：本断言要求 ≥3（window_opacity / panel_alpha / bg_dim / ui.scale）。\
+         若是有意删减，请同步更新这条断言"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}

crates/presenter/src/host/versions.rs

@@ -0,0 +1,173 @@
+//! 版本清单（下载页）：远端 manifest（12h 缓存）+ 内嵌 unlisted 清单 → 分类好的行。
+//!
+//! 分类口径抄 analyse/03 §2.4：官方 `type` 决定 release/snapshot/远古；远古再按 id
+//! 前缀拆 classic（`rd-*`）/ old_alpha（`a*`）/ old_beta（`b*`），其余归 unlisted 汇总。
+//! 拉取失败但有旧缓存时用旧缓存（离线可用），全无才报错。
+
+use std::collections::BTreeSet;
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::game::install::RemoteSource;
+use unlucky_core::game::unlisted;
+use unlucky_core::game::version::{ReleaseType, RemoteVersion};
+
+use crate::dto::{AncientKind, VersionKind, VersionSummary};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 版本 id / 官方类型 → 下载页的四种归类。
+pub fn kind_of(id: &str, release_type: ReleaseType) -> VersionKind {
+    match release_type {
+        ReleaseType::Release => VersionKind::Release,
+        ReleaseType::Snapshot | ReleaseType::Pending | ReleaseType::Unobfuscated => {
+            VersionKind::Snapshot
+        }
+        ReleaseType::OldAlpha | ReleaseType::OldBeta | ReleaseType::Modified => {
+            VersionKind::Ancient(ancient_kind(id))
+        }
+        ReleaseType::Unknown => {
+            if id.starts_with("rd-") || id.starts_with("a") || id.starts_with("b") {
+                VersionKind::Ancient(ancient_kind(id))
+            } else {
+                VersionKind::Release
+            }
+        }
+    }
+}
+
+/// 远古版子类（`rd-*` → classic；`a1.*` → old_alpha；`b1.*` → old_beta；其余 unlisted）。
+pub fn ancient_kind(id: &str) -> AncientKind {
+    if id.starts_with("rd-") || id.starts_with("inf-") {
+        AncientKind::Classic
+    } else if id.starts_with("a1.") || id.starts_with("a0.") || id.starts_with('a') {
+        AncientKind::OldAlpha
+    } else if id.starts_with("b1.") || id.starts_with('b') {
+        AncientKind::OldBeta
+    } else {
+        AncientKind::Unlisted
+    }
+}
+
+/// 发布日期取 `releaseTime` 的日期部分（缺失时退回 `time`，再退回空串）。
+fn released_of(version: &RemoteVersion) -> String {
+    version
+        .release_time
+        .as_deref()
+        .or(version.time.as_deref())
+        .map(|text| text.get(..10).unwrap_or(text).to_string())
+        .unwrap_or_default()
+}
+
+/// 拉清单并翻译成 DTO（安装状态按盘上版本判定）。
+fn fetch(env: &HostEnv) -> Result<Vec<VersionSummary>, String> {
+    let engine = super::engine::engine(env);
+    let meta_cache = env.layout.meta_cache();
+    let now = now_ms();
+    let (mut list, _freshness) = block_on(async {
+        RemoteSource::new(&engine, &env.game, &meta_cache, now)
+            .manifest(false)
+            .await
+    })
+    .map_err(|error| format!("拉取版本清单失败：{error}"))?;
+    // 内嵌 unlisted 清单先合（同 id 先插入者胜），保证远古版显式可达（09 §G2）。
+    unlisted::merge_into(&mut list);
+    list.sort_newest_first();
+
+    let installed: BTreeSet<String> = env
+        .game
+        .installed_versions()
+        .unwrap_or_default()
+        .into_iter()
+        .collect();
+    Ok(list
+        .versions
+        .iter()
+        .map(|version| VersionSummary {
+            id: version.id.clone(),
+            kind: kind_of(&version.id, version.version_type),
+            released: released_of(version),
+            installed: installed.contains(&version.id),
+        })
+        .collect())
+}
+
+/// 后台拉清单（网络在后台线程里，UI 不卡）。
+pub fn spawn_list(env: HostEnv, tx: JobSender) {
+    spawn("versions", move || {
+        let result = fetch(&env);
+        let _ = tx.send(HostTask::Versions(result));
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn kinds_follow_official_types() {
+        assert_eq!(
+            kind_of("1.21.9", ReleaseType::Release),
+            VersionKind::Release
+        );
+        assert_eq!(
+            kind_of("1.21.9-pre3", ReleaseType::Snapshot),
+            VersionKind::Snapshot
+        );
+        assert_eq!(
+            kind_of("rd-132211", ReleaseType::OldAlpha),
+            VersionKind::Ancient(AncientKind::Classic)
+        );
+        assert_eq!(
+            kind_of("a1.1.1", ReleaseType::OldAlpha),
+            VersionKind::Ancient(AncientKind::OldAlpha)
+        );
+        assert_eq!(
+            kind_of("b1.7.3", ReleaseType::OldBeta),
+            VersionKind::Ancient(AncientKind::OldBeta)
+        );
+        assert_eq!(
+            kind_of("x-modified", ReleaseType::Modified),
+            VersionKind::Ancient(AncientKind::Unlisted)
+        );
+    }
+
+    #[test]
+    fn released_uses_date_part() {
+        let version = RemoteVersion {
+            id: "1.20.4".to_string(),
+            version_type: ReleaseType::Release,
+            url: String::new(),
+            time: None,
+            release_time: Some("2023-12-07T12:00:00+00:00".to_string()),
+            sha1: None,
+            size: None,
+        };
+        assert_eq!(released_of(&version), "2023-12-07");
+        let empty = RemoteVersion {
+            id: "x".to_string(),
+            version_type: ReleaseType::Unknown,
+            url: String::new(),
+            time: None,
+            release_time: None,
+            sha1: None,
+            size: None,
+        };
+        assert_eq!(released_of(&empty), "");
+    }
+
+    #[test]
+    fn unlisted_merge_keeps_ancient_versions_reachable() {
+        // core 的内嵌清单里一定有远古版（`rd-*` / `a1.*` / `b1.*`）
+        let mut list = unlucky_core::game::version::VersionList::default();
+        let added = unlisted::merge_into(&mut list);
+        assert!(added > 0, "内嵌 unlisted 清单不该为空");
+        assert!(
+            list.versions.iter().any(|v| v.id.starts_with("a1.")
+                || v.id.starts_with("b1.")
+                || v.id.starts_with("rd-")),
+            "远古版必须显式可达"
+        );
+    }
+}