release: v0.2.4 里程碑快照（孤儿提交，无父；树 = dev 68362e5）

本批内容见 CHANGELOG.md 的 0.2.4 段。按 D41 用孤儿快照推 main，保留「公开史只有里程碑」的模型。

crates/agent/Cargo.toml

@@ -0,0 +1,44 @@
+[package]
+name = "unlucky-agent"
+description = "Unlucky-Launcher AI Agent：工具注册表 + 内置客户端 + MCP server（双形态共用一个内核）"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 依赖方向：agent 依赖 core 的公共 API，core 不知道 agent 的存在（AGENTS.md §2）。
+# 端口层（src/port*.rs）让 agent 能在没有 core 实现时独立编译与测试；装配层用 core 实现
+# 填充 `Ports`（GUI 侧是 `crates/app`，headless 侧是 `crates/cli` 的 `ull agent serve`）。
+[dependencies]
+unlucky-core = { path = "../core", version = "0.2.4" }
+
+# 序列化：工具 JSON Schema 是手写 serde_json::Value（不引 schemars），
+# 工具结果 / 审计记录 / 事件流都用 serde derive。
+serde.workspace = true
+serde_json.workspace = true
+
+# LLM Provider + agent 循环。**锁精确版本**：rig 12 周 5 个 minor、CHANGELOG 满是 breaking
+# （DevDocs/PlanDoc/02-ai-agent-design.md §0 + research/02 §7 R1）。升级必须单独提交并跑回放回归。
+# 依赖面收口：整个 crate 只有 src/brain/rig.rs 允许 `use rig_*`。
+# feature `reqwest`：rig-core 0.45 的 default 只有 derive + rustls，HTTP 客户端要显式开；TLS 走 rustls
+# （免 OpenSSL，对 Win7/MinGW 友好，见 research/02 §7 R3）。
+rig-core = { version = "=0.45.0", features = ["reqwest"] }
+# TODO(M16-P1): 目前**声明但未使用**——对话循环/工具编排是自研的（要在中间插确认与审计）。
+# 保留是为了把版本按 02 §0 钉死；P1 接 rig 的 agent 运行时（工具服务句柄 / rig-cassette 回放 /
+# rig-rmcp 让内置 agent 吃 MCP）时再真正消费。若 P1 决定彻底不用，删这一行即可。
+rig-agent = "=0.45.0"
+
+# 异步运行时（rig 的 HTTP/流式需要）与流工具（消费 rig 的 Stream）。
+tokio.workspace = true
+futures-util.workspace = true
+
+# MCP server（M39）：rmcp 3.8 投影 + stdio / Streamable HTTP 传输。
+# 依赖面收口纪律与 rig 相同——整个 crate 只有 src/mcp/ 允许 `use rmcp::`。
+rmcp.workspace = true
+axum.workspace = true
+
+[lints]
+workspace = true

crates/agent/src/audit.rs

@@ -0,0 +1,283 @@
+//! 审计日志：**每一次工具调用**都留痕（02 文档 §3.1 末条 / mission M16 任务 4）。
+//!
+//! 落盘位置由装配处给（`<data_root>/agent/audit/audit-<日期>.jsonl`，按天分文件，
+//! 见 `PlanDoc/04-data-and-config.md` §2）。一行一条 JSON，只追加不修改。
+//!
+//! 三条纪律：
+//! 1. **参数先脱敏再落盘**（[`crate::redact::redact_args`]）——`set_config` 能改 AI 端点，
+//!    参数里会有 api_key；
+//! 2. 写失败**不打断**工具执行（审计是旁路），但要把失败打到 stderr 留痕；
+//! 3. YOLO 与「是否经确认」分别记录（`yolo=true, confirmed=false` 与
+//!    `yolo=false, confirmed=true` 是两件事，事故复盘的差别就在这）。
+
+use std::fs::OpenOptions;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use crate::clock::{date_of_unix_ms, format_unix_ms, SharedClock};
+use crate::redact::redact_args;
+
+/// 一次工具调用的结局（审计用）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AuditOutcome {
+    /// 成功返回。
+    Ok,
+    /// 工具返回错误（含端口失败、未找到会话等）。
+    ToolError,
+    /// 参数没过 schema 校验（模型给错了参数）。
+    InvalidArgs,
+    /// 用户/策略拒绝。
+    Denied,
+    /// 只发出了确认请求，尚未执行（编排层在把请求交给闸门之前先记一条，
+    /// 这样「AI 想改 X 但被拒」和「用户点了允许」在审计里是两条独立的证据）。
+    AwaitingConfirmation,
+    /// 模型调了不存在的工具。
+    UnknownTool,
+}
+
+/// 一条审计记录。
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct AuditRecord {
+    /// RFC3339 UTC。
+    pub ts: String,
+    /// 会话 id（agent 对话框的会话，不是游戏会话）。
+    pub agent_session_id: String,
+    /// 工具名。
+    pub tool: String,
+    /// 参数（已脱敏）。
+    pub args: Value,
+    /// 结局。
+    pub outcome: AuditOutcome,
+    /// 一句话结果摘要。
+    pub summary: String,
+    /// 是否运行在 YOLO 模式。
+    pub yolo: bool,
+    /// 是否经过用户确认（YOLO 下为 false——自动放行不是"确认"）。
+    pub confirmed: bool,
+    /// 工具执行耗时（毫秒）。
+    pub duration_ms: u64,
+}
+
+/// 审计出口。
+pub trait AuditSink: Send + Sync {
+    /// 记录一条（实现方不应阻塞工具执行链；失败自行吞掉并留痕）。
+    fn record(&self, record: &AuditRecord);
+}
+
+/// 按天滚动的 JSONL 审计（生产实现）。
+pub struct JsonlAudit {
+    dir: PathBuf,
+    clock: SharedClock,
+    guard: Mutex<()>,
+}
+
+impl JsonlAudit {
+    /// `dir` 通常是 `<data_root>/agent/audit`；目录按需创建。
+    #[must_use]
+    pub fn new(dir: impl Into<PathBuf>, clock: SharedClock) -> Self {
+        Self {
+            dir: dir.into(),
+            clock,
+            guard: Mutex::new(()),
+        }
+    }
+
+    /// 给定时刻对应的文件路径（测试与 UI「查看审计」共用）。
+    #[must_use]
+    pub fn path_for(&self, unix_ms: u64) -> PathBuf {
+        self.dir
+            .join(format!("audit-{}.jsonl", date_of_unix_ms(unix_ms)))
+    }
+
+    /// 追加一行；失败返回 `std::io::Error`（由 [`AuditSink::record`] 吞掉并打日志）。
+    fn append(&self, record: &AuditRecord) -> std::io::Result<()> {
+        let path = self.path_for(self.clock.now_unix_ms());
+        let line = serde_json::to_string(record)
+            .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        let _guard = self.guard.lock();
+        let mut file = OpenOptions::new().create(true).append(true).open(&path)?;
+        file.write_all(line.as_bytes())?;
+        file.write_all(b"\n")
+    }
+}
+
+impl AuditSink for JsonlAudit {
+    fn record(&self, record: &AuditRecord) {
+        if let Err(err) = self.append(record) {
+            // 审计是旁路：写不进去也不能让工具调用失败，但要留下痕迹。
+            eprintln!("[unlucky-agent] 审计写入失败: {err}");
+        }
+    }
+}
+
+/// 内存审计（测试 + 「P0 不落盘」的降级路径）。
+#[derive(Debug, Default)]
+pub struct MemoryAudit {
+    records: Mutex<Vec<AuditRecord>>,
+}
+
+impl MemoryAudit {
+    /// 空审计。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 已记录条数。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.records.lock().map(|r| r.len()).unwrap_or(0)
+    }
+
+    /// 是否一条都没有。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// 取快照。
+    #[must_use]
+    pub fn records(&self) -> Vec<AuditRecord> {
+        self.records.lock().map(|r| r.clone()).unwrap_or_default()
+    }
+
+    /// 按工具名筛出记录（测试断言用）。
+    #[must_use]
+    pub fn records_for(&self, tool: &str) -> Vec<AuditRecord> {
+        self.records()
+            .into_iter()
+            .filter(|r| r.tool == tool)
+            .collect()
+    }
+}
+
+impl AuditSink for MemoryAudit {
+    fn record(&self, record: &AuditRecord) {
+        if let Ok(mut records) = self.records.lock() {
+            records.push(record.clone());
+        }
+    }
+}
+
+/// 丢弃审计（不推荐，只给"连内存都不想留"的极端场景/基准测试）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NullAudit;
+
+impl AuditSink for NullAudit {
+    fn record(&self, _record: &AuditRecord) {}
+}
+
+/// 组装一条记录时的"其余字段"（时间戳从时钟取，参数先脱敏）。
+#[derive(Debug, Clone, Copy)]
+pub struct AuditDraft<'a> {
+    /// 工具名。
+    pub tool: &'a str,
+    /// 原始参数（内部会脱敏）。
+    pub args: &'a Value,
+    /// 结局。
+    pub outcome: AuditOutcome,
+    /// 一句话结果摘要。
+    pub summary: &'a str,
+    /// 是否 YOLO。
+    pub yolo: bool,
+    /// 是否经用户确认。
+    pub confirmed: bool,
+    /// 耗时（毫秒）。
+    pub duration_ms: u64,
+}
+
+/// 组装一条审计记录（时间戳从时钟取、参数脱敏，调用方不用自己拼）。
+#[must_use]
+pub fn make_record(
+    clock: &dyn crate::clock::Clock,
+    agent_session_id: &str,
+    draft: AuditDraft<'_>,
+) -> AuditRecord {
+    AuditRecord {
+        ts: format_unix_ms(clock.now_unix_ms()),
+        agent_session_id: agent_session_id.to_string(),
+        tool: draft.tool.to_string(),
+        args: redact_args(draft.args),
+        outcome: draft.outcome,
+        summary: draft.summary.to_string(),
+        yolo: draft.yolo,
+        confirmed: draft.confirmed,
+        duration_ms: draft.duration_ms,
+    }
+}
+
+/// 便捷：给出数据根下的审计目录（`<data_root>/agent/audit`）。
+#[must_use]
+pub fn audit_dir(data_root: &Path) -> PathBuf {
+    data_root.join("agent").join("audit")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::clock::FixedClock;
+    use serde_json::json;
+    use std::sync::Arc;
+
+    #[test]
+    fn record_redacts_args_before_store() {
+        let audit = MemoryAudit::new();
+        let clock = FixedClock::new(1_793_304_753_123);
+        let args = json!({ "path": "ai.api_key", "value": "sk-x" });
+        let rec = make_record(
+            &clock,
+            "s1",
+            AuditDraft {
+                tool: "set_config",
+                args: &args,
+                outcome: AuditOutcome::Ok,
+                summary: "ok",
+                yolo: false,
+                confirmed: true,
+                duration_ms: 3,
+            },
+        );
+        audit.record(&rec);
+        let stored = &audit.records()[0];
+        assert_eq!(stored.args["value"], json!("***"), "敏感路径的值必须掩码");
+        assert_eq!(stored.ts, "2026-10-29T20:12:33.123Z");
+    }
+
+    #[test]
+    fn jsonl_audit_writes_one_line_per_record_per_day() {
+        let dir = std::env::temp_dir().join(format!("unlucky-agent-audit-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let clock: SharedClock = Arc::new(FixedClock::new(1_793_304_753_123));
+        let audit = JsonlAudit::new(&dir, Arc::clone(&clock));
+        let args = json!({});
+        let rec = make_record(
+            clock.as_ref(),
+            "s1",
+            AuditDraft {
+                tool: "get_config",
+                args: &args,
+                outcome: AuditOutcome::Ok,
+                summary: "ok",
+                yolo: false,
+                confirmed: false,
+                duration_ms: 1,
+            },
+        );
+        audit.record(&rec);
+        audit.record(&rec);
+        let path = dir.join("audit-2026-10-29.jsonl");
+        let content = std::fs::read_to_string(&path).expect("审计文件应存在");
+        assert_eq!(content.lines().count(), 2);
+        let first: AuditRecord = serde_json::from_str(content.lines().next().unwrap()).unwrap();
+        assert_eq!(first.tool, "get_config");
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+}

crates/agent/src/brain/chat.rs

@@ -0,0 +1,267 @@
+//! 对话协议类型 + [`ChatProvider`] trait（四态端点配置在 [`super::provider`]）。
+//!
+//! 这里**没有协议方言**：OpenAI/Ollama/Anthropic 的报文差异全部由实现方
+//! （阶段 B 的 [`super::rig`]）吃掉。本模块只定义循环需要的三样东西：
+//! 消息、请求/回复、流式增量回调。
+//!
+//! 一次工具调用的完整往返：
+//! `Assistant { tool_calls }` → 编排层执行 → `Tool { call_id, name, content }` → 再次补全。
+
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use super::provider::{ProviderConfig, ProviderError};
+use crate::event::{AgentEvent, AgentEventSink};
+use crate::registry::ToolDefinition;
+
+/// 一条工具调用请求（模型产出）。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ToolCall {
+    /// 调用 id（OpenAI 方言的 `tool_call_id`；Ollama 原生没有 id，由适配层生成）。
+    pub id: String,
+    /// 工具名。
+    pub name: String,
+    /// 参数（JSON 对象）。
+    pub arguments: Value,
+}
+
+/// 对话消息。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "role", rename_all = "snake_case")]
+pub enum ChatMessage {
+    /// 系统提示词（每轮由 [`super::BrainConfig::system_prompt`] 重新注入，不进历史）。
+    System {
+        /// 提示词正文。
+        content: String,
+    },
+    /// 用户输入。
+    User {
+        /// 正文。
+        content: String,
+    },
+    /// 模型回复（可能带工具调用）。
+    Assistant {
+        /// 文本正文（工具调用轮可能为空）。
+        text: String,
+        /// 工具调用。
+        tool_calls: Vec<ToolCall>,
+    },
+    /// 工具结果回灌。
+    Tool {
+        /// 对应调用 id。
+        call_id: String,
+        /// 工具名（Ollama 原生靠 `tool_name` 配对，不是 id）。
+        name: String,
+        /// 结果 JSON 字符串。
+        content: String,
+    },
+}
+
+impl ChatMessage {
+    /// 便捷：系统消息。
+    #[must_use]
+    pub fn system(content: impl Into<String>) -> Self {
+        Self::System {
+            content: content.into(),
+        }
+    }
+
+    /// 便捷：用户消息。
+    #[must_use]
+    pub fn user(content: impl Into<String>) -> Self {
+        Self::User {
+            content: content.into(),
+        }
+    }
+
+    /// 便捷：工具结果消息。
+    #[must_use]
+    pub fn tool(
+        call_id: impl Into<String>,
+        name: impl Into<String>,
+        content: impl Into<String>,
+    ) -> Self {
+        Self::Tool {
+            call_id: call_id.into(),
+            name: name.into(),
+            content: content.into(),
+        }
+    }
+}
+
+/// 一次补全请求。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ChatRequest {
+    /// 模型名。
+    pub model: String,
+    /// 消息（system 在首位）。
+    pub messages: Vec<ChatMessage>,
+    /// 工具定义（双投影的 rig 侧载荷）。
+    pub tools: Vec<ToolDefinition>,
+    /// 采样温度。
+    pub temperature: Option<f32>,
+    /// token 上限。
+    pub max_tokens: Option<u32>,
+}
+
+/// token 用量（本地模型可能不报）。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Usage {
+    /// 输入 token。
+    pub prompt_tokens: Option<u32>,
+    /// 输出 token。
+    pub completion_tokens: Option<u32>,
+}
+
+/// 一次补全结果。
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct ChatReply {
+    /// 文本正文。
+    pub text: String,
+    /// 工具调用（非空 ⇒ 循环继续）。
+    pub tool_calls: Vec<ToolCall>,
+    /// 用量。
+    pub usage: Option<Usage>,
+}
+
+impl ChatReply {
+    /// 纯文本回复。
+    #[must_use]
+    pub fn text(text: impl Into<String>) -> Self {
+        Self {
+            text: text.into(),
+            tool_calls: Vec::new(),
+            usage: None,
+        }
+    }
+
+    /// 带工具调用的回复。
+    #[must_use]
+    pub fn with_tool_calls(tool_calls: Vec<ToolCall>) -> Self {
+        Self {
+            text: String::new(),
+            tool_calls,
+            usage: None,
+        }
+    }
+}
+
+/// 流式增量接收者。实现方必须**非阻塞**。
+pub trait DeltaObserver: Send + Sync {
+    /// 收到一段文本增量。
+    fn on_delta(&self, text: &str);
+}
+
+/// 丢弃增量（不关心流式的调用方）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoopObserver;
+
+impl DeltaObserver for NoopObserver {
+    fn on_delta(&self, _text: &str) {}
+}
+
+/// 把增量转成 [`AgentEvent::TextDelta`]（P1 聊天面板逐字渲染就靠它）。
+#[derive(Clone)]
+pub struct EventDeltaObserver {
+    sink: Arc<dyn AgentEventSink>,
+}
+
+impl EventDeltaObserver {
+    /// 用事件流构造。
+    #[must_use]
+    pub fn new(sink: Arc<dyn AgentEventSink>) -> Self {
+        Self { sink }
+    }
+}
+
+impl DeltaObserver for EventDeltaObserver {
+    fn on_delta(&self, text: &str) {
+        self.sink.emit(AgentEvent::TextDelta {
+            text: text.to_string(),
+        });
+    }
+}
+
+/// 收集增量（测试断言流式拼接）。
+#[derive(Debug, Default)]
+pub struct CollectingObserver {
+    chunks: std::sync::Mutex<Vec<String>>,
+}
+
+impl CollectingObserver {
+    /// 收完的内容。
+    #[must_use]
+    pub fn collected(&self) -> String {
+        self.chunks.lock().map(|c| c.concat()).unwrap_or_default()
+    }
+}
+
+impl DeltaObserver for CollectingObserver {
+    fn on_delta(&self, text: &str) {
+        if let Ok(mut chunks) = self.chunks.lock() {
+            chunks.push(text.to_string());
+        }
+    }
+}
+
+/// 补全未来的箱子类型。
+pub type ProviderFuture<'a> =
+    Pin<Box<dyn Future<Output = Result<ChatReply, ProviderError>> + Send + 'a>>;
+
+/// LLM 端点抽象：**这是 agent 唯一的异步边界**。
+///
+/// P0 实现 = 测试里的 mock；阶段 B 实现 = [`super::rig`] 的 rig 适配器。
+/// 换实现（genai / 自写循环）只需要满足本 trait，[`super::Brain`] 不动。
+pub trait ChatProvider: Send + Sync {
+    /// 当前配置（循环用它取 model/temperature，也用它判断是否启用）。
+    fn config(&self) -> &ProviderConfig;
+    /// 一次补全。流式增量通过 `observer` 回吐。
+    fn complete<'a>(
+        &'a self,
+        request: &'a ChatRequest,
+        observer: &'a dyn DeltaObserver,
+    ) -> ProviderFuture<'a>;
+}
+
+/// 装配期用的 provider 工厂：按配置造实现（阶段 B 在这里接 rig，测试接 mock）。
+pub type ProviderFactory =
+    Arc<dyn Fn(&ProviderConfig) -> Result<Arc<dyn ChatProvider>, ProviderError> + Send + Sync>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::event::MemoryEventSink;
+
+    #[test]
+    fn collecting_observer_concatenates_chunks() {
+        let observer = CollectingObserver::default();
+        observer.on_delta("正在");
+        observer.on_delta("读取日志");
+        assert_eq!(observer.collected(), "正在读取日志");
+    }
+
+    #[test]
+    fn event_observer_emits_text_delta() {
+        let sink = Arc::new(MemoryEventSink::new());
+        let observer = EventDeltaObserver::new(sink.clone());
+        observer.on_delta("嗨");
+        assert_eq!(sink.streamed_text(), "嗨");
+    }
+
+    #[test]
+    fn message_helpers_round_trip_through_json() {
+        let messages = vec![
+            ChatMessage::system("你是助手"),
+            ChatMessage::user("看看日志"),
+            ChatMessage::tool("call_1", "read_game_log", "{}"),
+        ];
+        let json = serde_json::to_string(&messages).expect("可序列化");
+        let back: Vec<ChatMessage> = serde_json::from_str(&json).expect("可反序列化");
+        assert_eq!(back, messages);
+        assert!(json.contains("\"role\":\"tool\""));
+    }
+}

crates/agent/src/brain/exec.rs

@@ -0,0 +1,347 @@
+//! 工具执行编排：schema 校验 → 分级确认 → 执行 → 审计 → 事件。
+//!
+//! **YOLO 只在这里**（mission M16 任务 3 的分工）：工具自己不判断 policy，
+//! 只声明「这次需要确认 + diff」；本模块按 [`ConfirmPolicy`] 决定问不问。
+//!
+//! 一次工具调用最多两条审计记录：
+//! 1. 需要确认时先记一条 `awaiting_confirmation`（「AI 想改 X」本身必须留痕）；
+//! 2. 结局记一条 `ok` / `denied` / `tool_error`（带 `yolo` 与 `confirmed` 标记）。
+//!
+//! 这两条区分了三种在复盘里完全不同的事：用户点了拒绝、YOLO 自动放行、用户点了允许。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::audit::{make_record, AuditDraft, AuditOutcome, AuditSink};
+use crate::brain::chat::ToolCall;
+use crate::clock::SharedClock;
+use crate::confirm::{ConfirmDecision, ConfirmGate, ConfirmPolicy, ConfirmRequest, DenyGuidance};
+use crate::event::{AgentEvent, AgentEventSink};
+use crate::registry::validate::validate;
+use crate::registry::{ToolCtx, ToolError, ToolRegistry};
+
+/// 一次工具执行的结局（回灌给模型的内容 + 成败标记）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ToolExecOutcome {
+    /// 回灌内容（结构化）。
+    pub content: Value,
+    /// 是否成功（UI/事件用；模型看的是 `content`）。
+    pub ok: bool,
+}
+
+impl ToolExecOutcome {
+    /// 成功。
+    #[must_use]
+    pub fn ok(content: Value) -> Self {
+        Self { content, ok: true }
+    }
+
+    /// 失败（`code` 给模型看，帮助它改正后重试）。
+    #[must_use]
+    pub fn error(code: &str, message: impl Into<String>) -> Self {
+        Self {
+            content: json!({ "status": "error", "code": code, "message": message.into() }),
+            ok: false,
+        }
+    }
+
+    /// 序列化成回灌给模型的字符串（工具消息的 `content`）。
+    #[must_use]
+    pub fn to_model_content(&self) -> String {
+        serde_json::to_string(&self.content).unwrap_or_else(|_| {
+            json!({ "status": "error", "code": "internal", "message": "结果序列化失败" })
+                .to_string()
+        })
+    }
+}
+
+/// 工具执行器（无状态，可跨轮复用）。
+pub struct ToolExecutor {
+    registry: Arc<ToolRegistry>,
+    audit: Arc<dyn AuditSink>,
+    gate: Arc<dyn ConfirmGate>,
+    policy: ConfirmPolicy,
+    clock: SharedClock,
+    sink: Arc<dyn AgentEventSink>,
+    guidance: DenyGuidance,
+    confirm_seq: AtomicU64,
+}
+
+impl ToolExecutor {
+    /// 装配（默认拒绝口径 = 内置对话：[`DenyGuidance::InApp`]）。
+    pub fn new(
+        registry: Arc<ToolRegistry>,
+        audit: Arc<dyn AuditSink>,
+        gate: Arc<dyn ConfirmGate>,
+        policy: ConfirmPolicy,
+        clock: SharedClock,
+        sink: Arc<dyn AgentEventSink>,
+    ) -> Self {
+        Self {
+            registry,
+            audit,
+            gate,
+            policy,
+            clock,
+            sink,
+            guidance: DenyGuidance::InApp,
+            confirm_seq: AtomicU64::new(0),
+        }
+    }
+
+    /// 换拒绝口径（外部 MCP 客户端用 [`DenyGuidance::External`]：没有弹窗可点）。
+    ///
+    /// 只改**文案**：策略、闸门、审计标记一个字都不变——这正是「同一注册表、
+    /// 同一安全策略、同一审计」在代码上的落点。
+    #[must_use]
+    pub fn with_guidance(mut self, guidance: DenyGuidance) -> Self {
+        self.guidance = guidance;
+        self
+    }
+
+    /// 执行一次工具调用（含确认与审计）。
+    pub async fn execute(
+        &self,
+        agent_session_id: &str,
+        call: &ToolCall,
+        step: usize,
+    ) -> ToolExecOutcome {
+        let started_at = self.clock.now_unix_ms();
+        self.sink.emit(AgentEvent::ToolCallStarted {
+            tool: call.name.clone(),
+            // 与审计同一套脱敏：事件（P1 会持久化）不能带出凭据明文。
+            args: crate::redact::redact_args(&call.arguments),
+            step,
+        });
+
+        let Some(spec) = self.registry.get(&call.name).cloned() else {
+            let message = format!(
+                "没有名为 `{}` 的工具。可用工具：{}",
+                call.name,
+                self.registry.names().join("、")
+            );
+            self.record(
+                agent_session_id,
+                &call.name,
+                &call.arguments,
+                AuditOutcome::UnknownTool,
+                &message,
+                false,
+                false,
+                started_at,
+            );
+            self.finish_event(&call.name, false, &message, false);
+            return ToolExecOutcome::error("unknown_tool", message);
+        };
+
+        if let Err(errors) = validate(&spec.input_schema, &call.arguments) {
+            let message = format!("参数不合法：{}", errors.join("；"));
+            self.record(
+                agent_session_id,
+                &call.name,
+                &call.arguments,
+                AuditOutcome::InvalidArgs,
+                &message,
+                false,
+                false,
+                started_at,
+            );
+            self.finish_event(&call.name, false, &message, false);
+            return ToolExecOutcome::error("invalid_args", message);
+        }
+
+        let ctx = ToolCtx {
+            agent_session_id: agent_session_id.to_string(),
+            confirmed: false,
+        };
+        let quoted = match (spec.handler)(&ctx, &call.arguments) {
+            Ok(output) => output,
+            Err(err) => return self.fail(agent_session_id, call, err, started_at),
+        };
+
+        let Some(confirmation) = quoted.confirmation.clone() else {
+            return self.succeed(agent_session_id, call, quoted, false, false, started_at);
+        };
+
+        // ── 需要确认：决定问不问（YOLO 只影响这里）──
+        let asked = self.policy.requires_confirmation(confirmation.sensitivity);
+        let yolo_auto = !asked && confirmation.sensitivity == crate::confirm::Sensitivity::High;
+
+        if asked {
+            self.record(
+                agent_session_id,
+                &call.name,
+                &call.arguments,
+                AuditOutcome::AwaitingConfirmation,
+                &confirmation.summary,
+                false,
+                false,
+                started_at,
+            );
+            let request = ConfirmRequest {
+                id: format!(
+                    "confirm-{}",
+                    self.confirm_seq.fetch_add(1, Ordering::Relaxed) + 1
+                ),
+                tool: call.name.clone(),
+                summary: confirmation.summary.clone(),
+                details: confirmation.details.clone(),
+                sensitivity: confirmation.sensitivity,
+            };
+            self.sink.emit(AgentEvent::ConfirmRequested {
+                request: Box::new(request.clone()),
+            });
+            if self.gate.request(request).await == ConfirmDecision::Denied {
+                let message = self.guidance.message().to_string();
+                self.record(
+                    agent_session_id,
+                    &call.name,
+                    &call.arguments,
+                    AuditOutcome::Denied,
+                    &message,
+                    false,
+                    false,
+                    started_at,
+                );
+                self.sink.emit(AgentEvent::ToolDenied {
+                    tool: call.name.clone(),
+                    reason: message.clone(),
+                });
+                self.finish_event(&call.name, false, &message, true);
+                return ToolExecOutcome::error("denied", message);
+            }
+        }
+
+        // ── 已获授权（用户允许或 YOLO）：带 confirmed 重放 ──
+        let confirmed_ctx = ToolCtx {
+            agent_session_id: agent_session_id.to_string(),
+            confirmed: true,
+        };
+        match (spec.handler)(&confirmed_ctx, &call.arguments) {
+            Ok(output) => {
+                if let Some(second) = output.confirmation {
+                    // 工具在"已确认"状态下仍要确认 = 实现写错了，明确报出来而不是死循环。
+                    let message = format!(
+                        "工具 `{}` 在已确认状态下仍请求确认：{}",
+                        call.name, second.summary
+                    );
+                    self.record(
+                        agent_session_id,
+                        &call.name,
+                        &call.arguments,
+                        AuditOutcome::ToolError,
+                        &message,
+                        yolo_auto,
+                        asked,
+                        started_at,
+                    );
+                    self.finish_event(&call.name, false, &message, true);
+                    return ToolExecOutcome::error("internal", message);
+                }
+                self.succeed(agent_session_id, call, output, asked, yolo_auto, started_at)
+            }
+            Err(err) => {
+                self.fail_after_confirm(agent_session_id, call, err, asked, yolo_auto, started_at)
+            }
+        }
+    }
+
+    fn succeed(
+        &self,
+        agent_session_id: &str,
+        call: &ToolCall,
+        output: crate::registry::ToolOutput,
+        confirmed: bool,
+        yolo: bool,
+        started_at: u64,
+    ) -> ToolExecOutcome {
+        self.record(
+            agent_session_id,
+            &call.name,
+            &call.arguments,
+            AuditOutcome::Ok,
+            &output.summary,
+            yolo,
+            confirmed,
+            started_at,
+        );
+        self.finish_event(
+            &call.name,
+            true,
+            &output.summary,
+            output.confirmation.is_some(),
+        );
+        ToolExecOutcome::ok(output.content)
+    }
+
+    fn fail(
+        &self,
+        agent_session_id: &str,
+        call: &ToolCall,
+        err: ToolError,
+        started_at: u64,
+    ) -> ToolExecOutcome {
+        self.fail_after_confirm(agent_session_id, call, err, false, false, started_at)
+    }
+
+    fn fail_after_confirm(
+        &self,
+        agent_session_id: &str,
+        call: &ToolCall,
+        err: ToolError,
+        confirmed: bool,
+        yolo: bool,
+        started_at: u64,
+    ) -> ToolExecOutcome {
+        let message = err.message().to_string();
+        self.record(
+            agent_session_id,
+            &call.name,
+            &call.arguments,
+            AuditOutcome::ToolError,
+            &message,
+            yolo,
+            confirmed,
+            started_at,
+        );
+        self.finish_event(&call.name, false, &message, false);
+        ToolExecOutcome::error(err.code(), message)
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    fn record(
+        &self,
+        agent_session_id: &str,
+        tool: &str,
+        args: &Value,
+        outcome: AuditOutcome,
+        summary: &str,
+        yolo: bool,
+        confirmed: bool,
+        started_at: u64,
+    ) {
+        let duration_ms = self.clock.now_unix_ms().saturating_sub(started_at);
+        let draft = AuditDraft {
+            tool,
+            args,
+            outcome,
+            summary,
+            yolo,
+            confirmed,
+            duration_ms,
+        };
+        self.audit
+            .record(&make_record(self.clock.as_ref(), agent_session_id, draft));
+    }
+
+    fn finish_event(&self, tool: &str, ok: bool, summary: &str, requires_confirmation: bool) {
+        self.sink.emit(AgentEvent::ToolCallFinished {
+            tool: tool.to_string(),
+            ok,
+            summary: summary.to_string(),
+            requires_confirmation,
+        });
+    }
+}

crates/agent/src/brain/mod.rs

@@ -0,0 +1,323 @@
+//! Agent 大脑：Provider 抽象 + 对话循环 + 流式事件。
+//!
+//! 选型（M10 定稿）：`rig-core` + `rig-agent`，**版本锁 `=0.45.x`**——上游 12 周 5 个 minor
+//! 的 breaking 频率决定了必须锁死；依赖面只在本文件收口，其它模块不许直接碰 rig，
+//! 以便随时换 genai / 自写循环逃生（`DevDocs/PlanDoc/02-ai-agent-design.md` §0）。
+//!
+//! Provider 形态（02 §2）：OpenAI 兼容（默认，含本地 llama.cpp `127.0.0.1:PORT/v1`）、
+//! Anthropic 原生、Ollama 原生、以及「禁用」——禁用时规则引擎仍可用。
+//!
+//! 统一 trait（M16 落地）：`stream_chat(messages, tools) -> Stream<Event>`，含 tool_call 事件。
+//! 本 crate 的落地形态是 [`chat::ChatProvider::complete`]（`request + observer → ChatReply`）：
+//! rig 0.45 的流在 [`rig`] 适配层里展开成增量回调，循环侧只消费「文本增量 + 工具调用」两件事。
+//! **rig 依赖面收口在 [`rig`] 一个文件**，本文件不 `use rig_*`。
+//!
+//! ## 对话循环（02 文档 §3.3）
+//!
+//! ```text
+//! run_turn(user_input)
+//!   ├─ provider.complete(request)  ← 流式增量经 EventDeltaObserver → UI
+//!   ├─ 有 tool_calls → ToolExecutor.execute（校验/确认/YOLO/审计）→ Tool 消息回灌
+//!   └─ 没有 tool_calls → 结束，返回最终文本
+//! ```
+//!
+//! 三条不变量：
+//! 1. **system prompt 每轮重新注入**，不进历史（改提示词立刻生效，也不会被压缩逻辑吃掉）；
+//! 2. 工具结果**永远回灌**（包括失败），模型才有机会改正；
+//! 3. 步数上限 [`DEFAULT_MAX_STEPS`] 兜底，防止模型在两个工具间打转烧 token。
+
+pub mod chat;
+pub mod exec;
+pub mod provider;
+pub mod rig;
+
+use std::fmt;
+use std::sync::Arc;
+
+use crate::audit::AuditSink;
+use crate::clock::SharedClock;
+use crate::confirm::{ConfirmGate, ConfirmPolicy};
+use crate::event::{AgentEvent, AgentEventSink};
+use crate::registry::ToolRegistry;
+
+pub use chat::{
+    ChatMessage, ChatProvider, ChatReply, ChatRequest, DeltaObserver, EventDeltaObserver,
+    NoopObserver, ProviderFactory, ProviderFuture, ToolCall, Usage,
+};
+pub use exec::{ToolExecOutcome, ToolExecutor};
+pub use provider::{ProviderConfig, ProviderError, ProviderFailure, ProviderKind};
+
+/// 一轮对话最多几轮工具调用。
+pub const DEFAULT_MAX_STEPS: usize = 8;
+
+/// 内置系统提示词（P0 版本；P2 会按实例上下文按需注入）。
+#[must_use]
+pub fn default_system_prompt() -> String {
+    [
+        "你是 Unlucky-Launcher（ULL，Minecraft 启动器）的内置助手。",
+        "你能调用工具：读配置（get_config）、改配置（set_config）、列出游戏会话（list_game_sessions）、",
+        "读会话日志（read_game_log）、跑崩溃规则引擎（diagnose_crash）。",
+        "纪律：",
+        "1. 先查后改：改任何配置前先用 get_config 确认键名与现值。",
+        "2. 崩溃问题先看 diagnose_crash 的规则结论；规则未命中或需要更多信息时，才用 read_game_log",
+        "   取 stderr / exit / crash_found，不要拉全量日志。",
+        "3. 只能改 get_config 列出的可写键。敏感键会要求用户确认：被拒绝就换方案，不要重复尝试同一改动。",
+        "4. 用中文回答，给用户可以立即执行的下一步；不确定时直说不确定，不要编造规则或日志内容。",
+    ]
+    .join("\n")
+}
+
+/// 循环参数。
+#[derive(Debug, Clone)]
+pub struct BrainConfig {
+    /// 最多几轮工具调用。
+    pub max_steps: usize,
+    /// 系统提示词。
+    pub system_prompt: String,
+}
+
+impl Default for BrainConfig {
+    fn default() -> Self {
+        Self {
+            max_steps: DEFAULT_MAX_STEPS,
+            system_prompt: default_system_prompt(),
+        }
+    }
+}
+
+impl BrainConfig {
+    /// 自定义提示词（步数用默认）。
+    #[must_use]
+    pub fn with_system_prompt(system_prompt: impl Into<String>) -> Self {
+        Self {
+            max_steps: DEFAULT_MAX_STEPS,
+            system_prompt: system_prompt.into(),
+        }
+    }
+}
+
+/// 循环的旁路依赖（审计/确认/时钟/事件）。
+pub struct BrainDeps {
+    /// 审计出口。
+    pub audit: Arc<dyn AuditSink>,
+    /// 确认闸门（P0 = [`crate::confirm::NoUiGate`]）。
+    pub gate: Arc<dyn ConfirmGate>,
+    /// YOLO 等策略快照。
+    pub policy: ConfirmPolicy,
+    /// 时间源。
+    pub clock: SharedClock,
+    /// 事件出口。
+    pub sink: Arc<dyn AgentEventSink>,
+}
+
+impl BrainDeps {
+    /// 装配。
+    pub fn new(
+        audit: Arc<dyn AuditSink>,
+        gate: Arc<dyn ConfirmGate>,
+        policy: ConfirmPolicy,
+        clock: SharedClock,
+        sink: Arc<dyn AgentEventSink>,
+    ) -> Self {
+        Self {
+            audit,
+            gate,
+            policy,
+            clock,
+            sink,
+        }
+    }
+}
+
+/// 一轮对话的结局。
+#[derive(Debug, Clone, PartialEq)]
+pub struct TurnOutcome {
+    /// 最终文本（可能是空的，例如撞上步数上限且模型最后一句只有工具调用）。
+    pub text: String,
+    /// 用掉的轮次。
+    pub steps: usize,
+    /// 工具调用总次数。
+    pub tool_calls: usize,
+    /// 为什么停下来。
+    pub stopped_reason: StopReason,
+}
+
+/// 停止原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StopReason {
+    /// 模型给出了最终回答。
+    Completed,
+    /// 撞上 [`BrainConfig::max_steps`]。
+    StepLimit,
+}
+
+/// 循环级错误。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum BrainError {
+    /// AI 被禁用（规则引擎仍可用）。
+    Disabled,
+    /// provider 报错。
+    Provider(ProviderError),
+}
+
+impl fmt::Display for BrainError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Disabled => f.write_str(DISABLED_MESSAGE),
+            Self::Provider(err) => write!(f, "LLM 调用失败：{err}"),
+        }
+    }
+}
+
+impl std::error::Error for BrainError {}
+
+/// AI 被禁用时给用户的话（装配层直接展示，不用先构造 Brain）。
+pub const DISABLED_MESSAGE: &str =
+    "AI 已禁用：请在设置 → AI 中配置端点。规则引擎崩溃诊断不受影响。";
+
+/// 对话循环。
+pub struct Brain {
+    provider: Arc<dyn ChatProvider>,
+    registry: Arc<ToolRegistry>,
+    executor: ToolExecutor,
+    config: BrainConfig,
+    sink: Arc<dyn AgentEventSink>,
+}
+
+impl Brain {
+    /// 装配。
+    pub fn new(
+        provider: Arc<dyn ChatProvider>,
+        registry: Arc<ToolRegistry>,
+        deps: BrainDeps,
+        config: BrainConfig,
+    ) -> Self {
+        let executor = ToolExecutor::new(
+            Arc::clone(&registry),
+            Arc::clone(&deps.audit),
+            Arc::clone(&deps.gate),
+            deps.policy,
+            Arc::clone(&deps.clock),
+            Arc::clone(&deps.sink),
+        );
+        Self {
+            provider,
+            registry,
+            executor,
+            config,
+            sink: deps.sink,
+        }
+    }
+
+    /// 当前 provider 配置（设置页/UI 展示用）。
+    #[must_use]
+    pub fn provider_config(&self) -> &ProviderConfig {
+        self.provider.config()
+    }
+
+    /// 跑一轮对话。`history` 由调用方持有（P1 落盘为 `agent/sessions/*.jsonl`）。
+    ///
+    /// # Errors
+    /// AI 被禁用（[`BrainError::Disabled`]）或 provider 报错（[`BrainError::Provider`]）。
+    pub async fn run_turn(
+        &self,
+        agent_session_id: &str,
+        history: &mut Vec<ChatMessage>,
+        user_input: &str,
+    ) -> Result<TurnOutcome, BrainError> {
+        if !self.provider.config().is_enabled() {
+            self.sink.emit(AgentEvent::Error {
+                message: DISABLED_MESSAGE.to_string(),
+            });
+            return Err(BrainError::Disabled);
+        }
+
+        self.sink.emit(AgentEvent::TurnStarted {
+            session_id: agent_session_id.to_string(),
+            user_text: user_input.to_string(),
+        });
+        history.push(ChatMessage::user(user_input));
+
+        let observer = EventDeltaObserver::new(Arc::clone(&self.sink));
+        let mut tool_calls = 0usize;
+        let mut last_text = String::new();
+        let mut used_steps = 0usize;
+
+        for step in 1..=self.config.max_steps {
+            used_steps = step;
+            let request = self.build_request(history);
+            let reply = match self.provider.complete(&request, &observer).await {
+                Ok(reply) => reply,
+                Err(err) => {
+                    self.sink.emit(AgentEvent::Error {
+                        message: err.to_string(),
+                    });
+                    return Err(BrainError::Provider(err));
+                }
+            };
+
+            if !reply.text.trim().is_empty() {
+                last_text = reply.text.clone();
+                self.sink.emit(AgentEvent::AssistantText {
+                    text: reply.text.clone(),
+                });
+            }
+
+            if reply.tool_calls.is_empty() {
+                history.push(ChatMessage::Assistant {
+                    text: reply.text.clone(),
+                    tool_calls: Vec::new(),
+                });
+                self.sink.emit(AgentEvent::TurnFinished {
+                    steps: step,
+                    text: reply.text.clone(),
+                });
+                return Ok(TurnOutcome {
+                    text: reply.text,
+                    steps: step,
+                    tool_calls,
+                    stopped_reason: StopReason::Completed,
+                });
+            }
+
+            history.push(ChatMessage::Assistant {
+                text: reply.text.clone(),
+                tool_calls: reply.tool_calls.clone(),
+            });
+            for call in &reply.tool_calls {
+                let outcome = self.executor.execute(agent_session_id, call, step).await;
+                tool_calls += 1;
+                history.push(ChatMessage::tool(
+                    call.id.clone(),
+                    call.name.clone(),
+                    outcome.to_model_content(),
+                ));
+            }
+        }
+
+        self.sink.emit(AgentEvent::TurnFinished {
+            steps: used_steps,
+            text: last_text.clone(),
+        });
+        Ok(TurnOutcome {
+            text: last_text,
+            steps: used_steps,
+            tool_calls,
+            stopped_reason: StopReason::StepLimit,
+        })
+    }
+
+    fn build_request(&self, history: &[ChatMessage]) -> ChatRequest {
+        let config = self.provider.config();
+        let mut messages = Vec::with_capacity(history.len() + 1);
+        messages.push(ChatMessage::system(self.config.system_prompt.clone()));
+        messages.extend_from_slice(history);
+        ChatRequest {
+            model: config.model.clone(),
+            messages,
+            tools: self.registry.definitions(),
+            temperature: config.temperature,
+            max_tokens: config.max_tokens,
+        }
+    }
+}

crates/agent/src/brain/provider.rs

@@ -0,0 +1,324 @@
+//! Provider 四态端点配置（02 文档 §2）。
+//!
+//! | 形态 | 端点 | 备注 |
+//! |------|------|------|
+//! | OpenAI 兼容（默认） | `base_url` + `api_key` + `model` | 覆盖 OpenAI/DeepSeek/Qwen/GLM/**本地 llama.cpp server**（`http://127.0.0.1:8080/v1`）/LM Studio |
+//! | Anthropic 原生 | `api_key` + `model` | Claude 系列（没有可用的 Rust 单厂商 SDK，见 research/02 §3.6） |
+//! | Ollama 原生 | `http://127.0.0.1:11434` | 本地另一种主流 |
+//! | 禁用 | — | 完全关闭 agent，规则引擎（`diagnose_crash`）仍可用 |
+//!
+//! 本文件只放**配置与校验**；对话协议在 [`super::chat`]。这样 rig 的 pre-1.0 破坏面
+//! （research/02 §7 R1）被关在 [`super::rig`] 一个文件里，这里连 rig 的名字都不出现。
+
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+#[path = "provider/failure.rs"]
+mod failure;
+
+pub use failure::ProviderFailure;
+
+/// 本地 llama.cpp server 的默认 OpenAI 兼容端点（research/02 §5.1）。
+pub const LLAMACPP_DEFAULT_BASE_URL: &str = "http://127.0.0.1:8080/v1";
+/// Ollama 默认端点（research/02 §5.2）。
+pub const OLLAMA_DEFAULT_BASE_URL: &str = "http://127.0.0.1:11434";
+/// Anthropic 官方 API 端点。
+pub const ANTHROPIC_DEFAULT_BASE_URL: &str = "https://api.anthropic.com";
+
+/// Provider 四态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ProviderKind {
+    /// OpenAI 兼容（含本地 llama.cpp / LM Studio / DeepSeek / Qwen…）。
+    OpenAiCompatible,
+    /// Anthropic 原生。
+    Anthropic,
+    /// Ollama 原生。
+    Ollama,
+    /// 完全禁用 agent。
+    Disabled,
+}
+
+impl ProviderKind {
+    /// 该形态是否必须提供 API key（本地推理通常不需要）。
+    #[must_use]
+    pub fn requires_api_key(self) -> bool {
+        matches!(self, Self::Anthropic)
+    }
+
+    /// 该形态的默认端点（OpenAI 兼容没有统一默认值，必须显式填；
+    /// 本地 llama.cpp 走 [`ProviderConfig::llamacpp_local`] 带的显式默认）。
+    #[must_use]
+    pub fn default_base_url(self) -> &'static str {
+        match self {
+            Self::OpenAiCompatible => "",
+            Self::Anthropic => ANTHROPIC_DEFAULT_BASE_URL,
+            Self::Ollama => OLLAMA_DEFAULT_BASE_URL,
+            Self::Disabled => "",
+        }
+    }
+
+    /// 配置键 `ai.provider` 的取值 → 形态（M174）。
+    ///
+    /// **不能用 serde**：`#[serde(rename_all = "snake_case")]` 把本枚举写成
+    /// `open_ai_compatible`（见本文件末尾的用例），而 schema 的允许值表
+    /// （`core::setting::keys::AI_PROVIDERS`）与设置页存的是 `openai_compatible`。两个词表必须在这里
+    /// 显式对上，否则「设置里存的值」读不到——这正是 M174 之前 agent 侧一次都没读过设置的原因。
+    /// 未知值给 `None`（由调用方回落默认，不猜）。
+    #[must_use]
+    pub fn from_setting(value: &str) -> Option<Self> {
+        match value.trim() {
+            "openai_compatible" => Some(Self::OpenAiCompatible),
+            "anthropic" => Some(Self::Anthropic),
+            "ollama" => Some(Self::Ollama),
+            "disabled" => Some(Self::Disabled),
+            _ => None,
+        }
+    }
+
+    /// 本形态在 `ai.provider` 里的取值（[`Self::from_setting`] 的逆；写回设置时用）。
+    #[must_use]
+    pub fn setting_value(self) -> &'static str {
+        match self {
+            Self::OpenAiCompatible => "openai_compatible",
+            Self::Anthropic => "anthropic",
+            Self::Ollama => "ollama",
+            Self::Disabled => "disabled",
+        }
+    }
+
+    /// 设置页展示名。
+    #[must_use]
+    pub fn display_name(self) -> &'static str {
+        match self {
+            Self::OpenAiCompatible => "OpenAI 兼容",
+            Self::Anthropic => "Anthropic 原生",
+            Self::Ollama => "Ollama 原生",
+            Self::Disabled => "已禁用",
+        }
+    }
+}
+
+/// Provider 配置（设置 → AI 的一份快照）。
+///
+/// `api_key` 只在进程内存在，**任何日志/审计/事件都不得带它**——
+/// `Debug` 是手写的（掩码 key），要连形态一起看用 [`ProviderConfig::redacted_debug`]。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+pub struct ProviderConfig {
+    /// 四态。
+    pub kind: ProviderKind,
+    /// 端点；空串表示用 [`ProviderKind::default_base_url`]。
+    pub base_url: String,
+    /// 模型名；`Disabled` 时可为空。
+    pub model: String,
+    /// API key（本地推理可空）。
+    pub api_key: Option<String>,
+    /// 采样温度。
+    pub temperature: Option<f32>,
+    /// 单次回复 token 上限。
+    pub max_tokens: Option<u32>,
+}
+
+impl Default for ProviderConfig {
+    fn default() -> Self {
+        Self::disabled()
+    }
+}
+
+impl ProviderConfig {
+    fn base(kind: ProviderKind, base_url: &str, model: &str) -> Self {
+        Self {
+            kind,
+            base_url: base_url.to_string(),
+            model: model.to_string(),
+            api_key: None,
+            temperature: None,
+            max_tokens: None,
+        }
+    }
+
+    /// OpenAI 兼容端点（云端或自建）。
+    #[must_use]
+    pub fn openai_compatible(base_url: &str, model: &str) -> Self {
+        Self::base(ProviderKind::OpenAiCompatible, base_url, model)
+    }
+
+    /// 本机 llama.cpp server（用户就在跑 llama-server 的默认场景）。
+    #[must_use]
+    pub fn llamacpp_local(model: &str) -> Self {
+        Self::base(
+            ProviderKind::OpenAiCompatible,
+            LLAMACPP_DEFAULT_BASE_URL,
+            model,
+        )
+    }
+
+    /// Anthropic 原生。
+    #[must_use]
+    pub fn anthropic(model: &str) -> Self {
+        Self::base(ProviderKind::Anthropic, ANTHROPIC_DEFAULT_BASE_URL, model)
+    }
+
+    /// 本机 Ollama。
+    #[must_use]
+    pub fn ollama(model: &str) -> Self {
+        Self::base(ProviderKind::Ollama, OLLAMA_DEFAULT_BASE_URL, model)
+    }
+
+    /// 禁用 agent。
+    #[must_use]
+    pub fn disabled() -> Self {
+        Self::base(ProviderKind::Disabled, "", "")
+    }
+
+    /// 带上 API key。
+    #[must_use]
+    pub fn with_api_key(mut self, api_key: impl Into<String>) -> Self {
+        self.api_key = Some(api_key.into());
+        self
+    }
+
+    /// 带上温度。
+    #[must_use]
+    pub fn with_temperature(mut self, temperature: f32) -> Self {
+        self.temperature = Some(temperature);
+        self
+    }
+
+    /// agent 是否启用。
+    #[must_use]
+    pub fn is_enabled(&self) -> bool {
+        self.kind != ProviderKind::Disabled
+    }
+
+    /// 实际使用的端点（空则回落默认值）。
+    #[must_use]
+    pub fn resolved_base_url(&self) -> &str {
+        if self.base_url.trim().is_empty() {
+            self.kind.default_base_url()
+        } else {
+            self.base_url.trim()
+        }
+    }
+
+    /// 配置是否可用（装配期调用一次，错就进设置页提示而不是等到对话时炸）。
+    ///
+    /// # Errors
+    /// 禁用、缺模型名、缺端点、缺 API key 时返回可读错误。
+    pub fn validate(&self) -> Result<(), ProviderError> {
+        if !self.is_enabled() {
+            return Err(ProviderError::classified(
+                ProviderFailure::NotConfigured,
+                "AI 已禁用：请在设置 → AI 中选择端点（规则引擎诊断不受影响）",
+            ));
+        }
+        if self.model.trim().is_empty() {
+            return Err(ProviderError::classified(
+                ProviderFailure::NotConfigured,
+                "没有配置模型名（model）",
+            ));
+        }
+        if self.resolved_base_url().trim().is_empty() {
+            return Err(ProviderError::classified(
+                ProviderFailure::NotConfigured,
+                format!("{} 需要填写端点（base_url）", self.kind.display_name()),
+            ));
+        }
+        if self.kind.requires_api_key()
+            && self
+                .api_key
+                .as_deref()
+                .is_none_or(|key| key.trim().is_empty())
+        {
+            return Err(ProviderError::classified(
+                ProviderFailure::NotConfigured,
+                format!("{} 需要 API key", self.kind.display_name()),
+            ));
+        }
+        Ok(())
+    }
+
+    /// 可打印的形态描述（**key 已掩码**，给日志/审计/设置页用）。
+    #[must_use]
+    pub fn redacted_debug(&self) -> String {
+        let key = match self.api_key.as_deref() {
+            None => "无".to_string(),
+            Some(k) if k.trim().is_empty() => "无".to_string(),
+            Some(_) => crate::redact::MASK.to_string(),
+        };
+        format!(
+            "{} base_url={} model={} api_key={key}",
+            self.kind.display_name(),
+            self.resolved_base_url(),
+            if self.model.is_empty() {
+                "（未设置）"
+            } else {
+                &self.model
+            },
+        )
+    }
+}
+
+impl fmt::Debug for ProviderConfig {
+    /// 手写 Debug：**key 掩码**（`api_key` 是唯一不能出现在日志里的字段）。
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("ProviderConfig")
+            .field("kind", &self.kind)
+            .field("base_url", &self.resolved_base_url())
+            .field("model", &self.model)
+            .field(
+                "api_key",
+                &self.api_key.as_deref().map(|_| crate::redact::MASK),
+            )
+            .field("temperature", &self.temperature)
+            .field("max_tokens", &self.max_tokens)
+            .finish()
+    }
+}
+
+/// Provider 层错误（消息面向用户 + **结构化分类**：`kind` 由 `brain::rig` 的适配层从 rig 的
+/// `ErrorReport` 翻译，见 [`failure`]）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderError {
+    kind: ProviderFailure,
+    message: String,
+}
+
+impl ProviderError {
+    /// 从可读文本构造（分类是 [`ProviderFailure::Other`]：调用方不知道结构化原因时用它）。
+    #[must_use]
+    pub fn new(message: impl Into<String>) -> Self {
+        Self {
+            kind: ProviderFailure::Other,
+            message: message.into(),
+        }
+    }
+
+    /// 带分类构造（`brain::rig` 的 `map_error` 与 [`ProviderConfig::validate`] 用）。
+    #[must_use]
+    pub fn classified(kind: ProviderFailure, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+        }
+    }
+
+    /// 失败分类（「测试连接」按它分档）。
+    #[must_use]
+    pub fn kind(&self) -> ProviderFailure {
+        self.kind
+    }
+}
+
+impl fmt::Display for ProviderError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for ProviderError {}
+
+#[cfg(test)]
+#[path = "provider/tests.rs"]
+mod tests;

crates/agent/src/brain/provider/failure.rs

@@ -0,0 +1,62 @@
+//! Provider 失败的**结构化分类**（M174 r1 复审 P2-5）：一次「测试连接」失败到底属于哪一类。
+//!
+//! ## 为什么不是字符串匹配
+//!
+//! r1 的版本对 `ProviderError` 的 `Display` 做子串匹配（找 `"401"` / `"connection refused"` /
+//! `"timed out"`），有三个真问题：①URL / 请求 id / 模型名里出现 `401` 这类数字就误判（假阳）；
+//! ②「连接被拒」的实际文本是 `Http client error: error sending request for url (…)`，不含
+//! `connection refused`，只能靠补一个更宽的 `error sending request` 兜住——**这是在猜文本**；
+//! ③文本随 rig / reqwest 版本漂，升级一次就静默错档（复审实测：`closed_port_is_unreachable`
+//! 一度偶发红）。
+//!
+//! 现在分类由 [`super::rig`] 的适配层从 rig 0.45 的**结构化报告**（`ErrorReport`：`kind` /
+//! `http_status` / `code`）翻译出来，本文件只放枚举与「给界面看的稳定名」。本模块不认识 rig。
+//!
+//! ## 六档口径
+//!
+//! | 档 | 判据（`super::rig::map_error`） | 界面含义 |
+//! |---|---|---|
+//! | [`ProviderFailure::NotConfigured`] | 配置不完整（`validate()` 拒绝）——**没有发请求** | 先把配置填完 |
+//! | [`ProviderFailure::Auth`] | 有 HTTP 状态且是 401 / 403，或 rig 明确报「凭据被拒」 | 密钥/权限不对 |
+//! | [`ProviderFailure::ModelNotFound`] | 有 HTTP 状态 404，或响应体的机器码是 `model_not_found` | 端点通了，模型不存在 |
+//! | [`ProviderFailure::Unreachable`] | 传输层失败：连接被拒 / DNS / TLS / 响应被截断（**没有拿到任何回应**） | 端点不可达 |
+//! | [`ProviderFailure::Timeout`] | 调用方的时限（探测的 8 秒）或 rig 报 `ErrorKind::Timeout` / 传输层 `io::ErrorKind::TimedOut` | 太慢或端点不响应 |
+//! | [`ProviderFailure::Other`] | 其余（JSON / URL / 请求构造 / 5xx 之类） | 请求失败（详情见下） |
+
+/// 一次 provider 调用的失败分类（见模块文档的六档表）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProviderFailure {
+    /// 配置不完整：**没有发出任何请求**。
+    NotConfigured,
+    /// 鉴权失败（401 / 403 / 凭据被拒）。
+    Auth,
+    /// 模型不存在（404 / `model_not_found`）。
+    ModelNotFound,
+    /// 端点不可达（传输层失败，没拿到任何回应）。
+    Unreachable,
+    /// 超时（调用方时限或传输层超时）。
+    Timeout,
+    /// 其它（协议 / 解析 / 5xx / 未知）。
+    Other,
+}
+
+impl ProviderFailure {
+    /// 稳定名（日志 / CLI / 测试断言用；界面文案走 i18n）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::NotConfigured => "not_configured",
+            Self::Auth => "auth",
+            Self::ModelNotFound => "model_not_found",
+            Self::Unreachable => "unreachable",
+            Self::Timeout => "timeout",
+            Self::Other => "other",
+        }
+    }
+
+    /// 「配置不完整」以外都意味着**请求真的发出去了**（守卫②/③的判据）。
+    #[must_use]
+    pub const fn sent_a_request(self) -> bool {
+        !matches!(self, Self::NotConfigured)
+    }
+}

crates/agent/src/brain/provider/tests.rs

@@ -0,0 +1,107 @@
+//! [`super`] 的用例（M174 r1 复审 P2-5 拆出来：`provider.rs` 撞了 400 行硬线）。
+//!
+//! 拆的是**纯搬移**：一条断言都没改。分类那半边的新用例在 `failure` 的模块文档里指路，
+//! 结构化分类本身由 `brain/rig.rs` 的 `map_error` 产生，用例在 `probe` 的真服务器那几条。
+
+use super::*;
+
+#[test]
+fn local_defaults_match_research() {
+    assert_eq!(
+        ProviderConfig::llamacpp_local("qwen2.5").resolved_base_url(),
+        LLAMACPP_DEFAULT_BASE_URL
+    );
+    assert_eq!(
+        ProviderConfig::ollama("llama3").resolved_base_url(),
+        OLLAMA_DEFAULT_BASE_URL
+    );
+    assert_eq!(
+        ProviderConfig::anthropic("claude-sonnet-4").resolved_base_url(),
+        ANTHROPIC_DEFAULT_BASE_URL
+    );
+}
+
+#[test]
+fn setting_vocabulary_round_trips() {
+    // 设置里存的是 `openai_compatible`（schema 的 `AI_PROVIDERS`），不是 serde 的
+    // `open_ai_compatible`：两个词表必须是这里这一对映射，否则「用户在设置页选的值」
+    // agent 侧读出来是 None（M174 的根因）。
+    for kind in [
+        ProviderKind::OpenAiCompatible,
+        ProviderKind::Anthropic,
+        ProviderKind::Ollama,
+        ProviderKind::Disabled,
+    ] {
+        assert_eq!(ProviderKind::from_setting(kind.setting_value()), Some(kind));
+    }
+    assert_eq!(
+        ProviderKind::from_setting("  ollama "),
+        Some(ProviderKind::Ollama)
+    );
+    assert_eq!(ProviderKind::from_setting("open_ai_compatible"), None);
+    assert_eq!(ProviderKind::from_setting(""), None);
+    // schema 的允许值表与本枚举的取值表是**同一个集合**（一方加了另一方没加就红）。
+    assert_eq!(
+        unlucky_core::setting::keys::AI_PROVIDERS,
+        [
+            ProviderKind::OpenAiCompatible.setting_value(),
+            ProviderKind::Anthropic.setting_value(),
+            ProviderKind::Ollama.setting_value(),
+            ProviderKind::Disabled.setting_value(),
+        ]
+    );
+}
+
+#[test]
+fn validate_requires_model_base_url_and_key() {
+    assert!(!ProviderConfig::disabled().is_enabled());
+    assert!(ProviderConfig::disabled().validate().is_err());
+    assert!(ProviderConfig::llamacpp_local("").validate().is_err());
+    assert!(ProviderConfig::llamacpp_local("qwen").validate().is_ok());
+    // OpenAI 兼容必须显式给端点
+    assert!(ProviderConfig::openai_compatible("", "gpt-4o-mini")
+        .validate()
+        .is_err());
+    assert!(
+        ProviderConfig::openai_compatible("https://api.deepseek.com/v1", "deepseek-chat")
+            .validate()
+            .is_ok()
+    );
+    assert!(ProviderConfig::anthropic("claude").validate().is_err());
+    assert!(ProviderConfig::anthropic("claude")
+        .with_api_key("sk-ant")
+        .validate()
+        .is_ok());
+}
+
+#[test]
+fn redacted_debug_never_leaks_key() {
+    let config = ProviderConfig::openai_compatible("https://api.deepseek.com/v1", "deepseek-chat")
+        .with_api_key("sk-super-secret");
+    let text = config.redacted_debug();
+    assert!(!text.contains("sk-super-secret"), "{text}");
+    assert!(text.contains(crate::redact::MASK));
+    // `{:?}` 也必须掩码：Debug 是 panic 消息/日志的默认出口。
+    let debug = format!("{config:?}");
+    assert!(!debug.contains("sk-super-secret"), "{debug}");
+    assert!(debug.contains(crate::redact::MASK), "{debug}");
+}
+
+#[test]
+fn empty_base_url_falls_back_to_default() {
+    let mut config = ProviderConfig::ollama("llama3");
+    config.base_url = String::new();
+    assert_eq!(config.resolved_base_url(), OLLAMA_DEFAULT_BASE_URL);
+}
+
+#[test]
+fn four_states_serialize_as_snake_case() {
+    assert_eq!(
+        serde_json::to_string(&ProviderKind::OpenAiCompatible).unwrap(),
+        "\"open_ai_compatible\""
+    );
+    assert_eq!(
+        serde_json::to_string(&ProviderConfig::disabled()).unwrap(),
+        "{\"kind\":\"disabled\",\"base_url\":\"\",\"model\":\"\",\"api_key\":null,\"temperature\":null,\"max_tokens\":null}"
+    );
+}

crates/agent/src/brain/rig.rs

@@ -0,0 +1,345 @@
+//! rig 适配层：[`ChatProvider`] 的**唯一**实现，也是整个 crate 唯一允许 `use rig_*` 的文件。
+//!
+//! 依赖面收窄纪律（`DevDocs/PlanDoc/02-ai-agent-design.md` §0 + research/02 §7 R1）：
+//! rig 是 pre-1.0、12 周 5 个 minor、CHANGELOG 满是 `[**breaking**]`（0.43 把 MCP 拆出 rig-agent、
+//! 0.45 升 rmcp 3.5 并改 owned connection）。所以把它关在这一个文件里：它变了，只有这里编译失败，
+//! [`super::ChatProvider`] 以上的循环/编排/审计一行不用动。
+//!
+//! ## 0.45 的接线（实读源码，非照文档猜）
+//!
+//! ```text
+//! ProviderConfig ─┬─ OpenAiCompatible → OpenAIConfig::new(key).with_base_url(url).client().chat(model)
+//!                 ├─ Anthropic        → AnthropicConfig::new(key).with_base_url(url).client().completion(model)
+//!                 ├─ Ollama           → OllamaConfig::new().with_base_url(url).client().completion(model)
+//!                 └─ Disabled         → 不构造（Brain::run_turn 已提前返回）
+//!                        ↓ Model<W>.erase()
+//!                 DynModel<Completion>（wire + transport 擦除，本文件只持有这一个类型）
+//! ```
+//!
+//! 循环侧只要两件事：流式文本增量、以及折好的 [`ChatReply`]（文本 + 工具调用）。
+//! 所以这里用 `model.stream(request)` 边转发 [`StreamEvent::Text`] 增量给 [`DeltaObserver`]，
+//! 最后 `Streamed::finish()` 拿到完整 [`CompletionResponse`]——工具调用从响应里取，
+//! 不自己拼分片 JSON（拼分片是 rig 的 `ReplyFold` 已经做过的事）。
+//!
+//! ## 三个已确认的坑
+//!
+//! 1. **llama.cpp 默认端点就是 `http://localhost:8080/v1`**（`providers/llamacpp/mod.rs`），
+//!    与 [`LLAMACPP_DEFAULT_BASE_URL`] 一致。这里统一走 OpenAI 方言 + 显式 base_url：
+//!    llama.cpp / LM Studio / DeepSeek 都是 OpenAI 兼容面，方言差异主要在默认端点与特有位
+//!    （`chat_template_kwargs`、`num_ctx`）——真要下发这些，再换成 `providers::llamacpp` 方言或
+//!    Ollama 的 `native_completion`。
+//! 2. **Ollama 原生方言的工具结果用 `tool_name` 配对（没有 id）**，OpenAI 方言用 `tool_call_id`。
+//!    这里走 rig 的 `Ollama::completion`（OpenAI 兼容 `/v1/chat/completions`），由 rig 负责回灌形状；
+//!    要下发 `num_ctx`（崩溃日志几千行，上下文必须可配）才需要 `native_completion`，留作 P1。
+//! 3. **取消**：`Streamed` 是普通 future/stream，丢弃即断开——P0 用「丢弃 future」实现停止生成，
+//!    P1 接 UI 的「停止」按钮时按 rig 的取消语义（drop stream）对齐即可，不需要 unsafe。
+//!
+//! ## 逃生口（保留但不是 Plan A）
+//!
+//! rig 的破坏变更真伤到（或 Rust 1.92 MSRV 追不上 rig 的 1.97.1）时：换 `genai`
+//! （provider + function calling，无 agent 循环）或自己写 OpenAI 方言（约 300~500 行）。
+//! **代价只是实现一个新的 [`ChatProvider`]**——这正是把它关在一个文件里的意义。
+//!
+//! [`LLAMACPP_DEFAULT_BASE_URL`]: super::provider::LLAMACPP_DEFAULT_BASE_URL
+//! [`StreamEvent::Text`]: rig_core::streaming::StreamEvent::Text
+
+use std::sync::Arc;
+
+use futures_util::StreamExt;
+use rig_core::completion::{CompletionRequest, ToolDefinition as RigToolDefinition};
+use rig_core::error::{ErrorKind, ProviderError as RigError};
+use rig_core::message::{
+    AssistantContent as RigAssistantContent, AssistantMessage as RigAssistantMessage, CallId,
+    Message as RigMessage, Text as RigText, ToolCall as RigToolCall, ToolFunction,
+    ToolName as RigToolName, ToolResult, ToolResultContent, UserContent,
+};
+use rig_core::operation::Completion;
+use rig_core::providers::anthropic::AnthropicConfig;
+use rig_core::providers::ollama::OllamaConfig;
+use rig_core::providers::openai::OpenAIConfig;
+use rig_core::streaming::{Item, StreamEvent};
+use rig_core::DynModel;
+
+use super::chat::{
+    ChatMessage, ChatProvider, ChatReply, ChatRequest, DeltaObserver, ProviderFactory,
+    ProviderFuture,
+};
+use super::provider::{ProviderConfig, ProviderError, ProviderFailure, ProviderKind};
+
+/// 锁定的 rig 版本（与 `Cargo.toml` 的唯一记录点，避免两处不一致）。
+pub const RIG_VERSION_PIN: &str = "=0.45.0";
+
+/// 擦掉 wire / transport 之后的补全模型——本文件对外只暴露这一个 rig 类型之外的东西。
+type ErasedModel = DynModel<Completion>;
+
+/// rig 实现的 [`ChatProvider`]：四态配置 + 一个擦除后的模型。
+pub struct RigProvider {
+    config: ProviderConfig,
+    model: ErasedModel,
+}
+
+impl RigProvider {
+    /// 按配置造 provider。`Disabled`、缺模型名、缺 key 都在这里被拒（fail-fast）。
+    ///
+    /// # Errors
+    /// AI 被禁用、配置不完整、或 rig 端点构造失败时返回可读错误。
+    pub fn new(config: ProviderConfig) -> Result<Self, ProviderError> {
+        config.validate()?;
+        let model = build_model(&config)?;
+        Ok(Self { config, model })
+    }
+
+    /// 装配层用的工厂：`ProviderFactory` 直接塞给 `crates/app`。
+    #[must_use]
+    pub fn factory() -> ProviderFactory {
+        Arc::new(|config: &ProviderConfig| {
+            Ok(Arc::new(Self::new(config.clone())?) as Arc<dyn ChatProvider>)
+        })
+    }
+}
+
+impl ChatProvider for RigProvider {
+    fn config(&self) -> &ProviderConfig {
+        &self.config
+    }
+
+    fn complete<'a>(
+        &'a self,
+        request: &'a ChatRequest,
+        observer: &'a dyn DeltaObserver,
+    ) -> ProviderFuture<'a> {
+        Box::pin(async move {
+            let rig_request = build_request(request)?;
+            let mut stream = self.model.stream(rig_request).map_err(map_error)?;
+
+            // 先转发增量，再拿折好的完整响应（工具调用只从响应取，不拼分片）。
+            let mut text = String::new();
+            while let Some(item) = stream.next().await {
+                match item.map_err(map_error)? {
+                    Item::Event(StreamEvent::Text { text: fragment, .. }) => {
+                        text.push_str(&fragment);
+                        observer.on_delta(&fragment);
+                    }
+                    Item::Event(_) | Item::Unknown(_) => {}
+                }
+            }
+            let response = stream.finish().await.map_err(map_error)?;
+            to_reply(&response, text)
+        })
+    }
+}
+
+/// 四态 → rig 模型。
+fn build_model(config: &ProviderConfig) -> Result<ErasedModel, ProviderError> {
+    let model = config.model.trim().to_string();
+    let base_url = config.resolved_base_url().to_string();
+    let api_key = config.api_key.clone().unwrap_or_default();
+    let erased = match config.kind {
+        ProviderKind::OpenAiCompatible => OpenAIConfig::new(api_key)
+            .with_base_url(base_url)
+            .client()
+            .chat(model)
+            .erase(),
+        ProviderKind::Anthropic => AnthropicConfig::new(api_key)
+            .with_base_url(base_url)
+            .client()
+            .completion(model)
+            .erase(),
+        ProviderKind::Ollama => OllamaConfig::new()
+            .with_base_url(base_url)
+            .client()
+            .completion(model)
+            .erase(),
+        ProviderKind::Disabled => {
+            return Err(ProviderError::new(
+                "AI 已禁用：请在设置 → AI 中选择端点（规则引擎诊断不受影响）",
+            ))
+        }
+    };
+    Ok(erased)
+}
+
+/// 本方消息 → rig 补全请求。
+fn build_request(request: &ChatRequest) -> Result<CompletionRequest, ProviderError> {
+    let mut history = to_rig_messages(&request.messages)?;
+    // rig 把历史最后一条当 prompt，其余是上下文；空历史没有可发的 prompt。
+    let prompt = history
+        .pop()
+        .ok_or_else(|| ProviderError::new("对话历史为空：至少需要一条用户消息"))?;
+    let prompt = Arc::unwrap_or_clone(prompt);
+    let tools = request
+        .tools
+        .iter()
+        .map(to_rig_tool)
+        .collect::<Result<Vec<_>, _>>()?;
+
+    Ok(CompletionRequest::new(prompt)
+        .messages(history)
+        .tools(tools)
+        .temperature(request.temperature.map(f64::from))
+        .max_tokens(request.max_tokens.map(u64::from)))
+}
+
+/// 本方工具定义 → rig 工具定义（入参都是裸 JSON Schema，这正是双投影的支点）。
+fn to_rig_tool(tool: &crate::registry::ToolDefinition) -> Result<RigToolDefinition, ProviderError> {
+    let name = tool_name(&tool.name)?;
+    Ok(RigToolDefinition::new(
+        name,
+        tool.description.clone(),
+        tool.input_schema.clone(),
+    ))
+}
+
+/// 本方消息 → rig 消息。
+fn to_rig_messages(messages: &[ChatMessage]) -> Result<Vec<Arc<RigMessage>>, ProviderError> {
+    let mut out = Vec::with_capacity(messages.len());
+    for message in messages {
+        let rig = match message {
+            ChatMessage::System { content } => RigMessage::system(content.clone()),
+            ChatMessage::User { content } => RigMessage::user(content.clone()),
+            ChatMessage::Assistant { text, tool_calls } => {
+                let mut parts = Vec::with_capacity(tool_calls.len() + 1);
+                if !text.trim().is_empty() {
+                    parts.push(RigAssistantContent::Text(RigText::new(text.clone())));
+                }
+                for call in tool_calls {
+                    parts.push(RigAssistantContent::ToolCall(RigToolCall::new(
+                        CallId::from_wire(call.id.clone()),
+                        ToolFunction::new(tool_name(&call.name)?, call.arguments.clone()),
+                    )));
+                }
+                RigMessage::Assistant(RigAssistantMessage::new(parts))
+            }
+            ChatMessage::Tool {
+                call_id,
+                name,
+                content,
+            } => RigMessage::User {
+                content: vec![UserContent::ToolResult(ToolResult {
+                    call: CallId::from_wire(call_id.clone()),
+                    name: tool_name(name)?,
+                    content: vec![ToolResultContent::text(content.clone())],
+                    is_error: false,
+                })],
+            },
+        };
+        out.push(Arc::new(rig));
+    }
+    Ok(out)
+}
+
+/// rig 响应 → 本方回复（文本 + 工具调用 + 用量）。
+fn to_reply(
+    response: &rig_core::completion::CompletionResponse,
+    streamed: String,
+) -> Result<ChatReply, ProviderError> {
+    let mut text = streamed;
+    let mut tool_calls = Vec::new();
+    for part in &response.choice {
+        match part {
+            RigAssistantContent::Text(chunk) => {
+                if text.is_empty() {
+                    text.push_str(&chunk.text);
+                }
+            }
+            RigAssistantContent::ToolCall(call) => {
+                if let Some(raw) = call.function.invalid_arguments.as_deref() {
+                    return Err(ProviderError::new(format!(
+                        "模型返回的工具调用参数不是 JSON 对象（工具 `{}`）：{raw}",
+                        call.function.name.as_str()
+                    )));
+                }
+                tool_calls.push(super::chat::ToolCall {
+                    id: call.id.to_string(),
+                    name: call.function.name.as_str().to_string(),
+                    arguments: serde_json::Value::Object(call.function.arguments.clone()),
+                });
+            }
+            // 推理链/图片/未知块不进对话循环（P0 只消费文本 + 工具调用）。
+            _ => {}
+        }
+    }
+    Ok(ChatReply {
+        text,
+        tool_calls,
+        usage: Some(super::chat::Usage {
+            prompt_tokens: response
+                .usage
+                .input_tokens
+                .and_then(|v| u32::try_from(v).ok()),
+            completion_tokens: response
+                .usage
+                .output_tokens
+                .and_then(|v| u32::try_from(v).ok()),
+        }),
+    })
+}
+
+/// rig 错误 → 本方错误：**分类取自 rig 的结构化报告**（`ErrorReport` 的 `kind` /
+/// `http_status` / `code`），不猜 `Display` 文本（M174 r1 复审 P2-5）。
+///
+/// | rig 侧信号 | 本方分类 |
+/// |---|---|
+/// | `http_status ∈ {401, 403}` | [`ProviderFailure::Auth`] |
+/// | `http_status == 404` | [`ProviderFailure::ModelNotFound`]（OpenAI 兼容面的 404 只可能是模型不在，`/chat/completions` 本身是固定路径；Anthropic 的 404 也是同一语义） |
+/// | `code == "model_not_found"` / `"model_not_found_error"` | [`ProviderFailure::ModelNotFound`] |
+/// | `ErrorKind::Timeout` 或传输层 `io::ErrorKind::TimedOut` | [`ProviderFailure::Timeout`] |
+/// | `ErrorKind::Http`（连接被拒 / DNS / TLS / 截断） | [`ProviderFailure::Unreachable`] |
+/// | 其余（JSON / URL / 请求构造 / 5xx / 未知） | [`ProviderFailure::Other`] |
+fn map_error(error: RigError) -> ProviderError {
+    let report = error.report();
+    let kind = match report.kind {
+        ErrorKind::Timeout => ProviderFailure::Timeout,
+        ErrorKind::Http => {
+            if transport_timed_out(&error) {
+                ProviderFailure::Timeout
+            } else {
+                ProviderFailure::Unreachable
+            }
+        }
+        ErrorKind::ProviderResponse | ErrorKind::Provider => match report.http_status {
+            Some(401 | 403) => ProviderFailure::Auth,
+            Some(404) => ProviderFailure::ModelNotFound,
+            _ if matches!(
+                report.code.as_deref(),
+                Some("model_not_found" | "model_not_found_error")
+            ) =>
+            {
+                ProviderFailure::ModelNotFound
+            }
+            _ => ProviderFailure::Other,
+        },
+        _ => ProviderFailure::Other,
+    };
+    ProviderError::classified(kind, report.message)
+}
+
+/// 传输层失败里有没有「超时」：沿 `source()` 链找 `io::ErrorKind::TimedOut`
+/// （reqwest 把超时折在 transport error 里，rig 只留一个 `Box<dyn Error>`）。
+///
+/// 结构化判据（类型 + `ErrorKind`），不是文本匹配：这条路径上的其它失败（连接被拒、DNS、
+/// TLS）都归 `Unreachable`。
+fn transport_timed_out(error: &RigError) -> bool {
+    let RigError::Http(http_error) = error else {
+        return false;
+    };
+    let mut source = std::error::Error::source(http_error);
+    for _ in 0..8 {
+        let Some(cause) = source else { return false };
+        if let Some(io) = cause.downcast_ref::<std::io::Error>() {
+            return io.kind() == std::io::ErrorKind::TimedOut;
+        }
+        source = cause.source();
+    }
+    false
+}
+
+/// 工具名 → rig 的 [`RigToolName`]（空名是唯一的非法输入）。
+fn tool_name(name: &str) -> Result<RigToolName, ProviderError> {
+    RigToolName::new(name)
+        .map_err(|_| ProviderError::new("工具名不能为空（ToolSpec 注册阶段应已拦截）"))
+}
+
+#[cfg(test)]
+#[path = "rig/tests.rs"]
+mod tests;

crates/agent/src/brain/rig/tests.rs

@@ -0,0 +1,82 @@
+//! [`super`]（rig 适配层）的用例（M174 r1 复审 P2-5 拆出来：结构化映射让 `rig.rs` 撞了 400 行）。
+//!
+//! 纯搬移。分类的端到端证据不在本文件：那要真 HTTP，用例在
+//! `crates/cli/src/commands/agent/probe/tests.rs`（四类各一台假服务器）。
+
+use super::*;
+
+fn tool(id: &str, name: &str) -> super::super::chat::ToolCall {
+    super::super::chat::ToolCall {
+        id: id.to_string(),
+        name: name.to_string(),
+        arguments: serde_json::json!({ "path": "appearance.theme_mode" }),
+    }
+}
+
+#[test]
+fn disabled_config_is_rejected_before_touching_the_network() {
+    let Err(err) = RigProvider::new(ProviderConfig::disabled()) else {
+        panic!("禁用态应在构造阶段被拒");
+    };
+    assert!(err.to_string().contains("禁用"));
+}
+
+#[test]
+fn anthropic_without_key_is_rejected() {
+    assert!(RigProvider::new(ProviderConfig::anthropic("claude-sonnet-4")).is_err());
+    assert!(
+        RigProvider::new(ProviderConfig::anthropic("claude-sonnet-4").with_api_key("sk-ant"))
+            .is_ok()
+    );
+}
+
+#[test]
+fn local_states_build_offline() {
+    assert!(RigProvider::new(ProviderConfig::llamacpp_local("qwen2.5-7b")).is_ok());
+    assert!(RigProvider::new(ProviderConfig::ollama("llama3.1")).is_ok());
+}
+
+#[test]
+fn request_maps_messages_and_tools() {
+    let request = ChatRequest {
+        model: "mock".to_string(),
+        messages: vec![
+            ChatMessage::system("你是助手"),
+            ChatMessage::user("把主题换成浅色"),
+            ChatMessage::Assistant {
+                text: String::new(),
+                tool_calls: vec![tool("call_1", "set_config")],
+            },
+            ChatMessage::tool("call_1", "set_config", "{\"status\":\"written\"}"),
+        ],
+        tools: vec![crate::registry::ToolDefinition {
+            name: "set_config".to_string(),
+            description: "改配置".to_string(),
+            input_schema: serde_json::json!({ "type": "object" }),
+        }],
+        temperature: Some(0.5),
+        max_tokens: Some(512),
+    };
+    let built = build_request(&request).expect("应能构造");
+    assert_eq!(built.chat_history.len(), 4);
+    assert_eq!(built.tools.len(), 1);
+    assert_eq!(built.tools[0].name.as_str(), "set_config");
+    assert_eq!(built.temperature, Some(0.5));
+    assert_eq!(built.max_tokens, Some(512));
+    // 工具结果在 rig 0.45 里是 user 角色的 ToolResult 内容块
+    let json = serde_json::to_string(&built.chat_history[3]).expect("可序列化");
+    assert!(json.contains("toolresult"), "{json}");
+}
+
+#[test]
+fn empty_history_is_a_readable_error() {
+    let request = ChatRequest {
+        model: "m".to_string(),
+        messages: Vec::new(),
+        tools: Vec::new(),
+        temperature: None,
+        max_tokens: None,
+    };
+    let err = build_request(&request).unwrap_err();
+    assert!(err.to_string().contains("对话历史为空"));
+}

crates/agent/src/clock.rs

@@ -0,0 +1,139 @@
+//! 时间源：审计日志、事件流、工具耗时都要时间戳，但**测试不能依赖真实时钟**
+//! （否则断言不稳定）。所以照既有做法注入 [`Clock`]。
+//!
+//! 时间戳格式化自己实现（[`format_unix_ms`]），不引 `chrono`：agent 的依赖面按
+//! `DevDocs/PlanDoc/02-ai-agent-design.md` §0 越窄越好，RFC3339 UTC 只需要一个
+//! 民用历换算（Howard Hinnant 的 `civil_from_days`）。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// 时间源。生产用 [`SystemClock`]，测试用 [`FixedClock`]。
+pub trait Clock: Send + Sync {
+    /// 当前 Unix 毫秒时间戳。
+    fn now_unix_ms(&self) -> u64;
+}
+
+/// 真实系统时钟（单调性不保证，审计只要"大致有序"）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct SystemClock;
+
+impl Clock for SystemClock {
+    fn now_unix_ms(&self) -> u64 {
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map_or(0, |d| d.as_millis() as u64)
+    }
+}
+
+/// 可控时钟：测试里固定起点、必要时手动推进。
+#[derive(Debug)]
+pub struct FixedClock {
+    ms: AtomicU64,
+    step_ms: u64,
+}
+
+impl FixedClock {
+    /// 从固定时间戳开始，每次读走一步 `step_ms`（0 = 不自动推进）。
+    #[must_use]
+    pub fn new(start_ms: u64) -> Self {
+        Self {
+            ms: AtomicU64::new(start_ms),
+            step_ms: 0,
+        }
+    }
+
+    /// 每次读取自动前进 `step_ms`，用来断言工具耗时字段。
+    #[must_use]
+    pub fn with_step(start_ms: u64, step_ms: u64) -> Self {
+        Self {
+            ms: AtomicU64::new(start_ms),
+            step_ms,
+        }
+    }
+
+    /// 手动推进。
+    pub fn advance(&self, ms: u64) {
+        self.ms.fetch_add(ms, Ordering::Relaxed);
+    }
+}
+
+impl Clock for FixedClock {
+    fn now_unix_ms(&self) -> u64 {
+        if self.step_ms == 0 {
+            return self.ms.load(Ordering::Relaxed);
+        }
+        self.ms.fetch_add(self.step_ms, Ordering::Relaxed) + self.step_ms
+    }
+}
+
+/// `Arc<dyn Clock>` 的简写。
+pub type SharedClock = Arc<dyn Clock>;
+
+/// Unix 毫秒 → `YYYY-MM-DDTHH:MM:SS.mmmZ`（UTC）。
+#[must_use]
+pub fn format_unix_ms(ms: u64) -> String {
+    let secs = (ms / 1000) as i64;
+    let millis = ms % 1000;
+    let days = secs.div_euclid(86_400);
+    let sod = secs.rem_euclid(86_400);
+    let (y, m, d) = civil_from_days(days);
+    let (h, mi, s) = (sod / 3600, (sod % 3600) / 60, sod % 60);
+    format!("{y:04}-{m:02}-{d:02}T{h:02}:{mi:02}:{s:02}.{millis:03}Z")
+}
+
+/// Unix 毫秒 → `YYYY-MM-DD`（UTC），审计落盘按天分文件用。
+#[must_use]
+pub fn date_of_unix_ms(ms: u64) -> String {
+    let (y, m, d) = civil_from_days(((ms / 1000) as i64).div_euclid(86_400));
+    format!("{y:04}-{m:02}-{d:02}")
+}
+
+/// 1970-01-01 起的天数 → (年, 月, 日)。
+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) as u64; // [0, 146096]
+    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; // [0, 399]
+    let y = yoe as i64 + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); // [0, 365]
+    let mp = (5 * doy + 2) / 153; // [0, 11]
+    let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
+    let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
+    (if m <= 2 { y + 1 } else { y }, m, d)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn formats_epoch_and_known_instants() {
+        assert_eq!(format_unix_ms(0), "1970-01-01T00:00:00.000Z");
+        // 2026-10-29T20:12:33.123Z
+        assert_eq!(
+            format_unix_ms(1_793_304_753_123),
+            "2026-10-29T20:12:33.123Z"
+        );
+        assert_eq!(date_of_unix_ms(1_793_304_753_123), "2026-10-29");
+    }
+
+    #[test]
+    fn handles_leap_day() {
+        // 2024-02-29T00:00:00Z
+        assert_eq!(
+            format_unix_ms(1_709_164_800_000),
+            "2024-02-29T00:00:00.000Z"
+        );
+    }
+
+    #[test]
+    fn fixed_clock_can_step() {
+        let clock = FixedClock::with_step(1_000, 5);
+        assert_eq!(clock.now_unix_ms(), 1_005);
+        assert_eq!(clock.now_unix_ms(), 1_010);
+        clock.advance(10);
+        assert_eq!(clock.now_unix_ms(), 1_025);
+    }
+}

crates/agent/src/confirm.rs

@@ -0,0 +1,235 @@
+//! 分级确认协议（02 文档 §3.1「分级确认」+ §4b「YOLO」）。
+//!
+//! 分工：
+//! - **工具**只声明「这次调用需要确认」并给出 diff（[`ConfirmRequest`]），不自己做决定；
+//! - **编排层**（[`crate::brain::exec`]）拿 [`ConfirmPolicy`] 决定是问人、还是走 YOLO；
+//! - **UI** 在 P1 通过 [`ConfirmGate`] 接进来（P0 只有事件 + fail-closed 的默认实现）。
+//!
+//! fail-closed 是刻意的：P0 没有确认弹窗，敏感键的写入**一律拒绝**而不是静默放行
+//! （research/02 §7 R9「写操作的破坏半径」）。
+
+use std::collections::VecDeque;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Mutex;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+/// 敏感等级。**与 M12 `setting::spec::Sensitivity` 逐字一致**
+/// （`DevDocs/SubAgentsTalk/setting-接口约定.md` §8）：
+///
+/// | 等级 | 语义 |
+/// |------|------|
+/// | `Low` | 静默生效 |
+/// | `Medium` | 静默生效，审计里能查到（每次调用本来都审计，这里只是标记用途） |
+/// | `High` | 必须用户确认（YOLO 可跳过确认，但**仍受白名单约束**） |
+///
+/// 「AI 完全不能写」的键（`ai.api_key` 等凭据）由 M12 的 `writable=false` 表达，
+/// 它们**不进白名单**，agent 侧走「不在白名单」的拒绝分支，不需要第四级。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Sensitivity {
+    /// 静默生效。
+    #[default]
+    Low,
+    /// 静默生效但审计标记（下载源、语言、日志级别）。
+    Medium,
+    /// 必须用户确认（数据目录、Java 路径、代理、AI 端点/YOLO 开关）。
+    High,
+}
+
+/// 一个待确认的操作：给用户看的措辞 + 结构化细节（UI 画 diff 用）。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct ConfirmRequest {
+    /// 请求 id（编排层生成，UI 回填决定时原样带回）。
+    pub id: String,
+    /// 工具名。
+    pub tool: String,
+    /// 一句话请求（「AI 请求把 `instance.java.path` 改为 `D:\jdk17`」）。
+    pub summary: String,
+    /// 结构化细节（`{"path":…, "old":…, "new":…}`）。
+    pub details: Value,
+    /// 敏感等级。
+    pub sensitivity: Sensitivity,
+}
+
+/// 用户决定。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ConfirmDecision {
+    /// 允许这一次。
+    Approved,
+    /// 拒绝（工具调用返回「用户拒绝」给模型）。
+    Denied,
+    /// 允许，且本会话后续不再询问（UI 的「全部允许」）。
+    ///
+    /// 编排层当前**只当普通放行**处理（`brain/exec.rs` 不区分两者）；「据此临时开 YOLO」
+    /// 是 P1 的行为，落地前不要按已实现来看。
+    ApprovedAll,
+}
+
+impl ConfirmDecision {
+    /// 是否放行（`Approved` 与 `ApprovedAll` 都放行）。
+    #[must_use]
+    pub fn is_approved(self) -> bool {
+        matches!(self, Self::Approved | Self::ApprovedAll)
+    }
+}
+
+/// 确认闸门：P1 由 app 的 Slint 弹窗实现；测试用 [`ScriptedGate`]。
+pub trait ConfirmGate: Send + Sync {
+    /// 发起确认并等待决定（UI 未接时由实现方立即给出 fail-closed 结果）。
+    fn request(&self, request: ConfirmRequest) -> ConfirmFuture;
+}
+
+/// 确认未来的箱子类型。
+pub type ConfirmFuture = Pin<Box<dyn Future<Output = ConfirmDecision> + Send + 'static>>;
+
+/// 一律放行（YOLO 单测 / 未来"用户已信任该工具"场景）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct AutoApproveGate;
+
+impl ConfirmGate for AutoApproveGate {
+    fn request(&self, _request: ConfirmRequest) -> ConfirmFuture {
+        Box::pin(async { ConfirmDecision::Approved })
+    }
+}
+
+/// 一律拒绝（fail-closed 的极简形态）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct AutoDenyGate;
+
+impl ConfirmGate for AutoDenyGate {
+    fn request(&self, _request: ConfirmRequest) -> ConfirmFuture {
+        Box::pin(async { ConfirmDecision::Denied })
+    }
+}
+
+/// P0 默认闸门：**没有确认 UI** → 一律拒绝（fail-closed）。
+///
+/// 请求本身已经由编排层作为 [`crate::event::AgentEvent::ConfirmRequested`] 发出去了，
+/// 所以 P0 的行为是「敏感操作既不静默执行，也不卡住对话」：事件流里留下了
+/// 「AI 想改 X」的完整记录，P1 接上弹窗后同一个事件直接变成可点的确认框。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoUiGate;
+
+impl ConfirmGate for NoUiGate {
+    fn request(&self, _request: ConfirmRequest) -> ConfirmFuture {
+        Box::pin(async { ConfirmDecision::Denied })
+    }
+}
+
+/// 脚本化闸门：按顺序返回预设决定，用完之后走 `default`（测试用）。
+pub struct ScriptedGate {
+    decisions: Mutex<VecDeque<ConfirmDecision>>,
+    default: ConfirmDecision,
+}
+
+impl ScriptedGate {
+    /// 依次给出 `decisions`，耗尽后返回 `default`。
+    #[must_use]
+    pub fn new(
+        decisions: impl IntoIterator<Item = ConfirmDecision>,
+        default: ConfirmDecision,
+    ) -> Self {
+        Self {
+            decisions: Mutex::new(decisions.into_iter().collect()),
+            default,
+        }
+    }
+}
+
+impl ConfirmGate for ScriptedGate {
+    fn request(&self, _request: ConfirmRequest) -> ConfirmFuture {
+        let decision = self
+            .decisions
+            .lock()
+            .ok()
+            .and_then(|mut q| q.pop_front())
+            .unwrap_or(self.default);
+        Box::pin(async move { decision })
+    }
+}
+
+/// 确认策略（编排层用）。YOLO 的真实开关在设置里，这里只是当次运行的快照。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct ConfirmPolicy {
+    /// 自动批准全部工具调用（设置 → AI → YOLO，默认关）。
+    pub yolo: bool,
+}
+
+/// 拒绝时的引导口径：**内置对话**有弹窗可点，**外部 MCP** 没有 UI——这条差别只在
+/// 「拒绝文案」上，策略本身完全相同（同一条 `ConfirmPolicy`、同一份审计）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DenyGuidance {
+    /// 内置对话：弹窗拒绝（或 P0 的 fail-closed）。
+    InApp,
+    /// 外部 MCP 客户端：引导用户去设置页确认，或打开 YOLO。
+    External,
+}
+
+impl DenyGuidance {
+    /// 拒绝后回给模型/用户的一句话（区分「谁拒的」与「下一步怎么办」）。
+    #[must_use]
+    pub fn message(self) -> &'static str {
+        match self {
+            Self::InApp => "用户拒绝了这次操作，未做任何修改",
+            Self::External => {
+                "这次操作需要用户确认，但当前是外部 MCP 客户端（没有确认弹窗），已按默认策略拒绝。\
+                 请让用户在启动器设置页手动修改，或在设置 → AI 里打开 YOLO 模式后重试（审计照记）。"
+            }
+        }
+    }
+}
+
+impl ConfirmPolicy {
+    /// 该等级是否需要**询问**用户：只有 `High` 会问；YOLO 下连 `High` 也不问
+    /// （02 文档 §4b：YOLO 跳过分级确认，但**仍受白名单约束**——能改的键没变少）。
+    #[must_use]
+    pub fn requires_confirmation(self, sensitivity: Sensitivity) -> bool {
+        !self.yolo && sensitivity == Sensitivity::High
+    }
+
+    /// 该等级是否可以直接执行（不需要询问）。
+    #[must_use]
+    pub fn auto_approves(self, sensitivity: Sensitivity) -> bool {
+        !self.requires_confirmation(sensitivity)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn low_and_medium_keys_never_ask() {
+        let policy = ConfirmPolicy { yolo: false };
+        assert!(!policy.requires_confirmation(Sensitivity::Low));
+        assert!(!policy.requires_confirmation(Sensitivity::Medium));
+        assert!(policy.auto_approves(Sensitivity::Low));
+        assert!(policy.auto_approves(Sensitivity::Medium));
+    }
+
+    #[test]
+    fn high_keys_ask_unless_yolo() {
+        assert!(ConfirmPolicy { yolo: false }.requires_confirmation(Sensitivity::High));
+        assert!(!ConfirmPolicy { yolo: false }.auto_approves(Sensitivity::High));
+        assert!(!ConfirmPolicy { yolo: true }.requires_confirmation(Sensitivity::High));
+        assert!(ConfirmPolicy { yolo: true }.auto_approves(Sensitivity::High));
+    }
+
+    #[test]
+    fn sensitivity_matches_m12_levels() {
+        // 序列化名必须与 M12 `setting::spec::Sensitivity` 一致
+        assert_eq!(serde_json::to_string(&Sensitivity::Low).unwrap(), "\"low\"");
+        assert_eq!(
+            serde_json::to_string(&Sensitivity::Medium).unwrap(),
+            "\"medium\""
+        );
+        assert_eq!(
+            serde_json::to_string(&Sensitivity::High).unwrap(),
+            "\"high\""
+        );
+    }
+}

crates/agent/src/event.rs

@@ -0,0 +1,197 @@
+//! agent 事件流：**UI 与审计之外的观察者**都从这里接（02 文档 §1 的「event channel」）。
+//!
+//! P0 只做输出（[`AgentEventSink`]），P1 的 Slint 聊天面板订阅同一路事件把
+//! 「正在读取日志…」「请求修改设置：下载并发 64→16」画出来，确认弹窗直接复用
+//! [`AgentEvent::ConfirmRequested`]。
+//!
+//! 实现方必须**非阻塞**：`emit` 在对话循环的同步路径上被调用。
+
+use std::sync::mpsc::Sender;
+use std::sync::Mutex;
+
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::confirm::ConfirmRequest;
+
+/// 一条 agent 事件（全部可序列化：P1 走 IPC 给 app 时不写两套类型）。
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum AgentEvent {
+    /// 一轮对话开始。
+    TurnStarted {
+        /// agent 会话 id。
+        session_id: String,
+        /// 用户输入。
+        user_text: String,
+    },
+    /// 流式文本增量（P1 聊天面板逐字渲染）。
+    TextDelta {
+        /// 增量文本。
+        text: String,
+    },
+    /// 模型这一轮的非流式完整文本（流式之外的兜底，也是审计用的正文）。
+    AssistantText {
+        /// 文本。
+        text: String,
+    },
+    /// 开始执行一个工具调用。
+    ToolCallStarted {
+        /// 工具名。
+        tool: String,
+        /// 模型给的参数。
+        args: Value,
+        /// 第几轮工具循环（从 1 开始）。
+        step: usize,
+    },
+    /// 一个工具调用结束。
+    ToolCallFinished {
+        /// 工具名。
+        tool: String,
+        /// 是否成功。
+        ok: bool,
+        /// 一句话结果摘要（UI 直接显示）。
+        summary: String,
+        /// 这次是否触发了确认请求。
+        requires_confirmation: bool,
+    },
+    /// 需要用户确认（P0 只发事件，P1 变成可点的弹窗）。
+    ConfirmRequested {
+        /// 待确认请求。
+        request: Box<ConfirmRequest>,
+    },
+    /// 工具调用被拒绝（策略或用户）。
+    ToolDenied {
+        /// 工具名。
+        tool: String,
+        /// 拒绝原因。
+        reason: String,
+    },
+    /// 一轮对话结束。
+    TurnFinished {
+        /// 实际用掉的最大工具轮次。
+        steps: usize,
+        /// 最终给用户看的文本。
+        text: String,
+    },
+    /// 循环级错误（provider 挂了、AI 被禁用…）。
+    Error {
+        /// 人类可读原因。
+        message: String,
+    },
+}
+
+/// 事件出口。
+pub trait AgentEventSink: Send + Sync {
+    /// 发一条事件。实现方不得阻塞。
+    fn emit(&self, event: AgentEvent);
+}
+
+/// 丢弃事件。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoopSink;
+
+impl AgentEventSink for NoopSink {
+    fn emit(&self, _event: AgentEvent) {}
+}
+
+/// 内存事件流（测试断言 + P0 的「暂不接 UI」）。
+#[derive(Debug, Default)]
+pub struct MemoryEventSink {
+    events: Mutex<Vec<AgentEvent>>,
+}
+
+impl MemoryEventSink {
+    /// 空 sink。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 取快照。
+    #[must_use]
+    pub fn events(&self) -> Vec<AgentEvent> {
+        self.events.lock().map(|e| e.clone()).unwrap_or_default()
+    }
+
+    /// 已发条数。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.events.lock().map(|e| e.len()).unwrap_or(0)
+    }
+
+    /// 是否还没发过事件。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// 拼接所有文本增量（测试断言「流式内容拼起来等于完整文本」）。
+    #[must_use]
+    pub fn streamed_text(&self) -> String {
+        self.events()
+            .into_iter()
+            .filter_map(|e| match e {
+                AgentEvent::TextDelta { text } => Some(text),
+                _ => None,
+            })
+            .collect()
+    }
+}
+
+impl AgentEventSink for MemoryEventSink {
+    fn emit(&self, event: AgentEvent) {
+        if let Ok(mut events) = self.events.lock() {
+            events.push(event);
+        }
+    }
+}
+
+/// 标准库 channel 出口（P1 的 app 用一个线程收、喂给 Slint 的事件循环）。
+#[derive(Debug, Clone)]
+pub struct MpscSink {
+    tx: Sender<AgentEvent>,
+}
+
+impl MpscSink {
+    /// 包一个 `std::sync::mpsc::Sender`。
+    #[must_use]
+    pub fn new(tx: Sender<AgentEvent>) -> Self {
+        Self { tx }
+    }
+}
+
+impl AgentEventSink for MpscSink {
+    fn emit(&self, event: AgentEvent) {
+        // 接收端已关闭说明 UI 没了，事件直接丢弃（不能拖累对话）。
+        let _ = self.tx.send(event);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn memory_sink_collects_and_concatenates_deltas() {
+        let sink = MemoryEventSink::new();
+        sink.emit(AgentEvent::TextDelta {
+            text: "正在".into(),
+        });
+        sink.emit(AgentEvent::TextDelta {
+            text: "读取日志".into(),
+        });
+        assert_eq!(sink.streamed_text(), "正在读取日志");
+        assert_eq!(sink.len(), 2);
+    }
+
+    #[test]
+    fn mpsc_sink_forwards() {
+        let (tx, rx) = std::sync::mpsc::channel();
+        let sink = MpscSink::new(tx);
+        sink.emit(AgentEvent::Error {
+            message: "boom".into(),
+        });
+        assert!(matches!(rx.recv(), Ok(AgentEvent::Error { .. })));
+    }
+}

crates/agent/src/lib.rs

@@ -0,0 +1,45 @@
+//! Unlucky-Launcher AI Agent（`unlucky_agent`）。
+//!
+//! 形态定案（决策 D4）：**内置 Agent 客户端 + 对外的 MCP server 双形态，共享同一个工具内核**。
+//! 设计定稿：`DevDocs/PlanDoc/02-ai-agent-design.md`。
+//!
+//! 三条不能破的边界：
+//! 1. 工具只定义一次（[`registry`]），内置客户端与 MCP server 都把同一个 `ToolSpec` 投影出去；
+//! 2. AI 是 Port 不是 Service——LLM 不可用时规则引擎仍能诊断；
+//! 3. AI 永不接触账户凭据；写配置受 schema 白名单约束并留审计。
+//!
+//! 与 core 的关系：agent 依赖 core 的公共 API，core 不知道 agent 的存在。
+//! 落地方式是把需要 core 的能力收成[`port`]里的五个 trait（配置读写 / 会话日志 / 崩溃诊断 /
+//! 实例与 Java / 账户），由装配层用 core 的实现填充——这样 M12/M14/M15/M18/M31/M33 未合并时
+//! agent 也能独立编译、独立测试。装配处有两条：`crates/app`（GUI）与 `ull agent serve`（headless）。
+//!
+//! 当前状态：工具内核 + 对话循环 + 审计（P0 定稿）+ **对外 MCP server**（M39）已落地。
+//! 两个外部依赖都收口在单文件：[`brain::rig`] 对 rig、[`mcp`] 对 rmcp（3.8.x）——
+//! 它们升 breaking 时只有那两个模块编译失败，上层的循环/编排/审计一行不用动。
+//!
+//! 模块分工：
+//! - [`registry`] 工具注册表（唯一真相源 + 双投影载荷）；
+//! - [`tools`] 工具 v1 实现（配置读写 / 会话日志 / 崩溃诊断）；
+//! - [`brain`] Provider 抽象 + 对话循环 + 工具编排；
+//! - [`mcp`] 对外 MCP server（rmcp 双投影 + stdio / Streamable HTTP 传输）；
+//! - [`confirm`] 分级确认协议与 YOLO 策略；
+//! - [`audit`] 每次工具调用的审计留痕；
+//! - [`event`] 面向 UI 的事件流；
+//! - [`port`] 与 core 的接触面（依赖倒置）；
+//! - [`redact`] 密钥/主目录脱敏；
+//! - [`clock`] 可注入时间源（审计/事件用）；
+//! - [`testing`] 五个端口的 mock 实现（供本 crate、app 与 MCP 契约测试复用）。
+
+#![forbid(unsafe_code)]
+
+pub mod audit;
+pub mod brain;
+pub mod clock;
+pub mod confirm;
+pub mod event;
+pub mod mcp;
+pub mod port;
+pub mod redact;
+pub mod registry;
+pub mod testing;
+pub mod tools;

crates/agent/src/mcp/mod.rs

@@ -0,0 +1,159 @@
+//! 对外 MCP server（02 文档 §1「双形态共享一个工具内核」的第二形态）。
+//!
+//! 传输定论（§0）：**Streamable HTTP on 127.0.0.1 是主力**（外部 agent 起 stdio 会变成
+//! 双实例抢数据目录锁），**stdio 形态保留**给 llama.cpp server 的内置 MCP client。
+//!
+//! 与内置客户端的关系：两侧都只吃 [`crate::registry::ToolRegistry`] 的 `(name, description,
+//! input_schema)`，并且**都必须走** [`crate::brain::exec::ToolExecutor`]——schema 校验、
+//! 分级确认、YOLO、审计一个字都不少。所以「用户在聊天里让 AI 改配置」与「Claude Code
+//! 通过 MCP 改配置」是同一条路径（02 §1 的铁律）。
+//!
+//! 安全边界（MCP 场景的差别只有一条）：
+//! - 敏感键（`Sensitivity::High`）默认**拒绝**而不是弹窗——外部客户端没有我们的 UI；
+//!   拒绝文案引导用户去设置页确认，或在设置里打开 `ai.yolo`（YOLO 下照记 `yolo=true` 审计）；
+//! - 写工具默认不暴露（`agent.mcp.allow_write=false`）：只读子集注册进注册表，
+//!   调写工具会得到「没有这个工具 + 可用工具清单」（并留一条 `unknown_tool` 审计）。
+//!
+//! 依赖面纪律：整个 crate 只有本模块允许 `use rmcp::`（与 `brain::rig` 对 rig 的规则同形）。
+
+pub mod projection;
+pub mod sample;
+pub mod serve;
+pub mod server;
+
+use std::fmt;
+
+pub use sample::{config_samples, ConfigSamples};
+pub use serve::{bind, serve_http, serve_http_on, serve_stdio};
+pub use server::RegistryServer;
+
+/// 一次 MCP server 运行的配置（由设置键 `agent.mcp.*` + 命令行覆盖合成）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct McpConfig {
+    /// 监听地址。**只允许回环地址**（默认 `127.0.0.1`）：MCP 工具能改配置，不能对外开。
+    pub host: String,
+    /// Streamable HTTP 端口（默认 47823，设置键 `agent.mcp.port`）。
+    pub port: u16,
+    /// 访问令牌（`Authorization: Bearer <token>`）；`None` = 不校验（仅限回环监听时允许）。
+    pub token: Option<String>,
+    /// 是否只暴露只读工具（默认 **true**；`agent.mcp.allow_write=true` 才放开写侧）。
+    pub read_only: bool,
+}
+
+impl Default for McpConfig {
+    fn default() -> Self {
+        Self {
+            host: "127.0.0.1".to_string(),
+            port: 47823,
+            token: None,
+            read_only: true,
+        }
+    }
+}
+
+impl McpConfig {
+    /// `host:port` 形态的监听地址（IPv6 字面量自动加方括号，`::1` 不会拼成 `::1:47823`）。
+    #[must_use]
+    pub fn socket_addr(&self) -> String {
+        if self.host.contains(':') {
+            format!("[{}]:{}", self.host, self.port)
+        } else {
+            format!("{}:{}", self.host, self.port)
+        }
+    }
+
+    /// MCP 端点 URL（客户端配置样例里用的那串）。
+    #[must_use]
+    pub fn url(&self) -> String {
+        format!("http://{}/mcp", self.socket_addr())
+    }
+
+    /// 拒绝非回环监听——这是安全铁律的**代码化**，不是文档里的建议。
+    ///
+    /// # Errors
+    /// `host` 不是回环地址时返回 [`McpServeError::NotLoopback`]。
+    pub fn ensure_loopback(&self) -> Result<(), McpServeError> {
+        let host = self.host.trim();
+        if host == "127.0.0.1" || host == "localhost" || host == "::1" {
+            return Ok(());
+        }
+        Err(McpServeError::NotLoopback(host.to_string()))
+    }
+}
+
+/// MCP server 启动/运行期错误（文案面向用户，可直接进 CLI 输出）。
+#[derive(Debug)]
+pub enum McpServeError {
+    /// 监听地址不是回环地址。
+    NotLoopback(String),
+    /// 端口被占用（最常见：另一个 `ull agent serve` 已经在跑）。
+    PortInUse {
+        /// 监听地址（`127.0.0.1:47823`）。
+        addr: String,
+    },
+    /// 其他 IO 失败（权限、端口不足、传输中断）。
+    Io(String),
+}
+
+impl fmt::Display for McpServeError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::NotLoopback(host) => write!(
+                f,
+                "拒绝在 `{host}` 上监听：MCP server 只允许回环地址（127.0.0.1 / localhost / ::1）"
+            ),
+            Self::PortInUse { addr } => write!(
+                f,
+                "端口已被占用：{addr}。可能另一个 `ull agent serve` 正在运行；\
+                 用 `--port <端口>` 或设置键 `agent.mcp.port` 换一个"
+            ),
+            Self::Io(message) => write!(f, "MCP server 传输失败：{message}"),
+        }
+    }
+}
+
+impl std::error::Error for McpServeError {}
+
+impl From<std::io::Error> for McpServeError {
+    fn from(error: std::io::Error) -> Self {
+        Self::Io(error.to_string())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn only_loopback_hosts_are_accepted() {
+        let mut cfg = McpConfig::default();
+        assert!(cfg.ensure_loopback().is_ok());
+        cfg.host = "localhost".to_string();
+        assert!(cfg.ensure_loopback().is_ok());
+        cfg.host = "::1".to_string();
+        assert_eq!(cfg.url(), "http://[::1]:47823/mcp");
+        assert!(cfg.ensure_loopback().is_ok());
+        cfg.host = "0.0.0.0".to_string();
+        let err = cfg.ensure_loopback().unwrap_err();
+        assert!(matches!(err, McpServeError::NotLoopback(_)));
+        assert!(err.to_string().contains("回环地址"));
+    }
+
+    #[test]
+    fn default_is_read_only_on_the_documented_port() {
+        let cfg = McpConfig::default();
+        assert!(cfg.read_only);
+        assert_eq!(cfg.port, 47823);
+        assert_eq!(cfg.url(), "http://127.0.0.1:47823/mcp");
+    }
+
+    #[test]
+    fn port_in_use_message_is_actionable() {
+        let err = McpServeError::PortInUse {
+            addr: "127.0.0.1:47823".to_string(),
+        };
+        let text = err.to_string();
+        assert!(text.contains("--port"), "{text}");
+        assert!(text.contains("agent.mcp.port"), "{text}");
+    }
+}

crates/agent/src/mcp/projection.rs

@@ -0,0 +1,106 @@
+//! 双投影的 **MCP 侧**：`ToolDefinition` → rmcp `Tool`（`ToolRoute::new_dyn` 的属性入参）。
+//!
+//! rig 侧在 [`crate::brain::rig`]（`ToolDefinition → RigToolDefinition`）。两侧都只吃裸
+//! `serde_json::Value` schema，所以「一致性」是可断言的：`tests/mcp_contract.rs` 遍历注册表，
+//! 断言 MCP 侧的 `(name, description, input_schema)` 与注册表逐项相等——这就是
+//! research/02 §6.2 建议进 CI 的那条契约。
+//!
+//! 额外一位信息：`annotations.read_only_hint`。MCP 客户端拿它决定「这个工具能不能
+//! 静默调用」，我们用它把 [`Access`] 语义透出去（只读提示，不是权限——权限在编排层）。
+
+use std::sync::Arc;
+
+use rmcp::model::{JsonObject, Tool, ToolAnnotations};
+use serde_json::Value;
+
+use crate::registry::{Access, ToolDefinition, ToolRegistry};
+
+/// 一个 `ToolDefinition` → rmcp `Tool`。
+///
+/// 注册表在注册阶段已保证 `input_schema` 根是 `object`，所以这里的兜底分支
+/// （非对象 → 空 schema）只是为了不 panic：真走到它说明注册校验被绕过了。
+#[must_use]
+pub fn tool_attr(definition: &ToolDefinition, access: Access) -> Tool {
+    let schema: JsonObject = match &definition.input_schema {
+        Value::Object(map) => map.clone(),
+        _ => JsonObject::new(),
+    };
+    let mut attr = Tool::new(
+        definition.name.clone(),
+        definition.description.clone(),
+        Arc::new(schema),
+    );
+    let mut annotations = ToolAnnotations::default();
+    annotations.read_only_hint = Some(access == Access::ReadOnly);
+    annotations.destructive_hint = Some(access == Access::Mutating);
+    attr.annotations = Some(annotations);
+    attr
+}
+
+/// 注册表 → rmcp `Tool` 列表（顺序同注册顺序，便于两侧比对）。
+#[must_use]
+pub fn tool_attrs(registry: &ToolRegistry) -> Vec<Tool> {
+    registry
+        .specs()
+        .iter()
+        .map(|spec| tool_attr(&spec.definition(), spec.access))
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::mock_ports;
+    use crate::tools::build_v1_registry;
+    use serde_json::json;
+
+    fn registry() -> ToolRegistry {
+        let (ports, _settings) = mock_ports();
+        build_v1_registry(&ports).expect("注册表应装配成功")
+    }
+
+    #[test]
+    fn projection_keeps_name_description_and_schema() {
+        let registry = registry();
+        let attrs = tool_attrs(&registry);
+        assert_eq!(attrs.len(), registry.len());
+
+        for (attr, spec) in attrs.iter().zip(registry.specs()) {
+            let definition = spec.definition();
+            assert_eq!(attr.name.as_ref(), definition.name);
+            assert_eq!(
+                attr.description.as_deref(),
+                Some(definition.description.as_str()),
+                "{} 的说明必须逐字相等",
+                definition.name
+            );
+            let projected = Value::Object((*attr.input_schema).clone());
+            assert_eq!(
+                projected, definition.input_schema,
+                "{} 的 JSON Schema 必须逐字相等",
+                definition.name
+            );
+        }
+    }
+
+    #[test]
+    fn read_only_hint_matches_access() {
+        let registry = registry();
+        for (attr, spec) in tool_attrs(&registry).iter().zip(registry.specs()) {
+            let hint = attr
+                .annotations
+                .as_ref()
+                .and_then(|a| a.read_only_hint)
+                .unwrap_or(false);
+            assert_eq!(hint, spec.access == Access::ReadOnly, "{}", attr.name);
+        }
+    }
+
+    #[test]
+    fn schema_root_stays_an_object_on_the_wire() {
+        for attr in tool_attrs(&registry()) {
+            let value = Value::Object((*attr.input_schema).clone());
+            assert_eq!(value["type"], json!("object"), "{}", attr.name);
+        }
+    }
+}

crates/agent/src/mcp/sample.rs

@@ -0,0 +1,80 @@
+//! 对外客户端配置样例（用户把它们粘进 Claude Code / Cursor 就能连上）。
+//!
+//! 为什么要生成而不是写在文档里：端口与令牌是**用户本机**的值，手抄必错。
+//! 两个客户端的形状不同（02 §0）：
+//! - **Claude Code**：`{"type":"http","url":…}`（`type` 必填，缺了会被当成 stdio）
+//! - **Cursor**：`{"url":…}`（`mcp.json` 里只认 url；多写 type 会被忽略但不报错）
+//!
+//! 令牌只在设置里非空时出现——回环 + 无令牌是允许的（研究里“至少一个 token”是建议不是铁律，
+//! 而我们用 `McpConfig::ensure_loopback` 硬性禁掉对外监听）。
+
+use serde_json::{json, Value};
+
+/// 客户端配置样例（三件套：端点 URL + 两份可直接粘的 JSON）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ConfigSamples {
+    /// `http://127.0.0.1:<port>/mcp`。
+    pub url: String,
+    /// Claude Code（`claude mcp add` / `~/.claude.json` 的 `mcpServers` 片段）。
+    pub claude_code: Value,
+    /// Cursor（`.cursor/mcp.json` 的 `mcpServers` 片段）。
+    pub cursor: Value,
+}
+
+/// 生成样例。`token` 非空时补 `headers.Authorization`。
+#[must_use]
+pub fn config_samples(url: &str, token: Option<&str>) -> ConfigSamples {
+    let headers = token
+        .filter(|t| !t.trim().is_empty())
+        .map(|t| json!({ "Authorization": format!("Bearer {t}") }));
+
+    let mut claude_entry = json!({ "type": "http", "url": url });
+    let mut cursor_entry = json!({ "url": url });
+    if let Some(headers) = &headers {
+        claude_entry["headers"] = headers.clone();
+        cursor_entry["headers"] = headers.clone();
+    }
+
+    ConfigSamples {
+        url: url.to_string(),
+        claude_code: json!({ "mcpServers": { "unlucky-launcher": claude_entry } }),
+        cursor: json!({ "mcpServers": { "unlucky-launcher": cursor_entry } }),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn claude_code_needs_type_http_and_cursor_does_not() {
+        let samples = config_samples("http://127.0.0.1:47823/mcp", None);
+        assert_eq!(
+            samples.claude_code["mcpServers"]["unlucky-launcher"]["type"],
+            json!("http")
+        );
+        assert_eq!(
+            samples.claude_code["mcpServers"]["unlucky-launcher"]["url"],
+            json!("http://127.0.0.1:47823/mcp")
+        );
+        assert!(samples.cursor["mcpServers"]["unlucky-launcher"]
+            .get("type")
+            .is_none());
+        assert_eq!(
+            samples.cursor["mcpServers"]["unlucky-launcher"]["url"],
+            json!("http://127.0.0.1:47823/mcp")
+        );
+    }
+
+    #[test]
+    fn token_becomes_bearer_header_and_empty_token_is_skipped() {
+        let with = config_samples("http://127.0.0.1:1/mcp", Some("s3cret"));
+        let header = &with.cursor["mcpServers"]["unlucky-launcher"]["headers"]["Authorization"];
+        assert_eq!(header, &json!("Bearer s3cret"));
+
+        let without = config_samples("http://127.0.0.1:1/mcp", Some("  "));
+        assert!(without.claude_code["mcpServers"]["unlucky-launcher"]
+            .get("headers")
+            .is_none());
+    }
+}

crates/agent/src/mcp/serve.rs

@@ -0,0 +1,144 @@
+//! 两种传输：stdio（llama.cpp 内置 MCP client 用）与 Streamable HTTP（主力）。
+//!
+//! 传输定论（02 §0）：**外部 MCP 主力是 127.0.0.1 上的 Streamable HTTP**，
+//! 因为 stdio 形态要被外部 agent 拉起 = 同一份数据目录出现第二个实例，
+//! 迟早撞上单写者锁（M18 的会话 jsonl、M12 的 launcher.json 都是单写者）。
+//! stdio 保留给**已经常驻的**本地模型服务（llama.cpp server 的 MCP client 由它自己拉子进程）。
+//!
+//! 令牌：`Authorization: Bearer <agent.mcp.token>`。设置里为空 = 不校验（只允许回环监听，
+//! `McpConfig::ensure_loopback` 已经拦掉对外监听）。research/02 §4.4 的原话是
+//! 「至少要有 headers 里的一枚随机 token」——我们做成可配、默认留空但样例里带。
+
+use std::net::SocketAddr;
+
+use axum::extract::Request;
+use axum::http::header::AUTHORIZATION;
+use axum::http::StatusCode;
+use axum::middleware::Next;
+use axum::response::{IntoResponse, Response};
+use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
+use rmcp::transport::streamable_http_server::{StreamableHttpServerConfig, StreamableHttpService};
+use rmcp::ServiceExt;
+use tokio::net::TcpListener;
+
+use crate::mcp::server::RegistryServer;
+use crate::mcp::{McpConfig, McpServeError};
+
+/// stdio 形态：读 stdin 写 stdout，直到对端关闭。
+///
+/// 注意：**stdout 只能有 JSON-RPC**。任何日志都要走 stderr（否则客户端解析失败）。
+///
+/// # Errors
+/// 传输中断或初始化失败时返回 [`McpServeError`]。
+pub async fn serve_stdio(server: RegistryServer) -> Result<(), McpServeError> {
+    let service = server
+        .serve(rmcp::transport::stdio())
+        .await
+        .map_err(|error| McpServeError::Io(format!("stdio 初始化失败：{error}")))?;
+    service
+        .waiting()
+        .await
+        .map_err(|error| McpServeError::Io(format!("stdio 传输中断：{error}")))?;
+    Ok(())
+}
+
+/// 绑定 Streamable HTTP 监听（**只绑回环**），返回实际地址。
+///
+/// 拆出来是为了让调用方在进入 `axum::serve` 之前就能打印「监听在哪」——
+/// 端口被占用时也能拿到一条可操作的错误（tower 的提醒：撞端口要给出换端口的指引）。
+///
+/// # Errors
+/// 非回环地址、端口被占用、或绑定失败时返回 [`McpServeError`]。
+pub async fn bind(cfg: &McpConfig) -> Result<(SocketAddr, TcpListener), McpServeError> {
+    cfg.ensure_loopback()?;
+    let addr = cfg.socket_addr();
+    let listener = TcpListener::bind(&addr).await.map_err(|error| {
+        if error.kind() == std::io::ErrorKind::AddrInUse {
+            McpServeError::PortInUse { addr: addr.clone() }
+        } else {
+            McpServeError::Io(format!("绑定 {addr} 失败：{error}"))
+        }
+    })?;
+    let local = listener
+        .local_addr()
+        .map_err(|error| McpServeError::Io(error.to_string()))?;
+    Ok((local, listener))
+}
+
+/// Streamable HTTP 形态：`POST /mcp` 一条 JSON-RPC 请求 / 一条响应。
+///
+/// `json_response = true`：简单请求直接回 `application/json`（脚本与裸 JSON-RPC
+/// 客户端最省事；需要服务端推送时 rmcp 会自动回落到 SSE）。
+///
+/// # Errors
+/// 绑定失败（见 [`bind`]）或服务运行期致命错误时返回 [`McpServeError`]。
+pub async fn serve_http(server: RegistryServer, cfg: McpConfig) -> Result<(), McpServeError> {
+    let (local, listener) = bind(&cfg).await?;
+    serve_http_on(server, cfg, local, listener).await
+}
+
+/// 在已绑定的监听上跑（测试用临时端口，避免抢 47823）。
+///
+/// # Errors
+/// 服务运行期致命错误时返回 [`McpServeError`]。
+pub async fn serve_http_on(
+    server: RegistryServer,
+    cfg: McpConfig,
+    local: SocketAddr,
+    listener: TcpListener,
+) -> Result<(), McpServeError> {
+    let http_config = StreamableHttpServerConfig::default()
+        .with_json_response(true)
+        .with_legacy_session_mode(false);
+    let factory_server = server.clone();
+    let service: StreamableHttpService<RegistryServer, LocalSessionManager> =
+        StreamableHttpService::new(
+            move || Ok(factory_server.clone()),
+            std::sync::Arc::new(LocalSessionManager::default()),
+            http_config,
+        );
+
+    let token = cfg.token.clone();
+    let app = axum::Router::new()
+        .nest_service("/mcp", service)
+        .layer(axum::middleware::from_fn(
+            move |request: Request, next: Next| {
+                let token = token.clone();
+                async move { authorize(token, request, next).await }
+            },
+        ));
+
+    eprintln!(
+        "[unlucky-agent] MCP server 监听 http://{local}/mcp（{} 个工具；令牌：{}）",
+        server.tool_count(),
+        if cfg.token.is_some() {
+            "已启用"
+        } else {
+            "未设置（仅回环监听）"
+        }
+    );
+
+    axum::serve(listener, app)
+        .await
+        .map_err(|error| McpServeError::Io(error.to_string()))
+}
+
+/// Bearer 令牌闸门：未配置 = 放行；配置了则严格比对。
+async fn authorize(token: Option<String>, request: Request, next: Next) -> Response {
+    let Some(expected) = token else {
+        return next.run(request).await;
+    };
+    let presented = request
+        .headers()
+        .get(AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .unwrap_or_default();
+    if presented == format!("Bearer {expected}") {
+        return next.run(request).await;
+    }
+    (
+        StatusCode::UNAUTHORIZED,
+        "缺少或错误的 Authorization: Bearer <agent.mcp.token>",
+    )
+        .into_response()
+}

crates/agent/src/mcp/server.rs

@@ -0,0 +1,243 @@
+//! rmcp `ServerHandler`：把同一份注册表挂成 MCP 工具路由。
+//!
+//! 每次 `tools/call` 都走 [`ToolExecutor`]——schema 校验、确认闸门、YOLO、审计、
+//! 事件**与内置客户端完全同一条路径**（02 §1 铁律）。工具级失败返回
+//! `CallToolResult::error`（客户端能看到文案），协议级错误只留给「路由不到」的情况
+//! （research/02 §3.2：`Err(McpError)` 会被大多数客户端吞成 "internal error"）。
+
+use std::sync::Arc;
+
+use rmcp::handler::server::tool::{ToolCallContext, ToolRoute, ToolRouter};
+use rmcp::model::{
+    CallToolRequestParams, CallToolResponse, CallToolResult, ContentBlock, Implementation,
+    ListToolsResult, PaginatedRequestParams, ServerCapabilities, ServerConfig, Tool,
+};
+use rmcp::service::RequestContext;
+use rmcp::{ErrorData as McpError, RoleServer, ServerHandler};
+use serde_json::Value;
+
+use crate::brain::chat::ToolCall;
+use crate::brain::exec::ToolExecutor;
+use crate::mcp::projection::tool_attr;
+use crate::registry::{Access, ToolRegistry};
+
+/// MCP server 的 `ServerHandler` 实现。
+///
+/// `Clone` 是 Streamable HTTP 要的：每个会话/请求由工厂造一份（共享同一批 `Arc`，
+/// 因此审计与策略仍是同一份）。
+#[derive(Clone)]
+pub struct RegistryServer {
+    router: ToolRouter<RegistryServer>,
+    visible: Arc<Vec<Tool>>,
+    session_id: String,
+}
+
+impl std::fmt::Debug for RegistryServer {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("RegistryServer")
+            .field("session_id", &self.session_id)
+            .field("tools", &self.visible.len())
+            .finish()
+    }
+}
+
+impl RegistryServer {
+    /// 用注册表 + 执行器装配。
+    ///
+    /// **`router_registry` 必须是完整注册表**（含写工具），`executor` 才决定「哪些工具真能跑」：
+    /// - 只读模式：`-executor` 用 `read_only_subset()` 装配，`tools/list` 只列只读项，
+    ///   硬调写工具会路由到执行器 → `unknown_tool`（**tool-level 错误 + 审计**），
+    ///   而不是 rmcp 的协议级 `-32602 tool not found`（那个客户端只会显示 "internal error"）。
+    /// - 写模式：两者都是完整注册表。
+    ///
+    /// `session_id` 进审计的 `agent_session_id` 字段（`mcp-http` / `mcp-stdio`），
+    /// 让复盘时能区分「内置对话改的」和「外部 MCP 改的」。
+    #[must_use]
+    pub fn new(
+        router_registry: Arc<ToolRegistry>,
+        executor: Arc<ToolExecutor>,
+        session_id: impl Into<String>,
+        read_only: bool,
+    ) -> Self {
+        let mut router = ToolRouter::new();
+        for spec in router_registry.specs() {
+            let attr = tool_attr(&spec.definition(), spec.access);
+            router.add_route(route(attr, Arc::clone(&executor)));
+        }
+        let visible: Vec<Tool> = router_registry
+            .specs()
+            .iter()
+            .filter(|spec| !read_only || spec.access == Access::ReadOnly)
+            .map(|spec| tool_attr(&spec.definition(), spec.access))
+            .collect();
+        Self {
+            router,
+            visible: Arc::new(visible),
+            session_id: session_id.into(),
+        }
+    }
+
+    /// 本 server **对外可见**的工具（`tools/list` 的内容）。
+    #[must_use]
+    pub fn tools(&self) -> Vec<Tool> {
+        (*self.visible).clone()
+    }
+
+    /// 审计用的会话标签。
+    #[must_use]
+    pub fn session_id(&self) -> &str {
+        &self.session_id
+    }
+
+    /// 对外可见的工具数（启动日志/断言用）。
+    #[must_use]
+    pub fn tool_count(&self) -> usize {
+        self.visible.len()
+    }
+}
+
+fn route(attr: Tool, executor: Arc<ToolExecutor>) -> ToolRoute<RegistryServer> {
+    ToolRoute::new_dyn(attr, move |context: ToolCallContext<'_, RegistryServer>| {
+        let executor = Arc::clone(&executor);
+        let session_id = context.service.session_id().to_string();
+        let name = context.name().to_string();
+        let arguments = context
+            .arguments
+            .clone()
+            .map_or_else(|| Value::Object(serde_json::Map::new()), Value::Object);
+
+        Box::pin(async move {
+            let call = ToolCall {
+                id: format!("mcp-{name}"),
+                name,
+                arguments,
+            };
+            let outcome = executor.execute(&session_id, &call, 0).await;
+            let text = outcome.to_model_content();
+            let content = vec![ContentBlock::text(text)];
+            let result = if outcome.ok {
+                CallToolResult::structured(outcome.content)
+            } else {
+                CallToolResult::error(content)
+            };
+            Ok(result.into())
+        })
+    })
+}
+
+impl ServerHandler for RegistryServer {
+    fn get_info(&self) -> ServerConfig {
+        ServerConfig::new(ServerCapabilities::builder().enable_tools().build())
+            .with_server_info(Implementation::new(
+                "unlucky-launcher",
+                env!("CARGO_PKG_VERSION"),
+            ))
+            .with_instructions(
+                "Unlucky-Launcher 的工具服务：读写启动器配置、看实例/版本/Java、读游戏日志、跑崩溃诊断。\
+                 账户凭据永不经由本服务出口；写配置受 schema 白名单与敏感键确认约束。",
+            )
+    }
+
+    async fn list_tools(
+        &self,
+        _request: Option<PaginatedRequestParams>,
+        _context: RequestContext<RoleServer>,
+    ) -> Result<ListToolsResult, McpError> {
+        Ok(ListToolsResult::with_all_items(self.tools()))
+    }
+
+    async fn call_tool(
+        &self,
+        request: CallToolRequestParams,
+        context: RequestContext<RoleServer>,
+    ) -> Result<CallToolResponse, McpError> {
+        let call_context = ToolCallContext::new(self, request, context);
+        self.router.call(call_context).await
+    }
+
+    fn get_tool(&self, name: &str) -> Option<Tool> {
+        self.router.get(name).cloned()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::audit::MemoryAudit;
+    use crate::clock::{FixedClock, SharedClock};
+    use crate::confirm::{AutoDenyGate, ConfirmPolicy};
+    use crate::event::NoopSink;
+    use crate::testing::mock_ports;
+    use crate::tools::build_v1_registry;
+    use serde_json::json;
+
+    fn server(registry: Arc<ToolRegistry>, read_only: bool) -> (RegistryServer, Arc<MemoryAudit>) {
+        let audit = Arc::new(MemoryAudit::new());
+        let clock: SharedClock = Arc::new(FixedClock::new(1_793_304_753_123));
+        let exposed = if read_only {
+            Arc::new(registry.read_only_subset())
+        } else {
+            Arc::clone(&registry)
+        };
+        let executor = Arc::new(ToolExecutor::new(
+            exposed,
+            audit.clone(),
+            Arc::new(AutoDenyGate),
+            ConfirmPolicy::default(),
+            clock,
+            Arc::new(NoopSink),
+        ));
+        (
+            RegistryServer::new(registry, executor, "mcp-test", read_only),
+            audit,
+        )
+    }
+
+    fn registry() -> Arc<ToolRegistry> {
+        let (ports, _settings) = mock_ports();
+        Arc::new(build_v1_registry(&ports).expect("注册表应装配成功"))
+    }
+
+    #[test]
+    fn lists_every_registered_tool_in_write_mode() {
+        let registry = registry();
+        let (server, _audit) = server(Arc::clone(&registry), false);
+        let tools = server.tools();
+        assert_eq!(tools.len(), registry.len());
+        assert_eq!(server.tool_count(), registry.len());
+        assert_eq!(server.session_id(), "mcp-test");
+        assert!(tools.iter().any(|tool| tool.name == "set_config"));
+    }
+
+    #[test]
+    fn read_only_mode_hides_the_writing_tool_but_keeps_it_routable() {
+        let (server, _audit) = server(registry(), true);
+        let names: Vec<String> = server.tools().iter().map(|t| t.name.to_string()).collect();
+        assert!(!names.iter().any(|n| n == "set_config"), "{names:?}");
+        assert!(names.iter().any(|n| n == "get_config"));
+        assert_eq!(names.len(), 9);
+        // 路由仍然存在（否则 rmcp 会回协议级 -32602，客户端看到的是 "internal error"），
+        // 真正拦下来的是只读子集执行器 → tool-level 错误 + 审计。
+        assert!(server.router.get("set_config").is_some());
+    }
+
+    #[test]
+    fn info_advertises_tools_and_a_stable_identity() {
+        let (server, _audit) = server(registry(), false);
+        let info = server.get_info();
+        assert!(info.capabilities.tools.is_some());
+        assert_eq!(info.server_info.name, "unlucky-launcher");
+    }
+
+    #[test]
+    fn get_tool_returns_the_projected_attr() {
+        let (server, _audit) = server(registry(), false);
+        let attr = server.get_tool("get_config").expect("工具存在");
+        assert_eq!(attr.name, "get_config");
+        assert_eq!(
+            Value::Object((*attr.input_schema).clone())["type"],
+            json!("object")
+        );
+        assert!(server.get_tool("nope").is_none());
+    }
+}

crates/agent/src/port.rs

@@ -0,0 +1,315 @@
+//! 端口层（port）：agent 与 `ull-core` 各模块之间**唯一**的接触面。
+//!
+//! 为什么不直接 `use ull_core::*`：M12（setting）/ M14（game）/ M15（diagnose）/ M18（launch）
+//! 与本 crate 并行开发，直接依赖会把 agent 的编译期绑死在别人的 API 日期上。这里用
+//! **依赖倒置**——agent 只声明自己需要的形状（本文件的 trait + 结构体），由 `crates/app`
+//! 在装配处用 `ull-core` 的实现去满足（`#![forbid(unsafe_code)]` 的纯适配层）。
+//!
+//! | 端口 | 提供的工具 | 对方模块 / 数据源 |
+//! |------|-----------|------------------|
+//! | [`SettingPort`] | `get_config` / `set_config` | M12 · `config/*.json` schema |
+//! | [`GameSessionPort`] | `list_game_sessions` / `read_game_log` | M18 · `agent/sessions/game/{index,<id>}.jsonl` |
+//! | [`DiagnosePort`] | `diagnose_crash` | M15 · 规则引擎 |
+//!
+//! 形状依据（以对方文件为准，改字段先改对方文件）：
+//! - `DevDocs/SubAgentsTalk/launch-接口约定.md` §2/§5（事件行 + 索引行）
+//! - `DevDocs/SubAgentsTalk/agent-ToolSpec约定.md`（本 crate 对外的对齐说明）
+//!
+//! 错误一律用 `Result<T, String>`：错误文本会**原样进工具结果**给模型与用户看
+//! （rmcp 的 `CallToolResult::error` 同理——协议级错误不给模型看，见 research/02 §3.2）。
+//! 因此端口实现写中文、面向用户、可执行（「配置键 `x` 不存在」而不是 `ENOENT`）。
+
+use std::collections::BTreeMap;
+use std::sync::Arc;
+
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::confirm::Sensitivity;
+
+pub mod game;
+
+pub use game::{
+    AccountPort, AccountSummary, GamePort, InstanceSummary, JavaRuntimeSummary, JavaStatus,
+    VersionSummary,
+};
+
+/// 端口调用结果的错误文本（面向用户可读，直接进工具结果）。
+pub type PortResult<T> = Result<T, String>;
+
+/// agent 需要的全部端口。装配处（`crates/app` / `ull agent serve`）用它一次性注入。
+#[derive(Clone)]
+pub struct Ports {
+    /// 配置读写（M12）。
+    pub setting: Arc<dyn SettingPort>,
+    /// 游戏会话与日志（M18）。
+    pub sessions: Arc<dyn GameSessionPort>,
+    /// 崩溃规则引擎（M15）。
+    pub diagnose: Arc<dyn DiagnosePort>,
+    /// 实例 / 版本 / Java（M14 + M33）。
+    pub game: Arc<dyn GamePort>,
+    /// 账户元数据（M31，**只有公开字段**，凭据永不出口）。
+    pub accounts: Arc<dyn AccountPort>,
+}
+
+// ───────────────────────────── 配置（M12） ─────────────────────────────
+
+/// AI 可写白名单里的一个键，带**敏感分级**（02 文档 §3.1 的「分级确认」依据）。
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct SettingKey {
+    /// 点分路径，如 `download.concurrency`、`java.selected_path`（键名以 M12 的 schema 为准）。
+    pub path: String,
+    /// 敏感等级（M12 `Low/Medium/High`）：只有 `High` 需要用户确认。
+    pub sensitivity: Sensitivity,
+    /// 值类型（`string` / `integer` / `boolean` / `enum` / `json`），用于错误提示。
+    pub value_type: String,
+    /// 一句话说明，同时进 `get_config` 概要与模型上下文。
+    pub description: String,
+}
+
+/// 一次成功的写入，带旧值即「diff」（research/02 §6.4 的 dry-run 落点）。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct SettingChange {
+    /// 被修改的键路径。
+    pub path: String,
+    /// 修改前的值；键此前不存在时为 `None`。
+    pub old: Option<Value>,
+    /// 写入后的值。
+    pub new: Value,
+}
+
+/// 配置端口（M12 实现，`ull-core::setting` 的 schema API 直译）。
+///
+/// agent 侧只做**白名单 + 敏感分级 + 确认编排**，值本身的范围/类型校验归 setting 模块所有
+/// （单一真相源：配置 schema 在 M12，agent 不复制一份）。
+pub trait SettingPort: Send + Sync {
+    /// 全量概要（`get_config()` 无参时返回）：键 → 当前值的扁平表，敏感键已脱敏。
+    fn summary(&self) -> Value;
+    /// 读单个键。键不存在时返回人类可读错误。
+    ///
+    /// **凭据契约**：`writable=false` 的凭据类键（`ai.api_key` 等）必须**拒绝或掩码**，
+    /// 不得返回明文——agent 侧还有一道 `redact::is_sensitive_key` 守卫，但端口是数据的
+    /// 第一道闸（模型上下文与对话历史都会带上这里的返回值）。
+    fn get(&self, path: &str) -> PortResult<Value>;
+    /// 写单个键（值校验由实现方负责），返回 diff。
+    fn set(&self, path: &str, value: &Value) -> PortResult<SettingChange>;
+    /// **AI 可写白名单**（含敏感分级）。不在表里的键 agent 一律拒绝。
+    fn writable_keys(&self) -> Vec<SettingKey>;
+    /// 配置 schema 的给 AI 版本（`get_config_schema` 工具）：只含 AI 可写键与
+    /// `x-ai-sensitivity` 标注，凭据类键天然不在其中（M12 `SettingSchema::to_json_schema`）。
+    fn schema(&self) -> Value;
+}
+
+// ──────────────────────── 游戏会话与日志（M18） ────────────────────────
+
+/// `index.jsonl` 一行 → 一个会话摘要（同 id 多行由实现方取最后一行）。
+///
+/// 字段对齐 `launch-接口约定.md` §5；对方新增字段时这里补 `Option`，不破坏旧实现。
+#[derive(Debug, Clone, Default, Serialize, PartialEq)]
+pub struct GameSessionSummary {
+    /// 会话 id，格式 `YYYYMMDDTHHMMSS-<6 位 hex>`（UTC）。
+    pub session_id: String,
+    /// 实例 id。
+    pub instance_id: Option<String>,
+    /// 实例显示名。
+    pub instance_name: Option<String>,
+    /// MC 版本。
+    pub game_version: Option<String>,
+    /// 启动时间（RFC3339 UTC）。
+    pub started_at: Option<String>,
+    /// 结束时间；会话未结束时为 `None`。
+    pub ended_at: Option<String>,
+    /// 时长毫秒。
+    pub duration_ms: u64,
+    /// 退出码；未正常结束时可能缺失。
+    pub exit_code: Option<i32>,
+    /// `exit_type`：`normal|application_error|jvm_error|sigkill|sigterm|killed|interrupted`。
+    pub exit_type: Option<String>,
+    /// exit 0 但疑似静默失败（D8 升级 1）。
+    pub silent_failure: bool,
+    /// 是否检测到游戏窗口。
+    pub window_detected: bool,
+    /// 事件条数。
+    pub event_count: u64,
+    /// 是否发现 crash-report / hs_err。
+    pub crash_found: bool,
+    /// 规则引擎首选结论 id（`diagnosis` 事件的 top candidate）。
+    pub diagnosis_top: Option<String>,
+}
+
+/// `read_game_log` 的查询条件：**按事件 seq 切片**，不是按行号
+/// （stdout/stderr 是一行一事件，但同一条日志行可能被切成多块，见 launch §1）。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct LogQuery {
+    /// 起始 `seq`（含）。
+    pub from_seq: Option<u64>,
+    /// 结束 `seq`（含）。
+    pub to_seq: Option<u64>,
+    /// 只要这些 `kind`（空 = 全部）。未知 kind 由实现方忽略而不是报错（前向兼容）。
+    pub kinds: Vec<String>,
+    /// 最多返回多少条事件（工具层已钳到 [`crate::tools::session::MAX_LOG_EVENTS`]）。
+    pub max_events: usize,
+}
+
+/// 一条事件行（`{v,seq,ts,t_ms,kind,session_id,payload}`），落盘时已脱敏。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct LogEvent {
+    /// 会话内单调递增序号。
+    pub seq: u64,
+    /// RFC3339 UTC。
+    pub ts: String,
+    /// 距会话开始的毫秒数。
+    pub t_ms: u64,
+    /// 事件类型（`stdout|stderr|exit|crash_found|diagnosis|…`）。
+    pub kind: String,
+    /// 事件负载，原样透传（已脱敏）。
+    pub payload: Value,
+}
+
+/// 一页日志事件 + 全量统计（模型拿到摘要就不会盲目翻页，防 token 爆炸）。
+#[derive(Debug, Clone, Default, Serialize, PartialEq)]
+pub struct LogPage {
+    /// 会话 id。
+    pub session_id: String,
+    /// 文件内事件总数。
+    pub total_events: u64,
+    /// 命中过滤条件的事件数。
+    pub matched_events: u64,
+    /// 是否因 `max_events` 截断。
+    pub truncated: bool,
+    /// 全量 kind 计数（不受过滤影响）。
+    pub kind_counts: BTreeMap<String, u64>,
+    /// 首事件时间。
+    pub first_ts: Option<String>,
+    /// 末事件时间。
+    pub last_ts: Option<String>,
+    /// 本次返回的事件（已按 seq 升序）。
+    pub events: Vec<LogEvent>,
+}
+
+/// 会话端口（M18 实现，`ull-core::launch::session_index` + `session` 的读侧）。
+///
+/// 读取**必须容忍最后一行不完整**（会话被 kill 时 jsonl 尾部可能截断）——这是实现方义务，
+/// 由 `launch-接口约定.md` §1 规定，agent 只消费结果。
+pub trait GameSessionPort: Send + Sync {
+    /// 按 `started_at` 倒序、按 `session_id` 去重后的会话列表；`instance_id` 非空时过滤。
+    fn list_sessions(
+        &self,
+        limit: usize,
+        instance_id: Option<&str>,
+    ) -> PortResult<Vec<GameSessionSummary>>;
+    /// 按 [`LogQuery`] 切片读取一个会话的事件流。
+    fn read_log(&self, session_id: &str, query: &LogQuery) -> PortResult<LogPage>;
+}
+
+// ───────────────────────── 崩溃诊断（M15） ─────────────────────────
+
+/// 六维修复动作（M15 `diagnose::rules::FixActionKind`，internally-tagged enum，
+/// YAML 里写 `kind:`）。序列化名与 M15 逐字相同：`change_java|adjust_memory|
+/// change_graphics|remove_mod|reinstall|seek_help`。
+#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum FixActionKind {
+    /// 换 Java（大版本上下界/指定实现）。
+    ChangeJava,
+    /// 调 Xmx/Xms、64 位 Java、系统虚拟内存。
+    AdjustMemory,
+    /// 驱动/渲染器/分辨率/覆盖层。
+    ChangeGraphics,
+    /// 删/禁/换 mod。
+    RemoveMod,
+    /// 重装/修组件（java|game_jar|loader|natives|libraries|assets|mods…）。
+    Reinstall,
+    /// 导出诊断包 / 需要更多信息。
+    SeekHelp,
+}
+
+/// 一条修复建议（M15 的 `MaterializedFixAction { kind, tool, args }` + 一句人话）。
+///
+/// `tool` 是 M15 给的**语义动作 id**（`java.set` / `memory.set` / …）。P0 没有这些细分工具，
+/// 所以 agent 侧按 [`FixActionKind`] 桥接到现有工具（见 [`crate::tools::diagnose`]），
+/// `tool` 只原样透传给模型与审计，不用于分发。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct FixAction {
+    /// 六维动作类别。
+    pub kind: FixActionKind,
+    /// 语义动作 id（如 `memory.set`）；P1 落对应工具后可直接当工具名。
+    pub tool: String,
+    /// 一句话建议（可为空，agent 会按 `kind` 补兜底文案）。
+    pub label: String,
+    /// 已做模板替换与单位换算的参数（M15 `materialize()` 的产物）。
+    pub args: std::collections::BTreeMap<String, String>,
+}
+
+/// 一条诊断候选（M15 `DiagnosisRecord::candidates[]`）。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct DiagnosisCandidate {
+    /// 规则 id（如 `jvm.32bit`）。
+    pub id: String,
+    /// `critical|error|warn|info`。
+    pub severity: String,
+    /// 分组（`jvm|memory|graphics|integrity|mod|…`）。
+    pub category: String,
+    /// 置信度 0.0~1.0。
+    pub confidence: f32,
+    /// i18n key（如 `diagnose.cause.jvm.32bit`）。
+    pub message_key: String,
+    /// **渲染后**的人类可读结论（M15 保证非空；agent 侧只在极旧数据上回落 `message_key`）。
+    pub message: String,
+    /// 更细的处理建议（M15 `detail`，可能为空）。
+    pub detail: String,
+    /// 证据行（已脱敏）。
+    pub evidence: Vec<String>,
+    /// 该候选的修复动作。
+    pub fix_actions: Vec<FixAction>,
+}
+
+/// 退出摘要（M15 `DiagnosisRecord::exit`，与 launch 的 `exit` 事件同源）。
+#[derive(Debug, Clone, Default, Serialize, PartialEq)]
+pub struct ExitSummary {
+    /// 退出码。
+    pub code: Option<i32>,
+    /// `normal|application_error|jvm_error|sigkill|sigterm|killed|interrupted`。
+    pub exit_type: Option<String>,
+    /// exit 0 但疑似静默失败。
+    pub silent_failure: bool,
+}
+
+/// 规则引擎结论：**这就是给 LLM 的全部输入**（不是裸日志）。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct CrashDiagnosis {
+    /// 会话 id。
+    pub session_id: String,
+    /// `rules|ai`（谁产出的）。
+    pub source: String,
+    /// 规则拿不准、需要更多信息时置 true（此时才值得让 LLM 深挖）。
+    pub needs_more_info: bool,
+    /// 主因候选，`candidates[0]` 即首因（M15 已按 priority→confidence 排序）。
+    pub candidates: Vec<DiagnosisCandidate>,
+    /// 被抑制的次要候选。
+    pub secondary: Vec<DiagnosisCandidate>,
+    /// 会话级关键片段（`crash_found.excerpt` / `hs_err` 摘要，已脱敏）。
+    pub evidence: Vec<String>,
+    /// 退出摘要。
+    pub exit: ExitSummary,
+}
+
+impl CrashDiagnosis {
+    /// 首选候选（主因）。
+    #[must_use]
+    pub fn top(&self) -> Option<&DiagnosisCandidate> {
+        self.candidates.first()
+    }
+
+    /// 最高置信度（没有候选时为 0）。
+    #[must_use]
+    pub fn top_confidence(&self) -> f32 {
+        self.top().map_or(0.0, |c| c.confidence)
+    }
+}
+
+/// 诊断端口（M15 实现）。agent 只做「调规则引擎 → 把结论 + 片段交给 LLM」。
+pub trait DiagnosePort: Send + Sync {
+    /// 对一个会话跑规则引擎。会话不存在/没有日志时返回人类可读错误。
+    fn diagnose(&self, session_id: &str) -> PortResult<CrashDiagnosis>;
+}

crates/agent/src/port/game.rs

@@ -0,0 +1,152 @@
+//! 实例 / 版本 / Java / 账户四个读侧端口（M39 的只读工具集用）。
+//!
+//! 与 [`super`] 的既有三个端口同形：trait 由 agent 声明，实现在装配层用 `unlucky-core` 填充。
+//! 拆分出来的原因是 `port.rs` 挨着 400 行硬上限（`guards.yml` 的 file-size 门禁）——
+//! 「会话与日志」「崩溃诊断」留在父模块，「游戏与账户」在这里，语义上也是一刀干净的分界。
+//!
+//! **凭据红线**（D9 / 02 文档 §3.1）：账户端口只露 [`AccountSummary`] 的公开字段。
+//! `Credentials`（access token / 刷新令牌 / authlib 密码）在 core 的 Secret 体系里，
+//! 根本不出现在本文件的类型里，因此不可能被工具结果带出去。
+
+use serde::Serialize;
+
+use super::PortResult;
+
+// ───────────────────────── 实例 / 版本（M14） ─────────────────────────
+
+/// 一个实例（`profiles.json` 一行）的摘要：模型只需要「能定位、能判断载荷在不在」。
+#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
+pub struct InstanceSummary {
+    /// 实例 id。
+    pub id: String,
+    /// 显示名。
+    pub name: String,
+    /// 版本 id（如 `1.21.1` / `fabric-loader-0.16.9-1.21.1`）。
+    pub version_id: String,
+    /// 该版本的载荷是否真的在 `versions/` 下（`false` = 装了档案但载荷缺失）。
+    pub version_present: bool,
+    /// 独立游戏目录（未覆盖时为 `None`）。
+    pub game_dir: Option<String>,
+    /// 实例级 Java 覆盖路径（未覆盖时为 `None`）。
+    pub java_path: Option<String>,
+    /// 上次启动时刻（Unix 毫秒；从未启动为 `None`）。
+    pub last_played_at: Option<u64>,
+}
+
+/// 已安装版本的摘要（`versions/<id>/` 的存在性 + 可读的元信息）。
+#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
+pub struct VersionSummary {
+    /// 版本 id。
+    pub id: String,
+    /// 版本 JSON 里声明的 `type`（`release` / `snapshot` / 加载器自报），读不到为 `None`。
+    pub kind: Option<String>,
+    /// 被几个实例引用。
+    pub instance_count: usize,
+}
+
+// ──────────────────────────── Java（M33） ────────────────────────────
+
+/// 一个探测到的 Java 运行时。
+#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
+pub struct JavaRuntimeSummary {
+    /// `java` 可执行文件路径。
+    pub binary: String,
+    /// 完整版本串（`21.0.2` / `1.8.0_402`）。
+    pub version: Option<String>,
+    /// 主版本号（8 / 17 / 21）。
+    pub major: Option<u32>,
+    /// 发行方（temurin / oracle / microsoft / zulu …）。
+    pub vendor: Option<String>,
+    /// 来源类别（`instance` / `managed` / `env` / `system`）。
+    pub origin: String,
+}
+
+/// Java 现状（`get_java_status`）。
+#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
+pub struct JavaStatus {
+    /// 默认堆内存（MB，`java.default_memory_mb`）。
+    pub default_memory_mb: Option<u64>,
+    /// 托管 JDK 的扫描根。
+    pub managed_roots: Vec<String>,
+    /// 探测到的候选（已去重，优先级从高到低）。
+    pub candidates: Vec<JavaRuntimeSummary>,
+}
+
+// ──────────────────────────── 账户（M31） ────────────────────────────
+
+/// 账户的**公开字段**摘要。凭据类字段刻意不存在（凭据红线）。
+#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
+pub struct AccountSummary {
+    /// 条目 id。
+    pub id: String,
+    /// 轨道：`offline` / `microsoft` / `authlib`。
+    pub kind: String,
+    /// Minecraft 档案 UUID（32 位无连字符）。
+    pub profile_id: String,
+    /// 玩家名（可能为空串 = 有档案但名字待刷新）。
+    pub profile_name: String,
+    /// 登录名（仅 authlib 轨有值）。
+    pub login_name: Option<String>,
+    /// 创建时刻（Unix 毫秒）。
+    pub created_at_ms: u64,
+}
+
+/// 游戏资产端口（M14 实例/版本 + M33 Java 探测）。
+pub trait GamePort: Send + Sync {
+    /// 全部实例（按上次启动时间倒序）。
+    fn list_instances(&self) -> PortResult<Vec<InstanceSummary>>;
+    /// 已安装版本清单。
+    fn list_versions(&self) -> PortResult<Vec<VersionSummary>>;
+    /// Java 现状（候选 + 托管根 + 默认内存）。
+    fn java_status(&self) -> PortResult<JavaStatus>;
+}
+
+/// 账户端口（M31）。实现方只允许读 `AccountStore::accounts()`（`AccountMeta`），
+/// **不得**调用 `credentials()`——那是凭据出口，agent 侧没有对应字段可以承接。
+pub trait AccountPort: Send + Sync {
+    /// 账户清单（公开字段）。
+    fn list_accounts(&self) -> PortResult<Vec<AccountSummary>>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn account_summary_has_no_credential_fields() {
+        // 把摘要序列化成 JSON：任何 token / password / secret 形态的键都不许出现。
+        // 这是凭据红线的**可执行断言**——将来有人往结构体里加字段，这条测试先炸。
+        let summary = AccountSummary {
+            id: "a1".to_string(),
+            kind: "offline".to_string(),
+            profile_id: "0123456789abcdef0123456789abcdef".to_string(),
+            profile_name: "Steve".to_string(),
+            login_name: Some("steve@example.com".to_string()),
+            created_at_ms: 1_793_304_753_123,
+        };
+        let json = serde_json::to_string(&summary).expect("可序列化");
+        for forbidden in ["token", "password", "secret", "credential", "refresh"] {
+            assert!(
+                !json.to_lowercase().contains(forbidden),
+                "账户摘要不得包含 `{forbidden}`：{json}"
+            );
+        }
+    }
+
+    #[test]
+    fn java_status_round_trips() {
+        let status = JavaStatus {
+            default_memory_mb: Some(2048),
+            managed_roots: vec!["/data/java-managed".to_string()],
+            candidates: vec![JavaRuntimeSummary {
+                binary: "/jdk/bin/java".to_string(),
+                version: Some("21.0.2".to_string()),
+                major: Some(21),
+                vendor: Some("temurin".to_string()),
+                origin: "managed".to_string(),
+            }],
+        };
+        assert_eq!(status.candidates.len(), 1);
+        assert_eq!(status.candidates[0].major, Some(21));
+    }
+}

crates/agent/src/redact.rs

@@ -0,0 +1,217 @@
+//! 脱敏：审计日志的参数、以及日志工具返回文本的**第二道**防线。
+//!
+//! 第一道在 launch 落盘时（`launch-接口约定.md` §4：`<redacted:token>` / `<home>` /
+//! `<redacted:opaque>`），所以这里不重复实现那套；本模块只兜两件事：
+//! 1. 审计日志里的参数可能含 API key（`set_config` 能改 AI 端点）→ 按键名掩码；
+//! 2. 日志正文万一含用户主目录绝对路径（旧会话、第三方 mod 输出）→ 掩码用户名段。
+//!
+//! 幂等：对已脱敏文本再跑一遍结果不变（`<home>` / `***` 原样保留）。
+
+use serde_json::{Map, Value};
+
+/// 掩码占位。
+pub const MASK: &str = "***";
+
+/// 键名是否敏感（不区分大小写，含子串即算）。
+///
+/// 覆盖：`api_key` / `apikey` / `accessToken` / `session_token` / `password` /
+/// `secret` / `authorization` / `credential`。
+#[must_use]
+pub fn is_sensitive_key(key: &str) -> bool {
+    const NEEDLES: [&str; 8] = [
+        "api_key",
+        "apikey",
+        "token",
+        "password",
+        "passwd",
+        "secret",
+        "authorization",
+        "credential",
+    ];
+    let lower = key.to_ascii_lowercase();
+    NEEDLES.iter().any(|n| lower.contains(n))
+}
+
+/// 审计用：递归把敏感键的值换成 [`MASK`]（保留结构，读审计的人仍能看出改的是哪个键）。
+///
+/// 除了「键名本身敏感」之外，还认 `set_config {path, value}` 这种**值随路径敏感**的形状：
+/// 当同级的 `path` 是敏感键名（`ai.api_key`）时，`value`/`old`/`new` 一律掩码——
+/// 否则审计日志会把 API key 原文写进磁盘。
+#[must_use]
+pub fn redact_args(value: &Value) -> Value {
+    match value {
+        Value::Object(map) => {
+            let sensitive_path = map
+                .get("path")
+                .and_then(Value::as_str)
+                .is_some_and(is_sensitive_key);
+            let mut out = Map::with_capacity(map.len());
+            for (k, v) in map {
+                let mask = is_sensitive_key(k)
+                    || (sensitive_path && matches!(k.as_str(), "value" | "old" | "new"));
+                let masked = if mask {
+                    Value::String(MASK.to_string())
+                } else {
+                    redact_args(v)
+                };
+                out.insert(k.clone(), masked);
+            }
+            Value::Object(out)
+        }
+        Value::Array(items) => Value::Array(items.iter().map(redact_args).collect()),
+        other => other.clone(),
+    }
+}
+
+/// 文本脱敏：用户主目录段 + `Bearer` 令牌。已脱敏文本原样返回（幂等）。
+#[must_use]
+pub fn redact_text(text: &str) -> String {
+    let masked = mask_user_dirs(text);
+    mask_bearer(&masked)
+}
+
+/// 任意 JSON 的每个字符串都过 [`redact_text`]（工具结果出口的第二道防线）。
+///
+/// 与 [`redact_args`] 的分工：那个按键名掩码（审计参数），这个按**内容**掩码
+/// （日志正文、账户展示名之类可能夹带主目录/Bearer 的字符串）。
+#[must_use]
+pub fn redact_texts(value: &Value) -> Value {
+    match value {
+        Value::String(text) => Value::String(redact_text(text)),
+        Value::Array(items) => Value::Array(items.iter().map(redact_texts).collect()),
+        Value::Object(map) => Value::Object(
+            map.iter()
+                .map(|(key, child)| (key.clone(), redact_texts(child)))
+                .collect(),
+        ),
+        other => other.clone(),
+    }
+}
+
+/// `C:\Users\<名>` / `/home/<名>` / `/Users/<名>` → 用户名段替换为 [`MASK`]。
+fn mask_user_dirs(text: &str) -> String {
+    let lower = text.to_ascii_lowercase();
+    let mut out = String::with_capacity(text.len());
+    let mut cursor = 0usize;
+    while cursor < text.len() {
+        let Some((start, marker_len)) = find_marker(&lower, cursor) else {
+            out.push_str(&text[cursor..]);
+            break;
+        };
+        out.push_str(&text[cursor..start + marker_len]);
+        let name_start = start + marker_len;
+        let name_end = segment_end(text, name_start);
+        let segment = &text[name_start..name_end];
+        if segment.is_empty() || segment == MASK || segment.eq_ignore_ascii_case("<home>") {
+            out.push_str(segment);
+        } else {
+            out.push_str(MASK);
+        }
+        cursor = name_end;
+    }
+    out
+}
+
+/// 找最靠前的用户目录标记，返回 `(字节位置, 标记长度)`。标记须与 `lower` 同源。
+fn find_marker(lower: &str, from: usize) -> Option<(usize, usize)> {
+    const MARKERS: [&str; 3] = ["c:\\users\\", "/home/", "/users/"];
+    MARKERS
+        .iter()
+        .filter_map(|m| lower[from..].find(m).map(|p| (from + p, m.len())))
+        .min_by_key(|(start, _)| *start)
+}
+
+/// 从 `from` 起取到下一个路径分隔符/空白/引号为止。
+fn segment_end(text: &str, from: usize) -> usize {
+    const STOPS: [char; 9] = ['\\', '/', '"', '\'', ' ', '\t', '\n', '\r', ','];
+    text[from..]
+        .find(STOPS)
+        .map_or(text.len(), |offset| from + offset)
+}
+
+/// `Bearer <token>` → `Bearer ***`。
+fn mask_bearer(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut cursor = 0usize;
+    while let Some(pos) = text[cursor..].find("Bearer ") {
+        let token_start = cursor + pos + "Bearer ".len();
+        let token_end = segment_end(text, token_start);
+        out.push_str(&text[cursor..token_start]);
+        if token_end > token_start {
+            out.push_str(MASK);
+        }
+        cursor = token_end;
+    }
+    out.push_str(&text[cursor..]);
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn masks_sensitive_arg_keys_only() {
+        let args = json!({
+            "path": "launcher.theme",
+            "value": "light",
+            "nested": { "accessToken": "abc", "keep": 1 },
+            "list": [{ "password": "p" }]
+        });
+        let red = redact_args(&args);
+        // 非敏感路径：值原样保留（审计要能看出改成了什么）
+        assert_eq!(red["value"], json!("light"));
+        assert_eq!(red["path"], json!("launcher.theme"));
+        // 键名敏感：值掩码
+        assert_eq!(red["nested"]["accessToken"], json!(MASK));
+        assert_eq!(red["nested"]["keep"], json!(1));
+        assert_eq!(red["list"][0]["password"], json!(MASK));
+    }
+
+    #[test]
+    fn masks_value_when_path_itself_is_sensitive() {
+        // `set_config {path: "ai.api_key", value: "sk-…"}` 是最容易漏的泄漏点
+        let args = json!({ "path": "ai.api_key", "value": "sk-super-secret" });
+        let red = redact_args(&args);
+        assert_eq!(red["value"], json!(MASK));
+        let rendered = red.to_string();
+        assert!(!rendered.contains("sk-super-secret"), "{rendered}");
+    }
+
+    #[test]
+    fn masks_windows_and_posix_home() {
+        assert_eq!(
+            redact_text(r"C:\Users\aska\.minecraft\logs\latest.log"),
+            r"C:\Users\***\.minecraft\logs\latest.log"
+        );
+        assert_eq!(
+            redact_text("/home/aska/.minecraft/logs"),
+            "/home/***/.minecraft/logs"
+        );
+    }
+
+    #[test]
+    fn keeps_already_redacted_and_is_idempotent() {
+        let once = redact_text(r"C:\Users\aska\game\log.txt");
+        assert_eq!(once, r"C:\Users\***\game\log.txt");
+        assert_eq!(redact_text(&once), once);
+        assert_eq!(redact_text("<home>/.minecraft"), "<home>/.minecraft");
+    }
+
+    #[test]
+    fn masks_bearer_token() {
+        assert_eq!(
+            redact_text("Authorization: Bearer eyJhbGciOi.payload.sig"),
+            "Authorization: Bearer ***"
+        );
+    }
+
+    #[test]
+    fn detects_sensitive_key_names() {
+        assert!(is_sensitive_key("ai.api_key"));
+        assert!(is_sensitive_key("AccessToken"));
+        assert!(is_sensitive_key("proxy.password"));
+        assert!(!is_sensitive_key("download.concurrency"));
+    }
+}

crates/agent/src/registry/mod.rs

@@ -0,0 +1,260 @@
+//! 工具注册表：整个 agent 的**唯一真相源**。
+//!
+//! 一个 `ToolSpec`（名称 + 描述 + serde JSON Schema）投影两份：
+//! - 内置客户端的 rig `DynamicTool` 视图；
+//! - 对外 MCP server 的 rmcp `ToolRouter` 视图。
+//!
+//! 两份投影必须一致，用契约测试固定（同 name / 同 description / 同 schema）。
+//! 设计依据：`DevDocs/PlanDoc/02-ai-agent-design.md` §1。
+//!
+//! 工具 v1 清单（M16 起，M39 扩到十个）：`get_config` / `set_config` / `get_config_schema` /
+//! `list_instances` / `list_versions` / `get_java_status` / `list_accounts` /
+//! `list_game_sessions` / `read_game_log` / `diagnose_crash`。
+//!
+//! 安全策略随工具走：敏感键分级确认、YOLO 模式标记、审计留痕（02 §3.1 / §4b）。
+//!
+//! ## 落地形态
+//!
+//! ```text
+//! registry（Vec<ToolSpec>）
+//!   ├─ definitions() → rig `DynamicTool::new`    （内置 agent，`brain::rig`）
+//!   └─ definitions() → rmcp `ToolRoute::new_dyn` （外部 MCP，`mcp::projection`）
+//! ```
+//!
+//! 防漂移的关键一招（research/02 §6.2 建议进 CI）：**契约测试**遍历注册表，断言两侧
+//! 投影拿到的 `(name, description, schema)` 逐字节相等。因为两侧都只吃
+//! [`ToolDefinition`]，这条约束在本 crate 里天然成立——测试只需要锁住
+//! 「definition 是纯投影」+「schema 根必须是 object」+「名字不重复」。
+//!
+//! 注册表**不持有任何端口**：工具闭包在构造时就捕获了 `Arc<dyn …Port>`，注册表只是索引。
+
+pub mod schema;
+pub mod spec;
+pub mod validate;
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::fmt;
+use std::sync::Arc;
+
+pub use spec::{
+    Access, Confirmation, ToolCtx, ToolDefinition, ToolError, ToolFn, ToolOutput, ToolSpec,
+};
+
+/// 注册失败原因。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RegistryError {
+    /// 工具名为空或重复。
+    DuplicateName(String),
+    /// schema 不合法（根必须是 `type: object`，否则 MCP 侧直接拒收）。
+    InvalidSchema {
+        /// 工具名。
+        tool: String,
+        /// 原因。
+        reason: String,
+    },
+    /// 说明为空（模型靠 description 选工具，空说明等于没有这个工具）。
+    EmptyDescription(String),
+}
+
+impl fmt::Display for RegistryError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::DuplicateName(name) => write!(f, "工具名重复或为空：`{name}`"),
+            Self::InvalidSchema { tool, reason } => {
+                write!(f, "工具 `{tool}` 的 schema 不合法：{reason}")
+            }
+            Self::EmptyDescription(name) => write!(f, "工具 `{name}` 缺少说明"),
+        }
+    }
+}
+
+impl std::error::Error for RegistryError {}
+
+/// 工具注册表。
+#[derive(Debug, Default, Clone)]
+pub struct ToolRegistry {
+    specs: Vec<Arc<ToolSpec>>,
+    index: BTreeMap<String, usize>,
+}
+
+impl ToolRegistry {
+    /// 空注册表。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 注册一个工具。注册即校验名/schema/说明，**运行时不再做二次判断**。
+    ///
+    /// # Errors
+    /// 名字重复或为空、schema 根不是 object、说明为空时返回 [`RegistryError`]。
+    pub fn register(&mut self, spec: ToolSpec) -> Result<(), RegistryError> {
+        let name = spec.name.trim();
+        if name.is_empty() || self.index.contains_key(name) {
+            return Err(RegistryError::DuplicateName(name.to_string()));
+        }
+        if spec.description.trim().is_empty() {
+            return Err(RegistryError::EmptyDescription(name.to_string()));
+        }
+        if spec.input_schema.get("type").and_then(|t| t.as_str()) != Some("object") {
+            return Err(RegistryError::InvalidSchema {
+                tool: name.to_string(),
+                reason: "根类型必须是 object（rig 与 rmcp 的入参都是对象 schema）".to_string(),
+            });
+        }
+        self.index.insert(name.to_string(), self.specs.len());
+        self.specs.push(Arc::new(spec));
+        Ok(())
+    }
+
+    /// 按名查找。
+    #[must_use]
+    pub fn get(&self, name: &str) -> Option<&Arc<ToolSpec>> {
+        self.index.get(name).and_then(|i| self.specs.get(*i))
+    }
+
+    /// 全部工具（按注册顺序，模型看到的顺序稳定）。
+    #[must_use]
+    pub fn specs(&self) -> &[Arc<ToolSpec>] {
+        &self.specs
+    }
+
+    /// 工具名列表（错误提示/审计用）。
+    #[must_use]
+    pub fn names(&self) -> Vec<&str> {
+        self.specs.iter().map(|s| s.name).collect()
+    }
+
+    /// 工具数量。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.specs.len()
+    }
+
+    /// 是否没有工具。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.specs.is_empty()
+    }
+
+    /// **投影 1/2 的公共载荷**：`(name, description, input_schema)`。
+    #[must_use]
+    pub fn definitions(&self) -> Vec<ToolDefinition> {
+        self.specs.iter().map(|s| s.definition()).collect()
+    }
+
+    /// 只读子集（P1 的 `--readonly` 外部 MCP 模式用）。
+    #[must_use]
+    pub fn read_only_definitions(&self) -> Vec<ToolDefinition> {
+        self.specs
+            .iter()
+            .filter(|s| s.access == Access::ReadOnly)
+            .map(|s| s.definition())
+            .collect()
+    }
+
+    /// **只读模式**的注册表副本（外部 MCP 默认形态）。
+    ///
+    /// 返回的是「物理上不含写工具」的新注册表：`tools/list` 里看不到 `set_config`，
+    /// 硬调它也会在编排层得到 `unknown_tool`（并留一条审计），而不是静默执行。
+    /// 这比「列表过滤 + 调用拦截」两套逻辑更不容易漏——只有一份子集，两侧天然一致。
+    #[must_use]
+    pub fn read_only_subset(&self) -> Self {
+        let mut subset = Self::new();
+        for spec in self.specs.iter().filter(|s| s.access == Access::ReadOnly) {
+            let name = spec.name.to_string();
+            if subset.index.insert(name, subset.specs.len()).is_none() {
+                subset.specs.push(Arc::clone(spec));
+            }
+        }
+        subset
+    }
+
+    /// 名 → access（装配处检查白名单/只读模式）。
+    #[must_use]
+    pub fn access_of(&self, name: &str) -> Option<Access> {
+        self.get(name).map(|s| s.access)
+    }
+
+    /// 去重后的名字集合（契约测试用）。
+    #[must_use]
+    pub fn unique_names(&self) -> BTreeSet<&str> {
+        self.specs.iter().map(|s| s.name).collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::registry::schema::{non_empty_string, object};
+    use serde_json::{json, Value};
+
+    fn echo(name: &'static str) -> ToolSpec {
+        ToolSpec::read_only(
+            name,
+            "回显",
+            object(&[("text", non_empty_string("文本"))], &["text"]),
+            Arc::new(|_ctx: &ToolCtx, args: &Value| Ok(ToolOutput::ok(args.clone(), "echo"))),
+        )
+    }
+
+    #[test]
+    fn register_and_lookup() {
+        let mut reg = ToolRegistry::new();
+        reg.register(echo("echo")).unwrap();
+        assert_eq!(reg.len(), 1);
+        assert_eq!(reg.names(), vec!["echo"]);
+        assert!(reg.get("echo").is_some());
+        assert!(reg.get("nope").is_none());
+        assert_eq!(reg.access_of("echo"), Some(Access::ReadOnly));
+    }
+
+    #[test]
+    fn rejects_duplicate_empty_and_non_object_schema() {
+        let mut reg = ToolRegistry::new();
+        reg.register(echo("echo")).unwrap();
+        assert_eq!(
+            reg.register(echo("echo")),
+            Err(RegistryError::DuplicateName("echo".into()))
+        );
+
+        let bad = ToolSpec::read_only(
+            "bad",
+            "x",
+            json!({ "type": "array" }),
+            Arc::new(|_, _| Ok(ToolOutput::ok(Value::Null, "x"))),
+        );
+        assert!(matches!(
+            reg.register(bad),
+            Err(RegistryError::InvalidSchema { .. })
+        ));
+
+        let no_desc = ToolSpec::read_only(
+            "nodesc",
+            "  ",
+            json!({ "type": "object" }),
+            Arc::new(|_, _| Ok(ToolOutput::ok(Value::Null, "x"))),
+        );
+        assert!(matches!(
+            reg.register(no_desc),
+            Err(RegistryError::EmptyDescription(_))
+        ));
+    }
+
+    #[test]
+    fn definitions_are_stable_and_filterable() {
+        let mut reg = ToolRegistry::new();
+        reg.register(echo("a")).unwrap();
+        reg.register(ToolSpec::mutating(
+            "b",
+            "写",
+            json!({ "type": "object" }),
+            Arc::new(|_, _| Ok(ToolOutput::ok(Value::Null, "b"))),
+        ))
+        .unwrap();
+        assert_eq!(reg.definitions().len(), 2);
+        assert_eq!(reg.read_only_definitions().len(), 1);
+        assert_eq!(reg.definitions()[0].name, "a");
+        assert_eq!(reg.unique_names().len(), 2);
+    }
+}

crates/agent/src/registry/schema.rs

@@ -0,0 +1,116 @@
+//! JSON Schema 构造helper。
+//!
+//! 工具参数 schema 一律**手写 JSON**（research/02 §6.2：`rig` 的 `DynamicTool::new` 与
+//! rmcp 的 `ToolRoute::new_dyn` 吃的都是裸 `serde_json::Value`），所以不需要 schemars 派生。
+//! 手写的好处是同一份 schema 直接喂两方，坏处是啰嗦——这个模块把啰嗦收敛到几个函数。
+//!
+//! 生成的 schema 一律按 **JSON Schema 2020-12** 的写法（rmcp 支持该版本；
+//! `additionalProperties: false` 让模型少给野参数，[`super::validate`] 会执行它）。
+
+use serde_json::{json, Map, Value};
+
+/// 对象 schema。`properties` 按给定顺序写入（JSON 对象保序，UI 展示稳定）。
+#[must_use]
+pub fn object(properties: &[(&str, Value)], required: &[&str]) -> Value {
+    let mut props = Map::new();
+    for (name, schema) in properties {
+        props.insert((*name).to_string(), schema.clone());
+    }
+    json!({
+        "type": "object",
+        "properties": Value::Object(props),
+        "required": required,
+        "additionalProperties": false,
+    })
+}
+
+/// 任意 JSON 值（不校验类型）。
+#[must_use]
+pub fn any() -> Value {
+    json!({})
+}
+
+/// 字符串。
+#[must_use]
+pub fn string(description: &str) -> Value {
+    json!({ "type": "string", "description": description })
+}
+
+/// 非空字符串（`minLength: 1`，省掉一堆「路径不能为空」的运行时判断）。
+#[must_use]
+pub fn non_empty_string(description: &str) -> Value {
+    json!({ "type": "string", "description": description, "minLength": 1 })
+}
+
+/// 枚举字符串。
+#[must_use]
+pub fn string_enum(values: &[&str], description: &str) -> Value {
+    json!({ "type": "string", "description": description, "enum": values })
+}
+
+/// 布尔。
+#[must_use]
+pub fn boolean(description: &str) -> Value {
+    json!({ "type": "boolean", "description": description })
+}
+
+/// 带范围约束的整数。
+#[must_use]
+pub fn integer(description: &str, minimum: i64, maximum: i64) -> Value {
+    json!({
+        "type": "integer",
+        "description": description,
+        "minimum": minimum,
+        "maximum": maximum,
+    })
+}
+
+/// 字符串数组（可选条数上限）。
+#[must_use]
+pub fn string_array(description: &str, max_items: u64) -> Value {
+    json!({
+        "type": "array",
+        "description": description,
+        "items": { "type": "string" },
+        "maxItems": max_items,
+    })
+}
+
+/// 枚举字符串数组（如 `kinds: ["stderr","exit"]`）。
+#[must_use]
+pub fn enum_string_array(values: &[&str], description: &str, max_items: u64) -> Value {
+    json!({
+        "type": "array",
+        "description": description,
+        "items": { "type": "string", "enum": values },
+        "maxItems": max_items,
+        "uniqueItems": true,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::registry::validate::validate;
+
+    #[test]
+    fn object_records_required_and_forbids_extras() {
+        let schema = object(
+            &[("path", non_empty_string("键路径")), ("value", any())],
+            &["path", "value"],
+        );
+        assert_eq!(schema["type"], json!("object"));
+        assert_eq!(schema["additionalProperties"], json!(false));
+        assert_eq!(schema["required"], json!(["path", "value"]));
+        assert!(validate(&schema, &json!({ "path": "a", "value": 1 })).is_ok());
+    }
+
+    #[test]
+    fn integer_builder_carries_bounds() {
+        let schema = integer("条数", 1, 500);
+        assert_eq!(schema["minimum"], json!(1));
+        assert_eq!(schema["maximum"], json!(500));
+        assert!(validate(&schema, &json!(0)).is_err());
+        assert!(validate(&schema, &json!(500)).is_ok());
+    }
+}

crates/agent/src/registry/spec.rs

@@ -0,0 +1,262 @@
+//! 工具的**唯一定义类型**（[`ToolSpec`]）与它的两份投影载荷（[`ToolDefinition`]）。
+//!
+//! 双投影的支点在 research/02 §6.2：`rig::tool::DynamicTool::new(name, description,
+//! parameters: serde_json::Value, ..)` 与 `rmcp::ToolRoute::new_dyn(name, description,
+//! schema, handler)` 的入参**都是裸 JSON Schema**。所以本 crate 只维护一份
+//! [`ToolSpec`]，由 [`ToolSpec::definition`] 生成两侧共用的 `(name, description, schema)`。
+//!
+//! 工具实现是**同步**的：端口调用全是本地文件/内存，没有网络 IO；异步只存在于
+//! provider 边界（[`crate::brain::provider::ChatProvider`]）。P1 若出现网络类工具
+//! （mod 搜索/版本安装）再升成 `Fn -> BoxFuture`，不影响调用方语义。
+
+use std::fmt;
+use std::sync::Arc;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use crate::confirm::Sensitivity;
+
+/// 工具的副作用等级（外部 MCP 只读模式、P1 的 `--readonly` 都按它筛）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Access {
+    /// 只读：可以给外部 agent、可以在无确认的情况下调用。
+    ReadOnly,
+    /// 会改用户数据（写配置），受白名单 + 分级确认约束。
+    Mutating,
+}
+
+/// 工具定义的三元组：**双投影就投这个**。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ToolDefinition {
+    /// 工具名（模型可见，`snake_case`）。
+    pub name: String,
+    /// 一句话说明（模型可见）。
+    pub description: String,
+    /// 参数 JSON Schema（2020-12，根类型必须 `object`）。
+    pub input_schema: Value,
+}
+
+/// 工具调用上下文：编排层注入，工具只读。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ToolCtx {
+    /// agent 对话会话 id（审计用；与游戏 session_id 不是一回事）。
+    pub agent_session_id: String,
+    /// 是否已获确认。**只有编排层能置 true**（YOLO 或用户点了允许），
+    /// 工具据此决定「先报价再执行」还是「直接执行」。
+    pub confirmed: bool,
+}
+
+/// 工具的返回。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ToolOutput {
+    /// 给模型/审计的结构化结果（编排层序列化成 JSON 字符串回灌）。
+    pub content: Value,
+    /// 一句话摘要（UI 展示 + 审计 summary）。
+    pub summary: String,
+    /// 非空表示「这次没执行，先要确认」（[`crate::confirm::ConfirmRequest`] 的原料）。
+    pub confirmation: Option<Confirmation>,
+}
+
+/// 待确认的操作详情（dry-run 的产物）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Confirmation {
+    /// 一句话请求（「AI 请求把 X 从 A 改为 B」）。
+    pub summary: String,
+    /// 结构化 diff（`{"path":…,"old":…,"new":…}`）。
+    pub details: Value,
+    /// 敏感等级（决定 YOLO 能不能跳过）。
+    pub sensitivity: Sensitivity,
+}
+
+impl ToolOutput {
+    /// 成功返回。
+    #[must_use]
+    pub fn ok(content: Value, summary: impl Into<String>) -> Self {
+        Self {
+            content,
+            summary: summary.into(),
+            confirmation: None,
+        }
+    }
+
+    /// 需要确认（本次**没有**产生副作用）。
+    #[must_use]
+    pub fn needs_confirmation(
+        summary: impl Into<String>,
+        details: Value,
+        sensitivity: Sensitivity,
+    ) -> Self {
+        let summary = summary.into();
+        Self {
+            content: serde_json::json!({
+                "status": "needs_confirmation",
+                "summary": summary,
+            }),
+            confirmation: Some(Confirmation {
+                summary: summary.clone(),
+                details,
+                sensitivity,
+            }),
+            summary,
+        }
+    }
+}
+
+/// 工具错误。**全部面向用户可读**——它们会作为工具结果回到模型，
+/// 由模型决定重试还是换方案（rmcp 的 `Ok(CallToolResult::error(..))` 同义，
+/// 见 research/02 §3.2：协议级 `Err` 会被客户端吞掉，不能用来报业务错误）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ToolError {
+    /// 参数语义不合法（schema 校验之外的规则，如路径不在白名单）。
+    NotAllowed(String),
+    /// 找不到对象（会话/键/文件）。
+    NotFound(String),
+    /// 端口（M12/M15/M18）报错，文本原样透传。
+    Port(String),
+    /// 工具自身内部错误（不该发生）。
+    Internal(String),
+}
+
+impl ToolError {
+    /// 一句话文案（写日志/审计用）。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        match self {
+            Self::NotAllowed(m) | Self::NotFound(m) | Self::Port(m) | Self::Internal(m) => m,
+        }
+    }
+
+    /// 错误码（审计与 UI 分类用）。
+    #[must_use]
+    pub fn code(&self) -> &'static str {
+        match self {
+            Self::NotAllowed(_) => "not_allowed",
+            Self::NotFound(_) => "not_found",
+            Self::Port(_) => "port_error",
+            Self::Internal(_) => "internal",
+        }
+    }
+}
+
+impl fmt::Display for ToolError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.message())
+    }
+}
+
+impl std::error::Error for ToolError {}
+
+/// 工具处理函数。
+pub type ToolFn = Arc<dyn Fn(&ToolCtx, &Value) -> Result<ToolOutput, ToolError> + Send + Sync>;
+
+/// 一个工具的完整定义 + 实现。
+#[derive(Clone)]
+pub struct ToolSpec {
+    /// 工具名（`snake_case`，同时是 MCP 侧的工具名）。
+    pub name: &'static str,
+    /// 说明。
+    pub description: &'static str,
+    /// 参数 schema（根必须 object）。
+    pub input_schema: Value,
+    /// 副作用等级。
+    pub access: Access,
+    /// 实现。
+    pub handler: ToolFn,
+}
+
+impl fmt::Debug for ToolSpec {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("ToolSpec")
+            .field("name", &self.name)
+            .field("access", &self.access)
+            .finish_non_exhaustive()
+    }
+}
+
+impl ToolSpec {
+    /// 建一个只读工具。
+    #[must_use]
+    pub fn read_only(
+        name: &'static str,
+        description: &'static str,
+        input_schema: Value,
+        handler: ToolFn,
+    ) -> Self {
+        Self {
+            name,
+            description,
+            input_schema,
+            access: Access::ReadOnly,
+            handler,
+        }
+    }
+
+    /// 建一个会改数据的工具。
+    #[must_use]
+    pub fn mutating(
+        name: &'static str,
+        description: &'static str,
+        input_schema: Value,
+        handler: ToolFn,
+    ) -> Self {
+        Self {
+            name,
+            description,
+            input_schema,
+            access: Access::Mutating,
+            handler,
+        }
+    }
+
+    /// 投影成两侧共用的 `(name, description, schema)`。
+    #[must_use]
+    pub fn definition(&self) -> ToolDefinition {
+        ToolDefinition {
+            name: self.name.to_string(),
+            description: self.description.to_string(),
+            input_schema: self.input_schema.clone(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::registry::schema::{non_empty_string, object};
+    use serde_json::json;
+
+    fn echo_handler() -> ToolFn {
+        Arc::new(|_ctx: &ToolCtx, args: &Value| Ok(ToolOutput::ok(args.clone(), "echo")))
+    }
+
+    #[test]
+    fn definition_is_a_pure_projection() {
+        let spec = ToolSpec::read_only(
+            "echo",
+            "回显",
+            object(&[("text", non_empty_string("文本"))], &["text"]),
+            echo_handler(),
+        );
+        let def = spec.definition();
+        assert_eq!(def.name, "echo");
+        assert_eq!(def.description, "回显");
+        assert_eq!(def.input_schema, spec.input_schema);
+        assert_eq!(spec.access, Access::ReadOnly);
+    }
+
+    #[test]
+    fn confirmation_carries_details() {
+        let out = ToolOutput::needs_confirmation(
+            "AI 请求修改 x",
+            json!({ "path": "x" }),
+            Sensitivity::High,
+        );
+        assert_eq!(out.content["status"], json!("needs_confirmation"));
+        let confirmation = out.confirmation.expect("必须有待确认详情");
+        assert_eq!(confirmation.sensitivity, Sensitivity::High);
+        assert_eq!(confirmation.summary, out.summary);
+        assert_eq!(confirmation.details, json!({ "path": "x" }));
+    }
+}

crates/agent/src/registry/validate.rs

@@ -0,0 +1,332 @@
+//! 参数校验：JSON Schema 2020-12 的**最小子集**实现。
+//!
+//! 为什么不引 `jsonschema` crate：agent 的 schema 全是自己手写的（[`super::schema`]），
+//! 用到的关键字只有 `type/required/properties/additionalProperties/enum/minimum/maximum/
+//! minLength/minItems/maxItems/uniqueItems/items`。三百行的校验器换掉一棵依赖树，
+//! 对 Win7 单文件形态（D12）值得。
+//!
+//! 校验失败的文案是给**模型**看的（它会据此改正参数重试），所以要具体：
+//! 「参数 `limit` 必须是 1~500 的整数，实际是 2000」，不是 `schema validation failed`。
+
+use serde_json::Value;
+
+/// 校验入口。返回全部错误（一次给全，省模型来回试错）。
+///
+/// # Errors
+/// 参数不符合 schema 时返回人类可读的错误列表。
+pub fn validate(schema: &Value, args: &Value) -> Result<(), Vec<String>> {
+    let mut errors = Vec::new();
+    validate_at(schema, args, "", &mut errors);
+    if errors.is_empty() {
+        Ok(())
+    } else {
+        Err(errors)
+    }
+}
+
+/// 只取第一条错误（日志/审计摘要用）。
+#[must_use]
+pub fn first_error(schema: &Value, args: &Value) -> Option<String> {
+    validate(schema, args)
+        .err()
+        .and_then(|errors| errors.into_iter().next())
+}
+
+fn validate_at(schema: &Value, value: &Value, path: &str, errors: &mut Vec<String>) {
+    let Some(schema) = schema.as_object() else {
+        return; // `{}` = 任意值
+    };
+
+    if let Some(expected) = schema.get("type").and_then(Value::as_str) {
+        if !type_matches(expected, value) {
+            errors.push(format!(
+                "参数 {} 应为 {}，实际是 {}",
+                label(path),
+                expected,
+                type_name(value)
+            ));
+            return; // 类型都不对，后面的范围检查没有意义
+        }
+    }
+
+    if let Some(allowed) = schema.get("enum").and_then(Value::as_array) {
+        if !allowed.iter().any(|v| v == value) {
+            let list: Vec<String> = allowed.iter().map(render).collect();
+            errors.push(format!(
+                "参数 {} 只能取 [{}]，实际是 {}",
+                label(path),
+                list.join(", "),
+                render(value)
+            ));
+        }
+    }
+
+    check_bounds(schema, value, path, errors);
+
+    match value {
+        Value::Object(map) => {
+            let required = schema.get("required").and_then(Value::as_array);
+            for name in required.into_iter().flatten().filter_map(Value::as_str) {
+                if !map.contains_key(name) {
+                    errors.push(format!("缺少必填参数 {}", label(&join(path, name))));
+                }
+            }
+            let properties = schema.get("properties").and_then(Value::as_object);
+            for (key, entry) in map {
+                match properties.and_then(|p| p.get(key)) {
+                    Some(sub) => validate_at(sub, entry, &join(path, key), errors),
+                    None => {
+                        if schema.get("additionalProperties").and_then(Value::as_bool)
+                            == Some(false)
+                        {
+                            let known: Vec<&str> = properties
+                                .map(|p| p.keys().map(String::as_str).collect())
+                                .unwrap_or_default();
+                            errors.push(format!(
+                                "参数 {} 不是可接受的参数名（可用：{}）",
+                                label(&join(path, key)),
+                                if known.is_empty() {
+                                    "无".to_string()
+                                } else {
+                                    known.join(", ")
+                                }
+                            ));
+                        }
+                    }
+                }
+            }
+        }
+        Value::Array(items) => {
+            if let Some(sub) = schema.get("items") {
+                for (i, item) in items.iter().enumerate() {
+                    validate_at(sub, item, &format!("{path}[{i}]"), errors);
+                }
+            }
+        }
+        _ => {}
+    }
+}
+
+fn check_bounds(
+    schema: &serde_json::Map<String, Value>,
+    value: &Value,
+    path: &str,
+    errors: &mut Vec<String>,
+) {
+    let number = value.as_f64();
+    let minimum = schema.get("minimum").and_then(Value::as_f64);
+    let maximum = schema.get("maximum").and_then(Value::as_f64);
+    if let (Some(n), Some(min), Some(max)) = (number, minimum, maximum) {
+        if n < min || n > max {
+            errors.push(format!(
+                "参数 {} 必须在 {}~{} 之间，实际是 {}",
+                label(path),
+                render_number(min),
+                render_number(max),
+                render_number(n)
+            ));
+            return;
+        }
+    } else if let (Some(n), Some(min)) = (number, minimum) {
+        if n < min {
+            errors.push(format!(
+                "参数 {} 不能小于 {}，实际是 {}",
+                label(path),
+                render_number(min),
+                render_number(n)
+            ));
+        }
+    } else if let (Some(n), Some(max)) = (number, maximum) {
+        if n > max {
+            errors.push(format!(
+                "参数 {} 不能大于 {}，实际是 {}",
+                label(path),
+                render_number(max),
+                render_number(n)
+            ));
+        }
+    }
+
+    if let Some(text) = value.as_str() {
+        if let Some(min_len) = schema.get("minLength").and_then(Value::as_u64) {
+            if (text.chars().count() as u64) < min_len {
+                errors.push(format!(
+                    "参数 {} 不能为空（最少 {} 个字符）",
+                    label(path),
+                    min_len
+                ));
+            }
+        }
+    }
+
+    if let Some(items) = value.as_array() {
+        if let Some(max_items) = schema.get("maxItems").and_then(Value::as_u64) {
+            if items.len() as u64 > max_items {
+                errors.push(format!(
+                    "参数 {} 最多 {} 项，实际 {} 项",
+                    label(path),
+                    max_items,
+                    items.len()
+                ));
+            }
+        }
+        if let Some(min_items) = schema.get("minItems").and_then(Value::as_u64) {
+            if (items.len() as u64) < min_items {
+                errors.push(format!(
+                    "参数 {} 至少 {} 项，实际 {} 项",
+                    label(path),
+                    min_items,
+                    items.len()
+                ));
+            }
+        }
+        if schema.get("uniqueItems").and_then(Value::as_bool) == Some(true) {
+            if let Some(duplicate) = first_duplicate(items) {
+                errors.push(format!(
+                    "参数 {} 不能有重复项（{} 出现了多次）",
+                    label(path),
+                    render(duplicate)
+                ));
+            }
+        }
+    }
+}
+
+/// 数组里第一个重复出现的元素（`uniqueItems` 用；`null` 也算一个值）。
+fn first_duplicate(items: &[Value]) -> Option<&Value> {
+    items
+        .iter()
+        .enumerate()
+        .find(|(index, item)| items.iter().take(*index).any(|prev| prev == *item))
+        .map(|(_, item)| item)
+}
+
+fn type_matches(expected: &str, value: &Value) -> bool {
+    match expected {
+        "object" => value.is_object(),
+        "array" => value.is_array(),
+        "string" => value.is_string(),
+        "boolean" => value.is_boolean(),
+        "null" => value.is_null(),
+        "integer" => value.as_f64().is_some_and(|n| n.fract() == 0.0),
+        "number" => value.is_number(),
+        _ => true, // 未知关键字不拦（前向兼容）
+    }
+}
+
+fn type_name(value: &Value) -> &'static str {
+    match value {
+        Value::Null => "null",
+        Value::Bool(_) => "boolean",
+        Value::Number(n) if n.as_f64().is_some_and(|f| f.fract() == 0.0) => "integer",
+        Value::Number(_) => "number",
+        Value::String(_) => "string",
+        Value::Array(_) => "array",
+        Value::Object(_) => "object",
+    }
+}
+
+fn label(path: &str) -> String {
+    if path.is_empty() {
+        "（根）".to_string()
+    } else {
+        format!("`{path}`")
+    }
+}
+
+fn join(path: &str, key: &str) -> String {
+    if path.is_empty() {
+        key.to_string()
+    } else {
+        format!("{path}.{key}")
+    }
+}
+
+fn render(value: &Value) -> String {
+    match value {
+        Value::String(s) => format!("\"{s}\""),
+        other => other.to_string(),
+    }
+}
+
+fn render_number(n: f64) -> String {
+    if n.fract() == 0.0 {
+        format!("{}", n as i64)
+    } else {
+        n.to_string()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::registry::schema::{
+        enum_string_array, integer, non_empty_string, object, string_array, string_enum,
+    };
+    use serde_json::json;
+
+    fn errors(schema: &Value, args: &Value) -> Vec<String> {
+        validate(schema, args).unwrap_err()
+    }
+
+    #[test]
+    fn accepts_valid_and_reports_missing_required() {
+        let schema = object(
+            &[("session_id", non_empty_string("会话 id"))],
+            &["session_id"],
+        );
+        assert!(validate(&schema, &json!({ "session_id": "20261029T124501-9f3c2a" })).is_ok());
+        let errs = errors(&schema, &json!({}));
+        assert_eq!(errs.len(), 1);
+        assert!(errs[0].contains("缺少必填参数 `session_id`"), "{errs:?}");
+    }
+
+    #[test]
+    fn rejects_empty_string_and_wrong_type() {
+        let schema = object(
+            &[("session_id", non_empty_string("会话 id"))],
+            &["session_id"],
+        );
+        assert!(errors(&schema, &json!({ "session_id": "" }))[0].contains("不能为空"));
+        assert!(errors(&schema, &json!({ "session_id": 1 }))[0].contains("应为 string"));
+    }
+
+    #[test]
+    fn rejects_out_of_range_and_unknown_keys() {
+        let schema = object(
+            &[
+                ("limit", integer("条数", 1, 500)),
+                ("kinds", string_array("类型", 8)),
+            ],
+            &[],
+        );
+        let errs = errors(&schema, &json!({ "limit": 2000 }));
+        assert!(errs[0].contains("1~500"), "{errs:?}");
+        let errs = errors(&schema, &json!({ "limit": 1, "evil": true }));
+        assert!(errs[0].contains("不是可接受的参数名"), "{errs:?}");
+    }
+
+    #[test]
+    fn checks_enum_and_nested_objects() {
+        let schema = object(&[("level", string_enum(&["error", "warn"], "级别"))], &[]);
+        assert!(validate(&schema, &json!({ "level": "error" })).is_ok());
+        assert!(errors(&schema, &json!({ "level": "fatal" }))[0].contains("只能取"));
+    }
+
+    #[test]
+    fn rejects_duplicate_items_when_unique() {
+        let schema = object(
+            &[("kinds", enum_string_array(&["stderr", "exit"], "类型", 4))],
+            &[],
+        );
+        let errs = errors(&schema, &json!({ "kinds": ["stderr", "exit", "stderr"] }));
+        assert!(errs[0].contains("不能有重复项"), "{errs:?}");
+        assert!(validate(&schema, &json!({ "kinds": ["stderr", "exit"] })).is_ok());
+    }
+
+    #[test]
+    fn integer_type_rejects_fraction() {
+        assert!(validate(&json!({ "type": "integer" }), &json!(1.5)).is_err());
+        assert!(validate(&json!({ "type": "integer" }), &json!(2.0)).is_ok());
+    }
+}

crates/agent/src/testing.rs

@@ -0,0 +1,190 @@
+//! 测试替身：五个端口的 **mock 实现**（无盘、无网络、无时间依赖）。
+//!
+//! 放在库内（而不是只在 `#[cfg(test)]`）是刻意的：`crates/app` 装配时也要能给
+//! 自己的单测造一套「无盘」环境，且 P1/M39 的 MCP 契约测试要复用同一批假数据。
+//!
+//! 按端口拆文件（`port.rs` 挨 400 行上限的同款理由）：`settings` 配置、`sessions`
+//! 会话日志在下面，`game` 实例/Java/账户与 `diagnose` 诊断各一个子模块。
+//! 对外名字不变，`unlucky_agent::testing::MockSettings` 之类照旧可用（走 re-export）。
+
+pub mod diagnose;
+pub mod game;
+pub mod settings;
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde_json::{json, Value};
+
+use crate::port::{GameSessionPort, GameSessionSummary, LogEvent, LogPage, LogQuery, PortResult};
+
+pub use diagnose::MockDiagnose;
+pub use game::{MockAccounts, MockGame};
+pub use settings::MockSettings;
+
+/// 内存会话端口。
+#[derive(Debug, Default)]
+pub struct MockSessions {
+    sessions: Vec<GameSessionSummary>,
+    events: BTreeMap<String, Vec<LogEvent>>,
+}
+
+impl MockSessions {
+    /// 空数据。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 加一个会话及其事件流。
+    pub fn add(&mut self, summary: GameSessionSummary, events: Vec<LogEvent>) {
+        self.events.insert(summary.session_id.clone(), events);
+        self.sessions.push(summary);
+    }
+
+    /// 便捷：造一个崩溃会话（`exit_code=1` + stderr + crash_found）。
+    #[must_use]
+    pub fn crashing_session(session_id: &str) -> (GameSessionSummary, Vec<LogEvent>) {
+        let summary = GameSessionSummary {
+            session_id: session_id.to_string(),
+            instance_id: Some("inst-1".to_string()),
+            instance_name: Some("1.20.1 Forge".to_string()),
+            game_version: Some("1.20.1".to_string()),
+            started_at: Some("2026-10-29T12:45:01.123Z".to_string()),
+            ended_at: Some("2026-10-29T12:46:31.123Z".to_string()),
+            duration_ms: 90_000,
+            exit_code: Some(1),
+            exit_type: Some("application_error".to_string()),
+            silent_failure: false,
+            window_detected: true,
+            event_count: 5,
+            crash_found: true,
+            diagnosis_top: Some("forge_missing_library".to_string()),
+        };
+        let events = vec![
+            event(
+                0,
+                "stdout",
+                json!({ "line": "Starting Minecraft 1.20.1", "level": "info" }),
+            ),
+            event(
+                1,
+                "stderr",
+                json!({ "line": "java.lang.NoClassDefFoundError: cpw/mods/bootstraplauncher/BootstrapLauncher", "level": "error" }),
+            ),
+            event(
+                2,
+                "crash_found",
+                json!({ "source": "crash_report", "path": r"C:\Users\aska\.minecraft\crash-reports\crash-1.txt", "excerpt": "Description: Mod loading failure" }),
+            ),
+            event(
+                3,
+                "exit",
+                json!({ "code": 1, "exit_type": "application_error", "silent_failure": false }),
+            ),
+            event(
+                4,
+                "session_end",
+                json!({ "reason": "exit", "duration_ms": 90000 }),
+            ),
+        ];
+        (summary, events)
+    }
+}
+
+fn event(seq: u64, kind: &str, payload: Value) -> LogEvent {
+    LogEvent {
+        seq,
+        ts: format!("2026-10-29T12:45:0{seq}.000Z"),
+        t_ms: seq * 1_000,
+        kind: kind.to_string(),
+        payload,
+    }
+}
+
+impl GameSessionPort for MockSessions {
+    fn list_sessions(
+        &self,
+        limit: usize,
+        instance_id: Option<&str>,
+    ) -> PortResult<Vec<GameSessionSummary>> {
+        let mut out: Vec<GameSessionSummary> = self
+            .sessions
+            .iter()
+            .filter(|s| instance_id.is_none_or(|id| s.instance_id.as_deref() == Some(id)))
+            .cloned()
+            .collect();
+        out.sort_by(|a, b| b.started_at.cmp(&a.started_at));
+        out.truncate(limit);
+        Ok(out)
+    }
+
+    fn read_log(&self, session_id: &str, query: &LogQuery) -> PortResult<LogPage> {
+        let events = self
+            .events
+            .get(session_id)
+            .ok_or_else(|| format!("会话 `{session_id}` 不存在"))?;
+        let mut kind_counts = BTreeMap::new();
+        for event in events {
+            *kind_counts.entry(event.kind.clone()).or_insert(0u64) += 1;
+        }
+        let matched: Vec<&LogEvent> = events
+            .iter()
+            .filter(|e| query.from_seq.is_none_or(|from| e.seq >= from))
+            .filter(|e| query.to_seq.is_none_or(|to| e.seq <= to))
+            .filter(|e| query.kinds.is_empty() || query.kinds.contains(&e.kind))
+            .collect();
+        let max = if query.max_events == 0 {
+            matched.len()
+        } else {
+            query.max_events
+        };
+        let truncated = matched.len() > max;
+        Ok(LogPage {
+            session_id: session_id.to_string(),
+            total_events: events.len() as u64,
+            matched_events: matched.len() as u64,
+            truncated,
+            kind_counts,
+            first_ts: events.first().map(|e| e.ts.clone()),
+            last_ts: events.last().map(|e| e.ts.clone()),
+            events: matched.into_iter().take(max).cloned().collect(),
+        })
+    }
+}
+
+/// 一次性造好全部端口的 [`crate::port::Ports`]（含一个崩溃会话，够跑通对话与日志工具）。
+#[must_use]
+pub fn mock_ports() -> (crate::port::Ports, std::sync::Arc<MockSettings>) {
+    use std::sync::Arc;
+    let settings = Arc::new(MockSettings::new());
+    let (summary, events) = MockSessions::crashing_session("20261029T124501-9f3c2a");
+    let mut sessions = MockSessions::new();
+    sessions.add(summary, events);
+    let ports = crate::port::Ports {
+        setting: settings.clone(),
+        sessions: Arc::new(sessions),
+        diagnose: Arc::new(MockDiagnose::new()),
+        game: Arc::new(MockGame::new()),
+        accounts: Arc::new(MockAccounts::new()),
+    };
+    (ports, settings)
+}
+
+/// 测试里常用的「全部工具名」集合（契约测试与 MCP 投影比对用）。
+#[must_use]
+pub fn expected_v1_tool_names() -> BTreeSet<&'static str> {
+    [
+        "get_config",
+        "get_config_schema",
+        "set_config",
+        "list_game_sessions",
+        "read_game_log",
+        "diagnose_crash",
+        "list_instances",
+        "list_versions",
+        "get_java_status",
+        "list_accounts",
+    ]
+    .into_iter()
+    .collect()
+}

crates/agent/src/testing/diagnose.rs

@@ -0,0 +1,87 @@
+//! 内存诊断端口（`DiagnosePort` 的测试替身）。
+
+use crate::port::{
+    CrashDiagnosis, DiagnosePort, DiagnosisCandidate, ExitSummary, FixAction, FixActionKind,
+    PortResult,
+};
+
+/// 内存诊断端口（固定返回一份规则结论）。
+#[derive(Debug, Clone)]
+pub struct MockDiagnose {
+    report: Option<CrashDiagnosis>,
+}
+
+impl Default for MockDiagnose {
+    fn default() -> Self {
+        Self {
+            report: Some(Self::forge_missing_library()),
+        }
+    }
+}
+
+impl MockDiagnose {
+    /// 构造使用默认结论的端口。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 让端口对所有会话返回「会话不存在」。
+    #[must_use]
+    pub fn unavailable() -> Self {
+        Self { report: None }
+    }
+
+    /// 默认结论：Forge 缺库（对应 analyse/02 的高发场景）。
+    #[must_use]
+    pub fn forge_missing_library() -> CrashDiagnosis {
+        CrashDiagnosis {
+            session_id: String::new(),
+            source: "rules".to_string(),
+            needs_more_info: false,
+            candidates: vec![DiagnosisCandidate {
+                id: "integrity.forge_missing_library".to_string(),
+                severity: "error".to_string(),
+                category: "integrity".to_string(),
+                confidence: 0.86,
+                message_key: "diagnose.cause.integrity.forge_missing_library".to_string(),
+                message: "Forge 启动缺少 bootstraplauncher 库，通常是版本组件未下载完整"
+                    .to_string(),
+                detail: "在实例上重装 Forge 组件（或先用官方启动器补全一次再回来）".to_string(),
+                evidence: vec![
+                    "java.lang.NoClassDefFoundError: cpw/mods/bootstraplauncher/BootstrapLauncher"
+                        .to_string(),
+                ],
+                fix_actions: vec![FixAction {
+                    kind: FixActionKind::Reinstall,
+                    tool: "component.reinstall".to_string(),
+                    label: "重装该版本的 Forge 组件".to_string(),
+                    args: [("component".to_string(), "forge".to_string())]
+                        .into_iter()
+                        .collect(),
+                }],
+            }],
+            secondary: Vec::new(),
+            evidence: vec!["Description: Mod loading failure".to_string()],
+            exit: ExitSummary {
+                code: Some(1),
+                exit_type: Some("application_error".to_string()),
+                silent_failure: false,
+            },
+        }
+    }
+}
+
+impl DiagnosePort for MockDiagnose {
+    fn diagnose(&self, session_id: &str) -> PortResult<CrashDiagnosis> {
+        self.report.clone().map_or_else(
+            || Err(format!("会话 `{session_id}` 不存在")),
+            |report| {
+                Ok(CrashDiagnosis {
+                    session_id: session_id.to_string(),
+                    ..report
+                })
+            },
+        )
+    }
+}

crates/agent/src/testing/game.rs

@@ -0,0 +1,158 @@
+//! 实例 / 版本 / Java / 账户四个只读端口的测试替身。
+
+use crate::port::game::{
+    AccountPort, AccountSummary, GamePort, InstanceSummary, JavaRuntimeSummary, JavaStatus,
+    VersionSummary,
+};
+use crate::port::PortResult;
+
+/// 内存游戏端口：一个 1.20.1 Forge 实例 + 两个已安装版本 + 两个 Java 候选。
+#[derive(Debug, Clone)]
+pub struct MockGame {
+    instances: Vec<InstanceSummary>,
+    versions: Vec<VersionSummary>,
+    java: JavaStatus,
+    fail: Option<String>,
+}
+
+impl Default for MockGame {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl MockGame {
+    /// 默认假数据（够跑通 `list_instances` / `list_versions` / `get_java_status`）。
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            instances: vec![InstanceSummary {
+                id: "inst-1".to_string(),
+                name: "1.20.1 Forge".to_string(),
+                version_id: "1.20.1-forge-47.2.20".to_string(),
+                version_present: true,
+                game_dir: None,
+                java_path: Some(r"D:\jdk17\bin\java.exe".to_string()),
+                last_played_at: Some(1_793_304_753_123),
+            }],
+            versions: vec![
+                VersionSummary {
+                    id: "1.20.1-forge-47.2.20".to_string(),
+                    kind: Some("release".to_string()),
+                    instance_count: 1,
+                },
+                VersionSummary {
+                    id: "1.21.1".to_string(),
+                    kind: Some("release".to_string()),
+                    instance_count: 0,
+                },
+            ],
+            java: JavaStatus {
+                default_memory_mb: Some(2048),
+                managed_roots: vec![r"D:\ULL\.ULL\data\java-managed".to_string()],
+                candidates: vec![
+                    JavaRuntimeSummary {
+                        binary: r"D:\ULL\.ULL\data\java-managed\jdk-17-temurin\bin\java.exe"
+                            .to_string(),
+                        version: Some("17.0.13".to_string()),
+                        major: Some(17),
+                        vendor: Some("temurin".to_string()),
+                        origin: "managed".to_string(),
+                    },
+                    JavaRuntimeSummary {
+                        binary: "/usr/bin/java".to_string(),
+                        version: Some("21.0.2".to_string()),
+                        major: Some(21),
+                        vendor: None,
+                        origin: "PATH".to_string(),
+                    },
+                ],
+            },
+            fail: None,
+        }
+    }
+
+    /// 让三个查询全部返回同一个错误（测端口错误透传）。
+    #[must_use]
+    pub fn failing(message: &str) -> Self {
+        Self {
+            fail: Some(message.to_string()),
+            ..Self::new()
+        }
+    }
+
+    fn fail(&self) -> Option<String> {
+        self.fail.clone()
+    }
+}
+
+impl GamePort for MockGame {
+    fn list_instances(&self) -> PortResult<Vec<InstanceSummary>> {
+        self.fail().map_or_else(|| Ok(self.instances.clone()), Err)
+    }
+
+    fn list_versions(&self) -> PortResult<Vec<VersionSummary>> {
+        self.fail().map_or_else(|| Ok(self.versions.clone()), Err)
+    }
+
+    fn java_status(&self) -> PortResult<JavaStatus> {
+        self.fail().map_or_else(|| Ok(self.java.clone()), Err)
+    }
+}
+
+/// 内存账户端口：一个离线账户。**只有公开字段**，凭据无处可放。
+#[derive(Debug, Clone)]
+pub struct MockAccounts {
+    accounts: Vec<AccountSummary>,
+    fail: Option<String>,
+}
+
+impl Default for MockAccounts {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl MockAccounts {
+    /// 一个离线账户（Steve）。
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            accounts: vec![AccountSummary {
+                id: "acc-1".to_string(),
+                kind: "offline".to_string(),
+                profile_id: "8667ba71b85a4004af54457a9734eed7".to_string(),
+                profile_name: "Steve".to_string(),
+                login_name: None,
+                created_at_ms: 1_793_304_753_123,
+            }],
+            fail: None,
+        }
+    }
+
+    /// 空账户列表（测「没有账户」的提示文案）。
+    #[must_use]
+    pub fn empty() -> Self {
+        Self {
+            accounts: Vec::new(),
+            fail: None,
+        }
+    }
+
+    /// 让查询失败（测端口错误透传）。
+    #[must_use]
+    pub fn failing(message: &str) -> Self {
+        Self {
+            fail: Some(message.to_string()),
+            ..Self::new()
+        }
+    }
+}
+
+impl AccountPort for MockAccounts {
+    fn list_accounts(&self) -> PortResult<Vec<AccountSummary>> {
+        self.fail
+            .clone()
+            .map_or_else(|| Ok(self.accounts.clone()), Err)
+    }
+}

crates/agent/src/testing/settings.rs

@@ -0,0 +1,201 @@
+//! 内存配置端口（`SettingPort` 的测试替身）。
+
+use std::collections::BTreeMap;
+use std::sync::Mutex;
+
+use serde_json::{json, Map, Value};
+
+use crate::confirm::Sensitivity;
+use crate::port::{PortResult, SettingChange, SettingKey, SettingPort};
+
+/// 内存配置端口。
+#[derive(Debug, Default)]
+pub struct MockSettings {
+    keys: Vec<SettingKey>,
+    values: Mutex<BTreeMap<String, Value>>,
+    fail_set: Mutex<Option<String>>,
+    set_calls: Mutex<usize>,
+}
+
+/// 与 `PlanDoc/04` §3 / M12 `setting-接口约定.md` §8 的键表一致的默认白名单
+/// （覆盖三档敏感度；`ai.api_key` 这类凭据是 `writable=false`，**故意不在这里**）。
+fn default_keys() -> Vec<SettingKey> {
+    fn key(
+        path: &str,
+        sensitivity: Sensitivity,
+        value_type: &str,
+        description: &str,
+    ) -> SettingKey {
+        SettingKey {
+            path: path.to_string(),
+            sensitivity,
+            value_type: value_type.to_string(),
+            description: description.to_string(),
+        }
+    }
+    vec![
+        key(
+            "appearance.theme_mode",
+            Sensitivity::Low,
+            "enum",
+            "界面主题",
+        ),
+        key(
+            "download.concurrency",
+            Sensitivity::Low,
+            "integer",
+            "下载并发（1~256）",
+        ),
+        key(
+            "java.default_memory_mb",
+            Sensitivity::Low,
+            "integer",
+            "最大内存（512~65536 MB）",
+        ),
+        key("download.region", Sensitivity::Medium, "enum", "下载源区域"),
+        key("ai.model", Sensitivity::Medium, "text", "AI 模型名"),
+        key(
+            "java.selected_path",
+            Sensitivity::High,
+            "path",
+            "Java 可执行文件路径",
+        ),
+        key("download.proxy_url", Sensitivity::High, "text", "HTTP 代理"),
+        key("ai.base_url", Sensitivity::High, "text", "AI 端点"),
+        key(
+            "core.data_mode",
+            Sensitivity::High,
+            "enum",
+            "数据目录模式（portable/standard/custom）",
+        ),
+    ]
+}
+
+impl MockSettings {
+    /// 用默认白名单 + 一批初值造一个。
+    #[must_use]
+    pub fn new() -> Self {
+        let mut values = BTreeMap::new();
+        values.insert("appearance.theme_mode".to_string(), json!("metro_dark"));
+        values.insert("download.concurrency".to_string(), json!(8));
+        values.insert("java.default_memory_mb".to_string(), json!(2048));
+        Self {
+            keys: default_keys(),
+            values: Mutex::new(values),
+            fail_set: Mutex::new(None),
+            set_calls: Mutex::new(0),
+        }
+    }
+
+    /// 让接下来的 `set` 全部失败（测错误透传）。
+    pub fn fail_set_with(&self, message: &str) {
+        if let Ok(mut slot) = self.fail_set.lock() {
+            *slot = Some(message.to_string());
+        }
+    }
+
+    /// 当前值（断言「未确认时没有写进去」）。
+    #[must_use]
+    pub fn value_of(&self, path: &str) -> Option<Value> {
+        self.values.lock().ok().and_then(|v| v.get(path).cloned())
+    }
+
+    /// 直接塞一个值，模拟 M12 真实实现里存在的**任意键**（含凭据键）。
+    ///
+    /// 白名单以外的键也能塞——测「`get_config` 不把凭据读给模型」需要它
+    /// （`ai.api_key` 是 `writable=false`，故意不在白名单里）。
+    pub fn seed_value(&self, path: &str, value: Value) {
+        if let Ok(mut values) = self.values.lock() {
+            values.insert(path.to_string(), value);
+        }
+    }
+
+    /// 成功写入次数。
+    #[must_use]
+    pub fn set_calls(&self) -> usize {
+        self.set_calls.lock().map(|n| *n).unwrap_or(0)
+    }
+}
+
+impl SettingPort for MockSettings {
+    fn summary(&self) -> Value {
+        let values = self.values.lock().map(|v| v.clone()).unwrap_or_default();
+        let mut map = serde_json::Map::new();
+        for key in &self.keys {
+            let value = values.get(&key.path).cloned().unwrap_or(Value::Null);
+            map.insert(key.path.clone(), value);
+        }
+        Value::Object(map)
+    }
+
+    fn get(&self, path: &str) -> PortResult<Value> {
+        self.values
+            .lock()
+            .ok()
+            .and_then(|v| v.get(path).cloned())
+            .ok_or_else(|| format!("配置键 `{path}` 没有值"))
+    }
+
+    fn set(&self, path: &str, value: &Value) -> PortResult<SettingChange> {
+        if let Ok(slot) = self.fail_set.lock() {
+            if let Some(message) = slot.as_ref() {
+                return Err(message.clone());
+            }
+        }
+        let old = self.get(path).ok();
+        if let Ok(mut values) = self.values.lock() {
+            values.insert(path.to_string(), value.clone());
+        }
+        if let Ok(mut calls) = self.set_calls.lock() {
+            *calls += 1;
+        }
+        Ok(SettingChange {
+            path: path.to_string(),
+            old,
+            new: value.clone(),
+        })
+    }
+
+    fn writable_keys(&self) -> Vec<SettingKey> {
+        self.keys.clone()
+    }
+
+    fn schema(&self) -> Value {
+        // 与 `core::setting::catalog::SettingSchema::to_json_schema` 同形：
+        // 只含白名单键 + `x-ai-sensitivity`，凭据键天然缺席。
+        let mut properties = Map::new();
+        for key in &self.keys {
+            properties.insert(
+                key.path.clone(),
+                json!({
+                    "type": key.value_type,
+                    "description": key.description,
+                    "x-ai-sensitivity": key.sensitivity,
+                }),
+            );
+        }
+        json!({
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "title": "ull.launcher",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": properties,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn schema_excludes_credential_keys() {
+        let schema = MockSettings::new().schema();
+        let json = schema.to_string();
+        assert!(
+            !json.contains("ai.api_key"),
+            "schema 不得包含凭据键：{json}"
+        );
+        assert!(json.contains("download.concurrency"));
+    }
+}

crates/agent/src/tools/accounts.rs

@@ -0,0 +1,110 @@
+//! `list_accounts`：账户清单（**凭据永不出口**）。
+//!
+//! 这个工具存在的理由很具体：用户常问「我有哪几个号 / 这局用的是哪个号」。
+//! 但 D4/D9 的凭据红线是硬的——工具结果会回灌模型、也可能被发往远端 LLM，
+//! 所以：
+//! 1. 端口只回 [`crate::port::AccountSummary`]（`AccountMeta` 的公开字段）；
+//! 2. 本文件里**没有任何**能表达 token / 密码的类型（连字段名都不出现）；
+//! 3. 工具结果再过一遍 [`crate::redact`]，兜住实现方把凭据塞进 `profile_name` 的意外。
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::port::AccountPort;
+use crate::registry::schema::object;
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 工具名。
+pub const LIST_ACCOUNTS: &str = "list_accounts";
+
+/// 注册 `list_accounts`。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(
+    registry: &mut ToolRegistry,
+    port: Arc<dyn AccountPort>,
+) -> Result<(), RegistryError> {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, _args: &Value| {
+        let accounts = port.list_accounts().map_err(ToolError::Port)?;
+        let count = accounts.len();
+        let display: Vec<String> = accounts
+            .iter()
+            .map(|a| {
+                if a.profile_name.trim().is_empty() {
+                    format!("{}（{}）", a.id, a.kind)
+                } else {
+                    format!("{}（{}）", a.profile_name, a.kind)
+                }
+            })
+            .collect();
+        let mut content = json!({
+            "count": count,
+            "accounts": accounts,
+            "credential_policy": "账户凭据（access token / 刷新令牌 / authlib 密码）永不经由 AI 工具出口",
+        });
+        // 兜底脱敏：端口实现若把敏感串塞进了公开字段，这里也不会带出去。
+        content = crate::redact::redact_texts(&content);
+        Ok(ToolOutput::ok(
+            content,
+            if count == 0 {
+                "还没有任何账户".to_string()
+            } else {
+                format!("账户 {count} 个：{}", display.join("、"))
+            },
+        ))
+    });
+
+    registry.register(ToolSpec::read_only(
+        LIST_ACCOUNTS,
+        "列出启动器里已登录的账户（展示名 / 轨道 offline|microsoft|authlib / 档案 UUID / 创建时间）。**永不返回任何凭据**：令牌与密码不在工具结果的类型里，需要登录态请让用户在启动器界面查看。",
+        object(&[], &[]),
+        handler,
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockAccounts;
+
+    fn registry(port: Arc<dyn AccountPort>) -> ToolRegistry {
+        let mut registry = ToolRegistry::new();
+        register(&mut registry, port).expect("注册应成功");
+        registry
+    }
+
+    fn call(registry: &ToolRegistry) -> Value {
+        let spec = registry.get(LIST_ACCOUNTS).expect("工具存在").clone();
+        let ctx = ToolCtx {
+            agent_session_id: "s1".to_string(),
+            confirmed: false,
+        };
+        (spec.handler)(&ctx, &json!({})).expect("应成功").content
+    }
+
+    #[test]
+    fn lists_accounts_without_credentials() {
+        let content = call(&registry(Arc::new(MockAccounts::new())));
+        assert_eq!(content["count"], json!(1));
+        assert_eq!(content["accounts"][0]["profile_name"], json!("Steve"));
+        // 只扫账户数据本身：`credential_policy` 那句说明文字里本来就写着 "token"。
+        let fields = content["accounts"].to_string().to_lowercase();
+        for forbidden in ["token", "password", "refresh", "secret"] {
+            assert!(
+                !fields.contains(forbidden),
+                "账户字段含 `{forbidden}`：{fields}"
+            );
+        }
+    }
+
+    #[test]
+    fn empty_list_is_not_an_error() {
+        let content = call(&registry(Arc::new(MockAccounts::empty())));
+        assert_eq!(content["count"], json!(0));
+        assert_eq!(content["accounts"], json!([]));
+    }
+}

crates/agent/src/tools/config.rs

@@ -0,0 +1,345 @@
+//! `get_config` / `set_config`（02 文档 §3.1「有权限修改 ULL 各项配置」）。
+//!
+//! 安全边界都落在这里，但**分级确认的"要不要问"不在这里**：
+//! 工具只负责「白名单过滤 → 生成 diff → 需要确认时只报价不执行」，
+//! 问不问由编排层按 [`crate::confirm::ConfirmPolicy`] 决定（YOLO 也只改那一处）。
+//!
+//! 值校验（类型/范围/schema）归 M12 的配置 schema 所有：agent 不复制一份，
+//! 否则两处规则迟早漂移（02 文档 §3.1「schema 强校验」）。
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::confirm::Sensitivity;
+use crate::port::{SettingKey, SettingPort};
+use crate::registry::schema::{any, non_empty_string, object, string};
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 读配置。
+pub const GET_CONFIG: &str = "get_config";
+/// 写配置。
+pub const SET_CONFIG: &str = "set_config";
+/// 错误提示里最多列多少个可写键（防"把白名单灌给模型"）。
+pub const MAX_LISTED_KEYS: usize = 16;
+/// 摘要里值的最大展示长度。
+const BRIEF_CHARS: usize = 60;
+
+/// 注册两个配置工具。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(
+    registry: &mut ToolRegistry,
+    port: Arc<dyn SettingPort>,
+) -> Result<(), RegistryError> {
+    registry.register(get_config_spec(Arc::clone(&port)))?;
+    registry.register(set_config_spec(port))
+}
+
+fn get_config_spec(port: Arc<dyn SettingPort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let path = args
+            .get("path")
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|p| !p.is_empty());
+        match path {
+            None => {
+                let summary = port.summary();
+                let writable = port.writable_keys();
+                Ok(ToolOutput::ok(
+                    json!({
+                        "scope": "all",
+                        "values": summary,
+                        "writable_keys": writable.iter().map(describe_key).collect::<Vec<_>>(),
+                    }),
+                    format!(
+                        "读取全部配置概要（{} 个键，其中 {} 个 AI 可写）",
+                        summary.as_object().map_or(0, serde_json::Map::len),
+                        writable.len()
+                    ),
+                ))
+            }
+            Some(path) => {
+                // 凭据类键一律不读：值会进 ToolOutput.content → 回灌模型 → 发往远端 LLM，
+                // 违反本 crate 的硬边界（AI 永不接触账户凭据，见 `lib.rs`）。
+                // 这是 agent 侧的第二道防线：第一道是 M12 不把凭据放白名单/概要。
+                if crate::redact::is_sensitive_key(path) {
+                    return Err(ToolError::NotAllowed(format!(
+                        "`{path}` 是凭据类配置，AI 不可读取也不可写入；请让用户自己在设置页查看。"
+                    )));
+                }
+                let value = port.get(path).map_err(ToolError::Port)?;
+                Ok(ToolOutput::ok(
+                    json!({ "scope": "key", "path": path, "value": value }),
+                    format!("读取配置 `{path}` = {}", brief(&value)),
+                ))
+            }
+        }
+    });
+
+    ToolSpec::read_only(
+        GET_CONFIG,
+        "读取启动器配置。不带 path 返回全部配置概要（含 AI 可写键及其敏感等级）；带 path 返回单个键的值。",
+        object(
+            &[(
+                "path",
+                string("配置键点分路径，如 `download.concurrency`；省略则返回全部概要"),
+            )],
+            &[],
+        ),
+        handler,
+    )
+}
+
+fn set_config_spec(port: Arc<dyn SettingPort>) -> ToolSpec {
+    let handler: ToolFn =
+        Arc::new(move |ctx: &ToolCtx, args: &Value| apply_set_config(port.as_ref(), ctx, args));
+
+    ToolSpec::mutating(
+        SET_CONFIG,
+        "修改启动器配置（仅限白名单内的键）。普通键立即生效；敏感键（Java 路径/数据目录/代理/AI 端点）会先返回 needs_confirmation，等用户确认后才会真正写入。值必须符合该键的类型与范围。",
+        object(
+            &[
+                ("path", non_empty_string("配置键点分路径，必须是 get_config 列出的可写键")),
+                ("value", any()),
+            ],
+            &["path", "value"],
+        ),
+        handler,
+    )
+}
+
+/// `set_config` 的实现（独立成函数便于单测直接调用）。
+///
+/// # Errors
+/// 键不在白名单、值缺失、端口写入失败时返回 [`ToolError`]。
+pub fn apply_set_config(
+    port: &dyn SettingPort,
+    ctx: &ToolCtx,
+    args: &Value,
+) -> Result<ToolOutput, ToolError> {
+    let path = args
+        .get("path")
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|p| !p.is_empty())
+        .ok_or_else(|| ToolError::NotAllowed("缺少参数 `path`".to_string()))?
+        .to_string();
+    let value = args
+        .get("value")
+        .cloned()
+        .ok_or_else(|| ToolError::NotAllowed("缺少参数 `value`".to_string()))?;
+
+    let keys = port.writable_keys();
+    let key = keys
+        .iter()
+        .find(|k| k.path == path)
+        .ok_or_else(|| ToolError::NotAllowed(not_writable_message(&keys, &path)))?;
+
+    // 旧值读不到不影响写（首次设置），只是 diff 少一半。
+    let old = port.get(&path).ok();
+
+    if !ctx.confirmed && key.sensitivity == Sensitivity::High {
+        let diff = json!({
+            "path": path,
+            "old": old,
+            "new": value,
+            "sensitivity": key.sensitivity,
+            "description": key.description,
+        });
+        return Ok(ToolOutput::needs_confirmation(
+            format!(
+                "AI 请求把 `{path}` 从 {} 改为 {}（{}）",
+                brief_opt(&old),
+                brief(&value),
+                sensitivity_label(key.sensitivity)
+            ),
+            diff,
+            key.sensitivity,
+        ));
+    }
+
+    let change = port.set(&path, &value).map_err(ToolError::Port)?;
+    Ok(ToolOutput::ok(
+        json!({
+            "status": "written",
+            "path": change.path,
+            "old": change.old,
+            "new": change.new,
+            "sensitivity": key.sensitivity,
+        }),
+        format!(
+            "已把 `{}` 从 {} 改为 {}",
+            change.path,
+            brief_opt(&change.old),
+            brief(&change.new)
+        ),
+    ))
+}
+
+/// 白名单拒绝的文案：说清"不能写"并给出可写键（模型会据此改用正确路径）。
+fn not_writable_message(keys: &[SettingKey], path: &str) -> String {
+    let listed: Vec<&str> = keys
+        .iter()
+        .take(MAX_LISTED_KEYS)
+        .map(|k| k.path.as_str())
+        .collect();
+    let rest = keys.len().saturating_sub(listed.len());
+    let tail = if rest > 0 {
+        format!("，另有 {rest} 个键见 get_config 概要")
+    } else {
+        String::new()
+    };
+    format!(
+        "配置键 `{path}` 不在 AI 可写白名单内。可写键（{} 个）：{}{tail}",
+        keys.len(),
+        listed.join("、")
+    )
+}
+
+fn describe_key(key: &SettingKey) -> Value {
+    json!({
+        "path": key.path,
+        "sensitivity": key.sensitivity,
+        "value_type": key.value_type,
+        "description": key.description,
+    })
+}
+
+fn sensitivity_label(sensitivity: Sensitivity) -> &'static str {
+    match sensitivity {
+        Sensitivity::Low => "普通",
+        Sensitivity::Medium => "中等（静默但审计）",
+        Sensitivity::High => "敏感，需确认",
+    }
+}
+
+fn brief(value: &Value) -> String {
+    let rendered = match value {
+        Value::String(s) => s.clone(),
+        other => other.to_string(),
+    };
+    truncate(&rendered)
+}
+
+fn brief_opt(value: &Option<Value>) -> String {
+    value
+        .as_ref()
+        .map_or_else(|| "（未设置）".to_string(), brief)
+}
+
+fn truncate(text: &str) -> String {
+    if text.chars().count() <= BRIEF_CHARS {
+        return text.to_string();
+    }
+    let head: String = text.chars().take(BRIEF_CHARS).collect();
+    format!("{head}…")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockSettings;
+
+    fn ctx(confirmed: bool) -> ToolCtx {
+        ToolCtx {
+            agent_session_id: "s1".to_string(),
+            confirmed,
+        }
+    }
+
+    #[test]
+    fn rejects_keys_outside_whitelist() {
+        let port = MockSettings::new();
+        let err = apply_set_config(
+            &port,
+            &ctx(true),
+            &json!({ "path": "java.random.thing", "value": 1 }),
+        )
+        .unwrap_err();
+        assert!(matches!(err, ToolError::NotAllowed(_)));
+        assert!(err.message().contains("不在 AI 可写白名单内"));
+        assert!(err.message().contains("download.concurrency"));
+        assert_eq!(port.set_calls(), 0);
+    }
+
+    #[test]
+    fn normal_key_writes_without_confirmation() {
+        let port = MockSettings::new();
+        let out = apply_set_config(
+            &port,
+            &ctx(false),
+            &json!({ "path": "download.concurrency", "value": 16 }),
+        )
+        .unwrap();
+        assert!(out.confirmation.is_none());
+        assert_eq!(out.content["status"], json!("written"));
+        assert_eq!(port.value_of("download.concurrency"), Some(json!(16)));
+    }
+
+    #[test]
+    fn medium_key_writes_silently_too() {
+        // M12：Medium = 静默生效但审计标记，不弹窗
+        let port = MockSettings::new();
+        let out = apply_set_config(
+            &port,
+            &ctx(false),
+            &json!({ "path": "download.region", "value": "cn" }),
+        )
+        .unwrap();
+        assert!(out.confirmation.is_none());
+        assert_eq!(port.set_calls(), 1);
+    }
+
+    #[test]
+    fn high_key_quotes_first_then_writes_after_confirm() {
+        let port = MockSettings::new();
+        let args = json!({ "path": "java.selected_path", "value": "D:/jdk17/bin/java.exe" });
+
+        let quoted = apply_set_config(&port, &ctx(false), &args).unwrap();
+        let confirmation = quoted.confirmation.expect("High 键应要求确认");
+        assert_eq!(confirmation.sensitivity, Sensitivity::High);
+        assert_eq!(confirmation.details["new"], json!("D:/jdk17/bin/java.exe"));
+        assert_eq!(port.set_calls(), 0, "未确认前不得写入");
+
+        let written = apply_set_config(&port, &ctx(true), &args).unwrap();
+        assert!(written.confirmation.is_none());
+        assert_eq!(port.set_calls(), 1);
+        assert_eq!(
+            port.value_of("java.selected_path"),
+            Some(json!("D:/jdk17/bin/java.exe"))
+        );
+    }
+
+    #[test]
+    fn locked_credential_key_is_not_writable() {
+        // M12：ai.api_key 是 writable=false，不在白名单里 → 任何情况下都拒绝
+        let port = MockSettings::new();
+        let err = apply_set_config(
+            &port,
+            &ctx(true),
+            &json!({ "path": "ai.api_key", "value": "sk-x" }),
+        )
+        .unwrap_err();
+        assert!(matches!(err, ToolError::NotAllowed(_)));
+        assert_eq!(port.set_calls(), 0);
+    }
+
+    #[test]
+    fn port_error_is_passed_through() {
+        let port = MockSettings::new();
+        port.fail_set_with("磁盘只读");
+        let err = apply_set_config(
+            &port,
+            &ctx(true),
+            &json!({ "path": "appearance.theme_mode", "value": "metro_light" }),
+        )
+        .unwrap_err();
+        assert_eq!(err.code(), "port_error");
+        assert!(err.message().contains("磁盘只读"));
+    }
+}

crates/agent/src/tools/diagnose.rs

@@ -0,0 +1,335 @@
+//! `diagnose_crash`（02 文档 §3.2 第三条）。
+//!
+//! 流水线是「**规则在前、模型补位**」（analyse/02 §8.3）：本工具只跑 M15 的规则引擎，
+//! 把**结构化结论 + 关键片段**交给模型，绝不让模型读裸日志。规则未命中
+//! （`candidates` 空 / `needs_more_info`）时，模型再去用 `read_game_log` 自己找证据。
+//!
+//! P0 与 M15 的桥：M15 的修复动作指向 `java.set` / `memory.set` 这些 **P1 才有的**语义工具 id。
+//! P0 只有 `set_config`，所以这里按 [`FixActionKind`] 生成 `p0_next_steps`
+//! （`adjust_memory` → `set_config {"path":"java.default_memory_mb"}`，`change_java` →
+//! `set_config {"path":"java.selected_path"}`，见 [`MEMORY_KEY`] / [`JAVA_KEY`]），
+//! 剩下的动作明确标成「P0 无工具，解释给用户」。
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::port::{CrashDiagnosis, DiagnosePort, DiagnosisCandidate, FixAction, FixActionKind};
+use crate::redact::redact_text;
+use crate::registry::schema::{integer, non_empty_string, object};
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 诊断工具名。
+pub const DIAGNOSE_CRASH: &str = "diagnose_crash";
+/// 单次返回的证据行上限（防 token 爆炸）。
+pub const MAX_EVIDENCE_LINES: usize = 40;
+/// 证据行默认条数。
+pub const DEFAULT_EVIDENCE_LINES: usize = 20;
+/// 单条证据最大字符数。
+pub const MAX_EVIDENCE_CHARS: usize = 400;
+/// 内存建议的配置键（M12 白名单里的键名，见 `setting-接口约定.md` §8）。
+pub const MEMORY_KEY: &str = "java.default_memory_mb";
+/// Java 路径的配置键。
+pub const JAVA_KEY: &str = "java.selected_path";
+
+/// 注册诊断工具。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(
+    registry: &mut ToolRegistry,
+    port: Arc<dyn DiagnosePort>,
+) -> Result<(), RegistryError> {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let session_id = args
+            .get("session_id")
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .ok_or_else(|| ToolError::NotAllowed("缺少参数 `session_id`".to_string()))?;
+        let max_lines = args
+            .get("max_evidence_lines")
+            .and_then(Value::as_u64)
+            .map_or(DEFAULT_EVIDENCE_LINES, |n| n as usize)
+            .clamp(1, MAX_EVIDENCE_LINES);
+        let report = port.diagnose(session_id).map_err(ToolError::Port)?;
+        Ok(render(&report, max_lines))
+    });
+
+    registry.register(ToolSpec::read_only(
+        DIAGNOSE_CRASH,
+        "对某次游戏会话跑规则引擎（59 条崩溃规则）并返回结构化结论：主因、置信度、证据行、修复动作。规则未命中时会提示需要更多信息——此时再用 read_game_log 取 stderr/exit 片段。",
+        object(
+            &[
+                ("session_id", non_empty_string("会话 id，来自 list_game_sessions")),
+                (
+                    "max_evidence_lines",
+                    integer("返回多少条证据行", 1, MAX_EVIDENCE_LINES as i64),
+                ),
+            ],
+            &["session_id"],
+        ),
+        handler,
+    ))
+}
+
+/// 把规则引擎结论压成工具结果。
+fn render(report: &CrashDiagnosis, max_evidence_lines: usize) -> ToolOutput {
+    let candidates: Vec<Value> = report
+        .candidates
+        .iter()
+        .map(|c| render_candidate(c, max_evidence_lines))
+        .collect();
+    let secondary: Vec<Value> = report
+        .secondary
+        .iter()
+        .take(5)
+        .map(|c| {
+            json!({
+                "id": c.id,
+                "severity": c.severity,
+                "category": c.category,
+                "confidence": c.confidence,
+                "message": message_of(c),
+            })
+        })
+        .collect();
+    let next_steps: Vec<Value> = report
+        .candidates
+        .iter()
+        .flat_map(|c| c.fix_actions.iter())
+        .map(bridge_to_p0)
+        .collect();
+
+    let content = json!({
+        "session_id": report.session_id,
+        "source": report.source,
+        "needs_more_info": report.needs_more_info,
+        "exit": report.exit,
+        "top_confidence": report.top_confidence(),
+        "candidates": candidates,
+        "secondary": secondary,
+        "evidence": cap_lines(&report.evidence, max_evidence_lines),
+        "p0_next_steps": next_steps,
+    });
+
+    ToolOutput::ok(content, summarize(report))
+}
+
+fn render_candidate(candidate: &DiagnosisCandidate, max_evidence_lines: usize) -> Value {
+    json!({
+        "id": candidate.id,
+        "severity": candidate.severity,
+        "category": candidate.category,
+        "confidence": candidate.confidence,
+        "message": message_of(candidate),
+        "detail": candidate.detail,
+        "evidence": cap_lines(&candidate.evidence, max_evidence_lines),
+        "fix_actions": candidate.fix_actions,
+    })
+}
+
+/// `message` 为空时回落显示 i18n key（装配层没渲染时至少不丢信息）。
+fn message_of(candidate: &DiagnosisCandidate) -> String {
+    let text = candidate.message.trim();
+    if text.is_empty() {
+        candidate.message_key.clone()
+    } else {
+        text.to_string()
+    }
+}
+
+fn summarize(report: &CrashDiagnosis) -> String {
+    match report.top() {
+        Some(top) => {
+            let label = top
+                .fix_actions
+                .first()
+                .map(action_label)
+                .unwrap_or_else(|| "没有可执行的修复动作".to_string());
+            format!(
+                "规则引擎命中 {} 条候选，主因 `{}`（置信度 {:.2}）；建议：{label}",
+                report.candidates.len(),
+                top.id,
+                top.confidence
+            )
+        }
+        None if report.needs_more_info => {
+            "规则引擎未命中，且需要更多信息（用 read_game_log 取 stderr/exit 片段后再判断）"
+                .to_string()
+        }
+        None => "规则引擎未命中（59 条规则都不匹配），需要结合日志片段人工/AI 判断".to_string(),
+    }
+}
+
+/// M15 的语义动作 → P0 现有工具。返回给模型看的"下一步"。
+fn bridge_to_p0(action: &FixAction) -> Value {
+    let label = action_label(action);
+    match action.kind {
+        FixActionKind::AdjustMemory => {
+            let value = pick_memory_mb(action).map_or(Value::Null, |mb| json!(mb));
+            json!({
+                "action": action.tool,
+                "kind": action.kind,
+                "label": label,
+                "suggested_tool": "set_config",
+                "suggested_args": { "path": MEMORY_KEY, "value": value },
+            })
+        }
+        FixActionKind::ChangeJava => {
+            let value = pick_arg(action, &["path", "java_path", "binary", "value"])
+                .map_or(Value::Null, |p| json!(p));
+            json!({
+                "action": action.tool,
+                "kind": action.kind,
+                "label": label,
+                "suggested_tool": "set_config",
+                "suggested_args": { "path": JAVA_KEY, "value": value },
+            })
+        }
+        other => json!({
+            "action": action.tool,
+            "kind": other,
+            "label": label,
+            "suggested_tool": Value::Null,
+            "unavailable_reason": "P0 没有对应工具（P1 落地），请把这个建议解释给用户",
+        }),
+    }
+}
+
+/// 动作的人话：优先 M15 给的 `label`，否则按 kind 兜底。
+fn action_label(action: &FixAction) -> String {
+    let label = action.label.trim();
+    if !label.is_empty() {
+        return label.to_string();
+    }
+    match action.kind {
+        FixActionKind::ChangeJava => "换一个匹配的 Java 版本".to_string(),
+        FixActionKind::AdjustMemory => "调整最大内存".to_string(),
+        FixActionKind::ChangeGraphics => "调整图形设置/驱动".to_string(),
+        FixActionKind::RemoveMod => "移除或替换冲突的 Mod".to_string(),
+        FixActionKind::Reinstall => "重装/修复对应组件".to_string(),
+        FixActionKind::SeekHelp => "导出诊断包并反馈".to_string(),
+    }
+}
+
+/// 从动作参数里挑内存上限：先看常见键，再退化成"第一个带数字的值"。
+fn pick_memory_mb(action: &FixAction) -> Option<i64> {
+    if let Some(value) = pick_arg(
+        action,
+        &["value", "suggest", "mb", "max_mb", "xmx", "xmx_mb"],
+    ) {
+        if let Some(mb) = parse_mb(&value) {
+            return Some(mb);
+        }
+    }
+    action.args.values().find_map(|v| parse_mb(v))
+}
+
+fn pick_arg(action: &FixAction, keys: &[&str]) -> Option<String> {
+    keys.iter()
+        .find_map(|key| action.args.get(*key).cloned())
+        .filter(|v| !v.trim().is_empty())
+}
+
+/// `"4096"` / `"4G"` / `"6144M"` → MB。
+fn parse_mb(raw: &str) -> Option<i64> {
+    let text = raw.trim().to_ascii_lowercase();
+    let (number, scale) = if let Some(rest) = text.strip_suffix('g') {
+        (rest, 1024)
+    } else if let Some(rest) = text.strip_suffix("gb") {
+        (rest, 1024)
+    } else if let Some(rest) = text.strip_suffix('m') {
+        (rest, 1)
+    } else if let Some(rest) = text.strip_suffix("mb") {
+        (rest, 1)
+    } else {
+        (text.as_str(), 1)
+    };
+    number.trim().parse::<i64>().ok().map(|n| n * scale)
+}
+
+fn cap_lines(lines: &[String], max_lines: usize) -> Vec<String> {
+    lines
+        .iter()
+        .take(max_lines)
+        .map(|line| {
+            let masked = redact_text(line);
+            if masked.chars().count() <= MAX_EVIDENCE_CHARS {
+                masked
+            } else {
+                let head: String = masked.chars().take(MAX_EVIDENCE_CHARS).collect();
+                format!("{head}…")
+            }
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockDiagnose;
+
+    fn call(port: &MockDiagnose, session_id: &str) -> ToolOutput {
+        let report = port.diagnose(session_id).expect("mock 应返回结论");
+        render(&report, DEFAULT_EVIDENCE_LINES)
+    }
+
+    #[test]
+    fn renders_candidates_with_p0_bridge_for_reinstall() {
+        let out = call(&MockDiagnose::new(), "s-1");
+        assert_eq!(out.content["candidates"].as_array().unwrap().len(), 1);
+        let confidence = out.content["top_confidence"].as_f64().unwrap();
+        assert!((confidence - 0.86).abs() < 1e-6, "{confidence}");
+        let steps = out.content["p0_next_steps"].as_array().unwrap();
+        assert_eq!(steps[0]["kind"], json!("reinstall"));
+        assert_eq!(steps[0]["suggested_tool"], Value::Null);
+        assert!(out.summary.contains("建议：重装该版本的 Forge 组件"));
+    }
+
+    #[test]
+    fn bridges_memory_action_to_set_config() {
+        let mut report = MockDiagnose::forge_missing_library();
+        if let Some(candidate) = report.candidates.first_mut() {
+            candidate.fix_actions = vec![FixAction {
+                kind: FixActionKind::AdjustMemory,
+                tool: "memory.set".to_string(),
+                label: String::new(),
+                args: [("suggest".to_string(), "4G".to_string())]
+                    .into_iter()
+                    .collect(),
+            }];
+        }
+        let out = render(&report, 5);
+        let steps = out.content["p0_next_steps"].as_array().unwrap();
+        assert_eq!(steps[0]["suggested_tool"], json!("set_config"));
+        assert_eq!(steps[0]["suggested_args"]["path"], json!(MEMORY_KEY));
+        assert_eq!(steps[0]["suggested_args"]["value"], json!(4096));
+        assert_eq!(steps[0]["label"], json!("调整最大内存"));
+    }
+
+    #[test]
+    fn parses_memory_units() {
+        assert_eq!(parse_mb("4096"), Some(4096));
+        assert_eq!(parse_mb("4G"), Some(4096));
+        assert_eq!(parse_mb("6144mb"), Some(6144));
+        assert_eq!(parse_mb("abc"), None);
+    }
+
+    #[test]
+    fn empty_candidates_says_need_more_info() {
+        let report = CrashDiagnosis {
+            session_id: "s-2".into(),
+            source: "rules".into(),
+            needs_more_info: true,
+            candidates: vec![],
+            secondary: vec![],
+            evidence: vec![],
+            exit: crate::port::ExitSummary::default(),
+        };
+        let out = render(&report, 5);
+        assert!(out.summary.contains("需要更多信息"));
+    }
+}

crates/agent/src/tools/game.rs

@@ -0,0 +1,199 @@
+//! 实例 / 版本 / Java 三个只读工具（M39 任务 3 的读侧）。
+//!
+//! 全部只读、全部走 [`crate::port::GamePort`]：agent 不自己去翻 `versions/` 目录，
+//! 也不自己扫 JDK——那两件事的真相源在 M14（game）与 M33（java），重复一份必然漂。
+//!
+//! 输出形状刻意做成「摘要 + 上限」：实例可能几十个、Java 候选可能十几个，
+//! 一次全塞给模型等于烧 token（02 §3.2 的「单次返回上限防 token 爆炸」同理）。
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::port::GamePort;
+use crate::registry::schema::{integer, object};
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 实例列表工具名。
+pub const LIST_INSTANCES: &str = "list_instances";
+/// 版本列表工具名。
+pub const LIST_VERSIONS: &str = "list_versions";
+/// Java 现状工具名。
+pub const GET_JAVA_STATUS: &str = "get_java_status";
+/// 单次最多返回多少个实例/版本。
+pub const MAX_ROWS: usize = 50;
+
+/// 注册三个只读工具。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(registry: &mut ToolRegistry, port: Arc<dyn GamePort>) -> Result<(), RegistryError> {
+    registry.register(list_instances_spec(Arc::clone(&port)))?;
+    registry.register(list_versions_spec(Arc::clone(&port)))?;
+    registry.register(java_status_spec(port))
+}
+
+fn limit_arg(args: &Value) -> usize {
+    args.get("limit")
+        .and_then(Value::as_u64)
+        .map_or(MAX_ROWS, |n| usize::try_from(n).unwrap_or(MAX_ROWS))
+        .clamp(1, MAX_ROWS)
+}
+
+fn limit_schema() -> Value {
+    integer(
+        &format!("最多返回多少条（1~{MAX_ROWS}，默认 {MAX_ROWS}）"),
+        1,
+        MAX_ROWS as i64,
+    )
+}
+
+fn list_instances_spec(port: Arc<dyn GamePort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let limit = limit_arg(args);
+        let mut instances = port.list_instances().map_err(ToolError::Port)?;
+        let total = instances.len();
+        instances.truncate(limit);
+        Ok(ToolOutput::ok(
+            json!({
+                "total": total,
+                "shown": instances.len(),
+                "truncated": total > instances.len(),
+                "instances": instances,
+            }),
+            format!("列出 {}/{} 个实例", instances.len(), total),
+        ))
+    });
+
+    ToolSpec::read_only(
+        LIST_INSTANCES,
+        "列出启动器里的游戏实例（id / 名称 / 版本 id / 载荷是否已安装 / 独立游戏目录 / 实例级 Java）。要看某个实例的日志先用 list_game_sessions。",
+        object(&[("limit", limit_schema())], &[]),
+        handler,
+    )
+}
+
+fn list_versions_spec(port: Arc<dyn GamePort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let limit = limit_arg(args);
+        let mut versions = port.list_versions().map_err(ToolError::Port)?;
+        let total = versions.len();
+        versions.truncate(limit);
+        Ok(ToolOutput::ok(
+            json!({
+                "total": total,
+                "shown": versions.len(),
+                "truncated": total > versions.len(),
+                "versions": versions,
+            }),
+            format!("列出 {}/{} 个已安装版本", versions.len(), total),
+        ))
+    });
+
+    ToolSpec::read_only(
+        LIST_VERSIONS,
+        "列出已安装的游戏版本（`versions/<id>/` 下真实存在的载荷），带类型与被几个实例引用。判断「实例的载荷缺没缺」时配合 list_instances 的 version_present 一起看。",
+        object(&[("limit", limit_schema())], &[]),
+        handler,
+    )
+}
+
+fn java_status_spec(port: Arc<dyn GamePort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, _args: &Value| {
+        let status = port.java_status().map_err(ToolError::Port)?;
+        let majors: Vec<String> = status
+            .candidates
+            .iter()
+            .filter_map(|c| c.major.map(|m| m.to_string()))
+            .collect();
+        Ok(ToolOutput::ok(
+            json!({
+                "default_memory_mb": status.default_memory_mb,
+                "managed_roots": status.managed_roots,
+                "candidate_count": status.candidates.len(),
+                "majors": majors,
+                "candidates": status.candidates,
+            }),
+            format!(
+                "Java 候选 {} 个（主版本 {}）",
+                status.candidates.len(),
+                if majors.is_empty() {
+                    "无".to_string()
+                } else {
+                    majors.join("/")
+                }
+            ),
+        ))
+    });
+
+    ToolSpec::read_only(
+        GET_JAVA_STATUS,
+        "读取 Java 现状：托管扫描根、默认堆内存、探测到的全部运行时（路径 / 版本 / 主版本 / 发行方 / 来源）。启动报「不支持的 class 版本」「找不到 Java」时先看这里。",
+        object(&[], &[]),
+        handler,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockGame;
+
+    fn registry() -> ToolRegistry {
+        let mut registry = ToolRegistry::new();
+        register(&mut registry, Arc::new(MockGame::new())).expect("注册应成功");
+        registry
+    }
+
+    fn call(registry: &ToolRegistry, name: &str, args: Value) -> Value {
+        let spec = registry.get(name).expect("工具存在").clone();
+        let ctx = ToolCtx {
+            agent_session_id: "s1".to_string(),
+            confirmed: false,
+        };
+        (spec.handler)(&ctx, &args).expect("应成功").content
+    }
+
+    #[test]
+    fn lists_instances_with_limit() {
+        let content = call(&registry(), LIST_INSTANCES, json!({ "limit": 1 }));
+        assert_eq!(content["total"], json!(1));
+        assert_eq!(content["instances"][0]["id"], json!("inst-1"));
+        assert_eq!(content["truncated"], json!(false));
+    }
+
+    #[test]
+    fn lists_versions() {
+        let content = call(&registry(), LIST_VERSIONS, json!({}));
+        assert_eq!(content["total"], json!(2));
+        assert_eq!(content["versions"][0]["id"], json!("1.20.1-forge-47.2.20"));
+    }
+
+    #[test]
+    fn java_status_summarises_majors() {
+        let content = call(&registry(), GET_JAVA_STATUS, json!({}));
+        assert_eq!(content["candidate_count"], json!(2));
+        assert_eq!(content["majors"], json!(["17", "21"]));
+        assert_eq!(content["default_memory_mb"], json!(2048));
+    }
+
+    #[test]
+    fn port_errors_are_passed_through() {
+        let mut registry = ToolRegistry::new();
+        register(
+            &mut registry,
+            Arc::new(MockGame::failing("versions 目录不可读")),
+        )
+        .expect("注册应成功");
+        let spec = registry.get(LIST_VERSIONS).expect("工具存在").clone();
+        let ctx = ToolCtx {
+            agent_session_id: "s1".to_string(),
+            confirmed: false,
+        };
+        let err = (spec.handler)(&ctx, &json!({})).unwrap_err();
+        assert_eq!(err.code(), "port_error");
+        assert!(err.message().contains("versions 目录不可读"));
+    }
+}

crates/agent/src/tools/mod.rs

@@ -0,0 +1,39 @@
+//! 工具集 v1（02 文档 §3）：配置读写 / 会话与日志 / 崩溃诊断 / 实例与 Java / 账户。
+//!
+//! 分工边界（重要，评审时按这条看）：
+//! - **工具**：参数语义 → 端口调用 → 结构化结果；需要确认时**只报价不执行**。
+//! - **编排层**（[`crate::brain::exec`]）：schema 校验、确认闸门、YOLO 判定、审计、事件。
+//! - **端口**（[`crate::port`]）：真正的 IO 与领域校验（M12/M14/M15/M18/M31/M33 拥有）。
+//!
+//! 这样「YOLO」只在一个地方（编排层），工具的测试不需要关心 policy。
+//!
+//! 双投影：这里的注册表是**唯一真相源**，内置客户端投成 rig `DynamicTool`，
+//! 对外 MCP server 投成 rmcp `ToolRoute`（[`crate::mcp`]）。工具数量与顺序对外一致。
+
+pub mod accounts;
+pub mod config;
+pub mod diagnose;
+pub mod game;
+pub mod schema_tool;
+pub mod session;
+
+use crate::port::Ports;
+use crate::registry::{RegistryError, ToolRegistry};
+
+/// 组装 v1 的全部工具。注册顺序 = 模型看到的顺序（只读在前，写在后）。
+///
+/// 顺序不是随便排的：模型在长工具表里更容易选中靠前的项，所以「先看再改」
+/// （`get_config*` 在 `set_config` 之前）是刻意的提示。
+///
+/// # Errors
+/// 工具名重复 / schema 非法时返回 [`RegistryError`]（属于编码错误，装配期就该炸）。
+pub fn build_v1_registry(ports: &Ports) -> Result<ToolRegistry, RegistryError> {
+    let mut registry = ToolRegistry::new();
+    config::register(&mut registry, ports.setting.clone())?;
+    schema_tool::register(&mut registry, ports.setting.clone())?;
+    game::register(&mut registry, ports.game.clone())?;
+    accounts::register(&mut registry, ports.accounts.clone())?;
+    session::register(&mut registry, ports.sessions.clone())?;
+    diagnose::register(&mut registry, ports.diagnose.clone())?;
+    Ok(registry)
+}

crates/agent/src/tools/schema_tool.rs

@@ -0,0 +1,84 @@
+//! `get_config_schema`：把 M12 的配置 schema（**只含 AI 可写键**）投给模型。
+//!
+//! 为什么单独一个工具而不是塞进 `get_config`：模型要能「先看有哪些键、类型是什么、
+//! 哪些是敏感键」，再决定要不要写——这是一次性的静态信息，和读当前值不是同一件事。
+//! 拆开还能让 token 预算更可控（schema 比概要大一个量级）。
+//!
+//! 凭据边界：schema 由 M12 的 `SettingSchema::to_json_schema()` 生成，只遍历
+//! `ai.writable && !deprecated` 的键，`ai.api_key`（`locked`）天然不在其中。
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::port::SettingPort;
+use crate::registry::schema::object;
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 工具名。
+pub const GET_CONFIG_SCHEMA: &str = "get_config_schema";
+
+/// 注册 `get_config_schema`。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(
+    registry: &mut ToolRegistry,
+    port: Arc<dyn SettingPort>,
+) -> Result<(), RegistryError> {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, _args: &Value| {
+        let schema = port.schema();
+        if schema.get("properties").is_none() {
+            return Err(ToolError::Port(
+                "配置 schema 不可用：装配层没有提供 SettingPort::schema()".to_string(),
+            ));
+        }
+        let writable = schema
+            .get("properties")
+            .and_then(Value::as_object)
+            .map_or(0, serde_json::Map::len);
+        Ok(ToolOutput::ok(
+            json!({
+                "scope": "ai_writable_schema",
+                "writable_key_count": writable,
+                "schema": schema,
+            }),
+            format!("读取配置 schema（{writable} 个 AI 可写键）"),
+        ))
+    });
+
+    registry.register(ToolSpec::read_only(
+        GET_CONFIG_SCHEMA,
+        "读取启动器配置的 JSON Schema（只含 AI 可写键）。每个键带类型、取值范围、说明与 `x-ai-sensitivity` 敏感等级；凭据类键不会出现。写配置前先看它。",
+        object(&[], &[]),
+        handler,
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockSettings;
+
+    fn ctx() -> ToolCtx {
+        ToolCtx {
+            agent_session_id: "s1".to_string(),
+            confirmed: false,
+        }
+    }
+
+    #[test]
+    fn returns_schema_without_credentials() {
+        let port: Arc<dyn SettingPort> = Arc::new(MockSettings::new());
+        let mut registry = ToolRegistry::new();
+        register(&mut registry, port).expect("注册应成功");
+        let spec = registry.get(GET_CONFIG_SCHEMA).expect("工具存在").clone();
+        let out = (spec.handler)(&ctx(), &json!({})).expect("应返回 schema");
+        let text = out.content.to_string();
+        assert!(out.content["writable_key_count"].as_u64().unwrap_or(0) > 0);
+        assert!(text.contains("x-ai-sensitivity"));
+        assert!(!text.contains("ai.api_key"), "凭据键不得进 schema：{text}");
+    }
+}

crates/agent/src/tools/session.rs

@@ -0,0 +1,388 @@
+//! `list_game_sessions` / `read_game_log`（02 文档 §3.2「能读取某次游戏崩溃日志」）。
+//!
+//! 数据源是 M18 的会话事件流（`DevDocs/SubAgentsTalk/launch-接口约定.md`）：
+//! - 列表读 `index.jsonl`（每会话一行摘要，同 id 取最后一行）；
+//! - 日志读 `<session-id>.jsonl`，**按 `seq` 切片 + 按 `kind` 过滤**，不是按行号。
+//!
+//! 两条防 token 爆炸的硬约束：
+//! 1. 单次最多 [`MAX_LOG_EVENTS`] 条事件（默认 [`DEFAULT_LOG_EVENTS`]）；
+//! 2. 单条 payload 里的字符串超过 [`MAX_PAYLOAD_CHARS`] 截断。
+//!
+//! 脱敏：launch 落盘前已经做过一遍（`<home>` / `<redacted:token>`），本工具再跑一遍
+//! [`crate::redact::redact_text`] 作为第二道防线（幂等，旧会话/第三方 mod 输出可能漏网）。
+
+use std::sync::Arc;
+
+use serde_json::{json, Map, Value};
+
+use crate::port::{GameSessionPort, LogEvent, LogPage, LogQuery};
+use crate::redact::redact_text;
+use crate::registry::schema::{enum_string_array, integer, non_empty_string, object, string};
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 列出游戏会话。
+pub const LIST_GAME_SESSIONS: &str = "list_game_sessions";
+/// 读一个会话的日志。
+pub const READ_GAME_LOG: &str = "read_game_log";
+
+/// 单次返回的事件上限（防 token 爆炸的硬闸）。
+pub const MAX_LOG_EVENTS: usize = 500;
+/// 默认返回条数。
+pub const DEFAULT_LOG_EVENTS: usize = 100;
+/// 单条 payload 字符串的展示上限（字符）。
+pub const MAX_PAYLOAD_CHARS: usize = 800;
+/// 列表默认/最大条数。
+pub const DEFAULT_SESSION_LIMIT: usize = 10;
+/// 列表最大条数。
+pub const MAX_SESSION_LIMIT: usize = 50;
+
+/// `launch-接口约定.md` §3 的事件类型（schema 里给模型做枚举；未知 kind 仍可透传）。
+pub const KNOWN_KINDS: [&str; 13] = [
+    "session_start",
+    "java_selected",
+    "cmd_built",
+    "natives_extracted",
+    "proc_start",
+    "stdout",
+    "stderr",
+    "window_detected",
+    "exit",
+    "crash_found",
+    "diagnosis",
+    "killed",
+    "session_end",
+];
+
+/// 注册两个日志工具。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(
+    registry: &mut ToolRegistry,
+    port: Arc<dyn GameSessionPort>,
+) -> Result<(), RegistryError> {
+    registry.register(list_sessions_spec(Arc::clone(&port)))?;
+    registry.register(read_log_spec(port))
+}
+
+fn list_sessions_spec(port: Arc<dyn GameSessionPort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let limit = args
+            .get("limit")
+            .and_then(Value::as_u64)
+            .map_or(DEFAULT_SESSION_LIMIT, |n| n as usize)
+            .clamp(1, MAX_SESSION_LIMIT);
+        let instance_id = args.get("instance_id").and_then(Value::as_str);
+        let sessions = port
+            .list_sessions(limit, instance_id)
+            .map_err(ToolError::Port)?;
+
+        if sessions.is_empty() {
+            return Ok(ToolOutput::ok(
+                json!({ "sessions": [], "count": 0 }),
+                "没有游戏会话记录（还没启动过游戏，或数据目录不对）".to_string(),
+            ));
+        }
+
+        let crashed = sessions
+            .iter()
+            .filter(|s| s.crash_found || s.silent_failure || s.exit_code.is_some_and(|c| c != 0))
+            .count();
+        let summary = format!(
+            "最近 {} 个游戏会话，其中 {crashed} 个崩溃/异常退出；最近一次 {}（{}）",
+            sessions.len(),
+            sessions[0].session_id,
+            sessions[0].started_at.as_deref().unwrap_or("启动时间未知")
+        );
+        Ok(ToolOutput::ok(
+            json!({ "sessions": sessions, "count": sessions.len(), "problem_count": crashed }),
+            summary,
+        ))
+    });
+
+    ToolSpec::read_only(
+        LIST_GAME_SESSIONS,
+        "列出最近的游戏会话（启动时间、退出码、是否崩溃、规则引擎首选结论）。用于定位要读哪一次会话的日志。",
+        object(
+            &[
+                ("limit", integer("返回条数", 1, MAX_SESSION_LIMIT as i64)),
+                ("instance_id", string("只看某个实例的会话；省略则全部实例")),
+            ],
+            &[],
+        ),
+        handler,
+    )
+}
+
+fn read_log_spec(port: Arc<dyn GameSessionPort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let session_id = args
+            .get("session_id")
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .ok_or_else(|| ToolError::NotAllowed("缺少参数 `session_id`".to_string()))?
+            .to_string();
+
+        let kinds: Vec<String> = args
+            .get("kinds")
+            .and_then(Value::as_array)
+            .map(|items| {
+                items
+                    .iter()
+                    .filter_map(Value::as_str)
+                    .map(str::to_string)
+                    .collect()
+            })
+            .unwrap_or_default();
+
+        let max_events = args
+            .get("max_events")
+            .and_then(Value::as_u64)
+            .map_or(DEFAULT_LOG_EVENTS, |n| n as usize)
+            .clamp(1, MAX_LOG_EVENTS);
+
+        let query = LogQuery {
+            from_seq: args.get("from_seq").and_then(Value::as_u64),
+            to_seq: args.get("to_seq").and_then(Value::as_u64),
+            kinds,
+            max_events,
+        };
+        let page = port
+            .read_log(&session_id, &query)
+            .map_err(ToolError::Port)?;
+        Ok(render_page(&page))
+    });
+
+    ToolSpec::read_only(
+        READ_GAME_LOG,
+        "读取某次游戏会话的事件流（stdout/stderr 按行、退出事件、crash-report 摘录）。可按 seq 区间和事件类型过滤；单次最多 500 条、单条最长 800 字符，优先用 kinds 过滤 stderr/exit/crash_found 而不是拉全量。",
+        object(
+            &[
+                ("session_id", non_empty_string("会话 id，来自 list_game_sessions")),
+                ("from_seq", integer("起始 seq（含）", 0, 9_007_199_254_740_991)),
+                ("to_seq", integer("结束 seq（含）", 0, 9_007_199_254_740_991)),
+                (
+                    "kinds",
+                    enum_string_array(&KNOWN_KINDS, "只要这些事件类型；省略则全部", 13),
+                ),
+                ("max_events", integer("最多返回多少条", 1, MAX_LOG_EVENTS as i64)),
+            ],
+            &["session_id"],
+        ),
+        handler,
+    )
+}
+
+/// 把端口返回的一页日志压成工具结果（含摘要，模型据此决定要不要继续翻页）。
+fn render_page(page: &LogPage) -> ToolOutput {
+    let events: Vec<Value> = page.events.iter().map(render_event).collect();
+    let kind_summary = page
+        .kind_counts
+        .iter()
+        .map(|(kind, count)| format!("{kind}×{count}"))
+        .collect::<Vec<_>>()
+        .join(", ");
+
+    let (content, summary) = if events.is_empty() {
+        (
+            json!({
+                "session_id": page.session_id,
+                "total_events": page.total_events,
+                "matched_events": 0,
+                "truncated": false,
+                "kind_counts": page.kind_counts,
+                "first_ts": page.first_ts,
+                "last_ts": page.last_ts,
+                "events": [],
+                "hint": "没有符合过滤条件的事件；把 kinds/from_seq/to_seq 放宽再试",
+            }),
+            format!(
+                "会话 {} 没有匹配的事件（共 {} 条）",
+                page.session_id, page.total_events
+            ),
+        )
+    } else {
+        let truncated_note = if page.truncated {
+            "（已截断）"
+        } else {
+            ""
+        };
+        (
+            json!({
+                "session_id": page.session_id,
+                "total_events": page.total_events,
+                "matched_events": page.matched_events,
+                "truncated": page.truncated,
+                "kind_counts": page.kind_counts,
+                "first_ts": page.first_ts,
+                "last_ts": page.last_ts,
+                "events": events,
+            }),
+            format!(
+                "会话 {}：共 {} 条事件，返回 {} 条{truncated_note}；类型分布 {kind_summary}",
+                page.session_id,
+                page.total_events,
+                events.len(),
+            ),
+        )
+    };
+    ToolOutput::ok(content, summary)
+}
+
+fn render_event(event: &LogEvent) -> Value {
+    json!({
+        "seq": event.seq,
+        "ts": event.ts,
+        "t_ms": event.t_ms,
+        "kind": event.kind,
+        "payload": shrink(&event.payload),
+    })
+}
+
+/// 递归脱敏 + 截断（第二道脱敏防线）。
+fn shrink(value: &Value) -> Value {
+    match value {
+        Value::String(text) => Value::String(cap(&redact_text(text))),
+        Value::Array(items) => Value::Array(items.iter().map(shrink).collect()),
+        Value::Object(map) => {
+            let mut out = Map::with_capacity(map.len());
+            for (key, item) in map {
+                out.insert(key.clone(), shrink(item));
+            }
+            Value::Object(out)
+        }
+        other => other.clone(),
+    }
+}
+
+fn cap(text: &str) -> String {
+    let length = text.chars().count();
+    if length <= MAX_PAYLOAD_CHARS {
+        return text.to_string();
+    }
+    let head: String = text.chars().take(MAX_PAYLOAD_CHARS).collect();
+    format!("{head}…（已截断 {} 字符）", length - MAX_PAYLOAD_CHARS)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockSessions;
+    use serde_json::json;
+
+    const SESSION: &str = "20261029T124501-9f3c2a";
+
+    fn mock() -> MockSessions {
+        let (summary, events) = MockSessions::crashing_session(SESSION);
+        let (older, older_events) = MockSessions::crashing_session("20261028T100000-aaaaaa");
+        let mut sessions = MockSessions::new();
+        sessions.add(summary, events);
+        sessions.add(older, older_events);
+        sessions
+    }
+
+    fn registry() -> ToolRegistry {
+        let mut registry = ToolRegistry::new();
+        register(&mut registry, Arc::new(mock())).expect("注册应成功");
+        registry
+    }
+
+    /// 走**真实注册表 → 真实 handler**，不复制实现（否则测的是复制品）。
+    fn call(tool: &str, args: Value) -> ToolOutput {
+        let registry = registry();
+        let spec = registry.get(tool).expect("工具应存在").clone();
+        (spec.handler)(
+            &ToolCtx {
+                agent_session_id: "s1".to_string(),
+                confirmed: false,
+            },
+            &args,
+        )
+        .expect("工具应成功")
+    }
+
+    #[test]
+    fn lists_sessions_newest_first() {
+        let out = call(LIST_GAME_SESSIONS, json!({ "limit": 5 }));
+        assert_eq!(out.content["count"], json!(2));
+        assert_eq!(out.content["sessions"][0]["session_id"], json!(SESSION));
+        assert_eq!(out.content["problem_count"], json!(2));
+        assert!(out.summary.contains("2 个崩溃/异常退出"));
+    }
+
+    #[test]
+    fn list_respects_limit() {
+        let out = call(LIST_GAME_SESSIONS, json!({ "limit": 1 }));
+        assert_eq!(out.content["count"], json!(1));
+    }
+
+    #[test]
+    fn filters_by_kind_and_keeps_summary() {
+        let out = call(
+            READ_GAME_LOG,
+            json!({ "session_id": SESSION, "kinds": ["stderr"] }),
+        );
+        assert_eq!(out.content["events"].as_array().unwrap().len(), 1);
+        assert_eq!(out.content["kind_counts"]["stdout"], json!(1));
+        assert!(out.summary.contains("共 5 条事件"));
+    }
+
+    #[test]
+    fn truncates_when_more_events_than_cap() {
+        let out = call(
+            READ_GAME_LOG,
+            json!({ "session_id": SESSION, "max_events": 2 }),
+        );
+        assert_eq!(out.content["events"].as_array().unwrap().len(), 2);
+        assert_eq!(out.content["truncated"], json!(true));
+        assert_eq!(out.content["matched_events"], json!(5));
+    }
+
+    #[test]
+    fn masks_user_dir_in_payload() {
+        let out = call(
+            READ_GAME_LOG,
+            json!({ "session_id": SESSION, "kinds": ["crash_found"] }),
+        );
+        let payload = &out.content["events"][0]["payload"];
+        assert_eq!(
+            payload["path"],
+            json!(r"C:\Users\***\.minecraft\crash-reports\crash-1.txt")
+        );
+    }
+
+    #[test]
+    fn reports_empty_result_with_hint() {
+        let out = call(
+            READ_GAME_LOG,
+            json!({ "session_id": SESSION, "kinds": ["window_detected"] }),
+        );
+        assert_eq!(out.content["events"], json!([]));
+        assert!(out.content["hint"].is_string());
+    }
+
+    #[test]
+    fn caps_long_payload_text() {
+        let long = "x".repeat(MAX_PAYLOAD_CHARS + 10);
+        assert!(cap(&long).contains("已截断 10 字符"));
+    }
+
+    #[test]
+    fn unknown_session_is_a_port_error() {
+        let registry = registry();
+        let spec = registry.get(READ_GAME_LOG).expect("工具应存在").clone();
+        let err = (spec.handler)(
+            &ToolCtx {
+                agent_session_id: "s1".to_string(),
+                confirmed: false,
+            },
+            &json!({ "session_id": "nope" }),
+        )
+        .unwrap_err();
+        assert_eq!(err.code(), "port_error");
+        assert!(err.message().contains("不存在"));
+    }
+}

crates/agent/tests/brain_loop.rs

@@ -0,0 +1,248 @@
+//! 对话循环集成测试：mock provider 驱动**完整链路**（provider → 工具编排 → 审计 → 事件）。
+//!
+//! 这里测"循环的骨架"：多轮工具调用、步数上限、流式增量、禁用态、provider 失败。
+//! 安全边界（白名单/确认/YOLO/审计标记）在 `tools_security.rs`。
+
+mod support;
+
+use std::sync::Arc;
+
+use serde_json::json;
+use support::{
+    block_on, list_args, tool_call_reply, Harness, MockProvider, AGENT_SESSION, SESSION,
+};
+use unlucky_agent::audit::AuditOutcome;
+use unlucky_agent::brain::{BrainError, ChatMessage, ChatReply, StopReason, ToolCall};
+use unlucky_agent::event::AgentEvent;
+
+#[test]
+fn single_turn_without_tools_returns_text() {
+    let harness = Harness::new(vec![ChatReply::text("你好，需要我看看最近的崩溃吗？")]);
+    let mut history = Vec::new();
+
+    let outcome = block_on(harness.brain.run_turn(AGENT_SESSION, &mut history, "你好")).unwrap();
+
+    assert_eq!(outcome.text, "你好，需要我看看最近的崩溃吗？");
+    assert_eq!(outcome.steps, 1);
+    assert_eq!(outcome.tool_calls, 0);
+    assert_eq!(outcome.stopped_reason, StopReason::Completed);
+    assert_eq!(history.len(), 2, "应只有 user + assistant");
+    assert!(harness.audit.is_empty(), "没调工具就不该有审计记录");
+}
+
+#[test]
+fn system_prompt_leads_every_request_and_tools_are_projected() {
+    let harness = Harness::new(vec![ChatReply::text("好的")]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "看看配置"),
+    )
+    .unwrap();
+
+    let requests = harness.provider.requests();
+    assert_eq!(requests.len(), 1);
+    let request = &requests[0];
+    assert!(
+        matches!(&request.messages[0], ChatMessage::System { content } if content.contains("Unlucky-Launcher")),
+        "system prompt 必须在首位"
+    );
+    assert_eq!(request.model, "mock-model");
+    let names: Vec<&str> = request.tools.iter().map(|t| t.name.as_str()).collect();
+    assert_eq!(
+        names,
+        vec![
+            "get_config",
+            "set_config",
+            "get_config_schema",
+            "list_instances",
+            "list_versions",
+            "get_java_status",
+            "list_accounts",
+            "list_game_sessions",
+            "read_game_log",
+            "diagnose_crash",
+        ],
+        "注册表的双投影载荷必须原样交给 provider"
+    );
+    // 双投影契约：provider 收到的 schema 与注册表定义逐字节相等。
+    assert_eq!(request.tools, harness.registry.definitions());
+}
+
+#[test]
+fn tool_call_round_trip_feeds_result_back_and_finishes() {
+    let harness = Harness::new(vec![
+        tool_call_reply("call_1", "list_game_sessions", list_args()),
+        ChatReply::text("最近一次会话崩溃了，要不要跑诊断？"),
+    ]);
+    let mut history = Vec::new();
+
+    let outcome = block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "最近崩了吗"),
+    )
+    .unwrap();
+
+    assert_eq!(outcome.tool_calls, 1);
+    assert_eq!(outcome.steps, 2);
+    assert_eq!(outcome.stopped_reason, StopReason::Completed);
+
+    let requests = harness.provider.requests();
+    assert_eq!(requests.len(), 2);
+    let tool_message = requests[1]
+        .messages
+        .iter()
+        .find_map(|m| match m {
+            ChatMessage::Tool {
+                call_id,
+                name,
+                content,
+            } => Some((call_id.clone(), name.clone(), content.clone())),
+            _ => None,
+        })
+        .expect("必须有工具结果消息");
+    assert_eq!(tool_message.0, "call_1");
+    assert_eq!(tool_message.1, "list_game_sessions");
+    assert!(
+        tool_message.2.contains(SESSION),
+        "工具结果应包含会话 id：{}",
+        tool_message.2
+    );
+
+    let audits = harness.audit.records();
+    assert_eq!(audits.len(), 1);
+    assert_eq!(audits[0].tool, "list_game_sessions");
+    assert_eq!(audits[0].outcome, AuditOutcome::Ok);
+    assert!(!audits[0].yolo);
+    assert!(!audits[0].confirmed);
+}
+
+#[test]
+fn multiple_tool_calls_in_one_step_all_execute() {
+    let reply = ChatReply::with_tool_calls(vec![
+        ToolCall {
+            id: "c1".to_string(),
+            name: "list_game_sessions".to_string(),
+            arguments: list_args(),
+        },
+        ToolCall {
+            id: "c2".to_string(),
+            name: "diagnose_crash".to_string(),
+            arguments: json!({ "session_id": SESSION }),
+        },
+    ]);
+    let harness = Harness::new(vec![reply, ChatReply::text("诊断完成")]);
+    let mut history = Vec::new();
+
+    let outcome = block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "查一下"),
+    )
+    .unwrap();
+    assert_eq!(outcome.tool_calls, 2);
+    assert_eq!(harness.audit.len(), 2);
+    assert_eq!(
+        harness
+            .audit
+            .records()
+            .iter()
+            .map(|r| r.tool.as_str())
+            .collect::<Vec<_>>(),
+        vec!["list_game_sessions", "diagnose_crash"]
+    );
+}
+
+#[test]
+fn step_limit_stops_runaway_loop() {
+    // 每一步都要求调工具，永远不会给最终回答。
+    let script: Vec<ChatReply> = (0..16)
+        .map(|i| tool_call_reply(&format!("c{i}"), "get_config", json!({})))
+        .collect();
+    let harness = Harness::new(script);
+    let mut history = Vec::new();
+
+    let outcome = block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "死循环"),
+    )
+    .unwrap();
+    assert_eq!(outcome.stopped_reason, StopReason::StepLimit);
+    assert_eq!(outcome.steps, unlucky_agent::brain::DEFAULT_MAX_STEPS);
+    assert_eq!(outcome.tool_calls, unlucky_agent::brain::DEFAULT_MAX_STEPS);
+}
+
+#[test]
+fn streaming_deltas_are_forwarded_as_events() {
+    let harness = Harness::new(vec![ChatReply::text("日志里是 NoClassDefFoundError")]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "什么错误"),
+    )
+    .unwrap();
+
+    assert_eq!(
+        harness.events.streamed_text(),
+        "日志里是 NoClassDefFoundError"
+    );
+    let events = harness.events.events();
+    assert!(events
+        .iter()
+        .any(|e| matches!(e, AgentEvent::TurnStarted { .. })));
+    assert!(events
+        .iter()
+        .any(|e| matches!(e, AgentEvent::AssistantText { .. })));
+    assert!(events
+        .iter()
+        .any(|e| matches!(e, AgentEvent::TurnFinished { .. })));
+}
+
+#[test]
+fn disabled_provider_fails_fast() {
+    let harness = Harness::from_provider(Arc::new(MockProvider::disabled()));
+    let mut history = Vec::new();
+
+    let err = block_on(harness.brain.run_turn(AGENT_SESSION, &mut history, "你好")).unwrap_err();
+    assert_eq!(err, BrainError::Disabled);
+    assert!(err.to_string().contains("规则引擎"), "要提示降级能力");
+    assert!(
+        harness.provider.requests().is_empty(),
+        "禁用态不该发起任何请求"
+    );
+    assert!(history.is_empty(), "禁用态不该改动历史");
+}
+
+#[test]
+fn provider_error_surfaces_as_brain_error_and_event() {
+    let harness = Harness::from_provider(Arc::new(MockProvider::failing(
+        "连接 http://127.0.0.1:8080 失败",
+    )));
+    let mut history = Vec::new();
+
+    let err = block_on(harness.brain.run_turn(AGENT_SESSION, &mut history, "你好")).unwrap_err();
+    assert_eq!(
+        err,
+        BrainError::Provider(unlucky_agent::brain::ProviderError::new(
+            "连接 http://127.0.0.1:8080 失败"
+        ))
+    );
+    assert!(harness
+        .events
+        .events()
+        .iter()
+        .any(|e| matches!(e, AgentEvent::Error { message } if message.contains("8080"))));
+}
+
+#[test]
+fn empty_script_yields_empty_completion_turn() {
+    let harness = Harness::new(vec![]);
+    let mut history = Vec::new();
+    let outcome = block_on(harness.brain.run_turn(AGENT_SESSION, &mut history, "你好")).unwrap();
+    assert_eq!(outcome.text, "");
+    assert_eq!(outcome.stopped_reason, StopReason::Completed);
+}

crates/agent/tests/mcp_contract.rs

@@ -0,0 +1,132 @@
+//! **双投影契约测试（MCP 侧）**：注册表 → rmcp `Tool` 必须与 rig 侧逐项相等。
+//!
+//! research/02 §6.2 建议进 CI 的那条断言，M16 落的是「注册表自身是纯投影」+「rig 适配层
+//! 只做直投」，M39 补上 rmcp 侧：
+//!
+//! 1. `mcp::projection::tool_attrs(&registry)` 的 `(name, description, input_schema)`
+//!    与 `registry.definitions()` **逐项相等**（JSON 层面，不是"看起来差不多"）；
+//! 2. `tools/list` 的顺序与注册顺序一致，数量等于注册表长度；
+//! 3. 每个 schema 根是 `object`（rig 与 rmcp 的共同前提）；
+//! 4. `read_only_hint` 与 `Access` 一致（外部客户端据此决定能不能静默调用）；
+//! 5. 只读子集不会漏出写工具（`agent.mcp.allow_write=false` 的默认形态）。
+
+use serde_json::{json, Value};
+use unlucky_agent::mcp::projection::{tool_attr, tool_attrs};
+use unlucky_agent::port::Ports;
+use unlucky_agent::registry::{Access, ToolDefinition, ToolRegistry};
+use unlucky_agent::testing::mock_ports;
+use unlucky_agent::tools::build_v1_registry;
+
+fn registry() -> ToolRegistry {
+    let (ports, _settings) = mock_ports();
+    build_v1_registry(&ports).expect("注册表应装配成功")
+}
+
+fn ports() -> Ports {
+    mock_ports().0
+}
+
+#[test]
+fn mcp_projection_equals_registry_definition_item_by_item() {
+    let registry = registry();
+    let definitions = registry.definitions();
+    let attrs = tool_attrs(&registry);
+    assert_eq!(attrs.len(), definitions.len());
+
+    for (attr, definition) in attrs.iter().zip(definitions.iter()) {
+        assert_eq!(attr.name.as_ref(), definition.name, "工具名必须相等");
+        assert_eq!(
+            attr.description.as_deref(),
+            Some(definition.description.as_str()),
+            "{} 的 description 必须逐字相等",
+            definition.name
+        );
+        assert_eq!(
+            Value::Object((*attr.input_schema).clone()),
+            definition.input_schema,
+            "{} 的 JSON Schema 必须逐项相等",
+            definition.name
+        );
+    }
+}
+
+#[test]
+fn projection_order_matches_registration_order() {
+    let registry = registry();
+    let projected: Vec<String> = tool_attrs(&registry)
+        .iter()
+        .map(|attr| attr.name.to_string())
+        .collect();
+    assert_eq!(projected, registry.names(), "两侧顺序必须一致");
+}
+
+#[test]
+fn every_projected_schema_is_an_object_and_round_trips() {
+    for attr in tool_attrs(&registry()) {
+        let schema = Value::Object((*attr.input_schema).clone());
+        assert_eq!(
+            schema["type"],
+            json!("object"),
+            "{} 的 schema 根必须是 object",
+            attr.name
+        );
+        // rmcp 会把 Tool 序列化进 tools/list 的响应体：必须能反序列化回来。
+        let json = serde_json::to_string(&attr).expect("Tool 可序列化");
+        let back: rmcp::model::Tool = serde_json::from_str(&json).expect("Tool 可反序列化");
+        assert_eq!(back, attr);
+    }
+}
+
+#[test]
+fn read_only_hint_tracks_access() {
+    let registry = registry();
+    for (attr, spec) in tool_attrs(&registry).iter().zip(registry.specs()) {
+        let hint = attr
+            .annotations
+            .as_ref()
+            .and_then(|annotations| annotations.read_only_hint)
+            .expect("每个工具都应有 read_only_hint");
+        assert_eq!(hint, spec.access == Access::ReadOnly, "{}", attr.name);
+    }
+}
+
+#[test]
+fn read_only_subset_projects_without_the_writing_tool() {
+    let subset = registry().read_only_subset();
+    assert_eq!(subset.len(), 9);
+    let names: Vec<String> = tool_attrs(&subset)
+        .iter()
+        .map(|attr| attr.name.to_string())
+        .collect();
+    assert!(!names.iter().any(|name| name == "set_config"), "{names:?}");
+    assert!(subset.access_of("set_config").is_none());
+}
+
+#[test]
+fn projected_attrs_are_pure_functions_of_the_definition() {
+    let definition = ToolDefinition {
+        name: "demo".to_string(),
+        description: "演示".to_string(),
+        input_schema: json!({ "type": "object", "properties": {}, "required": [] }),
+    };
+    let first = tool_attr(&definition, Access::ReadOnly);
+    let second = tool_attr(&definition, Access::ReadOnly);
+    assert_eq!(first, second);
+
+    // 副作用等级换一下，只有 annotations 变，name/description/schema 不变。
+    let mutating = tool_attr(&definition, Access::Mutating);
+    assert_eq!(first.name, mutating.name);
+    assert_eq!(first.input_schema, mutating.input_schema);
+    assert_ne!(first.annotations, mutating.annotations);
+}
+
+#[test]
+fn mock_ports_cover_every_port_the_registry_needs() {
+    // 装配完整性：五个端口都在，注册表才有这十个工具（少一个端口 = 少工具）。
+    let ports = ports();
+    let registry = build_v1_registry(&ports).expect("注册表应装配成功");
+    assert_eq!(registry.len(), 10);
+    assert!(unlucky_agent::testing::expected_v1_tool_names()
+        .iter()
+        .all(|name| registry.get(name).is_some()));
+}

crates/agent/tests/mcp_http.rs

@@ -0,0 +1,336 @@
+//! MCP over Streamable HTTP 的端到端测试：真起监听、打裸 JSON-RPC，断言工具返回与审计。
+//!
+//! 为什么不用 MCP 客户端 crate：客户端依赖会再拖一棵 reqwest 树（且 3.8 的客户端 feature
+//! 与我们的服务端 feature 不是一组）。裸 HTTP 反而更贴近「用户用 Claude Code 连上来」
+//! 的实际形状——握手、会话头、`tools/list`、`tools/call` 一个都不省。
+//!
+//! 覆盖的安全语义（02 §3.1 / §4b）：
+//! - 只读模式下 `set_config` 根本不在工具表里，硬调 → tool-level 错误 + `unknown_tool` 审计；
+//! - 普通键（`download.concurrency`，Low）直接写入，审计 `outcome=ok`；
+//! - 敏感键（`java.selected_path`，High）在**没有弹窗**的外部场景被拒，文案引导去设置页/YOLO；
+//! - 打开 YOLO 后同一个写入成功，审计 `yolo=true`。
+
+use std::net::SocketAddr;
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpStream;
+use unlucky_agent::audit::{AuditOutcome, AuditRecord, JsonlAudit};
+use unlucky_agent::brain::exec::ToolExecutor;
+use unlucky_agent::clock::{FixedClock, SharedClock};
+use unlucky_agent::confirm::{ConfirmPolicy, DenyGuidance, NoUiGate};
+use unlucky_agent::event::NoopSink;
+use unlucky_agent::mcp::{bind, serve_http_on, McpConfig, RegistryServer};
+use unlucky_agent::testing::mock_ports;
+use unlucky_agent::tools::build_v1_registry;
+
+const INITIALIZE: &str = r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"ull-test","version":"0.1"}}}"#;
+
+struct Harness {
+    addr: SocketAddr,
+    audit_dir: std::path::PathBuf,
+}
+
+fn audit_dir(tag: &str) -> std::path::PathBuf {
+    let dir = std::env::temp_dir().join(format!("ull-mcp-http-{tag}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    dir
+}
+
+fn server(read_only: bool, yolo: bool, audit: Arc<JsonlAudit>) -> RegistryServer {
+    let (ports, _settings) = mock_ports();
+    let registry = Arc::new(build_v1_registry(&ports).expect("注册表应装配成功"));
+    let exposed = if read_only {
+        Arc::new(registry.read_only_subset())
+    } else {
+        Arc::clone(&registry)
+    };
+    let clock: SharedClock = Arc::new(FixedClock::new(1_793_304_753_123));
+    let executor = Arc::new(
+        ToolExecutor::new(
+            exposed,
+            audit,
+            Arc::new(NoUiGate),
+            ConfirmPolicy { yolo },
+            clock,
+            Arc::new(NoopSink),
+        )
+        .with_guidance(DenyGuidance::External),
+    );
+    RegistryServer::new(registry, executor, "mcp-http", read_only)
+}
+
+async fn spawn(tag: &str, read_only: bool, yolo: bool) -> Harness {
+    let dir = audit_dir(tag);
+    let clock: SharedClock = Arc::new(FixedClock::new(1_793_304_753_123));
+    let audit = Arc::new(JsonlAudit::new(&dir, clock));
+    let server = server(read_only, yolo, audit);
+
+    let cfg = McpConfig {
+        port: 0,
+        ..McpConfig::default()
+    };
+    let (addr, listener) = bind(&cfg).await.expect("应能绑定临时端口");
+    tokio::spawn(async move {
+        let _ = serve_http_on(server, cfg, addr, listener).await;
+    });
+    Harness {
+        addr,
+        audit_dir: dir,
+    }
+}
+
+/// 发一条 HTTP POST（`Connection: close` 让读取变成 read_to_end）。
+async fn post(
+    addr: SocketAddr,
+    body: &str,
+    session: Option<&str>,
+    token: Option<&str>,
+) -> (u16, Option<String>, String) {
+    let mut stream = TcpStream::connect(addr).await.expect("连接失败");
+    let mut head = format!(
+        "POST /mcp HTTP/1.1\r\nHost: {addr}\r\nContent-Type: application/json\r\n\
+         Accept: application/json, text/event-stream\r\nConnection: close\r\n\
+         Content-Length: {}\r\n",
+        body.len()
+    );
+    if let Some(session) = session {
+        head.push_str(&format!("Mcp-Session-Id: {session}\r\n"));
+    }
+    if let Some(token) = token {
+        head.push_str(&format!("Authorization: Bearer {token}\r\n"));
+    }
+    head.push_str("\r\n");
+    stream
+        .write_all(format!("{head}{body}").as_bytes())
+        .await
+        .expect("写请求失败");
+    stream.flush().await.expect("刷新失败");
+
+    let mut raw = Vec::new();
+    stream.read_to_end(&mut raw).await.expect("读响应失败");
+    let text = String::from_utf8_lossy(&raw).to_string();
+    let (head, body) = text.split_once("\r\n\r\n").unwrap_or((text.as_str(), ""));
+    let status = head
+        .lines()
+        .next()
+        .and_then(|line| line.split_whitespace().nth(1))
+        .and_then(|code| code.parse::<u16>().ok())
+        .unwrap_or(0);
+    let session = head.lines().find_map(|line| {
+        let (name, value) = line.split_once(':')?;
+        name.eq_ignore_ascii_case("mcp-session-id")
+            .then(|| value.trim().to_string())
+    });
+    (status, session, body.to_string())
+}
+
+/// 响应体可能是裸 JSON，也可能是 SSE（`data: {...}`）；两种都解出第一条 JSON-RPC 响应。
+fn parse_rpc(body: &str) -> Value {
+    if let Ok(value) = serde_json::from_str::<Value>(body.trim()) {
+        return value;
+    }
+    for line in body.lines() {
+        let Some(data) = line.strip_prefix("data: ") else {
+            continue;
+        };
+        if let Ok(value) = serde_json::from_str::<Value>(data.trim()) {
+            return value;
+        }
+    }
+    panic!("响应体既不是 JSON 也不是 SSE：{body}");
+}
+
+async fn initialize(addr: SocketAddr) -> Option<String> {
+    let (status, session, body) = post(addr, INITIALIZE, None, None).await;
+    assert_eq!(status, 200, "initialize 应成功：{body}");
+    let response = parse_rpc(&body);
+    assert_eq!(
+        response["result"]["serverInfo"]["name"],
+        json!("unlucky-launcher")
+    );
+    // 按 MCP 规范补一条 initialized 通知（无 id、无响应体）。
+    let _ = post(
+        addr,
+        r#"{"jsonrpc":"2.0","method":"notifications/initialized"}"#,
+        session.as_deref(),
+        None,
+    )
+    .await;
+    session
+}
+
+async fn rpc(
+    addr: SocketAddr,
+    session: Option<&str>,
+    id: u32,
+    method: &str,
+    params: Value,
+) -> Value {
+    let body =
+        json!({ "jsonrpc": "2.0", "id": id, "method": method, "params": params }).to_string();
+    let (status, _session, text) = post(addr, &body, session, None).await;
+    assert_eq!(status, 200, "{method} 应成功：{text}");
+    parse_rpc(&text)
+}
+
+fn audit_records(dir: &std::path::Path) -> Vec<AuditRecord> {
+    let mut out = Vec::new();
+    if let Ok(entries) = std::fs::read_dir(dir) {
+        for entry in entries.flatten() {
+            let text = std::fs::read_to_string(entry.path()).unwrap_or_default();
+            for line in text.lines() {
+                if let Ok(record) = serde_json::from_str::<AuditRecord>(line) {
+                    out.push(record);
+                }
+            }
+        }
+    }
+    out
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn readonly_server_lists_and_serves_only_read_tools() {
+    let harness = spawn("readonly", true, false).await;
+    let session = initialize(harness.addr).await;
+
+    let list = rpc(harness.addr, session.as_deref(), 2, "tools/list", json!({})).await;
+    let tools = list["result"]["tools"].as_array().expect("应有 tools 数组");
+    let names: Vec<&str> = tools
+        .iter()
+        .filter_map(|tool| tool["name"].as_str())
+        .collect();
+    assert_eq!(names.len(), 9, "{names:?}");
+    assert!(!names.contains(&"set_config"), "只读模式不得暴露写工具");
+    assert!(names.contains(&"get_config"));
+
+    // 真调一个只读工具：返回真实配置概要（mock 端口）。
+    let call = rpc(
+        harness.addr,
+        session.as_deref(),
+        3,
+        "tools/call",
+        json!({ "name": "get_config", "arguments": {} }),
+    )
+    .await;
+    assert_ne!(call["result"]["isError"], json!(true), "{call}");
+    let text = call["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or_default();
+    assert!(text.contains("download.concurrency"), "{text}");
+
+    // 硬调写工具：tool-level 错误（客户端能看见文案）+ unknown_tool 审计。
+    let denied = rpc(
+        harness.addr,
+        session.as_deref(),
+        4,
+        "tools/call",
+        json!({ "name": "set_config", "arguments": { "path": "download.concurrency", "value": 16 } }),
+    )
+    .await;
+    assert_eq!(denied["result"]["isError"], json!(true), "{denied}");
+
+    let records = audit_records(&harness.audit_dir);
+    assert!(records.iter().any(|r| r.tool == "get_config"
+        && r.outcome == AuditOutcome::Ok
+        && r.agent_session_id == "mcp-http"));
+    assert!(records
+        .iter()
+        .any(|r| r.tool == "set_config" && r.outcome == AuditOutcome::UnknownTool));
+    let _ = std::fs::remove_dir_all(&harness.audit_dir);
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn write_server_enforces_sensitive_key_confirmation() {
+    let harness = spawn("write", false, false).await;
+    let session = initialize(harness.addr).await;
+
+    // 普通键：直接写。
+    let ok = rpc(
+        harness.addr,
+        session.as_deref(),
+        2,
+        "tools/call",
+        json!({ "name": "set_config", "arguments": { "path": "download.concurrency", "value": 16 } }),
+    )
+    .await;
+    assert_ne!(ok["result"]["isError"], json!(true), "{ok}");
+
+    // 敏感键：外部客户端没有弹窗 → 拒绝，文案要能指导用户下一步。
+    let denied = rpc(
+        harness.addr,
+        session.as_deref(),
+        3,
+        "tools/call",
+        json!({ "name": "set_config", "arguments": { "path": "java.selected_path", "value": "D:/jdk17/bin/java.exe" } }),
+    )
+    .await;
+    assert_eq!(denied["result"]["isError"], json!(true), "{denied}");
+    let text = denied["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or_default();
+    assert!(
+        text.contains("YOLO"),
+        "拒绝文案应引导到 YOLO/设置页：{text}"
+    );
+    assert!(text.contains("设置页"), "{text}");
+
+    let records = audit_records(&harness.audit_dir);
+    assert!(records
+        .iter()
+        .any(|r| r.tool == "set_config" && r.outcome == AuditOutcome::AwaitingConfirmation));
+    assert!(records
+        .iter()
+        .any(|r| r.tool == "set_config" && r.outcome == AuditOutcome::Denied && !r.yolo));
+    let _ = std::fs::remove_dir_all(&harness.audit_dir);
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn yolo_lets_the_same_write_through_and_audits_the_flag() {
+    let harness = spawn("yolo", false, true).await;
+    let session = initialize(harness.addr).await;
+
+    let written = rpc(
+        harness.addr,
+        session.as_deref(),
+        2,
+        "tools/call",
+        json!({ "name": "set_config", "arguments": { "path": "java.selected_path", "value": "D:/jdk17/bin/java.exe" } }),
+    )
+    .await;
+    assert_ne!(written["result"]["isError"], json!(true), "{written}");
+
+    let records = audit_records(&harness.audit_dir);
+    let yolo_ok = records
+        .iter()
+        .find(|r| r.tool == "set_config" && r.outcome == AuditOutcome::Ok);
+    let record = yolo_ok.expect("应有一条 ok 审计");
+    assert!(record.yolo, "YOLO 放行必须标记 yolo=true");
+    assert!(!record.confirmed, "YOLO 自动放行不算用户确认");
+    let _ = std::fs::remove_dir_all(&harness.audit_dir);
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn bearer_token_is_enforced_when_configured() {
+    let dir = audit_dir("token");
+    let clock: SharedClock = Arc::new(FixedClock::new(1_793_304_753_123));
+    let audit = Arc::new(JsonlAudit::new(&dir, clock));
+    let server = server(true, false, audit);
+    let cfg = McpConfig {
+        port: 0,
+        token: Some("s3cret".to_string()),
+        ..McpConfig::default()
+    };
+    let (addr, listener) = bind(&cfg).await.expect("应能绑定");
+    tokio::spawn(async move {
+        let _ = serve_http_on(server, cfg, addr, listener).await;
+    });
+
+    let (status, _, _) = post(addr, INITIALIZE, None, None).await;
+    assert_eq!(status, 401, "没带令牌必须 401");
+
+    let (status, _, body) = post(addr, INITIALIZE, None, Some("s3cret")).await;
+    assert_eq!(status, 200, "带对令牌应通过：{body}");
+    let _ = std::fs::remove_dir_all(&dir);
+}

crates/agent/tests/schema_contract.rs

@@ -0,0 +1,163 @@
+//! **双投影契约测试**（research/02 §6.2 建议进 CI 的那一条）。
+//!
+//! rig 侧（`DynamicTool::new`）与 rmcp 侧（`ToolRoute::new_dyn`）吃的都是
+//! `(name, description, serde_json::Value schema)`。本 crate 只维护一份 `ToolSpec`，
+//! 所以「两侧相等」在这里等价于三条可断言的性质：
+//! 1. [`unlucky_agent::registry::ToolRegistry::definitions`] 是纯投影（多次调用逐字节相等）；
+//! 2. 每个 schema 根是 `type: object`（两侧都要求对象入参）且拒绝多余参数；
+//! 3. 名字唯一，`required` 真的被执行（缺参能被校验器抓到）。
+//!
+//! 本文件只锁**投影载荷本身**；两侧的一致性各有专测：
+//! - rig 侧：`tests/brain_loop.rs` 断言 `provider` 收到的 `request.tools` 与
+//!   `registry.definitions()` 逐字节相等（`brain/rig.rs` 只做直投）；
+//! - MCP 侧：`tests/mcp_contract.rs` 断言 rmcp `Tool` 的 `(name, description, schema)` 与
+//!   注册表逐项相等（M39 补的那条）。
+
+use serde_json::json;
+use unlucky_agent::registry::validate::validate;
+use unlucky_agent::registry::{Access, ToolDefinition};
+use unlucky_agent::testing::mock_ports;
+
+fn registry() -> unlucky_agent::registry::ToolRegistry {
+    let (ports, _settings) = mock_ports();
+    unlucky_agent::tools::build_v1_registry(&ports).expect("注册表应装配成功")
+}
+
+#[test]
+fn ships_exactly_the_v1_tools() {
+    let registry = registry();
+    assert_eq!(
+        registry.names(),
+        vec![
+            "get_config",
+            "set_config",
+            "get_config_schema",
+            "list_instances",
+            "list_versions",
+            "get_java_status",
+            "list_accounts",
+            "list_game_sessions",
+            "read_game_log",
+            "diagnose_crash",
+        ]
+    );
+    assert_eq!(registry.len(), 10);
+}
+
+#[test]
+fn definitions_are_pure_projections() {
+    let registry = registry();
+    let first = registry.definitions();
+    let second = registry.definitions();
+    assert_eq!(first, second, "投影必须是纯函数");
+
+    for definition in &first {
+        // 序列化后再反序列化必须完全一样（rig 与 rmcp 都走 JSON）。
+        let json = serde_json::to_string(definition).expect("可序列化");
+        let round_trip: ToolDefinition = serde_json::from_str(&json).expect("可反序列化");
+        assert_eq!(&round_trip, definition);
+        assert!(!definition.description.trim().is_empty());
+        assert_eq!(
+            definition.input_schema["type"],
+            json!("object"),
+            "{} 的 schema 根必须是 object",
+            definition.name
+        );
+    }
+}
+
+#[test]
+fn only_set_config_is_mutating() {
+    let registry = registry();
+    for name in registry.names() {
+        let expected = if name == "set_config" {
+            Access::Mutating
+        } else {
+            Access::ReadOnly
+        };
+        assert_eq!(registry.access_of(name), Some(expected), "{name}");
+    }
+    let read_only: Vec<String> = registry
+        .read_only_definitions()
+        .into_iter()
+        .map(|d| d.name)
+        .collect();
+    assert_eq!(
+        read_only,
+        vec![
+            "get_config",
+            "get_config_schema",
+            "list_instances",
+            "list_versions",
+            "get_java_status",
+            "list_accounts",
+            "list_game_sessions",
+            "read_game_log",
+            "diagnose_crash",
+        ],
+        "只读 MCP 模式只暴露这九个（写侧只有 set_config）"
+    );
+}
+
+#[test]
+fn every_schema_rejects_unknown_arguments() {
+    for definition in registry().definitions() {
+        let err = validate(&definition.input_schema, &json!({ "__unexpected": 1 }))
+            .expect_err(&format!("{} 应拒绝野参数", definition.name));
+        assert!(
+            err.iter().any(|e| e.contains("不是可接受的参数名")),
+            "{}: {err:?}",
+            definition.name
+        );
+    }
+}
+
+#[test]
+fn required_fields_are_actually_enforced() {
+    for definition in registry().definitions() {
+        let required = definition
+            .input_schema
+            .get("required")
+            .and_then(|r| r.as_array())
+            .cloned()
+            .unwrap_or_default();
+        if required.is_empty() {
+            continue;
+        }
+        let err = validate(&definition.input_schema, &json!({}))
+            .expect_err(&format!("{} 应有必填参数", definition.name));
+        for field in required {
+            let name = field.as_str().unwrap_or_default();
+            assert!(
+                err.iter().any(|e| e.contains(name)),
+                "{} 的必填 `{name}` 没被校验：{err:?}",
+                definition.name
+            );
+        }
+    }
+}
+
+#[test]
+fn integer_bounds_are_declared_and_enforced() {
+    let registry = registry();
+    let read_log = registry.get("read_game_log").expect("工具存在");
+    let max_events = &read_log.input_schema["properties"]["max_events"];
+    assert_eq!(max_events["minimum"], json!(1));
+    assert_eq!(max_events["maximum"], json!(500));
+
+    assert!(validate(
+        &read_log.input_schema,
+        &json!({ "session_id": "s", "max_events": 0 })
+    )
+    .is_err());
+    assert!(validate(
+        &read_log.input_schema,
+        &json!({ "session_id": "s", "max_events": 501 })
+    )
+    .is_err());
+    assert!(validate(
+        &read_log.input_schema,
+        &json!({ "session_id": "s", "max_events": 500 })
+    )
+    .is_ok());
+}

crates/agent/tests/support/mod.rs

@@ -0,0 +1,225 @@
+//! 集成测试的公共脚手架：**mock provider** + 迷你 `block_on` + 装配好的 harness。
+//!
+//! `block_on` 是手写的 20 行：mock provider 的 future 永远立刻 Ready，所以不需要运行时。
+//! 这样 agent 的循环测试**零 tokio 依赖**，阶段 B 换成 rig 后才需要真运行时。
+
+#![allow(dead_code)]
+
+use std::collections::VecDeque;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, Mutex};
+use std::task::{Context, Poll, Waker};
+
+use serde_json::{json, Value};
+use unlucky_agent::audit::{AuditSink, MemoryAudit};
+use unlucky_agent::brain::{Brain, BrainConfig, BrainDeps};
+use unlucky_agent::brain::{
+    ChatProvider, ChatReply, ChatRequest, DeltaObserver, ProviderConfig, ProviderError,
+    ProviderFuture, ToolCall,
+};
+use unlucky_agent::clock::{FixedClock, SharedClock};
+use unlucky_agent::confirm::{AutoApproveGate, ConfirmGate, ConfirmPolicy, NoUiGate};
+use unlucky_agent::event::{AgentEventSink, MemoryEventSink};
+use unlucky_agent::registry::ToolRegistry;
+use unlucky_agent::testing::{mock_ports, MockSettings};
+
+/// 立刻完成的 future 直接 poll；挂起就是测试写错了。
+pub fn block_on<F: Future>(future: F) -> F::Output {
+    let mut future: Pin<Box<F>> = Box::pin(future);
+    let waker = Waker::noop();
+    let mut context = Context::from_waker(waker);
+    match future.as_mut().poll(&mut context) {
+        Poll::Ready(value) => value,
+        Poll::Pending => panic!("mock provider 不应挂起：测试里没有执行器"),
+    }
+}
+
+/// 脚本化 provider：按顺序回放 [`ChatReply`]，并记录收到的请求。
+pub struct MockProvider {
+    config: ProviderConfig,
+    script: Mutex<VecDeque<ChatReply>>,
+    requests: Mutex<Vec<ChatRequest>>,
+    fail_with: Option<String>,
+}
+
+impl MockProvider {
+    /// 用默认模型名（本地 llama.cpp 形态）回放脚本。
+    #[must_use]
+    pub fn new(script: Vec<ChatReply>) -> Self {
+        Self {
+            config: ProviderConfig::llamacpp_local("mock-model"),
+            script: Mutex::new(script.into()),
+            requests: Mutex::new(Vec::new()),
+            fail_with: None,
+        }
+    }
+
+    /// 禁用态（测 `BrainError::Disabled`）。
+    #[must_use]
+    pub fn disabled() -> Self {
+        Self {
+            config: ProviderConfig::disabled(),
+            script: Mutex::new(VecDeque::new()),
+            requests: Mutex::new(Vec::new()),
+            fail_with: None,
+        }
+    }
+
+    /// 每次补全都失败（测 provider 错误透传）。
+    #[must_use]
+    pub fn failing(message: &str) -> Self {
+        Self {
+            fail_with: Some(message.to_string()),
+            ..Self::new(Vec::new())
+        }
+    }
+
+    /// 收到的请求（断言 system prompt / 工具定义 / 回灌的工具消息）。
+    #[must_use]
+    pub fn requests(&self) -> Vec<ChatRequest> {
+        self.requests.lock().map(|r| r.clone()).unwrap_or_default()
+    }
+}
+
+impl ChatProvider for MockProvider {
+    fn config(&self) -> &ProviderConfig {
+        &self.config
+    }
+
+    fn complete<'a>(
+        &'a self,
+        request: &'a ChatRequest,
+        observer: &'a dyn DeltaObserver,
+    ) -> ProviderFuture<'a> {
+        Box::pin(async move {
+            if let Ok(mut requests) = self.requests.lock() {
+                requests.push(request.clone());
+            }
+            if let Some(message) = &self.fail_with {
+                return Err(ProviderError::new(message.clone()));
+            }
+            let reply = self
+                .script
+                .lock()
+                .ok()
+                .and_then(|mut script| script.pop_front())
+                .unwrap_or_default();
+            // 按 4 字符切块吐增量，模拟流式。
+            if !reply.text.is_empty() {
+                for chunk in reply.text.chars().collect::<Vec<_>>().chunks(4) {
+                    observer.on_delta(&chunk.iter().collect::<String>());
+                }
+            }
+            Ok(reply)
+        })
+    }
+}
+
+/// 装配好的测试环境。
+pub struct Harness {
+    /// 对话循环。
+    pub brain: Brain,
+    /// 审计出口（内存）。
+    pub audit: Arc<MemoryAudit>,
+    /// 事件出口（内存）。
+    pub events: Arc<MemoryEventSink>,
+    /// mock provider（查请求）。
+    pub provider: Arc<MockProvider>,
+    /// mock 配置端口（查是否真的写入）。
+    pub settings: Arc<MockSettings>,
+    /// 工具注册表。
+    pub registry: Arc<ToolRegistry>,
+}
+
+impl Harness {
+    /// P0 默认形态：无确认 UI（`NoUiGate`，敏感操作 fail-closed）+ 非 YOLO。
+    /// 确认请求本身仍会作为 [`unlucky_agent::event::AgentEvent::ConfirmRequested`] 发出。
+    #[must_use]
+    pub fn new(script: Vec<ChatReply>) -> Self {
+        Self::with_gate(script, ConfirmPolicy::default(), |_sink| Arc::new(NoUiGate))
+    }
+
+    /// YOLO：自动放行全部（除破坏性）。
+    #[must_use]
+    pub fn yolo(script: Vec<ChatReply>) -> Self {
+        Self::with_gate(script, ConfirmPolicy { yolo: true }, |_sink| {
+            Arc::new(AutoApproveGate)
+        })
+    }
+
+    /// 用指定的（可能失效/禁用的）provider 装配，其余同 [`Harness::new`]。
+    #[must_use]
+    pub fn from_provider(provider: Arc<MockProvider>) -> Self {
+        Self::build(provider, ConfirmPolicy::default(), |_sink| {
+            Arc::new(NoUiGate)
+        })
+    }
+
+    /// 自定义闸门 + 策略。
+    #[must_use]
+    pub fn with_gate(
+        script: Vec<ChatReply>,
+        policy: ConfirmPolicy,
+        make_gate: impl FnOnce(Arc<dyn AgentEventSink>) -> Arc<dyn ConfirmGate>,
+    ) -> Self {
+        Self::build(Arc::new(MockProvider::new(script)), policy, make_gate)
+    }
+
+    fn build(
+        provider: Arc<MockProvider>,
+        policy: ConfirmPolicy,
+        make_gate: impl FnOnce(Arc<dyn AgentEventSink>) -> Arc<dyn ConfirmGate>,
+    ) -> Self {
+        let (ports, settings) = mock_ports();
+        let registry =
+            Arc::new(unlucky_agent::tools::build_v1_registry(&ports).expect("注册表应装配成功"));
+        let audit = Arc::new(MemoryAudit::new());
+        let events = Arc::new(MemoryEventSink::new());
+        let clock: SharedClock = Arc::new(FixedClock::with_step(1_793_314_353_123, 3));
+        let gate = make_gate(events.clone());
+        let deps = BrainDeps::new(
+            audit.clone() as Arc<dyn AuditSink>,
+            gate,
+            policy,
+            clock,
+            events.clone() as Arc<dyn AgentEventSink>,
+        );
+        let brain = Brain::new(
+            provider.clone(),
+            Arc::clone(&registry),
+            deps,
+            BrainConfig::default(),
+        );
+        Self {
+            brain,
+            audit,
+            events,
+            provider,
+            settings,
+            registry,
+        }
+    }
+}
+
+/// 构造一条工具调用回复。
+#[must_use]
+pub fn tool_call_reply(id: &str, name: &str, arguments: Value) -> ChatReply {
+    ChatReply::with_tool_calls(vec![ToolCall {
+        id: id.to_string(),
+        name: name.to_string(),
+        arguments,
+    }])
+}
+
+/// 便捷：游戏会话 id（与 `MockSessions::crashing_session` 一致）。
+pub const SESSION: &str = "20261029T124501-9f3c2a";
+
+/// 便捷：agent 对话会话 id。
+pub const AGENT_SESSION: &str = "chat-1";
+
+/// 便捷：`list_game_sessions` 的最小参数。
+#[must_use]
+pub fn list_args() -> Value {
+    json!({ "limit": 5 })
+}

crates/agent/tests/tools_security.rs

@@ -0,0 +1,365 @@
+//! 安全边界集成测试：白名单拦截、分级确认、YOLO、审计标记。
+//!
+//! 这些是 02 文档 §3.1「安全边界」+ §4b「YOLO」与 M12 `setting-接口约定.md` §8
+//! （`Low/Medium/High` 三档 + `writable=false` 凭据）的可执行版本；
+//! 判断口径对照 research/02 §7 R9（写操作的破坏半径）。
+
+mod support;
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+use support::{block_on, tool_call_reply, Harness, AGENT_SESSION};
+use unlucky_agent::audit::AuditOutcome;
+use unlucky_agent::brain::ChatReply;
+use unlucky_agent::confirm::{ConfirmDecision, ConfirmPolicy, ScriptedGate};
+use unlucky_agent::event::AgentEvent;
+
+fn set_config_reply(path: &str, value: Value) -> ChatReply {
+    tool_call_reply("c1", "set_config", json!({ "path": path, "value": value }))
+}
+
+fn tool_results(harness: &Harness) -> Vec<String> {
+    harness
+        .provider
+        .requests()
+        .last()
+        .map(|request| {
+            request
+                .messages
+                .iter()
+                .filter_map(|m| match m {
+                    unlucky_agent::brain::ChatMessage::Tool { content, .. } => {
+                        Some(content.clone())
+                    }
+                    _ => None,
+                })
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn confirm_events(harness: &Harness) -> usize {
+    harness
+        .events
+        .events()
+        .iter()
+        .filter(|e| matches!(e, AgentEvent::ConfirmRequested { .. }))
+        .count()
+}
+
+#[test]
+fn low_key_writes_silently_without_confirmation() {
+    let harness = Harness::new(vec![
+        set_config_reply("appearance.theme_mode", json!("metro_light")),
+        ChatReply::text("已切换主题"),
+    ]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "换成浅色"),
+    )
+    .unwrap();
+
+    assert_eq!(harness.settings.set_calls(), 1);
+    assert_eq!(
+        harness.settings.value_of("appearance.theme_mode"),
+        Some(json!("metro_light"))
+    );
+    assert_eq!(confirm_events(&harness), 0, "Low 键不该打扰用户");
+
+    let records = harness.audit.records_for("set_config");
+    assert_eq!(records.len(), 1);
+    assert_eq!(records[0].outcome, AuditOutcome::Ok);
+    assert!(!records[0].confirmed, "静默生效不是「用户确认」");
+    assert!(!records[0].yolo);
+}
+
+#[test]
+fn medium_key_also_writes_silently() {
+    // M12：Medium = 静默生效但审计标记（不弹窗）
+    let harness = Harness::new(vec![
+        set_config_reply("download.region", json!("cn")),
+        ChatReply::text("已切到国内源"),
+    ]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "换下载源"),
+    )
+    .unwrap();
+
+    assert_eq!(harness.settings.set_calls(), 1);
+    assert_eq!(confirm_events(&harness), 0);
+    assert_eq!(
+        harness.audit.records_for("set_config")[0].outcome,
+        AuditOutcome::Ok
+    );
+}
+
+#[test]
+fn high_key_is_fail_closed_without_ui() {
+    let harness = Harness::new(vec![
+        set_config_reply("java.selected_path", json!("D:/jdk17/bin/java.exe")),
+        ChatReply::text("需要你确认"),
+    ]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "换 Java"),
+    )
+    .unwrap();
+
+    assert_eq!(
+        harness.settings.set_calls(),
+        0,
+        "P0 无 UI 时必须 fail-closed"
+    );
+    assert_eq!(harness.settings.value_of("java.selected_path"), None);
+    assert_eq!(confirm_events(&harness), 1, "确认请求必须作为事件发出");
+
+    let outcomes: Vec<AuditOutcome> = harness
+        .audit
+        .records_for("set_config")
+        .iter()
+        .map(|r| r.outcome)
+        .collect();
+    assert_eq!(
+        outcomes,
+        vec![AuditOutcome::AwaitingConfirmation, AuditOutcome::Denied],
+        "先记「AI 想改」，再记「被拒绝」"
+    );
+    assert!(tool_results(&harness)
+        .iter()
+        .any(|content| content.contains("denied")));
+    assert!(harness
+        .events
+        .events()
+        .iter()
+        .any(|e| matches!(e, AgentEvent::ToolDenied { .. })));
+}
+
+#[test]
+fn user_approval_writes_and_marks_confirmed() {
+    let harness = Harness::with_gate(
+        vec![
+            set_config_reply("java.selected_path", json!("D:/jdk17/bin/java.exe")),
+            ChatReply::text("已更新"),
+        ],
+        ConfirmPolicy::default(),
+        |_sink| {
+            Arc::new(ScriptedGate::new(
+                [ConfirmDecision::Approved],
+                ConfirmDecision::Denied,
+            ))
+        },
+    );
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "换 Java"),
+    )
+    .unwrap();
+
+    assert_eq!(harness.settings.set_calls(), 1, "确认后只写一次");
+    let records = harness.audit.records_for("set_config");
+    let last = records.last().expect("必须有审计记录");
+    assert_eq!(last.outcome, AuditOutcome::Ok);
+    assert!(last.confirmed, "用户点了允许");
+    assert!(!last.yolo);
+}
+
+#[test]
+fn yolo_skips_confirm_but_audits_flag() {
+    let harness = Harness::yolo(vec![
+        set_config_reply("java.selected_path", json!("D:/jdk17/bin/java.exe")),
+        ChatReply::text("已更新"),
+    ]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "换 Java"),
+    )
+    .unwrap();
+
+    assert_eq!(harness.settings.set_calls(), 1);
+    assert_eq!(confirm_events(&harness), 0, "YOLO 不打扰用户");
+    let records = harness.audit.records_for("set_config");
+    assert_eq!(records.len(), 1, "YOLO 只留结局记录");
+    assert!(records[0].yolo, "审计必须标记 yolo");
+    assert!(!records[0].confirmed, "自动放行不是用户确认");
+    assert_eq!(records[0].outcome, AuditOutcome::Ok);
+}
+
+#[test]
+fn whitelist_violation_is_rejected_and_audited() {
+    let harness = Harness::new(vec![
+        set_config_reply("java.home.mystery", json!("x")),
+        ChatReply::text("换个方案"),
+    ]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "改个不存在的键"),
+    )
+    .unwrap();
+
+    assert_eq!(harness.settings.set_calls(), 0);
+    let records = harness.audit.records_for("set_config");
+    assert_eq!(records.len(), 1);
+    assert_eq!(records[0].outcome, AuditOutcome::ToolError);
+    let results = tool_results(&harness);
+    assert!(
+        results.iter().any(|c| c.contains("白名单")),
+        "模型需要知道为什么被拒：{results:?}"
+    );
+}
+
+#[test]
+fn invalid_args_are_rejected_before_any_side_effect() {
+    // 缺 value（schema required）
+    let harness = Harness::new(vec![
+        tool_call_reply(
+            "c1",
+            "set_config",
+            json!({ "path": "appearance.theme_mode" }),
+        ),
+        ChatReply::text("参数补上"),
+    ]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "改主题"),
+    )
+    .unwrap();
+
+    assert_eq!(harness.settings.set_calls(), 0);
+    let records = harness.audit.records_for("set_config");
+    assert_eq!(records[0].outcome, AuditOutcome::InvalidArgs);
+    assert!(tool_results(&harness)
+        .iter()
+        .any(|c| c.contains("缺少必填参数")));
+
+    // 多余参数（additionalProperties: false）
+    let harness = Harness::new(vec![
+        tool_call_reply(
+            "c2",
+            "read_game_log",
+            json!({ "session_id": "x", "path": "evil" }),
+        ),
+        ChatReply::text("好"),
+    ]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "读日志"),
+    )
+    .unwrap();
+    let records = harness.audit.records_for("read_game_log");
+    assert_eq!(records[0].outcome, AuditOutcome::InvalidArgs);
+}
+
+#[test]
+fn unknown_tool_lists_available_names() {
+    let harness = Harness::new(vec![
+        tool_call_reply("c1", "delete_everything", json!({})),
+        ChatReply::text("抱歉"),
+    ]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "删库跑路"),
+    )
+    .unwrap();
+
+    let records = harness.audit.records_for("delete_everything");
+    assert_eq!(records[0].outcome, AuditOutcome::UnknownTool);
+    let results = tool_results(&harness);
+    assert!(
+        results.iter().any(|c| c.contains("get_config")),
+        "{results:?}"
+    );
+}
+
+#[test]
+fn locked_credential_key_is_refused_even_under_yolo() {
+    // M12：ai.api_key 是 writable=false（不在白名单）→ YOLO 也不能放宽可写范围
+    let harness = Harness::yolo(vec![
+        set_config_reply("ai.api_key", json!("sk-super-secret-value")),
+        ChatReply::text("换不了"),
+    ]);
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "换 key"),
+    )
+    .unwrap();
+
+    assert_eq!(harness.settings.set_calls(), 0);
+    let records = harness.audit.records_for("set_config");
+    assert_eq!(records[0].outcome, AuditOutcome::ToolError);
+
+    let args = serde_json::to_string(&records[0].args).unwrap();
+    assert!(
+        !args.contains("sk-super-secret-value"),
+        "审计绝不能落明文密钥：{args}"
+    );
+    assert!(args.contains("***"), "{args}");
+}
+
+#[test]
+fn get_config_refuses_credential_keys() {
+    // F1：模型可自由给 path，凭据键必须读不到 —— 否则值会进模型上下文发往远端 LLM。
+    let harness = Harness::new(vec![
+        tool_call_reply("c1", "get_config", json!({ "path": "ai.api_key" })),
+        ChatReply::text("读不到"),
+    ]);
+    // 模拟 M12 真实实现：凭据键在文件里确实有值（writable=false，不在白名单也要能防住读）
+    harness
+        .settings
+        .seed_value("ai.api_key", json!("sk-live-credential-value"));
+    let mut history = Vec::new();
+    block_on(
+        harness
+            .brain
+            .run_turn(AGENT_SESSION, &mut history, "看看我的 key"),
+    )
+    .unwrap();
+
+    // 1) 工具报错并被审计
+    let records = harness.audit.records_for("get_config");
+    assert_eq!(records[0].outcome, AuditOutcome::ToolError);
+    // 2) 模型拿到的是拒绝文案，不是值
+    let results = tool_results(&harness);
+    assert!(
+        results.iter().any(|c| c.contains("凭据")),
+        "应给出可读拒绝：{results:?}"
+    );
+    assert!(
+        !results
+            .iter()
+            .any(|c| c.contains("sk-live-credential-value")),
+        "工具结果绝不能带凭据：{results:?}"
+    );
+    // 3) 事件流与对话历史里也不能出现（P1 事件会落盘 / 历史会持久化）
+    let leaked_in_events = harness
+        .events
+        .events()
+        .iter()
+        .any(|e| format!("{e:?}").contains("sk-live-credential-value"));
+    assert!(!leaked_in_events, "事件流不能带凭据明文");
+    let leaked_in_history = history
+        .iter()
+        .any(|m| format!("{m:?}").contains("sk-live-credential-value"));
+    assert!(!leaked_in_history, "对话历史不能带凭据明文");
+}

crates/app-iced/Cargo.toml

@@ -0,0 +1,108 @@
+[package]
+name = "unlucky-app-iced"
+description = "Unlucky-Launcher 桌面壳（iced 0.14 重写版）：M3 Expressive 骨架 / 令牌适配 / 截图通道"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 并存期（D26）：Slint 版仍是 `crates/app` 的 `unlucky-launcher`，本 crate 出
+# `unlucky-launcher-iced`。两个 package 在同一 target 目录产出同名 bin 会冲突，
+# 所以**翻牌前不许改回 `unlucky-launcher`**（步骤见 SubAgentsTalk/app-iced-骨架与翻牌.md）。
+[[bin]]
+name = "unlucky-launcher-iced"
+path = "src/main.rs"
+
+[lib]
+name = "unlucky_app_iced"
+path = "src/lib.rs"
+
+[dependencies]
+# 令牌唯一真源（M61）：颜色/排版/形状/间距/图标几何全部只从这里取。
+unlucky-design = { path = "../design", version = "0.2.4" }
+
+# 平台识别（Termux / $PREFIX 路径）唯一真源：字体注册这类平台适配不再各写一份环境判断。
+unlucky-core = { path = "../core", version = "0.2.4" }
+
+# M85：UI 框架无关的宿主层（DTO / 状态 reducer / host）。**只登记依赖，本 mission 不接线**——
+# 页面用它的时机由后续 iced 页面 mission 决定（接线流程见 crates/presenter/src/lib.rs 的 crate 文档）。
+# 与 Slint 版共用同一套 host 与状态语义，这是 D26「重写只换渲染」的落点。
+unlucky-presenter = { path = "../presenter", version = "0.2.4" }
+
+# UI 框架（D26 锁定 iced 0.14）。**不得依赖 slint**。
+# 关掉默认 features 后必须显式给执行器（M60 踩坑 Q2：否则 `No futures executor has been enabled`），
+# 这里给 `thread-pool`（iced 自己的默认执行器，不额外引 tokio 运行时）。
+# `wgpu` 由本 crate 的 `gpu` feature 打开，于是「仅 CPU」体积基线用 `--no-default-features` 就能量到。
+iced = { version = "=0.14.0", default-features = false, features = [
+    "tiny-skia",
+    "crisp",
+    "advanced",
+    # M93：背景图要真图直出 ⇒ 需要渲染器的 image 支持。用 `image-without-codecs` 而不是
+    # `image` 是刻意的：后者会打开 `image/default` 的全套编解码器；前者的编解码能力由本 crate
+    # 依赖表里那条 `image` 的 features 决定（png / jpeg / bmp），不必把 webp/tiff/exr/gif 拖进来。
+    "image-without-codecs",
+    "svg",
+    "thread-pool",
+] }
+
+# 截图落 PNG + 背景图解码（M93）：png 是截图通道，jpeg/bmp 是用户真会挑的背景图/壁纸格式
+# （M73 的壁纸探测不筛扩展名）。仍不开 default-features——那会拖进 avif/ravif/webp/tiff 一整套。
+image = { version = "0.25", default-features = false, features = [
+    "png",
+    "jpeg",
+    "bmp",
+] }
+
+# M82：同一个二进制也带 CLI 子命令（`unlucky-launcher-iced instances list` …），
+# 进 UI 之前分发，命中就把控制权交给 `unlucky_cli::run`。依赖方向 app-iced → cli →
+# core/agent 不违反 core 零 UI 铁律（core 的依赖树里没有 cli）。零 UI 依赖的 `ull`
+# 仍在 `crates/cli`，给没有图形库的机器用——两者不是重复品。
+unlucky-cli = { path = "../cli", version = "0.2.4" }
+
+# M92（D28）：国际化地基（语言探测 / 消息目录 / 中文字体策略）。零依赖 crate——它拿不到 iced，
+# 所以系统字体扫描留在这里（`src/fonts/cjk.rs`），本 crate 只把族名喂给它的纯函数。
+unlucky-i18n = { path = "../i18n", version = "0.2.4" }
+
+# M97：判据表第 8 行的取证通道。`iced_wgpu` 在真创建设备时会 `log::info!("Selected: {adapter:#?}")`，
+# 但进程里从来没人装 logger，于是「看不见」被当成了「没发生」。这里装一个只放行 `iced_wgpu*` /
+# `wgpu*` 的 logger（见 `src/renderer/log_bridge.rs`），把这行捞出来。
+# 已是 iced 传递依赖树里的版本（0.4.34），不新增任何传递依赖；MIT OR Apache-2.0，许可白名单内。
+log = { version = "0.4", features = ["std"] }
+
+# X11 / Wayland 后端与 Linux 主题检测只在 Linux 上启用：macOS 没有 X11/Wayland（走 Metal +
+# 系统外观），Windows 走 DX12，这三个 feature 在那边没有意义。同一个包在两处写 features 是
+# **取并集**（Cargo 的 feature 解析是加法），所以 Linux 上拿到的仍是上面 5 个 + 这 3 个，
+# Windows / macOS 只拿上面那 5 个（`cargo tree --target` 可复核）。
+# 诚实边界：这**不**解决「iced 版至今没在 macOS 上编过」这件事——`iced_winit` 已把 `mundy`
+# 放在 `cfg(target_os = "linux")` 段里，这三个 feature 在非 Linux 上本来就不拉依赖，这里只是
+# 让本仓库的依赖图按平台自述清楚，不再把 Linux 专属能力写成全平台事实。
+[target.'cfg(target_os = "linux")'.dependencies]
+iced = { version = "=0.14.0", default-features = false, features = [
+    "x11",
+    "wayland",
+    "linux-theme-detection",
+] }
+
+[features]
+default = ["gpu"]
+# 硬件渲染后端（wgpu→Vulkan/DX12）。关闭后只剩 tiny-skia（CPU），用于体积基线与无 GPU 机器。
+gpu = ["iced/wgpu"]
+# M169：把「本地更新源」这条测试通道编进 GUI（默认关）。人工验收更新链路时的构建方式：
+#   ULL_UPDATE_DIR=<root> ULL_UPDATE_TEST_SOURCE=1 \
+#     cargo run -p unlucky-app-iced --features update-test-source
+# ⚠ `-p` 只认 **package** 名（`unlucky-app-iced`），`unlucky-launcher-iced` 是它在 [[bin]] 里
+# 声明的 bin 名——写成 `-p unlucky-launcher-iced` 会 `package(s) … not found`（r1 复审 P2-1）。
+# 转发给 presenter 与内嵌的 cli（两者都依赖 core，feature 取并集）；官方发布构建不带它。
+update-test-source = ["unlucky-presenter/update-test-source", "unlucky-cli/update-test-source"]
+
+[lints]
+workspace = true
+
+# M190：把版本资源写进 PE（Windows「属性 → 详细信息」里的发布者/产品/版权/版本）。
+# 只在 windows 目标上真跑（`build.rs` 先看 CARGO_CFG_TARGET_OS，其它平台直接返回），
+# 共享口径在 `packaging/pe_version.rs`（两个 bin 各 include 一次，署名不会漂）。
+[build-dependencies]
+winresource = "0.1"

crates/app-iced/build.rs

@@ -0,0 +1,14 @@
+//! `unlucky-launcher-iced` 的 PE 版本资源（M190）。
+//!
+//! 与 `crates/cli/build.rs` 同一份共享口径（`packaging/pe_version.rs`）：两个产物的
+//! CompanyName / ProductName / LegalCopyright / 版本号必须逐字相同。
+//!
+//! ⚠ 本文件**只**写版本资源，不碰子系统：PE 的 `Subsystem` 由 rustc 的
+//! `windows_subsystem` 属性决定（本分支上还没有那个属性，是 M196 的事），版本资源与子系统是两件事。
+//! 判据：`packaging/check_pe_version.py` 会把它读到的 `subsystem` 打出来，加资源前后必须一致。
+
+include!("../../packaging/pe_version.rs");
+
+fn main() {
+    emit_pe_version_resource("unlucky-launcher-iced");
+}

crates/app-iced/examples/pages_demo.rs

@@ -0,0 +1,37 @@
+//! 页面骨架截图入口（M84 `PAGEFRAME` 的验收通道）。
+//!
+//! ```text
+//! cargo run -p unlucky-app-iced --example pages_demo -- \
+//!   --screen=instances --width=1180 --height=760 \
+//!   --screenshot=out.png --screenshot-theme=light --software-renderer
+//! ```
+//!
+//! 参数解析与 iced 接线都在 `unlucky_app_iced::pages::harness` 里：**本 example 只是入口**，
+//! 它也刻意不接 `cli.rs`（那边归 M75）。详细口径见 `pages::harness` 的模块文档。
+
+use std::process::ExitCode;
+
+use unlucky_app_iced::pages::harness::{self, Request};
+
+fn main() -> ExitCode {
+    let request = match Request::parse(std::env::args().skip(1)) {
+        Ok(request) => request,
+        Err(message) => {
+            eprintln!("[cli] {message}");
+            eprintln!(
+                "用法：pages_demo [--screen=instances|download|settings|logs] [--width <px>] \
+                 [--height <px>] [--theme=light|dark] [--screenshot-theme=light|dark] \
+                 [--screenshot <png>] [--renderer=auto|gpu|cpu] [--software-renderer]"
+            );
+            return ExitCode::from(2);
+        }
+    };
+
+    match harness::run(request) {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(message) => {
+            eprintln!("[run] {message}");
+            ExitCode::FAILURE
+        }
+    }
+}

crates/app-iced/src/app/adopt.rs

@@ -0,0 +1,261 @@
+//! 「导入已有版本」向导（M223 GUIADOPT）：实例页页头的入口 + 一张盖在页面上的向导卡。
+//!
+//! ## 四段（与 presenter 的 `AdoptState` 一一对应）
+//!
+//! | 段 | 画什么 | 从哪来 | 文件 |
+//! |---|---|---|---|
+//! | Pick | 候选版本 + 目标档 + 实例名 | `AdoptEvent::Scan` | [`pick`] |
+//! | Preview | 落点 / 隔离档 / **`target_notes()` 原文** | `AdoptEvent::Planned` | [`panes`] |
+//! | Failed | 稳定码 + 人读原因 + **`problems[]` 逐条** | `AdoptEvent::Failed` | [`panes`] |
+//! | Done | 实例名 / 运行目录 / 提示原文 | `AdoptEvent::Done` | [`panes`] |
+//!
+//! 「现在画哪一段」的判据只有一处：presenter 的 `AdoptState::stage`，外面套一条收窄
+//! [`Form::stage`]——`Preview` 只在用户**点过预检**（`Form::checked`）之后才算数。收窄的理由：
+//! 共享档 / 版本目录档一被点选就要显示后果原文（§5.2），那要用一次**零写盘**的预检换；
+//! 但那次结果不该把用户直接甩到确认页（实例名还没填完）。
+//!
+//! 卡壳与页脚在 [`shell`]（定高可滚 / 收高两种几何），三段视图在 [`pick`] 与 [`panes`]，
+//! 等宽与正文小工具在 `text`，D30 出图种子在 `shot`（`ULL_ADOPT_STATE`，只在 `--screenshot` 下生效）。
+//!
+//! ## 三条纪律（契约 §5 的 1/2/3）
+//!
+//! 1. **运行目录不派生**：Preview / Done 上那个路径**原样**来自回程事件（缺省档可能带 `-2` 后缀，
+//!    只有 core 知道最后用了哪个）。本模块没有任何「拼一个目录名」的代码。
+//! 2. **后果话术不重写**：共享档 / 版本目录档的后果句在 Preview 段**逐条**画 `plan.notes`
+//!    （core `target_notes()` 的原文）。Pick 段只放一句短提示（选之前就得知道会碰别人的目录），
+//!    真正的后果原文在确认按钮之前一定会出现。
+//! 3. **不折叠问题**：Failed 段把 `problems` 一条一行画出来，标题只说「导入失败」，原因全在下面。
+//!
+//! ## 为什么是「盖一层」而不是实例页里的一段
+//!
+//! 向导有四段状态、每段内容都不一样，塞进 list-detail 的正文列会把版式判据（424 散文宽、
+//! 列表独立滚动）搅乱。盖一层与 M187 的模态同一手法（遮罩 + 居中卡），但**不是**
+//! `DialogQueue` 那种「标题 + 正文 + 两个按钮」的窄形态：向导要画候选列表、单选档位与输入框。
+//!
+//! ## 表单字段归 `App`，事件真相归 presenter
+//!
+//! [`Form`] 只装「用户正在填的东西」（选中哪个版本、展示名、目标档、有没有在等回程）；
+//! 候选、预检、失败、完成全部来自 `AppState.adopt`（presenter 的 `AdoptState`）。两边各管一半，
+//! 于是「画出来的落点」与「真正写盘的落点」永远是同一份事实。
+
+mod panes;
+mod pick;
+mod shell;
+/// D30 出图用的状态夹具（只在 `--screenshot` 下按环境变量生效）。
+pub(crate) mod shot;
+mod text;
+
+#[cfg(test)]
+mod tests;
+
+use iced::widget::{container, mouse_area, opaque, Space};
+use iced::{Alignment, Background, Element, Length};
+
+use unlucky_design::spacing::Space as Sp;
+use unlucky_i18n::{Catalog, Lang};
+use unlucky_presenter::dto::{
+    AdoptCandidateView, AdoptPlanView, AdoptStage, AdoptState, AdoptTargetView,
+};
+
+use crate::app::components::feedback::dialog::scrim;
+use crate::theme::Ui;
+
+use super::message::Message;
+
+/// 向导卡宽度：比模态卡（560）宽一档——候选行要放「版本 id + 状态」，目标档是三枚 chip。
+const CARD_WIDTH: f32 = 640.0;
+
+/// 卡片的最大高（窗口更矮时整卡按窗口走：内容在中间区滚）。
+const CARD_MAX_HEIGHT: f32 = 620.0;
+
+/// 正在等哪一条命令的回程。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Busy {
+    /// 空闲（可以点）
+    #[default]
+    Idle,
+    /// 正在扫描 `versions/`
+    Scanning,
+    /// 正在预检（零写盘）
+    Checking,
+    /// 正在真正登记
+    Importing,
+}
+
+impl Busy {
+    /// 有没有在等回程。
+    #[must_use]
+    pub const fn waiting(self) -> bool {
+        !matches!(self, Self::Idle)
+    }
+}
+
+/// 向导的表单态（**归 `App`**，页面借一帧）。
+#[derive(Debug, Default)]
+pub struct Form {
+    /// 面板开着吗
+    pub open: bool,
+    /// 选中的版本 id（`None` = 还没选）
+    pub selected: Option<String>,
+    /// 展示名（空 = 用版本 id）
+    pub name: String,
+    /// 运行目录档（缺省 [`AdoptTargetView::InstanceDir`]，**不是** isolated）
+    pub target: AdoptTargetView,
+    /// 在等在飞的那一条命令
+    pub busy: Busy,
+    /// 用户已经点过「预检」（没点过就留在 Pick 段，哪怕后台已经顺手算过一次落点）。
+    ///
+    /// 为什么要有这一位：共享档 / 版本目录档一旦被点选，界面就要立刻显示 `target_notes()` 的
+    /// **后果原文**（契约 §5.2）——那是 core 唯一会产出这段文字的地方，所以点选时顺手发一次
+    /// **零写盘**的预检。但那一次结果不该把用户甩到「可以导入」的确认页：确认必须由显式的
+    /// `Check` 触发。于是 `checked` 记住「这次预检是不是用户要的」。
+    pub checked: bool,
+}
+
+impl Form {
+    /// 打开面板（回到 Pick 段、清掉上一轮的选中与名字）。
+    pub fn open(&mut self) {
+        *self = Self {
+            open: true,
+            busy: Busy::Scanning,
+            ..Self::default()
+        };
+    }
+
+    /// 关掉面板（全清）。
+    pub fn close(&mut self) {
+        *self = Self::default();
+    }
+
+    /// 回程到了：不在等任何东西了。
+    pub fn settled(&mut self) {
+        self.busy = Busy::Idle;
+    }
+
+    /// 当前该画哪一段：`Preview` 只在用户**点过预检**之后才算数，其余按 `AdoptState::stage()`。
+    ///
+    /// 这条收窄是为了「点选共享档 ⇒ 立刻看到后果原文」而不把用户直接甩到确认页：
+    /// 自动预检的结果落在 Pick 段里当**提示**读，用户点「预检」之后才进确认段。
+    #[must_use]
+    pub fn stage(&self, adopt_state: &AdoptState) -> AdoptStage {
+        match adopt_state.stage() {
+            AdoptStage::Preview if !self.checked => AdoptStage::Pick,
+            other => other,
+        }
+    }
+
+    /// 后台算出来、且**对得上当前选择**的预检（对不上 = 过期的结果，一律不画）。
+    ///
+    /// 两个判据缺一不可：
+    /// - **目标档一致**：改了档之后旧 plan 的 `notes` 说的是别的目录；
+    /// - **版本 id 一致**：换了版本之后旧 plan 的 `notes` 说的是别的版本目录
+    ///   （版本目录档的后果原文里带 `versions/<id>`，拿它当新版本的后果就是撒谎）。
+    ///
+    /// 没有选中版本时也返回 `None`：那一刻没有任何版本可言，画谁的预检都不成立。
+    /// 这两条都不是「选中即重扫」带来的——`Select` 只改本地字段、不发命令（落点见
+    /// `app/update/adopt.rs`），所以过期判定只能在这里做。
+    #[must_use]
+    pub fn fresh_plan<'a>(&self, adopt_state: &'a AdoptState) -> Option<&'a AdoptPlanView> {
+        let selected = self.selected.as_deref()?;
+        adopt_state
+            .plan
+            .as_ref()
+            .filter(|plan| plan.target == self.target && plan.version_id == selected)
+    }
+
+    /// 当前选中的候选（选中项已不在列表里时返回 `None`，界面自动退回「请选择」）。
+    #[must_use]
+    pub fn candidate<'a>(&self, adopt_state: &'a AdoptState) -> Option<&'a AdoptCandidateView> {
+        let id = self.selected.as_deref()?;
+        adopt_state
+            .scan
+            .as_ref()?
+            .candidates
+            .iter()
+            .find(|candidate| candidate.version_id == id)
+    }
+}
+
+/// 向导消息（`crate::app::Message::Adopt` 的载荷）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AdoptMessage {
+    /// 打开向导（实例页页头「导入」）
+    Open,
+    /// 关掉（点遮罩 / 关闭按钮）
+    Close,
+    /// 选中一个候选版本
+    Select(String),
+    /// 改展示名
+    Name(String),
+    /// 改运行目录档
+    Target(AdoptTargetView),
+    /// 预检（零写盘）
+    Check,
+    /// 确认登记（唯一写盘入口）
+    Confirm,
+    /// 从 Preview / Failed 退回候选列表（等价于重新扫一次）
+    Back,
+}
+
+/// 向导消息 → app 消息。
+fn adopt(message: AdoptMessage) -> Message {
+    Message::Adopt(message)
+}
+
+// --------------------------------------------------------------- 视图
+
+/// 把向导叠在页面之上（没打开时原样返回页面树）。
+pub(super) fn layer<'a>(
+    ui: &'a Ui,
+    base: Element<'a, Message>,
+    form: &'a Form,
+    adopt_state: &'a AdoptState,
+    lang: Lang,
+) -> Element<'a, Message> {
+    if !form.open {
+        return base;
+    }
+    let catalog = lang.catalog();
+    let backdrop = mouse_area(
+        container(Space::new())
+            .width(Length::Fill)
+            .height(Length::Fill)
+            .style(move |_theme| container::Style {
+                background: Some(Background::Color(scrim(ui))),
+                ..container::Style::default()
+            }),
+    )
+    .on_press(adopt(AdoptMessage::Close));
+
+    // 透明的一层只负责居中；吃点击的 `opaque` 只包卡片（点卡内不关，点遮罩才关）。
+    let centered = container(opaque(shell::card(ui, form, adopt_state, catalog)))
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .padding(ui.space(Sp::X6));
+
+    iced::widget::stack![base, backdrop, centered].into()
+}
+
+/// 中间区（按段交给 `pick` / `panes`）。
+pub(super) fn middle<'a>(
+    ui: &'a Ui,
+    form: &'a Form,
+    adopt_state: &'a AdoptState,
+    stage: AdoptStage,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    match stage {
+        AdoptStage::Pick => pick::pick(
+            ui,
+            form,
+            adopt_state.scan.as_ref(),
+            form.fresh_plan(adopt_state),
+            catalog,
+        ),
+        AdoptStage::Preview => panes::preview(ui, form.fresh_plan(adopt_state), catalog),
+        AdoptStage::Failed => panes::failed(ui, adopt_state.failure.as_ref(), catalog),
+        AdoptStage::Done => panes::done(ui, adopt_state.done.as_ref(), catalog),
+    }
+}

crates/app-iced/src/app/adopt/panes.rs

@@ -0,0 +1,127 @@
+//! Preview / Failed / Done 三段。
+//!
+//! | 段 | 画什么 | 判据 |
+//! |---|---|---|
+//! | Preview | 生效运行目录（**回程给的**）+ 隔离档 + `notes` 原文逐条 | `AdoptEvent::Planned` |
+//! | Failed | 稳定码 + `problems[]` 逐条 | `AdoptEvent::Failed` |
+//! | Done | 实例名 + 运行目录 + `notes` 原文逐条 | `AdoptEvent::Done` |
+//!
+//! 三段都不自己算路径、不自己写后果句：`run_dir` 与 `notes` 是 core 的返回值原样。
+//! 缺省档会带 `-2`/`-3` 后缀（两个不同展示名可能落到同一个物理目录），**只有 core 知道**
+//! 最后用了哪个——页面对它再做一次派生就会与真正启动时用的目录分叉。
+
+use iced::widget::column;
+use iced::{Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::spacing::Space as Sp;
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{AdoptDoneView, AdoptFailureView, AdoptPlanView};
+
+use crate::theme::Ui;
+
+use super::super::message::Message;
+use super::text::{field_line, isolation_label, mono, problem_line, wrapped};
+
+/// 预检结果：落点 + 隔离档 + 后果原文。
+pub(super) fn preview<'a>(
+    ui: &'a Ui,
+    plan: Option<&'a AdoptPlanView>,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    let Some(plan) = plan else {
+        return wrapped(
+            ui,
+            catalog.text(Key::AdoptScanning).to_string(),
+            ui.color(Role::OnSurfaceVariant),
+        );
+    };
+    let mut body = column![
+        field_line(ui, catalog.text(Key::AdoptInstanceName), &plan.name),
+        field_line(
+            ui,
+            catalog.text(Key::AdoptPlanRunDir),
+            &plan.run_dir.display().to_string()
+        ),
+        field_line(
+            ui,
+            catalog.text(Key::AdoptPlanIsolation),
+            &isolation_label(plan.isolation, catalog),
+        ),
+    ]
+    .spacing(ui.space(Sp::X2))
+    .width(Length::Fill);
+
+    // 后果话术：core `target_notes()` 的原文，一条一行、一个字不改
+    for note in &plan.notes {
+        body = body.push(wrapped(ui, note.clone(), ui.color(Role::OnSurfaceVariant)));
+    }
+    body.into()
+}
+
+/// 失败：稳定码 + **problems 逐条**。
+pub(super) fn failed<'a>(
+    ui: &'a Ui,
+    failure: Option<&'a AdoptFailureView>,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    let Some(failure) = failure else {
+        return wrapped(
+            ui,
+            catalog.text(Key::AdoptScanning).to_string(),
+            ui.color(Role::OnSurfaceVariant),
+        );
+    };
+    let mut body = column![mono(ui, failure.code.clone())]
+        .spacing(ui.space(Sp::X2))
+        .width(Length::Fill);
+
+    if failure.problems.is_empty() {
+        body = body.push(wrapped(
+            ui,
+            failure.message.clone(),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+        return body.into();
+    }
+    body = body.push(wrapped(
+        ui,
+        catalog.text(Key::AdoptProblemCount).to_string(),
+        ui.color(Role::OnSurfaceVariant),
+    ));
+    for problem in &failure.problems {
+        body = body.push(problem_line(ui, problem));
+    }
+    body.into()
+}
+
+/// 完成：实例名 + 运行目录 + 提示原文。
+pub(super) fn done<'a>(
+    ui: &'a Ui,
+    done: Option<&'a AdoptDoneView>,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    let Some(done) = done else {
+        return wrapped(ui, String::new(), ui.color(Role::OnSurfaceVariant));
+    };
+    let mut body = column![
+        field_line(ui, catalog.text(Key::AdoptInstanceName), &done.name),
+        field_line(
+            ui,
+            catalog.text(Key::AdoptPlanRunDir),
+            &done.run_dir.display().to_string()
+        ),
+        field_line(
+            ui,
+            catalog.text(Key::AdoptPlanIsolation),
+            &isolation_label(done.isolation, catalog),
+        ),
+    ]
+    .spacing(ui.space(Sp::X2))
+    .width(Length::Fill);
+
+    for note in &done.notes {
+        body = body.push(wrapped(ui, note.clone(), ui.color(Role::OnSurfaceVariant)));
+    }
+    body.into()
+}

crates/app-iced/src/app/adopt/pick.rs

@@ -0,0 +1,228 @@
+//! Pick 段：候选列表 + 目标档 + 实例名。
+//!
+//! **可导入的候选才可点**：不可导入的行把 `problems` 逐条列在下面但不接点击——点它只会换来
+//! 一条注定被 core 拒绝的命令（`adopt_not_adoptable`），而用户从行上已经看到了原因。
+//!
+//! 目标档三枚 chip 的**短提示**在选中时立刻换（共享/版本目录档用 `Error` 色）；
+//! **后果原文**不在这里——它在 Preview 段逐条画 `plan.notes`（core `target_notes()` 的原文）。
+
+use iced::widget::{button, column, container, row};
+use iced::{Alignment, Background, Border, Color, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space as Sp;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{AdoptCandidateView, AdoptPlanView, AdoptScanView, AdoptTargetView};
+
+use crate::app::components::inputs::{text_field, Field};
+use crate::app::components::selection::{chip, Chip};
+use crate::pages::frame;
+use crate::theme::Ui;
+
+use super::super::message::Message;
+use super::text::{label, problem_line, target_label, wrapped};
+use super::{adopt, AdoptMessage, Form};
+
+/// Pick 段整体。
+pub(super) fn pick<'a>(
+    ui: &'a Ui,
+    form: &'a Form,
+    scan: Option<&'a AdoptScanView>,
+    plan: Option<&'a AdoptPlanView>,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    let Some(scan) = scan else {
+        // 扫描还没回来：一行进度文案（不做假进度条）
+        return wrapped(
+            ui,
+            catalog.text(Key::AdoptScanning).to_string(),
+            ui.color(Role::OnSurfaceVariant),
+        );
+    };
+
+    let mut body = column![].spacing(ui.space(Sp::X3)).width(Length::Fill);
+    if scan.is_empty() {
+        let dir = scan.versions_dir.display().to_string();
+        body = body.push(wrapped(
+            ui,
+            catalog.render(Key::AdoptEmpty, &[("dir", &dir)]),
+            ui.color(Role::OnSurfaceVariant),
+        ));
+    } else {
+        body = body.push(label(ui, catalog.text(Key::AdoptSelectLabel)));
+        body = body.push(candidate_list(ui, form, scan, catalog));
+    }
+
+    body = body.push(frame::divider(ui).map(Message::Page));
+    body = body.push(label(ui, catalog.text(Key::AdoptTargetLabel)));
+    body = body.push(target_row(ui, form, catalog));
+    // 后果原文（契约 §5.2）：共享档 / 版本目录档一被点选就显示 core `target_notes()` 的原文——
+    // 这一条来自**零写盘**的自动预检（见 `AdoptMessage::Target` 的落点），不是界面另写的一句。
+    if let Some(plan) = plan {
+        for note in &plan.notes {
+            body = body.push(wrapped(ui, note.clone(), ui.color(Role::OnSurfaceVariant)));
+        }
+    }
+    body = body.push(text_field(
+        ui,
+        Field::new(form.name.as_str()).label(catalog.text(Key::AdoptNameLabel)),
+        |value| adopt(AdoptMessage::Name(value)),
+    ));
+    body.into()
+}
+
+/// 候选列表（可滚，定高：列表再长页脚按钮也留在卡里）。
+fn candidate_list<'a>(
+    ui: &'a Ui,
+    form: &'a Form,
+    scan: &'a AdoptScanView,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    let rows = column(
+        scan.candidates
+            .iter()
+            .map(|candidate| candidate_row(ui, form, candidate, catalog))
+            .collect::<Vec<_>>(),
+    )
+    .spacing(ui.space(Sp::X1))
+    .width(Length::Fill);
+
+    rows.into()
+}
+
+/// 一条候选。
+fn candidate_row<'a>(
+    ui: &'a Ui,
+    form: &'a Form,
+    candidate: &'a AdoptCandidateView,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    let selected = form.selected.as_deref() == Some(candidate.version_id.as_str());
+
+    let mut items = column![row![
+        frame::text_role(
+            ui,
+            TypeRole::BodyLarge,
+            selected,
+            candidate.version_id.as_str(),
+            ui.color(Role::OnSurface),
+        )
+        .map(Message::Page),
+        container(status(ui, candidate, selected, catalog))
+            .width(Length::Fill)
+            .align_x(Alignment::End),
+    ]
+    .width(Length::Fill)
+    .align_y(Alignment::Center)]
+    .spacing(ui.space(Sp::X1))
+    .width(Length::Fill);
+
+    // 问题逐条（不折叠）：候选阶段就把「为什么不能导入」说清楚
+    for problem in &candidate.problems {
+        items = items.push(problem_line(ui, problem));
+    }
+
+    let body = container(items)
+        .width(Length::Fill)
+        .padding(ui.space(Sp::X2))
+        .style(move |_theme| container::Style {
+            background: selected.then(|| Background::Color(ui.color(Role::SecondaryContainer))),
+            border: Border {
+                radius: ui.radius_dp(ShapeScale::Medium),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        });
+
+    if !candidate.adoptable() {
+        // 不可导入的行**不可点**（也就不存在「点了才被告知不行」这条路）
+        return body.into();
+    }
+    button(body)
+        .width(Length::Fill)
+        .padding(0)
+        .style(|_theme, _status| button::Style {
+            background: None,
+            text_color: Color::TRANSPARENT,
+            border: Border::default(),
+            shadow: iced::Shadow::default(),
+            snap: true,
+        })
+        .on_press(adopt(AdoptMessage::Select(candidate.version_id.clone())))
+        .into()
+}
+
+/// 候选右侧那枚状态（可导入 / N 个问题 / 已被某实例使用）。
+fn status<'a>(
+    ui: &'a Ui,
+    candidate: &AdoptCandidateView,
+    selected: bool,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    if !candidate.adoptable() {
+        let count = candidate.problems.len().to_string();
+        return wrapped(
+            ui,
+            catalog.render(Key::AdoptBlocked, &[("count", &count)]),
+            ui.color(Role::Error),
+        );
+    }
+    if let Some(name) = candidate.registered.first() {
+        return wrapped(
+            ui,
+            catalog.render(Key::AdoptRegistered, &[("name", name)]),
+            ui.color(Role::OnSurfaceVariant),
+        );
+    }
+    if selected {
+        return chip(ui, Chip::current(catalog.text(Key::AdoptReady)));
+    }
+    wrapped(
+        ui,
+        catalog.text(Key::AdoptReady).to_string(),
+        ui.color(Role::OnSurfaceVariant),
+    )
+}
+
+/// 三枚目标 chip（缺省档在最前；共享 / 版本目录档必须**明确点选**）。
+fn target_row<'a>(ui: &'a Ui, form: &'a Form, catalog: Catalog) -> Element<'a, Message> {
+    let chips = AdoptTargetView::ALL
+        .into_iter()
+        .map(|target| {
+            chip(
+                ui,
+                Chip::filter(
+                    target_label(target, catalog),
+                    form.target == target,
+                    adopt(AdoptMessage::Target(target)),
+                ),
+            )
+        })
+        .collect::<Vec<_>>();
+
+    column![
+        row(chips).spacing(ui.space(Sp::X2)).width(Length::Fill),
+        target_hint(ui, form.target, catalog),
+    ]
+    .spacing(ui.space(Sp::X1))
+    .width(Length::Fill)
+    .into()
+}
+
+/// 目标档的一句话说明（点选后立刻换）。**不是后果原文**：原文在 Preview 段逐条画
+/// `plan.notes`（core `target_notes()`）。
+fn target_hint<'a>(ui: &'a Ui, target: AdoptTargetView, catalog: Catalog) -> Element<'a, Message> {
+    let key = match target {
+        AdoptTargetView::InstanceDir => Key::AdoptTargetInstanceDirHint,
+        AdoptTargetView::Shared => Key::AdoptTargetSharedHint,
+        AdoptTargetView::VersionDir => Key::AdoptTargetVersionDirHint,
+    };
+    let color = if target.touches_foreign_dir() {
+        ui.color(Role::Error)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+    wrapped(ui, catalog.text(key).to_string(), color)
+}

crates/app-iced/src/app/adopt/shell.rs

@@ -0,0 +1,198 @@
+//! 向导卡的外壳与页脚（M223 从 `app/adopt.rs` 搬出，守 400 行硬线）。
+//!
+//! | 函数 | 职责 |
+//! |---|---|
+//! | [`card`] | 卡壳（标题 + 说明 + 中间区 + 页脚）、定高/收高两种几何、遮罩上的那一张卡 |
+//! | [`title_text`] / [`subtitle`] | 四段的标题与一句说明（文案全部来自 i18n 目录） |
+//! | [`footer`] | 按段给按钮组合；在等回程时主按钮禁用 |
+//!
+//! ## 这个文件不是「纯搬移」
+//!
+//! 它**起于**一次搬移：`app/adopt.rs` 落笔 412 行越过 `components::gate` 的 400 行硬线，
+//! 于是把卡壳 / 标题 / 页脚搬到这里。但**同一个提交里**这三块还改过行为与几何，逐条如下
+//! （复审对 diff 时按这几条看，别按「一行未改」看）：
+//!
+//! | 改了什么 | 为什么 |
+//! |---|---|
+//! | `card` 拆成「定高 + 中间区可滚」（Pick / Failed）与「按内容收高」（Preview / Done）两种几何 | 原来只给 `max_height`，内容一高就被裁：页脚按钮与实例名整排不可见（出图时抓到） |
+//! | `footer` 的「关闭」只在 Pick / Preview 出现 | Failed / Done 的主按钮就是关闭，再给一枚文字关闭就是两枚一模一样的按钮 |
+//! | `subtitle` 的 Preview 文案改成「版本名 · 目标档」 | 原来打「隔离档 · 目标档」，同屏两个「共用目录」 |
+//!
+//! 调用方仍是 `app/adopt.rs` 的 `layer` 与 `middle`。
+
+use iced::widget::{column, container, row, scrollable, Space};
+use iced::{Background, Element, Length};
+
+use unlucky_design::color::Role;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::Space as Sp;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{AdoptStage, AdoptState};
+
+use crate::app::components::buttons::{self, Button};
+use crate::pages::frame;
+use crate::theme::Ui;
+
+use super::super::message::Message;
+use super::text::{target_label, wrapped};
+use super::{adopt, middle, AdoptMessage, Form, CARD_MAX_HEIGHT, CARD_WIDTH};
+
+/// 卡片本体：标题 + 一句说明 + 中间（按段） + 页脚按钮。
+pub(super) fn card<'a>(
+    ui: &'a Ui,
+    form: &'a Form,
+    adopt_state: &'a AdoptState,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    let stage = form.stage(adopt_state);
+    let middle = middle(ui, form, adopt_state, stage, catalog);
+    let head = column![
+        frame::text_role(
+            ui,
+            TypeRole::HeadlineSmall,
+            true,
+            title_text(stage, catalog),
+            ui.color(Role::OnSurface),
+        )
+        .map(Message::Page),
+        wrapped(
+            ui,
+            subtitle(stage, adopt_state, catalog),
+            ui.color(Role::OnSurfaceVariant)
+        ),
+        frame::divider(ui).map(Message::Page),
+    ]
+    .spacing(ui.space(Sp::X3))
+    .width(Length::Fill);
+
+    let tail = column![
+        frame::divider(ui).map(Message::Page),
+        footer(ui, form, adopt_state, stage, catalog),
+    ]
+    .spacing(ui.space(Sp::X3))
+    .width(Length::Fill);
+
+    // 列表段（Pick / Failed）**定高 + 中间区可滚**：内容再长，页脚按钮也不会被裁掉
+    // （第一版就是被裁掉的）。短内容段（Preview / Done）按内容高收，不留一大片空白。
+    let list_stage = matches!(stage, AdoptStage::Pick | AdoptStage::Failed);
+    let card = if list_stage {
+        let body = column![
+            head,
+            scrollable(middle)
+                .height(Length::Fill)
+                .style(frame::scroll_style(ui)),
+            tail,
+        ]
+        .spacing(ui.space(Sp::X3))
+        .width(Length::Fill);
+        container(body)
+            .width(Length::Fixed(CARD_WIDTH))
+            .height(Length::Fixed(CARD_MAX_HEIGHT))
+    } else {
+        let body = column![head, middle, tail]
+            .spacing(ui.space(Sp::X3))
+            .width(Length::Fill);
+        container(body)
+            .width(Length::Fixed(CARD_WIDTH))
+            .max_height(CARD_MAX_HEIGHT)
+    };
+
+    card.padding(ui.space(Sp::X6))
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.layer(MaterialLayer::Overlay))),
+            border: ui.outlined(ShapeScale::ExtraLarge),
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 段标题（四段各一句）。
+pub(super) fn title_text(stage: AdoptStage, catalog: Catalog) -> &'static str {
+    match stage {
+        AdoptStage::Pick => catalog.text(Key::AdoptTitle),
+        AdoptStage::Preview => catalog.text(Key::AdoptPlanTitle),
+        AdoptStage::Failed => catalog.text(Key::AdoptFailureTitle),
+        AdoptStage::Done => catalog.text(Key::AdoptDoneTitle),
+    }
+}
+
+/// 标题下那句说明（Pick 段说清「什么都不复制」；Done 段说清「去实例列表启动」）。
+pub(super) fn subtitle(stage: AdoptStage, adopt_state: &AdoptState, catalog: Catalog) -> String {
+    match stage {
+        AdoptStage::Pick => catalog.text(Key::AdoptSubtitle).to_string(),
+        // 预检：版本名 · 目标档（隔离档在正文里单独一行，重复一遍只会更吵）
+        AdoptStage::Preview => adopt_state
+            .plan
+            .as_ref()
+            .map(|plan| format!("{} · {}", plan.name, target_label(plan.target, catalog)))
+            .unwrap_or_default(),
+        AdoptStage::Failed => adopt_state
+            .failure
+            .as_ref()
+            .map(|failure| failure.message.clone())
+            .unwrap_or_default(),
+        AdoptStage::Done => catalog.text(Key::AdoptDoneHint).to_string(),
+    }
+}
+
+/// 页脚按钮（按段给不同组合；在等回程时主按钮禁用）。
+pub(super) fn footer<'a>(
+    ui: &'a Ui,
+    form: &'a Form,
+    adopt_state: &'a AdoptState,
+    stage: AdoptStage,
+    catalog: Catalog,
+) -> Element<'a, Message> {
+    let busy = form.busy.waiting();
+
+    let primary: Element<'a, Message> = match stage {
+        AdoptStage::Pick => {
+            let ready = form.candidate(adopt_state).is_some_and(|c| c.adoptable()) && !busy;
+            if ready {
+                buttons::filled(
+                    ui,
+                    Button::new(catalog.text(Key::AdoptPreview), adopt(AdoptMessage::Check)),
+                )
+            } else {
+                buttons::filled(ui, Button::disabled(catalog.text(Key::AdoptPreview)))
+            }
+        }
+        AdoptStage::Preview if !busy => buttons::filled(
+            ui,
+            Button::new(
+                catalog.text(Key::AdoptConfirm),
+                adopt(AdoptMessage::Confirm),
+            ),
+        ),
+        AdoptStage::Preview => {
+            buttons::filled(ui, Button::disabled(catalog.text(Key::AdoptConfirm)))
+        }
+        // 失败 / 完成：主按钮就是关掉（Done 不用「去列表看」——实例已经在列表里了）
+        AdoptStage::Failed | AdoptStage::Done => buttons::filled(
+            ui,
+            Button::new(catalog.text(Key::AdoptClose), adopt(AdoptMessage::Close)),
+        ),
+    };
+
+    let mut actions = row![].spacing(ui.space(Sp::X2)).width(Length::Fill);
+    // Preview / Failed 给一条「退回候选列表」（= 重新扫一次，代价只有一次读目录）
+    if matches!(stage, AdoptStage::Preview | AdoptStage::Failed) {
+        actions = actions.push(buttons::text(
+            ui,
+            Button::new(catalog.text(Key::AdoptBack), adopt(AdoptMessage::Back)),
+        ));
+    }
+    actions = actions.push(container(Space::new()).width(Length::Fill));
+    // 失败/完成段的主按钮就是「关闭」，再给一枚文字「关闭」就是两枚一模一样的按钮
+    if matches!(stage, AdoptStage::Pick | AdoptStage::Preview) {
+        actions = actions.push(buttons::text(
+            ui,
+            Button::new(catalog.text(Key::AdoptClose), adopt(AdoptMessage::Close)),
+        ));
+    }
+    actions = actions.push(primary);
+
+    column![actions].width(Length::Fill).into()
+}

crates/app-iced/src/app/adopt/shot.rs

@@ -0,0 +1,205 @@
+//! 出图用的向导状态夹具（D30 视觉验收的输入）。
+//!
+//! ## 为什么要有它
+//!
+//! 向导是**四段有状态**的界面，而截图通道只跑一次 `view()`（第 3 帧落盘），没有真人点按钮。
+//! 组件库的做法是 `--screen=gallery` + `ForcedState`，页面层的做法是 `pages/instances/demo.rs`
+//! 的 `DEMO`——同一类要求，同一类做法：**给渲染器一份确定的状态**，而不是让截图去赌异步时序。
+//!
+//! ## 哪些是真、哪些是夹具（复审请照这条核对）
+//!
+//! | 内容 | 来源 |
+//! |---|---|
+//! | 候选 / 问题 / 失败原因 | **夹具**（合成的 id 与问题文本，只为把版面撑到真实形态） |
+//! | 运行目录 / 隔离档 | 夹具（固定路径，便于两张图逐像素对照） |
+//! | **后果原文** | **真**：`unlucky_core::game::adopt::target_notes()` 现算，一个字不抄 |
+//! | 文案（标题/标签/按钮） | **真**：`unlucky_i18n` 目录 |
+//! | 渲染 | **真**：`--software-renderer`（tiny-skia）1180×760，与产品路径同一棵控件树 |
+//!
+//! 也就是说：这些图证明**版面与文案**，不证明 core 的判据（判据的证据在 `host/adopt/tests.rs`
+//! 与 `core/tests/adopt/`）。
+//!
+//! ## 怎么用
+//!
+//! ```text
+//! ULL_ADOPT_STATE=pick|pick-selected|empty|preview|shared|failed|done \
+//!   unlucky-launcher-iced.exe --software-renderer --screenshot <path> [--screenshot-theme dark]
+//! ```
+//!
+//! 只在 `--screenshot` 已经给了的情况下生效（交互模式读这个环境变量没有意义，直接忽略）。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::adopt::{target_notes, AdoptTarget};
+use unlucky_presenter::dto::{
+    AdoptCandidateView, AdoptDoneView, AdoptEvent, AdoptFailureView, AdoptIsolationView,
+    AdoptPlanView, AdoptProblemView, AdoptScanView, AdoptState, AdoptTargetView,
+};
+
+use super::{Busy, Form};
+
+/// 夹具里的版本目录（只是**画**出来的路径，不碰盘）。
+const VERSIONS_DIR: &str = "D:/minecraft/.minecraft/versions";
+
+/// 夹具里的数据区运行目录。
+const INSTANCE_RUN_DIR: &str = "D:/ULL/.ULL/data/instances/Better-MC";
+
+/// 夹具里的游戏根。
+const GAME_ROOT: &str = "D:/minecraft/.minecraft";
+
+/// 环境变量名（见模块文档）。
+pub(crate) const ENV: &str = "ULL_ADOPT_STATE";
+
+/// 按名字造一份「打开着的向导」；不认识的名字返回 `None`（不影响正常启动）。
+pub(crate) fn seed(name: &str) -> Option<(Form, AdoptState)> {
+    let name = name.trim().to_ascii_lowercase();
+    let mut form = Form {
+        open: true,
+        ..Form::default()
+    };
+    let mut state = AdoptState::default();
+
+    match name.as_str() {
+        // 扫描完成、还没选版本（列表里三态齐全：可导入 / 已登记 / 有问题）
+        "pick" => {
+            state.apply(AdoptEvent::Scan(Box::new(scan_view())));
+            form.busy = Busy::Idle;
+        }
+        // 扫描完成、**已选中一个可导入的版本**（选中行底色 + 预检按钮启用态）
+        "pick-selected" => {
+            state.apply(AdoptEvent::Scan(Box::new(scan_view())));
+            form.selected = Some("1.20.1".to_string());
+            form.busy = Busy::Idle;
+        }
+        // 游戏根下真没有版本（空态）
+        "empty" => {
+            state.apply(AdoptEvent::Scan(Box::new(AdoptScanView {
+                versions_dir: PathBuf::from(VERSIONS_DIR),
+                candidates: Vec::new(),
+            })));
+            form.busy = Busy::Idle;
+        }
+        // 选中缺省档（InstanceDir）并点过预检
+        "preview" => {
+            state.apply(AdoptEvent::Scan(Box::new(scan_view())));
+            state.apply(AdoptEvent::Planned(Box::new(plan_view(
+                AdoptTargetView::InstanceDir,
+                AdoptIsolationView::Custom,
+                INSTANCE_RUN_DIR,
+            ))));
+            form.selected = Some("1.20.1".to_string());
+            form.checked = true;
+            form.busy = Busy::Idle;
+        }
+        // 选中共享档（Shared）：后果原文由 core `target_notes()` 现算
+        "shared" => {
+            state.apply(AdoptEvent::Scan(Box::new(scan_view())));
+            state.apply(AdoptEvent::Planned(Box::new(plan_view(
+                AdoptTargetView::Shared,
+                AdoptIsolationView::Shared,
+                GAME_ROOT,
+            ))));
+            form.selected = Some("1.20.1".to_string());
+            form.target = AdoptTargetView::Shared;
+            form.checked = true;
+            form.busy = Busy::Idle;
+        }
+        // 预检失败：两条问题逐条列出（不许折叠成一句）
+        "failed" => {
+            state.apply(AdoptEvent::Scan(Box::new(scan_view())));
+            state.apply(AdoptEvent::Failed(Box::new(AdoptFailureView {
+                code: "adopt_not_adoptable".to_string(),
+                message: "版本 1.19.4 不能登记：清单不是合法 JSON".to_string(),
+                problems: vec![
+                    AdoptProblemView {
+                        code: "manifest_invalid_json".to_string(),
+                        message: format!(
+                            "清单不是合法 JSON {VERSIONS_DIR}/1.19.4/1.19.4.json：expected `,` or `}}` at line 12 column 3"
+                        ),
+                    },
+                    AdoptProblemView {
+                        code: "missing_parent".to_string(),
+                        message: "版本 1.19.4 继承的父版本 1.19.3 不在盘上".to_string(),
+                    },
+                ],
+            })));
+            form.selected = Some("1.19.4".to_string());
+            form.checked = true;
+            form.busy = Busy::Idle;
+        }
+        // 登记完成
+        "done" => {
+            state.apply(AdoptEvent::Scan(Box::new(scan_view())));
+            state.apply(AdoptEvent::Done(Box::new(AdoptDoneView {
+                instance_id: "2f1c0a5e-7f4b-4c1d-9a2e-6b8d5c3a1f70".to_string(),
+                name: "Better MC".to_string(),
+                version_id: "1.20.1-fabric-0.15.0".to_string(),
+                isolation: AdoptIsolationView::Custom,
+                run_dir: PathBuf::from(INSTANCE_RUN_DIR),
+                dir_created: true,
+                notes: target_notes(&AdoptTarget::InstanceDir, &PathBuf::from(INSTANCE_RUN_DIR)),
+            })));
+            form.selected = Some("1.20.1-fabric-0.15.0".to_string());
+            form.checked = true;
+            form.busy = Busy::Idle;
+        }
+        _ => return None,
+    }
+    Some((form, state))
+}
+
+/// 一份扫描结果（三态齐全）。
+fn scan_view() -> AdoptScanView {
+    AdoptScanView {
+        versions_dir: PathBuf::from(VERSIONS_DIR),
+        candidates: vec![
+            AdoptCandidateView {
+                version_id: "1.20.1".to_string(),
+                jar_present: true,
+                inherits: Vec::new(),
+                registered: Vec::new(),
+                problems: Vec::new(),
+            },
+            AdoptCandidateView {
+                version_id: "1.20.1-fabric-0.15.0".to_string(),
+                jar_present: false,
+                inherits: vec!["1.20.1-fabric-0.15.0".to_string(), "1.20.1".to_string()],
+                registered: vec!["Better MC".to_string()],
+                problems: Vec::new(),
+            },
+            AdoptCandidateView {
+                version_id: "1.19.4".to_string(),
+                jar_present: true,
+                inherits: Vec::new(),
+                registered: Vec::new(),
+                problems: vec![AdoptProblemView {
+                    code: "manifest_invalid_json".to_string(),
+                    message: format!(
+                        "清单不是合法 JSON {VERSIONS_DIR}/1.19.4/1.19.4.json：expected `,` or `}}` at line 12 column 3"
+                    ),
+                }],
+            },
+        ],
+    }
+}
+
+/// 一份预检结果。**`notes` 由 core 现算**（共享档/版本目录档的后果原文只有一处）。
+fn plan_view(
+    target: AdoptTargetView,
+    isolation: AdoptIsolationView,
+    run_dir: &str,
+) -> AdoptPlanView {
+    let core_target = match target {
+        AdoptTargetView::InstanceDir => AdoptTarget::InstanceDir,
+        AdoptTargetView::Shared => AdoptTarget::Shared,
+        AdoptTargetView::VersionDir => AdoptTarget::VersionDir,
+    };
+    AdoptPlanView {
+        version_id: "1.20.1".to_string(),
+        name: "1.20.1".to_string(),
+        target,
+        isolation,
+        run_dir: PathBuf::from(run_dir),
+        notes: target_notes(&core_target, &PathBuf::from(run_dir)),
+    }
+}

crates/app-iced/src/app/adopt/tests.rs

@@ -0,0 +1,287 @@
+//! `app::adopt` 的用态用例（M223）：表单态 + 四段投影。
+//!
+//! 抓得住：
+//! - `Form` 的生命周期（open 清上一轮 / close 全清 / settled 解除等待）；
+//! - `candidate()` 在选中项不在列表里时返回 `None`（界面自动退回「请选择」）；
+//! - 四段的文案真源（标题/后果原文/问题逐条）能从 `AdoptState` 投影出来。
+//!
+//! 抓不住：**像素**（那是 D30 的截图通道）；也不抓 core 的判据（那是 `host/adopt/tests.rs`）。
+
+use unlucky_i18n::{Key, Lang};
+use unlucky_presenter::dto::{
+    AdoptCandidateView, AdoptDoneView, AdoptEvent, AdoptFailureView, AdoptIsolationView,
+    AdoptPlanView, AdoptProblemView, AdoptScanView, AdoptStage, AdoptState, AdoptTargetView,
+};
+
+use super::*;
+
+fn candidate(version_id: &str, problems: Vec<AdoptProblemView>) -> AdoptCandidateView {
+    AdoptCandidateView {
+        version_id: version_id.to_string(),
+        jar_present: true,
+        inherits: Vec::new(),
+        registered: Vec::new(),
+        problems,
+    }
+}
+
+fn state_with_scan() -> AdoptState {
+    let mut state = AdoptState::default();
+    state.apply(AdoptEvent::Scan(Box::new(AdoptScanView {
+        versions_dir: std::path::PathBuf::from("/game/versions"),
+        candidates: vec![candidate("1.20.1", Vec::new())],
+    })));
+    state
+}
+
+/// 打开 ⇒ 关闭：上一轮的选中与名字都要清掉（否则下次打开画的是上一次的草稿）。
+#[test]
+fn open_and_close_reset_the_form() {
+    let mut form = Form::default();
+    form.open();
+    assert!(form.open);
+    assert_eq!(form.busy, Busy::Scanning);
+    assert_eq!(form.target, AdoptTargetView::InstanceDir);
+
+    form.selected = Some("1.20.1".to_string());
+    form.name = "生存".to_string();
+    form.close();
+    assert!(!form.open);
+    assert!(form.selected.is_none());
+    assert!(form.name.is_empty());
+
+    // 再开一次也不该带着上一轮的选中项
+    form.open();
+    assert!(form.selected.is_none());
+}
+
+/// `settled` 只解除等待，不动用户填的东西（回程不该清表单）。
+#[test]
+fn settling_keeps_what_the_user_typed() {
+    let mut form = Form::default();
+    form.open();
+    form.selected = Some("1.20.1".to_string());
+    form.name = "生存".to_string();
+    form.settled();
+    assert_eq!(form.busy, Busy::Idle);
+    assert_eq!(form.selected.as_deref(), Some("1.20.1"));
+    assert_eq!(form.name, "生存");
+}
+
+/// 选中项不在候选列表里 ⇒ `candidate()` 是 `None`（界面不能对着一个不存在的版本画「预检」）。
+#[test]
+fn candidate_is_none_when_the_selection_vanished() {
+    let state = state_with_scan();
+    let mut form = Form {
+        selected: Some("1.20.1".to_string()),
+        ..Form::default()
+    };
+    assert!(form.candidate(&state).is_some());
+    form.selected = Some("9.9.9".to_string());
+    assert!(form.candidate(&state).is_none());
+}
+
+/// 四段的标题与后果原文都从目录来（不写死英文字面量、不重写 core 的后果句）。
+#[test]
+fn the_four_stages_project_from_the_event_state() {
+    let catalog = Lang::ZhCn.catalog();
+    let mut state = state_with_scan();
+
+    // Pick
+    assert_eq!(state.stage(), AdoptStage::Pick);
+    assert_eq!(
+        shell::title_text(state.stage(), catalog),
+        catalog.text(Key::AdoptTitle),
+        "标题走目录"
+    );
+    assert!(shell::subtitle(state.stage(), &state, catalog).contains("不复制"));
+
+    // Preview：`notes` 是 core `target_notes()` 的原文，界面一个字都不许改
+    let note =
+        "运行目录 = /game（共享档）：mods/saves/config 会落在别人的 .minecraft 里".to_string();
+    state.apply(AdoptEvent::Planned(Box::new(AdoptPlanView {
+        version_id: "1.20.1".to_string(),
+        name: "1.20.1".to_string(),
+        target: AdoptTargetView::Shared,
+        isolation: AdoptIsolationView::Shared,
+        run_dir: std::path::PathBuf::from("/game"),
+        notes: vec![note.clone()],
+    })));
+    assert_eq!(state.stage(), AdoptStage::Preview);
+    assert_eq!(
+        state.plan.as_ref().map(|plan| plan.notes.first().cloned()),
+        Some(Some(note.clone())),
+        "后果原文必须原样留着"
+    );
+
+    // Failed：problems 逐条（不折叠）
+    state.apply(AdoptEvent::Failed(Box::new(AdoptFailureView {
+        code: "adopt_not_adoptable".to_string(),
+        message: "版本 1.19.4 不能登记".to_string(),
+        problems: vec![
+            AdoptProblemView {
+                code: "manifest_missing".to_string(),
+                message: "没有清单".to_string(),
+            },
+            AdoptProblemView {
+                code: "missing_parent".to_string(),
+                message: "缺父版本 1.20.1".to_string(),
+            },
+        ],
+    })));
+    assert_eq!(state.stage(), AdoptStage::Failed);
+    assert_eq!(
+        state.failure.as_ref().map(|f| f.problems.len()),
+        Some(2),
+        "两条问题一条都不许吞"
+    );
+    assert_eq!(
+        shell::title_text(state.stage(), catalog),
+        catalog.text(Key::AdoptFailureTitle)
+    );
+
+    // Done
+    state.apply(AdoptEvent::Done(Box::new(AdoptDoneView {
+        instance_id: "id-1".to_string(),
+        name: "1.20.1".to_string(),
+        version_id: "1.20.1".to_string(),
+        isolation: AdoptIsolationView::Shared,
+        run_dir: std::path::PathBuf::from("/game"),
+        dir_created: false,
+        notes: vec![note],
+    })));
+    assert_eq!(state.stage(), AdoptStage::Done);
+    assert_eq!(
+        shell::title_text(state.stage(), catalog),
+        catalog.text(Key::AdoptDoneTitle)
+    );
+}
+
+/// 中英两套目录的向导文案都不是占位（`text()` 回落到 key 名就是这个用例要抓的假绿）。
+#[test]
+fn both_catalogs_have_the_wizard_wording() {
+    for lang in [Lang::En, Lang::ZhCn] {
+        let catalog = lang.catalog();
+        for key in [
+            Key::AdoptTitle,
+            Key::AdoptSubtitle,
+            Key::AdoptScanning,
+            Key::AdoptEmpty,
+            Key::AdoptSelectLabel,
+            Key::AdoptReady,
+            Key::AdoptTargetLabel,
+            Key::AdoptTargetInstanceDir,
+            Key::AdoptTargetShared,
+            Key::AdoptTargetVersionDir,
+            Key::AdoptNameLabel,
+            Key::AdoptPreview,
+            Key::AdoptConfirm,
+            Key::AdoptBack,
+            Key::AdoptClose,
+            Key::AdoptPlanTitle,
+            Key::AdoptPlanRunDir,
+            Key::AdoptPlanIsolation,
+            Key::AdoptFailureTitle,
+            Key::AdoptProblemCount,
+            Key::AdoptDoneTitle,
+            Key::AdoptDoneHint,
+        ] {
+            let value = catalog.text(key);
+            assert!(!value.is_empty(), "{key:?} 在 {lang:?} 是空的");
+            assert_ne!(
+                value,
+                format!("{key:?}"),
+                "{key:?} 在 {lang:?} 没进目录（回落成了 key 名）"
+            );
+        }
+    }
+    // 共享档的短提示必须把「会写进别人的 .minecraft」说清楚（选之前就得知道）
+    let hint = Lang::En.catalog().text(Key::AdoptTargetSharedHint);
+    assert!(hint.contains(".minecraft"), "{hint}");
+}
+
+/// 「点选共享档 ⇒ 立刻看到后果原文」但**不**把用户甩到确认页：
+/// 预检结果到了也只是 Pick 段里的提示，直到用户点过「预检」(`checked`) 才进 Preview。
+///
+/// 抓得住：把 `Form::stage` 写回直接取 `AdoptState::stage()`（点一次共享档就跳到确认页，
+/// 实例名还没来得及改）；或忘了 `fresh_plan` 的目标一致性判据（改档之后画上一档的后果原文）。
+#[test]
+fn a_foreign_target_shows_its_notes_without_jumping_to_confirm() {
+    let mut state = state_with_scan();
+    let note =
+        "运行目录 = /game（共享档）：mods/saves/config 会落在别人的 .minecraft 里".to_string();
+    state.apply(AdoptEvent::Planned(Box::new(AdoptPlanView {
+        version_id: "1.20.1".to_string(),
+        name: "1.20.1".to_string(),
+        target: AdoptTargetView::Shared,
+        isolation: AdoptIsolationView::Shared,
+        run_dir: std::path::PathBuf::from("/game"),
+        notes: vec![note.clone()],
+    })));
+
+    let mut form = Form {
+        open: true,
+        selected: Some("1.20.1".to_string()),
+        target: AdoptTargetView::Shared,
+        ..Form::default()
+    };
+
+    // 自动预检回来但用户没点「预检」：仍是 Pick 段，notes 当作提示可读
+    assert_eq!(form.stage(&state), AdoptStage::Pick);
+    assert_eq!(
+        form.fresh_plan(&state)
+            .map(|plan| plan.notes.first().cloned()),
+        Some(Some(note.clone())),
+        "后果原文必须能取到"
+    );
+
+    // 点过「预检」之后才进确认段
+    form.checked = true;
+    assert_eq!(form.stage(&state), AdoptStage::Preview);
+
+    // 换了目标档：上一档的预检作废（不再当后果原文画）
+    form.target = AdoptTargetView::VersionDir;
+    assert!(form.fresh_plan(&state).is_none(), "过期的预检不许画");
+}
+
+/// **P2-2**：`fresh_plan` 必须按**版本 id** 过期，不只是目标档。
+///
+/// 场景：先选 1.20.1 + 版本目录档（notes 说 `versions/1.20.1`），再改选 1.19.4——目标档没变，
+/// 旧的预检结果若不按版本过滤就会继续当「这个版本的后果原文」画出来，那是一句假话。
+///
+/// 抓得住：`fresh_plan` 只看 `plan.target == self.target`（第一次修法就是这样漏的）。
+/// 抓不住：core 真的会不会为 1.19.4 算出同一段 notes（那是 `target_notes()` 的活）。
+#[test]
+fn fresh_plan_expires_when_the_selected_version_changes() {
+    let mut state = state_with_scan();
+    state.apply(AdoptEvent::Planned(Box::new(AdoptPlanView {
+        version_id: "1.20.1".to_string(),
+        name: "1.20.1".to_string(),
+        target: AdoptTargetView::VersionDir,
+        isolation: AdoptIsolationView::Isolated,
+        run_dir: std::path::PathBuf::from("/game/versions/1.20.1"),
+        notes: vec!["运行目录 = 版本目录 /game/versions/1.20.1".to_string()],
+    })));
+
+    let mut form = Form {
+        open: true,
+        selected: Some("1.20.1".to_string()),
+        target: AdoptTargetView::VersionDir,
+        checked: true,
+        ..Form::default()
+    };
+    assert!(
+        form.fresh_plan(&state).is_some(),
+        "对得上版本与目标档时应当可读"
+    );
+
+    // 改选另一个版本：目标档没变，但旧预检说的是别的版本的目录
+    form.selected = Some("1.19.4".to_string());
+    assert!(
+        form.fresh_plan(&state).is_none(),
+        "换了版本之后旧预检必须过期（否则画的是 1.20.1 的后果原文）"
+    );
+    // 没选版本时同样不该画（`None` = 没有任何版本的预检可言）
+    form.selected = None;
+    assert!(form.fresh_plan(&state).is_none());
+}

crates/app-iced/src/app/adopt/text.rs

@@ -0,0 +1,88 @@
+//! 向导里的小工具：等宽行、可换行正文、标签、问题行、档位人话。
+//!
+//! 单独一个文件只为守 400 行硬线（AGENTS §3.1）：三段视图（`pick` / `panes`）与卡壳
+//! （`adopt.rs`）都要用它们，放哪儿都会让那一处越线。
+
+use iced::widget::text::LineHeight;
+use iced::widget::{column, text};
+use iced::{Color, Element, Font, Length, Pixels};
+
+use unlucky_design::color::Role;
+use unlucky_design::typography::TypeRole;
+use unlucky_i18n::{Catalog, Key};
+use unlucky_presenter::dto::{AdoptIsolationView, AdoptProblemView, AdoptTargetView};
+
+use crate::pages::frame;
+use crate::theme::Ui;
+
+use super::super::message::Message;
+
+/// 段内的次级标签（`LabelMedium` + `OnSurfaceVariant`）。
+pub(super) fn label<'a>(ui: &'a Ui, value: &'a str) -> Element<'a, Message> {
+    frame::text_role(
+        ui,
+        TypeRole::LabelMedium,
+        false,
+        value,
+        ui.color(Role::OnSurfaceVariant),
+    )
+    .map(Message::Page)
+}
+
+/// 等宽一行（路径 / 机读码要能逐字读）。
+pub(super) fn mono<'a>(ui: &'a Ui, value: String) -> Element<'a, Message> {
+    let style = ui.style(TypeRole::BodySmall);
+    text(value)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        .font(Font {
+            family: iced::font::Family::Name(ui.families().mono),
+            ..Font::DEFAULT
+        })
+        .color(ui.color(Role::OnSurface))
+        .width(Length::Fill)
+        .wrapping(iced::widget::text::Wrapping::WordOrGlyph)
+        .into()
+}
+
+/// 一段可换行的正文（长路径只按词折行会把卡顶破，所以按词或字形折）。
+pub(super) fn wrapped<'a>(ui: &'a Ui, value: String, color: Color) -> Element<'a, Message> {
+    frame::text_role_owned(ui, TypeRole::BodySmall, false, value, color).map(Message::Page)
+}
+
+/// 「标签 + 值」一行（值用等宽）。
+pub(super) fn field_line<'a>(ui: &'a Ui, label_text: &'a str, value: &str) -> Element<'a, Message> {
+    column![label(ui, label_text), mono(ui, value.to_string())]
+        .spacing(0.0)
+        .width(Length::Fill)
+        .into()
+}
+
+/// 一条问题：稳定码（等宽） + 人读原因（`Error` 色）。**一条都不许折叠**。
+pub(super) fn problem_line<'a>(ui: &'a Ui, problem: &'a AdoptProblemView) -> Element<'a, Message> {
+    column![
+        mono(ui, problem.code.clone()),
+        wrapped(ui, problem.message.clone(), ui.color(Role::Error)),
+    ]
+    .spacing(0.0)
+    .width(Length::Fill)
+    .into()
+}
+
+/// 隔离档的人话（沿用实例页已有的两条；`custom` 就是缺省档，直接说「在 ULL 数据区新建」）。
+pub(super) fn isolation_label(isolation: AdoptIsolationView, catalog: Catalog) -> String {
+    match isolation {
+        AdoptIsolationView::Isolated => catalog.text(Key::InstancesIsolationIsolated).to_string(),
+        AdoptIsolationView::Shared => catalog.text(Key::InstancesIsolationShared).to_string(),
+        AdoptIsolationView::Custom => catalog.text(Key::AdoptTargetInstanceDir).to_string(),
+    }
+}
+
+/// 目标档的短标签。
+pub(super) fn target_label(target: AdoptTargetView, catalog: Catalog) -> &'static str {
+    match target {
+        AdoptTargetView::InstanceDir => catalog.text(Key::AdoptTargetInstanceDir),
+        AdoptTargetView::Shared => catalog.text(Key::AdoptTargetShared),
+        AdoptTargetView::VersionDir => catalog.text(Key::AdoptTargetVersionDir),
+    }
+}

crates/app-iced/src/app/appearance.rs

@@ -0,0 +1,133 @@
+//! App 侧的外观动作：**下发整窗 α / 写回配置 / 打取证日志**。
+//!
+//! 三件事各自只有一条路，且都从这里出去（`update` 只负责把它们按消息串起来）：
+//!
+//! | 动作 | 唯一落点 | 为什么 |
+//! |---|---|---|
+//! | 下发整窗 α | [`App::apply_window_alpha`] → `app::window_alpha::dispatch` | 判据在 `platform`、FFI 在 `platform/win32`，这里只做「取 α → 交给执行侧 → 记日志」 |
+//! | 写回配置 | [`App::persist_appearance`]（8 个 UI 字段）+ `AppCommand::SetSetting`（另外**三个**只读键） | 每个键**只有一个写者**：`AppearancePrefs` 里没有 `window_opacity` / `palette_source` / `window_corner`，它们只能走 schema 指令 |
+//! | 取证日志 | [`App::log_appearance`] | 一行里同时有请求值、生效值、下发字节与 FFI 结局 |
+//!
+//! ## 为什么「写回」要分两条路
+//!
+//! `SettingsBridge::persist` 收的是 `AppearancePrefs`（背景图四件 + 面板 α + 玻璃 + 强调色），
+//! 它的实现是「先读文件当前值，再覆盖我们改的那几个字段」——所以用它写**它覆盖的键**最省事，
+//! 也不会把用户的自定义强调色冲掉。而 `appearance.window_opacity` / `appearance.palette_source` /
+//! `appearance.window_corner` 不在那个结构里（它们是「只读下层键」，见
+//! `presenter::prefs::AppearanceBase` 的**四个**字段：整窗 α / 标题栏三态 / 配色来源 / 窗口圆角），
+//! 写它们只能走 schema 白名单指令 `AppCommand::SetSetting`（真 host 用 `SettingStore::set` 落盘）。
+//! 其中「标题栏三态」目前**没有 UI 写者**（D37 的接线未落地），所以走 `SetSetting` 的是**三个**键。
+
+use crate::app::diag::diag;
+use unlucky_presenter::dto::AppCommand;
+
+use crate::pages::appearance::Change;
+
+use super::state::App;
+use super::window_alpha::{self, Dispatch};
+
+impl App {
+    /// 把当前整窗 α 交给执行侧（补 `WS_EX_LAYERED` + `SetLayeredWindowAttributes`）并记一行日志。
+    ///
+    /// 没有句柄时**也打日志**（`hwnd=none`）：不能让「α 没生效」这件事只体现为「屏幕上没变化」。
+    pub(super) fn apply_window_alpha(&self, context: &str) {
+        let Some(hwnd) = self.hwnd else {
+            self.log_appearance(context, None);
+            return;
+        };
+        let alpha = crate::platform::effective_window_alpha(
+            self.appearance.backend,
+            f64::from(self.appearance.window_opacity),
+        );
+        let dispatch = window_alpha::dispatch(hwnd, alpha);
+        self.log_appearance(context, Some(&dispatch));
+    }
+
+    /// 取证日志：`[appearance] <状态行> layered=… outcome=…`。
+    ///
+    /// 数值来自 [`crate::pages::appearance::State::log_line`]（请求值 / 生效值 / 下发字节），
+    /// 尾巴来自执行侧。**这一行就是「透明度到底设成了多少」的证据**——RDP 上的观感不可信。
+    pub(super) fn log_appearance(&self, context: &str, dispatch: Option<&Dispatch>) {
+        let mut line = self.appearance.log_line(context);
+        if let Some(dispatch) = dispatch {
+            line.push(' ');
+            line.push_str(&dispatch.describe());
+        } else {
+            line.push_str(" layered=skipped outcome=no-window");
+        }
+        diag!("{line}");
+    }
+
+    /// 设置页改了一项外观。
+    pub(super) fn on_appearance(&mut self, change: Change) {
+        let needs_window = self.appearance.apply(change.clone());
+
+        // 配色来源 / 背景图可能变了 ⇒ `Ui` 可能要改用解析出的方案。
+        self.rebuild_ui();
+        self.view_dirty = true;
+        self.refresh_view();
+
+        match change.key() {
+            // 三个只读下层键（整窗 α / 配色来源 / 窗口圆角）：走 schema 指令
+            // （`SettingsBridge` 的结构里没有它们；标题栏三态还没有 UI 写者，不在此列）。
+            Some(_)
+                if matches!(
+                    change,
+                    Change::WindowOpacity(_) | Change::PaletteSource(_) | Change::Corner(_)
+                ) =>
+            {
+                if let (Some(key), Some(value)) = (change.key(), change.value()) {
+                    self.dispatch(AppCommand::SetSetting {
+                        key: key.to_owned(),
+                        value,
+                    });
+                }
+            }
+            // 其余键：走 bridge（M250 起强调色也在这条路上，取的是上一次合法值）。
+            Some(_) => self.persist_appearance(),
+            None => {}
+        }
+
+        if needs_window {
+            self.apply_window_alpha("change");
+        } else {
+            self.log_appearance("change", None);
+        }
+        // M116：圆角档位变了要**重新判定 + 重新下发**（与整窗 α 是两条独立的管线）。
+        self.apply_window_corner("change");
+    }
+
+    /// 重读配置后同步外观（热切：外部 CLI / AI 改完 1 秒内生效）。
+    pub(super) fn reload_appearance(&mut self) {
+        let (prefs, _theme) = self.bridge.load();
+        let base = self.bridge.load_base();
+        self.appearance.reload(&prefs, &base);
+        self.appearance_prefs = prefs;
+        self.rebuild_ui();
+        self.view_dirty = true;
+        self.apply_window_alpha("reload");
+        // M116：外部（CLI / AI）改了 `appearance.window_corner` 也要热生效。
+        self.apply_window_corner("reload");
+    }
+
+    /// 把外观写回 `launcher.json`（本页控件管的那批字段 + 强调色；其余键原样保留）。
+    fn persist_appearance(&mut self) {
+        let mut prefs = self.appearance_prefs.clone();
+        prefs.bg_image_enabled = self.appearance.bg_enabled;
+        prefs.bg_image = self.appearance.bg_path.clone();
+        prefs.bg_fill = self.appearance.bg_fill;
+        prefs.bg_dim = self.appearance.bg_dim;
+        prefs.panel_alpha = self.appearance.panel_alpha;
+        prefs.glass = self.appearance.glass;
+        // M250：强调色也是「UI 写入字段」了——取**上一次合法值**（非法手输不写盘，见 `accent::Accent`）。
+        prefs.accent_color = self.appearance.accent.persist_value().to_owned();
+
+        self.bridge.persist(&prefs, self.theme_mode);
+        self.appearance_prefs = prefs;
+
+        match self.bridge.path() {
+            Some(path) => diag!("[settings] 外观已写回 {}", path.display()),
+            None => diag!("[settings] 外观未落盘（数据根解析不出来，内存态运行）"),
+        }
+    }
+}

crates/app-iced/src/app/backend.rs

@@ -0,0 +1,177 @@
+//! 本进程**实际**用的是哪个渲染后端（D36 的「CPU 档」判据）。
+//!
+//! ## 为什么不能直接看 `--renderer` 的请求值
+//!
+//! `Options::backend` 是**请求**（默认 `Auto`）。真正落到哪个渲染器由 `probe::apply` 决定，
+//! 它把结论写进进程环境变量 `ICED_BACKEND`（iced 只认这个）。于是默认参数 + 没有独显的机器上：
+//! 请求是 `Auto`，实际是 tiny-skia（CPU）——如果面板 α / 玻璃的降级判据只看请求值，
+//! D36 明写的「CPU 档面板 α 强制 1.0」**恰好在它最该生效的场景失效**（复审 r1 P2-2）。
+//!
+//! 所以判据统一走 [`effective_backend`]：它把 `ICED_BACKEND` 翻译回 [`Backend`]。
+//! 这里是**唯一**的翻译点，别在别处再读一遍环境变量。
+//!
+//! ## M97 之后这条链是准的（以前不是）
+//!
+//! 以前 `ICED_BACKEND` 可能是**候选列表**（`wgpu,tiny-skia`），运行期 wgpu 静默回退到
+//! tiny-skia 时这个变量还停在 wgpu ⇒ 本模块按 **GPU 档**判 ⇒ **半透明在 CPU 渲染器上照开**。
+//! 也就是说「静默降级」不只让日志说谎，还让 D36 的降级判据一起说谎。
+//!
+//! 现在 `ICED_BACKEND` **永远是单项**（[`crate::renderer::Kind`]），而且 `app::boot` 的重试
+//! 在降级重开前会把它改成 `tiny-skia`，于是：**真降级到 CPU 的那一次，面板 α 会正确地强制 1.0**。
+//!
+//! ## 已知边界（诚实登记）
+//!
+//! `iced` 0.14 没有公开的「当前后端」查询，所以本模块读的仍是**我们请求的那一项**。
+//! 单项 + 重试（[`crate::renderer`] 判据表第 8 行）把「请求 ≠ 实际」的窗口压到只剩一种：
+//! 重试那次自己也失败——那时候进程会带着具名错误退出，不会带着错的档位继续画。
+
+use crate::renderer::Kind;
+use crate::Backend;
+
+/// `ICED_BACKEND` 的取值 → 后端（纯函数，好测）。
+///
+/// 逗号列表按**首项**解释：兼容 M97 之前写下的值（以及外部手设的实验值），
+/// 但本 crate 不再产出那种值（守门测试见 `probe::tests::apply_writes_exactly_one_backend`）。
+#[must_use]
+pub(super) fn parse_kind(env: &str) -> Option<Kind> {
+    match env.trim().split(',').next()?.trim() {
+        "tiny-skia" => Some(Kind::TinySkia),
+        "wgpu" => Some(Kind::Wgpu),
+        _ => None,
+    }
+}
+
+/// `ICED_BACKEND` → 实际档位（纯函数，好测）。
+///
+/// | `ICED_BACKEND` | 含义（`probe::apply` 的产物） | 结论 |
+/// |---|---|---|
+/// | `tiny-skia` | 只有 CPU（`--renderer=cpu` / 未编 wgpu / 探测无硬件 / wgpu 失败后重开） | [`Backend::Cpu`] |
+/// | `wgpu` | 判据表第 3、6 行：起步就是 GPU（起不来会打印具名错误并重开成 `tiny-skia`） | [`Backend::Gpu`] |
+/// | 未设 / 别的值 | 不是本 crate 写的（外部手设 / M97 之前的旧进程） | 请求值（不猜） |
+#[must_use]
+pub(super) fn backend_from_env(request: Backend, env: Option<&str>) -> Backend {
+    env.and_then(parse_kind).map_or(request, Kind::tier)
+}
+
+/// 本进程实际生效的后端（判据 = `probe::apply` 写下的 `ICED_BACKEND`）。
+#[must_use]
+pub(super) fn effective_backend(request: Backend) -> Backend {
+    backend_from_env(request, std::env::var("ICED_BACKEND").ok().as_deref())
+}
+
+/// 本进程实际生效的**后端名**（`None` = 变量没写 / 不认识）。
+///
+/// 与 [`effective_backend`] 的区别：那个给「档位」，这个给「名字」，用于**取证日志**
+/// （`[shot] … renderer=wgpu`）。两张图分辨不出 GPU/CPU 的时候，靠的就是这一行。
+#[must_use]
+pub(super) fn effective_kind() -> Option<Kind> {
+    std::env::var("ICED_BACKEND")
+        .ok()
+        .as_deref()
+        .and_then(parse_kind)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::backend_from_env;
+    use crate::Backend;
+    use unlucky_presenter::prefs::{PANEL_ALPHA_MIN, WINDOW_ALPHA_MIN};
+
+    /// 抓得住：`probe::apply` 现在产出的**每一种单项值**都被翻译成正确的档位，
+    /// 且 M97 之前写下的逗号列表仍按首项解释（向后兼容）。
+    /// 抓不住：运行期重试降级那一刻的时序（那由 `app::boot` 的重试保证，见 `renderer` 判据表第 8 行）。
+    #[test]
+    fn every_iced_backend_value_maps_to_a_tier() {
+        // 本 crate 现在只产单项（`probe::tests::apply_writes_exactly_one_backend` 守这一条）。
+        assert_eq!(
+            backend_from_env(Backend::Auto, Some("tiny-skia")),
+            Backend::Cpu,
+            "M97 判据表第 5 行：探测无硬件 ⇒ CPU 档"
+        );
+        assert_eq!(
+            backend_from_env(Backend::Auto, Some("wgpu")),
+            Backend::Gpu,
+            "M97 判据表第 6 行：有硬件 ⇒ GPU 档"
+        );
+        assert_eq!(
+            backend_from_env(Backend::Cpu, Some("tiny-skia")),
+            Backend::Cpu,
+            "强制 CPU 也是 CPU 档"
+        );
+        // 兼容 M97 之前的逗号列表（外部手设 / 旧进程留下）：按首项解释。
+        assert_eq!(
+            backend_from_env(Backend::Auto, Some("tiny-skia,wgpu")),
+            Backend::Cpu
+        );
+        assert_eq!(
+            backend_from_env(Backend::Auto, Some("wgpu,tiny-skia")),
+            Backend::Gpu
+        );
+        assert_eq!(
+            backend_from_env(Backend::Gpu, Some("wgpu,tiny-skia")),
+            Backend::Gpu
+        );
+        // 未设 / 空白：保持请求值（不是本 crate 写的，不猜）。
+        assert_eq!(backend_from_env(Backend::Auto, None), Backend::Auto);
+        assert_eq!(backend_from_env(Backend::Auto, Some("  ")), Backend::Auto);
+        // 不认识的取值不猜：保留请求值。
+        assert_eq!(
+            backend_from_env(Backend::Auto, Some("metal")),
+            Backend::Auto
+        );
+    }
+
+    /// **复审 r1 P2-2 的守门**：默认档（`Auto`）在无独显机器上必须落进 CPU 档，
+    /// 从而让「面板 α / 玻璃强制 1.0」在默认路径上真的生效。
+    ///
+    /// 抓得住：判据走 `effective_backend()` 这条链（谁把 `State::new` 改回只吃请求值，这条会红）。
+    /// 抓不住：整窗 α 在 CPU 档仍要生效（那是另一条判据，见 `alpha` 模块真值表）。
+    #[test]
+    fn auto_with_a_software_renderer_forces_the_panel_opaque() {
+        use crate::pages::appearance::alpha::{effective_glass, effective_panel_alpha};
+
+        let backend = backend_from_env(Backend::Auto, Some("tiny-skia"));
+        assert_eq!(backend, Backend::Cpu);
+        assert_eq!(
+            effective_panel_alpha(backend, 0.55),
+            1.0,
+            "D36：CPU 档面板 1.0"
+        );
+        assert!(!effective_glass(backend, true), "D36：CPU 档玻璃强制关");
+        // 但整窗 α 不受限（D36 对 D27 的修订）。
+        assert!(crate::platform::effective_window_alpha(backend, 0.8).is_some());
+
+        // 反方向：GPU 档不做这个降级（否则「强制」就没意义了）。
+        let gpu = backend_from_env(Backend::Auto, Some("wgpu"));
+        assert_eq!(effective_panel_alpha(gpu, 0.55), 0.55);
+        assert!((PANEL_ALPHA_MIN - 0.4).abs() < 1e-9 && (WINDOW_ALPHA_MIN - 0.08).abs() < 1e-9);
+    }
+
+    /// **M97 的新守门**：wgpu 失败重开成 `tiny-skia` 之后，档位必须跟着变成 CPU 档。
+    ///
+    /// 这是修之前做不到的一条：那时变量停在 `wgpu,tiny-skia`，静默回退到 tiny-skia 之后
+    /// 判据仍然读 `Gpu` ⇒ 半透明在 CPU 渲染器上照开。现在 `app::boot` 重开前会改写这个值，
+    /// 这条测试钉的是「改写成 tiny-skia 之后判据确实翻转」。
+    /// **两个后端取值各自对应哪个档位、面板 α 各是多少。**
+    ///
+    /// ⚠️ 这条**不**守「降级后档位翻转」——它只是把两个字面量喂给纯函数，`respawn` 一行都没执行。
+    /// 复审 M97 r1 p2-1 就是靠这一点把 `respawn` 里的 `.env("ICED_BACKEND", …)` 删掉而测试全绿的。
+    /// 真正的翻转由 `app::boot::tests::fallback_env_carries_the_backend_and_the_gate`
+    /// （respawn 到底传了什么）钉住——那条红了才是「翻转坏了」。
+    #[test]
+    fn each_backend_value_maps_to_its_tier_and_alpha() {
+        use crate::pages::appearance::alpha::effective_panel_alpha;
+
+        let gpu = backend_from_env(Backend::Auto, Some("wgpu"));
+        assert_eq!(gpu, Backend::Gpu);
+        assert_eq!(effective_panel_alpha(gpu, 0.55), 0.55);
+
+        let cpu = backend_from_env(Backend::Auto, Some("tiny-skia"));
+        assert_eq!(cpu, Backend::Cpu);
+        assert_eq!(
+            effective_panel_alpha(cpu, 0.55),
+            1.0,
+            "D36：CPU 档面板 α 强制 1.0"
+        );
+    }
+}

crates/app-iced/src/app/boot.rs

@@ -0,0 +1,263 @@
+//! 启动编排：**探测 → 字体 → 打印诊断 → 起 iced**（四步，别把它撑回一坨）。
+//!
+//! ## 三条纪律（每条都对应一次返工）
+//!
+//! 1. **后端起不来时的两条路策略不同**（判据表第 8/9 行）：交互启动换进程重开、取证启动
+//!    （`--screenshot`）拒绝出图 —— 实现与测试都在 [`fallback`]。
+//! 2. **窗口设置只有一个产地**（[`diagnostics::window_settings`]），`[window]` / `[caps]` 两行日志
+//!    从**同一个** `&window::Settings` 取字段。M98 r1 p2-1 的教训：把 `decorations=false` 写进
+//!    格式化串，等于让日志与真实行为可以各走各的（踩坑记录 U1）。
+//! 3. **没测过的就写 `skipped`**，不许拿 `0ms` 冒充实测（[`diagnostics::report_font`] 的 `probe`）。
+//!
+//! 为什么重开必须是**换进程**：Windows 实测本进程里再 `run()` 一次直接 panic
+//! （`iced_winit-0.14.1/src/lib.rs:81` → `Create event loop: RecreationAttempt`）。
+
+use crate::app::diag::diag;
+use std::time::{Duration, Instant};
+
+use iced::Task;
+
+use unlucky_design::color::SchemeFlavor;
+
+use crate::cli::Options;
+use crate::fonts;
+use crate::probe;
+use crate::renderer::{self, acceptance, Decision};
+use crate::theme::Families;
+
+use super::message::Message;
+use super::state::{App, STARTED};
+use super::{MIN_SIZE, WINDOW_SIZE};
+
+mod diagnostics;
+mod fallback;
+mod termux_gpu;
+mod termux_window;
+
+use fallback::{on_failure, respawn, OnFailure};
+
+/// 启动 iced（阻塞到退出）。`--diff` 不走这里，见 `main.rs`。
+pub(crate) fn run(options: Options) -> iced::Result {
+    let _ = STARTED.set(Instant::now());
+    let boot_started = Instant::now();
+
+    // ① 探测（判据取在哪、日志在 `report_boot` 里统一打）
+    // Termux + glibc 构建：装了我们自编的 turnip ICD 就先生效，auto 也能选到 GPU。
+    termux_gpu::enable();
+    let boot = boot_probe(&options);
+    let decision = boot.decision;
+    diagnostics::report_boot(&options, &boot.probe, &decision);
+
+    // ② 字体（`fonts` 自己打两行既有日志；新加的那行在 `report_font` 里）
+    let font_started = Instant::now();
+    let resolved = fonts::resolve();
+    let font_ms = font_started.elapsed();
+    diag!("[font] 求值耗时 {:.0} ms", font_ms.as_secs_f64() * 1000.0);
+    diag!("{}", resolved.describe());
+    if resolved.has_synthetic() {
+        diag!(
+            "[font] 警告：有字重落在「合成加粗」档（观感降级），D28 后半（CDN 字体/按档换字族）要处理"
+        );
+    }
+    let families = resolved.families();
+
+    // ③ 打印（主题来源 + 字体回退链 + 启动耗时）
+    // 截图模式：`--screenshot-theme` > `--theme` > **Light**（唯一取值口 `Options::capture_flavor`）。
+    // **不再有**「等系统主题到达」的闸门——CI 的 xvfb 没有主题会话，等它就是挂死（见 cli 文档）。
+    if options.screenshot.is_some() && options.shot_flavor().is_none() {
+        diag!("[shot] 未指定主题，按 Light 出图（D30 可复现；CI 冒烟依赖这条默认值）");
+    }
+    let flavor = options.capture_flavor().unwrap_or(SchemeFlavor::Light);
+    diagnostics::report_theme(&options, flavor);
+    diagnostics::report_font(
+        resolved.platform,
+        boot.probe_ms,
+        font_ms,
+        boot_started.elapsed(),
+    );
+
+    // ④ 起 iced（失败按判据表第 8/9 行分流；具名原因在分流之前就打到同一个 stderr 上了）
+    let launch_started = Instant::now();
+    let result = match launch(&options, families, flavor, decision.primary) {
+        Err(iced::Error::GraphicsCreationFailed(error)) => {
+            renderer::report_failure(decision.primary, &error);
+            match on_failure(decision, options.screenshot.as_ref()) {
+                Some(OnFailure::Respawn(fallback)) => {
+                    respawn(decision.primary, fallback, &error.to_string())
+                }
+                Some(OnFailure::Refuse) => {
+                    // 取证启动：**拒绝降级出图**（换了后端出的图会让报告撒谎）。
+                    diag!(
+                        "[gpu] 拒绝降级出图：本次是取证启动（--screenshot {}），换后端出的图会撒谎。",
+                        options
+                            .screenshot
+                            .as_ref()
+                            .map_or_else(String::new, |path| path.display().to_string())
+                    );
+                    diag!(
+                        "[gpu] 想用 CPU 出图请显式加 --renderer=cpu / --software-renderer（CI 就是这么跑的）。"
+                    );
+                    Err(iced::Error::GraphicsCreationFailed(error))
+                }
+                None => Err(iced::Error::GraphicsCreationFailed(error)),
+            }
+        }
+        other => other,
+    };
+    let launch_elapsed = launch_started.elapsed();
+
+    diagnostics::report_outcome(
+        &decision,
+        result.as_ref().err().map(|error| {
+            renderer::named_graphics_error(error).unwrap_or_else(|| error.to_string())
+        }),
+        acceptance::failure_via(decision.fallback.is_some(), options.screenshot.is_some()),
+        if options.screenshot.is_some() {
+            "screenshot"
+        } else {
+            "interactive"
+        },
+        launch_elapsed,
+    );
+
+    result
+}
+
+/// 按一次后端启动 iced。`backend` 决定这次写进 `ICED_BACKEND` 的唯一一项。
+fn launch(
+    options: &Options,
+    families: Families,
+    flavor: SchemeFlavor,
+    backend: renderer::Kind,
+) -> iced::Result {
+    std::env::set_var("ICED_BACKEND", backend.env_value());
+
+    let boot_options = options.clone();
+
+    // M98：`ULL_WINDOW_SIZE=1520x900` 覆盖尺寸（矩阵的「最小 / 宽屏」两档靠它，且必须走**真外壳**
+    // ——`pages_demo` example 的标题栏是留白带，出不了「三键位置」那张图）。
+    // Termux：没有环境覆盖时，默认尺寸按 X 屏幕等比自适应（横屏优先），
+    // 失败就退回 1180×760 的验收尺寸。
+    let (default_size, default_source) = termux_window::default_size(
+        (WINDOW_SIZE.width, WINDOW_SIZE.height),
+        (MIN_SIZE.width, MIN_SIZE.height),
+    )
+    .unwrap_or(((WINDOW_SIZE.width, WINDOW_SIZE.height), "default"));
+    let (size, size_source) =
+        acceptance::window_size(default_size, (MIN_SIZE.width, MIN_SIZE.height));
+    let size_source = if size_source == "default" {
+        default_source
+    } else {
+        size_source
+    };
+    let settings = diagnostics::window_settings(size);
+    // 两行日志与开窗用的是**同一个** settings（见模块文档纪律 2）
+    diagnostics::report_window(&settings, options.scale_factor, size_source);
+
+    let application = iced::application(
+        move || {
+            (
+                App::new(boot_options.clone(), families, flavor),
+                Task::done(Message::Boot),
+            )
+        },
+        App::update,
+        App::view,
+    )
+    .title(App::title)
+    .theme(App::theme)
+    .subscription(App::subscription)
+    .default_font(default_font(families))
+    .window(settings);
+
+    match options.scale_factor {
+        Some(scale) => application.scale_factor(move |_| scale).run(),
+        None => application.run(),
+    }
+}
+
+/// [`boot_probe`] 的产物：判据 + 探测到的适配器 + **探测耗时（没测就是 `None`）**。
+///
+/// 为什么把 `Probe` 带出来：`[env]` 的 `gpu=` / `hardware=` 必须是**这一次真枚举到的**结果
+/// （再枚举一遍多花 0.65~1.2 s，还可能给出不同状态）。判据与诊断看同一份数据。
+struct Boot {
+    decision: Decision,
+    probe: probe::Probe,
+    probe_ms: Option<Duration>,
+}
+
+/// 渲染后端探测 + 写 `ICED_BACKEND`，返回判据产物（供 `run` 决定要不要换进程重开）。
+fn boot_probe(options: &Options) -> Boot {
+    // 「上一步失败后重开」的那一次：别再探（会得到同一个结论，然后无限重开）。兜底必须是 None
+    // ——由 `decision::fallback_round` 单点保证。
+    if let Some(kind) = renderer::forced_fallback() {
+        let decision = renderer::fallback_round(kind);
+        std::env::set_var("ICED_BACKEND", kind.env_value());
+        diag!(
+            "[probe] 本次是降级重开（{}={}）：跳过探测 -> ICED_BACKEND={}",
+            renderer::FALLBACK_ENV,
+            kind.env_value(),
+            kind.env_value()
+        );
+        diag!("[probe] {}", decision.describe());
+        // 验收要 `[env]` 里的真实适配器：这一轮**也枚举一次，并如实计时**（没计时就 `None`
+        // ⇒ 日志写 `probe=skipped`，不写 0ms）。
+        let (probe, probe_ms) = if acceptance::enabled() {
+            let started = Instant::now();
+            let probe = probe::Probe::run();
+            (probe, Some(started.elapsed()))
+        } else {
+            (probe::Probe::default(), None)
+        };
+        return Boot {
+            decision,
+            probe,
+            probe_ms,
+        };
+    }
+
+    // 只有 `auto` 需要探测（`cpu`/`gpu` 的决策与硬件无关，枚举 13 个适配器本机要 0.65~1.2 s）。
+    // 验收模式例外：`[env]` 那行要 GPU 名，不管请求是哪个后端。
+    let needs_probe = options.backend == crate::Backend::Auto || acceptance::enabled();
+    let probe_started = Instant::now();
+    let probe = if needs_probe {
+        probe::Probe::run()
+    } else {
+        probe::Probe::default()
+    };
+    let probe_ms = needs_probe.then(|| probe_started.elapsed());
+
+    // `ULL_PREFLIGHT=1` 时先自己验一遍 wgpu（判据表第 7 行）；默认不跑，见 preflight 模块文档。
+    let preflight = renderer::preflight::run_if_requested();
+    let decision = probe::apply_with_preflight(options.backend, &probe, preflight.as_ref());
+
+    if cfg!(feature = "gpu") {
+        match probe_ms {
+            Some(elapsed) => diag!(
+                "[probe] 探测耗时 {:.0} ms（wgpu 实例 + 全后端适配器枚举）",
+                elapsed.as_secs_f64() * 1000.0
+            ),
+            None => diag!(
+                "[probe] 探测耗时 跳过（--renderer={} 与硬件无关，未枚举）",
+                options.backend.name()
+            ),
+        }
+    }
+    Boot {
+        decision,
+        probe,
+        probe_ms,
+    }
+}
+
+/// 默认字体（正文档解析出来的族）。
+fn default_font(families: Families) -> iced::Font {
+    iced::Font {
+        family: iced::font::Family::Name(families.text),
+        ..iced::Font::DEFAULT
+    }
+}
+
+#[cfg(test)]
+#[path = "boot/tests.rs"]
+mod tests;

crates/app-iced/src/app/boot/diagnostics.rs

@@ -0,0 +1,115 @@
+//! 启动阶段的**验收诊断编排**：把 `app/boot.rs` 的 `run()` 收成「探测 → 字体 → 打印 → 起 iced」。
+//!
+//! ## 为什么单独一个文件（M98 r1 p2-1 的根因）
+//!
+//! 第一版把 `[window] requested … resizable=true decorations=false transparent=false` 直接写在
+//! 格式化串里，而 `boot.rs` 给窗口的 `settings` 是另一处常量 —— 两者**没有任何绑定**。定向变异
+//! 把 `settings.decorations` 改成 `true`，371 个测试全绿，而验收包里 `[caps] decorations=true` 与
+//! `[window] decorations=false` 会互相矛盾（踩坑记录 U1：常量冒充观测结果）。
+//!
+//! 现在：窗口设置由 [`window_settings`] **一处**产生，日志由 [`report_window`] 从**同一个
+//! `&window::Settings`** 取字段。钉死它的守门测试在 `boot/tests.rs`（`window_settings_*`）。
+//!
+//! 另一件事：所有「跑没跑」都要能如实说。降级重开那一轮没计时就写 `probe=skipped`，
+//! 不许拿 `0ms` 冒充一次实测（M98 r1 p3-1）。
+
+use std::time::Duration;
+
+use iced::window;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_design::typography::Platform as FontPlatform;
+
+use crate::cli::Options;
+use crate::probe::Probe;
+use crate::renderer::{acceptance, Decision};
+
+use super::MIN_SIZE;
+use crate::app::APP_TITLE;
+
+/// 产品窗口设置（**唯一产地**：`launch()` 用它开窗，`[window]` / `[caps]` 从它取字段）。
+///
+/// `ULL_WINDOW_SIZE` 的覆盖在 `boot.rs` 解析成 `size` 后从这里进来 —— 日志与真窗口永远同源。
+pub(super) fn window_settings(size: (f32, f32)) -> window::Settings {
+    window::Settings {
+        size: iced::Size::new(size.0, size.1),
+        min_size: Some(MIN_SIZE),
+        // 自绘三键（M93）：窗口**不许**带系统装饰，否则 macOS 上会出现原生标题栏 + 自绘三键两套。
+        //
+        // M182：这一行**同时**是「macOS 四角是直角」的原因——winit 见到 `decorations: false`
+        // 会给出 `NSWindowStyleMask::Borderless`（没有 `Titled`），而窗口服务器只给 titled 窗
+        // 做圆角裁剪。链条与「要不要迁移原生标题栏」的口径写在 `platform::macos` 的模块文档里，
+        // 改动这一行之前先读那一页（迁移必须连同撤掉自绘三键一起做，否则两套控件打架）。
+        decorations: false,
+        resizable: true,
+        // M93 / D36：整窗 α 需要 `WS_EX_LAYERED`，但这里给不了——`window::Settings` 没有扩展样式
+        // 字段，写它只有 `Get/SetWindowLongPtrW`（`unsafe`，全仓只允许出现在
+        // `platform/win32/transparency.rs`）。所以 α 下发在拿到句柄之后（`Message::WindowHandle`）。
+        transparent: false,
+        ..window::Settings::default()
+    }
+}
+
+/// `[window] requested` + `[caps]` 两行，**都从同一个 `settings` 取**（不给手抄字面量的机会）。
+pub(super) fn report_window(settings: &window::Settings, scale: Option<f32>, size_source: &str) {
+    let facts = acceptance::WindowFacts::from_settings(settings);
+    acceptance::report_window(&facts, scale, size_source, Some(APP_TITLE));
+    acceptance::report_caps(
+        std::env::current_exe().ok().as_deref(),
+        facts.transparent,
+        facts.resizable,
+        facts.decorations,
+    );
+}
+
+/// 第一段：`[acceptance] on` + `[backend] plan` +（验收模式）`[env]` / `[i18n]`。
+pub(super) fn report_boot(options: &Options, probe: &Probe, decision: &Decision) {
+    if acceptance::enabled() {
+        acceptance::announce();
+    }
+    acceptance::report_backend_plan(decision, options.backend);
+    if acceptance::enabled() {
+        acceptance::report_startup(probe, options.scale_factor, options.screenshot.is_some());
+    }
+}
+
+/// 第二段：`[font] chain` + `[perf] boot`（都要 `ULL_ACCEPTANCE=1`）。
+///
+/// `probe = None` = 这一轮**没有探测**（既不是 `auto` 也没开验收）⇒ 打 `probe=skipped`。
+pub(super) fn report_font(
+    platform: FontPlatform,
+    probe: Option<Duration>,
+    font: Duration,
+    to_run: Duration,
+) {
+    if acceptance::enabled() {
+        acceptance::report_font_chain(platform);
+        acceptance::report_perf_boot(probe, font, to_run);
+    }
+}
+
+/// 第三段：`[theme]`（恒开：它解释的是「这次主题凭什么是这个」）。
+pub(super) fn report_theme(options: &Options, flavor: SchemeFlavor) {
+    let (source, follows) = acceptance::theme_source(
+        options.screenshot_theme.is_some(),
+        options.theme.is_some(),
+        options.screenshot.is_some(),
+    );
+    let explicit = (!follows).then_some(if flavor.is_dark() { "dark" } else { "light" });
+    acceptance::report_theme(source, explicit, follows);
+}
+
+/// 第四段：`[backend] final`（恒开）+ `[perf] session`（验收模式）。
+///
+/// `error` = 具名失败原因（`None` = 起来了）；`via` 见 `renderer::acceptance::failure_via`。
+/// `refuse` / `none` 两条路**什么都没跑起来** ⇒ `final=none`；只有 `respawn` 才有「换到哪个
+/// 后端」可言（那一格是兜底名，子进程自己还会再打一遍自己的 plan/final）。
+pub(super) fn report_outcome(
+    decision: &Decision,
+    error: Option<String>,
+    via: &str,
+    mode: &str,
+    elapsed: Duration,
+) {
+    acceptance::report_outcome(decision, error.as_deref(), via, mode, elapsed);
+}

crates/app-iced/src/app/boot/fallback.rs

@@ -0,0 +1,121 @@
+//! 起步后端失败后的**兜底/重开**一簇：判据、进程环境交接、`respawn`、退出码透传。
+//!
+//! 从 `app/boot.rs` 拆出来的理由：这一簇**与启动编排零耦合**，但已有 5 条测试，而且它是
+//! M97 判据表第 8/9 行的落点。`boot.rs` 那边只负责「什么时候调它」。
+//!
+//! ## 为什么必须换进程（别改回进程内重试）
+//!
+//! Windows 实测本进程里再 `run()` 一次直接 panic
+//! （`iced_winit-0.14.1/src/lib.rs:81` → `Create event loop: RecreationAttempt`），winit 一个进程
+//! 只能建一次事件循环。
+
+use crate::app::diag::diag;
+use crate::renderer::Decision;
+use crate::renderer::{self, acceptance, Kind};
+
+/// 起步后端失败后的去向（判据表第 8 行 vs 第 9 行——**两条路策略不同，别合成一条**）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum OnFailure {
+    /// 交互启动：安全网优先，换进程用这个后端重开。
+    Respawn(Kind),
+    /// 取证启动：红着退出，**不出图**。
+    Refuse,
+}
+
+/// 纯判据：起步后端失败时走哪条路。
+///
+/// `evidence` 非空 = 本次是取证启动（带 `--screenshot`）；返回 `None` = 没有兜底可用
+/// （`--renderer=cpu` / 未编 wgpu），原样把错误交回去。抽成纯函数只为一个理由：这条分支以前
+/// **没有任何测试**，`respawn` / `Refuse` 两条路可以被静默改反（M97 r1 p2-1 就是这么测出来的）。
+pub(super) fn on_failure(
+    decision: Decision,
+    evidence: Option<&std::path::PathBuf>,
+) -> Option<OnFailure> {
+    let fallback = decision.fallback?;
+    Some(match evidence {
+        Some(_) => OnFailure::Refuse,
+        None => OnFailure::Respawn(fallback),
+    })
+}
+
+/// 降级重开要传给子进程的环境变量（**两条缺一不可**）。
+///
+/// ① `ICED_BACKEND`：让子进程直接用 `fallback` 跑。
+/// ② [`renderer::FALLBACK_ENV`]：**防无限重开的闸门**——子进程见它就必须跳过探测
+///    （`boot_probe` 的第一个分支），否则会算出同一个结论、再失败、再 respawn。
+///
+/// 抽成纯函数是为了让「漏传其中之一」变成**测试能抓到**的错误：两条都是静默失效型
+/// （漏 ① 重开又跑一遍 wgpu、漏 ② 无限重开），线上极难看出来。
+pub(super) fn fallback_env(fallback: Kind) -> [(&'static str, &'static str); 2] {
+    [
+        ("ICED_BACKEND", fallback.env_value()),
+        (renderer::FALLBACK_ENV, fallback.env_value()),
+    ]
+}
+
+/// 安全网：起一个**新进程**用 `fallback` 后端重开，然后带着它的退出码退出。
+///
+/// 只在**交互启动**时走到这里（取证启动宁可红着退出也不换后端出图）；子进程看到
+/// [`renderer::FALLBACK_ENV`] 必须跳过探测，否则无限递归重开（闸门在 `boot_probe` 入口）。
+pub(super) fn respawn(failed: Kind, fallback: Kind, error: &str) -> ! {
+    let exe = std::env::current_exe().unwrap_or_else(|err| {
+        diag!("[gpu] 降级重开失败：拿不到自身路径（{err}）");
+        std::process::exit(exit_code(None));
+    });
+    diag!(
+        "[gpu] 降级 → {}（{} 已失败，原因见上两行；换一个进程重开：winit 不允许同进程建两次事件循环）。\
+         下一次的日志从 `[probe] 本次是降级重开` 开始。",
+        fallback.name(),
+        failed.name()
+    );
+    // `[backend] final` 一行把「哪个后端失败了、去了哪、为什么」收在一起（可 grep 的单一结论行）。
+    // 这里 `final=` 装的是**兜底**（进程即将带着它重开）；`via=respawn` 说明它是换进程去的。
+    acceptance::report_backend_failed(failed, Some(fallback), Some(fallback), "respawn", error);
+
+    let status = fallback_command(&exe, std::env::args_os().skip(1), fallback).status();
+
+    // 退出码**透传**子进程的：上层脚本/CI 靠它判断成败。写错的失效方式是「安静地给出一个错
+    // 结论」——不崩、不静默降级、不无限重开，只是让 CI 把失败当成功。
+    let code = match status {
+        Ok(status) => exit_code(status.code()),
+        Err(err) => {
+            diag!("[gpu] 降级重开失败：{err}");
+            exit_code(None)
+        }
+    };
+    std::process::exit(code)
+}
+
+/// 子进程退出码 → 本进程退出码。
+///
+/// `None` = 子进程被信号杀死（只有 Unix）：走兜底码而**不是** panic、也不是 0——上层判据是
+/// 「非零 = 失败」，「拿不到退出码」和「退出码是某个非零值」对脚本是一回事。
+pub(super) fn exit_code(code: Option<i32>) -> i32 {
+    /// 重开失败 / 拿不到退出码时的兜底码（与 `main` 的「参数或运行错误」一致）。
+    const RESPAWN_FAILED: i32 = 2;
+    code.unwrap_or(RESPAWN_FAILED)
+}
+
+/// 构造降级重开的子进程命令（**可测**：program / argv / env 都能在测试里断言）。
+///
+/// `program` / `args` 是参数而不是在函数里读 `std::env`，唯一目的是让测试能喂假命令
+/// （`cmd /c exit 7` / `sh -c "exit 7"`）来验退出码透传——真用 `current_exe()` 就没法测。
+///
+/// 三路 stdio **显式**继承：子进程日志必须和父进程同一路输出，否则验收只抓到父进程那两行具名
+/// 错误。`Command` 没有 stdio 的 getter（stable 没有），所以这条只能靠真跑一次证明。
+pub(super) fn fallback_command(
+    program: &std::path::Path,
+    args: impl IntoIterator<Item = std::ffi::OsString>,
+    fallback: Kind,
+) -> std::process::Command {
+    // 子进程就是本 GUI exe 自己（PE Subsystem=2，本来就不会分到控制台），所以这一处今天闪不了；
+    // 走 `quiet` 是为了让「app-iced 里除 opener 外不留裸构造」这条规则整体可被守卫钉住——将来
+    // 某天把降级重开换成控制台辅助程序时，不会从这里漏出一块黑框（M217）。
+    let mut command = unlucky_core::platform::child::quiet(program);
+    command.args(args).envs(fallback_env(fallback));
+    command
+        .stdin(std::process::Stdio::inherit())
+        .stdout(std::process::Stdio::inherit())
+        .stderr(std::process::Stdio::inherit());
+    command
+}

crates/app-iced/src/app/boot/termux_gpu.rs

@@ -0,0 +1,58 @@
+//! Termux 上自动启用随附的 Vulkan ICD（glibc 侧 turnip，`ull_freedreno.json`）。
+//!
+//! 背景：Termux 软件源里的 glibc Mesa（24.2.6）不认识 Adreno 840，硬件 GPU 需要用
+//! `packaging/docs/termux-glibc-build.md` §5 里自编的 Mesa 26（KGSL）。驱动装在
+//! `$PREFIX/glibc/share/vulkan/icd.d/ull_freedreno.json` 时，这里在探测之前把它设进
+//! `VK_ICD_FILENAMES` / `VK_DRIVER_FILES`，让 `auto` 也能选到 GPU。
+//!
+//! 只在 **glibc 构建**（`target_os = "linux"`）上生效：Termux 原生（bionic）构建的
+//! `target_os = "android"`，glibc 驱动对它没有意义。用户显式设了这两个变量时不覆盖。
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::platform::paths::ProcessEnv;
+use unlucky_core::platform::termux;
+
+/// 随附 ICD 的相对路径（相对 `$PREFIX`）。
+const ICD_REL: &str = "glibc/share/vulkan/icd.d/ull_freedreno.json";
+
+/// 在 GPU 探测之前调用：装了就启用，没装就什么都不做。
+pub(super) fn enable() {
+    if !cfg!(target_os = "linux") {
+        return;
+    }
+    if std::env::var_os("VK_ICD_FILENAMES").is_some()
+        || std::env::var_os("VK_DRIVER_FILES").is_some()
+    {
+        return;
+    }
+    let Some(prefix) = termux::prefix(&ProcessEnv) else {
+        return;
+    };
+    let icd = icd_path(&prefix);
+    if icd.is_file() {
+        std::env::set_var("VK_ICD_FILENAMES", &icd);
+        std::env::set_var("VK_DRIVER_FILES", &icd);
+    }
+}
+
+/// `$PREFIX` 下随附 ICD 的路径（纯函数，测试用）。
+fn icd_path(prefix: &Path) -> PathBuf {
+    prefix.join(ICD_REL)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::icd_path;
+
+    #[test]
+    fn icd_path_is_under_the_glibc_prefix() {
+        let path = icd_path(std::path::Path::new("/data/data/com.termux/files/usr"));
+        assert_eq!(
+            path,
+            std::path::PathBuf::from(
+                "/data/data/com.termux/files/usr/glibc/share/vulkan/icd.d/ull_freedreno.json"
+            )
+        );
+    }
+}

crates/app-iced/src/app/boot/termux_window.rs

@@ -0,0 +1,117 @@
+//! Termux / termux-x11 下的窗口尺寸自适应（横屏优先）。
+//!
+//! 验收尺寸（1180×760）是 D30 的硬要求，不能改；但手机显示器可能横屏远大于它
+//! （例如 2066×1272）或竖屏略小。这里只在**运行时**把「默认尺寸」换成按当前 X
+//! 屏幕算出的最大等比矩形；`ULL_WINDOW_SIZE` 覆盖仍然优先（见 `acceptance::window_size`）。
+//!
+//! 只在 Termux + 有 `DISPLAY` 时探测；`xdpyinfo` 缺失/解析失败一律回默认，不影响其它平台。
+
+use unlucky_core::platform::paths::ProcessEnv;
+use unlucky_core::platform::termux;
+
+/// 屏幕四周留白（像素）。
+const MARGIN: f32 = 32.0;
+/// 最大放大倍数：大屏上也不把窗口撑成巨屏。
+const MAX_SCALE: f32 = 2.0;
+/// `xdpyinfo` 里尺寸那一行的前缀。
+const DIMENSIONS_PREFIX: &str = "dimensions:";
+
+/// Termux 上的默认窗口尺寸：按 X 屏幕等比放大/缩小，失败返回 `None`（用调用方默认）。
+///
+/// `default` / `min` 由调用方传入（[`super::WINDOW_SIZE`] / [`super::MIN_SIZE`]），
+/// 这里不复制常量。
+#[must_use]
+pub(super) fn default_size(
+    default: (f32, f32),
+    min: (f32, f32),
+) -> Option<((f32, f32), &'static str)> {
+    if !termux::is_termux(&ProcessEnv) || std::env::var_os("DISPLAY").is_none() {
+        return None;
+    }
+    let screen = x_screen_size()?;
+    Some((fit_screen(default, min, screen), "termux-screen"))
+}
+
+/// 在 `screen` 里放一个保持 `default` 宽高比的最大矩形（保留留白，不突破 `min`）。
+#[must_use]
+pub(super) fn fit_screen(default: (f32, f32), min: (f32, f32), screen: (f32, f32)) -> (f32, f32) {
+    if screen.0 <= 0.0 || screen.1 <= 0.0 || default.0 <= 0.0 || default.1 <= 0.0 {
+        return default;
+    }
+    let available = (
+        (screen.0 - MARGIN * 2.0).max(1.0),
+        (screen.1 - MARGIN * 2.0).max(1.0),
+    );
+    let scale = (available.0 / default.0)
+        .min(available.1 / default.1)
+        .min(MAX_SCALE);
+    let width = (default.0 * scale).max(min.0).min(screen.0);
+    let height = (default.1 * scale).max(min.1).min(screen.1);
+    (width, height)
+}
+
+/// 当前 X 屏幕尺寸（`xdpyinfo` 的 `dimensions: WxH pixels`）。
+fn x_screen_size() -> Option<(f32, f32)> {
+    // 非 Windows 上 `quiet` 是原样返回（POSIX 没有「spawn 就新开一个终端」这回事）；走它是为了
+    // 不在整棵 `crates/` 的子进程守卫里开一个「Termux 专用」例外（M217）。
+    let output = unlucky_core::platform::child::quiet("xdpyinfo")
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let text = String::from_utf8_lossy(&output.stdout);
+    let line = text
+        .lines()
+        .find(|line| line.trim_start().starts_with(DIMENSIONS_PREFIX))?;
+    let value = line.split_whitespace().nth(1)?;
+    let (width, height) = value.split_once('x')?;
+    Some((width.parse().ok()?, height.parse().ok()?))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::fit_screen;
+
+    const DEFAULT: (f32, f32) = (1180.0, 760.0);
+    const MIN: (f32, f32) = (880.0, 560.0);
+
+    fn close(actual: (f32, f32), expected: (f32, f32)) {
+        assert!(
+            (actual.0 - expected.0).abs() < 0.5 && (actual.1 - expected.1).abs() < 0.5,
+            "expected {expected:?}, got {actual:?}"
+        );
+    }
+
+    #[test]
+    fn landscape_screen_scales_up_keeping_aspect() {
+        // 2066×1272：留白后 2002×1208，高度是瓶颈 → 1875.6×1208。
+        close(
+            fit_screen(DEFAULT, MIN, (2066.0, 1272.0)),
+            (1875.58, 1208.0),
+        );
+    }
+
+    #[test]
+    fn portrait_screen_still_fits_width() {
+        // 1272×2066：宽度是瓶颈 → 1208×778。
+        close(fit_screen(DEFAULT, MIN, (1272.0, 2066.0)), (1208.0, 778.03));
+    }
+
+    #[test]
+    fn huge_screen_is_capped_at_two_times() {
+        close(fit_screen(DEFAULT, MIN, (4000.0, 3000.0)), (2360.0, 1520.0));
+    }
+
+    #[test]
+    fn tiny_screen_never_goes_below_min_or_overflow() {
+        let (width, height) = fit_screen(DEFAULT, MIN, (800.0, 600.0));
+        assert_eq!(width, 800.0, "宽度受屏幕限制");
+        assert_eq!(height, 560.0, "高度不小于最小尺寸");
+    }
+
+    #[test]
+    fn invalid_screen_falls_back_to_default() {
+        assert_eq!(fit_screen(DEFAULT, MIN, (0.0, 0.0)), DEFAULT);
+    }
+}

crates/app-iced/src/app/boot/tests.rs

@@ -0,0 +1,271 @@
+//! `app/boot.rs` 的单元测试 + **变异验证说明**（M97 r1）。
+//!
+//! 放独立文件（同 `pages/harness/tests.rs`）是为了让 `boot.rs` 留在 400 行内。
+
+//! ## 变异验证怎么做（M97 r1 的教训，改测试前先读这段）
+//!
+//! 这批测试的价值不是「跑绿了」，而是「把实现改坏会红」。做变异时**只在目标函数体内替换**，
+//! 并且把测试里的同一字面量排除在外：
+//!
+//! ```text
+//! # // 示意（真实脚本是一次性的，没入库）
+//! def in_body(path, marker, changes):
+//!     """按函数体范围替换。**不能**全局 sed：那会连测试期望里的同一字面量一起改掉，
+//!     于是实现和断言被换成同一个错值 ⇒ 测试照样绿 ⇒ 验证的是变异脚本自己。"""
+//! ```
+//!
+//! M97 r1 第一次跑变异时，M1/M2/M3 三个变异「照样绿」——不是测试弱，是脚本用全局 `sed`
+//! 把断言一起改了。这类假绿最阴：变异验证本来是我们判断「测试够不够」的终极手段，
+//! 手段本身假绿时，它还会附赠「已验证」的强信心。
+
+use super::fallback::*;
+use super::*;
+
+use crate::renderer::acceptance::WindowFacts;
+use crate::renderer::decision;
+use crate::renderer::Kind;
+use std::ffi::{OsStr, OsString};
+use std::path::Path;
+
+fn probe(device_type: &'static str) -> crate::Probe {
+    crate::Probe {
+        adapters: vec![crate::probe::AdapterSummary {
+            name: "adapter".to_owned(),
+            device_type,
+        }],
+        hardware: !matches!(device_type, "Cpu" | "Other"),
+    }
+}
+
+/// **降级重开到底传了什么**（M97 r1 p2-1 的守门）。
+///
+/// 抓得住：`fallback_env` 少写/写错任一条——两条都是静默失效型：
+/// 漏 `ICED_BACKEND` ⇒ 子进程又去试 wgpu（白开一次窗）；漏 `ULL_GPU_FALLBACK` ⇒ **无限重开**。
+/// 抓不住：`Command` 本身没被建起来（那要真起进程，见 §「Windows 实测」）。
+#[test]
+fn fallback_env_carries_the_backend_and_the_gate() {
+    for fallback in [Kind::TinySkia, Kind::Wgpu] {
+        let env = fallback_env(fallback);
+        assert_eq!(
+            env.len(),
+            2,
+            "就这两条，多一条少一条都要在这里改文档：{env:?}"
+        );
+        assert!(
+            env.contains(&("ICED_BACKEND", fallback.env_value())),
+            "子进程必须直接用 {fallback:?} 跑，实际 {env:?}"
+        );
+        assert!(
+            env.contains(&(renderer::FALLBACK_ENV, fallback.env_value())),
+            "缺防无限重开的闸门 {FALLBACK_ENV:?}，实际 {env:?}",
+            FALLBACK_ENV = renderer::FALLBACK_ENV
+        );
+    }
+}
+
+/// 闸门的另一半：子进程那一轮的决策**不能再有兜底**，否则失败后继续 respawn ⇒ 无限递归。
+///
+/// 抓得住：`fallback_round` 的 `fallback` 被写成 `Some(..)`（自杀式循环）。
+/// 抓不住：`forced_fallback()` 没被 `boot_probe` 调用（那是环境变量的读，见下一条的说明）。
+#[test]
+fn fallback_round_never_degrades_again() {
+    for kind in [Kind::TinySkia, Kind::Wgpu] {
+        let decision = decision::fallback_round(kind);
+        assert_eq!(decision.primary, kind);
+        assert_eq!(
+            decision.fallback, None,
+            "降级重开那一次不许再有兜底，否则会无限递归重开"
+        );
+        assert_eq!(decision.reason, "fallback-after-failure");
+    }
+}
+
+/// 判据表第 8 行 vs 第 9 行：**交互降级 / 取证拒绝**，两条路的策略不同。
+///
+/// 抓得住：`--screenshot` 分支被改回「也降级」（那正是 M97 要杀的「取证工具自己换后端」）。
+/// 抓不住：`screenshot` 传进来的时机（那是 `run()` 的接线，见 Windows 实测记录）。
+#[test]
+fn evidence_start_refuses_instead_of_degrading() {
+    let auto = decision::decide(crate::Backend::Auto, &probe("IntegratedGpu"), true);
+    let evidence = std::path::PathBuf::from("out.png");
+
+    assert_eq!(
+        on_failure(auto, Some(&evidence)),
+        Some(OnFailure::Refuse),
+        "取证启动 + wgpu 起不来 ⇒ 拒绝出图"
+    );
+    assert_eq!(
+        on_failure(auto, None),
+        Some(OnFailure::Respawn(Kind::TinySkia)),
+        "交互启动 + wgpu 起不来 ⇒ 换进程降级"
+    );
+}
+
+/// **构造侧**：argv 原样透传、两组 env 都在、program 就是传进来的那个。
+///
+/// 抓得住：重开时丢掉用户参数（`--screenshot` / `--screen` / `--data-dir` 全没了，
+/// 子进程会按默认参数跑，那是最难查的一种「重开后行为变了」）、env 少传（M97 r1 的 p2-1）。
+/// 抓不住：stdio 继承（`Command` 没有 stdio getter，只能真跑一次，见 `fallback_command` 的注释）。
+#[test]
+fn fallback_command_passes_program_argv_and_envs() {
+    let args = ["--renderer=auto", "--screenshot", "out.png"];
+    let command = fallback_command(
+        Path::new("unlucky-launcher-iced"),
+        args.iter().map(OsString::from),
+        Kind::TinySkia,
+    );
+
+    assert_eq!(
+        command.get_program(),
+        OsStr::new("unlucky-launcher-iced"),
+        "program 必须是传进来的那个（生产里是 current_exe）"
+    );
+    assert_eq!(
+        command.get_args().collect::<Vec<_>>(),
+        args.iter().map(OsStr::new).collect::<Vec<_>>(),
+        "argv 必须原样透传，一条不漏、顺序不变"
+    );
+    let envs: Vec<_> = command.get_envs().collect();
+    for (key, value) in fallback_env(Kind::TinySkia) {
+        assert!(
+            envs.contains(&(OsStr::new(key), Some(OsStr::new(value)))),
+            "重开命令缺 {key}={value}，实际 {envs:?}"
+        );
+    }
+}
+
+/// **执行侧**：子进程退出 7 → 父进程拿到 7（不是 0、不是自己造的值）。
+///
+/// 抓得住：`exit_code` 被改成恒 0 / 恒 1 / 写成 `status.success().into()`。
+/// 抓不住：生产里 `current_exe()` 那个 program（测试用假命令，见 `fallback_command` 注释）。
+#[test]
+fn fallback_command_really_passes_the_child_exit_code() {
+    #[cfg(windows)]
+    let (program, args) = ("cmd", vec!["/c", "exit", "7"]);
+    #[cfg(unix)]
+    let (program, args) = ("sh", vec!["-c", "exit 7"]);
+
+    let status = fallback_command(
+        Path::new(program),
+        args.iter().map(OsString::from),
+        Kind::TinySkia,
+    )
+    .status()
+    .expect("假子进程必须能起来");
+    assert_eq!(
+        exit_code(status.code()),
+        7,
+        "子进程退出 7，父进程必须透传 7；{status:?}"
+    );
+}
+
+/// 子进程**被信号杀死**（`code()` 为 `None`）：走兜底码，不 panic、不当成功。
+///
+/// 这是纯函数测试，所以在 Windows 上也能跑（真造一个信号死亡的 `ExitStatus`
+/// 需要 `ExitStatusExt`，只有 Unix 有；而这里测的正是「拿不到码」那一刻的行为）。
+#[test]
+fn signal_death_falls_back_to_a_nonzero_code() {
+    assert_eq!(exit_code(Some(0)), 0, "成功必须透传 0");
+    assert_eq!(exit_code(Some(7)), 7);
+    let fallback = exit_code(None);
+    assert_ne!(fallback, 0, "拿不到退出码绝不能当成功");
+    assert_eq!(fallback, 2, "兜底码与 main 的「参数或运行错误」一致");
+}
+
+/// 没有兜底可用的两行（强制 CPU / 未编 wgpu）：失败就原样把错误交回去，不许 respawn。
+#[test]
+fn no_fallback_means_no_respawn() {
+    let cpu = decision::decide(crate::Backend::Cpu, &probe("IntegratedGpu"), true);
+    let evidence = std::path::PathBuf::from("out.png");
+    assert_eq!(cpu.fallback, None);
+    assert_eq!(on_failure(cpu, None), None);
+    assert_eq!(
+        on_failure(cpu, Some(&evidence)),
+        None,
+        "强制 CPU 也不该走到「拒绝降级」那条提示上（它压根没想上 GPU）"
+    );
+
+    let not_compiled = decision::decide(crate::Backend::Auto, &probe("IntegratedGpu"), false);
+    assert_eq!(on_failure(not_compiled, None), None);
+}
+
+/// **窗口设置就是验收日志里那三个字段的来源**（M98 r1 p2-1 的守门）。
+///
+/// 抓得住：把 `decorations` 改回 `true`（自绘三键退回系统装饰）、把 `resizable` / `transparent`
+/// 打开 —— 这三种改动都会让 `[window]` 与 `[caps]` 两行与代码自相矛盾，而在此之前**371 个测试
+/// 全绿**（复审 M6 变异实证）。现在它们必须红在这里。
+/// 抓不住：winit 是否真按这些设置建窗（那要真机看窗口，见判据表「谁能验证」列）。
+#[test]
+fn window_settings_match_what_the_acceptance_logs_claim() {
+    let settings = diagnostics::window_settings((1180.0, 760.0));
+
+    assert!(
+        !settings.decorations,
+        "M93 自绘三键：窗口不能带系统装饰（否则 macOS 上会出现两套标题栏）"
+    );
+    assert!(
+        settings.resizable,
+        "验收要验「能否缩放」，窗口必须声明可缩放"
+    );
+    assert!(
+        !settings.transparent,
+        "整窗透明只在 win32 拿到句柄后下发（D36），窗口创建侧不许打开它"
+    );
+    assert_eq!(
+        settings.min_size,
+        Some(MIN_SIZE),
+        "最小尺寸档（880×560）是矩阵的一格，不能被改动"
+    );
+
+    // 日志确实从上面这个 settings 取值（而不是另抄一份字面量）
+    let facts = WindowFacts::from_settings(&settings);
+    let line = crate::renderer::acceptance::window_text(
+        &facts,
+        None,
+        "default",
+        Some(super::super::APP_TITLE),
+    );
+    assert!(line.contains("resizable=true"), "{line}");
+    assert!(line.contains("decorations=false"), "{line}");
+    assert!(line.contains("transparent=false"), "{line}");
+    assert!(line.contains("size=1180x760"), "{line}");
+    assert!(line.contains("min=880x560"), "{line}");
+
+    // 抽字段这一步必须**忠实**：拿一份处处相反的 settings 进来，facts 必须跟着反
+    // （抓的是「from_settings 里又写死一份常量」这条回退路 —— M98 r1 M7 变异实证它当年漏抓）
+    let odd = iced::window::Settings {
+        size: iced::Size::new(640.0, 480.0),
+        min_size: None,
+        decorations: true,
+        resizable: false,
+        transparent: true,
+        ..iced::window::Settings::default()
+    };
+    assert_eq!(
+        WindowFacts::from_settings(&odd),
+        WindowFacts {
+            size: (640.0, 480.0),
+            min: None,
+            resizable: false,
+            decorations: true,
+            transparent: true,
+        },
+        "from_settings 必须逐字段搬运，不能在内部再写死一份常量"
+    );
+
+    // 反向：把事实翻个身，日志必须跟着变（证明没有第二份真值）
+    let flipped = WindowFacts {
+        decorations: true,
+        ..facts
+    };
+    let line = crate::renderer::acceptance::window_text(
+        &flipped,
+        None,
+        "default",
+        Some(super::super::APP_TITLE),
+    );
+    assert!(
+        line.contains("decorations=true"),
+        "日志必须跟着 settings 走：{line}"
+    );
+}

crates/app-iced/src/app/diag.rs

@@ -0,0 +1,169 @@
+//! 启动期诊断行的**双写**：stderr + `<.ULL>/logs/launcher.log`（M188）。
+//!
+//! ## 为什么要有这一层
+//!
+//! 双击启动的 GUI 进程**没有 stderr 去向**（Windows 上根本没有控制台）。此前 `[font]` /
+//! `[probe]` / `[theme]` / `[appearance]` / `[gpu]` 这些诊断只走 `eprintln!`，于是「启动器视角
+//! 到底发生了什么」在事故之后一个字都不剩——用户投诉的「只有一个安装日志」有一半是它。
+//!
+//! 现在这些行同时进 `launch::launcher_log`：
+//!
+//! ```text
+//! diag!("[font] 求值耗时 {:.0} ms", ms)   →  stderr: [font] 求值耗时 12 ms
+//!                                          →  launcher.log: 2026-… [font] 求值耗时 12 ms
+//! ```
+//!
+//! scope 就是行首那个 `[tag]`，所以日志行与老用法**长得一样**，`grep '\[gpu\]'` 仍然好使。
+//!
+//! ## 哪些行进日志、哪些只进 stderr
+//!
+//! 判据（M188 复审后收紧成这一句）：**逐帧度量不接；显式取证开关与一次性事故行可接。**
+//!
+//! | 进日志 | 只进 stderr |
+//! |---|---|
+//! | 启动编排（探测结论 / 字体重建 / 主题来源 / 后端最终值 / 降级重开） | **验收与出图矩阵的逐帧度量**：`[window]` / `[perf]` / `[caps]` / `[theme] source=`（`renderer::acceptance/**`，一次启动上百行） |
+//! | **一次性事故行**：`[gpu] <backend> 初始化失败（具名）` / `[gpu] 失败详情（具名）`（`renderer::report_failure`）、`[gpu] iced_wgpu: …Selected: AdapterInfo…`（`log_bridge`）、`[probe] request=… -> ICED_BACKEND=…`（`probe::apply_with_preflight`）、`[gpu-preflight]`（`ULL_PREFLIGHT=1`） | 组件几何探针的断言输出（`components/**` 的 `[feedback-probe]` / gallery 页面里的 `[gallery]`） |
+//! | 用户动作的结果（打开目录、写设置失败、更新忽略/应用、语言没落盘） | 每条日志行的正文里再套一层括号（不是标签，见 [`split_scope`]） |
+//! | 显式开关下的一次性行：`[tick]`（`ULL_TICK_TRACE=1`，≈1 行/秒 ≈ 4.8 小时才滚一次）、`[shot]` 的通道提示 | — |
+//!
+//! 为什么逐帧行不许接：`launcher.log` 有 1 MiB 上限（滚成 `launcher.1.log`，只留一份），
+//! 逐帧写会在几分钟内把「事故现场」冲掉。反过来，`report_failure` 那两行**就是**事故本体——
+//! 双击启动没有 stderr，把它们留在 stderr 等于在最该有日志的路径上什么都没有（M188 复审 P2-1）。
+
+/// 行首没有 `[tag]` 时的默认 scope。
+pub const APP_SCOPE: &str = "app";
+
+/// 记一行诊断：stderr 照旧，另外进启动器日志（best-effort，写不进去也不影响启动）。
+pub(crate) fn emit(line: &str) {
+    eprintln!("{line}");
+    let (scope, message) = split_scope(line);
+    unlucky_core::launch::launcher_log::record(scope, message);
+}
+
+/// `[font] 求值耗时 12 ms` → (`font`, `求值耗时 12 ms`)。
+///
+/// scope 只认「短、无空白、非空」的方括号前缀：`[a b]` 这种是正文而不是标签，别把整行拆坏。
+pub(crate) fn split_scope(line: &str) -> (&str, &str) {
+    let Some(rest) = line.strip_prefix('[') else {
+        return (APP_SCOPE, line);
+    };
+    let Some((scope, tail)) = rest.split_once(']') else {
+        return (APP_SCOPE, line);
+    };
+    if scope.is_empty() || scope.len() > 24 || scope.contains(char::is_whitespace) {
+        return (APP_SCOPE, line);
+    }
+    (scope, tail.trim_start())
+}
+
+/// 双写一行诊断（`diag!("[scope] 正文")`，参数同 `eprintln!`）。
+macro_rules! diag {
+    ($($arg:tt)*) => {{
+        crate::app::diag::emit(&format!($($arg)*));
+    }};
+}
+
+pub(crate) use diag;
+
+/// 串行化「会改 `launcher_log` 全局目录」的用例。
+///
+/// `core::launch::launcher_log` 是**进程级单例**（目录 + 缓冲），而 app-iced 的测试二进制里
+/// 有两条用例会 `set_dir` 到自己的临时目录（本文件的滚动闸、`app/dialog/tests.rs` 的启动事实闸）。
+/// 它们必须串行，否则互相把对方的落点改走——那是两条闸互相打架，不是产品问题。
+#[cfg(test)]
+pub(crate) static LOG_STATE_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+#[cfg(test)]
+mod tests {
+    use super::split_scope;
+
+    #[test]
+    fn the_leading_bracket_becomes_the_scope() {
+        assert_eq!(
+            split_scope("[font] 求值耗时 12 ms"),
+            ("font", "求值耗时 12 ms")
+        );
+        assert_eq!(split_scope("[gpu]"), ("gpu", ""));
+        // 正文里的方括号不是标签
+        assert_eq!(
+            split_scope("[page] 占位动作 [x] pressed"),
+            ("page", "占位动作 [x] pressed")
+        );
+    }
+
+    #[test]
+    fn lines_without_a_tag_fall_back_to_the_default_scope() {
+        assert_eq!(split_scope("没有标签的一行"), ("app", "没有标签的一行"));
+        assert_eq!(
+            split_scope("[a b] 空白不是标签"),
+            ("app", "[a b] 空白不是标签")
+        );
+    }
+
+    /// 守门②：**启动器日志的滚动真的会发生**，写超上限之后文件仍然有界。
+    ///
+    /// ## 为什么要「重试」
+    ///
+    /// `launcher_log` 是**进程级单例**（目录 + 缓冲），而同进程里还有一条用例
+    /// （`app/dialog/tests.rs` 的 `boot_facts_are_recorded_into_the_launcher_log`）会
+    /// `set_dir` 到它自己的临时目录。两边撞上时我这几行的落点就换了人，所以每一轮都要
+    /// **从头跑一遍**（登记 → 造超限 → 追加 → 看有没有滚），并且用「我这份超限文件有没有被
+    /// rename」判断这一轮是不是真的跑在我目录上。重试不是放宽断言：每轮该发生的都得真发生。
+    ///
+    /// 变异证明：删掉 `core::launch::launcher_log::append` 里那段「超限就 rename 成 launcher.1.log」，
+    /// 每一轮都不会出现 `launcher.1.log`，本条在重试用尽后红。
+    #[test]
+    fn the_launcher_log_rolls_over_and_stays_bounded() {
+        use unlucky_core::launch::launcher_log;
+
+        let _guard = super::LOG_STATE_LOCK
+            .lock()
+            .unwrap_or_else(|error| error.into_inner());
+
+        let dir = std::env::temp_dir().join(format!("ull-launcher-log-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).expect("建夹具目录");
+        let path = dir.join(launcher_log::FILE_NAME);
+        let rolled = dir.join("launcher.1.log");
+        let oversize = usize::try_from(launcher_log::MAX_BYTES).expect("上限能塞进 usize") + 16;
+
+        for _ in 0..50 {
+            let _ = std::fs::remove_file(&path);
+            let _ = std::fs::remove_file(&rolled);
+            launcher_log::set_dir(&dir);
+            if launcher_log::path() != Some(path.clone()) {
+                continue; // 这一轮被别人的 set_dir 抢先了
+            }
+            launcher_log::record("boot", "第一行");
+            std::fs::write(&path, vec![b'x'; oversize]).expect("造一份超限日志");
+            if launcher_log::path() != Some(path.clone()) {
+                continue;
+            }
+            launcher_log::record("boot", "滚过之后这一行必须在新文件里");
+            if launcher_log::path() != Some(path.clone()) {
+                continue; // 追加落到了别人的目录，这一轮不算
+            }
+
+            // 到这儿为止，追加**确实**落在本目录：超限就必须滚。
+            assert!(rolled.is_file(), "超限之后旧档必须滚成 launcher.1.log");
+            let size = std::fs::metadata(&path).expect("新文件").len();
+            assert!(
+                size < launcher_log::MAX_BYTES,
+                "滚完之后新文件必须远小于上限：{size}"
+            );
+            let text = std::fs::read_to_string(&path).expect("读新文件");
+            assert!(text.contains("滚过之后这一行"), "{text}");
+
+            // 只留一份历史：再滚一次仍然是 `launcher.1.log`，不会长出 launcher.2.log。
+            std::fs::write(&path, vec![b'y'; oversize]).expect("再造一份超限日志");
+            launcher_log::record("boot", "第二次滚动");
+            assert!(rolled.is_file());
+            assert!(!dir.join("launcher.2.log").exists(), "历史只留一份");
+            assert!(std::fs::metadata(&path).expect("新文件").len() < launcher_log::MAX_BYTES);
+
+            std::fs::remove_dir_all(&dir).ok();
+            return;
+        }
+        panic!("50 轮都撞上别的用例在改全局日志目录，这一条没能真正跑起来");
+    }
+}

crates/app-iced/src/app/dialog.rs

@@ -0,0 +1,390 @@
+//! 模态对话框（M187 接通 `DialogQueue`）+ 启动失败卡片。
+//!
+//! ## 为什么先补这一层
+//!
+//! 接线审计（M177）的结论很硬：`DialogQueue` / `DialogRequest` 在 app-iced 里**零引用**，
+//! 所有弹窗都画不出来。于是「像 PCL2 / HMCL 那样，启动失败时弹一个带崩溃说明的框」这件事
+//! 在此之前根本无处落脚。本模块是最小可用的一层：
+//!
+//! ```text
+//! presenter AppState::dialogs（唯一队列）
+//!         │ current()
+//!         ▼
+//! dialog::current(lang, request, card)  ← 纯视图模型（测试打这里）
+//!         │
+//!         ▼
+//! dialog::view::layer(ui, base, modal)  ← 模态遮罩 + 卡片 + 主/次按钮
+//! ```
+//!
+//! 交互：主按钮 / 次按钮 / 点遮罩 / `Esc` 都关当前条（`DialogQueue::close_current`）。
+//!
+//! ## 崩溃卡片额外带什么
+//!
+//! `DialogRequest`（presenter 的 DTO）只有标题/正文/按钮，而这次用户要的是**证据**：
+//! 退出码、一句人话原因、**文件路径**、可展开的崩溃说明、以及三个按钮（导出 / 打开文件夹 /
+//! 复制路径）。这些东西不进 `DialogRequest`——它是 presenter 的公共 DTO，塞进 UI 专用字段
+//! 会把「谁拥有证据」搅浑。做法是：队列管**弹窗**，[`CrashCard`] 管**这次失败的事实**，
+//! 两者按 `DialogId` 绑定，见 [`App::open_failure_dialog`]。
+//!
+//! 事实来源是 `unlucky_core::launch::crash_report`（启动线程收尾时登记的现场）。这里只读它，
+//! 不重算：**界面不读盘、不猜原因**。
+
+use unlucky_core::launch::crash_report::{CrashReport, Evidence};
+use unlucky_i18n::catalog::{Catalog, Key};
+use unlucky_i18n::Lang;
+use unlucky_presenter::dialogs::{DialogId, DialogKind, DialogSource};
+
+use crate::app::state::App;
+
+pub(super) mod export;
+#[cfg(test)]
+mod tests;
+pub(super) mod view;
+
+/// 崩溃卡片：一次失败的**事实**（不含任何结论）。
+#[derive(Debug, Clone)]
+pub struct CrashCard {
+    /// 现场。
+    pub report: CrashReport,
+    /// 「详细崩溃说明」是否展开。
+    pub expanded: bool,
+    /// 与哪一条队列请求绑定（关掉它时把卡片一起清掉）。
+    pub dialog: DialogId,
+    /// 上一次动作的结论（导出到哪 / 打不开文件夹的原因）。
+    ///
+    /// 为什么写在卡片里而不是只推 Toast：app-iced 的 Toast 通道**至今没有任何渲染点**
+    /// （`state.toasts` 只被推入与过期，`view` 里一次都没读）。导出这种「必须看见落到哪」的
+    /// 结果不能挂在一条不显示的通道上。
+    pub outcome: Option<String>,
+}
+
+/// 弹窗消息。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Message {
+    /// 主按钮。
+    Primary,
+    /// 次按钮。
+    Secondary,
+    /// 点遮罩 / Esc。
+    Dismiss,
+    /// 展开 / 收起详细说明。
+    Toggle,
+    /// 打开日志文件夹。
+    OpenFolder,
+    /// 复制全部路径。
+    CopyPaths,
+    /// 复制第 `index` 条路径（`Modal::paths` 的下标）。
+    CopyPath(usize),
+}
+
+/// 视图模型：**测试与渲染共用**的一份「这一屏该出现什么」。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub(super) struct Modal {
+    /// 标题。
+    pub title: String,
+    /// 正文（每行一段；都是运行时拼出来的 owned 字符串）。
+    pub body: Vec<String>,
+    /// 主按钮文字。
+    pub primary: String,
+    /// 次按钮文字（`None` = 不画）。
+    pub secondary: Option<String>,
+    /// 是否有次按钮（`Progress` 没有）。
+    pub blocking_progress: bool,
+    /// 崩溃卡片（普通弹窗为 `None`）。
+    pub card: Option<CardView>,
+    /// 动作结论（导出路径 / 失败原因）；`None` = 还没有动作。
+    pub notice: Option<String>,
+}
+
+/// 崩溃卡片的展示内容。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub(super) struct CardView {
+    /// 展开 / 收起按钮的文字。
+    pub toggle: String,
+    /// 当前的展开态。
+    pub expanded: bool,
+    /// （标签, 路径）列表——**逐条可点**（点了复制该条）。
+    pub paths: Vec<(String, String)>,
+    /// 详细说明的小标题（`None` = 没有可展开的内容）。
+    pub detail_title: Option<String>,
+    /// 详细说明的正文行。
+    pub detail_lines: Vec<String>,
+    /// 三个按钮的文字。
+    pub actions: [String; 3],
+}
+
+impl Modal {
+    /// 正文全文（测试与「复制摘要」共用；换行拼起来）。
+    #[must_use]
+    #[cfg(test)]
+    pub fn body_text(&self) -> String {
+        self.body.join("\n")
+    }
+}
+
+/// 从队列当前条与卡片造视图模型（**纯函数**：不读盘、不看 App）。
+#[must_use]
+pub(super) fn current(
+    lang: Lang,
+    request: &DialogRequestView<'_>,
+    card: Option<&CrashCard>,
+) -> Modal {
+    let catalog = Catalog::of(lang);
+    let mut modal = Modal {
+        title: request.title.to_string(),
+        body: vec![request.body.to_string()],
+        primary: request.primary.to_string(),
+        secondary: request.secondary.map(str::to_string),
+        blocking_progress: request.blocking_progress,
+        card: None,
+        notice: None,
+    };
+    if let Some(card) = card {
+        let detail = detail_of(&catalog, card);
+        modal.body = failure_body(&catalog, &card.report);
+        modal.primary = catalog.text(Key::CrashDialogExport).to_string();
+        modal.secondary = Some(catalog.text(Key::CrashDialogClose).to_string());
+        modal.card = Some(CardView {
+            toggle: catalog
+                .text(if card.expanded {
+                    Key::CrashDialogHideDetail
+                } else {
+                    Key::CrashDialogShowDetail
+                })
+                .to_string(),
+            expanded: card.expanded,
+            paths: path_rows(&catalog, &card.report),
+            detail_title: detail.0,
+            detail_lines: detail.1,
+            actions: [
+                catalog.text(Key::CrashDialogExport).to_string(),
+                catalog.text(Key::CrashDialogOpenFolder).to_string(),
+                catalog.text(Key::CrashDialogCopyPaths).to_string(),
+            ],
+        });
+        modal.notice = card.outcome.clone();
+    }
+    modal
+}
+
+/// 队列当前条的最小视图（避免把 `DialogRequest` 的细节漏进页面层）。
+pub(super) struct DialogRequestView<'a> {
+    /// 标题。
+    pub title: &'a str,
+    /// 正文。
+    pub body: &'a str,
+    /// 主按钮。
+    pub primary: &'a str,
+    /// 次按钮。
+    pub secondary: Option<&'a str>,
+    /// 进度框不可点主按钮。
+    pub blocking_progress: bool,
+}
+
+impl<'a> DialogRequestView<'a> {
+    /// 从 presenter 的请求取视图。
+    pub(super) fn of(request: &'a unlucky_presenter::dialogs::DialogRequest) -> Self {
+        Self {
+            title: &request.title,
+            body: &request.body,
+            primary: request.kind.primary_label(),
+            secondary: request.kind.secondary_label(),
+            blocking_progress: request.kind.is_blocking_progress(),
+        }
+    }
+}
+
+/// 失败正文：退出码 + **一句人话原因** + 证据形态。
+///
+/// 三件事都必须有——用户投诉的原话是「找半天没找到崩溃日志」，所以第三句不是锦上添花：
+/// 它要么指向游戏写的那份，要么明确说「这次没有，下面是捕获到的输出」。
+fn failure_body(catalog: &Catalog, report: &CrashReport) -> Vec<String> {
+    let mut body = Vec::new();
+    if let Some(code) = report.exit_code {
+        body.push(catalog.render(Key::CrashDialogExitCode, &[("code", &code.to_string())]));
+    }
+    if let Some(stage) = &report.stage {
+        let label = stage_label(catalog, stage);
+        body.push(catalog.render(Key::CrashDialogStageReason, &[("stage", label)]));
+    } else if report.exit_code == Some(0) {
+        body.push(catalog.text(Key::CrashDialogSilentFailure).to_string());
+    } else {
+        body.push(catalog.text(Key::CrashDialogStartedThenDied).to_string());
+    }
+    body.push(
+        match report.evidence() {
+            Evidence::GameCrashReport => catalog.text(Key::CrashDialogCrashReportFound),
+            Evidence::CapturedOutput => catalog.text(Key::CrashDialogNoGameLog),
+            Evidence::Nothing => catalog.text(Key::CrashDialogNoLogAtAll),
+        }
+        .to_string(),
+    );
+    body
+}
+
+/// 装配阶段 slug → 文案（**不**复用 core 的中文诊断串）。
+fn stage_label(catalog: &Catalog, slug: &str) -> &'static str {
+    let key = match slug {
+        "version_manifest" => Key::LaunchStageVersionManifest,
+        "inheritance" => Key::LaunchStageInheritance,
+        "instance_config" => Key::LaunchStageInstanceConfig,
+        "isolation" => Key::LaunchStageIsolation,
+        "identity" => Key::LaunchStageIdentity,
+        _ => Key::LaunchStageSpawn,
+    };
+    catalog.text(key)
+}
+
+/// 路径行（**启动器日志目录 + 该实例 latest.log + crash-reports 目录 + 会话 JSONL**）。
+fn path_rows(catalog: &Catalog, report: &CrashReport) -> Vec<(String, String)> {
+    let mut rows = Vec::new();
+    if let Some(log) = &report.session_log {
+        rows.push((
+            catalog.text(Key::CrashDialogSessionLog).to_string(),
+            log.display().to_string(),
+        ));
+    }
+    if let Some(dir) = &report.launcher_logs {
+        rows.push((
+            catalog.text(Key::CrashDialogLauncherLogs).to_string(),
+            dir.display().to_string(),
+        ));
+    }
+    if let Some(path) = report.latest_log_path() {
+        rows.push((
+            catalog.text(Key::CrashDialogGameLog).to_string(),
+            path.display().to_string(),
+        ));
+    }
+    if let Some(dir) = report.crash_reports_dir() {
+        rows.push((
+            catalog.text(Key::CrashDialogCrashReports).to_string(),
+            dir.display().to_string(),
+        ));
+    }
+    rows
+}
+
+/// 详细说明：有崩溃报告贴 Description/栈片段，否则贴启动器捕获的尾巴。
+fn detail_of(catalog: &Catalog, card: &CrashCard) -> (Option<String>, Vec<String>) {
+    let report = &card.report;
+    if let Some(artifact) = report
+        .artifacts
+        .iter()
+        .find(|artifact| artifact.source == "crash_report")
+    {
+        let mut lines = Vec::new();
+        if let Some(excerpt) = &artifact.excerpt {
+            lines.extend(excerpt.lines().map(str::to_string));
+        } else {
+            lines.push(artifact.path.display().to_string());
+        }
+        let title = format!(
+            "{} {}",
+            catalog.text(Key::LogsDiagnosisTitle),
+            artifact.path.display()
+        );
+        return (Some(title), lines);
+    }
+    if report.stderr_tail.is_empty() {
+        return (None, Vec::new());
+    }
+    let title = catalog.render(
+        Key::CrashDialogCapturedTail,
+        &[("count", &report.stderr_tail.len().to_string())],
+    );
+    (Some(title), report.stderr_tail.clone())
+}
+
+// --------------------------------------------------------------- 与 App 的接线
+
+impl App {
+    /// 队列当前条 → 视图模型（`view()` 与测试共用同一个入口）。
+    pub(super) fn dialog_modal(&self) -> Option<Modal> {
+        let request = self.state.dialogs.current()?;
+        let view = DialogRequestView::of(request);
+        let card = self
+            .dialog_card
+            .as_ref()
+            .filter(|card| card.dialog == request.id);
+        Some(current(self.lang(), &view, card))
+    }
+
+    /// 收到一次启动收尾：失败就弹框（成功不打扰）。
+    ///
+    /// 只在**真的失败**时弹：`LogOutcome::Ok` 且没有阶段失败 ⇒ 什么都不做，与既有 Toast 口径一致。
+    pub(super) fn open_failure_dialog(
+        &mut self,
+        finished: &unlucky_presenter::dto::LaunchFinished,
+    ) {
+        let failed = finished.outcome != unlucky_presenter::dto::LogOutcome::Ok
+            || finished.failure.is_some();
+        if !failed {
+            return;
+        }
+        let Some(report) = unlucky_core::launch::crash_report::failing_launch() else {
+            return;
+        };
+        if !finished.session.is_empty() && report.session != finished.session {
+            // 登记的是另一场（并发启动）：不拿它去解释这一场。
+            return;
+        }
+        let catalog = self.lang().catalog();
+        let crashed = report.started();
+        let title = catalog.text(if crashed {
+            Key::CrashDialogTitleCrashed
+        } else {
+            Key::CrashDialogTitleFailed
+        });
+        let summary = self.dialog_summary(&report);
+        let at = self.lang();
+        let id = self.state.dialogs.push(
+            DialogSource::UserAction,
+            title,
+            summary,
+            DialogKind::Confirm {
+                primary: Catalog::of(at).text(Key::CrashDialogExport).to_string(),
+                secondary: Catalog::of(at).text(Key::CrashDialogClose).to_string(),
+            },
+        );
+        self.dialog_card = Some(CrashCard {
+            report,
+            // 默认展开：正文已经说「下面是捕获的最后若干行」，收着就成了空口承诺。
+            expanded: true,
+            dialog: id,
+            outcome: None,
+        });
+        self.view_dirty = true;
+    }
+
+    /// 队列标题下的那一行摘要（弹窗正文由 [`current`] 按卡片重算，这里给它一份独立可读的短句）。
+    fn dialog_summary(&self, report: &CrashReport) -> String {
+        let catalog = self.lang().catalog();
+        match report.exit_code {
+            Some(code) => catalog.render(Key::CrashDialogExitCode, &[("code", &code.to_string())]),
+            None => catalog.text(Key::CrashDialogTitleFailed).to_string(),
+        }
+    }
+
+    /// 关掉当前弹窗（主/次按钮、遮罩、`Esc` 共用）。
+    pub(super) fn close_dialog(&mut self) {
+        let closed = self.state.dialogs.current().map(|request| request.id);
+        self.state.dialogs.close_current();
+        if self
+            .dialog_card
+            .as_ref()
+            .is_some_and(|card| closed == Some(card.dialog))
+        {
+            self.dialog_card = None;
+        }
+        self.view_dirty = true;
+    }
+
+    /// 展开 / 收起详细说明。
+    pub(super) fn toggle_dialog_detail(&mut self) {
+        if let Some(card) = &mut self.dialog_card {
+            card.expanded = !card.expanded;
+            self.view_dirty = true;
+        }
+    }
+}

crates/app-iced/src/app/dialog/export.rs

@@ -0,0 +1,217 @@
+//! 失败卡片的三个动作：导出诊断包 / 打开文件夹 / 复制路径。
+//!
+//! 与 [`super`] 分开是因为职责不同：那边管**弹窗与事实**，这边管**把事实带出界面**。
+//! 打包本体在 `unlucky_core::launch::crash_bundle`（脱敏、上限、清单都在那一处），
+//! 本文件只负责「放哪、叫什么名字、怎么打开」。
+
+use std::path::PathBuf;
+
+use unlucky_core::launch::crash_bundle::{self, BundleEntry, BundleSpec};
+use unlucky_core::launch::crash_report::CrashReport;
+use unlucky_i18n::catalog::{Catalog, Key};
+use unlucky_i18n::Lang;
+
+/// 一次导出的结论（**成功也带事实**：路径、字节数、有没有文件被截断）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct Exported {
+    /// 给用户看的那一句（已本地化）。
+    pub text: String,
+    /// 是否成功。
+    pub ok: bool,
+    /// 有几个文件被截断（`>0` 时界面要明说「证据是残的」）。
+    pub truncated: usize,
+}
+
+/// 导出诊断包：打到「启动器日志目录 / exports / 一场一个文件名」。
+///
+/// 返回的那句话说清**落到哪、多少字节**（用户要的第一件事就是「文件在哪」）；
+/// 有文件被截断时再补一句——别让用户以为包里的证据是完整的。
+pub(crate) fn export(report: &CrashReport, lang: Lang) -> Exported {
+    let catalog = Catalog::of(lang);
+    let Some(logs) = &report.launcher_logs else {
+        return Exported {
+            text: catalog.render(
+                Key::CrashDialogExportFailed,
+                &[("error", "no launcher log dir")],
+            ),
+            ok: false,
+            truncated: 0,
+        };
+    };
+    let stamp =
+        unlucky_core::launch::time::format_rfc3339_millis(unlucky_core::launch::time::now())
+            .replace([':', '.', 'T'], "-")
+            .trim_end_matches('Z')
+            .to_string();
+    let name = if report.session.is_empty() {
+        &report.instance
+    } else {
+        &report.session
+    };
+    let target = crash_bundle::default_target_dir(logs).join(format!("crash-{name}-{stamp}.zip"));
+    match crash_bundle::write_bundle(&spec_of(report), &target) {
+        Ok(bundle) => {
+            let mut text = catalog.render(
+                Key::CrashDialogExportDone,
+                &[
+                    ("bytes", &bundle.bytes.to_string()),
+                    ("path", &bundle.path.display().to_string()),
+                ],
+            );
+            if bundle.truncated > 0 {
+                text.push('\n');
+                text.push_str(&catalog.render(
+                    Key::CrashDialogExportTruncated,
+                    &[("count", &bundle.truncated.to_string())],
+                ));
+            }
+            Exported {
+                text,
+                ok: true,
+                truncated: bundle.truncated,
+            }
+        }
+        Err(error) => Exported {
+            text: catalog.render(Key::CrashDialogExportFailed, &[("error", &error)]),
+            ok: false,
+            truncated: 0,
+        },
+    }
+}
+
+/// 现场 → 诊断包清单（**进包的东西必须与弹窗上列出的路径一致**）。
+fn spec_of(report: &CrashReport) -> BundleSpec {
+    let mut entries: Vec<BundleEntry> = Vec::new();
+    let push = |entries: &mut Vec<BundleEntry>, group: &'static str, path: &std::path::Path| {
+        if path.exists() {
+            entries.push(BundleEntry::new(group, path));
+        }
+    };
+    if let Some(logs) = &report.launcher_logs {
+        push(&mut entries, "launcher", &logs.join("launcher.log"));
+        push(&mut entries, "launcher", &logs.join("launcher.1.log"));
+        push(&mut entries, "launcher", &logs.join("install.log"));
+    }
+    if let Some(session) = &report.session_log {
+        // 源文件名就是会话 id：钉成 `session.jsonl`，包内名与清单名同时不再泄漏 id，
+        // 也不会出现「清单写 <redacted:token> 而包里是原始 id」（r1 复审 P2-2）。
+        if session.exists() {
+            entries.push(BundleEntry::named("session", session, "session.jsonl"));
+        }
+    }
+    for artifact in &report.artifacts {
+        // `latest.log` 在下面单独收一次（它同时是扫描结果与固定项，重复收会变成两份）。
+        if artifact.source != "latest_log" {
+            push(&mut entries, "game", &artifact.path);
+        }
+    }
+    if let Some(latest) = report.latest_log_path() {
+        push(&mut entries, "game", &latest);
+    }
+    if let Some(json) = &report.version_json {
+        push(&mut entries, "instance", json);
+    }
+    let mut secrets = vec![report.session.clone()];
+    secrets.retain(|secret| !secret.is_empty());
+    BundleSpec {
+        instance: report.name.clone(),
+        version: report.version.clone(),
+        session: report.session.clone(),
+        exit_code: report.exit_code,
+        exit_type: report.exit_type.clone(),
+        uptime_ms: report.uptime_ms,
+        command: report.command.clone(),
+        java: report.java.clone(),
+        system: report.system.clone(),
+        notes: report.note_lines(),
+        missing: report.missing_lines(),
+        entries,
+        secrets,
+        home: std::env::var("USERPROFILE")
+            .or_else(|_| std::env::var("HOME"))
+            .ok()
+            .map(PathBuf::from),
+    }
+}
+
+/// 打开「日志文件夹」：有现场就开实例运行目录，否则开启动器日志目录。
+///
+/// 平台差异只在这里一处（`explorer` / `open` / `xdg-open`），不往业务代码里散写 `cfg`。
+pub(crate) fn open_folder(report: &CrashReport, lang: Lang) -> String {
+    let catalog = Catalog::of(lang);
+    let target = report
+        .run_dir
+        .clone()
+        .filter(|dir| dir.is_dir())
+        .or_else(|| report.launcher_logs.clone().filter(|dir| dir.is_dir()));
+    let Some(dir) = target else {
+        return catalog.render(
+            Key::CrashDialogOpenFailed,
+            &[("error", "no folder on disk")],
+        );
+    };
+    match open_dir(&dir) {
+        Ok(()) => String::new(),
+        Err(error) => catalog.render(Key::CrashDialogOpenFailed, &[("error", &error)]),
+    }
+}
+
+/// 打开一个目录（M188：设置页/日志页的「打开日志文件夹」也走这里，**不再另写一套 `cfg`**）。
+///
+/// 失败文本带完整路径：调用方把它显示/记日志出来，用户至少能照着路径去找。
+pub(crate) fn open_dir(dir: &std::path::Path) -> Result<(), String> {
+    if !dir.is_dir() {
+        return Err(format!("{}（目录不存在）", dir.display()));
+    }
+    spawn_opener(dir).map_err(|error| format!("{}（打开失败：{error}）", dir.display()))
+}
+
+/// 平台各自的「打开这个目录」实现。
+///
+/// ## 为什么这三处**故意**不走 `unlucky_core::platform::child::quiet`（M217）
+///
+/// 这一处 spawn 的**目的就是让桌面上出现一个可见的东西**（文件管理器窗口 / Finder 窗口 /
+/// 桌面环境的文件管理器）。`quiet` 的语义是「把子进程的窗口抑制掉」，用在这里是把目的本身
+/// 抑制掉——改错了用户点「打开文件夹」就只看到「打不开」的报错。
+///
+/// 而且从窗口角度也不需要它：`explorer.exe` / `open` / `xdg-open` 自己都是 GUI 侧程序，由
+/// 无控制台的 GUI 父进程 spawn 时 Windows 不会给它们新建控制台。所以这三处在
+/// `crates/core/tests/child_quiet_guard.rs` 的 `ALLOWED_ROLES` 里登记成「目录打开器」角色，
+/// **不是**漏网。别把它们改成 `quiet`。
+#[cfg(target_os = "windows")]
+fn spawn_opener(dir: &std::path::Path) -> Result<(), String> {
+    // `explorer` 不用 shell：路径里的空格与 `&` 不会被当成命令分隔符。
+    std::process::Command::new("explorer")
+        .arg(dir)
+        .spawn()
+        .map(|_| ())
+        .map_err(|error| error.to_string())
+}
+
+#[cfg(target_os = "macos")]
+fn spawn_opener(dir: &std::path::Path) -> Result<(), String> {
+    std::process::Command::new("open")
+        .arg(dir)
+        .spawn()
+        .map(|_| ())
+        .map_err(|error| error.to_string())
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+fn spawn_opener(dir: &std::path::Path) -> Result<(), String> {
+    std::process::Command::new("xdg-open")
+        .arg(dir)
+        .spawn()
+        .map(|_| ())
+        .map_err(|error| error.to_string())
+}
+
+/// 「复制路径」的一段文本（每条一行，标签 + 路径）。
+pub(crate) fn paths_text(report: &CrashReport) -> String {
+    report
+        .path_lines()
+        .into_iter()
+        .map(|(label, path)| format!("{label}: {}", path.display()))
+        .collect::<Vec<_>>()
+        .join("\n")
+}

crates/app-iced/src/app/dialog/tests.rs

@@ -0,0 +1,344 @@
+//! 弹窗的三条守卫：**队列真的被消费**、**运行时中文真的进了正文**、**两种失败说两句话**。
+//!
+//! ## 这些用例抓得住什么 / 抓不住什么（说在明处）
+//!
+//! | 用例 | 抓得住 | 抓不住 |
+//! |---|---|---|
+//! | [`queue_drives_the_modal_through_refresh_view`] | 队列里有请求 ⇒ `refresh_view` 之后 `view()` 拿到的模型里就有它（把消费点删掉即红） | 像素：`view()` 是否真的把控件塞进 iced 树（由 `DevDocs/artifacts/m187/` 的截图守） |
+//! | [`runtime_chinese_reaches_the_body`] | 运行时拼出来的中文（`render` / `format!` 的 owned 串）确实在正文里 | 字形是否栅格化出来（同上，wgpu / tiny-skia 并排图） |
+//! | [`two_failure_shapes_say_two_different_things`] | 没有 crash-report 时**不会**说成「有崩溃报告」，而且必须贴出捕获行 | 那句话读起来顺不顺（review） |
+//!
+//! 「owned 文字在 wgpu 下丢字」这条 M190 的怀疑在本 branch 上**没有复现**（A/B 图见
+//! `DevDocs/artifacts/m187/ab-wgpu.png` 与 `ab-tinyskia.png`）：同一串中文走 `text_role` 与
+//! `text_role_owned` 在两种后端下逐字相同。所以这里不编一条「为了变绿而改渲染路径」的断言。
+
+use std::path::PathBuf;
+
+use unlucky_core::launch::crash_report::{self, ArtifactFact, CrashReport};
+use unlucky_i18n::catalog::Key;
+use unlucky_i18n::Lang;
+use unlucky_presenter::dialogs::{DialogKind, DialogQueue, DialogSource};
+use unlucky_presenter::dto::{LaunchFinished, LogOutcome};
+
+use super::{current, path_rows, CrashCard, DialogRequestView};
+
+use crate::app::state::App;
+use crate::cli::Options;
+use crate::theme::Families;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+fn headless() -> App {
+    use unlucky_presenter::mock::MockBackend;
+    use unlucky_presenter::settings_bridge::SettingsBridge;
+    App::with_presenter(
+        Options::default(),
+        FAMILIES,
+        unlucky_design::color::SchemeFlavor::Light,
+        Box::new(MockBackend::new()),
+        SettingsBridge::memory_only(),
+    )
+}
+
+fn report(with_crash_report: bool, tail: Vec<String>) -> CrashReport {
+    let run_dir = PathBuf::from("/instances/survival");
+    let artifacts = if with_crash_report {
+        vec![ArtifactFact {
+            source: "crash_report".to_string(),
+            path: run_dir.join("crash-reports/crash-2026-11-08.txt"),
+            excerpt: Some("Description: Initializing game".to_string()),
+        }]
+    } else {
+        Vec::new()
+    };
+    CrashReport {
+        instance: "survival".to_string(),
+        name: "生存".to_string(),
+        version: "1.20.4-fabric".to_string(),
+        session: "9f2c".to_string(),
+        session_log: Some(PathBuf::from("/sessions/game/9f2c.jsonl")),
+        version_json: Some(PathBuf::from("/game/versions/1.20.4/1.20.4.json")),
+        launcher_logs: Some(PathBuf::from("/logs")),
+        run_dir: Some(run_dir),
+        artifacts,
+        exit_code: Some(1),
+        exit_type: "application_error".to_string(),
+        uptime_ms: 1_000,
+        command: "javaw -Xmx4096m".to_string(),
+        java: "javaw.exe (21)".to_string(),
+        system: "os=windows".to_string(),
+        stage: None,
+        stage_detail: None,
+        stderr_tail: tail,
+    }
+}
+
+/// 守卫①：队列消费。请求进队列 ⇒ `refresh_view` 之后模型里有它；空队列 ⇒ 没有。
+///
+/// **变异证明**：把 `refresh_view` 末尾那行 `self.dialog_model = self.dialog_modal();` 删掉，
+/// 本用例第二段立刻红（`dialog_model` 恒 `None`）。
+#[test]
+fn queue_drives_the_modal_through_refresh_view() {
+    let mut app = headless();
+    app.refresh_view();
+    assert!(
+        app.dialog_model.is_none(),
+        "空队列不该画任何弹窗（现状：队列零引用，弹窗从不渲染）"
+    );
+
+    let title = app.lang().catalog().text(Key::CrashDialogTitleFailed);
+    app.state.dialogs.push(
+        DialogSource::UserAction,
+        title,
+        "正文一行",
+        DialogKind::Confirm {
+            primary: "主要".to_string(),
+            secondary: "次要".to_string(),
+        },
+    );
+    app.view_dirty = true;
+    app.refresh_view();
+
+    let modal = app.dialog_model.as_ref().expect("队列里有请求就必须有模型");
+    assert_eq!(modal.title, title);
+    assert_eq!(modal.primary, "主要");
+    assert_eq!(modal.secondary.as_deref(), Some("次要"));
+}
+
+/// 守卫②：**运行时拼出来的中文**必须真的进正文（owned 串走 `Catalog::render` / `format!`）。
+///
+/// **变异证明**：把 `failure_body` 里的 `catalog.render(Key::CrashDialogExitCode, …)` 换成固定
+/// 英文，本用例第一处断言立刻红。
+#[test]
+fn runtime_chinese_reaches_the_body() {
+    let lang = Lang::ZhCn;
+    let card = CrashCard {
+        report: report(false, vec!["java.lang.RuntimeException: boom".to_string()]),
+        expanded: true,
+        dialog: 1,
+        outcome: None,
+    };
+    let mut queue = DialogQueue::new();
+    queue.push(
+        DialogSource::UserAction,
+        "游戏崩溃",
+        "",
+        DialogKind::Confirm {
+            primary: String::new(),
+            secondary: String::new(),
+        },
+    );
+    let request = queue.current().expect("当前条");
+    let view = DialogRequestView::of(request);
+    let modal = current(lang, &view, Some(&card));
+    let body = modal.body_text();
+
+    // 退出码那句是 `render`（带参数）拼出来的：必须带中文与数字。
+    assert!(body.contains("退出码 1"), "{body}");
+    assert!(body.contains("游戏进程起来了"), "{body}");
+    // 没有 crash-report 时必须说「没生成」+「下面是捕获的行」。
+    assert!(body.contains("没有生成崩溃报告"), "{body}");
+    assert!(body.contains("捕获"), "{body}");
+    // 英文界面里同样的三句不许出现中文（反向守卫：i18n 不是只往一个方向写）。
+    let en = current(Lang::En, &view, Some(&card));
+    assert!(!en.body_text().contains('崩'), "{}", en.body_text());
+}
+
+/// 守卫③：两种失败**说两句不同的话**，而且都可以导出（事实齐全）。
+#[test]
+fn two_failure_shapes_say_two_different_things() {
+    let lang = Lang::ZhCn;
+    let with = report(true, vec!["stack line".to_string()]);
+    let without = report(false, vec!["Error: could not find java.dll".to_string()]);
+
+    assert_ne!(with.evidence(), without.evidence());
+    let with_card = CrashCard {
+        report: with.clone(),
+        expanded: true,
+        dialog: 1,
+        outcome: None,
+    };
+    let without_card = CrashCard {
+        report: without.clone(),
+        expanded: true,
+        dialog: 1,
+        outcome: None,
+    };
+    let mut queue = DialogQueue::new();
+    queue.push(
+        DialogSource::UserAction,
+        "t",
+        "",
+        DialogKind::Error {
+            primary: "p".to_string(),
+            hint: None,
+        },
+    );
+    let request = queue.current().unwrap();
+    let view = DialogRequestView::of(request);
+
+    let crash = current(lang, &view, Some(&with_card));
+    let no_log = current(lang, &view, Some(&without_card));
+    assert_ne!(crash.body_text(), no_log.body_text());
+    assert!(crash.body_text().contains("写出了崩溃报告"));
+    assert!(!no_log.body_text().contains("写出了崩溃报告"));
+    // 没有 crash-report 的那一态仍然有可展开的细节（贴的是捕获行）与四条路径。
+    assert!(no_log.card.as_ref().expect("卡片").detail_title.is_some());
+    assert_eq!(path_rows(&lang.catalog(), &without).len(), 4);
+    assert!(path_rows(&lang.catalog(), &without)
+        .iter()
+        .any(|(_, path)| path.ends_with("latest.log")));
+}
+
+/// 弹窗开/关与卡片的绑定：关掉之后两样都要空（否则下一次失败会读到上一次的现场）。
+#[test]
+fn closing_the_dialog_clears_the_card() {
+    let mut app = headless();
+    crash_report::publish(report(false, vec!["line".to_string()]));
+    let finished = LaunchFinished {
+        id: "survival".to_string(),
+        session: "9f2c".to_string(),
+        outcome: LogOutcome::Crashed,
+        exit_code: Some(1),
+        uptime_ms: 1_000,
+        failure: None,
+    };
+    app.open_failure_dialog(&finished);
+    assert!(app.state.dialogs.current().is_some(), "失败必须弹框");
+    assert!(app.dialog_card.is_some());
+
+    app.close_dialog();
+    assert!(app.state.dialogs.current().is_none());
+    assert!(app.dialog_card.is_none());
+}
+
+/// 成功收尾不打扰用户。
+#[test]
+fn a_successful_launch_does_not_pop_anything() {
+    let mut app = headless();
+    crash_report::publish(report(false, Vec::new()));
+    let finished = LaunchFinished {
+        id: "survival".to_string(),
+        session: "9f2c".to_string(),
+        outcome: LogOutcome::Ok,
+        exit_code: Some(0),
+        uptime_ms: 90_000,
+        failure: None,
+    };
+    app.open_failure_dialog(&finished);
+    assert!(app.state.dialogs.current().is_none());
+}
+
+/// P2-1：**卡片那一层只能是卡片大**。
+///
+/// 抓得住什么：r1 复审实测的那个 bug —— `mouse_area(整窗居中容器)` 的命中区是整窗，
+/// 卡片外任何一次点击都先被它捕获，遮罩永远收不到（「点遮罩关闭」形同虚设）。
+/// `Widget::size_hint()` 不需要渲染器就能问，所以这条能在单测里跑：卡片层若声明
+/// `Fill`/`Fill`，就等于「命中区 = 整窗」。
+///
+/// **抓不住什么**：端到端指针派发（本仓没有事件 harness，`Element` 的 `layout`/`update`
+/// 需要真渲染器）。所以这条守的是**结构属性**，不是「点一下真的关了」。
+#[test]
+fn the_card_layer_is_card_sized_so_the_backdrop_can_be_clicked() {
+    use iced::Length;
+
+    let mut app = headless();
+    app.state.dialogs.push(
+        DialogSource::UserAction,
+        "t",
+        "b",
+        DialogKind::Confirm {
+            primary: "p".to_string(),
+            secondary: "s".to_string(),
+        },
+    );
+    let modal = {
+        let request = app.state.dialogs.current().expect("当前条");
+        let view = DialogRequestView::of(request);
+        super::current(app.lang(), &view, None)
+    };
+    let plane = super::view::card_plane(app.ui(), &modal);
+    let hint = iced::advanced::Widget::size_hint(plane.as_widget());
+    // 任一维是 `Fill` 就意味着「跟随父级 = 整窗」（外层是 Fill 的居中容器），
+    // 命中区于是变成整窗 —— 那正是 r1 抓到的原实现。
+    assert_ne!(
+        hint.width,
+        Length::Fill,
+        "卡片层宽度不能 Fill（会撑成整窗）"
+    );
+    assert_ne!(
+        hint.height,
+        Length::Fill,
+        "卡片层高度不能 Fill（会撑成整窗）"
+    );
+}
+
+/// P1-1：遮罩必须是**不透明预合成**，而且两档都**压暗**（深色档尤其）。
+///
+/// 抓得住 r1 实测的那个 p1：`Role::OnSurface @ 32%` 在深色档是「近白 @32%」⇒ 遮罩把整窗
+/// 提亮（实测 (9,21,28) → (129,138,145)）。这里用亮度直接判方向：遮罩必须比画布暗。
+///
+/// 抓不住：具体色值对不对（那是令牌层的事）。
+#[test]
+fn the_backdrop_is_an_opaque_precomposite_and_darkens_both_flavors() {
+    use unlucky_design::color::{Role, SchemeFlavor};
+    use unlucky_design::elevation::MaterialLayer;
+    use unlucky_design::typography::Platform;
+
+    let luma = |color: iced::Color| 0.2126 * color.r + 0.7152 * color.g + 0.0722 * color.b;
+
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let ui = crate::theme::Ui::with_platform(flavor, Platform::Windows, FAMILIES);
+        // 断言**视图真正用的那一份**（不是组件层的默认值）：改回「OnSurface @32%」这里就红。
+        let backdrop = super::view::backdrop_color(&ui);
+        assert_eq!(
+            backdrop.a, 1.0,
+            "{flavor:?}：遮罩必须是不透明预合成（D27：CPU 档零半透明）"
+        );
+
+        let canvas = crate::theme::to_iced(
+            unlucky_design::color::Scheme::baseline(flavor)
+                .get(MaterialLayer::Canvas.surface_role()),
+        );
+        assert!(
+            luma(backdrop) < luma(canvas),
+            "{flavor:?}：遮罩必须比画布暗（当前 lane {:.3} vs 画布 {:.3}）——              用 Role::OnSurface 当遮罩会在深色档把整窗提亮",
+            luma(backdrop),
+            luma(canvas)
+        );
+        assert_eq!(Role::Surface, MaterialLayer::Canvas.surface_role());
+    }
+}
+
+/// P2-4：启动那一拍的**事实**确实进了启动器日志（登记目录后一次刷出）。
+///
+/// 抓得住：记录函数被拆掉/改空（缓冲里就什么都没有）。
+/// 抓不住：`on_boot` 有没有调它 —— 那靠这条用例旁边的调用点与 `host/launch.rs` 的 `set_dir`，
+/// 真机第一次崩溃才是最终验收闸门（复审与我的一致口径）。
+#[test]
+fn boot_facts_are_recorded_into_the_launcher_log() {
+    // 与 `app/diag.rs` 的滚动闸串行：两条用例都动同一个进程级单例目录。
+    let _guard = crate::app::diag::LOG_STATE_LOCK
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    let dir = std::env::temp_dir().join(format!("ull-m187-bootlog-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("建目录");
+    unlucky_core::launch::launcher_log::set_dir(&dir);
+
+    let app = headless();
+    crate::app::update::boot_env::record_boot_log(&app);
+
+    let path = dir.join(unlucky_core::launch::launcher_log::FILE_NAME);
+    let text = std::fs::read_to_string(&path).expect("launcher.log");
+    assert!(text.contains("[boot] app boot"), "{text}");
+    assert!(text.contains("theme="), "{text}");
+    assert!(text.contains("window="), "{text}");
+}
+
+#[path = "tests/export.rs"]
+mod export;

crates/app-iced/src/app/dialog/tests/export.rs

@@ -0,0 +1,85 @@
+//! 导出的用例：真的落盘、真的报字节数、真的在有截断时说一句。
+//!
+//! 从 `tests.rs` 拆出（那个文件贴着 400 行硬线）。共用父模块的 `report()` 夹具。
+
+use unlucky_i18n::Lang;
+
+use super::report;
+use crate::app::dialog::export;
+
+/// 导出：真的落盘、真的报出路径与字节数（**没有 crash-report 也要能导出**）。
+#[test]
+fn export_writes_a_bundle_even_without_a_crash_report() {
+    let root = std::env::temp_dir().join(format!("ull-m187-export-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&root);
+    std::fs::create_dir_all(root.join("logs")).expect("建目录");
+    std::fs::write(root.join("logs").join("launcher.log"), "[launch] boom\n").expect("写日志");
+
+    let mut spec_report = report(false, vec!["Error: boom".to_string()]);
+    spec_report.launcher_logs = Some(root.join("logs"));
+    spec_report.session_log = None;
+    spec_report.run_dir = None;
+    spec_report.version_json = None;
+
+    let done = export::export(&spec_report, Lang::ZhCn);
+    let text = done.text.clone();
+    assert!(done.ok, "{text}");
+    assert_eq!(done.truncated, 0);
+    assert!(text.contains("已导出"), "{text}");
+    assert!(text.contains("字节"), "{text}");
+
+    let exports = root.join("logs").join("exports");
+    let files: Vec<_> = std::fs::read_dir(&exports)
+        .expect("导出目录")
+        .filter_map(Result::ok)
+        .collect();
+    assert_eq!(files.len(), 1, "一次导出只该落一个包");
+    let size = files[0].metadata().expect("元数据").len();
+    assert!(size > 0, "包不该是空文件");
+    assert!(
+        text.contains(&size.to_string()),
+        "报出来的字节数要与磁盘一致：{text} / {size}"
+    );
+}
+
+/// P3-4：`truncated > 0` 时**界面上那一句**真的出现（r2 复审登记的那条没有用例）。
+///
+/// 抓得住：把 `Exported.text` 里「有文件被截断」那句删掉/短路（变异证明见报告）。
+/// 抓不住：那句话排版好不好看（视觉）。
+#[test]
+fn a_truncated_export_says_so_in_the_notice() {
+    use unlucky_core::launch::crash_bundle::MAX_ENTRY_BYTES;
+
+    let root = std::env::temp_dir().join(format!("ull-m187-trunc-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&root);
+    std::fs::create_dir_all(root.join("logs")).expect("建目录");
+    std::fs::create_dir_all(root.join("game").join("logs")).expect("建目录");
+    std::fs::write(root.join("logs").join("launcher.log"), "boot\n").expect("写日志");
+
+    // 略超上限的 latest.log：必须用**真实日志行**填充 —— 同一字符的 4 MiB 会被
+    // 「长不透明串」脱敏规则整段替换成占位符，长度就不超限了（那测的是脱敏不是截断）。
+    let line = "2026-11-08T15:30:12.441Z [Render thread/INFO]: loading chunk\n";
+    let mut big = String::new();
+    while big.len() < usize::try_from(MAX_ENTRY_BYTES).expect("常数") + 256 {
+        big.push_str(line);
+    }
+    std::fs::write(root.join("game").join("logs").join("latest.log"), &big).expect("写大日志");
+
+    let mut report = report(false, Vec::new());
+    report.launcher_logs = Some(root.join("logs"));
+    report.run_dir = Some(root.join("game"));
+    report.session_log = None;
+    report.version_json = None;
+
+    let done = export::export(&report, Lang::ZhCn);
+    assert!(done.ok, "{}", done.text);
+    assert_eq!(
+        done.truncated, 1,
+        "这份 latest.log 必须真的被截断（>4 MiB）"
+    );
+    assert!(
+        done.text.contains("已截断"),
+        "界面上没有说「有文件被截断」：{}",
+        done.text
+    );
+}

crates/app-iced/src/app/dialog/view.rs

@@ -0,0 +1,299 @@
+//! 模态层的控件树：**遮罩 + 卡片 + 主/次按钮**，正文与路径全部来自 [`super::Modal`]。
+//!
+//! ## 命中语义（为什么点遮罩能关、点卡片不关）
+//!
+//! `iced::widget::Stack` 的 `update` 从上往下（后画的先收）派发，遇到 `shell.is_event_captured()`
+//! 立刻停。所以三层的顺序是：
+//!
+//! ```text
+//! stack![ 页面树, 遮罩（mouse_area→Dismiss，整窗）, 居中容器（透明）→ opaque(卡片) ]
+//! ```
+//!
+//! 卡片那层用 `opaque` 把卡片内的左键按下**吃掉**（[`super::Message`] 不需要再有一条专用
+//! 消息），于是点卡片里的空白不会冒到遮罩去关框；卡片里的按钮自己会先捕获。
+//! **`opaque` 只包卡片**是这条语义成立的前提：包住整窗居中容器的话，命中区就变成整窗，
+//! 遮罩永远收不到按下（r1 复审 P2-1 抓到的原实现）。
+
+use iced::widget::text::LineHeight;
+use iced::widget::{button, column, container, mouse_area, row, scrollable, text, Space};
+use iced::{Alignment, Background, Border, Color, Element, Font, Length, Pixels, Shadow};
+
+use unlucky_design::color::Role;
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::spacing::Space as Sp;
+use unlucky_design::typography::TypeRole;
+
+use crate::app::components::buttons;
+use crate::app::components::feedback::dialog::scrim;
+use crate::app::components::feedback::panel::DialogGeometry;
+use crate::pages::frame;
+use crate::theme::Ui;
+
+use super::super::message::Message;
+use super::{Message as DialogMessage, Modal};
+
+/// 卡片内**滚动区**高度（详情 + 路径在这里滚；页脚按钮永远在卡片里）。
+const SCROLL_HEIGHT: f32 = 300.0;
+/// 有导出结论时滚动区让出的高度（那一段会多占两行，不让就只能压扁页脚按钮）。
+const SCROLL_HEIGHT_WITH_NOTICE: f32 = 210.0;
+/// 卡片最大高（兜底：不许把边框撑出屏幕）。
+const CARD_HEIGHT: f32 = 660.0;
+
+/// 把模态层叠在 `base` 上（没有弹窗时由调用方原样返回 `base`，这里是纯叠加）。
+///
+/// ## 三层的命中语义（r1 复审 P2-1 的修法）
+///
+/// ```text
+/// stack![ 页面树, 遮罩(mouse_area→Dismiss, 整窗), 居中容器(透明) → opaque(卡片) ]
+/// ```
+///
+/// 关键在于**卡片那层只有卡片那么大**：`opaque(卡片)` 的命中区就是卡片本身，点卡片里
+/// 只会被它吃掉（`shell.capture_event`），点卡片外则**继续往下走**到遮罩 → `Dismiss`。
+/// 反例（r1 抓到的原实现）：`mouse_area(整窗居中容器).on_press(Swallow)` —— 整窗都在它
+/// 的 bounds 里，任何一次卡片外点击都先被它捕获，遮罩永远收不到，于是「点遮罩关闭」
+/// 只存在于注释里。
+pub(crate) fn layer<'a>(
+    ui: &'a Ui,
+    base: Element<'a, Message>,
+    modal: &'a Modal,
+) -> Element<'a, Message> {
+    let backdrop = mouse_area(
+        container(Space::new())
+            .width(Length::Fill)
+            .height(Length::Fill)
+            .style(move |_theme| container::Style {
+                background: Some(Background::Color(backdrop_color(ui))),
+                ..container::Style::default()
+            }),
+    )
+    .on_press(Message::Dialog(DialogMessage::Dismiss));
+
+    // 透明的一层只负责居中；会吃点击的 `opaque` 只包卡片。
+    let centered = container(card_plane(ui, modal))
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .padding(ui.space(Sp::X6));
+
+    iced::widget::stack![base, backdrop, centered].into()
+}
+
+/// 遮罩色：**组件层那一份不透明预合成**（黑 @0.32 叠在画布上）。
+///
+/// 为什么不自己拿 `Role::OnSurface` 加 α：它在深色档是 **tone 90（近白）**，32% 铺上去会把
+/// 整窗**提亮**（r1 复审实测 (9,21,28) → (129,138,145)）；而且 α 混色在 wgpu/tiny-skia 两档
+/// 合成口径不同（linear vs sRGB），D27 要求 CPU 档零半透明。组件层 [`scrim`] 两件事都解决了。
+///
+/// 单独成函数是为了让 [`super::tests`] 断言**视图真正用的那一份**（P1 的守卫）。
+pub(super) fn backdrop_color(ui: &Ui) -> Color {
+    scrim(ui)
+}
+
+/// 卡片层：`opaque` 让「卡片内的点击」被吃掉，不再冒到遮罩（点遮罩才关）。
+///
+/// 可见性放宽到 `pub(super)` 只为让 [`super::tests`] 能断言它的 `size_hint`（P2-1 的守卫）。
+pub(super) fn card_plane<'a>(ui: &'a Ui, modal: &'a Modal) -> Element<'a, Message> {
+    iced::widget::opaque(card(ui, modal))
+}
+
+/// 卡片本体（**尺寸 = 内容**，不声明 `Fill` —— 见 [`layer`] 的命中语义）。
+fn card<'a>(ui: &'a Ui, modal: &'a Modal) -> Element<'a, Message> {
+    // 几何全部走组件层（r1 复审 P1 的纪律项：别绕过现成的 Dialog 档）。
+    let geometry = DialogGeometry::of(ui);
+    let shape = Component::Dialog.spec().shape;
+
+    // 头（标题 + 三句正文）与脚（按钮）**固定**，中间那段滚——按钮滚出屏幕等于功能不存在
+    // （视觉复审在日志页踩过同一坑：诊断卡把摘要页脚顶出去了）。
+    let mut header = column![].spacing(ui.space(Sp::X2)).width(Length::Fill);
+    header = header.push(role(
+        ui,
+        TypeRole::HeadlineSmall,
+        true,
+        modal.title.as_str(),
+    ));
+    for line in &modal.body {
+        header = header.push(wrapped(ui, line.as_str(), ui.color(Role::OnSurface)));
+    }
+
+    let mut middle = column![].spacing(ui.space(Sp::X2)).width(Length::Fill);
+    if let Some(card) = &modal.card {
+        // **详细说明在前、路径在后**：用户先要知道「发生了什么」，再要「文件在哪」。
+        if card.expanded {
+            if let Some(title) = &card.detail_title {
+                middle = middle.push(role(ui, TypeRole::LabelMedium, false, title.as_str()));
+            }
+            for line in &card.detail_lines {
+                middle = middle.push(mono(ui, line.clone()));
+            }
+            middle = middle.push(frame::divider(ui).map(Message::Page));
+        }
+        for (index, (label, path)) in card.paths.iter().enumerate() {
+            middle = middle.push(
+                button(
+                    column![
+                        role(ui, TypeRole::LabelMedium, false, label.as_str()),
+                        mono(ui, path.clone()),
+                    ]
+                    .spacing(0.0)
+                    .width(Length::Fill),
+                )
+                .width(Length::Fill)
+                .padding(0)
+                .style(|_theme, _status| button::Style {
+                    background: None,
+                    text_color: Color::TRANSPARENT,
+                    border: Border::default(),
+                    shadow: Shadow::default(),
+                    snap: true,
+                })
+                .on_press(Message::Dialog(DialogMessage::CopyPath(index))),
+            );
+        }
+    }
+
+    let mut footer = column![].spacing(ui.space(Sp::X1)).width(Length::Fill);
+    if let Some(notice) = &modal.notice {
+        footer = footer.push(wrapped(ui, notice.as_str(), ui.color(Role::Primary)));
+    }
+    footer = footer.push(actions(ui, modal));
+
+    // 中间那段给**定高**预算：`Shrink` 会让滚动区按内容高排版，把页脚顶到卡片外面
+    // （实测第一版就是这样：导出/关闭两个按钮整排不可见）。
+    let body = if modal.card.is_some() {
+        column![
+            header,
+            scrollable(middle).height(Length::Fixed(if modal.notice.is_some() {
+                SCROLL_HEIGHT_WITH_NOTICE
+            } else {
+                SCROLL_HEIGHT
+            })),
+            frame::divider(ui).map(Message::Page),
+            footer,
+        ]
+    } else {
+        column![header, frame::divider(ui).map(Message::Page), footer,]
+    }
+    .spacing(ui.space(Sp::X3))
+    .width(Length::Fill);
+
+    // 宽度取官方**上限** 560（`DialogGeometry::max_width`）而不是本项目默认 480：
+    // 崩溃卡片多两行路径 + 三枚辅助按钮，480 会把主按钮压成竖排（实测过）。
+    // 边界：组件层日后若改宽度，这里不会跟（已记 P3 台账）。
+    container(body)
+        .width(Length::Fixed(geometry.max_width))
+        .max_height(CARD_HEIGHT)
+        .padding(geometry.padding)
+        .style(move |_theme| container::Style {
+            background: Some(Background::Color(ui.layer(MaterialLayer::Overlay))),
+            border: ui.outlined(shape),
+            ..container::Style::default()
+        })
+        .into()
+}
+
+/// 底部按钮区：**两行**——辅助操作（开文件夹 / 复制路径 / 展开）在上，主次按钮在下靠右。
+///
+/// 为什么分两行：五个按钮塞一行在 560 的卡宽里会把主按钮压成竖排（实测第一版就是这样，
+/// 「导出诊断包」被挤成两行单字）。
+fn actions<'a>(ui: &'a Ui, modal: &'a Modal) -> Element<'a, Message> {
+    let mut column_actions = column![].spacing(ui.space(Sp::X2)).width(Length::Fill);
+
+    if let Some(card) = &modal.card {
+        column_actions = column_actions.push(
+            row![
+                buttons::outlined(
+                    ui,
+                    buttons::Button::new(
+                        card.actions[1].as_str(),
+                        Message::Dialog(DialogMessage::OpenFolder),
+                    ),
+                ),
+                buttons::outlined(
+                    ui,
+                    buttons::Button::new(
+                        card.actions[2].as_str(),
+                        Message::Dialog(DialogMessage::CopyPaths),
+                    ),
+                ),
+                buttons::text(
+                    ui,
+                    buttons::Button::new(
+                        card.toggle.as_str(),
+                        Message::Dialog(DialogMessage::Toggle),
+                    ),
+                ),
+            ]
+            .spacing(ui.space(Sp::X2))
+            .align_y(Alignment::Center),
+        );
+    }
+
+    let mut line = row![Space::new().width(Length::Fill)].spacing(ui.space(Sp::X2));
+    if let Some(secondary) = &modal.secondary {
+        line = line.push(buttons::text(
+            ui,
+            buttons::Button::new(
+                secondary.as_str(),
+                Message::Dialog(DialogMessage::Secondary),
+            ),
+        ));
+    }
+    if !modal.blocking_progress {
+        line = line.push(buttons::filled(
+            ui,
+            buttons::Button::new(
+                modal.primary.as_str(),
+                Message::Dialog(DialogMessage::Primary),
+            ),
+        ));
+    }
+    column_actions.push(line.align_y(Alignment::Center)).into()
+}
+
+/// 令牌排版档的文字（`pages::frame` 的那一套，映射成本层的消息类型）。
+fn role<'a>(
+    ui: &'a Ui,
+    role: TypeRole,
+    emphasized: bool,
+    content: &'a str,
+) -> Element<'a, Message> {
+    frame::text_role(
+        ui,
+        role,
+        emphasized,
+        content,
+        ui.color(Role::OnSurfaceVariant),
+    )
+    .map(Message::Page)
+}
+
+/// 等宽文字（路径 / 堆栈 / 捕获输出——这些必须能一眼看出字符边界）。
+fn mono<'a>(ui: &'a Ui, content: String) -> Element<'a, Message> {
+    let style = ui.style(TypeRole::BodySmall);
+    text(content)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        .font(Font {
+            family: iced::font::Family::Name(ui.families().mono),
+            ..Font::DEFAULT
+        })
+        .color(ui.color(Role::OnSurface))
+        .width(Length::Fill)
+        .wrapping(iced::widget::text::Wrapping::WordOrGlyph)
+        .into()
+}
+
+/// 正文一段：令牌排版档 + 按词折行（长路径只按词折会把卡片顶破）。
+fn wrapped<'a>(ui: &'a Ui, content: &'a str, color: Color) -> Element<'a, Message> {
+    let style = ui.style(TypeRole::BodyMedium);
+    text(content)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        .font(ui.font_of(style))
+        .color(color)
+        .width(Length::Fill)
+        .wrapping(iced::widget::text::Wrapping::WordOrGlyph)
+        .into()
+}

crates/app-iced/src/app/logs_folder.rs

@@ -0,0 +1,121 @@
+//! 「日志文件夹」在 app 侧的唯一解析口（M188）：路径从哪来、点了按钮之后开哪个目录。
+//!
+//! ## 为什么不在页面里现拼路径
+//!
+//! 日志根 = `<启动器数据目录>/logs`，而「启动器数据目录」是三模式解析（便携 / 标准 / 自定义）
+//! 的结果。那条解析链只有一份实现（`core::platform::data_dir` + `presenter::settings_bridge`），
+//! 页面若自己拼 `exe_dir/.ULL/logs`，标准模式与自定义模式的用户就会看到一个**不存在的目录**。
+//!
+//! 本模块只做两件事：
+//!
+//! 1. 从设置桥给定的 `config/launcher.json` 反推 `<home>`，再用 `LauncherLayout::logs()` 取分区
+//!    （分区名只从 core 的 `layout` 来，不手拼字符串）；
+//! 2. 打开前先确认目录真的在（不在就建），失败时给出的文本**带完整路径**——用户至少能照着去翻。
+//!
+//! ## 谁来登记
+//!
+//! `App::new` 拿到设置桥之后调 [`register`]：那是本进程唯一知道「实际生效的数据根」的地方
+//! （`--data-dir` 也在这里生效）。没登记时（`pages_demo` 出图通道、单测）退回
+//! `platform::data::layout()`——同一份解析链的缓存版本。
+
+use std::path::{Path, PathBuf};
+use std::sync::OnceLock;
+
+use unlucky_core::platform::layout::LauncherLayout;
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+static LOGS_DIR: OnceLock<Option<PathBuf>> = OnceLock::new();
+
+/// `<home>/config/launcher.json` → `<home>/logs`（**只有**这一条形状，别处不许手拼）。
+pub(crate) fn logs_dir_of(config: &Path) -> Option<PathBuf> {
+    let home = config.parent()?.parent()?;
+    Some(LauncherLayout::new(home).logs())
+}
+
+/// 登记本进程的日志目录（`App::new` 在第一帧之前调一次；重复调用以**第一次**为准）。
+pub(crate) fn register(bridge: &SettingsBridge) {
+    let _ = LOGS_DIR.set(bridge.path().and_then(logs_dir_of));
+}
+
+/// 本进程的日志目录。
+///
+/// - 已登记且解析出来 ⇒ 那条；
+/// - 已登记但解析不出来（内存态桥）⇒ `None`：页面照实说「数据根没解析出来」，不猜一个目录；
+/// - 还没登记（`pages_demo` / 单测）⇒ 退回 `platform::data::layout()`。
+pub(crate) fn logs_dir() -> Option<PathBuf> {
+    match LOGS_DIR.get() {
+        Some(known) => known.clone(),
+        None => crate::platform::data::layout().map(|layout| layout.logs()),
+    }
+}
+
+/// 确保日志目录存在（不在就建），返回给用户看的路径。
+///
+/// 失败文本里**带完整路径**：界面把这段话原样显示出来，用户能复制去自己找。
+pub(crate) fn prepare(dir: &Path) -> Result<PathBuf, String> {
+    std::fs::create_dir_all(dir)
+        .map_err(|error| format!("{}（这个目录建不出来：{error}）", dir.display()))?;
+    if !dir.is_dir() {
+        return Err(format!("{}（这个路径不是一个目录）", dir.display()));
+    }
+    Ok(dir.to_path_buf())
+}
+
+/// 打开日志文件夹：解析 → 确保存在 → 交给平台打开器。
+///
+/// # Errors
+///
+/// 返回的文本永远带路径（`...logs` 那一串），可以直接贴给用户/贴进 issue。
+pub(crate) fn open() -> Result<PathBuf, String> {
+    let dir = logs_dir().ok_or_else(|| {
+        "日志目录：数据根没解析出来（启动器拿不到自己所在的目录；用 --data-dir 指定一个）"
+            .to_string()
+    })?;
+    let dir = prepare(&dir)?;
+    crate::app::dialog::export::open_dir(&dir)?;
+    Ok(dir)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 落点形状：`<home>/config/launcher.json` → `<home>/logs`。
+    ///
+    /// 变异证明：把 `logs_dir_of` 里的 `LauncherLayout::logs` 换成 `cache`，这条立刻红。
+    #[test]
+    fn the_log_folder_is_the_logs_partition_next_to_config() {
+        let config = PathBuf::from("/tmp/ull-home/.ULL/config/launcher.json");
+        assert_eq!(
+            logs_dir_of(&config),
+            Some(PathBuf::from("/tmp/ull-home/.ULL/logs"))
+        );
+        // 少了 config 那一层就没有 `<home>` 可言：宁可不猜。
+        assert_eq!(logs_dir_of(Path::new("launcher.json")), None);
+    }
+
+    /// **目录真的存在**（守门③）：`prepare` 在不在时把它建出来，并且返回同一个路径。
+    ///
+    /// 变异证明：删掉 `create_dir_all` 那一行，`is_dir` 立刻为假。
+    #[test]
+    fn prepare_creates_the_folder_and_reports_the_same_path() {
+        let root = std::env::temp_dir().join(format!("ull-logs-folder-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&root);
+        let dir = root.join(".ULL/logs");
+        assert!(!dir.is_dir(), "夹具目录不该已经存在");
+        let prepared = prepare(&dir).expect("应当建得出来");
+        assert_eq!(prepared, dir);
+        assert!(dir.is_dir(), "打开之前必须真的存在");
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    /// 失败文本带路径（「不许只在成功时可用」）。
+    #[test]
+    fn a_failure_names_the_path_it_could_not_use() {
+        let file = std::env::temp_dir().join(format!("ull-logs-notadir-{}", std::process::id()));
+        std::fs::write(&file, b"x").expect("写夹具");
+        let error = prepare(&file).expect_err("一个文件不是目录");
+        assert!(error.contains(&file.display().to_string()), "{error}");
+        std::fs::remove_file(&file).ok();
+    }
+}

crates/app-iced/src/app/message.rs

@@ -0,0 +1,108 @@
+//! 应用消息：单一大枚举。
+//!
+//! 纪律：本枚举是**唯一**的消息类型，`view` 产出的所有回调都必须落到这里；组件库与页面层
+//! 各自用自己的 `Message`（组件契约 §2 的泛型纪律），由 `view` 做一次 `.map` 接上。
+//!
+//! ## 三类输入（M90）
+//!
+//! | 来源 | 变体 | 落点 |
+//! |---|---|---|
+//! | 窗口/框架 | `Boot` / `WindowReady` / `Window` / `Frame` / `Captured` / 三个 caption | [`super::update`] 直接处理 |
+//! | **时间** | `Frame`（忙碌，33 ms 闸门）+ `Heartbeat`（空闲，1 Hz） | presenter 的 TICK 节拍：`backend.tick` + `drain_events` + `apply` |
+//! | **页面** | `Page(pages::Message)` | 导航 → `AppState::navigate`；启动/停止 → `AppCommand` |
+
+use iced::{window, window::Direction};
+
+use unlucky_presenter::router::Route;
+
+use crate::pages;
+use crate::shell::NavItem;
+
+use super::components;
+
+/// 消息（单一大枚举）。
+#[derive(Debug, Clone)]
+pub enum Message {
+    /// 启动即发一次（`iced::application` 的 boot 闭包）。
+    Boot,
+    /// `window::latest()` 的结果。
+    WindowReady(Option<window::Id>),
+    /// 系统主题探测结果（只可能在**交互模式**出现，截图模式必有主题）。
+    SystemTheme(iced::theme::Mode),
+    /// 一帧画完。**只在需要 33 ms 节拍时订阅**：截图通道 / 有 Busy-Running 实例 / 有未过期
+    /// toast / 派发后的 3 s 观察窗（见 `subscription::needs_frames`）。
+    Frame,
+    /// **空闲态**的 1 Hz 心跳：`Task::perform(sleep(1s))` 的自续链，用来替代空闲时的帧循环
+    /// （M90 r3 / P2-2）。它保证 `theme::config_poll_due` 仍按「30 × 33 ms ≈ 1 秒」的
+    /// presenter 语义跑，外部 CLI/AI 改配置后主题 1 秒内生效。
+    Heartbeat,
+    /// 窗口事件（M90：`Resized` 决定布局档位，600 / 840 两条断点靠它生效）。
+    Window(window::Event),
+    /// 窗口句柄（M93：`window::run` 探测出的 raw handle；`None` = 拿不到，整窗 α 无法下发）。
+    WindowHandle(Option<isize>),
+    /// 页面消息（导航 / 启动 / 停止 / 占位动作）。
+    Page(pages::Message),
+    /// **AI 助手栏 / 独立页**的消息（M104：三档状态、输入框、拖拽、键盘）。
+    ///
+    /// 为什么不走 `pages::Message`：助手栏是**外壳级视图**（它挂在任何页面右边），不是某一页的
+    /// 消息；塞进页面枚举还要动 `app/update/page_messages.rs` 的穷尽 match（那个文件正被未合的
+    /// M101 改），绕开它就少一处 rebase 面。落点是 `app/update/agent.rs`。
+    Agent(crate::shell::agent::Message),
+    /// 外壳导航轨点选（`src/shell/nav.rs` 的回调仍然发这一条；收到就翻成同一个路由跳转）。
+    ///
+    /// M90 起产品界面用 `pages` 里的真 `NavigationRail`，这条变体是给**外壳回退路径**
+    /// （`Route::Agent`）留的——`shell` 不在本 mission 的 scope 里，不能删它的消息。
+    Select(NavItem),
+    /// 按下标题栏 → 拖窗。
+    DragWindow,
+    /// 边缘热区：开始缩放（方向由坐标决定）。
+    ResizeStart(Direction),
+    /// 最小化。
+    Minimize,
+    /// 最大化/还原。
+    ToggleMaximize,
+    /// 关窗退出。
+    Close,
+    /// 截图回来了。
+    Captured(window::Screenshot),
+    /// gallery（组件库 harness）里的演示交互。
+    Demo(components::gallery::DemoMessage),
+    /// 模态对话框（M187）：主/次按钮、遮罩、展开、导出、打开文件夹、复制路径。
+    Dialog(super::dialog::Message),
+    /// 导入已有版本向导（M223）：打开 / 选版本 / 选目标 / 预检 / 确认 / 关闭。
+    ///
+    /// 落点是 `app/update/adopt.rs`。页面只发一条入口意图
+    /// （`pages::Message::Action(pages::Action::Import)`），向导自己的四段状态都在这里收口。
+    Adopt(super::adopt::AdoptMessage),
+}
+
+/// 外壳导航项 → 路由（导航项只在一级页之间有对应；AI 项对应 [`Route::Agent`]）。
+///
+/// 这是 `NavItem → Route` 的**唯一**转换点：外壳（`src/shell/nav.rs`）与页面导航轨
+/// （`pages::NAV`）最终都落到同一个 `Route`，所以两条入口不会各走一套页面语义。
+pub(super) fn route_of(nav: NavItem) -> Route {
+    match nav {
+        NavItem::Instances => Route::Instances,
+        NavItem::Download => Route::Download,
+        NavItem::Logs => Route::Logs,
+        NavItem::Settings => Route::Settings,
+        NavItem::Ai => Route::Agent,
+        // 轨底头像位（M114）：账户是一级页，但**不在主序列**里
+        NavItem::Account => Route::Accounts,
+    }
+}
+
+/// 路由 → 外壳导航项（[`route_of`] 的逆；外壳 rail 与 caption 键都按它高亮）。
+///
+/// `Route::Detail(_)` 高亮「实例」（与 `Route::nav()` 同源）。
+pub(super) fn nav_item_of(route: &Route) -> NavItem {
+    match route {
+        Route::Instances | Route::Detail(_) => NavItem::Instances,
+        // M109：内容库与版本管理共用「下载」那一个导航项（B1 裁定）
+        Route::Download | Route::Content => NavItem::Download,
+        Route::Logs => NavItem::Logs,
+        Route::Settings => NavItem::Settings,
+        Route::Agent => NavItem::Ai,
+        Route::Accounts => NavItem::Account,
+    }
+}

crates/app-iced/src/app/mod.rs

@@ -0,0 +1,75 @@
+//! Elm 三件套：`State` / `Message` / `update` + `view` 接线，以及启动序列。
+//!
+//! 启动序列：①探测渲染后端并写 `ICED_BACKEND`（必须在 `run()` 之前，M60 Q1）→ ②求值字体栈
+//! （D28 前半）→ ③`iced::application(..).run()`（1180×760、无边框自绘标题栏）→ ④首个 `view()`
+//! 打耗时；截图模式第 3 帧落盘后退出（无边框窗首帧可能是旧尺寸，M60 坑 #5）。
+//!
+//! ## 为什么拆成目录（M90）
+//!
+//! 本文件原来是**单个 400 行的 `app.rs`**：正好卡在「单文件 ≤400 行、动它前必须先拆」的硬门槛上
+//! （AGENTS 的文件上限 + 本 mission 的第一条任务）。拆法与职责：
+//!
+//! | 文件 | 职责（**只做这一件事**） |
+//! |---|---|
+//! | [`state`] | [`App`] 字段 + 构造（presenter 三件在此持有）+ 主题切换 |
+//! | [`message`] | [`Message`] 枚举与「导航项 → 路由」的翻译 |
+//! | [`update`] | 全部 `Message` 分支 + 「用户动作 → `AppCommand`」的派发与事件回流 |
+//! | [`subscription`] | 帧事件（截图）与 presenter 的 TICK 节拍 |
+//! | [`view`] | `view` / `theme` / `title` |
+//! | [`boot`] | [`run`]：后端探测 → 字体 → `iced::application(..)` |
+//!
+//! 拆分的每一步都保持**可观察行为不变**（截图四件套 `--screenshot` / `--screenshot-theme` /
+//! `--screen=gallery` / `--diff` 出图逐字节相同），presenter 接线是在拆分**之后**另一步做的。
+//!
+//! ## 组件库为什么还在本模块下声明
+//!
+//! `src/lib.rs` 是五条组件线共用的文件，改它必然冲突；`#[path]` 保证物理路径仍是
+//! `src/components/`（组件目录自己的归属规则不变），逻辑路径仍是 `crate::app::components`
+//! （组件源码里的文档与测试都按这个路径写）。
+
+mod adopt;
+mod appearance;
+mod backend;
+mod boot;
+pub(crate) mod diag;
+mod dialog;
+pub(crate) mod logs_folder;
+mod message;
+mod state;
+mod subscription;
+mod update;
+mod view;
+mod window_alpha;
+
+#[cfg(test)]
+mod tests;
+
+pub(crate) use boot::run;
+pub use message::Message;
+
+// 组件库（D39）在本文件声明：`src/lib.rs` 是五条组件线共用的文件，改它必然冲突；
+// `#[path]` 保证物理路径仍是 `src/components/`（组件目录自己的归属规则不变）。
+//
+// M90：可见性从 `mod` 放到 `pub(crate) mod` —— 页面层（`src/pages/**`）要**用**真组件
+// （`components::buttons` / `navigation` / `divider`），而 `app` 不是它的父模块。
+// 只放开 crate 内可见，组件目录的归属规则一字不改。
+#[path = "../components/mod.rs"]
+pub(crate) mod components;
+
+/// 验收窗口尺寸（1180×760 @100% DPI —— D30 的硬要求）。
+pub const WINDOW_SIZE: iced::Size = iced::Size {
+    width: 1180.0,
+    height: 760.0,
+};
+
+/// 产品名（自绘标题栏的标题；`'static` 好让 view 借用）。
+pub const APP_TITLE: &str = "Unlucky Launcher";
+
+/// 窗口最小尺寸（再小骨架会挤坏：88 导航 + 页面留白 + 卡片）。
+const MIN_SIZE: iced::Size = iced::Size {
+    width: 880.0,
+    height: 560.0,
+};
+
+/// 截图落盘的帧号（见模块文档）。
+const CAPTURE_AT_FRAME: u32 = 3;

crates/app-iced/src/app/state.rs

@@ -0,0 +1,246 @@
+//! 应用状态：**只放字段与构造**，不放消息分支（那是 [`super::update`] 的事）。
+//!
+//! ## presenter 三件（`crates/presenter/src/lib.rs` crate 文档 §4）
+//!
+//! | 字段 | 谁给 | 干什么 |
+//! |---|---|---|
+//! | `backend: Box<dyn Backend>` | [`build_backend`](unlucky_presenter::backend::build_backend) | 派发 [`AppCommand`](unlucky_presenter::dto::AppCommand)、收 [`AppEvent`](unlucky_presenter::dto::AppEvent) |
+//! | `bridge: SettingsBridge` | [`SettingsBridge::open`](unlucky_presenter::settings_bridge::SettingsBridge::open) | 读一次外观/主题，之后每 N 拍问「文件变了吗」 |
+//! | `state: AppState` | [`AppState::new`](unlucky_presenter::state::AppState::new) | **唯一**的状态写入口（`apply` / `navigate`） |
+//!
+//! `view: pages::Model` 是**展示转换的缓存**：presenter 快照 → 页面要画的东西。
+//! 它在**状态真的变了**时重建（[`App::view_dirty`] 门控，M90 r2/P2-1 起），不是每拍重建——
+//! 重建要把 N 个实例的名字/版本串克隆一遍，30 Hz 空转没有意义。缓存成字段是为了让
+//! `view(&self)` 能只借 `&self`：iced 的 `view` 签名不允许返回一棵借用局部变量的树。
+//!
+//! ## 本文件只管「有哪些字段」
+//!
+//! M119 起按功能拆出去（`state.rs` 当时正好 400 行、零余量）：
+//!
+//! | 子文件 | 内容 |
+//! |---|---|
+//! | [`construct`] | 两个构造器 + 字段初始化表 |
+//! | [`refresh`] | [`App::refresh_view`]（快照 → 视图模型的唯一转换点） |
+//! | [`theme`] | `Ui` 重算 / 主题档 / [`App::has_screenshot`] |
+//! | [`boot_probe`] | 启动探针（`ULL_*` 取证开关与首帧日志） |
+
+use std::time::Instant;
+
+use iced::window;
+
+use unlucky_presenter::dto::Backend;
+use unlucky_presenter::prefs::ThemeMode;
+use unlucky_presenter::settings_bridge::SettingsBridge;
+use unlucky_presenter::state::AppState;
+
+use crate::cli::Options;
+use crate::pages;
+use crate::theme::{Families, Ui};
+use crate::ui::lang::LangState;
+
+/// presenter 的 TICK 节拍（33 ms ≈ 30 fps）——**忙碌态**的节拍。
+///
+/// 与 Slint 版的 `TICK_MS` 同值：`backend.tick(..)` 的时间推进、toast 过期、
+/// `theme::config_poll_due` 的计数都按这个节拍走，两个 UI 版的时间语义因此一致。
+pub(super) const TICK_MS: u64 = 33;
+
+/// [`TICK_MS`] 的 `Duration` 形态。
+pub(super) const TICK: std::time::Duration = std::time::Duration::from_millis(TICK_MS);
+
+/// **空闲态**的低频心跳（1 Hz，M90 r3 / P2-2）。
+///
+/// 空闲时不能订阅 `window::frames()`：那条订阅会自持重绘循环（实测软件渲染约 500 帧/秒），
+/// 而空闲时唯一需要的时钟是「偶发一次」——外部 CLI / AI 工具改 `launcher.json` 后的热切
+/// （presenter 的 `theme::config_poll_due` 语义是 30 × 33 ms ≈ 1 秒一拍）。
+///
+/// 实现用的是 `Task::perform(async { sleep(1s) })` 的自续链：[`App::heartbeat`]。它每秒只唤醒
+/// 一次、只触发**一帧**重绘，而 `frames()` 是每秒几百帧。为什么不用 `iced::time::every`：
+/// 它挂在 tokio/smol 后端下，本 crate 的执行器是 thread-pool（Cargo.toml 不在 scope）。
+///
+/// **M192 的第三条时钟不在这里**：动效（`components::motion`）也只在「有轨道」时借用帧订阅，
+/// 最后一个轨道到期就清空 ⇒ 下一拍 [`App::needs_frames`] 自动退回这条 1 Hz 心跳。
+pub(super) const IDLE_TICK: std::time::Duration = std::time::Duration::from_secs(1);
+
+/// 派发指令后保持帧订阅的观察窗（见 [`App::watch_until`]）。
+///
+/// 3 秒够真 host 把「命令已受理」的第一条事件交回来；之后由「有 Busy/Running 实例」这个条件续订。
+pub(super) const WATCH_WINDOW: std::time::Duration = std::time::Duration::from_secs(3);
+
+mod boot_probe;
+// M224: 出图取证用的 MODS 夹具（`ULL_MODS_FIXTURE`；产品路径零影响）
+mod construct;
+mod mods_shot;
+mod refresh;
+// M235: 出图取证用的 SAVES 夹具（`ULL_SAVES_FIXTURE=1`）
+mod saves_shot;
+mod theme;
+
+/// iced 侧的 presenter 接线层（M119）：物理目录 `src/presenter/`，逻辑名字在 `crate::app::state` 下。
+///
+/// 为什么用 `#[path]` 而不是在 `lib.rs` 加一行 `mod presenter;`：本 mission 的 scope 不含
+/// `lib.rs` / `app/mod.rs`，而 `shell::agent` 挂 `pages/agent/` 是同一个先例。没有第二份实现。
+#[path = "../presenter/mod.rs"]
+pub(super) mod presenter;
+
+pub(crate) use boot_probe::{log_first_frame, STARTED};
+
+/// 应用状态：UI 状态 + presenter 三件 + 展示转换缓存。
+pub struct App {
+    /// 启动参数（截图/主题/画面开关）。
+    pub(super) options: Options,
+    /// 字体族（切主题时重建 [`Ui`] 要用）。
+    pub(super) families: Families,
+    /// 令牌求值器（浅/深两套）。
+    pub(super) ui: Ui,
+    /// 后端通道（真 host 或 mock）。
+    pub(super) backend: Box<dyn Backend>,
+    /// 设置持久化桥。
+    pub(super) bridge: SettingsBridge,
+    /// presenter 的全局状态（唯一写入口是 `apply`）。
+    pub(super) state: AppState,
+    /// 已推进的拍数（`theme::config_poll_due` 的输入）。单位是 **33 ms 一拍**，不是调用次数。
+    pub(super) ticks: u64,
+    /// 下一次「比对配置文件 mtime」的 tick 号（见 `update::advance` 的注释）。
+    pub(super) config_due_at: u64,
+    /// 设置文件里的主题模式（`auto` / `light` / `dark`）。
+    ///
+    /// 用来定优先级：`--theme` > 配置文件 > 系统主题。没有它，`Message::SystemTheme` 会无条件
+    /// 盖掉配置文件的显式主题（M90 r3 修）。
+    pub(super) theme_mode: ThemeMode,
+    /// 界面语言（M106）：用户档位 + 探测结论 + 目录选择。见 [`crate::ui::lang`]。
+    ///
+    /// 为什么不在 `Ui` 里：`theme.rs` 是令牌求值器（颜色/字号），而语言是**运行期状态**——
+    /// 随设置变、要落盘、要重建视图模型（切主题只重建 Style）。
+    pub(super) lang: LangState,
+    /// 上一次推进节拍的时刻（节拍由帧事件驱动，按真实流逝时间累加）。
+    pub(super) last_tick: Instant,
+    /// 窗口宽度（布局档位的判据；交互模式跟着 resize 事件走）。
+    pub(super) width: f32,
+    /// 展示转换缓存（presenter 快照 → 页面视图模型）。
+    pub(super) view: pages::Model,
+    /// 视图模型是否过期（P2-1）：只有 `apply` / `navigate` / resize / 主题这类**真的改了状态**
+    /// 的事情才置位，`advance()` 每拍只在置位时重建模型（否则 30 Hz × N 实例的白克隆）。
+    pub(super) view_dirty: bool,
+    /// 「刚派发过指令，等后端回事件」的观察窗（P2-1）。
+    ///
+    /// 空闲态**不订阅帧事件**（只有 1 Hz 的 `heartbeat`），所以派发之后必须有这段短窗口让
+    /// 33 ms 节拍跑起来，否则真 host 的异步事件永远抽不出来。
+    ///
+    /// 空闲态不订阅帧事件（不点亮窗口重绘），但派发之后必须有一段短窗口保持节拍，
+    /// 否则真 host 的异步事件永远抽不出来（`LaunchInstance` 之后状态还是 Idle ⇒ 帧订阅永不开启）。
+    pub(super) watch_until: Option<Instant>,
+    /// 窗口句柄（`window::latest()` 之后才有）。
+    pub(super) window: Option<window::Id>,
+    /// 已画的帧数（截图闸门用）。
+    pub(super) frames: u32,
+    /// 视图模型重建次数（P2-1 的可观测计数：空闲态 100 拍里必须是 0 增长）。
+    pub(super) refreshes: u64,
+    /// 首屏快照到位后是否已经自动选中过第一行（list-detail 的桌面惯例，见 `update::auto_select`）。
+    pub(super) auto_selected: bool,
+    /// 上一次看到的**中文字体下载状态**（M168）。
+    ///
+    /// 下载在后台线程里推进，状态是一份进程级快照（`fonts::install::status`）。这里存一份是为了
+    /// 「变了才重建视图模型」：设置页那一行因此自己会从「正在获取」翻成「已就绪 / 失败」，
+    /// 而空闲态不会为了它每拍白重建一次。
+    pub(super) font_seen: crate::fonts::install::CjkInstall,
+    /// 窗口高度（背景图平铺网格的视口判据；宽度在 `width`）。
+    pub(super) height: f32,
+    /// 外观运行期状态（M93）：面板 α / 背景图 / 配色来源 / 诊断。
+    pub(super) appearance: pages::appearance::State,
+    /// 设置文件里那 8 个「UI 写入」外观字段的最近快照（写回时只改我们真改了的字段，
+    /// 没动过的字段原样保留；M250 起强调色也在「真改了」的那一列里）。
+    pub(super) appearance_prefs: unlucky_presenter::prefs::AppearancePrefs,
+    /// 窗口句柄（`Message::WindowHandle` 之后才有；非 Windows 平台恒 `None`）。
+    pub(super) hwnd: Option<isize>,
+    /// 设置页各组自己的运行期状态（M101 r2 的**状态漏斗**）。
+    ///
+    /// 所有者在 `pages/settings/state.rs` 的 `Groups`：加/改某一组的字段只改那一组自己的文件，
+    /// 本字段与 `app/view.rs` 都不用动（`settings::States` 只看 `&Groups`，不看任何一组的字段）。
+    /// 放在字段列表**末尾**：后续 mission 若也要往这里加字段，冲突面最小。
+    pub(super) settings: pages::settings::Groups,
+    /// AI 助手栏的 UI 状态（M104）：右栗三档 + 展开宽度 + 草稿/焦点。
+    ///
+    /// 挂在 `App` 上而不是全局：这棵树在 `view(&self)` 里只读、在 `update(&mut self)` 里改，
+    /// 状态跟着 App 走才能 per-app、可测（tower 明确否掉了 `OnceLock<Mutex<..>>`）。
+    ///
+    /// **只留 UI 态**：会话内容 / 未读 / busy 在 `agent_host` 的 rail 上（M119 起）。
+    pub(super) agent: crate::shell::agent::AgentUi,
+    /// AI 助手的 presenter 句柄（M119）：四个契约 + 事件队列 + 具名错误。
+    ///
+    /// 为什么单独一份 `AppState` 而不是把 `state` 交给它：`Presenter` 的可写状态后门
+    /// （`state_mut`）只在 presenter crate 的 `#[cfg(test)]` 里存在，而 `app/subscription.rs`
+    /// 等处仍要直读 `App.state`。所以口径是——**`App.state` 管除 rail 外的一切，这个句柄管 rail**；
+    /// `AppEvent::Agent` 只喂这里（`App.state.ai` 从此不再被读，也不再被写）。
+    pub(super) agent_host: presenter::AgentHost,
+    /// 下载页的安装草稿（M105：选中版本 + 加载器 + 加载器版本 + 实例名）。
+    ///
+    /// 为什么住在 `App` 而不是页面模型：`refresh_view` 每次事件都把 `self.view` 整棵重建，
+    /// 页面自己存不住「用户正在填但还没确认」的东西；这与分类筛选（`view.download.category`）
+    /// 是同一个理由、同一个做法。
+    pub(super) download_draft: pages::InstallDraft,
+    /// 已经提示过的取消次数（M105）：`AppState::install_cancelled` 是「发生过几次取消」，
+    /// 这里是「其中几次已经弹过提示」。两者不等 ⇒ 弹一次 i18n 提示。
+    pub(super) install_cancelled_seen: u64,
+    /// 已经提示过的启动收尾次数（M161）：`AppState::launch_ends` 是「收尾过几场」，
+    /// 这里是「其中几场已经弹过 Toast」。两者不等 ⇒ 弹一次（与 `install_cancelled_seen` 同构）。
+    pub(super) launch_ends_seen: u64,
+    /// 已经提示过的启停失败（M224）：`(实例, 文件, 大类)`。同一条失败重复到达不重弹。
+    ///
+    /// 为什么不用计数器（与上面两条不同）：失败是**并发可交错**的（A 的文件失败、B 的列表成功、
+    /// A 又失败），计数差说明不了"哪一条没提示过"，三元组才是幂等键。
+    pub(super) mods_failed_seen: Option<(String, String, unlucky_presenter::dto::ModFailureKind)>,
+    /// 内容库页的页面内选择（M109）：内容类型 / 选中项目 / 目标实例 / 关键词草稿。
+    ///
+    /// 为什么在 `App` 而不是 presenter：这四样是「用户在这一屏上点了什么」，重建快照不该冲掉；
+    /// 而检索条件与结果（会跨页存活、要被事件写）在 `AppState::content`。放进 `view` 模型也
+    /// 不行——`refresh_view` 每次都用快照重建模型，选择会被冲回默认值。
+    pub(super) content: pages::content::PageState,
+    /// 账户页的**表单状态**（三条轨道的输入串；密码只活在这一次请求里）。
+    pub(super) account_form: pages::account::Form,
+    /// 账户页视图模型（与 `view` 同一条「状态变了才重建」的门控）。
+    pub(super) account: pages::account::Page,
+    /// 实例页「启动参数」区的表单（M157）：五项 + 脏标记 + 绑定的实例 id。
+    ///
+    /// 住在 `App` 的理由与 `download_draft` 完全一致：`refresh_view` 每次都整棵重建
+    /// `pages::Model`，用户正在输入的内容存不到视图模型里。重播种点在
+    /// [`App::refresh_view`]（`LaunchForm::sync`，换实例必重播种、同实例的脏草稿不覆盖）。
+    pub(super) launch_form: pages::LaunchForm,
+    /// 实例页「导入已有版本」向导的表单态（M223）：选中版本 / 展示名 / 目标档 / 在等回程。
+    ///
+    /// 住在 `App` 的理由与 `launch_form` 一致：向导跨帧（扫描 → 选 → 预检 → 确认），
+    /// 而候选/预检/失败/完成这些**事件真相**在 `AppState.adopt`（presenter），不在这里。
+    pub(super) adopt_form: super::adopt::Form,
+    /// 启动失败弹窗的**事实**（M187）：与 `state.dialogs` 里的当前条按 id 绑定。
+    ///
+    /// 为什么事实不塞进 `DialogRequest`：那是 presenter 的公共 DTO，弹窗与「这次失败的现场」
+    /// 是两件事——队列管弹窗的排队与按钮，卡片管证据（路径 / 崩溃摘要 / 捕获输出）。
+    pub(super) dialog_card: Option<super::dialog::CrashCard>,
+    /// 弹窗的**视图模型**（在 [`App::refresh_view`] 里重建；`view()` 只借它）。
+    ///
+    /// 为什么不像页面那样现算：`Element` 借字符串，现算的模型是局部变量，`view()` 一返回就
+    /// 悬空（编译期就过不去）。与 `view` / `account` 两张缓存同一条理由、同一个门控。
+    pub(super) dialog_model: Option<super::dialog::Modal>,
+    /// 皮肤/头像解码缓存（M114：同一张皮肤只解一次）。
+    pub(super) avatars: pages::account::avatar::Cache,
+    /// 上一次**真下发过**的圆角判定指纹（M116 r1 复审 P2-4：判定没变就不重下、不重记日志）。
+    ///
+    /// `None` = 还没下发过（首屏 `boot` 那一次）。指纹类型见
+    /// [`crate::platform::win32::corner::CornerApplied`]。
+    pub(super) corner_applied: Option<crate::platform::win32::corner::CornerApplied>,
+}
+
+impl App {
+    /// iced 侧的**设置组快照**（M201）：presenter 的 `CoreEvent::SettingsChanged` 回流进来的那一份。
+    ///
+    /// 真值只有一份——presenter 的 `AppState::settings_groups`（`apply_core` 是它唯一的写入口，
+    /// 由 host 的 `refresh_all` / `SetSetting` 分支发出来）。这里**不另存一个字段**：那会变成第二份
+    /// 真相，两份在 `pump` 之间必然有一步不一致（而「界面上是旧值、盘上是新值」正是本 mission 要
+    /// 消灭的形状）。要画的那一份是 [`pages::Model::settings`]（`refresh_view` 里从同一个字段克隆）。
+    ///
+    /// `#[cfg(test)]`：产品路径不需要这个入口（页面拿的是 `Model.settings`，同一份数据的投影），
+    /// 断言需要它——「App 认的值变了吗」必须能直接从 App 上问，不能去问页面模型（那是下游）。
+    #[cfg(test)]
+    pub(crate) fn settings_snapshot(&self) -> &[unlucky_presenter::dto::SettingGroupView] {
+        &self.state.settings_groups
+    }
+}

crates/app-iced/src/app/state/boot_probe.rs

@@ -0,0 +1,61 @@
+//! 启动期取证：后端选项的换算 + 首帧耗时那一行日志。
+//!
+//! 从 `app/state.rs` 拆出（rebase 到 5adac23 之后 `state.rs` 顶到 401 行）。这两件事都属于
+//! 「进程启动那一刻记了什么」，与 `App` 的状态机无关；`state.rs` 只留 `pub(super) use` 再导出，
+//! 于是 `app/boot.rs`（`use super::state::STARTED`）与 `app/view.rs`（`log_first_frame`）的既有路径一字未变。
+
+use crate::app::diag::diag;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::OnceLock;
+use std::time::Instant;
+
+use crate::cli::Options;
+use unlucky_presenter::backend::AppOptions;
+
+/// 进程内「run() 开始」的时刻（首帧耗时基线）。
+pub(crate) static STARTED: OnceLock<Instant> = OnceLock::new();
+/// 首帧日志只打一次。
+static FIRST_FRAME_LOGGED: AtomicBool = AtomicBool::new(false);
+
+/// 启动参数 → presenter 的后端选项。
+pub(super) fn app_options(options: &Options) -> AppOptions {
+    AppOptions {
+        // `--data-dir`：M90 起**真的消费**它（此前是「接受并忽略」的翻牌兼容参数）。
+        // 截图通道强制 mock，所以 CI 冒烟那条 `--data-dir <tmp>` 不会往那个目录写东西。
+        data_root: options.data_dir.clone(),
+        mock: options.screenshot.is_some() && !real_host_in_screenshot(),
+    }
+}
+
+/// 取证开关 `ULL_SCREENSHOT_REAL_HOST=1`：让**截图通道**接真 host（默认关）。
+///
+/// ## 为什么需要它（M201）
+///
+/// 截图通道恒 `mock: true`（D30：同一份代码出同一张图），而 `MockBackend` **不发**
+/// `CoreEvent::SettingsChanged` ⇒ 设置页拿不到任何真值，只能拍演示行。可「设置页里改了就生效」
+/// 这件事的正脸图**必须带真值**：M193 用户的投诉就是「图上有 8 threads，追下去是假的」。
+/// 这条开关把出图的**数据源**换成真 host（`--data-dir` 指一个临时根），渲染通道与落盘一字不改。
+///
+/// ## 边界（别把它当产品行为）
+///
+/// - 默认关；开了它就不再满足 D30 的可复现（数据来自磁盘，两台机器会不同），所以**只用于取证**；
+/// - 它只改 `mock` 这一位，不碰任何业务分支（`build_backend` 的其余两条路仍然照旧）；
+/// - 与 `ULL_START_ROUTE` / `ULL_SETTINGS_GROUP` 同一族：只影响这一次进程。
+fn real_host_in_screenshot() -> bool {
+    std::env::var("ULL_SCREENSHOT_REAL_HOST")
+        .ok()
+        .is_some_and(|raw| raw.trim() == "1")
+}
+
+/// 首帧耗时日志（只在第一次 `view()` 打一行）。
+pub(crate) fn log_first_frame() {
+    if FIRST_FRAME_LOGGED.swap(true, Ordering::Relaxed) {
+        return;
+    }
+    if let Some(started) = STARTED.get() {
+        diag!(
+            "[boot] first frame in {:.0} ms（run() 开始 → 首次 view，含后端探测与字体扫描）",
+            started.elapsed().as_secs_f64() * 1000.0
+        );
+    }
+}

crates/app-iced/src/app/state/construct.rs

@@ -0,0 +1,185 @@
+//! `App` 的两个构造器（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。
+//!
+//! | 构造器 | 谁用 | 碰不碰磁盘 |
+//! |---|---|---|
+//! | [`App::new`](super::App::new) | 生产（`main` → `boot`） | 按启动参数选后端 + 打开设置桥 |
+//! | [`App::with_presenter`](super::App::with_presenter) | 单测（后端与桥都由调用方给） | **不碰** |
+//!
+//! 两个都走 `with_presenter`：生产路径只是先造好后端与桥。**字段初始化表**也在这一个文件里
+//! （构造 = 字段表 + 三件外部依赖），加字段时只改这一处。
+
+use iced::window;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_presenter::backend::{build_backend, config_path};
+use unlucky_presenter::dto::Backend;
+use unlucky_presenter::prefs::ThemeMode;
+use unlucky_presenter::settings_bridge::SettingsBridge;
+use unlucky_presenter::state::AppState;
+
+use crate::cli::Options;
+use crate::pages;
+use crate::theme::{Families, Ui};
+use crate::ui::lang::LangState;
+
+use super::super::WINDOW_SIZE;
+use super::boot_probe::app_options;
+use super::App;
+
+impl App {
+    /// 生产构造：按启动参数选后端、打开设置桥。
+    ///
+    /// **截图通道强制 mock**：出图要可复现（D30），真 host 会按本机盘上的实例清单画面，
+    /// 同一份代码在两台机器上出不了同一张图。交互模式走真 host（数据根解析不出来时
+    /// [`build_backend`] 自己退回 mock）。
+    pub(in crate::app) fn new(options: Options, families: Families, flavor: SchemeFlavor) -> Self {
+        let backend = build_backend(&app_options(&options));
+        // P2-2：设置桥必须与后端指向**同一个数据根**。早先这里无条件 `SettingsBridge::open()`
+        // （按便携配置解析），于是 `--data-dir X` 会出现「实例来自 X、主题/设置读写默认根」的一进程
+        // 两个数据根。Slint 版是同一条口径：`app/src/ui_bind.rs` 的
+        // `Some(root) => SettingsBridge::with_path(config_path(root))`。
+        let bridge = match &options.data_dir {
+            Some(root) => SettingsBridge::with_path(config_path(root)),
+            None => SettingsBridge::open(),
+        };
+        // M188：日志目录也在这一拍登记——它是从**同一份**设置桥反推的（`--data-dir` 同样生效），
+        // 所以设置页显示的路径与 `launcher.log` 的真实落点不会各说各话。
+        crate::app::logs_folder::register(&bridge);
+        Self::with_presenter(options, families, flavor, backend, bridge)
+    }
+
+    /// 注入式构造（单测用：后端与桥都由调用方给，**不碰磁盘**）。
+    pub(in crate::app) fn with_presenter(
+        options: Options,
+        families: Families,
+        flavor: SchemeFlavor,
+        backend: Box<dyn Backend>,
+        bridge: SettingsBridge,
+    ) -> Self {
+        let width = WINDOW_SIZE.width;
+        let height = WINDOW_SIZE.height;
+        // 主题档：截图通道**不读机器配置**（D30：同一份代码在两台机器上要出同一张图）——
+        // 由 `--screenshot-theme` 钉死（浅 → Silver / `light`，深 → Ink / `dark`）。
+        // 产品路径才读 `appearance.theme_mode`。复审 P2：此前这里两种通道都读文件，
+        // 设置页「主题」那一行的选中态会随出图机器的配置漂移。
+        let theme_mode = match options.screenshot.is_some() {
+            true => match options.shot_flavor().unwrap_or(SchemeFlavor::Light) {
+                SchemeFlavor::Light => ThemeMode::Light,
+                SchemeFlavor::Dark => ThemeMode::Dark,
+            },
+            false => bridge.load().1,
+        };
+        // 外观两半分开读：`load()` 给 8 个 UI 写入字段，`load_base()` 给 4 个只读下层键
+        // （整窗 α / 标题栏三态 / 配色来源 / 窗口圆角）。M93 之前这些键在 app 侧**根本读不到**。
+        //
+        // 截图通道**不读用户配置**（D30：同一份代码在两台机器上要出同一张图）：外观一律取出厂值，
+        // 矩阵需要的值由 `ULL_APPEARANCE_*` 显式灌进来。
+        let (appearance_prefs, appearance_base) = if options.screenshot.is_some() {
+            (
+                unlucky_presenter::prefs::AppearancePrefs::factory(),
+                unlucky_presenter::prefs::AppearanceBase::factory(),
+            )
+        } else {
+            (bridge.load().0, bridge.load_base())
+        };
+        // 面板 α / 玻璃的降级判据要的是**实际**后端，不是 `--renderer` 的请求值（复审 r1 P2-2）：
+        // 默认 `Auto` + 无独显时请求是 Auto、实际是 tiny-skia，只看请求值就会漏掉 D36 的强制项。
+        let backend_tier = super::super::backend::effective_backend(options.backend);
+        let mut appearance = pages::appearance::State::new(
+            &appearance_prefs,
+            &appearance_base,
+            backend_tier,
+            flavor,
+        );
+        // 取证开关（D30）：`ULL_SETTINGS_GROUP=<下标>` 直达设置页的某一组（出图要看见语言行）。
+        if let Some(index) =
+            crate::ui::lang::screenshot_settings_group(options.screenshot.is_some())
+        {
+            appearance.selected_group = index;
+        }
+        // 界面语言（M106）：**M92 已经探测对了，问题是一直没人用**——`pages::Model.lang` 此前在
+        // `view::model` 里被写死成 `Lang::En`，于是中文系统上开出来的是全英文界面。
+        let lang = LangState::boot(&bridge, options.screenshot.is_some());
+        // M168（复审 r2 P2-2）：出图通道**不许联网**——`log_cjk` 那一拍会走 `after_probe`，
+        // 一台 zh-locale 且没有中文字体的机器上会真的下 17 MiB，并可能在出图过程中注册新字体
+        // （D30：同一份代码要出同一张图）。产品路径不设这个开关。
+        crate::fonts::install::set_offline(options.screenshot.is_some());
+        let mut view = pages::Model::new(
+            pages::Screen::Instances,
+            width,
+            height,
+            Some(pages::Screen::Instances.nav()),
+        );
+        view.lang = lang.lang();
+
+        let mut app = Self {
+            ui: Ui::new(flavor, families),
+            families,
+            options,
+            backend,
+            bridge,
+            state: AppState::new(),
+            ticks: 0,
+            config_due_at: unlucky_presenter::theme::CONFIG_POLL_TICKS,
+            theme_mode,
+            lang,
+            last_tick: std::time::Instant::now(),
+            width,
+            view,
+            view_dirty: false,
+            watch_until: None,
+            window: None::<window::Id>,
+            frames: 0,
+            refreshes: 0,
+            auto_selected: false,
+            // M168：中文字体下载状态。构造这一拍 `lang.log_cjk()` 与启动编排的 `fonts::resolve()`
+            // 已经可能发起下载，所以初值就取**当前快照**（不能假定是 Unknown，否则第一拍会白重建）。
+            font_seen: crate::fonts::install::status(),
+            height,
+            appearance,
+            appearance_prefs,
+            hwnd: None,
+            settings: pages::settings::Groups::default(),
+            // 出厂是**空会话**（M119 删了 M104 的样本会话）；取证开关 `ULL_AGENT_*` 的档位
+            // 与夹具在 `boot_agent` 里落地（它要先让 presenter 知道栏可见性，见那里）。
+            agent: crate::shell::agent::AgentUi::new(),
+            agent_host: super::presenter::AgentHost::from_env(),
+            // 下载页安装草稿（M105）：出厂态 = 没选中、原版、两个空串
+            download_draft: pages::InstallDraft::default(),
+            launch_form: pages::LaunchForm::default(),
+            adopt_form: super::super::adopt::Form::default(),
+            install_cancelled_seen: 0,
+            launch_ends_seen: 0,
+            mods_failed_seen: None,
+            dialog_card: None,
+            dialog_model: None,
+            content: pages::content::PageState::default(),
+            account_form: pages::account::Form::new(),
+            account: pages::account::Page::build(
+                &AppState::new(),
+                &pages::account::Form::new(),
+                &mut pages::account::avatar::Cache::default(),
+                unlucky_i18n::Lang::En,
+                width,
+            ),
+            avatars: pages::account::avatar::Cache::default(),
+            corner_applied: None,
+        };
+        // M229：设置页「主题」行的选中态来自设置组自有状态（`language_appearance::State::theme`），
+        // 唯一写者是 `App::set_theme_mode`；这里把启动时读到的档位灌进去，首帧才不会画错档。
+        app.settings.language_appearance.theme = theme_mode;
+        // 配色来源档可能已经指向一张背景图：那时 `Ui` 必须由解析出的方案构造，而不是色板。
+        app.rebuild_ui();
+        // M174：助手配置的首屏值（真值来自 `config/launcher.json`；截图通道走 `ULL_AI_STATE`）。
+        app.hydrate_ai_settings();
+        // M175：Java 分组的首屏值 + **首屏自动扫一次盘**（截图通道走 `ULL_JAVA_STATE`）。
+        // M223: adopt wizard screenshot seed (evidence channel only; `ULL_ADOPT_STATE`).
+        app.hydrate_adopt_state();
+        app.hydrate_java_settings();
+        // 两行日志：①档位 + 探测结论 + 生效语言 ②中文策略（D28 缺字体不许静默）。
+        // 下一个人据此分得清「探测错了」还是「探测对了但没用上」。
+        app.lang.log();
+        app.lang.log_cjk();
+        app
+    }
+}

crates/app-iced/src/app/state/mods_shot.rs

@@ -0,0 +1,97 @@
+//! 出图取证用的 MODS 夹具（`ULL_MODS_FIXTURE=1`）。
+//!
+//! # 它解决什么
+//!
+//! D30 的 MODS 区截图需要一屏**有内容的列表**。产品路径的列表来自后台线程（列 `mods/` → 快照），
+//! 而截图通道在第 3 帧就出图（`CAPTURE_AT_FRAME`）：那条后台往返来不及完成，截出来会是
+//! 「正在读取 mods/…」。M157 的启动参数区、M222 的下载页、M223 的导入都是同一个问题，
+//! 处理方式一致：**状态注入**，且注入点放在「快照 → 页面模型」之前，于是转换逻辑照样被执行。
+//!
+//! # 边界（不要把它读成产品能力）
+//!
+//! - 只在环境变量存在时生效；产品路径读不到它 ⇒ 一帧都不影响；
+//! - 它注入的是**快照**（[`ModListView`]），不是页面模型——`Mods::from_state` 的转换、
+//!   计数、`.old` 徽标、在飞置灰走的都是产品代码；
+//! - 真实链路由两条端到端用例钉住（`host::mods::tests` 在真盘上列目录 + 启停）。
+
+/// 夹具开关是否打开（`ULL_MODS_FIXTURE` 非空且不为 `0`）。
+#[must_use]
+pub fn enabled() -> bool {
+    std::env::var("ULL_MODS_FIXTURE")
+        .map(|value| {
+            let value = value.trim();
+            !value.is_empty() && value != "0"
+        })
+        .unwrap_or(false)
+}
+
+/// 一份固定快照（实例 id 用调用方给的那个）。
+///
+/// `dir` 故意留空：夹具不碰路径（这一版页面也不画它），写一个假路径反而会被当成"真的派生结果"。
+#[must_use]
+pub fn view(instance: &str) -> unlucky_presenter::dto::ModListView {
+    use unlucky_presenter::dto::{ModEntryView, ModListView};
+
+    let entry = |file: &str, name: &str, enabled: bool, bytes: u64, old: bool| ModEntryView {
+        file: file.to_string(),
+        name: name.to_string(),
+        enabled,
+        bytes,
+        old,
+    };
+    // 夹具不碰路径：`dir` 留空（页面这一版不画它，它只是 DTO 的一部分）。
+    let dir = String::new();
+
+    ModListView {
+        instance: instance.to_string(),
+        dir,
+        exists: true,
+        entries: vec![
+            entry(
+                "sodium-fabric-0.5.11.jar",
+                "sodium-fabric-0.5.11.jar",
+                true,
+                1_048_576,
+                false,
+            ),
+            entry(
+                "iris-fabric-1.8.5.jar",
+                "iris-fabric-1.8.5.jar",
+                true,
+                2_621_440,
+                false,
+            ),
+            entry(
+                "jei-1.20.4-forge-17.3.0.49.jar.disabled",
+                "jei-1.20.4-forge-17.3.0.49.jar",
+                false,
+                1_363_148,
+                false,
+            ),
+            entry(
+                "aether-1.20.1-1.0.0.jar.old",
+                "aether-1.20.1-1.0.0.jar",
+                true,
+                7_340_032,
+                true,
+            ),
+            entry(
+                "create-1.20.1-0.5.1.f.jar.disabled",
+                "create-1.20.1-0.5.1.f.jar",
+                false,
+                4_194_304,
+                false,
+            ),
+            entry(
+                "fabric-api-0.92.2+1.20.4.jar",
+                "fabric-api-0.92.2+1.20.4.jar",
+                true,
+                2_097_152,
+                false,
+            ),
+        ],
+        skipped: Vec::new(),
+        running: false,
+        known: true,
+    }
+}

crates/app-iced/src/app/state/refresh.rs

@@ -0,0 +1,234 @@
+//! 快照 → 视图模型的重建口径（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。
+//!
+//! 全仓只有 [`App::refresh_view`] 这一个「presenter 快照 → 页面要画的东西」的转换点，
+//! 由 [`App::view_dirty`](super::App) 门控（M90 r2/P2-1 起）：只有真的改了状态的事情才置位，
+//! 30 Hz 空转不重建（重建要把 N 个实例的名字/版本串克隆一遍）。
+
+use unlucky_presenter::dto::{AppCommand, ModsCommand, SavesCommand};
+
+use super::{mods_shot, saves_shot};
+use unlucky_presenter::toast::ToastKind;
+
+use crate::app::view;
+use crate::pages;
+
+use unlucky_presenter::router::Route;
+
+use super::App;
+
+impl App {
+    /// 把 presenter 的快照转换成页面视图模型（**展示转换在 UI 侧做**）。
+    ///
+    /// 代价是「克隆 N 个实例的名字/版本串」，所以只在 [`App::view_dirty`] 置位时调用（P2-1）。
+    pub(in crate::app) fn refresh_view(&mut self) {
+        // **不变式先对齐再算宽度**（M104 / 复审 r1 P2-1）：`Route::Agent` ⟺ `RailState::Detached`。
+        // 每一次路由变化都会走到这里，所以它是「档位 ↔ 路由」的唯一点；放在算宽度之前，
+        // 是为了让模型拿到的 `content_width` 与页面头部读到的档位来自同一份状态。
+        self.sync_agent_route();
+        // M119：把「栏可见吗」写回 presenter（未读口径的输入，两个窄入口：`navigate` + `prefs_mut`）。
+        // 必须在 `sync_agent_route` 之后：档位刚被它对齐过，这里读到的才是这一帧的真值。
+        self.sync_agent_presenter();
+
+        // M105：取消安装的提示语在**这里**弹（`refresh_view` 是事件 apply 之后必经的那一处）。
+        // 文案由页面层求（`pages::cancelled_toast`），presenter 只发信号 ——
+        // 否则会出现「选项区英文、取消弹窗中文」的同屏两语（复审 P2-2）。
+        if self.state.install_cancelled != self.install_cancelled_seen {
+            self.install_cancelled_seen = self.state.install_cancelled;
+            // M106：提示语跟着**生效语言**走（M105 留的 `view::ui_lang()` 占位已删——它恒英文，
+            // 中文界面会弹出英文提示，那正是 M105 r1 复审 P2-2 要堵的同屏两语）。
+            let text = pages::cancelled_toast(self.lang());
+            self.state.toasts.push(ToastKind::Info, text);
+        }
+
+        // M161：启动收尾的提示语也在这里弹（presenter 只发结构：结局 + 退出码 + 失败阶段）。
+        // 此前 presenter 直接推一条自己拼好的中文 Toast，英文界面会弹中文。
+        if self.state.launch_ends != self.launch_ends_seen {
+            self.launch_ends_seen = self.state.launch_ends;
+            if let Some(finished) = self.state.last_launch_end.as_deref() {
+                let text = view::instances::launch_toast(finished, self.lang());
+                let kind = if finished.outcome == unlucky_presenter::dto::LogOutcome::Ok
+                    && finished.failure.is_none()
+                {
+                    ToastKind::Success
+                } else {
+                    ToastKind::Error
+                };
+                self.state.toasts.push(kind, text);
+                // M187：失败要**弹窗**（Toast 会自己消失，崩溃现场不能只靠它）。
+                let ended = finished.clone();
+                self.open_failure_dialog(&ended);
+            }
+        }
+
+        // M224：详情页 ⇄ MODS 区的绑定与取数（换实例就重新列一次 mods/）。
+        // **必须在建模型之前**：它会把快照写进 presenter 状态，而下一行 `model()` 就读那份状态
+        // （放在 `model()` 之后等于这一帧画的是旧快照——M224 出图实测：注入的夹具要等下一帧）。
+        self.sync_mods();
+        // M235：详情页 ⇄ SAVES 区的绑定与取数（换实例就重新列一次存档）。同样是**建模型之前**。
+        self.sync_saves();
+        // M224：启停失败的提示语（presenter 只发结构，文案在这里按 i18n 现求）。
+        self.note_mods_failure();
+        // M247（复审 r1 P2-1）：被确认的世界已经从快照里消失 ⇒ 收起那个确认框。
+        // 不这样的话主按钮就是一次静默空操作（点了没删、也不说一句）。
+        self.settle_saves_confirm();
+
+        // 分类是**页面自己持有的过滤条件**（真 host 丢弃 `ListVersions` 的分类参数）：
+        // 重建视图模型时带回去，否则每次事件都会把 chip 打回「全部」（复审 P2-1）。
+        let category = self.view.download.category;
+        // 草稿同理（M105）：它也是页面自己持有的输入，重建模型时带回去，
+        // 否则每来一条事件（连安装进度都算）用户填的加载器就被抹回「原版」。
+        let draft = self.download_draft.clone();
+        // 右栏占掉的宽度先扣掉：面板展开时页面按更窄的宽度排版（「收缩而不是溢出」，M104）
+        let width = self.agent.content_width(self.width);
+        // M106：语言形参跟着 `LangState` 走（`draft` 那一位是 M105 的安装草稿）。
+        self.view = super::super::view::model(
+            &self.state,
+            width,
+            self.height,
+            self.options.force_state,
+            category,
+            &draft,
+            self.lang(),
+            &self.content,
+        );
+        // M157：启动参数表单的重播种（换实例必重播种、同实例的脏草稿不覆盖）。
+        self.sync_launch_form();
+        // 账户页（M114）：与 `view` 同一次门控重建（实现见 `view/account_page.rs`，
+        // 皮肤解码走缓存，所以重复重建不重解图）。
+        self.rebuild_account_page(width);
+        // M187：弹窗的视图模型也在这一处重建——`view()` 只借 `&self`，放不进局部变量
+        // （Element 借字符串，局部一死树就悬空）。全仓「快照 → 视图模型」只在这里发生。
+        self.dialog_model = self.dialog_modal();
+        self.view_dirty = false;
+        self.refreshes += 1;
+    }
+
+    /// 收掉「被确认的世界已经不在快照里」的那个删除确认框（M247，复审 r1 P2-1）。
+    ///
+    /// 判据由 presenter 给（`SavesState::take_closed_confirm`：那个世界从快照里消失了），
+    /// **框的 id 也由它带着**——所以只收我们自己那个框，崩溃卡片/进度框一概不碰。
+    ///
+    /// 为什么必须收：目标已经作废，主按钮就成了一次**静默空操作**（用户点了「删除世界」，
+    /// 框关了、什么也没发生、也没一句解释）。少删是安全的，但"看起来坏了"不是可接受的结果。
+    fn settle_saves_confirm(&mut self) {
+        let Some(dialog) = self.state.saves.take_closed_confirm() else {
+            return;
+        };
+        if self
+            .state
+            .dialogs
+            .current()
+            .is_some_and(|current| current.id == dialog)
+        {
+            self.close_dialog();
+        }
+    }
+
+    /// 把详情页当前实例的启动参数快照灌进表单（唯一的重播种点，见 `pages/instances/state.rs`）。
+    ///
+    /// 不在详情页（或实例已不在快照里）时解绑：下次进详情页会重新播种，
+    /// 免得「A 的草稿被当成 B 的初值」。
+    fn sync_launch_form(&mut self) {
+        let Route::Detail(id) = self.state.route() else {
+            self.launch_form.bound = None;
+            return;
+        };
+        match self
+            .state
+            .instances
+            .iter()
+            .find(|instance| &instance.id == id)
+        {
+            Some(instance) => {
+                let view = instance.launch.clone();
+                self.launch_form.sync(&view);
+            }
+            None => self.launch_form.bound = None,
+        }
+    }
+
+    /// 详情页 ⇄ MODS 区的绑定与取数。
+    ///
+    /// 判据只有一条：**绑定变了**（进详情页 / 换实例 / 退出详情页）。
+    /// - 绑定函数自己会清掉旧快照（A 的列表不许画在 B 的详情页上，见 presenter 的 `ModsState::bind`）；
+    /// - 绑定之后手上没有快照 ⇒ 派一条 `AppCommand::Mods(List)` 去后台列目录。
+    ///
+    /// 为什么放在 `refresh_view` 里：它是**唯一**的「路由变了」漏斗（点行、返回、首屏自动选中都走它）。
+    /// 派发会再进一次 `refresh_view`（`dispatch` → `pump` → 重建），但那时 `bound` 已经相等，
+    /// 这一支直接返回，不会重复发请求、也不会无限递归。
+    fn sync_mods(&mut self) {
+        let wanted = match self.state.route() {
+            Route::Detail(id) => Some(id.clone()),
+            _ => None,
+        };
+        if self.state.mods.bound == wanted {
+            return;
+        }
+        self.state.bind_mods(wanted.as_deref());
+        let Some(id) = wanted else {
+            return;
+        };
+        // 出图取证（`ULL_MODS_FIXTURE=1`）：后台往返赶不上第 3 帧出图，注入一份固定快照。
+        // 产品路径读不到这个变量 ⇒ 下面这行什么都不做（见 `mods_shot` 的模块文档）。
+        if mods_shot::enabled() {
+            self.state.mods.changed(mods_shot::view(&id));
+            return;
+        }
+        // **不走 `App::dispatch`**：那条路会为「等第一条事件」把帧订阅打开 3 秒（`watch_until`），
+        // 而这里只是"进详情页顺手后台列一次目录"——结果在下一拍心跳（1 Hz）落地就够了。
+        // 走观察窗会把 M192 的「空闲不烧帧」守卫打红（`subscription` 的三条用例立刻红：实测过）。
+        self.backend
+            .dispatch(AppCommand::Mods(Box::new(ModsCommand::List(id))));
+    }
+
+    /// 详情页 ⇄ SAVES 区的绑定与取数（M235）。
+    ///
+    /// 判据与 `sync_mods` **一字不差**：绑定变了（进详情页 / 换实例 / 退出详情页）才动；
+    /// 绑定之后手上没有快照 ⇒ 派一条 `AppCommand::Saves(List)` 去后台列目录。
+    ///
+    /// 不弹 Toast：存档区的失败就地画在卡片里（带「重试」），再弹一条是同一件事说两遍。
+    fn sync_saves(&mut self) {
+        let wanted = match self.state.route() {
+            Route::Detail(id) => Some(id.clone()),
+            _ => None,
+        };
+        if self.state.saves.bound == wanted {
+            return;
+        }
+        self.state.bind_saves(wanted.as_deref());
+        let Some(id) = wanted else {
+            return;
+        };
+        // 出图取证（`ULL_SAVES_FIXTURE=1`）：后台往返赶不上第 3 帧出图，注入一份固定快照。
+        // 产品路径读不到这个变量 ⇒ 下面这行什么都不做（见 `saves_shot` 的模块文档）。
+        if saves_shot::enabled() {
+            saves_shot::seed(self, &id);
+            return;
+        }
+        // **不走 `App::dispatch`**：那条路会为「等第一条事件」把帧订阅打开 3 秒，
+        // 这里只是"进详情页顺手后台列一次目录"，结果在下一拍心跳落地就够了（M224 同款理由：
+        // 走观察窗会把 M192 的「空闲不烧帧」守卫打红）。
+        self.backend
+            .dispatch(AppCommand::Saves(Box::new(SavesCommand::List(id))));
+    }
+
+    /// 启停失败的提示语：每条**新**失败弹一次 Toast。
+    ///
+    /// 判据是 `(实例, 文件, 大类)` 三元组：同一个文件连点两次、每次都失败在同一个大类上时，
+    /// **只弹一次**——第二次是同一件事的重复，再弹就是刷屏（用户已经看见了那句红字）。
+    /// 换了文件、换了实例、或失败大类变了（例如"不覆盖冲突"变成"被占用"），三元组就变了，
+    /// 于是照样会再弹一次：提示语跟的是"新事实"，不是"点击次数"。
+    fn note_mods_failure(&mut self) {
+        let Some(failure) = self.state.mods.failed.as_ref() else {
+            self.mods_failed_seen = None;
+            return;
+        };
+        let key = (failure.instance.clone(), failure.file.clone(), failure.kind);
+        if self.mods_failed_seen.as_ref() == Some(&key) {
+            return;
+        }
+        let text = pages::mods_failure_line(failure, self.lang().catalog());
+        self.state.toasts.push(ToastKind::Error, text);
+        self.mods_failed_seen = Some(key);
+    }
+}

crates/app-iced/src/app/state/saves_shot.rs

@@ -0,0 +1,266 @@
+//! 出图取证用的 SAVES 夹具（`ULL_SAVES_FIXTURE=1`）。
+//!
+//! # 它解决什么
+//!
+//! D30 的 SAVES 区截图需要一屏**有内容的列表**（世界 + 截图）。产品路径的列表来自后台线程
+//! （列 `saves/` → 快照），而截图通道在第 3 帧就出图（`CAPTURE_AT_FRAME`）：那条后台往返来不及
+//! 完成，截出来会是「正在读取 saves/…」。M157 / M222 / M223 / M224 都是同一个问题，处理方式一致：
+//! **状态注入**，注入点放在「快照 → 页面模型」之前，于是转换逻辑照样被执行。
+//!
+//! # 边界（不要把它读成产品能力）
+//!
+//! - 只在环境变量存在时生效；产品路径读不到它 ⇒ 一帧都不影响；
+//! - 它注入的是**快照**（[`SavesListView`]），不是页面模型——`Saves::from_state` 的时间格式化、
+//!   计数、「有图标」标记走的都是产品代码；
+//! - 真实链路由端到端用例钉住：`core::game::saves::tests`（真盘只读列举）与
+//!   `presenter::host::saves::tests`（派生运行目录 → 快照）。
+//!
+//! ```text
+//! ULL_SAVES_FIXTURE=1 ULL_INSTANCE_STATE=demo ULL_START_ROUTE=instances \
+//!   unlucky-launcher-iced --screenshot=saves.png --software-renderer
+//! ```
+
+/// 夹具开关是否打开（`ULL_SAVES_FIXTURE` 非空且不为 `0`）。
+#[must_use]
+pub fn enabled() -> bool {
+    std::env::var("ULL_SAVES_FIXTURE")
+        .map(|value| {
+            let value = value.trim();
+            !value.is_empty() && value != "0"
+        })
+        .unwrap_or(false)
+}
+
+/// 2024-05-01 10:00 UTC（写死的 UTC 毫秒，不是"现在"）。
+///
+/// 写死有两个原因：两张主题图要能逐像素对照；而且它能证明「毫秒 → `YYYY-MM-DD HH:MM UTC`」
+/// 这条换算在页面上真的走通了（`docs` 里的期望值就是这个时刻）。
+const NEWEST: u64 = 1_714_557_600_000;
+/// 比 [`NEWEST`] 早 32 天。
+const MIDDLE: u64 = NEWEST - 32 * 24 * 3_600_000;
+/// 比 [`NEWEST`] 早 42 天。
+const OLDEST: u64 = NEWEST - 42 * 24 * 3_600_000;
+
+/// 一份固定快照（实例 id 用调用方给的那个）。
+///
+/// 其中一个世界/一张截图的 mtime 是 `None`：那是「时间未知」这条分支的唯一出图证据。
+#[must_use]
+pub fn view(instance: &str) -> unlucky_presenter::dto::SavesListView {
+    use unlucky_presenter::dto::{
+        SavesListView, ScreenshotPreview, ScreenshotThumbFailure, ScreenshotThumbKind,
+        ScreenshotView, WorldView,
+    };
+
+    let world = |dir: &str, icon: bool, modified_ms: Option<u64>| WorldView {
+        dir: dir.to_string(),
+        icon,
+        modified_ms,
+    };
+    let shot = |file: &str, bytes: u64, modified_ms: Option<u64>, preview: ScreenshotPreview| {
+        ScreenshotView {
+            file: file.to_string(),
+            bytes,
+            modified_ms,
+            preview,
+        }
+    };
+
+    SavesListView {
+        instance: instance.to_string(),
+        dir: "D:/ULL/.ULL/data/instances/Better-MC/saves".to_string(),
+        exists: true,
+        worlds: vec![
+            world("Better World", true, Some(NEWEST)),
+            world("Redstone Lab", true, Some(MIDDLE)),
+            world("Skyblock", false, Some(OLDEST)),
+            world("Test Flat", false, None),
+        ],
+        screenshots_dir: "D:/ULL/.ULL/data/instances/Better-MC/screenshots".to_string(),
+        screenshots_exists: true,
+        // 四张截图，把缩略图墙的**四种格子**一次摆出来（M251）：
+        // ① 白天（真像素）② 黄昏（真像素）③ 「未生成预览」占位 ④ 具名的失败原因。
+        // 像素是**合成的**（下面 `scene`）：夹具不连真实解码器，出图只证明墙的排版与状态，
+        // 解码由 presenter 的 `host::saves::thumbs` 用例用真 PNG 钉住。
+        screenshots: vec![
+            shot(
+                "2024-05-01_10.00.00.png",
+                1_887_436,
+                Some(NEWEST),
+                ScreenshotPreview::Ready(scene(1)),
+            ),
+            shot(
+                "2024-04-30_21.14.05.png",
+                2_097_152,
+                Some(MIDDLE),
+                ScreenshotPreview::Ready(scene(2)),
+            ),
+            shot(
+                "2024-04-20_08.30.00.png",
+                964_608,
+                None,
+                ScreenshotPreview::NotGenerated,
+            ),
+            shot(
+                "2024-04-11_19.02.41.png",
+                9_437_184,
+                Some(OLDEST),
+                ScreenshotPreview::Failed(ScreenshotThumbFailure {
+                    kind: ScreenshotThumbKind::TooLarge,
+                    detail: "9437184 > 8388608".to_string(),
+                }),
+            ),
+        ],
+        skipped: Vec::new(),
+        // 出图夹具不造回执：默认那一张就是「刚列完目录」的样子。
+        // 要看「备份成功那句话」长什么样，用 `ULL_SAVES_FIXTURE=backed-up`（见 `seed`）。
+        last_op: None,
+    }
+}
+
+/// 夹具形态（由 `ULL_SAVES_FIXTURE` 的取值决定；未知值 = 默认那一种）。
+///
+/// | 取值 | 出图抓什么 |
+/// |---|---|
+/// | `1`（或任何未知值） | 有内容的列表：世界行右侧的重命名 / 备份 / 删除 |
+/// | `rename` | 行内重命名进行中（输入框 + 改名/取消） |
+/// | `confirm` | 删除的二次确认模态框 |
+/// | `backed-up` | 备份成功的回执那句话（带落点路径与大小） |
+/// | `running` | 「游戏正在运行，先退出再操作」那条写失败（M247 的在飞闸门） |
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Mode {
+    /// 默认：列表 + 行操作区。
+    Plain,
+    /// 行内重命名进行中。
+    Rename,
+    /// 删除确认模态。
+    Confirm,
+    /// 备份成功的回执。
+    BackedUp,
+    /// 写操作被「游戏在运行」挡下。
+    Running,
+}
+
+fn mode() -> Mode {
+    match std::env::var("ULL_SAVES_FIXTURE")
+        .unwrap_or_default()
+        .trim()
+    {
+        "rename" => Mode::Rename,
+        "confirm" => Mode::Confirm,
+        "backed-up" => Mode::BackedUp,
+        "running" => Mode::Running,
+        _ => Mode::Plain,
+    }
+}
+
+/// 注入这一屏需要的状态（**只走产品路径的入口**：`changed` / `start_rename` / `ask_delete` /
+/// `dialogs.push`，一处新渲染分支都没有）。
+pub fn seed(app: &mut crate::app::state::App, instance: &str) {
+    let mode = mode();
+    let mut view = view(instance);
+    if mode == Mode::BackedUp {
+        view.last_op = Some(unlucky_presenter::dto::SavesOped::BackedUp {
+            dir: "Better World".to_string(),
+            file: "Better World-20240501-100000.zip".to_string(),
+            path: "D:/ULL/.ULL/data/exports/saves/Better World-20240501-100000.zip".to_string(),
+            bytes: 84_213_760,
+            skipped: 0,
+        });
+    }
+    let first = view.worlds.first().map(|world| world.dir.clone());
+    app.state.saves.changed(view);
+    let Some(dir) = first else {
+        return;
+    };
+    match mode {
+        Mode::Rename => app.state.saves.start_rename(&dir),
+        // 在飞闸门那条失败（`host::saves::dispatch` 在 `running` 时直接回它）。
+        Mode::Running => app
+            .state
+            .saves
+            .failed(unlucky_presenter::dto::SavesFailureView {
+                instance: instance.to_string(),
+                file: dir,
+                op: Some(unlucky_presenter::dto::SavesFailureOp::Rename),
+                kind: unlucky_presenter::dto::SavesFailureKind::GameRunning,
+                detail: String::new(),
+            }),
+        Mode::Confirm => {
+            let (title, body, primary, secondary) =
+                crate::pages::saves_delete_prompt(app.lang().catalog(), &dir);
+            let dialog = app.state.dialogs.push(
+                unlucky_presenter::dialogs::DialogSource::UserAction,
+                title,
+                body,
+                unlucky_presenter::dialogs::DialogKind::Confirm { primary, secondary },
+            );
+            app.state.saves.ask_delete(dialog, &dir);
+        }
+        Mode::Plain | Mode::BackedUp => {}
+    }
+}
+
+/// 一张**合成的**缩略图（160×90 RGBA）：天空渐变 + 地面 + 太阳/月亮。
+///
+/// 为什么合成而不是读真图：夹具的职责是「让页面有东西可画」，而它跑在截图通道的第 3 帧——
+/// 真解码要真的有一张 PNG 在盘上、还要等后台线程回来。合成像素让出图**确定**（两张主题图
+/// 逐像素可比），并且明确地不假装自己是解码证据（那由 presenter 的用例负责）。
+///
+/// `tone`：`1` = 白天（亮天空 + 绿地面），其余 = 黄昏（橙天空 + 暗地面）。同一套几何，
+/// 两种配色——墙上两格一眼能看出"每格各画各的"。
+fn scene(tone: u8) -> unlucky_presenter::dto::ThumbnailView {
+    const W: u32 = 160;
+    const H: u32 = 90;
+    // 地平线在 2/3 高度（截图里天空总比地面多）。
+    const HORIZON: u32 = H * 2 / 3;
+    let (sky_top, sky_bottom, ground, sun): ([u8; 3], [u8; 3], [u8; 3], [u8; 3]) = if tone == 1 {
+        (
+            [128, 176, 240],
+            [200, 224, 248],
+            [86, 138, 66],
+            [255, 246, 186],
+        )
+    } else {
+        ([96, 66, 96], [232, 148, 96], [58, 74, 48], [255, 214, 150])
+    };
+    let mut pixels = Vec::with_capacity((W * H * 4) as usize);
+    for y in 0..H {
+        for x in 0..W {
+            let (r, g, b) = if y < HORIZON {
+                // 天空：从顶到底线性插值（`t` = 0..=255 的定点比例）。
+                let t = y * 255 / HORIZON.max(1);
+                let mix = |from: u8, to: u8| -> u8 {
+                    let span = i32::from(to) - i32::from(from);
+                    (i32::from(from) + span * t as i32 / 255) as u8
+                };
+                (
+                    mix(sky_top[0], sky_bottom[0]),
+                    mix(sky_top[1], sky_bottom[1]),
+                    mix(sky_top[2], sky_bottom[2]),
+                )
+            } else {
+                // 地面：按 3px 一条的条纹给出「方块地形」的观感。
+                let stripe = (y / 3) % 2 == 0;
+                let shade: u8 = if stripe { 0 } else { 14 };
+                (
+                    ground[0].saturating_sub(shade),
+                    ground[1].saturating_sub(shade),
+                    ground[2].saturating_sub(shade),
+                )
+            };
+            // 太阳/月亮：右上角一个 18px 的圆（够小，不会盖住画面主体）。
+            let (dx, dy) = (x as i32 - 126, y as i32 - 26);
+            let (r, g, b) = if dx * dx + dy * dy <= 18 * 18 {
+                (sun[0], sun[1], sun[2])
+            } else {
+                (r, g, b)
+            };
+            pixels.extend_from_slice(&[r, g, b, 255]);
+        }
+    }
+    unlucky_presenter::dto::ThumbnailView {
+        width: W,
+        height: H,
+        pixels,
+    }
+}

crates/app-iced/src/app/state/theme.rs

@@ -0,0 +1,232 @@
+//! 主题与 `Ui` 的重算口径（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。
+//!
+//! 三件事在这里：①`Ui` 什么时候重建（[`App::rebuild_ui`]）②主题档怎么定
+//! （[`App::set_flavor`] / [`App::apply_config_theme`]）③读当前求值器（[`App::ui`]）。
+//!
+//! 截图通道的判据 [`App::has_screenshot`] 也放在这儿：上面三条里两条都要「截图不读用户配置」。
+
+use crate::app::diag::diag;
+use crate::app::message::Message;
+use iced::Task;
+use unlucky_design::color::SchemeFlavor;
+use unlucky_presenter::prefs::ThemeMode;
+
+use crate::theme::Ui;
+
+use super::App;
+
+impl App {
+    /// 本次进程是否走截图通道。
+    pub(in crate::app) fn has_screenshot(&self) -> bool {
+        self.options.screenshot.is_some()
+    }
+
+    /// 切主题：重建 [`Ui`]（= 重建 Style），**不动任何 UI 状态**。
+    ///
+    /// M93 起 `Ui` 有两个来源：配色来源取到了图（①②级）就用解析出的方案，否则用令牌 baseline。
+    /// 所以这里改叫「重算 `Ui`」：先让外观状态记住新深浅（配色解析要它），再重建。
+    pub(in crate::app) fn set_flavor(&mut self, flavor: SchemeFlavor) {
+        if self.ui.flavor() == flavor && self.appearance.flavor() == flavor {
+            return;
+        }
+
+        self.appearance.set_flavor(flavor);
+        let previous = self.ui.name();
+        self.rebuild_ui();
+        diag!(
+            "[theme] {} -> {} (Theme::name 变化触发缓存重算)",
+            previous,
+            self.ui.name()
+        );
+    }
+
+    /// 按「强调色 / 配色来源是否接管」重建 [`Ui`]。
+    ///
+    /// **优先级（M250）：显式强调色 > D38 取色方案 > 出厂品牌板**。手填的色是直接意图，取色是从
+    /// 图片派生的，所以强调色只在用户真的填了合法值时压过取色——两条路都只决定「颜色来自哪里」，
+    /// `flavor`（明暗 / 跟随系统）仍由 `self.appearance.flavor()` 决定。
+    ///
+    /// 色卡档（③）刻意继续走 `Scheme::baseline`：`resolve_source` 的色卡档返回的是
+    /// `DEFAULT_CARD`（天蓝卡）方案，与令牌 baseline 逐色不同，应用它会把**全部既有验收图的
+    /// 像素**改掉。这条偏离登记在 `pages::appearance` 的偏离表 #4。
+    pub(in crate::app) fn rebuild_ui(&mut self) {
+        // 面板 α（D36）在这里注入 `Ui`：全仓所有表面色都从 `Ui::layer` 出去，所以这是**唯一**
+        // 生效点（外壳 / 三页卡片 / 外观分组卡片 / 空态图标块自动同源，调用点没有机会各处自乘）。
+        let panel_alpha = self.appearance.effective_panel_alpha();
+        // 三选一规则只在 `theme::tokens` 里写一遍：出图 harness 也调它（两头各抄一份迟早
+        // 出现「图上有强调色、产品里没有」，而那种偏差在图上看不出来）。
+        let (ui, colors) = crate::theme::tokens(
+            self.appearance.flavor(),
+            self.appearance.accent.color(),
+            self.appearance.derived_scheme().copied(),
+            self.families,
+        );
+        match colors {
+            crate::theme::Colors::Accent => {
+                // M250：一行里同时给「强调色生效了」与「取色方案被谁压住」，两件事都能读出来。
+                diag!(
+                    "[appearance] accent={} → Ui::with_accent（只换 primary/secondary/tertiary；取色方案 palette={} 被压住）",
+                    self.appearance.accent.log_token(),
+                    self.appearance.palette_level()
+                );
+            }
+            crate::theme::Colors::Scheme => {
+                diag!(
+                    "[appearance] palette={} → Ui::from_scheme（取色方案接管 49 个角色）",
+                    self.appearance.palette_level()
+                );
+            }
+            crate::theme::Colors::Board => {
+                // 非法值：**保持出厂板**，但错行留在设置页（不静默），日志里也留一条。
+                if let Some(error) = self.appearance.accent.error() {
+                    diag!("[appearance] accent 非法（{error:?}）→ 出厂板，错行见设置页");
+                }
+            }
+        }
+        self.ui = ui.with_panel_alpha(panel_alpha);
+    }
+
+    /// 按设置文件里的主题模式切一次外观；`--theme` 显式给了就不动。
+    ///
+    /// **截图通道直接跳过**：`--screenshot` 的主题唯一取值口是 `Options::capture_flavor`
+    /// （D30 可复现），读本机 `launcher.json` 会让同一份代码在两台机器上出不同的图。
+    ///
+    /// `ThemeMode::Auto` 不在这里处理：那要看系统主题（`iced::system::theme()` 的结果在
+    /// `Message::SystemTheme` 里落地）。
+    pub(in crate::app) fn apply_config_theme(&mut self) {
+        if self.has_screenshot() || self.options.theme.is_some() {
+            return;
+        }
+        let mode = self.bridge.load().1;
+        self.theme_mode = mode;
+        // M229：设置页那一行画的是这个字段（唯一写者见 [`App::set_theme_mode`]）。
+        self.settings.language_appearance.theme = mode;
+        match mode {
+            ThemeMode::Light => self.set_flavor(SchemeFlavor::Light),
+            ThemeMode::Dark => self.set_flavor(SchemeFlavor::Dark),
+            ThemeMode::Auto => {}
+        }
+    }
+
+    /// 换主题档（M229：设置页「通用 → 主题」→ `pages::Message::Theme`）。
+    ///
+    /// 四件事：①改 `theme_mode`（唯一真相）②同步设置页那一行的档位 ③重建 `Ui`（色板换了，
+    /// `Theme::name` 与 49 个角色一起变，iced 才会重算缓存）④落盘 `appearance.theme_mode`。
+    /// `Auto` 自己没有颜色，要等系统回答——所以返回 `iced::system::theme()` 那个 Task，
+    /// 由既有的 `Message::SystemTheme` 分支落地（它只在 `theme_mode == Auto` 时吃这条消息）。
+    pub(in crate::app) fn set_theme_mode(&mut self, mode: ThemeMode) -> Task<Message> {
+        self.settings.language_appearance.theme = mode;
+        if mode == self.theme_mode {
+            return Task::none();
+        }
+        self.theme_mode = mode;
+
+        let prefs = self.appearance_prefs.clone();
+        self.bridge.persist(&prefs, mode);
+        match self.bridge.path() {
+            Some(path) => diag!("[theme] mode={} 已写回 {}", mode.as_str(), path.display()),
+            None => diag!(
+                "[theme] mode={} 未落盘（数据根解析不出来，内存态运行）：重启会回到旧值",
+                mode.as_str()
+            ),
+        }
+
+        match mode {
+            ThemeMode::Light => {
+                self.set_flavor(SchemeFlavor::Light);
+                self.after_theme_switch();
+                Task::none()
+            }
+            ThemeMode::Dark => {
+                self.set_flavor(SchemeFlavor::Dark);
+                self.after_theme_switch();
+                Task::none()
+            }
+            // 跟随系统：当前先按已有深浅画，紧接着由系统主题回答覆盖
+            // （`set_flavor` 有「同档不重建」的保护，所以这里不必先猜一次）。
+            ThemeMode::Auto => iced::system::theme().map(Message::SystemTheme),
+        }
+    }
+
+    /// 换档之后重建视图模型 + 记一行取证日志（色板名就是证据：`ink` / `silver`）。
+    fn after_theme_switch(&mut self) {
+        self.view_dirty = true;
+        self.refresh_view();
+        diag!(
+            "[theme] mode={} board={} Theme::name={}",
+            self.theme_mode().as_str(),
+            self.board_name(),
+            self.ui.name()
+        );
+    }
+
+    /// 当前主题档（设置页那一行的选中态来自 `settings.groups`，这里是取证与测试的读数口）。
+    pub(in crate::app) fn theme_mode(&self) -> ThemeMode {
+        self.theme_mode
+    }
+
+    /// 当前色板名（日志与测试用：`ink` / `silver`；取色方案接管时仍报它所属深浅的那块）。
+    pub(in crate::app) fn board_name(&self) -> &'static str {
+        self.ui.board().name()
+    }
+
+    /// 当前令牌求值器（测试与截图日志用）。
+    pub(in crate::app) fn ui(&self) -> &Ui {
+        &self.ui
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::App;
+    use crate::app::components::feedback::progress;
+    use crate::cli::Options;
+    use crate::pages::appearance::Change;
+    use crate::theme::Families;
+    use unlucky_design::color::{Color, SchemeFlavor};
+    use unlucky_presenter::mock::MockBackend;
+    use unlucky_presenter::settings_bridge::SettingsBridge;
+
+    const FAMILIES: Families = Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+
+    /// 强调色接线（M250 ACCENTWIRE）的 App 级判据：`rebuild_ui` 真的换了令牌。
+    ///
+    /// **这条是判据一的变异探针**：把 [`App::rebuild_ui`] 改回「恒走 `Ui::new` 出厂板」
+    /// （或在它前面短路掉 `accent.color()` 分支），下面 `assert_ne!` 当场红——`pages/appearance`
+    /// 那条用例只证明「`Ui::with_accent` 能给出不同的色」，抓不到「谁去调它」。
+    ///
+    /// 抓得住：接线不存在 / 被短路 / 强调色解析结果没进 `Ui`。
+    /// 抓不住：像素（样式闭包被别处覆盖）——那是出图的事。
+    #[test]
+    fn rebuild_ui_follows_the_configured_accent() {
+        let mut app = App::with_presenter(
+            Options::default(),
+            FAMILIES,
+            SchemeFlavor::Light,
+            Box::new(MockBackend::new()),
+            SettingsBridge::memory_only(),
+        );
+
+        // 出厂态：同一组件（进度指示条 = `Role::Primary`）取到的值
+        let (_, factory_primary) = progress::linear_colors(app.ui());
+        assert_eq!(app.ui().name(), "ull-silver");
+
+        // 设置页填色 → `on_appearance` 会 rebuild 一次（与真机路径同一个函数）
+        app.on_appearance(Change::Accent(Color::rgb(0x00, 0x6A, 0x5C).to_hex()));
+        let (_, accent_primary) = progress::linear_colors(app.ui());
+
+        assert_ne!(
+            factory_primary, accent_primary,
+            "填了自定义强调色，`rebuild_ui` 却还给出出厂板的 Primary ⇒ 接线没落地"
+        );
+        assert_eq!(
+            app.ui().flavor(),
+            SchemeFlavor::Light,
+            "强调色只换颜色来源，不改明暗"
+        );
+    }
+}

crates/app-iced/src/app/subscription.rs

@@ -0,0 +1,350 @@
+//! 订阅：**按需**帧节拍（presenter 的 TICK）+ 窗口尺寸事件。
+//!
+//! ## 为什么要「按需」
+//!
+//! iced_winit 在处理完任何一条消息后都会 `request_redraw()`，而 `window::frames()` 监听的是
+//! `RedrawRequested` —— 于是「订阅帧 → 收 Frame → update → 再触发重绘」是一条**自持循环**：
+//! 只要订阅着，窗口就永远在重绘（M90 r1 就是这样，CPU 空转）。
+//!
+//! 现在只在**真的需要 33 ms 节拍**的时候订阅（[`App::needs_frames`]）：
+//!
+//! | 条件 | 为什么需要 33 ms 节拍 |
+//! |---|---|
+//! | 截图通道 | 第 3 帧要落盘 |
+//! | **有动画在跑**（M192） | 动效时间轴要逐帧采样（帧泵自己按 16 ms 结算，见 `components::motion`） |
+//! | 有 `Busy` / `Running` 实例 | 启动进度、日志尾随都靠 `backend.tick` 推进 |
+//! | 有未过期的 toast | toast 按毫秒倒计时 |
+//! | 刚派发过指令（3 s 观察窗） | 真 host 的异步事件要靠节拍抽出来 |
+//!
+//! 上面五条**共享同一个布尔**：订阅表里 `window::frames()` 只出现一处（写在同一个 `if` 里），
+//! 所以「动画」与「观察窗 / Busy」同时成立时也只有一条订阅——不双订阅靠的是结构，不是判重。
+//!
+//! 空闲态**一条帧消息都不来** ⇒ 窗口不重绘、`refresh_view` 不跑（配合 `view_dirty`）。
+//!
+//! ## 空闲态的时钟从哪来（M90 r3 / P2-2）
+//!
+//! r2 把空闲的帧订阅掐掉之后，`config_poll_due` 就再也没被调用过 —— 外部 CLI / AI 工具改
+//! `launcher.json` 后主题**永不生效**（不是「等下次交互」，是「等下一次 dispatch」）。这与
+//! D4「AI 能读改 ULL 配置」直接冲突。
+//!
+//! 所以空闲态换成一个 **1 Hz 的自续心跳**（[`crate::app::message::Message::Heartbeat`]，
+//! 由 `Task::perform(sleep(1s))` 驱动，见 `update::heartbeat`）：每秒醒一次、推进一拍
+//! presenter（内部按 33 ms 折算 30 拍，于是 `config_poll_due` 仍是「约 1 秒比对一次 mtime」）。
+//!
+//! 为什么不用 `window::frames()` + 1 s 闸门来实现这个低频时钟：帧订阅**本身就是**自持重绘循环
+//! （iced_winit 处理完任何消息都 `request_redraw()`），闸门只能省掉 `advance()` 里的活，省不掉
+//! 整窗重绘——实测软件渲染约 **500 帧/秒**。心跳是「每秒一帧」，差三个数量级。
+//!
+//! ## 已知代价（都登记，不藏）
+//!
+//! 1. **忙碌态仍是自持帧循环**：`Running`/`Busy` 一天不结束，就一天按帧刷（软件渲染实测约
+//!    970 帧/秒，refreshes 不增长 = 纯像素空转）。功能上需要 tick 来发现游戏退出，但「整段
+//!    运行期近千帧/秒重绘」是真实开销；要收口得让 `Running` 走更慢的时钟（follow-up）。
+//! 2. 心跳用 `thread::sleep` 占线程池一个线程 1 秒；1 Hz 下可接受，但不是优雅解法（正解仍是
+//!    `iced::time::every` + tokio/smol，Cargo.toml 在 scope 外，已报 finding）。
+
+use std::time::Instant;
+
+use iced::{window, Subscription};
+
+use super::components::motion;
+use super::message::Message;
+use super::state::App;
+
+impl App {
+    /// 本次进程的订阅表。
+    pub(super) fn subscription(&self) -> Subscription<Message> {
+        let frames = if self.needs_frames() {
+            window::frames().map(|_| Message::Frame)
+        } else {
+            Subscription::none()
+        };
+
+        // 断点 600 / 840 要跟着真窗口宽度走；截图模式的窗口尺寸由参数钉死，不吃 resize。
+        let events = if self.has_screenshot() {
+            Subscription::none()
+        } else {
+            window::events().map(|(_, event)| Message::Window(event))
+        };
+
+        // 键盘（M104）：`Esc` 收栗 / `Tab` 走焦点环 / `Enter` 激活焦点键。
+        //
+        // 为什么订阅整条键盘流而不是自己挑键：`iced::keyboard::listen()` 是唯一的全窗键盘入口，
+        // 挑键与「什么状态下该做什么」的解释权放在 `app/update/agent.rs`（一眼看完），
+        // 订阅表只负责搬运。截图通道不开它——D30 要可复现，键盘事件一个都不该进图。
+        let keys = if self.has_screenshot() {
+            Subscription::none()
+        } else {
+            iced::keyboard::listen()
+                .map(|event| Message::Agent(crate::shell::agent::Message::Key(event)))
+        };
+
+        Subscription::batch([frames, events, keys])
+    }
+
+    /// 是否订阅帧事件（= 截图模式要帧数闸门）。
+    pub(super) fn wants_frames(&self) -> bool {
+        self.has_screenshot()
+    }
+
+    /// 现在要不要**时钟**（见模块文档的表）。
+    pub(super) fn needs_frames(&self) -> bool {
+        self.has_screenshot()
+            // M192：只有动画在跑时才多这一条（帧泵清空轨道后立刻为假 ⇒ 退回 1 Hz 心跳）。
+            || motion::needs_frames()
+            || !self.state.toasts.is_empty()
+            || !self.state.running().is_empty()
+            // M175：Java 扫描进行中（进度 3/7 要动起来，否则用户只看到「正在扫描」卡着）。
+            || self.settings.java.scanning.is_some()
+            || self
+                .watch_until
+                .is_some_and(|deadline| Instant::now() < deadline)
+    }
+}
+#[cfg(test)]
+mod tests {
+    //! 帧订阅的**有界**守卫（M192）：动画期间订阅、结束即退订、关掉动效一帧都不订阅。
+    //!
+    //! ## 这一组按**运行时顺序**写（M192 r1 复审 P1-1 的教训）
+    //!
+    //! 第一版这里是「先 `motion::enter(...)` 再问 `needs_frames()`」——而 iced 的真实顺序是
+    //! 「`update()`（订阅表在这里求值）→ `view()`」，于是这条守卫全绿、生产路径上却根本播不出来。
+    //! 现在全部改走**真消息**：`app.update(Message::Page(Navigate(..)))` 之后再问订阅表，
+    //! 而且断言 `watch_until` 仍是 `None`（排除「观察窗顺手开了帧」这条假绿）。
+    //!
+    //! 时间轴用 `motion::advance_by` 摆（不等真实时钟），每个用例在自己的线程上跑，互不干扰。
+
+    use super::*;
+    use crate::app::components::motion::{Slot, FRAME_MS};
+    use crate::cli::Options;
+    use crate::pages;
+    use crate::theme::Families;
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_design::motion::MotionScale;
+    use unlucky_presenter::mock::MockBackend;
+    use unlucky_presenter::router::Route;
+    use unlucky_presenter::settings_bridge::SettingsBridge;
+
+    const FAMILIES: Families = Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+
+    /// 不碰磁盘、后端是 mock 的 App（与 `app/tests.rs` 的 `headless` 同构）。
+    fn headless() -> App {
+        App::with_presenter(
+            Options::default(),
+            FAMILIES,
+            SchemeFlavor::Light,
+            Box::new(MockBackend::new()),
+            SettingsBridge::memory_only(),
+        )
+    }
+
+    /// 走到「真·空闲」：没有观察窗、没有忙碌实例、没有动画（首屏那一条 Boot 已跑完）。
+    ///
+    /// `Boot` 自己就会起跑一次首屏动效（`on_boot` → `sync_motion`），所以必须先把它推完，
+    /// 否则后面的 `assert!(!needs_frames())` 测的是「动画还在跑」而不是「空闲」。
+    fn idle_app() -> App {
+        motion::reset();
+        motion::configure(MotionScale::STANDARD, None);
+        let mut app = headless();
+        // 有窗口才谈得上动效（`sync_motion` 在没有窗口时直接返回，见它的文档）
+        app.window = Some(iced::window::Id::unique());
+        let _ = app.update(Message::Boot);
+        app.watch_until = None;
+        run_until_idle();
+        assert!(!motion::needs_frames(), "前提：首屏动效已经跑完");
+        app
+    }
+
+    /// 把时间轴推到全部轨道结束（每步 16 ms，上限 20 s）。
+    fn run_until_idle() {
+        for _ in 0..1250 {
+            if !motion::needs_frames() {
+                return;
+            }
+            motion::advance_by(FRAME_MS);
+        }
+    }
+
+    /// **按运行时顺序**：空闲态一条消息进来（换页）⇒ **同一拍**订阅表就要有帧；跑完立刻退订。
+    ///
+    /// 变异证明：把起跑搬回 `view`（删掉 `App::update` 里的 `sync_motion`）⇒ 第一步的
+    /// `assert!(app.needs_frames())` 红；把 `Pump::advance` 的「到期即删除」删掉 ⇒ 最后一步红。
+    #[test]
+    fn a_state_change_opens_the_frame_subscription_in_the_same_tick() {
+        let mut app = idle_app();
+        assert!(!app.needs_frames(), "前提：空闲交互态本来就不订阅帧");
+
+        // 用户点了一次导航轨：**一条**消息，之后不再补任何消息
+        let _ = app.update(Message::Page(pages::Message::Navigate(Route::Download)));
+
+        assert!(
+            app.watch_until.is_none(),
+            "换页不该打开观察窗（这里要证明帧是**动效**要来的，不是派发顺手开的）"
+        );
+        assert!(motion::needs_frames(), "换页必须在同一拍起跑");
+        assert!(
+            app.needs_frames(),
+            "同一拍的订阅表必须能看见轨道（iced 先算订阅表、后建视图 —— 复审 P1-1）"
+        );
+
+        run_until_idle();
+        assert!(!motion::needs_frames(), "动画跑完帧泵必须清空");
+        assert!(
+            !app.needs_frames(),
+            "动画结束后必须退回 1 Hz 心跳（占着帧订阅 = 空闲烧帧）"
+        );
+        motion::reset();
+    }
+
+    /// 列表 ↔ 详情同样走「一条消息 ⇒ 当拍有帧」，且 `Detail` 槽真的是那条。
+    #[test]
+    fn opening_a_detail_also_opens_the_frames_in_the_same_tick() {
+        let mut app = idle_app();
+        // 出厂快照会自动选中第一条 ⇒ 先回列表，让「点进详情」真的是一次详情变化
+        let _ = app.update(Message::Page(pages::Message::Navigate(Route::Instances)));
+        run_until_idle();
+        assert!(!app.needs_frames());
+        let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail(
+            "survival".to_string(),
+        ))));
+        assert!(app.needs_frames(), "点进详情必须当拍订阅帧");
+        run_until_idle();
+        assert!(!app.needs_frames());
+        motion::reset();
+    }
+
+    /// 账户页 / AI 独立页**不归 pages 画**：切过去不起跑（否则白跑 300 ms 帧）；切回来照旧跑。
+    #[test]
+    fn pages_that_render_elsewhere_do_not_start_a_track() {
+        let mut app = idle_app();
+        let _ = app.update(Message::Page(pages::Message::Navigate(Route::Accounts)));
+        assert!(
+            !motion::needs_frames(),
+            "账户页没有 pages 树可动，不许白开帧"
+        );
+
+        let _ = app.update(Message::Page(pages::Message::Navigate(Route::Instances)));
+        assert!(motion::needs_frames(), "从账户页回到某一屏仍然是换页，要跑");
+        run_until_idle();
+        motion::reset();
+    }
+
+    /// **没有窗口就不起跑**：`window::frames()` 在没窗口时一条消息都不会有，起跑只是白占一档；
+    /// 首屏那一条也因此要等窗口到了才算「第一眼」。
+    #[test]
+    fn without_a_window_nothing_animates() {
+        motion::reset();
+        motion::configure(MotionScale::STANDARD, None);
+        let mut app = headless();
+        assert!(app.window.is_none(), "前提：还没拿到窗口句柄");
+        let _ = app.update(Message::Boot);
+        app.watch_until = None;
+        assert!(!motion::needs_frames(), "没有窗口 ⇒ 不许起跑");
+
+        // 窗口来了：首屏入场这时才开始（不是被启动期那棵空树吃掉）
+        let _ = app.update(Message::WindowReady(Some(iced::window::Id::unique())));
+        assert!(app.needs_frames(), "窗口到了之后「首屏」才起跑");
+        run_until_idle();
+        motion::reset();
+    }
+
+    /// **`MotionScale::NONE` 真的零订阅**：不是「跑一遍 0 时长动画」。
+    ///
+    /// 变异证明：把 `Pump::play` 的 `is_off()` 分支删掉 ⇒ 帧采样次数非 0，本用例红。
+    #[test]
+    fn no_scale_requests_no_frames_at_all() {
+        motion::reset();
+        let mut app = headless();
+        app.window = Some(iced::window::Id::unique());
+        let _ = app.update(Message::Boot);
+        app.watch_until = None;
+        motion::configure(MotionScale::NONE, None);
+
+        // 三种状态变化：换页 / 换详情 / 再换回来
+        let _ = app.update(Message::Page(pages::Message::Navigate(Route::Download)));
+        assert!(!app.needs_frames(), "关掉动效后换页一帧都不该订阅");
+        let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail(
+            "survival".to_string(),
+        ))));
+        assert!(!app.needs_frames());
+        run_until_idle();
+
+        assert!(!motion::needs_frames());
+        assert_eq!(motion::samples(), 0, "NONE 档的帧采样次数必须是 0");
+        motion::reset();
+    }
+
+    /// 帧订阅在**产品接线**里只出现一处：五条理由共享同一个布尔，所以不会出现「动画与 Busy 各订一条」。
+    ///
+    /// 口径是**全仓 `src/**`**（复审 r1 备注：只扫 `subscription.rs` 抓不到别人另开订阅），只看
+    /// 代码行（注释/文档里提到这个符号不算）。唯一允许的第二个文件是 `pages/harness.rs`——
+    /// 那是 `pages_demo` 这条**独立 example** 自己的 iced app（不接 `App`、不进产品路径）。
+    #[test]
+    fn there_is_exactly_one_frame_subscription() {
+        let src = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
+        let mut files = Vec::new();
+        collect_rust_files(&src, &mut files);
+        assert!(
+            files.len() >= 40,
+            "只扫到 {} 个文件：扫描逻辑坏了",
+            files.len()
+        );
+
+        let mut hits = Vec::new();
+        for path in files {
+            let text = std::fs::read_to_string(&path).expect("读源文件");
+            let product = text.split("#[cfg(test)]").next().unwrap_or(&text);
+            let code = product
+                .lines()
+                .filter(|line| !line.trim_start().starts_with("//"))
+                .collect::<Vec<_>>()
+                .join(
+                    "
+",
+                );
+            let count = code.matches("window::frames()").count();
+            if count > 0 {
+                let name = path
+                    .strip_prefix(&src)
+                    .unwrap_or(&path)
+                    .to_string_lossy()
+                    .replace(std::path::MAIN_SEPARATOR, "/");
+                hits.push((name, count));
+            }
+        }
+
+        hits.sort();
+        let expected = [
+            ("app/subscription.rs".to_string(), 1_usize),
+            ("pages/harness.rs".to_string(), 1_usize),
+        ];
+        assert_eq!(
+            hits, expected,
+            "`window::frames()` 只许出现在 `app/subscription.rs`（产品接线）\
+             与 `pages/harness.rs`（独立 example 的自有 app），且各一处"
+        );
+    }
+
+    /// 递归收集 `dir/**/*.rs`。
+    fn collect_rust_files(dir: &std::path::Path, out: &mut Vec<std::path::PathBuf>) {
+        for entry in std::fs::read_dir(dir).expect("读目录") {
+            let path = entry.expect("目录项").path();
+            if path.is_dir() {
+                collect_rust_files(&path, out);
+            } else if path.extension().is_some_and(|ext| ext == "rs") {
+                out.push(path);
+            }
+        }
+    }
+
+    /// 槽枚举的可见性检查：`Slot` 只经帧泵导出（页面拿不到「给我 250ms」这种口子）。
+    #[test]
+    fn slots_are_the_three_documented_ones() {
+        assert_eq!(Slot::ALL.len(), 3);
+        assert_eq!(Slot::ALL.map(Slot::name), ["boot", "screen", "detail"]);
+    }
+}

crates/app-iced/src/app/tests.rs

@@ -0,0 +1,386 @@
+//! `app` 的单测：主题切换、窗口尺寸、截图闸门、gallery 能构图，以及**presenter 接线的闭环**。
+//!
+//! 闭环测试用的是 `MockBackend`（presenter 自带的假后端）：它走的是与真 host 完全相同的
+//! `dispatch → drain_events → AppState::apply → 视图模型` 通道，所以「点 Play → 状态真的变」
+//! 这件事在这里就能判死，不必等图形环境。
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_presenter::mock::MockBackend;
+use unlucky_presenter::router::Route;
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+#[cfg(test)]
+mod appearance;
+#[cfg(test)]
+mod instances_save_loop;
+#[cfg(test)]
+mod presenter;
+
+use super::message::Message;
+use super::state::App;
+use super::{APP_TITLE, WINDOW_SIZE};
+use crate::cli::{Options, Screen};
+use crate::pages;
+use crate::shell::agent::RailState;
+use crate::shell::NavItem;
+use crate::theme::Families;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+/// 不碰磁盘的 App（mock 后端 + 内存设置桥）。
+fn headless(options: Options, flavor: SchemeFlavor) -> App {
+    App::with_presenter(
+        options,
+        FAMILIES,
+        flavor,
+        Box::new(MockBackend::new()),
+        SettingsBridge::memory_only(),
+    )
+}
+
+fn screenshot_options() -> Options {
+    Options {
+        screenshot: Some(std::path::PathBuf::from("x.png")),
+        ..Options::default()
+    }
+}
+
+#[test]
+fn switching_flavor_rebuilds_styles_but_keeps_ui_state() {
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    app.state.navigate(Route::Logs);
+    app.refresh_view();
+    assert_eq!(app.ui().name(), "ull-silver");
+
+    app.set_flavor(SchemeFlavor::Dark);
+
+    assert_eq!(app.ui().name(), "ull-ink", "切主题要换主题名");
+    assert_eq!(app.state.route(), &Route::Logs, "切主题不许重置 UI 状态");
+    assert_eq!(app.view.screen, pages::Screen::Logs, "视图模型跟着路由");
+    assert!(app.options.screenshot.is_none(), "切主题不许改启动参数");
+}
+
+#[test]
+fn window_size_is_the_acceptance_size() {
+    assert_eq!((WINDOW_SIZE.width, WINDOW_SIZE.height), (1180.0, 760.0));
+    assert_eq!(APP_TITLE, "Unlucky Launcher");
+}
+
+#[test]
+fn screenshot_mode_never_waits_for_the_system_theme() {
+    // 门禁依赖：CI 的 runtime-smoke 不带主题，xvfb 里也没有主题会话。
+    let options = screenshot_options();
+    assert!(!options.wants_system_theme(), "截图模式不许等系统主题");
+    assert_eq!(options.capture_flavor(), Some(SchemeFlavor::Light));
+
+    let app = headless(options, SchemeFlavor::Light);
+    assert!(app.has_screenshot() && app.ui().name() == "ull-silver");
+}
+
+#[test]
+fn gallery_screen_builds_a_tree() {
+    assert_eq!(Options::default().screen, Screen::Shell, "默认仍是产品骨架");
+    let options = Options {
+        screen: Screen::Gallery,
+        ..Options::default()
+    };
+    let app = headless(options, SchemeFlavor::Light);
+    // 真实像素由 `--screen=gallery --screenshot` 出图 + `gallery::probe` 量
+    let _ = app.view();
+}
+
+#[test]
+fn frames_are_only_requested_in_screenshot_mode() {
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    assert!(!app.wants_frames(), "普通运行不订阅帧，避免每帧重绘");
+
+    app.options.screenshot = Some(std::path::PathBuf::from("x.png"));
+    assert!(
+        app.wants_frames(),
+        "截图模式必须订阅帧事件才能在第 3 帧出图"
+    );
+}
+
+// --------------------------------------------------------------- P2-1 按需节拍
+
+/// 空闲态**不要每帧节拍**（但要有 1 Hz 心跳）。
+///
+/// 意图与 r2 那条 `an_idle_app_asks_for_no_clock` 一致：空闲时不许按帧循环跑（那会以每秒几百帧
+/// 的速度重绘整窗），改成「低频心跳」。断言拆成两半：
+///
+/// 1. `needs_frames()` 为假 ⇒ **不订阅** `window::frames()`；
+/// 2. 空闲时钟的周期 = [`IDLE_TICK`] = 1 s，且心跳每拍推进的 tick 预算 = 30（= 1 s / 33 ms），
+///    这样 `theme::config_poll_due`（30 拍）仍是「约 1 秒比对一次 mtime」。
+///
+/// 抓得住：有人把「无条件订阅帧」改回来（第 1 半红）；有人把心跳周期改快/改慢（第 2 半红）。
+/// 抓不住：真实窗口的重绘次数（那要 `ULL_TICK_TRACE=1` 跑一次交互模式看日志，见报告）。
+#[test]
+fn an_idle_app_uses_a_slow_heartbeat_instead_of_frames() {
+    let app = headless(screenshot_options(), SchemeFlavor::Light);
+    assert!(app.needs_frames(), "截图通道永远要帧（第 3 帧落盘）");
+
+    let mut idle = headless(Options::default(), SchemeFlavor::Light);
+    let _ = idle.update(Message::Boot);
+    assert!(
+        idle.needs_frames(),
+        "Boot 刚派发过 RefreshAll：3 秒观察窗内要节拍（等真 host 的首批事件）"
+    );
+
+    // 观察窗过期、也没有忙碌实例 ⇒ 空闲态不订阅帧事件（改走 1 Hz 心跳）
+    idle.watch_until = None;
+    assert!(!idle.needs_frames(), "空闲交互态：不订阅帧事件（只有心跳）");
+
+    // 派发之后观察窗重新打开
+    let _ = idle.update(Message::Page(pages::Message::Navigate(Route::Detail(
+        "survival".to_string(),
+    ))));
+    let _ = idle.update(Message::Page(pages::Message::Launch(
+        "survival".to_string(),
+    )));
+    assert!(idle.needs_frames(), "派发后观察窗内要有节拍");
+
+    // 进入 Busy 之后由「忙碌实例」这个条件自己续订（不靠观察窗）
+    idle.watch_until = None;
+    assert!(
+        idle.needs_frames(),
+        "有 Busy 实例时即便观察窗过期也要继续 tick"
+    );
+}
+
+/// 心跳的**节奏**：1 Hz，且每拍折算 30 个 33 ms 单位 ⇒ `config_poll_due` ≈ 每秒一次。
+///
+/// 抓得住：心跳周期常量、以及 `advance()` 里「按流逝时间折算 ticks」这条记账（改回
+/// `ticks += 1` 会让空闲态的配置轮询变成 30 秒一次，这条就红）。
+/// 抓不住：`Task::perform` 那条自续链真的每秒触发一次（那是运行期 trace 的事，见报告）。
+#[test]
+fn the_idle_heartbeat_budgets_one_config_poll_per_second() {
+    use unlucky_presenter::theme::config_poll_due;
+
+    assert_eq!(
+        super::state::IDLE_TICK,
+        std::time::Duration::from_secs(1),
+        "空闲心跳周期必须是 1 s"
+    );
+
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    let _ = app.update(Message::Boot);
+    app.watch_until = None;
+
+    // 一次空闲心跳（1 s）之后：ticks 增加 30，且正好落在 config 轮询点上
+    let before = app.ticks;
+    app.advance(super::state::IDLE_TICK);
+    assert_eq!(app.ticks - before, 30, "1 s 应折算 30 个 33 ms 拍");
+    assert!(
+        config_poll_due(app.ticks),
+        "空闲心跳每拍都要落在 config 轮询点上（ticks={}）",
+        app.ticks
+    );
+}
+
+/// 空闲态每拍**不再重建视图模型**（P2-1 的另一半：`refresh_view` 的 30 Hz × N 实例白克隆）。
+///
+/// 抓得住：把 `advance()` 里的 `if self.view_dirty` 去掉（改回无条件 `refresh_view()`）时，
+/// 这条断言里的 `refreshes` 会从「不增长」变成「每拍 +1」。
+/// 抓不住：「重建一次花了多少微秒」（没有基准测试；量级判断见报告）。
+#[test]
+fn idle_ticks_do_not_rebuild_the_view_model() {
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    let _ = app.update(Message::Boot);
+
+    let before = app.refreshes;
+    for _ in 0..100 {
+        app.advance(super::state::TICK);
+    }
+    assert_eq!(
+        app.refreshes,
+        before,
+        "空闲 100 拍：视图模型一次都不该重建（实际 +{}）",
+        app.refreshes - before
+    );
+
+    // 有事件进来时仍然要重建（否则页面不刷新）
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Logs)));
+    assert!(app.refreshes > before, "导航之后必须重建一次");
+}
+/// 视图模型跟着窗口宽度走（交互模式下 600 / 840 两条断点靠 resize 事件生效）。
+///
+/// M104 起 `view.window_width` 装的是**中栗可用宽度**（窗口 − 右栗 − 拖拽缝），所以这里按三档
+/// 各钉一个**字面量**：48 的折叠条与 320 的面板各自的减法都得对。
+/// （断言里不调 `agent.content_width(..)`——那是同义反复，实现错一处它照样绿。）
+#[test]
+fn resizing_the_window_rebuilds_the_view_model() {
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    let _ = app.update(Message::Boot);
+
+    // 出厂是 Collapsed(48) 档：中栗 = 窗口 − 48
+    let _ = app.update(Message::Window(iced::window::Event::Resized(
+        iced::Size::new(1180.0, 760.0),
+    )));
+    assert!(
+        (app.view.window_width - 1132.0).abs() < f32::EPSILON,
+        "1180 − 48（折叠条）= 1132，实际 {}",
+        app.view.window_width
+    );
+
+    let _ = app.update(Message::Window(iced::window::Event::Resized(
+        iced::Size::new(700.0, 600.0),
+    )));
+    assert!(
+        (app.view.window_width - 652.0).abs() < f32::EPSILON,
+        "700 − 48（折叠条）= 652，实际 {}",
+        app.view.window_width
+    );
+
+    // Expanded(320) 档：中栗 = 窗口 − 320（面板）− 8（拖拽缝）= 852
+    app.agent.expand();
+    app.view_dirty = true;
+    app.refresh_view();
+    assert!(
+        (app.view.window_width - 652.0).abs() < f32::EPSILON,
+        "700 上展开档不成立（上限 700 − 88 − 472 − 8 = 132 < 280）⇒ 实际按折叠条 48 算：         700 − 48 = 652，实际 {}",
+        app.view.window_width
+    );
+    let _ = app.update(Message::Window(iced::window::Event::Resized(
+        iced::Size::new(1180.0, 760.0),
+    )));
+    assert!(
+        (app.view.window_width - 852.0).abs() < f32::EPSILON,
+        "1180 − 320 − 8 = 852，实际 {}",
+        app.view.window_width
+    );
+
+    // Detached 档：右栗不占宽，中栗 = 窗口 = 1180。
+    // **必须走路由**（`Select(Ai)`）：r1 之后「档位 = Detached」与「路由 = Agent」是一条不变式，
+    // 直接 `agent.detach()` 再手工 refresh 会被 `sync_agent_route` 立刻收回右栗（那正是要的语义）。
+    let _ = app.update(Message::Select(NavItem::Ai));
+    app.view_dirty = true;
+    app.refresh_view();
+    assert!(
+        (app.view.window_width - 1180.0).abs() < f32::EPSILON,
+        "拆出后右栗不占宽：1180 − 0 = 1180，实际 {}",
+        app.view.window_width
+    );
+    // 页面照旧能构图（窄窗退化到单列，不 panic）
+    let _ = app.view();
+}
+
+/// **不变式（复审 r1 的 P2-1）**：`Route::Agent` ⟺ `RailState::Detached`。
+///
+/// 走的是**真实路由入口**（外壳导航第五项 `Assistant` → `Message::Select(NavItem::Ai)`），不是
+/// 直接调 `agent.detach()`：r1 复现的 bug 正是「导航进页面时档位没变」，只测 `detach()` 抓不到它。
+///
+/// 抓得住：①进独立页后档位 = Detached（页头才会是 `Dock back` 而不是 `Open assistant`/`Pop out`）；
+/// ②未读在进页时清零；③`Esc` 在独立页真的离开（不是只把档位改成折叠）；④从页上点别的导航，
+/// 会话收回右栗（档位不再停在 Detached）。
+/// 抓不住：按钮在像素上长什么样（那要出图，见 `13/14` 两张）。
+#[test]
+fn entering_the_agent_route_detaches_the_rail() {
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    let _ = app.update(Message::Boot);
+    assert_eq!(app.agent.rail, RailState::Collapsed, "出厂是折叠档");
+    // M119：出厂没有样本会话，未读由 presenter 按真事件累加 ⇒ 出厂就是 0
+    assert_eq!(app.agent_host.rail().unread, 0, "出厂 0 条未读");
+
+    // ① 外壳导航第五项（真实入口）
+    let _ = app.update(Message::Select(NavItem::Ai));
+    assert_eq!(app.state.route(), &Route::Agent);
+    assert_eq!(
+        app.agent.rail,
+        RailState::Detached,
+        "进了独立页，档位必须是 Detached——否则页头会画右栗才有的动作"
+    );
+    assert_eq!(app.agent_host.rail().unread, 0, "进独立页即读");
+
+    // ③ Esc 真的离开这一页
+    let _ = app.update(Message::Agent(crate::shell::agent::Message::Escape));
+    assert_ne!(app.state.route(), &Route::Agent, "独立页上 Esc 必须离开");
+    assert_eq!(app.agent.rail, RailState::Expanded, "收回到右栗展开档");
+
+    // ④ 从独立页点别的导航：会话收回右栗（档位不能停在 Detached）
+    let _ = app.update(Message::Select(NavItem::Ai));
+    assert_eq!(app.agent.rail, RailState::Detached);
+    let _ = app.update(Message::Select(NavItem::Instances));
+    assert_eq!(app.state.route(), &Route::Instances);
+    assert_eq!(
+        app.agent.rail,
+        RailState::Expanded,
+        "离开独立页 ⇒ 会话收回右栗（否则页走了、栏还是 0 宽）"
+    );
+}
+
+/// 同一条不变式的另一个入口：页面层的 `Navigate(Route::Agent)`（右栗里的 `pages::Message` 路径）。
+#[test]
+fn the_page_navigation_entry_also_detaches() {
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    let _ = app.update(Message::Boot);
+    // 走真消息（不是直接改字段）：这样「展开即读」的 `agent_mark_read` 也会真的发生
+    let _ = app.update(Message::Agent(crate::shell::agent::Message::Expand));
+    assert_eq!(app.agent.rail, RailState::Expanded);
+
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Agent)));
+    assert_eq!(app.state.route(), &Route::Agent);
+    assert_eq!(app.agent.rail, RailState::Detached);
+    assert_eq!(app.agent_host.rail().unread, 0);
+
+    // 页面层回退（不是 Dock 消息）也要把档位收回来
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Instances)));
+    assert_eq!(app.agent.rail, RailState::Expanded);
+}
+
+/// 截图模式不读设置文件里的主题（D30 可复现：两台机器出同一张图）。
+#[test]
+fn screenshot_mode_ignores_the_settings_file_theme() {
+    let mut app = headless(screenshot_options(), SchemeFlavor::Light);
+    app.apply_config_theme();
+    assert_eq!(app.ui().name(), "ull-silver", "截图模式的主题只认命令行");
+}
+
+/// 主题优先级：`--theme` > 配置文件 `appearance.theme_mode` > 系统主题。
+///
+/// r2 之前 `Message::SystemTheme` 无条件 `set_flavor`，于是「配置文件写 dark、系统是浅色」会
+/// 出现 `light -> dark -> light` 的一次抖动、配置永远不生效（r3 做 P2-2 的配置热切实测时暴露
+/// 出来，一并修）。
+///
+/// 抓得住：系统主题不许盖掉显式配置/命令行给出的主题（三条分支各一条断言）。
+/// 抓不住：真实桌面切换系统主题时的事件时序（只有消息级验证）。
+#[test]
+fn the_system_theme_never_overrides_an_explicit_one() {
+    use unlucky_presenter::prefs::ThemeMode;
+
+    // ① auto（内存桥默认）：系统主题说了算
+    let mut auto = headless(Options::default(), SchemeFlavor::Light);
+    assert_eq!(auto.theme_mode, ThemeMode::Auto);
+    let _ = auto.update(Message::SystemTheme(iced::theme::Mode::Dark));
+    assert_eq!(auto.ui().name(), "ull-ink", "auto 模式要跟随系统");
+
+    // ② 配置文件显式 dark：系统给浅色也不许改
+    let mut pinned = headless(Options::default(), SchemeFlavor::Dark);
+    pinned.theme_mode = ThemeMode::Dark;
+    let _ = pinned.update(Message::SystemTheme(iced::theme::Mode::Light));
+    assert_eq!(
+        pinned.ui().name(),
+        "ull-ink",
+        "配置文件说 dark，系统说 light：不许改"
+    );
+
+    // ③ 命令行 `--theme` 优先级最高
+    let mut explicit = headless(
+        Options {
+            theme: Some(SchemeFlavor::Dark),
+            ..Options::default()
+        },
+        SchemeFlavor::Dark,
+    );
+    let _ = explicit.update(Message::SystemTheme(iced::theme::Mode::Light));
+    assert_eq!(
+        explicit.ui().name(),
+        "ull-ink",
+        "--theme 优先级最高，系统主题不许盖"
+    );
+}
+
+mod theme;

crates/app-iced/src/app/tests/appearance.rs

@@ -0,0 +1,331 @@
+//! 外观接线的单测：**配置 → 状态 → 下发字节 / 像素 / 落盘**。
+//!
+//! 每条都按本 mission 的验收纪律写「抓得住 / 抓不住」。真机才有的东西（`WS_EX_LAYERED` 是否补上、
+//! `LWA_ALPHA` 的观感）不在这里假装——那是 `[appearance]` 日志与报告里「没验的部分」的事。
+
+use std::path::PathBuf;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_presenter::mock::MockBackend;
+use unlucky_presenter::prefs::{BgFill, PaletteSource};
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+use crate::cli::{Backend, Options};
+use crate::pages::appearance::{self, Change, State};
+use crate::pages::{self, Screen};
+
+use super::{headless, FAMILIES};
+
+use super::super::state::App;
+
+/// 一个把配置写在临时文件里的 App（测「读回 / 写回」必须真的过文件）。
+fn with_config(json: &str, backend: Backend, label: &str) -> (App, PathBuf) {
+    let dir = std::env::temp_dir().join(format!(
+        "ull-appear-{label}-{}-{}",
+        std::process::id(),
+        line!()
+    ));
+    std::fs::create_dir_all(dir.join("config")).expect("临时目录");
+    let path = dir.join("config/launcher.json");
+    std::fs::write(&path, json).expect("写配置文件");
+
+    let app = App::with_presenter(
+        Options {
+            backend,
+            ..Options::default()
+        },
+        FAMILIES,
+        SchemeFlavor::Light,
+        Box::new(MockBackend::new()),
+        SettingsBridge::with_path(&path),
+    );
+    (app, dir)
+}
+
+fn cleanup(dir: &PathBuf) {
+    std::fs::remove_dir_all(dir).ok();
+}
+
+/// 抓得住：配置里写 `window_opacity=0.8` → 启动读回 0.8 → 下发字节 205（钳位链的入口那一段）。
+/// 抓不住：Win32 是否真的收下 204（`transparency` 的单测与本机日志各自举证）。
+#[test]
+fn the_configured_window_alpha_is_read_back_and_turned_into_a_byte() {
+    let (app, dir) = with_config(
+        r#"{"appearance":{"window_opacity":0.8,"palette_source":"preset"}}"#,
+        Backend::Cpu,
+        "read",
+    );
+
+    assert_eq!(app.appearance.window_opacity, 0.8);
+    assert_eq!(
+        app.appearance.window_alpha_byte(),
+        Some(205),
+        "f32 0.8 → f64 略大于 0.8 → ceil 205（不向下取整）"
+    );
+    // CPU 档：窗口 α 允许，面板 α 强制 1.0。
+    assert_eq!(app.appearance.effective_panel_alpha(), 1.0);
+    assert!(app.appearance.panel_is_forced());
+    cleanup(&dir);
+}
+
+/// 抓得住：①面板 α 滑到 0.8 → 状态是 0.8、生效值 GPU 档也是 0.8；
+/// ②CPU 档下滑到 0.5 → 生效值仍是 1.0，而**请求值**仍是 0.5（界面上的「requested → forced」靠这条）。
+/// 抓不住：这层半透明在屏幕上到底多透（RDP 上不可信，见报告）。
+#[test]
+fn panel_alpha_is_independent_of_the_window_alpha_and_forced_on_cpu() {
+    let mut gpu = headless(Options::default(), SchemeFlavor::Light);
+    gpu.appearance.apply(Change::PanelAlpha(0.8));
+    assert_eq!(gpu.appearance.panel_alpha, 0.8);
+    assert_eq!(gpu.appearance.effective_panel_alpha(), 0.8);
+    assert_eq!(gpu.appearance.window_opacity, 1.0, "面板 α 不许带动整窗 α");
+
+    let mut cpu = headless(
+        Options {
+            backend: Backend::Cpu,
+            ..Options::default()
+        },
+        SchemeFlavor::Light,
+    );
+    assert!(
+        !cpu.appearance.apply(Change::PanelAlpha(0.5)),
+        "只有整窗 α 需要立刻下发（面板 α 只重绘）"
+    );
+    assert_eq!(cpu.appearance.panel_alpha, 0.5, "请求值保留");
+    assert_eq!(
+        cpu.appearance.effective_panel_alpha(),
+        1.0,
+        "CPU 档强制 1.0"
+    );
+    assert_eq!(cpu.appearance.window_alpha_byte(), None, "整窗 α 仍是 1.0");
+}
+
+/// 抓得住：一次滑块改动 → 落盘 → **新开一个 bridge** 能读回（= 重启后还在）。
+/// 抓不住：真 host 是否也写了同一份文件（`AppCommand::SetSetting` 走的是同一份 schema）。
+#[test]
+fn a_panel_alpha_change_is_written_back_to_the_config_file() {
+    let (mut app, dir) = with_config("{}", Backend::Gpu, "write");
+    app.on_appearance(Change::PanelAlpha(0.8));
+    app.on_appearance(Change::BgFill(BgFill::Tile));
+    app.on_appearance(Change::BgDim(0.5));
+
+    let path = dir.join("config/launcher.json");
+    let reopened = SettingsBridge::with_path(&path).load().0;
+    assert_eq!(reopened.panel_alpha, 0.8);
+    assert_eq!(reopened.bg_fill, BgFill::Tile);
+    assert!((reopened.bg_dim - 0.5).abs() < 1e-6);
+    assert_eq!(
+        app.appearance_prefs.panel_alpha, 0.8,
+        "内存里的「已落盘快照」也要跟上，否则下一次写回会拿旧基底覆盖"
+    );
+    cleanup(&dir);
+}
+
+/// 抓得住：路径读不出来时 ①不 panic ②`background_active()` 为假（静默回落）
+/// ③诊断里有一句人话（不是空串）④配色回落到色卡档（不换 scheme）。
+/// 抓不住：这张图在别的机器上路径存在时会怎样（那是成功路径，另一条测试管）。
+#[test]
+fn a_broken_background_path_falls_back_silently_but_says_why() {
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    app.appearance
+        .apply(Change::BgImage("D:/definitely/not/here.png".to_owned()));
+
+    assert!(!app.appearance.background_active());
+    assert!(app.appearance.image().is_none(), "解码失败 ⇒ 没有可用图");
+    assert_eq!(app.appearance.diagnostics().len(), 1, "恰好一条诊断");
+    assert!(
+        app.appearance.diagnostics()[0].contains("could not be read"),
+        "诊断要是人话：{:?}",
+        app.appearance.diagnostics()
+    );
+    assert_eq!(app.appearance.palette_level(), "preset", "回落色卡");
+    assert!(
+        app.appearance.derived_scheme().is_none(),
+        "色卡档不换 scheme"
+    );
+}
+
+/// 抓得住：真 PNG → 背景真的生效（解出原图尺寸、路径留给渲染器、配色走「背景图取色」这一级）。
+/// 抓不住：渲染出来的像素（由截图举证），以及三种填充的覆盖范围（由 `background::tiles` 的
+/// 「覆盖 ≥ 视口」断言守）。
+#[test]
+fn a_decodable_png_makes_the_background_and_the_palette_active() {
+    let dir = std::env::temp_dir().join(format!("ull-appear-png-{}", std::process::id()));
+    std::fs::create_dir_all(&dir).expect("临时目录");
+    let path = dir.join("bg.png");
+    let image = image::RgbImage::from_fn(64, 32, |x, _y| {
+        if x < 32 {
+            image::Rgb([200, 30, 30])
+        } else {
+            image::Rgb([20, 60, 200])
+        }
+    });
+    image.save(&path).expect("写 png");
+
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    app.appearance
+        .apply(Change::PaletteSource(PaletteSource::BackgroundImage));
+    app.appearance
+        .apply(Change::BgImage(path.to_string_lossy().to_string()));
+    app.rebuild_ui();
+
+    assert!(app.appearance.background_active());
+    assert!(app.appearance.image().is_some(), "解码成功 ⇒ 有可用图");
+    assert!(
+        !app.appearance.bg_path.trim().is_empty(),
+        "渲染器按路径解码（见 picture::image_handle）"
+    );
+    assert_eq!(app.appearance.diagnostics().len(), 0, "成功时没有诊断");
+    assert_eq!(app.appearance.palette_level(), "background-image");
+    assert!(
+        app.appearance.derived_scheme().is_some(),
+        "取色成功后 Ui 要换成解析出的方案"
+    );
+    // 换 scheme 之后主题名仍是同一个（深浅没变），但 primary 必须与 baseline 不同。
+    assert_eq!(app.ui().name(), "ull-silver");
+    let baseline = crate::theme::Ui::new(SchemeFlavor::Light, FAMILIES);
+    assert_ne!(
+        app.ui().color(unlucky_design::color::Role::Primary),
+        baseline.color(unlucky_design::color::Role::Primary)
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// 抓得住：设置页在有外观状态时能真的构图（真控件树，含文本框/滑块/互斥按钮），并且
+/// 「外观」分组的下标与 `appearance::APPEARANCE_GROUP` 一致（点左列能切过去）。
+/// 抓不住：这些控件点下去之后的交互（`Message` 的落点由 `on_appearance` 的其它测试管）。
+#[test]
+fn the_settings_page_renders_the_real_appearance_group() {
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    app.state
+        .navigate(unlucky_presenter::router::Route::Settings);
+    app.refresh_view();
+    assert_eq!(app.view.screen, Screen::Settings);
+    assert_eq!(app.appearance.selected_group, appearance::APPEARANCE_GROUP);
+
+    let _tree = pages::page_with_appearance(&app.ui, &app.view, &app.appearance, &app.launch_form);
+    drop(_tree);
+
+    // 切分组：只改视图状态，不落盘（`Change::SelectGroup` 的 key() == None）。
+    app.appearance.apply(Change::SelectGroup(0));
+    assert_eq!(app.appearance.selected_group, 0);
+    let _tree = pages::page_with_appearance(&app.ui, &app.view, &app.appearance, &app.launch_form);
+}
+
+/// **P2-2 的守门（复审 r1）**：面板 α 只作用到允许半透明的层。
+///
+/// 抓得住：`Ui::layer(Canvas)` 在 α=0.55 时仍是不透明（标题栏/导航轨/页头带都取 Canvas，
+/// 它们一旦透底，三个窗口键与导航文字就压在背景照片上）；`Card` / `Overlay` 必须真的吃到 α。
+/// 抓不住：真实合成后的观感（那由截图看）。
+#[test]
+fn the_canvas_layer_stays_opaque_while_panels_take_the_alpha() {
+    use unlucky_design::elevation::MaterialLayer;
+
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    app.appearance.apply(Change::PanelAlpha(0.55));
+    app.rebuild_ui();
+
+    let ui = app.ui();
+    assert_eq!(ui.panel_alpha(), 0.55, "生效值进了 Ui");
+    assert_eq!(
+        ui.layer(MaterialLayer::Canvas).a,
+        1.0,
+        "窗口底（标题栏/导航轨/页头带）永远不透明——令牌的不变量"
+    );
+    for layer in [MaterialLayer::Card, MaterialLayer::Overlay] {
+        assert!(
+            (ui.layer(layer).a - 0.55).abs() < 1e-6,
+            "{layer:?} 必须吃面板 α（实际 {}）",
+            ui.layer(layer).a
+        );
+    }
+
+    // CPU 档：α 被强制 1.0 ⇒ 连卡片也不透明。
+    let mut cpu = headless(
+        Options {
+            backend: Backend::Cpu,
+            ..Options::default()
+        },
+        SchemeFlavor::Light,
+    );
+    cpu.appearance.apply(Change::PanelAlpha(0.55));
+    cpu.rebuild_ui();
+    assert_eq!(cpu.ui().layer(MaterialLayer::Card).a, 1.0, "CPU 档强制 1.0");
+}
+
+/// 抓得住：**把滑块从头拖到尾**（0.00 → 1.00 的 11 个档）时，状态里的整窗 α 与下发字节逐档单调
+/// 上升、且最低一档就是下限字节 21（= 0.0824 ≥ 0.08）、最后一档不透明（不给字节）。
+/// 这就是「拖动 → 实际 α」的链条在数值上的等价物；真机拖动的那一次由二进制日志举证。
+/// 抓不住：拖动的手感与真实观感（RDP 上不可信）。
+#[test]
+fn a_slider_sweep_moves_the_alpha_and_the_byte_monotonically() {
+    let mut app = headless(Options::default(), SchemeFlavor::Light);
+    let mut bytes = Vec::new();
+    for step in 0..=10 {
+        let fraction = step as f32 / 10.0;
+        let alpha = crate::pages::appearance::alpha::window_alpha_from_fraction(fraction);
+        app.appearance.apply(Change::WindowOpacity(alpha));
+        let byte = app.appearance.window_alpha_byte();
+        bytes.push(byte);
+        // 每一档都要能打出一行（数值而不是观感）。
+        assert!(app.appearance.log_line("sweep").contains("window_alpha="));
+    }
+
+    assert_eq!(bytes[0], Some(21), "0% 一档 = 下限 0.08 → 21");
+    assert_eq!(bytes[10], None, "100% 一档 = 不透明 → 不下发");
+    let sent: Vec<u8> = bytes.iter().flatten().copied().collect();
+    assert!(
+        sent.windows(2).all(|pair| pair[0] <= pair[1]),
+        "字节必须单调不减：{sent:?}"
+    );
+    assert_eq!(sent.len(), 10, "除最后一档（不透明）之外每档都有字节");
+    assert!(
+        sent.iter().all(|byte| *byte >= 21),
+        "任何一档都不许低于下限字节：{sent:?}"
+    );
+}
+
+/// 抓得住：日志行里有请求值、生效值与下发字节（RDP 上唯一可信的证据形态）。
+/// 抓不住：这行日志是否真的被写进了 stderr（本测试只钉格式，真机日志由跑起来的二进制举证）。
+#[test]
+fn the_log_line_carries_requests_effective_values_and_the_byte() {
+    let mut cpu = headless(
+        Options {
+            backend: Backend::Cpu,
+            ..Options::default()
+        },
+        SchemeFlavor::Light,
+    );
+    cpu.appearance.apply(Change::WindowOpacity(0.5));
+    cpu.appearance.apply(Change::PanelAlpha(0.4));
+
+    let line = cpu.appearance.log_line("change");
+    assert!(line.starts_with("[appearance] change "), "{line}");
+    assert!(line.contains("window_alpha=0.500"), "{line}");
+    assert!(line.contains("panel_alpha=1.000"), "CPU 档生效值：{line}");
+    assert!(line.contains("(requested 0.400)"), "请求值也要在：{line}");
+    assert!(
+        line.contains("byte=128"),
+        "0.5×255=127.5 → 向上取整 128：{line}"
+    );
+
+    // 不透明时不给字节（而不是给 255）。
+    let opaque = headless(Options::default(), SchemeFlavor::Light);
+    assert!(opaque.appearance.log_line("boot").contains("byte=none"));
+}
+
+/// 抓得住：`State::new` 与 `apply_env` 之外，`State` 的构造不会偷偷读环境（测试之间不串味）。
+/// 抓不住：`ULL_APPEARANCE_*` 在真机上的解析（`apply_env` 由截图矩阵覆盖，见报告）。
+#[test]
+fn a_fresh_state_is_the_factory_appearance() {
+    let state = State::new(
+        &unlucky_presenter::prefs::AppearancePrefs::factory(),
+        &unlucky_presenter::prefs::AppearanceBase::factory(),
+        Backend::Gpu,
+        SchemeFlavor::Light,
+    );
+    assert_eq!(state.window_opacity, 1.0);
+    assert_eq!(state.effective_panel_alpha(), 1.0);
+    assert!(!state.background_active());
+    assert!(state.diagnostics().is_empty());
+    assert!(state.image().is_none());
+}

crates/app-iced/src/app/tests/instances_save_loop.rs

@@ -0,0 +1,145 @@
+//! 「启动参数保存失败」的**整环**回归（M157 r4 复审 P3-a）。
+//!
+//! 仓里原来只有这条环的两半：`LaunchForm::sync` 的单测（本 crate 的 `pages/instances/state.rs`）
+//! 与「Save 只派发不清脏」（`app/update/instances.rs`）。两半各自绿，但**接线**（消息 →
+//! `dispatch` → 后端回事件 → `pump` → `refresh_view` → `sync_launch_form`）没有任何活着的断言。
+//! 把 `dirty = false` 提前到派发前，只有这条整环测试会红（单测两半都不会）。
+//!
+//! 造的后端与真 host 的失败路径同形：收到 `SetInstanceLaunchArgs` 只回一条 Toast（错误的用户
+//! 可见反馈），**不回** `InstancesChanged`——盘上没改，快照还是旧的。
+
+use std::cell::RefCell;
+use std::rc::Rc;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_presenter::dto::{
+    AppCommand, AppEvent, Backend, CoreEvent, InstanceRuntime, InstanceSummary, LaunchArgsView,
+    LoaderInfo, LoaderKind,
+};
+use unlucky_presenter::router::Route;
+use unlucky_presenter::settings_bridge::SettingsBridge;
+use unlucky_presenter::toast::{Toast, ToastKind};
+
+use crate::app::message::Message;
+use crate::app::state::{App, TICK};
+use crate::cli::Options;
+use crate::pages;
+use crate::theme::Families;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+/// 失败路径的后端：命令进台账；`SetInstanceLaunchArgs` 只回一条错误 Toast。
+#[derive(Debug, Default)]
+struct FailingSaveBackend {
+    dispatched: Rc<RefCell<Vec<AppCommand>>>,
+    queued: Vec<AppEvent>,
+}
+
+impl Backend for FailingSaveBackend {
+    fn drain_events(&mut self) -> Vec<AppEvent> {
+        std::mem::take(&mut self.queued)
+    }
+
+    fn dispatch(&mut self, command: AppCommand) {
+        self.dispatched.borrow_mut().push(command.clone());
+        if matches!(command, AppCommand::SetInstanceLaunchArgs { .. }) {
+            // 真 host 在 `dispatch_inner` 的 Err 分支只发 toast（不发 InstancesChanged）。
+            self.queued.push(AppEvent::Toast(Toast {
+                id: 0,
+                kind: ToastKind::Error,
+                text: "内存超出范围".to_string(),
+                remaining_ms: 0,
+            }));
+        }
+    }
+}
+
+/// 盘上的实例快照：内存 4096、其余留空（= 保存失败时 pump 会带回来的那份）。
+fn snapshot() -> Vec<InstanceSummary> {
+    vec![InstanceSummary {
+        id: "survival".to_string(),
+        name: "生存".to_string(),
+        mc_version: "1.20.4".to_string(),
+        loader: LoaderInfo {
+            kind: LoaderKind::Vanilla,
+            version: String::new(),
+        },
+        last_played: None,
+        runtime: InstanceRuntime::Idle,
+        icon: None,
+        isolation: "isolated".to_string(),
+        version_id: "1.20.4".to_string(),
+        version_present: true,
+        launch: LaunchArgsView {
+            instance_id: "survival".to_string(),
+            memory_mb: Some(4096),
+            memory_effective_mb: 4096,
+            ..LaunchArgsView::default()
+        },
+    }]
+}
+
+fn app_with_snapshot() -> (App, Rc<RefCell<Vec<AppCommand>>>) {
+    let dispatched = Rc::new(RefCell::new(Vec::new()));
+    let backend = FailingSaveBackend {
+        dispatched: Rc::clone(&dispatched),
+        queued: vec![AppEvent::Core(CoreEvent::InstancesChanged(snapshot()))],
+    };
+    let app = App::with_presenter(
+        Options::default(),
+        FAMILIES,
+        SchemeFlavor::Light,
+        Box::new(backend),
+        SettingsBridge::memory_only(),
+    );
+    (app, dispatched)
+}
+
+/// **保存失败不许吃掉草稿**（整环）：输入 `4g` → 点保存 → 后端回错误事件 → pump 重建视图。
+///
+/// 抓得住：①`Save` 在派发前清脏（草稿被旧快照覆盖成 4096）；②`LaunchForm::sync` 去掉
+/// `matches` 判据（同样覆盖）；③`pump` 没把事件喂进 `apply`/`refresh_view`（表单不会被播种，
+/// 下面的前置断言会红）。
+/// 抓不住：真 host 的落盘失败（那是 `host::launch_args` 的单测射程）。
+#[test]
+fn failed_save_keeps_the_draft_through_the_whole_loop() {
+    let (mut app, dispatched) = app_with_snapshot();
+
+    // 首屏快照到位 → 自动选中 → 表单按盘上的值播种。
+    let _ = app.update(Message::Boot);
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail(
+        "survival".to_string(),
+    ))));
+    app.advance(TICK);
+    assert_eq!(app.launch_form.memory, "4096", "首帧要按快照播种");
+    assert!(!app.launch_form.dirty);
+
+    // 用户把内存改成非法值（host 会拒），然后点保存。
+    let _ = app.update(Message::Page(pages::Message::Instances(
+        pages::InstanceMessage::Memory("4g".to_string()),
+    )));
+    assert_eq!(app.launch_form.memory, "4g");
+    let _ = app.update(Message::Page(pages::Message::Instances(
+        pages::InstanceMessage::Save,
+    )));
+    assert!(
+        dispatched
+            .borrow()
+            .iter()
+            .any(|command| matches!(command, AppCommand::SetInstanceLaunchArgs { .. })),
+        "保存要把命令派发出去"
+    );
+
+    // 失败回程：一条错误 Toast → pump → refresh_view → sync_launch_form（旧快照）。
+    app.advance(TICK);
+
+    assert_eq!(
+        app.launch_form.memory, "4g",
+        "保存失败后，pump 用旧快照把用户刚敲的内容冲掉了"
+    );
+    assert!(app.launch_form.dirty, "草稿还在，脏标记也不能掉");
+}

crates/app-iced/src/app/tests/presenter.rs

@@ -0,0 +1,246 @@
+//! presenter 闭环与节拍的断言（M90 r2 从 `app/tests.rs` 外置：那边 416 行会被 file-size 判红）。
+//!
+//! 这里的每条都依赖一个可注入的 `Backend`：
+//! - `MockBackend`（presenter 自带）验「命令 → 事件 → 状态」的闭环；
+//! - `RecorderBackend`（本文件，只记账不回事件）验「UI 侧不做乐观回显」——用 MockBackend 验这条
+//!   会得到**假绿**，因为它是同步发事件的，本地回显与事件回流终态相同（P3-2 的教训）。
+
+use std::cell::RefCell;
+use std::rc::Rc;
+
+use unlucky_i18n::Key;
+use unlucky_presenter::dto::{AppCommand, AppEvent, Backend, CoreEvent};
+use unlucky_presenter::mock_data::mock_instances;
+
+use super::*;
+
+// --------------------------------------------------------------- presenter 闭环
+
+/// **首屏快照在 Boot 就到位**（截图在第 3 帧落盘，等 30 fps 的 tick 会拍进空页面）。
+#[test]
+fn boot_drains_the_first_snapshot_before_the_first_frame() {
+    let mut app = headless(screenshot_options(), SchemeFlavor::Light);
+    assert!(app.view.instances.rows.is_empty(), "还没 Boot");
+
+    let _ = app.update(Message::Boot);
+
+    assert_eq!(
+        app.view.instances.rows.len(),
+        4,
+        "mock 的四个实例已进视图模型"
+    );
+    assert_eq!(app.view.screen, pages::Screen::Instances);
+}
+
+/// 首屏自动选中第一行（右栏不该开局空白），且**只做一次**：返回列表后再刷新不弹回详情。
+#[test]
+fn the_first_snapshot_selects_the_first_instance_once() {
+    let mut app = headless(screenshot_options(), SchemeFlavor::Light);
+    let _ = app.update(Message::Boot);
+    assert_eq!(
+        app.state.route(),
+        &Route::Detail("survival".to_string()),
+        "首屏快照到位后自动选中第一行"
+    );
+
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Instances)));
+    assert_eq!(app.state.route(), &Route::Instances);
+
+    // 再推进一拍（会 drain_events + auto_select）：不该把他弹回详情页
+    app.advance(super::super::state::TICK);
+    assert_eq!(app.state.route(), &Route::Instances, "自动选中只做一次");
+}
+
+/// 只记账、**不回任何事件**的后端（P3-2）。
+///
+/// 为什么需要它：`MockBackend::dispatch` 是**同步**发事件的，于是「UI 本地回显」与「事件回流」
+/// 在 dispatch 之后终态相同——拿 MockBackend 测「不乐观回显」是假绿（r1 就是栽在这条上）。
+/// 这个后端把两件事分开：命令只进 `dispatched`，`drain_events` 永远空 ⇒ 状态**不可能**变；
+/// 一旦有人在 `update` 里偷偷改本地状态，下面那条断言立刻红（实测见报告「P3-2 取证」）。
+#[derive(Debug, Default)]
+struct RecorderBackend {
+    dispatched: Rc<RefCell<Vec<AppCommand>>>,
+    seeded: Vec<AppEvent>,
+}
+
+impl Backend for RecorderBackend {
+    fn drain_events(&mut self) -> Vec<AppEvent> {
+        std::mem::take(&mut self.seeded)
+    }
+
+    fn dispatch(&mut self, command: AppCommand) {
+        self.dispatched.borrow_mut().push(command);
+    }
+}
+
+/// 用 recorder 后端造一个 App（首屏快照靠 `seeded` 一次性喂进去）。
+fn recording(options: Options, flavor: SchemeFlavor) -> (App, Rc<RefCell<Vec<AppCommand>>>) {
+    let recorded = Rc::new(RefCell::new(Vec::new()));
+    // 注意：`InstancesChanged` 是**整体替换**，所以四条必须合成一条事件；
+    // 分开发的话最后只会剩一个实例（r1 在这条上踩过）。
+    let backend = RecorderBackend {
+        dispatched: Rc::clone(&recorded),
+        seeded: vec![AppEvent::Core(
+            CoreEvent::InstancesChanged(mock_instances()),
+        )],
+    };
+    let app = App::with_presenter(
+        options,
+        FAMILIES,
+        flavor,
+        Box::new(backend),
+        SettingsBridge::memory_only(),
+    );
+    (app, recorded)
+}
+
+/// **P3-2：不做乐观回显**——命令必须真的出 UI 层，而状态在后端回事件之前**一个字节都不许变**。
+///
+/// 抓得住：`update` 里出现「本地先改状态」的写法（recorder 永远不回事件，本地一改这里就红）。
+/// 抓不住：「命令有没有真的到达 host」——那由 `MockBackend` 的闭环测试与真机验证负责。
+#[test]
+fn launching_only_dispatches_and_never_echoes_locally() {
+    let mut options = screenshot_options();
+    options.screenshot = None; // recorder 不依赖截图通道
+    let (mut app, recorded) = recording(options, SchemeFlavor::Light);
+
+    let _ = app.update(Message::Boot);
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail(
+        "survival".to_string(),
+    ))));
+
+    // Boot 自己发过一条 RefreshAll，先把账本清掉，下面只看「点 Play」这一个动作
+    recorded.borrow_mut().clear();
+
+    let before = app.view.instances.detail.clone().expect("有选中项");
+    assert!(before.can_launch && !before.can_stop && before.status.is_none());
+
+    let _ = app.update(Message::Page(pages::Message::Launch(
+        "survival".to_string(),
+    )));
+
+    // ① 命令真的出 UI 层了
+    assert_eq!(
+        *recorded.borrow(),
+        vec![AppCommand::LaunchInstance("survival".to_string())],
+        "Launch 必须翻成一条 AppCommand::LaunchInstance 并交给 Backend::dispatch"
+    );
+
+    // ② 后端一条事件都没回 ⇒ 视图模型必须**原样不动**（任何本地回显都会让这条红）
+    let after = app.view.instances.detail.clone().expect("有选中项");
+    assert_eq!(
+        after, before,
+        "没有事件回流时页面不许自己变（乐观回显）；现在的差异是 {after:?}"
+    );
+    assert!(!after.can_stop, "不许因为点了 Play 就本地切成「可停止」");
+    assert!(after.status.is_none(), "不许本地造一条进度文案");
+}
+
+/// **点 Play → 命令真的派发出去 → 事件回流 → 页面真的变**（真后端的闭环）。
+#[test]
+fn launching_goes_through_the_backend_and_comes_back_as_events() {
+    let mut app = headless(screenshot_options(), SchemeFlavor::Light);
+    let _ = app.update(Message::Boot);
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail(
+        "survival".to_string(),
+    ))));
+
+    let detail = app.view.instances.detail.as_ref().expect("有选中项");
+    assert!(
+        detail.can_launch && !detail.can_stop,
+        "空闲：可启动不可停止"
+    );
+
+    let _ = app.update(Message::Page(pages::Message::Launch(
+        "survival".to_string(),
+    )));
+
+    let detail = app.view.instances.detail.as_ref().expect("有选中项");
+    assert!(
+        !detail.can_launch && detail.can_stop,
+        "派发 LaunchInstance 后后端发回了 Busy 事件：按钮组合必须已经翻转"
+    );
+    // 阶段名跟界面语言走（M120）：断言对着**当前生效语言**的目录算，别在中文机器上钉死英文
+    let stage = app.lang().catalog().text(Key::InstancesStageDownload);
+    assert_eq!(
+        detail.status.as_deref(),
+        Some(format!("{stage} · 0%").as_str()),
+        "状态行来自事件里的进度，不是本地假造"
+    );
+}
+
+/// 时间推进真的把状态往前推（后端的脚本按 tick 的累计时长走）。
+#[test]
+fn ticks_advance_the_backend_script() {
+    let mut app = headless(screenshot_options(), SchemeFlavor::Light);
+    let _ = app.update(Message::Boot);
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail(
+        "survival".to_string(),
+    ))));
+    let _ = app.update(Message::Page(pages::Message::Launch(
+        "survival".to_string(),
+    )));
+
+    // 33 ms × 50 ≈ 1.65 s：mock 的脚本在 1.5 s 从 Download 切到 Verify
+    for _ in 0..50 {
+        app.advance(super::super::state::TICK);
+    }
+
+    let detail = app.view.instances.detail.as_ref().expect("有选中项");
+    let status = detail.status.as_deref().unwrap_or_default();
+    let catalog = app.lang().catalog();
+    let (verify, launch) = (
+        catalog.text(Key::InstancesStageVerify),
+        catalog.text(Key::InstancesStageLaunch),
+    );
+    assert!(
+        status.starts_with(verify) || status.starts_with(launch),
+        "50 拍之后应已过下载阶段，实际 {status:?}"
+    );
+}
+
+/// 停止也是真命令：`StopInstance` 让 mock 直接回一条 Idle 事件。
+#[test]
+fn stopping_returns_to_idle_through_an_event() {
+    let mut app = headless(screenshot_options(), SchemeFlavor::Light);
+    let _ = app.update(Message::Boot);
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail(
+        "survival".to_string(),
+    ))));
+    let _ = app.update(Message::Page(pages::Message::Launch(
+        "survival".to_string(),
+    )));
+    let _ = app.update(Message::Page(pages::Message::Stop("survival".to_string())));
+
+    let detail = app.view.instances.detail.as_ref().expect("有选中项");
+    assert!(detail.can_launch && !detail.can_stop, "停下来回到空闲");
+    assert!(detail.status.is_none(), "空闲没有状态行");
+}
+
+/// 导航：一级页替换、详情压栈、返回出栈——页面换的是 `Route`，不是页面自己的选中项。
+#[test]
+fn navigation_follows_the_presenter_router() {
+    let mut app = headless(screenshot_options(), SchemeFlavor::Light);
+    let _ = app.update(Message::Boot);
+
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail(
+        "survival".to_string(),
+    ))));
+    assert_eq!(app.view.screen, pages::Screen::Instances, "详情仍是实例页");
+    assert!(app.state.router.can_go_back());
+
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Settings)));
+    assert_eq!(app.view.screen, pages::Screen::Settings);
+    assert_eq!(
+        app.view.active,
+        Some(pages::Screen::Settings.nav()),
+        "导航轨高亮跟着路由走"
+    );
+    assert!(
+        !app.state.router.can_go_back(),
+        "一级页互相替换，不进栈（presenter::router 的语义）"
+    );
+
+    let _ = app.update(Message::Page(pages::Message::Navigate(Route::Instances)));
+    assert_eq!(app.view.screen, pages::Screen::Instances);
+}

crates/app-iced/src/app/tests/theme.rs

@@ -0,0 +1,187 @@
+//! 主题三档（Ink / Silver / 跟随系统）的落点测试（M229；从 `app/tests.rs` 拆出守 400 行）。
+//!
+//! 这一份只管**用户点设置页那三枚 chip 之后**发生的事：换色板、同步设置组状态、落盘。
+//! `Auto`（跟随系统）那条路在 `app::tests::the_system_theme_never_overrides_an_explicit_one`。
+
+use crate::app::message::Message;
+use crate::app::state::App;
+use crate::cli::Options;
+use crate::pages;
+use crate::theme::Families;
+use unlucky_design::color::SchemeFlavor;
+use unlucky_presenter::mock::MockBackend;
+use unlucky_presenter::prefs::ThemeMode;
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+/// 一个把配置写在临时文件里的 App：测「落盘」必须真的过文件（内存桥读回来永远是出厂值）。
+fn with_config() -> (App, std::path::PathBuf) {
+    let dir = std::env::temp_dir().join(format!("ull-theme-m229-{}", std::process::id()));
+    std::fs::create_dir_all(dir.join("config")).expect("临时目录");
+    let path = dir.join("config/launcher.json");
+    std::fs::write(&path, "{}").expect("写配置文件");
+
+    let app = App::with_presenter(
+        Options::default(),
+        FAMILIES,
+        SchemeFlavor::Light,
+        Box::new(MockBackend::new()),
+        SettingsBridge::with_path(&path),
+    );
+    (app, dir)
+}
+
+/// M229：设置页「通用 → 主题」三档（Ink / Silver / 跟随系统）真的换色板、真的落盘。
+///
+/// 抓得住：①`pages::Message::Theme` 没接进 `on_page`（点了没反应）②接了但不换 `Ui`
+/// （只有选中态变了，界面颜色还是旧的）③同步设置组状态漏了（设置页首帧/刷新后画错档）
+/// ④落盘漏了（重启回旧值——这里**真的过文件**：`with_config` 用 `SettingsBridge::with_path` 写临时
+/// 配置，再用同一路径重新 `load()` 读回；内存桥读回来永远是出厂值，验不了落盘）。
+/// 抓不住：色板好不好看、像素级差异（那要截图，见 `DevDocs/artifacts/m229/`）。
+#[test]
+fn the_theme_message_switches_the_board_and_persists_it() {
+    let (mut app, dir) = with_config();
+    assert_eq!(app.board_name(), "silver", "首帧是浅色主方案（Silver）");
+
+    // 选 Ink（= 深色主方案）
+    let _ = app.update(Message::Page(pages::Message::Theme(ThemeMode::Dark)));
+    assert_eq!(app.theme_mode(), ThemeMode::Dark);
+    assert_eq!(app.board_name(), "ink", "Ink 深板要真切过去");
+    assert_eq!(app.ui().flavor(), SchemeFlavor::Dark);
+    assert_eq!(
+        app.settings.language_appearance.theme,
+        ThemeMode::Dark,
+        "设置页那一行的档位要跟着改"
+    );
+    // 落盘：真的过了文件（重新打开同一个配置读回来就是 dark）
+    assert_eq!(
+        SettingsBridge::with_path(dir.join("config/launcher.json"))
+            .load()
+            .1,
+        ThemeMode::Dark,
+        "主题档要落盘"
+    );
+
+    // 选 Silver（= 浅色主方案）
+    let _ = app.update(Message::Page(pages::Message::Theme(ThemeMode::Light)));
+    assert_eq!(app.board_name(), "silver");
+    assert_eq!(app.ui().flavor(), SchemeFlavor::Light);
+    assert_eq!(
+        SettingsBridge::with_path(dir.join("config/launcher.json"))
+            .load()
+            .1,
+        ThemeMode::Light
+    );
+
+    // 同一档再点一次：不许白重建
+    let refreshes = app.refreshes;
+    let _ = app.update(Message::Page(pages::Message::Theme(ThemeMode::Light)));
+    assert_eq!(app.refreshes, refreshes, "同一档不该再重建视图模型");
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// **截图通道把主题档钉死在 `--screenshot-theme`**，不读机器上的 `launcher.json`（D30 可复现）。
+///
+/// 复审 r2 P2-a 指出：`construct.rs` 里新加的这条分支没有回归测试——于是「哪天有人把它改回
+/// `bridge.load().1`」不会有人发现，两次不同配置的机器又会出不同颜色的图。
+///
+/// 判据：**同一份截图参数 + 两份不同的机器配置 ⇒ 同一个档位**，且等于参数（浅→`Light`、深→`Dark`）；
+/// 反证：非截图通道下同样两份配置**确实**分出两个档（否则这条测试等于没测到分支）。
+#[test]
+fn the_screenshot_channel_pins_the_theme_mode_instead_of_reading_the_file() {
+    use std::path::{Path, PathBuf};
+
+    /// 写一份只含 `appearance.theme_mode` 的临时配置，并用它构造 App。
+    fn with_mode(
+        dir_name: &str,
+        json: &str,
+        options: Options,
+        flavor: SchemeFlavor,
+    ) -> (App, PathBuf) {
+        let dir =
+            std::env::temp_dir().join(format!("ull-shot-theme-{dir_name}-{}", std::process::id()));
+        std::fs::create_dir_all(dir.join("config")).expect("临时目录");
+        let path = dir.join("config/launcher.json");
+        std::fs::write(&path, json).expect("写配置文件");
+        let app = App::with_presenter(
+            options,
+            FAMILIES,
+            flavor,
+            Box::new(MockBackend::new()),
+            SettingsBridge::with_path(&path),
+        );
+        (app, dir)
+    }
+
+    fn cleanup(dir: &Path) {
+        std::fs::remove_dir_all(dir).ok();
+    }
+
+    let dark_file = r#"{"appearance":{"theme_mode":"dark"}}"#;
+    let light_file = r#"{"appearance":{"theme_mode":"light"}}"#;
+
+    // ① 截图参数给浅色：机器配置是 dark 也一样出 Light（钉死值赢）
+    let shot_light = Options {
+        screenshot: Some(PathBuf::from("unused.png")),
+        screenshot_theme: Some(SchemeFlavor::Light),
+        ..Options::default()
+    };
+    let (from_dark_file, d1) = with_mode(
+        "light-a",
+        dark_file,
+        shot_light.clone(),
+        SchemeFlavor::Light,
+    );
+    let (from_light_file, d2) = with_mode("light-b", light_file, shot_light, SchemeFlavor::Light);
+    assert_eq!(
+        from_dark_file.theme_mode(),
+        ThemeMode::Light,
+        "截图模式下档位必须由 --screenshot-theme 决定，不许读文件里的 dark"
+    );
+    assert_eq!(
+        from_dark_file.theme_mode(),
+        from_light_file.theme_mode(),
+        "两份机器配置必须出同一个档位"
+    );
+    assert_eq!(from_dark_file.board_name(), "silver");
+    assert_eq!(from_light_file.board_name(), "silver");
+
+    // ② 反方向：截图参数给深色 ⇒ 即使文件写 light 也是 Dark/Ink
+    let shot_dark = Options {
+        screenshot: Some(PathBuf::from("unused.png")),
+        screenshot_theme: Some(SchemeFlavor::Dark),
+        ..Options::default()
+    };
+    let (from_light_file_dark, d3) = with_mode("dark-a", light_file, shot_dark, SchemeFlavor::Dark);
+    assert_eq!(from_light_file_dark.theme_mode(), ThemeMode::Dark);
+    assert_eq!(from_light_file_dark.board_name(), "ink");
+
+    // ③ 反证：非截图通道下，同样的两份配置**确实**分出两个档（证明这条分支真的存在）
+    let (interactive_dark, d4) =
+        with_mode("plain-a", dark_file, Options::default(), SchemeFlavor::Dark);
+    let (interactive_light, d5) = with_mode(
+        "plain-b",
+        light_file,
+        Options::default(),
+        SchemeFlavor::Light,
+    );
+    assert_eq!(
+        interactive_dark.theme_mode(),
+        ThemeMode::Dark,
+        "产品路径要读文件"
+    );
+    assert_eq!(
+        interactive_light.theme_mode(),
+        ThemeMode::Light,
+        "产品路径要读文件"
+    );
+
+    for dir in [d1, d2, d3, d4, d5] {
+        cleanup(&dir);
+    }
+}

crates/app-iced/src/app/update.rs

@@ -0,0 +1,382 @@
+//! `update`：消息分支的**唯一**落点（含「用户动作 → 后端指令」的派发与事件回流）。
+//!
+//! ## 数据流的三个入口（presenter crate 文档 §2）
+//!
+//! ```text
+//! 用户动作 ──dispatch(AppCommand)──► backend ──► drain_events() ──► AppState::apply ──► 视图模型
+//!      ▲                                                    ▲
+//!      └── pages::Message（导航/启动/停止）──────────────────┘  忙碌 33 ms / 空闲 1 Hz
+//! ```
+//!
+//! 三条纪律：
+//!
+//! 1. **不做乐观回显**：点了「Play」不改本地状态，等 `InstanceRuntimeChanged` 事件回来才变
+//!    （否则事件与本地状态打架时，磁贴与进度条会各说一套）；
+//! 2. **状态只有一个写入口**：`AppState::apply`（事件）与 `AppState::navigate`（路由）；
+//! 3. **只在状态变了才重建视图模型**：`refresh_view()` 是快照 → 页面的唯一转换点，
+//!    由 `view_dirty` 门控（M90 r2/P2-1 起；此前是每拍无条件重建）。
+//!
+//! ## 两个时钟（M90 r3 / P2-2）
+//!
+//! | 场景 | 时钟 | 周期 | 谁触发 |
+//! |---|---|---|---|
+//! | 截图 / **有动画在跑（M192）** / 有 Busy-Running 实例 / 有 toast / 派发后 3 s 观察窗 | `window::frames()` + 闸门 | 33 ms | [`App::needs_frames`] |
+//! | 其余（空闲） | `Heartbeat` 自续链 | 1 s | [`App::heartbeat`] |
+//!
+//! 两条时钟不会同时干活：心跳在 `needs_frames()` 为真时**只续排、不推进**，忙碌结束自动接回。
+//! 动效那条**不新开循环**：它只是给同一个布尔加一个分支（有轨道才为真），轨道到期当场清空，
+//! 下一拍就退回心跳（见 `components::motion`）。
+
+use crate::app::components::motion;
+use crate::app::diag::diag;
+use std::time::Instant;
+
+use iced::{window, Task};
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_presenter::dto::AppCommand;
+use unlucky_presenter::prefs::ThemeMode;
+use unlucky_presenter::router::Route;
+
+use crate::pages;
+use crate::renderer::Kind;
+
+use super::message::{route_of, Message};
+use super::state::{App, IDLE_TICK, TICK, WATCH_WINDOW};
+use super::CAPTURE_AT_FRAME;
+
+mod account;
+// M223：导入已有版本向导（扫描 / 预检 / 确认 / 关闭 / 退回）
+mod adopt;
+mod agent;
+mod appearance;
+pub(super) mod boot_env;
+mod clock;
+mod content;
+mod content_pack;
+mod dialog;
+mod dialog_fixture;
+mod download;
+mod instances;
+mod motion_sync;
+mod page_messages;
+mod settings;
+mod update_action;
+
+/// 这一条键盘事件是不是 `Esc` 按下。
+fn is_escape(event: &iced::keyboard::Event) -> bool {
+    matches!(
+        event,
+        iced::keyboard::Event::KeyPressed {
+            key: iced::keyboard::Key::Named(iced::keyboard::key::Named::Escape),
+            ..
+        }
+    )
+}
+
+impl App {
+    /// 一条消息进来，改状态并返回后续任务。
+    ///
+    /// **分两段**：先派发（[`App::route_message`]），再同步一次动效的内容标识。第二段必须在
+    /// `update` 里而不是 `view` 里：iced 求值订阅表**早于**建视图（`app/update/motion.rs` 的模块
+    /// 文档有源码行号），在 `view` 里起跑的轨道当拍订阅不上，动画会退化成「一帧偏移 + 闪跳」。
+    pub(super) fn update(&mut self, message: Message) -> Task<Message> {
+        let task = self.route_message(message);
+        self.sync_motion();
+        task
+    }
+
+    /// 把一条消息派发到它的落点（`update` 的正文；拆出来只为让 [`App::sync_motion`] 收尾）。
+    fn route_message(&mut self, message: Message) -> Task<Message> {
+        match message {
+            Message::Boot => self.on_boot(),
+            Message::WindowReady(id) => {
+                self.window = id;
+                // M93：整窗 α 要 Win32 句柄，而 iced 只给 `window::Id`。`window::run` 是唯一能把
+                // `&dyn Window`（实现了 `HasWindowHandle`）拿出来的入口。
+                match id {
+                    Some(id) => {
+                        window::run(id, super::window_alpha::probe_hwnd).map(Message::WindowHandle)
+                    }
+                    None => Task::none(),
+                }
+            }
+            Message::WindowHandle(hwnd) => {
+                self.hwnd = hwnd;
+                match hwnd {
+                    Some(_) => self.apply_window_alpha("boot"),
+                    None => {
+                        diag!("[appearance] hwnd=none（拿不到窗口句柄：整窗 α 无法下发）");
+                        self.log_appearance("boot", None);
+                    }
+                }
+                // M116：圆角放在 α **之后**——α < 1 时那一步才补上 `WS_EX_LAYERED`，
+                // 先打圆角日志会把 `layered=` 记成 `off`（那正是我们要分辨的那一位）。
+                self.apply_window_corner("boot");
+                Task::none()
+            }
+            Message::SystemTheme(mode) => {
+                let flavor = match mode {
+                    iced::theme::Mode::Dark => SchemeFlavor::Dark,
+                    iced::theme::Mode::None | iced::theme::Mode::Light => SchemeFlavor::Light,
+                };
+                diag!("[theme] 系统主题 = {mode:?}");
+                // 优先级：`--theme` > 配置文件里的 `appearance.theme_mode` > 系统。
+                // 早先这里无条件盖掉，于是「配置文件写 dark、系统是浅色」会出现
+                // `light -> dark -> light` 的一次抖动，配置永远不生效（M90 r3 顺手修）。
+                if self.options.theme.is_none() && self.theme_mode == ThemeMode::Auto {
+                    self.set_flavor(flavor);
+                }
+                Task::none()
+            }
+            Message::Frame => self.on_frame(),
+            Message::Heartbeat => self.on_heartbeat(),
+            Message::Window(event) => {
+                match event {
+                    window::Event::Resized(size) => {
+                        self.width = size.width;
+                        // 高度是背景平铺网格的视口判据之一（宽度早就有），以前只记宽是因为没有背景层。
+                        self.height = size.height;
+                        self.view_dirty = true;
+                        self.refresh_view();
+                    }
+                    // M113: import/export —— 拖入整合包（本版唯一的选文件通道；窗口级事件，
+                    // 所以入口收起时也照样接得住。细节在 `on_pack_dropped` / `on_pack_hover`）
+                    window::Event::FileDropped(path) => return self.on_pack_dropped(path),
+                    window::Event::FileHovered(_) => return self.on_pack_hover(true),
+                    window::Event::FilesHoveredLeft => return self.on_pack_hover(false),
+                    _ => {}
+                }
+                Task::none()
+            }
+            Message::Page(message) => self.on_page(message),
+            Message::Dialog(message) => dialog::on_dialog(self, message),
+            // M223：导入已有版本向导（打开 / 选版本 / 选目标 / 预检 / 确认 / 退回 / 关闭）
+            Message::Adopt(message) => self.on_adopt(message),
+            Message::Agent(message) => {
+                // `Esc` 先给弹窗：有弹窗时它属于「关掉这一层」，不属于 AI 栏的收起。
+                if let crate::shell::agent::Message::Key(event) = &message {
+                    if is_escape(event) && dialog::escape(self) {
+                        return Task::none();
+                    }
+                }
+                self.on_agent(message)
+            }
+            // 外壳导航轨（`src/shell/nav.rs`）发来的点选：翻成同一次路由跳转
+            Message::Select(nav) => {
+                self.state.navigate(route_of(nav));
+                self.view_dirty = true;
+                self.refresh_view();
+                Task::none()
+            }
+            Message::DragWindow => match self.window {
+                Some(id) => window::drag(id),
+                None => Task::none(),
+            },
+            Message::ResizeStart(direction) => match self.window {
+                Some(id) => window::drag_resize(id, direction),
+                None => Task::none(),
+            },
+            Message::Minimize => match self.window {
+                Some(id) => window::minimize(id, true),
+                None => Task::none(),
+            },
+            Message::ToggleMaximize => match self.window {
+                Some(id) => window::toggle_maximize(id),
+                None => Task::none(),
+            },
+            Message::Close => iced::exit(),
+            Message::Captured(screenshot) => self.on_captured(&screenshot),
+            Message::Demo(message) => {
+                // gallery 只是 harness：按下只打日志，不接业务（组件库要能脱离业务验收）
+                diag!("[gallery] {} pressed", message.id());
+                Task::none()
+            }
+        }
+    }
+
+    /// 启动：问窗口句柄 → 让后端发布首屏快照 → 决定主题。
+    ///
+    /// **首屏快照在 `Boot` 就抽干**（不是等第一拍）：截图通道在第 3 帧落盘，33 ms 的节拍
+    /// 未必来得及到达，等节拍会把空页面拍进图里。
+    fn on_boot(&mut self) -> Task<Message> {
+        let mut tasks = vec![window::latest().map(Message::WindowReady)];
+
+        // M192：给动效帧泵定档（截图档关、CPU 档半速、GPU 档正常；`ULL_MOTION*` 可覆盖）。
+        // 必须在第一次 `view()` 之前：页面主体的入场由 `pages::render` 采样，配置晚了首屏就没有动效。
+        self.configure_motion();
+
+        // M117：启动日志一行 —— `[auth] msa client_id=configured|missing source=env|build|none`。
+        // 判据（配没配 + 从哪来）在 `core::auth::microsoft::client_id_status()`，零网络；
+        // 本 crate 不直接依赖 core，所以经 `unlucky_cli`（已是本 crate 的依赖）出面，
+        // 免得 UI 侧把判据重算一遍、两份口径漂。日后看日志能一眼分辨
+        // 「没配置」与「配了但登录失败」。
+        diag!("{}", unlucky_cli::commands::msa_client_id_log_line());
+
+        // 主题优先级：显式 `--theme` / `--screenshot-theme` > 设置文件 > 系统。
+        // 截图通道**不读设置文件**（D30 可复现：同一份代码在两台机器上要出同一张图）。
+        self.apply_config_theme();
+
+        // M93 外观取证开关（`ULL_APPEARANCE_*`）+ 启动那一行数值日志。
+        // 必须在 `refresh_view` 之前：设置页要画的就是这份状态。
+        self.appearance.apply_env();
+        self.rebuild_ui();
+        self.log_appearance("boot", None);
+        // M187（r1 复审 P2-4）：启动这一拍的事实进启动器日志的缓冲（第一次启动时落盘）。
+        boot_env::record_boot_log(self);
+
+        // 交互模式且没显式指定主题 → 探系统；截图模式永不等（见 cli 模块文档）
+        if self.options.wants_system_theme() {
+            tasks.push(iced::system::theme().map(Message::SystemTheme));
+        }
+
+        // M104：助手栏的启动尾巴（窗口尺寸 adopt + 「拆出档直接落到独立页」）在 update/agent.rs。
+        // **必须在 RefreshAll 之前**：那次 dispatch 会 `pump → auto_select`，把路由拉到实例详情，
+        // 而 `sync_agent_route` 看到「不在 Agent 页却还是 Detached」就会把档位收回来——顺序反了
+        // 就会出现「`ULL_AGENT_RAIL=detached` 启动后停在实例页」（r2 实测踩到）。
+        self.boot_agent();
+
+        // 「重新扫描实例目录 + 全部页面快照」：真 host 在这里发首批事件，mock 在构造时已预置
+        self.dispatch(AppCommand::RefreshAll);
+
+        // 取证开关 `ULL_START_ROUTE`：截图/冒烟直接落到某一页（`cli.rs` 不在本 mission 的 scope，
+        // 而「外观」分组只在设置页上，出矩阵必须能直达）。未知值忽略。
+        if let Some(route) = boot_env::env_start_route() {
+            diag!("[boot] ULL_START_ROUTE → {route:?}");
+            self.state.navigate(route);
+            // 直达某一页时不要再被「自动选中第一条实例」拉回详情页。
+            self.auto_selected = true;
+            // M109：直达内容库时补一次检索（与页面内切换同一个入口）
+            self.ensure_content_loaded();
+        }
+        account::force_account_state(self);
+        // M187：启动失败弹窗的取证夹具（`ULL_DIALOG_FIXTURE`），必须在 `refresh_view` 之前。
+        if let Some(mode) = dialog_fixture::apply(self) {
+            diag!("[boot] ULL_DIALOG_FIXTURE → {mode}");
+        }
+
+        self.auto_select();
+        self.view_dirty = true;
+        self.refresh_view();
+
+        // 空闲心跳从这里开始自续（它是唯一能在「没有帧事件」时戳醒 app 的时钟）
+        tasks.push(heartbeat());
+
+        Task::batch(tasks)
+    }
+
+    /// M192：给帧泵定档（策略全在 [`boot_env::motion_scale`]，这里只搬输入）。
+    fn configure_motion(&mut self) {
+        let pin = boot_env::env_motion_pin();
+        let gpu = matches!(
+            super::backend::effective_kind(),
+            Some(crate::renderer::Kind::Wgpu)
+        );
+        let scale = boot_env::motion_scale(self.options.screenshot.is_some(), gpu, pin.is_some());
+        motion::configure(scale, pin);
+        // 打**帧泵实际拿到的**档位（不是刚算出的那个）：配置没生效时这一行会露馅。
+        diag!(
+            "[motion] scale={:.2} pin={:?} gpu={} screenshot={}",
+            motion::scale().factor(),
+            pin,
+            gpu,
+            self.options.screenshot.is_some()
+        );
+    }
+
+    /// 空闲心跳：只有「不需要帧节拍」时才推进一拍，然后**无条件续排**下一拍。
+    ///
+    /// 为什么无条件续排：忙碌结束（游戏退出、toast 过期、观察窗关闭）之后没有别的东西会叫醒
+    /// app，心跳链必须一直在，才能把低频时钟接回去。忙碌期间它只是每秒醒一次、什么都不做。
+    fn on_heartbeat(&mut self) -> Task<Message> {
+        // 动效时间轴也吃这一拍：窗口被遮挡 / 最小化 / 合成器不送绘制时，帧一个都不来，而
+        // 「有轨道」又让下面的 1 Hz 推进整段停摆——那会让 `needs_frames()` 永远为真。心跳把
+        // 轨道按单次上限（[`components::motion::pump::MAX_STEP_MS`]）推几步收尾，最坏的「没有帧」
+        // 情况下 5 拍内自然退订；有帧时它只多推 64 ms/秒，看不出来。
+        motion::advance();
+        if !self.needs_frames() {
+            let now = Instant::now();
+            let elapsed = now.saturating_duration_since(self.last_tick).max(IDLE_TICK);
+            self.last_tick = now;
+            self.advance(elapsed);
+        }
+        // M192 真机取证（`ULL_MOTION_FIXTURE_AT`）：到点就**真的**导航一次。放在 advance 之后 ⇒
+        // 这一拍是货真价实的空闲态；跳转后由 `update` 收尾的 `sync_motion` 起跑（与点击同一条路）。
+        self.motion_fixture_after_idle();
+        heartbeat()
+    }
+
+    /// 一帧画完：①动效时间轴推进 ②够 33 ms 就推进一拍 presenter ③截图模式在第
+    /// [`CAPTURE_AT_FRAME`] 帧出图。
+    ///
+    /// 时间闸门按**真实流逝时间**判（不是数帧）：掉帧不会把游戏启动进度拖慢，
+    /// 也不会在慢机器上把 1.5 s 的下载阶段拉成 4 s。
+    fn on_frame(&mut self) -> Task<Message> {
+        self.frames += 1;
+
+        // M192：动效时间轴。**每帧都调**，帧率上限在帧泵内部（16 ms 一次结算），所以忙碌态的
+        // 近千 fps 不会变成近千次重排；动画结束后帧泵自动清空，下一拍订阅表就不再有 `frames()`。
+        motion::advance();
+        // 出图取证（`ULL_MOTION_FIXTURE`）：前两帧各做一次**真的**状态变化。
+        // 没有这步，截图通道每一帧画的都是同一屏，页面切换 / 列表↔详情的入场就没有可拍的相位。
+        // `ULL_MOTION_FIXTURE_AT`（真机空闲取证）在的时候**不跑**这一支：两条取证路互斥，
+        // 否则第 1 帧就把页面换成目标页，等 `_AT` 的心跳再跳同一个目标 = 标识没变 = 没有动效。
+        if self.frames <= 2 && boot_env::env_motion_fixture_at().is_none() {
+            self.motion_fixture();
+        }
+
+        let now = Instant::now();
+        let elapsed = now.saturating_duration_since(self.last_tick);
+        if elapsed >= TICK {
+            self.last_tick = now;
+            self.advance(elapsed);
+        }
+
+        // 主题在启动时就已确定（截图模式必有主题，见 cli 模块文档），这里只剩帧数闸门
+        if !self.wants_frames() || self.frames < CAPTURE_AT_FRAME {
+            return Task::none();
+        }
+
+        match self.window {
+            Some(id) => window::screenshot(id).map(Message::Captured),
+            None => Task::none(),
+        }
+    }
+
+    /// 截图回来了：落盘 + 打一行取证日志，然后退出。
+    fn on_captured(&mut self, screenshot: &window::Screenshot) -> Task<Message> {
+        let Some(path) = self.options.screenshot.clone() else {
+            return Task::none();
+        };
+        match crate::shot::save(screenshot, &path) {
+            Ok(summary) => {
+                diag!("{}", summary.describe());
+                // M97：打**实际**后端名（`wgpu`/`tiny-skia`），不是请求值——`renderer=auto` 曾经出现在每张验收图的日志里。
+                diag!(
+                    "[shot] screen={} theme={} renderer={} route={:?}",
+                    self.options.screen.name(),
+                    crate::shot::flavor_slug(&self.ui),
+                    super::backend::effective_kind().map_or("?", Kind::name),
+                    self.state.route()
+                );
+            }
+            Err(error) => diag!("[shot] 失败：{error}"),
+        }
+
+        iced::exit()
+    }
+}
+
+/// 空闲心跳的一拍：睡 1 秒再发 [`Message::Heartbeat`]。
+///
+/// 用 `Task::perform` + `std::thread::sleep` 而不是 `iced::time::every`：后者只在 tokio/smol
+/// 后端提供（本 crate 的执行器是 thread-pool，Cargo.toml 不在 scope）。代价是每拍让线程池里
+/// 一个线程阻塞 1 秒——按 1 Hz 算，对线程池（默认 = CPU 数）是可接受的占用。
+fn heartbeat() -> Task<Message> {
+    Task::perform(async { std::thread::sleep(IDLE_TICK) }, |()| {
+        Message::Heartbeat
+    })
+}
+
+#[cfg(test)]
+mod download_wiring;

crates/app-iced/src/app/update/account.rs

@@ -0,0 +1,233 @@
+//! 账户页消息的落点（M114）：页面只发意图，这里翻成 `AppCommand` 或本地的表单状态写入。
+//!
+//! 三条纪律（与 `update.rs` 同源）：
+//!
+//! 1. **不做乐观回显**：切账户/删账户/登录都只派命令，等 `AccountsChanged` /
+//!    `DeviceLoginChanged` / `AuthlibLoginChanged` 回来才改列表；
+//! 2. **密码只走一次**：`Submit` 把 `AuthlibRequest` 交给后端后立刻清掉表单里的密码
+//!    （成功失败都清——重试用新输入，不在内存里多留一份凭据）；
+//! 3. **表单态是纯 UI 状态**：输入框改动只写 `App::account_form` + 置脏，不派命令。
+//!
+//! ## 返回 `Task`（M114 r2 / 复审 P2-1）
+//!
+//! 复制用户码/链接必须把 `iced::clipboard::write` 的 `Task` **交回 runtime**——iced 0.14 的
+//! `Task` 是惰性 stream，丢掉返回值等于永不执行（日志页的 Copy summary 就是正确写法）。
+
+use iced::Task;
+use unlucky_presenter::dto::{AccountKind, AppCommand, AuthlibRequest, DeviceLoginPhase};
+
+use crate::app::Message;
+use crate::pages::account::{Hint, Message as Account, Panel, Track};
+
+use super::super::state::App;
+
+impl App {
+    /// 账户页消息。
+    pub(super) fn on_account(&mut self, message: Account) -> Task<Message> {
+        // 复制是唯一需要**交回 Task** 的分支：先把它的 Task 抓出来，其余分支照旧改状态
+        let clipboard = match &message {
+            Account::Copy(text) => Some(text.clone()),
+            _ => None,
+        };
+
+        match message {
+            Account::Open(track) => {
+                self.account_form.open(track);
+                self.account_form.hint = None;
+                self.view_dirty = true;
+            }
+            Account::ToggleAdd => {
+                self.account_form.section_open = !self.account_form.section_open;
+                self.account_form.hint = None;
+                self.view_dirty = true;
+            }
+            Account::Close => {
+                self.account_form.close();
+                // 关面板必须把**两条轨**的登录态都收回 Idle（复审 r2 P2-1：只看 `busy()` 时，
+                // `Failed`/`Succeeded` 不在 busy ⇒ 状态仍是非 Idle ⇒ `Page::build` 又把面板
+                // 强制回 Microsoft，按钮成了死按钮）。`CancelDeviceLogin` 在 host 侧本来就
+                // 同时收两条轨并发 Idle，所以判据用「非 Idle」而不是「busy」。
+                if self.state.device_login.phase != DeviceLoginPhase::Idle
+                    || self.state.authlib_login.phase != DeviceLoginPhase::Idle
+                {
+                    self.dispatch(AppCommand::CancelDeviceLogin);
+                }
+                self.view_dirty = true;
+            }
+            Account::DismissNotice => self.dispatch(AppCommand::DismissAccountNotice),
+            Account::Server(value) => {
+                self.account_form.server = value;
+                self.view_dirty = true;
+            }
+            Account::Login(value) => {
+                self.account_form.login = value;
+                self.view_dirty = true;
+            }
+            Account::Password(value) => {
+                self.account_form.password = value;
+                self.view_dirty = true;
+            }
+            Account::OfflineName(value) => {
+                self.account_form.offline_name = value;
+                self.view_dirty = true;
+            }
+            Account::Probe => {
+                let server = self.account_form.server.clone();
+                if !server.trim().is_empty() {
+                    self.dispatch(AppCommand::ProbeAuthlibServer(server));
+                }
+            }
+            Account::Submit => match self.account_form.panel {
+                Panel::Offline => {
+                    // 名字**不清空**：失败时用户还要看见自己输入的（复审 r1 P2-2 的另一半）
+                    let name = self.account_form.offline_name.trim().to_string();
+                    if !name.is_empty() {
+                        self.dispatch(AppCommand::AddOfflineAccount(name));
+                    }
+                }
+                Panel::Authlib => {
+                    if self.account_form.authlib_ready() {
+                        let request = AuthlibRequest::new(
+                            self.account_form.server.clone(),
+                            self.account_form.login.clone(),
+                            std::mem::take(&mut self.account_form.password),
+                        );
+                        self.dispatch(AppCommand::AddAuthlibAccount(request));
+                    }
+                }
+                Panel::Microsoft => return self.on_account(Account::StartDevice),
+                Panel::None => {}
+            },
+            Account::StartDevice => self.dispatch(AppCommand::StartDeviceLogin),
+            Account::StartBrowser => self.dispatch(AppCommand::StartBrowserLogin),
+            Account::Cancel => {
+                self.account_form.close();
+                self.dispatch(AppCommand::CancelDeviceLogin);
+            }
+            Account::Copy(_) => {}
+            Account::Switch(id) => self.dispatch(AppCommand::SwitchAccount(id)),
+            Account::Remove(id) => self.dispatch(AppCommand::RemoveAccount(id)),
+            Account::Relogin(id) => return self.relogin(&id),
+        }
+        self.refresh_view();
+
+        match clipboard {
+            Some(text) => iced::clipboard::write(text),
+            None => Task::none(),
+        }
+    }
+
+    /// 「重新登录」按**账户类型**分派（复审 r1 P2-3）。
+    ///
+    /// - 微软轨：走授权码流（原路）；
+    /// - 第三方轨：第三方站没有「一键重登」——预填服务器地址与登录名，让用户补密码；
+    /// - 本地档案：没有服务器账户可重登 ⇒ 明确说明，不假装能做。
+    fn relogin(&mut self, id: &str) -> Task<Message> {
+        let Some(account) = self
+            .state
+            .accounts
+            .iter()
+            .find(|account| account.id == id)
+            .cloned()
+        else {
+            return Task::none();
+        };
+        self.account_form.hint = None;
+        match account.kind {
+            AccountKind::Microsoft => {
+                self.account_form.panel = Panel::Microsoft;
+                // M178：重登也走设备码（不依赖任何应用注册项）。想试浏览器再点面板里的次按钮。
+                self.dispatch(AppCommand::StartDeviceLogin);
+            }
+            AccountKind::Authlib => {
+                self.account_form.open(Track::Authlib);
+                self.account_form.server = account.server_url.clone();
+                self.account_form.login = account.login_name.clone();
+                self.account_form.password.clear();
+                self.account_form.hint = Some(Hint::AuthlibReauth);
+                self.view_dirty = true;
+                self.refresh_view();
+            }
+            AccountKind::Offline => {
+                self.account_form.hint = Some(Hint::OfflineNoRelogin);
+                self.view_dirty = true;
+                self.refresh_view();
+            }
+        }
+        Task::none()
+    }
+}
+
+/// 取证开关 `ULL_ACCOUNT_STATE` 的落地（**只在 `--screenshot` 下生效**）。
+///
+/// 为什么需要：设备码过期要等 15 分钟、表单要手点两下，截图通道等不到自然发生的状态。
+pub(super) fn force_account_state(app: &mut App) {
+    if !app.has_screenshot() {
+        return;
+    }
+    let Ok(state) = std::env::var("ULL_ACCOUNT_STATE") else {
+        return;
+    };
+    match state.trim().to_lowercase().as_str() {
+        // 设备码已过期：起点往前挪一小时（倒计时自己算出来就是 0）
+        "expired" => {
+            app.state.device_login_started =
+                Some(std::time::Instant::now() - std::time::Duration::from_secs(3_600));
+        }
+        // M178：浏览器登录没走成、已回退设备码的那一态（设备码 + 一句「为什么 + 怎么修」）。
+        //
+        // 为什么在 app 层造：真走到这一步要一次真网络请求（预检），截图通道要的是**确定性**。
+        // 这里只替换登录视图本身——面板的渲染路径与真 host 完全同一条
+        // （`apply_device_login` → `pages::account::panels::device_panel` → `login::panel`）。
+        "msa-fallback" => {
+            app.account_form.panel = crate::pages::account::Panel::Microsoft;
+            app.state.apply_device_login(
+                unlucky_presenter::dto::DeviceLoginView::waiting(
+                    "ABCD-EFGH",
+                    "https://www.microsoft.com/link",
+                    900,
+                    "",
+                )
+                .with_browser_note(unlucky_presenter::dto::BrowserLoginNote::RedirectNotRegistered),
+            );
+        }
+        // 第三方站**失败**态：面板打开 + mock 那边给出的 `AuthlibLoginChanged(Failed)`
+        "authlib-failed" => {
+            app.account_form.panel = crate::pages::account::Panel::Authlib;
+            app.account_form.server = "https://example.invalid/api/yggdrasil/".to_string();
+            app.account_form.login = "alex@example.com".to_string();
+        }
+        // 离线档案失败态：面板打开（横幅由 mock 的 notice 场景给）
+        "notice" => {
+            app.account_form.panel = crate::pages::account::Panel::Offline;
+            app.account_form.offline_name = "ab".to_string();
+        }
+        // 第三方站表单：直接把面板打开并预填地址
+        "authlib" | "authlib-form" => {
+            app.account_form.panel = crate::pages::account::Panel::Authlib;
+            if app.account_form.server.trim().is_empty() {
+                app.account_form.server = "https://littleskin.cn/api/yggdrasil/".to_string();
+            }
+            app.account_form.login = "steve@example.com".to_string();
+            app.account_form.password = "not-a-real-password".to_string();
+        }
+        // 「关掉之后」：mock 给的是 failed 种子，这里按一次 Close（走真实的
+        // `on_account` → `CancelDeviceLogin` 通道），出「面板真的关了」的对照图。
+        "closed" => {
+            let _ = app.on_account(crate::pages::account::Message::Close);
+        }
+        // M178：登录入口面板（两个按钮 + 一行「没有浏览器时用这个」）。复审 r1 P2-5 的文案改动
+        // 要有图可看：`device_login` 是 Idle ⇒ 面板落在空闲态（主按钮=设备码，次按钮=浏览器）。
+        "msa-entry" => {
+            app.account_form.panel = crate::pages::account::Panel::Microsoft;
+        }
+        // 有账号时「Add an account」展开态（P2-4 的收敛后形态）
+        "add" => {
+            app.account_form.section_open = true;
+        }
+        _ => {}
+    }
+}
+
+#[cfg(test)]
+mod tests;

crates/app-iced/src/app/update/account/tests.rs

@@ -0,0 +1,303 @@
+//! **树测试②（M119 验收核心）**：账户页消费 presenter 的账户列表与登录事件。
+//!
+//! 后端是 UI 侧的 [`AccountRig`]：它把 `AppCommand` 翻成**与真 host 同形状**的 `CoreEvent`
+//! （`AccountsChanged` / `DeviceLoginChanged` / `AccountNoticeChanged`），数据在内存里。
+//! 于是这条测试钉住的是「**接线**」——用户点一下之后，命令出去、事件回来、页面重算、横幅出现；
+//! 抓不住的是 `core::auth::AccountStore` 的落盘（那条由 presenter 自己的
+//! `host::accounts::offline_add_list_remove_round_trips` 覆盖，原因见 `presenter/rig.rs` 的模块文档）。
+//!
+//! 覆盖任务书第 3 条与第 4 条的账户那一半：
+//!
+//! | 断言 | 抓得住什么 |
+//! |---|---|
+//! | 添加离线档案 → 列表出现一行 | `AddOfflineAccount` 没派发 / 事件没回流 / 页面没重建 |
+//! | 切换当前账号 → 「当前」标记换人 | `SwitchAccount` 没派发（M114 的 `active` 标记是页面唯一来源）|
+//! | 删除 → 列表回到空态 | `RemoveAccount` 没派发 |
+//! | 设备码「进行中可见 + 可取消」 | `StartDeviceLogin` / `CancelDeviceLogin` 没接线（只剩转圈）|
+//! | 失败态：名字不合法 / 凭据失效都给**具名**错误 | 失败被吞掉（复审 r1 P2-2 的老毛病）|
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_i18n::{Catalog, Key, Lang};
+use unlucky_presenter::dto::{
+    AccountNoticeCode, AppEvent, AuthlibLoginView, CoreEvent, DeviceLoginView, LoginFailure,
+};
+use unlucky_presenter::mock::MockBackend;
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+use crate::app::state::presenter::rig::AccountRig;
+use crate::pages::account::model::{AuthlibPanel, DevicePanel};
+use crate::pages::account::{Form, Message as Account, Panel, Track};
+use crate::theme::Families;
+
+use super::App;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+/// 不碰磁盘的 App，后端换成**账户 rig**（其余分支照旧走 `MockBackend` 的能力就够）。
+fn with_rig() -> App {
+    App::with_presenter(
+        crate::cli::Options::default(),
+        FAMILIES,
+        SchemeFlavor::Light,
+        Box::new(AccountRig::new()),
+        SettingsBridge::memory_only(),
+    )
+}
+
+/// 不碰磁盘的 App（mock 后端 + 内存设置桥），与 `app/tests.rs` 的 `headless` 同源。
+fn headless() -> App {
+    App::with_presenter(
+        crate::cli::Options::default(),
+        FAMILIES,
+        SchemeFlavor::Light,
+        Box::new(MockBackend::new()),
+        SettingsBridge::memory_only(),
+    )
+}
+
+fn seed(app: &mut App, event: CoreEvent) {
+    app.state.apply(AppEvent::Core(event));
+    app.refresh_view();
+}
+
+/// **添加 → 切换 → 删除**（任务书第 3 条，一条端到端）。
+///
+/// 抓得住：三条命令任何一条没派发 / 事件没回流 / `refresh_view` 没带上账户页。
+/// 抓不住：真实账户库的落盘（见模块文档）。
+#[test]
+fn an_offline_profile_is_added_switched_and_removed_end_to_end() {
+    let mut app = with_rig();
+    assert!(app.account.is_empty(), "出厂是空态");
+
+    // ① 添加离线档案：走真消息（点轨道卡 → 填名字 → 提交）
+    let _ = app.on_account(Account::Open(Track::Offline));
+    assert_eq!(app.account_form.panel, Panel::Offline);
+    // 表单输入也走真消息（纯 UI 态，只写 `App::account_form` + 置脏）
+    let _ = app.on_account(Account::OfflineName("Steve".to_string()));
+    assert!(
+        app.account_form.offline_ready(),
+        "3–16 位字母：按钮该是亮的"
+    );
+    let _ = app.on_account(Account::Submit);
+
+    assert_eq!(app.account.rows.len(), 1, "列表出现一行（不是静默）");
+    assert_eq!(app.account.rows[0].name, "Steve");
+    assert_eq!(
+        app.account.notice.as_ref().map(|notice| notice.code),
+        Some(AccountNoticeCode::Added),
+        "页面横幅给出的是一次性结果"
+    );
+    let id = app.account.rows[0].id.clone();
+
+    // ② 切换当前账号
+    let _ = app.on_account(Account::Switch(id.clone()));
+    assert_eq!(
+        app.account.active_row().map(|row| row.name.as_str()),
+        Some("Steve"),
+        "「当前」标记跟着切换走"
+    );
+
+    // ③ 删除
+    let _ = app.on_account(Account::Remove(id));
+    assert!(app.account.rows.is_empty(), "删除后回到空态");
+    assert_eq!(
+        app.account.notice.as_ref().map(|notice| notice.code),
+        Some(AccountNoticeCode::Removed)
+    );
+    // 两个横幅文案都有词（中英各一条，不是硬编码）
+    for lang in [Lang::En, Lang::ZhCn] {
+        assert!(!Catalog::of(lang).text(Key::AccountNoticeRemoved).is_empty());
+    }
+    // 整棵树在三种状态下都能构图
+    let _ = app.view();
+}
+
+/// 设备码流程：**指令发出 + 进行中可见 + 可取消**（任务书第 3 条的后半，真实网络不要求）。
+#[test]
+fn the_device_code_flow_is_started_visible_and_cancellable() {
+    let mut app = with_rig();
+    assert_eq!(app.account.device, DevicePanel::Hidden);
+
+    let _ = app.on_account(Account::StartDevice);
+    match &app.account.device {
+        DevicePanel::Code {
+            code, countdown, ..
+        } => {
+            assert_eq!(code, "ABCD-EFGH", "用户码要上屏");
+            assert!(!countdown.is_empty(), "倒计时在跑（文案由模型拼好）");
+        }
+        other => panic!("进行中状态必须可见，实际 {other:?}"),
+    }
+    assert_eq!(app.account.panel, Panel::Microsoft, "面板要切到微软那条轨");
+    let _ = app.view();
+
+    let _ = app.on_account(Account::Cancel);
+    assert_eq!(app.account.device, DevicePanel::Hidden, "取消要真的收掉");
+    assert_eq!(
+        app.state.device_login.phase,
+        unlucky_presenter::dto::DeviceLoginPhase::Idle
+    );
+}
+
+/// 失败态①：**未实现 / 名字不合法** ⇒ 页面横幅给出结构化码（不是静默无语）。
+#[test]
+fn an_invalid_profile_name_surfaces_a_named_failure() {
+    let mut app = with_rig();
+    let _ = app.on_account(Account::Open(Track::Offline));
+    // 名字不合法时**发送键是灰的**（与 host 同一份判据），所以这里直接派命令：
+    // 抓的是「host 真的回了一个结构化失败码」这条链路，而不是按钮的禁用态。
+    assert!(!app.account_form.offline_ready());
+    app.dispatch(unlucky_presenter::dto::AppCommand::AddOfflineAccount(
+        "ab".to_string(),
+    ));
+
+    assert!(app.account.rows.is_empty(), "不合法的名字不入列表");
+    let notice = app.account.notice.as_ref().expect("必须有横幅");
+    assert_eq!(notice.code, AccountNoticeCode::OfflineNameInvalid);
+    assert!(notice.failure, "失败档（配色不同）");
+    assert_eq!(notice.subject, "ab", "横幅要带上是哪个名字");
+    // 文案走 catalog，中英各一条
+    for lang in [Lang::En, Lang::ZhCn] {
+        assert!(!Catalog::of(lang)
+            .text(Key::AccountNoticeOfflineNameInvalid)
+            .is_empty());
+    }
+    let _ = app.view();
+}
+
+/// 失败态②：**账户凭据失效** ⇒ 第三方轨面板进入 `Failed(BadCredentials)`（只带原因码）。
+///
+/// 为什么只断言原因码：M114 r3 起面板类型里**没有** `message`/`detail` 字段（原文只进 presenter
+/// 日志），页面据码选 catalog 文案。这条测试与「页面画得出文案」之间的桥梁是
+/// `pages::account::login::failure_body_key`（同一 crate 内的穷尽 match，缺一条编译不过）。
+#[test]
+fn expired_credentials_surface_a_named_failure_code() {
+    let mut app = headless();
+    seed(
+        &mut app,
+        CoreEvent::AuthlibLoginChanged(AuthlibLoginView::failed_as(
+            LoginFailure::BadCredentials,
+            "服务器返回 401：凭据已失效（token=…已脱敏）",
+        )),
+    );
+    app.account_form.open(Track::Authlib);
+    app.refresh_view();
+
+    assert_eq!(
+        app.account.authlib,
+        AuthlibPanel::Failed {
+            failure: LoginFailure::BadCredentials
+        },
+        "凭据失效要落成具名原因码，而不是静默回 Idle"
+    );
+    // 原因码对应的那句译文两套语言都得有
+    for lang in [Lang::En, Lang::ZhCn] {
+        let text = Catalog::of(lang).text(Key::AccountFailureBadCredentials);
+        assert!(!text.trim().is_empty(), "{} 缺这条失败文案", lang.tag());
+    }
+    // 原文不许出现在页面的任何可视文本里（M114 的凭据红线）
+    assert!(
+        !format!("{:?}", app.account).contains("服务器返回 401"),
+        "后端原文不许进页面模型"
+    );
+    let _ = app.view();
+}
+
+// ---------------------------------------------------------------- M114 的既有回归闸
+
+/// **复审 r2 P2-1 的回归闸**：登录失败/成功态下按 `Close`，面板必须真的关掉。
+///
+/// 为什么这条以前是死按钮：`Page::build` 只要 `device_login.phase != Idle` 就把面板强制
+/// 回 Microsoft，而 `Close` 只在 `busy()`（Requesting/Waiting）时才派 `CancelDeviceLogin`
+/// ⇒ Failed/Succeeded 下点了没反应。现在判据改成「非 Idle」，两条轨都覆盖。
+///
+/// 抓得住：判据退回 `busy()`；`Close` 忘了 dispatch；`CancelDeviceLogin` 没有把状态收回 Idle。
+/// 抓不住：`CancelDeviceLogin` 在**真 host** 上的副作用（这里跑的是 mock，但 mock 已按
+/// 真 host 的契约发 Idle，见 `presenter/src/mock.rs`）。
+#[test]
+fn close_really_closes_the_login_panel_on_both_tracks() {
+    // ① 微软轨：失败态
+    let mut app = headless();
+    seed(
+        &mut app,
+        CoreEvent::DeviceLoginChanged(DeviceLoginView {
+            phase: unlucky_presenter::dto::DeviceLoginPhase::Failed,
+            message: "微软拒绝了这次登录：AADSTS7000218（HTTP 403）".to_string(),
+            failure: Some(LoginFailure::NotWhitelisted),
+            ..DeviceLoginView::new()
+        }),
+    );
+    assert_eq!(app.account.panel, Panel::Microsoft, "失败态面板要显示");
+    let _ = app.on_account(Account::Close);
+    assert_eq!(app.account.panel, Panel::None, "Close 之后面板必须关掉");
+    assert_eq!(
+        app.state.device_login.phase,
+        unlucky_presenter::dto::DeviceLoginPhase::Idle
+    );
+
+    // ② 微软轨：成功态（同样不在 busy 里）
+    let mut app = headless();
+    seed(
+        &mut app,
+        CoreEvent::DeviceLoginChanged(DeviceLoginView::succeeded("Steve")),
+    );
+    assert_eq!(app.account.panel, Panel::Microsoft);
+    let _ = app.on_account(Account::Close);
+    assert_eq!(app.account.panel, Panel::None, "成功提示也要能关掉");
+
+    // ③ 第三方轨：失败态
+    let mut app = headless();
+    seed(
+        &mut app,
+        CoreEvent::AuthlibLoginChanged(AuthlibLoginView {
+            phase: unlucky_presenter::dto::DeviceLoginPhase::Failed,
+            server: "https://example.invalid/api/yggdrasil/".to_string(),
+            server_name: String::new(),
+            message: "服务器返回 HTTP 404".to_string(),
+            failure: Some(LoginFailure::NotAuthlibServer),
+            account_name: String::new(),
+        }),
+    );
+    app.account_form.open(Track::Authlib);
+    app.refresh_view();
+    assert_eq!(
+        app.account.panel,
+        Panel::Authlib,
+        "第三方轨失败态面板要显示"
+    );
+    let _ = app.on_account(Account::Close);
+    assert_eq!(app.account.panel, Panel::None, "第三方轨也要能关掉");
+    assert_eq!(
+        app.state.authlib_login.phase,
+        unlucky_presenter::dto::DeviceLoginPhase::Idle
+    );
+}
+
+/// 表单态是纯 UI 状态：打开/关闭面板不派命令，但会把面板切对。
+///
+/// 抓得住：`Open` 忘了写 `panel`（点了轨道卡什么都不出现）、`close()` 不清密码。
+/// 抓不住：真实 dispatch 的副作用（那要真后端）。
+#[test]
+fn the_form_state_follows_the_page_messages() {
+    let mut form = Form::new();
+    assert_eq!(form.panel, Panel::None);
+    form.open(Track::Authlib);
+    assert_eq!(form.panel, Panel::Authlib);
+    form.password = "hunter2".to_string();
+    form.close();
+    assert_eq!(form.panel, Panel::None);
+    assert!(form.password.is_empty(), "关闭面板必须把一次性密码清掉");
+}
+
+/// 三张轨道卡默认收起（有账号时），`ToggleAdd` 展开（复审 r1 P2-4）。
+#[test]
+fn the_add_section_starts_collapsed() {
+    let mut form = Form::new();
+    assert!(!form.section_open);
+    form.section_open = true;
+    assert!(form.section_open);
+}

crates/app-iced/src/app/update/adopt.rs

@@ -0,0 +1,358 @@
+//! 「导入已有版本」向导的落点（M223 GUIADOPT）。
+//!
+//! ## 四段各自发什么、等什么
+//!
+//! | 用户动作 | 发什么 | 等什么回程 |
+//! |---|---|---|
+//! | 页头「导入」/ [`AdoptMessage::Open`] | `AdoptCommand::Scan` | `AdoptEvent::Scan` |
+//! | 选目标 + 点「预检」/ [`AdoptMessage::Check`] | `AdoptCommand::Preview` | `Planned` / `Failed` |
+//! | 点「确认导入」/ [`AdoptMessage::Confirm`] | `AdoptCommand::Confirm` | `Done` / `Failed` |
+//! | 「返回」/ [`AdoptMessage::Back`] | `AdoptCommand::Scan`（重扫一次，顺手清掉预检/失败） | `Scan` |
+//! | 「关闭」/ [`AdoptMessage::Close`] | `AdoptCommand::Dismiss` | `Cleared` |
+//!
+//! ## 三段纪律
+//!
+//! 1. **不在本地判「能不能导入」**：候选可不可用、落点在哪、有哪些问题全部来自 presenter 的回程
+//!    （`AdoptState`）。这里只把「用户点了什么」翻成命令；
+//! 2. **确认只发用户填过的那份请求**（版本 + 名字 + 目标档），预检与确认**同一份**——
+//!    于是「预检 A、写 B」这种错位不可能发生；
+//! 3. **在等回程时把主按钮并掉**（`Form::busy`）：连点两次「确认」不会写两条实例记录。
+
+use iced::Task;
+use unlucky_presenter::dto::{AdoptCommand, AdoptRequestView, AppCommand};
+
+use crate::app::adopt::{AdoptMessage, Busy};
+
+use super::super::message::Message;
+use super::super::state::App;
+
+impl App {
+    /// 向导的一条消息。
+    pub(super) fn on_adopt(&mut self, message: AdoptMessage) -> Task<Message> {
+        match message {
+            AdoptMessage::Open => {
+                self.adopt_form.open();
+                self.dispatch_adopt(AdoptCommand::Scan);
+            }
+            AdoptMessage::Close => {
+                // 登记在飞时不吃「关闭」：core 那条线程已经开跑了，写了盘却不回报 Done
+                // 就会出现「实例已存在但界面什么都没说」——等它交卷（几十毫秒级）。
+                if self.adopt_form.busy == Busy::Importing {
+                    return Task::none();
+                }
+                self.adopt_form.close();
+                self.dispatch_adopt(AdoptCommand::Dismiss);
+            }
+            AdoptMessage::Select(version_id) => {
+                self.adopt_form.selected = Some(version_id);
+            }
+            AdoptMessage::Name(name) => self.adopt_form.name = name,
+            AdoptMessage::Target(target) => {
+                // 登记在飞时不吃「换档」：它会派一条零写盘的预览把 `adopt_epoch` +1，
+                // 于是在飞的 Confirm 交卷时 Done 被代次丢掉——实例写进去了，界面什么都没说。
+                // 连本地档位也不改：界面上显示 A 档、盘上写的是 B 档，是最糟的一种不一致。
+                if self.adopt_form.busy == Busy::Importing {
+                    return Task::none();
+                }
+                self.adopt_form.target = target;
+                // 换了目标档 ⇒ 上一档的预检作废（确认按钮不该继续亮着）
+                self.adopt_form.checked = false;
+                // 共享档 / 版本目录档会写进**别人的目录**：一被点选就把后果原文拿出来
+                // （零写盘的预检，见 `Form::stage` 的收窄：这一次结果落在 Pick 段当提示读）。
+                if target.touches_foreign_dir() {
+                    if let Some(request) = self.adopt_request() {
+                        self.adopt_form.busy = Busy::Checking;
+                        self.dispatch_adopt(AdoptCommand::Preview(Box::new(request)));
+                    }
+                }
+            }
+            AdoptMessage::Check => {
+                if let Some(request) = self.adopt_request() {
+                    self.adopt_form.checked = true;
+                    self.adopt_form.busy = Busy::Checking;
+                    self.dispatch_adopt(AdoptCommand::Preview(Box::new(request)));
+                }
+            }
+            AdoptMessage::Confirm => {
+                if let Some(request) = self.adopt_request() {
+                    self.adopt_form.busy = Busy::Importing;
+                    self.dispatch_adopt(AdoptCommand::Confirm(Box::new(request)));
+                }
+            }
+            AdoptMessage::Back => {
+                // 同 Close / Target：登记在飞时「返回」会把 `adopt_epoch` +1（它派 Scan），
+                // 在飞 Confirm 的 Done 就再也到不了界面。
+                if self.adopt_form.busy == Busy::Importing {
+                    return Task::none();
+                }
+                // 退回候选列表 = 重新扫一次：`scan` 会把上一轮的预检/失败一起作废，
+                // 于是界面回到 Pick 段，不需要再给 core 加一个「清失败」的命令。
+                self.adopt_form.checked = false;
+                self.adopt_form.busy = Busy::Scanning;
+                self.dispatch_adopt(AdoptCommand::Scan);
+            }
+        }
+        Task::none()
+    }
+
+    /// 回程到了：这一条命令已经交卷（`pump` 收到 `CoreEvent::Adopt` 时调，见 `update/clock.rs`）。
+    /// 出图通道的种子（`ULL_ADOPT_STATE`，与 `ULL_JAVA_STATE` / `ULL_AI_STATE` 同一族）。
+    ///
+    /// **只在 `--screenshot` 下生效**：交互模式读这个环境变量没有意义（也没有人会设它）。
+    /// 不认识的名字一律忽略，退回正常启动路径（向导保持关闭）。
+    pub(in crate::app) fn hydrate_adopt_state(&mut self) {
+        if self.options.screenshot.is_none() {
+            return;
+        }
+        let Ok(raw) = std::env::var(crate::app::adopt::shot::ENV) else {
+            return;
+        };
+        if let Some((form, state)) = crate::app::adopt::shot::seed(&raw) {
+            self.adopt_form = form;
+            self.state.adopt = state;
+        }
+    }
+
+    pub(super) fn settle_adopt(&mut self) {
+        self.adopt_form.settled();
+    }
+
+    /// 当前表单能拼出的请求（没选版本就没有请求——按钮在那边也是禁用的）。
+    fn adopt_request(&self) -> Option<AdoptRequestView> {
+        let version_id = self.adopt_form.selected.clone()?;
+        let name = self.adopt_form.name.trim();
+        Some(AdoptRequestView {
+            version_id,
+            name: (!name.is_empty()).then(|| name.to_string()),
+            target: self.adopt_form.target,
+        })
+    }
+
+    fn dispatch_adopt(&mut self, command: AdoptCommand) {
+        self.dispatch(AppCommand::Adopt(Box::new(command)));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::cell::RefCell;
+    use std::rc::Rc;
+
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_presenter::dto::{
+        AdoptCommand, AdoptEvent, AdoptTargetView, AppCommand, AppEvent, Backend,
+    };
+    use unlucky_presenter::mock::MockBackend;
+    use unlucky_presenter::settings_bridge::SettingsBridge;
+
+    use crate::app::adopt::{AdoptMessage, Busy};
+    use crate::app::state::App;
+    use crate::cli::Options;
+    use crate::theme::Families;
+
+    const FAMILIES: Families = Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+
+    fn headless() -> App {
+        App::with_presenter(
+            Options::default(),
+            FAMILIES,
+            SchemeFlavor::Light,
+            Box::new(MockBackend::new()),
+            SettingsBridge::memory_only(),
+        )
+    }
+
+    /// 记账后端：把 `dispatch` 收到的命令留在台账里（`MockBackend` 只认自己那几条，
+    /// 「有没有派出去」根本看不见——而 P2-1 的判据正是「不许派」）。
+    #[derive(Debug, Default)]
+    struct RecordingBackend {
+        dispatched: Rc<RefCell<Vec<AppCommand>>>,
+    }
+
+    impl Backend for RecordingBackend {
+        fn drain_events(&mut self) -> Vec<AppEvent> {
+            Vec::new()
+        }
+
+        fn dispatch(&mut self, command: AppCommand) {
+            self.dispatched.borrow_mut().push(command);
+        }
+    }
+
+    /// 带台账的 App（返回台账句柄，测试直接查「派了什么」）。
+    fn recording() -> (App, Rc<RefCell<Vec<AppCommand>>>) {
+        let dispatched: Rc<RefCell<Vec<AppCommand>>> = Rc::new(RefCell::new(Vec::new()));
+        let app = App::with_presenter(
+            Options::default(),
+            FAMILIES,
+            SchemeFlavor::Light,
+            Box::new(RecordingBackend {
+                dispatched: Rc::clone(&dispatched),
+            }),
+            SettingsBridge::memory_only(),
+        );
+        (app, dispatched)
+    }
+
+    /// 台账里有没有派过某条 adopt 命令（只认命令种类，不看载荷内容）。
+    ///
+    /// 写法是 `let ... else` + `matches!`：内层用 `match` 会被 clippy 判成
+    /// `match expression looks like matches! macro`（deny 级，CI 的 `-D warnings` 直接红）。
+    fn dispatched_adopt(ledger: &Rc<RefCell<Vec<AppCommand>>>, want: &str) -> bool {
+        ledger.borrow().iter().any(|command| {
+            let AppCommand::Adopt(command) = command else {
+                return false;
+            };
+            matches!(
+                (&**command, want),
+                (AdoptCommand::Scan, "scan")
+                    | (AdoptCommand::Preview(_), "preview")
+                    | (AdoptCommand::Confirm(_), "confirm")
+                    | (AdoptCommand::Dismiss, "dismiss")
+            )
+        })
+    }
+
+    /// 打开向导 = 表单进入「在等扫描」+ 派一条 `Scan`。
+    ///
+    /// 抓得住：`Open` 没派命令（面板永远停在「正在扫描」）、或忘了置 `Busy::Scanning`（没有等待态）。
+    /// 抓不住：扫描真的返回了什么（那在 presenter 的 `host/adopt` 用例里）。
+    #[test]
+    fn opening_the_wizard_asks_for_a_scan() {
+        let mut app = headless();
+        let _ = app.on_adopt(AdoptMessage::Open);
+        assert!(app.adopt_form.open);
+        assert_eq!(app.adopt_form.busy, Busy::Scanning);
+        assert_eq!(
+            app.adopt_form.target,
+            AdoptTargetView::InstanceDir,
+            "缺省不是 isolated"
+        );
+    }
+
+    /// 没选版本时「预检 / 确认」不派命令（否则会发出一条 `version_id` 为空的请求）。
+    ///
+    /// 抓得住：`adopt_request()` 在没有选中项时仍拼出请求（空版本 id 打到 core 换一句
+    /// `adopt_version_not_found`，用户看到莫名其妙的失败）。
+    #[test]
+    fn no_request_without_a_selected_version() {
+        let mut app = headless();
+        let _ = app.on_adopt(AdoptMessage::Open);
+        let _ = app.on_adopt(AdoptMessage::Check);
+        assert_eq!(app.adopt_form.busy, Busy::Scanning, "Check 不该改等待态");
+        let _ = app.on_adopt(AdoptMessage::Confirm);
+        assert_eq!(app.adopt_form.busy, Busy::Scanning);
+    }
+
+    /// 选中 + 预检 = 一条 Preview 命令，且请求里的名字是**去过空白**的用户输入。
+    #[test]
+    fn check_sends_the_form_as_a_preview_request() {
+        let mut app = headless();
+        let _ = app.on_adopt(AdoptMessage::Open);
+        let _ = app.on_adopt(AdoptMessage::Select("1.20.1".to_string()));
+        let _ = app.on_adopt(AdoptMessage::Name("  生存  ".to_string()));
+        let _ = app.on_adopt(AdoptMessage::Target(AdoptTargetView::Shared));
+        let _ = app.on_adopt(AdoptMessage::Check);
+        assert_eq!(app.adopt_form.busy, Busy::Checking);
+        // 请求本体不在 App 上留副本：能证明意图的只有等待态与目标档
+        assert_eq!(app.adopt_form.target, AdoptTargetView::Shared);
+    }
+
+    /// 回程到了就解除等待（`settle_adopt` 由 `pump` 调）。
+    #[test]
+    fn an_incoming_event_settles_the_wait() {
+        let mut app = headless();
+        let _ = app.on_adopt(AdoptMessage::Open);
+        assert!(app.adopt_form.busy.waiting());
+        app.settle_adopt();
+        assert_eq!(app.adopt_form.busy, Busy::Idle);
+        // 事件真相进了 presenter 的状态（界面从它取词）
+        app.state.apply(unlucky_presenter::dto::AppEvent::Core(
+            unlucky_presenter::dto::CoreEvent::Adopt(Box::new(AdoptEvent::Cleared)),
+        ));
+        assert!(app.state.adopt.scan.is_none());
+    }
+
+    /// 共享档一被点选就发一条**预检**（零写盘），但**不**置 `checked`——确认页要用户点「预检」。
+    ///
+    /// 抓得住：`Target` 分支忘了发预检（后果原文永远不出现，契约 §5.2 失守）、
+    /// 或者顺手把 `checked` 也置上（点一下档位就跳到确认页）。
+    #[test]
+    fn choosing_a_foreign_target_previews_but_waits_for_the_user() {
+        let mut app = headless();
+        let _ = app.on_adopt(AdoptMessage::Open);
+        let _ = app.on_adopt(AdoptMessage::Select("1.20.1".to_string()));
+        let _ = app.on_adopt(AdoptMessage::Target(AdoptTargetView::Shared));
+        assert_eq!(app.adopt_form.busy, Busy::Checking);
+        assert!(!app.adopt_form.checked, "确认页要等用户点「预检」");
+
+        // 缺省档不触发自动预检（它不会写进别人的目录）
+        let _ = app.on_adopt(AdoptMessage::Target(AdoptTargetView::InstanceDir));
+        assert!(!app.adopt_form.checked);
+    }
+
+    /// 登记在飞时「关闭」被忽略：core 已经在写了，关掉面板只会让 Done 无处可去。
+    ///
+    /// 抓得住：Close 无条件清表单并 `Dismiss`（实例写成功了，界面却什么都没说）。
+    #[test]
+    fn closing_is_ignored_while_the_registration_is_in_flight() {
+        let mut app = headless();
+        let _ = app.on_adopt(AdoptMessage::Open);
+        let _ = app.on_adopt(AdoptMessage::Select("1.20.1".to_string()));
+        let _ = app.on_adopt(AdoptMessage::Check);
+        app.adopt_form.busy = Busy::Importing;
+        let _ = app.on_adopt(AdoptMessage::Close);
+        assert!(app.adopt_form.open, "登记在飞时不许把面板关掉");
+    }
+
+    /// **P2-1**：登记在飞时，除了 Close，「返回」与「换目标档」也必须早退。
+    ///
+    /// 三条都是同一条病：它们都会派一条新命令把 `adopt_epoch` +1，于是在飞 Confirm 的
+    /// `Done` 回来时被代次丢掉 —— 实例**写进去了**，界面却什么都没说（Close 那条早就守住了，
+    /// 唯独这两支漏了）。
+    ///
+    /// 抓得住：`Back` 派了 `Scan`（旧 `Done` 被丢）、`Target` 派了 `Preview`（同上），
+    /// 以及「守卫写了但写在改本地状态之后」（表单被改成新档位，而盘上写的是旧档位）。
+    /// 抓不住：host 侧代次比较的真实时序（那在 presenter 的 `host/adopt` 那层）。
+    #[test]
+    fn back_and_target_are_ignored_while_the_registration_is_in_flight() {
+        let (mut app, ledger) = recording();
+        let _ = app.on_adopt(AdoptMessage::Open);
+        let _ = app.on_adopt(AdoptMessage::Select("1.20.1".to_string()));
+        let _ = app.on_adopt(AdoptMessage::Target(AdoptTargetView::InstanceDir));
+        // 走到「确认」那一步：真的派一条 Confirm 出去
+        let _ = app.on_adopt(AdoptMessage::Check);
+        let _ = app.on_adopt(AdoptMessage::Confirm);
+        assert!(
+            dispatched_adopt(&ledger, "confirm"),
+            "前提：确认要真的派出去"
+        );
+        assert_eq!(app.adopt_form.busy, Busy::Importing);
+        ledger.borrow_mut().clear();
+
+        // 在飞期间点「返回」：不许派 Scan
+        let _ = app.on_adopt(AdoptMessage::Back);
+        assert!(
+            !dispatched_adopt(&ledger, "scan"),
+            "登记在飞时 Back 不许派 Scan（会把 Done 的代次顶掉）"
+        );
+        assert_eq!(app.adopt_form.busy, Busy::Importing, "等待态不许被改掉");
+
+        // 在飞期间换目标档：不许派 Preview，也不许改本地档位
+        let _ = app.on_adopt(AdoptMessage::Target(AdoptTargetView::Shared));
+        assert!(
+            !dispatched_adopt(&ledger, "preview"),
+            "登记在飞时换档不许派 Preview（会把 Done 的代次顶掉）"
+        );
+        assert_eq!(
+            app.adopt_form.target,
+            AdoptTargetView::InstanceDir,
+            "挡下来的点击不该改出界面与盘上不一致的档位"
+        );
+        assert_eq!(app.adopt_form.busy, Busy::Importing);
+    }
+}

crates/app-iced/src/app/update/agent.rs

@@ -0,0 +1,382 @@
+//! 助手栏消息的落点（M104 建，M119 接线）：三档状态迁移 / 输入 / 键盘 / **presenter 四契约**。
+//!
+//! ## 为什么单独一个文件
+//!
+//! `app/update.rs` 已经贴着 400 行硬上限（M94 也因此把下载页四支拆到 `update/download.rs`）。
+//! 助手栏有十几个变体，塞回主文件必破线。
+//!
+//! ## 分工：视图态 vs presenter 契约（M119 之后的分界线）
+//!
+//! | 消息 | 落到哪 |
+//! |---|---|
+//! | `Expand` / `Collapse` / `Dock` / `Escape` | **只改视图态**（`AgentUi`）+ 路由栈（离开/进入 `Route::Agent`）+ `agent_mark_read` |
+//! | `Detach` | 视图态 + `Route::Agent`（压栈，`back()` 能回去）+ `agent_mark_read` |
+//! | `Edit` | 视图态（草稿），并同步进 presenter 的草稿（`agent_set_draft`） |
+//! | `Submit` | [`AgentHost::submit`] → `agent_submit`；失败**不留白**（具名错误进横幅） |
+//! | `Stop` | `AppCommand::StopAgent`（真后端才收敛得出结果；同步 rig 下是 no-op） |
+//! | `Confirm(accept)` | [`AgentHost::confirm`] → `agent_confirm`（YOLO 下 presenter 自己放行并记审计） |
+//! | `Events(..)` | [`AgentHost::apply`] → `AppState::apply`（**事件回流的唯一落点**） |
+//! | `DragStart` / `DragTo` / `DragEnd` | 视图态：吸附宽度 |
+//! | `Key` / `Tab` / `Activate` | 键盘路径（`Tab` 的环要在流式中多一格，`busy` 从 rail 取） |
+//!
+//! **会话内容一行都不在这里攒**：`transcript` / `busy` / `unread` / `confirm` 全在 presenter 的
+//! `AgentRail` 上（M119 删掉了 M104 的自持副本）。
+//!
+//! ## 事件为什么绕一圈消息再回来
+//!
+//! `agent_submit` / `agent_confirm` 的端口是同步的，但**事件走队列**（见
+//! `app/state/presenter/transport.rs`）：抽队列的那一步必须和用户点击走同一条漏斗，否则两处各改
+//! 一次状态，流式标记与未读会打架。所以 [`App::drain_agent`] 抽出来之后立刻
+//! `on_agent(agent::Message::Events(..))` —— 同一条 `Message::Agent(..)` 通道。
+
+use crate::app::diag::diag;
+use iced::keyboard::{key, Key};
+use iced::Task;
+
+use unlucky_i18n::{Catalog, Key as TextKey};
+use unlucky_presenter::dto::AppCommand;
+
+use crate::app::MIN_SIZE;
+use crate::app::WINDOW_SIZE;
+use crate::shell::agent::demo::{self, Fixture};
+use crate::shell::agent::{self, Focus, RailState};
+
+use super::super::state::presenter::agent::SubmitOutcome;
+use super::*;
+
+#[cfg(test)]
+mod tests;
+
+impl App {
+    /// 助手栏消息（`app::Message::Agent(..)` 的唯一落点）。
+    pub(super) fn on_agent(&mut self, message: agent::Message) -> Task<Message> {
+        // M106 口径：文案走**生效语言**的目录，不再恒英文
+        let catalog = Catalog::of(self.lang());
+
+        // 只有**几何**会变的几支才需要重建页面模型（`pages::Model` 里没有会话内容：会话在
+        // presenter 的 rail 上，右栗自己那棵树每次 `view()` 都从 rail 现读）。复审 P3-9 的教训：
+        // 每敲一个字符都重建整张模型是白克隆。
+        let geometry_changed = matches!(
+            message,
+            agent::Message::Expand
+                | agent::Message::Collapse
+                | agent::Message::Detach
+                | agent::Message::Dock
+                | agent::Message::DragTo(_)
+                | agent::Message::DragEnd
+                | agent::Message::Escape
+                | agent::Message::Activate
+                | agent::Message::Key(_)
+        );
+
+        match message {
+            agent::Message::Expand => {
+                self.agent.expand();
+                // 「展开即读」是 presenter 的语义（`agent_mark_read`），壳只负责在正确的时刻调它
+                self.agent_host.mark_read();
+            }
+            agent::Message::Collapse | agent::Message::Escape => self.collapse_agent(),
+            agent::Message::Detach => {
+                self.agent.detach();
+                self.agent_host.mark_read();
+                self.state.navigate(Route::Agent);
+            }
+            agent::Message::Dock => {
+                self.agent.dock();
+                self.agent_host.mark_read();
+                self.leave_agent_page();
+            }
+            agent::Message::DragStart => self.agent.drag_start(),
+            agent::Message::DragTo(x) => self.agent.drag_to(self.width, x),
+            agent::Message::DragEnd => self.agent.drag_end(),
+            agent::Message::Edit(action) => {
+                self.agent.edit(action);
+                // 草稿同步给 presenter（切形态不丢；它也是 rail 上唯一允许躺原文的字段）
+                self.agent_host.set_draft(self.agent.draft.text());
+            }
+            agent::Message::Submit => self.submit_agent(),
+            agent::Message::Stop => self.dispatch(AppCommand::StopAgent),
+            agent::Message::Confirm(accept) => {
+                self.agent_host.confirm(accept);
+                self.drain_agent();
+            }
+            agent::Message::Events(events) => {
+                for event in events {
+                    self.agent_host.apply(event);
+                }
+                self.view_dirty = true;
+            }
+            agent::Message::Tab { shift } => {
+                let rail = self.agent_host.rail();
+                let (busy, pending) = (rail.busy, rail.confirm.is_some());
+                self.agent.step_focus(shift, busy, pending);
+            }
+            agent::Message::Activate => self.activate_focused(catalog),
+            agent::Message::Key(event) => return self.on_agent_key(event),
+        }
+
+        // 待确认请求出现/消失时，把键盘焦点挪到（或挪离）确认条的按钮上
+        self.sync_confirm_focus();
+        // 档位 / 路由变了就要把「栏可见吗」写回 presenter（未读口径的输入）
+        self.sync_agent_presenter();
+        if geometry_changed {
+            self.view_dirty = true;
+            self.refresh_view();
+        }
+        Task::none()
+    }
+
+    /// 发送：草稿 → `agent_submit` → 抽事件。
+    ///
+    /// 三种结局各自有落点：发出去（清草稿）/ 后端失败（具名横幅，见 [`App::agent_failure`]）/
+    /// presenter 拒收（日志一行——这三种情形正常情况下被禁用态挡住，够不着）。
+    fn submit_agent(&mut self) {
+        let text = self.agent.draft.text();
+        if text.trim().is_empty() {
+            return;
+        }
+        match self.agent_host.submit(text) {
+            SubmitOutcome::Sent => {
+                self.agent.clear_draft();
+                self.agent_host.set_draft(String::new());
+                self.drain_agent();
+            }
+            SubmitOutcome::Failed(failure) => {
+                diag!("[agent] 提交失败（{}）", failure.code());
+            }
+            SubmitOutcome::Rejected => {
+                diag!("[agent] presenter 拒收：空文本 / 上一轮未完 / 待确认 三闸该先挡住");
+            }
+        }
+    }
+
+    /// 抽干 presenter 的事件队列，**经既有 Message 通道**回流（见模块文档末节）。
+    pub(crate) fn drain_agent(&mut self) {
+        let events = self.agent_host.drain();
+        if events.is_empty() {
+            return;
+        }
+        let _ = self.on_agent(agent::Message::Events(events));
+    }
+
+    /// 把「栏可见吗」写回 presenter（`navigate` + `prefs_mut` 两个窄入口，见 `AgentHost`）。
+    pub(crate) fn sync_agent_presenter(&mut self) {
+        let on_page = self.state.route() == &Route::Agent;
+        let collapsed = self.agent.rail == RailState::Collapsed;
+        self.agent_host.sync_visibility(on_page, collapsed);
+    }
+
+    /// 失败横幅要显示的东西（`None` = 没有错误）。
+    ///
+    /// 两个来源都取**展示输入**：具名原因码 → catalog 译文；或 presenter 已脱敏的这一轮原因。
+    /// 壳在这一层不做任何脱敏（那是 presenter 的`scrub_text`），也不拼中英（那是 catalog 的事）。
+    pub(crate) fn agent_failure(&self) -> Option<agent::Failure<'_>> {
+        let catalog = self.lang().catalog();
+        if let Some(failure) = self.agent_host.last_failure() {
+            return Some(agent::Failure {
+                title: TextKey::AgentErrorTitle,
+                body: catalog.text(failure.body_key()),
+            });
+        }
+        self.agent_host
+            .rail()
+            .error
+            .as_deref()
+            .map(|body| agent::Failure {
+                title: TextKey::AgentErrorTitle,
+                body,
+            })
+    }
+
+    /// 待确认请求出现 ⇒ 焦点直接落在「允许」；消失 ⇒ 收回输入框。
+    ///
+    /// **只挪焦点，不替用户打开键盘巡航**（M119 r2 / 复审 P2-2）：r1 在这里顺手把
+    /// `keyboard_mode` 置真，而 `sync_confirm_focus` 是 `on_agent` 的无条件尾巴、`Events` 又由心跳
+    /// 驱动——于是只要冒出待确认，全局键盘闸就被打开；用户发完那句话接着打下一句，第一个空格
+    /// 就成了「批准写操作」。现在那道闸只由真实的键盘表态打开（`Tab`，见 `AgentUi::step_focus`；
+    /// 或者 `on_agent_key` 把按键送进来时用户本来就在键盘巡航）。
+    ///
+    /// 键盘用户怎么走到确认条：待确认时焦点已经在这两个按钮上，**按一次 `Tab` 点亮焦点环即是
+    /// 表态**（`step_focus` 里那条 arming 规则：这一次不移动焦点），之后 `Enter`/`Space` 就能裁决。
+    ///
+    /// 唯一写入口：`on_agent` 末尾（任何会改动 rail 的分支之后都要经过它）。
+    fn sync_confirm_focus(&mut self) {
+        let pending = self.agent_host.rail().confirm.is_some();
+        let on_confirm = matches!(self.agent.focus, Focus::ConfirmAllow | Focus::ConfirmDeny);
+        if pending && !on_confirm {
+            self.agent.focus = Focus::ConfirmAllow;
+            diag!("[agent] 写操作待确认 → 焦点落到 Allow（Tab 点亮焦点环后 Enter/Space 裁决）");
+        } else if !pending && on_confirm {
+            self.agent.focus = Focus::Composer;
+            self.agent.keyboard_mode = false;
+        }
+    }
+
+    /// **不变式**：`route() == Route::Agent` ⟺ `agent.rail == RailState::Detached`（唯一同步点）。
+    ///
+    /// 为什么需要它（复审 r1 的 P2-1，实测复现）：`agent.rail` 只在自己发 `Detach`/`Dock` 时变，
+    /// 而路由还能从三条**别的**路径进 `Route::Agent`——左侧导航第五项、`pages::Message::Navigate`、
+    /// `ULL_START_ROUTE=agent`。脱钩的后果：从导航进独立页时头部出现「Open assistant」（那是
+    /// 「展开右栗」的意思）、标题旁挂着不化的未读胶囊、`Esc` 也收不走页面。
+    ///
+    /// 两条对向规则：
+    /// - **在**独立页上 ⇒ `Detached`（顺带按「拆出即读」清未读）；
+    /// - **不在**独立页上而档位还是 `Detached`（用户从页上点了别的导航）⇒ 会话收回右栗（`dock()`），
+    ///   否则会话会「两头都没有」：页走了、栏还是 0 宽。
+    ///
+    /// 调用点只有一个：`App::refresh_view` 的开头。每一次路由变化都会经过它，于是**模型算宽度时**
+    /// 与**画头部动作时**读到的永远是同一份档位。
+    pub(crate) fn sync_agent_route(&mut self) {
+        let on_page = self.state.route() == &Route::Agent;
+        match (on_page, self.agent.rail) {
+            (true, RailState::Detached) | (false, RailState::Collapsed | RailState::Expanded) => {}
+            (true, _) => self.agent.detach(),
+            (false, RailState::Detached) => self.agent.dock(),
+        }
+    }
+
+    /// 启动时助手栏要做的三件事（从 `on_boot` 搬出来：那边只许留一行调用，复审 P3-6）。
+    ///
+    /// 1. **窗口尺寸 adopt**：唯一真源是 `boot.rs` 开窗时用的那一个（`ULL_WINDOW_SIZE` + 最小尺寸
+    ///    钳位）。`App::with_presenter` 只认识常量 1180×760，不 adopt 的话验收矩阵开 900 / 1520 的窗
+    ///    时页面还按 1180 排版（窄窗里内容被裁）。
+    /// 2. **取证夹具**（`ULL_AGENT_*`）：先落档位，再**跑一轮真提交**——夹具不造消息，消息只能
+    ///    由 presenter 产生（M119 的口径，见 `pages/agent/demo.rs`）。
+    /// 3. **拆出档直接落到独立页**：`ULL_AGENT_RAIL=detached`（以及将来持久化的偏好）时，会话就在
+    ///    独立页里，启动后不该停在实例页。
+    pub(super) fn boot_agent(&mut self) {
+        let (window_size, _source) = crate::renderer::acceptance::window::window_size(
+            (WINDOW_SIZE.width, WINDOW_SIZE.height),
+            (MIN_SIZE.width, MIN_SIZE.height),
+        );
+        self.width = window_size.0;
+        self.height = window_size.1;
+
+        if let Some((ui, fixture)) = demo::from_env() {
+            self.agent = ui;
+            // 先让 presenter 知道「栏现在看得见吗」，再跑提交，未读口径才对
+            self.sync_agent_presenter();
+            match fixture {
+                Fixture::None => {}
+                Fixture::Turn | Fixture::Unread => {
+                    let _ = self.agent_host.submit(demo::DEMO_QUESTION.to_string());
+                    self.drain_agent();
+                }
+                Fixture::Armed => {
+                    // 先跑一轮（写操作脚本会挂一个待确认），再按一次 `Tab`：
+                    // 待确认时这一下只 arm、不移动焦点（见 `AgentUi::step_focus` 的 arming 规则）
+                    let _ = self.agent_host.submit(demo::DEMO_QUESTION.to_string());
+                    self.drain_agent();
+                    let rail = self.agent_host.rail();
+                    let (busy, pending) = (rail.busy, rail.confirm.is_some());
+                    self.agent.step_focus(false, busy, pending);
+                }
+                Fixture::Focused => {
+                    let rail = self.agent_host.rail();
+                    let (busy, pending) = (rail.busy, rail.confirm.is_some());
+                    self.agent.step_focus(false, busy, pending);
+                }
+            }
+        }
+
+        if self.agent.rail == RailState::Detached && self.state.route() != &Route::Agent {
+            diag!("[agent] rail=detached → Route::Agent");
+            self.state.navigate(Route::Agent);
+            // 直达独立页时不要再被「自动选中第一条实例」拉回详情页。
+            self.auto_selected = true;
+        }
+    }
+
+    /// 键盘订阅来的按键（`app/subscription.rs` 把整条键盘事件搬过来，解释权在这一层）。
+    ///
+    /// 为什么不让订阅层直接翻成三个枚举：那样 `Escape`/`Tab`/`Enter` 的语义（什么状态下该做什么）
+    /// 会散在订阅表里；这里一眼能看完。
+    fn on_agent_key(&mut self, event: iced::keyboard::Event) -> Task<Message> {
+        let iced::keyboard::Event::KeyPressed { key, modifiers, .. } = event else {
+            return Task::none();
+        };
+
+        let message = match key {
+            Key::Named(key::Named::Escape) => agent::Message::Escape,
+            // 折叠档没有会话动作可巡航，`Tab` 不该被助手栏吃掉
+            Key::Named(key::Named::Tab) if self.agent.rail == RailState::Collapsed => {
+                return Task::none();
+            }
+            Key::Named(key::Named::Tab) => agent::Message::Tab {
+                shift: modifiers.shift(),
+            },
+            // `Activate` 只在软焦点落在**按钮**上时才动手（输入框的 Enter 由
+            // `text_editor::key_binding` 分流成「发送」，不能在这里重复发一次）。
+            //
+            // M119 r1 / P2-2：`Space` 与 `Enter` 等价（键盘用户对确认条的习惯动作是空格）。
+            // 它不会抢输入框里的空格：`activate_focused` 头一行就是 `keyboard_mode` 闸，
+            // 而用鼠标点进输入框时那道闸是关的（`AgentUi::edit` 的 `Click` 分支）。
+            Key::Named(key::Named::Enter | key::Named::Space) => agent::Message::Activate,
+            _ => return Task::none(),
+        };
+
+        self.on_agent(message)
+    }
+
+    /// `Esc` / `⌄`：展开 → 收起；独立页 → 收回右栗并离开 `Route::Agent`。
+    fn collapse_agent(&mut self) {
+        let was_detached = self.agent.rail == RailState::Detached;
+        self.agent.collapse();
+        if was_detached {
+            self.leave_agent_page();
+        }
+    }
+
+    /// 离开 AI 独立页：能回退就回退（`Detach` 是压栈的），否则回实例页。
+    fn leave_agent_page(&mut self) {
+        if self.state.route() != &Route::Agent {
+            return;
+        }
+        if !self.state.back() {
+            self.state.navigate(Route::Instances);
+        }
+    }
+
+    /// 键盘 `Enter`：激活软焦点上的按钮（`Tab` 环的顺序见 [`Focus`]）。
+    ///
+    /// 焦点在 [`Focus::Composer`] 上时**什么都不做**：那一条路径由输入框自己的 `key_binding`
+    /// 负责（按 `Tab` 走到输入框并不等于真的把 iced 焦点交过去，两次发送会打架）。
+    fn activate_focused(&mut self, catalog: Catalog) {
+        // 鼠标刚点过输入框（或从没按过 `Tab`）⇒ 这个 Enter 不归助手栏管
+        if !self.agent.keyboard_mode {
+            return;
+        }
+
+        let intent = match (self.agent.rail, self.agent.focus) {
+            (RailState::Collapsed, Focus::Collapse) => Some(agent::Message::Expand),
+            (RailState::Expanded, Focus::Collapse) => Some(agent::Message::Collapse),
+            (RailState::Expanded, Focus::Detach) | (RailState::Detached, Focus::Detach) => {
+                Some(if self.agent.rail == RailState::Detached {
+                    agent::Message::Dock
+                } else {
+                    agent::Message::Detach
+                })
+            }
+            (_, Focus::ConfirmAllow) => Some(agent::Message::Confirm(true)),
+            (_, Focus::ConfirmDeny) => Some(agent::Message::Confirm(false)),
+            (_, Focus::Send) => Some(agent::Message::Submit),
+            (_, Focus::Stop) => Some(agent::Message::Stop),
+            // 折叠档没有「拆出」、独立页没有「收起」：焦点环按 `Focus::order` 不会落到这两格，
+            // 显式列成 None 只是为了让编译器确认这份 intent 表是穷尽的。
+            (RailState::Collapsed, Focus::Detach)
+            | (RailState::Detached, Focus::Collapse)
+            | (_, Focus::Composer) => None,
+        };
+
+        if let Some(message) = intent {
+            let _ = self.on_agent(message);
+        } else {
+            // 「不得静默无反应」：焦点在输入框上按 Enter 由输入框自己处理，这里只留一行日志。
+            diag!(
+                "[agent] Enter on focus={} handled by the composer",
+                self.agent.focus.name()
+            );
+            let _ = catalog;
+        }
+    }
+}

crates/app-iced/src/app/update/agent/tests.rs

@@ -0,0 +1,352 @@
+//! **树测试①（M119 验收核心）**：AI 右栏在**真实 presenter 状态**下渲染。
+//!
+//! 走的是同一条用户路径：`Message::Agent(Submit)` → `AgentHost::submit` → `Presenter::agent_submit`
+//! → transport → 事件队列 → `Message::Agent(Events)` → `Presenter::apply` → `AgentRail`。
+//! **没有一条断言看本地数组**：`transcript` 这类壳自己的会话副本 M119 已经删了，能断言的只剩
+//! presenter 的 rail，而 rail 正是右栏画的东西（`pages/agent::spec` 从它借）。
+//!
+//! 覆盖任务书点名的四件事：
+//!
+//! | 断言 | 抓得住什么 |
+//! |---|---|
+//! | 提交后 rail 出现「你 + 助手」两条、正文来自事件的流式增量 | 提交没接到 presenter、或右栏还在画样本会话 |
+//! | `busy` 翻真 → 收敛后翻假 | 事件没回流、或流式标记没收敛（输入框会永远禁用） |
+//! | 标记已读后未读归零 | `agent_mark_read` 没接、或未读口径没跟着 rail |
+//! | 三种失败都给**具名**横幅 | 失败被吞掉（M104 的「静默无语」）|
+
+use iced::widget::text_editor;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_i18n::{Catalog, Key, Lang};
+use unlucky_presenter::dto::{AgentEvent, AppEvent, ChatRole};
+use unlucky_presenter::mock::MockBackend;
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+use iced::keyboard::key::{Code, Named, Physical};
+use iced::keyboard::{key, Location, Modifiers};
+
+use crate::app::state::presenter::transport::Script;
+use crate::app::state::presenter::AgentHost;
+use crate::app::Message;
+use crate::cli::Options;
+use crate::shell::agent::{Focus, Message as AgentMessage, RailState};
+use crate::theme::Families;
+
+use super::App;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+
+/// 不碰磁盘的 App（mock 后端 + 内存设置桥 + **本脚本的** presenter 句柄）。
+fn app_with(script: Script) -> App {
+    let mut app = App::with_presenter(
+        Options::default(),
+        FAMILIES,
+        SchemeFlavor::Light,
+        Box::new(MockBackend::new()),
+        SettingsBridge::memory_only(),
+    );
+    app.agent_host = AgentHost::with_script(script);
+    // 换句柄 = 可见性还没写回去；`refresh_view` 是那条单点同步
+    app.refresh_view();
+    app
+}
+
+/// 走真消息提交（用户路径：填草稿 → 点发送）。
+fn submit(app: &mut App, text: &str) {
+    app.agent.draft = text_editor::Content::with_text(text);
+    let _ = app.update(Message::Agent(AgentMessage::Submit));
+}
+
+/// **提交 → 事件回流 → 右栏出现这一轮 → 标记已读归零**（任务书第 2 条）。
+///
+/// 抓得住：①`Submit` 没接 `agent_submit`（rail 空）；②事件没经 Message 通道回流（rail 只有半截）；
+/// ③`expand` 没调 `agent_mark_read`（未读不清）；④右栏读的还是壳自己的副本。
+/// 抓不住：气泡在像素上长什么样（那要出图，见 `DevDocs/artifacts/m119/`）。
+#[test]
+fn a_submitted_turn_lands_in_the_rail_and_reading_it_zeroes_unread() {
+    let mut app = app_with(Script::Qa);
+    // 出厂是折叠档 ⇒ presenter 认为「用户没在看着」，到达的助手消息应计未读
+    assert_eq!(app.agent.rail, RailState::Collapsed);
+    assert_eq!(app.agent_host.rail().unread, 0, "空会话没有未读");
+
+    submit(&mut app, "Which instance should I start?");
+
+    let rail = app.agent_host.rail();
+    assert_eq!(
+        rail.messages.len(),
+        2,
+        "一条「你」+ 一条助手（事件产生，不是本地回显）"
+    );
+    assert_eq!(rail.messages[0].role, ChatRole::User);
+    assert_eq!(rail.messages[0].text, "Which instance should I start?");
+    assert_eq!(rail.messages[1].role, ChatRole::Assistant);
+    assert!(
+        rail.messages[1].text.contains("Fabric"),
+        "正文来自流式增量：{:?}",
+        rail.messages[1].text
+    );
+    assert!(!rail.messages[1].streaming, "Qa 脚本会收敛");
+    assert!(!rail.busy, "收敛之后不忙（发送键要能再按）");
+    assert_eq!(rail.unread, 1, "折叠态到达的一条助手消息 = 一条未读");
+
+    // 右栏画的正是这份 rail（`pages/agent::spec` 直接借它）——构图不 panic
+    let _ = app.view();
+
+    // 打开栏 = 读过：`agent_mark_read`
+    let _ = app.update(Message::Agent(AgentMessage::Expand));
+    assert_eq!(app.agent_host.rail().unread, 0, "标记已读后未读归零");
+    assert_eq!(app.agent_host.rail().messages.len(), 2, "已读不改会话");
+}
+
+/// **busy 正确翻转**：流式中忙 → 后端收敛后不忙。
+///
+/// 抓得住：`busy` 还由壳自己算（那它不会跟 rail 走）；`Events` 通道被当成「只追加消息」而丢掉
+/// `MessageFinished`（输入框会永远禁用——这是最要命的坏法之一）。
+#[test]
+fn busy_flips_with_the_backend_events() {
+    let mut app = app_with(Script::Streaming);
+    submit(&mut app, "hello");
+    assert!(app.agent_host.rail().busy, "流式没收敛前输入要禁用");
+
+    // 后端收敛：一条 `MessageFinished` 经同一条 Message 通道回流
+    let index = app.agent_host.rail().messages.len() - 1;
+    let _ = app.update(Message::Agent(AgentMessage::Events(vec![AppEvent::Agent(
+        AgentEvent::MessageFinished { index },
+    )])));
+    assert!(!app.agent_host.rail().busy, "收敛之后必须能再发");
+}
+
+/// 写操作确认：rail 上有待确认 ⇒ 忙；裁决后收敛并记一条审计。
+#[test]
+fn a_pending_write_op_is_visible_and_decidable() {
+    let mut app = app_with(Script::WriteOp);
+    submit(&mut app, "把下载并发改小");
+
+    let rail = app.agent_host.rail();
+    let request = rail.confirm.as_ref().expect("要挂一个待确认请求");
+    assert_eq!(request.tool, "set_config");
+    assert!(
+        rail.busy,
+        "等确认也算忙（否则用户能在一轮写操作中间再发一句）"
+    );
+    let _ = app.view();
+
+    let _ = app.update(Message::Agent(AgentMessage::Confirm(true)));
+    assert!(app.agent_host.rail().confirm.is_none(), "裁决后清空");
+    assert!(!app.agent_host.rail().busy);
+    assert_eq!(app.agent_host.audit_len(), 1, "裁决要进审计（YOLO 下也是）");
+}
+
+/// 失败态①：**AI 端点不可达** ⇒ 具名横幅（不是静默，也不是把后端原文糊上屏）。
+#[test]
+fn an_unreachable_endpoint_shows_a_named_error() {
+    let mut app = app_with(Script::Unreachable);
+    submit(&mut app, "hello");
+
+    let failure = app.agent_failure().expect("提交失败必须给横幅");
+    // 文案跟着**生效语言**走（`LangState` 在这台机器上探到 zh-CN，硬编码英文会假红）
+    let effective = app.lang().catalog();
+    assert_eq!(failure.title, Key::AgentErrorTitle, "标题是 catalog 键");
+    assert_eq!(failure.body, effective.text(Key::AgentErrorUnavailable));
+    assert!(!failure.body.trim().is_empty());
+    assert!(
+        app.agent_host.rail().messages.is_empty(),
+        "失败不产生消息：不许假装有回复"
+    );
+    let _ = app.view();
+}
+
+/// 失败态②：**未实现路由** ⇒ 另一句具名错误（两种失败不能糊成一句）。
+#[test]
+fn an_unimplemented_route_shows_its_own_named_error() {
+    let mut app = app_with(Script::NotImplemented);
+    submit(&mut app, "hello");
+
+    let failure = app.agent_failure().expect("必须给横幅");
+    let effective = app.lang().catalog();
+    assert_eq!(failure.body, effective.text(Key::AgentErrorNotImplemented));
+    // 两条原因码要两句话（中英两套都得分开），不是一句万能错误
+    for lang in [Lang::En, Lang::ZhCn] {
+        let catalog = Catalog::of(lang);
+        assert_ne!(
+            catalog.text(Key::AgentErrorNotImplemented),
+            catalog.text(Key::AgentErrorUnavailable),
+            "{} 下两条原因码糊成一句了",
+            lang.tag()
+        );
+    }
+}
+
+/// 失败态③：**这一轮回复中途断流** ⇒ 横幅用 presenter 已脱敏的那句原因，已到的增量保留。
+#[test]
+fn a_turn_level_failure_keeps_the_partial_answer_and_the_reason() {
+    let mut app = app_with(Script::FailsMidStream);
+    submit(&mut app, "读一下日志");
+
+    let rail = app.agent_host.rail();
+    // 用户 + 助手（流式占位）+ 系统条目（`Failed` 会额外追加一条，错误也要能回翻）
+    assert_eq!(rail.messages.len(), 3, "断流不撤销已到的增量");
+    assert!(
+        rail.messages[1].text.contains("日志"),
+        "已到的增量要留着：{:?}",
+        rail.messages[1].text
+    );
+    assert!(!rail.busy, "断流要收敛掉流式标记");
+    let failure = app.agent_failure().expect("`Failed` 事件要立横幅");
+    assert!(
+        failure.body.contains("read timeout"),
+        "横幅正文是 presenter 脱敏后的原因：{}",
+        failure.body
+    );
+}
+
+/// 输入框的草稿会同步给 presenter（切形态不丢的语义在 presenter 那边）。
+/// **P2-1**：默认配置下后端是脚本化 rig ⇒ 视图必须知道「这是模拟」（界面据此常驻标记）。
+///
+/// 抓得住：`is_simulated` 被写死成 `false`、或者视图拿不到这个事实（用户就会以为模型接上了）。
+/// 抓不住：标记在像素上长什么样（那要出图，见 `DevDocs/artifacts/m119/08-*`）。
+#[test]
+fn the_default_backend_reports_itself_as_simulated() {
+    let app = app_with(Script::Qa);
+    assert!(
+        app.agent_host.is_simulated(),
+        "脚本化 rig 必须自报「模拟」，否则界面就能假装模型接上了"
+    );
+    // 空会话（最容易被误读成一屏）也要能拿到：视图入参 `Session.simulated` 就是它
+    let session = crate::shell::agent::Session {
+        agent: &app.agent,
+        rail: app.agent_host.rail(),
+        failure: app.agent_failure(),
+        simulated: app.agent_host.is_simulated(),
+    };
+    assert!(session.simulated);
+}
+
+#[test]
+fn typing_syncs_the_draft_into_the_presenter() {
+    let mut app = app_with(Script::Qa);
+    app.agent.draft = text_editor::Content::with_text("half typed");
+    let _ = app.update(Message::Agent(AgentMessage::Edit(
+        text_editor::Action::Edit(text_editor::Edit::Insert('!')),
+    )));
+    assert_eq!(
+        app.agent_host.rail().draft,
+        app.agent.draft.text(),
+        "编辑器里是什么，rail 上就该是什么（同一个串，不是它自己的副本）"
+    );
+    assert!(app.agent_host.rail().draft.contains('!'), "改动真的进去了");
+    // 发送成功后草稿两边都清空
+    let _ = app.update(Message::Agent(AgentMessage::Submit));
+    assert!(app.agent.draft_is_blank(), "编辑器清空");
+    assert!(app.agent_host.rail().draft.is_empty(), "presenter 侧也清空");
+}
+
+/// 手搓一条按键事件（订阅层搬过来的就是它；`on_agent_key` 只看 `KeyPressed`）。
+fn press(named: key::Named) -> iced::keyboard::Event {
+    let key = key::Key::Named(named);
+    iced::keyboard::Event::KeyPressed {
+        key: key.clone(),
+        modified_key: key,
+        physical_key: Physical::Code(Code::Enter),
+        location: Location::Standard,
+        modifiers: Modifiers::default(),
+        text: None,
+        repeat: false,
+    }
+}
+
+/// **P2-2 的回归闸**：不碰鼠标、只用键盘消息，能完成一次写操作确认。
+///
+/// 为什么这条重要：确认条原本只有鼠标路径，而待确认时 `busy` 锁着发送、`Stop` 又走主后端
+/// （清不掉 presenter 的 pending）——键盘用户会在这一步**永久卡死**。
+///
+/// 抓得住：①焦点没主动落到确认条（`Enter` 够不着）；②`Enter` / `Space` 没映射成 `Activate`；
+/// ③`Tab` 环里没有确认条那两格；④裁决完焦点没收回输入框（下一句话打不进去）。
+/// 抓不住：焦点环在像素上的样子（那要出图，见 `DevDocs/artifacts/m119/09-*`）。
+#[test]
+fn a_blocking_confirm_can_be_decided_with_the_keyboard_alone() {
+    let mut app = app_with(Script::WriteOp);
+    submit(&mut app, "把下载并发改小");
+    assert!(
+        app.agent_host.rail().confirm.is_some(),
+        "先要有一个待确认请求"
+    );
+    // ① 焦点主动落在「允许」（阻塞态），但**键盘闸不替用户打开**（复审 r2 / P2-2）
+    assert_eq!(
+        app.agent.focus,
+        Focus::ConfirmAllow,
+        "焦点要落在可操作元素上"
+    );
+    assert!(
+        !app.agent.keyboard_mode,
+        "塔台 r2：不许自动 arm——自动 arm 会让用户随手敲的空格变成「批准」"
+    );
+
+    // ② 第一次 Tab = 「我要用键盘」的表态：只点亮焦点环，**不移动**焦点
+    let _ = app.update(Message::Agent(AgentMessage::Tab { shift: false }));
+    assert!(app.agent.keyboard_mode, "Tab 之后才算 armed");
+    assert_eq!(
+        app.agent.focus,
+        Focus::ConfirmAllow,
+        "arming 的那一次不移动焦点（否则 Enter 会反着裁决）"
+    );
+
+    // ③ Enter = 允许
+    let _ = app.update(Message::Agent(AgentMessage::Key(press(Named::Enter))));
+    assert!(
+        app.agent_host.rail().confirm.is_none(),
+        "Enter 必须真的裁决掉"
+    );
+    assert_eq!(app.agent_host.audit_len(), 1, "裁决进审计");
+    assert_eq!(app.agent.focus, Focus::Composer, "裁决完焦点收回输入框");
+    assert!(!app.agent.keyboard_mode, "阻塞态结束就不再亮焦点环");
+
+    // ④ 第二轮走「Tab 点环 → Tab 走到拒绝 → Space 触发」：键盘用户不必背 Enter 是哪一个
+    submit(&mut app, "那把并发改回来");
+    assert_eq!(app.agent.focus, Focus::ConfirmAllow);
+    let _ = app.update(Message::Agent(AgentMessage::Tab { shift: false }));
+    let _ = app.update(Message::Agent(AgentMessage::Tab { shift: false }));
+    assert_eq!(app.agent.focus, Focus::ConfirmDeny, "Tab 要能走到「拒绝」");
+    let _ = app.update(Message::Agent(AgentMessage::Key(press(Named::Space))));
+    assert!(app.agent_host.rail().confirm.is_none(), "Space 也要能裁决");
+    assert_eq!(app.agent_host.audit_len(), 2);
+}
+
+/// **复审 r2 / P2-2 的反向回归**：没 armed 的时候，空格与回车都不许裁决写操作。
+///
+/// 复审用临时用例复现的路径：WriteOp 提交后（r1 无条件 arm），用户接着打下一句，第一个空格就成了
+/// 「允许」。真实场景里编辑器仍持 iced 焦点，所以这条不是理论问题。
+///
+/// 抓得住：谁把 `sync_confirm_focus` 里的 `keyboard_mode = true` 加回来；谁把 `Space`/`Enter` 的
+/// `Activate` 绕到 `keyboard_mode` 闸之外。
+/// 抓不住：iced 组件树里空格到底有没有进输入框（那要真窗口，出图另算）——这里只断言「没裁决」。
+#[test]
+fn a_stray_space_or_enter_never_approves_a_pending_write() {
+    let mut app = app_with(Script::WriteOp);
+    submit(&mut app, "把下载并发改小");
+    assert!(app.agent_host.rail().confirm.is_some());
+    assert!(!app.agent.keyboard_mode, "待确认不该自动 arm");
+
+    // 用户接着打下一句：先敲一个字符（编辑器自己消化），再敲空格
+    let _ = app.update(Message::Agent(AgentMessage::Edit(
+        text_editor::Action::Edit(text_editor::Edit::Insert('a')),
+    )));
+    let _ = app.update(Message::Agent(AgentMessage::Key(press(Named::Space))));
+    assert!(
+        app.agent_host.rail().confirm.is_some(),
+        "未 armed 时空格不许批准写操作"
+    );
+    assert_eq!(app.agent_host.audit_len(), 0, "也不许留下审计");
+
+    // 回车同理：未 armed 时它归编辑器（发送键），不归确认条
+    let _ = app.update(Message::Agent(AgentMessage::Key(press(Named::Enter))));
+    assert!(
+        app.agent_host.rail().confirm.is_some(),
+        "未 armed 时回车不许批准写操作"
+    );
+    assert_eq!(app.agent_host.audit_len(), 0);
+}

crates/app-iced/src/app/update/appearance.rs

@@ -0,0 +1,82 @@
+//! M116：窗口圆角的下发落点（`impl App::apply_window_corner`）。
+//!
+//! ## 为什么单独成文件
+//!
+//! 圆角与整窗 α 是**两条独立的管线**，只是都必须拿到 HWND、都在同一个时点下发：
+//!
+//! | 管线 | 判据 | 落点 | 键 |
+//! |---|---|---|---|
+//! | 整窗 α（D36） | `platform::effective_window_alpha` | `SetLayeredWindowAttributes` | `appearance.window_opacity` |
+//! | 圆角（M116） | `platform::plan_corner` | `DwmSetWindowAttribute` | `appearance.window_corner` |
+//!
+//! 合在一个函数里会让「α 变了要不要重设圆角」这种问题变成实现细节；分开之后两个判据各自可测。
+//!
+//! ## 日志为什么是**一行、六栏**
+//!
+//! `corner=policy=… source=dwm|square os=… excluded_reason=… radius=system pref=… readback=… frame=… layered=…`
+//!
+//! 用户报的现象是「别的窗口都有圆角，只有我们的没有」。没有这一行，事后无法区分
+//! 「没生效」「生效了但看不见」「这台系统根本没有这个能力」；`frame` / `layered` 两栏则是
+//! 「圆角为什么不生效」的两个现场读数：`frame=`（窗口形状）与 `layered=`（整窗 α 引入的分层位）。
+//!
+//! ⚠️ **产品窗口不是 `WS_POPUP`**（M116 r4 复审订正）：winit 在 `decorations = false` 下给的是
+//! `WS_CAPTION|WS_BORDER|WS_CLIPSIBLINGS|WS_SYSMENU`（可缩放时再加 `WS_THICKFRAME` 与 min/max 键），
+//! `WS_POPUP` 只在**带 owner** 的弹出窗才加；无边框观感来自 `WM_NCCALCSIZE` 把客户区铺满。
+//! 所以真进程日志里 `frame=` 应是 `overlapped`（关掉 min/max 则 `other`），**永远不会是 `popup`**。
+//! 真正让系统忽略圆角请求的是**整窗 α 补的 `WS_EX_LAYERED`**（`layered=on`）。
+//!
+//! `radius=system` 是刻意的：系统不暴露 DWM 的圆角半径，我们也不自己定一个数字
+//! （M116 取消了 8/12/16 固定档）。
+
+use crate::app::diag::diag;
+use crate::platform;
+use crate::platform::win32::corner::{self, CornerApplied};
+use crate::platform::win32::transparency::{apply_corner, style_summary, CornerOutcome};
+
+use super::super::state::App;
+
+impl App {
+    /// 把当前圆角策略下发到窗口，并打一行可分辨的日志。
+    ///
+    /// ## 去重（M116 r1 复审 P2-4）
+    ///
+    /// 设置页的滑条（整窗 α / 面板 α / 暗化）每动一下都会走一次外观变更，而<b>圆角与那些键无关</b>。
+    /// 判定完全没变时这里**直接返回**：不动窗口、不打日志。判据是
+    /// [`corner::needs_redispatch`]（纯函数，有「同一策略 N 次只记 1 行」的测试），
+    /// 指纹只含「策略 / 来源 / 原因码 / 有没有句柄」，不含只有真下发才拿得到的读数。
+    ///
+    /// 没有句柄时**也打日志**（`window=none`）：不能让「没生效」只体现为屏幕上没变化。
+    /// 句柄从无到有会让指纹变化 ⇒ 首次拿到 HWND 时必然重下一次。
+    pub(crate) fn apply_window_corner(&mut self, context: &str) {
+        let policy = self.appearance.window_corner();
+        let plan = platform::plan_corner(
+            policy,
+            platform::current_windows_version(),
+            self.appearance.backend,
+        );
+        // 整窗 α < 1 ⇒ `window_alpha::dispatch` 会给窗口补 `WS_EX_LAYERED`；系统因此忽略圆角请求
+        // （tower 裁定 A / D47）。这里只记**事实**：α 是否把我们自己的分层位打开了。
+        let alpha_layered = self.appearance.window_opacity < 1.0;
+        let suppressed_by = alpha_layered.then_some("window_alpha");
+        let next = CornerApplied::new(policy, &plan, self.hwnd.is_some(), alpha_layered);
+        if !corner::needs_redispatch(self.corner_applied.as_ref(), &next) {
+            return;
+        }
+        self.corner_applied = Some(next);
+
+        // 行的形状只有一处（`corner::format_line`），因为那里能在没有窗口的环境里被单测钉住。
+        // 关键的三栏必须在同一行：`pref=`（请求发出去了）、`layered=`（分层位在不在，来自
+        // 整窗 α）、`frame=`（窗口形状 = `overlapped`，不是 `popup`）——否则以后只能猜是哪一条。
+        let (outcome, style) = match self.hwnd {
+            Some(hwnd) => (apply_corner(hwnd, &plan).describe(), style_summary(hwnd)),
+            None => (
+                CornerOutcome::NoWindow.describe(),
+                "frame=? layered=?".to_owned(),
+            ),
+        };
+        diag!(
+            "{}",
+            corner::format_line(context, &plan, policy, &outcome, &style, suppressed_by)
+        );
+    }
+}

crates/app-iced/src/app/update/boot_env.rs

@@ -0,0 +1,173 @@
+//! 启动期的取证环境变量解析（`ULL_START_ROUTE` / 动效三个开关）。
+//!
+//! 从 `app/update.rs` 原样搬出（那个文件在 M105/M106/M109/M113 之后贴着 400 行硬线）：
+//! **纯函数、无状态**，只是取值表长到了十条。M192 在这里加的是动效那一组
+//! （[`motion_scale`] / [`env_motion_pin`] / [`env_motion_fixture`]）：档位策略只有这一处，
+//! 帧泵自己不读环境变量。
+
+use unlucky_design::motion::MotionScale;
+use unlucky_presenter::router::Route;
+
+/// 取证开关 `ULL_START_ROUTE` 的取值解析（`settings` / `instances` / `download` / `content` / `logs`）。
+///
+/// 为什么是环境变量：`crates/app-iced/src/cli.rs` 不在 M93 的 scope，而外观矩阵必须在**设置页**上
+/// 出图。语义与 `ULL_APPEARANCE_*` / `ULL_TICK_TRACE` 一致：只影响这一次进程。
+pub(super) fn env_start_route() -> Option<Route> {
+    match std::env::var("ULL_START_ROUTE").ok()?.trim() {
+        "instances" => Some(Route::Instances),
+        "download" => Some(Route::Download),
+        "logs" => Some(Route::Logs),
+        "settings" => Some(Route::Settings),
+        // M104：AI 独立页也要能直达（三态矩阵的 Detached 那张）
+        "agent" => Some(Route::Agent),
+        // M109：内容库（截图矩阵要能直达；页面内的四条侧栏不在路由里）
+        "content" => Some(Route::Content),
+        // M114：账户页的 D30 矩阵要能直达（`cli.rs` 不在本 mission 的 scope）
+        "accounts" => Some(Route::Accounts),
+        _ => None,
+    }
+}
+
+/// 动效档位与相位钉住（M192）：帧泵**只在产品的 `on_boot` 里定档**。
+///
+/// ## 为什么档位在这里算
+///
+/// 三个输入只有启动这一拍齐全：①是不是截图通道（`--screenshot`）②实际渲染后端
+/// （`backend::effective_kind()`，不是 `--renderer` 的请求值）③`ULL_MOTION` 的强制值。
+/// 帧泵自己（`components::motion`）不读环境变量，它只接受一个 [`MotionScale`]——这样动效策略
+/// 只有一处，测试也不必摆环境变量。
+///
+/// | 条件 | 档位 | 为什么 |
+/// |---|---|---|
+/// | `ULL_MOTION=off` | `NONE` | 一键关（排障 / 想量基线时用） |
+/// | 截图通道，且没给 `ULL_MOTION_AT` | `NONE` | D30：出图不许有动画（否则第 3 帧抓到中间态，图就不可复现） |
+/// | CPU 渲染（`tiny-skia`） | `HALF` | 时长减半 = 帧数减半。位移是**布局量**，CPU 档最贵的就是逐帧重排 |
+/// | 其余（`wgpu`） | `STANDARD` | —— |
+/// | `ULL_MOTION=half` / `full` | 强制 | 覆盖上表（出图矩阵要在 GPU 上量同一段动效） |
+///
+/// 「减少动效」的用户开关**还不存在**（`core/src/setting` 里没有 animation key，见报告 follow-up），
+/// 所以本函数只认上面这些来源。
+pub(super) fn motion_scale(screenshot: bool, gpu: bool, pinned: bool) -> MotionScale {
+    match std::env::var("ULL_MOTION").ok().as_deref().map(str::trim) {
+        Some("off") | Some("none") => return MotionScale::NONE,
+        Some("half") => return MotionScale::HALF,
+        Some("full") => return MotionScale::STANDARD,
+        _ => {}
+    }
+    if pinned {
+        // 取证相位优先于「截图必须静」，否则多帧序列图一张都出不来。
+        return MotionScale::STANDARD;
+    }
+    if screenshot {
+        return MotionScale::NONE;
+    }
+    if gpu {
+        MotionScale::STANDARD
+    } else {
+        MotionScale::HALF
+    }
+}
+
+/// `ULL_MOTION_AT=<ms>`：把动画时钟钉在某一毫秒（多帧序列图取证）。
+///
+/// 语义与 `ULL_APPEARANCE_*` / `ULL_DIALOG_FIXTURE` 一致：只影响这一次进程。没有它，第 3 帧落在
+/// 动画的哪个相位取决于这台机器的渲染速度 —— 那样「0% / 50% / 100% 三张图」是抓阄抓出来的。
+pub(super) fn env_motion_pin() -> Option<f64> {
+    std::env::var("ULL_MOTION_AT")
+        .ok()?
+        .trim()
+        .parse::<f64>()
+        .ok()
+        .filter(|ms| ms.is_finite() && *ms >= 0.0)
+}
+
+/// `ULL_MOTION_FIXTURE`：第 1 帧之后**真的**做一次状态变化（多帧序列图靠它）。
+///
+/// 为什么要制造变化：页面主体的入场只在「内容标识变了」时起跑（`motion::observe`），而截图通道
+/// 从第一帧起画的就是同一页——不制造一次真实的路由变化，就没有可拍的动效。
+#[derive(Debug, Clone)]
+pub(super) enum MotionFixture {
+    /// 跳到一个一级页（走「换页」那一档）。
+    Route(Route),
+    /// 「列表 → 详情」：先回列表（第 1 帧），再点进第一条实例（第 2 帧）。
+    Detail,
+}
+
+/// `ULL_MOTION_FIXTURE=<instances|download|logs|settings|content|detail>`。
+pub(super) fn env_motion_fixture() -> Option<MotionFixture> {
+    Some(match std::env::var("ULL_MOTION_FIXTURE").ok()?.trim() {
+        "instances" => MotionFixture::Route(Route::Instances),
+        "download" => MotionFixture::Route(Route::Download),
+        "logs" => MotionFixture::Route(Route::Logs),
+        "settings" => MotionFixture::Route(Route::Settings),
+        "content" => MotionFixture::Route(Route::Content),
+        "detail" => MotionFixture::Detail,
+        _ => return None,
+    })
+}
+
+/// `ULL_MOTION_FIXTURE_AT=<秒>`：启动后第 N 次心跳（≈第 N 秒）**真的**导航一次。
+///
+/// ## 为什么需要它（真机空闲取证）
+///
+/// 复审 r1 要求「空闲 ≥10 s 后点一次导航轨，看 `[tick] motion=` 涨多少」。本机工作区所在会话
+/// 没有前台窗口（`GetForegroundWindow()==0`），合成鼠标事件（`mouse_event` 与
+/// `PostMessage(WM_LBUTTONDOWN)` 都试过）递不进 iced 的输入层，所以这里换一条**同构**的路：
+/// 由 1 Hz 心跳（空闲态本来就有的消息）在第 N 秒做一次真实的路由跳转。
+///
+/// 两条路在 `update` 之后**完全同一段代码**：消息 → `sync_motion`（起跑）→ `subscription()`
+/// （同一拍看见轨道）→ `frames()`。差别只在「消息是谁产生的」，而这正是 P1 要验的那一段。
+pub(super) fn env_motion_fixture_at() -> Option<u32> {
+    std::env::var("ULL_MOTION_FIXTURE_AT")
+        .ok()?
+        .trim()
+        .parse::<u32>()
+        .ok()
+        .filter(|beats| *beats > 0)
+}
+
+/// 把启动那一拍的**事实**写进启动器自己的日志（M187 / r1 复审 P2-4）。
+///
+/// ## 为什么这一拍只能「先记、后落」
+///
+/// `.ULL/logs` 的落点由 `platform::data_dir` 的三模式决定（要读配置、follow `redirect.json`），
+/// 那件事只有 presenter 的 `HostEnv` 做过。app 层拿不到它，于是这里只 `record`
+/// （core 侧缓冲，最多 200 行）；presenter **构造 `HostEnv` 的那一刻**就调
+/// `launcher_log::set_dir`（M188 补上的那一半），缓冲一次刷进 `<.ULL>/logs/launcher.log`。
+///
+/// 效果正是用户投诉要的那份东西：他「双击 → 启动 → 崩 → 找日志」时，`launcher.log` 里从
+/// **启动这一拍**（主题 / 语言 / 路由 / 窗口 / 后端）一直写到退出，而不是只有 launch 那一段。
+///
+/// M188 之后边界也变了：`boot.rs` / `boot/fallback.rs` / `state/*` 那些 `eprintln!` 改走
+/// [`crate::app::diag::emit`]（stderr + 文件双写），同样靠这条缓冲接住——所以「一局都没开就崩」
+/// 的进程也会留下 `launcher.log`。
+pub(crate) fn record_boot_log(app: &super::super::state::App) {
+    use unlucky_core::launch::launcher_log;
+
+    launcher_log::record("boot", "app boot");
+    launcher_log::record(
+        "boot",
+        &format!(
+            "theme={} lang={:?} route={:?} window={:.0}x{:.0} screenshot={} instances={}",
+            app.ui().name(),
+            app.lang(),
+            app.state.route(),
+            app.width,
+            app.height,
+            app.has_screenshot(),
+            app.state.instances.len(),
+        ),
+    );
+    launcher_log::record("boot", &unlucky_cli::commands::msa_client_id_log_line());
+    // 后端这一拍也要在日志里：`[probe]` / `[backend]` 那几行由 `renderer::acceptance` 打到
+    // stderr（那个模块不在 M188 的 scope），事故之后翻日志的人至少要看得出「这次用的是哪个后端」。
+    launcher_log::record(
+        "boot",
+        &format!(
+            "backend request={} effective={} renderer_fallback={}",
+            app.options.backend.name(),
+            super::super::backend::effective_backend(app.options.backend).name(),
+            std::env::var(crate::renderer::FALLBACK_ENV).unwrap_or_else(|_| "-".to_string()),
+        ),
+    );
+}

crates/app-iced/src/app/update/clock.rs

@@ -0,0 +1,184 @@
+//! 节拍：推进一拍 / 派发指令 / 抽干事件（M119 从 `update.rs` 拆出来守 400 行硬线；纯搬不改）。
+//!
+//! ## 为什么这三件必须在一起
+//!
+//! `advance` → `pump` → `apply` → `refresh_view` 是同一条链：时间推进、事件抽干、状态落地、
+//! 视图重建。拆开看每一段都无害，合起来才是「presenter 的异步事件在 UI 侧怎么被消费」的答案。
+//!
+//! ## 两个时钟的相位（M90 r3 / P2-2 的老账，代码里有细节）
+//!
+//! | 场景 | 时钟 | 周期 |
+//! |---|---|---|
+//! | 截图 / 有 Busy-Running 实例 / 有 toast / 派发后 3 s 观察窗 | `window::frames()` + 闸门 | 33 ms |
+//! | 其余（空闲） | `Heartbeat` 自续链 | 1 s |
+//!
+//! ## M119 增加了什么
+//!
+//! [`App::pump`] 里多了一行 [`App::drain_agent`]：AI 助手的事件队列和 core 的事件队列同拍抽干，
+//! 于是「右栗的未读/流式状态」和页面快照共享同一个刷新节奏（不会一个 30 Hz、一个 1 Hz）。
+
+use crate::app::diag::diag;
+use std::time::{Duration, Instant};
+
+use unlucky_presenter::dto::AppCommand;
+use unlucky_presenter::theme::CONFIG_POLL_TICKS;
+
+use super::super::state::TICK_MS;
+use super::*;
+
+impl App {
+    /// 推进一拍：后端消化时间 → 抽干事件 → 过期 toast → 偶发重读配置文件。
+    ///
+    /// `elapsed` 是真实流逝时间（毫秒级抖动是正常的：`MockBackend` 的脚本按累计时长走）。
+    pub(in crate::app) fn advance(&mut self, elapsed: Duration) {
+        self.backend.tick(elapsed);
+        self.pump();
+
+        self.state
+            .toasts
+            .expire(u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX));
+
+        // 设备码/授权码的倒计时（M114）：等待态每秒都要重画一次，否则「剩 900s」永远不动，
+        // 用户会以为卡死了——这正是任务里「不得只转圈」的那一条。
+        if self.state.device_login.phase == unlucky_presenter::dto::DeviceLoginPhase::Waiting {
+            self.view_dirty = true;
+        }
+        // 中文字体下载（M168）：后台线程推进，这里只比对快照。变了就重建视图模型 ⇒ 设置页那一行
+        // 从「正在获取中文字体…（16.9 MB）」翻到「已就绪 / 获取失败」，不需要用户再点一下。
+        let font_status = crate::fonts::install::status();
+        if font_status != self.font_seen {
+            self.font_seen = font_status;
+            self.view_dirty = true;
+        }
+        // Java 扫描（M175）：同一条「后台线程 + 快照」路数。进度（3/7）与结论都在里面，
+        // 扫描期间按帧跑（见 `subscription::needs_frames`），扫完回到 1 Hz。
+        self.hydrate_java_scan();
+        // `ticks` 的单位是**33 ms 的一拍**，不是「advance 被调了几次」：空闲心跳一次跨 1 s，
+        // 要记 30 拍，这样 `theme::config_poll_due`（30 拍 ≈ 1 秒）在两种时钟下语义一致。
+        let ticks = elapsed.as_millis().div_euclid(u128::from(TICK_MS));
+        let ticks = u64::try_from(ticks).unwrap_or(u64::MAX).max(1);
+        let bucket_before = self.ticks / 30;
+        self.ticks += ticks;
+        let bucket_after = self.ticks / 30;
+
+        // 外部（AI / CLI）改了配置文件：主题跟着换，其余外观项等玻璃/背景 mission。
+        //
+        // 判据用**跨越**而不是 presenter 的 `config_poll_due(ticks)`（整除）：两个时钟的相位不同
+        // （帧节拍按 33 ms 累加、空闲心跳按 30 拍累加），整除判定一旦错过一次就**再也命中不了**
+        // ——实测 ticks=137 之后每拍 +30 永远不整除，配置轮询静默死掉。间隔真源仍是
+        // `CONFIG_POLL_TICKS`（30 拍 × 33 ms ≈ 1 秒）。截图通道不轮询（D30 可复现）。
+        let poll_due = self.ticks >= self.config_due_at;
+        if poll_due {
+            // 追到「当前 ticks 之后的第一个间隔点」，避免心跳把相位拖飞
+            self.config_due_at = self.ticks + CONFIG_POLL_TICKS;
+        }
+        let reloaded =
+            !self.has_screenshot() && poll_due && self.bridge.reload_if_changed().is_some();
+        if reloaded {
+            diag!("[settings] 配置文件变了，重读主题 + 外观");
+            self.apply_config_theme();
+            // M93：外观也热切（面板 α / 背景图 / 配色来源 / 整窗 α 都在里面）。
+            self.reload_appearance();
+            // M174：助手那四项也一样（`ull config set ai.* …` 改完 1 秒内可见；脏草稿不覆盖）。
+            self.hydrate_ai_settings();
+            // M175：Java 三键同理（外部改了内存 / JVM 参数 / 默认 JDK，设置页 1 秒内跟上）。
+            self.hydrate_java_settings();
+        }
+
+        if self.view_dirty {
+            self.refresh_view();
+        }
+
+        // 取证开关（`ULL_TICK_TRACE=1`）：每跨过 30 拍（≈1 秒）打一行。
+        // 忙碌态由帧节拍跨桶（≈1 行/秒），空闲态由心跳一次 +30 跨桶（**也是 1 行/秒**）——
+        // 两种时钟都用同一把尺子，所以 trace 的密度本身就是「时钟在跑」的证据。
+        if bucket_after != bucket_before && std::env::var_os("ULL_TICK_TRACE").is_some() {
+            diag!(
+                "[tick] n={} frames={} refreshes={} clock={} motion={}",
+                self.ticks,
+                self.frames,
+                self.refreshes,
+                if self.needs_frames() {
+                    "frames"
+                } else {
+                    "idle-1hz"
+                },
+                // M192：动效时间轴已结算的帧数（每秒一行 ⇒ 这一列的增长速度就是动画的实际帧率，
+                // 也是「动画期间重绘成本」的记账口径，见报告）
+                crate::app::components::motion::samples()
+            );
+        }
+    }
+
+    /// 派发一条指令并**立刻**抽干它带出来的事件（不本地回显，等价于 Slint 版的 `dispatch`）。
+    pub(in crate::app) fn dispatch(&mut self, command: AppCommand) {
+        self.backend.dispatch(command);
+        // 观察窗：命令发出后 3 秒内保持帧订阅，等后端把第一条事件交回来
+        // （真 host 是异步的，派发瞬间状态还没变；不设这个窗口，空闲态的帧订阅永远不会打开）。
+        self.watch_until = Some(Instant::now() + WATCH_WINDOW);
+        self.pump();
+    }
+
+    /// 抽干事件队列并逐条 `apply`（**唯一**的状态写入口）。
+    pub(in crate::app) fn pump(&mut self) {
+        // M119：AI 助手的事件队列与 core 的事件队列**同拍**抽干（顺序无关：两个队列互不依赖）。
+        // 抽出来的这批事件经 `Message::Agent(Events)` 回流，见 `update/agent.rs`。
+        self.drain_agent();
+
+        let events = self.backend.drain_events();
+        if events.is_empty() {
+            return;
+        }
+        let mut clean_scan = false;
+        for event in events {
+            // M160：预检之后**没有冲突**就不打扰用户——直接带着"全部保留"往下导。
+            if matches!(
+                &event,
+                unlucky_presenter::dto::AppEvent::Core(unlucky_presenter::dto::CoreEvent::Pack(
+                    pack
+                )) if matches!(&**pack, unlucky_presenter::dto::PackEvent::Scan(scan) if scan.is_clean())
+            ) {
+                clean_scan = true;
+            }
+            // M223：导入向导「在等回程」只认事件到达（派发时置位、这里解除），
+            // 于是连点「确认」不会写两条实例记录，界面也不会一直转圈。
+            let settled_adopt = matches!(
+                &event,
+                unlucky_presenter::dto::AppEvent::Core(unlucky_presenter::dto::CoreEvent::Adopt(_))
+            );
+            self.state.apply(event);
+            if settled_adopt {
+                self.settle_adopt();
+            }
+        }
+        self.view_dirty = true;
+        self.auto_select();
+        self.refresh_view();
+        // 派发放在循环之后：`dispatch` 自己会再 pump 一次，在循环里调会把事件顺序搅乱。
+        if clean_scan {
+            self.continue_import_after_clean_scan();
+        }
+    }
+
+    /// 首屏快照到位后**自动选中第一行**（桌面 list-detail 的惯例：右栏不该开局就是空的）。
+    ///
+    /// 只做一次：用户点「返回」回到列表后，再刷新实例列表也不会把他弹回详情页。
+    /// 选中这件事走的是 `AppState::navigate`（路由栈），不是本地选中字段——于是「当前选中」
+    /// 永远等于「路由栈顶」，用户点返回时栈语义自然成立。
+    pub(in crate::app) fn auto_select(&mut self) {
+        if self.auto_selected || self.state.route() != &Route::Instances {
+            return;
+        }
+        let Some(first) = self
+            .state
+            .tiles()
+            .first()
+            .map(|cell| cell.instance.id.clone())
+        else {
+            return;
+        };
+        self.auto_selected = true;
+        self.state.navigate(Route::Detail(first));
+        self.view_dirty = true;
+    }
+}

crates/app-iced/src/app/update/content.rs

@@ -0,0 +1,238 @@
+//! 内容库页的消息落点（M109）：`pages::Message::Content(..)` 的穷尽分发。
+//!
+//! ## 两件事分开（与 `update/download.rs` 同一条纪律）
+//!
+//! | 意图 | 谁改状态 | 派指令吗 |
+//! |---|---|---|
+//! | 关键词草稿 / 选中项目 / 目标实例 | `App::content`（页面内选择） | 不派 |
+//! | 检索条件（类型/来源/排序/版本/加载器/关键词提交/翻页/重试） | `AppState::content`（presenter） | 派 `SearchContent` |
+//! | 装入 | 谁都不改 | 派 `InstallContent` |
+//!
+//! 「装入」不改本地状态是关键：装上的证据是 `InstallProgress` 事件回流到安装面板
+//! （`pages/download::install_panel`），页面自己不做乐观回显。
+//!
+//! ## 为什么条件写进 presenter 再派
+//!
+//! `AppState::content.query` 是「当前结果对应哪份条件」的唯一真相：结果回来时
+//! `apply_content` 用它判「迟到的事件要不要丢」。页面自己存一份就会有两份真相。
+
+use crate::app::diag::diag;
+use unlucky_presenter::dto::{
+    AppCommand, ContentDetailRequest, ContentInstallRequest, ContentQuery, ContentSource,
+    ExportRequestView,
+};
+
+use crate::pages::content::{Blocker, Content};
+
+use super::*;
+
+impl App {
+    /// 进入内容库页时补一次检索（首个用户动作不该是「再点一下搜索」）。
+    ///
+    /// 判据是 `AppState::content` 里还没有结果、也没有请求在飞：重复进出不重复打网络。
+    pub(super) fn ensure_content_loaded(&mut self) {
+        if self.state.content.results.is_some() || self.state.content.pending {
+            return;
+        }
+        let query = ContentQuery::first(self.content.kind);
+        self.search_content(query);
+    }
+
+    /// 页面消息（穷尽分发：漏一支报 E0004）。
+    pub(super) fn on_content(&mut self, message: pages::content::Message) -> Task<Message> {
+        match message {
+            pages::content::Message::SetKind(kind) => {
+                // 换类型 = 换一份条件（facet 全变）：选中项作废，条件回到该类型的首页
+                self.content.kind = kind;
+                self.content.selected = None;
+                let mut query = ContentQuery::first(kind);
+                // 保留用户已经选好的来源/排序/版本/加载器：换成默认值会让筛选条自己跳回去
+                query.source = self.state.content.query.source;
+                query.sort = self.state.content.query.sort;
+                query.game_version = self.state.content.query.game_version.clone();
+                query.loader = self.state.content.query.loader;
+                self.search_content(query);
+            }
+            pages::content::Message::QueryChanged(text) => {
+                self.content.draft = text;
+                self.view_dirty = true;
+            }
+            pages::content::Message::Search => {
+                let mut query = self.state.content.query.clone();
+                query.text = self.content.draft.trim().to_string();
+                query.offset = 0;
+                self.search_content(query);
+            }
+            pages::content::Message::SetSource(source) => {
+                if source == ContentSource::Curseforge && !self.curseforge_available() {
+                    // 筛选条那条本来就是禁用的；这里再挡一次（防绕过 UI 的消息）
+                    return Task::none();
+                }
+                self.with_query(|query| query.source = source);
+            }
+            pages::content::Message::SetSort(sort) => self.with_query(|query| query.sort = sort),
+            pages::content::Message::SetVersion(version) => {
+                self.with_query(|query| query.game_version = version);
+            }
+            pages::content::Message::SetLoader(loader) => {
+                self.with_query(|query| query.loader = loader)
+            }
+            pages::content::Message::Select(id) => {
+                // M162：选中就拉这个项目的详情/版本列表（一条独立通道，失败只影响详情面板）
+                self.content.selected = Some(id.clone());
+                self.state.content.request_detail(&id);
+                if let Some(request) = self.content_detail_request() {
+                    self.dispatch(AppCommand::LoadContentDetail(Box::new(request)));
+                }
+                self.view_dirty = true;
+            }
+            pages::content::Message::SetTarget(id) => {
+                self.content.target = Some(id);
+                self.view_dirty = true;
+            }
+            pages::content::Message::LoadMore => {
+                let next = self.state.content.query.next_page();
+                self.search_content(next);
+            }
+            pages::content::Message::Retry => {
+                let mut query = self.state.content.query.clone();
+                query.offset = 0;
+                self.search_content(query);
+            }
+            pages::content::Message::Install => {
+                if let Some(request) = self.content_install_request() {
+                    self.dispatch(AppCommand::InstallContent(Box::new(request)));
+                }
+            }
+            // M191：「只重试上次失败的那几项」。请求构造在 `pages/content/model.rs`
+            // （`retry_install_request`：载荷带 `retry: true`），这里只做转发。
+            pages::content::Message::RetryFailed => {
+                let catalog = unlucky_i18n::Lang::En.catalog();
+                let model = Content::from_snapshot(&self.state, &self.content, catalog);
+                if let Some(request) = model.retry_install_request() {
+                    self.dispatch(AppCommand::InstallContent(Box::new(request)));
+                }
+            }
+            // M113: import/export —— 导入/导出区（细节在 `on_pack`）
+            pages::content::Message::Pack(message) => self.on_pack(message),
+        }
+        Task::none()
+    }
+
+    /// 组一份导出请求（预检与写盘**共用同一份**，确认时原样发回）。
+    ///
+    /// 没有选中实例就没有导出对象 ⇒ `None`。**「Save to」必须真的进请求**
+    /// （复审 r1 P1-1：以前这里硬编码 `target: None`，那个输入框是死的）。
+    pub(super) fn pack_export_request(&self) -> Option<ExportRequestView> {
+        let instance = self.content.pack.instance.clone()?;
+        Some(pages::content::request_export(
+            &self.content.pack,
+            &instance,
+        ))
+    }
+
+    /// 拖入一个文件/目录（`app/update.rs` 的窗口事件转发到这里）。
+    pub(super) fn on_pack_dropped(&mut self, path: std::path::PathBuf) -> Task<Message> {
+        // 拖入是「现在就要看到结果」的动作：先把用户带到内容库页，再落草稿
+        self.state
+            .navigate(unlucky_presenter::router::Route::Content);
+        self.on_pack(pages::content::PackMessage::Dropped(path));
+        self.refresh_view();
+        Task::none()
+    }
+
+    /// 拖拽悬停状态（有文件在窗口上方时高亮入口）。
+    pub(super) fn on_pack_hover(&mut self, hover: bool) -> Task<Message> {
+        // 状态没变就不重画：winit 对同一批文件会连发几次 hover 事件
+        let changed = self.content.pack.hover != hover;
+        self.on_pack(pages::content::PackMessage::Hover(hover));
+        if changed {
+            self.refresh_view();
+        }
+        Task::none()
+    }
+
+    /// 改一个筛选字段并**立刻重查**（第一页）。
+    fn with_query(&mut self, change: impl FnOnce(&mut ContentQuery)) {
+        let mut query = self.state.content.query.clone();
+        change(&mut query);
+        query.offset = 0;
+        self.search_content(query);
+    }
+
+    /// 提交一次检索：条件先落进 presenter（迟到事件的判据），再派指令。
+    fn search_content(&mut self, query: ContentQuery) {
+        self.state.set_content_query(query.clone());
+        self.view_dirty = true;
+        self.dispatch(AppCommand::SearchContent(query));
+    }
+
+    /// CF 源可用吗（结果里带回的那一位；还没拉过 ⇒ `false`）。
+    fn curseforge_available(&self) -> bool {
+        self.state
+            .content
+            .results
+            .as_ref()
+            .is_some_and(|results| results.curseforge)
+    }
+
+    /// 详情的请求载荷（选中项 + 目标实例的版本/加载器；没有选中项就没有请求）。
+    ///
+    /// 详情是**独立通道**：检索结果里只有 facets（支持哪些版本/加载器），拿不到「有哪些版本
+    /// 可以装」；跟着检索一起拉等于每页多 N 次请求，所以只在选中时发一条。
+    fn content_detail_request(&self) -> Option<ContentDetailRequest> {
+        let catalog = unlucky_i18n::Lang::En.catalog();
+        let model = Content::from_snapshot(&self.state, &self.content, catalog);
+        let hit = model.selected_hit()?;
+        let target = model
+            .targets
+            .iter()
+            .find(|target| Some(&target.id) == model.target.as_ref());
+        Some(ContentDetailRequest {
+            project: hit.id.clone(),
+            source: hit.source,
+            game_version: target.map(|target| target.mc_version.clone()),
+            loader: target.map(|target| target.loader),
+        })
+    }
+
+    /// 组一份内容库的「装入」请求；闸门与页面上的按钮**同一个判据**（`Content::can_install`）。
+    ///
+    /// 名字带 `content_`：M105 的版本安装已经占了 `install_request`（版本 → `CreateRequest`），
+    /// 两者语义完全不同，撞名会被编译器拦下（本轮 rebase 撞过）。
+    ///
+    /// 这里再判一次不是重复劳动：页面禁用的只是那一个按钮，消息仍然可能从别的路径进来，
+    /// 而 host 侧对整合包会直接回失败——三道闸门同一个结论，才不会出现「有的路能过」。
+    fn content_install_request(&self) -> Option<ContentInstallRequest> {
+        let catalog = unlucky_i18n::Lang::En.catalog();
+        let model = Content::from_snapshot(&self.state, &self.content, catalog);
+        if !model.can_install() {
+            // 有原因就打印出来（取证用）；没有选中项时什么都不做
+            for reason in model.blocker_reasons(catalog) {
+                diag!("[content] 装入被挡下：{reason}");
+            }
+            if model.blockers.contains(&Blocker::NeedsPipeline) {
+                diag!("[content] 整合包装入未实现（M111）");
+            }
+            return None;
+        }
+        let hit = model.selected_hit()?;
+        let target = model
+            .targets
+            .iter()
+            .find(|target| Some(&target.id) == model.target.as_ref())?;
+        Some(ContentInstallRequest {
+            project: hit.id.clone(),
+            title: hit.title.clone(),
+            // 整合包走不到这里：`ContentKind::Modpack` 的 `dir()` 是 `None` ⇒ 必然带
+            // `Blocker::NeedsPipeline` ⇒ `can_install()` 为假。所以这里就是「单文件」那一类。
+            kind: model.kind,
+            source: hit.source,
+            instance: target.id.clone(),
+            game_version: target.mc_version.clone(),
+            loader: target.loader,
+            // 普通装入：从根项目解起（「只重试这些」是另一条消息，`retry: true`）
+            retry: false,
+        })
+    }
+}

crates/app-iced/src/app/update/content_pack.rs

@@ -0,0 +1,240 @@
+//! 整合包导入/导出区的消息落点（M113 + M160）：**从 `content.rs` 拆出来守 400 行硬线**。
+//!
+//! ## 为什么单独一个文件
+//!
+//! M160 给这一区加了预检、冲突清单、逐项决策三条通道，`content.rs` 到 409 行越线。拆的口径与
+//! 仓库其它拆分一致：**纯搬移**，`on_pack` 及其私有 helper（组请求）原样搬过来，别处一行不改。
+//!
+//! ## 两条口径（与原来同一句）
+//!
+//! 1. **页内选择改本地状态**（路径草稿 / 目标实例 / 格式 / 包名 / 展开的冲突）——它们不属于业务
+//!    状态，不进 presenter；
+//! 2. **意图只派指令，不做乐观回显**（导入 / 预检 / 确认 / 关面板）：进度、报告、预检结果全部由
+//!    `CoreEvent::Pack` 回来（`dto::pack::event` 的 `PackState::apply` 是唯一写入点）。
+//!
+//! ## M160 加的那条纪律
+//!
+//! 点「导入」先发 `PackCommand::Scan`（只读），拿到 `PackEvent::Scan` 之后：**没有冲突就直接往下导**
+//! （`clock::pump` 里的 `continue_import_after_clean_scan`），有冲突才画清单等用户点头。决策的缺省
+//! 档永远是 `KeepAll`——没问过用户就不会覆盖。
+
+use unlucky_presenter::dto::{
+    AppCommand, ConflictChoiceView, ConflictDecisionsView, ImportRequestView, PackCommand,
+};
+
+use crate::pages;
+
+use super::*;
+
+impl App {
+    /// 导入/导出区的消息（M113）。
+    ///
+    /// 两条口径：
+    ///
+    /// 1. **页内选择改本地状态**（路径草稿 / 目标实例 / 格式 / 包名 / 展开的冲突）——
+    ///    它们不属于业务状态，不进 presenter（同 `QueryChanged` 的处理）；
+    /// 2. **意图只派指令，不做乐观回显**（导入 / 预检 / 确认写盘 / 关面板）：进度、报告、预检结果
+    ///    全部由 `CoreEvent::Pack` 回来（`dto::pack::event` 的 `PackState::apply` 是唯一写入点）。
+    pub(super) fn on_pack(&mut self, message: pages::content::PackMessage) {
+        use pages::content::PackMessage;
+        match message {
+            PackMessage::Dropped(path) => {
+                // 拖进来的包属于「整合包」这一类：顺手把类型切过去，否则这一块根本不在屏上
+                self.content.kind = unlucky_presenter::dto::ContentKind::Modpack;
+                self.content.pack.draft = path.display().to_string();
+                self.content.pack.hover = false;
+                self.view_dirty = true;
+            }
+            PackMessage::Hover(hover) => {
+                self.content.pack.hover = hover;
+                self.view_dirty = true;
+            }
+            PackMessage::PathChanged(path) => {
+                self.content.pack.draft = path;
+                self.view_dirty = true;
+            }
+            PackMessage::SetInstance(instance) => {
+                self.content.pack.instance = instance;
+                self.view_dirty = true;
+            }
+            PackMessage::SetInstanceName(name) => {
+                self.content.pack.instance_name = name;
+                self.view_dirty = true;
+            }
+            PackMessage::SetFormat(format) => {
+                self.content.pack.format = format;
+                self.view_dirty = true;
+            }
+            PackMessage::SetExportName(name) => {
+                self.content.pack.export_name = name;
+                self.view_dirty = true;
+            }
+            PackMessage::SetExportVersion(version) => {
+                self.content.pack.export_version = version;
+                self.view_dirty = true;
+            }
+            PackMessage::SetOutput(path) => {
+                self.content.pack.output = path;
+                self.view_dirty = true;
+            }
+            PackMessage::ToggleConflict(path) => {
+                self.content.pack.expanded = if self.content.pack.expanded.as_deref() == Some(&path)
+                {
+                    None
+                } else {
+                    Some(path)
+                };
+                self.view_dirty = true;
+            }
+            PackMessage::OpenExport => {
+                self.content.pack.export_open = true;
+                // 包名缺省取目标实例名（用户不该为一个名字再敲一遍键盘）
+                if self.content.pack.export_name.trim().is_empty() {
+                    self.content.pack.export_name =
+                        self.content.pack.instance.clone().unwrap_or_default();
+                }
+                self.view_dirty = true;
+            }
+            PackMessage::AbortExport => {
+                self.content.pack.export_open = false;
+                // 连预检结果一起清：留着会让用户以为「还能再点一次确认」
+                self.dispatch(AppCommand::Pack(Box::new(PackCommand::Dismiss)));
+                self.view_dirty = true;
+            }
+            PackMessage::Dismiss => {
+                // 报告 / 探测诊断 / 预检都在 presenter 里：关面板 = 让 host 清掉它们
+                // （`PackEvent::Cleared`），于是界面回到入口态，浏览网格重新露出来
+                self.content.pack.expanded = None;
+                self.dispatch(AppCommand::Pack(Box::new(PackCommand::Dismiss)));
+                self.view_dirty = true;
+            }
+            PackMessage::Import => {
+                // 先预检（M160）：没有冲突就直接导，有冲突就把清单画出来等用户点头。
+                self.content.pack.pick_page = 0;
+                self.content.pack.pick_choices.clear();
+                self.content.pack.pick_overwrite_all = false;
+                if let Some(request) = self.pack_import_request() {
+                    self.dispatch(AppCommand::Pack(Box::new(PackCommand::Scan(Box::new(
+                        request,
+                    )))));
+                }
+            }
+            PackMessage::PickPage(page) => {
+                self.content.pack.pick_page = page;
+                self.view_dirty = true;
+            }
+            PackMessage::TogglePick(path) => {
+                // 点一下就翻到另一侧，并把结果**原样记进表里**（保留也记）。
+                // 表里为什么保留"保留"项：整批覆盖之后单独放回某几条时，「保留」必须能盖住
+                // 整批档；等到发请求时 `PackPageState::decisions` 再把"与缺省档相同"的项过滤掉
+                // （所以"一次都没点过"仍然等于 `KeepAll`）。
+                let choice = self.content.pack.pick_choice(&path);
+                let flipped = match choice {
+                    ConflictChoiceView::KeepUser => ConflictChoiceView::Overwrite,
+                    ConflictChoiceView::Overwrite => ConflictChoiceView::KeepUser,
+                };
+                self.content.pack.pick_choices.insert(path, flipped);
+                self.view_dirty = true;
+            }
+            PackMessage::PickKeepAll => {
+                self.content.pack.pick_overwrite_all = false;
+                self.content.pack.pick_choices.clear();
+                self.view_dirty = true;
+            }
+            PackMessage::PickOverwriteAll => {
+                self.content.pack.pick_overwrite_all = true;
+                self.content.pack.pick_choices.clear();
+                self.view_dirty = true;
+            }
+            PackMessage::ConfirmImport => {
+                let decisions = self
+                    .content
+                    .pack
+                    .decisions(self.state.pack.import.scan.as_ref());
+                if let Some(request) = self.pack_import_request_with(decisions) {
+                    self.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new(
+                        request,
+                    )))));
+                }
+            }
+            PackMessage::CancelImport => {
+                // 取消 = 什么都不导（预检是只读的，没有东西要撤）
+                self.content.pack.pick_page = 0;
+                self.content.pack.pick_choices.clear();
+                self.content.pack.pick_overwrite_all = false;
+                self.dispatch(AppCommand::Pack(Box::new(PackCommand::Dismiss)));
+                self.view_dirty = true;
+            }
+            PackMessage::Overwrite => {
+                // 「以包为准重新导入」：这条是**导入之后**从报告里点的，所以直接带整批覆盖再跑一遍。
+                if let Some(request) =
+                    self.pack_import_request_with(ConflictDecisionsView::OverwriteAll)
+                {
+                    self.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new(
+                        request,
+                    )))));
+                }
+            }
+            PackMessage::Cancel => {
+                // 与面板上那个「取消」同一个指令：host 会把导入的取消标记与代次一起处理
+                self.dispatch(AppCommand::CancelInstall);
+            }
+            PackMessage::Precheck => {
+                if let Some(request) = self.pack_export_request() {
+                    // 先记下「这次预检对的是哪份请求」，确认写盘时原样发回
+                    self.state.pack.set_export_request(request.clone());
+                    self.view_dirty = true;
+                    self.dispatch(AppCommand::Pack(Box::new(PackCommand::Export(Box::new(
+                        request,
+                    )))));
+                }
+            }
+            PackMessage::Confirm => {
+                if let Some(request) = self.state.pack.export.request.clone() {
+                    self.dispatch(AppCommand::Pack(Box::new(PackCommand::Confirm(Box::new(
+                        request,
+                    )))));
+                }
+            }
+        }
+    }
+
+    /// 预检干净（没有冲突）时直接往下导。
+    ///
+    /// 这条是"不打扰不该打扰的文件"的另一半：清单为空时弹一屏"共 0 项冲突"只会让人以为出错了。
+    /// 决策固定给 [`ConflictDecisionsView::KeepAll`]——即使预检与导入之间磁盘上突然多出个同名文件，
+    /// 结论也只会是"保留用户的"。
+    pub(in crate::app) fn continue_import_after_clean_scan(&mut self) {
+        if let Some(request) = self.pack_import_request_with(ConflictDecisionsView::KeepAll) {
+            self.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new(
+                request,
+            )))));
+        }
+    }
+
+    /// 组一份导入请求（路径草稿 → DTO）。草稿为空 ⇒ `None`（按钮不该发指令）。
+    ///
+    /// **决策缺省是「全部保留」**（[`ConflictDecisionsView::default`]）：预检时还不知道有没有冲突，
+    /// 而 core 侧那份缺省同样落在保留上——所以"还没问过用户"绝不会变成"覆盖"。
+    fn pack_import_request(&self) -> Option<ImportRequestView> {
+        self.pack_import_request_with(ConflictDecisionsView::default())
+    }
+
+    /// 组一份带决策的导入请求（逐项 / 整批都从这里出去）。
+    fn pack_import_request_with(
+        &self,
+        decisions: ConflictDecisionsView,
+    ) -> Option<ImportRequestView> {
+        let draft = self.content.pack.draft.trim();
+        if draft.is_empty() {
+            return None;
+        }
+        let name = self.content.pack.instance_name.trim();
+        Some(ImportRequestView {
+            pack: std::path::PathBuf::from(draft),
+            instance: self.content.pack.instance.clone(),
+            instance_name: (!name.is_empty()).then(|| name.to_string()),
+            decisions,
+        })
+    }
+}

crates/app-iced/src/app/update/dialog.rs

@@ -0,0 +1,138 @@
+//! 弹窗消息的落点：关闭 / 展开 / 导出 / 打开文件夹 / 复制路径。
+//!
+//! 只有两类副作用：**剪贴板**（返回 `Task`，必须交回 runtime）与**弹 Toast**（就地推）。
+//! 导出与打开文件夹是同步的本地动作（写一个 zip / 拉起一个 `explorer`），耗时都在毫秒级，
+//! 不为它们单开线程——真要慢（网络盘）也是用户能感知的一次点击。
+
+use iced::Task;
+use unlucky_presenter::toast::ToastKind;
+
+use crate::app::dialog::{export, Message as DialogMessage};
+use crate::app::state::App;
+
+pub(super) fn on_dialog(app: &mut App, message: DialogMessage) -> Task<crate::app::Message> {
+    match message {
+        DialogMessage::Primary => {
+            // M247：删除存档的二次确认——主按钮就是**真删**（这是本页唯一不可逆的动作）。
+            // 目标记在 presenter 的状态里（`SavesState::confirm`）：模态队列只画框，不记"要删谁"。
+            //
+            // **认框不认人**（复审 r1 P1-1）：只核销"当前这个框"登记的目标。哪怕某条关闭路径漏清，
+            // 崩溃卡片的「导出诊断包」也拿不走它——否则就是一次静默删世界。
+            let current = app.state.dialogs.current().map(|request| request.id);
+            if let Some(dir) = current.and_then(|id| app.state.saves.take_confirm(id)) {
+                app.close_dialog();
+                if let Some(instance) = app.selected_instance_id() {
+                    app.state
+                        .saves
+                        .mark_pending(unlucky_presenter::state::SavesOp::Delete {
+                            dir: dir.clone(),
+                        });
+                    app.dispatch(unlucky_presenter::dto::AppCommand::Saves(Box::new(
+                        unlucky_presenter::dto::SavesCommand::DeleteWorld { id: instance, dir },
+                    )));
+                }
+                app.refresh_view();
+                return Task::none();
+            }
+            // 崩溃卡片的主按钮是「导出诊断包」；普通确认框的主按钮就是「关掉」。
+            let Some(card) = app.dialog_card.clone() else {
+                app.close_dialog();
+                return Task::none();
+            };
+            let done = export::export(&card.report, app.lang());
+            // 结论**画在卡片里**：导出这种「必须看见落到哪」的结果不能只靠 Toast
+            // （app-iced 的 Toast 至今没有渲染点）。成败按 `write_bundle` 的真实结果判，
+            // 不看「launcher_logs 有没有值」——那只是入参齐全度（r1 复审 P3-2）。
+            app.state.toasts.push(
+                if done.ok {
+                    ToastKind::Success
+                } else {
+                    ToastKind::Error
+                },
+                done.text.clone(),
+            );
+            if let Some(state) = &mut app.dialog_card {
+                state.outcome = Some(done.text);
+            }
+            app.view_dirty = true;
+            app.refresh_view();
+            Task::none()
+        }
+        DialogMessage::Secondary | DialogMessage::Dismiss => {
+            // M247：取消/关掉删除确认框 ⇒ 忘掉那个目标（不然下一次点确定会删上一个）。
+            // **只核销当前这个框的目标**（复审 r2 加固）：别人的框关掉时不该动我们的。
+            if let Some(current) = app.state.dialogs.current().map(|request| request.id) {
+                app.state.saves.close_confirm(current);
+            }
+            app.close_dialog();
+            // 立即重画：空闲态只有 1 Hz 心跳，只置 `view_dirty` 会让弹窗再留最多 1 秒
+            // （r1 复审 P3-1）。
+            app.refresh_view();
+            Task::none()
+        }
+        DialogMessage::Toggle => {
+            app.toggle_dialog_detail();
+            Task::none()
+        }
+        DialogMessage::OpenFolder => {
+            let Some(card) = app.dialog_card.clone() else {
+                return Task::none();
+            };
+            let problem = export::open_folder(&card.report, app.lang());
+            if !problem.is_empty() {
+                if let Some(state) = &mut app.dialog_card {
+                    state.outcome = Some(problem.clone());
+                }
+                app.state.toasts.push(ToastKind::Error, problem);
+                app.view_dirty = true;
+                app.refresh_view();
+            }
+            Task::none()
+        }
+        DialogMessage::CopyPaths => {
+            let Some(card) = app.dialog_card.clone() else {
+                return Task::none();
+            };
+            app.state.toasts.push(
+                ToastKind::Info,
+                app.lang()
+                    .catalog()
+                    .text(unlucky_i18n::catalog::Key::CrashDialogCopied),
+            );
+            iced::clipboard::write(export::paths_text(&card.report))
+        }
+        DialogMessage::CopyPath(index) => {
+            let Some(card) = app.dialog_card.clone() else {
+                return Task::none();
+            };
+            let Some((_, path)) = card.report.path_lines().into_iter().nth(index) else {
+                return Task::none();
+            };
+            app.state.toasts.push(
+                ToastKind::Info,
+                app.lang()
+                    .catalog()
+                    .text(unlucky_i18n::catalog::Key::CrashDialogCopied),
+            );
+            iced::clipboard::write(path.display().to_string())
+        }
+    }
+}
+
+/// `Esc` 关弹窗（有弹窗时**先吃这一条**，不让它落到 AI 栏的 Esc 收起上）。
+pub(super) fn escape(app: &mut App) -> bool {
+    let Some(current) = app.state.dialogs.current().map(|request| request.id) else {
+        return false;
+    };
+    // M247（复审 r1 P1-1）：**三条关闭路径都要清**——次按钮/遮罩清了，`Esc` 这条以前漏了，
+    // 于是"删存档 → Esc → 崩溃卡片 → 导出诊断包"会把那个世界静默删掉。
+    // 现在还有 id 绑定兜一道（`take_confirm(current)`），这里是纵深防御的第二层。
+    // 复审 r2 加固：清的时候**只清这个框自己的目标**（`close_confirm`），不碰别人的。
+    app.state.saves.close_confirm(current);
+    app.close_dialog();
+    app.refresh_view();
+    true
+}
+
+#[cfg(test)]
+mod tests;

crates/app-iced/src/app/update/dialog/tests.rs

@@ -0,0 +1,262 @@
+//! 主按钮 / Esc 的落点判据（M247，复审 r1 P1-1 / P2-1）：**接线**层，不是 presenter 的状态机。
+//! 一个 App + 一个只记账的后端，看"点了主按钮之后下发了什么"——「盘上的世界还在」在这里等价于
+//! 「没有下发 `DeleteWorld`」（app 不写盘，唯一写入口是 `host::saves::dispatch`）。
+//! 真实 `export()` 写没写 zip 由 `app/dialog/tests.rs` 的夹具覆盖，这里不造崩溃卡片。
+
+use std::cell::RefCell;
+use std::rc::Rc;
+
+use unlucky_design::color::SchemeFlavor;
+use unlucky_presenter::dialogs::{DialogKind, DialogSource};
+use unlucky_presenter::dto::{
+    AppCommand, AppEvent, Backend, CoreEvent, SavesCommand, SavesListView, WorldView,
+};
+use unlucky_presenter::mock_data::mock_instances;
+use unlucky_presenter::router::Route;
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+use super::{escape, on_dialog};
+use crate::app::dialog::Message as DialogMessage;
+use crate::app::message::Message;
+use crate::app::state::App;
+use crate::cli::Options;
+use crate::pages;
+use crate::theme::Families;
+
+const FAMILIES: Families = Families {
+    text: "Segoe UI",
+    display: "Segoe UI",
+    mono: "Consolas",
+};
+const DIR: &str = "Better World";
+
+/// 只记账、按需喂事件的后端（与 `app/tests/presenter.rs` 的 recorder 同款）。
+#[derive(Debug, Default)]
+struct SpyBackend {
+    dispatched: Rc<RefCell<Vec<AppCommand>>>,
+    events: Rc<RefCell<Vec<AppEvent>>>,
+}
+
+impl Backend for SpyBackend {
+    fn drain_events(&mut self) -> Vec<AppEvent> {
+        std::mem::take(&mut *self.events.borrow_mut())
+    }
+
+    fn dispatch(&mut self, command: AppCommand) {
+        self.dispatched.borrow_mut().push(command);
+    }
+}
+
+/// 一个进到详情页、可喂事件、可记账的 App。
+struct Harness {
+    app: App,
+    dispatched: Rc<RefCell<Vec<AppCommand>>>,
+    events: Rc<RefCell<Vec<AppEvent>>>,
+}
+
+impl Harness {
+    fn new() -> Self {
+        let dispatched = Rc::new(RefCell::new(Vec::new()));
+        let events = Rc::new(RefCell::new(vec![AppEvent::Core(
+            CoreEvent::InstancesChanged(mock_instances()),
+        )]));
+        let backend = SpyBackend {
+            dispatched: Rc::clone(&dispatched),
+            events: Rc::clone(&events),
+        };
+        let mut harness = Self {
+            app: App::with_presenter(
+                Options::default(),
+                FAMILIES,
+                SchemeFlavor::Light,
+                Box::new(backend),
+                SettingsBridge::memory_only(),
+            ),
+            dispatched,
+            events,
+        };
+        let _ = harness.app.update(Message::Boot);
+        assert_eq!(
+            harness.app.state.route(),
+            &Route::Detail("survival".to_string()),
+            "首屏该落在详情页（后面每一步都以它为前提交付目标）"
+        );
+        harness
+    }
+
+    /// 喂一条事件再抽干（`pump` 是唯一的 apply 入口，它顺带 `refresh_view`）。
+    fn feed(&mut self, event: AppEvent) {
+        self.events.borrow_mut().push(event);
+        self.app.pump();
+        self.app.refresh_view();
+    }
+
+    /// 点一次「删除 X」（页面消息的真实入口）。
+    fn request_delete(&mut self) {
+        let _ = self.app.update(Message::Page(pages::Message::Instances(
+            pages::InstanceMessage::RequestDeleteWorld {
+                dir: DIR.to_string(),
+            },
+        )));
+    }
+
+    /// 有没有下发过 `SavesCommand::DeleteWorld`（= core 会不会去删盘上的世界）。
+    fn deleted(&self) -> bool {
+        self.dispatched.borrow().iter().any(|command| {
+            matches!(
+                command,
+                AppCommand::Saves(command)
+                    if matches!(**command, SavesCommand::DeleteWorld { .. })
+            )
+        })
+    }
+}
+
+/// 一份 `saves/` 快照（`worlds` 决定"那个世界还在不在"）。
+fn snapshot(worlds: &[&str]) -> AppEvent {
+    AppEvent::Core(CoreEvent::Saves(Box::new(Ok(SavesListView {
+        instance: "survival".to_string(),
+        dir: "C:/mc/saves".to_string(),
+        exists: true,
+        worlds: worlds
+            .iter()
+            .map(|dir| WorldView {
+                dir: (*dir).to_string(),
+                icon: false,
+                modified_ms: None,
+            })
+            .collect(),
+        screenshots_dir: "C:/mc/screenshots".to_string(),
+        screenshots_exists: false,
+        screenshots: Vec::new(),
+        skipped: Vec::new(),
+        last_op: None,
+    }))))
+}
+
+/// **P1-1 事故链**：删存档 → `Esc` → 一个不相干的 `Confirm`（崩溃卡片的主按钮是「导出诊断包」）
+/// → 点主按钮 ⇒ **没有** `DeleteWorld` 下发，框走它自己那条路（这里没有崩溃卡片 ⇒ 关框）。
+#[test]
+fn escaping_the_delete_dialog_disarms_it_for_the_next_one() {
+    let mut harness = Harness::new();
+    harness.request_delete();
+    assert!(
+        harness.app.state.dialogs.current().is_some(),
+        "确认框没弹出来"
+    );
+    assert!(harness.app.state.saves.confirm.is_some(), "目标没登记");
+
+    assert!(escape(&mut harness.app), "有框时 Esc 该被吃掉");
+    assert!(
+        harness.app.state.saves.confirm.is_none(),
+        "Esc 之后目标还留着 —— 下一个框的主按钮会把它兑现"
+    );
+    assert!(harness.app.state.dialogs.current().is_none());
+
+    // 不相干的框：崩溃卡片就是这个形态（`Confirm`，主按钮「导出诊断包」）。
+    let _ = harness.app.state.dialogs.push(
+        DialogSource::UserAction,
+        "启动失败",
+        "退出码 1",
+        DialogKind::Confirm {
+            primary: "导出诊断包".to_string(),
+            secondary: "关闭".to_string(),
+        },
+    );
+    let _ = on_dialog(&mut harness.app, DialogMessage::Primary);
+
+    assert!(
+        !harness.deleted(),
+        "Esc 之后那个目标被下一个框兑现了：世界被静默删除"
+    );
+    assert!(
+        harness.app.state.dialogs.current().is_none(),
+        "主按钮该走它自己那条路（这里没有崩溃卡片 ⇒ 关框）"
+    );
+}
+
+/// **纵深防御（P1-1 的第二层）**：万一某条路径只关了框、**漏清**目标，下一个不相干的框
+/// 点主按钮也**拿不走**它 —— 因为 `take_confirm` 只有在"登记时那个框 == 当前框"时才交付。
+///
+/// 这条直接构造"漏清"状态（登记一个不存在的框 id），所以它**不依赖** `Esc` 那条路有没有清：
+/// 去掉 id 校验，它立刻红。
+#[test]
+fn a_leaked_target_cannot_be_redeemed_by_another_dialog() {
+    let mut harness = Harness::new();
+    // 模拟事故形态：目标还挂着，但那个框早就不在了（登记 999 = 一个不存在的框）。
+    harness.app.state.saves.ask_delete(999, DIR);
+    let _ = harness.app.state.dialogs.push(
+        DialogSource::UserAction,
+        "启动失败",
+        "退出码 1",
+        DialogKind::Confirm {
+            primary: "导出诊断包".to_string(),
+            secondary: "关闭".to_string(),
+        },
+    );
+
+    let _ = on_dialog(&mut harness.app, DialogMessage::Primary);
+
+    assert!(
+        !harness.deleted(),
+        "漏清的目标被别的框兑现了：世界被静默删除（P1-1 的事故形态）"
+    );
+    assert!(
+        harness.app.state.saves.confirm.is_some(),
+        "别人的框不该顺手清掉我们的目标（清它的是关闭路径，不是主按钮）"
+    );
+}
+
+/// 反向：目标属于**当前**这个框时，主按钮仍然真的下发删除（没把功能关死）。
+#[test]
+fn the_owning_dialog_still_deletes() {
+    let mut harness = Harness::new();
+    harness.request_delete();
+    let _ = on_dialog(&mut harness.app, DialogMessage::Primary);
+
+    assert!(harness.deleted(), "自己的框点主按钮居然没删");
+    assert!(harness.app.state.saves.confirm.is_none(), "取走即清");
+    assert!(
+        harness.app.state.saves.pending.is_some(),
+        "该把那一行标成在飞（否则能连点）"
+    );
+    assert!(harness.app.state.dialogs.current().is_none(), "框该关掉");
+}
+
+/// **P2-1**：世界还在 ⇒ 一拍无关快照（备份回程 / 打开文件夹回程）之后，主按钮照样删。
+#[test]
+fn an_unrelated_snapshot_keeps_the_confirmation_redeemable() {
+    let mut harness = Harness::new();
+    harness.request_delete();
+    harness.feed(snapshot(&[DIR, "Other"]));
+
+    assert!(
+        harness.app.state.saves.confirm.is_some(),
+        "无关快照把目标吃掉了：主按钮会变成静默空操作"
+    );
+    assert!(
+        harness.app.state.dialogs.current().is_some(),
+        "框不该被收掉"
+    );
+    let _ = on_dialog(&mut harness.app, DialogMessage::Primary);
+    assert!(harness.deleted(), "快照之后主按钮点了没反应");
+}
+
+/// **P2-1 的另一半**：世界从快照里消失 ⇒ 框被**收起来**（不是留一个点了没反应的按钮），
+/// 而且不下发删除（那个世界已经不存在了，下发只会换来一条 `WriteMissing` 噪音）。
+#[test]
+fn a_vanished_world_closes_its_confirmation() {
+    let mut harness = Harness::new();
+    harness.request_delete();
+    harness.feed(snapshot(&["Other"]));
+
+    assert!(
+        harness.app.state.saves.confirm.is_none(),
+        "作废的目标还留着"
+    );
+    assert!(
+        harness.app.state.dialogs.current().is_none(),
+        "框没被收起：主按钮会是一次静默空操作"
+    );
+    assert!(!harness.deleted(), "世界都不在了还下发删除");
+}

crates/app-iced/src/app/update/dialog_fixture.rs

@@ -0,0 +1,152 @@
+//! 启动失败弹窗的**取证夹具**（`ULL_DIALOG_FIXTURE`，只在 `--screenshot` 下生效）。
+//!
+//! ## 为什么要有它
+//!
+//! 弹窗要出两张图（「有 crash-report」/「只有捕获输出」），而真机上要复现一次崩溃得先让一个
+//! 真实的 MC 进程死掉——截图通道要的是**确定性**。做法与 `ULL_ACCOUNT_STATE` 同一档：
+//! 在临时目录里造一份**真的文件树**（launcher.log / 会话 JSONL / crash-reports / latest.log），
+//! 于是弹窗上的路径是真路径、点「导出诊断包」真的会打出一个装得下这些文件的 zip。
+//!
+//! 取值：
+//!
+//! | 值 | 现场 |
+//! |---|---|
+//! | `crash-report` | 游戏写了 `crash-reports/crash-*.txt`（证据一） |
+//! | `no-logs` | 没有 crash-report、没有 latest.log，只有会话 JSONL 里的 stderr（证据二） |
+//! | `export` | 同 `no-logs`，并在出图前**真的跑一次导出**（第三张图：路径 + 字节数） |
+//!
+//! 夹具只影响这一次进程；产品路径（`host/launch.rs` 收尾 → `crash_report::publish` →
+//! `refresh_view` → 弹窗）与它完全同一条，这里只是**代填事实**。
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::launch::crash_report::{self, ArtifactFact, CrashReport};
+use unlucky_core::launch::crash_scan::{self, CrashSource};
+use unlucky_presenter::dto::{LaunchFinished, LogOutcome};
+
+use crate::app::state::App;
+
+/// 现场根（`%TEMP%/ull-m187-fixture-<pid>`）。
+fn root() -> PathBuf {
+    std::env::temp_dir().join(format!("ull-m187-fixture-{}", std::process::id()))
+}
+
+fn write(path: &Path, text: &str) {
+    if let Some(parent) = path.parent() {
+        let _ = std::fs::create_dir_all(parent);
+    }
+    let _ = std::fs::write(path, text);
+}
+
+/// 出图用的夹具（`None` = 没有开关，什么都不做）。
+pub(super) fn apply(app: &mut App) -> Option<String> {
+    let mode = std::env::var("ULL_DIALOG_FIXTURE").ok()?;
+    let mode = mode.trim().to_lowercase();
+    if !app.has_screenshot() {
+        return None;
+    }
+    let root = root();
+    let _ = std::fs::remove_dir_all(&root);
+    let logs = root.join("logs");
+    write(
+        &logs.join("launcher.log"),
+        "2026-11-08T15:30:11.002Z [boot] renderer=wgpu\n\
+         2026-11-08T15:30:12.441Z [launch] instance=survival spawn game_dir=… java=javaw (21)\n\
+         2026-11-08T15:30:19.870Z [launch] instance=survival session=9f2c exit=1\n",
+    );
+    write(&logs.join("install.log"), "installed 1.20.4-fabric\n");
+
+    let session = "9f2c4a1e-77bd-4f27-9d21-5b0a1f2c3d4e";
+    let session_log = root
+        .join("sessions")
+        .join("game")
+        .join(format!("{session}.jsonl"));
+    write(
+        &session_log,
+        "{\"kind\":\"stdout\",\"payload\":{\"line\":\"[main/INFO]: Loading Minecraft 1.20.4\"}}\n\
+         {\"kind\":\"stderr\",\"payload\":{\"line\":\"java.lang.RuntimeException: mixin injection failed\"}}\n\
+         {\"kind\":\"stderr\",\"payload\":{\"line\":\"Caused by: java.lang.NoClassDefFoundError: org/lwjgl/glfw/GLFW\"}}\n\
+         {\"kind\":\"exit\",\"payload\":{\"code\":1}}\n",
+    );
+    let tail: Vec<String> = vec![
+        "[main/INFO]: Loading Minecraft 1.20.4".to_string(),
+        "java.lang.RuntimeException: mixin injection failed".to_string(),
+        "Caused by: java.lang.NoClassDefFoundError: org/lwjgl/glfw/GLFW".to_string(),
+    ];
+
+    let run_dir = root.join("instances").join("survival");
+    let latest = run_dir.join("logs").join("latest.log");
+    let version_json = root
+        .join("game")
+        .join("versions")
+        .join("1.20.4-fabric")
+        .join("1.20.4-fabric.json");
+    write(&version_json, "{\"id\":\"1.20.4-fabric\"}\n");
+
+    let mut artifacts: Vec<ArtifactFact> = Vec::new();
+    if mode != "no-logs" {
+        write(
+            &run_dir
+                .join("crash-reports")
+                .join("crash-2026-11-08_15.30.19-client.txt"),
+            "---- Minecraft Crash Report ----\n\
+             Time: 2026-11-08 15:30:19\n\
+             Description: Initializing game\n\n\
+             java.lang.RuntimeException: mixin injection failed\n\
+             \tat net.fabricmc.loader.impl.launch.knot.Knot.init(Knot.java:142)\n\
+             \tat net.minecraft.client.main.Main.main(Main.java:51)\n",
+        );
+        write(&latest, "[15:30:12] [main/INFO]: Loading Minecraft 1.20.4\n[15:30:19] [Render thread/ERROR]: GLFW init failed\n");
+        let since = std::time::SystemTime::now() - std::time::Duration::from_secs(120);
+        artifacts = crash_scan::scan(&run_dir, since, 8)
+            .into_iter()
+            .map(|artifact| ArtifactFact {
+                source: artifact.source.as_str().to_string(),
+                path: artifact.path,
+                excerpt: artifact.excerpt,
+            })
+            .collect();
+    }
+
+    let report = CrashReport {
+        instance: "survival".to_string(),
+        name: "生存服的 1.20.4".to_string(),
+        version: "1.20.4-fabric".to_string(),
+        session: session.to_string(),
+        session_log: Some(session_log),
+        version_json: Some(version_json),
+        launcher_logs: Some(logs),
+        run_dir: Some(run_dir),
+        artifacts,
+        exit_code: Some(1),
+        exit_type: "application_error".to_string(),
+        uptime_ms: 7_400,
+        command: "javaw -Xmx4096m -Djava.library.path=<home>… ".to_string(),
+        java: "C:/Program Files/Java/jdk-21/bin/javaw.exe (major 21)".to_string(),
+        system: "os=windows version=10.0.26100 arch=x86_64".to_string(),
+        stage: None,
+        stage_detail: None,
+        stderr_tail: tail,
+    };
+    crash_report::publish(report);
+    let finished = LaunchFinished {
+        id: "survival".to_string(),
+        session: session.to_string(),
+        outcome: LogOutcome::Crashed,
+        exit_code: Some(1),
+        uptime_ms: 7_400,
+        failure: None,
+    };
+    app.open_failure_dialog(&finished);
+    if mode == "export" {
+        // 走**真的**那一条：与用户点「导出诊断包」同一个处理函数。
+        let _ = super::dialog::on_dialog(app, crate::app::dialog::Message::Primary);
+    }
+    Some(mode)
+}
+
+/// 夹具里崩溃报告的来源名（与 `CrashSource::CrashReport` 同源，测试用）。
+#[allow(dead_code)]
+pub(super) fn crash_report_source() -> &'static str {
+    CrashSource::CrashReport.as_str()
+}

crates/app-iced/src/app/update/download.rs

@@ -0,0 +1,381 @@
+//! 下载页在 app 层的那几支（M94；M105 补上安装选项）。
+//!
+//! 为什么单独一个文件：M93（外观三件套接线）合入后 `update.rs` 已经贴到 400 行，下载页再往里塞
+//! 几个 arm 就顶破硬线；拆出来是既不动 M93 的代码、又能守住 ≤400 的办法（`app/update/**` 属本
+//! mission scope）。
+//!
+//! ## 各支各自的纪律（M105 后的口径）
+//!
+//! | 消息 | 落点 | 为什么 |
+//! |---|---|---|
+//! | [`pages::Message::SelectVersion`] | 只改**草稿** | 选中是页面内状态，不是业务命令；顺手清掉加载器版本（换了原版版本，旧版本号几乎必然不适用） |
+//! | [`pages::Message::SetLoader`] | 改草稿 + 必要时派 `ListLoaderVersions` | 加载器版本列表来自官方元数据，页面不能自己编 |
+//! | [`pages::Message::SetLoaderVersion`] / `SetInstanceName` | 只改草稿 | 纯输入 |
+//! | [`pages::Message::InstallVersion`] | `AppCommand::CreateInstance(草稿)` | **确认才开工**（带加载器 / 加载器版本 / 实例名） |
+//! | [`pages::Message::CancelInstall`] | `AppCommand::CancelInstall` | 见 `host/dispatch.rs`：真停 + 作废旧代次 |
+//! | [`pages::Message::SetCategory`] | 写分类 → 重建 → `AppCommand::ListVersions` | 见下 |
+//!
+//! [「刷新下载源」](pages::Action::RefreshSources) 也在这里：它不是占位动作，具体分类 → 重拉该分类、
+//! 「全部」→ 让 host 重扫一遍（`RefreshAll`）。
+//!
+//! ## 分类为什么既写视图模型、又派指令
+//!
+//! 真 host 的 `AppCommand::ListVersions(_)` 会丢掉分类参数、回全量清单（复审 P2-1），所以**过滤在
+//! 本页做**：写进视图模型 → 立刻 `refresh_view()`（它会把 category 带回去、按同一谓词过滤行）→
+//! 再派指令。这不是「乐观回显」：写的是**过滤条件本身**，chip 与列表用同一个
+//! [`Category::matches`](crate::pages::Category)，于是不可能出现「chip 说正式版、列表是全量」的两份真相。
+//!
+//! ## 草稿为什么住在这里而不是页面模型里
+//!
+//! `refresh_view()` 每次事件都把 `self.view` 整棵重建（连安装进度都算），页面存不住「用户正在填、
+//! 还没确认」的东西。于是草稿放 `App::download_draft`，与分类筛选同一个做法：
+//! 改草稿 → `view_dirty = true` → `refresh_view()`。
+
+use unlucky_presenter::dto::CreateRequest;
+
+use super::*;
+
+impl App {
+    /// 下载页的消息。**处理了返回 `true`**（`on_page` 里就不用再写一遍这些 arm）。
+    pub(super) fn on_download(&mut self, message: &pages::Message) -> bool {
+        match message {
+            pages::Message::SelectVersion(id) => {
+                if self.download_draft.selected.as_deref() != Some(id.as_str()) {
+                    // 换了原版版本：加载器版本是**按 (加载器, 原版版本)** 取的（见
+                    // `CoreEvent::LoaderVersions` 的缓存键），旧的版本号留着只会误导。
+                    self.download_draft.loader_version.clear();
+                }
+                self.download_draft.selected = Some(id.clone());
+                self.mark_download_dirty();
+                // 选了加载器版本之后换原版版本，列表要跟着换——已经查过的直接从快照读，不重复派。
+                self.ensure_loader_versions();
+            }
+            pages::Message::SetLoader(loader) => {
+                self.download_draft.loader = *loader;
+                self.download_draft.loader_version.clear();
+                self.mark_download_dirty();
+                self.ensure_loader_versions();
+            }
+            pages::Message::SetLoaderVersion(version) => {
+                self.download_draft.loader_version = version.clone();
+                self.mark_download_dirty();
+            }
+            pages::Message::SetInstanceName(name) => {
+                self.download_draft.instance_name = name.clone();
+                self.mark_download_dirty();
+            }
+            pages::Message::InstallVersion(id) => {
+                // 防守：按钮带的是**页面上那一行**的 id，草稿里的选中项理论上与它一致；
+                // 万一不一致（例如列表刚换过、用户手快），不能让 A 版本的加载器版本落到 B 版本上。
+                if self.download_draft.selected.as_deref() != Some(id.as_str()) {
+                    self.download_draft.selected = Some(id.clone());
+                    self.download_draft.loader_version.clear();
+                }
+                let request = self.install_request(id);
+                self.dispatch(AppCommand::CreateInstance(request));
+            }
+            pages::Message::CancelInstall => self.dispatch(AppCommand::CancelInstall),
+            pages::Message::SetCategory(category) => {
+                self.view.download.category = *category;
+                self.view_dirty = true;
+                self.refresh_view();
+                if let Some(kind) = category.command() {
+                    self.dispatch(AppCommand::ListVersions(kind));
+                }
+            }
+            // M107：查询词落在快照里（无状态视图的唯一存活方式），再走同一条重建路径过滤。
+            pages::Message::SetVersionQuery(query) => {
+                self.rebuild_after_query(query.clone());
+            }
+            pages::Message::ClearVersionQuery => {
+                self.rebuild_after_query(String::new());
+            }
+            // M107：主版本桶的选中是纯视图态，不重建、不派命令（同 `SelectVersion`）。
+            //
+            // **搜索期间点桶 = 「我就是要看这个桶」**（复审 r2 P2-1(b)）：搜索让第二级失效（P2-1 的
+            // 一致性放宽），如果这里只改选择而不清查询，用户会看到「点了没反应、清空搜索后才生效」
+            // 的活控件。所以搜索中点桶顺带退出搜索，按新桶过滤——一次点击做完用户想要的两件事。
+            pages::Message::SelectMajor(key) => {
+                if self.view.download.has_query() {
+                    // 先退出搜索再落选择：`rebuild_after_query` 会用**全量行**重算桶并回填选择
+                    // （它带回 `selected_major`，且校验桶仍存在）。
+                    self.view.download.selected_major = key.clone();
+                    self.rebuild_after_query(String::new());
+                } else {
+                    self.view.download.selected_major = key.clone();
+                }
+            }
+            // M107：类型栏的手动折叠也是纯视图态。
+            pages::Message::ToggleTypeRail => {
+                self.view.download.type_rail_folded = !self.view.download.type_rail_folded;
+            }
+            pages::Message::Action(pages::Action::RefreshSources) => {
+                match self.view.download.category.command() {
+                    Some(kind) => self.dispatch(AppCommand::ListVersions(kind)),
+                    None => self.dispatch(AppCommand::RefreshAll),
+                }
+            }
+            _ => return false,
+        }
+        true
+    }
+
+    /// 改草稿之后统一走这一条：置脏 + 立刻重建（不等下一拍，点了就有反应）。
+    fn mark_download_dirty(&mut self) {
+        self.view_dirty = true;
+        self.refresh_view();
+    }
+
+    /// 确认安装时的 `CreateRequest`（草稿 → 指令载荷）。
+    ///
+    /// 实例名留空就让 core 用版本号（`CreateRequest::instance_name` 的既有口径），
+    /// 所以这里**不**自己拼一个默认名——两处各拼一份迟早会漂。
+    fn install_request(&self, id: &str) -> CreateRequest {
+        let draft = &self.download_draft;
+        CreateRequest {
+            name: draft.instance_name.trim().to_string(),
+            version: id.to_string(),
+            loader: draft.loader.kind(),
+            loader_version: draft.loader_version.trim().to_string(),
+        }
+    }
+
+    /// 当前草稿需要加载器版本列表、而快照里还没有时，派一次查询。
+    ///
+    /// 判据是 `state.loader_versions_for(...)` 的 `None`（= 没查过）：查过的（成功或失败）都不再重复派，
+    /// 失败要重试走 `RefreshSources` 那条路，页面上的红色原因行不会因为一次点击就消失。
+    fn ensure_loader_versions(&mut self) {
+        let loader = self.download_draft.loader;
+        if loader == pages::Loader::Vanilla {
+            return;
+        }
+        let Some(version) = self.download_draft.selected.clone() else {
+            return;
+        };
+        // 静态就不支持的组合不联网（否则只会换来一条「取不到」的假原因；真正的原因是
+        // 「这个加载器没有这个版本的构建」，页面已经用静态规则说清了）。
+        let kind = self
+            .state
+            .versions
+            .iter()
+            .find(|summary| summary.id == version)
+            .map(|summary| summary.kind);
+        if let Some(kind) = kind {
+            if loader.supports(&version, kind).is_err() {
+                return;
+            }
+        }
+        if self
+            .state
+            .loader_versions_for(loader.kind(), &version)
+            .is_some()
+        {
+            return;
+        }
+        self.dispatch(AppCommand::ListLoaderVersions {
+            kind: loader.kind(),
+            mc_version: version,
+        });
+    }
+
+    /// 搜索词变了：写进快照 → 重建视图 → **把纯视图态捡回来**。
+    ///
+    /// `refresh_view()` 整块换掉 `self.view`，而它只把 `category` 与**安装草稿**带回去（`app/state.rs`
+    /// 归 M105/M106）。所以「折叠状态」与「选中的主版本桶」必须在重建前后自己搬一次——否则用户敲第一个
+    /// 字符，展开着的类型栏就自己收起来、选中的主版本也跳回「全部」。
+    /// 「搜索时侧栏保留当前位置」这条要求，落点就是这里的四行。
+    fn rebuild_after_query(&mut self, query: String) {
+        self.state.download_query = query;
+        let major = self.view.download.selected_major.take();
+        let folded = self.view.download.type_rail_folded;
+        self.view_dirty = true;
+        self.refresh_view();
+        // 回填要**校验**：桶是按当前行聚合法出来的，新桶列表里没有的那个选择不该被复活
+        // （复审 P2-1(a)：否则会出现「侧栏没有任何一项点亮」的幽灵选中）。
+        self.view.download.selected_major = major.filter(|key| {
+            self.view
+                .download
+                .buckets
+                .iter()
+                .any(|bucket| bucket.key.as_deref() == Some(key.as_str()))
+        });
+        self.view.download.type_rail_folded = folded;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    //! 搜索链路的**端到端**断言（复审 P2-5）。
+    //!
+    //! 为什么非要在 app 层写：这条链是 `Message → on_page → on_download → AppState.download_query
+    //! → refresh_view → from_snapshot 过滤`，中间任何一环断掉，页面层测试都看不见（页面只拿到
+    //! 已经过滤好的模型）。复审原话：「把 `rebuild_after_query` 第一行删掉，现有测试全绿，而搜索
+    //! 变成假控件」——这几条就是补那个洞的。
+
+    use std::cell::RefCell;
+    use std::rc::Rc;
+
+    use unlucky_presenter::dto::{AppEvent, Backend, CoreEvent, VersionKind, VersionSummary};
+    use unlucky_presenter::settings_bridge::SettingsBridge;
+
+    use super::*;
+
+    /// 只记账、不回事件的后端（同 `app/update/download_wiring.rs`）：命令出了 UI 层，状态一个字节
+    /// 都不许变——否则「本地乐观回显」与「事件回流」终态相同，断言会假绿。
+    struct Recorder(Rc<RefCell<Vec<AppCommand>>>);
+
+    impl Backend for Recorder {
+        fn drain_events(&mut self) -> Vec<AppEvent> {
+            Vec::new()
+        }
+        fn dispatch(&mut self, command: AppCommand) {
+            self.0.borrow_mut().push(command);
+        }
+    }
+
+    fn version(id: &str) -> VersionSummary {
+        VersionSummary {
+            id: id.to_string(),
+            kind: VersionKind::Release,
+            released: "2026-09-20".to_string(),
+            installed: false,
+        }
+    }
+
+    /// 一个装好三行版本的 App（`1.21.9` / `1.20.4` / `1.20.1`）。
+    fn app() -> App {
+        let families = crate::theme::Families {
+            text: "Segoe UI",
+            display: "Segoe UI",
+            mono: "Consolas",
+        };
+        let mut app = App::with_presenter(
+            crate::cli::Options::default(),
+            families,
+            SchemeFlavor::Light,
+            Box::new(Recorder(Rc::new(RefCell::new(Vec::new())))),
+            SettingsBridge::memory_only(),
+        );
+        app.state
+            .apply(AppEvent::Core(CoreEvent::VersionListChanged(vec![
+                version("1.21.9"),
+                version("1.20.4"),
+                version("1.20.1"),
+            ])));
+        app.refresh_view();
+        app
+    }
+
+    /// 键入 → 快照 → 列表：一条走完的链。
+    ///
+    /// 抓得住：`rebuild_after_query` 不再写 `AppState.download_query`（搜索变假控件）、
+    /// 或 `from_snapshot` 不再按 query 过滤（列表不跟着收窄）。
+    /// 抓不住：真机上 `text_input` 的按键是否走到这里（那是组件的事，`search_bar` 已接 `on_input`）。
+    #[test]
+    fn typing_a_query_reaches_the_state_and_narrows_the_list() {
+        let mut app = app();
+        assert_eq!(app.view.download.rows.len(), 3, "初始是全量");
+
+        let _ = app.on_page(pages::Message::SetVersionQuery("1.20".to_string()));
+
+        assert_eq!(app.state.download_query, "1.20", "查询词落在快照里");
+        assert_eq!(app.view.download.rows.len(), 2, "列表收窄到两行");
+        assert_eq!(app.view.download.hits, 2);
+        assert_eq!(app.view.download.query, "1.20", "模型回显查询词");
+
+        // 清空回到全量（`ClearVersionQuery` 那一支）
+        let _ = app.on_page(pages::Message::ClearVersionQuery);
+        assert!(app.state.download_query.is_empty());
+        assert_eq!(app.view.download.rows.len(), 3);
+    }
+
+    /// 查询词**跨事件存活**：再来一次重建，列表仍是收窄的。
+    ///
+    /// 抓得住：把查询词只写在视图模型里（下一次 `refresh_view` 就丢）——这是「搜索看起来能用、
+    /// 一来事件就复位」的坏法。
+    #[test]
+    fn the_query_survives_a_snapshot_rebuild() {
+        let mut app = app();
+        let _ = app.on_page(pages::Message::SetVersionQuery("1.21".to_string()));
+        assert_eq!(app.view.download.rows.len(), 1);
+
+        // 安装进度这类事件回来时，`pump()` 会重建视图：查询词必须还在
+        app.state
+            .apply(AppEvent::Core(CoreEvent::InstallProgress(None)));
+        app.refresh_view();
+
+        assert_eq!(app.state.download_query, "1.21", "查询词在快照里，重建不丢");
+        assert_eq!(app.view.download.rows.len(), 1, "列表仍收窄");
+    }
+
+    /// **搜索期间点主版本桶 = 退出搜索并按该桶过滤**（复审 r2 P2-1(b)）。
+    ///
+    /// 抓得住：`SelectMajor` 只改选择不清查询 —— 那时搜索让第二级失效（P2-1 的一致性放宽），
+    /// 用户点了当场没反应、要等清空搜索那次点击才生效，就是「可点但无反应」的活控件。
+    /// 抓不住：真机点击是否走到这里（`ListItem`/`Chip` 的 `on_press` 是组件既有实现）。
+    #[test]
+    fn clicking_a_bucket_during_a_search_leaves_the_search() {
+        let mut app = app();
+        let _ = app.on_page(pages::Message::SetVersionQuery("1.20".to_string()));
+        assert_eq!(app.view.download.rows.len(), 2, "此刻在搜 1.20");
+
+        // 点「1.21」这个桶
+        let _ = app.on_page(pages::Message::SelectMajor(Some("1.21".to_string())));
+
+        assert!(app.state.download_query.is_empty(), "点桶顺带退出搜索");
+        assert!(!app.view.download.has_query());
+        assert_eq!(
+            app.view.download.selected_major.as_deref(),
+            Some("1.21"),
+            "选择落在刚点的那个桶上"
+        );
+        assert_eq!(
+            app.view.download.rows.len(),
+            3,
+            "查询词清掉之后模型回到全量（桶过滤发生在渲染时的 visible 里）"
+        );
+        assert_eq!(
+            app.view
+                .download
+                .buckets
+                .iter()
+                .find(|bucket| bucket.key.as_deref() == Some("1.21"))
+                .map(|bucket| bucket.count),
+            Some(1),
+            "1.21 桶里只有一个版本 ⇒ 列表会显示一行"
+        );
+
+        // 没有搜索词时点桶照旧只改选择（不触发多余重建）
+        let _ = app.on_page(pages::Message::SelectMajor(None));
+        assert_eq!(app.view.download.selected_major, None);
+    }
+
+    /// 搜索时侧栏的**位置与折叠**不许丢（`rebuild_after_query` 的三行）。
+    ///
+    /// 抓得住：删掉那两行回填（敲第一个字符，类型栏自己弹开、主版本跳回「全部」）。
+    /// 抓不住：其它事件（安装进度）回来时也会复位 —— 那条要 `app/state.rs` 的 `refresh_view`
+    /// 一起改，不在本 mission scope，已在报告里明确登记「留到 M105 之后」。
+    #[test]
+    fn a_query_keeps_the_rail_position_and_the_fold() {
+        let mut app = app();
+        app.view.download.selected_major = Some("1.20".to_string());
+        app.view.download.type_rail_folded = true;
+
+        let _ = app.on_page(pages::Message::SetVersionQuery("1.20".to_string()));
+
+        assert_eq!(
+            app.view.download.selected_major.as_deref(),
+            Some("1.20"),
+            "桶选择还在（生效值在搜索期间放宽，但选择本身不许被清）"
+        );
+        assert!(app.view.download.type_rail_folded, "折叠状态还在");
+
+        // 选中一个**新桶列表里不存在**的桶：搜索后不许把它复活成幽灵选中（P2-1(a)）
+        app.view.download.selected_major = Some("9.99".to_string());
+        let _ = app.on_page(pages::Message::SetVersionQuery("1.20".to_string()));
+        assert_eq!(
+            app.view.download.selected_major, None,
+            "新桶列表里没有 9.99 ⇒ 回填空值，而不是留一个点不亮的幽灵选中"
+        );
+    }
+}

crates/app-iced/src/app/update/download_wiring.rs

@@ -0,0 +1,228 @@
+//! 下载页（M94）在 app 层的接线测试：**命令出得去、状态不自己变**。
+//!
+//! 从 `app/update.rs` 外置（那边 348 行 + 这个模块会顶破 400 行硬上限；同一句话的理由见
+//! `crates/i18n/src/catalog/tests.rs`）。`use super::*` 依然指向 `crate::app::update`。
+
+use std::cell::RefCell;
+use std::rc::Rc;
+
+use unlucky_presenter::dto::{AppEvent, Backend, VersionCategory};
+use unlucky_presenter::settings_bridge::SettingsBridge;
+
+use super::*;
+
+/// 只记账、**不回事件**的后端（同 `app/tests/presenter.rs`）：命令出了 UI 层，状态一个字节都不许变。
+/// 不用 `MockBackend`：它同步回事件，「本地乐观回显」与「事件回流」终态相同，断言会**假绿**。
+struct Recorder(Rc<RefCell<Vec<AppCommand>>>);
+
+impl Backend for Recorder {
+    fn drain_events(&mut self) -> Vec<AppEvent> {
+        Vec::new()
+    }
+    fn dispatch(&mut self, command: AppCommand) {
+        self.0.borrow_mut().push(command);
+    }
+}
+
+/// 四条下载页消息：三条派真指令，`SelectVersion` 只改视图模型（P3-2 的不乐观回显）。
+/// 抓得住：意图被写成「本地改状态就算完」、或派错指令；抓不住：host 收到后真的开始下载。
+#[test]
+fn download_intents_dispatch_real_commands() {
+    let log: Rc<RefCell<Vec<AppCommand>>> = Rc::new(RefCell::new(Vec::new()));
+    let families = crate::theme::Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+    let mut app = App::with_presenter(
+        crate::cli::Options::default(),
+        families,
+        SchemeFlavor::Light,
+        Box::new(Recorder(Rc::clone(&log))),
+        SettingsBridge::memory_only(),
+    );
+    // M95 起 `on_page` 返回 `Task`（剪贴板命令要走返回的 Task）：这里只关心派发与视图模型，
+    // 任务本身没有需要断言的后效，显式丢弃。
+    let _ = app.on_page(pages::Message::InstallVersion("1.21.9".to_string()));
+    let _ = app.on_page(pages::Message::CancelInstall);
+    let _ = app.on_page(pages::Message::SetCategory(pages::Category::Release));
+    let _ = app.on_page(pages::Message::SelectVersion("1.21.8".to_string()));
+    // M105：「安装」不再是「立刻装原版」，而是把**草稿里的选项**一起交出去
+    // （`CreateInstance` 带加载器 / 加载器版本 / 实例名）——这正是用户报的「没有加载器可选」的修复点。
+    let expected = vec![
+        AppCommand::CreateInstance(unlucky_presenter::dto::CreateRequest {
+            version: "1.21.9".to_string(),
+            loader: unlucky_presenter::dto::LoaderKind::Vanilla,
+            loader_version: String::new(),
+            name: String::new(),
+        }),
+        AppCommand::CancelInstall,
+        AppCommand::ListVersions(VersionCategory::Release),
+    ];
+    assert_eq!(
+        *log.borrow(),
+        expected,
+        "三条各派一条；`SelectVersion` 不派"
+    );
+    // M105：选中项住在**草稿**里（`refresh_view` 每次事件都会整棵重建页面模型，
+    // 页面自己存不住它）；recorder 不回 `VersionListChanged` ⇒ 列表是空的 ⇒
+    // 视图模型里那一行不存在，于是 `selected` 被过滤成 `None`（防「切分类后还留着一个点不动的安装」）。
+    assert_eq!(app.download_draft.selected.as_deref(), Some("1.21.8"));
+    assert_eq!(
+        app.view.download.selected, None,
+        "选中的行不在列表里时，视图模型不该拿着它"
+    );
+    assert_eq!(app.view.download.category, pages::Category::Release);
+    assert_eq!(
+        app.view.download.rows.len(),
+        0,
+        "recorder 不回事件 ⇒ 列表不该冒出来"
+    );
+    // 分类是本地过滤条件：**任何一次视图重建都不许把它打回 `All`**（复审 P2-1 的回归点）。
+    // 抓得住：`refresh_view` 忘记把分类带回去（那一行删掉这条就红）。
+    // 抓不住：真 host 是否按分类拉清单（那是 presenter 的 `spawn_list`，已报 finding）。
+    app.refresh_view();
+    assert_eq!(
+        app.view.download.category,
+        pages::Category::Release,
+        "重建视图模型之后分类必须还在"
+    );
+}
+
+/// **取消之后面板要回到「未安装态」且能立刻再装**（M105 的验收项，CI 可跑的那一半）。
+///
+/// 现场（用户原话）：「取消下载按钮点了没反应」。真根因是取消生效了又被旧任务的事件盖回去
+/// （presenter 侧的代次守门在 `host/cancel_tests.rs`）；这一条钉的是**页面这一侧**：
+/// 收到 `InstallProgress(None)` 之后，面板必须回到安装选项区、确认键可用、选中的版本还在
+/// ——不需要用户重新点一遍版本。
+///
+/// 抓得住：取消后仍画着进度面板 / 选项区丢了选中 / 确认键还是禁用。
+/// 抓不住：真网络下的取消延迟（那条是 `#[ignore]` 的真网络用例）。
+#[test]
+fn cancelling_gives_the_panel_back_to_the_install_options() {
+    let log: Rc<RefCell<Vec<AppCommand>>> = Rc::new(RefCell::new(Vec::new()));
+    let families = crate::theme::Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+    let mut app = App::with_presenter(
+        crate::cli::Options::default(),
+        families,
+        SchemeFlavor::Light,
+        Box::new(Recorder(Rc::clone(&log))),
+        SettingsBridge::memory_only(),
+    );
+    app.state.apply(AppEvent::Core(
+        unlucky_presenter::dto::CoreEvent::VersionListChanged(vec![
+            unlucky_presenter::dto::VersionSummary {
+                id: "1.21.9".to_string(),
+                kind: unlucky_presenter::dto::VersionKind::Release,
+                released: "2026-09-20".to_string(),
+                installed: false,
+            },
+        ]),
+    ));
+    app.refresh_view();
+
+    // 选中 → 面板给出选项区
+    let _ = app.on_page(pages::Message::SelectVersion("1.21.9".to_string()));
+    let options = app
+        .view
+        .download
+        .options
+        .as_ref()
+        .expect("选中版本之后要出现安装选项区");
+    assert!(options.can_confirm, "原版 + 列表里的版本 = 可以装");
+    assert_eq!(options.version, "1.21.9");
+
+    // 开装：host 回一条「下载中」→ 面板换成进度
+    app.state.apply(AppEvent::Core(
+        unlucky_presenter::dto::CoreEvent::InstallProgress(Some(
+            unlucky_presenter::dto::InstallProgressView {
+                version: "1.21.9".to_string(),
+                stage: unlucky_presenter::dto::InstallStage::Downloading,
+                files_done: 9,
+                files_total: 512,
+                ..unlucky_presenter::dto::InstallProgressView::new()
+            },
+        )),
+    ));
+    app.refresh_view();
+    assert!(app.view.download.install.is_some(), "装的时候面板讲进度");
+    assert!(app.view.download.options.is_none(), "进度与选项互斥");
+
+    // 取消：host 回 `InstallProgress(None)`（`CancelInstall` 的既有语义）
+    let _ = app.on_page(pages::Message::CancelInstall);
+    app.state.apply(AppEvent::Core(
+        unlucky_presenter::dto::CoreEvent::InstallProgress(None),
+    ));
+    app.refresh_view();
+    assert!(app.view.download.install.is_none(), "取消后面板必须收回");
+    let options = app
+        .view
+        .download
+        .options
+        .as_ref()
+        .expect("取消后要回到安装选项区（未安装态），而不是只剩一句提示");
+    assert_eq!(
+        options.version, "1.21.9",
+        "选中项要还在，用户不必重新点一遍"
+    );
+    assert!(options.can_confirm, "取消后要能立刻再装一次");
+}
+
+/// **取消提示只说一次，且说的是页面语言**（复审 P2-2）。
+///
+/// 修前：`presenter` 在取消时直接推一条**写死的中文** Toast，而下载页此刻渲染英文 ⇒
+/// 选项区英文、取消弹窗中文，同屏两语。现在 host 只发信号（`CoreEvent::InstallCancelled`），
+/// 文案由页面层按 `Key::DownloadCancelled` 现求，语言跟页面走。
+///
+/// 抓得住：谁把中文写回 presenter（类型上已经做不到——它没有 i18n 依赖）、
+/// 或者 app 层每次 `refresh_view` 都重复弹（下面的 `items().len() == 1`）。
+/// 抓不住：`Lang` 本身接得对不对（M106 起语言来自 `App::lang()`，本测试**显式钉**成英文，
+/// 否则这条断言会跟着跑测试那台机器的 locale 变——那是假绿）。
+#[test]
+fn cancelling_announces_once_in_the_page_language() {
+    let log: Rc<RefCell<Vec<AppCommand>>> = Rc::new(RefCell::new(Vec::new()));
+    let families = crate::theme::Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+    let mut app = App::with_presenter(
+        crate::cli::Options::default(),
+        families,
+        SchemeFlavor::Light,
+        Box::new(Recorder(Rc::clone(&log))),
+        SettingsBridge::memory_only(),
+    );
+    assert!(app.state.toasts.is_empty(), "出厂态不该有 Toast");
+
+    // M106：语言显式钉成英文。不钉的话「页面语言」就是跑测试那台机器的 locale（英文 CI 绿、
+    // 中文机器红）——那种测试证明不了任何事。钉住之后期望值仍从目录取，守的是同一条原意：
+    // **提示语来自 i18n 目录，不是 presenter 写死的中文**。
+    app.set_language(unlucky_i18n::LangChoice::Fixed(unlucky_i18n::Lang::En));
+
+    app.state.apply(AppEvent::Core(
+        unlucky_presenter::dto::CoreEvent::InstallCancelled,
+    ));
+    app.refresh_view();
+    let items = app.state.toasts.items();
+    assert_eq!(items.len(), 1, "取消要提示一条（且只一条）");
+    let text = items[0].text.clone();
+    assert_eq!(
+        text,
+        pages::cancelled_toast(unlucky_i18n::Lang::En),
+        "提示语必须来自 i18n 目录（不是 presenter 写死的中文）"
+    );
+    assert!(
+        !text.contains('取') && !text.contains('消'),
+        "页面此刻是英文，取消提示不该混中文：{text}"
+    );
+
+    // 再重建一次视图：不该重复弹（信号是计数，不是「每拍都算一次」）
+    app.refresh_view();
+    assert_eq!(app.state.toasts.items().len(), 1, "同一次取消只提示一次");
+    let _ = app.state.toasts.len();
+}

crates/app-iced/src/app/update/instances.rs

@@ -0,0 +1,304 @@
+//! 实例页「启动参数」区的消息落点（M157）。
+//!
+//! 三件事：
+//! 1. **编辑**只改页面状态（`App::launch_form`）并置脏——不 dispatch，不打网络；
+//! 2. **保存**派一条 [`AppCommand::SetInstanceLaunchArgs`]（整份五项补丁），回程由
+//!    `InstancesChanged` 快照刷新页面（不做乐观回显，与 M90 的启动/停止同一条纪律）；
+//! 3. **恢复跟随全局**只清表单（仍需用户点保存）——「点一下就写盘」会让误触直接生效。
+//!
+//! **清脏的唯一时机是「回程快照等于表单」**：`LaunchForm::sync` 在「同实例 + 脏」时只在
+//! `matches(&view)` 成立时才清脏并重播种，其余情况原样保留草稿。保存本身**不清脏**——落盘成败
+//! 要等回程事件，写盘失败时旧快照回来必须留住用户敲的值（M157 r3 复审 P2-2）。
+
+use iced::Task;
+use unlucky_presenter::dialogs::{DialogKind, DialogSource};
+use unlucky_presenter::dto::{AppCommand, LaunchArgsPatch, ModsCommand, SavesCommand};
+use unlucky_presenter::state::SavesOp;
+
+use crate::pages::InstanceMessage;
+
+use super::super::message::Message;
+use super::super::state::App;
+
+impl App {
+    /// 实例页详情列的一条消息（启动参数表单 + MODS 区）。
+    pub(super) fn on_instance_message(&mut self, message: InstanceMessage) -> Task<Message> {
+        let Some(instance) = self.selected_instance_id() else {
+            return Task::none();
+        };
+
+        match message {
+            // M224：启停一个 mod。**不做乐观翻面**——先把那个开关标成「请求在飞」（置灰），
+            // 真状态等 host 回一份新快照（与 Save 分支同一条纪律）。
+            //
+            // 这一支在 `bound_to` 守卫**之前**：MODS 区的启停只依赖「当前选中实例」，
+            // 与启动参数表单播没播种无关（守卫是给表单草稿用的，见下一条）。
+            InstanceMessage::SetModEnabled { file, enabled } => {
+                self.state.mods.mark_pending(&file);
+                self.dispatch(AppCommand::Mods(Box::new(ModsCommand::SetEnabled {
+                    id: instance,
+                    file,
+                    enabled,
+                })));
+                return Task::none();
+            }
+            // M235：重新列一次存档（失败后的「重试」也走这条）。
+            //
+            // 与 `SetModEnabled` 一样放在 `bound_to` 守卫**之前**：存档区只认"当前选中实例"，
+            // 与启动参数表单播没播种无关（那条守卫是给表单草稿用的）。
+            InstanceMessage::ReloadSaves => {
+                self.dispatch(AppCommand::Saves(Box::new(SavesCommand::List(instance))));
+                return Task::none();
+            }
+            // M235：打开存档文件夹——拉起哪个目录由 host 定（`saves/` → `screenshots/` → 运行目录），
+            // 真正的 opener 在 `core::platform::opener`（平台差异不散到 app 这一层）。
+            InstanceMessage::OpenSavesFolder => {
+                self.dispatch(AppCommand::Saves(Box::new(SavesCommand::OpenFolder {
+                    id: instance,
+                })));
+                return Task::none();
+            }
+            // M247：行内重命名的三个动作。**输入过程不 dispatch**（只改 presenter 的草稿），
+            // 提交才发命令——与启动参数表单「编辑只改状态，保存才派命令」同一条纪律。
+            InstanceMessage::StartRenameWorld { dir } => {
+                self.state.saves.start_rename(&dir);
+                self.view_dirty = true;
+                self.refresh_view();
+                return Task::none();
+            }
+            InstanceMessage::RenameWorldChanged(text) => {
+                self.state.saves.edit_rename(text);
+                self.view_dirty = true;
+                self.refresh_view();
+                return Task::none();
+            }
+            InstanceMessage::CommitRenameWorld => {
+                let Some(draft) = self.state.saves.take_rename() else {
+                    return Task::none();
+                };
+                // 空名字 / 没改 → 直接收起，不打后台：这两个不是"操作失败"，是"用户改主意了"。
+                if draft.text.is_empty() || draft.text == draft.dir {
+                    self.view_dirty = true;
+                    self.refresh_view();
+                    return Task::none();
+                }
+                self.state.saves.mark_pending(SavesOp::Rename {
+                    dir: draft.dir.clone(),
+                });
+                self.dispatch(AppCommand::Saves(Box::new(SavesCommand::RenameWorld {
+                    id: instance,
+                    dir: draft.dir,
+                    to: draft.text,
+                })));
+                return Task::none();
+            }
+            InstanceMessage::CancelRenameWorld => {
+                self.state.saves.cancel_rename();
+                self.view_dirty = true;
+                self.refresh_view();
+                return Task::none();
+            }
+            // M247：删除**先弹确认框**。确认目标是"哪个世界"必须记在状态里——
+            // 主按钮落点在 `app/update/dialog.rs`，那里只有 `App`，没有这个页面。
+            InstanceMessage::RequestDeleteWorld { dir } => {
+                let (title, body, primary, secondary) =
+                    crate::pages::saves_delete_prompt(self.lang().catalog(), &dir);
+                // **先压框、拿到它的 id，再登记目标**：目标绑在那个框上（复审 r1 P1-1）——
+                // 反过来（先登记再压框）会让"这一拍还没有框"的中间态挂在状态里，别的框的主按钮
+                // 就有机会把它兑掉。
+                let dialog = self.state.dialogs.push(
+                    DialogSource::UserAction,
+                    title,
+                    body,
+                    DialogKind::Confirm { primary, secondary },
+                );
+                self.state.saves.ask_delete(dialog, &dir);
+                self.view_dirty = true;
+                return Task::none();
+            }
+            // M247：备份——落点由 host 定（`<data>/exports/saves/`），回执里带完整路径。
+            InstanceMessage::BackupWorld { dir } => {
+                self.state
+                    .saves
+                    .mark_pending(SavesOp::Backup { dir: dir.clone() });
+                self.dispatch(AppCommand::Saves(Box::new(SavesCommand::BackupWorld {
+                    id: instance,
+                    dir,
+                    dest: None,
+                })));
+                return Task::none();
+            }
+            // 表单还没对着这个实例（首帧还没播种）：不接编辑，免得改到别的实例上。
+            _ if !self.launch_form.bound_to(&instance) => return Task::none(),
+            InstanceMessage::Jvm(text) => {
+                self.launch_form.jvm = text;
+                self.launch_form.dirty = true;
+            }
+            InstanceMessage::Game(text) => {
+                self.launch_form.game = text;
+                self.launch_form.dirty = true;
+            }
+            InstanceMessage::Memory(text) => {
+                self.launch_form.memory = text;
+                self.launch_form.dirty = true;
+            }
+            InstanceMessage::Java(text) => {
+                self.launch_form.java = text;
+                self.launch_form.dirty = true;
+            }
+            InstanceMessage::Backend(id) => {
+                self.launch_form.backend = id;
+                self.launch_form.dirty = true;
+            }
+            InstanceMessage::Reset => {
+                self.launch_form.reset();
+            }
+            InstanceMessage::Save => {
+                // **不在这里清脏**：`dispatch` 只是把命令送出去，落盘成败要等回程事件。
+                // 失败时（内存 `4g` / 写盘失败）pump 会带**旧快照**重建视图，脏标记若已清掉，
+                // `LaunchForm::sync` 就会用旧值覆盖用户刚敲的草稿（M157 r3 复审 P2-2）。
+                // 清脏的唯一时机是「回程快照已经等于表单」——见 `LaunchForm::sync`。
+                let patch: LaunchArgsPatch = self.launch_form.patch();
+                self.dispatch(AppCommand::set_launch_args(&instance, patch));
+            }
+        }
+        // 纯本地编辑：不重建视图模型（页面直接从表单画），只要一帧重绘即可——iced 在
+        // 消息处理完之后本来就会画一帧，所以这里什么都不排。
+        Task::none()
+    }
+
+    /// 详情页当前选中的实例 id（不在详情页时为 `None`）。
+    ///
+    /// `pub(in crate::app)`（M247）：删除确认框的主按钮在 `app/update/dialog.rs`，也要问同一个问题。
+    pub(in crate::app) fn selected_instance_id(&self) -> Option<String> {
+        match self.state.route() {
+            unlucky_presenter::router::Route::Detail(id) => Some(id.clone()),
+            _ => None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_presenter::dto::LaunchArgsView;
+    use unlucky_presenter::settings_bridge::SettingsBridge;
+
+    use crate::app::state::App;
+    use crate::cli::Options;
+    use crate::pages::{InstanceMessage, LaunchForm};
+
+    use crate::theme::Families;
+
+    const FAMILIES: Families = Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+
+    fn app_with_form() -> App {
+        let mut app = App::with_presenter(
+            Options::default(),
+            FAMILIES,
+            SchemeFlavor::Light,
+            Box::new(unlucky_presenter::mock::MockBackend::new()),
+            SettingsBridge::memory_only(),
+        );
+        // 进详情页 + 直接放一份「已播种」的表单：本测试只验消息落点，
+        // 不验播种（那在 `LaunchForm::sync` 的单测里）。
+        app.state.navigate(unlucky_presenter::router::Route::Detail(
+            INSTANCE.to_string(),
+        ));
+        app.launch_form = LaunchForm::from_view(
+            Some(INSTANCE),
+            &LaunchArgsView {
+                instance_id: INSTANCE.to_string(),
+                ..LaunchArgsView::default()
+            },
+        );
+        app
+    }
+
+    /// 测试用的实例 id（mock 后端的实例快照里有它）。
+    const INSTANCE: &str = "survival";
+
+    /// 编辑 → 脏；恢复 → 五项清空仍需保存；保存前不发命令。
+    #[test]
+    fn editing_marks_dirty_and_reset_waits_for_save() {
+        let mut app = app_with_form();
+        let _ = app.on_instance_message(InstanceMessage::Memory("6144".to_string()));
+        assert_eq!(app.launch_form.memory, "6144");
+        assert!(app.launch_form.dirty);
+
+        let _ = app.on_instance_message(InstanceMessage::Backend("vulkan".to_string()));
+        assert_eq!(app.launch_form.backend, "vulkan");
+
+        let _ = app.on_instance_message(InstanceMessage::Reset);
+        assert_eq!(app.launch_form.memory, "");
+        assert_eq!(app.launch_form.backend, "default");
+        assert!(app.launch_form.dirty, "恢复之后还得点保存才落盘");
+    }
+
+    /// **MODS 区的启停在表单守卫之前**（M224）：表单还没播种也照样能启停。
+    ///
+    /// 抓得住：把 `SetModEnabled` 放回 `bound_to` 守卫之后——那时首帧的详情页点了开关
+    /// 什么都不会发生（用户看到开关纹丝不动，也没有任何提示）。
+    #[test]
+    fn mod_toggles_work_before_the_launch_form_is_bound() {
+        let mut app = app_with_form();
+        // 页面已经打开（真路径上 `refresh_view` 的 `sync_mods` 会做这一步），但表单还没播种。
+        app.state.bind_mods(Some(INSTANCE));
+        app.launch_form = LaunchForm::from_view(
+            Some("other"),
+            &LaunchArgsView {
+                instance_id: "other".to_string(),
+                ..LaunchArgsView::default()
+            },
+        );
+
+        let _ = app.on_instance_message(InstanceMessage::SetModEnabled {
+            file: "sodium.jar".to_string(),
+            enabled: false,
+        });
+
+        assert!(
+            app.state.mods.is_pending("sodium.jar"),
+            "启停被表单守卫挡住了（开关点了没反应）"
+        );
+    }
+
+    /// 表单没绑定到当前实例时不接编辑（否则草稿会写到别的实例上）。
+    #[test]
+    fn edits_are_ignored_when_the_form_is_bound_elsewhere() {
+        let mut app = app_with_form();
+        app.launch_form = LaunchForm::from_view(
+            Some("other"),
+            &LaunchArgsView {
+                instance_id: "other".to_string(),
+                ..LaunchArgsView::default()
+            },
+        );
+        let _ = app.on_instance_message(InstanceMessage::Memory("9999".to_string()));
+        assert_eq!(app.launch_form.memory, "");
+        assert!(!app.launch_form.dirty);
+    }
+
+    /// **保存只派发、不清脏**（M157 r3 复审 P2-2）：落盘成败要等回程事件，
+    /// 派发前清掉脏标记会让失败后的重播覆盖用户草稿。
+    ///
+    /// 抓得住：Save 分支里又写回 `dirty = false`（那条路径在失败时丢草稿）。
+    /// 抓不住：回程事件的真实时序——清脏判据在 `LaunchForm::sync` 的
+    /// `confirmed_save_clears_dirty_and_reseeds` / `failed_save_keeps_the_draft` 里。
+    #[test]
+    fn save_dispatch_keeps_the_dirty_flag() {
+        let mut app = app_with_form();
+        let _ = app.on_instance_message(InstanceMessage::Memory("4g".to_string()));
+        assert!(app.launch_form.dirty);
+        let _ = app.on_instance_message(InstanceMessage::Save);
+        assert!(
+            app.launch_form.dirty,
+            "派发后仍要保留脏标记，等回程快照确认"
+        );
+        assert_eq!(app.launch_form.memory, "4g", "派发不改表单内容");
+    }
+}